@bongos/core 1.19.417 → 1.19.419

package/modules/platform-identity/connections.js

@@ -0,0 +1,490 @@
+// modules/platform-identity/connections.js — the connection graph domain
+// (task 1002295 / goal 1000045 criterion C6; ADR 0202, which this implements).
+//
+// WHAT LIVES HERE: the request/accept/decline/cancel/remove lifecycle over
+// platform_identity_connections, the two own-scope list reads (my connections,
+// my inbox+outbox), and the BOUNDED degree-of-separation query behind a
+// profile's "2nd" label. Every rule the ADR made load-bearing is enforced HERE,
+// next to the data, so no route can forget one:
+//
+//   * a decline is SILENT and opens a 90-day cooldown in which a re-ask is
+//     SWALLOWED — nothing written, and the caller gets the same answer a real
+//     create gets (ADR 0202 D2; ADR 0194 D3 applied to a person);
+//   * a pending request EXPIRES at 30 days read-time, and the write path
+//     resolves an expired row of the pair in the SAME statement that inserts the
+//     new one — now() cannot live in an index predicate, so a stale pending row
+//     would otherwise keep the partial unique index locked forever;
+//   * REMOVE hard-deletes; 'rejected' is kept because it still does work;
+//   * degree expansion is CAPPED (FANOUT_1, FANOUT_2, DEGREE_MAX) with a
+//     deterministic frontier order, and past the caps the label is null — "out
+//     of network", never a number the query did not establish (ADR 0202 D3);
+//   * every count returned is the LENGTH OF THE ARRAY the viewer may see. No
+//     raw count beside a filtered list — that is a leak by subtraction
+//     (ADR 0171 D4 / ADR 0202 D4).
+//
+// WHOSE GRAPH. Node visibility is viewer-relative by design (ADR 0202 title):
+// the viewer's OWN connections floor on profile_state='active' alone — a private
+// account that accepted you appears in your own-scope list (D4 §2) — while every
+// DEEPER hop floors on the full public predicate in account-visibility.js. So a
+// bridge the viewer may not see yields `null`, not "3rd", and two viewers
+// legitimately seeing different labels for the same target is the model working.
+//
+// NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank, credit, admission or
+// permission path reads a connection; accepting one changes nobody's access.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const api = require('../../src/module-api');
+const { accountVisibleSql, accountActiveSql } = require('./account-visibility');
+
+const { pool: defaultPool } = api;
+
+// ---------------------------------------------------------------------------
+// The constants ADR 0202 D2/D3 named. Exported rather than spelled inline so a
+// route, a test and a doc read the same number.
+// ---------------------------------------------------------------------------
+
+// The lifecycle vocabulary (mirrors the migration's CHECK — the two must not drift).
+const CONNECTION_STATUSES = ['pending', 'accepted', 'rejected', 'cancelled', 'expired'];
+
+// A pending request is gone at 30 days, computed at read/write time — the
+// privacy spec's D4 constant and mechanism, no sweeper.
+const REQUEST_EXPIRY_DAYS = 30;
+
+// A decline closes the door for 90 days. Inside it, a re-ask from the SAME
+// requester is swallowed: nothing written, and the response is the one a real
+// create returns, because a 409 saying "declined" would disclose exactly what
+// the silence protects.
+const DECLINE_COOLDOWN_DAYS = 90;
+
+// The optional one-line "why I'm asking" on a request. Bio-sized (the P02
+// precedent) — long enough to be a sentence, short enough not to be a message
+// channel, which connections deliberately are not.
+const NOTE_MAX_CHARS = 280;
+
+// Bounded expansion (D3). Past DEGREE_MAX hops, or past a fan-out cap, the label
+// is null. FANOUT_1 bounds a single account's 1-hop; FANOUT_2 bounds the 2-hop
+// frontier the 3rd-degree test intersects against.
+const DEGREE_MAX = 3;
+const FANOUT_1 = 500;
+const FANOUT_2 = 5000;
+
+// What a counterparty row carries: exactly what a name in a list needs (ADR 0202
+// Deferred — "handle, display name, avatar"). github_id stays internal, and
+// github_login is deliberately absent: a private account that connected with you
+// did not thereby publish its GitHub identity to you.
+const COUNTERPARTY_COLUMNS = 'pa.handle, pa.display_name, pa.avatar_url';
+
+// ---------------------------------------------------------------------------
+// The 1-hop, written once
+// ---------------------------------------------------------------------------
+
+// The accepted-neighbour set of ONE account, as a SQL fragment over the two
+// directional indexes (never `pair_lo = x OR pair_hi = x`, which cannot use
+// either). `param` is the $n placeholder holding that account's github_id.
+// Written once so no caller invents a direction-aware WHERE of its own — the
+// symmetry of an accepted edge is a property of the schema, not of a route.
+function neighboursSql(param) {
+  if (!/^\$\d+$/.test(String(param))) {
+    throw new Error('neighboursSql: param must be a $n placeholder');
+  }
+  return `
+    SELECT addressee_github_id AS gid FROM platform_identity_connections
+     WHERE requester_github_id = ${param}::bigint AND status = 'accepted'
+    UNION
+    SELECT requester_github_id AS gid FROM platform_identity_connections
+     WHERE addressee_github_id = ${param}::bigint AND status = 'accepted'`;
+}
+
+// The same expansion from a SET of accounts (the 2-hop frontier). `cte` is the
+// name of a CTE with one `gid` column.
+function frontierSql(cte) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(cte))) {
+    throw new Error('frontierSql: cte must be a bare SQL identifier');
+  }
+  return `
+    SELECT c.addressee_github_id AS gid
+      FROM platform_identity_connections c
+      JOIN ${cte} s ON c.requester_github_id = s.gid
+     WHERE c.status = 'accepted'
+    UNION
+    SELECT c.requester_github_id AS gid
+      FROM platform_identity_connections c
+      JOIN ${cte} s ON c.addressee_github_id = s.gid
+     WHERE c.status = 'accepted'`;
+}
+
+// ---------------------------------------------------------------------------
+// Addressing: handle → account
+// ---------------------------------------------------------------------------
+
+// Resolve a handle to the row the visibility predicates need. Matches the
+// current handle first, then the single-slot previous_handle (P01's rename
+// window) — an ACTION endpoint follows a rename rather than answering 301, so a
+// stale "Connect" link on a page still works. Returns null for an unknown
+// handle; the CALLER decides visibility, because the answer is viewer-relative.
+async function findAccountByHandle(handle, { pool = defaultPool } = {}) {
+  const norm = String(handle ?? '').trim().toLowerCase();
+  if (!/^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/.test(norm)) return null;
+  const { rows } = await pool.query(
+    `SELECT github_id, handle, display_name, avatar_url, profile_state, account_visibility
+       FROM platform_identity_accounts
+      WHERE lower(handle) = $1 OR lower(previous_handle) = $1
+      ORDER BY (lower(handle) = $1) DESC
+      LIMIT 1`,
+    [norm],
+  );
+  return rows[0] || null;
+}
+
+// Is this account already an ACCEPTED connection of the viewer? The other half
+// of viewer-relative visibility: a private account you are connected to is
+// addressable to YOU (ADR 0202 D4 §2) and to nobody else.
+async function isConnectedTo(viewerGithubId, targetGithubId, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `SELECT 1 FROM platform_identity_connections
+      WHERE status = 'accepted'
+        AND pair_lo = LEAST($1::bigint, $2::bigint)
+        AND pair_hi = GREATEST($1::bigint, $2::bigint)
+      LIMIT 1`,
+    [viewerGithubId, targetGithubId],
+  );
+  return rowCount > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Write: request
+// ---------------------------------------------------------------------------
+
+// Send a connection request. ONE statement, and the shape is load-bearing:
+//
+//   `expired`  resolves any timed-out pending row of this pair — referenced by
+//              the main query through `guard` so the executor must drain it
+//              BEFORE the INSERT is attempted (an UNREFERENCED data-modifying
+//              CTE runs in ExecPostprocessPlan, i.e. AFTER the insert, which
+//              would hit the very unique index the expiry exists to release);
+//   the cooldown NOT EXISTS inserts zero rows inside the 90-day window, which is
+//              how a swallowed re-ask writes nothing while still answering yes.
+//
+// Returns { outcome: 'created' | 'swallowed' | 'already_open' }. The ROUTE must
+// answer 'created' and 'swallowed' identically — that is the whole point.
+//
+// WHAT THE SILENCE DOES NOT COVER, stated rather than implied: a swallowed ask
+// writes nothing, so it never appears in the requester's own outbox, while a real
+// one does within milliseconds. The RESPONSE reveals nothing (D2 §2); the absence
+// afterwards is observable. ADR 0202's own Consequences accept exactly this — "a
+// builder can send the same request twice a year and never learn why nothing
+// happens" — and the alternative, writing a decoy row, would be a lie in the
+// database to protect a lie in the API. See ADR 0207.
+async function requestConnection(
+  { requesterGithubId, addresseeGithubId, note = null },
+  { pool = defaultPool } = {},
+) {
+  const sql = `
+    WITH expired AS (
+      UPDATE platform_identity_connections c
+         SET status = 'expired', resolved_at = now(), updated_at = now()
+       WHERE c.pair_lo = LEAST($1::bigint, $2::bigint)
+         AND c.pair_hi = GREATEST($1::bigint, $2::bigint)
+         AND c.status = 'pending'
+         AND c.created_at <= now() - make_interval(days => $3::int)
+      RETURNING c.id
+    ),
+    guard AS (SELECT count(*)::int AS expired_count FROM expired)
+    INSERT INTO platform_identity_connections (requester_github_id, addressee_github_id, note)
+    SELECT $1::bigint, $2::bigint, $5::text
+      FROM guard
+     WHERE NOT EXISTS (
+       SELECT 1 FROM platform_identity_connections c
+        WHERE c.pair_lo = LEAST($1::bigint, $2::bigint)
+          AND c.pair_hi = GREATEST($1::bigint, $2::bigint)
+          AND c.status = 'rejected'
+          AND c.requester_github_id = $1::bigint
+          AND c.resolved_at > now() - make_interval(days => $4::int)
+     )
+    RETURNING id`;
+  try {
+    const { rowCount, rows } = await pool.query(sql, [
+      requesterGithubId, addresseeGithubId,
+      REQUEST_EXPIRY_DAYS, DECLINE_COOLDOWN_DAYS, note,
+    ]);
+    return rowCount > 0
+      ? { outcome: 'created', id: String(rows[0].id) }
+      : { outcome: 'swallowed' };
+  } catch (err) {
+    // 23505 = the partial unique index over (pending, accepted): a request or a
+    // connection is already open for this pair. Safe to name — both cases are
+    // already visible in the caller's OWN scope, so it discloses nothing the
+    // caller cannot read anyway.
+    if (err && err.code === '23505') return { outcome: 'already_open' };
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Write: resolve — accept, decline, remove/cancel
+// ---------------------------------------------------------------------------
+
+// Accept a pending request. The addressee ONLY, in one statement, so an
+// 'accepted' row can never exist without being readable as a connection.
+// rowCount 0 covers every refusal — not yours, not pending, expired — and the
+// route answers all of them 404, so a connection id cannot be probed.
+async function acceptConnection({ id, githubId }, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `UPDATE platform_identity_connections
+        SET status = 'accepted', resolved_at = now(), updated_at = now()
+      WHERE id = $1 AND addressee_github_id = $2::bigint AND status = 'pending'
+        AND created_at > now() - make_interval(days => $3::int)
+      RETURNING id`,
+    [id, githubId, REQUEST_EXPIRY_DAYS],
+  );
+  return rowCount > 0;
+}
+
+// Decline. The addressee ONLY. The requester is never told (D2 §1); the row is
+// kept because 'rejected' IS the 90-day cooldown, not merely an audit trail.
+async function declineConnection({ id, githubId }, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `UPDATE platform_identity_connections
+        SET status = 'rejected', resolved_at = now(), updated_at = now()
+      WHERE id = $1 AND addressee_github_id = $2::bigint AND status = 'pending'
+        AND created_at > now() - make_interval(days => $3::int)
+      RETURNING id`,
+    [id, githubId, REQUEST_EXPIRY_DAYS],
+  );
+  return rowCount > 0;
+}
+
+// Remove an accepted connection (either side — it is consensual data about two
+// people, so either may withdraw) or cancel a pending one (the requester only;
+// an addressee ending a pending row is a DECLINE and must go through that path,
+// which is what arms the cooldown). One statement, two mutually-exclusive
+// branches keyed on status. Remove HARD-DELETES: a tombstone saying "A removed
+// B" is data neither consented to keep and no read path uses.
+// Returns 'removed' | 'cancelled' | null (nothing matched → the route 404s).
+async function removeConnection({ id, githubId }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `WITH removed AS (
+       DELETE FROM platform_identity_connections
+        WHERE id = $1 AND status = 'accepted'
+          AND (requester_github_id = $2::bigint OR addressee_github_id = $2::bigint)
+       RETURNING 'removed'::text AS outcome
+     ),
+     cancelled AS (
+       UPDATE platform_identity_connections
+          SET status = 'cancelled', resolved_at = now(), updated_at = now()
+        WHERE id = $1 AND status = 'pending' AND requester_github_id = $2::bigint
+        RETURNING 'cancelled'::text AS outcome
+     )
+     SELECT outcome FROM removed UNION ALL SELECT outcome FROM cancelled`,
+    [id, githubId],
+  );
+  return rows[0] ? rows[0].outcome : null;
+}
+
+// ---------------------------------------------------------------------------
+// Read: the two own-scope lists
+// ---------------------------------------------------------------------------
+
+// The caller's accepted connections. OWN SCOPE: the floor is profile_state
+// alone, because a private account that connected with you appears in your list
+// and in theirs (D4 §2) — and in no public list, which is why this read has no
+// public twin. The returned `count` is the array's own length by construction
+// (the leak-by-subtraction rule); there is no hidden remainder.
+async function listConnections({ githubId, limit = FANOUT_1, offset = 0 }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `WITH edge AS (
+       SELECT id, addressee_github_id AS gid, resolved_at
+         FROM platform_identity_connections
+        WHERE requester_github_id = $1::bigint AND status = 'accepted'
+       UNION ALL
+       SELECT id, requester_github_id AS gid, resolved_at
+         FROM platform_identity_connections
+        WHERE addressee_github_id = $1::bigint AND status = 'accepted'
+     )
+     SELECT e.id::text AS id, e.resolved_at AS connected_at, ${COUNTERPARTY_COLUMNS}
+       FROM edge e
+       JOIN platform_identity_accounts pa ON pa.github_id = e.gid
+      WHERE ${accountActiveSql('pa')}
+      ORDER BY e.resolved_at DESC NULLS LAST, e.id DESC
+      LIMIT $2 OFFSET $3`,
+    [githubId, Math.min(Number(limit) || FANOUT_1, FANOUT_1), Math.max(0, Number(offset) || 0)],
+  );
+  return rows;
+}
+
+// The caller's inbox and outbox: pending, unexpired requests in both directions.
+// The counterparty floors on profile_state only — an incoming request must name
+// who is asking or it cannot be decided, and D4 §2 lets a private account send.
+//
+// Each direction carries its OWN limit: a shared cap applied before the split
+// would let a busy outbox push every incoming request out of the response, and
+// an empty inbox that is really a truncation is the worst kind of wrong answer.
+//
+// `seen_at` rides the INCOMING rows only and is stripped from the outbox — a
+// decline is silent, and so is a read (D2 §1): a requester who could watch
+// seen_at appear would learn the addressee is deliberating. The stamp is then
+// written back for exactly the rows this call rendered, so it means "delivered",
+// not "your inbox was polled".
+async function listRequests({ githubId, limit = FANOUT_1 }, { pool = defaultPool } = {}) {
+  const cap = Math.min(Number(limit) || FANOUT_1, FANOUT_1);
+  const { rows } = await pool.query(
+    `WITH mine AS (
+       (SELECT c.id, c.note, c.created_at, c.seen_at, true AS incoming,
+               c.requester_github_id AS other
+          FROM platform_identity_connections c
+         WHERE c.addressee_github_id = $1::bigint AND c.status = 'pending'
+           AND c.created_at > now() - make_interval(days => $2::int)
+         ORDER BY c.created_at DESC, c.id DESC
+         LIMIT $3)
+       UNION ALL
+       (SELECT c.id, c.note, c.created_at, c.seen_at, false AS incoming,
+               c.addressee_github_id AS other
+          FROM platform_identity_connections c
+         WHERE c.requester_github_id = $1::bigint AND c.status = 'pending'
+           AND c.created_at > now() - make_interval(days => $2::int)
+         ORDER BY c.created_at DESC, c.id DESC
+         LIMIT $3)
+     )
+     SELECT m.id::text AS id, m.note, m.created_at, m.seen_at, m.incoming, ${COUNTERPARTY_COLUMNS}
+       FROM mine m
+       JOIN platform_identity_accounts pa ON pa.github_id = m.other
+      WHERE ${accountActiveSql('pa')}
+      ORDER BY m.created_at DESC, m.id DESC`,
+    [githubId, REQUEST_EXPIRY_DAYS, cap],
+  );
+  const incoming = rows.filter((r) => r.incoming).map(({ incoming, ...r }) => r);
+  const outgoing = rows.filter((r) => !r.incoming).map(({ incoming, seen_at, ...r }) => r);
+  const unseen = incoming.filter((r) => !r.seen_at).map((r) => r.id);
+  if (unseen.length) {
+    await pool.query(
+      `UPDATE platform_identity_connections
+          SET seen_at = now(), updated_at = now()
+        WHERE id = ANY($1::bigint[]) AND addressee_github_id = $2::bigint AND seen_at IS NULL`,
+      [unseen, githubId],
+    );
+  }
+  return { incoming, outgoing };
+}
+
+// ---------------------------------------------------------------------------
+// Read: the bounded degree label
+// ---------------------------------------------------------------------------
+
+// degreeBetween(viewer, target) → { degree: 0|1|2|3|null, mutuals: [], truncated }
+//
+// Bounded expansion FROM THE VIEWER, staged exactly as ADR 0202 D3 describes,
+// because the stages have different costs and most calls stop at the first:
+//
+//   near  — one statement: is the target in V's 1-hop (1st), and what is the
+//           intersection of V's and T's 1-hops (2nd, and the mutual list for
+//           free). Two index range scans and a hash intersect.
+//   far   — only when `near` found nothing: V's 1-hop (cap FANOUT_1) expanded to
+//           a 2-hop frontier (cap FANOUT_2) and intersected with T's 1-hop.
+//
+// Deliberate departure from the ADR's "recursive CTE" wording, same semantics:
+// a recursive term cannot carry a PER-LEVEL fan-out cap or a deterministic
+// per-level truncation order, which are the two properties D3 actually decided.
+// Level-wise CTEs express both; `ORDER BY gid LIMIT n` makes a truncation
+// reproducible rather than a different answer each call.
+//
+// Past the caps or past DEGREE_MAX the answer is null — "out of network", never
+// a number the query did not establish. `truncated` says a cap bit, so the UI
+// can be honest about it; it describes the VIEWER'S OWN graph size and so
+// discloses nothing about anyone else.
+//
+// TWO HONEST LIMITS (ADR 0207). (a) The TARGET's 1-hop is capped too, and that
+// truncation is deliberately NOT reported: `truncated: true` on it would leak one
+// bit about a third party's degree, which is a worse trade than an occasional
+// null. (b) The QUERY COUNT is constant, and so is the OUTPUT size — but the
+// frontier's WORK is O(sum of degree over v1), because ORDER BY … LIMIT must
+// materialise the frontier before it truncates. At hub scale that is a few index
+// scans; the revisit trigger is a measured p95, not a guess.
+async function degreeBetween(viewerGithubId, targetGithubId, { pool = defaultPool } = {}) {
+  if (String(viewerGithubId) === String(targetGithubId)) {
+    return { degree: 0, mutuals: [], truncated: false };
+  }
+
+  const near = 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 $3
+     ),
+     t1 AS (
+       SELECT r.gid FROM (${neighboursSql('$2')}) r ORDER BY r.gid LIMIT $3
+     )
+     SELECT
+       EXISTS (SELECT 1 FROM platform_identity_connections
+                WHERE status = 'accepted'
+                  AND pair_lo = LEAST($1::bigint, $2::bigint)
+                  AND pair_hi = GREATEST($1::bigint, $2::bigint)) AS is_first,
+       (SELECT count(*)::int FROM v1) AS v1_count,
+       COALESCE((
+         SELECT json_agg(json_build_object(
+                  'handle', pa.handle,
+                  'display_name', pa.display_name,
+                  'avatar_url', pa.avatar_url) ORDER BY pa.github_id)
+           FROM v1
+           JOIN t1 ON t1.gid = v1.gid
+           JOIN platform_identity_accounts pa ON pa.github_id = v1.gid
+       ), '[]'::json) AS mutuals`,
+    [viewerGithubId, targetGithubId, FANOUT_1],
+  );
+  const n = near.rows[0] || {};
+  // Every mutual is one of V's OWN connections, so V is entitled to all of them
+  // and the array is complete up to FANOUT_1 — which is why the count may be its
+  // length rather than a separate number.
+  const mutuals = Array.isArray(n.mutuals) ? n.mutuals : [];
+  const v1Truncated = (n.v1_count || 0) >= FANOUT_1;
+
+  if (n.is_first) return { degree: 1, mutuals, truncated: v1Truncated };
+  if (mutuals.length > 0) return { degree: 2, mutuals, truncated: v1Truncated };
+
+  const far = 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 $3
+     ),
+     v2 AS (
+       SELECT f.gid FROM (${frontierSql('v1')}) f
+         JOIN platform_identity_accounts pa ON pa.github_id = f.gid
+        WHERE ${accountVisibleSql('pa')}
+          AND f.gid <> $1::bigint
+          AND f.gid NOT IN (SELECT gid FROM v1)
+        ORDER BY f.gid LIMIT $4
+     ),
+     t1 AS (
+       SELECT r.gid FROM (${neighboursSql('$2')}) r ORDER BY r.gid LIMIT $3
+     )
+     SELECT EXISTS (SELECT 1 FROM v2 JOIN t1 ON t1.gid = v2.gid) AS is_third,
+            (SELECT count(*)::int FROM v2) AS v2_count`,
+    [viewerGithubId, targetGithubId, FANOUT_1, FANOUT_2],
+  );
+  const f = far.rows[0] || {};
+  const truncated = v1Truncated || (f.v2_count || 0) >= FANOUT_2;
+  return { degree: f.is_third ? DEGREE_MAX : null, mutuals, truncated };
+}
+
+module.exports = {
+  CONNECTION_STATUSES,
+  REQUEST_EXPIRY_DAYS,
+  DECLINE_COOLDOWN_DAYS,
+  NOTE_MAX_CHARS,
+  DEGREE_MAX,
+  FANOUT_1,
+  FANOUT_2,
+  findAccountByHandle,
+  isConnectedTo,
+  requestConnection,
+  acceptConnection,
+  declineConnection,
+  removeConnection,
+  listConnections,
+  listRequests,
+  degreeBetween,
+};

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

