@bongos/core 1.19.590 → 1.19.591

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.590",
-  "core_contract": "1.19.590",
-  "source_commit": "250f70f068d2406d49d2b57306a8f3f1ebf0f1ab",
+  "core_version": "1.19.591",
+  "core_contract": "1.19.591",
+  "source_commit": "1a5d5f0eb546f0430b57a3ca5446be6ebd135fe9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T02:32:23.112Z",
+  "built_at": "2026-09-08T02:46:21.428Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2061,
+    "functional_verbatim": 2063,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2542,
-  "tree_sha256": "ff91f93bb16afd98f8d2130615c602425ac4d133c4b01c83fbe94e6d8015f2cc",
+  "file_count": 2544,
+  "tree_sha256": "8c944ccd379b18b96ad8d347ecc09ae1d5a3d163d40ca3c446e9bce07f86a002",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "c2736a86c941e12d08b38f798ab18eddf8a365ef709ed952778629d13ebf4e1d"
+      "sha256": "32f8765fbbc0999a25b5abfc0f58a5dc5980db09c03ff4ee127b6774387c865a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7602,12 +7602,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "035ec486f26d0a18ffcc578a861b2758f79ea279371c4f88dfe5fdfa1b04fefe"
+      "sha256": "b89e31e9693695643d5effcfe1386164ec4b8759e50fec6d86fe4edf19f09cb6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "05c57c598f80ce768e83bc0040feb275732545150cbcb3cd01341ff3633ea96f"
+      "sha256": "09428614577361d939096da4a4a91a0f742a0504d97168cdea6d169ccb8931be"
     },
     {
       "path": "public-docs/index.html",
@@ -8087,7 +8087,7 @@
     {
       "path": "scripts/gds/gds-literal-scan.js",
       "mode": "0000644",
-      "sha256": "fe622c9abf848a668fe2672d699fef22141156f41bb2396523461d1484341ec1"
+      "sha256": "3f873da74a012f73e30e659f070b3476eda81ac55f802913307494a645d8ee88"
     },
     {
       "path": "scripts/gds/gen-api-client.js",
@@ -8454,6 +8454,11 @@
       "mode": "0000644",
       "sha256": "4cbb7baf533e1aa2eced1c828f37bbd11f7183846a0f3862f9fb72b3f504be66"
     },
+    {
+      "path": "scripts/gds/rename-history-check.js",
+      "mode": "0000644",
+      "sha256": "06ad6a69304cfc66509f4ab283e7f76196ac7edcac97f8eba55ea3ab92c3eecb"
+    },
     {
       "path": "scripts/gds/render-ideas.js",
       "mode": "0000644",
@@ -9317,7 +9322,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b2b2d8c9ccf065e7bbc7b984ff9acda5f4400c9db4e9063678e6d996616f7d1c"
+      "sha256": "5c9d16a923a0cb30e18960d8714e1e8454940d1c4d6cef4d22fa8096a98237ab"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11959,6 +11964,11 @@
       "mode": "0000644",
       "sha256": "a7a0a61260a4ee78f5452b76ee6d8ef732104cf9c32a3c05bfa25517bf883aeb"
     },
+    {
+      "path": "tests/rename_history_restraint.mjs",
+      "mode": "0000644",
+      "sha256": "2cbc4981c0f33a6597445f268055d10107b6696be4de42e5790e7efefc087edd"
+    },
     {
       "path": "tests/render_prefs.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1629,5 +1629,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.588 with no explicit bump. run 34179479729. (task 1002620)
   1.19.590 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.589 with no explicit bump. run 34180363432. (task 1002620)
+  1.19.591 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.590 with no explicit bump. run 34181177013. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.590",
+  "version": "1.19.591",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.590",
+      "version": "1.19.591",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.590",
+  "version": "1.19.591",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/gds-literal-scan.js

@@ -69,6 +69,13 @@ const GDS_RULE_FILES = new Set([
   'scripts/gds/fitness-ratchets.js',      // the gate: names the metric and carries the builder-facing hint
   'tests/fitness_gds_ratchet.mjs',        // its test, which must write the literal to prove the gate fires
   'config/fitness-baselines.json',        // the baseline's own _comment explains what is counted
+  // The RESTRAINT half of the same rename (task 1003697, criterion C5). It fails
+  // the build when the old name is ERASED from the frozen record, so it has to
+  // name both the literal and the version ids it pins — the same reason this
+  // file is exempt. A gate that cannot state its own rule cannot explain itself.
+  'scripts/gds/rename-history-check.js',
+  'tests/rename_history_restraint.mjs',
+  'config/rename-history-baseline.json',
 ]);
 
 // A version id is a row key, not vocabulary. Stripped before matching so it is

package/scripts/gds/rename-history-check.js

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+'use strict';
+// rename-history-check.js — the RESTRAINT half of the GDS→Bongos rename
+// (criterion C5 of goal 1000073, "history is intact and the alias still
+// answers"; task 1003697).
+//
+// WHY THIS EXISTS, AND WHY IT IS THE MIRROR OF THE RATCHET. Its sibling
+// gds-literal-scan.js + the `legacy_gds_literals` ratchet fail the build when
+// the old name COMES BACK. This module fails the build when the old name is
+// erased from somewhere it must stay. The goal's rule needs both halves:
+//
+//     rename what the project says about itself GOING FORWARD;
+//     leave what it recorded about its PAST.
+//
+// A ratchet alone rewards deletion — the cheapest way to lower a literal count
+// is to sweep the record clean, which is precisely the failure this guards.
+//
+// WHY IT LANDS BEFORE CRITERION C3. C3 renames scripts/gds/ → scripts/bongos/
+// with a codemod across ~1,000 referencing files. The goal calls C3 "the risky
+// criterion" and says C5 is "verified THROUGHOUT the goal, not at the end" —
+// which is not possible without a test. This is that test, built first so the
+// risky pass has something to be verified against.
+//
+// THE FOUR PROPERTIES, and the concrete damage each one prevents:
+//
+//   1. FROZEN FILENAMES — every migration filename, core and module-owned.
+//      schema_migrations is keyed by the filename STEM, so a renamed applied
+//      migration reads as unapplied and RE-RUNS. This is an outage, not an
+//      aesthetic. Two stems in this repo literally carry the old name and sit
+//      directly in a codemod's path:
+//        migrations/019_rename_pms_v3_to_gds_v3.sql
+//        modules/economy/migrations/economy_001_fix_gds_shipper_description.sql
+//      They are the reason this check is a pinned list rather than a pattern.
+//
+//   2. FROZEN LITERAL FLOORS — per-file minimum occurrence counts under the
+//      frozen record (docs/adr, docs/session-logs, docs/audits, limitations).
+//      A FLOOR, not a ceiling: the count may rise as new records are written,
+//      never fall. An ADR rewritten to today's vocabulary destroys the evidence
+//      that the words ever changed, and a per-file floor catches that even
+//      while new files push the directory total up.
+//
+//   3. VERSION ID FLOORS — GDS-V3 / GDS-V4 are row KEYS in the versions table,
+//      not vocabulary. gds-literal-scan.js deliberately strips them before
+//      counting so they stay legal anywhere; the corollary is that nothing else
+//      notices if a blanket find-replace rewrites them. This does.
+//
+//   4. ALIAS MOUNTS — '/api/gds' is a PERMANENT alias (src/bongos/api-prefix.js
+//      says never to remove it: shipped Dev Box binaries and live dev boxes
+//      call it and cannot be force-updated). Asserted against the real exported
+//      mount list. The DISPATCH half — that the alias is a live mount and so
+//      gets no corrective 404 hint — is already covered by
+//      tests/api_path_404.mjs and is deliberately not duplicated here.
+//
+// EVERY CHECKER IS PURE and takes its inputs explicitly, so the test can name
+// exactly the paths and counts under test without writing into the repo. That
+// is the gds-literal-scan.js precedent, and it is not tidiness: the unit lane
+// runs test files in parallel, and a test that edits the tree corrupts whatever
+// suite happens to be scanning it.
+//
+// Usage:
+//   node scripts/gds/rename-history-check.js            # verify against the baseline
+//   node scripts/gds/rename-history-check.js --json
+//   node scripts/gds/rename-history-check.js --write    # re-pin the baseline (see below)
+//
+// RE-PINNING. --write is legitimate ONLY when the record genuinely grew — a new
+// migration, a new ADR. It is never the fix for a failing check: if a floor
+// dropped, something erased history, and lowering the floor hides it.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { countInText, GDS_RULE_FILES } = require('./gds-literal-scan.js');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const BASELINE_PATH = path.join(ROOT, 'config', 'rename-history-baseline.json');
+
+// The frozen record. Matched against the repo-relative path at any depth, so an
+// instance's own docs/ and a module-owned migrations/ fall under the same rule
+// as the core's. Kept in step with GDS_EXCLUDED_PATHS in gds-literal-scan.js —
+// the same set of paths, read the opposite way: excluded from the ratchet
+// BECAUSE they are pinned here.
+const FROZEN_RECORD_PATHS = [
+  /(^|\/)docs\/adr\//,
+  /(^|\/)docs\/session-logs\//,
+  /(^|\/)docs\/audits\//,
+  /(^|\/)limitations\//,
+];
+
+// Any path segment named migrations/ — core and module-owned alike.
+const MIGRATION_PATH_RE = /(^|\/)migrations\/[^/]+\.sql$/;
+
+// Version ids that must survive as row keys. Deliberately a literal list and
+// not a pattern: the point is that THESE specific keys still resolve.
+const PINNED_VERSION_IDS = ['GDS-V3', 'GDS-V4'];
+
+// Mounts the server must keep answering on.
+const REQUIRED_ALIAS_MOUNTS = ['/api/gds'];
+
+function isFrozenRecordPath(relPath) {
+  return FROZEN_RECORD_PATHS.some((re) => re.test(relPath));
+}
+
+function isMigrationPath(relPath) {
+  return MIGRATION_PATH_RE.test(relPath);
+}
+
+// ---------- the four checkers (pure) ----------
+
+// checkFrozenFilenames — every pinned migration filename must still exist under
+// exactly that path. A rename shows up as a miss, which is the whole point:
+// schema_migrations keys on the stem, so a rename is a silent re-run.
+function checkFrozenFilenames({ present, pinned }) {
+  const have = new Set(present);
+  const missing = pinned.filter((p) => !have.has(p));
+  return { ok: missing.length === 0, missing };
+}
+
+// checkFrozenLiteralFloors — a per-file FLOOR on occurrences of the old name in
+// the frozen record. A file that vanished counts as zero, so deleting a record
+// fails exactly as loudly as rewriting one.
+function checkFrozenLiteralFloors({ counts, floors }) {
+  const dropped = [];
+  for (const [relPath, floor] of Object.entries(floors)) {
+    const now = Object.prototype.hasOwnProperty.call(counts, relPath) ? counts[relPath] : 0;
+    if (now < floor) dropped.push({ path: relPath, was: floor, now });
+  }
+  return { ok: dropped.length === 0, dropped };
+}
+
+// checkVersionIdFloors — the version ids are row keys; they may be referenced
+// more often over time, never fewer.
+function checkVersionIdFloors({ counts, floors }) {
+  const dropped = [];
+  for (const [id, floor] of Object.entries(floors)) {
+    const now = counts[id] || 0;
+    if (now < floor) dropped.push({ id, was: floor, now });
+  }
+  return { ok: dropped.length === 0, dropped };
+}
+
+// checkAliasMounts — the permanent alias must still be in the mount list.
+function checkAliasMounts({ mounts, required }) {
+  const have = new Set(mounts);
+  const missing = required.filter((m) => !have.has(m));
+  return { ok: missing.length === 0, missing };
+}
+
+// runAll — the four checkers over one set of gathered inputs. Returns every
+// failure rather than short-circuiting: a codemod that broke one property
+// usually broke several, and reporting them one release at a time is useless.
+function runAll({ observed, baseline }) {
+  const results = {
+    frozenFilenames: checkFrozenFilenames({
+      present: observed.migrationFiles,
+      pinned: baseline.migrationFiles,
+    }),
+    frozenLiteralFloors: checkFrozenLiteralFloors({
+      counts: observed.frozenLiteralCounts,
+      floors: baseline.frozenLiteralFloors,
+    }),
+    versionIdFloors: checkVersionIdFloors({
+      counts: observed.versionIdCounts,
+      floors: baseline.versionIdFloors,
+    }),
+    aliasMounts: checkAliasMounts({
+      mounts: observed.aliasMounts,
+      required: REQUIRED_ALIAS_MOUNTS,
+    }),
+  };
+  return { ok: Object.values(results).every((r) => r.ok), results };
+}
+
+// ---------- collectors (touch the repo; kept out of the checkers) ----------
+
+function trackedFiles() {
+  const out = execFileSync('git', ['ls-files'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+function readRepoFile(relPath) {
+  return fs.readFileSync(path.join(ROOT, relPath), 'utf8');
+}
+
+// Compiled ONCE, not per file. observe() reads every tracked file in the repo,
+// so a `new RegExp` inside that loop is thousands of needless compilations on
+// every unit-gate run. Reuse is safe: String.prototype.match with a global
+// regex ignores lastIndex and returns all matches, so the shared objects carry
+// no state between files.
+const VERSION_ID_RES = PINNED_VERSION_IDS.map((id) => [
+  id,
+  new RegExp(id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'),
+]);
+
+// observe — everything the checkers compare against, gathered once.
+// `files` and `readFile` are injectable for the same reason gds-literal-scan.js
+// makes them injectable: so a test can exercise the real aggregation without
+// writing to a tree other suites are reading in parallel.
+function observe({ files = null, readFile = null, aliasMounts = null } = {}) {
+  const read = readFile || readRepoFile;
+  const all = files || trackedFiles();
+
+  const migrationFiles = all.filter(isMigrationPath).sort();
+
+  const frozenLiteralCounts = {};
+  const versionIdCounts = {};
+  for (const id of PINNED_VERSION_IDS) versionIdCounts[id] = 0;
+
+  for (const relPath of all) {
+    let text;
+    try {
+      text = read(relPath);
+    } catch {
+      continue;
+    }
+    if (text.includes(String.fromCharCode(0))) continue; // binary (a NUL byte)
+
+    if (isFrozenRecordPath(relPath)) {
+      const n = countInText(text);
+      if (n) frozenLiteralCounts[relPath] = n;
+    }
+    // The files that STATE the rule are not part of the record they protect.
+    // This module and its test name the version ids as fixtures; counting those
+    // would pin a floor to test data, so editing a test could later red the
+    // build as if history had been erased. Same exemption, same reason, as
+    // GDS_RULE_FILES in the ratchet.
+    if (!GDS_RULE_FILES.has(relPath)) {
+      for (const [id, re] of VERSION_ID_RES) {
+        versionIdCounts[id] += (text.match(re) || []).length;
+      }
+    }
+  }
+
+  let mounts = aliasMounts;
+  if (!mounts) {
+    // Read the real exported mount list rather than grepping for the string —
+    // a comment mentioning the alias must not satisfy the check.
+    mounts = require('../../src/bongos/api-prefix.js').ALL_API_PREFIXES;
+  }
+
+  return { migrationFiles, frozenLiteralCounts, versionIdCounts, aliasMounts: mounts };
+}
+
+function loadBaseline() {
+  return JSON.parse(fs.readFileSync(BASELINE_PATH, 'utf8'));
+}
+
+function baselineFrom(observed) {
+  return {
+    _comment: [
+      'Pinned by scripts/gds/rename-history-check.js (task 1003697, criterion C5 of goal 1000073).',
+      'These are FLOORS on the historical record, the mirror of the legacy_gds_literals ratchet.',
+      'migrationFiles: every migration filename must keep existing verbatim — schema_migrations',
+      'is keyed by the filename stem, so a rename reads as unapplied and RE-RUNS the migration.',
+      'frozenLiteralFloors / versionIdFloors: counts may RISE as the record grows, never fall.',
+      'Re-pin with --write only when the record genuinely grew. A dropped floor means something',
+      'erased history; lowering it hides the erasure instead of fixing it.',
+    ],
+    migrationFiles: observed.migrationFiles,
+    frozenLiteralFloors: observed.frozenLiteralCounts,
+    versionIdFloors: observed.versionIdCounts,
+  };
+}
+
+// ---------- CLI ----------
+
+// describe — the failure report. Names the damage, not just the diff, because
+// the reader is a builder mid-codemod who needs to know what to restore.
+function describe(report) {
+  const lines = [];
+  const { results } = report;
+  if (results.frozenFilenames.missing.length) {
+    lines.push(`frozen filenames MISSING (${results.frozenFilenames.missing.length}) — a renamed applied migration RE-RUNS:`);
+    for (const p of results.frozenFilenames.missing.slice(0, 20)) lines.push(`    ${p}`);
+  }
+  if (results.frozenLiteralFloors.dropped.length) {
+    lines.push(`frozen record ERASED in ${results.frozenLiteralFloors.dropped.length} file(s) — history was rewritten:`);
+    for (const d of results.frozenLiteralFloors.dropped.slice(0, 20)) {
+      lines.push(`    ${d.path}  ${d.was} → ${d.now}`);
+    }
+  }
+  if (results.versionIdFloors.dropped.length) {
+    lines.push('version ids REWRITTEN — these are row keys, not vocabulary:');
+    for (const d of results.versionIdFloors.dropped) lines.push(`    ${d.id}  ${d.was} → ${d.now}`);
+  }
+  if (results.aliasMounts.missing.length) {
+    lines.push(`alias mount REMOVED: ${results.aliasMounts.missing.join(', ')} — shipped clients call it and cannot be updated (src/bongos/api-prefix.js)`);
+  }
+  return lines;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const observed = observe();
+
+  if (argv.includes('--write')) {
+    // Print what re-pinning would ERASE before doing it. --write is legitimate
+    // when the record grew, and is the wrong move when a floor dropped — so the
+    // one thing it must never do is lower a floor silently. Everything under
+    // "removes" below is exactly what the check would have caught.
+    let prior = null;
+    try {
+      prior = loadBaseline();
+    } catch {
+      prior = null;
+    }
+    if (prior) {
+      const lost = describe(runAll({ observed, baseline: prior }));
+      if (lost.length) {
+        console.log('re-pinning would LOWER the record — read this before committing:\n');
+        for (const line of lost) console.log(`  ${line}`);
+        console.log('\nIf that was not deliberate, restore what was renamed or erased instead.\n');
+      }
+    }
+
+    fs.writeFileSync(BASELINE_PATH, `${JSON.stringify(baselineFrom(observed), null, 2)}\n`);
+    console.log(`re-pinned ${path.relative(ROOT, BASELINE_PATH)}`);
+    const priorMigrations = prior ? prior.migrationFiles.length : 0;
+    const priorFrozen = prior ? Object.keys(prior.frozenLiteralFloors).length : 0;
+    console.log(`  ${observed.migrationFiles.length} migration filename(s)  (was ${priorMigrations})`);
+    console.log(`  ${Object.keys(observed.frozenLiteralCounts).length} frozen-record file(s)  (was ${priorFrozen})`);
+    console.log(`  version ids: ${Object.entries(observed.versionIdCounts).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+    return;
+  }
+
+  const baseline = loadBaseline();
+  const report = runAll({ observed, baseline });
+
+  if (argv.includes('--json')) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exitCode = report.ok ? 0 : 1;
+    return;
+  }
+
+  if (report.ok) {
+    console.log('rename restraint: OK — history intact, alias still mounted');
+    console.log(`  ${baseline.migrationFiles.length} migration filename(s) unchanged`);
+    console.log(`  ${Object.keys(baseline.frozenLiteralFloors).length} frozen-record file(s) at or above their floor`);
+    console.log(`  version ids: ${Object.entries(observed.versionIdCounts).map(([k, v]) => `${k}=${v}`).join(' ')}`);
+    console.log(`  mounts: ${observed.aliasMounts.join(' ')}`);
+    return;
+  }
+
+  console.error('rename restraint: FAILED — the record changed where it must not\n');
+  for (const line of describe(report)) console.error(`  ${line}`);
+  console.error('\nThis is not fixed by re-pinning the baseline. Restore what was renamed or erased.');
+  process.exitCode = 1;
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  FROZEN_RECORD_PATHS,
+  MIGRATION_PATH_RE,
+  PINNED_VERSION_IDS,
+  REQUIRED_ALIAS_MOUNTS,
+  isFrozenRecordPath,
+  isMigrationPath,
+  checkFrozenFilenames,
+  checkFrozenLiteralFloors,
+  checkVersionIdFloors,
+  checkAliasMounts,
+  runAll,
+  observe,
+  baselineFrom,
+  loadBaseline,
+  describe,
+  BASELINE_PATH,
+};

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.590'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.591'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/rename_history_restraint.mjs

@@ -0,0 +1,236 @@
+// tests/rename_history_restraint.mjs — the RESTRAINT half of the GDS→Bongos
+// rename (task 1003697, criterion C5 of goal 1000073: "history is intact and
+// the alias still answers").
+//
+// WHY THE NEGATIVE CASES ARE THE LOAD-BEARING ONES. Its sibling
+// tests/fitness_gds_ratchet.mjs makes the same argument and it applies twice as
+// hard here: a restraint check that only asserts today's tree is clean would
+// pass identically if every checker returned "ok" unconditionally. So each of
+// the four properties gets a synthetic FORBIDDEN change and an assertion that
+// the checker FAILS it. The positive case is the cheap half.
+//
+// The checkers are pure and take their inputs explicitly, so every case names
+// its own paths and counts. Nothing here writes to the repo — the unit lane
+// runs test files in parallel, and an earlier version of the ratchet test
+// proved what happens when a suite edits a tree another suite is scanning.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const check = require(path.join(ROOT, 'scripts', 'gds', 'rename-history-check.js'));
+const scan = require(path.join(ROOT, 'scripts', 'gds', 'gds-literal-scan.js'));
+
+const LITERAL = ['G', 'D', 'S'].join(''); // built, not written, so the fixtures below carry no vocabulary of their own
+
+// ---------- 1. frozen filenames: a renamed applied migration RE-RUNS ----------
+
+test('a migration that kept its name passes', () => {
+  const pinned = ['migrations/019_rename_pms_v3_to_gds_v3.sql'];
+  const r = check.checkFrozenFilenames({ present: pinned, pinned });
+  assert.equal(r.ok, true);
+  assert.deepEqual(r.missing, []);
+});
+
+test('a RENAMED migration fails and is named — schema_migrations keys on the stem', () => {
+  const pinned = [
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+  ];
+  // exactly what a scripts/gds/ → scripts/bongos/ codemod would do to these two
+  const present = [
+    'migrations/019_rename_pms_v3_to_bongos_v3.sql',
+    'modules/economy/migrations/economy_001_fix_bongos_shipper_description.sql',
+  ];
+  const r = check.checkFrozenFilenames({ present, pinned });
+  assert.equal(r.ok, false, 'a renamed migration MUST fail — it reads as unapplied and re-runs');
+  assert.deepEqual(r.missing, pinned);
+});
+
+test('a DELETED migration fails the same way as a renamed one', () => {
+  const r = check.checkFrozenFilenames({ present: [], pinned: ['migrations/001_init.sql'] });
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.missing, ['migrations/001_init.sql']);
+});
+
+test('a NEW migration alongside the pinned ones is fine — the list is a floor', () => {
+  const r = check.checkFrozenFilenames({
+    present: ['migrations/001_init.sql', 'migrations/999_new.sql'],
+    pinned: ['migrations/001_init.sql'],
+  });
+  assert.equal(r.ok, true);
+});
+
+// ---------- 2. frozen literal floors: a rewritten ADR erases the evidence ----------
+
+test('an unchanged record passes, and MORE occurrences pass — the floor only stops erasure', () => {
+  const floors = { 'docs/adr/0064-rename.md': 12 };
+  assert.equal(check.checkFrozenLiteralFloors({ counts: { 'docs/adr/0064-rename.md': 12 }, floors }).ok, true);
+  assert.equal(check.checkFrozenLiteralFloors({ counts: { 'docs/adr/0064-rename.md': 30 }, floors }).ok, true);
+});
+
+test('an ADR REWRITTEN to today’s vocabulary fails, with the before/after', () => {
+  const r = check.checkFrozenLiteralFloors({
+    counts: { 'docs/adr/0064-rename.md': 3 },
+    floors: { 'docs/adr/0064-rename.md': 12 },
+  });
+  assert.equal(r.ok, false, 'rewriting the record MUST fail — it destroys the evidence the words changed');
+  assert.deepEqual(r.dropped, [{ path: 'docs/adr/0064-rename.md', was: 12, now: 3 }]);
+});
+
+test('a DELETED record counts as zero — deleting fails as loudly as rewriting', () => {
+  const r = check.checkFrozenLiteralFloors({
+    counts: {},
+    floors: { 'docs/session-logs/2026-09-06-something.md': 4 },
+  });
+  assert.equal(r.ok, false);
+  assert.deepEqual(r.dropped, [{ path: 'docs/session-logs/2026-09-06-something.md', was: 4, now: 0 }]);
+});
+
+test('every dropped file is reported, not just the first', () => {
+  const r = check.checkFrozenLiteralFloors({
+    counts: { 'docs/adr/a.md': 0, 'docs/adr/b.md': 1 },
+    floors: { 'docs/adr/a.md': 5, 'docs/adr/b.md': 5, 'docs/adr/c.md': 5 },
+  });
+  assert.equal(r.dropped.length, 3, 'a codemod breaks many files at once; one-at-a-time reporting is useless');
+});
+
+// ---------- 3. version ids are row keys, not vocabulary ----------
+
+test('version id floors pass when the keys survive, fail on a blanket find-replace', () => {
+  const floors = { 'GDS-V3': 183, 'GDS-V4': 188 };
+  assert.equal(check.checkVersionIdFloors({ counts: { 'GDS-V3': 183, 'GDS-V4': 200 }, floors }).ok, true);
+
+  const r = check.checkVersionIdFloors({ counts: { 'GDS-V3': 0, 'GDS-V4': 188 }, floors });
+  assert.equal(r.ok, false, 'rewriting a version id MUST fail — it is a row key and stops resolving');
+  assert.deepEqual(r.dropped, [{ id: 'GDS-V3', was: 183, now: 0 }]);
+});
+
+test('the ratchet deliberately ignores version ids, so THIS check is the only thing watching them', () => {
+  // gds-literal-scan strips version ids before counting — that is correct for
+  // the ratchet and is exactly why the floors above have to exist.
+  assert.equal(scan.countInText(`${LITERAL}-V3 and ${LITERAL}-V4`), 0);
+  assert.deepEqual(check.PINNED_VERSION_IDS, ['GDS-V3', 'GDS-V4']);
+});
+
+// ---------- 4. the permanent alias mount ----------
+
+test('the alias mount passes while present and FAILS when dropped', () => {
+  const required = ['/api/gds'];
+  assert.equal(check.checkAliasMounts({ mounts: ['/api/bongos/v1', '/api/bongos', '/api/gds'], required }).ok, true);
+
+  const r = check.checkAliasMounts({ mounts: ['/api/bongos/v1', '/api/bongos'], required });
+  assert.equal(r.ok, false, 'shipped Dev Box binaries call the alias and cannot be force-updated');
+  assert.deepEqual(r.missing, ['/api/gds']);
+});
+
+test('the alias is asserted against the real exported mount list, not a grep', () => {
+  // A comment mentioning the alias must not be able to satisfy the check.
+  const { ALL_API_PREFIXES } = require(path.join(ROOT, 'src', 'bongos', 'api-prefix.js'));
+  assert.ok(ALL_API_PREFIXES.includes('/api/gds'), 'src/bongos/api-prefix.js still mounts the permanent alias');
+});
+
+// ---------- runAll: one broken codemod reports every property it broke ----------
+
+test('runAll reports ALL four failures together', () => {
+  const observed = {
+    migrationFiles: [],
+    frozenLiteralCounts: {},
+    versionIdCounts: { 'GDS-V3': 0, 'GDS-V4': 0 },
+    aliasMounts: ['/api/bongos'],
+  };
+  const baseline = {
+    migrationFiles: ['migrations/001_init.sql'],
+    frozenLiteralFloors: { 'docs/adr/0064-rename.md': 12 },
+    versionIdFloors: { 'GDS-V3': 183, 'GDS-V4': 188 },
+  };
+  const report = check.runAll({ observed, baseline });
+  assert.equal(report.ok, false);
+  for (const key of ['frozenFilenames', 'frozenLiteralFloors', 'versionIdFloors', 'aliasMounts']) {
+    assert.equal(report.results[key].ok, false, `${key} should have failed`);
+  }
+  const text = check.describe(report).join('\n');
+  for (const fragment of ['RE-RUNS', 'ERASED', 'REWRITTEN', 'REMOVED']) {
+    assert.ok(text.includes(fragment), `the failure report should say what broke: ${fragment}`);
+  }
+});
+
+// ---------- observe(): the aggregation, on injected inputs ----------
+
+test('observe classifies frozen vs go-forward files and counts version ids everywhere', () => {
+  const files = [
+    'docs/adr/0064-rename.md',
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+    'src/bongos/routes.js',
+  ];
+  const texts = {
+    'docs/adr/0064-rename.md': `the ${LITERAL} acronym, twice: ${LITERAL}. and version GDS-V3`,
+    'migrations/019_rename_pms_v3_to_gds_v3.sql': '-- GDS-V3',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql': '-- nothing',
+    'src/bongos/routes.js': `a go-forward mention of ${LITERAL} that this check does NOT pin`,
+  };
+  const observed = check.observe({
+    files,
+    readFile: (p) => texts[p],
+    aliasMounts: ['/api/gds'],
+  });
+
+  // module-owned migrations are found by the same rule as the core's
+  assert.deepEqual(observed.migrationFiles, [
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+  ]);
+  // the frozen record is floored; a go-forward file is NOT (that is the ratchet's job)
+  assert.deepEqual(Object.keys(observed.frozenLiteralCounts), ['docs/adr/0064-rename.md']);
+  assert.equal(observed.frozenLiteralCounts['docs/adr/0064-rename.md'], 2, 'the version id on the line is not counted as vocabulary');
+  // version ids are counted across every file, frozen or not
+  assert.equal(observed.versionIdCounts['GDS-V3'], 2);
+  assert.equal(observed.versionIdCounts['GDS-V4'], 0);
+});
+
+test('the shared version-id regexes carry no state between files', () => {
+  // observe() compiles the version-id regexes ONCE and reuses them across every
+  // tracked file. That is only safe because String.match with a global regex
+  // ignores lastIndex — so count the same id across several files and assert
+  // none of them are silently skipped.
+  const files = ['a.md', 'b.md', 'c.md', 'd.md'];
+  const observed = check.observe({
+    files,
+    readFile: () => 'GDS-V3 GDS-V3 GDS-V4',
+    aliasMounts: ['/api/gds'],
+  });
+  assert.equal(observed.versionIdCounts['GDS-V3'], 8, 'two per file across four files');
+  assert.equal(observed.versionIdCounts['GDS-V4'], 4);
+});
+
+test('observe skips a binary file instead of guessing at its contents', () => {
+  const observed = check.observe({
+    files: ['docs/adr/logo.png'],
+    readFile: () => `${String.fromCharCode(0)}${LITERAL}`,
+    aliasMounts: ['/api/gds'],
+  });
+  assert.deepEqual(observed.frozenLiteralCounts, {});
+});
+
+// ---------- the committed baseline, and today's tree ----------
+
+test('the committed baseline pins the two migrations that literally carry the old name', () => {
+  const baseline = check.loadBaseline();
+  for (const p of [
+    'migrations/019_rename_pms_v3_to_gds_v3.sql',
+    'modules/economy/migrations/economy_001_fix_gds_shipper_description.sql',
+  ]) {
+    assert.ok(baseline.migrationFiles.includes(p), `baseline must pin ${p} — it sits directly in a codemod's path`);
+  }
+  assert.ok(baseline.migrationFiles.length > 100, 'every migration filename is pinned, not a sample');
+  assert.ok(Object.keys(baseline.frozenLiteralFloors).length > 100, 'the frozen record is pinned per file');
+});
+
+test('today’s tree passes — the cheap half, asserted last', () => {
+  const report = check.runAll({ observed: check.observe(), baseline: check.loadBaseline() });
+  assert.equal(report.ok, true, check.describe(report).join('\n'));
+});