@bongos/core 1.19.1018 → 1.19.1020

package/docs/copy-registry.json

@@ -3,9 +3,9 @@
   "generator": "scripts/gds/copy-inventory.js",
   "goal": 1000074,
   "counts": {
-    "strings": 2037,
-    "unique_ids": 1738,
-    "certain": 2037,
+    "strings": 2038,
+    "unique_ids": 1739,
+    "certain": 2038,
     "heuristic": 0,
     "duplicate_ids": 212
   },
@@ -13,7 +13,7 @@
     "builders-hall": {
       "at": "modules/hall-ui/public",
       "files": 102,
-      "strings": 1546
+      "strings": 1547
     },
     "status-dashboard": {
       "at": "modules/status-ui/public",
@@ -1481,8 +1481,8 @@
       "text": "Request sent",
       "occurrences": 2,
       "at": [
-        "modules/hall-ui/public/profile-connections.js:86",
-        "modules/hall-ui/public/profile-connections.js:134"
+        "modules/hall-ui/public/profile-connections.js:95",
+        "modules/hall-ui/public/profile-connections.js:143"
       ]
     },
     {
@@ -3471,6 +3471,15 @@
       "origin": "html-text",
       "confidence": "certain"
     },
+    {
+      "id": "306bc316184d",
+      "surface": "builders-hall",
+      "text": "Builders you may know",
+      "file": "modules/hall-ui/public/profile-connections.js",
+      "line": 158,
+      "origin": "js-markup",
+      "confidence": "certain"
+    },
     {
       "id": "60b248791dc3",
       "surface": "builders-hall",
@@ -9542,7 +9551,7 @@
       "surface": "builders-hall",
       "text": "Request sent",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 86,
+      "line": 95,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -9551,7 +9560,7 @@
       "surface": "builders-hall",
       "text": "Request sent",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 134,
+      "line": 143,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10280,7 +10289,7 @@
       "surface": "builders-hall",
       "text": "Sign in to the platform once to activate your profile before connecting.",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 220,
+      "line": 253,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -10442,7 +10451,7 @@
       "surface": "builders-hall",
       "text": "Something went wrong. Try again.",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 275,
+      "line": 319,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -10856,7 +10865,7 @@
       "surface": "builders-hall",
       "text": "That request is no longer available.",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 270,
+      "line": 314,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -11567,7 +11576,7 @@
       "surface": "builders-hall",
       "text": "They have asked to connect.",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 203,
+      "line": 236,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -15320,7 +15329,7 @@
       "surface": "builders-hall",
       "text": "{…} asking to connect",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 136,
+      "line": 145,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -15581,7 +15590,7 @@
       "surface": "builders-hall",
       "text": "{…} you have sent",
       "file": "modules/hall-ui/public/profile-connections.js",
-      "line": 137,
+      "line": 146,
       "origin": "js-markup",
       "confidence": "certain"
     },

package/docs/module-api-changelog.md

@@ -2515,5 +2515,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         only a token and a login — the <redacted> precedent.
   1.19.1018 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.1017 with no explicit bump. run 36083406390. (task 1002620)
+  1.19.1019 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1018 with no explicit bump. run 36084684814. (task 1002620)
+  1.19.1020 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.1019 with no explicit bump. run 36085437258. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/modules-contract.md

