@bongos/core 1.20.19 → 1.20.20

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.19",
-  "core_contract": "1.20.19",
-  "source_commit": "634240626e5878bfa71f84a126f2a5066315c631",
+  "core_version": "1.20.20",
+  "core_contract": "1.20.20",
+  "source_commit": "81de3611c8c98f0a428be1780f94435846cd7bf2",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T14:16:31.957Z",
+  "built_at": "2026-09-30T14:55:04.182Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 557,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2631,
+    "functional_verbatim": 2636,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3214,
-  "tree_sha256": "1941a2dc44fb870a71c3227166d032c854f48237c2fef4cc958e355f9658f585",
+  "file_count": 3219,
+  "tree_sha256": "9d08157c7a131c0010616436de1c1b4b0ecd19030def84afd3ed402813e39499",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -347,7 +347,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "2fb562be1e4db7d2471f9ed6b7284d8b95071d9a365982c4721ff72febdfba63"
+      "sha256": "d9b3edd04125960791f6282252f5f31b2ace6abb90beeb19c483af1a422fbf53"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -2247,7 +2247,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "796e47e332b7788981b5118aabfbacdc9b728e22796da301cedce44ac1ab8dc6"
+      "sha256": "4167b07fddd64f47f901082e130a12f307e4e2fab5ac9bc821e24a0c4f6f3d72"
     },
     {
       "path": "docs/architecture.md",
@@ -2777,7 +2777,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f7fe6c9e2a06b6dfb71087791b38b22ff4ce57f897320ade88e65a131fdb4160"
+      "sha256": "2b82bf65da0987ffc862ad6369e0cbcf8e6adef0a70915cf7a7a2c2289a69c85"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6864,10 +6864,15 @@
       "mode": "0000644",
       "sha256": "793e96feacef39ec52166dd7372c894a25679c7137c9c3c5e9df38ec323f1c4a"
     },
+    {
+      "path": "modules/platform-identity/guild-totals.js",
+      "mode": "0000644",
+      "sha256": "8e07aed97641d68d826ffea3055d209b8fd9eb172e1d000f17e335f7296cc6d6"
+    },
     {
       "path": "modules/platform-identity/guilds.js",
       "mode": "0000644",
-      "sha256": "5f1189de2d33fe550b4a84b8105ccb0a0b60a08d342fde6c9bfcec30b969d4ff"
+      "sha256": "e048e674b087eae9035da5b3449d8f4029ec329a42333980eb21ac3e6c13a297"
     },
     {
       "path": "modules/platform-identity/hub-device.js",
@@ -7019,10 +7024,15 @@
       "mode": "0000644",
       "sha256": "9f8d582d626dec82b55b96272f9d6d7f6c1488ac28bd9a98ab673404afde0c8e"
     },
+    {
+      "path": "modules/platform-identity/migrations/platform_identity_027_guild_totals.sql",
+      "mode": "0000644",
+      "sha256": "9b263f91ce6df19640ef8ae413f3eb40cc17589924fdf21256da7647b55631c1"
+    },
     {
       "path": "modules/platform-identity/module.json",
       "mode": "0000644",
-      "sha256": "73d471a97dac75af28c561149649176739475dc262b3c42e37800fd73a36fe21"
+      "sha256": "48c9d82d9ec647430a97ba19f403b22e7eba13e16ff553b6bbd08691a8918a7b"
     },
     {
       "path": "modules/platform-identity/origin-containment.js",
@@ -7039,6 +7049,11 @@
       "mode": "0000644",
       "sha256": "b6eea95dbe66a3126fc2c73d93237cf38dd648a803e910eb88fbd5c780ccef62"
     },
