@bongos/core 1.21.4 → 1.21.6

package/modules/government/docket-vocab.js

@@ -0,0 +1,82 @@
+'use strict';
+
+// modules/government/docket-vocab.js — the Governor City's fixed words: the nine
+// civic buildings in street order, the seven ways a matter is decided, the three
+// states a matter can be in for one viewer, and the six readings (task 1004523,
+// goal 1000125).
+//
+// WHY. The docket (docket.js) is the one server read every Governor City screen
+// draws from — the home city's pins, the street, the building interiors, the
+// floors and the matter cards (tasks 1004524-1004528). Those screens must agree
+// on what a building key, a rule key or a state key MEANS, so the vocabulary is
+// declared once, here, and shipped on the response (`vocabulary`) so a page builds
+// its legend from the server instead of retyping it. The words and their order are
+// the reference design's (docs/design/mocks/governor-city/README.md, "The street"
+// and "Decision glyphs"); a change here is a change to the design of record.
+//
+// Pure data, no requires: browser-side copies are held equal by test, never by
+// hand.
+
+// The nine civic buildings, in the order work moves along the street, each under
+// its street group label.
+const BUILDINGS = Object.freeze([
+  Object.freeze({ key: 'charter', name: 'Charter', group: 'how we decide' }),
+  Object.freeze({ key: 'rules', name: 'Rules', group: 'how we decide' }),
+  Object.freeze({ key: 'disputes', name: 'Disputes', group: 'how we decide' }),
+  Object.freeze({ key: 'people', name: 'People', group: 'who and what' }),
+  Object.freeze({ key: 'planning', name: 'Planning', group: 'who and what' }),
+  Object.freeze({ key: 'automation', name: 'Automation', group: 'the work' }),
+  Object.freeze({ key: 'review', name: 'Review', group: 'checks and going live' }),
+  Object.freeze({ key: 'release', name: 'Release', group: 'checks and going live' }),
+  Object.freeze({ key: 'treasury', name: 'Treasury', group: 'money' }),
+]);
+const BUILDING_KEYS = Object.freeze(BUILDINGS.map((b) => b.key));
+
+// How a matter is decided — the seven decision glyphs.
+const RULES = Object.freeze([
+  Object.freeze({ key: 'decide', words: 'one person decides' }),
+  Object.freeze({ key: 'first', words: 'first yes wins' }),
+  Object.freeze({ key: 'consent', words: 'passes unless someone objects' }),
+  Object.freeze({ key: 'majority', words: 'more than half must say yes' }),
+  Object.freeze({ key: 'unanimous', words: 'everyone has to agree' }),
+  Object.freeze({ key: 'signoff', words: 'signed off by someone who did not build it' }),
+  Object.freeze({ key: 'rule', words: 'settled by a rule' }),
+]);
+const RULE_KEYS = Object.freeze(RULES.map((r) => r.key));
+
+// The board's pass rules (config.js PASS_RULES) in the city's words. An unknown
+// pass rule maps to null — the card then says the rule is not one it knows,
+// rather than drawing the nearest glyph.
+const PASS_RULE_TO_RULE = Object.freeze({
+  first_ratifier: 'first',
+  consent: 'consent',
+  majority: 'majority',
+  unanimous: 'unanimous',
+});
+
+// A matter's state for ONE viewer. Exactly one applies (README "Pins").
+//   needs   — waits on the viewer's own act
+//   moving  — open, and moving without the viewer (they acted, or it is a call
+//             they share that is not theirs to make right now)
+//   settled — decided, or not the viewer's to act on
+const STATES = Object.freeze(['needs', 'moving', 'settled']);
+
+// The six readings on the street's footer, each a door to the building it reads.
+const READINGS = Object.freeze([
+  Object.freeze({ key: 'flow', label: 'flow', building: 'review' }),
+  Object.freeze({ key: 'promises', label: 'promises', building: 'planning' }),
+  Object.freeze({ key: 'money', label: 'money', building: 'treasury' }),
+  Object.freeze({ key: 'people', label: 'people', building: 'people' }),
+  Object.freeze({ key: 'fairness', label: 'fairness', building: 'disputes' }),
+  Object.freeze({ key: 'rules', label: 'rules at work', building: 'rules' }),
+]);
+
+module.exports = {
+  BUILDINGS,
+  BUILDING_KEYS,
+  RULES,
+  RULE_KEYS,
+  PASS_RULE_TO_RULE,
+  STATES,
+  READINGS,
+};

