@bongos/core 1.19.1025 → 1.19.1027

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 419 endpoints across 71 route files.
+> **Generated from the live route files** — the route file is authoritative. 437 endpoints across 74 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -188,10 +188,11 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/closeness/weights` | `any-builder` | — | the MODEL is not private, and publishing it is the whole point of the weights being data. |
 | GET | `/api/bongos/closeness/with/:builderId` | `any-builder` | — | One pair — "why am I close to THEM", asked directly rather than by paging the graph. |
 
-## `community` (1)
+## `community` (2)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/community/leaderboard` | `public` | — | the cross-project leaderboard (?window=7d\|30d\|365d\|all, default all; ?discipline=; ?limit=&offset=). |
 | GET | `/api/bongos/community/search` | `public` | — | a name/discipline search under EXACTLY the public-profile visibility rules (D4): a hide_stats account is findable by name but drops out o… |
 
 ## `connections` (8)
@@ -331,6 +332,31 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 |---|---|---|---|---|
 | GET | `/api/bongos/grades/by-builder` | `metic+archon` | — | GET /grades/by-builder?days=30 — per-builder grade breakdown (task 726). |
 
+## `guild-requests` (3)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| DELETE | `/api/bongos/guild-requests/:id` | `any-builder` | — | cancel a row I opened: my request, or (as owner) an invite my guild sent. |
+| POST | `/api/bongos/guild-requests/:id/accept` | `any-builder` | `visibility`, `counted_in_totals` | accept an invite addressed to ME, or (as the guild's owner) a request to join it. |
+| POST | `/api/bongos/guild-requests/:id/decline` | `any-builder` | — | decline an invite to ME, or (as owner) a request to my guild. |
+
+## `guilds` (12)
+
+| Method | Path | Rank | Body | Description |
+|---|---|---|---|---|
+| POST | `/api/bongos/guilds` | `any-builder` | `slug`, `name`, `description`, `visibility` | create a guild. |
+| GET | `/api/bongos/guilds/:slug` | `public` | — | a public guild's page data. |
+| PATCH | `/api/bongos/guilds/:slug` | `any-builder` | `name`, `description`, `visibility` | owner: edit name, description or visibility. |
+| DELETE | `/api/bongos/guilds/:slug` | `any-builder` | — | owner: dissolve. |
+| POST | `/api/bongos/guilds/:slug/invites` | `any-builder` | `handles` | owner: invite up to INVITE_BATCH_MAX builders by handle, each an ordinary individual invite (ADR 0336 D3). |
+| GET | `/api/bongos/guilds/:slug/members` | `any-builder` | — | the members' roster, for members only (the own-scope door to an unlisted guild, ADR 0336 D4). |
+| DELETE | `/api/bongos/guilds/:slug/members/:handle` | `any-builder` | — | owner: remove a member (never the owner). |
+| PATCH | `/api/bongos/guilds/:slug/membership` | `any-builder` | `shown_publicly`, `counted_in_totals` | MY switches in one guild: shown on its public page (ADR 0336 D4) and counted in its totals (ADR 0337 D4.4). |
+| DELETE | `/api/bongos/guilds/:slug/membership` | `any-builder` | — | leave. |
+| GET | `/api/bongos/guilds/:slug/requests` | `any-builder` | — | owner: the join requests to decide and the invites still out. |
+| POST | `/api/bongos/guilds/:slug/requests` | `any-builder` | `counted_in_totals` | ask to join. |
+| POST | `/api/bongos/guilds/:slug/transfer` | `any-builder` | `handle` | owner: hand ownership to an existing member. |
+
 ## `healthz` (1)
 
 | Method | Path | Rank | Body | Description |
@@ -405,7 +431,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/llm-cache/lookup` | `metic+archon` | `cache_key`, `tokens_saved_est` | POST /llm-cache/lookup — hit/miss + atomic hit_count bump. |
 | POST | `/api/bongos/llm-cache/store` | `metic+archon` | `spec`, `result_stdout`, `result_cost_usd` | POST /llm-cache/store — upsert a freshly-produced result. |
 
-## `me` (32)
+## `me` (34)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -420,6 +446,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/me/display-name` | `any-builder` | _undocumented_ | PATCH the display name. |
 | GET | `/api/bongos/me/event-sound-prefs` | `any-builder` | — | Per-builder per-event sound variant selection (task 582, migration 164). |
 | PATCH | `/api/bongos/me/event-sound-prefs` | `any-builder` | _undocumented_ | PATCH a partial set of event sound overrides. |
+| GET | `/api/bongos/me/guild-requests` | `any-builder` | — | MY queue: invites addressed to me, each carrying the card (the guild's current visibility, which an accept must echo back), and the join … |
+| GET | `/api/bongos/me/guilds` | `any-builder` | — | MY guilds, each with my own two switches. |
 | PATCH | `/api/bongos/me/handle` | `any-builder` | `handle` | rename the caller's OWN handle (own data, keyed on the authenticated github_id). |
 | GET | `/api/bongos/me/interaction` | `any-builder` | — | Per-builder INTERACTION PROFILE (task 2010, shares the behavior_prefs jsonb / migration 119). |
 | PATCH | `/api/bongos/me/interaction` | `any-builder` | _undocumented_ | PATCH the interaction profile. |
@@ -516,7 +544,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/projects/:id/status` | `metic+archon` | `status` | THE TAKEDOWN LEVER (R08, task 1002327; ADR 0252 §5.1). |
 | POST | `/api/bongos/projects/:projectId/specialities` | `any-builder` | `name`, `discipline`, `summary`, `contract_md`, `visibility`, `sellable` | POST /projects/:projectId/specialities — author one OWNED BY A PROJECT. |
 | GET | `/api/bongos/projects/featured` | `public` | — | the public map of projects; no auth by design. |
-| POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | 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'… |
+| POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | 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… |
 
 ## `provisioning` (31)
 

package/docs/copy-inventory.md

@@ -4,7 +4,7 @@
 > Deterministic on a given tree — regenerate and commit rather than hand-editing.
 > Machine-readable twin: [`copy-registry.json`](copy-registry.json).
 
-**2040 strings** across 3 surfaces · 1741 distinct pieces of copy · 2040 certain, 0 heuristic · 212 shown in more than one place.
+**2040 strings** across 3 surfaces · 1742 distinct pieces of copy · 2040 certain, 0 heuristic · 211 shown in more than one place.
 
 ## Surfaces
 
@@ -76,7 +76,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `064c72453555` | 3x | goals · | modules/hall-ui/public/roadmap.js:218, modules/hall-ui/public/sky-interaction.js:39, modules/hall-ui/public/sky-interaction.js:124 |
 | `cc5106af4b35` | 3x | {…} of {…} criteria satisfied | modules/hall-ui/public/goals-lib.js:32, modules/hall-ui/public/goals-render.js:705, modules/hall-ui/public/goals.js:45 |
 | `7926e30955d2` | 3x | ← Back to goal | modules/hall-ui/public/goals.html:199, modules/hall-ui/public/goals.html:210, modules/hall-ui/public/goals.html:222 |
-| … | | _172 more in the JSON registry_ | |
+| … | | _171 more in the JSON registry_ | |
 
 ## `builders-hall` — 1547 strings
 
@@ -1062,7 +1062,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `19b23f2cc45b` | certain | The grading panel could not run when this task was shipped, so no quality signal was recorded — an outage, not | `modules/hall-ui/public/task.js:413` |
 | `027e9420daa2` | certain | The headline lands, but the sub-line reads like a brochure. | `modules/hall-ui/public/studio.js:162` |
 | `9f45c63c9697` | certain | The kinds of work you prefer. Task suggestions lean toward your choices — pick one, several, or none. | `modules/hall-ui/public/settings.html:127` |
-| `dbbcedba5f3c` | certain | The list | `modules/hall-ui/public/goal-map.html:99` |
+| `814eb6889339` | certain | The ledger | `modules/hall-ui/public/goal-map.html:99` |
 | `dbbcedba5f3c` | certain | The list | `modules/hall-ui/public/thinking.html:98` |
 | `a02d386fbc13` | certain | The map | `modules/hall-ui/public/atlas.html:45` |
 | `e1ce3766c6fe` | certain | The map has not been generated on this deploy yet. | `modules/hall-ui/public/atlas.js:416` |
@@ -1850,7 +1850,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `485c565b5745` | certain | How people join | `modules/public-landing/public/projects.html:801` |
 | `4b542b000afa` | certain | How this project is drawn: on the sky, in your list, at the top of this page and on its card. A planet is a | `modules/public-landing/public/projects.html:921` |
 | `9f31eaed8252` | certain | If you grant repository access while creating a project, that permission is used to create or adopt your repos | `modules/public-landing/public/privacy.html:55` |
-| `2a1b87d28a9c` | certain | If your account already existed when this version took effect, the platform accepted it on your behalf, rather | `modules/public-landing/public/terms.html:71` |
+| `3b1cbe9e33aa` | certain | If your account already existed when this version took effect, the platform accepted it on your behalf, rather | `modules/public-landing/public/terms.html:71` |
 | `607551ae732b` | certain | Invite a builder | `modules/public-landing/public/projects.html:894` |
 | `20786b02f47a` | certain | Invite builders | `modules/public-landing/public/projects.html:1305` |
 | `a1256030d879` | certain | Invite only | `modules/public-landing/public/projects.html:805` |
@@ -1885,7 +1885,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `837fdaa0936a` | certain | Nothing matches that. | `modules/public-landing/public/projects.html:649` |
 | `1bc11853e893` | certain | On the map | `modules/public-landing/public/projects.html:820` |
 | `b4ac8f44710c` | certain | On the public map | `modules/public-landing/public/projects.html:742` |
-| `69400ca12477` | certain | Once you have signed in here and accepted these terms, your profile and that record are public by default: at  | `modules/public-landing/public/terms.html:68` |
+| `7fe31ce20c09` | certain | Once you have signed in to a project with your platform account and accepted these terms, your profile and tha | `modules/public-landing/public/terms.html:68` |
 | `8329bb1a3693` | certain | One tap files the request and the platform starts standing your project up — server, database, address. Here's | `modules/public-landing/public/projects.html:1277` |
 | `86cde1930d84` | certain | Only mine | `modules/public-landing/public/projects.html:419` |
 | `f82fe1982ab3` | certain | Open an issue on the repository | `modules/public-landing/public/contact.html:52` |
@@ -1981,7 +1981,7 @@ Identical copy within one surface. Sometimes right (a repeated button), sometime
 | `fb416bf1a26b` | certain | The handle names your project on the platform — and its address comes with it. Once it stands up, a few GitHub | `modules/public-landing/public/projects.html:1245` |
 | `a954f0dce9a3` | certain | The platform | `modules/public-landing/public/contact.html:65` |
 | `4fd8f5746cc5` | certain | The platform is run as a non-profit, capture-resistant commons. | `modules/public-landing/public/terms.html:50` |
-| `666291db6ac3` | certain | The platform stores the date you accepted these terms, and which version, on your account. It is written by si | `modules/public-landing/public/terms.html:70` |
+| `dede132846fe` | certain | The platform stores the date you accepted these terms, and which version, on your account. It is written when  | `modules/public-landing/public/terms.html:70` |
 | `20fcebaa85c4` | certain | The project hub needs JavaScript — the map, your projects, and starting a new one all live here. You can read  | `modules/public-landing/public/projects.html:472` |
 | `4a740b5afe73` | certain | The project map | `modules/public-landing/public/projects.html:482` |
 | `345fec12e5d8` | certain | The repository | `modules/public-landing/public/contact.html:50` |

package/docs/copy-registry.json

@@ -4,10 +4,10 @@
   "goal": 1000074,
   "counts": {
     "strings": 2040,
-    "unique_ids": 1741,
+    "unique_ids": 1742,
     "certain": 2040,
     "heuristic": 0,
-    "duplicate_ids": 212
+    "duplicate_ids": 211
   },
   "surfaces": {
     "builders-hall": {
@@ -1665,16 +1665,6 @@
         "modules/hall-ui/public/thinking.html:123"
       ]
     },
-    {
-      "id": "dbbcedba5f3c",
-      "surface": "builders-hall",
-      "text": "The list",
-      "occurrences": 2,
-      "at": [
-        "modules/hall-ui/public/goal-map.html:99",
-        "modules/hall-ui/public/thinking.html:98"
-      ]
-    },
     {
       "id": "7f03838faf0c",
       "surface": "builders-hall",
@@ -11068,9 +11058,9 @@
       "confidence": "certain"
     },
     {
-      "id": "dbbcedba5f3c",
+      "id": "814eb6889339",
       "surface": "builders-hall",
-      "text": "The list",
+      "text": "The ledger",
       "file": "modules/hall-ui/public/goal-map.html",
       "line": 99,
       "origin": "html-attr:aria-label",
@@ -17170,9 +17160,9 @@
       "confidence": "certain"
     },
     {
-      "id": "2a1b87d28a9c",
+      "id": "3b1cbe9e33aa",
       "surface": "landing",
-      "text": "If your account already existed when this version took effect, the platform accepted it on your behalf, rather than waiting for you to sign in, and dated it the day that was done. The record marks that acceptance as grandfathered, so it is never mistaken for one you gave, and your own acceptance replaces it the next time you sign in.",
+      "text": "If your account already existed when this version took effect, the platform accepted it on your behalf, rather than waiting for you to sign in, and dated it the day that was done. The record marks that acceptance as grandfathered, so it is never mistaken for one you gave, and your own acceptance replaces it the next time you sign in to a project.",
       "file": "modules/public-landing/public/terms.html",
       "line": 71,
       "origin": "html-text",
@@ -17485,9 +17475,9 @@
       "confidence": "certain"
     },
     {
-      "id": "69400ca12477",
+      "id": "7fe31ce20c09",
       "surface": "landing",
-      "text": "Once you have signed in here and accepted these terms, your profile and that record are public by default: at your handle’s page, in the people directory, to project owners looking for people to work with, and to search engines. An account that has never signed in here stays provisional and is published nowhere.",
+      "text": "Once you have signed in to a project with your platform account and accepted these terms, your profile and that record are public by default: at your handle’s page, in the people directory, to project owners looking for people to work with, and to search engines. An account that has never signed in to a project that way stays provisional and is published nowhere.",
       "file": "modules/public-landing/public/terms.html",
       "line": 68,
       "origin": "html-text",
@@ -18349,9 +18339,9 @@
       "confidence": "certain"
     },
     {
-      "id": "666291db6ac3",
+      "id": "dede132846fe",
       "surface": "landing",
-      "text": "The platform stores the date you accepted these terms, and which version, on your account. It is written by signing in here, and only once — signing in again does not change the original date. This is version",
+      "text": "The platform stores the date you accepted these terms, and which version, on your account. It is written when you sign in to a project with your platform account, and only once — signing in again does not change the date you accepted. This is version",
       "file": "modules/public-landing/public/terms.html",
       "line": 70,
       "origin": "html-text",

package/docs/module-api-changelog.md

@@ -2529,5 +2529,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1023 with no explicit bump. run 36183325302. (task 1002620)
   1.19.1025 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1024 with no explicit bump. run 36185386905. (task 1002620)
+  1.19.1026 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1025 with no explicit bump. run 36186644421. (task 1002620)
+  1.19.1027 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1026 with no explicit bump. run 36187742785. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/hall-ui/public/goal-map.html

@@ -96,7 +96,7 @@
 <div class="card glass" id="card" role="tooltip" aria-hidden="true"></div>
 <div class="menu glass" id="menu" hidden role="menu" aria-label="Chart the routes"></div>
 
-<aside class="room" id="room" hidden aria-label="The list">
+<aside class="room" id="room" hidden aria-label="The ledger">
   <div class="head"><h2 id="roomTitle">the ledger</h2><span class="lbl" id="roomCount"></span></div>
   <div class="filters" id="filters" role="group" aria-label="Filter"></div>
   <div class="rows" id="rows"></div>

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/connections.js

@@ -561,6 +561,7 @@ module.exports = {
   DEGREE_MAX,
   FANOUT_1,
   FANOUT_2,
+  neighboursSql,
   findAccountByHandle,
   isConnectedTo,
   requestConnection,