@bongos/core 1.19.591 → 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.591",
-  "core_contract": "1.19.591",
-  "source_commit": "1a5d5f0eb546f0430b57a3ca5446be6ebd135fe9",
+  "core_version": "1.19.592",
+  "core_contract": "1.19.592",
+  "source_commit": "0a1abcd19a9b10e8a397d736bca30bf3cde53e12",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T02:46:21.428Z",
+  "built_at": "2026-09-08T02:51:06.758Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2063,
+    "functional_verbatim": 2065,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2544,
-  "tree_sha256": "8c944ccd379b18b96ad8d347ecc09ae1d5a3d163d40ca3c446e9bce07f86a002",
+  "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": "32f8765fbbc0999a25b5abfc0f58a5dc5980db09c03ff4ee127b6774387c865a"
+      "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": "b89e31e9693695643d5effcfe1386164ec4b8759e50fec6d86fe4edf19f09cb6"
+      "sha256": "ef993eb06f7e089d4a9cfed05d07ec4bc19aa542517543b2bff2d8d2259242f5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "09428614577361d939096da4a4a91a0f742a0504d97168cdea6d169ccb8931be"
+      "sha256": "a8f9e814cd551d7a4ec38257da9398e9f93b361f1a27e7837c94a2cb794f693b"
     },
     {
       "path": "public-docs/index.html",
@@ -9322,7 +9327,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "5c9d16a923a0cb30e18960d8714e1e8454940d1c4d6cef4d22fa8096a98237ab"
+      "sha256": "f089d18d9173dcae6228221928c87d6d0142ca1cfdd7b0d8743ad87d67e8054d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11517,7 +11522,7 @@
     {
       "path": "tests/one_planning_version.mjs",
       "mode": "0000644",
-      "sha256": "1f8c6924dac2c922a1f88c22693b4386ec16d5f0ae346609b3d1dc0003308a70"
+      "sha256": "347d8856d88246e08abcdfcaf744b491821f95f0daaab0291c4f9bb2a427ed6b"
     },
     {
       "path": "tests/origin_containment.mjs",
@@ -12654,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

@@ -1631,5 +1631,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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.591",
+  "version": "1.19.592",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.591",
+      "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.591",
+  "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/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.591'; // 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/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/);
+});