@onlineapps/mq-client-core 3.2.0 → 4.0.1

package/CHANGELOG.md

@@ -4,6 +4,374 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [4.0.1] — 2026-09-17
+
+### Fixed — zrušení konzumenta brokerem přestalo být tiché (d.605)
+
+`basic.cancel` od brokera — smazaná fronta, přesun fronty při HA failoveru
+(`x-cancel-on-ha-failover`) — doručí amqplib do callbacku `consume()` jako
+zprávu `null`. Klient na ni odpovídal holým `return`: žádný záznam, žádná změna
+stavu, žádné znovupřipojení. Značka konzumenta zůstala nastavená, a protože
+právě ona je jediný fakt, kterým `performHealthCheck()` odpovídá „je konzument
+TOHOTO klienta připojený", hlásil klient `healthy: true` o frontě, ze které už
+nic nečetl. Ticho je vada stejné závažnosti jako špatný výsledek
+(`automation-gates.md` §5).
+
+Nově v tomto pořadí: značka se zahodí (týž fakt, který d.386b zavedl pro
+odmítnutou re-registraci — od té chvíle je klient `unhealthy` a jmenuje frontu),
+ztráta se zapíše na úrovni **error** se jménem fronty i zrušené značky, a
+konzument se znovu připojí **kolejí, kterou už používá obnova kanálu**: tělo
+smyčky `_reRegisterConsumers()` dostalo jméno (`_reRegisterConsumer()`) a cancel
+volá tutéž funkci pro jednu frontu. Celá smyčka by znovu připojila i konzumenty,
+kteří o své místo nepřišli.
+
+Klasifikaci, deklaraci a prefetch tedy dělá `_prepareQueueForConsume()` —
+vlastněná business fronta se znovu deklaruje, nevlastněná infrastrukturní se jen
+`checkQueue` a její absence je odmítnutí se značkou `CONSUMER_QUEUE_MISSING`,
+nikdy tiché založení. Odmítnuté znovupřipojení nechá konzumenta sledovaného bez
+značky a důvod jede na události, kterou balíček už má —
+`consumer:re-registration:failed`.
+
+**Žádný nový veřejný kontrakt**: žádná nová metoda, žádná nová událost, žádná
+změna podpisu. Každý stav, do kterého se cesta může dostat, už balíček hlásí.
+
+Ticho zůstává tam, kde zrušení není vada: vlastní `cancelConsumer()` callback
+vůbec nevolá (amqplib odregistruje konzumenta na `basic.cancel-ok`; broker
+neposílá cancel), a cancel, který dorazí během `disconnect()`, je zapsán na
+úrovni debug — úmyslné zavření není porucha.
+
+Kdo z toho co má: každá služba, která konzumuje frontu, se po re-pinu na tuto
+verzi dozví, že o konzumenta přišla — dnes to nepozná ani z logu, ani ze
+zdravotní kontroly.
+
+### Fixed — „připojený konzument" má jednu definici, a čte ji i levný reportér (d.613)
+
+`getConsumerState()` vracelo jako `active` klíče `_activeConsumers`, tedy
+konzumenty, které klient **sleduje**. `_performHealthCheck()` odpovídá na tutéž
+otázku podle značky (`consumerInfo.consumerTag`), kterou d.386b a d.605 nechávají
+nastavenou jen po dobu skutečného připojení. Jeden soubor, dvě definice slova
+„aktivní" — a rozcházely se přesně tam, kde na tom záleží: konzument, jemuž
+někdo smazal frontu a jehož znovupřipojení broker odmítl (406), zůstává
+sledovaný bez značky, takže zdravotní kontrola hlásila 0 připojených, kdežto
+`getConsumerState()` frontu dál jmenovalo jako aktivní.
+
+To není kosmetika. `getConsumerState()` je ta **levná synchronní** odpověď, na
+kterou se čtenář dostane: `docs/standards/rabbitmq-channel-best-practices.md`
+§ „Consumers stop receiving after a reconnect" i
+`docs/operations/rabbitmq-connection-recovery-troubleshooting.md` posílají
+operátora právě sem pro tento případ — a dostal odpověď, že konzument je aktivní.
+
+Nově obě čtení volají jednu privátní funkci `_isConsumerAttached(consumerInfo)`;
+`active` jmenuje **připojené** fronty a `tracked` zůstává počtem sledovaných,
+takže `tracked > active.length` je celá věta „tento klient z některé fronty nic
+nebere". Tvar návratové hodnoty se nemění (žádný klíč nepřibyl ani nezmizel),
+mění se pravdivost hodnoty `active`; mimo tento balíček ji dnes nečte žádný kód
+(změřeno přes `api`, `api_biz/*`, `fe_adminui`), takže se nic dalšího
+nepřepisuje.
+
+Kdo z toho co má: `@onlineapps/conn-infra-mq` to po re-pinu pošle dál ve
+`getHealth().consumers` a `@onlineapps/service-wrapper` z toho odvodí
+`components.mq` — služba se ztraceným konzumentem přestane být v heartbeatu
+`healthy`.
+
+## [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

