{"row":{"id":"ADR-032","title":"WasmPluginError OutOfFuel + Trap + PluginCallContext reservation","file":"adr-032-wasm-plugin-context.md","status":"accepted","date":"2026-04-17","cites":7,"supersedes":[],"superseded_by":[],"layers":["L0.5"],"tags":["l0.5","wasm","plugin","fuel"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-032: WasmPluginError OutOfFuel + Trap + PluginCallContext reservation","id":"adr-032-wasmpluginerror-outoffuel--trap--plugincallcontext-reservation"},{"k":"p","inline":[{"k":"text","text":"Status flipped "},{"k":"code","text":"proposed → accepted"},{"k":"text","text":" 2026-07-12 under the merged-code\nrule (the #474 ADR ruling): all three reservations ship in\n"},{"k":"code","text":"crates/nika-kernel-plugin/src/wasm.rs"},{"k":"text","text":" (the kernel's plugin member —\nthe ADR predates the kernel descent; "},{"k":"code","text":"nika-kernel"},{"k":"text","text":" re-exports). The\nstub's two open follow-ups were RESOLVED in the shipped code; the\nprose records those resolutions."}]},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Wave 4A R4 (commit "},{"k":"code","text":"368820e42"},{"k":"text","text":", 2026-04-17) extended the WASM plugin\nstubs shipped under ADR-020 with three additive reservations, so the\nv0.100 wasmtime integration lands without breaking every v0.8x plugin\nconsumer: a fuel-cancellation error, a structured trap surface, and a\nper-call context that carries trust + budgets."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"All three shapes are "},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":", shipped in\n"},{"k":"code","text":"nika-kernel-plugin/src/wasm.rs"},{"k":"text","text":":"}]},{"k":"list","ordered":true,"items":[[{"k":"strong","text":"`WasmPluginError::OutOfFuel { consumed, budget }`"},{"k":"text","text":" — fuel-based\ncancellation beside the wall-clock "},{"k":"code","text":"Timeout"},{"k":"text","text":". The seed sketched a\nsingle "},{"k":"code","text":"fuel_consumed"},{"k":"text","text":"; the shipped shape carries BOTH sides of the\nledger — an error that says how much was spent but not what was\nallowed teaches nothing."}],[{"k":"strong","text":"`WasmPluginError::Trap { kind: TrapKind }`"},{"k":"text","text":" — guest-level aborts\n(unreachable · divide-by-zero · stack overflow · …) distinct from\nhost errors. "},{"k":"strong","text":"Follow-up resolved"},{"k":"text","text":": "},{"k":"code","text":"TrapKind"},{"k":"text","text":" is\n"},{"k":"code","text":"#[non_exhaustive]"},{"k":"text","text":", mirroring wasmtime's "},{"k":"code","text":"TrapCode"},{"k":"text","text":" taxonomy at the\nnika layer — engine-specific variants land without a major AND\nwithout a direct wasmtime dep in L0.5."}],[{"k":"strong","text":"`PluginCallContext { trust, input_trust, cancel, fuel_budget,\nwall_timeout_ms }`"},{"k":"text","text":" — the per-call DTO replacing the bare-cancel\nargument. "},{"k":"strong","text":"Follow-up resolved"},{"k":"text","text":": the seed's "},{"k":"code","text":"caller_trust"},{"k":"text","text":" /\n"},{"k":"code","text":"plugin_trust"},{"k":"text","text":" pair became "},{"k":"code","text":"input_trust"},{"k":"text","text":" (propagated from the verb\nthat constructed the call) and "},{"k":"code","text":"trust"},{"k":"text","text":" (granted to the plugin's\nOUTPUT — lower than "},{"k":"code","text":"input_trust"},{"k":"text","text":" by host policy: plugin output is\nalways untrusted data regardless of what it was given, the ADR-030\nsticky-taint model applied at the plugin boundary). Both budget\nknobs ride the context ("},{"k":"code","text":"None"},{"k":"text","text":" = unmetered), so the dual-timeout\npolicy (fuel + wall) is per-call, not global."}]]},{"k":"h","depth":2,"text":"Alternatives considered","id":"alternatives-considered"},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"Single timeout (wall-clock only)"},{"k":"text","text":" — rejected: wall time cannot\ndistinguish a slow host from a hot guest loop; fuel is deterministic\nper-op and survives host load. Both ship."}],[{"k":"strong","text":"Closed `TrapKind` enum"},{"k":"text","text":" — rejected (the stub's open question):\nwasmtime/wasmer taxonomies evolve; a closed enum turns every new trap\nclass into a major."}],[{"k":"strong","text":"Trust pair as caller/plugin"},{"k":"text","text":" (the seed's sketch) — rejected at\nhardening: what gates downstream consumption is the trust of the\nOUTPUT, not the identity of the caller; input/output naming states\nthe dataflow directly."}]]},{"k":"h","depth":2,"text":"Empirical validation (what makes this \"merged code\")","id":"empirical-validation-what-makes-this-merged-code"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-kernel-plugin/src/wasm.rs"},{"k":"text","text":" — "},{"k":"code","text":"OutOfFuel"},{"k":"text","text":" (line ~146), "},{"k":"code","text":"Trap"},{"k":"text","text":" +\n"},{"k":"code","text":"TrapKind"},{"k":"text","text":" (lines ~162-192, with "},{"k":"code","text":"Display"},{"k":"text","text":"), "},{"k":"code","text":"PluginCallContext"},{"k":"text","text":"\n(line ~217) with the untrusted-default constructor."}],[{"k":"text","text":"The reservations are exercised by the plugin trait's mock host in\n"},{"k":"code","text":"nika-kernel-mock"},{"k":"text","text":" (the ADR-020 test seam)."}]]},{"k":"h","depth":2,"text":"See also","id":"see-also"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"ADR-020 — WASM plugin boundary + Sandbox (amended by this ADR)."}],[{"k":"text","text":"ADR-028 — Forward-compat reservation policy (this ADR is an instance)."}],[{"k":"text","text":"ADR-030 — sticky-taint trust model (applied here at the plugin edge)."}],[{"k":"text","text":"ADR-033 — "},{"k":"code","text":"TrustLevel"},{"k":"text","text":" lattice used by "},{"k":"code","text":"PluginCallContext"},{"k":"text","text":"."}],[{"k":"text","text":"FCI-035 addendum — Wave 4A/4B reservation catalog."}],[{"k":"text","text":"NIKA-700..749 — WASM plugin error code range (reserved v0.80)."}]]},{"k":"p","inline":[{"k":"text","text":"🦋"}]}]

ADR-032

WasmPluginError OutOfFuel + Trap + PluginCallContext reservation

accepted · 2026-04-17 · L0.5 · cites 7

ADR-032: WasmPluginError OutOfFuel + Trap + PluginCallContext reservation #

Status flipped proposed → accepted 2026-07-12 under the merged-code rule (the #474 ADR ruling): all three reservations ship in crates/nika-kernel-plugin/src/wasm.rs (the kernel's plugin member — the ADR predates the kernel descent; nika-kernel re-exports). The stub's two open follow-ups were RESOLVED in the shipped code; the prose records those resolutions.

Context #

Wave 4A R4 (commit 368820e42, 2026-04-17) extended the WASM plugin stubs shipped under ADR-020 with three additive reservations, so the v0.100 wasmtime integration lands without breaking every v0.8x plugin consumer: a fuel-cancellation error, a structured trap surface, and a per-call context that carries trust + budgets.

Decision #

All three shapes are #[non_exhaustive], shipped in nika-kernel-plugin/src/wasm.rs:

`WasmPluginError::OutOfFuel { consumed, budget }` — fuel-based cancellation beside the wall-clock Timeout. The seed sketched a single fuel_consumed; the shipped shape carries BOTH sides of the ledger — an error that says how much was spent but not what was allowed teaches nothing.
`WasmPluginError::Trap { kind: TrapKind }` — guest-level aborts (unreachable · divide-by-zero · stack overflow · …) distinct from host errors. Follow-up resolved: TrapKind is #[non_exhaustive], mirroring wasmtime's TrapCode taxonomy at the nika layer — engine-specific variants land without a major AND without a direct wasmtime dep in L0.5.
`PluginCallContext { trust, input_trust, cancel, fuel_budget, wall_timeout_ms }` — the per-call DTO replacing the bare-cancel argument. Follow-up resolved: the seed's caller_trust / plugin_trust pair became input_trust (propagated from the verb that constructed the call) and trust (granted to the plugin's OUTPUT — lower than input_trust by host policy: plugin output is always untrusted data regardless of what it was given, the ADR-030 sticky-taint model applied at the plugin boundary). Both budget knobs ride the context (None = unmetered), so the dual-timeout policy (fuel + wall) is per-call, not global.

Alternatives considered #

Single timeout (wall-clock only) — rejected: wall time cannot distinguish a slow host from a hot guest loop; fuel is deterministic per-op and survives host load. Both ship.
Closed `TrapKind` enum — rejected (the stub's open question): wasmtime/wasmer taxonomies evolve; a closed enum turns every new trap class into a major.
Trust pair as caller/plugin (the seed's sketch) — rejected at hardening: what gates downstream consumption is the trust of the OUTPUT, not the identity of the caller; input/output naming states the dataflow directly.

Empirical validation (what makes this "merged code") #

nika-kernel-plugin/src/wasm.rs — OutOfFuel (line ~146), Trap + TrapKind (lines ~162-192, with Display), PluginCallContext (line ~217) with the untrusted-default constructor.
The reservations are exercised by the plugin trait's mock host in nika-kernel-mock (the ADR-020 test seam).