@bongos/core 1.23.18 → 1.23.20

package/tests/community_crowns.mjs

@@ -0,0 +1,369 @@
+// tests/community_crowns.mjs — the builders of the week, the month and the year behind the
+// hub's /community page (task 1004902).
+//
+// DB-free. A fake pool answers each statement by its shape. Which snapshots open and close
+// a month or a year, and that the year's first-snapshot baseline really counts, need a real
+// Postgres: tests/community_crowns_db.mjs.
+//
+// What this pins:
+//   1. the month: the last FULL calendar month (UTC) before now, at every edge.
+//   2. history: a month that began before snapshot history is not crowned, and the answer
+//      names the day the first month will be; no history at all crowns nothing.
+//   3. the month crowned like the week: the week's statement, written once and never
+//      overwritten, crowned once however many reads arrive, read back through the
+//      leaderboard's numbers predicate.
+//   4. the year: live from 1 January with the first-snapshot baseline, memoised for
+//      LEADER_TTL_MS, `since` while history starts inside the year, the leader shown only if
+//      still eligible, asked on every read; the year that ended
+//      crowned on the first read of the next, by the same rule, and shown as `last`.
+//   5. the answer: the three periods, no github_id anywhere.
+//   6. the route: no-store, the same body with or without credentials, the 500 envelope,
+//      and its own rate-limit scope.
+//
+// Run:  node tests/community_crowns.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 } = require('../modules/platform-identity/account-visibility.js');
+const NUMBERS = rollupVisibleSql('pa').replace(/\s+/g, ' ').trim();
+
+// ---- fake engine ------------------------------------------------------------
+
+const WEEK_PROBE = /^SELECT 1 FROM platform_identity_weekly_features WHERE week_start = \$1::date$/;
+const isWeekInsert = (sql) => /^INSERT INTO platform_identity_weekly_features/.test(sql);
+const isWeekRead = (sql) => /FROM platform_identity_weekly_features f\s+JOIN platform_identity_accounts pa/.test(sql);
+const HISTORY = /^SELECT reported_at FROM platform_identity_activity_snapshots ORDER BY id ASC LIMIT 1$/;
+const PERIOD_PROBE = /^SELECT 1 FROM platform_identity_period_features WHERE period = \$1 AND period_start = \$2::date$/;
+const isWinner = (sql) => /^WITH act AS/.test(sql);
+const isYearRule = (sql) => /\) f ON true/.test(sql);
+const isPeriodInsert = (sql) => /^INSERT INTO platform_identity_period_features/.test(sql);
+const isPeriodRead = (sql) => /FROM platform_identity_period_features f JOIN platform_identity_accounts pa/.test(sql);
+const isLeaderRead = (sql) => /FROM platform_identity_accounts pa WHERE pa\.github_id = \$1::bigint/.test(sql);
+const iso = (d) => (d instanceof Date ? d.toISOString() : String(d));
+
+const engine = {
+  calls: [],
+  history: null,        // the first snapshot's reported_at, or null
+  periods: new Set(),   // 'month:2026-10-01' rows the probe finds
+  winners: {},          // 'month' | 'year' | 'week' → the winner statement's row
+  periodShown: {},      // 'month:2026-10-01' → the read's row (already filtered)
+  accounts: {},         // github_id → the leader read's row (already filtered)
+  weekShown: [],
+  throwOn: null,
+  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 (WEEK_PROBE.test(sql)) return { rows: [{ '?column?': 1 }] };
+    if (isWeekRead(sql)) return { rows: engine.weekShown };
+    if (isWeekInsert(sql)) return { rows: [], rowCount: 1 };
+    if (HISTORY.test(sql)) return { rows: engine.history ? [{ reported_at: engine.history }] : [] };
+    if (PERIOD_PROBE.test(sql)) return { rows: engine.periods.has(`${params[0]}:${params[1]}`) ? [{ '?column?': 1 }] : [] };
+    if (isWinner(sql)) {
+      if (engine.slowWinner) await new Promise((r) => setTimeout(r, 10));
+      const w = engine.winners[isYearRule(sql) ? 'year' : 'month'];
+      return { rows: w ? [w] : [] };
+    }
+    if (isPeriodInsert(sql)) { engine.periods.add(`${params[0]}:${params[1]}`); return { rows: [], rowCount: 1 }; }
+    if (isPeriodRead(sql)) { const r = engine.periodShown[`${params[0]}:${params[1]}`]; return { rows: r ? [r] : [] }; }
+    if (isLeaderRead(sql)) { const r = engine.accounts[params[0]]; return { rows: r ? [r] : [] }; }
+    throw new Error(`fake pool: unexpected statement ${sql.slice(0, 80)}`);
+  },
+};
+function reset() {
+  Object.assign(engine, {
+    calls: [], history: null, periods: new Set(), winners: {}, periodShown: {}, accounts: {},
+    weekShown: [], throwOn: null, slowWinner: false,
+  });
+  botw.clearCrownMemo();
+  crowns.clearCrownsMemo();
+}
+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 crowns = require('../modules/platform-identity/community-crowns.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildRoutes = require('../modules/platform-identity/routes/community-leaderboard.js');
+
+const HISTORY_BEGAN = '2026-09-27T14:05:00.000Z';
+const row = (handle, credits, ships) => ({ handle, github_login: handle, display_name: handle.toUpperCase(), avatar_url: null, credits_delta: String(credits), ships_delta: String(ships) });
+const acct = (handle) => ({ handle, github_login: handle, display_name: handle.toUpperCase(), avatar_url: null });
+const read = (now) => crowns.readCrowns({ now: new Date(now), pool: engine });
+
+// ---- 1. the month -----------------------------------------------------------
+
+await t('the crowned month is the last full calendar month (UTC) before now, at every edge', () => {
+  const month = (now) => { const m = crowns.crownedMonth(new Date(now)); return [m.start.toISOString(), m.end.toISOString()]; };
+  const oct = ['2026-10-01T00:00:00.000Z', '2026-11-01T00:00:00.000Z'];
+  assert.deepEqual(month('2026-11-17T09:30:00.000Z'), oct, 'mid-month: the month before this one');
+  assert.deepEqual(month('2026-11-01T00:00:00.000Z'), oct, 'the very first instant of the 1st: the month that just ended');
+  assert.deepEqual(month('2026-11-30T23:59:59.999Z'), oct, 'the last instant of the month: still the same one');
+  assert.deepEqual(month('2026-10-31T23:59:59.999Z'), ['2026-09-01T00:00:00.000Z', '2026-10-01T00:00:00.000Z'], 'the month ending tonight is not over yet');
+  assert.deepEqual(month('2027-01-04T12:00:00.000Z'), ['2026-12-01T00:00:00.000Z', '2027-01-01T00:00:00.000Z'], 'across a year');
+});
+
+// ---- 2. history ----------------------------------------------------------------
+
+await t('a month that began before snapshot history is not crowned; the answer names the first crown', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  const out = await read('2026-10-28T09:30:00.000Z');
+  assert.deepEqual(out.month, { start: '2026-09-01', end: '2026-10-01', winner: null, first_crown: '2026-11-01' });
+  assert.equal(callsOf((s) => PERIOD_PROBE.test(s) && /month/.test(s)).length, 0);
+  assert.equal(callsOf(isPeriodInsert).length, 0, 'nothing recorded: no month is "nobody" for want of data');
+  assert.equal(callsOf((s) => isWinner(s) && !isYearRule(s)).length, 0);
+});
+
+await t('history that begins on the 1st makes that month the first one', async () => {
+  reset();
+  engine.history = '2026-10-01T00:00:00.000Z';
+  assert.equal((await read('2026-10-28T09:30:00.000Z')).month.first_crown, '2026-11-01');
+  reset();
+  engine.history = '2026-10-01T00:00:00.000Z';
+  const nov = await read('2026-11-02T00:00:00.000Z');
+  assert.equal(nov.month.first_crown, null);
+  assert.deepEqual(callsOf(isPeriodInsert).map((c) => c.params.slice(0, 2)), [['month', '2026-10-01']]);
+});
+
+await t('no history at all: nothing computed, nothing written, no first crown to name', async () => {
+  reset();
+  const out = await read('2026-11-02T00:00:00.000Z');
+  assert.deepEqual(out.month, { start: '2026-10-01', end: '2026-11-01', winner: null, first_crown: null });
+  assert.deepEqual(out.year, { start: '2026-01-01', since: '2026-01-01', winner: null, last: null });
+  assert.equal(callsOf(isWinner).length, 0);
+  assert.equal(callsOf(isPeriodInsert).length, 0);
+});
+
+await t('history is asked once per process once it exists, and again while it does not', async () => {
+  reset();
+  await read('2026-10-28T09:30:00.000Z');
+  await read('2026-10-28T09:31:00.000Z');
+  assert.equal(callsOf((s) => HISTORY.test(s)).length, 2, 'no history yet: asked every time');
+  engine.history = HISTORY_BEGAN;
+  await read('2026-10-28T09:32:00.000Z');
+  await read('2026-10-28T09:33:00.000Z');
+  assert.equal(callsOf((s) => HISTORY.test(s)).length, 3);
+});
+
+// ---- 3. the month crowned like the week -------------------------------------------
+
+await t('the month: the week’s statement and rule, written once and never overwritten', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.winners.month = { github_id: '42', credits: '900', tasks_shipped: '3' };
+  await read('2026-11-03T08:00:00.000Z');
+  const [w] = callsOf((s) => isWinner(s) && !isYearRule(s));
+  assert.ok(w.sql.includes(NUMBERS), 'the leaderboard’s numbers predicate');
+  assert.match(w.sql, /HAVING sum\(tasks_shipped\) >= 1/);
+  assert.match(w.sql, /\) b ON true WHERE b\.credits IS NOT NULL OR act\.first_seen_at >= \$1::timestamptz \)/, 'the week’s baseline rule: no lifetime in one month');
+  assert.deepEqual(w.params.map(iso), ['2026-10-01T00:00:00.000Z', '2026-11-01T00:00:00.000Z']);
+  const [ins] = callsOf(isPeriodInsert);
+  assert.match(ins.sql, /ON CONFLICT \(period, period_start\) DO NOTHING$/, 'the first decision stands');
+  assert.doesNotMatch(ins.sql, /DO UPDATE/);
+  assert.deepEqual(ins.params, ['month', '2026-10-01', '42', '900', '3']);
+});
+
+await t('a month nobody won is written with no winner, so it stays empty', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  const out = await read('2026-11-03T08:00:00.000Z');
+  assert.deepEqual(callsOf(isPeriodInsert)[0].params, ['month', '2026-10-01', null, 0, 0]);
+  assert.equal(out.month.winner, null);
+});
+
+await t('a recorded month is never recomputed, and an unrecorded one is crowned once however many reads arrive', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.periods.add('month:2026-10-01');
+  await read('2026-11-03T08:00:00.000Z');
+  assert.equal(callsOf((s) => isWinner(s) && !isYearRule(s)).length, 0);
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.slowWinner = true;
+  engine.winners.month = { github_id: '7', credits: '50', tasks_shipped: '1' };
+  await Promise.all([1, 2, 3, 4].map(() => read('2026-11-03T08:00:00.000Z')));
+  assert.equal(callsOf((s) => isWinner(s) && !isYearRule(s)).length, 1);
+  assert.equal(callsOf((s) => isPeriodInsert(s)).length, 1);
+  assert.equal(callsOf(isPeriodRead).length, 4, 'every read still reads the crown');
+});
+
+await t('the month read: the numbers predicate at read time; a winner who hid since is not drawn', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.periods.add('month:2026-10-01');
+  engine.periodShown['month:2026-10-01'] = row('ana', 1240, 4);
+  const out = await read('2026-11-03T08:00:00.000Z');
+  const [r] = callsOf(isPeriodRead);
+  assert.ok(r.sql.includes(NUMBERS));
+  assert.doesNotMatch(r.sql.match(/^SELECT (.+?) FROM /)[1], /github_id/, 'github_id never crosses');
+  assert.deepEqual(out.month.winner, { handle: 'ana', github_login: 'ana', display_name: 'ANA', avatar_url: null, credits: 1240, tasks_shipped: 4 });
+  delete engine.periodShown['month:2026-10-01'];
+  assert.equal((await read('2026-11-03T08:00:00.000Z')).month.winner, null);
+});
+
+// ---- 4. the year ----------------------------------------------------------------
+
+await t('the year so far: live from 1 January, counting a row with no earlier history from its first snapshot', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.winners.year = { github_id: '9', credits: '3000', tasks_shipped: '12' };
+  engine.accounts['9'] = acct('cy');
+  const out = await read('2026-10-28T09:30:00.000Z');
+  const [y] = callsOf(isYearRule);
+  assert.ok(y.sql.includes(NUMBERS));
+  assert.match(y.sql, /COALESCE\(e\.credits, 0\)::bigint - COALESCE\(b\.credits, CASE WHEN act\.first_seen_at >= \$1::timestamptz THEN 0 ELSE f\.credits END, 0\) AS credits/);
+  assert.match(y.sql, /AND s\.reported_at > \$1::timestamptz AND s\.reported_at <= \$2::timestamptz ORDER BY s\.reported_at ASC, s\.id ASC LIMIT 1 \) f ON true/, 'the first snapshot inside the year');
+  assert.match(y.sql, /WHERE b\.credits IS NOT NULL OR act\.first_seen_at >= \$1::timestamptz OR f\.credits IS NOT NULL \)/);
+  assert.deepEqual(y.params.map(iso), ['2026-01-01T00:00:00.000Z', '2026-10-28T09:30:00.000Z']);
+  const [l] = callsOf(isLeaderRead);
+  assert.ok(l.sql.includes(NUMBERS), 'the leader is shown only while eligible');
+  assert.deepEqual(out.year, {
+    start: '2026-01-01', since: '2026-09-27', last: null,
+    winner: { handle: 'cy', github_login: 'cy', display_name: 'CY', avatar_url: null, credits: 3000, tasks_shipped: 12 },
+  });
+  assert.equal(callsOf((s) => isPeriodInsert(s)).length, 0, 'a year so far is never written');
+});
+
+await t('the year so far is recomputed once its memo is older than LEADER_TTL_MS, and a leader who cannot be shown is no leader', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.winners.year = { github_id: '9', credits: '3000', tasks_shipped: '12' };
+  assert.equal((await read('2026-10-28T09:30:00.000Z')).year.winner, null);
+  engine.accounts['9'] = acct('cy');
+  assert.equal((await read('2026-10-28T09:31:00.000Z')).year.winner.handle, 'cy');
+  assert.equal(callsOf(isYearRule).length, 2);
+});
+
+await t('inside the memo the leader is not recomputed, but whether they may be shown is asked every read', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.winners.year = { github_id: '9', credits: '3000', tasks_shipped: '12' };
+  engine.accounts['9'] = acct('cy');
+  const t0 = Date.parse('2026-10-28T09:30:00.000Z');
+  assert.equal((await read(t0)).year.winner.handle, 'cy');
+  delete engine.accounts['9']; // the leader hides
+  assert.equal((await read(t0 + crowns.LEADER_TTL_MS - 1)).year.winner, null, 'a hide beats the memo');
+  assert.equal(callsOf(isYearRule).length, 1, 'one computation inside the memo');
+  assert.equal(callsOf(isLeaderRead).length, 2, 'the visibility read every time');
+  await read(t0 + crowns.LEADER_TTL_MS);
+  assert.equal(callsOf(isYearRule).length, 2, 'and a fresh one once it is stale');
+  await read(t0 - 1000);
+  assert.equal(callsOf(isYearRule).length, 3, 'a clock that runs backwards is never served from the memo');
+});
+
+await t('the year that ended is crowned on the first read of the next, by the year’s rule, and shown as last', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.winners.year = { github_id: '9', credits: '3000', tasks_shipped: '12' };
+  engine.accounts['9'] = acct('cy');
+  engine.periodShown['year:2026-01-01'] = row('cy', 3100, 13);
+  const out = await read('2027-01-02T10:00:00.000Z');
+  const crowned = callsOf(isYearRule).find((c) => iso(c.params[1]) === '2027-01-01T00:00:00.000Z');
+  assert.deepEqual(crowned.params.map(iso), ['2026-01-01T00:00:00.000Z', '2027-01-01T00:00:00.000Z']);
+  assert.deepEqual(callsOf(isPeriodInsert).map((c) => c.params.slice(0, 2)), [['month', '2026-12-01'], ['year', '2026-01-01']]);
+  assert.equal(out.year.start, '2027-01-01');
+  assert.equal(out.year.since, '2027-01-01', 'history began before this year');
+  assert.deepEqual(out.year.last, { start: '2026-01-01', winner: { handle: 'cy', github_login: 'cy', display_name: 'CY', avatar_url: null, credits: 3100, tasks_shipped: 13 } });
+});
+
+await t('a year that ended before history began is never crowned', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  await read('2026-10-28T09:30:00.000Z');
+  assert.equal(callsOf((s) => PERIOD_PROBE.test(s)).filter((c) => c.params[0] === 'year').length, 0);
+});
+
+// ---- 5. the answer -----------------------------------------------------------------
+
+await t('the three periods, the week as builder-of-the-week.js decides it, and no github_id anywhere', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.weekShown = [{ week_start: '2026-10-19', ...row('ana', 120, 2) }];
+  engine.winners.year = { github_id: '9', credits: '3000', tasks_shipped: '12' };
+  engine.accounts['9'] = acct('cy');
+  const out = await read('2026-10-28T09:30:00.000Z');
+  assert.deepEqual(Object.keys(out), ['week', 'month', 'year']);
+  assert.deepEqual(out.week, { start: '2026-10-19', end: '2026-10-26', winner: { handle: 'ana', github_login: 'ana', display_name: 'ANA', avatar_url: null, credits: 120, tasks_shipped: 2 } });
+  assert.doesNotMatch(JSON.stringify(out), /github_id|"9"/);
+});
+
+// ---- 6. 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/crowns';
+
+await t('GET /community/crowns: the three periods; no-store; CORS-open; the same for every viewer', async () => {
+  reset();
+  engine.history = HISTORY_BEGAN;
+  engine.winners.year = { github_id: '9', credits: '3000', tasks_shipped: '12' };
+  engine.accounts['9'] = acct('cy');
+  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), ['week', 'month', 'year']);
+  assert.equal(anon.json.year.winner.handle, 'cy');
+  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) => HISTORY.test(sql);
+  const r = await get(server, URL_);
+  assert.equal(r.status, 500);
+  assert.equal(r.json.error.code, 'community_crowns_failed');
+  assert.doesNotMatch(r.body, /boom/);
+});
+
+await t('its own rate-limit budget, not the leaderboard’s or the week’s', () => {
+  const { _internals } = buildRoutes;
+  assert.equal(_internals.CROWNS_READ_RATE_SCOPE, 'community-crowns-read');
+  assert.equal(new Set([_internals.CROWNS_READ_RATE_SCOPE, _internals.READ_RATE_SCOPE, _internals.WEEK_READ_RATE_SCOPE]).size, 3);
+});
+
+server.close();
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);

