@bongos/core 1.24.29 → 1.24.31

package/tests/home_city.mjs

@@ -0,0 +1,580 @@
+// tests/home_city.mjs — Home's project city (task 1005054): the weekly summary the
+// server counts, and the drawing that turns it into towers and a ladder.
+//
+// The server half (modules/lifecycle/home-city.js) is driven three ways with no
+// database: the pure shaping over hand-written rows, the reads against a recording
+// fake pool (to prove every query is bounded by the window, the areas or a LIMIT,
+// and that the viewer-only and module-optional parts behave), and the handler. The
+// drawing half (modules/hall-ui/public/home-city-draw.js) is pure and runs in node.
+//
+// Run:  node tests/home_city.mjs
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+process.env.NODE_ENV = 'test';
+const city = require(path.join(ROOT, 'modules/lifecycle/home-city.js'));
+const Draw = require(path.join(ROOT, 'modules/hall-ui/public/home-city-draw.js'));
+const Gov = require(path.join(ROOT, 'modules/hall-ui/public/city-draw.js'));
+const FIXTURE = JSON.parse(fs.readFileSync(path.join(ROOT, 'scripts/hall-preview/fixtures/home__city.json'), 'utf8'));
+
+const { test, summary } = makeRunner();
+
+const START = new Date('2026-08-31T00:00:00Z');
+function raw(over = {}) {
+  return Object.assign({
+    N: 4, start: START, version: { id: 'V2', name: 'The ten working areas' },
+    areas: [{ goal_id: '10', title: 'Area ten' }, { goal_id: '20', title: 'Area twenty' }],
+    areaWeeks: [], leads: [], peopleWeeks: [], ideaCounts: [], ideas: [], gov: [], sites: [], waiting: [],
+    builders: [{ id: '1', github_login: 'ana', display_name: 'Ana', avatar_url: null }, { id: '2', github_login: 'bo', display_name: null, avatar_url: 'https://x/2.png' }],
+  }, over);
+}
+
+// ---------------------------------------------------------------------------
+// 1. the shaping (pure)
+// ---------------------------------------------------------------------------
+
+await test('an area splits what came before the window from each week, and art from build', () => {
+  const out = city.shapeCity(raw({
+    areaWeeks: [
+      { goal_id: '10', wk: -1, art: false, n: 40 }, { goal_id: '10', wk: -1, art: true, n: 3 },
+      { goal_id: '10', wk: 0, art: false, n: 5 }, { goal_id: '10', wk: 3, art: true, n: 2 },
+      { goal_id: '10', wk: 7, art: false, n: 99 }, // outside a four-week window: dropped, never piled on the edge
+      { goal_id: '99', wk: 1, art: false, n: 9 },  // not an area of the version: ignored
+    ],
+  }), null);
+  const a = out.areas.find((x) => x.goal_id === '10');
+  assert.equal(a.base_build, 40); assert.equal(a.base_art, 3);
+  assert.deepEqual(a.build, [5, 0, 0, 0]); assert.deepEqual(a.art, [0, 0, 0, 2]);
+  assert.deepEqual(out.weeks.map((w) => w.start), ['2026-08-31', '2026-09-07', '2026-09-14', '2026-09-21']);
+});
+
+await test('people are only known builders; the viewer is always there, even with a quiet week', () => {
+  const out = city.shapeCity(raw({
+    peopleWeeks: [{ id: '1', wk: 2, art: false, n: 4 }, { id: '1', wk: 2, art: true, n: 1 }, { id: '77', wk: 2, art: false, n: 8 }],
+    ideaCounts: [{ id: '2', wk: 1, n: 3 }], gov: [{ id: '1', wk: 3, n: 2 }],
+  }), { id: '2', rank: 'metic' });
+  const ana = out.people.find((p) => p.id === '1'), bo = out.people.find((p) => p.id === '2');
+  assert.deepEqual(ana.build, [0, 0, 4, 0]); assert.deepEqual(ana.art, [0, 0, 1, 0]); assert.deepEqual(ana.gov, [0, 0, 0, 2]);
+  assert.deepEqual(bo.idea, [0, 3, 0, 0]);
+  assert.equal(bo.name, 'bo', 'no display name falls back to the login');
+  assert.ok(!out.people.some((p) => p.id === '77'), 'a machine principal or deleted builder (not in builders) is never drawn');
+  assert.equal(out.viewer.id, '2');
+  assert.ok(out.people.every((p) => p.agent === false), 'a person is never an agent: agents are a site fact');
+});
+
+await test('leads, ideas and sites keep only what the city can place', () => {
+  const out = city.shapeCity(raw({
+    leads: [{ goal_id: '10', wk: 1, shipped_by: '1' }, { goal_id: '20', wk: 1, shipped_by: '77' }],
+    ideas: [{ id: 5, title: 'Sky', by: '1', wk: 3, goal_id: '20' }, { id: 6, title: 'Old', by: '1', wk: 9, goal_id: null }, { id: 7, title: 'Stray', by: '77', wk: 0, goal_id: '99' }],
+    sites: [{ goal_id: '10', builder_id: '1', agent: true }, { goal_id: '99', builder_id: '1', agent: false }, { goal_id: '20', builder_id: '77', agent: false }],
+    waiting: [{ goal_id: '20', n: 4 }, { goal_id: '10', n: 0 }, { goal_id: '99', n: 2 }],
+  }), null);
+  assert.equal(out.areas[0].lead[1], '1'); assert.equal(out.areas[1].lead[1], null);
+  assert.deepEqual(out.ideas.map((i) => [i.id, i.goal_id, i.by]), [['5', '20', '1'], ['7', null, null]]);
+  assert.deepEqual(out.now.sites, [{ goal_id: '10', builder_id: '1', agent: true }]);
+  assert.deepEqual(out.now.waiting, [{ goal_id: '20', count: 4 }]);
+});
+
+await test('a private area the viewer may not read keeps its tower but loses its name, and so do its ideas (ADR 0112)', () => {
+  const r = raw({
+    areas: [{ goal_id: '10', title: 'Area ten', visible: true }, { goal_id: '20', title: 'Secret plan', visible: false }],
+    areaWeeks: [{ goal_id: '20', wk: 1, art: false, n: 3 }],
+    ideas: [{ id: '7', title: 'Secret idea', by: '1', wk: 1, goal_id: '20' }, { id: '8', title: 'Open idea', by: '1', wk: 1, goal_id: '10' }],
+  });
+  const d = city.shapeCity(r, { id: '1' });
+  const hidden = d.areas.find((a) => a.goal_id === '20');
+  assert.equal(hidden.title, null, 'the private name never leaves the server');
+  assert.deepEqual(hidden.build, [0, 3, 0, 0], 'its counts are structure and stay');
+  assert.equal(d.areas.find((a) => a.goal_id === '10').title, 'Area ten');
+  assert.equal(d.ideas.find((x) => x.id === '7').title, null, 'an idea tied to it loses its title too');
+  assert.equal(d.ideas.find((x) => x.id === '8').title, 'Open idea');
+  assert.ok(!JSON.stringify(d).includes('Secret'), 'no private prose anywhere in the payload');
+  const m = Draw.cityModel(d);
+  assert.equal(m.areas.find((a) => a.id === '20').title, 'A private area');
+  assert.equal(m.ideas.find((x) => x.id === '7').title, 'A private idea');
+});
+
+await test('weeks are clamped: never fewer than four, never more than twenty-six', () => {
+  assert.equal(city.clampWeeks(undefined), city.DEFAULT_WEEKS);
+  assert.equal(city.clampWeeks('2'), 4);
+  assert.equal(city.clampWeeks('500'), 26);
+  assert.equal(city.clampWeeks('abc'), city.DEFAULT_WEEKS);
+});
+
+// ---------------------------------------------------------------------------
+// 2. the reads: bounded, viewer-scoped, module-optional
+// ---------------------------------------------------------------------------
+
+function fakePool({ tables = {} } = {}) {
+  const seen = [];
+  return {
+    seen,
+    async query(sql, params) {
+      seen.push({ sql, params });
+      if (/to_regclass/.test(sql)) return { rows: [{ ok: !!tables[String(params[0]).replace('public.', '')] }] };
+      if (/date_trunc\('week'/.test(sql)) return { rows: [{ start: START }] };
+      if (/FROM versions/.test(sql)) return { rows: [{ id: 'V2', name: 'V2' }] };
+      if (/FROM goals g/.test(sql)) return { rows: [{ goal_id: '10', title: 'Area ten' }] };
+      if (/FROM builders b/.test(sql)) return { rows: [] };
+      return { rows: [] };
+    },
+  };
+}
+
+await test('every read is bounded by the window, the areas or a LIMIT, and never selects a task body', async () => {
+  const pool = fakePool({ tables: { government_board_votes: true, autonomy_runner_heartbeat: true, government_asks: true, ideas_votes: true } });
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'archon' } }, { pool, getFocusVersionId: async () => null });
+  const data = pool.seen.filter((q) => !/to_regclass|date_trunc\('week'|FROM versions/.test(q.sql));
+  assert.ok(data.length >= 8, 'the summary reads areas, weeks, leads, people, ideas, govern, sites and waiting');
+  for (const q of data) {
+    const bounded = /LIMIT \d+/.test(q.sql) || /goal_id = ANY\(\$1::bigint\[\]\)/.test(q.sql) || /(shipped_at|captured_at|cast_at|resolved_at|recorded_at) >= \$1/.test(q.sql) || /b\.id = ANY/.test(q.sql);
+    assert.ok(bounded, `unbounded read:\n${q.sql}`);
+    assert.doesNotMatch(q.sql, /description|body_md|value_summary/, 'the city never downloads prose it does not draw');
+  }
+  assert.ok(data.filter((q) => /FROM tasks t/.test(q.sql) && !/claims c/.test(q.sql)).every((q) => /GROUP BY/.test(q.sql)), 'task reads come back as counts, not rows');
+});
+
+await test('visibility comes from the signed-in viewer: membership or Archon, never the query', async () => {
+  const metic = fakePool();
+  await city.readCity({ weeks: 10, viewer: { id: '42', rank: 'metic' } }, { pool: metic, getFocusVersionId: async () => null });
+  const q = metic.seen.find((x) => /FROM goals g/.test(x.sql));
+  assert.match(q.sql, /visibility IS DISTINCT FROM 'private'/);
+  assert.match(q.sql, /goal_members gm WHERE gm\.goal_id = g\.id AND gm\.builder_id = \$3/);
+  assert.deepEqual(q.params.slice(1), [false, '42']);
+  const archon = fakePool();
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'archon' } }, { pool: archon, getFocusVersionId: async () => null });
+  assert.equal(archon.seen.find((x) => /FROM goals g/.test(x.sql)).params[1], true);
+});
+
+await test('the independent reads run together, not one after another', async () => {
+  let inFlight = 0; let peak = 0;
+  const pool = fakePool({ tables: { government_board_votes: true, autonomy_runner_heartbeat: true, government_asks: true } });
+  const orig = pool.query.bind(pool);
+  pool.query = async (sql, params) => { inFlight += 1; peak = Math.max(peak, inFlight); await new Promise((r) => setTimeout(r, 5)); inFlight -= 1; return orig(sql, params); };
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'archon' } }, { pool, getFocusVersionId: async () => null });
+  assert.ok(peak >= 8, `the per-area and per-person reads overlap (peak ${peak})`);
+});
+
+await test('"waits on you" is the docket\'s routing when the government port answers, for any viewer it routes to', async () => {
+  const asked = [];
+  const government = { yoursByGoal: async (v) => { asked.push(v); return { available: true, goals: { 10: 2, 99: 5, 20: 0 } }; } };
+  const pool = fakePool({ tables: { government_asks: true } });
+  const r = await city.readCity({ weeks: 10, viewer: { id: '8', rank: 'metic' } }, { pool, government, getFocusVersionId: async () => null });
+  assert.deepEqual(asked, [{ id: '8', rank: 'metic' }], 'the port is asked once, for this viewer');
+  assert.deepEqual(r.waiting, [{ goal_id: '10', n: 2 }], 'a seated Metic gets their dots; a goal that is not an area is dropped');
+  assert.ok(!pool.seen.some((q) => /JOIN task_blockers/.test(q.sql)), 'the approximation is not read when the docket answered');
+  const none = await city.readCity({ weeks: 10, viewer: null }, { pool: fakePool(), government, getFocusVersionId: async () => null });
+  assert.deepEqual([none.waiting, asked.length], [[], 1], 'a signed-out viewer is never asked about');
+});
+
+await test('"waits on you" is held per viewer for a short window, so a reload of Home costs no docket reads', async () => {
+  let calls = 0; let t = 1000;
+  const government = { yoursByGoal: async () => { calls += 1; return { available: true, goals: { 10: 1 } }; } };
+  const run = (viewer) => city.readCity({ weeks: 10, viewer }, { pool: fakePool(), government, now: () => t, getFocusVersionId: async () => null });
+  const a = await run({ id: '8', rank: 'metic' });
+  t += city.WAITING_TTL_MS - 1;
+  const b = await run({ id: '8', rank: 'metic' });
+  assert.deepEqual([calls, a.waiting, b.waiting], [1, [{ goal_id: '10', n: 1 }], [{ goal_id: '10', n: 1 }]], 'inside the window: one docket read, the same dots');
+  await run({ id: '9', rank: 'metic' });
+  assert.equal(calls, 2, 'another viewer is asked for their own answer');
+  t += 2;
+  await run({ id: '8', rank: 'metic' });
+  assert.equal(calls, 3, 'after the window the docket is asked again');
+  const failing = { yoursByGoal: async () => ({ available: false, reason: 'unavailable' }) };
+  let fcalls = 0; const counted = { yoursByGoal: async (v) => { fcalls += 1; return failing.yoursByGoal(v); } };
+  for (let i = 0; i < 2; i += 1) await city.readCity({ weeks: 10, viewer: { id: '8', rank: 'metic' } }, { pool: fakePool(), government: counted, now: () => t, getFocusVersionId: async () => null });
+  assert.equal(fcalls, 2, 'an unavailable answer is never held');
+});
+
+await test('"waits on you" falls back to the approximation (Archon only) when the port is absent, older, unavailable or throws', async () => {
+  const ports = [null, {}, { yoursByGoal: async () => ({ available: false, reason: 'unavailable' }) }, { yoursByGoal: async () => { throw new Error('db down'); } }];
+  for (const government of ports) {
+    const metic = fakePool({ tables: { government_asks: true } });
+    const m = await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'metic' } }, { pool: metic, government, getFocusVersionId: async () => null });
+    assert.ok(!metic.seen.some((q) => /JOIN task_blockers/.test(q.sql)), 'a Metic is not the owner seat: no approximation read');
+    assert.deepEqual(m.waiting, []);
+    const archon = fakePool({ tables: { government_asks: true } });
+    await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'archon' } }, { pool: archon, government, getFocusVersionId: async () => null });
+    const w = archon.seen.find((q) => /JOIN task_blockers/.test(q.sql));
+    assert.ok(w, 'an Archon gets the per-area approximation');
+    assert.match(w.sql, /a\.waits_on = 'owner'/, 'only blockers whose ask waits on the owner seat (or carry none)');
+  }
+});
+
+await test('the government port\'s yoursByGoal counts, per goal, the goal-shaped matters the docket routes to the viewer', async () => {
+  const docket = require(path.join(ROOT, 'modules/government/docket.js'));
+  const port = require(path.join(ROOT, 'modules/government/routes/government.js')).governmentPort;
+  assert.equal(typeof port.yoursByGoal, 'function', 'the port carries it');
+  assert.deepEqual([...docket.GOAL_SOURCES], ['blockers', 'criteria_uat', 'goal_join_requests']);
+  const src = (source, building, rows, gate = { anyBuilder: true }) => [source, { source, building, gate, read: async () => rows }];
+  const contributions = { sources: new Map([
+    src('blockers', 'planning', [{ id: 7, title: 'Pick a host', state: 'needs' }, { id: 8, title: 'Token scope', state: 'needs' }, { id: 9, title: 'Moving one', state: 'moving' }]),
+    src('criteria_uat', 'review', [{ id: 31, title: 'Sign off C3', state: 'needs' }], { permission: 'criterion.review' }),
+    src('goal_join_requests', 'people', [{ id: 55, title: 'Bo asks to join', state: 'needs' }]),
+    src('core_update', 'release', [{ id: 1, title: 'Update', state: 'needs' }]), // not goal-shaped: never read
+  ]) };
+  const seats = { leads: [{ building: 'review', builder_id: 8 }], owner: { builders: [{ id: 7 }] }, holders: {}, access: {} };
+  const asks = new Map([['blockers:8', { waits_on: 'lead:review' }]]);
+  let mapped = null;
+  const goalsOf = async (q) => {
+    mapped = q;
+    const rows = { 'blockers:7': ['10', '20'], 'blockers:8': ['10'], 'criteria_uat:31': ['20'], 'goal_join_requests:55': ['30'] };
+    return [...q.blockers.map((id) => `blockers:${id}`), ...q.criteria.map((id) => `criteria_uat:${id}`), ...q.joinRequests.map((id) => `goal_join_requests:${id}`)]
+      .flatMap((m) => (rows[m] || []).map((g) => ({ matter_id: m, goal_id: g })));
+  };
+  const opts = (permissions) => ({ contributions, permissions, readAsks: async () => asks, readSeats: async () => seats, goalsOf });
+
+  // The owner (no Lead in Planning or People): the ask-less blocker and the join request fall to them.
+  const owner = await docket.yoursByGoal({ id: 7, rank: 'archon' }, opts(['board.vote.cast', 'criterion.review']));
+  assert.deepEqual(owner, { available: true, goals: { 10: 1, 20: 1, 30: 1 } });
+  assert.deepEqual(mapped, { blockers: ['7'], criteria: [], joinRequests: ['55'] }, 'only matters routed to the viewer are mapped');
+
+  // The seated Review Lead: the blocker whose ask names their seat, and the criterion at their building.
+  const lead = await docket.yoursByGoal({ id: 8, rank: 'metic' }, opts(['board.vote.cast', 'criterion.review']));
+  assert.deepEqual(lead, { available: true, goals: { 10: 1, 20: 1 } });
+
+  // Without the criterion atom the source is gated out, exactly as on the docket.
+  const gated = await docket.yoursByGoal({ id: 8, rank: 'metic' }, opts(['board.vote.cast']));
+  assert.deepEqual(gated.goals, { 10: 1 });
+
+  // Without the docket's own atom nothing is routed (docketFor's rule).
+  assert.deepEqual(await docket.yoursByGoal({ id: 7 }, opts([])), { available: true, goals: {} });
+  // Unreadable seats are said, never a guessed zero.
+  assert.deepEqual(await docket.yoursByGoal({ id: 7 }, { ...opts(['board.vote.cast']), readSeats: async () => null }), { available: false, reason: 'unavailable' });
+});
+
+await test('government and autonomy tables are probed first: switched off, they are never named', async () => {
+  const pool = fakePool({ tables: {} });
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'archon' } }, { pool, getFocusVersionId: async () => null });
+  const all = pool.seen.filter((q) => !/to_regclass/.test(q.sql)).map((q) => q.sql).join('\n');
+  assert.doesNotMatch(all, /government_board_votes|autonomy_runner_heartbeat|government_asks/);
+});
+
+await test('an Xenos viewer never sees skill-friction ideas', async () => {
+  const pool = fakePool();
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'xenos' } }, { pool, getFocusVersionId: async () => null });
+  const ideaReads = pool.seen.filter((q) => /FROM idea_inbox/.test(q.sql));
+  assert.equal(ideaReads.length, 2);
+  for (const q of ideaReads) assert.match(q.sql, /i\.kind <> 'skill-friction' AND i\.title NOT LIKE '\[skill-friction\]%'/);
+  const metic = fakePool();
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'metic' } }, { pool: metic, getFocusVersionId: async () => null });
+  for (const q of metic.seen.filter((x) => /FROM idea_inbox/.test(x.sql))) assert.doesNotMatch(q.sql, /skill-friction/);
+});
+
+await test('no version being built: no areas are read and the city has nothing to draw', async () => {
+  const pool = fakePool();
+  pool.query = ((orig) => async (sql, params) => (/FROM versions/.test(sql) ? { rows: [] } : orig.call(pool, sql, params)))(pool.query);
+  const r = await city.readCity({ weeks: 10, viewer: null }, { pool, getFocusVersionId: async () => null });
+  assert.equal(r.version, null);
+  assert.deepEqual(r.areas, []);
+  assert.ok(!pool.seen.some((q) => /FROM goals g/.test(q.sql)));
+});
+
+// ---------------------------------------------------------------------------
+// 3. the handler
+// ---------------------------------------------------------------------------
+
+function fakeRes() {
+  const res = { headers: {}, body: null, failed: null };
+  res.set = (k, v) => { res.headers[k] = v; return res; };
+  res.json = (b) => { res.body = b; return res; };
+  res.fail = (code, o) => { res.failed = { code, status: o.status }; return res; };
+  return res;
+}
+
+await test('the handler shapes the read for the caller, privately cached', async () => {
+  let asked = null;
+  const h = city.homeCityHandler({ read: async (q) => { asked = q; return raw(); } });
+  const res = fakeRes();
+  await h({ builder: { id: '1', rank: 'thetes' }, query: { weeks: '8' } }, res);
+  assert.deepEqual(asked, { weeks: '8', viewer: { id: '1', rank: 'thetes' } });
+  assert.equal(res.headers['Cache-Control'], 'private, max-age=60');
+  assert.equal(res.body.viewer.id, '1');
+  assert.equal(res.body.areas.length, 2);
+});
+
+await test('a failed read is a 500, never a half-drawn city', async () => {
+  const h = city.homeCityHandler({ read: async () => { throw new Error('db down'); }, log: { error() {} } });
+  const res = fakeRes();
+  await h({ builder: { id: '1' }, query: {} }, res);
+  assert.deepEqual(res.failed, { code: 'home_city_failed', status: 500 });
+  assert.equal(res.body, null);
+});
+
+await test('the route is registered by the lifecycle module', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules/lifecycle/module.json'), 'utf8'));
+  assert.ok(manifest.contributes.routes.includes('home-city'));
+});
+
+// ---------------------------------------------------------------------------
+// 4. the drawing (pure)
+// ---------------------------------------------------------------------------
+
+await test('the fixture is a shape the drawing accepts, and the tallest areas stand at the back', () => {
+  const m = Draw.cityModel(FIXTURE);
+  assert.equal(m.W, 10);
+  assert.ok(m.areas.length > 5);
+  assert.ok(m.areas[0].total >= m.areas[m.areas.length - 1].total);
+  const back = (a) => a.x + a.y;
+  assert.deepEqual([m.areas[0].x, m.areas[0].y], Draw.RING[0], 'the tallest tower takes the back corner');
+  assert.ok(m.areas.every((a, n) => n === 0 || back(a) >= back(m.areas[n - 1])), 'each shorter area stands no farther back than a taller one');
+});
+
+await test('the ring of plots stays off the civic core and the museum, and no two plots overlap (v16)', () => {
+  const F = 1.8, C = Draw.CORE, MUSEUM = { x0: 4.6, y0: 10.9, x1: 11.4, y1: 19.2 };
+  const hit = (a, b) => a.x0 < b.x1 && b.x0 < a.x1 && a.y0 < b.y1 && b.y0 < a.y1;
+  const plots = Draw.RING.map(([x, y]) => ({ x0: x, y0: y, x1: x + F, y1: y + F }));
+  plots.forEach((p, n) => {
+    assert.ok(!hit(p, C), `plot ${n} stands clear of the civic plaza`);
+    assert.ok(!hit(p, MUSEUM), `plot ${n} stands clear of the museum and its garden`);
+    plots.slice(n + 1).forEach((q) => assert.ok(!hit(p, q), 'plots do not overlap'));
+  });
+});
+
+await test('more areas than the ground holds are reported, not drawn', () => {
+  const many = { weeks: [{ start: '2026-08-31' }], areas: Array.from({ length: 20 }, (_, i) => ({ goal_id: String(i), title: `A${i}`, base_build: 20 - i, build: [0], art: [0] })) };
+  const m = Draw.cityModel(many);
+  assert.equal(m.areas.length, Draw.MAX_AREAS);
+  assert.equal(m.unplaced, 20 - Draw.MAX_AREAS);
+});
+
+await test('the ladder ranks the week by total, and the viewer is appended when below the top seven', () => {
+  const people = Array.from({ length: 9 }, (_, i) => ({ id: String(i), name: `P${i}`, build: [9 - i], art: [0], idea: [0], gov: [0] }));
+  const m = Draw.cityModel({ weeks: [{ start: '2026-08-31' }], areas: [], people });
+  const top = Draw.ladderFor(m, 0, '8');
+  assert.deepEqual(top.map((r) => r.id), ['0', '1', '2', '3', '4', '5', '6', '8']);
+  assert.equal(top[7].me, true);
+  assert.deepEqual(Draw.ladderFor(m, 0, '3').map((r) => r.id).length, 7, 'a viewer in the top seven is not repeated');
+});
+
+await test('the latest week shows who is on site now; an earlier week shows its four busiest areas', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const now = Draw.sitesFor(m, m.W - 1);
+  assert.deepEqual(Object.keys(now).sort(), FIXTURE.now.sites.map((s) => s.goal_id).sort());
+  assert.equal(now['1000095'].agent, true, 'a runner working the site marks it an agent\'s');
+  const earlier = Draw.sitesFor(m, 3);
+  assert.ok(Object.keys(earlier).length <= 4 && Object.keys(earlier).length > 0);
+  assert.ok(Object.values(earlier).every((s) => s.agent === false));
+});
+
+// the scene comes back as shapes; walk them the way home-city.js builds them
+function walk(nodes, fn) { for (const n of nodes) { fn(n); walk(n.kids, fn); } }
+function all(nodes) { const out = []; walk(nodes, (n) => out.push(n)); return out; }
+
+await test('towers grow week by week, and salmon only appears on the latest week', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const first = all(Draw.citySvg(m, 0, { mode: 'dark' }).nodes);
+  const last = all(Draw.citySvg(m, m.W - 1, { mode: 'dark' }).nodes);
+  const shipped = (ns) => ns.map((n) => /^(\d+) shipped/.exec(n.attrs['data-tip-body'] || '')).filter(Boolean).reduce((s, x) => s + Number(x[1]), 0);
+  assert.ok(shipped(last) > shipped(first), 'more has shipped by now than by the first week');
+  assert.ok(!first.some((n) => n.attrs.fill === 'var(--accent)'), 'what waits on you is now, not then');
+  assert.ok(last.some((n) => n.attrs.class === 'hc-wait'));
+  assert.ok(last.some((n) => /'s agent$/.test(n.attrs['data-tip'] || '')), 'an agent\'s site is named as one');
+});
+
+await test('ledger text is never markup: titles and names travel as attribute values and text only', () => {
+  const hostile = { weeks: [{ start: '2026-08-31' }], areas: [{ goal_id: '1', title: '<img src=x onerror=alert(1)>', base_build: 5, build: [1], art: [0], lead: ['9'] }],
+    people: [{ id: '9', name: '"><script>x</script>', build: [1], art: [0], idea: [0], gov: [0] }],
+    ideas: [{ id: '3', week: 0, by: '9', title: '<b>idea</b>' }], now: { sites: [{ goal_id: '1', builder_id: '9' }] } };
+  const ns = all(Draw.citySvg(Draw.cityModel(hostile), 0, { mode: 'light' }).nodes);
+  const SHAPES = new Set(['defs', 'radialGradient', 'stop', 'path', 'line', 'circle', 'ellipse', 'g', 'a', 'rect', 'text', 'clipPath', 'image']);
+  assert.deepEqual([...new Set(ns.map((n) => n.tag))].filter((t) => !SHAPES.has(t)), [], 'only SVG shapes, whatever a title says');
+  assert.ok(ns.some((n) => n.attrs['data-tip'] === '<img src=x onerror=alert(1)>'), 'the title rides as an attribute value, set with setAttribute');
+  assert.ok(ns.some((n) => n.tag === 'text' && n.text === '"'), 'a name\'s initial is a text node');
+});
+
+// v16 (task 1005058): one city for every craft, its districts as doors
+const linksOf = (ns) => ns.filter((n) => n.tag === 'a');
+await test('the civic core is drawn by city-draw.js itself, and the whole district is ONE door to the street', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const ns = all(Draw.citySvg(m, m.W - 1, { mode: 'dark', gov: Gov }).nodes);
+  const core = linksOf(ns).filter((n) => /\bhc-core\b/.test(n.attrs.class));
+  assert.equal(core.length, 1, 'one link for the nine buildings, not nine');
+  assert.equal(core[0].attrs.href, Gov.STREET_HREF);
+  // the same paths city-draw.js's recipe draws for the Charter, in its own palette
+  const k = Gov.isoKit(50, 25, 0, 0, 0.82, Gov.isoTheme('dark'), true), charter = [];
+  Gov.isoInstitution(charter, k, 'charter', 0, 0, {});
+  const fills = new Set(all([core[0]]).map((n) => n.attrs.fill));
+  charter.forEach((p) => assert.ok(fills.has(p.f), 'the core wears the Governor City\'s own faces'));
+  assert.ok(all([core[0]]).filter((n) => n.tag === 'path').length > 9 * 3, 'all nine buildings, not a placeholder');
+  const bare = all(Draw.citySvg(m, m.W - 1, { mode: 'dark' }).nodes);
+  assert.ok(!linksOf(bare).some((n) => /hc-core/.test(n.attrs.class)), 'without city-draw.js loaded the city still draws, just without its core');
+});
+
+await test('on the builder\'s Home the core and the museum are faded; a craft\'s own district stays in colour', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const cls = (focus, key) => linksOf(all(Draw.citySvg(m, m.W - 1, { mode: 'light', gov: Gov, focus }).nodes)).find((n) => new RegExp(`\\b${key}\\b`).test(n.attrs.class)).attrs.class;
+  assert.match(cls(undefined, 'hc-core'), /hc-quiet/);
+  assert.match(cls(undefined, 'hc-museum'), /hc-quiet/);
+  assert.doesNotMatch(cls('museum', 'hc-museum'), /hc-quiet/);
+  assert.doesNotMatch(cls('core', 'hc-core'), /hc-quiet/);
+  const css = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/home-city.css'), 'utf8');
+  assert.match(css, /\.hc-quiet\s*\{[^}]*opacity:\s*\.3/, 'faded');
+  assert.match(css, /\.hc-quiet:hover,\s*\.hc-svg \.hc-quiet:focus-visible\s*\{[^}]*filter:\s*none/, 'back to colour under the pointer or the keyboard');
+});
+
+await test('a building opens its goal; the museum and the band of stars are doors to the artist\'s and the ideator\'s Home', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const ls = linksOf(all(Draw.citySvg(m, m.W - 1, { mode: 'dark', gov: Gov }).nodes));
+  const towers = ls.filter((n) => n.attrs.class === 'hc-tower');
+  assert.equal(towers.length, m.areas.length);
+  towers.forEach((n) => assert.match(n.attrs.href, /^\/goals#\/goal\/\d+$/));
+  assert.ok(m.areas.every((a) => towers.some((n) => n.attrs.href === `/goals#/goal/${a.id}`)), 'each area links to its own goal');
+  assert.equal(ls.find((n) => /hc-museum/.test(n.attrs.class)).attrs['data-craft-door'], 'artistry');
+  const sky = ls.find((n) => /hc-sky/.test(n.attrs.class));
+  assert.equal(sky.attrs['data-craft-door'], 'ideating');
+  assert.ok(ls.every((n) => n.attrs['aria-label']), 'every door is named for a screen reader');
+  const stars = all([sky]).filter((n) => n.tag === 'circle');
+  const box = Draw.viewBoxOf(m);
+  assert.ok(stars.length > 0 && stars.every((c) => c.attrs.cy < box.OY - 150), 'the stars sit high above the city, apart from it');
+});
+
+await test('a week part-way through grows each tower part-way: the slider glides, it does not jump', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const a = m.areas.find((x) => x.build[4] + x.art[4] > 0);
+  const at = (t) => { const d = Draw.doneAt(a, t); return d.build + d.art; };
+  assert.ok(at(3) < at(3.5) && at(3.5) < at(4), 'half a week in is half of that week\'s work');
+  assert.equal(at(3.5), (at(3) + at(4)) / 2);
+});
+
+await test('both modes draw with their own faces', () => {
+  const m = Draw.cityModel(FIXTURE);
+  assert.ok(all(Draw.citySvg(m, m.W - 1, { mode: 'dark' }).nodes).some((n) => n.attrs.fill === '#34343a'));
+  assert.ok(all(Draw.citySvg(m, m.W - 1, { mode: 'light' }).nodes).some((n) => n.attrs.fill === '#f6f5f8'));
+});
+
+// ---------------------------------------------------------------------------
+// the ideator's sky (task 1005059)
+// ---------------------------------------------------------------------------
+
+await test('an idea carries its area, the week it became work, its votes, and whether it waits on the viewer', () => {
+  const idea = (o) => Object.assign({ id: '1', title: 'T', by: '2', wk: 3, goal_id: null, aim_id: null, became_wk: null, votes: 0, voted: false, status: 'open' }, o);
+  const out = city.shapeCity(raw({
+    ideas: [
+      idea({ id: 'work', goal_id: '10', aim_id: '20', became_wk: 9, votes: 4 }), // became work: its task's goal wins over the aim; the week is clamped to the window
+      idea({ id: 'aim', aim_id: '20', wk: 2 }),                                  // aimed: placed in that area, not yet work
+      idea({ id: 'far', aim_id: '99' }),                                         // aimed outside this version: not placed
+      idea({ id: 'early', goal_id: '10', became_wk: 1, wk: 2 }),                 // a task made before the filing reads as the filing week
+      idea({ id: 'mine', by: '1' }), idea({ id: 'voted', voted: true }), idea({ id: 'old', wk: 1 }), idea({ id: 'shut', status: 'promoted' }),
+    ],
+    ideaVotes: [{ id: '1', wk: 2, n: 3 }, { id: '77', wk: 2, n: 9 }],
+    taskTotal: 50,
+  }), { id: '1', rank: 'metic' });
+  const by = Object.fromEntries(out.ideas.map((x) => [x.id, x]));
+  assert.deepEqual([by.work.area_id, by.work.goal_id, by.work.became, by.work.votes], ['10', '10', 3, 4]);
+  assert.deepEqual([by.aim.area_id, by.aim.became], ['20', null]);
+  assert.equal(by.far.area_id, null);
+  assert.equal(by.early.became, 2);
+  assert.deepEqual(out.ideas.filter((x) => x.waits).map((x) => x.id), ['far'], 'new, open, in no area, not mine, not voted on — and only these two weeks');
+  assert.deepEqual(out.people.find((p) => p.id === '1').vote, [0, 0, 3, 0], 'idea votes per week, known builders only');
+  assert.equal(out.version.tasks, 50);
+  assert.ok(city.shapeCity(raw(), null).ideas.every((x) => !x.waits), 'nothing waits on a signed-out viewer');
+});
+
+await test('the votes are read only where the ideas module keeps them; the viewer id rides only with that read', async () => {
+  const off = fakePool();
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'metic' } }, { pool: off, getFocusVersionId: async () => null });
+  const q = off.seen.find((x) => /FROM idea_inbox i\s+LEFT JOIN/.test(x.sql));
+  assert.doesNotMatch(q.sql, /ideas_votes/);
+  assert.equal(q.params.length, 1);
+  const on = fakePool({ tables: { ideas_votes: true } });
+  await city.readCity({ weeks: 10, viewer: { id: '1', rank: 'metic' } }, { pool: on, getFocusVersionId: async () => null });
+  const q2 = on.seen.find((x) => /FROM idea_inbox i\s+LEFT JOIN/.test(x.sql));
+  assert.match(q2.sql, /LEFT JOIN LATERAL \(SELECT[\s\S]*?FROM ideas_votes v WHERE v\.target_idea_id = i\.id\) iv ON true/); assert.equal(q2.sql.split('FROM ideas_votes').length - 1, 1, 'one look-up per idea, not two'); assert.deepEqual(q2.params.slice(1), ['1']);
+  assert.ok(/LIMIT \d+/.test(q2.sql), 'still the bounded newest-first list');
+});
+
+await test('the skyline IS the city: every building at its own screen x and height, seen from the street', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const t = m.W - 1;
+  const sil = Draw.skylineOf(m, t, Gov);
+  const OX = Draw.viewBoxOf(m).OX, sx = (x, y) => OX + (x - y) * 25;
+  m.areas.forEach((a) => {
+    const s = sil.find((x) => x.k === 'area' && x.id === a.id);
+    const d = Draw.doneAt(a, t);
+    assert.equal(s.l, sx(a.x, a.y + 1.8)); assert.equal(s.r, sx(a.x + 1.8, a.y));
+    assert.equal(s.h, 4 + Math.max(2, (d.build + d.art) * m.px), 'as tall as its tower in the city');
+  });
+  // the tower's own drawing agrees: its body's left and right faces span exactly the silhouette's edges
+  const I = Draw.theme('dark');
+  const xs = (n) => n.attrs.d.slice(1, -1).split('L').map((p) => Number(p.split(' ')[0]));
+  const towers = Draw.citySvg(m, t, { mode: 'dark', gov: Gov }).nodes.filter((n) => n.attrs.class === 'hc-tower');
+  assert.equal(towers.length, sil.filter((s) => s.k === 'area').length);
+  towers.forEach((tw) => {
+    const s = sil.find((x) => tw.attrs.href === `/goals#/goal/${x.id}`);
+    const left = tw.kids.find((k) => k.attrs.fill === I.work.l), right = tw.kids.find((k) => k.attrs.fill === I.work.r);
+    assert.ok(Math.abs(Math.min(...xs(left)) - s.l) <= 0.1 && Math.abs(Math.max(...xs(right)) - s.r) <= 0.1, `${s.id} stands where its tower does`);
+  });
+  const civic = sil.filter((s) => s.k === 'civic');
+  assert.equal(civic.length, Gov.CIVIC_SLOTS.length);
+  civic.forEach((s) => assert.equal(s.h, Gov.ROOF[s.id] * 0.82, 'a civic building at the core\'s own scale'));
+  assert.equal(sil.filter((s) => s.k === 'museum').length, 2, 'the museum block and its atrium');
+  for (let n = 1; n < sil.length; n++) assert.ok(sil[n - 1].depth <= sil[n].depth, 'back to front');
+  // it grows with the slider
+  const tallest = (u) => Math.max(...Draw.skylineOf(m, u, Gov).filter((s) => s.k === 'area').map((s) => s.h));
+  assert.ok(tallest(0) < tallest(t));
+});
+
+await test('outlines never show through a nearer building, and the three doors lie on top', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const ns = all(Draw.skySvg(m, m.W - 1, { mode: 'dark', gov: Gov }).nodes);
+  const sky = ns.find((n) => n.attrs.class === 'hc-skyline').kids;
+  // each silhouette's outline comes straight after its own fill, so every LATER (nearer) fill covers it
+  const fills = sky.filter((n) => n.attrs.class === 'hc-sil');
+  assert.equal(fills.length, Draw.skylineOf(m, m.W - 1, Gov).length);
+  sky.forEach((n, i) => { if (/hc-ol\b/.test(n.attrs.class || '')) assert.equal(sky[i - 1].attrs.d, n.attrs.d); });
+  const hits = ns.filter((n) => n.tag === 'a' && n.attrs.class === 'hc-hit');
+  assert.equal(hits.length, fills.length, 'one hit per silhouette, back to front, so the nearest takes the pointer');
+  const order = ns.indexOf(ns.find((n) => n.attrs.class === 'hc-hits'));
+  assert.ok(order > ns.indexOf(ns.find((n) => n.attrs.class === 'hc-skyline')), 'the hit layer is drawn over the skyline');
+  const group = (k) => hits.filter((h) => h.attrs['data-group'] === k);
+  assert.ok(group('area').every((h) => h.attrs.href === '/goals'), 'Building opens the goals');
+  assert.ok(group('civic').every((h) => h.attrs.href === Gov.STREET_HREF), 'Government opens the street');
+  assert.ok(group('museum').every((h) => h.attrs['data-craft-door'] === 'artistry'), 'Art switches to Artistry');
+  ['area', 'civic', 'museum'].forEach((k) => {
+    const g = group(k);
+    assert.ok(g.length > 0);
+    assert.equal(g.filter((h) => h.attrs.tabindex !== '-1').length, 1, 'one keyboard stop per group');
+    assert.ok(g[0].attrs['aria-label']);
+    g.forEach((h) => { const y = Math.min(...h.kids[0].attrs.d.match(/V(-?[\d.]+)/g).map((v) => Number(v.slice(1)))); assert.ok(Draw.SKY.h - y >= 30, 'a low building still offers a band to point at'); });
+  });
+});
+
+await test('the sky: constellations from real areas, a field for the unplaced, rings only at Live, work falls into its tower', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const ns = all(Draw.skySvg(m, m.W - 1, { mode: 'dark', gov: Gov }).nodes);
+  const consts = ns.filter((n) => n.attrs.class === 'hc-const');
+  const { groups } = Draw.skyPlaces(m);
+  assert.equal(consts.length, groups.length);
+  assert.ok(groups.every((g) => m.areas.includes(g.area)), 'a constellation per working area of this version');
+  assert.ok(ns.some((n) => n.attrs.class === 'hc-loose'));
+  const rings = (u) => all(Draw.skySvg(m, u, { mode: 'dark', gov: Gov }).nodes).filter((n) => n.attrs.class === 'hc-ring').length;
+  assert.equal(rings(m.W - 1), m.ideas.filter((x) => x.waits).length);
+  assert.equal(rings(m.W - 2), 0, 'what waits on you is now, not history');
+  const falls = ns.filter((n) => n.attrs.class === 'hc-fall').length;
+  assert.equal(falls, m.ideas.filter((x) => x.became === m.W - 1 && m.areas.some((a) => a.id === x.goal)).length);
+  const stars = ns.filter((n) => n.attrs.class === 'hc-star');
+  assert.equal(stars.length, m.ideas.filter((x) => !(x.became != null && x.became < m.W - 1)).length, 'an idea that became work earlier lit its window instead');
+  assert.ok(stars.every((s) => s.kids.some((k) => k.attrs.r >= 12)), 'each star offers a 24-unit target for its tip');
+  const built = Draw.versionBuilt(m, m.W - 1);
+  assert.ok(built > 0 && built < 1);
+  assert.ok(Draw.versionBuilt(m, 0) < built, 'the moon waxes with the slider');
+  assert.equal(Draw.versionBuilt(Object.assign({}, m, { version: null }), 1), null);
+});
+
+await test('the ideator\'s ladder ranks ideas, votes and work; the builder\'s ladder is unchanged', () => {
+  const m = Draw.cityModel(FIXTURE);
+  const i = m.W - 1;
+  const rows = Draw.ladderFor(m, i, FIXTURE.viewer.id, 'ideating');
+  rows.forEach((r) => assert.deepEqual(Object.keys(r.v), ['idea', 'vote', 'work']));
+  rows.forEach((r) => assert.equal(r.v.work, m.ideas.filter((x) => x.by === r.id && x.became === i).length));
+  Draw.ladderFor(m, i, FIXTURE.viewer.id).forEach((r) => assert.deepEqual(Object.keys(r.v), ['art', 'build', 'idea', 'gov']));
+});
+
+summary();