@onlineapps/conn-orch-validator 7.0.0 → 8.1.0

package/src/utils/installContract.js

@@ -1,17 +1,34 @@
 'use strict';
 
 /**
- * Installation contract for a biz service repository.
+ * Installation contract for a repository.
  *
- *   SETUP_DOCS   every repo carries docs/setup/{INSTALL,PLATFORM_MATRIX,VALIDATION}.md
- *   SQL_PACKAGE  a repo WITH a database carries the BASELINE / SEED SQL tree
- *   SQL_HEADERS  every SQL package file declares its dataset class and safety
+ *   SETUP_DOCS   every repo carries docs/80-setup/{INSTALL,PLATFORM_MATRIX,VALIDATION}.md
+ *                The branch is numbered because DOC-STANDARD rule 7 governs the
+ *                shape of a docs tree and the contract follows it, not the other
+ *                way round (confirmation docs-setup-branch-naming 001). The number
+ *                is 80: property, the only numbered biz tree so far, already carries
+ *                docs/80-setup/; 30 would collide with property's 30-recurring; and
+ *                setup is an operational appendix behind the contract nodes, in the
+ *                same 80-decisions/90-migration band as the platform tree.
+ *                The number is a literal and not the `\d{2}-setup` shape rule 7
+ *                permits, because eight repositories each free to pick a digit pair
+ *                is eight layouts: the confirmation delegates ONE number, and this
+ *                is where it is written down.
+ *   SQL_PACKAGE  a repo WITH a database carries the BASELINE / SEED SQL tree, and a
+ *                manifest package (§3 model 2) names exactly what the installer
+ *                applies — in both directions (§7)
+ *   SQL_HEADERS  every live SQL file declares its dataset class and safety, with
+ *                VALUES from the contract's closed vocabularies and not merely the
+ *                four keys (§4)
  *
- * Rules: ADR 0006 (api/docs/biz/80-decisions/) — database and test-data contract.
+ * Rules: api/docs/standards/repository-installation-sql-contract.md §2-§5, §7
+ * @see api/docs/governance/confirmations/installation-sql-contract-scope.md
+ * @see api/docs/governance/confirmations/docs-setup-branch-naming.md
  *
  * Whether the SQL half applies is DERIVED from the service's own
  * integration-contract.json database block, never declared a second time here.
- * The eight shell copies this replaces each carried a hand-maintained
+ * The nine shell copies this replaces each carried a hand-maintained
  * REPO_HAS_DB literal, and three of them (converter, hello-service, ingest) said
  * "false" while their contract declared a database — so the SQL half checked
  * nothing in those repos while still printing PASS. One fact, one owner: the
@@ -27,10 +44,30 @@
 const fs = require('fs');
 const path = require('path');
 
+const { compareVersion } = require('./migrationOrder');
+const { normalizeDatabaseDeclaration } = require('./bizCiGateContract');
+// Exact-name existence: `fs.existsSync` answers true for `install.md` on a
+// case-insensitive filesystem (macOS APFS), so a gate built on it says one thing
+// on a developer machine and another in node:24-alpine (BIZ-PROPERTY, 2026-09-14:
+// 361 findings vs 363). `automation-gates.md` §1.1 — same inputs, same result.
+const { existsExactly } = require('../manifest/checks/gitTracked');
+
+/**
+ * The requirement ids this module raises, and the ONLY place their extent is
+ * stated. `add()` below refuses an id that is not on this list, and the manifest
+ * bridge reads it to refuse a row citing a requirement nothing raises.
+ *
+ * Exported for the same reason `deployContract.js` exports its own list: the
+ * bridge had a hand-written copy of these three ids, and a copy of a list is a
+ * list that drifts — measured on the deploy contract, whose four messages named
+ * one requirement fewer than the module enforced, for months.
+ */
+const INSTALL_CONTRACT_REQUIREMENTS = Object.freeze(['SETUP_DOCS', 'SQL_PACKAGE', 'SQL_HEADERS']);
+
 const SETUP_DOCS = [
-  'docs/setup/INSTALL.md',
-  'docs/setup/PLATFORM_MATRIX.md',
-  'docs/setup/VALIDATION.md'
+  'docs/80-setup/INSTALL.md',
+  'docs/80-setup/PLATFORM_MATRIX.md',
+  'docs/80-setup/VALIDATION.md'
 ];
 
 const SQL_DIRECTORIES = [
@@ -39,15 +76,44 @@ const SQL_DIRECTORIES = [
   'migrations/SEED/test_only'
 ];
 
-const REQUIRED_HEADERS = [
-  '-- Dataset-Class:',
-  '-- Target-DB:',
-  '-- Safe-For-Production:',
-  '-- Idempotency:'
-];
+const MIGRATIONS_ROOT = 'migrations';
+
+/**
+ * History is outside the installation contract: the contract is what a cold
+ * start applies, and these two hold the record of how a baseline was reached
+ * (owner, `installation-sql-contract-scope` 001 — "archive/ určitě nepatří",
+ * and `superseded/` is to be merged into it by the repositories that own one).
+ * The installer agrees by construction: `setupDatabase.resolveMigrationPlan`
+ * reads one directory's own .sql files and descends into no subdirectory.
+ */
+const HISTORY_DIRECTORIES = new Set(['archive', 'superseded']);
+
+/**
+ * §4. Three of the four fields are CLOSED vocabularies and the fourth is a name.
+ * The gate enforces the vocabulary and not mere presence, because a header that
+ * parses but lies is worse than a missing one: measured 2026-08-31, a live file
+ * shipped `Idempotency: full` — a value this contract never defined — and every
+ * copy of the gate printed PASS.
+ *
+ * `Target-DB` carries `null`: the contract asks only that it is present, and
+ * comparing it against the schema the integration contract declares would make
+ * the header a second copy of that fact. One copy of the gate does compare them;
+ * the contract does not ask for it, and this module implements the contract.
+ */
+const HEADER_FIELDS = Object.freeze([
+  Object.freeze({ name: 'Dataset-Class', values: Object.freeze(['BASELINE', 'PRODUCTION_LIKE', 'TEST_ONLY', 'MIGRATION']) }),
+  Object.freeze({ name: 'Target-DB', values: null }),
+  Object.freeze({ name: 'Safe-For-Production', values: Object.freeze(['yes', 'no']) }),
+  Object.freeze({ name: 'Idempotency', values: Object.freeze(['yes', 'partial', 'no']) })
+]);
 
 const TEST_ONLY_DIRECTORY = 'migrations/SEED/test_only';
 
+/** The marker §4 asks every test-only file to carry visibly, in comments. */
+const TEST_ONLY_MARKER = 'TEST-ONLY';
+
+const APPLIES_PREFIX = '-- Applies:';
+
 /** Sorted so the report order is the directory order, not the filesystem's. */
 function listSqlFiles(absoluteDir) {
   return fs.readdirSync(absoluteDir)
@@ -55,41 +121,168 @@ function listSqlFiles(absoluteDir) {
     .sort();
 }
 
+/**
+ * Every live SQL file of the package, repo-relative and depth-first in name
+ * order, with history pruned. The whole tree is in scope and not the three
+ * package directories alone: the root `migrations/*.sql` set IS the live
+ * migration set of four services, and until this loop reached it those files
+ * carried no header requirement at all while the gate reported PASS.
+ */
+function listLiveSqlFiles(serviceRoot) {
+  const found = [];
+
+  const walk = (relativeDir) => {
+    const absoluteDir = path.join(serviceRoot, relativeDir);
+    if (!fs.existsSync(absoluteDir)) return;
+
+    const entries = fs.readdirSync(absoluteDir, { withFileTypes: true })
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (HISTORY_DIRECTORIES.has(entry.name)) continue;
+        walk(`${relativeDir}/${entry.name}`);
+      } else if (entry.isFile() && entry.name.endsWith('.sql')) {
+        found.push(`${relativeDir}/${entry.name}`);
+      }
+    }
+  };
+
+  walk(MIGRATIONS_ROOT);
+  return found;
+}
+
+/**
+ * The declared value of one header: the whole text after the colon, and the
+ * first token of it. §4 — "the value is the first token on the line; free text
+ * after it is allowed", which is what makes a claim checkable (`yes (CREATE
+ * TABLE IF NOT EXISTS)` says why, `yes` asks to be believed).
+ *
+ * @returns {{declared: string, token: string}|null} null when the file carries
+ *   no such header line at all
+ */
+function readHeader(lines, name) {
+  const prefix = `-- ${name}:`;
+  const line = lines.find((candidate) => candidate.startsWith(prefix));
+  if (line === undefined) return null;
+
+  const declared = line.slice(prefix.length).trim();
+  return { declared, token: declared.split(/\s+/)[0] ?? '' };
+}
+
 function checkSetupDocs(serviceRoot, add) {
   for (const relativePath of SETUP_DOCS) {
-    if (!fs.existsSync(path.join(serviceRoot, relativePath))) {
+    if (!existsExactly(serviceRoot, relativePath.split('/'))) {
       add('SETUP_DOCS', `Missing required file - ${relativePath}. `
-        + `Fix: add ${relativePath} to the repository.`);
+        + `Fix: add ${relativePath} to the repository; `
+        + 'a repo carrying the older docs/setup/ branch renames it to docs/80-setup/.');
     }
   }
 }
 
