@bongos/core 1.20.25 → 1.20.26

package/modules/government/routes/government.js

@@ -108,6 +108,13 @@ const governmentPort = {
   // is no counterpart that records an outcome, and there must never be one: an
   // outcome is written by a close, never by the module reading it.
   boardPassForIdea: board.boardPassForIdea,
+  // task 1004429 (BV2.PS04): a finished genesis stage is put to the board — the
+  // genesis home (task 1004423) calls this when a stage's tasks are done. The
+  // finished-tasks gate lives inside board.js; the item is an ordinary one under
+  // the constitution in force. And the founding band's read: per stage, what it
+  // is waiting on. A pass is announced as `board.genesis_stage.passed`.
+  openGenesisStageClose: board.openGenesisStageClose,
+  genesisStageStatus: board.genesisStageStatus,
 };
 
 function registerSeams() {
@@ -460,6 +467,19 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.vote.cast — the founding band's read (task 1004429): each
+  // genesis stage's latest sitting, and who it is still waiting on under the
+  // item's own snapshot. Same atom as the room — seeing who is still to vote is
+  // part of the open ballot (§9). A read; nothing here opens or decides.
+  router.get('/government/board/genesis-stages', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await board.genesisStageStatus());
+    } catch (err) {
+      log.error('[gds] GET /government/board/genesis-stages', err);
+      res.fail('genesis_stage_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.item.open — put an AMENDMENT to the board (R14 of goal
   // 1000069, ADR 0175 §7). The board's other subject never comes through here:
   // a Full Idea's window opens AUTOMATICALLY on grade pass (R07), so requesting

package/modules/hall-ui/public/board-room.js

@@ -132,6 +132,11 @@
       const title = item.subject ? item.subject.title : `idea ${item.subject_id}`;
       return `<a href="/#/idea/${escapeHtml(String(item.subject_id))}">${escapeHtml(title)}</a> ${pill('quiet', 'Full Idea')}`;
     }
+    // task 1004429: the third subject — closing a founding stage.
+    if (item.subject_type === 'genesis_stage') {
+      const label = item.subject ? item.subject.label : `stage ${item.subject_id}`;
+      return `Close the ${escapeHtml(label)} stage ${pill('quiet', 'genesis stage')}`;
+    }
     return `Constitutional amendment ${pill('quiet', 'amendment')}`;
   }
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.25",
+  "version": "1.20.26",
   "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/release-notes.json

@@ -8210,5 +8210,11 @@
       "id": "1004412",
       "text": "New users can create a project again. Since 19 September, anyone new who pressed \"Create my project\" was turned away with a vague error, because hosted projects had been limited to trusted builders. Now everyone who is signed"
     }
+  ],
+  "1.20.26": [
+    {
+      "id": "1004429",
+      "text": "A new project's founding stages are now decided by its own government. When a stage's work is finished, closing the stage goes to the Board Room like any other decision. A solo founder under the default one-leader government c"
+    }
   ]
 }

package/src/bongos/route-rank-check.js

@@ -268,6 +268,9 @@ const GOVERNMENT_PINS = {
   // R18: the Constitution view — the live rule + the amendment history; reading
   // the rule you vote under is part of casting.
   'GET /government/constitution': 'perm:board.vote.cast',
+  // task 1004429: the founding band — who each genesis stage is waiting on. A
+  // read of the open ballot, so the same atom as the room.
+  'GET /government/board/genesis-stages': 'perm:board.vote.cast',
 };
 
 // Module-scoped privileged-rank pins: a privileged route that lives in a FEATURE

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.25'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.26'; // 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('discord'); log.info('mounted');

package/tests/government_board_genesis_stage.mjs

