Source: https://guthlabs.ai/docs/instruments/astronomical-twilight-duration/implementation/

instrument implementation / implementation-contract

# Astronomical Twilight Duration implementation

A source-bound implementation contract for Astronomical Twilight Duration; deployment and executable qualification remain separate.

Status: **VERIFIED_WITH_ERRATA**Lifecycle: **implementation-contract**

## Binding contract

This record describes what an executable surface must bind and validate. It does not claim that a public calculator, package, or production route is deployed.

**Record owner**: Guth Instruments

**Lifecycle**: verified-with-binding-errata

**Evidence ID**: t6-090

**Effect**: Computation or source lookup only

## Input and validation requirements

- Missing timezone or explicit UTC output can shift every displayed time by hours.

- Longitude sign convention and degree-versus-radian handling must be validated; a 180° longitude is an especially important wraparound case.

- The hour-angle formula divides by cos(latitude)cos(declination); it becomes singular or numerically unstable near the poles and must use an explicit no-event/continuous-event policy.

- Each threshold requires checking whether the computed acos argument lies in [-1,1]. Outside that interval, the corresponding twilight event does not occur rather than producing NaN or a fabricated time.

- Near the poles and near threshold boundaries, floating-point rounding can incorrectly switch between an event and no event.

- Atmospheric refraction, elevation above sea level, solar radius, and terrain horizon can change event times by more than the claimed one-minute accuracy.

- Date handling must include leap years, UTC date boundaries, and equation-of-time/date conversion. A date without timezone and calendar specification is not sufficient.

- The honest label should say approximately one minute only after the exact solar-position algorithm and environmental assumptions are documented; otherwise the accuracy claim is unsupported.

## Required corrections

````
[
  {
    "vector": "3,4",
    "field": "civil/astronomical hour_angle_deg",
    "wrong": "98.503 / 115.921",
    "correct": "98.5009 / 115.9136",
    "cause": "micro acos slips at lat 45; nautical is exact"
  }
]
````

## Inspectable interface fixture

The sample below is evidence for interface and validation tests, not a production implementation.

````
{
  "inputs": {
    "lat_deg": 0,
    "lon_deg": 0,
    "date": "idealized_equinox",
    "solar_declination_deg": 0,
    "timezone": "UTC",
    "model": "geometric hour-angle check"
  },
  "expected_outputs": {
    "civil": {
      "begin": "05:36:00 UTC",
      "end": "18:24:00 UTC",
      "hour_angle_deg": 96
    },
    "nautical": {
      "begin": "05:12:00 UTC",
      "end": "18:48:00 UTC",
      "hour_angle_deg": 102
    },
    "astronomical": {
      "begin": "04:48:00 UTC",
      "end": "19:12:00 UTC",
      "hour_angle_deg": 108
    }
  },
  "working": "For latitude 0° and declination 0°, sin(phi)sin(delta)=0 and cos(phi)cos(delta)=1, so cos(H)=cos(Z). Therefore H=Z. Civil: Z=90°+6°=96°; 96°/15=6.4 h=6 h 24 min, so 12:00-06:24=05:36 and 12:00+06:24=18:24. Nautical: Z=102°; 102/15=6.8 h=6 h 48 min, so 05:12 and 18:48. Astronomical: Z=108°; 108/15=7.2 h=7 h 12 min, so 04:48 and 19:12."
}
````

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/astronomical-twilight-duration/>)[02**Mechanism**](<https://guthlabs.ai/docs/instruments/astronomical-twilight-duration/mechanism/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/astronomical-twilight-duration/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-tranche6/tranche6-results.json`

- `tranche errata record`