@@ -226,6 +226,7 @@ A module calls `api.seams.emit(eventName, payload)` to broadcast. Any module tha
 | Port: `builder-settings` | `builder-settings` (R80) | core `routes/me.js` (`GET /me`) + `cascade-dispatch.js` | `{ getBuilderBehaviorPrefs, describeWandering, describeRender, computeNeeds, skillCeiling }` — the per-builder prefs read surface. The `GET /me` aggregator resolves it for its wandering/render/needs slices; the dormant cascade router for the skill ceiling. Default-on; degrades gracefully when off ([ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1, [02-module-map §2](design/modular-architecture/02-module-map.md)). |
 | Port: `onboarding` | `onboarding` (R81) | the lifecycle (`db.js` claim/ship — transaction-participant `markStage`) + `auth.js` + `routes/me.js`/`builders.js`/`tasks.js`/`claims.js` | `{ getState, shapeForApi, safeMarkStage, markStage, broadcastGraduation, restockForClaim, restockAll, SOURCE_TAG }` — the onboarding state-machine + newcomer-restock surface. The FIRST core→module port the lifecycle ticks inside its own txn (alongside `reward`). Default-on; degrades to best-effort no-ops when off ([ADR 0093](adr/0093-tranche-2-core-carve-sequence.md) §1). |
 | Event: `builder.box-reconcile-needed` | core `db.js` (on rank change / deactivate / auto-graduation) | `dev-box` | `{ builderId, rank, status, actor }` — flags the box for reconciliation. |
+| Event: `builder.secrets-scrub-needed` | core `db.js` (`deactivateBuilder`) | `art-pipeline` (when installed) | `{ builderId, actor }` — task 1003338 / [ADR 0332](adr/0332-offboarding-secret-scrub-semantics.md): best-effort teardown port for a MODULE-owned builder-keyed secret (today: the Gemini BYOK key, `gemini_key_enc`/`last4`/`set_at`). Core does not write those columns directly (ADR 0102) — the module listens and clears its own store. `github_oauth_tokens` (core-owned) is deleted synchronously inside `deactivateBuilder`'s transaction instead, no event needed. |
 
 ---
 

package/modules/hall-ui/public/profile-connections.js

@@ -40,6 +40,15 @@
 // viewer was actually handed — never a total carried beside a filtered list,
 // which is a leak by subtraction (ADR 0171 D4 / ADR 0202 D4).
 //
+// "BUILDERS YOU MAY KNOW" (R21, task 1002297; ADR 0202 D5) renders on YOUR
+// OWN profile only, under your connections — never on someone else's, which
+// is what makes it own-scope: the candidate pool is the session's own
+// frontier. The server already picked the reason; this file renders it
+// verbatim and adds no ranking or filtering of its own. The read is
+// ADDITIVE, never load-bearing — a failed or absent read (an older server,
+// a provisional account) simply omits the section rather than hiding the
+// connections + requests the rest of the own-profile view already has.
+//
 // NOTHING HERE IS AUTHORITY (ADR 0016): a connection grants no rank, no credits
 // and no admission. Nothing rendered here is rollup-derived either, which is
 // why `hide_stats` does not suppress it — hiding your stats hides the numbers
@@ -137,21 +146,45 @@
       + (outgoing.length ? `<h3 class="conn-sub">${escapeHtml(plural(outgoing.length, 'request'))} you have sent</h3><ul class="conn-reqs">${outbox}</ul>` : '');
   }
 
