# 2026-11-01 — kido-time deliberation (session 41, builder crew)

## The gap, stated first

Session 29 gave the tree a timer that can arm a compare
and report a count. Nothing since has turned that count
into time. Every future consumer that needs a duration —
a timeout, a scheduler quantum, a log timestamp, a
barrier bound measured in something other than loop
iterations (smp's AFFINITY_POLLS is a loop count because
no clock existed when it was written) — currently has
only raw ticks, and ticks are not a unit: 62,500,000
ticks is one second on QEMU virt and something else
wherever CNTFRQ differs. The missing piece is a leaf
that converts ticks to nanoseconds, monotonically, with
overflow refused rather than wrapped. This session
drafts kido-time: that leaf. Zero existing files
touched (the session-24/25/26/33 fence pattern); the
module-map row and the ledger entry are the only other
edits. No wiring into the scheduler, no tick policy —
consumers are Gate items, as with every leaf since
session 33.

## Circle

- **P1 timekeeper realist** — the kernel needs time in
  a unit every consumer shares. Nanoseconds is the
  unit: seconds are too coarse for a 62.5 MHz counter,
  ticks are platform-relative. One conversion, owned
  once, instead of every consumer dividing by a hz it
  read itself.
- **P2 math auditor** — the conversion must be exact
  in pure uint64 C11, no `__int128`, no float. The
  freestanding build cannot assume a 128-bit integer
  type, and a float conversion would quantize the
  very durations the clock exists to measure. The
  split — seconds plus remainder — keeps every
  intermediate inside a bound the test can state.
- **P3 monotonicity auditor** — a clock that goes
  backwards breaks every ordering built on it
  (elapsed durations, timeout comparisons). The
  architecture guarantees one counter never
  decreases; the leaf guarantees the clock never
  does, even if its source is re-bound or a future
  virtual timer misbehaves. A backwards step is
  clamped and counted, never hidden and never
  refused.
- **P4 fence keeper** — leaf, injected source, no
  timer.c edits. The concrete reason, not just taste:
  timer's hosted setters live behind
  KIDO_TIMER_SELFTEST, which also defines timer's
  `main` — linking timer.c into this leaf's test
  would collide mains. The ops table is the honest
  seam, the ipi precedent (transport injected, one-line
  Gate binding, zero MMIO in the leaf). The binding
  is named in the header: `{ kido_timer_now,
  kido_timer_hz }`, whose signatures match the
  source slots exactly.
