@alexify/migronaut 2.2.0 → 2.4.0

package/src/index.js

@@ -1,8 +1,12 @@
 const { EXIT_CODES } = require('./cli/exit-codes.js');
+const { startBackgroundRunner } = require('./core/background-runner.js');
 const { MigratorKit } = require('./core/migrator.js');
 const { pendingMigrations, runMigrations } = require('./core/run.js');
 const { createLogger } = require('./utils/logger.js');
 const {
+  BackgroundConflictError,
+  BackgroundFailedError,
+  BackgroundPendingError,
   ChecksumMismatchError,
   ConfigFileExistsError,
   ConfigInvalidError,
@@ -27,7 +31,10 @@ const {
   OutOfOrderMigrationError,
   QueueJobFailedError,
   QueueJobInvalidError,
+  RevisionConflictError,
   RunAbortedError,
+  SandboxRefusedError,
+  ShapeVersionError,
 } = require('./errors/index.js');
 
 module.exports = {
@@ -46,7 +53,13 @@ module.exports = {
   // The CLI's exit-code map, for wrappers that mirror its semantics
   EXIT_CODES,
 
+  // Background migrations driven from inside the application (experimental)
+  startBackgroundRunner,
+
   // Error classes
+  BackgroundConflictError,
+  BackgroundFailedError,
+  BackgroundPendingError,
   ChecksumMismatchError,
   ConfigFileExistsError,
   ConfigInvalidError,
@@ -71,5 +84,8 @@ module.exports = {
   OutOfOrderMigrationError,
   QueueJobFailedError,
   QueueJobInvalidError,
+  RevisionConflictError,
   RunAbortedError,
+  SandboxRefusedError,
+  ShapeVersionError,
 };

package/src/utils/error.js

@@ -1,5 +1,5 @@
 const { MigronautError } = require('../errors/index.js');
-const { redactUris } = require('./redact.js');
+const { redactOutbound, redactUris } = require('./redact.js');
 
 /**
  * Human-readable message from any thrown value, with URI credentials masked.
@@ -25,4 +25,13 @@ function errorWithCause(error) {
   return cause ? `${message} — ${cause}` : message;
 }
 
-module.exports = { errorText, errorWithCause };
+/**
+ * {@link errorText} for an error about the application's data — a background
+ * migration's document errors and failed slices, kept in its state and
+ * logged: the values a server error quotes (an E11000's duplicate key — an
+ * email, a phone number) are masked too. Migronaut never logs a document's
+ * contents; the index name still says which constraint was violated.
+ */
+const documentErrorText = (error) => redactOutbound(errorText(error));
+
+module.exports = { documentErrorText, errorText, errorWithCause };

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

package/src/utils/loader.js

@@ -3,6 +3,7 @@ const path = require('node:path');
 const { pathToFileURL } = require('node:url');
 const { MigrationFileNotFoundError, MigrationInvalidExportError } = require('../errors/index.js');
 const { errorText } = require('./error.js');
+const { requiresIssues } = require('./migration-name.js');
 
 /** TypeScript source extensions that require a TS-capable runtime to import */
 const TS_EXTENSIONS = new Set(['.ts', '.mts', '.cts']);
@@ -96,16 +97,13 @@ function importUserFile(filepath, options = {}) {
 }
 
 /**
- * Dynamically load a migration file and validate its exports.
- *
- * Handles all three supported formats:
- * - TypeScript / JavaScript ESM named exports (`export async function up/down`)
- * - CommonJS default export (`module.exports = { up, down }`)
+ * Import a migration file: its module, resolved — the default export of a
+ * CommonJS file, the namespace of an ES module with named exports.
  *
  * @throws {MigrationFileNotFoundError} when the file does not exist
- * @throws {MigrationInvalidExportError} when up/down are not both functions
+ * @throws {MigrationInvalidExportError} when TypeScript cannot be loaded
  */
-async function loadMigrationFile(filepath, options = {}) {
+async function importMigrationModule(filepath, options = {}) {
   try {
     await fs.access(filepath);
   } catch {
@@ -123,7 +121,48 @@ async function loadMigrationFile(filepath, options = {}) {
     throw error;
   }
   // `mod.default ?? mod` handles the CommonJS default-export case
-  const resolved = imported.default ?? imported;
+  return imported.default ?? imported;
+}
+
+/** The `requires` export, validated against the file's own name */
+function readRequires(resolved, filepath) {
+  if (resolved.requires === undefined) return {};
+  const issues = requiresIssues(resolved.requires, path.basename(filepath));
+  if (issues.length > 0) {
+    throw new MigrationInvalidExportError(`Invalid ${issues[0].path}: ${issues[0].message}`, {
+      filepath,
+      issues,
+    });
+  }
+  return { requires: [...resolved.requires] };
+}
+
+/**
+ * What a migration module exports, validated: a regular migration
+ * (`{ up, down, useTransaction?, timeoutMs?, description?, requires? }`) or a
+ * background one (`{ kind: 'background', background, description?,
+ * requires? }` — its spec is validated where the collection's versioning is
+ * known). A file with both `background` and `up`/`down` is refused: the
+ * expand steps belong in a migration of their own.
+ *
+ * @throws {MigrationInvalidExportError}
+ */
+function resolveMigrationExports(resolved, filepath) {
+  if (resolved.background !== undefined) {
+    if (resolved.up !== undefined || resolved.down !== undefined) {
+      throw new MigrationInvalidExportError(
+        'A background migration exports no up() or down() — put the expand steps in a ' +
+          'migration of their own',
+        { filepath },
+      );
+    }
+    return {
+      kind: 'background',
+      background: resolved.background,
+      ...(typeof resolved.description === 'string' ? { description: resolved.description } : {}),
+      ...readRequires(resolved, filepath),
+    };
+  }
 
   if (!isFunction(resolved.up) || !isFunction(resolved.down)) {
     throw new MigrationInvalidExportError('Migration must export async up() and down() functions', {
@@ -142,8 +181,37 @@ async function loadMigrationFile(filepath, options = {}) {
   if (typeof resolved.description === 'string') {
     migration.description = resolved.description;
   }
+  Object.assign(migration, readRequires(resolved, filepath));
 
   return migration;
 }
 
-module.exports = { importUserFile, loadMigrationFile, tsLoadErrorOrNull, tsLoadMessageOrNull };
+/**
+ * Dynamically load a migration file and validate its exports.
+ *
+ * Handles all three supported formats:
+ * - TypeScript / JavaScript ESM named exports (`export async function up/down`)
+ * - CommonJS default export (`module.exports = { up, down }`)
+ *
+ * A background migration (`kind: 'background'`) is returned like any other:
+ * the caller tells it apart by its kind.
+ *
+ * @throws {MigrationFileNotFoundError} when the file does not exist
+ * @throws {MigrationInvalidExportError} when up/down are not both functions
+ */
+async function loadMigrationFile(filepath, options = {}) {
+  const migration = resolveMigrationExports(
+    await importMigrationModule(filepath, options),
+    filepath,
+  );
+  return migration;
+}
+
+module.exports = {
+  importMigrationModule,
+  importUserFile,
+  loadMigrationFile,
+  resolveMigrationExports,
+  tsLoadErrorOrNull,
+  tsLoadMessageOrNull,
+};

package/src/utils/migration-name.js

@@ -29,4 +29,36 @@ function assertMigrationName(name, context = {}) {
   }
 }
 
-module.exports = { assertMigrationName, isBareFilename };
+/**
+ * Why a file's `requires` export is not valid: an array of bare migration
+ * file names, no duplicates, each sorting strictly before the file itself
+ * (`name`). Files run in name order, so an edge that only ever points
+ * backwards can never close a cycle — the whole "is it a DAG?" question,
+ * answered by the name. Returns `{ path, message }` issues.
+ */
+function requiresIssues(requires, name) {
+  if (requires === undefined) return [];
+  if (!Array.isArray(requires)) {
+    return [{ path: 'requires', message: 'must be an array of migration file names' }];
+  }
+  const issues = [];
+  const seen = new Set();
+  for (const [position, required] of requires.entries()) {
+    const path = `requires[${position}]`;
+    if (!isBareFilename(required)) {
+      issues.push({ path, message: 'must be a bare migration file name' });
+    } else if (seen.has(required)) {
+      issues.push({ path, message: `names "${required}" twice` });
+    } else if (name !== undefined && required >= name) {
+      issues.push({
+        path,
+        message: `must name an earlier migration ("${required}" does not sort before "${name}")`,
+      });
+    } else {
+      seen.add(required);
+    }
+  }
+  return issues;
+}
+
+module.exports = { assertMigrationName, isBareFilename, requiresIssues };

package/src/utils/redact.js

@@ -1,3 +1,5 @@
+const { isPlainObject } = require('./canonical.js');
+
 /**
  * Credential redaction for anything that leaves the process — error messages,
  * stacks, `--json` payloads, log lines. The MongoDB driver echoes the raw
@@ -69,6 +71,24 @@ function redactOutbound(text) {
   return redactUris(text).replace(DUPLICATE_KEY_VALUES, '$1{ <redacted> }');
 }
 
+/**
+ * Set `key` on a copy as an own property. A plain assignment of `__proto__` —
+ * a key `JSON.parse` happily makes — would replace the copy's prototype and
+ * lose the key instead.
+ */
+function put(target, key, value) {
+  if (key === '__proto__') {
+    Object.defineProperty(target, key, {
+      value,
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  } else {
+    target[key] = value;
+  }
+}
+
 /**
  * Redact every string reachable from `value` (plain objects and arrays only —
  * class instances are left alone rather than cloned into broken shapes).
@@ -81,12 +101,129 @@ function redactDeep(value) {
     for (let index = 0; index < value.length; index++) copy[index] = redactDeep(value[index]);
     return copy;
   }
-  if (value !== null && typeof value === 'object' && value.constructor === Object) {
+  if (isPlainObject(value)) {
     const copy = {};
-    for (const key of Object.keys(value)) copy[key] = redactDeep(value[key]);
+    for (const key of Object.keys(value)) put(copy, key, redactDeep(value[key]));
     return copy;
   }
   return value;
 }
 
-module.exports = { redactDeep, redactOutbound, redactUris };
+/**
+ * How much of a value {@link redactBounded} copies: nesting, entries in all,
+ * the length of one string and of one piece of binary data. What a migration
+ * hands to `ctx.logger` is the application's own data, of any size and shape —
+ * a cycle included — and a subscriber stores it; these keep one call's copy
+ * small and finite.
+ */
+const BOUNDS = Object.freeze({ depth: 8, entries: 1000, string: 4096, bytes: 4096 });
+
+/** Stands in for what {@link redactBounded} left out */
+const TRUNCATED = '[truncated]';
+
+/** The size of binary data — a Buffer or another Uint8Array, a BSON Binary — or undefined */
+function byteLength(item) {
+  if (item instanceof Uint8Array) return item.byteLength;
+  if (item._bsontype === 'Binary') return item.position;
+  return undefined;
+}
+
+/**
+ * An Error as data: its name, its message — credentials and the values a
+ * server error quotes masked, as for anything that leaves the process — and
+ * its code. Not the stack, and not what else it carries: a driver error's raw
+ * server response repeats the offending document's values (`keyValue`,
+ * `errmsg`), and its `message` is not even enumerable, so the error itself
+ * would be stored as an empty document.
+ */
+function errorData(error) {
+  const data = {
+    name: String(error.name),
+    message: redactOutbound(typeof error.message === 'string' ? error.message : ''),
+  };
+  if (typeof error.code === 'number' || typeof error.code === 'string') data.code = error.code;
+  if (typeof error.codeName === 'string') data.codeName = error.codeName;
+  return data;
+}
+
+/**
+ * {@link redactDeep} within {@link BOUNDS}, for data that leaves the process
+ * as a document: every string reachable redacted ({@link redactOutbound}: the
+ * values a server error quotes too) and clipped, nesting past
+ * the depth (which is what ends a cycle) and entries past the budget replaced
+ * or dropped. What the driver stores as a value of its own is kept as is — a
+ * Date, a RegExp, an ObjectId or another BSON value, and binary data within
+ * its bound. An Error becomes `{ name, message, code?, codeName? }`; a Map is
+ * copied as an object and a Set as an array; any other instance goes by its
+ * `toJSON()`, or its own fields, the way `JSON.stringify` would see it.
+ * `omit` names a key left out of the top level only. Returns
+ * `{ value, truncated }`; never mutates the input.
+ */
+function redactBounded(value, { omit } = {}) {
+  let entries = 0;
+  let truncated = false;
+  /** One more entry, or false once the budget is spent */
+  const take = () => {
+    if (entries >= BOUNDS.entries) {
+      truncated = true;
+      return false;
+    }
+    entries += 1;
+    return true;
+  };
+  const copy = (item, depth) => {
+    if (typeof item === 'string') {
+      // Outbound, like the event's message: an error's text copied into a
+      // field (`{ error: err.message }`) loses the values it quotes too.
+      const text = redactOutbound(item);
+      if (text.length <= BOUNDS.string) return text;
+      truncated = true;
+      return `${text.slice(0, BOUNDS.string)}…`;
+    }
+    if (item === null || typeof item !== 'object') return item;
+    if (item instanceof Date || item instanceof RegExp) return item;
+    const bytes = byteLength(item);
+    if (bytes !== undefined) {
+      if (bytes <= BOUNDS.bytes) return item;
+      truncated = true;
+      return TRUNCATED;
+    }
+    if (typeof item._bsontype === 'string') return item;
+    if (item instanceof Error) return copy(errorData(item), depth);
+    if (depth >= BOUNDS.depth) {
+      truncated = true;
+      return TRUNCATED;
+    }
+    if (Array.isArray(item) || item instanceof Set) {
+      const out = [];
+      for (const element of item) {
+        if (!take()) break;
+        out.push(copy(element, depth + 1));
+      }
+      return out;
+    }
+    const out = {};
+    if (item instanceof Map) {
+      for (const [key, element] of item) {
+        if (!take()) break;
+        put(out, String(key), copy(element, depth + 1));
+      }
+      return out;
+    }
+    // What JSON.stringify would see: a toJSON() result one level down (so a
+    // chain of them ends at the depth bound), else the instance's own fields.
+    if (!isPlainObject(item) && typeof item.toJSON === 'function') {
+      return copy(item.toJSON(), depth + 1);
+    }
+    for (const key of Object.keys(item)) {
+      if (depth === 0 && key === omit) continue;
+      if (!take()) break;
+      put(out, key, copy(item[key], depth + 1));
+    }
+    return out;
+  };
+  const result = copy(value, 0);
+  return { value: result, truncated };
+}
+
+module.exports = { BOUNDS, redactBounded, redactDeep, redactOutbound, redactUris };

package/src/utils/telemetry.js

@@ -13,6 +13,8 @@ const SPAN_STATUS_ERROR = 2;
 const SPANS = {
   RUN: 'migronaut.run',
   MIGRATION: 'migronaut.migration',
+  BACKGROUND_SLICE: 'migronaut.background.slice',
+  BACKGROUND_COORDINATE: 'migronaut.background.coordinate',
 };
 
 /** Every attribute key migronaut sets, on spans and on metric points */
@@ -35,6 +37,14 @@ const ATTRIBUTES = {
   MIGRATION_INDEX: 'migronaut.migration.index',
   MIGRATION_TOTAL: 'migronaut.migration.total',
   MIGRATION_TRANSACTION: 'migronaut.migration.transaction',
+  MIGRATION_ATTEMPTS: 'migronaut.migration.attempts',
+  JOB_ID: 'migronaut.job.id',
+  JOB_GROUP_ID: 'migronaut.job.group_id',
+  BACKGROUND_NAME: 'migronaut.background.name',
+  BACKGROUND_OUTCOME: 'migronaut.background.outcome',
+  BACKGROUND_RESULT: 'migronaut.background.result',
+  BACKGROUND_REASON: 'migronaut.background.reason',
+  BACKGROUND_SHARD: 'migronaut.background.shard',
   ERROR_TYPE: 'error.type',
   /** The database a run is against — OpenTelemetry's database semantic convention */
   DB_NAMESPACE: 'db.namespace',
@@ -48,6 +58,14 @@ const METRICS = {
   LOCK_REFUSED: 'migronaut.lock.refused',
   LOCK_LOST: 'migronaut.lock.lost',
   SEARCH_WAIT_DURATION: 'migronaut.converge.search.wait.duration',
+  BACKGROUND_DOCUMENTS: 'migronaut.background.documents',
+  BACKGROUND_SLICE_DURATION: 'migronaut.background.slice.duration',
+  BACKGROUND_BATCH_WRITE_DURATION: 'migronaut.background.batch.write.duration',
+  BACKGROUND_THROTTLE: 'migronaut.background.throttled',
+  BACKGROUND_DRIFT: 'migronaut.background.drift.detected',
+  BACKGROUND_TRANSACTION_RETRIES: 'migronaut.background.transaction.retried',
+  BACKGROUND_LEASES_RECLAIMED: 'migronaut.background.leases.reclaimed',
+  BACKGROUND_WATCH_DELAY: 'migronaut.background.watch.delay',
 };
 
 /**
@@ -339,6 +357,47 @@ function createTelemetry(telemetry, { dbName } = {}) {
     'Time a converge waited for its search index builds, by how the wait ended',
   );
 
+  const backgroundDocuments = counter(
+    METRICS.BACKGROUND_DOCUMENTS,
+    'Documents a background migration handled, by result (migrated, skipped, conflict, failed)',
+    '{document}',
+  );
+  const backgroundSliceDuration = histogram(
+    METRICS.BACKGROUND_SLICE_DURATION,
+    'Duration of one background migration slice, by outcome',
+  );
+  const backgroundBatchWrite = histogram(
+    METRICS.BACKGROUND_BATCH_WRITE_DURATION,
+    'Time to write one background migration batch',
+  );
+  const backgroundThrottle = counter(
+    METRICS.BACKGROUND_THROTTLE,
+    'Adaptive throttle changes of background migrations, by reason',
+    '{change}',
+  );
+  const backgroundDrift = counter(
+    METRICS.BACKGROUND_DRIFT,
+    'Old-shape documents found after a background migration completed',
+    '{finding}',
+  );
+  const backgroundTransactionRetries = counter(
+    METRICS.BACKGROUND_TRANSACTION_RETRIES,
+    'Transactional background batches retried, by reason',
+    '{retry}',
+  );
+  const backgroundLeasesReclaimed = counter(
+    METRICS.BACKGROUND_LEASES_RECLAIMED,
+    'Partition leases reclaimed from a lane that stopped renewing',
+    '{lease}',
+  );
+  const backgroundWatchDelay = histogram(
+    METRICS.BACKGROUND_WATCH_DELAY,
+    'Time from an old-shape write to its upgrade by the live drift watcher',
+  );
+  const add = (instrument, value, attributes) => {
+    if (instrument && value > 0) safe(() => instrument.add(value, withBase(attributes)));
+  };
+
   // Durations are measured in milliseconds everywhere in migronaut and
   // reported in seconds, the unit OpenTelemetry's conventions settle on.
   const record = (instrument, durationMs, attributes) => {
@@ -391,6 +450,57 @@ function createTelemetry(telemetry, { dbName } = {}) {
     searchWaited({ waitedMs, outcome }) {
       record(searchWaitDuration, waitedMs, { [ATTRIBUTES.SEARCH_WAIT_OUTCOME]: outcome });
     },
+    /**
+     * A background migration slice ended: its duration by outcome, and the
+     * documents it handled by result. The partition is never an attribute —
+     * dimensions stay low-cardinality.
+     */
+    backgroundSliceEnded({ name, durationMs, outcome, counters = {}, error }) {
+      const at = { [ATTRIBUTES.BACKGROUND_NAME]: name };
+      record(backgroundSliceDuration, durationMs, {
+        ...at,
+        [ATTRIBUTES.BACKGROUND_OUTCOME]: outcome,
+        ...failure(error),
+      });
+      for (const [key, result] of [
+        ['migrated', 'migrated'],
+        ['skipped', 'skipped'],
+        ['conflicts', 'conflict'],
+        ['failed', 'failed'],
+      ]) {
+        add(backgroundDocuments, counters[key] ?? 0, {
+          ...at,
+          [ATTRIBUTES.BACKGROUND_RESULT]: result,
+        });
+      }
+    },
+    backgroundBatchWritten({ name, durationMs, shard }) {
+      record(backgroundBatchWrite, durationMs, {
+        [ATTRIBUTES.BACKGROUND_NAME]: name,
+        [ATTRIBUTES.BACKGROUND_SHARD]: shard,
+      });
+    },
+    backgroundThrottled({ name, reason }) {
+      add(backgroundThrottle, 1, {
+        [ATTRIBUTES.BACKGROUND_NAME]: name,
+        [ATTRIBUTES.BACKGROUND_REASON]: reason,
+      });
+    },
+    backgroundDrift({ name, count = 1 }) {
+      add(backgroundDrift, count, { [ATTRIBUTES.BACKGROUND_NAME]: name });
+    },
+    backgroundTransactionRetried({ name, reason, count = 1 }) {
+      add(backgroundTransactionRetries, count, {
+        [ATTRIBUTES.BACKGROUND_NAME]: name,
+        [ATTRIBUTES.BACKGROUND_REASON]: reason,
+      });
+    },
+    backgroundLeasesReclaimed({ name, count }) {
+      add(backgroundLeasesReclaimed, count, { [ATTRIBUTES.BACKGROUND_NAME]: name });
+    },
+    backgroundWatchDelay({ name, delayMs }) {
+      record(backgroundWatchDelay, delayMs, { [ATTRIBUTES.BACKGROUND_NAME]: name });
+    },
   };
 }
 

package/src/utils/template.js

@@ -145,6 +145,51 @@ module.exports = { description, up, down };
 `;
 }
 
+/**
+ * The built-in background migration template (`create --background`): the
+ * declarative form, with the knobs most worth knowing about spelled out.
+ */
+function defaultBackgroundTemplate(js, esm = false) {
+  const typed = js
+    ? "/** @type {import('@alexify/migronaut').DeclarativeBackgroundMigration} */\n"
+    : '';
+  const typeImport = js
+    ? ''
+    : "import type { DeclarativeBackgroundMigration } from '@alexify/migronaut';\n\n";
+  const annotation = js ? '' : ': DeclarativeBackgroundMigration';
+  const body = `{
+  // The collection to rewrite (\`up\` refuses this placeholder).
+  collection: 'TODO',
+  // Documents at version \`from\` (0: no version field yet) become version \`to\`.
+  from: 1,
+  to: 2,
+  // The new document for one old one — return it reshaped; migronaut sets the
+  // version, bumps the revision and writes only the fields that changed.
+  migrate: (doc) => {
+    // TODO: reshape doc, and return it
+    throw new Error('migrate is not written yet');
+  },
+  // The way back, for \`down\`. Without one, \`down\` refuses once documents
+  // were rewritten. Never \`(doc) => doc\`: that would stamp the old version
+  // on documents still in the new shape.
+  // revert: ({ shipping, ...doc }) => ({ ...doc, address: shipping.address }),
+  // Partitions worked at once, across every process (default 1).
+  // maxParallel: 4,
+}`;
+  if (esm) {
+    return `${typeImport}export const description = '';
+
+${typed}export const background${annotation} = ${body};
+`;
+  }
+  return `${typeImport}const description = '';
+
+${typed}const background${annotation} = ${body};
+
+module.exports = { description, background };
+`;
+}
+
 /** Extensions a custom `--template` file may have — anything else is refused */
 const TEMPLATE_EXTENSIONS = ['.ts', '.js', '.cjs', '.mjs'];
 
@@ -152,7 +197,8 @@ const TEMPLATE_EXTENSIONS = ['.ts', '.js', '.cjs', '.mjs'];
 const MAX_TEMPLATE_BYTES = 1024 * 1024;
 
 /** Resolve template file contents — a custom template if provided, else the built-in */
-async function resolveTemplateContent(templatePath, js, esm = false) {
+async function resolveTemplateContent(templatePath, js, esm = false, background = false) {
+  if (background) return defaultBackgroundTemplate(js, esm);
   if (templatePath) {
     const ext = path.extname(templatePath);
     if (!TEMPLATE_EXTENSIONS.includes(ext)) {
@@ -198,6 +244,7 @@ async function createMigrationFile(options) {
     // Match the project's module system, so a generated migration never makes
     // Node reparse it and warn.
     await isEsmProject(options.dir),
+    options.background === true,
   );
   try {
     // 'wx' fails if the path exists — creating a migration must never silently
@@ -366,6 +413,20 @@ function configBody(values, createExtension) {
   // waitForSearchIndexes: false,
   // searchIndexWaitTimeoutMs: 600000,
 
+  // ── Background migrations (experimental) ────────────────────
+  // A migration file with \`export const background = {…}\` is registered by
+  // \`up\` and runs in partitions (BullMQ, \`migronaut background run\`, or an
+  // in-process runner) without holding the migration lock.
+  // backgroundCollection: '_migronaut_background',
+  // Run it to the end inside the \`up\` that registers it instead.
+  // backgroundInline: false,
+  // Old-shape documents after it completed: reopen it ('reopen') or report.
+  // backgroundOnDrift: 'reopen',
+  // How drift is watched: 'poll' (every 10 minutes), 'stream', or 'both'.
+  // backgroundDrift: 'poll',
+  // Partition a sharded collection by its shard key ('auto') or not ('off').
+  // backgroundShardAware: 'auto',
+
   // ── Lifecycle hooks (code only — not available in JSON config) ──
   // hooks: {
   //   beforeAll: async (ctx) => {},