first commit

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

@@ -0,0 +1,86 @@
+# error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable `SAND_WASM.*` error-code registry and the
+`SandWasmError` subclass thrown by every production path inside the
+WASM sandbox host. Concentrating codes in a single module keeps the
+catch sites code-matchable (no message-string parsing) and lets the
+repo-wide conformance gate verify every documented code is
+thrown from at least one non-test source file.
+
+The registry is frozen at module load via `defineCodes` so accidental
+mutation surfaces immediately, and the side-effect import from the
+package's `src/index.ts` ensures any consumer that touches the public
+surface registers the namespace.
+
+## Features
+
+- `SAND_WASM_CODES` — frozen literal map of every code.
+- `SandWasmError` — `SuaveplanError` subclass with a public constructor
+  (required by `scripts/lint/check-error-subclass-constructors.ts`).
+- `SAND_WASM_ERROR_NAME` — stable `error.name` for logger aggregation.
+- `SandWasmCode` — type-level union for catch-site discrimination.
+
+## Usage: Basic
+
+```ts
+import {
+    SAND_WASM_CODES,
+    SandWasmError,
+} from "@suaveplan/api-sandbox-wasm/error-codes";
+
+throw new SandWasmError(
+    SAND_WASM_CODES.OUTBOUND_DENIED,
+    "error.sand_wasm.outbound_denied",
+    { context: { destination: "evil.example.com" } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+try {
+    await createWasmSandbox({ ... });
+} catch (err) {
+    if (err instanceof SandWasmError) {
+        switch (err.code) {
+            case SAND_WASM_CODES.INSTANTIATION_FAILED:
+                metrics.increment("plugin.instantiation_failed");
+                break;
+            case SAND_WASM_CODES.WASI_VERSION_UNSUPPORTED:
+                logger.error("Unsupported WASI version", err.context);
+                break;
+        }
+    }
+}
+```
+
+## API Reference
+
+- `SAND_WASM_CODES.INSTANTIATION_FAILED` — compile or instantiate threw.
+- `SAND_WASM_CODES.WASI_VERSION_UNSUPPORTED` — module imports a WASI
+  namespace not on the allowlist.
+- `SAND_WASM_CODES.PREOPEN_DENIED` — `path_open` resolved outside any
+  preopen OR requested write against a read-only preopen.
+- `SAND_WASM_CODES.OUTBOUND_DENIED` — `sock_connect` destination not in
+  `policy.fetch[]`.
+
+## Implementation Notes
+
+The `SuaveplanError` base class has a `protected constructor`. Without
+the public re-declaration in the subclass, callers cannot `new
+SandWasmError(...)` (TS2674). The repo's
+`check-error-subclass-constructors.ts` lint gate enforces this — a
+missing public constructor has surfaced four times in other packages,
+which is why the rule exists.
+
+Codes are kept in alphabetical order in tests but emitted in spec order
+in the registry to match the proposal's enumeration. The
+registry is frozen, so adding a new code requires editing both this
+module AND its `.test.ts` AND extending the spec delta — three-way
+diffing keeps drift visible during code review.