@onlineapps/mq-client-core 3.2.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,304 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [4.0.0] — 2026-09-16
+
+### Changed — značku odmítnutí nese i deklarační rail, jednou funkcí pro obě cesty (d.582)
+
+d.577 dala verdikt cestě `consume()`. `assertQueue()` — veřejný rail, kterým jde
+**každá** deklarace a po kterém jde FÁZE 0.8 `@onlineapps/service-wrapper`, když
+si služba zakládá vlastní business fronty — dál propouštěl syrovou chybu
+z amqplib. Odmítnutá deklarace tak odcházela s `code` = **číslo** `406`
+a bez jakékoli klasifikace: `@onlineapps/conn-orch-registry` přenáší, co
+rozhodlo jádro (d.579), a neměl co přenést; wrapper, který končí fázi natrvalo na
+`code: 'MQ_CONNECTION_FATAL'`, označil odmítnutí za přechodné.
+
+Teď obě cesty odpovídají **jednou funkcí** `_asRefusal(kind, queue, err)`: `kind`
+volí větu a třídu obalu, verdikt se píše jednou a v pravopisu, který už používá
+`_failFatally()`. Odmítnutá deklarace vychází jako chyba s
+`code: 'MQ_CONNECTION_FATAL'`, `reason: 'broker-refused'`, jménem fronty v `queue`
+a původní chybou brokeru — včetně reply kódu — v `cause`. Dvě kopie jedné
+klasifikace by se mohly rozejít (`change-discipline.md` § One rail per concern).
+
+`_failFatally()` se ani tady nevolá: odmítnuta je fronta, ne spojení — klient
+zůstává připojený a `isConnectionFatal()` je dál `false`.
+
+Kdo z toho co má: po re-pinu na tuto verzi doručí `ensureQueues()`
+v `@onlineapps/conn-orch-registry` (d.579) značku wrapperu, takže 406 z FÁZE 0.8
+skončí boot natrvalo místo aby ho opakoval proti frontě, kterou služba nikdy
+nesmí založit.
+
+Chování, které se **nemění**: 404, „channel ended", 503 i odmítnutí volajícího
+(`Queue lifetime is not the caller's to set`) odcházejí přesně tak, jak přišly;
+přijatá deklarace dál vrací `queue.declare-ok` brokeru. Kontrolní noha d.295
+v `connect-refusal-fails-fast.integration.test.js` čte reply kód nově o jedno
+`cause` níž — její vlastní tvrzení (spojení nebylo v sázce, klient se nestaví
+mimo provoz) platí beze změny.
+
+### Changed — odmítnutí fronty brokerem nese stejný verdikt jako odmítnutí spojení (d.577)
+
+Fronta, která na brokeru existuje s jinými argumenty, než jaké `queueConfig`
+deklaruje, odpoví na `assertQueue()` kódem **406 PRECONDITION-FAILED**.
+`_prepareQueueForConsume()` z toho stavěl `ConsumeError` **bez `code` a bez
+`reason`** — kód brokeru přežil jen v `cause` (a o jedno obalení výš, v
+`@onlineapps/conn-orch-registry`, až v `cause.cause`). `REFUSAL_REPLY_CODES` a
+`_isBrokerRefusal()` se přitom ptaly jen v connect/reconnect.
+
+Co to stálo: `@onlineapps/service-wrapper` ukončí FÁZI 0.7 trvale jen na
+`code: 'MQ_CONNECTION_FATAL'`, takže 406 na frontě byl klasifikován jako
+PŘECHODNÝ a služba opakovala boot proti frontě, kterou nikdy nesmí založit —
+každý pokus dostane stejnou odpověď (změřeno sondou W532 proti živému brokeru).
+
+Teď je to **jeden slovník pro jeden fakt**: každá chyba z cesty
+`consume()` — klasifikace fronty, deklarace i registrace konzumenta — kterou
+broker odmítl kódem z `REFUSAL_REPLY_CODES` (403/530/406), vychází jako
+`ConsumeError` s `code: 'MQ_CONNECTION_FATAL'`, `reason: 'broker-refused'` a
+původní chybou brokeru v `cause`. Klasifikuje se **kódem odpovědi**, ne zněním
+hlášky (`_isBrokerRefusal()`, jediná kolej). Verdikt píše jedno místo — `catch`
+v `consume()` transportu — a `BaseClient.consume()` takovou chybu přeposílá
+**beze změny**: obalení by před přesnou větu brokeru postavilo obecnější a
+značku zanořilo o jedno `cause` hlouběji.
+
+Co se záměrně **nemění**: `_failFatally()` se tu nevolá. Odmítnuta je fronta, ne
+spojení — klient zůstává připojený, publikační cesta nad týmž spojením nemá co
+odpovídat a líné zotavení se nezastavuje. Chyba, kterou broker neodmítl, odchází
+přesně tak, jak přišla: 404 dál nese `CONSUMER_QUEUE_MISSING`, chybějící
+dead-letter route dál `CONSUMER_DEAD_LETTER_ROUTE_MISSING`, 503 a „channel
+ended" dál žádnou značku.
+
+### Documentation — kadence heartbeatu se tady nedeklaruje (d.574)
+
+Dva komentáře v `src/config/queueConfig.js` psaly kadenci heartbeatu číslem
+(„every 10s"). Balíček ji nevlastní: je to povinná volba konstruktoru
+`RegistryClient` (`@onlineapps/conn-orch-registry`, `heartbeatInterval`), kterou
+`@onlineapps/service-wrapper` plní z `BIZ_HEARTBEAT_INTERVAL_MS`. Ručně psané
+číslo v komentáři je popisný fakt bez mechanismu, který ho drží pravdivý
+(`.claude/rules/doc-code-binding.md` §1), takže obě věty teď ukazují na
+vlastníka a číslo nenesou. Chování ani API se nemění.
+
+### Changed — odmítnutí brokerem na cestě bootu nese verdikt (d.295)
+
+`connect()` přeposílal syrovou chybu z amqplib bez jakéhokoli verdiktu, takže
+volající nad ním nemohl poznat, jestli broker **odpověděl a odmítl** (403
+ACCESS-REFUSED, 530 NOT-ALLOWED, 406 PRECONDITION-FAILED), nebo jestli **nikdo
+neodpověděl** (ECONNREFUSED, timeout). `_isBrokerRefusal()` ten rozdíl umí od
+d.339, ale četla ho jediná cesta — `_reconnectWithBackoff()`, tedy spojení
+ztracené za běhu. Teď ho čte i první `connect()`: odmítnutí z něj vychází jako
+chyba s `code: 'MQ_CONNECTION_FATAL'`, `reason: 'broker-refused'`, původní chybou
+v `cause` a hláškou §5, která jmenuje credentials, vhost a topologii jako fix.
+`isConnectionFatal()` je od té chvíle `true`, takže se proti odmítajícímu brokeru
+už nerozbíhá líné zotavení.
+
+Verdikt se na této cestě **neohlašuje** na `connection:fatal` ani přes `onFatal`:
+volající na `connect()` čeká, takže se ho dozví výjimkou, a druhé oznámení téže
+události je přesně ta škoda, kterou popisuje `_reportRecoveryFailure()`. Výsledek
+bootu patří volajícímu bootu (`@onlineapps/service-wrapper`, poznámka `BOOT
+budget` v `_initializeMQ()`), ne kanálu pro asynchronní ztrátu.
+
+`BaseClient.connect()` verdikt propouští beze změny. Dosud ho obalil do obecné
+`ConnectionError` s fixem „read error.cause" — přesná odpověď degradovaná na
+vágní, a značka, na kterou volající přestává opakovat, se ztratila úplně
+(`ConnectionError` bere `code` jako argument konstruktoru a to volání žádný
+nepředávalo).
+
+Co se **nemění**: `REFUSAL_REPLY_CODES` zůstávají `[403, 530, 406]` — 503
+COMMAND-INVALID se nepřidává, žádné měření si to nevyžádalo. Neodpovídající
+broker odchází z `connect()` přesně jako dřív, syrový a opakovatelný, protože
+„vzdát to navždy" nad výpadkem zakazuje konfirmace
+`mq-client-lifecycle-contract` 001 bod 3. A 406 z `assertQueue()` nad živým
+spojením zůstává chybou fronty, ne ztrátou spojení.
+
+### Changed — `publish()` cituje příčinu, nehádá ji (d.514)
+
+`BaseClient.publish()` přepisoval všechno, co transport vyhodí, na jednu větu:
+*„Failed to publish to queue "<q>" - Expected: the queue to exist and the channel
+to be open. Fix: read error.cause for the broker reason."* Dvě ze tří jejích
+klauzulí byly dohad. Transport odmítá publikaci i z důvodů, které s chybějící
+frontou ani se zavřeným kanálem nemají nic společného — pravidlo vlastnictví
+(`QueueNotFoundError`, `kind: 'unowned'`, d.419), vyčerpaný rozpočet opakování,
+odmítnutí brokerem — a u každého z nich hláška posílala čtenáře prověřit frontu,
+která existuje, a kanál, který je otevřený. Pravá věta ležela v `error.cause`,
+kam se řádek logu nedívá.
+
+Je to táž vada, kterou d.297 odstranila o volání vedle (`_consumerRefusal()`),
+a odpovídá se stejně: vrstva **nejmenuje nejpravděpodobnější příčinu, cituje tu,
+kterou skutečně chytila**. Nový tvar hlášky §5 je
+`[BaseClient] Failed to publish to queue "<q>": <věta transportu> - Expected:
+publish() to hand the message to the broker. Fix: act on the reason above …
+error.cause carries the original error, error.queue names the target queue.`
+
+Co se **nemění**: třída (`PublishError`), `error.queue`, `error.cause` ani objekt
+v něm — volající, který se rozhoduje podle třídy, čte dál objekt. Nemění se ani
+`ConnectionError` z nepřipojeného klienta a `SerializationError` z nepřevoditelné
+zprávy; obě mají vlastní, pravdivou větu už teď. Odmítnutí, které vyhodí hodnotu
+bez `message` (neErrorová rejekce), se do hlášky přenáší celé (`String(thrown)`),
+protože „undefined" uprostřed odmítnutí je horší odpověď než řetězec, kterým
+někdo odmítl.
+
+### Removed (BREAKING) — `recoveryScope`: klíč, který po d.419 nic nečetlo (d.514)
+
+`recoveryScope` byl poslední zbytek dveří, kterými klient zakládal frontu bez
+vlastníka. d.419 odebrala `queueCreationFilter` i `queueCreationCallback`
+a `RecoveryWorker.createQueue()`; hodnota `recoveryScope` ale dál putovala ze
+schématu přes `rabbitmqClient.js` do `RecoveryWorker`, kde se přiřadila do pole
+`this._scope`, **které nečetlo nic v celém balíčku** (měřeno 2026-09-15:
+`grep -rn "_scope" src/` → jediný výskyt je přiřazení a jedna zmínka v komentáři).
+Deklarace, kterou nikdo nečte, tvrdí čtenáři, že na ní něco závisí.
+
+Odchází celý řetěz: `configSchema.recoveryScope`, `defaultConfig.recoveryScope`,
+argument `scope` konstruktoru `RecoveryWorker` i pole `this._scope`. Schéma je
+ZAVŘENÉ, takže konfigurace, která klíč pořád nese, je odmítnuta **jménem** při
+konstrukci — ne tiše ignorována.
+
+**Čtyři otázky** (`.claude/rules/change-discipline.md` § Removing something
+removes its declaration): **(1) proč vznikl** — `scope` říkal, jestli tenhle
+klient smí zakládat fronty; v `business` scope je zakládal, v `infrastructure`
+ne. Byla to volba provozovatele nad ad-hoc jmény z doby, kdy neexistovala
+centrální šablona, ze které by se dala fronta deklarovat. **(2) která část
+koncepce ho nesla** — hlavička `RecoveryWorker`, § Queue Creation: *„ostatní
+jména … smí založit, pokud to scope a `queueCreationFilter` dovolují"*. Ta část
+**neplatí**: nahradila ji konfirmace `mq-consumer-contract` 006 — *„queues come
+into being only from declarations"* — a d.419 podle ní zavřela obě zbylé dveře.
+**(3) proč ho dnes nikdo nečte** — ustoupil rozhodnutí: s dveřmi zmizel jediný
+čtenář a klíč zůstal ležet. Vacuózní byl ale už předtím, a je to zapsané v kódu,
+který se teď maže: `ConnectorMQClient` nastavoval `'business'` **každé** biz
+službě, takže „smí zakládat" platilo plošně a nerozhodovalo nic. **(4) je náhrada
+koncepčnější** — ano. O tvaru hlášení rozhoduje třída vlastnictví, kterou
+odpověděla centrální deklarace (`error.kind` z `QueueNotFoundError`: `infrastructure`
+/ `business` / `unowned`). Ta plyne z `queueConfig`, ne z toho, kdo klienta
+postavil, takže dva klienti namířené na tutéž frontu nemohou dostat různou
+odpověď — a odpověď se nemůže rozejít s deklarací, protože je z ní odvozená.
+
+**Pro volajícího:** `@onlineapps/conn-infra-mq` klíč jak je publikován pořád
+posílá (`ConnectorMQClient.js`, `recoveryScope: config.recoveryScope || 'business'`;
+pinuje `@onlineapps/mq-client-core` 2.0.1, kde klíč ještě existuje). Až se pin
+pohne, bude odmítnut jménem při konstrukci. Úprava konektoru patří do dávky, která
+pin posouvá, ne do téhle — stejně jako u `queueCreationCallback` v d.419.
+
+### Removed — výjimka pro `rpc.reply.*` v `consume()`, nedosažitelná od d.259 (d.514)
+
+`_prepareQueueForConsume()` měla třetí třídu jména: co začínalo `rpc.reply.`,
+přeskočilo klasifikaci, rozlišení argumentů z centrální konfigurace i otázku na
+brokera (`checkQueue`/`assertQueue`). Mezi ty dvě výjimky ale d.259 postavila
+bránu nedoručitelných zpráv, a ta takové jméno **odmítne dřív**: `queueConfig`
+ho neklasifikuje jako infrastrukturní ani business (měřeno:
+`isInfrastructureQueue('rpc.reply.abc123') === false`, `isBusinessQueue` totéž),
+takže pro něj nedeklaruje žádnou cestu, a `getDeadLetterRoute()` vrací `null`
+při `isDeadLetterTarget() === false`. Druhá polovina výjimky tak byla mrtvý kód
+a první nerozhodovala nic (obě klasifikace jsou pro to jméno `false` i bez ní).
+
+**Čtyři otázky**: **(1) proč vznikla** — RPC odpovědní cesta: volající si sám
+založil dočasnou, nedurabilní frontu s vlastní životností a konzumoval z ní, takže
+`consume()` nad ní nesměl nic deklarovat. **(2) která část koncepce ji nesla** —
+právě ta cesta. **Neplatí**: `createTemporaryQueue()` byla zrušena
+(`conn-infra-mq` d.275b) a konfirmace `mq-consumer-contract` 003 bod 3 to říká
+větou — *„`rpc.reply.*` is not a topology question — `createTemporaryQueue()` has
+no caller, it is a removal question"*. **(3) proč ji dnes nic nečte** — ustoupila
+rozhodnutí d.259: konzument bez cesty pro nedoručitelnou zprávu se nepřipojí,
+a fronta bez deklarace žádnou cestu nemá. **(4) je náhrada koncepčnější** — ano,
+je to jedna kolej: fronta je konzumovatelná právě tehdy, když centrální deklarace
+říká, kam s odmítnutou zprávou. Neexistuje druhá třída jmen, která klasifikaci
+a deklaraci přeskočí na slovo volajícího. Výjimka slibovala podporu, kterou d.259
+odebrala, takže kód teď říká, co systém dělá.
+
+Chování se **nemění** a je změřené proti živému brokeru: `rpc.reply.*` fronta,
+která na brokeru **skutečně je** (nedurabilní, jak ji zakládala zrušená cesta), je
+odmítnuta touž větou jako každé jiné jméno bez deklarované cesty, nic se k ní
+nepřipojí a nic se nepředeklaruje
+(`tests/integration/dead-letter-route-required.integration.test.js`).
+
+### Changed — `amqplib` přišpendlen přesně na `0.10.9` (d.514)
+
+`^0.10.3` je plovoucí rozsah, a tenhle balíček na konkrétním chování amqplib
+**staví změřená tvrzení**: „ani `Connection`, ani `Channel` nenese vlastnost
+`closed`" (d.260, amqplib 0.10.9, živý broker, 2026-09-12) je předpoklad
+`isConnected()`, `getChannelState()`, všech tří `_ensure*Channel()`
+a `_performHealthCheck()`. S plovoucím rozsahem může tentýž commit nainstalovat
+jiný kód jiný den — přesně to, čemu pravidlo o pinech brání u `@onlineapps/*`
+(`architecture-principles.md` § Version pinning: „a floating range makes the same
+commit install different code on different days"). Hodnota `0.10.9` není nová,
+je to co bylo v `package-lock.json` nainstalováno (měřeno:
+`require('amqplib/package.json').version` → `0.10.9`); mění se jen to, že ji
+`package.json` říká nahlas. `amqplib` není v SSOT `api/config/libraries.json`
+(měřeno: grep bez shody), takže tenhle pin nevlastní publikační vlna.
+
+### Changed (testy) — sady `liveness-health-publish*` říkají, proč mají zotavení vypnuté (d.514)
+
+Obě běží s `reconnectEnabled: false`. Důvod je pravdivý a teď je napsaný: co v nich
+umírá, je KANÁL, a obnova spojení má vlastní sady (`reconnect-cycles-lazy-retry`,
+`reconnect-exhaustion`, `disconnect-ends-reconnect`). Napsané je i to, co ten
+příznak nese: **nenese nic** — měřeno 2026-09-15, obě sady jsou zelené i s
+`reconnectEnabled: true` (integrace 4/4 třikrát po sobě, unit 11/11) — a právě
+proto neviděly d.467, kde `performHealthCheck()` spouštěl obnovovací cyklus
+bezpodmínečně. Případ s obnovou se do nich **nedoplňuje**: ta otázka má vlastní
+kolej se zapnutou obnovou (`health-check-does-not-recover-a-live-client`, unit
+i integrace), a druhá akceptační sada nad jedním pojmem je duplicita, kterou
+`change-discipline.md` § One rail per concern označuje za vadu.
+
+### Fixed — pracující konzument s prefetchem 1 už není poplach (d.550)
+
+Změřeno na BIZ-pdfgen a BIZ-converteru, dvakrát při každém bootu:
+
+    ⚠️ Prefetch utilization high: queue 'biz-pdfgen.registry' has 1/1 messages
+       in-flight (100%, threshold: 80%)
+
+Registrační fronta má prefetch 1, takže jedna zpráva v letu je 100 % okna — a
+zároveň naprosto normální stav konzumenta, který právě dělá tu jedinou práci,
+kterou smí. Poplach se proto spustil při KAŽDÉM doručení do takové fronty a
+žádný práh na tom nic nemění: `1/1 >= 0.8` platí stejně jako `1/1 >= 0.99`.
+Varování, které nemůže nenastat, neříká nic — jen učí čtenáře přehlížet řádek,
+na kterém jednou bude stát skutečné zahlcení.
+
+`_checkPrefetchUtilization()` nově okno jedné zprávy neměří: jeho jediné dva
+stavy jsou 0 % (nečinný) a 100 % (pracuje) a ani jeden není zjištění, kvůli
+kterému by měl kdo zasáhnout. Pro okno větší než jedna zpráva se nemění nic —
+`prefetchUtilizationThreshold` zůstává, jak ho deklaruje
+`src/config/defaultConfig.js`, žádný nový práh ani default nevzniká, a plné okno
+dvou i deseti zpráv se hlásí dál se stejným textem (kontrolní případy v obou
+tierech: `tests/unit/prefetch-of-one-is-not-a-warning.test.js`,
+`tests/integration/prefetch-of-one-is-not-a-warning.integration.test.js`).
+
+### Changed (testy) — kontrolní případ redakce jmenuje allow-list, ne jeho polovinu (d.514)
+
+`tests/unit/redact-credentials.test.js` měl kontrolní případ nadepsaný *„URL bez
+pověření se vrací nezměněná“*. Tvrzení zní jako obecné pravidlo, které od
+`@onlineapps/logger-contract` 2.0.0 (d.476) neplatí: redakce je ALLOW-LIST —
+zachová protokol, host, port a cestu, a všechno ostatní odejde bez ohledu na to,
+jestli v tom pověření je. URL bez pověření, ale s dotazem (`?heartbeat=60`) se
+nezměněná nevrací. Kontrolní případ, který jmenuje polovinu pravidla, zůstává
+zelený i nad implementací, která dotaz propouští — tedy přesně nad vadou, kvůli
+které allow-list vznikl.
+
+Hodnota v assertu se **nemění** (`amqp://api_services_queuer:5672/oa_vhost` se
+vrací identické); mění se věta, kterou test tvrdí, a důvod je u ní zapsaný.
+Sousední případ, který zahození dotazu měří, zůstává jedinou kolejí pro to
+tvrzení — nový se nepřidává. Žádná změna produkčního kódu.
+
+### Documentation — terminální frontu zakládá vlastník prefixu, který ji jmenuje (d.568)
+
+Deklarace není pokyn k založení. Zápis sekce v `queueConfig` říká, **jak** fronta
+vypadá; **kdo** ji na brokeru založí, rozhoduje `options.queues` toho, kdo volá
+`initInfrastructureQueues()`. Odvození celého seznamu z prefixů je jen VÝCHOZÍ větev
+té funkce (`shared/infrastructure-tools/src/orchestration/initInfrastructureQueues.js`)
+a žádný dnešní volající jí nenechá rozhodnout: gateway jmenuje přesně pět front
+`workflow.*`, které vlastní (`infra/api_gateway/index.js`). `monitoring.dlq`
+a `telemetry.dlq` tedy patří do volání monitoringu, ne gateway.
+
+INFRA-monitoring to změřilo 2026-09-16 na dev brokeru: 78 front, `.dlq` mezi nimi jen
+`workflow.dlq` a `delivery.dlq`. Sedm front rodin `monitoring.*` a `telemetry.*` nese od
+d.475 `x-dead-letter-routing-key: '<prefix>.dlq'`, takže `nack(requeue=false)` nad nimi
+směřuje na routing key, pod kterým žádná fronta není — a broker zprávu zahodí.
+Terminál založí vlastník prefixu u sebe (INFRA-monitoring, W9c).
+
+Opraveny věty v živém textu: JSDoc `monitoring.dlq` a `telemetry.dlq`
+(`src/config/queueConfig.js`), úroveň § terminální fronty v `README.md` a hlavička
+testu `tests/unit/dead-letter-topology.test.js`, která tvrdila, že zápis sekce JE pokyn
+k založení. Dobový záznam v `[3.2.0]` se nemění. Deklarace sama je v pořádku a nově to
+měří test: `declarationOptions('monitoring.dlq')` a `('telemetry.dlq')` vrací přesně
+`{ durable: true, arguments: { 'x-max-length': 50000 } }` — žádné TTL, žádná další
+cesta — s kontrolním případem `workflow.dlq` (totéž) a `monitoring.audit` (routovaná
+fronta též rodiny si TTL, strop i cestu drží). Žádná změna produkčního kódu.
+
 ## [3.2.0] — 2026-09-15
 
 ### Added — dead-letter cesty pro rodiny `monitoring.*` a `telemetry.*` (d.475)

package/README.md

@@ -195,7 +195,12 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   connection (see § Connection loss)
 
 `publish()` and the workflow helpers built on it resolve to `undefined`; failure is
-signalled by a thrown `PublishError`, never by a falsy return.
+signalled by a thrown `PublishError`, never by a falsy return. That `PublishError`
+**quotes the reason it caught** — `[BaseClient] Failed to publish to queue "<q>":
+<the transport's own sentence> - Expected: … Fix: …` — and keeps the object it came
+from in `error.cause`, so a caller deciding on the class still reads the object
+while a log line already carries the reason. The layer names no likeliest cause of
+its own; the same rule `consume()` follows (§ `errors` and `errorCodes`).
 
 ### `consume()` — the delivery contract
 
@@ -235,6 +240,17 @@ policy exists to end) and it is never silent: the client logs it at error level,
 the queue, the attempts and the error, and the `message_dlq` event is published as for any
 other rejection.
 
+**A terminal queue is declared here and CREATED by the owner of the prefix that names
+it.** A section entry says what the queue looks like, never who brings it into being:
+`initInfrastructureQueues()` derives the full list from the sections only when its caller
+passes no `queues` list, and every caller passes one — the gateway's names the five
+`workflow.*` queues it owns and nothing else (`infra/api_gateway/index.js`). So
+`monitoring.dlq` and `telemetry.dlq` belong to the monitoring service's own call. Until a
+terminal exists on the broker, the drop above happens one step earlier and without the
+`x-death` trail: the rejection is routed to a name no queue carries (measured 2026-09-16
+on the dev broker — 78 queues, `.dlq` among them only `workflow.dlq` and
+`delivery.dlq`).
+
 ```javascript
 await client.consume(queue, async (msg, delivery) => {
   // delivery = { attempt, maxAttempts, isFinalAttempt }
@@ -459,9 +475,12 @@ arguments no longer match. The rule is enforced in two places, and both are
 required: the 404 branch of `_publishOnce()` refuses the publish, and
 `RecoveryWorker.handleQueueNotFound()` refuses to create the queue behind it.
 
-`recoveryScope: 'business'` (the default every `ConnectorMQClient` sets) says the
-client belongs to a business service. It has never meant "may create business
-queues".
+Which of the three sentences the refusal carries is decided by the ownership class
+in the error (`kind`), which the central declaration answers — never by how the
+client was constructed. `recoveryScope` used to say which kind of service a client
+belonged to; it never meant "may create business queues", and once d.419 closed the
+door it had guarded, nothing read it. The key is retired (d.514) and a config still
+carrying it is refused by name at construction.
 
 **An exchange is named by a publisher, never declared by one.** `publish(queue,
 message, { exchange, routingKey })` sends to the exchange the caller names and
@@ -521,12 +540,28 @@ for `'Connection closed unexpectedly'` while the transport emitted `'RabbitMQ co
 closed unexpectedly'`, one capital letter apart, so the branch written to ignore that
 error had never once run (fixed 2026-09-08, `errors.ConnectionError` now carries `code`).
 
-`consume()` refuses for two named reasons, and they ask for OPPOSITE actions:
+`consume()` refuses for three named reasons, and they ask for OPPOSITE actions:
 
 | `error.code` | what happened | what fixes it |
 |---|---|---|
 | `CONSUMER_QUEUE_MISSING` | the queue does not exist | start the service that owns the queue — a consumer never creates one |
 | `CONSUMER_DEAD_LETTER_ROUTE_MISSING` | the queue exists, `queueConfig` declares no dead-letter route for it | declare `x-dead-letter-exchange`/`-routing-key` for that queue and bind the destination; the queue itself is fine |
+| `MQ_CONNECTION_FATAL` (with `reason: 'broker-refused'`) | the BROKER refused this queue — 406 PRECONDITION-FAILED for a queue that exists with other arguments, 403/530 for one this account may not use | correct the topology or the permission the broker named in `error.cause`, then restart; retrying gets the same answer |
+
+The third one is the SAME verdict a refused connection carries (§ *permanently lost*),
+because it asks the lifecycle owner for the same thing: stop retrying. It refuses the
+QUEUE, not the connection — the client stays connected and `isConnectionFatal()` stays
+`false`. `@onlineapps/service-wrapper` reads `code` to end FÁZE 0.7 permanently; before
+2026-09-16 a 406 on a queue carried no code at all, so the service kept booting against a
+queue it will never be allowed to declare.
+
+**`assertQueue()` answers the same way**, and for the same reason: a service declaring
+its own business queues meets the refusal there, not on the consume path. A declaration
+the broker refuses (403/530/406) leaves that rail as an error carrying
+`code: 'MQ_CONNECTION_FATAL'`, `reason: 'broker-refused'`, the queue name in `queue` and
+the broker's own error — reply code included — in `cause`. One function states both
+(`_asRefusal(kind, queue, err)`): two copies of one classification would be free to
+drift. Anything the broker did not refuse leaves either rail exactly as it arrived.
 
 Any other failure carries **no** code and its `ConsumeError` says so: the reason is in
 `error.cause`, and this layer does not name the likeliest-sounding one. Until 2026-09-14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "3.2.0",
+  "version": "4.0.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"
@@ -26,7 +26,7 @@
     "@onlineapps/logger-contract": "2.0.0",
     "@onlineapps/runtime-config": "1.2.0",
     "ajv": "^8.12.0",
-    "amqplib": "^0.10.3"
+    "amqplib": "0.10.9"
   },
   "devDependencies": {
     "jest": "^29.7.0"

package/src/BaseClient.js

@@ -196,6 +196,24 @@ function invalidConfigurationMessage(unknownKeys, declaredKeys) {
  * @throws {ValidationError} If the argument is not a plain object of properties, or
  *   redeclares a key the library already owns.
  */
+/**
+ * What was thrown, rendered for a sentence a human reads in a log line.
+ *
+ * Neither branch invents anything: an `Error` is quoted by its own `message`,
+ * and a value that is not an `Error` is quoted whole, because "undefined" in the
+ * middle of a refusal is a worse answer than the string somebody rejected with.
+ * The object itself always stays reachable as `error.cause`.
+ *
+ * @param {*} thrown - Whatever the transport rejected with.
+ * @returns {string}
+ */
+function describeThrown(thrown) {
+  if (thrown instanceof Error && typeof thrown.message === 'string' && thrown.message !== '') {
+    return thrown.message;
+  }
+  return String(thrown);
+}
+
 function schemaWithSubclassProperties(extraProperties) {
   if (extraProperties === null || extraProperties === undefined) {
     return configSchema;
@@ -395,6 +413,18 @@ class BaseClient {
       this._logger.info('[BaseClient] Transport connected successfully');
       this._connected = true;
     } catch (err) {
+      // A refusal is already answered, so it passes through untouched. The
+      // transport reached the verdict (`code: 'MQ_CONNECTION_FATAL'`,
+      // `reason: 'broker-refused'`) and wrote the sentence that names
+      // credentials, vhost and topology as the fix; wrapping it here would
+      // replace that with "read error.cause" — a precise answer demoted to a
+      // vague one, and the marker the caller stops retrying on lost with it
+      // (`ConnectionError` takes its code as a constructor argument and this
+      // call passed none, so the wrap erased it). d.295.
+      if (err && err.code === 'MQ_CONNECTION_FATAL') {
+        throw err;
+      }
+
       throw new ConnectionError(
         '[BaseClient] Failed to connect to broker - Expected: a reachable broker at the configured host. '
           + 'Fix: read error.cause for the transport reason, then check the MQ url, credentials and network the service was started with.',
@@ -476,9 +506,23 @@ class BaseClient {
     try {
       await this._transport.publish(queue, buffer, options);
     } catch (err) {
+      // The reason is QUOTED, never guessed. Until d.514 this sentence read
+      // "Expected: the queue to exist and the channel to be open", and two of its
+      // three clauses were a guess: the transport refuses a publish for reasons
+      // that have nothing to do with a missing queue or a closed channel — the
+      // ownership rule (`QueueNotFoundError`, `kind: 'unowned'`, d.419), a spent
+      // retry budget, a broker refusal — and for each of those the reader was sent
+      // to check a queue that exists and a channel that is open. The true sentence
+      // sat in `error.cause`, where a log line does not look. Same defect, same
+      // answer as d.297 one call over (`_consumerRefusal()`): name no likeliest
+      // cause, carry the one actually caught. `cause` is unchanged, so a caller
+      // deciding on the class still reads the object.
       throw new PublishError(
-        `[BaseClient] Failed to publish to queue "${queue}" - Expected: the queue to exist and the channel to be open. `
-          + 'Fix: read error.cause for the broker reason; error.queue names the target queue.',
+        `[BaseClient] Failed to publish to queue "${queue}": ${describeThrown(err)} - `
+          + 'Expected: publish() to hand the message to the broker. '
+          + 'Fix: act on the reason above — this layer does not know which failure it was, and naming the '
+          + 'likeliest would send you to fix something that may not be broken. error.cause carries the '
+          + 'original error, error.queue names the target queue.',
         queue,
         err
       );
@@ -623,6 +667,18 @@ class BaseClient {
   _consumerRefusal(queue, err) {
     const code = err && err.code;
 
+    // The broker ANSWERED and refused this queue (403/530/406). Rethrown
+    // UNCHANGED, for the reason `@onlineapps/service-wrapper`'s `MQConnector`
+    // gives one layer up: that message carries the broker's own words and names
+    // the permission or the topology as the fix, and the verdict it carries
+    // (`code: 'MQ_CONNECTION_FATAL'`, `reason: 'broker-refused'`) is what the
+    // lifecycle owner reads to stop retrying a decision. Re-wrapping it here
+    // would put a sentence that knows less in front of one that knows more, and
+    // bury the marker one `cause` deeper (d.577).
+    if (code === 'MQ_CONNECTION_FATAL') {
+      return err;
+    }
+
     if (code === CONSUMER_DEAD_LETTER_ROUTE_MISSING) {
       return new ConsumeError(
         `[BaseClient] Cannot consume from queue "${queue}": queueConfig declares no dead-letter route for it - `

package/src/config/configSchema.js

@@ -387,22 +387,15 @@ module.exports = {
     },
 
     // ---------------------------------------------------------------------
-    // Which kind of service this client belongs to. `queueCreationFilter` and
-    // `queueCreationCallback` stood here until d.419: they were the two keys by
-    // which a client declared a queue nobody owns, and a queue now comes into
-    // being from a declaration or not at all
+    // `queueCreationFilter` and `queueCreationCallback` stood here until d.419,
+    // and `recoveryScope` — the permission they were filtered by — until d.514.
+    // They were how a client declared a queue nobody owns, and a queue now comes
+    // into being from a declaration or not at all
     // (`docs/governance/confirmations/mq-consumer-contract.md` 006). A config
-    // still carrying either is refused by name at construction — the schema is
-    // CLOSED, which is what makes the removal visible to the caller instead of
-    // silently ignored.
+    // still carrying any of the three is refused by name at construction — the
+    // schema is CLOSED, which is what makes the removal visible to the caller
+    // instead of silently ignored.
     // ---------------------------------------------------------------------
-    recoveryScope: {
-      type: 'string',
-      enum: ['infrastructure', 'business'],
-      description:
-        'Which kind of service this client belongs to. It decides nothing about queue '
-        + 'creation: no client declares a queue (workers/RecoveryWorker.js).',
-    },
   },
   required: ['type', 'host'], // Only type and host required
 

package/src/config/defaultConfig.js

@@ -186,11 +186,7 @@ module.exports = {
   criticalHealthShutdown: true,
   criticalHealthShutdownDelay: 60000,
 
-  // ---------------------------------------------------------------------
-  // Which kind of service this client belongs to. It decides nothing about queue
-  // creation: this client declares no queue at all, and the two callbacks that
-  // used to let it — `queueCreationFilter` and `queueCreationCallback` — left
-  // with that door (d.419, conf mq-consumer-contract 006).
-  // ---------------------------------------------------------------------
-  recoveryScope: 'infrastructure',
+  // `recoveryScope` stood here until d.514, with the two callbacks it filtered
+  // (`queueCreationFilter`, `queueCreationCallback`, d.419) one batch ahead of
+  // it. This client declares no queue at all, so there is no permission to give.
 };

package/src/config/queueConfig.js

@@ -648,7 +648,10 @@ module.exports = {
      * InfrastructureHealthTracker publishes service status changes
      * Message format includes event_type: 'service.registered' | 'service.validation.completed' | 
      *   'service.version.changed' | 'service.deregistered' | 'service.status.changed'
-     * NOTE: Heartbeats are NOT published here (too frequent, every 10s)
+     * NOTE: Heartbeats are NOT published here - they are too frequent. The cadence
+     *   is not a number this file owns: see the `heartbeatInterval` constructor option
+     *   of RegistryClient (@onlineapps/conn-orch-registry), which ServiceWrapper feeds
+     *   from BIZ_HEARTBEAT_INTERVAL_MS.
      * NOTE: Healthcheck messages go to infrastructure.health.events exchange
      */
     'services': {
@@ -715,6 +718,17 @@ module.exports = {
      * onward route — because the operator's dashboard matches `*.dlq` and a message
      * that expired there is a message nobody got to decide about (confirmation
      * `mq-consumer-contract` 002 point 2, 003 point 1).
+     *
+     * **A declaration is not a creation instruction. The terminal is brought into being
+     * by the owner of the prefix that NAMES it.** `initInfrastructureQueues()` derives
+     * the whole list from these sections only when its caller passes no `queues` list;
+     * every caller passes one, and the gateway's names exactly the five `workflow.*`
+     * queues it owns (`infra/api_gateway/index.js`). `monitoring.dlq` therefore belongs
+     * to the monitoring service's own call, beside the queues it consumes. Until that
+     * call names it, a `nack(requeue=false)` on a queue of this family dead-letters onto
+     * a routing key no queue carries and the broker DROPS the message — measured
+     * 2026-09-16 on the dev broker: 78 queues, and the only `.dlq` among them
+     * `workflow.dlq` and `delivery.dlq`.
      */
     dlq: {
       durable: true,
@@ -784,6 +798,10 @@ module.exports = {
      * `workflow.dlq`, `delivery.dlq` and `monitoring.dlq` — durable, capped at 50k, no
      * TTL, no onward route. A telemetry record the intake cannot process is the one an
      * operator most needs to look at, and a TTL here would delete it before they did.
+     *
+     * Brought into being by the owner of the `telemetry.` prefix, the same rule as
+     * `monitoring.dlq` above: declared here, created by the service whose
+     * `initInfrastructureQueues()` call names it.
      */
     dlq: {
       durable: true,
@@ -891,7 +909,9 @@ module.exports = {
      * CRITICAL: This is the ONLY queue used for service-to-Registry communication.
      * Registry listener processes different message types based on msg.type:
      * - type: 'register'   - Service registration requests (full spec + operations)
-     * - type: 'heartbeat'  - Periodic health check messages (sent every 10s)
+     * - type: 'heartbeat'  - Periodic health check messages (cadence owned by the
+     *   `heartbeatInterval` constructor option of RegistryClient,
+     *   @onlineapps/conn-orch-registry - not declared here)
      * - type: 'deregister' - Voluntary shutdown notice
      * (The legacy 'apiDescription' / 'apiDescriptionRequest' types are no
      *  longer supported — see operations-registry-contract.md §2.)

package/src/transports/rabbitmqClient.js

@@ -415,10 +415,11 @@ class RabbitMQClient extends EventEmitter {
 
     // Recovery worker — connection recovery, and the report of a queue that does
     // not exist. It creates none: queue creation left it with the two callbacks
-    // that fed it (d.419).
+    // that fed it (d.419) and with `recoveryScope`, the permission they were
+    // filtered by (d.514). Which rule the report names is decided by the
+    // ownership class in the error, not by who built this client.
     this._recoveryWorker = new RecoveryWorker({
       client: this,
-      scope: this._config.recoveryScope,
       logger: this._logger,
     });
 
@@ -696,6 +697,142 @@ class RabbitMQClient extends EventEmitter {
     return REFUSAL_REPLY_CODES.some((code) => message.includes(`server: ${code} (`));
   }
 
+  /**
+   * State the broker's refusal of a QUEUE the same way `_failFatally()` states
+   * its refusal of a CONNECTION — as a marker on the error, read by the caller
+   * that must decide what to do about it.
+   *
+   * Measured defect (d.577, sonda W532 against the live broker): a queue that
+   * already exists with other arguments answers `assertQueue()` with `406
+   * PRECONDITION-FAILED`, and `_prepareQueueForConsume()` built a `ConsumeError`
+   * for it with no `code` and no `reason`. The reply code survived in `cause`
+   * alone — and one wrapping further up (`@onlineapps/conn-orch-registry`) in
+   * `cause.cause`, where nothing looks. `@onlineapps/service-wrapper` ends FÁZE
+   * 0.7 permanently only on `code: 'MQ_CONNECTION_FATAL'`, so a 406 on a queue
+   * was classified TRANSIENT and the service went on booting against a queue it
+   * will never be allowed to declare. Every attempt gets the same answer.
+   *
+   * ONE vocabulary for one fact, therefore: the marker is the one `_failFatally()`
+   * already writes for `broker-refused` (d.295/d.490), not a second spelling of
+   * it. A refusal of the topology and a refusal of the connection ask the reader
+   * for the same thing — stop retrying, fix what the broker named — and the
+   * lifecycle owner reads one marker, not a list of them.
+   *
+   * What it deliberately does NOT do is `_failFatally()`: that declares the
+   * CONNECTION permanently lost and stands the client down. The connection here
+   * is healthy; it is this queue the broker refuses, and the publish path over
+   * the same connection has nothing to answer for.
+   *
+   * The decision is taken on the REPLY CODE (`_isBrokerRefusal()`,
+   * `REFUSAL_REPLY_CODES`), never on the wording of a sentence somebody may
+   * reword — the defect d.164 measured. The broker's own error is kept as
+   * `cause`, so its reply code stays readable.
+   *
+   * BOTH rails that talk to the broker about a queue go through this one
+   * function (d.582). `consume()` was the first; `assertQueue()` is the other
+   * half of the same fact, and it is the one FÁZE 0.8 walks — a service that
+   * declares its business queues gets the 406 there, not on the consume path.
+   * Two copies of one classification would be free to drift
+   * (`change-discipline.md` § One rail per concern), so `kind` decides only the
+   * SENTENCE and the class of the wrapper; the verdict is written once.
+   *
+   * @param {'consume'|'declare'} kind - which rail is answering.
+   * @param {string} queue - the queue the broker was asked about.
+   * @param {Error} err - what that rail threw.
+   * @returns {Error} the same error carrying the verdict, a typed error carrying
+   *   it when the throw was the broker's raw one, or `err` untouched when the
+   *   broker refused nothing.
+   * @private
+   */
+  _asRefusal(kind, queue, err) {
+    const brokerError = this._brokerRefusalCause(err);
+
+    if (!brokerError) return err;
+
+    // Already stated, and in the shape this rail hands out: the verdict is
+    // written once, not once per layer that passes it on.
+    const alreadyStated = err.code === 'MQ_CONNECTION_FATAL'
+      && (kind !== 'consume' || err instanceof ConsumeError);
+    if (alreadyStated) return err;
+
+    // An error this rail built itself — the 406 sentence of
+    // `_prepareQueueForConsume()` — is marked in place: it names the fix more
+    // precisely than anything this function could write.
+    if (kind === 'consume' && err instanceof ConsumeError) {
+      return this._markBrokerRefusal(err);
+    }
+
+    const refusal = kind === 'consume'
+      ? new ConsumeError(
+        `[RabbitMQClient] Cannot consume from queue "${queue}": the broker REFUSED the operation, `
+          + `so retrying cannot change the answer (reason: ${brokerError.message}). `
+          + 'Expected: an account allowed to use this queue, and a queue whose declaration is the one '
+          + 'queueConfig prescribes. '
+          + 'Fix: correct the permission or the topology the broker named, then restart the process; '
+          + 'error.cause carries the broker reply code.',
+        queue,
+        brokerError
+      )
+      : new Error(
+        `[RabbitMQClient] Cannot declare queue "${queue}": the broker REFUSED the declaration, `
+          + `so retrying cannot change the answer (reason: ${brokerError.message}). `
+          + 'Expected: the queue to exist with the arguments queueConfig prescribes, and an account '
+          + 'allowed to declare it. '
+          + 'Fix: align the declaration the broker named (406 means the queue exists with other '
+          + 'arguments) or correct the permission, then restart the process; '
+          + 'error.cause carries the broker reply code.',
+        { cause: brokerError }
+      );
+
+    if (kind !== 'consume') refusal.queue = queue;
+    return this._markBrokerRefusal(refusal);
+  }
+
+  /**
+   * The broker error behind a failure, or `null` when the broker refused nothing.
+   *
+   * One `cause` deep, because that is how far the rails here wrap: the
+   * declaration step throws the broker's error, and the sentence built around it
+   * keeps it as `cause`. The decision is taken on the REPLY CODE
+   * (`_isBrokerRefusal()`, `REFUSAL_REPLY_CODES`), never on the wording of a
+   * sentence somebody may reword — the defect d.164 measured.
+   *
+   * @param {Error|null} err
+   * @returns {Error|null} the error carrying the broker's reply code
+   * @private
+   */
+  _brokerRefusalCause(err) {
+    if (!err) return null;
+
+    // An error already carrying the verdict is NOT the broker's own — the
+    // broker's is one `cause` below it. Asked of the marked error, the text half
+    // of `_isBrokerRefusal()` would answer yes about the wrapper, because the
+    // sentence built here quotes the broker's message verbatim (measured while
+    // writing d.582: `error.cause.code` came back `'MQ_CONNECTION_FATAL'`
+    // instead of `406`). The code is asked first, so the quote cannot be
+    // mistaken for the answer.
+    if (err.code === 'MQ_CONNECTION_FATAL') {
+      return this._isBrokerRefusal(err.cause) ? err.cause : null;
+    }
+
+    if (this._isBrokerRefusal(err)) return err;
+    if (this._isBrokerRefusal(err.cause)) return err.cause;
+    return null;
+  }
+
+  /**
+   * Write the verdict. ONE spelling, the one `_failFatally()` uses.
+   *
+   * @param {Error} error
+   * @returns {Error} the same error, marked
+   * @private
+   */
+  _markBrokerRefusal(error) {
+    error.code = 'MQ_CONNECTION_FATAL';
+    error.reason = 'broker-refused';
+    return error;
+  }
+
   /**
    * A recovery cycle is over and the client is NOT connected, but the broker
    * never refused it — so this is not the end.
@@ -823,12 +960,27 @@ class RabbitMQClient extends EventEmitter {
    * confused with an ordinary transient error: the `connection:fatal` event and
    * the injected `onFatal` callback.
    *
+   * WHO IS TOLD, and why that is not always the same. The `connection:fatal`
+   * event and the injected `onFatal` callback exist for a loss that happens
+   * asynchronously, with nobody awaiting anything — the owner would otherwise
+   * never hear of it. On the BOOT path a caller IS awaiting `connect()`, so it
+   * learns by the throw, and announcing as well would be a second notification
+   * of one event: the harm `_reportRecoveryFailure()` documents a few methods
+   * up, and a crossing of the line the boot caller draws itself (a boot failure
+   * is the boot's outcome, not a lifecycle event — see the `BOOT budget` note in
+   * `@onlineapps/service-wrapper`'s `_initializeMQ()`). Hence `announce`. The
+   * verdict, the state and the sentence are identical either way; only the
+   * channel differs (d.295).
+   *
    * @param {Error} lastError - The error from the final failed attempt.
    * @param {'broker-refused'|'cycles-spent'} reason - Which of the two it is.
+   * @param {Object} [options] - Reporting options.
+   * @param {boolean} [options.announce=true] - Emit `connection:fatal` and call
+   *   `onFatal`. False on a path whose caller is awaiting the throw.
    * @returns {Error} The fatal error, so callers can throw it.
    * @private
    */
-  _failFatally(lastError, reason) {
+  _failFatally(lastError, reason, { announce = true } = {}) {
     this._connectionFatal = true;
     this._reconnecting = false;
     this._lastConnectionError = lastError || null;
@@ -855,16 +1007,21 @@ class RabbitMQClient extends EventEmitter {
     fatal.cycles = this._reconnectCycles;
     fatal.cause = lastError;
 
+    // The log line is the RECORD and is unconditional; the two lines below are
+    // the NOTIFICATION, and only a caller that is not awaiting needs it.
     this._logger.error(`[RabbitMQClient] [mq-client-core] ${fatal.message}`);
-    this.emit('connection:fatal', fatal);
 
-    if (this._onFatal) {
-      try {
-        this._onFatal(fatal);
-      } catch (err) {
-        this._logger.error(
-          `[RabbitMQClient] [mq-client-core] onFatal handler threw: ${err.message}`
-        );
+    if (announce) {
+      this.emit('connection:fatal', fatal);
+
+      if (this._onFatal) {
+        try {
+          this._onFatal(fatal);
+        } catch (err) {
+          this._logger.error(
+            `[RabbitMQClient] [mq-client-core] onFatal handler threw: ${err.message}`
+          );
+        }
       }
     }
 
@@ -1327,6 +1484,25 @@ class RabbitMQClient extends EventEmitter {
         }
         this._connection = null;
       }
+
+      // The broker ANSWERED and refused — 403, 530, 406. The same verdict
+      // `_reconnectWithBackoff()` reaches at runtime, on the same rail
+      // (`_isBrokerRefusal`), because it is the same question: did anybody
+      // answer? Until d.295 this catch rethrew whatever amqplib raised, with no
+      // verdict on it, and the boot caller could only guess — `ServiceWrapper`
+      // guessed "transient" and spent its whole connection budget, backoff and
+      // all, on an answer no further attempt can change
+      // (`architecture-principles.md` §4).
+      //
+      // Anything unrecognised still leaves here as it arrived, and that is the
+      // owner's decision, not an omission: giving up forever on a broker that
+      // never answered is forbidden
+      // (`docs/governance/confirmations/mq-client-lifecycle-contract.md` 001
+      // point 3), so only an ANSWERED refusal ends the attempts.
+      if (this._isBrokerRefusal(err)) {
+        throw this._failFatally(err, 'broker-refused', { announce: false });
+      }
+
       throw err;
     } finally {
       if (connectTimeoutTimer) {
@@ -2203,7 +2379,19 @@ class RabbitMQClient extends EventEmitter {
 
     const channel = await this._requireQueueChannel('assertQueue', queue);
 
-    return await channel.assertQueue(queue, queueOptions);
+    try {
+      return await channel.assertQueue(queue, queueOptions);
+    } catch (err) {
+      // The SAME verdict the consume rail states, through the SAME function
+      // (d.582). This is the rail FÁZE 0.8 walks: a service declaring its own
+      // business queues meets the 406 here, and until this batch the raw amqplib
+      // error left with the reply code as a NUMBER and no classification at all,
+      // so `@onlineapps/conn-orch-registry` had nothing to carry and
+      // `@onlineapps/service-wrapper` — which reads `error.code` — called a
+      // refusal transient. `_failFatally()` is deliberately not called: it is
+      // this QUEUE the broker refuses, not the connection.
+      throw this._asRefusal('declare', queue, err);
+    }
   }
 
   /**
@@ -2993,8 +3181,8 @@ class RabbitMQClient extends EventEmitter {
    * declared with.
    *
    * ONE rail for the first `consume()` and for every re-registration after a
-   * channel recreate. It classifies the queue (reply / infrastructure /
-   * business), resolves the arguments from the central config, refuses a queue
+   * channel recreate. It classifies the queue (infrastructure / business /
+   * neither), resolves the arguments from the central config, refuses a queue
    * whose config declares no dead-letter route, and then CHECKS an
    * infrastructure queue (consumers never create those) or ASSERTS a business
    * one.
@@ -3014,15 +3202,24 @@ class RabbitMQClient extends EventEmitter {
     const durable = options.durable !== undefined ? options.durable : this._config.durable;
     let queueOptions = options.queueOptions || { durable };
 
-    // Skip assertQueue for reply queues (they're already created with specific settings)
-    // Reply queues start with 'rpc.reply.' and are created as non-durable
-    const isReplyQueue = queue.startsWith('rpc.reply.');
     // Classification is read once and used by both blocks below — the one that
     // resolves the central arguments, and the one that checks or asserts the queue.
-    const isInfraQueue = !isReplyQueue && queueConfig.isInfrastructureQueue(queue);
-    const isBusinessQueue = !isReplyQueue && queueConfig.isBusinessQueue(queue);
+    //
+    // There is no third class. Until d.514 a name starting `rpc.reply.` was
+    // exempted here and again below: classification, declaration and the broker
+    // question were all skipped, because the retired RPC reply path declared such
+    // a queue itself, with its own non-durable lifetime. Both exemptions had been
+    // unreachable since d.259: `queueConfig` classifies that name as nothing, so
+    // it declares no dead-letter route, so the gate between the two blocks throws
+    // first — measured against the live broker on a reply queue that really
+    // existed (`tests/integration/dead-letter-route-required.integration.test.js`).
+    // The four questions are answered in the CHANGELOG of that batch; the path the
+    // exemption served is gone (`docs/governance/confirmations/mq-consumer-contract.md`
+    // 003 point 3 — "`rpc.reply.*` is not a topology question … it is a removal
+    // question", and `conn-infra-mq` removed `createTemporaryQueue()` in d.275b).
+    const isInfraQueue = queueConfig.isInfrastructureQueue(queue);
+    const isBusinessQueue = queueConfig.isBusinessQueue(queue);
 
-    if (!isReplyQueue) {
     // CRITICAL: Use queueConfig.js to get correct parameters (TTL, max-length, etc.)
     // This prevents 406 PRECONDITION-FAILED errors from TTL mismatches.
     // queueConfig is loaded once at the top of this module; it used to be required
@@ -3066,9 +3263,6 @@ class RabbitMQClient extends EventEmitter {
           : `[RabbitMQClient] [mq-client-core] [CONSUMER] Asserting business queue ${queue} with the declaration queueConfig owns`
       );
     }
-    // End of the queue-classification block. What follows applies to EVERY
-    // queue this consumer may attach to, reply queues included.
-    }
 
     // The dead-letter policy below rejects a spent message with
     // `nack(requeue=false)`, and the broker then moves it ONLY if the queue
@@ -3122,7 +3316,6 @@ class RabbitMQClient extends EventEmitter {
       );
     }
 
-    if (!isReplyQueue) {
     this._logger.debug(`[RabbitMQClient] [mq-client-core] [CONSUMER] Asserting queue ${queue} before consume() at ${new Date().toISOString()}`);
     this._logger.debug(`[RabbitMQClient] [mq-client-core] [CONSUMER] Queue options:`, JSON.stringify(queueOptions, null, 2));
     this._logger.debug(`[RabbitMQClient] [mq-client-core] [CONSUMER] _queueChannel state: exists=${!!this._queueChannel}, closed=${!this._isChannelAlive(this._queueChannel)}`);
@@ -3194,7 +3387,11 @@ class RabbitMQClient extends EventEmitter {
       } catch (assertErr) {
         // If queue exists with different arguments (406), this is a CRITICAL ERROR
         // We should NOT proceed - the root cause must be fixed
-        if (assertErr.code === 406) {
+        // Read off the BROKER's reply code, which since d.582 travels as the
+        // `cause` of the declaration rail's own refusal — never off the marker,
+        // which says "refused" without saying which of the three codes it was.
+        const brokerError = this._brokerRefusalCause(assertErr);
+        if (brokerError && brokerError.code === 406) {
           this._logger.error(`[RabbitMQClient] [mq-client-core] [CONSUMER] ✗ CRITICAL: Queue ${queue} exists with different arguments!`);
           this._logger.error(`[RabbitMQClient] [mq-client-core] [CONSUMER] Error:`, assertErr.message);
           this._logger.error(`[RabbitMQClient] [mq-client-core] [CONSUMER] Expected options:`, JSON.stringify(queueOptions, null, 2));
@@ -3205,14 +3402,15 @@ class RabbitMQClient extends EventEmitter {
               + 'Fix: find the assertQueue() call that declared it without parameters and fix that call; '
               + 'the queue is NOT redeclared here, because doing so would hide the drift instead of ending it.',
             queue,
-            assertErr
+            // The BROKER's error, not the declaration rail's wrapper around it:
+            // one `cause` hop, and `error.cause.code` is the reply code (d.582).
+            brokerError
           );
         }
         // Other error - rethrow
         throw assertErr;
       }
     }
-    }
 
     return queueOptions;
   }
@@ -3497,8 +3695,15 @@ class RabbitMQClient extends EventEmitter {
       // Return consumer tag for cancellation
       return consumeResult.consumerTag;
     } catch (err) {
-      this.emit('error', err);
-      throw err;
+      // ONE place states the broker's verdict for this whole rail — the queue
+      // classification, the declaration and the consumer registration alike —
+      // because it is ONE question ("did the broker answer and refuse?") and a
+      // copy of it per branch is free to drift (`change-discipline.md` § One rail
+      // per concern). Anything the broker did not refuse leaves exactly as it
+      // arrived (d.577).
+      const refusal = this._asRefusal('consume', queue, err);
+      this.emit('error', refusal);
+      throw refusal;
     }
   }
 
@@ -3941,7 +4146,22 @@ class RabbitMQClient extends EventEmitter {
   }
 
   /**
-   * Check prefetch utilization for a queue and alert if threshold exceeded
+   * Check prefetch utilization for a queue and alert if threshold exceeded.
+   *
+   * A window of ONE message has no utilisation to watch (d.550). Its only two
+   * states are 0 % (idle) and 100 % (the consumer is doing the one piece of work
+   * it is allowed), and 100 % is the normal state of a healthy consumer, not a
+   * finding anybody can act on. The alarm therefore fired on EVERY delivery to
+   * such a queue, whatever the threshold - `1/1 >= 0.8` holds exactly as
+   * `1/1 >= 0.99` does. MEASURED (BIZ-pdfgen, BIZ-converter, twice per boot):
+   * `Prefetch utilization high: queue 'biz-pdfgen.registry' has 1/1 messages
+   * in-flight (100%, threshold: 80%)` - a warning that cannot fail to happen
+   * says nothing, and it teaches the reader to skip the line where a real
+   * saturation will one day stand.
+   *
+   * The threshold itself is unchanged and no new one is introduced: a window
+   * larger than one message is measured exactly as before.
+   *
    * @private
    * @param {string} queue - Queue name
    * @param {Object} tracking - Prefetch tracking object
@@ -3950,7 +4170,11 @@ class RabbitMQClient extends EventEmitter {
     if (!tracking || tracking.prefetchCount === 0) {
       return; // No prefetch set or tracking not available
     }
-    
+
+    if (tracking.prefetchCount <= 1) {
+      return; // One-message window: 0 % or 100 %, and 100 % is the working state.
+    }
+
     const utilization = tracking.inFlight / tracking.prefetchCount;
     
     if (utilization >= this._prefetchUtilizationThreshold) {

package/src/workers/RecoveryWorker.js

@@ -27,13 +27,16 @@ const { assertLogger } = require('@onlineapps/logger-contract');
  * Čtyři otázky (`change-discipline.md` § Removing something removes its
  * declaration) jsou zodpovězené v CHANGELOGu dávky.
  *
- * `scope` tedy už o zakládání front nerozhoduje; říká jen, čí ten klient je.
+ * `scope` tedy už o zakládání front nerozhodoval; od d.419 neříkal nic a od d.514
+ * tu není. Co rozhoduje o tvaru hlášení, je třída vlastnictví, kterou odpověděla
+ * CENTRÁLNÍ deklarace — `error.kind` z `QueueNotFoundError` — takže dva klienti
+ * namířené na tutéž frontu nemohou dostat různou odpověď podle toho, kdo je
+ * postavil. Čtyři otázky k odstranění jsou zodpovězené v CHANGELOGu dávky.
  */
 class RecoveryWorker {
   /**
    * @param {Object} options
    * @param {Object} options.client - RabbitMQClient instance
-   * @param {string} [options.scope='infrastructure'] - 'infrastructure' nebo 'business'
    * @param {Object} options.logger - Logger s info/warn/error/debug (povinny)
    */
   constructor(options = {}) {
@@ -45,7 +48,6 @@ class RecoveryWorker {
     }
 
     this._client = options.client;
-    this._scope = options.scope || 'infrastructure';
     this._logger = assertLogger(
       'RecoveryWorker',
       options.logger,
@@ -98,9 +100,11 @@ class RecoveryWorker {
     // with default arguments and no TTL. Refusing at one door while opening the
     // other is not a guard.
     //
-    // `_scope: 'business'` says the CLIENT belongs to a business service. It has
-    // never meant "may create business queues", and ConnectorMQClient.js:74 sets
-    // it for every biz service, so that reading made the rule vacuous.
+    // `recoveryScope: 'business'` said the CLIENT belongs to a business service.
+    // It never meant "may create business queues", and `ConnectorMQClient` set it
+    // for every biz service, so that reading made the rule vacuous. The key is
+    // gone with the door it guarded (d.514); what decides here is `error.kind`,
+    // which the central declaration answers.
     if (error.kind === 'business') {
       this._logger.error(`[RecoveryWorker] Cannot create business queue '${error.queueName}' - it is created by its owning service via setupServiceQueues() after registration`);
       throw error;