@alexify/migronaut 1.0.0 → 2.1.0

package/src/core/collections.js

@@ -0,0 +1,372 @@
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { ConfigInvalidError } = require('../errors/index.js');
+const { isPlainObject, regExpIssue, toWire } = require('../utils/canonical.js');
+const { isCollectionName } = require('../utils/collection-name.js');
+const { mapLimit } = require('../utils/concurrency.js');
+const { errorText } = require('../utils/error.js');
+const { importUserFile, tsLoadMessageOrNull } = require('../utils/loader.js');
+const { indexIssues, normalizeDeclaredIndex, sameDeclaredSignature } = require('./index-spec.js');
+
+/**
+ * Declared collections: validating a definition, normalizing it for the
+ * planner, and gathering definitions from their two sources — the
+ * `collections` config key and the files in `collectionsDir`.
+ *
+ * Knows nothing about the database. Definitions are validated strictly: an
+ * unknown key is an error rather than ignored, because every typo here
+ * (`indexs`, `validtor`) would otherwise read as "not managed" and silently
+ * leave the database alone.
+ */
+
+/** Every key a collection definition may carry */
+const DEFINITION_KEYS = [
+  'name',
+  'indexes',
+  'validator',
+  'validationLevel',
+  'validationAction',
+  'prune',
+];
+const DEFINITION_KEY_SET = new Set(DEFINITION_KEYS);
+const VALIDATION_LEVELS = ['off', 'strict', 'moderate'];
+const VALIDATION_ACTIONS = ['error', 'warn', 'errorAndLog'];
+
+/** Simultaneous definition-file loads — the same EMFILE bound as every other multi-file path */
+const FS_CONCURRENCY = 16;
+
+/** `collections[2]` + `indexes` → `collections[2].indexes`; `users.ts:` + `indexes` → `users.ts: indexes` */
+function join(base, key) {
+  return base.endsWith(':') ? `${base} ${key}` : `${base}.${key}`;
+}
+
+/** What makes a validator unsendable — a function, a symbol, a cycle — or null */
+function unsendable(value, seen = new Set()) {
+  if (seen.size === 0) {
+    const issue = regExpIssue(value);
+    if (issue) return issue;
+  }
+  const type = typeof value;
+  if (type === 'function') return 'must not contain functions';
+  if (type === 'symbol') return 'must not contain symbols';
+  if (value === null || type !== 'object') return null;
+  if (seen.has(value)) return 'must not contain circular references';
+  seen.add(value);
+  const items = Array.isArray(value) ? value : isPlainObject(value) ? Object.values(value) : [];
+  for (const item of items) {
+    const reason = unsendable(item, seen);
+    if (reason) return reason;
+  }
+  seen.delete(value);
+  return null;
+}
+
+const isEmptyObject = (value) => isPlainObject(value) && Object.keys(value).length === 0;
+
+function indexListIssues(indexes, base, issues) {
+  if (!Array.isArray(indexes)) {
+    issues.push({ path: join(base, 'indexes'), message: 'must be an array of index definitions' });
+    return;
+  }
+  const valid = [];
+  for (const [position, index] of indexes.entries()) {
+    const indexPath = `${join(base, 'indexes')}[${position}]`;
+    const found = indexIssues(index, indexPath);
+    issues.push(...found);
+    if (found.length === 0) {
+      valid.push({ position, path: indexPath, index: normalizeDeclaredIndex(index) });
+    }
+  }
+  for (let a = 1; a < valid.length; a++) {
+    for (let b = 0; b < a; b++) {
+      const later = valid[a];
+      const earlier = valid[b];
+      let message;
+      if (later.index.name === earlier.index.name) {
+        message = `has the same name as indexes[${earlier.position}] ("${later.index.name}")`;
+      } else if (later.index.isText && earlier.index.isText) {
+        message = `is a second text index (after indexes[${earlier.position}]) — a collection has at most one`;
+      } else if (sameDeclaredSignature(later.index, earlier.index)) {
+        message =
+          `has the same key, partialFilterExpression and collation as indexes[${earlier.position}] ` +
+          '— the server keeps only one of them';
+      }
+      if (message) {
+        issues.push({ path: later.path, message });
+        break;
+      }
+    }
+  }
+}
+
+/**
+ * Validate one collection definition, returning `{ path, message }` issues
+ * (empty when valid). `path` prefixes every issue (`collections[2]`, or
+ * `users.ts:` for a file); `reserved` are migronaut's own collection names;
+ * `fallbackName` is the name a file-based definition gets when it sets none.
+ */
+function definitionIssues(definition, { path: base, reserved = [], fallbackName } = {}) {
+  const self = base.endsWith(':') ? base.slice(0, -1) : base;
+  if (!isPlainObject(definition)) {
+    return [{ path: self, message: 'must be a collection definition object' }];
+  }
+  const issues = [];
+  const report = (key, message) => issues.push({ path: join(base, key), message });
+  for (const key of Object.keys(definition)) {
+    if (!DEFINITION_KEY_SET.has(key)) {
+      report(
+        key,
+        `is not a collection definition key (expected one of: ${DEFINITION_KEYS.join(', ')})`,
+      );
+    }
+  }
+
+  const name = definition.name ?? fallbackName;
+  const nameSource =
+    definition.name === undefined && fallbackName !== undefined ? 'file name' : 'name';
+  if (name === undefined) {
+    report('name', 'is required');
+  } else if (!isCollectionName(name)) {
+    report(
+      'name',
+      nameSource === 'name'
+        ? "must be a valid collection name (no '$'/NUL, not system.*)"
+        : `the file name gives "${name}", which is not a valid collection name — set name explicitly`,
+    );
+  } else if (reserved.includes(name)) {
+    report('name', `"${name}" is one of migronaut's own collections`);
+  }
+
+  if (definition.indexes === undefined && definition.validator === undefined) {
+    issues.push({
+      path: self,
+      message: 'declares neither indexes nor a validator — nothing to manage',
+    });
+  }
+  if (definition.indexes !== undefined) indexListIssues(definition.indexes, base, issues);
+
+  const { validator } = definition;
+  if (validator !== undefined && validator !== null) {
+    if (!isPlainObject(validator)) {
+      report('validator', 'must be an object (a query or { $jsonSchema }), or null for none');
+    } else {
+      const reason = unsendable(validator);
+      if (reason) report('validator', reason);
+    }
+  }
+  const hasValidator = isPlainObject(validator) && !isEmptyObject(validator);
+  for (const [key, allowed] of [
+    ['validationLevel', VALIDATION_LEVELS],
+    ['validationAction', VALIDATION_ACTIONS],
+  ]) {
+    const value = definition[key];
+    if (value === undefined) continue;
+    if (!allowed.includes(value)) {
+      report(key, `must be ${allowed.map((item) => `'${item}'`).join(', ')}`);
+    } else if (!hasValidator) {
+      report(key, 'has no effect without a validator');
+    }
+  }
+  if (definition.prune !== undefined && typeof definition.prune !== 'boolean') {
+    report('prune', 'must be a boolean');
+  }
+  return issues;
+}
+
+/**
+ * Validate the `collections` config key: each definition, plus no collection
+ * declared twice. `reserved` are the changelog and lock collection names.
+ */
+function collectionsIssues(list, { reserved = [] } = {}) {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) {
+    return [{ path: 'collections', message: 'must be an array of collection definitions' }];
+  }
+  const issues = [];
+  const seen = new Map();
+  for (const [position, definition] of list.entries()) {
+    const base = `collections[${position}]`;
+    issues.push(...definitionIssues(definition, { path: base, reserved }));
+    const name = isPlainObject(definition) ? definition.name : undefined;
+    if (typeof name !== 'string') continue;
+    if (seen.has(name)) {
+      issues.push({
+        path: `${base}.name`,
+        message: `declares "${name}" again (already collections[${seen.get(name)}])`,
+      });
+    } else {
+      seen.set(name, position);
+    }
+  }
+  return issues;
+}
+
+/**
+ * A valid definition in the planner's shape: indexes normalized (effective
+ * names, server-form keys, the spec to send), the validator cleaned for the
+ * wire. `indexes`/`validator` stay `undefined` when not managed.
+ */
+function normalizeDefinition(definition, { name, source } = {}) {
+  const { validator } = definition;
+  return {
+    name: definition.name ?? name,
+    source,
+    indexes: definition.indexes?.map((index) => normalizeDeclaredIndex(index)),
+    validator: validator === undefined || validator === null ? validator : toWire(validator),
+    ...(definition.validationLevel !== undefined
+      ? { validationLevel: definition.validationLevel }
+      : {}),
+    ...(definition.validationAction !== undefined
+      ? { validationAction: definition.validationAction }
+      : {}),
+    ...(definition.prune !== undefined ? { prune: definition.prune } : {}),
+  };
+}
+
+/** The extensions a definition file may have: `fileExtensions`, dotted, plus `.json` — longest first */
+function definitionExtensions(extensions) {
+  const set = new Set(['.json']);
+  for (const ext of extensions) set.add(ext.startsWith('.') ? ext : `.${ext}`);
+  return [...set].sort((a, b) => b.length - a.length);
+}
+
+/**
+ * Load one definition file. JSON is parsed; anything else is imported, and
+ * its default export (or, for an ES module with only named exports, the
+ * exports themselves) is the definition. A function is refused rather than
+ * called — a Mongoose model is a function, and a definitions directory is
+ * exactly where one might be left by mistake.
+ */
+async function loadDefinitionFile(filepath, options) {
+  if (filepath.endsWith('.json')) {
+    const raw = await fs.readFile(filepath, 'utf8');
+    try {
+      return JSON.parse(raw);
+    } catch (error) {
+      throw new ConfigInvalidError(
+        'Collection definition file is not valid JSON',
+        { path: filepath, cause: errorText(error) },
+        { cause: error },
+      );
+    }
+  }
+  let mod;
+  try {
+    mod = await importUserFile(filepath, { reload: options.reload });
+  } catch (error) {
+    throw new ConfigInvalidError(
+      tsLoadMessageOrNull(filepath, error, 'collection definition') ??
+        'Collection definition file failed to load',
+      { path: filepath, cause: errorText(error) },
+      { cause: error },
+    );
+  }
+  const exported = mod.default ?? mod;
+  if (typeof exported === 'function') {
+    throw new ConfigInvalidError(
+      'A collection definition file must export one definition object, not a function',
+      { path: filepath },
+    );
+  }
+  // A shallow copy: an ES module namespace is an exotic object, not a plain one.
+  return isPlainObject(exported) || exported === mod ? { ...exported } : exported;
+}
+
+/**
+ * Load every definition file in `dir`: one collection per file, non-recursive,
+ * sorted by file name. Dotfiles and declaration files (`.d.ts`) are skipped,
+ * like in the migrations directory. An explicitly configured directory that
+ * does not exist is an error, not "no definitions".
+ */
+async function loadCollectionsDir(dir, { extensions, reload = false }) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+      throw new ConfigInvalidError('collectionsDir not found', { path: dir });
+    }
+    throw new ConfigInvalidError(
+      'collectionsDir could not be read',
+      { path: dir, cause: errorText(error) },
+      { cause: error },
+    );
+  }
+  const accepted = definitionExtensions(extensions);
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile()) continue;
+    const file = entry.name;
+    if (file.startsWith('.')) continue;
+    if (file.endsWith('.d.ts') || file.endsWith('.d.mts') || file.endsWith('.d.cts')) continue;
+    const ext = accepted.find(
+      (candidate) => file.endsWith(candidate) && file.length > candidate.length,
+    );
+    if (ext) files.push({ file, name: file.slice(0, -ext.length) });
+  }
+  files.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return mapLimit(files, FS_CONCURRENCY, async ({ file, name }) => {
+    const filepath = path.join(dir, file);
+    return { file, name, definition: await loadDefinitionFile(filepath, { reload }) };
+  });
+}
+
+/**
+ * Every declared collection, normalized: the `collections` key first (already
+ * validated with the rest of the config), then the files in `dir`, if one is
+ * configured. A collection declared by both sources — or by two files — is
+ * an error: which declaration wins would otherwise depend on load order.
+ *
+ * @throws {ConfigInvalidError} on a missing directory, a file that does not
+ *   load, or invalid definitions (all issues at once, in `context.issues`)
+ */
+async function resolveDefinitions({
+  inline,
+  dir,
+  extensions = ['.ts', '.js'],
+  reload,
+  reserved = [],
+}) {
+  const definitions = [];
+  const declaredBy = new Map();
+  for (const [position, definition] of (inline ?? []).entries()) {
+    const source = `collections[${position}]`;
+    definitions.push(normalizeDefinition(definition, { source }));
+    declaredBy.set(definition.name, source);
+  }
+  if (dir === undefined) return definitions;
+
+  const files = await loadCollectionsDir(dir, { extensions, reload });
+  const issues = [];
+  for (const { file, name: fallbackName, definition } of files) {
+    const base = `${file}:`;
+    const found = definitionIssues(definition, { path: base, reserved, fallbackName });
+    if (found.length > 0) {
+      issues.push(...found);
+      continue;
+    }
+    const name = definition.name ?? fallbackName;
+    if (declaredBy.has(name)) {
+      issues.push({
+        path: join(base, 'name'),
+        message: `declares "${name}" again (already ${declaredBy.get(name)})`,
+      });
+      continue;
+    }
+    declaredBy.set(name, file);
+    definitions.push(normalizeDefinition(definition, { name, source: file }));
+  }
+  if (issues.length > 0) {
+    throw new ConfigInvalidError('Invalid collection definition(s)', { path: dir, issues });
+  }
+  return definitions;
+}
+
+module.exports = {
+  DEFINITION_KEYS,
+  collectionsIssues,
+  definitionIssues,
+  loadCollectionsDir,
+  normalizeDefinition,
+  resolveDefinitions,
+};

