Initial Commit

packages/api-stack/api/wasm-compiler-javy/src/error-codes/error-codes.md

@@ -0,0 +1,65 @@
+# `WASM_COMPILER` error codes
+
+## Purpose
+
+This module defines the six stable error codes raised by the TS->WASM compiler and the concrete `WasmCompilerError` class every production path throws. The codes name the failure modes exhaustively: the bundle step (`BUNDLE_FAILED`), bundler input rejections (`BROWSER_INCOMPAT_DEPENDENCY`), the platform-locate step (`JAVY_PLATFORM_MISMATCH`), the Javy spawn step (`JAVY_INVOCATION_FAILED`), the post-Javy ABI reflection (`ABI_VALIDATION_FAILED`), and the route-extraction probe (`MANIFEST_MISSING_ROUTES`).
+
+Stability matters because callers (`@suaveplan/api-host` operators, CI gates, plugin operators) branch on `error.code` rather than parsing free-form messages. The code registry is built via `@suaveplan/error`'s `defineCodes` so each code is a frozen `"WASM_COMPILER.<NAME>"` string literal, and TypeScript can narrow `error.code` to the `WasmCompilerCode` union for exhaustive switches.
+
+## Features
+
+- `WASM_COMPILER_CODES` — frozen `defineCodes` registry of all six codes.
+- `WasmCompilerCode` — exhaustive union type.
+- `WasmCompilerError` — `SuaveplanError` subclass with a **public** constructor (rule §19), carrying the namespaced code and i18n message key.
+- `WASM_COMPILER_ERROR_NAME` — stable `error.name` (`"WasmCompilerError"`) for cross-realm `instanceof` fallbacks.
+
+## Usage: Basic
+
+```ts
+import { WASM_COMPILER_CODES, WasmCompilerError } from "@suaveplan/wasm-compiler-javy";
+
+throw new WasmCompilerError(
+    WASM_COMPILER_CODES.JAVY_PLATFORM_MISMATCH,
+    "error.wasm_compiler.javy_platform_mismatch",
+    { context: { requested: "freebsd-x64" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import { WasmCompilerError } from "@suaveplan/wasm-compiler-javy";
+
+try {
+    await compilePluginToWasm({ pluginEntry, outDir });
+} catch (err) {
+    if (err instanceof WasmCompilerError) {
+        switch (err.code) {
+            case "WASM_COMPILER.BUNDLE_FAILED":
+            case "WASM_COMPILER.BROWSER_INCOMPAT_DEPENDENCY":
+                console.error("bundle:", err.message);
+                break;
+            case "WASM_COMPILER.JAVY_PLATFORM_MISMATCH":
+            case "WASM_COMPILER.JAVY_INVOCATION_FAILED":
+                console.error("javy:", err.message);
+                break;
+            case "WASM_COMPILER.ABI_VALIDATION_FAILED":
+            case "WASM_COMPILER.MANIFEST_MISSING_ROUTES":
+                console.error("post-compile:", err.message);
+                break;
+        }
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+- `WASM_COMPILER_CODES: Readonly<Record<"BUNDLE_FAILED" | "BROWSER_INCOMPAT_DEPENDENCY" | "JAVY_PLATFORM_MISMATCH" | "JAVY_INVOCATION_FAILED" | "ABI_VALIDATION_FAILED" | "MANIFEST_MISSING_ROUTES", string>>`.
+- `type WasmCompilerCode = (typeof WASM_COMPILER_CODES)[keyof typeof WASM_COMPILER_CODES]`.
+- `class WasmCompilerError extends SuaveplanError<WasmCompilerCode>` — public constructor taking `(code, messageKey, options?)`.
+- `const WASM_COMPILER_ERROR_NAME = "WasmCompilerError"`.
+
+## Implementation Notes
+
+The class extends the framework's `SuaveplanError<TCode>`, providing the namespace-qualified `code`, an i18n `messageKey`, and the `cause`/`context` plumbing every `@suaveplan` package shares. The public constructor satisfies rule §19 (catches stale `// biome-ignore` suppressions where subclasses redeclared protected constructors as private). Every throw site in this package allocates one of these — no naked `Error`s — so `instanceof WasmCompilerError` is sufficient to distinguish compiler failures from unrelated runtime errors at the boundary.