first commit

docs/api-stack/api/api-db-adapter/src/error-codes/error-codes.md

@@ -0,0 +1,77 @@
+# `error-codes` — `DB_ADAPTER.*` registry + `DbAdapterError`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+This module is the single source of truth for every public failure code raised
+by `@suaveplan/api-db-adapter`. Codes are namespaced under `DB_ADAPTER.*` and
+exposed through both a `const` registry (`DB_ADAPTER_CODES`) and a typed
+`SuaveplanError` subclass (`DbAdapterError`).
+
+Consumers branch on the literal value at runtime — never on the message text —
+which means the wire format of every error is stable across releases. The
+registry is consumed by the migration runner, the tenant-scoped wrapper, the
+options validator, the engine registry, and the `db.unsafe-queries` capability
+gate.
+
+## Features
+
+- Five stable codes covering every public failure path: `TENANT_SCOPE_VIOLATION`,
+    `UNSAFE_NOT_PERMITTED`, `MIGRATION_FAILED`, `ENGINE_UNSUPPORTED`,
+    `INVALID_OPTIONS`.
+- Single `DbAdapterError` class extending `SuaveplanError` — discriminable by
+    `instanceof` or by code string.
+- `SuaveplanErrorOptions.cause` is honoured, so engine-side throws (e.g. a
+    Postgres protocol error during migration) are preserved on the cause chain.
+- Compatible with the standard `SuaveplanError` wire format — no per-package
+    deviations.
+
+## Usage: Basic
+
+```ts
+import {
+    DB_ADAPTER_CODES,
+    DbAdapterError,
+} from "@suaveplan/api-db-adapter/error-codes";
+
+throw new DbAdapterError(
+    DB_ADAPTER_CODES.UNSAFE_NOT_PERMITTED,
+    "plugin 'audit' does not declare db.unsafe-queries"
+);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    DB_ADAPTER_CODES,
+    DbAdapterError,
+} from "@suaveplan/api-db-adapter/error-codes";
+
+try {
+    await runMigrations(plugin, capabilities);
+} catch (cause) {
+    throw new DbAdapterError(
+        DB_ADAPTER_CODES.MIGRATION_FAILED,
+        `migration ${cause.file} failed`,
+        { cause, context: { file: cause.file } }
+    );
+}
+```
+
+## API Reference
+
+- `DB_ADAPTER_CODES` — `const` registry of the five codes.
+- `DbAdapterCode` — union of all registry values.
+- `DbAdapterError` — subclass of `SuaveplanError<DbAdapterCode>`.
+
+## Implementation Notes
+
+The codes are declared via `defineCodes("DB_ADAPTER", [...])` which produces a
+frozen mapping `{ TENANT_SCOPE_VIOLATION: "DB_ADAPTER.TENANT_SCOPE_VIOLATION",
+... }`. Comparisons against the registry value never drift even if a future
+change reorders the input array because the keys are spelled identically to the
+prefixed value's tail.