@onlineapps/mq-client-core 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-09-15
+
+### Added — `topology` nese i tři telemetrické fronty (d.461)
+
+`module.exports.topology` vystavuje `telemetryLogsQueue`, `telemetryMetricsQueue`,
+`telemetryTracesQueue`, složené ze sekce `telemetry` v `queueConfig` (tatáž
+deklarace, ne kopie). Monitoring, jediný konzument těch front, může zrušit
+svoje privátní literály a číst jména odtud; `src/config/queueConfig` zůstává
+interní cestou. README § topology popisuje celý export.
+
+### Fixed — `performHealthCheck()` hlásí stav, nemění ho (d.467)
+
+Kontrola spouštěla obnovovací cyklus bezpodmínečně: `_reconnectWithBackoff()`
+nastaví `_reconnecting` synchronně, `isConnected()` ho čte, a tak zdravý klient
+reportoval vlastní vedlejší účinek (`healthy: false`, `Connection is closed or
+missing`, `isConnected()` true → false) a obnova skutečně vyměnila živý socket
+za nový. Teď se obnova spouští jen u odstaveného klienta — otázku klade jednomu
+zdroji živosti (`isConnected()` nad `_connectionAlive`), tam, kde ji kladou
+`_ensurePublisherChannel()` a `_ensureConsumerChannel()`. Líný kontrakt d.339
+zůstává: odstavený klient se health checkem dál vrací do provozu. Repro nad
+živým brokerem s `reconnectEnabled: true` (starší sady o health checku stavěly
+klienta s `reconnectEnabled: false`, proto vadu nikdy neviděly).
+
+### Fixed — `redactUrl` se bere z `@onlineapps/logger-contract`, lokální kopie pryč (d.455)
+
+`src/utils/redactCredentials.js` držel vlastní `redactUrl`
+a `UNPARSEABLE_PLACEHOLDER`. Od `@onlineapps/logger-contract` 1.2.0 (d.453) je
+vlastní core vrstva, takže je tenhle modul importuje a `src/index.js` je
+**re-exportuje identitou** — veřejné API se nemění, dependants dál píší
+`require('@onlineapps/mq-client-core').redactUrl`. Zdejší zůstává jen
+`redactConnectionTarget`: fail-fast obal nad deklarovaným config klíčem `host`,
+který v core vrstvě nemá co dělat (vyhazuje tam, kde `redactUrl` vrací
+placeholder — d.292 §2/§3).
+
+Čtyři otázky ke smazané deklaraci (`change-discipline.md` § Removing):
+
+1. **Proč vznikla** — d.448 sjednotila sémantiku (celé userinfo pryč, ne jen
+   heslo) poté, co se na `api_service_hello` 2026-09-07 změřilo heslo brokeru
+   ve stdout a přes monitoring i v Loki. Core domov tehdy neexistoval, takže
+   funkce zůstala tady.
+2. **Která část koncepce ji nesla** — `change-discipline.md` § One rail per
+   concern ji naopak zakazuje: tři kopie jednoho pravidla (tady,
+   `service-common`, `conn-orch-registry`). Ta část koncepce stojí dál.
+3. **Proč ji dnes nikdo nečte** — `@onlineapps/logger-contract` 1.2.0 exportuje
+   `redactUrl` i `UNPARSEABLE_PLACEHOLDER` a všechny tři dependants míří na něj.
+4. **Je náhrada koncepčnější** — ano: `logger-contract` je L1 bez `@onlineapps`
+   závislostí, takže na něj dosáhne i kategorie `orchestration`, které brána G7
+   odmítá pin do kategorie `runtime`.
+
+**Změna chování na jednom okraji:** zdejší kopie vracela `parsed.href` bez
+úpravy, logger-contract navíc utne lomítko, které WHATWG dopisuje prázdné cestě
+u *special* schemat (`http`, `https`, `ws`, `wss`, `ftp`, `file`). Na `amqp` /
+`amqps` — jediných, se kterými tenhle klient pracuje — jsou obě implementace
+bajtově shodné; `http://u:p@host:8080` nově vrátí `http://host:8080` místo
+`http://host:8080/`.
+
+Sada `tests/unit/redact-credentials.test.js`: blok se sémantikou `redactUrl`
+case-by-case odešel (drží ho logger-contract), místo něj drží identitu
+re-exportu, nepřítomnost druhé koleje v `utils/redactCredentials`
+(`Object.keys` = `['redactConnectionTarget']`), shodu výstupu
+`redactConnectionTarget` s `loggerContract.redactUrl` a cestu selhání.
+Zmizely i mrtvé citace na `shared/service-common/src/redactUrl.js`
+a `shared/connector/conn-orch-registry/src/redactUrl.js` — oba soubory už
+neexistují.
+
+## [3.0.1] — 2026-09-14
+
+- **Fixed: `consume()` accepts a TERMINAL queue — one this configuration dead-letters TO — instead of demanding a dead-letter route it must not have.** The d.259 gate refuses a queue for which `queueConfig` declares no `x-dead-letter-exchange`/`-routing-key`, because the policy ends a spent message with `nack(requeue=false)` and the broker drops what it cannot move. True of every working queue — and false of the queues that RECEIVE those moves: `workflow.failed` is named in `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`, `<service>.dlq` by every business template, `workflow.dlq` and `delivery.dlq` by their own families, and the confirmed topology leaves exactly those without a route of their own (`api/docs/governance/confirmations/mq-consumer-contract.md` 002 point 2, 003 point 2 — "workflow.failed and workflow.dlq themselves keep no route"). A dead-letter route on a dead-letter queue is a loop or a chain with no end. So `workflow.failed` — the operator's queue, read by the delivery dispatcher — was unconsumable: `[BaseClient] Cannot consume from queue "workflow.failed": queueConfig declares no dead-letter route`. The gate now asks a second question, `queueConfig.isDeadLetterTarget(queue)`, **derived from the templates** (the set of every declared `x-dead-letter-routing-key`, `{service}` placeholder read through the same `templateShape()` the business templates use) rather than from a list of names that would have to be edited in step with them — the defect d.278 removed from `matchBusinessTemplate()`. The `.dlq` family needs no rule of its own: every `.dlq` this configuration declares is already the target of a declared routing key (measured 2026-09-14). Every other queue with no route is refused exactly as before, with the same sentence. A message that spends its budget on a terminal queue is rejected the same way and then DROPPED by the broker — the end of the chain is the end — never requeued for ever, and the loss is now logged at error level (`Message discarded on terminal queue "<queue>"`, with the queue, the attempts and the error) before the `message_dlq` event is published. Tests: new unit `consume-terminal-queue.test.js` (10 — the derivation from the declared keys, the terminal names and the non-terminal control, `consume('workflow.failed')` and `consume('<svc>.dlq')` attaching, the three refusals that must not change with the refusal verbatim, the discard with its log line and meta, and a routed queue as the control that says nothing about a discard); integration `dead-letter-route-required.integration.test.js` (+2 against the live broker: a message rejected from `<svc>.queue` reaches `<svc>.dlq` and is DELIVERED to a consumer there with `x-death[0].reason = 'rejected'`, and a handler failing on that terminal queue leaves the queue empty with no second delivery after 2 s — the drop no mock can measure). Three tests that encoded the old rule follow the new one: the `<svc>.dlq` refusal leg of `consume-dead-letter-route-required.test.js` (its subject moved to the new file), and the two integration control queues that used a dead-letter queue as "the queue with no route" (`delivery-events-lookup` → `monitoring.workflow`, `queue-declaration-options-one-rail` → `<svc>.events`).
+
+## [3.0.0] — 2026-09-14
+
 - **Changed (BREAKING for a reader of the log, not for a caller): the credential redaction removes the WHOLE userinfo, not just the password.** `utils/redactCredentials.js` masked the password (`amqp://oa_dev:***@queuer:5672`) and kept the account name, while the platform's two other redactors — `shared/service-common/src/redactUrl.js` (d.245/d.245b) and `shared/connector/conn-orch-registry/src/redactUrl.js` (d.446, whose header says plainly that it stayed local because this package masked the password only) — drop the userinfo entirely. One concern, two semantics, which is two rails (`.claude/rules/change-discipline.md` § One rail per concern). The platform one wins: `amqp://queuer:5672/vhost?heartbeat=30`, the account name gone with the password, because a name is the other half of the same credential and a log line needs neither. A value that is not a parseable URL is answered with `<unparseable-url>` instead of being echoed — previously a non-URL string came back verbatim (`api_services_queuer`) or with a `***@` prefix, and an unparseable value is exactly the case where nobody can say whether it holds a credential. `redactConnectionTarget()` still THROWS on a non-string: it guards a declared config key, where a wrong type is a boot-time defect. Tests: unit `redact-credentials.test.js` (rewritten to the new semantics, +6 over the package: the userinfo cases, the transport's `?heartbeat` query as a control, the placeholder cases and the export identity), `connect-credentials-not-logged.test.js` and `one-owner-a-floor-down.test.js` (both now assert the account name is absent too), integration `credential-redaction.integration.test.js` (+2: the LIVE broker accepts the real credential while no logger argument carries either half of it, and a real 403 refusal leaks nothing into the error, the stack or the log) (d.448).
 - **Added:** `redactUrl` and `UNPARSEABLE_PLACEHOLDER` are exports of `src/index.js`. The dependants that render an AMQP URL into a log line or an error message (`conn-orch-registry`, `conn-infra-mq`) each carry a local copy of the same function; a copy can only be replaced by an import if the package declares one (d.448).
 - **Fixed:** a reconnect wait ends only on an error that carries NO publish classification. d.435 taught `_waitForReconnection()` to skip a RETRYABLE publish failure, which left the same defect standing one class of error further out: a `PermanentPublishError` or a `QueueNotFoundError` from a concurrent publish still rejected every waiter, although "no retry will help this message" says nothing about whether the link is coming back. The condition is now the PRESENCE of the classification, not its verdict — `utils/publishErrors.js` sets `retryable` on every error it produces, so an error that never went through that rail carries none, and that absence is the whole test (plus the transport's own typed close, which never ended the wait). No second list of codes. Tests: unit `wait-for-reconnection-not-ended-by-a-foreign-publish.test.js` (+4, both permanent classifications built by the real rail, controls for an unclassified error and for the typed close), integration `…integration.test.js` (+1: the live broker refuses a publish to a name no declaration owns with a real 404, and that real `QueueNotFoundError` is put on the channel during a real outage — a permanent classification cannot arise while the link is down, where everything classifies transient) (d.435b).
@@ -30,7 +101,7 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 - **Removed (BREAKING: `persistentBufferEnabled` and `persistentRedisClient` are refused by name):** the persistent publish buffer, which never existed. `buffer/RedisBuffer.js` was a placeholder — `add()` stored nothing, `flush()` returned 0 — and `MessageBuffer.add()` returned after that branch without falling back (the stub did not throw, so there was nothing to fall back from). With `persistentBufferEnabled: true` a critical-priority message that failed transiently was therefore DROPPED, while the same message at normal priority was held in memory and replayed after the reconnect: the key inverted its own promise. The package's own concept node already said so in writing (`docs/architecture/mq-publish-reliability.md` § Buffering: "RedisBuffer is a stub … Leave persistentBufferEnabled at its default") — a mechanism documented as not existing (`automation-gates.md` §5). The four questions of `change-discipline.md` § Removing are answered in the commit and in `tests/unit/persistent-buffer-removed.test.js`: it arrived with the publish-reliability layer (`3588b148`) as a hook for a future extension; no part of the concept requires persistence; nothing ever set either key outside one test (measured across `api`, `api_biz`, `infra`, `fe_adminui`, 2026-09-14); and what stands in its place — one in-memory buffer holding every priority — is more conceptual than a switch that loses messages. `getBufferState()` is therefore `{ size, inMemory }` (the `persistent` count could only ever be 0), `MessageBuffer.flush()` returns the number replayed instead of `{ inMemory, persistent }`, and both key names now fail the constructor with a sentence saying the mechanism is gone rather than a name to rename them to (d.343).
 - **Fixed (BREAKING: `publish()` no longer creates the exchange it publishes to, and `options.exchangeType` is gone):** an exchange is NAMED by a publisher, never declared by one. `_publishOnce()` asserted the exchange before EVERY publish, with arguments it made up on the spot — the type from `options.exchangeType || 'direct'` and the durability from the PUBLISHING client's own config — so the publisher decided the topology and two differently configured publishers declared one exchange two ways. Measured on the live broker: a client configured `durable: false` publishing to a fanout its owner declared durable is refused with `406 PRECONDITION-FAILED … inequivalent arg 'type' … received 'direct' but current is 'fanout'`, on a message that had nothing wrong with it. The owner's decision names this exact defect one object down — "the endpoint's own `{ durable: true }` assert is a second declaration and already yields 406 against the library's" (`docs/governance/confirmations/mq-consumer-contract.md` 003, point 4). Exchanges are declared once in `config/queueConfig.js` and asserted by their owners (measured: every exchange the platform publishes to already is), so an exchange nobody declared is now a broker-side 404 on the publish rather than an exchange invented by whoever published first — the same rule as `README.md` § Queue ownership states for queues. `options.exchangeType` existed for that one assert and left with it, including its only caller inside the library, `monitoring-publish.js` (d.342).
 - **Added:** `BaseClient.isConnectionFatal()` and `BaseClient.performHealthCheck()` — the last two methods a service could not reach. Same hole d.296 closed for the five counters, different question: both were methods of the TRANSPORT alone, and `new RabbitMQClient` is called in exactly one place in the whole workspace (`transports/transportFactory.js`, inside this library), so a service holding a `BaseClient` saw `isConnected() === false` with no way to learn whether to wait or to restart, and the manual probe `docs/architecture/rabbitmq-channel-lifecycle.md` documents was callable on nothing it holds. The transport keeps the computation; the client delegates. `performHealthCheck()` follows the five counters and refuses before `connect()` built a transport; `isConnectionFatal()` deliberately does not — a client that never connected has a true answer (no), and a healthcheck must not be answered by an exception. `onChannelClose` stays the transport's: it is an internal hook on a channel's lifetime, not a question a service asks. The d.296 gate now covers both new counterparts (d.341).
-- **Removed (BREAKING for a caller importing the transport):** `require('@onlineapps/mq-client-core').RabbitMQClient`. The four questions, answered before deleting: it came in with the library's extraction (`7a47b2fa`), as part of publishing the module's surface; no part of the concept ever carried it — `docs/architecture/mq-publish-reliability.md` describes the transport as what `BaseClient` selects, never as what a caller constructs; nothing reads it because `transportFactory` has been the one constructor since that same commit (measured across `api_biz/*`, `infra/*`, `shared/*`: zero uses outside this package); and what stands in its place is more conceptual, not less — the factory picks the transport from `type` (Configuration Over Convention), while constructing it by hand bypasses config composition, schema validation and the instance registry `disconnectAll()` is built on (d.341).
+- **Removed (BREAKING for a caller importing the transport):** `require('@onlineapps/mq-client-core').RabbitMQClient`. The four questions, answered before deleting: it came in with the library's extraction (`7a47b2fa`), as part of publishing the module's surface; no part of the concept ever carried it — `docs/architecture/mq-publish-reliability.md` describes the transport as what `BaseClient` selects, never as what a caller constructs; nothing reads it because `transportFactory` has been the one constructor since that same commit (measured across `api_biz/*`, `infra/*`, `shared/*`: zero uses outside this package — that scope skipped `api/tests/**`, which carried 13 uses in 3 suites; INFRA retires them as a second rail, measured 2026-09-15); and what stands in its place is more conceptual, not less — the factory picks the transport from `type` (Configuration Over Convention), while constructing it by hand bypasses config composition, schema validation and the instance registry `disconnectAll()` is built on (d.341).
 - **Fixed (BREAKING: a spent reconnect budget is no longer the end of the client):** after the attempt budget of one recovery cycle runs out against a broker that never answered, the client **stands down** — `connection:standby` with `{ cycle, cyclesMax, attempts, lastError, timestamp }`, no timer, no socket, `isConnected()` false and `isConnectionFatal()` FALSE — and the next `publish()`, `consume()` or `performHealthCheck()` starts the next cycle. Nothing polls in between, so a client nobody uses costs nothing while the broker is away. Until now one spent budget set the fatal flag and the client refused every operation for the life of the process, which the README taught as "dead until the process restarts"; that is the "give up forever" the owner forbade (`docs/governance/confirmations/mq-client-lifecycle-contract.md` 001 point 3), and it meant a broker restart longer than `maxReconnectAttempts × reconnectMaxDelay` needed a process restart to undo. One rail: the lazy retry re-enters the same `_reconnectWithBackoff()`, there is no second loop (d.339).
 - **Added:** `maxReconnectCycles` (default 3, env `RABBITMQ_MAX_RECONNECT_CYCLES`) — how many recovery cycles the client runs before the connection IS permanently lost. It is what keeps the lazy retry finite; the value is the one `maxDeliveryAttempts` already answers the same question with (how many whole retries one thing gets), and two answers to one question must not differ (d.339).
 - **Changed (BREAKING for a caller reading the fatal error):** `connection:fatal` says WHICH of the two endings it is — `reason: 'broker-refused'` or `'cycles-spent'` — and carries `cycles` beside `attempts`, with a different sentence for each. A broker that ANSWERED and refused (403 `ACCESS-REFUSED`, 530 `NOT-ALLOWED`, 406 `PRECONDITION-FAILED`) is fatal on the spot, with no further attempt spent on an answer that cannot change: measured against amqplib 0.10.9 on the live broker (2026-09-14), such a refusal arrives as a plain `Error` with `code` undefined and the AMQP reply code rendered into the message, so the reply code is what is read — the broker's protocol constant, never wording invented here. Not recognised, and said rather than implied: a wrong vhost reaches amqplib as `Expected ConnectionOpenOk; got <ConnectionClose channel:0>`, so it is treated as an outage and ends at the cycle cap (d.339).

package/README.md

@@ -216,6 +216,24 @@ broker cannot be asked, because `checkQueue()` answers with `queue.declare-ok`,
 carries `{ queue, messageCount, consumerCount }` and no arguments (measured, 2026-09-12).
 `queueConfig.getDeadLetterRoute(queue)` is the exported form of the same answer.
 
+**A TERMINAL queue is consumed, and it is not an exception to that rule but its other
+half.** A queue something else dead-letters TO — `<service>.dlq`, `workflow.failed`,
+`workflow.dlq`, `delivery.dlq` — declares no onward route because the topology says it
+must not have one: a dead-letter route on a dead-letter queue closes a loop or starts a
+chain with no end (`api/docs/governance/confirmations/mq-consumer-contract.md` 002
+point 2, 003 point 2). So the gate asks a second question, `queueConfig.isDeadLetterTarget(queue)`,
+derived from the templates themselves — the set of every `x-dead-letter-routing-key` they
+declare, `{service}` placeholder and all — never from a list of names. Every OTHER queue
+with no route is refused exactly as before, with the same sentence.
+
+What a terminal queue does NOT get is a different delivery policy: the budget is counted
+the same way, and a message that spends it is rejected with `nack(requeue=false)` the same
+way. The difference is what the broker then does with it — there is nowhere to move it to,
+so it is **dropped**. That loss is deliberate (the alternative is the endless requeue this
+policy exists to end) and it is never silent: the client logs it at error level, naming
+the queue, the attempts and the error, and the `message_dlq` event is published as for any
+other rejection.
+
 ```javascript
 await client.consume(queue, async (msg, delivery) => {
   // delivery = { attempt, maxAttempts, isFinalAttempt }
@@ -527,12 +545,18 @@ const { queueConfig } = require('@onlineapps/mq-client-core');
 queueConfig.isInfrastructureQueue('workflow.init'); // true
 queueConfig.isBusinessQueue('emailer.workflow');    // true
 queueConfig.getInfrastructureQueueConfig('workflow.init'); // { durable, arguments }
+queueConfig.getDeadLetterRoute('workflow.init');    // { exchange: '', routingKey: 'workflow.failed' }
+queueConfig.isDeadLetterTarget('workflow.failed');  // true — the end of that chain
 ```
 
 - `workflow.failed` carries no `x-message-ttl`. It is read by an operator, not by a
   service, and it has no dead-letter exchange, so a TTL there does not move a message
   anywhere — it deletes it. See
   `api/docs/governance/confirmations/mq-consumer-contract.md` 002.
+- `isDeadLetterTarget()` answers "does this configuration dead-letter TO this name",
+  derived from the declared routing keys rather than from a list. It is what lets
+  `consume()` attach to `workflow.failed` and to any `<service>.dlq` while every other
+  queue with no declared route stays refused — see § `consume()` — the delivery contract.
 
 **That require is the contract.** Reaching into
 `@onlineapps/mq-client-core/src/config/queueConfig` is an internal path the package
@@ -541,6 +565,42 @@ file moves. Callers holding the deep path switch to the named export; callers th
 receive `queueConfig` by injection (`initInfrastructureQueues` in
 `@onlineapps/infrastructure-tools`) pass it from here.
 
+### topology — platform queue names, as a declared export
+
+A name that travels ON THE WIRE between services has to have ONE owner, or it has one
+copy per service. `topology` is that owner: a frozen object of the platform names, each
+one composed from the entry that DECLARES it in `queueConfig`, so a rename there moves
+the export with it and an entry that is gone fails fast instead of handing back a
+plausible string.
+
+```javascript
+const { topology } = require('@onlineapps/mq-client-core');
+
+topology.infrastructureHealthEventsExchange; // 'infrastructure.health.events'
+topology.telemetryLogsQueue;                 // 'telemetry.logs.queue'
+topology.telemetryLogsQueue = 'mine';        // TypeError — the object is frozen
+```
+
+| Key | Name on the wire | Who publishes / who drains it |
+|---|---|---|
+| `infrastructureHealthEventsExchange` | `infrastructure.health.events` | Fanout. The registry publishes (`api/infra/api_services_registry/src/services/infrastructureEventPublisher.js`); the two queues below are bound to it. |
+| `monitoringInfrastructureHealthEventsQueue` | `monitoring.infrastructure.health.events` | The monitoring consumer's queue on that fanout (`api/infra/api_monitoring/src/consumer/topology.js`, `MONITORING_INFRA_EVENT_QUEUE`). |
+| `deliveryHealthEventsQueue` | `delivery.health.events` | The delivery endpoint binds it to the fanout and consumes it for WS push (`api/infra/api_delivery_endpoint/src/index.js`, `bindQueueToFanout(config.healthEventsQueue, …)`). |
+| `deliveryResourceEventsQueue` | `delivery.resource.events` | Bound to the `monitoring.resource` exchange by `resource.changed.#`; published by the monitoring watcher `resourceChangedPublisher.js`, drained by `ResourceChangedConsumer.js` in the delivery endpoint. |
+| `telemetryLogsQueue` | `telemetry.logs.queue` | Bound to `telemetry.exchange`, which every service publishes to with its own name as the routing key; drained by the monitoring consumer (`api/infra/api_monitoring/src/consumer/index.js`, `topology.TELEMETRY_LOGS_QUEUE`). |
+| `telemetryMetricsQueue` | `telemetry.metrics.queue` | The same exchange, the same consumer — metric samples. |
+| `telemetryTracesQueue` | `telemetry.traces.queue` | The same exchange, the same consumer — spans. |
+
+- **Frozen on purpose.** An importer must not be able to rewrite platform topology: a
+  name overridden on one side of a fanout loses the events silently, which is why batch
+  243g-C removed the per-service env override for the health-events exchange in the
+  first place.
+- **The named export is the contract.** `@onlineapps/mq-client-core/src/config/queueConfig`
+  is an internal path this package never promised — it resolves today and breaks the day
+  the file moves. Import `topology` (or `queueConfig`) from the package root.
+- 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.
+
 ### redactUrl — a connection URL that is safe to log
 
 `RABBITMQ_URL` carries the broker account, so anything that renders it verbatim
@@ -565,9 +625,10 @@ redactUrl(undefined);                                   // '<unparseable-url>'
   goes through `redactConnectionTarget()` instead, which refuses a non-string
   outright, because `host` is a declared config key and a wrong type there is a
   boot-time defect.
-- It is the SAME function this package uses internally, and the same semantics as
-  `shared/service-common/src/redactUrl.js`. A dependant that renders a broker URL
-  imports it from here rather than keeping a copy.
+- It is the SAME function this package uses internally. Implementaci vlastní
+  `@onlineapps/logger-contract` (vrstva L1, dosáhne na ni každá kategorie);
+  tenhle balíček ji od d.455 jen **re-exportuje identitou**, aby dependant,
+  který renderuje URL brokeru, importoval funkci místo kopie.
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/mq-client-core",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"
@@ -23,8 +23,8 @@
   "author": "OnlineApps",
   "license": "MIT",
   "dependencies": {
-    "@onlineapps/logger-contract": "1.1.0",
-    "@onlineapps/runtime-config": "1.1.0",
+    "@onlineapps/logger-contract": "1.3.0",
+    "@onlineapps/runtime-config": "1.2.0",
     "ajv": "^8.12.0",
     "amqplib": "^0.10.3"
   },

package/src/BaseClient.js

@@ -502,6 +502,14 @@ class BaseClient {
    * `message_dlq` event would report a destination nothing routed to. The fix is
    * always to declare the route, never to consume without one.
    *
+   * The one queue that demand cannot be made of is the END of a chain — a queue
+   * this configuration dead-letters TO (`<service>.dlq`, `workflow.failed`). The
+   * topology withholds its route deliberately, so the gate reads a second,
+   * derived answer (`queueConfig.isDeadLetterTarget()`) and lets its consumer
+   * attach (d.452). A message that spends its budget there is rejected as
+   * anywhere else and then dropped by the broker, with an error line naming the
+   * loss — never an endless requeue. README § `consume()` — the delivery contract.
+   *
    * @param {string} queue - Name of the queue to consume from.
    * @param {function(Object, {attempt: number, maxAttempts: number, isFinalAttempt: boolean}): Promise<void>} messageHandler -
    *   Async function to process each message. Its second argument says which

package/src/config/queueConfig.js

@@ -100,6 +100,10 @@ const TEMPLATE_PLACEHOLDER = /^\{[^.{}]+\}$/;
  * service name, with `null` where the template accepts anything (`registry.events`
  * -> `['registry', 'events']`; a key writing `registry.{kind}` would give
  * `['registry', null]`).
+ *
+ * A declared dead-letter routing key is written in the same notation
+ * (`{service}.dlq`), so `isDeadLetterTarget()` reads it through this one function
+ * rather than through a second placeholder rule.
  */
 const templateShape = (template) =>
   template.split('.').map((part) => (TEMPLATE_PLACEHOLDER.test(part) ? null : part));
@@ -169,6 +173,41 @@ const declaredInfrastructureNames = (config) => {
   return names;
 };
 
+/**
+ * Every name this configuration dead-letters TO — the END of a chain.
+ *
+ * Derived from the declarations themselves: the value of every
+ * `x-dead-letter-routing-key` any section writes, placeholders and all
+ * (`{service}.dlq`, `workflow.failed`, `workflow.dlq`, `delivery.dlq`). A list of
+ * names typed here would have to be edited in step with the templates and could
+ * therefore disagree with them — the defect d.278 removed from
+ * `matchBusinessTemplate()`, and the reason `declaredInfrastructureNames()` above
+ * derives its set the same way.
+ *
+ * The `.dlq` family needs no rule of its own: every `.dlq` this configuration
+ * declares — `workflow.dlq`, `delivery.dlq`, `{service}.dlq` — is already the
+ * target of a declared routing key (measured 2026-09-14), so the set covers it.
+ * A `.dlq` nothing routes to would be a queue with no writer, which is a defect
+ * in the declaration, not a case to paper over here.
+ *
+ * @param {Object} config - The queueConfig object (its sections are read from `this`).
+ * @returns {Set<string>} The routing keys, e.g. `workflow.failed`, `{service}.dlq`.
+ */
+const declaredDeadLetterTargets = (config) => {
+  const targets = new Set();
+
+  for (const section of Object.values(config)) {
+    if (section === null || typeof section !== 'object') continue;
+    for (const entry of Object.values(section)) {
+      if (entry === null || typeof entry !== 'object') continue;
+      const routingKey = entry.arguments && entry.arguments['x-dead-letter-routing-key'];
+      if (typeof routingKey === 'string' && routingKey !== '') targets.add(routingKey);
+    }
+  }
+
+  return targets;
+};
+
 /**
  * The two ways out of "this configuration declares no such queue", named in the
  * refusal itself.
@@ -1222,6 +1261,51 @@ module.exports = {
     return { exchange, routingKey };
   },
 
+  /**
+   * Is this queue the END of a dead-letter chain — a queue something
+   * dead-letters TO?
+   *
+   * The counterpart of `getDeadLetterRoute()`, and the reason a queue may have no
+   * route without that being a defect. `workflow.failed` is named in
+   * `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`;
+   * `{service}.dlq` by every business template; `workflow.dlq` and `delivery.dlq`
+   * by their own families. Giving such a queue a route of its own would either
+   * close a loop or start an endless chain, which is why the confirmed topology
+   * leaves them without one (`docs/governance/confirmations/mq-consumer-contract.md`
+   * 002 point 2, 003 point 2 — "workflow.failed and workflow.dlq themselves keep
+   * no route").
+   *
+   * The consumer's dead-letter gate reads this second question, so a terminal
+   * queue is consumable while every OTHER queue with no declared route stays
+   * refused (`transports/rabbitmqClient.js`, d.452). What happens to a message
+   * that fails there is unchanged and stated in the README: the budget is spent,
+   * `nack(requeue=false)` is issued, the broker DROPS the message — the end of the
+   * chain is the end — and the loss is logged as an error rather than turned into
+   * an endless requeue.
+   *
+   * Derived from the templates (`declaredDeadLetterTargets()`), never from a list
+   * of names: a `{placeholder}` segment matches any one part, exactly as a
+   * business template key does.
+   *
+   * @param {string} queueName - Full queue name.
+   * @returns {boolean} True if this configuration dead-letters to this name.
+   */
+  isDeadLetterTarget(queueName) {
+    if (typeof queueName !== 'string' || queueName === '') return false;
+
+    const parts = queueName.split('.');
+
+    for (const target of declaredDeadLetterTargets(this)) {
+      const shape = templateShape(target);
+      if (shape.length !== parts.length) continue;
+      if (shape.every((part, index) => (part === null ? parts[index] !== '' : part === parts[index]))) {
+        return true;
+      }
+    }
+
+    return false;
+  },
+
   /**
    * Get infrastructure queue configuration by queue name (auto-detect type)
    *

package/src/index.js

@@ -38,7 +38,7 @@ const {
 } = require('./monitoring-publish');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
-const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('./utils/redactCredentials');
+const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
 
 // Export BaseClient as default (constructor), with additional named exports
 // NOTE: When destructuring, use: const { BaseClient } = require('@onlineapps/mq-client-core');
@@ -117,7 +117,18 @@ module.exports.topology = Object.freeze({
    * names (`api/docs/governance/confirmations/mq-consumer-contract.md` 003 — the
    * endpoint declaring its queues from `queueConfig` is INFRA's step).
    */
-  deliveryResourceEventsQueue: queueConfig.queueName('deliveryEvents', 'resource.events')
+  deliveryResourceEventsQueue: queueConfig.queueName('deliveryEvents', 'resource.events'),
+  /**
+   * The monitoring consumer's OpenTelemetry log intake, bound to `telemetry.exchange`.
+   * Declared in `queueConfig` since d.269; the consumer carries the same literal as a
+   * private constant (`api/infra/api_monitoring/src/consumer/topology.js`), which is the
+   * shape d.270 gave an owner for the health-events names.
+   */
+  telemetryLogsQueue: queueConfig.queueName('telemetry', 'logs.queue'),
+  /** The same consumer's metric-sample intake on that exchange. */
+  telemetryMetricsQueue: queueConfig.queueName('telemetry', 'metrics.queue'),
+  /** The same consumer's span intake on that exchange. */
+  telemetryTracesQueue: queueConfig.queueName('telemetry', 'traces.queue')
 });
 /**
  * The dead-letter policy of `consume()` as a contract, not as an implementation
@@ -137,16 +148,17 @@ module.exports.deliveryPolicy = deliveryPolicy;
  * userinfo out, scheme/host/port/vhost in, and a fixed placeholder for a value that
  * is not a parseable URL.
  *
- * It is exported because it was already written three times — here, in
- * `shared/service-common/src/redactUrl.js` (d.245/d.245b) and in
- * `shared/connector/conn-orch-registry/src/redactUrl.js` (d.446), whose header says
- * plainly that it stayed local only because this package declared no redactor and
- * masked the password alone. Two semantics for one concern are two rails
- * (`change-discipline.md` § One rail per concern); d.448 made them one and put it
- * where a dependant can import it instead of copying it.
+ * It is exported because it was already written three times across the platform.
+ * Two semantics for one concern are two rails (`change-discipline.md` § One rail
+ * per concern); d.448 made them one, a d.455 je přesunula tam, kam patří —
+ * `@onlineapps/logger-contract` (vrstva L1, bez `@onlineapps` závislostí, dosáhne
+ * na ni každá kategorie). Zdejší export je od té chvíle **re-export identitou**:
+ * zůstává, protože dependants ho importují odsud.
  *
  * The placeholder travels with the function: a caller comparing against it must
  * read the same literal, not retype it.
+ *
+ * @see node_modules/@onlineapps/logger-contract/src/redactUrl.js
  */
 module.exports.redactUrl = redactUrl;
 module.exports.UNPARSEABLE_PLACEHOLDER = UNPARSEABLE_PLACEHOLDER;

