@bongos/core 1.21.56 → 1.21.58

package/modules/ui-design/kit/fixtures/guilds.json

@@ -0,0 +1,73 @@
+{
+  "forge-crew": {
+    "public": {
+      "guild": {
+        "slug": "forge-crew",
+        "name": "Forge Crew",
+        "description": "Builders who like the unglamorous parts: migrations, test harnesses, the deploy path. We pick up the work nobody else claims.",
+        "created_at": "2026-09-12T10:20:00.000Z"
+      },
+      "members": [
+        { "handle": "mara-quinn", "display_name": "Mara Quinn", "avatar_url": "/__kit/avatar.svg", "membership_kind": "owner" },
+        { "handle": "ines-duarte", "display_name": "Ines Duarte", "avatar_url": null, "membership_kind": "member" },
+        { "handle": "kip", "display_name": "Kip", "avatar_url": "/__kit/avatar.svg", "membership_kind": "member" },
+        { "handle": "theo-park", "display_name": "Theo Park", "avatar_url": "/__kit/avatar.svg", "membership_kind": "member" }
+      ],
+      "size": 4,
+      "totals": { "credits": 2000, "works_shipped": 100, "karma": 50, "projects": 0, "as_of": "2026-10-01T03:00:00.000Z" }
+    },
+    "members": {
+      "guild": {
+        "slug": "forge-crew",
+        "name": "Forge Crew",
+        "description": "Builders who like the unglamorous parts: migrations, test harnesses, the deploy path. We pick up the work nobody else claims.",
+        "visibility": "public"
+      },
+      "you": { "membership_kind": "member", "shown_publicly": false, "counted_in_totals": true },
+      "members": [
+        { "handle": "mara-quinn", "display_name": "Mara Quinn", "avatar_url": "/__kit/avatar.svg", "membership_kind": "owner" },
+        { "handle": "builder", "display_name": "A Builder", "avatar_url": "/__kit/avatar.svg", "membership_kind": "member" },
+        { "handle": "ines-duarte", "display_name": "Ines Duarte", "avatar_url": null, "membership_kind": "member" },
+        { "handle": "kip", "display_name": "Kip", "avatar_url": "/__kit/avatar.svg", "membership_kind": "member" },
+        { "handle": "sol-reyes", "display_name": "Sol Reyes", "avatar_url": null, "membership_kind": "member" },
+        { "handle": "theo-park", "display_name": "Theo Park", "avatar_url": "/__kit/avatar.svg", "membership_kind": "member" }
+      ],
+      "count": 6
+    }
+  },
+  "night-shift": {
+    "public": null,
+    "members": {
+      "guild": {
+        "slug": "night-shift",
+        "name": "Night Shift",
+        "description": "",
+        "visibility": "unlisted"
+      },
+      "you": { "membership_kind": "owner", "shown_publicly": false, "counted_in_totals": false },
+      "members": [
+        { "handle": "builder", "display_name": "A Builder", "avatar_url": "/__kit/avatar.svg", "membership_kind": "owner" },
+        { "handle": "ines-duarte", "display_name": "Ines Duarte", "avatar_url": null, "membership_kind": "member" },
+        { "handle": "sol-reyes", "display_name": "Sol Reyes", "avatar_url": null, "membership_kind": "member" }
+      ],
+      "count": 3
+    }
+  },
+  "open-hands": {
+    "public": {
+      "guild": {
+        "slug": "open-hands",
+        "name": "Open Hands",
+        "description": "A newer guild for first-time builders. Ask anything.",
+        "created_at": "2026-10-03T16:05:00.000Z"
+      },
+      "members": [
+        { "handle": "ada-ng", "display_name": "Ada Ng", "avatar_url": "/__kit/avatar.svg", "membership_kind": "owner" },
+        { "handle": "ruth-okafor", "display_name": "Ruth Okafor", "avatar_url": null, "membership_kind": "member" }
+      ],
+      "size": 2,
+      "totals": null
+    },
+    "members": null
+  }
+}

package/modules/ui-design/kit/fixtures/me__guild-engagements.json

@@ -0,0 +1,7 @@
+{
+  "engagements": [
+    { "guild": { "slug": "forge-crew", "name": "Forge Crew" }, "kind": "apply", "project": { "name": "Tidepool", "origin": "https://tidepool.cloudbongos.com" }, "created_at": "2026-10-03T12:00:00.000Z" },
+    { "guild": { "slug": "forge-crew", "name": "Forge Crew" }, "kind": "invited", "project": { "name": "Lantern Works", "origin": "https://lantern-works.cloudbongos.com" }, "created_at": "2026-10-02T09:30:00.000Z" }
+  ],
+  "count": 2
+}

