first commit

docs/api-stack/api/api-audit-file/src/error-codes/error-codes.md

@@ -0,0 +1,83 @@
+# `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.