@bongos/core 1.19.227 → 1.19.228

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.227",
-  "core_contract": "1.19.227",
-  "source_commit": "f6137a0375f70937656a4026edfe79fb32897774",
+  "core_version": "1.19.228",
+  "core_contract": "1.19.228",
+  "source_commit": "f14babca30bfba954ddd62b510ebc1ed4749d9fa",
   "source_ref": "HEAD",
-  "built_at": "2026-08-18T04:58:06.044Z",
+  "built_at": "2026-08-18T05:08:08.027Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 311,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1641,
-  "tree_sha256": "eede258e0c6a9ae77dd442500e39fdb81956608f764730d9eccbf7caa11a4fce",
+  "tree_sha256": "2a30117336498006b3241dc75e5157ce5fdc462327dbdf3618e469ad9defb158",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2902,7 +2902,7 @@
     {
       "path": "modules/government/board.js",
       "mode": "0000644",
-      "sha256": "43a284c7c69e3181268d1cb1e177deecbafe3c2693881211a74e72442aabf854"
+      "sha256": "6a2b7ebfcbba1442f45efe6df40131b03455fa0fff9ecce51e87696a72c5b117"
     },
     {
       "path": "modules/government/catalog.js",
@@ -2917,7 +2917,7 @@
     {
       "path": "modules/government/db.js",
       "mode": "0000644",
-      "sha256": "8bd28cbedd0dcb829147ad341c5a0bd3cf30225d6b2665c66218172a1930d1b0"
+      "sha256": "e20e5a4aa8a79441e5860ceda2f19e41cbdb8fd85c0eda5d00f572eee5701f20"
     },
     {
       "path": "modules/government/migrations/governance_001_tables.sql",
@@ -4302,12 +4302,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "9f7314822fed28bb1cc244c3a440c0139fa6c383f58019565647078c267738d8"
+      "sha256": "41bf0bb43e6a556ddf9598e5208bc478dd9bfc5d92f46ff64b6af6ef3ecac0eb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2b3299463571782b859abbccdb9a2fb7d0130dc6390da6de5484ab6c9800bde3"
+      "sha256": "1b62282a15730fccfbe7ae8b3a2cb2321c4b1f9947bba37928150613db0e6d7d"
     },
     {
       "path": "public-docs/index.html",
@@ -4932,7 +4932,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "a255afac6eb4a2b8269e896032e8eabf10f104aed5a0f1e8d0a7348695625424"
+      "sha256": "00eacd557419ebdba21347e215ef0f197de8cd839f6af778bf90ff2901823a0e"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -5922,7 +5922,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "206a9ffcb92d028f8f954dad04df2ec172bfacbd6be04d5204176acd4a94788a"
+      "sha256": "985014c8a83781918e242757e48bf93cbc1df612b1eb4560177aeba85b30b0f7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6847,7 +6847,7 @@
     {
       "path": "tests/government_board_close.mjs",
       "mode": "0000644",
-      "sha256": "59b35a20d28c2d689fac976f02eb0e10e95ef887c63702b9e52e3361e71eb6b4"
+      "sha256": "4408ec434f36b70a589b0592814733d3f88d48aa9aff38c08c9a2eb6c6c9f7b3"
     },
     {
       "path": "tests/government_board_membership.mjs",

package/modules/government/board.js

@@ -40,6 +40,7 @@
 // take effect on the very next window without a process restart, the same
 // instant-effect posture the resolver takes (ADR 0016).
 
+const api = require('../../src/module-api');
 const db = require('./db');
 const { loadGovernmentConfig } = require('./config');
 const { isBoardMember, resolveBoardMembers } = require('./board-membership');
@@ -250,17 +251,89 @@ function shouldCloseAfterVote({ constitution, votes, members } = {}) {
   return false; // unknown rule: only the clock closes it
 }
 
-// Close an item: tally what was cast, write the outcome, pay the author on a
-// pass. Idempotent end to end — the single-winner UPDATE plus the karma's
+// The pass-event payload (R12, docs/specs/board-room-pass-event-contract.md
+// Decision 2) — IDENTICAL shape for the in-transaction port call and the
+// post-commit event, so there is one thing to reason about. Deliberately
+// carries no tally, no voter list, no constitution: the economy module has no
+// business reading how the vote went, only that it passed.
+function passPayload(closed, { authorId, completenessScore, passedAt }) {
+  const isIdea = closed.subject_type === 'full_idea';
+  return {
+    item_id: closed.id,
+    subject_type: closed.subject_type,
+    subject_id: closed.subject_id,
+    idea_id: isIdea ? closed.subject_id : null,
+    author_id: authorId,
+    completeness_score: completenessScore,
+    passed_at: passedAt,
+  };
+}
+
+// Close an item: tally what was cast, write the outcome, pay on a pass.
+// Idempotent end to end — the single-winner UPDATE plus every award's
 // reason-key guard. `cause` is for the caller's telemetry ('vote' | 'expiry').
+//
+// R12 (the pass-event contract): MONEY RIDES THE CLOSE TRANSACTION. Stream 3's
+// credit is booked through the `reward` PORT inside the same transaction that
+// writes the outcome — if the credit write fails, the close rolls back and the
+// item stays open, so the vote is retried rather than silently unpaid.
+// `resolveOptional` returning null (no economy module), or a reward port that
+// does not yet carry awardIdeaGovernancePassCredit (IC5 unbuilt), is a CLEAN
+// NO-OP: the item still closes, nothing is booked, and the durable
+// `outcome = 'passed'` row lets IC5's re-drive sweep pay later. The port is
+// resolved and the payload's reads happen BEFORE the transaction opens.
+//
+// `board.item.passed` is then emitted AFTER commit, emitAsync, for non-money
+// reactions only (R22's Discord mirror, future notifications) — emitAsync
+// swallows listener errors, which is right for a broadcast and disqualifying
+// for a payment, which is exactly why the money went through the port above.
 async function closeItem(item, { cause = 'vote' } = {}) {
   if (!item || item.closed_at) return { closed: false, reason: 'already_closed' };
   const votes = await db.getVotesForItem(item.id);
   const outcome = tallyOutcome(votes);
-  const closed = await db.closeBoardItem({ itemId: item.id, outcome });
+
+  // The payload's reads, ahead of the transaction (reads never ride a tx they
+  // don't need). Only a pass needs them, and only a full_idea can pay.
+  let authorId = null;
+  let completenessScore = null;
+  let credit = null;
+  if (outcome === 'passed') {
+    authorId = await db.getBoardItemAuthor(item);
+    if (item.subject_type === 'full_idea') {
+      completenessScore = await db.getIdeaCompleteness(item.subject_id);
+    }
+  }
+
+  const reward = outcome === 'passed' && item.subject_type === 'full_idea'
+    ? (api.resolveOptional && api.resolveOptional('reward'))
+    : null;
+  const payMoney = reward && typeof reward.awardIdeaGovernancePassCredit === 'function';
+
+  const closed = await db.closeBoardItem({
+    itemId: item.id,
+    outcome,
+    afterClose: payMoney
+      ? async (client) => {
+          credit = await reward.awardIdeaGovernancePassCredit(client, {
+            ideaId: item.subject_id,
+            authorId,
+            completenessScore,
+          });
+        }
+      : null,
+  });
   if (!closed) return { closed: false, reason: 'already_closed' };
+
   const authorKarma = outcome === 'passed' ? await awardAuthorRatifyKarma(closed) : null;
-  return { closed: true, item: closed, outcome, cause, author_karma: authorKarma };
+
+  if (outcome === 'passed') {
+    const payload = passPayload(closed, { authorId, completenessScore, passedAt: closed.closed_at });
+    try {
+      if (api.emitAsync) await api.emitAsync('board.item.passed', payload);
+    } catch (_) { /* emitAsync isolates listener errors; nothing that moves credits subscribes */ }
+  }
+
+  return { closed: true, item: closed, outcome, cause, author_karma: authorKarma, ...(credit ? { credit } : {}) };
 }
 
 // The post-vote hook R08's route fires after a FRESH cast. Reads everything it
@@ -290,6 +363,7 @@ module.exports = {
   castVote,
   tallyOutcome,
   shouldCloseAfterVote,
+  passPayload,
   closeItem,
   maybeCloseAfterVote,
 };

package/modules/government/db.js

@@ -386,15 +386,55 @@ async function getVotesForItem(itemId) {
 // two concurrent closers (a racing vote and the expiry sweep) write exactly one
 // outcome; the loser gets null and reads the winner's row back if it cares.
 // closed_at comes from the database clock, like every timestamp on this table.
-async function closeBoardItem({ itemId, outcome }) {
+//
+// R12 (the pass-event contract, Decision 1) made this a TRANSACTION: money
+// rides the close, so `afterClose(client, closedRow)` runs INSIDE it — if the
+// credit write fails, the close rolls back and the item stays open (the vote is
+// retried, never silently unpaid; "the ledger and the outcome can never
+// disagree"). No afterClose (or a null one) degrades to the plain single-
+// statement close R10 shipped.
+async function closeBoardItem({ itemId, outcome, afterClose = null }) {
+  if (typeof afterClose !== 'function') {
+    const { rows } = await pool.query(
+      `UPDATE government_board_items
+          SET closed_at = now(), outcome = $2
+        WHERE id = $1 AND closed_at IS NULL
+        RETURNING *`,
+      [itemId, outcome],
+    );
+    return rows[0] || null;
+  }
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    const { rows } = await client.query(
+      `UPDATE government_board_items
+          SET closed_at = now(), outcome = $2
+        WHERE id = $1 AND closed_at IS NULL
+        RETURNING *`,
+      [itemId, outcome],
+    );
+    const closed = rows[0] || null;
+    if (closed) await afterClose(client, closed);
+    await client.query('COMMIT');
+    return closed;
+  } catch (err) {
+    try { await client.query('ROLLBACK'); } catch (_) { /* connection-level failure */ }
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// The subject's stored completeness score, for the pass-event payload (R12).
+// ideas_grades is another module's table; READING it is the sanctioned pattern
+// (the boundary is code imports, not table access) — null when unscored.
+async function getIdeaCompleteness(ideaId) {
   const { rows } = await pool.query(
-    `UPDATE government_board_items
-        SET closed_at = now(), outcome = $2
-      WHERE id = $1 AND closed_at IS NULL
-      RETURNING *`,
-    [itemId, outcome],
+    `SELECT completeness_score FROM ideas_grades WHERE idea_id = $1`,
+    [ideaId],
   );
-  return rows[0] || null;
+  return rows[0] ? rows[0].completeness_score : null;
 }
 
 // Author-ratification karma (+3, board.js AUTHOR_RATIFY_KARMA_DELTA) — fired by
@@ -450,4 +490,5 @@ module.exports = {
   insertAuthorRatifyKarma,
   getVotesForItem,
   closeBoardItem,
+  getIdeaCompleteness,
 };

package/package-lock.json

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

package/package.json

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

@@ -1688,6 +1688,16 @@ const VOCAB_ALLOW = [
        + 'repo, so the old spelling is still read. Dropping it would silently stop '
        + 'honouring a label override someone already configured.',
   },
+  {
+    file: 'modules/government/board.js',
+    match: 'governancepasscredit',
+    why: 'the R02 pass-event contract (docs/specs/board-room-pass-event-contract.md, agreed '
+       + 'cross-goal 2026-08-17) names the economy-side award awardIdeaGovernancePassCredit, '
+       + 'matching the credit_log reason family idea.credit.governance_pass:<id> that streams '
+       + '1-3 share. The board calls the CONSUMER\'s agreed method name — renaming it here '
+       + 'would break the contract, and the reason strings are durable ledger rows. Scoped to '
+       + 'the method name, so a stray "governance" elsewhere in board.js still reds the build.',
+  },
   {
     file: 'modules/government/module.json',
     match: 'role',

package/src/module-api.js

@@ -881,8 +881,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.225 with no explicit bump. run 32100543772. (task 1002620)
 //   1.19.227 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.227'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.228'; // 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_close.mjs

@@ -99,6 +99,7 @@ test('a pass pays the author (+3, idempotent downstream); a return pays nobody',
     getVotesForItem: async () => [yes('42')],
     closeBoardItem: async ({ itemId, outcome }) => ({ ...openItem(), id: String(itemId), closed_at: 't', outcome }),
     getBoardItemAuthor: async () => '7',
+    getIdeaCompleteness: async () => 82,
     insertAuthorRatifyKarma: async (args) => { karma.push(args); return true; },
   }, async () => {
     const out = await closeItem(openItem(), { cause: 'vote' });
@@ -124,6 +125,8 @@ test('a pass pays the author (+3, idempotent downstream); a return pays nobody',
 test('the losing racer gets already_closed and pays nothing', async () => {
   await withDb({
     getVotesForItem: async () => [yes('42')],
+    getBoardItemAuthor: async () => '7',
+    getIdeaCompleteness: async () => 82,
     closeBoardItem: async () => null, // the WHERE closed_at IS NULL conflict path
     insertAuthorRatifyKarma: async () => { throw new Error('must not be reached'); },
   }, async () => {
@@ -143,6 +146,7 @@ test('monarchy end to end: the first yes closes the item as passed, author paid'
     getActiveBuildersWithRank: async () => [{ builder_id: '42', github_login: 'a', display_name: 'A' }],
     closeBoardItem: async ({ outcome }) => ({ ...openItem(), closed_at: 't', outcome }),
     getBoardItemAuthor: async () => '7',
+    getIdeaCompleteness: async () => 82,
     insertAuthorRatifyKarma: async (args) => { karma.push(args); return true; },
   }, async () => {
     const out = await maybeCloseAfterVote(11);
@@ -166,12 +170,87 @@ test('consent with turnout outstanding leaves the window open', async () => {
 
 // ── the structural pins ──────────────────────────────────────────────────────
 
-test('the close UPDATE is single-winner in the SQL, and the pass event is NOT emitted here', () => {
+test('the close UPDATE is single-winner in the SQL — in BOTH the plain and the transactional form', () => {
   const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
-  const block = src.slice(src.indexOf('async function closeBoardItem'), src.indexOf('// Author-ratification karma'));
-  assert.match(block, /WHERE id = \$1 AND closed_at IS NULL/, 'two racers write exactly one outcome');
+  const block = src.slice(src.indexOf('async function closeBoardItem'), src.indexOf('async function getIdeaCompleteness'));
+  assert.equal((block.match(/WHERE id = \$1 AND closed_at IS NULL/g) || []).length, 2,
+    'two racers write exactly one outcome, with or without an in-tx credit hook');
+  assert.match(block, /ROLLBACK/, 'a failed in-tx credit rolls the close back — the vote is retried, never silently unpaid');
+});
+
+// ── R12: money rides the port inside the tx; the event is post-commit courtesy ──
+
+test('a pass books the stream-3 credit INSIDE the close transaction, through the reward port', async () => {
+  const api = require(path.join(ROOT, 'src', 'module-api.js'));
+  const hadReward = api.hasProvider('reward');
+  if (!hadReward) {
+    api.registerProvider('reward', {
+      awardIdeaGovernancePassCredit: async (client, args) => ({ credited: 82, reason: 'paid', _client: client, _args: args }),
+    });
+  }
+  const seen = [];
+  try {
+    await withDb({
+      getVotesForItem: async () => [yes('42')],
+      getBoardItemAuthor: async () => '7',
+      getIdeaCompleteness: async () => 82,
+      closeBoardItem: async ({ outcome, afterClose }) => {
+        const closed = { ...openItem(), closed_at: 't', outcome };
+        // the db layer hands afterClose ITS transaction client — simulate that
+        if (afterClose) await afterClose({ __tx: true }, closed);
+        seen.push({ outcome, hadHook: typeof afterClose === 'function' });
+        return closed;
+      },
+      insertAuthorRatifyKarma: async () => true,
+    }, async () => {
+      const out = await closeItem(openItem(), { cause: 'vote' });
+      assert.equal(out.closed, true);
+      if (out.credit) { // present only when a reward provider carries IC5's method
+        assert.equal(out.credit.reason, 'paid');
+        assert.deepEqual(out.credit._client, { __tx: true }, 'the award ran on the CLOSE transaction\'s client');
+        assert.equal(out.credit._args.ideaId, '7');
+        assert.equal(out.credit._args.completenessScore, 82);
+      }
+      assert.equal(seen[0].outcome, 'passed');
+    });
+  } finally { /* provider registry is process-global; leave whatever was there */ }
+});
+
+test('a RETURNED item books nothing and emits nothing — only a pass pays or announces', async () => {
+  await withDb({
+    getVotesForItem: async () => [no('42')],
+    closeBoardItem: async ({ outcome, afterClose }) => {
+      assert.equal(afterClose, null, 'no in-tx hook on a return — nothing to book');
+      return { ...openItem(), closed_at: 't', outcome };
+    },
+    getBoardItemAuthor: async () => { throw new Error('must not be reached'); },
+    getIdeaCompleteness: async () => { throw new Error('must not be reached'); },
+  }, async () => {
+    const out = await closeItem(openItem());
+    assert.equal(out.outcome, 'returned');
+    assert.equal(out.credit, undefined);
+  });
+});
+
+test('the payload matches the contract shape, and an amendment carries idea_id null', () => {
+  const closed = { id: '11', subject_type: 'full_idea', subject_id: '7', closed_at: 'T' };
+  const p = board.passPayload(closed, { authorId: '42', completenessScore: 82, passedAt: 'T' });
+  assert.deepEqual(Object.keys(p).sort(),
+    ['author_id', 'completeness_score', 'idea_id', 'item_id', 'passed_at', 'subject_id', 'subject_type'],
+    'exactly the contract\'s seven fields — no tally, no voter list, no constitution');
+  assert.equal(p.idea_id, '7', 'idea_id === subject_id for a full_idea');
+  const amendment = board.passPayload({ ...closed, subject_type: 'constitutional_amendment' },
+    { authorId: '3', completenessScore: null, passedAt: 'T' });
+  assert.equal(amendment.idea_id, null, 'an amendment traverses the same path and must book nothing — the consumer filters on subject_type');
+});
+
+test('the event is emitAsync AFTER the close, and money never rides it (source pins)', () => {
   const boardSrc = fs.readFileSync(path.join(GOV, 'board.js'), 'utf8');
-  assert.ok(!/emit|event/i.test(boardSrc.slice(boardSrc.indexOf('async function closeItem'), boardSrc.indexOf('async function maybeCloseAfterVote'))) || true,
-    'sanity only');
-  assert.ok(!boardSrc.includes('pass_event'), 'R12 owns the pass event — closing and emitting are separate acts');
+  const close = boardSrc.slice(boardSrc.indexOf('async function closeItem'), boardSrc.indexOf('async function maybeCloseAfterVote'));
+  assert.match(close, /emitAsync\('board\.item\.passed'/, 'the courtesy event exists for R22');
+  assert.ok(close.indexOf('closeBoardItem') < close.indexOf("emitAsync('board.item.passed'"),
+    'emitted after the close write — a payment must not depend on a listener having been alive');
+  assert.match(close, /awardIdeaGovernancePassCredit/, 'the money goes through the PORT');
+  const emitBlock = close.slice(close.indexOf("emitAsync('board.item.passed'"));
+  assert.ok(!emitBlock.includes('award'), 'nothing that moves credits touches the event path');
 });