@bongos/core 1.19.1029 → 1.19.1030

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.1029",
-  "core_contract": "1.19.1029",
-  "source_commit": "9061b1b634a11e0d3737336b0d59fe110d2a7a17",
+  "core_version": "1.19.1030",
+  "core_contract": "1.19.1030",
+  "source_commit": "198e316ae502b4929018d6c592d28fd6bfa3b81d",
   "source_ref": "HEAD",
-  "built_at": "2026-09-25T21:07:08.900Z",
+  "built_at": "2026-09-25T21:18:42.202Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 529,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 3014,
-  "tree_sha256": "1305b1deb2512746e9b12451812ed65ff0e0364e416b1cbdc3ffacb9d12b8851",
+  "tree_sha256": "980cdb45376b2b35067d51b269d2709e1e1922dcbfb541554877cbcb9ae0c9e1",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2757,7 +2757,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "bc6a32426c475f26a5257ae634f5cf8c9c0863c53edd9b8981c411323b2f21e4"
+      "sha256": "bb67419c4dd3f2311a231615a96bd462cc6806b6e3a1967ea0614e3966ef9b0e"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6452,7 +6452,7 @@
     {
       "path": "modules/platform-identity/activity-snapshots.js",
       "mode": "0000644",
-      "sha256": "6cf9dce12fa2689b29a149ccb56204fb494ea7b8c4cc59a3421f471162dbb529"
+      "sha256": "c483a9ef792ad0ac3600dc1eb227323c6f851e7cd33189cc418a4e0ef3443ed6"
     },
     {
       "path": "modules/platform-identity/applicant-profile.js",
@@ -6652,7 +6652,7 @@
     {
       "path": "modules/platform-identity/platform-identity.js",
       "mode": "0000644",
-      "sha256": "16cae6287be02d85baa6ea359d80ba963df59a1d5f787f4234079b66b97812a6"
+      "sha256": "0f60239ec8ae79e1cb87870d7454f6b03de84170d557a06fae93cc556757004a"
     },
     {
       "path": "modules/platform-identity/pollers/code-sweep.js",
@@ -6767,12 +6767,12 @@
     {
       "path": "modules/platform-identity/tests/activity-snapshots.mjs",
       "mode": "0000644",
-      "sha256": "19682ecba44275080f00d203b4f708ea4f244f6107d3dce73960f97529c3874b"
+      "sha256": "47e4970496e303b66007c3c8cee9ecf1b1a10fe8805d28c8ef44d545ed7f1b4f"
     },
     {
       "path": "modules/platform-identity/tests/platform-identity.mjs",
       "mode": "0000644",
-      "sha256": "7db35ebebd3101fb2cb9d6a7d7e3d99c2aae176456a93d5b109f5f3ba72420e6"
+      "sha256": "6bbddd8d1b85f159ba1bade8df61552979e85e50dace2e1c9128de4b9ee8beb9"
     },
     {
       "path": "modules/platform-identity/ui/.gitkeep",
@@ -8362,12 +8362,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8608f78a458012a57ffc19e813402909f783c77bcc50f3d45780e4f8b2e3f759"
+      "sha256": "ab4b3ba1d87734173359f3ade610dc804a339ac3a518e7e5efebee2a1ff68cd0"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "32e6fc0b4953d6f15b41649ea9df77918f37ac8a8ed7168ce17d9040d04bf5c6"
+      "sha256": "ddb2d7173af124e48c454d0ba5db240e96d35541495fe7cf414246b1df433cd7"
     },
     {
       "path": "public-docs/index.html",
@@ -10412,7 +10412,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9763f23d6375a13a9ce55193be5689f74c04cd9170079735bca1956524f007c7"
+      "sha256": "439c0db441cc17b1ce9da268d30703325667f137d05f4b810786b356c9d56cfd"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10517,7 +10517,7 @@
     {
       "path": "tests/activity_snapshots_db.mjs",
       "mode": "0000644",
-      "sha256": "5dcd2f23e6549938decf39306807dac6405f95e3245bd9fbb59a4e482a2c694d"
+      "sha256": "219569f3160eb22a89e92a217b854a194afba6ebc7032dc07eff2534efc4390a"
     },
     {
       "path": "tests/admission_ceiling_gate.mjs",
@@ -12562,7 +12562,7 @@
     {
       "path": "tests/hub_recent_ships.mjs",
       "mode": "0000644",
-      "sha256": "0d8f07c64f4d17c8c894b2d6395281882efd4e186c5714fe9aab61e2808d4314"
+      "sha256": "ad183edeb3b24bdd70de80aad370c5411d32257907baa36c65b70a8143d8ec53"
     },
     {
       "path": "tests/idea_brightness.mjs",
@@ -14597,7 +14597,7 @@
     {
       "path": "tests/sso_checkin_identity_spoof.mjs",
       "mode": "0000644",
-      "sha256": "27bd2a87e001eec2bc58e13cfa58e53f88c73ebe7504b944c718182247d98ca7"
+      "sha256": "628db25b4f0c5dc157e4aa9bc9d136efd474e88769641061dfbeca6d3e013cc2"
     },
     {
       "path": "tests/sso_checkin_legacy_field_gone.mjs",

package/docs/module-api-changelog.md

@@ -2537,5 +2537,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.1027 with no explicit bump. run 36188894725. (task 1002620)
   1.19.1029 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1028 with no explicit bump. run 36189693139. (task 1002620)
+  1.19.1030 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1029 with no explicit bump. run 36190779629. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/platform-identity/activity-snapshots.js

@@ -11,37 +11,53 @@
 // Compaction (daily granularity after 90 days) is a later, volume-triggered task
 // — nothing here prunes. A disconnected/re-registered project's snapshots are
 // likewise not purged here — platform_identity_builder_project_activity (the
-// table this mirrors) has the identical gap today; the future leaderboard reader
-// is where consent (rollupVisibleSql) is enforced, per that table's own precedent.
+// table this mirrors) has the identical gap today; the leaderboard reader
+// (community-leaderboard.js) is where consent (rollupVisibleSql) is enforced.
 'use strict';
 
-const { pool: defaultPool } = require('../../src/module-api');
+const api = require('../../src/module-api');
 
-// Append one snapshot row iff the totals differ from the last one on record for
-// this (client, builder) pair — ONE statement, not a read then a write: the CTE
-// and the conditional INSERT run in the same round trip, closing the two-round-
-// trip check-then-insert race the earlier design had. A DB-level race remains
-// under READ COMMITTED — two truly concurrent statements for the same pair can
-// each see no conflicting row and both insert — but the worst case is a harmless
-// duplicate snapshot with IDENTICAL totals, which reads the same either way in
-// the windowed-delta arithmetic. A first-ever report (no prior row) always
-// inserts — NOT EXISTS is true against an empty CTE regardless of the
-// comparison. `id DESC` breaks a tie on an identical `reported_at` so "the last
-// snapshot" is always one specific row.
-async function recordActivitySnapshot({ clientId, githubId, credits = 0, tasksShipped = 0, karma = 0 }, { pool = defaultPool } = {}) {
-  const { rows } = await pool.query(
-    `WITH last AS (
-       SELECT credits, tasks_shipped, karma FROM platform_identity_activity_snapshots
-        WHERE client_id = $1 AND github_id = $2
-        ORDER BY reported_at DESC, id DESC LIMIT 1
-     )
-     INSERT INTO platform_identity_activity_snapshots (client_id, github_id, credits, tasks_shipped, karma, reported_at)
-     SELECT $1, $2, $3, $4, $5, now()
-      WHERE NOT EXISTS (SELECT 1 FROM last WHERE credits = $3 AND tasks_shipped = $4 AND karma = $5)
-     RETURNING id, reported_at`,
-    [clientId, githubId, credits, tasksShipped, karma],
-  );
-  return rows[0] || null;
+// Snapshot the LIVE totals of one (project, builder) iff they differ from the
+// last snapshot. Must run on the transaction that just upserted the live row:
+// that upsert's row lock queues racing reports, so this sees every earlier
+// snapshot and a live row no one else can change (task 1004244).
+// Best-effort: a fault rolls back to the savepoint, is logged, and returns null,
+// so the upsert still commits. If even that rollback fails the transaction is
+// gone, and the error propagates rather than let COMMIT silently drop the upsert.
+// reported_at is the write's own moment (clock_timestamp(); now() would be the
+// transaction start, before any wait on the lock), never earlier than the last
+// row's, so the index order (reported_at, id) always ends at the last write.
+async function recordActivitySnapshot({ clientId, githubId }, { client }) {
+  await client.query('SAVEPOINT activity_snapshot');
+  try {
+    const { rows } = await client.query(
+      `WITH live AS (
+         SELECT credits, tasks_shipped, karma FROM platform_identity_builder_project_activity
+          WHERE client_id = $1 AND github_id = $2
+       ), last AS (
+         SELECT credits, tasks_shipped, karma, reported_at FROM platform_identity_activity_snapshots
+          WHERE client_id = $1 AND github_id = $2
+          ORDER BY reported_at DESC, id DESC LIMIT 1
+       )
+       INSERT INTO platform_identity_activity_snapshots (client_id, github_id, credits, tasks_shipped, karma, reported_at)
+       SELECT $1, $2, live.credits, live.tasks_shipped, live.karma,
+              GREATEST(clock_timestamp(), (SELECT reported_at FROM last))
+         FROM live
+        WHERE NOT EXISTS (
+                SELECT 1 FROM last
+                 WHERE last.credits = live.credits
+                   AND last.tasks_shipped = live.tasks_shipped
+                   AND last.karma = live.karma)
+       RETURNING id, reported_at`,
+      [clientId, githubId],
+    );
+    await client.query('RELEASE SAVEPOINT activity_snapshot');
+    return rows[0] || null;
+  } catch (err) {
+    await client.query('ROLLBACK TO SAVEPOINT activity_snapshot');
+    api.logger('platform-identity').error({ err }, 'activity snapshot write failed (non-fatal)');
+    return null;
+  }
 }
 
 module.exports = { recordActivitySnapshot };

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

@@ -666,31 +666,26 @@ async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped =
     .filter((d) => typeof d === 'string' && d.length > 0 && d.length <= MAX_DISCIPLINE_LENGTH)
     .slice(0, MAX_ROLLUP_DISCIPLINES);
   const ships = sanitizeRecentShips(recentShips, clientOrigin);
-  const { rows } = await pool.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())
-     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,
-       last_active = now(), updated_at = now()
-     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)],
-  );
-  // Windowed data plane (task 1002977): one snapshot per report whose totals
-  // changed, skipped on a no-op re-report — see activity-snapshots.js.
-  // Best-effort, the application-echo.js precedent: descriptive analytics, never
-  // authority, so a fault here (e.g. migration 022 not yet applied on this
-  // instance) must never fail the rollup report that already committed above.
-  try {
-    await recordActivitySnapshot({ clientId, githubId, credits: credits | 0, tasksShipped: tasksShipped | 0, karma: karma | 0 }, { pool });
-  } catch (err) {
-    api.logger('platform-identity').error(`activity snapshot write failed (non-fatal): ${err && err.message}`);
-  }
-  return rows[0];
+  // One transaction with the snapshot: the upsert's row lock queues racing reports (task 1004244).
+  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())
+       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,
+         last_active = now(), updated_at = now()
+       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)],
+    );
+    // Windowed data plane (task 1002977) — best-effort, see activity-snapshots.js.
+    await recordActivitySnapshot({ clientId, githubId }, { client });
+    return rows[0];
+  }, { pool });
 }
 
 // The scouting rollup: one row PER BUILDER, aggregated across every project they

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

