docs: document final artifact sealing contract

[cursor]

🧠 Noēsis Pull Request

Overview

Adds first-class documentation for the final.json terminal sealing contract and updates the artifacts explanation so final markers, checkpoint files, and manifest inclusion are easier to reason about.

Type of Change

• 📚 Documentation or research notes

Motivation & Context

The final/2.0.0 schema existed, but the public docs did not have a dedicated final artifact reference. The artifact overview also omitted final.json, checkpoint placement, and the exact terminal vs paused-run sealing behavior.

Technical Details

Docs added/updated:

• Added docs/reference/final.mdx with schema fields, outcome mapping, sealing lifecycle, paused-run constraints, and operational checks.
• Updated docs/explanation/artifacts.mdx to include final.json, checkpoints/, sealing order, manifest coverage, and corrected the manifest verification example to use the files array shape.
• Added reference/final to the Schema reference navigation in docs/docs.json.

Codepaths covered:

• noesis/domain/artifacts/finalization.py (FinalizationRecord, schema constants, outcome vocabulary)
• noesis/usecases/finalization.py (runtime outcome to final contract mapping)
• noesis/core.py (_seal_episode, _finalize_episode sealing order and rollback)
• noesis/usecases/run_lifecycle.py (sealed-run guardrails, checkpoint files, pause/resume lifecycle)
• noesis/runtime/artifacts/writer.py (manifest default and untracked artifact inclusion)

Key knowledge gaps addressed:

• How to interpret outcome and verification_status in final.json.
• Why paused/interrupted approval flows stay unsealed until terminal continuation.
• How final.json and manifest.json should be checked together for sealed-run evidence.
• Where checkpoint anchors live and how they relate to non-terminal runs.

Validation

Required

• Equivalent targeted suite: git diff --check HEAD~1..HEAD
• Schema validation and export diff clean: python3 -m json.tool docs/docs.json and python3 -m json.tool docs/schema/final/2.0.0.json

Situational

• Docs build/link validation: npx --yes mintlify@latest broken-links from docs/

Observability & Safety

Documentation-only change. No runtime behavior, schema, telemetry, or policy semantics changed.

Educational / Research Value

Improves operator and developer understanding of sealed evidence bundles, terminal artifacts, and pause/resume auditability.

Screenshots / Logs

Validation output:

success no broken links found

Related Issues / References

Source-backed against the finalization, run lifecycle, and manifest writer implementations listed above.