# `error-codes` — stable Router-Hono error registry

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

This module defines the canonical, frozen error-code namespace `ROUTER_HONO.*` shared by every production path inside `@suaveplan/api-router-hono`. Stable codes are how downstream observers (`@suaveplan/api-host`, structured-log consumers, OpenTelemetry dashboards) discriminate adapter failures from generic application errors without resorting to brittle string matching on `error.message`.

The registry is intentionally narrow — Hono itself owns most failure modes (404, 405, body parse, etc.) and surfaces them as ordinary HTTP responses. The two `ROUTER_HONO.*` codes carved out here cover the two scenarios where the adapter cannot delegate cleanly to Hono: a Hono-internal throw bubbling through the bridge, and a programmer-supplied peer (`getHonoApp()` consumers handing back a non-Hono shim).

## Features

- `ROUTER_HONO.HONO_INTERNAL_ERROR` — wraps any unexpected throw originating inside the Hono request/response bridge.
- `ROUTER_HONO.INVALID_HONO_PEER` — guard for the `getHonoApp()` accessor and middleware-adapter when a non-Hono value is supplied.
- `RouterHonoError` extends `SuaveplanError<RouterHonoCode>` so cause chains and Zod-validated wire format flow through `@suaveplan/error` unchanged.
- `defineCodes` produces a frozen, namespaced map — duplicate codes fail at module load.

## Usage: Basic

```ts
import { ROUTER_HONO_CODES, RouterHonoError } from "@suaveplan/api-router-hono/error-codes";

throw new RouterHonoError(
    ROUTER_HONO_CODES.HONO_INTERNAL_ERROR,
    "hono raised during dispatch",
    { cause: caught },
);
```

## Usage: Advanced

```ts
import { RouterHonoError } from "@suaveplan/api-router-hono/error-codes";
import type { RouterHonoCode } from "@suaveplan/api-router-hono/error-codes";

function handle(err: unknown): RouterHonoCode | null {
    if (err instanceof RouterHonoError) return err.code;
    return null;
}
```

## API Reference

- `ROUTER_HONO_CODES` — `Readonly<Record<"HONO_INTERNAL_ERROR" | "INVALID_HONO_PEER", "ROUTER_HONO.HONO_INTERNAL_ERROR" | "ROUTER_HONO.INVALID_HONO_PEER">>`.
- `RouterHonoCode` — string-literal union of the resolved codes.
- `RouterHonoError` — `SuaveplanError<RouterHonoCode>` subclass with `code`, `message`, optional `cause`, optional `context`.

## Implementation Notes

`defineCodes` enforces alphabetisation and uniqueness at build time. Adding a code requires extending the tuple here AND wiring at least one production throw site (see `adapter.ts` and `middleware-adapter.ts`). The registry is consumed by the `error-codes.test.ts` enumeration which asserts every entry maps to a value of the form `ROUTER_HONO.<NAME>` so observers can pattern-match the namespace prefix.