@alexify/migronaut 2.3.0 → 2.4.0

package/src/core/migrator.js

@@ -26,6 +26,7 @@ const { computeChecksum } = require('../utils/checksum.js');
 const { mapLimit } = require('../utils/concurrency.js');
 const { errorText, errorWithCause } = require('../utils/error.js');
 const { createIdGenerator } = require('../utils/id.js');
+const { jobFields } = require('../utils/job-ref.js');
 const { loadMigrationFile } = require('../utils/loader.js');
 const { resolveLogger } = require('../utils/logger.js');
 const { assertMigrationName } = require('../utils/migration-name.js');
@@ -77,6 +78,7 @@ const { readChunks, readShardKey } = require('./shard-info.js');
 
 const { runImport } = require('./import-runner.js');
 const { MigrationLock, runWithLock, toLockInfo } = require('./lock.js');
+const { MIGRATION_LOG_EVENT, backgroundLogs, createRunLog } = require('./migration-logger.js');
 const {
   assertActorValid,
   assertConvergeOptions,
@@ -85,6 +87,7 @@ const {
   assertFilename,
   assertHistoryLimit,
   assertImportOptions,
+  assertJobValid,
   assertListOptions,
   assertRedoOptions,
   assertUpOptions,
@@ -137,6 +140,14 @@ class MigratorKit extends EventEmitter {
   #runSetupDepth = 0;
   /** Correlation id for the run in flight — ties logs, lock and changelog together */
   #runId;
+  /**
+   * The log side of the run in flight (migration-logger's `createRunLog`): its
+   * job and actor, `ctx.run`, `ctx.logger`, the `migration:log` counter. Set
+   * and cleared with #runId; a logger keeps what it was made with.
+   */
+  #runLog;
+  /** The `migration:log` channel handed to migration loggers — made once */
+  #logEmitterInstance;
   /** Mints an id in the configured format (`generateId`, else a UUID); set with the config */
   #newId;
   /** Spans and metrics through the injected `telemetry` (a no-op without one); set with the config */
@@ -191,7 +202,11 @@ class MigratorKit extends EventEmitter {
   #moduleCache = new Map();
 
   constructor(config = {}, options = {}) {
-    super();
+    // An async listener whose promise rejects (a subscriber's insert that
+    // failed) would otherwise surface as an unhandledRejection, which ends the
+    // process — captureRejections routes it to the method below instead, so it
+    // is contained the way #emit contains a listener that throws.
+    super({ captureRejections: true });
     this.#partialConfig = config;
     this.#configPath = options.configPath;
     this.#progress = options.progress;
@@ -208,8 +223,13 @@ class MigratorKit extends EventEmitter {
    * failure into a second, unrelated one.
    */
   #emit(event, payload) {
+    this.#deliver(event, { ...(this.#runId ? { runId: this.#runId } : {}), ...payload });
+  }
+
+  /** {@link #emit} without the run id stamp: for a payload that carries its own */
+  #deliver(event, payload) {
     try {
-      this.emit(event, { ...(this.#runId ? { runId: this.#runId } : {}), ...payload });
+      this.emit(event, payload);
     } catch (error) {
       // A listener's failure is its own problem — but an invisible one is
       // undebuggable, so leave a trace at debug level.
@@ -220,6 +240,23 @@ class MigratorKit extends EventEmitter {
     }
   }
 
+  /**
+   * Where a listener's rejected promise lands (see the constructor): left at
+   * debug level like a listener that throws, never re-emitted as `error` —
+   * with no `error` listener that would throw, from a tick no one awaits.
+   */
+  [EventEmitter.captureRejectionSymbol](error, event) {
+    try {
+      const name = String(event);
+      this.#logger.debug(
+        `Event listener for '${name}' rejected: ${errorText(error)}`,
+        this.#fields({ event: name, error: errorText(error) }),
+      );
+    } catch {
+      // Reporting a listener's failure must not become a failure of its own.
+    }
+  }
+
   /**
    * Stop the run in progress: the migration currently executing is allowed to
    * finish (interrupting it mid-write is what leaves a database half-migrated),
@@ -324,10 +361,11 @@ class MigratorKit extends EventEmitter {
    * Structured fields for a log line. Passed as the logger's second argument
    * (first, for pino-style loggers) so a machine-readable sink gets
    * `{migration, direction, durationMs, …}` instead of having to parse the
-   * emoji-prefixed human string.
+   * emoji-prefixed human string. A run's lines carry its id and, when the
+   * caller named one, its queue job (`jobId`, `groupId`).
    */
   #fields(extra) {
-    return this.#runId ? { runId: this.#runId, ...extra } : { ...extra };
+    return this.#runId ? { runId: this.#runId, ...this.#runLog?.fields, ...extra } : { ...extra };
   }
 
   /** Record a finished wait for the lock — see {@link RECORD_LOCK_WAIT} */
@@ -485,6 +523,13 @@ class MigratorKit extends EventEmitter {
     // before any other run state exists: a `generateId` that throws or returns
     // a non-id rejects here, leaving nothing to unwind and no event emitted.
     this.#runId = this.#newId();
+    this.#runLog = createRunLog({
+      id: this.#runId,
+      job: options.job,
+      actor: pickActor(options),
+      sink: this.#logger,
+      emitter: this.#logEmitter(),
+    });
     // A second controller layered over the lock's own signal, so stop() and a
     // lost lock abort through the same path the run loops already watch.
     const stopper = new AbortController();
@@ -502,6 +547,7 @@ class MigratorKit extends EventEmitter {
     const recorder = new RunRecorder({
       info,
       runId: this.#runId,
+      job: this.#runLog.fields,
       telemetry: this.#telemetry,
       emit: (event, payload) => this.#emit(event, payload),
       logger: this.#logger,
@@ -544,9 +590,23 @@ class MigratorKit extends EventEmitter {
       recorder.finish(result, failure);
       this.#abort = undefined;
       this.#runId = undefined;
+      this.#runLog = undefined;
     }
   }
 
+  /**
+   * The kit's side of `migration:log` for migration loggers: `wanted` spares
+   * them the copy of a payload no one listens to. A payload names its own run
+   * (a late call's is not the run in flight), so it is delivered as it is.
+   */
+  #logEmitter() {
+    this.#logEmitterInstance ??= {
+      wanted: () => this.listenerCount(MIGRATION_LOG_EVENT) > 0,
+      emit: (payload) => this.#deliver(MIGRATION_LOG_EVENT, payload),
+    };
+    return this.#logEmitterInstance;
+  }
+
   /**
    * Attach partial results to an error's context. Copy-on-write: the error may
    * live on a shared abort signal (see #assertNotAborted) or already carry
@@ -781,8 +841,12 @@ class MigratorKit extends EventEmitter {
     const results = [];
     let doneCount = 0;
     let failure;
+    // The hooks around the whole run see the run's correlation, not one
+    // migration's: no migration name, no attempt.
+    const run = this.#runLog.info(direction);
+    const runContext = { ...context, run, logger: this.#runLog.logger(run) };
     try {
-      await this.#runHook(config.hooks?.beforeAll, 'beforeAll', [context]);
+      await this.#runHook(config.hooks?.beforeAll, 'beforeAll', [runContext]);
       for (const [index, name] of names.entries()) {
         // Between migrations is the only safe place to stop: the one in flight
         // has committed, and the next has not started.
@@ -808,7 +872,7 @@ class MigratorKit extends EventEmitter {
     // the diagnosis the caller needs, not the notification hook's own trouble.
     try {
       await this.#runHook(config.hooks?.afterAll, 'afterAll', [
-        context,
+        runContext,
         { success: succeeded, applied: doneCount, direction },
       ]);
     } catch (hookError) {
@@ -876,10 +940,15 @@ class MigratorKit extends EventEmitter {
     const config = this.#config;
     const logger = this.#logger;
     const batchField = batch !== undefined ? { batch } : {};
+    // What each attempt adds to the context — ctx.run and ctx.logger — made
+    // anew per attempt, so a retried transaction's body knows it is one.
+    const runLog = this.#runLog;
+    const attemptContext = (attempt) =>
+      runLog.attempt(direction, { migration: name, batch, attempt });
 
     await this.#runHook(config.hooks?.beforeEach, 'beforeEach', [
       name,
-      context,
+      { ...context, ...attemptContext(1) },
       { direction, index, total },
     ]);
     const loaded = await loadMigrationFile(this.#filepath(name), {
@@ -899,23 +968,28 @@ class MigratorKit extends EventEmitter {
     try {
       // The changelog write happens inside runMigration so that, under
       // useTransaction, it commits atomically with the migration itself.
-      const { duration } = await runMigration({
+      const { duration, attempts } = await runMigration({
         name,
         migration,
         direction,
         context,
         useTransaction,
         logger,
+        attemptContext,
         ...(config.timeoutMs ? { timeoutMs: config.timeoutMs } : {}),
         onSuccess: (elapsed, session) => onSuccess(migration, elapsed, session),
         ...(config.hooks ? { hooks: config.hooks } : {}),
       });
       this.#progress?.onStop('success');
+      span.set({ [ATTRIBUTES.MIGRATION_ATTEMPTS]: attempts });
+      // A transaction the driver retried ran the body again: say how often.
+      const retried = attempts > 1 ? { attempts } : {};
       this.#emit('migration:success', {
         migration: name,
         direction,
         ...batchField,
         durationMs: duration,
+        ...retried,
       });
       const label =
         migration.kind === 'background'
@@ -927,7 +1001,13 @@ class MigratorKit extends EventEmitter {
             : '↩ Reverted';
       logger.info(
         `${label} ${name}   [${duration}ms]`,
-        this.#fields({ migration: name, direction, ...batchField, durationMs: duration }),
+        this.#fields({
+          migration: name,
+          direction,
+          ...batchField,
+          durationMs: duration,
+          ...retried,
+        }),
       );
       if (migration.registered) {
         this.#emit('background:registered', { migration: name, ...migration.registered });
@@ -941,7 +1021,7 @@ class MigratorKit extends EventEmitter {
       await this.#runHook(config.hooks?.afterEach, 'afterEach', [
         name,
         duration,
-        context,
+        { ...context, ...attemptContext(attempts) },
         { direction, index, total },
       ]);
       return duration;
@@ -956,6 +1036,13 @@ class MigratorKit extends EventEmitter {
           ? error.context.durationMs
           : undefined;
       const durationField = durationMs !== undefined ? { durationMs } : {};
+      // And how many times the body ran, when it did.
+      const attempts =
+        error instanceof MigronautError && typeof error.context?.attempts === 'number'
+          ? error.context.attempts
+          : undefined;
+      if (attempts !== undefined) span.set({ [ATTRIBUTES.MIGRATION_ATTEMPTS]: attempts });
+      const retried = attempts > 1 ? { attempts } : {};
       // errorText, not the raw Error: a driver message can echo the
       // credentialed URI, and event subscribers (Sentry, JSON logs) would
       // ship it — the same redaction the log line below already gets.
@@ -964,6 +1051,7 @@ class MigratorKit extends EventEmitter {
         direction,
         ...batchField,
         ...durationField,
+        ...retried,
         error: errorText(error),
       });
       logger.error(
@@ -973,6 +1061,7 @@ class MigratorKit extends EventEmitter {
           direction,
           ...batchField,
           ...durationField,
+          ...retried,
           error: errorText(error),
         }),
       );
@@ -2280,7 +2369,7 @@ class MigratorKit extends EventEmitter {
   #backgroundHost() {
     return {
       store: this.#backgroundStore(),
-      deps: (owner) => this.#backgroundDeps(owner),
+      deps: (owner, options) => this.#backgroundDeps(owner, options),
       newId: () => this.#newId(),
       logger: this.#logger,
       emit: (event, payload) => this.#emit(event, payload),
@@ -2289,17 +2378,30 @@ class MigratorKit extends EventEmitter {
     };
   }
 
-  /** What background.js runs with — `owner` names a lane: its lease's owner, its events' runId */
-  #backgroundDeps(owner) {
+  /**
+   * What background.js runs with — `owner` names a lane: its lease's owner, its
+   * events' runId. `job` is the queue job working the lane, when there is one
+   * (`{ id }` for a background queue's lane, `{ id, groupId? }` for a run that
+   * drives it inline): it goes on the lane's log lines and `migration:log`
+   * events.
+   */
+  #backgroundDeps(owner, { job } = {}) {
     const config = this.#config;
     const db = this.#requireDb();
     const stamp = owner ? { runId: owner } : {};
+    const lineStamp = job ? { ...stamp, ...jobFields(job) } : stamp;
     return {
       db,
       client: this.#client,
       store: this.#backgroundStore(),
       logger: this.#logger,
-      fields: (extra) => ({ ...stamp, ...extra }),
+      // The lane's (or watcher's) run id, for ctx.background — `owner` itself
+      // is a function here and a string in the watcher's deps.
+      ...(owner ? { runId: owner } : {}),
+      // One counter per lane slice (or watcher): orders its migration:log events.
+      logs: backgroundLogs({ sink: this.#logger, emitter: this.#logEmitter() }),
+      ...(job ? { job } : {}),
+      fields: (extra) => ({ ...lineStamp, ...extra }),
       emit: (event, payload) => this.#emit(event, { ...stamp, ...payload }),
       lockFor: (name) =>
         new MigrationLock(db, config.lockCollection, config.lockTTLSeconds, {
@@ -2575,10 +2677,14 @@ class MigratorKit extends EventEmitter {
       this.#fields({ background: name, inline: true }),
     );
     await this.#backgroundReady(name, { lanes: true });
+    // The lanes work for the run's queue job: their lines and events name it,
+    // with its group — which a background queue's own lanes never have.
+    const job = this.#runLog?.job;
     const status = await drive(this.#backgroundHost(), name, {
       signal,
       concurrency: state.spec?.maxParallel ?? 1,
       inline: true,
+      ...(job ? { job } : {}),
     });
     if (status.status === 'blocked') {
       throw new BackgroundPendingError(
@@ -2637,13 +2743,20 @@ class MigratorKit extends EventEmitter {
   /**
    * One slice of one lane of a background migration: claim a partition and a
    * slot, work it until `sliceMs` (the spec's by default) runs out, release.
+   * `job: { id }` names the queue job working the lane, for its log lines.
    * @experimental
    */
-  async runBackgroundSlice(name, { signal, sliceMs } = {}) {
+  async runBackgroundSlice(name, { signal, sliceMs, job } = {}) {
     if (sliceMs !== undefined) assertSliceMs(sliceMs);
+    // A lane's job has no group: `{ id }` only.
+    assertJobValid(job, { groupId: false });
     await this.#backgroundReady(name, { lanes: true });
     const owner = this.#newId();
-    return runSlice(this.#backgroundDeps(owner), name, { signal, sliceMs, owner });
+    return runSlice(this.#backgroundDeps(owner, job ? { job } : {}), name, {
+      signal,
+      sliceMs,
+      owner,
+    });
   }
 
   /**

package/src/core/options.js

@@ -1,6 +1,8 @@
 const { ConfigInvalidError, MigrationInvalidNameError } = require('../errors/index.js');
 const { actorIssue } = require('../utils/actor.js');
+const { isPlainObject } = require('../utils/canonical.js');
 const { isCollectionName } = require('../utils/collection-name.js');
+const { jobRefIssue } = require('../utils/job-ref.js');
 
 /**
  * Validation of the options the kit's run methods take. Pure — no config, no
@@ -101,6 +103,20 @@ function assertActorValid(options) {
   }
 }
 
+/**
+ * Validate `job`: the queue job a run works for, `{ id, groupId? }` — bound
+ * into the run's correlation, so it must be small and exactly that shape.
+ */
+function assertJobValid(job, options) {
+  const issue = jobRefIssue(job, options);
+  if (issue) {
+    // For the error's context: the keys of what was given, not its values.
+    throw new ConfigInvalidError(issue, {
+      job: isPlainObject(job) ? Object.keys(job).join(', ') : typeof job,
+    });
+  }
+}
+
 /**
  * Validate `checksum`: the SHA-256 the caller expects the named file to have
  * — how a queue job says which version of the file it was planned with.
@@ -183,6 +199,7 @@ function assertUpOptions(filename, options) {
   assertChecksumValid(options.checksum, filename);
   assertBackgroundPendingValid(options.onBackgroundPending);
   assertActorValid(options);
+  assertJobValid(options.job);
 }
 
 /** `down(filename, options)` */
@@ -193,12 +210,14 @@ function assertDownOptions(filename, options) {
   assertToValid(options.to, filename, options);
   assertOrderedValid(options.ordered, filename);
   assertActorValid(options);
+  assertJobValid(options.job);
 }
 
 /** `redo(filename, options)` */
 function assertRedoOptions(filename, options) {
   assertFilename(filename);
   assertActorValid(options);
+  assertJobValid(options.job);
 }
 
 /** `dryRun(direction, filename, options)` */
@@ -270,6 +289,7 @@ function assertImportOptions(options) {
 
 module.exports = {
   assertActorValid,
+  assertJobValid,
   assertConvergeOptions,
   assertDownOptions,
   assertDryRunOptions,

package/src/core/run-recorder.js

@@ -17,6 +17,8 @@ const { ATTRIBUTES } = require('../utils/telemetry.js');
 class RunRecorder {
   #info;
   #runId;
+  /** The queue job the run works for — `{ jobId?, groupId? }` — for its span */
+  #job;
   #telemetry;
   #emit;
   #logger;
@@ -29,9 +31,10 @@ class RunRecorder {
   /** Set once the lock is held and the run span is open */
   #span;
 
-  constructor({ info, runId, telemetry, emit, logger, fields }) {
+  constructor({ info, runId, job = {}, telemetry, emit, logger, fields }) {
     this.#info = info;
     this.#runId = runId;
+    this.#job = job;
     this.#telemetry = telemetry;
     this.#emit = emit;
     this.#logger = logger;
@@ -69,6 +72,8 @@ class RunRecorder {
       [ATTRIBUTES.RUN_ID]: this.#runId,
       [ATTRIBUTES.RUN_COMMAND]: this.#info.command,
       [ATTRIBUTES.RUN_DIRECTION]: this.#info.direction,
+      [ATTRIBUTES.JOB_ID]: this.#job.jobId,
+      [ATTRIBUTES.JOB_GROUP_ID]: this.#job.groupId,
       [ATTRIBUTES.LOCK_ACQUIRE_MS]: this.#acquired?.acquireMs,
       [ATTRIBUTES.LOCK_SKIPPED]: this.#acquired?.skipped,
     };

package/src/core/runner.js

@@ -84,9 +84,15 @@ async function withTimeout(promise, timeoutMs, name, direction, onTimeout) {
  * body succeeded and only the (non-transactional) changelog write failed, the
  * error carries `context.phase = 'changelog-write'` and `onError` is not fired —
  * the migration itself did not fail.
+ *
+ * `attemptContext(attempt)` returns what the caller adds to the context of
+ * each attempt (`ctx.run`, `ctx.logger`): a retried transaction runs the body
+ * again, and that run gets a context of its own. Resolves to
+ * `{ duration, attempts }`; a failure carries `attempts` in its context.
  */
 async function runMigration(params) {
   const { name, migration, direction, context, useTransaction, hooks, onSuccess, logger } = params;
+  const { attemptContext } = params;
   const fn = direction === 'up' ? migration.up : migration.down;
   // A per-file `export const timeoutMs` overrides the global setting.
   const timeoutMs = migration.timeoutMs ?? params.timeoutMs;
@@ -102,7 +108,18 @@ async function runMigration(params) {
   const signal = context.signal
     ? AbortSignal.any([context.signal, timedOut.signal])
     : timedOut.signal;
-  let runtimeContext = { ...context, signal };
+  // A fresh context per attempt, not one mutated in place: a body from an
+  // earlier attempt that is still running (a timeout does not stop it) keeps
+  // the attempt it started with.
+  const contextOf = (session, attempt) => ({
+    ...context,
+    signal,
+    ...(session ? { session } : {}),
+    ...attemptContext?.(attempt),
+  });
+  let attempts = 0;
+  // The context the body last ran with — what onError gets.
+  let runtimeContext;
   const onTimeout = (timeoutError) => timedOut.abort(timeoutError);
   let duration = 0;
   // 'body' while the migration's own code runs; 'changelog' once it committed
@@ -114,25 +131,28 @@ async function runMigration(params) {
   try {
     if (useTransaction) {
       session = context.client.startSession();
-      runtimeContext = { ...runtimeContext, session };
       // withTransaction may run the body more than once when the driver retries
       // a transient failure, so duration is re-measured on each attempt. The
       // changelog write stays inside the transaction, so a failure there
       // aborts the body's writes too — 'body' phase is accurate throughout.
       await session.withTransaction(async () => {
         const attemptStart = Date.now();
+        attempts += 1;
+        runtimeContext = contextOf(session, attempts);
         await withTimeout(fn(runtimeContext), timeoutMs, name, direction, onTimeout);
         duration = Date.now() - attemptStart;
         await onSuccess?.(duration, session);
       });
     } else {
+      attempts += 1;
+      runtimeContext = contextOf(undefined, attempts);
       await withTimeout(fn(runtimeContext), timeoutMs, name, direction, onTimeout);
       duration = Date.now() - start;
       phase = 'changelog';
       await onSuccess?.(duration, undefined);
     }
 
-    return { duration };
+    return { duration, attempts };
   } catch (error) {
     const err = error instanceof Error ? error : new Error(String(error));
     // Failures deserve timing data as much as successes — a slow-then-failing
@@ -162,15 +182,21 @@ async function runMigration(params) {
     if (hooks?.onError) {
       // A throwing onError hook must not replace the real cause.
       try {
-        await hooks.onError(name, err, runtimeContext);
+        // A transaction that failed before its body ever ran (a session that
+        // would not start) still hands onError a whole context: a first
+        // attempt's, not counted as one.
+        await hooks.onError(name, err, runtimeContext ?? contextOf(session, 1));
       } catch (hookError) {
         const message = errorText(hookError);
         logger?.warn(`⚠ onError hook failed for ${name}: ${message}`);
       }
     }
 
+    // How many times the body ran (the driver retries a transient
+    // transaction error by running it again) — absent if it never started.
+    const attemptsField = attempts > 0 ? { attempts } : {};
     if (err instanceof MigrationTimeoutError) {
-      err.context = { durationMs: elapsed, ...err.context };
+      err.context = { durationMs: elapsed, ...attemptsField, ...err.context };
       throw err;
     }
     // A standalone deployment refusing the transaction is a topology problem,
@@ -179,7 +205,7 @@ async function runMigration(params) {
       throw new TransactionsUnsupportedError(
         `Cannot run ${name} in a transaction — this deployment is standalone. ` +
           'Set useTransaction: false, or run against a replica set / mongos.',
-        { name, direction, durationMs: elapsed, cause: err.message },
+        { name, direction, durationMs: elapsed, ...attemptsField, cause: err.message },
         { cause: err },
       );
     }
@@ -187,7 +213,7 @@ async function runMigration(params) {
       `Migration ${direction} failed: ${name}`,
       // The message is duplicated into context because that is what survives
       // JSON serialization; `cause` keeps the real Error (and its stack).
-      { name, direction, durationMs: elapsed, cause: err.message },
+      { name, direction, durationMs: elapsed, ...attemptsField, cause: err.message },
       { cause: err },
     );
   } finally {

package/src/utils/job-ref.js

@@ -0,0 +1,44 @@
+const { isPlainObject } = require('./canonical.js');
+const { MAX_ID_LENGTH } = require('./id.js');
+
+/**
+ * The queue job a run works for: `job: { id, groupId? }` on `up`, `down` and
+ * `redo` (a background lane's slice takes `{ id }`). It is bound into
+ * `ctx.run`, the run's log lines and every `migration:log` event, so what a
+ * migration logs can be joined to the job a dashboard shows — nothing is
+ * stored. The one definition of its limits, shared by the kit's options and
+ * the queue adapter, which must never pass what the kit refuses.
+ *
+ * `id` allows a custom BullMQ job id (they can be long); `groupId` is minted
+ * by the kit's own id generator, so it has that generator's bound.
+ */
+const JOB_REF_LIMITS = Object.freeze({ id: 1024, groupId: MAX_ID_LENGTH });
+
+/**
+ * The problem with a job reference, or null when it is absent or valid.
+ * `groupId: false` refuses that key (a lane has no group).
+ */
+function jobRefIssue(job, { groupId = true } = {}) {
+  if (job === undefined) return null;
+  if (!isPlainObject(job)) return 'job must be an object: { id, groupId? }';
+  for (const key of Object.keys(job)) {
+    // Own keys only: `constructor` or `toString` must not pass for a limit.
+    if (!Object.hasOwn(JOB_REF_LIMITS, key) || (key === 'groupId' && !groupId)) {
+      return `job.${key} is not an option`;
+    }
+    const max = JOB_REF_LIMITS[key];
+    const value = job[key];
+    if (typeof value !== 'string' || value.length === 0 || value.length > max) {
+      return `job.${key} must be a non-empty string of at most ${max} characters`;
+    }
+  }
+  return job.id === undefined ? 'job.id is required' : null;
+}
+
+/** What a valid job reference adds to a run's correlation: `{ jobId, groupId? }` */
+function jobFields(job) {
+  if (job === undefined) return {};
+  return { jobId: job.id, ...(job.groupId !== undefined ? { groupId: job.groupId } : {}) };
+}
+
+module.exports = { JOB_REF_LIMITS, jobFields, jobRefIssue };