@bongos/core 1.19.600 → 1.19.601

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.600",
-  "core_contract": "1.19.600",
-  "source_commit": "8e02f02563986161d1b77b266027bab29d5534aa",
+  "core_version": "1.19.601",
+  "core_contract": "1.19.601",
+  "source_commit": "16a19ddf0ad7e10177aea562deb878093568f308",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T04:42:02.346Z",
+  "built_at": "2026-09-08T05:00:27.028Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2075,
+    "functional_verbatim": 2076,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2556,
-  "tree_sha256": "a008ff8e9029ba8be4b741e6ce36012a90a005bad10e76f4fed030cee2404487",
+  "file_count": 2557,
+  "tree_sha256": "eb65ec1fb208a9e7c09906234b5a43e7660816544a9b4ae44ecf94d7f64e6260",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -392,7 +392,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "16af99cbe6df845f0f7a90f4569f77550635af0967dce552e2ef07a7b4ef0080"
+      "sha256": "877ca14cd017c1392fcc5206c2f3603fb24becdc32670aa1e2ad0de9d930dfca"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1852,7 +1852,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "f2433a337aed6aa2f0f1a1c2d61b17103b493a028fa03c2944b92b5f3bb5e609"
+      "sha256": "81485c0440de636511dc9ee723e18af89f313b175ea626723d0beeeed31bba2f"
     },
     {
       "path": "docs/architecture.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "251ae2f82d65d325f220649d865bc5413a3febbf493db6994b6f3e9713968ac8"
+      "sha256": "71f84a8b41b3efb16f49909dcf6b6542deecfa51378e24ad271267cf3de1d6a9"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5567,12 +5567,12 @@
     {
       "path": "modules/lifecycle/db-versions.js",
       "mode": "0000644",
-      "sha256": "53f87c20f89c33a3d14ee4410bafa0f3122fb7534708ce5bdacb8cc1098a487c"
+      "sha256": "2c10a17f86506788ab2f9db25c23024120ec9fddb3c7c4894e65d8354cd46869"
     },
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "33fc8959d522bcf18c445b1a5710940379f84d1e938eecdc52cdf52bec9c4b3d"
+      "sha256": "b4b2d6d7890ec67e52fc00718a814bf01a64f4432ed7380a175dca8bc794b0e4"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -5817,7 +5817,7 @@
     {
       "path": "modules/lifecycle/routes/versions.js",
       "mode": "0000644",
-      "sha256": "35919f2cdd1e9a5da11a89adc9731818aa6b1b292c0754d9123a4cd8324bd970"
+      "sha256": "014de34389dbf26b4b089b677466c9c7cfd81f79b9e1714241be12f589086c0f"
     },
     {
       "path": "modules/lifecycle/routes/visuals.js",
@@ -7627,12 +7627,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d3456f52cc8555eb1a20f884dc2d32240032138193c5d525ea455d07423e9656"
+      "sha256": "d9ab931e2e3779b181225611efe7019b45d037bea4249d643574104445931164"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "107d899ff6ec92f0f2dd863f62ab2a68eaa82c7f60d9e172c243b9b5ff421f52"
+      "sha256": "9903e5cd3c9d790a76647c7fff7556c33d900dd119d5b5afd0ada6797508df1d"
     },
     {
       "path": "public-docs/index.html",
@@ -9347,7 +9347,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "fa5a67fefe06f235502a19ee017a75467ab1f5cadf77c2b004edd4109b397ece"
+      "sha256": "de0d452d14fef52118d0302145065609722f6fbdf333fcbf47ec5864cbd3d86a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12719,6 +12719,11 @@
       "mode": "0000644",
       "sha256": "692261c26e3da46519757733a7fcf9a9998e0942bc5890688b66b79590d82c27"
     },
+    {
+      "path": "tests/version_promotion.mjs",
+      "mode": "0000644",
+      "sha256": "43ba25381f3d02d7ecaaa8a2639bb8f1f72587d6966e6498db1c887b289148eb"
+    },
     {
       "path": "tests/version_roll_forward.mjs",
       "mode": "0000644",

package/clients/bongos-client/index.d.ts

@@ -390,7 +390,7 @@ export interface PostTasksNewcomerRestockResponse { ok: boolean; stamped: unknow
 export interface PostTasksRequest { version_id: string; title: string; description?: string; status?: string; touches?: string[]; est_minutes?: number; est_cost_usd?: number; manual_degree?: number; priority?: number; automation_tag?: string; credits_reward?: number; source?: string; source_ref?: string; value_summary?: string; kind?: string; discipline?: string; parallel_safe?: unknown; newcomer_friendly?: boolean; security_sensitive?: boolean; requires_rank?: string; auto_detect_touches?: boolean; criterion_ids?: unknown[]; module_key?: string; goal_id?: number }
 export interface PostTasksResponse { task: unknown; needs_migration: unknown; criteria: unknown; idempotent: boolean }
 export interface PostVersionsIdCloseRequest { reason?: string; dispositions?: Record<string, unknown> }
-export interface PostVersionsIdCloseResponse { ok: boolean; version: unknown; applied: unknown }
+export interface PostVersionsIdCloseResponse { ok: boolean; version: unknown; applied: unknown; promoted: unknown; carried: unknown }
 export interface PostVersionsIdDoneWhenRequest { criterion_id: string; criterion_md: string; goal_id?: number; sort_order?: number }
 export interface PostVersionsIdDoneWhenResponse { ok: boolean; criterion: unknown }
 export interface PostVersionsRequest { id: string; name: string; status?: string; track?: string; done_when?: string; scope_doc_path?: string; criteria?: unknown[] }

package/docs/api/openapi.json

@@ -22494,12 +22494,16 @@
             "type": "boolean"
           },
           "version": {},
-          "applied": {}
+          "applied": {},
+          "promoted": {},
+          "carried": {}
         },
         "required": [
           "ok",
           "version",
-          "applied"
+          "applied",
+          "promoted",
+          "carried"
         ]
       },
       "PostVersionsIdDoneWhenRequest": {

package/docs/module-api-changelog.md

@@ -1649,5 +1649,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.598 with no explicit bump. run 34187136306. (task 1002620)
   1.19.600 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.599 with no explicit bump. run 34187881031. (task 1002620)
+  1.19.601 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.600 with no explicit bump. run 34188958832. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/db-versions.js

@@ -245,14 +245,51 @@ async function openNonMaintenanceGoals(versionId, deps = {}) {
 //     must run INSIDE this transaction and BEFORE any carry-over, because
 //     `ensureMaintenanceGoal` returns null for a non-`building` version. The seam
 //     is `deps.onClosed` below rather than a later edit to this function.
-//   • It does not create successor goals. `roll_forward` here only ABSTAINS from
-//     cutting the goal; task 1003604 (R17) does the lineage write. Until it ships,
-//     a rolled-forward goal simply stays open on the closed version — visible and
-//     recoverable, which is the right failure while half the feature exists.
+//   • It DOES create successor goals now — task 1003604 (R17) shipped, so
+//     `roll_forward` writes the successor, moves the unfinished tasks and records
+//     `succeeded_by_goal_id`. This note used to say the opposite; it is kept,
+//     corrected, because a reader who met the old wording would otherwise go
+//     looking for the abstention it described.
 //   • It does not write `limitations/<version>-shipped.md`. That is a repo file; a
 //     route cannot write one, and file I/O has no business in this transaction.
 //
 // `plan` is planVersionClose's validated output: [{ goalId, verb }].
+// promotePlanningVersion — the single `planning` version becomes the live train
+// (BV1.R20, task 1003607, goal 1000086, ADR 0263 §8).
+//
+// WHY IT RUNS IN THE CLOSE'S TRANSACTION. A project with zero building versions
+// is a BROKEN state, not an intermediate one: `currentBuildingVersionId` returns
+// null there and every routing path closed over it fails, so nothing is
+// claimable. Promoting in a second transaction would leave exactly that window
+// open, however briefly.
+//
+// ZERO PLANNING VERSIONS IS NOT AN ERROR. The close succeeds and the project sits
+// with no live train until someone cuts one. Refusing the close instead would
+// trap a finished version open because nobody had scoped the next one yet — and
+// the close is the thing that makes scoping the next one worth doing.
+//
+// SELF-GUARDING IN SQL rather than by a read-then-write. The `NOT EXISTS`
+// sub-select is what keeps this from creating the second building version R19
+// forbids: it is evaluated inside the same statement, so a concurrent close
+// cannot slip a promotion past a check that has already run. `ORDER BY id LIMIT 1`
+// makes the pick deterministic; R04 guarantees there is at most one to pick.
+//
+// `started_at` is stamped only if it was never set — a version's start is when it
+// began building, and a re-promotion (which cannot happen, but the COALESCE costs
+// nothing) must not rewrite history.
+//
+// Returns the promoted row, or null when there was nothing to promote.
+async function promotePlanningVersion(exec) {
+  const { rows } = await exec.query(
+    `UPDATE versions
+        SET status = 'building', started_at = COALESCE(started_at, now())
+      WHERE id = (SELECT id FROM versions WHERE status = 'planning' ORDER BY id LIMIT 1)
+        AND NOT EXISTS (SELECT 1 FROM versions WHERE status = 'building')
+      RETURNING id, name, track, status, started_at`
+  );
+  return rows[0] ?? null;
+}
+
 async function closeVersion({ versionId, plan = [], reason, planningVersionId = null }, deps = {}) {
   const activePool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool;
   const client = await activePool.connect();
@@ -437,6 +474,7 @@ async function closeVersion({ versionId, plan = [], reason, planningVersionId =
 
 module.exports = {
   closeVersion,
+  promotePlanningVersion,
   createVersion,
   maintenanceGoalExemptSql,
   openNonMaintenanceGoals,

package/modules/lifecycle/db.js

@@ -63,7 +63,7 @@ const {
   singleRungPromotionError,
   xenosClaimAllowed,
 } = require('./db-rank-authz.js');
-const { closeVersion, createVersion, currentBuildingVersionId, getVersion, listVersions, maintenanceGoalExemptSql, openNonMaintenanceGoals, versionProgress, versionsWithStatus } = require('./db-versions.js');
+const { closeVersion, promotePlanningVersion, createVersion, currentBuildingVersionId, getVersion, listVersions, maintenanceGoalExemptSql, openNonMaintenanceGoals, versionProgress, versionsWithStatus } = require('./db-versions.js');
 const {
   acceptMembershipRequestAndAddMember,
   achieveGoalIfComplete,
@@ -222,6 +222,7 @@ module.exports = {
   openNonMaintenanceGoals,
   versionsWithStatus,
   closeVersion,
+  promotePlanningVersion,
   createVersion,
   currentBuildingVersionId,
   createGoal,

package/modules/lifecycle/routes/versions.js

@@ -287,12 +287,53 @@ module.exports = function buildVersionsRouter() {
     try {
       const out = await db.closeVersion({
         versionId, plan: plan.plan, reason,
+        // BV1.R20 (task 1003607, ADR 0263 §8): the close's last act, inside its
+        // own transaction. A project with zero building versions is a BROKEN
+        // state — `currentBuildingVersionId` returns null and nothing is
+        // claimable — so promoting in a second transaction would leave exactly
+        // that window open.
+        //
+        // ORDER IS LOAD-BEARING: promote, THEN carry the bugs forward.
+        // `ensureMaintenanceGoal` returns null for a version that is not yet
+        // `building`, so a carry-over run first silently carries nothing and the
+        // defect queue stays entombed on the version that just shipped.
+        //
+        // COMPOSED HERE rather than inside closeVersion because the two halves
+        // live in different db units (versions and goals, siblings in the
+        // module's require DAG) and the route is the one place already holding
+        // the whole facade — reaching sideways between the units is how that DAG
+        // stops being one.
+        //
+        // Zero planning versions is NOT an error: the close succeeds and the
+        // project sits idle until someone cuts the next version.
         // R04 guarantees at most one planning version, so [0] is THE successor
         // rather than a pick. Null when nothing rolls forward, which is the
         // common close.
         planningVersionId: planning[0]?.id ?? null,
+      }, {
+        // NOTE THE SECOND ARGUMENT. `closeVersion` reads this hook from `deps`,
+        // not from its options object — putting it in the first one is silently
+        // ignored, the hook never runs, and the close still returns 200 having
+        // promoted nothing. Caught here by running the real close against a real
+        // Postgres; no fake would have noticed.
+        onClosed: async (client, { versionId: closedId }) => {
+          const promoted = await db.promotePlanningVersion(client);
+          const carried = promoted
+            ? await db.carryBugsForward({ fromVersionId: closedId, toVersionId: promoted.id }, { client })
+            : null;
+          return { promoted, carried };
+        },
+      });
+      // `promoted` and `carried` ride the response because a close now changes
+      // WHICH version is live, and a caller that has to go and re-read
+      // /versions to discover that has been told half the outcome. `promoted:
+      // null` is the honest answer for a project with nothing scoped next, not
+      // an omission.
+      return res.json({
+        ok: true, version: out.version, applied: out.applied,
+        promoted: out.after?.promoted ?? null,
+        carried: out.after?.carried ?? null,
       });
-      return res.json({ ok: true, version: out.version, applied: out.applied });
     } catch (err) {
       if (err && err.code === 'VERSION_NOT_FOUND') return res.fail('version_not_found', 404);
       if (err && err.code === 'VERSION_NOT_BUILDING') {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.600",
+  "version": "1.19.601",
   "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.600'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.601'; // 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/version_promotion.mjs

@@ -0,0 +1,143 @@
+// tests/version_promotion.mjs — the planning version promotes itself when the
+// building version closes (BV1.R20, task 1003607, goal 1000086, ADR 0263 §8).
+//
+// WHY IT RUNS INSIDE THE CLOSE'S TRANSACTION. A project with zero building
+// versions is a BROKEN state, not an intermediate one: `currentBuildingVersionId`
+// returns null there and every routing path closed over it fails, so nothing is
+// claimable. Promoting in a second transaction leaves exactly that window open,
+// however briefly.
+//
+// AND WHY THE ORDER IS LOAD-BEARING. Promote, THEN carry the bugs forward.
+// `ensureMaintenanceGoal` returns null for a version that is not yet `building`,
+// so a carry-over run first silently carries nothing and the defect queue stays
+// entombed on the version that just shipped — the 1000771 shape, arriving through
+// the close instead of through routing.
+//
+// ONE MORE THING THIS FILE PINS, because it is the bug that actually happened
+// while building R20: `closeVersion` reads the hook from its SECOND argument
+// (`deps`), not from its options object. Passing `onClosed` in the first one is
+// silently ignored — the hook never runs, nothing is promoted, and the close
+// still answers 200. No fake caught it; running the real close against a real
+// Postgres did.
+//
+// Run:  node --test tests/version_promotion.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { promotePlanningVersion } = require('../modules/lifecycle/db-versions.js');
+
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const ROUTES = src('modules/lifecycle/routes/versions.js');
+const DBV = src('modules/lifecycle/db-versions.js');
+
+const recorder = (handler) => {
+  const seen = [];
+  const c = makeSqlAwareClient((sql, params) => { seen.push({ sql: String(sql).replace(/\s+/g, ' '), params }); return handler(sql, params); });
+  return { seen, exec: { query: (sql, params) => c._client.query(sql, params) } };
+};
+
+// ---------------------------------------------------------------------------
+// The promotion itself
+// ---------------------------------------------------------------------------
+
+test('promotion is ONE self-guarding statement, not a read-then-write', async () => {
+  // A read-then-write leaves a window in which a concurrent close promotes too,
+  // producing the second building version R19 forbids. The NOT EXISTS is
+  // evaluated inside the same statement, so it cannot be raced past.
+  const r = recorder(() => ({ rows: [] }));
+  await promotePlanningVersion(r.exec);
+  assert.equal(r.seen.length, 1, 'one statement — a separate check could be raced');
+  const sql = r.seen[0].sql;
+  assert.match(sql, /UPDATE versions SET status = 'building'/);
+  assert.match(sql, /WHERE status = 'planning' ORDER BY id LIMIT 1/);
+  assert.match(sql, /NOT EXISTS \(SELECT 1 FROM versions WHERE status = 'building'\)/,
+    'the guard against creating a second building version must be in the statement');
+});
+
+test('started_at is stamped only if it was never set', async () => {
+  const r = recorder(() => ({ rows: [] }));
+  await promotePlanningVersion(r.exec);
+  assert.match(r.seen[0].sql, /started_at = COALESCE\(started_at, now\(\)\)/,
+    "a version's start is when it began building; a re-promotion must not rewrite history");
+});
+
+test('nothing to promote returns null — an idle project is not an error', async () => {
+  const r = recorder(() => ({ rows: [] }));
+  assert.equal(await promotePlanningVersion(r.exec), null);
+});
+
+test('the promoted row is returned so the caller can carry bugs into it', async () => {
+  const r = recorder(() => ({ rows: [{ id: 'V2', name: 'two', status: 'building', started_at: 't' }] }));
+  const out = await promotePlanningVersion(r.exec);
+  assert.equal(out.id, 'V2');
+  assert.equal(out.status, 'building');
+});
+
+// ---------------------------------------------------------------------------
+// The wiring — where the bug was
+// ---------------------------------------------------------------------------
+
+test('onClosed is passed as the DEPS argument, not in the options object', () => {
+  // THE BUG THIS PINS. `closeVersion({...opts}, deps)` reads `deps.onClosed`.
+  // Putting the hook in the first object is silently ignored: no promotion, no
+  // carry-over, and a 200 response that looks correct.
+  const call = ROUTES.slice(ROUTES.indexOf('const out = await db.closeVersion('), ROUTES.indexOf('return res.json({ ok: true, version: out.version'));
+  const optsEnd = call.indexOf('}, {');
+  assert.ok(optsEnd !== -1, 'the close must be called with a second (deps) argument');
+  assert.equal(call.slice(0, optsEnd).includes('onClosed'), false,
+    'onClosed in the options object is a silent no-op — it belongs in deps');
+  assert.ok(call.slice(optsEnd).includes('onClosed'), 'and it must actually be in deps');
+});
+
+test('the hook promotes BEFORE it carries — the ordering trap', () => {
+  const hook = ROUTES.slice(ROUTES.indexOf('onClosed: async (client'), ROUTES.indexOf('return { promoted, carried };'));
+  const promoteAt = hook.indexOf('promotePlanningVersion');
+  const carryAt = hook.indexOf('carryBugsForward');
+  assert.ok(promoteAt !== -1 && carryAt !== -1);
+  assert.ok(promoteAt < carryAt,
+    'ensureMaintenanceGoal returns null for a non-building version, so carrying first silently carries nothing');
+});
+
+test('no promotion means no carry attempt at all', () => {
+  // Not "carry into null and hope" — there is genuinely nowhere to put them, and
+  // the honest answer is that the bugs stay findable on the closed version until
+  // someone cuts the next one.
+  assert.match(ROUTES, /const carried = promoted\s*\n?\s*\?\s*await db\.carryBugsForward/);
+  assert.match(ROUTES, /:\s*null;/);
+});
+
+test('the close reports what it promoted and carried', () => {
+  // A close now changes WHICH version is live. A caller made to re-read /versions
+  // to discover that has been told half the outcome.
+  assert.match(ROUTES, /promoted: out\.after\?\.promoted \?\? null/);
+  assert.match(ROUTES, /carried: out\.after\?\.carried \?\? null/);
+});
+
+// ---------------------------------------------------------------------------
+// Composition
+// ---------------------------------------------------------------------------
+
+test('the hook is composed in the ROUTE, not inside closeVersion', () => {
+  // The two halves live in different db units — versions and goals, siblings in
+  // the module's require DAG — and the route is the one place already holding the
+  // whole facade. Reaching sideways between the units is how that DAG stops being
+  // one.
+  assert.equal(/carryBugsForward/.test(DBV), false,
+    'db-versions.js must not reach into db-goals.js');
+  assert.match(ROUTES, /db\.promotePlanningVersion\(client\)/);
+  assert.match(ROUTES, /db\.carryBugsForward\(/);
+});
+
+test('the stale R17 note in closeVersion was corrected, not left to mislead', () => {
+  // It said roll_forward "only ABSTAINS from cutting the goal ... until R17
+  // ships". R17 shipped; a reader meeting the old wording would go looking for
+  // an abstention that is no longer there.
+  assert.equal(/Until it ships/.test(DBV), false);
+  assert.match(DBV, /It DOES create successor goals now/);
+});