first commit

docs/api-stack/api/api-router-hono/src/error-codes/error-codes.md

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