@bongos/core 1.19.1015 → 1.19.1017

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

@@ -0,0 +1,153 @@
+// modules/platform-identity/builder-search.js — the PUBLIC builder search (D4,
+// docs/specs/bongos-v1-community-tab.md; task 1002979, goal 1000110 CT3). Answers
+// "find a builder by name, optionally narrowed to a discipline" for the future
+// /community page (tasks 1002980 / 1003363) — NOT the recruiting directory
+// (routes/scouting.js), which stays a separate, project.curate/owner-gated
+// surface with its own consent predicate, and NOT its archon-floor pre-accept
+// sliver (recruiter-sliver.js). This surface reveals nothing beyond the same
+// public-profile rules /profiles/:handle already applies (D8: no new disclosure
+// class).
+//
+// TWO PREDICATES FROM account-visibility.js, ONE PER AXIS D4 NAMES:
+//   NAME MATCH        — accountVisibleSql (existence: active + public). A
+//     hide_stats account is still findable BY NAME — hiding removes the
+//     rollup, not the page (the same rule /profiles/:handle already honors).
+//   DISCIPLINE MATCH   — rollupVisibleSql (existence AND NOT hide_stats),
+//     because a discipline is ROLLUP-DERIVED
+//     (platform_identity_builder_project_activity.disciplines) and the rollup
+//     is exactly what hide_stats suppresses. A hidden account's disciplines are
+//     therefore never attached and never filterable — which is what keeps a
+//     discipline facet from re-exposing a hidden account's rollup by a side
+//     door. Private and provisional accounts never reach either predicate, so
+//     they are absent from every result regardless of query or filter.
+// Both predicates are IMPORTED, never re-derived — the sole-owner rule
+// tests/effective_visibility_predicate.mjs enforces.
+//
+// Matching: handle / display_name PREFIX (escaped LIKE) OR pg_trgm fuzzy (the
+// `%` similarity operator) — the two legs D4 asks for. BOTH legs compare
+// lower(column) against lower($1)/lower($2) — the `%` operator is
+// case-SENSITIVE (unlike ILIKE, pg_trgm has no case-insensitive variant), so
+// without the explicit lower() a query differing only in case would silently
+// miss the fuzzy leg while the `sim` column (already lower()-folded) still
+// scored it. Indexed by migration platform_identity_023_builder_search_trgm.sql
+// — a GIN gin_trgm_ops index on lower(handle) and lower(display_name), which
+// accelerates both legs since both now query that same expression.
+// github_id never crosses the projection — handle is the address, exactly as
+// every sibling public read in this module already treats it.
+'use strict';
+
+const { pool: defaultPool } = require('../../src/module-api');
+const { accountVisibleSql, rollupVisibleSql } = require('./account-visibility');
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
+// Deep OFFSET pagination on an unauthenticated route is a free scan-and-discard
+// knob (?offset=999999999 still walks and throws away every matched row before
+// the LIMIT) — capped so a caller can page a reasonable distance and no further.
+const MAX_OFFSET = 1000;
+// A 1-character query has no usable trigram and a near-unselective LIKE
+// prefix, so it would materialize and sort a large share of the table before
+// LIMIT on every anonymous request. 2 chars is the floor at which a trigram
+// exists at all.
+const MIN_QUERY_CHARS = 2;
+const MAX_QUERY_CHARS = 100;
+const MAX_DISCIPLINE_CHARS = 32; // mirrors upsertActivity's per-discipline cap
+
+function clampLimit(limit) {
+  const n = parseInt(limit, 10);
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_LIMIT;
+  return Math.min(n, MAX_LIMIT);
+}
+
+function clampOffset(offset) {
+  const n = parseInt(offset, 10);
+  if (!Number.isFinite(n) || n < 0) return 0;
+  return Math.min(n, MAX_OFFSET);
+}
+
+// Escape LIKE's own wildcard characters so a searcher's literal % or _ can't
+// turn a prefix match into an unbounded pattern.
+function escapeLikePrefix(s) {
+  return s.replace(/[\\%_]/g, (c) => `\\${c}`);
+}
+
+// searchBuilders — the one read behind GET /community/search. `q` is required
+// (too short/empty/oversized → no results, never a throw — the route
+// validates and 400s before calling this; this stays defensive on its own).
+// `discipline` is optional; '' means no filter. Returns
+// { results, limit, offset } — `limit`/`offset` are the CLAMPED values
+// actually used, so a caller (the route) never re-derives them to echo back.
+// A result's `disciplines` is null for a hidden account or one with no
+// rollup activity.
+async function searchBuilders({ q, discipline, limit, offset, pool = defaultPool } = {}) {
+  const query = typeof q === 'string' ? q.trim() : '';
+  const lim = clampLimit(limit);
+  const off = clampOffset(offset);
+  if (query.length < MIN_QUERY_CHARS || query.length > MAX_QUERY_CHARS) {
+    return { results: [], limit: lim, offset: off };
+  }
+  const disc = typeof discipline === 'string' ? discipline.trim().slice(0, MAX_DISCIPLINE_CHARS) : '';
+
+  const { rows } = await pool.query(
+    `WITH matches AS (
+       SELECT pa.github_id, pa.handle, pa.github_login, pa.display_name, pa.avatar_url,
+              (lower(pa.handle) = lower($1)) AS exact_handle,
+              GREATEST(similarity(lower(pa.handle), lower($1)),
+                       similarity(lower(COALESCE(pa.display_name, '')), lower($1))) AS sim
+         FROM platform_identity_accounts pa
+        WHERE ${accountVisibleSql('pa')}
+          AND (
+            lower(pa.handle) LIKE lower($2) ESCAPE '\\'
+            OR lower(pa.display_name) LIKE lower($2) ESCAPE '\\'
+            OR lower(pa.handle) % lower($1)
+            OR lower(pa.display_name) % lower($1)
+          )
+     ), disc AS (
+       -- Scoped to the name matches only (never the whole activity table),
+       -- which is strictly smaller — though 'matches' itself is bounded only
+       -- by MIN_QUERY_CHARS' selectivity, not by a hard cap, since the
+       -- discipline filter (below) needs every match's disciplines before
+       -- LIMIT can apply.
+       SELECT x.github_id, array_agg(DISTINCT x.d) AS disciplines
+         FROM (SELECT a.github_id, unnest(a.disciplines) AS d
+                 FROM platform_identity_builder_project_activity a
+                WHERE a.github_id IN (SELECT github_id FROM matches)
+                  AND EXISTS (
+                        SELECT 1 FROM platform_identity_accounts pa2
+                         WHERE pa2.github_id = a.github_id AND ${rollupVisibleSql('pa2')})) x
+        WHERE x.d IS NOT NULL
+        GROUP BY x.github_id
+     )
+     SELECT m.handle, m.github_login, m.display_name, m.avatar_url, d.disciplines
+       FROM matches m
+       LEFT JOIN disc d ON d.github_id = m.github_id
+      WHERE ($3::text = '' OR d.disciplines @> ARRAY[$3]::text[])
+      ORDER BY m.exact_handle DESC, m.sim DESC, m.handle
+      LIMIT $4 OFFSET $5`,
+    [query, `${escapeLikePrefix(query)}%`, disc, lim, off],
+  );
+  return {
+    results: rows.map((r) => ({
+      handle: r.handle,
+      github_login: r.github_login,
+      display_name: r.display_name,
+      avatar_url: r.avatar_url,
+      disciplines: Array.isArray(r.disciplines) ? r.disciplines : null,
+    })),
+    limit: lim,
+    offset: off,
+  };
+}
+
+module.exports = {
+  searchBuilders,
+  clampLimit,
+  clampOffset,
+  escapeLikePrefix,
+  DEFAULT_LIMIT,
+  MAX_LIMIT,
+  MAX_OFFSET,
+  MIN_QUERY_CHARS,
+  MAX_QUERY_CHARS,
+  MAX_DISCIPLINE_CHARS,
+};

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

