@bongos/core 1.19.1025 → 1.19.1026

package/modules/platform-identity/community-leaderboard.js

@@ -0,0 +1,235 @@
+// modules/platform-identity/community-leaderboard.js — the PUBLIC windowed
+// leaderboard (D3, docs/specs/bongos-v1-community-tab.md; task 1002978, goal
+// 1000110 CT2): "who earned the most across every project, this week / month /
+// year / ever", optionally narrowed to one discipline. The read behind
+// GET /community/leaderboard, for the hub's /community page (task 1003363).
+//
+// WHO: rollupVisibleSql — active + public + NOT hide_stats, the privacy matrix's
+// NUMBERS predicate, imported from account-visibility.js and never restated. A
+// leaderboard row IS stats, so hide_stats excludes; private and provisional
+// accounts never reach it. Deliberately NOT scoutingListableSql: the recruiting
+// opt-out governs the recruiting directory only (spec D3). Viewer-independent —
+// nothing here takes a viewer, so every caller sees the same board.
+//
+// WHAT (spec D2): all-time = the live rollup rows summed across projects. A
+// window = per (project, builder), the live row minus the last snapshot
+// at-or-before the window start (activity-snapshots.js), summed across projects;
+// no such snapshot counts as zero. So until a builder's first changed report
+// after snapshots began, their whole lifetime total counts inside every window —
+// the spec's accepted rollout behaviour, self-correcting. Deltas attribute to
+// REPORTING time, not earning time (the spec's stated V1 limitation).
+//
+// TWO HALVES, because the board is public and unauthenticated. The expensive
+// half — every builder's window totals, one snapshot probe per activity row — is
+// memoized per window for TOTALS_TTL_MS, so traffic cannot multiply it. The cheap
+// half — who is eligible, and their name and avatar — is re-read on EVERY
+// request, so a builder who hides or goes private leaves the board on the very
+// next request (hide must beat the cache, ADR 0171 D5). The memo can only lag on
+// numbers, never on who is shown.
+//
+// A builder with nothing to show in the window (credits, ships and karma all
+// unchanged) is left off that window's board rather than listed at zero.
+// github_id never crosses the projection; handle is the address.
+'use strict';
+
+const { pool: defaultPool } = require('../../src/module-api');
+const { rollupVisibleSql } = require('./account-visibility');
+// The sibling public community read's paging + input caps, shared rather than
+// copied so the two routes cannot drift apart.
+const { clampOffset, MAX_OFFSET, MAX_DISCIPLINE_CHARS } = require('./builder-search');
+
+// The spec's four windows. null = all-time (no baseline subtracted).
+const WINDOW_DAYS = Object.freeze({ '7d': 7, '30d': 30, '365d': 365, all: null });
+const WINDOWS = Object.freeze(Object.keys(WINDOW_DAYS));
+const DEFAULT_WINDOW = 'all';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 100;
+// How long one window's totals are reused. Numbers are reporting-time already
+// (they move when an instance reports), so half a minute of lag is invisible;
+// eligibility is never memoized.
+const TOTALS_TTL_MS = 30 * 1000;
+
+function isWindow(value) {
+  return typeof value === 'string' && Object.prototype.hasOwnProperty.call(WINDOW_DAYS, value);
+}
+
+// The instant a window opens, or null for all-time. `now` is injectable so a
+// test can pin the boundary.
+function windowStart(window, now = new Date()) {
+  const days = WINDOW_DAYS[window];
+  if (days == null) return null;
+  return new Date(now.getTime() - days * DAY_MS);
+}
+
+function clampLimit(limit) {
+  const n = parseInt(limit, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+// Every eligible builder's totals for one window, unsorted and unpaged:
+// [{ githubId, credits, tasks_shipped, karma, disciplines }]. The expensive
+// half. Arithmetic is bigint: the columns are instance-reported int4, and one
+// extreme report must not overflow the whole public board into a 500.
+async function computeWindowTotals(since, pool) {
+  const { rows } = await pool.query(
+    `WITH act AS (
+       SELECT a.client_id, a.github_id, a.credits, a.tasks_shipped, a.karma, a.disciplines
+         FROM platform_identity_builder_project_activity a
+         JOIN platform_identity_accounts pa ON pa.github_id = a.github_id
+        WHERE ${rollupVisibleSql('pa')}
+     ), per_project AS (
+       -- The baseline probe walks platform_identity_activity_snapshots_builder_time
+       -- in index order. All-time binds $1 NULL, so the probe never runs.
+       SELECT act.github_id,
+              act.credits::bigint - COALESCE(b.credits, 0)             AS credits,
+              act.tasks_shipped::bigint - COALESCE(b.tasks_shipped, 0) AS tasks_shipped,
+              act.karma::bigint - COALESCE(b.karma, 0)                 AS karma
+         FROM act
+         LEFT JOIN LATERAL (
+           SELECT s.credits, s.tasks_shipped, s.karma
+             FROM platform_identity_activity_snapshots s
+            WHERE $1::timestamptz IS NOT NULL
+              AND s.client_id = act.client_id AND s.github_id = act.github_id
+              AND s.reported_at <= $1::timestamptz
+            ORDER BY s.reported_at DESC, s.id DESC
+            LIMIT 1
+         ) b ON true
+     ), board AS (
+       SELECT github_id,
+              sum(credits)::bigint       AS credits,
+              sum(tasks_shipped)::bigint AS tasks_shipped,
+              sum(karma)::bigint         AS karma
+         FROM per_project
+        GROUP BY github_id
+     ), disc AS (
+       SELECT x.github_id, array_agg(DISTINCT x.d ORDER BY x.d) AS disciplines
+         FROM (SELECT act.github_id, unnest(act.disciplines) AS d FROM act) x
+        WHERE x.d IS NOT NULL
+        GROUP BY x.github_id
+     )
+     SELECT board.github_id, board.credits, board.tasks_shipped, board.karma, disc.disciplines
+       FROM board
+       LEFT JOIN disc ON disc.github_id = board.github_id
+      WHERE board.credits <> 0 OR board.tasks_shipped <> 0 OR board.karma <> 0`,
+    [since],
+  );
+  // int8 arrives from node-postgres as a string; any real total is far inside
+  // Number's exact-integer range.
+  return rows.map((r) => ({
+    githubId: String(r.github_id),
+    credits: Number(r.credits),
+    tasks_shipped: Number(r.tasks_shipped),
+    karma: Number(r.karma),
+    disciplines: Array.isArray(r.disciplines) ? r.disciplines : [],
+  }));
+}
+
+// window -> { expires, since, promise }. Concurrent requests share one
+// in-flight computation; a failed one is dropped so the next request retries.
+const totalsMemo = new Map();
+
+function memoizedWindowTotals(window, pool) {
+  const hit = totalsMemo.get(window);
+  if (hit && hit.pool === pool && hit.expires > Date.now()) return hit;
+  const since = windowStart(window);
+  const entry = { pool, since, expires: Date.now() + TOTALS_TTL_MS, promise: computeWindowTotals(since, pool) };
+  entry.promise.catch(() => { if (totalsMemo.get(window) === entry) totalsMemo.delete(window); });
+  totalsMemo.set(window, entry);
+  return entry;
+}
+
+function clearTotalsMemo() {
+  totalsMemo.clear();
+}
+
+// The cheap half, re-read on every request: which of these builders are
+// eligible RIGHT NOW, and how they are shown. Map githubId -> identity.
+async function eligibleIdentities(githubIds, pool) {
+  if (githubIds.length === 0) return new Map();
+  const { rows } = await pool.query(
+    `SELECT pa.github_id, pa.handle, pa.github_login, pa.display_name, pa.avatar_url
+       FROM platform_identity_accounts pa
+      WHERE pa.github_id = ANY($1::bigint[])
+        AND ${rollupVisibleSql('pa')}`,
+    [githubIds],
+  );
+  return new Map(rows.map((r) => [String(r.github_id), r]));
+}
+
+// Credits, then ships, then karma, then handle/login so a tie is stable —
+// compared by code unit, so the order never depends on the server's locale.
+const byText = (x, y) => { const a = String(x ?? ''); const b = String(y ?? ''); return a < b ? -1 : a > b ? 1 : 0; };
+function compareRows(a, b) {
+  return (b.credits - a.credits) || (b.tasks_shipped - a.tasks_shipped) || (b.karma - a.karma)
+    || byText(a.handle, b.handle) || byText(a.github_login, b.github_login);
+}
+
+// listLeaderboard — one page of the board. Throws on an unknown window (the
+// route validates and 400s first). Returns { window, since, results, limit,
+// offset }: `since` is the window start the totals were computed from (null
+// for all-time) and limit/offset are the CLAMPED values, so the route echoes
+// rather than re-derives them. `place` is the 1-based position on the whole
+// board — named so it can never be read as a builder's rank. Passing `now`
+// pins the window start and bypasses the memo (tests of the boundary).
+async function listLeaderboard({ window = DEFAULT_WINDOW, discipline, limit, offset, now, pool = defaultPool } = {}) {
+  if (!isWindow(window)) throw new Error(`listLeaderboard: unknown window ${JSON.stringify(window)}`);
+  const lim = clampLimit(limit);
+  const off = clampOffset(offset);
+  const disc = typeof discipline === 'string' ? discipline.trim().slice(0, MAX_DISCIPLINE_CHARS) : '';
+
+  let since;
+  let totals;
+  if (now !== undefined) {
+    since = windowStart(window, now);
+    totals = await computeWindowTotals(since, pool);
+  } else {
+    const entry = memoizedWindowTotals(window, pool);
+    since = entry.since;
+    totals = await entry.promise;
+  }
+
+  const candidates = disc ? totals.filter((t) => t.disciplines.includes(disc)) : totals;
+  const identities = await eligibleIdentities(candidates.map((t) => t.githubId), pool);
+  const board = candidates
+    .filter((t) => identities.has(t.githubId))
+    .map((t) => {
+      const who = identities.get(t.githubId);
+      return {
+        handle: who.handle,
+        github_login: who.github_login,
+        display_name: who.display_name,
+        avatar_url: who.avatar_url,
+        credits: t.credits,
+        tasks_shipped: t.tasks_shipped,
+        karma: t.karma,
+        disciplines: t.disciplines,
+      };
+    })
+    .sort(compareRows);
+
+  return {
+    window,
+    since: since ? since.toISOString() : null,
+    results: board.slice(off, off + lim).map((row, i) => ({ place: off + i + 1, ...row })),
+    limit: lim,
+    offset: off,
+  };
+}
+
+module.exports = {
+  listLeaderboard,
+  clearTotalsMemo,
+  windowStart,
+  isWindow,
+  clampLimit,
+  WINDOWS,
+  DEFAULT_WINDOW,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+  MAX_OFFSET,
+  MAX_DISCIPLINE_CHARS,
+  TOTALS_TTL_MS,
+};

package/modules/platform-identity/module.json

@@ -10,7 +10,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search"],
+    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard"],
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull"]
   },

package/modules/platform-identity/read-rate-limit.js

@@ -0,0 +1,61 @@
+// modules/platform-identity/read-rate-limit.js — a per-IP read cap for an
+// UNAUTHENTICATED public GET in this module. The global limiter meters writes
+// only, and core's per-IP sliding window (src/bongos/middleware/rate-limit.js
+// perIpSlidingWindow) reaches modules only as ready-built instances on the
+// doorway (ADR 0209: an instance per budget), none of which is this module's.
+// This is the module-side twin of that function — same 429 envelope and
+// headers — written once (task 1002978) and mounted by both community reads
+// (routes/community-leaderboard.js, routes/community-search.js).
+// routes/public-profile.js and routes/sso.js still carry older vendored copies.
+'use strict';
+
+const SWEEP_EVERY_MS = 5 * 60 * 1000;
+// Bounds the bucket map between sweeps: rotating source addresses (an IPv6
+// block) must not grow the heap without limit on an unauthenticated route.
+const MAX_TRACKED_IPS = 10000;
+
+// createReadRateLimit({ scope, limit, windowMs, maxTrackedIps }) → Express
+// middleware allowing `limit` requests per IP per sliding `windowMs`, then 429
+// rate_limited with Retry-After. `scope` names the budget in the response so a
+// client can tell which cap it hit. Buckets live in this closure: one budget
+// per call. The map is kept in least-recently-seen order, so at the tracking
+// cap the IP evicted is the one idle longest — O(1), no scan on the hot path.
+function createReadRateLimit({ scope, limit, windowMs = 60 * 1000, maxTrackedIps = MAX_TRACKED_IPS }) {
+  const buckets = new Map(); // ip -> timestamp[], least recently seen first
+
+  const sweepTimer = setInterval(() => {
+    const cutoff = Date.now() - windowMs;
+    for (const [k, arr] of buckets) {
+      while (arr.length && arr[0] < cutoff) arr.shift();
+      if (arr.length === 0) buckets.delete(k);
+    }
+  }, SWEEP_EVERY_MS);
+  if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
+
+  return function readRateLimit(req, res, next) {
+    const now = Date.now();
+    const key = req.ip || req.socket?.remoteAddress || 'unknown';
+    let bucket = buckets.get(key);
+    if (bucket) {
+      buckets.delete(key); // re-inserted below: most recently seen goes last
+    } else {
+      if (buckets.size >= maxTrackedIps) buckets.delete(buckets.keys().next().value);
+      bucket = [];
+    }
+    buckets.set(key, bucket);
+    const cutoff = now - windowMs;
+    while (bucket.length && bucket[0] < cutoff) bucket.shift();
+    if (bucket.length >= limit) {
+      const retryAfter = Math.max(1, Math.ceil((bucket[0] + windowMs - now) / 1000));
+      res.set('Retry-After', String(retryAfter));
+      res.set('X-RateLimit-Scope', scope);
+      res.set('X-RateLimit-Limit', String(limit));
+      res.set('X-RateLimit-Window-Seconds', String(windowMs / 1000));
+      return res.fail('rate_limited', 429, { scope, retry_after_seconds: retryAfter });
+    }
+    bucket.push(now);
+    return next();
+  };
+}
+
+module.exports = { createReadRateLimit, MAX_TRACKED_IPS };

package/modules/platform-identity/routes/community-leaderboard.js

@@ -0,0 +1,69 @@
+// modules/platform-identity/routes/community-leaderboard.js — GET
+// /community/leaderboard, the PUBLIC windowed leaderboard behind the hub's
+// /community page (D3, docs/specs/bongos-v1-community-tab.md; task 1002978,
+// goal 1000110 CT2). The sibling of routes/community-search.js: same module,
+// same public posture. Who appears and how a window is counted live entirely in
+// ../community-leaderboard.js; this file is the HTTP shell — validation, the
+// per-IP read cap, the response envelope. It never reads a session, so the
+// board is the same for every viewer.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const leaderboard = require('../community-leaderboard');
+const { createReadRateLimit } = require('../read-rate-limit');
+
+const { pool, corsPublicGet } = api;
+
+const READ_RATE_LIMIT = 60; // per IP per minute — the community-search budget
+const READ_RATE_SCOPE = 'community-leaderboard-read';
+const leaderboardReadRateLimit = createReadRateLimit({ scope: READ_RATE_SCOPE, limit: READ_RATE_LIMIT });
+
+module.exports = function communityLeaderboardRoutes() {
+  const router = express.Router();
+
+  router.use('/community/leaderboard', corsPublicGet('/community/leaderboard'));
+
+  // rank: public — the cross-project leaderboard (?window=7d|30d|365d|all,
+  // default all; ?discipline=; ?limit=&offset=). Eligibility is the privacy
+  // matrix's numbers predicate (active + public + stats shown); the recruiting
+  // opt-out does not apply. no-store: hide must beat the cache (ADR 0171 D5).
+  // Rollout note: until a builder's first changed report after snapshot history
+  // began, their whole lifetime total counts inside every window (spec D2's
+  // missing-baseline-is-zero rule) — expected on day one, and self-correcting.
+  router.get('/community/leaderboard', leaderboardReadRateLimit, async (req, res) => {
+    const window = req.query.window === undefined || req.query.window === ''
+      ? leaderboard.DEFAULT_WINDOW
+      : req.query.window;
+    if (!leaderboard.isWindow(window)) {
+      return res.fail('bad_window', { status: 400, message: `window must be one of: ${leaderboard.WINDOWS.join(', ')}` });
+    }
+    const discipline = (typeof req.query.discipline === 'string' ? req.query.discipline : '').trim();
+    if (discipline.length > leaderboard.MAX_DISCIPLINE_CHARS) {
+      return res.fail('discipline_too_long', { status: 400, message: `discipline must be at most ${leaderboard.MAX_DISCIPLINE_CHARS} characters` });
+    }
+    try {
+      const board = await leaderboard.listLeaderboard({
+        window, discipline, limit: req.query.limit, offset: req.query.offset, pool,
+      });
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        window: board.window,
+        since: board.since,
+        discipline: discipline || null,
+        count: board.results.length,
+        results: board.results,
+        page: { limit: board.limit, offset: board.offset },
+      });
+    } catch (err) {
+      api.logger('platform-identity').error({ err: err && err.message }, 'GET /community/leaderboard failed');
+      res.fail('leaderboard_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+module.exports._internals = { READ_RATE_LIMIT, READ_RATE_SCOPE };

package/modules/platform-identity/routes/community-search.js

@@ -16,6 +16,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const builderSearch = require('../builder-search');
+const { createReadRateLimit } = require('../read-rate-limit');
 
 const { pool, corsPublicGet } = api;
 
@@ -33,39 +34,11 @@ const log = {
 
 // Per-IP read cap for this UNAUTHENTICATED route (the public-profile.js R05
 // posture: the global limiter only meters WRITES, so an uncapped scraper could
-// otherwise run the trigram leg at line rate). Vendored, not shared — the core
-// /public/* limiter is not on the doorway, and each public GET here owns its
-// own budget rather than reaching into a sibling module's copy.
+// otherwise run the trigram leg at line rate). Its own budget, built by the
+// module's shared factory (task 1002978) rather than a vendored copy.
 const READ_RATE_WINDOW_MS = 60 * 1000;
 const READ_RATE_LIMIT = 60;
-const buckets = new Map(); // ip -> timestamp[]
-
-const sweepTimer = setInterval(() => {
-  const cutoff = Date.now() - READ_RATE_WINDOW_MS;
-  for (const [k, arr] of buckets) {
-    while (arr.length && arr[0] < cutoff) arr.shift();
-    if (arr.length === 0) buckets.delete(k);
-  }
-}, 5 * 60 * 1000);
-if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
-
-function searchReadRateLimit(req, res, next) {
-  const now = Date.now();
-  const key = req.ip || req.socket?.remoteAddress || 'unknown';
-  let bucket = buckets.get(key);
-  if (!bucket) { bucket = []; buckets.set(key, bucket); }
-  const cutoff = now - READ_RATE_WINDOW_MS;
-  while (bucket.length && bucket[0] < cutoff) bucket.shift();
-  if (bucket.length >= READ_RATE_LIMIT) {
-    const retryAfter = Math.max(1, Math.ceil((bucket[0] + READ_RATE_WINDOW_MS - now) / 1000));
-    res.set('Retry-After', String(retryAfter));
-    res.set('X-RateLimit-Scope', 'community-search-read');
-    res.set('X-RateLimit-Limit', String(READ_RATE_LIMIT));
-    return res.fail('rate_limited', 429, { scope: 'community-search-read', retry_after_seconds: retryAfter });
-  }
-  bucket.push(now);
-  return next();
-}
+const searchReadRateLimit = createReadRateLimit({ scope: 'community-search-read', limit: READ_RATE_LIMIT, windowMs: READ_RATE_WINDOW_MS });
 
 module.exports = function communitySearchRoutes() {
   const router = express.Router();

package/modules/platform-identity/routes/projects.js

@@ -120,7 +120,7 @@ module.exports = function projectsRoutes() {
   // as any-builder — wrong in the dangerous direction (the ADR 0210 rule).
 
   // rank: metic+archon — own-or-metic in effect: invite a builder into a project
-  // (ADR 0141 §5, task #1002115), called by a `project.curate` holder OR the project's OWN
+  // (ADR 0141 §5, task 1002115), called by a `project.curate` holder OR the project's OWN
   // OWNER (task 1003580; the ownership proof is `provisioning_instances.owner_builder_id`,
   // reached through a port — see invite-authz.js). The wizard's audience is any signed-in
   // GitHub user, typically a xenos who used to get 403 on their own project. A caller who is

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1025",
+  "version": "1.19.1026",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1025",
+      "version": "1.19.1026",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1025",
+  "version": "1.19.1026",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/run-unit-tests.js

@@ -87,6 +87,11 @@ const INTEGRATION = new Set([
   // WHERE NOT EXISTS statement) and the upsertActivity wiring against real SQL —
   // a fake pool can prove the query shape but not which reports it inserts.
   'activity_snapshots_db',
+  // task 1002978: the windowed leaderboard against real SQL. Which snapshot
+  // becomes a window baseline (a LATERAL at-or-before probe), a missing baseline
+  // counting as zero, and the privacy matrix filtering are all planner facts the
+  // DB-free route test can only assert the shape of.
+  'community_leaderboard_db',
   'asset_version', 'auth_flow_slice1', 'backfill_sessions', 'bfg', 'bfg_write',
   'box_connect_e2e', 'box_onboard', 'boxes', 'cf_tunnel', 'cli_token_reissue',
   // consumer_layout_boot builds the core .tgz, `npm install`s it, and boots a live

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1025'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1026'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');