docs: clarify run lifecycle checkpoint/resume contracts

[cursor]

🧠 Noēsis Pull Request

Overview

Improve lifecycle documentation so checkpoint/resume behavior is explicit and operationally actionable.

Docs updated:

• docs/reference/events.mdx
• docs/reference/python-api.mdx

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 lifecycle changes strengthened checkpoint consistency validation, but docs did not fully describe:

• runtime run.interrupt / run.checkpoint / run.resume payload contracts
• what checkpoint metadata contains and where it lives
• why CheckpointConsistencyError occurs and how to recover safely

Technical Details

What was added:

• In docs/reference/events.mdx:
  • New contract sections for run.interrupt, run.checkpoint, and run.resume
  • Concrete JSON examples for each runtime event subtype
  • Field-level definitions (checkpoint_id, event_offset, checkpoint_path, resume_strategy)
  • Checkpoint metadata location/fields and pre-resume consistency validation notes
• In docs/reference/python-api.mdx:
  • New "Checkpoint consistency troubleshooting" runbook
  • Exact consistency checks mapped to runtime behavior
  • Recovery guidance for artifact drift and tamper scenarios

Codepaths covered by these docs:

• noesis/usecases/run_lifecycle.py
• noesis/domain/run_lifecycle.py
• tests/runtime/test_run_lifecycle.py

Key knowledge gaps addressed:

• Missing reference docs for lifecycle runtime event payloads
• Missing operational explanation for checkpoint consistency failures
• Missing concrete guidance for safe resume recovery workflow

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. This is a docs-only PR that clarifies fail-closed checkpoint consistency semantics and safe recovery expectations.

Educational / Research Value

N/A (documentation clarification only).

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

Screenshots / Logs

N/A (docs-only).

Related Issues / References

• Runtime lifecycle contracts and checkpoint consistency logic in:
  • noesis/usecases/run_lifecycle.py
  • noesis/domain/run_lifecycle.py
  • tests/runtime/test_run_lifecycle.py