@bongos/core 1.21.8 → 1.21.9

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 497 endpoints across 92 route files.
+> **Generated from the live route files** — the route file is authoritative. 499 endpoints across 92 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -340,7 +340,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/goals/rollups` | `any-builder` | — | GET /goals/rollups?version= — one small row per goal: readiness counters, the last-activity timestamp, the craft set, and the next claima… |
 | GET | `/api/bongos/goals/suggestions` | `any-builder` | — | GET /goals/suggestions — "which goal should this draft live in?", answered before anything is created (task 1003062 / R07). |
 
-## `government` (17)
+## `government` (19)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -348,10 +348,12 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/government/assignments` | `archon` | `builder_id`, `rank_key` | government.manage — assign a CUSTOM rank to a builder. |
 | DELETE | `/api/bongos/government/assignments/:builderId/:rankKey` | `archon` | — | government.manage — remove a custom-rank assignment. |
 | POST | `/api/bongos/government/board/charter` | `metic+archon` | `form`, `franchise`, `council_rank`, `pass_rule`, `rationale_md`, `acknowledge_self_removal` | board.item.open — the genesis charter + legislation choice (task 1004427, spec D10): a form of government and/or its two live settings (f… |
+| POST | `/api/bongos/government/board/decision-rules` | `metic+archon` | `rules`, `rationale_md` | board.item.open — propose a change to WHO DECIDES WHAT (task 1004529): one or more buildings' rows of the decision-rules table, filed as … |
 | GET | `/api/bongos/government/board/genesis-stages` | `any-builder` | — | 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 … |
 | GET | `/api/bongos/government/board/items` | `any-builder` | — | board.vote.cast — the Board Room view: open items with their clock, the OPEN BALLOT, the closed history (R16 of goal 1000069). |
 | POST | `/api/bongos/government/board/items` | `metic+archon` | `subject_type`, `proposal`, `rationale_md`, `acknowledge_self_removal` | board.item.open — put an AMENDMENT to the board (R14 of goal 1000069, ADR 0175 §7). |
 | POST | `/api/bongos/government/board/items/:itemId/votes` | `any-builder` | `direction`, `reason_md`, `section_key` | board.vote.cast — cast a vote on an open board item (R08 of goal 1000069, ADR 0175). |
+| POST | `/api/bongos/government/board/matters` | `metic+archon` | `area`, `title`, `detail_md`, `action` | board.item.open — put a MATTER to a building's sitting (task 1004529): the board's new subjects, one per building other than the charter. |
 | GET | `/api/bongos/government/constitution` | `any-builder` | — | board.vote.cast — the Constitution view (R18 of goal 1000069): the live board block plus the full amendment history, passed and returned … |
 | GET | `/api/bongos/government/docket` | `any-builder` | — | board.vote.cast — the governor's DOCKET (task 1004523, goal 1000125): ONE read of every matter waiting on, or moving for, a governor, whi… |
 | GET | `/api/bongos/government/permissions` | `archon` | — | government.manage — the permission catalog + principals, straight from code (the catalog is CODE, not a table); no DB read. |

package/docs/module-api-changelog.md

@@ -2843,5 +2843,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.6 with no explicit bump. run 37038340446. (task 1002620)
   1.21.8 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.7 with no explicit bump. run 37041143274. (task 1002620)
+  1.21.9 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.8 with no explicit bump. run 37042188671. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/discord/board-broadcast.js

@@ -149,6 +149,8 @@ const CHANNEL = 'board_room';
 
 function subjectLabel(subjectType) {
   if (subjectType === 'genesis_stage') return 'A genesis stage'; // task 1004429
+  // task 1004529: a building's matter (rules_matter, people_matter, ...)
+  if (typeof subjectType === 'string' && subjectType.endsWith('_matter')) return 'A matter';
   return subjectType === 'constitutional_amendment' ? 'A constitutional amendment' : 'A Full Idea';
 }
 

package/modules/government/board.js

@@ -61,6 +61,8 @@ const { describeMembership } = require('./membership-predicate');
 // and variable names, and the name a constitution reads as.
 const charter = require('./charter');
 const recommendations = require('./recommendations');
+const decisionRules = require('./decision-rules');
+const decisionBoard = require('./decision-board');
 
 // ADR 0175 §5: the completeness bar a Full Idea must clear to reach the board.
 // Held equal to economy's IDEA_FULL_PASS_BAR by test — see the header.
@@ -296,7 +298,7 @@ async function castVote({ itemId, voterId, direction, reasonMd = null, sectionKe
   // owner's rule is that a self-vote confers no advantage.
   // Not even asked for an amendment — the carve-out means there is nothing to
   // learn, and the read is a query on the vote path.
-  const subjectAuthorId = authorRuleApplies(item.subject_type)
+  const subjectAuthorId = authorRuleApplies(item.subject_type, constitution)
     ? await db.getBoardItemAuthor(item)
     : null;
   const isSelfCast = subjectAuthorId != null && String(subjectAuthorId) === String(voterId);
@@ -389,12 +391,17 @@ async function castVote({ itemId, voterId, direction, reasonMd = null, sectionKe
 // Everything downstream reads the author through this: for an amendment the
 // deciding author is NULL, so the trigger and the tally behave exactly as they
 // did before task 1003273.
-const authorRuleApplies = (subjectType) => subjectType === 'full_idea';
-
-// The author id that the DECIDING rules should see: the real one for a full
-// idea, nobody for an amendment.
-const decidingAuthorId = (subjectType, authorId) =>
-  (authorRuleApplies(subjectType) ? authorId : null);
+// One more scope (task 1004529): a building's matter sat under SIGN-OFF, which
+// IS the author rule (someone who did not build it signs). Other matters are in
+// the amendment's position.
+const authorRuleApplies = (subjectType, constitution = null) =>
+  subjectType === 'full_idea'
+  || (decisionRules.isMatterSubject(subjectType) && !!constitution && constitution.rule === 'signoff');
+
+// The author id the DECIDING rules see: real for a full idea or a sign-off
+// matter, nobody for an amendment.
+const decidingAuthorId = (subjectType, authorId, constitution = null) =>
+  (authorRuleApplies(subjectType, constitution) ? authorId : null);
 
 const isAuthorVote = (v, authorId) =>
   authorId != null && String(v.voter_id) === String(authorId);
@@ -581,7 +588,7 @@ async function closeItem(item, { cause = 'vote' } = {}) {
   // the read stays where it always was — after the tally, only on a pass, for the
   // payload and the ratification karma. Same query count as before this task on
   // the amendment path, one extra on an idea close.
-  let authorId = authorRuleApplies(item.subject_type)
+  let authorId = authorRuleApplies(item.subject_type, constitution)
     ? await db.getBoardItemAuthor(item)
     : null;
   // Only `majority` needs the membership denominator; the absence-passes rules
@@ -596,7 +603,7 @@ async function closeItem(item, { cause = 'vote' } = {}) {
   const outcome = tallyOutcome(votes, {
     constitution, members,
     // Subject-typed: an amendment's proposer is not held to the author rule (§7).
-    authorId: decidingAuthorId(item.subject_type, authorId),
+    authorId: decidingAuthorId(item.subject_type, authorId, constitution),
   });
 
   // The payload's remaining reads (reads never ride a tx they don't need). Only a
@@ -616,16 +623,28 @@ async function closeItem(item, { cause = 'vote' } = {}) {
     : null;
   const payMoney = reward && typeof reward.awardIdeaGovernancePassCredit === 'function';
 
+  // Read BEFORE the close (task 1004529): a decision-rules amendment is written
+  // INSIDE the closing transaction, so a failed write rolls the close back and
+  // the sitting is retried. A board-block amendment still applies after commit.
+  const amendment = outcome === 'passed' && item.subject_type === 'constitutional_amendment'
+    ? await db.getAmendment(item.subject_id)
+    : null;
+  const rulesAmendment = !!amendment && amendment.kind === 'decision_rules';
+  let appliedDecisionRules = null;
+
   const closed = await db.closeBoardItem({
     itemId: item.id,
     outcome,
-    afterClose: payMoney
-      ? async (client) => {
-          credit = await reward.awardIdeaGovernancePassCredit(client, {
-            ideaId: item.subject_id,
-            authorId,
-            completenessScore,
-          });
+    afterClose: (payMoney || rulesAmendment)
+      ? async (client, closedRow) => {
+          if (payMoney) {
+            credit = await reward.awardIdeaGovernancePassCredit(client, {
+              ideaId: item.subject_id,
+              authorId,
+              completenessScore,
+            });
+          }
+          if (rulesAmendment) appliedDecisionRules = await decisionBoard.applyPassedDecisionRules(client, closedRow, amendment);
         }
       : null,
   });
@@ -633,8 +652,10 @@ async function closeItem(item, { cause = 'vote' } = {}) {
 
   // A genesis stage ratifies no authored work — closing it is the project's
   // decision that a stage is done, not a reward for the founder who put it up
-  // (task 1004429). Ideas and amendments pay exactly as before.
+  // (task 1004429). Ideas and amendments pay exactly as before; a building's
+  // matter pays nothing either (task 1004529).
   const authorKarma = outcome === 'passed' && closed.subject_type !== 'genesis_stage'
+    && !decisionRules.isMatterSubject(closed.subject_type)
     ? await awardAuthorRatifyKarma(closed)
     : null;
 
@@ -643,9 +664,8 @@ async function closeItem(item, { cause = 'vote' } = {}) {
   // failure, never silently absorbed. The apply is re-drivable from the passed
   // item + amendment rows. A returned amendment applies nothing.
   let appliedConstitution = null;
-  if (outcome === 'passed' && closed.subject_type === 'constitutional_amendment') {
+  if (outcome === 'passed' && closed.subject_type === 'constitutional_amendment' && !rulesAmendment) {
     try {
-      const amendment = await db.getAmendment(closed.subject_id);
       if (amendment) {
         appliedConstitution = governmentConfig.applyBoardAmendment(amendment.proposed);
       } else {
@@ -656,12 +676,21 @@ async function closeItem(item, { cause = 'vote' } = {}) {
     }
   }
 
+  // A PASSED building matter: the building acts where it can by itself (People
+  // giving or taking a custom rank, task 1004529), after the commit, loudly on
+  // failure — the passed row is the durable decision.
+  let acted = null;
+  if (outcome === 'passed' && decisionRules.isMatterSubject(closed.subject_type)) {
+    acted = await decisionBoard.actOnPassedMatter(closed);
+  }
+
   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 */ }
     if (closed.subject_type === 'genesis_stage') await emitGenesisStagePassed(closed);
+    if (acted) await decisionBoard.announcePassedMatter(acted);
   }
 
   // R22's mirror event: BOTH outcomes, after commit, emitAsync. Separate from
@@ -678,6 +707,8 @@ async function closeItem(item, { cause = 'vote' } = {}) {
     closed: true, item: closed, outcome, cause, author_karma: authorKarma,
     ...(credit ? { credit } : {}),
     ...(appliedConstitution ? { applied_constitution: appliedConstitution } : {}),
+    ...(appliedDecisionRules ? { applied_decision_rules: appliedDecisionRules } : {}),
+    ...(acted ? { acted: acted.result } : {}),
   };
 }
 
@@ -692,7 +723,7 @@ async function maybeCloseAfterVote(itemId) {
   const members = await resolveBoardMembers(constitution);
   // task 1003273: the author is an input to the trigger, not just the tally — an
   // author's cast must never be the vote that ends the sitting.
-  const authorId = authorRuleApplies(item.subject_type)
+  const authorId = authorRuleApplies(item.subject_type, constitution)
     ? await db.getBoardItemAuthor(item)
     : null;
   if (!shouldCloseAfterVote({ constitution, votes, members, authorId })) {
@@ -866,6 +897,17 @@ async function proposeCharter({
   return out.ok ? { ...out, reads_as: readsAs } : out;
 }
 
+// ── who decides what (task 1004529, ADR 0363) ───────────────────────────────
+// The board side lives in decision-board.js; these wrappers add the window-open
+// nudge every open emits.
+const withOpenNudge = (fn) => async (args) => {
+  const out = await fn(args);
+  if (out.ok && out.item) await emitWindowOpened(out.item);
+  return out;
+};
+const proposeDecisionRules = withOpenNudge((a) => decisionBoard.proposeDecisionRules(a));
+const openMatter = withOpenNudge((a) => decisionBoard.openMatter(a));
+
 // ── the board's third subject: closing a genesis stage (task 1004429) ───────
 //
 // Spec decision D7 (docs/specs/bongos-v2-project-startup.md): a new project is
@@ -1071,9 +1113,10 @@ async function boardRoomView({ closedLimit = 20 } = {}) {
   const votes = await db.getVotesForItems(all.map((i) => i.id));
   const ideaIds = [...new Set(all.filter((i) => i.subject_type === 'full_idea').map((i) => i.subject_id))];
   const amendmentIds = [...new Set(all.filter((i) => i.subject_type === 'constitutional_amendment').map((i) => i.subject_id))];
-  const [ideas, amendments] = await Promise.all([
+  const [ideas, amendments, matterById] = await Promise.all([
     db.getIdeaSubjects(ideaIds),
     db.getAmendmentSubjects(amendmentIds),
+    decisionBoard.matterSubjectsById(all), // task 1004529: no query when no matter is on the board
   ]);
   const ideaById = new Map(ideas.map((r) => [String(r.id), r]));
   const amendmentById = new Map(amendments.map((r) => [String(r.id), r]));
@@ -1118,7 +1161,9 @@ async function boardRoomView({ closedLimit = 20 } = {}) {
             recommendation: r.recommendation ?? null,
           } : null;
         })()
-      : (() => { const r = amendmentById.get(String(item.subject_id)); return r ? { proposed: r.proposed, rationale_md: r.rationale_md, author_id: r.proposed_by == null ? null : String(r.proposed_by) } : null; })();
+      : decisionRules.isMatterSubject(item.subject_type)
+      ? decisionBoard.projectMatterSubject(matterById.get(String(item.subject_id)))
+      : (() => { const r = amendmentById.get(String(item.subject_id)); return r ? { proposed: r.proposed, rationale_md: r.rationale_md, ...(r.kind ? { kind: r.kind } : {}), author_id: r.proposed_by == null ? null : String(r.proposed_by) } : null; })();
     return {
       id: String(item.id),
       subject_type: item.subject_type,
@@ -1226,7 +1271,9 @@ async function constitutionView({ historyLimit = 50, type = null, headcount: ask
     closed_at: r.closed_at,
     outcome: r.outcome,
     decided_under: r.decided_under || null,
+    kind: r.kind || 'constitution',
   }));
+  const rulesTable = await decisionBoard.decisionRulesFor(live); // task 1004529; null if unreadable
   return {
     board: live,
     history,
@@ -1244,7 +1291,11 @@ async function constitutionView({ historyLimit = 50, type = null, headcount: ask
     // `historyLimit` in principle; a board with 50 amendments newer than its
     // last passed one is not a shape this system has, and the honest failure
     // there is a missed warning rather than a wrong one.
-    divergence: constitutionDivergence(live, history),
+    // Only board-block amendments say what the board block should be (a rules
+    // amendment changes the table, task 1004529).
+    divergence: constitutionDivergence(live, history.filter((h) => h.kind !== 'decision_rules')),
+    // Who decides what at each building, as today or set by a passed amendment.
+    decision_rules: decisionBoard.constitutionBlock(rulesTable),
     // The genesis charter + legislation stages' payload (task 1004427): every
     // form and variable by its real name with its plain explanation, and the
     // form the constitution in force reads as (or Custom). Pure — no query.
@@ -1400,6 +1451,14 @@ async function pendingVotesFor(builderId) {
 }
 
 module.exports = {
+  proposeDecisionRules,
+  openMatter,
+  decisionRulesView: (...a) => decisionBoard.decisionRulesView(...a),
+  decisionRulesWriteAllowed: decisionBoard.decisionRulesWriteAllowed,
+  applyPassedDecisionRules: decisionBoard.applyPassedDecisionRules,
+  validateMatterAction: decisionBoard.validateMatterAction,
+  checkActAlone: (...a) => decisionBoard.checkActAlone(...a),
+  authorRuleApplies,
   GENESIS_STAGES,
   PASS_RULE_WORDS,
   proposeCharter,

package/modules/government/db.js

@@ -528,7 +528,7 @@ async function getIdeaSubjects(ideaIds) {
 async function getAmendmentSubjects(amendmentIds) {
   if (!amendmentIds || !amendmentIds.length) return [];
   const { rows } = await pool.query(
-    `SELECT id, proposed, rationale_md, proposed_by FROM government_amendments WHERE id = ANY($1::bigint[])`,
+    `SELECT id, proposed, rationale_md, proposed_by, kind FROM government_amendments WHERE id = ANY($1::bigint[])`,
     [amendmentIds],
   );
   return rows;
@@ -554,7 +554,7 @@ async function countActiveBuilders() {
 async function listAmendmentHistory(limit = 50) {
   const { rows } = await pool.query(
     `SELECT i.id AS item_id, i.opened_at, i.closed_at, i.outcome, i.constitution AS decided_under,
-            a.id AS amendment_id, a.proposed, a.rationale_md, a.proposed_by,
+            a.id AS amendment_id, a.proposed, a.rationale_md, a.proposed_by, a.kind,
             b.github_login AS proposer_login, b.display_name AS proposer_name
        FROM government_board_items i
        JOIN government_amendments a ON a.id = i.subject_id
@@ -569,16 +569,86 @@ async function listAmendmentHistory(limit = 50) {
 
 // --- amendments (BV1.R14 of goal 1000069) ------------------------------------
 
-async function createAmendment({ proposed, rationaleMd = null, proposedBy }) {
+// `kind` (government_023, task 1004529): 'constitution' for a board-block
+// amendment (every row before that task), 'decision_rules' for a change to who
+// decides what at a building. Same table, same subject type, same pass path.
+async function createAmendment({ proposed, rationaleMd = null, proposedBy, kind = 'constitution' }) {
   const { rows } = await pool.query(
-    `INSERT INTO government_amendments (proposed, rationale_md, proposed_by)
-     VALUES ($1::jsonb, $2, $3)
+    `INSERT INTO government_amendments (proposed, rationale_md, proposed_by, kind)
+     VALUES ($1::jsonb, $2, $3, $4)
      RETURNING *`,
-    [JSON.stringify(proposed), rationaleMd, proposedBy],
+    [JSON.stringify(proposed), rationaleMd, proposedBy, kind],
   );
   return rows[0];
 }
 
+// --- who decides what (task 1004529, government_023) -------------------------
+
+// Every building's row. Nine rows at most; read per request, uncached (ADR 0016
+// — a passed amendment takes effect on the very next request).
+async function listDecisionRules() {
+  const { rows } = await pool.query(
+    `SELECT area, decided_by, rule, who, set_by_item_id, updated_at
+       FROM government_decision_rules`,
+  );
+  return rows;
+}
+
+// THE ONE WRITE, and it runs only INSIDE the transaction that closes a
+// decision-rules amendment as passed (board.closeItem's afterClose — `client` is
+// that transaction). Two guards besides the caller's: the statement writes
+// nothing unless the named item is a passed decision-rules amendment (the WHERE
+// EXISTS), and government_023's trigger refuses any write that is not — so a
+// change that skipped the board cannot land even through hand-written SQL.
+// Throws when a row did not land, which rolls the close back: the item stays
+// open and the decision is retried rather than recorded as passed-but-unapplied.
+async function applyDecisionRules(client, { itemId, rules }) {
+  let written = 0;
+  for (const r of rules) {
+    const { rowCount } = await client.query(
+      `INSERT INTO government_decision_rules (area, decided_by, rule, who, set_by_item_id, updated_at)
+       SELECT $1::text, $2::text, $3::text, $4::text, $5::bigint, now()
+        WHERE EXISTS (
+          SELECT 1 FROM government_board_items i
+            JOIN government_amendments a ON a.id = i.subject_id
+           WHERE i.id = $5::bigint AND i.subject_type = 'constitutional_amendment'
+             AND i.outcome = 'passed' AND a.kind = 'decision_rules')
+       ON CONFLICT (area) DO UPDATE
+          SET decided_by = EXCLUDED.decided_by, rule = EXCLUDED.rule, who = EXCLUDED.who,
+              set_by_item_id = EXCLUDED.set_by_item_id, updated_at = now()`,
+      [r.area, r.decided_by, r.rule, r.who, itemId],
+    );
+    if (rowCount !== 1) throw new Error(`decision rule for ${r.area} not written (item ${itemId} is not a passed decision-rules amendment)`);
+    written += 1;
+  }
+  return written;
+}
+
+// A matter put to a building's sitting. Immutable once filed, like an amendment.
+async function createMatter({ area, title, detailMd = null, action = null, proposedBy }) {
+  const { rows } = await pool.query(
+    `INSERT INTO government_matters (area, title, detail_md, action, proposed_by)
+     VALUES ($1, $2, $3, $4::jsonb, $5)
+     RETURNING *`,
+    [area, title, detailMd, action == null ? null : JSON.stringify(action), proposedBy],
+  );
+  return rows[0];
+}
+
+async function getMatter(id) {
+  const { rows } = await pool.query(`SELECT * FROM government_matters WHERE id = $1`, [id]);
+  return rows[0] || null;
+}
+
+async function getMatterSubjects(matterIds) {
+  if (!matterIds || !matterIds.length) return [];
+  const { rows } = await pool.query(
+    `SELECT id, area, title, detail_md, action, proposed_by FROM government_matters WHERE id = ANY($1::bigint[])`,
+    [matterIds],
+  );
+  return rows;
+}
+
 async function getAmendment(id) {
   const { rows } = await pool.query(
     `SELECT * FROM government_amendments WHERE id = $1`,
@@ -804,6 +874,11 @@ module.exports = {
   getLatestPassedItem,
   createAmendment,
   getAmendment,
+  listDecisionRules,
+  applyDecisionRules,
+  createMatter,
+  getMatter,
+  getMatterSubjects,
   listOpenBoardItems,
   listClosedBoardItems,
   getVotesForItems,