@@ -0,0 +1,46 @@
+-- platform_identity_022_activity_snapshots.sql — the windowed data plane's ONE
+-- new table (community spec D2, task 1002977): an append-only history of each
+-- (project, builder)'s reported totals, one row per rollup report WHOSE TOTALS
+-- CHANGED (a no-op re-report inserts nothing — upsertActivity skips it via
+-- activity-snapshots.js:recordActivitySnapshot).
+--
+-- A window's value = latest totals (platform_identity_builder_project_activity)
+-- minus the last snapshot at-or-before the window start, summed across projects;
+-- missing baseline counts as zero (D2 option A, chosen over B/C — see the spec).
+-- Reporting-time semantics, not earning-time: the honest, accepted V1 limitation.
+--
+-- Retention: nothing pruned here. A compaction pass (daily granularity after 90
+-- days) is a later, volume-triggered task, not built now.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_activity_snapshots (
+  id             bigserial PRIMARY KEY,
+
+  -- The project (the sso_client that reported) + the builder (stable github id) —
+  -- the same pair platform_identity_builder_project_activity is keyed on.
+  client_id      text NOT NULL,
+  github_id      bigint NOT NULL,
+
+  -- The reported totals AT this point in time (a snapshot, not a delta).
+  credits        integer NOT NULL DEFAULT 0,
+  tasks_shipped  integer NOT NULL DEFAULT 0,
+  karma          integer NOT NULL DEFAULT 0,
+
+  reported_at    timestamptz NOT NULL DEFAULT now()
+);
+
+-- The windowed read's whole access path: "the last snapshot at-or-before a given
+-- timestamp, for this (project, builder)". DESC so the common query (the most
+-- recent snapshot <= window start) hits the front of the index; `id DESC`
+-- matches activity-snapshots.js's own tiebreak, so its top-1 probe is a pure
+-- index-order LIMIT 1 rather than relying on an incremental sort.
+CREATE INDEX IF NOT EXISTS platform_identity_activity_snapshots_builder_time
+  ON platform_identity_activity_snapshots (client_id, github_id, reported_at DESC, id DESC);
+
+COMMENT ON TABLE platform_identity_activity_snapshots IS
+  'Append-only history of reported totals per (client_id, github_id), one row per rollup report whose totals changed (community spec D2, task 1002977). A leaderboard window computes latest minus the last snapshot at-or-before the window start; missing baseline counts as zero. Reporting-time semantics, not earning-time. Nothing pruned in V1 — a later, volume-triggered compaction task handles retention.';
+
+COMMIT;

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

