{"row":{"id":"ADR-022","title":"Foundation crate layout v0.81: 14 crates, publish = false, 5 renames + extracts","file":"adr-022-foundation-crate-layout-v081.md","status":"accepted","date":"2026-04-16","cites":11,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L4"],"tags":["architecture","crates","layout","publish"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-022: Foundation crate layout v0.81","id":"adr-022-foundation-crate-layout-v081"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"After multi-agent architectural review (rust-architect + web-researcher SOTA\nworkspaces + rust-pro + Explore file audit, 2026-04-16), the v0.80 foundation\nlayout (10 crate plan, 7 in workspace) is replaced by a 14-crate layout with\nstrict tier discipline, "},{"k":"code","text":"publish = false"},{"k":"text","text":" strategy, and 5 structural changes."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"h","depth":3,"text":"The 14-crate constellation","id":"the-14-crate-constellation"},{"k":"code","lang":"text","text":"L0-tier-0 (LEAVES — zero nika-* deps):\n  nika-core              [RENAME from nika-types]\n  nika-macros            [NEW proc-macro stub]\n\nL0-tier-1 (depend on tier-0):\n  nika-error             [DROP nika-types re-export facade]\n  nika-envelope          [NEW — apiVersion+Kind+Metadata+multi-doc+PckSpec]\n\nL0-tier-2 (depend on tier-0+1):\n  nika-event             [22 scoped sub-enums]\n  nika-binding-transform [NEW — 65 pure transforms extracted]\n  nika-catalog-codegen   [extract from catalog/build.rs]\n  nika-schema-ast        [NEW — Raw + Analyzed AST types]\n\nL0-tier-3:\n  nika-catalog           [internal split data/models.rs + build/]\n  nika-binding           [template engine + dispatch]\n  nika-schema            [parser + analyzer + DAG + taint + jsonsubset]\n\nL0.5:\n  nika-kernel            [40 traits, NO split forever per ADR-006-amend]\n  nika-kernel-mock\n\nL4:\n  nika-catalog-verify    [RELABEL from L0]"},{"k":"h","depth":3,"text":"`publish = false` for ALL foundation crates","id":"publish--false-for-all-foundation-crates"},{"k":"p","inline":[{"k":"text","text":"Every foundation crate (13 internal + 1 L4) carries "},{"k":"code","text":"publish = false"},{"k":"text","text":". Only\n"},{"k":"code","text":"nika"},{"k":"text","text":" (binary) and future "},{"k":"code","text":"nika-sdk"},{"k":"text","text":" ever ship to crates.io."}]},{"k":"h","depth":3,"text":"5 structural changes","id":"5-structural-changes"},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Rename `nika-types` → `nika-core`"},{"k":"text","text":" (matches helix/bevy/ra/polkadot\nconvention; "},{"k":"code","text":"nika-core@0.74.0"},{"k":"text","text":" legacy on crates.io gets yanked)"}],[{"k":"strong","text":"Extract `nika-envelope`"},{"k":"text","text":" (single highest-ROI move — shared by 9 doc kinds)"}],[{"k":"strong","text":"Drop `nika-error → nika_types::*` facade"},{"k":"text","text":" (re-export pollution gone with\n0 users)"}],[{"k":"strong","text":"Split `nika-schema` into 2"},{"k":"text","text":" ("},{"k":"code","text":"nika-schema-ast"},{"k":"text","text":" + "},{"k":"code","text":"nika-schema"},{"k":"text","text":") — circular-\ndep concern from original spec was wrong (analyzer reads raw, writes analyzed)"}],[{"k":"strong","text":"Split `nika-binding` into 2"},{"k":"text","text":" ("},{"k":"code","text":"nika-binding-transform"},{"k":"text","text":" + "},{"k":"code","text":"nika-binding"},{"k":"text","text":") —\n65 pure transforms have known 2nd consumer (verb-exec basename)"}]]},{"k":"h","depth":3,"text":"`nika-pck-manifest` MERGES into `nika-envelope`","id":"nika-pck-manifest-merges-into-nika-envelope"},{"k":"p","inline":[{"k":"text","text":"A pck manifest IS an envelope document ("},{"k":"code","text":"Envelope<PckSpec>"},{"k":"text","text":"). Eliminates 1\ncrate, conceptually cleaner."}]},{"k":"h","depth":3,"text":"`nika-catalog-verify` RELABEL L0 → L4","id":"nika-catalog-verify-relabel-l0--l4"},{"k":"p","inline":[{"k":"text","text":"Already does HTTP. Wrong layer assignment. Free fix."}]},{"k":"h","depth":3,"text":"`nika-macros` proc-macro stub now (empty)","id":"nika-macros-proc-macro-stub-now-empty"},{"k":"p","inline":[{"k":"text","text":"Per Agent 2 SOTA finding: every surveyed Rust workspace (rust-analyzer, biome,\nruff, uv, bevy, oxc) has a companion "},{"k":"code","text":"*_macros"},{"k":"text","text":" crate. Adding it later requires\nL0 shuffle; adding empty now is free insurance."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"✅ 14 crates with crystal-clear single-responsibility"}],[{"k":"text","text":"✅ Tier discipline enables "},{"k":"code","text":"cargo public-api"},{"k":"text","text":" snapshots without churn"}],[{"k":"text","text":"✅ "},{"k":"code","text":"publish = false"},{"k":"text","text":" frees rename/refactor velocity forever"}],[{"k":"text","text":"✅ Renames legitimate (no users)"}],[{"k":"text","text":"❌ ~7 commits of refactor work in Phase D (nuke + redo)"}],[{"k":"text","text":"❌ Existing nika-types imports across all admitted crates need update\n(mechanical — find/replace + cargo check)"}],[{"k":"text","text":"⚠️ The legacy "},{"k":"code","text":"crates/nika-core/"},{"k":"text","text":" excluded directory (v0.79 main-leftover)\nmust be deleted before the rename — handled in Phase D.1"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Keep nika-types"},{"k":"text","text":" (no rename) — name is weak placeholder, every other\nimprovement depends on knowing canonical name"}],[{"k":"strong","text":"Split nika-schema into 4"},{"k":"text","text":" (types + parser + analyzer + jsonsubset) —\nover-fragmented, 2 is the right number per cohesion analysis"}],[{"k":"strong","text":"Polkadot-style 14 micro-crates for nika-core"},{"k":"text","text":" (nika-id, nika-cost, ...) —\nQ2 anti-pattern, no consumer-side benefit"}],[{"k":"strong","text":"Publish all foundation crates"},{"k":"text","text":" — 0 users, no value, locks API surface\nprematurely"}]]},{"k":"h","depth":2,"text":"Reference","id":"reference"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"~/.claude/.../memory/project_foundation_v081_constellation.md"}],[{"k":"code","text":"~/.claude/.../memory/feedback_publish_false_foundation_strategy.md"}]]}]

