first commit

docs/networking/drive/drive-plugin-chunks/src/error-codes.md

@@ -0,0 +1,59 @@
+# 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.