first commit

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

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