@bongos/core 1.21.113 → 1.21.114

package/modules/government/buildouts.js

@@ -0,0 +1,160 @@
+'use strict';
+
+// modules/government/buildouts.js — A LEAD'S BUILD-OUTS: the structure a
+// building grows under its holder, as data (task 1004711, goal 1000111; ADR
+// 0378). db.js holds the reads and the one write, decision-board.js decides a
+// build-out (at once, or filed as a vote) and carries out a passed one,
+// routes/government.js serves POST /government/buildouts, and government_030
+// is the table and its guard.
+//
+// WHAT A BUILD-OUT IS. One of the four capsules build-rights.js names, added to
+// one of the nine buildings: a committee room, a new floor, an annex, or growing
+// the building into a district. It carries a short name and one line saying
+// what it is for. A build-out is never edited or taken down: each row is one
+// change to the city, on the record.
+//
+// THE TWO PATHS, decided by the ONE rule (build-rights.js, task 1004710):
+//   * AT ONCE — the building's holder (its Lead, or the owner seat when it is
+//     unseated: leads.answerFor) asks, and build_rights for that capsule says
+//     `without_vote`: the row is written now, carrying the rule's `ground` and
+//     `why`. The city shows it being built (a live site, scaffold and crane)
+//     for BUILD_HOURS from when it started; then it stands as built.
+//   * BY VOTE — otherwise the ask is filed as a matter (action build_out)
+//     through the board's own matters path (decision-board openMatter, the same
+//     code POST /government/board/matters runs). While the sitting is open the
+//     city draws it as a dashed ghost with the sitting's tally arc; when it
+//     passes, the row is written naming the passed item and it goes up.
+//
+// WHO MAY ASK. Only the building's holder: a Lead grows the structure under
+// them. Whether they may do it without a vote is never theirs to say.
+//
+// PURE: no db.
+
+const { AREA_KEYS } = require('./decision-rules');
+const { CAPSULES } = require('./build-rights');
+
+// How long a build-out stands as a live site before it reads as built. Progress
+// is the share of this window since it started: a real clock, not a number
+// anyone sets.
+const BUILD_HOURS = 24;
+const BUILD_MS = BUILD_HOURS * 3600 * 1000;
+const NAME_MIN = 2;
+const NAME_MAX = 40;
+const LINE_MAX = 140;
+
+// What each capsule is called when its holder names nothing.
+const DEFAULT_NAMES = Object.freeze({
+  committee: 'Committee room',
+  floor: 'New floor',
+  annex: 'Annex',
+  district: 'District',
+});
+
+const isBuilding = (b) => typeof b === 'string' && AREA_KEYS.includes(b);
+const isCapsule = (c) => typeof c === 'string' && CAPSULES.includes(c);
+
+// A build-out's name, normalised, or null when it breaks the rule (2-40
+// characters, one line). An absent name takes the capsule's default.
+function nameOf(raw, capsule) {
+  if (raw == null || raw === '') return DEFAULT_NAMES[capsule] || null;
+  if (typeof raw !== 'string' || /[\r\n]/.test(raw)) return null;
+  const s = raw.trim();
+  return s.length >= NAME_MIN && s.length <= NAME_MAX ? s : null;
+}
+// Its line: one line of at most 140 characters, or '' when none is given.
+function lineOf(raw) {
+  if (raw == null || raw === '') return '';
+  if (typeof raw !== 'string' || /[\r\n]/.test(raw)) return null;
+  const s = raw.trim();
+  return s.length <= LINE_MAX ? s : null;
+}
+
+// A build-out ask, checked strictly: { ok, buildout } or { ok: false, reason, field }.
+// The same shape is the matter action (type 'build_out') a vote carries.
+function checkBuildOut(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return { ok: false, reason: 'bad_buildout', field: null };
+  for (const k of Object.keys(raw)) {
+    if (!['type', 'building', 'capsule', 'name', 'line'].includes(k)) return { ok: false, reason: 'unknown_field', field: k };
+  }
+  if (raw.type != null && raw.type !== 'build_out') return { ok: false, reason: 'bad_buildout', field: 'type' };
+  if (!isBuilding(raw.building)) return { ok: false, reason: 'bad_buildout', field: 'building' };
+  if (!isCapsule(raw.capsule)) return { ok: false, reason: 'bad_buildout', field: 'capsule' };
+  const name = nameOf(raw.name, raw.capsule);
+  if (!name) return { ok: false, reason: 'bad_buildout', field: 'name' };
+  const line = lineOf(raw.line);
+  if (line == null) return { ok: false, reason: 'bad_buildout', field: 'line' };
+  return { ok: true, buildout: { type: 'build_out', building: raw.building, capsule: raw.capsule, name, line } };
+}
+
+// Where a build-out vote is filed: a matter at the building itself. The Charter
+// takes no matters (its changes are amendments), so its build-outs go to the
+// board as a People matter, the building that answers for positions.
+const matterAreaFor = (building) => (building === 'charter' ? 'people' : building);
+
+// How far up a build-out stands at `now` (ms): 0..1 over BUILD_HOURS from its start.
+function progressOf(row, now) {
+  const t = Date.parse(row && row.started_at);
+  if (!Number.isFinite(t) || !Number.isFinite(now)) return 1;
+  return Math.max(0, Math.min(1, Math.round(((now - t) / BUILD_MS) * 1000) / 1000));
+}
+
+// One standing build-out as the read shows it.
+function projectBuildOut(r, now) {
+  const progress = progressOf(r, now);
+  const started = r.started_at instanceof Date ? r.started_at.toISOString() : r.started_at || null;
+  return {
+    id: String(r.id),
+    building: r.building,
+    capsule: r.capsule,
+    name: r.name,
+    line: r.line || '',
+    state: progress >= 1 ? 'built' : 'building',
+    progress,
+    started_at: started,
+    builder: r.built_by == null ? null : { id: String(r.built_by), login: r.github_login || null, name: r.display_name || r.github_login || null },
+    // how it was allowed: a passed vote, or the rule that let its holder build at once
+    allowed: r.authorised_by_item_id != null
+      ? { path: 'vote', item_id: String(r.authorised_by_item_id), href: `/board-room?item=${r.authorised_by_item_id}` }
+      : { path: 'at_once', ground: r.ground, why: r.why || null },
+  };
+}
+
+// One proposal waiting on its sitting: an open board item whose matter is a build_out.
+function projectProposal(p) {
+  const a = (p && p.action) || {};
+  return {
+    item_id: String(p.item_id),
+    matter_id: String(p.matter_id),
+    // the docket's id for this sitting: its tally rides there
+    docket_id: `board:${p.item_id}`,
+    building: a.building,
+    capsule: a.capsule,
+    name: a.name,
+    line: a.line || '',
+    opened_at: p.opened_at || null,
+    closes_at: p.closes_at || null,
+    href: `/board-room?item=${p.item_id}`,
+  };
+}
+
+// Per building: what stands (built or going up) and what waits on a vote.
+// `rows` are government_buildouts rows, `pending` the open build_out sittings
+// ({ item_id, matter_id, action, opened_at, closes_at }).
+function structureOf(building, rows, pending, now) {
+  return {
+    standing: (rows || []).filter((r) => r && r.building === building).map((r) => projectBuildOut(r, now)),
+    proposed: (pending || []).filter((p) => p && p.action && p.action.building === building).map(projectProposal),
+  };
+}
+
+module.exports = {
+  BUILD_HOURS,
+  BUILD_MS,
+  DEFAULT_NAMES,
+  NAME_MAX,
+  LINE_MAX,
+  checkBuildOut,
+  matterAreaFor,
+  progressOf,
+  structureOf,
+};

