@onlineapps/cookbook-router 3.0.1 → 5.0.0

package/API.md

@@ -0,0 +1,297 @@
+## 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_ its constructor takes `createRouter` (through
+`cookbook.createRouter`), and `processWorkflowMessage` and the method that
+hands the next steps message to the router call `routeToService` on the
+result. 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: its constructor takes `createRouter` (through
+`cookbook.createRouter`), and `processWorkflowMessage` and the method that
+hands the next steps message to the router call `routeToService` on the
+result. 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="#CookbookRouter">CookbookRouter</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>processWorkflowMessage()</code> and
+the method that hands the next step&#39;s message to the router.</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>
+</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_ its constructor takes `createRouter` (through
+`cookbook.createRouter`), and `processWorkflowMessage` and the method that
+hands the next steps message to the router call `routeToService` on the
+result. 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: its constructor takes `createRouter` (through
+`cookbook.createRouter`), and `processWorkflowMessage` and the method that
+hands the next steps message to the router call `routeToService` on the
+result. 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="CookbookRouter"></a>
+
+## CookbookRouter
+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: `processWorkflowMessage()` and
+the method that hands the next step's message to the router.
+
+**Kind**: global class  
+**See**: /api/shared/cookbook/cookbook-router/README.md  
+<a name="CookbookRouter+routeToService"></a>
+
+### cookbookRouter.routeToService(serviceName, message, [publishOptions]) ⇒ <code>Promise.&lt;void&gt;</code>
+Route message directly to a specific service
+
+**Kind**: instance method of [<code>CookbookRouter</code>](#CookbookRouter)  
+**Throws**:
+
+- <code>Error</code> when `publishOptions` is given and is not a plain object —
+  before the registry is asked and before anything is published
+
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| serviceName | <code>string</code> |  | Target service name |
+| message | <code>Object</code> |  | Workflow message to send |
+| [publishOptions] | <code>Object</code> | <code>{}</code> | Publish options for this one message,   handed unchanged as the third argument of `QueueManager.publish()`, which   merges them over its message defaults and passes them to the MQ client   (e.g. `{ bufferOnFailure: false }`). The router neither reads nor completes   them: a key the MQ client does not know is the client's to ignore. Must be   a plain object when given. |
+
+<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.
+
+`false` is the registry's answer: the service is there and not active, or the
+projection does not hold it (`getService()` resolved to `null`). A lookup the
+registry could not answer is not that answer, so it is thrown with its cause
+rather than read as "not available" (d.1086; architecture-principles.md §3–§5).
+A failed lookup is never cached.
+
+**Kind**: instance method of [<code>ServiceDiscovery</code>](#ServiceDiscovery)  
+**Throws**:
+
+- <code>Error</code> `code: 'SERVICE_DISCOVERY_FAILED'`, `serviceName`, and the
+  registry's rejection as `cause`, when `registryClient.getService()` rejects;
+  `type` copied from the cause when the cause declares one (d.1093).
+
+
+| 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="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,360 @@
+# Changelog — @onlineapps/cookbook-router
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+## [5.0.0] — 2026-10-03
+
+pin: `@onlineapps/conn-orch-registry` 7.0.0 → 8.0.0
+
+### Changed — BREAKING: selhání registru už není „Service not available" (d.1086)
+
+Pro volajícího `isServiceAvailable()` a `routeToService()` se mění kontrakt: při odmítnutí
+`registryClient.getService()` dřív dostal `false` (a `routeToService` chybu
+`Service not available`), teď dostane odmítnutí s `code: 'SERVICE_DISCOVERY_FAILED'`.
+
+- `ServiceDiscovery.isServiceAvailable()` spolkla odmítnutí `registryClient.getService()`:
+  zalogovala ho a vrátila `false`, takže `routeToService` hlásil
+  `[CookbookRouter] Service not available: <služba>` a příčina (nedostupný Redis, poškozený
+  záznam projekce, chyba zapojení) do neúspěšného běhu nedošla (architecture-principles §3–§5).
+  Nově se odmítnutí dál loguje a **vyhodí** jako `Error` s `code: 'SERVICE_DISCOVERY_FAILED'`,
+  `serviceName` a původní chybou v `cause`; `routeToService` ji nechá projít. Neúspěšný dotaz
+  se necachuje.
+- `false` zůstává jen odpovědí registru: služba není `active`, nebo ji projekce nedrží
+  (`getService()` → `null`). Pro neznámou službu metoda dřív vracela `null` místo slíbeného
+  `boolean`; nyní `false`.
+- Klasifikace pro retry se nemění: `SERVICE_DISCOVERY_FAILED` klasifikátor
+  (`error-handler-core`) nezná → `UNKNOWN`, stejně jako dřívější „Service not available".
+
+### Changed — jedna cesta chyby discovery, mrtvá větev `ECONNREFUSED` pryč (d.1092)
+
+- `ServiceDiscovery.isServiceAvailable()` logovala odmítnutí s `code === 'ECONNREFUSED'`
+  jinou řádkou (`Registry connection failed`). Větev zbyla z HTTP discovery; dotaz dnes čte
+  Redis projekci (conf `biz-discovery-redis` 001, ADR 0005) a jeho klient takový `code`
+  nedává, takže nebyla dosažitelná. Každé odmítnutí se teď loguje jednou řádkou
+  `Service discovery failed for <služba>:` a hází stejně jako dřív
+  (`SERVICE_DISCOVERY_FAILED`, `cause` = původní chyba).
+
+### Added — `SERVICE_DISCOVERY_FAILED` nese `type` příčiny (d.1093)
+
+- Odmítnutí z `ServiceDiscovery.isServiceAvailable()` převezme `type` z `cause`, pokud ho
+  příčina má; jinak `type` nemá. Verdikt vzniká tam, kde vzniká chyba: `@onlineapps/conn-orch-registry`
+  `getService()` otypuje dotaz, na který projekce registru neodpověděla (termín / Redis
+  nedostupný), jako `TRANSIENT`, a klasifikátor L1 (`error-handler-core`) čte `type`, aniž by
+  znal Redis — krok tak jde do retry místo `non_retryable_unknown`. Příčina bez `type` se
+  klasifikuje jako dřív (`UNKNOWN`).
+
+### Added — integrační tier: discovery nad skutečným registry klientem a Redisem (d.1097)
+
+- Nový tier `npm run test:integration` (`jest.integration.config.js`, `tests/integration/`);
+  `npm test` = unit && integration. `globalSetup` ověří živý Redis (`REDIS_URL`, jediný klíč,
+  hodnota se nikdy nevypisuje) a bez něj běh odmítne s opravou; `jest.config.js` tier
+  vylučuje, takže do unit tieru api nevstoupí.
+- `ServiceDiscovery` se skládá s **nainstalovaným** `@onlineapps/conn-orch-registry` a `redis`
+  (devDependencies, přesné piny): služba v projekci `registry:services` jako `active` → `true`,
+  jiný stav nebo chybějící záznam → `false` (s kontrolou souseda v témže hashi), nečitelný
+  záznam, odpojený Redis, zavřený socket a chybová odpověď → `SERVICE_DISCOVERY_FAILED`
+  s původní chybou v `cause`. Živý Redis v databázi tieru, jen pole vlastního běhu.
+- Pojmenovaná mez: nainstalovaný registry klient chybu netypuje, proto sada tvrdí
+  `type === undefined`; strážní test verze zčervená při posunu pinu, kdy se tvrzení mění na
+  `TRANSIENT` a přibude scénář polootevřeného Redisu (conf `biz-discovery-redis` 003).
+
+### Fixed — `QueueManager.publish()` už publish neopakuje (d.1121)
+
+- Při odmítnutí, jehož text obsahoval `Connection lost`, volal `publish()` klienta podruhé.
+  Retry a buffer publishe vlastní `@onlineapps/mq-client-core` uvnitř každého `publish()`
+  (`docs/architecture/mq-publish-reliability.md` § The one rule for services); vyhozená
+  chyba znamená „nepotvrzeno" — zpráva je v bufferu klienta, nebo odmítnuta natrvalo — a druhé
+  volání by odeslalo druhou kopii. Rozhodovalo se navíc podle textu hlášky, ne podle typu.
+- Nově jedno volání na zprávu; odmítnutí se zaloguje a propadne volajícímu beze změny (týž
+  objekt). Měřeno nad vydaným `mq-client-core` 5.0.0 (skutečné `BaseClient`, `RabbitMQClient`,
+  `PublishLayer`, dvojník jen `amqplib.connect`): ztracené spojení bez obnovy, odmítnutá obnova
+  i kanál mrtvý pod potvrzením hodí `PublishError`/`ConnectionError`, žádná s `Connection lost`
+  v textu — větev na této verzi nebyla dosažitelná.
+
+### Added — `routeToService` nese volby publishe (d.1124)
+
+- `routeToService(serviceName, message, publishOptions = {})`: třetí argument se předá
+  beze změny jako třetí argument `QueueManager.publish()`, který ho sloučí přes výchozí volby
+  zprávy (`{ persistent: true }`) a pošle MQ klientovi. Router volby nečte ani nedoplňuje —
+  klíč, který klient nezná, je klientův k ignorování. Do d.1124 router třetí argument zahodil,
+  takže `{ bufferOnFailure: false }` orchestrátoru k MQ klientovi nedošel a klient zprávu
+  dalšího kroku po vyčerpaném publishi uložil do bufferu a po reconnectu odeslal podruhé
+  (změřeno d.1119).
+- Volby, jsou-li dány, musí být plain object; jinak `routeToService` hodí
+  `[CookbookRouter] routeToService - publishOptions must be an object - …` dřív, než se zeptá
+  registru, a nic nepublikuje. Bez třetího argumentu se chování nemění (`publish()` dostane `{}`).
+- `API.md` nově nese `CookbookRouter` a jeho `routeToService`: docblock třídy stál nad
+  `require('./serviceDiscovery')`, takže ho jsdoc2md vykreslil jako druhý záznam
+  „ServiceDiscovery" (konstanta) a třídu s metodou vynechal. Docblock je teď nad
+  `class CookbookRouter`; citace volajících jsou jmény metod `WorkflowOrchestrator`, ne
+  ručně psanými čísly řádků.
+
+### Tests — integrační helper staví registry klienta s `discoveryTimeoutMs` (d.1200)
+
+- Test, ne chování: `registryClientOver()` (`tests/integration/helpers.js`) stavěl klienta bez
+  `discoveryTimeoutMs`, který je od kontraktu registry 8.0.0 povinný (d.1093); se zdrojem
+  registry z `release/w4` proto padalo 11 z 12 testů integračního tieru hláškou
+  `Missing constructor option - discoveryTimeoutMs is required`. Helper teď předává hodnotu
+  z deklarace `REGISTRY_DISCOVERY_TIMEOUT_MS` v `config/shared-env.json` — tutéž, kterou wrapper
+  čte a klientovi předává — nikdy literál; chybějící nebo nečíselná deklarace skončí
+  pojmenovanou chybou. Tvrzení beze změny; `src/**` se nemění.
+
+### Changed — hláška `SERVICE_DISCOVERY_FAILED` bez dvojité tečky (d.1202)
+
+- `ServiceDiscovery.isServiceAvailable()` uzavíral citovanou příčinu vždy tečkou. Odmítnutí
+  registry klienta 8.0.0 jsou celé věty `[Context] Problem - Expected/Fix`, které tečkou už
+  končí, takže hláška četla `…retried as TRANSIENT.. Expected: …` (architecture-principles §5).
+  Příčina zakončená `.`, `!` nebo `?` se teď cituje beze změny; příčině bez koncové interpunkce
+  se tečka doplní jako dřív. Kód, `serviceName`, `cause` a `type` beze změny.
+
+### Tests — aserce objevování na kontrakt registry 8.0.0 (K13; d.1201)
+
+- Test, ne chování: `tests/integration/serviceDiscovery.integration.test.js` popisoval registry
+  klienta 7.0.0, který selhání dotazu netypuje (dva případy „NAMED LIMIT: untyped"). Registry
+  8.0.0 při `isReady === false` (offline s `disableOfflineQueue`, socket zavřený pod příkazem)
+  odmítne vlastní chybou `REGISTRY_DISCOVERY_UNAVAILABLE`, `type: 'TRANSIENT'`, s chybou
+  node-redis v její `cause` (d.1093). Oba případy teď tvrdí `SERVICE_DISCOVERY_FAILED` s
+  `type: 'TRANSIENT'`, v `cause` chybu registru (`code`, `type`) a pod ní původní třídu
+  node-redis (`ClientOfflineError`, `SocketClosedUnexpectedlyError`); offline případ dál tvrdí
+  celou hlášku. Strážní `INSTALLED_REGISTRY_VERSION` je `'8.0.0'`; devDependency
+  `@onlineapps/conn-orch-registry` přechází na 8.0.0 v témže commitu (K13). Chybová
+  odpověď připojeného Redisu a poškozený záznam projekce zůstávají netypované. `src/**` se nemění.
+
+## [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

@@ -36,8 +36,8 @@ const { createRouter, CookbookRouter, ServiceDiscovery, QueueManager } =
 
 | Export | What it is |
 |---|---|
-| `createRouter(mqClient, registryClient, options)` | Factory returning a `CookbookRouter`. This is what `WorkflowOrchestrator.js:71` takes. |
-| `CookbookRouter` | One method: `routeToService(serviceName, message)`. |
+| `createRouter(mqClient, registryClient, options)` | Factory returning a `CookbookRouter`. This is what the `WorkflowOrchestrator` constructor takes (through `cookbook.createRouter`). |
+| `CookbookRouter` | One method: `routeToService(serviceName, message, publishOptions)`. |
 | `ServiceDiscovery` | One method: `isServiceAvailable(serviceName)`, with a TTL cache. |
 | `QueueManager` | Two methods: `publish(queue, message, options)` and `ensureQueue(queue, options)`. |
 | `VERSION` | String constant. |
@@ -47,35 +47,71 @@ 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);
+
+// Publish options for this one message travel to the MQ client unchanged.
+await router.routeToService('biz-invoicing', workflowMessage, { bufferOnFailure: false });
 ```
 
+The optional third argument, `publishOptions`, is handed as-is to
+`QueueManager.publish()`, which merges it over the message defaults and passes it
+to the MQ client. The router neither reads nor completes it; without it the
+client gets the message defaults alone.
+
 `routeToService` fails fast and never publishes a message it could not place:
 
 | Condition | Result |
 |---|---|
 | `serviceName` missing or not a string | throws `[CookbookRouter] routeToService - serviceName is required and must be a string` |
 | `message` missing or not an object | throws `[CookbookRouter] routeToService - message is required and must be an object` |
+| `publishOptions` given and not a plain object | throws `[CookbookRouter] routeToService - publishOptions must be an object - …` |
 | registry says the service is not `active` | throws `[CookbookRouter] Service not available: <name>` |
 | the publish itself fails | the underlying error propagates unchanged |
 
 ## 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`,
@@ -112,11 +148,16 @@ orchestrator's, not this package's.
 ## Collaborator contracts
 
 - `registryClient.getService(serviceName)` resolves to an object whose `status`
-  is `'active'` when the service is up. A rejection is logged and read as "not
-  available" — `isServiceAvailable` returns `false`, it does not throw.
+  is `'active'` when the service is up, or to `null` when the registry does not
+  hold the service — both are answers, and `isServiceAvailable` returns `false`
+  for anything but `'active'`. A rejection is not an answer: it is logged and
+  thrown as `code: 'SERVICE_DISCOVERY_FAILED'` with `serviceName` and the
+  rejection as `cause`, and `routeToService` lets it through (d.1086) — never
+  "Service not available". A failed lookup is not cached.
 - `mqClient.assertQueue(queue, options)` and `mqClient.publish(queue, message,
-  options)`. `publish` retries exactly once when the error message contains
-  `Connection lost`; every other error propagates.
+  options)`. `publish` is called once per message; a rejection propagates
+  unchanged. Retry and buffering are the client's
+  (`docs/architecture/mq-publish-reliability.md` § The one rule for services).
 
 ## Related packages
 

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@onlineapps/cookbook-router",
-  "version": "3.0.1",
+  "version": "5.0.0",
   "description": "Message routing for cookbook workflows - handles service discovery and queue routing",
   "oa": {
     "category": "orchestration"
   },
   "main": "src/index.js",
   "scripts": {
-    "test": "npm run test:unit",
+    "test": "npm run test:unit && npm run test:integration",
     "test:unit": "jest tests/unit",
+    "test:integration": "jest --config=jest.integration.config.js",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
     "docs": "jsdoc2md --files 'src/**/*.js' > API.md.tmp && mv API.md.tmp API.md || (rm -f API.md.tmp; exit 1)"
@@ -22,16 +23,23 @@
   ],
   "author": "OnlineApps",
   "license": "PROPRIETARY",
-  "dependencies": {},
+  "dependencies": {
+    "@onlineapps/logger-contract": "2.0.0"
+  },
   "devDependencies": {
+    "@onlineapps/conn-orch-registry": "8.0.0",
     "jest": "^29.7.0",
-    "jsdoc-to-markdown": "^8.0.0"
+    "jsdoc-to-markdown": "^8.0.0",
+    "redis": "4.7.1"
   },
   "engines": {
     "node": ">=24.0.0 <25"
   },
   "files": [
-    "src"
+    "src",
+    "CHANGELOG.md",
+    "README.md",
+    "API.md"
   ],
   "publishConfig": {
     "access": "public"

package/src/index.js

@@ -9,9 +9,10 @@
  * 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
+ * is also the only caller: its constructor takes `createRouter` (through
+ * `cookbook.createRouter`), and `processWorkflowMessage` and the method that
+ * hands the next step's message to the router call `routeToService` on the
+ * result. 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.
  *

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();
@@ -88,18 +94,15 @@ class QueueManager {
 
       logger.debug(`Publishing to ${queueName}`);
 
-      // Handle connection errors with retry
-      try {
-        await this.mqClient.publish(queueName, messageWithTimestamp, publishOptions);
-        return true;
-      } catch (error) {
-        // If connection lost, retry once
-        if (error.message.includes('Connection lost')) {
-          await this.mqClient.publish(queueName, messageWithTimestamp, publishOptions);
-          return true;
-        }
-        throw error;
-      }
+      // ONE call. Retry, buffering and reconnect coordination live inside the
+      // client's `publish()` (`@onlineapps/mq-client-core`), so a rejection is its
+      // answer — the message was buffered for replay or refused for good — and a
+      // second call from here would be a second copy of it. Until d.1121 this
+      // published again whenever the rejection's text contained `Connection lost`:
+      // a service-side retry, decided on a sentence no client release produces.
+      // @see ../../../../docs/architecture/mq-publish-reliability.md § The one rule for services
+      await this.mqClient.publish(queueName, messageWithTimestamp, publishOptions);
+      return true;
 
     } catch (error) {
       logger.error(`Failed to publish to ${queueName}:`, error);

package/src/router.js

@@ -1,20 +1,34 @@
 'use strict';
 
+const ServiceDiscovery = require('./serviceDiscovery');
+const QueueManager = require('./queueManager');
+const { assertLogger } = require('./options');
+
+/**
+ * A plain object: `{}` or `Object.create(null)` — not `null`, an array, or an
+ * instance of another class (a `Map` of options would reach the MQ client as an
+ * object with no own keys).
+ * @private
+ * @param {*} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  if (value === null || typeof value !== 'object') return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
 /**
  * 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`.
+ * 001), which is also this class's only caller: `processWorkflowMessage()` and
+ * the method that hands the next step's message to the router.
  *
  * @see /api/shared/cookbook/cookbook-router/README.md
  */
