@bongos/core 1.19.1026 → 1.19.1028

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

@@ -0,0 +1,100 @@
+-- platform_identity_025_guilds.sql — guilds on the hub (task 1002300, R24;
+-- ADR 0336 D1, whose migration sketch this is, amended by ADR 0337 D4.4).
+--
+-- WHAT THIS IS. Three tables: the guild, its members, and the open invites and
+-- join requests between them. A guild is account-global, so it lives beside
+-- connections in platform-identity rather than beside core goal_members (a goal
+-- is an instance-local work container; a guild is a cross-project group of
+-- people). A standalone instance never enables this module, so it has no guild
+-- surface at all.
+--
+-- THE SHAPE CARRIES THE RULES, so no route has to remember them:
+--   * visibility has NO DEFAULT — the creator chooses public or unlisted, and a
+--     silent default would decide a privacy question for them (ADR 0336 D1);
+--   * there is no creator column — the owner ROW is the authority, and a
+--     permanent "created by" would keep a departed creator tied to the guild;
+--   * membership_kind, never `role` — ADR 0174 reserves that word for the crafts;
+--   * exactly one owner per guild is a partial unique index, held by the
+--     database. Because it is checked row by row and a partial index cannot be
+--     deferred, a transfer is two statements in one transaction (ADR 0336 D2);
+--   * shown_publicly has NO DEFAULT — it records what the join card showed
+--     (ADR 0336 D4 §3), so every insert must say it;
+--   * counted_in_totals DEFAULTS TRUE — ADR 0337 D4.4: every member counts in the
+--     guild's rounded totals unless they switch it off for that guild. The
+--     request row carries the requester's choice until the owner accepts.
+--
+-- Leaving, removal and dissolving HARD-DELETE (ADR 0336 D2, the ADR 0202 D2
+-- reason); the FKs cascade so a dissolved guild takes its open requests with it.
+--
+-- NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank, credit or admission
+-- path reads these tables; a guild membership admits nobody anywhere.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). CREATE only, so the
+-- previous release still runs against this schema. Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_guilds (
+  id          bigserial PRIMARY KEY,
+  -- The /g/<slug> key, fixed at creation (ADR 0336 D6): the handle charset,
+  -- lowercase, 2-39 characters. Canonical form is enforced here as well as in
+  -- the domain, so a direct write cannot store a slug the URL cannot carry.
+  slug        text NOT NULL CONSTRAINT platform_identity_guilds_slug_form
+                CHECK (slug ~ '^[a-z0-9][a-z0-9-]{0,37}[a-z0-9]$'),
+  name        text NOT NULL CONSTRAINT platform_identity_guilds_name_len
+                CHECK (length(name) BETWEEN 1 AND 80),
+  description text CONSTRAINT platform_identity_guilds_description_len
+                CHECK (description IS NULL OR length(description) <= 500),
+  visibility  text NOT NULL CHECK (visibility IN ('public', 'unlisted')),
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_guilds_slug
+  ON platform_identity_guilds (lower(slug));
+
+CREATE TABLE IF NOT EXISTS platform_identity_guild_members (
+  guild_id          bigint NOT NULL REFERENCES platform_identity_guilds(id) ON DELETE CASCADE,
+  github_id         bigint NOT NULL,
+  membership_kind   text NOT NULL DEFAULT 'member' CHECK (membership_kind IN ('owner', 'member')),
+  shown_publicly    boolean NOT NULL,
+  counted_in_totals boolean NOT NULL DEFAULT true,
+  joined_at         timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (guild_id, github_id)
+);
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_guild_owner
+  ON platform_identity_guild_members (guild_id) WHERE membership_kind = 'owner';
+CREATE INDEX IF NOT EXISTS platform_identity_guild_members_account
+  ON platform_identity_guild_members (github_id);
+
+CREATE TABLE IF NOT EXISTS platform_identity_guild_requests (
+  id                bigserial PRIMARY KEY,
+  guild_id          bigint NOT NULL REFERENCES platform_identity_guilds(id) ON DELETE CASCADE,
+  github_id         bigint NOT NULL,
+  kind              text NOT NULL CHECK (kind IN ('invite', 'request')),
+  status            text NOT NULL DEFAULT 'pending'
+                      CHECK (status IN ('pending', 'accepted', 'rejected', 'cancelled', 'expired')),
+  counted_in_totals boolean NOT NULL DEFAULT true,
+  seen_at           timestamptz,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  resolved_at       timestamptz
+);
+-- At most one OPEN row per (guild, person), whichever direction it runs, so an
+-- invite and a request for the same pair collide instead of racing.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_platform_identity_guild_requests_open
+  ON platform_identity_guild_requests (guild_id, github_id) WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS platform_identity_guild_requests_account
+  ON platform_identity_guild_requests (github_id, status);
+
+COMMENT ON TABLE platform_identity_guilds IS
+  'Hub guilds (ADR 0336). visibility is the owner''s choice: public (a public page, takes join requests) or unlisted (no public existence, invites only). No creator column: the owner row in platform_identity_guild_members is the authority. Descriptive only, never authority (ADR 0016).';
+
+COMMENT ON COLUMN platform_identity_guild_members.shown_publicly IS
+  'This member agreed to appear on the guild''s PUBLIC page (ADR 0336 D4). Set from the visibility the join card showed; changing the guild''s visibility changes only the owner''s flag, never another member''s.';
+
+COMMENT ON COLUMN platform_identity_guild_members.counted_in_totals IS
+  'The member''s per-guild switch for the guild''s rounded totals (ADR 0337 D4.4). On by default; the member may turn it off for any guild at any time.';
+
+COMMENT ON COLUMN platform_identity_guild_requests.status IS
+  'pending -> accepted | rejected (declined: SILENT, and a 90-day cooldown that swallows a re-ask of the same kind) | cancelled | expired (30 days, resolved at write time). The connections lifecycle, verbatim (ADR 0336 D3, ADR 0202 D2).';
+
+COMMIT;

package/modules/platform-identity/module.json

@@ -10,7 +10,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard"],
+    "routes": ["sso", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull"]
   },

package/modules/platform-identity/read-rate-limit.js

@@ -4,8 +4,9 @@
 // perIpSlidingWindow) reaches modules only as ready-built instances on the
 // doorway (ADR 0209: an instance per budget), none of which is this module's.
 // This is the module-side twin of that function — same 429 envelope and
-// headers — written once (task 1002978) and mounted by both community reads
-// (routes/community-leaderboard.js, routes/community-search.js).
+// headers — written once (task 1002978) and mounted by the community reads
+// (routes/community-leaderboard.js, routes/community-search.js) and the public
+// guild read (routes/guilds-public.js).
 // routes/public-profile.js and routes/sso.js still carry older vendored copies.
 'use strict';
 

package/modules/platform-identity/routes/guilds-public.js

@@ -0,0 +1,57 @@
+// modules/platform-identity/routes/guilds-public.js — the PUBLIC guild read
+// (task 1002300, R24; ADR 0336 D4). Its own file because every route in
+// routes/guilds.js is own-scoped and held there by tests/own_scope_guard.mjs;
+// this one is deliberately not.
+//
+//   GET /guilds/:slug — a PUBLIC guild's name, description, public roster and
+//   size. 404 for an unknown slug AND for an unlisted guild, to everyone, its own
+//   members included: the read takes no viewer, so it cannot vary by one (the
+//   private-profile rule, ADR 0171 D4). Members reach an unlisted guild through
+//   the own-scope GET /guilds/:slug/members. The page at /g/<slug> is task
+//   1002301's; this is its read.
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const guilds = require('../guilds');
+const { createReadRateLimit } = require('../read-rate-limit');
+
+const { pool } = api;
+
+// Resolved at call time, the community-search.js precedent: a proof that stubs a
+// partial doorway can still require() this file.
+let resolvedLog = null;
+function logError(msg) {
+  if (!resolvedLog) resolvedLog = typeof api.logger === 'function' ? api.logger('platform-identity') : { error: () => {} };
+  resolvedLog.error(msg);
+}
+
+// Per-IP read cap for this UNAUTHENTICATED route, its own budget. The global
+// limiter meters writes only, and a roster read maps handles to guilds, so an
+// uncapped scraper could walk the slug space at line rate.
+const guildReadRateLimit = createReadRateLimit({ scope: 'guild-public-read', limit: 120 });
+
+module.exports = function guildPublicRoutes() {
+  const router = express.Router();
+
+  // rank: public — a public guild's page data. The roster is the members who
+  // agreed to be shown AND whose own accounts are publicly visible (ADR 0336 D4);
+  // size is that roster's length. no-store: a hide or a visibility flip must beat
+  // every cache (ADR 0171 D5).
+  router.get('/guilds/:slug', guildReadRateLimit, async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    try {
+      const slug = guilds.lookupSlug(req.params.slug);
+      const out = slug ? await guilds.getPublicGuild(slug, { pool }) : null;
+      if (!out) return res.fail('guild_not_found', 404);
+      res.json({ guild: out.guild, members: out.members, size: out.size });
+    } catch (err) {
+      logError(`GET /guilds/:slug failed: ${err && err.message}`);
+      res.fail('guild_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

package/modules/platform-identity/routes/guilds.js

@@ -0,0 +1,393 @@
+// modules/platform-identity/routes/guilds.js — the guild API, own-scope half
+// (task 1002300, R24; ADR 0336 D2–D4 + D6, ADR 0337 D4.4). The one PUBLIC read,
+// GET /guilds/:slug, lives in routes/guilds-public.js, because every route in
+// this file sits behind requireBuilder and tests/own_scope_guard.mjs holds it.
+//
+// EVERY ROUTE HERE IS OWN-SCOPED. The acting account is always
+// req.builder.github_id. A guild is named by slug, a person by public handle,
+// an invite or request by its row id — none of them is a way to act AS someone
+// else. Owner-only acts are re-asserted inside each statement, so the route's
+// pre-check is a clearer error, never the only gate.
+//
+//   POST   /guilds                         create {slug, name, description?, visibility}
+//   GET    /me/guilds                      my guilds, with my own two switches
+//   GET    /me/guild-requests              invites to me (the card) + requests I sent
+//   GET    /guilds/:slug/members           the members' roster (members only; 404 else)
+//   PATCH  /guilds/:slug/membership        my switches {shown_publicly?, counted_in_totals?}
+//   DELETE /guilds/:slug/membership        leave (the owner transfers first, or is last and dissolves)
+//   POST   /guilds/:slug/requests          ask to join a PUBLIC guild {counted_in_totals?}
+//   PATCH  /guilds/:slug                   owner: {name?, description?, visibility?}
+//   DELETE /guilds/:slug                   owner: dissolve
+//   POST   /guilds/:slug/invites           owner: invite {handles: [≤25]}
+//   GET    /guilds/:slug/requests          owner: join requests + invites still out
+//   DELETE /guilds/:slug/members/:handle   owner: remove a member
+//   POST   /guilds/:slug/transfer          owner: hand ownership to a member {handle}
+//   POST   /guild-requests/:id/accept      invitee {visibility (the card's), counted_in_totals?} or owner
+//   POST   /guild-requests/:id/decline     invitee or owner; SILENT 204
+//   DELETE /guild-requests/:id             whoever opened it: cancel
+//
+// A GUILD IS NEVER AUTHORITY (ADR 0016 / ADR 0141). no-store everywhere: these
+// payloads are privacy-filtered per viewer (ADR 0171 D5).
+//
+// Reaches core only through the doorway (ADR 0083).
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pi = require('../platform-identity');
+const guilds = require('../guilds');
+const { isAccountActive } = require('../account-visibility');
+
+const { pool, requireBuilder, validateOrRespond, parsePagination } = api;
+const log = api.logger('platform-identity');
+
+// A request row id is a bigserial. Anything else is 404, not 400: an id past the
+// bigint range would reach Postgres as a 22003 and answer 500, and a different
+// answer for a different id is a probe (the routes/connections.js rule, with the
+// range checked exactly rather than by digit count).
+const BIGINT_MAX = 9223372036854775807n;
+function requestId(req) {
+  const raw = String(req.params.id || '');
+  return /^\d{1,19}$/.test(raw) && BigInt(raw) <= BIGINT_MAX ? raw : null;
+}
+
+// The caller's platform account, or a { fail }. The consent axis floors the
+// whole feature (ADR 0336 D3): a provisional or terms-less account cannot
+// create, ask, accept or appear anywhere.
+async function actingAccount(builder) {
+  const githubId = builder && builder.github_id;
+  if (!pi.isNumericGithubId(githubId)) {
+    return { fail: ['no_platform_identity', { status: 400, message: 'this session has no platform account' }] };
+  }
+  const acct = await pi.getAccount(githubId, { pool });
+  if (!isAccountActive(acct)) {
+    return { fail: ['profile_provisional', { status: 403, message: 'sign in to the platform once to activate your profile before using guilds' }] };
+  }
+  return { githubId };
+}
+
+// The caller's membership of the guild in the path, or a { fail }. A non-member
+// gets the same 404 as a guild that does not exist, so no guild route confirms
+// an unlisted guild to a stranger. (One honest limit, inherent to a global slug:
+// POST /guilds with a taken slug must answer "taken", unlisted or not.)
+async function memberOf(me, rawSlug) {
+  const slug = guilds.lookupSlug(rawSlug);
+  const guild = slug ? await guilds.getMembership(slug, me.githubId, { pool }) : null;
+  if (!guild) return { fail: ['guild_not_found', 404] };
+  return { guild, slug };
+}
+
+// memberOf, narrowed to the owner. A member already knows the guild exists, so
+// they may be told plainly that the act is the owner's.
+async function ownerOf(me, rawSlug) {
+  const out = await memberOf(me, rawSlug);
+  if (out.fail) return out;
+  if (out.guild.membership_kind !== 'owner') {
+    return { fail: ['guild_owner_only', { status: 403, message: 'only the guild owner can do that' }] };
+  }
+  return out;
+}
+
+// The guild fields a member-facing response carries. The row id stays internal.
+function guildView(g) {
+  return { slug: g.slug, name: g.name, description: g.description, visibility: g.visibility };
+}
+
+// One try/catch shape for every handler: the act, or a logged 500.
+function handle(label, code, fn) {
+  return async (req, res) => {
+    try {
+      await fn(req, res);
+    } catch (err) {
+      log.error({ err: err && err.message }, `${label} failed`);
+      res.fail(code, { status: 500, message: 'internal error' });
+    }
+  };
+}
+
+const COUNTED = { type: 'boolean' };
+
+module.exports = function guildRoutes() {
+  const router = express.Router();
+
+  router.use(['/guilds', '/me/guilds', '/me/guild-requests', '/guild-requests'], (req, res, next) => {
+    res.set('Cache-Control', 'no-store');
+    next();
+  });
+
+  // rank: any-builder — create a guild. The creator becomes its one owner, and
+  // chooses its visibility: there is no default (ADR 0336 D1).
+  router.post('/guilds', requireBuilder, handle('POST /guilds', 'guild_create_failed', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      slug: { required: true, type: 'string', minLength: 1, maxLength: 39 },
+      name: { required: true, type: 'string', minLength: 1, maxLength: guilds.NAME_MAX_CHARS },
+      description: { type: 'string', maxLength: guilds.DESCRIPTION_MAX_CHARS },
+      visibility: { required: true, type: 'string', enum: guilds.GUILD_VISIBILITIES },
+    })) return;
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const s = guilds.normalizeGuildSlug(req.body.slug);
+    if (s.error === 'slug_reserved') return res.fail('guild_slug_reserved', { status: 400, message: 'that slug is reserved' });
+    if (s.error) return res.fail('guild_slug_invalid', { status: 400, message: 'a slug is 2-39 lowercase letters, digits or inner hyphens' });
+    const name = req.body.name.trim();
+    if (!name) return res.fail('guild_name_required', { status: 400, message: 'a guild needs a name' });
+    const out = await guilds.createGuild({
+      githubId: me.githubId, slug: s.slug, name,
+      description: (req.body.description || '').trim() || null,
+      visibility: req.body.visibility,
+    }, { pool });
+    if (out.taken) return res.fail('guild_slug_taken', { status: 409, message: 'that slug is taken' });
+    res.status(201).json({ guild: out.guild });
+  }));
+
+  // rank: any-builder — MY guilds, each with my own two switches. count is the
+  // array's own length.
+  router.get('/me/guilds', requireBuilder, handle('GET /me/guilds', 'guilds_read_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const { limit, offset } = parsePagination(req, { defaultLimit: guilds.LIST_MAX, maxLimit: guilds.LIST_MAX });
+    const mine = await guilds.listMyGuilds({ githubId: me.githubId, limit, offset }, { pool });
+    res.json({ guilds: mine, count: mine.length });
+  }));
+
+  // rank: any-builder — MY queue: invites addressed to me, each carrying the
+  // card (the guild's current visibility, which an accept must echo back), and
+  // the join requests I sent. Stamps seen_at on the invites.
+  router.get('/me/guild-requests', requireBuilder, handle('GET /me/guild-requests', 'guild_requests_read_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const { incoming, outgoing } = await guilds.listMyRequests({ githubId: me.githubId }, { pool });
+    res.json({ incoming, outgoing, incoming_count: incoming.length, outgoing_count: outgoing.length });
+  }));
+
+  // rank: any-builder — the members' roster, for members only (the own-scope
+  // door to an unlisted guild, ADR 0336 D4). A private member is listed here,
+  // to fellow members, and on no public page.
+  router.get('/guilds/:slug/members', requireBuilder, handle('GET /guilds/:slug/members', 'guild_members_read_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const m = await memberOf(me, req.params.slug);
+    if (m.fail) return res.fail(...m.fail);
+    const { limit, offset } = parsePagination(req, { defaultLimit: guilds.LIST_MAX, maxLimit: guilds.LIST_MAX });
+    const members = await guilds.listMemberRoster({ guildId: m.guild.id, limit, offset }, { pool });
+    res.json({
+      guild: guildView(m.guild),
+      you: {
+        membership_kind: m.guild.membership_kind,
+        shown_publicly: m.guild.shown_publicly,
+        counted_in_totals: m.guild.counted_in_totals,
+      },
+      members,
+      count: members.length,
+    });
+  }));
+
+  // rank: any-builder — MY switches in one guild: shown on its public page
+  // (ADR 0336 D4) and counted in its totals (ADR 0337 D4.4). Each optional, at
+  // least one required, both keyed on the session.
+  router.patch('/guilds/:slug/membership', requireBuilder, handle('PATCH /guilds/:slug/membership', 'guild_membership_update_failed', async (req, res) => {
+    if (validateOrRespond(req, res, { shown_publicly: { type: 'boolean' }, counted_in_totals: COUNTED })) return;
+    const { shown_publicly: shown, counted_in_totals: counted } = req.body || {};
+    if (shown == null && counted == null) {
+      return res.fail('nothing_to_update', { status: 400, message: 'send shown_publicly and/or counted_in_totals' });
+    }
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const slug = guilds.lookupSlug(req.params.slug);
+    const flags = slug ? await guilds.setMembershipFlags({
+      slug, githubId: me.githubId, shownPublicly: shown ?? null, countedInTotals: counted ?? null,
+    }, { pool }) : null;
+    if (!flags) return res.fail('guild_not_found', 404);
+    res.json(flags);
+  }));
+
+  // rank: any-builder — leave. The owner must transfer first unless they are the
+  // last member, when leaving dissolves the guild (ADR 0336 D2).
+  router.delete('/guilds/:slug/membership', requireBuilder, handle('DELETE /guilds/:slug/membership', 'guild_leave_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const m = await memberOf(me, req.params.slug);
+    if (m.fail) return res.fail(...m.fail);
+    const outcome = await guilds.leaveGuild({ guildId: m.guild.id, githubId: me.githubId }, { pool });
+    if (outcome === 'must_transfer') {
+      return res.fail('guild_owner_must_transfer', { status: 409, message: 'hand the guild to another member before you leave' });
+    }
+    if (!outcome) return res.fail('guild_not_found', 404);
+    res.json({ outcome });
+  }));
+
+  // rank: any-builder — ask to join. Only a PUBLIC guild takes requests, so an
+  // unlisted guild and an unknown slug are one 404 (ADR 0336 D3/D4). A request
+  // written and one swallowed by a decline cooldown answer identically.
+  router.post('/guilds/:slug/requests', requireBuilder, handle('POST /guilds/:slug/requests', 'guild_request_failed', async (req, res) => {
+    if (validateOrRespond(req, res, { counted_in_totals: COUNTED })) return;
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const slug = guilds.lookupSlug(req.params.slug);
+    const { outcome } = slug
+      ? await guilds.requestToJoin({ slug, githubId: me.githubId, countedInTotals: req.body?.counted_in_totals }, { pool })
+      : { outcome: 'not_found' };
+    if (outcome === 'not_found') return res.fail('guild_not_found', 404);
+    if (outcome === 'already_member') return res.fail('guild_already_member', { status: 409, message: 'you are already in this guild' });
+    if (outcome === 'already_open') return res.fail('guild_request_already_open', { status: 409, message: 'there is already an open invite or request between you and this guild' });
+    res.status(201).json({ status: 'pending' });
+  }));
+
+  // rank: any-builder — owner: edit name, description or visibility. The slug is
+  // fixed at creation (ADR 0336 D6), so it is not a field here.
+  router.patch('/guilds/:slug', requireBuilder, handle('PATCH /guilds/:slug', 'guild_update_failed', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      name: { type: 'string', minLength: 1, maxLength: guilds.NAME_MAX_CHARS },
+      description: { type: 'string', maxLength: guilds.DESCRIPTION_MAX_CHARS },
+      visibility: { type: 'string', enum: guilds.GUILD_VISIBILITIES },
+    })) return;
+    // The validator reads null as absent, so null is handled here: a name cannot
+    // be cleared, a description can (null or ''), and a null visibility is no
+    // change. Absent means "leave it".
+    const body = req.body || {};
+    if (body.name === undefined && body.description === undefined && body.visibility == null) {
+      return res.fail('nothing_to_update', { status: 400, message: 'send name, description and/or visibility' });
+    }
+    const name = body.name === undefined ? undefined : String(body.name ?? '').trim();
+    if (name === '') return res.fail('guild_name_required', { status: 400, message: 'a guild needs a name' });
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const o = await ownerOf(me, req.params.slug);
+    if (o.fail) return res.fail(...o.fail);
+    const guild = await guilds.updateGuild({
+      guildId: o.guild.id, githubId: me.githubId, name,
+      description: body.description === undefined ? undefined : String(body.description ?? '').trim(),
+      visibility: body.visibility ?? undefined,
+    }, { pool });
+    if (!guild) return res.fail('guild_not_found', 404);
+    res.json({ guild });
+  }));
+
+  // rank: any-builder — owner: dissolve. Hard delete, cascading to every
+  // membership and open request (ADR 0336 D2).
+  router.delete('/guilds/:slug', requireBuilder, handle('DELETE /guilds/:slug', 'guild_dissolve_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const o = await ownerOf(me, req.params.slug);
+    if (o.fail) return res.fail(...o.fail);
+    const ok = await guilds.dissolveGuild({ guildId: o.guild.id, githubId: me.githubId }, { pool });
+    if (!ok) return res.fail('guild_not_found', 404);
+    res.json({ outcome: 'dissolved' });
+  }));
+
+  // rank: any-builder — owner: invite up to INVITE_BATCH_MAX builders by handle,
+  // each an ordinary individual invite (ADR 0336 D3). Unlisted guilds take
+  // invites. count is the array's own length.
+  router.post('/guilds/:slug/invites', requireBuilder, handle('POST /guilds/:slug/invites', 'guild_invite_failed', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      handles: { required: true, type: 'array', itemsType: 'string', maxItems: guilds.INVITE_BATCH_MAX },
+    })) return;
+    if (!req.body.handles.length) return res.fail('handles_required', { status: 400, message: 'name at least one handle' });
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const o = await ownerOf(me, req.params.slug);
+    if (o.fail) return res.fail(...o.fail);
+    const results = await guilds.inviteHandles({
+      guildId: o.guild.id, ownerGithubId: me.githubId, handles: req.body.handles,
+    }, { pool });
+    res.json({ results, count: results.length });
+  }));
+
+  // rank: any-builder — owner: the join requests to decide and the invites
+  // still out. Stamps seen_at on the requests only.
+  router.get('/guilds/:slug/requests', requireBuilder, handle('GET /guilds/:slug/requests', 'guild_requests_read_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const o = await ownerOf(me, req.params.slug);
+    if (o.fail) return res.fail(...o.fail);
+    const { incoming, outgoing } = await guilds.listGuildRequests({
+      guildId: o.guild.id, ownerGithubId: me.githubId,
+    }, { pool });
+    res.json({ incoming, outgoing, incoming_count: incoming.length, outgoing_count: outgoing.length });
+  }));
+
+  // rank: any-builder — owner: remove a member (never the owner). Hard delete.
+  router.delete('/guilds/:slug/members/:handle', requireBuilder, handle('DELETE /guilds/:slug/members/:handle', 'guild_member_remove_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const o = await ownerOf(me, req.params.slug);
+    if (o.fail) return res.fail(...o.fail);
+    const target = guilds.lookupSlug(req.params.handle);
+    const ok = target ? await guilds.removeMember({
+      guildId: o.guild.id, ownerGithubId: me.githubId, handle: target,
+    }, { pool }) : false;
+    if (!ok) return res.fail('guild_member_not_found', 404);
+    res.json({ outcome: 'removed' });
+  }));
+
+  // rank: any-builder — owner: hand ownership to an existing member. Two
+  // statements in one transaction (ADR 0336 D2).
+  router.post('/guilds/:slug/transfer', requireBuilder, handle('POST /guilds/:slug/transfer', 'guild_transfer_failed', async (req, res) => {
+    if (validateOrRespond(req, res, { handle: { required: true, type: 'string', minLength: 1, maxLength: 39 } })) return;
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const o = await ownerOf(me, req.params.slug);
+    if (o.fail) return res.fail(...o.fail);
+    const target = guilds.lookupSlug(req.body.handle);
+    const outcome = target ? await guilds.transferOwnership({
+      guildId: o.guild.id, ownerGithubId: me.githubId, handle: target,
+    }, { pool }) : 'not_member';
+    if (outcome === 'not_member') return res.fail('guild_member_not_found', 404);
+    if (outcome !== 'transferred') return res.fail('guild_owner_only', { status: 403, message: 'only the guild owner can do that' });
+    res.json({ outcome });
+  }));
+
+  // rank: any-builder — accept an invite addressed to ME, or (as the guild's
+  // owner) a request to join it. An invite accept must echo the visibility its
+  // card showed; if the guild changed since, 409 and the card re-renders
+  // (ADR 0336 D4 §3). Any row the caller may not accept is 404.
+  router.post('/guild-requests/:id/accept', requireBuilder, handle('POST /guild-requests/:id/accept', 'guild_accept_failed', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      visibility: { type: 'string', enum: guilds.GUILD_VISIBILITIES },
+      counted_in_totals: COUNTED,
+    })) return;
+    const id = requestId(req);
+    if (!id) return res.fail('guild_request_not_found', 404);
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const out = await guilds.acceptRequest({
+      id, githubId: me.githubId,
+      cardVisibility: req.body?.visibility ?? null,
+      countedInTotals: req.body?.counted_in_totals ?? null,
+    }, { pool });
+    if (out.outcome === 'card_required') {
+      return res.fail('guild_card_visibility_required', { status: 400, message: 'send the visibility your invite card showed' });
+    }
+    if (out.outcome === 'visibility_changed') {
+      return res.fail('guild_visibility_changed', 409, { visibility: out.visibility });
+    }
+    if (out.outcome !== 'accepted') return res.fail('guild_request_not_found', 404);
+    res.json({ status: 'accepted' });
+  }));
+
+  // rank: any-builder — decline an invite to ME, or (as owner) a request to my
+  // guild. SILENT: 204, and the other side is never told.
+  router.post('/guild-requests/:id/decline', requireBuilder, handle('POST /guild-requests/:id/decline', 'guild_decline_failed', async (req, res) => {
+    const id = requestId(req);
+    if (!id) return res.fail('guild_request_not_found', 404);
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const ok = await guilds.declineRequest({ id, githubId: me.githubId }, { pool });
+    if (!ok) return res.fail('guild_request_not_found', 404);
+    res.status(204).end();
+  }));
+
+  // rank: any-builder — cancel a row I opened: my request, or (as owner) an
+  // invite my guild sent.
+  router.delete('/guild-requests/:id', requireBuilder, handle('DELETE /guild-requests/:id', 'guild_cancel_failed', async (req, res) => {
+    const id = requestId(req);
+    if (!id) return res.fail('guild_request_not_found', 404);
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const ok = await guilds.cancelRequest({ id, githubId: me.githubId }, { pool });
+    if (!ok) return res.fail('guild_request_not_found', 404);
+    res.json({ outcome: 'cancelled' });
+  }));
+
+  return router;
+};

