@bongos/core 1.19.418 → 1.19.420

package/docs/file-map.md

@@ -349,6 +349,7 @@ tests/
 ├── sandbox_stage.mjs             ← (#927, ADR 0046): sandbox-first review gate — box detection, BOX_PREVIEW_HOSTNAME parsing, previewable-surface matching, decideShipGate table, tree-stamp freshness (temp git repo), runShipGate composition with injected fs/exec/prompt.
 ├── session_start_freshness.mjs   ← (#1277, ADR 0067): the SessionStart freshness decision (decideFreshness) — pull ONLY on a clean `main` full clone strictly behind origin/main; warn in every other behind case; skip when up to date.
 ├── own_scope_guard.mjs           ← (task 1003343, goal 1000045 criterion own-scope-held-by-a-test): the OWN-SCOPE structural guard, generalised out of memory_isolation.mjs. An explicit inventory of own-scoped route files; inside them the route's declared PATH decides — a path naming no builder must never read a subject from the request (direct, optional-chained, destructured, aliased, computed-key or header), a path that DOES name one needs a per-route exemption whose gate the guard verifies is present. Repo-wide backstop: any file mounting a `/me` route must be in the inventory. Source-grepping, so it runs in the DB-free `unit` lane.
+├── account_existence_rate_limit.mjs ← (task 1003339, goal 1000045, ADR 0209): the two PUBLIC account-existence probes (onboarding GET /access-requests/status + core GET /auth/web/admission-status) share ONE per-IP budget. Counts to the limit on each route, proves the budget is shared in both directions and when alternated, moves Date.now to prove the window slides on the real mounted route, and proves a refused probe issues no query. DB-free; mutation-checked three ways.
 └── public_task_resolver.mjs      ← (#604): the public `/public/tasks/:id` projection — title/value_summary exposed only for shipped|confirmed; withheld for in-flight so unshipped/security task names can't leak.
 ```
 

package/docs/module-api-changelog.md

@@ -1273,5 +1273,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.416 with no explicit bump. run 33263505319. (task 1002620)
   1.19.418 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.417 with no explicit bump. run 33264139544. (task 1002620)
+  1.19.419 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.418 with no explicit bump. run 33265382684. (task 1002620)
+  1.19.420 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.419 with no explicit bump. run 33266034679. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -263,6 +263,22 @@ function createClient(opts = {}) {
       // GET /closeness/with/{builderId} — rank: any-builder — GET /closeness/with/:builderId
       getClosenessWithBuilderId: (args) => request("GET", "/closeness/with/{builderId}", { hasBody: false }, args),
     },
+    "connections": {
+      // GET /connections — rank: any-builder — GET /connections
+      getConnections: (args) => request("GET", "/connections", { hasBody: false }, args),
+      // POST /connections — rank: any-builder — POST /connections
+      postConnections: (args) => request("POST", "/connections", { hasBody: true }, args),
+      // DELETE /connections/{id} — rank: any-builder — DELETE /connections/:id
+      deleteConnectionsId: (args) => request("DELETE", "/connections/{id}", { hasBody: false }, args),
+      // POST /connections/{id}/accept — rank: any-builder — POST /connections/:id/accept
+      postConnectionsIdAccept: (args) => request("POST", "/connections/{id}/accept", { hasBody: true }, args),
+      // POST /connections/{id}/decline — rank: any-builder — POST /connections/:id/decline
+      postConnectionsIdDecline: (args) => request("POST", "/connections/{id}/decline", { hasBody: true }, args),
+      // GET /connections/degree/{handle} — rank: any-builder — GET /connections/degree/:handle
+      getConnectionsDegreeHandle: (args) => request("GET", "/connections/degree/{handle}", { hasBody: false }, args),
+      // GET /connections/requests — rank: any-builder — GET /connections/requests
+      getConnectionsRequests: (args) => request("GET", "/connections/requests", { hasBody: false }, args),
+    },
     "copyDesk": {
       // POST /copy-desk/flags — rank: any-builder — POST /copy-desk/flags
       postCopyDeskFlags: (args) => request("POST", "/copy-desk/flags", { hasBody: true }, args),
@@ -624,6 +640,8 @@ function createClient(opts = {}) {
       postProvisioningInstances: (args) => request("POST", "/provisioning/instances", { hasBody: true }, args),
       // GET /provisioning/instances/{id} — rank: any-builder — GET /provisioning/instances/:id
       getProvisioningInstancesId: (args) => request("GET", "/provisioning/instances/{id}", { hasBody: false }, args),
+      // PATCH /provisioning/instances/{id}/detail — rank: any-builder — PATCH /provisioning/instances/:id/detail
+      patchProvisioningInstancesIdDetail: (args) => request("PATCH", "/provisioning/instances/{id}/detail", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/domain — rank: any-builder — POST /provisioning/instances/:id/domain
       postProvisioningInstancesIdDomain: (args) => request("POST", "/provisioning/instances/{id}/domain", { hasBody: true }, args),
       // POST /provisioning/instances/{id}/force-teardown — rank: metic+archon — POST /provisioning/instances/:id/force-teardown

package/modules/onboarding/routes/access-requests.js

@@ -28,7 +28,10 @@
 //
 // The global IP rate-limiter (mounted in routes.js before every router) guards
 // the public POST against spam. A partial unique index on lower(github_login)
-// stops one username piling up duplicate open requests.
+// stops one username piling up duplicate open requests. The global limiter
+// meters WRITES only, so the public GET /access-requests/status carries its own
+// per-IP read cap — api.accountExistenceReadRateLimit, shared with core's
+// admission-status twin (task 1003339, ADR 0209).
 
 const express = require('express');
 // Carved into modules/onboarding/ (BV1.R81 / ADR 0093 §1). The auth gates, the
@@ -38,7 +41,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const auth = { requireBuilder: api.requireBuilder, requirePermission: api.requirePermission };
 const { pool } = api;
-const { validateOrRespond, parseId } = api;
+const { validateOrRespond, parseId, accountExistenceReadRateLimit } = api;
 const approvalBroadcast = require('../approval-broadcast');
 const log = api.logger('onboarding');
 
@@ -137,7 +140,17 @@ module.exports = function buildAccessRequestsRouter() {
   // rank: public — a would-be builder is by definition outside the system.
   // Declared BEFORE `GET /access-requests` so the literal `/status` path is matched
   // as its own route (not swallowed as a query on the list route).
-  router.get('/access-requests/status', async (req, res) => {
+  //
+  // RATE-LIMITED (task 1003339 / ADR 0209). Public + unthrottled, this was a
+  // login→membership oracle an attacker could script at line rate to learn who
+  // builds here. accountExistenceReadRateLimit is the doorway's SHARED 120/60s
+  // per-IP budget: core's GET /auth/web/admission-status (the boolean twin of
+  // this answer) mounts the very same instance, so the two cannot be alternated
+  // for double the rate. The limiter runs before the queries, so a refused probe
+  // costs no DB work. Whether the ANSWER should also collapse — so a caller who
+  // is not the subject cannot tell pending/dismissed/none apart — is the owner's
+  // call and is filed as a blocker, not decided here.
+  router.get('/access-requests/status', accountExistenceReadRateLimit, async (req, res) => {
     const login = normalizeLogin(req.query.github_login);
     if (!GITHUB_LOGIN_RE.test(login)) {
       return res.fail('bad_github_login', { status: 400, message: 'That does not look like a GitHub username.' });

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

@@ -0,0 +1,58 @@
+// modules/platform-identity/account-visibility.js — THE effective-visibility
+// predicate for a platform account, published in both forms so a route and a
+// query cannot drift (ADR 0202 D4; the ADR 0182 `publishableSql` precedent).
+//
+// WHAT IT ANSWERS: "may the world see that this account exists at all?" —
+// profile_state = 'active' (consent: a hub session has touched the account,
+// ADR 0171 D3) AND account_visibility = 'public' (existence: the privacy-spec
+// D1 axis). Both floors, ANDed, in one place.
+//
+// WHY ITS OWN FILE. ADR 0202 D4 requires connections to consume ONE shared
+// reader rather than grow a connections-flavoured variant — "adding a second
+// predicate is the drift ADR 0194 D7 exists to prevent". The reader the ADR
+// names belongs to task 1002967, which has not shipped; platform-identity.js is
+// already at the file-size ratchet. So the definition lands here, alone and
+// tiny, and 1002967 ADOPTS it rather than writing a second one.
+//
+// WHAT IT IS NOT. Not a rollup gate: hide_stats suppresses NUMBERS, not
+// existence, and is applied by the rollup readers (ADR 0171 D2), never here.
+// Not authority: an account being visible confers nothing (ADR 0016).
+//
+// Fail-closed: a missing/absent account row is invisible, never visible
+// (ADR 0192 §6 / ADR 0194 §2).
+'use strict';
+
+// The JS twin. `account` is any row carrying profile_state + account_visibility;
+// anything falsy (absent row, unreadable account) answers false.
+function isAccountVisible(account) {
+  if (!account) return false;
+  return account.profile_state === 'active' && account.account_visibility === 'public';
+}
+
+// The SAME predicate as a SQL fragment, for the reads that filter in the
+// database. `alias` qualifies the columns for a joined query (e.g.
+// accountVisibleSql('pa')); omit it for an unaliased single-table query.
+function accountVisibleSql(alias) {
+  // The alias is INTERPOLATED, so it is the one thing here that could carry SQL.
+  // Callers pass a literal, but a helper that builds SQL should refuse anything
+  // that is not a bare identifier rather than trust every future caller.
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('accountVisibleSql: alias must be a bare SQL identifier');
+  }
+  const q = alias ? `${alias}.` : '';
+  return `(${q}profile_state = 'active' AND ${q}account_visibility = 'public')`;
+}
+
+// The CONSENT floor on its own — active, without the existence axis. A private
+// account is still a real participant in its OWN scope: ADR 0202 D4 §2 says its
+// connections appear in its own list and in the counterparty's own list, and an
+// incoming request must name who is asking or it cannot be decided. Those
+// own-scope reads floor on this; every PUBLIC read floors on accountVisibleSql.
+function accountActiveSql(alias) {
+  if (alias && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(alias))) {
+    throw new Error('accountActiveSql: alias must be a bare SQL identifier');
+  }
+  return `(${alias ? `${alias}.` : ''}profile_state = 'active')`;
+}
+
+module.exports = { isAccountVisible, accountVisibleSql, accountActiveSql };

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,
+};