@alexify/migronaut 2.2.0 → 2.4.0

package/src/core/bson-peer.js

@@ -0,0 +1,23 @@
+/**
+ * The driver's BSON, from the `mongodb` peer — loaded on first use, never at
+ * startup, and from this one module only (pinned by a test), so nothing else
+ * under src/ grows its own dependency on the driver's internals.
+ *
+ * What it is for: measuring a document the way the server will (a step's
+ * checkpoint must stay small) and writing one as relaxed EJSON for a dry
+ * run's report — both things only BSON itself can do exactly.
+ */
+let bson;
+
+function loadBson() {
+  bson ??= require('mongodb').BSON;
+  return bson;
+}
+
+/** The size of `value` as a BSON document, in bytes */
+const bsonSize = (value) => loadBson().calculateObjectSize(value);
+
+/** `value` as relaxed EJSON — plain JSON a person can read, types tagged where JSON has none */
+const toRelaxedEjson = (value) => loadBson().EJSON.serialize(value, { relaxed: true });
+
+module.exports = { bsonSize, loadBson, toRelaxedEjson };

package/src/core/changelog.js

@@ -109,6 +109,26 @@ class Changelog {
     return failed;
   }
 
+  /**
+   * Which of `names` are applied from a history that predates migronaut — a
+   * `baseline` or an import from migrate-mongo: never run here, so a
+   * background migration among them has no state, and counts as done.
+   */
+  async getAdoptedNames(db, names) {
+    if (names.length === 0) return [];
+    const docs = await this.#coll(db)
+      .find({
+        status: 'applied',
+        origin: { $in: ['baseline', 'migrate-mongo'] },
+        name: { $in: names },
+      })
+      .project({ name: 1, _id: 0 })
+      .toArray();
+    const adopted = [];
+    for (const doc of docs) adopted.push(doc.name);
+    return adopted;
+  }
+
   /** Return a single record by migration name, or null */
   async getByName(db, name) {
     return this.#coll(db).findOne({ name });
@@ -292,6 +312,18 @@ class Changelog {
     await this.#coll(db).bulkWrite(ops, { ordered: false });
   }
 
+  /**
+   * Re-pin an applied record to the file now on disk — `background repin`,
+   * so the strict drift check agrees with what is actually running.
+   */
+  async setChecksum(db, name, checksum) {
+    const result = await this.#coll(db).updateOne(
+      { name, status: 'applied' },
+      { $set: { checksum } },
+    );
+    return result.matchedCount === 1;
+  }
+
   /**
    * Mark a migration as reverted. Sets `status='reverted'` and `revertedAt=now`.
    * Never deletes the record — preserves the full audit history.

package/src/core/collections.js

@@ -8,6 +8,13 @@ const { errorText } = require('../utils/error.js');
 const { importUserFile, tsLoadMessageOrNull } = require('../utils/loader.js');
 const { indexIssues, normalizeDeclaredIndex, sameDeclaredSignature } = require('./index-spec.js');
 const { normalizeDeclaredSearchIndex, searchIndexIssues } = require('./search-index-spec.js');
+const { resolveVersioning, versioningIssues } = require('../versioning/config.js');
+const {
+  isVersioningIndexKey,
+  mergeVersioningValidator,
+  validatorVersioningIssues,
+  versioningIndex,
+} = require('./versioning-spec.js');
 
 /**
  * Declared collections: validating a definition, normalizing it for the
@@ -29,6 +36,7 @@ const DEFINITION_KEYS = [
   'validationLevel',
   'validationAction',
   'prune',
+  'versioning',
 ];
 const DEFINITION_KEY_SET = new Set(DEFINITION_KEYS);
 const VALIDATION_LEVELS = ['off', 'strict', 'moderate'];
@@ -108,6 +116,40 @@ function searchIndexListIssues(searchIndexes, base, issues) {
   }
 }
 
+/**
+ * Validate the `versioning` key and how it fits the rest of the definition:
+ * a declared validator must leave the managed fields to it, and a declared
+ * index must not duplicate the version index. Returns whether the definition
+ * is versioned (valid or not), so the validator checks below know a
+ * validator is coming.
+ */
+function versioningDefinitionIssues(definition, base, issues) {
+  if (definition.versioning === undefined) return false;
+  const path = join(base, 'versioning');
+  const found = versioningIssues(definition.versioning, path);
+  issues.push(...found);
+  if (found.length > 0) return true;
+  const versioning = resolveVersioning(definition.versioning);
+  if (isPlainObject(definition.validator) || definition.validator === null) {
+    for (const message of validatorVersioningIssues(definition.validator, versioning)) {
+      issues.push({ path: join(base, 'validator'), message });
+    }
+  }
+  if (versioning.index && Array.isArray(definition.indexes)) {
+    for (const [position, index] of definition.indexes.entries()) {
+      if (isPlainObject(index) && isVersioningIndexKey(index.key, versioning)) {
+        issues.push({
+          path: `${join(base, 'indexes')}[${position}]`,
+          message:
+            'is the version index, which versioning declares itself — remove it, or set ' +
+            'versioning.index: false',
+        });
+      }
+    }
+  }
+  return true;
+}
+
 /**
  * Validate one collection definition, returning `{ path, message }` issues
  * (empty when valid). `path` prefixes every issue (`collections[2]`, or
@@ -149,17 +191,19 @@ function definitionIssues(definition, { path: base, reserved = [], fallbackName
   if (
     definition.indexes === undefined &&
     definition.searchIndexes === undefined &&
-    definition.validator === undefined
+    definition.validator === undefined &&
+    definition.versioning === undefined
   ) {
     issues.push({
       path: self,
-      message: 'declares no indexes, searchIndexes or validator — nothing to manage',
+      message: 'declares no indexes, searchIndexes, validator or versioning — nothing to manage',
     });
   }
   if (definition.indexes !== undefined) indexListIssues(definition.indexes, base, issues);
   if (definition.searchIndexes !== undefined) {
     searchIndexListIssues(definition.searchIndexes, base, issues);
   }
+  const versioning = versioningDefinitionIssues(definition, base, issues);
 
   const { validator } = definition;
   if (validator !== undefined && validator !== null) {
@@ -170,7 +214,8 @@ function definitionIssues(definition, { path: base, reserved = [], fallbackName
       if (reason) report('validator', reason);
     }
   }
-  const hasValidator = isPlainObject(validator) && !isEmptyObject(validator);
+  // The versioning rules are a validator of their own.
+  const hasValidator = (isPlainObject(validator) && !isEmptyObject(validator)) || versioning;
   for (const [key, allowed] of [
     ['validationLevel', VALIDATION_LEVELS],
     ['validationAction', VALIDATION_ACTIONS],
@@ -222,13 +267,39 @@ function collectionsIssues(list, { reserved = [] } = {}) {
  * names, server-form keys, the spec to send), search indexes with their
  * default name and type, the validator cleaned for the wire.
  * `indexes`/`searchIndexes`/`validator` stay `undefined` when not managed.
+ * `versioning` is resolved and folded in: its rules merged into the
+ * validator, its index appended to `indexes` — with `indexesPartial` when it
+ * is the only index declared, so the others stay unmanaged.
  */
 function normalizeDefinition(definition, { name, source } = {}) {
   const { validator } = definition;
+  let wireValidator = validator === undefined || validator === null ? validator : toWire(validator);
+  let indexes = definition.indexes?.map((index) => normalizeDeclaredIndex(index));
+  let validationLevel = definition.validationLevel;
+  let versioning;
+  let indexesPartial = false;
+  if (definition.versioning !== undefined) {
+    // Folded into an ordinary validator and an ordinary index, so the planner
+    // needs to know nothing about versioning.
+    versioning = resolveVersioning(definition.versioning);
+    // A validator synthesized for versioning alone applies `moderate`: an
+    // update to a legacy document that predates the rules stays possible.
+    if (wireValidator === undefined || isEmptyObject(wireValidator)) validationLevel ??= 'moderate';
+    wireValidator = mergeVersioningValidator(wireValidator, versioning);
+    if (versioning.index) {
+      // Marked: on a sharded collection the planner swaps in the shard-key-prefixed form.
+      const index = { ...normalizeDeclaredIndex(versioningIndex(versioning)), versionIndex: true };
+      // Declaring the version index alone must not make every other index of
+      // the collection "undeclared" — and so a candidate for prune.
+      indexesPartial = indexes === undefined;
+      indexes = [...(indexes ?? []), index];
+    }
+  }
   return {
     name: definition.name ?? name,
     source,
-    indexes: definition.indexes?.map((index) => normalizeDeclaredIndex(index)),
+    indexes,
+    ...(indexesPartial ? { indexesPartial } : {}),
     ...(definition.searchIndexes !== undefined
       ? {
           searchIndexes: definition.searchIndexes.map((index) =>
@@ -236,14 +307,13 @@ function normalizeDefinition(definition, { name, source } = {}) {
           ),
         }
       : {}),
-    validator: validator === undefined || validator === null ? validator : toWire(validator),
-    ...(definition.validationLevel !== undefined
-      ? { validationLevel: definition.validationLevel }
-      : {}),
+    validator: wireValidator,
+    ...(validationLevel !== undefined ? { validationLevel } : {}),
     ...(definition.validationAction !== undefined
       ? { validationAction: definition.validationAction }
       : {}),
     ...(definition.prune !== undefined ? { prune: definition.prune } : {}),
+    ...(versioning !== undefined ? { versioning } : {}),
   };
 }
 

package/src/core/config.js

@@ -38,6 +38,11 @@ const DEFAULT_CONFIG = {
   onSearchUnavailable: 'fail',
   waitForSearchIndexes: false,
   searchIndexWaitTimeoutMs: 600_000,
+  backgroundCollection: '_migronaut_background',
+  backgroundInline: false,
+  backgroundOnDrift: 'reopen',
+  backgroundDrift: 'poll',
+  backgroundShardAware: 'auto',
 };
 
 /** Candidate config file names, checked in priority order within the cwd */
@@ -47,6 +52,26 @@ const isNonEmptyString = (value) => typeof value === 'string' && value.length >
 const isBoolean = (value) => typeof value === 'boolean';
 const isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
 const isExtension = (value) => value === 'ts' || value === 'js';
+const oneOf = (values) => (value) => values.includes(value);
+const quoted = (values) => values.map((value) => `'${value}'`).join(', ');
+
+const ON_DRIFT = ['reopen', 'report'];
+const DRIFT_MODES = ['poll', 'stream', 'both'];
+const SHARD_AWARE = ['auto', 'off'];
+
+/**
+ * The collections a background migration keeps its state in: the state
+ * documents themselves, their partitions and the drift watcher's resume
+ * tokens — the last two named after the first, so one setting moves all
+ * three (and a test of "must differ" covers them together).
+ */
+function backgroundCollectionNames(backgroundCollection) {
+  return {
+    state: backgroundCollection,
+    partitions: `${backgroundCollection}_partitions`,
+    watch: `${backgroundCollection}_watch`,
+  };
+}
 
 function isStringList(value) {
   if (!Array.isArray(value) || value.length === 0) return false;
@@ -169,6 +194,31 @@ const CONFIG_KEYS = [
     message: 'must be a positive integer',
     optional: true,
   },
+  {
+    path: 'backgroundCollection',
+    check: isCollectionName,
+    message: "must be a valid collection name (no '$'/NUL, not system.*)",
+    optional: true,
+  },
+  { path: 'backgroundInline', check: isBoolean, message: 'must be a boolean', optional: true },
+  {
+    path: 'backgroundOnDrift',
+    check: oneOf(ON_DRIFT),
+    message: `must be ${quoted(ON_DRIFT)}`,
+    optional: true,
+  },
+  {
+    path: 'backgroundDrift',
+    check: oneOf(DRIFT_MODES),
+    message: `must be ${quoted(DRIFT_MODES)}`,
+    optional: true,
+  },
+  {
+    path: 'backgroundShardAware',
+    check: oneOf(SHARD_AWARE),
+    message: `must be ${quoted(SHARD_AWARE)}`,
+    optional: true,
+  },
 ];
 
 /**
@@ -220,26 +270,51 @@ function validateConfig(config, options = {}) {
   // pure data, so this costs nothing. Definition *files* are loaded only when
   // a converge runs: importing them here would make one broken file block
   // every command, an emergency `down` included.
-  // Three bookkeeping collections, three jobs: sharing one would mix records.
-  const bookkeeping = ['migrationsCollection', 'lockCollection', 'convergeLogCollection'];
-  for (const [position, key] of bookkeeping.entries()) {
-    for (const other of bookkeeping.slice(0, position)) {
-      if (config[key] !== undefined && config[key] === config[other]) {
-        issues.push({ path: key, message: `must differ from ${other}` });
-      }
+  // Every bookkeeping collection has one job: sharing one would mix records.
+  const bookkeeping = bookkeepingCollections(config);
+  for (let position = 1; position < bookkeeping.length; position++) {
+    const [key, name, what] = bookkeeping[position];
+    if (name === undefined) continue;
+    for (let earlier = 0; earlier < position; earlier++) {
+      const [otherKey, otherName, otherWhat] = bookkeeping[earlier];
+      if (name !== otherName) continue;
+      issues.push({
+        path: key,
+        message: `${what ? `${what} (${name}) ` : ''}must differ from ${otherWhat ? `${otherKey}'s ${otherWhat}` : otherKey}`,
+      });
+      break;
     }
   }
   if (Array.isArray(config.collections)) {
-    const reserved = [
-      config.migrationsCollection,
-      config.lockCollection,
-      config.convergeLogCollection,
-    ];
+    const reserved = [];
+    for (const [, name] of bookkeeping) if (name !== undefined) reserved.push(name);
     for (const issue of collectionsIssues(config.collections, { reserved })) issues.push(issue);
   }
   return issues;
 }
 
+/**
+ * Every collection migronaut keeps records in, as `[configKey, name, what?]`
+ * — `what` names a collection derived from the key (the background
+ * partitions and watch collections).
+ */
+function bookkeepingCollections(config) {
+  const entries = [
+    ['migrationsCollection', config.migrationsCollection],
+    ['lockCollection', config.lockCollection],
+    ['convergeLogCollection', config.convergeLogCollection],
+  ];
+  if (typeof config.backgroundCollection === 'string') {
+    const names = backgroundCollectionNames(config.backgroundCollection);
+    entries.push(
+      ['backgroundCollection', names.state],
+      ['backgroundCollection', names.partitions, 'partitions collection'],
+      ['backgroundCollection', names.watch, 'watch collection'],
+    );
+  }
+  return entries;
+}
+
 const TRUE_BOOLEAN_STRINGS = new Set(['true', '1', 'yes']);
 const FALSE_BOOLEAN_STRINGS = new Set(['false', '0', 'no']);
 
@@ -361,6 +436,19 @@ const ENV_KEYS = [
     path: 'searchIndexWaitTimeoutMs',
     parse: parsePositiveInteger,
   },
+  { env: 'MIGRONAUT_BACKGROUND_COLLECTION', path: 'backgroundCollection', parse: parseString },
+  { env: 'MIGRONAUT_BACKGROUND_INLINE', path: 'backgroundInline', parse: parseBoolean },
+  {
+    env: 'MIGRONAUT_BACKGROUND_ON_DRIFT',
+    path: 'backgroundOnDrift',
+    parse: parseEnum(ON_DRIFT),
+  },
+  { env: 'MIGRONAUT_BACKGROUND_DRIFT', path: 'backgroundDrift', parse: parseEnum(DRIFT_MODES) },
+  {
+    env: 'MIGRONAUT_BACKGROUND_SHARD_AWARE',
+    path: 'backgroundShardAware',
+    parse: parseEnum(SHARD_AWARE),
+  },
 ];
 
 /** Build a partial config from the MIGRONAUT_* environment variables */
