# @suaveplan/api-sandbox-wasm-host-bridge - Host bridge wrapping a @suaveplan/api-sandbox-wasm WasmSandboxHandle as a @suaveplan/api-host PluginModule. Validates the WASM ABI surface (__suaveplan_alloc / free / handle_request / routes / start / dispose + memory) at bridge-init, marshals SerializedRequest bytes into linear memory via__suaveplan_alloc, invokes __suaveplan_handle_request, reads the packed (responsePtr, responseLen) result, JSON-decodes the SerializedResponse, and unmarshals it back to a host Response. Traps surface as SAND_WASM_BRIDGE.HANDLER_TRAPPED with classified trapKind; denied capabilities surface as SAND_PERM.DENIED. Host-integration layer that wraps a `@suaveplan/api-sandbox-wasm` `WasmSandboxHandle` as a `@suaveplan/api-host` `PluginModule`. Sandboxed-tier plugins compiled to WebAssembly export the `__suaveplan_*` ABI surface (`memory`, `__suaveplan_alloc`, `__suaveplan_free`, `__suaveplan_handle_request`, `__suaveplan_routes`, `__suaveplan_start`, `__suaveplan_dispose`); this bridge validates that surface, discovers the guest's routes once at bridge-init time, and emits per-route closures that marshal `SerializedRequest` records through the guest's linear memory. ## Documentation tree - [bridge](./src/bridge/bridge.md) — `createSandboxedWasmPluginModule({ sandbox, manifest })` is the public entry point of `@suaveplan/api-sandbox-wasm-host… - [bridge](./src/bridge/bridge.md) — `createSandboxedWasmPluginModule({ sandbox, manifest })` is the public entry point of `@suaveplan/api-sandbox-wasm-host… - [error-codes](./src/error-codes/error-codes.md) — Defines the seven stable `SAND_WASM_BRIDGE.*` error codes raised on production paths in `@suaveplan/api-sandbox-wasm-ho… - [error-codes](./src/error-codes/error-codes.md) — Defines the seven stable `SAND_WASM_BRIDGE.*` error codes raised on production paths in `@suaveplan/api-sandbox-wasm-ho… - [instruments](./src/instruments/instruments.md) — `createSandboxWasmBridgeInstruments(config)` constructs the OTel counter + histogram registry every production path in… - [instruments](./src/instruments/instruments.md) — `createSandboxWasmBridgeInstruments(config)` constructs the OTel counter + histogram registry every production path in… - [lifecycle](./src/lifecycle/lifecycle.md) — `createIdempotentLifecycle(deps)` returns the `start` / `dispose` pair the bridge installs on the host's `PluginModule.… - [lifecycle](./src/lifecycle/lifecycle.md) — `createIdempotentLifecycle(deps)` returns the `start` / `dispose` pair the bridge installs on the host's `PluginModule.… - [marshal](./src/marshal/marshal.md) — Encodes a `SerializedRequest` to UTF-8 JSON bytes for transport into the guest's linear memory and decodes the matching… - [marshal](./src/marshal/marshal.md) — Encodes a `SerializedRequest` to UTF-8 JSON bytes for transport into the guest's linear memory and decodes the matching… - [memory](./src/memory/memory.md) — Wraps the four primitive operations the host bridge performs against the guest's linear memory: allocating a buffer via… - [memory](./src/memory/memory.md) — Wraps the four primitive operations the host bridge performs against the guest's linear memory: allocating a buffer via… - [trap-classifier](./src/memory/trap-classifier.md) — `classifyTrap(cause)` maps a raw `WebAssembly.RuntimeError` (or any thrown value the bridge catches around a guest call… - [route-discovery](./src/route-discovery/route-discovery.md) — `discoverRoutes(exports, pluginName)` calls the guest's `__suaveplan_routes` export exactly once at bridge-init time, u… - [route-discovery](./src/route-discovery/route-discovery.md) — `discoverRoutes(exports, pluginName)` calls the guest's `__suaveplan_routes` export exactly once at bridge-init time, u… - [wasm-host-bridge-conformance](./src/testing/wasm-host-bridge-conformance/wasm-host-bridge-conformance.md) — `runWasmHostBridgeConformance({ buildBridge })` is the contract test every wasm host-bridge configuration must pass. Th… - [wasm-host-bridge-conformance](./src/testing/wasm-host-bridge-conformance/wasm-host-bridge-conformance.md) — `runWasmHostBridgeConformance({ buildBridge })` is the contract test every wasm host-bridge configuration must pass. Th… - [abi-validator](./src/wasm-abi/abi-validator.md) — `validateWasmAbi(instance, pluginName)` performs the bridge-init-time ABI check that gates every other operation in `@s… - [abi](./src/wasm-abi/abi.md) — Declares the `__suaveplan_*` ABI surface a sandboxed WASM plugin must export for `@suaveplan/api-sandbox-wasm-host-brid… ## Install ```bash bun add @suaveplan/api-sandbox-wasm-host-bridge ``` Peer-style dependencies (already required by any host that boots sandboxed-tier plugins): - `@suaveplan/api-host` - `@suaveplan/api-sandbox-permissions` - `@suaveplan/api-sandbox-wasm` - `@suaveplan/api-types` ## Basic usage ```ts import { createWasmSandbox } from "@suaveplan/api-sandbox-wasm"; import { createSandboxedWasmPluginModule } from "@suaveplan/api-sandbox-wasm-host-bridge"; const sandbox = await createWasmSandbox({ pluginName: "example", policy, capabilities, checker, wasmBytes, }); const install = createSandboxedWasmPluginModule({ sandbox, manifest }); await host.installPlugin({ module: install.module, manifest: install.manifest, manifestHash, specifier: "example@0.1.0", routes: install.routes, }); ``` ## Conformance The package ships `runWasmHostBridgeConformance({ buildBridge })` under `./testing`. Five invariants — route registration, request round-trip, lifecycle idempotency, trap propagation, and capability-gate fidelity — are asserted against the supplied factory. The harness uses a hand-encoded WASM fixture (no `wabt` build step) so the test suite has no external compile-time dependency. ## Error codes `SAND_WASM_BRIDGE.*`: `INVALID_PLUGIN_SURFACE`, `MEMORY_ALLOC_FAILED`, `MARSHAL_FAILED`, `UNMARSHAL_FAILED`, `HANDLER_TRAPPED`, `CAPABILITY_DENIED`, `LIFECYCLE_FAILED`. Capability denials are surfaced through the canonical `SAND_PERM.DENIED` code from `@suaveplan/api-sandbox-permissions`.