Source: https://guthlabs.ai/docs/instruments/date-duration-calculator/mechanism/

instrument mechanism / verified-clean

# Date & Duration Calculator mechanism

The inspectable method record for Date & Duration Calculator, kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Model scope

The core concept is sound, but the instrument is not verifiable as specified. Before release, define endpoint inclusivity, calendar system, timezone/date-only policy, month and year decomposition semantics, negative-value behavior, invalid-date handling, and the exact output schema. The honest label should disclose these conventions rather than remain “none”.

- “Calendar-aware date arithmetic” is a valid approach, but it is not a sufficiently precise formula for verification. The specification must define whether duration endpoints are exclusive or inclusive.

- Month and year durations are ambiguous because months and years have variable lengths; the component-decomposition rule must be specified, such as anchored calendar addition followed by a remaining-day calculation.

- If “plain arithmetic” means subtracting serialized dates or assuming fixed-length months/years, that would be incorrect. Calendar APIs or equivalent Gregorian calendar logic are required.

- The specification does not define the calendar system, date format, timezone, or behavior for invalid dates.

- The output “duration breakdown” is unspecified: it must define whether it reports total days, weeks with a remainder, calendar months/days, or multiple simultaneous representations.

## Units and conventions

- Test vectors assume the proleptic Gregorian calendar.

- Inputs are date-only values in ISO 8601 format (YYYY-MM-DD), with no time-of-day or timezone component.

- Date duration uses end-midnight minus start-midnight: the start date is not counted as an elapsed day and the end date is not treated as an additional inclusive day.

- Calendar month/day breakdown uses anchored addition: add whole calendar years and months first, then count remaining calendar days.

- Total weeks are calculated as integer division of total days by 7, with the remainder reported separately; 7 days equals exactly 1 week.

- Day-of-week names use the Gregorian calendar.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "mode": "duration",
    "start_date": "2024-01-15",
    "end_date": "2024-03-20"
  },
  "expected_outputs": {
    "total_days": 65,
    "calendar_years": 0,
    "calendar_months": 2,
    "calendar_days": 5,
    "whole_weeks": 9,
    "remaining_days": 2,
    "end_day_of_week": "Wednesday"
  },
  "working": "Add 2 calendar months: 2024-01-15 -> 2024-03-15. Count remaining days: 2024-03-15 -> 2024-03-20 = 5 days. Total days: Jan 15 -> Mar 15 = 31 + 29 - 15 = 45 days; 45 + 5 = 50? Correction: Jan 15 -> Feb 15 = 31 days, Feb 15 -> Mar 15 = 29 days, and Mar 15 -> Mar 20 = 5 days, so calendar-component arithmetic gives 2 months and 5 days, while elapsed total days is 31 + 29 + 5 = 65 days. Weeks: 65 = (9 x 7) + 2, so 9 whole weeks and 2 remaining days. March 20, 2024 is Wednesday."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

The specification leaves invalid-date behavior and duration conventions unspecified. The invalid 2023-02-29 input must be rejected, and reversed dates must have an explicitly defined signed-versus-absolute and inclusive-versus-exclusive convention; otherwise different plausible implementations produce different results.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/date-duration-calculator/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/date-duration-calculator/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/date-duration-calculator/qualification/>)

## Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

- `VERIFIED_LEDGER.json`

- `evidence-tranche4/tranche4-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`