@onlineapps/mq-client-core 4.0.1 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,83 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [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

@@ -673,6 +673,53 @@ 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.
+
 ### 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.1.0",
   "description": "Core MQ client library for RabbitMQ - shared by infrastructure services and connectors",
   "oa": {
     "category": "connector"

package/src/config/queueConfig.js

@@ -60,7 +60,8 @@ const SECTION_PREFIXES = Object.freeze({
   monitoring: 'monitoring',
   telemetry: 'telemetry',
   alerts: 'alert',
-  registry: 'registry'
+  registry: 'registry',
+  scheduler: 'scheduler'
 });
 
 /**
@@ -81,7 +82,8 @@ const INFRASTRUCTURE_PREFIX_LOOKUPS = Object.freeze({
   validation: 'getValidationQueueConfig',
   monitoring: 'getMonitoringQueueConfig',
   telemetry: 'getTelemetryQueueConfig',
-  delivery: 'getDeliveryQueueConfig'
+  delivery: 'getDeliveryQueueConfig',
+  scheduler: 'getSchedulerQueueConfig'
 });
 
 const INFRASTRUCTURE_PREFIXES = Object.freeze(Object.keys(INFRASTRUCTURE_PREFIX_LOOKUPS));
@@ -689,6 +691,33 @@ module.exports = {
       durable: true
     },
 
+    /**
+     * monitoring.resource - Topic exchange for resource-changed events
+     *
+     * The monitoring consumer's resource-changed watcher publishes here with a routing
+     * key of the shape `resource.changed.<resource_type>`; the delivery endpoint binds
+     * `delivery.resource.events` to it by the pattern `resource.changed.#` for WS push.
+     * Three sides of ONE wire — the publisher, this exchange and the bound queue — and
+     * until d.619 the name had an owner on none of them: a module constant on the
+     * publishing side and a required env key on the binding side, so an override or a
+     * typo on either side loses every event silently. That is the same reasoning d.270
+     * settled for the health-events fanout, and the reason the name lives here and is
+     * published by `src/index.js` § topology.
+     *
+     * `topic`, `durable`, no arguments: what the publisher asserts, and what the running
+     * broker answers for it. An exchange holds nothing to dead-letter, so — like every
+     * other exchange in this file — it carries no route, even though every QUEUE of this
+     * section routes to `monitoring.dlq`.
+     *
+     * @see api/infra/api_monitoring/src/consumer/watchers/resourceChangedPublisher.js
+     * @see api/docs/biz/70-contracts/resource-changed.md
+     */
+    resource: {
+      type: 'exchange',
+      exchangeType: 'topic',
+      durable: true
+    },
+
     /**
      * monitoring.infrastructure.health.events - the monitoring consumer's own copy of
      * the infrastructure health events, bound to the infrastructure.health.events
@@ -743,8 +772,8 @@ module.exports = {
    * Telemetry queue configurations
    *
    * The OpenTelemetry intake of the monitoring consumer: every service publishes
-   * logs, metrics and spans to `telemetry.exchange` with a routing key carrying its
-   * own name, and these three queues are bound to it
+   * logs, metrics and spans to the `telemetry.exchange` declared below, with a routing
+   * key carrying its own name, and these three queues are bound to it
    * (`docs/standards/monitoring-queues.md`, `docs/architecture/monitoring.md`).
    *
    * The TTL and the cap are the ones the queues are created with today; this config is
@@ -758,6 +787,45 @@ module.exports = {
    * @see api/docs/governance/confirmations/mq-consumer-contract.md 003
    */
   telemetry: {
+    /**
+     * telemetry.exchange - the topic exchange every telemetry producer on the platform
+     * publishes to, and the one the three queues below are bound to.
+     *
+     * The widest wire there is: every biz service through `@onlineapps/service-wrapper`,
+     * every infrastructure service through `@onlineapps/monitoring-core` (its logger and
+     * its OpenTelemetry exporter), and the monitoring consumer, which asserts the
+     * exchange, binds the three queues and drains them — and since I16 publishes its own
+     * lines onto it as well.
+     *
+     * Until d.708 the name appeared HERE only in the prose above, while the other three
+     * platform exchanges of this file (`infrastructure.health.events`,
+     * `monitoring.workflow.fanout`, `monitoring.resource`) each had a template. So one
+     * name had three owners — a module constant in the monitoring consumer
+     * (`infra/api_monitoring/src/consumer/topology.js`) and a config default in each of
+     * monitoring-core's two publishers — which is exactly the shape d.270 gave an owner
+     * for the health-events fanout and d.619 for the resource-changed topic
+     * (`change-discipline.md` § One rail per concern).
+     *
+     * `topic`, `durable`, no arguments: what all three of those sides assert today
+     * (`assertExchange(<name>, 'topic', { durable: true })`), measured before this entry
+     * was written. The broker compares an exchange's type and durability at EVERY
+     * declaration, so a value invented here would be `406 PRECONDITION-FAILED` for
+     * whichever side booted second. An exchange holds nothing to dead-letter, so — like
+     * every other exchange in this file — it carries no route, even though every QUEUE
+     * of this section routes to `telemetry.dlq`.
+     *
+     * Declaring it is not creating it: the exchange is brought into being by the service
+     * that asserts it, the same rule as `telemetry.dlq` below.
+     *
+     * @see api/infra/api_monitoring/src/consumer/index.js — assertMonitoringTopology()
+     * @see api/shared/monitoring/monitoring-core/src/exporters/rabbitmq.js
+     */
+    exchange: {
+      type: 'exchange',
+      exchangeType: 'topic',
+      durable: true
+    },
+
     /** telemetry.logs.queue - OpenTelemetry log records, drained into Loki. */
     'logs.queue': {
       durable: true,
@@ -932,15 +1000,129 @@ module.exports = {
     },
 
     /**
-     * registry.changes - Registry event fanout exchange
-     * (This is an exchange, not a queue, but included for reference)
+     * registry.changes - the fanout exchange registry index changes travel on.
+     *
+     * One module is every side of this wire: `@onlineapps/conn-orch-registry`,
+     * `src/registryEventConsumer.js`. It holds the only spelling of the name (`:92`),
+     * it is the only party that ASSERTS the exchange (`:117`,
+     * `assertExchange(name, 'fanout', { durable: true })`), it binds each service's
+     * `{service}.registry.events` to it with the pattern `''` (`:133`), and it publishes
+     * the snapshot request onto it (`:331`, `routingKey: ''`). The publish path declares
+     * nothing since d.342, so there is no second founder.
+     *
+     * Until d.712 this was the ONE exchange of this file with no `exchangeType`, so the
+     * founder had to decide the kind on its own while the template only said "an
+     * exchange, durable". `type` is one of the two properties the broker compares at
+     * every declaration, which makes it exactly the half that cannot live somewhere
+     * else (`change-discipline.md` § One rail per concern; the same step d.619 made for
+     * `monitoring.resource` and d.708 for `telemetry.exchange`).
+     *
+     * `fanout`, `durable`, no arguments: measured on that founder, not chosen. The
+     * binding pattern `''` only routes on a fanout, so the type is load-bearing rather
+     * than decorative. An exchange holds nothing to dead-letter, so — like every other
+     * exchange in this file — it carries no route.
+     *
+     * Declaring it is not creating it: the exchange is brought into being by the service
+     * whose registry client subscribes to changes.
+     *
+     * @see api/shared/connector/conn-orch-registry/src/registryEventConsumer.js
      */
     changes: {
       type: 'exchange',
+      exchangeType: 'fanout',
       durable: true
     }
   },
 
+  /**
+   * Scheduler queue configurations — the platform's one holder of time.
+   *
+   * The scheduler consumes requests for a run: a recurrence that came due, or a deferred
+   * request somebody filed. Both are published by other services and both are the ONLY
+   * record that the run was owed, so the family is shaped for loss-aversion rather than
+   * for freshness (`docs/governance/confirmations/scheduler.md` 001, 004).
+   *
+   * @see api/infra/api_scheduler/README.md
+   */
+  scheduler: {
+    /**
+     * scheduler.request - every request for a run, from every producer.
+     *
+     * NO `x-message-ttl`, deliberately, and it is the one property that differs from the
+     * shape of a workflow queue: a request that waited out a consumer outage is still the
+     * run that was due, and a TTL would turn that outage into runs which silently never
+     * happened. What bounds the queue is its length, and what catches a request the
+     * scheduler could not process is the family's dead-letter queue below — over the
+     * DEFAULT exchange, where the routing key IS the destination name, the same way every
+     * other infrastructure family here routes (the `dlx` exchange belongs to the business
+     * templates, whose queues one service owns).
+     *
+     * Without this declaration `consume()` refuses to attach a consumer at all — a queue
+     * with no declared route would have the broker DROP what the policy rejects
+     * (`docs/governance/confirmations/mq-consumer-contract.md` 002).
+     */
+    request: {
+      durable: true,
+      arguments: {
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'scheduler.dlq'
+      }
+    },
+
+    /**
+     * scheduler.workflow.events - where the scheduler learns that a run it started ENDED.
+     *
+     * 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.
+     *
+     * 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
+     * platform and the scheduler discards most of them. 300 000 ms is what
+     * `monitoring.workflow` carries on the same exchange - the sibling whose readings this
+     * one follows. What an outage longer than the TTL costs is on record: those events are
+     * lost and the run is closed by the per-schedule timeout, which 007 keeps as the
+     * backstop rather than replacing it.
+     *
+     * The route goes over the DEFAULT exchange, like every other infrastructure family
+     * here, and ends in this family's own `scheduler.dlq`. Without a declared route
+     * `consume()` refuses to attach at all (`BaseClient.js`,
+     * `CONSUMER_DEAD_LETTER_ROUTE_MISSING`; `mq-consumer-contract` 002).
+     *
+     * @see api/docs/governance/confirmations/scheduler.md 007
+     */
+    'workflow.events': {
+      durable: true,
+      arguments: {
+        'x-message-ttl': 300000,      // Stated by confirmation 007, like monitoring.workflow
+        'x-max-length': 10000,
+        'x-dead-letter-exchange': '',        // Default exchange: routing key IS the queue name
+        'x-dead-letter-routing-key': 'scheduler.dlq'
+      }
+    },
+
+    /**
+     * scheduler.dlq - the END of this family's chain.
+     *
+     * Durable, capped higher, no TTL and no onward route — the three properties every
+     * dead-letter queue in this file carries, and the reason the operator's `*.dlq`
+     * dashboard finds it (`mq-consumer-contract` 003).
+     */
+    dlq: {
+      durable: true,
+      arguments: {
+        // No TTL for DLQ - messages should persist
+        'x-max-length': 50000         // Higher limit for DLQ
+      }
+    }
+  },
+
   /**
    * The full wire name of a declared entry: the section's prefix + the entry's key.
    *
@@ -1219,6 +1401,23 @@ module.exports = {
     return this.getQueueConfig('infrastructure', name);
   },
 
+  /**
+   * Get scheduler queue configuration
+   * @param {string} queueName - Queue name (e.g., 'scheduler.request')
+   * @returns {Object} Queue configuration
+   * @throws {ValidationError} If the name carries another prefix, or nothing declares it.
+   */
+  getSchedulerQueueConfig(queueName) {
+    if (!queueName.startsWith('scheduler.')) {
+      throw new ValidationError(
+        `[queueConfig] Queue ${queueName} is not a scheduler queue - Expected: a name starting with "scheduler.". `
+          + 'Fix: call getInfrastructureQueueConfig(), which routes each prefix to the right lookup.'
+      );
+    }
+    const name = queueName.slice('scheduler.'.length);
+    return this.getQueueConfig('scheduler', name);
+  },
+
   /**
    * Get monitoring queue configuration
    * @param {string} queueName - Queue name (e.g., 'monitoring.workflow')

package/src/index.js

@@ -36,6 +36,10 @@ const {
   publishToMonitoringServices,
   isQueueUnavailableError,
 } = require('./monitoring-publish');
+const {
+  buildWorkflowInitiatedEvent,
+  publishWorkflowInitiated,
+} = require('./monitoring-initiated');
 const queueConfig = require('./config/queueConfig');
 const deliveryPolicy = require('./config/deliveryPolicy');
 const { redactUrl, UNPARSEABLE_PLACEHOLDER } = require('@onlineapps/logger-contract');
@@ -84,6 +88,11 @@ module.exports.monitoring = {
   publishToMonitoringWorkflow,
   publishToMonitoringServices,
   isQueueUnavailableError,
+  // d.819 - the one builder of `workflow_initiated`, beside the transport half it uses
+  // (`docs/governance/confirmations/scheduler.md` 009). The gateway and the scheduler each
+  // built that event in their own words; two rails over one event is a defect by default.
+  buildWorkflowInitiatedEvent,
+  publishWorkflowInitiated,
 };
 /** The only public way to reach the central queue classification; `src/config/queueConfig` is an internal path, not a contract. */
 module.exports.queueConfig = queueConfig;
@@ -109,6 +118,18 @@ module.exports.topology = Object.freeze({
   monitoringInfrastructureHealthEventsQueue: queueConfig.queueName('monitoring', 'infrastructure.health.events'),
   /** The delivery endpoint's queue bound to that exchange, for WS push. */
   deliveryHealthEventsQueue: queueConfig.queueName('deliveryEvents', 'health.events'),
+  /**
+   * Topic exchange: the monitoring consumer's resource-changed watcher publishes here,
+   * with a routing key of the shape `resource.changed.<resource_type>`.
+   *
+   * Declared in `queueConfig` since d.619. Until then the name was a module constant on
+   * the publishing side and a required env key on the binding side
+   * (`MONITORING_RESOURCE_EXCHANGE`) — the third side of this wire with no owner, while
+   * the queue bound to it had one here since d.270.
+   *
+   * @see api/infra/api_monitoring/src/consumer/watchers/resourceChangedPublisher.js
+   */
+  monitoringResourceExchange: queueConfig.queueName('monitoring', 'resource'),
   /**
    * The delivery endpoint's queue for resource-changed events, bound to the
    * `monitoring.resource` exchange by the routing pattern `resource.changed.#`.

package/src/monitoring-initiated.js

@@ -0,0 +1,187 @@
+'use strict';
+
+/**
+ * The `workflow_initiated` event — ONE rail for every service that starts a run.
+ *
+ * Monitoring learns that a run exists from this event and from nothing else: its intake
+ * reads the run's tenancy, labels and trigger out of `workflow_initiated` and marks the
+ * run `active` on it (`api/infra/api_monitoring/src/consumer/index.js`). A service that
+ * does not file it starts runs that are invisible for their whole life.
+ *
+ * Until now two services built that event, each in its own words: the gateway
+ * (`infra/api_gateway/shared/monitoringInitiatedCopy.js`, with a redacted cookbook) and
+ * the scheduler (`infra/api_scheduler/src/publisher/workflowPublisher.js`, inline, the
+ * cookbook verbatim and no `tenant_uuid` at all). Two implementations of one concern are
+ * a defect by default (`change-discipline.md` § One rail per concern), and the owner
+ * settled which rail survives: this one, in the library that already owns the transport
+ * half of the same wire (`docs/governance/confirmations/scheduler.md` 009). Both copies
+ * are retired by their own services in the change that adopts this module — no period
+ * with both (`architecture-principles.md` §11).
+ *
+ * WHAT THIS MODULE DOES NOT DO, deliberately:
+ *
+ *   1. **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 library a
+ *      dependency on the operation specs and on `infrastructure-tools`. The caller passes
+ *      the observability copy it already built (`cookbookRedaction.js` in the gateway); 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.
+ *   2. **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, so
+ *      `tenant_uuid: null` passes through as the explicit value it is (a webhook run has
+ *      no personal identity, and a scheduled run of the pilot writes `null` on purpose —
+ *      `docs/governance/confirmations/run-envelope-tenant-uuid.md` 001). A `|| null` here
+ *      would hide a broken envelope instead of reporting it (`architecture-principles.md`
+ *      §3).
+ *
+ * @see api/docs/governance/confirmations/scheduler.md 009
+ * @see api/docs/biz/70-contracts/monitoring-events.md
+ * @see ./monitoring-publish.js — the transport half: the queue, the fanout, the fail-safe
+ */
+
+const { assertLogger } = require('@onlineapps/logger-contract');
+const { publishToMonitoringWorkflow } = require('./monitoring-publish');
+
+/** Starting a run is not a step of the cookbook; it has its own constant coordinates. */
+const STEP_ID = 'workflow_start';
+const STEP_INDEX = -1;
+/** The event's own two words, which the monitoring intake matches on. */
+const EVENT_TYPE = 'initiated';
+const STATUS = 'initiated';
+
+/** The keys of `_system` this event carries, each of which must exist on the envelope. */
+const REQUIRED_SYSTEM_KEYS = Object.freeze(['tenant_id', 'tenant_uuid']);
+
+/**
+ * The body of the `initiated` event — exactly these keys and no others.
+ *
+ * @param {Object} args
+ * @param {string} args.workflowId - the id of the run this event reports.
+ * @param {Object} args.redactedCookbook - the observability copy of the unified cookbook,
+ *   ALREADY redacted by the caller; it travels as it arrived.
+ * @param {string} args.serviceName - the platform name of the service filing the event;
+ *   the monitoring intake refuses an event that names no publisher (`service_name_missing`).
+ * @param {string} args.timestamp - the instant the run started, ISO-8601. The caller's,
+ *   not a second reading of the clock here: the run and the row observing it then say the
+ *   same thing.
+ * @returns {Object} the message for `monitoring.workflow`.
+ * @throws {Error} when an argument is missing, or the envelope does not carry what this
+ *   event states about it.
+ */
+function buildWorkflowInitiatedEvent({ workflowId, redactedCookbook, serviceName, timestamp } = {}) {
+  if (typeof workflowId !== 'string' || workflowId.trim() === '') {
+    throw new Error(
+      '[monitoring-initiated] Missing workflow_id - Expected: the id of the run this event '
+        + 'reports, as a non-empty string. Fix: pass workflowId of the run being published.'
+    );
+  }
+  if (typeof serviceName !== 'string' || serviceName.trim() === '') {
+    throw new Error(
+      '[monitoring-initiated] Missing service_name - Expected: the platform name of the service '
+        + 'filing this event; the monitoring intake refuses an event that names no publisher '
+        + '(service_name_missing). Fix: pass config.serviceName.'
+    );
+  }
+  if (typeof timestamp !== 'string' || timestamp.trim() === '') {
+    throw new Error(
+      '[monitoring-initiated] Missing timestamp - Expected: the instant the run started, as an '
+        + 'ISO-8601 string taken from the run itself, so the run and the row observing it say the '
+        + 'same thing. Fix: pass the envelope\'s own instant, not a new Date() read here.'
+    );
+  }
+  if (!redactedCookbook || typeof redactedCookbook !== 'object') {
+    throw new Error(
+      '[monitoring-initiated] Missing cookbook - Expected: the redacted observability copy of the '
+        + 'unified cookbook. Fix: pass the copy the caller built with its own redaction '
+        + '(a path that cannot redact does not file this event at all).'
+    );
+  }
+
+  const system = redactedCookbook._system;
+  if (!system || typeof system !== 'object') {
+    throw new Error(
+      '[monitoring-initiated] Cookbook carries no _system - Expected: the unified cookbook with '
+        + 'its system metadata, which is where the intake reads the run\'s tenancy, labels and '
+        + 'trigger. Fix: build the copy from the unified cookbook the run was published with.'
+    );
+  }
+
+  for (const key of REQUIRED_SYSTEM_KEYS) {
+    if (!Object.prototype.hasOwnProperty.call(system, key)) {
+      throw new Error(
+        `[monitoring-initiated] Cookbook _system carries no ${key} - Expected: every entry path `
+          + 'writes it explicitly (a value, or null where the path has none - a webhook run proves '
+          + 'itself by signature, a scheduled run of the pilot has no personal identity). '
+          + `Fix: set _system.${key} where the unified cookbook is built.`
+      );
+    }
+  }
+
+  return {
+    event_type: EVENT_TYPE,
+    workflow_id: workflowId,
+    service_name: serviceName,
+    step_index: STEP_INDEX,
+    step_id: STEP_ID,
+    cookbook: redactedCookbook,
+    status: STATUS,
+    tenant_uuid: system.tenant_uuid,
+    tenant_id: system.tenant_id,
+    timestamp
+  };
+}
+
+/**
+ * File the `initiated` event. NEVER throws — a lost copy is reported, not raised.
+ *
+ * It is observability about a run that has already happened: refusing the run because the
+ * observer could not be told would trade a real effect for a record of it. Both services
+ * that build this event today made the same decision in their own words, and it moves here
+ * with the event. A missing logger is the one exception, and it is the transport half's
+ * rule (`monitoring-publish.js`): without a logger the promise "every failure is reported"
+ * cannot hold, so the call refuses instead of dropping events in silence.
+ *
+ * @param {Object} args
+ * @param {Object} args.mqClient - the connected `BaseClient`.
+ * @param {Object} args.logger - the service logger; REQUIRED.
+ * @param {string} args.workflowId
+ * @param {Object} args.redactedCookbook
+ * @param {string} args.serviceName
+ * @param {string} args.timestamp
+ * @param {Object} [args.context] - extra context for the log lines.
+ * @returns {Promise<boolean>} whether the event reached the broker.
+ */
+async function publishWorkflowInitiated({
+  mqClient,
+  logger,
+  workflowId,
+  redactedCookbook,
+  serviceName,
+  timestamp,
+  context = {}
+} = {}) {
+  assertLogger(
+    'publishWorkflowInitiated',
+    logger,
+    'a copy monitoring never received is reported instead of silently returning false',
+    'pass the logger your service already built'
+  );
+
+  try {
+    const event = buildWorkflowInitiatedEvent({ workflowId, redactedCookbook, serviceName, timestamp });
+    return await publishToMonitoringWorkflow(mqClient, event, logger, { workflowId, ...context });
+  } catch (error) {
+    logger.warn('[monitoring-initiated] Failed to publish workflow_initiated to monitoring', {
+      ...context,
+      workflow_id: workflowId,
+      service_name: serviceName,
+      error: error.message
+    });
+    return false;
+  }
+}
+
+module.exports = {
+  buildWorkflowInitiatedEvent,
+  publishWorkflowInitiated
+};

package/src/transports/rabbitmqClient.js

@@ -3437,9 +3437,11 @@ class RabbitMQClient extends EventEmitter {
     // leaves exactly those without a route of their own, because a dead-letter
     // route on a dead-letter queue is a loop or a chain with no end
     // (`mq-consumer-contract` 002 point 2, 003 point 2). Until d.452 the gate
-    // asked only the first question, so the operator's own queue was
-    // unconsumable and its reader — the delivery dispatcher — could not attach
-    // at all. The second question is derived from the templates
+    // asked only the first question, so the operator's own queue could not be
+    // consumed through this library at all. Who reads such a queue is that
+    // service's own fact, not this file's —
+    // @see api/infra/api_monitoring/src/consumer/deadLetterPeek.js
+    // The second question is derived from the templates
     // (`queueConfig.isDeadLetterTarget()`), never from a list of names, so it
     // cannot fall behind them; every other queue with no route is refused
     // exactly as before, with the same sentence.