@onlineapps/conn-orch-registry 6.0.2 → 7.0.0

package/CHANGELOG.md

@@ -0,0 +1,538 @@
+# Changelog — @onlineapps/conn-orch-registry
+
+All notable changes to this package. Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+## [Unreleased]
+
+## [7.0.0] — 2026-09-27
+
+pin: `@onlineapps/mq-client-core` 4.2.0 → 5.0.0
+
+### Documentation — `API.md` je součástí tarballu (d.1039)
+
+`files` teď jmenuje `API.md`; dokument ležel v balíčku, ale do vydaného artefaktu se nedostal.
+
+### Changed — BREAKING — odpověď na registraci chodí na frontu instance `<service>.registry.<instance_id>` (d.817c)
+
+Konfirmace `registry-instance-identity` 001 (c): odpověď na registraci jde na frontu TÉ kopie, která
+se registrovala, přes existující `responseQueue`. Sdílenou `<service>.registry` dostávají od registru
+jen podněty. Klient teď:
+- ve zprávě `register` posílá `responseQueue: "<service>.registry.<instance_id>"` (dřív
+  `"<service>.registry"`); nová vlastnost `instanceResponseQueue`;
+- v `init()` konzumuje DVĚ fronty, obě s `requeueOnError: false`: sdílenou `<service>.registry`
+  (podněty registru, např. `revalidate`, které `api_services_registry` posílá na
+  `<serviceName>.registry`) a frontu instance (odpovědi);
+- hlášku o vypršení registrace jmenuje frontou instance a log `Initialized` nese `promptQueue` a
+  `responseQueue`.
+
+Heartbeat a `deregister` se nemění. Pořadí z konfirmace 002 platí: šablona `registry.{instance_id}`
+s dead-letter cestou musí být v pinovaném `@onlineapps/mq-client-core` (d.817b), jinak `consume()`
+frontu instance odmítne. Tato změna proto vyžaduje mq-client-core s d.817b. Server registru
+(`registry.listener.js`, `validationResponse.listener.js`) odpovídá na `msg.responseQueue` ze
+zprávy a změnu nepotřebuje.
+
+Proč BREAKING: mění se veřejný tvar zprávy `register` (`responseQueue`), topologie, kterou klient
+deklaruje (nová trvalá fronta na instanci), a minimální `@onlineapps/mq-client-core` (musí nést d.817b).
+
+Životnost fronty instance (`auto-delete`, `x-expires`, trvalá) rozhodnutá není (konfirmace 002,
+Conditions; šablona d.817b ji záměrně nenese). Fronta je trvalá a po skončení kopie zůstává.
+
+### Documentation — README, průvodce a komentáře testů ukazují na vlastníka drátu jeho jménem (d.999b, d.999d)
+
+Balíček citoval kontrakt registrace starým jménem dokumentu, který v `docs/biz/30-operations/` není.
+Odkazy přitom vedly na `registration-wire.md`. Všechna místa teď jmenují existující uzel a jeho
+sekci:
+- úvod README: `registration-wire.md §2` (MQ wire format) (d.999b);
+- komentář v příkladu `register()` v README a parametr `serviceInfo.operations` v
+  `docs/REGISTRY_CLIENT_GUIDE.md`: `§3` (Operation schema);
+- úvod průvodce a komentáře ve třech unit testech: `§2.1` (`register`) (d.999d).
+
+### Changed — BREAKING — konstruktor `ServiceRegistryClient` vyžaduje `instanceId`; `instance_id` jde v `register`, `heartbeat` i `deregister` (d.817)
+
+Každá zpráva na drát teď říká nejen, KTERÁ služba, ale i KTERÁ běžící kopie (konfirmace
+`registry-instance-identity` 001): `register`, `heartbeat` a `deregister` nesou `instance_id`.
+Registr podle něj maže jen při shodě, takže krátce žijící cizí kopie už neodhlásí tu živou.
+Konstruktor bez `instanceId` (nebo s prázdným řetězcem) skončí chybou:
+`[RegistryClient] <service>: Missing instanceId - got undefined. Expected: a non-empty string naming
+THIS running copy of the service, the same value for the whole process; … Fix: pass the instance id
+the wrapper made once at boot (SERVICE_INSTANCE_ID when the deployment gives one, otherwise a UUID v4)
+- this client never makes one, because the same value also reaches monitoring-core as serviceInstanceId.`
+
+Migrace volajícího: předat `instanceId`, jednu hodnotu na proces. `@onlineapps/service-wrapper` ji
+předává (`this.instanceId`, stejná hodnota jde do monitoringu jako `serviceInstanceId`). Kdo staví
+klienta sám, musí ji doplnit. Registrační odpověď dál chodí do sdílené fronty `<service>.registry`,
+viz komentář u `serviceRegistryQueue` v `src/registryClient.js`.
+
+### Changed — BREAKING — `register()` přijímá jen klíče registračního kontraktu (d.702)
+
+`register(serviceInfo)` odmítne klíč, který kontrakt nezná (`registration-wire.md` §2.1). Dřív ho
+tiše zahodil. Povolené klíče: `endpoints`, `operations`, `metadata`, `health`, `workspaceScoped`,
+`timeout`. Hláška:
+`[RegistryClient] <service>: serviceInfo key "foo" is not part of the registration contract - Expected
+one of: endpoints, operations, metadata, health, workspaceScoped, timeout (api/docs/biz/30-operations/
+registration-wire.md §2.1). Fix: delete "foo" from the object passed to register(), or send the value
+under the key the contract names for it.`
+Zaniklé klíče si dál nesou vlastní hlášku (např. `token`: `serviceInfo carries the retired key "token" …`).
+Migrace: z objektu pro `register()` odstranit vše mimo šest klíčů výše.
+
+### Changed — druhý souběžný `register()` pod týmž request id a druhé `startHeartbeat()` se odmítnou, místo tichého přepisu (d.760b, d.760c)
+
+- `register()`, dokud čeká registrace se stejným `id`, skončí chybou `[RegistryClient] <service>: Duplicate
+  request id "<id>" - a registration with this id is still pending. … Fix: await the register() already in
+  flight before starting another one …`. Dřív druhé volání přepsalo záznamy prvního a handle jeho timeru
+  zmizel, takže starší timer doběhl celý timeout bez možnosti ho zrušit. S `uuid.v4` se id neopakují,
+  takže běžný volající to nepozná.
+- `startHeartbeat()` nad klientem, jehož smyčka běží, skončí chybou `[RegistryClient] <service>: A heartbeat
+  loop is already running - … Fix: call client.stopHeartbeat() before starting a new loop, or keep the loop
+  that is already running.`. Dřív přepsal handle a první smyčka tepala dál bez možnosti ji zastavit.
+
+### Fixed — `RegistryEventConsumer` bere jméno výměny `registry.changes` z `queueConfig` (d.809); `stopHeartbeat()` ruší jen `setTimeout` (d.752c)
+
+- Jméno výměny, na kterou se odběratel změn váže, vlastní `@onlineapps/mq-client-core`
+  (`queueConfig.queueName('registry', 'changes')`), ne literál v balíčku. Hodnota se nemění:
+  `registry.changes`.
+- `stopHeartbeat()` volal nad týmž handlem `clearTimeout` i `clearInterval`, přestože smyčka je
+  rekurzivní `setTimeout`. Druhé volání je pryč, chování se nemění.
+
+### Changed — `CHANGELOG.md` je součástí tarballu (d.997)
+
+`package.json` `files` nese `CHANGELOG.md`. Vydaná 6.0.3 ho nenesla.
+
+## [6.0.3] — 2026-09-25
+
+pin: `@onlineapps/mq-client-core` 4.1.0 → 4.2.0
+
+## [6.0.2] — 2026-09-24
+
+pin: `@onlineapps/mq-client-core` 4.0.1 → 4.1.0
+
+## [6.0.1] — 2026-09-17
+
+pin: `@onlineapps/mq-client-core` 4.0.0 → 4.0.1
+
+## [6.0.0] — 2026-09-17
+
+### Changed (testy) — odmítnutá deklarace se tvrdí hodnotou značky (d.579b)
+
+`tests/integration/ensureQueuesRefusal.integration.test.js` čekal `cause.code === 406` z doby pinu jádra 3.2.0; pinované
+`@onlineapps/mq-client-core` 4.x značí odmítnutou deklaraci u zdroje (d.582), takže případ teď tvrdí `code: MQ_CONNECTION_FATAL`,
+`reason: broker-refused` a 406 brokeru čte o patro níž (`cause.cause.code`). Sada byla od re-pinu červená (W592 měření).
+
+### Removed — BREAKING: `deployable` odchází z registrační zprávy (d.592)
+
+Verdikt shody s uniformou jezdil na registraci od d.221 a **nikdo ho nečetl**:
+`processRegistration` (`api/infra/api_services_registry/src/listeners/registry.listener.js`)
+zprávu destrukturuje bez něj a jiný čtenář na platformě není (`grep -rn deployable`
+nad `api/infra/**` a `fe_adminui/src` vrací prázdno). Slib konfirmace
+`biz-service-manifest` 001 §4 — „registr ho promítne do
+`infrastructure:health:<service>` vedle `status`" — zůstal bez implementace.
+
+Čtyři otázky `change-discipline.md` § Removing something removes its declaration:
+
+- **Vznik.** d.221 klíč zavedla, aby nasaditelnost dojela z běhu služby k registru.
+- **Role v koncepci.** 001 §4: dvě závažnosti, dva důsledky — `boot` shodí start,
+  `deploy` nechá službu běžet a označí ji jako nenasaditelnou.
+- **Proč nikdo nečte.** Projekce nikdy nevznikla, a mezitím se ukázalo, že
+  verdikt z běžícího kontejneru nevypovídá o repozitáři: produkční obraz není git
+  checkout a nenese compose ani README, takže krok 7 nad ním hlásí 12 nálezů
+  nepřítomnosti — na drát by u každé zdravé služby jel `false`.
+- **Náhrada je koncepčnější.** Nasaditelnost dokládá z každého commitu CI job
+  `validate-uniform` nad checkoutem (konfirmace `biz-service-manifest` 010), tedy
+  jediné místo, které vidí, co dostane klon. Rozhodnutí vlastníka 2026-09-17,
+  konfirmace `biz-service-manifest` 011.
+
+S klíčem odešel i jeho `@param` v JSDoc a blok `if ('deployable' in serviceInfo)`;
+`API.md` je zregenerovaná ze zdrojů (`npm run docs`).
+
+### Changed — BREAKING: `register()` odmítá zaniklý klíč jménem (d.592)
+
+`deployable` je šestý řádek tabulky `RETIRED_SERVICE_INFO_KEYS` (vedle `spec`,
+`token`, `validationToken`, `secret`, `tokenSecret` z d.562). Volání, které ho
+ještě pošle, **skončí výjimkou před publikací**, ne tiše bez účinku:
+
+    [RegistryClient] biz-invoicing: serviceInfo carries the retired key
+    "deployable" - the manifest-conformance verdict of a boot-time validation run
+    (owner decision 2026-09-17, confirmation
+    `api/docs/governance/confirmations/biz-service-manifest.md` 011). … Fix:
+    delete "deployable" from the object passed to register().
+
+Odmítnutí se ptá na **přítomnost klíče, ne na jeho hodnotu** — `false` i `null`
+byly stavy, které wrapper posílal nejčastěji, a kontrola podle pravdivosti by je
+propustila.
+
+Dopad: `ServiceWrapper._buildRegistrationPayload()` klíč dnes posílá, takže
+wrapperová půlka změny (d.591) musí přistát ve stejné vlně; bez ní boot skončí
+touto výjimkou. Pro ostatní přímé volající `register()` platí `Fix:` z hlášky.
+
+Sady: unit 19 suites / 205 testů (o jednu sadu méně — `registryClient.deployable`
+i `deployable-on-the-wire` odešly s klíčem, který tvrdily); integrace proti
+živému brokeru včetně případu `deployable: false` odmítnutého dřív, než něco
+odjede.
+
+## [5.0.0] — 2026-09-16
+
+### Fixed — klasifikace chyby přežije i rewrap ve FÁZI 0.8 (d.579)
+
+`ensureQueues()` byla **třetí** cesta, která obalovala pád do
+`new Error(msg, { cause })` — a ta konstrukce nenese žádnou vlastní vlastnost,
+takže `code` i `reason`, které na chybu napsal
+`@onlineapps/mq-client-core`, tady umíraly. d.532 opravila dvě cesty FÁZE 0.7
+(`QueueManager.init()`, `RegistryClient.init()`); deklarace business front ve
+FÁZI 0.8 zůstala. `@onlineapps/service-wrapper` rozhoduje podle `error.code`,
+takže odmítnutí z této cesty dostal jako neklasifikované a ukončil ho jako
+přechodné.
+
+Teď se klasifikace přenáší týmž vzorem jako v `init()`: `refusal.code =
+assertErr.code`, `refusal.reason = assertErr.reason`, původní chyba zůstává
+v `cause` a věta, kterou tato vrstva přidává (která fronta, co to spraví), je
+beze změny.
+
+**Nic se tu neklasifikuje**: co zdroj nechal neoznačené, zůstává neoznačené.
+Tenhle balíček nečte AMQP reply kódy ani nematchuje text hlášky — otázku „odpověděl
+broker a odmítl?" vlastní `@onlineapps/mq-client-core` (`REFUSAL_REPLY_CODES`,
+`_isBrokerRefusal()`) a druhá kopie toho seznamu by se od něj mohla rozejít.
+
+Změřeno a nezamlčeno: proti pinu `@onlineapps/mq-client-core` 3.2.0 předává
+`assertQueue()` syrovou chybu z amqplib, takže dnes touto cestou cestuje **číslo
+406**, ne značka `code: 'MQ_CONNECTION_FATAL'` / `reason: 'broker-refused'`,
+podle které wrapper končí boot natrvalo. d.577 dala značku rail `consume()`
+v jádře; deklarační rail ji zatím nemá. Tento přenos je tedy nutný, ne
+dostačující — a integrační test to říká nahlas místo toho, aby tvrdil značku,
+kterou žádný zdroj nepíše.
+
+### Documentation — komentář v `registryClient.js` ukazoval na zrušený dokument (d.574)
+
+Komentář nad propagací `workspaceScoped` posílal čtenáře na
+`biz-service-onboarding.md` §4 — dokument, který 2026-08-16 přešel na
+`api/docs/biz/60-templates/onboarding-checklist.md` (čísla sekcí se přenesla,
+`api/docs/biz/RETIRED-VOCABULARY.md` §4). Nová podoba je `@see` s živou cestou.
+Ostatních 16 citací `api/docs/…` v tomto souboru bylo změřeno (`ls`) a všechny
+cíle existují. Chování ani API se nemění.
+
+### Removed — BREAKING: `spec`, `validationToken` a `tokenSecret` odcházejí z registrační zprávy (d.562)
+
+Tři klíče jezdily na každé registraci a nikdo je nečetl. Změřeno 2026-09-16 nad
+`api/infra/api_services_registry/src/**`: `processRegistration` destrukturuje
+`id, serviceName, version, endpoints, operations, metadata, health,
+specificationEndpoint, responseQueue, timestamp, validationProof,
+validationData, workspaceScoped` — a `grep -rn 'validationToken|tokenSecret'`
+nad tím stromem nevrací nic. Kontrakt to už popisoval slovy „emitted, unread"
+(`api/docs/biz/30-operations/registration-wire.md` §2.1).
+
+Čtyři otázky `change-discipline.md` § Removing something removes its declaration:
+
+- `spec` nesl OpenAPI dokument z doby, kdy registr dereferencoval HTTP cestu
+  `/specification`. ADR 0005 vzalo biz kontejnerům HTTP; co registr dnes
+  **validuje**, je `operations` podle schema-v3 (§3 téhož kontraktu). Schéma,
+  které protistrana kontroluje klíč po klíči, je koncepčnější než dokument,
+  který se jen uložil.
+- `validationToken` a `tokenSecret` patřily k JWT token API, které odplulo
+  z `@onlineapps/service-validator-core` v d.344; poslední čtenář (HTTP
+  `POST /validate`) byl smazán 2026-08-22 a validator si zrušení zapsal do
+  vlastní konfigurace (`api/infra/api_services_validator/src/config/config.js`
+  § security). Běh dnes dokládá `validationProof` / `validationData` a podepsaný
+  certifikát — důkaz, který si příjemce ověří, místo sdíleného tajemství, které
+  tahle zpráva vozila po brokeru v čistém tvaru.
+
+S klíči padly i dvě jejich záložky: `spec: serviceInfo.spec || null`
+(výchozí hodnota pod `architecture-principles.md` §3) a dva pravopisy jednoho
+pole — `serviceInfo.token || serviceInfo.validationToken`, `serviceInfo.secret
+|| serviceInfo.tokenSecret`.
+
+### Changed — BREAKING: `register()` odmítá zaniklý klíč jménem (d.562)
+
+Volání, které některý z pěti zaniklých klíčů (`spec`, `token`,
+`validationToken`, `secret`, `tokenSecret`) ještě posílá, **skončí výjimkou
+ještě před publikací** — nikoli tiše bez účinku, protože tiše zahozený klíč
+nechává volajícího věřit, že něco odjelo:
+
+    [RegistryClient] biz-invoicing: serviceInfo carries the retired key
+    "tokenSecret" - the shared secret of that same token API, whose last reader
+    (HTTP POST /validate) was deleted 2026-08-22; nothing verifies a token with
+    it, and a broker message is no place for a secret. Fix: delete "tokenSecret"
+    from the object passed to register().
+
+Hláška **nikdy neopakuje předanou hodnotu** — dva z těch klíčů nesly tajemství.
+
+`ServiceWrapper._buildRegistrationPayload()` žádný z nich neodesílá, takže pro
+běžící biz služby se nemění nic; dopad je na přímého volajícího `register()`.
+
+Sady: unit 20 suites / 199 testů; integrace 6 suites / 38 testů proti živému
+brokeru, včetně nové `registrationPayloadKeys.integration.test.js`, která čte
+zprávu zpět z fronty — `undefined` klíč zmizí až v serializaci, takže to, co
+brokerem opravdu jede, neukáže žádný unit tier.
+
+### Fixed — značka odmítnutí brokerem přežije přebalení chyby (d.532)
+
+Obě selhávající cesty tohohle balíčku chybu z jádra **přebalují**, aby dodaly
+fakt, který jádru chybí: který broker (`QueueManager.init()`) a která fronta
+které služby (`RegistryClient.init()`). Dělaly to holým `new Error(msg, { cause })`,
+které nenese žádnou vlastní vlastnost — takže `code: 'MQ_CONNECTION_FATAL'`
+a `reason: 'broker-refused'`, které na chybu napsal její vlastník
+(`@onlineapps/mq-client-core`, `REFUSAL_REPLY_CODES` + `_isBrokerRefusal()`),
+tady umřely.
+
+Volající, který podle nich jedná, je `@onlineapps/service-wrapper`: FÁZE 0.3
+ukončí boot natrvalo právě podle `error.code`, a od d.532 to dělá i FÁZE 0.7.
+Bez značky viděl neklasifikované selhání a odmítnutí ohlásil jako přechodné —
+změřeno na biz-meta (dev, wrapper 8.1.1): FÁZE 0.7 FAILED pro 406 na
+`biz-meta.registry`, hlášeno jako „a restart against a recovered dependency can
+succeed", a služba pak v crash loopu.
+
+`code` i `reason` se teď přenášejí **bezpodmínečně** — táž kolej, jakou drží
+`@onlineapps/conn-infra-mq` v `ConnectorMQClient` (d.498b). Nic se tu
+neklasifikuje: co zdroj neoznačil, zůstává neoznačené, takže se do balíčku
+nedostane druhá kopie seznamu AMQP reply kódů ani čtení textu hlášky.
+
+Sonda `tests/unit/error-message-contract.test.js` navíc umí tvar
+`const <jméno> = new …Error(…); … throw <jméno>;` — chyba, která nese vlastní
+vlastnosti, se jinak postavit nedá. Bez toho by obě hlášky tiše vypadly z jejího
+dosahu (změřeno: kontrolní počet spadl 28 → 26), což je přesně ta falešná záruka,
+kvůli které kontrolní případ existuje (`automation-gates.md` §5).
+
+### Breaking — `startHeartbeat({ maxFailures, onFatal })`: smyčka heartbeatu má mez selhání (d.496)
+
+Do téhle dávky `startHeartbeat()` selhání pouze logovala a plánovala další beat
+donekonečna (`src/registryClient.js`, větev `heartbeatLoop`/`catch`). Služba, jejíž
+beaty registr nedostával, tedy běžela dál a nikdo v tomhle balíčku neuměl říct, že
+je „živá" jen naoko. Mez měl jen `@onlineapps/service-wrapper`, ve **vlastní druhé
+smyčce** kolem `sendHeartbeat()` — dvě smyčky nad jednou kadencí, což
+`.claude/rules/change-discipline.md` § One rail per concern označuje za vadu
+a co si CHANGELOG wrapperu sám poznamenal do „Co tahle dávka NEudělala"
+(*„Ta metoda selhání jen loguje — nemá počítadlo ani mez"*).
+
+`startHeartbeat()` nově **vyžaduje objekt se dvěma volbami** a ani jednu si
+nedosazuje (`architecture-principles` §3 a §4; chybějící nebo nesmyslná hodnota je
+výjimka §5 dřív, než vznikne timer):
+
+- `maxFailures` — kladné celé číslo beatů **v řadě**, které služba smí minout.
+  Jeden úspěch počítadlo nuluje.
+- `onFatal(err)` — zavolá se **právě jednou**, ve chvíli, kdy je rozpočet vyčerpán.
+  Dostane chybu, která jmenuje počet, poslední příčinu (i jako `cause`) a Fix.
+  Smyčka je v tu chvíli už zastavená, takže do zavírající se služby nepřiletí
+  další beat.
+
+**Kadence parametrem metody NENÍ** a záměrně: má jednoho vlastníka, a tím je
+volba konstruktoru `heartbeatInterval` (rozhodnutí vlastníka
+`api/docs/governance/confirmations/biz-health-freshness.md` 001 bod 3). Přijímat
+ji ještě jednou při volání by bylo přesně to druhé nezávisle nastavené číslo pro
+jednu věc, které to potvrzení odmítá.
+
+Co s tím musí udělat volající: doplnit obě volby. Volání bez nich je od téhle
+verze výjimka, ne tichý default. `@onlineapps/service-wrapper` pak svou vlastní
+smyčku ruší ve prospěch téhle — samostatná dávka, po pinu.
+
+Dvě menší změny chování ve stejné smyčce:
+
+- **První (okamžitý) beat se počítá do téhož rozpočtu.** Dřív měl vlastní
+  `catch` a vlastní hlášku `[RegistryClient] Initial heartbeat failed`; ta
+  zaniká. Beat započtený mimo rozpočet by z `maxFailures` udělal „N + 1 pro
+  první selhání" — číslo, které volající nenastavil.
+- **Každé selhání se loguje s počtem, kterého dosáhlo, a s rozpočtem, proti
+  kterému se počítá** (`consecutiveFailures`, `maxFailures` v meta), takže log
+  říká, jak blízko ke konci smyčka je, ne jen že jeden beat neprošel.
+
+Testy: nová sada `tests/unit/registryClient.heartbeatBudget.test.js` (13 případů —
+odmítnutí obou voleb hodnotou, vyčerpaný rozpočet, a kontrolní případy, které se
+změnit nesmí: `maxFailures − 1` selhání a úspěch, zdravá smyčka bez `onFatal`,
+idempotentní `stopHeartbeat`) a `tests/integration/heartbeatBudget.integration.test.js`
+(3 případy proti **živému** RabbitMQ: beaty na drátě, skutečné odmítnutí po ztrátě
+spojení, a reset počítadla beatem, který prošel). Selhání se v obou tierech vyrábí
+skutečnou cestou kódu — nikdy atrapou `sendHeartbeat`, která by dokázala jen to, že
+počítadlo počítá volání.
+
+Kontrolní počet chyb v `tests/unit/error-message-contract.test.js` je 28 (bylo 25):
+tři nové jsou odmítnutí voleb. Chyba předaná do `onFatal` mezi nimi **není** a hledat
+se tam nemá — nevzniká `throw` ani `reject`, takže ji ta sonda nevidí; její znění
+tvrdí hodnotou nová sada výše.
+
+`README.md`, `docs/REGISTRY_CLIENT_GUIDE.md` a oba příklady učí novou signaturu;
+`API.md` je přegenerované (`npm run docs`).
+
+### Fixed
+
+- `API.md` regenerated from the sources (`npm run docs`). The committed file still
+  described the connector as asserting `workflow` and `<serviceName>.registry` on
+  startup and as handing out its channel for further operations — a surface replaced
+  when the connector moved onto a single `@onlineapps/mq-client-core` client, declared
+  its queues through `queueConfig` and stopped asserting infrastructure queues it does
+  not own. 167 lines changed, generated content only: the file is written by `jsdoc2md`,
+  never by hand (`.claude/rules/doc-code-binding.md` §1). What now keeps it true is
+  `scripts/ci/verify-generated-api-docs.mjs` (`npm run docs:api:check`).
+
+## [4.0.3] — 2026-09-15
+
+## [4.0.2] — 2026-09-15
+
+### Fixed — `redactUrl` se bere z `@onlineapps/logger-contract`, ne přes `mq-client-core` (d.455)
+
+`src/queueManager.js` si redaktor bral z `@onlineapps/mq-client-core` (d.446b),
+protože tehdy jediný deklaroval platformní sémantiku. Od
+`@onlineapps/logger-contract` 1.2.0 (d.453) ji vlastní core vrstva, kterou
+pinuje každá kategorie, takže import míří tam — vedle `assertLogger`, které si
+tenhle soubor z téhož balíčku bere už dřív. Chování se nemění: pro `amqp` /
+`amqps` vrací obě implementace shodný řetězec (změřeno).
+
+Tady se nic nemaže — smazaná deklarace byla `src/redactUrl.js` a odešla už
+v d.446b. Mění se jen to, **odkud** se tatáž funkce bere; `mq-client-core`
+zůstává závislostí kvůli `BaseClient` a `queueConfig`.
+
+Sady `queueManager.test.js`, `queueManager.spec.test.js`
+a `queueManager.credentialRedaction.test.js`: dvojník `@onlineapps/mq-client-core`
+už **záměrně nenabízí** `redactUrl` ani `UNPARSEABLE_PLACEHOLDER` — kdyby je
+nabízel, sada by prošla i pro import ze špatného balíčku (to byla červená, která
+tuhle změnu vynutila: `TypeError: redactUrl is not a function`,
+`src/queueManager.js:69`). Přibyl kontrolní případ, že dvojník redaktor nemá,
+a cesta selhání (neparsovatelná adresa → placeholder).
+
+## [4.0.1] — 2026-09-14
+
+## [4.0.0] — 2026-09-14
+
+### Breaking
+
+#### Delivery of a registry message belongs to the core, not to this package (d.198b-3)
+
+Both consumers here held a RAW amqplib channel (`queueManager.channel`): they
+asserted their own queue, called `channel.consume(…, { noAck: false })` and settled
+every delivery by hand — `channel.ack(msg)` on success,
+`channel.nack(msg, false, false)` on failure. That is a second implementation of the
+delivery contract (`.claude/rules/change-discipline.md` § One rail per concern), and
+it is the half that cannot count: a hand-written nack knows nothing about the attempt
+budget, the `x-oa-delivery-attempts` header or the `message_dlq` event
+`@onlineapps/mq-client-core` publishes. Worse, `nack(requeue=false)` asks the broker
+to DROP the message — and it did, because `<service>.registry` declared no
+dead-letter route at all. A registry reply this service could not read simply ceased
+to exist.
+
+Both now run on `consume(queue, handler, { requeueOnError: false })`: one attempt,
+and a failure is rejected into `<service>.dlq` over `dlx`, the route `queueConfig`
+declares for these queues. A handler reports failure by THROWING and settles nothing
+itself. Measured on the live broker (`tests/integration/deliveryPolicy.integration`):
+the poison message arrives in the DLQ verbatim with `x-death[0].reason: 'rejected'`,
+the handler ran exactly once, and the control case leaves both queues empty.
+
+`QueueManager` is now the package's single MQ surface, built on
+`@onlineapps/mq-client-core`: `init/isConnected/ensureQueues/checkQueue/
+assertExchange/bindQueue/publish/consume/close`. **It hands out no `channel` any
+more** — a caller reaching for `client.queueManager.channel` gets `undefined`.
+Queue names are this package's; the DECLARATION behind them (durability, TTL, cap,
+dead-letter route) is `queueConfig`'s, so `<service>.registry` and
+`<service>.registry.events` are asserted with no options of our own. The 406 branch
+in `subscribeToChanges()` — "the queue exists with different arguments, use it
+as-is" — went with them: that is the fallback `architecture-principles.md` §3
+forbids, and the reason a queue keeps whatever arguments its first declarer happened
+to pass. `register()` publishes through the core (`persistent: true`), so a failed
+publish THROWS instead of returning `false`, and the infrastructure-queue check runs
+on the core's queue channel rather than a private one.
+
+#### `heartbeatInterval` and `specificationEndpoint` are REQUIRED (d.278c)
+
+Both were module defaults (`10000`, `'/api/v1/specification'`) and both were
+statements this package had no standing to make.
+
+The heartbeat cadence has ONE owner — `wrapper.registry.heartbeatInterval`, fed from
+`BIZ_HEARTBEAT_INTERVAL_MS` (owner confirmation `biz-health-freshness` 001 point 3),
+and the freshness window monitoring computes is a multiple of it. A library default
+beside it is a second cadence that fires whenever the caller forgets the first. The
+specification path is REQUIRED on the wire (`registration-wire.md` §2.1) and the
+registry stores what it is sent, so a substituted path lands in `registry:services`
+for a service that never declared it. Both are refused at construction, by value —
+a string `'10000'` is not parsed into a cadence — naming the fix.
+
+**Callers must now pass both.** `@onlineapps/service-wrapper` passes
+`specificationEndpoint` already and does NOT pass `heartbeatInterval` (it runs its
+own heartbeat loop from `wrapper.registry.heartbeatInterval` and calls
+`sendHeartbeat()`); that value has to reach the constructor.
+
+#### `register()` and `deregister()` return what actually happened (d.278c)
+
+`register()` read the registry's reply and dropped two of its fields on the floor:
+`validationStatus` and `instructions` (`registration-wire.md` §2.5 — the parked
+registration, "you have not pre-validated yet" plus what to run about it). A caller
+saw `success: false` and nothing that explained it. Both are now passed through
+verbatim, like `errorCode`: a confirmed registration sends neither and both stay
+`undefined` — nothing is substituted.
+
+`deregister()` answered a hardcoded `{ success: true, message: 'Service deregistered
+successfully' }` whatever happened. The registry sends NO reply to a `deregister`
+(`registration-wire.md` §2.3), so there was no success to report — a claim about the
+registry made by the one party that never heard from it. It now returns what this
+call knows: `{ requestId, serviceName, version, publishedTo, heartbeatStopped,
+publishedAt }`. A publish that fails REJECTS; reaching the return means the broker
+took the message. There is no `success` key.
+
+### Fixed
+
+#### The integration tier connects with a credential (d.446b)
+
+`tests/config.js` composed the AMQP URI as `amqp://${host}:${port}` from
+`RABBITMQ_HOST` + `RABBITMQ_PORT` — a URI with no account, which the broker answers
+`403 ACCESS-REFUSED` to. 21 of the tier's 24 tests failed on it, on every run, for as
+long as the broker has required authentication. The tier now takes `RABBITMQ_URL`
+whole (credential included) and DERIVES host and port from it, so the address it
+probes in `integration/setup.js` is the address it then connects to. The banner it
+prints names host and port only.
+
+Two more reds went with them, both stale rather than broken: `readRegistrySpec()`
+asked `GET /services/<name>/spec`, a route `api_services_registry` stopped mounting
+when the `/services` alias went in batch 263c — so `status === 404` passed for the
+WRONG reason (a missing route, not a missing record) while the body assertion failed.
+It reads `/microservices/<name>/spec` now, the route `src/app.js` mounts. And the
+"nobody consumes the registry queue" failure path pointed at a queue that did not
+exist; since the publish path asks the broker whether the target exists, that is now
+a different (and faster) failure, so the harness declares the queue and leaves it
+unconsumed — the situation the timeout exists for.
+
+
+#### AMQP URL v hlášce i logu bez credentialu (d.446)
+
+`AMQP_URL` je jediná kolej pro heslo k brokeru, takže obě chybové cesty
+`QueueManager.init()` — timeout spojení i selhání `amqp.connect()` — vypisovaly to
+heslo doslova: URL šla do hlášky nezredigovaná. Chyba konektoru jde rovnou do logu
+služby a odtud do Loki, kde je trvalá a vyhledatelná. Táž třída úniku, kterou pro
+Redis zavřel `shared/service-common/src/redisClient.js`.
+
+Nově jde URL do hlášky přes `src/redactUrl.js`: userinfo (`uživatel:heslo@`) pryč,
+schéma, host, port i vhost zůstávají — to je, co čtenář logu potřebuje. Hodnota,
+kterou nelze přečíst jako URL, se nevypisuje vůbec, nahradí ji `<unparseable-url>`
+(neparsovatelný řetězec je právě ten případ, kdy nikdo neumí říct, jestli
+credential nese). Připojení samo dál používá původní URL — redakce se týká výhradně
+renderu do textu.
+
+Helper byl zprvu lokální (`src/redactUrl.js`): pinované závislosti balíčku tehdy
+žádnou redakci nevystavovaly. **Od d.446b je pryč** — `@onlineapps/mq-client-core`
+3.0.0 exportuje `redactUrl` i `UNPARSEABLE_PLACEHOLDER` s totožnou sémantikou
+(d.448, celé userinfo pryč), takže lokální kopie byla druhá kolej pro jeden koncept
+(`change-discipline.md` § One rail per concern). `QueueManager` ho importuje z jádra;
+identitu toho exportu drží test, a `tests/unit/redactUrl.test.js` (chování lokální
+kopie) odešel s ní.
+
+### Konstruktor klienta už nenese `registryUrl` (d.244)
+
+Parametr `registryUrl` i pole `this.registryUrl` zrušeny. Od konfirmace
+`biz-discovery-redis` 001 a commitu `725b25c2` se jen ukládaly a nikdo je nečetl
+(v `src/` žádný `axios`/`fetch`/`http.request`). Uložený nečtený parametr není
+neškodný: říkal každému volajícímu, že na té adrese něco závisí — a to drželo
+`REGISTRY_URL` jako povinný klíč v osmi biz konfiguracích. Konfirmace
+`biz-discovery-redis` 002.
+
+Volající, který `registryUrl` stále předá, ho dostane ignorovaný, ne uložený.
+JSDoc konstruktoru ho nikdy nepopisoval (změřeno), takže se tam nic nemazalo.
+Integrační tier balíčku `REGISTRY_URL` dál vyžaduje — čte jím HTTP API registru,
+aby ověřil, co registr uložil; to je testovací harness, ne klient.
+
+### `register()` nese `deployable` na drát (d.221)
+
+`register()` staví zprávu z pevného seznamu klíčů, takže klíč, který nejmenuje,
+se na drát nedostane — tiše. Nově jmenuje `deployable`: verdikt shody s manifestem
+(krok 7/7 validace), který registry promítá do `infrastructure:health:<service>`
+vedle `status` (potvrzení vlastníka
+`api/docs/governance/confirmations/biz-service-manifest.md` 001 §4). Přenáší se
+doslova ve všech třech stavech — `true`, `false`, `null` (běh konformitu nezměřil) —
+proto test přítomnosti klíče, ne pravdivosti hodnoty. Volající, který verdikt
+neposílá, nemá klíč ve zprávě; nic se za něj nedosazuje.
+
+## [3.0.1] — 2026-09-04
+
+- Changelog started with this release; the history before it is in git (`git log -- shared/connector/conn-orch-registry`).

