@bongos/core 1.21.56 → 1.21.58

package/modules/platform-identity/application-echo.js

@@ -47,19 +47,25 @@ const APPLICATION_ECHO_WINDOW_DAYS = 30;
 // is measured from the most recent ask — otherwise an applicant who re-asks
 // watches their own card go quiet while their request is still open.
 //
+// `guildId` is the guild this application was made with (task 1002303, ADR 0365
+// D1) — resolved by the relay through guild-engagements.js engagementFor, never
+// taken from the request — or null for a solo application. It is written on
+// EVERY upsert, null included, so the most recent application decides the label
+// the reviewer sees: applying again on your own clears it.
+//
 // BEST-EFFORT BY CONTRACT: returns false instead of throwing when the account is
 // a non-numeric principal (ADR 0171 D2). The caller must also swallow a DB error
 // — the echo is a convenience on the applicant's own view, and losing it must
 // never turn a filed application into a reported failure.
-async function recordApplication({ githubId, clientId }, { pool = defaultPool } = {}) {
+async function recordApplication({ githubId, clientId, guildId = null }, { pool = defaultPool } = {}) {
   if (!isNumericGithubId(githubId)) return false;
   const client = String(clientId || '');
   if (!client) return false;
   await pool.query(
-    `INSERT INTO platform_identity_application_echoes (github_id, client_id, applied_at)
-     VALUES ($1::bigint, $2, now())
-     ON CONFLICT (github_id, client_id) DO UPDATE SET applied_at = now()`,
-    [String(githubId), client],
+    `INSERT INTO platform_identity_application_echoes (github_id, client_id, applied_at, guild_id)
+     VALUES ($1::bigint, $2, now(), $3::bigint)
+     ON CONFLICT (github_id, client_id) DO UPDATE SET applied_at = now(), guild_id = EXCLUDED.guild_id`,
+    [String(githubId), client, guildId == null ? null : String(guildId)],
   );
   return true;
 }

package/modules/platform-identity/guild-engagements.js

@@ -0,0 +1,255 @@
+// modules/platform-identity/guild-engagements.js — a guild engaging a project:
+// "G is applying to P" and "P invited G", plus the guild label an application
+// carries to the project's reviewer (task 1002303, R27; ADR 0336 D7, amended by
+// ADR 0365).
+//
+// WHAT LIVES HERE, next to the data so no route can forget a rule:
+//
+//   * A PROJECT STILL ADMITS PEOPLE, ONE AT A TIME (D7). An engagement admits
+//     nobody. A member who acts on one applies AS THEMSELVES through the
+//     existing relay (routes/my-projects.js), vouched and echoed; the echo then
+//     carries the guild as a label. Filing does not apply on the owner's behalf.
+//   * A PROJECT INVITING A GUILD WRITES NO INVITES (ADR 0365 D3, after ADR
+//     0353). It records the `invited` engagement and hands back one hall link
+//     per member on the guild's PUBLIC roster at that moment — the people the
+//     inviter could see — so each invite is the project's own row, sent from
+//     its own hall. An unlisted guild cannot be invited: it answers like an
+//     unknown one.
+//   * THE NAMING RULE (ADR 0365 D4): a project is named only when it is on the
+//     map AND Public (namedProjectSql — the getRollupForBuilder rule, composed
+//     from the feed's own onMapSql). It gates both kinds, at filing AND at
+//     read. A private or stealth project's engagement is not shown at all,
+//     never shown anonymised.
+//   * ONE FRAGMENT DECIDES WHICH ENGAGEMENTS A MEMBER MAY SEE
+//     (memberEngagementsSql): their own guild's, inside the window, naming a
+//     project by the rule above, and an `invited` row only if they were already
+//     a member when it was filed. The inbox AND the join's guild check both use
+//     it, so the join can never accept a guild the inbox would not have shown —
+//     that difference would let a member probe whether a private project had
+//     invited their guild.
+//   * STATELESS AND STATUSLESS (ADR 0201 D1.3). No status, no filer, no
+//     withdraw: a row ages out read-time at ENGAGEMENT_WINDOW_DAYS, and
+//     re-filing restarts it.
+//
+// NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). Every read that touches
+// platform_identity_accounts joins account-visibility.js
+// (tests/effective_visibility_predicate.mjs). client_id never leaves this file.
+//
+// Its own file because platform-identity.js is at the size ratchet. Reaches
+// core only through the doorway (ADR 0083).
+'use strict';
+
+const api = require('../../src/module-api');
+const { accountVisibleSql } = require('./account-visibility');
+const { onMapSql } = require('./projects-feed');
+const { isNumericGithubId } = require('./platform-identity');
+const { APPLICATION_ECHO_WINDOW_DAYS } = require('./application-echo');
+const { hallInviteUrl } = require('./invite-notices');
+const { ownerExistsSql, LIST_MAX } = require('./guilds');
+
+const { pool: defaultPool } = api;
+
+// How long an engagement stays visible. READ-TIME, like the application echo's
+// window and for the same reason: no sweep to fall behind, no status to expire
+// into. Exported so the routes, the tests and the docs quote one number.
+const ENGAGEMENT_WINDOW_DAYS = 30;
+
+// A project may be NAMED to a guild's members only when it is on the map and
+// Public (ADR 0365 D4, the ADR 0171 D2 amendment). onMapSql validates the alias.
+function namedProjectSql(alias) {
+  return `(${onMapSql(alias)} AND ${alias}.visibility = 'public')`;
+}
+
+// The FROM + WHERE every member-facing read shares (see the header). `member`
+// and `windowDays` are placeholders, e.g. '$1' and '$2'. The client must still
+// be an active registration: a dead client is not a project anyone can apply to.
+function memberEngagementsSql(member, windowDays) {
+  return `
+       FROM platform_identity_guild_members m
+       JOIN platform_identity_guilds g ON g.id = m.guild_id
+       JOIN platform_identity_guild_engagements e ON e.guild_id = m.guild_id
+       JOIN platform_identity_sso_clients c ON c.client_id = e.client_id
+       JOIN platform_identity_projects p ON p.origin = c.origin
+      WHERE m.github_id = ${member}::bigint
+        AND e.created_at > now() - make_interval(days => ${windowDays}::int)
+        AND c.status = 'active' AND ${namedProjectSql('p')}
+        AND (e.kind = 'apply' OR m.joined_at <= e.created_at)`;
+}
+
+// The wire shape of one engagement. A literal whitelist: client_id, the guild's
+// row id and the guild's visibility never cross.
+function engagementView(r) {
+  return {
+    guild: { slug: r.slug, name: r.guild_name },
+    kind: r.kind,
+    project: { name: r.project_name, origin: r.project_origin },
+    created_at: r.created_at,
+  };
+}
+
+// fileEngagement — the guild's OWNER files "this guild is applying to P"
+// (kind 'apply'). ONE statement: P is resolved from the origin the way the join
+// relay resolves it (the oldest active registration at that exact origin), must
+// pass the naming rule, and the owner test is re-asserted inside the INSERT, so
+// the route's pre-check is a clearer error and never the only gate. Re-filing
+// restarts the window. Returns the engagement view, or null when P is unknown,
+// inactive or not named — one null, so the route's 404 cannot be an oracle.
+async function fileEngagement({ guildId, githubId, origin }, { pool = defaultPool } = {}) {
+  const norm = String(origin || '').replace(/\/+$/, '');
+  if (!norm || !isNumericGithubId(githubId)) return null;
+  const { rows } = await pool.query(
+    `WITH target AS (
+       SELECT c.client_id, p.name, p.origin
+         FROM platform_identity_sso_clients c
+         JOIN platform_identity_projects p ON p.origin = c.origin
+        WHERE c.client_id = (SELECT c1.client_id FROM platform_identity_sso_clients c1
+                              WHERE c1.origin = $3 AND c1.status = 'active'
+                              ORDER BY c1.id ASC LIMIT 1)
+          AND ${namedProjectSql('p')}
+     ),
+     filed AS (
+       INSERT INTO platform_identity_guild_engagements AS e (guild_id, client_id, kind)
+       SELECT g.id, target.client_id, 'apply'
+         FROM platform_identity_guilds g CROSS JOIN target
+        WHERE g.id = $1 AND ${ownerExistsSql('g.id', '$2')}
+       ON CONFLICT (guild_id, client_id, kind) DO UPDATE SET created_at = now()
+       RETURNING e.guild_id, e.kind, e.created_at
+     )
+     SELECT g.slug, g.name AS guild_name, filed.kind, filed.created_at,
+            target.name AS project_name, target.origin AS project_origin
+       FROM filed
+       JOIN platform_identity_guilds g ON g.id = filed.guild_id
+       CROSS JOIN target`,
+    [guildId, String(githubId), norm],
+  );
+  return rows[0] ? engagementView(rows[0]) : null;
+}
+
+// inviteGuild — a project invites a PUBLIC guild (ADR 0365 D3). The caller has
+// already passed the project's inviter gate and holds the active client row.
+// Returns { guild, invites } — one hall hand-off link per member on the guild's
+// public roster at this moment — or null when the slug is unknown OR unlisted
+// (one answer: an unlisted guild cannot be addressed).
+//
+// The `invited` row is written only while P passes the naming rule, re-checked
+// in the INSERT: a private or stealth project's invite reaches the people it
+// chose and nobody else, so it leaves no notice for the members it could not
+// see — not even one that would surface if P went public later.
+async function inviteGuild({ clientId, origin, slug }, { pool = defaultPool } = {}) {
+  const g = await pool.query(
+    `SELECT id, slug, name FROM platform_identity_guilds
+      WHERE lower(slug) = $1 AND visibility = 'public'`,
+    [slug],
+  );
+  const guild = g.rows[0];
+  if (!guild) return null;
+  await pool.query(
+    `INSERT INTO platform_identity_guild_engagements AS e (guild_id, client_id, kind)
+     SELECT $1::bigint, c.client_id, 'invited'
+       FROM platform_identity_sso_clients c
+       JOIN platform_identity_projects p ON p.origin = c.origin
+      WHERE c.client_id = $2 AND c.status = 'active' AND ${namedProjectSql('p')}
+        AND EXISTS (SELECT 1 FROM platform_identity_guilds pg
+                     WHERE pg.id = $1 AND pg.visibility = 'public')
+     ON CONFLICT (guild_id, client_id, kind) DO UPDATE SET created_at = now()`,
+    [guild.id, clientId],
+  );
+  const roster = await publicRosterForInvite(guild.id, { pool });
+  const invites = roster
+    .map((m) => ({ handle: m.handle, display_name: m.display_name, invite_url: hallInviteUrl(origin, m.github_login) }))
+    .filter((m) => m.invite_url);
+  return { guild: { slug: guild.slug, name: guild.name }, invites };
+}
+
+// The guild's PUBLIC roster, exactly as getPublicGuild reads it (shown_publicly
+// AND accountVisibleSql, owner first, then by handle, capped at LIST_MAX) — the
+// people an inviter can already see on the guild's page. github_login is read
+// only to build each hall link (the hall's ?invite= prefill takes a login, which
+// a public profile already shows); it is never returned on its own.
+async function publicRosterForInvite(guildId, { pool }) {
+  const { rows } = await pool.query(
+    `SELECT pa.handle, pa.display_name, pa.github_login
+       FROM platform_identity_guild_members m
+       JOIN platform_identity_accounts pa ON pa.github_id = m.github_id
+      WHERE m.guild_id = $1 AND m.shown_publicly AND ${accountVisibleSql('pa')}
+      ORDER BY (m.membership_kind = 'owner') DESC, lower(pa.handle)
+      LIMIT $2`,
+    [guildId, LIST_MAX],
+  );
+  return rows;
+}
+
+// listMyEngagements — the caller's OWN inbox: engagements of guilds they belong
+// to that they may act on, newest first, capped at LIST_MAX. On top of the shared
+// rule (memberEngagementsSql) it drops any project the caller already builds on,
+// already holds a live invite notice for (the inviteExpiry window), or already
+// has a live application echo for — the card would ask them to do what they
+// have done. Own-scope only: the github_id is always the session's.
+async function listMyEngagements({ githubId }, { pool = defaultPool } = {}) {
+  if (!isNumericGithubId(githubId)) return [];
+  const { rows } = await pool.query(
+    `SELECT g.slug, g.name AS guild_name, e.kind, e.created_at,
+            p.name AS project_name, p.origin AS project_origin
+     ${memberEngagementsSql('$1', '$2')}
+        AND NOT EXISTS (SELECT 1 FROM platform_identity_project_memberships pm
+                         WHERE pm.client_id = e.client_id AND pm.github_id = $1::bigint
+                           AND (pm.membership_kind <> 'pending'
+                                OR pm.joined_at > now() - make_interval(days => $3::int)))
+        AND NOT EXISTS (SELECT 1 FROM platform_identity_application_echoes ae
+                         WHERE ae.github_id = $1::bigint AND ae.client_id = e.client_id
+                           AND ae.applied_at > now() - make_interval(days => $4::int))
+      ORDER BY e.created_at DESC, g.slug, e.kind
+      LIMIT $5`,
+    [String(githubId), ENGAGEMENT_WINDOW_DAYS, api.inviteExpiry.INVITE_EXPIRY_DAYS,
+      APPLICATION_ECHO_WINDOW_DAYS, LIST_MAX],
+  );
+  return rows.map(engagementView);
+}
+
+// engagementFor — "may THIS member apply to THIS project WITH this guild?" The
+// join relay's check before it relays anything (ADR 0365 D2): the guild must be
+// one the caller belongs to, with an engagement of either kind for the project
+// that the shared rule lets them see. Returns { id, slug, name } (the id is for
+// the echo, never the wire) or null — left the guild, aged out, or never visible.
+async function engagementFor({ githubId, slug, clientId }, { pool = defaultPool } = {}) {
+  if (!isNumericGithubId(githubId) || !slug || !clientId) return null;
+  const { rows } = await pool.query(
+    `SELECT g.id, g.slug, g.name
+     ${memberEngagementsSql('$1', '$4')}
+        AND lower(g.slug) = $2 AND e.client_id = $3
+      LIMIT 1`,
+    [String(githubId), slug, String(clientId), ENGAGEMENT_WINDOW_DAYS],
+  );
+  return rows[0] || null;
+}
+
+// echoGuildLabel — the guild an applicant's LIVE echo for this project carries,
+// as the reviewer may see it: { slug, name } while the applicant is still a
+// member (slug null for an unlisted guild, which has no public page to open),
+// else null. Read by POST /sso/applicant-profile only AFTER its echo gate, so
+// it says nothing about anyone who did not apply to the calling project. The
+// most recent application decides: a later solo one wrote guild_id NULL.
+async function echoGuildLabel({ githubId, clientId }, { pool = defaultPool } = {}) {
+  if (!isNumericGithubId(githubId) || !clientId) return null;
+  const { rows } = await pool.query(
+    `SELECT g.slug, g.name, g.visibility
+       FROM platform_identity_application_echoes ae
+       JOIN platform_identity_guilds g ON g.id = ae.guild_id
+       JOIN platform_identity_guild_members m ON m.guild_id = ae.guild_id AND m.github_id = ae.github_id
+      WHERE ae.github_id = $1::bigint AND ae.client_id = $2
+        AND ae.applied_at > now() - make_interval(days => $3::int)
+      LIMIT 1`,
+    [String(githubId), String(clientId), APPLICATION_ECHO_WINDOW_DAYS],
+  );
+  const r = rows[0];
+  return r ? { slug: r.visibility === 'public' ? r.slug : null, name: r.name } : null;
+}
+
+module.exports = {
+  ENGAGEMENT_WINDOW_DAYS,
+  fileEngagement,
+  inviteGuild,
+  listMyEngagements,
+  engagementFor,
+  echoGuildLabel,
+};

package/modules/platform-identity/guilds.js

@@ -80,7 +80,8 @@ const PERSON_COLUMNS = 'pa.handle, pa.display_name, pa.avatar_url';
 
 // The owner test every owner-only statement re-asserts in its own WHERE, so a
 // route's pre-check is a nicer error and never the only gate. $g/$a are the
-// placeholders holding the guild id and the acting github_id.
+// placeholders holding the guild id and the acting github_id. Exported for
+// guild-engagements.js, whose owner-filed engagement asserts the same test.
 function ownerExistsSql(g, a) {
   return `EXISTS (SELECT 1 FROM platform_identity_guild_members o
                    WHERE o.guild_id = ${g} AND o.github_id = ${a}::bigint
@@ -686,6 +687,7 @@ module.exports = {
   DESCRIPTION_MAX_CHARS,
   INVITE_BATCH_MAX,
   LIST_MAX,
+  ownerExistsSql,
   normalizeGuildSlug,
   lookupSlug,
   createGuild,

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

@@ -0,0 +1,64 @@
+-- platform_identity_030_guild_engagements.sql — a guild's engagement with a
+-- project, and the guild an application was made with (task 1002303, R27;
+-- ADR 0336 D7, amended by ADR 0365).
+--
+-- WHAT THIS IS. One row says "this guild is applying to this project" (kind
+-- 'apply', filed by the guild's owner) or "this project invited this guild"
+-- (kind 'invited', written when a project's inviter names a public guild).
+-- Members read it in their own inbox and may apply AS THEMSELVES through the
+-- existing relay; nobody reaches a project without their own act. And the
+-- application echo gains the guild the member applied with, so the project's
+-- reviewer can see the label on the live applicant-profile read.
+--
+-- THE SHAPE CARRIES THE RULES, so no route has to remember them:
+--   * NO FILER COLUMN — for the reason the guild row keeps no creator: the
+--     owner row is the authority, and a permanent "filed by" would tie a person
+--     to an act after they have left the guild.
+--   * NO STATUS COLUMN, AND ADDING ONE WOULD BE THE BUG (ADR 0201 D1.3). The
+--     hub may not hold an admission fact about someone else's project; whether
+--     anyone got in is the project's own access_requests row, and it becomes
+--     visible here only as membership does.
+--   * THE KEY IS (guild, project, kind), so re-filing cannot pile up rows: the
+--     writer's upsert restarts created_at in place.
+--   * THE 30-DAY WINDOW IS READ-TIME, not a column and not a sweep
+--     (ENGAGEMENT_WINDOW_DAYS in ../guild-engagements.js). A stale row is
+--     invisible rather than wrong.
+--   * THE GUILD FK CASCADES, so a dissolved guild takes its engagements with
+--     it (the ADR 0336 D2 no-tombstone reason). The echo's guild_id is SET NULL
+--     instead: the application stands without its label.
+--   * client_id is the registered sso_client, never a caller-supplied origin —
+--     the writer resolves the origin against the registry, as the join relay does.
+--
+-- NOTHING HERE IS AUTHORITY (ADR 0016 / ADR 0141). No rank, credit or admission
+-- path reads these rows; an engagement admits nobody anywhere.
+--
+-- Additive + platform_identity_-namespaced (ADR 0083 §5). CREATE and ADD COLUMN
+-- only, so the previous release still runs against this schema. Idempotent.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS platform_identity_guild_engagements (
+  guild_id   bigint NOT NULL REFERENCES platform_identity_guilds(id) ON DELETE CASCADE,
+  client_id  text NOT NULL,
+  kind       text NOT NULL CHECK (kind IN ('apply', 'invited')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (guild_id, client_id, kind)
+);
+
+-- The project side: the member's join check and the per-project reads.
+CREATE INDEX IF NOT EXISTS platform_identity_guild_engagements_client
+  ON platform_identity_guild_engagements (client_id);
+
+COMMENT ON TABLE platform_identity_guild_engagements IS
+  'A guild''s engagement with a project (ADR 0336 D7, ADR 0365): apply (the guild owner filed "we are applying") or invited (a project''s inviter named this public guild). No filer column, as the guild row keeps no creator. No status column: the hub holds no admission fact about someone else''s project (ADR 0201 D1.3). The 30-day window is applied when read (ENGAGEMENT_WINDOW_DAYS); nothing expires the rows. Descriptive only, never authority (ADR 0016).';
+
+COMMENT ON COLUMN platform_identity_guild_engagements.created_at IS
+  'When this engagement was most recently filed. Re-filing restarts it in place, so the 30-day read window is measured from the latest act.';
+
+ALTER TABLE platform_identity_application_echoes
+  ADD COLUMN IF NOT EXISTS guild_id bigint REFERENCES platform_identity_guilds(id) ON DELETE SET NULL;
+
+COMMENT ON COLUMN platform_identity_application_echoes.guild_id IS
+  'The guild this application was made with (ADR 0365 D1), or NULL for a solo application. Written by the join relay on every application, so the most recent one decides the label: applying again on your own clears it. SET NULL when the guild is dissolved. A label only, never a status.';
+
+COMMIT;

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

@@ -25,6 +25,8 @@
 //   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
+//   POST   /guilds/:slug/engagements       owner: "this guild is applying to P" {origin} (R27)
+//   GET    /me/guild-engagements           my inbox: engagements I may act on (R27)
 //
 // A GUILD IS NEVER AUTHORITY (ADR 0016 / ADR 0141). no-store everywhere: these
 // payloads are privacy-filtered per viewer (ADR 0171 D5).
@@ -36,6 +38,7 @@ const express = require('express');
 const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const guilds = require('../guilds');
+const engagements = require('../guild-engagements');
 const { isAccountActive } = require('../account-visibility');
 
 const { pool, requireBuilder, validateOrRespond, parsePagination } = api;
@@ -110,7 +113,7 @@ 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) => {
+  router.use(['/guilds', '/me/guilds', '/me/guild-requests', '/me/guild-engagements', '/guild-requests'], (req, res, next) => {
     res.set('Cache-Control', 'no-store');
     next();
   });
@@ -389,5 +392,36 @@ module.exports = function guildRoutes() {
     res.json({ outcome: 'cancelled' });
   }));
 
+  // rank: any-builder — owner: file "this guild is applying to P" (ADR 0365 D2,
+  // task 1002303). Each member then sees it in their own inbox and applies as
+  // themselves; filing applies for nobody, the owner included. P unknown,
+  // inactive, or not on the map and Public is ONE 404 — no oracle on a private
+  // project. The owner test is re-asserted inside the INSERT. Re-filing restarts
+  // the 30-day window.
+  router.post('/guilds/:slug/engagements', requireBuilder, handle('POST /guilds/:slug/engagements', 'guild_engagement_failed', async (req, res) => {
+    if (validateOrRespond(req, res, { origin: { required: true, type: 'string', maxLength: 512 } })) 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 engagement = await engagements.fileEngagement({
+      guildId: o.guild.id, githubId: me.githubId, origin: req.body.origin,
+    }, { pool });
+    if (!engagement) return res.fail('unknown_project', 404);
+    res.json({ engagement });
+  }));
+
+  // rank: any-builder — MY inbox of guild engagements (ADR 0365): "G is applying
+  // to P" and "P invited G", for guilds I belong to, inside 30 days, naming only
+  // projects on the map and Public, an invite only if I was a member when it was
+  // sent, and never a project I already build on, hold an invite to, or applied
+  // to. count is the array's own length; client_id never crosses.
+  router.get('/me/guild-engagements', requireBuilder, handle('GET /me/guild-engagements', 'guild_engagements_read_failed', async (req, res) => {
+    const me = await actingAccount(req.builder);
+    if (me.fail) return res.fail(...me.fail);
+    const list = await engagements.listMyEngagements({ githubId: me.githubId }, { pool });
+    res.json({ engagements: list, count: list.length });
+  }));
+
   return router;
 };

package/modules/platform-identity/routes/my-projects.js

@@ -5,7 +5,9 @@
 //                                    apart, plus `applied`: the projects it has
 //                                    asked to join and when (ADR 0201 D1.3)
 //   POST /my-projects/join         — apply to a project: one click plus an optional
-//                                    note in the applicant's own words (task 1002330).
+//                                    note in the applicant's own words (task 1002330),
+//                                    and optionally WITH a guild that is engaging the
+//                                    project (`guild`, a slug; task 1002303, ADR 0365).
 //                                    Relayed; the project executes and decides —
 //                                    unless the platform's record says it is unpublished.
 //   POST /my-projects/:clientId/leave — self-service offboard (reflected to the hub)
@@ -25,6 +27,8 @@ const api = require('../../../src/module-api');
 const pi = require('../platform-identity');
 const projectStats = require('../project-stats');
 const applicationEcho = require('../application-echo');
+const guilds = require('../guilds');
+const guildEngagements = require('../guild-engagements');
 const hubKeys = require('../hub-keys');
 const { isAccountActive } = require('../account-visibility');
 const { projectPublishability } = require('../publish-gate');
@@ -219,12 +223,30 @@ module.exports = function myProjectsRoutes() {
     if (validateOrRespond(req, res, {
       origin: { required: true, type: 'string', maxLength: 512 },
       note: { type: 'string', maxLength: APPLICANT_NOTE_MAX },
+      guild: { type: 'string', maxLength: 39 },
     })) return;
     try {
       const client = await pi.getClientByOrigin(req.body.origin, { pool });
       if (!client || client.status !== 'active' || !client.origin) {
         return res.fail('unknown_project', 404);
       }
+      // Applying WITH a guild (ADR 0365 D2). The guild must still resolve FOR THE
+      // CALLER — a guild they belong to, engaging this project inside the window,
+      // by the same rule their inbox shows it — BEFORE anything is relayed. A guild
+      // that no longer does (they left, it aged out, the project stopped being
+      // named) is a 409 with nothing relayed and nothing echoed: the applicant
+      // chose to apply with that guild, so the hub never files it without one.
+      let guildId = null;
+      if (req.body.guild != null) {
+        const slug = guilds.lookupSlug(req.body.guild);
+        const engaged = slug ? await guildEngagements.engagementFor({
+          githubId: req.builder.github_id, slug, clientId: client.client_id,
+        }, { pool }) : null;
+        if (!engaged) {
+          return res.fail('guild_engagement_gone', { status: 409, message: 'that guild is no longer engaging this project — apply on your own instead' });
+        }
+        guildId = engaged.id;
+      }
       if (await isDarkMatter(client)) {
         return res.json({ ok: true, status: 'not_published', project: { name: client.name, origin: client.origin },
           message: RELAY_SENTENCE.not_published });
@@ -256,11 +278,13 @@ module.exports = function myProjectsRoutes() {
       // covers the project's own already_pending 200, D1.4), and refreshes the date.
       // Best-effort in both directions: a lost echo must never turn a filed
       // application into a reported failure, which is the only reason this is
-      // allowed to swallow its error.
+      // allowed to swallow its error. The echo carries the guild this application
+      // was made with — NULL when none, so a later solo application clears the
+      // label the reviewer sees (ADR 0365 D1).
       if (outcome.status === 'requested') {
         try {
           await applicationEcho.recordApplication(
-            { githubId: req.builder.github_id, clientId: client.client_id }, { pool },
+            { githubId: req.builder.github_id, clientId: client.client_id, guildId }, { pool },
           );
         } catch (e) {
           api.logger('platform-identity').error(`join echo write failed (non-fatal): ${e && e.message}`);

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

@@ -17,6 +17,9 @@
 //   POST  /projects/invite     — a `project.curate` holder OR the project's OWN owner:
 //                                where to invite — the project's hall (invite-authz.js,
 //                                invite-notices.js); writes nothing (ADR 0353)
+//   POST  /projects/invite-guild — the same gate: invite a PUBLIC guild — records the
+//                                `invited` engagement and answers one hall link per
+//                                member on its public roster (ADR 0365 D3)
 //   PATCH /projects/:id/featured — Archon: the feature / unfeature control
 //   PATCH /projects/:id/status   — `project.curate`: the TAKEDOWN lever (R08, ADR 0252
 //                                §5.1). Setting 'hidden' pins the row so the ADR 0246
@@ -33,6 +36,8 @@ const projectCatalog = require('../project-catalog');
 const projectStats = require('../project-stats');
 const inviteAuthz = require('../invite-authz');
 const inviteNotices = require('../invite-notices');
+const guilds = require('../guilds');
+const guildEngagements = require('../guild-engagements');
 
 const { pool, requireBuilder, requirePermission, validateOrRespond, parseId, corsPublicGet,
   parsePagination, pageMeta } = api;
@@ -168,6 +173,45 @@ module.exports = function projectsRoutes() {
     },
   );
 
+  // rank: metic+archon — own-or-metic in effect, the SAME gate as POST /projects/invite
+  // above and for the same reasons (a non-inviter gets that route's unchanged refusal,
+  // identical whether or not the project exists): a project invites a PUBLIC guild
+  // (task 1002303, ADR 0365 D3, amending ADR 0336 D7).
+  //
+  // IT WRITES NO INVITES (ADR 0353). It records the `invited` engagement — so members
+  // the inviter could not see get a "P invited this guild" notice and may apply
+  // themselves, and only while P is on the map and Public (ADR 0365 D4) — and answers
+  // one hall hand-off link per member on the guild's PUBLIC roster at this moment.
+  // The inviter sends each from the project's hall, so every invite is the project's
+  // own row. Members who join later inherit nothing. An unlisted guild cannot be
+  // addressed, so it answers the unknown-guild 404 byte for byte.
+  router.post(
+    '/projects/invite-guild',
+    requireBuilder,
+    inviteAuthz.requireProjectInviter({ curateGate: api.requirePermission('project.curate'), pool, log }),
+    async (req, res) => {
+      if (validateOrRespond(req, res, {
+        client_id: { required: true, type: 'string', maxLength: 200 },
+        guild: { required: true, type: 'string', maxLength: 39 },
+      })) return;
+      try {
+        const client = req.inviteTargetClient || await pi.getClient(req.body.client_id, { pool });
+        if (!client || client.status !== 'active' || !inviteNotices.hallInviteUrl(client.origin)) {
+          return res.fail('unknown_project', 404);
+        }
+        const slug = guilds.lookupSlug(req.body.guild);
+        const out = slug ? await guildEngagements.inviteGuild({
+          clientId: client.client_id, origin: client.origin, slug,
+        }, { pool }) : null;
+        if (!out) return res.fail('guild_not_found', 404);
+        return res.json({ invited: false, guild: out.guild, invites: out.invites, count: out.invites.length });
+      } catch (err) {
+        log.error({ err: err && err.message }, 'POST /projects/invite-guild failed');
+        res.fail('invite_guild_failed', { status: 500, message: 'internal error' });
+      }
+    },
+  );
+
   // rank: archon — the feature / unfeature control (the ADR 0141 §5 curation gate),
   // BOUNDED BY THE PUBLISH GATE (ADR 0182 D3, task 1002335). Featuring ranks among
   // projects already on the map; it is not a way ONTO it, so featuring a dark-matter

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

@@ -27,6 +27,8 @@ const hubDevice = require('../hub-device');
 const applicantProfile = require('../applicant-profile');
 const terms = require('../terms-acceptance');
 const applicationEcho = require('../application-echo');
+// The guild label the echo carries (task 1002303, ADR 0365 D5).
+const guildEngagements = require('../guild-engagements');
 const instanceFeedback = require('../instance-feedback');
 
 // One limiter per hub process for POST /sso/feedback (task 1004462).
@@ -638,8 +640,11 @@ module.exports = function ssoRoutes() {
   // profile view for its own reviewer queue, LIVE at render (privacy spec D7,
   // task 1002972). Server-to-server, client_id+client_secret auth, like the two
   // routes above. Answers { profile: null | { view:'public', … } | { view:
-  // 'sliver', … } } — the D7 rule, decided entirely inside
-  // ../applicant-profile.js.
+  // 'sliver', … }, guild } — the D7 rule, decided entirely inside
+  // ../applicant-profile.js, plus the guild the applicant applied with
+  // (ADR 0365 D5): { slug, name } while they are still a member of it (slug null
+  // for an unlisted guild), else null. A project on an older core reads only
+  // `profile` and ignores the rest (the ADR 0201 D2.2 compatibility rule).
   //
   // WHY A POST FOR A READ. The same reason /sso/activity/rollup is one: the
   // credentials are in the body, and a client_secret in a query string lands in
@@ -693,12 +698,25 @@ module.exports = function ssoRoutes() {
       );
       if (!applied) return res.fail('no_application', 404);
       const profile = await applicantProfile.getApplicantProfileView(b.github_id, { pool });
+      // The guild label rides only beside a profile: an applicant who discloses
+      // nothing discloses no guild either. BEST-EFFORT — a label is a convenience
+      // on the reviewer's queue, so a failed read answers null and never costs
+      // the profile. Read only here, after the echo gate above.
+      let guild = null;
+      if (profile) {
+        try {
+          guild = await guildEngagements.echoGuildLabel({ githubId: b.github_id, clientId: client.client_id }, { pool });
+        } catch (e) {
+          log.error('[platform-identity] /sso/applicant-profile guild label read failed (non-fatal)', e && e.message);
+          guild = null;
+        }
+      }
       // The rollup half is live-derived and hide must beat any cache (ADR 0171
       // D5) — and D7's "live at review time" says the same thing louder: a
       // cached applicant view is a snapshot, which is the one thing the rule
       // forbids.
       res.set('Cache-Control', 'no-store');
-      res.json({ profile });
+      res.json({ profile, guild });
     } catch (err) {
       log.error('[platform-identity] /sso/applicant-profile', err);
       res.fail('applicant_profile_failed', { status: 500, message: 'internal error' });

package/modules/public-landing/public/assets/cosmos.css

@@ -1325,6 +1325,13 @@ p.sec-p{font-size:var(--fs-lede);font-weight:500;color:var(--ink-soft);line-heig
 .mineJoinRow input::placeholder{color:var(--ink-faint);}
 .mineJoinNote{display:block;width:100%;box-sizing:border-box;margin-top:10px;min-height:64px;padding:12px 16px;font:inherit;font-size:14px;line-height:1.5;color:var(--ink);background:var(--bg-card);border:1px solid var(--ctl-line);border-radius:14px;resize:vertical;}
 .mineJoinNote::placeholder{color:var(--ink-faint);}
+/* the guild cards (task 1002303, R27): a second list under the invitations, one
+   hairline between the two when both have rows; each card's note waits behind
+   "Add a note", and its status line takes no room until it has something to say */
+.mineRows:not(:empty)+.mineRows .mineRow:first-child{border-top:1px solid var(--rule-soft);}
+.engageRow .mineJoinNote{max-width:62ch;}
+.engageRow .projMsg{margin-top:6px;min-height:0;}
+.engageRow .projMsg:empty{margin:0;}
 
 /* ── the ledger row: planet · name and chip · the facts · the rail · the
    doors. The planet and the doors are fixed widths; the three middle tracks