@bongos/core 1.19.222 → 1.19.223

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.222",
-  "core_contract": "1.19.222",
-  "source_commit": "4425d4ace9a3b996b50be1b59002e4cf85f027db",
+  "core_version": "1.19.223",
+  "core_contract": "1.19.223",
+  "source_commit": "f9d11234723ed42c73cf2eff487deabe34464ab5",
   "source_ref": "HEAD",
-  "built_at": "2026-08-18T03:36:13.104Z",
+  "built_at": "2026-08-18T04:00:41.918Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 311,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1303,
+    "functional_verbatim": 1305,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1635,
-  "tree_sha256": "6bf87d2a8bb013b102f3ae8287a56fd6fe7ed99ed49b48f4607abcb047f59f74",
+  "file_count": 1637,
+  "tree_sha256": "149332598cd294f2de39adf373feaa298158120232a1dfebbd58e5ee56207689",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -2894,6 +2894,11 @@
       "mode": "0000644",
       "sha256": "7cb9dac9cb87b679e1ae50e4112b3a7928a38ebb9902c8947a74d17bec4d9009"
     },
+    {
+      "path": "modules/government/board-membership.js",
+      "mode": "0000644",
+      "sha256": "5bf474bee95bc8a8982e4a52c9e5b19955a20195dc1affd51c07e99540c8c059"
+    },
     {
       "path": "modules/government/catalog.js",
       "mode": "0000644",
@@ -2907,7 +2912,7 @@
     {
       "path": "modules/government/db.js",
       "mode": "0000644",
-      "sha256": "0e84802af9d1dd4c139548d4e621fc11896513415abf4e9eadfacbae33c40952"
+      "sha256": "581d1b67c4765ec3f1d98a7af06afaefb2b6904f84d4fbb8be79f3d0008d4712"
     },
     {
       "path": "modules/government/migrations/governance_001_tables.sql",
@@ -2997,7 +3002,7 @@
     {
       "path": "modules/government/routes/government.js",
       "mode": "0000644",
-      "sha256": "872f144bcd788e36f8b8bc87e5bd31f2389169ffa5d930e03d74ba24a0264f3b"
+      "sha256": "120877f860336de8bb010fe09872348257967b79a51951e5914fc32e907b5886"
     },
     {
       "path": "modules/government/routes/rank-sync.js",
@@ -4292,12 +4297,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "44f9bf150c24b1bed1d68bcd0a9661b4c659a32e5087a268a21b7b4370d7099a"
+      "sha256": "886be125dcb957387fea954c943d27f852347b7f38662905d59e2146cbb17e0b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "231179c4f9a0fffdd0ecdb48ceb161e99e7aab4e3058296762561d510f15281a"
+      "sha256": "7e5374d7ead5886cd5b376a95724500196a0e9dc748617a99af436b2863a235c"
     },
     {
       "path": "public-docs/index.html",
@@ -5912,7 +5917,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e999662a04f1981cbf01b2a9b5d18d33e71034311702fac6e5a6e0a0a209dcc0"
+      "sha256": "ea7ae52689115222eeafffffbcf8fb1f9fcf13b6e01f90f1153e133928d52dea"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6834,6 +6839,11 @@
       "mode": "0000644",
       "sha256": "8f5354cbacf15c9b49500f96b265fe52f5c0d4500a4ec7b41b4819a149782893"
     },
+    {
+      "path": "tests/government_board_membership.mjs",
+      "mode": "0000644",
+      "sha256": "1a6f90e319c88ecd3e5588d5a6df44a9848c0adf08efd13bfcc52ac99e84d5d0"
+    },
     {
       "path": "tests/government_catalog.mjs",
       "mode": "0000644",

package/modules/government/board-membership.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// modules/government/board-membership.js — WHO SITS ON THE BOARD, right now
+// (BV1.R06 of goal 1000069, ADR 0175).
+//
+// Resolves the constitution's membership predicate (R05: `board.membership`,
+// grammar `rank:<key>`) to the live member list. Consumed by R07 (who to
+// announce a window to), R08 (the live membership re-check before a vote
+// counts), and R10 (the tally's denominator).
+//
+// It preserves ADR 0016 exactly, the same three ways resolver.js does:
+//   • server-side — membership is computed from government_builder_ranks rows,
+//     never from a token claim or a client-supplied list;
+//   • per request — the caller asks on the request that needs the answer, so a
+//     demoted Archon is off the board on their very next request, and a vote
+//     they attempt after the demotion does not count (R08's re-check);
+//   • UNCACHED — no memo, no TTL, no process-local map. A cached member list
+//     would keep a demoted builder governing, which is the precise failure the
+//     trust boundary exists to prevent. If the join ever profiles hot, the
+//     answer is a DB index, not a cache.
+//
+// WHY RANK, NEVER CRAFT (the spec's rejected craft-chamber model): PATCH
+// /me/disciplines is deliberately ungated — a builder owns their own profile
+// (src/bongos/routes/me.js) — so a craft-derived franchise (Artist / Ideator /
+// Builder as voting chambers) would be one-request self-enfranchisement. Rank
+// is written only through the Archon-gated rank-set path with the R95b rank
+// rotation, so deriving membership from rank inherits that write gate for free.
+//
+// Fail-closed throughout, in the same direction as R05's config sanitizer: a
+// predicate this file cannot parse resolves to NOBODY, never to everybody. An
+// unknown grammar must not quietly widen the franchise — an empty board under
+// `first_ratifier` simply means no one can ratify until the constitution is
+// fixed, which is loud, visible, and reversible by fixing the config.
+
+const db = require('./db');
+
+// The one predicate grammar v1 defines, mirrored from config.js's MEMBERSHIP_RE
+// (the two must agree; tests/government_board_membership.mjs pins that). The
+// rank key is validated by SHAPE only — whether it names a live rank is the
+// DB's question, answered by the query returning nobody for a key with no
+// assignment rows. Config deliberately cannot see custom ranks (R05), so this
+// is where `rank:some-custom-rank` becomes real or resolves to an empty board.
+const PREDICATE_RE = /^rank:([a-z][a-z0-9_-]*)$/;
+
+// Pure: predicate string -> { rankKey } or null. Null means "unparseable", and
+// every caller must treat null as NOBODY. Exported so R07/R08 can validate a
+// snapshotted constitution's predicate without touching the DB.
+function parseMembershipPredicate(predicate) {
+  if (typeof predicate !== 'string') return null;
+  const m = PREDICATE_RE.exec(predicate);
+  return m ? Object.freeze({ rankKey: m[1] }) : null;
+}
+
+// The resolve entry point: constitution board block -> the live member list, as
+// a frozen array of { builder_id, github_login, display_name } rows sorted by
+// id. Takes the BOARD BLOCK (not the whole config) because R07-R10 operate on
+// the constitution SNAPSHOT stored on the item (government_board_items
+// .constitution), not on the live config — an amendment must not rewrite who
+// may vote on an already-open item mid-sitting.
+async function resolveBoardMembers(board) {
+  const parsed = parseMembershipPredicate(board && board.membership);
+  if (!parsed) return Object.freeze([]); // unparseable predicate → nobody governs
+  const rows = await db.getActiveBuildersWithRank(parsed.rankKey);
+  return Object.freeze(rows.map((r) => Object.freeze({
+    builder_id: String(r.builder_id),
+    github_login: r.github_login,
+    display_name: r.display_name,
+  })));
+}
+
+// The R08 re-check: is THIS builder on the board defined by THIS constitution,
+// right now? One indexed lookup rather than materializing the whole list —
+// same rows, same filters, same fail-closed null handling.
+async function isBoardMember(builderId, board) {
+  if (builderId === null || builderId === undefined || builderId === '') return false;
+  const parsed = parseMembershipPredicate(board && board.membership);
+  if (!parsed) return false;
+  return db.builderHoldsRankActive(builderId, parsed.rankKey);
+}
+
+module.exports = {
+  parseMembershipPredicate,
+  resolveBoardMembers,
+  isBoardMember,
+};

package/modules/government/db.js

@@ -239,6 +239,48 @@ async function unassignRank({ builderId, rankKey }) {
   return rowCount > 0;
 }
 
+// --- the board membership READS (BV1.R06 of goal 1000069) --------------------
+//
+// Both filters are load-bearing, and both must appear in BOTH queries below —
+// board-membership.js's list and its single-member re-check must be the same
+// question at two granularities, never two questions:
+//   • b.status = 'active' — a deactivated builder is off the board the moment
+//     builder-exit flips them (their rank also drops to xenos, but membership
+//     must not depend on that ordering);
+//   • b.system_role IS NULL — a machine principal never governs. Today's two
+//     principals are xenos+inactive so the status filter would catch them, but
+//     that is circumstance, not a rule; this makes it structural, mirroring the
+//     resolver's principal-key drop (R98).
+
+async function getActiveBuildersWithRank(rankKey) {
+  const { rows } = await pool.query(
+    `SELECT br.builder_id, b.github_login, b.display_name
+       FROM government_builder_ranks br
+       JOIN builders b ON b.id = br.builder_id
+      WHERE br.rank_key = $1
+        AND b.status = 'active'
+        AND b.system_role IS NULL
+      ORDER BY br.builder_id`,
+    [rankKey],
+  );
+  return rows;
+}
+
+async function builderHoldsRankActive(builderId, rankKey) {
+  const { rows } = await pool.query(
+    `SELECT 1
+       FROM government_builder_ranks br
+       JOIN builders b ON b.id = br.builder_id
+      WHERE br.builder_id = $1
+        AND br.rank_key = $2
+        AND b.status = 'active'
+        AND b.system_role IS NULL
+      LIMIT 1`,
+    [builderId, rankKey],
+  );
+  return rows.length > 0;
+}
+
 module.exports = {
   getPermissionKeysForBuilder,
   getRankKeysForBuilder,
@@ -254,4 +296,6 @@ module.exports = {
   listAssignments,
   assignRank,
   unassignRank,
+  getActiveBuildersWithRank,
+  builderHoldsRankActive,
 };

package/modules/government/routes/government.js

@@ -23,6 +23,7 @@ const resolver = require('../resolver');
 const catalog = require('../catalog');
 const db = require('../db');
 const sessionScopes = require('../session-scopes');
+const boardMembership = require('../board-membership');
 
 // The port surface. Deliberately narrow: resolution + the catalog reads a gate or
 // the Archon tab needs. It grows with R98-R101 (principals, session-scopes,
@@ -78,6 +79,13 @@ const governmentPort = {
   narrowToSessionScope: resolver.narrowToSessionScope,
   sessionScopeFor: sessionScopes.scopeFor,
   listSessionScopes: () => sessionScopes.SESSION_SCOPES,
+  // The Board Room's membership axis (R06 of goal 1000069): who governs, right
+  // now, under a given constitution's board block — per request, uncached, the
+  // same ADR 0016 posture as the resolves above. On the port because R21 (the
+  // Discord announcer) needs the member list from outside this module.
+  parseMembershipPredicate: boardMembership.parseMembershipPredicate,
+  resolveBoardMembers: boardMembership.resolveBoardMembers,
+  isBoardMember: boardMembership.isBoardMember,
 };
 
 function registerSeams() {

package/package-lock.json

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

package/package.json

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

@@ -871,8 +871,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.220 with no explicit bump. run 32095276039. (task 1002620)
 //   1.19.222 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.221 with no explicit bump. run 32096034408. (task 1002620)
+//   1.19.223 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.222 with no explicit bump. run 32097491676. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.222'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.223'; // 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_membership.mjs

@@ -0,0 +1,183 @@
+// tests/government_board_membership.mjs — who sits on the board (BV1.R06 of
+// goal 1000069, ADR 0175).
+//
+// DB-free: the pure predicate parser is exercised directly, and the two resolve
+// entry points run against a monkeypatched db module (the government_routes.mjs
+// idiom), so the invariants here are testable without Postgres. What must hold:
+//
+//   1. FAIL-CLOSED — an unparseable predicate resolves to NOBODY, never to
+//      everybody. Membership widening by typo is the board-shaped version of the
+//      config file granting a permission, and it fails the same direction.
+//   2. THE TWO GRAMMARS AGREE — config.js (R05) decides which predicates SURVIVE
+//      sanitization; this file decides which predicates RESOLVE. A string the
+//      config keeps but the resolver cannot parse would be a constitution that
+//      validates and then seats nobody, silently.
+//   3. NO CACHE — the member list is computed per call from the db module's
+//      CURRENT answer. A demotion between two calls changes the second answer.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+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 membership = require(path.join(GOV, 'board-membership.js'));
+const db = require(path.join(GOV, 'db.js'));
+const { sanitizeBoard, BOARD_DEFAULTS } = require(path.join(GOV, 'config.js'));
+
+const { parseMembershipPredicate, resolveBoardMembers, isBoardMember } = membership;
+
+// ── the pure parser ──────────────────────────────────────────────────────────
+
+test('the one v1 grammar parses: rank:<key>', () => {
+  assert.deepEqual(parseMembershipPredicate('rank:archon'), { rankKey: 'archon' });
+  assert.deepEqual(parseMembershipPredicate('rank:metic'), { rankKey: 'metic' });
+  assert.deepEqual(parseMembershipPredicate('rank:triage-helper'), { rankKey: 'triage-helper' },
+    'a CUSTOM rank is legal by shape — whether it seats anyone is the DB\'s answer');
+  assert.deepEqual(parseMembershipPredicate('rank:board_member'), { rankKey: 'board_member' });
+});
+
+test('everything else parses to null — the fail-closed value', () => {
+  const junk = [
+    undefined, null, 42, {}, [], '',
+    'archon',                       // bare rank, no axis prefix
+    'rank:',                        // empty key
+    'RANK:ARCHON',                  // grammar is lowercase
+    'rank:Archon',
+    'role:builder',                 // the rejected role-chamber model — must never parse
+    'rank:archon;metic',            // no lists in v1
+    'rank: archon',                 // no whitespace
+    'builder:3',                    // naming a PERSON is config-as-authority — refused by shape
+  ];
+  for (const p of junk) {
+    assert.equal(parseMembershipPredicate(p), null, `${JSON.stringify(p)} must not parse`);
+  }
+});
+
+test('the parser and the config sanitizer agree on every sample — no validate-then-seat-nobody gap', () => {
+  // Property: config KEEPS a membership string ⇔ this file PARSES it. A predicate
+  // that survives R05's sanitizer but fails R06's parse would be a constitution
+  // that looks valid and silently seats nobody; the reverse would mean the
+  // resolver honours strings config would have replaced with the default.
+  const samples = [
+    'rank:archon', 'rank:metic', 'rank:xenos', 'rank:triage-helper', 'rank:a1_b-c',
+    'archon', 'rank:', 'RANK:ARCHON', 'role:builder', 'builder:3', '', 'rank: archon',
+    'rank:Archon', 'rank:archon;metic',
+  ];
+  for (const s of samples) {
+    const kept = sanitizeBoard({ membership: s }).membership === s;
+    const parses = parseMembershipPredicate(s) !== null;
+    assert.equal(kept, parses, `config and resolver disagree on ${JSON.stringify(s)}`);
+  }
+});
+
+// ── the resolve entry points, against a stubbed db ───────────────────────────
+
+// board-membership.js reads db.* by property lookup at CALL time, so replacing
+// the shared module object's methods (and restoring in finally) drives both
+// entry points without Postgres.
+async function withDb(stubs, fn) {
+  const originals = {};
+  for (const [k, v] of Object.entries(stubs)) { originals[k] = db[k]; db[k] = v; }
+  try { return await fn(); }
+  finally { for (const [k, v] of Object.entries(originals)) db[k] = v; }
+}
+
+const MONARCHY = Object.freeze({ ...BOARD_DEFAULTS });
+
+test('resolveBoardMembers: the happy path — rows come back frozen, ids as strings', async () => {
+  await withDb({
+    getActiveBuildersWithRank: async (rankKey) => {
+      assert.equal(rankKey, 'archon', 'the predicate\'s rank key reaches the query verbatim');
+      return [
+        { builder_id: 42n, github_login: 'first-member', display_name: 'First Member' },
+        { builder_id: '1000099', github_login: 'second-member', display_name: 'Second Member' },
+      ];
+    },
+  }, async () => {
+    const members = await resolveBoardMembers(MONARCHY);
+    assert.equal(members.length, 2);
+    assert.deepEqual(members.map((m) => m.builder_id), ['42', '1000099'],
+      'ids are normalized to strings — Postgres bigints and JS numbers must compare equal downstream');
+    assert.ok(Object.isFrozen(members) && Object.isFrozen(members[0]));
+  });
+});
+
+test('an unparseable predicate resolves to NOBODY without touching the db', async () => {
+  await withDb({
+    getActiveBuildersWithRank: async () => { throw new Error('must not be called'); },
+    builderHoldsRankActive: async () => { throw new Error('must not be called'); },
+  }, async () => {
+    for (const board of [undefined, null, {}, { membership: 'everyone' }, { membership: 'role:builder' }]) {
+      assert.deepEqual(await resolveBoardMembers(board), [], `${JSON.stringify(board)} seats nobody`);
+      assert.equal(await isBoardMember('42', board), false);
+    }
+  });
+});
+
+test('a predicate naming a rank with no assignments seats an EMPTY board — loud, not widened', async () => {
+  await withDb({ getActiveBuildersWithRank: async () => [] }, async () => {
+    const members = await resolveBoardMembers({ ...MONARCHY, membership: 'rank:board-of-directors' });
+    assert.deepEqual(members, []);
+  });
+});
+
+test('isBoardMember: fail-closed on a missing builder id, true only on a live row', async () => {
+  await withDb({
+    builderHoldsRankActive: async (builderId, rankKey) => builderId === '42' && rankKey === 'archon',
+  }, async () => {
+    assert.equal(await isBoardMember('42', MONARCHY), true);
+    assert.equal(await isBoardMember('999', MONARCHY), false);
+    for (const bad of [null, undefined, '']) {
+      assert.equal(await isBoardMember(bad, MONARCHY), false, `${String(bad)} is nobody`);
+    }
+  });
+});
+
+test('NO CACHE: a demotion between two calls changes the second answer', async () => {
+  // The ADR 0016 instant-demotion property, observed rather than asserted from
+  // source text: the same call against a db whose answer changed returns the
+  // changed answer. A memo anywhere in the path would fail this.
+  let demoted = false;
+  await withDb({
+    getActiveBuildersWithRank: async () => (demoted
+      ? []
+      : [{ builder_id: '42', github_login: 'demoted-archon', display_name: 'Demoted Archon' }]),
+    builderHoldsRankActive: async () => !demoted,
+  }, async () => {
+    assert.equal((await resolveBoardMembers(MONARCHY)).length, 1);
+    assert.equal(await isBoardMember('42', MONARCHY), true);
+    demoted = true;
+    assert.deepEqual(await resolveBoardMembers(MONARCHY), [], 'off the board on the very next request');
+    assert.equal(await isBoardMember('42', MONARCHY), false);
+  });
+});
+
+test('the membership queries exclude machines and the deactivated — structurally, in the SQL', () => {
+  // The db half is one query away from Postgres, so its two load-bearing filters
+  // are pinned as source: b.status = 'active' (builder-exit takes effect without
+  // depending on the rank drop's ordering) and b.system_role IS NULL (a machine
+  // principal never governs — today's principals happen to be inactive xenos,
+  // but that is circumstance; this is the rule). Both must appear in BOTH reads.
+  const fs = require('node:fs');
+  const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
+  const start = src.indexOf('getActiveBuildersWithRank');
+  assert.ok(start > -1);
+  const block = src.slice(start);
+  assert.equal((block.match(/b\.status = 'active'/g) || []).length, 2, 'both reads filter status');
+  assert.equal((block.match(/b\.system_role IS NULL/g) || []).length, 2, 'both reads exclude principals');
+});
+
+test('the government port carries the membership axis for cross-module consumers (R21)', () => {
+  const routes = require(path.join(GOV, 'routes', 'government.js'));
+  assert.equal(typeof routes, 'function', 'the router factory registers the port');
+  const api = require(path.join(ROOT, 'src', 'module-api.js'));
+  routes(); // registering twice is a no-op (hasProvider guard)
+  const port = api.resolveOptional('government');
+  assert.ok(port, 'the government port is registered');
+  for (const method of ['parseMembershipPredicate', 'resolveBoardMembers', 'isBoardMember']) {
+    assert.equal(typeof port[method], 'function', `port.${method} must be callable`);
+  }
+});