@@ -0,0 +1,40 @@
+-- platform_identity_023_builder_search_trgm.sql — GIN trigram indexes for the
+-- public builder search (D4, docs/specs/bongos-v1-community-tab.md; task
+-- 1002979). builder-search.js's searchBuilders() queries
+-- lower(handle) LIKE lower($2) OR lower(handle) % lower($1) (and the same
+-- pair for display_name) against platform_identity_accounts on EVERY request
+-- to an UNAUTHENTICATED, rate-limited-but-public route — an unindexed
+-- sequential scan there is a cost every anonymous caller can trigger.
+--
+-- INDEXED ON THE EXPRESSION, NOT THE BARE COLUMN. Both query legs compare
+-- lower(handle)/lower(display_name), so a plain gin_trgm_ops index on the raw
+-- column would never be used — Postgres only matches a functional index
+-- against the identical expression. One index per column then serves BOTH
+-- legs (prefix LIKE and % fuzzy), because pg_trgm's GIN opclass supports LIKE
+-- as well as the trigram similarity operators.
+--
+-- pg_trgm itself is already enabled repo-wide by migrations/103_search_chunks.sql
+-- (a core migration, so it runs before any module migration) — nothing to
+-- create here.
+--
+-- WHY NOT CONCURRENTLY. Same reasoning core_222 and modules/ideas/migrations/-
+-- ideas_004_lineage_route_index.sql recorded for their own indexes: CREATE
+-- INDEX CONCURRENTLY cannot run inside a transaction block, and this file is
+-- wrapped BEGIN/COMMIT so it lands atomically. Acceptable here specifically
+-- because platform_identity_accounts is a hub-only, human-signup-paced table
+-- (one row per platform account) — the build is a light, one-time lock against
+-- a small table, not a write-hot one.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Forward-safe: index
+-- creation only, no column/type change, so the previous release runs
+-- unmodified against this schema. Idempotent (IF NOT EXISTS).
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS platform_identity_accounts_handle_trgm
+  ON platform_identity_accounts USING gin (lower(handle) gin_trgm_ops);
+
+CREATE INDEX IF NOT EXISTS platform_identity_accounts_display_name_trgm
+  ON platform_identity_accounts USING gin (lower(display_name) gin_trgm_ops);
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -10,7 +10,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections"],
+    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search"],
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull"]
   },

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

