# `error-codes`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Frozen registry of the six stable `AUDIT_FILE.*` error codes raised by
the file-rotating audit sink, plus the concrete
`AuditFileError extends SuaveplanError` subclass that carries them.
Operators rely on the codes for dashboard slicing; package consumers
rely on the typed subclass to differentiate sink failures from generic
host errors without parsing message strings.

The registry is built with `defineCodes("AUDIT_FILE", [...])` from
`@suaveplan/error`, so every code is recorded in the global registry
exactly once at module load. The OpenSpec conformance gate verifies
every entry here is also raised by a production code path elsewhere in
`src/` — no dead codes are permitted.

## Features

- Six stable codes: `INVALID_RECORD`, `WRITER_FAILED`, `QUEUE_FULL`,
  `ROTATION_FAILED`, `RETENTION_FAILED`, `PATH_NOT_WRITEABLE`.
- Typed union `AuditFileCode` for narrowing on `error.code`.
- `AuditFileError` subclass with stable `error.name === "AuditFileError"`.
- Forwards `cause`, `context`, `redacted`, and other
  `SuaveplanErrorOptions` to the base constructor unchanged.

## Usage: Basic

```ts
import {
    AUDIT_FILE_CODES,
    AuditFileError,
} from "@suaveplan/api-audit-file/error-codes";

throw new AuditFileError(
    AUDIT_FILE_CODES.PATH_NOT_WRITEABLE,
    "error.audit.file.path_not_writeable",
    { context: { path: "/var/log/suaveplan/audit.log" } }
);
```

## Usage: Advanced

Narrow on the union after catching to drive code-specific recovery:

```ts
import {
    AUDIT_FILE_CODES,
    type AuditFileCode,
    AuditFileError,
} from "@suaveplan/api-audit-file/error-codes";

function recover(err: unknown): "retry" | "drop" {
    if (!(err instanceof AuditFileError)) throw err;
    const code: AuditFileCode = err.code;
    if (code === AUDIT_FILE_CODES.QUEUE_FULL) return "drop";
    if (code === AUDIT_FILE_CODES.WRITER_FAILED) return "retry";
    if (code === AUDIT_FILE_CODES.ROTATION_FAILED) return "retry";
    throw err;
}
```

## API Reference

- `AUDIT_FILE_CODES: Readonly<Record<Name, "AUDIT_FILE.<Name>">>`
- `type AuditFileCode = (typeof AUDIT_FILE_CODES)[keyof typeof AUDIT_FILE_CODES]`
- `AUDIT_FILE_ERROR_NAME = "AuditFileError"`
- `class AuditFileError extends SuaveplanError<AuditFileCode>`
  - `new AuditFileError(code, messageKey, options?)`

## Implementation Notes

The codes are declared `as const` so TypeScript freezes both the keys
and the fully-qualified string values. The `name` literal is exported
separately because some structured loggers group errors on `name`
before they inspect `code` — pinning a constant keeps that grouping
stable across releases. The module is side-effect-imported from
`src/index.ts` so a consumer who only loads a subpath
(`@suaveplan/api-audit-file/sink`) still triggers code registration.