Skip to content

Error classification, propagation, and rendering

This contract separates the meaning of a failure from the transport used to carry it and the public protocol used to render it.

Contract status

Current behavior is distributed across engine, message, and entrypoint code. The semantic hierarchy proposed by #5570 remains an open RFC. Proposed types and wire records from that RFC are not current contracts.

Ownership boundary

This document owns semantic classification, fatal versus request-scoped failure, cross-process error context, compatibility policy, sanitization, and offline, HTTP, SSE, WebSocket, and asynchronous-job rendering rules.

engine/messages.py remains primarily owned by the I/O contract; this page owns the semantics of its error fields. Route and serving files remain primarily owned by entrypoints.md; this page owns their rendering constraints.

Candidate invariants

The following topics require owner review before receiving stable IDs:

  • A request-scoped failure terminates only the affected request unless the underlying engine is no longer usable.
  • Every public rendering path preserves a stable classification while removing sensitive internal context.
  • Cancellation remains distinguishable from internal failure across process and protocol boundaries.

Invariant namespace

ERR-INV reserves 001-099 for classification ownership, 100-199 for wire context and compatibility, 200-299 for fatality, termination, sanitization, and rendering, and 300-399 for upstream alignment and transport extension points. Numbers become append-only after normative promotion.

Safe-change guide

Exercise exception classification, stage wire round trips, fatal and request-scoped propagation, cancellation, sanitization, offline exceptions, HTTP status/body consistency, streaming terminal events, asynchronous-job persistence, and metrics classification.

Promotion gate

  • Resolve #5570's hierarchy, wire record, sanitization, and mixed-version questions.
  • Add table-driven exception/status/type tests and stage wire round trips.
  • Verify all public transports terminate once and do not leak sensitive payload data.
  • Obtain approval from both technical owners and an independent validation reviewer.