causet forensics
causet forensics is a shipped, sandbox-only command group for forensic diagnostics and per-decision repair.
Concept guide (why / when / workflow): Forensics CLI.
Available only in the sandbox environment. Uses the active CLI context (causet context show): platform, application, and fork.
Usage
# Interactive menu (terminal)
causet forensics
# Subcommands (prompt for missing flags in a terminal)
causet forensics replay-check
causet forensics repair-plan
causet forensics repair-applyWith no subcommand, the menu offers:
- Replay-check (detect snapshot drift)
- Repair-plan (generate inverse patch)
- Repair-apply (apply a plan)
Subcommands
replay-check
Re-apply recorded ledger patches from a cursor and report fields that diverge from the stored snapshot.
causet forensics replay-check \
--stream order_stream \
--entity order-123 \
--from-cursor 5| Flag | Required* | Description |
|---|---|---|
--stream | yes | Stream ID (interactive stream picker if omitted) |
--entity | yes | Entity ID |
--from-cursor | yes | Replay from this timeline cursor (>= 1) |
--platform / --application / --fork | no | Override CLI context |
--json | no | Machine-readable output (disables prompts) |
*Required in non-interactive / --json / CI mode. In a terminal, missing values are prompted.
What divergence means: storage or replication drift — not that product rules would produce a different result if re-run today.
repair-plan
Generate a __SYSTEM_APPLY_PATCH__ intent that reverts fields changed by one timeline step, using previousValue captured on that step’s effects. Does not apply the plan.
causet forensics repair-plan --decision 22222222-2222-2222-2222-222222222222
causet forensics repair-plan --decision <uuid> --json > plan.json| Flag | Required* | Description |
|---|---|---|
--decision | yes | Timeline step ID (decision_routes.id) |
--platform / --application / --fork | no | Override CLI context |
--json | no | Machine-readable output |
Decision ID is the UUID of one timeline step — the same id shown by causet inspect timeline. It is not the intent type name, entity ID, or cursor number.
If generation fails, the strategy message usually means a non-invertible op (no previousValue). Use a product compensating action instead.
repair-apply
Submit a __SYSTEM_APPLY_PATCH__ repair intent. Provide either a decision ID (generate then apply) or a plan file from repair-plan.
causet forensics repair-apply --decision <uuid>
causet forensics repair-apply --plan-file plan.json| Flag | Required* | Description |
|---|---|---|
--decision | one of | Timeline step ID — generate plan then apply |
--plan-file | one of | Path to repair plan JSON from repair-plan |
--platform / --application / --fork | no | Override CLI context |
--json | no | Machine-readable output |
Use only one of --decision or --plan-file. Interactive mode asks which source to use, then confirms before apply when generating from a decision.
Applied intents are tagged repair_source=generate_repair_plan for provenance.
Interactive behavior
| Mode | Behavior |
|---|---|
| Terminal, missing flags | Prompts for stream / entity / cursor / decision / plan file |
--json or CI set | No prompts — flags required |
repair-apply from --decision in a terminal | Shows affected fields and asks to confirm before submit |
Examples
# Drift check
causet forensics replay-check \
--stream order_stream --entity order-123 --from-cursor 1
# Plan + apply one bad step
causet inspect timeline --entity order-123 --stream order_stream
causet forensics repair-plan --decision <bad-decision-uuid>
causet forensics repair-apply --decision <bad-decision-uuid>Related commands
- Forensics CLI — why to use it and the full workflow
causet inspect timeline— find decision IDscauset recovery replay/rewind— stream replay and entity rewind (sandbox)causet fork create/branch— isolate repair workcauset doctor— verify auth and context before running forensics