{"row":{"id":"ADR-020","title":"WASM plugin boundary + Sandbox: trait stubs now, dual timeout later","file":"adr-020-wasm-plugin-boundary.md","status":"accepted","date":"2026-04-16","cites":12,"supersedes":[],"superseded_by":[],"layers":["L0.5"],"tags":["wasm","plugin","sandbox","capability"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-020: WASM plugin boundary + Sandbox: trait stubs now, dual timeout later","id":"adr-020-wasm-plugin-boundary--sandbox-trait-stubs-now-dual-timeout-later"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"code","text":"forward-compat-invariants.md"},{"k":"text","text":" Pattern 1 lists "},{"k":"code","text":"WasmPluginHost"},{"k":"text","text":", "},{"k":"code","text":"Sandbox"},{"k":"text","text":",\nand "},{"k":"code","text":"ObservabilitySink"},{"k":"text","text":" as locked stub traits for v0.81. The intent: define\nthe trait shape now so future implementations slot in with zero breaking\nchange to the public API (Pattern 2: "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" + opt-in fields)."}]},{"k":"p","inline":[{"k":"text","text":"The kernel before Wave 2 ("},{"k":"code","text":"crates/nika-kernel/src/lib.rs:48-60"},{"k":"text","text":") defined ~20\natomic traits across 13 modules (agent, blob, checkpoint, clock, context,\nerrors, fs, http, memory, process, provider, tool_executor, types). None of\nthem addressed plugin sandboxing."}]},{"k":"p","inline":[{"k":"text","text":"S1-B (Wave 2 commit "},{"k":"code","text":"b68e58d4b"},{"k":"text","text":") added 4 new modules:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-kernel-core/src/cancel.rs"},{"k":"text","text":" — "},{"k":"code","text":"CancelCtx"},{"k":"text","text":" (real impl)."}],[{"k":"code","text":"crates/nika-kernel/src/observability.rs"},{"k":"text","text":" — "},{"k":"code","text":"ObservabilitySink"},{"k":"text","text":" (stub)."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/wasm.rs"},{"k":"text","text":" — "},{"k":"code","text":"WasmPluginHost"},{"k":"text","text":", "},{"k":"code","text":"PluginFs"},{"k":"text","text":",\n"},{"k":"code","text":"PluginHttp"},{"k":"text","text":", "},{"k":"code","text":"WasmPluginError"},{"k":"text","text":" (stubs)."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/sandbox.rs"},{"k":"text","text":" — "},{"k":"code","text":"Sandbox"},{"k":"text","text":", "},{"k":"code","text":"Capability"},{"k":"text","text":",\n"},{"k":"code","text":"SandboxError"},{"k":"text","text":" (stubs)."}]]},{"k":"p","inline":[{"k":"text","text":"ADR-014 sealing policy distinguishes \"sealed\" traits (community cannot\nimplement, must use the pck plugin protocol) from \"open\" traits (community\nmay implement alternative backends). The choice is per-trait."}]},{"k":"p","inline":[{"k":"text","text":"The kernel "},{"k":"code","text":"Cargo.toml"},{"k":"text","text":" ("},{"k":"code","text":"crates/nika-kernel/Cargo.toml:18-26"},{"k":"text","text":") has no WASM\ndeps — the stubs are trait definitions only, zero implementation code, zero\nnew transitive deps."}]},{"k":"p","inline":[{"k":"text","text":"Shield error codes NIKA-380 (CapabilityDenied), NIKA-381 (TrustViolation),\nNIKA-384 (SpotlightRequired) already exist for runtime capability checks at\nthe workflow layer. The Sandbox trait gives those codes a kernel-level\nsubstrate to enforce on."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Define the WASM plugin and sandbox traits at v0.81 with zero\nimplementation. Pick implementation details when v0.100 is in scope."}]},{"k":"h","depth":3,"text":"v0.81 (now, shipped in S1-B)","id":"v081-now-shipped-in-s1-b"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"WasmPluginHost"},{"k":"text","text":" (async, sealed = NO / "},{"k":"strong","text":"open"},{"k":"text","text":") — community may ship\nalternative WASM hosts (wasmtime, wasmer, or future WASI preview3\nruntimes)."}],[{"k":"code","text":"PluginFs"},{"k":"text","text":" (sync, "},{"k":"strong","text":"open"},{"k":"text","text":") — sandboxed file access for guest code."}],[{"k":"code","text":"PluginHttp"},{"k":"text","text":" (sync, "},{"k":"strong","text":"open"},{"k":"text","text":") — sandboxed HTTP for guest code."}],[{"k":"code","text":"WasmPluginError"},{"k":"text","text":" enum: "},{"k":"code","text":"NotFound"},{"k":"text","text":", "},{"k":"code","text":"ExecutionFailed"},{"k":"text","text":", "},{"k":"code","text":"SandboxViolation"},{"k":"text","text":",\n"},{"k":"code","text":"Timeout"},{"k":"text","text":". All variants "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":"."}],[{"k":"code","text":"Sandbox"},{"k":"text","text":" trait (async, "},{"k":"strong","text":"open"},{"k":"text","text":") — community may ship alternative sandbox\nbackends (Landlock on Linux, seatbelt on macOS, AppArmor, Bubblewrap)."}],[{"k":"code","text":"Capability"},{"k":"text","text":" enum ("},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":"): "},{"k":"code","text":"FsRead"},{"k":"text","text":", "},{"k":"code","text":"FsWrite"},{"k":"text","text":", "},{"k":"code","text":"Network"},{"k":"text","text":",\n"},{"k":"code","text":"ProcessSpawn"},{"k":"text","text":", "},{"k":"code","text":"EnvRead"},{"k":"text","text":". "},{"k":"strong","text":"Default-deny"},{"k":"text","text":" allowlist model."}],[{"k":"code","text":"SandboxError"},{"k":"text","text":" enum: "},{"k":"code","text":"Unavailable"},{"k":"text","text":", "},{"k":"code","text":"CapabilityDenied"},{"k":"text","text":", "},{"k":"code","text":"SetupFailed"},{"k":"text","text":"."}],[{"k":"text","text":"Mocks: "},{"k":"code","text":"NullWasmPluginHost"},{"k":"text","text":" (always returns "},{"k":"code","text":"NotFound"},{"k":"text","text":"), "},{"k":"code","text":"NullSandbox"},{"k":"text","text":"\n(allow-all for tests)."}]]},{"k":"h","depth":3,"text":"v0.100 (deferred)","id":"v0100-deferred"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Implementation choice between wasmtime and wasmer"},{"k":"text","text":" — benchmark when\nv0.100 is in scope. Both are viable; the trait shape is engine-agnostic."}],[{"k":"strong","text":"Dual timeout"},{"k":"text","text":": wall-clock (kills the WASM instance) AND fuel-based\n(instruction budget, platform-agnostic). Both required because wall-clock\nalone misses runaway pure-compute, and fuel alone misses I/O-bound stalls."}],[{"k":"strong","text":"Plugin payload format"},{"k":"text","text":": MessagePack or CBOR for compactness; decide at\nv0.100 with a benchmark on representative payloads."}],[{"k":"strong","text":"Sandbox backends"},{"k":"text","text":":"},{"k":"text","text":"- `nika-sandbox-landlock` (Linux 5.13+).\n- `nika-sandbox-seatbelt` (macOS).\n- `nika-sandbox-noop` (Windows / unsupported, hard-fails on any\n  capability check by default)."}]]},{"k":"h","depth":3,"text":"Sealing rationale (ADR-014 application)","id":"sealing-rationale-adr-014-application"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Trait · Sealed? · Why"}],[{"k":"text","text":"`Provider`, `MemoryStore`, `EventSink`, `BillingSink` · **sealed** (per ADR-034) · Workspace controls implementations; community uses the pck protocol."}],[{"k":"text","text":"`WasmPluginHost`, `PluginFs`, `PluginHttp` · **open** · Multiple WASM runtimes are legitimate; we should not block alternative hosts."}],[{"k":"text","text":"`Sandbox` · **open** · Platform-specific backends; users should be free to add new OS backends."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"h","depth":3,"text":"Positive","id":"positive"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Future v0.100 implementations are "},{"k":"strong","text":"strictly additive"},{"k":"text","text":" — no breaking\nchange to any consumer that imports the trait today."}],[{"k":"text","text":"Capability model is default-deny — security posture is conservative by\nconstruction."}],[{"k":"text","text":"Open traits invite community contributions (Bubblewrap, Firecracker\nmicro-VMs) without forking the kernel."}],[{"k":"text","text":"The mocks ("},{"k":"code","text":"NullWasmPluginHost"},{"k":"text","text":", "},{"k":"code","text":"NullSandbox"},{"k":"text","text":") let downstream crates\nsatisfy trait bounds today even though no real impl exists."}]]},{"k":"h","depth":3,"text":"Negative","id":"negative"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Stub traits add ~250 LOC to the kernel that returns errors today. Cost\nis small; the alternative (adding traits at v0.100) is a breaking\nchange for every "},{"k":"code","text":"Provider"},{"k":"text","text":" impl that wants to live alongside."}],[{"k":"text","text":"\"Open\" classification means we cannot later add a non-trivial method to\n"},{"k":"code","text":"Sandbox"},{"k":"text","text":" without a major version bump, even at v0.x. Mitigated by\n"},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" on the trait's associated enums (Capability,\nSandboxError) and by adding new methods with "},{"k":"code","text":"default"},{"k":"text","text":" impls."}],[{"k":"code","text":"PluginFs"},{"k":"text","text":" and "},{"k":"code","text":"PluginHttp"},{"k":"text","text":" are sync (per design decision: WASM guests\nsee synchronous calls), but real impls must internally bridge to async\nHTTP — cost of bridging happens once per call, accepted."}]]},{"k":"h","depth":3,"text":"Neutral","id":"neutral"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"Sandbox"},{"k":"text","text":" is orthogonal to WASM. It is also reusable for MCP server\nisolation when MCP lifecycle ships (Phase D Session 4)."}],[{"k":"code","text":"WasmPluginError::Timeout { timeout_ms }"},{"k":"text","text":" reserves the wall-clock\ntimeout shape. The fuel-based timeout will surface as a separate\nvariant ("},{"k":"code","text":"OutOfFuel"},{"k":"text","text":") when v0.100 ships — additive."}]]},{"k":"h","depth":2,"text":"Evidence / Affected code","id":"evidence--affected-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"crates/nika-kernel-plugin/src/wasm.rs:11-22"},{"k":"text","text":" — "},{"k":"code","text":"WasmPluginHost"},{"k":"text","text":" trait."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/wasm.rs:24-39"},{"k":"text","text":" — "},{"k":"code","text":"PluginFs"},{"k":"text","text":", "},{"k":"code","text":"PluginHttp"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/wasm.rs:50-83"},{"k":"text","text":" — "},{"k":"code","text":"WasmPluginError"},{"k":"text","text":" enum."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/sandbox.rs:18-26"},{"k":"text","text":" — "},{"k":"code","text":"Sandbox"},{"k":"text","text":" trait."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/sandbox.rs:28-54"},{"k":"text","text":" — "},{"k":"code","text":"Capability"},{"k":"text","text":" enum."}],[{"k":"code","text":"crates/nika-kernel-plugin/src/sandbox.rs:78-99"},{"k":"text","text":" — "},{"k":"code","text":"SandboxError"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-kernel-mock/src/plugin.rs"},{"k":"text","text":" — "},{"k":"code","text":"NullWasmPluginHost"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-kernel-mock/src/sandbox.rs"},{"k":"text","text":" — "},{"k":"code","text":"NullSandbox"},{"k":"text","text":"."}],[{"k":"code","text":"crates/nika-kernel/src/lib.rs:50,58,64-65"},{"k":"text","text":" — module + re-exports."}],[{"k":"code","text":"crates/nika-kernel/Cargo.toml:18-26"},{"k":"text","text":" — dep list (no WASM crates)."}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" — Pattern 1 (kernel\ntraits upfront)."}],[{"k":"code","text":"docs/adr/adr-014-sealed-kernel-traits.md"},{"k":"text","text":" — sealing policy."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"h","depth":3,"text":"Alt A -- No WASM support; extend MCP only","id":"alt-a----no-wasm-support-extend-mcp-only"},{"k":"p","inline":[{"k":"text","text":"Lean on MCP servers for all extensibility.\nRejected: MCP requires a separate process per server, with stdio or\nTCP overhead per call. WASM allows in-process plugins with microsecond\nstartup and shared memory. Both will coexist at v0.100; WASM is\nstrictly faster for short-lived, high-frequency plugins."}]},{"k":"h","depth":3,"text":"Alt B -- WASI-only, no custom traits","id":"alt-b----wasi-only-no-custom-traits"},{"k":"p","inline":[{"k":"text","text":"Adopt the WASI Preview2 component model directly.\nRejected: WASI Preview2 doesn't cover all Nika capabilities (e.g., LLM\ninference calls "},{"k":"em","text":"from"},{"k":"text","text":" plugins to providers). Custom traits give us\ncontrol of the host-side API; we can still target WASI Preview2/3 as\nthe guest ABI inside "},{"k":"code","text":"nika-wasm-host"},{"k":"text","text":"."}]},{"k":"h","depth":3,"text":"Alt C -- Define full WASM types now (memory layout, instance handles)","id":"alt-c----define-full-wasm-types-now-memory-layout-instance-handles"},{"k":"p","inline":[{"k":"text","text":"Land everything at v0.81.\nRejected: premature. The trait shape is enough to satisfy Pattern 1.\nMemory layout, instance lifecycle, and host-function bindings depend\non wasmtime/wasmer API evolution; defining them now risks rework when\nv0.100 arrives."}]},{"k":"h","depth":3,"text":"Alt D -- Seal `WasmPluginHost` and `Sandbox`","id":"alt-d----seal-wasmpluginhost-and-sandbox"},{"k":"p","inline":[{"k":"text","text":"Apply the same sealing policy as "},{"k":"code","text":"Provider"},{"k":"text","text":".\nRejected: unlike "},{"k":"code","text":"Provider"},{"k":"text","text":" (where workspace owns 25 implementations),\nWASM hosts and sandbox backends are platform-specific and benefit\nfrom community alternatives. Sealing them would block legitimate\nimplementations (Bubblewrap, Firecracker, AppArmor, future WASI runtimes)."}]},{"k":"h","depth":3,"text":"Alt E -- Single timeout (wall-clock only) at v0.100","id":"alt-e----single-timeout-wall-clock-only-at-v0100"},{"k":"p","inline":[{"k":"text","text":"Skip fuel-based timeouts.\nRejected for design intent: pure-compute WASM (no I/O) can spin without\never yielding to the host. Wall-clock requires a separate watchdog\nthread; fuel-based is cooperative and platform-agnostic. Both are\nneeded; choosing one is a regression we should not bake in."}]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-006 — kernel ISP trait design. ADR-020 adds traits to the kernel\nlist but does not change ADR-006's existing trait set."}],[{"k":"text","text":"ADR-007 — forward-compat invariants (Pattern 1: kernel traits upfront,\nPattern 2: "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":" on every public enum/struct)."}],[{"k":"text","text":"ADR-014 — sealed kernel traits. ADR-020 explicitly classifies\n"},{"k":"code","text":"WasmPluginHost"},{"k":"text","text":", "},{"k":"code","text":"PluginFs"},{"k":"text","text":", "},{"k":"code","text":"PluginHttp"},{"k":"text","text":", "},{"k":"code","text":"Sandbox"},{"k":"text","text":" as "},{"k":"strong","text":"open"},{"k":"text","text":"\n(not sealed)."}],[{"k":"text","text":"ADR-016 — Cancellation. WASM plugin calls should accept a\n"},{"k":"code","text":"CancelCtx"},{"k":"text","text":" once v0.95 ships, so a plugin call respects parent\ncancellation."}]]},{"k":"h","depth":2,"text":"Notes","id":"notes"},{"k":"p","inline":[{"k":"text","text":"Follow-ups (v0.100 territory):"}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"Pick wasmtime vs wasmer with a benchmark on representative payloads\n(large LLM responses passed into plugin, plugin returning embeddings)."}],[{"k":"text","text":"Implement dual-timeout (wall-clock + fuel) inside "},{"k":"code","text":"nika-wasm-host"},{"k":"text","text":"."}],[{"k":"text","text":"Decide payload format: MessagePack (smaller) vs CBOR (more standardized)."}],[{"k":"text","text":"Implement "},{"k":"code","text":"nika-sandbox-landlock"},{"k":"text","text":", "},{"k":"code","text":"nika-sandbox-seatbelt"},{"k":"text","text":", and a\n"},{"k":"code","text":"nika-sandbox-noop"},{"k":"text","text":" for unsupported platforms."}],[{"k":"text","text":"Add new variants to "},{"k":"code","text":"Capability"},{"k":"text","text":" enum as platform support widens\n(e.g., "},{"k":"code","text":"Clock"},{"k":"text","text":" for time access, "},{"k":"code","text":"RandomBytes"},{"k":"text","text":" for entropy)."}]]}]

