# 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](../../docs/architecture/POSIX_DECLARED_PROFILE.md) 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**)