@onlineapps/mq-client-core 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,153 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [4.1.0] — 2026-09-23
+
+### Added — plánovač se dozví KONEC běhu z vlastní fronty (d.818)
+
+`queueConfig.scheduler` nese třetí položku, `workflow.events`. Je to fronta,
+kterou si plánovač sám naváže na existující výměnu `monitoring.workflow.fanout`
+a čte si z ní terminální událost běhu (`completed` / `failed` / `discarded`) —
+místo aby se ptal pozorovatele přes HTTP nebo četl databázi, která není jeho
+(rozhodnutí vlastníka, `api/docs/governance/confirmations/scheduler.md` 007).
+Žádný producent se nemění; od knihovny je jen deklarace.
+
+TTL je **vyslovená, ne zděděná**: `x-message-ttl: 300000`, stejně jako u
+sourozence `monitoring.workflow` na téže výměně. Fanout neumí filtrovat, takže
+fronta dostane všechny workflow události platformy a plánovač většinu zahodí; co
+stojí výpadek delší než TTL, je zapsané v 007 (události se ztratí a běh uzavře
+per-schedule timeout, který zůstává pojistkou). Dál `x-max-length: 10000` a
+dead-letter přes VÝCHOZÍ výměnu do `scheduler.dlq` — bez deklarované cesty by
+`consume()` frontu vůbec nepřipojil (conf `mq-consumer-contract` 002).
+
+Import: `queueConfig.queueName('scheduler', 'workflow.events')` složí jméno,
+`queueConfig.declarationOptions('scheduler.workflow.events')` vrátí argumenty,
+kterými ji služba asserteuje — druhá kopie těch čísel u služby by se s touhle
+potkala jako 406 v den, kdy se rozejdou.
+
+### Added — `workflow_initiated` má jednu kolej: stavitel události vedle jejího přenosu (d.819)
+
+`monitoring.buildWorkflowInitiatedEvent()` a `monitoring.publishWorkflowInitiated()`
+— jediný stavitel události, ze které se monitoring dozví, že běh existuje (čte
+z ní tenanta, štítky i spouštěč a teprve jí označí běh za `active`). Dosud ji
+stavěly dvě služby, každá po svém; rozhodnutí vlastníka
+(`api/docs/governance/confirmations/scheduler.md` 009) dalo kolej sem, do
+knihovny, která už vlastní přenosovou půlku téhož drátu.
+
+Vstup: `{ workflowId, redactedCookbook, serviceName, timestamp }`. Modul
+**neredaguje** — co je v receptu citlivé, ví jedině spec služby v registru, a
+číst ho by knihovně přidalo závislost na specech operací; volající předává
+observability kopii, kterou si sám postavil. A **nic nevymýšlí**: každý klíč
+`_system` musí existovat (`hasOwnProperty`, ne pravdivost), takže
+`tenant_uuid: null` projde jako výslovná hodnota (conf
+`run-envelope-tenant-uuid` 001) a chybějící klíč je hlášená chyba, ne tiché
+`null`.
+
+Publikace jde stávající `publishToMonitoringWorkflow`, tedy fail-safe: ztracená
+kopie se hlásí, běh se kvůli ní neodmítá. Jediná výjimka je chybějící logger —
+bez něj by slib „každé selhání se ohlásí" neplatil.
+
+Import: `const { monitoring } = require('@onlineapps/mq-client-core');`
+
+### Added — jméno `monitoring.resource` má vlastníka v jádru (d.619)
+
+Topic exchange, po které jezdí události `resource.changed.*`, byla poslední
+stranou téhle linky bez vlastníka jména: publikující strana ji nesla jako
+konstantu modulu (`api/infra/api_monitoring/src/consumer/watchers/
+resourceChangedPublisher.js`, `EXCHANGE_NAME`), bindující strana jako **povinný
+env klíč** (`MONITORING_RESOURCE_EXCHANGE` v delivery-endpointu), zatímco fronta
+na ni navázaná (`delivery.resource.events`) má vlastníka tady od d.270/d.278.
+Jméno, na kterém se musí shodnout tři strany jedné linky, má mít jednoho
+vlastníka — jinak jich má tolik, kolik je míst, která ho píší, a překlep nebo
+override na jedné straně ztrácí události tiše (týž důvod jako u fanout výměny
+`infrastructure.health.events`, d.270).
+
+Nově: `queueConfig.monitoring.resource` deklaruje `type: 'exchange'`,
+`exchangeType: 'topic'`, `durable: true` — tvar, který publikující strana
+asserteuje a který vrací i běžící broker — a `topology.monitoringResourceExchange`
+to jméno publikuje, složené z té deklarace (`queueConfig.queueName()`), ne
+přepsané. Import: `const { topology } = require('@onlineapps/mq-client-core');`
+
+Doklad proti realitě, ne proti sobě: integrační tier jméno ověřuje na živém
+brokeru (`checkExchange`) a deklarovaný typ `assertExchange`em, s kontrolním
+případem, že tatáž výměna asserteovaná jako `fanout` končí 406 — typ je tedy
+změřený, ne předpokládaný.
+
+Beze změny na drátě: žádné jméno se nepřejmenovává, výměna se nezakládá (
+deklarace není pokyn k vytvoření — zakládá ji dál vlastník prefixu). Pro INFRA
+z toho plyne, že povinný klíč `MONITORING_RESOURCE_EXCHANGE` může po re-pinu
+zmizet stejně jako pět jmen před ním.
+
+## [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)

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
@@ -328,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
@@ -637,6 +673,53 @@ topology.telemetryLogsQueue = 'mine';        // TypeError — the object is froz
 - A service that still carries one of these names as a private literal is carrying the
   spelling of a fact declared here; importing it changes the wire by nothing at all.
 
