@bongos/core 1.20.18 → 1.20.20

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

@@ -0,0 +1,27 @@
+-- platform_identity_026_activity_reported_as_of.sql — WHEN the reporting instance
+-- read the totals a rollup carries (task 1004268).
+--
+-- WHY. POST /sso/activity/rollup upserted the live activity row last-writer-wins,
+-- and a report carried no timestamp. A sign-in report and a ship report racing to
+-- the hub could commit in the wrong order, leaving the older totals live (and, since
+-- task 1004244, as the newest snapshot) — a leaderboard regression that never
+-- happened, until the builder's next report.
+--
+-- WHAT. One nullable column: the instance's own "as of" for the stored totals, sent
+-- as the Bongos-Report-As-Of header and clamped to the hub's clock on write.
+-- upsertActivity's conflict branch applies a report only when its stamp is at least
+-- this one. NULL means "unstamped" — every row written before this column, and every
+-- report from an instance too old to send the header — and an unstamped side always
+-- applies, which is exactly the old behaviour.
+--
+-- No backfill, no default: inventing a stamp for an existing row would make it
+-- refuse an honest report from an instance whose clock reads earlier than the hub's.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent.
+
+BEGIN;
+
+ALTER TABLE platform_identity_builder_project_activity
+  ADD COLUMN IF NOT EXISTS reported_as_of timestamptz;
+
+COMMIT;

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/platform-identity.js

