@nest-batch/core 0.2.0

package/src/execution/job-launcher.ts

@@ -0,0 +1,132 @@
+import { randomUUID } from 'crypto';
+
+import { Inject, Injectable, Optional, forwardRef } from '@nestjs/common';
+
+import { JobNotFoundError, JobExecutionAlreadyRunningError } from '../core/errors';
+import { JobRepository, type JobParameters, type JobExecution } from '../core/repository';
+import { JobRegistry } from '../registry/job-registry';
+
+import {
+  EXECUTION_STRATEGY,
+  type IExecutionStrategy,
+} from './execution-strategy';
+import { JobExecutor } from './job-executor';
+import { canonicalJobKey } from './job-key';
+
+import type { JobDefinition } from '../core/ir';
+
+
+
+/**
+ * JobLauncher — public entry point for starting a new JobExecution.
+ *
+ * Flow (pre-strategy, kept unchanged for backwards compat):
+ *   1. Look up the `JobDefinition` from the registry. Missing → `JobNotFoundError`.
+ *   2. Canonicalize `params` into a stable `jobKey` hash. Object key order,
+ *      `null/undefined` omission, `Date → ISO` are all normalized so that
+ *      semantically-identical params yield the same key.
+ *   3. `createExecutionAtomic(jobId, jobKey, params)` — idempotent
+ *      instance get-or-create + `SELECT ... FOR UPDATE SKIP LOCKED` to
+ *      serialize concurrent launches + running-execution check + insert,
+ *      all in a single transaction. Throws
+ *      `JobExecutionAlreadyRunningError` if another launch is in flight
+ *      or an execution is already STARTING/STARTED for the same instance.
+ *   4. Delegate to the injected `IExecutionStrategy` (default:
+ *      `InProcessExecutionStrategy`, which wraps `JobExecutor.execute`).
+ *      The lock is released when the createExecutionAtomic transaction
+ *      commits; the executor itself runs outside the lock (it can be
+ *      long-running).
+ *
+ * `allowDuplicateInstances: true` bypasses step 2's dedup by appending a
+ * fresh UUID nonce to the canonical key on every call, forcing a new
+ * `JobInstance` each time.
+ *
+ * Polymorphic strategy (Task 11):
+ *   The launcher is a thin facade — it owns the registry lookup, the
+ *   canonical `jobKey` derivation, the atomic instance + concurrency
+ *   lock, and the post-strategy `JobExecution` re-resolution. The
+ *   actual *how* of running the job (in-process vs. transport) lives
+ *   behind the `EXECUTION_STRATEGY` token. Sibling packages (e.g.
+ *   `@nest-batch/bullmq`) override the token with a transport
+ *   strategy that enqueues work; the launcher never learns about the
+ *   transport.
+ *
+ *   When no strategy is bound (e.g. direct manual construction in
+ *   unit tests), the launcher falls back to the original direct
+ *   `JobExecutor.execute` path. This keeps the legacy
+ *   `tests/execution/job-launcher.test.ts` working without changes.
+ */
+@Injectable()
+export class JobLauncher {
+  constructor(
+    private readonly registry: JobRegistry,
+    private readonly repository: JobRepository,
+    @Inject(forwardRef(() => JobExecutor))
+    private readonly jobExecutor: JobExecutor,
+    @Optional()
+    @Inject(EXECUTION_STRATEGY)
+    private readonly strategy?: IExecutionStrategy,
+  ) {}
+
+  /**
+   * Launch a new job execution. Returns the final `JobExecution` after it
+   * has finished (status = COMPLETED | FAILED) — or, for transport
+   * strategies that return `{ kind: 'enqueued' }`, the latest persisted
+   * `JobExecution` (still in `STARTING` / `STARTED`, since the executor
+   * has not run on the launcher process).
+   *
+   * Throws `JobNotFoundError` if `jobId` is not registered.
+   * Throws `JobExecutionAlreadyRunningError` if a previous launch of the
+   * same `jobName + jobKey` is still in flight.
+   */
+  async launch(jobId: string, params: JobParameters = {}): Promise<JobExecution> {
+    const jobDef = this.registry.get(jobId); // throws JobNotFoundError on miss
+    const canonical = canonicalJobKey(params);
+    const jobKey = jobDef.allowDuplicateInstances ? `${canonical}::${randomUUID()}` : canonical;
+
+    // Atomic get-or-create + lock + check + insert. The repository's
+    // implementation uses INSERT ... ON CONFLICT DO NOTHING +
+    // FOR UPDATE SKIP LOCKED to serialize concurrent launches.
+    const execution = await this.repository.createExecutionAtomic(jobId, jobKey, params);
+
+    // No strategy bound → fall back to the legacy direct-execute path.
+    // This branch preserves `tests/execution/job-launcher.test.ts` (which
+    // wires the launcher by hand, no Nest module) and any other
+    // direct-construction consumer.
+    if (this.strategy === undefined) {
+      return this.jobExecutor.execute(execution, jobDef);
+    }
+
+    // The strategy's `LaunchResult` is intentionally discarded: the
+    // public `JobLauncher.launch` contract always returns a
+    // `JobExecution` (re-resolved from the repository below), and
+    // `queueJobId` is for the strategy's own bookkeeping only.
+    await this.strategy.launch(jobDef, params, {
+      executionId: execution.id,
+      jobExecutionId: execution.id,
+    });
+
+    // For both `completed` and `enqueued` the public `JobLauncher.launch`
+    // contract returns a `JobExecution`. Re-resolve the latest persisted
+    // row so the caller sees the executor's writes (status, endTime,
+    // exitCode) without us hand-merging patches here. If the lookup
+    // somehow returns null (e.g. a custom repository that drops rows),
+    // fall back to the execution the launcher pre-created.
+    const latest = await this.repository.getJobExecution(execution.id);
+    return latest ?? execution;
+  }
+
+  /**
+   * Resume an existing `JobExecution` (used by the restart path).
+   * For this MVP it just delegates to the executor — the launcher does
+   * not yet gate on restartable / concurrency / FAILED-prev-exists rules.
+   *
+   * Note: `run` bypasses the strategy on purpose. Restart is a
+   * recovery path on the in-process execution model; transport
+   * strategies that need their own resume semantics can override
+   * this method on a subclass or via a future token.
+   */
+  async run(execution: JobExecution, jobDef: JobDefinition): Promise<JobExecution> {
+    return this.jobExecutor.execute(execution, jobDef);
+  }
+}