- **P5 honesty auditor** — truncation toward zero,
  stated, with error under one tick; overflow refused
  loud at both guards, never wrapped; no new header
  codes (NO_TIMER for a missing time base is the
  timer's own code, reused, not invented).
- **P6 test keeper** — the hosted proof must pin the
  pure converter at both overflow guards (the
  second guard needs a constructed case, not a
  hand-waved one), the clamp, the regression count,
  the elapsed refusal, and the microsecond
  truncation — the only things a host can pin about
  a clock whose real counter lives in silicon.

## Challenges, answered

- **C1 — direct timer coupling or injected source?**
  Injected source (`kido_time_source_t`: a now slot
  and a hz slot). Direct coupling would drag timer.c
  into every test build and collide mains (P4); it
  would also hard-wire the one counter the tree may
  one day virtualize (timer's own futures name a
  virtual-timer driver). The leaf calls the source
  and propagates its status unchanged — a source
  that is not initialized reports its own EARLY_ENV,
  never a time invention.
- **C2 — what does hz == 0 mean, and where?**
  Two meanings, kept apart. In the pure converter,
  hz == 0 is an argument error: EARLY_ENV, out
  untouched (division by zero has no honest
  answer). In init, a source reporting hz == 0 is a
  missing time base: NO_TIMER, the timer's own code
  for exactly this condition (CNTFRQ == 0 at timer
  init). Same value, different layer, different code
  — conflating them would make a caller bug look
  like missing hardware.
- **C3 — backwards counter: refuse, trust, or clamp?**
  Clamp and count. Refusing a clock read breaks
  every caller at the moment it most needs time
  (the refusal dissent, D1). Trusting the counter
  bets the leaf's monotonicity law on one
  architecture's guarantee surviving every future
  source binding. Clamping preserves ordering and
  the regression counter preserves honesty: the
  caller gets a usable time and the audit trail
  shows the source stepped back.
- **C4 — init-once or re-init allowed?**
  Init-once (the topo precedent). Re-init would
  need an epoch policy: a new hz mid-boot moves
  every timestamp's meaning, and resetting last_ns
  would let the clock jump backwards through the
  clamp's own floor. Refusing the second init keeps
  the epoch single. A genuine re-init (for a reboot
  path) makes its own case to the Gate.
- **C5 — elapsed() with a future `since`?**
  Refuse EARLY_ENV. Because now_ns is monotonic
  (C3), any `since` from this clock's own past
  satisfies since <= now; a future value is either
  a caller bug or a foreign timestamp, and the
  unsigned wrap complement would be a lie dressed
  as a duration. The read still counts in stats:
  the read succeeded, the refusal is the caller's.
- **C6 — truncation or rounding in the converter?**
  Truncation toward zero, stated. Rounding up
  would report time not yet elapsed — the timer
  arm_us precedent refuses a sub-tick request
  rather than rounding it into existence. Error
  is under one tick period, pinned by test
  (hz = 3, ticks = 1 -> 333,333,333 ns, the third
  of a second truncated, not rounded).
- **C7 — what do stats carry?**
  Reads and regressions only. last_ns is internal:
  exposing it would invite callers to reimplement
  the clamp (a second monotonicity path that could
  drift). Reads counts every successful now_ns,
  including the reads now_us and elapsed make
  internally — one counter, one meaning.
- **C8 — the 584-year wrap.** Nanoseconds in uint64
  wrap after ~584.9 years. The converter refuses
  any ticks whose seconds exceed
  UINT64_MAX / 1e9 (guard one) and any sum that
  would cross the top (guard two), so no wrapped
  timestamp is ever returned. Elapsed arithmetic
  is unsigned subtraction, correct modulo 2^64 for
  any interval shorter than the wrap period. A boot
  that outlives 584 years is not a case the leaf
  hides from: conversion refuses before it.

## Convergence

One leaf, six functions (init / now_ns / now_us /
elapsed_ns / ticks_to_ns / stats), one injected
source table, no new header codes (EARLY_ENV for
every refusal, NO_TIMER for a missing time base),
no coupling beyond the timer's two public signatures
as function-pointer slots, zero existing files
touched. The equation is the module: ns =
(ticks / hz) * 1e9 + (ticks % hz) * 1e9 / hz, both
guards stated as bounds, every intermediate inside
uint64 by construction: rem < hz <= 2^32 - 1, so
rem * 1e9 < 4.3e18 < 2^64. The clock answers always,
never goes backwards, and counts its own compromises.

## Preserved dissent

- **D1 — refuse the read on a backwards counter
  (overruled, C3).** Loudest, and wrong for a clock:
  a refused now_ns at timeout-check time leaves the
  caller with no time at all. The clamp answers and
  the counter testifies.
- **D2 — allow re-init with a new source
  (overruled, C4).** Convenient for tests that want
  two frequencies in one process — the self-test
  sequences one hz for exactly this reason — and
  wrong for the epoch: two epochs in one boot is
  two clocks wearing one name.
- **D3 — `__int128` for the conversion
  (overruled, C2/P2).** Shorter, and an assumption
  the freestanding build does not own. The uint64
  split is exact, and its bounds are provable in
  the header's own arithmetic.
- **D4 — round to nearest in the converter
  (overruled, C6).** Prettier numbers, overstated
  time. A clock that reports 1,000,000,000 ns when
  999,999,999 have elapsed has lied by a
  nanosecond; truncation never claims more than
  measured.

## Honest limits

WRITTEN, NOT ASSEMBLED, NEVER EXECUTED — toolchain
absent a 24th time (no aarch64-linux-gnu-gcc, no
qemu-system-aarch64; `which` finds neither). The leaf
has no asm of its own — its ARM64 content is the
timer's already-carried register reads — so what
awaits a tooled VM is the Gate binding
(`{ kido_timer_now, kido_timer_hz }`) plus a QEMU
virt run showing now_ns advancing at the real
62.5 MHz CNTFRQ, which also needs the Gate timer-init
wiring before the proof means anything on silicon.
The hosted proof pins the conversion math at both
overflow guards, the monotonic clamp, the regression
count, the elapsed refusal, and the microsecond
truncation — not delivery across silicon. The
non-hosted -fsyntax-only build correctly REFUSES on
the x86 host (the arch-discipline error, working as
designed, the mpidr/cache/topo precedent).
