@onlineapps/cookbook-router 3.0.0 → 4.0.0

package/API.md

@@ -0,0 +1,274 @@
+## Modules
+
+<dl>
+<dt><a href="#@onlineapps/cookbook-router
+
+Message routing for cookbook workflows_ given a service name and a workflow
+message, publish it to that services workflow queue.
+
+The package does NOT execute cookbooks, drive flow control, retry, complete
+or dead-letter them. Those belong to `WorkflowOrchestrator` — confirmation
+`api/docs/governance/confirmations/cookbook-execution-owner.md` 001 — which
+is also the only caller_ it takes `createRouter`
+(WorkflowOrchestrator.js_71) and calls `routeToService` on the result
+(_78,233,241,1223,1230). The second routing rail, the retry rail and the
+queue/registry administration this package used to carry had zero callers
+outside it and were removed on 2026-09-02.module_">@onlineapps/cookbook-router
+
+Message routing for cookbook workflows: given a service name and a workflow
+message, publish it to that services workflow queue.
+
+The package does NOT execute cookbooks, drive flow control, retry, complete
+or dead-letter them. Those belong to `WorkflowOrchestrator` — confirmation
+`api/docs/governance/confirmations/cookbook-execution-owner.md` 001 — which
+is also the only caller: it takes `createRouter`
+(WorkflowOrchestrator.js:71) and calls `routeToService` on the result
+(:78,233,241,1223,1230). The second routing rail, the retry rail and the
+queue/registry administration this package used to carry had zero callers
+outside it and were removed on 2026-09-02.</a></dt>
+<dd></dd>
+</dl>
+
+## Classes
+
+<dl>
+<dt><a href="#QueueManager">QueueManager</a></dt>
+<dd><p>QueueManager - Queue operations and management</p>
+<p>A QUEUE and a MESSAGE are two different things, and neither one&#39;s defaults
+belong to the other. Until d.396d this class held ONE object for both —
+<code>defaultOptions: { durable: true, persistent: true }</code> — and spread it into the
+publish AND into the queue declaration, so each call site was handed a key it
+has no use for. Measured in both directions on the unit tier:</p>
+<pre><code>assertQueue(&#39;split.queue&#39;, { durable: true, persistent: true })
+publish(&#39;control.publish&#39;, …,  { durable: true, persistent: true })
+</code></pre>
+<p><code>persistent</code> is a message property (amqplib <code>Options.Publish</code>) and means
+nothing to a queue; <code>durable</code> is a queue property and means nothing to a
+message. Nothing objected, because <code>@onlineapps/mq-client-core</code> read the two
+keys it knew and dropped the rest in silence — and since d.396c it no longer
+does: <code>assertQueue()</code> refuses an option it does not read, by name. What was an
+invisible confusion becomes a throw the moment the pin moves, and the cure is
+not to catch it but to stop sending a message property to a queue.</p>
+<p>So there are two defaults with two owners, <code>queueOptions</code> and <code>publishOptions</code>,
+and each call site merges only its own.</p>
+</dd>
+<dt><a href="#ServiceDiscovery">ServiceDiscovery</a></dt>
+<dd><p>ServiceDiscovery - Service discovery and health checking</p>
+</dd>
+</dl>
+
+## Constants
+
+<dl>
+<dt><a href="#DEFAULT_QUEUE_OPTIONS">DEFAULT_QUEUE_OPTIONS</a></dt>
+<dd><p>What describes the QUEUE. Handed to <code>mqClient.assertQueue()</code>, whose declared
+option set is <code>durable</code>, <code>arguments</code>, <code>exclusive</code>, <code>autoDelete</code>.</p>
+</dd>
+<dt><a href="#DEFAULT_PUBLISH_OPTIONS">DEFAULT_PUBLISH_OPTIONS</a></dt>
+<dd><p>What describes the MESSAGE. Handed to <code>mqClient.publish()</code>.</p>
+</dd>
+<dt><a href="#ServiceDiscovery">ServiceDiscovery</a></dt>
+<dd><p>CookbookRouter - routes a workflow message to a service queue.</p>
+<p>ONE responsibility, ONE method: <code>routeToService</code>. Execution, flow control,
+retry, DLQ and completion belong to <code>WorkflowOrchestrator</code>
+(confirmation <code>api/docs/governance/confirmations/cookbook-execution-owner.md</code>
+001), which is also this class&#39;s only caller —
+<code>WorkflowOrchestrator.js:78,233,241,1223,1230</code>.</p>
+</dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#describeValue">describeValue(value)</a> ⇒ <code>string</code></dt>
+<dd><p>Renders a refused value for an error message without ever printing it as a
+bare word: <code>&quot;300000&quot;</code> and <code>300000</code> look identical otherwise, and the whole
+point of the refusal is that they are not the same thing.</p>
+</dd>
+<dt><a href="#readCacheTTL">readCacheTTL(context, value)</a> ⇒ <code>number</code></dt>
+<dd><p>Reads the discovery cache lifetime: a required, non-negative integer of
+milliseconds, where <code>0</code> means &quot;no cache — every lookup reaches the registry&quot;.</p>
+<p><code>options.cacheTTL || 300000</code> is what this replaces, and <code>0</code> was the value it
+destroyed: a caller switching the cache off was given five minutes of cached
+<code>status</code> instead, with nothing said. A default that inverts the one override
+it is asked for is not a default (<code>architecture-principles.md</code> §3, §8), and
+the absent case is not a value at all — it is a missing decision, so it
+throws (§4).</p>
+</dd>
+</dl>
+
+<a name="@onlineapps/cookbook-router
+
+Message routing for cookbook workflows_ given a service name and a workflow
+message, publish it to that services workflow queue.
+
+The package does NOT execute cookbooks, drive flow control, retry, complete
+or dead-letter them. Those belong to `WorkflowOrchestrator` — confirmation
+`api/docs/governance/confirmations/cookbook-execution-owner.md` 001 — which
+is also the only caller_ it takes `createRouter`
+(WorkflowOrchestrator.js_71) and calls `routeToService` on the result
+(_78,233,241,1223,1230). The second routing rail, the retry rail and the
+queue/registry administration this package used to carry had zero callers
+outside it and were removed on 2026-09-02.module_"></a>
+
+## @onlineapps/cookbook-router
+
+Message routing for cookbook workflows: given a service name and a workflow
+message, publish it to that services workflow queue.
+
+The package does NOT execute cookbooks, drive flow control, retry, complete
+or dead-letter them. Those belong to `WorkflowOrchestrator` — confirmation
+`api/docs/governance/confirmations/cookbook-execution-owner.md` 001 — which
+is also the only caller: it takes `createRouter`
+(WorkflowOrchestrator.js:71) and calls `routeToService` on the result
+(:78,233,241,1223,1230). The second routing rail, the retry rail and the
+queue/registry administration this package used to carry had zero callers
+outside it and were removed on 2026-09-02.
+**See**: /api/shared/cookbook/cookbook-router/README.md  
+<a name="QueueManager"></a>
+
+## QueueManager
+QueueManager - Queue operations and management
+
+A QUEUE and a MESSAGE are two different things, and neither one's defaults
+belong to the other. Until d.396d this class held ONE object for both —
+`defaultOptions: { durable: true, persistent: true }` — and spread it into the
+publish AND into the queue declaration, so each call site was handed a key it
+has no use for. Measured in both directions on the unit tier:
+
+    assertQueue('split.queue', { durable: true, persistent: true })
+    publish('control.publish', …,  { durable: true, persistent: true })
+
+`persistent` is a message property (amqplib `Options.Publish`) and means
+nothing to a queue; `durable` is a queue property and means nothing to a
+message. Nothing objected, because `@onlineapps/mq-client-core` read the two
+keys it knew and dropped the rest in silence — and since d.396c it no longer
+does: `assertQueue()` refuses an option it does not read, by name. What was an
+invisible confusion becomes a throw the moment the pin moves, and the cure is
+not to catch it but to stop sending a message property to a queue.
+
+So there are two defaults with two owners, `queueOptions` and `publishOptions`,
+and each call site merges only its own.
+
+**Kind**: global class  
+
+* [QueueManager](#QueueManager)
+    * [.publish(queueName, message, options)](#QueueManager+publish) ⇒ <code>Promise.&lt;boolean&gt;</code>
+    * [.ensureQueue(queueName, options)](#QueueManager+ensureQueue) ⇒ <code>Promise.&lt;boolean&gt;</code>
+
+<a name="QueueManager+publish"></a>
+
+### queueManager.publish(queueName, message, options) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Publish message to queue
+
+**Kind**: instance method of [<code>QueueManager</code>](#QueueManager)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| queueName | <code>string</code> | Target queue name |
+| message | <code>Object</code> | Message to publish |
+| options | <code>Object</code> | Publishing options (amqplib `Options.Publish`) |
+
+<a name="QueueManager+ensureQueue"></a>
+
+### queueManager.ensureQueue(queueName, options) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Ensure queue exists
+
+**Kind**: instance method of [<code>QueueManager</code>](#QueueManager)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| queueName | <code>string</code> | Queue name |
+| options | <code>Object</code> | Queue options, as `mqClient.assertQueue()` declares   them (`durable`, `arguments`, `exclusive`, `autoDelete`). A limit is one   entry of `arguments`, in the broker's own vocabulary — `x-max-length`,   `x-message-ttl`. This class translates no friendlier spelling into one:   `maxLength` is a key the client does not read, and since d.396c it says so   by name instead of dropping it. |
+
+<a name="ServiceDiscovery"></a>
+
+## ServiceDiscovery
+ServiceDiscovery - Service discovery and health checking
+
+**Kind**: global class  
+<a name="ServiceDiscovery+isServiceAvailable"></a>
+
+### serviceDiscovery.isServiceAvailable(serviceName) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Check if a service is available
+
+**Kind**: instance method of [<code>ServiceDiscovery</code>](#ServiceDiscovery)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| serviceName | <code>string</code> | Service name |
+
+<a name="DEFAULT_QUEUE_OPTIONS"></a>
+
+## DEFAULT\_QUEUE\_OPTIONS
+What describes the QUEUE. Handed to `mqClient.assertQueue()`, whose declared
+option set is `durable`, `arguments`, `exclusive`, `autoDelete`.
+
+**Kind**: global constant  
+<a name="DEFAULT_PUBLISH_OPTIONS"></a>
+
+## DEFAULT\_PUBLISH\_OPTIONS
+What describes the MESSAGE. Handed to `mqClient.publish()`.
+
+**Kind**: global constant  
+<a name="ServiceDiscovery"></a>
+
+## ServiceDiscovery
+CookbookRouter - routes a workflow message to a service queue.
+
+ONE responsibility, ONE method: `routeToService`. Execution, flow control,
+retry, DLQ and completion belong to `WorkflowOrchestrator`
+(confirmation `api/docs/governance/confirmations/cookbook-execution-owner.md`
+001), which is also this class's only caller —
+`WorkflowOrchestrator.js:78,233,241,1223,1230`.
+
+**Kind**: global constant  
+**See**: /api/shared/cookbook/cookbook-router/README.md  
+<a name="ServiceDiscovery+isServiceAvailable"></a>
+
+### serviceDiscovery.isServiceAvailable(serviceName) ⇒ <code>Promise.&lt;boolean&gt;</code>
+Check if a service is available
+
+**Kind**: instance method of [<code>ServiceDiscovery</code>](#ServiceDiscovery)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| serviceName | <code>string</code> | Service name |
+
+<a name="describeValue"></a>
+
+## describeValue(value) ⇒ <code>string</code>
+Renders a refused value for an error message without ever printing it as a
+bare word: `"300000"` and `300000` look identical otherwise, and the whole
+point of the refusal is that they are not the same thing.
+
+**Kind**: global function  
+
+| Param | Type |
+| --- | --- |
+| value | <code>\*</code> | 
+
+<a name="readCacheTTL"></a>
+
+## readCacheTTL(context, value) ⇒ <code>number</code>
+Reads the discovery cache lifetime: a required, non-negative integer of
+milliseconds, where `0` means "no cache — every lookup reaches the registry".
+
+`options.cacheTTL || 300000` is what this replaces, and `0` was the value it
+destroyed: a caller switching the cache off was given five minutes of cached
+`status` instead, with nothing said. A default that inverts the one override
+it is asked for is not a default (`architecture-principles.md` §3, §8), and
+the absent case is not a value at all — it is a missing decision, so it
+throws (§4).
+
+**Kind**: global function  
+**Throws**:
+
+- <code>Error</code> when the value is absent, or is not an integer >= 0
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| context | <code>string</code> | Name of the caller for the message |
+| value | <code>\*</code> | The value the caller passed as `options.cacheTTL` |
+

package/CHANGELOG.md

@@ -0,0 +1,242 @@
+# Changelog — @onlineapps/cookbook-router
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+## [4.0.0] — 2026-09-27
+
+### Changed — BREAKING: `logger` and `cacheTTL` are required, and `0` is a value (d.615)
+
+Three constructors read their options with `||`:
+
+    logger:   options.logger   || console     (router.js, serviceDiscovery.js, queueManager.js)
+    cacheTTL: options.cacheTTL || 300000      (serviceDiscovery.js)
+
+Both are the shape `.claude/rules/architecture-principles.md` §3 bans by name,
+and the second did measurable harm beyond the principle. `cacheTTL: 0` means
+"ask the registry every time"; `||` is false for `0`, so that request became
+five minutes of cached `status` instead — the exact opposite of what the caller
+asked for, decided in silence. A caller who had switched the cache off was
+served a service's liveness from memory for 300 seconds and had no way to see
+it. `logger || console` is the quieter half: a component nobody handed a logger
+wrote to a stream no collector reads, on a platform where every neighbouring
+package refuses the same omission by name.
+
+So both keys are now **required** and checked in the constructor (§4):
+
+- `logger` must be an object with `info`, `warn`, `error` and `debug` as
+  functions. Absent → `[<class>] logger is required - Expected: a logger with
+  info/warn/error/debug, so <reason>. Fix: pass options.logger …`; incomplete →
+  the same message naming the missing methods. `console` satisfies the shape and
+  is still accepted — when a caller passes it deliberately.
+- `cacheTTL` must be an integer `>= 0`, in milliseconds. Absent (or `null`, the
+  way `WorkflowOrchestrator.readNumericOption` reads an omitted number) →
+  `cacheTTL is required`; `NaN`, negative, fractional, `Infinity`, a numeric
+  string or a boolean → `cacheTTL is invalid - … got <value>`, with the value
+  rendered so `"300000"` and `300000` cannot be confused.
+- `cacheTTL: 0` is accepted and means **no cache**: `getCached` now compares
+  `age >= cacheTTL` rather than `age > cacheTTL`, so an entry whose age has
+  reached its lifetime is spent and every lookup reaches the registry. With `>`
+  two lookups inside one millisecond would still have hit the cache, and "no
+  cache" would have held only most of the time.
+
+The checks live in one new module, `src/options.js`, because all three
+constructors read `logger` with the same meaning and a second copy inside one
+package is two rails for one concern (`change-discipline.md` § One rail per
+concern). The logger contract itself comes from `@onlineapps/logger-contract`,
+which owns it platform-wide: `src/options.js` re-exports its `assertLogger`
+rather than restating it, now that the publication wave has pinned the package
+(`f60f24c3`, `@onlineapps/logger-contract 2.0.0`). Until that pin existed the
+check was a hand-written copy here, word for word identical — so the swap cost
+one import and no re-test: every message assertion in the suite passed
+unchanged. `readCacheTTL` stays this package's own, because `cacheTTL` is its
+own option and no library owns it.
+
+**For the caller:** `@onlineapps/conn-orch-orchestrator` built the router with
+`createRouter(this.mqClient, this.registryClient, { logger: this.logger })` in
+`WorkflowOrchestrator` — a logger but no `cacheTTL`. It passes one since d.615b
+(`config.serviceDiscoveryCacheTTL`, default 300000, `0` honoured), so this major
+has its caller ready before it is published. Nothing else in the workspace
+constructs these classes: `conn-orch-cookbook` only destructures and re-exports
+them.
+
+Tests: `tests/unit/required-options.test.js` (26), covering each refusal by its
+message, `cacheTTL: 0` sending three lookups to the registry, the control that a
+real TTL still serves the second from cache, the control that the whole chain
+still routes end to end with the real collaborators, and — since the pin — that
+`options.assertLogger` IS the library's function (identity, not an equal copy)
+and that the module exports no second `LOGGER_METHODS`.
+
+### Removed — BREAKING: `cacheEnabled`, druhá kolej pro „necachuj" (d.615b)
+
+`ServiceDiscovery` odpovídal na otázku „mám si pamatovat odpověď registru?"
+dvěma klíči: `cacheEnabled` (`options.cacheEnabled !== false`) a — od d.615 —
+`cacheTTL`, kde `0` znamená bez cache. Obě odpovědi šly napsat proti sobě:
+`{ cacheEnabled: true, cacheTTL: 0 }` i `{ cacheEnabled: false, cacheTTL: 300000 }`
+byly platné a v každé z nich jeden z těch dvou klíčů lhal. Jedna starost, dvě
+koleje (`change-discipline.md` § One rail per concern) — a `cacheEnabled` navíc
+implicitní default rozhodovaný z `!== false` (§8).
+
+Zůstává `cacheTTL`: jedna hodnota říká obojí — jestli cachovat a jak dlouho.
+Kdo nechce cachovat, napíše `0`; od téhle dávky se při něm do `Map` ani nic
+nezapisuje. Klíč `cacheEnabled` se nečte vůbec (nepřekládá se, nevaruje,
+neodmítá) — volající, který ho ještě pošle, dostane to, co říká životnost.
+
+Čtyři otázky `change-discipline.md` § Removing something removes its declaration:
+
+1. **Proč vznikl.** Přišel s balíkem do `shared/` (`d05bb7be`, restrukturalizace)
+   jako přepínač „tenhle volající nechce discovery-cache". `git log -S cacheEnabled
+   -- shared/cookbook/cookbook-router` zná od té doby tři commity (`d05bb7be`,
+   `144db203`, `7fa728e8`) a ani jeden z nich ten klíč nikde nenastavuje.
+2. **Která část koncepce ho nesla.** Žádná: nemá ADR, kontrakt ani model, jen
+   řádek v README § Options. Koncept „necachuj" vlastní od d.615 `cacheTTL`
+   (`0` = bez cache, `getCached` porovnává `age >= cacheTTL`).
+3. **Proč ho dnes nikdo nečte.** Mimo balík ho nikdy nikdo nenastavil. Jediný
+   stavitel routeru je `WorkflowOrchestrator` a ten posílá `{ logger, cacheTTL }`
+   (d.615b). Změřeno napříč workspace (`api`, `api_biz/*`, `fe_adminui`, mimo
+   `node_modules`): jediné další výskyty `cacheEnabled` patří `conn-base-storage`
+   a `conn-orch-registry` — vlastní, nesouvisející volby jejich vlastních tříd.
+4. **Je náhrada koncepčnější.** Ano. Jedna hodnota nemůže sama se sebou být
+   v rozporu, zatímco dvě klidně ano; a `0` je hodnota, kterou volající vysloví,
+   místo default odvozeného z `!== false`.
+
+Testy: `tests/unit/serviceDiscovery.test.js` — `cacheTTL: 0` je jediná cesta
+k „necachuj" (dva lookupy = dvě volání registru, `cache.size === 0`),
+`cacheEnabled: false` s reálnou životností cache NEvypne (druhý lookup jde z ní),
+a konstruktor po sobě nenechá `options.cacheEnabled`.
+
+### Changed — tarball nese CHANGELOG, README a API.md (d.1021)
+
+`files` v `package.json` jmenoval jen `src`, takže vydaný balíček nenesl `CHANGELOG.md`
+ani generované `API.md` — kdo měl router v `node_modules`, neviděl, co se mezi verzemi
+změnilo, ani referenci exportů. `files` je teď `src`, `CHANGELOG.md`, `README.md`,
+`API.md`. `README.md` npm přibaluje vždy; v seznamu stojí proto, aby obsah tarballu
+říkal jeden seznam, ne seznam plus pravidlo npm. Ze `src` nic neubylo
+(`npm pack --dry-run`: přibyly `API.md` a `CHANGELOG.md`).
+
+## [3.0.1] — 2026-09-16
+
+### Fixed — the unit tier claimed a queue declaration the client refuses (d.520)
+
+`should apply custom queue options` asserted that `ensureQueue('custom.queue',
+{ maxLength: 1000, messageTtl: 60000 })` reaches the declaration with those two
+keys. Neither half held: this package composes no queue argument — it merges its
+defaults with the caller's options and hands the result to
+`mqClient.assertQueue()` — and since d.396c of `@onlineapps/mq-client-core` that
+client refuses, by name, a key `assertQueue()` does not read:
+
+    [RabbitMQClient] Queue option not declared by assertQueue(): "maxLength",
+    "messageTtl" - Expected: only durable, arguments, exclusive, autoDelete.
+
+The test passed only because its client stub accepted anything. The stub now
+refuses exactly what the real client refuses, which makes it the guard of the
+file: every declaration any test here produces runs through it, so a key the
+client does not read cannot pass unnoticed. The claim itself is corrected to the
+broker vocabulary — `arguments: { 'x-max-length': 1000, 'x-message-ttl': 60000 }`
+— with the value asserted, not its presence.
+
+Added with it: the failure path (a friendlier spelling is refused and the refusal
+propagates — the package neither translates nor catches, and the queue is not
+remembered as ensured), the control case (a queue asked for without limits
+carries no `arguments` key at all), and a test that every declaration this
+package composes on its own — constructor defaults, the `publish()` path, a
+per-call merge — carries only keys the client reads.
+
+No behaviour change: `src/queueManager.js` already forwarded the declared option
+set, and its `ensureQueue()` doc now says where a limit belongs. `README.md`
+§ Options documents the shape.
+
+## [3.0.0] — 2026-09-14
+
+### BREAKING — `defaultOptions` is two keys, `queueOptions` and `publishOptions` (d.396d)
+
+A queue declaration and a message are two different things, and neither one's
+defaults belong to the other. One object fed both — `{ durable: true,
+persistent: true }`, spread into the publish AND into the queue declaration — so
+each call site was handed a key it has no use for. Measured in both directions
+on the unit tier:
+
+    assertQueue('split.queue', { durable: true, persistent: true })
+    publish('control.publish', …,  { durable: true, persistent: true })
+
+`persistent` is a message property (amqplib `Options.Publish`) and means nothing
+to a queue; `durable` is a queue property and means nothing to a message.
+Nothing objected, because `@onlineapps/mq-client-core` read the two keys it knew
+and dropped the rest in silence — and since its d.396c it no longer does:
+`assertQueue()` refuses an option it does not read, by name. What was an
+invisible confusion becomes a throw the moment the pin moves, and the cure is
+not to catch it but to stop sending a message property to a queue.
+
+- `queueOptions` (default `{ durable: true }`) is merged into every queue
+  declaration and reaches `mqClient.assertQueue()`, whose declared option set is
+  `durable`, `arguments`, `exclusive`, `autoDelete`.
+- `publishOptions` (default `{ persistent: true }`) is merged into every publish
+  and reaches `mqClient.publish()` as amqplib message properties.
+- Per-call options are unchanged: `ensureQueue(queue, options)` and
+  `publish(queue, message, options)` still override their own defaults.
+
+**Fixed in the same expression:** the constructor spread `...options` AFTER the
+computed block, which undid the merge it was written to extend — a caller
+passing `{ durable: false }` replaced the whole defaults object instead of
+overriding one key of it, and lost the other default with it. `...options` now
+comes first, so every key this class does not compute is still forwarded
+untouched (`router.js` hands its whole options object to both collaborators) and
+the computed keys survive.
+
+**Callers:** none. `defaultOptions` was measured across `api`, `api_biz` and
+`fe_adminui` (no `node_modules`) on 2026-09-14 — nothing outside this package
+constructs `QueueManager` or writes the key; `config/libraries.json` pins the
+package, and `api/jest.config.unit.js` lists it, neither of which passes options.
+
+RED (unit): 8 of 24, with the leak named in both directions —
+`+ "persistent": true` inside the `assertQueue` call and `+ "durable": true`
+inside the publish options. GREEN: 24/24 in the file, 63/63 for the package.
+
+### BREAKING — the package routes, and does nothing else (DÁVKA 83)
+
+Execution, flow control, retry, completion and dead-lettering have exactly one
+owner, `WorkflowOrchestrator` — confirmation
+[`cookbook-execution-owner.md`](/api/docs/governance/confirmations/cookbook-execution-owner.md)
+001. This package carried a second copy of most of it. Measured on 2026-09-02
+across `api/shared`, `api/infra`, `api_biz` and `fe_adminui` (no
+`node_modules`), every removed member had **zero callers outside this package**;
+the only live chain is `createRouter` → `routeToService` →
+`isServiceAvailable` → `publish` → `ensureQueue`, which
+`WorkflowOrchestrator.js:71,78,233,241,1223,1230` uses and nothing else does.
+
+Removed:
+
+- `CookbookRouter`: `routeWorkflow`, `routeToNextService`, `routeToCompleted`,
+  `routeToDLQ`, `determineTargetService`, `buildWorkflowMessage`, `handleRetry`.
+  `routeToService` and the constructor stay.
+- `RetryHandler` — the whole class and its module, reachable only from
+  `handleRetry`. It is no longer exported here, nor re-exported by
+  `@onlineapps/conn-orch-cookbook`. Retry with backoff lives in
+  `WorkflowOrchestrator.js:495`, and the exhausted-retry publish to
+  `workflow.failed` at `:574`.
+- `QueueManager`: `consume`, `getQueueInfo`, `purgeQueue`, `deleteQueue`,
+  `resetConnection`. Consumption belongs to `@onlineapps/mq-client-core` through
+  `ServiceWrapper`. Removing `consume` also closes the open ack/nack question
+  recorded against `queueManager.js` in `api/shared/TODO.md`: the code it asked
+  about is gone.
+- `ServiceDiscovery`: `getServiceInfo`, `listAvailableServices`,
+  `getServiceQueue`, `invalidateCache`. `isServiceAvailable` and its TTL cache
+  stay.
+- `CookbookRouter` option defaults `defaultQueue`, `completedQueue`, `dlqSuffix`,
+  `maxRetries`, `retryDelay`. The first three fed the removed routing rail; the
+  last two had no reader even before it — `RetryHandler` keyed on `maxAttempts`
+  and `baseDelay`, never on these. `logger` is the only key the class reads, and
+  the caller's `options` still reach `ServiceDiscovery` and `QueueManager`
+  whole. A declaration nothing reads is dead
+  (`.claude/rules/change-discipline.md` § Removing).
+
+Also in this change: the package gained a `jest.config.js` and a line in
+`api/jest.config.unit.js`, so its suites run in the api unit tier. They ran
+under no root npm script before — a whole sada outside the regression loop
+(`.claude/rules/service-refactoring.md` § forbidden action #4).
+
+The DÁVKA 78 fix that made `routeToNextService` and `handleRetry` find steps by
+`step_id` instead of `id` is superseded: both methods are gone, and so is the
+`id`-vs-`step_id` question in this package. `routeToService` takes a service
+name and an opaque message and reads no step identifier at all.

package/README.md

@@ -47,7 +47,7 @@ const { createRouter, CookbookRouter, ServiceDiscovery, QueueManager } =
 ```javascript
 const { createRouter } = require('@onlineapps/cookbook-router');
 
-const router = createRouter(mqClient, registryClient, { logger });
+const router = createRouter(mqClient, registryClient, { logger, cacheTTL: 300000 });
 
 // Publishes to `biz-invoicing.workflow`.
 await router.routeToService('biz-invoicing', workflowMessage);
@@ -64,18 +64,45 @@ await router.routeToService('biz-invoicing', workflowMessage);
 
 ## Options
 
-The single caller passes `{ logger }` and nothing else. `options` is forwarded
-verbatim to both collaborators, so their keys travel through it:
+The caller passes `{ logger, cacheTTL }`; everything else has a default.
+`options` is forwarded verbatim to both collaborators, so their keys travel
+through it:
 
 | Key | Read by | Default |
 |---|---|---|
-| `logger` | `CookbookRouter`, `ServiceDiscovery`, `QueueManager` | `console` |
-| `cacheEnabled` | `ServiceDiscovery` | `true` |
-| `cacheTTL` | `ServiceDiscovery` (ms) | `300000` |
+| `logger` | `CookbookRouter`, `ServiceDiscovery`, `QueueManager` | **required** |
+| `cacheTTL` | `ServiceDiscovery` (ms) | **required** |
 | `ensureQueues` | `QueueManager` — assert the queue before the first publish | `true` |
 | `queueOptions` | `QueueManager` — merged into every queue declaration | `{ durable: true }` |
 | `publishOptions` | `QueueManager` — merged into every publish | `{ persistent: true }` |
 
+What a `logger` IS comes from `@onlineapps/logger-contract` (pinned in
+`f60f24c3`): `src/options.js` re-exports its `assertLogger`, so the four methods
+and the wording below are the platform's, not this package's.
+
+The two required keys are checked in the constructor, and each refusal names
+the key:
+
+| Condition | Result |
+|---|---|
+| `logger` absent | throws `[<class>] logger is required - Expected: a logger with info/warn/error/debug, …` |
+| `logger` missing a method | throws `[<class>] logger is incomplete - … missing: debug. Fix: pass a logger implementing all four.` |
+| `cacheTTL` absent or `null` | throws `[ServiceDiscovery] cacheTTL is required - Expected: an integer >= 0, milliseconds …` |
+| `cacheTTL` not an integer `>= 0` | throws `[ServiceDiscovery] cacheTTL is invalid - … got <value>.` |
+
+`cacheTTL: 0` is a value, not an absence: it means **no cache** — every
+`isServiceAvailable` lookup reaches the registry, and nothing is written to the
+Map on the way. Until d.615 it was read as `options.cacheTTL || 300000`, so that
+request silently became five minutes of cached `status`, and `logger` was read as
+`options.logger || console`, so a caller who passed none had its output written
+where nothing collects it.
+
+It is also the **only** way to say it. `cacheEnabled` was a second key for the
+same question until d.615b: with both, `{ cacheEnabled: true, cacheTTL: 0 }` and
+`{ cacheEnabled: false, cacheTTL: 300000 }` were sayable, and in each of them one
+of the two keys was a lie. The key is no longer read at all — a caller who still
+passes it gets what the lifetime says.
+
 A queue declaration and a message are two different things, so their defaults
 are two objects with two owners. `queueOptions` reaches
 `mqClient.assertQueue()`, whose declared option set is `durable`, `arguments`,
@@ -84,6 +111,23 @@ amqplib message properties. One object fed both until d.396d, which meant the
 queue was declared with `persistent` and the message published with `durable` —
 neither of which the receiving side reads.
 
+A queue limit — how long a message lives, how many the queue holds — is one
+entry of `arguments`, written in the broker's own vocabulary: `x-message-ttl`,
+`x-max-length`. This package translates nothing: `queueOptions` and the per-call
+`options` of `ensureQueue()` are merged and handed to `assertQueue()` as they
+are, so a friendlier spelling such as `maxLength` arrives at the client as a key
+it does not read, and the client refuses it by name rather than dropping it:
+
+    ensureQueue('quotes.workflow', {
+      arguments: { 'x-max-length': 1000, 'x-message-ttl': 60000 }
+    })
+    → assertQueue('quotes.workflow', {
+        durable: true,
+        arguments: { 'x-max-length': 1000, 'x-message-ttl': 60000 }
+      })
+
+A queue asked for without limits carries no `arguments` key at all.
+
 A key not in this table is not read by anything here.
 
 ## Queue naming

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/cookbook-router",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description": "Message routing for cookbook workflows - handles service discovery and queue routing",
   "oa": {
     "category": "orchestration"
@@ -22,7 +22,9 @@
   ],
   "author": "OnlineApps",
   "license": "PROPRIETARY",
-  "dependencies": {},
+  "dependencies": {
+    "@onlineapps/logger-contract": "2.0.0"
+  },
   "devDependencies": {
     "jest": "^29.7.0",
     "jsdoc-to-markdown": "^8.0.0"
@@ -31,7 +33,10 @@
     "node": ">=24.0.0 <25"
   },
   "files": [
-    "src"
+    "src",
+    "CHANGELOG.md",
+    "README.md",
+    "API.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/options.js

@@ -0,0 +1,79 @@
+'use strict';
+
+/**
+ * The option checks this package's three constructors share.
+ *
+ * ONE place, because all three read the same key with the same meaning: a
+ * second copy of "what a logger is" inside one package would be two rails for
+ * one concern (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * For `logger` that one place is not here at all: the platform owns the concern
+ * in `@onlineapps/logger-contract`, and this module re-exports `assertLogger`
+ * from it. d.615 carried a hand-written copy, word for word identical, only
+ * because the package declared no dependencies; the publication wave pinned
+ * `@onlineapps/logger-contract 2.0.0` (`f60f24c3`), and a declared dependency
+ * nothing requires is what `change-discipline.md` § Removing something removes
+ * its declaration calls a defect. So the copy is gone — including its own
+ * `LOGGER_METHODS`, which this module no longer exports: whoever needs the list
+ * reads it from the package that defines it.
+ *
+ * `readCacheTTL` stays here. `cacheTTL` is this package's own option, read by
+ * `ServiceDiscovery` alone; no library owns it.
+ *
+ * @see /api/shared/logger-contract/src/index.js
+ */
+
+const { assertLogger } = require('@onlineapps/logger-contract');
+
+/**
+ * Renders a refused value for an error message without ever printing it as a
+ * bare word: `"300000"` and `300000` look identical otherwise, and the whole
+ * point of the refusal is that they are not the same thing.
+ *
+ * @param {*} value
+ * @returns {string}
+ */
+function describeValue(value) {
+  return typeof value === 'string' ? JSON.stringify(value) : String(value);
+}
+
+/**
+ * Reads the discovery cache lifetime: a required, non-negative integer of
+ * milliseconds, where `0` means "no cache — every lookup reaches the registry".
+ *
+ * `options.cacheTTL || 300000` is what this replaces, and `0` was the value it
+ * destroyed: a caller switching the cache off was given five minutes of cached
+ * `status` instead, with nothing said. A default that inverts the one override
+ * it is asked for is not a default (`architecture-principles.md` §3, §8), and
+ * the absent case is not a value at all — it is a missing decision, so it
+ * throws (§4).
+ *
+ * @param {string} context - Name of the caller for the message
+ * @param {*} value - The value the caller passed as `options.cacheTTL`
+ * @returns {number}
+ * @throws {Error} when the value is absent, or is not an integer >= 0
+ */
+function readCacheTTL(context, value) {
+  if (value === undefined || value === null) {
+    throw new Error(
+      `[${context}] cacheTTL is required - Expected: an integer >= 0, milliseconds `
+      + '(0 = no cache, every lookup reaches the registry). '
+      + 'Fix: pass options.cacheTTL, e.g. 300000 for five minutes.'
+    );
+  }
+
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(
+      `[${context}] cacheTTL is invalid - Expected: an integer >= 0, milliseconds `
+      + `(0 = no cache); got ${describeValue(value)}. `
+      + 'Fix: pass options.cacheTTL as a non-negative integer, or 0 to switch the cache off.'
+    );
+  }
+
+  return value;
+}
+
+module.exports = {
+  assertLogger,
+  readCacheTTL
+};

package/src/queueManager.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { assertLogger } = require('./options');
+
 /**
  * What describes the QUEUE. Handed to `mqClient.assertQueue()`, whose declared
  * option set is `durable`, `arguments`, `exclusive`, `autoDelete`.
@@ -52,7 +54,11 @@ class QueueManager {
         ...DEFAULT_PUBLISH_OPTIONS,
         ...options.publishOptions
       },
-      logger: options.logger || console
+      logger: assertLogger(
+        'QueueManager',
+        options.logger,
+        'a publish and its failure are reported somewhere that collects it'
+      )
     };
 
     this.ensuredQueues = new Set();
@@ -111,7 +117,11 @@ class QueueManager {
    * Ensure queue exists
    * @param {string} queueName - Queue name
    * @param {Object} options - Queue options, as `mqClient.assertQueue()` declares
-   *   them (`durable`, `arguments`, `exclusive`, `autoDelete`)
+   *   them (`durable`, `arguments`, `exclusive`, `autoDelete`). A limit is one
+   *   entry of `arguments`, in the broker's own vocabulary — `x-max-length`,
+   *   `x-message-ttl`. This class translates no friendlier spelling into one:
+   *   `maxLength` is a key the client does not read, and since d.396c it says so
+   *   by name instead of dropping it.
    * @returns {Promise<boolean>}
    */
   async ensureQueue(queueName, options = {}) {

package/src/router.js

@@ -14,6 +14,7 @@
 
 const ServiceDiscovery = require('./serviceDiscovery');
 const QueueManager = require('./queueManager');
+const { assertLogger } = require('./options');
 
 class CookbookRouter {
   constructor(mqClient, registryClient, options = {}) {
@@ -26,11 +27,20 @@ class CookbookRouter {
     // keyed on `maxAttempts`/`baseDelay`, never on these. A declaration nothing
     // reads is dead (`.claude/rules/change-discipline.md` § Removing).
     // `options` is still forwarded whole to the two collaborators below, so
-    // their own keys (`cacheEnabled`, `cacheTTL`, `ensureQueues`,
-    // `queueOptions`, `publishOptions`) reach them unchanged.
+    // their own keys (`cacheTTL`, `ensureQueues`, `queueOptions`,
+    // `publishOptions`) reach them unchanged.
+    // `logger` used to default to `console` here. It no longer defaults at all:
+    // a router that logs where nothing collects is a router whose routing
+    // decisions are unobservable, and `||`/an implicit default is exactly what
+    // §3 bans. The check runs BEFORE the collaborators are built so the caller
+    // is told which object refused, in this class's own name.
     this.options = {
-      logger: console,
-      ...options
+      ...options,
+      logger: assertLogger(
+        'CookbookRouter',
+        options.logger,
+        'every routing decision is reported somewhere that collects it'
+      )
     };
 
     this.serviceDiscovery = new ServiceDiscovery(registryClient, options);

package/src/serviceDiscovery.js

@@ -1,17 +1,24 @@
 'use strict';
 
+const { assertLogger, readCacheTTL } = require('./options');
+
 /**
  * ServiceDiscovery - Service discovery and health checking
  */
-
 class ServiceDiscovery {
   constructor(registryClient, options = {}) {
     this.registryClient = registryClient;
+    // `...options` comes FIRST so the two checked keys below survive it — the
+    // same order `QueueManager` uses, and for the same reason: a spread placed
+    // last undoes the block it was written to extend.
     this.options = {
-      cacheEnabled: options.cacheEnabled !== false,
-      cacheTTL: options.cacheTTL || 300000, // 5 minutes default
-      logger: options.logger || console,
-      ...options
+      ...options,
+      cacheTTL: readCacheTTL('ServiceDiscovery', options.cacheTTL),
+      logger: assertLogger(
+        'ServiceDiscovery',
+        options.logger,
+        'a failed registry lookup is reported somewhere that collects it'
+      )
     };
 
     this.cache = new Map();
@@ -24,17 +31,19 @@ class ServiceDiscovery {
    */
   async isServiceAvailable(serviceName) {
     try {
-      // Check cache first if enabled
-      if (this.options.cacheEnabled) {
-        const cached = this.getCached(serviceName);
-        if (cached !== null) {
-          return cached.status === 'active';
-        }
+      // Whether there is anything to serve is `getCached`'s answer, and it reads
+      // the ONE value that decides it — the lifetime. Until d.615b a second key,
+      // `cacheEnabled`, guarded these two branches as well, so "do not cache"
+      // had two spellings that could contradict each other
+      // (`.claude/rules/change-discipline.md` § One rail per concern).
+      const cached = this.getCached(serviceName);
+      if (cached !== null) {
+        return cached.status === 'active';
       }
 
       const service = await this.registryClient.getService(serviceName);
 
-      if (service && this.options.cacheEnabled) {
+      if (service) {
         this.setCached(serviceName, service);
       }
 
@@ -55,18 +64,19 @@ class ServiceDiscovery {
    * @private
    */
   getCached(serviceName) {
-    if (!this.options.cacheEnabled) {
-      return null;
-    }
-
     const cached = this.cache.get(serviceName);
 
     if (!cached) {
       return null;
     }
 
+    // `>=`, not `>`: an entry whose age has REACHED the lifetime is spent, and
+    // that is what makes `cacheTTL: 0` mean what it says — every age is `>= 0`,
+    // so no entry is ever served and each lookup reaches the registry. With
+    // `>` the two lookups inside one millisecond would have hit the cache, and
+    // "no cache" would have been true only most of the time.
     const age = Date.now() - cached.timestamp;
-    if (age > this.options.cacheTTL) {
+    if (age >= this.options.cacheTTL) {
       this.cache.delete(serviceName);
       return null;
     }
@@ -79,6 +89,14 @@ class ServiceDiscovery {
    * @private
    */
   setCached(serviceName, data) {
+    // `cacheTTL: 0` means no cache, so there is nothing to remember: `getCached`
+    // compares `age >= cacheTTL`, so an entry written with a zero lifetime is
+    // spent the moment it exists and the Map would grow with entries no lookup
+    // can ever be served from. Same single value decides here as there.
+    if (this.options.cacheTTL === 0) {
+      return;
+    }
+
     this.cache.set(serviceName, {
       data,
       timestamp: Date.now()