@@ -664,8 +664,10 @@ function sanitizeRecentShips(raw, clientOrigin) {
 // Descriptive analytics — never authority. Refreshes last_active on each report.
 // `clientOrigin` is the AUTHENTICATED client's registered origin (never a
 // caller-named one) and exists only to bound the ship links — see
-// origin-containment.js:urlWithinOrigin.
-async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped = 0, karma = 0, rank = null, disciplines = [], recentShips = [], clientOrigin = null }, { pool = defaultPool } = {}) {
+// origin-containment.js:urlWithinOrigin. `asOf` is when the instance read these
+// totals (task 1004268, migration 026): an older report never overwrites a newer
+// one; unstamped (an older instance) keeps last-writer-wins; a future stamp is clamped.
+async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped = 0, karma = 0, rank = null, disciplines = [], recentShips = [], clientOrigin = null, asOf = null }, { pool = defaultPool } = {}) {
   // api.LIVE_RANK_LADDER is a published doorway export (src/module-api.js, a
   // lazy getter over db-kernel's canonical four-rank ladder).
   const safeRank = api.LIVE_RANK_LADDER.includes(rank) ? rank : null;
@@ -677,17 +679,20 @@ async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped =
   return api.withTx(async (client) => {
     const { rows } = await client.query(
       `INSERT INTO platform_identity_builder_project_activity
-         (client_id, github_id, credits, tasks_shipped, karma, rank_held, disciplines, recent_ships, last_active, updated_at)
-       VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, now(), now())
+         (client_id, github_id, credits, tasks_shipped, karma, rank_held, disciplines, recent_ships, last_active, updated_at, reported_as_of)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, now(), now(),
+               CASE WHEN $9::timestamptz IS NULL THEN NULL ELSE LEAST($9::timestamptz, now()) END)
        ON CONFLICT (client_id, github_id) DO UPDATE SET
          credits = EXCLUDED.credits, tasks_shipped = EXCLUDED.tasks_shipped, karma = EXCLUDED.karma,
          rank_held = EXCLUDED.rank_held, disciplines = EXCLUDED.disciplines,
-         recent_ships = EXCLUDED.recent_ships,
+         recent_ships = EXCLUDED.recent_ships, reported_as_of = EXCLUDED.reported_as_of,
          last_active = now(), updated_at = now()
+       WHERE EXCLUDED.reported_as_of IS NULL OR platform_identity_builder_project_activity.reported_as_of IS NULL
+          OR EXCLUDED.reported_as_of >= platform_identity_builder_project_activity.reported_as_of
        RETURNING id, client_id, github_id`,
       // jsonb is bound as a JSON STRING: node-postgres serializes a JS array as a
       // Postgres ARRAY literal, which the jsonb column would reject.
-      [clientId, githubId, credits | 0, tasksShipped | 0, karma | 0, safeRank, disc, JSON.stringify(ships)],
+      [clientId, githubId, credits | 0, tasksShipped | 0, karma | 0, safeRank, disc, JSON.stringify(ships), asOf],
     );
     // Windowed data plane (task 1002977) — best-effort, see activity-snapshots.js.
     await recordActivitySnapshot({ clientId, githubId }, { client });

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/modules/platform-identity/routes/sso.js

@@ -83,6 +83,14 @@ const log = api.logger('platform-identity');
 
 const { pool, validateOrRespond, resolveSession } = api;
 
+// The Bongos-Report-As-Of header of a rollup as an ISO timestamp, or null when it
+// is absent or unparseable (task 1004268; see POST /sso/activity/rollup).
+function reportAsOf(req) {
+  const raw = req.get ? req.get('Bongos-Report-As-Of') : null;
+  const ms = typeof raw === 'string' && raw.length <= 64 ? Date.parse(raw) : NaN;
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : null;
+}
+
 // Minimal standalone error page for the browser leg (no template engine / deps).
 // The /sso/authorize failures are pre-redirect (bad client / bad redirect_uri), so
 // we must render our OWN page rather than bounce to an unvalidated URI.
@@ -538,6 +546,15 @@ module.exports = function ssoRoutes() {
   // 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.
   router.post('/sso/activity/rollup', async (req, res) => {
     if (validateOrRespond(req, res, {
@@ -595,6 +612,7 @@ module.exports = function ssoRoutes() {
         // ship link must fall inside (task 1002803). Taken from the client row,
         // never from the body, for the same reason client_id is.
         clientOrigin: client.origin,
+        asOf: reportAsOf(req),
       }, { pool });
       res.json({ ok: true });
     } catch (err) {

package/modules/platform-identity/tests/platform-identity.mjs

@@ -595,8 +595,9 @@ await ta('upsertActivity upserts per (client_id, github_id) with the talent snap
   assert.match(c.text, /ON CONFLICT \(client_id, github_id\) DO UPDATE/);
   // recent_ships (task 1002803) rides the same row as a jsonb STRING param —
   // an empty list when the sender reported none, never NULL. Its own cap,
-  // shape and link bound are covered by tests/hub_recent_ships.mjs.
-  assert.deepEqual(c.params, ['c1', 42, 100, 5, 3, 'metic', ['engineer'], '[]']);
+  // shape and link bound are covered by tests/hub_recent_ships.mjs. The last param
+  // is the report's as-of stamp (task 1004268): null when the sender gave none.
+  assert.deepEqual(c.params, ['c1', 42, 100, 5, 3, 'metic', ['engineer'], '[]', null]);
 });
 
 await ta('upsertActivity sanitizes third-party self-report (ADR 0171 D7): off-ladder rank → null, disciplines validated + capped', async () => {

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.18",
+  "version": "1.20.20",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.18",
+      "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.18",
+  "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

@@ -8164,5 +8164,17 @@
       "id": "1004265",
       "text": "The terms page now says your agreement is recorded when you sign in to a project in your browser, and explains why a command-line-only sign-in doesn't publish your profile."
     }
+  ],
+  "1.20.19": [
+    {
+      "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

@@ -87,6 +87,10 @@ const INTEGRATION = new Set([
   // WHERE NOT EXISTS statement) and the upsertActivity wiring against real SQL —
   // a fake pool can prove the query shape but not which reports it inserts.
   'activity_snapshots_db',
+  // task 1004268: an older rollup report never overwrites a newer one — a WHERE on
+  // the upsert's conflict branch, whose NULL handling and racing-writer outcome only
+  // a real Postgres settles (the DB-free sibling is activity_rollup_as_of).
+  'activity_rollup_order_db',
   // task 1002978: the windowed leaderboard against real SQL. Which snapshot
   // becomes a window baseline (a LATERAL at-or-before probe), a missing baseline
   // counting as zero, and the privacy matrix filtering are all planner facts the
@@ -174,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/bongos/auth-admission.js

@@ -148,6 +148,10 @@ async function reportActivityRollup({ builderId, githubId = null }) {
   const idp = loadIdpConfig();
   if (!idp) return;
   try {
+    // Stamped BEFORE the reads: the hub keeps whichever report was read latest, so a
+    // sign-in push and a ship push racing to it cannot land the older totals last
+    // (task 1004268). A header, not a body field — see the hub's rollup route.
+    const asOf = new Date().toISOString();
     // Snapshot the builder's talent signals directly from the DB (auth.js is a
     // kernel file — it uses pool, never a non-kernel domain module like metrics.js).
     const b = await pool.query(
@@ -162,7 +166,10 @@ async function reportActivityRollup({ builderId, githubId = null }) {
     const recentShips = await recentShipsForRollup(builderId);
     await fetch(`${idp.origin}/api/bongos/sso/activity/rollup`, {
       method: 'POST',
-      headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent() },
+      headers: {
+        'Content-Type': 'application/json', Accept: 'application/json', 'User-Agent': userAgent(),
+        'Bongos-Report-As-Of': asOf,
+      },
       body: JSON.stringify({
         client_id: idp.clientId,
         client_secret: idp.clientSecret,

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.18'; // 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/activity_rollup_as_of.mjs

@@ -0,0 +1,172 @@
+// tests/activity_rollup_as_of.mjs — task 1004268, the two ends of the wire.
+//
+// A rollup report now says WHEN the instance read its totals, so the hub can keep
+// the newest one when a sign-in push and a ship push race (the ordering itself is
+// proven against real SQL in tests/activity_rollup_order_db.mjs). This file holds
+// the two halves a fake can settle:
+//
+//   1. THE SENDER stamps every report with a `Bongos-Report-As-Of` header, taken
+//      BEFORE it reads the totals, and never puts the stamp in the body — the hub
+//      validates the body strictly, so a body field from a newer instance would
+//      400 on an older hub and lose the report.
+//   2. THE HUB ROUTE binds that header as the upsert's stamp, and reads a missing
+//      or unparseable one as "unstamped" (last-writer-wins, the old behaviour)
+//      rather than refusing — the sender never reads the response, so a 400 would
+//      silently drop the report, not just its ordering.
+//
+// DB-free: the core half pins require.cache and stubs fetch (the
+// tests/hub_recent_ships.mjs idiom); the hub half drives the real route handler
+// over a recording fake pool.
+//
+// Run:  node tests/activity_rollup_as_of.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.error(`  FAIL ${name}\n       ${e.message}`); }
+}
+
+function mockPool(answer = () => ({ rows: [] })) {
+  const calls = [];
+  const query = async (text, params = []) => {
+    calls.push({ text: String(text), params, at: Date.now() });
+    return answer(String(text), params) || { rows: [] };
+  };
+  return {
+    calls,
+    query,
+    connect: async () => ({ query, release: () => {} }),
+    find: (re) => calls.find((c) => re.test(c.text)),
+  };
+}
+
+// ---- 1. the sender ----------------------------------------------------------
+
+console.log('\n1. the instance stamps each report, in a header:');
+
+const pin = (rel, exports) => {
+  const p = require.resolve(rel);
+  require.cache[p] = { id: p, filename: p, loaded: true, exports };
+};
+
+await t('reportActivityRollup sends Bongos-Report-As-Of, stamped before the totals were read', async () => {
+  const senderPool = mockPool((sql) => {
+    if (/FROM builders WHERE id/.test(sql)) {
+      return { rows: [{ github_id: 42, total_credits: 7, karma: 1, rank: 'metic', preferred_disciplines: ['engineer'] }] };
+    }
+    if (/count\(\*\)/.test(sql)) return { rows: [{ n: 3 }] };
+    return { rows: [] };
+  });
+  pin('../src/bongos/pool.js', { pool: senderPool });
+  pin('../src/bongos/auth-config.js', {
+    loadIdpConfig: () => ({ origin: 'https://hub.example', clientId: 'c1', clientSecret: 's' }),
+  });
+  delete require.cache[require.resolve('../src/bongos/auth-admission.js')];
+  const { reportActivityRollup } = require('../src/bongos/auth-admission.js');
+
+  const sent = [];
+  const realFetch = globalThis.fetch;
+  globalThis.fetch = async (url, opts) => { sent.push({ url, opts }); return { ok: true, json: async () => ({ ok: true }) }; };
+  const before = Date.now();
+  try {
+    await reportActivityRollup({ builderId: 7 });
+  } finally {
+    globalThis.fetch = realFetch;
+  }
+  assert.equal(sent.length, 1, 'exactly one rollup was sent');
+  assert.match(sent[0].url, /\/sso\/activity\/rollup$/);
+  const stamp = sent[0].opts.headers['Bongos-Report-As-Of'];
+  assert.equal(typeof stamp, 'string', 'the report carries its as-of header');
+  const ms = Date.parse(stamp);
+  assert.ok(Number.isFinite(ms) && new Date(ms).toISOString() === stamp, `an ISO timestamp, got ${stamp}`);
+  assert.ok(ms >= before && ms <= senderPool.calls[0].at,
+    'stamped BEFORE the first read — a stamp taken after could order a report ahead of totals read later');
+  const body = JSON.parse(sent[0].opts.body);
+  assert.equal(body.credits, 7, 'CONTROL: the body still carries the totals');
+  assert.ok(!Object.keys(body).some((k) => /as_?of/i.test(k)),
+    'the stamp must never ride the body: an older hub validates it strictly and would 400 the whole report');
+});
+
+// ---- 2. the hub route --------------------------------------------------------
+
+console.log('\n2. the hub binds the stamp, and an unusable one degrades to unstamped:');
+
+const SECRET = 'as-of-secret';
+function hubRoute() {
+  const pi = require('../modules/platform-identity/platform-identity.js');
+  const rollupPool = mockPool((sql) => {
+    if (/FROM platform_identity_sso_clients/.test(sql)) {
+      return { rows: [{ client_id: 'c1', secret_hash: pi.sha256hex(SECRET), status: 'active', origin: 'https://p.example' }] };
+    }
+    if (/FROM platform_identity_project_memberships/.test(sql)) {
+      return { rows: [{ id: 1, client_id: 'c1', github_id: 42, membership_kind: 'member', signin_verified_at: '2026-08-29T00:00:00.000Z' }] };
+    }
+    return { rows: [{ id: 1 }] };
+  });
+  const helpers = require('../src/bongos/routes/_helpers.js');
+  const realApi = require('../src/module-api.js');
+  const moduleApiPath = require.resolve('../src/module-api.js');
+  require.cache[moduleApiPath] = {
+    id: moduleApiPath, filename: moduleApiPath, loaded: true,
+    exports: {
+      pool: rollupPool,
+      validateOrRespond: helpers.validateOrRespond,
+      resolveSession: async () => null,
+      logger: () => ({ info() {}, warn() {}, error() {} }),
+      LIVE_RANK_LADDER: realApi.LIVE_RANK_LADDER,
+      withTx: realApi.withTx,
+      corsPublicGet: () => (_q, _s, next) => next(),
+      on: () => () => {},
+      hasProvider: () => false,
+      registerProvider: () => {},
+    },
+  };
+  delete require.cache[require.resolve('../modules/platform-identity/routes/sso.js')];
+  const router = require('../modules/platform-identity/routes/sso.js')();
+  const layer = router.stack.find((l) => l.route && l.route.path === '/sso/activity/rollup');
+  return { handle: layer.route.stack[0].handle, rollupPool };
+}
+
+async function postRollup(headers) {
+  const { handle, rollupPool } = hubRoute();
+  const res = { body: null, failure: null };
+  res.json = (b) => { res.body = b; return res; };
+  res.fail = (code, ...rest) => { res.failure = { code, rest }; return res; };
+  const lower = Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v]));
+  const req = {
+    get: (name) => lower[name.toLowerCase()],
+    body: { client_id: 'c1', client_secret: SECRET, github_id: 42, credits: 10, tasks_shipped: 2, karma: 1 },
+  };
+  await handle(req, res, () => {});
+  const insert = rollupPool.find(/INSERT INTO platform_identity_builder_project_activity/);
+  return { res, stamp: insert ? insert.params[8] : undefined };
+}
+
+await t('a stamped report binds its as-of as the upsert stamp', async () => {
+  const { res, stamp } = await postRollup({ 'Bongos-Report-As-Of': '2026-09-30T12:00:10.123Z' });
+  assert.equal(res.failure, null, JSON.stringify(res.failure));
+  assert.deepEqual(res.body, { ok: true });
+  assert.equal(stamp, '2026-09-30T12:00:10.123Z');
+});
+
+await t('no header (an older instance) is unstamped — the report still applies', async () => {
+  const { res, stamp } = await postRollup({});
+  assert.deepEqual(res.body, { ok: true });
+  assert.equal(stamp, null);
+});
+
+await t('an unparseable or oversized header is unstamped, never a 400 that would drop the report', async () => {
+  for (const bad of ['yesterday-ish', '', 'x'.repeat(200)]) {
+    const { res, stamp } = await postRollup({ 'Bongos-Report-As-Of': bad });
+    assert.equal(res.failure, null, `a bad stamp (${bad.slice(0, 20)}) refused the whole report`);
+    assert.equal(stamp, null, `a bad stamp (${bad.slice(0, 20)}) was bound`);
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);