bare-operating-system/developer-guide/adr/002-wasm-kernel-compile-hook.md

ADR 002: Feature-gated WASM compile hook (ctx.bareOsWasmKernelCompile)

Status

Accepted (2026-04-04)

Context

Operators asked for a bounded path to validate WebAssembly modules in the same runtime that runs the kernel, without pulling Node.js builtins into booter sources or silently loading foreign code.

Decision

• Expose ctx.bareOsWasmKernelCompile(buf, opts?) only when the host sets BARE_OS_WASM_KERNEL=1 (or true), copied into session shellEnv like other passthrough keys.
• Implementation calls WebAssembly.compile on a size-capped Uint8Array (default max 512 KiB; override via opts.maxBytes). No instantiation, no imports, and no execution — compile-only probe suitable for static validation and export-name listing when the engine exposes WebAssembly.Module.exports.
• Code lives in packages/bare-os-booter/lib/bare-os-wasm-kernel.js and uses globalThis only (Bare/V8).

Consequences

• Security: Mis-toggling BARE_OS_WASM_KERNEL only enables compilation CPU work within caps; it does not grant syscall bridges. Full guest loaders remain out of scope for this ADR.
• Optional dep: bare-vm remains an optional package for future instantiation work; this ADR does not require it on the compile path.
• Docs: Environment appendix lists BARE_OS_WASM_KERNEL; POSIX declared profile remains the normative “honest POSIX” surface.

Related

• docs/architecture/POSIX_DECLARED_PROFILE.md
• docs/reference/environment-and-posix-appendix.md
• packages/bare-os-booter/CHANGELOG.md (ctx 1.33.0)