+### monitoring — `workflow_initiated`, the event a run is known by
+
+Monitoring learns that a run exists from ONE event and from nowhere else: it reads the run's
+tenancy, its labels and its trigger out of `workflow_initiated` and marks the run active on it.
+A service that starts runs and does not file it starts runs that are invisible for their whole
+life. So the event has one builder, here, beside the transport half that sends it
+([`scheduler` 009](/docs/governance/confirmations/scheduler.md)).
+
+```javascript
+const { monitoring } = require('@onlineapps/mq-client-core');
+
+await monitoring.publishWorkflowInitiated({
+  mqClient,
+  logger,
+  workflowId,
+  redactedCookbook,                 // already redacted by the caller
+  serviceName: 'api_gateway',       // who files the event
+  timestamp: startedAt,             // the run's instant, not a second reading of the clock
+  context: { correlationId }        // optional, for the log lines
+});
+```
+
+`monitoring.buildWorkflowInitiatedEvent({ workflowId, redactedCookbook, serviceName, timestamp })`
+composes the body alone, so a suite can state it without a broker. It carries exactly these ten
+keys: `event_type` (`initiated`), `workflow_id`, `service_name`, `step_index` (`-1`), `step_id`
+(`workflow_start`), `cookbook`, `status` (`initiated`), `tenant_uuid`, `tenant_id`, `timestamp`.
+
+What it does NOT do, and both halves are rules rather than omissions:
+
+- **It does not redact.** What is sensitive in a cookbook is known only to the service spec in
+  the registry, and reading that spec would give this package a dependency on the operation
+  specs. The caller hands over the observability copy it built; a path that cannot redact does
+  not file the event at all, because an empty set of sensitive fields is silent consent to an
+  unredacted copy.
+- **It invents no value.** `service_name` and the instant are the caller's, and every key it
+  reads out of `_system` must EXIST — `hasOwnProperty`, not truthiness. `tenant_uuid: null`
+  therefore passes through as the explicit value it is (a webhook run proves itself by
+  signature and has no personal identity), while a MISSING `_system.tenant_id` or
+  `_system.tenant_uuid` is a reported error. A `|| null` here would make the two cases
+  identical and hide a broken envelope.
+
+`publishWorkflowInitiated()` is **fail-safe**: it never throws. It is observability about a run
+that has already happened, so refusing the run because the observer could not be told would
+trade a real effect for a record of it — a lost copy is reported through the logger and the call
+answers `false`. The one exception is a missing logger, which is the transport half's rule:
+without it the promise "every failure is reported" cannot hold.
+
 ### redactUrl — a connection URL that is safe to log
 
 `RABBITMQ_URL` carries the broker account, so anything that renders it verbatim

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"

package/src/BaseClient.js

