@bongos/core 1.19.596 → 1.19.597

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.596",
-  "core_contract": "1.19.596",
-  "source_commit": "25b1abaa5a60deab7277d0a2179e58dfc482b6b0",
+  "core_version": "1.19.597",
+  "core_contract": "1.19.597",
+  "source_commit": "1015d778d266d3357eaffb989262715110662ad1",
   "source_ref": "HEAD",
-  "built_at": "2026-09-08T04:01:26.614Z",
+  "built_at": "2026-09-08T04:16:25.146Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 457,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2071,
+    "functional_verbatim": 2073,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2552,
-  "tree_sha256": "fd2460b94c293de3373d6e8b25a51f6cfc3c851ef13536d9ae525b90d0ae5d2c",
+  "file_count": 2554,
+  "tree_sha256": "47e446b7dc9ebe46479e9138f5c45722dd3aa0c70e847abc587415af364f4d0b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2727,7 +2727,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "8cd803732ddfd0a2b36f63b63b6a280665a86bfed256198589f00c4a2c288609"
+      "sha256": "adfc4f65fbe9fc3265ec5599eb55dbe4c25063ae382006530df8c96ed930fc67"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3739,6 +3739,11 @@
       "mode": "0000644",
       "sha256": "92964dc3578fb2f4b1b7547867d0f53b2998c30bdb39271336e9b9aa348a1b37"
     },