package/modules/government/docket.js

@@ -0,0 +1,458 @@
+'use strict';
+
+// modules/government/docket.js — the governor's docket: ONE read of every matter
+// waiting on, or moving for, a governor, plus the six readings (task 1004523,
+// goal 1000125, the Governor City).
+//
+// WHY. The Governor City (docs/design/mocks/governor-city/, Street.dc.html's
+// matters() / status() / signsOf()) draws every part of a project's government
+// as a building, with a pin over each open matter. Before this file the matters
+// lived in a dozen places — the board, blockers, access requests, override
+// requests, removal proposals, red-team reports, criteria awaiting UAT, the core
+// update, CI gate approvals, the Autobongos fence, goal join requests — and the
+// only cross-source summary was a browser card fetching five of them one by one.
+// The screen tasks (1004524 home city, 1004525 street, 1004526 interiors, 1004527
+// floors, 1004528 matter cards) all read THIS instead, so they agree on what is
+// open, where it sits and whose move it is.
+//
+// HOW A SOURCE GETS HERE: THE `governor.docket` CONTRIBUTION POINT. A module may
+// not require a sibling (ADR 0083), and the sources live in five modules and the
+// core. So each owner contributes its own source, built on its OWN existing db
+// read, with `api.contribute('governor.docket', { … })` from its route factory —
+// and this file collects them. The contract (validated here, fail-closed):
+//
+//   { source:   'blockers',                   // unique key (EXPECTED_SOURCES)
+//     building: 'planning',                   // one of docket-vocab BUILDING_KEYS
+//     gate:     { permission: 'blocker.review' }   // hidden unless the viewer holds it
+//            |  { anyBuilder: true },                // the read scopes itself to the viewer
+//     read:     async (ctx) => [matter, …] }
+//
+//   { reading: 'flow', gate: …, read: async (ctx) => { figure, line, value, hot } }
+//
+// `ctx` is { builderId, rank, has(permission) } — `has` answers from the
+// viewer's permission set resolved ONCE for this request, server-side and
+// uncached (ADR 0016). A contribution with no recognisable gate is DROPPED, never
+// run: an unscoped source would show every viewer everything.
+//
+// RANK-SCOPED SERVER-SIDE. The gate a source declares is the SAME atom its own
+// list route requires, so the docket can never show a viewer a matter its owning
+// route would refuse them. A gated-out source is reported as `not_yours` with no
+// rows — the screen can say a building has matters you cannot see without
+// leaking them.
+//
+// NOTHING IS INVENTED. A source the design names that has no data yet (grade
+// appeals, votes on new standing rules, the treasury's spending matters) is
+// reported `coming`; a source whose module is off is `off`; a read that throws or
+// times out is `unavailable`. None of them ever contributes a sample row.
+
+const api = require('../../src/module-api');
+const vocab = require('./docket-vocab');
+const board = require('./board');
+const db = require('./db');
+const { resolveBoardMembers } = require('./board-membership');
+const resolver = require('./resolver');
+
+const log = api.logger('government');
+
+const CONTRIBUTION_POINT = 'governor.docket';
+
+// Every source the reference design names, with the building it stands in. The
+// docket reports a status for each, so a screen never has to guess whether an
+// empty building is empty or unbuilt.
+const EXPECTED_SOURCES = Object.freeze([
+  Object.freeze({ source: 'board', building: 'charter', label: 'board sittings' }),
+  Object.freeze({ source: 'blockers', building: 'planning', label: 'blockers' }),
+  Object.freeze({ source: 'access_requests', building: 'people', label: 'access requests' }),
+  Object.freeze({ source: 'goal_join_requests', building: 'people', label: 'goal join requests' }),
+  Object.freeze({ source: 'override_requests', building: 'release', label: 'override requests' }),
+  Object.freeze({ source: 'removal_proposals', building: 'disputes', label: 'removal proposals' }),
+  Object.freeze({ source: 'redteam_reports', building: 'disputes', label: 'red-team reports' }),
+  Object.freeze({ source: 'criteria_uat', building: 'review', label: 'criteria awaiting UAT' }),
+  Object.freeze({ source: 'core_update', building: 'release', label: 'core update' }),
+  Object.freeze({ source: 'gate_approvals', building: 'release', label: 'CI gate approvals' }),
+  Object.freeze({ source: 'autobongos_fence', building: 'automation', label: 'the Autobongos fence' }),
+  Object.freeze({ source: 'module_rechecks', building: 'release', label: 'module re-checks' }),
+]);
+
+// Named by the design, not yet recorded anywhere. Each says why, in words.
+const COMING_SOURCES = Object.freeze([
+  Object.freeze({ source: 'grade_appeals', building: 'disputes', label: 'grade appeals',
+    reason: 'There is no way to appeal a grade yet.' }),
+  Object.freeze({ source: 'standing_rules', building: 'rules', label: 'standing rules',
+    reason: 'A new standing rule has nowhere to be proposed yet. The one rule in force, idea routing, is counted in the rules-at-work reading.' }),
+  Object.freeze({ source: 'treasury_spending', building: 'treasury', label: 'spending matters',
+    reason: 'The project has no budget or spending votes recorded yet.' }),
+]);
+
+
+// A source read that has not answered by now is reported unavailable rather than
+// holding the whole city hostage (one source calls GitHub, one the npm registry).
+const SOURCE_TIMEOUT_MS = 4000;
+
+// ── pure helpers ──────────────────────────────────────────────────────────────
+
+function iso(v) {
+  if (v == null || v === '') return null;
+  const d = v instanceof Date ? v : new Date(v);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+function person(p) {
+  if (!p || typeof p !== 'object') return null;
+  const id = p.id == null ? null : String(p.id);
+  const login = p.login == null ? null : String(p.login);
+  const name = p.name == null ? null : String(p.name);
+  if (id == null && login == null && name == null) return null;
+  return { id, login, name };
+}
+
+function tally(t) {
+  if (!t || typeof t !== 'object') return null;
+  const n = (x) => (Number.isFinite(Number(x)) ? Number(x) : 0);
+  return {
+    for: n(t.for),
+    against: n(t.against),
+    open: n(t.open),
+    needs: t.needs == null ? null : String(t.needs),
+  };
+}
+
+// One matter as a contributor handed it → the docket's one shape. Pure. Unknown
+// rule → null (the card says so), unknown state → 'moving' (never a false
+// "needs you"), unknown building → the source's own building.
+function normalizeMatter(raw, { source, building }) {
+  if (!raw || typeof raw !== 'object' || raw.id == null || !raw.title) return null;
+  const b = vocab.BUILDING_KEYS.includes(raw.building) ? raw.building : building;
+  return {
+    id: `${source}:${raw.id}`,
+    source,
+    building: b,
+    rule: vocab.RULE_KEYS.includes(raw.rule) ? raw.rule : null,
+    state: vocab.STATES.includes(raw.state) ? raw.state : 'moving',
+    title: String(raw.title),
+    short: raw.short ? String(raw.short) : null,
+    where: raw.where ? String(raw.where) : null,
+    opened_at: iso(raw.opened_at),
+    deadline: iso(raw.deadline),
+    proposer: person(raw.proposer),
+    tally: tally(raw.tally),
+    href: raw.href ? String(raw.href) : null,
+    ref: raw.ref && typeof raw.ref === 'object' ? { type: String(raw.ref.type), id: String(raw.ref.id) } : null,
+  };
+}
+
+// Does this viewer pass this gate? Fail-closed: anything unrecognised is false.
+function gateAllows(gate, ctx) {
+  if (!gate || typeof gate !== 'object') return false;
+  if (gate.anyBuilder === true) return true;
+  if (typeof gate.permission === 'string' && gate.permission) return ctx.has(gate.permission);
+  return false;
+}
+
+function hasValidGate(gate) {
+  return !!gate && typeof gate === 'object'
+    && (gate.anyBuilder === true || (typeof gate.permission === 'string' && !!gate.permission));
+}
+
+// needs first, then by deadline (soonest first, none last), then oldest first.
+const STATE_ORDER = { needs: 0, moving: 1, settled: 2 };
+function compareMatters(a, b) {
+  if (STATE_ORDER[a.state] !== STATE_ORDER[b.state]) return STATE_ORDER[a.state] - STATE_ORDER[b.state];
+  const da = a.deadline ? Date.parse(a.deadline) : Infinity;
+  const dbb = b.deadline ? Date.parse(b.deadline) : Infinity;
+  if (da !== dbb) return da - dbb;
+  const oa = a.opened_at ? Date.parse(a.opened_at) : Infinity;
+  const ob = b.opened_at ? Date.parse(b.opened_at) : Infinity;
+  return oa - ob;
+}
+
+function countStates(matters) {
+  const c = { needs: 0, moving: 0, settled: 0 };
+  for (const m of matters) c[m.state] += 1;
+  return c;
+}
+
+// The home line under "start governing", in the design's words.
+function homeLine(counts) {
+  if (!counts.needs && !counts.moving) return 'nothing waits on you.';
+  const parts = [];
+  if (counts.needs) parts.push(`${counts.needs} ${counts.needs === 1 ? 'matter waits' : 'matters wait'} on you`);
+  if (counts.moving) parts.push(`${counts.moving} moving`);
+  return parts.join(' · ');
+}
+
+// ── the board, read here (this module owns it) ───────────────────────────────
+
+const PASS_RULE_NEEDS = Object.freeze({
+  first_ratifier: 'one yes decides',
+  consent: 'passes unless someone objects',
+  majority: 'needs more than half',
+  unanimous: 'needs everyone who votes',
+});
+
+// One open or recently closed sitting, for one viewer. Pure.
+//
+// "needs" is board.awaitsVoter, the SAME predicate pendingVotesFor (the /me
+// summons) runs — open, not past its deadline, a member under the item's OWN
+// snapshot, not already cast, not the subject's author (a genesis stage has no
+// author to hold back) — so the city never promises a ballot the vote route then
+// refuses, and never disagrees with the roster about it. One definition, held by
+// tests/governor_docket.mjs driving both over the same matrix.
+function boardMatter(item, { viewerId, members }) {
+  const viewer = String(viewerId);
+  const constitution = item.constitution || {};
+  const votes = item.votes || [];
+  const memberIds = new Set((members || []).map((m) => String(m.builder_id)));
+  const voted = votes.some((v) => String(v.voter_id) === viewer);
+  const authorId = item.subject_type === 'genesis_stage'
+    ? null
+    : (item.subject && item.subject.author_id != null ? String(item.subject.author_id) : null);
+  const isOpen = !item.closed_at;
+  let state;
+  if (!isOpen) state = 'settled';
+  else if (board.awaitsVoter({ builderId: viewer, authorId, alreadyVoted: voted, isMember: memberIds.has(viewer), expired: item.expired === true })) state = 'needs';
+  else if (voted || memberIds.has(viewer) || authorId === viewer) state = 'moving';
+  else state = 'settled';
+
+  const building = item.subject_type === 'full_idea' ? 'planning' : 'charter';
+  const title = item.subject_type === 'constitutional_amendment'
+    ? (item.subject && item.subject.rationale_md ? firstLine(item.subject.rationale_md) : 'A change to the charter')
+    : item.subject_type === 'genesis_stage'
+      ? `Close the founding stage: ${(item.subject && item.subject.label) || item.subject_id}`
+      : ((item.subject && item.subject.title) || `Full idea ${item.subject_id}`);
+  const where = item.subject_type === 'constitutional_amendment' ? 'charter · amendment'
+    : item.subject_type === 'genesis_stage' ? 'charter · founding'
+      : 'planning · idea to ratify';
+  const forN = votes.filter((v) => v.direction === 'yes').length;
+  const againstN = votes.filter((v) => v.direction === 'no').length;
+  const castIds = new Set(votes.map((v) => String(v.voter_id)));
+  const open = [...memberIds].filter((id) => !castIds.has(id)).length;
+  const proposerRow = authorId == null ? null
+    : (members || []).find((m) => String(m.builder_id) === authorId)
+      || votes.find((v) => String(v.voter_id) === authorId);
+  return {
+    id: item.id,
+    building,
+    rule: vocab.PASS_RULE_TO_RULE[constitution.pass_rule] || null,
+    state,
+    title,
+    short: item.subject_type === 'constitutional_amendment' ? 'amendment'
+      : item.subject_type === 'genesis_stage' ? 'founding stage' : 'idea to ratify',
+    where,
+    opened_at: item.opened_at,
+    deadline: item.closes_at,
+    proposer: authorId == null ? null : {
+      id: authorId,
+      login: proposerRow ? proposerRow.github_login : null,
+      name: proposerRow ? proposerRow.display_name : null,
+    },
+    tally: { for: forN, against: againstN, open: isOpen ? open : 0, needs: PASS_RULE_NEEDS[constitution.pass_rule] || null },
+    href: `/board-room?item=${encodeURIComponent(item.id)}`,
+    ref: { type: 'board_item', id: item.id },
+  };
+}
+
+function firstLine(md) {
+  const line = String(md).split(/\r?\n/).map((s) => s.replace(/^[#>*\-\s]+/, '').trim()).find(Boolean);
+  if (!line) return 'A change to the charter';
+  return line.length > 120 ? `${line.slice(0, 117)}…` : line;
+}
+
+// A closed sitting stays on the docket as settled for this long, so a pass is
+// seen once before its pin drops (README: "Passed matters drop their pin").
+const SETTLED_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+// The board source: open sittings + sittings closed in the last week. Members are
+// resolved once per DISTINCT predicate, as pendingVotesFor does.
+async function readBoard(ctx, { now = Date.now() } = {}) {
+  const view = await board.boardRoomView({ closedLimit: 20 });
+  const recent = (view.closed || []).filter((i) => i.closed_at && now - Date.parse(i.closed_at) <= SETTLED_WINDOW_MS);
+  const items = [...(view.open || []), ...recent];
+  const membersBy = new Map();
+  const out = [];
+  for (const item of items) {
+    const key = String((item.constitution || {}).membership || '');
+    if (!membersBy.has(key)) membersBy.set(key, await resolveBoardMembers(item.constitution || {}).catch(() => []));
+    out.push(boardMatter(item, { viewerId: ctx.builderId, members: membersBy.get(key) }));
+  }
+  return out;
+}
+
+const BOARD_SOURCE = Object.freeze({
+  source: 'board',
+  building: 'charter',
+  gate: Object.freeze({ permission: 'board.vote.cast' }),
+  read: readBoard,
+});
+
+// ── readings this module can answer ──────────────────────────────────────────
+
+const OWN_READINGS = Object.freeze([
+  Object.freeze({
+    reading: 'people',
+    gate: Object.freeze({ anyBuilder: true }),
+    read: async () => {
+      const n = await db.countActiveBuilders();
+      return { value: n, figure: `${n} ${n === 1 ? 'builder' : 'builders'}`, line: 'active people in the project', hot: false };
+    },
+  }),
+]);
+
+// Open disputes, from the matters the viewer can see at Disputes. Pure.
+function fairnessReading(matters, sourceStatus) {
+  const seen = sourceStatus.filter((s) => s.building === 'disputes' && s.status === 'live');
+  if (!seen.length) return null;
+  const open = matters.filter((m) => m.building === 'disputes' && m.state !== 'settled');
+  const n = open.length;
+  const oldest = open.map((m) => m.opened_at).filter(Boolean).sort()[0] || null;
+  return {
+    value: n,
+    figure: `${n} open`,
+    line: n ? `${n === 1 ? 'one dispute' : `${n} disputes`} waiting · oldest since ${oldest ? oldest.slice(0, 10) : 'unknown'}` : 'no open disputes',
+    hot: open.some((m) => m.state === 'needs'),
+  };
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), ms); if (timer.unref) timer.unref(); }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+// The registered contributions, last registration per key winning (a route
+// factory re-runs whenever a test rebuilds the router; the newest closure is the
+// live one).
+function registeredContributions() {
+  const sources = new Map();
+  const readings = new Map();
+  for (const c of api.contributions(CONTRIBUTION_POINT)) {
+    if (!c || typeof c !== 'object' || typeof c.read !== 'function' || !hasValidGate(c.gate)) continue;
+    if (typeof c.source === 'string' && c.source) sources.set(c.source, c);
+    else if (typeof c.reading === 'string' && c.reading) readings.set(c.reading, c);
+  }
+  return { sources, readings };
+}
+
+// ── the collector ────────────────────────────────────────────────────────────
+
+// Build the docket for one viewer. `permissions` is the viewer's resolved set;
+// `contributions` defaults to what is registered on the seam (a test passes its
+// own). Never throws for a source: each is isolated and timed.
+async function buildDocket({ viewer, permissions, contributions = registeredContributions(), now = Date.now(), timeoutMs = SOURCE_TIMEOUT_MS } = {}) {
+  const held = new Set(permissions || []);
+  const ctx = Object.freeze({
+    builderId: String(viewer.id),
+    rank: viewer.rank || null,
+    has: (p) => held.has(p),
+  });
+  const sources = new Map(contributions.sources);
+  sources.set('board', BOARD_SOURCE); // the board is read here, never contributed
+  const comingKeys = new Set(COMING_SOURCES.map((c) => c.source));
+
+  const matters = [];
+  const sourceStatus = [];
+  const declared = [...EXPECTED_SOURCES, ...COMING_SOURCES.filter((c) => !EXPECTED_SOURCES.some((e) => e.source === c.source))];
+  await Promise.all(declared.map(async (decl) => {
+    const c = sources.get(decl.source);
+    const row = { source: decl.source, building: decl.building, label: decl.label, status: null, count: 0, reason: null };
+    sourceStatus.push(row);
+    if (!c) {
+      if (comingKeys.has(decl.source)) {
+        row.status = 'coming';
+        row.reason = COMING_SOURCES.find((x) => x.source === decl.source).reason;
+      } else {
+        row.status = 'off';
+        row.reason = 'The module that holds this is not enabled here.';
+      }
+      return;
+    }
+    if (!gateAllows(c.gate, ctx)) { row.status = 'not_yours'; return; }
+    try {
+      const raw = await withTimeout(Promise.resolve(c.read(ctx, { now })), timeoutMs);
+      const list = (Array.isArray(raw) ? raw : []).map((m) => normalizeMatter(m, { source: decl.source, building: c.building || decl.building })).filter(Boolean);
+      row.status = 'live';
+      row.count = list.length;
+      matters.push(...list);
+    } catch (err) {
+      row.status = 'unavailable';
+      row.reason = err && err.message === 'timeout' ? 'It did not answer in time.' : 'It could not be read just now.';
+      log.warn({ source: decl.source, err: err && err.message }, 'governor docket source failed');
+    }
+  }));
+  // Stable order: the declared order, not the order the reads finished in.
+  const order = declared.map((d) => d.source);
+  sourceStatus.sort((a, b) => order.indexOf(a.source) - order.indexOf(b.source));
+  matters.sort(compareMatters);
+
+  // Readings: contributed + this module's own + the ones derived from matters.
+  const readingImpls = new Map(contributions.readings);
+  for (const r of OWN_READINGS) readingImpls.set(r.reading, r);
+  const readings = await Promise.all(vocab.READINGS.map(async (decl) => {
+    const base = { key: decl.key, label: decl.label, building: decl.building, status: null, value: null, figure: null, line: null, hot: false, reason: null };
+    if (decl.key === 'fairness') {
+      const f = fairnessReading(matters, sourceStatus);
+      return f ? { ...base, status: 'live', ...f } : { ...base, status: 'not_yours' };
+    }
+    const impl = readingImpls.get(decl.key);
+    if (!impl) return { ...base, status: 'off', reason: 'The module that holds this is not enabled here.' };
+    if (!gateAllows(impl.gate, ctx)) return { ...base, status: 'not_yours' };
+    try {
+      const r = await withTimeout(Promise.resolve(impl.read(ctx, { now, matters })), timeoutMs);
+      if (!r) return { ...base, status: 'unavailable', reason: 'It could not be read just now.' };
+      return {
+        ...base,
+        status: 'live',
+        value: r.value ?? null,
+        figure: r.figure == null ? null : String(r.figure),
+        line: r.line == null ? null : String(r.line),
+        hot: r.hot === true,
+      };
+    } catch (err) {
+      log.warn({ reading: decl.key, err: err && err.message }, 'governor docket reading failed');
+      return { ...base, status: 'unavailable', reason: 'It could not be read just now.' };
+    }
+  }));
+
+  const counts = countStates(matters);
+  const buildings = vocab.BUILDINGS.map((b) => {
+    const here = matters.filter((m) => m.building === b.key);
+    return { key: b.key, name: b.name, group: b.group, counts: countStates(here), matter_ids: here.map((m) => m.id) };
+  });
+  return {
+    viewer: { id: ctx.builderId },
+    generated_at: new Date(now).toISOString(),
+    counts,
+    line: homeLine(counts),
+    matters,
+    buildings,
+    sources: sourceStatus,
+    readings,
+    vocabulary: { buildings: vocab.BUILDINGS, rules: vocab.RULES, states: vocab.STATES },
+  };
+}
+
+// The route's entry point: resolve the viewer's permissions server-side (fresh,
+// uncached — ADR 0016), then build.
+async function docketFor(builder) {
+  const permissions = await resolver.resolveBuilderPermissions(builder.id);
+  return buildDocket({ viewer: builder, permissions });
+}
+
+module.exports = {
+  CONTRIBUTION_POINT,
+  EXPECTED_SOURCES,
+  COMING_SOURCES,
+  SOURCE_TIMEOUT_MS,
+  SETTLED_WINDOW_MS,
+  normalizeMatter,
+  gateAllows,
+  compareMatters,
+  homeLine,
+  boardMatter,
+  fairnessReading,
+  registeredContributions,
+  buildDocket,
+  docketFor,
+};

package/modules/government/routes/government.js

@@ -26,6 +26,7 @@ const sessionScopes = require('../session-scopes');
 const boardMembership = require('../board-membership');
 const board = require('../board');
 const recommendations = require('../recommendations');
+const docket = require('../docket');
 // task 1003208: structured logging (pino via the doorway) — was console.*.
 const log = api.logger('government');
 
@@ -531,6 +532,39 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.vote.cast — the governor's DOCKET (task 1004523, goal
+  // 1000125): ONE read of every matter waiting on, or moving for, a governor,
+  // which the Governor City screens all draw from. Same coarse atom as the room
+  // (xenos floor: whoever the constitution may enfranchise may open the city);
+  // the real scoping is PER SOURCE, inside docket.js — each source is shown only
+  // to a viewer holding the same atom its own list route requires, and a hidden
+  // source reports `not_yours` with no rows (ADR 0016, server-side, uncached).
+  //
+  // Response (docket.buildDocket):
+  //   { viewer: { id }, generated_at, line,               // "3 matters wait on you · 2 moving"
+  //     counts: { needs, moving, settled },
+  //     matters: [{ id: '<source>:<id>', source, building, rule, state,
+  //                 title, short, where, opened_at, deadline,
+  //                 proposer: { id, login, name } | null,
+  //                 tally: { for, against, open, needs } | null, href, ref }],
+  //     buildings: [{ key, name, group, counts, matter_ids }],   // street order
+  //     sources:  [{ source, building, label, status, count, reason }],
+  //               // status: live | not_yours | coming | off | unavailable
+  //     readings: [{ key, label, building, status, value, figure, line, hot, reason }],
+  //     vocabulary: { buildings, rules, states } }
+  // `building` ∈ charter rules disputes people planning automation review release
+  // 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.
+  router.get('/government/docket', api.requireBuilder, api.requirePermission('board.vote.cast'), async (req, res) => {
+    try {
+      res.json(await docket.docketFor(req.builder));
+    } catch (err) {
+      log.error('[gds] GET /government/docket', err);
+      res.fail('docket_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.item.open — put an AMENDMENT to the board (R14 of goal
   // 1000069, ADR 0175 §7). The board's other subject never comes through here:
   // a Full Idea's window opens AUTOMATICALLY on grade pass (R07), so requesting