Skip to content

docs: document checkpoint artifact integrity during resume #224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
cursor wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: document checkpoint artifact integrity during resume #224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/guides/integrate-adapters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,7 @@ Identity and binding rules:
| `ApprovalDecisionBindingError` | decision is not bound to reviewed prepared intent | store `request_id`, `reviewed_fingerprint`, and `impact_hash` from the prepared artifact and verify before save |
| `tool.replayed` result with no dispatch | same idempotency key and fingerprint seen previously | treat as successful replay; do not retry with a new side effect |
| `summary.json` / `manifest.json` missing while run is paused | expected non-terminal lifecycle state | inspect latest `run.state_projection` links; resume and terminate run to produce final artifacts |
| `CheckpointConsistencyError` with `artifact manifest hash` on `resume`/`resume_run` | checkpoint-visible artifact set changed while paused (for example state/event tampering, or manifest added/removed/rewritten) | restore anchored artifacts to the checkpoint state or create a new checkpoint from current state; avoid mutating run artifacts outside Noēsis while paused |

### Runtime bridge guardrails (current)

Expand Down Expand Up @@ -199,6 +200,8 @@ evidence is complete:
`events` and `learn` (no `summary`/`manifest` yet)
- on paused runs, `run.state_projection.payload.status` should match the pause
status (for example `interrupted`)
- do not manually write or delete `manifest.json` while paused; resume validation treats manifest appearance/disappearance as checkpoint drift
- appending lifecycle events after checkpoint creation is expected and does not break resume validation on its own

After approval and `ns.resume_run(...)` completes terminally, the latest
`run.state_projection` should include terminal links (`summary`, `manifest`) and
Expand Down
6 changes: 5 additions & 1 deletion docs/reference/python-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,10 @@ Continuation contract:
- Same run ID.
- Append-only artifacts preserved.
- Resume continues post-plan by default (no replan) with anchor validation.
- Resume validates checkpoint integrity against the checkpoint anchor: `event_offset`/`last_event_id`, `state_hash`, and `artifact_manifest_hash`.
- Event-log checks are prefix-aware at `event_offset`, so lifecycle appends after checkpoint creation do not invalidate an otherwise unchanged checkpoint.
- For pre-manifest checkpoints, adding `manifest.json` before resume is treated as artifact-set drift and rejected.
- For manifest-anchored checkpoints, deleting or rewriting `manifest.json` before resume is rejected.

Adapter continuity:

Expand All @@ -219,7 +223,7 @@ Adapter continuity:
- `RunSealedError`: lifecycle writes and resume attempts are rejected once `final.json` seals the run.
- `CheckpointNotFoundError`: `resume`/`resume_run` reference a checkpoint that does not exist.
- `MissingCausalParentError`: checkpoint/interrupt cannot anchor to a causal parent event.
- `CheckpointConsistencyError`: checkpoint anchor (`event_offset`, `last_event_id`, `state_hash`) no longer matches artifacts.
- `CheckpointConsistencyError`: checkpoint anchor (`event_offset`, `last_event_id`, `state_hash`, `artifact_manifest_hash`) no longer matches the current run artifacts.
- `RunLifecycleTransitionError`: lifecycle mutation violates the run state-machine contract.
- `ResumeAdapterRequiredError`: `resume_run` requires explicit `using` for non-minimal checkpoints.
- `ResumeAdapterMismatchError`: `resume_run` adapter does not match checkpoint adapter contract.
Expand Down
Loading