---
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.