@bongos/core 1.24.29 → 1.24.31

package/modules/lifecycle/home-city.js

@@ -0,0 +1,388 @@
+'use strict';
+
+// modules/lifecycle/home-city.js — the weekly summary behind Home's project city
+// (task 1005054, the owner's Home redesign).
+//
+// WHY. Home became one scene (modules/hall-ui/public/home-city.js): a tower per
+// working area as tall as what has shipped there, a ladder of the week's builders,
+// and a slider that replays the last few weeks. Drawing that from the browser would
+// mean downloading every shipped task, idea and vote and slicing it — the read the
+// hall's bounded-reads rule forbids (modules/hall-ui/CLAUDE.md: a Home card asks
+// the server for what it draws). So it is counted here, in SQL, grouped by week:
+// the response grows with the number of areas, builders and weeks, never with the
+// corpus.
+//
+// WHAT IT ANSWERS, for the last N weeks (Monday-start, UTC; the last is this week):
+//   areas  — each open, non-maintenance goal of the version being built (the focus
+//            version, else the newest one building): what it had shipped before the
+//            window, then per week, split into art (artist and ui work — economy's
+//            credits-by-craft rule) and build, and the builder who shipped most there.
+//   people — per builder per week: tasks shipped (build / art), ideas filed, and
+//            govern acts (board votes cast, blockers resolved).
+//   ideas  — the window's ideas for the sky, newest first, bounded, each with the
+//            goal of the task it became, the area it is aimed at (that goal, else
+//            the filer's suggested goal), the week it became work, its net votes,
+//            and whether it waits on THIS viewer (task 1005059, the ideator's sky:
+//            a new idea no area holds yet, not the viewer's own, that they have not
+//            voted on — "to place or vote on").
+//   people — (as above) plus the idea votes each builder cast per week, for the
+//            ideator's ladder.
+//   version.tasks — every task under the areas, the moon's whole (how far along).
+//   now    — who holds an open claim in each area (an Autobongos runner working it
+//            marks the site as an agent's), and how many matters in each area
+//            wait on THIS viewer.
+//
+// "WAITS ON YOU" IS THE DOCKET'S OWN ANSWER (task 1005056). The government port's
+// yoursByGoal(viewer) routes the docket's goal-shaped matters (blockers, criteria
+// awaiting sign-off, goal join requests) with modules/government/routing.js and
+// counts, per goal, those whose route is the viewer's — so a seated Lead, a board
+// member or an access holder sees their own dots, and the city never disagrees
+// with the docket. The port is resolved optionally (not declared in `consumes`):
+// with government switched off, an older government without the method, or seats
+// it could not read, the city falls back to the old approximation — open blockers
+// whose stored ask waits on `owner` (or that carry none), shown only to an Archon.
+//
+// MODULE BOUNDARY: reaches core only through the published doorway. The ideas,
+// blockers, government and autonomy tables are READ in SQL (a cross-table read
+// crosses the wall, a cross-module require does not — modules/ideas/CLAUDE.md);
+// the two module tables are probed with to_regclass first, so a project with
+// government or autonomy switched off answers without them rather than failing.
+
+const api = require('../../src/module-api');
+
+const log = api.logger('lifecycle');
+
+const MIN_WEEKS = 4;
+const MAX_WEEKS = 26;
+const DEFAULT_WEEKS = 10;
+const MAX_AREAS = 30;
+const MAX_IDEAS = 120;
+const ART_DISCIPLINES = Object.freeze(['artist', 'ui']);
+// modules/ideas/skill-friction.js holds the original; a module may not require a
+// sibling, so the two markers are mirrored here (an Xenos viewer never sees them).
+const SKILL_FRICTION_KIND = 'skill-friction';
+const SKILL_FRICTION_TAG = '[skill-friction]';
+const SMOKE_TITLE = '\\_\\_smoke\\_\\_%';
+
+function clampWeeks(v) {
+  const n = Number.parseInt(v, 10);
+  if (!Number.isFinite(n)) return DEFAULT_WEEKS;
+  return Math.max(MIN_WEEKS, Math.min(MAX_WEEKS, n));
+}
+
+// week index of a timestamp column against the window start ($ref), as SQL
+const wk = (col, ref) => `floor(extract(epoch FROM (${col} - ${ref}::timestamptz)) / 604800)::int`;
+
+async function tableExists(pool, name) {
+  const { rows } = await pool.query('SELECT to_regclass($1) IS NOT NULL AS ok', [`public.${name}`]);
+  return !!(rows[0] && rows[0].ok);
+}
+
+// The project's focus version when one is set, else db-versions.js
+// currentBuildingVersionId's rule (building only, newest started first, id breaks a
+// tie) — the version the roadmap and Goals already lead with.
+async function versionBeingBuilt(pool, deps) {
+  const focus = await (deps.getFocusVersionId || api.projectSettings.getFocusVersionId)().catch(() => null);
+  const { rows } = await pool.query(
+    `SELECT id, name FROM versions
+      WHERE ($1::text IS NOT NULL AND id = $1) OR ($1::text IS NULL AND status = 'building')
+      ORDER BY started_at DESC NULLS LAST, id
+      LIMIT 1`,
+    [focus],
+  );
+  return rows[0] || null;
+}
+
+// The docket's answer, held per viewer for WAITING_TTL_MS. Home is the most-loaded
+// page and the docket's routing is several reads deep, so a reload inside the
+// window costs no reads. The dots are a display count that gates nothing, so the
+// uncached-authority rule (ADR 0016) is untouched; the docket itself stays live.
+// Keyed by port so a swapped port (a test, a reload) never sees another's answers.
+const WAITING_TTL_MS = 30 * 1000;
+const WAITING_MAX = 500;
+const waitingMemo = new WeakMap();
+async function yoursByGoalHeld(gov, viewer, now) {
+  const memo = waitingMemo.get(gov) || new Map();
+  waitingMemo.set(gov, memo);
+  const key = `${viewer.id}:${String(viewer.rank || '').toLowerCase()}`;
+  const hit = memo.get(key);
+  if (hit && now - hit.at < WAITING_TTL_MS) return hit.r;
+  const r = await Promise.resolve().then(() => gov.yoursByGoal(viewer)).catch((err) => {
+    log.warn({ err: err && err.message }, 'home city: the docket could not say what waits on the viewer');
+    return null;
+  });
+  if (r && r.available === true) {
+    if (memo.size >= WAITING_MAX) memo.delete(memo.keys().next().value);
+    memo.set(key, { at: now, r });
+  }
+  return r;
+}
+
+// Per area, how many matters wait on the viewer → [{ goal_id, n }]. The docket's
+// routing through the government port when it answers; else the approximation
+// (Archon only), so Home never loses its dots to a missing or failing port.
+async function waitingOnViewer(pool, goalIds, viewer, deps) {
+  if (!viewer || viewer.id == null) return [];
+  const gov = deps.government !== undefined ? deps.government : api.resolveOptional('government');
+  if (gov && typeof gov.yoursByGoal === 'function') {
+    const r = await yoursByGoalHeld(gov, viewer, deps.now ? deps.now() : Date.now());
+    if (r && r.available === true) {
+      const areas = new Set(goalIds);
+      return Object.entries(r.goals || {})
+        .filter(([goalId, n]) => areas.has(String(goalId)) && Number(n) > 0)
+        .map(([goalId, n]) => ({ goal_id: String(goalId), n: Number(n) }));
+    }
+  }
+  if (String(viewer.rank || '').toLowerCase() !== 'archon') return [];
+  const hasAsks = await tableExists(pool, 'government_asks');
+  return (await pool.query(
+    `SELECT t.goal_id::text AS goal_id, count(DISTINCT b.id)::int AS n
+       FROM blockers b
+       JOIN task_blockers tb ON tb.blocker_id = b.id
+       JOIN tasks t ON t.id = tb.task_id
+       ${hasAsks ? `LEFT JOIN government_asks a ON a.matter_id = 'blockers:' || b.id` : ''}
+      WHERE b.status = 'open' AND t.goal_id = ANY($1::bigint[])
+        ${hasAsks ? `AND (a.matter_id IS NULL OR a.waits_on = 'owner')` : ''}
+      GROUP BY 1`,
+    [goalIds],
+  )).rows;
+}
+
+// → the raw rows, every query bounded by the window, the areas or a LIMIT.
+// The reads that do not depend on each other run together (Promise.all): the
+// window and the version first, then the areas, then everything else at once.
+async function readCity({ weeks, viewer }, deps = {}) {
+  const pool = (deps.pool && process.env.NODE_ENV === 'test') ? deps.pool : api.pool;
+  const N = clampWeeks(weeks);
+  const rank = viewer ? String(viewer.rank || '').toLowerCase() : '';
+  const isArchon = rank === 'archon';
+  const viewerId = viewer && viewer.id != null ? String(viewer.id) : null;
+  const [{ rows: [win] }, version, hasVotes, hasRunners, hasIdeaVotes] = await Promise.all([
+    pool.query(
+      `SELECT ((date_trunc('week', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC') - make_interval(weeks => $1 - 1)) AS start`,
+      [N],
+    ),
+    versionBeingBuilt(pool, deps),
+    tableExists(pool, 'government_board_votes'),
+    tableExists(pool, 'autonomy_runner_heartbeat'),
+    tableExists(pool, 'ideas_votes'),
+  ]);
+  const start = win.start;
+  const out = { N, start, version, areas: [], areaWeeks: [], leads: [], peopleWeeks: [], ideaCounts: [], ideas: [], gov: [], builders: [], sites: [], waiting: [], ideaVotes: [], taskTotal: null };
+
+  // VISIBILITY (ADR 0112's leak rule, as goal-graph.js applies it): a private
+  // goal the viewer is neither a member of nor an Archon over stays a tower (its
+  // counts are structure) but its title, and the titles of ideas tied to it, are
+  // dropped in shapeCity. Visibility comes from the signed-in viewer, never the query.
+  if (version) {
+    out.areas = (await pool.query(
+      `SELECT g.id::text AS goal_id, g.title,
+              (g.visibility IS DISTINCT FROM 'private'
+                 OR $2::boolean
+                 OR EXISTS (SELECT 1 FROM goal_members gm WHERE gm.goal_id = g.id AND gm.builder_id = $3::bigint)) AS visible
+         FROM goals g
+        WHERE g.version_id = $1 AND g.status = 'open' AND NOT g.is_maintenance
+        ORDER BY g.sort_order, g.id
+        LIMIT ${MAX_AREAS}`,
+      [version.id, isArchon, viewerId],
+    )).rows;
+  }
+  const goalIds = out.areas.map((a) => a.goal_id);
+  const none = Promise.resolve({ rows: [] });
+  const friction = rank === 'xenos' ? `AND i.kind <> '${SKILL_FRICTION_KIND}' AND i.title NOT LIKE '${SKILL_FRICTION_TAG}%'` : '';
+
+  // the idea's net votes and the viewer's own vote in ONE look-up per idea (at most
+  // MAX_IDEAS of them, each an index read on idx_ideas_votes_target), read only when the
+  // ideas module's votes table is there (a project with ideas switched off answers without them)
+  const ideaVoteCols = hasIdeaVotes ? 'iv.votes, iv.voted' : '0 AS votes, false AS voted';
+  const ideaVoteJoin = hasIdeaVotes
+    ? `LEFT JOIN LATERAL (SELECT coalesce(sum(v.vote), 0)::int AS votes, coalesce(bool_or(v.voter_builder_id = $2::bigint), false) AS voted
+                               FROM ideas_votes v WHERE v.target_idea_id = i.id) iv ON true`
+    : '';
+  const [areaWeeks, leads, peopleWeeks, ideaCounts, ideas, gov, sites, waiting, ideaVotes, taskTotal] = await Promise.all([
+    goalIds.length ? pool.query(
+      `SELECT t.goal_id::text AS goal_id,
+              CASE WHEN t.shipped_at < $2 THEN -1 ELSE ${wk('t.shipped_at', '$2')} END AS wk,
+              (t.discipline = ANY($3::text[])) AS art,
+              count(*)::int AS n
+         FROM tasks t
+        WHERE t.status = 'shipped' AND t.shipped_at IS NOT NULL
+          AND t.goal_id = ANY($1::bigint[])
+          AND t.title NOT LIKE '${SMOKE_TITLE}' ESCAPE '\\'
+        GROUP BY 1, 2, 3`,
+      [goalIds, start, ART_DISCIPLINES],
+    ) : none,
+    goalIds.length ? pool.query(
+      `SELECT DISTINCT ON (goal_id, wk) goal_id, wk, shipped_by
+         FROM (SELECT t.goal_id::text AS goal_id, ${wk('t.shipped_at', '$2')} AS wk, t.shipped_by::text AS shipped_by, count(*) AS n
+                 FROM tasks t
+                WHERE t.status = 'shipped' AND t.shipped_at >= $2 AND t.shipped_by IS NOT NULL
+                  AND t.goal_id = ANY($1::bigint[])
+                GROUP BY 1, 2, 3) x
+        ORDER BY goal_id, wk, n DESC, shipped_by`,
+      [goalIds, start],
+    ) : none,
+    pool.query(
+      `SELECT t.shipped_by::text AS id, ${wk('t.shipped_at', '$1')} AS wk, (t.discipline = ANY($2::text[])) AS art, count(*)::int AS n
+         FROM tasks t
+        WHERE t.status = 'shipped' AND t.shipped_at >= $1 AND t.shipped_by IS NOT NULL
+          AND t.title NOT LIKE '${SMOKE_TITLE}' ESCAPE '\\'
+        GROUP BY 1, 2, 3`,
+      [start, ART_DISCIPLINES],
+    ),
+    pool.query(
+      `SELECT i.captured_by::text AS id, ${wk('i.captured_at', '$1')} AS wk, count(*)::int AS n
+         FROM idea_inbox i
+        WHERE i.captured_at >= $1 AND i.captured_by IS NOT NULL ${friction}
+        GROUP BY 1, 2`,
+      [start],
+    ),
+    pool.query(
+      `SELECT i.id::text AS id, i.title, i.captured_by::text AS by, ${wk('i.captured_at', '$1')} AS wk, pt.goal_id::text AS goal_id,
+              i.suggested_goal_id::text AS aim_id, i.status,
+              CASE WHEN pt.id IS NULL THEN NULL ELSE ${wk('pt.created_at', '$1')} END AS became_wk,
+              ${ideaVoteCols}
+         FROM idea_inbox i
+         LEFT JOIN tasks pt ON pt.id = i.promoted_to_task_id
+         ${ideaVoteJoin}
+        WHERE i.captured_at >= $1 ${friction}
+        ORDER BY i.captured_at DESC
+        LIMIT ${MAX_IDEAS}`,
+      hasIdeaVotes ? [start, viewerId] : [start],
+    ),
+    pool.query(
+      `SELECT id, wk, sum(n)::int AS n FROM (
+         ${hasVotes ? `SELECT v.voter_id::text AS id, ${wk('v.cast_at', '$1')} AS wk, count(*) AS n
+           FROM government_board_votes v WHERE v.cast_at >= $1 GROUP BY 1, 2
+         UNION ALL` : ''}
+         SELECT b.resolved_by::text AS id, ${wk('b.resolved_at', '$1')} AS wk, count(*) AS n
+           FROM blockers b WHERE b.status = 'resolved' AND b.resolved_at >= $1 AND b.resolved_by IS NOT NULL GROUP BY 1, 2
+       ) x GROUP BY 1, 2`,
+      [start],
+    ),
+    goalIds.length ? pool.query(
+      `SELECT DISTINCT ON (t.goal_id) t.goal_id::text AS goal_id, c.builder_id::text AS builder_id,
+              ${hasRunners ? `EXISTS (SELECT 1 FROM autonomy_runner_heartbeat h
+                                       WHERE h.working_task_id = t.id AND h.last_seen_at > now() - interval '15 minutes')` : 'false'} AS agent
+         FROM claims c
+         JOIN tasks t ON t.id = c.task_id
+        WHERE c.released_at IS NULL AND t.goal_id = ANY($1::bigint[])
+        ORDER BY t.goal_id, c.claimed_at DESC`,
+      [goalIds],
+    ) : none,
+    goalIds.length ? waitingOnViewer(pool, goalIds, viewer, deps) : Promise.resolve([]),
+    hasIdeaVotes ? pool.query(
+      `SELECT v.voter_builder_id::text AS id, ${wk('v.recorded_at', '$1')} AS wk, count(*)::int AS n
+         FROM ideas_votes v WHERE v.recorded_at >= $1 GROUP BY 1, 2`,
+      [start],
+    ) : none,
+    goalIds.length ? pool.query(
+      `SELECT t.goal_id::text AS goal_id, count(*)::int AS n FROM tasks t
+        WHERE t.goal_id = ANY($1::bigint[]) AND t.status <> 'abandoned'
+          AND t.title NOT LIKE '${SMOKE_TITLE}' ESCAPE '\\'
+        GROUP BY 1`,
+      [goalIds],
+    ) : none,
+  ]);
+  Object.assign(out, {
+    areaWeeks: areaWeeks.rows, leads: leads.rows, peopleWeeks: peopleWeeks.rows, ideaCounts: ideaCounts.rows,
+    ideas: ideas.rows, gov: gov.rows, sites: sites.rows, waiting,
+    ideaVotes: ideaVotes.rows, taskTotal: goalIds.length ? taskTotal.rows.reduce((n, r) => n + (Number(r.n) || 0), 0) : null,
+  });
+
+  const ids = new Set();
+  [out.leads.map((r) => r.shipped_by), out.peopleWeeks.map((r) => r.id), out.ideaCounts.map((r) => r.id), out.ideas.map((r) => r.by), out.gov.map((r) => r.id), out.sites.map((r) => r.builder_id), out.ideaVotes.map((r) => r.id)]
+    .forEach((list) => list.forEach((id) => { if (id != null) ids.add(String(id)); }));
+  if (viewerId) ids.add(viewerId);
+  if (ids.size) {
+    out.builders = (await pool.query(
+      `SELECT b.id::text AS id, b.github_login, b.display_name, b.avatar_url
+         FROM builders b
+        WHERE b.id = ANY($1::bigint[]) AND b.system_role IS NULL`,
+      [[...ids]],
+    )).rows;
+  }
+  return out;
+}
+
+// The raw rows → the response Home draws. Pure: a test feeds it rows with no
+// database. Rows outside the window (a clock skew, a bad week index) are dropped,
+// never counted at the edge.
+function shapeCity(raw, viewer) {
+  const N = raw.N;
+  const inWeek = (w) => Number.isInteger(w) && w >= 0 && w < N;
+  const zeros = () => Array(N).fill(0);
+  const start = raw.start instanceof Date ? raw.start : new Date(raw.start);
+  const weeks = Array.from({ length: N }, (_, i) => ({ start: new Date(start.getTime() + i * 7 * 864e5).toISOString().slice(0, 10) }));
+
+  const areas = raw.areas.map((a) => ({ goal_id: a.goal_id, title: a.visible === false ? null : a.title, base_build: 0, base_art: 0, build: zeros(), art: zeros(), lead: Array(N).fill(null) }));
+  const byGoal = new Map(areas.map((a) => [a.goal_id, a]));
+  const hiddenGoals = new Set(raw.areas.filter((a) => a.visible === false).map((a) => String(a.goal_id)));
+  raw.areaWeeks.forEach((r) => {
+    const a = byGoal.get(String(r.goal_id)); if (!a) return;
+    const n = Number(r.n) || 0;
+    if (r.wk === -1) { if (r.art) a.base_art += n; else a.base_build += n; return; }
+    if (inWeek(r.wk)) (r.art ? a.art : a.build)[r.wk] += n;
+  });
+  raw.leads.forEach((r) => { const a = byGoal.get(String(r.goal_id)); if (a && inWeek(r.wk)) a.lead[r.wk] = String(r.shipped_by); });
+
+  const known = new Map(raw.builders.map((b) => [String(b.id), b]));
+  const people = new Map();
+  const person = (id) => {
+    const key = String(id);
+    if (!known.has(key)) return null; // a machine principal or a deleted builder is never drawn
+    if (!people.has(key)) {
+      const b = known.get(key);
+      people.set(key, { id: key, login: b.github_login || '', name: b.display_name || b.github_login || 'Builder', avatar_url: b.avatar_url || null, agent: false, build: zeros(), art: zeros(), idea: zeros(), gov: zeros(), vote: zeros() });
+    }
+    return people.get(key);
+  };
+  raw.peopleWeeks.forEach((r) => { const p = person(r.id); if (p && inWeek(r.wk)) (r.art ? p.art : p.build)[r.wk] += Number(r.n) || 0; });
+  raw.ideaCounts.forEach((r) => { const p = person(r.id); if (p && inWeek(r.wk)) p.idea[r.wk] += Number(r.n) || 0; });
+  raw.gov.forEach((r) => { const p = person(r.id); if (p && inWeek(r.wk)) p.gov[r.wk] += Number(r.n) || 0; });
+  (raw.ideaVotes || []).forEach((r) => { const p = person(r.id); if (p && inWeek(r.wk)) p.vote[r.wk] += Number(r.n) || 0; });
+  if (viewer && viewer.id != null) person(viewer.id);
+  areas.forEach((a) => { a.lead = a.lead.map((id) => (id && known.has(id) ? id : null)); });
+
+  // The sky's facts per idea (task 1005059). Its AREA is the goal of the work it became,
+  // else the goal its filer aimed it at — an area of this version, or none ("not placed
+  // yet"). It BECAME work the week its task was made, never before it was filed and never
+  // past this week. It WAITS on the viewer when it is new (these two weeks), open, in no
+  // area, not theirs, and they have not voted on it.
+  const viewerKey = viewer && viewer.id != null ? String(viewer.id) : null;
+  const ideas = raw.ideas.filter((r) => inWeek(r.wk)).map((r) => {
+    const goal = r.goal_id && byGoal.has(String(r.goal_id)) ? String(r.goal_id) : null;
+    const aim = r.aim_id && byGoal.has(String(r.aim_id)) ? String(r.aim_id) : null;
+    const area = goal || aim;
+    const became = Number.isInteger(r.became_wk) && goal ? Math.max(r.wk, Math.min(N - 1, r.became_wk)) : null;
+    const hidden = hiddenGoals.has(String(r.goal_id)) || hiddenGoals.has(String(r.aim_id));
+    const waits = !!viewerKey && r.status === 'open' && !area && r.wk >= N - 2 && String(r.by) !== viewerKey && !r.voted;
+    return { id: String(r.id), week: r.wk, by: r.by && known.has(String(r.by)) ? String(r.by) : null, title: hidden ? null : (r.title || ''), goal_id: goal, area_id: area, became, votes: Number(r.votes) || 0, waits };
+  });
+  const sites = raw.sites.filter((s) => byGoal.has(String(s.goal_id)) && known.has(String(s.builder_id)))
+    .map((s) => { person(s.builder_id); return { goal_id: String(s.goal_id), builder_id: String(s.builder_id), agent: !!s.agent }; });
+  const waiting = raw.waiting.filter((w) => byGoal.has(String(w.goal_id)) && Number(w.n) > 0).map((w) => ({ goal_id: String(w.goal_id), count: Number(w.n) }));
+
+  return {
+    viewer: viewer && viewer.id != null ? { id: String(viewer.id) } : null,
+    version: raw.version ? { id: raw.version.id, name: raw.version.name || raw.version.id, tasks: Number.isFinite(raw.taskTotal) ? raw.taskTotal : null } : null,
+    weeks, areas, people: [...people.values()], ideas, now: { sites, waiting },
+  };
+}
+
+// The GET /home/city handler, injectable so a test drives it with no express.
+function homeCityHandler({ log, read = readCity } = {}) {
+  return async function homeCityRoute(req, res) {
+    try {
+      const viewer = req.builder ? { id: req.builder.id, rank: req.builder.rank } : null;
+      const raw = await read({ weeks: req.query && req.query.weeks, viewer });
+      res.set('Cache-Control', 'private, max-age=60');
+      res.json(shapeCity(raw, viewer));
+    } catch (err) {
+      if (log) log.error('GET /home/city', err);
+      res.fail('home_city_failed', { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+module.exports = { WAITING_TTL_MS, DEFAULT_WEEKS, MAX_AREAS, MAX_IDEAS, clampWeeks, readCity, shapeCity, homeCityHandler };