Initial Commit

packages/api-stack/api/wasm-compiler-javy/README.md

@@ -0,0 +1,50 @@
+# @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.