{"row":{"id":"ADR-008","title":"TOML-driven catalog with build-time codegen and perfect-hash lookup","file":"adr-008-toml-driven-catalog.md","status":"accepted","date":"2026-04-14","cites":3,"supersedes":[],"superseded_by":[],"layers":["L0","L4"],"tags":["catalog","toml","codegen","build-time"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-008: TOML-driven catalog with build-time codegen + perfect-hash lookup","id":"adr-008-toml-driven-catalog-with-build-time-codegen--perfect-hash-lookup"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Nika needs to resolve a user-supplied "},{"k":"code","text":"provider: claude"},{"k":"text","text":" → canonical provider id → model → capabilities → pricing in a single YAML field. Legacy used hardcoded Rust arrays. That had two problems:"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Contribution friction:"},{"k":"text","text":" adding a provider required writing Rust + rebuilding. Community contributors were blocked."}],[{"k":"strong","text":"Silent rot:"},{"k":"text","text":" the Phase A audit (2026-03) discovered "},{"k":"strong","text":"29 broken MCP aliases"},{"k":"text","text":" — entries pointing at servers that no longer existed. No one noticed for months because the data lived inside compiled code."}]]},{"k":"p","inline":[{"k":"text","text":"Session 2a (2026-04-14) set the target: move all catalog data to TOML with schema validation at build time, and add a model-capabilities rule table that replaces a 900-line "},{"k":"code","text":"match"},{"k":"text","text":" cascade."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"All catalog data lives in `data/*.toml`"},{"k":"text","text":" with versioned schemas:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika/llm-providers@1.0"},{"k":"text","text":" — 21 providers, each with "},{"k":"code","text":"canonical_id"},{"k":"text","text":", "},{"k":"code","text":"aliases"},{"k":"text","text":", "},{"k":"code","text":"api_dialect"},{"k":"text","text":" (closed enum: anthropic | openai-chat | openai-responses | gemini | cohere | ai21 | bedrock | voyage | mock)"}],[{"k":"code","text":"nika/mcp-servers@1.0"},{"k":"text","text":" — MCP server aliases + trust labels"}],[{"k":"code","text":"nika/model-capabilities@1.0"},{"k":"text","text":" — 9 first-match-wins rules (Session 2a), projected to 28 (Session 2b)"}],[{"k":"code","text":"nika/builtins@1.0"},{"k":"text","text":" — builtin tool definitions + safety tags"}]]},{"k":"p","inline":[{"k":"strong","text":"`build.rs` does the heavy lifting:"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"Parse each TOML file against its schema version"}],[{"k":"text","text":"Enforce invariants: every "},{"k":"code","text":"scope.providers[i]"},{"k":"text","text":" in "},{"k":"code","text":"model-capabilities.toml"},{"k":"text","text":" must be a canonical id declared in "},{"k":"code","text":"llm-providers.toml"},{"k":"text","text":" (foreign-key check). "},{"k":"code","text":"api_dialect"},{"k":"text","text":" in rule scopes must be in the closed dialect set."}],[{"k":"text","text":"Emit static Rust arrays + "},{"k":"code","text":"phf::Map"},{"k":"text","text":" indexes into "},{"k":"code","text":"\u0024OUT_DIR"},{"k":"text","text":" for zero-runtime-cost lookup."}]]},{"k":"p","inline":[{"k":"strong","text":"Lookup strategy is hybrid"},{"k":"text","text":" (see "},{"k":"code","text":"docs/crate-specs/nika-catalog.md"},{"k":"text","text":"):"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"phf::Map"},{"k":"text","text":" + "},{"k":"code","text":"unicase"},{"k":"text","text":" for case-insensitive entities (providers, MCP aliases) — O(1)"}],[{"k":"text","text":"Sorted arrays + "},{"k":"code","text":"binary_search"},{"k":"text","text":" for case-sensitive entities (builtins, transforms) — O(log n)"}],[{"k":"text","text":"First-match-wins rule table for model capabilities — O(n) but n = 9–28"}]]},{"k":"p","inline":[{"k":"code","text":"nika-catalog-verify"},{"k":"text","text":" (L4 binary, also admitted) provides an "},{"k":"strong","text":"online verification layer"},{"k":"text","text":": fetches provider API endpoints nightly, confirms MCP aliases still respond, flags drift in CI."}]},{"k":"p","inline":[{"k":"strong","text":"Session 2a concrete additions"},{"k":"text","text":" (shipped, grep-verified):"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"data/model-capabilities.toml"},{"k":"text","text":" — 9 rules covering OpenAI o-series, GPT-5, Claude family, Anthropic catch-all, DeepSeek reasoner, DeepSeek any, xAI Grok-4"}],[{"k":"code","text":"build/capabilities.rs"},{"k":"text","text":" — 380 LOC codegen, extracted from "},{"k":"code","text":"build.rs"},{"k":"text","text":" to respect the 1,500-LOC file cap"}],[{"k":"code","text":"src/types/capabilities.rs"},{"k":"text","text":" — 276 LOC ("},{"k":"code","text":"CapPatch"},{"k":"text","text":" + "},{"k":"code","text":"Matcher"},{"k":"text","text":" + "},{"k":"code","text":"Rule"},{"k":"text","text":"), "},{"k":"code","text":"const fn merge_with"},{"k":"text","text":", "},{"k":"code","text":"fn materialize"}],[{"k":"code","text":"api_dialect"},{"k":"text","text":" field added to all 21 providers in "},{"k":"code","text":"llm-providers.toml"}],[{"k":"text","text":"16 new constructors (invariant #19 complete — see ADR-007)"}],[{"k":"text","text":"Proptest parity harness — 10,000 random (provider, model) pairs compared against frozen legacy"}],[{"k":"text","text":"Insta snapshot — 31 golden (provider, model) pairs reviewable"}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Community contributors edit TOML, not Rust. Learning curve drops to \"know YAML/TOML.\""}],[{"k":"text","text":"Build-time FK checks catch typos before they ship."}],[{"k":"text","text":"Zero runtime overhead — all data in static memory."}],[{"k":"code","text":"nika-catalog-verify"},{"k":"text","text":" catches silent rot (29-alias class) nightly."}],[{"k":"text","text":"Schema versions ("},{"k":"code","text":"nika/model-capabilities@1.0"},{"k":"text","text":") make future migrations explicit."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Build times grow with data (current: catalog build ~8s cold). Acceptable; amortized over cargo caches."}],[{"k":"strong","text":"Rule-authoring sharp edge:"},{"k":"text","text":" first-match-wins means a single rule must carry "},{"k":"strong","text":"all"},{"k":"text","text":" capabilities for a matched (provider, model) pair. Documented extensively in "},{"k":"code","text":"model-capabilities.toml"},{"k":"text","text":" header (lines 32–48). Getting this wrong silently drops capabilities."}],[{"k":"text","text":"Adding a new capability field requires running the 10k-pair proptest parity harness (~30s)."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The TOML-vs-YAML choice: TOML for code-authored config (typing explicit, no indentation fragility, comments allowed). YAML stays for Nika workflow files (user-authored DSL)."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-catalog/data/model-capabilities.toml"},{"k":"text","text":" lines 1–80 — schema, FK invariants, resolution algorithm, first-match-wins authoring note"}],[{"k":"code","text":"crates/nika-catalog/data/llm-providers.toml"},{"k":"text","text":" lines 1–50 — "},{"k":"code","text":"api_dialect"},{"k":"text","text":" on every provider"}],[{"k":"code","text":"crates/nika-catalog/build.rs"},{"k":"text","text":" lines 1–50 — build script overview"}],[{"k":"code","text":"crates/nika-catalog-codegen/src/capabilities.rs"},{"k":"text","text":" — capabilities codegen (extracted per 1,500 LOC cap ADR-004 · build/capabilities.rs twin NUKEd at the D-2026-06-10-N4 codegen WIRE)"}],[{"k":"code","text":"crates/nika-catalog/src/types/capabilities.rs"},{"k":"text","text":" — 276 LOC: "},{"k":"code","text":"CapPatch"},{"k":"text","text":", "},{"k":"code","text":"Matcher"},{"k":"text","text":", "},{"k":"code","text":"Rule"}],[{"k":"code","text":"docs/crate-specs/nika-catalog.md"},{"k":"text","text":" lines 1–60 — hybrid lookup rationale"}],[{"k":"code","text":"CHANGELOG.md"},{"k":"text","text":" — Session 2a entry \"TOML-driven model capabilities\" (Unreleased section)"}],[{"k":"text","text":"Related crates: "},{"k":"strong","text":"`nika-catalog`"},{"k":"text","text":" (L0, 4,690 LOC, 154 tests), "},{"k":"strong","text":"`nika-catalog-verify`"},{"k":"text","text":" (L4 binary, online check)"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Hardcoded Rust arrays (legacy approach)","id":"alt-a--hardcoded-rust-arrays-legacy-approach"},{"k":"p","inline":[{"k":"text","text":"Rejected. See context (contribution friction + 29-alias rot)."}]},{"k":"h","depth":3,"text":"Alt B — Runtime TOML loading (no codegen)","id":"alt-b--runtime-toml-loading-no-codegen"},{"k":"p","inline":[{"k":"text","text":"Rejected. Adds startup cost, loses compile-time FK checks, introduces a \"which TOML did we load?\" bug class."}]},{"k":"h","depth":3,"text":"Alt C — Database (sqlite) instead of TOML","id":"alt-c--database-sqlite-instead-of-toml"},{"k":"p","inline":[{"k":"text","text":"Rejected. Git-based review workflow (PR diffs, blame, history) is more valuable than query flexibility for a 21-provider catalog. sqlite reconsidered if catalog exceeds ~500 entries."}]},{"k":"h","depth":3,"text":"Alt D — JSON instead of TOML","id":"alt-d--json-instead-of-toml"},{"k":"p","inline":[{"k":"text","text":"Rejected. No comments, more fragile indentation, harder to review in diff."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-004 — context-window sizing (catalog is 4,690 LOC; "},{"k":"code","text":"build/capabilities.rs"},{"k":"text","text":" extracted to respect 1,500 LOC file cap)"}],[{"k":"text","text":"ADR-007 — forward-compat invariants (schema versions + "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" in generated types)"}],[{"k":"code","text":"docs/crate-specs/nika-catalog.md"},{"k":"text","text":" — full hybrid-lookup spec"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Session 2b (next) expands the rule table to 28 entries + 5 new ModelCapabilities fields (Modality, TokenizerFamily, ParamFlag, supports_system_messages, supports_reasoning). Session 3 adds pricing schema + 8 providers without rules + 4 new providers (qwen, minimax, moonshot, zhipu). Schema version stays "},{"k":"code","text":"@1.0"},{"k":"text","text":" — invariants #19 and #11 of "},{"k":"code","text":"forward-compat-invariants.md"},{"k":"text","text":" allow extension without version bump."}]},{"k":"h","depth":2,"text":"Implementation notes — Session 2b / Session 3","id":"implementation-notes--session-2b--session-3"},{"k":"p","inline":[{"k":"text","text":"The P0-1 \"two sources of truth\" hazard (Rust "},{"k":"code","text":"Default"},{"k":"text","text":" impl + TOML "},{"k":"code","text":"[defaults]"},{"k":"text","text":" diverging silently) is now closed by three coordinated measures:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"CapPatch::materialize(&CAPABILITY_DEFAULTS)"},{"k":"text","text":" draws every unset field from the TOML "},{"k":"code","text":"[defaults]"},{"k":"text","text":" block at resolve time. The Rust "},{"k":"code","text":"ModelCapabilities::default()"},{"k":"text","text":" impl is kept only as an internal-crate shortcut for test scaffolding and struct-literal ergonomics; it is never consulted by the resolver."}],[{"k":"text","text":"The "},{"k":"code","text":"materialize_defaults_agree_with_rust_default_impl"},{"k":"text","text":" unit test (in "},{"k":"code","text":"src/types/capabilities.rs"},{"k":"text","text":") asserts that the TOML-shaped defaults materialise into the same "},{"k":"code","text":"ModelCapabilities"},{"k":"text","text":" as the Rust "},{"k":"code","text":"Default"},{"k":"text","text":" impl — any edit to one without the other fails the test."}],[{"k":"text","text":"Session 3 Phase G tightens "},{"k":"code","text":"validate_caps_patch(&file.defaults, \"[defaults]\", require_all=true)"},{"k":"text","text":" so the "},{"k":"code","text":"[defaults]"},{"k":"text","text":" block must explicitly set every field that has an "},{"k":"code","text":"unwrap_or"},{"k":"text","text":" fallback in "},{"k":"code","text":"materialize"},{"k":"text","text":" (8 of 9 slots; "},{"k":"code","text":"tokenizer"},{"k":"text","text":" stays legitimately optional by design). The hard-coded fallbacks in "},{"k":"code","text":"materialize"},{"k":"text","text":" become structurally unreachable for any TOML that passes build-time validation; "},{"k":"code","text":"debug_assert!"},{"k":"text","text":" lines in "},{"k":"code","text":"materialize"},{"k":"text","text":" catch runtime regressions in debug mode at zero release cost."}]]},{"k":"p","inline":[{"k":"text","text":"Session 3 also retires the coarse "},{"k":"code","text":"ModelCapabilities::supports_vision: bool"},{"k":"text","text":" — consumers migrate to "},{"k":"code","text":"input_modalities.contains(&Modality::Image)"},{"k":"text","text":", which was the Session 2b replacement. The pricing catalog is extended with three "},{"k":"code","text":"Option<f64>"},{"k":"text","text":" axes (cached input, image, reasoning tokens); the full TOML-driven pricing migration (new "},{"k":"code","text":"data/model-pricing.toml"},{"k":"text","text":" + "},{"k":"code","text":"build/pricing.rs"},{"k":"text","text":") is scheduled as Phase E2 of Session 4. The \"two sources of truth\" hazard is now "},{"k":"strong","text":"scoped"},{"k":"text","text":": defaults is closed (commit 731f11bfe — "},{"k":"code","text":"require_all"},{"k":"text","text":" on "},{"k":"code","text":"[defaults]"},{"k":"text","text":" + "},{"k":"code","text":"debug_assert!"},{"k":"text","text":" in "},{"k":"code","text":"materialize"},{"k":"text","text":"); pricing closure lands with Phase E2. The Rust "},{"k":"code","text":"ALL_PRICING"},{"k":"text","text":" slice remains the only source until the TOML migration, so the hazard has no bite today."}]}]

ADR-008

TOML-driven catalog with build-time codegen and perfect-hash lookup

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

ADR-008: TOML-driven catalog with build-time codegen + perfect-hash lookup #

Context #

Nika needs to resolve a user-supplied provider: claude → canonical provider id → model → capabilities → pricing in a single YAML field. Legacy used hardcoded Rust arrays. That had two problems:

Contribution friction: adding a provider required writing Rust + rebuilding. Community contributors were blocked.
Silent rot: the Phase A audit (2026-03) discovered 29 broken MCP aliases — entries pointing at servers that no longer existed. No one noticed for months because the data lived inside compiled code.

Session 2a (2026-04-14) set the target: move all catalog data to TOML with schema validation at build time, and add a model-capabilities rule table that replaces a 900-line match cascade.

Decision #

All catalog data lives in `data/*.toml` with versioned schemas:

nika/[email protected] — 21 providers, each with canonical_id, aliases, api_dialect (closed enum: anthropic | openai-chat | openai-responses | gemini | cohere | ai21 | bedrock | voyage | mock)
nika/[email protected] — MCP server aliases + trust labels
nika/[email protected] — 9 first-match-wins rules (Session 2a), projected to 28 (Session 2b)
nika/[email protected] — builtin tool definitions + safety tags

`build.rs` does the heavy lifting:

Parse each TOML file against its schema version
Enforce invariants: every scope.providers[i] in model-capabilities.toml must be a canonical id declared in llm-providers.toml (foreign-key check). api_dialect in rule scopes must be in the closed dialect set.
Emit static Rust arrays + phf::Map indexes into $OUT_DIR for zero-runtime-cost lookup.

Lookup strategy is hybrid (see docs/crate-specs/nika-catalog.md):

phf::Map + unicase for case-insensitive entities (providers, MCP aliases) — O(1)
Sorted arrays + binary_search for case-sensitive entities (builtins, transforms) — O(log n)
First-match-wins rule table for model capabilities — O(n) but n = 9–28

nika-catalog-verify (L4 binary, also admitted) provides an online verification layer: fetches provider API endpoints nightly, confirms MCP aliases still respond, flags drift in CI.

Session 2a concrete additions (shipped, grep-verified):

data/model-capabilities.toml — 9 rules covering OpenAI o-series, GPT-5, Claude family, Anthropic catch-all, DeepSeek reasoner, DeepSeek any, xAI Grok-4
build/capabilities.rs — 380 LOC codegen, extracted from build.rs to respect the 1,500-LOC file cap
src/types/capabilities.rs — 276 LOC (CapPatch + Matcher + Rule), const fn merge_with, fn materialize
api_dialect field added to all 21 providers in llm-providers.toml
16 new constructors (invariant #19 complete — see ADR-007)
Proptest parity harness — 10,000 random (provider, model) pairs compared against frozen legacy
Insta snapshot — 31 golden (provider, model) pairs reviewable

Consequences #

Positive #

Community contributors edit TOML, not Rust. Learning curve drops to "know YAML/TOML."
Build-time FK checks catch typos before they ship.
Zero runtime overhead — all data in static memory.
nika-catalog-verify catches silent rot (29-alias class) nightly.
Schema versions (nika/[email protected]) make future migrations explicit.

Negative #

Build times grow with data (current: catalog build ~8s cold). Acceptable; amortized over cargo caches.
Rule-authoring sharp edge: first-match-wins means a single rule must carry all capabilities for a matched (provider, model) pair. Documented extensively in model-capabilities.toml header (lines 32–48). Getting this wrong silently drops capabilities.
Adding a new capability field requires running the 10k-pair proptest parity harness (~30s).

Neutral #

The TOML-vs-YAML choice: TOML for code-authored config (typing explicit, no indentation fragility, comments allowed). YAML stays for Nika workflow files (user-authored DSL).

Evidence #

crates/nika-catalog/data/model-capabilities.toml lines 1–80 — schema, FK invariants, resolution algorithm, first-match-wins authoring note
crates/nika-catalog/data/llm-providers.toml lines 1–50 — api_dialect on every provider
crates/nika-catalog/build.rs lines 1–50 — build script overview
crates/nika-catalog-codegen/src/capabilities.rs — capabilities codegen (extracted per 1,500 LOC cap ADR-004 · build/capabilities.rs twin NUKEd at the D-2026-06-10-N4 codegen WIRE)
crates/nika-catalog/src/types/capabilities.rs — 276 LOC: CapPatch, Matcher, Rule
docs/crate-specs/nika-catalog.md lines 1–60 — hybrid lookup rationale
CHANGELOG.md — Session 2a entry "TOML-driven model capabilities" (Unreleased section)
Related crates: `nika-catalog` (L0, 4,690 LOC, 154 tests), `nika-catalog-verify` (L4 binary, online check)

Alternatives considered #

Alt A — Hardcoded Rust arrays (legacy approach) #

Rejected. See context (contribution friction + 29-alias rot).

Alt B — Runtime TOML loading (no codegen) #

Rejected. Adds startup cost, loses compile-time FK checks, introduces a "which TOML did we load?" bug class.

Alt C — Database (sqlite) instead of TOML #

Rejected. Git-based review workflow (PR diffs, blame, history) is more valuable than query flexibility for a 21-provider catalog. sqlite reconsidered if catalog exceeds ~500 entries.

Alt D — JSON instead of TOML #

Rejected. No comments, more fragile indentation, harder to review in diff.

ADR-004 — context-window sizing (catalog is 4,690 LOC; build/capabilities.rs extracted to respect 1,500 LOC file cap)
ADR-007 — forward-compat invariants (schema versions + #[non_exhaustive] in generated types)
docs/crate-specs/nika-catalog.md — full hybrid-lookup spec

Notes #

Session 2b (next) expands the rule table to 28 entries + 5 new ModelCapabilities fields (Modality, TokenizerFamily, ParamFlag, supports_system_messages, supports_reasoning). Session 3 adds pricing schema + 8 providers without rules + 4 new providers (qwen, minimax, moonshot, zhipu). Schema version stays @1.0 — invariants #19 and #11 of forward-compat-invariants.md allow extension without version bump.

Implementation notes — Session 2b / Session 3 #

The P0-1 "two sources of truth" hazard (Rust Default impl + TOML [defaults] diverging silently) is now closed by three coordinated measures:

CapPatch::materialize(&CAPABILITY_DEFAULTS) draws every unset field from the TOML [defaults] block at resolve time. The Rust ModelCapabilities::default() impl is kept only as an internal-crate shortcut for test scaffolding and struct-literal ergonomics; it is never consulted by the resolver.
The materialize_defaults_agree_with_rust_default_impl unit test (in src/types/capabilities.rs) asserts that the TOML-shaped defaults materialise into the same ModelCapabilities as the Rust Default impl — any edit to one without the other fails the test.
Session 3 Phase G tightens validate_caps_patch(&file.defaults, "[defaults]", require_all=true) so the [defaults] block must explicitly set every field that has an unwrap_or fallback in materialize (8 of 9 slots; tokenizer stays legitimately optional by design). The hard-coded fallbacks in materialize become structurally unreachable for any TOML that passes build-time validation; debug_assert! lines in materialize catch runtime regressions in debug mode at zero release cost.

Session 3 also retires the coarse ModelCapabilities::supports_vision: bool — consumers migrate to input_modalities.contains(&Modality::Image), which was the Session 2b replacement. The pricing catalog is extended with three Option<f64> axes (cached input, image, reasoning tokens); the full TOML-driven pricing migration (new data/model-pricing.toml + build/pricing.rs) is scheduled as Phase E2 of Session 4. The "two sources of truth" hazard is now scoped: defaults is closed (commit 731f11bfe — require_all on [defaults] + debug_assert! in materialize); pricing closure lands with Phase E2. The Rust ALL_PRICING slice remains the only source until the TOML migration, so the hazard has no bite today.

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

Every decision, with its status This one in the repo