package/modules/ui-design/kit/serve.js

@@ -111,9 +111,12 @@ const FEEDS = {
 // /founding/genesis and /government/constitution (task 1004423) ship no default file: the
 // genesis home asks for them only in founding mode, so every existing render is unchanged,
 // and the genesis variants point them at their samples.
+// /me/guild-engagements (task 1002303, R27) is the mine view's guild cards: a guild applying
+// to a project, and a project that invited a guild, for the guilds the builder is in.
 const AUTHED = {
   '/my-projects': 'my-projects', '/my-projects/invites': 'my-projects__invites', '/founding/builders': 'founding-builders',
   '/founding/genesis': 'founding-genesis', '/government/constitution': 'government-constitution',
+  '/me/guild-engagements': 'me__guild-engagements',
 };
 const UNAUTH = { error: { code: 'unauthenticated', message: 'unauthenticated' } };
 
@@ -436,6 +439,85 @@ function handlePatch(res, body) {
   return json(res, 200, { handle: h, previous_handle: previous || null });
 }
 
+// The hub's guild page (task 1002301): GET /guilds/:slug (public), GET /guilds/:slug/members
+// and PATCH /guilds/:slug/membership (own-scope), answered from ONE set of guilds held for the
+// run (guilds.json, or the file a states file's stub.fixtures names), keyed by slug, each with
+// the public read's body (null = the 404 an unlisted or unknown guild answers) and the
+// signed-in builder's members read (null = not a member: the same 404). The PATCH mirrors the
+// route's schema — the two booleans, at least one — so a save the page re-reads comes back saved.
+let GUILDS = null;
+function guildsHeld() {
+  if (!GUILDS) {
+    const name = 'guilds';
+    GUILDS = JSON.parse(fs.readFileSync(path.join(FIXTURES, (ALIAS[name] || name) + '.json'), 'utf8'));
+  }
+  return GUILDS;
+}
+// a root-relative avatar is this stub's own (/__kit/avatar.svg), absolutised as me() does
+function withAvatars(body, origin) {
+  if (!body || !Array.isArray(body.members)) return body;
+  return { ...body, members: body.members.map((m) => (typeof m.avatar_url === 'string' && m.avatar_url.startsWith('/') ? { ...m, avatar_url: origin + m.avatar_url } : m)) };
+}
+const PAGE_ALIAS = { g: 'guild' };
+const GUILD_NOT_FOUND ={ error: { code: 'guild_not_found', message: 'guild_not_found' } };
+function guildRead(res, slug, half, origin) {
+  const g = guildsHeld()[String(slug).toLowerCase()];
+  const body = g && g[half];
+  return body ? json(res, 200, withAvatars(body, origin)) : json(res, 404, GUILD_NOT_FOUND);
+}
+function guildMembershipPatch(res, slug, body) {
+  const keys = Object.keys(body);
+  const bad = keys.find((k) => !['shown_publicly', 'counted_in_totals'].includes(k));
+  if (bad) return refuse(res, 400, 'validation_failed', `unknown field: ${bad}`);
+  for (const k of keys) if (typeof body[k] !== 'boolean') return refuse(res, 400, 'validation_failed', `${k} must be a boolean`);
+  if (!keys.length) return refuse(res, 400, 'nothing_to_update', 'send shown_publicly and/or counted_in_totals');
+  const g = guildsHeld()[String(slug).toLowerCase()];
+  if (!g || !g.members) return json(res, 404, GUILD_NOT_FOUND);
+  Object.assign(g.members.you, body);
+  return json(res, 200, { shown_publicly: g.members.you.shown_publicly, counted_in_totals: g.members.you.counted_in_totals });
+}
+
+// Guild engagements (task 1002303, R27; ADR 0365). The stub mirrors the routes' refusals so
+// a probe cannot pass on a body or a caller the server would refuse:
+//   POST /guilds/:slug/engagements { origin }  the owner files "this guild is applying to P":
+//     a non-member's 404, a member's owner-only 403, and ONE 404 for a project that is
+//     unknown or not (on the map AND public) — here, a featured-feed row whose orb is a planet;
+//   POST /projects/invite-guild { client_id, guild }  one hall hand-off link per member on the
+//     guild's PUBLIC roster; an unknown or unlisted guild is one 404;
+//   POST /my-projects/join's optional `guild` must name a held guild the builder is in with a
+//     held engagement (me__guild-engagements.json) for that project, else 409 and nothing relayed.
+const UNKNOWN_PROJECT = { error: { code: 'unknown_project', message: 'unknown_project' } };
+const sameOrigin = (a, b) => String(a || '').trim().toLowerCase().replace(/\/+$/, '') === String(b || '').trim().toLowerCase().replace(/\/+$/, '');
+function heldFixture(name) {
+  return JSON.parse(fs.readFileSync(path.join(FIXTURES, (ALIAS[name] || name) + '.json'), 'utf8'));
+}
+function guildEngagementPost(res, slug, body) {
+  const g = guildsHeld()[String(slug).toLowerCase()];
+  if (!g || !g.members) return json(res, 404, GUILD_NOT_FOUND);
+  if (g.members.you.membership_kind !== 'owner') return refuse(res, 403, 'guild_owner_only', 'only the guild owner can do that');
+  const bad = Object.keys(body).find((k) => k !== 'origin');
+  if (bad) return refuse(res, 400, 'validation_failed', `unknown field: ${bad}`);
+  if (typeof body.origin !== 'string' || !body.origin || body.origin.length > 300) return refuse(res, 400, 'validation_failed', 'origin must be a string');
+  const p = (heldFixture('featured').projects || []).find((x) => x.orb === 'planet' && sameOrigin(x.origin, body.origin));
+  if (!p) return json(res, 404, UNKNOWN_PROJECT);
+  return json(res, 200, { engagement: { guild: { slug: g.members.guild.slug, name: g.members.guild.name }, kind: 'apply', project: { name: p.name, origin: p.origin }, created_at: new Date().toISOString() } });
+}
+function guildInvitePost(res, body) {
+  const bad = Object.keys(body).find((k) => !['client_id', 'guild'].includes(k));
+  if (bad) return refuse(res, 400, 'validation_failed', `unknown field: ${bad}`);
+  if (typeof body.client_id !== 'string' || !body.client_id) return refuse(res, 400, 'validation_failed', 'client_id must be a string');
+  if (typeof body.guild !== 'string' || !body.guild || body.guild.length > 39) return refuse(res, 400, 'validation_failed', 'guild must be a string of at most 39 characters');
+  const g = guildsHeld()[body.guild.toLowerCase()];
+  if (!g || !g.public) return json(res, 404, GUILD_NOT_FOUND);
+  const invites = (g.public.members || []).map((m) => ({ handle: m.handle, display_name: m.display_name || null, invite_url: 'https://mercury.example.test/builders/watch?invite=' + encodeURIComponent(m.handle) }));
+  return json(res, 200, { invited: false, guild: { slug: g.public.guild.slug, name: g.public.guild.name }, invites, count: invites.length });
+}
+function guildEngagementLive(slug, origin) {
+  const g = typeof slug === 'string' && guildsHeld()[slug.toLowerCase()];
+  if (!g || !g.members) return false;
+  return (heldFixture('me__guild-engagements').engagements || []).some((e) => e.guild && e.guild.slug === slug.toLowerCase() && e.project && sameOrigin(e.project.origin, origin));
+}
+
 const server = http.createServer((req, res) => {
   const u = new URL(req.url, 'http://x');
   const p = u.pathname;
@@ -453,6 +535,11 @@ const server = http.createServer((req, res) => {
     if (rest === '/me/cross-project' && req.method === 'PATCH') return AUTH ? readBody(req, (body) => crossProjectPatch(res, body)) : json(res, 401, UNAUTH);
     if (rest === '/me/profile' && req.method === 'PATCH') return AUTH ? readBody(req, (body) => profilePatch(res, body)) : json(res, 401, UNAUTH);
     if (rest === '/me/handle' && req.method === 'PATCH') return AUTH ? readBody(req, (body) => handlePatch(res, body)) : json(res, 401, UNAUTH);
+    const guild = rest.match(/^\/guilds\/([^/]+)(\/members|\/membership|\/engagements)?$/);
+    if (guild && !guild[2] && req.method === 'GET') return guildRead(res, guild[1], 'public', origin);
+    if (guild && guild[2] === '/members' && req.method === 'GET') return AUTH ? guildRead(res, guild[1], 'members', origin) : json(res, 401, UNAUTH);
+    if (guild && guild[2] === '/membership' && req.method === 'PATCH') return AUTH ? readBody(req, (body) => guildMembershipPatch(res, guild[1], body)) : json(res, 401, UNAUTH);
+    if (guild && guild[2] === '/engagements' && req.method === 'POST') return AUTH ? readBody(req, (body) => guildEngagementPost(res, guild[1], body)) : json(res, 401, UNAUTH);
     if (rest === '/provisioning/instances' && req.method === 'GET') return AUTH ? instances(res, null, false) : json(res, 401, UNAUTH);
     // the planet-physics questions' pre-create check (task 1004418): nothing stops here —
     // the kit carries no screen. Of the soft-limit table it mirrors only the three hide
@@ -491,10 +578,13 @@ const server = http.createServer((req, res) => {
     // decline receipts a real render or probe of the my-projects block drives,
     // so those buttons are not stuck picturing only their failure branch.
     if (rest === '/my-projects/join' && req.method === 'POST') {
-      return AUTH ? readBody(req, (body) => json(res, 200, {
-        ok: true, status: 'requested', project: { name: body.origin || 'a project', origin: body.origin || null },
-        message: 'Requested access. The project’s owner admits new builders; once approved, sign in to enter.',
-      })) : json(res, 401, UNAUTH);
+      return AUTH ? readBody(req, (body) => {
+        if (body.guild !== undefined && !guildEngagementLive(body.guild, body.origin)) return refuse(res, 409, 'guild_engagement_gone', 'that guild engagement has ended');
+        return json(res, 200, {
+          ok: true, status: 'requested', project: { name: body.origin || 'a project', origin: body.origin || null },
+          message: 'Requested access. The project’s owner admits new builders; once approved, sign in to enter.',
+        });
+      }) : json(res, 401, UNAUTH);
     }
     if (/^\/my-projects\/[^/]+\/leave$/.test(rest) && req.method === 'POST') return AUTH ? json(res, 200, { ok: true, left: true }) : json(res, 401, UNAUTH);
     if (/^\/my-projects\/invites\/[^/]+\/decline$/.test(rest) && req.method === 'POST') return AUTH ? json(res, 200, { ok: true, accepted: false }) : json(res, 401, UNAUTH);
@@ -507,6 +597,7 @@ const server = http.createServer((req, res) => {
         invite_url: 'https://mercury.example.test/builders/watch?invite=' + encodeURIComponent(body.github_login || ''),
       })) : json(res, 401, UNAUTH);
     }
+    if (rest === '/projects/invite-guild' && req.method === 'POST') return AUTH ? readBody(req, (body) => guildInvitePost(res, body)) : json(res, 401, UNAUTH);
     // the manage flows (task 1003345): every door on a row and on the manage page only ASKS
     // (ADR 0111) — the stub answers each ask with the route's receipt so the probes can drive
     // attach / restart / teardown / revive / join end to end; nothing changes in the fixture
@@ -550,7 +641,10 @@ const server = http.createServer((req, res) => {
   // TASK_DETAIL_PAGE_RE / IDEA_DETAIL_PAGE_RE routes). Without this the states
   // for those pages could only be rendered at a URL production never serves, and
   // a page script that reads its id out of location.pathname would see none.
-  const name = under2 === '' ? 'index' : (fs.existsSync(path.join(DIR, under2 + '.html')) ? under2 : under2.replace(/\/[^/]+$/, ''));
+  // A namespace word may name its page differently: the hub serves /g/<slug> from
+  // guild.html (platform-server.js's /g/:slug route, task 1002301).
+  const base = under2 === '' ? 'index' : (fs.existsSync(path.join(DIR, under2 + '.html')) ? under2 : under2.replace(/\/[^/]+$/, ''));
+  const name = PAGE_ALIAS[base] && fs.existsSync(path.join(DIR, PAGE_ALIAS[base] + '.html')) ? PAGE_ALIAS[base] : base;
   if (!name.includes('/') && fs.existsSync(path.join(DIR, name + '.html'))) {
     try { res.writeHead(200, { 'content-type': MIME['.html'], 'cache-control': 'no-store' }); return res.end(page(name + '.html').html); }
     catch (e) { res.writeHead(500, { 'content-type': 'text/plain' }); return res.end('render failed: ' + e.stack); }

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.56",
+  "version": "1.21.58",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.56",
+      "version": "1.21.58",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.56",
+  "version": "1.21.58",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9108,5 +9108,17 @@
       "id": "1004581",
       "text": "The street no longer shows the small grey line of words above the buildings. The owner wants the city to read at a glance from its look alone, and the line was also wrong in light mode. It is gone in light and dark and on phon"
     }
+  ],
+  "1.21.57": [
+    {
+      "id": "1002301",
+      "text": "Guilds now have their own page on cloudbongos.com — who is in it and what it has shipped together — and members can choose whether they appear on it and count toward its totals."
+    }
+  ],
+  "1.21.58": [
+    {
+      "id": "1002303",
+      "text": "Guilds can now put themselves forward for a project, and a project can invite a whole guild — but every member still applies or accepts as themselves, so nobody joins a project without their own say."
+    }
   ]
 }

package/scripts/gds/run-unit-tests.js

@@ -183,6 +183,11 @@ const INTEGRATION = new Set([
   // proves the one-owner partial index, the expiry CTE drained before its insert,
   // the cascade on dissolve and the two-statement transfer.
   'guilds_db',
+  // task 1002303 (R27): guild engagements against real SQL — the FK that cascades
+  // a dissolved guild's engagements and the one that SETs NULL on the echo, the
+  // upsert restarting the 30-day window in place, and the joined_at rule. The
+  // DB-free sibling (guild_engagement) pins the routes and statement shapes.
+  'guild_engagement_db',
   // task 1002302 (R26): a guild's weekly rounded totals against real SQL. Who is
   // counted (three predicates and a FILTERed k count) and the upsert's week guard,
   // re-evaluated against a racing writer's committed row, are planner facts; the

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.56'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.58'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/src/platform-server.js

@@ -305,6 +305,19 @@ function buildPlatformApp() {
     if (!html) return next();
     res.type('html').send(html);
   });
+  // THE GUILD PAGE (task 1002301, R25; ADR 0336 D4/D6): /g/<slug>, the namespace
+  // D6 reserved. Hub-only for the /account reason — every read it makes is a
+  // platform-identity route. ONE shell for every slug: the page reads the public
+  // guild and, signed in, the members' own-scope read, so whether a guild exists
+  // (and whether an unlisted one is yours) is answered by those routes and never
+  // by this one. A segment that cannot be a slug falls through to the 404 tail.
+  app.get('/g/:slug', (req, res, next) => {
+    if (!isApexHost(req) || !isModuleEnabled('platform-identity')) return next();
+    if (!/^[A-Za-z0-9-]{2,39}$/.test(req.params.slug)) return next();
+    const html = landingPage('guild.html');
+    if (!html) return next();
+    res.type('html').send(html);
+  });
   // Assets fall through to the 404 tail when no module claims the apex root — the
   // handler is not mounted at all rather than pointed at a missing directory.
   const landingAssets = landingDir() && express.static(landingDir(), { index: false, fallthrough: true });

package/tests/applicant_profile_boundary.mjs

@@ -248,9 +248,18 @@ function activityScope(sql, params) {
 const CLIENT = { client_id: 'client-alpha', secret_hash: null, name: 'Alpha', redirect_uris: [], origin: 'https://alpha.example', owner_github_id: '1', status: 'active' };
 const OTHER_CLIENT = { client_id: 'client-beta', secret_hash: null, name: 'Beta', redirect_uris: [], origin: 'https://beta.example', owner_github_id: '2', status: 'active' };
 // (github_id, client_id) pairs the HUB witnessed, and whether they are inside
-// the read-time window. Only PUB and PRIVOUT applied to alpha.
+// the read-time window. Only PUB and PRIVOUT applied to alpha. An echo may carry
+// the guild the application was made with (task 1002303, ADR 0365 D5).
 let ECHOES = [];
 
+// The guilds an echo can name, and who is (still) in them.
+const GUILDS = [
+  { id: '81', slug: 'open-guild', name: 'Open Guild', visibility: 'public' },
+  { id: '82', slug: 'quiet-guild', name: 'Quiet Guild', visibility: 'unlisted' },
+];
+let GUILD_MEMBERS = [];
+let labelFails = false;
+
 let calls = [];
 const pool = {
   query: async (text, params = []) => {
@@ -262,6 +271,28 @@ const pool = {
       return { rows: hit ? [{ ...hit }] : [], rowCount: hit ? 1 : 0 };
     }
 
+    // THE GUILD LABEL (guild-engagements.js echoGuildLabel). Its membership
+    // requirement is a JOIN, so the join is read rather than assumed: drop it
+    // and an applicant who LEFT the guild genuinely keeps the label here.
+    if (/^SELECT g\.slug, g\.name, g\.visibility FROM platform_identity_application_echoes ae /.test(sql)) {
+      if (labelFails) throw new Error('the guild tables are on fire');
+      const m = /^SELECT g\.slug, g\.name, g\.visibility FROM platform_identity_application_echoes ae (.+?) WHERE (.+?) LIMIT 1$/.exec(sql);
+      if (!m) throw new Error(`fake pool: the label read moved — ${sql}`);
+      if (!/^JOIN platform_identity_guilds g ON g\.id = ae\.guild_id\b/.test(m[1])) throw new Error(`fake pool: the label join moved — ${m[1]}`);
+      const rest = m[1].replace(/^JOIN platform_identity_guilds g ON g\.id = ae\.guild_id/, '').trim();
+      const mustBeMember = rest === 'JOIN platform_identity_guild_members m ON m.guild_id = ae.guild_id AND m.github_id = ae.github_id';
+      if (rest && !mustBeMember) throw new Error(`fake pool: unmodelled label join — ${rest}`);
+      assert.equal(m[2], 'ae.github_id = $1::bigint AND ae.client_id = $2 AND ae.applied_at > now() - make_interval(days => $3::int)',
+        'the label reads ONE echo — this account, this client, inside the 30-day window');
+      assert.equal(params[2], 30);
+      const rows = ECHOES
+        .filter((e) => String(e.github_id) === String(params[0]) && e.client_id === params[1] && e.in_window && e.guild_id)
+        .filter((e) => !mustBeMember || GUILD_MEMBERS.some((gm) => gm.guild_id === e.guild_id && gm.github_id === String(e.github_id)))
+        .map((e) => GUILDS.find((g) => g.id === e.guild_id))
+        .map((g) => ({ slug: g.slug, name: g.name, visibility: g.visibility, id: g.id }));
+      return { rows: rows.slice(0, 1), rowCount: Math.min(rows.length, 1) };
+    }
+
     // The GATE's own read. The window term is modelled explicitly rather than
     // waved through: an echo outside it must stop working, and a fake that
     // ignored `applied_at` would make that untestable.
@@ -584,6 +615,78 @@ test('a real applicant resolves, uncacheable, through the gate', async () => {
     'a cached applicant view is a snapshot, which is the one thing "live at review time" forbids');
 });
 
+// ---------------------------------------------------------------------------
+// The guild label (task 1002303, ADR 0365 D5): { profile, guild }
+// ---------------------------------------------------------------------------
+
+const labelReads = () => calls.filter((c) => /FROM platform_identity_application_echoes ae /.test(c.sql));
+
+test('the guild label: { slug, name } beside the profile while the applicant is still in the guild', async () => {
+  ECHOES = [{ github_id: PUB, client_id: CLIENT.client_id, in_window: true, guild_id: '81' }];
+  GUILD_MEMBERS = [{ guild_id: '81', github_id: PUB }];
+  labelFails = false;
+  const r = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PUB });
+  assert.equal(r.status, 200);
+  assert.deepEqual(Object.keys(r.json).sort(), ['guild', 'profile'], 'the label sits BESIDE the profile, never inside it');
+  assert.equal(r.json.profile.view, VIEW_PUBLIC);
+  assert.deepEqual(r.json.guild, { slug: 'open-guild', name: 'Open Guild' }, 'a slug and a name — no guild id, no visibility');
+  assert.equal(labelReads()[0].params[1], CLIENT.client_id, 'asked about the AUTHENTICATED client');
+});
+
+test('the guild label: an UNLISTED guild is named with slug null — it has no public page to open', async () => {
+  ECHOES = [{ github_id: PRIVOUT, client_id: CLIENT.client_id, in_window: true, guild_id: '82' }];
+  GUILD_MEMBERS = [{ guild_id: '82', github_id: PRIVOUT }];
+  labelFails = false;
+  const r = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PRIVOUT });
+  assert.equal(r.json.profile.view, VIEW_SLIVER);
+  assert.deepEqual(r.json.guild, { slug: null, name: 'Quiet Guild' });
+});
+
+test('the guild label: null once the applicant LEFT the guild, and null for a solo application', async () => {
+  ECHOES = [{ github_id: PUB, client_id: CLIENT.client_id, in_window: true, guild_id: '81' }];
+  GUILD_MEMBERS = [];
+  labelFails = false;
+  const left = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PUB });
+  assert.equal(left.json.profile.view, VIEW_PUBLIC);
+  assert.equal(left.json.guild, null, 'a guild they are no longer in does not vouch for them');
+
+  ECHOES = [{ github_id: PUB, client_id: CLIENT.client_id, in_window: true, guild_id: null }];
+  GUILD_MEMBERS = [{ guild_id: '81', github_id: PUB }];
+  const solo = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PUB });
+  assert.equal(solo.json.guild, null);
+});
+
+test('the guild label: null whenever the profile is null — and then not even read', async () => {
+  ECHOES = [{ github_id: PROV, client_id: CLIENT.client_id, in_window: true, guild_id: '81' }];
+  GUILD_MEMBERS = [{ guild_id: '81', github_id: PROV }];
+  labelFails = false;
+  const r = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PROV });
+  assert.equal(r.status, 200);
+  assert.equal(r.json.profile, null);
+  assert.equal(r.json.guild, null, 'an applicant who discloses nothing discloses no guild either');
+  assert.deepEqual(labelReads(), [], 'the label is read only beside a profile');
+});
+
+test('the guild label is BEST-EFFORT: a failed read answers guild null and never costs the profile', async () => {
+  ECHOES = [{ github_id: PUB, client_id: CLIENT.client_id, in_window: true, guild_id: '81' }];
+  GUILD_MEMBERS = [{ guild_id: '81', github_id: PUB }];
+  labelFails = true;
+  try {
+    const r = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PUB });
+    assert.equal(r.status, 200);
+    assert.equal(r.json.profile.view, VIEW_PUBLIC);
+    assert.equal(r.json.guild, null);
+  } finally { labelFails = false; }
+});
+
+test('the guild label waits behind the echo gate: no application, no label read', async () => {
+  ECHOES = [{ github_id: PUB, client_id: OTHER_CLIENT.client_id, in_window: true, guild_id: '81' }];
+  GUILD_MEMBERS = [{ guild_id: '81', github_id: PUB }];
+  const r = await post('/api/bongos/sso/applicant-profile', { ...creds, github_id: PUB });
+  assert.equal(r.status, 404);
+  assert.deepEqual(labelReads(), []);
+});
+
 test('bad credentials are refused before anything is read', async () => {
   ECHOES = [{ github_id: PUB, client_id: CLIENT.client_id, in_window: true }];
   const r = await post('/api/bongos/sso/applicant-profile', { client_id: CLIENT.client_id, client_secret: 'wrong', github_id: PUB });

package/tests/application_echo.mjs

@@ -75,7 +75,17 @@ test('the write is an upsert on the pair, refreshing the date (D1.4)', async ()
   const [{ sql, params }] = pool.calls;
   assert.match(sql, /ON CONFLICT \(github_id, client_id\) DO UPDATE SET applied_at = now\(\)/,
     're-applying is a success, so a second ask refreshes rather than erroring or piling up a row');
-  assert.deepEqual(params, [String(ME), 'proj-a']);
+  assert.deepEqual(params, [String(ME), 'proj-a', null], 'a solo application binds NO guild');
+});
+
+test('the write carries the guild the application was made with, and every upsert rewrites it (task 1002303, ADR 0365 D1)', async () => {
+  const pool = recorder();
+  await recordApplication({ githubId: ME, clientId: 'proj-a', guildId: 71 }, { pool });
+  const [{ sql, params }] = pool.calls;
+  assert.match(sql, /INSERT INTO platform_identity_application_echoes \(github_id, client_id, applied_at, guild_id\) VALUES \(\$1::bigint, \$2, now\(\), \$3::bigint\)/);
+  assert.match(sql, /DO UPDATE SET applied_at = now\(\), guild_id = EXCLUDED\.guild_id$/,
+    'the most recent application decides the label: a later solo one writes NULL over it');
+  assert.deepEqual(params, [String(ME), 'proj-a', '71']);
 });
 
 test('neither function carries a status, because the table holds none', async () => {
@@ -106,6 +116,10 @@ let echoFails = false;
 let statements = [];
 let account = null;
 let accountFails = false;
+// (session, guild slug, client) triples that resolve to an engagement for the
+// join's `guild` field (task 1002303).
+const ENGAGED = [{ github_id: ME, slug: 'guild-a', client_id: 'proj-open', guild_id: '71' }];
+let engagementFails = false;
 
 function seed() {
   const now = Date.now();
@@ -128,6 +142,7 @@ function seed() {
     { client_id: 'proj-invited', membership_kind: 'pending', joined_at: now - DAY, last_active: null, project_name: 'Invited', project_origin: 'https://invited.example', owner_github_id: null },
   ];
   echoFails = false;
+  engagementFails = false;
   statements = [];
   // An account that has cleared the consent floor: active, and the platform
   // terms accepted (account-visibility.js isAccountActive).
@@ -238,13 +253,28 @@ const pool = {
 
     if (/^INSERT INTO platform_identity_application_echoes/.test(sql)) {
       if (echoFails) throw new Error('echo table is on fire');
-      const [githubId, clientId] = params;
+      const [githubId, clientId, guildId = null] = params;
+      // The conflict branch is READ from the statement, so dropping the guild_id
+      // rewrite from it genuinely leaves a stale label behind (task 1002303).
+      const rewritesGuild = /DO UPDATE SET .*\bguild_id = EXCLUDED\.guild_id\b/.test(sql);
       const existing = echoes.find((e) => String(e.github_id) === String(githubId) && e.client_id === clientId);
-      if (existing) existing.applied_at = Date.now();
-      else echoes.push({ github_id: Number(githubId), client_id: clientId, applied_at: Date.now() });
+      if (existing) {
+        existing.applied_at = Date.now();
+        if (rewritesGuild) existing.guild_id = guildId;
+      } else echoes.push({ github_id: Number(githubId), client_id: clientId, applied_at: Date.now(), guild_id: guildId });
       return { rows: [] };
     }
 
+    // The join's guild check (guild-engagements.js engagementFor) — the rule
+    // itself is interpreted in tests/guild_engagement.mjs; here only WHICH guild
+    // resolves for whom matters, keyed on the bound session, slug and client.
+    if (/^SELECT g\.id, g\.slug, g\.name FROM platform_identity_guild_members m /.test(sql)) {
+      if (engagementFails) throw new Error('engagement table is on fire');
+      assert.match(sql, /lower\(g\.slug\) = \$2 AND e\.client_id = \$3 LIMIT 1$/);
+      const hit = ENGAGED.find((x) => String(params[0]) === String(x.github_id) && params[1] === x.slug && params[2] === x.client_id);
+      return { rows: hit ? [{ id: hit.guild_id, slug: hit.slug, name: hit.slug }] : [] };
+    }
+
     if (/FROM platform_identity_application_echoes e/.test(sql)) {
       if (echoFails) throw new Error('echo table is on fire');
       m = /WHERE (.+?) ORDER BY/.exec(sql);
@@ -342,7 +372,7 @@ function call(method, pathname, body) {
     req.end(payload);
   });
 }
-const join = (note) => call('POST', '/api/bongos/my-projects/join', { origin: 'https://target.example', note });
+const join = (note, guild) => call('POST', '/api/bongos/my-projects/join', { origin: 'https://target.example', note, ...(guild === undefined ? {} : { guild }) });
 
 test('the interpreter refuses a predicate it cannot read — parameterised or not', () => {
   assert.throws(() => predicateFor('github_id = $1::bigint AND something = $2', [1, 2]), /unread predicate on \$2/);
@@ -414,6 +444,62 @@ test('a failed echo write never turns a filed application into a reported failur
   assert.equal(r.json.status, 'requested');
 });
 
+// ── applying WITH a guild (task 1002303, ADR 0365 D2) ─────────────────────────
+// The guild is resolved for the SESSION before anything is relayed; one that
+// no longer resolves relays nothing and echoes nothing, and one that does is the
+// label the echo carries until the next application rewrites it.
+
+test('a `guild` that no longer resolves is a 409 guild_engagement_gone, with nothing relayed and no echo', async () => {
+  for (const guild of ['other-guild', 'Not A Slug!', '']) {
+    seed();
+    echoes = echoes.filter((e) => e.client_id !== 'proj-open');
+    relay = { status: 201, body: { ok: true } };
+    const r = await join('please', guild);
+    assert.equal(r.status, 409, `guild ${JSON.stringify(guild)}`);
+    assert.equal(r.json.error.code, 'guild_engagement_gone');
+    assert.equal(relayed, null, 'the project never heard of it — the applicant chose to apply WITH the guild');
+    assert.equal(echo('proj-open'), undefined);
+  }
+});
+
+test('a guild that resolves is checked for the SESSION, relayed as an ordinary application, and lands on the echo', async () => {
+  seed();
+  echoes = echoes.filter((e) => e.client_id !== 'proj-open');
+  relay = { status: 201, body: { ok: true } };
+  const r = await join('please', 'Guild-A');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.status, 'requested');
+  assert.ok(relayed, 'relayed');
+  assert.deepEqual(Object.keys(JSON.parse(relayed.init.body)).sort(), ['display_name', 'github_login', 'note'],
+    'no new field reaches the project: the label travels on the applicant-profile read (ADR 0365 D5)');
+  const check = statements.find((x) => /^SELECT g\.id, g\.slug, g\.name FROM platform_identity_guild_members/.test(x.sql));
+  assert.deepEqual(check.params.slice(0, 3), [String(ME), 'guild-a', 'proj-open'], 'the session, the canonical slug, the resolved client');
+  assert.equal(echo('proj-open').guild_id, '71');
+});
+
+test('a later solo application clears the guild label — the most recent application decides', async () => {
+  seed();
+  relay = { status: 201, body: { ok: true } };
+  await join('with them', 'guild-a');
+  assert.equal(echo('proj-open').guild_id, '71');
+  await join('on my own');
+  assert.equal(echo('proj-open').guild_id, null);
+});
+
+test('a refused application leaves no echo even with a guild, and a broken guild check relays nothing', async () => {
+  seed();
+  echoes = echoes.filter((e) => e.client_id !== 'proj-open');
+  relay = { status: 403, body: { error: { code: 'invite_only' } } };
+  assert.equal((await join(undefined, 'guild-a')).json.status, 'invite_only');
+  assert.equal(echo('proj-open'), undefined);
+
+  seed();
+  engagementFails = true;
+  const r = await join(undefined, 'guild-a');
+  assert.equal(r.status, 500, 'a label the hub cannot verify is never attached by guesswork');
+  assert.equal(relayed, null);
+});
+
 // ── the vouch the relay carries (R09, task 1002285; ADR 0201 D2) ─────────────
 // The ECHO above is what authorizes the project's later profile read
 // (applicationBacksProfileRead); the VOUCH is what tells the project whose