{"row":{"id":"ADR-005","title":"Trait-based error hierarchy with NikaErrorCode and Box<dyn>","file":"adr-005-error-hierarchy.md","status":"accepted","date":"2026-04-13","cites":8,"supersedes":[],"superseded_by":[],"layers":["L0"],"tags":["error-handling","traits","error-codes"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-005: Trait-based error hierarchy (`NikaErrorCode` + `Box<dyn>` + code registry)","id":"adr-005-trait-based-error-hierarchy-nikaerrorcode--boxdyn--code-registry"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Legacy Nika had a god "},{"k":"code","text":"NikaError"},{"k":"text","text":" enum with hundreds of variants spread across crates. Shadow-zone audit (2026-04-13) identified this as zone #6: "},{"k":"strong","text":"95% of variants lacked Display golden tests"},{"k":"text","text":", and error codes had silently collided. Downstream crates had to depend on the central enum, creating cyclic dep risks."}]},{"k":"p","inline":[{"k":"text","text":"Three alternatives were weighed during "},{"k":"code","text":"nika-error"},{"k":"text","text":" admission:"}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"A — `anyhow::Error` everywhere:"},{"k":"text","text":" opaque, no structured codes, loses the wire-format IDs ("},{"k":"code","text":"NIKA-140"},{"k":"text","text":", "},{"k":"code","text":"NIKA-384"},{"k":"text","text":") that Shield and CLI rely on."}],[{"k":"strong","text":"B — single `thiserror` enum in a root crate:"},{"k":"text","text":" every crate must depend on the enum; adding a variant touches the root crate and rebuilds the world; circular-dep magnet."}],[{"k":"strong","text":"C+ — trait-based hierarchy:"},{"k":"text","text":" per-crate error enums implement a shared trait; unified at API boundaries via "},{"k":"code","text":"Box<dyn>"},{"k":"text","text":"."}]]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"\"Option C+\" — trait-based error hierarchy."}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" trait lives in "},{"k":"code","text":"nika-error"},{"k":"text","text":" (L0). Every crate's error enum implements it."}],[{"k":"code","text":"NikaError = Box<dyn NikaErrorCode>"},{"k":"text","text":" — dynamic dispatch at API boundaries."}],[{"k":"code","text":"NikaCode"},{"k":"text","text":" carries a "},{"k":"strong","text":"dual representation"},{"k":"text","text":": wire format "},{"k":"code","text":"\"NIKA-140\""},{"k":"text","text":" for Display/logs AND a structured "},{"k":"code","text":"{num: u16, category: Category, severity: Severity, slug: &'static str}"},{"k":"text","text":" for JSON serialization and programmatic routing."}],[{"k":"code","text":"CoreError"},{"k":"text","text":" handles cross-cutting errors that don't belong to any specific crate (config, bootstrap, etc.)."}],[{"k":"strong","text":"Error code ranges reserved per subsystem"},{"k":"text","text":" in "},{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":":"},{"k":"text","text":"\n\n"},{"k":"text","text":"| Range | Subsystem |\n|---|---|\n| NIKA-000..099 | Core |\n| NIKA-100..199 | MCP |\n| NIKA-200..299 | Shield (security) |\n| NIKA-300..399 | Catalog |\n| NIKA-400..499 | Cortex (memory) |\n| NIKA-500..599 | Providers |\n| NIKA-600..699 | Runtime / DAG |\n| NIKA-700..799 | IO (fs, http, shell) |\n| NIKA-800..899 | Observability |\n| NIKA-900..999 | Reserved |\n"}],[{"k":"text","text":"Default trait methods: "},{"k":"code","text":"is_transient() -> bool"},{"k":"text","text":" (for retry logic), "},{"k":"code","text":"fingerprint() -> u64"},{"k":"text","text":" (for dedup/ratelimit)."}],[{"k":"text","text":"Downcasting via "},{"k":"code","text":"AsAny"},{"k":"text","text":" supertrait avoids per-impl boilerplate."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Each crate owns its error enum without circular deps."}],[{"k":"code","text":"is_transient()"},{"k":"text","text":" default enables retry logic across all errors without coupling the retry layer to specific error types."}],[{"k":"text","text":"Error code ranges prevent collision as subsystems are admitted over 11+ months."}],[{"k":"text","text":"Display parity enforced via golden tests per crate, resolving shadow zone #6."}],[{"k":"text","text":"JSON serialization round-trips: "},{"k":"code","text":"{num, category, severity, slug}"},{"k":"text","text":" → wire format → back."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"Box<dyn>"},{"k":"text","text":" allocation on the error path (vs zero-alloc enum with "},{"k":"code","text":"thiserror"},{"k":"text","text":"). Measured: ~50ns additional latency per error — acceptable; errors are exceptional by definition."}],[{"k":"text","text":"Every new crate author must implement "},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" — more ceremony than "},{"k":"code","text":"anyhow::bail!"},{"k":"text","text":". Mitigated by "},{"k":"code","text":"derive"},{"k":"text","text":"-style helpers in "},{"k":"code","text":"nika-error"},{"k":"text","text":"."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"Box<dyn>"},{"k":"text","text":" + "},{"k":"code","text":"AsAny"},{"k":"text","text":" supertrait means error types must be "},{"k":"code","text":"'static"},{"k":"text","text":", "},{"k":"code","text":"Send"},{"k":"text","text":", "},{"k":"code","text":"Sync"},{"k":"text","text":" — matches existing conventions."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-error/src/traits.rs"},{"k":"text","text":" lines 43–71 — "},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" trait definition with "},{"k":"code","text":"is_transient"},{"k":"text","text":", "},{"k":"code","text":"fingerprint"},{"k":"text","text":" defaults"}],[{"k":"code","text":"crates/nika-error/src/lib.rs"},{"k":"text","text":" — full crate structure, 1,013 LOC, 44 tests, Gate 5 mutation 100%"}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" lines 105–127 — reserved error code ranges table"}],[{"k":"code","text":"CHANGELOG.md"},{"k":"text","text":" — "},{"k":"code","text":"nika-error"},{"k":"text","text":" admission commit "},{"k":"code","text":"42909b1c7"}],[{"k":"text","text":"Related crate: "},{"k":"strong","text":"`nika-error`"},{"k":"text","text":" (first admitted, L0)"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — `anyhow::Error` at API boundaries","id":"alt-a--anyhowerror-at-api-boundaries"},{"k":"p","inline":[{"k":"text","text":"See context. Rejected: opaque; loses wire-format IDs; breaks Shield integration."}]},{"k":"h","depth":3,"text":"Alt B — Single `thiserror` enum in root","id":"alt-b--single-thiserror-enum-in-root"},{"k":"p","inline":[{"k":"text","text":"See context. Rejected: coupling + build-time cascade on any variant addition."}]},{"k":"h","depth":3,"text":"Alt D — `snafu` with context selectors","id":"alt-d--snafu-with-context-selectors"},{"k":"p","inline":[{"k":"text","text":"Evaluated in Rust Council. Rejected: snafu's context pattern is ergonomic for small error trees but less flexible for dual wire/structured representation. Trait-based pattern scales better past 100 error variants."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-007 — forward-compat invariants ("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" on error enums)"}],[{"k":"text","text":"ADR-010 — miette as L4 presentation (the rendering contract that wraps this structural contract)"}],[{"k":"text","text":"ADR-015 — "},{"k":"code","text":"expect-test"},{"k":"text","text":" inline snapshots (regression coverage for rendered error output)"}],[{"k":"code","text":"crates/nika-error"},{"k":"text","text":" — implementation"}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" — error code range registry"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"If a subsystem exhausts its 100-number range (unlikely), extend into NIKA-900..999 reserved range with explicit registry update. Never overlap."}]}]

ADR-005

Trait-based error hierarchy with NikaErrorCode and Box<dyn>

accepted · 2026-04-13 · L0 · cites 8

ADR-005: Trait-based error hierarchy (`NikaErrorCode` + `Box<dyn>` + code registry) #

Context #

Legacy Nika had a god NikaError enum with hundreds of variants spread across crates. Shadow-zone audit (2026-04-13) identified this as zone #6: 95% of variants lacked Display golden tests, and error codes had silently collided. Downstream crates had to depend on the central enum, creating cyclic dep risks.

Three alternatives were weighed during nika-error admission:

A — `anyhow::Error` everywhere: opaque, no structured codes, loses the wire-format IDs (NIKA-140, NIKA-384) that Shield and CLI rely on.
B — single `thiserror` enum in a root crate: every crate must depend on the enum; adding a variant touches the root crate and rebuilds the world; circular-dep magnet.
C+ — trait-based hierarchy: per-crate error enums implement a shared trait; unified at API boundaries via Box<dyn>.

Decision #

"Option C+" — trait-based error hierarchy.

NikaErrorCode trait lives in nika-error (L0). Every crate's error enum implements it.
NikaError = Box<dyn NikaErrorCode> — dynamic dispatch at API boundaries.
NikaCode carries a dual representation: wire format "NIKA-140" for Display/logs AND a structured {num: u16, category: Category, severity: Severity, slug: &'static str} for JSON serialization and programmatic routing.
CoreError handles cross-cutting errors that don't belong to any specific crate (config, bootstrap, etc.).
Error code ranges reserved per subsystem in docs/architecture/forward-compat-invariants.md: | Range | Subsystem | |---|---| | NIKA-000..099 | Core | | NIKA-100..199 | MCP | | NIKA-200..299 | Shield (security) | | NIKA-300..399 | Catalog | | NIKA-400..499 | Cortex (memory) | | NIKA-500..599 | Providers | | NIKA-600..699 | Runtime / DAG | | NIKA-700..799 | IO (fs, http, shell) | | NIKA-800..899 | Observability | | NIKA-900..999 | Reserved |
Default trait methods: is_transient() -> bool (for retry logic), fingerprint() -> u64 (for dedup/ratelimit).
Downcasting via AsAny supertrait avoids per-impl boilerplate.

Consequences #

Positive #

Each crate owns its error enum without circular deps.
is_transient() default enables retry logic across all errors without coupling the retry layer to specific error types.
Error code ranges prevent collision as subsystems are admitted over 11+ months.
Display parity enforced via golden tests per crate, resolving shadow zone #6.
JSON serialization round-trips: {num, category, severity, slug} → wire format → back.

Negative #

Box<dyn> allocation on the error path (vs zero-alloc enum with thiserror). Measured: ~50ns additional latency per error — acceptable; errors are exceptional by definition.
Every new crate author must implement NikaErrorCode — more ceremony than anyhow::bail!. Mitigated by derive-style helpers in nika-error.

Neutral #

Box<dyn> + AsAny supertrait means error types must be 'static, Send, Sync — matches existing conventions.

Evidence #

crates/nika-error/src/traits.rs lines 43–71 — NikaErrorCode trait definition with is_transient, fingerprint defaults
crates/nika-error/src/lib.rs — full crate structure, 1,013 LOC, 44 tests, Gate 5 mutation 100%
docs/architecture/forward-compat-invariants.md lines 105–127 — reserved error code ranges table
CHANGELOG.md — nika-error admission commit 42909b1c7
Related crate: `nika-error` (first admitted, L0)

Alternatives considered #

Alt A — `anyhow::Error` at API boundaries #

See context. Rejected: opaque; loses wire-format IDs; breaks Shield integration.

Alt B — Single `thiserror` enum in root #

See context. Rejected: coupling + build-time cascade on any variant addition.

Alt D — `snafu` with context selectors #

Evaluated in Rust Council. Rejected: snafu's context pattern is ergonomic for small error trees but less flexible for dual wire/structured representation. Trait-based pattern scales better past 100 error variants.

ADR-007 — forward-compat invariants (#[non_exhaustive] on error enums)
ADR-010 — miette as L4 presentation (the rendering contract that wraps this structural contract)
ADR-015 — expect-test inline snapshots (regression coverage for rendered error output)
crates/nika-error — implementation
docs/architecture/forward-compat-invariants.md — error code range registry

Notes #

If a subsystem exhausts its 100-number range (unlikely), extend into NIKA-900..999 reserved range with explicit registry update. Never overlap.

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo