@onlineapps/error-handler-core 1.1.15 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog — @onlineapps/error-handler-core
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+### Added
+
+- **Regrese pro tři řádky tabulky, které ji neměly (d.331).** `401` → `BUSINESS` (neopakuje se), `408` → `TIMEOUT` a `429` → `RATE_LIMIT` (obojí se opakuje) — u každého se tvrdí verdikt I `shouldRetry`, protože klasifikace bez opakovatelnosti neříká nic o osudu zprávy. Právě těmhle třem statusům chyběl záznam v druhé, dnes už smazané mapě orchestrátoru, takže se rate-limitovaný krok neopakoval proti řádku `RATE_LIMIT` v `docs/standards/ERROR_HANDLING.md`. Tabulka je měřením v pořádku — chyběl jí hlas, kterým se ozve, až se pohne (`automation-gates.md` §5). Kontrolní případ pojmenuje důsledek jediného jména: chyba značkovaná vyřazeným `statusCode` propadne na hláškové vzory.
+
+- `CircuitOpenError` (code `CIRCUIT_OPEN`): an open circuit is a typed error with a code, not a message string — thrown by `CircuitBreaker.execute()`, exported from the package index, classified by `ErrorClassifier` (`b1849b6b`, d.153d-2; entry written 2026-09-12 — the change had shipped to the tree without one).
+
+### Removed
+
+- `circuitBreakerOptions` on the `CircuitBreakerManager` constructor (d.309). d.188 had turned it into a declared, validated door, and that made visible what it actually was: opossum's spelling of the five options the constructor already names, i.e. a second rail for one concern with no justification on record (`.claude/rules/change-discipline.md` § One rail per concern). Nothing outside this package's own tests ever passed it. Use the named options.
+
+### Changed
+
+- **BREAKING** `UnifiedLogSchema.create()` accepts only a category `ErrorClassifier` declares as `errorType`, and `_determineSeverity()` has no `|| 'error'` left (d.310). The severity map is keyed off `ErrorTypes` rather than repeating the names, and a declared category with no severity is refused at `require()` time — the second list used to drift silently, filing a new category under a severity nobody chose. A missing value and an invented category are now one refusal with one message.
+- **BREAKING** `DLQRouter._determineRoutingReason()` reads the same resolved `retryCount` the DLQ message records (d.310). It used to read `context.retryCount` on its own, so a message carrying the number disagreed with its own reason: three retries recorded, and a reason saying the budget played no part.
+- `UnifiedLogSchema.create()` uses `??` for every field where `null` states an absence (d.310). `handling.circuitBreakerState`, `handling.circuitName` and `handling.maxRetries` kept a present falsy value instead of filing it as "we do not know"; the three `context` keys behave as before (the `...context` spread already re-applied them) and now simply match the file's one shape.
+- **BREAKING** `UnifiedLogSchema.create()` requires `error` to be an `Error` instance and `errorType` to be a non-empty string (d.309). `|| 'Unknown error'` could only fire for something that is not an error, and it turned that caller defect into an entry reading like a real failure with a real message; `|| 'UNKNOWN'` let the schema speak a classification nobody made.
+- **BREAKING** `CircuitBreakerManager.getCircuitBreaker()` / `executeWithCircuitBreaker()` check their per-call `options` against the same table of ranges as the constructor (d.309), before the circuit is created and regardless of whether the breaker is enabled. This was the second unchecked way into opossum: `executeWithCircuitBreaker(name, fn, { timeout: 0 })` expired every call before its first byte. An undeclared key or a non-object is refused with the accepted keys listed.
+- **BREAKING** `DLQRouter.routeToDLQ()` checks `retryCount` (integer >= 0) and reads it through `??` (d.309). `message.retryCount || context.retryCount || 0` skipped a `retryCount: 0` on the message in favour of the context, and `_determineRoutingReason()` compares that number with `maxRetries` — so a dead message could be filed under a reason nobody produced. Both records of one dead message (the DLQ message and the `message_dlq` event) now state the same resolved number.
+- `UnifiedLogSchema.create()` writes `handling.action` and `handling.retryDelay` as they arrive (`??`): `'throw'` recorded a decision nobody had taken yet — `logError()` passes `handling: {}` precisely because the decision comes later — and `retryDelay: 0` is a documented valid value that `||` filed as "we do not know" (d.309). `DLQRouter` keeps a falsy-but-present `error.code` for the same reason.
+- **BREAKING** `UnifiedLogSchema.create()` requires `moduleName` and `operation` (d.187). `|| 'unknown-module'` / `|| 'unknown-operation'` filed the entry under a module and an operation of those names, and downstream that reads exactly like a real one — the defect d.178 removed for `serviceName`. A caller that omits either is refused with the key named.
+- **BREAKING** `maxRetries` means a budget of **attempts** everywhere (d.189). `ErrorHandlerCore._determineAction()` read the same key as a budget of retries and granted one call more than `RetryHandler.executeWithRetry()` ever ran: `maxRetries: 3` meant three calls on one path and four on the other. A caller driving the loop from `result.shouldRetry` now stops one attempt earlier.
+- **BREAKING** `circuitBreakerOptions` is a declared, validated door (d.188). The raw spread reached opossum after the d.177 range checks, so `{ circuitBreakerOptions: { timeout: 0 } }` expired every call before its first byte. Only the five declared opossum options are accepted, each against the same range; an undeclared key or a non-object is refused with the accepted keys listed.
+- **BREAKING** `ErrorHandlerCore` validates `context.retryCount` (integer >= 0) instead of reading every value through `|| 0` (d.187/d.189); it now decides whether an attempt is left, so a nonsense value is refused rather than read as "none yet".
+- `UnifiedLogSchema.create()` keeps a falsy-but-present `error.code` and `handling.retryCount` (`??`, not `||`): zero retries so far is a measurement, and `null` is reserved for the absence (d.187).
+- `ErrorHandlerCore` resolves `serviceVersion` and `environment` through `runtimeCfg.resolve()` alone (d.187). The `config.x || resolved.x` beside it asked the same question a second time — one rail per concern; no behaviour change, the resolver already preferred the explicit value.
+- **BREAKING** `ErrorClassifier.classify()` reads the HTTP status from `error.status`, the field the error contract names, instead of `error.statusCode`. A branded business error (`code` string + `status` number, `api/docs/biz/70-contracts/error-handling.md` §1) was missing both of the first two lookups and fell through to the message-pattern rules, so a 404 whose message contained the word "invalid" was filed as VALIDATION. No `status || statusCode` chain: one name only (`architecture-principles.md` §3). A caller that attaches `statusCode` alone is no longer classified by it.
+
+## [1.1.16] — 2026-08-29
+
+- Changelog started with this release; the history before it is in git (`git log -- shared/error-handler-core`).