@@ -0,0 +1,305 @@
+// tests/government_board_genesis_stage.mjs — a genesis stage is the Board
+// Room's third subject (task 1004429 / BV2.PS04, spec decision D7).
+//
+// When a founding stage's tasks are all finished (shipped or dropped), closing
+// the stage is put to the constitution IN FORCE as a board item. DB-free (db
+// monkeypatched, membership logic real). The invariants:
+//
+//   1. THE GATE IS "THE STAGE'S TASKS ARE FINISHED", and it lives here — an
+//      unknown stage, an empty task list, or any unfinished (or missing) task
+//      opens nothing, before any write.
+//   2. THE ITEM IS AN ORDINARY ITEM — it snapshots the live constitution, runs
+//      the live window, and is idempotent through government_003's one-open-
+//      per-subject index (subject_id = the stage number).
+//   3. MONARCHY: THE FOUNDER'S ONE CONFIRM CLOSES IT — under first_ratifier the
+//      founder who put the stage up casts yes and the sitting passes. No bypass
+//      makes that true: the author rule is full_idea-scoped (ADR 0191), exactly
+//      as for an amendment, so the founder is simply the first ratifier.
+//   4. EVERY OTHER SHAPE IS A REAL SITTING — consent waits for full turnout,
+//      majority counts the membership; no new pass rule exists.
+//   5. A PASS FIRES `board.genesis_stage.passed` for the genesis home, pays no
+//      credit and no ratify karma.
+//   6. "WHO IS THIS STAGE WAITING ON" is answered from the item's own snapshot
+//      and the live members, and the founder is SUMMONED for their own stage.
+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 api = require(path.join(ROOT, 'src', 'module-api.js'));
+const board = require(path.join(GOV, 'board.js'));
+const db = require(path.join(GOV, 'db.js'));
+const config = require(path.join(GOV, 'config.js'));
+
+const { GENESIS_STAGES, openGenesisStageClose, genesisStageStatus, castVote, maybeCloseAfterVote, closeItem } = board;
+
+const FOUNDER = '42';
+const AVERY = '43';
+const JORDAN = '44';
+
+const MONARCHY = Object.freeze({
+  membership: 'rank:archon', pass_rule: 'first_ratifier', window_minutes: null, close_early_on_full_turnout: true,
+});
+const CONSENT = Object.freeze({ ...MONARCHY, membership: 'rank:metic+', pass_rule: 'consent', window_minutes: 1440 });
+const MAJORITY = Object.freeze({ ...CONSENT, pass_rule: 'majority' });
+
+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; }
+}
+
+// Capture one seam event for the duration of fn.
+async function capturing(event, fn) {
+  const seen = [];
+  const off = api.on(event, (p) => { seen.push(p); });
+  try { await fn(); } finally { if (typeof off === 'function') off(); }
+  return seen;
+}
+
+const stageItem = (over = {}) => ({
+  id: '90', subject_type: 'genesis_stage', subject_id: '3', opened_by: FOUNDER,
+  closes_at: null, closed_at: null, outcome: null, expired: false, constitution: MONARCHY, ...over,
+});
+const vote = (voter, direction = 'yes', extra = {}) => ({ voter_id: voter, direction, ...extra });
+const member = (id, login) => ({ builder_id: id, github_login: login, display_name: login });
+
+// ── the stage list ──────────────────────────────────────────────────────────
+
+test('the five founding stages, in order, numbered 1..5 — the range the migration CHECK allows', () => {
+  assert.deepEqual(GENESIS_STAGES.map((s) => s.key), ['scope', 'strategize', 'charter', 'legalize', 'legislation']);
+  assert.deepEqual(GENESIS_STAGES.map((s) => s.number), [1, 2, 3, 4, 5]);
+  assert.ok(Object.isFrozen(GENESIS_STAGES) && GENESIS_STAGES.every(Object.isFrozen));
+  const sql = fs.readFileSync(path.join(GOV, 'migrations', 'government_020_genesis_stage_subject.sql'), 'utf8');
+  assert.match(sql, /subject_type IN \('full_idea', 'constitutional_amendment', 'genesis_stage'\)/,
+    'the CHECK widens to the third subject and keeps the first two');
+  assert.match(sql, new RegExp(`subject_id BETWEEN 1 AND ${GENESIS_STAGES.length}`),
+    'the stage-number range in the database is the length of the one list here');
+});
+
+// ── invariant 1: the finished-tasks gate ─────────────────────────────────────
+
+test('nothing opens for an unknown stage, an empty task list, or any unfinished or missing task', async () => {
+  await withDb({
+    openBoardItem: async () => { throw new Error('must not be reached'); },
+    getTaskStatuses: async (ids) => ids.filter((id) => id !== 103).map((id) => ({
+      id: String(id), status: id === 102 ? 'active' : 'shipped',
+    })),
+  }, async () => {
+    assert.equal((await openGenesisStageClose({ stageKey: 'coronation', taskIds: [101], openedBy: FOUNDER })).reason, 'unknown_stage');
+    assert.equal((await openGenesisStageClose({ stageKey: 'charter', taskIds: [], openedBy: FOUNDER })).reason, 'no_stage_tasks');
+    assert.equal((await openGenesisStageClose({ stageKey: 'charter', taskIds: ['x'], openedBy: FOUNDER })).reason, 'no_stage_tasks');
+    const out = await openGenesisStageClose({ stageKey: 'charter', taskIds: [101, 102, 103], openedBy: FOUNDER });
+    assert.equal(out.opened, false);
+    assert.equal(out.reason, 'stage_tasks_unfinished');
+    assert.deepEqual(out.unfinished, [
+      { task_id: '102', status: 'active' },
+      { task_id: '103', status: null },
+    ], 'each blocker is named, and a task nobody can find counts as unfinished');
+  });
+});
+
+// ── invariant 2: an ordinary item under the constitution in force ────────────
+
+test('finished tasks (shipped AND dropped) open ONE item that snapshots the live constitution', async () => {
+  let opened = null;
+  const live = config.loadGovernmentConfig().board;
+  const events = await capturing('board.item.opened', () => withDb({
+    getTaskStatuses: async () => [{ id: '101', status: 'shipped' }, { id: '102', status: 'abandoned' }],
+    openBoardItem: async (args) => { opened = args; return { ...stageItem(), constitution: args.constitution }; },
+  }, async () => {
+    const out = await openGenesisStageClose({ stageKey: 'charter', taskIds: [101, '102'], openedBy: FOUNDER });
+    assert.equal(out.opened, true);
+    assert.equal(out.stage.key, 'charter');
+  }));
+  assert.equal(opened.subjectType, 'genesis_stage');
+  assert.equal(opened.subjectId, 3, 'the subject is the stage NUMBER — one open sitting per stage, structurally');
+  assert.equal(opened.openedBy, FOUNDER);
+  assert.deepEqual(opened.constitution, live, 'the item snapshots the constitution in force, like every item');
+  assert.equal(opened.windowMinutes, live.window_minutes, 'the live clock rule, unchanged');
+  assert.equal(events.length, 1, 'the window-open nudge fires, as for any item');
+});
+
+test('a second open while the stage sits returns the standing item and opens nothing', async () => {
+  const events = await capturing('board.item.opened', () => withDb({
+    getTaskStatuses: async () => [{ id: '101', status: 'shipped' }],
+    openBoardItem: async () => null, // the partial unique index said no
+    getOpenBoardItem: async (type, id) => (type === 'genesis_stage' && id === 3 ? stageItem() : null),
+  }, async () => {
+    const out = await openGenesisStageClose({ stageKey: 'charter', taskIds: [101], openedBy: FOUNDER });
+    assert.equal(out.opened, false);
+    assert.equal(out.reason, 'already_open');
+    assert.equal(out.item.id, '90');
+  }));
+  assert.equal(events.length, 0, 'nobody is summoned twice');
+});
+
+// ── invariant 3: the monarchy default — the founder's one confirm ────────────
+
+test('under Monarchy / BDFL the founder\'s single yes closes the stage — no bypass, just the first ratifier', async () => {
+  const votes = [];
+  let karmaPaid = false;
+  const passed = await capturing('board.genesis_stage.passed', async () => {
+    await withDb({
+      getBoardItemForVote: async () => stageItem(),
+      builderHoldsRankActive: async (id) => id === FOUNDER,
+      getActiveBuildersWithRank: async () => [member(FOUNDER, 'founder')],
+      // Returns opened_by for any non-idea subject — the founder. The point of
+      // the test is that the deciding rules never hold it against them.
+      getBoardItemAuthor: async (item) => item.opened_by,
+      insertBoardVote: async (row) => { const v = { ...row, voter_id: row.voterId, direction: row.direction }; votes.push(v); return v; },
+      insertVoteKarma: async () => {},
+      getVotesForItem: async () => votes,
+      closeBoardItem: async ({ outcome, afterClose }) => {
+        assert.equal(afterClose, null, 'a stage close books no credit — nothing rides the transaction');
+        return { ...stageItem(), closed_at: 'T', outcome };
+      },
+      insertAuthorRatifyKarma: async () => { karmaPaid = true; return true; },
+    }, async () => {
+      const cast = await castVote({ itemId: '90', voterId: FOUNDER, direction: 'yes' });
+      assert.equal(cast.ok, true);
+      assert.equal(cast.self_cast, false, 'the author rule is full_idea-scoped — the founder is not a self-caster here');
+      const closed = await maybeCloseAfterVote('90');
+      assert.equal(closed.closed, true);
+      assert.equal(closed.outcome, 'passed');
+    });
+  });
+  assert.equal(karmaPaid, false, 'closing a stage ratifies no authored work — no ratify karma');
+  assert.deepEqual(passed, [{ item_id: '90', stage_key: 'charter', stage_number: 3, passed_at: 'T' }],
+    'the genesis home hears exactly which stage passed');
+});
+
+// ── invariant 4: every other shape is a real sitting ─────────────────────────
+
+test('under consent the founder\'s yes does not end it — the sitting waits for full turnout', async () => {
+  const members = [member(FOUNDER, 'founder'), member(AVERY, 'avery')];
+  const votes = [vote(FOUNDER)];
+  await withDb({
+    getBoardItemForVote: async () => stageItem({ constitution: CONSENT }),
+    getActiveBuildersWithRank: async () => members,
+    getVotesForItem: async () => votes,
+    getBoardItemAuthor: async (item) => item.opened_by,
+    closeBoardItem: async ({ outcome }) => ({ ...stageItem({ constitution: CONSENT }), closed_at: 'T', outcome }),
+    insertAuthorRatifyKarma: async () => true,
+  }, async () => {
+    assert.equal((await maybeCloseAfterVote('90')).reason, 'window_still_open');
+    votes.push(vote(AVERY));
+    const out = await maybeCloseAfterVote('90');
+    assert.equal(out.outcome, 'passed', 'every member has spoken, nobody objected');
+  });
+});
+
+test('under majority, silence is not assent: one yes of three returns the stage at expiry', async () => {
+  const members = [member(FOUNDER, 'f'), member(AVERY, 'a'), member(JORDAN, 'j')];
+  const passed = await capturing('board.genesis_stage.passed', () => withDb({
+    getVotesForItem: async () => [vote(FOUNDER)],
+    getActiveBuildersWithRank: async () => members,
+    getBoardItemAuthor: async (item) => item.opened_by,
+    closeBoardItem: async ({ outcome }) => ({ ...stageItem({ constitution: MAJORITY }), closed_at: 'T', outcome }),
+  }, async () => {
+    const out = await closeItem(stageItem({ constitution: MAJORITY }), { cause: 'expiry' });
+    assert.equal(out.outcome, 'returned');
+  }));
+  assert.equal(passed.length, 0, 'a returned stage announces no pass');
+});
+
+// ── invariant 6: who is this stage waiting on ────────────────────────────────
+
+test('the stage status names who each open sitting is waiting on, from the item\'s own snapshot', async () => {
+  const items = [
+    { ...stageItem({ id: '80', subject_id: '1' }), closed_at: 'T1', outcome: 'passed' },
+    stageItem({ id: '90', subject_id: '3', constitution: CONSENT, closes_at: 'T9', remaining_seconds: 600 }),
+  ];
+  let resolvedFor = null;
+  await withDb({
+    listLatestGenesisStageItems: async () => items,
+    getVotesForItems: async () => [{ item_id: '90', voter_id: AVERY, direction: 'yes', github_login: 'avery', display_name: 'Avery' }],
+    getActiveBuildersWithRank: async (keys) => { resolvedFor = keys; return [member(FOUNDER, 'founder'), member(AVERY, 'avery')]; },
+  }, async () => {
+    const status = await genesisStageStatus();
+    assert.deepEqual(status.stages.map((s) => [s.key, s.state]), [
+      ['scope', 'passed'], ['strategize', 'not_put'], ['charter', 'sitting'], ['legalize', 'not_put'], ['legislation', 'not_put'],
+    ]);
+    const charter = status.stages[2];
+    assert.equal(charter.item_id, '90');
+    assert.equal(charter.pass_rule, 'consent');
+    assert.equal(charter.remaining_seconds, 600, 'the database\'s own countdown, never client clock math');
+    assert.deepEqual(charter.waiting_on.map((m) => m.builder_id), [FOUNDER]);
+    assert.deepEqual(charter.voted.map((m) => [m.builder_id, m.direction]), [[AVERY, 'yes']]);
+    assert.equal(typeof charter.needs, 'string');
+    assert.ok(charter.needs.length > 0, 'the rule is said in words');
+    assert.equal(status.stages[0].waiting_on.length, 0, 'a closed stage waits on nobody');
+  });
+  assert.ok(resolvedFor.includes('archon') && resolvedFor.includes('metic'),
+    'membership is resolved under the SNAPSHOT (rank:metic+), not the live config');
+});
+
+test('under monarchy the band says one vote decides, and names every member who could give it', async () => {
+  await withDb({
+    listLatestGenesisStageItems: async () => [stageItem()],
+    getVotesForItems: async () => [],
+    getActiveBuildersWithRank: async () => [member(FOUNDER, 'founder')],
+  }, async () => {
+    const charter = (await genesisStageStatus()).stages[2];
+    assert.equal(charter.one_vote_decides, true);
+    assert.deepEqual(charter.waiting_on.map((m) => m.builder_id), [FOUNDER]);
+  });
+});
+
+test('every pass rule the constitution knows has its words for the band — no more, no fewer', () => {
+  assert.deepEqual(Object.keys(board.PASS_RULE_WORDS).sort(), [...config.PASS_RULES].sort());
+});
+
+test('the latest-sitting read has its own partial index, keyed to its ORDER BY', () => {
+  const sql = fs.readFileSync(path.join(GOV, 'migrations', 'government_020_genesis_stage_subject.sql'), 'utf8');
+  assert.match(sql, /ON government_board_items \(subject_id, opened_at DESC, id DESC\)\s+WHERE subject_type = 'genesis_stage'/);
+  const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
+  const block = src.slice(src.indexOf('async function listLatestGenesisStageItems'), src.indexOf('// Author-ratification karma'));
+  assert.match(block, /WHERE subject_type = 'genesis_stage'\s+ORDER BY subject_id, opened_at DESC, id DESC/,
+    'the query filters and orders exactly as the index is built');
+});
+
+test('the founder is summoned for their own stage — the author hold-back is not applied to it', () => {
+  const src = fs.readFileSync(path.join(GOV, 'db.js'), 'utf8');
+  const block = src.slice(src.indexOf('async function openBoardItemsAwaitingVoter'), src.indexOf('async function getTaskStatuses'));
+  assert.match(block, /WHEN i\.subject_type = 'genesis_stage' THEN NULL/,
+    'the summons SQL yields no author for a stage, so pendingVotesFor never skips the founder');
+});
+
+// ── the surfaces that carry it ───────────────────────────────────────────────
+
+test('the Board Room view names the stage instead of mistaking it for an amendment', async () => {
+  await withDb({
+    listOpenBoardItems: async () => [stageItem()],
+    listClosedBoardItems: async () => [],
+    getVotesForItems: async () => [],
+    getIdeaSubjects: async () => [],
+    getAmendmentSubjects: async () => [],
+  }, async () => {
+    const view = await board.boardRoomView();
+    assert.deepEqual(view.open[0].subject, { stage_key: 'charter', stage_number: 3, label: 'Charter', author_id: FOUNDER });
+  });
+  const room = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'board-room.js'), 'utf8');
+  assert.match(room, /subject_type === 'genesis_stage'/, 'the hall card has its own line for a stage');
+  const discord = require(path.join(ROOT, 'modules', 'discord', 'board-broadcast.js'));
+  if (typeof discord.subjectLabel === 'function') {
+    assert.match(discord.subjectLabel('genesis_stage'), /genesis stage/i);
+  } else {
+    const src = fs.readFileSync(path.join(ROOT, 'modules', 'discord', 'board-broadcast.js'), 'utf8');
+    assert.match(src, /genesis_stage/, 'the announcer does not call a stage "A Full Idea"');
+  }
+});
+
+test('the port carries the open and the status; the status route is pinned on the vote atom', () => {
+  const routes = fs.readFileSync(path.join(GOV, 'routes', 'government.js'), 'utf8');
+  assert.match(routes, /openGenesisStageClose: board\.openGenesisStageClose/);
+  assert.match(routes, /genesisStageStatus: board\.genesisStageStatus/);
+  assert.match(routes, /router\.get\('\/government\/board\/genesis-stages', api\.requireBuilder, api\.requirePermission\('board\.vote\.cast'\)/);
+  const pins = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'), 'utf8');
+  assert.match(pins, /'GET \/government\/board\/genesis-stages': 'perm:board\.vote\.cast'/);
+});

package/tests/government_seed.mjs

@@ -43,6 +43,7 @@ const NON_GRANT_MIGRATIONS = new Set([
   'government_008_closed_items_index.sql',         // R16 closed-history index (task 1003029)
   'government_017_board_section_keys_v2.sql',      // BV2.R06 board section_key CHECK widening (task 1004085)
   'government_018_passed_items_index.sql',         // BV2.R17 passed-item lookup index (task 1004096)
+  'government_020_genesis_stage_subject.sql',      // BV2.PS04 genesis_stage board subject CHECK (task 1004429)
 ]);
 
 // Permission keys RENAMED after the grant migrations that first granted them.