<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/4.x/2026-10-11-1-archive-freeze-verifies-reducer-outcome-not-byte-identity/">
  <id>https://docs.spec-kitty.ai/adr/4.x/2026-10-11-1-archive-freeze-verifies-reducer-outcome-not-byte-identity/</id>
  <title>ADR: the archive-freeze gate verifies reducer OUTCOME reproduction, not byte-identity</title>
  <updated>2026-10-11T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/4.x/2026-10-11-1-archive-freeze-verifies-reducer-outcome-not-byte-identity/"/>
  <summary>Archived status.json is a frozen derived snapshot; a correct reducer improvement may re-assign a WP terminal-transition id without it counting as archive drift.</summary>
  <content type="html">&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-10-11&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Stijn Dejongh (owner), during the maintainer landing of PR &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/pull/6039&quot;&gt;#6039&lt;/a&gt; (adopt &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; 10.4.2).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; &lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/issues/5967&quot;&gt;#5967&lt;/a&gt; and its upstream reducer fixes &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events#77&lt;/code&gt; (10.4.1) / &lt;code dir=&quot;auto&quot;&gt;#78&lt;/code&gt; (10.4.2). Amends the historical-preservation gate &lt;code dir=&quot;auto&quot;&gt;tests/architectural/test_archive_root_byte_identical.py&lt;/code&gt; (M1 NFR-002, WP12 FR-007–011).&lt;/p&gt;