package/README.md

@@ -1,3 +1,15 @@
+> Status: current
+> Owns: the platform's error handling itself — classification, retry, circuit breaker, DLQ routing and compensation
+
+<!-- BEGIN GENERATED: library-uniform — regenerate: npx oa-sync-template readme-uniform --all -->
+Uniform: [library/connector](../connector/conn-orch-validator/manifests/library.manifest.json)
+
+Duty sections that apply:
+
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `connector`: L-CONNECTOR-ENV
+<!-- END GENERATED: library-uniform -->
+
 # @onlineapps/error-handler-core
 
 Core error handling functionality for OA Drive microservices. Used by both business services (via `conn-infra-error-handler` wrapper) and infrastructure services (directly).
@@ -48,6 +60,14 @@ const errorHandler = new ErrorHandlerCore({
 });
 ```
 
+`maxRetries` is a budget of **attempts**, not of retries on top of a first call:
+`maxRetries: 3` means at most three calls, whichever path drives them —
+`executeWithRetry()` loops three times, and a caller driving the loop itself from
+`handleError()`'s `result.shouldRetry` stops after the third as well. The other
+`handling` keys, their defaults and their accepted ranges belong to the component
+that reads each key (`RetryHandler`, `CircuitBreakerManager`, `DLQRouter`); a
+value outside its range is refused in the constructor.
+
 ### Log Error
 
 ```javascript