package/modules/government/counts.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// modules/government/counts.js — the government's counts, in ONE server read
+// (task 1004716, goal 1000111): GET /government/counts.
+//
+// WHY. The city's plaque and door, the street's header, the decision deck and the
+// top bar's Governing tally all print the same five numbers ("24 to do", "3 wait
+// on others", "38 to decide", "5 agents working", "7 moving"). The hall counted
+// them itself over about five reads (the docket, the blockers, the seats, the
+// claims, GET /moving), and a page that only wanted the tally paid for all of
+// them. Now the server answers the counts once, and the hall's one count rule
+// (modules/hall-ui/public/gov-living.js countsOf) reads them from here.
+//
+// THE RULE IS THE DOCKET'S, not a second one. Whether a matter is on you is the
+// route the docket already carries (routing.routeMatter `yours`, task 1004705):
+//   on_you          docket matters whose route is yours (the docket's counts.yours)
+//   on_others       matters that need a person, are not yours, and somebody can
+//                   still answer (an overdue or unheld ask has settled: route.nobody)
+//   open            on_you + on_others: what the deck holds
+//   agents_at_work  open claims, one per agent (GET /tasks/claimable active_claims)
+//   moving          tasks being built or waiting to land (GET /moving: active +
+//                   confirmed); never below agents_at_work
+// A docket that could not be routed (the seats were unreadable) says every matter
+// that needs a person is on you, as the hall did before routing existed.
+// A count that could not be read is null, never 0: zero says nothing waits on you.
+//
+// `yours` and `others` name the matters, so a page can take away the ones it has
+// answered this visit without reading the docket again.
+
+const api = require('../../src/module-api');
+
+// → the counts over a docket (docket.buildDocket's shape) and the traffic counts.
+// Pure; the route and the hall's parity test (tests/government_counts.mjs) call it.
+function countsOf(docket, traffic) {
+  const d = docket && typeof docket === 'object' ? docket : null;
+  const t = traffic && typeof traffic === 'object' ? traffic : {};
+  const yours = [];
+  const others = [];
+  if (d) {
+    const routed = d.routed === true;
+    for (const m of Array.isArray(d.matters) ? d.matters : []) {
+      if (!m || m.id == null || m.state !== 'needs') continue;
+      const r = routed && m.route && typeof m.route === 'object' ? m.route : null;
+      if (r && r.nobody) continue;
+      (routed ? (r && r.yours) : true) ? yours.push(String(m.id)) : others.push(String(m.id));
+    }
+  }
+  const n = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null);
+  return {
+    on_you: d ? yours.length : null,
+    on_others: d ? others.length : null,
+    open: d ? yours.length + others.length : null,
+    agents_at_work: n(t.agents_at_work),
+    moving: n(t.moving),
+    routed: !!(d && d.routed === true),
+    yours: d ? yours : null,
+    others: d ? others : null,
+  };
+}
+
+// The two traffic counts through the `lifecycle.traffic` port (modules/lifecycle/
+// moving.js); a module that is off, or a count that fails, leaves its figure null.
+async function readTraffic() {
+  const port = typeof api.resolveOptional === 'function' ? api.resolveOptional('lifecycle.traffic', null) : null;
+  if (!port) return {};
+  const [moving, agents] = await Promise.all([
+    Promise.resolve().then(() => port.countMoving()).catch(() => null),
+    Promise.resolve().then(() => port.countAgentsAtWork()).catch(() => null),
+  ]);
+  return { moving: moving && typeof moving.moving === 'number' ? moving.moving : null, agents_at_work: agents };
+}
+
+// GET /government/counts for this viewer: the docket they would read (the same
+// per-source gates, the same seats) and the traffic, counted once.
+async function countsFor(builder, deps = {}) {
+  const docket = deps.docket || require('./docket');
+  const [d, traffic] = await Promise.all([docket.docketFor(builder), (deps.readTraffic || readTraffic)()]);
+  return Object.assign({ viewer: { id: d && d.viewer ? d.viewer.id : null }, generated_at: d && d.generated_at ? d.generated_at : new Date().toISOString() }, countsOf(d, traffic));
+}
+
+module.exports = { countsOf, countsFor };

