# vault error codes

## Purpose

`codes.ts` defines the stable error-code registry for `@suaveplan/vault`. Every failure raised by the orchestration layer — locked-state rejections, bad-credential unlocks, manifest tampering, item validation, attachment / share / sync failures, and opaque-handle violations — carries one of these literal codes. The codes are frozen at module-load via `defineCodes("VAULT", [...])` so consumer code can assert on the exact strings without depending on JavaScript identifier ordering or import-time side effects.

The codes form the discriminated-union narrowing surface for `VaultError`. Together with the `VaultError` class they form the complete error contract: callers `import { VAULT_CODES, VaultError, type VaultErrorCode } from "@suaveplan/vault/errors"`, branch on `err.code`, and let TypeScript exhaustively check the switch.

## Features

- Two-level namespacing — `VAULT.LOCKED` for top-level lifecycle errors, `VAULT.ITEM.NOT_FOUND` for module-scoped errors. The dot-separated form is searchable and groups related failures (`ITEM.*`, `ATTACHMENT.*`, `SHARE.*`, `SYNC.*`).
- Every code is a literal string in the `VaultErrorCode` union — no enum cost, no value coupling.
- Hard-frozen registry — `defineCodes` returns a frozen object so consumers cannot accidentally mutate or extend the registry at runtime.

## Usage: Basic Example

```ts
import { VAULT_CODES, VaultError } from "@suaveplan/vault/errors";

throw new VaultError(VAULT_CODES.LOCKED, "error.vault.locked");
```

## Usage: Advanced Example

```ts
import { VAULT_CODES, VaultError, type VaultErrorCode } from "@suaveplan/vault/errors";

function describe(err: VaultError): string {
    const code: VaultErrorCode = err.code;
    switch (code) {
        case VAULT_CODES.LOCKED:
            return "Vault is locked — call unlock() first.";
        case VAULT_CODES.INVALID_CREDENTIALS:
            return "Wrong password or secret key.";
        case VAULT_CODES["ITEM.NOT_FOUND"]:
            return "Item does not exist in this vault.";
        case VAULT_CODES["ITEM.VERSION_CONFLICT"]:
            return "Item was modified concurrently — refetch and retry.";
        // ... exhaustive
        default:
            return "Unknown vault error.";
    }
}
```

## API Reference

- `VAULT_CODES` — frozen `Record<string, "VAULT.X.Y">` literal registry.
- `VaultErrorCode` — union of every value in `VAULT_CODES`.

## Implementation Notes

- The registry is intentionally fixed in source — adding a code is a public-API change requiring an OpenSpec proposal and a coordinated release with consumers.
- `defineCodes("VAULT", [...])` automatically prefixes each entry with `VAULT.`; the source array contains the unqualified suffix so visual scanning stays compact.
- Sub-namespaces (`ITEM`, `ATTACHMENT`, `SHARE`, `SYNC`) match the file layout under `src/` so locating a code's emission site is mechanical.