first commit

docs/foundation/flow/queue/src/errors/queue-error.md

@@ -0,0 +1,95 @@
+# queue-error
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Defines the error hierarchy for `@suaveplan/queue`. All errors extend `SuaveplanError` via a shared `QueueError` base class, giving them stable numeric codes, cause-chain traversal, and OTel span-event integration from `@suaveplan/error`.
+
+Error codes are registered once via `defineCodes("queue", {...})` so each error can be identified numerically in distributed tracing, log pipelines, and wire protocols without relying on class names that may be minified.
+
+## Features
+
+- `QueueError` — base class for the entire queue error family
+- `QueueFullError` — capacity exceeded on enqueue
+- `QueueJobNotFoundError` — job ID lookup failure (includes optional `jobId` in message)
+- `QueueWorkerAbortedError` — worker stopped via `AbortSignal`
+- `QueueHandlerFailedError` — job handler threw an unhandled error
+- `QueueInvalidStateError` — illegal job state transition (includes `from`/`to` in message)
+- `QueueDeadLetterFailedError` — dead-letter enqueue failure
+- All codes under the `"queue"` domain namespace via `defineCodes`
+
+## Usage: Basic Example
+
+```ts
+import { QueueFullError, QueueHandlerFailedError } from "@suaveplan/queue/errors/queue-error";
+
+try {
+  throw new QueueFullError({ message: "Memory queue at capacity" });
+} catch (err) {
+  if (err instanceof QueueFullError) {
+    console.error("Queue full, code:", err.code); // stable numeric code
+  }
+}
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  QueueInvalidStateError,
+  QueueJobNotFoundError,
+  QUEUE_CODES,
+} from "@suaveplan/queue/errors/queue-error";
+
+// State transition with context
+throw new QueueInvalidStateError({
+  from: "completed",
+  to: "processing",
+});
+
+// Job lookup failure with ID
+const err = new QueueJobNotFoundError({ jobId: "job_abc123" });
+console.log(err.message); // "Job not found: job_abc123"
+console.log(err.code === QUEUE_CODES.QUEUE_JOB_NOT_FOUND); // true
+```
+
+## API Reference
+
+### `QUEUE_CODES`
+
+Stable code map: `QUEUE_FULL=1`, `QUEUE_JOB_NOT_FOUND=2`, `QUEUE_WORKER_ABORTED=3`, `QUEUE_HANDLER_FAILED=4`, `QUEUE_INVALID_STATE=5`, `QUEUE_DEAD_LETTER_FAILED=6`.
+
+### `QueueError`
+
+Base class. Extends `SuaveplanError`, domain `"queue"`.
+
+### `QueueFullError(options?)`
+
+- `options.message?` — override default message
+- `options.cause?` — wrapped cause
+
+### `QueueJobNotFoundError(options?)`
+
+- `options.jobId?` — included in default message
+
+### `QueueWorkerAbortedError(options?)`
+
+Thrown when `AbortSignal` fires during worker processing.
+
+### `QueueHandlerFailedError(options?)`
+
+Wraps the original handler error as `cause`.
+
+### `QueueInvalidStateError(options?)`
+
+- `options.from?` / `options.to?` — state labels included in default message
+
+### `QueueDeadLetterFailedError(options?)`
+
+Thrown when the dead-letter enqueue itself fails.
+
+## Implementation Notes
+
+`defineCodes` from `@suaveplan/error` allocates a namespace-prefixed numeric code map. This approach prevents code collisions across packages and survives minification. Each error class declares its code as both a static and instance property to support `instanceof` checks and code-based switching.