@@ -24,6 +24,9 @@ const terms = require('./terms-acceptance');
 // reads the SAME rule as a ship link instead of the "different host" check it had —
 // see origin-containment.js for why it is downward only and why it lives there.
 const { urlWithinOrigin } = require('./origin-containment');
+// The windowed data plane's append-only snapshot history (task 1002977, community
+// spec D2) — one call from upsertActivity below; the mechanism itself lives there.
+const { recordActivitySnapshot } = require('./activity-snapshots');
 
 const { pool: defaultPool } = api;
 const { ACCOUNT_VISIBILITY, accountVisibleSql, rollupVisibleSql, isRollupVisible, scoutingListableSql } = visibility;
@@ -677,6 +680,16 @@ async function upsertActivity({ clientId, githubId, credits = 0, tasksShipped =
     // 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];
 }
 

package/modules/platform-identity/routes/community-search.js

@@ -0,0 +1,120 @@
+// modules/platform-identity/routes/community-search.js — GET /community/search,
+// the PUBLIC builder-search read behind the future /community page (D4,
+// docs/specs/bongos-v1-community-tab.md; task 1002979, goal 1000110 CT3). A
+// sibling of public-profile.js and scouting.js — same module, same doorway,
+// DIFFERENT surface: this is name+discipline search under exactly the
+// public-profile visibility rules, never the project.curate/owner-gated
+// recruiting directory (routes/scouting.js `GET /scouting`) and never its
+// archon-floor pre-accept sliver (`GET /scouting/:handle`). The visibility
+// decision lives entirely in ../builder-search.js (account-visibility.js's
+// shared predicates); this file is the thin HTTP shell — validation, the
+// per-IP rate limit, the response envelope.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const builderSearch = require('../builder-search');
+
+const { pool, corsPublicGet } = api;
+
+// Resolved at CALL time, never at load — the scouting.js precedent: a proof
+// that stubs a PARTIAL doorway (pool + the auth gates only) must still be able
+// to require() this file, and a module-scope api.logger() call would break
+// that. A logging line is not worth breaking a privacy proof over.
+let resolvedLog = null;
+const log = {
+  error: (msg) => {
+    if (!resolvedLog) resolvedLog = typeof api.logger === 'function' ? api.logger('platform-identity') : { error: () => {} };
+    resolvedLog.error(msg);
+  },
+};
+
+// Per-IP read cap for this UNAUTHENTICATED route (the public-profile.js R05
+// posture: the global limiter only meters WRITES, so an uncapped scraper could
+// otherwise run the trigram leg at line rate). Vendored, not shared — the core
+// /public/* limiter is not on the doorway, and each public GET here owns its
+// own budget rather than reaching into a sibling module's copy.
+const READ_RATE_WINDOW_MS = 60 * 1000;
+const READ_RATE_LIMIT = 60;
+const buckets = new Map(); // ip -> timestamp[]
+
+const sweepTimer = setInterval(() => {
+  const cutoff = Date.now() - READ_RATE_WINDOW_MS;
+  for (const [k, arr] of buckets) {
+    while (arr.length && arr[0] < cutoff) arr.shift();
+    if (arr.length === 0) buckets.delete(k);
+  }
+}, 5 * 60 * 1000);
+if (typeof sweepTimer.unref === 'function') sweepTimer.unref();
+
+function searchReadRateLimit(req, res, next) {
+  const now = Date.now();
+  const key = req.ip || req.socket?.remoteAddress || 'unknown';
+  let bucket = buckets.get(key);
+  if (!bucket) { bucket = []; buckets.set(key, bucket); }
+  const cutoff = now - READ_RATE_WINDOW_MS;
+  while (bucket.length && bucket[0] < cutoff) bucket.shift();
+  if (bucket.length >= READ_RATE_LIMIT) {
+    const retryAfter = Math.max(1, Math.ceil((bucket[0] + READ_RATE_WINDOW_MS - now) / 1000));
+    res.set('Retry-After', String(retryAfter));
+    res.set('X-RateLimit-Scope', 'community-search-read');
+    res.set('X-RateLimit-Limit', String(READ_RATE_LIMIT));
+    return res.fail('rate_limited', 429, { scope: 'community-search-read', retry_after_seconds: retryAfter });
+  }
+  bucket.push(now);
+  return next();
+}
+
+module.exports = function communitySearchRoutes() {
+  const router = express.Router();
+
+  router.use('/community/search', corsPublicGet('/community/search'));
+
+  // rank: public — a name/discipline search under EXACTLY the public-profile
+  // visibility rules (D4): a hide_stats account is findable by name but drops
+  // out of a discipline-filtered result (disciplines are rollup-derived, and
+  // the rollup is what hide_stats suppresses); private and provisional
+  // accounts never appear. no-store: the same hide-must-beat-the-cache posture
+  // as /profiles/:handle (ADR 0171 D5) — this reads the identical predicate
+  // and a flip must be reflected on the very next request.
+  router.get('/community/search', searchReadRateLimit, async (req, res) => {
+    const q = (typeof req.query.q === 'string' ? req.query.q : '').trim();
+    if (!q) {
+      return res.fail('bad_request', { status: 400, message: 'q (a non-empty search string) is required' });
+    }
+    if (q.length < builderSearch.MIN_QUERY_CHARS) {
+      return res.fail('query_too_short', { status: 400, message: `q must be at least ${builderSearch.MIN_QUERY_CHARS} characters` });
+    }
+    if (q.length > builderSearch.MAX_QUERY_CHARS) {
+      return res.fail('query_too_long', { status: 400, message: `q must be at most ${builderSearch.MAX_QUERY_CHARS} characters` });
+    }
+    const discipline = (typeof req.query.discipline === 'string' ? req.query.discipline : '').trim();
+    if (discipline.length > builderSearch.MAX_DISCIPLINE_CHARS) {
+      return res.fail('discipline_too_long', { status: 400, message: `discipline must be at most ${builderSearch.MAX_DISCIPLINE_CHARS} characters` });
+    }
+    try {
+      const { results, limit, offset } = await builderSearch.searchBuilders({
+        q, discipline, limit: req.query.limit, offset: req.query.offset, pool,
+      });
+      res.set('Cache-Control', 'no-store');
+      res.json({
+        query: q,
+        discipline: discipline || null,
+        count: results.length,
+        results,
+        page: { limit, offset },
+      });
+    } catch (err) {
+      log.error(`GET /community/search failed: ${err && err.message}`);
+      res.fail('search_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+// Exported for tests — the pure rate-limit bucket logic + limits (the
+// modules/memory/routes/search.js precedent).
+module.exports._internals = { searchReadRateLimit, READ_RATE_LIMIT, READ_RATE_WINDOW_MS };

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

@@ -10,11 +10,14 @@
 // ../scouting-authz.js, which carries the full argument for why reading an
 // instance-asserted ownership claim is not the ADR 0201 D3 inversion.
 //
-// WHO APPEARS IN IT: consent is enforced IN listScoutingRollup itself, by the
-// shared scoutingListableSql predicate — active, publicly visible, not hidden,
-// and not opted out of recruiting (ADR 0171 D2/D3 + privacy spec D1). So this
-// surface honors both the hide flag and the recruiting opt-out by construction,
-// and widening WHO may read it could not widen WHAT is shown.
+// WHO APPEARS IN IT: consent is enforced in the two reads themselves, by shared
+// predicates. `builders` is listScoutingRollup over scoutingListableSql —
+// active, publicly visible, not hidden, not opted out (ADR 0171 D2/D3 + privacy
+// spec D1). `name_only` (ADR 0334, task 1002291) is the hidden-but-reachable
+// builder the spec's D2 lists "name-only": login, name and avatar, via
+// scouting-name-only.js. So the opt-out removes a builder and hide only strips
+// their row to identity, by construction; widening WHO may read it could not
+// widen WHAT is shown.
 //
 // TWO READS, TWO AUDIENCES — and the difference is the point (ADR 0215 D4, task
 // 1002968). `GET /scouting` is the DIRECTORY: the full rollup for builders who
@@ -37,6 +40,7 @@ const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const scoutingAuthz = require('../scouting-authz');
 const recruiterSliver = require('../recruiter-sliver');
+const scoutingNameOnly = require('../scouting-name-only');
 
 const { pool, requireBuilder, parsePagination } = api;
 
@@ -77,12 +81,15 @@ module.exports = function scoutingRoutes() {
     async (req, res) => {
       const { limit } = parsePagination(req, { defaultLimit: 100, maxLimit: 500 });
       try {
-        const builders = await pi.listScoutingRollup({ limit, pool });
+        const [builders, nameOnly] = await Promise.all([
+          pi.listScoutingRollup({ limit, pool }),
+          scoutingNameOnly.listScoutingNameOnly({ limit, pool }),
+        ]);
         // Same rollup-derived data as the sliver, so the same rule: hide and the
         // recruiting opt-out must beat any cache (ADR 0171 D5). This route
         // predates that posture and was the only rollup read still missing it.
         res.set('Cache-Control', 'no-store');
-        res.json({ builders });
+        res.json({ builders, name_only: nameOnly });
       } catch (err) {
         log.error(`GET /scouting failed: ${err && err.message}`);
         res.fail('scouting_failed', { status: 500, message: 'internal error' });

package/modules/platform-identity/scouting-name-only.js

@@ -0,0 +1,47 @@
+// modules/platform-identity/scouting-name-only.js — the recruiting directory's
+// NAME-ONLY tier: builders who hid their cross-project record but are still open
+// to recruiting (ADR 0334, task 1002291 / R15; privacy spec D2, whose recruiter
+// column lists a hidden builder "name-only (if not opted out)").
+//
+// WHAT IT RETURNS. For each such account: its GitHub login, display name and
+// avatar — what that builder's own public profile page already shows — and
+// nothing else. No id, no count, no date, no craft: every one of those is
+// derived from the record the builder hid. The projection is written out key by
+// key, so a column added to the statement later cannot ride into a response.
+//
+// WHO IS IN IT is scoutingNameOnlySql (account-visibility.js): publicly visible
+// AND hidden AND reachable. Two things it deliberately does NOT do:
+//   - consult the activity rollup. Listing only hidden builders who have built
+//     something would make presence here say so, and that is rollup-derived.
+//   - order by anything but the login. The ranked tier's order IS the record, so
+//     a hidden row ordered by it would leak its rank by position.
+//
+// WHO MAY READ IT is the directory's door (routes/scouting.js, ADR 0210). Not
+// authority in either direction (ADR 0016).
+//
+// Its own file because platform-identity.js sits at the 1,500-line ratchet.
+// Proof: tests/scouting_owner_access_and_reach.mjs §2b; the one-reader pin is in
+// tests/effective_visibility_predicate.mjs.
+'use strict';
+
+const { scoutingNameOnlySql } = require('./account-visibility');
+
+// listScoutingNameOnly({ limit, pool }) — the name-only tier, alphabetical by
+// login, bounded by the same `limit` the ranked tier takes.
+async function listScoutingNameOnly({ limit, pool }) {
+  const { rows } = await pool.query(
+    `SELECT github_login, display_name, avatar_url
+       FROM platform_identity_accounts
+      WHERE ${scoutingNameOnlySql()}
+      ORDER BY lower(github_login), github_login
+      LIMIT $1`,
+    [limit],
+  );
+  return rows.map((r) => ({
+    github_login: r.github_login ?? null,
+    display_name: r.display_name ?? null,
+    avatar_url: r.avatar_url ?? null,
+  }));
+}
+
+module.exports = { listScoutingNameOnly };

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

@@ -0,0 +1,68 @@
+// 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.
+//
+// Run standalone: node modules/platform-identity/tests/activity-snapshots.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { recordActivitySnapshot } = require('../activity-snapshots.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  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 = []) {
+  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 };
+    },
+  };
+}
+
+console.log('recordActivitySnapshot (community spec D2, task 1002977):');
+
+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]);
+  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);
+  assert.equal(out, null);
+});
+
+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]);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

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