package/README.md

@@ -25,11 +25,11 @@ Duty sections that apply:
 
 > A lightweight client for microservice registration and heartbeat over RabbitMQ.
 > Sends the full service specification (including `operations`) in the `register`
-> message — see [operations-registry-contract.md §2](../../../docs/biz/30-operations/registration-wire.md).
+> message — see [registration-wire.md §2](../../../docs/biz/30-operations/registration-wire.md).
 
 ## 🚀 Features
 
-* Automatic queue management (`workflow`, `<serviceName>.registry`, `api_services_queuer`, `registry.register`)
+* Automatic queue management (`workflow`, `<serviceName>.registry`, `<serviceName>.registry.<instanceId>`, `api_services_queuer`, `registry.register`)
 * Periodic heartbeat messages with metadata
 * Full specification (endpoints + operations) published inside `register`
 * Event-driven API using `EventEmitter`
@@ -63,15 +63,18 @@ const client = new ServiceRegistryClient({
   version: '1.0.0',
   specificationEndpoint: '/api/v1/specification', // required — see § Configuration
   heartbeatInterval: 30000,                        // required — see § Configuration
+  instanceId: process.env.SERVICE_INSTANCE_ID,     // required — THIS running copy; see § Configuration
   logger // required — see § Logger contract below
 });
 
 await client.init();
 
 // Publish full service spec in the register message (single round-trip).
