first commit

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

@@ -0,0 +1,62 @@
+# error-codes/error-codes
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the stable error-code registry for `@suaveplan/api-plugin-audit` and the concrete `AuditPluginError` class used by every production code path. The registry is shared with `@suaveplan/error`'s singleton via `defineCodes("AUDIT_PLUGIN", [...])`, so every code surfaces in the unified `ErrorCodes` table consumed by logging, metrics, and translation layers.
+
+Every code documented here corresponds to a real failure mode the plugin can surface at the call site. Consumers branch on the string code (`error.code === AUDIT_PLUGIN_CODES.INVALID_INPUT`) rather than `instanceof` checks against private subclasses.
+
+## Features
+
+- Four stable codes: `INVALID_INPUT`, `SERVICE_NOT_AVAILABLE`, `SINK_INIT_FAILED`, `SINK_WRITE_FAILED`.
+- `AuditPluginError` carries `cause`, `context`, and the `code` discriminant via the `SuaveplanError` base.
+- Every code is raised by at least one production code path and pinned by `src/api-plugin-audit.spec-conformance.test.ts`.
+
+## Usage: Basic
+
+```ts
+import {
+    AUDIT_PLUGIN_CODES,
+    AuditPluginError,
+} from "@suaveplan/api-plugin-audit/error-codes/error-codes";
+
+throw new AuditPluginError(
+    AUDIT_PLUGIN_CODES.SERVICE_NOT_AVAILABLE,
+    "audit plugin requires the `app` service in ServiceRegistry",
+    { context: { missing: ["app"], statusCode: 500 } }
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    AUDIT_PLUGIN_CODES,
+    AuditPluginError,
+} from "@suaveplan/api-plugin-audit/error-codes/error-codes";
+
+try {
+    await sink.save(event);
+} catch (cause) {
+    const err = new AuditPluginError(
+        AUDIT_PLUGIN_CODES.SINK_WRITE_FAILED,
+        "audit sink rejected save()",
+        { cause, context: { eventId: event.id } }
+    );
+    logger.warn(err.message, { code: err.code, cause: err.cause });
+}
+```
+
+## API Reference
+
+- `AUDIT_PLUGIN_CODES` — frozen record from `defineCodes("AUDIT_PLUGIN", [...])`.
+- `AuditPluginErrorCode` — string-literal union of the registered codes.
+- `class AuditPluginError extends SuaveplanError<AuditPluginErrorCode>` — public constructor accepts `(code, message, options?)`.
+
+## Implementation Notes
+
+The registry is small on purpose. Validation failures map to `INVALID_INPUT`; structural prerequisite failures map to `SERVICE_NOT_AVAILABLE`; sink construction failures map to `SINK_INIT_FAILED`; per-request sink rejections map to `SINK_WRITE_FAILED`. The middleware path never re-throws `SINK_WRITE_FAILED` — it logs and counts so the request response is unaffected (telemetry must not 500 the caller).