@@ -596,6 +596,27 @@ await ta('upsertActivity keeps a legitimate core rank key', async () => {
   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]);
+});
+
+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' }] };
+    },
+  };
+  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');
+});
+
 await ta('getMembership reads one (client, builder) row — the rollup membership requirement', async () => {
   const row = { id: '9', client_id: 'c1', github_id: '42', membership_kind: 'member', signin_verified_at: 'T' };
   const pool = mockPool([{ rows: [row] }]);

package/modules/public-landing/public/projects-floor.states.json

@@ -1,5 +1,5 @@
 {
-  "_": "The all-null floor card (task 1003301) on the hub's own catalog (task 1003345): the same page, the same stub, the catalog aliased to featured-hub.json — the landing's three plus Tidewater, a null row nobody owns. Demo, the landing catalog's floor row, is owned by the signed-in stub, and an owned orb's plain click opens its manage view, never its card. Since task 1003352 it also carries the card BACKDROP state: featured-hub gives Example World a card_backdrop, so the owner's plate can be seen standing in front of the project's own picture. Rendered by name: node modules/ui-design/kit/render.js --states public-landing/projects-floor.states.json",
+  "_": "The all-null floor card (task 1003301) on the hub's own catalog (task 1003345): the same page, the same stub, the catalog aliased to featured-hub.json — the landing's three plus Tidewater, a null row nobody owns. Demo, the landing catalog's floor row, is owned by the signed-in stub, and an owned orb's plain click opens its manage view, never its card. Since task 1003352 it also carries the card BACKDROP state: featured-hub gives Example World a card_backdrop, so the owner's plate can be seen standing in front of the project's own picture. Tidewater's null relationship is also the ONLY fixture row the signed-in stub neither owns nor builds on, which is exactly what the Apply button needs (R10, task 1002286) — card-floor is its one rendered state. Rendered by name: node modules/ui-design/kit/render.js --states public-landing/projects-floor.states.json",
   "page": "/projects",
   "surface": "public-landing",
   "modes": [
@@ -55,7 +55,14 @@
         "visible": [
           "#cardOpen",
           "#cardRuns",
-          "#cardListed"
+          "#cardListed",
+          "#cardApply"
+        ],
+        "text": [
+          [
+            "#cardApply",
+            "Apply to join"
+          ]
         ]
       }
     },