ADR-0002: Store step ordinals at finalize (not derive them at read time)
- Status: Accepted
- Date: 2026-07-06
- Deciders: Halfhand engineering
- Requirements context: step semantics (step assignment: 1-based ordinals,
terminal_outputexcluded, atool_resultshares itstool_call's step). ADR-0001 states the project's general "derived at read time" stance for view-layer values; this ADR records a deliberate exception forevents.step.
Context
The step semantics require every step-bearing event to carry a 1-based ordinal, with
tool_result sharing its correlated tool_call's ordinal. Two designs were
available:
- A. Derive at read time.
hh replay/hh inspect/hh listcompute step numbers on the fly from(ts_ms, id, correlates)whenever a session is read.events.stepwould not exist as a stored column. - B. Store at finalize. Run the step-assignment pass once, when a session's writer
has flushed and closed, and persist the result in
events.step(already present in the schema). Self-heal onStore::openfor the sessions that never got a chance to finalize cleanly.
Decision
We choose B: store the ordinals, computed by a pure pass
(hh_core::step::assign_steps) over EventRows and written back in one
transaction via Store::assign_steps.
Justification
- Session-row counts need
stepas a column.hh list/hh inspectreport a step count and a files-changed count per session without replaying the whole event stream.COUNT(DISTINCT step) WHERE step IS NOT NULLis a single indexed aggregate; deriving it at read time would mean re-running the step-assignment pass (a full table scan + correlation resolution) just to print a number inhh list. - The correlation pass is O(n) but not free, and it is reused.
hh replay,hh inspect, andhh listall want step numbers; recomputing the same pass in three call sites — or a shared read-time helper re-run on every invocation — costs more than computing it once and writing it down. - Idempotent by construction. The pass is pure
(
assign_steps_pass(&mut [EventRow])) and deterministic given(ts_ms, id, correlates, kind); re-running it (e.g. on self-heal) always converges to the same assignment, so "store vs. derive" is not a correctness trade — it is purely a caching decision with no staleness risk as long as every code path that appends events also re-runs the pass before the session is considered readable. - Crash / cross-process races are bounded, not eliminated, by design.
hh runruns the pass at finalize (writer flushed + joined, no intra-process contention). A crashedhh runleavesstep IS NULLon unfinalized sessions;Store::openself-heals by re-running the pass for any session with a NULL-stepped semantic event before the caller can read further (heal_steps, called aftermark_stale_interrupted). This mirrors the already-accepted crash-safety "reconcile on next open" pattern.
Consequences
events.stepis authoritative once set; nothing derives it independently.Store::list_sessions/session_step_countcomputeCOUNT(DISTINCT step) WHERE step IS NOT NULL, which is correct under the step-sharing rule (atool_call+tool_resultpair is one step, one distinct value) — the priorCOUNT(*) WHERE kind != 'terminal_output'query over-counted shared steps and has been replaced.- Attached
hh mcp-proxylate events are a known v0.1 limitation. The proxy runsassign_stepsbest-effort on its own attached session at exit (so MCP events usually get ordinals immediately), but if the parenthh runfinalizes concurrently and the proxy's write loses the race, the affected events keepstep = NULLuntil the nexthhinvocation's self-heal. No data is lost — only the ordinal is deferred. This is a cross-process race the child proxy process cannot join against; documented indocs/mcp-proxy.mdand the plan's deviations list rather than solved with cross-process locking (out of proportion for a display-ordinal race). Store::opendoes one extraSELECT DISTINCT session_idprobe on every invocation (heal_steps); this is a cheap, usually-empty scan and is the price of the self-heal guarantee.
Requirements deviation flagged
ADR-0001 (and the general engineering-standards framing) leans toward "derive
at read time" for view-layer values not backed by a requirement to persist
them. events.step is schema-backed (the documented schema already has the column)
and the step semantics do not mandate either storage strategy, so this is a deviation from
the project's general read-time-derivation instinct, not from an explicit
requirement — recorded here per CLAUDE.md's "flag deviations explicitly."