first commit

docs/api-stack/api/api-sandbox-wasm-host-bridge/src/abi-direct/wasm-abi/abi.md

@@ -0,0 +1,53 @@
+# 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
+
+```ts
+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
+
+```ts
+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".