@@ -187,7 +187,10 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   three channels, the consumers this client holds, and what is waiting in the
   publish buffer (`{ size, inMemory }` — there is one buffer). All five refuse
   before `connect()` has built a transport, rather than answering with an invented
-  zero.
+  zero. `getConsumerState()` answers `{ tracked, active }`: `tracked` counts the
+  consumers this client would restore, `active` names the ones ATTACHED right now
+  — the same question the health check asks — so `tracked > active.length` says
+  this client takes no message off some queue it registered.
 - `disconnectAll()` (static, on the class and on the package export) - Close every
   client this module holds; see § Shutdown.
 - `onError(callback)` - Register error handler
@@ -195,7 +198,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 +243,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 }
@@ -312,6 +331,39 @@ There is no third meaning. `requeueOnError: false` together with `maxAttempts`
 above 1 is a contradiction and is **refused where it was written**, rather than
 one of the two being silently ignored.
 
+#### A cancel from the BROKER — the consumer that was stopped without asking
+
+`basic.cancel` sent by the broker is how a consumer learns its attachment is gone
+while the channel and the connection stay up: the queue was deleted, or the broker
+moved it (`x-cancel-on-ha-failover`). amqplib delivers it to the consume callback
+as a `null` message, and it reaches nothing else in this client — the channel
+handlers listen for `error` and `close`, and both stay silent.
+
+It is **not** a silent event. In this order:
+
+- the consumer's tag is dropped, because it names an attachment the broker no
+  longer holds — so `performHealthCheck()` stops counting that consumer as
+  attached the moment the cancel arrives, rather than one recovery later;
+- the loss is logged at **error** level, naming the queue and the tag the broker
+  cancelled;
+- the consumer is re-attached on the rail a channel recreate uses, for that queue
+  alone: the queue is classified, declared or checked and the prefetch re-applied
+  exactly as `consume()` does it. So a business queue the service owns is
+  re-declared, and an infrastructure queue this client does not own is only
+  checked — a deleted one is refused with `CONSUMER_QUEUE_MISSING`, never
+  silently recreated.
+
+If that re-attachment is refused, the consumer stays **tracked with no tag** — the
+same state a refused re-registration leaves — so the client reports itself
+unhealthy and names the queue, `consumer:re-registration:failed` carries the
+broker's reason and code, and the next channel recreate tries again.
+
+Two cancels that are NOT this: `cancelConsumer()` on this client (the broker
+answers `basic.cancel-ok`, the callback is never invoked, and the consumer is
+dropped from the registry on purpose), and a cancel arriving while
+`disconnect()` is running — an intentional close is not a fault, and it is
+recorded at debug level.
+
 ### Connection loss — the contract
 
 When the broker goes away, the transport runs connection-level recovery with
@@ -459,9 +511,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 +576,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.1",
   "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 - `
@@ -1069,9 +1125,14 @@ class BaseClient {
   }
 
   /**
-   * The consumers this client currently holds: how many, and on which queues.
+   * The consumers this client currently holds: how many it TRACKS, and which of
+   * them are ATTACHED right now. A consumer whose queue was deleted, or whose
+   * re-registration the broker refused, stays tracked without its tag — so
+   * `tracked > active.length` says this client takes no message off some queue
+   * it registered (d.613; one definition of "attached",
+   * `RabbitMQClient._isConsumerAttached()`).
    *
-   * @returns {Object} `{ tracked: <count>, active: [<queue names>] }`
+   * @returns {Object} `{ tracked: <count>, active: [<attached queue names>] }`
    * @throws {ConnectionError} Before `connect()` has built a transport.
    */
   getConsumerState() {