Diagnostic codes

The compiler crate oxc-diagnostics holds the authoritative diagnostic catalog (generated.rs), regenerated from the [[diagnostic]] entries in oxc-syntax/grammar.toml. This appendix is generated from the same entries — it cannot drift from the catalog (CI enforces it via cargo xtask check-drift). Where prose elsewhere in the book disagrees with a row here, this table wins.

A code is O[E|W|I]NNNN — an O-prefix (legacy Ontolog/Oxide; carries through pending a v0.3 rename), a severity letter, and a four-digit number.

The catalog has 388 codes (367 OE + 19 OW + 2 OI), of which 350 are live (a real emitter exists) and 38 are reserved for planned later stages.

The Status column distinguishes a live code (a real emitter exists in the toolchain) from a reserved one (declared up-front for a planned later stage, no emitter yet — audit dc-04). A reserved code never fires today; it is listed so the number is claimed and the planned gate is documented. There are no library-namespaced codes (mlt::, potency::, ufo::) in the catalog: a theory package authors its constraints as its own rules/checks over the neutral substrate, never as reserved compiler codes. The MLT reasoning codes that once sat in 19xx are gone for exactly that reason; the 19xx codes that remain are the cross-level instantiation-body field-coverage gates (§5.2), which are substrate-level, not theory-specific.

Range allocation

The number’s leading digits group codes by subsystem. These are conventions for allocation, not a hard partition; ranges with no codes today are omitted.

Parse and name resolution (00xx–01xx)

Type, elaboration, predicate atoms, membership writes (02xx)

Stratification (05xx)

Reserved range — the stratifier’s pre-runtime aggregate diagnoses. The runtime equivalents fire as OE13xx rule-compile gates today.

Meta calculus, refinement, comparison, traits (06xx)

Modules, attributes, temporal, modal, forget (07xx)

Field modifiers, world-assumption gates, construction (08xx)

World-assumption conservativity (09xx)

Reserved range — the §6.9 world-assumption gates are designed but not yet wired.

CWA evaluation and field intent (10xx)

Bridges (11xx)

Build composition and .oxbin validation (12xx, §16)

Runtime contract and rule-evaluation gates (13xx, §17)

ox build is fail-closed: it re-runs the runtime’s own rule compiler as an oracle over every rule and refuses to write an .oxbin if any rule will not evaluate. The aggregate/quantifier codes (OE1311–OE1315) are the gate’s refusals.

Individual lifecycle and write-path stability gates (14xx)

Continuation of the runtime write-path gates past the exhausted 13xx range: the individual-retraction cascade’s transactional invariants and relation-end stability refusals allocate here.

Cross-level instantiation bodies (19xx)

Field-coverage gates for cross-level instantiation bodies (§5.2). The MLT reasoning codes (categorization / partition / order / subordination / powertype) that once sat here are gone — MLT is an unprivileged package (packages/mlt), so those constraints are authored as the package’s own rules/checks over the neutral substrate, not as reserved compiler codes.

Collection operators (24xx)

Explanations

Codes with an extended explanation (also available offline via ox explain <CODE>):

OE0204 — UnknownField

Field access x.f where the receiver’s established type declares no field f (counting inherited fields and any : T narrowing in scope). In a rule body the error fires only on provable absence: an Argon individual can be classified under several concepts, and a field on any established concept is admitted, so f must be missing from every one of them. A receiver with no established concept (an unbound variable, or a path to a declared type/enum) is skipped.

Fix: declare the field on the concept, narrow the receiver to a type that has it, or correct the field name.

use std::core::{type, rel};

pub type Person { name: String, age: Nat }

pub derive adult(p) :- p: Person, p.age >= 18;   // ok: `age` is on Person
pub derive bad(p)   :- p: Person, p.income > 0;  // OE0204: no `income` on Person

OE0211 — IofInsertOnDefined

A concept defined with iff is defined, not asserted: its membership is derived, so you cannot write membership into it manually — the substrate classifies individuals automatically whenever the definition holds. There are two defined forms:

• A braced-iff concept (iff { … }) derives membership from its refinement predicate over the individual’s fields.
• A shape-defined concept (iff <Shape>(self)) derives membership from a synthesized rule over relations/facts.

(A primitive concept declared with where is the opposite: membership is asserted, and insert iof is exactly how you assert it.)