+    {
+      "path": "migrations/core_235_one_maintenance_goal_per_version.sql",
+      "mode": "0000644",
+      "sha256": "c10c4bbbead4a3bafde336f3433a1432818880751f7a21436a6162f0dbde1abf"
+    },
     {
       "path": "modules/agents/lib/validate.js",
       "mode": "0000644",
@@ -5527,7 +5532,7 @@
     {
       "path": "modules/lifecycle/db-goals.js",
       "mode": "0000644",
-      "sha256": "433f3ef7e9c81190b7d7fa7cc71e74e46c768d54240f6d89678b2437dd67496b"
+      "sha256": "c3e06daaf78911c9dc44f72aa7a104f269624c92f343cd808b2962076a641a23"
     },
     {
       "path": "modules/lifecycle/db-grade.js",
@@ -5567,7 +5572,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "33fc8959d522bcf18c445b1a5710940379f84d1e938eecdc52cdf52bec9c4b3d"
+      "sha256": "14c05469abcf349c9173a80059e7fa0dd880b1b5a0b25680ba0d9e524e46d5d9"
     },
     {
       "path": "modules/lifecycle/dead-deps.js",
@@ -7617,12 +7622,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "e7a26121f535ff4cdd5eec05579d16849da238adb5932a4f94815e67d5de4745"
+      "sha256": "0318db53e76bb62b788fce5bf7dfd540e606e3fdcd1ab1e205732deba3a4bf03"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4f2e2854f84a88237284dbbe30261670e3fe6683fdb46dd7c24b09f18ebf9f82"
+      "sha256": "8d5d6869dab12ea697b5e0fae60883aabd464ae4568a47bc997a21cb8933cb59"
     },
     {
       "path": "public-docs/index.html",
@@ -9337,7 +9342,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ad5397fd512a3a25f3ad6a50a96f628ba1f43b6330ce2799f34c9cb099d70cc2"
+      "sha256": "2cb11336e7f6bde05dafd46c2ea3b94d9e5c7ae1f9be772a49b793e17baf7f0d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11284,6 +11289,11 @@
       "mode": "0000644",
       "sha256": "9a1813d6036886ea07d1563e71a466e66c28554b75b22605464c795fd9fa2ebb"
     },
+    {
+      "path": "tests/maintenance_carry_forward.mjs",
+      "mode": "0000644",
+      "sha256": "4ac9164b84ad7bf8e9c1b45e7cb5e157762c992ddde16041410a528a534e60f5"
+    },
     {
       "path": "tests/maintenance_goal.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1641,5 +1641,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.594 with no explicit bump. run 34185042811. (task 1002620)
   1.19.596 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.595 with no explicit bump. run 34185477798. (task 1002620)
+  1.19.597 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.596 with no explicit bump. run 34186368179. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_235_one_maintenance_goal_per_version.sql

@@ -0,0 +1,41 @@
+-- core_235_one_maintenance_goal_per_version.sql — make "one maintenance goal per
+-- version" a CONSTRAINT rather than a convention (task 1003708, BV1.R18b,
+-- goal 1000086, ADR 0263 §7).
+--
+-- WHAT core_234 LEFT OPEN. That migration added `goals.is_maintenance` and gave it
+-- a partial index for lookup speed, which is correct and is why this one is small.
+-- But the index is non-unique, so two goals on one version can both carry the flag
+-- — and `ensureMaintenanceGoal` (db-goals.js) is a find-or-create whose read is
+-- `WHERE version_id = $1 AND is_maintenance LIMIT 1`. With two flagged rows that
+-- `LIMIT 1` returns whichever the planner picks, and every homeless bug files into
+-- an arbitrary one of them, permanently.
+--
+-- That is EXACTLY the failure `pg_advisory_xact_lock` was taken for in task
+-- 1003691 — two bugs reported in the same second both reading "absent" and both
+-- inserting — arriving through a different door. The lock serialises the RACE; it
+-- cannot stop a second maintenance goal created any other way (a hand-set flag, a
+-- backfill on a version whose title convention drifted, a future feature). Moving
+-- from title to flag was the opportunity to make it a real constraint, because
+-- `goals` never had a unique constraint on (version_id, title) and the lock had
+-- been covering for that absence all along.
+--
+-- THE UPGRADE MAY FAIL, AND THAT IS THE POINT. If any version already has two
+-- flagged goals, this index cannot be created and the migration stops — loudly,
+-- before an ambiguous find-or-create becomes load-bearing. core_234's backfill
+-- keys on an exact title, so a duplicate is unlikely; if one exists it is a real
+-- data defect and the right response is to fix the rows, not to weaken the index.
+-- (Verified against live before writing this: no version has more than one.)
+--
+-- Replaces core_234's index rather than adding a second on the same expression:
+-- a UNIQUE index serves every read the plain one did, so keeping both would be
+-- two indexes doing one job.
+
+BEGIN;
+
+CREATE UNIQUE INDEX IF NOT EXISTS goals_one_maintenance_per_version_idx
+    ON goals (version_id)
+ WHERE is_maintenance;
+
+DROP INDEX IF EXISTS goals_maintenance_by_version_idx;
+
+COMMIT;

package/modules/lifecycle/db-goals.js

@@ -251,6 +251,61 @@ async function carryBugsForward({ fromVersionId, toVersionId }, deps = {}) {
   return { fromGoalId: String(from[0].id), toGoalId: String(to.id), moved: moved.length };
 }
 
+// carryMaintenanceForward — move a closing version's unfinished maintenance work
+// into the successor's maintenance goal (BV1.R18, task 1003605, ADR 0263 §7).
+//
+// THE ONE GOAL THAT LEGITIMATELY SPANS VERSIONS. Every other goal either finishes
+// or is dispositioned at close (roll forward, or abandon — R12). A maintenance
+// goal is neither: it holds defects against already-shipped work, and those arrive
+// on their own schedule rather than on the version's. Cutting them because a
+// version ended would delete a bug queue for a reason that has nothing to do with
+// the bugs; making them need an override to survive would put a counted escape
+// hatch on the ordinary path, which is what ADR 0250 §3 built the counter to
+// prevent. So they move.
+//
+// RUNS ON THE CLOSE'S OWN CLIENT, inside its transaction, via the `deps.onClosed`
+// seam R12 left in closeVersion. Two things follow, both load-bearing:
+//
+//   The successor must ALREADY be `building` when this runs. `ensureMaintenanceGoal`
+//   returns null for a version in any other state, so a carry-over run before R20's
+//   promotion silently carries nothing and reports success. That is why the seam
+//   fires after the flip and why this asserts rather than assumes.
+//
+//   Nothing here may fail the close for want of a destination. A version with no
+//   successor (no planning version was scoped) closes with its maintenance work
+//   left where it is — visible on a shipped version, recoverable, and honest —
+//   rather than the close failing or the bugs being cut. Returns a summary saying
+//   which happened.
+//
+// The source goal is left ARCHIVED with nothing open, so it passes R10's own
+// check on the way out rather than being special-cased around it.
+async function carryMaintenanceForward({ fromVersionId, toVersionId }, deps = {}) {
+  const exec = deps.client || ((deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : pool);
+  const { rows: src } = await exec.query(
+    `SELECT id FROM goals WHERE version_id = $1 AND is_maintenance LIMIT 1`, [fromVersionId]
+  );
+  if (!src[0]) return { carried: 0, from: null, to: null, reason: 'no_maintenance_goal' };
+  if (!toVersionId) return { carried: 0, from: String(src[0].id), to: null, reason: 'no_successor' };
+
+  const dest = await ensureMaintenanceGoal(toVersionId, { client: exec });
+  // Null means the successor is not `building` — see the ordering note above. Do
+  // not "fix" this by relaxing ensureMaintenanceGoal's version gate: that gate is
+  // what stops a defect being filed into a shipped version's goal (the 1000771 bug).
+  if (!dest) return { carried: 0, from: String(src[0].id), to: null, reason: 'successor_not_building' };
+
+  const { rows: moved } = await exec.query(
+    `UPDATE tasks SET goal_id = $2, version_id = $3, updated_at = now()
+      WHERE goal_id = $1 AND ${nonTerminalSql()}
+        AND ${SMOKE_NOT_LIKE.replace(/title/, 'tasks.title')}
+      RETURNING id`,
+    [src[0].id, dest.id, toVersionId]
+  );
+  // The emptied goal closes behind them. Archived rather than achieved: it was
+  // never "done", it stopped being the live queue.
+  await exec.query(`UPDATE goals SET status = 'archived', updated_at = now() WHERE id = $1`, [src[0].id]);
+  return { carried: moved.length, from: String(src[0].id), to: String(dest.id), reason: null };
+}
+
 // listVersionAdmissions (BV1.R07, task 1003594) — every goal admitted into ONE
 // version, newest first. ADR 0250 §3: "the overrides are counted and shown on the
 // version" — a visible counter is what keeps the exception honest, because an
@@ -1173,6 +1228,7 @@ module.exports = {
   carryBugsForward,
   achieveGoalIfComplete,
   archiveGoalWithDispositions,
+  carryMaintenanceForward,
   addGoalMember,
   addGoalScopeModules,
   createGoal,

package/modules/lifecycle/db.js

@@ -83,6 +83,7 @@ const {
   listActiveClaimsForTasks,
   listCriteriaForGoal,
   archiveGoalWithDispositions,
+  carryMaintenanceForward,
   openTasksInGoal,
   listGoalMembers,
   listGoals,
@@ -259,6 +260,7 @@ module.exports = {
   listPendingRequestsForGoal,
   listCriteriaForGoal,
   archiveGoalWithDispositions,
+  carryMaintenanceForward,
   openTasksInGoal,
   createTask,
   generalGoalIdForVersion,

package/package-lock.json

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

package/package.json

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

@@ -0,0 +1,122 @@
+// tests/maintenance_carry_forward.mjs — the one goal that spans versions
+// (BV1.R18b, task 1003708, goal 1000086, ADR 0263 §7).
+//
+// WHY THIS GOT A COLUMN. Since task 1003691 the maintenance goal was found by
+// matching `'<version> — maintenance'`. For the ROUTING path that was a
+// provenance wrinkle — a hand-titled goal receives a bug. For the CLOSING path
+// it was a way through the gate: `maintenanceGoalExemptSql` decides which goals
+// hold a VERSION open, so anyone who named a goal `'BONGOS-V1 — maintenance'`
+// exempted it from the rule that decides when a version may close.
+//
+// A naming convention is not an access control. That sentence is the whole task,
+// and most of this file is that sentence made mechanical.
+//
+// Run:  node tests/maintenance_flag.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { maintenanceGoalExemptSql, ensureMaintenanceGoal, carryMaintenanceForward, openNonMaintenanceGoals } = require('../modules/lifecycle/db.js');
+const { test, summary } = makeRunner();
+
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const MIG = src('migrations/core_235_one_maintenance_goal_per_version.sql');
+const MIG234 = src('migrations/core_234_goals_is_maintenance.sql');
+const flat = (q) => String(q.sql).replace(/\s+/g, ' ').trim();
+function pool(handler) {
+  const c = makeSqlAwareClient(handler);
+  return { connect: c.connect, query: (sql, p) => c._client.query(sql, p), queries: c._client.queries };
+}
+
+// ---- one per version is a CONSTRAINT ---------------------------------------
+
+await test('the per-version uniqueness is enforced by the DATABASE, not a convention', () => {
+  // core_234 gave the flag a partial index for lookup speed, which is right. But a
+  // NON-unique one leaves two flagged goals on one version possible, and
+  // ensureMaintenanceGoal's read is `WHERE version_id = $1 AND is_maintenance
+  // LIMIT 1` — with two rows that returns whichever the planner picks, and every
+  // homeless bug files into an arbitrary one of them, permanently.
+  assert.match(MIG, /CREATE UNIQUE INDEX IF NOT EXISTS goals_one_maintenance_per_version_idx[\s\S]*?ON goals \(version_id\)[\s\S]*?WHERE is_maintenance/);
+  assert.match(MIG, /DROP INDEX IF EXISTS goals_maintenance_by_version_idx/,
+    'and it replaces the plain one — a UNIQUE index serves every read the plain one did');
+  assert.match(MIG, /BEGIN;[\s\S]*COMMIT;/);
+});
+
+await test('it closes the door the advisory lock could not', () => {
+  // The lock (task 1003691) serialises the RACE. It cannot stop a second
+  // maintenance goal created any other way, and `goals` never had a unique
+  // constraint on (version_id, title) for the lock to fall back on.
+  const dbg = src('modules/lifecycle/db-goals.js');
+  assert.match(dbg, /pg_advisory_xact_lock/, 'the lock stays — it solves a different problem');
+  assert.match(MIG234, /is_maintenance boolean NOT NULL DEFAULT false/, 'core_234 still owns the column');
+});
+
+// ---- carry forward ---------------------------------------------------------
+
+function carryPool({ src = { id: 5 }, destStatus = 'building', destFound = { id: 9 } } = {}) {
+  return pool((sql) => {
+    const q = String(sql).replace(/\s+/g, ' ');
+    if (/SELECT id FROM goals WHERE version_id = \$1 AND is_maintenance LIMIT 1/.test(q)) return { rows: src ? [src] : [] };
+    if (/SELECT status FROM versions/.test(q)) return { rows: [{ status: destStatus }] };
+    if (/pg_advisory_xact_lock/.test(q)) return { rows: [] };
+    if (/FROM goals WHERE version_id = \$1 AND is_maintenance/.test(q)) return { rows: destFound ? [destFound] : [] };
+    if (/UPDATE tasks SET goal_id/.test(q)) return { rows: [{ id: 1 }, { id: 2 }, { id: 3 }] };
+    return { rows: [] };
+  });
+}
+
+await test('open bugs move to the successor, and the emptied goal archives behind them', async () => {
+  const p = carryPool();
+  const out = await carryMaintenanceForward({ fromVersionId: 'V1', toVersionId: 'V2' }, { pool: p });
+  assert.deepEqual(out, { carried: 3, from: '5', to: '9', reason: null });
+  const mv = p.queries.find((x) => /UPDATE tasks SET goal_id/.test(flat(x)));
+  assert.match(flat(mv), /NOT IN \('shipped', 'abandoned'\)/, 'only the unfinished ones travel');
+  assert.equal(mv.params[2], 'V2', 'and their version_id moves with them, or they are orphaned across the boundary');
+  assert.ok(p.queries.some((x) => /UPDATE goals SET status = 'archived'/.test(flat(x))));
+});
+
+await test('NO successor: the bugs stay put and the close still succeeds', async () => {
+  // A version with nothing scoped after it must not fail its close, and its bug
+  // queue must not be cut for a reason that has nothing to do with the bugs.
+  const p = carryPool();
+  const out = await carryMaintenanceForward({ fromVersionId: 'V1', toVersionId: null }, { pool: p });
+  assert.equal(out.carried, 0);
+  assert.equal(out.reason, 'no_successor');
+  assert.equal(p.queries.some((x) => /UPDATE tasks/.test(flat(x))), false, 'nothing moved');
+  assert.equal(p.queries.some((x) => /UPDATE goals SET status = 'archived'/.test(flat(x))), false,
+    'and the source goal is NOT closed — the queue is still live');
+});
+
+await test('a successor that is not yet BUILDING carries nothing, and says so', async () => {
+  // The ordering trap ADR 0263 §8 names: ensureMaintenanceGoal returns null for a
+  // non-building version, so a carry-over run before R20's promotion would report
+  // success while moving nothing.
+  const p = carryPool({ destStatus: 'planning', destFound: null });
+  const out = await carryMaintenanceForward({ fromVersionId: 'V1', toVersionId: 'V2' }, { pool: p });
+  assert.equal(out.carried, 0);
+  assert.equal(out.reason, 'successor_not_building', 'a silent zero would be indistinguishable from success');
+  assert.equal(p.queries.some((x) => /UPDATE tasks/.test(flat(x))), false);
+});
+
+await test('a version with no maintenance goal at all is a clean no-op', async () => {
+  const p = carryPool({ src: null });
+  const out = await carryMaintenanceForward({ fromVersionId: 'V1', toVersionId: 'V2' }, { pool: p });
+  assert.equal(out.reason, 'no_maintenance_goal');
+  assert.equal(out.carried, 0);
+});
+
+await test('it runs on the CALLER exec, so it joins the close transaction', () => {
+  // R12 left `deps.onClosed(client, …)` for exactly this. Opening its own
+  // connection would commit the carry-over independently of the close it belongs to.
+  const dbg = src('modules/lifecycle/db-goals.js');
+  const fn = dbg.slice(dbg.indexOf('async function carryMaintenanceForward'), dbg.indexOf('// listVersionAdmissions'));
+  assert.match(fn, /const exec = deps\.client \|\|/, 'it must accept the caller\'s client');
+  assert.doesNotMatch(fn, /\.connect\(\)/, 'and must never open its own');
+  assert.doesNotMatch(fn, /BEGIN|COMMIT/, 'nor manage a transaction it does not own');
+});
+
+summary();