@bongos/core 1.19.1019 → 1.19.1020

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.1019",
+  "version": "1.19.1020",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.1019",
+      "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.1019",
+  "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/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.1019'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1020'; // 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');