@alexify/migronaut 2.2.0 → 2.4.0

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.
@@ -152,6 +168,20 @@ function assertConvergeAfterUpValid(converge, filename, to) {
   }
 }
 
+/**
+ * `onBackgroundPending`: what a run does at a migration that `requires` a
+ * background migration not completed yet — `'error'` (throw
+ * BackgroundPendingError) or `'stop'` (end the run there, cleanly).
+ */
+function assertBackgroundPendingValid(onBackgroundPending) {
+  if (onBackgroundPending === undefined) return;
+  if (onBackgroundPending !== 'error' && onBackgroundPending !== 'stop') {
+    throw new ConfigInvalidError("onBackgroundPending must be 'error' or 'stop'", {
+      onBackgroundPending,
+    });
+  }
+}
+
 /** `up(filename, options)` */
 function assertUpOptions(filename, options) {
   assertFilename(filename);
@@ -167,7 +197,9 @@ function assertUpOptions(filename, options) {
   assertOrderedValid(options.ordered, filename);
   assertConvergeAfterUpValid(options.converge, filename, options.to);
   assertChecksumValid(options.checksum, filename);
+  assertBackgroundPendingValid(options.onBackgroundPending);
   assertActorValid(options);
+  assertJobValid(options.job);
 }
 
 /** `down(filename, options)` */
@@ -178,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)` */
@@ -254,6 +288,8 @@ 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/run.js

@@ -41,6 +41,7 @@ const { MigratorKit, RECORD_LOCK_WAIT } = require('./migrator.js');
 async function runMigrations(config = {}, options = {}) {
   const {
     noLock,
+    onBackgroundPending,
     onLockHeld = 'throw',
     // Left undefined unless given: the default then follows the holder's TTL.
     lockWaitTimeoutMs,
@@ -71,6 +72,11 @@ async function runMigrations(config = {}, options = {}) {
   kit.on('converge:end', (event) => {
     if (event.trigger === 'up' && event.success) converge = event.result;
   });
+  // With onBackgroundPending: 'stop', where the run stopped and what for.
+  const waiting = [];
+  kit.on('background:waiting', (event) => {
+    waiting.push({ migration: event.migration, waitsFor: event.waitsFor });
+  });
 
   // An abort reaches the run wherever it is: the wait loop sees the signal
   // between polls, and kit.stop() stops a run that is setting up or between
@@ -90,20 +96,28 @@ async function runMigrations(config = {}, options = {}) {
       waited,
       waitedMs,
       attempts,
-    } = await withLockWait(() => kit.up(undefined, noLock ? { noLock: true } : {}), {
-      onLockHeld,
-      ...(lockWaitTimeoutMs !== undefined ? { lockWaitTimeoutMs } : {}),
-      ...(lockPollIntervalMs !== undefined ? { lockPollIntervalMs } : {}),
-      // Resolved AFTER connect, from the kit's own merged config: a `logger:
-      // null` in the config file must silence the wait lines too, not only
-      // the kit's own.
-      logger: kit.logger,
-      ...(signal ? { signal } : {}),
-      onSettle: (wait) => kit[RECORD_LOCK_WAIT](wait),
-    });
+    } = await withLockWait(
+      () =>
+        kit.up(undefined, {
+          ...(noLock ? { noLock: true } : {}),
+          ...(onBackgroundPending !== undefined ? { onBackgroundPending } : {}),
+        }),
+      {
+        onLockHeld,
+        ...(lockWaitTimeoutMs !== undefined ? { lockWaitTimeoutMs } : {}),
+        ...(lockPollIntervalMs !== undefined ? { lockPollIntervalMs } : {}),
+        // Resolved AFTER connect, from the kit's own merged config: a `logger:
+        // null` in the config file must silence the wait lines too, not only
+        // the kit's own.
+        logger: kit.logger,
+        ...(signal ? { signal } : {}),
+        onSettle: (wait) => kit[RECORD_LOCK_WAIT](wait),
+      },
+    );
     return {
       applied,
-      upToDate: applied.length === 0,
+      upToDate: applied.length === 0 && waiting.length === 0,
+      ...(waiting.length > 0 ? { waiting } : {}),
       waited,
       waitedMs,
       attempts,

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 {
@@ -197,4 +223,4 @@ async function runMigration(params) {
   }
 }
 
-module.exports = { runMigration };
+module.exports = { isTransactionsUnsupported, runMigration };

package/src/core/server-info.js

@@ -25,16 +25,23 @@ const READ_CONCURRENCY = 8;
 
 /**
  * What the server is: a mongos in front of shards (its shard keys matter to
- * prune), and its version (what it can change in place). Best-effort — a
+ * prune), its topology (`replicaSet`, `sharded`, `standalone` — transactions
+ * need one of the first two), and its version (what it can change in place). Best-effort — a
  * server that refuses to say gets the conservative answer: no in-place
  * extras, no shard-key handling.
  */
 async function readServer(db) {
-  const server = { mongos: false, version: undefined };
+  const server = { mongos: false, version: undefined, topology: undefined };
   if (typeof db.admin !== 'function') return server;
   try {
     const hello = await db.admin().command({ hello: 1 });
     server.mongos = hello?.msg === 'isdbgrid';
+    // What transactions need: a replica set member or a mongos.
+    server.topology = server.mongos
+      ? 'sharded'
+      : typeof hello?.setName === 'string'
+        ? 'replicaSet'
+        : 'standalone';
   } catch {
     // Unknown — treated as a replica set or standalone.
   }

package/src/core/shard-info.js

@@ -0,0 +1,76 @@
+const { READ_OPTIONS } = require('./server-info.js');
+
+/**
+ * What the cluster says about a collection's sharding — read from the
+ * `config` database through a mongos. Every read here needs `clusterMonitor`
+ * (or more): a user without it gets `undefined` ("unknown"), never an error,
+ * and the caller falls back to what works without it.
+ *
+ * - `readShardKey` — the shard key, or `null` for a collection that is not
+ *   sharded (an 8.0 `unsplittable` one included: tracked, but on one shard
+ *   under `{ _id: 1 }`, which is no key to partition or target by);
+ * - `readChunks` — the chunks of a sharded collection, in key order.
+ */
+
+/** The server's "not authorized" — the one refusal that means "unknown", not "broken" */
+const UNAUTHORIZED = 13;
+
+const isUnauthorized = (error) => error?.code === UNAUTHORIZED;
+
+/**
+ * `{ key, uuid, timestamp, unsplittable }` of a sharded collection, `null` when
+ * it is not sharded, `undefined` when `config.collections` may not be read.
+ */
+async function readShardKey(client, dbName, collection) {
+  let entry;
+  try {
+    entry = await client
+      .db('config')
+      .collection('collections')
+      .findOne(
+        { _id: `${dbName}.${collection}` },
+        { projection: { key: 1, uuid: 1, timestamp: 1, unsplittable: 1 }, ...READ_OPTIONS },
+      );
+  } catch (error) {
+    if (isUnauthorized(error)) return undefined;
+    throw error;
+  }
+  if (entry === null || entry.unsplittable === true || entry.key === undefined) return null;
+  return {
+    key: entry.key,
+    uuid: entry.uuid,
+    ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
+  };
+}
+
+/**
+ * The chunks of a sharded collection (`readShardKey`'s result), in key order:
+ * `[{ min, max, shard }]` — or `undefined` when `config.chunks` may not be
+ * read. By `uuid` (5.0+), then by namespace (a cluster upgraded from 4.4 that
+ * never refreshed its chunks).
+ */
+async function readChunks(client, dbName, collection, sharding) {
+  const chunks = client.db('config').collection('chunks');
+  // Hashed bounds are NumberLongs: promoted to numbers, they lose precision
+  // past 2^53 (ARCHITECTURE §6.8).
+  const options = {
+    projection: { min: 1, max: 1, shard: 1 },
+    ...READ_OPTIONS,
+    promoteLongs: false,
+  };
+  try {
+    let rows = await chunks.find({ uuid: sharding.uuid }, options).sort({ min: 1 }).toArray();
+    if (rows.length === 0) {
+      rows = await chunks
+        .find({ ns: `${dbName}.${collection}` }, options)
+        .sort({ min: 1 })
+        .toArray();
+    }
+    return rows;
+  } catch (error) {
+    if (isUnauthorized(error)) return undefined;
+    throw error;
+  }
+}
+
+module.exports = { isUnauthorized, readChunks, readShardKey };

package/src/core/versioning-spec.js

@@ -0,0 +1,181 @@
+const { isPlainObject } = require('../utils/canonical.js');
+const { versionIndexKey } = require('../versioning/document.js');
+const { toCount } = require('../versioning/internal.js');
+
+/**
+ * What a collection's `versioning` block asks of the database: the validator
+ * rules for the version and revision fields, merged into whatever validator
+ * the definition declares, and the index every version-filtered scan uses.
+ * Pure — collections.js folds the result into the normalized definition, so
+ * the planner sees an ordinary validator and an ordinary index.
+ *
+ * The version rule has a `minimum` but never a `maximum`: during a rolling
+ * deploy (or after a rollback) a newer release writes a higher version than
+ * the declaration knows, and refusing that write would turn a deploy into an
+ * outage. A revision outgrows `int` after 2³¹ writes — `$inc` turns it into a
+ * `long` — so both are accepted.
+ */
+
+/** `{ required, properties }` for the managed fields, in a fixed order */
+function versioningRules(versioning) {
+  const { field, min, revisionField } = versioning;
+  const properties = { [field]: { bsonType: 'int', minimum: min } };
+  const required = [field];
+  if (revisionField !== null) {
+    properties[revisionField] = { bsonType: ['int', 'long'], minimum: 0 };
+    required.push(revisionField);
+  }
+  // `min: 0` adapts a collection whose documents predate versioning: the
+  // fields are typed when present, but nothing requires them yet.
+  return min === 0 ? { properties } : { required, properties };
+}
+
+/** The managed field names a validator already constrains itself */
+function managedFieldsIn(validator, versioning) {
+  const managed = [versioning.field];
+  if (versioning.revisionField !== null) managed.push(versioning.revisionField);
+  const found = new Set();
+  const schema = validator.$jsonSchema;
+  const properties = isPlainObject(schema) ? schema.properties : undefined;
+  const required = new Set(
+    isPlainObject(schema) && Array.isArray(schema.required) ? schema.required : [],
+  );
+  for (const name of managed) {
+    if (Object.hasOwn(validator, name)) found.add(name);
+    if (isPlainObject(properties) && Object.hasOwn(properties, name)) found.add(name);
+    if (required.has(name)) found.add(name);
+  }
+  return [...found];
+}
+
+/**
+ * Why a declared validator cannot carry the versioning rules — it constrains
+ * a managed field itself, or its `$jsonSchema` is not a schema object. Empty
+ * when the merge can go ahead.
+ */
+function validatorVersioningIssues(validator, versioning) {
+  if (validator === undefined) return [];
+  if (validator === null || !isPlainObject(validator)) {
+    return ['is null, which would remove the versioning rules — drop the validator key instead'];
+  }
+  const issues = [];
+  if (validator.$jsonSchema !== undefined && !isPlainObject(validator.$jsonSchema)) {
+    issues.push('$jsonSchema must be an object to take the versioning rules');
+  } else if (
+    isPlainObject(validator.$jsonSchema) &&
+    validator.$jsonSchema.required !== undefined &&
+    !Array.isArray(validator.$jsonSchema.required)
+  ) {
+    issues.push('$jsonSchema.required must be an array to take the versioning rules');
+  }
+  for (const name of managedFieldsIn(validator, versioning)) {
+    issues.push(`constrains "${name}", which is managed by versioning — remove that rule`);
+  }
+  return issues;
+}
+
+/**
+ * The validator to declare: the versioning rules alone (no validator
+ * declared), merged into the declared `$jsonSchema` (the declared `required`
+ * and `properties` first, ours after), or — next to query operators — added
+ * as a top-level `$jsonSchema`, which the server combines with them.
+ */
+function mergeVersioningValidator(validator, versioning) {
+  const rules = versioningRules(versioning);
+  if (validator === undefined || Object.keys(validator).length === 0) {
+    return { $jsonSchema: rules };
+  }
+  const schema = validator.$jsonSchema;
+  if (!isPlainObject(schema)) return { ...validator, $jsonSchema: rules };
+  const merged = { ...schema };
+  if (rules.required) merged.required = [...(schema.required ?? []), ...rules.required];
+  merged.properties = { ...schema.properties, ...rules.properties };
+  return { ...validator, $jsonSchema: merged };
+}
+
+/** The declared version index — `{ [field]: 1, _id: 1 }`, named by its key */
+const versioningIndex = (versioning) => ({ key: versionIndexKey(versioning) });
+
+/**
+ * The version index of a sharded collection: the shard key between the
+ * version field and `_id` — `{ __v: 1, region: 1, _id: 1 }` — so a batch
+ * over one chunk's range is an index range, not a filter over every old
+ * document of the shard. A hashed field stays hashed; `_id` is not repeated
+ * when the key holds it. On `{ _id: 1 }` it is the ordinary version index.
+ */
+function shardedVersionIndexKey(versioning, shardKey) {
+  const key = { [versioning.field]: 1 };
+  for (const [field, value] of Object.entries(shardKey)) {
+    if (field !== versioning.field) key[field] = value;
+  }
+  if (!('_id' in key)) key._id = 1;
+  return key;
+}
+
+/** Whether an index key is the version index's (same fields, same order, ascending) */
+function isVersioningIndexKey(key, versioning) {
+  if (!isPlainObject(key)) return false;
+  const entries = Object.entries(key);
+  const expected = Object.entries(versionIndexKey(versioning));
+  if (entries.length !== expected.length) return false;
+  for (let i = 0; i < entries.length; i++) {
+    if (entries[i][0] !== expected[i][0] || Number(entries[i][1]) !== expected[i][1]) return false;
+  }
+  return true;
+}
+
+/**
+ * The version floor the live validator enforces — the `minimum` of the version
+ * field's `$jsonSchema` rule — or `null` when it enforces none.
+ */
+function liveVersionFloor(options, versioning) {
+  const schema = options?.validator?.$jsonSchema;
+  const rule = isPlainObject(schema?.properties) ? schema.properties[versioning.field] : undefined;
+  return isPlainObject(rule) ? toCount(rule.minimum) : null;
+}
+
+/**
+ * The `min` converge must check the data against before it raises the floor,
+ * or `null` when there is nothing to check: no versioning, `min: 0`, a
+ * collection that does not exist yet (no documents), or a floor already that
+ * high. Only a rising floor costs a read — the steady state costs nothing.
+ */
+function versionFloorToCheck(definition, live) {
+  const versioning = definition.versioning;
+  if (!versioning || versioning.min === 0 || !live.exists) return null;
+  if (live.type !== undefined && live.type !== 'collection') return null;
+  const floor = liveVersionFloor(live.options, versioning);
+  return floor !== null && floor >= versioning.min ? null : versioning.min;
+}
+
+/**
+ * Why the version floor cannot be raised — `live.versionFloor` is what
+ * converge read: `{ min, below: true | false | 'unknown', error? }` — or
+ * `undefined` when it can. The document ids are never named: they may be PII.
+ */
+function versionFloorConflict(floor) {
+  if (!floor || floor.below === false) return undefined;
+  if (floor.below === true) {
+    return (
+      `documents below version ${floor.min} remain — raising versioning.min would leave them ` +
+      'invalid; let the background migration that upgrades them finish (migronaut background ' +
+      'status), then converge again'
+    );
+  }
+  return (
+    `could not check for documents below version ${floor.min} (${floor.error}) — converge ` +
+    'with the old min first so the version index exists, then raise it'
+  );
+}
+
+module.exports = {
+  isVersioningIndexKey,
+  shardedVersionIndexKey,
+  liveVersionFloor,
+  versionFloorConflict,
+  versionFloorToCheck,
+  mergeVersioningValidator,
+  validatorVersioningIssues,
+  versioningIndex,
+  versioningRules,
+};

package/src/errors/index.js

@@ -260,6 +260,88 @@ class ConvergeFailedError extends MigronautError {
   }
 }
 
+/**
+ * Thrown by the optimistic-concurrency helpers (`@alexify/migronaut/versioning`)
+ * when a revision-guarded write matched nothing. `context.reason` says why:
+ * `'conflict'` (the document exists at another revision — `context.actual`),
+ * `'not-found'` (no document matches the filter at all) or `'unknown'` (the
+ * follow-up read was skipped or could not tell). `context.expected` is the
+ * revision the caller held. The filter is never copied in — it may carry PII.
+ */
+class RevisionConflictError extends MigronautError {
+  constructor(message, context, options) {
+    super('REVISION_CONFLICT', message, context, options);
+    this.name = 'RevisionConflictError';
+  }
+}
+
+/**
+ * Thrown by an upcaster that cannot bring a document to the current shape:
+ * `context.reason` is `'newer'` (written by a newer release), `'below-min'`
+ * (older than the oldest shape still supported) or `'invalid'` (the version
+ * field is not a non-negative integer, or a step returned something that is
+ * not a document).
+ */
+class ShapeVersionError extends MigronautError {
+  constructor(message, context, options) {
+    super('SHAPE_VERSION_UNSUPPORTED', message, context, options);
+    this.name = 'ShapeVersionError';
+  }
+}
+
+/**
+ * Thrown when a migration `requires` a background migration that has not
+ * completed yet — or whose collection still holds documents of the old shape.
+ * Nothing was run: `context.waitsFor` names the background migrations it
+ * waits for, with their status.
+ */
+class BackgroundPendingError extends MigronautError {
+  constructor(message, context, options) {
+    super('BACKGROUND_PENDING', message, context, options);
+    this.name = 'BackgroundPendingError';
+  }
+}
+
+/**
+ * Thrown when a background migration ended `failed` — a partition used up its
+ * slice failures, the document error budget ran out, or old-shape documents
+ * kept appearing for `maxPasses` passes. `context.migration` names it and
+ * `context.lastError` says what happened last.
+ */
+class BackgroundFailedError extends MigronautError {
+  constructor(message, context, options) {
+    super('BACKGROUND_FAILED', message, context, options);
+    this.name = 'BackgroundFailedError';
+  }
+}
+
+/**
+ * Thrown when a control action does not fit the background migration's state
+ * — pausing a completed one, resuming one that is not paused, retrying one
+ * that is still running. `context.status` is the state it found and
+ * `context.action` what was asked.
+ */
+class BackgroundConflictError extends MigronautError {
+  constructor(message, context, options) {
+    super('BACKGROUND_CONFLICT', message, context, options);
+    this.name = 'BackgroundConflictError';
+  }
+}
+
+/**
+ * Thrown by the dry-run sandbox when a step reaches for something it cannot
+ * run inside an always-aborted transaction — DDL, an admin command, another
+ * session, `$out`/`$merge`, a migronaut-internal collection. `context.method`
+ * names the call and `context.reason` the rule it broke. A dry run reports
+ * every refusal even when the step caught the error itself.
+ */
+class SandboxRefusedError extends MigronautError {
+  constructor(message, context, options) {
+    super('SANDBOX_REFUSED', message, context, options);
+    this.name = 'SandboxRefusedError';
+  }
+}
+
 module.exports = {
   MigronautError,
   LockAlreadyHeldError,
@@ -286,4 +368,10 @@ module.exports = {
   QueueJobInvalidError,
   QueueJobFailedError,
   ConvergeFailedError,
+  RevisionConflictError,
+  ShapeVersionError,
+  BackgroundPendingError,
+  BackgroundFailedError,
+  BackgroundConflictError,
+  SandboxRefusedError,
 };