Initial Commit

packages/api-stack/api/api-audit-stdout/src/error-codes/error-codes.md

@@ -0,0 +1,87 @@
+# `error-codes` — `AUDIT_STDOUT_*` registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module declares the four stable error codes the stdout audit sink
+exposes to consumers. Every failure path inside `createStdoutAuditSink`
+maps onto exactly one of them, so callers can branch on `error.code`
+without parsing messages or stack traces. The registry uses
+`@suaveplan/error`'s `defineCodes` so the union narrows under
+`instanceof AuditStdoutError`.
+
+The codes capture the four observable failure modes of a write-only,
+fire-and-forget audit pipeline: a record that fails its own Zod schema
+(`INVALID_RECORD`), an option bag that fails the constructor schema
+(`INVALID_OPTIONS`), a transport error from the supplied writer
+(`WRITER_FAILED`), and the bounded-backpressure drop case
+(`QUEUE_FULL`). The codes are surfaced through the
+`AuditStdoutError` subclass, which carries a `code` property typed as
+the literal union — `instanceof` narrowing flows through.
+
+## Features
+
+- Stable string codes via `defineCodes("AUDIT_STDOUT", [...])`.
+- `AuditStdoutError` subclass with public constructor (lint rule
+  `check-error-subclass-constructors` enforced).
+- Code union exported as `AuditStdoutErrorCode` for callers who want
+  to switch over every member.
+- No runtime side effects — the registry is a frozen object literal.
+
+## Usage: Basic
+
+```ts
+import {
+    AUDIT_STDOUT_CODES,
+    AuditStdoutError,
+} from "@suaveplan/api-audit-stdout/error-codes";
+
+throw new AuditStdoutError(
+    AUDIT_STDOUT_CODES.INVALID_RECORD,
+    "error.audit_stdout.invalid_record"
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    AUDIT_STDOUT_CODES,
+    AuditStdoutError,
+    type AuditStdoutErrorCode,
+} from "@suaveplan/api-audit-stdout/error-codes";
+
+function handle(err: unknown): "drop" | "rethrow" {
+    if (!(err instanceof AuditStdoutError)) return "rethrow";
+    const code: AuditStdoutErrorCode = err.code;
+    switch (code) {
+        case AUDIT_STDOUT_CODES.QUEUE_FULL:
+        case AUDIT_STDOUT_CODES.WRITER_FAILED:
+            return "drop";
+        case AUDIT_STDOUT_CODES.INVALID_RECORD:
+        case AUDIT_STDOUT_CODES.INVALID_OPTIONS:
+            return "rethrow";
+    }
+}
+```
+
+## API Reference
+
+- `AUDIT_STDOUT_CODES` — frozen `{ INVALID_RECORD, WRITER_FAILED,
+  QUEUE_FULL, INVALID_OPTIONS }` mapping to the corresponding
+  `"AUDIT_STDOUT.*"` literal.
+- `AuditStdoutErrorCode` — union of the four literal strings.
+- `AuditStdoutError` — `SuaveplanError<AuditStdoutErrorCode>` subclass
+  with a public constructor accepting `(code, message, options?)`.
+
+## Implementation Notes
+
+`defineCodes` returns a frozen object — adding a new code requires an
+OpenSpec change. The subclass declares its own public constructor so
+`new AuditStdoutError(...)` is callable from outside the module (the
+base class is abstract with a protected constructor). The
+`auditStdoutCode` field is a typed alias of `code` for callers who
+want a non-generic accessor.