+    {
+      "path": "modules/platform-identity/pollers/guild-totals.js",
+      "mode": "0000644",
+      "sha256": "cfd421477fdcee4a8a92ed30fa1bb987e9f8a055862c8564de9a9bfe8eb5e089"
+    },
     {
       "path": "modules/platform-identity/pollers/visibility-pull.js",
       "mode": "0000644",
@@ -7092,7 +7107,7 @@
     {
       "path": "modules/platform-identity/routes/guilds-public.js",
       "mode": "0000644",
-      "sha256": "1a8d2d70d4b9f5e4cfc93bd1f6d83911ab625463866527838d74944162f978de"
+      "sha256": "b6029f6f9d40fec18e42c0eaba75779ad7baa0c29df47bb7fe248a83cb783396"
     },
     {
       "path": "modules/platform-identity/routes/guilds.js",
@@ -8872,12 +8887,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "01b48ab609eb6e0b51a3420a79cd5e13158e3bf3f996a5bd30dbd1c2927c5b91"
+      "sha256": "830a8f9950a12b57c520a79198562f423818f1f1a98095d7122ddf4a6100f052"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "15c8438b1ea0a683e536e21ca2ed353042533ddf893b727c3835d5422595797a"
+      "sha256": "3b0d575917863d61bca84ddc2ce68886c33bc0d4fae9825a7abb8e2a5da7eec8"
     },
     {
       "path": "public-docs/index.html",
@@ -8897,7 +8912,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "426ac20e29712617fe5881fdc428ff184ab09e2e0cfc093a99b1f10c192291a3"
+      "sha256": "47fee7ce9947c485d183f574d1564c43da3329822ffd470897609631fe95effc"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10057,7 +10072,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "456b185fcbab4fb486fb15aecf0de260183c9eda9942c12c0123000a8baeaa57"
+      "sha256": "b4b2358efdc538a35472258f5c0812bc3990e179612f663810cdcde6f1e0b143"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -11012,7 +11027,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "f80e044dd532aabc41f3731129d98f63c98c2d60a9a4fc3eecbf713e3a86650e"
+      "sha256": "091a4bde841eaad09639727d4691f0c8a5555926e33cbffc49c7acc6b95870a6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13064,10 +13079,20 @@
       "mode": "0000644",
       "sha256": "8298006ae35010d726bcac8a2d351a5aa932d2ee6d5b53ed7b8a5c095ca5e54f"
     },
+    {
+      "path": "tests/guild_totals.mjs",
+      "mode": "0000644",
+      "sha256": "c488d1231e2d7b9233e7b857cf584c4c6df9c596b34c7e4a74c8d976f38d1ada"
+    },
+    {
+      "path": "tests/guild_totals_db.mjs",
+      "mode": "0000644",
+      "sha256": "095f66255fa4755ff57db9aef07a5334f12a2f1720a71e9523eeb5d28356029a"
+    },
     {
       "path": "tests/guilds_api.mjs",
       "mode": "0000644",
-      "sha256": "9124d0f1e8edfd91b97fc7226a0f4f68638261c5dfa36954bedf6af95d24ec07"
+      "sha256": "2476ef4a332fa6d82d9d40ca798012c5aef40a74b08c5ca8d8d40e1975223cbb"
     },
     {
       "path": "tests/guilds_db.mjs",

package/clients/bongos-client/index.d.ts

@@ -74,7 +74,7 @@ export interface GetGovernmentRanksResponse { ranks: unknown }
 export interface GetGradesByBuilderResponse { window_days: unknown; builders: unknown }
 export interface GetGuildsSlugMembersResponse { guild: unknown; you: unknown; members: unknown; count: unknown }
 export interface GetGuildsSlugRequestsResponse { incoming: unknown; outgoing: unknown; incoming_count: unknown; outgoing_count: unknown }
-export interface GetGuildsSlugResponse { guild: unknown; members: unknown; size: unknown }
+export interface GetGuildsSlugResponse { guild: unknown; members: unknown; size: unknown; totals: unknown }
 export interface GetHealthzResponse { ok: boolean; auth_configured: unknown }
 export interface GetHelpRequestsArchiveResponse { asked_of_you: unknown; asked_of_others: unknown; count: unknown; crafts: unknown }
 export interface GetHelpRequestsForMeResponse { help_requests: unknown; count: unknown; crafts: unknown }

package/docs/api/openapi.json

@@ -8645,7 +8645,7 @@
           "guilds"
         ],
         "summary": "GET /guilds/:slug",
-        "description": "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).\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "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; 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).\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "modules/platform-identity/routes/guilds-public.js",
         "parameters": [
@@ -22586,12 +22586,14 @@
         "properties": {
           "guild": {},
           "members": {},
-          "size": {}
+          "size": {},
+          "totals": {}
         },
         "required": [
           "guild",
           "members",
-          "size"
+          "size",
+          "totals"
         ]
       },
       "GetHealthzResponse": {

package/docs/module-api-changelog.md

@@ -2695,5 +2695,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.17 with no explicit bump. run 36724081934. (task 1002620)
   1.20.19 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.20.18 with no explicit bump. run 36727774141. (task 1002620)
+  1.20.20 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.20.19 with no explicit bump. run 36732445320. (task 1002620)
 ---------------------------------------------------------------------------
 ```

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,13 @@
 // 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.
 //
 // Reaches core only through the doorway (ADR 0083).
 'use strict';
@@ -38,15 +39,16 @@ module.exports = function guildPublicRoutes() {
 
   // 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.20",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.19",
+      "version": "1.20.20",
       "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.20",
   "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,11 @@
       "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"
+    }
   ]
 }

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

@@ -178,6 +178,11 @@ 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 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.20'; // 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');

package/tests/guild_totals.mjs

@@ -0,0 +1,183 @@
+// tests/guild_totals.mjs — a guild's collective record (R26, task 1002302; ADR
+// 0337 D4.4, superseding ADR 0336 D5).
+//
+// DB-free. What it holds, each easy to lose in a later edit without anything else
+// going red:
+//
+//   1. THE BAND SCALE. 1-2-5 from 10, the band floor published, 0 below the first
+//      band — exact numbers never reach a row.
+//   2. THE NAMED CONSTANTS are the ADR's: k = 3, a 7-day refresh.
+//   3. THE COMPUTATION COMPOSES THE SHARED PREDICATES (accountActiveSql for who may
+//      count at all, rollupVisibleSql for who is public) and never restates them;
+//      only public members' named public projects enter the project count.
+//   4. THE WEEKLY GATE IS IN THE WRITE ITSELF, and the read is a bare SELECT.
+//   5. THE POLLER IS REGISTERED and a failed sweep never throws.
+//
+// The rules that only a real planner can settle (who is counted, when k flips,
+// the padding case, the upsert's age guard) are proved in tests/guild_totals_db.mjs.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const gt = require('../modules/platform-identity/guild-totals.js');
+const poller = require('../modules/platform-identity/pollers/guild-totals.js');
+const { accountActiveSql, rollupVisibleSql } = require('../modules/platform-identity/account-visibility.js');
+const { onMapSql } = require('../modules/platform-identity/projects-feed.js');
+
+// A pool that records every statement and answers from a queue.
+function recordingPool(responses = []) {
+  const calls = [];
+  const queue = [...responses];
+  return {
+    calls,
+    query(text, params) {
+      calls.push({ text, params });
+      const next = queue.shift();
+      if (next instanceof Error) return Promise.reject(next);
+      return Promise.resolve(next || { rows: [], rowCount: 0 });
+    },
+  };
+}
+
+// ── 1. The band scale ──
+
+test('bandFloor publishes the 1-2-5 band floor from 10, and 0 below it', () => {
+  const cases = [
+    [0, 0], [1, 0], [9, 0], [9.99, 0],
+    [10, 10], [19, 10], [20, 20], [49, 20], [50, 50], [99, 50],
+    [100, 100], [199, 100], [200, 200], [499, 200], [500, 500], [999, 500],
+    [1000, 1000], [2500, 2000], [7777, 5000], [12345, 10000],
+  ];
+  for (const [n, want] of cases) assert.equal(gt.bandFloor(n), want, `bandFloor(${n})`);
+});
+
+test('bandFloor never publishes more than it was given, and fails closed on junk', () => {
+  for (const n of [-50, -1, NaN, undefined, null, 'abc', Infinity]) {
+    assert.equal(gt.bandFloor(n), 0, `bandFloor(${String(n)}) is 0`);
+  }
+  // Postgres hands sums back as strings; the scale reads them the same.
+  assert.equal(gt.bandFloor('1234'), 1000);
+  // The columns are integer: a floor never exceeds what they can hold.
+  assert.equal(gt.bandFloor(5e12), 2000000000);
+  for (let n = 0; n < 5000; n += 7) assert.ok(gt.bandFloor(n) <= n);
+});
+
+// ── 2. The named constants ──
+
+test('the constants are the ADR\'s own numbers', () => {
+  assert.equal(gt.NON_PUBLIC_MIN_COUNTED, 3, 'k = 3 (ADR 0337 D4.4)');
+  assert.equal(gt.TOTALS_REFRESH_DAYS, 7, 'at most weekly');
+  assert.deepEqual(gt.TOTALS_BAND_MANTISSAS, [1, 2, 5]);
+  assert.equal(gt.TOTALS_FIRST_BAND, 10);
+});
+
+// ── 3. The computation ──
+
+test('who counts is composed from the shared predicates, never restated', async () => {
+  const pool = recordingPool([{ rows: [] }]);
+  await gt.computeGuildSums(['7', '8'], { pool });
+  const { text, params } = pool.calls[0];
+  assert.ok(text.includes(accountActiveSql('pa')), 'an un-consented account never counts');
+  assert.ok(text.includes(`(gm.shown_publicly AND ${rollupVisibleSql('pa')}) AS is_public`),
+    'public = shown on this guild\'s page AND the account\'s own record is public');
+  assert.match(text, /AND gm\.counted_in_totals/, 'the per-guild switch is honoured');
+  assert.match(text, /WHERE m\.is_public OR k\.non_public >= \$2/,
+    'non-public numbers enter only at or above k');
+  assert.deepEqual(params, [['7', '8'], 3], 'k is bound from the named constant');
+});
+
+test('only public members\' named public projects enter the project count', async () => {
+  const pool = recordingPool([{ rows: [] }]);
+  await gt.computeGuildSums(['7'], { pool });
+  const projs = pool.calls[0].text.split('projs AS')[1];
+  assert.ok(projs.includes(`WHERE c.is_public AND ${onMapSql('p')} AND p.visibility = 'public'`),
+    'ADR 0336 D5\'s union rule: never a non-public member\'s projects, never a non-public project');
+  assert.match(projs, /count\(DISTINCT p\.id\)/, 'a project two members share counts once');
+});
+
+test('an empty batch asks the database nothing', async () => {
+  const pool = recordingPool();
+  assert.deepEqual(await gt.computeGuildSums([], { pool }), []);
+  assert.equal(pool.calls.length, 0);
+});
+
+// ── 4. The weekly gate, and a read that only reads ──
+
+test('refresh stores band floors only, and re-asserts the week in its own upsert', async () => {
+  const pool = recordingPool([
+    { rows: [{ id: '7' }, { id: '8' }] },
+    { rows: [
+      { guild_id: '7', credits: '1234', works_shipped: '57', karma: '-3', projects: '2' },
+      { guild_id: '8', credits: '0', works_shipped: '0', karma: '0', projects: '0' },
+    ] },
+    { rows: [], rowCount: 2 },
+  ]);
+  const out = await gt.refreshStaleGuildTotals({ limit: 50 }, { pool });
+  assert.deepEqual(out, { scanned: 2, refreshed: 2 });
+
+  const [pick, , upsert] = pool.calls;
+  assert.match(pick.text, /t\.guild_id IS NULL OR t\.computed_at <= now\(\) - make_interval\(days => \$1::int\)/,
+    'due = never computed, or at least a week old');
+  assert.match(pick.text, /ORDER BY t\.computed_at ASC NULLS FIRST/, 'stalest first');
+  assert.deepEqual(pick.params, [7, 50]);
+
+  assert.match(upsert.text, /ON CONFLICT \(guild_id\) DO UPDATE[\s\S]*WHERE t\.computed_at <= now\(\) - make_interval\(days => \$6::int\)/,
+    'a racing sweep cannot refresh a guild twice in a week');
+  assert.match(upsert.text, /WHERE EXISTS \(SELECT 1 FROM platform_identity_guilds g WHERE g\.id = u\.guild_id\)/,
+    'a guild dissolved mid-sweep is skipped, not an FK failure for the batch');
+  assert.deepEqual(upsert.params, [['7', '8'], [1000, 0], [50, 0], [0, 0], [0, 0], 7],
+    'only band floors are written — 1234 credits is stored as 1000, never 1234');
+});
+
+test('nothing due → no computation and no write', async () => {
+  const pool = recordingPool([{ rows: [] }]);
+  assert.deepEqual(await gt.refreshStaleGuildTotals({}, { pool }), { scanned: 0, refreshed: 0 });
+  assert.equal(pool.calls.length, 1);
+});
+
+test('the read is one SELECT of the stored record, and null before the first refresh', async () => {
+  const at = new Date('2026-09-28T00:00:00Z');
+  const pool = recordingPool([
+    { rows: [{ credits: 1000, works_shipped: 50, karma: 0, projects: 2, computed_at: at }] },
+    { rows: [] },
+  ]);
+  assert.deepEqual(await gt.readGuildTotals('7', { pool }),
+    { credits: 1000, works_shipped: 50, karma: 0, projects: 2, as_of: at });
+  assert.equal(await gt.readGuildTotals('8', { pool }), null);
+  for (const c of pool.calls) {
+    assert.match(c.text.trim(), /^SELECT credits, works_shipped, karma, projects, computed_at\s+FROM platform_identity_guild_totals\s+WHERE guild_id = \$1$/);
+  }
+});
+
+test('the migration stores no exact sum and no member count', () => {
+  const sql = readFileSync(new URL('../modules/platform-identity/migrations/platform_identity_027_guild_totals.sql', import.meta.url), 'utf8');
+  const table = sql.split('CREATE TABLE IF NOT EXISTS platform_identity_guild_totals (')[1].split(');')[0];
+  const cols = table.split('\n').map((l) => l.trim().split(/\s+/)[0]).filter((c) => /^[a-z_]+$/.test(c));
+  assert.deepEqual(cols, ['guild_id', 'credits', 'works_shipped', 'karma', 'projects', 'computed_at'],
+    'a counted-member count, or a flag saying non-public numbers are in, would reveal how many non-public members a guild has');
+  assert.match(table, /REFERENCES platform_identity_guilds\(id\) ON DELETE CASCADE/, 'a dissolved guild takes its record with it');
+});
+
+// ── 5. The poller ──
+
+test('the poller is registered on the module and is hourly, with the weekly limit per row', () => {
+  const manifest = JSON.parse(readFileSync(new URL('../modules/platform-identity/module.json', import.meta.url), 'utf8'));
+  assert.ok(manifest.contributes.pollers.includes('guild-totals'));
+  assert.equal(poller.SWEEP_INTERVAL_MS, 60 * 60 * 1000);
+  assert.equal(typeof poller.start, 'function');
+  assert.equal(typeof poller.stop, 'function');
+});
+
+test('a failed sweep is logged and swallowed, never thrown', async () => {
+  const pool = recordingPool([new Error('db down')]);
+  assert.equal(await poller.sweepOnce({ pool }), null);
+});
+
+test('a sweep hands the injected pool through', async () => {
+  const pool = recordingPool([{ rows: [] }]);
+  assert.deepEqual(await poller.sweepOnce({ pool }), { scanned: 0, refreshed: 0 });
+  assert.equal(pool.calls.length, 1);
+});

package/tests/guild_totals_db.mjs

@@ -0,0 +1,292 @@
+// tests/guild_totals_db.mjs — a guild's collective record against REAL SQL
+// (R26, task 1002302; ADR 0337 D4.4).
+//
+// Why a real database: who is counted is a join over three predicates and a
+// FILTERed count, the k gate is a CTE comparison, and the weekly limit is a WHERE
+// on an upsert's conflict branch — whose re-evaluation against the row a racing
+// writer just committed only a real Postgres settles. The DB-free sibling,
+// tests/guild_totals.mjs, holds the band scale and the statement shapes.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set so the default DB-free lane never runs it. Fixture ids are
+// high-numbered and every guild slug starts r26-, so a shared DB is safe; all
+// fixtures are deleted before and after.
+//
+// Run:  DATABASE_URL=... node tests/guild_totals_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 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(`guild_totals_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const gt = require('../modules/platform-identity/guild-totals.js');
+const guilds = require('../modules/platform-identity/guilds.js');
+
+// The cast. Credits are powers of two where it matters, so every exact sum below
+// names exactly which members went into it.
+const OWN = 9002302001;    // public, shown — the guild's owner
+const PUB = 9002302002;    // public, shown
+const HID1 = 9002302003;   // hides their numbers
+const HID2 = 9002302004;   // hides their numbers
+const HID3 = 9002302005;   // hides their numbers
+const PRIV = 9002302006;   // private account
+const UNSHOWN = 9002302007; // public account, not shown on this guild's page
+const OFF = 9002302008;    // public, shown, switched counting OFF
+const PROV = 9002302009;   // provisional — never consented
+const FAKE1 = 9002302010;  // the padding case: private, numbers the owner knows
+const FAKE2 = 9002302011;
+const TARGET = 9002302012; // hides their numbers
+const ALL_IDS = [OWN, PUB, HID1, HID2, HID3, PRIV, UNSHOWN, OFF, PROV, FAKE1, FAKE2, TARGET];
+
+const CLIENT_A = 'r26-client-a';  // → a public project on the map
+const CLIENT_B = 'r26-client-b';  // → another public project on the map
+const CLIENT_C = 'r26-client-c';  // → a PRIVATE project
+const ORIGIN = { [CLIENT_A]: 'https://r26-a.example', [CLIENT_B]: 'https://r26-b.example', [CLIENT_C]: 'https://r26-c.example' };
+
+const q = (sql, params) => pool.query(sql, params);
+async function cleanup() {
+  await q(`DELETE FROM platform_identity_guilds WHERE slug LIKE 'r26-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_builder_project_activity WHERE github_id = ANY($1::bigint[])`, [ALL_IDS]).catch(() => {});
+  await q(`DELETE FROM platform_identity_projects WHERE origin LIKE 'https://r26-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_sso_clients WHERE client_id LIKE 'r26-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_accounts WHERE github_id = ANY($1::bigint[])`, [ALL_IDS]).catch(() => {});
+}
+
+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}`); };
+
+async function account(id, handle, { visibility = 'public', hide = false, state = 'active' } = {}) {
+  await q(
+    `INSERT INTO platform_identity_accounts
+       (github_id, github_login, handle, display_name, profile_state, terms_accepted_at, account_visibility, hide_stats)
+     VALUES ($1, $2, $2, $2, $3, CASE WHEN $3 = 'active' THEN now() END, $4, $5)`,
+    [id, handle, state, visibility, hide],
+  );
+}
+async function activity(id, client, credits, ships = 0, karma = 0) {
+  await q(
+    `INSERT INTO platform_identity_builder_project_activity (client_id, github_id, credits, tasks_shipped, karma)
+     VALUES ($1, $2, $3, $4, $5)`,
+    [client, id, credits, ships, karma],
+  );
+}
+async function guild(slug, visibility = 'public') {
+  const { rows } = await q(
+    `INSERT INTO platform_identity_guilds (slug, name, visibility) VALUES ($1, $1, $2) RETURNING id::text AS id`,
+    [slug, visibility],
+  );
+  return rows[0].id;
+}
+async function member(gid, id, { kind = 'member', shown = true, counted = true } = {}) {
+  await q(
+    `INSERT INTO platform_identity_guild_members (guild_id, github_id, membership_kind, shown_publicly, counted_in_totals)
+     VALUES ($1, $2, $3, $4, $5)`,
+    [gid, id, kind, shown, counted],
+  );
+}
+const sums = async (gid) => {
+  const [r] = await gt.computeGuildSums([gid], { pool });
+  return { credits: Number(r.credits), works_shipped: Number(r.works_shipped), karma: Number(r.karma), projects: Number(r.projects) };
+};
+const stored = async (gid) => (await q(
+  `SELECT credits, works_shipped, karma, projects, computed_at FROM platform_identity_guild_totals WHERE guild_id = $1`, [gid],
+)).rows[0] || null;
+const backdate = (gid, days) => q(
+  `UPDATE platform_identity_guild_totals SET computed_at = now() - make_interval(days => $2::int) WHERE guild_id = $1`, [gid, days],
+);
+// Only this file's guilds: a shared DB may hold other guilds the sweep would also pick.
+const refresh = () => gt.refreshStaleGuildTotals({ limit: 500 }, { pool });
+
+try {
+  // Every table the computation reads, all idempotent: accounts + consent, handle,
+  // privacy, terms; clients, projects, their visibility and the door stamp; the
+  // activity rollup; guilds; and this task's snapshot table.
+  for (const f of [
+    'platform_identity_001_tables.sql', 'platform_identity_004_projects.sql',
+    'platform_identity_005_builder_activity.sql', 'platform_identity_007_profile_consent.sql',
+    'platform_identity_008_handle.sql', 'platform_identity_011_project_visibility.sql',
+    'platform_identity_012_account_privacy.sql', 'platform_identity_019_terms_acceptance.sql',
+    'platform_identity_020_visibility_pull.sql', 'platform_identity_025_guilds.sql',
+    'platform_identity_027_guild_totals.sql',
+  ]) await q(migrationSql(f));
+  await q(migrationSql('platform_identity_027_guild_totals.sql')); // re-runnable
+  await cleanup();
+
+  await account(OWN, 'r26own');
+  await account(PUB, 'r26pub');
+  await account(HID1, 'r26hid1', { hide: true });
+  await account(HID2, 'r26hid2', { hide: true });
+  await account(HID3, 'r26hid3', { hide: true });
+  await account(PRIV, 'r26priv', { visibility: 'private' });
+  await account(UNSHOWN, 'r26unshown');
+  await account(OFF, 'r26off');
+  await account(PROV, 'r26prov', { state: 'provisional' });
+  await account(FAKE1, 'r26fake1', { visibility: 'private' });
+  await account(FAKE2, 'r26fake2', { visibility: 'private' });
+  await account(TARGET, 'r26target', { hide: true });
+
+  for (const c of [CLIENT_A, CLIENT_B, CLIENT_C]) {
+    await q(`INSERT INTO platform_identity_sso_clients (client_id, secret_hash, name, origin) VALUES ($1, 'x', $1, $2)`, [c, ORIGIN[c]]);
+  }
+  await q(
+    `INSERT INTO platform_identity_projects (origin, name, description, visibility, visibility_source)
+     VALUES ($1, 'A', 'a public project', 'public', 'control-plane'),
+            ($2, 'B', 'another public project', 'public', 'control-plane'),
+            ($3, 'C', 'a private project', 'private', 'control-plane')`,
+    [ORIGIN[CLIENT_A], ORIGIN[CLIENT_B], ORIGIN[CLIENT_C]],
+  );
+
+  await activity(OWN, CLIENT_A, 1, 1, 1);
+  await activity(OWN, CLIENT_C, 2, 1, 1);     // a public member on a private project
+  await activity(PUB, CLIENT_A, 4, 1, 1);     // shares project A with OWN
+  await activity(HID1, CLIENT_B, 8, 1, 1);    // the only builder on project B
+  await activity(HID2, CLIENT_A, 16, 1, 1);
+  await activity(HID3, CLIENT_A, 32, 1, 1);
+  await activity(PRIV, CLIENT_A, 64, 1, 1);
+  await activity(UNSHOWN, CLIENT_A, 128, 1, 1);
+  await activity(OFF, CLIENT_A, 256, 1, 1);
+  await activity(PROV, CLIENT_A, 512, 1, 1);
+
+  // --- 1. who is counted, and the k gate (ADR 0337 D4.4) --------------------
+  const g1 = await guild('r26-one');
+  await member(g1, OWN, { kind: 'owner' });
+  await member(g1, PUB);
+  await member(g1, HID1);
+  await member(g1, HID2);
+  await member(g1, OFF, { counted: false });
+  await member(g1, PROV);
+  same((await sums(g1)).credits, 1 + 2 + 4,
+    'two counted non-public members (< k) → the totals add up the public members alone; OFF and PROV never count');
+
+  await member(g1, HID3);
+  same((await sums(g1)).credits, 1 + 2 + 4 + 8 + 16 + 32,
+    'a third counted non-public member reaches k = 3 → every counted member\'s numbers enter');
+  same((await sums(g1)).works_shipped, 6, 'works shipped sums over the same members\' rows (OWN has two)');
+
+  const g2 = await guild('r26-two');
+  await member(g2, OWN, { kind: 'owner' });
+  await member(g2, PRIV);
+  await member(g2, UNSHOWN, { shown: false });
+  await member(g2, HID1);
+  same((await sums(g2)).credits, 1 + 2 + 64 + 128 + 8,
+    'a private account and a member not shown on the page are non-public too, and count toward k');
+  await q(`UPDATE platform_identity_guild_members SET counted_in_totals = false WHERE guild_id = $1 AND github_id = $2`, [g2, PRIV]);
+  same((await sums(g2)).credits, 1 + 2,
+    'one member switching off drops them AND can drop the guild below k, taking every non-public number out');
+
+  // --- 2. projects: public members, named public projects, distinct ---------
+  same((await sums(g1)).projects, 1,
+    'project A once (OWN and PUB share it); never private project C; never HID1\'s project B, even with k met');
+
+  // --- 3. the stored record: band floors only, and a read that only reads ----
+  same(await guilds.getPublicGuild('r26-one', { pool }).then((r) => r.totals), null,
+    'before the first refresh the public read carries no totals — and computes none');
+  same(await stored(g1), null, 'a public read wrote nothing');
+
+  await refresh();
+  const first = await stored(g1);
+  same({ credits: first.credits, works_shipped: first.works_shipped, karma: first.karma, projects: first.projects },
+    { credits: 50, works_shipped: 0, karma: 0, projects: 0 },
+    '63 credits is stored as its band floor 50; 6 works and 6 karma are under the first band (0)');
+  const pub = await guilds.getPublicGuild('r26-one', { pool });
+  same(pub.totals, { credits: 50, works_shipped: 0, karma: 0, projects: 0, as_of: first.computed_at },
+    'the public read publishes the stored band floors and when they were computed');
+  same(pub.size, 6,
+    'size stays the public roster\'s length: OWN, PUB, OFF and the three who hide their numbers (hide_stats hides numbers, never the name — ADR 0336 D4 §2); never PROV');
+
+  // --- 4. at most weekly -----------------------------------------------------
+  await activity(OWN, CLIENT_B, 1000);
+  for (let i = 0; i < 5; i++) await guilds.getPublicGuild('r26-one', { pool });
+  await refresh();
+  same((await stored(g1)).credits, 50,
+    'a change inside the week moves nothing: not five reads, not another sweep');
+
+  await backdate(g1, 6);
+  await refresh();
+  same((await stored(g1)).credits, 50, 'six days old is still inside the week');
+
+  await backdate(g1, 7);
+  const [a, b] = await Promise.all([refresh(), refresh()]);
+  same((await stored(g1)).credits, 1000, 'a week old → refreshed: 1063 credits is now the 1000 band');
+  const racedG1 = [a, b].filter((r) => r.refreshed > 0).length;
+  ok(racedG1 >= 1, 'at least one sweep refreshed the due guild');
+  const oneRow = await q(`SELECT count(*)::int AS n FROM platform_identity_guild_totals WHERE guild_id = $1`, [g1]);
+  same(oneRow.rows[0].n, 1, 'one row per guild');
+
+  // The upsert's own guard, without the pick step's help: a sweep that picked the
+  // guild while it was due, and lost the race to one that committed first, must
+  // update nothing. The wrapper plays the winning sweep between this one's pick
+  // and its write.
+  await backdate(g1, 7);
+  const losingPool = {
+    async query(text, params) {
+      const out = await pool.query(text, params);
+      if (/LEFT JOIN platform_identity_guild_totals t ON t\.guild_id = g\.id/.test(text)) {
+        await q(`UPDATE platform_identity_guild_totals SET credits = 20, computed_at = now() WHERE guild_id = $1`, [g1]);
+      }
+      return out;
+    },
+  };
+  await gt.refreshStaleGuildTotals({ limit: 500 }, { pool: losingPool });
+  same((await stored(g1)).credits, 20,
+    'the age check lives in the write: the losing sweep leaves the winner\'s record alone');
+
+  // --- 5. unlisted, and dissolve --------------------------------------------
+  const g3 = await guild('r26-quiet', 'unlisted');
+  await member(g3, OWN, { kind: 'owner', shown: false });
+  await refresh();
+  ok(!!(await stored(g3)), 'an unlisted guild has a record too (ready for a flip to public)…');
+  same(await guilds.getPublicGuild('r26-quiet', { pool }), null, '…but no public read reaches it');
+  await q(`DELETE FROM platform_identity_guilds WHERE id = $1`, [g3]);
+  same(await stored(g3), null, 'dissolving a guild takes its record with it (FK cascade)');
+
+  // --- 6. the honest limit, DOCUMENTED, not fixed (ADR 0337 D4.4) -----------
+  // A guild owner who pads with two accounts whose numbers they already know
+  // makes a real non-public member the third, and the total then carries that
+  // member. Accepted by the owner on 2026-09-25: the notice on the join card and
+  // the per-guild switch are the defence, not this computation. If this block
+  // ever goes red because the padding stopped working, the rule changed — update
+  // ADR 0337 D4.4 before this test.
+  await activity(TARGET, CLIENT_A, 777);
+  const own = 1 + 2 + 1000; // OWN's three rows, after section 4's report
+  const pad = await guild('r26-pad');
+  await member(pad, OWN, { kind: 'owner' });
+  await member(pad, FAKE1);
+  await member(pad, FAKE2);
+  same((await sums(pad)).credits, own, 'the two fakes alone are below k');
+  await member(pad, TARGET);
+  same((await sums(pad)).credits, own + 777,
+    'PADDING WORKS (accepted): the target becomes the third non-public member and enters the sum');
+  await q(`UPDATE platform_identity_guild_members SET counted_in_totals = false WHERE guild_id = $1 AND github_id = $2`, [pad, TARGET]);
+  same((await sums(pad)).credits, own, 'the target\'s answer is the switch: off, and they are out');
+
+  // --- 7. karma below zero stays inside the column's floor ------------------
+  const neg = await guild('r26-neg');
+  await member(neg, PUB, { kind: 'owner' });
+  await q(`UPDATE platform_identity_builder_project_activity SET karma = -40 WHERE github_id = $1`, [PUB]);
+  await refresh();
+  same((await stored(neg)).karma, 0, 'a negative sum publishes as 0, never below the CHECK');
+
+  console.log(`\nguild_totals_db.mjs: ${pass} passed`);
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/guilds_api.mjs

@@ -263,8 +263,13 @@ test('public read: the roster is shown_publicly AND the shared existence predica
   });
   const res = await call('GET', '/api/bongos/guilds/Guild-A');
   assert.equal(res.status, 200);
-  assert.deepEqual(Object.keys(res.json).sort(), ['guild', 'members', 'size']);
+  assert.deepEqual(Object.keys(res.json).sort(), ['guild', 'members', 'size', 'totals']);
   assert.equal(res.json.size, 2);
+  assert.equal(res.json.totals, null, 'no stored record yet → no totals, never a computed stand-in');
+  assert.ok(calls.some((c) => /FROM platform_identity_guild_totals\s+WHERE guild_id = \$1/.test(c.text)),
+    'the totals are READ from the weekly snapshot');
+  assert.ok(calls.every((c) => !/INSERT|UPDATE|platform_identity_builder_project_activity/.test(c.text)),
+    'the public read never computes or writes the totals (ADR 0337 D4.4: never on a read)');
   assert.equal(res.json.members.length, 2);
   assert.ok(!('id' in res.json.guild), 'the row id stays internal');
   assert.ok(!/github_id|github_login/.test(res.text), 'no account id or login crosses');