# @suaveplan/wasm-compiler-javy

TS->WASM compiler closing **Stage-8 gate 2.8**. Thin orchestrator around `Bun.build` (bundle) + an injected WASI-stdio ABI shim + **Javy v8.1.1** (JS->WASM) + `WebAssembly.compile` (ABI validation) + a host-side route-extraction probe + manifest sidecar emit.

The produced `.wasm` artifact speaks the WASI-stdio length-prefixed JSON framing protocol shared with `@suaveplan/api-sandbox-wasm-host-bridge`, so any plugin compiled here is deployable through `abiVariant: "wasi-stdio"` without further glue.

## Pipeline

```text
pluginEntry  ──[1]──>  bundled ESM JS  ──[2]──>  ABI-shimmed JS  ──[3]──>  .wasm  ──[4]──>  validate  ──[5]──>  route extract  ──[6]──>  manifest
                Bun.build           prepend WASI-stdio loop   javy build       reflect imports/exports     {kind:"routes"} probe     <basename>.wasm.json
```

## Public surface

```ts
import { compilePluginToWasm } from "@suaveplan/wasm-compiler-javy";

const result = await compilePluginToWasm({
    pluginEntry: "/abs/path/to/plugin/src/index.ts",
    outDir: "/tmp/plugin-wasm",
    optimizeFor: "size",   // default
    sourcemaps: false,      // default
});
// result: { wasmPath, metadataPath, sizeBytes, compilationMs, manifest }
```

CLI binary: `suaveplan-wasm-compile <entry> --out-dir <dir> [--optimize-for size|speed] [--sourcemaps]`.

## Conformance harness

```ts
import { runWasmCompilerConformance } from "@suaveplan/wasm-compiler-javy/testing";
```

Four invariants: ABI completeness, deterministic output, manifest fidelity, cross-bridge deployability.

## Error codes

`WASM_COMPILER.{BUNDLE_FAILED, BROWSER_INCOMPAT_DEPENDENCY, JAVY_PLATFORM_MISMATCH, JAVY_INVOCATION_FAILED, ABI_VALIDATION_FAILED, MANIFEST_MISSING_ROUTES}` — 6 codes via `defineCodes`, error class with **public constructor** (rule §19).

## OTel instruments

- `wasm_compiler.compiles_total{result}` (counter).
- `wasm_compiler.compile_duration_ms{result}` (histogram).
- `wasm_compiler.abi_validation_failures_total{missing_export}` (counter).

## Platform support

Javy binaries are downloaded at install time by the platform-specific wrapper packages: `@suaveplan/javy-cli-{linux-x64,linux-arm64,darwin-x64,darwin-arm64,win32-x64}`. The compiler resolves the matching wrapper via `optionalDependencies` so a single `bun install` stays cross-platform-safe.