# Error codes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module owns the stable `SAND_VM_BRIDGE.*` error-code registry used
by every public failure path inside the host bridge. The registry is
built once via `defineCodes("SAND_VM_BRIDGE", […])` so the namespace
prefix and per-code suffix are co-derived — that guarantee lets the
host's error boundary, audit sink, and the conformance harness branch
on literal code strings without ever decoding free-form messages.

Side-effect-importing this module from `src/index.ts` ensures every
consumer that imports the package barrel (or any subpath export)
participates in the same registration that the
`scripts/conformance.ts` audit walks.

## Features

- Five stable codes — `INVALID_PLUGIN_SURFACE`, `MARSHAL_FAILED`,
  `UNMARSHAL_FAILED`, `HANDLER_REJECTED`, `LIFECYCLE_FAILED` — each
  mapped to exactly one failure surface inside the bridge.
- A typed `SandboxVmBridgeError` subclass of `SuaveplanError` so
  consumers may discriminate via `instanceof` or by `code` string.
- A public constructor (`new SandboxVmBridgeError(code, message,
  options?)`) so consumers can synthesise the error at the host edge
  when re-wrapping a non-`SuaveplanError` cause.

## Usage: Basic

```ts
import {
    SAND_VM_BRIDGE_CODES,
    SandboxVmBridgeError,
} from "@suaveplan/api-sandbox-vm-host-bridge/error-codes/error-codes";

throw new SandboxVmBridgeError(
    SAND_VM_BRIDGE_CODES.MARSHAL_FAILED,
    "request body type is not supported by the bridge marshal layer"
);
```

## Usage: Advanced

Preserve the sandbox-side cause so the host's error boundary can walk
the chain back to the original `SandboxVmError`:

```ts
import {
    SAND_VM_BRIDGE_CODES,
    SandboxVmBridgeError,
} from "@suaveplan/api-sandbox-vm-host-bridge/error-codes/error-codes";

try {
    await invokeHandler();
} catch (err) {
    throw new SandboxVmBridgeError(
        SAND_VM_BRIDGE_CODES.HANDLER_REJECTED,
        "sandboxed handler threw",
        { cause: err, context: { route: "/foo", method: "GET" } }
    );
}
```

## API Reference

- `SAND_VM_BRIDGE_CODES` — frozen record mapping enum key (e.g.
  `HANDLER_REJECTED`) to the namespaced string code
  (`"SAND_VM_BRIDGE.HANDLER_REJECTED"`).
- `type SandboxVmBridgeCode` — literal union of every value in
  `SAND_VM_BRIDGE_CODES`.
- `class SandboxVmBridgeError extends SuaveplanError<SandboxVmBridgeCode>`
  — public constructor `(code, message, options?)`. `options.cause`
  preserves the original sandbox throw for the host's cause-chain
  walker.

## Implementation Notes

The registry is declared `as const` so the compiler retains literal
types — essential for exhaustive `switch` narrowing in the bridge's
internal dispatch. The class sets `this.name = "SandboxVmBridgeError"`
so heap snapshots, sourcemaps and uncaught-exception handlers
attribute failures to this package rather than the generic
`SuaveplanError` superclass. Registry ordering reflects the request
lifecycle: discovery first, then per-request marshal failures, then
the in-handler reject, then lifecycle failures last.