insert iof / delete iof into either defined form is refused — membership is single-source, never asserted. Constructing an instance of a shape-defined concept (insert C { … }), or of a subtype beneath one, is refused for the same reason: construction buffers an asserted iof, and a shape concept’s relational evidence can never be supplied by a construct. A braced-iff concept is constructible — its predicate evaluates over the constructed fields, so its extent stays honest.

Fix — write the underlying state the definition reads, and let classification follow:

use std::core::{type, rel};

pub type Adult <: Person iff { self.age >= 18 };

pub mutate seed() {
    insert Person { name: "Mia", age: 19 };   // not `insert iof Adult`
    // Mia classifies as Adult automatically (age >= 18).
}

For a shape-defined concept, construct the supertype and assert the relations/facts its shape derive reads.

The same applies through <:-ancestors: if any defined ancestor derives the membership, the write is refused — asserting (or constructing) a descendant would assert the single-source ancestor.

OE0213 — IofInsertIntoBot

Bot (⊥) is the empty concept — the lattice bottom. By definition it has no instances: nothing is ever an instance of Bot. So insert iof(x, Bot) asserts a contradiction (x is a member of a category that, by definition, is empty) and is refused statically.

This is a sound, unconditional refusal — it follows from Bot’s definition alone, not from any two-concept disjointness analysis (that stays reserved). The dual, Top (⊤), is the opposite: every individual is an instance of it, so a rule body Top(x) ranges over the whole domain.

If you meant to assert membership in a real concept, name that concept:

pub type Person;

pub mutate seed(p: Person) {
    insert iof(p, Person);   // not `insert iof(p, Bot)`
}

OE0605 — UnknownMetatype

Argon has no built-in ontology vocabulary. A declaration like pub kind Person reads kind as a classifier, and classifiers are not keywords — the leading introducer must resolve to a pub metatype that is in scope (§3.4). That is what keeps the language ontology-neutral: kind, class, rigid_sortal and friends ship in vocabulary packages (UFO, BFO, …), never in the compiler.

Even the no-commitment baseline type/rel are not ambient: they live in std::core and must be imported.

Fix — bring the baseline into scope:

use std::core::{type, rel};
pub type Person;            // ontology-uncommitted

or commit to a vocabulary you declare or import:

pub metatype kind = { };    // declares the `kind` classifier
pub kind Person;            // now legal

To make the baseline available across a whole package, set prelude = ["std::core::{type, rel}"] under [package] in ox.toml.

OE0668 — RefinementInvariantViolated

A primitive concept declared with where carries a necessary invariant: every member must satisfy it. This write would place an individual in the concept while the predicate evaluates to a definite false, so it is refused.

Three-valued by design: only a definite false blocks the write. If the predicate is unknown (a field the data has not supplied yet), the write is allowed — absence of information is not a violation.

use std::core::{type, rel};

pub type Adult <: Person where { self.age >= 18 };

pub mutate admit() {
    insert Adult { name: "Lee", age: 15 };   // OE0668: 15 >= 18 is definitely false
    insert Adult { name: "Ada", age: 21 };   // ok
    // age unknown -> allowed (unknown, not false)
}

Fix: write a value that satisfies the invariant, model the looser set with a weaker where, or — if membership should be derived rather than asserted — use an iff definition instead.

OE0239 — FactReferencesDerivedPredicate

A predicate in Argon has a single origin: its extent is either EXTENSIONAL (asserted as ground facts) or INTENSIONAL (computed by derive/query rules) — never both. pub fact P(...) asserts into an extensional relation, but here P is a rule head, so the seed fact would key a different relation node than the rule reads and silently drop out of the fixpoint: no error, wrong answer. Argon refuses at ox check / ox build rather than emit an artifact that mis-derives.

To give a derived predicate ground tuples, keep it single-origin: seed the head with a bodiless derive clause, or read a base relation. Note that rule bodies must be range-restricted — bind each head variable with a positive atom, not a bare comparison (p.income > 0 alone leaves p unbound):

use std::core::{type, rel};

// a base relation the rule reads (seed it with `pub fact HighEarner(...)`),
// unioned with the rule clauses over the same head:
pub rel HighEarner(mut p: Person);
pub derive owes_tax(p) :- HighEarner(p);
pub derive owes_tax(p) :- p: Person, p.income > 0;