{"row":{"id":"ADR-006","title":"Layered architecture with kernel ISP atomic traits and trait_variant","file":"adr-006-layered-kernel-isp-traits.md","status":"accepted","date":"2026-04-13","cites":25,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5","L1","L2","L3","L4","L5"],"tags":["architecture","kernel","traits","isp"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-006: Layered architecture + kernel ISP atomic traits + `trait_variant`","id":"adr-006-layered-architecture--kernel-isp-atomic-traits--trait_variant"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The kernel layer defines contracts for all side effects (filesystem, HTTP, shell, memory, embeddings, tool execution, WASM host, observability). Legacy approach was coarse-grained: one large "},{"k":"code","text":"Provider"},{"k":"text","text":" trait, one "},{"k":"code","text":"Fs"},{"k":"text","text":" trait. Consumers that only needed \"read a file\" had to depend on the entire surface. "},{"k":"code","text":"async_trait"},{"k":"text","text":" was universally used, which boxes every future on the async dispatch path — measurable overhead on the inference hot path."}]},{"k":"p","inline":[{"k":"text","text":"Rust 1.91 native AFIT (async fn in trait) + "},{"k":"code","text":"trait_variant"},{"k":"text","text":" crate (v0.1) unlocked a better pattern: write the async trait once, let "},{"k":"code","text":"trait_variant::make"},{"k":"text","text":" generate a companion "},{"k":"code","text":"Dyn"},{"k":"text","text":"-suffixed trait for object-safety without boxing on the static path."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Layered architecture"},{"k":"text","text":" (strict dep direction):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Layer · Purpose · Admitted"}],[{"k":"text","text":"L0 · Primitives — error codes, catalog data, pure types · `nika-error`, `nika-catalog`"}],[{"k":"text","text":"L0.5 · Kernel — abstract side-effect traits + request/response types · `nika-kernel`, `nika-kernel-mock`"}],[{"k":"text","text":"L1 · Infrastructure — implementations of kernel traits (fs, http, providers, etc.) · pending Phase 2+"}],[{"k":"text","text":"L2 · Core runtime + DAG execution · pending Phase 2+"}],[{"k":"text","text":"L3 · Subsystems — binding, catalog overlay, policy · pending Phase 3+"}],[{"k":"text","text":"L4 · Applications — CLI, TUI, daemon, serve, LSP, verify tooling · `nika-catalog-verify` (binary)"}],[{"k":"text","text":"L5 · Full product integration · pending"}]]},{"k":"p","inline":[{"k":"text","text":"Layer-level ordering is enforced by "},{"k":"code","text":"scripts/ci/check_layers.rs"},{"k":"text","text":" pattern (see ADR-009): "},{"k":"code","text":"layer(dep) ≥ layer(crate)"},{"k":"text","text":" is verified by parsing "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" deps against a table."}]},{"k":"p","inline":[{"k":"strong","text":"Kernel trait design (L0.5)"},{"k":"text","text":":"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"~20 atomic ISP traits: "},{"k":"code","text":"FsRead"},{"k":"text","text":", "},{"k":"code","text":"FsWrite"},{"k":"text","text":", "},{"k":"code","text":"FsMeta"},{"k":"text","text":", "},{"k":"code","text":"FsList"},{"k":"text","text":", "},{"k":"code","text":"HttpGet"},{"k":"text","text":", "},{"k":"code","text":"HttpPost"},{"k":"text","text":", "},{"k":"code","text":"ShellRun"},{"k":"text","text":", "},{"k":"code","text":"ShellCancel"},{"k":"text","text":", "},{"k":"code","text":"MemoryRemember"},{"k":"text","text":", "},{"k":"code","text":"MemoryRecall"},{"k":"text","text":", "},{"k":"code","text":"MemoryForget"},{"k":"text","text":", "},{"k":"code","text":"ProviderInfer"},{"k":"text","text":", "},{"k":"code","text":"ProviderStream"},{"k":"text","text":", "},{"k":"code","text":"ProviderMeta"},{"k":"text","text":", "},{"k":"code","text":"ProviderEmbed"},{"k":"text","text":" (optional), "},{"k":"code","text":"ProviderVision"},{"k":"text","text":" (optional), "},{"k":"code","text":"ToolExecutor"},{"k":"text","text":", "},{"k":"code","text":"WasmPluginHost"},{"k":"text","text":", "},{"k":"code","text":"ObservabilitySink"},{"k":"text","text":", "},{"k":"code","text":"Clock"},{"k":"text","text":" (sync by design)."}],[{"k":"text","text":"Grouped into ~6 super-traits via blanket impls: "},{"k":"code","text":"Fs"},{"k":"text","text":", "},{"k":"code","text":"HttpClient"},{"k":"text","text":", "},{"k":"code","text":"ShellExecutor"},{"k":"text","text":", "},{"k":"code","text":"MemoryStore"},{"k":"text","text":", "},{"k":"code","text":"Provider"},{"k":"text","text":"."}],[{"k":"text","text":"All async traits use "},{"k":"code","text":"#[trait_variant::make(Send)]"},{"k":"text","text":" — native Rust 1.91 AFIT on static path, "},{"k":"code","text":"Dyn"},{"k":"text","text":"-suffixed companion trait for object safety."}],[{"k":"code","text":"BTreeMap"},{"k":"text","text":" preferred over "},{"k":"code","text":"HashMap"},{"k":"text","text":" in kernel types for deterministic iteration (tests are reproducible)."}],[{"k":"text","text":"Cancel tokens passed as function parameters, not embedded in request structs (keeps structs runtime-agnostic)."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"A context loader that only reads files imports "},{"k":"code","text":"FsRead"},{"k":"text","text":" alone — compiler enforces minimum surface."}],[{"k":"text","text":"Zero boxing on the hot inference path (static dispatch via native AFIT)."}],[{"k":"text","text":"Test hermeticity is structural: every I/O path is behind a trait, so "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" substitutes with zero network/disk. "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" 99 tests + "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" 88 tests exercise this fully."}],[{"k":"text","text":"Adding a new side effect = new atomic trait, no impact on existing ones."}],[{"k":"code","text":"Provider"},{"k":"text","text":" mandatory-vs-optional split ("},{"k":"code","text":"ProviderInfer + ProviderStream + ProviderMeta"},{"k":"text","text":" mandatory; "},{"k":"code","text":"ProviderEmbed + ProviderVision"},{"k":"text","text":" optional) lets lightweight providers (e.g., mock) implement only what they support."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"trait_variant"},{"k":"text","text":" generates a pair of traits per async trait, doubling the documented API surface — ~40 traits visible to "},{"k":"code","text":"cargo doc"},{"k":"text","text":" from ~20 source definitions."}],[{"k":"text","text":"Caller ergonomics: implementing Provider requires 3 trait impls minimum ("},{"k":"code","text":"Infer + Stream + Meta"},{"k":"text","text":"). Mitigated by default methods where possible."}],[{"k":"code","text":"BTreeMap"},{"k":"text","text":" perf in ultra-hot loops is slightly worse than "},{"k":"code","text":"FxHashMap"},{"k":"text","text":"; kernel isn't a hot loop, so acceptable."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"Clock"},{"k":"text","text":" sync-only is explicit YAGNI. Revisit if proven wrong."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-kernel/src/lib.rs"},{"k":"text","text":" lines 19–34 — trait hierarchy docstring + re-export list"}],[{"k":"code","text":"crates/nika-kernel-ai/src/memory.rs"},{"k":"text","text":" lines 272–305 — "},{"k":"code","text":"MemoryRemember"},{"k":"text","text":", "},{"k":"code","text":"MemoryRecall"},{"k":"text","text":", "},{"k":"code","text":"MemoryForget"},{"k":"text","text":" + blanket "},{"k":"code","text":"MemoryStore"},{"k":"text","text":" + "},{"k":"code","text":"EmbeddingProvider"},{"k":"text","text":" with "},{"k":"code","text":"#[trait_variant::make(Send)]"}],[{"k":"code","text":"crates/nika-kernel-ai/src/provider.rs"},{"k":"text","text":" — "},{"k":"code","text":"InferRequest"},{"k":"text","text":"/"},{"k":"code","text":"InferResponse"},{"k":"text","text":" with reserved "},{"k":"code","text":"Option<MemoryDirective>"},{"k":"text","text":" field (see ADR-007)"}],[{"k":"code","text":"CHANGELOG.md"},{"k":"text","text":" lines 169–215 — "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" admission, key decisions listed, commit "},{"k":"code","text":"ef8804371"}],[{"k":"text","text":"Related crates: "},{"k":"strong","text":"`nika-kernel`"},{"k":"text","text":" (L0.5 traits), "},{"k":"strong","text":"`nika-kernel-mock`"},{"k":"text","text":" (L0.5 test mock)"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Coarse-grained traits (`Fs`, `Provider` mega-traits only)","id":"alt-a--coarse-grained-traits-fs-provider-mega-traits-only"},{"k":"p","inline":[{"k":"text","text":"Rejected: re-creates the legacy problem where consumers over-depend."}]},{"k":"h","depth":3,"text":"Alt B — `async_trait` everywhere (boxed futures)","id":"alt-b--async_trait-everywhere-boxed-futures"},{"k":"p","inline":[{"k":"text","text":"Rejected: measured ~100ns per call overhead; multiplied across a DAG with 100+ nodes becomes visible. Native AFIT is free."}]},{"k":"h","depth":3,"text":"Alt C — No super-traits, only atomic traits","id":"alt-c--no-super-traits-only-atomic-traits"},{"k":"p","inline":[{"k":"text","text":"Rejected: 20 atomic trait bounds is unergonomic for consumers that genuinely need most of Fs/Provider. Blanket "},{"k":"code","text":"Fs: FsRead + FsWrite + FsMeta + FsList"},{"k":"text","text":" gives the best of both."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-003 — 12-gate admission (kernel admission went through all 12)"}],[{"k":"text","text":"ADR-004 — context-window sizing (kernel + kernel-mock together are 5,080 LOC)"}],[{"k":"text","text":"ADR-007 — forward-compat invariants (kernel pre-plants "},{"k":"code","text":"MemoryStore"},{"k":"text","text":", "},{"k":"code","text":"ToolExecutor"},{"k":"text","text":" traits for v0.95 Cortex and v0.100 agent-v2 without touching kernel later)"}],[{"k":"text","text":"ADR-012 — typestate runtime (consumes the kernel via "},{"k":"code","text":"bind_kernel(&dyn Kernel)"},{"k":"text","text":")"}],[{"k":"text","text":"ADR-013 — Loom concurrency verification (validates trait "},{"k":"em","text":"impls"},{"k":"text","text":" of the contracts this ADR defines)"}],[{"k":"text","text":"ADR-014 — sealed kernel traits (locks the trait surface this ADR introduced behind a "},{"k":"code","text":"Sealed"},{"k":"text","text":" super-trait)"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Rust 1.91 "},{"k":"code","text":"trait_variant"},{"k":"text","text":" is still v0.1.x. Keep version-pinned. Re-evaluate when the crate reaches v1.0 or if stdlib absorbs the pattern."}]},{"k":"h","depth":2,"text":"Amendment 2026-04-16 — Kernel stays monolithic forever","id":"amendment-2026-04-16--kernel-stays-monolithic-forever"},{"k":"p","inline":[{"k":"text","text":"The original ADR-006 reserved a future split into 4 sibling crates\n("},{"k":"code","text":"nika-kernel-{core,ai,runtime,plugin}"},{"k":"text","text":") when LOC > 10k OR pub trait count"}]},{"k":"quote","inline":[]},{"k":"p","inline":[{"k":"code","text":"nika-kernel"},{"k":"text","text":" stays as ONE crate forever, with 5 internal group modules\n("},{"k":"code","text":"io/"},{"k":"text","text":", "},{"k":"code","text":"ai/"},{"k":"text","text":", "},{"k":"code","text":"runtime/"},{"k":"text","text":", "},{"k":"code","text":"plugin/"},{"k":"text","text":", "},{"k":"code","text":"infra/"},{"k":"text","text":") that already provide the\nlogical separation. Real Rust workspaces (rust-analyzer, helix, oxc, biome,\nruff, uv, bevy, tokio) keep their kernel-equivalents monolithic; only\npolkadot-sdk splits and that's blockchain-feature-gated. Splitting would force\n"},{"k":"code","text":"use nika_kernel_ai::Provider; use nika_kernel_core::Clock;"},{"k":"text","text":" everywhere — worse\nDX. The Q7 prelude hub (added 2026-04-16) depends on kernel being whole."}]},{"k":"p","inline":[{"k":"strong","text":"Trigger to revisit (both must hold):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"kernel exceeds 15k LOC, AND"}],[{"k":"text","text":"2+ active sub-domains being modified independently in same session for 3+\nconsecutive sessions"}]]},{"k":"p","inline":[{"k":"text","text":"Reserved crate names (nika-kernel-core/ai/runtime/plugin) freed."}]},{"k":"p","inline":[{"k":"text","text":"See "},{"k":"code","text":"~/.claude/.../memory/feedback_kernel_monolithic_forever.md"},{"k":"text","text":" for the full\nrationale + agent evidence."}]},{"k":"p","inline":[{"k":"text","text":"Status of original split-trigger: "},{"k":"strong","text":"superseded by this amendment."}]}]

ADR-006

Layered architecture with kernel ISP atomic traits and trait_variant

accepted · 2026-04-13 · L0 L0.5 L1 L2 L3 L4 L5 · cites 25

ADR-006: Layered architecture + kernel ISP atomic traits + `trait_variant` #

Context #

The kernel layer defines contracts for all side effects (filesystem, HTTP, shell, memory, embeddings, tool execution, WASM host, observability). Legacy approach was coarse-grained: one large Provider trait, one Fs trait. Consumers that only needed "read a file" had to depend on the entire surface. async_trait was universally used, which boxes every future on the async dispatch path — measurable overhead on the inference hot path.

Rust 1.91 native AFIT (async fn in trait) + trait_variant crate (v0.1) unlocked a better pattern: write the async trait once, let trait_variant::make generate a companion Dyn-suffixed trait for object-safety without boxing on the static path.

Decision #

Layered architecture (strict dep direction):

Layer · Purpose · Admitted
L0 · Primitives — error codes, catalog data, pure types · `nika-error`, `nika-catalog`
L0.5 · Kernel — abstract side-effect traits + request/response types · `nika-kernel`, `nika-kernel-mock`
L1 · Infrastructure — implementations of kernel traits (fs, http, providers, etc.) · pending Phase 2+
L2 · Core runtime + DAG execution · pending Phase 2+
L3 · Subsystems — binding, catalog overlay, policy · pending Phase 3+
L4 · Applications — CLI, TUI, daemon, serve, LSP, verify tooling · `nika-catalog-verify` (binary)
L5 · Full product integration · pending

Layer-level ordering is enforced by scripts/ci/check_layers.rs pattern (see ADR-009): layer(dep) ≥ layer(crate) is verified by parsing Cargo.toml deps against a table.

Kernel trait design (L0.5):

~20 atomic ISP traits: FsRead, FsWrite, FsMeta, FsList, HttpGet, HttpPost, ShellRun, ShellCancel, MemoryRemember, MemoryRecall, MemoryForget, ProviderInfer, ProviderStream, ProviderMeta, ProviderEmbed (optional), ProviderVision (optional), ToolExecutor, WasmPluginHost, ObservabilitySink, Clock (sync by design).
Grouped into ~6 super-traits via blanket impls: Fs, HttpClient, ShellExecutor, MemoryStore, Provider.
All async traits use #[trait_variant::make(Send)] — native Rust 1.91 AFIT on static path, Dyn-suffixed companion trait for object safety.
BTreeMap preferred over HashMap in kernel types for deterministic iteration (tests are reproducible).
Cancel tokens passed as function parameters, not embedded in request structs (keeps structs runtime-agnostic).

Consequences #

Positive #

A context loader that only reads files imports FsRead alone — compiler enforces minimum surface.
Zero boxing on the hot inference path (static dispatch via native AFIT).
Test hermeticity is structural: every I/O path is behind a trait, so nika-kernel-mock substitutes with zero network/disk. nika-kernel 99 tests + nika-kernel-mock 88 tests exercise this fully.
Adding a new side effect = new atomic trait, no impact on existing ones.
Provider mandatory-vs-optional split (ProviderInfer + ProviderStream + ProviderMeta mandatory; ProviderEmbed + ProviderVision optional) lets lightweight providers (e.g., mock) implement only what they support.

Negative #

trait_variant generates a pair of traits per async trait, doubling the documented API surface — ~40 traits visible to cargo doc from ~20 source definitions.
Caller ergonomics: implementing Provider requires 3 trait impls minimum (Infer + Stream + Meta). Mitigated by default methods where possible.
BTreeMap perf in ultra-hot loops is slightly worse than FxHashMap; kernel isn't a hot loop, so acceptable.

Neutral #

Clock sync-only is explicit YAGNI. Revisit if proven wrong.

Evidence #

crates/nika-kernel/src/lib.rs lines 19–34 — trait hierarchy docstring + re-export list
crates/nika-kernel-ai/src/memory.rs lines 272–305 — MemoryRemember, MemoryRecall, MemoryForget + blanket MemoryStore + EmbeddingProvider with #[trait_variant::make(Send)]
crates/nika-kernel-ai/src/provider.rs — InferRequest/InferResponse with reserved Option<MemoryDirective> field (see ADR-007)
CHANGELOG.md lines 169–215 — nika-kernel admission, key decisions listed, commit ef8804371
Related crates: `nika-kernel` (L0.5 traits), `nika-kernel-mock` (L0.5 test mock)

Alternatives considered #

Alt A — Coarse-grained traits (`Fs`, `Provider` mega-traits only) #

Rejected: re-creates the legacy problem where consumers over-depend.

Alt B — `async_trait` everywhere (boxed futures) #

Rejected: measured ~100ns per call overhead; multiplied across a DAG with 100+ nodes becomes visible. Native AFIT is free.

Alt C — No super-traits, only atomic traits #

Rejected: 20 atomic trait bounds is unergonomic for consumers that genuinely need most of Fs/Provider. Blanket Fs: FsRead + FsWrite + FsMeta + FsList gives the best of both.

ADR-003 — 12-gate admission (kernel admission went through all 12)
ADR-004 — context-window sizing (kernel + kernel-mock together are 5,080 LOC)
ADR-007 — forward-compat invariants (kernel pre-plants MemoryStore, ToolExecutor traits for v0.95 Cortex and v0.100 agent-v2 without touching kernel later)
ADR-012 — typestate runtime (consumes the kernel via bind_kernel(&dyn Kernel))
ADR-013 — Loom concurrency verification (validates trait impls of the contracts this ADR defines)
ADR-014 — sealed kernel traits (locks the trait surface this ADR introduced behind a Sealed super-trait)

Notes #

Rust 1.91 trait_variant is still v0.1.x. Keep version-pinned. Re-evaluate when the crate reaches v1.0 or if stdlib absorbs the pattern.

Amendment 2026-04-16 — Kernel stays monolithic forever #

The original ADR-006 reserved a future split into 4 sibling crates (nika-kernel-{core,ai,runtime,plugin}) when LOC > 10k OR pub trait count

nika-kernel stays as ONE crate forever, with 5 internal group modules (io/, ai/, runtime/, plugin/, infra/) that already provide the logical separation. Real Rust workspaces (rust-analyzer, helix, oxc, biome, ruff, uv, bevy, tokio) keep their kernel-equivalents monolithic; only polkadot-sdk splits and that's blockchain-feature-gated. Splitting would force use nika_kernel_ai::Provider; use nika_kernel_core::Clock; everywhere — worse DX. The Q7 prelude hub (added 2026-04-16) depends on kernel being whole.

Trigger to revisit (both must hold):

kernel exceeds 15k LOC, AND
2+ active sub-domains being modified independently in same session for 3+ consecutive sessions

Reserved crate names (nika-kernel-core/ai/runtime/plugin) freed.

See ~/.claude/.../memory/feedback_kernel_monolithic_forever.md for the full rationale + agent evidence.

Status of original split-trigger: superseded by this amendment.

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

Every decision, with its status This one in the repo