28 lines
1.7 KiB
Markdown
28 lines
1.7 KiB
Markdown
# 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**)
|