first commit

docs/foundation/flow/queue-distribution-worker-thread/src/errors/queue-distribution-worker-thread-error.md

@@ -0,0 +1,76 @@
+# `QueueDistributionWorkerThreadError` registry
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`QueueDistributionWorkerThreadError` is the base class for every structured error thrown by `@suaveplan/queue-distribution-worker-thread`. Each subclass carries a stable code from the registry produced by `defineCodes("WT", [...])`. Consumers match programmatically on `error.code` to distinguish a worker crash from a malformed reply, a request timeout, or a graceful termination — without parsing error messages.
+
+## Features
+
+- 4 stable codes — `WORKER_CRASHED`, `MESSAGE_MALFORMED`, `REQUEST_TIMEOUT`, `WORKER_TERMINATED`.
+- One concrete subclass per code with a typed constructor signature.
+- Optional `cause` narrowed to `Error` instances only.
+- Compatible with `SuaveplanError` cause-chain traversal and i18n message resolver.
+
+## Usage: Basic Example
+
+```ts
+import {
+    QueueDistributionWorkerThreadError,
+    WT_CODES,
+} from "@suaveplan/queue-distribution-worker-thread/errors/queue-distribution-worker-thread-error";
+
+try {
+    await worker.executeTask(task, input);
+} catch (error: unknown) {
+    if (
+        error instanceof QueueDistributionWorkerThreadError &&
+        error.code === WT_CODES.WORKER_CRASHED
+    ) {
+        // Re-route to a different worker.
+    }
+    throw error;
+}
+```
+
+## Usage: Advanced Example
+
+Use the discriminated codes to drive recovery strategy per failure class.
+
+```ts
+import {
+    QueueDistributionWorkerThreadError,
+    WT_CODES,
+} from "@suaveplan/queue-distribution-worker-thread/errors/queue-distribution-worker-thread-error";
+
+function recoveryPolicy(error: unknown): "retry" | "drop" | "fatal" {
+    if (!(error instanceof QueueDistributionWorkerThreadError)) {
+        return "fatal";
+    }
+    switch (error.code) {
+        case WT_CODES.REQUEST_TIMEOUT:
+            return "retry";
+        case WT_CODES.WORKER_TERMINATED:
+            return "drop";
+        case WT_CODES.WORKER_CRASHED:
+        case WT_CODES.MESSAGE_MALFORMED:
+            return "fatal";
+    }
+}
+```
+
+## API Reference
+
+- `const WT_CODES` — frozen registry of `WT.*` codes.
+- `type QueueDistributionWorkerThreadErrorCode` — union of every code.
+- `class QueueDistributionWorkerThreadError extends SuaveplanError<QueueDistributionWorkerThreadErrorCode>`.
+- `class WorkerThreadCrashedError({ workerId, cause? })`.
+- `class WorkerThreadMessageMalformedError({ workerId, cause? })`.
+- `class WorkerThreadRequestTimeoutError({ workerId, requestId, timeoutMs })`.
+- `class WorkerThreadTerminatedError({ workerId, requestId })`.
+
+## Implementation Notes
+
+`MESSAGE_MALFORMED` is used both for replies that fail the Zod envelope and for `ok: false` replies — both represent the worker telling us "this isn't going to work" without specifying _what_ about the worker is broken. If the upstream needs different classifications, the inbound payload schema is the place to extend, not the error registry. The `WORKER_CRASHED` and `WORKER_TERMINATED` codes are aimed at supervision: the first is what the operator wants to alert on; the second is what the manager wants to filter out of "real failures" during a graceful drain.