@bongos/core 1.20.19 → 1.20.21

package/modules/platform-identity/guild-totals.js

@@ -0,0 +1,217 @@
+// modules/platform-identity/guild-totals.js — a guild's collective record: the
+// rounded totals its public page publishes (task 1002302, R26; ADR 0337 D4.4,
+// which supersedes ADR 0336 D5's read-time sum).
+//
+// THE RULE, next to the data so no reader can forget a half of it:
+//
+//   * EVERY MEMBER COUNTS UNLESS THEY SWITCHED IT OFF. counted_in_totals is the
+//     per-membership switch R24 stores (task 1002300); the notice on the join
+//     cards is the consent. An account that has not consented at all (not
+//     accountActiveSql) is never counted, whatever its switch says.
+//   * A PUBLIC MEMBER is one whose numbers are already public on the guild's page:
+//     shown_publicly AND rollupVisibleSql. Everyone else counted is NON-PUBLIC — a
+//     private account, hidden numbers, or not agreeing to be shown.
+//   * A MINIMUM OF 3. Non-public members' numbers enter only while the guild has
+//     at least NON_PUBLIC_MIN_COUNTED counted non-public members. Below that the
+//     totals add up the public members alone.
+//   * ROUNDED, NEVER EXACT. Each total is published as its band floor on the
+//     1-2-5 scale ("100+"), and only the band floor is ever stored. The exact sum
+//     lives in memory for as long as it takes to round it.
+//   * WEEKLY, NEVER ON A READ. A poller (pollers/guild-totals.js) refreshes a row
+//     at most once every TOTALS_REFRESH_DAYS, and the upsert re-checks that age in
+//     its own statement. readGuildTotals only SELECTs, so no read, however many,
+//     can move a number an observer is watching.
+//   * PROJECTS ARE THE PUBLIC MEMBERS' NAMED PUBLIC PROJECTS, never a non-public
+//     member's (ADR 0336 D5's union rule, which D4.4 keeps). Even a hidden
+//     member's public projects are withheld on their own profile, so they stay
+//     out of the count.
+//
+// WHAT IS DELIBERATELY ABSENT. No count of counted members, and nothing that says
+// whether non-public numbers are in the total: either would reveal how many
+// non-public members a guild has, which its public size (the roster's length,
+// ADR 0336 D4) is built never to show.
+//
+// THE HONEST LIMIT, accepted by the owner (ADR 0337 D4.4, 2026-09-25). This stops
+// a casual reader, not a determined guild owner: padding the guild with two
+// accounts whose numbers the owner already knows makes a real non-public member
+// the third, and comparing totals across refreshes then yields a range for that
+// member. The notice and the per-guild switch answer it, not this file.
+// tests/guild_totals_db.mjs documents the padding case; it does not "fix" it.
+//
+// NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). Descriptive only.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const api = require('../../src/module-api');
+const { accountActiveSql, rollupVisibleSql } = require('./account-visibility');
+const { onMapSql } = require('./projects-feed');
+
+const { pool: defaultPool } = api;
+
+// ---------------------------------------------------------------------------
+// The constants ADR 0337 D4.4 names. Exported so a route, a test and a doc read
+// the same number.
+// ---------------------------------------------------------------------------
+
+// The 1-2-5 band scale: 10, 20, 50, 100, 200, 500, ... Below the first band a
+// total publishes as 0, which a page renders as "under 10".
+const TOTALS_BAND_MANTISSAS = [1, 2, 5];
+const TOTALS_FIRST_BAND = 10;
+
+// k: non-public members' numbers enter only while at least this many of them
+// are counted.
+const NON_PUBLIC_MIN_COUNTED = 3;
+
+// A row is refreshed at most this often. Each before/after comparison costs an
+// observer this long.
+const TOTALS_REFRESH_DAYS = 7;
+
+// The columns are integer; a band floor never exceeds what they can hold.
+const INT4_MAX = 2147483647;
+
+// bandFloor(n) → the largest band on the scale that is <= n, or 0 below the
+// first band (and for a negative or non-numeric sum).
+function bandFloor(value) {
+  const raw = Math.floor(Number(value));
+  if (!Number.isFinite(raw) || raw < TOTALS_FIRST_BAND) return 0;
+  const n = Math.min(raw, INT4_MAX);
+  let decade = TOTALS_FIRST_BAND;
+  while (decade * 10 <= n) decade *= 10;
+  let floor = decade;
+  for (const m of TOTALS_BAND_MANTISSAS) if (m * decade <= n) floor = m * decade;
+  return floor;
+}
+
+// ---------------------------------------------------------------------------
+// The computation
+// ---------------------------------------------------------------------------
+
+// The exact sums for a batch of guilds, one row per id asked for (a guild with
+// nobody counted sums to zero). Internal: its output is never stored or sent —
+// only its band floors are.
+async function computeGuildSums(guildIds, { pool = defaultPool } = {}) {
+  if (!guildIds.length) return [];
+  const { rows } = await pool.query(
+    `WITH m AS (
+       SELECT gm.guild_id, gm.github_id,
+              (gm.shown_publicly AND ${rollupVisibleSql('pa')}) AS is_public
+         FROM platform_identity_guild_members gm
+         JOIN platform_identity_accounts pa ON pa.github_id = gm.github_id
+        WHERE gm.guild_id = ANY($1::bigint[])
+          AND gm.counted_in_totals
+          AND ${accountActiveSql('pa')}
+     ),
+     k AS (
+       SELECT guild_id, count(*) FILTER (WHERE NOT is_public) AS non_public
+         FROM m GROUP BY guild_id
+     ),
+     counted AS (
+       SELECT m.guild_id, m.github_id, m.is_public
+         FROM m JOIN k ON k.guild_id = m.guild_id
+        WHERE m.is_public OR k.non_public >= $2
+     ),
+     sums AS (
+       SELECT c.guild_id,
+              COALESCE(sum(a.credits), 0)::bigint       AS credits,
+              COALESCE(sum(a.tasks_shipped), 0)::bigint AS works_shipped,
+              COALESCE(sum(a.karma), 0)::bigint         AS karma
+         FROM counted c
+         LEFT JOIN platform_identity_builder_project_activity a ON a.github_id = c.github_id
+        GROUP BY c.guild_id
+     ),
+     projs AS (
+       SELECT c.guild_id, count(DISTINCT p.id)::bigint AS projects
+         FROM counted c
+         JOIN platform_identity_builder_project_activity a ON a.github_id = c.github_id
+         JOIN platform_identity_sso_clients sc ON sc.client_id = a.client_id
+         JOIN platform_identity_projects p ON p.origin = sc.origin
+        WHERE c.is_public AND ${onMapSql('p')} AND p.visibility = 'public'
+        GROUP BY c.guild_id
+     )
+     SELECT g.id::text AS guild_id,
+            COALESCE(s.credits, 0)::text        AS credits,
+            COALESCE(s.works_shipped, 0)::text  AS works_shipped,
+            COALESCE(s.karma, 0)::text          AS karma,
+            COALESCE(pr.projects, 0)::text      AS projects
+       FROM unnest($1::bigint[]) AS g(id)
+       LEFT JOIN sums s ON s.guild_id = g.id
+       LEFT JOIN projs pr ON pr.guild_id = g.id`,
+    [guildIds, NON_PUBLIC_MIN_COUNTED],
+  );
+  return rows;
+}
+
+// Refresh every guild whose record is missing or at least TOTALS_REFRESH_DAYS
+// old, stalest first, at most `limit` per call. The upsert re-asserts the age in
+// its own WHERE, so a racing sweep cannot refresh a guild twice in a week, and
+// it re-checks each guild still exists so one dissolved mid-sweep is skipped
+// rather than failing the batch. Returns { scanned, refreshed }.
+async function refreshStaleGuildTotals({ limit = 200 } = {}, { pool = defaultPool } = {}) {
+  const { rows: stale } = await pool.query(
+    `SELECT g.id::text AS id
+       FROM platform_identity_guilds g
+       LEFT JOIN platform_identity_guild_totals t ON t.guild_id = g.id
+      WHERE t.guild_id IS NULL OR t.computed_at <= now() - make_interval(days => $1::int)
+      ORDER BY t.computed_at ASC NULLS FIRST, g.id
+      LIMIT $2`,
+    [TOTALS_REFRESH_DAYS, Math.max(1, Number(limit) || 1)],
+  );
+  if (!stale.length) return { scanned: 0, refreshed: 0 };
+  const sums = await computeGuildSums(stale.map((r) => r.id), { pool });
+  const col = (k) => sums.map((r) => bandFloor(r[k]));
+  const { rowCount } = await pool.query(
+    `INSERT INTO platform_identity_guild_totals AS t
+            (guild_id, credits, works_shipped, karma, projects, computed_at)
+     SELECT u.guild_id, u.credits, u.works_shipped, u.karma, u.projects, now()
+       FROM unnest($1::bigint[], $2::int[], $3::int[], $4::int[], $5::int[])
+              AS u(guild_id, credits, works_shipped, karma, projects)
+      WHERE EXISTS (SELECT 1 FROM platform_identity_guilds g WHERE g.id = u.guild_id)
+     ON CONFLICT (guild_id) DO UPDATE
+        SET credits = EXCLUDED.credits,
+            works_shipped = EXCLUDED.works_shipped,
+            karma = EXCLUDED.karma,
+            projects = EXCLUDED.projects,
+            computed_at = EXCLUDED.computed_at
+      WHERE t.computed_at <= now() - make_interval(days => $6::int)`,
+    [sums.map((r) => r.guild_id), col('credits'), col('works_shipped'), col('karma'), col('projects'),
+      TOTALS_REFRESH_DAYS],
+  );
+  return { scanned: stale.length, refreshed: rowCount };
+}
+
+// ---------------------------------------------------------------------------
+// The read
+// ---------------------------------------------------------------------------
+
+// A guild's published record, or null before its first refresh. A SELECT and
+// nothing else: the record moves only on the poller's clock, never on a read.
+// The caller decides whether the guild may be read at all (getPublicGuild).
+async function readGuildTotals(guildId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT credits, works_shipped, karma, projects, computed_at
+       FROM platform_identity_guild_totals
+      WHERE guild_id = $1`,
+    [guildId],
+  );
+  const r = rows[0];
+  if (!r) return null;
+  return {
+    credits: r.credits,
+    works_shipped: r.works_shipped,
+    karma: r.karma,
+    projects: r.projects,
+    as_of: r.computed_at,
+  };
+}
+
+module.exports = {
+  TOTALS_BAND_MANTISSAS,
+  TOTALS_FIRST_BAND,
+  NON_PUBLIC_MIN_COUNTED,
+  TOTALS_REFRESH_DAYS,
+  bandFloor,
+  computeGuildSums,
+  refreshStaleGuildTotals,
+  readGuildTotals,
+};

package/modules/platform-identity/guilds.js

@@ -26,7 +26,7 @@
 //     be seen by the guild, never by the world). Every count is the length of a
 //     list the reader may see.
 //   * counted_in_totals (ADR 0337 D4.4) is stored and switchable here; the
-//     totals that read it are task 1002302's.
+//     totals that read it live in guild-totals.js (task 1002302).
 //
 // NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). A guild grants no rank,
 // credits, admission or access to any project.
@@ -40,6 +40,7 @@ const {
 } = require('./account-visibility');
 const conn = require('./connections');
 const { normalizeHandle } = require('./platform-identity');
+const { readGuildTotals } = require('./guild-totals');
 
 const { pool: defaultPool } = api;
 
@@ -654,6 +655,8 @@ async function listGuildRequests({ guildId, ownerGithubId }, { pool = defaultPoo
 // vary by one. The roster is shown_publicly AND accountVisibleSql, ordered only
 // by what it publishes (ADR 0255), capped at LIST_MAX; `size` is the length of
 // the list returned, never a total beside it (D4: there is no "+N more").
+// `totals` is the weekly rounded record (ADR 0337 D4.4), or null before the
+// first refresh — read, never computed, here.
 async function getPublicGuild(slug, { pool = defaultPool } = {}) {
   const g = await pool.query(
     `SELECT id, slug, name, description, created_at
@@ -672,8 +675,9 @@ async function getPublicGuild(slug, { pool = defaultPool } = {}) {
       LIMIT $2`,
     [guild.id, LIST_MAX],
   );
+  const totals = await readGuildTotals(guild.id, { pool });
   const { id, ...shown } = guild;
-  return { guild: shown, members: rows, size: rows.length };
+  return { guild: shown, members: rows, size: rows.length, totals };
 }
 
 module.exports = {

package/modules/platform-identity/migrations/platform_identity_027_guild_totals.sql

@@ -0,0 +1,45 @@
+-- platform_identity_027_guild_totals.sql — a guild's collective record, as a
+-- stored weekly snapshot (task 1002302, R26; ADR 0337 D4.4, superseding ADR
+-- 0336 D5's read-time sum).
+--
+-- WHAT THIS IS. One row per guild: the totals its page publishes, and when they
+-- were computed. guild-totals.js writes it from a poller and nothing else does;
+-- the public read only SELECTs it. A guild with no row yet publishes no totals.
+--
+-- THE SHAPE CARRIES THE RULES, so no reader has to remember them:
+--   * ONLY BAND FLOORS ARE STORED. Every column is already rounded down on the
+--     1-2-5 scale (guild-totals.js bandFloor). The exact sum exists only in
+--     memory for the moment it takes to round it, so no read, dump or backup can
+--     recover a number more precise than the page shows. The CHECKs hold the
+--     floor at zero; the scale itself lives in the domain as a named constant.
+--   * computed_at IS THE WEEKLY GATE. The writer's upsert refreshes a row only
+--     when its computed_at is at least a week old, in the same statement, so two
+--     racing sweeps cannot refresh a guild twice in a week.
+--   * THE FK CASCADES, so a dissolved guild takes its record with it (the ADR
+--     0336 D2 no-tombstone reason).
+--
+-- NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank, credit or admission
+-- path reads this table; it is descriptive only.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). CREATE only, so the
+-- previous release still runs against this schema. Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_guild_totals (
+  guild_id       bigint PRIMARY KEY REFERENCES platform_identity_guilds(id) ON DELETE CASCADE,
+  credits        integer NOT NULL CHECK (credits >= 0),
+  works_shipped  integer NOT NULL CHECK (works_shipped >= 0),
+  karma          integer NOT NULL CHECK (karma >= 0),
+  projects       integer NOT NULL CHECK (projects >= 0),
+  computed_at    timestamptz NOT NULL DEFAULT now()
+);
+
+-- The sweep's working set: the stalest rows first.
+CREATE INDEX IF NOT EXISTS platform_identity_guild_totals_computed_at
+  ON platform_identity_guild_totals (computed_at);
+
+COMMENT ON TABLE platform_identity_guild_totals IS
+  'A guild''s published collective record (ADR 0337 D4.4, task 1002302): band floors on the 1-2-5 scale, never exact sums, recomputed at most weekly by a poller and never on a read. Non-public members'' numbers enter only while the guild has at least 3 counted non-public members. Descriptive only, never authority (ADR 0016).';
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -13,7 +13,7 @@
   "contributes": {
     "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
     "migrations": true,
-    "pollers": ["code-sweep", "visibility-pull"]
+    "pollers": ["code-sweep", "visibility-pull", "guild-totals"]
   },
   "provides": ["platform-identity.hub", "project.publishGate", "project.catalog"],
   "consumes": []

package/modules/platform-identity/pollers/guild-totals.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// modules/platform-identity/pollers/guild-totals.js — the loader poller entry that
+// refreshes guilds' collective records (R26, task 1002302; ADR 0337 D4.4). The
+// loader's startModulePollers requires THIS file and calls start(deps) at boot /
+// stop() at shutdown for the ENABLED module only (the hub) — non-blocking and
+// failure-isolated, so a sweep hiccup never touches a read. Mirrors visibility-pull.js.
+//
+// WHY A POLLER. D4.4 says the totals are "recomputed at most once a week, never on a
+// read": a read that recomputed would let an observer move the number they are
+// watching by asking for it. So the only writer runs on its own clock, and the
+// public read (getPublicGuild) only SELECTs what it last wrote.
+//
+// Proof: ../../../tests/guild_totals.mjs (DB-free), ../../../tests/guild_totals_db.mjs
+
+const api = require('../../../src/module-api');
+const guildTotals = require('../guild-totals');
+
+const log = api.logger('platform-identity');
+
+// Hourly. The weekly limit is enforced per row by refreshStaleGuildTotals, not by
+// this cadence, so the interval only sets how late a due row may run — and how soon
+// a new guild gets its first record.
+const SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+
+// Guilds per sweep. A ceiling rather than a page: refreshStaleGuildTotals takes the
+// stalest first, so a backlog larger than this converges over a few sweeps.
+const SWEEP_LIMIT = 200;
+
+// Wait before the FIRST sweep so boot is never competing with it.
+const FIRST_SWEEP_DELAY_MS = 60 * 1000;
+
+let timer = null;
+let firstTimer = null;
+
+async function sweepOnce(deps = {}) {
+  try {
+    const out = await guildTotals.refreshStaleGuildTotals(
+      { limit: SWEEP_LIMIT },
+      deps.pool ? { pool: deps.pool } : {},
+    );
+    // One line per sweep, and only when something was refreshed.
+    if (out.refreshed > 0) {
+      log.info({ refreshed: out.refreshed, scanned: out.scanned }, 'guild-totals: record(s) refreshed');
+    }
+    return out;
+  } catch (err) {
+    // Best-effort: a sweep failure must never crash the process. The rows it did not
+    // refresh stay due, so the next sweep picks them up.
+    log.error({ err: err && err.message }, 'guild-totals sweep failed (non-fatal)');
+    return null;
+  }
+}
+
+module.exports = {
+  start: (deps = {}) => {
+    if (timer || firstTimer) return; // idempotent
+    firstTimer = setTimeout(() => {
+      firstTimer = null;
+      sweepOnce(deps);
+      timer = setInterval(() => { sweepOnce(deps); }, SWEEP_INTERVAL_MS);
+      if (timer.unref) timer.unref();
+    }, FIRST_SWEEP_DELAY_MS);
+    // unref so neither timer keeps the process alive on its own.
+    if (firstTimer.unref) firstTimer.unref();
+  },
+  stop: () => {
+    if (timer) { clearInterval(timer); timer = null; }
+    if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
+  },
+  // exported for tests
+  sweepOnce,
+  SWEEP_INTERVAL_MS,
+  SWEEP_LIMIT,
+  FIRST_SWEEP_DELAY_MS,
+};

package/modules/platform-identity/routes/guilds-public.js

@@ -3,12 +3,17 @@
 // routes/guilds.js is own-scoped and held there by tests/own_scope_guard.mjs;
 // this one is deliberately not.
 //
-//   GET /guilds/:slug — a PUBLIC guild's name, description, public roster and
-//   size. 404 for an unknown slug AND for an unlisted guild, to everyone, its own
-//   members included: the read takes no viewer, so it cannot vary by one (the
-//   private-profile rule, ADR 0171 D4). Members reach an unlisted guild through
-//   the own-scope GET /guilds/:slug/members. The page at /g/<slug> is task
-//   1002301's; this is its read.
+//   GET /guilds/:slug — a PUBLIC guild's name, description, public roster,
+//   size and rounded weekly totals (task 1002302). 404 for an unknown slug AND
+//   for an unlisted guild, to everyone, its own members included: the read
+//   takes no viewer, so it cannot vary by one (the private-profile rule, ADR
+//   0171 D4). Members reach an unlisted guild through the own-scope
+//   GET /guilds/:slug/members. The page at /g/<slug> is task 1002301's; this is
+//   its read.
+//
+//   GET /guilds — the guild MAP (task 1002306, R30; ADR 0336 D8): public guilds
+//   with a non-empty public roster, ranked by size or by the stored shipped band
+//   floor, slug tiebreak, paged. Who and how live in ../guild-map.js.
 //
 // Reaches core only through the doorway (ADR 0083).
 'use strict';
@@ -16,6 +21,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const guilds = require('../guilds');
+const guildMap = require('../guild-map');
 const { createReadRateLimit } = require('../read-rate-limit');
 
 const { pool } = api;
@@ -33,20 +39,52 @@ function logError(msg) {
 // uncapped scraper could walk the slug space at line rate.
 const guildReadRateLimit = createReadRateLimit({ scope: 'guild-public-read', limit: 120 });
 
+// The map's own budget: one read aggregates every public guild's roster, so it
+// gets the community reads' tighter cap rather than the single-guild one.
+const guildMapRateLimit = createReadRateLimit({ scope: 'guild-map-read', limit: 60 });
+
 module.exports = function guildPublicRoutes() {
   const router = express.Router();
 
+  // rank: public — the guild map (?order=size|shipped, default size;
+  // ?limit=&offset=). Viewer-independent: it reads no session. size is the
+  // public roster's length; shipped is R26's stored band floor (ADR 0337 D4.4),
+  // never an exact sum, null before a guild's first refresh. no-store: a hide or
+  // a visibility flip moves size on the very next read (ADR 0171 D5).
+  router.get('/guilds', guildMapRateLimit, async (req, res) => {
+    const order = req.query.order === undefined || req.query.order === ''
+      ? guildMap.DEFAULT_ORDER
+      : req.query.order;
+    if (!guildMap.isOrder(order)) {
+      return res.fail('guild_map_bad_order', { status: 400, message: `order must be one of: ${guildMap.ORDER_KEYS.join(', ')}` });
+    }
+    try {
+      const map = await guildMap.listGuildMap({ order, limit: req.query.limit, offset: req.query.offset }, { pool });
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        order: map.order,
+        count: map.results.length,
+        results: map.results,
+        page: { limit: map.limit, offset: map.offset },
+      });
+    } catch (err) {
+      logError(`GET /guilds failed: ${err && err.message}`);
+      res.fail('guild_map_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: public — a public guild's page data. The roster is the members who
   // agreed to be shown AND whose own accounts are publicly visible (ADR 0336 D4);
-  // size is that roster's length. no-store: a hide or a visibility flip must beat
-  // every cache (ADR 0171 D5).
+  // size is that roster's length; totals are the weekly band floors (ADR 0337
+  // D4.4), null before the first refresh. no-store: a hide or a visibility flip
+  // must beat every cache (ADR 0171 D5).
   router.get('/guilds/:slug', guildReadRateLimit, async (req, res) => {
     res.set('Cache-Control', 'no-store');
     try {
       const slug = guilds.lookupSlug(req.params.slug);
       const out = slug ? await guilds.getPublicGuild(slug, { pool }) : null;
       if (!out) return res.fail('guild_not_found', 404);
-      res.json({ guild: out.guild, members: out.members, size: out.size });
+      res.json({ guild: out.guild, members: out.members, size: out.size, totals: out.totals });
     } catch (err) {
       logError(`GET /guilds/:slug failed: ${err && err.message}`);
       res.fail('guild_read_failed', { status: 500, message: 'internal error' });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.19",
+  "version": "1.20.21",
   "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/release-notes.json

@@ -8170,5 +8170,17 @@
       "id": "1004268",
       "text": "Builders' activity numbers on the platform can no longer briefly go backwards when two updates arrive at the same time."
     }
+  ],
+  "1.20.20": [
+    {
+      "id": "1002302",
+      "text": "Guilds now show a combined track record: rounded totals of their members' credits, shipped work and projects, refreshed once a week. Members who keep their numbers private still count, but only when at least three such members"
+    }
+  ],
+  "1.20.21": [
+    {
+      "id": "1002306",
+      "text": "The hub can now list guilds ranked by size or by how much their members have shipped, using the rounded weekly totals. Only public guilds with visible members appear, and private members are never counted."
+    }
   ]
 }

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

@@ -178,6 +178,15 @@ const INTEGRATION = new Set([
   // proves the one-owner partial index, the expiry CTE drained before its insert,
   // the cascade on dissolve and the two-statement transfer.
   'guilds_db',
+  // task 1002302 (R26): a guild's weekly rounded totals against real SQL. Who is
+  // counted (three predicates and a FILTERed k count) and the upsert's week guard,
+  // re-evaluated against a racing writer's committed row, are planner facts; the
+  // DB-free sibling (guild_totals) pins the band scale and statement shapes.
+  'guild_totals_db',
+  // task 1002306 (R30): the guild map against real SQL — the INNER join that drops
+  // an empty public roster, the capped roster count, and NULLS LAST on a guild
+  // with no weekly record yet. guilds_api §3b pins the route and statement shape.
+  'guild_map_db',
   // task 1003935: 'linkify_refs' was swept in with the three above without the
   // no-DB check they were being fixed for. It touches no Postgres at all — pure
   // string work plus a filesystem walk — so the DB-free lane skipped it and the

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.19'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.21'; // 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('discord'); log.info('mounted');