@@ -599,6 +687,8 @@ module.exports = {
   CONFIG_KEYS,
   DEFAULT_CONFIG,
   ENV_KEYS,
+  backgroundCollectionNames,
+  bookkeepingCollections,
   // Re-exported from utils/collection-name.js, where it moved so that
   // core/collections.js can use it without a require cycle through here.
   isCollectionName,

package/src/core/converge-plan.js

@@ -1,5 +1,12 @@
 const { deepEqual } = require('../utils/canonical.js');
-const { compareIndex, normalizeLiveIndex, restoreSpec, sameSignature } = require('./index-spec.js');
+const { shardedVersionIndexKey, versionFloorConflict } = require('./versioning-spec.js');
+const {
+  compareIndex,
+  normalizeDeclaredIndex,
+  normalizeLiveIndex,
+  restoreSpec,
+  sameSignature,
+} = require('./index-spec.js');
 const {
   compareSearchIndex,
   isBeingRemoved,
@@ -179,7 +186,50 @@ function joinReasons(first, second) {
   return first ? `${first}; ${second}` : second;
 }
 
-function planIndexes(declaredIndexes, live, { prune, rebuildUnique, capabilities }, row, steps) {
+/** Why the ordinary version index stays on a sharded collection whose version index replaced it */
+const DISPLACED_REASON =
+  'replaced by the shard-key-prefixed version index — drop it once nothing hints it ' +
+  '(prune does, when the indexes are declared)';
+
+/**
+ * The declared indexes as they apply to this live collection: on a sharded
+ * one, the version index takes the shard key between the version field and
+ * `_id` (versioning-spec.js). `displaced` names the ordinary version index it
+ * replaces, when the two differ.
+ */
+function indexesFor(definition, live) {
+  const indexes = definition.indexes;
+  if (indexes === undefined || !definition.versioning || !live.shardKey) return { indexes };
+  const sharded = normalizeDeclaredIndex({
+    key: shardedVersionIndexKey(definition.versioning, live.shardKey),
+  });
+  const result = [];
+  let displaced;
+  for (const index of indexes) {
+    if (index.versionIndex === true && index.name !== sharded.name) {
+      displaced = index.name;
+      result.push({ ...sharded, versionIndex: true });
+    } else {
+      result.push(index);
+    }
+  }
+  return { indexes: result, displaced };
+}
+
+/**
+ * Plan the declared indexes of one collection against its live ones. With
+ * `partial` (only the version index of `versioning` is declared, not the
+ * collection's own list) the other live indexes are not managed at all: never
+ * listed, never dropped — prune does not reach them.
+ */
+function planIndexes(
+  declaredIndexes,
+  live,
+  { prune: pruneOption, rebuildUnique, capabilities, partial = false, displaced },
+  row,
+  steps,
+) {
+  const prune = pruneOption && !partial;
   const defaultCollation = live.options?.collation;
   const liveIndexes = [];
   for (const raw of live.indexes) {
@@ -360,7 +410,22 @@ function planIndexes(declaredIndexes, live, { prune, rebuildUnique, capabilities
   }
   if (group.actions.length > 0) steps.push(group);
 
+  // The ordinary version index a sharded one replaced: kept, and said so —
+  // a background migration may still be hinting it.
+  const old = displaced !== undefined ? byName.get(displaced) : undefined;
+  if (old !== undefined && !declaredNames.has(displaced) && !prune) {
+    consumed.add(displaced);
+    row({
+      target: 'index',
+      name: displaced,
+      action: 'keep',
+      reason: DISPLACED_REASON,
+      from: indexValue(old.raw),
+    });
+  }
+
   // Last, so an index is only ever removed once everything declared exists.
+  if (partial) return;
   for (const index of liveIndexes) {
     if (consumed.has(index.name) || declaredNames.has(index.name)) continue;
     if (prune && backsShardKey(index, live.shardKey)) {
@@ -554,8 +619,8 @@ function planSearchIndexes(declaredList, live, { prune, search }, row, submit, d
 /**
  * Plan one collection. `definition` is a normalized definition (see
  * collections.js); `live` is `{ exists, type?, options?, indexes,
- * searchIndexes? }` as converge.js reads it. Returns `{ name, actions, steps }`:
- * `actions` are the result rows (status `'planned'`), `steps` the operations
+ * searchIndexes?, shardKey?, versionFloor? }` as converge.js reads it.
+ * Returns `{ name, actions, steps }`: `actions` are the result rows (status `'planned'`), `steps` the operations
  * that carry them out, in execution order, each pointing at the rows it
  * settles. `search` is `{ available, onUnavailable }` — whether the server has
  * Atlas Search, and what a declared search index becomes when it does not.
@@ -615,7 +680,7 @@ function planCollectionSteps(
   }
 
   const desired = desiredValidator(definition);
-  const declaredIndexes = definition.indexes;
+  const { indexes: declaredIndexes, displaced } = indexesFor(definition, live);
   const declaredSearch = definition.searchIndexes;
   const indexSteps = [];
   const searchSubmit = [];
@@ -655,10 +720,24 @@ function planCollectionSteps(
   }
 
   if (desired !== undefined) {
-    planValidator(name, desired, liveValidator(live.options), row, steps);
+    // Raising versioning.min over documents still below it: refused, so the
+    // whole run stops before its first write (see versionFloorToCheck).
+    const refused = versionFloorConflict(live.versionFloor);
+    if (refused) {
+      row({ target: 'validator', name, action: 'conflict', reason: refused, to: desired });
+    } else {
+      planValidator(name, desired, liveValidator(live.options), row, steps);
+    }
   }
   if (declaredIndexes !== undefined) {
-    planIndexes(declaredIndexes, live, { prune, rebuildUnique, capabilities }, row, indexSteps);
+    const partial = definition.indexesPartial === true;
+    planIndexes(
+      declaredIndexes,
+      live,
+      { prune, rebuildUnique, capabilities, partial, displaced },
+      row,
+      indexSteps,
+    );
   }
   if (declaredSearch !== undefined) {
     planSearchIndexes(declaredSearch, live, { prune, search }, row, searchSubmit, searchDrops);

package/src/core/converge.js

@@ -29,6 +29,8 @@ const {
   warnIgnored,
 } = require('./converge-search-run.js');
 const { inPlaceCapabilities } = require('./index-spec.js');
+const { belowVersionFilter } = require('../versioning/document.js');
+const { isVersioningIndexKey, versionFloorToCheck } = require('./versioning-spec.js');
 const {
   INDEX_NOT_FOUND,
   NAMESPACE_NOT_FOUND,
@@ -74,6 +76,53 @@ const HINTS = {
     'first (the index was left as it was)',
 };
 
+/**
+ * How long the version floor probe may scan. With the version index it reads
+ * one key; without it (the index is created by the same converge that raises
+ * the floor) it may have to scan the collection — bounded, and a timeout
+ * refuses the raise rather than risk it.
+ */
+const FLOOR_PROBE_TIMEOUT_MS = 60_000;
+
+/**
+ * Before converge raises `versioning.min`: is any document still below it?
+ * Sets `live.versionFloor` to `{ min, below }` (`below: 'unknown'` with
+ * `error` when the probe failed) for the planner to refuse the raise on. One
+ * `findOne` with only `_id` projected — nothing about the document is kept.
+ */
+async function probeVersionFloor(db, definition, live) {
+  const min = versionFloorToCheck(definition, live);
+  if (min === null) return;
+  const { versioning } = definition;
+  let hint;
+  for (const index of live.indexes) {
+    if (isVersioningIndexKey(index.key, versioning)) {
+      hint = index.name;
+      break;
+    }
+  }
+  try {
+    const found = await db
+      .collection(definition.name)
+      .findOne(belowVersionFilter(versioning, min), {
+        projection: { _id: 1 },
+        maxTimeMS: FLOOR_PROBE_TIMEOUT_MS,
+        ...(hint !== undefined ? { hint } : {}),
+        ...READ_OPTIONS,
+      });
+    live.versionFloor = { min, below: found !== null };
+  } catch (error) {
+    live.versionFloor = { min, below: 'unknown', error: errorText(error) };
+  }
+}
+
+/** Probe every versioned collection whose floor would rise — a few at a time */
+async function probeVersionFloors(db, definitions, live) {
+  await mapLimit([...definitions.keys()], READ_CONCURRENCY, (position) =>
+    probeVersionFloor(db, definitions[position], live[position]),
+  );
+}
+
 /** Shard key of each named collection, behind a mongos — when `config.collections` may be read */
 async function readShardKeys(deps, names) {
   const keys = new Map();
@@ -577,6 +626,7 @@ async function readAndPlan(deps, options) {
     }
   }
   if (search.declared) await readSearch(deps, server, definitions, live, search);
+  await probeVersionFloors(db, definitions, live);
   const plans = new Array(definitions.length);
   const ignored = [];
   for (const [position, definition] of definitions.entries()) {
@@ -636,6 +686,7 @@ async function readFresh(run, position, phase) {
   ) {
     fresh.searchIndexes = await readSearchIndexes(deps, definition.name, phase);
   }
+  await probeVersionFloor(deps.db, definition, fresh);
   return fresh;
 }
 
@@ -840,6 +891,42 @@ async function applyCollection(deps, plan, result, signal, search) {
   return kept;
 }
 
+/**
+ * After a run raised `versioning.min`: old-shape documents written while it
+ * ran (an old pod still deploying) got past the probe. Converge cannot undo
+ * the validator, so it says so — those documents now fail validation on
+ * their next strict write, and a background migration has to pick them up.
+ */
+async function warnFloorBreach(run, position) {
+  const { deps, definitions, live, result } = run;
+  const floor = live[position].versionFloor;
+  if (floor?.below !== false) return;
+  const raised = result.collections[position].actions.some(
+    (action) => action.target === 'validator' && action.status === 'applied',
+  );
+  if (!raised) return;
+  const definition = definitions[position];
+  let found;
+  try {
+    found = await deps.db
+      .collection(definition.name)
+      .findOne(belowVersionFilter(definition.versioning, floor.min), {
+        projection: { _id: 1 },
+        maxTimeMS: FLOOR_PROBE_TIMEOUT_MS,
+        ...READ_OPTIONS,
+      });
+  } catch {
+    return;
+  }
+  if (found === null) return;
+  deps.logger.warn(
+    `⚠ ${definition.name}: documents below version ${floor.min} were written while converge ` +
+      'raised versioning.min — an old release is still writing; run the background migration ' +
+      'again once it is gone',
+    deps.fields({ collection: definition.name, min: floor.min }),
+  );
+}
+
 /**
  * The verify phase — the fixed-point check: what was just applied must now
  * compare as unchanged. Anything that does not would be "changed" again on
@@ -864,6 +951,7 @@ async function verifyFixedPoint(run, position, kept, signal) {
     after = planFor(definition, await readFresh(run, position, 'apply'));
   }
   refreshBuilds(rows, after.actions);
+  await warnFloorBreach(run, position);
   for (const action of after.actions) {
     if (!CHANGE_ACTIONS.has(action.action)) continue;
     if (action.action === 'drop' && kept.has(action.name)) continue;