WASM ABI surface

Purpose

Declares the __suaveplan_* ABI surface a sandboxed WASM plugin must export for @suaveplan/api-sandbox-wasm-host-bridge to wrap it as a host PluginModule. The REQUIRED_WASM_ABI_SYMBOLS constant is the canonical, sorted list the validator compares against the instance's actual exports; the matching WasmAbiExports type-level view in abi.types.ts gives the bridge a strongly-typed handle on the export bag after validation.

Features

Single source-of-truth for the ABI: changing the surface here ripples through the validator, marshaller, route-discovery helper, and the fixture WASM builder used by the conformance harness.
Sorted alphabetically so context.missing arrays are deterministic across runs — the foundation redact codepath and snapshot tests both rely on this stability.
Frozen at module load via Object.freeze so consumers cannot accidentally mutate the contract.
Pairs with RequiredWasmAbiSymbol (a union of literal strings) so TypeScript narrows array element types automatically.

Usage: Basic

import { REQUIRED_WASM_ABI_SYMBOLS } from "@suaveplan/api-sandbox-wasm-host-bridge/wasm-abi";

console.log(REQUIRED_WASM_ABI_SYMBOLS);
// → ["__suaveplan_alloc", "__suaveplan_dispose", "__suaveplan_free",
//    "__suaveplan_handle_request", "__suaveplan_routes",
//    "__suaveplan_start", "memory"]

Usage: Advanced

import {
    REQUIRED_WASM_ABI_SYMBOLS,
    type WasmAbiExports,
} from "@suaveplan/api-sandbox-wasm-host-bridge/wasm-abi";

function missingExports(
    instance: WebAssembly.Instance,
): readonly string[] {
    const present = new Set(Object.keys(instance.exports));
    return REQUIRED_WASM_ABI_SYMBOLS.filter((name) => !present.has(name));
}

function typedExports(instance: WebAssembly.Instance): WasmAbiExports {
    return instance.exports as unknown as WasmAbiExports;
}

API Reference

REQUIRED_WASM_ABI_SYMBOLS: readonly RequiredWasmAbiSymbol[] — alphabetically sorted, frozen.
RequiredWasmAbiSymbol — "memory" | "__suaveplan_alloc" | "__suaveplan_dispose" | "__suaveplan_free" | "__suaveplan_handle_request" | "__suaveplan_routes" | "__suaveplan_start".
WasmAbiExports — readonly record interface mapping each symbol to its typed signature; consumed by bridge.ts.

Implementation Notes

The constant is split out from the validator function so the fixture WASM builder under tests/fixtures/ can iterate the same list to generate exports in lockstep with the runtime check — keeping both ends of the contract drift-free. Sorting alphabetically (instead of "logical-order") is deliberate: it makes the context.missing diagnostic stable under any future reordering of the symbol list, and matches the foundation's general policy of "set-shape diagnostics use sorted output".

2.8 KiB Raw Blame History