{"row":{"id":"ADR-028","title":"Forward-compat API-type reservation (amended — feature scheduling dropped)","file":"adr-028-forward-compat-reservation-policy.md","status":"accepted","date":"2026-04-16","cites":14,"supersedes":[],"superseded_by":[],"layers":["L0","L0.5"],"tags":["forward-compat","reservation","seams","yagni"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-028: Forward-compat reservation policy — seams now, crates later","id":"adr-028-forward-compat-reservation-policy--seams-now-crates-later"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The swarm-3 SOTA audit (rust-architect + rust-pro + web-researcher, 2026-04-16,\nHEAD "},{"k":"code","text":"5e810a94a"},{"k":"text","text":") closed a recurring strategic question:"}]},{"k":"quote","inline":[{"k":"em","text":"\"Puisqu'on refait Nika from scratch, est-ce con de différer Cortex memory à v0.95\net WASM plugin à v0.100 ? Faut-il tout planifier dès v0.90 ?\""}]},{"k":"p","inline":[{"k":"text","text":"The temptation is real: if every crate is rewritten clean, why not fully bake the\nv0.95 Cortex orchestrator ("},{"k":"code","text":"nika-memory"},{"k":"text","text":" + 8 satellites) and v0.100 WASM plugin\nhost ("},{"k":"code","text":"nika-wasm-host"},{"k":"text","text":" + "},{"k":"code","text":"nika-sandbox"},{"k":"text","text":") right now, so nothing ever needs to\nchange? This ADR closes the question."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Two-tier forward-compat policy. Seams are mandatory at v0.90; crate\nimplementations are deferable to their named v-target."}]},{"k":"h","depth":3,"text":"Tier 1 — SEAMS (mandatory, ship at v0.90)","id":"tier-1--seams-mandatory-ship-at-v090"},{"k":"p","inline":[{"k":"text","text":"A "},{"k":"em","text":"seam"},{"k":"text","text":" is the smallest API surface that fixes the shape of a future feature\nwithout committing to its implementation. Seams must land before v0.90:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Seam mechanism · Where in Nika today"}],[{"k":"text","text":"`#[non_exhaustive]` on every public enum + struct · All L0 + L0.5 crates (INV-019, ADR-007)"}],[{"k":"text","text":"Reserved trait stubs in kernel (`MemoryStore`, `WasmPluginHost`, `Sandbox`, `EmbeddingProvider`, `ToolExecutor`, `ObservabilitySink`) · `crates/nika-kernel/src/` (Wave 2 S1-B)"}],[{"k":"text","text":"Reserved sub-enums in event log (`EventKind::Memory` v0.95, `EventKind::Plugin` + `Wasm` v0.100) · Q4 + Q6 of `l0-l05-architecture-decisions.md`"}],[{"k":"text","text":"Reserved fields on Infer{Request,Response} + MemoryFrame · Wave 2 S1-B + S1-C"}],[{"k":"text","text":"`pub fn new()` constructors blocking struct-literal syntax · Every `#[non_exhaustive]` struct (Q-pattern)"}],[{"k":"text","text":"`Extension { ns, name, payload }` escape hatch on `EventKind` · Q6 (Pattern B sub-enums)"}]]},{"k":"p","inline":[{"k":"text","text":"Seams are "},{"k":"strong","text":"cheap to add now, ruinous to retrofit later"},{"k":"text","text":" (Hyrum's Law: every\nobservable behaviour gets depended on). They cost a few lines of "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":"\nand "},{"k":"code","text":"Reserved { version }"},{"k":"text","text":" placeholders. Their absence creates breaking changes\nat every v-tick."}]},{"k":"h","depth":3,"text":"Tier 2 — CRATE IMPLEMENTATIONS (deferable to named v-target)","id":"tier-2--crate-implementations-deferable-to-named-v-target"},{"k":"p","inline":[{"k":"text","text":"A "},{"k":"em","text":"crate implementation"},{"k":"text","text":" is the actual code that satisfies a seam. Crate\nimplementations are deferred until at least one of:"}]},{"k":"list","ordered":true,"items":[[{"k":"text","text":"A user signal demands the feature (real workflow, not speculation)."}],[{"k":"text","text":"The upstream design space stabilises (e.g. WASM Component Model Preview 3)."}],[{"k":"text","text":"A sibling Diamond crate would benefit immediately (≥2 consumers, Q2 rule)."}]]},{"k":"p","inline":[{"k":"text","text":"Specific deferrals locked by this ADR:"}]},{"k":"h","depth":4,"text":"v0.95 Cortex memory — KEEP-DEFER","id":"v095-cortex-memory--keep-defer"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Seams already shipped: "},{"k":"code","text":"MemoryStore"},{"k":"text","text":", "},{"k":"code","text":"EmbeddingProvider"},{"k":"text","text":", "},{"k":"code","text":"MemoryDirective"},{"k":"text","text":"\non "},{"k":"code","text":"InferRequest"},{"k":"text","text":", "},{"k":"code","text":"MemoryFrameRef"},{"k":"text","text":" on "},{"k":"code","text":"InferResponse"},{"k":"text","text":", "},{"k":"code","text":"EventKind::Memory"},{"k":"text","text":"\nreserved sub-enum."}],[{"k":"text","text":"Crates deferred: "},{"k":"code","text":"nika-memory"},{"k":"text","text":" (L2 orchestrator) + 8 satellites\n("},{"k":"code","text":"nika-memory-{hnsw,bm25,rrf,fsrs,rdfs-reasoner,temporal,graph-algos,autodesc}"},{"k":"text","text":")."}],[{"k":"text","text":"Rationale: 8 stub crates × 15k LOC budget each = ~120k LOC of empty hulls\nwith zero user signal. "},{"k":"code","text":"fsrs"},{"k":"text","text":" (forgetting curve) and "},{"k":"code","text":"rdfs-reasoner"},{"k":"text","text":" design\nspaces are open in 2026 — premature freeze guarantees a v0.95 refactor."}],[{"k":"text","text":"v0.90 deliverable: 2-3 property tests proving "},{"k":"code","text":"MemoryStore"},{"k":"text","text":" can host a\nrealistic HNSW backend (no implementation, just the trait shape proof)."}]]},{"k":"h","depth":4,"text":"v0.100 WASM plugin host — KEEP-DEFER","id":"v0100-wasm-plugin-host--keep-defer"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Seams already shipped: "},{"k":"code","text":"WasmPluginHost"},{"k":"text","text":", "},{"k":"code","text":"Sandbox"},{"k":"text","text":", "},{"k":"code","text":"EventKind::Plugin"},{"k":"text","text":" +\n"},{"k":"code","text":"Wasm"},{"k":"text","text":" reserved."}],[{"k":"text","text":"Crates deferred: "},{"k":"code","text":"nika-wasm-host"},{"k":"text","text":" + "},{"k":"code","text":"nika-sandbox"},{"k":"text","text":" (L3)."}],[{"k":"text","text":"Rationale: WebAssembly Component Model Preview 3 (async, streams) is still\nin flux upstream as of 2026-04. wasmtime tracks; wasmer + wasmi lag. Stubbing\nbefore Preview 3 stabilises = rebreak guaranteed."}],[{"k":"text","text":"Escape hatch: if a user demands plugins before v0.100, a Lua/Starlark/wasmi\nL1 crate ships under "},{"k":"code","text":"unstable-*"},{"k":"text","text":" (FCI-007 distribution flag)."}]]},{"k":"h","depth":3,"text":"What \"tout v0.100\" actually means","id":"what-tout-v0100-actually-means"},{"k":"p","inline":[{"k":"text","text":"The user proposal — \"since we rewrite from scratch, plan everything for v0.100\" —\nis "},{"k":"strong","text":"half right"},{"k":"text","text":": every "},{"k":"em","text":"seam"},{"k":"text","text":" must be planned for v0.100 (already done). But\n"},{"k":"em","text":"implementations"},{"k":"text","text":" follow YAGNI (Beck) + premature-abstraction caution (Metz):\nabstraction without ≥3 concrete usages is debt, not investment."}]},{"k":"h","depth":2,"text":"SOTA evidence (cross-project survey, swarm-3)","id":"sota-evidence-cross-project-survey-swarm-3"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Project · Future-feature pattern · Lesson"}],[{"k":"text","text":"Bevy (ECS, ~50 crates) · No reservation; deliberate breakage every 3 months. · \"Break early, break often\" — community accepts. Not Nika's contract (stable forward-compat · real semver toward 1.0 per ADR-002 · amended D-2026-06-20-N1)."}],[{"k":"text","text":"tokio (~10 crates) · `#[non_exhaustive]` + feature flags. `tokio-uring`, `tokio-console` = **separate crates**, not core refactors. · Isolate innovation in opt-in satellites."}],[{"k":"text","text":"Apollo Router (~40 crates) · Tower `Layer<S>` extension points + handshake-negotiated protocols (Federation 2). · Extension points = traits + negotiation, not frozen enums."}],[{"k":"text","text":"rust-analyzer (~70 crates) · Salsa query traits (open) + process boundaries (`proc-macro-srv`). · Process boundary buys forward-compat for free."}],[{"k":"text","text":"wasmtime · Component Model arrived as **sister crate** (`wasmtime-component`), not a core rewrite. · New major feature = new crate, not surgery."}]]},{"k":"p","inline":[{"k":"strong","text":"Pattern dominant"},{"k":"text","text":": zero surveyed projects pre-stub crates for v+2 milestones.\nAll five rely on the same three levers Nika already uses ("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":",\nfeatures, satellite crates)."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"p","inline":[{"k":"strong","text":"Positive:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"v0.90 ships with a stable kernel API surface — Cortex and WASM can land\nlater as additive admissions without touching admitted L0/L0.5 crates."}],[{"k":"text","text":"Zero \"stub crate debt\" at v0.90 (no empty 8-satellite scaffolding)."}],[{"k":"text","text":"Upstream churn (Component Model Preview 3, fsrs design) does not block Nika."}],[{"k":"text","text":"Any departure from a reserved seam (e.g. adding a non-additive field to\n"},{"k":"code","text":"MemoryStore"},{"k":"text","text":") is a breaking change — caught by "},{"k":"code","text":"cargo public-api"},{"k":"text","text":" +\n"},{"k":"code","text":"cargo semver-checks"},{"k":"text","text":" (planned, P0 follow-up)."}]]},{"k":"p","inline":[{"k":"strong","text":"Negative:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Reserved seams that turn out to be "},{"k":"em","text":"wrong"},{"k":"text","text":" (e.g. "},{"k":"code","text":"MemoryStore"},{"k":"text","text":" shape\nunsuitable for real backends) require a breaking trait change at v0.95.\nMitigation: property tests in v0.90 (P0 follow-up) prove the seam can host\na realistic backend before lock."}],[{"k":"text","text":"Documentation cost: every reserved seam needs a sentence in\n"},{"k":"code","text":"forward-compat-invariants.md"},{"k":"text","text":" explaining the v-target and the escape hatch."}]]},{"k":"p","inline":[{"k":"strong","text":"Neutral:"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Crate count target stays at 40-42 for v0.90, +9 Cortex at v0.95, +2 WASM at\nv0.100 = ~51-53 final. No change to ROADMAP."}]]},{"k":"h","depth":2,"text":"Escape hatch","id":"escape-hatch"},{"k":"p","inline":[{"k":"text","text":"Reserved kernel traits and reserved event sub-enums "},{"k":"strong","text":"remain modifiable until\ntheir named v-target"},{"k":"text","text":". A reserved seam is not a stable contract — it is a\n"},{"k":"em","text":"shape commitment"},{"k":"text","text":". The day Cortex lands at v0.95, "},{"k":"code","text":"MemoryStore"},{"k":"text","text":"'s final shape\nis locked; until then, breaking changes to the trait are allowed and tracked\nas "},{"k":"code","text":"affects_layers: [L0.5]"},{"k":"text","text":" ADR amendments."}]},{"k":"p","inline":[{"k":"text","text":"This must be documented in "},{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":"\nunder a new "},{"k":"code","text":"§reserved-mutability"},{"k":"text","text":" section (P1 follow-up)."}]},{"k":"h","depth":2,"text":"Related decisions","id":"related-decisions"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"ADR-002"},{"k":"text","text":" Real semver toward 1.0 (amended D-2026-06-20-N1) — context for the release model that demands reservation."}],[{"k":"strong","text":"ADR-006"},{"k":"text","text":" Layered kernel ISP traits — defines what trait stubs reserve."}],[{"k":"strong","text":"ADR-007"},{"k":"text","text":" Forward-compat invariants — "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" + "},{"k":"code","text":"::new()"},{"k":"text","text":" discipline."}],[{"k":"strong","text":"ADR-014"},{"k":"text","text":" Sealed kernel traits — prevents downstream impl, makes seam mutability safer."}],[{"k":"strong","text":"ADR-020"},{"k":"text","text":" WASM plugin boundary — names the v0.100 deferral target."}],[{"k":"strong","text":"ADR-024"},{"k":"text","text":" SOTA Rust patterns — survey context for this ADR."}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-028

Forward-compat API-type reservation (amended — feature scheduling dropped)

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

ADR-028: Forward-compat reservation policy — seams now, crates later #

Context #

The swarm-3 SOTA audit (rust-architect + rust-pro + web-researcher, 2026-04-16, HEAD 5e810a94a) closed a recurring strategic question:

"Puisqu'on refait Nika from scratch, est-ce con de différer Cortex memory à v0.95 et WASM plugin à v0.100 ? Faut-il tout planifier dès v0.90 ?"

The temptation is real: if every crate is rewritten clean, why not fully bake the v0.95 Cortex orchestrator (nika-memory + 8 satellites) and v0.100 WASM plugin host (nika-wasm-host + nika-sandbox) right now, so nothing ever needs to change? This ADR closes the question.

Decision #

Two-tier forward-compat policy. Seams are mandatory at v0.90; crate implementations are deferable to their named v-target.

Tier 1 — SEAMS (mandatory, ship at v0.90) #

A seam is the smallest API surface that fixes the shape of a future feature without committing to its implementation. Seams must land before v0.90:

Seam mechanism · Where in Nika today
`#[non_exhaustive]` on every public enum + struct · All L0 + L0.5 crates (INV-019, ADR-007)
Reserved trait stubs in kernel (`MemoryStore`, `WasmPluginHost`, `Sandbox`, `EmbeddingProvider`, `ToolExecutor`, `ObservabilitySink`) · `crates/nika-kernel/src/` (Wave 2 S1-B)
Reserved sub-enums in event log (`EventKind::Memory` v0.95, `EventKind::Plugin` + `Wasm` v0.100) · Q4 + Q6 of `l0-l05-architecture-decisions.md`
Reserved fields on Infer{Request,Response} + MemoryFrame · Wave 2 S1-B + S1-C
`pub fn new()` constructors blocking struct-literal syntax · Every `#[non_exhaustive]` struct (Q-pattern)
`Extension { ns, name, payload }` escape hatch on `EventKind` · Q6 (Pattern B sub-enums)

Seams are cheap to add now, ruinous to retrofit later (Hyrum's Law: every observable behaviour gets depended on). They cost a few lines of #[non_exhaustive] and Reserved { version } placeholders. Their absence creates breaking changes at every v-tick.

Tier 2 — CRATE IMPLEMENTATIONS (deferable to named v-target) #

A crate implementation is the actual code that satisfies a seam. Crate implementations are deferred until at least one of:

A user signal demands the feature (real workflow, not speculation).
The upstream design space stabilises (e.g. WASM Component Model Preview 3).
A sibling Diamond crate would benefit immediately (≥2 consumers, Q2 rule).

Specific deferrals locked by this ADR:

v0.95 Cortex memory — KEEP-DEFER #

Seams already shipped: MemoryStore, EmbeddingProvider, MemoryDirective on InferRequest, MemoryFrameRef on InferResponse, EventKind::Memory reserved sub-enum.
Crates deferred: nika-memory (L2 orchestrator) + 8 satellites (nika-memory-{hnsw,bm25,rrf,fsrs,rdfs-reasoner,temporal,graph-algos,autodesc}).
Rationale: 8 stub crates × 15k LOC budget each = ~120k LOC of empty hulls with zero user signal. fsrs (forgetting curve) and rdfs-reasoner design spaces are open in 2026 — premature freeze guarantees a v0.95 refactor.
v0.90 deliverable: 2-3 property tests proving MemoryStore can host a realistic HNSW backend (no implementation, just the trait shape proof).

v0.100 WASM plugin host — KEEP-DEFER #

Seams already shipped: WasmPluginHost, Sandbox, EventKind::Plugin + Wasm reserved.
Crates deferred: nika-wasm-host + nika-sandbox (L3).
Rationale: WebAssembly Component Model Preview 3 (async, streams) is still in flux upstream as of 2026-04. wasmtime tracks; wasmer + wasmi lag. Stubbing before Preview 3 stabilises = rebreak guaranteed.
Escape hatch: if a user demands plugins before v0.100, a Lua/Starlark/wasmi L1 crate ships under unstable-* (FCI-007 distribution flag).

What "tout v0.100" actually means #

The user proposal — "since we rewrite from scratch, plan everything for v0.100" — is half right: every seam must be planned for v0.100 (already done). But implementations follow YAGNI (Beck) + premature-abstraction caution (Metz): abstraction without ≥3 concrete usages is debt, not investment.

SOTA evidence (cross-project survey, swarm-3) #

Project · Future-feature pattern · Lesson
Bevy (ECS, ~50 crates) · No reservation; deliberate breakage every 3 months. · "Break early, break often" — community accepts. Not Nika's contract (stable forward-compat · real semver toward 1.0 per ADR-002 · amended D-2026-06-20-N1).
tokio (~10 crates) · `#[non_exhaustive]` + feature flags. `tokio-uring`, `tokio-console` = **separate crates**, not core refactors. · Isolate innovation in opt-in satellites.
Apollo Router (~40 crates) · Tower `Layer<S>` extension points + handshake-negotiated protocols (Federation 2). · Extension points = traits + negotiation, not frozen enums.
rust-analyzer (~70 crates) · Salsa query traits (open) + process boundaries (`proc-macro-srv`). · Process boundary buys forward-compat for free.
wasmtime · Component Model arrived as **sister crate** (`wasmtime-component`), not a core rewrite. · New major feature = new crate, not surgery.

Pattern dominant: zero surveyed projects pre-stub crates for v+2 milestones. All five rely on the same three levers Nika already uses (#[non_exhaustive], features, satellite crates).

Consequences #

Positive:

v0.90 ships with a stable kernel API surface — Cortex and WASM can land later as additive admissions without touching admitted L0/L0.5 crates.
Zero "stub crate debt" at v0.90 (no empty 8-satellite scaffolding).
Upstream churn (Component Model Preview 3, fsrs design) does not block Nika.
Any departure from a reserved seam (e.g. adding a non-additive field to MemoryStore) is a breaking change — caught by cargo public-api + cargo semver-checks (planned, P0 follow-up).

Negative:

Reserved seams that turn out to be wrong (e.g. MemoryStore shape unsuitable for real backends) require a breaking trait change at v0.95. Mitigation: property tests in v0.90 (P0 follow-up) prove the seam can host a realistic backend before lock.
Documentation cost: every reserved seam needs a sentence in forward-compat-invariants.md explaining the v-target and the escape hatch.

Neutral:

Crate count target stays at 40-42 for v0.90, +9 Cortex at v0.95, +2 WASM at v0.100 = ~51-53 final. No change to ROADMAP.

Escape hatch #

Reserved kernel traits and reserved event sub-enums remain modifiable until their named v-target. A reserved seam is not a stable contract — it is a shape commitment. The day Cortex lands at v0.95, MemoryStore's final shape is locked; until then, breaking changes to the trait are allowed and tracked as affects_layers: [L0.5] ADR amendments.

This must be documented in docs/architecture/forward-compat-invariants.md under a new §reserved-mutability section (P1 follow-up).

ADR-002 Real semver toward 1.0 (amended D-2026-06-20-N1) — context for the release model that demands reservation.
ADR-006 Layered kernel ISP traits — defines what trait stubs reserve.
ADR-007 Forward-compat invariants — #[non_exhaustive] + ::new() discipline.
ADR-014 Sealed kernel traits — prevents downstream impl, makes seam mutability safer.
ADR-020 WASM plugin boundary — names the v0.100 deferral target.
ADR-024 SOTA Rust patterns — survey context for this ADR.

🦋

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

Every decision, with its status This one in the repo