@@ -0,0 +1,78 @@
+-- platform_identity_015_connections.sql — the connection graph (task 1002295 /
+-- goal 1000045 criterion C6; ADR 0202 D1, whose migration sketch this is).
+--
+-- WHAT THIS IS. One directed row per relationship — the REQUEST, not the edge.
+-- requester/addressee are kept because the inbox, the cancel path and the
+-- 90-day decline cooldown all need to know who asked; the unordered pair is
+-- GENERATED from LEAST/GREATEST so A→B and B→A collide on one index instead of
+-- both being accepted. Reads are symmetric (the module unions both directions);
+-- no route writes a direction-aware WHERE of its own.
+--
+-- WHY GENERATED + A PARTIAL UNIQUE INDEX rather than a route check: a duplicate
+-- request and a simultaneous reciprocal request then become DATABASE errors, not
+-- a race two handlers have to remember to lose. The index covers only the OPEN
+-- statuses, so resolved rows stay as the audit trail and never block a later ask
+-- (the goal_membership_requests precedent, core_188).
+--
+-- WHY NO TOMBSTONE ON REMOVE (ADR 0202 D2): removing an accepted connection
+-- HARD-DELETES the row. "A removed B" is data neither party consented to keep
+-- and no read path uses. 'rejected' is kept because it still does work — it is
+-- the cooldown — which is exactly why the asymmetry is not an inconsistency.
+--
+-- NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank check, admission gate
+-- or credit path reads this table; accepting a connection changes nobody's rank,
+-- credits, or access to any project. It is descriptive social data only.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). Forward-safe: CREATE
+-- only, so the previous code release still runs against this schema. Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_connections (
+  id                   bigserial PRIMARY KEY,
+  requester_github_id  bigint NOT NULL,
+  addressee_github_id  bigint NOT NULL,
+  -- The unordered pair, derived — never written by a caller, so A→B and B→A
+  -- collide on the index below instead of both being accepted.
+  pair_lo bigint GENERATED ALWAYS AS (LEAST(requester_github_id, addressee_github_id)) STORED,
+  pair_hi bigint GENERATED ALWAYS AS (GREATEST(requester_github_id, addressee_github_id)) STORED,
+  status  text NOT NULL DEFAULT 'pending'
+            CHECK (status IN ('pending', 'accepted', 'rejected', 'cancelled', 'expired')),
+  -- The note cap lives HERE as well as in the route: requestConnection is an
+  -- exported domain function, and every other invariant in this table is one the
+  -- engine refuses to break rather than one a caller must remember.
+  note        text CONSTRAINT platform_identity_connections_note_len
+                CHECK (note IS NULL OR length(note) <= 280),
+  seen_at     timestamptz,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  resolved_at timestamptz,
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT platform_identity_connections_not_self
+    CHECK (requester_github_id <> addressee_github_id)
+);
+
+-- At most ONE open relationship per pair. Resolved rows stay as the audit trail
+-- and never block a later ask.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_connections_open
+  ON platform_identity_connections (pair_lo, pair_hi)
+  WHERE status IN ('pending', 'accepted');
+
+-- The three reads: my inbox, my outbox, and the 1-hop neighbourhood both the
+-- degree traversal and the suggester expand from.
+CREATE INDEX IF NOT EXISTS platform_identity_connections_addressee
+  ON platform_identity_connections (addressee_github_id, status);
+CREATE INDEX IF NOT EXISTS platform_identity_connections_requester
+  ON platform_identity_connections (requester_github_id, status);
+CREATE INDEX IF NOT EXISTS platform_identity_connections_pair_accepted
+  ON platform_identity_connections (pair_lo, pair_hi) WHERE status = 'accepted';
+
+COMMENT ON TABLE platform_identity_connections IS
+  'Account-to-account connections on the hub (ADR 0202). One DIRECTED request row per relationship; pair_lo/pair_hi are the generated unordered key a partial unique index over (pending, accepted) enforces. Lifecycle pending -> accepted | rejected | cancelled | expired; remove hard-deletes. Descriptive only — never authority (ADR 0016).';
+
+COMMENT ON COLUMN platform_identity_connections.status IS
+  'pending -> accepted (addressee accepted) | rejected (addressee declined — SILENT to the requester, and the 90-day cooldown that swallows a re-ask) | cancelled (requester withdrew) | expired (30 days unanswered, resolved at write time because now() cannot live in an index predicate).';
+
+COMMENT ON COLUMN platform_identity_connections.seen_at IS
+  'Stamped on first inbox render (ADR 0202 D2, the privacy-spec D4 parity item) so a delivered/seen affordance can land later without a schema change. Never exposed to the requester — a decline is silent, and so is a read.';
+
+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"],
+    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections"],
     "migrations": true,
     "pollers": ["code-sweep"]
   },