first commit

docs/api-stack/api/api-ws-bun/src/error-codes/error-codes.md

@@ -0,0 +1,63 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Provides the stable error-code registry and the typed `WsBunError` subclass for `@suaveplan/api-ws-bun`. Every production failure path in the package routes through one of the ten `WS_BUN.*` codes defined here, which means a downstream consumer can branch on `error.code === WS_BUN_CODES.TENANT_CAP_EXCEEDED` without importing implementation modules.
+
+The constants are frozen at module load time by `defineCodes` from `@suaveplan/error`, so consumers can compare against the namespaced literal string (`"WS_BUN.HANDSHAKE_REJECTED"`) directly when that is convenient — for example inside a JSON-serialised error wire format or a Hono error handler.
+
+## Features
+
+- Ten-entry registry covering handshake, tenant caps, backpressure, heartbeat, reconnect token validation, reconnect-buffer wiring, subprotocols, close timeouts and principal expiry.
+- `WsBunError` extends `SuaveplanError<WsBunErrorCode>` so `instanceof` narrows the `code` field to the registry's literal union.
+- One `raise*` helper per code so every entry has a production throw-site (CI checklist 6.3).
+- Helpers attach a stable message prefix per code so logs stay grep-able.
+
+## Usage: Basic
+
+```ts
+import { raiseTenantCapExceeded, WS_BUN_CODES } from "@suaveplan/api-ws-bun";
+
+try {
+    raiseTenantCapExceeded("tenant-a", 1000);
+} catch (err) {
+    if ((err as { code?: string }).code === WS_BUN_CODES.TENANT_CAP_EXCEEDED) {
+        // surface 429 to the caller
+    }
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    WS_BUN_CODES,
+    WsBunError,
+    type WsBunErrorCode,
+} from "@suaveplan/api-ws-bun";
+
+function logIfWsBun(error: unknown, logger: { error: (m: string) => void }) {
+    if (error instanceof WsBunError) {
+        const code: WsBunErrorCode = error.wsBunCode;
+        logger.error(`${code}: ${error.message}`);
+        return code === WS_BUN_CODES.HEARTBEAT_FAILED;
+    }
+    return false;
+}
+```
+
+## API Reference
+
+- `WS_BUN_CODES` — frozen `Record<LiteralName, "WS_BUN.<LiteralName>">` produced by `defineCodes`. Keys: `HANDSHAKE_REJECTED`, `TENANT_CAP_EXCEEDED`, `BACKPRESSURE_EVICTED`, `HEARTBEAT_FAILED`, `RECONNECT_TOKEN_INVALID`, `RECONNECT_TOKEN_EXPIRED`, `RECONNECT_BUFFER_MISS`, `SUBPROTOCOL_UNSUPPORTED`, `CLOSE_TIMEOUT`, `PRINCIPAL_EXPIRED`.
+- `WsBunError` — concrete subclass of `SuaveplanError<WsBunErrorCode>` with a `wsBunCode` mirror property.
+- `raise*` helpers — one per code, all return `never`, all throw `WsBunError` with a pre-formatted message.
+
+## Implementation Notes
+
+The `raise*` helpers exist not only as ergonomic shortcuts but as a forcing-function: CI rule §6.3 demands every code in the registry have at least one production raise-site. Concentrating the raise calls in this module guarantees that property regardless of how the engine internals evolve.
+
+Codes are intentionally namespaced (`WS_BUN.*` rather than `WS.*`) so error reports never confuse this engine adapter with the abstract `@suaveplan/api-ws` contract package, which owns the parallel `WS.*` namespace.