package/src/execution/job-operator.ts

@@ -0,0 +1,127 @@
+import { randomUUID } from 'node:crypto';
+
+import { Injectable } from '@nestjs/common';
+
+import { InvalidJobOperationError } from '../core/errors';
+import {
+  JobExecution,
+  JobExecutionDetails,
+  JobExecutionFilter,
+  JobInstance,
+  JobInstanceFilter,
+  JobParameters,
+  JobRepository,
+} from '../core/repository';
+import type { JobDefinition } from '../core/ir';
+import { JobStatus } from '../core/status';
+import { JobRegistry } from '../registry/job-registry';
+
+import { JobExplorer } from './job-explorer';
+import { JobLauncher } from './job-launcher';
+
+@Injectable()
+export class JobOperator {
+  constructor(
+    private readonly explorer: JobExplorer,
+    private readonly registry: JobRegistry,
+    private readonly repository: JobRepository,
+    private readonly launcher: JobLauncher,
+  ) {}
+
+  listJobs(): JobDefinition[] {
+    return this.explorer.listJobs();
+  }
+
+  listJobInstances(filter: JobInstanceFilter = {}): Promise<JobInstance[]> {
+    return this.explorer.listJobInstances(filter);
+  }
+
+  listJobExecutions(filter: JobExecutionFilter = {}): Promise<JobExecution[]> {
+    return this.explorer.listJobExecutions(filter);
+  }
+
+  getJobExecutionDetails(executionId: string): Promise<JobExecutionDetails> {
+    return this.explorer.getJobExecutionDetails(executionId);
+  }
+
+  async stop(executionId: string): Promise<JobExecutionDetails> {
+    const details = await this.explorer.getJobExecutionDetails(executionId);
+    const status = details.jobExecution.status;
+
+    if (status === JobStatus.STOPPED) {
+      return details;
+    }
+    if (!this.isActive(status)) {
+      throw new InvalidJobOperationError('stop', `Cannot stop execution in ${status} state`, {
+        executionId,
+        status,
+      });
+    }
+
+    await this.repository.updateJobExecution(executionId, {
+      status: JobStatus.STOPPED,
+      endTime: new Date(),
+      exitCode: 'STOPPED',
+      exitMessage: 'Stopped by JobOperator',
+    });
+
+    return this.explorer.getJobExecutionDetails(executionId);
+  }
+
+  async abandon(executionId: string): Promise<JobExecutionDetails> {
+    const details = await this.explorer.getJobExecutionDetails(executionId);
+    const status = details.jobExecution.status;
+
+    if (status === JobStatus.ABANDONED) {
+      return details;
+    }
+    if (this.isActive(status) || status === JobStatus.COMPLETED) {
+      throw new InvalidJobOperationError(
+        'abandon',
+        `Cannot abandon execution in ${status} state`,
+        { executionId, status },
+      );
+    }
+
+    await this.repository.updateJobExecution(executionId, {
+      status: JobStatus.ABANDONED,
+      endTime: details.jobExecution.endTime ?? new Date(),
+      exitCode: 'ABANDONED',
+      exitMessage: 'Abandoned by JobOperator',
+    });
+
+    return this.explorer.getJobExecutionDetails(executionId);
+  }
+
+  async restart(executionId: string): Promise<JobExecutionDetails> {
+    const details = await this.explorer.getJobExecutionDetails(executionId);
+    const status = details.jobExecution.status;
+
+    if (status !== JobStatus.FAILED && status !== JobStatus.STOPPED) {
+      throw new InvalidJobOperationError(
+        'restart',
+        `Cannot restart execution in ${status} state`,
+        { executionId, status },
+      );
+    }
+
+    const jobDef = this.registry.get(details.jobInstance.jobName);
+    const execution = await this.launcher.run(details.jobExecution, jobDef);
+    return this.explorer.getJobExecutionDetails(execution.id);
+  }
+
+  startNextInstance(jobId: string, params: JobParameters = {}): Promise<JobExecution> {
+    return this.launcher.launch(jobId, {
+      ...params,
+      _nestBatchRunId: randomUUID(),
+    });
+  }
+
+  private isActive(status: JobStatus): boolean {
+    return (
+      status === JobStatus.STARTING ||
+      status === JobStatus.STARTED ||
+      status === JobStatus.STOPPING
+    );
+  }
+}

