RFD-0024 — Diagnostic codes — OE / OW / OI severity prefix; X* for external bridges

Question

The compiler emits errors, warnings, and info notices. How are they identified, and how does the namespace accommodate diagnostics emitted by toolchain extensions like format bridges (ox-ontouml, ox-owl, etc.)?

Decision

Built-in compiler diagnostics use the O* family with a severity-prefix character + four-digit numeric category:

• OE#### — error. Severity is unrecoverable; the build fails.
• OW#### — warning. Build proceeds; the issue is surfaced.
• OI#### — info. Informational notice, never blocks.

Numeric categories cluster diagnostics by phase or subsystem:

• OE01XX — bare-keyword and primitive-name resolution.
• OE02XX — elaboration and validation.
• OE03XX — saturation and constraint violations.
• OE04XX — lowering and stratification.
• OE05XX — tier classification and enforcement.
• OE06XX — meta-property calculus.
• (etc., as the surface evolves.)

External bridge diagnostics use the X* family. A toolchain extension (RFD-0003) registers diagnostic codes through oxc-protocol::core::codes::StaticCode + inventory::submit!. The convention:

• X* first-character marks external/bridge origin.
• Per-bridge subrange is reserved (e.g., XW0841-XW0851 for OntoUML import warnings; XW0860-XW0869 reserved for the OWL translator).

The compiler’s enum-style ErrorCode retains a Registered(&'static str) escape hatch backed by the inventory registry; built-in compiler diagnostics use the dedicated enum variants.

Rationale

Severity in the prefix. A diagnostic code is read out of context (CI logs, ticket titles, search results). Embedding severity in the code itself means the reader sees OE0203 and knows it’s an error without further lookup.

Four-digit numeric category clusters by subsystem. When debugging, a developer who sees OE05XX knows it’s tier-related without having to look up the specific code. Clustering makes the namespace browsable.

O* vs X* separates origin. A diagnostic from oxc is the compiler’s claim about the source; a diagnostic from ox-ontouml is a bridge’s claim about a foreign-format input. Separating by prefix makes provenance clear and prevents the compiler enum from accumulating bridge-specific variants.

Enum + Registered hybrid. Compiler-built-in codes preserve enum exhaustiveness checks (the compiler can audit “do we handle every diagnostic kind”). External codes register dynamically (foreign-format-neutrality means the compiler doesn’t pre-know them). The Registered(&'static str) escape hatch carries external codes through the same surface without ballooning the enum.

Consequences

• New compiler diagnostics get an OE / OW / OI code in the next available numeric slot in their subsystem cluster.
• External bridges register codes in the X* namespace via inventory::submit!. The owning ox-* crate documents its subrange.
• Code allocation tracks centrally in oxc/src/diagnostics/codes.rs for built-ins; external subranges document in their owning crate.
• Reserved subranges: XW0841-XW0851 (OntoUML), XW0860-XW0869 (OWL translator), additional bridges as they land.
• The book’s appendix C reference covers OE / OW / OI built-in codes; external code documentation lives with the owning bridge.