@bongos/core 1.19.1026 → 1.19.1027

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);

package/modules/public-landing/public/terms.html

@@ -65,10 +65,10 @@
     <h2>Your work across projects</h2>
     <p>Each {{productName}} project you build in reports a summary of your work there to the platform: the {{currency}} you earned, the works you shipped, your karma, the rank that project gave you, the roles you worked in, and when you were last active. The platform adds these up across every project into one cross-project record. Projects report this themselves — the platform does not read their databases.</p>
     <p><b>These numbers describe; they do not govern.</b> Your cross-project record is descriptive analytics and never authority. What you may do inside any project is decided by that project alone, from its own records, at the moment you ask. A large record grants nothing and a hidden one takes nothing away; no project is required to read it, and none may treat it as permission. A rank shown here is that project&rsquo;s own standing for you, as that project reported it &mdash; the platform holds no rank of its own.</p>
-    <p><b>What is public.</b> Once you have signed in here and accepted these terms, your profile and that record are public by default: at your handle&rsquo;s page, in the people directory, to project owners looking for people to work with, and to search engines. An account that has never signed in here stays provisional and is published nowhere.</p>
+    <p><b>What is public.</b> Once you have signed in to a project with your platform account and accepted these terms, your profile and that record are public by default: at your handle&rsquo;s page, in the people directory, to project owners looking for people to work with, and to search engines. An account that has never signed in to a project that way stays provisional and is published nowhere.</p>
     <p><b>What you control.</b> From your settings you can hide your statistics, drop out of the recruiting directory, or make your account private. Each takes effect immediately, everywhere, including on a page someone already has open. Hiding removes the platform&rsquo;s combined view; it does not retract the per-project numbers each project publishes itself, so a determined reader could still add them up the hard way.</p>
-    <p><b>Your acceptance is recorded.</b> The platform stores the date you accepted these terms, and which version, on your account. It is written by signing in here, and only once &mdash; signing in again does not change the original date. This is version <b>2026-08-29</b>.</p>
-    <p><b>Accounts from before these terms.</b> If your account already existed when this version took effect, the platform accepted it on your behalf, rather than waiting for you to sign in, and dated it the day that was done. The record marks that acceptance as grandfathered, so it is never mistaken for one you gave, and your own acceptance replaces it the next time you sign in.</p>
+    <p><b>Your acceptance is recorded.</b> The platform stores the date you accepted these terms, and which version, on your account. It is written when you sign in to a project with your platform account, and only once &mdash; signing in again does not change the date you accepted. This is version <b>2026-08-29</b>.</p>
+    <p><b>Accounts from before these terms.</b> If your account already existed when this version took effect, the platform accepted it on your behalf, rather than waiting for you to sign in, and dated it the day that was done. The record marks that acceptance as grandfathered, so it is never mistaken for one you gave, and your own acceptance replaces it the next time you sign in to a project.</p>
     <!--apex-only:end-->
     <h2>Fair use</h2>
     <p>Don't use {{productName}} to break the law, to attack this site or other people's projects, to mine, spam or otherwise abuse hosted resources, or to harass other builders. The owner may deactivate a builder or take a project offline for breaking these, and may set further house rules inside the hall.</p>