Source: https://guthlabs.ai/docs/instruments/countdown-days-until-timer/mechanism/

instrument mechanism / verified-clean

# Countdown / Days-Until Timer mechanism

The inspectable method record for Countdown / Days-Until Timer, kept separate from implementation and qualification.

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

## Model scope

The core subtraction is correct for two timezone-aware instants, but the catalog entry needs an explicit timezone/DST policy, output breakdown definition, precision/rounding policy, and past-target behavior before it can pass. The honest label is currently 'none'; it should disclose dependence on the device clock and timezone interpretation. The optional EventKit hook is not needed for the formula, but calendar-event timezone semantics must match the timer semantics if implemented.

- The subtraction formula delta = target_datetime − now is mathematically standard, but it is incomplete unless both datetime values are interpreted as timezone-aware instants on the same timeline.

- The specification does not define how delta is converted into the advertised remaining-time breakdown of days and hours.

- The specification does not define whether a target in the past produces a negative countdown, clamps to zero, or displays an expired state.

- The specification does not define daylight-saving-time behavior, which can make a calendar-day difference differ from a fixed 24-hour duration.

## Units and conventions

- Test calculations use elapsed SI seconds, with 1 day = 86400 seconds, 1 hour = 3600 seconds, and 1 minute = 60 seconds.

- Datetime inputs are interpreted as ISO 8601 timestamps with explicit timezone offsets and converted to UTC before subtraction.

- Breakdowns below use signed total-duration decomposition: delta_seconds = days*86400 + hours*3600 + minutes*60 + seconds.

- The device clock is assumed correct and monotonic during each calculation; leap seconds are ignored.

- A production specification must explicitly choose whether 'days' means fixed 24-hour periods or calendar-day boundaries in a named timezone.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "target_datetime": "2025-03-10T12:45:00+00:00",
    "now": "2025-03-08T10:15:00+00:00"
  },
  "expected_outputs": {
    "delta_seconds": 181800,
    "remaining_days": 2,
    "remaining_hours": 2,
    "remaining_minutes": 30,
    "remaining_seconds": 0
  },
  "working": "delta = target − now = 2025-03-10 12:45 − 2025-03-08 10:15. From March 8 10:15 to March 10 10:15 = 2 days = 2 × 86400 = 172800 seconds. From 10:15 to 12:45 = 2 hours 30 minutes = (2 × 3600) + (30 × 60) = 7200 + 1800 = 9000 seconds. Total delta = 172800 + 9000 = 181800 seconds = 2 days, 2 hours, 30 minutes, 0 seconds."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

The timezone-less target produces different valid countdowns under plausible conventions: 24 hours when interpreted as UTC versus 28 hours when interpreted as America/New_York. The instrument should require or explicitly document timezone handling.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/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-tranche5/tranche5-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`