@onlineapps/mq-client-core 4.0.1 → 4.2.0

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/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
+};