@alexify/migronaut 1.0.0

package/src/core/config.js

@@ -0,0 +1,479 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { pathToFileURL } = require('node:url');
+const { ConfigInvalidError } = require('../errors/index.js');
+const { applyEnvFile } = require('../utils/env.js');
+const { errorText } = require('../utils/error.js');
+const { resolveLogger } = require('../utils/logger.js');
+const { redactDeep } = require('../utils/redact.js');
+
+/** Default values applied when no flag, env var, or config-file value is present */
+const DEFAULT_CONFIG = {
+  migrationsDir: './migrations',
+  migrationsCollection: '_migronaut_migrations',
+  lockCollection: '_migronaut_locks',
+  lockTTLSeconds: 60,
+  strict: false,
+  useTransaction: false,
+  fileExtensions: ['.ts', '.js'],
+  createExtension: 'js',
+  sequential: false,
+};
+
+/** Candidate config file names, checked in priority order within the cwd */
+const CONFIG_FILE_NAMES = ['migronaut.config.ts', 'migronaut.config.js', 'migronaut.config.json'];
+
+const isNonEmptyString = (value) => typeof value === 'string' && value.length > 0;
+const isBoolean = (value) => typeof value === 'boolean';
+const isPositiveInteger = (value) => Number.isInteger(value) && value > 0;
+const isExtension = (value) => value === 'ts' || value === 'js';
+
+/**
+ * Collection names we accept for the changelog/lock collections and
+ * `import --from/--to`: non-empty, no `$` or NUL (invalid server-side), and
+ * outside the reserved `system.` namespace — so a flag can never point a
+ * read or write at a system collection.
+ */
+function isCollectionName(value) {
+  return (
+    isNonEmptyString(value) &&
+    !value.includes('$') &&
+    !value.includes('\0') &&
+    !value.startsWith('system.')
+  );
+}
+function isStringList(value) {
+  if (!Array.isArray(value) || value.length === 0) return false;
+  for (const item of value) {
+    if (!isNonEmptyString(item)) return false;
+  }
+  return true;
+}
+
+/**
+ * Validation spec for every checked config key: predicate + failure message.
+ * `mongoose`, `hooks`, `logger` and `client` are deliberately unchecked —
+ * they hold live instances the validator has nothing to say about. Unknown
+ * keys are allowed, matching the previous zod (non-strict object) behavior.
+ */
+const CONFIG_KEYS = [
+  { path: 'uri', check: isNonEmptyString, message: 'uri is required' },
+  { path: 'dbName', check: isNonEmptyString, message: 'dbName is required' },
+  { path: 'migrationsDir', check: isNonEmptyString, message: 'must be a non-empty string' },
+  {
+    path: 'migrationsCollection',
+    check: isCollectionName,
+    message: "must be a valid collection name (no '$'/NUL, not system.*)",
+  },
+  {
+    path: 'lockCollection',
+    check: isCollectionName,
+    message: "must be a valid collection name (no '$'/NUL, not system.*)",
+  },
+  { path: 'lockTTLSeconds', check: isPositiveInteger, message: 'must be a positive integer' },
+  { path: 'strict', check: isBoolean, message: 'must be a boolean' },
+  { path: 'useTransaction', check: isBoolean, message: 'must be a boolean' },
+  {
+    path: 'fileExtensions',
+    check: isStringList,
+    message: 'must be a non-empty array of non-empty strings',
+  },
+  { path: 'createExtension', check: isExtension, message: "must be 'ts' or 'js'" },
+  { path: 'sequential', check: isBoolean, message: 'must be a boolean' },
+  {
+    path: 'templatePath',
+    check: isNonEmptyString,
+    message: 'must be a non-empty string',
+    optional: true,
+  },
+  {
+    path: 'environment',
+    check: isNonEmptyString,
+    message: 'must be a non-empty string',
+    optional: true,
+  },
+  {
+    path: 'onLockLost',
+    check: (value) => value === 'abort' || value === 'warn',
+    message: "must be 'abort' or 'warn'",
+    optional: true,
+  },
+  {
+    path: 'envFile',
+    check: (value) => value === false || isNonEmptyString(value),
+    message: 'must be a non-empty string or false',
+    optional: true,
+  },
+  { path: 'ensureIndexes', check: isBoolean, message: 'must be a boolean', optional: true },
+  {
+    path: 'clientOptions',
+    check: (value) => typeof value === 'object' && value !== null && !Array.isArray(value),
+    message: 'must be an object',
+    optional: true,
+  },
+  {
+    path: 'timeoutMs',
+    check: isPositiveInteger,
+    message: 'must be a positive integer',
+    optional: true,
+  },
+  { path: 'reloadMigrations', check: isBoolean, message: 'must be a boolean', optional: true },
+];
+
+/**
+ * Every key the merged config legitimately carries: the validated ones plus
+ * the deliberately-unchecked live instances. Used only to *mention* typos
+ * (`migrationsDirectory`, `useTransactions`) at debug level — unknown keys
+ * stay allowed, matching the documented non-strict contract.
+ */
+const KNOWN_CONFIG_KEYS = new Set(['logger', 'hooks', 'mongoose', 'client']);
+for (const spec of CONFIG_KEYS) KNOWN_CONFIG_KEYS.add(spec.path);
+
+/**
+ * Validate the merged config, returning a list of `{ path, message }` issues
+ * (empty when valid). With `requireDb: false`, empty `uri`/`dbName` strings
+ * are allowed — for commands that never touch the database (`init`, `create`).
+ */
+function validateConfig(config, options = {}) {
+  const requireDb = options.requireDb ?? true;
+  // An injected client already carries the connection, so a `uri` would be
+  // ignored — requiring one would only be busywork.
+  const hasClient = typeof config.client === 'object' && config.client !== null;
+  const issues = [];
+  for (const spec of CONFIG_KEYS) {
+    const value = config[spec.path];
+    if (spec.optional && value === undefined) continue;
+    if (hasClient && spec.path === 'uri') continue;
+    if (!requireDb && (spec.path === 'uri' || spec.path === 'dbName')) {
+      if (typeof value !== 'string') issues.push({ path: spec.path, message: 'must be a string' });
+      continue;
+    }
+    if (!spec.check(value)) issues.push({ path: spec.path, message: spec.message });
+  }
+  return issues;
+}
+
+const TRUE_BOOLEAN_STRINGS = new Set(['true', '1', 'yes']);
+const FALSE_BOOLEAN_STRINGS = new Set(['false', '0', 'no']);
+
+/**
+ * Parse a string into a boolean. Unrecognized values throw instead of silently
+ * becoming false — a typo like MIGRONAUT_STRICT=on must never disable a safety
+ * setting (fail closed).
+ */
+function parseBoolean(value, name) {
+  const normalized = value.trim().toLowerCase();
+  if (TRUE_BOOLEAN_STRINGS.has(normalized)) return true;
+  if (FALSE_BOOLEAN_STRINGS.has(normalized)) return false;
+  throw new ConfigInvalidError(`${name} must be 'true'/'1'/'yes' or 'false'/'0'/'no'`, {
+    name,
+    value,
+  });
+}
+
+/**
+ * Keys never copied from parsed input: JSON.parse creates `__proto__` as an own
+ * enumerable property, so merging it would poison the prototype of the merged
+ * config and let a JSON config file override values it never declared.
+ */
+const UNSAFE_MERGE_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/** Copy only the defined keys from `source` onto `target`, mutating and returning target */
+function mergeDefined(target, source) {
+  for (const key of Object.keys(source)) {
+    if (UNSAFE_MERGE_KEYS.has(key)) continue;
+    const value = source[key];
+    if (value !== undefined) {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+/**
+ * Parse a string into a positive integer, failing closed like `parseBoolean`.
+ * A bare `Number()` turns a typo into `NaN`, which surfaces as a generic
+ * validateConfig issue that never names the variable the user actually set.
+ */
+function parsePositiveInteger(value, name) {
+  const parsed = Number(value.trim());
+  if (!isPositiveInteger(parsed)) {
+    throw new ConfigInvalidError(`${name} must be a positive integer`, { name, value });
+  }
+  return parsed;
+}
+
+/** Parse one of a fixed set of string values, failing closed on anything else */
+function parseEnum(allowed) {
+  const values = new Set(allowed);
+  const list = allowed.map((item) => `'${item}'`).join(' or ');
+  return (value, name) => {
+    const normalized = value.trim();
+    if (!values.has(normalized)) {
+      throw new ConfigInvalidError(`${name} must be ${list}`, { name, value });
+    }
+    return normalized;
+  };
+}
+
+const parseString = (value) => value;
+
+/**
+ * Every environment variable that maps onto a config key: the variable name,
+ * the config path it feeds, and how its string is parsed. Table-driven for the
+ * same reason CONFIG_KEYS is — a hand-written `if` chain silently drifts from
+ * the key list it is supposed to mirror (MIGRONAUT_ENVIRONMENT was missing from
+ * the tests' save/restore list for exactly that reason).
+ *
+ * Every *scalar* config option has an entry here, which is what makes the
+ * documented "a config file is never required" promise literally true. Options
+ * holding non-scalars — `fileExtensions`, `clientOptions`, `client`, `mongoose`,
+ * `hooks`, `logger` — are config-file/API only; an env var cannot express them.
+ *
+ * MIGRONAUT_ENV_FILE is deliberately absent: it selects which .env file to load,
+ * so it has to be read before this table can run (see loadConfig).
+ */
+const ENV_KEYS = [
+  { env: 'MIGRONAUT_URI', path: 'uri', parse: parseString },
+  { env: 'MIGRONAUT_DB', path: 'dbName', parse: parseString },
+  { env: 'MIGRONAUT_MIGRATIONS_DIR', path: 'migrationsDir', parse: parseString },
+  { env: 'MIGRONAUT_COLLECTION', path: 'migrationsCollection', parse: parseString },
+  { env: 'MIGRONAUT_LOCK_COLLECTION', path: 'lockCollection', parse: parseString },
+  { env: 'MIGRONAUT_LOCK_TTL', path: 'lockTTLSeconds', parse: parsePositiveInteger },
+  { env: 'MIGRONAUT_STRICT', path: 'strict', parse: parseBoolean },
+  { env: 'MIGRONAUT_USE_TRANSACTION', path: 'useTransaction', parse: parseBoolean },
+  { env: 'MIGRONAUT_SEQUENTIAL', path: 'sequential', parse: parseBoolean },
+  { env: 'MIGRONAUT_CREATE_EXTENSION', path: 'createExtension', parse: parseEnum(['ts', 'js']) },
+  { env: 'MIGRONAUT_ENVIRONMENT', path: 'environment', parse: parseString },
+  { env: 'MIGRONAUT_TEMPLATE_PATH', path: 'templatePath', parse: parseString },
+  { env: 'MIGRONAUT_TIMEOUT_MS', path: 'timeoutMs', parse: parsePositiveInteger },
+  { env: 'MIGRONAUT_ON_LOCK_LOST', path: 'onLockLost', parse: parseEnum(['abort', 'warn']) },
+  { env: 'MIGRONAUT_ENSURE_INDEXES', path: 'ensureIndexes', parse: parseBoolean },
+  { env: 'MIGRONAUT_RELOAD_MIGRATIONS', path: 'reloadMigrations', parse: parseBoolean },
+];
+
+/** Build a partial config from the MIGRONAUT_* environment variables */
+function readEnvConfig(env = process.env) {
+  const result = {};
+  for (const spec of ENV_KEYS) {
+    const value = env[spec.env];
+    if (value === undefined) continue;
+    result[spec.path] = spec.parse(value, spec.env);
+  }
+  return result;
+}
+
+/** Returns true when `filepath` exists on disk */
+async function pathExists(filepath) {
+  try {
+    await fs.access(filepath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate a config file in `cwd`, returning its absolute path or null.
+ * Candidates are checked concurrently, then the first one that exists (in
+ * `CONFIG_FILE_NAMES` priority order) wins — preserves the original
+ * short-circuit priority without serializing the stat calls.
+ */
+async function discoverConfigFile(cwd) {
+  const candidates = [];
+  for (const name of CONFIG_FILE_NAMES) candidates.push(path.join(cwd, name));
+  const checks = [];
+  for (const candidate of candidates) checks.push(pathExists(candidate));
+  const found = await Promise.all(checks);
+  for (let i = 0; i < candidates.length; i++) {
+    if (found[i]) return candidates[i];
+  }
+  return null;
+}
+
+/**
+ * Load and return the config object exported by a config file.
+ *
+ * A `.ts`/`.js` config may export either a plain object or a (sync or async)
+ * factory function — the factory is invoked and awaited here, which is what
+ * lets users fetch values from a secret manager. A factory that throws is
+ * surfaced as a ConfigInvalidError. JSON configs are always objects.
+ */
+async function loadConfigFile(filepath, lenient = false) {
+  if (filepath.endsWith('.json')) {
+    const raw = await fs.readFile(filepath, 'utf8');
+    try {
+      return JSON.parse(raw);
+    } catch (error) {
+      // A bare SyntaxError has no typed code, which breaks the CLI's exit-code
+      // mapping and `--json` error shape.
+      throw new ConfigInvalidError(
+        'Config file is not valid JSON',
+        { path: filepath, cause: errorText(error) },
+        { cause: error },
+      );
+    }
+  }
+  let mod;
+  try {
+    mod = await import(pathToFileURL(filepath).href);
+  } catch (error) {
+    // Module-evaluation failures (syntax error, a throwing top-level statement)
+    // get the same treatment as a throwing factory below — including the
+    // lenient degradation for commands that never touch the database.
+    if (lenient) return null;
+    throw new ConfigInvalidError(
+      'Config file failed to load',
+      { path: filepath, cause: errorText(error) },
+      { cause: error },
+    );
+  }
+  const exported = mod.default ?? mod;
+
+  if (typeof exported === 'function') {
+    try {
+      return await exported();
+    } catch (error) {
+      if (lenient) {
+        // The caller does not need the connection (e.g. `create`), so a failing
+        // secret-manager round trip degrades to "no values from this file"
+        // rather than stopping an otherwise offline command.
+        return null;
+      }
+      throw new ConfigInvalidError(
+        'Config factory function failed to resolve',
+        { path: filepath, cause: errorText(error) },
+        { cause: error },
+      );
+    }
+  }
+  return exported;
+}
+
+/**
+ * Resolve the final MigronautConfig by merging, in priority order:
+ * CLI flags > environment variables > config file > defaults.
+ *
+ * With `lenient: true`, a config file whose exported factory throws is skipped
+ * with a warning instead of aborting — for commands that never open a
+ * connection (`create`), which otherwise fail because a secret manager is
+ * unreachable.
+ *
+ * Throws ConfigInvalidError when the merged result fails validation.
+ */
+async function loadConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  // The CLI's console logger, used only when neither flags nor the config file
+  // supply one — so this module's own lines honor `--verbose`/`--quiet` while
+  // a user's configured logger still wins.
+  const effectiveLogger = (value) =>
+    resolveLogger(value !== undefined ? value : options.fallbackLogger);
+
+  // Resolved before the merge, because loading the .env file is what supplies
+  // the MIGRONAUT_* variables the merge then reads. `false` opts out entirely —
+  // a stray .env silently outranking a committed config is a nasty surprise.
+  // This is why MIGRONAUT_ENV_FILE is read here rather than from ENV_KEYS: it
+  // has to resolve before the table that reads everything else can run.
+  const envFile = options.flags?.envFile ?? process.env.MIGRONAUT_ENV_FILE ?? '.env';
+  if (envFile !== false) {
+    // Checked here, before validateConfig runs, because path.resolve on a
+    // non-string throws a raw TypeError instead of the ConfigInvalidError the
+    // config contract promises.
+    if (!isNonEmptyString(envFile)) {
+      throw new ConfigInvalidError('Invalid configuration', {
+        issues: [{ path: 'envFile', message: 'must be a non-empty string or false' }],
+      });
+    }
+    await applyEnvFile(path.resolve(cwd, envFile));
+  }
+
+  const merged = { ...DEFAULT_CONFIG };
+
+  const configFilePath = options.configPath
+    ? path.resolve(cwd, options.configPath)
+    : await discoverConfigFile(cwd);
+
+  if (configFilePath) {
+    if (!(await pathExists(configFilePath))) {
+      throw new ConfigInvalidError('Config file not found', { path: configFilePath });
+    }
+    const fileConfig = await loadConfigFile(configFilePath, options.lenient ?? false);
+    // null means a lenient run whose factory failed — nothing usable from the
+    // file, so fall through to env vars, flags and defaults.
+    if (fileConfig === null) {
+      effectiveLogger(options.flags?.logger).warn(
+        `⚠ Could not resolve ${path.basename(configFilePath)} — continuing without it`,
+      );
+    } else {
+      mergeDefined(merged, fileConfig);
+    }
+  }
+
+  mergeDefined(merged, readEnvConfig());
+
+  if (options.flags) {
+    mergeDefined(merged, options.flags);
+  }
+
+  const requireDb = options.requireDb ?? true;
+  if (!requireDb) {
+    if (merged.uri === undefined) merged.uri = '';
+    if (merged.dbName === undefined) merged.dbName = '';
+  }
+
+  const issues = validateConfig(merged, { requireDb });
+  if (issues.length > 0) {
+    throw new ConfigInvalidError('Invalid configuration', { issues });
+  }
+
+  const config = merged;
+
+  // A typo'd key (`migrationsDirectory`, `useTransactions`) validates fine and
+  // then silently does nothing; a debug mention is the cheapest way to notice.
+  // The array is only allocated when a stray key actually exists.
+  let unknown;
+  for (const key in config) {
+    if (!KNOWN_CONFIG_KEYS.has(key)) (unknown ??= []).push(key);
+  }
+  if (unknown) {
+    effectiveLogger(config.logger).debug(
+      `Unrecognized config key(s), ignored: ${unknown.join(', ')}`,
+    );
+  }
+
+  if (config.logger && configFilePath) {
+    // resolveLogger, not a direct call — config.logger may be a pino instance.
+    effectiveLogger(config.logger).debug(`Loaded config from ${path.basename(configFilePath)}`);
+  }
+
+  // "Which config did it actually pick up?" — the merged result, once, at
+  // debug level. Live instances (client, mongoose, hooks, logger) are elided:
+  // they are not serializable and redactDeep rightly refuses to clone them.
+  {
+    const { client, mongoose, hooks, logger, ...rest } = config;
+    effectiveLogger(config.logger).debug(
+      `Resolved config (source: ${configFilePath ? path.basename(configFilePath) : 'env/flags/defaults'})`,
+      redactDeep({
+        ...rest,
+        ...(client ? { client: '[injected]' } : {}),
+        ...(mongoose ? { mongoose: '[injected]' } : {}),
+        ...(hooks ? { hooks: Object.keys(hooks) } : {}),
+        ...(logger !== undefined ? { logger: logger === null ? null : '[injected]' } : {}),
+      }),
+    );
+  }
+
+  return config;
+}
+
+// CONFIG_KEYS and ENV_KEYS are exported for the unit test that pins the two
+// tables against each other — internal to the config layer, not part of the
+// package's public surface (index.d.ts describes neither).
+module.exports = {
+  CONFIG_KEYS,
+  DEFAULT_CONFIG,
+  ENV_KEYS,
+  isCollectionName,
+  loadConfig,
+  validateConfig,
+};

package/src/core/context.js

@@ -0,0 +1,16 @@
+/**
+ * Build the MigrationContext passed into every migration function.
+ *
+ * `signal` is the run's abort signal: it fires when the lock is lost, when
+ * `stop()` is called, or on SIGINT/SIGTERM. A long migration can watch it to
+ * bail out early — migronaut cannot interrupt a running function on its own.
+ * The runner adds `session` on top of this when the migration is transactional.
+ */
+function buildContext(client, db, mongoose, signal) {
+  const context = { client, db };
+  if (mongoose) context.mongoose = mongoose;
+  if (signal) context.signal = signal;
+  return context;
+}
+
+module.exports = { buildContext };

package/src/core/import-runner.js

@@ -0,0 +1,164 @@
+const { ImportTargetNotEmptyError } = require('../errors/index.js');
+const { computeChecksum } = require('../utils/checksum.js');
+const { Changelog } = require('./changelog.js');
+const { isMigrateMongoDoc, mapMigrateMongoDocs } = require('./import.js');
+
+/** Default source collection name used by migrate-mongo */
+const MIGRATE_MONGO_COLLECTION = 'changelog';
+
+/** Records per bulkWrite — bounds a single request while keeping round trips rare */
+const IMPORT_CHUNK_SIZE = 1000;
+
+/**
+ * Adopt an existing migrate-mongo `changelog` collection by mapping its records
+ * into the migronaut schema and writing them to the target collection. The
+ * source collection is never modified. Forward-only: it records applied history
+ * so `up` skips it correctly — it does not adapt legacy migration file
+ * signatures, so `down`/`redo` on imported files is unsupported.
+ *
+ * Pure orchestration over capabilities the MigratorKit injects (`deps`):
+ * `{config, db, changelog, logger, fields, filepath, assertNotAborted}`.
+ */
+async function runImport(deps, options, signal) {
+  const { config, db, changelog, logger } = deps;
+
+  const source = options.from ?? MIGRATE_MONGO_COLLECTION;
+  const target = options.to ?? config.migrationsCollection;
+  const dryRun = options.dryRun ?? false;
+
+  // Records are written to `target`; reuse the connected changelog when it
+  // already points there, otherwise bind a fresh one (and ensure its index).
+  const targetChangelog =
+    target === config.migrationsCollection ? changelog : new Changelog(target);
+  // ensureIndexes (target) and getForeignDocs (source) touch unrelated
+  // collections — independent, safe to run concurrently.
+  const ensureIndexesPromise =
+    targetChangelog !== changelog && !dryRun
+      ? targetChangelog.ensureIndexes(db)
+      : Promise.resolve();
+  const [, rawDocs] = await Promise.all([
+    ensureIndexesPromise,
+    changelog.getForeignDocs(db, source),
+  ]);
+  if (rawDocs.length === 0) {
+    logger.info(`Nothing to import from "${source}"`, deps.fields({ source, target }));
+    return { source, target, imported: 0, skipped: 0, dryRun, rows: [] };
+  }
+
+  const valid = [];
+  let skipped = 0;
+  for (const doc of rawDocs) {
+    if (isMigrateMongoDoc(doc)) {
+      valid.push(doc);
+    } else {
+      skipped += 1;
+      logger.warn('⚠ Skipping source doc without a usable fileName');
+    }
+  }
+
+  // `{name, batch}` projections only — numbering new batches and detecting a
+  // non-empty target needs neither full documents nor the whole history twice.
+  const existing = await targetChangelog.getNamesAndBatches(db);
+  if (!options.force && !dryRun && existing.length > 0) {
+    throw new ImportTargetNotEmptyError(
+      `Target collection "${target}" already has ${existing.length} record(s) — re-run with force to proceed`,
+      { target, existing: existing.length },
+    );
+  }
+
+  // Continue batch numbering after the batches already in the target so imported
+  // records never collide with existing ones. Records this import will overwrite
+  // (same name) are excluded, keeping a forced re-import's batch numbers stable.
+  const incomingNames = new Set();
+  for (const doc of valid) incomingNames.add(doc.fileName);
+  let batchOffset = 0;
+  for (const record of existing) {
+    if (!incomingNames.has(record.name) && record.batch > batchOffset) {
+      batchOffset = record.batch;
+    }
+  }
+
+  const rowSources = new Map();
+  const records = await mapMigrateMongoDocs(valid, {
+    environment: 'imported',
+    executedBy: 'migronaut-import',
+    batchOffset,
+    resolveChecksum: async (fileName, fileHash) => {
+      const resolved = await resolveImportChecksum(
+        deps.filepath(fileName),
+        fileHash,
+        options.trustHash ?? false,
+      );
+      rowSources.set(fileName, resolved.source);
+      if (resolved.source === 'missing') {
+        logger.warn(`⚠ File not found on disk: ${fileName} — checksum unverifiable`);
+      }
+      return resolved;
+    },
+  });
+
+  const rows = [];
+  for (const record of records) {
+    rows.push({
+      file: record.name,
+      batch: record.batch,
+      appliedAt: record.appliedAt,
+      checksum: record.checksum,
+      checksumSource: rowSources.get(record.name) ?? 'missing',
+    });
+  }
+
+  if (dryRun) {
+    logger.info(
+      `◎ Dry-run  Would import ${rows.length} record(s) from "${source}" → "${target}"`,
+      deps.fields({ source, target, count: rows.length, dryRun: true }),
+    );
+    return { source, target, imported: 0, skipped, dryRun, rows };
+  }
+
+  // One unordered bulkWrite per chunk instead of one updateOne per record —
+  // adopting a 5,000-record changelog is 5 round trips, not 5,000, all while
+  // holding the migration lock. The abort check between chunks lets stop() /
+  // a lost lock halt a long import instead of running it to completion.
+  for (let start = 0; start < records.length; start += IMPORT_CHUNK_SIZE) {
+    deps.assertNotAborted(signal);
+    await targetChangelog.markAppliedBulk(db, records.slice(start, start + IMPORT_CHUNK_SIZE));
+  }
+
+  logger.info(
+    `✔ Imported ${records.length} record(s) from "${source}" → "${target}"`,
+    deps.fields({ source, target, imported: records.length, skipped }),
+  );
+  return { source, target, imported: records.length, skipped, dryRun, rows };
+}
+
+/**
+ * Decide the checksum to store for an imported migration. Order: when
+ * `trustHash`, reuse the source `fileHash` if present; otherwise reuse it only
+ * when it matches a freshly computed hash (algorithms align), else recompute
+ * from disk; when the file is missing, fall back to the source hash or empty.
+ */
+async function resolveImportChecksum(filepath, fileHash, trustHash) {
+  if (trustHash && fileHash) {
+    return { checksum: fileHash, source: 'reused' };
+  }
+  // computeChecksum directly, treating ENOENT as "missing" — an access()
+  // probe first would double the syscalls and open a TOCTOU window in which
+  // the answer can change anyway.
+  let recomputed;
+  try {
+    recomputed = await computeChecksum(filepath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    if (fileHash) {
+      return { checksum: fileHash, source: 'reused' };
+    }
+    return { checksum: '', source: 'missing' };
+  }
+  if (fileHash && fileHash === recomputed) {
+    return { checksum: fileHash, source: 'reused' };
+  }
+  return { checksum: recomputed, source: 'recomputed' };
+}
+
+module.exports = { runImport };