@alexify/migronaut 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -3,6 +3,89 @@
 All notable changes to this project will be documented in this file.
 Release headings carry the publish date (`## vX.Y.Z — YYYY-MM-DD`).
 
+## v2.4.0 — 2026-10-07
+
+Migration logs for the application's users. Additive: a migration that never touches the new
+context fields, and a kit with no `migration:log` listener, behave as before. Everything new is
+experimental — its shape may still change in a minor release (named here).
+
+### Added
+
+- **`ctx.logger` in every migration** — the kit's logger with the run's correlation bound into the
+  fields of every line: `runId`, `migration`, `direction`, `batch`, `attempt`, and `jobId` /
+  `groupId` when a queue job runs it. Pino's `(fields, msg)` order is accepted too.
+- **`ctx.run`** — that correlation as a frozen object: `{ id, direction, migration?, batch?,
+  attempt?, jobId?, groupId?, requestedBy?, reason? }`. `attempt` is 2 or more when the driver
+  retried the transaction and the body runs again (each attempt gets a context of its own).
+- **The `migration:log` event** — a `ctx.logger` call whose fields hold `userland: true` is also
+  emitted, for the application to store and show its users; calls without the marker emit
+  nothing. The payload is `{ kind, runId, …correlation, level, msg, data, at, seq, truncated? }`:
+  `data` a bounded, redacted copy of the fields (8 levels, 1000 entries, 4096-character strings;
+  an `Error` as `{ name, message, code?, codeName? }` with the values a server error quotes masked,
+  as in `msg`; BSON values and binary data up to 4096 bytes kept as they are),
+  `seq` increasing within a run, `at` a `Date` (TTL-ready). It fires whatever the logger's level,
+  and with `logger: null`. Migronaut stores none of it — the
+  [Migration Logs](https://migronaut.vercel.app/guide/migration-logs) guide has the recipe.
+- **Hooks get it too** — `beforeAll`/`afterAll` the run's logger and `ctx.run` (no migration, no
+  attempt), `beforeEach`/`afterEach`/`onError` the migration's.
+- **`job: { id, groupId? }` on `up`, `down` and `redo`** — the queue job a run works for, bound into
+  `ctx.run`, its lines (the kit's own included) and its events; and `job: { id }` on
+  `runBackgroundSlice`.
+- **Queue adapter** — the processor passes each job's id and group to its run, and writes the
+  migration's `userland: true` lines into the job's log as one-line `✎ …` rows (matched by job and
+  run id, so a timed-out body never writes into the next job's log — nor into a later run of the
+  same job). A background lane does the same for its slice, into the lane job's log. The new
+  `userlandLogRows` option (`createMigrationQueue`, both processors; default 1000) caps the rows one
+  job's log takes — the rest are counted in one closing row.
+- **Background migrations** — `ctx.logger` is bound to `ctx.background`, which gains the lane's
+  `runId`, its `jobId` (and, for a lane an `up` drives with `backgroundInline`, the run's job and
+  `groupId` — its lines land in that migration job's log) and the transaction `attempt`; a
+  `userland: true` call emits `migration:log` with `kind: 'background'`. A dry run marks its lines
+  `dryRun: true` and emits nothing.
+- **Retried transactions, visible** — when the driver retried a migration's transaction and its
+  body ran again, `migration:success` / `migration:error` and the kit's `✔ Applied` / `✖ Error`
+  lines carry `attempts`, a failure's context too, and the `migronaut.migration` span always has
+  `migronaut.migration.attempts`. A run that names a `job` puts `migronaut.job.id` /
+  `migronaut.job.group_id` on its `migronaut.run` span.
+- **A `ctx.logger` call that is dropped** (a field whose getter throws) **or cut to the event's
+  bounds** leaves one debug line per run — never one per call.
+- **Types** — `MigrationRunInfo`, `JobRef`, `MigrationLogEvent` (`OrdinaryMigrationLogEvent |
+  BackgroundMigrationLogEvent`), `MigrationLogEventBase`, `MigrationLogLevel`,
+  `BackgroundRunInfo`, `MigrationLogger` (`ctx.logger`: `(msg, fields?)`, pino's `(fields, msg?)`
+  and an `Error` as the message — any `MigronautLogger` or pino instance is one); `logger?` and
+  `run?` on `MigrationContext` (optional, so a context built by hand still type-checks);
+  `attempts?` on `MigrationEvent`.
+
+### Changed
+
+- `ctx.background` of a background migration is now frozen, and typed as `BackgroundRunInfo`.
+  **A type change on an experimental API:** its `generation` is now `number | undefined` (as it
+  always was at runtime for the live drift watcher), so strict TypeScript that reads it as a
+  `number` needs a check; `ctx.logger` is typed `MigrationLogger`, which every `MigronautLogger`
+  still fits.
+- The kit's log lines of a run that names a `job` carry `jobId` / `groupId`.
+
+### Fixed
+
+- **An `async` event listener that rejects no longer crashes the process.** The kit is an
+  `EventEmitter` with `captureRejections`: a listener's rejected promise is logged at debug level,
+  like a listener that throws, instead of surfacing as an `unhandledRejection`.
+
+### Documentation
+
+- **How It Works** — a new guide page with architecture diagrams: the engine and its entry points,
+  the life of a run, the lock, where the state lives, which tool fits which change, background
+  migrations and what a run reports.
+- **Diagrams across the guides** — Core Concepts (a migration's states, batches, a run), Transactions,
+  Declared Collections (a converge run), Document Versioning (the contract, optimistic concurrency,
+  the revision invariant, expand → background → contract), Background Migrations (statuses, one
+  lane's batches, passes, drift), the queue adapter (the line, a failure, background jobs) and
+  Migration Logs. They are Mermaid, drawn in the browser by a small theme component; `mermaid` is a
+  docs-only devDependency, loaded only by a page that has a diagram.
+- **The home page** shows what 2.1 – 2.4 added — declared collections, Atlas Search, document
+  versioning, background migrations, OpenTelemetry, migration logs — with a diagram of how the parts
+  fit together.
+
 ## v2.3.0 — 2026-10-06
 
 Document versioning and background migrations. Additive: nothing changes for a project that

package/README.md

@@ -66,6 +66,10 @@ change before it touches your database.
 - **Zero config files required** — drive everything from env vars if you prefer.
 - **Pino-friendly logging** — the `logger` option is pino-compatible; pass a pino instance directly
   and migronaut logs through it (with a `component: 'migronaut'` child binding).
+- **Migration logs for your users (experimental)** — every migration gets `ctx.logger`, bound to its
+  run (run id, migration, attempt, queue job), and `ctx.run`; a line marked `userland: true` is also
+  emitted as `migration:log` for your service to store and show — migronaut stores none of it
+  ([guide](https://migronaut.vercel.app/guide/migration-logs)).
 - **Your id format** — run ids and queue group ids are random UUIDs by default; pass
   `generateId: ulid` (or cuid2, nanoid, UUIDv7 — any `() => string`) and every id migronaut mints
   comes from your generator.
@@ -189,7 +193,7 @@ Full docs, guides, and the API reference live at
 - [Core Concepts](https://migronaut.vercel.app/guide/concepts) — migrations, batches, the changelog, locking
 - [Getting Started](https://migronaut.vercel.app/guide/getting-started) & [Tutorial](https://migronaut.vercel.app/guide/tutorial)
 - [Configuration](https://migronaut.vercel.app/guide/configuration) · [Writing Migrations](https://migronaut.vercel.app/guide/writing-migrations) · [Transactions](https://migronaut.vercel.app/guide/transactions) · [Hooks](https://migronaut.vercel.app/guide/hooks)
-- [Programmatic API](https://migronaut.vercel.app/guide/api) · [Migrations as a Queue (BullMQ)](https://migronaut.vercel.app/guide/bullmq) · [OpenTelemetry](https://migronaut.vercel.app/guide/opentelemetry) · [CI/CD](https://migronaut.vercel.app/guide/ci-cd) · [Troubleshooting](https://migronaut.vercel.app/guide/troubleshooting)
+- [Programmatic API](https://migronaut.vercel.app/guide/api) · [Migrations as a Queue (BullMQ)](https://migronaut.vercel.app/guide/bullmq) · [Migration Logs](https://migronaut.vercel.app/guide/migration-logs) · [OpenTelemetry](https://migronaut.vercel.app/guide/opentelemetry) · [CI/CD](https://migronaut.vercel.app/guide/ci-cd) · [Troubleshooting](https://migronaut.vercel.app/guide/troubleshooting)
 - Reference: [CLI Cheatsheet](https://migronaut.vercel.app/reference/cli) · [Error Codes](https://migronaut.vercel.app/reference/error-codes)
 
 ---
@@ -753,6 +757,9 @@ await mq.enqueueConverge();              // declared indexes and validators, as
   failed one. Duplicate enqueues are deduplicated; an already-applied migration completes as
   `skipped`.
 - **Bring your own Worker** with `createMigrationProcessor()` (NestJS, BullMQ Pro).
+- **What a migration logs for your users** (`logger.info(…, { userland: true })`) lands in the
+  job's log and reaches `mq.kit.on('migration:log', …)` with the job's id — keep it in a
+  collection of your own ([Migration Logs](https://migronaut.vercel.app/guide/migration-logs)).
 
 → **[Migrations as a Queue](https://migronaut.vercel.app/guide/bullmq)** ·
 [runnable example service](examples/migration-service)

package/bullmq.d.ts

@@ -840,6 +840,13 @@ export interface CreateMigrationProcessorOptions {
   jobOptions?: MigrationJobOptions;
   /** What a job may ask for beyond the ordinary — see {@link MigrationJobPermissions} */
   allow?: MigrationJobPermissions;
+  /**
+   * How many of a migration's `userland: true` lines one job's log takes (a
+   * lane: one slice) — the rest are counted in one closing row. `0` mirrors
+   * none; `migration:log` still carries every line. Default 1000
+   * @experimental New in 2.4
+   */
+  userlandLogRows?: number;
   /**
    * The background queue: what an `up` (or `down`) job registers gets its
    * coordinator there at once, and every `sync` tick heals it. @experimental
@@ -857,6 +864,11 @@ export interface CreateMigrationProcessorOptions {
  * declares exactly three parameters, which is what makes BullMQ hand it the
  * cancellation signal. Jobs are processed one at a time even when the Worker
  * is configured for more.
+ *
+ * Each run is told which job it works for (the kit's `job` option), so a
+ * migration's `ctx.run` and every `migration:log` event carry `jobId` and
+ * `groupId`, and the migration's `userland: true` lines are written into the
+ * job's log next to the processor's own rows (`✎ …`).
  */
 export interface MigrationProcessor {
   (
@@ -864,7 +876,10 @@ export interface MigrationProcessor {
     token?: string,
     signal?: AbortSignal,
   ): Promise<MigrationJobResult | SyncJobResult | ConvergeJobResult>;
-  /** The kit running the jobs — subscribe to its events for metrics */
+  /**
+   * The kit running the jobs — subscribe to its events for metrics, and to
+   * `migration:log` for what the migrations log for your users
+   */
   readonly kit: MigratorKit;
   /**
    * Stop taking the lock. Irreversible. A job that has not started its
@@ -911,10 +926,18 @@ export interface CreateBackgroundProcessorOptions {
   stallMs?: number;
   /** Failed slices in a row before a lane gives up (0–100). Default 8 */
   maxLaneRetries?: number;
+  /**
+   * See {@link CreateMigrationProcessorOptions.userlandLogRows} — counted per slice
+   * @experimental New in 2.4
+   */
+  userlandLogRows?: number;
 }
 
 /**
  * The function a Worker on the background queue runs. Jobs run side by side.
+ * A lane's slice is told its job (`runBackgroundSlice`'s `job`), so its
+ * `migration:log` events carry `jobId` and its `userland: true` lines are
+ * written into the lane job's log (`✎ …`).
  * @experimental New in 2.3
  */
 export interface BackgroundProcessor {
@@ -1108,6 +1131,12 @@ export interface CreateMigrationQueueOptions<
    * refuse fails at the call. Give every producer and worker the same policy.
    */
   allow?: MigrationJobPermissions;
+  /**
+   * See {@link CreateMigrationProcessorOptions.userlandLogRows} — for the
+   * migration jobs and, with `background`, the lanes
+   * @experimental New in 2.4
+   */
+  userlandLogRows?: number;
   /**
    * Background migrations on a queue of their own (`<queueName>-background`):
    * a coordinator job each, with lanes as its children. `true` takes every
@@ -1164,7 +1193,11 @@ export class MigrationQueue<
 > {
   constructor(options: CreateMigrationQueueOptions<Q, W, E>);
 
-  /** The kit behind the queue — `kit.on('migration:success', …)` for metrics */
+  /**
+   * The kit behind the queue — `kit.on('migration:success', …)` for metrics,
+   * `kit.on('migration:log', …)` (in the worker's process) to keep what the
+   * migrations log for your users
+   */
   readonly kit: MigratorKit;
   /** Your Queue, with its own type */
   readonly queue: Q;

package/index.d.ts

@@ -35,6 +35,57 @@ export interface MigrationContext {
    * migronaut cannot interrupt a running function by itself.
    */
   signal?: AbortSignal;
+  /**
+   * The kit's logger, with this run's correlation ({@link run}) bound into the
+   * fields of every line. A call whose fields hold `userland: true` is also
+   * emitted as the `migration:log` event, for the application to store and show
+   * its users — migronaut stores none of it:
+   *
+   * ```js
+   * logger.info('batch done', { userland: true, processed: 1000 });
+   * ```
+   *
+   * Always present when migronaut runs the migration; optional so a context
+   * built by hand (in a test) still type-checks.
+   * @experimental New in 2.4
+   */
+  logger?: MigrationLogger;
+  /**
+   * Who this is: the run id, the migration, the direction, the transaction
+   * attempt and, when the caller named them, the queue job and the actor.
+   * Frozen; the same values `logger` binds and `migration:log` carries.
+   * Always present when migronaut runs the migration.
+   * @experimental New in 2.4
+   */
+  run?: MigrationRunInfo;
+}
+
+/**
+ * The correlation of a run, as `ctx.run`. `migration`, `batch` and `attempt`
+ * describe one migration and are absent in `beforeAll`/`afterAll`.
+ * @experimental New in 2.4
+ */
+export interface MigrationRunInfo {
+  /** The run id — the same on the lock, the changelog record and every event of the run */
+  readonly id: string;
+  readonly direction: 'up' | 'down';
+  /** The migration file */
+  readonly migration?: string;
+  /** The changelog batch (`up` only) */
+  readonly batch?: number;
+  /**
+   * 1 — or more when a transaction was retried and the body runs again. Not a
+   * queue retry: a migration job is never retried.
+   */
+  readonly attempt?: number;
+  /** The queue job that runs this migration (set by the BullMQ adapter, or the `job` option) */
+  readonly jobId?: string;
+  /** The queue group the job belongs to */
+  readonly groupId?: string;
+  /** Who asked for the run (`requestedBy` option) */
+  readonly requestedBy?: string;
+  /** Why (`reason` option) */
+  readonly reason?: string;
 }
 
 /** Shape of an imported migration file module */
@@ -89,9 +140,18 @@ export type Body<T, N extends ShapeFieldNames = DefaultShapeFieldNames> = T exte
 export interface BackgroundMigrationContext {
   /** Aborted when the slice is stopping (lease lost, pause, shutdown) */
   signal: AbortSignal;
-  logger: MigronautLogger;
+  /**
+   * The kit's logger with {@link background} bound into every line. Fields
+   * with `userland: true` also emit `migration:log` (`kind: 'background'`) —
+   * but `migrate` runs once per document, and again for a document a
+   * concurrent write moved: log from `migrateBatch` or a `step` rather than
+   * per document. In a dry run the lines say `dryRun: true` and nothing is
+   * emitted.
+   */
+  logger: MigrationLogger;
   direction: 'forward' | 'revert';
-  background: { name: string; generation: number; partition: string };
+  /** Where this runs — frozen */
+  background: BackgroundRunInfo;
   session?: ClientSession;
   db?: Db;
   client?: MongoClient;
@@ -99,6 +159,43 @@ export interface BackgroundMigrationContext {
   dryRun?: boolean;
 }
 
+/**
+ * `ctx.background`: which background migration, generation and partition —
+ * and the lane, its queue job and the transaction attempt, as its log lines
+ * and `migration:log` events carry them.
+ */
+export interface BackgroundRunInfo {
+  readonly name: string;
+  /** The plan generation — absent when the live drift watcher runs the transformation */
+  readonly generation?: number;
+  /** The partition (`''` for the drift watcher, `'dry-run'` in a dry run) */
+  readonly partition: string;
+  /**
+   * The lane's run id — its lease's owner, the runId of its `background:*`
+   * events. Absent in a dry run.
+   * @experimental New in 2.4
+   */
+  readonly runId?: string;
+  /**
+   * The queue job working the lane — a background queue's lane job, or the
+   * migration job whose run drives it inline (`backgroundInline`)
+   * @experimental New in 2.4
+   */
+  readonly jobId?: string;
+  /**
+   * The group of that migration job — only when a run drives it inline; a
+   * background queue's lanes have none
+   * @experimental New in 2.4
+   */
+  readonly groupId?: string;
+  /**
+   * 1 — or more when a transactional batch or step runs again in a new
+   * transaction (a transient error, a conflict, a smaller batch)
+   * @experimental New in 2.4
+   */
+  readonly attempt: number;
+}
+
 /** How a background migration splits its collection into partitions */
 export interface BackgroundPartitionSettings {
   /** Partitions per lane (default 4), so a slow partition does not hold the pass */
@@ -1086,9 +1183,41 @@ export interface MigronautLogger {
  * `{ runId, migration, direction, batch, durationMs }` — so a machine-readable
  * logger does not have to parse the human string. A plain `(msg) => …` logger
  * remains valid: the extra argument is simply ignored.
+ *
+ * On a migration's `ctx.logger`, fields with `userland: true` also emit the
+ * `migration:log` event (see {@link MigrationLogEvent}).
  */
 export type LogMethod = (msg: string, fields?: Record<string, unknown>) => void;
 
+/**
+ * `ctx.logger`: the kit's logger with the run's correlation bound into every
+ * line. Each method takes `(msg, fields?)` — or pino's own `(fields, msg?)` —
+ * and an `Error` as the message (its message, credentials masked). Fields with
+ * `userland: true` also emit the `migration:log` event.
+ *
+ * Any {@link MigronautLogger} — or a pino instance — is one, so a context built
+ * by hand in a test can pass the logger it has.
+ * @experimental New in 2.4
+ */
+export interface MigrationLogger {
+  debug(
+    msgOrFields: string | Error | Record<string, unknown>,
+    fieldsOrMsg?: Record<string, unknown> | string,
+  ): void;
+  info(
+    msgOrFields: string | Error | Record<string, unknown>,
+    fieldsOrMsg?: Record<string, unknown> | string,
+  ): void;
+  warn(
+    msgOrFields: string | Error | Record<string, unknown>,
+    fieldsOrMsg?: Record<string, unknown> | string,
+  ): void;
+  error(
+    msgOrFields: string | Error | Record<string, unknown>,
+    fieldsOrMsg?: Record<string, unknown> | string,
+  ): void;
+}
+
 // ─── Telemetry ────────────────────────────────────────────────────────────────
 
 /** A span or metric attribute value — the scalar subset migronaut sets */
@@ -1453,6 +1582,25 @@ export interface UpOptions {
   requestedBy?: string;
   /** Why (≤ 512 characters) — a ticket, a sentence; stamped like `requestedBy` */
   reason?: string;
+  /**
+   * The queue job this run works for — bound into `ctx.run`, the run's log
+   * lines and `migration:log`. The BullMQ adapter sets it; set it yourself
+   * when you drive the kit from a queue of your own.
+   * @experimental New in 2.4
+   */
+  job?: JobRef;
+}
+
+/**
+ * The queue job a run works for. Nothing is stored: the ids only correlate
+ * what the run logs with the job a dashboard shows.
+ * @experimental New in 2.4
+ */
+export interface JobRef {
+  /** The job's id (≤ 1024 characters) */
+  id: string;
+  /** The group of jobs it was enqueued with (≤ 128 characters) */
+  groupId?: string;
 }
 
 /** Options for {@link MigratorKit.down} */
@@ -1487,6 +1635,11 @@ export interface DownOptions {
   requestedBy?: string;
   /** Why (≤ 512 characters) — a ticket, a sentence; stamped as `revertReason` */
   reason?: string;
+  /**
+   * The queue job this run works for — see {@link UpOptions.job}
+   * @experimental New in 2.4
+   */
+  job?: JobRef;
 }
 
 /** Payload common to every lifecycle event */
@@ -1500,6 +1653,12 @@ export interface MigrationEvent extends MigronautEventBase {
   direction: 'up' | 'down';
   batch?: number;
   durationMs?: number;
+  /**
+   * How many times the body ran, when the driver retried its transaction (on
+   * `migration:success` and `migration:error`; absent when it ran once)
+   * @experimental New in 2.4
+   */
+  attempts?: number;
   /**
    * Human-readable failure message (on `migration:error` only), with URI
    * credentials already redacted — safe to ship to metrics/alerting as-is.
@@ -1621,6 +1780,82 @@ export interface ConvergeEndEvent extends MigronautEventBase {
   error?: string;
 }
 
+/** The level of a `ctx.logger` call */
+export type MigrationLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * What every `migration:log` event carries.
+ * @experimental New in 2.4
+ */
+export interface MigrationLogEventBase {
+  level: MigrationLogLevel;
+  /**
+   * The message — URI credentials and the values a server error quotes (an
+   * E11000's duplicate key) masked — at most 2048 characters
+   */
+  msg: string;
+  /**
+   * The call's fields without the `userland` marker, as a document a driver can
+   * store: a copy, its strings redacted, at most 8 levels and 1000 entries
+   * deep, strings at most 4096 characters. Dates, regular expressions and BSON
+   * values are kept as they are, binary data up to 4096 bytes too. An `Error`
+   * becomes `{ name, message, code?, codeName? }`; a `Map` an object, a `Set`
+   * an array; any other instance what `JSON.stringify` would see.
+   */
+  data: Record<string, unknown>;
+  /** When the call was made, by this process's clock — a TTL index can expire on it */
+  at: Date;
+  /** Increasing within one `runId`: orders the events of one millisecond */
+  seq: number;
+  /** Present when `msg` or `data` was cut to those bounds */
+  truncated?: true;
+}
+
+/**
+ * A `ctx.logger` call with `userland: true` in an ordinary migration or its
+ * hooks — `migration`, `batch` and `attempt` are absent in `beforeAll`/`afterAll`.
+ * @experimental New in 2.4
+ */
+export interface OrdinaryMigrationLogEvent extends MigrationLogEventBase {
+  kind: 'migration';
+  runId: string;
+  direction: 'up' | 'down';
+  migration?: string;
+  batch?: number;
+  attempt?: number;
+  jobId?: string;
+  groupId?: string;
+  requestedBy?: string;
+  reason?: string;
+}
+
+/**
+ * A `ctx.logger` call with `userland: true` in a background migration's
+ * `migrate`, `migrateBatch`, `step` (or their way back). `runId` is the lane's,
+ * the one its `background:*` events carry.
+ * @experimental New in 2.4
+ */
+export interface BackgroundMigrationLogEvent extends MigrationLogEventBase {
+  kind: 'background';
+  /** The lane's run id (a dry run, which has none, emits nothing) */
+  runId: string;
+  migration: string;
+  direction: 'forward' | 'revert';
+  generation?: number;
+  partition: string;
+  attempt: number;
+  jobId?: string;
+  /** Only when a run drives it inline — see {@link BackgroundRunInfo.groupId} */
+  groupId?: string;
+}
+
+/**
+ * The `migration:log` event — `kind` tells an ordinary migration's from a
+ * background migration's.
+ * @experimental New in 2.4
+ */
+export type MigrationLogEvent = OrdinaryMigrationLogEvent | BackgroundMigrationLogEvent;
+
 /**
  * Lifecycle events emitted by {@link MigratorKit}. Subscribe to feed metrics or
  * alerting without parsing log lines; a listener that throws is contained and
@@ -1634,6 +1869,12 @@ export interface MigronautEvents {
   'migration:success': (event: MigrationEvent) => void;
   'migration:skipped': (event: MigrationEvent) => void;
   'migration:error': (event: MigrationEvent) => void;
+  /**
+   * A `ctx.logger` call marked `userland: true` — for the application to keep.
+   * Logged lines without the marker emit nothing.
+   * @experimental New in 2.4
+   */
+  'migration:log': (event: MigrationLogEvent) => void;
   'lock:acquired': (event: LockEvent) => void;
   'lock:released': (event: LockEvent) => void;
   'lock:lost': (event: LockEvent) => void;
@@ -1716,6 +1957,11 @@ export interface RedoOptions {
   requestedBy?: string;
   /** Why — stamped like `requestedBy` */
   reason?: string;
+  /**
+   * The queue job this run works for — both halves carry it; see {@link UpOptions.job}
+   * @experimental New in 2.4
+   */
+  job?: JobRef;
 }
 
 /** Options for {@link MigratorKit.create} */
@@ -1952,7 +2198,15 @@ export class MigratorKit extends EventEmitter {
   /** One slice of one lane: claim a partition and a slot, work it, release. @experimental */
   runBackgroundSlice(
     name: string,
-    options?: { signal?: AbortSignal; sliceMs?: number },
+    options?: {
+      signal?: AbortSignal;
+      sliceMs?: number;
+      /**
+       * The queue job working the lane — on its log lines and `migration:log` events
+       * @experimental New in 2.4
+       */
+      job?: Pick<JobRef, 'id'>;
+    },
   ): Promise<BackgroundSliceResult>;
   /**
    * Drive a background migration from this process until it is done (or one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexify/migronaut",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Elegant, fast, fully-typed, zero-dependency MongoDB migrations for Node.js — adopts an existing migrate-mongo changelog in one command",
   "license": "MIT",
   "author": "Alex Dolid <dolid.sasha@gmail.com>",
@@ -102,6 +102,7 @@
     "c8": "^10.1.3",
     "esbuild": "^0.28.1",
     "ioredis": "^5.11.1",
+    "mermaid": "^11.17.2",
     "mongodb": "^6.12.0",
     "mongodb-memory-server": "10.4.3",
     "mongoose": "^8.9.2",