docs: clarify run checkpoint/resume integrity contracts

[cursor]

🧠 Noēsis Pull Request

Overview

Refresh lifecycle documentation for checkpoint/resume behavior so operators can reliably troubleshoot paused runs and fail-closed resume errors.

Type of Change

• 🧩 Core framework (runtime, faculties, orchestrator, schema)
• 📈 Cognitive model or paper implementation (ReAct, Reflexion, ToT, Meta-CoT, etc.)
• 🧠 Meta-cognition or learning feedback logic
• ⚙️ Infrastructure / CI / build system
• 📚 Documentation or research notes
• 🧪 Experiment / benchmark / curriculum update
• 🧰 Developer experience (CLI, codemod, viewer, tooling)
• 🗃️ Dataset / artifact update (checkpoints, corpora, prompt packs)
• Other (please describe):

Motivation & Context

Recent runtime changes enforce stronger checkpoint consistency checks (event anchor, state hash, artifact digest, resume anchor constraints). Existing docs mentioned these only at a high level, leaving operators without concrete payload/runbook guidance when resume fails.

Technical Details

Updated docs in-place (no new redundant pages):

• docs/reference/events.mdx
  • Added explicit payload contracts and examples for run.interrupt, run.checkpoint, and run.resume runtime events.
  • Clarified caused_by anchor requirement for resume events.
• docs/reference/python-api.mdx
  • Expanded run lifecycle section with concrete pre-resume consistency checks.
  • Added precise CheckpointConsistencyError breakdown, including artifact-manifest drift and invalid explicit resume anchors.
• docs/guides/human-in-the-loop.mdx
  • Added a practical “Resume integrity checks” runbook with constraints and operator guidance.

Validation

Required

• All tests pass locally (uv run pytest) or equivalent targeted suite
• Schema validation and export diff clean

Situational

• Cognitive loop tested end-to-end (Observe → Learn)
• Docs build successfully (pnpm run build in docs/)
• CLI smoke tests pass (python scripts/pre_release.py --check-all)
• Benchmarks / eval sweeps reproduced
• Artifact integrity checked (hashes, licensing, storage footprint)

Notes:

• Verified behavior against source and lifecycle tests (tests/runtime/test_run_lifecycle.py) while authoring docs.
• Ran python scripts/validate_exports.py --strict; current repo baseline reports missing docs/app/reference exports unrelated to this docs change.

ADR-003 Schema Governance Checklist

• $schema_version bumped for every artifact whose stable fields changed
• docs/schema/** regenerated (no diff after python scripts/gen_schema.py)
• KPI updates include version bumps plus math/clamp/rationale updates in internal_docs/schema/kpi*.yaml
• Relevant entry added to MIGRATIONS.schema.md or MIGRATIONS.kpi.md
• python scripts/schema_guard.py --strict --json passes locally
• Docs under docs/app/reference/* updated when new fields/KPIs surface to users

Observability & Safety

No runtime behavior changed. This PR reduces operational risk by documenting fail-closed resume conditions and expected runtime evidence.

Educational / Research Value

• Replication kit (configs, seeds, sweeps, data access notes): Not applicable (documentation-only).

Screenshots / Logs

Not applicable.

Related Issues / References

• Related runtime behavior and tests in:
  • noesis/usecases/run_lifecycle.py
  • noesis/core.py
  • tests/runtime/test_run_lifecycle.py