@onlineapps/cookbook-router 4.0.0 → 5.0.0

package/API.md

@@ -9,9 +9,10 @@ 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
+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
 
@@ -21,9 +22,10 @@ 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
+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>
@@ -52,6 +54,14 @@ 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>
@@ -67,14 +77,6 @@ option set is <code>durable</code>, <code>arguments</code>, <code>exclusive</cod
 <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
@@ -105,9 +107,10 @@ 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
+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>
 
@@ -119,9 +122,10 @@ 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
+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  
@@ -181,6 +185,37 @@ Ensure queue exists
 | 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
@@ -190,9 +225,21 @@ ServiceDiscovery - Service discovery and health checking
 <a name="ServiceDiscovery+isServiceAvailable"></a>
 
 ### serviceDiscovery.isServiceAvailable(serviceName) ⇒ <code>Promise.&lt;boolean&gt;</code>
-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.
 
 **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 |
 | --- | --- | --- |
@@ -211,30 +258,6 @@ option set is `durable`, `arguments`, `exclusive`, `autoDelete`.
 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>

package/CHANGELOG.md

@@ -4,6 +4,124 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [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)

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. |
@@ -51,14 +51,23 @@ 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 |
 
@@ -139,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": "4.0.0",
+  "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)"
@@ -26,8 +27,10 @@
     "@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"

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/queueManager.js

@@ -94,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,21 +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');
-const { assertLogger } = require('./options');
-
 class CookbookRouter {
   constructor(mqClient, registryClient, options = {}) {
     this.mqClient = mqClient;
@@ -51,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') {
@@ -62,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);
@@ -73,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

@@ -25,38 +25,67 @@ class ServiceDiscovery {
   }
 
   /**
-   * 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 {
-      // 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.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';
   }
 
   /**