@onlineapps/mq-client-core 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -4,6 +4,149 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [4.2.0] — 2026-09-25
+
+### Added — služba deklaruje své rekurence a mluví s plánovačem jednou kolejí (d.833, d.840)
+
+`docs/architecture/scheduler.md` §7 dává klientské knihovně tvar jedné rekurence
+a wrapperu úkol při každém bootu ten stav znovu ohlásit. Odkud služba rekurence bere,
+je její věc — odpovídá jedním hookem (`scheduler: { recurrences: async () => [...] }`),
+platformní konstantním seznamem, tenantové odvozené z vlastních dat (conf `scheduler` 011).
+Knihovna nese tvar a cestu ke zprávě:
+`scheduler.validateRecurrences(document, source)`,
+`scheduler.buildRecurringRequest({ declaration, tenantId, workspaceId, requestedBy })`,
+`scheduler.publishSchedulerRequest(mqClient, request)` a jméno fronty
+`scheduler.requestQueue` (složené z deklarace v `queueConfig`, ne opsané).
+
+Záznam rekurence má u knihovny dvě podoby, obě jsou jejím vstupem:
+
+- **záznam deklarace** pro `validateRecurrences()` a `buildRecurringRequest({ declaration, … })`
+  ve snake_case, jak ho drží schéma `src/config/recurrencesSchema.js`:
+  `{ id, cookbook_ref, cron, timezone, input?, catch_up? }` (první čtyři povinné,
+  `additionalProperties: false`); tenancy v něm není — stavitel ji bere zvlášť jako
+  `tenantId` a `workspaceId`;
+- **záznam portu** `createSchedulerPublisher({ mqClient, requestedBy }).registerRecurring(…)`
+  v camelCase: `{ id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }`.
+  Port ho převede na záznam deklarace a tenancy předá staviteli.
+
+`id` cestuje jako `idempotency_key`, takže re-registrace je upsert a každý boot smí
+deklarovaný stav zopakovat. Dvě stejná `id` v jedné odpovědi jsou odmítnuta — tiše by se
+přepisovala. `source` u `validateRecurrences` je povinný: každá hláška ho cituje, takže
+výchozí hodnota by psala jméno jednoho volajícího k chybě druhého.
+
+**Tenant a workspace dodává VOLAJÍCÍ u každé rekurence — nikdy prostředí, nikdy výchozí
+hodnota.** Obojí je povinné a ≥ 1 (vlastník zamítl `0/0` jako platformní scope —
+konfirmace `scheduler` 002); chybí-li, stavitel hází jménem klíče. Rekurence služba odvozuje
+ze svých dat (conf `scheduler` 010) a hlásí je jedinou kolejí (011), takže tenancy nese
+každý záznam: boot hook wrapperu (FÁZE 0.7b) ji u každého vráceného záznamu VYŽADUJE, protože
+při bootu žádná obálka invokace není; port `ctx.scheduler` v handleru ji naopak doplní
+z obálky invokace a od volajícího ji odmítne. `catch_up` je klíč záznamu portu a požadavku,
+ne deklarace, kterou si služba drží ve svých datech (conf `scheduler` 012 a 018).
+
+**Fixed — hlášky o chybějící tenancy posílaly čtenáře na špatné místo (d.864).** Stavitel
+rekurence i události odmítal chybějící `tenantId` s Fix „pass the tenant the environment
+declares for this service" a chybějící `workspaceId` s Fix „pass the workspace the cookbook
+declares (defaults.workspace_id)". Ani jedno není zdroj, ze kterého hodnota na téhle cestě
+jde: Fix teď říká, že se obě hodnoty podávají s každým požadavkem — rekurence je nese
+v záznamu, který služba vrací ze svých dat, a `ctx.scheduler` je doplní z obálky invokace;
+odjinud se nečtou. Chování se nemění, mění se jen to, kam hláška posílá. Totéž u odmítnutí
+záznamu v `validateRecurrences()`: poznámka „tenant a workspace sem nepatří" citovala conf
+`tier1-runner-workspace` 001, která mluví o jiném běhu; teď cituje conf `scheduler` 010 a 011
+(d.864b).
+
+**Prázdná odpověď je odpověď**, ne chyba: služba bez rozvrhů hook nemá, nebo vrátí prázdný
+seznam, a wrapper svůj krok přeskočí. Odpověď, která NEOBSTOJÍ, hází — nezaregistrovaný
+rozvrh je práce, která se nikdy nestane, a nic jiného na to neupozorní. Ze stejného důvodu
+je odeslání **fail-fast**, na rozdíl od sousedních pomocníků monitoringu.
+
+Zpráva se staví přesně podle kontraktu plánovače
+(`api/infra/api_scheduler/contracts/scheduler.request.schema.json`, `additionalProperties:
+false`) a sada to proti TOMU kontraktu ověřuje Ajvem, ne proti kopii schématu.
+
+**d.840 — zbylé dva druhy a jedno odeslání.** Vedle `buildRecurringRequest()` přibyly
+`scheduler.buildEventRequest({ event: { service, name }, idempotencyKey, tenantId,
+workspaceId, requestedBy, input? })` a `scheduler.buildCancelRequest({ idempotencyKey,
+requestedBy })`, a všechny tři druhy odesílá JEDNA funkce
+`scheduler.publishSchedulerRequest(mqClient, request)` — druh je pole zprávy, ne druhá
+funkce. (Nevydané `publishRecurringRequest` tím zaniká; čtenáře mimo balíček nemělo,
+takže přechodový alias nevzniká — pravidlo 11.)
+
+Událost NEJMENUJE recept: plánovač spustí každý recept, jehož `triggers` tu událost
+deklarují (conf `scheduler` 004), takže producent, který by recept jmenoval, by mapoval
+práci na něco, co nemusí vlastnit (conf `ingest-poll-trigger-rail` 001). `cancel` nenese
+tenanta ani workspace — klíč jmenuje položku, která si kontext nese od registrace, a
+zrušení neexistujícího klíče je výsledek (`cancel-nothing`), ne chyba.
+
+**Klíč je vždy volajícího.** `idempotency_key` vyžaduje kořen kontraktu u všech druhů a
+plánovač podle něj jednorázovou položku rozhodne JEDNOU (druhá událost s týmž klíčem =
+`duplicate`), takže klíč vyrobený knihovnou by z každého opakování jednoho faktu udělal
+druhý běh. Žádný stavitel ho proto nevymýšlí.
+
+**Port `scheduler.createSchedulerPublisher({ mqClient, requestedBy })`** vrací tři slovesa
+(`registerRecurring`, `publishEvent`, `cancel`) se jménem služby už rozhodnutým. Klient
+i jméno fronty se ověřují PŘI KONSTRUKCI — služba, která ohlašuje fakty, má spadnout při
+bootu, ne u prvního dokladu — a každé odmítnutí jmenuje slot a Fix, aby vada wiringu
+neodpověděla místo operace. Tenancy zůstává na každém volání výslovná, protože port drží
+dva různí volající: služba pod wrapperem (doplní ji z obálky běhu) a operátorský skript,
+který wrapper vůbec nebootuje a pracuje řádek po řádku (měření BIZ-ingest 23. 9.).
+
+Při té příležitosti se rozšířil tvar `id` v záznamu rekurence: schéma ho dosud omezovalo
+na malá písmena a pomlčky, což je přísnější než konzument (jakýkoli řetězec 1–255 znaků) a
+odmítalo by to konvenci prvního volajícího `<source_uuid>:<cookbook_ref>`. Nově se odmítá
+jen bílé místo, které by z klíče udělalo větu.
+### Changed — port `registerRecurring()` klíč, který požadavek nedeklaruje, odmítne (d.864b)
+
+`createSchedulerPublisher(…).registerRecurring()` bral jen pojmenované klíče a cokoli
+navíc tiše zahodil — takže překlep (`catch_up` místo `catchUp`) prošel a rozvrh se
+zaregistroval bez toho, co volající chtěl. Port je teď stejně přísný jako záznam
+deklarace, na který se převádí (`additionalProperties: false`): klíč mimo
+`{ id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }` je odmítnutí,
+které ho jmenuje. Port je ve vydání nový, takže to žádného volajícího vydané verze nerozbije;
+změřeno, že dnešní volající (boot hook a `ctx.scheduler` wrapperu, `declaredRecurrences`
+ingestu) klíč navíc neposílají.
+
+### Added — výměna `dlx` je v `queueConfig` deklarovaná i s typem a trvanlivostí (d.902)
+
+`deadLetterExchange()` vracel jen jméno `dlx`; typ `direct` a `durable: true` žily jen
+u zakladatele (`@onlineapps/conn-infra-mq` `QueueManager.setupServiceQueues()`), takže
+CI nástroj INFRA `scripts/ci/declare-broker-exchanges.mjs` je nesl jako opsanou druhou
+kopii (TODO INFRA 349). Nová sekce `deadLetter` deklaruje `dlx` stejným tvarem jako každá
+jiná výměna (`type: 'exchange'`, `exchangeType: 'direct'`, `durable: true`), a protože
+jméno na drátě prefix nemá, `SECTION_PREFIXES.deadLetter` je `''` — deklarovaný případ,
+který `queueName()` čte výslovně (`queueName('deadLetter', 'dlx') === 'dlx'`); sekce bez
+deklarovaného prefixu je dál odmítnuta toutéž hláškou. `deadLetterExchange()` jméno skládá
+z téže položky. Seznam front (`infrastructurePrefixes()`, vstupy `initInfrastructureQueues`)
+se nemění — změřeno před/po; počet deklarovaných položek 36 → 37, výměn 6 → 7, front 30.
+
+### Fixed — handshake, který doběhne po `connectTimeout`, se zavře; nezůstane spojení bez vlastníka (INFRA 359, d.917)
+
+`connect()` i `_reconnectWithBackoff()` (`src/transports/rabbitmqClient.js`) závodily
+`amqp.connect()` s časovačem `connectTimeout`. Když vyhrál časovač, volající dostal chybu
+timeoutu, ale handshake běžel dál a mohl doběhnout do úplného AMQP spojení, na které
+žádné pole klienta neukazovalo — `disconnect()` ho tedy nezavřel, spojení viselo na
+brokeru a proces neskončil (INFRA 359, změřeno mimo jest: mlčící TCP server a proxy
+zdržující handshake o 11 s proti `connectTimeout` 10 000 ms). Obě místa teď závodí
+jedním pomocníkem `_raceHandshake()`: opuštěný handshake se po doběhnutí zavře (varování
+v logu), handshake, který po timeoutu selže, nic neotevřel. Kontrakt se nemění —
+`connect()` odmítne timeoutem stejnou chybou jako dřív a včas doběhlé spojení zůstává
+spojením klienta.
+
+### Changed — TTL telemetrie 60 s → 300 s (conf telemetry-queue-ttl 001, INFRA 356)
+
+`x-message-ttl` tří front `telemetry.logs.queue`, `telemetry.metrics.queue` a
+`telemetry.traces.queue` (`src/config/queueConfig.js`, sekce `telemetry`) je 300000 místo
+60000 — rozhodnutí vlastníka, varianta B (conf `telemetry-queue-ttl` 001). Proč: konzument
+telemetrie stojí v okně deploye (stop před migracemi, `up -d` až po nich); při prvním
+produkčním deployi `f03fad7c` bez něj byl 159 s a každá zpráva starší než 60 s expirovala
+do `telemetry.dlq` (1414, všechny `x-death.reason = expired`), takže brána 9b dala NO-GO na
+`dlqMaxMessages` 100 za ztrátu, kterou způsobil sám deploy. 300 s pokryje okno deploye.
+Nemění se: `x-max-length` 100000 (paměťový strop), `telemetry.dlq` (`x-max-length` 50000,
+bez TTL), dead-letter cesta ani práh brány 9b; fronty `delivery.*` a další s TTL 60 s
+zůstávají. Provozní důsledek: fronta existující na brokeru s `x-message-ttl` 60000 dá při
+bootu konzumenta na 4.2.0 406 `PRECONDITION_FAILED` (`initInfrastructureQueues` hází,
+nikdy nemaže) — smazání a znovuvytvoření tří front v okně deploye je krok deploye INFRA
+(conf `mq-consumer-contract` bod 4 a conf `telemetry-queue-ttl` 001 Conditions/limits).
+
 ## [4.1.0] — 2026-09-23
 
 ### Added — plánovač se dozví KONEC běhu z vlastní fronty (d.818)