@@ -1,11 +1,14 @@
 // modules/platform-identity/tests/activity-snapshots.mjs
 //
 // DB-free unit suite for the windowed data plane's append-only snapshot history
-// (community spec D2, task 1002977). Recording-fake-pool style, matching
-// tests/platform-identity.mjs: proves the SQL SHAPE (one statement, correct
-// table/columns, bound params, the tiebreak) — a fake pool cannot execute the
-// `WHERE NOT EXISTS` itself, so the skip-on-unchanged BEHAVIOUR is proved
-// against real Postgres in tests/activity_snapshots_db.mjs instead.
+// (community spec D2, task 1002977; the live-row read, task 1004244).
+// Recording-fake-client style, matching tests/platform-identity.mjs: proves the
+// SHAPE — a SAVEPOINT on the caller's transaction, ONE INSERT that reads the
+// totals from the live row (never from the caller) guarded by the last snapshot,
+// RELEASE; on a fault, ROLLBACK TO SAVEPOINT, log the Error, return null. A fake
+// cannot execute `WHERE NOT EXISTS` or a lock, so WHICH reports insert and how
+// racing reports settle are proved against real Postgres in
+// tests/activity_snapshots_db.mjs.
 //
 // Run standalone: node modules/platform-identity/tests/activity-snapshots.mjs
 
