@bongos/core 1.23.21 → 1.24.1

package/tests/batched_writes_parity.mjs

@@ -0,0 +1,340 @@
+// tests/batched_writes_parity.mjs — the batched goal archive, version close and
+// weekly karma tally give the SAME results as the one-query-per-row loops they
+// replaced (task 1004929).
+//
+// Each case runs the old loop (tests/fixtures/per-row-loops-legacy.cjs, a
+// verbatim copy) and the new code over the SAME seeded fake database, then
+// compares what each returned or threw AND what each left in the tables. The
+// fake is a small interpreter for exactly the statements both versions send —
+// old per-row reads and new batched reads answer from one store — and it hands
+// bigint ids back as STRINGS, as node-pg does, so a plan that carries numbers is
+// matched back to rows the way production matches them. BEGIN snapshots the
+// store and ROLLBACK restores it, so a thrown run is compared on what survived.
+//
+// The rank-set apply parity lives in tests/government_routes.mjs, where the real
+// router is already standing.
+//
+// Run:  node --test tests/batched_writes_parity.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const { archiveGoalWithDispositions, closeVersion } = require('../modules/lifecycle/db.js');
+const { tallyPeerVotes } = require('../modules/lifecycle/db-analytics.js');
+const { idKey } = require('../modules/lifecycle/db-shared.js');
+const pgPool = require('../src/bongos/pool').pool;
+const legacy = require('./fixtures/per-row-loops-legacy.cjs');
+
+const TERMINAL = new Set(['shipped', 'abandoned']);
+const same = (a, b) => String(a) === String(b);
+const inIds = (arr, v) => arr.some((x) => same(idKey(x), idKey(v)));
+const clone = (v) => JSON.parse(JSON.stringify(v));
+
+// ---- the fake database -------------------------------------------------------
+
+function fakeDb(seed) {
+  let st = clone(seed);
+  let snap = null;
+  const queries = [];
+  const task = (id) => st.tasks.find((t) => same(t.id, idKey(id)));
+  const goal = (id) => st.goals.find((g) => same(g.id, idKey(id)));
+  const out = (row) => (row ? { ...row, id: String(row.id) } : row);
+  const openWork = (t) => !TERMINAL.has(t.status) && !t.title.startsWith('__smoke__');
+
+  async function query(sql, p = []) {
+    const s = String(sql).replace(/\s+/g, ' ').trim();
+    queries.push(s);
+    if (s === 'BEGIN') { snap = clone(st); return { rows: [] }; }
+    if (s === 'COMMIT') { snap = null; return { rows: [] }; }
+    if (s === 'ROLLBACK') { if (snap) st = snap; snap = null; return { rows: [] }; }
+
+    // ---- goal archive -------------------------------------------------------
+    if (/^SELECT .* FROM goals WHERE id = \$1 FOR UPDATE$/.test(s)) return { rows: [goal(p[0])].filter(Boolean).map(out) };
+    if (/FROM tasks WHERE id = \$1 AND goal_id = \$2 FOR UPDATE$/.test(s)) {
+      const t = task(p[0]);
+      return { rows: t && same(t.goal_id, p[1]) ? [out(t)] : [] };
+    }
+    if (/FROM tasks WHERE id = ANY\(\$1::bigint\[\]\) AND goal_id = \$2 ORDER BY id FOR UPDATE$/.test(s)) {
+      return { rows: st.tasks.filter((t) => inIds(p[0], t.id) && same(t.goal_id, p[1])).sort((a, b) => a.id - b.id).map(out) };
+    }
+    if (/^SELECT id FROM claims WHERE task_id = \$1 AND released_at IS NULL LIMIT 1$/.test(s)) {
+      return { rows: st.claims.filter((c) => same(c.task_id, idKey(p[0])) && !c.released_at).slice(0, 1).map((c) => ({ id: String(c.id) })) };
+    }
+    if (/^SELECT DISTINCT task_id FROM claims WHERE task_id = ANY\(\$1::bigint\[\]\) AND released_at IS NULL$/.test(s)) {
+      const ids = [...new Set(st.claims.filter((c) => inIds(p[0], c.task_id) && !c.released_at).map((c) => String(c.task_id)))];
+      return { rows: ids.map((task_id) => ({ task_id })) };
+    }
+    if (/^UPDATE tasks SET status = 'abandoned', .* WHERE id = \$1$/.test(s)) {
+      const t = task(p[0]); t.status = 'abandoned'; if (p[1]) t.value_summary = p[1];
+      return { rows: [], rowCount: 1 };
+    }
+    if (/^SELECT id, status FROM goals WHERE id = \$1 FOR SHARE$/.test(s)) return { rows: [goal(p[0])].filter(Boolean).map((g) => ({ id: String(g.id), status: g.status })) };
+    if (/^UPDATE tasks SET goal_id = \$2, updated_at = now\(\) WHERE id = \$1$/.test(s)) {
+      task(p[0]).goal_id = Number(p[1]);
+      return { rows: [], rowCount: 1 };
+    }
+    if (/count\(\*\)::int AS n FROM (tasks|goals)/.test(s)) return { rows: [{ n: 0 }] }; // the re-counts are not under test
+    if (/^UPDATE goal_membership_requests/.test(s)) return { rows: [], rowCount: 0 };
+
+    // ---- version close ------------------------------------------------------
+    if (/FROM versions WHERE id = \$1 FOR UPDATE$/.test(s)) return { rows: [{ id: p[0], status: 'building' }] };
+    if (/FROM goals WHERE id = \$1 AND version_id = \$2 FOR UPDATE$/.test(s)) {
+      const g = goal(p[0]);
+      return { rows: g && same(g.version_id, p[1]) ? [out(g)] : [] };
+    }
+    if (/FROM goals WHERE id = ANY\(\$1::bigint\[\]\) AND version_id = \$2 ORDER BY id FOR UPDATE$/.test(s)) {
+      return { rows: st.goals.filter((g) => inIds(p[0], g.id) && same(g.version_id, p[1])).sort((a, b) => a.id - b.id).map(out) };
+    }
+    if (/^UPDATE tasks SET status = 'abandoned', .* WHERE goal_id = \$1 AND .* RETURNING id$/.test(s)) {
+      const hit = st.tasks.filter((t) => same(t.goal_id, idKey(p[0])) && openWork(t));
+      for (const t of hit) { t.status = 'abandoned'; t.value_summary = p[1]; }
+      return { rows: hit.map((t) => ({ id: String(t.id) })) };
+    }
+    if (/^UPDATE goals SET status = 'archived', updated_at = now\(\) WHERE id = \$1/.test(s)) {
+      const g = goal(p[0]); g.status = 'archived';
+      return { rows: [out(g)], rowCount: 1 };
+    }
+    if (/^WITH next_order AS .* INSERT INTO goals/.test(s)) {
+      const src = goal(p[0]);
+      const id = st.nextGoalId++;
+      st.goals.push({ id, version_id: p[1], title: src.title, status: 'open', succeeded_by_goal_id: null });
+      return { rows: [{ id: String(id) }] };
+    }
+    if (/^INSERT INTO goal_members/.test(s)) return { rows: [], rowCount: 0 };
+    if (/^UPDATE tasks SET goal_id = \$2, version_id = \$3, .* RETURNING id$/.test(s)) {
+      const hit = st.tasks.filter((t) => same(t.goal_id, idKey(p[0])) && openWork(t));
+      for (const t of hit) { t.goal_id = Number(p[1]); t.version_id = p[2]; }
+      return { rows: hit.map((t) => ({ id: String(t.id) })) };
+    }
+    if (/^UPDATE goals SET succeeded_by_goal_id = \$2/.test(s)) { goal(p[0]).succeeded_by_goal_id = Number(p[1]); return { rows: [] }; }
+    if (/FROM tasks t LEFT JOIN goals g/.test(s)) return { rows: [] };
+    if (/^UPDATE versions SET status = 'shipped'/.test(s)) return { rows: [{ id: p[0], status: 'shipped' }] };
+
+    // ---- weekly karma tally -------------------------------------------------
+    if (/FROM peer_votes pv JOIN tasks t/.test(s)) {
+      return { rows: st.peerVotes.filter((v) => !v.tallied).map((v) => ({ id: String(v.id), builder_id: String(v.builder_id), vote: v.vote })) };
+    }
+    if (/to_regclass\('ideas_votes'\)/.test(s)) return { rows: [{ has: st.ideaVotes !== null }] };
+    if (/FROM ideas_votes iv JOIN idea_inbox i/.test(s)) {
+      return { rows: st.ideaVotes.filter((v) => !v.tallied).map((v) => ({ id: String(v.id), builder_id: String(v.builder_id), vote: v.vote })) };
+    }
+    if (/^INSERT INTO karma_log .* VALUES \(\$1, \$2, 'peer_vote_weekly', NULL\)$/.test(s)) {
+      st.karma.push({ builder_id: String(p[0]), delta: Number(p[1]), reason: 'peer_vote_weekly', granted_by: null });
+      return { rows: [], rowCount: 1 };
+    }
+    if (/^INSERT INTO karma_log .* FROM unnest\(\$1::bigint\[\], \$2::int\[\]\) WITH ORDINALITY .* ORDER BY k\.ord$/.test(s)) {
+      p[0].forEach((b, i) => st.karma.push({ builder_id: String(b), delta: Number(p[1][i]), reason: 'peer_vote_weekly', granted_by: null }));
+      return { rows: [], rowCount: p[0].length };
+    }
+    if (/^UPDATE (peer_votes|ideas_votes) SET tallied_at = now\(\) WHERE id = ANY/.test(s)) {
+      const list = s.startsWith('UPDATE peer_votes') ? st.peerVotes : st.ideaVotes;
+      for (const v of list) if (inIds(p[0], v.id)) v.tallied = true;
+      return { rows: [], rowCount: p[0].length };
+    }
+
+    throw new Error(`fake db: unhandled statement: ${s.slice(0, 120)}`);
+  }
+  const client = { query, release() {} };
+  return {
+    pool: { connect: async () => client, query },
+    client,
+    queries,
+    get state() { return clone(st); },
+  };
+}
+
+// Run a legacy loop the way its function ran it: inside one transaction, rolled
+// back on a throw. Returns { result } or { error }.
+async function runLegacyTx(db, fn) {
+  await db.client.query('BEGIN');
+  try {
+    const result = await fn(db.client);
+    await db.client.query('COMMIT');
+    return { result };
+  } catch (error) {
+    await db.client.query('ROLLBACK');
+    return { error };
+  }
+}
+async function runNew(fn) {
+  try { return { result: await fn() }; } catch (error) { return { error }; }
+}
+const errShape = (e) => (e ? { code: e.code, taskId: e.taskId, taskTitle: e.taskTitle, goalId: e.goalId, toGoalId: e.toGoalId, targetStatus: e.targetStatus } : null);
+
+// ---- goal archive ------------------------------------------------------------
+
+const ARCHIVE_SEED = {
+  goals: [
+    { id: 7, version_id: 'V1', title: 'the goal being archived', status: 'open' },
+    { id: 8, version_id: 'V1', title: 'a neighbour', status: 'open' },
+    { id: 9, version_id: 'V1', title: 'an open move target', status: 'open' },
+    { id: 10, version_id: 'V1', title: 'a closed move target', status: 'archived' },
+  ],
+  tasks: [
+    { id: 1, goal_id: 7, version_id: 'V1', status: 'ready', title: 'one', value_summary: null },
+    { id: 2, goal_id: 7, version_id: 'V1', status: 'shipped', title: 'two', value_summary: null },
+    { id: 3, goal_id: 8, version_id: 'V1', status: 'ready', title: 'three (elsewhere)', value_summary: null },
+    { id: 4, goal_id: 7, version_id: 'V1', status: 'active', title: 'four (claimed)', value_summary: null },
+    { id: 5, goal_id: 7, version_id: 'V1', status: 'backlog', title: 'five', value_summary: null },
+    { id: 6, goal_id: 7, version_id: 'V1', status: 'ready', title: 'six', value_summary: null },
+  ],
+  claims: [{ id: 99, task_id: 4, released_at: null }, { id: 98, task_id: 6, released_at: '2026-01-01' }],
+  nextGoalId: 100,
+};
+
+const ARCHIVE_PLANS = {
+  'mixed verbs, skips and a move': [
+    { taskId: 1, verb: 'abandon' }, { taskId: 2, verb: 'abandon' }, { taskId: 3, verb: 'abandon' },
+    { taskId: 5, verb: 'move', toGoalId: 9 }, { taskId: 6, verb: 'abandon' },
+  ],
+  'plan order is not id order': [{ taskId: 6, verb: 'abandon' }, { taskId: 1, verb: 'move', toGoalId: 9 }, { taskId: 5, verb: 'abandon' }],
+  'a task named twice reads what the first step left': [
+    { taskId: 1, verb: 'abandon' }, { taskId: 1, verb: 'abandon' },
+    { taskId: 5, verb: 'move', toGoalId: 9 }, { taskId: 5, verb: 'abandon' },
+  ],
+  'ids as strings, as a JSON body carries them': [{ taskId: '1', verb: 'abandon' }, { taskId: '5', verb: 'move', toGoalId: '9' }],
+  'an actively claimed task stops it, after earlier steps': [{ taskId: 1, verb: 'abandon' }, { taskId: 4, verb: 'abandon' }, { taskId: 6, verb: 'abandon' }],
+  'a closed move target stops it': [{ taskId: 1, verb: 'abandon' }, { taskId: 5, verb: 'move', toGoalId: 10 }],
+  'a missing move target stops it': [{ taskId: 5, verb: 'move', toGoalId: 404 }],
+  'a task that does not exist is skipped': [{ taskId: 777, verb: 'abandon' }, { taskId: 6, verb: 'abandon' }],
+  'an empty plan': [],
+};
+
+for (const [name, plan] of Object.entries(ARCHIVE_PLANS)) {
+  test(`goal archive, old loop vs batched: ${name}`, async () => {
+    const args = { goalId: 7, plan, reason: 'cut in review' };
+    const oldDb = fakeDb(ARCHIVE_SEED);
+    const old = await runLegacyTx(oldDb, (c) => legacy.legacyArchiveLoop(c, args));
+    const neuDb = fakeDb(ARCHIVE_SEED);
+    const neu = await runNew(() => archiveGoalWithDispositions(args, { pool: neuDb.pool }));
+
+    assert.deepEqual(errShape(neu.error), errShape(old.error), 'the same refusal, naming the same task');
+    if (!old.error) assert.deepEqual(neu.result.applied, old.result, 'the same applied list, in plan order');
+    assert.deepEqual(neuDb.state.tasks, oldDb.state.tasks, 'the same tasks left behind');
+  });
+}
+
+test('goal archive reads every plan task in ONE locked statement and the claims in one more', async () => {
+  const db = fakeDb(ARCHIVE_SEED);
+  await archiveGoalWithDispositions({ goalId: 7, plan: ARCHIVE_PLANS['mixed verbs, skips and a move'], reason: 'r' }, { pool: db.pool });
+  assert.equal(db.queries.filter((q) => /FROM tasks WHERE id = ANY/.test(q)).length, 1);
+  assert.equal(db.queries.filter((q) => /FROM claims WHERE task_id/.test(q)).length, 1);
+  assert.equal(db.queries.filter((q) => /FROM tasks WHERE id = \$1/.test(q)).length, 0, 'no per-step read is left');
+});
+
+// ---- version close -----------------------------------------------------------
+
+const CLOSE_SEED = {
+  goals: [
+    { id: 1, version_id: 'V1', title: 'g1', status: 'open', succeeded_by_goal_id: null },
+    { id: 2, version_id: 'V1', title: 'g2', status: 'open', succeeded_by_goal_id: null },
+    { id: 3, version_id: 'V1', title: 'g3 (already closed)', status: 'archived', succeeded_by_goal_id: null },
+    { id: 4, version_id: 'V9', title: 'g4 (another version)', status: 'open', succeeded_by_goal_id: null },
+    { id: 5, version_id: 'V1', title: 'g5', status: 'open', succeeded_by_goal_id: null },
+  ],
+  tasks: [
+    { id: 11, goal_id: 1, version_id: 'V1', status: 'ready', title: 'a', value_summary: null },
+    { id: 12, goal_id: 1, version_id: 'V1', status: 'shipped', title: 'b', value_summary: 'done' },
+    { id: 13, goal_id: 1, version_id: 'V1', status: 'ready', title: '__smoke__ fixture', value_summary: null },
+    { id: 21, goal_id: 2, version_id: 'V1', status: 'backlog', title: 'c', value_summary: null },
+    { id: 22, goal_id: 2, version_id: 'V1', status: 'active', title: 'd', value_summary: null },
+    { id: 51, goal_id: 5, version_id: 'V1', status: 'ready', title: 'e', value_summary: null },
+  ],
+  claims: [],
+  nextGoalId: 100,
+};
+
+const CLOSE_CASES = {
+  'abandon and roll forward, with skips': {
+    plan: [{ goalId: 1, verb: 'abandon' }, { goalId: 3, verb: 'abandon' }, { goalId: 4, verb: 'roll_forward' }, { goalId: 2, verb: 'roll_forward' }],
+    planningVersionId: 'V2',
+  },
+  'plan order is not id order': {
+    plan: [{ goalId: 5, verb: 'roll_forward' }, { goalId: 2, verb: 'abandon' }, { goalId: 1, verb: 'roll_forward' }],
+    planningVersionId: 'V2',
+  },
+  'a goal named twice reads archived the second time': {
+    plan: [{ goalId: 1, verb: 'abandon' }, { goalId: 1, verb: 'roll_forward' }, { goalId: 2, verb: 'roll_forward' }, { goalId: 2, verb: 'abandon' }],
+    planningVersionId: 'V2',
+  },
+  'ids as strings': { plan: [{ goalId: '2', verb: 'abandon' }, { goalId: '5', verb: 'roll_forward' }], planningVersionId: 'V2' },
+  'a roll forward with no planning version throws after earlier steps': {
+    plan: [{ goalId: 1, verb: 'abandon' }, { goalId: 2, verb: 'roll_forward' }],
+    planningVersionId: null,
+  },
+  'an empty plan': { plan: [], planningVersionId: 'V2' },
+};
+
+for (const [name, { plan, planningVersionId }] of Object.entries(CLOSE_CASES)) {
+  test(`version close, old loop vs batched: ${name}`, async () => {
+    const args = { versionId: 'V1', plan, reason: 'V1 is done', planningVersionId };
+    const oldDb = fakeDb(CLOSE_SEED);
+    const old = await runLegacyTx(oldDb, (c) => legacy.legacyCloseLoop(c, args));
+    const neuDb = fakeDb(CLOSE_SEED);
+    const neu = await runNew(() => closeVersion(args, { pool: neuDb.pool }));
+
+    assert.deepEqual(errShape(neu.error), errShape(old.error), 'the same refusal');
+    if (!old.error) assert.deepEqual(neu.result.applied, old.result, 'the same applied list, in plan order');
+    assert.deepEqual(neuDb.state.goals, oldDb.state.goals, 'the same goals, successors included');
+    assert.deepEqual(neuDb.state.tasks, oldDb.state.tasks, 'the same tasks');
+  });
+}
+
+test('version close locks every plan goal in ONE statement, in id order', async () => {
+  const db = fakeDb(CLOSE_SEED);
+  await closeVersion({ versionId: 'V1', plan: CLOSE_CASES['plan order is not id order'].plan, reason: 'r', planningVersionId: 'V2' }, { pool: db.pool });
+  const locks = db.queries.filter((q) => /FROM goals WHERE id = ANY\(\$1::bigint\[\]\) AND version_id = \$2 ORDER BY id FOR UPDATE/.test(q));
+  assert.equal(locks.length, 1);
+  assert.equal(db.queries.filter((q) => /FROM goals WHERE id = \$1 AND version_id/.test(q)).length, 0, 'no per-step lock is left');
+});
+
+// ---- weekly karma tally ------------------------------------------------------
+
+const TALLY_SEED = {
+  goals: [], tasks: [], claims: [], nextGoalId: 1, karma: [],
+  peerVotes: [
+    { id: 1, builder_id: 30, vote: 1 }, { id: 2, builder_id: 10, vote: 1 }, { id: 3, builder_id: 30, vote: 1 },
+    { id: 4, builder_id: 20, vote: 1 }, { id: 5, builder_id: 20, vote: -1 }, // nets to zero: no row
+    { id: 6, builder_id: 40, vote: -1 },
+  ],
+  ideaVotes: [{ id: 7, builder_id: 10, vote: 1 }, { id: 8, builder_id: 50, vote: 1 }],
+};
+
+async function withFakePool(db, fn) {
+  const had = Object.prototype.hasOwnProperty.call(pgPool, 'connect');
+  const real = pgPool.connect;
+  pgPool.connect = db.pool.connect;
+  try { return await fn(); } finally { if (had) pgPool.connect = real; else delete pgPool.connect; }
+}
+const fakeWithTx = (db) => async (fn) => {
+  await db.client.query('BEGIN');
+  try { const r = await fn(db.client); await db.client.query('COMMIT'); return r; } catch (e) { await db.client.query('ROLLBACK'); throw e; }
+};
+
+for (const [name, seed] of Object.entries({
+  'task and idea votes, a zero net, first-seen order': TALLY_SEED,
+  'no ideas module': { ...TALLY_SEED, ideaVotes: null },
+  'nothing matured': { ...TALLY_SEED, peerVotes: [], ideaVotes: [] },
+})) {
+  test(`weekly karma tally, old loop vs batched: ${name}`, async () => {
+    const oldDb = fakeDb(seed);
+    const old = await legacy.legacyTallyPeerVotes(fakeWithTx(oldDb));
+    const neuDb = fakeDb(seed);
+    const neu = await withFakePool(neuDb, () => tallyPeerVotes());
+
+    assert.deepEqual(neu, old, 'the same reply');
+    assert.deepEqual(neuDb.state.karma, oldDb.state.karma, 'the same karma_log rows, in the same order');
+    assert.deepEqual(neuDb.state.peerVotes, oldDb.state.peerVotes, 'the same votes stamped');
+    assert.deepEqual(neuDb.state.ideaVotes, oldDb.state.ideaVotes);
+  });
+}
+
+test('the tally writes every credited builder in ONE insert', async () => {
+  const db = fakeDb(TALLY_SEED);
+  const r = await withFakePool(db, () => tallyPeerVotes());
+  assert.equal(r.builders_credited, 4);
+  assert.equal(db.queries.filter((q) => /^INSERT INTO karma_log/.test(q)).length, 1);
+});