-function checkSqlHeaders(serviceRoot, relativeDir, add) {
-  for (const name of listSqlFiles(path.join(serviceRoot, relativeDir))) {
-    const relativeFile = `${relativeDir}/${name}`;
-    const content = fs.readFileSync(path.join(serviceRoot, relativeFile), 'utf8');
-    const lines = content.split('\n');
+function checkSqlHeaders(serviceRoot, relativeFile, add) {
+  const content = fs.readFileSync(path.join(serviceRoot, relativeFile), 'utf8');
+  const lines = content.split('\n');
 
-    for (const header of REQUIRED_HEADERS) {
-      if (!lines.some((line) => line.startsWith(header))) {
-        add('SQL_HEADERS', `Missing "${header}" header - ${relativeFile}. `
-          + `Fix: add the "${header}" header line to the file.`);
-      }
+  const declared = {};
+  for (const field of HEADER_FIELDS) {
+    const header = readHeader(lines, field.name);
+    if (header === null) {
+      add('SQL_HEADERS', `Missing "-- ${field.name}:" header - ${relativeFile}. `
+        + `Fix: add the "-- ${field.name}:" header line to the file.`);
+      continue;
     }
 
-    if (relativeDir !== TEST_ONLY_DIRECTORY) continue;
+    declared[field.name] = header.token;
 
-    // Test data must be unmistakable at the file level: a TEST_ONLY package that
-    // reads as production-safe is the one mistake that reaches a real database.
-    if (!lines.some((line) => line.startsWith('-- Dataset-Class: TEST_ONLY'))) {
-      add('SQL_HEADERS', `Wrong Dataset-Class - ${relativeFile} must declare `
-        + '"-- Dataset-Class: TEST_ONLY". Fix: correct the Dataset-Class header.');
-    }
-    if (!lines.some((line) => line.startsWith('-- Safe-For-Production: no'))) {
-      add('SQL_HEADERS', `Wrong Safe-For-Production - ${relativeFile} must declare `
-        + '"-- Safe-For-Production: no". Fix: correct the Safe-For-Production header.');
+    if (field.values !== null && !field.values.includes(header.token)) {
+      add('SQL_HEADERS', `Value outside the vocabulary - ${relativeFile} declares `
+        + `"-- ${field.name}: ${header.declared}". Fix: the first token must be one of `
+        + `${field.values.join(', ')}; free text may follow it.`);
     }
   }
+
+  // Test data must be unmistakable at the file level: a TEST_ONLY package that
+  // reads as production-safe is the one mistake that reaches a real database.
+  // The directory separates it (§5 point 3) and the class declares it (§4); a
+  // file is test-only as soon as EITHER says so, because the mistake is exactly
+  // the case where the two disagree.
+  const inTestOnlyDirectory = relativeFile.startsWith(`${TEST_ONLY_DIRECTORY}/`);
+  if (inTestOnlyDirectory && declared['Dataset-Class'] !== 'TEST_ONLY') {
+    add('SQL_HEADERS', `Wrong Dataset-Class - ${relativeFile} must declare `
+      + '"-- Dataset-Class: TEST_ONLY". Fix: correct the Dataset-Class header.');
+  }
+
+  const isTestOnly = inTestOnlyDirectory || declared['Dataset-Class'] === 'TEST_ONLY';
+  if (!isTestOnly) return;
+
+  if (declared['Safe-For-Production'] !== 'no') {
+    add('SQL_HEADERS', `Wrong Safe-For-Production - ${relativeFile} must declare `
+      + '"-- Safe-For-Production: no". Fix: correct the Safe-For-Production header.');
+  }
+
+  // §4 last bullet: the marker is a SECOND, human-visible signal, deliberately
+  // not the same string as the class header (TEST-ONLY, not TEST_ONLY), so a
+  // reader who opens the file half-way down still sees it.
+  const hasMarker = lines.some((line) => line.includes('--') && line.includes(TEST_ONLY_MARKER));
+  if (!hasMarker) {
+    add('SQL_HEADERS', `Missing ${TEST_ONLY_MARKER} marker - ${relativeFile} is test-only but carries no `
+      + `comment containing "${TEST_ONLY_MARKER}". Fix: add a comment line with the ${TEST_ONLY_MARKER} marker.`);
+  }
+}
+
+/**
+ * §7 last bullet: a manifest package is incomplete in either direction — a file
+ * it names does not exist, or a file the installer applies is not named.
+ * Headers alone say nothing about this: a manifest is a hand-written list of
+ * file names, and such a list rots the moment somebody adds a file beside the
+ * ones it names (`doc-code-binding.md` §1), silently, with every header still
+ * in place.
+ *
+ * A file IS a manifest exactly when it carries an `-- Applies:` line. That is
+ * what distinguishes §3's two allowed models without a second declaration: a
+ * native package file (model 1) carries the statements itself and names nothing.
+ *
+ * The source directory is likewise DERIVED — it is the directory of the paths
+ * the manifest already names, which is why all lines of one manifest must live
+ * in one directory. The order compared against is the installer's own
+ * (`migrationOrder.compareVersion`, shared with `setupDatabase.js` and with the
+ * operator's `sort -V`), because with migrations the order IS semantics.
+ */
+function checkManifestCompleteness(serviceRoot, manifestFile, add) {
+  const content = fs.readFileSync(path.join(serviceRoot, manifestFile), 'utf8');
+  const declared = content.split('\n')
+    .filter((line) => line.startsWith(APPLIES_PREFIX))
+    .map((line) => line.slice(APPLIES_PREFIX.length).trim())
+    .filter((value) => value.length > 0);
+
+  if (declared.length === 0) return;
+
+  const missing = declared.filter((relativeFile) => !existsExactly(serviceRoot, relativeFile.split('/')));
+  if (missing.length > 0) {
+    add('SQL_PACKAGE', `Manifest names a file that does not exist - ${manifestFile} declares `
+      + `"${missing.join(', ')}". Fix: correct the "-- Applies:" path, or add the file.`);
+    return;
+  }
+
+  const sourceDirectory = path.posix.dirname(declared[0]);
+  const stray = declared.filter((relativeFile) => path.posix.dirname(relativeFile) !== sourceDirectory);
+  if (stray.length > 0) {
+    add('SQL_PACKAGE', `Manifest straddles two directories - ${manifestFile} names ${sourceDirectory} `
+      + `first but also declares "${stray.join(', ')}". Fix: one manifest covers one source directory; `
+      + 'give the other directory its own manifest.');
+    return;
+  }
+
+  const applied = listSqlFiles(path.join(serviceRoot, sourceDirectory))
+    .sort(compareVersion)
+    .map((name) => `${sourceDirectory}/${name}`);
+
+  if (declared.join('\n') !== applied.join('\n')) {
+    add('SQL_PACKAGE', `Manifest does not match what the installer applies - ${manifestFile} declares `
+      + `"${declared.join(', ')}" and ${sourceDirectory}/*.sql applies "${applied.join(', ')}". `
+      + 'Fix: make the "-- Applies:" lines name exactly those files, in that order.');
+  }
 }
 
 function checkSqlPackage(serviceRoot, add) {
@@ -107,10 +300,47 @@ function checkSqlPackage(serviceRoot, add) {
     if (listSqlFiles(absoluteDir).length === 0) {
       add('SQL_PACKAGE', `No SQL package files - ${relativeDir} contains no .sql file. `
         + 'Fix: add the SQL package files, or remove the database declaration from the contract.');
-      continue;
     }
+  }
+
+  const liveFiles = listLiveSqlFiles(serviceRoot);
+
+  for (const relativeFile of liveFiles) {
+    checkSqlHeaders(serviceRoot, relativeFile, add);
+  }
+
+  for (const relativeFile of liveFiles) {
+    checkManifestCompleteness(serviceRoot, relativeFile, add);
+  }
+}
+
+/**
+ * Principle 4: the gate validates its own input before it judges anything.
+ *
+ * `database` decides whether the SQL half applies at all, and it used to be read
+ * as a mere truthiness: the loader envelope (`{serviceRoot, contractPath,
+ * contract}`) or the whole normalized contract passed straight through, and the
+ * SQL package was then judged — or skipped — on a value this module had never
+ * recognised. A gate that cannot say what it was handed prints a guarantee it
+ * does not have (automation-gates.md §5).
+ *
+ * What a normalized block IS stays where it is defined: the check runs
+ * `normalizeDatabaseDeclaration` over the argument rather than restating its
+ * four fields, so this module cannot drift from the shape it accepts.
+ * A normalized block round-trips through it unchanged, which is precisely what
+ * makes it usable as the entry check.
+ */
+function assertNormalizedDatabase(database) {
+  if (database === null || database === undefined) return;
 
-    checkSqlHeaders(serviceRoot, relativeDir, add);
+  try {
+    normalizeDatabaseDeclaration(database, { db: true });
+  } catch (error) {
+    throw new Error('[InstallContract] Invalid database argument - Expected the normalized database block '
+      + 'of an integration contract, or null when the service declares none; the value given is neither: '
+      + `${error.message} `
+      + 'Fix: pass loadAndValidateIntegrationContract(serviceRoot).contract.database — not the loader '
+      + 'envelope that wraps it, and not the whole contract.');
   }
 }
 
@@ -121,8 +351,24 @@ function checkSqlPackage(serviceRoot, add) {
  * @returns {{service: string, ok: boolean, databaseChecked: boolean, violations: Array<{requirement: string, message: string}>}}
  */
 function verifyInstallContract(serviceRoot, database) {
+  if (typeof serviceRoot !== 'string' || serviceRoot.trim() === '') {
+    throw new Error('[InstallContract] Invalid serviceRoot - Expected a non-empty path to the repository '
+      + `root, got ${typeof serviceRoot}. Fix: pass the directory to inspect, e.g. `
+      + 'loadAndValidateIntegrationContract(serviceRoot).serviceRoot.');
+  }
+
+  assertNormalizedDatabase(database);
+
   const violations = [];
-  const add = (requirement, message) => violations.push({ requirement, message });
+  const add = (requirement, message) => {
+    if (!INSTALL_CONTRACT_REQUIREMENTS.includes(requirement)) {
+      throw new Error(`[InstallContract] Unknown requirement "${requirement}" - Expected one of `
+        + `${INSTALL_CONTRACT_REQUIREMENTS.join(', ')}. Fix: add the id to `
+        + 'INSTALL_CONTRACT_REQUIREMENTS in utils/installContract.js, so the list every reader '
+        + 'takes from this module stays this module\'s own.');
+    }
+    violations.push({ requirement, message });
+  };
 
   checkSetupDocs(serviceRoot, add);
 
@@ -139,4 +385,4 @@ function verifyInstallContract(serviceRoot, database) {
   };
 }
 
-module.exports = { verifyInstallContract };
+module.exports = { verifyInstallContract, INSTALL_CONTRACT_REQUIREMENTS };

package/src/utils/libCompat.js

@@ -14,6 +14,15 @@
  * list — a platform-release entry records what was deployed, so everything in
  * it is by definition shipped and must match.
  *
+ * That narrowing covers a package the SSOT DECLARES and infra does not install.
+ * A package the SSOT declares in NEITHER list is a different thing: not
+ * biz-only, but unknown to the platform. R6's rule is that a service pins
+ * exactly what the SSOT declares (`.claude/rules/architecture-principles.md`
+ * § Version pinning), and for an undeclared package there is no such version at
+ * all — so it is refused, never narrowed away. Passing it would be a fallback
+ * to "not gated" (principle 3), and it would let a typo or a retired package
+ * name travel into an image with the gate reporting OK (measured 2026-09-14).
+ *
  * Pure module: the rules and the fetch live here, presentation and exit codes
  * live in the CLI.
  *
@@ -71,13 +80,26 @@ function checkLibCompat(pkg, librarySet) {
   const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
   const ours = Object.entries(deps).filter(([name]) => name.startsWith(SCOPE));
 
-  const gated = infraConsumed ? ours.filter(([name]) => infraConsumed.has(name)) : ours;
-  const notGated = infraConsumed
-    ? ours.filter(([name]) => !infraConsumed.has(name)).map(([name]) => name)
-    : [];
-
+  const gated = [];
+  const notGated = [];
   const violations = [];
-  for (const [name, version] of gated) {
+
+  for (const [name, version] of ours) {
+    if (infraConsumed && !infraConsumed.has(name)) {
+      if (!(name in versions)) {
+        violations.push({
+          package: name,
+          message: `${name}: unknown to the platform library SSOT `
+            + "- declared in neither 'libraries' nor 'infraConsumed', so no platform version exists to pin against. "
+            + `Fix: publish ${name} and add it to config/libraries.json, or remove the pin.`
+        });
+        continue;
+      }
+      notGated.push(name);
+      continue;
+    }
+
+    gated.push(name);
     if (!EXACT_VERSION.test(version)) {
       violations.push({
         package: name,
@@ -104,7 +126,7 @@ function checkLibCompat(pkg, librarySet) {
 
   return {
     ok: violations.length === 0,
-    gated: gated.map(([name]) => name),
+    gated,
     notGated,
     violations
   };

package/src/utils/migrationOrder.js

@@ -0,0 +1,163 @@
+'use strict';
+
+/**
+ * The order migrations are applied in — ONE definition, shared with the operator.
+ *
+ * The schema of one service is built by two runners: `ci:gate:setup` (this
+ * package, `setupDatabase.js`) proves the set in CI, and the operator script
+ * `api/scripts/apply-oagen-meta-install-sql.sh` builds the real installation
+ * with `find … -name '*.sql' | LC_ALL=C sort -V`. The installation is the
+ * reference: CI has to prove the artefact the operator produces, not one of its
+ * own (`.claude/rules/architecture-principles.md` § Version pinning — CI proving
+ * one artefact while the deployment runs another is the defect class, and with
+ * migrations the order IS semantics: two files that touch the same table give a
+ * different result, or fail, when swapped).
+ *
+ * Until this module existed the CI side used JavaScript `Array#sort`, which is
+ * lexicographic by UTF-16 code unit. On three-digit zero-padded prefixes the two
+ * agree, which is why the divergence was reported as latent (BIZ-META
+ * 2026-08-29). It is not latent: measured 2026-09-14 over
+ * `api_biz/property/migrations` (87 files), `999_layer_tick.sql` is applied
+ * LAST by `sort -V` and FIRST of the `999*` group by `Array#sort`, because `_`
+ * (0x5F) precedes `a` (0x61) lexicographically while version order compares the
+ * digit run first and only then the bytes after it.
+ *
+ * So this is a port of what `sort -V` actually does — GNU coreutils `filevercmp`
+ * over gnulib `verrevcmp` — and not an approximation of it that happens to agree
+ * on today's file names. Its expectations are taken from the real tool's output,
+ * never from reasoning about it (`.claude/rules/architecture-principles.md`
+ * §10a).
+ *
+ * @see api/scripts/apply-oagen-meta-install-sql.sh
+ */
+
+/** Byte-wise, because `LC_ALL=C sort -V` compares bytes and not code points. */
+function isDigit(byte) {
+  return byte >= 0x30 && byte <= 0x39;
+}
+
+/**
+ * gnulib `order()`: within a non-digit run, letters sort before every other
+ * punctuation byte, and `~` sorts before everything including the end of the
+ * string. That is what puts `999a_x.sql` ahead of `999_x.sql`.
+ */
+function order(byte) {
+  if (isDigit(byte)) return 0;
+  if ((byte >= 0x41 && byte <= 0x5A) || (byte >= 0x61 && byte <= 0x7A)) return byte;
+  if (byte === 0x7E) return -1;
+  return byte + 256;
+}
+
+/**
+ * gnulib `verrevcmp`: alternate between non-digit runs (compared through
+ * `order`) and digit runs (compared numerically, leading zeros skipped).
+ *
+ * @param {Buffer} a
+ * @param {Buffer} b
+ * @returns {number}
+ */
+function verrevcmp(a, b) {
+  let i = 0;
+  let j = 0;
+
+  while (i < a.length || j < b.length) {
+    let firstDiff = 0;
+
+    while ((i < a.length && !isDigit(a[i])) || (j < b.length && !isDigit(b[j]))) {
+      const ca = i === a.length ? 0 : order(a[i]);
+      const cb = j === b.length ? 0 : order(b[j]);
+      if (ca !== cb) return ca - cb;
+      i += 1;
+      j += 1;
+    }
+
+    while (a[i] === 0x30) i += 1;
+    while (b[j] === 0x30) j += 1;
+
+    while (i < a.length && j < b.length && isDigit(a[i]) && isDigit(b[j])) {
+      if (firstDiff === 0) firstDiff = a[i] - b[j];
+      i += 1;
+      j += 1;
+    }
+
+    // A digit run that outlives the other one is the larger number: `10` beats
+    // `9` even though `9` beats `1` byte for byte.
+    if (i < a.length && isDigit(a[i])) return 1;
+    if (j < b.length && isDigit(b[j])) return -1;
+    if (firstDiff !== 0) return firstDiff;
+  }
+
+  return 0;
+}
+
+/**
+ * gnulib `file_prefixlen`: where the file suffix starts, as a byte offset.
+ *
+ * The suffix is the trailing run of `(\.[A-Za-z~][A-Za-z0-9~]*)+`, and it is
+ * compared only after the bases are equal — otherwise `010_a.sql` would sort
+ * after `010_ab.sql`, because `.` (0x2E) precedes `b` under `order` and the
+ * comparison would reach the dot before the name had ended.
+ *
+ * @param {string} name
+ * @returns {number} byte offset where the suffix begins, or the full length
+ */
+function suffixOffset(name) {
+  const match = /(?:\.[A-Za-z~][A-Za-z0-9~]*)+$/.exec(name);
+  if (match === null) return Buffer.byteLength(name, 'utf8');
+  return Buffer.byteLength(name.slice(0, match.index), 'utf8');
+}
+
+/**
+ * Compare two file names the way `LC_ALL=C sort -V` orders them.
+ *
+ * The hidden-file cases come first, exactly as gnulib `filevercmp` has them:
+ * `.` before `..` before every other dot-name before every ordinary name.
+ * Measured — `sort -V` puts `.sql` ahead of `000_a.sql`, which the suffix
+ * comparison alone gets backwards.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} negative when `a` is applied first, positive when `b` is
+ */
+function compareVersion(a, b) {
+  if (a === b) return 0;
+  if (a === '') return -1;
+  if (b === '') return 1;
+  if (a === '.') return -1;
+  if (b === '.') return 1;
+  if (a === '..') return -1;
+  if (b === '..') return 1;
+
+  const aHidden = a.startsWith('.');
+  const bHidden = b.startsWith('.');
+  if (aHidden && !bHidden) return -1;
+  if (!aHidden && bHidden) return 1;
+
+  const x = aHidden ? a.slice(1) : a;
+  const y = bHidden ? b.slice(1) : b;
+
+  const xb = Buffer.from(x, 'utf8');
+  const yb = Buffer.from(y, 'utf8');
+
+  const base = verrevcmp(xb.subarray(0, suffixOffset(x)), yb.subarray(0, suffixOffset(y)));
+  if (base !== 0) return base;
+
+  const whole = verrevcmp(xb, yb);
+  if (whole !== 0) return whole;
+
+  // `sort` falls back to the plain byte comparison for names version order
+  // cannot separate, so two names never compare equal unless they are equal.
+  return Buffer.compare(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));
+}
+
+/**
+ * The migration files of one directory, in the order they are applied.
+ *
+ * @param {string[]} names
+ * @returns {string[]} a new array; the input is left alone
+ */
+function sortByVersion(names) {
+  return [...names].sort(compareVersion);
+}
+
+module.exports = { compareVersion, sortByVersion };