Date: 2026-02-28
Status: Canonical supporting contract
Priority: Immediate implementation guidance

Related:

• SUBSYSTEM_DIAGNOSTICS.md
• ../subsystem_accessibility/accessibility_interaction_and_capability_spec.md
• ../subsystem_history/history_timeline_and_temporal_navigation_spec.md

---

This spec defines the supporting contract surface for diagnostics observability and harness behavior.

Policy authority remains in SUBSYSTEM_DIAGNOSTICS.md. If policy text in this file conflicts with SUBSYSTEM_DIAGNOSTICS.md, the subsystem file is authoritative.

It governs:

• channel schema integrity
• invariant watchdog behavior
• analyzer and harness boundaries
• retention and observability policy
• diagnostics UI readiness as a consumer of runtime signals

---

The Diagnostics subsystem has three distinct runtime roles:

1. channel schema registry
2. continuous analyzers
3. on-demand test harness execution

These roles must remain explicit and not collapse into one undifferentiated debug system.

---

• All emitted channels must have a declared schema and severity.
• Unknown channels may be tolerated for robustness, but never silently.
• Phase-required channels must be present at startup.

• Started operations that require termination signals must have watchdog coverage.
• Violations must enter the event ring.
• Pending invariants must be visible.

• Analyzers are live, continuous observers.
• Harness tests are isolated, synthetic, and explicitly invoked.
• Probes with side effects are forbidden.

• Per-channel retention must be respected.
• Runtime config changes must round-trip correctly.
• Diagnostics state must remain inspectable without mutating semantic subsystem state.

• history.* channel families declared by the History subsystem are first-class diagnostics contracts, not optional future logging.
• Diagnostics must be able to summarize history health without scraping UI text from the History Manager surface.
• Preview/replay violations must remain visible even when preview UI is disabled or hidden.

---

• richer diagnostics summaries by subsystem
• in-pane grouped counters and recent-history panels
• stronger invariant coverage across major mutation boundaries
• history subsystem health-summary projection fed by history.traversal.*, history.archive.*, and history.timeline.*

---

• mod-contributed analyzers with richer policy hooks
• subsystem health scoring
• automated remediation guidance for common failures

---

• Core channels and severities are declared.
• Invariant violations are observable.
• Analyzer and harness boundaries are enforced.
• Diagnostics can summarize subsystem degradation without becoming a mutation authority.
• History summary fields are derivable from explicit history.* traffic and do not depend on UI-only inspection.