@@ -1125,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() {

package/src/config/queueConfig.js

@@ -60,7 +60,8 @@ const SECTION_PREFIXES = Object.freeze({
   monitoring: 'monitoring',
   telemetry: 'telemetry',
   alerts: 'alert',
-  registry: 'registry'
+  registry: 'registry',
+  scheduler: 'scheduler'
 });
 
 /**
@@ -81,7 +82,8 @@ const INFRASTRUCTURE_PREFIX_LOOKUPS = Object.freeze({
   validation: 'getValidationQueueConfig',
   monitoring: 'getMonitoringQueueConfig',
   telemetry: 'getTelemetryQueueConfig',
-  delivery: 'getDeliveryQueueConfig'
+  delivery: 'getDeliveryQueueConfig',
+  scheduler: 'getSchedulerQueueConfig'
 });
 
 const INFRASTRUCTURE_PREFIXES = Object.freeze(Object.keys(INFRASTRUCTURE_PREFIX_LOOKUPS));
@@ -689,6 +691,33 @@ module.exports = {
       durable: true
     },
 
+    /**
+     * monitoring.resource - Topic exchange for resource-changed events
+     *
+     * The monitoring consumer's resource-changed watcher publishes here with a routing
+     * key of the shape `resource.changed.<resource_type>`; the delivery endpoint binds
+     * `delivery.resource.events` to it by the pattern `resource.changed.#` for WS push.
+     * Three sides of ONE wire — the publisher, this exchange and the bound queue — and
+     * until d.619 the name had an owner on none of them: a module constant on the
+     * publishing side and a required env key on the binding side, so an override or a
+     * typo on either side loses every event silently. That is the same reasoning d.270
+     * settled for the health-events fanout, and the reason the name lives here and is
+     * published by `src/index.js` § topology.
+     *
+     * `topic`, `durable`, no arguments: what the publisher asserts, and what the running
+     * broker answers for it. An exchange holds nothing to dead-letter, so — like every
+     * other exchange in this file — it carries no route, even though every QUEUE of this
+     * section routes to `monitoring.dlq`.
+     *
+     * @see api/infra/api_monitoring/src/consumer/watchers/resourceChangedPublisher.js
+     * @see api/docs/biz/70-contracts/resource-changed.md
+     */
+    resource: {
+      type: 'exchange',
+      exchangeType: 'topic',
+      durable: true
+    },
+
     /**
      * monitoring.infrastructure.health.events - the monitoring consumer's own copy of
      * the infrastructure health events, bound to the infrastructure.health.events
@@ -743,8 +772,8 @@ module.exports = {
    * Telemetry queue configurations
    *
    * The OpenTelemetry intake of the monitoring consumer: every service publishes
-   * logs, metrics and spans to `telemetry.exchange` with a routing key carrying its
-   * own name, and these three queues are bound to it
+   * logs, metrics and spans to the `telemetry.exchange` declared below, with a routing
+   * key carrying its own name, and these three queues are bound to it
    * (`docs/standards/monitoring-queues.md`, `docs/architecture/monitoring.md`).
    *
    * The TTL and the cap are the ones the queues are created with today; this config is
@@ -758,6 +787,45 @@ module.exports = {
    * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
    */
   telemetry: {
+    /**
+     * telemetry.exchange - the topic exchange every telemetry producer on the platform
+     * publishes to, and the one the three queues below are bound to.
+     *
+     * The widest wire there is: every biz service through `@onlineapps/service-wrapper`,
+     * every infrastructure service through `@onlineapps/monitoring-core` (its logger and
+     * its OpenTelemetry exporter), and the monitoring consumer, which asserts the
+     * exchange, binds the three queues and drains them — and since I16 publishes its own
+     * lines onto it as well.
+     *
+     * Until d.708 the name appeared HERE only in the prose above, while the other three
+     * platform exchanges of this file (`infrastructure.health.events`,
+     * `monitoring.workflow.fanout`, `monitoring.resource`) each had a template. So one
+     * name had three owners — a module constant in the monitoring consumer
+     * (`infra/api_monitoring/src/consumer/topology.js`) and a config default in each of
+     * monitoring-core's two publishers — which is exactly the shape d.270 gave an owner
+     * for the health-events fanout and d.619 for the resource-changed topic
+     * (`change-discipline.md` § One rail per concern).
+     *
+     * `topic`, `durable`, no arguments: what all three of those sides assert today
+     * (`assertExchange(<name>, 'topic', { durable: true })`), measured before this entry
+     * was written. The broker compares an exchange's type and durability at EVERY
+     * declaration, so a value invented here would be `406 PRECONDITION-FAILED` for
+     * whichever side booted second. An exchange holds nothing to dead-letter, so — like
+     * every other exchange in this file — it carries no route, even though every QUEUE
+     * of this section routes to `telemetry.dlq`.
+     *
+     * Declaring it is not creating it: the exchange is brought into being by the service
+     * that asserts it, the same rule as `telemetry.dlq` below.
+     *
+     * @see api/infra/api_monitoring/src/consumer/index.js — assertMonitoringTopology()
+     * @see api/shared/monitoring/monitoring-core/src/exporters/rabbitmq.js
+     */
+    exchange: {
+      type: 'exchange',
+      exchangeType: 'topic',
+      durable: true
+    },
+
     /** telemetry.logs.queue - OpenTelemetry log records, drained into Loki. */
     'logs.queue': {
       durable: true,
@@ -932,15 +1000,129 @@ module.exports = {
     },
 
     /**
-     * registry.changes - Registry event fanout exchange
-     * (This is an exchange, not a queue, but included for reference)
+     * registry.changes - the fanout exchange registry index changes travel on.
+     *
+     * One module is every side of this wire: `@onlineapps/conn-orch-registry`,
+     * `src/registryEventConsumer.js`. It holds the only spelling of the name (`:92`),
+     * it is the only party that ASSERTS the exchange (`:117`,
+     * `assertExchange(name, 'fanout', { durable: true })`), it binds each service's
+     * `{service}.registry.events` to it with the pattern `''` (`:133`), and it publishes
+     * the snapshot request onto it (`:331`, `routingKey: ''`). The publish path declares
+     * nothing since d.342, so there is no second founder.
+     *
+     * Until d.712 this was the ONE exchange of this file with no `exchangeType`, so the
+     * founder had to decide the kind on its own while the template only said "an
+     * exchange, durable". `type` is one of the two properties the broker compares at
+     * every declaration, which makes it exactly the half that cannot live somewhere
+     * else (`change-discipline.md` § One rail per concern; the same step d.619 made for
+     * `monitoring.resource` and d.708 for `telemetry.exchange`).
+     *
+     * `fanout`, `durable`, no arguments: measured on that founder, not chosen. The
+     * binding pattern `''` only routes on a fanout, so the type is load-bearing rather
+     * than decorative. An exchange holds nothing to dead-letter, so — like every other
+     * exchange in this file — it carries no route.
+     *
+     * Declaring it is not creating it: the exchange is brought into being by the service
+     * whose registry client subscribes to changes.
+     *
+     * @see api/shared/connector/conn-orch-registry/src/registryEventConsumer.js
      */
     changes: {
       type: 'exchange',
+      exchangeType: 'fanout',
       durable: true
     }
   },
 
+  /**
+   * Scheduler queue configurations — the platform's one holder of time.
+   *
+   * The scheduler consumes requests for a run: a recurrence that came due, or a deferred
+   * request somebody filed. Both are published by other services and both are the ONLY
+   * record that the run was owed, so the family is shaped for loss-aversion rather than
+   * for freshness (`docs/governance/confirmations/scheduler.md` 001, 004).
+   *
+   * @see api/infra/api_scheduler/README.md
+   */
+  scheduler: {
+    /**
+     * scheduler.request - every request for a run, from every producer.
+     *
+     * NO `x-message-ttl`, deliberately, and it is the one property that differs from the
+     * shape of a workflow queue: a request that waited out a consumer outage is still the
+     * run that was due, and a TTL would turn that outage into runs which silently never
+     * happened. What bounds the queue is its length, and what catches a request the
+     * scheduler could not process is the family's dead-letter queue below — over the
+     * DEFAULT exchange, where the routing key IS the destination name, the same way every
+     * other infrastructure family here routes (the `dlx` exchange belongs to the business
+     * templates, whose queues one service owns).
+     *
+     * Without this declaration `consume()` refuses to attach a consumer at all — a queue
+     * with no declared route would have the broker DROP what the policy rejects
+     * (`docs/governance/confirmations/mq-consumer-contract.md` 002).
+     */
+    request: {
+      durable: true,
+      arguments: {
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'scheduler.dlq'
+      }
+    },
+
+    /**
+     * scheduler.workflow.events - where the scheduler learns that a run it started ENDED.
+     *
+     * The third queue bound to `monitoring.workflow.fanout`, beside `monitoring.workflow`
+     * and `delivery.workflow.events`. The owner settled it in
+     * `docs/governance/confirmations/scheduler.md` 007: the terminal event of a run
+     * (`completed` / `failed` / `discarded`) already travels on that exchange, so the
+     * scheduler reads it there rather than asking the observer over HTTP or reading a
+     * database that is not its own. No producer changes; the binding is the scheduler's own
+     * act at boot (the pattern `infra/api_delivery_endpoint/src/index.js:164` already uses),
+     * and this file only DECLARES what that queue is.
+     *
+     * THE TTL IS STATED, NOT INHERITED, and it is a property of that decision rather than a
+     * default: a fanout cannot filter, so this queue receives EVERY workflow event of the
+     * platform and the scheduler discards most of them. 300 000 ms is what
+     * `monitoring.workflow` carries on the same exchange - the sibling whose readings this
+     * one follows. What an outage longer than the TTL costs is on record: those events are
+     * lost and the run is closed by the per-schedule timeout, which 007 keeps as the
+     * backstop rather than replacing it.
+     *
+     * The route goes over the DEFAULT exchange, like every other infrastructure family
+     * here, and ends in this family's own `scheduler.dlq`. Without a declared route
+     * `consume()` refuses to attach at all (`BaseClient.js`,
+     * `CONSUMER_DEAD_LETTER_ROUTE_MISSING`; `mq-consumer-contract` 002).
+     *
+     * @see api/docs/governance/confirmations/scheduler.md 007
+     */
+    'workflow.events': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 300000,      // Stated by confirmation 007, like monitoring.workflow
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'scheduler.dlq'
+      }
+    },
+
+    /**
+     * scheduler.dlq - the END of this family's chain.
+     *
+     * Durable, capped higher, no TTL and no onward route — the three properties every
+     * dead-letter queue in this file carries, and the reason the operator's `*.dlq`
+     * dashboard finds it (`mq-consumer-contract` 003).
+     */
+    dlq: {
+      durable: true,
+      arguments: {
+        // No TTL for DLQ - messages should persist
+        'x-max-length': 50000         // Higher limit for DLQ
+      }
+    }
+  },
+
   /**
    * The full wire name of a declared entry: the section's prefix + the entry's key.
    *
@@ -1219,6 +1401,23 @@ module.exports = {
     return this.getQueueConfig('infrastructure', name);
   },
 
+  /**
+   * Get scheduler queue configuration
+   * @param {string} queueName - Queue name (e.g., 'scheduler.request')
+   * @returns {Object} Queue configuration
+   * @throws {ValidationError} If the name carries another prefix, or nothing declares it.
+   */
+  getSchedulerQueueConfig(queueName) {
+    if (!queueName.startsWith('scheduler.')) {
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not a scheduler queue - Expected: a name starting with "scheduler.". `
+          + 'Fix: call getInfrastructureQueueConfig(), which routes each prefix to the right lookup.'
+      );
+    }
+    const name = queueName.slice('scheduler.'.length);
+    return this.getQueueConfig('scheduler', name);
+  },
+
   /**
    * Get monitoring queue configuration
    * @param {string} queueName - Queue name (e.g., 'monitoring.workflow')

package/src/index.js

@@ -36,6 +36,10 @@ const {
   publishToMonitoringServices,
   isQueueUnavailableError,
 } = require('./monitoring-publish');
+const {
+  buildWorkflowInitiatedEvent,
+  publishWorkflowInitiated,
+} = require('./monitoring-initiated');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
 const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
@@ -84,6 +88,11 @@ module.exports.monitoring = {
   publishToMonitoringWorkflow,
   publishToMonitoringServices,
   isQueueUnavailableError,
+  // d.819 - the one builder of `workflow_initiated`, beside the transport half it uses
+  // (`docs/governance/confirmations/scheduler.md` 009). The gateway and the scheduler each
+  // built that event in their own words; two rails over one event is a defect by default.
+  buildWorkflowInitiatedEvent,
+  publishWorkflowInitiated,
 };
 /** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
 module.exports.queueConfig = queueConfig;
@@ -109,6 +118,18 @@ module.exports.topology = Object.freeze({
   monitoringInfrastructureHealthEventsQueue: queueConfig.queueName('monitoring', 'infrastructure.health.events'),
   /** The delivery endpoint's queue bound to that exchange, for WS push. */
   deliveryHealthEventsQueue: queueConfig.queueName('deliveryEvents', 'health.events'),
+  /**
+   * Topic exchange: the monitoring consumer's resource-changed watcher publishes here,
+   * with a routing key of the shape `resource.changed.<resource_type>`.
+   *
+   * Declared in `queueConfig` since d.619. Until then the name was a module constant on
+   * the publishing side and a required env key on the binding side
+   * (`MONITORING_RESOURCE_EXCHANGE`) — the third side of this wire with no owner, while
+   * the queue bound to it had one here since d.270.
+   *
+   * @see api/infra/api_monitoring/src/consumer/watchers/resourceChangedPublisher.js
+   */
+  monitoringResourceExchange: queueConfig.queueName('monitoring', 'resource'),
   /**
    * The delivery endpoint's queue for resource-changed events, bound to the
    * `monitoring.resource` exchange by the routing pattern `resource.changed.#`.

package/src/monitoring-initiated.js

@@ -0,0 +1,187 @@
+'use strict';
+
+/**
+ * The `workflow_initiated` event — ONE rail for every service that starts a run.
+ *
+ * Monitoring learns that a run exists from this event and from nothing else: its intake
+ * reads the run's tenancy, labels and trigger out of `workflow_initiated` and marks the
+ * run `active` on it (`api/infra/api_monitoring/src/consumer/index.js`). A service that
+ * does not file it starts runs that are invisible for their whole life.
+ *
+ * Until now two services built that event, each in its own words: the gateway
+ * (`infra/api_gateway/shared/monitoringInitiatedCopy.js`, with a redacted cookbook) and
+ * the scheduler (`infra/api_scheduler/src/publisher/workflowPublisher.js`, inline, the
+ * cookbook verbatim and no `tenant_uuid` at all). Two implementations of one concern are
+ * a defect by default (`change-discipline.md` § One rail per concern), and the owner
+ * settled which rail survives: this one, in the library that already owns the transport
+ * half of the same wire (`docs/governance/confirmations/scheduler.md` 009). Both copies
+ * are retired by their own services in the change that adopts this module — no period
+ * with both (`architecture-principles.md` §11).
+ *
+ * WHAT THIS MODULE DOES NOT DO, deliberately:
+ *
+ *   1. **It does not redact.** What is sensitive in a cookbook is known only to the
+ *      service spec in the registry, and reading that spec would give this library a
+ *      dependency on the operation specs and on `infrastructure-tools`. The caller passes
+ *      the observability copy it already built (`cookbookRedaction.js` in the gateway); a
+ *      path that cannot redact does not file the event at all, because an empty set of
+ *      sensitive fields is silent consent to an unredacted copy.
+ *   2. **It invents no value.** `service_name` and the instant are the caller's, and every
+ *      key it reads out of `_system` must EXIST — `hasOwnProperty`, not truthiness, so
+ *      `tenant_uuid: null` passes through as the explicit value it is (a webhook run has
+ *      no personal identity, and a scheduled run of the pilot writes `null` on purpose —
+ *      `docs/governance/confirmations/run-envelope-tenant-uuid.md` 001). A `|| null` here
+ *      would hide a broken envelope instead of reporting it (`architecture-principles.md`
+ *      §3).
+ *
+ * @see api/docs/governance/confirmations/scheduler.md 009
+ * @see api/docs/biz/70-contracts/monitoring-events.md
+ * @see ./monitoring-publish.js — the transport half: the queue, the fanout, the fail-safe
+ */
+
+const { assertLogger } = require('@onlineapps/logger-contract');
+const { publishToMonitoringWorkflow } = require('./monitoring-publish');
+
+/** Starting a run is not a step of the cookbook; it has its own constant coordinates. */
+const STEP_ID = 'workflow_start';
+const STEP_INDEX = -1;
+/** The event's own two words, which the monitoring intake matches on. */
+const EVENT_TYPE = 'initiated';
+const STATUS = 'initiated';
+
+/** The keys of `_system` this event carries, each of which must exist on the envelope. */
+const REQUIRED_SYSTEM_KEYS = Object.freeze(['tenant_id', 'tenant_uuid']);
+
+/**
+ * The body of the `initiated` event — exactly these keys and no others.
+ *
+ * @param {Object} args
+ * @param {string} args.workflowId - the id of the run this event reports.
+ * @param {Object} args.redactedCookbook - the observability copy of the unified cookbook,
+ *   ALREADY redacted by the caller; it travels as it arrived.
+ * @param {string} args.serviceName - the platform name of the service filing the event;
+ *   the monitoring intake refuses an event that names no publisher (`service_name_missing`).
+ * @param {string} args.timestamp - the instant the run started, ISO-8601. The caller's,
+ *   not a second reading of the clock here: the run and the row observing it then say the
+ *   same thing.
+ * @returns {Object} the message for `monitoring.workflow`.
+ * @throws {Error} when an argument is missing, or the envelope does not carry what this
+ *   event states about it.
+ */
+function buildWorkflowInitiatedEvent({ workflowId, redactedCookbook, serviceName, timestamp } = {}) {
+  if (typeof workflowId !== 'string' || workflowId.trim() === '') {
+    throw new Error(
+      '[monitoring-initiated] Missing workflow_id - Expected: the id of the run this event '
+        + 'reports, as a non-empty string. Fix: pass workflowId of the run being published.'
+    );
+  }
+  if (typeof serviceName !== 'string' || serviceName.trim() === '') {
+    throw new Error(
+      '[monitoring-initiated] Missing service_name - Expected: the platform name of the service '
+        + 'filing this event; the monitoring intake refuses an event that names no publisher '
+        + '(service_name_missing). Fix: pass config.serviceName.'
+    );
+  }
+  if (typeof timestamp !== 'string' || timestamp.trim() === '') {
+    throw new Error(
+      '[monitoring-initiated] Missing timestamp - Expected: the instant the run started, as an '
+        + 'ISO-8601 string taken from the run itself, so the run and the row observing it say the '
+        + 'same thing. Fix: pass the envelope\'s own instant, not a new Date() read here.'
+    );
+  }
+  if (!redactedCookbook || typeof redactedCookbook !== 'object') {
+    throw new Error(
+      '[monitoring-initiated] Missing cookbook - Expected: the redacted observability copy of the '
+        + 'unified cookbook. Fix: pass the copy the caller built with its own redaction '
+        + '(a path that cannot redact does not file this event at all).'
+    );
+  }
+
+  const system = redactedCookbook._system;
+  if (!system || typeof system !== 'object') {
+    throw new Error(
+      '[monitoring-initiated] Cookbook carries no _system - Expected: the unified cookbook with '
+        + 'its system metadata, which is where the intake reads the run\'s tenancy, labels and '
+        + 'trigger. Fix: build the copy from the unified cookbook the run was published with.'
+    );
+  }
+
+  for (const key of REQUIRED_SYSTEM_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(system, key)) {
+      throw new Error(
+        `[monitoring-initiated] Cookbook _system carries no ${key} - Expected: every entry path `
+          + 'writes it explicitly (a value, or null where the path has none - a webhook run proves '
+          + 'itself by signature, a scheduled run of the pilot has no personal identity). '
+          + `Fix: set _system.${key} where the unified cookbook is built.`
+      );
+    }
+  }
+
+  return {
+    event_type: EVENT_TYPE,
+    workflow_id: workflowId,
+    service_name: serviceName,
+    step_index: STEP_INDEX,
+    step_id: STEP_ID,
+    cookbook: redactedCookbook,
+    status: STATUS,
+    tenant_uuid: system.tenant_uuid,
+    tenant_id: system.tenant_id,
+    timestamp
+  };
+}
+
+/**
+ * File the `initiated` event. NEVER throws — a lost copy is reported, not raised.
+ *
+ * It is observability about a run that has already happened: refusing the run because the
+ * observer could not be told would trade a real effect for a record of it. Both services
+ * that build this event today made the same decision in their own words, and it moves here
+ * with the event. A missing logger is the one exception, and it is the transport half's
+ * rule (`monitoring-publish.js`): without a logger the promise "every failure is reported"
+ * cannot hold, so the call refuses instead of dropping events in silence.
+ *
+ * @param {Object} args
+ * @param {Object} args.mqClient - the connected `BaseClient`.
+ * @param {Object} args.logger - the service logger; REQUIRED.
+ * @param {string} args.workflowId
+ * @param {Object} args.redactedCookbook
+ * @param {string} args.serviceName
+ * @param {string} args.timestamp
+ * @param {Object} [args.context] - extra context for the log lines.
+ * @returns {Promise<boolean>} whether the event reached the broker.
+ */
+async function publishWorkflowInitiated({
+  mqClient,
+  logger,
+  workflowId,
+  redactedCookbook,
+  serviceName,
+  timestamp,
+  context = {}
+} = {}) {
+  assertLogger(
+    'publishWorkflowInitiated',
+    logger,
+    'a copy monitoring never received is reported instead of silently returning false',
+    'pass the logger your service already built'
+  );
+
+  try {
+    const event = buildWorkflowInitiatedEvent({ workflowId, redactedCookbook, serviceName, timestamp });
+    return await publishToMonitoringWorkflow(mqClient, event, logger, { workflowId, ...context });
+  } catch (error) {
+    logger.warn('[monitoring-initiated] Failed to publish workflow_initiated to monitoring', {
+      ...context,
+      workflow_id: workflowId,
+      service_name: serviceName,
+      error: error.message
+    });
+    return false;
+  }
+}
+
+module.exports = {
+  buildWorkflowInitiatedEvent,
+  publishWorkflowInitiated
+};

package/src/transports/rabbitmqClient.js

@@ -525,13 +525,52 @@ class RabbitMQClient extends EventEmitter {
   }
 
   /**
-   * Get current consumer state
-   * @returns {Object} Consumer state information
+   * THE definition of "this client's consumer is attached to that queue".
+   *
+   * The tag is the one fact that is about THIS client: the broker gives it to
+   * the attachment it created, and since d.386b / d.605 the entry carries it
+   * only while that attachment exists — a refused re-registration and a cancel
+   * sent by the broker both drop it while the consumer stays TRACKED, because
+   * the next recovery must find it on the list.
+   *
+   * It is a method rather than an expression repeated twice for the reason
+   * `change-discipline.md` § One rail per concern states: until d.613
+   * `getConsumerState()` answered from `_activeConsumers.keys()` and
+   * `_performHealthCheck()` from the tag, so one file held two definitions of
+   * "active" — and the cheap synchronous reader, the one a service and an
+   * operator actually read, was the one that answered about a consumer the
+   * broker had already cancelled.
+   *
+   * @param {Object|undefined} consumerInfo - The entry `_activeConsumers` holds
+   * @returns {boolean}
+   * @private
+   */
+  _isConsumerAttached(consumerInfo) {
+    return typeof consumerInfo?.consumerTag === 'string' && consumerInfo.consumerTag !== '';
+  }
+
+  /**
+   * Get current consumer state.
+   *
+   * `tracked` counts the consumers this client would restore; `active` names the
+   * ones that are ATTACHED right now (`_isConsumerAttached()`, the same question
+   * `_performHealthCheck()` asks). `tracked > active.length` is therefore the
+   * cheap, synchronous statement that this client takes no message off some
+   * queue it registered — the state
+   * `docs/operations/rabbitmq-connection-recovery-troubleshooting.md` sends an
+   * operator here to read, and which the queue-name list could not carry.
+   *
+   * @returns {{tracked: number, active: string[]}} Consumer state information
    */
   getConsumerState() {
+    const active = [];
+    for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
+      if (this._isConsumerAttached(consumerInfo)) active.push(queue);
+    }
+
     return {
       tracked: this._activeConsumers.size,
-      active: Array.from(this._activeConsumers.keys())
+      active
     };
   }
 
