{"row":{"id":"ADR-027","title":"Strict L0 sublayer tiers + max 3 sibling deps + cargo timings per-crate budget","file":"adr-027-strict-l0-tiers-cargo-timings.md","status":"accepted","date":"2026-04-16","cites":6,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5"],"tags":["architecture","tiers","cargo-timings","compile-budget"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-027: Strict L0 sublayer tiers + cargo timings budget","id":"adr-027-strict-l0-sublayer-tiers--cargo-timings-budget"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"ADR-022 lays out 14 foundation crates. Without internal discipline, L0 risks\nbecoming a flat bag of crates with arbitrary cross-dependencies. We want the\nstrongest possible compile DAG."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"h","depth":3,"text":"Internal L0 tiers (sublayer discipline)","id":"internal-l0-tiers-sublayer-discipline"},{"k":"p","inline":[{"k":"text","text":"L0 has 4 internal tiers, strict downward-only:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Tier · Constraint · Crates"}],[{"k":"text","text":"**L0-tier-0** · LEAF — zero `nika-*` deps · `nika-core`, `nika-macros`"}],[{"k":"text","text":"**L0-tier-1** · depends on tier-0 only · `nika-error`, `nika-envelope`"}],[{"k":"text","text":"**L0-tier-2** · depends on tier-0+1, single domain · `nika-event`, `nika-binding-transform`, `nika-catalog-codegen`, `nika-schema-ast`"}],[{"k":"text","text":"**L0-tier-3** · depends on lower L0 tiers · `nika-catalog`, `nika-binding`, `nika-schema`"}]]},{"k":"h","depth":3,"text":"Hard rule: max 3 sibling L0 deps per L0 crate","id":"hard-rule-max-3-sibling-l0-deps-per-l0-crate"},{"k":"p","inline":[{"k":"text","text":"Hygiene vector 28 ("},{"k":"code","text":"check-l0-dep-fanout.sh"},{"k":"text","text":") reads "},{"k":"code","text":"docs/workspace.toml"},{"k":"text","text":" and\nasserts every L0 crate's "},{"k":"code","text":"sibling_deps"},{"k":"text","text":" array length ≤ 3."}]},{"k":"p","inline":[{"k":"code","text":"nika-schema"},{"k":"text","text":" is at the limit (4 deps including "},{"k":"code","text":"nika-catalog"},{"k":"text","text":"); admission\nspec must justify each dep."}]},{"k":"h","depth":3,"text":"`cargo timings` per-crate budget (vector 29)","id":"cargo-timings-per-crate-budget-vector-29"},{"k":"p","inline":[{"k":"text","text":"Each crate has "},{"k":"code","text":"compile_budget_secs"},{"k":"text","text":" in "},{"k":"code","text":"docs/workspace.toml"},{"k":"text","text":":"}]},{"k":"code","lang":"toml","text":"[crates.nika-core]\ncompile_budget_secs = 10\n[crates.nika-schema]\ncompile_budget_secs = 30"},{"k":"p","inline":[{"k":"text","text":"Hygiene vector 29 ("},{"k":"code","text":"check-cargo-timings.sh"},{"k":"text","text":") runs "},{"k":"code","text":"cargo build --timings"},{"k":"text","text":" and\nasserts no crate exceeds budget. CI ratchet — regression caught at PR time."}]},{"k":"h","depth":3,"text":"`cargo deny check duplicates` strict (vector 31)","id":"cargo-deny-check-duplicates-strict-vector-31"},{"k":"p","inline":[{"k":"code","text":"deny.toml"},{"k":"text","text":" configured to forbid duplicate crate versions in "},{"k":"code","text":"Cargo.lock"},{"k":"text","text":".\nSingle-version policy across the workspace."}]},{"k":"h","depth":3,"text":"`cargo doc --document-private-items` clean (vector 32)","id":"cargo-doc---document-private-items-clean-vector-32"},{"k":"p","inline":[{"k":"text","text":"Internal API documented with same rigor as public. No undocumented private\nitems."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ Maximum compile parallelism (independent tier-0 + tier-1 crates compile\nconcurrently)"}],[{"k":"text","text":"✅ Forward-compat: adding a tier-4 means promoting one tier-3 first —\nconscious decision"}],[{"k":"text","text":"✅ Predictable crate placement (mechanical sort test extends to internal\ntiers)"}],[{"k":"text","text":"✅ "},{"k":"code","text":"cargo timings"},{"k":"text","text":" budget catches O(n²) trait-resolution regressions early"}],[{"k":"text","text":"✅ "},{"k":"code","text":"cargo deny duplicates"},{"k":"text","text":" prevents "},{"k":"code","text":"tokio-util 0.7"},{"k":"text","text":" + "},{"k":"code","text":"tokio-util 0.8"},{"k":"text","text":"\necosystem split"}],[{"k":"text","text":"❌ +5 hygiene vectors (28, 29, 30, 31, 32) — implementation cost ~4h"}],[{"k":"text","text":"❌ Initial baseline: 14 "},{"k":"code","text":"cargo timings"},{"k":"text","text":" measurements committed to\n"},{"k":"code","text":"docs/api-baselines/timings/<crate>.toml"}]]},{"k":"h","depth":2,"text":"Vector summary (Phase B + E adds)","id":"vector-summary-phase-b--e-adds"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"# · Name · Tier · Mode · Source ADR"}],[{"k":"text","text":"22 · check-no-async-in-l0 · P1 · full · (planned, PRE-DIAMOND)"}],[{"k":"text","text":"23 · check-workflow-envelope · P0 · fast · ADR-021→082"}],[{"k":"text","text":"24 · check-model-format · P0 · fast · ADR-021→082"}],[{"k":"text","text":"25 · check-kind-closed-set · P0 · fast · ADR-021→082"}],[{"k":"text","text":"26 · check-status-claims-sync · P1 · fast · (this session)"}],[{"k":"text","text":"27 · check-file-loc · P1 · full · ADR-023"}],[{"k":"text","text":"28 · check-l0-dep-fanout · P0 · fast · ADR-027"}],[{"k":"text","text":"29 · check-cargo-timings · P2 · full · ADR-027"}],[{"k":"text","text":"30 · check-public-api-baseline · P1 · full · ADR-024"}],[{"k":"text","text":"31 · check-cargo-deny-duplicates · P1 · full · ADR-027"}],[{"k":"text","text":"32 · check-cargo-doc-private · P2 · full · ADR-027"}],[{"k":"text","text":"33 · check-workspace-toml-sync · P0 · fast · ADR-026"}]]},{"k":"p","inline":[{"k":"text","text":"Total deployed at v0.81: "},{"k":"strong","text":"21 (current) + 12 (new) = 33 vectors"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Reference","id":"reference"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-022 (14-crate layout)"}],[{"k":"text","text":"ADR-026 (workspace.toml SSOT — provides metadata for vectors 28+29)"}],[{"k":"code","text":"~/.claude/.../memory/feedback_l0_strict_sublayer_tiers.md"}]]}]

ADR-027

Strict L0 sublayer tiers + max 3 sibling deps + cargo timings per-crate budget

accepted · 2026-04-16 · L0 L0.5 · cites 6

ADR-027: Strict L0 sublayer tiers + cargo timings budget #

Context #

ADR-022 lays out 14 foundation crates. Without internal discipline, L0 risks becoming a flat bag of crates with arbitrary cross-dependencies. We want the strongest possible compile DAG.

Decision #

Internal L0 tiers (sublayer discipline) #

L0 has 4 internal tiers, strict downward-only:

Tier · Constraint · Crates
**L0-tier-0** · LEAF — zero `nika-*` deps · `nika-core`, `nika-macros`
**L0-tier-1** · depends on tier-0 only · `nika-error`, `nika-envelope`
**L0-tier-2** · depends on tier-0+1, single domain · `nika-event`, `nika-binding-transform`, `nika-catalog-codegen`, `nika-schema-ast`
**L0-tier-3** · depends on lower L0 tiers · `nika-catalog`, `nika-binding`, `nika-schema`

Hard rule: max 3 sibling L0 deps per L0 crate #

Hygiene vector 28 (check-l0-dep-fanout.sh) reads docs/workspace.toml and asserts every L0 crate's sibling_deps array length ≤ 3.

nika-schema is at the limit (4 deps including nika-catalog); admission spec must justify each dep.

`cargo timings` per-crate budget (vector 29) #

Each crate has compile_budget_secs in docs/workspace.toml:

toml

1[crates.nika-core]2compile_budget_secs = 103[crates.nika-schema]4compile_budget_secs = 30

Hygiene vector 29 (check-cargo-timings.sh) runs cargo build --timings and asserts no crate exceeds budget. CI ratchet — regression caught at PR time.

`cargo deny check duplicates` strict (vector 31) #

deny.toml configured to forbid duplicate crate versions in Cargo.lock. Single-version policy across the workspace.

`cargo doc --document-private-items` clean (vector 32) #

Internal API documented with same rigor as public. No undocumented private items.

Consequences #

✅ Maximum compile parallelism (independent tier-0 + tier-1 crates compile concurrently)
✅ Forward-compat: adding a tier-4 means promoting one tier-3 first — conscious decision
✅ Predictable crate placement (mechanical sort test extends to internal tiers)
✅ cargo timings budget catches O(n²) trait-resolution regressions early
✅ cargo deny duplicates prevents tokio-util 0.7 + tokio-util 0.8 ecosystem split
❌ +5 hygiene vectors (28, 29, 30, 31, 32) — implementation cost ~4h
❌ Initial baseline: 14 cargo timings measurements committed to docs/api-baselines/timings/<crate>.toml

Vector summary (Phase B + E adds) #

# · Name · Tier · Mode · Source ADR
22 · check-no-async-in-l0 · P1 · full · (planned, PRE-DIAMOND)
23 · check-workflow-envelope · P0 · fast · ADR-021→082
24 · check-model-format · P0 · fast · ADR-021→082
25 · check-kind-closed-set · P0 · fast · ADR-021→082
26 · check-status-claims-sync · P1 · fast · (this session)
27 · check-file-loc · P1 · full · ADR-023
28 · check-l0-dep-fanout · P0 · fast · ADR-027
29 · check-cargo-timings · P2 · full · ADR-027
30 · check-public-api-baseline · P1 · full · ADR-024
31 · check-cargo-deny-duplicates · P1 · full · ADR-027
32 · check-cargo-doc-private · P2 · full · ADR-027
33 · check-workspace-toml-sync · P0 · fast · ADR-026

Total deployed at v0.81: 21 (current) + 12 (new) = 33 vectors.

Reference #

ADR-022 (14-crate layout)
ADR-026 (workspace.toml SSOT — provides metadata for vectors 28+29)
~/.claude/.../memory/feedback_l0_strict_sublayer_tiers.md

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

Every decision, with its status This one in the repo