@onlineapps/mq-client-core 5.1.0 → 6.0.0

package/CHANGELOG.md

@@ -4,6 +4,335 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [6.0.0] — 2026-10-12
+
+### Added — `topology.workflowObserverCopyQueues`: pozorovatelské kopie běhu mají jeden seznam (d.1336, INFRA 559)
+
+Které fronty jsou „pozorovatelské kopie běhu“ (fronty na `monitoring.workflow.fanout` pro čtenáře,
+který běh sleduje a není jeho součástí; dead letter z nich = ztracená kopie telemetrie, ne ztracený
+běh) se vybíralo ručně na dvou místech — monitoring `src/consumer/topology.js` `OBSERVER_COPY_QUEUES`
+a plánovač `config/config.js` `observerCopyQueues`. Obsah se shoduje (změřeno hodnotami):
+`monitoring.workflow`, `delivery.workflow.events`, `scheduler.workflow.events`.
+
+- `queueConfig` deklaruje seznam jednou (`WORKFLOW_OBSERVER_COPIES`, páry `[section, key]`) — odvodit
+  ho z deklarace nejde: vazbu na fanout dělá každý konzument sám při bootu (`bindQueueToFanout()`), na
+  položce je jen komentářem, a TTL + dead-letter route nese každá rodina. Nový pozorovatel = jeden
+  řádek vedle své deklarace.
+- `queueConfig.workflowObserverCopyQueues()` a `topology.workflowObserverCopyQueues` vrací zmrazené pole
+  jmen složených `queueName()` (žádný literál; neznámá položka odmítnuta `ValidationError`).
+- Komentář `monitoring.workflow.fanout` („both receive copies“ — byly tři) ukazuje na seznam.
+- Deklarace front beze změny.
+
+
+### Tests — management API má v IT tieru jeden čtenář: `createMgmtAsk` ze `scripts/tests/sweepOrphanQueues.js` (d.1330)
+
+`tests/vhost.js § mgmt` byl po d.1324/d.1326 poslední vlastní čtenář management API v repu
+(vlastní `fetch`, vlastní mez `MGMT_ASK_TIMEOUT_MS` 5 000 ms, vlastní věta `MGMT_NO_ANSWER`);
+`tests/integration/setup.js` navíc bránu alarmu napojoval adaptérem `{ status, json }` nad ním.
+
+- `mgmt(path, init)` je tenké volání sdíleného čtenáře: požadavek, oba rozpočty a věta pro
+  management API, které neodpoví (`[mq-client-core/integration] The management API did not
+  answer - …` / `… did not finish within 10000ms …`), jsou čtenáře; tento soubor přidává jen
+  bránu stavů (`allow`, `MGMT_REFUSED`) a tvar `{ status, body }`, který sady balíčku čtou
+  (devět IT sad + `mgmtRead`/`mgmtWrite` beze změny). `MGMT_ASK_TIMEOUT_MS`, `MGMT_NO_ANSWER`
+  a `config.rabbitmq.mgmtAuthHeader` jsou pryč (bez čtenáře).
+- `tests/config.js` dodává `timeouts: { connection: 5000, operation: 10000 }` (hodnoty d.1324 /
+  registry d.744b, důvod u klíče) a `tier: 'mq-client-core/integration'`; `rabbitmq` nese
+  `user`/`password` pro čtenáře.
+- `setup.js`: brána `refuseBrokerUnderAlarm` dostává `ask: createMgmtAsk(...)` přímo — adaptér
+  odešel.
+- Sonda `tests/unit/mgmt-reader-has-one-rail.test.js`: žádný vlastní `fetch(` v `tests/**`,
+  `setup.js` bez adaptéru a s `createMgmtAsk(`, `vhost.js` requiruje sdíleného čtenáře; chování
+  `mgmt()` nad atrapou čtenáře (tvar, `allow`, `MGMT_REFUSED`, chyba čtenáře prochází netknutá).
+  `src/**` netknuto.
+
+### Tests — brána „broker pod alarmem“ IT tieru má jedno tělo v repu (d.1326)
+
+- `tests/brokerAlarm.js` (`refuseBrokerUnderAlarm(ask)`, d.807 — „one concern, two
+  implementations, on purpose and on record“ do dne, kdy bude sdílené místo) odstraněn; sdílené
+  místo je `api/scripts/tests/brokerAlarm.js` vedle `sweepOrphanQueues.js` (d.1320). Čtenář
+  zůstává kolej tohoto balíčku `tests/vhost.js` § `mgmt` — `integration/setup.js` ji předává
+  s `allow: [503]` a v tvaru Response (`status`, `json()`), který sdílené tělo čte.
+- `tests/unit/broker-alarm-gate.test.js` míří na sdílené tělo a tvrdí totéž (resource, node,
+  status, jedna otázka `/health/checks/alarms`, nedokumentovaný tvar = „unreported“, bez `ask`
+  odmítnuto jménem) + nově: mlčící čtenář = jeho vlastní chyba projde beze změny (žádný vymyšlený
+  alarm), HTTP mimo 200/503 = „did not answer the alarm check“. Tvrzení `init.allow === [503]`
+  odešlo z unit testu do adaptéru v `setup.js` (detail koleje, ne pravidla).
+
+Příští MAJOR (vlna 5). Tři nálezy INFRA z diagnózy dev plánovače (W224, INFRA 531, 5. 10. 2026):
+N3 je odebrání (BREAKING), N1 a N2 jsou opravy (d.1275).
+
+### Added — `topology.infrastructureHealthChecksQueue` = `infrastructure.health.checks` (d.1307)
+
+Nejčtenější jméno platformy — fronta, na kterou každá infra služba publikuje health checky a
+kterou odebírá registry (`docs/standards/queue-ownership.md` § Infrastructure Queue Creation
+Order) — mělo deklaraci tady (`queueConfig.infrastructure['health.checks']`), ale žádný složený
+export: `topology` (d.270) nesl `health.events`, monitoring a delivery, ne `health.checks`.
+Jméno proto žije podruhé jako literál v `@onlineapps/service-common` `src/defaults.js`
+(`infrastructureHealthQueueName`), který registry, health publisher i wrapper čtou a v hláškách
+označují za „one owner“ — dva deklarující vlastníci jednoho jména na drátě (nález d.1306).
+
+- `topology.infrastructureHealthChecksQueue` je složené z deklarace
+  (`queueConfig.queueName('infrastructure', 'health.checks')`), ne přepsané: přejmenování
+  v `queueConfig` export přesune, smazaný záznam padne rychle; objekt zůstává zmrazený.
+- Čtenář zatím žádný — `@onlineapps/service-common` / `@onlineapps/infrastructure-tools` se
+  přepnou podle rozhodnutí vlastníka A/B (d.1306: service-common cituje export × čtenáři
+  citují export přímo a klíč service-common zaniká). Export je krok společný oběma cestám.
+- Žádná změna chování transportu; test `tests/unit/queueConfig-public-export.test.js`
+  (hodnota, složení z deklarace a nepřítomnost literálu v `src/index.js`, argumenty fronty,
+  kontrola zmrazení a nezměněných jmen). README § topology — řádek tabulky.
+
+### Removed — BREAKING — `criticalHealthShutdown`, `criticalHealthShutdownDelay` a událost `health:shutdown` (d.1275, N3)
+
+Slovo vlastníka 2026-10-06 (dialog 7 (4)): „volbu i událost ZRUŠIT, žádný slib — o životě
+procesu rozhoduje wrapper/služba“.
+
+Co to znamená pro volajícího — hodnotami:
+
+- `new BaseClient({ …, criticalHealthShutdown: <cokoli> })` i `criticalHealthShutdownDelay`
+  hází `ValidationError` `[BaseClient] Configuration key "criticalHealthShutdown" does not exist
+  - Expected: no such key; a shutdown on sustained critical health is not something this client
+  has. Fix: remove "criticalHealthShutdown" from the configuration. …` — odmítnutí jménem
+  kolejí `NOT_A_KEY_OF_THIS_CLIENT`, jako `persistentBufferEnabled` (d.343); ani `false` se
+  nepřijme, protože už není co vypínat;
+- `defaultConfig` ani schéma oba klíče nedeklarují;
+- transport po žádné délce kritického zdraví neemituje `health:shutdown` a nepíše řádky
+  „Critical health will trigger shutdown in <ms> if not resolved“ ani „… - triggering shutdown“;
+- beze změny: `health:critical` a `healthCriticalCallback` při každé selhané kontrole, řádky
+  „Critical health detected at …“ a „Health recovered after <ms> of critical state“.
+
+Čtyři otázky `change-discipline.md` § Removing:
+
+1. **Proč vznikl a co měl dělat.** Volba přišla s monitorováním zdraví transportu: po
+   `criticalHealthShutdownDelay` (60 s) kritického zdraví emitovat `health:shutdown`, aby
+   aplikace proces ukončila a orchestrátor kontejneru ho nahodil znovu. Výchozí `true`.
+2. **Která část konceptu ji nesla a platí ještě.** Žádná živá: koncept životního cyklu říká
+   opak — knihovna proces neukončuje, ukončení je rozhodnutí vlastníka životního cyklu
+   (`_failFatally()` v `transports/rabbitmqClient.js`; trvalou ztrátu spojení hlásí
+   `connection:fatal` + injektovaný `onFatal`). `docs/architecture/rabbitmq-channel-lifecycle.md`
+   ji popisuje jako knob, ne jako rozhodnutí.
+3. **Proč ji dnes nic nečte.** Ustoupila rozhodnutí: `@onlineapps/service-wrapper` posluchače
+   `health:shutdown` odebral 2026-09-07 (jeho CHANGELOG § „Removed — the MQ `health:shutdown`
+   policy that could never apply“), žádná infra služba ho nikdy neměla — změřeno 2026-10-06
+   `git grep -n -e "health:shutdown" -e "criticalHealthShutdown"`: mimo tento balíček jen
+   komentáře a testy wrapperu, dvě věty v `docs/` a záznamy `TODO.md`, žádný kód. Výchozí `true`
+   tak každé kritické okno každého klienta zakončil slibem, který nikdo nesplnil (INFRA 531:
+   plánovač na devu hlásil „will trigger shutdown“, proces běžel dál — správně).
+4. **Je náhrada koncepčnější.** Ano: jedna kolej pro „proces končí“ (`onFatal` /
+   `connection:fatal`, vlastník životního cyklu rozhoduje), a pro trvalé kritické zdraví
+   hlášení bez rozhodnutí (`health:critical`, `healthCriticalCallback`). Slib bez vykonavatele
+   koncepčnější není nikdy.
+
+### Fixed — `consumers.active` se počítá z vlastního stavu klienta, ne z toho, zda doběhla sonda fronty (d.1275, N1)
+
+Dosud se `active` přičítalo jen uvnitř smyčky `checkQueue` v `_performHealthCheck()`. Mrtvý
+frontový (queue) kanál smyčku vůbec nespustil a `checkQueue` bez odpovědi v `brokerAnswerTimeout`
+ji ukončil — v obou případech `active: 0` a verdikt „No consumer of this client is attached …
+this client takes no message off any queue“ o klientovi, jehož consumer kanál žil a přijímal
+(W224 na dev plánovači 5. 10.: spojení i consumer kanál žily, queue kanál thrashoval).
+
+- „Připojený konzument“ má jednu definici `_isConsumerAttached()`: consumer kanál je živý
+  **a** záznam nese tag brokera. Čtou ji `performHealthCheck()` i `getConsumerState()` (d.613),
+  takže se nemění jen zdraví: **`getConsumerState().active` je při mrtvém consumer kanálu `[]`**
+  (dosud vypisoval frontu, dokud záznam držel tag kanálu, který už neexistuje).
+- `consumers.active` / `consumers.inactive` se počítají z toho před sondou, nezávisle na ní.
+  Mrtvý queue kanál je nález kanálu (`Queue channel is closed or missing`), neúspěšná sonda
+  nález sondy (`Error checking queue <q>: …`); věta „No consumer …“ jen když opravdu žádný
+  konzument připojený není.
+- Nové pole `queues.consumers`: `{ <fronta>: <consumerCount brokera> | 'unknown' }` — počet
+  konzumentů na frontě podle brokera (všech, ne jen tohoto klienta), `'unknown'` kde sonda
+  neběžela nebo nedostala odpověď. Nikdy 0 za „neptal jsem se“.
+- Issue u fronty bez připojeného konzumenta jmenuje příčinu: `(consumerTag missing)` při živém
+  consumer kanálu, `(consumer channel is not alive)` při mrtvém.
+
+### Fixed — buffer publishe expiruje podle vlastních hodin a `PublishError` neslibuje „not lost“ (d.1275, N2)
+
+- Záznam bufferu se zahodí **v okamžiku svého TTL** (`publishBufferTtlMs`) jedním časovačem
+  bufferu, ne až při příštím `add()`/`flush()`/`getBufferState()`. Změřeno na dev plánovači:
+  stáří při líné expiraci 584 843 ms a 5 267 969 ms místo 300 000. Časovač běží po koleji
+  časovačů klienta (`_setTimeout()`/`_clearTimeout()`, handle v `_activeTimers`), takže ho
+  `disconnect()` ukončí; prázdný buffer žádný časovač nedrží. `InMemoryBuffer`, `MessageBuffer`
+  a `PublishLayer` (interní, neexportované) proto vyžadují `timers: { setTimeout, clearTimeout }`
+  a bez nich odmítnou konstrukci jménem.
+- ERROR řádek expirace: `sent=false` → `[InMemoryBuffer] <n> buffered message(s) for <cíl> LOST
+  after <ms> ms (buffer TTL <ttl> ms; …)`, `sent=true` → `… expired after <ms> ms …` (broker ji
+  mohl doručit sám; conf `mq-publish-buffer` 001 — obě věty se nikdy neslučují). Věta `Expected:`
+  nově říká, že samotná obnova publisher kanálu nic nepřehraje.
+- `PublishError` z `PublishLayer` s `buffered: true` (vyčerpané pokusy, selhaný reconnect, na
+  který retry čekal) už ve `Fix:` neříká „the message is buffered, so it is not lost“, ale: „the message is buffered
+  for up to <ttl> ms (publishBufferTtlMs) and replayed only after a reconnect or after the broker
+  unblocks the connection — a recovered publisher channel alone does not replay it; if neither
+  comes within that time it expires and is reported as LOST …“ (u `sent: true` „reported as an
+  expired message whose frame had been sent (the broker may hold a copy)“).
+- **Neudělané (čeká na rozhodnutí):** flush bufferu po obnově samotného publisher kanálu.
+  Obnova kanálu na živém spojení je třetí spouštěč, o kterém conf `mq-publish-buffer` 001 nemluví
+  (rozhodl jen `reconnected` a `unblocked`), a u záznamu s `sent: true` je volba mezi druhou
+  kopií a ztrátou — §1.2 `confirmation-triggers.md`.
+
+### Fixed — `consume()`, které čekalo na obnovu, jež nedorazila, dostane chybu toho čekání, ne „queue channel is not available“ (d.1278, INFRA-DOCS ID254)
+
+Dosud `_ensureConsumerChannel()` chybu z čekání na obnovu (`_waitForReconnection()`) zapsalo
+jako WARN a odpovědělo `{ reRegistered: 0, failed: n }`, jako by to byl výsledek; `consume()`
+pokračovalo bez kanálu a volající dostal odmítnutí koleje frontového kanálu „Cannot checkQueue
+<q>: queue channel is not available … Fix: await client.connect()“ — bez `cause`, bez jména
+cyklu, a verdikt fatálního cyklu (`MQ_CONNECTION_FATAL`) dostal jen `onFatal`.
+
+- `_ensureConsumerChannel()` po neúspěšném čekání **hází** `ConnectionError` `[RabbitMQClient]
+  Cannot recreate the consumer channel: the recovery it waited for did not arrive - <věta
+  chyby čekání> Expected: … Fix: read error.cause for the verdict of that recovery …` — stejně
+  jako publisher kolej (`_ensurePublisherChannel()`) chybu čekání propouští.
+- `error.cause` je **tatáž** chyba, kterou cyklus vydal, ne kopie: po posledním cyklu objekt s
+  `code: 'MQ_CONNECTION_FATAL'`, který už dostal `onFatal` (volán právě jednou — hození není
+  druhé hlášení); po vyčerpaném cyklu `ConnectionError` jmenující cyklus (`recovery cycle 2/3
+  spent its 2 attempts …`) **bez `code`** — klient si `MQ_CONNECTION_STANDBY` nechává
+  (`docs/standards/rabbitmq-channel-best-practices.md` § Recovery).
+- Přes `BaseClient.consume()` je to `ConsumeError` → `cause` = ta `ConnectionError` → `cause.cause`
+  = verdikt cyklu.
+- Beze změny: `consume()` na živém kanálu; `consume()` po návratu brokeru spustí další cyklus a
+  konzumenta připojí (líná polovina obnovy, d.339); cesta `onFatal`.
+
+### Fixed — `consume()` na klientovi, který obnovu nespustí, řekne proč — ne „queue channel is not available“ (d.1281, nález d.1278)
+
+Zbylé dvě větve `_ensureConsumerChannel()`, které po d.1278 ještě vracely `{ reRegistered: 0,
+failed: n }` (volající pak dostal odmítnutí frontového kanálu „… queue channel is not available
+… Fix: await client.connect()“ bez `cause`), **hází** `ConnectionError` jmenující stav:
+
+- spojení trvale ztracené (`isConnectionFatal()`): `… the connection is permanently lost and no
+  recovery may start - <věta verdiktu> …`; `error.cause` je **tentýž objekt**, který dostal
+  `onFatal` / `connection:fatal` (`code: 'MQ_CONNECTION_FATAL'`) — klient si ho nově drží
+  (`_connectionFatalError`), `onFatal` se nevolá podruhé;
+- zavřeno volajícím (`disconnect()`): `… the caller closed this client (disconnect()) and no
+  recovery may start - … Fix: await client.connect() before consume(); only an explicit connect()
+  re-arms recovery.` — bez `cause`;
+- obnova vypnutá (`reconnectEnabled: false`): `… the connection is closed and recovery is disabled
+  by configuration (reconnectEnabled: false) - …` — bez `cause`;
+- čekání skončilo `reconnected`, ale spojení už zase neživé: `… the recovery it waited for
+  completed, but the connection is not alive any more - … Fix: run consume() again …` — bez
+  `cause` (druhou smrt nic nedrží jako objekt).
+
+Beze změny: `consume()` na živém kanálu, `onFatal` cesta, publish cesta.
+
+### Fixed — verdikt `MQ_CONNECTION_FATAL` je na chybě z `consume()` čitelný nahoře, ne o `cause` níž (d.1297, nález d.1294)
+
+Chyby z d.1278 a d.1281 (`consume()` čekající na obnovu, která skončila fatálně; `consume()` na
+trvale ztraceném klientovi) nesly verdikt cyklu jen jako `cause`. `BaseClient._consumerRefusal()`
+propouští odmítnutí beze změny jen s `code === 'MQ_CONNECTION_FATAL'` na chybě samé (d.577:
+značku nikdy nepohřbít o `cause` hlouběji) — obalilo je tedy `ConsumeError` a vlastník životního
+cyklu, který čte `error.code`, verdikt neviděl.
+
+- Transport verdikt **přenáší nahoru** (`_carryVerdict()`, jedna kolej pro obě místa): je-li
+  příčina fatální verdikt, chyba nese `code: 'MQ_CONNECTION_FATAL'` a `reason` verdiktu
+  (`'cycles-spent'` | `'broker-refused'`); `cause` zůstává tentýž objekt, který dostal `onFatal`.
+- `BaseClient.consume()` takovou chybu hází **beze změny** (`ConnectionError`, ne `ConsumeError`) —
+  tak jako každé jiné odmítnutí s verdiktem.
+- Nic nechodí řetězem `cause` (žádný fallback nad pohřbenou značkou): vyčerpaný cyklus (standby),
+  `disconnect()` a `reconnectEnabled: false` dál nenesou `code` ani `reason`.
+- Věty `Fix:` obou chyb říkají „read error.code“ místo „read error.cause“.
+
+### Changed — BREAKING — `publish()`, jehož čekání na obnovu skončí standby/fatal, zprávu DRŽÍ v bufferu (`buffered: true`) a nese verdikt nahoře (d.1300, B1)
+
+Slovo vlastníka 2026-10-06 (dialog 9): „B1 — držet v bufferu, `buffered: true`“ — jedna kolej
+pro „čekání na reconnect selhalo“ se sousední cestou `PublishLayer` (přechodná chyba → čekání na
+běžící reconnect → selhání → držení). Dosud (INFRA-DOCS ID254 bod 1, sonda d.1278): send kanál,
+který pokus nedostal, protože spojení zůstalo dole, hodil chybu čekání syrově — volající dostal
+`PublishError` se `sent: false` a **bez `buffered`**, zpráva držena nebyla.
+
+Co se mění pro volajícího — hodnotami:
+
+- `publish()` čekající na obnovu, která skončí **standby** (vyčerpaný cyklus) nebo **dokončením
+  do mrtvého spojení** — tedy tam, kde na tomto klientovi ještě může přijít `reconnected` —
+  odmítne `PublishError` s `buffered: true`, `sent: false`; zpráva je v bufferu a **přehraje se
+  po příštím `reconnected` / `unblocked`** (nic jiného ji nepřehrává), TTL `publishBufferTtlMs`
+  běží od držení, při expiraci ERROR řádek d.1275 (`LOST after <ms>`). Věta `Fix:` jmenuje stav
+  (`recovery cycle 2/3 spent its 2 attempts …`) a pravidla přehrání.
+- Tam, kde `reconnected` už nikdy nepřijde — čekání skončilo **fatálem**, klient je **trvale
+  ztracený**, zavřený **`disconnect()`**, nebo má **`reconnectEnabled: false`** — se **nic
+  nedrží** (`buffered: false`, věta „NOT buffered: this client will not reconnect on its own …
+  the caller holds the only copy“; d.1301 zúžení B1 rozhodnutím leada: držení má smysl jen tam,
+  kde přijde `reconnected`; jinak je to ztráta s odkladem hlášená až při TTL). Třída to nese v
+  povinném `replayable` (boolean), které transport odvozuje ze stavu po skončení čekání.
+- `bufferOnFailure: false` platí i tady: `buffered: false`, nic se nedrží (orchestrátor,
+  `publish_pending`).
+- **Verdikt nahoře** (publishová polovina d.1297): skončí-li obnova fatálně, nese `PublishError`
+  z `BaseClient.publish()` i chyba `PublishLayer` `code: 'MQ_CONNECTION_FATAL'` a `reason`
+  (`'cycles-spent'` | `'broker-refused'`), `cause` řetěz končí tímtéž objektem, který dostal
+  `onFatal`. Standby, `disconnect()` a `reconnectEnabled: false` `code` nenesou (kontrakt).
+- Nová třída `RecoveryEndedPublishError extends TransientPublishError` (export
+  `publishErrors.RecoveryEndedPublishError`): co transport hodí z `_ensurePublisherChannel()`,
+  když spojení zůstalo dole; `PublishLayer` ji drží okamžitě (žádný retry — další cyklus
+  spouští až příští použití klienta) týmž pomocníkem `_failedAfterRecovery()` jako selhané
+  čekání retry. Při `publishRetryEnabled: false` se hází tato chyba sama s `buffered`.
+- Událost `publish:failed` nese `reconnectFailed: true`, `retryable: false` — jako u sousední
+  cesty; `publish:buffered` při držení.
+- `carryVerdict()` z `utils/errorHandler.js` je jedno tělo přenosu verdiktu (transport,
+  `PublishLayer`, `BaseClient.publish()`).
+- Beze změny: sousední cesta (přechodná chyba → čekání na běžící reconnect → selhání) — stejný
+  tvar jako dosud; publish na živém spojení; `onFatal` právě jednou.
+
+### Fixed — `BaseClient.publish()`/`consume()` po `connection:fatal` odmítá s verdiktem nahoře, ne radou „await client.connect()“ (d.1301, nález d.1294 §4/2)
+
+Dosud po fatálu `_connected = false` → `ConnectionError` „Cannot publish/consume: client is not
+connected … Fix: await client.connect()“ bez `code`, ačkoli klient verdikt držel (`_fatalError`) —
+rada nepravdivá (po fatálu rozhoduje vlastník životního cyklu z `onFatal`, ne `connect()`) a
+větve „trvale ztracený“ transportu (d.1281, d.1300) byly přes `BaseClient` nedosažitelné.
+
+- `BaseClient` po fatálu volání **pouští do transportu**, který stav zná a odpoví sám (jedna
+  kolej, žádná druhá věta): `publish()` → `PublishError` s `code: 'MQ_CONNECTION_FATAL'`,
+  `reason`, `buffered: false`, `sent: false`, `cause` řetěz končí objektem z `onFatal`;
+  `consume()` → `ConnectionError` s týmž `code`/`reason`, `cause` = tentýž objekt
+  (`_consumerRefusal()` ji propouští beze změny). Nikde slovo `connect()` jako rada.
+- Beze změny: před prvním `connect()` a po čistém `disconnect()` zůstává „not connected … Fix:
+  await client.connect()“ bez `code` — tam je rada pravdivá. Explicitní `connect()` verdikt
+  smaže (staví nový transport).
+
+### Fixed — každá operace na brokeru po `connection:fatal` odpovídá verdiktem nahoře, ne radou „await client.connect()“ (d.1314, nález d.1301 §6/2)
+
+Rozšíření d.1301 na zbylé strážené metody `BaseClient`: `assertQueue`, `assertExchange`,
+`bindQueue`, `checkQueue`, `purgeQueue`, `deleteQueue`, `cancelConsumer`, `ack`, `nack` (měřeno:
+všech devět po fatálu hlásilo „Cannot <op>: client is not connected … Fix: await client.connect()“
+bez `code`).
+
+- `BaseClient`: jediná stráž `_requireUsable(op)` pro všech jedenáct operací (dosud jedenáct kopií);
+  odmítá jen před prvním `connect()` a po `disconnect()` — toutéž větou jako dosud; po fatálu
+  pouští volání do transportu.
+- Transport: jeden stavitel odmítnutí `_refusalWithoutRecovery(headline, verb)` (dosud jen pro
+  consumer kanál) odpovídá i v koleji frontového kanálu (`_requireQueueChannel`: assert/check/
+  purge/delete/bind/assertExchange), v `cancelConsumer()` a v `ack()`/`nack()`, je-li spojení
+  trvale ztracené: `ConnectionError` s `code: 'MQ_CONNECTION_FATAL'`, `reason`, `cause` = verdikt z
+  `onFatal`; věta „… the connection is permanently lost and no recovery may start - …“ místo
+  „queue channel is not available … wait for the reconnect“ / „consumer channel is not initialized
+  … await client.connect()“.
+- Stavové metody po fatálu nehází a říkají pravdu (beze změny): `isConnected()` `false`,
+  `isConnectionFatal()` `true`, `getConsumerState()` `{ tracked, active: [] }`,
+  `performHealthCheck()` `healthy: false` s `connection.closed: true`, metriky a stav bufferu.
+
+### Fixed — transport: „spojení dole a obnova nemůže začít“ odpovídá na každé koleji touž větou stavu; predikát „obnova může začít“ má jedno tělo (d.1319, nálezy d.1314)
+
+- (A) Po `disconnect()` a při `reconnectEnabled: false` (spojení dole) radily přímé koleje transportu
+  podle staré věty — frontový kanál „queue channel is not available … wait for the reconnect“,
+  `ack`/`nack` „consumer channel is not initialized … await client.connect() and start the consumer“,
+  `cancelConsumer` „call cancelConsumer() again once the connection is back“ — ačkoli žádný reconnect
+  nepřijde. Teď všechny (assert/check/purge/delete/bind/assertExchange, `cancelConsumer`, `ack`,
+  `nack`) odpovídají `_refusalWithoutRecovery()` (tři stavy jako consume d.1281): „… the caller closed
+  this client (disconnect()) and no recovery may start - …“ resp. „… recovery is disabled by
+  configuration (reconnectEnabled: false) - …“, bez `code` (není fatál). Beze změny: standby
+  (cyklus může přijít) dál „wait for the reconnect“; po fatálu verdikt (d.1314). Přes `BaseClient`
+  tyto dva stavy dál chytá jeho stráž („not connected … Fix: await client.connect()“).
+- (B) `_recoveryMayStart()` je jediné tělo predikátu „obnova může začít“ (ne fatál, ne `disconnect()`,
+  `reconnectEnabled: true`); čtou ho `_resumeRecovery()`, `replayable` v `_recoveryEndedForPublish()`
+  a koleje z (A). Chování beze změny.
+
+### Fixed — zavření spojení z opuštěného handshaku čeká na `close-ok` nejvýš `brokerAnswerTimeout` (d.1322, položka vlny 5)
+
+`_closeAbandonedHandshake()` (handshake dokončený po `connectTimeout`, který klientovi nepatří)
+čekalo na `late.close()` bez rozpočtu: broker, který na close neodpověděl, nechal pozdní spojení,
+jeho socket i heartbeat žít do konce procesu (únik handshaků). Teď jde zavření toutéž kolejí jako
+teardown (`_closeWithinTeardownBudget()` → `_awaitBrokerAnswer()`, jediný rozpočet čekání na broker —
+conf `mq-broker-answer-budget` 001): po `brokerAnswerTimeout` WARN „The broker did not answer the
+abandoned <connect|reconnect> handshake close within the teardown budget (<ms>ms) - …“ a socket s
+heartbeatem se zahodí (`_dropUnansweredConnection()`, jako u napůl otevřeného spojení v `connect()`).
+Časovač rozpočtu je na koleji klienta a s odpovědí se ruší; odmítnuté close hlásí dosavadní WARN.
+
 ## [5.1.0] — 2026-10-03
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ Uniform: [library/connector](../connector/conn-orch-validator/manifests/library.
 
 Duty sections that apply:
 
-- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-PACK-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
 - `connector`: L-CONNECTOR-ENV
 <!-- END GENERATED: library-uniform -->
 
@@ -107,6 +107,14 @@ config → env (`RABBITMQ_MAX_RECONNECT_ATTEMPTS`, `RABBITMQ_MAX_RECONNECT_CYCLE
 attempts inside ONE recovery cycle, the second how many cycles there may be — see
 § Connection loss.
 
+**`criticalHealthShutdown` and `criticalHealthShutdownDelay` are refused by name** (removed
+2026-10-06, d.1275, on the owner's word). They made the transport, after a minute
+of critical health, emit `health:shutdown` and log that it was "triggering shutdown" — but this
+library never ends the process (see § Connection loss), and nothing on the platform listened
+for the event, so the line promised an action that never came. The event went with the keys.
+Critical health is reported — `health:critical` and `healthCriticalCallback` on every failing
+check — and what to do about the process is the lifecycle owner's decision (`onFatal`).
+
 ### A subclass declares its own keys
 
 `new BaseClient(config, extraProperties?)`. The second argument is the JSON Schema
@@ -172,7 +180,17 @@ Owner decision: `api/docs/governance/confirmations/connector-logger-contract.md`
   healthy** — `healthy: false`, with an issue naming how many it tracks — because
   such a client takes no message off any queue. A client that registered no
   consumer at all is a publisher and stays healthy; the check's own log line says
-  which of the two it is.
+  which of the two it is. `consumers.active` / `consumers.inactive` are this
+  client's own facts — a consumer is attached while the consumer channel is alive
+  and its entry holds the broker's tag (the definition `getConsumerState()` reads)
+  — so a dead QUEUE channel or an unanswered queue probe is reported as what it is,
+  a channel or probe issue, never as "no consumer" (d.1275). The probe adds what
+  only the broker knows: `queues.consumers` maps each tracked queue to the broker's
+  `consumerCount` (every consumer on the queue, not only this client's), or to
+  `'unknown'` where the probe did not run or got no answer — never `0` for "not
+  asked". A failing check emits `health:critical` and calls
+  `healthCriticalCallback`; it decides nothing about the process (there is no
+  `health:shutdown`, see § Configuration).
 - `assertQueue(queue, options?)` / `checkQueue(queue)` / `purgeQueue(queue)` /
   `deleteQueue(queue, options?)` - Queue operations, on the queue channel.
   `assertQueue()` reads exactly four options — `durable`, `arguments`,
@@ -458,8 +476,21 @@ Permanently lost means all of this, together:
   built on them;
 - no further reconnect attempts are made, by a use or otherwise — the client is
   dead until the process restarts, or until an explicit `connect()`;
-- `publish()`/`consume()` refuse immediately instead of blocking on a recovery
-  that is not coming.
+- `publish()`/`consume()` — and every other operation on the broker:
+  `assertQueue`, `checkQueue`, `purgeQueue`, `deleteQueue`, `assertExchange`,
+  `bindQueue`, `cancelConsumer`, `ack`, `nack` — refuse immediately instead of
+  blocking on a recovery that is not coming, with the verdict on the error
+  (`code: 'MQ_CONNECTION_FATAL'`, `reason`, the verdict as `cause`); through
+  `BaseClient` too, which after the verdict lets the lost client answer for
+  itself instead of advising `connect()`. The state readers (`isConnected()`,
+  `isConnectionFatal()`, `getConsumerState()`, `getChannelState()`,
+  `performHealthCheck()`, the metrics) do not throw: they describe the state. A `consume()`
+  that was waiting when the verdict fell, or that is asked of the lost client
+  afterwards, is refused with that verdict readable on the error (`code`,
+  `reason`) and the verdict itself in `cause`. A `publish()` in the same position
+  is refused with a `PublishError` that carries the same `code` and `reason` and
+  `buffered: false`: nothing is held, because no `reconnected` will ever come to
+  replay it (§ *The publish buffer*) — the caller holds the only copy.
 
 **The library never ends the process, and never listens for a signal.** Ending
 it is the lifecycle owner's decision: a service typically logs and exits
@@ -590,14 +621,27 @@ is permanent (d.1134).
 **One call can leave the buffer: `publish(queue, message, { bufferOnFailure: false })`.**
 It is for a caller that keeps the message durably elsewhere and must not have a second
 copy replayed behind its back — the orchestrator writing a `publish_pending` record
-(`docs/governance/confirmations/step-publish-failure.md` 001). On each of the three
+(`docs/governance/confirmations/step-publish-failure.md` 001). On each of the four
 transient paths (retries exhausted, `publishRetryEnabled: false`, the reconnect a retry
-waited for failed) the error `publish()` throws carries `buffered` (boolean): `true` only
-when the buffer holds the message for the next reconnect, `false` when nothing will
-replay it. A permanent refusal never reaches the buffer and carries no `buffered`. A
+waited for failed, and a send channel the attempt could not get because the connection stayed
+down — the recovery it waited for ended in standby or fatal, or none may start: the client is
+permanently lost, closed by `disconnect()`, or has `reconnectEnabled: false`; B1, the owner's
+decision of 2026-10-06) the error `publish()` throws carries `buffered` (boolean): `true` only
+when the buffer holds the message for the next reconnect or `unblocked`, `false` when
+nothing will replay it. A permanent refusal never reaches the buffer and carries no `buffered`. A
 value that is not a boolean is refused before any attempt (`ValidationError`). Retry
 stays the library's either way — the option decides only what happens after it.
 
+The fourth path is its own class on the transport, `RecoveryEndedPublishError` (a
+`TransientPublishError`, exported under `publishErrors`): `PublishLayer` holds the message at
+once instead of retrying, because the next use of the client is what starts the next recovery
+cycle. It holds it **only where a `reconnected` can still come** — the class says so in
+`replayable`: after a spent cycle (standby) the message is held; once the client is permanently
+lost, closed by `disconnect()`, or has `reconnectEnabled: false`, nothing will ever replay it, so
+nothing is held and the error says `buffered: false` with the reason. When the recovery ended
+fatally the `PublishError` carries the verdict on top — `code: 'MQ_CONNECTION_FATAL'`, `reason` —
+and the verdict itself at the end of `cause`; a spent cycle carries no code.
+
 **Every failed publish says whether its frame left the client: `error.sent`** (boolean, on
 the `PublishError` from `publish()` and on its cause; conf
 `docs/governance/confirmations/mq-publish-buffer.md` 001). `true` when any attempt wrote the
@@ -611,9 +655,21 @@ happens when the outage ends:
 | a reconnect (`reconnected`) | re-sent | re-sent — the old socket and what the broker had not read are gone |
 | the broker unblocking the connection (`connection.unblocked`, end of a memory or disk alarm) | re-sent | dropped with a `warn` — the broker delivers the frames it held by itself |
 
-`connection.blocked` is logged as a `warn` with the broker's reason. A held message that
-outlives `publishBufferTtlMs` is logged as an `error` naming its queue or exchange, the
-count, the age and `sent` — `sent=false` is a message lost for good.
+`connection.blocked` is logged as a `warn` with the broker's reason. **Nothing else flushes
+the buffer**: an outage of the publisher CHANNEL alone, on a connection that stays up and is
+not blocked, ends with neither event, so a message held during it is not replayed when the
+next publish recreates the channel. Whether a channel recovery should flush too is an open
+decision (a sent entry re-sent then may be a second copy), and the error `publish()` throws
+says the gap in as many words: buffered for up to `publishBufferTtlMs`, replayed only after a
+reconnect or `unblocked`, reported as LOST at expiry.
+
+A held message that outlives `publishBufferTtlMs` is dropped **at its TTL, on the buffer's own
+timer** — not whenever the buffer is next touched (until d.1275 the expiry ran only inside the
+next `add()`/`flush()`/`getBufferState()`, and was measured on the dev scheduler up to 88
+minutes late; d.1275). The timer runs on the client's timer rail, so `disconnect()` ends it. The
+drop is logged as an `error` naming its queue or exchange, the count, the age and `sent` —
+`sent=false` reads `LOST after <ms>` and is a message lost for good; `sent=true` reads `expired
+after <ms>`, because the broker may have delivered it on its own.
 
 **There is no persistent buffer, and `persistentBufferEnabled` /
 `persistentRedisClient` are refused by name.** They declared one until
@@ -658,11 +714,15 @@ error had never once run (fixed 2026-09-08, `errors.ConnectionError` now carries
 | `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 |
+| `MQ_CONNECTION_FATAL` (with `reason: 'cycles-spent' \| 'broker-refused'`, and `isConnectionFatal()` now `true`) | the CONNECTION is permanently lost — the recovery this `consume()` waited for ended the client, or the client was already lost; `error.cause` is the very verdict `onFatal` received (§ *permanently lost*) | the lifecycle owner stops the process; the restart policy boots a new one against a verified broker |
 
 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
+`false`. The fourth is that connection verdict itself, carried onto the `consume()` that met
+it (one rail, `_carryVerdict()`): the code is on the error, not only in its `cause`, so
+`BaseClient` lets it through unchanged as it does every refusal with a verdict. A recovery
+cycle that merely ran out (standby) is no verdict and carries no code. `@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.
 
@@ -758,6 +818,7 @@ topology.telemetryLogsQueue = 'mine';        // TypeError — the object is froz
 
 | Key | Name on the wire | Who publishes / who drains it |
 |---|---|---|
+| `infrastructureHealthChecksQueue` | `infrastructure.health.checks` | Every infrastructure service publishes its health checks there (`@onlineapps/infrastructure-tools` `healthPublisher.js`); the registry drains it (`api/infra/api_services_registry/src/listeners/infrastructureHealth.listener.js`). Composed here since d.1307; no reader cites it yet — `@onlineapps/service-common` still carries the literal (`src/defaults.js`), and which side switches is the owner's decision (d.1306). |
 | `infrastructureHealthEventsExchange` | `infrastructure.health.events` | Fanout. The registry publishes (`api/infra/api_services_registry/src/services/infrastructureEventPublisher.js`); the two queues below are bound to it. |
 | `monitoringInfrastructureHealthEventsQueue` | `monitoring.infrastructure.health.events` | The monitoring consumer's queue on that fanout (`api/infra/api_monitoring/src/consumer/topology.js`, `MONITORING_INFRA_EVENT_QUEUE`). |
 | `deliveryHealthEventsQueue` | `delivery.health.events` | The delivery endpoint binds it to the fanout and consumes it for WS push (`api/infra/api_delivery_endpoint/src/index.js`, `bindQueueToFanout(config.healthEventsQueue, …)`). |
@@ -766,6 +827,7 @@ topology.telemetryLogsQueue = 'mine';        // TypeError — the object is froz
 | `telemetryMetricsQueue` | `telemetry.metrics.queue` | The same exchange, the same consumer — metric samples. |
 | `telemetryTracesQueue` | `telemetry.traces.queue` | The same exchange, the same consumer — spans. |
 | `telemetryExchange` | `telemetry.exchange` | Topic exchange the three queues above are bound to; every telemetry producer publishes to it, and the monitoring consumer asserts it (d.708b). |
+| `workflowObserverCopyQueues` | `['monitoring.workflow', 'delivery.workflow.events', 'scheduler.workflow.events']` (frozen array) | The observers' copies of a run: the queues bound to `monitoring.workflow.fanout` for a reader that watches the run and is not part of it (the monitoring consumer, the delivery endpoint's WS feed, the scheduler's end-of-run watch). A dead letter from one of them is a lost copy of the run's telemetry, not a lost run (INFRA 559). Declared once in `queueConfig` (`WORKFLOW_OBSERVER_COPIES`) — membership cannot be read off an entry, because the binding is each consumer's own act at boot — and composed by `queueName()` (d.1336). |
 
 - **Frozen on purpose.** An importer must not be able to rewrite platform topology: a
   name overridden on one side of a fanout loses the events silently, which is why batch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "5.1.0",
+  "version": "6.0.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"
@@ -23,7 +23,7 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/logger-contract": "2.0.0",
+    "@onlineapps/logger-contract": "2.1.0",
     "@onlineapps/runtime-config": "1.2.0",
     "ajv": "^8.12.0",
     "amqplib": "0.10.9"