package/modules/platform-identity/terms-acceptance.js

@@ -24,7 +24,10 @@
 //
 // WHY THE CALLER CANNOT FORGE ONE. These fragments have exactly one call site:
 // upsertAccount's `activate` branch, whose only caller is /sso/authorize
-// (routes/sso.js). There `activate: true` is a SOURCE LITERAL and every other
+// (routes/sso.js) — the leg a builder passes through when they use their platform
+// account to sign in to a PROJECT. Signing in to the hub itself does not reach it
+// and records nothing (blocker 1000124; task 1003361 adds that capture point),
+// which is why /terms names a project sign-in. There `activate: true` is a SOURCE LITERAL and every other
 // field comes from the hub's own resolved session — the ADR 0205 D3 property
 // established for recordFederatedSignin by task 1003340. No request-body field
 // reaches these statements, which is the whole point: an acceptance record a
@@ -40,7 +43,7 @@
 // accounts that already existed were accepted on their owner's behalf, and the
 // record says so rather than passing that off as a sign-in. A grandfather is not
 // an acceptance its owner gave, so it is the one acceptance that does not
-// "stand": the owner's next sign-in replaces it with their own. This file only
+// "stand": the owner's next project sign-in replaces it with their own. This file only
 // ever READS the marker. tests/terms_acceptance.mjs holds both rules, and fails
 // any other server file that writes these columns or names the marker.
 //
