first commit

docs/foundation/data/packer-browser/src/error-codes/error-codes.md

@@ -0,0 +1,89 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`error-codes.ts` is the single source of truth for every error class and
+stable code emitted by `@suaveplan/packer-browser`. It registers the
+`PACKER_BROWSER_CODES` constant via `defineCodes` from `@suaveplan/error`
+so the wire-serialiser, OTel adapter, and i18n resolver in the broader
+error stack pick up the codes automatically. Every production path that
+throws routes through `PackerBrowserError` so consumers can classify
+failures without string-matching message text.
+
+## Features
+
+- Six stable codes covering the Cluster A failure surface:
+  `RESOURCE_NOT_FOUND`, `SW_REGISTRATION_FAILED`,
+  `ARCHIVE_SIGNATURE_INVALID`, `UNSUPPORTED_RESOURCE_TYPE`, `ABORTED`,
+  `LOAD_FAILED`.
+- `PackerBrowserError extends SuaveplanError<TCode>` with `.name`
+  branded `"PackerBrowserError"` so logger sinks render structured
+  output.
+- `PACKER_BROWSER_ERROR_METADATA` table mapping every code to
+  `{ httpStatus, severity, retryable, description }` — consumed by
+  HTTP boundary middleware and retry policies.
+
+## Usage: Basic
+
+```ts
+import {
+    PACKER_BROWSER_CODES,
+    PackerBrowserError,
+} from "@suaveplan/packer-browser";
+
+throw new PackerBrowserError(
+    PACKER_BROWSER_CODES.RESOURCE_NOT_FOUND,
+    "Packed resource fetch returned HTTP 404."
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    PACKER_BROWSER_CODES,
+    PACKER_BROWSER_ERROR_METADATA,
+    PackerBrowserError,
+} from "@suaveplan/packer-browser";
+
+try {
+    await manager.load("/missing.packed");
+} catch (err) {
+    if (err instanceof PackerBrowserError) {
+        const meta =
+            PACKER_BROWSER_ERROR_METADATA[
+                err.code as keyof typeof PACKER_BROWSER_ERROR_METADATA
+            ];
+        if (meta.retryable) {
+            // schedule a retry
+        }
+    }
+}
+```
+
+## API Reference
+
+- `PACKER_BROWSER_CODES` — frozen record mapping bare code names
+  (e.g. `RESOURCE_NOT_FOUND`) to their fully-qualified form
+  (`"PACKER_BROWSER.RESOURCE_NOT_FOUND"`).
+- `PackerBrowserErrorCode` — union of every value in
+  `PACKER_BROWSER_CODES`.
+- `PACKER_BROWSER_ERROR_METADATA[code]` —
+  `{ httpStatus: number; severity: "info" | "warning" | "error"; retryable: boolean; description: string }`.
+- `class PackerBrowserError<TCode> extends SuaveplanError<TCode>` —
+  constructor `(code, message, options?)`.
+
+## Implementation Notes
+
+The registry is intentionally exhaustive of the Cluster A surface, not
+of the eventual public contract — Cluster B (encrypted-archive keyring)
+and Cluster C (BackgroundFetch / range / multi-origin) will extend the
+list. Every existing code is reachable from a production call site;
+unused entries are banned by CLAUDE.md §2c and would fail the
+conformance gate. The metadata `httpStatus` field is the value
+to surface from any HTTP-boundary translator (e.g. a Hono middleware)
+that re-renders a `PackerBrowserError` as an outbound response.