# error-codes

## Purpose

Defines the structured error registry for `@suaveplan/drive-plugin-chunks`. Every chunk-format failure mode the plugin can produce is registered through `defineCodes("CHUNKS", [...])` so that downstream consumers can branch on stable string codes (`"CHUNKS.AEAD_TAG_INVALID"`, etc.) without parsing English-language error messages. The companion `ChunksError` class extends the project-wide `SuaveplanError` base so chunked-file errors compose with cause-chain traversal, redaction, and OTel span-event adapters defined in `@suaveplan/error`.

## Features

- Frozen `CHUNKS_CODES` enum-shaped constant covering the twelve failure classes that can occur during chunk encoding, signing, manifest exchange, layout selection, ingest, and inline-hint verification.
- `ChunksErrorCode` literal union derived from `CHUNKS_CODES` so call sites stay type-safe.
- `ChunksError` class with the `SuaveplanError` constructor signature widened to public, accepting `(code, message, options?)` plus the standard `cause` field.
- Side-effect-safe registration via `defineCodes` so subpath consumers automatically see codes registered too.

## Usage: Basic Example

```ts
import { CHUNKS_CODES, ChunksError } from "@suaveplan/drive-plugin-chunks";

throw new ChunksError(
    CHUNKS_CODES.AEAD_TAG_INVALID,
    "chunk AEAD tag verification failed"
);
```

## Usage: Advanced Example

```ts
import { CHUNKS_CODES, ChunksError } from "@suaveplan/drive-plugin-chunks";

try {
    await chunks.ingest("photo.jpg");
} catch (err) {
    if (err instanceof ChunksError) {
        switch (err.code) {
            case CHUNKS_CODES.SIG_INVALID:
                return alertOps("server signing key drift");
            case CHUNKS_CODES.MANIFEST_NOT_FOUND:
                return rebuildManifest(err);
            default:
                throw new ChunksError(
                    CHUNKS_CODES.INGEST_FAILED,
                    "wrapped ingest failure",
                    { cause: err }
                );
        }
    }
    throw err;
}
```

## API Reference

- `CHUNKS_CODES` — `Readonly<Record<string, string>>` of `"CHUNKS.<NAME>"` strings.
- `ChunksErrorCode` — string-literal union of every value in `CHUNKS_CODES`.
- `ChunksError` — `class ChunksError extends SuaveplanError<ChunksErrorCode>` with constructor `(code: ChunksErrorCode, message: string, options?: SuaveplanErrorOptions)`. Inherits `name`, `code`, `message`, `cause`, and the structured-redaction surface from `SuaveplanError`.

## Implementation Notes

The twelve codes are deliberately narrow: each maps to one failure semantic (tag verification, signature verification, payload length mismatch, inline-hint signature failure, etc.) so monitoring dashboards can attach SLOs per code without redacting cardinality. `INLINE_SIG_INVALID` was added in DTP-25 to signal that an `InlineHint` failed Ed25519 verification against the drive's signing key over `fileId ‖ bytes`; legacy `LegacyInlineHint` shapes (no `sig` field) do not throw — they emit a `drive:inline:legacy` warning and trigger a rewrite-with-sig on next write.