@onlineapps/mq-client-core 5.0.0 → 6.0.0

package/CHANGELOG.md

@@ -4,6 +4,480 @@ 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
+
+- `publish(queue, message, { bufferOnFailure: false })` — volba pro jedno volání: zpráva, jejíž
+  publikace selhala přechodně (vyčerpané pokusy, `publishRetryEnabled: false`, selhaný reconnect,
+  na který retry čekal), se NEuloží do bufferu, takže ji žádný reconnect znovu neodešle. Výchozí
+  `true` = chování beze změny. Pro volajícího, který zprávu drží trvale jinde (orchestrátor,
+  `publish_pending`, conf `step-publish-failure` 001; d.1122). Hodnota jiná než boolean se
+  odmítne `ValidationError` před prvním pokusem.
+- Chyba ze tří přechodných cest nese `buffered` (boolean) — na chybě `PublishLayer` i na obalu
+  `PublishError` z `BaseClient.publish()`: `true` jen když buffer zprávu opravdu drží. Trvalé
+  odmítnutí `buffered` nenese. Věta `Fix:` chyby už neslibuje „is buffered“ tam, kde zpráva
+  v bufferu není (volba `false`, nebo buffer zprávu nepřijal).
+- Chyba publishe nese `sent` (boolean) — zda rámec zprávy OPUSTIL klienta (`sendToQueue()` /
+  `publish()` kanálu vrátil bez výjimky), vedle `buffered` z d.1122: na obalu `PublishError`
+  z `BaseClient.publish()` i na chybě `PublishLayer` (`true`, když ho odeslal KTERÝKOLI pokus
+  volání); chyba jednoho pokusu transportu (`_publishOnce()`) nese `sent` toho pokusu. Záznam
+  bufferu nese totéž. Neříká nic o tom, zda broker zprávu uložil: při memory alarmu broker
+  odeslané rámce doručí sám po jeho zrušení (d.1143: 3 kopie publishe na exchange, 1 kopie
+  prvního publishe do fronty, 0 u neodeslaného). Rozhodnutí vlastníka
+  `docs/governance/confirmations/mq-publish-buffer.md` 001 (D); orchestrátor ho kopíruje do
+  záznamu `publish_pending` (`step-publish-failure` 003). Chyba transportu bez booleovského
+  `sent` je vada souseda: `PublishLayer` ji odmítne jménem a zprávu nebufferuje (d.1145).
+
+### Changed
+
+- Každé čekání na odpověď brokera má limit `brokerAnswerTimeout` — jedna kolej, žádný nový klíč
+  (rozhodnutí vlastníka, `docs/governance/confirmations/mq-broker-answer-budget.md` 001, verdikt A;
+  d.1135). Dosud ho mělo jen potvrzení publishe a `close-ok` při `disconnect()`; `assertQueue`,
+  `checkQueue` (veřejné i kontrola před publishem do fronty), `bindQueue`, `assertExchange`,
+  `purgeQueue`, `deleteQueue`, `consume`, `cancelConsumer`, prefetch a otevření kanálu
+  (`createChannel` / `createConfirmChannel`, při `connect()`, obnově i reconnectu) čekaly bez
+  limitu. Změřeno d.1126 na izolovaném brokeru platformního obrazu: při alarmu paměti (spojení
+  žije, heartbeat teče) visela po 300 s, u zmrazeného brokeru je ukončil až heartbeat po ~90 s.
+  Co se mění pro volajícího — hodnotami:
+  - volání, na které broker v limitu neodpoví, skončí po `brokerAnswerTimeout` chybou
+    `ConnectionError` s větou `The broker did not answer <operace> <cíl> within
+    brokerAnswerTimeout (<N>ms)`; kanál, který požadavek nesl, se vyřadí a příští operace otevře
+    nový (kanál, který broker otevře až po limitu, se hned zavře);
+  - publish do fronty, jehož kontrola `checkQueue` (nebo obnova kanálu) nedostala odpověď, je
+    přechodné selhání: `TransientPublishError` → retry → buffer, s `bufferOnFailure: false`
+    `PublishError(cause=TransientPublishError)` a `buffered: false` (D2, conf
+    `step-publish-failure` 001);
+  - holé `Channel ended, no reply will be forthcoming` z amqplibu (kanál nebo spojení skončilo
+    dřív, než broker odpověděl) se na těchto voláních vrací jako `ConnectionError` s původní
+    chybou v `cause`; číslované odmítnutí brokera (404, 406, …) zůstává beze změny;
+  - `connect()`, jemuž broker neodpoví na otevření kanálu, skončí do limitu a zavře spojení
+    v témže limitu (neodpovězené zavření zahodí socket jako `disconnect()`).
+  Heartbeat, potvrzení publishe a teardown beze změny.
+- Klient poslouchá `blocked`/`unblocked` svého spojení (broker v memory/disk alarmu blokuje
+  spojení, které publikuje; d.1143 změřil na obrazu platformy). `blocked` = `warn` s důvodem
+  brokera; `unblocked` = `warn` a flush bufferu jednou kolejí `PublishLayer.flushBuffered('unblocked')`:
+  znovu se pošle JEN záznam, jehož rámec nikdy neopustil klienta; záznam s `sent: true` se vyřadí
+  s `warn` (fronta/exchange, stáří v bufferu), protože broker podržené rámce po alarmu doručí sám.
+  Flush po reconnectu beze změny — `flushBuffered('reconnected')` pošle všechno. Změřeno na
+  izolovaném brokeru d1145-rmq: po uvolnění alarmu u brokera 3 kopie odeslaného publishe na
+  exchange (beze změny, žádná navíc), 1 kopie odeslaného prvního publishe do fronty (beze změny)
+  a nově 1 kopie publishe, který se neodeslal (dřív 0 a tichá expirace); buffer po uvolnění
+  prázdný (dřív 2 a 1). Rozhodnutí vlastníka `docs/governance/confirmations/mq-publish-buffer.md`
+  001 (D), d.1145.
+- `PublishLayer.flushBuffered(trigger)` — jediný argument je nově POVINNÝ spouštěč
+  `'reconnected'` | `'unblocked'` (rozhoduje, co se stane se záznamem, jehož rámec už odešel);
+  jiná hodnota se odmítne jménem. `InMemoryBuffer.flush(flushFn, { sentEntries })` totéž
+  (`'resend'` | `'drop'`). Uvnitř balíčku jediný volající je transport (d.1145).
+  Druhý argument `flushOptions` (slučoval se do voleb každé znovu poslané zprávy) je PRYČ:
+  nikdo ho nepředával (0 volajících v `shared/**`, `infra/**`, `api_biz/*/src`); znovu poslaná
+  zpráva nese přesně volby, se kterými ji buffer držel (d.1145).
+- Vypršení zprávy v bufferu je `error`, ne `info`: jeden řádek na cíl (fronta nebo exchange)
+  a hodnotu `sent`, s počtem, stářím nejstarší a TTL; `sent=false` = zpráva je ZTRACENÁ,
+  `sent=true` = broker ji mohl doručit sám. Dřív „Removed N expired buffered messages“ bez
+  fronty i stáří. Rozhodnutí vlastníka `docs/governance/confirmations/mq-publish-buffer.md`
+  001 (D), d.1145.
+- Publish, jehož potvrzení ještě čekalo, když broker zavřel spojení nebo kanál (`320
+  CONNECTION_FORCED`, restart či stop brokeru, výpadek spojení), končil `PermanentPublishError`
+  bez bufferu a bez retry — zpráva byla ztracena, ač o ní broker nic neřekl (měřeno d.1126).
+  Příčina: amqplib odpovídá nepotvrzeným publishům `Error('channel closed')` ze svého `close`
+  posluchače registrovaného v konstruktoru kanálu, tedy DŘÍV, než klient kanál označil za
+  mrtvý; callback pak četl živý kanál. Klientův `close` posluchač send kanálu se nyní
+  registruje `prependListener` a běží první, takže tahle cesta je přechodná
+  (`TransientPublishError`) a jde dnešní cestou retry/buffer, včetně `bufferOnFailure: false`
+  (`buffered: false`). `nack` brokeru a číslovaný close frame této zprávy zůstávají trvalé
+  (d.1134).
+- Hláška `PublishError` větve fronty při zavření kanálu s čekajícím potvrzením tvrdila „and not
+  reconnecting“ — v S3 nepravda: spojení v tu chvíli ještě neohlásilo `close` a reconnect
+  následuje. Nově: „Channel closed during publish to queue "<q>" before the broker confirmed the
+  message …“, bez tvrzení o reconnectu, `Fix:` odkazuje na `error.buffered` (d.1134).
+- Re-registrace konzumentů po obnově kanálu se ptá na živost konzumentského kanálu před KAŽDÝM
+  konzumentem (a znovu po kroku fronty), ne jednou před smyčkou. Kanál, který zemřel uprostřed
+  smyčky (zavřel ho broker, nebo ho vyřadil `brokerAnswerTimeout`, d.1135), dřív vedl
+  u dalšího konzumenta na `TypeError: Cannot read properties of null (reading 'consume')`
+  a na zbytečnou deklaraci jeho fronty. Nově `ConnectionError` „Cannot re-register the consumer
+  of <q>: consumer channel is not available …“ v `consumer:re-registration:failed`; konzument
+  zůstává sledovaný bez tagu a obnoví ho příští obnova, jako dosud (d.1138).
+- Hláška `_waitForReconnection()` po vypršení jmenovala env `RABBITMQ_RECONNECT_WAIT_TIMEOUT`,
+  který nic nečte. Nově jmenuje, co se čte: klíč konfigurace `reconnectWaitTimeout` („set in the
+  client configuration“), nebo odvození `max(60000, maxReconnectAttempts × reconnectMaxDelay)`,
+  když klíč zadaný není; `Fix:` odkazuje na tentýž klíč. Chování beze změny (d.1138).
+- Přechodná chyba cesty publishe (`_publishPathTransient()`) tvrdila „queue channel is not
+  available (connection may be closed)“ i při ŽIVÉM spojení blokovaném memory alarmem (d.1143,
+  nález 3; od d.1135 končí touto chybou i neodpovězená kontrola `checkQueue`). Věta se nově
+  volí ze stavu klienta: zavřené spojení → „the connection is closed“; blokované → „the broker
+  has blocked this connection (reason: …)“; jinak „the queue channel is not available on a
+  live, unblocked connection“ s příčinou v `error.cause`. Třída beze změny (d.1145).
+
+### Fixed
+
+- Spojení, které obnova navázala až po `disconnect()` volajícího, se zavírá v rozpočtu
+  `brokerAnswerTimeout` (`_closeWithinTeardownBudget()`, jedna kolej, conf
+  `mq-broker-answer-budget` 001). Dřív `await revived.close()` bez limitu: broker, který v tu
+  chvíli neodpovídal, držel kolo obnovy (`_reconnecting: true`) a socket otevřené navždy.
+  Neodpovězené zavření nově zahodí socket jako teardown (d.1138).
+
+### Documentation — JSDoc a popis klíče na pravdu, docblock jedné koleje `workflow_initiated` bez smazané cesty (d.1134, d.1138, d.1176)
+
+- JSDoc `workflowIdOf()` tvrdil, že alias `workflowId` dosud píše webhook submit gatewaye.
+  Nepravda: žádný producent v `shared/**` ani `infra/**` alias nepíše (hlavičky gatewaye nesou
+  jen `workflow_id`, `infra/api_gateway/shared/workflowMessageHeaders.js`); čtení aliasu
+  v transportu neexistuje od d.416, chování beze změny (d.1134).
+- Popis klíče `heartbeat` v `configSchema.js` na pravdu: hodnota se navrhuje brokeru v URL
+  spojení (ne „předává se amqplibu“) a `0` heartbeat NEVYPNE — vyjednávání amqplibu vezme
+  stranu, která limit stanoví, tedy hodnotu brokera (změřeno d.1126: pauza zjištěna po 179 s).
+  Chování beze změny (d.1138).
+- Docblock `src/monitoring-initiated.js` popisuje rozhodnutí o jedné koleji události
+  `workflow_initiated` (conf `scheduler` 009 a 024) bez cesty na smazaný soubor gatewaye
+  a bez vyprávění o kopiích, které to rozhodnutí rušilo; chování beze změny (d.1176).
+
+### Tests — sady bez nástěnného času a s pravdivým popisem bloku (d.1174, d.1138)
+
+- Test, ne chování: sada `connect-timeout-closes-late-handshake.test.js` čekala nástěnný čas
+  (`connectTimeout` 20 ms, pak `setTimeout` 80 ms na druhý pokus reconnectu) a pod zátěží runneru
+  `oa-staging` (pipeline 2904670335) četla `amqp.connect` 2× místo 3×, proto hodiny teď řídí
+  test (`jest.useFakeTimers()` + `advanceTimersByTimeAsync`) a výsledek nezávisí na zátěži
+  stroje (d.1174).
+- Popis bloku testu `connection-parameters-reach-the-broker.test.js` („…one name for its two
+  consumers“) srovnán s d.1135: budget `brokerAnswerTimeout` platí pro každé čekání na odpověď
+  brokera, ne pro dva konzumenty (d.1138).
+- Test, ne chování: akceptační sada čekací koleje `waiting-helper.test.js` měřila vzorkování
+  `waitForValue`/`waitForEvent` na nástěnných hodinách a pod loadem 17–30 (pre-K sweep
+  `release/w4`) vzorek rastru 20 ms zpožděný o víc než 40 ms minul okno 150–190 ms, takže
+  „s `pollMs: 20` tentýž stav VIDÍ" četl `true`; hodiny teď řídí test (`jest.useFakeTimers()`
+  + `advanceTimersByTimeAsync`, čas čte `jest.now()`); hodnoty a počty v tvrzeních beze změny,
+  podlahy pauzy přesně podle pravidla, bez rezervy na plánovač; kolej `tests/waiting.js`
+  nedotčena (d.1192).
+
 ## [5.0.0] — 2026-09-27
 
 ### Removed — BREAKING — fronta `workflow.control` (d.1061)