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

instrument / verified-clean

# Countdown / Days-Until Timer

The current ledger marks this instrument verified clean within the source-bound verification corpus.

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

## Inspectable records

[01**Overview**Purpose and lifecycle](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/>)[02**Mechanism**Method and assumptions](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/mechanism/>)[03**Implementation**Binding and validation](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/implementation/>)[04**Qualification**Evidence and errata](<https://guthlabs.ai/docs/instruments/countdown-days-until-timer/qualification/>)

## Ledger state

The current ledger marks this instrument verified clean within the source-bound verification corpus.

**Area**: Everyday & Life

**Tranche**: tranche-5

**Evidence ID**: t5-018

**Ledger rows**: 1

No ledger note is attached.

## Review findings

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.

### Formula and scope findings

- 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.

### Unit assumptions

- 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.

## Boundary hardening

**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.

## Errata and corrections

No applied erratum is attached to this unique-name record.

## Inspectable example

4 review vectors are recorded. One source-bound sample is shown below.

````
{
  "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."
}
````

## Related workflows

No source-defined multi-instrument workflow membership is recorded.

## Sources and evidence

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

- `VERIFIED_LEDGER.json · VERIFIED_CLEAN`

- `evidence-tranche5/tranche5-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`