@bongos/core 1.19.1025 → 1.19.1027

package/tests/community_leaderboard_db.mjs

@@ -0,0 +1,202 @@
+// tests/community_leaderboard_db.mjs — task 1002978 (community spec D2/D3; real DB).
+//
+// Proves the windowed leaderboard's arithmetic and eligibility against real
+// SQL. The window math is a LATERAL "last snapshot at-or-before the window
+// start" probe per (project, builder) plus a cross-project sum, and a fake pool
+// can only prove the statement's SHAPE (tests/community_leaderboard_route.mjs);
+// only a real Postgres can prove which snapshot becomes the baseline, that a
+// missing baseline counts as zero, and that the privacy matrix really filters.
+//
+// Every fixture carries a discipline no real builder holds, and every read
+// filters on it, so a shared database's own builders never enter the board
+// under test.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set (scripts/gds/run-unit-tests.js) so the DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=... node tests/community_leaderboard_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 { listLeaderboard, clearTotalsMemo } = require('../modules/platform-identity/community-leaderboard.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_leaderboard_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+// High-numbered fixture ids so a shared DB can never collide with real data.
+const A = 90297801, B = 90297802, C = 90297803, D = 90297804, OPTOUT = 90297805;
+const HIDDEN = 90297806, PRIVATE = 90297807, PROV = 90297808, LEGACY = 90297809, BIG = 90297810;
+const IDS = [A, B, C, D, OPTOUT, HIDDEN, PRIVATE, PROV, LEGACY, BIG];
+const P1 = 't1002978-p1', P2 = 't1002978-p2';
+const TAG = 't1002978-board';     // every fixture holds it; every read filters on it
+const TAG_ART = 't1002978-art';   // held by A on P2 only — the union filter
+const TAG_BIG = 't1002978-big';   // BIG's own board, so its totals stay out of the others
+const INT4_MAX = 2147483647;
+const NOW = new Date('2026-06-01T12:00:00.000Z');
+const DAY = 24 * 60 * 60 * 1000;
+const ago = (days, extraMs = 0) => new Date(NOW.getTime() - days * DAY + extraMs);
+const q = (sql, params) => pool.query(sql, params);
+
+async function cleanup() {
+  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, { state = 'active', visibility = 'public', hide = false, accepted = true, reach = null } = {}) {
+  await q(
+    `INSERT INTO platform_identity_accounts
+       (github_id, github_login, display_name, handle, profile_state, account_visibility, hide_stats, recruiter_discoverable, terms_accepted_at)
+     VALUES ($1, $2, $2, $2, $3, $4, $5, $6, CASE WHEN $7::boolean THEN now() END)`,
+    [id, handle, state, visibility, hide, reach, accepted],
+  );
+}
+async function activity(id, client, credits, ships, karma, disciplines = [TAG]) {
+  await q(
+    `INSERT INTO platform_identity_builder_project_activity (client_id, github_id, credits, tasks_shipped, karma, disciplines)
+     VALUES ($1, $2, $3, $4, $5, $6)`,
+    [client, id, credits, ships, karma, disciplines],
+  );
+}
+async function snapshot(id, client, credits, ships, karma, at) {
+  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, at],
+  );
+}
+
+const board = async (window, discipline = TAG) =>
+  (await listLeaderboard({ window, discipline, limit: 100, now: NOW, pool })).results;
+const row = (results, handle) => results.find((r) => r.handle === handle);
+const totals = (r) => r && [r.credits, r.tasks_shipped, r.karma];
+
+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 {
+  // The module's own migrations (idempotent) — every column the NUMBERS
+  // predicate and the board read: 007 consent + hide, 008 handle, 012 privacy,
+  // 019 the terms half of consent, 005/022 the two tables the window reads.
+  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',
+  ]) await q(migrationSql(f));
+  await cleanup();
+
+  await account(A, 't1002978-a');
+  await account(B, 't1002978-b');
+  await account(C, 't1002978-c');
+  await account(D, 't1002978-d');
+  await account(OPTOUT, 't1002978-optout', { reach: false });
+  await account(HIDDEN, 't1002978-hidden', { hide: true });
+  await account(PRIVATE, 't1002978-private', { visibility: 'private' });
+  await account(PROV, 't1002978-prov', { state: 'provisional', accepted: false });
+  await account(LEGACY, 't1002978-legacy', { accepted: false }); // active, but never accepted the terms
+
+  // A: two projects. P1 has history; P2 has none (a builder not seen since
+  // snapshots began — the day-one case the spec accepts).
+  await activity(A, P1, 200, 9, 3);
+  await snapshot(A, P1, 100, 5, 2, ago(40));
+  await snapshot(A, P1, 150, 7, 3, ago(10));
+  await snapshot(A, P1, 200, 9, 3, ago(2));
+  await activity(A, P2, 30, 1, 0, [TAG, TAG_ART]);
+  // B: unchanged for the last 20 days.
+  await activity(B, P1, 500, 10, 1);
+  await snapshot(B, P1, 500, 10, 1, ago(20));
+  // C: a snapshot EXACTLY at the 7d start, and one a second after it.
+  await activity(C, P1, 45, 2, 0);
+  await snapshot(C, P1, 40, 2, 0, ago(7));
+  await snapshot(C, P1, 42, 2, 0, ago(7, 1000));
+  // D: lost credits inside the week (a clawback).
+  await activity(D, P1, 90, 3, 5);
+  await snapshot(D, P1, 100, 3, 5, ago(10));
+  await activity(OPTOUT, P1, 60, 2, 0);
+  // Out of the matrix — every one would top the board if it leaked.
+  for (const id of [HIDDEN, PRIVATE, PROV, LEGACY]) await activity(id, P1, 9000, 90, 9);
+  await account(BIG, 't1002978-big');
+  await activity(BIG, P1, INT4_MAX, 1, 0, [TAG_BIG]);
+  await activity(BIG, P2, INT4_MAX, 1, 0, [TAG_BIG]);
+  await snapshot(BIG, P1, -INT4_MAX, 0, 0, ago(10));
+
+  // 1 — all-time: the live rows summed across projects, no baseline.
+  const all = await board('all');
+  same(all.map((r) => r.handle), ['t1002978-b', 't1002978-a', 't1002978-d', 't1002978-optout', 't1002978-c'],
+    'all-time ranks by summed credits');
+  same(totals(row(all, 't1002978-a')), [230, 10, 3], 'all-time sums a builder across both projects');
+  same(all.map((r) => r.place), [1, 2, 3, 4, 5], 'place numbers the board from 1');
+
+  // 2 — the privacy matrix, against the real predicate.
+  for (const window of ['all', '7d', '30d', '365d']) {
+    const handles = (await board(window)).map((r) => r.handle);
+    for (const h of ['t1002978-hidden', 't1002978-private', 't1002978-prov', 't1002978-legacy']) {
+      assert.ok(!handles.includes(h), `${h} leaked onto the ${window} board`);
+    }
+  }
+  pass++; console.log('  ok - hidden, private, provisional and never-accepted builders are absent from every window');
+  ok(row(all, 't1002978-optout'), 'a builder who opted out of RECRUITING still appears (spec D3)');
+
+  // 3 — 7d: live minus the last snapshot at-or-before the start, summed.
+  const week = await board('7d');
+  same(totals(row(week, 't1002978-a')), [80, 3, 0],
+    '7d: P1 counts from the 10-day-old snapshot, P2 (no history) counts in full');
+  same(totals(row(week, 't1002978-c')), [5, 0, 0],
+    '7d: a snapshot exactly at the window start IS the baseline; one a second later is not');
+  same(totals(row(week, 't1002978-d')), [-10, 0, 0], '7d: a loss inside the window is a negative delta, not hidden');
+  ok(!row(week, 't1002978-b'), '7d: a builder with no movement in the window is left off the board');
+  same(week.map((r) => r.handle), ['t1002978-a', 't1002978-optout', 't1002978-c', 't1002978-d'],
+    '7d ranks by the window delta, a loss last');
+
+  // 4 — 30d and 365d.
+  const month = await board('30d');
+  same(totals(row(month, 't1002978-a')), [130, 5, 1], '30d: P1 counts from the 40-day-old snapshot');
+  same(totals(row(month, 't1002978-b')), [500, 10, 1],
+    '30d: a builder whose first snapshot is inside the window has no baseline, so counts in full');
+  const year = await board('365d');
+  same(totals(row(year, 't1002978-a')), [230, 10, 3], '365d: no snapshot is old enough, so everything counts');
+
+  // 5 — the discipline filter is the builder's union across projects.
+  const art = await board('all', TAG_ART);
+  same(art.map((r) => r.handle), ['t1002978-a'], 'a discipline held on ONE project admits the builder');
+  same(totals(art[0]), [230, 10, 3], 'the filter picks builders, not projects — totals stay whole');
+  same(art[0].disciplines, [TAG_ART, TAG].sort(), 'disciplines is the de-duplicated union');
+
+  // 6 — instance-reported int4 totals cannot overflow the board into a 500.
+  same(totals((await board('all', TAG_BIG))[0]), [2 * INT4_MAX, 2, 0], 'all-time: two int4-max projects sum past int4');
+  same(totals((await board('7d', TAG_BIG))[0]), [3 * INT4_MAX, 2, 0], '7d: int4-max minus a negative baseline does not overflow');
+
+  // 7 — paging keeps the board's own place numbers.
+  const page2 = (await listLeaderboard({ window: 'all', discipline: TAG, limit: 2, offset: 2, now: NOW, pool })).results;
+  same(page2.map((r) => [r.place, r.handle]), [[3, 't1002978-d'], [4, 't1002978-optout']], 'offset pages keep place');
+
+  // 8 — the memoized path (no `now`) against real SQL: hiding beats the memo.
+  clearTotalsMemo();
+  const memo = async () => (await listLeaderboard({ window: 'all', discipline: TAG, limit: 100, pool })).results;
+  ok(row(await memo(), 't1002978-a'), 'the memoized all-time board lists A');
+  await q(`UPDATE platform_identity_accounts SET hide_stats = true WHERE github_id = $1`, [A]);
+  ok(!row(await memo(), 't1002978-a'), 'A hides inside the memo TTL and is gone on the very next request');
+  clearTotalsMemo();
+
+  console.log(`\ncommunity_leaderboard_db.mjs: ${pass} passed`);
+} finally {
+  await cleanup();
+  await pool.end().catch(() => {});
+}

