@bongos/core 1.21.8 → 1.21.9

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

package/modules/government/decision-rules.js

@@ -0,0 +1,312 @@
+'use strict';
+
+// modules/government/decision-rules.js — WHO DECIDES WHAT: the per-project table
+// that says, for each building of the government, who decides its matters and by
+// which rule (task 1004529, goal 1000125 the Governor City). Decision of record:
+// docs/adr/0363-who-decides-what-is-a-table-changed-only-by-amendment.md.
+//
+// WHY. Before this, every building's matters were decided one way: whoever held
+// that building's fixed permission acted alone (the rank gate), and only the
+// charter had a board. The reference design (docs/design/mocks/governor-city/
+// Governments.dc.html, "Four governments") shows one project decided four ways —
+// one founder, a council, everyone votes, a board of trustees — and a project
+// that starts as one and amends itself into another. That needs the answer to
+// "who decides, and how" to be DATA a project can change, not code.
+//
+// THE THREE THINGS A ROW CAN SAY (the table is government_023):
+//   decided_by 'gate'      — AS TODAY. Whoever holds the building's fixed
+//                            permission acts alone, through its own page. No
+//                            rule of its own (the effective rule is `decide`).
+//                            Every building except the charter starts here.
+//   decided_by 'board'     — the CHARTER only: the constitution's own board,
+//                            under its own pass rule. The charter is changed by
+//                            amending the board block, never through this table.
+//   decided_by 'nobody'    — VACANT (rule 'vacant'): no one holds this building
+//                            yet. Its matters wait; none can be put to a sitting.
+//   decided_by <predicate> — a SITTING: matters here are put to the members the
+//                            predicate seats (the board's own grammar, rank:<key>,
+//                            rank:<key>+, rank:a,b — membership-predicate.js) and
+//                            decided by the row's rule.
+//
+// CHANGED ONLY BY A PASSED AMENDMENT. There is no settings route that writes the
+// table. A change is filed as an amendment of kind 'decision_rules'
+// (board.proposeDecisionRules), decided by the board in force like every other
+// amendment, and written INSIDE the transaction that closes the sitting as
+// passed (board.closeItem). The database refuses any other write (government_023's
+// trigger), so a hand-edited row is refused too.
+//
+// PURE: no db, no requires beyond the grammar and the catalog. The board and the
+// docket read the table through db.js and hand the rows here.
+
+const { parseMembershipPredicate, describeMembership } = require('./membership-predicate');
+const { RANK_ORDER } = require('./catalog');
+
+// The nine buildings, in street order (held equal to docket-vocab BUILDINGS by
+// test). `gate` is the fixed permission that decides the building's matters
+// today — the atom its own pages require, named so a reader can see what a
+// sitting replaces. `acts` lists the direct acts in THIS module that already
+// defer to the row (task 1004529 wired People's rank assignments); every other
+// building's own pages keep their gate until their owning module adopts
+// `mayActAlone` (the ADR's follow-up list).
+const AREAS = Object.freeze([
+  Object.freeze({ key: 'charter', name: 'Charter', gate: null,
+    today: 'the board, under the constitution in force', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'rules', name: 'Rules', gate: 'project.settings.manage',
+    today: 'whoever may change the project settings', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'disputes', name: 'Disputes', gate: 'security.report.adjudicate',
+    today: 'whoever may judge reports', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'people', name: 'People', gate: 'government.manage',
+    today: 'whoever may manage ranks',
+    acts: Object.freeze(['POST /government/assignments', 'DELETE /government/assignments/:builderId/:rankKey']) }),
+  Object.freeze({ key: 'planning', name: 'Planning', gate: 'goal.create',
+    today: 'whoever may create goals', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'automation', name: 'Automation', gate: 'autonomy.fence.manage',
+    today: 'whoever may switch unattended building on and off', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'review', name: 'Review', gate: 'criterion.satisfy',
+    today: 'whoever may mark work as meeting its checks', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'release', name: 'Release', gate: 'core.pin.move',
+    today: 'whoever may put a release live', acts: Object.freeze([]) }),
+  Object.freeze({ key: 'treasury', name: 'Treasury', gate: 'builder.budget.set',
+    today: 'whoever may set spending limits', acts: Object.freeze([]) }),
+]);
+const AREA_KEYS = Object.freeze(AREAS.map((a) => a.key));
+const areaByKey = (key) => AREAS.find((a) => a.key === key) || null;
+
+// The seven ways a building can decide (the design's decision glyphs, plus
+// vacant from the "Four governments" board). `sitting` rules put a matter to the
+// members a predicate seats; `decide` and `first` also let a seated member act
+// alone; `vacant` decides nothing.
+const DECISION_RULES = Object.freeze([
+  Object.freeze({ key: 'decide', words: 'decides alone', passRule: 'first_ratifier', actsAlone: true }),
+  Object.freeze({ key: 'first', words: 'first yes wins', passRule: 'first_ratifier', actsAlone: true }),
+  Object.freeze({ key: 'consent', words: 'passes unless someone objects', passRule: 'consent', actsAlone: false }),
+  Object.freeze({ key: 'majority', words: 'majority vote', passRule: 'majority', actsAlone: false }),
+  Object.freeze({ key: 'unanimous', words: 'everyone agrees', passRule: 'unanimous', actsAlone: false }),
+  Object.freeze({ key: 'signoff', words: 'signed off by someone who did not build it', passRule: 'first_ratifier', actsAlone: false }),
+  Object.freeze({ key: 'vacant', words: 'no one holds this yet', passRule: null, actsAlone: false }),
+]);
+const DECISION_RULE_KEYS = Object.freeze(DECISION_RULES.map((r) => r.key));
+const SITTING_RULE_KEYS = Object.freeze(DECISION_RULE_KEYS.filter((k) => k !== 'vacant'));
+const ruleByKey = (key) => DECISION_RULES.find((r) => r.key === key) || null;
+
+// The board's pass rules in the table's words (the charter row's effective rule).
+const PASS_RULE_TO_DECISION_RULE = Object.freeze({
+  first_ratifier: 'first', consent: 'consent', majority: 'majority', unanimous: 'unanimous',
+});
+
+// The board subject a building's matters sit as. The charter has none of its
+// own: its matters are constitutional amendments.
+const MATTER_SUBJECT_TYPES = Object.freeze(Object.fromEntries(
+  AREAS.filter((a) => a.key !== 'charter').map((a) => [a.key, `${a.key}_matter`]),
+));
+const areaForSubjectType = (subjectType) => {
+  const hit = Object.entries(MATTER_SUBJECT_TYPES).find(([, t]) => t === subjectType);
+  return hit ? hit[0] : null;
+};
+const isMatterSubject = (subjectType) => areaForSubjectType(subjectType) !== null;
+
+const WHO_MAX = 120;
+const DECIDED_BY_MAX = 200;
+
+// The as-today row for a building — what government_023 seeds, and what a
+// building reads as when its row is missing or unreadable as stored.
+function defaultRow(area) {
+  return Object.freeze({
+    area, decided_by: area === 'charter' ? 'board' : 'gate', rule: null, who: null, set_by_item_id: null,
+  });
+}
+
+// ── strict validation of a proposed change ──────────────────────────────────
+//
+// Like a constitution proposal (board.validateProposedConstitution), a proposal
+// is VALIDATED, never sanitized: the board must not ratify a row its proposer
+// did not write. A proposal lists the buildings it changes; each listed row is
+// replaced whole. Returns { ok, rules } in street order, or a named refusal.
+const PROPOSAL_FIELDS = Object.freeze(['area', 'decided_by', 'rule', 'who']);
+const PREDICATE_EXPECTED = "'gate' (as today), 'nobody' (vacant), or rank:<key> / rank:<key>+ / a comma list such as rank:council,archon";
+
+function validateDecisionRulesProposal(raw) {
+  if (!Array.isArray(raw) || raw.length === 0) return { ok: false, reason: 'proposal_not_a_list', expected: 'a non-empty list of { area, decided_by, rule, who }' };
+  if (raw.length > AREAS.length) return { ok: false, reason: 'too_many_rows' };
+  const seen = new Set();
+  const out = [];
+  for (const row of raw) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return { ok: false, reason: 'row_not_an_object' };
+    for (const k of Object.keys(row)) {
+      if (!PROPOSAL_FIELDS.includes(k)) return { ok: false, reason: 'unknown_field', field: k };
+    }
+    const area = row.area;
+    if (!AREA_KEYS.includes(area)) return { ok: false, reason: 'unknown_area', expected: AREA_KEYS };
+    if (seen.has(area)) return { ok: false, reason: 'duplicate_area', area };
+    seen.add(area);
+    if (area === 'charter') {
+      return {
+        ok: false, reason: 'charter_is_the_board', area,
+        expected: 'the charter is decided by the constitution\'s own board — change its members or rule with a constitution amendment (POST /government/board/items or /government/board/charter)',
+      };
+    }
+    const decidedBy = row.decided_by;
+    if (typeof decidedBy !== 'string' || decidedBy.length === 0 || decidedBy.length > DECIDED_BY_MAX) {
+      return { ok: false, reason: 'bad_decided_by', area, expected: PREDICATE_EXPECTED };
+    }
+    const rule = row.rule === undefined ? null : row.rule;
+    if (decidedBy === 'gate') {
+      if (rule !== null) return { ok: false, reason: 'gate_takes_no_rule', area, expected: 'leave rule out: as today, whoever holds the building\'s permission decides alone' };
+    } else if (decidedBy === 'nobody') {
+      if (rule !== 'vacant') return { ok: false, reason: 'nobody_is_vacant', area, expected: "rule 'vacant'" };
+    } else if (decidedBy === 'board') {
+      return { ok: false, reason: 'only_the_charter_is_the_board', area };
+    } else {
+      if (!parseMembershipPredicate(decidedBy)) return { ok: false, reason: 'bad_decided_by', area, expected: PREDICATE_EXPECTED };
+      if (!SITTING_RULE_KEYS.includes(rule)) return { ok: false, reason: 'bad_rule', area, expected: SITTING_RULE_KEYS };
+    }
+    let who = row.who === undefined ? null : row.who;
+    if (who !== null) {
+      if (typeof who !== 'string' || who.trim().length === 0 || who.length > WHO_MAX) {
+        return { ok: false, reason: 'bad_who', area, expected: `null, or the seat in words (1..${WHO_MAX} characters)` };
+      }
+      who = who.trim();
+    }
+    out.push(Object.freeze({ area, decided_by: decidedBy, rule, who }));
+  }
+  out.sort((a, b) => AREA_KEYS.indexOf(a.area) - AREA_KEYS.indexOf(b.area));
+  return { ok: true, rules: Object.freeze(out) };
+}
+
+// The CUSTOM rank keys a proposal names (a standard rank always exists), so the
+// caller can refuse a council that is not a rank yet — it would seat nobody.
+function customRankKeysIn(rules) {
+  const keys = new Set();
+  for (const r of rules || []) {
+    const parsed = parseMembershipPredicate(r.decided_by);
+    if (!parsed) continue;
+    for (const k of parsed.rankKeys) if (!RANK_ORDER.includes(k)) keys.add(k);
+  }
+  return [...keys];
+}
+
+// Would applying these rows change anything? A proposal that changes nothing is
+// refused before it costs a sitting.
+function changesAnything(rules, liveRows) {
+  const live = new Map((liveRows || []).map((r) => [r.area, r]));
+  return (rules || []).some((r) => {
+    const cur = live.get(r.area) || defaultRow(r.area);
+    return cur.decided_by !== r.decided_by || (cur.rule || null) !== (r.rule || null) || (cur.who || null) !== (r.who || null);
+  });
+}
+
+// ── reading a row ───────────────────────────────────────────────────────────
+
+// A stored row as the public, resolved shape: effective rule, the seat in words,
+// whether matters here go to a sitting, whether a seated member may act alone.
+// `board` is the live constitution block (the charter's row reads its rule).
+// A row that is malformed as stored reads as the as-today default — the same
+// fail-closed direction as the constitution's sanitizer: never wider than today.
+function resolveRow(stored, { board = {} } = {}) {
+  const area = stored && AREA_KEYS.includes(stored.area) ? stored.area : null;
+  if (!area) return null;
+  const def = areaByKey(area);
+  let row = stored;
+  const shapeOk = (area === 'charter' && row.decided_by === 'board' && row.rule == null)
+    || (area !== 'charter' && row.decided_by === 'gate' && row.rule == null)
+    || (area !== 'charter' && row.decided_by === 'nobody' && row.rule === 'vacant')
+    || (area !== 'charter' && parseMembershipPredicate(row.decided_by) && SITTING_RULE_KEYS.includes(row.rule));
+  if (!shapeOk) row = defaultRow(area);
+
+  const asToday = row.decided_by === 'gate' || row.decided_by === 'board';
+  let rule;
+  let who;
+  if (row.decided_by === 'board') {
+    rule = PASS_RULE_TO_DECISION_RULE[board.pass_rule] || null;
+    const members = describeMembership(board.membership);
+    who = row.who || (members ? `the board (${members})` : 'the board');
+  } else if (row.decided_by === 'gate') {
+    rule = 'decide';
+    who = row.who || def.today;
+  } else if (row.decided_by === 'nobody') {
+    rule = 'vacant';
+    who = row.who || 'no one yet';
+  } else {
+    rule = row.rule;
+    who = row.who || describeMembership(row.decided_by);
+  }
+  const r = ruleByKey(rule);
+  return Object.freeze({
+    area,
+    name: def.name,
+    decided_by: row.decided_by,
+    rule,
+    rule_words: r ? r.words : null,
+    who,
+    as_today: asToday,
+    // Matters here are put to a sitting of the seated members (never for the
+    // charter — its matters are amendments, sat under the board in force).
+    sitting: area !== 'charter' && !asToday && row.decided_by !== 'nobody',
+    gate: def.gate,
+    today: def.today,
+    acts: def.acts,
+    set_by_item_id: row.set_by_item_id == null ? null : String(row.set_by_item_id),
+    updated_at: row.updated_at || null,
+  });
+}
+
+// Every building, in street order, from whatever rows were read (a missing row
+// reads as its default).
+function resolveAll(rows, { board = {} } = {}) {
+  const byArea = new Map((rows || []).map((r) => [r.area, r]));
+  return Object.freeze(AREAS.map((a) => resolveRow(byArea.get(a.key) || defaultRow(a.key), { board })));
+}
+
+// The constitution a matter's sitting is snapshotted under. Built from the row
+// (who and how) and the live board (early close). A clock is set only under a
+// rule whose expiry means RETURN — under first_ratifier or consent a deadline
+// would pass a matter nobody read (ADR 0191 §4), so those sit with no clock.
+function sittingConstitution(resolved, { board = {}, clockSafe = (passRule) => passRule === 'majority' || passRule === 'unanimous' } = {}) {
+  const r = ruleByKey(resolved && resolved.rule);
+  if (!resolved || !resolved.sitting || !r || !r.passRule) return null;
+  const window = clockSafe(r.passRule) && Number.isInteger(board.window_minutes) ? board.window_minutes : null;
+  return Object.freeze({
+    membership: resolved.decided_by,
+    pass_rule: r.passRule,
+    window_minutes: window,
+    close_early_on_full_turnout: board.close_early_on_full_turnout !== false,
+    // The table's own words ride the snapshot, so the docket and the board read
+    // the rule the matter was decided under, and `signoff` holds the proposer
+    // to the author rule.
+    rule: resolved.rule,
+    area: resolved.area,
+  });
+}
+
+// May this builder act ALONE at this building right now? `seated` is whether
+// the row's predicate seats them (resolved by the caller, server-side,
+// uncached). As today → yes (the route's own permission gate still applies).
+// decide / first → only a seated member. Any other rule, or vacant → nobody:
+// the matter goes to a sitting.
+function mayActAlone(resolved, { seated = false } = {}) {
+  if (!resolved) return false;
+  if (resolved.as_today) return true;
+  const r = ruleByKey(resolved.rule);
+  return !!(r && r.actsAlone && resolved.sitting && seated);
+}
+
+module.exports = {
+  AREAS,
+  AREA_KEYS,
+  areaByKey,
+  DECISION_RULES,
+  DECISION_RULE_KEYS,
+  SITTING_RULE_KEYS,
+  PASS_RULE_TO_DECISION_RULE,
+  MATTER_SUBJECT_TYPES,
+  areaForSubjectType,
+  isMatterSubject,
+  defaultRow,
+  validateDecisionRulesProposal,
+  customRankKeysIn,
+  changesAnything,
+  resolveRow,
+  resolveAll,
+  sittingConstitution,
+  mayActAlone,
+};