@bongos/core 1.20.20 → 1.20.21

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.20.20",
-  "core_contract": "1.20.20",
-  "source_commit": "81de3611c8c98f0a428be1780f94435846cd7bf2",
+  "core_version": "1.20.21",
+  "core_contract": "1.20.21",
+  "source_commit": "21843bf1398d569536fc45f748fae3c195be4ba2",
   "source_ref": "HEAD",
-  "built_at": "2026-09-30T14:55:04.182Z",
+  "built_at": "2026-09-30T15:20:08.598Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 557,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2636,
+    "functional_verbatim": 2638,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3219,
-  "tree_sha256": "9d08157c7a131c0010616436de1c1b4b0ecd19030def84afd3ed402813e39499",
+  "file_count": 3221,
+  "tree_sha256": "07ce496b1770bfc67bcd98bdf44e2bc6a47d1f869682f5fba2db1ded196d0b07",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -327,12 +327,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "e02ae1f840ce2b9ba26906d22a71251f99093c1be99b7585d8d5492de6828247"
+      "sha256": "680d37464fa929b11cd7a02af6aa4fb144bedcde5134c3d81edac167d7b95980"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "d2eddb6398add51948e7facc2b3752a4bc9c2a1c5826cdade034328529389dd2"
+      "sha256": "c6dac0dab2b2d5fb996568cff8ead84e7f6ac9e036c3fab6a47893c79a99f8f4"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -342,17 +342,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "aef980f7c979cf57ce9cba684e370301f0343e3e72a4ce9076875fa0efd4287e"
+      "sha256": "baa7c833c3d18bf8250590fd94c499b3032ba05c6b9aa0af36b4660da295c799"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "d9b3edd04125960791f6282252f5f31b2ace6abb90beeb19c483af1a422fbf53"
+      "sha256": "e9b2837873e241f20472ebde570b550718365a663282d4a85c255d98a8c8e21c"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "b99063352bcd42be68be647d30b838fdedcb0aef3c39a2b7a7849e9f80208fdd"
+      "sha256": "79240ff449f616e50aca58fc310a3b0670af84dc30d7a93991d84c0d0f4b87d2"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -2242,12 +2242,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "73b9c0372c8d6ddf88b0eec04695defbc219a826b8be9da71a24b5a1eb6ff060"
+      "sha256": "36a01165649c2ca2f1e29c592332efe08f3cffcd926a547e8de4121ca05c0469"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "4167b07fddd64f47f901082e130a12f307e4e2fab5ac9bc821e24a0c4f6f3d72"
+      "sha256": "37b9cfbb4cce621c7ba60d358a66b618d60f6706b4b1c2dec7215c88451cff1c"
     },
     {
       "path": "docs/architecture.md",
@@ -2777,7 +2777,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "2b82bf65da0987ffc862ad6369e0cbcf8e6adef0a70915cf7a7a2c2289a69c85"
+      "sha256": "5be7dcf0c4dbcd61706bbaf8fec0edc509d32b721b7be1abae250dcff896f95e"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6864,6 +6864,11 @@
       "mode": "0000644",
       "sha256": "793e96feacef39ec52166dd7372c894a25679c7137c9c3c5e9df38ec323f1c4a"
     },
