@bongos/core 1.23.22 → 1.24.1

package/modules/government/db.js

@@ -429,9 +429,26 @@ async function openBoardItem({ subjectType, subjectId, openedBy = null, constitu
      RETURNING *`,
     [subjectType, subjectId, openedBy, windowMinutes, JSON.stringify(constitution || {})],
   );
+  // Tell the expiry poller (task 1004960): it sleeps until the soonest deadline
+  // it knows of, so a window shorter than its idle wait must wake it sooner.
+  // closes_at is now() + the window, so the window IS the time until close.
+  // A listener the poller registers (not a require: the poller requires this
+  // file). Never let a hint fail an open.
+  if (rows[0] && windowMinutes != null) {
+    for (const fn of deadlineListeners) {
+      try { fn(Number(windowMinutes) * 60_000); } catch (_) { /* best-effort */ }
+    }
+  }
   return rows[0] || null;
 }
 
+// Who wants to hear that a timed window opened (the expiry poller's start()).
+const deadlineListeners = new Set();
+function onBoardDeadline(fn) {
+  deadlineListeners.add(fn);
+  return () => deadlineListeners.delete(fn);
+}
+
 async function getOpenBoardItem(subjectType, subjectId) {
   const { rows } = await pool.query(
     `SELECT * FROM government_board_items
@@ -1114,6 +1131,21 @@ async function getExpiredOpenBoardItems(limit = 100) {
   return rows;
 }
 
+// The expiry poller's alarm clock (task 1004960): how many milliseconds until
+// the soonest OPEN deadline, measured on the DATABASE clock (so a skewed
+// process clock can never make the poller wake early or late), or null when no
+// open item has a clock. ONE read, served by the same partial index as the
+// sweep — the poller sleeps until this deadline instead of asking every minute.
+async function msUntilSoonestOpenDeadline() {
+  const { rows } = await pool.query(
+    `SELECT EXTRACT(EPOCH FROM (MIN(closes_at) - now())) * 1000 AS ms
+       FROM government_board_items
+      WHERE closed_at IS NULL AND closes_at IS NOT NULL`,
+  );
+  const ms = rows[0] ? rows[0].ms : null;
+  return ms == null ? null : Number(ms);
+}
+
 // The summons read (task 1003271): every OPEN item this builder could still
 // vote on, with the two facts that decide it — who authored the subject, and
 // whether this builder has already cast. Membership is NOT decided here: it
@@ -1260,6 +1292,8 @@ module.exports = {
   withdrawBoardItem,
   getIdeaCompleteness,
   getExpiredOpenBoardItems,
+  msUntilSoonestOpenDeadline,
+  onBoardDeadline,
   getLatestReturnedItemWithObjection,
   getLatestPassedItem,
   listPassedSubjectIds,

package/modules/government/docket.js

@@ -85,6 +85,7 @@ const docketFloors = require('./docket-floors');
 const governmentConfig = require('./config');
 const asksDb = require('./asks-db');
 const routing = require('./routing');
+const waiting = require('./waiting');
 const { ownerOf } = require('./leads');
 
 const log = api.logger('government');
@@ -847,6 +848,40 @@ async function loadSeats(government) {
   }
 }
 
+// OPEN BLOCKERS UNDER THE PEOPLE THEY WAIT ON (task 1004999). The blockers source is
+// read exactly as the docket reads it (the ideas module's contribution, under its own
+// `anyBuilder` gate — the list is public), each one carries its stored ask, and the
+// seats are read once, uncached (ADR 0016). waiting.js groups them with routing.js's
+// rule, so this answers "whose is it" exactly as the City does. A board seat's holders
+// are read only when some blocker names one. → { available, people, nobody, yours }
+// `available: false` names why nothing could be grouped — never an empty list
+// standing in for "nobody is waiting".
+async function blockersByPerson(builder, { contributions = registeredContributions(), now = Date.now(), timeoutMs = SOURCE_TIMEOUT_MS } = {}) {
+  const c = contributions.sources.get('blockers');
+  if (!c) return { available: false, reason: 'off', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  const permissions = await resolver.resolveBuilderPermissions(builder.id);
+  const held = new Set(permissions || []);
+  const ctx = Object.freeze({ builderId: String(builder.id), rank: builder.rank || null, has: (p) => held.has(p) });
+  if (!gateAllows(c.gate, ctx)) return { available: false, reason: 'not_yours', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  let matters;
+  try {
+    const raw = await withTimeout(Promise.resolve(c.read(ctx, { now })), timeoutMs);
+    matters = (Array.isArray(raw) ? raw : []).map((m) => normalizeMatter(m, { source: 'blockers', building: c.building || 'planning' })).filter(Boolean);
+  } catch (err) {
+    log.warn({ err: err && err.message }, 'blockers by person: blockers unreadable');
+    return { available: false, reason: 'unavailable', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  }
+  await attachAsks(matters, asksDb.asksFor, timeoutMs);
+  const boardSeat = matters.some((m) => /^board:/.test(routing.seatOf(m)));
+  const government = boardSeat
+    ? await loadGovernment({ decisions: await board.decisionRulesView().catch(() => null) })
+    : { holders: {} };
+  const seats = await loadSeats(government);
+  if (!seats) return { available: false, reason: 'unavailable', people: [], nobody: [], yours: waiting.forViewer(null, builder.id) };
+  const grouped = waiting.groupByPerson(matters, seats);
+  return { available: true, ...grouped, yours: waiting.forViewer(grouped, builder.id) };
+}
+
 // One matter with its stored ask and the seats, for passing it on to `toSeat`
 // (task 1004705): → { matter, seats } | { reason } as findMatter answers. A
 // board's holders are read only when a board seat is involved.
@@ -927,5 +962,6 @@ module.exports = {
   findMatter,
   findMatterFor,
   loadSeats,
+  blockersByPerson,
   matterWithSeats,
 };

package/modules/government/migrations/government_035_payout_approve.sql

@@ -0,0 +1,29 @@
+-- government_035_payout_approve.sql — grant the new `payout.approve` atom to
+-- Archon (task 1004913, goal 1000092 N9; ADR 0385 D4).
+--
+-- WHAT IT IS. The project's authorised person for money: signs a standing payout
+-- rule, narrows or revokes it, holds a run in its pause window, approves a single
+-- payout, signs an equity grant or a contract, and reads the approval log
+-- (core_283_payout_approvals). The routes also demand the person's own web
+-- session, so holding the atom on a CLI token is not enough to sign.
+--
+-- WHY THIS FILE EXISTS. RANK_SEED is derived from the catalog's floors, and the
+-- drift guard (tests/government_seed.mjs) compares it against the union of the
+-- run-once seed plus every later grant migration, per rank. An archon-floor key
+-- is held by archon only.
+--
+-- Additive only: one new permission key granted to one rank; nothing is revoked.
+-- Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT only).
+--
+-- The `SELECT '<rank>', unnest(ARRAY[…])` shape is load-bearing: the drift guard
+-- scans for it literally.
+
+BEGIN;
+
+INSERT INTO government_rank_permissions (rank_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'payout.approve'
+])
+ON CONFLICT (rank_key, permission_key) DO NOTHING;
+
+COMMIT;

package/modules/government/pollers/board-expiry.js

@@ -19,17 +19,32 @@
 // minute-cadence poller logging every tick would bury the journal (the
 // reconciler's own warn-once lesson).
 //
-// CADENCE: windows are minutes-granular (the recommended sitting is 90
-// minutes), so a one-minute sweep bounds lateness at ~1 minute — tight enough
-// that "closes on time" is honest, cheap enough that the query (one indexed
-// read; government_board_items_open_by_deadline exists for exactly this, per
-// government_003's own comment) is negligible. Concurrent windows are normal
+// CADENCE (task 1004960): the poller SLEEPS UNTIL THE SOONEST DEADLINE instead
+// of asking every minute. After each sweep it makes one MIN(closes_at) read
+// (msUntilSoonestOpenDeadline, the same partial index) and arms its next run
+// for just after that deadline — capped at MAX_WAIT_MS (5 minutes) so an item
+// opened by some other process is still caught. A window opened in THIS process
+// wakes it sooner through noteDeadline (db.openBoardItem calls it), so a
+// one-minute window still closes on time. An idle instance with no open clock
+// therefore reads twice per 5 minutes, not once a minute; a vote still closes
+// within ~1 second of its deadline. While something is OVERDUE after a sweep
+// (its close threw and rolled back) the retry waits RETRY_MS (the old one-minute
+// cadence), never a hot loop. Runs never overlap: a tick that fires while the
+// previous sweep is still in flight is skipped. Concurrent windows are normal
 // (owner decision 10): the sweep closes every due item, oldest deadline first.
 
 const board = require('../board');
 const db = require('../db');
 
-const INTERVAL_MS = Number(process.env.BOARD_EXPIRY_SWEEP_MS) || 60_000;
+// The longest the poller ever sleeps (BOARD_EXPIRY_SWEEP_MS overrides it). It
+// only bounds an item opened by ANOTHER process; this process's opens wake it.
+const MAX_WAIT_MS = Number(process.env.BOARD_EXPIRY_SWEEP_MS) || 5 * 60_000;
+// Kept as an alias: INTERVAL_MS was the fixed cadence before task 1004960.
+const INTERVAL_MS = MAX_WAIT_MS;
+// While an item is overdue after a sweep (its close failed and rolled back).
+const RETRY_MS = 60_000;
+// Wake just AFTER a deadline, since the sweep reads closes_at < now().
+const GRACE_MS = 1_000;
 // A first sweep shortly after boot, so windows that expired while the process
 // was down (a deploy restart mid-sitting) close promptly rather than one full
 // interval late.
@@ -38,8 +53,21 @@ const FIRST_SWEEP_DELAY_MS = Number(process.env.BOARD_EXPIRY_FIRST_MS) || 15_000
 // handful of open windows (the board's subjects are rare by construction).
 const SWEEP_LIMIT = 100;
 
-let intervalTimer = null;
-let firstTimer = null;
+let timer = null;
+let dueAt = null;      // when the armed timer fires (process clock, ms)
+let started = false;
+let running = false;
+let hintAt = null;     // soonest deadline (process clock) noted mid-sweep
+let startDeps = {};
+let unlisten = null;
+
+// When to run next, given the ms until the soonest open deadline (null: none).
+function nextDelayMs(msUntilSoonest) {
+  if (msUntilSoonest == null || !Number.isFinite(Number(msUntilSoonest))) return MAX_WAIT_MS;
+  const ms = Number(msUntilSoonest);
+  if (ms <= 0) return RETRY_MS; // still overdue after a sweep: retry, never spin
+  return Math.min(MAX_WAIT_MS, ms + GRACE_MS);
+}
 
 // One sweep. Injectable deps keep it DB-free testable: listFn yields the due
 // items, closeFn closes one, log receives the disposition lines.
@@ -82,20 +110,80 @@ function start(deps = {}) {
     console.log('[board-expiry] disabled (BOARD_EXPIRY_DISABLED=1)');
     return;
   }
-  if (intervalTimer) return; // already started
-  const tick = () => {
-    runSweep(deps).catch((e) => console.error(`[board-expiry] sweep crashed: ${e && e.message}`));
-  };
-  firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
-  if (firstTimer.unref) firstTimer.unref();
-  intervalTimer = setInterval(tick, INTERVAL_MS);
-  if (intervalTimer.unref) intervalTimer.unref(); // never hold the process open on a restart
-  console.log(`[board-expiry] started (every ${Math.round(INTERVAL_MS / 1000)}s; first sweep in ${Math.round(FIRST_SWEEP_DELAY_MS / 1000)}s)`);
+  if (started) return; // already started
+  started = true;
+  startDeps = deps;
+  unlisten = db.onBoardDeadline(noteDeadline); // a window opened here wakes us sooner
+  arm(FIRST_SWEEP_DELAY_MS);
+  console.log(`[board-expiry] started (sleeps until the soonest deadline, at most ${Math.round(MAX_WAIT_MS / 1000)}s; first sweep in ${Math.round(FIRST_SWEEP_DELAY_MS / 1000)}s)`);
+}
+
+function arm(delay) {
+  if (timer) clearTimeout(timer);
+  dueAt = Date.now() + delay;
+  timer = setTimeout(() => {
+    timer = null;
+    dueAt = null;
+    tick().catch((e) => console.error(`[board-expiry] sweep crashed: ${e && e.message}`));
+  }, delay);
+  if (timer.unref) timer.unref(); // never hold the process open on a restart
+}
+
+// One run: the sweep, then the one MIN(closes_at) read that sets the alarm.
+// A run that starts while the previous one is still in flight is skipped —
+// the running one re-arms when it finishes, so nothing is lost.
+async function tick(deps = startDeps) {
+  if (running) return { skipped: true };
+  running = true;
+  let soonest = null;
+  try {
+    const out = await runSweep(deps);
+    try {
+      soonest = await (deps.soonestFn || db.msUntilSoonestOpenDeadline)();
+    } catch (e) {
+      (deps.error || console.error)(`[board-expiry] soonest-deadline read failed: ${e && e.message}`);
+      soonest = 0; // unknown: fall back to the one-minute retry, not the 5-minute cap
+    }
+    return out;
+  } finally {
+    running = false;
+    if (hintAt != null) {
+      const hint = hintAt - Date.now();
+      soonest = soonest == null ? hint : Math.min(soonest, hint);
+      hintAt = null;
+    }
+    if (started) arm(nextDelayMs(soonest));
+  }
+}
+
+// A window was opened that closes msUntilClose from now: wake sooner if the
+// armed alarm is later than that deadline. Mid-sweep, remember it for the re-arm.
+function noteDeadline(msUntilClose) {
+  if (!started || msUntilClose == null || !Number.isFinite(Number(msUntilClose))) return;
+  const ms = Math.max(0, Number(msUntilClose));
+  if (running) {
+    const at = Date.now() + ms;
+    hintAt = hintAt == null ? at : Math.min(hintAt, at);
+    return;
+  }
+  const delay = Math.min(MAX_WAIT_MS, ms + GRACE_MS);
+  if (dueAt == null || Date.now() + delay < dueAt) arm(delay);
 }
 
 function stop() {
-  if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
-  if (intervalTimer) { clearInterval(intervalTimer); intervalTimer = null; }
+  started = false;
+  hintAt = null;
+  if (unlisten) { unlisten(); unlisten = null; }
+  if (timer) { clearTimeout(timer); timer = null; }
+  dueAt = null;
+}
+
+// For tests: what is armed right now.
+function _state() {
+  return { started, running, msUntilNextRun: dueAt == null ? null : dueAt - Date.now() };
 }
 
-module.exports = { start, stop, runSweep, INTERVAL_MS, SWEEP_LIMIT };
+module.exports = {
+  start, stop, runSweep, tick, noteDeadline, nextDelayMs, _state,
+  INTERVAL_MS, MAX_WAIT_MS, RETRY_MS, GRACE_MS, SWEEP_LIMIT,
+};

package/modules/government/protected-surfaces.json

@@ -30,6 +30,7 @@
     { "glob": "src/bongos/auth-config.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
     { "glob": "src/bongos/auth-discord.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
     { "glob": "src/bongos/auth-github.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
+    { "glob": "src/bongos/auth-google.js", "group": "authz", "why": "task 1004993 (ADR 0396). The Google sign-in beside auth-github.js: it checks Google's ID token, runs the admission gate for a Google person and mints their web session, so it is the same trust surface as the GitHub flow." },
     { "glob": "src/bongos/auth-idp.js", "group": "authz", "why": "task 1004024. Carved out of auth.js (task 1003206): the OAuth flows, session-token minting, admission and IdP checks auth.js now delegates to. Registering auth.js alone protected the facade and none of them." },
     { "glob": "src/bongos/db.js", "group": "authz", "why": "rank tiers, REQUIRES_RANK_TIER — the CASE edited in the SEC #863 incident" },
     { "glob": "src/bongos/db-kernel.js", "group": "authz", "why": "task 1004024. The kernel db slice carved out of db.js (BV1.R69 / ADR 0091): builder identity and the rank reads the SEC #863 entry above exists for." },

package/modules/government/routes/government.js

@@ -767,6 +767,28 @@ module.exports = function buildGovernmentRouter() {
   // treasury; `rule` ∈ decide first consent majority unanimous signoff rule (or
   // null); `state` ∈ needs moving settled. Nothing is ever sample data: a source
   // with nothing recorded yet is `coming`, never a placeholder row.
+  // OPEN BLOCKERS UNDER PEOPLE (task 1004999): every open blocker grouped under each
+  // person its seat resolves to (routing.js, the City's own rule), and the viewer's own
+  // group. The docket's atom: it floors at xenos, so every builder can see whose a
+  // blocker is; resolving one keeps its own blocker.review gate.
+  router.get('/government/blockers/people', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await docket.blockersByPerson(req.builder));
+    } catch (err) {
+      log.error('[gds] GET /government/blockers/people', err);
+      res.fail('blockers_people_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+  router.get('/government/blockers/for-me', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      const r = await docket.blockersByPerson(req.builder);
+      res.json({ available: r.available, reason: r.reason || null, ...r.yours });
+    } catch (err) {
+      log.error('[gds] GET /government/blockers/for-me', err);
+      res.fail('blockers_for_me_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   router.get('/government/docket', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
     try {
       res.json(await docket.docketFor(req.builder));

package/modules/government/routing.js

@@ -69,6 +69,35 @@ const idsOf = (list) => (Array.isArray(list) ? list : [])
   .filter((id) => id != null)
   .map(String);
 
+// Who each builder id is, from the seats already read (task 1004999): the owner
+// seat's Archons, the Leads in office and each building's holders. A route names
+// people, not just a seat — "waits on Lars, the owner", not "waits on the owner".
+// Pure; an id no seat row names reads as { id, login: null, name: null }.
+function directoryOf(ctx) {
+  const c = ctx || {};
+  const dir = new Map();
+  const put = (id, login, name) => {
+    if (id == null) return;
+    const key = String(id);
+    const prev = dir.get(key);
+    if (prev && prev.name) return;
+    dir.set(key, { id: key, login: login || null, name: name || login || null });
+  };
+  for (const b of (c.owner && c.owner.builders) || []) put(b.id, b.login, b.name);
+  for (const l of Array.isArray(c.leads) ? c.leads : Object.values(c.leads || {})) {
+    if (l && !l.removed_at) put(l.builder_id, l.github_login, l.display_name);
+  }
+  for (const list of Object.values(c.holders || {})) {
+    for (const p of Array.isArray(list) ? list : []) {
+      if (p && typeof p === 'object') put(p.builder_id ?? p.id, p.github_login ?? p.login, p.display_name ?? p.name);
+    }
+  }
+  return dir;
+}
+function peopleOf(ids, dir) {
+  return (ids || []).map((id) => dir.get(String(id)) || { id: String(id), login: null, name: null });
+}
+
 // resolveSeat(asked, ctx) → { asked, seat, label, builder_ids, fell_to_owner }
 //   asked        the seat the matter names
 //   seat         the seat that answers it, after any fall
@@ -97,11 +126,13 @@ function resolveSeat(asked, ctx) {
   return toOwner();
 }
 
-// routeMatter(matter, viewerId, ctx, now) → the route the docket carries:
-//   { seat, label, asked, fell_to_owner, yours, nobody: null | { why, outcome } }
+// routeMatter(matter, viewerId, ctx, now, dir) → the route the docket carries:
+//   { seat, label, asked, fell_to_owner, people, yours, nobody: null | { why, outcome } }
 // `yours` is the one answer to "is this on me": an open matter that needs a
 // person, on a seat the viewer sits in, that somebody can still answer.
-function routeMatter(matter, viewerId, ctx, now = Date.now()) {
+// `dir` is directoryOf(ctx); routeAll builds it ONCE per request and passes it,
+// so a docket of N matters does not rebuild the same name map N times.
+function routeMatter(matter, viewerId, ctx, now = Date.now(), dir = directoryOf(ctx)) {
   const m = matter || {};
   const needs = m.state === 'needs';
   // a sitting's voters are the item's own (its snapshot), never a fall to the owner
@@ -120,6 +151,8 @@ function routeMatter(matter, viewerId, ctx, now = Date.now()) {
     label: r.label,
     asked: r.asked,
     fell_to_owner: r.fell_to_owner,
+    // who sits in that seat now, by name (task 1004999); [] for a sitting's own voters
+    people: peopleOf(r.builder_ids, dir),
     yours: needs && !nobody && !!viewer && sits,
     nobody,
   };
@@ -128,8 +161,9 @@ function routeMatter(matter, viewerId, ctx, now = Date.now()) {
 // Route every matter in place; → how many are the viewer's.
 function routeAll(matters, viewerId, ctx, now = Date.now()) {
   let yours = 0;
+  const dir = directoryOf(ctx);
   for (const m of matters || []) {
-    m.route = routeMatter(m, viewerId, ctx, now);
+    m.route = routeMatter(m, viewerId, ctx, now, dir);
     if (m.route.yours) yours += 1;
   }
   return yours;
@@ -151,4 +185,4 @@ function passRefusal(matter, viewerId, toSeat, ctx, now = Date.now()) {
   return null;
 }
 
-module.exports = { seatOf, resolveSeat, routeMatter, routeAll, passRefusal, BUILDING_NAMES };
+module.exports = { seatOf, resolveSeat, directoryOf, peopleOf, routeMatter, routeAll, passRefusal, BUILDING_NAMES };

package/modules/government/waiting.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// modules/government/waiting.js — open blockers grouped UNDER THE PEOPLE they wait on
+// (task 1004999, goal 1000111).
+//
+// WHY. A blocker has no person on it: the blockers table has no assignee, and the only
+// "who" is the seat its ask names (owner | lead:<b> | board:<b> | committee:…). So every
+// surface listed every blocker to everyone, /blocker-review framed them all as the
+// owner's, and nobody could open one place and see "these wait on me" — or see that a
+// blocker was waiting on Lars rather than on "the owner".
+//
+// THE RULE. The seat is the truth; the person is resolved at READ time with the same
+// routing the City uses (routing.js seatOf → resolveSeat), so the two can never
+// disagree about whose a blocker is, and seating a new Lead moves their blockers with
+// no blocker edited. Never copy a name onto a blocker.
+//
+// A blocker waits on EVERY person its seat resolves to (a board's members, or two
+// Archons as the owner), so it is listed under each of them. One that resolves to
+// nobody is listed under `nobody`, never dropped.
+//
+// PURE: no db. docket.js reads the blockers, their asks and the seats, then calls this.
+
+const routing = require('./routing');
+
+// One blocker as a line under a person: what it is, where it lives, and the seat it
+// reaches that person through, in words ("as the owner", "as the Planning Lead").
+function itemOf(m, r) {
+  return {
+    id: m.ref && m.ref.id != null ? String(m.ref.id) : String(m.id),
+    matter_id: String(m.id),
+    title: m.title,
+    href: m.href || null,
+    opened_at: m.opened_at || null,
+    where: m.where || null,
+    seat: r.seat,
+    as: r.label,
+    asked: r.asked,
+    fell_to_owner: !!r.fell_to_owner,
+    question: m.ask && m.ask.question ? String(m.ask.question) : null,
+  };
+}
+
+const byOpened = (a, b) => String(a.opened_at || '').localeCompare(String(b.opened_at || '')) || a.id.localeCompare(b.id, 'en', { numeric: true });
+
+// groupByPerson(matters, seats) → { people: [{ person, count, items }], nobody: [items] }
+// People with the most waiting first, then by name; inside a person, oldest first.
+function groupByPerson(matters, seats) {
+  const dir = routing.directoryOf(seats);
+  const groups = new Map();
+  const nobody = [];
+  for (const m of matters || []) {
+    if (!m || m.state === 'settled') continue;
+    const r = routing.resolveSeat(routing.seatOf(m), seats);
+    const item = itemOf(m, r);
+    if (!r.builder_ids.length) { nobody.push(item); continue; }
+    for (const p of routing.peopleOf(r.builder_ids, dir)) {
+      if (!groups.has(p.id)) groups.set(p.id, { person: p, items: [] });
+      groups.get(p.id).items.push(item);
+    }
+  }
+  const people = [...groups.values()]
+    .map((g) => ({ person: g.person, count: g.items.length, items: g.items.sort(byOpened) }))
+    .sort((a, b) => b.count - a.count || String(a.person.name || a.person.id).localeCompare(String(b.person.name || b.person.id)));
+  return { people, nobody: nobody.sort(byOpened) };
+}
+
+// The viewer's own group: what waits on THEM. → { person, count, items } (count 0 when none).
+function forViewer(grouped, viewerId) {
+  const id = viewerId == null ? null : String(viewerId);
+  const g = id && grouped && Array.isArray(grouped.people) ? grouped.people.find((x) => x.person.id === id) : null;
+  return g || { person: id ? { id, login: null, name: null } : null, count: 0, items: [] };
+}
+
+module.exports = { groupByPerson, forViewer };