@bongos/core 1.19.417 → 1.19.419

package/tests/connections_api.mjs

@@ -0,0 +1,568 @@
+// tests/connections_api.mjs — the connection graph API (R19, task 1002295 /
+// goal 1000045 criterion C6; ADR 0202).
+//
+// WHAT THIS PINS, and why each one is a rule rather than a behaviour:
+//
+//   1. THE LIFECYCLE — request / accept / decline / remove / cancel / list.
+//      Including the two answers ADR 0202 D2 requires to be INDISTINGUISHABLE:
+//      a request that was written and a request swallowed by the 90-day decline
+//      cooldown. If those two responses ever differ by a byte, the silence a
+//      decline is supposed to buy is gone.
+//
+//   2. OWNERSHIP IS IN THE WHERE CLAUSE. A builder cannot act on someone
+//      else's connection, and the proof is not "a 403 happens" — it is that the
+//      acting github_id bound into every write is the SESSION's, never anything
+//      the request carried, and that a non-match answers 404 (a 403 would make
+//      the id space probeable). A hostile body naming another account changes
+//      nothing about the parameters.
+//
+//   3. THE DEGREE QUERY IS BOUNDED — the DoS surface. An unbounded traversal on
+//      a social graph is a denial-of-service primitive, so this asserts the caps
+//      on the SQL THAT ACTUALLY RAN (captured from the pool), not on a source
+//      guess: every level carries ORDER BY … LIMIT $n, the bound values are
+//      FANOUT_1/FANOUT_2, nothing is recursive, and the number of queries is
+//      constant no matter what the graph returns — the expansion stops at
+//      DEGREE_MAX and answers null rather than searching deeper.
+//
+//   4. THE LEAK-BY-SUBTRACTION BAN (ADR 0171 D4 / ADR 0202 D4) — every count in
+//      a response is the length of the array beside it, never a separate total.
+//
+//   5. NOTHING HERE IS AUTHORITY (ADR 0016) — no rank, permission or credit
+//      symbol appears anywhere in the feature.
+//
+// DB-free by construction: a recording fake pool, no Postgres, no network
+// beyond loopback. Runs in the unit gate that actually executes on a PR — a
+// proof parked in the integration lane would never run (task 1002282).
+//
+// Run:  node tests/connections_api.mjs
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const MIGRATION = readFileSync(
+  join(ROOT, 'modules/platform-identity/migrations/platform_identity_015_connections.sql'), 'utf8');
+const DOMAIN_SRC = readFileSync(join(ROOT, 'modules/platform-identity/connections.js'), 'utf8');
+const ROUTE_SRC = readFileSync(join(ROOT, 'modules/platform-identity/routes/connections.js'), 'utf8');
+
+// ---- the recording fake pool ----------------------------------------------
+//
+// One shared pool object, pinned into module-api below and resolved once at
+// require time, so the route, the domain and each test's queue are the same
+// thing. `calls` is the evidence the bound-parameter assertions read.
+let queued = [];
+let calls = [];
+const pool = {
+  query: async (text, params) => {
+    calls.push({ text: String(text), params: params || [] });
+    const next = queued.shift();
+    if (next instanceof Error) throw next;
+    return next || { rows: [], rowCount: 0 };
+  },
+};
+function expect(...responses) { queued = responses; calls = []; }
+const result = (rows = [], rowCount = null) => ({ rows, rowCount: rowCount ?? rows.length });
+
+// ---- the route over the real domain, with core pinned ----------------------
+
+const ME = { github_id: 4242, github_login: 'octo', display_name: 'Octo', avatar_url: 'https://a.example/o.png' };
+const ADA = 9001;
+
+// The live session the stub hands every route. Mutable so one test can prove a
+// non-numeric principal (a core `system:*` builder) is refused cleanly.
+let session = { ...ME };
+
+const moduleApiPath = require.resolve('../src/module-api.js');
+const helpers = require('../src/bongos/routes/_helpers.js');
+require.cache[moduleApiPath] = {
+  id: moduleApiPath, filename: moduleApiPath, loaded: true,
+  exports: {
+    pool,
+    validateOrRespond: helpers.validateOrRespond,
+    parsePagination: helpers.parsePagination,
+    logger: () => ({ error() {}, warn() {}, info() {} }),
+    // The own-scope stub: a live session, exactly as requireBuilder leaves it.
+    requireBuilder: (req, _res, next) => { req.builder = { ...session }; next(); },
+  },
+};
+const conn = require('../modules/platform-identity/connections.js');
+const buildConnectionRoutes = require('../modules/platform-identity/routes/connections.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/bongos', buildConnectionRoutes());
+const server = app.listen(0, '127.0.0.1');
+await new Promise((r) => server.once('listening', r));
+const port = server.address().port;
+after(() => server.close());
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
+    const req = http.request({
+      host: '127.0.0.1', port, method, path,
+      headers: payload ? { 'content-type': 'application/json', 'content-length': payload.length } : {},
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        let json = null; try { json = JSON.parse(text); } catch { /* non-JSON body */ }
+        resolve({ status: res.statusCode, json, text });
+      });
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+// The first query every route makes is the caller's own account (the
+// profile_state='active' floor, ADR 0202 D4 §1).
+const meActive = () => result([{ github_id: String(ME.github_id), profile_state: 'active', account_visibility: 'public', handle: 'octo' }]);
+const account = (over = {}) => ({
+  github_id: String(ADA), handle: 'ada', display_name: 'Ada', avatar_url: null,
+  profile_state: 'active', account_visibility: 'public', ...over,
+});
+
+// ===========================================================================
+// 1. The stored shape — the rules the database itself refuses to break
+// ===========================================================================
+
+test('migration 015 makes a duplicate and a reciprocal request DATABASE errors, not route bugs', () => {
+  assert.match(MIGRATION, /pair_lo bigint GENERATED ALWAYS AS \(LEAST\(requester_github_id, addressee_github_id\)\) STORED/,
+    'the unordered pair is derived, never written by a caller — A→B and B→A must collide');
+  assert.match(MIGRATION, /pair_hi bigint GENERATED ALWAYS AS \(GREATEST\(requester_github_id, addressee_github_id\)\) STORED/);
+  assert.match(MIGRATION, /CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_connections_open[\s\S]*?\(pair_lo, pair_hi\)[\s\S]*?WHERE status IN \('pending', 'accepted'\)/,
+    'ONE open relationship per pair, and only the OPEN statuses — a resolved row must never block a later ask');
+  assert.match(MIGRATION, /CHECK \(requester_github_id <> addressee_github_id\)/, 'no self-connection');
+  assert.match(MIGRATION, /CHECK \(status IN \('pending', 'accepted', 'rejected', 'cancelled', 'expired'\)\)/,
+    'the five statuses ADR 0202 D2 named — the engine refuses a sixth');
+});
+
+test('the note cap is a database constraint, not just a route rule', () => {
+  const m = MIGRATION.match(/CHECK \(note IS NULL OR length\(note\) <= (\d+)\)/);
+  assert.ok(m, 'requestConnection is an exported domain function — the cap cannot live only in the route');
+  assert.equal(Number(m[1]), conn.NOTE_MAX_CHARS, 'the SQL cap and NOTE_MAX_CHARS must not drift');
+});
+
+test('the migration CHECK and the exported vocabulary cannot drift', () => {
+  const inSql = MIGRATION.match(/CHECK \(status IN \(([^)]*)\)\)/)[1]
+    .split(',').map((s) => s.trim().replace(/'/g, ''));
+  assert.deepEqual(inSql, conn.CONNECTION_STATUSES);
+});
+
+// ===========================================================================
+// 2. The lifecycle
+// ===========================================================================
+
+test('request: a real create answers 201 { status: "pending" } and writes ONE statement', async () => {
+  expect(meActive(), result([account()]), result([{ id: '77' }]));
+  const res = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+  assert.equal(res.status, 201);
+  assert.deepEqual(res.json, { status: 'pending' });
+  assert.equal(calls.length, 3, 'own account, handle lookup, and ONE write');
+  const write = calls[2];
+  assert.match(write.text, /INSERT INTO platform_identity_connections/);
+  assert.deepEqual(write.params.slice(0, 4),
+    [ME.github_id, String(ADA), conn.REQUEST_EXPIRY_DAYS, conn.DECLINE_COOLDOWN_DAYS],
+    'the requester is the SESSION; expiry and cooldown are the ADR constants, bound not interpolated');
+});
+
+test('request: the write resolves an expired row in the SAME statement, and drains it FIRST', () => {
+  expect(); // no queries — this reads the SQL the previous test captured shape-wise
+  const sql = conn.requestConnection.toString();
+  assert.match(sql, /WITH expired AS \(\s*UPDATE platform_identity_connections/,
+    'expiry is resolved in the same statement that inserts (now() cannot live in an index predicate)');
+  assert.match(sql, /guard AS \(SELECT count\(\*\)::int AS expired_count FROM expired\)/);
+  assert.match(sql, /FROM guard/,
+    'the main query MUST reference the modifying CTE: an unreferenced one runs AFTER the insert '
+    + '(ExecPostprocessPlan) and would hit the very unique index the expiry exists to release');
+  assert.match(sql, /status = 'rejected'[\s\S]*?resolved_at > now\(\) - make_interval\(days => \$4::int\)/,
+    'the cooldown is a NOT EXISTS on the same statement — a swallowed re-ask inserts zero rows');
+});
+
+test('request: a re-ask inside the decline cooldown is SWALLOWED and answers IDENTICALLY', async () => {
+  expect(meActive(), result([account()]), result([{ id: '77' }]));
+  const created = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+
+  // Same call, but the insert matched zero rows because the cooldown NOT EXISTS
+  // held — nothing was written.
+  expect(meActive(), result([account()]), result([], 0));
+  const swallowed = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+
+  assert.equal(swallowed.status, created.status);
+  assert.equal(swallowed.text, created.text,
+    'byte-identical, or the requester can difference the two and learn they were declined — '
+    + 'which is exactly what ADR 0202 D2 §1/§2 keep quiet');
+  assert.doesNotMatch(created.text, /\bid\b/, 'a real create returns no id, so a swallowed one has none to fake');
+});
+
+test('request: an already-open pair is a 409 — safe to name, since the caller can already read it', async () => {
+  const dup = Object.assign(new Error('duplicate key'), { code: '23505' });
+  expect(meActive(), result([account()]), dup);
+  const res = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+  assert.equal(res.status, 409);
+  assert.equal(res.json.error.code, 'connection_already_open');
+});
+
+test('request: a PRIVATE stranger answers 404, never 403 — a 403 confirms the handle exists', async () => {
+  expect(meActive(), result([account({ account_visibility: 'private' })]), result([], 0));
+  const res = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+  assert.equal(res.status, 404);
+  assert.equal(res.json.error.code, 'connection_target_not_found');
+  assert.equal(calls.length, 3, 'it never reached the write');
+});
+
+test('request: a provisional account and an unknown handle are the SAME answer as private', async () => {
+  expect(meActive(), result([account({ profile_state: 'provisional' })]));
+  const provisional = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+  expect(meActive(), result([]));
+  const unknown = await call('POST', '/api/bongos/connections', { handle: 'nobody' });
+  assert.equal(provisional.status, 404);
+  assert.equal(unknown.text, provisional.text, 'absent, provisional and private are one indistinguishable 404');
+});
+
+test('request: a PRIVATE account already connected to the viewer IS addressable (D4 §2)', async () => {
+  // Private, but an accepted edge exists → visibleTarget resolves, so the write runs.
+  expect(meActive(), result([account({ account_visibility: 'private' })]), result([{ '?column?': 1 }]), result([{ id: '80' }]));
+  const res = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+  assert.equal(res.status, 201);
+  assert.equal(calls.length, 4);
+  assert.match(calls[2].text, /pair_lo = LEAST\(\$1::bigint, \$2::bigint\)/,
+    'the "am I connected" probe is the symmetric pair key, not a direction-aware WHERE');
+});
+
+test('request: a provisional CALLER cannot send at all — the feature floors on active (D4 §1)', async () => {
+  expect(result([{ github_id: String(ME.github_id), profile_state: 'provisional' }]));
+  const res = await call('POST', '/api/bongos/connections', { handle: 'ada' });
+  assert.equal(res.status, 403);
+  assert.equal(res.json.error.code, 'profile_provisional');
+  assert.equal(calls.length, 1, 'it never looked the target up');
+});
+
+test('accept: the addressee is the SESSION, bound into the WHERE clause', async () => {
+  expect(meActive(), result([{ id: '77' }]));
+  const res = await call('POST', '/api/bongos/connections/77/accept');
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.json, { status: 'accepted' });
+  const w = calls[1];
+  assert.match(w.text, /SET status = 'accepted'[\s\S]*WHERE id = \$1 AND addressee_github_id = \$2::bigint AND status = 'pending'/);
+  assert.match(w.text, /created_at > now\(\) - make_interval\(days => \$3::int\)/, 'an expired request cannot be accepted');
+  assert.deepEqual(w.params, ['77', ME.github_id, conn.REQUEST_EXPIRY_DAYS]);
+});
+
+test('decline: silent (204), and the row is KEPT because rejected IS the cooldown', async () => {
+  expect(meActive(), result([{ id: '77' }]));
+  const res = await call('POST', '/api/bongos/connections/77/decline');
+  assert.equal(res.status, 204);
+  assert.equal(res.text, '', 'nothing is returned — and nothing is emitted to the requester');
+  assert.match(calls[1].text, /SET status = 'rejected'/);
+  assert.doesNotMatch(calls[1].text, /DELETE/, 'a decline never deletes: the row is the 90-day cooldown');
+  assert.match(calls[1].text, /created_at > now\(\) - make_interval\(days => \$3::int\)/,
+    'an ALREADY-EXPIRED request must not be turnable into a fresh 90-day cooldown — '
+    + 'accept guards on expiry and decline has to guard identically');
+  assert.deepEqual(calls[1].params, ['77', ME.github_id, conn.REQUEST_EXPIRY_DAYS]);
+});
+
+test('remove: an accepted row is HARD-DELETED; a pending one I sent is cancelled', async () => {
+  expect(meActive(), result([{ outcome: 'removed' }]));
+  const removed = await call('DELETE', '/api/bongos/connections/77');
+  assert.deepEqual(removed.json, { outcome: 'removed' });
+  const sql = calls[1].text;
+  assert.match(sql, /DELETE FROM platform_identity_connections[\s\S]*status = 'accepted'[\s\S]*\(requester_github_id = \$2::bigint OR addressee_github_id = \$2::bigint\)/,
+    'either side may end a consensual connection — and no tombstone is written');
+  assert.match(sql, /SET status = 'cancelled'[\s\S]*status = 'pending' AND requester_github_id = \$2::bigint/,
+    'only the REQUESTER may cancel; an addressee ending a pending row must decline, which arms the cooldown');
+  assert.deepEqual(calls[1].params, ['77', ME.github_id]);
+});
+
+test('list: my connections, the count IS the array length, and paging is real', async () => {
+  const rows = [
+    { id: '1', connected_at: null, handle: 'ada', display_name: 'Ada', avatar_url: null },
+    { id: '2', connected_at: null, handle: 'bob', display_name: 'Bob', avatar_url: null },
+  ];
+  expect(meActive(), result(rows));
+  const res = await call('GET', '/api/bongos/connections?limit=2&offset=4');
+  assert.equal(res.status, 200);
+  assert.equal(res.json.count, res.json.connections.length);
+  assert.equal(res.json.count, 2);
+  assert.match(calls[1].text, /LIMIT \$2 OFFSET \$3/,
+    'a hard cap with no OFFSET would make the 501st connection unreachable while count still read 500');
+  assert.deepEqual(calls[1].params, [ME.github_id, 2, 4]);
+  assert.match(calls[1].text, /\(pa\.profile_state = 'active'\)/,
+    'own scope floors on consent alone — a private account you connected with appears HERE (D4 §2)');
+  assert.doesNotMatch(calls[1].text, /account_visibility/,
+    "…and applying the PUBLIC predicate here would erase your own connections from your own list");
+});
+
+test('list: the limit is clamped to FANOUT_1 however large a caller asks', async () => {
+  expect(meActive(), result([]));
+  await call('GET', '/api/bongos/connections?limit=999999');
+  assert.deepEqual(calls[1].params, [ME.github_id, conn.FANOUT_1, 0]);
+});
+
+test('requests: each direction carries its OWN limit, so a busy outbox cannot empty the inbox', async () => {
+  expect(meActive(), result([]));
+  await call('GET', '/api/bongos/connections/requests');
+  const sql = calls[1].text;
+  assert.equal((sql.match(/LIMIT \$3/g) || []).length, 2,
+    'ONE cap applied before the split would let 500 outgoing requests push every incoming one out '
+    + 'of the response, reporting incoming_count: 0 with nothing saying it was a truncation');
+  assert.match(sql, /c\.created_at > now\(\) - make_interval\(days => \$2::int\)/,
+    'expiry is read-time — an expired request is absent from both queues, with no sweeper');
+  assert.deepEqual(calls[1].params, [ME.github_id, conn.REQUEST_EXPIRY_DAYS, conn.FANOUT_1]);
+});
+
+test('requests: seen_at rides the inbox and is STRIPPED from the outbox', async () => {
+  const rows = [
+    { id: '5', note: null, created_at: null, seen_at: null, incoming: true, handle: 'ada', display_name: 'Ada', avatar_url: null },
+    { id: '6', note: 'hi', created_at: null, seen_at: '2026-08-29T00:00:00Z', incoming: false, handle: 'bob', display_name: 'Bob', avatar_url: null },
+  ];
+  expect(meActive(), result(rows), result([], 1));
+  const res = await call('GET', '/api/bongos/connections/requests');
+  assert.equal(res.json.incoming.length, 1);
+  assert.equal(res.json.outgoing.length, 1);
+  assert.equal(res.json.incoming_count, res.json.incoming.length);
+  assert.equal(res.json.outgoing_count, res.json.outgoing.length);
+  assert.ok(!('incoming' in res.json.incoming[0]), 'the discriminator is consumed, not published');
+  assert.ok('seen_at' in res.json.incoming[0], 'my own inbox may say what I have opened');
+  assert.ok(!('seen_at' in res.json.outgoing[0]),
+    'a read receipt on the OUTBOX would tell a requester the addressee is deliberating — '
+    + 'the migration comment and ADR 0202 D2 §1 both promise that never crosses');
+});
+
+test('requests: the seen_at stamp is scoped to the rows this call actually rendered', async () => {
+  const rows = [
+    { id: '5', note: null, created_at: null, seen_at: null, incoming: true, handle: 'ada', display_name: 'Ada', avatar_url: null },
+    { id: '7', note: null, created_at: null, seen_at: '2026-08-01T00:00:00Z', incoming: true, handle: 'cy', display_name: 'Cy', avatar_url: null },
+  ];
+  expect(meActive(), result(rows), result([], 1));
+  await call('GET', '/api/bongos/connections/requests');
+  assert.equal(calls.length, 3);
+  assert.match(calls[2].text, /WHERE id = ANY\(\$1::bigint\[\]\) AND addressee_github_id = \$2::bigint/,
+    'an unscoped UPDATE would stamp expired and filtered-out rows too, so seen_at would mean '
+    + '"your inbox was polled" rather than "this row was delivered"');
+  assert.deepEqual(calls[2].params, [['5'], ME.github_id], 'only the unseen row that was rendered');
+});
+
+test('requests: nothing unseen means no write at all — a GET does not have to be a write', async () => {
+  const rows = [{ id: '5', note: null, created_at: null, seen_at: '2026-08-01T00:00:00Z', incoming: true, handle: 'ada', display_name: 'Ada', avatar_url: null }];
+  expect(meActive(), result(rows));
+  await call('GET', '/api/bongos/connections/requests');
+  assert.equal(calls.length, 2, 'the stamp is skipped when there is nothing to stamp');
+});
+
+// ===========================================================================
+// 3. A builder cannot act on someone else's connection
+// ===========================================================================
+
+test('every write binds the SESSION as the acting account — a hostile body changes nothing', async () => {
+  const hostile = { github_id: 1, builder_id: 1, owner: 1, requester_github_id: 1, addressee_github_id: 1 };
+  for (const [method, path] of [
+    ['POST', '/api/bongos/connections/77/accept'],
+    ['POST', '/api/bongos/connections/77/decline'],
+    ['DELETE', '/api/bongos/connections/77'],
+  ]) {
+    expect(meActive(), result([{ id: '77', outcome: 'removed' }]));
+    await call(method, path, hostile);
+    const params = calls[1].params;
+    assert.equal(params[1], ME.github_id, `${method} ${path} bound the session, not the body`);
+    assert.ok(!params.includes(1) && !params.includes('1'),
+      `${method} ${path} let a body value reach the query parameters`);
+  }
+});
+
+test("someone else's connection row simply does not match — and the answer is 404, not 403", async () => {
+  for (const [method, path, code] of [
+    ['POST', '/api/bongos/connections/77/accept', 'connection_request_not_found'],
+    ['POST', '/api/bongos/connections/77/decline', 'connection_request_not_found'],
+    ['DELETE', '/api/bongos/connections/77', 'connection_not_found'],
+  ]) {
+    expect(meActive(), result([], 0)); // the WHERE clause matched nothing
+    const res = await call(method, path);
+    assert.equal(res.status, 404, `${method} ${path} must 404, never 403 — a 403 makes the id space probeable`);
+    assert.equal(res.json.error.code, code);
+  }
+});
+
+test('an id too large for bigint is 404 too — a 500 there is a working probe', async () => {
+  expect(meActive());
+  const res = await call('POST', '/api/bongos/connections/99999999999999999999999/accept');
+  assert.equal(res.status, 404);
+  assert.equal(calls.length, 0, 'it must not reach Postgres and raise 22003 as a 500');
+});
+
+test('a non-numeric connection id is 404 too, and never reaches the database', async () => {
+  expect(meActive());
+  const res = await call('POST', '/api/bongos/connections/1%20OR%201=1/accept');
+  assert.equal(res.status, 404);
+  assert.equal(calls.length, 0, 'refused before any query — ids are bound, and a malformed one is not even bound');
+});
+
+test('no route in this surface reads its subject from the request', () => {
+  // The structural twin of the above: tests/own_scope_guard.mjs inventories this
+  // file, so a future edit that adds ?builder_id= fails there. This asserts the
+  // inventory entry exists, so the guard cannot be dodged by deleting it.
+  const guard = readFileSync(join(ROOT, 'tests/own_scope_guard.mjs'), 'utf8');
+  assert.match(guard, /file: 'modules\/platform-identity\/routes\/connections\.js'/,
+    'the connections surface must stay in the own-scope inventory');
+});
+
+// ===========================================================================
+// 4. The degree query is BOUNDED — the DoS surface
+// ===========================================================================
+
+const degreeCall = (handle = 'ada') => call('GET', `/api/bongos/connections/degree/${handle}`);
+
+// Every LIMIT in a traversal query must be a BOUND parameter and must be
+// preceded by an ORDER BY on the frontier key, so a truncation is reproducible
+// rather than a different answer each call (ADR 0202 D3).
+function assertBounded(sql, label) {
+  const limits = sql.match(/LIMIT \$\d+/g) || [];
+  assert.ok(limits.length >= 2, `${label}: every expansion level must carry a LIMIT (found ${limits.length})`);
+  assert.equal((sql.match(/LIMIT\s+\d/g) || []).length, 0, `${label}: a LIMIT must be a bound parameter, never a literal`);
+  assert.equal((sql.match(/ORDER BY [a-z]+\.gid LIMIT \$\d+/g) || []).length, limits.length,
+    `${label}: every LIMIT must follow ORDER BY <alias>.gid — an unordered truncation answers differently each call`);
+  assert.doesNotMatch(sql, /RECURSIVE/, `${label}: no recursive term — a recursive CTE cannot carry a PER-LEVEL cap`);
+}
+
+test('degree: 1st degree costs ONE bounded query and never expands the frontier', async () => {
+  expect(meActive(), result([account()]),
+    result([{ is_first: true, v1_count: 3, mutuals: [] }]));
+  const res = await degreeCall();
+  assert.equal(res.json.degree, 1);
+  assert.equal(calls.length, 3, 'the FANOUT_2 expansion must not run when the near query already answered');
+  assertBounded(calls[2].text, 'near');
+  assert.deepEqual(calls[2].params, [ME.github_id, String(ADA), conn.FANOUT_1]);
+});
+
+test('degree: 1st degree is an UNBOUNDED pair-index probe, not a scan of the capped frontier', () => {
+  // The bug this pins: reading is_first off `v1` (ORDER BY gid LIMIT 500) makes a
+  // viewer with 900 connections see "2nd" for someone who is in their own
+  // connections list, purely because that github_id sorts past the 500th.
+  const src = readFileSync(join(ROOT, 'modules/platform-identity/connections.js'), 'utf8');
+  assert.match(src, /EXISTS \(SELECT 1 FROM platform_identity_connections[\s\S]*?pair_lo = LEAST\(\$1::bigint, \$2::bigint\)[\s\S]*?\) AS is_first/,
+    'ADR 0202 D3: 1st degree is "one index hit on the accepted-pair index"');
+  assert.doesNotMatch(src, /FROM v1 WHERE v1\.gid = \$2::bigint\) AS is_first/,
+    'is_first must never be computed against a truncated frontier');
+});
+
+test('degree: 2nd degree comes from the mutual intersection, still one query', async () => {
+  const mutuals = [{ handle: 'bob', display_name: 'Bob', avatar_url: null }];
+  expect(meActive(), result([account()]), result([{ is_first: false, v1_count: 9, mutuals }]));
+  const res = await degreeCall();
+  assert.equal(res.json.degree, 2);
+  assert.deepEqual(res.json.mutuals, mutuals);
+  assert.equal(calls.length, 3);
+});
+
+test('degree: 3rd degree runs exactly ONE more query, capped at FANOUT_1 then FANOUT_2', async () => {
+  expect(meActive(), result([account()]),
+    result([{ is_first: false, v1_count: 9, mutuals: [] }]),
+    result([{ is_third: true, v2_count: 400 }]));
+  const res = await degreeCall();
+  assert.equal(res.json.degree, 3);
+  assert.equal(res.json.degree, conn.DEGREE_MAX);
+  assert.equal(calls.length, 4, 'two graph queries, always — the expansion is staged, not open-ended');
+  const far = calls[3];
+  assertBounded(far.text, 'far');
+  assert.deepEqual(far.params, [ME.github_id, String(ADA), conn.FANOUT_1, conn.FANOUT_2],
+    'the caps are the ADR 0202 D3 constants, bound as parameters');
+  assert.match(far.text, /\(pa\.profile_state = 'active' AND pa\.account_visibility = 'public'\)/,
+    'a hop BEYOND the viewer\'s own connections must clear the full public predicate');
+});
+
+test('degree: past DEGREE_MAX the answer is null — "out of network", not a deeper search', async () => {
+  expect(meActive(), result([account()]),
+    result([{ is_first: false, v1_count: 500, mutuals: [] }]),
+    result([{ is_third: false, v2_count: 5000 }]));
+  const res = await degreeCall();
+  assert.equal(res.json.degree, null, 'never a number the query did not establish');
+  assert.equal(res.json.truncated, true, 'both caps bit, and the response says so honestly');
+  assert.equal(calls.length, 4, 'the query count is CONSTANT — the traversal cannot be made to run longer');
+});
+
+test('degree: the query count does not grow with the graph — the DoS bound', async () => {
+  // The pool hands back the biggest frontier the caps allow. If the expansion
+  // were driven by result size (or recursed), this would issue more queries.
+  const huge = Array.from({ length: conn.FANOUT_1 }, (_, i) => ({ handle: `m${i}`, display_name: null, avatar_url: null }));
+  expect(meActive(), result([account()]), result([{ is_first: false, v1_count: conn.FANOUT_1, mutuals: huge }]));
+  const res = await degreeCall();
+  assert.equal(calls.length, 3);
+  assert.equal(res.json.degree, 2);
+  assert.equal(res.json.mutual_count, res.json.mutuals.length,
+    'the count is the length of the array the viewer may see — never a total beside a filtered list');
+  assert.equal(res.json.mutual_count, conn.FANOUT_1, 'and the array itself is capped by FANOUT_1');
+});
+
+test('degree: measuring yourself is 0 and costs no graph query at all', async () => {
+  expect(meActive(), result([account({ github_id: String(ME.github_id), handle: 'octo' })]));
+  const res = await degreeCall('octo');
+  assert.equal(res.json.degree, 0);
+  assert.deepEqual(res.json.mutuals, []);
+  assert.equal(calls.length, 2);
+});
+
+test('degree: an invisible target is 404 before any traversal runs', async () => {
+  expect(meActive(), result([account({ account_visibility: 'private' })]), result([], 0));
+  const res = await degreeCall();
+  assert.equal(res.status, 404);
+  assert.equal(calls.length, 3, 'the expansion never started');
+});
+
+test('the caps are the ADR 0202 D3 numbers, and DEGREE_MAX really is 3', () => {
+  assert.equal(conn.DEGREE_MAX, 3);
+  assert.equal(conn.FANOUT_1, 500);
+  assert.equal(conn.FANOUT_2, 5000);
+  assert.equal(conn.REQUEST_EXPIRY_DAYS, 30);
+  assert.equal(conn.DECLINE_COOLDOWN_DAYS, 90);
+});
+
+// ===========================================================================
+// 5. Nothing here is authority (ADR 0016 / ADR 0141)
+// ===========================================================================
+
+test('no rank, permission or credit symbol appears anywhere in the feature', () => {
+  for (const [name, src] of [['domain', DOMAIN_SRC], ['routes', ROUTE_SRC]]) {
+    const code = src.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+    for (const forbidden of [/requireRank/, /requirePermission/, /\bcredits\b/, /\bkarma\b/, /builders\.rank/, /LIVE_RANK_LADDER/]) {
+      assert.doesNotMatch(code, forbidden,
+        `${name}: a connection must never touch authority — ${forbidden} found (ADR 0016)`);
+    }
+  }
+  assert.match(ROUTE_SRC, /requireBuilder/, '…while still requiring a live session on every route');
+});
+
+test('a system:* principal has no platform account and is refused cleanly, not with a cast error', async () => {
+  session = { github_id: 'system:bfg', github_login: 'bfg' };
+  try {
+    expect();
+    const res = await call('GET', '/api/bongos/connections');
+    assert.equal(res.status, 400);
+    assert.equal(res.json.error.code, 'no_platform_identity');
+    assert.equal(calls.length, 0, 'a non-numeric id must never be bound against the bigint column');
+  } finally {
+    session = { ...ME };
+  }
+});
+
+test('the responses are no-store — a hide or a visibility flip must beat any cache', async () => {
+  expect(meActive(), result([]));
+  const res = await new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port, path: '/api/bongos/connections' }, (r) => {
+      r.resume();
+      r.on('end', () => resolve(r.headers));
+    }).on('error', reject);
+  });
+  assert.equal(res['cache-control'], 'no-store');
+});