Initial Commit

packages/foundation/flow/streams-chunk-queue/src/errors/streams-chunk-queue-error.md

@@ -0,0 +1,97 @@
+# streams-chunk-queue-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`StreamsChunkQueueError` is the single typed error class raised by every
+public surface of `@suaveplan/streams-chunk-queue`. It extends
+`SuaveplanError` so callers get the full enterprise error contract: a
+stable `code` string, a structured `context` map, a redactable wire form,
+OpenTelemetry span-event mapping, and an unbroken cause chain. The
+package registers every code through `defineCodes`, guaranteeing the
+codes are immutable, frozen, and reachable from real call sites.
+
+## Features
+
+- One frozen registry — `STREAMS_CHUNK_QUEUE_CODES` — exposes the eight
+  canonical codes (`INVALID_TOTAL_CHUNKS`, `INVALID_CHUNK_ID`,
+  `STORAGE_NOT_CONFIGURED`, `STORAGE_CHUNK_MISSING`, `VALIDATION_FAILED`,
+  `DECRYPTION_FAILED`, `STREAM_TIMEOUT`, `RATE_LIMIT_EXHAUSTED`).
+- One literal-typed error class — `StreamsChunkQueueError` — narrows
+  `code` through `instanceof`.
+- Cause chaining via `SuaveplanError`'s `{ cause }` option, so the
+  underlying network or crypto failure is preserved.
+- Structured `context` map (e.g. `{ chunkId, fileId, totalChunks }`) for
+  observability and i18n.
+
+## Usage: Basic
+
+```ts
+import {
+    STREAMS_CHUNK_QUEUE_CODES,
+    StreamsChunkQueueError,
+} from "@suaveplan/streams-chunk-queue";
+
+throw new StreamsChunkQueueError(
+    STREAMS_CHUNK_QUEUE_CODES.INVALID_CHUNK_ID,
+    `chunk ${chunkId} out of range`,
+    { context: { chunkId: chunkId.toString() } },
+);
+```
+
+## Usage: Advanced
+
+```ts
+try {
+    await queue.addChunk(chunkId, bytes);
+} catch (err) {
+    if (
+        err instanceof StreamsChunkQueueError &&
+        err.code === STREAMS_CHUNK_QUEUE_CODES.VALIDATION_FAILED
+    ) {
+        observabilityBus.publish("chunk-fraud", {
+            chunkId: err.context?.chunkId,
+            cause: err.cause,
+        });
+    }
+    throw err;
+}
+```
+
+## API Reference
+
+### `STREAMS_CHUNK_QUEUE_CODES`
+
+A frozen record built by `defineCodes("STREAMS_CHUNK_QUEUE", […])`. Each
+key maps to the fully-qualified code string
+`STREAMS_CHUNK_QUEUE.<reason>`.
+
+### `StreamsChunkQueueErrorCode`
+
+Discriminated union of every code in the registry.
+
+### `StreamsChunkQueueError`
+
+```ts
+new StreamsChunkQueueError(
+    code: StreamsChunkQueueErrorCode,
+    message: string,
+    options?: { cause?: unknown; context?: Record<string, unknown> },
+)
+```
+
+- `code` — one of the registered code strings.
+- `message` — human-readable description (or i18n message key).
+- `options.cause` — underlying error preserved for `walkCauses`.
+- `options.context` — structured fields surfaced through the wire schema.
+
+## Implementation Notes
+
+`SuaveplanError` is `abstract`, so this module supplies the concrete
+subclass. The constructor delegates to `super` with the cause and context
+forwarded through `SuaveplanErrorOptions`. Codes are intentionally
+namespaced with `STREAMS_CHUNK_QUEUE.` so multi-package log scans can
+filter by prefix without false positives from sibling packages.