@bongos/core 1.19.228 → 1.19.229

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.228",
-  "core_contract": "1.19.228",
-  "source_commit": "f14babca30bfba954ddd62b510ebc1ed4749d9fa",
+  "core_version": "1.19.229",
+  "core_contract": "1.19.229",
+  "source_commit": "5c10983a65226999c00c47505064cbbc2f220b69",
   "source_ref": "HEAD",
-  "built_at": "2026-08-18T05:08:08.027Z",
+  "built_at": "2026-08-18T11:08:02.722Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 311,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1309,
+    "functional_verbatim": 1311,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1641,
-  "tree_sha256": "2a30117336498006b3241dc75e5157ce5fdc462327dbdf3618e469ad9defb158",
+  "file_count": 1643,
+  "tree_sha256": "e979d45fff4ac3f56c93dde15a58e8af514e7ed2254ff4df6c028de0aaaa9184",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2917,7 +2917,7 @@
     {
       "path": "modules/government/db.js",
       "mode": "0000644",
-      "sha256": "e20e5a4aa8a79441e5860ceda2f19e41cbdb8fd85c0eda5d00f572eee5701f20"
+      "sha256": "41c6cd987c619f7bfe6ae4f03a9acf7502872cb2f929b7256c95dbb84784c769"
     },
     {
       "path": "modules/government/migrations/governance_001_tables.sql",
@@ -2982,7 +2982,12 @@
     {
       "path": "modules/government/module.json",
       "mode": "0000644",
-      "sha256": "6ee190f95f9a5c7bbe6d4d4b193dff5116fe3c317ffcffc68512a40da7b1084c"
+      "sha256": "7baa08a671982532d9961164ffdb37b56bdf11bc8ba133739d3af07b54b0eaa8"
+    },
+    {
+      "path": "modules/government/pollers/board-expiry.js",
+      "mode": "0000644",
+      "sha256": "0e524bee731d9a6120cb98a23f419a2803f9bb19118f5e5aa46befd8e253e9ca"
     },
     {
       "path": "modules/government/protected-surfaces.js",
@@ -4302,12 +4307,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "41bf0bb43e6a556ddf9598e5208bc478dd9bfc5d92f46ff64b6af6ef3ecac0eb"
+      "sha256": "06a9692e854d494a7ddecb1c634fa93f7bc7e41fb0cfe6a9c51ff5cad64fca26"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1b62282a15730fccfbe7ae8b3a2cb2321c4b1f9947bba37928150613db0e6d7d"
+      "sha256": "e1bc3c9e5f02b5f174bf8a97531dbd6447f367cb0ccef682f9ee994619130308"
     },
     {
       "path": "public-docs/index.html",
@@ -5922,7 +5927,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "985014c8a83781918e242757e48bf93cbc1df612b1eb4560177aeba85b30b0f7"
+      "sha256": "2d2767e5620a5743401f0b04ccae76a989682e13356a3a27c80203a8bd267d8d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6849,6 +6854,11 @@
       "mode": "0000644",
       "sha256": "4408ec434f36b70a589b0592814733d3f88d48aa9aff38c08c9a2eb6c6c9f7b3"
     },
+    {
+      "path": "tests/government_board_expiry.mjs",
+      "mode": "0000644",
+      "sha256": "1bf22bc4ae339459e28a9f4e7975aac9e9d84eacd3f901d30371b44574f714c1"
+    },
     {
       "path": "tests/government_board_membership.mjs",
       "mode": "0000644",

package/modules/government/db.js

@@ -437,6 +437,21 @@ async function getIdeaCompleteness(ideaId) {
   return rows[0] ? rows[0].completeness_score : null;
 }
 
+// The expiry sweep's read (R11): every OPEN item whose deadline has passed, on
+// the database clock, oldest deadline first. Served by the partial index
+// government_board_items_open_by_deadline (government_003 built it for exactly
+// this). NULL closes_at — the no-clock configuration — never appears here.
+async function getExpiredOpenBoardItems(limit = 100) {
+  const { rows } = await pool.query(
+    `SELECT * FROM government_board_items
+      WHERE closed_at IS NULL AND closes_at IS NOT NULL AND closes_at < now()
+      ORDER BY closes_at
+      LIMIT $1`,
+    [limit],
+  );
+  return rows;
+}
+
 // Author-ratification karma (+3, board.js AUTHOR_RATIFY_KARMA_DELTA) — fired by
 // the R10 close on a passed item. IDEMPOTENT: the reason key is unique per item
 // and the INSERT is one atomic WHERE-NOT-EXISTS statement (the economy
@@ -491,4 +506,5 @@ module.exports = {
   getVotesForItem,
   closeBoardItem,
   getIdeaCompleteness,
+  getExpiredOpenBoardItems,
 };

package/modules/government/module.json

@@ -12,6 +12,9 @@
     "routes": [
       "government",
       "rank-sync"
+    ],
+    "pollers": [
+      "board-expiry"
     ]
   },
   "provides": [

package/modules/government/pollers/board-expiry.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// modules/government/pollers/board-expiry.js — the window expiry sweep
+// (BV1.R11 of goal 1000069, ADR 0175 §2).
+//
+// A window closes ON TIME with nobody touching it. The clock is the sitting
+// model's deadlock exit — absent members drop out of the denominator and the
+// deadline ends the sitting — so this poller is what makes the timed half of
+// the constitution real. It calls the SAME closeItem the post-vote path calls
+// (R10), so a clock-close and a turnout-close can never mean different things,
+// and the single-winner UPDATE makes racing one of them against a landing vote
+// safe: exactly one outcome is written.
+//
+// THE SWEEP SHAPE follows the publish reconciler (the in-tree precedent the
+// spec names): a bounded per-sweep read, PER-ITEM failure isolation (one item
+// that cannot close must not stall the item behind it), and a per-item
+// DISPOSITION LINE so a stuck window is visible in the journal rather than
+// silent. Unlike the reconciler it stays QUIET on an empty sweep — a
+// minute-cadence poller logging every tick would bury the journal (the
+// reconciler's own warn-once lesson).
+//
+// CADENCE: windows are minutes-granular (the recommended sitting is 90
+// minutes), so a one-minute sweep bounds lateness at ~1 minute — tight enough
+// that "closes on time" is honest, cheap enough that the query (one indexed
+// read; government_board_items_open_by_deadline exists for exactly this, per
+// government_003's own comment) is negligible. Concurrent windows are normal
+// (owner decision 10): the sweep closes every due item, oldest deadline first.
+
+const board = require('../board');
+const db = require('../db');
+
+const INTERVAL_MS = Number(process.env.BOARD_EXPIRY_SWEEP_MS) || 60_000;
+// A first sweep shortly after boot, so windows that expired while the process
+// was down (a deploy restart mid-sitting) close promptly rather than one full
+// interval late.
+const FIRST_SWEEP_DELAY_MS = Number(process.env.BOARD_EXPIRY_FIRST_MS) || 15_000;
+// Runaway guard, not an expected bound — a project rarely has more than a
+// handful of open windows (the board's subjects are rare by construction).
+const SWEEP_LIMIT = 100;
+
+let intervalTimer = null;
+let firstTimer = null;
+
+// One sweep. Injectable deps keep it DB-free testable: listFn yields the due
+// items, closeFn closes one, log receives the disposition lines.
+async function runSweep({ listFn = db.getExpiredOpenBoardItems, closeFn = board.closeItem, log = console.log, error = console.error } = {}) {
+  let due;
+  try {
+    due = await listFn(SWEEP_LIMIT);
+  } catch (e) {
+    error(`[board-expiry] sweep read failed: ${e && e.message}`);
+    return { closed: 0, failed: 0, due: 0 };
+  }
+  if (!due || !due.length) return { closed: 0, failed: 0, due: 0 }; // quiet on empty
+  let closed = 0;
+  let failed = 0;
+  for (const item of due) {
+    try {
+      const out = await closeFn(item, { cause: 'expiry' });
+      if (out && out.closed) {
+        closed += 1;
+        log(`[board-expiry] item ${item.id} (${item.subject_type} ${item.subject_id}) expired → ${out.outcome}`);
+      } else {
+        // A racer (a landing vote's close) beat the sweep — the item is closed,
+        // just not by us. That is the single-winner design working; say so.
+        log(`[board-expiry] item ${item.id} already closed by a racer — nothing to do`);
+      }
+    } catch (e) {
+      failed += 1;
+      // Per-item isolation: name the item and keep sweeping. A close that
+      // throws here (e.g. the in-tx credit failing) has ROLLED BACK, so the
+      // item is still open and the next sweep retries it — the pass-event
+      // contract's "retried, never silently unpaid".
+      error(`[board-expiry] item ${item.id} failed to close (still open; next sweep retries): ${e && e.message}`);
+    }
+  }
+  return { closed, failed, due: due.length };
+}
+
+function start(deps = {}) {
+  if (process.env.BOARD_EXPIRY_DISABLED === '1') {
+    console.log('[board-expiry] disabled (BOARD_EXPIRY_DISABLED=1)');
+    return;
+  }
+  if (intervalTimer) return; // already started
+  const tick = () => {
+    runSweep(deps).catch((e) => console.error(`[board-expiry] sweep crashed: ${e && e.message}`));
+  };
+  firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
+  if (firstTimer.unref) firstTimer.unref();
+  intervalTimer = setInterval(tick, INTERVAL_MS);
+  if (intervalTimer.unref) intervalTimer.unref(); // never hold the process open on a restart
+  console.log(`[board-expiry] started (every ${Math.round(INTERVAL_MS / 1000)}s; first sweep in ${Math.round(FIRST_SWEEP_DELAY_MS / 1000)}s)`);
+}
+
+function stop() {
+  if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
+  if (intervalTimer) { clearInterval(intervalTimer); intervalTimer = null; }
+}
+
+module.exports = { start, stop, runSweep, INTERVAL_MS, SWEEP_LIMIT };

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.228",
+  "version": "1.19.229",
   "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

@@ -883,8 +883,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.226 with no explicit bump. run 32101041951. (task 1002620)
 //   1.19.228 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.227 with no explicit bump. run 32101659669. (task 1002620)
+//   1.19.229 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.228 with no explicit bump. run 32130159805. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.228'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.229'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/government_board_expiry.mjs

@@ -0,0 +1,109 @@
+// tests/government_board_expiry.mjs — the window expiry poller (BV1.R11 of
+// goal 1000069, ADR 0175 §2): a window closes on time with nobody touching it.
+//
+// DB-free: runSweep takes injectable deps (the reconciler's testable shape).
+// What must hold:
+//   1. EVERY due item is closed through the SAME closeItem R10 built, with
+//      cause 'expiry' — a clock-close and a turnout-close are one path.
+//   2. PER-ITEM ISOLATION — an item that fails to close (rolled back, still
+//      open, retried next sweep) must not stall the items behind it.
+//   3. DISPOSITIONS ARE VISIBLE — a closed item and a racer-beaten item each
+//      log a line; an EMPTY sweep logs nothing (a minute-cadence poller must
+//      not bury the journal).
+//   4. The timers never hold the process open, and stop() is clean.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+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 GOV = path.join(ROOT, 'modules', 'government');
+const poller = require(path.join(GOV, 'pollers', 'board-expiry.js'));
+
+const item = (id, over = {}) => ({ id: String(id), subject_type: 'full_idea', subject_id: String(id * 10), closed_at: null, ...over });
+
+test('every due item closes via closeItem with cause expiry — concurrent windows are normal', async () => {
+  const closed = [];
+  const lines = [];
+  const out = await poller.runSweep({
+    listFn: async (limit) => { assert.equal(limit, poller.SWEEP_LIMIT); return [item(1), item(2), item(3)]; },
+    closeFn: async (it, opts) => { closed.push([it.id, opts.cause]); return { closed: true, outcome: 'passed' }; },
+    log: (l) => lines.push(l),
+    error: () => { throw new Error('no errors expected'); },
+  });
+  assert.deepEqual(closed, [['1', 'expiry'], ['2', 'expiry'], ['3', 'expiry']]);
+  assert.deepEqual(out, { closed: 3, failed: 0, due: 3 });
+  assert.equal(lines.length, 3, 'one disposition line per closed item');
+  assert.ok(lines[0].includes('expired → passed'));
+});
+
+test('one failing item does not stall the sweep — named, counted, retried next time', async () => {
+  const closed = [];
+  const errors = [];
+  const out = await poller.runSweep({
+    listFn: async () => [item(1), item(2), item(3)],
+    closeFn: async (it) => {
+      if (it.id === '2') throw new Error('credit write refused — close rolled back');
+      closed.push(it.id);
+      return { closed: true, outcome: 'returned' };
+    },
+    log: () => {},
+    error: (l) => errors.push(l),
+  });
+  assert.deepEqual(closed, ['1', '3'], 'the items behind the failure still closed');
+  assert.deepEqual(out, { closed: 2, failed: 1, due: 3 });
+  assert.equal(errors.length, 1);
+  assert.ok(errors[0].includes('item 2') && errors[0].includes('next sweep retries'),
+    'the stuck window is visible, and the retry story is stated');
+});
+
+test('a racer-beaten item is a disposition, not an error — the single-winner design working', async () => {
+  const lines = [];
+  const out = await poller.runSweep({
+    listFn: async () => [item(7)],
+    closeFn: async () => ({ closed: false, reason: 'already_closed' }),
+    log: (l) => lines.push(l),
+    error: () => { throw new Error('not an error'); },
+  });
+  assert.deepEqual(out, { closed: 0, failed: 0, due: 1 });
+  assert.ok(lines[0].includes('already closed by a racer'));
+});
+
+test('an empty sweep is SILENT, and a failed read is one error line, not a crash', async () => {
+  const lines = [];
+  const errors = [];
+  assert.deepEqual(await poller.runSweep({ listFn: async () => [], log: (l) => lines.push(l), error: (l) => errors.push(l) }),
+    { closed: 0, failed: 0, due: 0 });
+  assert.equal(lines.length, 0, 'a minute-cadence poller must not bury the journal');
+  assert.deepEqual(await poller.runSweep({ listFn: async () => { throw new Error('db down'); }, log: () => {}, error: (l) => errors.push(l) }),
+    { closed: 0, failed: 0, due: 0 });
+  assert.equal(errors.length, 1);
+});
+
+test('the sweep read is indexed, deadline-ordered, and never sees a no-clock item (SQL pins)', () => {
+  const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
+  const block = src.slice(src.indexOf('async function getExpiredOpenBoardItems'), src.indexOf('// Author-ratification karma'));
+  assert.match(block, /closed_at IS NULL AND closes_at IS NOT NULL AND closes_at < now\(\)/,
+    'open + due, on the DATABASE clock; NULL closes_at (no clock) never expires');
+  assert.match(block, /ORDER BY closes_at/, 'oldest deadline first');
+  const migration = fs.readFileSync(path.join(GOV, 'migrations', 'government_003_board_tables.sql'), 'utf8');
+  assert.ok(migration.includes('government_board_items_open_by_deadline'),
+    'the partial index government_003 built for this sweep exists');
+});
+
+test('the manifest declares the poller, and start/stop are idempotent + unref-safe', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(GOV, 'module.json'), 'utf8'));
+  assert.ok(manifest.contributes.pollers.includes('board-expiry'),
+    'the loader starts it only when declared (startModulePollers contract)');
+  // Behavioural start/stop with the sweep stubbed inert: no timer may survive stop().
+  poller.start({ listFn: async () => [], log: () => {}, error: () => {} });
+  poller.start(); // second start is a no-op (already started)
+  poller.stop();
+  poller.stop(); // second stop is a no-op
+  // The timers are unref'd in start(); nothing to await — reaching here without
+  // the test runner hanging IS the assertion.
+  assert.ok(true);
+});