package/tests/community_crowns_db.mjs

@@ -0,0 +1,164 @@
+// tests/community_crowns_db.mjs — task 1004902 (the builders of the month and the year;
+// real DB).
+//
+// Proves against real SQL what a fake pool cannot (tests/community_crowns.mjs): the month
+// keeps the week's rule (a lifetime brought into the month never counts), the year counts
+// that same row from its first snapshot inside the year and never its lifetime, a row first
+// seen in the year counts from zero, the month is pinned against a later report, a hide
+// and a race, and the year that ended is crowned on the next year's first read.
+//
+// The crowns are global (every eligible builder on the hub), so every fixture period is in
+// 2099: a shared database's real builders have no snapshot there, their 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/community_crowns_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 { clearCrownMemo } = require('../modules/platform-identity/builder-of-the-week.js');
+const { readCrowns, clearCrownsMemo } = require('../modules/platform-identity/community-crowns.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(`community_crowns_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const M = 90490201, L = 90490202, N = 90490203, Y = 90490204, HIDDEN = 90490205;
+const IDS = [M, L, N, Y, HIDDEN];
+const P1 = 't1004902-p1';
+const NOW = new Date('2099-03-12T10:00:00.000Z');
+const NEXT_YEAR = new Date('2100-01-02T10:00:00.000Z');
+const d = (iso) => new Date(iso);
+const q = (sql, params) => pool.query(sql, params);
+
+async function cleanup() {
+  await q(`DELETE FROM platform_identity_period_features WHERE period_start >= '2099-01-01'`).catch(() => {});
+  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, { 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', 'public', $3, now())`,
+    [id, handle, hide],
+  );
+}
+async function builder(id, history, firstSeen) {
+  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)`, [P1, id, firstSeen]);
+  for (const [when, credits, ships] 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, 0, $5)`,
+      [P1, id, credits, ships, d(when)],
+    );
+  }
+}
+const recorded = async (period, start) => (await q(
+  `SELECT github_id::text AS github_id, credits_delta::int AS credits, ships_delta::int AS ships
+     FROM platform_identity_period_features WHERE period = $1 AND period_start = $2::date`,
+  [period, start],
+)).rows;
+const read = (now = NOW, p = pool) => { clearCrownMemo(); clearCrownsMemo(); return readCrowns({ now, pool: p }); };
+const who = (w) => w && [w.handle, w.credits, w.tasks_shipped];
+
+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',
+    'platform_identity_033_period_features.sql',
+  ]) await q(migrationSql(f));
+  await cleanup();
+
+  await account(M, 't1004902-m');
+  await account(L, 't1004902-l');
+  await account(N, 't1004902-n');
+  await account(Y, 't1004902-y');
+  await account(HIDDEN, 't1004902-hidden', { hide: true });
+
+  // Y: history before the year — 400 credits and 3 works in it, all in March.
+  await builder(Y, [['2098-12-20T00:00:00Z', 0, 0], ['2099-03-05T00:00:00Z', 400, 3]], d('2098-06-01T00:00:00Z'));
+  // M: history before February — 250 credits and 2 works in February. In the year it has
+  // no snapshot before 1 January, so it counts from its first one inside (0).
+  await builder(M, [['2099-01-20T00:00:00Z', 0, 0], ['2099-02-10T00:00:00Z', 250, 2]], d('2098-06-01T00:00:00Z'));
+  // L: a lifetime brought into February — no history before it, seen before first_seen_at
+  // existed (NULL). Its first snapshot is 90000; it then earns 500 and two works. The month
+  // never counts it; the year counts 500, never 90500.
+  await builder(L, [['2099-02-03T00:00:00Z', 90000, 40], ['2099-02-12T00:00:00Z', 90500, 42]], null);
+  // N: first seen in the year, so counted from zero: 300 and a work.
+  await builder(N, [['2099-02-02T00:00:00Z', 300, 1]], d('2099-02-01T00:00:00Z'));
+  // HIDDEN out-earns everyone in both, and the leaderboard may not show them.
+  await builder(HIDDEN, [['2098-12-20T00:00:00Z', 0, 0], ['2099-02-05T00:00:00Z', 9000, 9]], d('2098-06-01T00:00:00Z'));
+
+  // 1 — the month: the week's rule
+  const first = await read();
+  same([first.month.start, first.month.end, first.month.first_crown], ['2099-02-01', '2099-03-01', null], 'the month is the last full calendar month');
+  same(who(first.month.winner), ['t1004902-n', 300, 1], 'the month: a row first seen in it counts from zero; a lifetime brought into it never counts; hidden never wins');
+  ok(!('github_id' in first.month.winner), 'github_id never crosses');
+  same(await recorded('month', '2099-02-01'), [{ github_id: String(N), credits: 300, ships: 1 }], 'the month is recorded on the first read');
+
+  // 2 — the year so far: the first snapshot inside the year is the baseline
+  same([first.year.start, first.year.since], ['2099-01-01', '2099-01-01'], 'history began before the year');
+  same(who(first.year.winner), ['t1004902-l', 500, 2], 'the year counts L from its first snapshot inside it — 500, not its 90500 lifetime — and that beats Y’s 400 and N’s 300');
+  same(await recorded('year', '2099-01-01'), [], 'a year so far is never written');
+
+  // 3 — pinned: a later report into the past month, 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, M, d('2099-02-20T00:00:00Z')]);
+  await q(`UPDATE platform_identity_accounts SET hide_stats = false WHERE github_id = $1`, [HIDDEN]);
+  same(who((await read()).month.winner), ['t1004902-n', 300, 1], 'the first decision stands');
+  await q(`UPDATE platform_identity_accounts SET hide_stats = true WHERE github_id = $1`, [HIDDEN]);
+
+  // 4 — a winner who hides is not shown, and their month goes to nobody else
+  await q(`UPDATE platform_identity_accounts SET hide_stats = true WHERE github_id = $1`, [N]);
+  same((await read()).month.winner, null, 'a hidden winner is not drawn');
+  same(await recorded('month', '2099-02-01'), [{ github_id: String(N), credits: 300, ships: 1 }], 'and the row is never re-crowned');
+  await q(`UPDATE platform_identity_accounts SET hide_stats = false WHERE github_id = $1`, [N]);
+
+  // 5 — the year that ended, crowned on the next year's first read by the year's rule
+  // (M's late February report now leads it), and shown as last
+  const later = await read(NEXT_YEAR);
+  same(await recorded('year', '2099-01-01'), [{ github_id: String(M), credits: 99999, ships: 50 }], 'the year is recorded on the next year’s first read');
+  same(later.year.last && [later.year.last.start, ...who(later.year.last.winner)], ['2099-01-01', 't1004902-m', 99999, 50], 'and shown as last year');
+  same(later.year.winner, null, 'nobody has earned in the new year yet');
+
+  // 6 — two hub processes crowning the same month at once: one row, no error
+  const other = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+  try {
+    clearCrownMemo();
+    clearCrownsMemo();
+    const at = d('2099-05-03T00:00:00Z');
+    const both = await Promise.all([readCrowns({ now: at, pool }), readCrowns({ now: at, pool: other })]);
+    same(both.map((b) => b.month.winner), [null, null], 'both answer');
+    same((await recorded('month', '2099-04-01')).length, 1, 'one row: ON CONFLICT DO NOTHING');
+  } finally { await other.end().catch(() => {}); }
+
+  console.log(`\ncommunity_crowns_db.mjs: ${pass} passed`);
+} finally {
+  clearCrownMemo();
+  clearCrownsMemo();
+  await cleanup();
+  await pool.end().catch(() => {});
+}