Replay
The ledger is the source of truth. Entity snapshots, projection tables, and query results are all derived — they can be rebuilt or inspected by re-processing history.
Mental model: Applications submit intents. Causet emits committed business events. Most replay operations re-apply recorded ledger patches via PatchReplayer — they do not re-run DSL rules. Full ruleset re-evaluation would require DecisionEvaluator and is not exposed as a general CLI operation today.
⚠️
Sandbox forensics. causet forensics … and causet recovery replay are sandbox-only. Prefer diagnosing on a fork before touching production.
See What runs today? and Support policy.
Behavior matrix
Aligned with causet/docs/RECOVERY_FORENSICS.md and PatchReplayer in the runtime:
| Operation | Runs DSL rules | Emits new events | External effects | Safe by default |
|---|---|---|---|---|
| Timeline inspection | No | No | No | Yes |
| Projection rebuild | No | No | No | Yes |
| Snapshot rehydration | No | No | No | Yes |
Forensic replay check (forensics replay-check) | No | No | No | Yes (read-only) |
Recovery stream replay (recovery replay) | No | No | No | Controlled (mutates sandbox fork state) |
Repair execution (forensics repair-*, recovery repair) | Via new intent | Yes | Potentially | Controlled |
Terminology
| Term | Shipped command / path | Meaning |
|---|---|---|
| Timeline inspection | causet inspect timeline, Entity Inspector scrubber | Read-only committed steps |
| Projection rebuild | Projection worker replay | Reprocesses events through projection handlers only |
| Snapshot rehydration | Entity rebuild / PatchReplayer | Re-applies recorded ledger patches to materialized entity state — no DSL rule re-evaluation |
| Forensic replay check | causet forensics replay-check | Read-only divergence check — compares patch-recomputed state to stored snapshot |
| Recovery stream replay | causet recovery replay --stream … | Mutating stream-level patch replay in sandbox (StreamReplayService) |
| Repair execution | causet forensics repair-plan / repair-apply, recovery repair | Corrective intents through the normal intent pipeline |
CLI examples
# Read-only inspection
causet inspect state --entity wallet-alice --stream wallet_stream --fork sandbox
causet inspect timeline --entity wallet-alice --stream wallet_stream --fork sandbox
# Sandbox forensics (Preview)
causet forensics replay-check --stream wallet_stream --entity wallet-alice --from-cursor 1
causet recovery replay --stream wallet_stream
causet forensics repair-plan --decision <decision-id>
causet forensics repair-apply --decision <decision-id>Choosing the right tool
| Symptom | Tool |
|---|---|
| ”What was state at cursor N?” | causet inspect state --cursor N or timeline scrubber |
| ”Snapshot doesn’t match ledger patches” | Snapshot rehydration or forensics replay-check |
| ”Read model rows are wrong” | Projection rebuild |
| ”Try a fix without touching prod” | Fork + sandbox forensics |
| ”Undo one bad timeline step” | forensics repair-plan → repair-apply on a fork |