suaveplan/openspec/changes/api-sandbox-wasm-host-bridge/tasks.md

Tasks — Sandbox WASM Host Bridge

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree and no in-flight worktrees with uncommitted work
• 0.2 Account for every worktree under .claude/worktrees/
• 0.3 MANIFEST.md package count matches find packages -maxdepth 3 -name package.json
• 0.4 §0a Sync: worktree-isolated agents fast-forward to orchestrator-supplied SHA

1. Dependency check

• 1.1 @suaveplan/api-types/sandbox-bridge subpath exists (authored by this change ahead of the sibling vm-bridge merge).
• 1.2 @suaveplan/api-sandbox-wasm exists with WasmSandboxHandle surface.
• 1.3 @suaveplan/api-host.installPlugin accepts the PluginModule shape (bridge returns SandboxedWasmPluginInstall carrying both module and routes).

2. Package scaffold

• 2.1 packages/api-stack/api/api-sandbox-wasm-host-bridge/ with package.json, tsconfig, vite, vitest configs.
• 2.2 Deps: @suaveplan/api-sandbox-wasm, @suaveplan/api-host, @suaveplan/api-types, @suaveplan/api-sandbox-permissions, @suaveplan/error, tslib, zod.

3. Implementation

• 3.1 src/bridge/bridge.ts — createSandboxedWasmPluginModule({ sandbox, manifest }) factory.
• 3.2 src/wasm-abi/abi.ts — __suaveplan_alloc/free/handle_request/routes/start/dispose export-name constants + signatures.
• 3.3 src/wasm-abi/abi-validator.ts — validates the WASM module exports all required functions before bridge init.
• 3.4 src/marshal/marshal.ts — JSON-encode SerializedRequest into linear memory, decode SerializedResponse out.
• 3.5 src/memory/memory.ts — alloc/free wrappers with trap protection.
• 3.6 src/route-discovery/route-discovery.ts — calls __suaveplan_routes at init time.
• 3.7 src/lifecycle/lifecycle.ts — __suaveplan_start / __suaveplan_dispose forwarders with idempotency.
• 3.8 src/error-codes/error-codes.ts — 7 SAND_WASM_BRIDGE codes + SandboxWasmBridgeError with public constructor.
• 3.9 src/instruments/instruments.ts — bridge OTel counters.
• 3.10 Paired .md per implementation file.

4. Conformance harness

• 4.1 src/testing/wasm-host-bridge-conformance/wasm-host-bridge-conformance.ts with 5 invariants.
• 4.2 Sibling .md, .types.ts, .test.ts, index.ts.

5. Tests

• 5.1 tests/fixtures/build-wasm.ts — hand-coded minimal WASM binary that exports the suaveplan ABI (returns canned routes + response). No external compile dep.
• 5.2 Real api-sandbox-wasm + real api-host integration test in tests/integration/full-flow.test.ts against the fixture WASM.
• 5.3 100% istanbul coverage on touched modules.
• 5.4 Public-constructor lint clean.
• 5.5 bunx --bun turbo lint typecheck test:coverage --filter=@suaveplan/api-sandbox-wasm-host-bridge green.

6. Archive

• 6.1 Fold delta into openspec/specs/api-sandbox-wasm-host-bridge/spec.md. (deferred to merge step)
• 6.2 Move folder → openspec/archive/2026-05-27-api-sandbox-wasm-host-bridge/. (deferred to merge step)
• 6.3 Refresh MANIFEST.md.