# DTP_CODES + DriveTemplateError

## Purpose

Frozen registry of error codes plus the error class for the `@suaveplan/drive-template` package. Eleven codes cover the complete failure surface: the eight-step validation pipeline that `Drive.hydrateFrom(template)` runs (version check, expiry, freshness, replay, issuer trust, signature, recursion depth, file consistency) plus three operational codes for CDN signature failure, inline-file signature failure, and key-grant rejection. Consumers branch on `code` programmatically; messages are for humans only.

## Features

- Eleven codes mapping one-to-one to the eight-step pipeline plus three operational paths.
- `DTP_CODES` is frozen via `defineCodes` from `@suaveplan/error` — adding a code requires a code change and a spec update.
- `DriveTemplateError extends SuaveplanError<DtpErrorCode>` — inherits cause-chain traversal, redaction, and JSON wire format.
- Type-level exhaustiveness on switch statements via the literal-string `DtpErrorCode` union.

## Usage: Basic Example

```ts
import { DriveTemplateError, DTP_CODES } from "@suaveplan/drive-template/errors";

throw new DriveTemplateError(
    DTP_CODES.TEMPLATE_EXPIRED,
    "template expired at 2026-01-01T00:00:00Z",
);
```

## Usage: Advanced Example

```ts
import {
    DriveTemplateError,
    DTP_CODES,
    type DtpErrorCode,
} from "@suaveplan/drive-template/errors";

const remediation: Record<DtpErrorCode, string> = {
    "DTP.TEMPLATE_VERSION_UNSUPPORTED": "Update the client; this template uses a newer schema.",
    "DTP.TEMPLATE_EXPIRED": "Request a fresh template from the issuer.",
    "DTP.TEMPLATE_STALE": "Request a fresh template; this one is more than 24h old.",
    "DTP.TEMPLATE_REPLAY": "Template nonce already seen; the issuer must mint a new one.",
    "DTP.TEMPLATE_UNTRUSTED_ISSUER": "Add the issuer to globalPolicy.trustedKeyAuthorities.",
    "DTP.TEMPLATE_SIG_INVALID": "Template signature does not match the canonical bytes; possible tampering.",
    "DTP.TEMPLATE_TOO_DEEP": "Folder recursion exceeds the 32-level cap.",
    "DTP.TEMPLATE_MALFORMED": "Per-file consistency violated; check chunkSize, totalChunks, and manifest fields.",
    "DTP.CDN_BAD_SIGNATURE": "CDN response failed Ed25519 verification; falling back to mesh.",
    "DTP.INLINE_SIG_INVALID": "Inline file's stored signature does not match the bytes.",
    "DTP.KEY_GRANT_REJECTED": "Key grant signature, recipient, or issuer did not match the template.",
};

try {
    // hydrate code...
} catch (err) {
    if (err instanceof DriveTemplateError) {
        console.error(`[${err.code}] ${err.message}`);
        console.error("Remediation:", remediation[err.code]);
    }
}
```

## API Reference

### `const DTP_CODES`

Frozen object mapping uppercase code names to wire-format strings. Eleven entries:

**Eight-step validation pipeline** (matches `DTP-05` ordering):

- `TEMPLATE_VERSION_UNSUPPORTED` — `template.schemaVersion !== 1`. Future schema versions ship as new packages.
- `TEMPLATE_EXPIRED` — `Date.now() >= template.expiresAt`.
- `TEMPLATE_STALE` — `Date.now() - template.issuedAt > 24h`. Templates issued more than 24h ago are rejected even if not yet expired.
- `TEMPLATE_REPLAY` — `(driveId, nonce)` already seen in the local LRU cache (last 1024 entries).
- `TEMPLATE_UNTRUSTED_ISSUER` — `template.issuer` is not in `globalPolicy.trustedKeyAuthorities`.
- `TEMPLATE_SIG_INVALID` — Ed25519 verification of `serverSignature` over `canonicalSerialize(template - sig)` failed.
- `TEMPLATE_TOO_DEEP` — folder recursion exceeds 32 levels.
- `TEMPLATE_MALFORMED` — per-file consistency violated: `chunkSize <= 164`, `totalChunks * chunkSize < size`, `manifestKey` empty, etc.

**Operational**:

- `CDN_BAD_SIGNATURE` — chunk fetched from CDN failed Ed25519 sig verification. Drive falls back to mesh.
- `INLINE_SIG_INVALID` — inline file's stored Ed25519 signature does not match `Ed25519-sign(driveSecretKey, fileId ‖ bytes)`.
- `KEY_GRANT_REJECTED` — incoming `KeyGrantEnvelope` failed validation: issuer mismatch, recipient mismatch, sig invalid, or expired.

### `type DtpErrorCode`

Union: `(typeof DTP_CODES)[keyof typeof DTP_CODES]`.

### `class DriveTemplateError extends SuaveplanError<DtpErrorCode>`

Constructor: `new DriveTemplateError(code, message, options?)`. Inherits all `SuaveplanError` features.

## Implementation Notes

The eight pipeline codes are ordered by check sequence in `DTP-05`. Implementations MUST throw the first applicable code — they are mutually exclusive in a single hydrate call. The three operational codes are independent: a single drive may emit multiple `CDN_BAD_SIGNATURE` and `INLINE_SIG_INVALID` errors during normal operation; both are observable signals, not blockers.

`KEY_GRANT_REJECTED` is the only error code whose `context` field carries structured detail by convention. Implementations should populate `context` with `{ reason: 'untrusted-issuer' | 'wrong-recipient' | 'bad-signature' | 'expired' }` so callers can branch on the specific failure.

The `error-codes.spec-conformance.test.ts` enforces (1) the registry is frozen, (2) every code value starts with `DTP.`, (3) the eleven names match what the spec requires.