ADR-022

Foundation crate layout v0.81: 14 crates, publish = false, 5 renames + extracts

accepted · 2026-04-16 · L0 L0.5 L4 · cites 11

ADR-022: Foundation crate layout v0.81 #

Context #

After multi-agent architectural review (rust-architect + web-researcher SOTA workspaces + rust-pro + Explore file audit, 2026-04-16), the v0.80 foundation layout (10 crate plan, 7 in workspace) is replaced by a 14-crate layout with strict tier discipline, publish = false strategy, and 5 structural changes.

Decision #

The 14-crate constellation #

text

1L0-tier-0 (LEAVES — zero nika-* deps):2  nika-core              [RENAME from nika-types]3  nika-macros            [NEW proc-macro stub]45L0-tier-1 (depend on tier-0):6  nika-error             [DROP nika-types re-export facade]7  nika-envelope          [NEW — apiVersion+Kind+Metadata+multi-doc+PckSpec]89L0-tier-2 (depend on tier-0+1):10  nika-event             [22 scoped sub-enums]11  nika-binding-transform [NEW — 65 pure transforms extracted]12  nika-catalog-codegen   [extract from catalog/build.rs]13  nika-schema-ast        [NEW — Raw + Analyzed AST types]1415L0-tier-3:16  nika-catalog           [internal split data/models.rs + build/]17  nika-binding           [template engine + dispatch]18  nika-schema            [parser + analyzer + DAG + taint + jsonsubset]1920L0.5:21  nika-kernel            [40 traits, NO split forever per ADR-006-amend]22  nika-kernel-mock2324L4:25  nika-catalog-verify    [RELABEL from L0]

`publish = false` for ALL foundation crates #

Every foundation crate (13 internal + 1 L4) carries publish = false. Only nika (binary) and future nika-sdk ever ship to crates.io.

5 structural changes #

Rename `nika-types` → `nika-core` (matches helix/bevy/ra/polkadot convention; [email protected] legacy on crates.io gets yanked)
Extract `nika-envelope` (single highest-ROI move — shared by 9 doc kinds)
Drop `nika-error → nika_types::*` facade (re-export pollution gone with 0 users)
Split `nika-schema` into 2 (nika-schema-ast + nika-schema) — circular- dep concern from original spec was wrong (analyzer reads raw, writes analyzed)
Split `nika-binding` into 2 (nika-binding-transform + nika-binding) — 65 pure transforms have known 2nd consumer (verb-exec basename)

`nika-pck-manifest` MERGES into `nika-envelope` #

A pck manifest IS an envelope document (Envelope<PckSpec>). Eliminates 1 crate, conceptually cleaner.

`nika-catalog-verify` RELABEL L0 → L4 #

Already does HTTP. Wrong layer assignment. Free fix.

`nika-macros` proc-macro stub now (empty) #

Per Agent 2 SOTA finding: every surveyed Rust workspace (rust-analyzer, biome, ruff, uv, bevy, oxc) has a companion *_macros crate. Adding it later requires L0 shuffle; adding empty now is free insurance.

Consequences #

✅ 14 crates with crystal-clear single-responsibility
✅ Tier discipline enables cargo public-api snapshots without churn
✅ publish = false frees rename/refactor velocity forever
✅ Renames legitimate (no users)
❌ ~7 commits of refactor work in Phase D (nuke + redo)
❌ Existing nika-types imports across all admitted crates need update (mechanical — find/replace + cargo check)
⚠️ The legacy crates/nika-core/ excluded directory (v0.79 main-leftover) must be deleted before the rename — handled in Phase D.1

Alternatives considered #

Keep nika-types (no rename) — name is weak placeholder, every other improvement depends on knowing canonical name
Split nika-schema into 4 (types + parser + analyzer + jsonsubset) — over-fragmented, 2 is the right number per cohesion analysis
Polkadot-style 14 micro-crates for nika-core (nika-id, nika-cost, ...) — Q2 anti-pattern, no consumer-side benefit
Publish all foundation crates — 0 users, no value, locks API surface prematurely

Reference #

~/.claude/.../memory/project_foundation_v081_constellation.md
~/.claude/.../memory/feedback_publish_false_foundation_strategy.md

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

Every decision, with its status This one in the repo