package/src/transports/rabbitmqClient.js

@@ -1784,7 +1784,22 @@ class RabbitMQClient extends EventEmitter {
     // The internal monitor calls `_performHealthCheck()` instead, deliberately:
     // a timer resuming recovery would make the retry periodic, which is the
     // opposite of the lazy contract.
-    this._resumeRecovery();
+    //
+    // "If this client stood down" is a QUESTION, and it is asked of the one
+    // liveness source (`_connectionAlive`, read through `isConnected()` — d.260)
+    // the two other uses already read it from: `_ensurePublisherChannel()` and
+    // `_ensureConsumerChannel()` resume recovery inside their
+    // `if (!this._connectionAlive)` branch. Until d.467 this one did not ask:
+    // `_reconnectWithBackoff()` sets `_reconnecting` synchronously and
+    // `isConnected()` reads it, so a check on a LIVE client reported its own
+    // side effect — `connection: { exists: true, closed: true }`, the issue
+    // `Connection is closed or missing`, `isConnected()` true before and false
+    // after — and then really replaced a healthy socket with a new one. A
+    // report that changes what it reports is not a report (INFRA 326b,
+    // measured 2026-09-15 against the live broker, amqplib 0.10.9).
+    if (!this.isConnected()) {
+      this._resumeRecovery();
+    }
     return this._performHealthCheck();
   }
   