package/tests/blockers_people.mjs

@@ -0,0 +1,198 @@
+// tests/blockers_people.mjs — open blockers UNDER THE PEOPLE they wait on (task 1004999).
+//
+// WHAT IT GUARDS.
+//   * Every route the City carries now names the PEOPLE in its seat, not only the seat.
+//   * groupByPerson lists each open blocker under every person its seat resolves to,
+//     with the City's own rule (seatOf → resolveSeat): owner, a seated Lead, an
+//     unseated building falling to the owner, a board's members, and nobody.
+//   * The grouping and the City agree on every blocker — they are one rule.
+//   * Seating a different Lead moves the blocker with nothing on the blocker edited.
+//   * blockersByPerson reads the real contributed source, its asks and the seats.
+//   * The hall draws it: the viewer first as "You", the seat in words, "Nobody yet",
+//     escaping, and the City card's "waits on Lars, the owner".
+//
+// DB-free: the government db reads, the resolver and the asks read are stubbed.
+// Run:  node --test tests/blockers_people.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const gov = (f) => path.join(ROOT, 'modules', 'government', f);
+const routing = require(gov('routing.js'));
+const waiting = require(gov('waiting.js'));
+const leads = require(gov('leads.js'));
+const people = require(path.join(ROOT, 'modules', 'hall-ui', 'public', 'blockers-by-person.js'));
+
+const NOW = Date.parse('2026-10-29T12:00:00Z');
+const ARCHONS = [{ id: 1, github_login: 'lars', display_name: 'Lars' }];
+const owner = leads.ownerOf(ARCHONS);
+const planningLead = { id: 9, building: 'planning', builder_id: 42, github_login: 'ana', display_name: 'Ana', removed_at: null };
+const releaseLead = { id: 10, building: 'release', builder_id: 43, github_login: 'ben', display_name: 'Ben', removed_at: null };
+const ask = (waitsOn) => ({ question: 'Allow it?', waits_on: waitsOn, if_nobody_answers: 'It stays stuck.' });
+const blocker = (id, over = {}) => ({
+  id: `blockers:${id}`, source: 'blockers', building: 'planning', state: 'needs', title: `Blocker ${id}`,
+  opened_at: `2026-10-2${id % 10}T00:00:00Z`, deadline: null, href: `/blockers#blocker-${id}`, ref: { type: 'blocker', id: String(id) }, ...over,
+});
+
+test('a route names the people in its seat, not only the seat', () => {
+  const seats = { leads: [planningLead], owner, holders: { charter: [{ builder_id: 7, github_login: 'cy', display_name: 'Cy' }, { builder_id: 8, github_login: 'di' }] } };
+  const byOwner = routing.routeMatter(blocker(1, { ask: ask('owner') }), '1', seats, NOW);
+  assert.deepEqual(byOwner.people, [{ id: '1', login: 'lars', name: 'Lars' }]);
+  const byLead = routing.routeMatter(blocker(2), '1', seats, NOW);
+  assert.equal(byLead.seat, 'lead:planning');
+  assert.deepEqual(byLead.people, [{ id: '42', login: 'ana', name: 'Ana' }]);
+  const unseated = routing.routeMatter(blocker(3, { building: 'treasury' }), '1', seats, NOW);
+  assert.deepEqual([unseated.seat, unseated.fell_to_owner, unseated.people.map((p) => p.name)], ['owner', true, ['Lars']]);
+  const board = routing.routeMatter(blocker(4, { ask: ask('board:charter') }), '1', seats, NOW);
+  assert.deepEqual(board.people, [{ id: '7', login: 'cy', name: 'Cy' }, { id: '8', login: 'di', name: 'di' }]);
+});
+
+test('the name map is built once per request: routeMatter takes it, and routeAll gives the same routes', () => {
+  const seats = { leads: [planningLead], owner, holders: {} };
+  // a passed map is the one used — so routeAll can hand every matter the one it built
+  const dir = new Map([['42', { id: '42', login: 'x', name: 'From the map' }]]);
+  assert.deepEqual(routing.routeMatter(blocker(1), '1', seats, NOW, dir).people, [{ id: '42', login: 'x', name: 'From the map' }]);
+  const ms = [blocker(1), blocker(2, { ask: ask('owner') }), blocker(3, { building: 'treasury' })];
+  const one = ms.map((m) => routing.routeMatter(m, '42', seats, NOW));
+  const all = ms.map((m) => ({ ...m }));
+  routing.routeAll(all, '42', seats, NOW);
+  assert.deepEqual(all.map((m) => m.route), one);
+  const src = fs.readFileSync(gov('routing.js'), 'utf8');
+  const body = src.slice(src.indexOf('function routeAll'), src.indexOf('\n}', src.indexOf('function routeAll')));
+  assert.match(body, /const dir = directoryOf\(ctx\);[\s\S]*routeMatter\(m, viewerId, ctx, now, dir\)/, 'built once, outside the loop');
+});
+
+test('groupByPerson: each blocker under every person its seat resolves to; nobody is never dropped', () => {
+  const seats = { leads: [planningLead], owner, holders: { charter: [{ builder_id: 7, display_name: 'Cy' }, { builder_id: 42, display_name: 'Ana' }], rules: [] } };
+  const matters = [
+    blocker(1, { ask: ask('owner') }),
+    blocker(2), // ask-less → lead:planning → Ana
+    blocker(3, { building: 'treasury' }), // unseated → the owner
+    blocker(4, { ask: ask('board:charter') }), // two members
+    blocker(5, { ask: ask('board:rules') }), // nobody seated → falls to the owner
+    blocker(6, { state: 'settled', ask: ask('owner') }), // settled is not waiting
+  ];
+  const g = waiting.groupByPerson(matters, seats);
+  const ids = (name) => g.people.find((x) => x.person.name === name).items.map((i) => i.id);
+  assert.deepEqual(ids('Lars'), ['1', '3', '5']);
+  assert.deepEqual(ids('Ana'), ['2', '4']);
+  assert.deepEqual(ids('Cy'), ['4']);
+  assert.deepEqual(g.people.map((p) => [p.person.name, p.count]), [['Lars', 3], ['Ana', 2], ['Cy', 1]], 'most waiting first');
+  const two = g.people.find((x) => x.person.name === 'Ana').items.find((i) => i.id === '2');
+  assert.deepEqual([two.seat, two.as, two.asked, two.fell_to_owner], ['lead:planning', 'the Planning Lead', 'lead:planning', false]);
+  const three = g.people.find((x) => x.person.name === 'Lars').items.find((i) => i.id === '3');
+  assert.deepEqual([three.seat, three.asked, three.fell_to_owner], ['owner', 'lead:treasury', true]);
+  // no owner at all: an owner-seat blocker waits on nobody, and is listed there
+  const empty = waiting.groupByPerson([blocker(1, { ask: ask('owner') })], { leads: [], owner: leads.ownerOf([]), holders: {} });
+  assert.deepEqual([empty.people.length, empty.nobody.map((i) => i.id)], [0, ['1']]);
+});
+
+test('the grouping and the City agree on every blocker', () => {
+  const seats = { leads: [planningLead, releaseLead], owner, holders: { charter: [{ builder_id: 7, display_name: 'Cy' }] } };
+  const matters = [blocker(1), blocker(2, { ask: ask('owner') }), blocker(3, { ask: ask('lead:release') }), blocker(4, { ask: ask('board:charter') }), blocker(5, { building: 'people' }), blocker(6, { ask: ask('committee:release.ops') })];
+  const g = waiting.groupByPerson(matters, seats);
+  for (const m of matters) {
+    const city = routing.routeMatter(m, null, seats, NOW).people.map((p) => p.id).sort();
+    const here = g.people.filter((x) => x.items.some((i) => i.matter_id === m.id)).map((x) => x.person.id).sort();
+    assert.deepEqual(here, city, `${m.id}: the same people on both`);
+  }
+});
+
+test('seating a different Lead moves the blocker; nothing on the blocker changes', () => {
+  const m = [blocker(1)];
+  const before = waiting.groupByPerson(m, { leads: [planningLead], owner, holders: {} });
+  const after = waiting.groupByPerson(m, { leads: [{ ...planningLead, builder_id: 77, github_login: 'eve', display_name: 'Eve' }], owner, holders: {} });
+  assert.deepEqual(before.people.map((p) => p.person.name), ['Ana']);
+  assert.deepEqual(after.people.map((p) => p.person.name), ['Eve']);
+  const removed = waiting.groupByPerson(m, { leads: [{ ...planningLead, removed_at: '2026-10-28T00:00:00Z' }], owner, holders: {} });
+  assert.deepEqual(removed.people.map((p) => p.person.name), ['Lars'], 'a removed Lead hands it back to the owner');
+});
+
+test('forViewer: the viewer\'s own group, or an empty one', () => {
+  const g = waiting.groupByPerson([blocker(1), blocker(2, { ask: ask('owner') })], { leads: [planningLead], owner, holders: {} });
+  assert.deepEqual(waiting.forViewer(g, 42).items.map((i) => i.id), ['1']);
+  assert.deepEqual(waiting.forViewer(g, '1').items.map((i) => i.id), ['2']);
+  assert.deepEqual([waiting.forViewer(g, 5).count, waiting.forViewer(g, 5).items], [0, []]);
+});
+
+test('blockersByPerson reads the contributed blockers, their asks and the seats', async () => {
+  const docket = require(gov('docket.js'));
+  const resolver = require(gov('resolver.js'));
+  const asksDb = require(gov('asks-db.js'));
+  const db = require(gov('db.js'));
+  const real = { perms: resolver.resolveBuilderPermissions, asks: asksDb.asksFor, leads: db.listLeads, archons: db.listActiveArchons };
+  resolver.resolveBuilderPermissions = async () => ['board.vote.cast'];
+  asksDb.asksFor = async (ids) => new Map(ids.filter((id) => id === 'blockers:7').map((id) => [id, ask('owner')]));
+  db.listLeads = async () => [planningLead];
+  db.listActiveArchons = async () => ARCHONS;
+  const rows = [{ id: 7, title: 'Token needs the workflow scope', created_at: '2026-10-29T10:00:00Z' }, { id: 8, title: 'Pick a host', created_at: '2026-10-28T10:00:00Z' }];
+  const contributions = { sources: new Map([['blockers', { source: 'blockers', building: 'planning', gate: { anyBuilder: true }, read: async () => rows.map((b) => ({ id: b.id, title: b.title, state: 'needs', opened_at: b.created_at, href: `/blockers#blocker-${b.id}`, ref: { type: 'blocker', id: b.id } })) }]]) };
+  try {
+    const r = await docket.blockersByPerson({ id: 42, rank: 'metic' }, { contributions, now: NOW });
+    assert.equal(r.available, true);
+    assert.deepEqual(r.people.map((p) => [p.person.name, p.items.map((i) => i.id)]), [['Ana', ['8']], ['Lars', ['7']]]);
+    assert.deepEqual(r.yours.items.map((i) => i.id), ['8'], 'Ana sees her own');
+    const off = await docket.blockersByPerson({ id: 42 }, { contributions: { sources: new Map() }, now: NOW });
+    assert.deepEqual([off.available, off.reason, off.people], [false, 'off', []], 'no source is said, not shown as empty');
+    db.listLeads = async () => { throw new Error('db down'); };
+    const down = await docket.blockersByPerson({ id: 42 }, { contributions, now: NOW });
+    assert.deepEqual([down.available, down.reason], [false, 'unavailable'], 'a failed seats read groups nothing rather than guessing');
+  } finally {
+    resolver.resolveBuilderPermissions = real.perms; asksDb.asksFor = real.asks; db.listLeads = real.leads; db.listActiveArchons = real.archons;
+  }
+});
+
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const fmtDate = (iso) => iso.slice(0, 10);
+
+test('the Blockers page: the viewer first as "You", the seat in words, "Nobody yet", escaped', () => {
+  const g = waiting.groupByPerson([
+    blocker(1, { ask: ask('owner'), title: '<b>Token</b>' }),
+    blocker(2), blocker(3, { building: 'treasury' }),
+    blocker(4, { ask: ask('board:rules') }),
+  ], { leads: [planningLead], owner: leads.ownerOf([]), holders: { rules: [] } });
+  const html = people.peopleHtml({ available: true, ...g }, { esc, fmtDate, viewerId: 42, blockerHref: (id) => `#/blocker/${id}` });
+  assert.ok(html.indexOf('>You<') < html.indexOf('>Nobody yet<'), 'the viewer first');
+  assert.match(html, /as the Planning Lead · filed 2026-10-22/);
+  assert.match(html, /href="#\/blocker\/2"/);
+  assert.match(html, /&lt;b&gt;Token&lt;\/b&gt;/, 'a title is escaped');
+  assert.ok(!html.includes('<b>Token'), 'never raw');
+  assert.equal(people.peopleHtml({ available: false, people: [], nobody: [] }, { esc, fmtDate }), '', 'unavailable draws nothing');
+  assert.equal(people.peopleHtml({ available: true, people: [], nobody: [] }, { esc, fmtDate }), '', 'nothing open draws nothing');
+  assert.equal(people.asWords({ as: 'the owner', asked: 'lead:treasury', fell_to_owner: true }), 'as the owner, since Treasury has no Lead');
+  assert.equal(people.asWords({ as: 'the owner', asked: 'owner', fell_to_owner: false }), 'as the owner');
+});
+
+test('Collab\'s block draws only the viewer\'s own, and nothing when nothing waits', () => {
+  const mine = { available: true, count: 1, items: [{ id: '9', title: 'Pick a host', as: 'the Planning Lead', asked: 'lead:planning', opened_at: '2026-10-28T00:00:00Z' }] };
+  const html = people.mineHtml(mine, { esc, fmtDate, blockerHref: (id) => `#/blocker/${id}` });
+  assert.match(html, /Pick a host/);
+  assert.match(html, /as the Planning Lead/);
+  assert.equal(people.mineHtml({ available: true, count: 0, items: [] }, { esc, fmtDate }), '');
+  assert.equal(people.mineHtml(null, { esc, fmtDate }), '');
+});
+
+test('the pages carry the sections and load the script', () => {
+  const pub = (f) => fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', f), 'utf8');
+  assert.match(pub('blockers.html'), /id="blockers-people-scroll"[^>]*hidden/);
+  assert.match(pub('blockers.html'), /<script src="\/builders\/blockers-by-person.js"><\/script>/);
+  assert.match(pub('collab.html'), /id="cb-blockers-scroll"[^>]*hidden/);
+  assert.match(pub('collab.html'), /<script src="\/builders\/blockers-by-person.js"><\/script>/);
+});
+
+test('the City card says who: "waits on Lars, the owner"', () => {
+  const deck = require(path.join(ROOT, 'modules', 'hall-ui', 'public', 'street-deck.js'));
+  const who = deck.whoWords;
+  assert.equal(who({ label: 'the owner', people: [{ name: 'Lars' }] }), 'Lars, the owner');
+  assert.equal(who({ label: 'the board', people: [{ name: 'Cy' }, { login: 'di' }] }), 'Cy and di, the board');
+  assert.equal(who({ label: 'the board', people: [{ name: 'A' }, { name: 'B' }, { name: 'C' }] }), 'A and 2 others, the board');
+  assert.equal(who({ label: 'the owner', people: [] }), 'the owner', 'nobody named: the seat alone');
+  const foot = deck.footOf({ waits_on: { real: true, label: 'the Planning Lead', people: [{ name: 'Ana' }] } }, '');
+  assert.equal(foot.rest, 'It waits on Ana, the Planning Lead.');
+});