ADR-020

WASM plugin boundary + Sandbox: trait stubs now, dual timeout later

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

ADR-020: WASM plugin boundary + Sandbox: trait stubs now, dual timeout later #

Context #

forward-compat-invariants.md Pattern 1 lists WasmPluginHost, Sandbox, and ObservabilitySink as locked stub traits for v0.81. The intent: define the trait shape now so future implementations slot in with zero breaking change to the public API (Pattern 2: #[non_exhaustive] + opt-in fields).

The kernel before Wave 2 (crates/nika-kernel/src/lib.rs:48-60) defined ~20 atomic traits across 13 modules (agent, blob, checkpoint, clock, context, errors, fs, http, memory, process, provider, tool_executor, types). None of them addressed plugin sandboxing.

S1-B (Wave 2 commit b68e58d4b) added 4 new modules:

crates/nika-kernel-core/src/cancel.rs — CancelCtx (real impl).
crates/nika-kernel/src/observability.rs — ObservabilitySink (stub).
crates/nika-kernel-plugin/src/wasm.rs — WasmPluginHost, PluginFs, PluginHttp, WasmPluginError (stubs).
crates/nika-kernel-plugin/src/sandbox.rs — Sandbox, Capability, SandboxError (stubs).

ADR-014 sealing policy distinguishes "sealed" traits (community cannot implement, must use the pck plugin protocol) from "open" traits (community may implement alternative backends). The choice is per-trait.

The kernel Cargo.toml (crates/nika-kernel/Cargo.toml:18-26) has no WASM deps — the stubs are trait definitions only, zero implementation code, zero new transitive deps.

Shield error codes NIKA-380 (CapabilityDenied), NIKA-381 (TrustViolation), NIKA-384 (SpotlightRequired) already exist for runtime capability checks at the workflow layer. The Sandbox trait gives those codes a kernel-level substrate to enforce on.

Decision #

Define the WASM plugin and sandbox traits at v0.81 with zero implementation. Pick implementation details when v0.100 is in scope.

v0.81 (now, shipped in S1-B) #

WasmPluginHost (async, sealed = NO / open) — community may ship alternative WASM hosts (wasmtime, wasmer, or future WASI preview3 runtimes).
PluginFs (sync, open) — sandboxed file access for guest code.
PluginHttp (sync, open) — sandboxed HTTP for guest code.
WasmPluginError enum: NotFound, ExecutionFailed, SandboxViolation, Timeout. All variants #[non_exhaustive].
Sandbox trait (async, open) — community may ship alternative sandbox backends (Landlock on Linux, seatbelt on macOS, AppArmor, Bubblewrap).
Capability enum (#[non_exhaustive]): FsRead, FsWrite, Network, ProcessSpawn, EnvRead. Default-deny allowlist model.
SandboxError enum: Unavailable, CapabilityDenied, SetupFailed.
Mocks: NullWasmPluginHost (always returns NotFound), NullSandbox (allow-all for tests).

v0.100 (deferred) #

Implementation choice between wasmtime and wasmer — benchmark when v0.100 is in scope. Both are viable; the trait shape is engine-agnostic.
Dual timeout: wall-clock (kills the WASM instance) AND fuel-based (instruction budget, platform-agnostic). Both required because wall-clock alone misses runaway pure-compute, and fuel alone misses I/O-bound stalls.
Plugin payload format: MessagePack or CBOR for compactness; decide at v0.100 with a benchmark on representative payloads.
Sandbox backends:- `nika-sandbox-landlock` (Linux 5.13+). - `nika-sandbox-seatbelt` (macOS). - `nika-sandbox-noop` (Windows / unsupported, hard-fails on any capability check by default).

Sealing rationale (ADR-014 application) #

Trait · Sealed? · Why
`Provider`, `MemoryStore`, `EventSink`, `BillingSink` · **sealed** (per ADR-034) · Workspace controls implementations; community uses the pck protocol.
`WasmPluginHost`, `PluginFs`, `PluginHttp` · **open** · Multiple WASM runtimes are legitimate; we should not block alternative hosts.
`Sandbox` · **open** · Platform-specific backends; users should be free to add new OS backends.

Consequences #

Positive #

Future v0.100 implementations are strictly additive — no breaking change to any consumer that imports the trait today.
Capability model is default-deny — security posture is conservative by construction.
Open traits invite community contributions (Bubblewrap, Firecracker micro-VMs) without forking the kernel.
The mocks (NullWasmPluginHost, NullSandbox) let downstream crates satisfy trait bounds today even though no real impl exists.

Negative #

Stub traits add ~250 LOC to the kernel that returns errors today. Cost is small; the alternative (adding traits at v0.100) is a breaking change for every Provider impl that wants to live alongside.
"Open" classification means we cannot later add a non-trivial method to Sandbox without a major version bump, even at v0.x. Mitigated by #[non_exhaustive] on the trait's associated enums (Capability, SandboxError) and by adding new methods with default impls.
PluginFs and PluginHttp are sync (per design decision: WASM guests see synchronous calls), but real impls must internally bridge to async HTTP — cost of bridging happens once per call, accepted.

Neutral #

Sandbox is orthogonal to WASM. It is also reusable for MCP server isolation when MCP lifecycle ships (Phase D Session 4).
WasmPluginError::Timeout { timeout_ms } reserves the wall-clock timeout shape. The fuel-based timeout will surface as a separate variant (OutOfFuel) when v0.100 ships — additive.

Evidence / Affected code #

crates/nika-kernel-plugin/src/wasm.rs:11-22 — WasmPluginHost trait.
crates/nika-kernel-plugin/src/wasm.rs:24-39 — PluginFs, PluginHttp.
crates/nika-kernel-plugin/src/wasm.rs:50-83 — WasmPluginError enum.
crates/nika-kernel-plugin/src/sandbox.rs:18-26 — Sandbox trait.
crates/nika-kernel-plugin/src/sandbox.rs:28-54 — Capability enum.
crates/nika-kernel-plugin/src/sandbox.rs:78-99 — SandboxError.
crates/nika-kernel-mock/src/plugin.rs — NullWasmPluginHost.
crates/nika-kernel-mock/src/sandbox.rs — NullSandbox.
crates/nika-kernel/src/lib.rs:50,58,64-65 — module + re-exports.
crates/nika-kernel/Cargo.toml:18-26 — dep list (no WASM crates).
docs/architecture/forward-compat-invariants.md — Pattern 1 (kernel traits upfront).
docs/adr/adr-014-sealed-kernel-traits.md — sealing policy.

Alternatives considered #

Alt A -- No WASM support; extend MCP only #

Lean on MCP servers for all extensibility. Rejected: MCP requires a separate process per server, with stdio or TCP overhead per call. WASM allows in-process plugins with microsecond startup and shared memory. Both will coexist at v0.100; WASM is strictly faster for short-lived, high-frequency plugins.

Alt B -- WASI-only, no custom traits #

Adopt the WASI Preview2 component model directly. Rejected: WASI Preview2 doesn't cover all Nika capabilities (e.g., LLM inference calls from plugins to providers). Custom traits give us control of the host-side API; we can still target WASI Preview2/3 as the guest ABI inside nika-wasm-host.

Alt C -- Define full WASM types now (memory layout, instance handles) #

Land everything at v0.81. Rejected: premature. The trait shape is enough to satisfy Pattern 1. Memory layout, instance lifecycle, and host-function bindings depend on wasmtime/wasmer API evolution; defining them now risks rework when v0.100 arrives.

Alt D -- Seal `WasmPluginHost` and `Sandbox` #

Apply the same sealing policy as Provider. Rejected: unlike Provider (where workspace owns 25 implementations), WASM hosts and sandbox backends are platform-specific and benefit from community alternatives. Sealing them would block legitimate implementations (Bubblewrap, Firecracker, AppArmor, future WASI runtimes).

Alt E -- Single timeout (wall-clock only) at v0.100 #

Skip fuel-based timeouts. Rejected for design intent: pure-compute WASM (no I/O) can spin without ever yielding to the host. Wall-clock requires a separate watchdog thread; fuel-based is cooperative and platform-agnostic. Both are needed; choosing one is a regression we should not bake in.

ADR-006 — kernel ISP trait design. ADR-020 adds traits to the kernel list but does not change ADR-006's existing trait set.
ADR-007 — forward-compat invariants (Pattern 1: kernel traits upfront, Pattern 2: #[non_exhaustive] on every public enum/struct).
ADR-014 — sealed kernel traits. ADR-020 explicitly classifies WasmPluginHost, PluginFs, PluginHttp, Sandbox as open (not sealed).
ADR-016 — Cancellation. WASM plugin calls should accept a CancelCtx once v0.95 ships, so a plugin call respects parent cancellation.

Notes #

Follow-ups (v0.100 territory):

Pick wasmtime vs wasmer with a benchmark on representative payloads (large LLM responses passed into plugin, plugin returning embeddings).
Implement dual-timeout (wall-clock + fuel) inside nika-wasm-host.
Decide payload format: MessagePack (smaller) vs CBOR (more standardized).
Implement nika-sandbox-landlock, nika-sandbox-seatbelt, and a nika-sandbox-noop for unsupported platforms.
Add new variants to Capability enum as platform support widens (e.g., Clock for time access, RandomBytes for entropy).

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

Every decision, with its status This one in the repo