-
-const ServiceDiscovery = require('./serviceDiscovery');
-const QueueManager = require('./queueManager');
-
 class CookbookRouter {
   constructor(mqClient, registryClient, options = {}) {
     this.mqClient = mqClient;
@@ -26,11 +40,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);
@@ -41,9 +64,17 @@ class CookbookRouter {
    * Route message directly to a specific service
    * @param {string} serviceName - Target service name
    * @param {Object} message - Workflow message to send
+   * @param {Object} [publishOptions={}] - Publish options for this one message,
+   *   handed unchanged as the third argument of `QueueManager.publish()`, which
+   *   merges them over its message defaults and passes them to the MQ client
+   *   (e.g. `{ bufferOnFailure: false }`). The router neither reads nor completes
+   *   them: a key the MQ client does not know is the client's to ignore. Must be
+   *   a plain object when given.
    * @returns {Promise<void>}
+   * @throws {Error} when `publishOptions` is given and is not a plain object —
+   *   before the registry is asked and before anything is published
    */
-  async routeToService(serviceName, message) {
+  async routeToService(serviceName, message, publishOptions = {}) {
     const { logger } = this.options;
 
     if (!serviceName || typeof serviceName !== 'string') {
@@ -52,6 +83,13 @@ class CookbookRouter {
     if (!message || typeof message !== 'object') {
       throw new Error('[CookbookRouter] routeToService - message is required and must be an object');
     }
+    if (!isPlainObject(publishOptions)) {
+      throw new Error(
+        '[CookbookRouter] routeToService - publishOptions must be an object - '
+        + 'Expected: a plain object of publish options (e.g. { bufferOnFailure: false }) or no third argument. '
+        + 'Fix: pass the options QueueManager.publish() hands to the MQ client, or omit the argument'
+      );
+    }
 
     // Verify service is available
     const isAvailable = await this.serviceDiscovery.isServiceAvailable(serviceName);
@@ -63,7 +101,7 @@ class CookbookRouter {
     const queueName = `${serviceName}.workflow`;
     logger.info(`[CookbookRouter] Routing to service: ${queueName}`);
 
-    await this.queueManager.publish(queueName, message);
+    await this.queueManager.publish(queueName, message, publishOptions);
   }
 }
 

package/src/serviceDiscovery.js

@@ -1,53 +1,91 @@
 '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();
   }
 
   /**
-   * Check if a service is available
+   * Check if a service is available.
+   *
+   * `false` is the registry's answer: the service is there and not active, or the
+   * projection does not hold it (`getService()` resolved to `null`). A lookup the
+   * registry could not answer is not that answer, so it is thrown with its cause
+   * rather than read as "not available" (d.1086; architecture-principles.md §3–§5).
+   * A failed lookup is never cached.
+   *
    * @param {string} serviceName - Service name
    * @returns {Promise<boolean>}
+   * @throws {Error} `code: 'SERVICE_DISCOVERY_FAILED'`, `serviceName`, and the
+   *   registry's rejection as `cause`, when `registryClient.getService()` rejects;
+   *   `type` copied from the cause when the cause declares one (d.1093).
    */
   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';
-        }
-      }
-
-      const service = await this.registryClient.getService(serviceName);
-
-      if (service && this.options.cacheEnabled) {
-        this.setCached(serviceName, service);
-      }
+    // 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';
+    }
 
-      return service && service.status === 'active';
+    let service;
+    try {
+      service = await this.registryClient.getService(serviceName);
     } catch (error) {
-      // Handle specific error codes
-      if (error.code === 'ECONNREFUSED') {
-        this.options.logger.error('Registry connection failed', { serviceName, error });
-      } else {
-        this.options.logger.error(`Service discovery failed for ${serviceName}:`, error);
+      this.options.logger.error(`Service discovery failed for ${serviceName}:`, error);
+      // The cause is quoted as a sentence. The registry's own refusals are whole
+      // `[Context] Problem - Expected/Fix` sentences that already end with a
+      // full stop (conn-orch-registry 8.0.0), so the stop is added only to a
+      // cause that does not close its own sentence (d.1202).
+      const cause = /[.!?]$/.test(error.message) ? error.message : `${error.message}.`;
+      const failure = new Error(
+        `[ServiceDiscovery] Registry lookup for service '${serviceName}' failed - ${cause} `
+        + 'Expected: the registry answers with the service summary or null. '
+        + 'Fix: make the registry projection reachable to this service (the cause names what failed); '
+        + 'an unanswered lookup is never read as an unavailable service.',
+        { cause: error }
+      );
+      failure.code = 'SERVICE_DISCOVERY_FAILED';
+      failure.serviceName = serviceName;
+      // The verdict is made where the failure is born, never here (d.1093): the
+      // registry client types a lookup the projection could not answer, and the
+      // L1 classifier reads `type` without knowing what a registry or Redis is.
+      // Carried only when the cause has one — no type is invented for a cause
+      // that declared none.
+      if (error.type !== undefined) {
+        failure.type = error.type;
       }
+      throw failure;
+    }
+
+    if (service === null) {
       return false;
     }
+
+    this.setCached(serviceName, service);
+    return service.status === 'active';
   }
 
   /**
@@ -55,18 +93,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 +118,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()