@onlineapps/mq-client-core 4.0.1 → 4.2.0

package/CHANGELOG.md

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

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