{"row":{"id":"ADR-010","title":"miette as the L4 diagnostic presentation layer","file":"adr-010-miette-diagnostic-layer.md","status":"accepted","date":"2026-04-14","cites":5,"supersedes":[],"superseded_by":[],"layers":["L0","L4"],"tags":["diagnostics","miette","error-rendering","l4"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-010: miette as the L4 diagnostic presentation layer","id":"adr-010-miette-as-the-l4-diagnostic-presentation-layer"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"ADR-005 established "},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" trait + "},{"k":"code","text":"Box<dyn>"},{"k":"text","text":" unification at API boundaries — correct for routing, retry ("},{"k":"code","text":"is_transient()"},{"k":"text","text":"), and fingerprinting. It does NOT, however, solve "},{"k":"em","text":"rendering"},{"k":"text","text":": when a user runs "},{"k":"code","text":"nika check workflow.nika.yaml"},{"k":"text","text":" and a template parse fails at line 14, they want source-span highlighting, a "},{"k":"code","text":"--explain NIKA-384"},{"k":"text","text":", and coloured severity — not a single-line "},{"k":"code","text":"Error: NIKA-384: ..."},{"k":"text","text":" string."}]},{"k":"p","inline":[{"k":"text","text":"The Rust 2026 ecosystem has converged on "},{"k":"strong","text":"miette"},{"k":"text","text":" for this role (ruff, uv, cargo-dist, rye all use it or miette-class renderers). "},{"k":"code","text":"miette 7.6"},{"k":"text","text":" is already pinned in "},{"k":"code","text":"[workspace.dependencies]"},{"k":"text","text":" and "},{"k":"code","text":"NikaError"},{"k":"text","text":" already carries "},{"k":"code","text":"impl miette::Diagnostic"},{"k":"text","text":". This ADR locks the pattern and scope so downstream L4 crates inherit it consistently."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-error"},{"k":"text","text":" "},{"k":"strong","text":"keeps"},{"k":"text","text":" the "},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" trait as the structural / routing contract (ADR-005 unchanged)."}],[{"k":"code","text":"nika-error"},{"k":"text","text":" "},{"k":"strong","text":"additionally"},{"k":"text","text":" implements "},{"k":"code","text":"miette::Diagnostic"},{"k":"text","text":" for "},{"k":"code","text":"NikaError"},{"k":"text","text":" — this is the rendering contract."}],[{"k":"text","text":"L4 crates ("},{"k":"code","text":"nika-cli"},{"k":"text","text":", "},{"k":"code","text":"nika-lsp"},{"k":"text","text":", "},{"k":"code","text":"nika-serve"},{"k":"text","text":", "},{"k":"code","text":"nika-catalog-verify"},{"k":"text","text":") render all user-visible errors via "},{"k":"code","text":"miette::GraphicalReportHandler"},{"k":"text","text":" (or equivalent)."}],[{"k":"text","text":"Source spans, severity, help strings, related diagnostics — all flow through miette's "},{"k":"code","text":"Diagnostic"},{"k":"text","text":" API."}],[{"k":"code","text":"--explain NIKA-NNN"},{"k":"text","text":" CLI subcommand uses the registered help string per "},{"k":"code","text":"NikaCode"},{"k":"text","text":"."}],[{"k":"text","text":"Library crates (L0, L0.5, L1, L2, L3) "},{"k":"strong","text":"do NOT"},{"k":"text","text":" depend on miette at runtime — their errors implement only "},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":"; miette is purely a presentation concern."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"User-facing errors are best-in-class (source underlines, colour, hyperlinked error codes)."}],[{"k":"text","text":"Library crates stay lean — no miette surface in kernel/catalog/error public types beyond the optional "},{"k":"code","text":"Diagnostic"},{"k":"text","text":" impl on "},{"k":"code","text":"NikaError"},{"k":"text","text":"."}],[{"k":"code","text":"--explain"},{"k":"text","text":" works by registry lookup — zero per-error maintenance cost."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"L0 "},{"k":"code","text":"nika-error"},{"k":"text","text":" carries a miette dep (already paid — feature-gated via "},{"k":"code","text":"diagnostic"},{"k":"text","text":")."}],[{"k":"text","text":"Two contracts per error type ("},{"k":"code","text":"NikaErrorCode"},{"k":"text","text":" + "},{"k":"code","text":"Diagnostic"},{"k":"text","text":"). Mitigated by derive helpers."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"If the community pivots to ariadne or a successor, we swap in "},{"k":"code","text":"nika-error"},{"k":"text","text":" only — library crates untouched."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-error/Cargo.toml:14"},{"k":"text","text":" — "},{"k":"code","text":"miette = { workspace = true, features = [\"fancy-no-backtrace\"] }"}],[{"k":"code","text":"crates/nika-error/src/nika_error.rs:97"},{"k":"text","text":" — "},{"k":"code","text":"impl miette::Diagnostic for NikaError"}],[{"k":"code","text":"crates/nika-error/src/codes.rs:128"},{"k":"text","text":" — per-code help strings"}],[{"k":"text","text":"ADR-005 — the structural error hierarchy this extends"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — `anyhow` / `eyre` at CLI","id":"alt-a--anyhow--eyre-at-cli"},{"k":"p","inline":[{"k":"text","text":"Rejected. Both produce flat strings — no spans, no "},{"k":"code","text":"--explain"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"Alt B — Custom renderer","id":"alt-b--custom-renderer"},{"k":"p","inline":[{"k":"text","text":"Rejected. Reinvents miette. Not valuable."}]},{"k":"h","depth":3,"text":"Alt C — `error-stack` (HASH) with attachments","id":"alt-c--error-stack-hash-with-attachments"},{"k":"p","inline":[{"k":"text","text":"Watching. Good for structured observability context but not focused on user-facing rendering. Revisit if miette stagnates."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-005 — trait-based error hierarchy (structural contract this rendering layer wraps)"}],[{"k":"text","text":"ADR-007 — forward-compat invariants ("},{"k":"code","text":"NikaError"},{"k":"text","text":" is "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":")"}],[{"k":"text","text":"ADR-015 — "},{"k":"code","text":"expect-test"},{"k":"text","text":" inline snapshots (regression coverage for the rendering this ADR locks)"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"When "},{"k":"code","text":"nika-cli"},{"k":"text","text":" is admitted, add a "},{"k":"code","text":"test-miette-render.rs"},{"k":"text","text":" golden test that pins the rendered output of 3 representative error codes. Prevents accidental UX regression."}]}]

ADR-010

miette as the L4 diagnostic presentation layer

accepted · 2026-04-14 · L0 L4 · cites 5

ADR-010: miette as the L4 diagnostic presentation layer #

Context #

ADR-005 established NikaErrorCode trait + Box<dyn> unification at API boundaries — correct for routing, retry (is_transient()), and fingerprinting. It does NOT, however, solve rendering: when a user runs nika check workflow.nika.yaml and a template parse fails at line 14, they want source-span highlighting, a --explain NIKA-384, and coloured severity — not a single-line Error: NIKA-384: ... string.

The Rust 2026 ecosystem has converged on miette for this role (ruff, uv, cargo-dist, rye all use it or miette-class renderers). miette 7.6 is already pinned in [workspace.dependencies] and NikaError already carries impl miette::Diagnostic. This ADR locks the pattern and scope so downstream L4 crates inherit it consistently.

Decision #

nika-error keeps the NikaErrorCode trait as the structural / routing contract (ADR-005 unchanged).
nika-error additionally implements miette::Diagnostic for NikaError — this is the rendering contract.
L4 crates (nika-cli, nika-lsp, nika-serve, nika-catalog-verify) render all user-visible errors via miette::GraphicalReportHandler (or equivalent).
Source spans, severity, help strings, related diagnostics — all flow through miette's Diagnostic API.
--explain NIKA-NNN CLI subcommand uses the registered help string per NikaCode.
Library crates (L0, L0.5, L1, L2, L3) do NOT depend on miette at runtime — their errors implement only NikaErrorCode; miette is purely a presentation concern.

Consequences #

Positive #

User-facing errors are best-in-class (source underlines, colour, hyperlinked error codes).
Library crates stay lean — no miette surface in kernel/catalog/error public types beyond the optional Diagnostic impl on NikaError.
--explain works by registry lookup — zero per-error maintenance cost.

Negative #

L0 nika-error carries a miette dep (already paid — feature-gated via diagnostic).
Two contracts per error type (NikaErrorCode + Diagnostic). Mitigated by derive helpers.

Neutral #

If the community pivots to ariadne or a successor, we swap in nika-error only — library crates untouched.

Evidence #

crates/nika-error/Cargo.toml:14 — miette = { workspace = true, features = ["fancy-no-backtrace"] }
crates/nika-error/src/nika_error.rs:97 — impl miette::Diagnostic for NikaError
crates/nika-error/src/codes.rs:128 — per-code help strings
ADR-005 — the structural error hierarchy this extends

Alternatives considered #

Alt A — `anyhow` / `eyre` at CLI #

Rejected. Both produce flat strings — no spans, no --explain.

Alt B — Custom renderer #

Rejected. Reinvents miette. Not valuable.

Alt C — `error-stack` (HASH) with attachments #

Watching. Good for structured observability context but not focused on user-facing rendering. Revisit if miette stagnates.

ADR-005 — trait-based error hierarchy (structural contract this rendering layer wraps)
ADR-007 — forward-compat invariants (NikaError is #[non_exhaustive])
ADR-015 — expect-test inline snapshots (regression coverage for the rendering this ADR locks)

Notes #

When nika-cli is admitted, add a test-miette-render.rs golden test that pins the rendered output of 3 representative error codes. Prevents accidental UX regression.

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

Every decision, with its status This one in the repo