suaveplan/packages/api-stack/api/api-sandbox-wasm-host-bridge/README.md

@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 — createSandboxedWasmPluginModule({ sandbox, manifest }) is the public entry point of `@suaveplan/api-sandbox-wasm-host…
  • bridge — createSandboxedWasmPluginModule({ sandbox, manifest }) is the public entry point of `@suaveplan/api-sandbox-wasm-host…
• error-codes — Defines the seven stable SAND_WASM_BRIDGE.* error codes raised on production paths in `@suaveplan/api-sandbox-wasm-ho…
  • error-codes — Defines the seven stable SAND_WASM_BRIDGE.* error codes raised on production paths in `@suaveplan/api-sandbox-wasm-ho…
• instruments — createSandboxWasmBridgeInstruments(config) constructs the OTel counter + histogram registry every production path in…
  • instruments — createSandboxWasmBridgeInstruments(config) constructs the OTel counter + histogram registry every production path in…
• lifecycle — createIdempotentLifecycle(deps) returns the start / dispose pair the bridge installs on the host's `PluginModule.…
  • lifecycle — createIdempotentLifecycle(deps) returns the start / dispose pair the bridge installs on the host's `PluginModule.…
• marshal — Encodes a SerializedRequest to UTF-8 JSON bytes for transport into the guest's linear memory and decodes the matching…
  • marshal — Encodes a SerializedRequest to UTF-8 JSON bytes for transport into the guest's linear memory and decodes the matching…
• memory — Wraps the four primitive operations the host bridge performs against the guest's linear memory: allocating a buffer via…
  • memory — Wraps the four primitive operations the host bridge performs against the guest's linear memory: allocating a buffer via…
  • trap-classifier — classifyTrap(cause) maps a raw WebAssembly.RuntimeError (or any thrown value the bridge catches around a guest call…
• route-discovery — discoverRoutes(exports, pluginName) calls the guest's __suaveplan_routes export exactly once at bridge-init time, u…
  • route-discovery — discoverRoutes(exports, pluginName) calls the guest's __suaveplan_routes export exactly once at bridge-init time, u…
• wasm-host-bridge-conformance — runWasmHostBridgeConformance({ buildBridge }) is the contract test every wasm host-bridge configuration must pass. Th…
  • wasm-host-bridge-conformance — runWasmHostBridgeConformance({ buildBridge }) is the contract test every wasm host-bridge configuration must pass. Th…
• abi-validator — validateWasmAbi(instance, pluginName) performs the bridge-init-time ABI check that gates every other operation in `@s…
• abi — Declares the __suaveplan_* ABI surface a sandboxed WASM plugin must export for `@suaveplan/api-sandbox-wasm-host-brid…

Install

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

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.