@bongos/core 1.19.1026 → 1.19.1027

package/modules/platform-identity/guilds.js

@@ -0,0 +1,705 @@
+// modules/platform-identity/guilds.js — the guild domain: create, membership,
+// invites and join requests, and the public/unlisted read (task 1002300, R24;
+// ADR 0336 D1–D4 + D6, amended by ADR 0337 D4.4).
+//
+// WHAT LIVES HERE, next to the data so no route can forget a rule:
+//
+//   * TWO CONSENTS TO JOIN, NO SELF-JOIN (D3). An owner invites and the invitee
+//     accepts, or a builder asks a PUBLIC guild and the owner accepts. An
+//     unlisted guild takes invites only, because a stranger cannot address it.
+//   * THE CONNECTIONS LIFECYCLE, VERBATIM (D3, ADR 0202 D2) — its exported
+//     constants, so the two features cannot drift: a decline is silent and a
+//     re-ask of the same kind inside the cooldown is SWALLOWED with the answer a
+//     real one gets; a pending row expires read-time and the write path resolves
+//     it in the same statement that inserts the next one; accepting resolves the
+//     row and inserts the membership in ONE statement.
+//   * CONSENT IS TO WHAT THE CARD SHOWED (D4 §3). shown_publicly is set by the
+//     guild's visibility at the moment of joining; an invite accept carries the
+//     visibility its card displayed and is refused if the guild changed since.
+//     A visibility change flips only the owner's own flag.
+//   * ONE OWNER (D2), held by a partial unique index. Transfer is two statements
+//     in one transaction — demote, then promote — because that index is checked
+//     row by row and cannot be deferred. The last member leaving dissolves.
+//   * THE PUBLIC ROSTER IS shown_publicly AND accountVisibleSql (D4): a private
+//     account is never on it, whatever its flag. Members read each other through
+//     the own-scope roster, which floors on consent alone (joining is consent to
+//     be seen by the guild, never by the world). Every count is the length of a
+//     list the reader may see.
+//   * counted_in_totals (ADR 0337 D4.4) is stored and switchable here; the
+//     totals that read it are task 1002302's.
+//
+// NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). A guild grants no rank,
+// credits, admission or access to any project.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const api = require('../../src/module-api');
+const {
+  accountVisibleSql, accountActiveSql, isAccountVisible, isAccountActive,
+} = require('./account-visibility');
+const conn = require('./connections');
+const { normalizeHandle } = require('./platform-identity');
+
+const { pool: defaultPool } = api;
+
+// ---------------------------------------------------------------------------
+// The constants ADR 0336 named. Exported so a route, a test and a doc read the
+// same number.
+// ---------------------------------------------------------------------------
+
+// Mirrors the migration's CHECK. No default anywhere: the creator chooses.
+const GUILD_VISIBILITIES = ['public', 'unlisted'];
+
+// Words the /g namespace uses (D6). A slug may never shadow them.
+const GUILD_RESERVED_SLUGS = ['me', 'new', 'edit', 'settings', 'admin', 'api'];
+
+// D6: the handle charset with a two-character floor. The ceiling (39) is the
+// charset's own, and the migration's CHECK holds both.
+const SLUG_MIN_CHARS = 2;
+
+// ADR 0336 Deferred: guild names are user-written public text, so R24 caps them.
+// Mirrored by the migration's CHECKs.
+const NAME_MAX_CHARS = 80;
+const DESCRIPTION_MAX_CHARS = 500;
+
+// D3: a batch invite is a loop of ordinary invites, never a new kind of
+// membership, and it is bounded.
+const INVITE_BATCH_MAX = 25;
+
+// The largest roster or queue one read returns.
+const LIST_MAX = 500;
+
+// The connections lifecycle's own numbers (D3), imported rather than restated.
+const { REQUEST_EXPIRY_DAYS, DECLINE_COOLDOWN_DAYS } = conn;
+
+// What a person in a guild list carries (ADR 0336 R25 row): handle, display
+// name, avatar. github_id and github_login never leave this module.
+const PERSON_COLUMNS = 'pa.handle, pa.display_name, pa.avatar_url';
+
+// The owner test every owner-only statement re-asserts in its own WHERE, so a
+// route's pre-check is a nicer error and never the only gate. $g/$a are the
+// placeholders holding the guild id and the acting github_id.
+function ownerExistsSql(g, a) {
+  return `EXISTS (SELECT 1 FROM platform_identity_guild_members o
+                   WHERE o.guild_id = ${g} AND o.github_id = ${a}::bigint
+                     AND o.membership_kind = 'owner')`;
+}
+
+// ---------------------------------------------------------------------------
+// Slugs and addressing
+// ---------------------------------------------------------------------------
+
+// A slug offered at creation → { slug } or { error }. Canonical form only.
+function normalizeGuildSlug(raw) {
+  const slug = normalizeHandle(raw);
+  if (!slug || slug.length < SLUG_MIN_CHARS) return { error: 'slug_invalid' };
+  if (GUILD_RESERVED_SLUGS.includes(slug)) return { error: 'slug_reserved' };
+  return { slug };
+}
+
+// A slug from a URL → its canonical form, or null. A reserved word simply never
+// matches a row, so lookups need no separate refusal.
+function lookupSlug(raw) {
+  return normalizeHandle(raw);
+}
+
+// Resolve a handle to an account THIS viewer may invite: publicly visible, or a
+// private account the viewer is already connected to (ADR 0202 D4 §2 — the
+// rule routes/connections.js visibleTarget applies, composed from the same
+// shared predicates). Unknown, provisional and private-stranger are one null.
+async function addressableAccount(viewerGithubId, handle, { pool = defaultPool } = {}) {
+  const acct = await conn.findAccountByHandle(handle, { pool });
+  if (!acct) return null;
+  if (isAccountVisible(acct)) return acct;
+  if (!isAccountActive(acct)) return null;
+  return (await conn.isConnectedTo(viewerGithubId, acct.github_id, { pool })) ? acct : null;
+}
+
+// ---------------------------------------------------------------------------
+// Guild CRUD
+// ---------------------------------------------------------------------------
+
+// Create a guild and its owner row in ONE statement, so a guild never exists
+// without its owner. The owner's shown_publicly follows the visibility they
+// chose. Returns { guild } or { taken: true } when the slug is in use.
+async function createGuild({ githubId, slug, name, description = null, visibility }, { pool = defaultPool } = {}) {
+  try {
+    const { rows } = await pool.query(
+      `WITH g AS (
+         INSERT INTO platform_identity_guilds (slug, name, description, visibility)
+         VALUES ($1, $2, $3, $4)
+         RETURNING id, slug, name, description, visibility, created_at
+       ),
+       owner_row AS (
+         INSERT INTO platform_identity_guild_members (guild_id, github_id, membership_kind, shown_publicly)
+         SELECT g.id, $5::bigint, 'owner', g.visibility = 'public' FROM g
+         RETURNING guild_id
+       )
+       SELECT g.slug, g.name, g.description, g.visibility, g.created_at
+         FROM g JOIN owner_row o ON o.guild_id = g.id`,
+      [slug, name, description, visibility, githubId],
+    );
+    return { guild: rows[0] };
+  } catch (err) {
+    // 23505 here can only be the case-insensitive slug index.
+    if (err && err.code === '23505') return { taken: true };
+    throw err;
+  }
+}
+
+// The caller's own membership of one guild, with the guild's details, or null.
+// The own-scope door to an UNLISTED guild: a non-member gets null, the same
+// answer as a guild that does not exist.
+async function getMembership(slug, githubId, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT g.id, g.slug, g.name, g.description, g.visibility, g.created_at,
+            m.membership_kind, m.shown_publicly, m.counted_in_totals, m.joined_at
+       FROM platform_identity_guilds g
+       JOIN platform_identity_guild_members m ON m.guild_id = g.id AND m.github_id = $2::bigint
+      WHERE lower(g.slug) = $1`,
+    [slug, githubId],
+  );
+  return rows[0] || null;
+}
+
+// Edit name, description or visibility — the owner only, re-asserted here. A
+// visibility CHANGE flips the owner's own shown_publicly to match and nobody
+// else's (D4 §3: consent given to a small audience is not consent to a large
+// one). `description` undefined leaves it; null or '' clears it.
+async function updateGuild({ guildId, githubId, name, description, visibility }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `WITH own AS (
+       SELECT g.id, g.visibility AS old_visibility
+         FROM platform_identity_guilds g
+        WHERE g.id = $1 AND ${ownerExistsSql('g.id', '$2')}
+     ),
+     upd AS (
+       UPDATE platform_identity_guilds g
+          SET name = COALESCE($3::text, g.name),
+              description = CASE WHEN $4::boolean THEN $5::text ELSE g.description END,
+              visibility = COALESCE($6::text, g.visibility),
+              updated_at = now()
+         FROM own
+        WHERE g.id = own.id
+       RETURNING g.id, g.slug, g.name, g.description, g.visibility, own.old_visibility
+     ),
+     flip AS (
+       UPDATE platform_identity_guild_members m
+          SET shown_publicly = (upd.visibility = 'public')
+         FROM upd
+        WHERE m.guild_id = upd.id AND m.github_id = $2::bigint
+          AND upd.visibility <> upd.old_visibility
+       RETURNING m.guild_id
+     )
+     SELECT slug, name, description, visibility FROM upd`,
+    [guildId, githubId, name ?? null, description !== undefined, description || null, visibility ?? null],
+  );
+  return rows[0] || null;
+}
+
+// Dissolve — the owner only. Hard delete; the FKs cascade to every membership
+// and open request (D2).
+async function dissolveGuild({ guildId, githubId }, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `DELETE FROM platform_identity_guilds g
+      WHERE g.id = $1 AND ${ownerExistsSql('g.id', '$2')}
+      RETURNING g.id`,
+    [guildId, githubId],
+  );
+  return rowCount > 0;
+}
+
+// ---------------------------------------------------------------------------
+// Membership
+// ---------------------------------------------------------------------------
+
+// The caller's guilds, newest first. Own data, so no account join.
+async function listMyGuilds({ githubId, limit = LIST_MAX, offset = 0 }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT g.slug, g.name, g.visibility,
+            m.membership_kind, m.shown_publicly, m.counted_in_totals, m.joined_at
+       FROM platform_identity_guild_members m
+       JOIN platform_identity_guilds g ON g.id = m.guild_id
+      WHERE m.github_id = $1::bigint
+      ORDER BY m.joined_at DESC, g.id DESC
+      LIMIT $2 OFFSET $3`,
+    [githubId, Math.min(Number(limit) || LIST_MAX, LIST_MAX), Math.max(0, Number(offset) || 0)],
+  );
+  return rows;
+}
+
+// The members' roster — the OWN-SCOPE read a member reaches their guild through
+// (D4). Floors on consent alone: a private member is visible to fellow members,
+// because joining is consent to be seen by the guild. Neither shown_publicly nor
+// counted_in_totals of anyone else is returned — both are that member's own call.
+async function listMemberRoster({ guildId, limit = LIST_MAX, offset = 0 }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT ${PERSON_COLUMNS}, m.membership_kind
+       FROM platform_identity_guild_members m
+       JOIN platform_identity_accounts pa ON pa.github_id = m.github_id
+      WHERE m.guild_id = $1 AND ${accountActiveSql('pa')}
+      ORDER BY (m.membership_kind = 'owner') DESC, lower(pa.handle), pa.github_id
+      LIMIT $2 OFFSET $3`,
+    [guildId, Math.min(Number(limit) || LIST_MAX, LIST_MAX), Math.max(0, Number(offset) || 0)],
+  );
+  return rows;
+}
+
+// A member's own switches: shown_publicly (D4) and counted_in_totals (ADR 0337
+// D4.4). Each is optional; null leaves it. Keyed on the session's github_id, so
+// nobody can flip anybody else's. Returns the new flags, or null if not a member.
+async function setMembershipFlags({ slug, githubId, shownPublicly = null, countedInTotals = null }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `UPDATE platform_identity_guild_members m
+        SET shown_publicly = COALESCE($3::boolean, m.shown_publicly),
+            counted_in_totals = COALESCE($4::boolean, m.counted_in_totals)
+       FROM platform_identity_guilds g
+      WHERE g.id = m.guild_id AND lower(g.slug) = $1 AND m.github_id = $2::bigint
+      RETURNING m.shown_publicly, m.counted_in_totals`,
+    [slug, githubId, shownPublicly, countedInTotals],
+  );
+  return rows[0] || null;
+}
+
+// Leave. A member leaves; the owner must transfer first, unless they are the
+// last member, in which case leaving DISSOLVES the guild (D2). One statement.
+// `mine` locks the caller's row, so a leave racing a transfer that is promoting
+// them waits and re-reads it as 'owner' (must_transfer) instead of deleting the
+// new owner from a stale snapshot; left_row re-checks the kind for the same
+// reason. The accepted request row that admitted them goes too: kept, it would
+// be a record that they were ever here (the D2 no-tombstone reason).
+// Returns 'left' | 'dissolved' | 'must_transfer' | null (not a member).
+async function leaveGuild({ guildId, githubId }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `WITH mine AS (
+       SELECT membership_kind FROM platform_identity_guild_members
+        WHERE guild_id = $1 AND github_id = $2::bigint
+        FOR UPDATE
+     ),
+     others AS (
+       SELECT EXISTS (SELECT 1 FROM platform_identity_guild_members
+                       WHERE guild_id = $1 AND github_id <> $2::bigint) AS has_others
+     ),
+     left_row AS (
+       DELETE FROM platform_identity_guild_members m
+        USING mine
+        WHERE m.guild_id = $1 AND m.github_id = $2::bigint
+          AND m.membership_kind = 'member' AND mine.membership_kind = 'member'
+       RETURNING 'left'::text AS outcome
+     ),
+     purged AS (
+       DELETE FROM platform_identity_guild_requests r
+        WHERE r.guild_id = $1 AND r.github_id = $2::bigint AND r.status = 'accepted'
+          AND EXISTS (SELECT 1 FROM left_row)
+       RETURNING r.id
+     ),
+     dissolved AS (
+       DELETE FROM platform_identity_guilds g
+        USING mine, others
+        WHERE g.id = $1 AND mine.membership_kind = 'owner' AND NOT others.has_others
+       RETURNING 'dissolved'::text AS outcome
+     )
+     SELECT outcome FROM left_row
+     UNION ALL SELECT outcome FROM dissolved
+     UNION ALL SELECT 'must_transfer'::text FROM mine, others
+                WHERE mine.membership_kind = 'owner' AND others.has_others`,
+    [guildId, githubId],
+  );
+  return rows[0] ? rows[0].outcome : null;
+}
+
+// Remove a member — the owner only, and never the owner themselves (they leave
+// or dissolve). Hard delete (D2), taking the accepted request row with it, as
+// leaveGuild does. The member is named by current handle, resolved on the same
+// consent floor as the members' roster the owner picked them from.
+async function removeMember({ guildId, ownerGithubId, handle }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `WITH gone AS (
+       DELETE FROM platform_identity_guild_members m
+        USING platform_identity_accounts pa
+        WHERE m.guild_id = $1 AND m.membership_kind = 'member'
+          AND pa.github_id = m.github_id AND lower(pa.handle) = $3
+          AND ${accountActiveSql('pa')}
+          AND ${ownerExistsSql('$1', '$2')}
+       RETURNING m.guild_id, m.github_id
+     ),
+     purged AS (
+       DELETE FROM platform_identity_guild_requests r
+        USING gone
+        WHERE r.guild_id = gone.guild_id AND r.github_id = gone.github_id AND r.status = 'accepted'
+       RETURNING r.id
+     )
+     SELECT count(*)::int AS removed FROM gone`,
+    [guildId, ownerGithubId, handle],
+  );
+  return !!rows[0] && rows[0].removed > 0;
+}
+
+class TransferAborted extends Error {}
+
+// Transfer ownership to an existing member: TWO statements in ONE transaction,
+// demote then promote (D2). A single UPDATE swapping both rows would pass or fail
+// on the order Postgres visits them, because the one-owner index is checked row
+// by row and a partial index cannot be deferred. The target row is locked first
+// so it cannot leave between the two. Returns 'transferred' | 'not_member' | 'not_owner'.
+async function transferOwnership({ guildId, ownerGithubId, handle }, { pool = defaultPool } = {}) {
+  try {
+    return await api.withTx(async (client) => {
+      const target = await client.query(
+        `SELECT m.github_id FROM platform_identity_guild_members m
+           JOIN platform_identity_accounts pa ON pa.github_id = m.github_id
+          WHERE m.guild_id = $1 AND m.membership_kind = 'member'
+            AND lower(pa.handle) = $2 AND ${accountActiveSql('pa')}
+          FOR UPDATE OF m`,
+        [guildId, handle],
+      );
+      if (!target.rows[0]) return 'not_member';
+      const demoted = await client.query(
+        `UPDATE platform_identity_guild_members SET membership_kind = 'member'
+          WHERE guild_id = $1 AND github_id = $2::bigint AND membership_kind = 'owner'
+          RETURNING github_id`,
+        [guildId, ownerGithubId],
+      );
+      if (!demoted.rowCount) return 'not_owner';
+      const promoted = await client.query(
+        `UPDATE platform_identity_guild_members SET membership_kind = 'owner'
+          WHERE guild_id = $1 AND github_id = $2::bigint AND membership_kind = 'member'
+          RETURNING github_id`,
+        [guildId, target.rows[0].github_id],
+      );
+      // Unreachable while the row lock holds, but a guild must never be left
+      // ownerless: throwing rolls the demotion back.
+      if (!promoted.rowCount) throw new TransferAborted();
+      return 'transferred';
+    }, { pool });
+  } catch (err) {
+    if (err instanceof TransferAborted) return 'not_member';
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Invites and join requests
+// ---------------------------------------------------------------------------
+
+// ONE statement for both directions, the connections requestConnection shape:
+// `expired` resolves a timed-out pending row of this pair and is referenced
+// through `guard`, so it is drained BEFORE the INSERT (an unreferenced
+// data-modifying CTE runs after it and would hit the open-row index); the
+// cooldown NOT EXISTS inserts nothing inside the window, which is how a
+// swallowed re-ask writes nothing while answering yes. `gate` is a static
+// fragment naming who may open this kind of row.
+function openRequestSql(gate) {
+  return `
+    WITH expired AS (
+      UPDATE platform_identity_guild_requests r
+         SET status = 'expired', resolved_at = now()
+       WHERE r.guild_id = $1 AND r.github_id = $2::bigint AND r.status = 'pending'
+         AND r.created_at <= now() - make_interval(days => $4::int)
+      RETURNING r.id
+    ),
+    guard AS (SELECT count(*)::int AS expired_count FROM expired)
+    INSERT INTO platform_identity_guild_requests (guild_id, github_id, kind, counted_in_totals)
+    SELECT $1::bigint, $2::bigint, $3::text, $6::boolean
+      FROM guard
+     WHERE ${gate}
+       AND NOT EXISTS (SELECT 1 FROM platform_identity_guild_members m
+                        WHERE m.guild_id = $1 AND m.github_id = $2::bigint)
+       AND NOT EXISTS (SELECT 1 FROM platform_identity_guild_requests r
+                        WHERE r.guild_id = $1 AND r.github_id = $2::bigint AND r.kind = $3::text
+                          AND r.status = 'rejected'
+                          AND r.resolved_at > now() - make_interval(days => $5::int))
+    RETURNING id`;
+}
+
+// Run an open-request insert → 'created' | 'swallowed' | 'already_open'. The
+// route must answer 'created' and 'swallowed' identically.
+async function runOpenRequest(sql, params, pool) {
+  try {
+    const { rowCount } = await pool.query(sql, params);
+    return rowCount > 0 ? 'created' : 'swallowed';
+  } catch (err) {
+    // The open-row index: an invite or a request is already pending for this
+    // (guild, person). Safe to name — it is in the caller's own queue already.
+    if (err && err.code === '23505') return 'already_open';
+    throw err;
+  }
+}
+
+async function isMember(guildId, githubId, pool) {
+  const { rowCount } = await pool.query(
+    `SELECT 1 FROM platform_identity_guild_members WHERE guild_id = $1 AND github_id = $2::bigint`,
+    [guildId, githubId],
+  );
+  return rowCount > 0;
+}
+
+// A builder asks to join. Only a PUBLIC guild takes requests (D3/D4), so an
+// unlisted slug and an unknown one are the same 'not_found'. Joining a public
+// guild is consent to be shown there, so the request needs no card check; the
+// requester's counted_in_totals choice rides the row until the owner accepts.
+// Returns { outcome: 'created' | 'swallowed' | 'already_open' | 'already_member' | 'not_found' }.
+async function requestToJoin({ slug, githubId, countedInTotals = true }, { pool = defaultPool } = {}) {
+  const { rows } = await pool.query(
+    `SELECT id FROM platform_identity_guilds WHERE lower(slug) = $1 AND visibility = 'public'`,
+    [slug],
+  );
+  const guild = rows[0];
+  if (!guild) return { outcome: 'not_found' };
+  if (await isMember(guild.id, githubId, pool)) return { outcome: 'already_member' };
+  const gate = `EXISTS (SELECT 1 FROM platform_identity_guilds g WHERE g.id = $1 AND g.visibility = 'public')`;
+  const outcome = await runOpenRequest(openRequestSql(gate), [
+    guild.id, githubId, 'request', REQUEST_EXPIRY_DAYS, DECLINE_COOLDOWN_DAYS, countedInTotals !== false,
+  ], pool);
+  return { outcome };
+}
+
+// The owner invites up to INVITE_BATCH_MAX handles, each an ordinary individual
+// invite (D3). Per handle: 'invited' (written OR swallowed by a decline
+// cooldown — deliberately one answer), 'already_open', 'already_member', or
+// 'not_found' (unknown, provisional, or a private account the owner is not
+// connected to — one answer for all three).
+async function inviteHandles({ guildId, ownerGithubId, handles }, { pool = defaultPool } = {}) {
+  const seen = new Set();
+  const results = [];
+  const sql = openRequestSql(ownerExistsSql('$1', '$7'));
+  for (const raw of handles.slice(0, INVITE_BATCH_MAX)) {
+    const handle = String(raw || '').trim().toLowerCase();
+    if (!handle || seen.has(handle)) continue;
+    seen.add(handle);
+    const target = await addressableAccount(ownerGithubId, handle, { pool });
+    if (!target) { results.push({ handle, outcome: 'not_found' }); continue; }
+    if (String(target.github_id) === String(ownerGithubId) || await isMember(guildId, target.github_id, pool)) {
+      results.push({ handle, outcome: 'already_member' });
+      continue;
+    }
+    const out = await runOpenRequest(sql, [
+      guildId, target.github_id, 'invite', REQUEST_EXPIRY_DAYS, DECLINE_COOLDOWN_DAYS, true, ownerGithubId,
+    ], pool);
+    results.push({ handle, outcome: out === 'already_open' ? 'already_open' : 'invited' });
+  }
+  return results;
+}
+
+// Accept an invite (the invitee) or a join request (the guild's owner).
+//
+// The invitee's accept carries the visibility their card showed; if the guild's
+// visibility has changed since, it is refused ('visibility_changed') so the
+// card can re-render for a fresh decision (D4 §3). They may also set their
+// counted_in_totals there (ADR 0337 D4.4). An owner accepting a request cannot
+// set the requester's switch: that comes from the request row.
+//
+// The accept itself is ONE statement: resolve the row and insert the membership,
+// every condition re-asserted in its WHERE. shown_publicly is the guild's
+// visibility at this moment. Returns { outcome: 'accepted' | 'not_found' |
+// 'card_required' | 'visibility_changed', visibility? }.
+async function acceptRequest({ id, githubId, cardVisibility = null, countedInTotals = null }, { pool = defaultPool } = {}) {
+  const pre = await pool.query(
+    `SELECT r.kind, r.github_id::text AS github_id, g.visibility,
+            ${ownerExistsSql('r.guild_id', '$2')} AS actor_is_owner
+       FROM platform_identity_guild_requests r
+       JOIN platform_identity_guilds g ON g.id = r.guild_id
+      WHERE r.id = $1 AND r.status = 'pending'
+        AND r.created_at > now() - make_interval(days => $3::int)`,
+    [id, githubId, REQUEST_EXPIRY_DAYS],
+  );
+  const row = pre.rows[0];
+  const asInvitee = !!row && row.kind === 'invite' && row.github_id === String(githubId);
+  const asOwner = !!row && row.kind === 'request' && row.actor_is_owner === true;
+  if (!asInvitee && !asOwner) return { outcome: 'not_found' };
+  if (asInvitee) {
+    if (!cardVisibility) return { outcome: 'card_required' };
+    if (cardVisibility !== row.visibility) return { outcome: 'visibility_changed', visibility: row.visibility };
+  }
+  const { rows } = await pool.query(
+    `WITH acc AS (
+       UPDATE platform_identity_guild_requests r
+          SET status = 'accepted', resolved_at = now()
+         FROM platform_identity_guilds g
+        WHERE r.id = $1 AND g.id = r.guild_id AND r.status = 'pending'
+          AND r.created_at > now() - make_interval(days => $3::int)
+          AND ((r.kind = 'invite' AND r.github_id = $2::bigint AND g.visibility = $4::text)
+               OR (r.kind = 'request' AND ${ownerExistsSql('r.guild_id', '$2')}
+                   AND EXISTS (SELECT 1 FROM platform_identity_accounts pa
+                                WHERE pa.github_id = r.github_id AND ${accountActiveSql('pa')})))
+       RETURNING r.guild_id, r.github_id, r.kind, r.counted_in_totals, g.visibility
+     ),
+     joined AS (
+       INSERT INTO platform_identity_guild_members
+              (guild_id, github_id, membership_kind, shown_publicly, counted_in_totals)
+       SELECT guild_id, github_id, 'member', visibility = 'public',
+              CASE WHEN kind = 'invite' THEN COALESCE($5::boolean, counted_in_totals)
+                   ELSE counted_in_totals END
+         FROM acc
+       ON CONFLICT (guild_id, github_id) DO NOTHING
+       RETURNING guild_id
+     )
+     SELECT (SELECT count(*)::int FROM acc) AS accepted`,
+    [id, githubId, REQUEST_EXPIRY_DAYS, asInvitee ? cardVisibility : null, asInvitee ? countedInTotals : null],
+  );
+  return { outcome: rows[0] && rows[0].accepted > 0 ? 'accepted' : 'not_found' };
+}
+
+// Decline — the invitee an invite, the owner a request. SILENT: the other side
+// is never told, and the kept 'rejected' row IS the cooldown.
+async function declineRequest({ id, githubId }, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `UPDATE platform_identity_guild_requests r
+        SET status = 'rejected', resolved_at = now()
+      WHERE r.id = $1 AND r.status = 'pending'
+        AND r.created_at > now() - make_interval(days => $3::int)
+        AND ((r.kind = 'invite' AND r.github_id = $2::bigint)
+             OR (r.kind = 'request' AND ${ownerExistsSql('r.guild_id', '$2')}))
+      RETURNING r.id`,
+    [id, githubId, REQUEST_EXPIRY_DAYS],
+  );
+  return rowCount > 0;
+}
+
+// Cancel — whoever opened the row: the requester their request, the owner an
+// invite. A cancel never arms a cooldown, so the other side cannot use it to
+// dodge a decline.
+async function cancelRequest({ id, githubId }, { pool = defaultPool } = {}) {
+  const { rowCount } = await pool.query(
+    `UPDATE platform_identity_guild_requests r
+        SET status = 'cancelled', resolved_at = now()
+      WHERE r.id = $1 AND r.status = 'pending'
+        AND ((r.kind = 'request' AND r.github_id = $2::bigint)
+             OR (r.kind = 'invite' AND ${ownerExistsSql('r.guild_id', '$2')}))
+      RETURNING r.id`,
+    [id, githubId],
+  );
+  return rowCount > 0;
+}
+
+// Split a two-direction queue: the incoming side keeps seen_at (and gets it
+// stamped); the outgoing side never sees it — a decline is silent, and so is a
+// read (the connections listRequests rule).
+function splitQueue(rows, incomingKind) {
+  const incoming = rows.filter((r) => r.kind === incomingKind).map(({ kind, ...r }) => r);
+  const outgoing = rows.filter((r) => r.kind !== incomingKind).map(({ kind, seen_at, ...r }) => r);
+  return { incoming, outgoing, unseen: incoming.filter((r) => !r.seen_at).map((r) => r.id) };
+}
+
+// The caller's own queue: invites addressed to them (each carrying the card —
+// the guild's name, description and CURRENT visibility, which the accept must
+// echo back) and the join requests they sent. Each direction has its own cap.
+async function listMyRequests({ githubId }, { pool = defaultPool } = {}) {
+  const one = (kind) => `
+    SELECT r.id::text AS id, r.kind, r.created_at, r.seen_at,
+            g.slug, g.name, g.description, g.visibility
+       FROM platform_identity_guild_requests r
+       JOIN platform_identity_guilds g ON g.id = r.guild_id
+      WHERE r.github_id = $1::bigint AND r.kind = '${kind}' AND r.status = 'pending'
+        AND r.created_at > now() - make_interval(days => $2::int)
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT $3`;
+  const { rows } = await pool.query(
+    `(${one('invite')}) UNION ALL (${one('request')})`,
+    [githubId, REQUEST_EXPIRY_DAYS, LIST_MAX],
+  );
+  const { incoming, outgoing, unseen } = splitQueue(rows, 'invite');
+  if (unseen.length) {
+    await pool.query(
+      `UPDATE platform_identity_guild_requests SET seen_at = now()
+        WHERE id = ANY($1::bigint[]) AND github_id = $2::bigint AND kind = 'invite' AND seen_at IS NULL`,
+      [unseen, githubId],
+    );
+  }
+  return { incoming, outgoing };
+}
+
+// The owner's queue for one guild: join requests to decide, and invites still
+// out. A requester floors on consent alone — they addressed the guild, and a
+// request must name who is asking or it cannot be decided. An INVITEE consented
+// to nothing yet, so they are listed only if THIS owner could address them
+// (public, or connected — the addressableAccount rule): after a transfer, a
+// private account the previous owner invited is not revealed to the new one.
+// Owner re-asserted in the statement.
+async function listGuildRequests({ guildId, ownerGithubId }, { pool = defaultPool } = {}) {
+  const one = (kind, extra = '') => `
+    SELECT r.id::text AS id, r.kind, r.created_at, r.seen_at, ${PERSON_COLUMNS}
+       FROM platform_identity_guild_requests r
+       JOIN platform_identity_accounts pa ON pa.github_id = r.github_id
+      WHERE r.guild_id = $1 AND r.kind = '${kind}' AND r.status = 'pending'
+        AND r.created_at > now() - make_interval(days => $3::int)
+        AND ${ownerExistsSql('$1', '$2')}
+        AND ${accountActiveSql('pa')}${extra}
+      ORDER BY r.created_at DESC, r.id DESC
+      LIMIT $4`;
+  const addressable = `
+        AND (${accountVisibleSql('pa')} OR pa.github_id IN (${conn.neighboursSql('$2')}))`;
+  const { rows } = await pool.query(
+    `(${one('request')}) UNION ALL (${one('invite', addressable)})`,
+    [guildId, ownerGithubId, REQUEST_EXPIRY_DAYS, LIST_MAX],
+  );
+  const { incoming, outgoing, unseen } = splitQueue(rows, 'request');
+  if (unseen.length) {
+    await pool.query(
+      `UPDATE platform_identity_guild_requests SET seen_at = now()
+        WHERE id = ANY($1::bigint[]) AND guild_id = $2 AND kind = 'request' AND seen_at IS NULL`,
+      [unseen, guildId],
+    );
+  }
+  return { incoming, outgoing };
+}
+
+// ---------------------------------------------------------------------------
+// The public read (D4)
+// ---------------------------------------------------------------------------
+
+// A PUBLIC guild's page data, or null. An unlisted guild answers null to
+// everyone, its own members included — the read takes no viewer, so it cannot
+// vary by one. The roster is shown_publicly AND accountVisibleSql, ordered only
+// by what it publishes (ADR 0255), capped at LIST_MAX; `size` is the length of
+// the list returned, never a total beside it (D4: there is no "+N more").
+async function getPublicGuild(slug, { pool = defaultPool } = {}) {
+  const g = await pool.query(
+    `SELECT id, slug, name, description, created_at
+       FROM platform_identity_guilds
+      WHERE lower(slug) = $1 AND visibility = 'public'`,
+    [slug],
+  );
+  const guild = g.rows[0];
+  if (!guild) return null;
+  const { rows } = await pool.query(
+    `SELECT ${PERSON_COLUMNS}, m.membership_kind
+       FROM platform_identity_guild_members m
+       JOIN platform_identity_accounts pa ON pa.github_id = m.github_id
+      WHERE m.guild_id = $1 AND m.shown_publicly AND ${accountVisibleSql('pa')}
+      ORDER BY (m.membership_kind = 'owner') DESC, lower(pa.handle)
+      LIMIT $2`,
+    [guild.id, LIST_MAX],
+  );
+  const { id, ...shown } = guild;
+  return { guild: shown, members: rows, size: rows.length };
+}
+
+module.exports = {
+  GUILD_VISIBILITIES,
+  NAME_MAX_CHARS,
+  DESCRIPTION_MAX_CHARS,
+  INVITE_BATCH_MAX,
+  LIST_MAX,
+  normalizeGuildSlug,
+  lookupSlug,
+  createGuild,
+  getMembership,
+  updateGuild,
+  dissolveGuild,
+  listMyGuilds,
+  listMemberRoster,
+  setMembershipFlags,
+  leaveGuild,
+  removeMember,
+  transferOwnership,
+  requestToJoin,
+  inviteHandles,
+  acceptRequest,
+  declineRequest,
+  cancelRequest,
+  listMyRequests,
+  listGuildRequests,
+  getPublicGuild,
+};