&lt;h2 id=&quot;context&quot;&gt;Context&lt;/h2&gt;
&lt;p&gt;Each archived mission dossier under &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; carries a &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; — a &lt;strong&gt;derived&lt;/strong&gt; projection of that mission’s immutable &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; through the canonical status-diary reducer (&lt;code dir=&quot;auto&quot;&gt;specify_cli.status.reducer.materialize_snapshot&lt;/code&gt;). The historical-preservation gate &lt;code dir=&quot;auto&quot;&gt;test_no_preexisting_archived_file_was_modified&lt;/code&gt; pins three per-pinned-snapshot (the WP11 reviewed-recovery &lt;code dir=&quot;auto&quot;&gt;SNAPSHOTS&lt;/code&gt;) guarantees:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Frozen bytes&lt;/strong&gt; — the committed &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; blob equals an independently reviewed git blob (&lt;code dir=&quot;auto&quot;&gt;_exact_candidate&lt;/code&gt; against the &lt;code dir=&quot;auto&quot;&gt;RECOVERED&lt;/code&gt; commit) and the recovery receipt’s &lt;code dir=&quot;auto&quot;&gt;after_sha256&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Byte-identical canonical replay&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;materialize_snapshot(dir)&lt;/code&gt; re-emitted &lt;em&gt;byte-for-byte&lt;/em&gt; equal to the committed file (&lt;code dir=&quot;auto&quot;&gt;assert canonical == candidate&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Terminal-state preservation&lt;/strong&gt; — the per-WP &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;verdict&lt;/code&gt; (and historically &lt;code dir=&quot;auto&quot;&gt;last_event_id&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;last_transition_at&lt;/code&gt;) match the reviewed history.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Guarantee (2) silently assumed the canonical reducer’s output for a given event log is &lt;strong&gt;stable for all time&lt;/strong&gt;. It is not: the reducer is allowed to be &lt;em&gt;fixed&lt;/em&gt;. Adopting &lt;code dir=&quot;auto&quot;&gt;spec-kitty-events&lt;/code&gt; 10.4.2 (the &lt;code dir=&quot;auto&quot;&gt;#78&lt;/code&gt; reconstruction-seed fix, built on 10.4.1’s generalized from-lane continuity, &lt;code dir=&quot;auto&quot;&gt;#5967&lt;/code&gt;) changes the materialized output of &lt;code dir=&quot;auto&quot;&gt;reject-cyclic-lane-graphs-01M0QCK4&lt;/code&gt; — but &lt;strong&gt;only&lt;/strong&gt; the identity of a work package’s terminal transition. WP01/WP02/WP03 each carry a duplicate terminal &lt;code dir=&quot;auto&quot;&gt;approved -&gt; done&lt;/code&gt; merge re-emit; the corrected reducer keeps the &lt;em&gt;first&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;done&lt;/code&gt; event and drops the causally-stale second one, so each WP’s recorded &lt;code dir=&quot;auto&quot;&gt;last_event_id&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;last_transition_at&lt;/code&gt; moves to the earlier event. Every outcome — &lt;code dir=&quot;auto&quot;&gt;lane&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;review_result.verdict&lt;/code&gt;, the summary, actors, subtasks, top-level identity — is unchanged. Guarantee (2) failed the gate on a reducer improvement that changed no outcome.&lt;/p&gt;
&lt;p&gt;Re-materialising the frozen file to the new bytes was rejected: it would mutate an archived artifact and break guarantee (1)‘s git-provenance pins (the reviewed &lt;code dir=&quot;auto&quot;&gt;RECOVERED&lt;/code&gt; blob is immutable).&lt;/p&gt;
&lt;h2 id=&quot;decision&quot;&gt;Decision&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Archived &lt;code dir=&quot;auto&quot;&gt;status.json&lt;/code&gt; bytes are frozen at the canonical reducer generation that authored them.&lt;/strong&gt; The archive-freeze gate verifies that the &lt;em&gt;current&lt;/em&gt; reducer &lt;strong&gt;reproduces the archived OUTCOME&lt;/strong&gt;, not that it reproduces byte-identical output forever.&lt;/p&gt;
&lt;p&gt;Concretely, guarantee (2) is relaxed from raw byte-equality to an outcome-equality (&lt;code dir=&quot;auto&quot;&gt;_assert_replay_preserves_outcome&lt;/code&gt;) that tolerates exactly the reducer-generation-sensitive per-WP terminal-transition identity fields — &lt;code dir=&quot;auto&quot;&gt;last_event_id&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;last_transition_at&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_EVENT_POINTER_KEYS&lt;/code&gt;). Every other field (lane, review_result, summary, actor, agent, subtasks, force_count, and the top-level identity) must still match the frozen snapshot exactly, so the gate stays non-vacuous: a changed lane or verdict, a different summary, an added/dropped WP, or a shifted actor/subtask still fails. As a further non-vacuity guard, any &lt;strong&gt;moved&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;last_event_id&lt;/code&gt; must name a real event in that mission’s &lt;code dir=&quot;auto&quot;&gt;status.events.jsonl&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;_logged_event_ids&lt;/code&gt;) — a fabricated or missing-log pointer fails — so the tolerated drift can only re-point within the mission’s own recorded events. Guarantees (1) frozen bytes and (3) terminal-state preservation are &lt;strong&gt;unchanged&lt;/strong&gt; — the committed file is never rewritten, and the reviewed git-provenance pins stand.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;A correct reducer evolution that preserves every mission’s outcome lands without rewriting any archived dossier or re-pinning the reviewed-recovery blobs.&lt;/li&gt;
&lt;li&gt;The gate no longer protects “the reducer’s output for these snapshots is byte-stable forever” — that guarantee was over-strict (it forbade fixing the reducer). It still protects “the reducer reproduces every archived mission’s outcome,” which is the property that actually matters for historical fidelity.&lt;/li&gt;
&lt;li&gt;A reducer change that would alter a frozen mission’s &lt;strong&gt;outcome&lt;/strong&gt; (not just terminal-transition identity) still fails the gate — correctly, because that &lt;em&gt;is&lt;/em&gt; archive drift and demands a conscious decision.&lt;/li&gt;
&lt;li&gt;The tolerance set is deliberately minimal (two fields). Widening it later requires amending this ADR, keeping the gate honest.&lt;/li&gt;
&lt;li&gt;The tolerance is &lt;strong&gt;gate-wide across every work package of every pinned snapshot&lt;/strong&gt;, not scoped to the three WPs that drifted under 10.4.2. The residual coverage boundary this draws: a future live-replay regression that re-points a currently-non-drifting WP’s terminal transition to a &lt;em&gt;wrong but same-lane, same-verdict&lt;/em&gt; event id would not be caught by this live-replay check. It is still bounded on four sides — the frozen committed bytes (which record the original terminal event id) stay pinned byte-exact by &lt;code dir=&quot;auto&quot;&gt;_exact_candidate&lt;/code&gt; + the receipt &lt;code dir=&quot;auto&quot;&gt;after_sha256&lt;/code&gt;; any wrong event that shifts lane or verdict is still caught by the preserved terminal-state pins; a moved pointer must still name a real logged event (&lt;code dir=&quot;auto&quot;&gt;_logged_event_ids&lt;/code&gt;), so it cannot be fabricated; and the frozen-vs-&lt;code dir=&quot;auto&quot;&gt;SOURCE&lt;/code&gt; historical loop still pins both tolerated fields between the two frozen blobs. A per-(mission, WP) tolerance would close the remaining same-lane/same-verdict residual but is brittle; the outcome guarantee plus the byte pin cover the property that matters for historical fidelity. A focused self-mutation test (&lt;code dir=&quot;auto&quot;&gt;test_replay_outcome_check_tolerates_only_logged_pointer_drift&lt;/code&gt;) pins the rejection floor — lane/verdict/membership drift and a ghost pointer both raise — so the relaxation cannot drift vacuous.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;alternatives-considered&quot;&gt;Alternatives considered&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Re-materialise the frozen snapshots to the new reducer output.&lt;/strong&gt; Rejected: mutates archived artifacts and breaks the reviewed &lt;code dir=&quot;auto&quot;&gt;RECOVERED&lt;/code&gt;-blob / receipt provenance pins (those commits are immutable), trading a strong historical guarantee for churn on every future reducer fix.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Add the path to &lt;code dir=&quot;auto&quot;&gt;_OPERATOR_SANCTIONED_CORRECTIONS&lt;/code&gt;.&lt;/strong&gt; Rejected: that allowlist is consulted only by the ordinary-history violations loop, &lt;em&gt;after&lt;/em&gt; &lt;code dir=&quot;auto&quot;&gt;_check_snapshot&lt;/code&gt;’s hard pins run, so it cannot lift the reducer-replay assertion for a pinned snapshot; and it is for sanctioned &lt;em&gt;byte corrections&lt;/em&gt;, not for a derived-snapshot reducer evolution.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