+// Only the keys of the registration contract are accepted — endpoints, operations,
+// metadata, health, workspaceScoped, timeout; any other key is refused by name.
 await client.register({
   endpoints: [/* ... */],
-  operations: await loadOperationsJson(), // see operations-registry-contract.md §3
+  operations: await loadOperationsJson(), // see registration-wire.md §3
   metadata: { /* ... */ },
   health: '/health'
 });
@@ -104,6 +107,7 @@ Configuration can be provided via environment variables or constructor options:
 | `version`               | Service version in SemVer format (required)   | —                    |
 | `specificationEndpoint` | Path the `register`/`heartbeat` messages carry (**required**) | —    |
 | `heartbeatInterval`     | Milliseconds between heartbeats (**required**) | —                   |
+| `instanceId`            | Non-empty string naming THIS running copy, one value per process (**required**) | — |
 | `apiQueue`              | Queue name for heartbeat/API messages         | `api_services_queuer` |
 | `registryQueue`         | Queue name for registry requests              | `registry.register`  |
 
@@ -122,6 +126,14 @@ whenever the caller forgets the first (architecture-principles §3):
 
 Both are refused at construction, by value, naming the fix.
 
+**`instanceId` carries no default either** (d.817, owner confirmation
+`registry-instance-identity` 001). The service name says which service, the instance id
+says which copy; `register`, `heartbeat` and `deregister` carry it as `instance_id`, and
+the registry deletes a registration only when it matches. The client never makes one:
+`@onlineapps/service-wrapper` makes it once at boot (`SERVICE_INSTANCE_ID` when the
+deployment gives one, otherwise a UUID v4) and hands the same value to monitoring as
+`serviceInstanceId`.
+
 `amqpUrl` carries the broker credential, so no error message and no log line of this
 package renders it as given: the URL passes through `redactUrl` from
 `@onlineapps/logger-contract`, which drops the userinfo (`user:password@`) and keeps