package/README.md

@@ -619,8 +619,16 @@ 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
+queueConfig.deadLetterExchange();                   // 'dlx' — composed from queueConfig.deadLetter
 ```
 
+- The platform's dead-letter exchange is declared like every other exchange here —
+  `queueConfig.deadLetter.dlx` is `{ type: 'exchange', exchangeType: 'direct', durable: true }`,
+  the shape its founder (`@onlineapps/conn-infra-mq` `setupServiceQueues()`) asserts. Its wire
+  name carries no prefix: the `deadLetter` section declares an empty one, so
+  `queueName('deadLetter', 'dlx')` is `'dlx'`, and a reader walking the `type: 'exchange'`
+  entries finds it with the rest.
+
 - `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
@@ -720,6 +728,125 @@ trade a real effect for a record of it — a lost copy is reported through the l
 answers `false`. The one exception is a missing logger, which is the transport half's rule:
 without it the promise "every failure is reported" cannot hold.
 
+**The two builders of this package fail differently, on purpose.** This one answers `false` and
+reports; `scheduler.publishSchedulerRequest()` below throws. A lost monitoring copy is a missing
+record of work that happened; a lost registration is work that will never happen, and nothing
+rings for it.
+
+### scheduler — what a service says to the platform's owner of time
+
+A service that runs work on a schedule ANSWERS with the recurrences it owns, through one hook
+the wrapper asks at boot, and the wrapper re-asserts each of them as a `scheduler.request` of
+kind `recurring` ([scheduler.md §7](/docs/architecture/scheduler.md)). Re-registration is an
+upsert — a recurring request's `idempotency_key` IS the schedule id — so a boot that re-asserts
+the declared state costs nothing and drifts nowhere.
+
+ONE RAIL FOR BOTH KINDS (confirmation `scheduler` 011): the hook answers a constant list for
+platform recurrences and a list derived from the service's own data for tenant ones. This
+package owns the SHAPE of a record and the message built from it — never where the record comes
+from, which is the service's business.
+
+```javascript
+// In the service, the hook the wrapper asks at boot (FÁZE 0.7b). Every record carries its own
+// tenancy, derived from the service's data — at boot there is no invocation envelope to take
+// it from (confirmations `scheduler` 002, 010):
+new ServiceWrapper({
+  scheduler: {
+    recurrences: async () => ([
+      { id: '31bf8bac:servant-poll', cookbookRef: 'servant-poll', cron: '0 * * * *',
+        timezone: 'Europe/Prague', tenantId: 101, workspaceId: 1, input: { source_uuid: '31bf8bac' } }
+    ])
+  }
+});
+
+// What the wrapper does with the answer — the port this package builds:
+const { scheduler } = require('@onlineapps/mq-client-core');
+const port = scheduler.createSchedulerPublisher({ mqClient, requestedBy: serviceName });
+for (const record of answered) await port.registerRecurring(record);
+```
+
+The port record is camelCase — `{ id, cookbookRef, cron, timezone, tenantId, workspaceId,
+input?, catchUp? }` — and the port turns it into the declaration record below, which is what
+`validateRecurrences()` and `buildRecurringRequest({ declaration, tenantId, workspaceId,
+requestedBy })` take. One declaration record, and nothing else:
+
+| Key | Required | Meaning |
+|---|---|---|
+| `id` | ✅ | The schedule's stable id; it travels as `idempotency_key`, so two records of one id are refused |
+| `cookbook_ref` | ✅ | The cookbook to run. Its `triggers` must name this service and the kind `recurring`, or the scheduler refuses the request |
+| `cron` | ✅ | Five fields, the same expression the scheduler's contract takes |
+| `timezone` | ✅ | An explicit IANA zone; there is no implicit one |
+| `input` | – | Handed to the cookbook unchanged — a scheduled run that writes says so in the record, while the same cookbook run by hand can be given a different input |
+| `catch_up` | – | Absent means false, and the scheduler materialises that default |
+
+- **Tenancy is the caller's, on every recurrence — never the environment, never a default.**
+  Both ids are mandatory and ≥ 1 (the owner rejected `0/0` as a platform scope, confirmation
+  `scheduler` 002), and a missing one is refused by name. The declaration record above does not
+  carry them; the builder takes them beside it, and the port record carries them per entry.
+  Who fills them depends on where the call comes from: the boot hook's records must carry
+  them (no envelope exists at boot), while `ctx.scheduler` inside a handler fills them from the
+  invocation envelope and refuses them from the caller.
+- **An empty answer is an answer.** A service with no recurrences has no hook, or answers an
+  empty list, and the wrapper skips its step. An answer that does NOT hold throws — a
+  recurrence nobody registered is work that never happens, and nothing else rings for it.
+- **`validateRecurrences(document, source)` names its source**, and the name is required: every
+  refusal quotes it, so a default here would put one caller's name on another caller's mistake.
+- **Sending is fail-fast**, unlike the monitoring helpers beside it. A lost monitoring copy
+  is a missing record of work that happened; a lost registration is work that will not happen.
+- `scheduler.requestQueue` is the queue name, composed from the declaration in `queueConfig`
+  — a caller never types `scheduler.request`.
+
+Two more things a service says on that queue, and one send for all of them:
+
+```javascript
+// THAT something happened. It names no cookbook: the scheduler starts every recipe whose
+// `triggers` declare this event, so a producer naming a recipe would map work to something it
+// may not own.
+await scheduler.publishSchedulerRequest(mqClient, scheduler.buildEventRequest({
+  event: { service: 'biz-ingest', name: 'job-persisted' },
+  idempotencyKey: `biz-ingest:job-persisted:${jobId}`,   // the identity of the fact
+  tenantId, workspaceId, requestedBy: serviceName,
+  input: { source_uuid }                                  // optional, handed to every cookbook it starts
+}));
+
+// An item back, by the key it was registered with.
+await scheduler.publishSchedulerRequest(mqClient, scheduler.buildCancelRequest({
+  idempotencyKey: 'servant-poll',
+  requestedBy: serviceName
+}));
+```
+
+- **The key is always the caller's.** `idempotency_key` is required for every kind, and the
+  scheduler decides a one-shot item ONCE by it — a second `event` carrying a known key is
+  answered `duplicate`. A key this package invented per call would turn every retry of one fact
+  into a second run, so no builder makes one up.
+- **`cancel` carries no tenancy**, and needs none: the key names an item that already holds the
+  context it was registered with. Cancelling a key that names nothing is a result rather than an
+  error — the scheduler answers `cancel-nothing` — so the builder judges nothing about it.
+- **One send, `publishSchedulerRequest()`**, for every kind: the kind is a field of the message,
+  never a second function. It is fail-fast like the registration above, and it refuses a message
+  none of these builders produced.
+
+A service that speaks to the scheduler more than once holds a port instead of repeating its own
+name and the queue:
+
+```javascript
+const port = scheduler.createSchedulerPublisher({ mqClient, requestedBy: serviceName });
+
+await port.registerRecurring({ id, cookbookRef, cron, timezone, tenantId, workspaceId, input, catchUp });
+await port.publishEvent({ name: 'job-persisted', idempotencyKey: jobUuid, tenantId, workspaceId, input });
+await port.cancel({ id });
+```
+
+- **The client and the queue are decided at construction**, not at the first call: a service that
+  announces facts has to fall over at boot rather than at its first document. On a pin whose
+  `queueConfig` declares no `scheduler` section this module refuses when it is required, earlier
+  still. Every refusal names the slot it is about and how to fix it, so a defect of the wiring can
+  never be read as the operation's own error.
+- **Tenancy stays explicit on every call**, because two kinds of caller hold this port: a service
+  under the wrapper, which fills it from the envelope of the run, and an operator script that does
+  not boot the wrapper at all and works row by row.
+
 ### redactUrl — a connection URL that is safe to log
 
 `RABBITMQ_URL` carries the broker account, so anything that renders it verbatim

