epic-12: after epic audit and init commit

2026-05-16 11:42:00 +04:00
commit c77277af0b
461 changed files with 28958 additions and 0 deletions
@@ -0,0 +1,93 @@
+---
+name: "Replay Model"
+description: "Replay modes, guarantees, and snapshot/cursor management"
+depth: 2
+links:
+  - "../index.md"
+  - "./overview.md"
+  - "./event-model.md"
+---
+
+# replay model
+
+**version:** 0.1-draft  
+**status:** architectural reference
+
+---
+
+## 1. purpose
+
+Replay is the ability to reconstruct the entire state of a session (projections, context builds, validation outcomes, transitions) purely from the immutable event log. It is a mandatory architectural guarantee, not an afterthought.
+
+---
+
+## 2. replay modes
+
+| mode | description |
+|------|-------------|
+| **full replay** | re‑apply all events, including inference (may re‑run models if available) |
+| **partial replay** | replay from a given cursor/sequence number |
+| **inference‑skipping replay** | skip model calls; use recorded `InferenceCompleted` events directly |
+| **projection‑only replay** | rebuild projections without touching orchestration |
+| **deterministic simulation** | test mode: compare current outcomes against a golden reference |
+
+---
+
+## 3. what can be replayed?
+
+* Session lifecycle (creation → completion)
+* Stage scheduling and transitions
+* Context pack building (subject to the same compression config, but compression events may be reused)
+* Validation decisions (recorded pass/reject)
+* Approval decisions (recorded as events)
+* Tool receipts (recorded; actual tool code not re‑executed unless in simulation mode)
+* All projections
+
+---
+
+## 4. what is NOT needed for replay?
+
+* The original model weights
+* Live tool access
+* Network connectivity
+* Provider credentials
+* The original Router UI
+
+Replay is self‑contained within the event store and configuration.
+
+---
+
+## 5. deterministic guarantees
+
+Replay is deterministic when:
+
+* the event store is unchanged
+* the configuration (workflows, policies, compression rules) is identical
+* the replay strategy matches (e.g., inference‑skipping uses recorded artifacts)
+
+Non‑determinism from model inference is thereby contained: the replay decision to trust a recorded artifact is itself a deterministic choice driven by the replay mode.
+
+---
+
+## 6. use cases
+
+* **debugging:** replay a failed session step‑by‑step, inspecting context packs and validation outcomes.
+* **audit:** prove which decision led to a tool execution and why.
+* **recovery:** if the harness crashes, resume from the last stable event cursor.
+* **dataset generation:** replay workflows with different inference providers to produce synthetic training data.
+* **testing:** deterministic simulation lets you verify orchestration logic without real models.
+
+---
+
+## 7. snapshot and cursor management
+
+To avoid replaying 100k+ events every time, the system supports periodic snapshots and replay cursors. A snapshot is a point‑in‑time projection bundle paired with the sequence number of the last applied event. Replay then only re‑processes events after that cursor.
+
+---
+
+## 8. implementation constraints
+
+* All projections must be buildable from events alone.
+* Context pack builds must be replays (using recorded compression events when possible).
+* No component may depend on in‑memory state that is not derived from events.
+* Events must remain serializable and versioned forever.