@bongos/core 1.23.13 → 1.23.15

package/src/platform-server.js

@@ -338,11 +338,11 @@ function buildPlatformApp() {
     res.type('html').send(html);
   });
   // THE COMMUNITY PAGES (task 1003363, ADR 0217 D1, ADR 0337 D1/D3): who is building
-  // across every project — the leaderboard, the builder search (the same for every
-  // viewer) and the recruiter list GET /scouting's own door admits. One file serves all
-  // three; its script shows the one the path names. Hub-only for the /account reason:
-  // every read it makes is a platform-identity route.
-  app.get(['/community', '/community/find', '/community/recruiters'], (req, res, next) => {
+  // across every project — the leaderboard, the builder of the week (task 1002981), the
+  // builder search (the same for every viewer) and the recruiter list GET /scouting's own
+  // door admits. One file serves all four; its script shows the one the path names.
+  // Hub-only for the /account reason: every read it makes is a platform-identity route.
+  app.get(['/community', '/community/week', '/community/find', '/community/recruiters'], (req, res, next) => {
     if (!isApexHost(req) || !isModuleEnabled('platform-identity')) return next();
     const html = landingPage('community.html');
     if (!html) return next();

package/tests/builder_of_the_week.mjs

@@ -0,0 +1,266 @@
+// tests/builder_of_the_week.mjs — Builder of the Week (community spec D5; task 1002981).
+//
+// DB-free. A fake pool answers the module's four statements: the existence probe on
+// platform_identity_weekly_features, the winner computation, the INSERT that records
+// the week, and the read of the crown and the weeks before it. Which snapshot becomes
+// the week's start and end, and that the predicate really filters, need a real
+// Postgres: tests/builder_of_the_week_db.mjs.
+//
+// What this pins:
+//   1. the week: the last FULL Monday-to-Monday week (UTC) before now, at every
+//      boundary of the week.
+//   2. the statements: both account reads carry the leaderboard's NUMBERS predicate
+//      (rollupVisibleSql) and not the recruiting one; the winner needs a shipped work
+//      and ties go to works, then karma, then handle; the write never overwrites.
+//   3. crown at render: a recorded week is never recomputed; an unrecorded one is
+//      computed once and written once, however many reads arrive together; a week
+//      nobody won is written with no winner; a failed crowning is retried next read.
+//   4. the read: the crown only for this week's row, the past weeks newest first, at
+//      most ARCHIVE_WEEKS of them, and no github_id anywhere.
+//   5. the route: no-store, the same body with or without credentials, the 500
+//      envelope, and its own rate-limit scope.
+//
+// Run:  node tests/builder_of_the_week.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.error(`  FAIL ${name}\n       ${e.message}`); }
+}
+
+const { rollupVisibleSql, scoutingListableSql } = require('../modules/platform-identity/account-visibility.js');
+
+// ---- fake engine ------------------------------------------------------------
+
+const PROBE = /^SELECT 1 FROM platform_identity_weekly_features WHERE week_start = \$1::date$/;
+const isWinner = (sql) => /platform_identity_activity_snapshots/.test(sql);
+const isInsert = (sql) => /^INSERT INTO platform_identity_weekly_features/.test(sql);
+const isRead = (sql) => /FROM platform_identity_weekly_features f\s+JOIN platform_identity_accounts pa/.test(sql);
+
+const engine = {
+  calls: [],
+  recorded: new Set(),  // weeks the probe finds
+  winner: null,         // what the winner statement returns
+  shown: [],            // what the read returns (already filtered, newest first)
+  throwOn: null,        // a predicate over the SQL that makes a call fail once
+  slowWinner: false,
+  query: async (text, params = []) => {
+    const sql = String(text).replace(/\s+/g, ' ').trim();
+    engine.calls.push({ sql, params });
+    if (engine.throwOn && engine.throwOn(sql)) { engine.throwOn = null; throw new Error('boom'); }
+    if (PROBE.test(sql)) return { rows: engine.recorded.has(params[0]) ? [{ '?column?': 1 }] : [] };
+    if (isWinner(sql)) {
+      if (engine.slowWinner) await new Promise((r) => setTimeout(r, 10));
+      return { rows: engine.winner ? [engine.winner] : [] };
+    }
+    if (isInsert(sql)) { engine.recorded.add(params[0]); return { rows: [], rowCount: 1 }; }
+    if (isRead(sql)) return { rows: engine.shown.slice(0, params[1]) };
+    throw new Error(`fake pool: unexpected statement ${sql.slice(0, 80)}`);
+  },
+};
+function reset() {
+  engine.calls = []; engine.recorded = new Set(); engine.winner = null; engine.shown = [];
+  engine.throwOn = null; engine.slowWinner = false;
+  botw.clearCrownMemo();
+}
+const callsOf = (pred) => engine.calls.filter((c) => pred(c.sql));
+
+// Pin the module doorway (ADR 0083) BEFORE the modules load.
+const moduleApiPath = require.resolve('../src/module-api.js');
+require.cache[moduleApiPath] = {
+  id: moduleApiPath, filename: moduleApiPath, loaded: true,
+  exports: {
+    pool: engine,
+    corsPublicGet: () => (_req, res, next) => { res.set('Access-Control-Allow-Origin', '*'); next(); },
+    logger: () => ({ error: () => {}, info: () => {}, warn: () => {} }),
+  },
+};
+
+const botw = require('../modules/platform-identity/builder-of-the-week.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRoutes = require('../modules/platform-identity/routes/community-leaderboard.js');
+
+const NOW = new Date('2026-10-28T09:30:00.000Z'); // a Wednesday
+const shownRow = (week_start, handle, credits, ships) => ({
+  week_start, handle, github_login: handle, display_name: handle.toUpperCase(), avatar_url: null,
+  credits_delta: String(credits), ships_delta: String(ships),
+});
+
+// ---- 1. the week ------------------------------------------------------------
+
+await t('the crowned week is the last full Monday-to-Monday week (UTC) before now, at every edge', () => {
+  const week = (iso) => { const w = botw.crownedWeek(new Date(iso)); return [w.start.toISOString(), w.end.toISOString()]; };
+  const last = ['2026-10-19T00:00:00.000Z', '2026-10-26T00:00:00.000Z'];
+  assert.deepEqual(week('2026-10-28T09:30:00.000Z'), last, 'a Wednesday: the week before this one');
+  assert.deepEqual(week('2026-10-26T00:00:00.000Z'), last, 'the very first instant of Monday: the week that just ended');
+  assert.deepEqual(week('2026-11-01T23:59:59.999Z'), last, 'the last instant of Sunday: still the same week');
+  assert.deepEqual(week('2026-10-25T23:59:59.999Z'), ['2026-10-12T00:00:00.000Z', '2026-10-19T00:00:00.000Z'], 'Sunday night: the week ending tonight is not over yet');
+  assert.deepEqual(week('2027-01-01T12:00:00.000Z'), ['2026-12-21T00:00:00.000Z', '2026-12-28T00:00:00.000Z'], 'across a year');
+});
+
+// ---- 2. the statements --------------------------------------------------------
+
+await t('the winner: eligible builders only, a shipped work required, ties by works then karma then handle', async () => {
+  reset();
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  const [w] = callsOf(isWinner);
+  assert.ok(w.sql.includes(rollupVisibleSql('pa').replace(/\s+/g, ' ').trim()), 'the leaderboard’s numbers predicate (hide, private and provisional are out)');
+  assert.ok(!w.sql.includes(scoutingListableSql('pa').replace(/\s+/g, ' ').trim()), 'the recruiting opt-out does not apply (spec D3)');
+  assert.match(w.sql, /HAVING sum\(tasks_shipped\) >= 1/, 'at least one work shipped in the week');
+  assert.match(w.sql, /ORDER BY sum\(credits\) DESC, sum\(tasks_shipped\) DESC, sum\(karma\) DESC, handle COLLATE "C", github_login COLLATE "C" LIMIT 1/);
+  assert.match(w.sql, /s\.reported_at <= \$2::timestamptz/, 'the week’s end: the last snapshot at-or-before it');
+  assert.match(w.sql, /s\.reported_at <= \$1::timestamptz/, 'the week’s start: the last snapshot at-or-before it');
+  assert.match(w.sql, /WITH act AS \( SELECT a\.client_id, a\.github_id, a\.first_seen_at, pa\.handle, pa\.github_login FROM/, 'never the live totals: a past week is read from history');
+  assert.match(w.sql, /\) b ON true WHERE b\.credits IS NOT NULL OR act\.first_seen_at >= \$1::timestamptz \)/, 'no history before the week: counted only if first seen in it (no lifetime in one week)');
+  assert.deepEqual(w.params.map((d) => d.toISOString()), ['2026-10-19T00:00:00.000Z', '2026-10-26T00:00:00.000Z']);
+});
+
+await t('the record: written once, never overwritten', async () => {
+  reset();
+  engine.winner = { github_id: '42', credits: '900', tasks_shipped: '3' };
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  const [ins] = callsOf(isInsert);
+  assert.match(ins.sql, /ON CONFLICT \(week_start\) DO NOTHING$/, 'the first decision stands');
+  assert.doesNotMatch(ins.sql, /DO UPDATE/);
+  assert.deepEqual(ins.params, ['2026-10-19', '42', '900', '3']);
+});
+
+await t('the read: the same predicate, at read time, and no github_id in the projection', async () => {
+  reset();
+  engine.recorded.add('2026-10-19');
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  const [r] = callsOf(isRead);
+  assert.ok(r.sql.includes(rollupVisibleSql('pa').replace(/\s+/g, ' ').trim()), 'a winner who hid since is not drawn (spec D8)');
+  const cols = r.sql.match(/^SELECT (.+?) FROM /)[1];
+  assert.doesNotMatch(cols, /github_id/, 'github_id never crosses');
+  assert.deepEqual(r.params, ['2026-10-19', botw.ARCHIVE_WEEKS + 1]);
+});
+
+// ---- 3. crown at render ---------------------------------------------------------
+
+await t('a recorded week is never recomputed', async () => {
+  reset();
+  engine.recorded.add('2026-10-19');
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  assert.equal(callsOf(isWinner).length, 0);
+  assert.equal(callsOf(isInsert).length, 0);
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  assert.equal(callsOf((s) => PROBE.test(s)).length, 1, 'and once known, not even asked about again in this process');
+});
+
+await t('an unrecorded week is computed and written once, however many reads arrive together', async () => {
+  reset();
+  engine.slowWinner = true;
+  engine.winner = { github_id: '7', credits: '50', tasks_shipped: '1' };
+  await Promise.all([1, 2, 3, 4].map(() => botw.readBuilderOfTheWeek({ now: NOW, pool: engine })));
+  assert.equal(callsOf(isWinner).length, 1);
+  assert.equal(callsOf(isInsert).length, 1);
+  assert.equal(callsOf(isRead).length, 4, 'every read still reads the crown');
+});
+
+await t('a week nobody won is written with no winner, so it stays empty', async () => {
+  reset();
+  const out = await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  const [ins] = callsOf(isInsert);
+  assert.deepEqual(ins.params, ['2026-10-19', null, 0, 0]);
+  assert.equal(out.winner, null);
+});
+
+await t('a failed crowning is not remembered: the next read tries again', async () => {
+  reset();
+  engine.throwOn = isWinner;
+  await assert.rejects(() => botw.readBuilderOfTheWeek({ now: NOW, pool: engine }), /boom/);
+  assert.equal(callsOf(isInsert).length, 0, 'nothing written on a failure');
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  assert.equal(callsOf(isInsert).length, 1);
+});
+
+await t('a new week is crowned on its own first read', async () => {
+  reset();
+  engine.recorded.add('2026-10-19');
+  await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  await botw.readBuilderOfTheWeek({ now: new Date('2026-11-02T00:00:01.000Z'), pool: engine });
+  assert.deepEqual(callsOf(isInsert).map((c) => c.params[0]), ['2026-10-26']);
+});
+
+// ---- 4. the read ----------------------------------------------------------------
+
+await t('the crown is this week’s row only; the past weeks are newest first, capped', async () => {
+  reset();
+  engine.recorded.add('2026-10-19');
+  engine.shown = [shownRow('2026-10-19', 'ana', 1240, 4), shownRow('2026-10-12', 'bo', 300, 1)];
+  const out = await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  assert.deepEqual(out.week, { start: '2026-10-19', end: '2026-10-26' });
+  assert.deepEqual(out.winner, { week_start: '2026-10-19', handle: 'ana', github_login: 'ana', display_name: 'ANA', avatar_url: null, credits: 1240, tasks_shipped: 4 });
+  assert.deepEqual(out.past.map((p) => [p.week_start, p.handle, p.credits]), [['2026-10-12', 'bo', 300]]);
+  // this week's winner hid since (or nobody won): no crown, and last week does not move up into it
+  engine.shown = [shownRow('2026-10-12', 'bo', 300, 1)];
+  const hidden = await botw.readBuilderOfTheWeek({ now: NOW, pool: engine });
+  assert.equal(hidden.winner, null);
+  assert.deepEqual(hidden.past.map((p) => p.week_start), ['2026-10-12']);
+  engine.shown = Array.from({ length: 20 }, (_, i) => shownRow(`2026-0${(i % 9) + 1}-01`, `b${i}`, 10, 1));
+  assert.equal((await botw.readBuilderOfTheWeek({ now: NOW, pool: engine })).past.length, botw.ARCHIVE_WEEKS);
+});
+
+// ---- 5. the route -----------------------------------------------------------------
+
+function serve() {
+  const app = express();
+  app.use(attachFail);
+  app.use('/api/bongos', buildRoutes());
+  const server = app.listen(0, '127.0.0.1');
+  return new Promise((resolve) => server.once('listening', () => resolve(server)));
+}
+function get(server, path_, headers = {}) {
+  return new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port: server.address().port, path: path_, headers }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body, json: body ? JSON.parse(body) : null }));
+    }).on('error', reject);
+  });
+}
+
+const server = await serve();
+const URL_ = '/api/bongos/community/builder-of-the-week';
+
+await t('GET /community/builder-of-the-week: the week, the crown and the past weeks; no-store; the same for every viewer', async () => {
+  reset();
+  engine.shown = [shownRow(botw.crownedWeek().start.toISOString().slice(0, 10), 'ana', 1240, 4)];
+  const anon = await get(server, URL_);
+  assert.equal(anon.status, 200);
+  assert.equal(anon.headers['cache-control'], 'no-store');
+  assert.equal(anon.headers['access-control-allow-origin'], '*');
+  assert.deepEqual(Object.keys(anon.json).sort(), ['past', 'week', 'winner']);
+  assert.equal(anon.json.winner.handle, 'ana');
+  assert.doesNotMatch(anon.body, /github_id/);
+  const signedIn = await get(server, URL_, { Cookie: 'bongos_session=x', Authorization: 'Bearer y' });
+  assert.equal(signedIn.body, anon.body, 'the route reads no session');
+});
+
+await t('a failure is the 500 envelope, never a stack', async () => {
+  reset();
+  engine.throwOn = (sql) => PROBE.test(sql);
+  const r = await get(server, URL_);
+  assert.equal(r.status, 500);
+  assert.equal(r.json.error.code, 'builder_of_the_week_failed');
+  assert.doesNotMatch(r.body, /boom/);
+});
+
+await t('its own rate-limit budget, not the leaderboard’s', () => {
+  const { _internals } = buildRoutes;
+  assert.equal(_internals.WEEK_READ_RATE_SCOPE, 'builder-of-the-week-read');
+  assert.notEqual(_internals.WEEK_READ_RATE_SCOPE, _internals.READ_RATE_SCOPE);
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/builder_of_the_week_db.mjs

@@ -0,0 +1,166 @@
+// tests/builder_of_the_week_db.mjs — task 1002981 (community spec D5; real DB).
+//
+// Proves Builder of the Week against real SQL: which snapshots open and close the
+// week, the shipped-work floor, the tie order, the leaderboard's eligibility, that
+// the first decision is pinned (a later change, a hide, a race) and that a week
+// nobody won is recorded empty. A fake pool can only prove the statements' shape
+// (tests/builder_of_the_week.mjs).
+//
+// The crown is global (every eligible builder on the hub), so every fixture week is
+// in 2099: a shared database's real builders have no snapshot there, their week's
+// delta is zero, and the shipped-work floor keeps them out.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set (scripts/bongos/run-unit-tests.js) so the DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/builder_of_the_week_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const { readBuilderOfTheWeek, crownedWeek, clearCrownMemo } = require('../modules/platform-identity/builder-of-the-week.js');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIG_DIR = join(here, '..', 'modules', 'platform-identity', 'migrations');
+const migrationSql = (f) => readFileSync(join(MIG_DIR, f), 'utf8');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`builder_of_the_week_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const A = 90298101, B = 90298102, C = 90298103, D = 90298104;
+const HIDDEN = 90298105, PRIVATE = 90298106, E = 90298107;
+const IDS = [A, B, C, D, E, HIDDEN, PRIVATE];
+const P1 = 't1002981-p1', P2 = 't1002981-p2';
+const DAY = 24 * 60 * 60 * 1000;
+const NOW = new Date('2099-03-12T10:00:00.000Z');
+const { start, end } = crownedWeek(NOW);
+const at = (base, ms) => new Date(base.getTime() + ms);
+const q = (sql, params) => pool.query(sql, params);
+
+async function cleanup() {
+  await q(`DELETE FROM platform_identity_weekly_features WHERE week_start >= '2099-01-01'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_activity_snapshots WHERE github_id = ANY($1::bigint[])`, [IDS]).catch(() => {});
+  await q(`DELETE FROM platform_identity_builder_project_activity WHERE github_id = ANY($1::bigint[])`, [IDS]).catch(() => {});
+  await q(`DELETE FROM platform_identity_accounts WHERE github_id = ANY($1::bigint[])`, [IDS]).catch(() => {});
+}
+async function account(id, handle, { visibility = 'public', hide = false } = {}) {
+  await q(
+    `INSERT INTO platform_identity_accounts
+       (github_id, github_login, display_name, handle, profile_state, account_visibility, hide_stats, terms_accepted_at)
+     VALUES ($1, $2, $2, $2, 'active', $3, $4, now())`,
+    [id, handle, visibility, hide],
+  );
+}
+// The live row (its numbers do not matter to a past week; first seen long before the
+// week unless said) and a history of snapshots.
+async function builder(id, client, history, firstSeen = at(start, -365 * DAY)) {
+  await q(`INSERT INTO platform_identity_builder_project_activity (client_id, github_id, credits, tasks_shipped, karma, first_seen_at) VALUES ($1, $2, 0, 0, 0, $3)`, [client, id, firstSeen]);
+  for (const [when, credits, ships, karma] of history) {
+    await q(
+      `INSERT INTO platform_identity_activity_snapshots (client_id, github_id, credits, tasks_shipped, karma, reported_at) VALUES ($1, $2, $3, $4, $5, $6)`,
+      [client, id, credits, ships, karma, when],
+    );
+  }
+}
+const recorded = async (week) => (await q(
+  `SELECT github_id::text AS github_id, credits_delta::int AS credits, ships_delta::int AS ships FROM platform_identity_weekly_features WHERE week_start = $1::date`,
+  [week],
+)).rows;
+const read = (now = NOW) => { clearCrownMemo(); return readBuilderOfTheWeek({ now, pool }); };
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+const same = (actual, expected, msg) => { assert.deepEqual(actual, expected, msg); pass++; console.log(`  ok - ${msg}`); };
+
+try {
+  for (const f of [
+    'platform_identity_001_tables.sql', 'platform_identity_005_builder_activity.sql',
+    'platform_identity_007_profile_consent.sql', 'platform_identity_008_handle.sql',
+    'platform_identity_012_account_privacy.sql', 'platform_identity_019_terms_acceptance.sql',
+    'platform_identity_022_activity_snapshots.sql', 'platform_identity_032_weekly_features.sql',
+  ]) await q(migrationSql(f));
+  await cleanup();
+
+  await account(A, 't1002981-a');
+  await account(B, 't1002981-b');
+  await account(C, 't1002981-c');
+  await account(D, 't1002981-d');
+  await account(E, 't1002981-e');
+  await account(HIDDEN, 't1002981-hidden', { hide: true });
+  await account(PRIVATE, 't1002981-private', { visibility: 'private' });
+
+  // A: 350 credits, 3 works, no karma — across two projects. P1 has a snapshot before
+  // the week (the baseline); P2 has none but was first seen in the week (counts from
+  // zero). A snapshot a second AFTER the week closes is not the week's.
+  await builder(A, P1, [[at(start, -3 * DAY), 100, 5, 4], [at(start, 2 * DAY), 400, 7, 4], [at(end, 1000), 99999, 99, 4]]);
+  await builder(A, P2, [[at(start, 3 * DAY), 50, 1, 0]], at(start, 3 * DAY));
+  // E: a lifetime brought into the week — no history before it, and seen before it (or
+  // before first_seen_at existed, NULL). Counting from zero would crown E; neither counts.
+  await builder(E, P1, [[at(start, DAY), 90000, 40, 0]], null);
+  await builder(E, P2, [[at(start, DAY), 90000, 40, 0]]);
+  // C: the same credits and works as A, two more karma — C beats A on karma.
+  await builder(C, P1, [[at(start, -DAY), 0, 0, 0], [at(start, DAY), 360, 3, 2]]);
+  // D: the same credits, the most karma, but one work fewer — works come before karma.
+  await builder(D, P1, [[at(start, -DAY), 0, 0, 0], [at(start, DAY), 350, 2, 9]]);
+  // B: the most credits, but no work shipped in the week (the floor).
+  await builder(B, P1, [[at(start, -DAY), 0, 4, 0], [at(start, DAY), 900, 4, 0]]);
+  // HIDDEN and PRIVATE out-earn everyone, and the leaderboard may not show them.
+  await builder(HIDDEN, P1, [[at(start, -DAY), 0, 0, 0], [at(start, DAY), 5000, 5, 0]]);
+  await builder(PRIVATE, P1, [[at(start, -DAY), 0, 0, 0], [at(start, DAY), 5000, 5, 0]]);
+  // A snapshot exactly at the start belongs to the baseline: C's week is 360 - 10, not 360.
+  await q(`INSERT INTO platform_identity_activity_snapshots (client_id, github_id, credits, tasks_shipped, karma, reported_at) VALUES ($1, $2, 10, 0, 0, $3)`, [P1, C, start]);
+
+  // 1 — the crown, and the row that records it
+  const first = await read();
+  same(first.week, { start: start.toISOString().slice(0, 10), end: end.toISOString().slice(0, 10) }, 'the week is the last full Monday-to-Monday week');
+  same(first.winner && [first.winner.handle, first.winner.credits, first.winner.tasks_shipped], ['t1002981-c', 350, 3], 'ties go to works shipped, then karma; no work, hidden, private and a lifetime brought into the week never win');
+  ok(!('github_id' in first.winner), 'github_id never crosses');
+  same(await recorded(first.week.start), [{ github_id: String(C), credits: 350, ships: 3 }], 'the week is recorded on the first read');
+
+  // 2 — pinned: a later report into the past week, or a builder who goes public, changes nothing
+  await q(`INSERT INTO platform_identity_activity_snapshots (client_id, github_id, credits, tasks_shipped, karma, reported_at) VALUES ($1, $2, 99999, 50, 0, $3)`, [P1, A, at(start, 4 * DAY)]);
+  await q(`UPDATE platform_identity_accounts SET hide_stats = false WHERE github_id = $1`, [HIDDEN]);
+  same((await read()).winner.handle, 't1002981-c', 'the first decision stands');
+  await q(`UPDATE platform_identity_accounts SET hide_stats = true WHERE github_id = $1`, [HIDDEN]);
+
+  // 3 — a winner who hides is not shown, and their week goes to nobody else
+  await q(`UPDATE platform_identity_accounts SET hide_stats = true WHERE github_id = $1`, [C]);
+  same((await read()).winner, null, 'a hidden winner is not drawn');
+  same(await recorded(first.week.start), [{ github_id: String(C), credits: 350, ships: 3 }], 'and the row is never re-crowned');
+
+  // 4 — a later week nobody shipped in (two on, past A's late snapshot) is recorded empty;
+  // the crowned week is in its past list once its winner is shown again
+  const next = at(NOW, 14 * DAY);
+  const empty = await read(next);
+  same(empty.winner, null, 'a week nobody won has no crown');
+  same(await recorded(empty.week.start), [{ github_id: null, credits: 0, ships: 0 }], 'and is recorded empty, so it stays empty');
+  same(empty.past, [], 'the week before is left out while its winner hides');
+  await q(`UPDATE platform_identity_accounts SET hide_stats = false WHERE github_id = $1`, [C]);
+  same((await read(next)).past.map((p) => [p.week_start, p.handle]), [[first.week.start, 't1002981-c']], 'shown again, it is back in the past weeks');
+
+  // 5 — two hub processes crowning the same week at once: one row, no error
+  const third = at(NOW, 21 * DAY);
+  const other = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+  try {
+    clearCrownMemo();
+    const both = await Promise.all([readBuilderOfTheWeek({ now: third, pool }), readBuilderOfTheWeek({ now: third, pool: other })]);
+    same(both.map((b) => b.winner), [null, null], 'both answer');
+    same((await recorded(both[0].week.start)).length, 1, 'one row: ON CONFLICT DO NOTHING');
+  } finally { await other.end().catch(() => {}); }
+
+  console.log(`\nbuilder_of_the_week_db.mjs: ${pass} passed`);
+} finally {
+  clearCrownMemo();
+  await cleanup();
+  await pool.end().catch(() => {});
+}

package/tests/hall_approval_queue.mjs

@@ -188,14 +188,19 @@ await test('open: the queue\'s head, the applied page\'s render, and the words b
   assert.ok(b.classes.has('aq-open'), 'the page behind stops scrolling');
   assert.equal(text(b.q('.aq-eyebrow')), 'approval queue · 1 of 2');
   assert.equal(text(b.q('.aq-title')), 'Home · landing · 1 line rewritten, applied · 1 not applied');
+  assert.equal(b.q('img'), null, 'the words lead: no picture until the artist asks for it');
+  assert.equal(b.requests.filter((r) => r.url.endsWith('/visuals')).length, 0, 'and none is fetched until then');
+  await b.click(b.q('[data-peek]'));
   const img = b.q('img');
   assert.equal(img.attrs.src, url(41, 'after-desktop-light'), 'the AFTER render, desktop, in the hall\'s own mode');
   assert.equal(img.attrs.alt, 'Home, after, desktop, light');
   assert.deepEqual(b.qa('[data-phase]').map((x) => [text(x), x.attrs['aria-pressed']]), [['before', 'false'], ['after', 'true']]);
+  await b.click(b.q('[data-peek]'));
+  assert.equal(b.q('img'), null, 'and it folds away again');
   assert.equal(b.qa('mark').length, 1, 'one applied line carries the mark');
   assert.equal(text(b.q('mark')), 'Agents write the code.');
   assert.match(text(b.q('.aq-line--refused')), /not applied: the page no longer shows it/);
-  assert.equal(b.body.querySelectorAll('img').length, 1, 'a hostile line is text, never markup');
+  assert.equal(b.body.querySelectorAll('img').length, 0, 'a hostile line is text, never markup');
   assert.equal(b.win.pwned, undefined);
   assert.equal(text(b.q('.aq-hint')), 'highlighted: the words you changed');
   assert.deepEqual(b.counts, [2], 'the door hears how many wait');
@@ -205,9 +210,10 @@ await test('open: the queue\'s head, the applied page\'s render, and the words b
 await test('the switches: before and after, desktop and phone, light and dark, each a render of the applied branch', async () => {
   const b = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41) } });
   await b.panel.open(); await settle(); await settle();
+  await b.click(b.q('[data-peek]'));
   await b.click(b.q('[data-phase="before"]'));
   assert.equal(b.q('img').attrs.src, url(41, 'before-desktop-light'));
-  assert.equal(b.qa('mark').length, 0, 'before is the page as it was: nothing marked');
+  assert.equal(b.qa('mark').length, 1, 'the words beside the picture do not change with it');
   await b.click(b.q('[data-device="phone"]'));
   assert.equal(b.q('img').attrs.src, url(41, 'before-phone-light'));
   assert.match(b.q('img').attrs.class, /aq-render--phone/);
@@ -216,17 +222,19 @@ await test('the switches: before and after, desktop and phone, light and dark, e
   assert.equal(b.requests.filter((r) => r.url.endsWith('/visuals')).length, 1, 'the renders are read once per round');
 });
 
-await test('a missing render says what it shows instead; no renders at all means nothing to approve from', async () => {
+await test('a missing render says what it shows instead; no renders at all never blocks the decision', async () => {
   const b = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41, ['after-desktop-dark']) } });
   await b.panel.open(); await settle(); await settle();
+  await b.click(b.q('[data-peek]'));
   assert.equal(b.q('img').attrs.src, url(41, 'after-desktop-dark'));
   assert.equal(text(b.q('.aq-frame__swap')), 'No desktop light render; showing desktop dark.');
   const none = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(41)]: slotsFor(41, []) } });
   await none.panel.open(); await settle(); await settle();
+  assert.ok(!none.q('[data-approve]').disabled, 'the words are what is approved: no picture is needed');
+  await none.click(none.q('[data-peek]'));
   assert.equal(none.q('img'), null);
   assert.match(text(none.q('.aq-frame__note')), /No render is attached/);
-  assert.ok(none.q('[data-approve]').disabled, 'approve waits for a picture of the page');
-  assert.ok(!none.q('[data-open-note]').disabled, 'sending it back does not');
+  assert.ok(!none.q('[data-open-note]').disabled, 'sending it back is open too');
 });
 
 await test('approve and ship: one POST through the host\'s write, then the artboard\'s line and the next page', async () => {
@@ -297,6 +305,24 @@ await test('a builder who may not decide reads the queue with a sentence, not tw
   assert.match(text(b.q('.aq-sealed')), /Only the artist who wrote this page, or another artist/);
 });
 
+await test('open(pageId) lands on that page card, says so when it is not in the queue, and can skip the second read', async () => {
+  const b = bootPanel({ answers: { [APPROVALS]: queueFor(), [vis(42)]: slotsFor(42) } });
+  await b.panel.open('landing:projects');
+  await settle(); await settle();
+  assert.equal(text(b.q('.aq-eyebrow')), 'approval queue · 2 of 2', 'the Projects card, not the head');
+  const miss = bootPanel({ answers: { [APPROVALS]: queueFor() } });
+  await miss.panel.open('landing:nowhere');
+  await settle(); await settle();
+  assert.equal(text(miss.q('.aq-eyebrow')), 'approval queue · 1 of 2');
+  assert.equal(text(miss.q('.aq-error')), 'That page is not waiting for your sign-off right now.');
+  const once = bootPanel({ answers: { [APPROVALS]: queueFor() } });
+  await once.panel.refresh();
+  await once.panel.open(undefined, { reload: false });
+  await settle(); await settle();
+  assert.equal(once.requests.filter((r) => r.url.endsWith('/copy-desk/approvals')).length, 1, 'refreshed once, opened without re-reading');
+  assert.equal(once.panel.notAppliedCount(), 0);
+});
+
 await test('empty, closed with Escape, and focus goes back where it was', async () => {
   const b = bootPanel({ answers: { [APPROVALS]: queueFor({ tasks: [] }) } });
   const opener = { focus() { boot.focused = opener; } };
@@ -391,9 +417,6 @@ await test('a line holding {{productName}} reads as the product name in a chip,
   assert.ok(chips.every((c) => c.attrs['data-hole'] === 'productName' && text(c) === 'Cloud Bongos'));
   assert.ok(b.q('mark').querySelector('.aq-hole'), 'the chip sits inside the changed words\' mark');
   assert.ok(!/\{\{/.test(b.scrim.innerHTML || '') && !/\{\{/.test(text(b.scrim)), 'no raw {{token}} anywhere in the panel');
-  b.scrim.fire('click', { target: b.q('[data-phase="before"]') }); await settle();
-  assert.equal(lineWords(), 'Both are how Cloud Bongos itself works.');
-  assert.equal(asideWords(), 'becomes: This project, Cloud Bongos, has two doors.');
 });
 
 await test('the dialog fits the viewport at every width: capped by the screen, the page shrinks first, rows wrap', () => {
@@ -411,7 +434,8 @@ await test('the dialog fits the viewport at every width: capped by the screen, t
   assert.match(rule('.aq-foot'), /flex-wrap: wrap/);
   assert.match(rule('.aq-body'), /min-width: 0/);
   assert.match(rule('.aq-frame'), /flex-grow: 1;[\s\S]*min-width: 0/, 'the rendered page is what shrinks first');
-  assert.match(rule('.aq-lines'), /width: clamp\(240px, 32%, 300px\)/, 'the words keep the artboard\'s 300 until the page has shrunk');
+  assert.match(rule('.aq-lines'), /min-width: 0/, 'the words take the full width and can shrink');
+  assert.match(rule('.aq-line'), /grid-template-columns: minmax\(0, 1fr\) minmax\(0, 1fr\)/, 'was and now sit side by side');
   assert.match(rule('.aq-line__text'), /overflow-wrap: anywhere/, 'a long word breaks inside its column');
 });