# `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.