docs: document checkpoint artifact integrity during resume

[cursor]

🧠 Noēsis Pull Request

Overview

Documentation-only update clarifying the checkpoint/resume integrity contract so developers can diagnose CheckpointConsistencyError reliably during pause/resume workflows.

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 lifecycle hardening in checkpoint/resume validation added strict artifact-manifest consistency checks anchored to checkpoint evidence. Existing docs mentioned anchor/state checks but did not fully explain artifact drift behavior (especially manifest appearance/disappearance while paused), creating troubleshooting ambiguity.

Technical Details

Docs added/updated

• Updated docs/reference/python-api.mdx
  • Expanded continuation contract to include artifact_manifest_hash validation.
  • Documented prefix-aware event-log checking at checkpoint event_offset.
  • Clarified pre-manifest vs manifest-anchored checkpoint behavior.
  • Expanded CheckpointConsistencyError description with full anchor fields.
• Updated docs/guides/integrate-adapters.mdx
  • Added troubleshooting row for CheckpointConsistencyError with artifact manifest hash.
  • Added runbook constraints for paused runs (do not mutate manifest.json; lifecycle appends are expected and safe).

Codepaths covered

• noesis/usecases/run_lifecycle.py
  • _assert_checkpoint_consistency(...)
  • _artifact_digest(...)
  • _events_prefix_artifact(...)
• tests/runtime/test_run_lifecycle.py
  • Resume integrity scenarios for unchanged pre-manifest checkpoints, manifest add/remove drift, and consistency errors.

Key knowledge gaps addressed

• What exactly is validated on resume beyond event/state anchor checks.
• Why appending lifecycle events after checkpoint is not itself a resume failure.
• Why manifest creation/deletion/rewrites during paused state can fail resume.
• Practical operator guidance for recovering from artifact-manifest mismatch.

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)

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 in this PR. The docs now explicitly communicate existing integrity guardrails and likely failure modes, reducing unsafe manual artifact mutations during paused runs.

Educational / Research Value

• Replication kit (configs, seeds, sweeps, data access notes): N/A (documentation-only)

Screenshots / Logs

N/A.

Related Issues / References

• noesis/usecases/run_lifecycle.py checkpoint/resume integrity checks
• tests/runtime/test_run_lifecycle.py lifecycle consistency regression coverage