package/tests/community_leaderboard_route.mjs

@@ -0,0 +1,414 @@
+// tests/community_leaderboard_route.mjs
+//
+// Guards GET /community/leaderboard — the PUBLIC windowed leaderboard (D3,
+// docs/specs/bongos-v1-community-tab.md; task 1002978). DB-free. A fake pool
+// asserts that BOTH real statements — the memoized window totals and the
+// per-request eligibility read — carry the shared NUMBERS predicate
+// (rollupVisibleSql('pa'), imported from account-visibility.js) and NOT the
+// recruiting directory's (scoutingListableSql). Which rows the fake returns is
+// a fixture simulation using the same JS twin (isRollupVisible); the window
+// arithmetic and the matrix against real SQL are tests/community_leaderboard_db.mjs.
+//
+// What this pins:
+//   1. the pure helpers — windows, windowStart, the limit clamp.
+//   2. the statements: predicate present in both, recruiting predicate absent,
+//      $1 = the window start (null for all-time).
+//   3. the memo: one totals computation per window per TTL however many
+//      requests, a builder who hides mid-TTL gone on the very next request, a
+//      failed computation never cached.
+//   4. the route: 400s on a bad window or oversized discipline, the default
+//      window, ranking + `place` numbering across pages, github_id never
+//      crosses, the same body with or without credentials, no-store, the 500
+//      path, and the per-IP rate limit.
+//
+// Run:  node tests/community_leaderboard_route.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 {
+  isRollupVisible, rollupVisibleSql, scoutingListableSql,
+} = require('../modules/platform-identity/account-visibility.js');
+
+// ---- fake engine ------------------------------------------------------------
+
+const ACCEPTED_AT = '2026-08-29T00:00:00.000Z';
+const account = (id, handle, extra = {}) => ({
+  github_id: id, handle, github_login: handle.replace(/-/g, ''), display_name: handle, avatar_url: null,
+  profile_state: 'active', terms_accepted_at: ACCEPTED_AT, account_visibility: 'public', hide_stats: false,
+  recruiter_discoverable: null, ...extra,
+});
+
+// Deliberately NOT in rank order — the module ranks, the fake does not.
+const BOARD = [
+  { acct: account('205', 'third-builder'), credits: 50, tasks_shipped: 1, karma: 0, disciplines: ['artist', 'engineer'] },
+  { acct: account('201', 'hidden-builder', { hide_stats: true }), credits: 250, tasks_shipped: 8, karma: 1, disciplines: ['artist'] },
+  { acct: account('200', 'top-builder'), credits: 300, tasks_shipped: 9, karma: 4, disciplines: ['engineer'] },
+  { acct: account('202', 'private-builder', { account_visibility: 'private' }), credits: 240, tasks_shipped: 7, karma: 1, disciplines: ['engineer'] },
+  { acct: account('203', 'prov-builder', { profile_state: 'provisional', terms_accepted_at: null }), credits: 230, tasks_shipped: 7, karma: 1, disciplines: ['engineer'] },
+  // Opted out of RECRUITING only — spec D3: that opt-out does not touch a leaderboard.
+  { acct: account('204', 'optout-builder', { recruiter_discoverable: false }), credits: 120, tasks_shipped: 3, karma: 0, disciplines: ['ui'] },
+  // Ties top-builder on every number: the handle decides, so it ranks second.
+  { acct: account('206', 'twin-builder'), credits: 300, tasks_shipped: 9, karma: 4, disciplines: ['ui'] },
+];
+const byId = (id) => BOARD.find((r) => r.acct.github_id === String(id));
+
+const isTotals = (sql) => /platform_identity_activity_snapshots/.test(sql);
+const engine = {
+  calls: [],
+  throwOnQuery: null,
+  query: async (text, params = []) => {
+    const sql = String(text);
+    engine.calls.push({ sql, params });
+    if (engine.throwOnQuery) throw engine.throwOnQuery;
+    if (isTotals(sql)) {
+      // node-postgres hands int8 back as a string — the shape the real sums arrive in.
+      return {
+        rows: BOARD.filter((r) => isRollupVisible(r.acct)).map((r) => ({
+          github_id: r.acct.github_id, credits: String(r.credits), tasks_shipped: String(r.tasks_shipped),
+          karma: String(r.karma), disciplines: r.disciplines,
+        })),
+      };
+    }
+    assert.match(sql, /github_id = ANY\(\$1::bigint\[\]\)/, 'the only other statement is the eligibility read');
+    const [ids] = params;
+    return {
+      rows: ids.map(byId).filter((r) => r && isRollupVisible(r.acct)).map((r) => ({
+        github_id: r.acct.github_id, handle: r.acct.handle, github_login: r.acct.github_login,
+        display_name: r.acct.display_name, avatar_url: r.acct.avatar_url,
+      })),
+    };
+  },
+};
+const totalsCalls = () => engine.calls.filter((c) => isTotals(c.sql));
+const lastTotalsCall = () => totalsCalls()[totalsCalls().length - 1];
+
+// 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 lb = require('../modules/platform-identity/community-leaderboard.js');
+const { createReadRateLimit } = require('../modules/platform-identity/read-rate-limit.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+const buildLeaderboardRoutes = require('../modules/platform-identity/routes/community-leaderboard.js');
+
+// ---- pure helpers -------------------------------------------------------------
+
+await t('the four spec windows, and nothing else', () => {
+  assert.deepEqual([...lb.WINDOWS], ['7d', '30d', '365d', 'all']);
+  for (const w of lb.WINDOWS) assert.ok(lb.isWindow(w), w);
+  for (const w of ['1d', '7D', '', 'toString', '__proto__', undefined, ['7d']]) assert.ok(!lb.isWindow(w), String(w));
+  assert.equal(lb.DEFAULT_WINDOW, 'all');
+});
+
+await t('windowStart: exactly N days before now; all-time has no start', () => {
+  const now = new Date('2026-09-25T12:00:00.000Z');
+  assert.equal(lb.windowStart('7d', now).toISOString(), '2026-09-18T12:00:00.000Z');
+  assert.equal(lb.windowStart('30d', now).toISOString(), '2026-08-26T12:00:00.000Z');
+  assert.equal(lb.windowStart('365d', now).toISOString(), '2025-09-25T12:00:00.000Z');
+  assert.equal(lb.windowStart('all', now), null);
+});
+
+await t('clampLimit: default, cap, garbage', () => {
+  assert.equal(lb.clampLimit(undefined), lb.DEFAULT_LIMIT);
+  assert.equal(lb.clampLimit('x'), lb.DEFAULT_LIMIT);
+  assert.equal(lb.clampLimit(0), lb.DEFAULT_LIMIT);
+  assert.equal(lb.clampLimit(10), 10);
+  assert.equal(lb.clampLimit(99999), lb.MAX_LIMIT);
+});
+
+await t('listLeaderboard refuses an unknown window rather than guessing one', async () => {
+  await assert.rejects(() => lb.listLeaderboard({ window: '2d', pool: engine }), /unknown window/);
+});
+
+// ---- the statements -------------------------------------------------------------
+
+await t('both statements join rollupVisibleSql — the NUMBERS predicate — and neither the recruiting one', async () => {
+  lb.clearTotalsMemo();
+  engine.calls = [];
+  await lb.listLeaderboard({ window: 'all', pool: engine });
+  assert.equal(engine.calls.length, 2, 'the window totals, then the eligibility read');
+  for (const { sql } of engine.calls) {
+    assert.ok(sql.includes(rollupVisibleSql('pa')), "must join rollupVisibleSql('pa') — active + public + not hidden");
+    assert.ok(!sql.includes(scoutingListableSql('pa')),
+      'must NOT join scoutingListableSql — the recruiting opt-out governs the directory only (spec D3)');
+  }
+  const { sql } = lastTotalsCall();
+  assert.match(sql, /s\.reported_at <= \$1::timestamptz/, 'the baseline is the last snapshot AT-OR-BEFORE the window start');
+  assert.match(sql, /COALESCE\(b\.credits, 0\)/, 'a missing baseline counts as zero (spec D2)');
+  assert.match(sql, /sum\(credits\)::bigint/, 'sums are bigint, so an extreme report cannot overflow the board');
+});
+
+await t('all-time binds no window start; a window binds exactly its start', async () => {
+  const now = new Date('2026-09-25T12:00:00.000Z');
+  await lb.listLeaderboard({ window: 'all', now, pool: engine });
+  assert.equal(lastTotalsCall().params[0], null);
+  await lb.listLeaderboard({ window: '7d', now, pool: engine });
+  assert.equal(lastTotalsCall().params[0].toISOString(), '2026-09-18T12:00:00.000Z');
+});
+
+await t('ranked credits → ships → karma → handle, with a trimmed discipline filter and clamped paging', async () => {
+  const all = await lb.listLeaderboard({ window: 'all', pool: engine });
+  assert.deepEqual(all.results.map((r) => r.handle), ['top-builder', 'twin-builder', 'optout-builder', 'third-builder']);
+  const eng = await lb.listLeaderboard({ window: 'all', discipline: '  engineer  ', limit: 5000, offset: 1, pool: engine });
+  assert.deepEqual(eng.results.map((r) => [r.place, r.handle]), [[2, 'third-builder']]);
+  assert.equal(eng.limit, lb.MAX_LIMIT);
+});
+
+// ---- the memo -------------------------------------------------------------------
+
+await t('many requests for one window compute its totals once; another window computes its own', async () => {
+  lb.clearTotalsMemo();
+  engine.calls = [];
+  for (let i = 0; i < 5; i++) await lb.listLeaderboard({ window: '30d', pool: engine });
+  assert.equal(totalsCalls().length, 1, 'the expensive half ran once for five requests');
+  assert.equal(engine.calls.length - totalsCalls().length, 5, 'the eligibility read ran on every request');
+  await lb.listLeaderboard({ window: '7d', pool: engine });
+  assert.equal(totalsCalls().length, 2);
+});
+
+await t('a builder who hides mid-TTL leaves the board on the very next request (hide beats the memo)', async () => {
+  lb.clearTotalsMemo();
+  const top = byId('200');
+  try {
+    const before = await lb.listLeaderboard({ window: 'all', pool: engine });
+    assert.ok(before.results.some((r) => r.handle === 'top-builder'));
+    const computed = totalsCalls().length;
+    top.acct.hide_stats = true;
+    const after = await lb.listLeaderboard({ window: 'all', pool: engine });
+    assert.equal(totalsCalls().length, computed, 'served from the memo — the totals were not recomputed');
+    assert.ok(!after.results.some((r) => r.handle === 'top-builder'), 'yet the hidden builder is gone');
+    assert.deepEqual(after.results.map((r) => r.place), [1, 2, 3], 'and place closes the gap');
+  } finally {
+    top.acct.hide_stats = false;
+  }
+});
+
+await t('a failed totals computation is not cached — the next request recomputes', async () => {
+  lb.clearTotalsMemo();
+  engine.throwOnQuery = new Error('transient');
+  await assert.rejects(() => lb.listLeaderboard({ window: '365d', pool: engine }), /transient/);
+  engine.throwOnQuery = null;
+  const ok = await lb.listLeaderboard({ window: '365d', pool: engine });
+  assert.ok(ok.results.length > 0);
+});
+
+// ---- the route ------------------------------------------------------------------
+
+function buildApp() {
+  const app = express();
+  app.use(attachFail);
+  app.use('/api/bongos', buildLeaderboardRoutes());
+  return app;
+}
+
+function get(port, path, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, method: 'GET', path, headers }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null; try { json = JSON.parse(text); } catch (_) {}
+        resolve({ status: res.statusCode, json, text, headers: res.headers });
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+const server = await new Promise((resolve) => { const s = buildApp().listen(0, '127.0.0.1', () => resolve(s)); });
+const port = server.address().port;
+const PATH = '/api/bongos/community/leaderboard';
+
+lb.clearTotalsMemo();
+
+await t('no window → the all-time board, ranked and numbered by place', async () => {
+  const r = await get(port, PATH);
+  assert.equal(r.status, 200);
+  assert.equal(r.json.window, 'all');
+  assert.equal(r.json.since, null);
+  assert.deepEqual(r.json.results.map((x) => x.handle), ['top-builder', 'twin-builder', 'optout-builder', 'third-builder']);
+  assert.deepEqual(r.json.results.map((x) => x.place), [1, 2, 3, 4]);
+  assert.equal(r.json.count, 4);
+  assert.deepEqual(Object.keys(r.json.results[0]).sort(),
+    ['avatar_url', 'credits', 'disciplines', 'display_name', 'github_login', 'handle', 'karma', 'place', 'tasks_shipped']);
+  const top = r.json.results[0];
+  assert.deepEqual([top.credits, top.tasks_shipped, top.karma], [300, 9, 4], 'int8 totals serialize as JSON numbers, not strings');
+});
+
+await t('hidden, private and provisional builders never appear; a recruiting opt-out does', async () => {
+  const r = await get(port, PATH);
+  const handles = r.json.results.map((x) => x.handle);
+  for (const h of ['hidden-builder', 'private-builder', 'prov-builder']) assert.ok(!handles.includes(h), h);
+  assert.ok(handles.includes('optout-builder'), 'recruiter_discoverable=false does not remove a builder from the leaderboard');
+});
+
+await t('a window echoes its start', async () => {
+  const before = Date.now();
+  const r = await get(port, `${PATH}?window=7d`);
+  assert.equal(r.status, 200);
+  assert.equal(r.json.window, '7d');
+  const since = Date.parse(r.json.since);
+  assert.ok(Math.abs((before - 7 * 86400000) - since) < 5000, 'since is ~7 days before the request');
+});
+
+await t('a discipline filter narrows the board and is echoed', async () => {
+  const r = await get(port, `${PATH}?window=30d&discipline=artist`);
+  assert.equal(r.status, 200);
+  assert.equal(r.json.discipline, 'artist');
+  assert.deepEqual(r.json.results.map((x) => x.handle), ['third-builder'],
+    'the hidden builder holds artist too, and still does not appear');
+});
+
+await t('place counts from the page offset, and page echoes the clamped values', async () => {
+  const r = await get(port, `${PATH}?limit=1&offset=1`);
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.results.map((x) => [x.place, x.handle]), [[2, 'twin-builder']]);
+  assert.deepEqual(r.json.page, { limit: 1, offset: 1 });
+  const deep = await get(port, `${PATH}?offset=${lb.MAX_OFFSET + 50}&limit=100000`);
+  assert.deepEqual(deep.json.page, { limit: lb.MAX_LIMIT, offset: lb.MAX_OFFSET });
+});
+
+await t('github_id never crosses the wire', async () => {
+  const r = await get(port, PATH);
+  assert.ok(!r.text.includes('github_id'), 'the internal join key must not appear');
+  assert.ok(!r.text.includes('"200"'));
+});
+
+await t('the response is identical for an anonymous and a credentialed viewer', async () => {
+  const anon = await get(port, `${PATH}?window=365d`);
+  const signedIn = await get(port, `${PATH}?window=365d`, { cookie: 'otb_session=abc', authorization: 'Bearer xyz' });
+  assert.equal(signedIn.status, 200);
+  const strip = (j) => ({ ...j, since: null });
+  assert.deepEqual(strip(signedIn.json), strip(anon.json));
+});
+
+await t('an unknown window → 400 bad_window, naming the allowed values', async () => {
+  for (const qs of ['window=1d', 'window=7D', 'window=toString', 'window=7d&window=30d']) {
+    const r = await get(port, `${PATH}?${qs}`);
+    assert.equal(r.status, 400, qs);
+    assert.equal(r.json.error.code, 'bad_window');
+    assert.match(r.json.error.message, /7d, 30d, 365d, all/);
+  }
+});
+
+await t('an oversized discipline → 400 discipline_too_long', async () => {
+  const r = await get(port, `${PATH}?discipline=${'a'.repeat(lb.MAX_DISCIPLINE_CHARS + 1)}`);
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'discipline_too_long');
+});
+
+await t('Cache-Control: no-store (hide must beat the cache, ADR 0171 D5) and CORS-open', async () => {
+  const r = await get(port, PATH);
+  assert.equal(r.headers['cache-control'], 'no-store');
+  assert.equal(r.headers['access-control-allow-origin'], '*');
+});
+
+await t('a query failure → 500 leaderboard_failed, with no internal detail in the body', async () => {
+  engine.throwOnQuery = new Error('DO-NOT-LEAK connection detail');
+  try {
+    const r = await get(port, PATH);
+    assert.equal(r.status, 500);
+    assert.equal(r.json.error.code, 'leaderboard_failed');
+    assert.ok(!r.text.includes('DO-NOT-LEAK'));
+  } finally {
+    engine.throwOnQuery = null;
+  }
+});
+
+server.close();
+
+// ---- the rate limit -------------------------------------------------------------
+
+function mkRes() {
+  const r = { _status: 200, _json: null, _headers: {} };
+  r.set = (k, v) => { r._headers[k] = v; return r; };
+  r.status = (s) => { r._status = s; return r; };
+  r.json = (j) => { r._json = j; return r; };
+  attachFail({}, r, () => {});
+  return r;
+}
+
+await t('the route mounts a read cap sized by its own constants', () => {
+  const { READ_RATE_LIMIT, READ_RATE_SCOPE } = buildLeaderboardRoutes._internals;
+  assert.ok(Number.isInteger(READ_RATE_LIMIT) && READ_RATE_LIMIT > 0);
+  assert.equal(READ_RATE_SCOPE, 'community-leaderboard-read');
+});
+
+await t('createReadRateLimit: allows up to the cap, then 429 with Retry-After and the scope', () => {
+  const limit = createReadRateLimit({ scope: 'test-read', limit: 3 });
+  const req = { ip: '203.0.113.90' };
+  let allowed = 0;
+  for (let i = 0; i < 3; i++) limit(req, mkRes(), () => { allowed++; });
+  assert.equal(allowed, 3);
+  const res = mkRes();
+  let nexted = false;
+  limit(req, res, () => { nexted = true; });
+  assert.equal(nexted, false);
+  assert.equal(res._status, 429);
+  assert.equal(res._json.error.code, 'rate_limited');
+  assert.ok(Number(res._headers['Retry-After']) >= 1);
+  assert.equal(res._headers['X-RateLimit-Scope'], 'test-read');
+  assert.equal(res._headers['X-RateLimit-Window-Seconds'], '60', 'the core limiter headers, one for one');
+});
+
+await t('createReadRateLimit: at the tracking cap the longest-idle IP is forgotten, never an active one', () => {
+  const limit = createReadRateLimit({ scope: 'cap', limit: 1, maxTrackedIps: 2 });
+  const hit = (ip) => { let passedThrough = false; limit({ ip }, mkRes(), () => { passedThrough = true; }); return passedThrough; };
+  hit('198.51.100.1');
+  hit('198.51.100.2');
+  assert.equal(hit('198.51.100.1'), false, '.1 is capped — and is now the most recently seen');
+  hit('198.51.100.3'); // a third IP at the cap evicts the longest idle: .2, not .1
+  assert.equal(hit('198.51.100.1'), false, 'the active, capped IP kept its bucket through the flood');
+  assert.equal(hit('198.51.100.2'), true, 'the idle IP was the one forgotten');
+});
+
+await t('createReadRateLimit keys on IP, and each budget is its own', () => {
+  const a = createReadRateLimit({ scope: 'a', limit: 1 });
+  const b = createReadRateLimit({ scope: 'b', limit: 1 });
+  a({ ip: '203.0.113.91' }, mkRes(), () => {});
+  let otherIp = false; a({ ip: '203.0.113.92' }, mkRes(), () => { otherIp = true; });
+  assert.ok(otherIp, 'another IP is unaffected');
+  let otherBudget = false; b({ ip: '203.0.113.91' }, mkRes(), () => { otherBudget = true; });
+  assert.ok(otherBudget, 'another limiter keeps its own buckets');
+});
+
+await t('createReadRateLimit: a request older than the window no longer counts', () => {
+  const realNow = Date.now;
+  try {
+    let clock = 1_000_000;
+    Date.now = () => clock;
+    const limit = createReadRateLimit({ scope: 'w', limit: 1, windowMs: 1000 });
+    limit({ ip: '203.0.113.93' }, mkRes(), () => {});
+    let blocked = true; limit({ ip: '203.0.113.93' }, mkRes(), () => { blocked = false; });
+    assert.ok(blocked, 'second call inside the window is capped');
+    clock += 1001;
+    let passedAgain = false; limit({ ip: '203.0.113.93' }, mkRes(), () => { passedAgain = true; });
+    assert.ok(passedAgain, 'the window slid past the first call');
+  } finally {
+    Date.now = realNow;
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/goal_map_page.mjs

@@ -412,5 +412,13 @@ await test('the page is the sky\'s own surface — the same sheet and the same s
   assert.equal(/goal-map-lib|goal-map\.js|goal-map\.css/.test(html), false);
 });
 
+await test('the ledger drawer accessible name matches its visible heading (docs/voice.md V3, task 1004251)', () => {
+  const html = read('goal-map.html');
+  const heading = html.match(/<h2 id="roomTitle">([^<]+)<\/h2>/)[1];
+  const label = html.match(/<aside class="room" id="room"[^>]*aria-label="([^"]+)"/)[1];
+  assert.equal(label.toLowerCase(), heading.toLowerCase(), 'one thing, one name');
+  assert.equal(label, 'The ledger');
+});
+
 console.log('');
 summary();