@bongos/core 1.20.18 → 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.18",
-  "core_contract": "1.20.18",
-  "source_commit": "e1841ec9f7044de186bb75988136b6dfb0835ef7",
+  "core_version": "1.20.20",
+  "core_contract": "1.20.20",
+  "source_commit": "81de3611c8c98f0a428be1780f94435846cd7bf2",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T13:46:50.940Z",
+  "built_at": "2026-09-30T14:55:04.182Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 556,
+    "docs_redacted": 557,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2628,
+    "functional_verbatim": 2636,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3210,
-  "tree_sha256": "34fda46e51438cef84700eb352c0f4dc3a8552cd8e8fc962864f4f500e09047d",
+  "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",
@@ -2229,10 +2229,15 @@
       "mode": "0000644",
       "sha256": "4ca4eae961c994cae0dd9d306ea0a5a6f9ce660de161a62c5ccd125d910f70ec"
     },
+    {
+      "path": "docs/adr/0352-a-rollup-report-carries-its-as-of-in-a-header.md",
+      "mode": "0000644",
+      "sha256": "d74b4f6262d4f23fd67f73771bbe8187e9cb92fa321b83ffb33ef03cf96d1236"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "bcfa8004aeaebbfb6c32c53042665d7da49098e80dd858a3f353420f8ef2c523"
+      "sha256": "943ac0f8c9c0b2dc5ef2a05241b0bac329c5fa986b09425841e12e62f4f9b936"
     },
     {
       "path": "docs/api-reference.md",
@@ -2242,7 +2247,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "829ba538e06cca081f0540bf819f280ba36e738a553e5fa3634af5f5af5bc5b0"
+      "sha256": "4167b07fddd64f47f901082e130a12f307e4e2fab5ac9bc821e24a0c4f6f3d72"
     },
     {
       "path": "docs/architecture.md",
@@ -2772,7 +2777,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "99307d7bab261c46f7e80d768b014352d9f3c47ec2c72088acfac7bc700dd06f"
+      "sha256": "2b82bf65da0987ffc862ad6369e0cbcf8e6adef0a70915cf7a7a2c2289a69c85"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6859,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",
@@ -7009,10 +7019,20 @@
       "mode": "0000644",
       "sha256": "72be4f7e3aa3afa47dd78de7a57dcdf57b877675b44fbdf02f6607a8632e1787"
     },