package/modules/government/db.js

@@ -687,6 +687,238 @@ async function applyDecisionRules(client, { itemId, rules }) {
   return written;
 }
 
+// --- standing orders: the project's laws (task 1004706, government_027) -----
+
+// The law book. In force only by default, in the order they passed; with
+// includeRepealed, every law ever passed. Each row carries the government it was
+// decided under (the passing item's snapshotted constitution) and its proposer.
+// Read per request, uncached — a law passed a moment ago reads back at once.
+async function listLaws({ includeRepealed = false } = {}) {
+  const { rows } = await pool.query(
+    `SELECT l.id, l.text, l.effect_on_ai, l.locks, l.proposed_by, l.passed_by_item_id, l.passed_at,
+            l.repealed_by_item_id, l.repealed_at, i.constitution AS decided_under,
+            b.github_login AS proposer_login, b.display_name AS proposer_name
+       FROM government_laws l
+       JOIN government_board_items i ON i.id = l.passed_by_item_id
+       LEFT JOIN builders b ON b.id = l.proposed_by
+      WHERE $1::boolean OR l.repealed_at IS NULL
+      ORDER BY l.passed_at, l.id`,
+    [includeRepealed === true],
+  );
+  return rows;
+}
+
+// Who said yes on these sittings — the "who passed it" half a law row points at.
+// Open ballot (ADR 0175 §9), so nothing here is private. Oldest vote first.
+async function listYesVoters(itemIds) {
+  if (!itemIds || !itemIds.length) return [];
+  const { rows } = await pool.query(
+    `SELECT v.item_id, v.voter_id, v.cast_at, b.github_login, b.display_name
+       FROM government_board_votes v
+       LEFT JOIN builders b ON b.id = v.voter_id
+      WHERE v.item_id = ANY($1::bigint[]) AND v.direction = 'yes'
+      ORDER BY v.cast_at, v.id`,
+    [itemIds],
+  );
+  return rows;
+}
+
+// THE ONE WRITE, and it runs only INSIDE the transaction that closes a laws
+// amendment as passed (board.closeItem's afterClose — `client` is that
+// transaction). Each statement writes nothing unless the named item is a passed
+// laws amendment (the WHERE EXISTS), and government_027's trigger refuses any
+// write that is not — so a law that skipped the board cannot land even through
+// hand-written SQL. An enacted law that did not land throws, which rolls the
+// close back (the sitting is retried, never passed-but-unapplied). A repeal of a
+// law another sitting already repealed is not an error: it is already out of
+// force, and the count says so.
+async function applyLaws(client, { itemId, enact = [], repeal = [], proposedBy = null }) {
+  const enacted = [];
+  for (const law of enact) {
+    const { rows } = await client.query(
+      `INSERT INTO government_laws (text, effect_on_ai, locks, proposed_by, passed_by_item_id)
+       SELECT $1::text, $2::text, $3::jsonb, $4::bigint, $5::bigint
+        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 = 'laws')
+       RETURNING id, text, effect_on_ai, locks, proposed_by, passed_by_item_id, passed_at`,
+      [law.text, law.effect_on_ai ?? null, JSON.stringify(law.locks || []), proposedBy, itemId],
+    );
+    if (rows.length !== 1) throw new Error(`law "${law.text}" not written (item ${itemId} is not a passed laws amendment)`);
+    enacted.push(rows[0]);
+  }
+  let repealed = [];
+  if (repeal.length) {
+    const { rows } = await client.query(
+      `UPDATE government_laws
+          SET repealed_by_item_id = $1::bigint, repealed_at = now()
+        WHERE id = ANY($2::bigint[]) AND repealed_at IS NULL
+          AND EXISTS (
+            SELECT 1 FROM government_board_items i
+              JOIN government_amendments a ON a.id = i.subject_id
+             WHERE i.id = $1::bigint AND i.subject_type = 'constitutional_amendment'
+               AND i.outcome = 'passed' AND a.kind = 'laws')
+        RETURNING id, repealed_at`,
+      [itemId, repeal],
+    );
+    repealed = rows;
+  }
+  return { enacted, repealed };
+}
+
+// --- the Lead of each building (task 1004709, government_029) -------------
+
+// Every appointment, in office first by default. Each row carries the Lead's
+// login and name. Read per request, uncached — an appointment carried out a
+// moment ago reads back at once.
+async function listLeads({ includePast = false } = {}) {
+  const { rows } = await pool.query(
+    `SELECT l.id, l.building, l.builder_id, l.charter, l.appointed_by_item_id, l.appointed_at,
+            l.removed_by_item_id, l.removed_at, b.github_login, b.display_name
+       FROM government_leads l
+       LEFT JOIN builders b ON b.id = l.builder_id
+      WHERE $1::boolean OR l.removed_at IS NULL
+      ORDER BY l.appointed_at, l.id`,
+    [includePast === true],
+  );
+  return rows;
+}
+
+// Every active Archon (the founder's rank), oldest id first: the owner seat
+// (leads.js ownerOf), the founding Archon first.
+async function listActiveArchons() {
+  const { rows } = await pool.query(
+    `SELECT id, github_login, display_name
+       FROM builders
+      WHERE rank = 'archon' AND status = 'active' AND system_role IS NULL
+      ORDER BY id`,
+  );
+  return rows;
+}
+
+// One builder of this project, or null: who a Lead appointment names. Only an
+// active person (no machine identity) can be appointed.
+async function getActiveBuilder(builderId) {
+  const { rows } = await pool.query(
+    `SELECT id, github_login, display_name FROM builders
+      WHERE id = $1 AND status = 'active' AND system_role IS NULL`,
+    [builderId],
+  );
+  return rows[0] || null;
+}
+
+// THE ONE WRITE: carry out a PASSED People matter's Lead act, in one
+// transaction. appoint_lead ends the building's Lead in office (if any) and
+// seats the new one; remove_lead ends the Lead in office. Every statement names
+// the passed item, and government_029's trigger refuses any write that item
+// does not say — so a Lead that skipped the vote cannot land even through
+// hand-written SQL. Carried out once: a second run of the same item seats
+// nobody twice (the unique index on appointed_by_item_id) and says so.
+// Returns { done, reason?, lead?, ended? }.
+async function applyLeadAct({ itemId, action }) {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    // the building's row of office, locked so two passed matters land one at a time
+    const { rows: current } = await client.query(
+      `SELECT id, builder_id, appointed_by_item_id FROM government_leads
+        WHERE building = $1 AND removed_at IS NULL
+          FOR UPDATE`,
+      [action.building],
+    );
+    const sitting = current[0] || null;
+    if (action.type === 'appoint_lead' && sitting && String(sitting.appointed_by_item_id) === String(itemId)) {
+      await client.query('ROLLBACK');
+      return { done: true, reason: 'already_carried_out' };
+    }
+    if (action.type === 'remove_lead' && !sitting) {
+      await client.query('ROLLBACK');
+      return { done: false, reason: 'no_lead' };
+    }
+    let ended = null;
+    if (sitting) {
+      const { rows } = await client.query(
+        `UPDATE government_leads SET removed_by_item_id = $1::bigint, removed_at = now()
+          WHERE id = $2 AND removed_at IS NULL
+          RETURNING id, builder_id, removed_at`,
+        [itemId, sitting.id],
+      );
+      ended = rows[0] || null;
+    }
+    let lead = null;
+    if (action.type === 'appoint_lead') {
+      const { rows } = await client.query(
+        `INSERT INTO government_leads (building, builder_id, charter, appointed_by_item_id)
+         VALUES ($1, $2::bigint, $3, $4::bigint)
+         ON CONFLICT (appointed_by_item_id) DO NOTHING
+         RETURNING id, building, builder_id, charter, appointed_by_item_id, appointed_at`,
+        [action.building, action.builder_id, action.charter, itemId],
+      );
+      if (!rows.length) {
+        await client.query('ROLLBACK');
+        return { done: true, reason: 'already_carried_out' };
+      }
+      lead = rows[0];
+    }
+    await client.query('COMMIT');
+    return { done: true, lead, ended };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// --- a Lead's build-outs (task 1004711, government_030) ---------------------
+
+// Every build-out on the record, oldest first, each with who asked. Read per
+// request, uncached: one built a moment ago reads back at once.
+async function listBuildouts() {
+  const { rows } = await pool.query(
+    `SELECT o.id, o.building, o.capsule, o.name, o.line, o.built_by, o.authorised_by_item_id,
+            o.ground, o.why, o.started_at, b.github_login, b.display_name
+       FROM government_buildouts o
+       LEFT JOIN builders b ON b.id = o.built_by
+      ORDER BY o.started_at, o.id`,
+  );
+  return rows;
+}
+
+// The build-outs waiting on a vote: every OPEN sitting whose matter's action is
+// a build_out, oldest first.
+async function listPendingBuildouts() {
+  const { rows } = await pool.query(
+    `SELECT i.id AS item_id, m.id AS matter_id, m.action, i.opened_at, i.closes_at
+       FROM government_board_items i
+       JOIN government_matters m ON m.id = i.subject_id AND i.subject_type = m.area || '_matter'
+      WHERE i.closed_at IS NULL
+        AND m.action->>'type' = 'build_out'
+      ORDER BY i.opened_at, i.id`,
+  );
+  return rows;
+}
+
+// THE ONE WRITE: put a build-out on the record. Exactly one of `itemId` (a
+// passed build_out matter: the vote path) or `ground` + `why` (the build-rights
+// answer that let its holder build at once). government_030's trigger refuses a
+// vote its matter did not say, an at-once district, and any later edit. A
+// passed item builds once: a second run returns { done: true, reason:
+// 'already_carried_out' }.
+async function insertBuildout({ building, capsule, name, line = '', builtBy = null, itemId = null, ground = null, why = null }) {
+  const { rows } = await pool.query(
+    `INSERT INTO government_buildouts (building, capsule, name, line, built_by, authorised_by_item_id, ground, why)
+     VALUES ($1, $2, $3, $4, $5::bigint, $6::bigint, $7, $8)
+     ON CONFLICT (authorised_by_item_id) WHERE authorised_by_item_id IS NOT NULL DO NOTHING
+     RETURNING id, building, capsule, name, line, built_by, authorised_by_item_id, ground, why, started_at`,
+    [building, capsule, name, line, builtBy, itemId, ground, why],
+  );
+  if (!rows.length) return { done: true, reason: 'already_carried_out' };
+  return { done: true, buildout: rows[0] };
+}
+
 // 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(
@@ -955,6 +1187,16 @@ module.exports = {
   getAmendment,
   listDecisionRules,
   applyDecisionRules,
+  listLaws,
+  listYesVoters,
+  applyLaws,
+  listLeads,
+  listActiveArchons,
+  getActiveBuilder,
+  applyLeadAct,
+  listBuildouts,
+  listPendingBuildouts,
+  insertBuildout,
   createMatter,
   getMatter,
   getMatterSubjects,