@bongos/core 1.21.7 → 1.21.9

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,

package/modules/government/decision-board.js

@@ -0,0 +1,300 @@
+'use strict';
+
+// modules/government/decision-board.js — the board's side of WHO DECIDES WHAT
+// (task 1004529, goal 1000125; ADR 0363). decision-rules.js is the pure half
+// (the buildings, the rules, validation, how a row reads); this file is where
+// the table meets the board: proposing a change as an amendment, writing a
+// passed one, putting a building's matter to its sitting, acting on a passed
+// matter, and the check a building's own route runs before one builder acts
+// alone. Split out of board.js so the board's close/vote file stays readable;
+// board.js calls in here and never the other way round (no require cycle).
+//
+// The window-open nudge (board.item.opened) is emitted by board.js's wrappers
+// around proposeDecisionRules and openMatter, beside every other open.
+
+const api = require('../../src/module-api');
+const db = require('./db');
+const { loadGovernmentConfig, isClockSafe } = require('./config');
+const { isBoardMember } = require('./board-membership');
+const decisionRules = require('./decision-rules');
+
+const log = api.logger('government');
+
+// ── who decides what: the amendment-only write (task 1004529) ───────────────
+//
+// THE GUARD. The decision-rules table is changed ONLY here, and only when the
+// row that just closed is a PASSED constitutional amendment whose amendment is
+// of kind 'decision_rules' and is the item's own subject. db.applyDecisionRules
+// carries the same condition in its SQL, and government_023's trigger refuses
+// any write that is not — three layers, so no route, script or hand-written
+// UPDATE can change who decides without the board having decided it.
+// Runs INSIDE the closing transaction (`client`); a throw rolls the close back.
+function decisionRulesWriteAllowed(closedRow, amendment) {
+  return !!closedRow && !!amendment
+    && closedRow.subject_type === 'constitutional_amendment'
+    && closedRow.outcome === 'passed'
+    && amendment.kind === 'decision_rules'
+    && String(amendment.id) === String(closedRow.subject_id);
+}
+
+async function applyPassedDecisionRules(client, closedRow, amendment) {
+  if (!decisionRulesWriteAllowed(closedRow, amendment)) {
+    throw new Error(`[government] decision rules may only be written by a passed decision-rules amendment (item ${closedRow && closedRow.id})`);
+  }
+  // Re-validated as a belt: the row was validated strictly at propose time and
+  // is immutable since, so a refusal here means the stored row was altered.
+  const v = decisionRules.validateDecisionRulesProposal((amendment.proposed || {}).decision_rules);
+  if (!v.ok) throw new Error(`[government] passed decision-rules amendment ${amendment.id} no longer validates (${v.reason}) — NOT applied`);
+  await db.applyDecisionRules(client, { itemId: closedRow.id, rules: v.rules });
+  return v.rules;
+}
+
+// A passed matter: act where the building can act by itself, and build the
+// announcement. Never throws — the decision already stands.
+async function actOnPassedMatter(closed) {
+  const area = decisionRules.areaForSubjectType(closed.subject_type);
+  let matter = null;
+  let result = { area, matter_id: String(closed.subject_id), action: null, done: false };
+  try {
+    matter = await db.getMatter(closed.subject_id);
+    const action = matter && matter.action;
+    if (area === 'people' && action && (action.type === 'assign_rank' || action.type === 'unassign_rank')) {
+      // The same walls as the direct route: a custom rank that still exists,
+      // never a seeded one (a seeded rank follows the builder's rank — R95b).
+      const rank = await db.getRankByKey(action.rank_key);
+      if (!rank || rank.is_system) {
+        result = { ...result, action: action.type, done: false, reason: rank ? 'seeded_rank' : 'rank_gone' };
+      } else if (action.type === 'assign_rank') {
+        await db.assignRank({ builderId: action.builder_id, rankKey: action.rank_key, assignedBy: matter.proposed_by });
+        result = { ...result, action: action.type, done: true, builder_id: String(action.builder_id), rank_key: action.rank_key };
+      } else {
+        await db.unassignRank({ builderId: action.builder_id, rankKey: action.rank_key });
+        result = { ...result, action: action.type, done: true, builder_id: String(action.builder_id), rank_key: action.rank_key };
+      }
+    }
+  } catch (err) {
+    log.error(`[government] matter ${closed.subject_id} passed at ${area} but its act did NOT run (re-drivable from the passed item): ${err && err.message}`);
+    result = { ...result, done: false, reason: 'act_failed' };
+  }
+  return {
+    result,
+    payload: {
+      item_id: String(closed.id),
+      area,
+      matter_id: String(closed.subject_id),
+      title: matter ? matter.title : null,
+      action: matter && matter.action ? matter.action : null,
+      acted: result.done,
+      passed_at: closed.closed_at || null,
+    },
+  };
+}
+
+// ── who decides what: proposing a change (task 1004529) ─────────────────────
+//
+// A change to who decides what at a building is an AMENDMENT — of kind
+// 'decision_rules' — filed and decided exactly like a constitution amendment:
+// validated strictly, sat under the constitution IN FORCE, ratified by the board
+// (the charter). Its `proposed` holds { decision_rules: [rows] }; the close
+// writes them (applyPassedDecisionRules). There is no other write path.
+//
+// Returns { ok, amendment, item, rules } or a named refusal:
+//   validateDecisionRulesProposal's reasons | 'unknown_rank' | 'no_change'
+//   | 'missing_proposer'.
+async function proposeDecisionRules({ rules, rationaleMd = null, proposedBy } = {}) {
+  const v = decisionRules.validateDecisionRulesProposal(rules);
+  if (!v.ok) return v;
+  if (proposedBy == null || proposedBy === '') return { ok: false, reason: 'missing_proposer' };
+  // A custom rank that does not exist would seat nobody: fail-closed, but a
+  // building nobody can ever decide. Refused before filing, like a council.
+  for (const key of decisionRules.customRankKeysIn(v.rules)) {
+    if (!(await db.getRankByKey(key))) return { ok: false, reason: 'unknown_rank', rank_key: key };
+  }
+  const live = await db.listDecisionRules();
+  if (!decisionRules.changesAnything(v.rules, live)) return { ok: false, reason: 'no_change' };
+
+  const { board } = loadGovernmentConfig();
+  const words = v.rules.map((r) => {
+    const resolved = decisionRules.resolveRow(r, { board });
+    return `${resolved.name}: ${resolved.who}, ${resolved.rule_words}`;
+  }).join('; ');
+  const amendment = await db.createAmendment({
+    proposed: { decision_rules: v.rules },
+    rationaleMd: rationaleMd || `Who decides: ${words}.`,
+    proposedBy,
+    kind: 'decision_rules',
+  });
+  const item = await db.openBoardItem({
+    subjectType: 'constitutional_amendment',
+    subjectId: amendment.id,
+    openedBy: proposedBy,
+    constitution: board,
+    windowMinutes: board.window_minutes,
+  });
+  return { ok: true, amendment, item, rules: v.rules };
+}
+
+// The live table, resolved: every building in street order with who decides it
+// and how. Read per request, uncached.
+async function decisionRulesView() {
+  const { board } = loadGovernmentConfig();
+  const rows = await db.listDecisionRules();
+  return decisionRules.resolveAll(rows, { board });
+}
+
+// ── a building's matter: the board's new subjects (task 1004529) ────────────
+//
+// Put a matter to the building's sitting. Allowed ONLY where the building's row
+// names a sitting — i.e. a passed amendment moved it off its fixed gate. Under
+// the default rows every building refuses ('decided_by_gate'), so nothing about
+// today's behaviour changes until a project amends itself.
+//
+// The sitting is snapshotted from the ROW (who and how), not the board: that is
+// the whole point — People decided by a council's consent sits as exactly that.
+const MATTER_TITLE_MAX = 200;
+const MATTER_DETAIL_MAX = 5000;
+const MATTER_ACTION_TYPES = Object.freeze(['assign_rank', 'unassign_rank']);
+
+function validateMatterAction(area, action) {
+  if (action == null) return { ok: true, action: null };
+  if (area !== 'people') return { ok: false, reason: 'action_not_supported_here', expected: 'only People can act by itself today (assign_rank / unassign_rank)' };
+  if (typeof action !== 'object' || Array.isArray(action)) return { ok: false, reason: 'bad_action' };
+  for (const k of Object.keys(action)) {
+    if (!['type', 'builder_id', 'rank_key'].includes(k)) return { ok: false, reason: 'unknown_field', field: `action.${k}` };
+  }
+  if (!MATTER_ACTION_TYPES.includes(action.type)) return { ok: false, reason: 'bad_action', expected: MATTER_ACTION_TYPES };
+  const builderId = Number(action.builder_id);
+  if (!Number.isInteger(builderId) || builderId <= 0) return { ok: false, reason: 'bad_action', field: 'action.builder_id' };
+  if (typeof action.rank_key !== 'string' || !/^[a-z][a-z0-9-]*$/.test(action.rank_key) || action.rank_key.length > 64) {
+    return { ok: false, reason: 'bad_action', field: 'action.rank_key' };
+  }
+  return { ok: true, action: { type: action.type, builder_id: builderId, rank_key: action.rank_key } };
+}
+
+async function openMatter({ area, title, detailMd = null, action = null, proposedBy } = {}) {
+  if (!decisionRules.AREA_KEYS.includes(area)) return { ok: false, reason: 'unknown_area', expected: decisionRules.AREA_KEYS };
+  if (area === 'charter') return { ok: false, reason: 'charter_matters_are_amendments', expected: 'POST /government/board/items (or /charter, /decision-rules)' };
+  if (typeof title !== 'string' || !title.trim() || title.length > MATTER_TITLE_MAX) return { ok: false, reason: 'bad_title' };
+  if (detailMd != null && (typeof detailMd !== 'string' || detailMd.length > MATTER_DETAIL_MAX)) return { ok: false, reason: 'bad_detail' };
+  if (proposedBy == null || proposedBy === '') return { ok: false, reason: 'missing_proposer' };
+  const a = validateMatterAction(area, action);
+  if (!a.ok) return a;
+
+  const { board } = loadGovernmentConfig();
+  const rows = await db.listDecisionRules();
+  const resolved = decisionRules.resolveAll(rows, { board }).find((r) => r.area === area);
+  if (resolved.as_today) {
+    return {
+      ok: false, reason: 'decided_by_gate', area, gate: resolved.gate,
+      what_this_means: `${resolved.name} is decided as it always has been: ${resolved.today} decides alone, on its own page. A sitting here needs an amendment first.`,
+    };
+  }
+  if (!resolved.sitting) return { ok: false, reason: 'no_one_holds_this', area, what_this_means: `No one holds ${resolved.name} yet, so nothing there can be decided.` };
+  if (a.action) {
+    const rank = await db.getRankByKey(a.action.rank_key);
+    if (!rank) return { ok: false, reason: 'unknown_rank', rank_key: a.action.rank_key };
+    if (rank.is_system) return { ok: false, reason: 'seeded_rank', rank_key: a.action.rank_key, expected: 'a custom rank — a seeded rank follows the builder\'s rank' };
+  }
+  const constitution = decisionRules.sittingConstitution(resolved, { board, clockSafe: isClockSafe });
+  if (!constitution) return { ok: false, reason: 'no_one_holds_this', area };
+
+  const matter = await db.createMatter({ area, title: title.trim(), detailMd, action: a.action, proposedBy });
+  const item = await db.openBoardItem({
+    subjectType: decisionRules.MATTER_SUBJECT_TYPES[area],
+    subjectId: matter.id,
+    openedBy: proposedBy,
+    constitution,
+    windowMinutes: constitution.window_minutes,
+  });
+  return { ok: true, matter, item, decided: resolved };
+}
+
+// May this builder act ALONE at this building — the check a building's own
+// direct route runs before acting (People's rank assignments today). Resolved
+// per request against the live row and the builder's live ranks, uncached.
+// Returns { ok: true } or { ok: false, reason: 'decided_by_sitting', … }.
+async function checkActAlone(area, builderId) {
+  const { board } = loadGovernmentConfig();
+  const rows = await db.listDecisionRules();
+  const resolved = decisionRules.resolveAll(rows, { board }).find((r) => r.area === area);
+  if (!resolved) return { ok: false, reason: 'unknown_area' };
+  if (resolved.as_today) return { ok: true, decided: resolved };
+  const seated = resolved.sitting
+    ? await isBoardMember(builderId, { membership: resolved.decided_by }).catch(() => false)
+    : false;
+  if (decisionRules.mayActAlone(resolved, { seated })) return { ok: true, decided: resolved };
+  return {
+    ok: false,
+    reason: 'decided_by_sitting',
+    area,
+    rule: resolved.rule,
+    who: resolved.who,
+    what_this_means: resolved.sitting
+      ? `${resolved.name} is decided by ${resolved.who} (${resolved.rule_words}). Put it to them as a matter instead.`
+      : `No one holds ${resolved.name} yet, so nothing there can be decided.`,
+    open_with: resolved.sitting ? 'POST /government/board/matters' : null,
+  };
+}
+
+// board.matter.passed: after commit, for the module that owns the building. A
+// nudge — nothing that decides or pays may subscribe; the passed row is the fact.
+async function announcePassedMatter(acted) {
+  try {
+    if (api.emitAsync) await api.emitAsync('board.matter.passed', acted.payload);
+  } catch (_) { /* emitAsync isolates listener errors */ }
+}
+
+// ── the reads board.js shows ────────────────────────────────────────────────
+
+// The Board Room's matter subjects, keyed by id. No query when no matter is on
+// the board, so a project that never amended itself reads exactly what it did.
+async function matterSubjectsById(items) {
+  const ids = [...new Set((items || []).filter((i) => decisionRules.isMatterSubject(i.subject_type)).map((i) => i.subject_id))];
+  const rows = ids.length ? await db.getMatterSubjects(ids) : [];
+  return new Map(rows.map((r) => [String(r.id), r]));
+}
+
+// One matter as the room shows it; null when its row is gone (said honestly).
+function projectMatterSubject(r) {
+  if (!r) return null;
+  return {
+    area: r.area, title: r.title, detail_md: r.detail_md || null, action: r.action || null,
+    author_id: r.proposed_by == null ? null : String(r.proposed_by),
+  };
+}
+
+// The table resolved against the live board block, or null when unreadable —
+// the rest of the constitution view still answers.
+async function decisionRulesFor(board) {
+  try {
+    return decisionRules.resolveAll(await db.listDecisionRules(), { board });
+  } catch (_) {
+    return null;
+  }
+}
+
+// GET /government/constitution's `decision_rules` block.
+function constitutionBlock(resolved) {
+  if (resolved === null || resolved === undefined) return null;
+  return {
+    areas: resolved,
+    rules: decisionRules.DECISION_RULES.map((r) => ({ key: r.key, words: r.words })),
+    changed_by: 'a passed amendment only — POST /government/board/decision-rules files one',
+  };
+}
+
+module.exports = {
+  announcePassedMatter,
+  matterSubjectsById,
+  projectMatterSubject,
+  decisionRulesFor,
+  constitutionBlock,
+  decisionRulesWriteAllowed,
+  applyPassedDecisionRules,
+  actOnPassedMatter,
+  proposeDecisionRules,
+  decisionRulesView,
+  validateMatterAction,
+  openMatter,
+  checkActAlone,
+};