@onlineapps/conn-orch-registry 7.0.0 → 9.0.0

package/API.md

@@ -405,6 +405,7 @@ Events (see src/events.js):
         * [.subscribeToChanges()](#module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient+subscribeToChanges) ⇒ <code>Promise.&lt;void&gt;</code>
         * [.getService(serviceName)](#module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient+getService) ⇒ <code>Promise.&lt;(ServiceSummary\|null)&gt;</code>
         * [.close()](#module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient+close) ⇒ <code>Promise.&lt;void&gt;</code>
+    * [~DISCOVERY_FAILURE_CODES](#module_@onlineapps/conn-orch-registry/src/registryClient..DISCOVERY_FAILURE_CODES)
     * [~RETIRED_SERVICE_INFO_KEYS](#module_@onlineapps/conn-orch-registry/src/registryClient..RETIRED_SERVICE_INFO_KEYS)
     * [~ACCEPTED_SERVICE_INFO_KEYS](#module_@onlineapps/conn-orch-registry/src/registryClient..ACCEPTED_SERVICE_INFO_KEYS)
     * [~ServiceSummary](#module_@onlineapps/conn-orch-registry/src/registryClient..ServiceSummary) : <code>Object</code>
@@ -438,11 +439,12 @@ Events (see src/events.js):
 | opts.serviceName | <code>string</code> |  | Name of the service (e.g., 'invoicing') |
 | opts.version | <code>string</code> |  | Version of the service (e.g., '1.2.0') |
 | opts.specificationEndpoint | <code>string</code> |  | Path the `register` and `heartbeat` messages   carry. REQUIRED: the wire format declares it required   (api/docs/biz/30-operations/registration-wire.md §2.1) and the registry stores what it   is sent, so a default here would write a path nobody configured into `registry:services`. |
-| opts.heartbeatInterval | <code>number</code> |  | Milliseconds between heartbeats. REQUIRED: the   cadence has ONE owner and it is not a library default (owner confirmation   docs/governance/confirmations/biz-health-freshness.md 001 point 3); ServiceWrapper   passes `wrapper.registry.heartbeatInterval`, itself fed from BIZ_HEARTBEAT_INTERVAL_MS. |
+| opts.heartbeatInterval | <code>number</code> |  | Milliseconds between heartbeats. REQUIRED: the   cadence has ONE owner and it is not a library default (owner confirmation   docs/governance/confirmations/biz-health-freshness.md 001 point 3); ServiceWrapper   reads it from the environment key BIZ_HEARTBEAT_INTERVAL_MS and passes it here. The   config key `wrapper.registry.heartbeatInterval` is retired and the wrapper refuses it. |
 | [opts.apiQueue] | <code>string</code> | <code>&quot;&#x27;api_services_queuer&#x27;&quot;</code> | Queue name for heartbeat and API traffic |
 | [opts.registryQueue] | <code>string</code> | <code>&quot;&#x27;registry.register&#x27;&quot;</code> | Queue name for registry messages |
 | [opts.validationProof] | <code>Object</code> | <code></code> | Validation proof object {hash, data} (injected from outside) |
 | [opts.registrationTimeoutMs] | <code>number</code> |  | How long register() waits for the registry response   before rejecting. Default comes from ./defaults.js (30000 ms); never read from the environment here. |
+| opts.discoveryTimeoutMs | <code>number</code> |  | How long ONE discovery read (`getService()`)   may wait for the registry projection before it is refused as `TRANSIENT`. REQUIRED,   no module default: the value belongs to the platform (ServiceWrapper reads it from   the platform env) and bounds how long a workflow step can hang on a Redis that is   down or half-open (d.1090, d.1093). Enforced as a race beside the command, never as   node-redis' `AbortSignal` (see `getService()` for why). |
 | opts.logger | <code>Object</code> |  | Logger with info/warn/error/debug. Required and validated here:   registration, heartbeat and revalidation events are what this client exists to report, and   until 2026-09-05 they went to stdout through bare printing while this parameter was accepted   and never read. Owner confirmation:   docs/governance/confirmations/connector-logger-contract.md 001 + 002. |
 
 <a name="module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient+init"></a>
@@ -494,6 +496,12 @@ What this call knows, and therefore what it returns: the request it published,
 where it published it, and that the heartbeat timer is stopped. A publish that
 fails REJECTS; reaching the return means the broker took the message.
 
+The heartbeat loop stops FIRST, before anything is published. A heartbeat is
+the claim "this copy is alive"; a caller that deregisters has decided it is
+leaving, and that decision does not wait for the broker. Until d.1083 the loop
+stopped only after a successful publish, so a rejected deregistration left it
+beating for a service on its way out.
+
 **Kind**: instance method of [<code>ServiceRegistryClient</code>](#module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient)  
 <a name="module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient+unregister"></a>
 
@@ -518,9 +526,10 @@ consecutive failures.
 
 A heartbeat loop with no budget is worse than none: the beats stop reaching
 the registry, the loop logs and reschedules forever, and the service keeps
-running while every consumer of `registry:services` reads it as stale. Until
-2026-09-15 that budget lived in `@onlineapps/service-wrapper`, in a second
-loop around `sendHeartbeat()` — two loops for one cadence
+running while every consumer of `registry:services` reads it as stale. The
+budget lives here and nowhere else: `@onlineapps/service-wrapper` arms this
+loop and runs none of its own (service-wrapper d.1076, its CHANGELOG) — two
+loops for one cadence would be two rails for one concern
 (`.claude/rules/change-discipline.md` § One rail per concern).
 
 The cadence is NOT an argument here. It has one owner and it is the
@@ -579,6 +588,18 @@ Creates event consumer and starts listening to registry.changes exchange
 Releases resources: stops heartbeat and closes connection.
 
 **Kind**: instance method of [<code>ServiceRegistryClient</code>](#module_@onlineapps/conn-orch-registry/src/registryClient..ServiceRegistryClient)  
+<a name="module_@onlineapps/conn-orch-registry/src/registryClient..DISCOVERY_FAILURE_CODES"></a>
+
+### @onlineapps/conn-orch-registry/src/registryClient~DISCOVERY\_FAILURE\_CODES
+The two ways a discovery read can fail that say nothing about the answer — the
+projection did not answer in time, or the client already knows Redis is gone. Both
+are typed HERE, where the failure is known, as `TRANSIENT` (d.1093; the pattern
+mq-client-core uses since d.683: a bare error from the transport is typed by the
+site that receives it, `src/utils/publishErrors.js` `TransientPublishError`). The
+L1 classifier reads `type` and never learns what Redis is; cookbook-router carries
+`type` from `cause` onto `SERVICE_DISCOVERY_FAILED`.
+
+**Kind**: inner constant of [<code>@onlineapps/conn-orch-registry/src/registryClient</code>](#module_@onlineapps/conn-orch-registry/src/registryClient)  
 <a name="module_@onlineapps/conn-orch-registry/src/registryClient..RETIRED_SERVICE_INFO_KEYS"></a>
 
 ### @onlineapps/conn-orch-registry/src/registryClient~RETIRED\_SERVICE\_INFO\_KEYS

package/CHANGELOG.md

@@ -4,6 +4,144 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [9.0.0] — 2026-10-12
+
+### Changed — BREAKING — zděděné chování `@onlineapps/mq-client-core` 6.0.0 (platí s pinem 6.0.0, který přijde s vydáním jádra; d.1361, d.1363)
+
+`QueueManager` je tenký průchod k `BaseClient` jádra — `publish()` (`src/queueManager.js:225-226`)
+a `consume()` (`:242-243`) předávají volání i odmítnutí beze změny. Z jádra tenhle balíček nic
+znovu nevydává (`src/index.js`: `ServiceRegistryClient`, `RegistryEventConsumer`, `EVENTS`) a
+konfiguraci jádra nepropouští (`BaseClient` se staví s pevnými klíči `type`, `host`,
+`serviceName`, `logger`, `src/queueManager.js:73-78`), takže odebrání `criticalHealthShutdown`
+a `health:shutdown` (jádro d.1275) volajícího nezasáhne. Co z CHANGELOGu jádra projde k
+volajícímu veřejnými metodami `ServiceRegistryClient`, jakmile se pin `@onlineapps/mq-client-core`
+zvedne z 5.1.0 na 6.0.0 (zdejší kód se nemění):
+
+- **`sendHeartbeat()` a `deregister()` propouštějí `PublishError` jádra neobalený**
+  (`src/registryClient.js:931`, `:880`; volby `{ persistent: true }`, tedy výchozí
+  `bufferOnFailure: true`). S jádrem 6.0.0 (d.1300): publish, jehož čekání na obnovu skončí
+  standby (vyčerpaný cyklus), odmítne `PublishError` s `buffered: true`, `sent: false` — dřív
+  bez `buffered` — a zprávu DRŽÍ v bufferu; přehraje ji po příštím `reconnected`/`unblocked`.
+  Skončí-li obnova fatálně, nese chyba `code: 'MQ_CONNECTION_FATAL'` a `reason`
+  (`'cycles-spent'` | `'broker-refused'`) přímo na sobě; nic se nedrží. Volající, který po
+  odmítnutí posílal heartbeat nebo deregistraci znovu sám, ji teď může poslat dvakrát.
+  Smyčka `startHeartbeat()` počítá odmítnutý beat jako selhání dál stejně (obal s `cause`).
+- **`init()` předává `code`/`reason` chyby `consume()` na svůj obal** (`src/registryClient.js:305`
+  → `_startRegistryConsumer`, `:370-371`). S jádrem 6.0.0 (d.1297) nese chyba `consume()` po
+  fatálním cyklu `code: 'MQ_CONNECTION_FATAL'` a `reason` NAHOŘE (dřív jen v `cause`, obal měl
+  `code` `undefined`). Volající, který podle `error.code` rozhoduje — `@onlineapps/service-wrapper`
+  v bootu (`ServiceWrapper.js`, větve `error.code !== 'MQ_CONNECTION_FATAL'`) — bere týž výpadek
+  jako TRVALÝ konec bootu, ne přechodný. Standby, `disconnect()` a `reconnectEnabled: false`
+  `code` dál nenesou.
+- **`register()` — zpráva držená přes standby se přehraje i po odmítnutí** (`src/registryClient.js:777`,
+  `:798-801`). `register()` chybu publishe obaluje (`Failed to send registration message: <věta
+  jádra>`, bez `code`) a čekající registraci zruší; zprávu `register`, kterou jádro 6.0.0 po
+  standby drží (d.1300), ale po reconnectu přehraje — registr tak dostane registraci, o které
+  volající ví, že selhala; její odpověď skončí řádkem WARN
+  „Registration response has no matching pending request“ (`:519`). Sousední cesta (přechodná chyba →
+  čekání na běžící reconnect → selhání) držela zprávu už v 5.1.0; 6.0.0 přidává standby.
+
+Precedent: `@onlineapps/conn-infra-mq` `[Unreleased]` „BREAKING — zděděné chování
+`@onlineapps/mq-client-core` 6.0.0“ a `@onlineapps/conn-orch-cookbook` `[7.0.0]`. Rozhodnutí
+leada d.1361: major 9.0.0.
+
+### Tests — brána „broker pod alarmem“ IT tieru má jedno tělo v repu (d.1326)
+
+- `refuseBrokerUnderAlarm` z `tests/integration/setup.js` (originál, d.775/d.783) přesunut do
+  `api/scripts/tests/brokerAlarm.js` vedle `sweepOrphanQueues.js` (d.1320), kam z tohoto tieru
+  odešel i sweep; `setup.js` ho volá `refuseBrokerUnderAlarm({ ask: mgmtReader(config), context,
+  where })` — čtenář zůstává zdejší `mgmtReader` (rozpočet `withinBudget`). Věta odmítnutí beze
+  změny tvrzení (`environmentProbe.integration.test.js`: `[conn-orch-registry/integration] The
+  broker is under a resource alarm and is blocking publishers`, `memory on rabbit@…`, `HTTP 503
+  from <host:port>`); `Fix` nově jmenuje i `rabbitmq-diagnostics -q alarms`.
+- Čtyři otázky `change-discipline.md` § Removing (za všechny tři kopie): četl je jen `setup.js`
+  každého tieru (+ unit testy wrapperu a mq-client-core); psal je každý tier zvlášť (tři
+  implementace, měřeno `diff`); nahrazuje je jedno tělo s injektovaným čtenářem; porušení se
+  pozná větou alarmu v globalSetup tieru před prvním testem (IT `environmentProbe` to drží stubem).
+
+## [8.0.0] — 2026-10-03
+
+pin: `@onlineapps/mq-client-core` 5.0.0 → 5.1.0
+
+### Changed — BREAKING: `discoveryTimeoutMs` je povinný, `getService()` má termín a typuje selhání (d.1093)
+
+- Nový povinný parametr konstruktoru `discoveryTimeoutMs` (kladné číslo ms, bez výchozí hodnoty;
+  chybějící i neplatná hodnota se odmítne při konstrukci). Hodnota patří platformnímu env, čte ji
+  `@onlineapps/service-wrapper`.
+- `getService()` dřív při ležícím nebo půlotevřeném Redisu čekal bez termínu (node-redis drží příkaz
+  v offline frontě nebo čeká na odpověď, d.1088, d.1090) a krok workflow visel, dokud broker po
+  `consumer_timeout` nezavřel kanál a zpráva neexpirovala do DLQ. Nově:
+  - dotaz, který neskončí do `discoveryTimeoutMs` → `Error` s `code: 'REGISTRY_DISCOVERY_TIMEOUT'`,
+    `type: 'TRANSIENT'`, `serviceName`, bez `cause` (nic pod ním neselhalo);
+  - odmítnutí, když klient hlásí `isReady === false` (offline s `disableOfflineQueue`, socket zavřený
+    pod příkazem) → `code: 'REGISTRY_DISCOVERY_UNAVAILABLE'`, `type: 'TRANSIENT'`, původní chyba v `cause`;
+  - jiné odmítnutí (chybová odpověď připojeného Redisu) projde beze změny.
+  Typuje se tady, kde je selhání známé (vzor mq-client-core d.683); `@onlineapps/cookbook-router`
+  převezme `type` z `cause`, klasifikátor L1 Redis nezná.
+- **Proč termín závodem a ne `AbortSignal`:** node-redis 4.7.1 (`@redis/client` 1.6.1) nabízí
+  `commandOptions({ signal })`, ale abort příkazu, který už odešel na server, odebere jeho uzel z fronty
+  podruhé (posluchač abortu zůstane po odeslání připojený), délka fronty klesne pod nulu a další
+  `flushAll` — chyba socketu při `disableOfflineQueue`, nebo `disconnect()` — hodí
+  `TypeError: Cannot read properties of undefined (reading 'reject')`; z handleru chyby socketu je to
+  nezachycená výjimka, která ukončí proces (změřeno d.1093 proti falešnému RESP serveru). Závod příkaz
+  nechá ve frontě: pozdní odpověď se spáruje správně a jeho pozdní odmítnutí se zachytí a zaloguje
+  (`debug`), nikdy nezůstane neošetřené.
+- devDependency `redis` 4.7.1 (přesně) pro integrační sadu `tests/integration/discoveryDeadline.integration.test.js`
+  (živý node-redis proti falešnému RESP serveru; dev Redis se nedotýká).
+
+### Fixed — `deregister()` zastaví heartbeat PŘED publikací, ne až po ní (d.1083)
+
+Smyčka se dřív zastavovala až po úspěšné publikaci zprávy `deregister`; když publikace selhala,
+volání odmítlo, ale smyčka tepala dál za kopii, která se odhlašuje. `stopHeartbeat()` je teď první
+krok `deregister()`, ať publikace dopadne jakkoli. Úspěšná deregistrace se chová stejně jako dřív
+(zpráva odejde, `heartbeatStopped: true`). Sada `tests/unit/registryClient.deregisterStopsHeartbeat.test.js`.
+`@onlineapps/service-wrapper` zastavuje smyčku v `shutdown()` sám před `unregister()` (d.1076), pro něj
+je změna neutrální.
+
+### Documentation — docblocky `startHeartbeat` a konstruktoru (`heartbeatInterval`) říkají pravdu (d.1083)
+
+`startHeartbeat`: rozpočet selhání žije jen tady, wrapper smyčku zapíná a vlastní nemá (odkaz na
+service-wrapper d.1076 a jeho CHANGELOG místo ručně psaného data). `opts.heartbeatInterval`: wrapper
+kadenci čte z env `BIZ_HEARTBEAT_INTERVAL_MS`; klíč `wrapper.registry.heartbeatInterval` je zrušený
+a wrapper ho odmítá. `API.md` přegenerován (`npm run docs`). Tutéž pravdu teď říká i `Fix:` hlášky
+konstruktoru při chybějícím `heartbeatInterval` (dřív radila právě zrušený klíč; test
+`registryClient.registryAnswer.test.js` tvrdí celou `Fix:` větu), `README.md` (vlastník kadence)
+a hlavička sady `registryClient.registryAnswer.test.js`.
+
+### Documentation — `examples/` srovnané na kontrakt 8.0.0 (d.1187)
+
+Oba příklady stavěly klienta, kterého konstruktor odmítne: chyběl `instanceId` (d.817) a
+`discoveryTimeoutMs` (d.1093), `event-consumer-example.js` navíc `specificationEndpoint` a
+`heartbeatInterval` (d.278c). Registrovaly operace ve tvaru v2 (`endpoint`, `method`, neprázdné
+`endpoints`), který registr odmítá (`schema-v3.md` § Keys the v3 schema rejects). Nově:
+- každá povinná volba je zapsaná výslovně; nastavení se čte z env podle jména (klíče platformy:
+  `RABBITMQ_URL`, `REDIS_URL`, `SERVICE_INSTANCE_ID`, `BIZ_HEARTBEAT_INTERVAL_MS`,
+  `REGISTRY_DISCOVERY_TIMEOUT_MS`, …) přes `examples/env.js`, který chybějící, prázdný nebo
+  nečíselný klíč odmítne s `Fix:`; žádný `||` fallback (dřív `REDIS_HOST || 'localhost'`,
+  `MINIO_ACCESS_KEY || 'minioadmin'` aj.);
+- operace ve tvaru v3 (`handler`, `bundle_scope`, `mutates`, `resource_type`, `minRole`, `input`,
+  `output`), `endpoints: []`, `metadata: { version, description }`;
+- `register()` se větví podle verdiktu registru (`success`, `errorCode`), ne podle událostí
+  `registerConfirmed`/`registerRejected`, které klient nevysílá; ukončení volá `deregister()` před
+  `close()`;
+- `event-consumer-example.js` běží v režimu jen-index bez `storageConfig`: `subscribeToChanges()`
+  staví konzumenta bez `StorageConnector` a úplný `storageConfig` by konstruktor
+  `RegistryEventConsumer` odmítl; Redis je node-redis (`createClient`), tentýž klient, kterým
+  `getService()` čte projekci.
+- devDependency `ioredis` odebrána: jejím jediným čtenářem byl `event-consumer-example.js`.
+- `README.md` § Quick Start čte `instanceId` přes `requireEnv` jako příklady, ne jako holé
+  `process.env.SERVICE_INSTANCE_ID` (d.1187b); `amqpUrl` přes `requireEnv('RABBITMQ_URL', …)` místo
+  holého `process.env.AMQP_URL`, `heartbeatInterval` a `discoveryTimeoutMs` z klíčů platformy
+  `BIZ_HEARTBEAT_INTERVAL_MS` a `REGISTRY_DISCOVERY_TIMEOUT_MS` místo čísel napsaných v kódu;
+  § Configuration už netvrdí, že se konfigurace dá předat proměnnými prostředí (klient žádnou
+  nečte) (d.1187c).
+
+Nová sada `tests/unit/examples.contract.test.js`: každý příklad projde `node --check`, nenese `||`
+ani `??`, nedeklaruje klíč operace v2 a konstruktoru předá všechny povinné volby jménem, žádnou jako
+holé `process.env`. Seznam povinných voleb sada sama ověří proti konstruktoru (bez kterékoli z nich
+konstrukce selže a hláška ji jmenuje), takže nová povinná volba sadu shodí dřív, než ji příklad tiše
+vynechá. Příklady sada nespouští (připojují se k RabbitMQ a Redisu).
+
 ## [7.0.0] — 2026-09-27
 
 pin: `@onlineapps/mq-client-core` 4.2.0 → 5.0.0

package/README.md

@@ -6,7 +6,7 @@ Uniform: [library/orchestration](../conn-orch-validator/manifests/library.manife
 
 Duty sections that apply:
 
-- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
+- `all`: L-MAIN, L-ENGINES, L-TESTS, L-TEST-SCRIPT, L-PACK-TESTS, L-PINS, L-NO-FILE-RANGE, L-CHANGELOG, L-PACK-CHANGELOG, L-README, L-README-REGION, L-CONSUMER
 <!-- END GENERATED: library-uniform -->
 
 # @onlineapps/conn-orch-registry
@@ -56,14 +56,17 @@ yarn add @onlineapps/conn-orch-registry
 // NOTE: Do NOT call dotenv.config() in libraries. Export environment variables explicitly.
 
 const { ServiceRegistryClient, EVENTS } = require('@onlineapps/conn-orch-registry');
+// requireEnv(name, description), requirePositiveIntegerEnv(name, description) — see examples/env.js
 
 const client = new ServiceRegistryClient({
-  amqpUrl: process.env.AMQP_URL,
+  amqpUrl: requireEnv('RABBITMQ_URL', 'RabbitMQ URL, amqp://user:pass@host:port'),
   serviceName: 'invoicing',
   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
+  heartbeatInterval: requirePositiveIntegerEnv('BIZ_HEARTBEAT_INTERVAL_MS', 'milliseconds between heartbeats'), // required; see § Configuration
+  instanceId: requireEnv('SERVICE_INSTANCE_ID', 'id of THIS running copy, one value per process'), // required; see § Configuration
+  discoveryTimeoutMs: requirePositiveIntegerEnv('REGISTRY_DISCOVERY_TIMEOUT_MS', 'deadline in ms of one getService() read'), // required; see § Configuration
+  redis,                                           // node-redis client getService() reads the projection with
   logger // required — see § Logger contract below
 });
 
@@ -98,7 +101,7 @@ process.on('SIGINT', async () => {
 
 ## 📄 Configuration
 
-Configuration can be provided via environment variables or constructor options:
+Configuration is passed as constructor options; the client reads no environment variable:
 
 | Option                  | Description                                   | Default              |
 | ----------------------- | --------------------------------------------- | -------------------- |
@@ -108,6 +111,7 @@ Configuration can be provided via environment variables or constructor options:
 | `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**) | — |
+| `discoveryTimeoutMs`    | Deadline (ms) of one `getService()` read of the registry projection (**required**) | — |
 | `apiQueue`              | Queue name for heartbeat/API messages         | `api_services_queuer` |
 | `registryQueue`         | Queue name for registry requests              | `registry.register`  |
 
@@ -119,13 +123,24 @@ whenever the caller forgets the first (architecture-principles §3):
   ([registration-wire.md](/api/docs/biz/30-operations/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;
-* the heartbeat cadence has ONE owner — `wrapper.registry.heartbeatInterval`, fed from
-  `BIZ_HEARTBEAT_INTERVAL_MS` (owner confirmation
+* the heartbeat cadence has ONE owner — the environment key `BIZ_HEARTBEAT_INTERVAL_MS`,
+  which `ServiceWrapper` reads and passes to this client; the config key
+  `wrapper.registry.heartbeatInterval` is retired and refused (owner confirmation
   [`biz-health-freshness.md`](/api/docs/governance/confirmations/biz-health-freshness.md)
   001 point 3) — and the freshness window the monitoring side computes is a multiple of it.
 
 Both are refused at construction, by value, naming the fix.
 
+**`discoveryTimeoutMs` carries no default** (d.1093). Without a deadline `getService()`
+waited for as long as Redis was down or half-open, and the workflow step waiting on it hung
+until the broker expired its message. The value belongs to the platform env, which
+`ServiceWrapper` reads and passes here. A lookup that does not end in time is refused with
+`code: 'REGISTRY_DISCOVERY_TIMEOUT'`, and a client that already knows Redis is gone
+(`isReady === false`) with `code: 'REGISTRY_DISCOVERY_UNAVAILABLE'` — both `type: 'TRANSIENT'`,
+so the step is retried. The deadline is a race beside the command, not node-redis'
+`AbortSignal`: aborting a command node-redis 4.7.1 has already sent corrupts its command
+queue (see the CHANGELOG entry of d.1093).
+
 **`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

package/examples/basicUsage.js

@@ -1,58 +1,43 @@
 /**
  * basicUsage.js
  *
- * Example demonstrating full lifecycle of ServiceRegistryClient:
- * 1. Load environment variables
- * 2. Instantiate client
- * 3. Initialize (setup queues and start listening for responses)
- * 4. Register with the full service specification (endpoints + operations)
- * 5. Start heartbeat loop
- * 6. Graceful shutdown on process signals
+ * The lifecycle of ServiceRegistryClient:
+ * 1. read the settings from the environment (examples/env.js)
+ * 2. construct the client with every required option
+ * 3. init() — the response queues and their consumers
+ * 4. register() the service specification and branch on the registry's verdict
+ * 5. startHeartbeat() with its failure budget
+ * 6. on SIGINT/SIGTERM: deregister() this copy, then close()
  *
- * See: api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
+ * Environment: RABBITMQ_URL, SERVICE_NAME, SERVICE_VERSION, SPECIFICATION_ENDPOINT,
+ * SERVICE_INSTANCE_ID, BIZ_HEARTBEAT_INTERVAL_MS, REGISTRY_DISCOVERY_TIMEOUT_MS.
+ *
+ * @see README.md § Configuration
+ * @see api/docs/biz/30-operations/registration-wire.md §2 MQ wire format
  */
 
-function requireEnv(name, description) {
-  const value = process.env[name];
-  if (!value || String(value).trim() === '') {
-    throw new Error(`[conn-orch-registry][example] Missing environment variable - ${name} is required. ${description || ''}`);
-  }
-  return String(value).trim();
-}
-
 // Requiring the package by its own name does not resolve from inside the package
-// (no self-reference `exports` field), so the example loads the sources directly —
-// same as examples/event-consumer-example.js. Consumers require
-// '@onlineapps/conn-orch-registry'; see README § Quick Start.
+// (no self-reference `exports` field), so the example loads the sources directly.
+// Consumers require '@onlineapps/conn-orch-registry'; see README § Quick Start.
 const { ServiceRegistryClient, EVENTS } = require('../src/index');
+const { requireEnv, requirePositiveIntegerEnv } = require('./env');
 
-// The logger is a hard requirement of every constructor in this package
-// (README § Logger contract). An example script has no service logger, so it passes
-// `console` explicitly — it implements info/warn/error/debug, and choosing it here is
-// the caller's decision, not a fallback inside the library.
+// The logger is required by every constructor in this package (README § Logger
+// contract). An example script has no service logger, so it passes `console`
+// explicitly — it implements info/warn/error/debug.
 const registryClient = new ServiceRegistryClient({
   logger: console,
-  amqpUrl: requireEnv('AMQP_URL', 'RabbitMQ URL (IPv4-only recommended: amqp://user:pass@127.0.0.1:PORT)'),
-  serviceName: requireEnv('SERVICE_NAME', 'Service logical name'),
-  version: requireEnv('SERVICE_VERSION', 'Service version (SemVer)'),
-  // Both REQUIRED since d.278c — the client substitutes neither, so the example
-  // demands them the same way it demands the URL and the service name.
-  specificationEndpoint: requireEnv('SPECIFICATION_ENDPOINT', 'Path the register message carries (e.g. /api/v1/specification)'),
-  heartbeatInterval: parseInt(requireEnv('HEARTBEAT_INTERVAL', 'Milliseconds between heartbeats'), 10),
-  apiQueue: process.env.API_QUEUE,
-  registryQueue: process.env.REGISTRY_QUEUE
+  amqpUrl: requireEnv('RABBITMQ_URL', 'RabbitMQ URL, amqp://user:pass@host:port'),
+  serviceName: requireEnv('SERVICE_NAME', 'service logical name'),
+  version: requireEnv('SERVICE_VERSION', 'service version, SemVer'),
+  specificationEndpoint: requireEnv('SPECIFICATION_ENDPOINT', 'path the register and heartbeat messages carry, e.g. /api/v1/specification'),
+  instanceId: requireEnv('SERVICE_INSTANCE_ID', 'id of THIS running copy, one value per process'),
+  heartbeatInterval: requirePositiveIntegerEnv('BIZ_HEARTBEAT_INTERVAL_MS', 'milliseconds between heartbeats'),
+  discoveryTimeoutMs: requirePositiveIntegerEnv('REGISTRY_DISCOVERY_TIMEOUT_MS', 'deadline in ms of one getService() read')
 });
 
 registryClient.on(EVENTS.HEARTBEAT_SENT, (msg) => {
-  console.log(`[Heartbeat] Sent at ${msg.timestamp} for ${msg.serviceName}@${msg.version}`);
-});
-
-registryClient.on(EVENTS.REGISTER_CONFIRMED, (msg) => {
-  console.log(`[Register] Confirmed for ${msg.serviceName || registryClient.serviceName}`);
-});
-
-registryClient.on(EVENTS.REGISTER_REJECTED, (msg) => {
-  console.error('[Register] Rejected', msg);
+  console.log(`[Heartbeat] Sent at ${msg.timestamp} for ${msg.serviceName}@${msg.version} (${msg.instance_id})`);
 });
 
 registryClient.on(EVENTS.REVALIDATE, (payload) => {
@@ -68,8 +53,15 @@ registryClient.on(EVENTS.ERROR, (err) => {
     await registryClient.init();
     console.log('RegistryClient initialized: queues are ready.');
 
-    await registryClient.register(await loadServiceSpec());
-    console.log('Register message published.');
+    // register() resolves with the registry's verdict; `errorCode` is the machine
+    // reason of a refusal (registration-wire.md §8).
+    const verdict = await registryClient.register(serviceSpecification(registryClient.version));
+    if (verdict.success !== true) {
+      console.error(`[Register] Refused: ${verdict.errorCode} - ${verdict.message}`);
+      await registryClient.close();
+      process.exit(1);
+    }
+    console.log(`[Register] Confirmed for ${verdict.serviceName}@${verdict.version}`);
 
     registryClient.startHeartbeat({
       maxFailures: 5,
@@ -82,53 +74,55 @@ registryClient.on(EVENTS.ERROR, (err) => {
 
     const shutdown = async () => {
       console.log('Shutting down RegistryClient...');
+      // deregister() stops the heartbeat first; the registry deletes only the
+      // registration whose instance_id matches this copy.
+      await registryClient.deregister();
       await registryClient.close();
       process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
   } catch (err) {
-    console.error('Failed to initialize RegistryClient', err);
+    console.error('Failed to run RegistryClient', err);
     process.exit(1);
   }
 })();
 
 /**
- * Helper: assemble the service specification published in the register message.
- * In a real service this is typically loaded from config/service/operations.json
- * plus the endpoint manifest.
+ * The service specification the register message carries. A real service sends the
+ * `operations` map of its config/service/operations.json; every operation is a v3
+ * declaration.
  *
- * @see api/docs/biz/30-operations/registration-wire.md §3 Operation schema
+ * @param {string} version - the service version the metadata repeats
+ * @see api/docs/biz/30-operations/schema-v3.md § Per-operation keys
+ * @see api/docs/biz/30-operations/registration-wire.md §2.1
  */
-async function loadServiceSpec() {
+function serviceSpecification(version) {
   return {
-    endpoints: [
-      { path: '/invoices', method: 'POST' },
-      { path: '/invoices/:id', method: 'GET' }
-    ],
+    endpoints: [],
     operations: {
       'create-invoice': {
         description: 'Create a new invoice',
-        endpoint: '/invoices',
-        method: 'POST',
+        handler: 'handlers/invoices#createInvoice',
+        bundle_scope: 'workspace',
         mutates: true,
         resource_type: 'invoice',
         minRole: 'EDITOR',
-        input: {},
-        output: {}
+        input: { type: 'object' },
+        output: { type: 'object' }
       },
       'get-invoice': {
-        description: 'Retrieve invoice by ID',
-        endpoint: '/invoices/:id',
-        method: 'GET',
+        description: 'Retrieve an invoice by id',
+        handler: 'handlers/invoices#getInvoice',
+        bundle_scope: 'workspace',
         mutates: false,
-        resource_type: null,
+        resource_type: 'invoice',
         minRole: 'VIEWER',
-        input: {},
-        output: {}
+        input: { type: 'object' },
+        output: { type: 'object' }
       }
     },
-    metadata: {},
+    metadata: { version, description: 'Invoice example' },
     health: '/health'
   };
 }

package/examples/env.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * env.js — how the examples read their settings: by key name, and a key that is
+ * missing or malformed stops the example naming the key and the fix. No default
+ * stands in for an unset key (architecture-principles.md §3, §5).
+ *
+ * The key names are the platform's own (`config/env-templates/shared.env`), so an
+ * example runs with the same environment a biz service gets.
+ */
+
+/**
+ * @param {string} name - environment key
+ * @param {string} description - what the value is, for the error message
+ * @returns {string} the trimmed value
+ * @throws {Error} when the key is unset or blank
+ */
+function requireEnv(name, description) {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new Error(
+      `[conn-orch-registry][example] Missing environment variable - ${name} is required (${description}). `
+      + `Fix: export ${name} before running the example.`
+    );
+  }
+  if (value.trim() === '') {
+    throw new Error(
+      `[conn-orch-registry][example] Empty environment variable - ${name} is set but blank (${description}). `
+      + `Fix: export ${name} with a value.`
+    );
+  }
+  return value.trim();
+}
+
+/**
+ * @param {string} name - environment key
+ * @param {string} description - what the value is, for the error message
+ * @returns {number} a positive whole number
+ * @throws {Error} when the key is unset, blank, not a whole number or not positive
+ */
+function requirePositiveIntegerEnv(name, description) {
+  const raw = requireEnv(name, description);
+  const value = Number(raw);
+  if (!Number.isInteger(value)) {
+    throw new Error(
+      `[conn-orch-registry][example] Invalid environment variable - ${name} is ${JSON.stringify(raw)}. `
+      + `Expected: a positive whole number (${description}). Fix: export ${name} as a whole number.`
+    );
+  }
+  if (value <= 0) {
+    throw new Error(
+      `[conn-orch-registry][example] Invalid environment variable - ${name} is ${value}. `
+      + `Expected: a positive whole number (${description}). Fix: export ${name} above zero.`
+    );
+  }
+  return value;
+}
+
+module.exports = { requireEnv, requirePositiveIntegerEnv };

package/examples/event-consumer-example.js

@@ -1,81 +1,85 @@
 /**
- * Example: Using ServiceRegistryClient with event consumption
+ * event-consumer-example.js
  *
- * Demonstrates opt-in subscription to registry change events. The events are an
- * invalidation hint ("something changed"), not a read path: to read another
- * service's spec, use createRegistryReader from @onlineapps/service-common.
+ * What this example shows: a client that registers, beats, and opts in to the
+ * registry change events through subscribeToChanges(), with listeners for them.
  *
- * @see api/docs/biz/30-operations/registration-wire.md §5, §7
+ * The consumer runs in index-only mode: no storageConfig, because
+ * subscribeToChanges() (src/registryClient.js) builds it without a StorageConnector
+ * and the RegistryEventConsumer constructor refuses a complete storageConfig
+ * without one. Redis persists the local service index.
+ *
+ * Environment: RABBITMQ_URL, REDIS_URL, SERVICE_NAME, SERVICE_VERSION,
+ * SPECIFICATION_ENDPOINT, SERVICE_INSTANCE_ID, BIZ_HEARTBEAT_INTERVAL_MS,
+ * REGISTRY_DISCOVERY_TIMEOUT_MS.
+ *
+ * @see README.md § Configuration
+ * @see api/docs/biz/30-operations/registration-wire.md §7
  */
 
+const { createClient } = require('redis');
 const { ServiceRegistryClient } = require('../src/index');
-const Redis = require('ioredis');
+const { requireEnv, requirePositiveIntegerEnv } = require('./env');
 
 async function main() {
-  // Optional Redis for index persistence
-  const redis = new Redis({
-    host: process.env.REDIS_HOST || 'localhost',
-    port: process.env.REDIS_PORT || 6379
+  // node-redis, the client getService() reads the registry projection with.
+  const redis = createClient({
+    url: requireEnv('REDIS_URL', 'Redis URL, redis://:password@host:port'),
+    disableOfflineQueue: true
   });
+  await redis.connect();
 
-  // Initialize client with storage configuration
-  // The logger is a hard requirement of every constructor in this package
-  // (README § Logger contract). An example script has no service logger, so it passes
-  // `console` explicitly — it implements info/warn/error/debug, and choosing it here is
-  // the caller's decision, not a fallback inside the library.
+  // The logger is required by every constructor in this package (README § Logger
+  // contract). An example script has no service logger, so it passes `console`
+  // explicitly — it implements info/warn/error/debug.
   const client = new ServiceRegistryClient({
     logger: console,
-    amqpUrl: process.env.AMQP_URL || 'amqp://localhost',
-    serviceName: 'example-service',
-    version: '1.0.0',
-    redis: redis,
-    storageConfig: {
-      endPoint: process.env.MINIO_ENDPOINT || 'localhost',
-      port: parseInt(process.env.MINIO_PORT || 9000),
-      useSSL: process.env.MINIO_USE_SSL === 'true',
-      accessKey: process.env.MINIO_ACCESS_KEY || 'minioadmin',
-      secretKey: process.env.MINIO_SECRET_KEY || 'minioadmin'
-    }
+    amqpUrl: requireEnv('RABBITMQ_URL', 'RabbitMQ URL, amqp://user:pass@host:port'),
+    serviceName: requireEnv('SERVICE_NAME', 'service logical name'),
+    version: requireEnv('SERVICE_VERSION', 'service version, SemVer'),
+    specificationEndpoint: requireEnv('SPECIFICATION_ENDPOINT', 'path the register and heartbeat messages carry, e.g. /api/v1/specification'),
+    instanceId: requireEnv('SERVICE_INSTANCE_ID', 'id of THIS running copy, one value per process'),
+    heartbeatInterval: requirePositiveIntegerEnv('BIZ_HEARTBEAT_INTERVAL_MS', 'milliseconds between heartbeats'),
+    discoveryTimeoutMs: requirePositiveIntegerEnv('REGISTRY_DISCOVERY_TIMEOUT_MS', 'deadline in ms of one getService() read'),
+    redis
   });
 
-  // Initialize connection
   await client.init();
 
-  // Register ourselves with the registry. The full spec (endpoints +
-  // operations) is published as part of the register message — see
-  // api/docs/biz/30-operations/registration-wire.md §2.
-  await client.register({
-    endpoints: [{ path: '/hello', method: 'GET' }],
+  // register() resolves with the registry's verdict (registration-wire.md §2.4, §8).
+  const verdict = await client.register({
+    endpoints: [],
     operations: {
       'say-hello': {
         description: 'Say hello',
-        endpoint: '/hello',
-        method: 'GET',
+        handler: 'handlers/hello#sayHello',
+        bundle_scope: 'platform',
         mutates: false,
         resource_type: null,
         minRole: 'VIEWER',
-        input: {},
-        output: {}
+        input: { type: 'object' },
+        output: { type: 'object' }
       }
     },
-    metadata: {},
+    metadata: { version: client.version, description: 'Event consumer example' },
     health: '/health'
   });
+  if (verdict.success !== true) {
+    throw new Error(`[conn-orch-registry][example] Registration refused - ${verdict.errorCode}: ${verdict.message}`);
+  }
 
-  // Start heartbeat
   client.startHeartbeat({
     maxFailures: 5,
     onFatal: (err) => {
       console.error(err.message);
-      process.exit(1);
+      process.exit(1); // the restart policy boots it again and it re-registers
     }
   });
 
-  // OPT-IN: Subscribe to registry changes
+  // OPT-IN: subscribe to registry changes.
   console.log('Subscribing to registry changes...');
   await client.subscribeToChanges();
 
-  // Listen for events
   client.on('serviceUpdated', ({ service, fingerprint, version }) => {
     console.log(`Service updated: ${service} v${version} (${fingerprint})`);
   });
@@ -88,14 +92,22 @@ async function main() {
     console.log(`Received snapshot with ${count} services`);
   });
 
-  // Graceful shutdown
+  client.on('error', (err) => {
+    console.error('[RegistryClient Error]', err);
+  });
+
   process.on('SIGINT', async () => {
     console.log('\nShutting down...');
+    // deregister() stops the heartbeat first; the registry deletes only the
+    // registration whose instance_id matches this copy.
+    await client.deregister();
     await client.close();
     await redis.quit();
     process.exit(0);
   });
 }
 
-// Run example
-main().catch(console.error);
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/conn-orch-registry",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "license": "MIT",
   "description": "conn-orch-registry provides the core communication mechanism for microservices in this environment. It enables them to interact with a services_registry to receive and fulfill tasks by submitting heartbeats or their API descriptions.",
   "keywords": [
@@ -38,15 +38,15 @@
     "access": "public"
   },
   "dependencies": {
-    "@onlineapps/logger-contract": "2.0.0",
-    "@onlineapps/mq-client-core": "5.0.0",
+    "@onlineapps/logger-contract": "2.1.0",
+    "@onlineapps/mq-client-core": "6.0.0",
     "uuid": "^9.0.1"
   },
   "devDependencies": {
     "amqplib": "0.10.9",
-    "ioredis": "^5.8.0",
     "jest": "^29.6.1",
-    "jsdoc-to-markdown": "^8.0.0"
+    "jsdoc-to-markdown": "^8.0.0",
+    "redis": "4.7.1"
   },
   "engines": {
     "node": ">=24.0.0 <25"

package/src/registryClient.js

@@ -35,6 +35,20 @@ const { queueConfig } = require('@onlineapps/mq-client-core');
 const DEFAULTS = require('./defaults');
 const { assertLogger } = require('@onlineapps/logger-contract');
 
+/**
+ * The two ways a discovery read can fail that say nothing about the answer — the
+ * projection did not answer in time, or the client already knows Redis is gone. Both
+ * are typed HERE, where the failure is known, as `TRANSIENT` (d.1093; the pattern
+ * mq-client-core uses since d.683: a bare error from the transport is typed by the
+ * site that receives it, `src/utils/publishErrors.js` `TransientPublishError`). The
+ * L1 classifier reads `type` and never learns what Redis is; cookbook-router carries
+ * `type` from `cause` onto `SERVICE_DISCOVERY_FAILED`.
+ */
+const DISCOVERY_FAILURE_CODES = Object.freeze({
+  timeout: 'REGISTRY_DISCOVERY_TIMEOUT',
+  unavailable: 'REGISTRY_DISCOVERY_UNAVAILABLE'
+});
+
 /**
  * Keys `register()` REFUSES, with the reason the caller needs to act on
  * (d.562, extended by d.592).
@@ -114,12 +128,19 @@ class ServiceRegistryClient extends EventEmitter {
    * @param {number} opts.heartbeatInterval - Milliseconds between heartbeats. REQUIRED: the
    *   cadence has ONE owner and it is not a library default (owner confirmation
    *   docs/governance/confirmations/biz-health-freshness.md 001 point 3); ServiceWrapper
-   *   passes `wrapper.registry.heartbeatInterval`, itself fed from BIZ_HEARTBEAT_INTERVAL_MS.
+   *   reads it from the environment key BIZ_HEARTBEAT_INTERVAL_MS and passes it here. The
+   *   config key `wrapper.registry.heartbeatInterval` is retired and the wrapper refuses it.
    * @param {string} [opts.apiQueue='api_services_queuer'] - Queue name for heartbeat and API traffic
    * @param {string} [opts.registryQueue='registry.register'] - Queue name for registry messages
    * @param {Object} [opts.validationProof=null] - Validation proof object {hash, data} (injected from outside)
    * @param {number} [opts.registrationTimeoutMs] - How long register() waits for the registry response
    *   before rejecting. Default comes from ./defaults.js (30000 ms); never read from the environment here.
+   * @param {number} opts.discoveryTimeoutMs - How long ONE discovery read (`getService()`)
+   *   may wait for the registry projection before it is refused as `TRANSIENT`. REQUIRED,
+   *   no module default: the value belongs to the platform (ServiceWrapper reads it from
+   *   the platform env) and bounds how long a workflow step can hang on a Redis that is
+   *   down or half-open (d.1090, d.1093). Enforced as a race beside the command, never as
+   *   node-redis' `AbortSignal` (see `getService()` for why).
    * @param {Object} opts.logger - Logger with info/warn/error/debug. Required and validated here:
    *   registration, heartbeat and revalidation events are what this client exists to report, and
    *   until 2026-09-05 they went to stdout through bare printing while this parameter was accepted
@@ -127,7 +148,7 @@ class ServiceRegistryClient extends EventEmitter {
    *   docs/governance/confirmations/connector-logger-contract.md 001 + 002.
    */
   constructor({ amqpUrl, serviceName, version, specificationEndpoint,
-                heartbeatInterval, instanceId, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
+                heartbeatInterval, discoveryTimeoutMs, instanceId, apiQueue = 'api_services_queuer', registryQueue = 'registry.register',
                 redis = null, storageConfig = {}, validationProof = null, logger,
                 registryKeyPrefix = DEFAULTS.registryKeyPrefix,
                 registrationTimeoutMs = DEFAULTS.registrationTimeoutMs }) {
@@ -194,7 +215,8 @@ class ServiceRegistryClient extends EventEmitter {
         `[RegistryClient] ${serviceName}: Missing constructor option - heartbeatInterval is required. `
         + 'Expected: the cadence its one owner decided (docs/governance/confirmations/biz-health-freshness.md 001 '
         + 'point 3), passed as a positive number of milliseconds. '
-        + 'Fix: pass wrapper.registry.heartbeatInterval (ServiceWrapper reads it from BIZ_HEARTBEAT_INTERVAL_MS).'
+        + 'Fix: pass heartbeatInterval; ServiceWrapper reads it from env BIZ_HEARTBEAT_INTERVAL_MS '
+        + '(the config key wrapper.registry.heartbeatInterval is retired and refused).'
       );
     }
     if (typeof heartbeatInterval !== 'number' || !Number.isFinite(heartbeatInterval) || heartbeatInterval <= 0) {
@@ -203,8 +225,23 @@ class ServiceRegistryClient extends EventEmitter {
         + `got ${JSON.stringify(heartbeatInterval)}. Fix: pass the cadence as a number; a string is not parsed here.`
       );
     }
+    if (discoveryTimeoutMs === undefined) {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Missing constructor option - discoveryTimeoutMs is required. `
+        + 'Expected: how long (ms) one discovery read of the registry projection may wait before it is '
+        + 'refused as TRANSIENT, as a positive number. '
+        + 'Fix: pass discoveryTimeoutMs; ServiceWrapper reads it from the platform env (shared.env).'
+      );
+    }
+    if (typeof discoveryTimeoutMs !== 'number' || !Number.isFinite(discoveryTimeoutMs) || discoveryTimeoutMs <= 0) {
+      throw new Error(
+        `[RegistryClient] ${serviceName}: Invalid discoveryTimeoutMs - expected a positive number of milliseconds, `
+        + `got ${JSON.stringify(discoveryTimeoutMs)}. Fix: pass the deadline as a number; a string is not parsed here.`
+      );
+    }
     this.specificationEndpoint = specificationEndpoint;
     this.heartbeatInterval = heartbeatInterval;
+    this.discoveryTimeoutMs = discoveryTimeoutMs;
     this.apiQueue = apiQueue;
     this.registryQueue = registryQueue;
     this.queueManager = new QueueManager(amqpUrl, serviceName, this.logger);
@@ -816,10 +853,18 @@ class ServiceRegistryClient extends EventEmitter {
    * where it published it, and that the heartbeat timer is stopped. A publish that
    * fails REJECTS; reaching the return means the broker took the message.
    *
+   * The heartbeat loop stops FIRST, before anything is published. A heartbeat is
+   * the claim "this copy is alive"; a caller that deregisters has decided it is
+   * leaving, and that decision does not wait for the broker. Until d.1083 the loop
+   * stopped only after a successful publish, so a rejected deregistration left it
+   * beating for a service on its way out.
+   *
    * @returns {Promise<{requestId: string, serviceName: string, version: string,
    *   publishedTo: string, heartbeatStopped: boolean, publishedAt: string}>}
    */
   async deregister() {
+    this.stopHeartbeat();
+
     const msg = {
       id: uuidv4(),
       type: 'deregister',
@@ -846,9 +891,6 @@ class ServiceRegistryClient extends EventEmitter {
 
     this.emit('deregisterSent', msg);
 
-    // Stop heartbeat if running
-    this.stopHeartbeat();
-
     return {
       requestId: msg.id,
       serviceName: this.serviceName,
@@ -907,9 +949,10 @@ class ServiceRegistryClient extends EventEmitter {
    *
    * A heartbeat loop with no budget is worse than none: the beats stop reaching
    * the registry, the loop logs and reschedules forever, and the service keeps
-   * running while every consumer of `registry:services` reads it as stale. Until
-   * 2026-09-15 that budget lived in `@onlineapps/service-wrapper`, in a second
-   * loop around `sendHeartbeat()` — two loops for one cadence
+   * running while every consumer of `registry:services` reads it as stale. The
+   * budget lives here and nowhere else: `@onlineapps/service-wrapper` arms this
+   * loop and runs none of its own (service-wrapper d.1076, its CHANGELOG) — two
+   * loops for one cadence would be two rails for one concern
    * (`.claude/rules/change-discipline.md` § One rail per concern).
    *
    * The cadence is NOT an argument here. It has one owner and it is the
@@ -1126,7 +1169,38 @@ class ServiceRegistryClient extends EventEmitter {
     }
 
     const key = `${this.registryKeyPrefix}services`;
-    const raw = await this.redis.hGet(key, serviceName);
+    // THE DEADLINE IS A RACE, NOT AN AbortSignal (d.1093). Without a deadline `hGet`
+    // never settles while Redis is down or half-open (d.1088, d.1090). node-redis 4.7.1
+    // does offer `commandOptions({ signal })`, but aborting a command the server has
+    // already received removes its queue node a second time (the abort listener stays
+    // attached after the command is sent), the queue length goes negative, and the next
+    // `flushAll` — a socket error with `disableOfflineQueue`, or `disconnect()` — throws
+    // `TypeError: Cannot read properties of undefined (reading 'reject')`; from the socket
+    // error handler that is an uncaught exception that ends the process (measured d.1093,
+    // fake RESP server). The race leaves the command in the queue: a late reply is still
+    // matched to it, and its late settlement is caught below, never unhandled.
+    const lookup = this.redis.hGet(key, serviceName);
+    let timer;
+    let timedOut = false;
+    const deadline = new Promise((resolve) => {
+      timer = setTimeout(() => { timedOut = true; resolve(); }, this.discoveryTimeoutMs);
+    });
+    let raw;
+    try {
+      raw = await Promise.race([lookup, deadline]);
+    } catch (err) {
+      throw this._typeDiscoveryFailure(err, { key, serviceName });
+    } finally {
+      clearTimeout(timer);
+    }
+    if (timedOut) {
+      lookup.then(() => {}, (late) => {
+        this.logger.debug(
+          `[RegistryClient] getService - abandoned lookup of "${serviceName}" settled after the deadline: ${late.message}`
+        );
+      });
+      throw this._discoveryTimeout({ key, serviceName });
+    }
     if (!raw) {
       return null;
     }
@@ -1150,6 +1224,49 @@ class ServiceRegistryClient extends EventEmitter {
     };
   }
 
+  /**
+   * The lookup did not end within `discoveryTimeoutMs`. Nothing failed underneath, so
+   * the error carries no `cause`.
+   * @private
+   * @returns {Error}
+   */
+  _discoveryTimeout({ key, serviceName }) {
+    const failure = new Error(
+      `[RegistryClient] getService - Registry projection did not answer the lookup of "${serviceName}" `
+      + `within ${this.discoveryTimeoutMs} ms (key ${key}). Expected: a reply from the Redis the registry projects into. `
+      + 'Fix: make that Redis reachable to this service; the step is retried as TRANSIENT.'
+    );
+    failure.code = DISCOVERY_FAILURE_CODES.timeout;
+    failure.type = 'TRANSIENT';
+    failure.serviceName = serviceName;
+    return failure;
+  }
+
+  /**
+   * Types a rejected discovery read by what THIS client knows, never by the text of the
+   * rejection (node-redis errors carry no `code` and no `name`, measured d.1090): a client
+   * that reports it is not ready means Redis is gone (offline with `disableOfflineQueue`,
+   * socket closed under the command). Anything else — a reply error from a connected
+   * Redis — is not a transport verdict and passes unchanged.
+   * @private
+   * @returns {Error}
+   */
+  _typeDiscoveryFailure(err, { key, serviceName }) {
+    if (this.redis.isReady !== false) {
+      return err;
+    }
+    const failure = new Error(
+      `[RegistryClient] getService - Registry projection is unreachable for the lookup of "${serviceName}" `
+      + `(key ${key}) - ${err.message}. Expected: a connected client of the Redis the registry projects into. `
+      + 'Fix: make that Redis reachable to this service; the step is retried as TRANSIENT.',
+      { cause: err }
+    );
+    failure.code = DISCOVERY_FAILURE_CODES.unavailable;
+    failure.type = 'TRANSIENT';
+    failure.serviceName = serviceName;
+    return failure;
+  }
+
   /**
    * Releases resources: stops heartbeat and closes connection.
    * @returns {Promise<void>}