@@ -13,6 +16,14 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
+
+// Pin the doorway's logger so the test can read what a fault logs.
+const logged = [];
+const moduleApiPath = require.resolve('../../../src/module-api.js');
+require.cache[moduleApiPath] = {
+  id: moduleApiPath, filename: moduleApiPath, loaded: true,
+  exports: { logger: () => ({ error: (obj, msg) => logged.push({ obj, msg }) }) },
+};
 const { recordActivitySnapshot } = require('../activity-snapshots.js');
 
 let passed = 0, failed = 0;
@@ -21,47 +32,75 @@ async function ta(name, fn) {
   catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
 }
 
-// A recording fake pool: returns queued responses in order and records every call.
-function mockPool(responses = []) {
+// A recording fake client: answers the INSERT with `insertRows`, or fails it;
+// `failRollback` also fails the savepoint rollback (a dead connection).
+function mockClient({ insertRows = [], failInsert = null, failRollback = null } = {}) {
   const calls = [];
-  let i = 0;
   return {
     calls,
     query: async (text, params) => {
       calls.push({ text: String(text), params: params || [] });
-      const r = responses[i++];
-      return r || { rows: [], rowCount: 0 };
+      if (/INSERT INTO platform_identity_activity_snapshots/.test(text)) {
+        if (failInsert) throw failInsert;
+        return { rows: insertRows };
+      }
+      if (/^ROLLBACK TO SAVEPOINT/.test(text) && failRollback) throw failRollback;
+      return { rows: [] };
     },
   };
 }
 
-console.log('recordActivitySnapshot (community spec D2, task 1002977):');
+const texts = (client) => client.calls.map((c) => c.text.replace(/\s+/g, ' ').trim());
+
+console.log('recordActivitySnapshot (community spec D2, tasks 1002977 + 1004244):');
 
-await ta('one statement: a CTE for the last snapshot, guarding a conditional INSERT', async () => {
-  const pool = mockPool([{ rows: [{ id: '1', reported_at: 'T1' }] }]);
-  const out = await recordActivitySnapshot({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
-  assert.equal(pool.calls.length, 1, 'one round trip, not a read then a write');
-  const c = pool.calls[0];
-  assert.match(c.text, /WITH last AS/);
-  assert.match(c.text, /FROM platform_identity_activity_snapshots/);
-  assert.match(c.text, /ORDER BY reported_at DESC, id DESC LIMIT 1/, 'a deterministic tiebreak on an identical reported_at');
-  assert.match(c.text, /INSERT INTO platform_identity_activity_snapshots/);
-  assert.match(c.text, /WHERE NOT EXISTS \(SELECT 1 FROM last WHERE credits = \$3 AND tasks_shipped = \$4 AND karma = \$5\)/);
-  assert.deepEqual(c.params, ['c1', 42, 100, 5, 3]);
+await ta('on the caller\'s transaction: SAVEPOINT, one conditional INSERT, RELEASE', async () => {
+  const client = mockClient({ insertRows: [{ id: '1', reported_at: 'T1' }] });
+  const out = await recordActivitySnapshot({ clientId: 'c1', githubId: 42 }, { client });
+  const t = texts(client);
+  assert.equal(t.length, 3);
+  assert.equal(t[0], 'SAVEPOINT activity_snapshot');
+  assert.match(t[1], /^WITH live AS/);
+  assert.equal(t[2], 'RELEASE SAVEPOINT activity_snapshot');
   assert.deepEqual(out, { id: '1', reported_at: 'T1' });
 });
 
-await ta('a skipped report (the fake pool answers no rows, as a real WHERE NOT EXISTS would on a match) returns null', async () => {
-  const pool = mockPool([{ rows: [] }]);
-  const out = await recordActivitySnapshot({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
-  assert.equal(pool.calls.length, 1);
+await ta('the INSERT reads the totals from the LIVE row, never from the caller', async () => {
+  const client = mockClient();
+  await recordActivitySnapshot({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3 }, { client });
+  assert.deepEqual(client.calls[1].params, ['c1', 42], 'only the pair is bound — a captured total has nowhere to go');
+  const sql = texts(client)[1];
+  assert.match(sql, /WITH live AS \( SELECT credits, tasks_shipped, karma FROM platform_identity_builder_project_activity WHERE client_id = \$1 AND github_id = \$2 \)/);
+  assert.match(sql, /SELECT \$1, \$2, live\.credits, live\.tasks_shipped, live\.karma, GREATEST\(clock_timestamp\(\), \(SELECT reported_at FROM last\)\) FROM live/,
+    'stamped at the write, and never earlier than the last row');
+  assert.ok(!/\$3/.test(sql), 'no third parameter exists to carry a caller value');
+});
+
+await ta('skipped when the live totals equal the last snapshot, found in migration 022\'s index order', async () => {
+  const client = mockClient();
+  const out = await recordActivitySnapshot({ clientId: 'c1', githubId: 42 }, { client });
+  const sql = texts(client)[1];
+  assert.match(sql, /last AS \( SELECT credits, tasks_shipped, karma, reported_at FROM platform_identity_activity_snapshots WHERE client_id = \$1 AND github_id = \$2 ORDER BY reported_at DESC, id DESC LIMIT 1 \)/,
+    '(client_id, github_id, reported_at DESC, id DESC) serves this as an index-order LIMIT 1');
+  assert.match(sql, /WHERE NOT EXISTS \( SELECT 1 FROM last WHERE last\.credits = live\.credits AND last\.tasks_shipped = live\.tasks_shipped AND last\.karma = live\.karma\)/);
+  assert.equal(out, null, 'no row returned → null');
+});
+
+await ta('a fault rolls back to the savepoint, logs the Error itself, and returns null — the caller\'s upsert still commits', async () => {
+  logged.length = 0;
+  const fault = Object.assign(new Error('relation "platform_identity_activity_snapshots" does not exist'), { code: '42P01' });
+  const client = mockClient({ failInsert: fault });
+  const out = await recordActivitySnapshot({ clientId: 'c1', githubId: 42 }, { client });
   assert.equal(out, null);
+  const t = texts(client);
+  assert.equal(t[t.length - 1], 'ROLLBACK TO SAVEPOINT activity_snapshot');
+  assert.equal(logged.length, 1);
+  assert.equal(logged[0].obj.err, fault, 'the Error object itself, so its stack and SQLSTATE reach the log');
 });
 
-await ta('missing totals default to zero, like upsertActivity\'s own defaults', async () => {
-  const pool = mockPool([{ rows: [{ id: '3', reported_at: 'T3' }] }]);
-  await recordActivitySnapshot({ clientId: 'c1', githubId: 42 }, { pool });
-  assert.deepEqual(pool.calls[0].params, ['c1', 42, 0, 0, 0]);
+await ta('if the savepoint rollback itself fails, the error propagates — COMMIT must not silently drop the upsert', async () => {
+  const client = mockClient({ failInsert: new Error('boom'), failRollback: new Error('connection terminated') });
+  await assert.rejects(() => recordActivitySnapshot({ clientId: 'c1', githubId: 42 }, { client }), /connection terminated/);
 });
 
 console.log(`\n${passed} passed, ${failed} failed`);

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

@@ -558,11 +558,26 @@ await ta('getAccountByLogin resolves case-insensitively, newest first', async ()
 
 console.log('\ncross-project activity (§4 scouting data plane):');
 
+// upsertActivity runs in a transaction, so a positional answer queue would be
+// spent by BEGIN: answer by statement shape instead, and find the upsert by text.
+const activityPool = ({ failSnapshot = false } = {}) => {
+  const calls = [];
+  const query = async (text, params) => {
+    calls.push({ text: String(text), params: params || [] });
+    if (failSnapshot && /INSERT INTO platform_identity_activity_snapshots/.test(text)) {
+      throw new Error('relation "platform_identity_activity_snapshots" does not exist');
+    }
+    if (/INSERT INTO platform_identity_builder_project_activity/.test(text)) return { rows: [{ id: '1' }] };
+    return { rows: [] };
+  };
+  return { calls, query, connect: async () => ({ query, release: () => {} }) };
+};
+const upsertCall = (pool) => pool.calls.find((c) => /INSERT INTO platform_identity_builder_project_activity/.test(c.text));
+
 await ta('upsertActivity upserts per (client_id, github_id) with the talent snapshot', async () => {
-  const pool = mockPool([{ rows: [{ id: '1' }] }]);
+  const pool = activityPool();
   await P.upsertActivity({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3, rank: 'metic', disciplines: ['engineer'] }, { pool });
-  const c = pool.calls[0];
-  assert.match(c.text, /INSERT INTO platform_identity_builder_project_activity/);
+  const c = upsertCall(pool);
   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,
@@ -571,7 +586,7 @@ await ta('upsertActivity upserts per (client_id, github_id) with the talent snap
 });
 
 await ta('upsertActivity sanitizes third-party self-report (ADR 0171 D7): off-ladder rank → null, disciplines validated + capped', async () => {
-  const pool = mockPool([{ rows: [{ id: '1' }] }]);
+  const pool = activityPool();
   await P.upsertActivity({
     clientId: 'c1', githubId: 42,
     rank: 'Supreme Overlord', // not one of the four core rank keys → stored null
@@ -581,7 +596,7 @@ await ta('upsertActivity sanitizes third-party self-report (ADR 0171 D7): off-la
       'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', // valid tail — capped to 8 total
     ],
   }, { pool });
-  const c = pool.calls[0];
+  const c = upsertCall(pool);
   assert.equal(c.params[5], null, 'an invented rank label is never stored');
   const disc = c.params[6];
   assert.ok(disc.length <= 8, `disciplines capped at 8 (got ${disc.length})`);
@@ -591,30 +606,35 @@ await ta('upsertActivity sanitizes third-party self-report (ADR 0171 D7): off-la
 });
 
 await ta('upsertActivity keeps a legitimate core rank key', async () => {
-  const pool = mockPool([{ rows: [{ id: '1' }] }]);
+  const pool = activityPool();
   await P.upsertActivity({ clientId: 'c1', githubId: 42, rank: 'archon', disciplines: [] }, { pool });
-  assert.equal(pool.calls[0].params[5], 'archon');
-});
-
-await ta('upsertActivity also appends to the snapshot history (task 1002977, community spec D2) — deleting that call would leave this red', async () => {
-  const pool = mockPool([{ rows: [{ id: '1' }] }, { rows: [{ id: 's1', reported_at: 'T' }] }]);
-  await P.upsertActivity({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
-  assert.equal(pool.calls.length, 2, 'the rollup upsert, then the snapshot statement');
-  assert.match(pool.calls[1].text, /INSERT INTO platform_identity_activity_snapshots/);
-  assert.deepEqual(pool.calls[1].params, ['c1', 42, 100, 5, 3]);
+  assert.equal(upsertCall(pool).params[5], 'archon');
 });
 
-await ta('upsertActivity survives a snapshot-write failure (best-effort — the application-echo.js precedent): the rollup report still succeeds', async () => {
-  const pool = {
-    calls: [],
-    query: async (text, params) => {
-      pool.calls.push({ text: String(text), params });
-      if (/INSERT INTO platform_identity_activity_snapshots/.test(text)) throw new Error('relation "platform_identity_activity_snapshots" does not exist');
-      return { rows: [{ id: '1' }] };
-    },
-  };
+await ta('upsertActivity writes the upsert and its snapshot in ONE transaction, the snapshot reading the live row (tasks 1002977 + 1004244)', async () => {
+  const pool = activityPool();
+  const out = await P.upsertActivity({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
+  const t = pool.calls.map((c) => c.text.replace(/\s+/g, ' ').trim().split(' ').slice(0, 4).join(' '));
+  assert.deepEqual(t, [
+    'BEGIN',
+    'INSERT INTO platform_identity_builder_project_activity (client_id,',
+    'SAVEPOINT activity_snapshot',
+    'WITH live AS (',
+    'RELEASE SAVEPOINT activity_snapshot',
+    'COMMIT',
+  ], 'the upsert holds the row lock until its snapshot is written; deleting the snapshot call leaves this red');
+  const snap = pool.calls.find((c) => /INSERT INTO platform_identity_activity_snapshots/.test(c.text));
+  assert.deepEqual(snap.params, ['c1', 42], 'the report\'s own totals are never handed to the snapshot');
+  assert.equal(out.id, '1');
+});
+
+await ta('upsertActivity survives a snapshot-write failure (best-effort — the application-echo.js precedent): the savepoint rolls back alone and the upsert commits', async () => {
+  const pool = activityPool({ failSnapshot: true });
   const out = await P.upsertActivity({ clientId: 'c1', githubId: 42, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
   assert.equal(out.id, '1', 'the rollup upsert result still returns despite the snapshot write throwing');
+  const t = pool.calls.map((c) => c.text.trim());
+  assert.ok(t.includes('ROLLBACK TO SAVEPOINT activity_snapshot'));
+  assert.equal(t[t.length - 1], 'COMMIT', 'the transaction still commits the upsert');
 });
 
 await ta('getMembership reads one (client, builder) row — the rollup membership requirement', async () => {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1029",
+  "version": "1.19.1030",
   "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/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1029'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1030'; // 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('dev-box'); log.info('mounted');

package/tests/activity_snapshots_db.mjs

@@ -1,11 +1,12 @@
-// tests/activity_snapshots_db.mjs — task 1002977 (community spec D2; real DB).
+// tests/activity_snapshots_db.mjs — tasks 1002977 + 1004244 (community spec D2; real DB).
 //
 // Proves the windowed data plane's append-only history against real SQL. The
-// skip-on-unchanged rule lives entirely inside one INSERT ... WHERE NOT EXISTS
-// statement (activity-snapshots.js), so a fake pool can only prove the query
-// SHAPE (modules/platform-identity/tests/activity-snapshots.mjs); only a real
-// Postgres can prove WHICH reports it actually inserts, and that upsertActivity
-// (the existing POST /sso/activity/rollup path) really calls it end to end.
+// skip-on-unchanged rule lives inside one INSERT ... WHERE NOT EXISTS, and racing
+// reports are serialised by the upsert's own row lock, so a fake pool can only
+// prove the SHAPE (modules/platform-identity/tests/activity-snapshots.mjs); only
+// a real Postgres can prove WHICH reports insert, that upsertActivity (the
+// POST /sso/activity/rollup path) writes the upsert and its snapshot together,
+// and that the newest snapshot always agrees with the live row.
 //
 // Real-DB integration test: self-skips without a reachable Postgres; in the
 // INTEGRATION set (scripts/gds/run-unit-tests.js) so the default DB-free lane
@@ -37,58 +38,126 @@ try {
 }
 
 // High-numbered fixture ids so a shared DB can never collide with real data.
-const BUILDER = 90002977, OTHER_BUILDER = 90002978;
-const IDS = [BUILDER, OTHER_BUILDER];
+const BUILDER = 90002977, OTHER_BUILDER = 90002978, RACE_BUILDER = 90002979, FLIGHT_BUILDER = 90002980;
+const IDS = [BUILDER, OTHER_BUILDER, RACE_BUILDER, FLIGHT_BUILDER];
 const CLIENT = 't1002977-client';
 const q = (sql, params) => pool.query(sql, params);
+const report = (githubId, credits) =>
+  pi.upsertActivity({ clientId: CLIENT, githubId, credits, tasksShipped: 1, karma: 0 }, { pool });
 
 async function cleanup() {
   await q(`DELETE FROM platform_identity_activity_snapshots WHERE github_id = ANY($1::bigint[])`, [IDS]).catch(() => {});
   await q(`DELETE FROM platform_identity_builder_project_activity WHERE github_id = ANY($1::bigint[])`, [IDS]).catch(() => {});
 }
+// The writer runs on its caller's transaction, right after the live row is set.
+async function setLiveAndSnapshot(githubId, credits) {
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+    await client.query(
+      `INSERT INTO platform_identity_builder_project_activity (client_id, github_id, credits, tasks_shipped, karma)
+       VALUES ($1, $2, $3, 5, 3)
+       ON CONFLICT (client_id, github_id) DO UPDATE SET credits = EXCLUDED.credits`,
+      [CLIENT, githubId, credits],
+    );
+    const row = await recordActivitySnapshot({ clientId: CLIENT, githubId }, { client });
+    await client.query('COMMIT');
+    return row;
+  } finally {
+    client.release();
+  }
+}
+async function history(githubId) {
+  const { rows } = await q(
+    `SELECT credits FROM platform_identity_activity_snapshots
+      WHERE client_id = $1 AND github_id = $2 ORDER BY reported_at, id`,
+    [CLIENT, githubId],
+  );
+  return rows.map((r) => r.credits);
+}
+// The newest snapshot (in the index order the writer and the leaderboard use) against the live row.
+async function newestVsLive(githubId) {
+  const { rows } = await q(
+    `SELECT (SELECT credits FROM platform_identity_activity_snapshots
+              WHERE client_id = $1 AND github_id = $2 ORDER BY reported_at DESC, id DESC LIMIT 1) AS newest,
+            (SELECT credits FROM platform_identity_builder_project_activity
+              WHERE client_id = $1 AND github_id = $2) AS live`,
+    [CLIENT, githubId],
+  );
+  return [rows[0].newest, rows[0].live];
+}
 
 let pass = 0;
 const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+const same = (actual, expected, msg) => { assert.deepEqual(actual, expected, msg); pass++; console.log(`  ok - ${msg}`); };
 
 try {
   await q(migrationSql('platform_identity_005_builder_activity.sql'));
   // upsertActivity's INSERT always names recent_ships (012_recent_ships adds the
-  // column); without it here, step 2 below fails 42703 on a fresh database.
+  // column); without it here, the upsertActivity steps fail 42703 on a fresh database.
   await q(migrationSql('platform_identity_012_recent_ships.sql'));
   await q(migrationSql('platform_identity_022_activity_snapshots.sql'));
   await cleanup();
 
-  // 1 — recordActivitySnapshot directly: the changed-totals skip rule.
-  const first = await recordActivitySnapshot({ clientId: CLIENT, githubId: BUILDER, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
-  ok(first !== null, 'a first-ever report inserts — nothing to be unchanged from');
-
-  const unchanged = await recordActivitySnapshot({ clientId: CLIENT, githubId: BUILDER, credits: 100, tasksShipped: 5, karma: 3 }, { pool });
-  ok(unchanged === null, 'an identical re-report inserts nothing');
-
-  const changed = await recordActivitySnapshot({ clientId: CLIENT, githubId: BUILDER, credits: 150, tasksShipped: 5, karma: 3 }, { pool });
-  ok(changed !== null, 'a changed report (credits differ) inserts a new row');
-
-  const { rows: history } = await q(
-    `SELECT credits FROM platform_identity_activity_snapshots
-      WHERE client_id = $1 AND github_id = $2 ORDER BY reported_at, id`,
+  // 1 — the writer snapshots the LIVE row, and only when it changed.
+  ok(await setLiveAndSnapshot(BUILDER, 100) !== null, 'a first-ever report inserts — nothing to be unchanged from');
+  ok(await setLiveAndSnapshot(BUILDER, 100) === null, 'an unchanged live row inserts nothing');
+  ok(await setLiveAndSnapshot(BUILDER, 150) !== null, 'a changed live row (credits differ) inserts a new row');
+  same(await history(BUILDER), [100, 150], 'exactly two rows, in write order — the unchanged report left no trace');
+  // A clock that stepped back: the last row carries a later stamp than "now".
+  await q(
+    `UPDATE platform_identity_activity_snapshots SET reported_at = clock_timestamp() + interval '1 hour'
+      WHERE client_id = $1 AND github_id = $2 AND credits = 150`,
     [CLIENT, BUILDER],
   );
-  ok(history.length === 2, 'exactly two rows exist — the unchanged report left no trace');
-  assert.deepEqual(history.map((r) => r.credits), [100, 150]);
-  pass++; console.log('  ok - the history is in report order');
+  const later = await setLiveAndSnapshot(BUILDER, 175);
+  same((await newestVsLive(BUILDER))[0], 175, 'a write after the clock stepped back is still the newest in index order');
+  ok(later !== null, 'and it was written, stamped no earlier than the row before it');
 
-  // 2 — upsertActivity (the real POST /sso/activity/rollup path) really calls it.
-  await pi.upsertActivity({ clientId: CLIENT, githubId: OTHER_BUILDER, credits: 10, tasksShipped: 1, karma: 0 }, { pool });
-  await pi.upsertActivity({ clientId: CLIENT, githubId: OTHER_BUILDER, credits: 10, tasksShipped: 1, karma: 0 }, { pool });
-  await pi.upsertActivity({ clientId: CLIENT, githubId: OTHER_BUILDER, credits: 20, tasksShipped: 1, karma: 0 }, { pool });
-  const { rows: viaRollup } = await q(
-    `SELECT credits FROM platform_identity_activity_snapshots
-      WHERE client_id = $1 AND github_id = $2 ORDER BY reported_at, id`,
-    [CLIENT, OTHER_BUILDER],
-  );
-  ok(viaRollup.length === 2, 'upsertActivity appends a snapshot per changed report — two calls, one repeat, one row skipped');
-  assert.deepEqual(viaRollup.map((r) => r.credits), [10, 20]);
-  pass++; console.log('  ok - deleting the call inside upsertActivity would leave this red');
+  // 2 — a report whose snapshot is still pending holds the row: its upsert is
+  // not visible yet, and a second report queues behind it. The prior state is the
+  // hard case the live-row read alone left open — the last snapshot (110) already
+  // equals the fresh report, while a stale report (100) is mid-flight. A table
+  // lock parks the stale report at its snapshot INSERT, deterministically.
+  await report(FLIGHT_BUILDER, 110);
+  const parker = await pool.connect();
+  let stale, fresh;
+  const settled = { stale: false, fresh: false };
+  try {
+    await parker.query('BEGIN');
+    await parker.query('LOCK TABLE platform_identity_activity_snapshots IN SHARE ROW EXCLUSIVE MODE');
+    stale = report(FLIGHT_BUILDER, 100).then(() => { settled.stale = true; });
+    await new Promise((r) => setTimeout(r, 300));
+    same((await newestVsLive(FLIGHT_BUILDER))[1], 110,
+      "the stale report's upsert is invisible while its snapshot is pending — the two commit together");
+    fresh = report(FLIGHT_BUILDER, 110).then(() => { settled.fresh = true; });
+    await new Promise((r) => setTimeout(r, 300));
+    ok(!settled.stale && !settled.fresh, 'and the fresh report queues behind it on the row lock');
+    await parker.query('COMMIT');
+  } finally {
+    parker.release();
+  }
+  await Promise.all([stale, fresh]);
+  same(await newestVsLive(FLIGHT_BUILDER), [110, 110],
+    'once both land, the newest snapshot agrees with the live row (the stale value is recorded, then superseded)');
+  same(await history(FLIGHT_BUILDER), [110, 100, 110], 'every change the live row went through is in the history');
+
+  // 3 — racing reports, end to end: however they interleave, once they settle
+  // the newest snapshot equals the live row.
+  for (let round = 0; round < 15; round++) {
+    const credits = [0, 1, 2, 3, 4].map((i) => 1000 + round * 10 + ((i * 7 + round) % 5));
+    await Promise.all(credits.map((c) => report(RACE_BUILDER, c)));
+    const [newest, live] = await newestVsLive(RACE_BUILDER);
+    assert.equal(newest, live, `round ${round}: newest snapshot ${newest} disagrees with the live row ${live}`);
+  }
+  pass++; console.log('  ok - 15 rounds of five racing reports: the newest snapshot always equals the live row');
+
+  // 4 — upsertActivity (the real POST /sso/activity/rollup path) really snapshots.
+  await report(OTHER_BUILDER, 10);
+  await report(OTHER_BUILDER, 10);
+  await report(OTHER_BUILDER, 20);
+  same(await history(OTHER_BUILDER), [10, 20],
+    'upsertActivity appends a snapshot per changed report — deleting the call inside it would leave this red');
 
   console.log(`\nactivity_snapshots_db.mjs: ${pass} passed`);
 } finally {

package/tests/hub_recent_ships.mjs

@@ -50,12 +50,15 @@ async function t(name, fn) {
 // asserts the params the real query actually bound.
 function mockPool(answer = () => ({ rows: [] })) {
   const calls = [];
+  const query = async (text, params = []) => {
+    calls.push({ text: String(text), params });
+    return answer(String(text), params) || { rows: [] };
+  };
   return {
     calls,
-    query: async (text, params = []) => {
-      calls.push({ text: String(text), params });
-      return answer(String(text), params) || { rows: [] };
-    },
+    query,
+    // upsertActivity runs its upsert + snapshot as one transaction on a pooled client.
+    connect: async () => ({ query, release: () => {} }),
     find: (re) => calls.find((c) => re.test(c.text)),
   };
 }

package/tests/sso_checkin_identity_spoof.mjs

@@ -73,6 +73,7 @@ require.cache[moduleApiPath] = {
   id: moduleApiPath, filename: moduleApiPath, loaded: true,
   exports: {
     pool,
+    withTx: (fn) => fn(pool),                  // transactions are not under test; keep the queue positional
     validateOrRespond: helpers.validateOrRespond,
     resolveSession: async () => null,          // the browser leg is not under test
     logger: () => noopLog,