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