93 lines
3.2 KiB
Markdown
93 lines
3.2 KiB
Markdown
---
|
||
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. |