+    {
+      "path": "modules/platform-identity/guild-map.js",
+      "mode": "0000644",
+      "sha256": "f550b6f42ef3e37c4390a1629d4c5f109285a130d2b5efd4ccbefa57acfe2cf1"
+    },
     {
       "path": "modules/platform-identity/guild-totals.js",
       "mode": "0000644",
@@ -7107,7 +7112,7 @@
     {
       "path": "modules/platform-identity/routes/guilds-public.js",
       "mode": "0000644",
-      "sha256": "b6029f6f9d40fec18e42c0eaba75779ad7baa0c29df47bb7fe248a83cb783396"
+      "sha256": "3217ae9aa5d952b72711a4e723bec3c93b4b5d12975f056bb74e8e9f4ff5e7e3"
     },
     {
       "path": "modules/platform-identity/routes/guilds.js",
@@ -8887,12 +8892,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "830a8f9950a12b57c520a79198562f423818f1f1a98095d7122ddf4a6100f052"
+      "sha256": "7ca4dcc58b8138d0f20002590f565c03952db6a97c8a740c09307c91b24872bf"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "3b0d575917863d61bca84ddc2ce68886c33bc0d4fae9825a7abb8e2a5da7eec8"
+      "sha256": "fc858fcc7b0fef1d6850cca8b5d5825250568cb16754f3452dc5a5d8f42545d5"
     },
     {
       "path": "public-docs/index.html",
@@ -8912,7 +8917,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "47fee7ce9947c485d183f574d1564c43da3329822ffd470897609631fe95effc"
+      "sha256": "1739d308859639e1ff64b6716cd4e04f117c094868c1ad8ad1f1fa1272232221"
     },
     {
       "path": "scripts/bongos-mcp.js",
@@ -10072,7 +10077,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "b4b2358efdc538a35472258f5c0812bc3990e179612f663810cdcde6f1e0b143"
+      "sha256": "8a7b0e6b5d899bc2706d952d2383ee5b45758810b7f7d5bd5b7ebc2fc547e43e"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -11027,7 +11032,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "091a4bde841eaad09639727d4691f0c8a5555926e33cbffc49c7acc6b95870a6"
+      "sha256": "7e01ad4572ca48ef4dba7c5776246f2e7ba1a251a1bc079f1ae0566b9dc67593"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13074,6 +13079,11 @@
       "mode": "0000644",
       "sha256": "6e834f3cf75dd34ba30795c46bc401098053a56c967da8661128f34db71ff8c3"
     },
+    {
+      "path": "tests/guild_map_db.mjs",
+      "mode": "0000644",
+      "sha256": "cc230b6df32f9f7ab7c81d0cca88af6d0ace233c800a4d29d43cd474d0deefa1"
+    },
     {
       "path": "tests/guild_namespace_reserved.mjs",
       "mode": "0000644",
@@ -13092,7 +13102,7 @@
     {
       "path": "tests/guilds_api.mjs",
       "mode": "0000644",
-      "sha256": "2476ef4a332fa6d82d9d40ca798012c5aef40a74b08c5ca8d8d40e1975223cbb"
+      "sha256": "ae92262fb5fa1a79b1540538e7b9191ae47d19c3b4ae3572d07d470159f4ef91"
     },
     {
       "path": "tests/guilds_db.mjs",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 461 operations across 70 resource groups
+- 462 operations across 70 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -499,6 +499,8 @@ function createClient(opts = {}) {
       postGuildRequestsIdDecline: (args) => request("POST", "/guild-requests/{id}/decline", { hasBody: true }, args),
     },
     "guilds": {
+      // GET /guilds — rank: public — GET /guilds
+      getGuilds: (args) => request("GET", "/guilds", { hasBody: false }, args),
       // POST /guilds — rank: any-builder — POST /guilds
       postGuilds: (args) => request("POST", "/guilds", { hasBody: true }, args),
       // DELETE /guilds/{slug} — rank: any-builder — DELETE /guilds/:slug

package/clients/bongos-client/index.cjs

@@ -498,6 +498,8 @@ function createClient(opts = {}) {
       postGuildRequestsIdDecline: (args) => request("POST", "/guild-requests/{id}/decline", { hasBody: true }, args),
     },
     "guilds": {
+      // GET /guilds — rank: public — GET /guilds
+      getGuilds: (args) => request("GET", "/guilds", { hasBody: false }, args),
       // POST /guilds — rank: any-builder — POST /guilds
       postGuilds: (args) => request("POST", "/guilds", { hasBody: true }, args),
       // DELETE /guilds/{slug} — rank: any-builder — DELETE /guilds/:slug

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

@@ -72,6 +72,7 @@ export interface GetGovernmentAssignmentsResponse { assignments: unknown }
 export interface GetGovernmentPermissionsResponse { permissions: unknown; principals: unknown }
 export interface GetGovernmentRanksResponse { ranks: unknown }
 export interface GetGradesByBuilderResponse { window_days: unknown; builders: unknown }
+export interface GetGuildsResponse { order: unknown; count: unknown; results: unknown; page: 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; totals: unknown }
@@ -925,6 +926,8 @@ export interface BongosClient {
     postGuildRequestsIdDecline(args?: RequestArgs): Promise<ApiResponse>;
   };
   "guilds": {
+    /** GET /guilds — rank: public */
+    getGuilds(args?: RequestArgs): Promise<GetGuildsResponse>;
     /** POST /guilds — rank: any-builder */
     postGuilds(args: RequestArgs & { body: PostGuildsRequest }): Promise<PostGuildsResponse>;
     /** DELETE /guilds/{slug} — rank: any-builder */

package/clients/bongos-client/index.mjs

@@ -495,6 +495,8 @@ export function createClient(opts = {}) {
       postGuildRequestsIdDecline: (args) => request("POST", "/guild-requests/{id}/decline", { hasBody: true }, args),
     },
     "guilds": {
+      // GET /guilds — rank: public — GET /guilds
+      getGuilds: (args) => request("GET", "/guilds", { hasBody: false }, args),
       // POST /guilds — rank: any-builder — POST /guilds
       postGuilds: (args) => request("POST", "/guilds", { hasBody: true }, args),
       // DELETE /guilds/{slug} — rank: any-builder — DELETE /guilds/:slug

package/docs/api/openapi.json

@@ -8590,6 +8590,32 @@
       }
     },
     "/guilds": {
+      "get": {
+        "operationId": "get_guilds",
+        "tags": [
+          "guilds"
+        ],
+        "summary": "GET /guilds",
+        "description": "the guild map (?order=size|shipped, default size; ?limit=&offset=). Viewer-independent: it reads no session. size is the public roster's length; shipped is R26's stored band floor (ADR 0337 D4.4), never an exact sum, null before a guild's first refresh. no-store: a hide or a visibility flip moves size on the very next read (ADR 0171 D5).\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/platform-identity/routes/guilds-public.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetGuildsResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      },
       "post": {
         "operationId": "post_guilds",
         "tags": [
@@ -22551,6 +22577,21 @@
           "builders"
         ]
       },
+      "GetGuildsResponse": {
+        "type": "object",
+        "properties": {
+          "order": {},
+          "count": {},
+          "results": {},
+          "page": {}
+        },
+        "required": [
+          "order",
+          "count",
+          "results",
+          "page"
+        ]
+      },
       "GetGuildsSlugMembersResponse": {
         "type": "object",
         "properties": {
@@ -29523,9 +29564,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 461,
-  "x-schema-count": 493,
+  "x-endpoint-count": 462,
+  "x-schema-count": 494,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 335,
+  "x-response-schemas": 336,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 461 endpoints across 82 route files.
+> **Generated from the live route files** — the route file is authoritative. 462 endpoints across 82 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -342,10 +342,11 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/guild-requests/:id/accept` | `any-builder` | `visibility`, `counted_in_totals` | accept an invite addressed to ME, or (as the guild's owner) a request to join it. |
 | POST | `/api/bongos/guild-requests/:id/decline` | `any-builder` | — | decline an invite to ME, or (as owner) a request to my guild. |
 
-## `guilds` (12)
+## `guilds` (13)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/guilds` | `public` | — | the guild map (?order=size\|shipped, default size; ?limit=&offset=). |
 | POST | `/api/bongos/guilds` | `any-builder` | `slug`, `name`, `description`, `visibility` | create a guild. |
 | GET | `/api/bongos/guilds/:slug` | `public` | — | a public guild's page data. |
 | PATCH | `/api/bongos/guilds/:slug` | `any-builder` | `name`, `description`, `visibility` | owner: edit name, description or visibility. |

package/docs/module-api-changelog.md

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

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

@@ -0,0 +1,105 @@
+// modules/platform-identity/guild-map.js — the guild map's data: public guilds,
+// ranked (R30, task 1002306; ADR 0336 D8, amended by ADR 0337 D4.4).
+//
+// WHO. `visibility = 'public'` AND a non-empty public roster. An unlisted guild
+// has no public existence (ADR 0336 D4), so it is never listed. Neither is a
+// public guild whose every member is private or unshown: it would be a name on
+// the map with nobody behind it.
+//
+// TWO ORDERINGS, NO STORED SCORE (D8):
+//   * size    — the public roster's length, computed exactly as getPublicGuild
+//               computes it (shown_publicly AND accountVisibleSql, capped at
+//               guilds.LIST_MAX), so the map and the guild page never disagree.
+//               hide_stats hides numbers, never membership (ADR 0336 D4 §2), so a
+//               member who hides their numbers is still in it; a private one never.
+//   * shipped — the guild's STORED works_shipped band floor (guild-totals.js),
+//               never an exact sum (D4.4). A guild not yet refreshed publishes
+//               null and sorts last.
+// Ties break on slug. Every sort key is a field the row publishes (ADR 0255: a
+// public list's order is a covert column otherwise).
+//
+// COST, AND WHY THERE IS NO CACHE. One aggregate per read, over PUBLIC guilds'
+// memberships only (the roster CTE filters on visibility before it groups, so an
+// unlisted guild's members are never counted, let alone scanned for the map) —
+// at the hub's scale a few index scans, bounded per caller by guild-map-read.
+// D8 decides "computed at read time" and names the revisit trigger: a measured
+// p95. It also rules out the cheap cache: any cache must be INVALIDATED by a hide,
+// a privacy flip, a shown_publicly change, a membership change and a visibility
+// change, because a TTL alone keeps publishing a withdrawn member in a guild's
+// size (the ADR 0202 D3 reason). community-leaderboard.js's 30s memo does not
+// transfer: it caches only NUMBERS and re-reads WHO on every request, and here
+// the expensive half IS who — the roster under the privacy predicates. A cache
+// is therefore a write-path change across guilds.js, the privacy setters and
+// consent, taken when the p95 says so, not a TTL bolted on here.
+//
+// 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 { accountVisibleSql } = require('./account-visibility');
+const { LIST_MAX } = require('./guilds');
+const { clampOffset, MAX_OFFSET } = require('./builder-search');
+
+const { pool: defaultPool } = api;
+
+const DEFAULT_LIMIT = 25;
+const MAX_LIMIT = 100;
+
+// The orderings, as fixed SQL. A request names a key; it never supplies SQL.
+const ORDERS = {
+  size: 'size DESC, g.slug',
+  shipped: 'shipped DESC NULLS LAST, g.slug',
+};
+const ORDER_KEYS = Object.keys(ORDERS);
+const DEFAULT_ORDER = 'size';
+
+function isOrder(order) {
+  return typeof order === 'string' && Object.prototype.hasOwnProperty.call(ORDERS, order);
+}
+
+function clampLimit(limit) {
+  const n = parseInt(limit, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+// One page of the map. `order` must already be valid (the route 400s first; an
+// invalid one here falls back to the default rather than reaching SQL). Returns
+// { order, results: [{ slug, name, size, shipped }], limit, offset } with the
+// CLAMPED paging, so the route echoes what was actually applied.
+async function listGuildMap({ order = DEFAULT_ORDER, limit, offset } = {}, { pool = defaultPool } = {}) {
+  const key = isOrder(order) ? order : DEFAULT_ORDER;
+  const lim = clampLimit(limit);
+  const off = clampOffset(offset);
+  const { rows } = await pool.query(
+    `WITH roster AS (
+       SELECT m.guild_id, LEAST(count(*), $3)::int AS size
+         FROM platform_identity_guilds pg
+         JOIN platform_identity_guild_members m ON m.guild_id = pg.id
+         JOIN platform_identity_accounts pa ON pa.github_id = m.github_id
+        WHERE pg.visibility = 'public' AND m.shown_publicly AND ${accountVisibleSql('pa')}
+        GROUP BY m.guild_id
+     )
+     SELECT g.slug, g.name, r.size, t.works_shipped AS shipped
+       FROM platform_identity_guilds g
+       JOIN roster r ON r.guild_id = g.id
+       LEFT JOIN platform_identity_guild_totals t ON t.guild_id = g.id
+      WHERE g.visibility = 'public'
+      ORDER BY ${ORDERS[key]}
+      LIMIT $1 OFFSET $2`,
+    [lim, off, LIST_MAX],
+  );
+  return { order: key, results: rows, limit: lim, offset: off };
+}
+
+module.exports = {
+  ORDER_KEYS,
+  DEFAULT_ORDER,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+  MAX_OFFSET,
+  isOrder,
+  listGuildMap,
+};

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

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

package/package-lock.json

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

package/package.json

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

package/release-notes.json

@@ -8176,5 +8176,11 @@
       "id": "1002302",
       "text": "Guilds now show a combined track record: rounded totals of their members' credits, shipped work and projects, refreshed once a week. Members who keep their numbers private still count, but only when at least three such members"
     }
+  ],
+  "1.20.21": [
+    {
+      "id": "1002306",
+      "text": "The hub can now list guilds ranked by size or by how much their members have shipped, using the rounded weekly totals. Only public guilds with visible members appear, and private members are never counted."
+    }
   ]
 }

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

@@ -183,6 +183,10 @@ const INTEGRATION = new Set([
   // re-evaluated against a racing writer's committed row, are planner facts; the
   // DB-free sibling (guild_totals) pins the band scale and statement shapes.
   'guild_totals_db',
+  // task 1002306 (R30): the guild map against real SQL — the INNER join that drops
+  // an empty public roster, the capped roster count, and NULLS LAST on a guild
+  // with no weekly record yet. guilds_api §3b pins the route and statement shape.
+  'guild_map_db',
   // task 1003935: 'linkify_refs' was swept in with the three above without the
   // no-DB check they were being fixed for. It touches no Postgres at all — pure
   // string work plus a filesystem walk — so the DB-free lane skipped it and the

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.20'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.21'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/guild_map_db.mjs

@@ -0,0 +1,157 @@
+// tests/guild_map_db.mjs — the guild map against REAL SQL (R30, task 1002306;
+// ADR 0336 D8, amended by ADR 0337 D4.4).
+//
+// Why a real database: who is listed is an INNER join to an aggregated roster,
+// size is a capped count under the shared existence predicate, and the shipped
+// ordering puts un-refreshed guilds (NULL) last — each a planner fact the
+// DB-free route test (tests/guilds_api.mjs §3b) can only assert the shape of.
+//
+// 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 r30-, so a shared DB is safe; all
+// fixtures are deleted before and after.
+//
+// Run:  DATABASE_URL=... node tests/guild_map_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_map_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const guildMap = require('../modules/platform-identity/guild-map.js');
+const guilds = require('../modules/platform-identity/guilds.js');
+
+const A = 9002306001;    // public
+const B = 9002306002;    // public
+const C = 9002306003;    // public
+const HID = 9002306004;  // public account, hides their numbers
+const PRIV = 9002306005; // private account
+const PROV = 9002306006; // provisional
+const ALL_IDS = [A, B, C, HID, PRIV, PROV];
+
+const q = (sql, params) => pool.query(sql, params);
+async function cleanup() {
+  await q(`DELETE FROM platform_identity_guilds WHERE slug LIKE 'r30-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_accounts WHERE github_id = ANY($1::bigint[])`, [ALL_IDS]).catch(() => {});
+}
+
+let pass = 0;
+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 guild(slug, visibility = 'public') {
+  const { rows } = await q(
+    `INSERT INTO platform_identity_guilds (slug, name, visibility) VALUES ($1, $1, $2) RETURNING id`,
+    [slug, visibility],
+  );
+  return rows[0].id;
+}
+async function member(gid, id, { kind = 'member', shown = true } = {}) {
+  await q(
+    `INSERT INTO platform_identity_guild_members (guild_id, github_id, membership_kind, shown_publicly)
+     VALUES ($1, $2, $3, $4)`,
+    [gid, id, kind, shown],
+  );
+}
+const totals = (gid, shipped) => q(
+  `INSERT INTO platform_identity_guild_totals (guild_id, credits, works_shipped, karma, projects)
+   VALUES ($1, 0, $2, 0, 0)`, [gid, shipped],
+);
+// Only this file's guilds: a shared DB may hold others.
+const mine = async (order) => (await guildMap.listGuildMap({ order, limit: 100 }, { pool }))
+  .results.filter((r) => r.slug.startsWith('r30-'));
+
+try {
+  for (const f of [
+    'platform_identity_001_tables.sql', 'platform_identity_007_profile_consent.sql',
+    'platform_identity_008_handle.sql', 'platform_identity_012_account_privacy.sql',
+    'platform_identity_019_terms_acceptance.sql', 'platform_identity_025_guilds.sql',
+    'platform_identity_027_guild_totals.sql',
+  ]) await q(migrationSql(f));
+  await cleanup();
+
+  await account(A, 'r30a');
+  await account(B, 'r30b');
+  await account(C, 'r30c');
+  await account(HID, 'r30hid', { hide: true });
+  await account(PRIV, 'r30priv', { visibility: 'private' });
+  await account(PROV, 'r30prov', { state: 'provisional' });
+
+  // r30-big: three public members, one who hides numbers (still shown), one private (never).
+  const big = await guild('r30-big');
+  await member(big, A, { kind: 'owner' });
+  await member(big, B);
+  await member(big, HID);
+  await member(big, PRIV);
+  await totals(big, 20);
+  // r30-alpha / r30-beta: two each, a size tie broken on slug; beta has no record yet.
+  const alpha = await guild('r30-alpha');
+  await member(alpha, A, { kind: 'owner' });
+  await member(alpha, C);
+  await totals(alpha, 50);
+  const beta = await guild('r30-beta');
+  await member(beta, B, { kind: 'owner' });
+  await member(beta, C);
+  // r30-gamma: same shipped band as big (tie on shipped → slug).
+  const gamma = await guild('r30-gamma');
+  await member(gamma, C, { kind: 'owner' });
+  await totals(gamma, 20);
+  // Never on the map: unlisted; a public guild whose only members are private,
+  // provisional or unshown.
+  const quiet = await guild('r30-quiet', 'unlisted');
+  await member(quiet, A, { kind: 'owner', shown: false });
+  await member(quiet, B, { shown: false });
+  const hollow = await guild('r30-hollow');
+  await member(hollow, PRIV, { kind: 'owner' });
+  await member(hollow, PROV);
+  await member(hollow, A, { shown: false });
+
+  same((await mine('size')).map((r) => [r.slug, r.size]),
+    [['r30-big', 3], ['r30-alpha', 2], ['r30-beta', 2], ['r30-gamma', 1]],
+    'size order: public roster length, slug tiebreak; the hidden member counts, the private one never; unlisted and empty-roster guilds absent');
+  same((await mine('shipped')).map((r) => [r.slug, r.shipped]),
+    [['r30-alpha', 50], ['r30-big', 20], ['r30-gamma', 20], ['r30-beta', null]],
+    'shipped order: the stored band floor, slug tiebreak, a guild with no record yet last');
+
+  const page = await guilds.getPublicGuild('r30-big', { pool });
+  same((await mine('size')).find((r) => r.slug === 'r30-big').size, page.size,
+    'the map\'s size is exactly the guild page\'s size');
+
+  // Hides beat the map on the very next read: B goes private.
+  await q(`UPDATE platform_identity_accounts SET account_visibility = 'private' WHERE github_id = $1`, [B]);
+  same((await mine('size')).map((r) => [r.slug, r.size]),
+    [['r30-alpha', 2], ['r30-big', 2], ['r30-beta', 1], ['r30-gamma', 1]],
+    'a member going private leaves every guild\'s size on the next read — nothing cached');
+
+  same(Object.keys((await mine('size'))[0]).sort(), ['name', 'shipped', 'size', 'slug'],
+    'a row carries only what it publishes');
+
+  console.log(`\nguild_map_db.mjs: ${pass} passed`);
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/guilds_api.mjs

@@ -10,6 +10,10 @@
 //   3. THE PUBLIC READ — 404 for an unlisted guild is byte-identical to an
 //      unknown slug, needs no session, is no-store, and its roster statement
 //      carries shown_publicly AND the shared existence predicate.
+//   3b. THE GUILD MAP (task 1002306) — public guilds with a non-empty public
+//      roster, sized by the guild page's own predicate and cap, ranked only by
+//      published fields (size, or the STORED shipped band floor), paging
+//      clamped, and an unknown order refused before any SQL.
 //   4. SILENCE — a request written and one swallowed by a decline cooldown
 //      answer identically; a decline is an empty 204.
 //   5. THE CARD — an invite accept must echo the visibility its card showed,
@@ -90,6 +94,7 @@ require.cache[moduleApiPath] = {
   },
 };
 const guilds = require('../modules/platform-identity/guilds.js');
+const guildMap = require('../modules/platform-identity/guild-map.js');
 const buildGuildRoutes = require('../modules/platform-identity/routes/guilds.js');
 const buildPublicRoutes = require('../modules/platform-identity/routes/guilds-public.js');
 const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
@@ -281,6 +286,75 @@ test('public read: the roster is shown_publicly AND the shared existence predica
   assert.equal(calls[0].params[0], 'guild-a', 'the slug is looked up in canonical form');
 });
 
+// ===========================================================================
+// 3b. The guild map (R30, task 1002306; ADR 0336 D8 + ADR 0337 D4.4)
+// ===========================================================================
+
+const IS_MAP = (t) => /WITH roster AS/.test(t) && /FROM platform_identity_guilds g/.test(t);
+
+test('guild map: public guilds with a public roster, sized like the guild page, ranked by size then slug', async () => {
+  on((t) => (IS_MAP(t) ? result([
+    { slug: 'big', name: 'Big', size: 9, shipped: 50 },
+    { slug: 'new', name: 'New', size: 2, shipped: null },
+  ]) : result()));
+  session = null; // the map must not need one
+  try {
+    const res = await call('GET', '/api/bongos/guilds');
+    assert.equal(res.status, 200);
+    assert.equal(res.headers['cache-control'], 'no-store');
+    assert.deepEqual(Object.keys(res.json).sort(), ['count', 'order', 'page', 'results']);
+    assert.equal(res.json.order, 'size', 'size is the default ordering');
+    assert.equal(res.json.count, res.json.results.length);
+    assert.deepEqual(res.json.page, { limit: guildMap.DEFAULT_LIMIT, offset: 0 });
+    assert.equal(calls.length, 1, 'one statement, and no read of the viewer');
+    const { text, params } = calls[0];
+    assert.match(text, /AND m\.shown_publicly AND \(\(pa\.profile_state = 'active' AND pa\.terms_accepted_at IS NOT NULL\) AND pa\.account_visibility = 'public'\)/,
+      'size is the public roster: shown_publicly AND accountVisibleSql — the getPublicGuild predicate');
+    assert.match(text, /JOIN roster r ON r\.guild_id = g\.id/, 'an INNER join: a guild with an empty public roster is not on the map');
+    assert.match(text, /WHERE g\.visibility = 'public'/, 'an unlisted guild is never listed');
+    assert.match(text, /LEAST\(count\(\*\), \$3\)/, 'size is capped like the guild page\'s roster');
+    assert.match(text.split('SELECT g.slug')[0], /WHERE pg\.visibility = 'public' AND m\.shown_publicly/,
+      'the aggregate groups PUBLIC guilds\' memberships only — an unlisted guild is never scanned for the map');
+    assert.deepEqual(params, [guildMap.DEFAULT_LIMIT, 0, guilds.LIST_MAX]);
+    assert.match(text, /ORDER BY size DESC, g\.slug\s+LIMIT/, 'ties break on slug');
+  } finally { session = { github_id: ME, github_login: 'octo' }; }
+});
+
+test('guild map: shipped ranks by the STORED band floor, never an exact sum; a guild not yet refreshed sorts last', async () => {
+  on((t) => (IS_MAP(t) ? result([]) : result()));
+  const res = await call('GET', '/api/bongos/guilds?order=shipped');
+  assert.equal(res.status, 200);
+  assert.equal(res.json.order, 'shipped');
+  const { text } = calls[0];
+  assert.match(text, /LEFT JOIN platform_identity_guild_totals t ON t\.guild_id = g\.id/);
+  assert.match(text, /t\.works_shipped AS shipped/, 'the published key IS the sort key (ADR 0255)');
+  assert.match(text, /ORDER BY shipped DESC NULLS LAST, g\.slug/);
+  assert.doesNotMatch(text, /platform_identity_builder_project_activity/, 'no exact sum is ever read here (ADR 0337 D4.4)');
+});
+
+test('guild map: a row carries slug, name, size and shipped — nothing that names an account', async () => {
+  on((t) => (IS_MAP(t) ? result([]) : result()));
+  await call('GET', '/api/bongos/guilds');
+  const select = calls[0].text.split(/SELECT g\.slug/)[1].split('FROM')[0];
+  assert.equal(`g.slug${select}`.replace(/\s+/g, ' ').trim(), 'g.slug, g.name, r.size, t.works_shipped AS shipped');
+});
+
+test('guild map: an unknown order is a 400 that reaches no SQL; paging is clamped and echoed', async () => {
+  on(() => result());
+  const bad = await call('GET', '/api/bongos/guilds?order=credits');
+  assert.equal(bad.status, 400);
+  assert.equal(bad.json.error.code, 'guild_map_bad_order');
+  assert.equal(calls.length, 0);
+
+  on((t) => (IS_MAP(t) ? result([]) : result()));
+  const big = await call('GET', '/api/bongos/guilds?limit=1000&offset=99999');
+  assert.deepEqual(big.json.page, { limit: guildMap.MAX_LIMIT, offset: guildMap.MAX_OFFSET });
+  assert.deepEqual(calls[0].params.slice(0, 2), [guildMap.MAX_LIMIT, guildMap.MAX_OFFSET]);
+  on((t) => (IS_MAP(t) ? result([]) : result()));
+  const junk = await call('GET', '/api/bongos/guilds?limit=-3&offset=abc');
+  assert.deepEqual(junk.json.page, { limit: guildMap.DEFAULT_LIMIT, offset: 0 });
+});
+
 // ===========================================================================
 // 4. Join requests and silence (D3)
 // ===========================================================================