@@ -132,8 +144,11 @@ implementace přestěhovala do core vrstvy; one concern, one rail.)
 
 ## 📬 Delivery of registry messages
 
-Both consumers in this package — the service's own `<service>.registry` response queue
-and the `<service>.registry.events` fanout copy — run on the delivery contract of
+The consumers in this package — the shared `<service>.registry` (the registry's own
+prompts, such as `revalidate`, heard by every copy), the answer queue of THIS copy
+`<service>.registry.<instanceId>` (named as `responseQueue` in `register`, so a copy
+never reads the answer meant for another — owner confirmation `registry-instance-identity`
+001 (c), d.817c) and the `<service>.registry.events` fanout copy — run on the delivery contract of
 [`@onlineapps/mq-client-core`](https://www.npmjs.com/package/@onlineapps/mq-client-core)
 (§ `consume()` — the delivery contract), registered with `requeueOnError: false`.
 
@@ -191,15 +206,25 @@ demands is a logger that component writes to). Standard:
 ### Register Request
 ```javascript
 {
+  id: "request-uuid",            // which request
+  instance_id: "copy-id",        // which running copy (the constructor's instanceId)
   type: "register",
   serviceName: "hello-service",
   version: "1.0.0",
-  token: "pre-validation-token",
+  specificationEndpoint: "/api/v1/specification",
   endpoints: [...],
+  operations: { ... },
+  metadata: { ... },
+  health: "/health",
+  responseQueue: "hello-service.registry.copy-id",   // THIS copy's answer queue (d.817c)
   timestamp: "ISO-8601"
+  // + workspaceScoped when the service declares it,
+  // + validationProof / validationData when a proof was injected
 }
 ```
 
+The wire format has one owner: `api/docs/biz/30-operations/registration-wire.md` §2.
+
 ### Register Confirmed
 ```javascript
 {
@@ -225,9 +250,12 @@ fixes it: `api/docs/biz/30-operations/registration-wire.md` §8.
 ### Heartbeat
 ```javascript
 {
+  id: "message-uuid",
   type: "heartbeat",
   serviceName: "hello-service",
-  status: "UP",
+  instance_id: "copy-id",
+  version: "1.0.0",
+  specificationEndpoint: "/api/v1/specification",
   timestamp: "ISO-8601"
 }
 ```