@bongos/core 1.21.19 → 1.21.21

package/modules/autonomy/governor-docket.js

@@ -21,6 +21,7 @@
 const api = require('../../src/module-api');
 const db = require('./db');
 const autonomyGate = require('../../scripts/gds/autonomy-gate');
+const runnerHealth = require('./runner-health');
 
 const POINT = 'governor.docket';
 
@@ -68,15 +69,123 @@ function moneyReading({ ceilingUsd, spentUsd }) {
   };
 }
 
+// ── floors and the record (task 1004527) ─────────────────────────────────────
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+function dayWord(at) { const d = new Date(at); return Number.isNaN(d.getTime()) ? '' : `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}`; }
+const usd = (n) => `$${Number(n).toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
+
+// Automation · Allowed goals. A line names its goal as `goal <id>`; the hall
+// letters it with the goal's title from its own goal list (this module cannot
+// read goals, ADR 0083), and the priority goal says so.
+function allowedGoalsFloor(project) {
+  const goals = Array.isArray(project && project.goals) ? project.goals : [];
+  const lines = goals.slice(0, 4).map((g) => [`goal ${g.goal_id}`, Number(project.priority_goal_id) === Number(g.goal_id) ? 'first in line' : g.added_at ? `since ${dayWord(g.added_at)}` : '']);
+  if (goals.length > 4) lines.push([`and ${goals.length - 4} more`, '']);
+  return { count: String(goals.length), line: goals.length ? `${goals.length} ${goals.length === 1 ? 'goal' : 'goals'} it may build` : 'no goal allowed', lines: lines.length ? lines : [['It may not build any goal yet.', '']], hot: false };
+}
+
+// Automation · Running now: runners checked in alive and working on a task.
+function runningFloor(scopes, nowMs, describe) {
+  const working = [];
+  for (const b of scopes || []) {
+    for (const r of b.runners || []) {
+      const h = describe(r, { nowMs });
+      if (h && h.ok && h.state !== 'never_seen' && r.working_task_id) working.push({ who: b.display_name || b.github_login || `builder ${b.builder_id}`, task: r.working_task_id });
+    }
+  }
+  return {
+    count: String(working.length),
+    line: working.length ? `${working.length} ${working.length === 1 ? 'build' : 'builds'} in progress` : 'nothing building now',
+    lines: working.slice(0, 4).map((w) => [`task ${w.task}`, w.who]),
+    hot: false,
+  };
+}
+
+// Automation · Spending limit: the month's unattended ceiling and what is used.
+function spendingLimitFloor({ ceilingUsd, spentUsd }) {
+  const ceiling = Number(ceilingUsd) || 0;
+  const spent = Math.max(0, Number(spentUsd) || 0);
+  return {
+    count: usd(ceiling),
+    line: `${usd(ceiling)} a month · ${usd(spent)} used`,
+    lines: [['It stops for the month when the limit is reached.', 'rule'], [`${usd(Math.max(0, ceiling - spent))} left this month.`, ''], ['A limit for each day is coming; today the limit is for the month.', 'coming']],
+    hot: ceiling > 0 && (ceiling - spent) / ceiling < 0.2,
+  };
+}
+
+// Automation · Reports: what the unattended routines decided, newest first, in
+// words (a routine key and a go/no-go are the gate's vocabulary, not a reader's).
+const DECISION_WORDS = Object.freeze({ go: 'went ahead', 'no-go': 'held back' });
+function routineWord(routine) {
+  const r = String(routine || '');
+  if (/builder/i.test(r)) return 'The builder';
+  if (/idea|triage/i.test(r)) return 'Idea sorting';
+  if (/simplify/i.test(r)) return 'The tidy-up pass';
+  if (/code-?review/i.test(r)) return 'The code review';
+  return r ? `The ${r} routine` : 'A routine';
+}
+function reportsFloor(runs, now) {
+  const week = (runs || []).filter((r) => r.created_at && now - Date.parse(r.created_at) <= 7 * 86400000);
+  const said = (r) => `${routineWord(r.routine)} ${DECISION_WORDS[r.decision] || `decided ${r.decision}`}${r.reason ? `: ${r.reason}` : ''}.`;
+  return {
+    count: String(week.length),
+    line: week.length ? `${week.length} ${week.length === 1 ? 'report' : 'reports'} this week` : 'no report this week',
+    lines: (runs || []).slice(0, 4).map((r) => [said(r), dayWord(r.created_at)]),
+    hot: false,
+  };
+}
+
+// The record: the switch's last change (the only one the fence row keeps).
+function fenceHistory(project) {
+  if (!project || !project.updated_at) return [];
+  return [{ id: 'switch', title: project.enabled ? 'Unattended building switched on' : `Unattended building switched off${project.paused_reason ? `: ${project.paused_reason}` : ''}`, at: project.updated_at, outcome: 'the switch' }];
+}
+
+// One read per docket request: the collector hands every read a per-request
+// `once(key, fn)` (docket.js buildDocket), so two floors that need the same rows
+// share one query. Without it (a direct call) the read simply runs.
+const shared = (once, key, fn) => (typeof once === 'function' ? once(key, fn) : fn());
+const spendFor = (reward, once) => shared(once, 'autonomy.spendMtd', () => reward.autonomousApiSpendMtd());
+const fenceFor = (once) => shared(once, 'autonomy.fence', () => db.readFence());
+
+function contributeAutonomyFloors() {
+  api.contribute(POINT, {
+    floor: 'automation.allowed_goals', gate: { anyBuilder: true },
+    read: async (_ctx, { once } = {}) => { const p = await fenceFor(once); if (!p) throw new Error('fence_uninitialised'); return allowedGoalsFloor(p); },
+  });
+  // GET /autonomy/runners/all is the owner's read of every runner.
+  api.contribute(POINT, {
+    floor: 'automation.running', gate: { permission: 'autonomy.fence.manage' },
+    read: async (_ctx, { now } = {}) => runningFloor(await db.readAllRunnerScopes(), now || Date.now(), runnerHealth.describeRunner),
+  });
+  api.contribute(POINT, {
+    floor: 'automation.spending_limit', gate: { permission: 'autonomy.precheck' },
+    read: async (_ctx, { once } = {}) => {
+      const reward = api.resolveOptional('reward');
+      if (!reward || typeof reward.autonomousApiSpendMtd !== 'function') throw new Error('economy_off');
+      return spendingLimitFloor({ ceilingUsd: autonomyGate.ceilingUsd(), spentUsd: await spendFor(reward, once) });
+    },
+  });
+  api.contribute(POINT, {
+    floor: 'automation.reports', gate: { permission: 'autonomy.precheck' },
+    read: async (_ctx, { now } = {}) => reportsFloor(await db.readAutonomyRuns({ limit: 50 }), now || Date.now()),
+  });
+  api.contribute(POINT, {
+    history: 'switch', building: 'automation', gate: { anyBuilder: true },
+    read: async (_ctx, { once } = {}) => fenceHistory(await fenceFor(once)),
+  });
+}
+
 function contributeAutonomyToDocket() {
+  contributeAutonomyFloors();
   // GET /autonomy/fence is any builder's read; the read itself fails on a missing
   // fence row rather than fabricating "off" (that route's rule).
   api.contribute(POINT, {
     source: 'autobongos_fence',
     building: 'automation',
     gate: { anyBuilder: true },
-    read: async (ctx) => {
-      const project = await db.readFence();
+    read: async (ctx, { once } = {}) => {
+      const project = await fenceFor(once);
       if (!project) throw new Error('fence_uninitialised');
       return fenceDocketMatters(project, ctx.has('autonomy.fence.manage'));
     },
@@ -86,10 +195,10 @@ function contributeAutonomyToDocket() {
   api.contribute(POINT, {
     reading: 'money',
     gate: { permission: 'autonomy.precheck' },
-    read: async () => {
+    read: async (_ctx, { once } = {}) => {
       const reward = api.resolveOptional('reward');
       if (!reward || typeof reward.autonomousApiSpendMtd !== 'function') throw new Error('economy_off');
-      return moneyReading({ ceilingUsd: autonomyGate.ceilingUsd(), spentUsd: await reward.autonomousApiSpendMtd() });
+      return moneyReading({ ceilingUsd: autonomyGate.ceilingUsd(), spentUsd: await spendFor(reward, once) });
     },
   });
 }
@@ -98,4 +207,9 @@ module.exports = {
   contributeAutonomyToDocket,
   fenceDocketMatters,
   moneyReading,
+  allowedGoalsFloor,
+  runningFloor,
+  spendingLimitFloor,
+  reportsFloor,
+  fenceHistory,
 };

package/modules/economy/cost.js

@@ -88,6 +88,41 @@ async function autonomousApiSpendMtd() {
   return Number(rows[0]?.usd) || 0;
 }
 
+// The Treasury's three spending lines, month by month (task 1004527, the
+// Governor City): rewards paid to builders (credit_log, 1 credit = $1), what the
+// grader cost (cost_log source 'grader') and hosting (categories infra, compute,
+// domain). The same ledgers GET /public/cost-summary already publishes, cut the
+// one way the Treasury building reads them. Newest month first, bounded.
+const HOSTING_CATEGORIES = Object.freeze(['infra', 'compute', 'domain']);
+async function treasuryMonths({ months = 6 } = {}) {
+  const n = Math.max(1, Math.min(24, Number(months) || 6));
+  const [spend, rewards] = await Promise.all([
+    pool.query(
+      `SELECT to_char(recorded_at, 'YYYY-MM') AS month,
+              COALESCE(SUM(amount_usd) FILTER (WHERE source = 'grader'), 0) AS grading_usd,
+              COALESCE(SUM(amount_usd) FILTER (WHERE category = ANY($2::text[])), 0) AS hosting_usd
+         FROM cost_log
+        WHERE recorded_at >= date_trunc('month', now()) - (($1::int - 1) * interval '1 month')
+        GROUP BY month`,
+      [n, HOSTING_CATEGORIES]
+    ),
+    pool.query(
+      `SELECT to_char(recorded_at, 'YYYY-MM') AS month,
+              COALESCE(SUM(delta), 0) AS credits, COUNT(DISTINCT builder_id)::int AS builders
+         FROM credit_log
+        WHERE delta > 0
+          AND recorded_at >= date_trunc('month', now()) - (($1::int - 1) * interval '1 month')
+        GROUP BY month`,
+      [n]
+    ),
+  ]);
+  const by = new Map();
+  const row = (m) => { if (!by.has(m)) by.set(m, { month: m, grading_usd: 0, hosting_usd: 0, rewards_credits: 0, rewarded_builders: 0 }); return by.get(m); };
+  for (const r of spend.rows) Object.assign(row(String(r.month)), { grading_usd: Number(r.grading_usd) || 0, hosting_usd: Number(r.hosting_usd) || 0 });
+  for (const r of rewards.rows) Object.assign(row(String(r.month)), { rewards_credits: Number(r.credits) || 0, rewarded_builders: Number(r.builders) || 0 });
+  return [...by.values()].sort((a, b) => (a.month < b.month ? 1 : -1));
+}
+
 // V3.R84 (#302): Archon sets (or clears) a builder's monthly budget override.
 // usd === null clears the override (the builder falls back to the project
 // default). Returns the updated row's id + budget, or null if no such builder.
@@ -527,6 +562,7 @@ async function costCalibrationSummary() {
 module.exports = {
   getBuilderCostStatus,
   autonomousApiSpendMtd,
+  treasuryMonths,
   setBuilderMonthlyBudget,
   logCost,
   reconcileSessionCosts,

package/modules/economy/governor-docket.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// modules/economy/governor-docket.js — the Treasury's floors and record for the
+// governor's docket (task 1004527, goal 1000125; collector:
+// modules/government/docket.js).
+//
+// WHY. Inside the Treasury building three floors are the project's real
+// spending lines — rewards paid for shipped work, the AI grader, and hosting —
+// and its record drawers are those same lines month by month. They come from
+// the two ledgers this module owns (credit_log, cost_log) through ONE bounded
+// read, cost.treasuryMonths. The ledgers are already published unauthenticated
+// by GET /public/cost-summary, so the floors are any builder's to read.
+//
+// Reserve and spending votes are not here: Reserve is the `money` reading
+// (autonomy's unattended ceiling), and the project treasury with its own budget
+// and votes is an engine that does not exist yet (the docket says `coming`).
+//
+// Contributed from the cost route factory (a module never requires a sibling,
+// ADR 0083). Pure mappers exported for tests.
+
+const api = require('../../src/module-api');
+const cost = require('./cost');
+
+const POINT = 'governor.docket';
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+
+function usd(n) {
+  const v = Math.round(Number(n) || 0);
+  return `$${v.toLocaleString('en-US')}`;
+}
+function monthKey(now) { const d = new Date(now); return `${d.getUTCFullYear()}-${String(d.getUTCMonth() + 1).padStart(2, '0')}`; }
+function monthWord(key) { const m = Number(String(key).slice(5, 7)); return MONTHS[m - 1] || String(key); }
+
+// One spending line's floor from the month rows. Pure.
+function lineFloor(months, now, field, { what, meta }) {
+  const rows = Array.isArray(months) ? months : [];
+  const cur = rows.find((r) => r.month === monthKey(now));
+  const prev = rows.find((r) => r.month < monthKey(now));
+  const v = cur ? Number(cur[field]) || 0 : 0;
+  const lines = [[what, meta]];
+  if (prev) lines.push([`${usd(prev[field])} in ${monthWord(prev.month)}.`, 'last month']);
+  return { count: usd(v), line: `${usd(v)} this month`, lines, hot: false };
+}
+
+function rewardsFloor(months, now) {
+  const f = lineFloor(months, now, 'rewards_credits', { what: 'Paid to builders for shipped work, one credit to the dollar.', meta: 'each ship' });
+  const cur = (months || []).find((r) => r.month === monthKey(now));
+  const n = cur ? cur.rewarded_builders : 0;
+  return { ...f, line: `${f.count} this month · ${n} ${n === 1 ? 'builder' : 'builders'}` };
+}
+const gradingFloor = (months, now) => lineFloor(months, now, 'grading_usd', { what: 'The reviewer that grades every ship.', meta: 'each ship' });
+const hostingFloor = (months, now) => lineFloor(months, now, 'hosting_usd', { what: 'Servers, storage and the domain.', meta: 'monthly' });
+
+// The record: each month's three lines. Pure.
+function treasuryHistory(months) {
+  const out = [];
+  for (const r of months || []) {
+    const at = `${r.month}-01T00:00:00.000Z`;
+    if (r.rewards_credits > 0) out.push({ id: `rewards:${r.month}`, title: `Paid ${usd(r.rewards_credits)} to ${r.rewarded_builders} ${r.rewarded_builders === 1 ? 'builder' : 'builders'}`, at, outcome: 'rewards' });
+    if (r.grading_usd > 0) out.push({ id: `grading:${r.month}`, title: `AI grading cost ${usd(r.grading_usd)}`, at, outcome: 'grading' });
+    if (r.hosting_usd > 0) out.push({ id: `hosting:${r.month}`, title: `Hosting cost ${usd(r.hosting_usd)}`, at, outcome: 'hosting' });
+  }
+  return out;
+}
+
+// One read per docket request: the collector hands every read a per-request
+// `once(key, fn)` (docket.js buildDocket), so two floors that need the same rows
+// share one query. Without it (a direct call) the read simply runs.
+const shared = (once, key, fn) => (typeof once === 'function' ? once(key, fn) : fn());
+const monthsFor = (once) => shared(once, 'economy.treasuryMonths', () => cost.treasuryMonths({ months: 6 }));
+
+function contributeEconomyToDocket() {
+  const any = { anyBuilder: true };
+  const at = (now) => now || Date.now();
+  api.contribute(POINT, { floor: 'treasury.rewards', gate: any, read: async (_c, { now, once } = {}) => rewardsFloor(await monthsFor(once), at(now)) });
+  api.contribute(POINT, { floor: 'treasury.grading', gate: any, read: async (_c, { now, once } = {}) => gradingFloor(await monthsFor(once), at(now)) });
+  api.contribute(POINT, { floor: 'treasury.hosting', gate: any, read: async (_c, { now, once } = {}) => hostingFloor(await monthsFor(once), at(now)) });
+  api.contribute(POINT, { history: 'treasury', building: 'treasury', gate: any, read: async (_c, { once } = {}) => treasuryHistory(await monthsFor(once)) });
+}
+
+module.exports = { contributeEconomyToDocket, rewardsFloor, gradingFloor, hostingFloor, treasuryHistory };

package/modules/economy/routes/cost.js

@@ -25,6 +25,8 @@ const { validateOrRespond, LIMITS } = api;
 const COST_CATEGORIES = ['api', 'compute', 'infra', 'domain', 'art', 'other'];
 
 module.exports = function buildCostRouter() {
+  // The Treasury's floors and record in the Governor City (task 1004527).
+  require('../governor-docket').contributeEconomyToDocket();
   const router = express.Router();
 
   // rank: any-builder — log cost on own claim (idempotent via source/source_ref).

package/modules/government/docket-floors.js

@@ -0,0 +1,222 @@
+'use strict';
+
+// modules/government/docket-floors.js — the floors and the record this module
+// answers for the governor's docket (task 1004527, goal 1000125).
+//
+// WHY. Inside each building of the Governor City a floor is either a queue of
+// matters (a docket source), a reading, or a STATE: who sits on the council,
+// what each section of the charter says, the ranks and who holds them. The
+// government module owns those states, so it answers them here, from the reads
+// docketFor() has already made once for the request (the board block in force,
+// the decision-rules table, the seated board, the founding stages, the ranks and
+// the closed sittings). Every builder below is PURE — a missing input gives
+// `null`, which the collector reports as `unavailable`, never as an empty floor.
+//
+// NOTHING IS INVENTED. Each line is a sentence about a row that exists. Where
+// the design names an engine this project does not have yet (seats with a term,
+// elections and recalls, promotion by a vote, a written purpose), the floor
+// says so in words and marks the line `coming`.
+
+const { describeMembership } = require('./membership-predicate');
+const decisionRules = require('./decision-rules');
+
+const PASS_WORDS = Object.freeze({
+  first_ratifier: 'the first yes',
+  consent: 'no one objecting',
+  majority: 'more than half saying yes',
+  unanimous: 'everyone who votes saying yes',
+});
+const OUTCOME_WORDS = Object.freeze({ passed: 'passed', returned: 'returned', expired: 'ran out of time', withdrawn: 'withdrawn' });
+const MAX_LINES = 4;
+
+function personName(p) {
+  if (!p) return null;
+  return p.display_name || p.name || p.github_login || p.login || (p.builder_id != null ? `builder ${p.builder_id}` : null);
+}
+
+// 'Ana', 'Ana and Theo', 'Ana, Theo and Mira', 'Ana, Theo, Mira and 4 more'.
+function namesLine(people, max = 3) {
+  const names = (people || []).map(personName).filter(Boolean);
+  if (!names.length) return '';
+  if (names.length === 1) return names[0];
+  if (names.length <= max) return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+  return `${names.slice(0, max).join(', ')} and ${names.length - max} more`;
+}
+
+function sentence(s) {
+  const t = String(s || '').trim();
+  if (!t) return '';
+  return t.charAt(0).toUpperCase() + t.slice(1) + (/[.!?]$/.test(t) ? '' : '.');
+}
+
+// The words a decision row is read in: who, then how.
+function decisionLine(d) {
+  if (!d) return null;
+  if (d.rule === 'vacant') return 'held by no one yet';
+  return `${d.who}${d.rule_words ? ` · ${d.rule_words}` : ''}`;
+}
+// Whether a building's row is still the one the project started with.
+function decisionMeta(d) { return d && d.as_today ? 'as founded' : 'amended'; }
+
+function decisionFor(gov, area) {
+  return (gov && Array.isArray(gov.decisions) ? gov.decisions : []).find((d) => d && d.area === area) || null;
+}
+
+// §5 Money, §6 Review, §7 Release: one building's row, in a sentence.
+function sectionFloor(gov, area) {
+  const d = decisionFor(gov, area);
+  if (!d) return null;
+  const line = decisionLine(d);
+  const text = d.rule === 'vacant'
+    ? `${d.name} is held by no one yet. Its matters wait until an amendment seats someone.`
+    : `Held by ${d.who}${d.rule_words ? `: ${d.rule_words}` : ''}.`;
+  return { count: '', line, lines: [[text, decisionMeta(d)]], hot: false };
+}
+
+function councilFloor(gov, { short = false } = {}) {
+  if (!gov || !Array.isArray(gov.members) || !gov.board) return null;
+  const n = gov.members.length;
+  const pass = PASS_WORDS[gov.board.pass_rule];
+  const lines = [];
+  if (n) lines.push([`${sentence(namesLine(gov.members, 5))}`, 'seated now']);
+  else lines.push(['No one is seated on the council.', 'seated now']);
+  if (pass) lines.push([`A matter put to it passes on ${pass}.`, 'charter']);
+  lines.push(['Seats have no term yet. Elections and recalls are coming.', 'coming']);
+  return {
+    count: String(n),
+    line: short ? `${n} ${n === 1 ? 'seat' : 'seats'} · no term yet` : `${n} ${n === 1 ? 'seat' : 'seats'}${pass ? ` · passes on ${pass}` : ''}`,
+    lines,
+    hot: false,
+  };
+}
+
+function foundingFloor(gov) {
+  const stages = gov && gov.genesis && Array.isArray(gov.genesis.stages) ? gov.genesis.stages : null;
+  if (!stages) return null;
+  const word = (s) => s.state === 'not_put' ? 'not put yet' : s.state === 'sitting' ? 'being decided' : (OUTCOME_WORDS[s.state] || String(s.state));
+  const passed = stages.filter((s) => s.state === 'passed').length;
+  return {
+    count: '',
+    line: stages.length ? `${passed} of ${stages.length} founding steps passed` : 'no founding steps',
+    lines: stages.slice(0, MAX_LINES + 1).map((s) => [sentence(s.label), word(s)]),
+    hot: stages.some((s) => s.state === 'sitting'),
+  };
+}
+
+function membershipFloor(gov) {
+  if (!gov || !gov.board) return null;
+  const who = describeMembership(gov.board.membership);
+  const people = decisionFor(gov, 'people');
+  const lines = [[who ? `The council is everyone who holds ${who}.` : 'Who sits on the council is not readable from the charter.', 'charter']];
+  if (people) lines.push([`Who joins, and their rank, is settled by ${people.who}${people.rule_words && people.rule !== 'vacant' ? `: ${people.rule_words}` : ''}.`, decisionMeta(people)]);
+  return { count: '', line: who ? `the council: ${who}` : 'who belongs, and how they join', lines, hot: false };
+}
+
+function rulesSectionFloor(gov) {
+  if (!gov || !gov.board) return null;
+  const d = decisionFor(gov, 'rules');
+  const pass = PASS_WORDS[gov.board.pass_rule];
+  const lines = [];
+  if (pass) lines.push([`A change to the charter passes on ${pass}.`, 'charter']);
+  if (d) lines.push([`A standing rule is set by ${d.who}${d.rule_words && d.rule !== 'vacant' ? `: ${d.rule_words}` : ''}.`, decisionMeta(d)]);
+  if (!lines.length) return null;
+  return { count: '', line: d ? decisionLine(d) : 'how a rule passes', lines, hot: false };
+}
+
+function testersFloor(gov) {
+  const d = decisionFor(gov, 'review');
+  const holders = gov && gov.holders ? gov.holders.review : null;
+  if (!d || !Array.isArray(holders)) return null;
+  if (d.rule === 'vacant') return { count: '0', line: 'no seat yet', lines: [['No one holds the testers seat yet.', decisionMeta(d)]], hot: false };
+  const n = holders.length;
+  return {
+    count: String(n),
+    line: n ? namesLine(holders) : 'no one holds the seat',
+    lines: [[n ? `${sentence(namesLine(holders, 5)).replace(/\.$/, '')} may sign off finished work.` : 'No one may sign off finished work yet.', decisionMeta(d)], [sentence(d.rule_words || ''), 'rule']].filter((l) => l[0]),
+    hot: false,
+  };
+}
+
+function ranksFloor(gov) {
+  if (!gov || !Array.isArray(gov.ranks)) return null;
+  const ranks = gov.ranks.slice().sort((a, b) => (b.holders || 0) - (a.holders || 0));
+  const people = decisionFor(gov, 'people');
+  const lines = ranks.slice(0, MAX_LINES).map((r) => [String(r.label || r.rank_key), `${r.holders || 0} ${(r.holders || 0) === 1 ? 'person' : 'people'}`]);
+  lines.push([`Ranks are granted by ${people ? people.who : 'whoever may manage ranks'}. Promotion by a vote is coming.`, 'coming']);
+  return { count: String(ranks.length), line: `${ranks.length} ${ranks.length === 1 ? 'rank' : 'ranks'}`, lines, hot: false };
+}
+
+// Every floor this module answers, keyed as docket-vocab FLOORS names them.
+const BUILDERS = Object.freeze({
+  'charter.founding': foundingFloor,
+  'charter.membership': membershipFloor,
+  'charter.council': (gov) => councilFloor(gov),
+  'charter.rules': rulesSectionFloor,
+  'charter.money': (gov) => sectionFloor(gov, 'treasury'),
+  'charter.review': (gov) => sectionFloor(gov, 'review'),
+  'charter.release': (gov) => sectionFloor(gov, 'release'),
+  'people.council': (gov) => councilFloor(gov, { short: true }),
+  'people.testers': testersFloor,
+  'people.ranks': ranksFloor,
+  'review.testers': testersFloor,
+});
+
+// Ideas to ratify: the board's open full-idea sittings the viewer can see. Pure
+// over the docket's own matters, so it can never disagree with the pins.
+function ideasFloor(matters) {
+  const open = (matters || []).filter((m) => m.source === 'board' && m.short === 'idea to ratify' && m.state !== 'settled');
+  const n = open.length;
+  return {
+    count: String(n),
+    line: n ? `${n} full ${n === 1 ? 'idea' : 'ideas'} waiting for a vote` : 'no full idea waiting for a vote',
+    lines: open.slice(0, MAX_LINES).map((m) => [m.title, m.state === 'needs' ? 'needs you' : 'moving']),
+    hot: open.some((m) => m.state === 'needs'),
+  };
+}
+
+function firstLine(md, fallback) {
+  const line = String(md || '').split(/\r?\n/).map((s) => s.replace(/^[#>*\-\s]+/, '').trim()).find(Boolean);
+  if (!line) return fallback;
+  return line.length > 120 ? `${line.slice(0, 117)}…` : line;
+}
+
+// The record: what this module has closed, as history rows. Pure.
+//   amendments  db.listAmendmentHistory rows (closed amendment sittings)
+//   genesis     genesisStageStatus().stages (closed founding steps)
+//   closed      boardRoomView().closed (closed sittings of every subject)
+//   assignments db.listAssignments rows (who was given which rank, when)
+function governmentHistory(gov) {
+  const out = [];
+  const outcome = (o) => OUTCOME_WORDS[o] || (o ? String(o) : null);
+  for (const a of (gov && gov.amendments) || []) {
+    if (!a || !a.closed_at) continue;
+    out.push({ id: `amendment:${a.item_id}`, building: 'charter', at: a.closed_at, outcome: outcome(a.outcome),
+      title: a.kind === 'decision_rules' ? firstLine(a.rationale_md, 'A change to who decides at a building') : firstLine(a.rationale_md, 'A change to the charter') });
+  }
+  const stages = gov && gov.genesis && Array.isArray(gov.genesis.stages) ? gov.genesis.stages : [];
+  for (const s of stages) {
+    if (!s.closed_at) continue;
+    out.push({ id: `founding:${s.item_id}`, building: 'charter', at: s.closed_at, outcome: outcome(s.state), title: `Founding: ${s.label}` });
+  }
+  for (const item of (gov && gov.closed) || []) {
+    if (!item || !item.closed_at) continue;
+    const area = decisionRules.areaForSubjectType(item.subject_type);
+    const building = area || (item.subject_type === 'full_idea' ? 'planning' : null);
+    if (!building) continue; // amendments and founding steps are filed above
+    const title = (item.subject && item.subject.title) || (item.subject_type === 'full_idea' ? `Full idea ${item.subject_id}` : `A matter at ${building}`);
+    const o = item.subject_type === 'full_idea' && item.outcome === 'passed' ? 'ratified' : outcome(item.outcome);
+    out.push({ id: `board:${item.id}`, building, at: item.closed_at, outcome: o, title });
+  }
+  for (const r of (gov && gov.assignments) || []) {
+    if (!r || !r.assigned_at || r.is_system) continue;
+    const who = r.display_name || r.github_login || `builder ${r.builder_id}`;
+    out.push({ id: `rank:${r.builder_id}:${r.rank_key}`, building: 'people', at: r.assigned_at, outcome: 'granted', title: `${who} holds ${r.rank_label || r.rank_key}` });
+  }
+  return out;
+}
+
+module.exports = {
+  BUILDERS,
+  ideasFloor,
+  governmentHistory,
+};

package/modules/government/docket-vocab.js

@@ -71,6 +71,25 @@ const READINGS = Object.freeze([
   Object.freeze({ key: 'rules', label: 'rules at work', building: 'rules' }),
 ]);
 
+// The floors inside the buildings that are not a queue of matters or a reading
+// (task 1004527): a state, a roster or a month's figure, each read live by the
+// module that owns it. The docket reports a status for every one, so a floor
+// whose engine does not exist yet is drawn and says so (`coming`) rather than
+// looking empty.
+const FLOORS = Object.freeze([
+  ['charter.founding', 'charter'], ['charter.purpose', 'charter'], ['charter.membership', 'charter'],
+  ['charter.council', 'charter'], ['charter.rules', 'charter'], ['charter.money', 'charter'],
+  ['charter.review', 'charter'], ['charter.release', 'charter'],
+  ['rules.in_force', 'rules'],
+  ['people.council', 'people'], ['people.testers', 'people'], ['people.newcomers', 'people'], ['people.ranks', 'people'],
+  ['planning.goals', 'planning'], ['planning.ideas', 'planning'], ['planning.priorities', 'planning'], ['planning.versions', 'planning'],
+  ['automation.allowed_goals', 'automation'], ['automation.running', 'automation'],
+  ['automation.spending_limit', 'automation'], ['automation.reports', 'automation'],
+  ['review.testers', 'review'], ['review.signed_off', 'review'],
+  ['release.held_back', 'release'], ['release.live_month', 'release'],
+  ['treasury.rewards', 'treasury'], ['treasury.grading', 'treasury'], ['treasury.hosting', 'treasury'],
+].map(([key, building]) => Object.freeze({ key, building })));
+
 module.exports = {
   BUILDINGS,
   BUILDING_KEYS,
@@ -79,4 +98,5 @@ module.exports = {
   PASS_RULE_TO_RULE,
   STATES,
   READINGS,
+  FLOORS,
 };