first commit

docs/api-stack/api/api-logger-worker-proxy/src/error-codes/error-codes.md

@@ -0,0 +1,92 @@
+# `error-codes`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Stable identifier registry for failures originating in
+`@suaveplan/api-logger-worker-proxy`. Every public failure path that
+results in a thrown `LoggerProxyError` carries one of these
+`LOGGER_PROXY.*` namespaced codes so consumers can branch on the literal
+value without depending on the concrete error class.
+
+The package follows a best-effort posture by design: a logger that throws
+on log calls would force application code to wrap every `log.info(...)`
+in a try/catch. Instead, the proxy drops records and increments a
+counter when the wire is congested. Codes here are reserved for the
+narrow set of failures where dropping is not an option — invalid frame
+received on the main side (must surface to surface a protocol bug), or a
+caller using the worker-side proxy after `dispose()` (a programming
+error, not a transient transport problem).
+
+## Features
+
+- `LOGGER_PROXY_CODES` — readonly record produced by
+  `defineCodes("LOGGER_PROXY", [...])`. Each value is the
+  fully-qualified string (e.g. `"LOGGER_PROXY.QUEUE_OVERFLOW"`).
+- `LoggerProxyCode` — union of every fully-qualified code in the
+  registry; safe to use in switch exhaustiveness checks.
+- `LoggerProxyError` — typed `SuaveplanError` subclass; carries a code
+  and the standard cause chain, redaction, and OTel hooks from
+  `@suaveplan/error`.
+
+## Usage: Basic
+
+```ts
+import {
+    LOGGER_PROXY_CODES,
+    LoggerProxyError,
+} from "@suaveplan/api-logger-worker-proxy/error-codes";
+
+throw new LoggerProxyError(
+    LOGGER_PROXY_CODES.PROXY_DISPOSED,
+    "log.info called after dispose()"
+);
+```
+
+## Usage: Advanced
+
+Branching on the code rather than `instanceof` lets caller code stay
+loose-coupled to this package:
+
+```ts
+import { LOGGER_PROXY_CODES } from "@suaveplan/api-logger-worker-proxy/error-codes";
+
+try {
+    proxy.info("hello");
+} catch (err) {
+    if (
+        err instanceof Error &&
+        "code" in err &&
+        err.code === LOGGER_PROXY_CODES.PROXY_DISPOSED
+    ) {
+        // restart the proxy
+    } else {
+        throw err;
+    }
+}
+```
+
+## API Reference
+
+- `LOGGER_PROXY_CODES.QUEUE_OVERFLOW` — emitted main-side when an
+  inbound batch exceeds the configured ceiling; the inbound port is
+  closed to protect the main logger.
+- `LOGGER_PROXY_CODES.PROXY_DISPOSED` — emitted worker-side when a log
+  call is made after `dispose()`.
+- `LOGGER_PROXY_CODES.INVALID_FRAME` — emitted main-side when a frame
+  fails Zod validation.
+- `LOGGER_PROXY_CODES.PORT_CLOSED` — emitted main-side when a `goodbye`
+  frame is received or when `postMessage` throws.
+- `LOGGER_PROXY_CODES.DISABLED` — informational; the proxy is
+  currently in `disable` mode and is dropping records.
+
+## Implementation Notes
+
+`defineCodes` from `@suaveplan/error` produces a frozen record with
+fully-qualified string values. The package SHOULD NOT add codes for
+transient transport failures — those increment counters instead so the
+application keeps running. Adding a new code is a breaking change for
+downstream consumers that branch on the union; gate via OpenSpec.