@bongos/core 1.21.8 → 1.21.10

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,
+};