first commit

docs/api-stack/api/api-sandbox-vm-host-bridge/src/error-codes/error-codes.md

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