package/src/core/config.js

@@ -2,22 +2,36 @@ const fs = require('node:fs/promises');
 const path = require('node:path');
 const { pathToFileURL } = require('node:url');
 const { ConfigInvalidError } = require('../errors/index.js');
+const { isCollectionName } = require('../utils/collection-name.js');
+const { TELEMETRY_KEYS, telemetryIssues } = require('../utils/telemetry.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');
+const { collectionsIssues } = require('./collections.js');
 
-/** Default values applied when no flag, env var, or config-file value is present */
+/**
+ * Default values applied when no flag, env var, or config-file value is
+ * present. The single canonical home for every effective default — a use-site
+ * `??` fallback would hide these from the schema/template sync tests and let
+ * the same fact drift across hand-written copies.
+ */
 const DEFAULT_CONFIG = {
   migrationsDir: './migrations',
   migrationsCollection: '_migronaut_migrations',
   lockCollection: '_migronaut_locks',
+  convergeLogCollection: '_migronaut_converge',
   lockTTLSeconds: 60,
   strict: false,
   useTransaction: false,
   fileExtensions: ['.ts', '.js'],
   createExtension: 'js',
   sequential: false,
+  ensureIndexes: true,
+  onLockLost: 'abort',
+  onOutOfOrder: 'warn',
+  reloadMigrations: false,
+  convergeAfterUp: false,
 };
 
 /** Candidate config file names, checked in priority order within the cwd */
