# 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".