@@ -3073,7 +3088,26 @@ class RabbitMQClient extends EventEmitter {
     // arguments (measured, 2026-09-12 — see queueConfig.getDeadLetterRoute()).
     // The caller's own `queueOptions` do not count either; a route supplied at
     // the call site would be a second declaration of one queue's topology.
-    if (queueConfig.getDeadLetterRoute(queue) === null) {
+    //
+    // The ONE queue this demand cannot be made of is the one at the END of a
+    // chain: a queue something else dead-letters TO. `workflow.failed` is named
+    // in `x-dead-letter-routing-key` by `workflow.init` and `workflow.control`,
+    // `<service>.dlq` by every business template — and the confirmed topology
+    // 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
+    // (`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.
+    //
+    // A message that spends its budget on a terminal queue is REJECTED as
+    // anywhere else and then dropped by the broker, which is the end of the
+    // chain doing its job. It is never requeued for ever, and the loss is said
+    // out loud in `_rejectDelivery()`.
+    if (queueConfig.getDeadLetterRoute(queue) === null && !queueConfig.isDeadLetterTarget(queue)) {
       throw new ConsumeError(
         `[RabbitMQClient] consume(${queue}): the dead-letter policy needs a dead-letter route and `
           + 'queueConfig declares none for this queue - '
@@ -4136,13 +4170,21 @@ class RabbitMQClient extends EventEmitter {
    * `status`.
    *
    * The `onDeadLetter` hook — and therefore the `message_dlq` event it publishes —
-   * is only ever reached for a message that CAN be dead-lettered: `consume()`
-   * refuses to register a consumer on a queue for which `queueConfig` declares no
+   * is reached for a message that CAN be dead-lettered: `consume()` refuses to
+   * register a consumer on a queue for which `queueConfig` declares no
    * `x-dead-letter-exchange`/`-routing-key` (d.259), so by the time a delivery
    * arrives here the route exists by declaration. Without that gate the same
    * `nack(requeue=false)` made the broker DROP the message while this event
    * announced it had reached `.dlq` — a report of a destination nothing routed to.
    *
+   * ONE class of queue reaches this method with no route, and it is not that
+   * defect: the END of a chain, a queue something else dead-letters TO
+   * (`<service>.dlq`, `workflow.failed`), whose consumer the gate admits on
+   * purpose (d.452). There the rejection does not move the message anywhere — the
+   * broker drops it, because the end of the chain is the end — so the loss is
+   * logged at error level below before monitoring is told. What is NOT done is
+   * inventing a requeue for it: that is the unbounded loop d.198b ended.
+   *
    * @param {Object} args
    * @private
    */
@@ -4178,6 +4220,29 @@ class RabbitMQClient extends EventEmitter {
       return;
     }
 
+    // A TERMINAL queue — one this configuration dead-letters TO — declares no
+    // onward route by design, so the rejection just issued does not MOVE the
+    // message: the broker drops it. That is the end of the chain working as
+    // intended, and the alternative would be the unbounded requeue d.198b ended.
+    // It is still a message the platform has lost, so it is said out loud, at
+    // error level, exactly once, before monitoring is told (d.452).
+    if (queueConfig.getDeadLetterRoute(queue) === null) {
+      this._logger.error(
+        `[RabbitMQClient] [mq-client-core] [CONSUMER] Message discarded on terminal queue "${queue}" - `
+          + 'Expected: a terminal queue is the end of the dead-letter chain, so it declares no onward '
+          + 'route and the broker DROPS what nack(requeue=false) rejects instead of moving it. '
+          + 'Fix: nothing to declare — the delivery budget is spent and the message is deliberately gone '
+          + 'rather than circling for ever; read the error and fix what made the handler fail.',
+        {
+          queue,
+          attempts,
+          maxAttempts,
+          classification,
+          error: error && error.message ? error.message : null
+        }
+      );
+    }
+
     if (onDeadLetter === undefined) {
       // Driving this transport directly is allowed (it is an export of this
       // package), but then nothing owns the monitoring rail, and a message

package/src/utils/redactCredentials.js

@@ -12,53 +12,21 @@
  * boot, so the broker account was readable in container stdout and, through the
  * monitoring consumer, in Loki (measured 2026-09-07 on api_service_hello).
  *
- * `redactUrl` returns the URL with the WHOLE userinfo removed: what stays is
- * scheme, host, port, vhost and query — the part a reader of the log actually
- * came for. The account NAME goes with the password, because it is the other
- * half of the same credential, and because this is the redaction semantics the
- * platform already writes: `shared/service-common/src/redactUrl.js`
- * (d.245/d.245b, Redis) and `shared/connector/conn-orch-registry/src/redactUrl.js`
- * (d.446, AMQP). Until d.448 this module masked the password only, which made
- * two semantics for one concern — two rails (`change-discipline.md` § One rail
- * per concern). `src/index.js` exports the function so the dependants import it
- * instead of keeping a local copy.
+ * Samotné pravidlo „co smí z URL dorazit do logu“ tenhle balíček neimplementuje.
+ * Od d.455 je bere z `@onlineapps/logger-contract` (`redactUrl`,
+ * `UNPARSEABLE_PLACEHOLDER`): userinfo ven, scheme/host/port/vhost/query
+ * dovnitř, neparsovatelná hodnota nahrazená placeholderem místo echa. Do d.455
+ * tu stála bajtově stejná kopie jako v `@onlineapps/service-common` — tři
+ * vlastníci jednoho pravidla, tedy přesně to, co `change-discipline.md`
+ * § One rail per concern označuje za vadu.
  *
- * A value that is not a parseable URL is answered with a fixed placeholder
- * rather than echoed: an unparseable string is exactly the case where nobody can
- * say whether it holds a credential, and echoing it would be the leak this
- * helper exists to prevent.
- */
-
-const UNPARSEABLE_PLACEHOLDER = '<unparseable-url>';
-
-/**
- * Strip userinfo (`user:password@`) from a connection URL.
+ * Zdejší zůstává jediná věc, kterou core vrstva nemá proč znát:
+ * `redactConnectionTarget`, fail-fast obal nad DEKLAROVANÝM config klíčem.
  *
- * @param {string} url - connection URL, e.g. `amqp://oa_dev:secret@queuer:5672/vhost`
- * @returns {string} the URL without userinfo, e.g. `amqp://queuer:5672/vhost`,
- *   or `<unparseable-url>` when the input is not a URL.
+ * @see node_modules/@onlineapps/logger-contract/src/redactUrl.js
  */
-function redactUrl(url) {
-  if (typeof url !== 'string' || url.length === 0) {
-    return UNPARSEABLE_PLACEHOLDER;
-  }
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch (_) {
-    return UNPARSEABLE_PLACEHOLDER;
-  }
-  // `new URL('api_services_queuer:5672')` SUCCEEDS — it reads `api_services_queuer:`
-  // as the scheme and `5672` as an opaque path, so the value comes back with an
-  // empty host and no userinfo to strip. Without this guard such a value would be
-  // echoed verbatim, which is the leak this helper exists to prevent.
-  if (!parsed.host) {
-    return UNPARSEABLE_PLACEHOLDER;
-  }
-  parsed.username = '';
-  parsed.password = '';
-  return parsed.href;
-}
+
+const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
 
 /**
  * Makes a connection target safe to log.
@@ -103,4 +71,4 @@ function redactConnectionTarget(target) {
   );
 }
 
-module.exports = { redactConnectionTarget, redactUrl, UNPARSEABLE_PLACEHOLDER };
+module.exports = { redactConnectionTarget };