-  // Your own connections + both request queues. Returns false when the hub
-  // routes are absent or the session is gone, so the caller leaves the section
-  // hidden rather than rendering an empty shell.
+  // "Builders you may know" (R21, task 1002297; ADR 0202 D5) — mutual
+  // connections + shared projects, each explained in one line by the server.
+  // Empty when the server has nothing to say, same as every other honest
+  // empty here (no section is better than an empty shell).
+  function suggestionsHtml(suggestions) {
+    if (!suggestions.length) return '';
+    const rows = suggestions.map((s) => `<li class="conn-req">${personHtml(s)}`
+      + `<p class="conn-req__note">${escapeHtml(s.reason)}</p>`
+      + `<span class="conn-req__acts">${suggestConnectHtml(s.handle)}</span></li>`).join('');
+    return `<h3 class="conn-sub">Builders you may know</h3><ul class="conn-reqs">${rows}</ul>`;
+  }
+
+  // A suggestion's own connect button, `data-act="suggest-connect"` rather
+  // than the generic `btn()` helper: the degree-view connect button lives
+  // beside a single `.conn-act` paragraph the click handler replaces by a
+  // page-wide match, and a second one in this list would collide with it.
+  function suggestConnectHtml(handle) {
+    return `<button class="btn-ghost" type="button" data-act="suggest-connect" data-handle="${escapeHtml(handle)}">Connect</button>`;
+  }
+
+  // Your own connections + both request queues + "builders you may know".
+  // Returns false when the hub routes are absent or the session is gone, so
+  // the caller leaves the section hidden rather than rendering an empty
+  // shell.
   async function renderOwn(body) {
-    const [list, reqs] = await Promise.all([
+    const [list, reqs, suggestions] = await Promise.all([
       api.request('GET', `${API}/connections`),
       api.request('GET', `${API}/connections/requests`),
+      api.request('GET', `${API}/connections/suggestions`),
     ]);
     if (!list.ok || !reqs.ok) return false;
     const connections = arr(list.data && list.data.connections);
     const incoming = arr(reqs.data && reqs.data.incoming);
     const outgoing = arr(reqs.data && reqs.data.outgoing);
+    const suggested = suggestions.ok ? arr(suggestions.data && suggestions.data.suggestions) : [];
     body.innerHTML = requestsHtml(incoming, outgoing)
       + `<p class="scroll__lede">${escapeHtml(plural(connections.length, 'connection'))}.</p>`
-      + '<div id="conn-ledger"></div>';
+      + '<div id="conn-ledger"></div>'
+      + suggestionsHtml(suggested);
     const mount = $('#conn-ledger');
     if (mount) {
       const pager = window.OTBKit.makePager('conn', 'profile.connections.perPage');
@@ -264,6 +297,17 @@
         toast(out.message);
         return;
       }
+      if (act === 'suggest-connect') {
+        const out = await connect(el.dataset.handle);
+        toast(out.message);
+        // A full re-render, the ROW_ACTIONS precedent below: on success the
+        // server's own excludedSuggestionIds now covers this handle, so the
+        // refreshed list is the honest way to remove it — a targeted DOM
+        // patch would still show it as "sent" for a person the API may
+        // already be treating as already-open.
+        if (last) await render(last.data, last.selfId);
+        return;
+      }
       const spec = ROW_ACTIONS[act];
       if (!spec) return;
       const res = await spec.call(el.dataset.id);

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

@@ -0,0 +1,219 @@
+// modules/platform-identity/connection-suggestions.js — "Builders you may
+// know" (R21, task 1002297, goal 1000045 criterion C6; ADR 0202 D5, which
+// this implements).
+//
+// THREE NATIVE SIGNALS (D5's table), scored and combined, never a fourth:
+// mutual connections (connections.mutualFrontier, weight 3 × min(mutuals,
+// 10)), shared projects (co-membership on platform_identity_project_-
+// memberships, weight 2 × shared_projects), and recency (max(last_active)
+// inside the last 30 days, weight 1). Ties break on last_active, then
+// github_id, so the list is stable (D5) — a hand-tuned linear sum on
+// purpose, since the requirement is a sentence a human reads, not accuracy.
+//
+// GUILDS ARE A RESERVED SLOT, NOT A SIGNAL (D5's third refusal). This file
+// adds no guild term, no guild query and no guild weight — the scorer below
+// reads only the two signals it has real tables for, and leaves guilds for
+// C7's own wave to add a term for once its tables exist (task 1002300)
+// rather than inventing a signal against a schema nobody has written.
+// Likewise refused, per D5: shared goals (instance-local), Discord, the
+// GitHub follower graph, email, or any address-book import.
+//
+// EVERY CANDIDATE CLEARS accountVisibleSql (D4) — the same floor the whole
+// connections feature uses, so a private or provisional account is never
+// suggested: a suggestion the viewer cannot address would both dead-end the
+// Connect button and name a hidden builder by implication. Anyone the
+// viewer already has an open or in-cooldown-declined row with is excluded
+// silently (connections.excludedSuggestionIds) — no "N more" counter, which
+// would be leak-by-subtraction with a friendlier label (D5).
+'use strict';
+
+const api = require('../../src/module-api');
+const { accountVisibleSql } = require('./account-visibility');
+const { onMapSql } = require('./projects-feed');
+const conn = require('./connections');
+
+const { pool: defaultPool } = api;
+
+// D3: "the same expansion, one level, ranked, LIMIT 20."
+const MAX_SUGGESTIONS = 20;
+// Twice the shown count, so exclusion (pending/cooldown) rarely starves the
+// final list — still a flat, bounded read, never unbounded fan-out.
+const CANDIDATE_POOL_CAP = MAX_SUGGESTIONS * 2;
+// The co-membership scan is bounded from the OTHER side too: a viewer in one
+// very large project must not turn "who else builds here" into an unbounded
+// join. FANOUT_2's order of magnitude (ADR 0202 D3) — generous at today's
+// hub scale, a deliberate cap rather than a guess, same "revisit on a
+// measured p95" posture D3 states for its own caps.
+const MEMBERSHIP_SCAN_CAP = 5000;
+// D5's recency window and weights.
+const RECENT_DAYS = 30;
+const MUTUAL_CAP = 10;
+const WEIGHT_MUTUAL = 3;
+const WEIGHT_SHARED_PROJECT = 2;
+const WEIGHT_RECENCY = 1;
+
+// A membership ADR 0205 D4 would let back a public-facing surface: not
+// merely present, but backed by the hub's own sign-in witness — the SQL
+// twin of membershipBacksRollup (platform-identity.js). A row a federated
+// client wrote for someone who never signed in at the hub must not surface
+// their project association to another builder.
+function membershipBackedSql(alias) {
+  const q = alias ? `${alias}.` : '';
+  return `${q}membership_kind <> 'pending' AND ${q}signin_verified_at IS NOT NULL`;
+}
+
+// Builders who share a real, witnessed project membership with the viewer.
+// `named_project` carries a project's name only where its catalogue row is
+// ON THE MAP AND PUBLIC (the getRollupForBuilder naming rule, task
+// 1003558) — otherwise it is null and the caller falls back to D5's generic
+// reason ("a project you both build on"): the aggregate is not the leak,
+// the name is.
+async function sharedProjectCandidates(viewerGithubId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `WITH mine AS (
+       SELECT DISTINCT client_id FROM platform_identity_project_memberships
+        WHERE github_id = $1::bigint AND ${membershipBackedSql()}
+     ),
+     shared AS (
+       SELECT m.github_id, m.client_id
+         FROM platform_identity_project_memberships m
+         JOIN mine ON mine.client_id = m.client_id
+        WHERE m.github_id <> $1::bigint AND ${membershipBackedSql('m')}
+        ORDER BY m.last_active DESC NULLS LAST, m.github_id ASC
+        LIMIT $3
+     ),
+     named AS (
+       SELECT DISTINCT ON (s.github_id) s.github_id, p.name
+         FROM shared s
+         JOIN platform_identity_sso_clients c ON c.client_id = s.client_id
+         JOIN platform_identity_projects p ON p.origin = c.origin
+        WHERE ${onMapSql('p')} AND p.visibility = 'public'
+        ORDER BY s.github_id, p.name
+     )
+     SELECT s.github_id::text AS github_id, count(DISTINCT s.client_id)::int AS shared_projects,
+            n.name AS named_project
+       FROM shared s
+       JOIN platform_identity_accounts pa ON pa.github_id = s.github_id
+       LEFT JOIN named n ON n.github_id = s.github_id
+      WHERE ${accountVisibleSql('pa')}
+      GROUP BY s.github_id, n.name
+      ORDER BY shared_projects DESC, s.github_id ASC
+      LIMIT $2`,
+    [viewerGithubId, CANDIDATE_POOL_CAP, MEMBERSHIP_SCAN_CAP],
+  );
+  return rows;
+}
+
+// Every candidate's own most-recent project activity, for D5's recency
+// signal — independent of WHICH signal surfaced the candidate.
+async function lastActiveById(githubIds, { pool = defaultPool } = {}) {
+  if (!githubIds.length) return new Map();
+  const { rows } = await pool.query(
+    `SELECT github_id::text AS github_id, max(last_active) AS last_active
+       FROM platform_identity_project_memberships
+      WHERE github_id = ANY($1::bigint[]) AND ${membershipBackedSql()}
+      GROUP BY github_id`,
+    [githubIds],
+  );
+  return new Map(rows.map((r) => [r.github_id, r.last_active]));
+}
+
+// The display identity for a candidate set — handle/display_name/avatar_url,
+// the same whitelist every connections read projects, PLUS hide_stats:
+// never on the wire (stripped below), read only to decide whether this
+// candidate's activity may feed the recency signal. Re-clears
+// accountVisibleSql (defense in depth against a candidate going private
+// between the source query above and this one, inside the same request)
+// rather than trusting the caller's set to still be accurate.
+async function identityById(githubIds, { pool = defaultPool } = {}) {
+  if (!githubIds.length) return new Map();
+  const { rows } = await pool.query(
+    `SELECT pa.github_id::text AS github_id, pa.handle, pa.display_name, pa.avatar_url, pa.hide_stats
+       FROM platform_identity_accounts pa
+      WHERE pa.github_id = ANY($1::bigint[]) AND ${accountVisibleSql('pa')}`,
+    [githubIds],
+  );
+  return new Map(rows.map((r) => [r.github_id, r]));
+}
+
+function mutualReason(n) {
+  return `${n} mutual connection${n === 1 ? '' : 's'}`;
+}
+
+// listConnectionSuggestions({ githubId, pool }) → [{ handle, display_name,
+// avatar_url, reason }], highest score first, ties broken on last_active
+// then github_id (D5), capped at MAX_SUGGESTIONS. `score` is the RANKING,
+// never the RESPONSE: it is never returned, because an ordinal is exactly
+// the kind of number ADR 0202 D4 §3 suppresses under hide_stats, and
+// handing it over would let a caller reconstruct the recency bit that
+// ranking otherwise only implies.
+async function listConnectionSuggestions({ githubId, pool = defaultPool } = {}) {
+  const [mutuals, shared, excluded] = await Promise.all([
+    conn.mutualFrontier(githubId, { pool, resultCap: CANDIDATE_POOL_CAP }),
+    sharedProjectCandidates(githubId, { pool }),
+    conn.excludedSuggestionIds(githubId, { pool }),
+  ]);
+
+  const byId = new Map();
+  const get = (id) => {
+    if (!byId.has(id)) byId.set(id, { mutual_count: 0, shared_projects: 0, named_project: null });
+    return byId.get(id);
+  };
+  for (const row of mutuals) {
+    if (excluded.has(row.github_id)) continue;
+    get(row.github_id).mutual_count = row.mutual_count;
+  }
+  for (const row of shared) {
+    if (excluded.has(row.github_id)) continue;
+    const c = get(row.github_id);
+    c.shared_projects = row.shared_projects;
+    c.named_project = row.named_project;
+  }
+  if (byId.size === 0) return [];
+
+  const ids = [...byId.keys()];
+  const [identities, lastActive] = await Promise.all([
+    identityById(ids, { pool }),
+    lastActiveById(ids, { pool }),
+  ]);
+
+  const cutoff = Date.now() - RECENT_DAYS * 24 * 60 * 60 * 1000;
+  const scored = [];
+  for (const id of ids) {
+    const person = identities.get(id);
+    if (!person) continue; // went private / vanished between reads — never surfaced
+    const c = byId.get(id);
+    // hide_stats suppresses NUMBERS derived from activity, everywhere else
+    // in this module (ADR 0202 D4 §3) — recency is exactly that, so a
+    // hidden candidate's real last_active never reaches the score OR the
+    // tie-break: both would otherwise let a viewer back out the 30-day bit
+    // hide_stats exists to hide.
+    const activity = person.hide_stats ? null : (lastActive.get(id) || null);
+    const mutualScore = WEIGHT_MUTUAL * Math.min(c.mutual_count, MUTUAL_CAP);
+    const projectScore = WEIGHT_SHARED_PROJECT * c.shared_projects;
+    const recent = activity ? new Date(activity).getTime() >= cutoff : false;
+    const score = mutualScore + projectScore + (recent ? WEIGHT_RECENCY : 0);
+    // The reason names the PRIMARY signal — the one that contributed more —
+    // rather than every signal that applied, matching D5's "a sentence a
+    // human reads", not an itemised ledger.
+    const reason = mutualScore >= projectScore && c.mutual_count > 0
+      ? mutualReason(c.mutual_count)
+      : c.named_project
+        ? `You both build on ${c.named_project}`
+        : 'A project you both build on';
+    scored.push({ id, person, score, reason, activity });
+  }
+
+  scored.sort((a, b) => b.score - a.score
+    || new Date(b.activity || 0) - new Date(a.activity || 0)
+    || Number(a.id) - Number(b.id));
+
+  return scored.slice(0, MAX_SUGGESTIONS).map(({ person, reason }) => ({
+    handle: person.handle,
+    display_name: person.display_name,
+    avatar_url: person.avatar_url,
+    reason,
+  }));
+}
+
+module.exports = { listConnectionSuggestions, MAX_SUGGESTIONS };

package/modules/platform-identity/connections.js

@@ -471,6 +471,88 @@ async function degreeBetween(viewerGithubId, targetGithubId, { pool = defaultPoo
   return { degree: f.is_third ? DEGREE_MAX : null, mutuals, truncated };
 }
 
+// ---------------------------------------------------------------------------
+// Read: the 2nd-degree frontier, ranked ("builders you may know", R21, task
+// 1002297; ADR 0202 D3's frontier + D5's mutual-connections signal)
+// ---------------------------------------------------------------------------
+
+// mutualFrontier(viewer) → [{ github_id, mutual_count }] — the viewer's 1-hop
+// expanded one level and grouped by candidate, D3's "2nd-degree frontier …
+// ranked". `via` (which of the viewer's own connections bridges a candidate)
+// is counted, never returned: the mutual COUNT is a suggestion signal, not a
+// disclosure of who bridges it.
+//
+// The viewer's OWN 1-hop floors on accountActiveSql — the own-scope consent
+// floor degreeBetween's `near` query already uses (D4 §2: a private account
+// that connected with the viewer is still real inside the viewer's own
+// scope). The CANDIDATE floors on accountVisibleSql — D5's "filtered per
+// D4": a suggestion the viewer cannot address (private, provisional) is not
+// a suggestion, and surfacing one would name a hidden builder by
+// implication. Self and the viewer's own 1-hop are excluded — a suggestion
+// names someone not already known.
+//
+// The 2-hop EXPANSION is capped too, not just v1 and the output — the same
+// FANOUT_2 bound degreeBetween's `far` query puts on its own 2-hop frontier
+// (D3), so a viewer with FANOUT_1 highly-connected neighbours cannot force
+// an unbounded edges scan (up to FANOUT_1² rows uncapped). `edgeCap`
+// defaults to FANOUT_2 rather than to `resultCap` on purpose: the two bound
+// different things (raw edges scanned vs. candidates returned) and must not
+// be read as one knob wearing two names.
+async function mutualFrontier(viewerGithubId, { pool = defaultPool, fanoutCap = FANOUT_1, resultCap = 40, edgeCap = FANOUT_2 } = {}) {
+  const { rows } = await pool.query(
+    `WITH v1 AS (
+       SELECT r.gid FROM (${neighboursSql('$1')}) r
+         JOIN platform_identity_accounts pa ON pa.github_id = r.gid
+        WHERE ${accountActiveSql('pa')}
+        ORDER BY r.gid LIMIT $2
+     ),
+     edges AS (
+       SELECT gid, via FROM (
+         SELECT c.addressee_github_id AS gid, c.requester_github_id AS via
+           FROM platform_identity_connections c
+           JOIN v1 ON v1.gid = c.requester_github_id
+          WHERE c.status = 'accepted'
+         UNION ALL
+         SELECT c.requester_github_id AS gid, c.addressee_github_id AS via
+           FROM platform_identity_connections c
+           JOIN v1 ON v1.gid = c.addressee_github_id
+          WHERE c.status = 'accepted'
+       ) raw
+       ORDER BY gid, via
+       LIMIT $4
+     )
+     SELECT e.gid::text AS github_id, count(DISTINCT e.via)::int AS mutual_count
+       FROM edges e
+       JOIN platform_identity_accounts pa ON pa.github_id = e.gid
+      WHERE e.gid <> $1::bigint
+        AND e.gid NOT IN (SELECT gid FROM v1)
+        AND ${accountVisibleSql('pa')}
+      GROUP BY e.gid
+      ORDER BY mutual_count DESC, e.gid ASC
+      LIMIT $3`,
+    [viewerGithubId, fanoutCap, resultCap, edgeCap],
+  );
+  return rows;
+}
+
+// The viewer's OWN open or in-cooldown counterparties — every github_id a
+// pending ask, an accepted connection, or a still-cooling decline already
+// names. "Builders you may know" (D5) excludes each of these SILENTLY: a
+// suggestion the viewer cannot act on (already open), or whose addressee
+// just declined (D2's swallowed re-ask), is not a suggestion.
+async function excludedSuggestionIds(viewerGithubId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT DISTINCT (CASE WHEN requester_github_id = $1::bigint THEN addressee_github_id
+                           ELSE requester_github_id END)::text AS github_id
+       FROM platform_identity_connections
+      WHERE (requester_github_id = $1::bigint OR addressee_github_id = $1::bigint)
+        AND (status IN ('pending', 'accepted')
+             OR (status = 'rejected' AND resolved_at > now() - make_interval(days => $2::int)))`,
+    [viewerGithubId, DECLINE_COOLDOWN_DAYS],
+  );
+  return new Set(rows.map((r) => r.github_id));
+}
+
 module.exports = {
   CONNECTION_STATUSES,
   REQUEST_EXPIRY_DAYS,
@@ -488,4 +570,6 @@ module.exports = {
   listConnections,
   listRequests,
   degreeBetween,
+  mutualFrontier,
+  excludedSuggestionIds,
 };

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

@@ -17,6 +17,12 @@
 //   GET    /connections               — my accepted connections. count is the
 //                                       array's own length (no hidden remainder).
 //   GET    /connections/requests      — my inbox + outbox; stamps seen_at.
+//   GET    /connections/suggestions   — "builders you may know" (R21, task
+//                                       1002297; ADR 0202 D5): mutuals + shared
+//                                       projects, ranked and explained. The
+//                                       candidate pool is the SESSION's own
+//                                       frontier, so there is no counterparty
+//                                       parameter to misuse.
 //   GET    /connections/degree/:handle — the viewer-relative label 0|1|2|3|null
 //                                       plus the mutuals it is computed from.
 //                                       An OWN-SCOPE read (D4 §4): this is how a
@@ -40,6 +46,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const conn = require('../connections');
+const suggest = require('../connection-suggestions');
 const { isAccountVisible, isAccountActive } = require('../account-visibility');
 
 const { pool, requireBuilder, validateOrRespond, parsePagination } = api;
@@ -123,6 +130,23 @@ module.exports = function connectionRoutes() {
     }
   });
 
+  // rank: any-builder — "builders you may know" (R21, task 1002297; ADR 0202
+  // D5). Own-scope by construction: the candidate pool is the SESSION's own
+  // frontier, and every candidate already clears the same visibility floor
+  // the rest of the feature does (D4), so nothing here can reveal a hidden
+  // builder. count is the array's own length, same rule as every list above.
+  router.get('/connections/suggestions', requireBuilder, async (req, res) => {
+    try {
+      const me = await actingAccount(req.builder);
+      if (me.fail) return res.fail(...me.fail);
+      const suggestions = await suggest.listConnectionSuggestions({ githubId: me.githubId, pool });
+      res.json({ suggestions, count: suggestions.length });
+    } catch (err) {
+      log.error({ err: err && err.message }, 'GET /connections/suggestions failed');
+      res.fail('connection_suggestions_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: any-builder — the degree label between the CALLER and one handle, plus
   // the mutuals it was computed from (own-scope read, D4 §4). Bounded by
   // construction: degreeBetween caps every level and answers null past the caps.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1018",
+  "version": "1.19.1020",
   "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/bongos/db.js

@@ -605,6 +605,12 @@ async function deactivateBuilder({ builderId, reason, actorBuilderId }) {
         WHERE builder_id = $1 AND revoked_at IS NULL`,
       [builderId]
     );
+    // PRIVACY (task 1003338 / ADR 0332): scrub the stored GitHub OAuth repo
+    // token in the SAME transaction — github_oauth_tokens is core's own table
+    // (not module-owned), so it gets the direct treatment the session revoke
+    // above gets. deleteGithubToken is a plain DELETE; safe to call even when
+    // no row exists.
+    await deleteGithubToken({ builderId, p: client });
     return { updated, activeClaims };
   });
   // Source-access clawback (ADR 0031 §6 / #600): a deactivated builder loses
@@ -616,6 +622,16 @@ async function deactivateBuilder({ builderId, reason, actorBuilderId }) {
   await seams.emitAsync('builder.box-reconcile-needed', {
     builderId, rank: 'xenos', status: 'inactive', actor: `builder-exit:builder#${actorBuilderId}`,
   });
+  // PRIVACY (task 1003338 / ADR 0332): teardown port for a MODULE-owned
+  // builder-keyed secret (today: art-pipeline's Gemini BYOK key,
+  // gemini_key_enc/last4/set_at — CRUD moved out of core under ADR 0102, so
+  // core does not touch those columns directly). Best-effort, same as
+  // box-reconcile-needed above: a module that stores such a secret listens
+  // for this event and clears its own store; on a vanilla instance (no
+  // listener registered) it is a no-op.
+  await seams.emitAsync('builder.secrets-scrub-needed', {
+    builderId, actor: `builder-exit:builder#${actorBuilderId}`,
+  });
   return {
     builder: updated[0],
     claims_released: activeClaims.map((c) => c.task_id),
@@ -646,6 +662,12 @@ async function reactivateBuilder({ builderId, actorBuilderId }) {
     // Rank is intentionally left at whatever it is (xenos after a deactivation):
     // an Archon re-promotes deliberately via PATCH /builders/:id/rank.
     //
+    // Same posture for the secrets deactivateBuilder scrubs (task 1003338 /
+    // ADR 0332): NEITHER the deleted github_oauth_tokens row NOR the
+    // module-owned Gemini BYOK key is restored here, deliberately. A
+    // returning builder re-enters their own key; do not "helpfully" resurrect
+    // a stored credential on reactivation.
+    //
     // REACTIVATION IS THE EXPOSURE (task 1003193). Rank does not move here, but
     // status flipping back to 'active' makes whatever seeded rank-role the builder
     // still holds live again — getActiveBuildersWithRank, builderHoldsRankActive,