@@ -57,6 +60,10 @@
 //
 // Date-stamped rather than numbered: the page says "Version <this>", and a
 // reader comparing page to record should not have to translate.
+//
+// The terms_version column it fills is WRITE-ONLY today, on purpose: nothing
+// reads it until a revision needs to know who accepted which text (ADR 0213 D5).
+// It is not dead — dropping it would erase exactly that answer.
 const TERMS_VERSION = '2026-08-29';
 
 // A Postgres placeholder, e.g. '$5'. Interpolated into SQL, so it is validated
@@ -73,9 +80,11 @@ function acceptanceInsertColumns() {
   return ', terms_accepted_at, terms_version, terms_accepted_source';
 }
 
-// The matching VALUES fragment. A row created by a NON-activating caller
-// (ensureAccount's check-in / device-poll path) gets NULL — fail-closed: no hub
-// session witnessed that human, so there is no acceptance to record.
+// The matching VALUES fragment. A row created by a NON-activating upsert — the
+// device poll (POST /sso/device/poll) or a handle change (PATCH /me/handle) —
+// gets NULL: fail-closed, because no sign-in the hub witnessed recorded an
+// acceptance. The federated check-in never reaches this at all; it writes
+// through ensureAccount, whose insert-only statement names none of these columns.
 function acceptanceInsertValues(activateParam, versionParam) {
   assertPlaceholder('acceptanceInsertValues', activateParam);
   assertPlaceholder('acceptanceInsertValues', versionParam);