{"row":{"id":"ADR-014","title":"Sealed kernel traits with explicit adapter registration","file":"adr-014-sealed-kernel-traits.md","status":"accepted","date":"2026-04-14","cites":14,"supersedes":[],"superseded_by":[],"layers":["L0.5"],"tags":["kernel","sealed-traits","api-stability"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-014: Sealed kernel traits with explicit adapter registration","id":"adr-014-sealed-kernel-traits-with-explicit-adapter-registration"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"code","text":"nika-kernel"},{"k":"text","text":" (L0.5) defines ~20 public async traits — "},{"k":"code","text":"Provider"},{"k":"text","text":", "},{"k":"code","text":"MemoryStore"},{"k":"text","text":", "},{"k":"code","text":"ToolExecutor"},{"k":"text","text":", "},{"k":"code","text":"FsRead"},{"k":"text","text":", "},{"k":"code","text":"HttpGet"},{"k":"text","text":", "},{"k":"code","text":"ShellExecutor"},{"k":"text","text":", etc. Today only "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" implements them (L0.5 test). As Phase 2 admits L1 effect crates ("},{"k":"code","text":"nika-http"},{"k":"text","text":", "},{"k":"code","text":"nika-fs"},{"k":"text","text":", "},{"k":"code","text":"nika-process"},{"k":"text","text":"), each trait gains real implementors."}]},{"k":"p","inline":[{"k":"strong","text":"The open question"},{"k":"text","text":": can an "},{"k":"em","text":"external"},{"k":"text","text":" crate (outside supernovae-st/nika workspace) implement these traits? If yes, every method signature becomes load-bearing across semver — adding a default-method parameter is a breaking change for external implementors. If no, we preserve flexibility to evolve method signatures as we learn."}]},{"k":"p","inline":[{"k":"text","text":"2026 Rust practice (axum, serde, uv) uses the "},{"k":"strong","text":"sealed-trait pattern"},{"k":"text","text":" ("},{"k":"code","text":"pub trait Foo: private::Sealed { ... }"},{"k":"text","text":") to prevent external impls while keeping the trait public for users who depend on it via "},{"k":"code","text":"dyn Foo"},{"k":"text","text":". rust-analyzer, rustls, tokio all seal core traits."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"All public traits in "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" are "},{"k":"strong","text":"sealed"},{"k":"text","text":" via the "},{"k":"code","text":"private::Sealed"},{"k":"text","text":" supertrait pattern:"}]},{"k":"code","lang":"rust","text":"// nika-kernel/src/lib.rs\nmod private {\n    pub trait Sealed {}\n}\n\n// nika-kernel/src/provider.rs\npub trait ProviderInfer: private::Sealed + Send + Sync { /* ... */ }\n\n// nika-kernel/src/provider.rs (internal, for blanket Sealed impls)\nimpl<T: crate::Provider + ?Sized> private::Sealed for T {}"},{"k":"p","inline":[{"k":"text","text":"External crates "},{"k":"strong","text":"cannot"},{"k":"text","text":" "},{"k":"code","text":"impl ProviderInfer for MyType"},{"k":"text","text":" (compile error: "},{"k":"code","text":"Sealed"},{"k":"text","text":" not implemented, and "},{"k":"code","text":"Sealed"},{"k":"text","text":" is private). Instead, external integrations route through:"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"Adapter macros"},{"k":"text","text":" ("},{"k":"code","text":"nika_kernel::provider_impl!"},{"k":"text","text":") for workspace-local crates ("},{"k":"code","text":"nika-provider-rig"},{"k":"text","text":", "},{"k":"code","text":"nika-provider-native"},{"k":"text","text":", "},{"k":"code","text":"nika-provider-mock"},{"k":"text","text":")."}],[{"k":"strong","text":"`nika-builtin-*` wrappers"},{"k":"text","text":" for ecosystem integrations (GitHub, Cloud, Workspace — ADR tbd)."}],[{"k":"strong","text":"Future pck packages"},{"k":"text","text":" (plugin protocol, Phase 4+) for community extensions."}]]},{"k":"p","inline":[{"k":"text","text":"Adding a trait method still requires care, but the set of implementors is "},{"k":"strong","text":"finite and controlled by the workspace"},{"k":"text","text":"."}]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Method signatures and default methods can evolve within v0.x without breaking external code (there isn't any external impl by construction)."}],[{"k":"text","text":"Clear path for ecosystem extensions (adapter macros > plugin protocol > pck) — enforced architecturally."}],[{"k":"text","text":"Matches Rust 2026 canonical pattern."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Some friction for hypothetical out-of-workspace adapters — but there are none today, and when they emerge they belong as "},{"k":"code","text":"nika-builtin-*"},{"k":"text","text":" or pck packages per ADR-004's crate-count discipline."}],[{"k":"text","text":"Adds a "},{"k":"code","text":"private::Sealed"},{"k":"text","text":" module + blanket impl per trait group."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Language-level "},{"k":"code","text":"sealed"},{"k":"text","text":" keyword RFC is still unmerged as of 2026-Q1 — the supertrait pattern is idiomatic."}]]},{"k":"h","depth":2,"text":"Evidence","id":"evidence"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Pattern sources: axum, serde ("},{"k":"code","text":"private::Sealed"},{"k":"text","text":"), rustls ("},{"k":"code","text":"server::ServerConfig"},{"k":"text","text":" sealed), tokio-stream"}],[{"k":"code","text":"crates/nika-kernel/src/lib.rs:19-34"},{"k":"text","text":" — trait hierarchy (to be updated with sealed pattern)"}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A — Open traits (no sealing)","id":"alt-a--open-traits-no-sealing"},{"k":"p","inline":[{"k":"text","text":"Rejected — every method change becomes potential breakage."}]},{"k":"h","depth":3,"text":"Alt B — Opaque impl trait only (no trait at all)","id":"alt-b--opaque-impl-trait-only-no-trait-at-all"},{"k":"p","inline":[{"k":"text","text":"Rejected — loses "},{"k":"code","text":"dyn Trait"},{"k":"text","text":" + breaks test substitutability (kernel-mock)."}]},{"k":"h","depth":3,"text":"Alt C — `#[non_exhaustive]` on the trait","id":"alt-c--non_exhaustive-on-the-trait"},{"k":"p","inline":[{"k":"text","text":"Not valid in Rust — "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" is structs/enums only."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-006 — kernel ISP traits (which this seals)"}],[{"k":"text","text":"ADR-012 — typestate runtime (uses sealed kernel via "},{"k":"code","text":"bind_kernel(&dyn Kernel)"},{"k":"text","text":")"}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Migration: sealing can be added to "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" in a single commit before any L1 effect crate admits. No breaking change to "},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" (workspace-local, blanket-Sealed applies). Plan for Phase 2 Session 1."}]}]

ADR-014

Sealed kernel traits with explicit adapter registration

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

ADR-014: Sealed kernel traits with explicit adapter registration #

Context #

nika-kernel (L0.5) defines ~20 public async traits — Provider, MemoryStore, ToolExecutor, FsRead, HttpGet, ShellExecutor, etc. Today only nika-kernel-mock implements them (L0.5 test). As Phase 2 admits L1 effect crates (nika-http, nika-fs, nika-process), each trait gains real implementors.

The open question: can an external crate (outside supernovae-st/nika workspace) implement these traits? If yes, every method signature becomes load-bearing across semver — adding a default-method parameter is a breaking change for external implementors. If no, we preserve flexibility to evolve method signatures as we learn.

2026 Rust practice (axum, serde, uv) uses the sealed-trait pattern (pub trait Foo: private::Sealed { ... }) to prevent external impls while keeping the trait public for users who depend on it via dyn Foo. rust-analyzer, rustls, tokio all seal core traits.

Decision #

All public traits in nika-kernel are sealed via the private::Sealed supertrait pattern:

rust

1// nika-kernel/src/lib.rs2mod private {3    pub trait Sealed {}4}56// nika-kernel/src/provider.rs7pub trait ProviderInfer: private::Sealed + Send + Sync { /* ... */ }89// nika-kernel/src/provider.rs (internal, for blanket Sealed impls)10impl<T: crate::Provider + ?Sized> private::Sealed for T {}

External crates cannot impl ProviderInfer for MyType (compile error: Sealed not implemented, and Sealed is private). Instead, external integrations route through:

Adapter macros (nika_kernel::provider_impl!) for workspace-local crates (nika-provider-rig, nika-provider-native, nika-provider-mock).
`nika-builtin-*` wrappers for ecosystem integrations (GitHub, Cloud, Workspace — ADR tbd).
Future pck packages (plugin protocol, Phase 4+) for community extensions.

Adding a trait method still requires care, but the set of implementors is finite and controlled by the workspace.

Consequences #

Positive #

Method signatures and default methods can evolve within v0.x without breaking external code (there isn't any external impl by construction).
Clear path for ecosystem extensions (adapter macros > plugin protocol > pck) — enforced architecturally.
Matches Rust 2026 canonical pattern.

Negative #

Some friction for hypothetical out-of-workspace adapters — but there are none today, and when they emerge they belong as nika-builtin-* or pck packages per ADR-004's crate-count discipline.
Adds a private::Sealed module + blanket impl per trait group.

Neutral #

Language-level sealed keyword RFC is still unmerged as of 2026-Q1 — the supertrait pattern is idiomatic.

Evidence #

Pattern sources: axum, serde (private::Sealed), rustls (server::ServerConfig sealed), tokio-stream
crates/nika-kernel/src/lib.rs:19-34 — trait hierarchy (to be updated with sealed pattern)

Alternatives considered #

Alt A — Open traits (no sealing) #

Rejected — every method change becomes potential breakage.

Alt B — Opaque impl trait only (no trait at all) #

Rejected — loses dyn Trait + breaks test substitutability (kernel-mock).

Alt C — `#[non_exhaustive]` on the trait #

Not valid in Rust — #[non_exhaustive] is structs/enums only.

ADR-006 — kernel ISP traits (which this seals)
ADR-012 — typestate runtime (uses sealed kernel via bind_kernel(&dyn Kernel))

Notes #

Migration: sealing can be added to nika-kernel in a single commit before any L1 effect crate admits. No breaking change to nika-kernel-mock (workspace-local, blanket-Sealed applies). Plan for Phase 2 Session 1.

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

Every decision, with its status This one in the repo