first commit

docs/api-stack/api/api-ws-broker-redis/src/error-codes/error-codes.md

@@ -0,0 +1,96 @@
+# `error-codes` — `WS_BROKER_REDIS_CODES`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module defines the stable error-code registry for
+`@suaveplan/api-ws-broker-redis`. Every failure surface the broker emits at
+runtime — Redis connection drops, publish/subscribe failures, buffer reads
+and writes, oversize payloads, deserialise failures, configuration errors,
+reconnect exhaustion, and command timeouts — carries one of the ten
+`WS_BROKER_REDIS.*` codes defined here. Callers branch on the literal string
+value (or `instanceof WsBrokerRedisError`) to drive recovery logic.
+
+The registry is closed: adding a new code requires an OpenSpec change so
+production dashboards and alerting rules keyed on the existing codes stay
+stable.
+
+## Features
+
+- Ten stable codes covering every documented failure surface.
+- `defineCodes("WS_BROKER_REDIS", [...])` so the runtime values are
+  auto-namespaced to `WS_BROKER_REDIS.<NAME>`.
+- `WsBrokerRedisError` subclass with a public constructor (lint-enforced),
+  so callers can `new WsBrokerRedisError(code, message, { cause })` directly
+  rather than coercing through a factory.
+- Tied-off TypeScript literal union (`WsBrokerRedisErrorCode`) for
+  exhaustive `switch` statements at call sites.
+
+## Usage: Basic
+
+```ts
+import {
+    WS_BROKER_REDIS_CODES,
+    WsBrokerRedisError,
+} from "@suaveplan/api-ws-broker-redis/error-codes";
+
+try {
+    await broker.publish("orders", envelope);
+} catch (err) {
+    if (
+        err instanceof WsBrokerRedisError &&
+        err.brokerCode === WS_BROKER_REDIS_CODES.PAYLOAD_TOO_LARGE
+    ) {
+        // Drop or split — Redis is not going to accept this frame.
+        return;
+    }
+    throw err;
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    type WsBrokerRedisErrorCode,
+    WS_BROKER_REDIS_CODES,
+} from "@suaveplan/api-ws-broker-redis/error-codes";
+
+function classify(code: WsBrokerRedisErrorCode): "retry" | "drop" | "fatal" {
+    switch (code) {
+        case WS_BROKER_REDIS_CODES.CONNECTION_LOST:
+        case WS_BROKER_REDIS_CODES.TIMEOUT:
+        case WS_BROKER_REDIS_CODES.PUBLISH_FAILED:
+            return "retry";
+        case WS_BROKER_REDIS_CODES.PAYLOAD_TOO_LARGE:
+        case WS_BROKER_REDIS_CODES.DESERIALISE_FAILED:
+            return "drop";
+        default:
+            return "fatal";
+    }
+}
+```
+
+## API Reference
+
+- `WS_BROKER_REDIS_CODES` — frozen registry mapping name → `WS_BROKER_REDIS.<NAME>`.
+- `WsBrokerRedisErrorCode` — literal union over every registered code.
+- `WsBrokerRedisError` — `SuaveplanError<WsBrokerRedisErrorCode>` subclass with
+  `brokerCode` field and a public 2/3-arg constructor.
+
+## Implementation Notes
+
+`WsBrokerRedisError` declares its own public constructor (rather than relying
+on the base `SuaveplanError`'s protected one) so `new WsBrokerRedisError(...)`
+compiles cleanly from outside the file. This is required by the repo's
+`check-error-subclass-constructors` lint — TypeScript's TS2674 ("Constructor of
+class is protected and only accessible within the class declaration") would
+otherwise reject every call site.
+
+The `brokerCode` field is a deliberate alias for `code`. Calling code commonly
+branches on the narrower `WsBrokerRedisErrorCode` literal union to get
+exhaustiveness from the TypeScript compiler; reading the alias keeps that
+narrowing locally explicit even when the catch block widened the type.