@bongos/core 1.21.56 → 1.21.58

package/tests/guild_engagement_db.mjs

@@ -0,0 +1,240 @@
+// tests/guild_engagement_db.mjs — guild engagements against REAL SQL (task
+// 1002303, R27; ADR 0336 D7 as amended by ADR 0365).
+//
+// Why a real database: the rules that matter here live in the schema and in
+// single statements a fake pool cannot execute — the FK that cascades a
+// dissolved guild's engagements, the one that SETs NULL on the echo instead,
+// the upsert that restarts the 30-day window in place, the read-time window
+// itself, the joined_at rule that keeps a later joiner from inheriting an
+// invite, and the owner test and naming rule riding inside one INSERT. The
+// DB-free sibling, tests/guild_engagement.mjs, covers the route layer and the
+// statement shapes.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set so the default DB-free lane never runs it. Fixture ids are
+// high-numbered, every guild slug starts r27-, every client id r27- and every
+// origin https://r27-…, so a shared DB is safe; all fixtures are deleted before
+// and after.
+//
+// Run:  DATABASE_URL=... node tests/guild_engagement_db.mjs
+
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { strict as assert } from 'node:assert';
+
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const MIG_DIR = join(here, '..', 'modules', 'platform-identity', 'migrations');
+const migrationSql = (f) => readFileSync(join(MIG_DIR, f), 'utf8');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`guild_engagement_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const guilds = require('../modules/platform-identity/guilds.js');
+const engagements = require('../modules/platform-identity/guild-engagements.js');
+const { recordApplication } = require('../modules/platform-identity/application-echo.js');
+
+const OWNER = 9002303001;   // public, active — owns the guild
+const MEMBER = 9002303002;  // public, active — a member from long ago
+const LATE = 9002303003;    // public, active — joins after the project invites the guild
+const PRIVM = 9002303004;   // PRIVATE account, a shown member
+const SHYM = 9002303005;    // public account, a member NOT shown on the page
+const ALL_IDS = [OWNER, MEMBER, LATE, PRIVM, SHYM];
+
+const ORIGIN = (k) => `https://r27-${k}.example`;
+const PROJECTS = {
+  pub: { visibility: 'public' },
+  inv: { visibility: 'public' },
+  priv: { visibility: 'private' },
+};
+
+const q = (sql, params) => pool.query(sql, params);
+async function cleanup() {
+  await q(`DELETE FROM platform_identity_guilds WHERE slug LIKE 'r27-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_guild_engagements WHERE client_id LIKE 'r27-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_application_echoes WHERE client_id LIKE 'r27-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_project_memberships WHERE client_id LIKE 'r27-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_projects WHERE origin LIKE 'https://r27-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_sso_clients WHERE client_id LIKE 'r27-%'`).catch(() => {});
+  await q(`DELETE FROM platform_identity_accounts WHERE github_id = ANY($1::bigint[])`, [ALL_IDS]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+async function rejects(promise, code, msg) {
+  let caught = null;
+  try { await promise; } catch (e) { caught = e; }
+  ok(caught && caught.code === code, `${msg} (expected ${code}, got ${caught ? caught.code : 'no error'})`);
+}
+const engagementRows = async (clientId) => (await q(
+  `SELECT kind, created_at FROM platform_identity_guild_engagements WHERE client_id = $1 ORDER BY kind`, [clientId])).rows;
+const inboxOf = async (gid) => (await engagements.listMyEngagements({ githubId: gid }, { pool }))
+  .map((e) => `${e.guild.slug}|${e.project.origin.replace('https://r27-', '').replace('.example', '')}|${e.kind}`);
+
+try {
+  // The migrations this domain reads, all idempotent: accounts + consent,
+  // handles, privacy, terms; clients, memberships and the project catalog with
+  // its door columns; the echo; guilds; and the engagements.
+  for (const f of [
+    'platform_identity_001_tables.sql', 'platform_identity_003_project_memberships.sql',
+    'platform_identity_004_projects.sql', 'platform_identity_007_profile_consent.sql',
+    'platform_identity_008_handle.sql', 'platform_identity_011_project_visibility.sql',
+    'platform_identity_012_account_privacy.sql', 'platform_identity_016_application_echo.sql',
+    'platform_identity_019_terms_acceptance.sql', 'platform_identity_020_visibility_pull.sql',
+    'platform_identity_025_guilds.sql', 'platform_identity_030_guild_engagements.sql',
+  ]) await q(migrationSql(f));
+  // The membership_kind rename (010 expand, 021 contract) is not re-runnable once
+  // contracted, so it is applied only to a table still in its 003 shape. Both
+  // record themselves in the core migrations ledger, which a scratch DB lacks.
+  const renamed = (await q(`SELECT 1 FROM information_schema.columns
+                             WHERE table_name = 'platform_identity_project_memberships' AND column_name = 'membership_kind'`)).rowCount > 0;
+  if (!renamed) {
+    await q('CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())');
+    for (const f of ['platform_identity_010_membership_kind.sql', 'platform_identity_021_drop_legacy_role.sql']) await q(migrationSql(f));
+  }
+  await q(migrationSql('platform_identity_030_guild_engagements.sql')); // re-runnable
+  await cleanup();
+
+  // --- 1. the schema holds its own rules ------------------------------------
+  const cols = (await q(
+    `SELECT column_name FROM information_schema.columns WHERE table_name = 'platform_identity_guild_engagements' ORDER BY ordinal_position`)).rows
+    .map((r) => r.column_name);
+  ok(JSON.stringify(cols) === JSON.stringify(['guild_id', 'client_id', 'kind', 'created_at']),
+    'the engagement table is (guild_id, client_id, kind, created_at): no filer, no status (ADR 0201 D1.3)');
+  const fk = async (table, column) => (await q(
+    `SELECT c.confdeltype FROM pg_constraint c
+       JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+      WHERE c.contype = 'f' AND c.conrelid = $1::regclass AND a.attname = $2`, [table, column])).rows[0]?.confdeltype;
+  ok(await fk('platform_identity_guild_engagements', 'guild_id') === 'c', 'the engagement FK CASCADES on dissolve');
+  ok(await fk('platform_identity_application_echoes', 'guild_id') === 'n', 'the echo FK SETs NULL on dissolve');
+  const echoCol = (await q(
+    `SELECT is_nullable FROM information_schema.columns WHERE table_name = 'platform_identity_application_echoes' AND column_name = 'guild_id'`)).rows[0];
+  ok(echoCol && echoCol.is_nullable === 'YES', 'the echo\'s guild_id is nullable — a solo application has none');
+
+  // --- fixtures ---------------------------------------------------------------
+  await q(
+    `INSERT INTO platform_identity_accounts
+       (github_id, github_login, handle, display_name, profile_state, terms_accepted_at, account_visibility)
+     VALUES ($1, 'r27own', 'r27own', 'Owner', 'active', now(), 'public'),
+            ($2, 'r27mem', 'r27mem', 'Member', 'active', now(), 'public'),
+            ($3, 'r27late', 'r27late', 'Late', 'active', now(), 'public'),
+            ($4, 'r27privm', 'r27privm', 'PrivM', 'active', now(), 'private'),
+            ($5, 'r27shym', 'r27shym', 'ShyM', 'active', now(), 'public')`,
+    ALL_IDS,
+  );
+  for (const [k, p] of Object.entries(PROJECTS)) {
+    await q(`INSERT INTO platform_identity_sso_clients (client_id, secret_hash, name, redirect_uris, origin, status)
+             VALUES ($1, '', $2, '{}', $3, 'active')`, [`r27-${k}`, `R27 ${k}`, ORIGIN(k)]);
+    await q(`INSERT INTO platform_identity_projects (origin, name, description, visibility, visibility_source, status)
+             VALUES ($1, $2, 'a real description', $3, 'control-plane', 'active')`, [ORIGIN(k), `R27 Project ${k}`, p.visibility]);
+  }
+  const created = await guilds.createGuild({ githubId: OWNER, slug: 'r27-guild', name: 'R27 Guild', visibility: 'public' }, { pool });
+  ok(created.guild && created.guild.slug === 'r27-guild', 'the guild exists, its creator its owner');
+  const gid = (await q(`SELECT id FROM platform_identity_guilds WHERE slug = 'r27-guild'`)).rows[0].id;
+  await q(`INSERT INTO platform_identity_guild_members (guild_id, github_id, membership_kind, shown_publicly, joined_at)
+           VALUES ($1, $2, 'member', true, now() - interval '100 days'),
+                  ($1, $3, 'member', true, now() - interval '90 days'),
+                  ($1, $4, 'member', false, now() - interval '90 days')`, [gid, MEMBER, PRIVM, SHYM]);
+
+  await rejects(q(`INSERT INTO platform_identity_guild_engagements (guild_id, client_id, kind) VALUES ($1, 'r27-pub', 'pending')`, [gid]),
+    '23514', 'kind is apply or invited, nothing else');
+
+  // --- 2. filing: the owner, a named project, one statement --------------------
+  const filed = await engagements.fileEngagement({ guildId: gid, githubId: OWNER, origin: `${ORIGIN('pub')}/` }, { pool });
+  ok(filed && filed.kind === 'apply' && filed.project.origin === ORIGIN('pub') && filed.guild.slug === 'r27-guild',
+    'the owner files "this guild is applying to P"');
+  ok(await engagements.fileEngagement({ guildId: gid, githubId: MEMBER, origin: ORIGIN('inv') }, { pool }) === null
+    && (await engagementRows('r27-inv')).length === 0,
+    'a member who is not the owner files nothing — the owner test is in the INSERT');
+  ok(await engagements.fileEngagement({ guildId: gid, githubId: OWNER, origin: ORIGIN('priv') }, { pool }) === null
+    && (await engagementRows('r27-priv')).length === 0,
+    'a private project cannot be named, so it cannot be applied to as a guild (the naming rule at filing)');
+  ok(await engagements.fileEngagement({ guildId: gid, githubId: OWNER, origin: 'https://r27-nowhere.example' }, { pool }) === null,
+    'an unknown origin is the same null');
+  await rejects(q(`INSERT INTO platform_identity_guild_engagements (guild_id, client_id, kind) VALUES ($1, 'r27-pub', 'apply')`, [gid]),
+    '23505', 'the key is (guild, project, kind): a second row for the same act is a database error');
+
+  // --- 3. the window is read-time, and re-filing restarts it ------------------
+  ok((await inboxOf(MEMBER)).includes('r27-guild|pub|apply'), 'a member sees the apply engagement in their inbox');
+  await q(`UPDATE platform_identity_guild_engagements SET created_at = now() - interval '31 days' WHERE client_id = 'r27-pub'`);
+  ok(!(await inboxOf(MEMBER)).includes('r27-guild|pub|apply'), 'a row older than 30 days is invisible …');
+  ok((await engagementRows('r27-pub')).length === 1, '… and still there: no sweep, nothing expired');
+  ok(await engagements.engagementFor({ githubId: MEMBER, slug: 'r27-guild', clientId: 'r27-pub' }, { pool }) === null,
+    'an aged-out engagement no longer lets anyone apply with the guild');
+  await engagements.fileEngagement({ guildId: gid, githubId: OWNER, origin: ORIGIN('pub') }, { pool });
+  const restarted = await engagementRows('r27-pub');
+  ok(restarted.length === 1 && Date.now() - new Date(restarted[0].created_at).getTime() < 60_000,
+    're-filing restarts the window IN PLACE — one row, created_at now');
+  ok((await inboxOf(MEMBER)).includes('r27-guild|pub|apply'), 'and the card is back');
+
+  // --- 4. a project invites the guild: links to the public roster, a notice for the rest
+  const inv = await engagements.inviteGuild({ clientId: 'r27-inv', origin: ORIGIN('inv'), slug: 'r27-guild' }, { pool });
+  ok(inv && JSON.stringify(inv.invites.map((i) => i.handle)) === JSON.stringify(['r27own', 'r27mem']),
+    'one hall link per member on the PUBLIC roster: the private account and the unshown member are not on it');
+  ok(inv.invites.every((i) => i.invite_url.startsWith(`${ORIGIN('inv')}/builders/watch?invite=r27`)), 'each link is the project\'s own hall');
+  ok((await engagementRows('r27-inv')).map((r) => r.kind).join() === 'invited', 'the invited engagement is recorded');
+  const privInv = await engagements.inviteGuild({ clientId: 'r27-priv', origin: ORIGIN('priv'), slug: 'r27-guild' }, { pool });
+  ok(privInv.invites.length === 2 && (await engagementRows('r27-priv')).length === 0,
+    'a private project still gets its links, but leaves no notice for the members it could not see');
+  await q(`UPDATE platform_identity_guilds SET visibility = 'unlisted' WHERE id = $1`, [gid]);
+  ok(await engagements.inviteGuild({ clientId: 'r27-inv', origin: ORIGIN('inv'), slug: 'r27-guild' }, { pool }) === null,
+    'an unlisted guild cannot be invited');
+  await q(`UPDATE platform_identity_guilds SET visibility = 'public' WHERE id = $1`, [gid]);
+
+  // --- 5. a later joiner does not inherit the invite --------------------------
+  await q(`UPDATE platform_identity_guild_engagements SET created_at = now() - interval '1 hour' WHERE client_id = 'r27-inv'`);
+  await q(`INSERT INTO platform_identity_guild_members (guild_id, github_id, membership_kind, shown_publicly, joined_at)
+           VALUES ($1, $2, 'member', true, now())`, [gid, LATE]);
+  ok((await inboxOf(PRIVM)).includes('r27-guild|inv|invited'),
+    'a member the inviter could NOT see gets the "P invited this guild" notice (ADR 0336 D7)');
+  ok(!(await inboxOf(LATE)).includes('r27-guild|inv|invited'), 'a member who joined AFTER the invite does not see it');
+  ok((await inboxOf(LATE)).includes('r27-guild|pub|apply'), '… but sees the guild\'s apply engagement, whenever they joined');
+  ok(await engagements.engagementFor({ githubId: LATE, slug: 'r27-guild', clientId: 'r27-inv' }, { pool }) === null,
+    'and cannot apply with an invite they never saw — the join and the inbox share one rule');
+  const forPriv = await engagements.engagementFor({ githubId: PRIVM, slug: 'R27-Guild'.toLowerCase(), clientId: 'r27-inv' }, { pool });
+  ok(forPriv && String(forPriv.id) === String(gid), 'a member who saw the notice may apply with the guild');
+
+  // --- 6. the inbox drops what the caller has already done --------------------
+  await recordApplication({ githubId: MEMBER, clientId: 'r27-inv', guildId: gid }, { pool });
+  ok(!(await inboxOf(MEMBER)).some((x) => x.includes('|inv|')), 'a live application echo removes the card');
+  await q(`INSERT INTO platform_identity_project_memberships (client_id, github_id, membership_kind, joined_at)
+           VALUES ('r27-pub', $1, 'pending', now() - interval '40 days')`, [MEMBER]);
+  ok((await inboxOf(MEMBER)).includes('r27-guild|pub|apply'), 'a LAPSED invite notice is no invite: the card stays');
+  await q(`UPDATE platform_identity_project_memberships SET joined_at = now() WHERE client_id = 'r27-pub' AND github_id = $1`, [MEMBER]);
+  ok(!(await inboxOf(MEMBER)).includes('r27-guild|pub|apply'), 'a live invite notice removes the card');
+  await q(`UPDATE platform_identity_project_memberships SET membership_kind = 'member' WHERE client_id = 'r27-pub' AND github_id = $1`, [MEMBER]);
+  ok(!(await inboxOf(MEMBER)).includes('r27-guild|pub|apply'), 'so does building on the project');
+
+  // --- 7. the label: still a member, the latest application, dissolve -----------
+  const label = await engagements.echoGuildLabel({ githubId: MEMBER, clientId: 'r27-inv' }, { pool });
+  ok(label && label.slug === 'r27-guild' && label.name === 'R27 Guild', 'the echo carries the guild while the applicant is in it');
+  await recordApplication({ githubId: PRIVM, clientId: 'r27-inv', guildId: gid }, { pool });
+  await q(`DELETE FROM platform_identity_guild_members WHERE guild_id = $1 AND github_id = $2`, [gid, PRIVM]);
+  ok(await engagements.echoGuildLabel({ githubId: PRIVM, clientId: 'r27-inv' }, { pool }) === null,
+    'an applicant who LEFT the guild carries no label');
+  await recordApplication({ githubId: MEMBER, clientId: 'r27-inv' }, { pool });
+  const solo = (await q(`SELECT guild_id FROM platform_identity_application_echoes WHERE github_id = $1 AND client_id = 'r27-inv'`, [MEMBER])).rows[0];
+  ok(solo && solo.guild_id === null, 'a later SOLO application clears the label — the most recent one decides');
+  await recordApplication({ githubId: MEMBER, clientId: 'r27-inv', guildId: gid }, { pool });
+
+  ok(await guilds.dissolveGuild({ guildId: gid, githubId: OWNER }, { pool }), 'the owner dissolves the guild');
+  ok((await q(`SELECT count(*)::int AS n FROM platform_identity_guild_engagements WHERE client_id LIKE 'r27-%'`)).rows[0].n === 0,
+    'dissolving CASCADES to every engagement (no tombstone)');
+  const echo = (await q(`SELECT guild_id FROM platform_identity_application_echoes WHERE github_id = $1 AND client_id = 'r27-inv'`, [MEMBER])).rows[0];
+  ok(echo && echo.guild_id === null, 'the application itself stands; only its label is SET NULL');
+
+  console.log(`\nguild_engagement_db.mjs: ${pass} passed`);
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/hub_engagement_cards.mjs

@@ -0,0 +1,307 @@
+// tests/hub_engagement_cards.mjs — the guild cards in /projects?view=mine's
+// Invitations, EXECUTED (task 1002303, R27; ADR 0365 D2/D3).
+//
+// GET /me/guild-engagements names what the guilds a builder is in have going with
+// a project: "G is applying to P" (the guild's owner put it forward) and "P
+// invited G". Each card's Apply is the hub's ONE join relay (postJoinRequest,
+// tests/card_apply_ui.mjs pins it for the map's card) with `guild` added — the
+// builder applies as themselves, never as the guild. What these pin:
+//   • the two kinds draw as two sentences, with the project's host and a plain
+//     hint; a row the page cannot act on is dropped, never drawn with a dead button
+//   • the Invitations section shows while EITHER list has a row, and hides when
+//     neither does (the projects' own invites and the guild cards are one section)
+//   • Apply sends exactly { origin, guild } — plus the builder's own note when they
+//     open "Add a note" and write one — on the cookie session, to /my-projects/join
+//   • `requested` is the only answer that reads as applied; the relay's other
+//     answers are said in its own words and the card stays re-tryable
+//   • 409 guild_engagement_gone says the guild application has ended and offers
+//     the plain application, which then sends no `guild`
+//   • an expired session and a dead network are said as such
+//   • textContent / createElement only — no markup built from strings
+//
+// The idiom is tests/project_invite_ui.mjs: lift the region out of projects.html,
+// run it in a node:vm under a DOM stub, drive real clicks, and assert the slice
+// boundaries, so a rename can never leave this file executing an empty string.
+//
+// DB-free. Run:  node --test tests/hub_engagement_cards.mjs
+
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const HUB = fs.readFileSync(path.join(LANDING, 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = (HUB.match(/<script>([\s\S]*?)<\/script>\s*<\/body>/) || [, ''])[1];
+
+// the rows region: mineEl/mineRow, the two lists, the section, and the guild cards
+const START = SCRIPT.indexOf('  function mineEl(tag, cls)');
+const END = SCRIPT.indexOf('\n  }\n', SCRIPT.indexOf('  function loadEngagements() {')) + 5;
+assert.ok(START > 0, 'the region starts at mineEl');
+assert.ok(END > START, 'and ends with loadEngagements');
+const REGION = SCRIPT.slice(START, END);
+for (const fn of ['function mineRow(', 'function renderInvitesList(', 'function paintInvitesSection(', 'function loadInvites(',
+  'function engageLine(', 'function engageRow(', 'function renderEngagements(', 'function loadEngagements(']) {
+  assert.ok(REGION.includes(fn), `the region must carry ${fn}`);
+}
+const RELAY_START = SCRIPT.indexOf('function postJoinRequest(');
+const RELAY = SCRIPT.slice(RELAY_START, SCRIPT.indexOf('\n  }', RELAY_START) + 4);
+assert.ok(RELAY_START > 0 && RELAY.endsWith('}'), 'postJoinRequest is findable');
+const CARDS = REGION.slice(REGION.indexOf('function paintInvitesSection('));
+
+// ── the DOM stub ─────────────────────────────────────────────────────────────
+// Just wide enough for the region: created elements keep their children; setting
+// textContent clears them, as in a browser; querySelector answers one class.
+function el(tag) {
+  const n = { tag, children: [], _text: '', className: '', hidden: false, disabled: false, value: '', attrs: {}, _on: {}, parent: null };
+  Object.defineProperty(n, 'textContent', {
+    get() { return n._text + n.children.map((c) => c.textContent).join(''); },
+    set(v) { n._text = String(v); n.children = []; },
+  });
+  n.appendChild = (c) => { c.parent = n; n.children.push(c); return c; };
+  n.remove = () => { if (n.parent) n.parent.children = n.parent.children.filter((c) => c !== n); };
+  n.setAttribute = (k, v) => { n.attrs[k] = String(v); };
+  n.getAttribute = (k) => (k in n.attrs ? n.attrs[k] : null);
+  n.addEventListener = (t, f) => { (n._on[t] ||= []).push(f); };
+  n.focus = () => { n.focused = true; };
+  n.querySelector = (sel) => {
+    const cls = sel.replace(/^\./, '');
+    const walk = (x) => { for (const c of x.children) { if (String(c.className).split(' ').includes(cls)) return c; const d = walk(c); if (d) return d; } return null; };
+    return walk(n);
+  };
+  return n;
+}
+
+const TIDEPOOL = { guild: { slug: 'forge-crew', name: 'Forge Crew' }, kind: 'apply', project: { name: 'Tidepool', origin: 'https://tidepool.example.com' }, created_at: '2026-10-03T12:00:00.000Z' };
+const LANTERN = { guild: { slug: 'forge-crew', name: 'Forge Crew' }, kind: 'invited', project: { name: 'Lantern Works', origin: 'https://lantern.example.com' }, created_at: '2026-10-02T09:30:00.000Z' };
+const REQUESTED = { ok: true, status: 200, body: { ok: true, status: 'requested', message: 'Requested access. The project’s owner admits new builders.' } };
+
+function boot({ answers = [] } = {}) {
+  const ids = new Map();
+  for (const id of ['mineInvites', 'invitesList', 'engageList', 'buildingList', 'buildingEmpty']) ids.set(id, el(id === 'mineInvites' ? 'section' : 'ul'));
+  ids.get('mineInvites').hidden = true;
+  const requests = [];
+  const queued = answers.slice();
+  const fetch = (url, init = {}) => {
+    requests.push({ url, method: init.method || 'GET', body: init.body ? JSON.parse(init.body) : undefined, credentials: init.credentials });
+    const a = typeof queued[0] === 'function' ? queued.shift()(url) : (queued.shift() || REQUESTED);
+    if (a.reject) return Promise.reject(new Error('offline'));
+    return Promise.resolve({ ok: a.ok, status: a.status, json: () => Promise.resolve(a.body) });
+  };
+  const document = { createElement: el, createTextNode: (t) => ({ tag: '#text', textContent: String(t), children: [], className: '' }) };
+  const sandbox = {
+    document, fetch, console, Promise, JSON, String, Object, Array, URL,
+    $: (id) => ids.get(id) || null,
+    API: '/api/bongos',
+    appliedOrigins: {}, mineOrigins: {},
+    hostOf: (o) => String(o || '').replace(/^https?:\/\//, '').replace(/^www\./, '').replace(/\/.*$/, '').toLowerCase(),
+    safeHttpUrl: (raw) => { try { const u = new URL(String(raw)); return (u.protocol === 'https:' || u.protocol === 'http:') ? u.href : ''; } catch (e) { return ''; } },
+    jsonOrEmpty: (res) => res.json().catch(() => ({})),
+    apiError: (data, status) => { const e = (data && data.error) || {}; return { code: e.code || ('http_' + status), message: e.message || '' }; },
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(RELAY, sandbox, { filename: 'projects.html#join-relay' });
+  vm.runInContext(REGION, sandbox, { filename: 'projects.html#mine-rows' });
+  const settle = async () => { for (let i = 0; i < 30; i++) await Promise.resolve(); };
+  const cards = () => ids.get('engageList').children;
+  const part = (card, cls) => card.querySelector('.' + cls);
+  const button = (card, cls) => part(card, 'mineRow__actions').children.find((b) => String(b.className).split(' ').includes(cls));
+  const click = async (b) => { for (const f of b._on.click || []) f({}); await settle(); };
+  return { sandbox, ids, requests, settle, cards, part, button, click, section: () => ids.get('mineInvites') };
+}
+
+// ── drawing the cards ────────────────────────────────────────────────────────
+
+test('the two kinds draw as two plain sentences, with the project’s host, a hint, and their own Apply', () => {
+  const ui = boot();
+  ui.sandbox.renderEngagements([TIDEPOOL, LANTERN]);
+  const [a, b] = ui.cards();
+  assert.equal(ui.cards().length, 2);
+  assert.equal(ui.part(a, 'mineRow__name').textContent, 'Forge Crew is applying to Tidepool — apply with them?');
+  assert.equal(ui.part(b, 'mineRow__name').textContent, 'Lantern Works invited Forge Crew');
+  assert.equal(ui.part(a, 'mineRow__host').textContent, 'tidepool.example.com');
+  assert.equal(ui.part(a, 'mineRow__hint').textContent, 'You apply as yourself — add a note for the owner if you like.');
+  assert.equal(a.className, 'mineRow engageRow');
+  assert.equal(ui.button(a, 'btn').textContent, 'Apply');
+  assert.equal(ui.button(a, 'linklike').textContent, 'Add a note');
+  assert.equal(ui.part(a, 'mineJoinNote').hidden, true, 'the note waits behind "Add a note"');
+  assert.equal(ui.part(a, 'mineJoinNote').maxLength, 400, 'the join note’s own limit');
+  assert.equal(ui.part(a, 'projMsg').getAttribute('role'), 'status');
+  assert.equal(ui.section().hidden, false, 'guild cards alone show the Invitations section');
+});
+
+test('a row the page cannot act on is dropped, never drawn with a button that fails', () => {
+  const ui = boot();
+  ui.sandbox.renderEngagements([
+    { ...TIDEPOOL, kind: 'merged' },
+    { ...TIDEPOOL, guild: { slug: null, name: 'Night Shift' } },
+    { ...TIDEPOOL, guild: null },
+    { ...TIDEPOOL, project: { name: 'Bad', origin: 'javascript:alert(1)' } },
+    { ...TIDEPOOL, project: null },
+    null,
+  ]);
+  assert.equal(ui.cards().length, 0);
+  assert.equal(ui.section().hidden, true, 'nothing to show: the section hides');
+});
+
+test('the section shows while EITHER list has a row, and a decline that empties both hides it', async () => {
+  const ui = boot({ answers: [{ ok: true, status: 200, body: { ok: true } }] });
+  ui.sandbox.renderInvitesList([{ client_id: 'cb-grove', name: 'The Grove', origin: 'https://grove.example.com' }]);
+  ui.sandbox.renderEngagements([]);
+  assert.equal(ui.section().hidden, false, 'a project’s own invite alone');
+  ui.sandbox.renderEngagements([TIDEPOOL]);
+  ui.sandbox.renderInvitesList([]);
+  assert.equal(ui.section().hidden, false, 'guild cards alone');
+  ui.sandbox.renderEngagements([]);
+  assert.equal(ui.section().hidden, true, 'neither');
+
+  ui.sandbox.renderInvitesList([{ client_id: 'cb-grove', name: 'The Grove', origin: 'https://grove.example.com' }]);
+  const row = ui.ids.get('invitesList').children[0];
+  const decline = row.querySelector('.mineRow__actions').children.find((b) => b.textContent === 'Decline');
+  await ui.click(decline);
+  assert.equal(ui.ids.get('invitesList').children.length, 0);
+  assert.equal(ui.section().hidden, true, 'the last decline hides it when there is no guild card either');
+});
+
+test('loadInvites reads both lists, and a guild read that fails is silent', async () => {
+  const ui = boot({ answers: [
+    (url) => (url.endsWith('/my-projects/invites') ? { ok: true, status: 200, body: { invites: [] } } : { ok: false, status: 500, body: {} }),
+    (url) => (url.endsWith('/my-projects/invites') ? { ok: true, status: 200, body: { invites: [] } } : { ok: false, status: 500, body: {} }),
+  ] });
+  await ui.sandbox.loadInvites();
+  await ui.settle();
+  assert.deepEqual(ui.requests.map((r) => `${r.method} ${r.url}`).sort(), ['GET /api/bongos/me/guild-engagements', 'GET /api/bongos/my-projects/invites']);
+  for (const r of ui.requests) assert.equal(r.credentials, 'same-origin', 'own-scope reads, on the cookie session');
+  assert.equal(ui.cards().length, 0);
+  assert.equal(ui.section().hidden, true);
+
+  const ok = boot({ answers: [
+    (url) => (url.endsWith('/me/guild-engagements') ? { ok: true, status: 200, body: { engagements: [TIDEPOOL], count: 1 } } : { ok: true, status: 200, body: { invites: [] } }),
+    (url) => (url.endsWith('/me/guild-engagements') ? { ok: true, status: 200, body: { engagements: [TIDEPOOL], count: 1 } } : { ok: true, status: 200, body: { invites: [] } }),
+  ] });
+  await ok.sandbox.loadInvites();
+  await ok.settle();
+  assert.equal(ok.cards().length, 1);
+  assert.equal(ok.section().hidden, false);
+});
+
+// ── applying ─────────────────────────────────────────────────────────────────
+
+test('Apply sends exactly { origin, guild } to the one join relay, on the cookie session — you apply as yourself', async () => {
+  const ui = boot();
+  ui.sandbox.renderEngagements([TIDEPOOL]);
+  await ui.click(ui.button(ui.cards()[0], 'btn'));
+  assert.equal(ui.requests.length, 1);
+  assert.equal(ui.requests[0].url, '/api/bongos/my-projects/join');
+  assert.equal(ui.requests[0].method, 'POST');
+  assert.equal(ui.requests[0].credentials, 'same-origin');
+  assert.deepEqual(ui.requests[0].body, { origin: 'https://tidepool.example.com', guild: 'forge-crew' },
+    'the project’s own origin as the read gave it, and the guild’s slug — nothing names anyone else');
+});
+
+test('"Add a note" opens the card’s own note, and the note rides along, trimmed', async () => {
+  const ui = boot();
+  ui.sandbox.renderEngagements([TIDEPOOL, LANTERN]);
+  const card = ui.cards()[0];
+  await ui.click(ui.button(card, 'linklike'));
+  assert.equal(ui.part(card, 'mineJoinNote').hidden, false);
+  assert.equal(ui.part(card, 'mineJoinNote').focused, true, 'focus goes to the note it opened');
+  assert.equal(ui.button(card, 'linklike').hidden, true);
+  assert.equal(ui.part(ui.cards()[1], 'mineJoinNote').hidden, true, 'the other card’s note stays shut');
+  ui.part(card, 'mineJoinNote').value = '  I like the boring parts too.  ';
+  await ui.click(ui.button(card, 'btn'));
+  assert.deepEqual(ui.requests[0].body, { origin: 'https://tidepool.example.com', note: 'I like the boring parts too.', guild: 'forge-crew' });
+});
+
+test('requested is the one answer that reads as applied: the button says so and stays down, and the map learns it too', async () => {
+  const ui = boot({ answers: [REQUESTED] });
+  ui.sandbox.renderEngagements([TIDEPOOL]);
+  const card = ui.cards()[0];
+  await ui.click(ui.button(card, 'linklike'));
+  await ui.click(ui.button(card, 'btn'));
+  assert.equal(ui.button(card, 'btn').textContent, 'Applied');
+  assert.equal(ui.button(card, 'btn').disabled, true);
+  assert.equal(ui.button(card, 'btn').className, 'btn small ghost', 'no longer pressable, so no longer the accent');
+  assert.equal(ui.part(card, 'mineJoinNote').hidden, true, 'a sent note is not offered again');
+  assert.equal(ui.part(card, 'mineRow__hint').hidden, true, 'nor is the hint about one');
+  assert.equal(ui.part(card, 'projMsg').className, 'projMsg ok');
+  assert.equal(ui.part(card, 'projMsg').textContent, 'Requested access. The project’s owner admits new builders.', 'the relay’s own words');
+  assert.equal(ui.sandbox.appliedOrigins['tidepool.example.com'], true, 'the map’s Apply reads the same echo');
+});
+
+test('409 guild_engagement_gone: the guild application has ended, the plain application is offered, and it sends no guild', async () => {
+  const ui = boot({ answers: [{ ok: false, status: 409, body: { error: { code: 'guild_engagement_gone', message: 'guild_engagement_gone' } } }, REQUESTED] });
+  ui.sandbox.renderEngagements([LANTERN]);
+  const card = ui.cards()[0];
+  await ui.click(ui.button(card, 'btn'));
+  assert.equal(ui.part(card, 'projMsg').textContent, 'That guild application has ended — you can still apply on your own.');
+  assert.equal(ui.button(card, 'btn').textContent, 'Apply on my own');
+  assert.equal(ui.button(card, 'btn').disabled, false);
+  assert.equal(ui.sandbox.appliedOrigins['lantern.example.com'], undefined, 'nothing was relayed, so nothing reads as applied');
+
+  await ui.click(ui.button(card, 'btn'));
+  assert.deepEqual(ui.requests[1].body, { origin: 'https://lantern.example.com' }, 'on your own means no guild');
+  assert.equal(ui.button(card, 'btn').textContent, 'Applied');
+});
+
+test('the relay’s other answers are said in its own words, and the card stays re-tryable', async () => {
+  const ui = boot({ answers: [
+    { ok: true, status: 200, body: { ok: true, status: 'invite_only', message: 'This project is invite-only — it doesn’t take requests.' } },
+    { ok: false, status: 404, body: { error: { code: 'unknown_project', message: 'no such project' } } },
+    { ok: false, status: 500, body: {} },
+  ] });
+  ui.sandbox.renderEngagements([TIDEPOOL]);
+  const card = ui.cards()[0];
+  await ui.click(ui.button(card, 'btn'));
+  assert.equal(ui.part(card, 'projMsg').className, 'projMsg', 'the door’s answer, not an error');
+  assert.match(ui.part(card, 'projMsg').textContent, /invite-only/);
+  assert.equal(ui.button(card, 'btn').textContent, 'Apply');
+  assert.equal(ui.button(card, 'btn').disabled, false);
+  await ui.click(ui.button(card, 'btn'));
+  assert.equal(ui.part(card, 'projMsg').className, 'projMsg err');
+  assert.equal(ui.part(card, 'projMsg').textContent, 'no such project');
+  await ui.click(ui.button(card, 'btn'));
+  assert.equal(ui.part(card, 'projMsg').textContent, 'Could not reach that project — try again in a moment.');
+});
+
+test('an expired session offers a way back in, built from elements; a dead network is said as one', async () => {
+  const ui = boot({ answers: [{ ok: false, status: 401, body: null }, { reject: true }] });
+  ui.sandbox.renderEngagements([TIDEPOOL]);
+  const card = ui.cards()[0];
+  await ui.click(ui.button(card, 'btn'));
+  const msg = ui.part(card, 'projMsg');
+  assert.equal(msg.className, 'projMsg err');
+  assert.equal(msg.textContent, 'Your session expired — sign in again.');
+  const link = msg.children.find((c) => c.tag === 'a');
+  assert.equal(link.href, '/api/bongos/auth/web/start?return=/projects%3Fview%3Dmine&repos=1', 'back to this view, with the repo scope every hub sign-in carries');
+  assert.equal(ui.button(card, 'btn').disabled, false);
+  await ui.click(ui.button(card, 'btn'));
+  assert.equal(msg.textContent, 'Couldn’t reach the platform — check your connection and try again.');
+});
+
+// ── the markup, the region's rules, the kit ──────────────────────────────────
+
+test('the cards are a real list inside the Invitations section, built with createElement / textContent only', () => {
+  const section = (HUB.match(/<section id="mineInvites" hidden aria-labelledby="mineInvitesH">[\s\S]*?<\/section>/) || [''])[0];
+  assert.match(section, /<ul class="mineRows" id="invitesList"><\/ul>/);
+  assert.match(section, /<ul class="mineRows" id="engageList"><\/ul>/, 'ships as real markup the script only fills');
+  assert.doesNotMatch(CARDS, /innerHTML|insertAdjacentHTML|outerHTML/, 'no markup built from strings');
+  assert.match(SCRIPT, /if \(v === 'mine' && me\) \{ refreshList\(\); loadMemberships\(\); loadInvites\(\); \}/, 'the mine view re-reads both lists on entry, through loadInvites');
+  const COSMOS = fs.readFileSync(path.join(LANDING, 'assets', 'cosmos.css'), 'utf8');
+  assert.match(COSMOS, /\.mineRows:not\(:empty\)\+\.mineRows \.mineRow:first-child\{border-top:1px solid var\(--rule-soft\);\}/, 'one hairline between the two lists when both have rows');
+  assert.doesNotMatch(HUB.slice(0, HUB.indexOf('</head>')), /engageRow/, 'styled in cosmos.css, not in the page head');
+});
+
+test('the kit pictures the cards and the stub answers the read and the guild on the join', () => {
+  const states = JSON.parse(fs.readFileSync(path.join(LANDING, 'projects.states.json'), 'utf8')).states;
+  assert.ok(states['in-mine-engagements'] && states['in-mine-engagement-applied'], 'two kit states: the cards, and one applied');
+  const serve = fs.readFileSync(path.join(ROOT, 'modules', 'ui-design', 'kit', 'serve.js'), 'utf8');
+  assert.match(serve, /'\/me\/guild-engagements': 'me__guild-engagements'/);
+  assert.match(serve, /refuse\(res, 409, 'guild_engagement_gone'/, 'the stub refuses a guild with no engagement, as the route does');
+  const fixture = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules', 'ui-design', 'kit', 'fixtures', 'me__guild-engagements.json'), 'utf8'));
+  assert.deepEqual(fixture.engagements.map((e) => e.kind).sort(), ['apply', 'invited']);
+  for (const e of fixture.engagements) assert.deepEqual(Object.keys(e).sort(), ['created_at', 'guild', 'kind', 'project'], 'the route’s row shape, and never a client_id');
+});