core/docs/analysis/replay-moment-backend-scoping-2026-06-12.md

# Replay Moment Backend — Scoping (Wave R3, `GET /replay/{turn_id}`)

Date: 2026-06-12
Plan: `docs/workbench/wave-R-mastery-revamp.md` § Wave R3 (first item).
Status: implemented — with one design correction recorded below.

## Amendment (implementation PR, same day)

The "sealed genesis-prefix replay" decision below was **wrong** and was
corrected before any code shipped.  This doc was written before reading the
chat handler; implementation began by reading it, which surfaced the
decisive fact: `workbench/api.py::_run_chat_turn` constructs a **fresh
`ChatRuntime()` per turn**.  The journaled turns were never one continuous
session, so feeding prompts `1..N` through a single runtime would
accumulate session state the original turns never had — prefix replay
would manufacture spurious divergence by construction.

What shipped instead: **sealed fresh-runtime single-turn replay**
(`comparison_basis: "sealed_fresh_runtime_single_turn"`), which matches
the original per-turn execution shape and is O(1) instead of O(N).  The
honesty consequence is unchanged in kind but renamed: the unknown is not
prefix completeness but whether the original turn's fresh runtime loaded
an engine-state checkpoint present at the time (`origin_state:
"unrecorded"` — the journal does not record it).  `refused:
prefix_too_long` is obsolete (no prefix); the contract section in
`docs/workbench/api-contract-v1.md` § Replay is authoritative for the
shipped shape.  The five proof obligations below survive, re-aimed at the
single-turn model, and all execute in `tests/test_workbench_replay.py`.

The original analysis is preserved unedited below as the decision record.

## What exists today

- `workbench/api.py:257` — `GET /replay/...` returns 501 (`deferred beyond
  W-026`).
- `workbench/schemas.py` — `ReplayComparison` / `ReplayDivergence` already
  exist (W-026 vintage, keyed by `artifact_id`).
- `docs/workbench/api-contract-v1.md` § Replay — standing honesty rule:
  the API must not claim `"equivalent": true` unless a real replay/compare
  path ran; digest-to-itself comparison is not replay evidence.
- `workbench/journal.py` — entries carry the full `prompt` plus the full
  recorded envelope (`surface`, `articulation_surface`, `walk_surface`,
  `trace_hash`, `verdicts`, `epistemic_state`, …), monotonic `turn_id`.

## The constraint that shapes the design

A turn's output depends on the lived engine state at that turn.  The engine
keeps ONE rolling checkpoint, written **after** turns (`chat/runtime.py::
checkpoint_engine_state`) — there is no per-turn checkpoint history, so the
pre-turn state of an arbitrary historical turn is **not recoverable** from
checkpoints.

And the journal is **not a provably complete input history**: it is appended
only by the workbench chat handler (`workbench/api.py:390`).  Turns via
`core chat` CLI, `idle_tick` learning, teaching ratifications, and
checkpoint-restored prior state all advance the engine without journal
entries.

## Decided v1 semantics: sealed genesis-prefix replay

`GET /replay/{turn_id}` re-runs journal entries `1..N` (prompts only, in
order) in a **sealed transient runtime** — fresh genesis state, current
default identity/pack configuration, `persist_session_state=False`, no
journal appends, no checkpoint writes — and compares the resulting envelope
at turn N against the recorded entry, leaf by leaf.

The claim this demonstrates is exactly the architectural one: **same input
sequence → bit-identical envelope** (determinism), NOT "the live engine's
full history is captured here."  The response must carry that envelope
explicitly:

- `comparison_basis: "genesis_prefix_replay"` — names the method;
- `history_complete: "unknown"` — the journal cannot prove the original
  turns ran from genesis with no interleaved non-journaled inputs (no
  per-entry config/lineage fields exist today);
- divergences therefore mean *either* nondeterminism *or* unjournaled
  state influence — the UI honesty card states both, and the frontend
  never renders a divergent replay as a determinism failure verdict.

Rejected alternatives (record for the ADR/PR):

- **Checkpoint-restore replay** — unimplementable for historical turns
  (no per-turn checkpoints); sound only for "the next turn", which is not
  yet a journaled subject.
- **Replay against current live state** — compares different states;
  dishonest as "replay".
- **Claiming completeness** — would violate the contract's honesty rule;
  completeness becomes provable only via an additive journal field
  (genesis marker + config digest), which is a sanctioned follow-up,
  same pattern as the `versor_condition` journal note in the plan.

## Response shape (supersedes the W-026 `artifact_id` placeholder)

`ReplayComparison` is re-keyed to `turn_id` (the W-026 placeholder was
never wired; `artifact_id` had no consumer).  Fields: `turn_id`,
`comparison_basis`, `history_complete`, `original_hash` / `replay_hash`
(trace hashes), `equivalent` (true only on zero critical divergences),
`divergences: list[ReplayDivergence]`, `replayed_prefix_length`.

Leaf comparison over the recorded entry vs the re-run envelope, with
severity classes:

- **critical** — `trace_hash`, `surface`, `articulation_surface`,
  `walk_surface`, `verdicts`, `epistemic_state`, `grounding_source`,
  `refusal_emitted`, `hedge_injected`, `proposal_candidates`;
- **informational** — wall-clock fields (`timestamp`, `turn_cost_ms`) and
  `journal_digest` (recomputed over different timestamps by construction);
  never affect `equivalent`.

Refusal vocabulary (typed, fail-closed — never a 500, never a fabricated
comparison): `refused:turn_not_found`, `refused:prefix_too_long` (bound
N at a documented cap; replay cost is O(N) turns), `refused:runtime_error`
(replay runtime failed to construct — reason echoed, no comparison
claimed).

## Trust boundary

Journaled prompts are user-controlled text re-entering the runtime: the
replay runtime is constructed sealed (transient, no persistence, no
teaching ratification, no pack mutation — proposal-only paths stay
proposal-only), and the endpoint is GET/read-only.  No new write surface.

## Proof obligations (MEANINGFULLY-FAILS tests, per CLAUDE.md schema rule)

1. Mutating one recorded prompt in a fixture journal flips `equivalent`
   to false with a critical divergence at the right leaf path.
2. Mutating one recorded envelope leaf (e.g. `surface`) does the same —
   the comparison reads the RECORDED entry, not a re-derivation.
3. A digest-to-itself shortcut (no re-execution) cannot pass: test asserts
   the replay runtime actually ran N turns (e.g. via prefix-length
   evidence on the response).
4. Replay leaves no trace: journal byte-identical, no checkpoint written,
   `engine_state/` untouched (asserted on disk).
5. Wall-clock fields differing does NOT break equivalence.

## Same-PR documentation obligations

- Amend `docs/workbench/api-contract-v1.md` § Replay (turn-keyed shape,
  honesty fields, refusal vocabulary).
- The frontend Replay Moment (separate R3 PR) renders `comparison_basis`
  and `history_complete` on the honesty card; hash-to-hash equality is the
  hero only when `equivalent` is true.