ADR-0016: Obligation clocks are userland; the kernel owes durable timers only

Status

Accepted

Date

2026-07-03

Context

The telecom analysis and the BSNL CNOC tender are saturated with money-bearing deadlines: SLA clocks that start on commissioning, pause on validated hindrances, and bind both parties (the buyer accepts validation deadlines on itself); breach forecasting (“30-day milestone risk alerts”); business-calendar arithmetic (“5 working days”, IST); escalation matrices reacting to breaches. The architecture-implications review initially proposed “Clocks as kernel objects.”

But the LLD locks the relevant cut: the kernel owns durable execution (P10), triggers, timers, compensation-over-the-log, and the approval outcome; userland owns process meaning — definitions, SLAs, escalation, assignment. An SLA clock is process meaning. Making it a kernel primitive would violate that principle for no enforcement gain — nothing about clocks needs write-path enforcement the way sealed-only ledgers (ADR-0023) did.

Decision

No new kernel primitive. Obligation clocks are a canonical userland pattern — specified once, shipped as a standard library of the works-execution Reality Package, so every product builds clocks the same way:

Clock state is entity data. An obligation clock is an entity (or trait set) with plain attributes: obligated party, basis (contract/definition reference), started/paused/elapsed, target, calendar reference.
Adjustments are Acts. Start, pause, resume, extend, and re-baseline are governed Acts with actor + justification. Where the adjustment is money-bearing (hindrance validation adjusting an LD computation), the act type is declared sealable per ADR-0023 — the clock’s history becomes chain-verifiable evidence.
Deadlines are Schedule timers. Each armed obligation registers a durable timer (schedule(TimerSpec)); adjustments cancel/re-arm. Breach and pre-breach warnings are Events feeding Subscribe — escalation matrices are userland subscriptions over those events.
Business calendars are definition data (working days, holidays, timezones) owned by the package; deadline arithmetic resolves through them in userland before timers are armed on absolute instants.
Forecasting is a Serving-plane projection (burn-down over open obligations), not a timer concern.
Symmetry is a modeling stance, not a mechanism: a clock’s obligated party may be any actor — field crew, contractor, approver, the platform operator. The pattern makes “clocks on the buyer” the same object as “clocks on the vendor.”

The kernel owes only what it already promises: durable, re-armable timers with delivery guarantees under P10, and Events broad enough to carry timer firings (both already canon).

Alternatives Considered

First-class kernel Clock object. Rejected: contradicts the locked LLD cut (userland owns SLAs/escalation); enlarges the kernel with semantics only some products need; no write-path enforcement requirement justifies it.
No ADR — leave it to each product. Rejected: symmetric, attributable, sealable clocks are tender-critical and interact with ADR-0023; without a canonical pattern every product invents divergent clock semantics and the “clocks bind both parties” stance gets lost.
Kernel-level business calendars. Rejected: calendars are jurisdiction/contract data — definition content, not mechanism.

Consequences

The works-execution package owes an obligation-clock library spec: state shape, the adjustment act taxonomy (with sealable flags), timer re-arm discipline, breach event contract, and the burn-down projection.
ADR-0023 interaction confirmed: money-bearing clock adjustments are sealable acts; a disputed LD computation replays from chain-verifiable clock history.
The kernel’s TimerSpec/TimerRef contract must support cancel and re-arm without loss under replay (verify against P10 adapter choices; already implied by durable-execution semantics).
Sensitive to: if a future profile needs kernel-enforced deadline semantics (e.g., an Act that must auto-expire), that is a Schedule-verb extension, not a reversal of this ADR.