# `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.