@@ -1858,54 +1897,160 @@ class RabbitMQClient extends EventEmitter {
     if (this._activeConsumers.size > 0) {
       this._logger.info(`[RabbitMQClient] [mq-client-core] Re-registering ${this._activeConsumers.size} consumers...`);
       for (const [queue, consumerInfo] of this._activeConsumers.entries()) {
-        try {
-          await this._prepareQueueForConsume(queue, {
-            durable: consumerInfo.options.durable,
-            queueOptions: consumerInfo.options.queueOptions
-          });
-
-          // The consumer's prefetch is re-applied here for the same reason the
-          // queue step is: the channel is new, and QoS lives on the channel.
-          await this._applyConsumerPrefetch(queue, consumerInfo.options.prefetch);
-
-          const consumeResult = await this._consumerChannel.consume(
-            queue,
-            consumerInfo.handler,
-            { noAck: consumerInfo.options.noAck }
-          );
-          consumerInfo.consumerTag = consumeResult.consumerTag;
+        if (await this._reRegisterConsumer(queue, consumerInfo)) {
           reRegistered++;
-          this._logger.info(`[RabbitMQClient] [mq-client-core] \u2713 Re-registered consumer for queue: ${queue} (consumerTag: ${consumeResult.consumerTag})`);
-        } catch (err) {
+        } else {
           failed++;
-          this._logger.error(`[RabbitMQClient] [mq-client-core] Failed to re-register consumer for queue ${queue}:`, err.message);
-          // The consumer STAYS tracked. Whatever refused it — a 406 against the
-          // owner's declaration, a missing infrastructure queue, a channel that
-          // went away mid-flight — is a condition somebody fixes at its source,
-          // and the next recreate must find the consumer still on the list.
-          //
-          // Its TAG does not stay, and the two are not the same fact (d.386b). A
-          // consumer tag names an attachment on ONE channel; the channel that
-          // issued this one is gone and the new one refused to re-attach, so the
-          // string the entry carried names nothing on the broker. Two readers
-          // took it for an attachment that exists: `_performHealthCheck()` counts
-          // `active` by "is the tag set", so a client whose only consumer had
-          // just been refused reported `healthy: true` and `1/1 consumers active`
-          // — the false OK d.386 exists to end, one layer below where d.386 could
-          // reach it; and `cancelConsumer()` sent `basic.cancel` with it, asking
-          // the broker to stop a consumer it does not hold.
-          consumerInfo.consumerTag = null;
-          // The broker's own code is what a listener acts on (406 = the queue
-          // exists with different arguments), and the rail wraps it in a typed
-          // error, so it is read from the cause when the wrapper carries none.
-          const code = err.code !== undefined ? err.code : (err.cause ? err.cause.code : undefined);
-          this.emit('consumer:re-registration:failed', { queue, error: err.message, code });
         }
       }
     }
     return { reRegistered, failed };
   }
 
+  /**
+   * Re-attach ONE tracked consumer on the current consumer channel.
+   *
+   * This is the body of the loop above, given a name in d.605 because a second
+   * event needs exactly it: `basic.cancel` from the broker takes ONE consumer
+   * away while every other one stays attached, so re-running the whole loop
+   * would re-attach consumers that never lost their place — a second
+   * `basic.consume` for each of them on the broker. One rail, one set of
+   * consequences (`change-discipline.md` § One rail per concern).
+   *
+   * Everything a first `consume()` does is done here: the queue is classified,
+   * declared or checked by `_prepareQueueForConsume()` — so an owned business
+   * queue is re-declared and an unowned infrastructure queue is only checked,
+   * its absence answered with `CONSUMER_QUEUE_MISSING` rather than a silent
+   * creation — and the prefetch is re-applied, because QoS lives on the channel.
+   *
+   * @param {string} queue - Queue name
+   * @param {Object} consumerInfo - The entry `_activeConsumers` holds for it
+   * @returns {Promise<boolean>} `true` when the consumer is attached again
+   * @private
+   */
+  async _reRegisterConsumer(queue, consumerInfo) {
+    try {
+      await this._prepareQueueForConsume(queue, {
+        durable: consumerInfo.options.durable,
+        queueOptions: consumerInfo.options.queueOptions
+      });
+
+      // The consumer's prefetch is re-applied here for the same reason the
+      // queue step is: the channel is new, and QoS lives on the channel.
+      await this._applyConsumerPrefetch(queue, consumerInfo.options.prefetch);
+
+      const consumeResult = await this._consumerChannel.consume(
+        queue,
+        consumerInfo.handler,
+        { noAck: consumerInfo.options.noAck }
+      );
+      consumerInfo.consumerTag = consumeResult.consumerTag;
+      this._logger.info(`[RabbitMQClient] [mq-client-core] ✓ Re-registered consumer for queue: ${queue} (consumerTag: ${consumeResult.consumerTag})`);
+      return true;
+    } catch (err) {
+      this._logger.error(`[RabbitMQClient] [mq-client-core] Failed to re-register consumer for queue ${queue}:`, err.message);
+      // The consumer STAYS tracked. Whatever refused it — a 406 against the
+      // owner's declaration, a missing infrastructure queue, a channel that
+      // went away mid-flight — is a condition somebody fixes at its source,
+      // and the next recreate must find the consumer still on the list.
+      //
+      // Its TAG does not stay, and the two are not the same fact (d.386b). A
+      // consumer tag names an attachment on ONE channel; the channel that
+      // issued this one is gone and the new one refused to re-attach, so the
+      // string the entry carried names nothing on the broker. Two readers
+      // took it for an attachment that exists: `_performHealthCheck()` counts
+      // `active` by "is the tag set", so a client whose only consumer had
+      // just been refused reported `healthy: true` and `1/1 consumers active`
+      // — the false OK d.386 exists to end, one layer below where d.386 could
+      // reach it; and `cancelConsumer()` sent `basic.cancel` with it, asking
+      // the broker to stop a consumer it does not hold.
+      consumerInfo.consumerTag = null;
+      // The broker's own code is what a listener acts on (406 = the queue
+      // exists with different arguments), and the rail wraps it in a typed
+      // error, so it is read from the cause when the wrapper carries none.
+      const code = err.code !== undefined ? err.code : (err.cause ? err.cause.code : undefined);
+      this.emit('consumer:re-registration:failed', { queue, error: err.message, code });
+      return false;
+    }
+  }
+
+  /**
+   * The broker cancelled one of this client's consumers.
+   *
+   * `basic.cancel` sent BY THE BROKER is not an error frame and does not touch
+   * the channel or the connection: the queue was deleted, or the broker moved it
+   * (`x-cancel-on-ha-failover`). Nothing else in this client hears it — the
+   * channel handlers listen for `error` and `close`, and both stay silent — so
+   * this method is the whole of the client's answer, and until d.605 that answer
+   * was nothing at all.
+   *
+   * Three things happen, in this order:
+   *
+   *   1. the TAG is dropped, first, because it is the one fact
+   *      `_performHealthCheck()` reads to answer "is THIS client's consumer
+   *      attached" (d.386b). Dropping it before anything else leaves no window in
+   *      which the check reports an attachment the broker has already cancelled;
+   *   2. the loss is stated at ERROR level, naming the queue and the cancelled
+   *      tag. A consumer that stops reading a queue is not a debug-level event,
+   *      and the record is what tells an operator which queue went quiet;
+   *   3. the consumer is re-attached through `_reRegisterConsumer()`, the rail a
+   *      channel recreate already uses. A refusal there keeps the consumer
+   *      tracked with no tag and travels on `consumer:re-registration:failed` —
+   *      which is why this method introduces no event and no public method of its
+   *      own: every state it can reach is a state the package already reports.
+   *
+   * @param {string} queue - The queue whose consumer the broker cancelled
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _onBrokerCancel(queue) {
+    if (this._closedByCaller) {
+      // An intentional close is not a fault — the doctrine `disconnect()` states
+      // and both channel handlers already follow.
+      this._logger.debug(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Broker cancelled the consumer for queue "${queue}" while the client was being closed by its caller - no alarm, no re-attachment`
+      );
+      return;
+    }
+
+    const consumerInfo = this._activeConsumers.get(queue);
+    const cancelledTag = consumerInfo ? consumerInfo.consumerTag : null;
+
+    if (consumerInfo) {
+      consumerInfo.consumerTag = null;
+    }
+
+    this._logger.error(
+      `[RabbitMQClient] Consumer cancelled by the broker - the consumer on queue "${queue}" `
+        + `(consumerTag: ${cancelledTag}) was stopped by the BROKER, not by this client: the queue `
+        + 'was deleted, or the broker moved it (x-cancel-on-ha-failover). '
+        + 'Expected: a consumer stays attached until cancelConsumer() or disconnect(). '
+        + 'Fix: none here - the client re-attaches it on the rail a channel recreate uses; if that '
+        + 'is refused, the consumer stays tracked with no tag, performHealthCheck() reports this '
+        + 'client unhealthy and names the queue, and consumer:re-registration:failed carries the '
+        + 'broker reason.',
+      { queue, consumerTag: cancelledTag }
+    );
+
+    if (!consumerInfo) {
+      // The client no longer holds this consumer, so there is nothing to
+      // re-attach and no state left to correct. The loss is still stated above.
+      return;
+    }
+
+    if (!this._isChannelAlive(this._consumerChannel)) {
+      // Re-attaching on a dead channel is not this method's job: the channel
+      // recovery re-registers every tracked consumer when it recreates the
+      // channel (d.262), and the consumer stays tracked for exactly that.
+      this._logger.warn(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Consumer for queue "${queue}" stays tracked and unattached - the consumer channel is not alive, so the channel recovery re-registers it`
+      );
+      return;
+    }
+
+    await this._reRegisterConsumer(queue, consumerInfo);
+  }
+
   /**
    * Disconnects: closes channel and connection.
    * @returns {Promise<void>}
@@ -2061,8 +2206,10 @@ class RabbitMQClient extends EventEmitter {
             // this client's and everybody else's alike, so it cannot say whether
             // the one asking is among them. The tag can: it is the name the
             // broker gave THIS client's attachment, and since d.386b it is set
-            // only while that attachment exists.
-            if (consumerInfo.consumerTag) {
+            // only while that attachment exists. The question is asked through
+            // `_isConsumerAttached()` — the one definition `getConsumerState()`
+            // now reads too (d.613).
+            if (this._isConsumerAttached(consumerInfo)) {
               health.consumers.active++;
             } else {
               health.consumers.inactive.push(queue);
@@ -3290,9 +3437,11 @@ class RabbitMQClient extends EventEmitter {
     // leaves exactly those without a route of their own, because a dead-letter
     // route on a dead-letter queue is a loop or a chain with no end
     // (`mq-consumer-contract` 002 point 2, 003 point 2). Until d.452 the gate
-    // asked only the first question, so the operator's own queue was
-    // unconsumable and its reader — the delivery dispatcher — could not attach
-    // at all. The second question is derived from the templates
+    // asked only the first question, so the operator's own queue could not be
+    // consumed through this library at all. Who reads such a queue is that
+    // service's own fact, not this file's —
+    // @see api/infra/api_monitoring/src/consumer/deadLetterPeek.js
+    // The second question is derived from the templates
     // (`queueConfig.isDeadLetterTarget()`), never from a list of names, so it
     // cannot fall behind them; every other queue with no route is refused
     // exactly as before, with the same sentence.
@@ -3532,7 +3681,21 @@ class RabbitMQClient extends EventEmitter {
       // Wrap handler to track message processing and prefetch utilization
       const messageHandler = async (msg) => {
         if (msg === null) {
-          return; // Consumer cancellation
+          // `null` is not a message. It is `basic.cancel` FROM THE BROKER,
+          // handed to this callback by amqplib (`handleCancel()` →
+          // `dispatchMessage(fields, null)`), and it is the only way a consumer
+          // learns that 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`).
+          //
+          // Until d.605 the answer was this bare `return`. Nothing was logged,
+          // the tag stayed set — so `_performHealthCheck()` went on counting the
+          // consumer as attached — and nothing re-attached it. The service
+          // reported itself healthy while no message was taken off the queue,
+          // which is the failure `automation-gates.md` §5 calls a defect of the
+          // same severity as a wrong result.
+          await this._onBrokerCancel(queue);
+          return;
         }
 
         // IMPORTANT: