# Error codes

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

## Purpose

This module owns the stable `SAND_VM.*` error-code registry used by every
public failure path inside the `@suaveplan/api-sandbox-vm` package. The
registry is built once via `defineCodes("SAND_VM", […])` so the
namespace prefix and per-code suffix are co-derived — that guarantee
lets the host's lifecycle driver, the audit sink, and the conformance
harness branch on literal code strings without ever decoding free-form
error 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 code registration, which is what
`scripts/conformance.ts` validates.

## Features

- Five stable codes (`EVAL_REJECTED`, `INDIRECT_EVAL_REJECTED`,
  `MODULE_IMPORT_FORBIDDEN`, `SOURCE_TEXT_MODULE_FAILED`,
  `PERMISSION_DENIED`) — every failure surface in the package maps to
  exactly one.
- A typed `SandboxVmError` subclass of `SuaveplanError` so consumers
  may discriminate via `instanceof` or by `code` string.
- Wire-stable `code` string: the namespaced form (e.g.
  `"SAND_VM.EVAL_REJECTED"`) is the value used in OTel attributes,
  audit logs, and IPC envelopes back to the host.

## Usage: Basic

```ts
import {
    SAND_VM_CODES,
    SandboxVmError,
} from "@suaveplan/api-sandbox-vm/error-codes/error-codes";

throw new SandboxVmError(
    SAND_VM_CODES.EVAL_REJECTED,
    "dynamic code evaluation is disabled in the vm sandbox"
);
```

## Usage: Advanced

Use the `context` option to attach a redaction-safe payload that flows
through to OTel span attributes and the lifecycle driver's crash
report:

```ts
import {
    SAND_VM_CODES,
    SandboxVmError,
} from "@suaveplan/api-sandbox-vm/error-codes/error-codes";

function denyOutboundFetch(host: string, reason: string): never {
    throw new SandboxVmError(
        SAND_VM_CODES.PERMISSION_DENIED,
        `outbound HTTP to ${host} denied by policy`,
        {
            context: { capability: "fetch", host, reason },
        }
    );
}
```

## API Reference

- `SAND_VM_CODES` — frozen record mapping enum key (e.g.
  `EVAL_REJECTED`) to the namespaced string code
  (`"SAND_VM.EVAL_REJECTED"`).
- `type SandboxVmCode` — the literal union of every value in
  `SAND_VM_CODES`.
- `class SandboxVmError extends SuaveplanError<SandboxVmCode>` —
  constructor takes `(code, message, options?)`. `options.context` is
  forwarded through the base class redaction pipeline.

## Implementation Notes

The registry is declared `as const` so the compiler retains literal
types (essential for exhaustive `switch` narrowing in consumers). The
class sets `this.name = "SandboxVmError"` so heap snapshots, sourcemaps
and uncaught-exception handlers attribute failures to this package
rather than the generic `SuaveplanError` super-class. Registry
ordering reflects severity in roughly increasing order — the first two
entries reflect deliberate plugin policy violations, the next two
reflect host-environment misconfiguration, and the last reflects
permission-policy denials that fan in from `api-sandbox-permissions`.