@bongos/core 1.19.590 → 1.19.592

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.592",
+  "core_contract": "1.19.592",
+  "source_commit": "0a1abcd19a9b10e8a397d736bca30bf3cde53e12",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T02:32:23.112Z",
+  "built_at": "2026-09-08T02:51:06.758Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2061,
+    "functional_verbatim": 2065,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2542,
-  "tree_sha256": "ff91f93bb16afd98f8d2130615c602425ac4d133c4b01c83fbe94e6d8015f2cc",
+  "file_count": 2546,
+  "tree_sha256": "25f1a2e82d0354d67b93d0215ffb20b0afae0240e24c02eb2683ac075c62e755",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "c2736a86c941e12d08b38f798ab18eddf8a365ef709ed952778629d13ebf4e1d"
+      "sha256": "2b198dcf7147b6d736ec28fe28fb7b4c97727df4573dcb3017fd00e8efc756a8"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3729,6 +3729,11 @@
       "mode": "0000644",
       "sha256": "5ed2ff8117e6650de621a1576062b27f2d6e84faf8860f9cb2aed45323a85aa6"
     },
+    {
+      "path": "migrations/core_233_versions_one_planning_idx.sql",
+      "mode": "0000644",
+      "sha256": "ca03e583bc418f600c1b1ba464bcaf4e380916033ec06cd68990cf153184d883"
+    },
     {
       "path": "modules/agents/lib/validate.js",
       "mode": "0000644",
@@ -5792,12 +5797,12 @@
     {
       "path": "modules/lifecycle/routes/version-route-authz.js",
       "mode": "0000644",
-      "sha256": "5db4f94ca52f634f41cdb489572e43eb6785744220d2565a716cff47bfa72b30"
+      "sha256": "a978720f7e0fa63626978c507e4a6a001faeab95989bc0ceb3cedd02f36b40d3"
     },
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "5efe819220f9128844793a0c068babcd402860b434aab322fd9a99f8d2d26167"
+      "sha256": "432dc7d632e2f528bc885348bd878ea19dc94d1395d5e6f51b39ebf39c5f91ca"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -7602,12 +7607,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "035ec486f26d0a18ffcc578a861b2758f79ea279371c4f88dfe5fdfa1b04fefe"
+      "sha256": "ef993eb06f7e089d4a9cfed05d07ec4bc19aa542517543b2bff2d8d2259242f5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "05c57c598f80ce768e83bc0040feb275732545150cbcb3cd01341ff3633ea96f"
+      "sha256": "a8f9e814cd551d7a4ec38257da9398e9f93b361f1a27e7837c94a2cb794f693b"
     },
     {
       "path": "public-docs/index.html",
@@ -8087,7 +8092,7 @@
     {
       "path": "scripts/gds/gds-literal-scan.js",
       "mode": "0000644",
-      "sha256": "fe622c9abf848a668fe2672d699fef22141156f41bb2396523461d1484341ec1"
+      "sha256": "3f873da74a012f73e30e659f070b3476eda81ac55f802913307494a645d8ee88"
     },
     {
       "path": "scripts/gds/gen-api-client.js",
@@ -8454,6 +8459,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 +9327,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b2b2d8c9ccf065e7bbc7b984ff9acda5f4400c9db4e9063678e6d996616f7d1c"
+      "sha256": "f089d18d9173dcae6228221928c87d6d0142ca1cfdd7b0d8743ad87d67e8054d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11512,7 +11522,7 @@
     {
       "path": "tests/one_planning_version.mjs",
       "mode": "0000644",
-      "sha256": "1f8c6924dac2c922a1f88c22693b4386ec16d5f0ae346609b3d1dc0003308a70"
+      "sha256": "347d8856d88246e08abcdfcaf744b491821f95f0daaab0291c4f9bb2a427ed6b"
     },
     {
       "path": "tests/origin_containment.mjs",
@@ -11959,6 +11969,11 @@
       "mode": "0000644",
       "sha256": "a7a0a61260a4ee78f5452b76ee6d8ef732104cf9c32a3c05bfa25517bf883aeb"
     },
+    {
+      "path": "tests/rename_history_restraint.mjs",
+      "mode": "0000644",
+      "sha256": "2cbc4981c0f33a6597445f268055d10107b6696be4de42e5790e7efefc087edd"
+    },
     {
       "path": "tests/render_prefs.mjs",
       "mode": "0000644",
@@ -12644,6 +12659,11 @@
       "mode": "0000644",
       "sha256": "808a5fb2e14fb03ded6ed5ea0b3c0a0a7f53bfb885e853acb225f7b439a06ac3"
     },
+    {
+      "path": "tests/version_build_slot.mjs",
+      "mode": "0000644",
+      "sha256": "795946106f5e562a55f0ad04f3226884ee7815a86f8c20b94220e8069e192c41"
+    },
     {
       "path": "tests/version_close.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1629,5 +1629,9 @@ 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)
+  1.19.592 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.591 with no explicit bump. run 34181434332. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_233_versions_one_planning_idx.sql

@@ -0,0 +1,47 @@
+-- core_233_versions_one_planning_idx.sql — exactly one version may sit in
+-- `planning` (BV1.R19, task 1003606, goal 1000086, ADR 0250 D5, ADR 0263 §9).
+--
+-- WHAT THIS CLOSES. R04 (task 1003592) shipped the one-planning-version rule as a
+-- check-then-insert in `routes/versions.js`, and documented IN THE ROUTE that no
+-- database constraint backs it: two concurrent POST /versions with status=planning
+-- could both pass, because unlike the id collision above it, nothing catches this
+-- one. That comment names this task as the place to fix it. This index is that fix
+-- — the race now resolves the way the id collision already does, with a 23505 the
+-- route translates into the same clean named 409.
+--
+-- WHY ONLY THE PLANNING INDEX, WHEN ADR 0263 §9 ASKS FOR TWO.
+-- The ADR is right that both rules have the same shape and should be backed the
+-- same way. It could not see that the live database VIOLATES the building rule
+-- today: BONGOS-V1 and CB-V1 are both `building`, which is the exact violation
+-- R27 (task 1003614) exists to resolve, and which R19's own brief acknowledges
+-- ("R27 resolves the existing violation").
+--
+-- A migration is applied ONCE and tracked by filename stem (scripts/migrate.sh),
+-- so the two ways to write the building index here are both wrong:
+--   * unconditionally — CREATE UNIQUE INDEX raises on the duplicate rows, the
+--     migration fails, and every deploy of the live instance wedges behind a data
+--     cutover that has not happened yet;
+--   * conditionally, skipping with a NOTICE — it lands "applied", never runs
+--     again, and the constraint silently never arms. That is worse than not
+--     shipping it, because the route comment would then point at a guard that
+--     does not exist.
+-- So the building index ships with R27, in the same migration as the data fix
+-- that makes it legal. Constraint and cutover land together or neither does.
+-- R19's own deliverable — "the server refuses a second building version; a named
+-- 409; a test covers it" — is the ROUTE rule, which lands complete here.
+--
+-- ON "per project": this instance's `versions` table has no project column
+-- (migration 003) — a Bongos database IS one project — so "one version plans per
+-- project" and "one version plans in this table" are the same statement. If a
+-- project column ever lands, this becomes a partial index on (project_id).
+--
+-- CORE, not modules/lifecycle/migrations/: `versions` is a CORE table (migration
+-- 003), and a module migration may only touch its own <key>_-prefixed objects —
+-- fitness.js checkModuleMigrationsAdditive hard-fails an `ALTER TABLE versions`
+-- from a module (ADR 0083 Decision #5).
+--
+-- Legal on the live data as written: zero versions are `planning` today.
+
+CREATE UNIQUE INDEX IF NOT EXISTS versions_one_planning_idx
+    ON versions ((status))
+ WHERE status = 'planning';

package/modules/lifecycle/routes/version-route-authz.js

@@ -53,4 +53,44 @@ function authorizeVersionCreate({ status, planning = [] }) {
   };
 }
 
-module.exports = { authorizeVersionCreate };
+// authorizeVersionBuild — may a version ENTER `building` in this state?
+// (BV1.R19, task 1003606, goal 1000086, ADR 0250 D5, ADR 0263 §9.)
+//
+// THE RULE: exactly one version builds at a time. This is the invariant every
+// other rule in this goal stands on, and the one the live instance breaks today:
+// BONGOS-V1 and CB-V1 are both `building`, which is why "the current version" has
+// no meaning here. `currentBuildingVersionId` resolves that ambiguity with an
+// `ORDER BY started_at DESC ... LIMIT 1` — it picks one and says nothing — so
+// R03's gate ("is this version still in planning?") silently has two answers
+// depending on which row won. Task 1003614 (R27) resolves the existing violation;
+// this stops a third from ever being created.
+//
+// THE TWIN OF authorizeVersionCreate, and deliberately a SEPARATE function rather
+// than a second branch inside it. The two guard different slots, and this one has
+// a second caller coming: the close flow promotes the planning version to
+// `building` in its own transaction (task 1003607, R20), where there is no
+// caller-supplied `status` to branch on. One function taking a status would force
+// that path to pass a value it is not setting.
+//
+// `building` is the versions already in that state (id + name), read by the
+// caller. Passing the rows rather than a boolean lets the refusal NAME the
+// version holding the slot — the caller's next move is to close it or scope onto
+// it, and neither is answerable from a bare "no".
+//
+// Returns { ok: true } or { ok: false, status, body } — the exact HTTP status and
+// JSON the route sends.
+function authorizeVersionBuild({ building = [] }) {
+  const existing = Array.isArray(building) ? building.filter(Boolean) : [];
+  if (existing.length === 0) return { ok: true };
+  return {
+    ok: false,
+    status: 409,
+    body: {
+      error: 'building_version_exists',
+      message: `Version '${existing[0].id}' is already building — close it first, or scope this work onto it. One version builds at a time.`,
+      building: existing,
+    },
+  };
+}
+
+module.exports = { authorizeVersionCreate, authorizeVersionBuild };

package/modules/lifecycle/routes/versions.js

@@ -23,7 +23,7 @@ const auth = api;
 const db = require('../db');
 const versionClose = require('../version-close');
 const doneWhen = require('../done-when');
-const { authorizeVersionCreate } = require('./version-route-authz.js');
+const { authorizeVersionCreate, authorizeVersionBuild } = require('./version-route-authz.js');
 const { asyncHandler, validateOrRespond } = api;
 
 // versions.status CHECK (migration 003). A new version starts 'planning' or
@@ -128,15 +128,11 @@ module.exports = function buildVersionsRouter() {
     // sibling of R03's authorizeGoalCreate — the route gathers the facts and
     // renders the verdict, it does not carry the rule.
     //
-    // RACE, ACCEPTED AND UNMITIGATED: this is check-then-insert, and no database
-    // constraint backs it — two concurrent POST /versions with status=planning
-    // could both pass. Unlike the id collision above, which Postgres catches on
-    // the primary key, nothing catches this one. The real fix is a partial unique
-    // index (`ON versions (status) WHERE status = 'planning'`), which is a
-    // migration this task did not reserve a number for; task 1003606 (R19) adds
-    // the second-BUILDING-version rule of the same shape and is the natural place
-    // to add the index for both. Until then the exposure is bounded by the route
-    // being Archon-gated and used a few times a year — small, not zero.
+    // THE RACE IS CLOSED (BV1.R19, task 1003606, migration core_233): this is
+    // still check-then-insert, but `versions_one_planning_idx` now backs it, so a
+    // race-loser gets a 23505 that the catch below translates into this same
+    // refusal. R04 shipped this check documenting that nothing caught it; that is
+    // no longer true for the planning slot.
     const versionDecision = authorizeVersionCreate({
       status,
       planning: status === 'planning' ? await db.versionsWithStatus('planning') : [],
@@ -144,6 +140,27 @@ module.exports = function buildVersionsRouter() {
     if (!versionDecision.ok) {
       return res.status(versionDecision.status).json(versionDecision.body);
     }
+
+    // BV1.R19 (task 1003606, goal 1000086, ADR 0250 D5, ADR 0263 §9): the other
+    // half of the same rule. Exactly one version builds at a time — with two,
+    // "the current version" has no meaning and R03's goal-set gate has two
+    // answers depending on which row `currentBuildingVersionId`'s LIMIT 1 picked.
+    //
+    // NOT BACKED BY AN INDEX YET, and that is a data problem rather than an
+    // oversight: BONGOS-V1 and CB-V1 are both `building` on the live instance
+    // today, so `versions_one_building_idx` cannot be created until task 1003614
+    // (R27) folds them. core_233's header records why shipping it early — either
+    // unconditionally, which wedges the deploy, or skipped-with-a-NOTICE, which
+    // marks the migration applied and never arms — is worse than shipping it with
+    // the cutover. Until then this check-then-insert carries the rule alone, with
+    // the same bounded exposure R04 accepted: an Archon-gated route used a few
+    // times a year.
+    const buildDecision = authorizeVersionBuild({
+      building: status === 'building' ? await db.versionsWithStatus('building') : [],
+    });
+    if (!buildDecision.ok) {
+      return res.status(buildDecision.status).json(buildDecision.body);
+    }
     // Normalize criteria: each { criterion_id, criterion_md } (+ optional sort_order).
     const rawCriteria = Array.isArray(body.criteria) ? body.criteria : [];
     const criteria = [];
@@ -176,6 +193,31 @@ module.exports = function buildVersionsRouter() {
       // returns, instead of letting asyncHandler surface a 500 (hacker dispatch,
       // task 1204).
       if (err && err.code === '23505') {
+        // TWO unique constraints can raise here now, and they mean different
+        // things (BV1.R19, migration core_233). `versions_one_planning_idx` is
+        // the race-loser of the one-planning-version rule — the pre-check above
+        // passed because the winner had not committed yet — and must render as
+        // that rule's refusal, not as "this id is taken", which would send the
+        // caller off to rename a version that was never the problem. Matched on
+        // the constraint name rather than the message text, which is localised.
+        if (String(err.constraint || '') === 'versions_one_planning_idx') {
+          // Re-read rather than reuse the pre-check's rows: the winner has
+          // committed by now, so this read is what names it.
+          //
+          // The refusal is still rendered BY THE GATE, not written here — this
+          // route must never carry a second copy of the rule's wording, which is
+          // what tests/one_planning_version.mjs pins. The index only raises when
+          // a planning row exists, so the re-read is non-empty in every real
+          // case; the fallback row covers the one interleaving where the winner
+          // was deleted between the raise and this read, and exists solely so the
+          // gate cannot be handed an empty list and return `ok` with no body.
+          const planningNow = await db.versionsWithStatus('planning');
+          const raced = authorizeVersionCreate({
+            status: 'planning',
+            planning: planningNow.length ? planningNow : [{ id: '(a concurrent create)', name: '' }],
+          });
+          return res.status(raced.status).json(raced.body);
+        }
         return res.fail('version_exists', { status: 409, message: `Version '${id}' already exists.` });
       }
       throw err;

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.590",
+  "version": "1.19.592",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.590",
+      "version": "1.19.592",
       "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.592",
   "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.592'; // 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/one_planning_version.mjs

@@ -141,14 +141,31 @@ test('the default status is planning, so an unqualified create hits the gate', (
   assert.match(ROUTE, /const status = body\.status \|\| 'planning';/);
 });
 
-test('the accepted race is described as unmitigated, because it is', () => {
-  // An earlier draft of this comment said the race was "left to a partial unique
-  // index" — which reads as though one exists. It does not, and a future reader
-  // taking that at face value would believe two concurrent creates cannot both
-  // slip through. Pinned so the honest wording cannot quietly regress.
-  assert.match(ROUTE, /RACE, ACCEPTED AND UNMITIGATED/);
-  assert.match(ROUTE, /no database\s*\n?\s*\/\/ constraint backs it/,
-    'the comment must say plainly that nothing catches it');
+test('the planning race is now BACKED, and the comment says so honestly', () => {
+  // WHAT THIS TEST USED TO ASSERT, AND WHY IT FLIPPED. Until BV1.R19 (task
+  // 1003606) this pinned the words "RACE, ACCEPTED AND UNMITIGATED", because an
+  // earlier draft of the comment claimed the race was "left to a partial unique
+  // index" when no such index existed — a future reader taking that at face
+  // value would have believed two concurrent creates could not both slip
+  // through. R19 shipped the index (migration core_233), so the old wording is
+  // now the dishonest one. The TEST'S PURPOSE is unchanged: the comment must
+  // describe the mitigation that actually exists, no more and no less.
+  assert.match(ROUTE, /THE RACE IS CLOSED/);
+  assert.match(ROUTE, /versions_one_planning_idx/,
+    'the comment must name the index that backs it, so the claim is checkable');
+  assert.equal(/RACE, ACCEPTED AND UNMITIGATED/.test(ROUTE), false,
+    'the planning race is mitigated as of R19 — the old wording would now under-claim');
+});
+
+test('the BUILDING half is still unmitigated, and the comment does not pretend otherwise', () => {
+  // The other half of the same honesty rule, and the one that matters now. R19
+  // could only ship ONE of ADR 0263 §9's two indexes: the live instance has two
+  // `building` versions, so `versions_one_building_idx` cannot be created until
+  // task 1003614 (R27) folds them. The building slot is therefore guarded by a
+  // check-then-insert with nothing behind it — exactly the state the planning
+  // slot was in before — and a reader who assumed symmetry would be wrong.
+  assert.match(ROUTE, /NOT BACKED BY AN INDEX YET/);
+  assert.match(ROUTE, /1003614/, 'the comment must name the task that makes the index legal');
 });
 
 // ---- the rule is one half of a pair ----------------------------------------

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'));
+});

package/tests/version_build_slot.mjs

@@ -0,0 +1,157 @@
+// tests/version_build_slot.mjs — exactly one version builds at a time
+// (BV1.R19, task 1003606, goal 1000086, ADR 0250 D5, ADR 0263 §9).
+//
+// THE INVARIANT EVERY OTHER RULE IN THIS GOAL STANDS ON. R03 refuses a goal on a
+// version that is not `planning`, which presumes "the version that is building"
+// names ONE row. With two, it does not: `currentBuildingVersionId` resolves the
+// ambiguity with `ORDER BY started_at DESC ... LIMIT 1`, so it picks one and says
+// nothing, and R03's gate silently has two answers depending on which row won.
+// The live instance is in exactly that state today (BONGOS-V1 and CB-V1 both
+// `building`) — task 1003614 (R27) resolves it; this file pins that a third can
+// never be created.
+//
+// WHY THE PREDICATE IS TESTED, NOT THE ROUTE. authorizeVersionBuild is pure — no
+// express, no DB, no pool — so its whole truth table runs here, including the
+// shapes a live-Postgres test would never bother to set up: a null in the rows, a
+// non-array, an absent argument. The ROUTE's job is only to gather the facts and
+// render the verdict verbatim, and the source assertions at the bottom pin that
+// it does exactly that and nothing else. Inlining the rule in the handler would
+// leave it testable only by string-matching the source, which passes just as
+// happily on a wrong branch.
+//
+// Run:  node --test tests/version_build_slot.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { authorizeVersionBuild, authorizeVersionCreate } =
+  require('../modules/lifecycle/routes/version-route-authz.js');
+
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const ROUTES = src('modules/lifecycle/routes/versions.js');
+const MIGRATION = src('migrations/core_233_versions_one_planning_idx.sql');
+
+// ---------------------------------------------------------------------------
+// The rule
+// ---------------------------------------------------------------------------
+
+test('an empty building slot allows the version', () => {
+  assert.deepEqual(authorizeVersionBuild({ building: [] }), { ok: true });
+});
+
+test('no argument at all is allowed — the default is "nothing is building"', () => {
+  assert.deepEqual(authorizeVersionBuild({}), { ok: true });
+});
+
+test('one building version refuses, with a named 409', () => {
+  const v = authorizeVersionBuild({ building: [{ id: 'BONGOS-V1', name: 'Cloud Bongos — platform (V1)' }] });
+  assert.equal(v.ok, false);
+  assert.equal(v.status, 409);
+  assert.equal(v.body.error, 'building_version_exists');
+});
+
+test('the refusal NAMES the version holding the slot, in the message and the payload', () => {
+  const v = authorizeVersionBuild({ building: [{ id: 'BONGOS-V1', name: 'platform' }] });
+  // The whole reason the rows are passed instead of a boolean: a caller told only
+  // "no" has to go look up which version to close, and a caller who looks it up
+  // is one step from cutting a version to get around the gate anyway.
+  assert.match(v.body.message, /BONGOS-V1/);
+  assert.deepEqual(v.body.building, [{ id: 'BONGOS-V1', name: 'platform' }]);
+});
+
+test('the live two-building-version violation refuses, and names the first', () => {
+  const v = authorizeVersionBuild({
+    building: [{ id: 'BONGOS-V1', name: 'platform' }, { id: 'CB-V1', name: 'dogfood' }],
+  });
+  assert.equal(v.ok, false);
+  assert.equal(v.body.building.length, 2);
+  assert.match(v.body.message, /BONGOS-V1/);
+});
+
+// ---------------------------------------------------------------------------
+// Shapes a live-Postgres test would not set up
+// ---------------------------------------------------------------------------
+
+test('nulls in the rows do not count as a version', () => {
+  assert.deepEqual(authorizeVersionBuild({ building: [null, undefined] }), { ok: true });
+});
+
+test('a non-array building is treated as empty, not as truthy', () => {
+  // A caller that hands over a bare count, or a bad DB read that returns an
+  // object, must not be able to LOOSEN the rule by accident — but neither should
+  // it hard-refuse a legitimate create. Both degrade to "nothing is building",
+  // which is the state the pre-check will then re-derive from the real table.
+  for (const bad of [1, 'yes', {}, null, undefined]) {
+    assert.deepEqual(authorizeVersionBuild({ building: bad }), { ok: true }, `building=${JSON.stringify(bad)}`);
+  }
+});
+
+test('the two slot rules are independent — building says nothing about planning', () => {
+  // Guards against a future refactor collapsing them into one status-branching
+  // function: the close flow (task 1003607, R20) promotes a version to `building`
+  // with no caller-supplied status to branch on.
+  assert.deepEqual(authorizeVersionBuild({ building: [] }), { ok: true });
+  assert.equal(authorizeVersionCreate({ status: 'planning', planning: [{ id: 'X' }] }).ok, false);
+  assert.equal(authorizeVersionCreate({ status: 'building', planning: [{ id: 'X' }] }).ok, true);
+});
+
+// ---------------------------------------------------------------------------
+// The wiring: the route gathers the facts and renders the verdict
+// ---------------------------------------------------------------------------
+
+test('POST /versions consults the building slot, and only when status is building', () => {
+  assert.match(ROUTES, /authorizeVersionBuild\(\{/);
+  // The read is CONDITIONAL on the requested status, mirroring the planning one:
+  // creating a `shipped` or `frozen` row is archival bookkeeping and must not pay
+  // for a query, nor be refused by a rule about a slot it is not entering.
+  assert.match(ROUTES, /status === 'building' \? await db\.versionsWithStatus\('building'\) : \[\]/);
+});
+
+test('the route renders the refusal verbatim — it does not restate the rule', () => {
+  assert.match(ROUTES, /if \(!buildDecision\.ok\) \{\s*return res\.status\(buildDecision\.status\)\.json\(buildDecision\.body\);/);
+  // No second copy of the message anywhere in the route.
+  assert.equal(ROUTES.includes('One version builds at a time'), false);
+});
+
+test('a 23505 on the planning index renders as the planning rule, not "id taken"', () => {
+  // The race-loser's pre-check passed because the winner had not committed. If
+  // this fell through to `version_exists` the caller would be told to rename a
+  // version that was never the problem, and would rename and retry forever.
+  assert.match(ROUTES, /err\.constraint\s*\|\|\s*''\)\s*===\s*'versions_one_planning_idx'/);
+  // And it renders that refusal BY RE-RUNNING THE GATE, never by writing the
+  // wording a second time — tests/one_planning_version.mjs pins the absence of
+  // the literal `planning_version_exists` in this handler, and an earlier draft
+  // of this very test asserted its presence, which is how the two suites caught
+  // each other. The gate owns the words; the route owns only the plumbing.
+  assert.match(ROUTES, /const raced = authorizeVersionCreate\(\{/);
+  assert.match(ROUTES, /return res\.status\(raced\.status\)\.json\(raced\.body\);/);
+});
+
+// ---------------------------------------------------------------------------
+// The migration
+// ---------------------------------------------------------------------------
+
+test('core_233 creates the planning index and NOT the building one', () => {
+  assert.match(MIGRATION, /CREATE UNIQUE INDEX IF NOT EXISTS versions_one_planning_idx/);
+  assert.match(MIGRATION, /WHERE status = 'planning'/);
+  // The deliberate omission ADR 0263 §9 asked for and the live data forbids. If a
+  // later edit adds it here, this test is the reminder that the migration will
+  // fail on any instance with two building versions — and that a skipped-with-a-
+  // NOTICE variant marks itself applied and never arms.
+  assert.equal(MIGRATION.includes('versions_one_building_idx'), false,
+    'the building index ships with R27 (task 1003614), in the migration that makes it legal');
+});
+
+test('the migration records WHY the building index is not here', () => {
+  // The reasoning is the artifact: without it the next reader files this as an
+  // oversight and "fixes" it into a wedged deploy.
+  assert.match(MIGRATION, /1003614/);
+});
+
+test('the route points at the same reason', () => {
+  assert.match(ROUTES, /1003614/);
+});