ADR-11: Unified error taxonomy

Status: accepted (2026-05-28) Blocks: workstream A (core errors), workstream D (Python bindings), workstream E (bridge), workstream G (cross-cutting infra).

Context

Rust returns Result<T, DagMlError>; the C ABI uses integer return codes; Python bindings raise exceptions; nirs4all has its own exception hierarchy. Without a unified taxonomy, a single failure becomes a different opaque error in every binding layer. Users can’t write robust catch-blocks; debugging crosses three layers.

Decision

One stable error code surface that maps deterministically across all layers:

Error code structure

error_code = (category, code, severity):

  • category: one of validation, runtime, data, controller, bundle, lineage, replay, security, compatibility, internal.

  • code: short stable identifier (e.g. oof_leakage, envelope_version_unsupported, schema_fingerprint_mismatch, controller_dispatch_failed, repetition_leakage).

  • severity: fatal | error | warning. warning doesn’t fail by default but flips to error under --strict.

Per-layer mapping

  • Rust — DagMlError enum with one variant per (category, code). Carries structured context: stable code, category, severity, optional cause: Box<dyn Error>, optional remediation_hint: &'static str, and a context: BTreeMap<&'static str, serde_json::Value> for query-time debug fields.

  • C ABI — returns int32_t: 0 on success, otherwise (category << 16) | code. A thread-local last-error buffer holds the JSON-serialized DagMlError so callers can fetch the structured payload via dagml_last_error_json.

  • Python — DagMlError base class with one subclass per category (DagMlValidationError, DagMlRuntimeError, etc.). Each subclass exposes .code, .category, .severity, .remediation_hint, .context. Catch hierarchy mirrors the Rust enum.

  • nirs4all — bridge maps DagMlError.category to nirs4all’s existing exception classes (PipelineError, DataError, ValidationError from nirs4all/core/exceptions.py). The mapping is exhaustive and tested.

Remediation hints

Every error variant carries a remediation_hint — a single sentence telling the user the next thing to do. Hints are part of the public ABI; CI fails if a new variant ships without one. Examples:

  • oof_leakage → “Refit the offending edge with requires_oof = true or remove the leakage path; see ADR-05.”

  • envelope_version_unsupported → “Re-export your bundle with nirs4all workspace migrate; see ADR-02.”

  • repetition_leakage → “Pass respect_repetition=True to your splitter; see ADR-05.”

Consequences

  • Workstream A task 6 introduces the DagMlError enum + builders.

  • Workstream G task 1 lands the C ABI side and the Python exception hierarchy.

  • CONTRIBUTING.md (workstream C task 1) documents how to add a new error variant, including the remediation-hint requirement.

  • The bridge logs every refusal with code, category, context — feeds the observability hooks (ADR-12).

Risk

  • An exhaustive enum is a stable surface; adding variants is non-breaking but renaming/removing one is. CHANGELOG entries flag any new variants under “added” and removals under “breaking change” with the deprecation cycle from ADR-14.