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