@@ -59,6 +79,12 @@ await errorHandler.logError({
 });
 ```
 
+`serviceName` (on the handler), `moduleName`, `operation` and `error` are required
+inputs, and `error` must be an `Error` instance. A missing one is refused with a
+message naming it — never renamed to `unknown-service` / `unknown-module` /
+`unknown-operation` and never given a substitute message, all of which downstream
+reads exactly like the real thing.
+
 ### Handle Error
 
 ```javascript
@@ -103,6 +129,26 @@ const result = await errorHandler.executeWithCircuitBreaker({
 });
 ```
 
+An open circuit refuses with `CircuitOpenError` — a type, not a sentence, because
+this is the one refusal a client sees verbatim (INFRA-DOCS audit P5, point 7):
+
+```javascript
+const { CircuitOpenError } = require('@onlineapps/error-handler-core');
+
+try {
+  await errorHandler.executeWithCircuitBreaker('user-api', fn);
+} catch (error) {
+  if (error.code === 'CIRCUIT_OPEN') {
+    // error.details.name === 'user-api'; error instanceof CircuitOpenError
+  }
+  throw error;
+}
+```
+
+Branch on `error.code`, never on `error.message`: the wording follows
+`.claude/rules/architecture-principles.md` §5 and may be improved, the code and
+`details.name` are the contract.
+
 ## API Reference
 
 See [ERROR_HANDLING.md](/docs/standards/ERROR_HANDLING.md) for the cross-cutting standard (classification table, fail-loudly rules).

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@onlineapps/error-handler-core",
-  "version": "1.1.15",
+  "version": "2.0.0",
   "description": "Core error handling functionality for OA Drive microservices - classification, retry, circuit breaker, DLQ routing",
+  "oa": {
+    "category": "connector"
+  },
+  "engines": {
+    "node": ">=24.0.0 <25"
+  },
   "main": "src/index.js",
   "scripts": {
-    "test": "jest",
+    "test": "npm run test:unit",
     "test:coverage": "jest --coverage",
     "test:watch": "jest --watch",
-    "test:unit": "jest tests/unit",
-    "test:component": "jest tests/component"
+    "test:unit": "jest tests/unit"
   },
   "keywords": [
     "error-handling",
@@ -20,9 +25,9 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/monitoring-core": "1.0.26",
-    "@onlineapps/runtime-config": "1.0.2",
-    "opossum": "^7.0.0"
+    "@onlineapps/logger-contract": "1.1.0",
+    "@onlineapps/runtime-config": "1.1.0",
+    "opossum": "10.0.0"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/src/CircuitBreaker.js

@@ -4,17 +4,132 @@
  */
 
 const CircuitBreaker = require('opossum');
+const CircuitOpenError = require('./CircuitOpenError');
+const { assertNumberInRange, describeValue } = require('./configRanges');
+
+const POSITIVE_MS = 'a number > 0 (milliseconds)';
+
+/**
+ * The opossum options this class accepts, spelled as opossum spells them, each
+ * with the range it must satisfy. Declared ONCE and used by both ways in: the
+ * named constructor options, and the per-call options of `getCircuitBreaker()` —
+ * so a value cannot be valid on one path and broken on the other.
+ */
+const CIRCUIT_OPTION_RULES = {
+  timeout: { exclusiveMin: 0, expected: POSITIVE_MS },
+  errorThresholdPercentage: { min: 1, max: 100, expected: 'a number between 1 and 100 (percent)' },
+  resetTimeout: { exclusiveMin: 0, expected: POSITIVE_MS },
+  rollingCountTimeout: { exclusiveMin: 0, expected: POSITIVE_MS },
+  rollingCountBuckets: { integer: true, min: 1, expected: 'an integer >= 1' }
+};
+
+const ACCEPTED_OPTIONS = Object.keys(CIRCUIT_OPTION_RULES);
+
+/**
+ * Accept per-call `options` only as declared, validated options.
+ *
+ * Two ways led into opossum and only one of them was checked. d.188 closed the
+ * first (`circuitBreakerOptions`, since retired: it carried opossum's spelling of
+ * the five options the constructor already names, which is a second rail for one
+ * concern — `.claude/rules/change-discipline.md` § One rail per concern). This is
+ * the second: `getCircuitBreaker()` spread the caller's per-call options straight
+ * over `this.options`, so `executeWithCircuitBreaker(name, fn, { timeout: 0 })`
+ * expired every call before its first byte. One table of rules, both ways in —
+ * a value cannot be valid on one path and broken on the other
+ * (`.claude/rules/architecture-principles.md` §4 fail-fast, §8 explicit).
+ *
+ * @param {*} options - Value as received
+ * @returns {Object} The accepted options
+ * @throws {Error} If the value is not an object, carries an undeclared key, or a
+ *   declared key outside its range
+ */
+function assertCircuitOptions(options) {
+  if (options === undefined) return {};
+
+  if (typeof options !== 'object' || options === null || Array.isArray(options)) {
+    throw new Error(
+      '[CircuitBreakerManager] Invalid configuration value - "options" must be an object '
+      + `of declared opossum options, got ${describeValue(options)}. `
+      + 'Fix: pass an object such as { resetTimeout: 5000 }, or omit it.'
+    );
+  }
+
+  for (const [key, value] of Object.entries(options)) {
+    const rule = CIRCUIT_OPTION_RULES[key];
+    if (rule === undefined) {
+      throw new Error(
+        `[CircuitBreakerManager] Unknown circuit-breaker option - "options.${key}" `
+        + `is not a declared option. Expected one of: ${ACCEPTED_OPTIONS.join(', ')}. `
+        + 'Fix: use a declared option, or drop the key.'
+      );
+    }
+    assertNumberInRange('CircuitBreakerManager', `options.${key}`, value, rule);
+  }
+
+  return options;
+}
 
 class CircuitBreakerManager {
-  constructor(config = {}) {
-    this.enabled = config.circuitBreakerEnabled !== false;
+  /**
+   * Every option is optional and its default is declared HERE, once — this
+   * class owns them. Written as destructuring defaults, not `||`: opossum threw
+   * its own `||` out in 10.0.0 exactly so an explicit 0 survives (see the test
+   * file's header), and this constructor used to undo that one line earlier —
+   * `resetTimeout: 0` never reached opossum at all. See
+   * `.claude/rules/architecture-principles.md` §3.
+   *
+   * Each numeric option is checked against its range before it reaches opossum
+   * (`.claude/rules/architecture-principles.md` §4): once d.173 let an explicit
+   * 0 through, `timeout: 0` expired every call before it started and
+   * `rollingCountBuckets: 0` divided the statistics window by zero.
+   *
+   * @param {Object} [config] - Circuit breaker configuration
+   * @param {boolean} [config.circuitBreakerEnabled=true] - Enable the breakers
+   * @param {number} [config.timeout=10000] - Call timeout in ms; > 0
+   * @param {number} [config.errorThreshold=50] - Error threshold in percent; 1–100
+   * @param {number} [config.resetTimeout=30000] - Open → half-open delay in ms; > 0
+   * @param {number} [config.rollingCountTimeout=10000] - Stats window in ms; > 0
+   * @param {number} [config.rollingCountBuckets=10] - Stats buckets; integer >= 1
+   * @throws {Error} If a named numeric option is outside its range
+   */
+  constructor({
+    circuitBreakerEnabled,
+    timeout = 10000,
+    errorThreshold = 50,
+    resetTimeout = 30000,
+    rollingCountTimeout = 10000,
+    rollingCountBuckets = 10
+  } = {}) {
+    // The rule for each option is spelled once, in CIRCUIT_OPTION_RULES; the key
+    // passed here is the one the CALLER wrote, so the message names their key
+    // (`errorThreshold` is this class's name for opossum's
+    // `errorThresholdPercentage`).
+    assertNumberInRange(
+      'CircuitBreakerManager', 'timeout', timeout, CIRCUIT_OPTION_RULES.timeout
+    );
+    assertNumberInRange(
+      'CircuitBreakerManager', 'errorThreshold', errorThreshold,
+      CIRCUIT_OPTION_RULES.errorThresholdPercentage
+    );
+    assertNumberInRange(
+      'CircuitBreakerManager', 'resetTimeout', resetTimeout, CIRCUIT_OPTION_RULES.resetTimeout
+    );
+    assertNumberInRange(
+      'CircuitBreakerManager', 'rollingCountTimeout', rollingCountTimeout,
+      CIRCUIT_OPTION_RULES.rollingCountTimeout
+    );
+    assertNumberInRange(
+      'CircuitBreakerManager', 'rollingCountBuckets', rollingCountBuckets,
+      CIRCUIT_OPTION_RULES.rollingCountBuckets
+    );
+
+    this.enabled = circuitBreakerEnabled !== false;
     this.options = {
-      timeout: config.timeout || 10000,
-      errorThresholdPercentage: config.errorThreshold || 50,
-      resetTimeout: config.resetTimeout || 30000,
-      rollingCountTimeout: config.rollingCountTimeout || 10000,
-      rollingCountBuckets: config.rollingCountBuckets || 10,
-      ...config.circuitBreakerOptions
+      timeout,
+      errorThresholdPercentage: errorThreshold,
+      resetTimeout,
+      rollingCountTimeout,
+      rollingCountBuckets
     };
     
     // Registry of circuit breakers
@@ -26,10 +141,17 @@ class CircuitBreakerManager {
    * 
    * @param {string} name - Operation name
    * @param {Function} fn - Function to protect
-   * @param {Object} options - Circuit breaker options
+   * @param {Object} [options] - Declared opossum options for this call; they
+   *   override the instance ones and are checked against the same ranges
    * @returns {CircuitBreaker} Circuit breaker instance
+   * @throws {Error} If options is not an object of declared, in-range options
    */
   getCircuitBreaker(name, fn, options = {}) {
+    // Before anything else, including the disabled pass-through: an option out
+    // of range is the caller's defect whether or not this manager acts on it,
+    // and a defect reported only in some configurations is a defect that hides.
+    const accepted = assertCircuitOptions(options);
+
     if (!this.enabled) {
       // Return pass-through if disabled
       return {
@@ -42,7 +164,7 @@ class CircuitBreakerManager {
     if (!this.breakers.has(name)) {
       const breaker = new CircuitBreaker(fn, {
         ...this.options,
-        ...options
+        ...accepted
       });
       
       this.breakers.set(name, breaker);
@@ -56,9 +178,12 @@ class CircuitBreakerManager {
    * 
    * @param {string} name - Operation name
    * @param {Function} fn - Async function to execute
-   * @param {Object} options - Circuit breaker options
+   * @param {Object} [options] - Declared opossum options for this call
    * @returns {Promise<*>} Function result
-   * @throws {Error} If circuit is open or operation fails
+   * @throws {CircuitOpenError} If the circuit is open (code 'CIRCUIT_OPEN')
+   * @throws {Error} If the operation itself fails
+   * @throws {Error} If options is not an object of declared, in-range options —
+   *   before the circuit is created
    */
   async executeWithCircuitBreaker(name, fn, options = {}) {
     const breaker = this.getCircuitBreaker(name, fn, options);
@@ -67,7 +192,7 @@ class CircuitBreakerManager {
       return await breaker.fire();
     } catch (error) {
       if (error.code === 'EOPENBREAKER') {
-        throw new Error(`Service unavailable: ${name} circuit is open`);
+        throw new CircuitOpenError(name);
       }
       throw error;
     }

package/src/CircuitOpenError.js

@@ -0,0 +1,30 @@
+/**
+ * CircuitOpenError
+ *
+ * The one error of this platform a client sees verbatim: when a circuit is open
+ * the caller gets no upstream answer at all, only this. That makes the refusal a
+ * contract, not an internal note — and a contract is a type with a code, never a
+ * sentence somebody may reword (INFRA-DOCS audit P5, point 7).
+ *
+ * Branch on `code === 'CIRCUIT_OPEN'`; `details.name` carries the circuit whose
+ * breaker refused. The message follows
+ * `.claude/rules/architecture-principles.md` §5 and is owned here, so every
+ * raise site produces exactly the same text.
+ */
+
+class CircuitOpenError extends Error {
+  /**
+   * @param {string} circuitName - Name of the circuit whose breaker is open
+   */
+  constructor(circuitName) {
+    super(
+      `[CircuitBreaker] Service unavailable - circuit "${circuitName}" is open. `
+      + 'Expected: retry after resetTimeout, or check the upstream.'
+    );
+    this.name = 'CircuitOpenError';
+    this.code = 'CIRCUIT_OPEN';
+    this.details = { name: circuitName };
+  }
+}
+
+module.exports = CircuitOpenError;

package/src/CompensationHandler.js

@@ -17,7 +17,10 @@ class CompensationHandler {
    */
   register(operation, handler) {
     if (typeof handler !== 'function') {
-      throw new Error(`Compensation handler for ${operation} must be a function`);
+      throw new Error(
+        `[CompensationHandler] Compensation handler for ${operation} must be a function - `
+        + `got ${typeof handler}. Fix: register(operation, async (context) => { … }).`
+      );
     }
     
     this.handlers.set(operation, handler);
@@ -45,7 +48,11 @@ class CompensationHandler {
     try {
       return await handler(context);
     } catch (error) {
-      throw new Error(`Compensation failed for ${operation}: ${error.message}`);
+      throw new Error(
+        `[CompensationHandler] Compensation failed for ${operation} - ${error.message}. `
+        + 'Fix: the rollback of this operation did not complete; the state it was undoing may be half-written.',
+        { cause: error }
+      );
     }
   }
   

package/src/DLQRouter.js

@@ -3,29 +3,100 @@
  * Routes failed messages to DLQ for manual inspection
  */
 
+const { assertLogger } = require('@onlineapps/logger-contract');
+const { assertNumberInRange, assertQueuePattern } = require('./configRanges');
+
+/**
+ * Retries already made before the message was dead-lettered. Read in two places
+ * (the DLQ message and the monitoring event), so the rule that reads it lives in
+ * one (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * `??`, not `||`: `retryCount: 0` on the message is a measurement, and `||`
+ * skipped it in favour of the context — which is not merely untidy, because
+ * `_determineRoutingReason()` compares that number with `maxRetries` and would
+ * file the message under a reason nobody produced.
+ *
+ * @param {Object} message - Original message
+ * @param {Object} context - Additional context
+ * @returns {number} Accepted retry count
+ * @throws {Error} If the value present is not an integer >= 0
+ */
+function resolveRetryCount(message, context) {
+  const retryCount = message.retryCount ?? context.retryCount ?? 0;
+  assertNumberInRange('DLQRouter', 'retryCount', retryCount, {
+    integer: true,
+    min: 0,
+    expected: 'an integer >= 0 (the number of retries already made)'
+  });
+  return retryCount;
+}
+
 class DLQRouter {
+  /**
+   * @param {Object} config - Configuration
+   * @param {Object} config.logger - Logger with info/warn/error/debug (required)
+   * @param {boolean} [config.dlqEnabled=true] - Enable DLQ routing
+   * @param {Object} [config.mqClient] - MQ client used to publish to the DLQ
+   * @param {string} [config.dlqNamePattern='{queue}.dlq'] - DLQ naming pattern;
+   *   a non-empty string containing the `{queue}` placeholder
+   * @param {boolean} [config.emitMonitoringEvents=true] - Emit message_dlq events
+   * @throws {Error} If dlqNamePattern cannot name a per-origin queue
+   */
   constructor(config = {}) {
+    // `dlqNamePattern` and `mqClient` carry their documented defaults as
+    // destructuring defaults, declared here once: a default stands in for a
+    // MISSING key, it never overrules what the caller passed
+    // (`.claude/rules/architecture-principles.md` §3). `logger` is read from
+    // `config` below because assertLogger owns its (absent) default: it throws.
+    const { mqClient = null, dlqNamePattern = '{queue}.dlq' } = config;
+    assertQueuePattern('DLQRouter', 'dlqNamePattern', dlqNamePattern);
+
     this.enabled = config.dlqEnabled !== false;
-    this.mqClient = config.mqClient || null;
-    this.dlqNamePattern = config.dlqNamePattern || '{queue}.dlq';
+    this.mqClient = mqClient;
+    this.dlqNamePattern = dlqNamePattern;
     this.emitMonitoringEvents = config.emitMonitoringEvents !== false;
+    // Both failure paths below deliberately swallow their error so that DLQ
+    // routing never breaks error handling; the logger is what keeps them visible.
+    this.logger = assertLogger(
+      'DLQRouter',
+      config.logger,
+      'a DLQ routing failure this router deliberately swallows still reaches the structured log'
+    );
   }
   
   /**
    * Route message to DLQ
    * 
    * @param {Object} message - Original message
+   * @param {string} [message.queue] - Queue the message came from; required
+   *   unless `context.queue` carries it
    * @param {Error} error - Error that occurred
    * @param {string} errorType - Classified error type
    * @param {Object} context - Additional context
+   * @param {string} [context.queue] - Queue of origin, when the message body
+   *   does not carry it
    * @returns {Promise<void>}
+   * @throws {Error} If neither the message nor the context names the queue
    */
   async routeToDLQ(message, error, errorType, context = {}) {
     if (!this.enabled || !this.mqClient) {
       return; // DLQ disabled or no MQ client
     }
-    
-    const originalQueue = message.queue || context.queue || 'unknown';
+
+    // The queue of origin is the only thing a dead message can be found by, so a
+    // missing one is refused here — before anything is published — rather than
+    // renamed. `… || 'unknown'` used to file every such message in `unknown.dlq`,
+    // a queue nobody is looking in, and said nothing about it. Owner's rule:
+    // no invented value (`api/docs/governance/confirmations/dlq-purge.md` 002).
+    const originalQueue = message.queue ?? context.queue;
+    if (typeof originalQueue !== 'string' || originalQueue.trim() === '') {
+      throw new Error(
+        '[DLQRouter] Missing required field - "queue" must be a non-empty string naming the queue the '
+        + 'message came from; a dead message is found by nothing else. '
+        + 'Fix: pass message.queue, or context.queue when the body does not carry it.'
+      );
+    }
+    const retryCount = resolveRetryCount(message, context);
     const dlqName = this._generateDLQName(originalQueue);
     
     const dlqMessage = {
@@ -36,16 +107,18 @@ class DLQRouter {
       error: {
         message: error.message,
         stack: error.stack,
-        code: error.code || null,
+        // `??`: a code that is present but falsy is a value; `null` is reserved
+        // for the absence of one.
+        code: error.code ?? null,
         type: errorType,
         timestamp: new Date().toISOString()
       },
       
       // Routing metadata
       originalQueue: originalQueue,
-      retryCount: message.retryCount || context.retryCount || 0,
+      retryCount,
       routedAt: new Date().toISOString(),
-      routingReason: this._determineRoutingReason(errorType, context)
+      routingReason: this._determineRoutingReason(errorType, context, retryCount)
     };
     
     try {
@@ -55,25 +128,43 @@ class DLQRouter {
       
       // Emit message_dlq monitoring event
       if (this.emitMonitoringEvents) {
-        await this._emitDLQEvent(message, dlqName, originalQueue, error, errorType, context);
+        await this._emitDLQEvent(message, dlqName, originalQueue, error, errorType, context, retryCount);
       }
     } catch (dlqError) {
       // If DLQ routing fails, log but don't throw
       // (we don't want DLQ failures to break error handling)
-      console.error(`[DLQRouter] Failed to route to DLQ ${dlqName}:`, dlqError.message);
+      this.logger.error('[DLQRouter] DLQ routing failed', {
+        dlqName,
+        originalQueue,
+        errorType,
+        reason: dlqError.message
+      });
     }
   }
   
   /**
    * Emit message_dlq event to monitoring
+   *
+   * @param {number} retryCount - Already resolved and checked by the caller, so
+   *   both records of one dead message state the same number
    * @private
    */
-  async _emitDLQEvent(message, dlqName, originalQueue, error, errorType, context) {
+  async _emitDLQEvent(message, dlqName, originalQueue, error, errorType, context, retryCount) {
     if (!this.mqClient) return;
-    
+
+    // Resolved before the try so the catch below can name the workflow it failed on.
+    //
+    // `null`, not `'unknown'`: a dead-lettered message need not belong to a
+    // workflow, but an absent id is never renamed into one. The consumer of
+    // `monitoring.workflow` takes any non-empty string as a real id
+    // (`infra/api_monitoring/src/consumer/apiflow-extension.js`, readReported +
+    // the MISSING_WORKFLOW_ID gate), so `'unknown'` wrote `workflow_traces` rows
+    // claiming a workflow by that name; `null` is the absence the message
+    // actually states, and that gate counts it as faulty telemetry instead.
+    // Owner: `api/docs/governance/confirmations/dlq-purge.md` 002.
+    const workflowId = message.workflow_id ?? context.workflow_id ?? null;
+
     try {
-      const workflowId = message.workflow_id || context.workflow_id || 'unknown';
-      
       await this.mqClient.publish('monitoring.workflow', {
         event_type: 'message_dlq',
         workflow_id: workflowId,
@@ -86,7 +177,7 @@ class DLQRouter {
             originalQueue: originalQueue,
             reason: error.message,
             errorType: errorType,
-            retryCount: message.retryCount || context.retryCount || 0,
+            retryCount,
             routedAt: new Date().toISOString()
           }
         },
@@ -97,30 +188,46 @@ class DLQRouter {
         }
       }, { persistent: true });
       
-      console.log(`[DLQRouter] ✓ Emitted message_dlq event for ${workflowId}`);
+      // One per dead-lettered message: a trace of the side effect, not an event
+      // of its own — the published message_dlq event is the record.
+      this.logger.debug('[DLQRouter] message_dlq event emitted', { workflowId, dlqName });
     } catch (emitError) {
       // Silent fail - don't break DLQ routing
-      console.warn(`[DLQRouter] Failed to emit monitoring event:`, emitError.message);
+      this.logger.warn('[DLQRouter] monitoring event emit failed', {
+        workflowId,
+        dlqName,
+        reason: emitError.message
+      });
     }
   }
   
   /**
-   * Generate DLQ name from original queue name
+   * Generate DLQ name from original queue name. The constructor has already
+   * refused a pattern without `{queue}`, so there is no second branch here: the
+   * one this method used to carry returned a pattern-shaped name for every
+   * origin, which is the collapse the check now prevents.
    * @private
    */
   _generateDLQName(originalQueue) {
-    if (this.dlqNamePattern.includes('{queue}')) {
-      return this.dlqNamePattern.replace('{queue}', originalQueue);
-    }
-    return this.dlqNamePattern;
+    return this.dlqNamePattern.replace('{queue}', originalQueue);
   }
   
   /**
-   * Determine routing reason
+   * Determine routing reason.
+   *
+   * Takes the SAME resolved `retryCount` the message records. It used to read
+   * `context.retryCount` on its own, so when the number came on the message the
+   * two disagreed: the entry said three retries and the reason said the budget
+   * had nothing to do with it.
+   *
+   * @param {string} errorType - Classified error type
+   * @param {Object} context - Additional context
+   * @param {number} retryCount - Resolved by `resolveRetryCount()`
+   * @returns {string} Routing reason
    * @private
    */
-  _determineRoutingReason(errorType, context) {
-    if (context.retryCount >= context.maxRetries) {
+  _determineRoutingReason(errorType, context, retryCount) {
+    if (retryCount >= context.maxRetries) {
       return 'max_retries_exceeded';
     }