# crypto-vault — Error code registry

## Purpose

`codes.ts` is the canonical, frozen registry of every error code emitted by
`@suaveplan/crypto-vault`. The registry exists so that consumers — vault
orchestrators, sync layers, telemetry pipelines, audit log post-processors —
can assert against a stable set of strings rather than parsing free-form
messages. The registry is built with `defineCodes` from `@suaveplan/error`,
which freezes the resulting record at module load and infers each code's
literal type so `instanceof CryptoVaultError` can narrow `code` to the union.

## Features

- Frozen `CRYPTO_VAULT_CODES` record with `CRYPTOVAULT.<MODULE>.<REASON>`
  namespacing.
- `CryptoVaultCode` type union for exhaustive `switch` discrimination.
- One canonical home for every failure mode the package can produce. Adding a
  new code requires touching this file plus the production path that throws.

## Usage: Basic Example

```ts
import {
    CRYPTO_VAULT_CODES,
    CryptoVaultError,
} from "@suaveplan/crypto-vault/errors";

throw new CryptoVaultError(
    CRYPTO_VAULT_CODES["BIP39.INVALID_ENTROPY_LENGTH"],
    "error.crypto-vault.bip39.invalid-entropy-length",
    { context: { length: 7 } }
);
```

## Usage: Advanced Example

```ts
import { CryptoVaultError } from "@suaveplan/crypto-vault/errors";
import type { CryptoVaultCode } from "@suaveplan/crypto-vault/errors";

function describe(err: unknown): string {
    if (!(err instanceof CryptoVaultError)) return "unknown error";
    const code: CryptoVaultCode = err.code;
    switch (code) {
        case "CRYPTOVAULT.BIP39.INVALID_MNEMONIC":
            return "Invalid recovery phrase";
        case "CRYPTOVAULT.SRP.AUTHENTICATION_FAILED":
            return "Wrong password — try again";
        default:
            return `Unhandled crypto-vault code: ${code}`;
    }
}
```

## API Reference

### `CRYPTO_VAULT_CODES`

A frozen `Record<string, string>` mapping each reason key (e.g.
`BIP39.INVALID_ENTROPY_LENGTH`) to its fully-qualified code (e.g.
`CRYPTOVAULT.BIP39.INVALID_ENTROPY_LENGTH`).

### `CryptoVaultCode`

Union of every string literal value held by `CRYPTO_VAULT_CODES`. Use as the
generic parameter of `CryptoVaultError`.

## Implementation Notes

- The registry is intentionally append-only. Removing a code is a breaking
  change for any consumer that asserts on it.
- Codes are checked at runtime via the `defineCodes` factory — any duplicate
  reason in the array would surface as the same key collapsing in the output
  record.
- Every code listed here must be thrown by at least one production path. The
  spec-conformance test enumerates the registry and verifies the production
  surface throws each code at least once.