kestrel.markets/docs/adr/0040-clock-honest-wakes-deliberation-consumes-tape-time.md

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

# Clock-honest wakes: deliberation consumes tape time

**Status:** accepted (2026-07-15); **implemented 2026-07-15** (epic kestrel-w7la:
PRs #111 / #136 / #127 / #151 — engine core, clocked escalation, latency-blind
rankability leg, clocked goldens; kestrel-653j closed, no Grade formula change).
Determinism clause live (RUNTIME §0 gains "+ same recorded deliberation costs");
Bus schema at v6. Engine-semantics change. Companions on the platform side:
the platform's benchmark-governance canon (which gates the first governed season on
this ADR) and its model program. Extends ADR-0012 (the simulator:
wake-driven agent-in-loop) and reinterprets ADR-0019 (the kernel leads every
frame) for a moving clock.

## Implemented

The as-built contract is `docs/design/clock-honest-wakes.md` (the source of truth
for what shipped); the season-audience summary is `docs/clock-honest-wakes-season.md`.
What landed on main, per the design doc's section map:

- **Bus v6 — the deliberation record.** `BUS_SCHEMA = 6`, a within-stream
  `WAKE`/`deliberation` `DeliberationEvent` (`wake_seq`, `measured_ms`, `buffer_ms`;
  `ts` IS the derived return time), reader validation + cross-record identity in
  `src/bus/read.ts` (design §1).
- **The clocked turn.** `runSimulateSession`'s `clockedTurn` measures wall time and
  lands the returning control at `returnTs = vantageTs + measuredMs + bufferMs`;
  `foldDeliberationWindow` + the `latency-fold` `WakeSource` coalesce in-window wakes
  into one catch-up delivery; OPEN is clocked with its own checkpoint (design §2).
- **Escalation clocked** via the existing supersede path — the armed plan governs the
  gap, repair retries accrue cumulatively (design §3).
- **Config + eligibility fail-closed.** `AgentConfig.clockHonest` / `latencyBufferMs`
  (no default — refused at open when absent); `clockHonestIneligibility` cross-checks
  the data-floor rung fail-closed (design §4).
- **The `clock_honest` attestation leg** — `MetaPayload.clock_honest`, appended LAST in
  `deriveRankability` (`certified → post_cutoff → date_blind → season_frozen →
  clock_honest`); a latency-blind session is valid but never governed-leaderboard-rankable
  (design §5).
- **No Grade formula change** — latency is priced by physics through the strict-cross
  floor at `returnTs` fills; kestrel-653j closed (design §6).
- **Determinism** — recorded costs are inside the byte hash; replay/certification
  re-project from recorded costs and never re-time (design §7).

Guards live in `tests/simulate.clocked.test.ts`,
`tests/simulate.clocked-escalation.test.ts`, `tests/simulate.clocked-goldens.test.ts`,
and `tests/blotter.rankable.test.ts`.

## Context

The README's founding claim is a latency claim: every trading API assumes the
decision-maker is fast enough to sit in the loop, and an LLM is not. Plan exists
so judgment can be authored in advance and fired in milliseconds. Yet the sim
that grades this world is latency-blind: wakes are delivered, the agent
deliberates for free, and the market waits. A slow frontier model pays nothing
for being slow — so the benchmark built on this sim structurally cannot show the
one thing the language was designed around, and "no single frontier model can
fill the watcher seat" remains a marketing claim instead of an empirical result.

v1 was latency-blind by circumstance, not belief: the corpus lacked uniform
sub-minute resolution, and clocking deliberation adds real complexity. That
constraint has lapsed for enough of the catalog: 1s-level bars exist for some
series and realtime event streams for others.

Two-tier architecture context (ADR-0032): the Watcher is the fast reflex seat;
the Strategist is the slow deliberate seat the Watcher escalates to for plan
updates. Latency matters at BOTH edges — the Watcher's wake-to-control time, and
the escalation round-trip (a plan update arriving in 20s versus 5min lands in a
different market).

## Decision

**Deliberation consumes tape time.** While a seat thinks, the sim clock advances
and the market keeps moving; the control that comes back lands on the tape as of
its return time, not its wake time. Alpha internalizes latency — there is no
separate latency score, no judge-designed weighting, nothing to game. The screen
is measured, not designed (ADR-0030 spirit), and now so is the clock.

Mechanics (charter for implementation):

- **Measured, buffered time.** A wake's deliberation cost = measured wall time
  of the seat's response plus a configured latency buffer (network/infra
  allowance). Determinism is preserved by *recording* the deliberation cost on
  the Bus as part of the session record: replays and certification re-project
  from the recorded costs, byte-identical (the determinism invariant binds the
  recorded run, and recomputation replays recorded time rather than re-timing).
- **Both edges clocked.** Watcher wake→control, and the Watcher→Strategist
  escalation round-trip (plan revision arrives when it arrives; the armed plan
  governs until then — restraint semantics unchanged, fail-closed as always).
- **Data floor.** Clock-honest sessions require sub-minute ground truth: 1s
  bars and/or event streams for the session's series. Sessions on coarser data
  remain valid but are labeled latency-blind; a latency-blind session can never
  ground a latency claim (FORBIDDEN-CLAIMS enforceable).
- **No lapse-to-null default.** A slow response is not dropped (that would
  reward the null policy the phase-0 recon flagged as degenerate); it executes
  late and the tape prices the delay.

## Consequences

- The first governed benchmark season waits for this ADR (per the platform's
  benchmark-governance canon and its season program) — accepted slip, deliberately.
- Dataset acquisition inherits a resolution floor across all tiers, effective
  immediately (the platform's tape-lake program).
- The recorded-time approach means the determinism invariant ("same bus + same
  armed documents ⇒ byte-identical stream") gains a clause: same recorded
  deliberation costs. Golden fixtures gain a clocked variant.
- Thinking-budget settings become measurable trade-offs: more thinking = later
  fills. Restraint (declining to act late) becomes visible in the Grade rather
  than free.