+    {
+      "path": "modules/platform-identity/migrations/platform_identity_026_activity_reported_as_of.sql",
+      "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",
@@ -7022,13 +7042,18 @@
     {
       "path": "modules/platform-identity/platform-identity.js",
       "mode": "0000644",
-      "sha256": "badb8e19541a08a35f85037bc9f5130c553403ae75017423354d255f972cbe46"
+      "sha256": "a823bd5e79795f93aa011470088b5840bf2ada6fb696fbf6b9b1c6c2ea85e5ef"
     },
     {
       "path": "modules/platform-identity/pollers/code-sweep.js",
       "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",
@@ -7082,7 +7107,7 @@
     {
       "path": "modules/platform-identity/routes/guilds-public.js",
       "mode": "0000644",
-      "sha256": "1a8d2d70d4b9f5e4cfc93bd1f6d83911ab625463866527838d74944162f978de"
+      "sha256": "b6029f6f9d40fec18e42c0eaba75779ad7baa0c29df47bb7fe248a83cb783396"
     },
     {
       "path": "modules/platform-identity/routes/guilds.js",
@@ -7117,7 +7142,7 @@
     {
       "path": "modules/platform-identity/routes/sso.js",
       "mode": "0000644",
-      "sha256": "aa1bceddd27140e33d12f1c22ca362ba35352d837b556422b54633fd4fcedfc0"
+      "sha256": "2906d873fa46a2745fbbecefdeb81194f6f433e97deed65ee5fbee3e9a7fa140"
     },
     {
       "path": "modules/platform-identity/scouting-authz.js",
@@ -7142,7 +7167,7 @@
     {
       "path": "modules/platform-identity/tests/platform-identity.mjs",
       "mode": "0000644",
-      "sha256": "788915622457990f61b7b95cc6266d1e285097100100be06419145702191c9ce"
+      "sha256": "93d74c10d601eab840da83b5d33d7bbf51907830626401cc27fadb138441fcc3"
     },
     {
       "path": "modules/platform-identity/ui/.gitkeep",
@@ -8862,12 +8887,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "35d3b7a5f69caee9c6a98b7c34c02daec4289cd0548637d05ff41fd23d1926c4"
+      "sha256": "830a8f9950a12b57c520a79198562f423818f1f1a98095d7122ddf4a6100f052"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9807202c95ba59b5f8104eb0c6701241d989800e67fdddf8252bc569b9a74c96"
+      "sha256": "3b0d575917863d61bca84ddc2ce68886c33bc0d4fae9825a7abb8e2a5da7eec8"
     },
     {
       "path": "public-docs/index.html",
@@ -8887,7 +8912,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "19b0f5588a02e7517cc25668a59df836f8ee1a183e1f1ec4a2b63d79214b3808"
+      "sha256": "47fee7ce9947c485d183f574d1564c43da3329822ffd470897609631fe95effc"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10047,7 +10072,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "55ffec8533dc352849c2a9bb40663a1a0c95d72d466360bf47091e9491683b0b"
+      "sha256": "b4b2358efdc538a35472258f5c0812bc3990e179612f663810cdcde6f1e0b143"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -10667,7 +10692,7 @@
     {
       "path": "src/bongos/auth-admission.js",
       "mode": "0000644",
-      "sha256": "2d11e7b745a0476fa0643fd997c2e17a49709bae1ef93a7c4636f7efd18c7ab0"
+      "sha256": "9fd9311df751a418985073db3aed97825e52d2a45ca7501b93f93cf5019c1fe6"
     },
     {
       "path": "src/bongos/auth-config.js",
@@ -11002,7 +11027,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "3f49c56de113748d04529b5028e1ac2fca037cf00c1d6be6e531346dcfbea552"
+      "sha256": "091a4bde841eaad09639727d4691f0c8a5555926e33cbffc49c7acc6b95870a6"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11104,10 +11129,20 @@
       "mode": "0000644",
       "sha256": "f7434d510d656e5081f735d1f9356ecb11e8c3630a86a86137c3290134541c8d"
     },
+    {
+      "path": "tests/activity_rollup_as_of.mjs",
+      "mode": "0000644",
+      "sha256": "d5903404f0fed48e599b68f259e0d79a44d11c249bb69bc4b59643e7dac62cbb"
+    },
+    {
+      "path": "tests/activity_rollup_order_db.mjs",
+      "mode": "0000644",
+      "sha256": "497b453aa441ba06276d5146fc71f54da111a12c7c0c2e192da199cc1f2812ec"
+    },
     {
       "path": "tests/activity_snapshots_db.mjs",
       "mode": "0000644",
-      "sha256": "219569f3160eb22a89e92a217b854a194afba6ebc7032dc07eff2534efc4390a"
+      "sha256": "73cb5a43e3f3ce61dd7f57720e523a310390ed60ed491d39fdaf8b8e9c78053a"
     },
     {
       "path": "tests/admission_ceiling_gate.mjs",
@@ -13044,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",
@@ -14347,7 +14392,7 @@
     {
       "path": "tests/profile_rollup_consent.mjs",
       "mode": "0000644",
-      "sha256": "986cd6a9aa83743f5d2bc6083803e6ed576f6b7b35a8c6dc05e9096fa022f898"
+      "sha256": "093f078f965454e535d6026c1852a0e0668695809f270f84e5d26dba4025abbd"
     },
     {
       "path": "tests/profile_route.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/adr/0352-a-rollup-report-carries-its-as-of-in-a-header.md

@@ -0,0 +1,38 @@
+# ADR 0352 — A rollup report carries its "as of" in a header, and the hub keeps the newest
+
+- **Status:** accepted
+- **Date:** 2026-09-30
+- **Task:** [task 1004268](https://cloudbongos.com/builders#/task/1004268) (goal 1000110), found in [task 1004244](https://cloudbongos.com/builders#/task/1004244)'s code review
+- **Interacts with:** [ADR 0141](<redacted>.md) §4 (the activity rollup), [ADR 0171](0171-profile-rollup-join-and-consent.md) D7 (a report is third-party self-report), [ADR 0083](0083-modular-architecture-strangler-build-plan.md) §5 (module-namespaced migrations)
+
+## Context
+
+`POST /sso/activity/rollup` upserted the live activity row last-writer-wins, and a report carried no timestamp. An instance pushes one on every federated sign-in and one on every ship, so a sign-in report read earlier and a ship report read later can reach the hub together, and the older one can commit last. The live row and, since task 1004244, the newest snapshot then show the older totals. The leaderboard reads a regression that never happened until the builder's next report. It is low-urgency, since the next report corrects it, but it is wrong in exactly the place people compare numbers.
+
+The fix the task names is for the instance to send when it read the totals, and for the hub to refuse an older report. What is not obvious is where that stamp travels.
+
+## Decision
+
+**D1 — The stamp is a request header, `Bongos-Report-As-Of`, not a body field.** The hub validates the rollup body strictly (`validateOrRespond`), so an unknown field is a 400. The hub and its instances upgrade independently, and an instance can run a newer core than the hub (today the hub's pin trails main). A body field sent by an upgraded instance would be refused by a hub that predates it. The sender never reads the response, so every report from that instance would be lost silently until the hub caught up. An unknown header is ignored, so the header is safe in both directions: an old hub ignores it, and a new hub treats its absence as "unstamped".
+
+**D2 — Unstamped means the old behaviour, never a refusal.** A missing or unparseable header binds NULL. A NULL on either side of the comparison (an older instance's report, or a row written before migration 026) applies last-writer-wins, as before. An unstamped report also clears the stored stamp, so a stamp never outlives the numbers it described. A malformed header is not a 400, for D1's reason: a refusal drops the report, when the only thing lost should be its ordering.
+
+**D3 — The guard is a WHERE on the upsert's conflict branch.** `ON CONFLICT (client_id, github_id) DO UPDATE … WHERE EXCLUDED.reported_as_of IS NULL OR <row>.reported_as_of IS NULL OR EXCLUDED.reported_as_of >= <row>.reported_as_of`. A skipped update still takes the row lock, so racing reports stay queued exactly as task 1004244 arranged, and the snapshot beside it copies an unchanged live row, which records nothing. Ties apply (the later arrival wins, as before).
+
+**D4 — The stamp is the instance's clock, compared only with itself, and clamped to the hub's.** A row's stored stamp only ever comes from the same client for the same builder, so skew between an instance and the hub does not matter. A stamp later than the hub's `now()` is stored as `now()`, so an instance whose clock runs ahead cannot freeze the row until its clock is reached. The sender stamps before its first read, so a report is never ordered ahead of totals read after it.
+
+## Consequences
+
+- Migration `platform_identity_026_activity_reported_as_of.sql` adds one nullable column, with no backfill and no default. An invented stamp on an existing row could refuse an honest report from an instance whose clock reads earlier than the hub's.
+- A mixed fleet behaves as before until each instance upgrades. An upgraded instance talking to an old hub is also unaffected.
+- **Honest limit:** an instance clock that steps backwards (an NTP correction after running fast) has its reports refused until it passes the last stamp it sent. The skew bounds this, the clamp bounds the skew by the hub's own time, and the next report after that applies. A report refused this way still answers `{ ok: true }`, because the instance ignores the body.
+- **The pattern generalises:** a field added to a hub↔instance wire that the older side validates strictly must be able to ride where the older side ignores it, or the change must land on the hub first and be released before any instance sends it.
+
+Proof: `tests/activity_rollup_order_db.mjs` (real Postgres: the out-of-order race, ties, NULLs on each side, the future clamp, and ten rounds of five racing writers ending on the latest stamp with the snapshot agreeing) and `tests/activity_rollup_as_of.mjs` (DB-free: the sender stamps a header before its reads and never the body; the route binds it and degrades a bad one to unstamped).
+
+## Alternatives considered
+
+- **A body field `as_of`.** This is what the task sketched. It is lost against any older hub (D1).
+- **`GREATEST` on each total.** Credits and karma can legitimately fall, so this would pin a clawback forever.
+- **The standard `Date` header.** It has one-second granularity, and a sign-in push and a ship push inside the same second are exactly the case being fixed.
+- **A 400 on a malformed stamp.** It turns a sender bug into silent data loss (D2).

package/docs/adr/README.md

@@ -470,3 +470,4 @@ These 20 numbers are each shared by exactly two files. They are **accepted histo
 | 0349 | [**A version preview is a sandboxed child the web tier launches, reached by a cookie** ([task 1004300](https://cloudbongos.com/builders#/task/1004300), goal 1000090 — BONGOS-V2, owner Lars, approved 2026-09-29). Amends ADR 0293 D1 for this feature only. **D1 (owner):** route by a `bongos_preview` cookie through an optional `request.divert` seam, not a path; forward only with the cookie, off the sign-in and preview paths, with no Bearer, and with `core.pin.move` re-checked on every request. **D2 (owner):** the npm-release module launches the preview itself, with a deny-by-default environment, a dump-and-restore copy of the database (never a template copy), one at a time, 20-minute idle stop, published versions within 30 of the running one. **D3:** the same database role and no egress firewall are accepted for now.](0349-a-version-preview-is-a-sandboxed-child-the-web-tier-launches.md) | modules / npm-release / deploy |
 | 0350 | [**The hub holds a per-project WRITE deploy key, so a hosted project's upgraded pin always reaches its GitHub repo** ([task 1004291](https://cloudbongos.com/builders#/task/1004291), follow-up to task 1004065). Amends ADR 0176. The owner's token lasts one hour and the checkout's own key is read-only, so most hosted upgrades ended "GitHub was not updated". **D1:** a second deploy key per repo, registered `read_only: false` as `cloudbongos-pin-<slug>`, the pull key untouched. **D2:** kept outside every checkout in the runner's own directory (0700 dir, 0600 key, modes verified), unreadable by the project's account. **D3:** minted at standup and whenever a fresh owner token finds none, so reconnecting GitHub once is enough. **D4:** `pushUpgradePin` tries write key, then owner token, then origin, never forced. **D5:** revoked on teardown and disconnect. **D6:** a project on the shared app user is refused a key: "needs its own account first". **D7:** /deploy says reconnecting sets up lasting access.](0350-the-hub-holds-a-per-project-write-deploy-key-so-a-hosted-upgrade-reaches-github.md) | provisioning / security |
 | 0351 | [**A criterion closes on a UAT, not on its linked tasks shipping** ([task 1004392](https://cloudbongos.com/builders#/task/1004392), goal 1000089 — working area 3). Supersedes ADR 0183's close rule. `wa7-government` had closed on six Board Room navigation tasks while nothing it describes was on the live site. **D1:** three checks — Code (linked tasks done, ≥1 shipped; automatic), Live, UAT — and the sweep closes a criterion only with a CURRENT sign-off (no older than the newest linked ship). **D2 (owner):** "Awaiting UAT" is a visible state. **D3 (owner):** one step; the signer is refused if they shipped linked work, the project owner excepted. **D4 (owner):** an mp4/webm up to 100 MB on the project's own server. **D5 (owner):** backend-only is set while a criterion is open and takes a recording-free sign-off. **D6 (owner):** Live is read via the `deploy.taskWhere` port where the site can tell, attested otherwise. **D7 (owner):** already-closed criteria stay closed ("Closed before UAT"). **D8:** `/satisfy` is a recorded override that needs a reason. **D9:** `/goal-uat` + `scripts/gds/uat.js`; the hall is task 1004402.](0351-a-criterion-closes-on-a-uat.md) | lifecycle / criteria / review |
+| 0352 | [**A rollup report carries its "as of" in a header, and the hub keeps the newest** ([task 1004268](https://cloudbongos.com/builders#/task/1004268), goal 1000110). `POST /sso/activity/rollup` was last-writer-wins with no report timestamp, so a sign-in push read earlier and a ship push read later could land the older totals last. **D1:** the instance's read time rides a `Bongos-Report-As-Of` HEADER, not a body field, because the hub validates the body strictly and hub and instances upgrade independently: a body field from a newer instance would 400 on an older hub and lose the report, while an unknown header is ignored. **D2:** missing or unparseable = unstamped = last-writer-wins, never a 400. **D3:** the guard is a WHERE on the upsert's conflict branch (migration 026, `reported_as_of`, no backfill); a skipped update keeps the row lock, so the task 1004244 snapshot stays in step. **D4:** the stamp is compared only with the same client's, and clamped to the hub's `now()`.](0352-a-rollup-report-carries-its-as-of-in-a-header.md) | platform identity / federation |

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": [
@@ -18502,7 +18502,7 @@
           "sso"
         ],
         "summary": "POST /sso/activity/rollup",
-        "description": "POST /sso/activity/rollup — a federated instance reports a builder's activity snapshot (ADR 0141 §4). Server-to-server, client_id+client_secret auth. Keyed to the AUTHENTICATED client_id. Descriptive analytics for the Archon-only scouting view — never authority. rank: public — authenticated by client_id + client_secret, not a builder rank.\n\n**Rank:** `public` — No authentication — any caller.",
+        "description": "POST /sso/activity/rollup — a federated instance reports a builder's activity snapshot (ADR 0141 §4). Server-to-server, client_id+client_secret auth. Keyed to the AUTHENTICATED client_id. Descriptive analytics for the Archon-only scouting view — never authority. Optional `Bongos-Report-As-Of` header (task 1004268): when the instance read these totals, so an older report landing last cannot overwrite a newer one. A HEADER, not a body field, because the body is validated strictly and the hub and its instances upgrade independently: a new instance's body field would 400 on an older hub and the report would be lost, while an unknown header is ignored. Absent or unparseable reads as unstamped (last-writer-wins, as before) rather than a 400 — the sender never reads the response, so a refusal would silently drop the report instead of only its ordering. rank: public — authenticated by client_id + client_secret, not a builder rank.\n\n**Rank:** `public` — No authentication — any caller.",
         "x-rank": "public",
         "x-source": "modules/platform-identity/routes/sso.js",
         "requestBody": {
@@ -22586,12 +22586,14 @@
         "properties": {
           "guild": {},
           "members": {},
-          "size": {}
+          "size": {},
+          "totals": {}
         },
         "required": [
           "guild",
           "members",
-          "size"
+          "size",
+          "totals"
         ]
       },
       "GetHealthzResponse": {

package/docs/module-api-changelog.md

@@ -2693,5 +2693,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.20.16 with no explicit bump. run 36722139698. (task 1002620)
   1.20.18 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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 = {