@@ -28,20 +42,6 @@ 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) {
@@ -53,8 +53,13 @@ function isStringList(value) {
 /**
  * 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.
+ * they hold live instances the validator has nothing to say about.
+ * `generateId` and `telemetry` are code-only too, but each has exactly one
+ * valid shape, so validateConfig checks them on their own rather than through
+ * this table (which a test pins against the JSON schema — and a function or a
+ * tracer has no place there).
+ * Unknown keys are allowed, matching the previous zod (non-strict object)
+ * behavior.
  */
 const CONFIG_KEYS = [
   { path: 'uri', check: isNonEmptyString, message: 'uri is required' },
@@ -70,6 +75,11 @@ const CONFIG_KEYS = [
     check: isCollectionName,
     message: "must be a valid collection name (no '$'/NUL, not system.*)",
   },
+  {
+    path: 'convergeLogCollection',
+    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' },
@@ -98,6 +108,12 @@ const CONFIG_KEYS = [
     message: "must be 'abort' or 'warn'",
     optional: true,
   },
+  {
+    path: 'onOutOfOrder',
+    check: (value) => value === 'warn' || value === 'error' || value === 'allow',
+    message: "must be 'warn', 'error' or 'allow'",
+    optional: true,
+  },
   {
     path: 'envFile',
     check: (value) => value === false || isNonEmptyString(value),
@@ -118,15 +134,39 @@ const CONFIG_KEYS = [
     optional: true,
   },
   { path: 'reloadMigrations', check: isBoolean, message: 'must be a boolean', optional: true },
+  // Only the outer shape here — each definition is checked by
+  // collectionsIssues (core/collections.js), which reports nested paths
+  // (`collections[2].indexes[0].key`) instead of one opaque message.
+  {
+    path: 'collections',
+    check: Array.isArray,
+    message: 'must be an array of collection definitions',
+    optional: true,
+  },
+  {
+    path: 'collectionsDir',
+    check: isNonEmptyString,
+    message: 'must be a non-empty string',
+    optional: true,
+  },
+  { path: 'convergeAfterUp', 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.
+ * the code-only ones (the live instances, `generateId` and `telemetry`). 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']);
+const KNOWN_CONFIG_KEYS = new Set([
+  'logger',
+  'hooks',
+  'mongoose',
+  'client',
+  'generateId',
+  'telemetry',
+]);
 for (const spec of CONFIG_KEYS) KNOWN_CONFIG_KEYS.add(spec.path);
 
 /**
@@ -150,6 +190,34 @@ function validateConfig(config, options = {}) {
     }
     if (!spec.check(value)) issues.push({ path: spec.path, message: spec.message });
   }
+  // What it returns is checked on every call (utils/id.js); that it is callable
+  // at all is a config mistake — a JSON config's `"generateId": "ulid"` — and
+  // belongs with the others, before a run is started.
+  if (config.generateId !== undefined && typeof config.generateId !== 'function') {
+    issues.push({ path: 'generateId', message: 'must be a function' });
+  }
+  for (const issue of telemetryIssues(config.telemetry)) issues.push(issue);
+  // Inline definitions are checked with the rest of the config — they are
+  // 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}` });
+      }
+    }
+  }
+  if (Array.isArray(config.collections)) {
+    const reserved = [
+      config.migrationsCollection,
+      config.lockCollection,
+      config.convergeLogCollection,
+    ];
+    for (const issue of collectionsIssues(config.collections, { reserved })) issues.push(issue);
+  }
   return issues;
 }
 
@@ -227,8 +295,9 @@ const parseString = (value) => value;
  *
  * 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.
+ * holding non-scalars — `fileExtensions`, `clientOptions`, `collections`,
+ * `client`, `mongoose`, `hooks`, `logger`, `generateId`, `telemetry` — 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).
@@ -239,6 +308,11 @@ const ENV_KEYS = [
   { 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_CONVERGE_LOG_COLLECTION',
+    path: 'convergeLogCollection',
+    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 },
@@ -248,8 +322,15 @@ const ENV_KEYS = [
   { 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_ON_OUT_OF_ORDER',
+    path: 'onOutOfOrder',
+    parse: parseEnum(['warn', 'error', 'allow']),
+  },
   { env: 'MIGRONAUT_ENSURE_INDEXES', path: 'ensureIndexes', parse: parseBoolean },
   { env: 'MIGRONAUT_RELOAD_MIGRATIONS', path: 'reloadMigrations', parse: parseBoolean },
+  { env: 'MIGRONAUT_COLLECTIONS_DIR', path: 'collectionsDir', parse: parseString },
+  { env: 'MIGRONAUT_CONVERGE_AFTER_UP', path: 'convergeAfterUp', parse: parseBoolean },
 ];
 
 /** Build a partial config from the MIGRONAUT_* environment variables */
@@ -394,7 +475,10 @@ async function loadConfig(options = {}) {
     : await discoverConfigFile(cwd);
 
   if (configFilePath) {
-    if (!(await pathExists(configFilePath))) {
+    // Only an explicit --config path needs the probe (a typo deserves a clear
+    // "not found") — discovery already proved existence, and re-checking it
+    // would pay a redundant fs.access on every invocation.
+    if (options.configPath && !(await pathExists(configFilePath))) {
       throw new ConfigInvalidError('Config file not found', { path: configFilePath });
     }
     const fileConfig = await loadConfigFile(configFilePath, options.lenient ?? false);
@@ -435,6 +519,13 @@ async function loadConfig(options = {}) {
   for (const key in config) {
     if (!KNOWN_CONFIG_KEYS.has(key)) (unknown ??= []).push(key);
   }
+  // Same for `telemetry`: handing over the whole `@opentelemetry/api` module
+  // (`trace`, `metrics`) instead of a tracer and a meter turns it off silently.
+  if (config.telemetry) {
+    for (const key in config.telemetry) {
+      if (!TELEMETRY_KEYS.includes(key)) (unknown ??= []).push(`telemetry.${key}`);
+    }
+  }
   if (unknown) {
     effectiveLogger(config.logger).debug(
       `Unrecognized config key(s), ignored: ${unknown.join(', ')}`,
@@ -447,18 +538,23 @@ async function loadConfig(options = {}) {
   }
 
   // "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.
+  // debug level. Live instances (client, mongoose, hooks, logger, telemetry)
+  // and the generateId function are elided: they are not serializable and
+  // redactDeep rightly refuses to clone them. Declared collections show as
+  // names only — validators can run to hundreds of lines.
   {
-    const { client, mongoose, hooks, logger, ...rest } = config;
+    const { client, mongoose, hooks, logger, generateId, telemetry, collections, ...rest } = config;
     effectiveLogger(config.logger).debug(
       `Resolved config (source: ${configFilePath ? path.basename(configFilePath) : 'env/flags/defaults'})`,
       redactDeep({
         ...rest,
+        ...(collections ? { collections: collections.map((definition) => definition.name) } : {}),
         ...(client ? { client: '[injected]' } : {}),
         ...(mongoose ? { mongoose: '[injected]' } : {}),
         ...(hooks ? { hooks: Object.keys(hooks) } : {}),
         ...(logger !== undefined ? { logger: logger === null ? null : '[injected]' } : {}),
+        ...(generateId ? { generateId: '[injected]' } : {}),
+        ...(telemetry ? { telemetry: '[injected]' } : {}),
       }),
     );
   }
@@ -473,6 +569,8 @@ module.exports = {
   CONFIG_KEYS,
   DEFAULT_CONFIG,
   ENV_KEYS,
+  // 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,
   loadConfig,
   validateConfig,