package/src/execution/listener-invoker.ts

@@ -0,0 +1,389 @@
+/**
+ * ListenerInvoker — orchestrates lifecycle listeners around step / chunk / job /
+ * item / skip execution.
+ *
+ * Supports the 7 listener kinds declared in `ListenerKind` (job / step / chunk /
+ * item-read / item-process / item-write / skip) with proper failure policy:
+ *
+ *   - default                → listener throw propagates
+ *   - `nonCritical: true`    → log + continue with the next listener
+ *
+ * Two resolver-map shapes are supported:
+ *
+ *   1. Legacy (Task 17) — `Map<string, ListenerResolver>` keyed by
+ *      `${phase}-${kind}:${name}` (e.g. `before-step:MyListener`). The
+ *      convenience methods `invokeBeforeStep / invokeAfterStep /
+ *      invokeOnErrorStep` operate on this shape and remain in place for
+ *      backward compatibility with the Wave-3 step executor.
+ *
+ *   2. Current (Task 20) — `Map<string, ListenerEntry>` keyed by
+ *      `${phase}:${kind}:${name}` (e.g. `before:step:MyListener`,
+ *      `on-skip:read:MySkipListener`). This is the shape consumed by
+ *      `invokeBefore / invokeAfter / invokeOnError / invokeOnSkipRead /
+ *      invokeOnSkipProcess / invokeOnSkipWrite` and is the source of truth for
+ *      all 7 listener kinds going forward.
+ *
+ * Registration order is preserved (Map iteration is insertion-ordered in JS).
+ */
+import { Injectable, Logger } from '@nestjs/common';
+import type { ExecutionContext } from '../core/repository';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * Listener function — signature is determined by the listener's kind/phase.
+ *
+ * Typed as `any[]` rather than `unknown[]` so listeners can be authored with
+ * the narrower, kind-specific signatures (e.g. `(ctx) => void`,
+ * `(item, ctx) => void`, `(err, item) => void`) without TypeScript rejecting
+ * the assignment to `ListenerEntry.fn`. The runtime contract is enforced by
+ * the invoker's kind-aware `buildCallArgs`, not by the type system.
+ */
+export type ListenerFn = (...args: any[]) => any;
+
+/**
+ * Resolver-map entry used by the current (Task 20) API.
+ *
+ * - `fn`           — the actual listener function to invoke
+ * - `nonCritical`  — when true, failures from this listener are logged and
+ *                    suppressed; otherwise the failure propagates out of the
+ *                    `invoke*` call and aborts the surrounding executor.
+ */
+export interface ListenerEntry {
+  fn: ListenerFn;
+  nonCritical?: boolean;
+}
+
+/** Resolver map consumed by the current (Task 20) `invoke*` methods. */
+export type ResolverMap = Map<string, ListenerEntry>;
+
+// ---------------------------------------------------------------------------
+// Legacy types (Task 17 backward compatibility)
+// ---------------------------------------------------------------------------
+
+/** Phase prefix constants used by the legacy convenience methods. */
+export const LISTENER_PHASE_PREFIX = {
+  BeforeStep: 'before-step:',
+  AfterStep: 'after-step:',
+  OnStepError: 'on-step-error:',
+} as const;
+
+/** Legacy resolver function type — bare callable, no per-entry metadata. */
+export type ListenerResolver = (...args: unknown[]) => unknown | Promise<unknown>;
+
+export interface StepListenerContext extends ListenerContext {
+  jobExecutionId: string;
+  stepExecutionId: string;
+  getExecutionContext?: () => Promise<ExecutionContext>;
+  saveExecutionContext?: (ctx: ExecutionContext) => Promise<void>;
+}
+
+export interface StepListenerResult {
+  status: string;
+  exitCode?: string;
+  exitMessage?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Current (Task 20) phase / kind constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Phase segment for the current key format `${phase}:${kind}:${name}`.
+ *
+ * - `before`     — `invokeBefore`
+ * - `after`      — `invokeAfter`
+ * - `on-error`   — `invokeOnError` (job / step / chunk)
+ * - `on-skip`    — `invokeOnSkipRead / Process / Write` (the trailing kind
+ *                  segment is one of `read` / `process` / `write`)
+ */
+export const LISTENER_PHASE = {
+  Before: 'before',
+  After: 'after',
+  OnError: 'on-error',
+  OnSkip: 'on-skip',
+} as const;
+
+/** Phase kinds that share the standard `${phase}:${kind}:${name}` shape. */
+export type LifecyclePhaseKind =
+  | 'job'
+  | 'step'
+  | 'chunk'
+  | 'item-read'
+  | 'item-process'
+  | 'item-write';
+
+/** Phase kinds accepted by `invokeOnError` (subset of the lifecycle kinds). */
+export type OnErrorKind = 'job' | 'step' | 'chunk';
+
+/**
+ * Sub-kinds for the `on-skip` phase. The resolver key looks like
+ * `on-skip:${SkipSubKind}:${name}` — for example `on-skip:read:MySkipListener`.
+ */
+export type SkipSubKind = 'read' | 'process' | 'write';
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+@Injectable()
+export class ListenerInvoker {
+  private readonly logger = new Logger(ListenerInvoker.name);
+
+  // -------------------------------------------------------------------------
+  // Current (Task 20) API — supports all 7 listener kinds with failure policy
+  // -------------------------------------------------------------------------
+
+  /**
+   * Invoke every `before:<kind>:<name>` resolver, in registration order.
+   *
+   * Listener signature depends on `<kind>`:
+   *   - `job` / `chunk`   — `fn(ctx)`
+   *   - `step`            — `fn(ctx, result)` (the optional `args` is the result)
+   *   - `item-read` / `item-process` / `item-write` — `fn(item, ctx)` (the
+   *     optional `args` is the item, placed in the first position by
+   *     convention)
+   */
+  async invokeBefore(
+    resolvers: ResolverMap,
+    kind: LifecyclePhaseKind,
+    ctx: ListenerContext,
+    args?: unknown,
+  ): Promise<void> {
+    const callArgs = this.buildCallArgs(kind, ctx, args);
+    await this.invokeMatching(resolvers, `${LISTENER_PHASE.Before}:${kind}:`, callArgs);
+  }
+
+  /**
+   * Invoke every `after:<kind>:<name>` resolver, in registration order.
+   * Same signature rules as `invokeBefore`.
+   */
+  async invokeAfter(
+    resolvers: ResolverMap,
+    kind: LifecyclePhaseKind,
+    ctx: ListenerContext,
+    args?: unknown,
+  ): Promise<void> {
+    const callArgs = this.buildCallArgs(kind, ctx, args);
+    await this.invokeMatching(resolvers, `${LISTENER_PHASE.After}:${kind}:`, callArgs);
+  }
+
+  /**
+   * Invoke every `on-error:<kind>:<name>` resolver, in registration order.
+   * Listener signature is `fn(ctx, err)`.
+   */
+  async invokeOnError(
+    resolvers: ResolverMap,
+    kind: OnErrorKind,
+    ctx: ListenerContext,
+    err: unknown,
+  ): Promise<void> {
+    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnError}:${kind}:`, [ctx, err]);
+  }
+
+  /** Invoke every `on-skip:read:<name>` resolver. Listener signature: `fn(err, item)`. */
+  async invokeOnSkipRead(
+    resolvers: ResolverMap,
+    err: unknown,
+    item: unknown,
+  ): Promise<void> {
+    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:read:`, [err, item]);
+  }
+
+  /** Invoke every `on-skip:process:<name>` resolver. Listener signature: `fn(item, err)`. */
+  async invokeOnSkipProcess(
+    resolvers: ResolverMap,
+    item: unknown,
+    err: unknown,
+  ): Promise<void> {
+    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:process:`, [item, err]);
+  }
+
+  /** Invoke every `on-skip:write:<name>` resolver. Listener signature: `fn(items, err)`. */
+  async invokeOnSkipWrite(
+    resolvers: ResolverMap,
+    items: unknown[],
+    err: unknown,
+  ): Promise<void> {
+    await this.invokeMatching(resolvers, `${LISTENER_PHASE.OnSkip}:write:`, [items, err]);
+  }
+
+  // -------------------------------------------------------------------------
+  // Legacy (Task 17) convenience methods — preserved for backward compat.
+  // They now delegate to the current (Task 20) API by converting the legacy
+  // `Map<string, ListenerResolver>` shape into a `ResolverMap` and routing
+  // through the shared `invokeMatching` internal path. One source of truth
+  // for listener dispatch, two public surfaces.
+  // -------------------------------------------------------------------------
+
+  /**
+   * Invoke all `before-step:*` resolvers in Map insertion order. Operates on
+   * the legacy `Map<string, ListenerResolver>` shape; the current
+   * `invokeBefore(resolvers, 'step', ...)` should be preferred for new code.
+   *
+   * Implementation: convert the legacy `before-step:*` entries into the new
+   * `before:step:*` shape and delegate to `invokeBefore` so the dispatch /
+   * `nonCritical` policy is shared with the rest of the invoker.
+   */
+  async invokeBeforeStep(
+    resolvers: Map<string, ListenerResolver>,
+    ctx: StepListenerContext,
+  ): Promise<void> {
+    const newResolvers = this.convertLegacyResolvers(
+      resolvers,
+      LISTENER_PHASE_PREFIX.BeforeStep,
+      LISTENER_PHASE.Before,
+    );
+    await this.invokeBefore(newResolvers, 'step', ctx);
+  }
+
+  /**
+   * Invoke all `after-step:*` resolvers, receiving the step result as the
+   * second argument. Legacy shape; see `invokeAfter(resolvers, 'step', ...)`
+   * for the current API.
+   */
+  async invokeAfterStep(
+    resolvers: Map<string, ListenerResolver>,
+    ctx: StepListenerContext,
+    result: StepListenerResult,
+  ): Promise<void> {
+    const newResolvers = this.convertLegacyResolvers(
+      resolvers,
+      LISTENER_PHASE_PREFIX.AfterStep,
+      LISTENER_PHASE.After,
+    );
+    await this.invokeAfter(newResolvers, 'step', ctx, result);
+  }
+
+  /**
+   * Invoke all `on-step-error:*` resolvers, receiving the thrown error as the
+   * second argument. Legacy shape; see `invokeOnError(resolvers, 'step', ...)`
+   * for the current API.
+   */
+  async invokeOnErrorStep(
+    resolvers: Map<string, ListenerResolver>,
+    ctx: StepListenerContext,
+    err: unknown,
+  ): Promise<void> {
+    const newResolvers = this.convertLegacyResolvers(
+      resolvers,
+      LISTENER_PHASE_PREFIX.OnStepError,
+      LISTENER_PHASE.OnError,
+    );
+    await this.invokeOnError(newResolvers, 'step', ctx, err);
+  }
+
+  /**
+   * Translate legacy `before-step:` / `after-step:` / `on-step-error:` keys
+   * into the new `${phase}:step:${name}` shape. Only entries whose key
+   * starts with the given legacy prefix are forwarded; everything else is
+   * silently dropped (matches the prefix-filter semantics of the original
+   * legacy loops).
+   *
+   * `nonCritical` is not representable in the legacy `ListenerResolver`
+   * shape (bare function values), so the converted entries always carry
+   * `nonCritical: undefined` — i.e. critical propagation. This preserves
+   * the legacy contract exactly.
+   */
+  private convertLegacyResolvers(
+    legacy: Map<string, ListenerResolver>,
+    legacyPrefix: string,
+    newPhase: string,
+  ): ResolverMap {
+    const out: ResolverMap = new Map();
+    for (const [key, fn] of legacy.entries()) {
+      if (!key.startsWith(legacyPrefix)) continue;
+      const newKey = `${newPhase}:step:${key.slice(legacyPrefix.length)}`;
+      out.set(newKey, { fn: fn as ListenerFn });
+    }
+    return out;
+  }
+
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+
+  /**
+   * Compute the positional argument list to forward to a before/after
+   * listener, based on the listener's kind.
+   *
+   * - `job` / `chunk`   → `[ctx]`
+   * - `step`            → `[ctx, args]`   (args is the result)
+   * - `item-read` /
+   *   `item-process` /
+   *   `item-write`      → `[args, ctx]`   (args is the item, leading position)
+   */
+  private buildCallArgs(
+    kind: LifecyclePhaseKind,
+    ctx: ListenerContext,
+    args: unknown,
+  ): unknown[] {
+    switch (kind) {
+      case 'item-read':
+      case 'item-process':
+      case 'item-write':
+        return [args, ctx];
+      case 'step':
+        return [ctx, args];
+      case 'job':
+      case 'chunk':
+        return [ctx];
+      default: {
+        // exhaustive guard
+        const _exhaustive: never = kind;
+        void _exhaustive;
+        return [ctx];
+      }
+    }
+  }
+
+  /**
+   * Iterate the resolver map in insertion order, invoke every entry whose key
+   * starts with `prefix`, and apply the failure policy:
+   *
+   *   - if the entry is missing / the function rejects:
+   *       - `nonCritical: true`  → log a warning, swallow, continue
+   *       - otherwise            → re-throw, aborting the surrounding executor
+   */
+  private async invokeMatching(
+    resolvers: ResolverMap,
+    prefix: string,
+    args: unknown[],
+  ): Promise<void> {
+    for (const [key, entry] of resolvers.entries()) {
+      if (!key.startsWith(prefix)) continue;
+      try {
+        await entry.fn(...args);
+      } catch (err) {
+        if (entry.nonCritical) {
+          this.logger.warn(
+            `[ListenerInvoker] non-critical listener "${key}" failed: ${formatError(err)}`,
+          );
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Shared listener-context payload. All fields are optional because the
+ *  caller (executor) may not always have a stepExecutionId at hand (e.g. for
+ *  job-level listeners). */
+export interface ListenerContext {
+  jobExecutionId: string;
+  stepExecutionId?: string;
+  stepName?: string;
+  /** Arbitrary, executor-supplied metadata (transaction context, etc.). */
+  [extra: string]: unknown;
+}
+
+function formatError(err: unknown): string {
+  return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+}