package/package.json

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

package/src/config/queueConfig.js

@@ -61,7 +61,12 @@ const SECTION_PREFIXES = Object.freeze({
   telemetry: 'telemetry',
   alerts: 'alert',
   registry: 'registry',
-  scheduler: 'scheduler'
+  scheduler: 'scheduler',
+  // The one section whose names travel WITHOUT a prefix: `dlx` is the wire name every
+  // business queue dead-letters to (`x-dead-letter-exchange`), and renaming it would
+  // re-declare live topology. The empty prefix is a declared case, read explicitly by
+  // `queueName()`; a section absent from this map is still refused (d.902).
+  deadLetter: ''
 });
 
 /**
@@ -629,10 +634,17 @@ module.exports = {
     /**
      * monitoring.workflow - Unified workflow lifecycle monitoring
      * Bound to monitoring.workflow.fanout exchange (fanout).
-     * Delivery Dispatcher publishes 'completed'/'failed' events after processing workflow.completed/workflow.failed
-     * Business services publish 'progress' events during workflow step processing
-     * Message format includes event_type: 'completed' | 'failed' | 'progress'
-     * Includes full cookbook and context snapshots for trace storage
+     *
+     * WHO publishes onto that fanout: the Delivery Dispatcher after it processes a terminal
+     * workflow message, the in-process orchestrator during a run, and this client's own
+     * dead-letter hook. WHICH event_type each of them sends is not written here - the
+     * vocabulary has one owner and it grows, so a list copied into this comment would be a
+     * hand-written descriptive fact that ages in silence
+     * (`.claude/rules/doc-code-binding.md` §1).
+     *
+     * The message carries the cookbook and the context snapshot the trace store keeps.
+     *
+     * @see api/docs/biz/70-contracts/monitoring-events.md
      */
     'workflow': {
       durable: true,
@@ -646,15 +658,20 @@ module.exports = {
 
     /**
      * monitoring.services - Service lifecycle events monitoring
-     * Registry publishes service lifecycle events (registered, validation.completed, version.changed, status.changed)
-     * InfrastructureHealthTracker publishes service status changes
-     * Message format includes event_type: 'service.registered' | 'service.validation.completed' | 
-     *   'service.version.changed' | 'service.deregistered' | 'service.status.changed'
+     *
+     * WHO publishes here: the Registry, which owns the service lifecycle, and the
+     * InfrastructureHealthTracker with service status changes. WHICH event_type each of them
+     * sends is not written here — that vocabulary has one owner and it grows, and a list
+     * copied into this comment would be a hand-written descriptive fact that ages in silence
+     * (`.claude/rules/doc-code-binding.md` §1).
+     *
      * NOTE: Heartbeats are NOT published here - they are too frequent. The cadence
      *   is not a number this file owns: see the `heartbeatInterval` constructor option
      *   of RegistryClient (@onlineapps/conn-orch-registry), which ServiceWrapper feeds
      *   from BIZ_HEARTBEAT_INTERVAL_MS.
      * NOTE: Healthcheck messages go to infrastructure.health.events exchange
+     *
+     * @see api/docs/biz/70-contracts/monitoring-events.md
      */
     'services': {
       durable: true,
@@ -830,7 +847,7 @@ module.exports = {
     'logs.queue': {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,       // 1 minute TTL for unprocessed messages
+        'x-message-ttl': 300000,      // 5 min — okno deploye bez konzumenta; conf telemetry-queue-ttl 001
         'x-max-length': 100000,       // Max 100k messages in queue
         'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
         'x-dead-letter-routing-key': 'telemetry.dlq'
@@ -841,7 +858,7 @@ module.exports = {
     'metrics.queue': {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,
+        'x-message-ttl': 300000, // 5 min — okno deploye bez konzumenta; conf telemetry-queue-ttl 001
         'x-max-length': 100000,
         'x-dead-letter-exchange': '',
         'x-dead-letter-routing-key': 'telemetry.dlq'
@@ -852,7 +869,7 @@ module.exports = {
     'traces.queue': {
       durable: true,
       arguments: {
-        'x-message-ttl': 60000,
+        'x-message-ttl': 300000, // 5 min — okno deploye bez konzumenta; conf telemetry-queue-ttl 001
         'x-max-length': 100000,
         'x-dead-letter-exchange': '',
         'x-dead-letter-routing-key': 'telemetry.dlq'
@@ -1075,12 +1092,16 @@ module.exports = {
      *
      * The third queue bound to `monitoring.workflow.fanout`, beside `monitoring.workflow`
      * and `delivery.workflow.events`. The owner settled it in
-     * `docs/governance/confirmations/scheduler.md` 007: the terminal event of a run
-     * (`completed` / `failed` / `discarded`) already travels on that exchange, so the
-     * scheduler reads it there rather than asking the observer over HTTP or reading a
-     * database that is not its own. No producer changes; the binding is the scheduler's own
-     * act at boot (the pattern `infra/api_delivery_endpoint/src/index.js:164` already uses),
-     * and this file only DECLARES what that queue is.
+     * `docs/governance/confirmations/scheduler.md` 007: the terminal event of a run already
+     * travels on that exchange, so the scheduler reads it there rather than asking the
+     * observer over HTTP or reading a database that is not its own. No producer changes; the
+     * binding is the scheduler's own act at boot (the pattern
+     * `infra/api_delivery_endpoint/src/index.js:164` already uses), and this file only
+     * DECLARES what that queue is.
+     *
+     * WHICH event_type values those are is NOT written here: the vocabulary has one owner and
+     * it grows. A list copied into this comment would be a hand-written descriptive fact that
+     * ages in silence (`.claude/rules/doc-code-binding.md` §1).
      *
      * THE TTL IS STATED, NOT INHERITED, and it is a property of that decision rather than a
      * default: a fanout cannot filter, so this queue receives EVERY workflow event of the
@@ -1096,6 +1117,7 @@ module.exports = {
      * `CONSUMER_DEAD_LETTER_ROUTE_MISSING`; `mq-consumer-contract` 002).
      *
      * @see api/docs/governance/confirmations/scheduler.md 007
+     * @see api/docs/biz/70-contracts/monitoring-events.md
      */
     'workflow.events': {
       durable: true,
@@ -1123,6 +1145,31 @@ module.exports = {
     }
   },
 
+  /**
+   * The platform's dead-letter exchange, DECLARED — name, type and durability.
+   *
+   * Every business template dead-letters here (`x-dead-letter-exchange`), and
+   * `@onlineapps/conn-infra-mq` `QueueManager.setupServiceQueues()` brings it into
+   * being as a durable `direct` exchange before binding `{service}.dlq` to it. The
+   * broker compares type and durability at EVERY `assertExchange`, so they belong to
+   * the declaration, where a second reader — `api/scripts/ci/declare-broker-exchanges.mjs`,
+   * which declares exchanges on a CI broker nobody's services booted against — finds
+   * them through the same loop as every other exchange of this file, instead of keeping
+   * a copy of the founder's line (TODO INFRA 349, d.902).
+   *
+   * Its wire name carries no prefix (`SECTION_PREFIXES.deadLetter` is `''`), and the key
+   * is the one constant at the top of this file, so the name has one spelling.
+   * An exchange holds nothing to dead-letter, so — like every other exchange here — it
+   * carries no route.
+   */
+  deadLetter: {
+    [DEAD_LETTER_EXCHANGE]: {
+      type: 'exchange',
+      exchangeType: 'direct',
+      durable: true
+    }
+  },
+
   /**
    * The full wire name of a declared entry: the section's prefix + the entry's key.
    *
@@ -1132,9 +1179,13 @@ module.exports = {
    * a name this configuration does not declare would be asserted against the broker
    * by whoever imported it, which is how a typo becomes a second queue.
    *
+   * A section whose declared prefix is `''` (`deadLetter`) composes the bare key: its
+   * names travel without a prefix. That is a value of the map, not a default — a
+   * section missing from it is refused below.
+   *
    * @param {string} section - Section holding the entry (e.g. 'deliveryEvents').
    * @param {string} key - The entry's key within that section (e.g. 'health.events').
-   * @returns {string} The full name (e.g. 'delivery.health.events').
+   * @returns {string} The full name (e.g. 'delivery.health.events'; the bare key for 'deadLetter').
    * @throws {ValidationError} If the section composes no wire name, or the entry is undeclared.
    */
   queueName(section, key) {
@@ -1156,7 +1207,7 @@ module.exports = {
       );
     }
 
-    return `${prefix}.${key}`;
+    return prefix === '' ? key : `${prefix}.${key}`;
   },
 
   /**
@@ -1627,11 +1678,12 @@ module.exports = {
    * Every business template routes here (`x-dead-letter-exchange`), and so does
    * `getDeadLetterRoute()` for a business queue. `@onlineapps/conn-infra-mq` binds
    * `<service>.dlq` to it and had to read the name back out of a queue's arguments
-   * for want of an export.
+   * for want of an export. Composed from the `deadLetter` entry, which also declares
+   * the exchange's type and durability — one declaration, not a name beside it.
    *
    * @returns {string}
    */
   deadLetterExchange() {
-    return DEAD_LETTER_EXCHANGE;
+    return this.queueName('deadLetter', DEAD_LETTER_EXCHANGE);
   }
 };

package/src/config/recurrencesSchema.js

@@ -0,0 +1,121 @@
+'use strict';
+
+/**
+ * recurrencesSchema.js
+ *
+ * JSON Schema used by Ajv (in `src/scheduler-request.js`) to validate the recurrences a service
+ * declares about itself.
+ *
+ * WHY THE SHAPE LIVES HERE. `docs/architecture/scheduler.md` §7 has the wrapper register a
+ * service's recurrences at boot — "idempotent, so every boot re-asserts the declared state" —
+ * and the service answers with them through ONE hook, platform ones as a constant list and
+ * tenant ones derived from its own data (confirmation `scheduler` 011). The shape of a record
+ * is the library's; where the record comes from is not. One owner of the shape means every service's file is the
+ * same file, and the wrapper reading it never has to guess.
+ *
+ * WHAT THE FILE DOES NOT CARRY, and why that is a rule rather than an omission:
+ *
+ *   - **`tenant_id` and `workspace_id`.** They travel beside the record, not in it: the
+ *     builder takes them as `tenantId` and `workspaceId`, and the caller supplies them with
+ *     every recurrence — the service knows them from its own data, and nothing reads them from
+ *     the environment or defaults them.
+ *     @see api/docs/governance/confirmations/scheduler.md 002, 010
+ *   - **`requested_by`.** It is the service that declared the record; the caller passes the name
+ *     it already knows, so a record cannot disagree with the service that answered it.
+ *
+ * `additionalProperties: false` at both levels, deliberately: the consumer's own contract
+ * (`api/infra/api_scheduler/contracts/scheduler.request.schema.json`) closes its keys the same
+ * way, so a key accepted here and refused there would turn a boot into a dead-lettered
+ * request nobody reads.
+ *
+ * @see ../scheduler-request.js — the shape check, the builders and the send
+ * @see api/docs/architecture/scheduler.md §4, §7
+ */
+
+/**
+ * Five whitespace-separated fields — the same expression the scheduler's contract takes
+ * (`recurrence.cron`, pattern `^\S+( \S+){4}$`). Whether those fields describe a reachable
+ * instant is the tick engine's answer, not this file's.
+ */
+const CRON_PATTERN = '^\\S+( \\S+){4}$';
+
+/**
+ * The id of one schedule: it becomes `idempotency_key`, so it is a name, not a sentence.
+ *
+ * As WIDE as the consumer's own rule and no wider: the scheduler takes any string of 1–255
+ * characters for that key, so this file refuses only what would make the key a sentence —
+ * whitespace. The narrower spelling this schema first carried (lower-case letters and dashes)
+ * was the library being stricter than the contract for no reason, and it refused the very
+ * convention the first caller uses: `<source_uuid>:<cookbook_ref>` (BIZ-ingest, 2026-09-23).
+ */
+const ID_PATTERN = '^\\S+$';
+
+const recurrencesSchema = {
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  $id: 'https://onlineapps.cz/schemas/mq-client-core/recurrences.v1.schema.json',
+  title: 'Service recurrence declaration',
+  description:
+    'What a service declares about its own recurring runs. The wrapper re-asserts every record '
+    + 'at boot as a `scheduler.request` of kind `recurring`.',
+  type: 'object',
+  additionalProperties: false,
+  required: ['recurrences'],
+  properties: {
+    recurrences: {
+      description:
+        'Every recurrence this service owns. An empty list is a valid declaration of nothing, '
+        + 'and a service with no recurrences may answer one.',
+      type: 'array',
+      items: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['id', 'cookbook_ref', 'cron', 'timezone'],
+        properties: {
+          id: {
+            description:
+              'Stable id of THIS schedule; it travels as `idempotency_key`, so re-registration '
+              + 'upserts instead of creating a second schedule.',
+            type: 'string',
+            minLength: 1,
+            maxLength: 255,
+            pattern: ID_PATTERN
+          },
+          cookbook_ref: {
+            description:
+              'Id of the cookbook to run. Its `triggers` must name this service and the kind '
+              + '`recurring`, or the scheduler refuses the request (confirmation scheduler 004).',
+            type: 'string',
+            minLength: 1,
+            maxLength: 255
+          },
+          cron: {
+            description: 'Cron expression, five fields.',
+            type: 'string',
+            pattern: CRON_PATTERN
+          },
+          timezone: {
+            description: 'IANA zone, explicit. No implicit zone exists (scheduler.md §4).',
+            type: 'string',
+            minLength: 1,
+            maxLength: 64
+          },
+          input: {
+            description:
+              'Input handed to the cookbook unchanged. Present only where the run needs one — '
+              + 'a scheduled import that writes says so here, while the same cookbook run by hand '
+              + 'can be given a different input.',
+            type: 'object'
+          },
+          catch_up: {
+            description:
+              'Whether a missed window runs once when the scheduler comes back. Absent means '
+              + 'false, and the scheduler materialises that default — this file does not.',
+            type: 'boolean'
+          }
+        }
+      }
+    }
+  }
+};
+
+module.exports = { recurrencesSchema, CRON_PATTERN, ID_PATTERN };

package/src/index.js

@@ -40,6 +40,15 @@ const {
   buildWorkflowInitiatedEvent,
   publishWorkflowInitiated,
 } = require('./monitoring-initiated');
+const {
+  schedulerRequestQueue,
+  validateRecurrences,
+  buildRecurringRequest,
+  buildEventRequest,
+  buildCancelRequest,
+  publishSchedulerRequest,
+  createSchedulerPublisher,
+} = require('./scheduler-request');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
 const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
@@ -94,6 +103,23 @@ module.exports.monitoring = {
   buildWorkflowInitiatedEvent,
   publishWorkflowInitiated,
 };
+/**
+ * The recurrences a service declares, and how one of them is registered (d.833).
+ *
+ * `docs/architecture/scheduler.md` §7 gives this library the shape of one declared recurrence
+ * and the wrapper the job of re-asserting what the service answers at every boot (one hook,
+ * confirmation `scheduler` 011). The queue name travels with them, so no caller composes
+ * `scheduler.request` itself.
+ */
+module.exports.scheduler = {
+  requestQueue: schedulerRequestQueue,
+  validateRecurrences,
+  buildRecurringRequest,
+  buildEventRequest,
+  buildCancelRequest,
+  publishSchedulerRequest,
+  createSchedulerPublisher,
+};
 /** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
 module.exports.queueConfig = queueConfig;
 /**

package/src/scheduler-request.js

@@ -0,0 +1,481 @@
+'use strict';
+
+/**
+ * The recurrences a service declares, and the request that registers ONE of them.
+ *
+ * `docs/architecture/scheduler.md` §7: a service declares the recurrences it owns and the
+ * wrapper re-asserts them at every boot as `scheduler.request` messages of kind `recurring`.
+ * The service answers with them through ONE hook (`scheduler: { recurrences: async () => [...] }`,
+ * d.834) - platform ones as a constant list, tenant ones derived from its own data - and this
+ * library fixes the SHAPE of a record (`validateRecurrences()`), never where it comes from
+ * (confirmation `scheduler` 011). The scheduler treats a
+ * repeated registration as an upsert — `idempotency_key` for a recurring request IS the
+ * schedule id — so re-asserting the declared state costs nothing and drifts nowhere
+ * (`api/infra/api_scheduler/src/consumer/decideOnRequest.js`, `contracts/scheduler.request.schema.json`).
+ *
+ * ONE RAIL FOR EVERY THING A SERVICE SAYS TO THE SCHEDULER. The queue takes one message with
+ * four branches, and three of them are a service's to send: `recurring` (a schedule, built from
+ * a record the service declared), `event` (a fact that happened, naming no
+ * cookbook - the scheduler starts every recipe whose `triggers` declare it, confirmation
+ * `scheduler` 004) and `cancel` (an item by its key). Each has a pure builder anybody can ask
+ * without a broker, and ONE `publishSchedulerRequest()` sends them all: the kind is a field of
+ * the message, never a second function - the split `./monitoring-initiated.js` uses for
+ * `workflow_initiated`, with one send instead of three.
+ *
+ * THE KEY IS ALWAYS THE CALLER'S. `idempotency_key` sits in the contract's root `required`, and
+ * the consumer decides a one-shot item ONCE by it (a second `event` of a known key answers
+ * `duplicate`). A key invented here would make every retry of one fact a second run, so no
+ * builder makes one up - it is the identity of the thing, and only the caller knows it.
+ *
+ * WHERE IT DIFFERS FROM THAT SIBLING, and why: sending is **fail-fast**. A lost monitoring
+ * copy is a missing record of work that already happened, so that rail returns `false` and
+ * reports. A lost registration is work that will never happen, and nothing rings when a run
+ * does not start — so every refusal here is thrown and the boot stops on it
+ * (`architecture-principles.md` §4).
+ *
+ * WHAT IT NEVER INVENTS: `tenant_id` and `workspace_id`. Both are mandatory and ≥ 1, and the
+ * caller passes them with every request — nothing here reads them from the environment or
+ * supplies a default. For a recurrence the service knows them from its own data, so the records
+ * its boot hook returns carry them; inside a handler `ctx.scheduler` takes them from the
+ * invocation envelope.
+ *
+ * @see api/docs/governance/confirmations/scheduler.md 002
+ * @see api/docs/governance/confirmations/scheduler.md 010
+ * @see api/docs/governance/confirmations/scheduler.md 011
+ *
+ * @see ./config/recurrencesSchema.js — the shape of one declared recurrence
+ * @see ./monitoring-initiated.js — the same split for `workflow_initiated`
+ * @see api/docs/architecture/scheduler.md §4, §7
+ */
+
+const Ajv = require('ajv');
+
+const queueConfig = require('./config/queueConfig');
+const { recurrencesSchema } = require('./config/recurrencesSchema');
+
+/** The queue the scheduler consumes, composed from the declaration rather than typed. */
+const schedulerRequestQueue = queueConfig.queueName('scheduler', 'request');
+
+const ajv = new Ajv({ allErrors: true });
+const validateDeclaration = ajv.compile(recurrencesSchema);
+
+/** Ajv's findings as one sentence a human can act on. */
+const describeErrors = (errors) => (errors || [])
+  .map((error) => {
+    const where = error.instancePath === '' ? 'the document' : error.instancePath;
+    const what = error.params && error.params.additionalProperty
+      ? `${error.message} ("${error.params.additionalProperty}")`
+      : error.message;
+    return `${where} ${what}`;
+  })
+  .join('; ');
+
+/**
+ * Check a parsed declaration document and hand back its records.
+ *
+ * @param {Object} document - `{ recurrences: [...] }`, as the service declared it.
+ * @param {string} source - Where it came from, named in every sentence this function throws.
+ *   Required: a default here would put one caller's name on another caller's mistake.
+ * @returns {Array<Object>} The declared recurrences, in the order they were given.
+ * @throws {Error} When the document does not hold, naming every rule it broke.
+ */
+function validateRecurrences(document, source) {
+  if (typeof source !== 'string' || source.trim() === '') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Missing source - Expected: a name for what is being '
+        + 'checked, because every refusal below quotes it and a wrong name sends the reader to the '
+        + 'wrong place. Fix: pass what the caller calls this document (e.g. "the declaration").'
+    );
+  }
+
+  if (!document || typeof document !== 'object' || Array.isArray(document)) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] ${source} is not a declaration - Expected: an object with a "recurrences" list, `
+        + `got ${Array.isArray(document) ? 'an array' : typeof document}. `
+        + 'Fix: write { "recurrences": [ … ] }, or remove the file if the service declares none.'
+    );
+  }
+
+  if (!validateDeclaration(document)) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] ${source} does not hold: ${describeErrors(validateDeclaration.errors)} - `
+        + 'Expected: every record carries id, cookbook_ref, cron (five fields) and an explicit '
+        + 'IANA timezone, and nothing this shape does not declare. '
+        + 'Fix: correct the record the message names; the shape is src/config/recurrencesSchema.js. '
+        + 'Note: tenant and workspace do NOT belong here - the caller passes them '
+        + '(confirmations scheduler 010, 011; the tenancy rule itself is scheduler 002).'
+    );
+  }
+
+  const seen = new Set();
+  for (const recurrence of document.recurrences) {
+    if (seen.has(recurrence.id)) {
+      throw new Error(
+        `[mq-client-core/scheduler-request] ${source} declares the id "${recurrence.id}" twice - Expected: one record per `
+          + 'id, because the id travels as the scheduler\'s idempotency_key and a second record '
+          + 'would silently overwrite the first at every boot. '
+          + 'Fix: give each schedule its own id, or remove the duplicate.'
+      );
+    }
+    seen.add(recurrence.id);
+  }
+
+  return document.recurrences;
+}
+
+/** A whole number a tenant or workspace id may be: ≥ 1, never 0 (confirmation scheduler 002). */
+const isContextId = (value) => Number.isInteger(value) && value >= 1;
+
+/**
+ * Turn ONE declared recurrence into the message the scheduler takes.
+ *
+ * @param {Object} args
+ * @param {Object} args.declaration - One record the service declared.
+ * @param {number} args.tenantId - The tenant the runs execute under; supplied by the caller with
+ *   this recurrence (the service's own data), never a default.
+ * @param {number} args.workspaceId - The workspace the runs execute under; supplied the same way.
+ * @param {string} args.requestedBy - The service registering this schedule.
+ * @returns {Object} The `scheduler.request` message, exactly the keys the contract declares.
+ * @throws {Error} When anything is missing, zero, or not a whole number.
+ */
+function buildRecurringRequest({ declaration, tenantId, workspaceId, requestedBy } = {}) {
+  const [recurrence] = validateRecurrences({ recurrences: [declaration] }, 'the declaration');
+
+  requireTenancy(tenantId, workspaceId);
+  const by = requireRequestedBy(requestedBy);
+
+  const request = {
+    kind: 'recurring',
+    idempotency_key: recurrence.id,
+    cookbook_ref: recurrence.cookbook_ref,
+    recurrence: { cron: recurrence.cron, timezone: recurrence.timezone },
+    tenant_id: tenantId,
+    workspace_id: workspaceId,
+    requested_by: by
+  };
+
+  // Written only when the declaration states them: an absent `input` is no input, and an absent
+  // `catch_up` is the scheduler's own default (§5) - a value materialised here would be a second
+  // owner of it.
+  if (Object.prototype.hasOwnProperty.call(recurrence, 'input')) request.input = recurrence.input;
+  if (Object.prototype.hasOwnProperty.call(recurrence, 'catch_up')) request.catch_up = recurrence.catch_up;
+
+  return request;
+}
+
+/** The platform spelling of a service or an event name, as the consumer's contract defines it. */
+const NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/** The key that identifies the item, whatever kind it is - required by the contract's root. */
+function requireIdempotencyKey(idempotencyKey) {
+  if (typeof idempotencyKey !== 'string' || idempotencyKey.trim() === '') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Missing idempotency_key - Expected: the stable identity '
+        + 'of this item, chosen by the caller. The scheduler decides a one-shot item ONCE by this '
+        + 'key, so a key invented here would turn every retry of one fact into a second run. '
+        + 'Fix: pass the key that names the thing (for an event, what it happened to).'
+    );
+  }
+
+  return idempotencyKey.trim();
+}
+
+/** The service registering, cancelling or reporting - checked by the scheduler against services.json. */
+function requireRequestedBy(requestedBy) {
+  if (typeof requestedBy !== 'string' || requestedBy.trim() === '') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Missing requested_by - Expected: the platform name of the '
+        + 'service sending this request; the scheduler checks it against api/config/services.json '
+        + "and against the cookbook's own trigger declaration. "
+        + 'Fix: pass the service name the wrapper already holds.'
+    );
+  }
+
+  return requestedBy.trim();
+}
+
+/** Both context ids, under the one rule confirmation `scheduler` 002 fixed. */
+function requireTenancy(tenantId, workspaceId) {
+  if (!isContextId(tenantId)) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Invalid tenant_id ${JSON.stringify(tenantId)} - Expected: `
+        + 'a whole number of at least 1. The owner rejected a reserved value: 0 is not a platform '
+        + 'scope, and an absent tenant is an error rather than a default (confirmation scheduler 002). '
+        + 'Fix: pass tenantId with every request - a recurrence carries it in the record the service '
+        + 'returns from its own data, and ctx.scheduler fills it from the invocation envelope; it is '
+        + 'never read from anywhere else.'
+    );
+  }
+
+  if (!isContextId(workspaceId)) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Invalid workspace_id ${JSON.stringify(workspaceId)} - `
+        + 'Expected: a whole number of at least 1, under the same rule as the tenant (confirmation '
+        + 'scheduler 002). Fix: pass workspaceId with every request - a recurrence carries it in the '
+        + 'record the service returns from its own data, and ctx.scheduler fills it from the invocation '
+        + 'envelope; it is never read from anywhere else.'
+    );
+  }
+}
+
+/**
+ * Turn a fact into the message that reports it.
+ *
+ * It names NO cookbook, and that is the point: the scheduler starts every recipe whose
+ * `triggers` declare this event (confirmation `scheduler` 004), so a producer naming a recipe
+ * would be mapping work to something it may not own (`ingest-poll-trigger-rail` 001: which
+ * cookbook runs is a platform decision, not the producer's).
+ *
+ * @param {Object} args
+ * @param {{service: string, name: string}} args.event - Who it happened to, and what happened.
+ * @param {number} args.tenantId
+ * @param {number} args.workspaceId
+ * @param {string} args.requestedBy
+ * @param {string} args.idempotencyKey - The identity of this fact; see the module note.
+ * @param {Object} [args.input] - Handed to every cookbook the event starts, unchanged.
+ * @returns {Object} The `scheduler.request` message of kind `event`.
+ * @throws {Error} When anything is missing or not the shape the contract takes.
+ */
+function buildEventRequest({ event, tenantId, workspaceId, requestedBy, idempotencyKey, input } = {}) {
+  const key = requireIdempotencyKey(idempotencyKey);
+  const by = requireRequestedBy(requestedBy);
+  requireTenancy(tenantId, workspaceId);
+
+  if (!event || typeof event !== 'object' || Array.isArray(event)) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Missing event - Expected: { service, name } - who it `
+        + 'happened to and what happened, both of them. '
+        + 'Fix: pass the fact this service publishes, never a cookbook name.'
+    );
+  }
+
+  for (const [field, value] of [['service', event.service], ['name', event.name]]) {
+    if (typeof value !== 'string' || !NAME_PATTERN.test(value)) {
+      throw new Error(
+        `[mq-client-core/scheduler-request] Invalid event.${field} ${JSON.stringify(value)} - `
+          + 'Expected: the platform spelling, lower case letters, digits and dashes '
+          + '(the pattern the scheduler\'s own contract declares). '
+          + `Fix: pass the ${field} as api/config/services.json spells it.`
+      );
+    }
+  }
+
+  const request = {
+    kind: 'event',
+    idempotency_key: key,
+    event: { service: event.service, name: event.name },
+    tenant_id: tenantId,
+    workspace_id: workspaceId,
+    requested_by: by
+  };
+
+  if (input !== undefined) request.input = input;
+
+  return request;
+}
+
+/**
+ * Take an item back by its key.
+ *
+ * Idempotent by contract: a key that names nothing is answered `cancel-nothing` by the
+ * scheduler, not refused - so this builder judges nothing about the key, it only requires one.
+ * The item carries the context it was registered with, which is why no tenancy travels here.
+ *
+ * @param {Object} args
+ * @param {string} args.idempotencyKey - The key of the schedule or pending item to remove.
+ * @param {string} args.requestedBy - Only the service that registered an item may cancel it.
+ * @returns {Object} The `scheduler.request` message of kind `cancel`.
+ * @throws {Error} When the key or the requester is missing.
+ */
+function buildCancelRequest({ idempotencyKey, requestedBy } = {}) {
+  return {
+    kind: 'cancel',
+    idempotency_key: requireIdempotencyKey(idempotencyKey),
+    requested_by: requireRequestedBy(requestedBy)
+  };
+}
+
+/** Every key the port's `registerRecurring()` takes — anything else is refused, never dropped. */
+const RECURRING_PORT_KEYS = Object.freeze([
+  'id', 'cookbookRef', 'cron', 'timezone', 'tenantId', 'workspaceId', 'input', 'catchUp'
+]);
+
+/** The kinds this library builds, and the only ones it will send. */
+const SENDABLE_KINDS = Object.freeze(['recurring', 'event', 'cancel']);
+
+/**
+ * Send one request of any kind this library builds. Throws on every refusal — see the module
+ * note on fail-fast.
+ *
+ * @param {Object} mqClient - A connected `BaseClient`.
+ * @param {Object} request - What one of the builders above produced.
+ * @returns {Promise<void>}
+ * @throws {Error} When the client is not connected, the request is not one of ours, or the
+ *   publish fails.
+ */
+async function publishSchedulerRequest(mqClient, request) {
+  if (!mqClient || typeof mqClient.publish !== 'function' || typeof mqClient.isConnected !== 'function') {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Missing client - Expected: a connected @onlineapps/mq-client-core BaseClient, so `
+        + `the registration reaches ${schedulerRequestQueue}. `
+        + 'Fix: pass the client the composition root connected.'
+    );
+  }
+
+  if (!mqClient.isConnected()) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] The client is not connected - Expected: a registration reaches `
+        + `${schedulerRequestQueue} before the service starts taking work; a schedule nobody `
+        + 'registered is a run that never happens. Fix: connect the client first.'
+    );
+  }
+
+  if (!request || !SENDABLE_KINDS.includes(request.kind) || typeof request.idempotency_key !== 'string') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Not a request this library built - Expected: one of '
+        + `${SENDABLE_KINDS.join(', ')}, got kind ${JSON.stringify(request && request.kind)}. `
+        + 'Fix: build the message with buildRecurringRequest(), buildEventRequest() or '
+        + 'buildCancelRequest() before sending it.'
+    );
+  }
+
+  try {
+    await mqClient.publish(schedulerRequestQueue, request);
+  } catch (error) {
+    throw new Error(
+      `[mq-client-core/scheduler-request] Could not send "${request.idempotency_key}" (${request.kind}) `
+        + `on ${schedulerRequestQueue}: ${error.message} - Expected: the request to reach the `
+        + 'scheduler; a request nobody received is work that will not happen. '
+        + 'Fix: act on the reason above - the boot stops here rather than running a service whose '
+        + 'schedules were silently not registered.',
+      { cause: error }
+    );
+  }
+}
+
+/**
+ * A port one service holds: the three things it says, with WHO is speaking already decided.
+ *
+ * TWO CALLERS, TWO DOORS. The wrapper builds `ctx.scheduler` over this factory at boot and fills
+ * the tenancy of each call from the envelope of the run. The operator CLIs of biz-ingest
+ * (`scripts/run-{poll,fetch-source-item,retry-pending-items}.js`) do NOT boot the wrapper - a
+ * bootstrap there would start consumers, the registry and a heartbeat - and today they are the
+ * only way a document of the pilot comes into being, so they call this factory directly with the
+ * service identity and the tenancy of the row they are working on. That is why tenancy is
+ * explicit on every call rather than held by the port: one port, two kinds of caller, and no
+ * hidden context that the CLI would have to fake (BIZ-ingest measurement, 2026-09-23).
+ *
+ * EAGER ON PURPOSE. The client and the name of the queue are decided HERE, when the port is
+ * made, so a service that announces facts falls over at boot rather than at its first document.
+ * (On a pin whose `queueConfig` declares no `scheduler` section this module already refuses at
+ * require time, which is earlier still.) And because a defect of the wiring must never answer in
+ * place of the operation, every refusal names the slot it is about and how to fix it.
+ *
+ * @param {Object} args
+ * @param {Object} args.mqClient - A `BaseClient` (connected by the time a verb is called).
+ * @param {string} args.requestedBy - The service this port speaks for; it becomes `requested_by`
+ *   on every request and `event.service` on every fact.
+ * @returns {{registerRecurring: Function, publishEvent: Function, cancel: Function}}
+ * @throws {Error} When a slot is missing or unusable - at construction, never later.
+ */
+function createSchedulerPublisher({ mqClient, requestedBy } = {}) {
+  if (!mqClient || typeof mqClient.publish !== 'function' || typeof mqClient.isConnected !== 'function') {
+    throw new Error(
+      '[mq-client-core/scheduler-request] Cannot build the scheduler port: slot "mqClient" is '
+        + 'missing or cannot publish - Expected: the @onlineapps/mq-client-core BaseClient this '
+        + `service connects, so a request reaches ${schedulerRequestQueue}. This is decided now, at `
+        + 'construction, because a service that announces facts must fail at boot rather than at '
+        + 'its first document. Fix: pass the client the composition root built.'
+    );
+  }
+
+  const by = (() => {
+    try {
+      return requireRequestedBy(requestedBy);
+    } catch (error) {
+      throw new Error(
+        '[mq-client-core/scheduler-request] Cannot build the scheduler port: slot "requestedBy" is '
+          + `missing - ${error.message} `
+          + 'Fix: pass the platform name of the service this port speaks for (config.serviceName).'
+      );
+    }
+  })();
+
+  return {
+    /**
+     * Re-assert one recurrence. The id is the schedule's identity, so a repeat upserts.
+     *
+     * @param {Object} args - `{ id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }`
+     * @returns {Promise<void>}
+     */
+    async registerRecurring(record = {}) {
+      // As strict as the declaration it becomes (`additionalProperties: false` in
+      // `./config/recurrencesSchema.js`): a key nobody reads is a typo or a second definition of
+      // something, and dropping it in silence hides both (`architecture-principles.md` §3).
+      for (const key of Object.keys(record)) {
+        if (!RECURRING_PORT_KEYS.includes(key)) {
+          throw new Error(
+            `[mq-client-core/scheduler-request] registerRecurring got a key the request does not declare ("${key}") - `
+              + 'Expected: exactly { id, cookbookRef, cron, timezone, tenantId, workspaceId, input?, catchUp? }. '
+              + 'Fix: remove the key from the record the service returns / the ctx.scheduler call.'
+          );
+        }
+      }
+
+      const { id, cookbookRef, cron, timezone, tenantId, workspaceId, input, catchUp } = record;
+      const declaration = { id, cookbook_ref: cookbookRef, cron, timezone };
+      if (input !== undefined) declaration.input = input;
+      if (catchUp !== undefined) declaration.catch_up = catchUp;
+
+      await publishSchedulerRequest(mqClient, buildRecurringRequest({
+        declaration,
+        tenantId,
+        workspaceId,
+        requestedBy: by
+      }));
+    },
+
+    /**
+     * Announce one fact. The service is this port's; the key is the caller's (the identity of the
+     * thing that happened - a job's uuid, not a clock reading), because the scheduler decides a
+     * one-shot item once by it.
+     *
+     * @param {Object} args - `{ name, idempotencyKey, tenantId, workspaceId, input? }`
+     * @returns {Promise<void>}
+     */
+    async publishEvent({ name, idempotencyKey, tenantId, workspaceId, input } = {}) {
+      await publishSchedulerRequest(mqClient, buildEventRequest({
+        event: { service: by, name },
+        idempotencyKey,
+        tenantId,
+        workspaceId,
+        requestedBy: by,
+        input
+      }));
+    },
+
+    /**
+     * Take back an item this service registered, by its id.
+     *
+     * @param {Object} args - `{ id }`
+     * @returns {Promise<void>}
+     */
+    async cancel({ id } = {}) {
+      await publishSchedulerRequest(mqClient, buildCancelRequest({
+        idempotencyKey: id,
+        requestedBy: by
+      }));
+    }
+  };
+}
+
+module.exports = {
+  schedulerRequestQueue,
+  SENDABLE_KINDS,
+  validateRecurrences,
+  buildRecurringRequest,
+  buildEventRequest,
+  buildCancelRequest,
+  publishSchedulerRequest,
+  createSchedulerPublisher
+};

package/src/transports/rabbitmqClient.js

@@ -1416,6 +1416,70 @@ class RabbitMQClient extends EventEmitter {
     }
   }
 
+  /**
+   * Race an `amqp.connect()` handshake against its `connectTimeout`, and own the
+   * handshake the timeout abandons.
+   *
+   * When the timeout wins, the race rejects but the handshake does not stop: it
+   * can still complete into a full AMQP connection that no field of this client
+   * points at, so `disconnect()` never closes it and it keeps the process alive
+   * (INFRA 359, measured with a proxy delaying the handshake past the timeout).
+   * The rejection the caller receives is unchanged; what changes is that the
+   * abandoned handshake is closed the moment it completes.
+   *
+   * @private
+   * @param {Promise<Object>} connectPromise - the handshake from `amqp.connect()`
+   * @param {Promise<never>} timeoutPromise - rejects with the timeout error
+   * @param {string} phase - 'connect' or 'reconnect', named in the log lines
+   * @returns {Promise<Object>} the connection, when the handshake won the race
+   */
+  async _raceHandshake(connectPromise, timeoutPromise, phase) {
+    let abandoned = false;
+    const timeoutLeg = timeoutPromise.catch((err) => {
+      abandoned = true;
+      throw err;
+    });
+    try {
+      return await Promise.race([connectPromise, timeoutLeg]);
+    } catch (err) {
+      if (abandoned) {
+        this._closeAbandonedHandshake(connectPromise, phase);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Close the connection an abandoned handshake produces, whenever it completes.
+   * A handshake that fails after its timeout opened nothing; its error adds
+   * nothing to the timeout the caller already received.
+   * @private
+   * @param {Promise<Object>} connectPromise - the handshake the timeout abandoned
+   * @param {string} phase - 'connect' or 'reconnect'
+   */
+  _closeAbandonedHandshake(connectPromise, phase) {
+    connectPromise.then(
+      async (late) => {
+        this._logger.warn(
+          `[RabbitMQClient] Handshake completed after the ${phase} timeout (${this._connectTimeout} ms) - `
+            + 'closing that connection, nothing in this client owns it'
+        );
+        try {
+          await late.close();
+        } catch (closeErr) {
+          this._logger.warn(
+            `[RabbitMQClient] Error closing the connection whose handshake outlived the ${phase} timeout: ${closeErr.message}`
+          );
+        }
+      },
+      (lateErr) => {
+        this._logger.debug(
+          `[RabbitMQClient] Handshake abandoned by the ${phase} timeout failed afterwards: ${lateErr.message}`
+        );
+      }
+    );
+  }
+
   /**
    * Clear all active timers
    * @private
@@ -1459,7 +1523,7 @@ class RabbitMQClient extends EventEmitter {
         }
       });
       this._logger.debug('[RabbitMQClient] Starting connection race...');
-      this._connection = await Promise.race([connectPromise, timeoutPromise]);
+      this._connection = await this._raceHandshake(connectPromise, timeoutPromise, 'connect');
       if (connectTimeoutTimer) {
         this._clearTimeout(connectTimeoutTimer);
         connectTimeoutTimer = null;
@@ -3941,7 +4005,7 @@ class RabbitMQClient extends EventEmitter {
           )), this._connectTimeout);
         });
 
-        const revived = await Promise.race([connectPromise, timeoutPromise]);
+        const revived = await this._raceHandshake(connectPromise, timeoutPromise, 'reconnect');
 
         // The caller may have disposed of this client while that handshake was
         // in flight. The socket is up, and it belongs to nobody: keeping it