@bongos/core 1.20.26 → 1.20.28

package/tests/government_charter_forms.mjs

@@ -0,0 +1,283 @@
+// tests/government_charter_forms.mjs — the genesis charter and legislation
+// stages, on the real constitution (task 1004427 / BV2.PS13, spec decision D10).
+//
+// DB-free (db monkeypatched; the apply runs against a REAL temp file). The
+// invariants:
+//
+//   1. THE REAL NAMES, EACH EXPLAINED — four forms available today (Monarchy /
+//      BDFL, Timocratic Republic, Direct Democracy, Foundation), three coming
+//      later (Presidential, Cooperative, Federation); seven variables with the
+//      government doc's names. Every one carries a short plain explanation.
+//      The names are held equal to the hall's charter library, so the genesis
+//      stage and the Constitution tab can never call a form two things.
+//   2. TWO VARIABLES ARE LIVE, ONE IS ALWAYS ON, THE REST COME LATER — franchise
+//      and pass rule are the real board block; loyalty of enforcement is always
+//      on; nothing that is not built claims to be.
+//   3. THE NAME FOLLOWS THE SETTINGS — read from what the constitution SEATS,
+//      so two spellings of one board read the same; anything else is "custom".
+//   4. APPLYING WRITES THE REAL CONSTITUTION THROUGH ITS AMENDMENT PATH — the
+//      choice becomes an ordinary amendment, validated strictly, decided under
+//      the rule in force; under monarchy the founder's yes applies it.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GOV = path.join(ROOT, 'modules', 'government');
+const charter = require(path.join(GOV, 'charter.js'));
+const board = require(path.join(GOV, 'board.js'));
+const db = require(path.join(GOV, 'db.js'));
+const config = require(path.join(GOV, 'config.js'));
+const { parseMembershipPredicate } = require(path.join(GOV, 'membership-predicate.js'));
+
+const { FORMS, VARIABLES, FRANCHISE_OPTIONS, PASS_RULE_OPTIONS, TRAJECTORIES, readCharter, buildCharterProposal } = charter;
+
+const MONARCHY = Object.freeze({
+  membership: 'rank:archon', pass_rule: 'first_ratifier', window_minutes: null, close_early_on_full_turnout: true,
+});
+
+async function withDb(stubs, fn) {
+  const originals = {};
+  for (const [k, v] of Object.entries(stubs)) { originals[k] = db[k]; db[k] = v; }
+  try { return await fn(); } finally { for (const [k, v] of Object.entries(originals)) db[k] = v; }
+}
+
+// A plain explanation: present, a sentence or two, and not merely the name again.
+function assertExplained(entry, what) {
+  assert.equal(typeof entry.explanation, 'string', `${what} carries an explanation`);
+  const sentences = entry.explanation.split(/[.!?](\s|$)/).filter((s) => s && s.trim()).length;
+  assert.ok(entry.explanation.length >= 30 && sentences >= 1 && sentences <= 3,
+    `${what}: one or two plain sentences, got "${entry.explanation}"`);
+  assert.notEqual(entry.explanation.trim().toLowerCase(), String(entry.name).toLowerCase());
+}
+
+// ── invariant 1: the real names, each explained ──────────────────────────────
+
+test('the forms carry the real academic names — four today, three coming later', () => {
+  assert.deepEqual(FORMS.filter((f) => f.available).map((f) => f.name),
+    ['Monarchy / BDFL', 'Timocratic Republic', 'Direct Democracy', 'Foundation']);
+  assert.deepEqual(FORMS.filter((f) => !f.available).map((f) => f.name),
+    ['Presidential', 'Cooperative', 'Federation']);
+  for (const f of FORMS) assertExplained(f, `form ${f.key}`);
+  assert.ok(Object.isFrozen(FORMS) && FORMS.every(Object.isFrozen));
+});
+
+test('the variables are the government doc\'s seven, each with its question and explanation', () => {
+  assert.deepEqual(VARIABLES.map((v) => v.key), [
+    'franchise', 'pass_rule', 'veto_points', 'executive_legislative', 'judicial_review',
+    'loyalty_of_enforcement', 'trajectory',
+  ]);
+  assert.deepEqual(VARIABLES.map((v) => v.name), [
+    'Franchise', 'Pass rule (winning coalition)', 'Veto points', 'Executive–legislative relationship',
+    'Judicial review', 'Loyalty of enforcement', 'Trajectory',
+  ]);
+  for (const v of VARIABLES) {
+    assertExplained(v, `variable ${v.key}`);
+    assert.ok(typeof v.question === 'string' && v.question.endsWith('?'), `${v.key} asks its question plainly`);
+  }
+  for (const o of [...FRANCHISE_OPTIONS, ...PASS_RULE_OPTIONS, ...TRAJECTORIES]) assertExplained(o, `option ${o.key}`);
+  assert.deepEqual(TRAJECTORIES.map((t) => t.name), ['Locked', 'Laddered', 'Scheduled']);
+});
+
+test('the names are the hall charter library\'s names — one form, one name, everywhere', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'government.js'), 'utf8');
+  const block = src.slice(src.indexOf('const CHARTERS = ['), src.indexOf('const TRAJECTORIES = ['));
+  const hall = [...block.matchAll(/key: '([^']+)', name: '([^']+)', selectable: (true|false)/g)]
+    .map((m) => ({ key: m[1], name: m[2], selectable: m[3] === 'true' }));
+  assert.equal(hall.length, 7, 'sanity: the hall library lists seven structures');
+  const byKey = new Map(hall.map((h) => [h.key, h]));
+  for (const f of FORMS) {
+    const h = byKey.get(f.key);
+    assert.ok(h, `the hall library knows ${f.key}`);
+    assert.equal(f.name, h.name, `${f.key} has one name`);
+    assert.equal(f.available, h.selectable, `${f.key}: available here iff selectable there`);
+  }
+  const trajectories = src.slice(src.indexOf('const TRAJECTORIES = ['), src.indexOf('const LADDER ='));
+  for (const t of TRAJECTORIES) assert.ok(trajectories.includes(`name: '${t.name}'`), `trajectory ${t.name} matches the hall`);
+});
+
+// ── invariant 2: what is live, what is always on, what comes later ───────────
+
+test('franchise and pass rule are live; loyalty of enforcement is always on; the rest come later', () => {
+  const status = Object.fromEntries(VARIABLES.map((v) => [v.key, v.status]));
+  assert.deepEqual(status, {
+    franchise: 'live', pass_rule: 'live', veto_points: 'later', executive_legislative: 'later',
+    judicial_review: 'later', loyalty_of_enforcement: 'always_on', trajectory: 'later',
+  });
+  assert.deepEqual([...PASS_RULE_OPTIONS.map((o) => o.key)].sort(), [...config.PASS_RULES].sort(),
+    'every pass rule the constitution knows is offered, and nothing else');
+  for (const o of FRANCHISE_OPTIONS.filter((x) => x.predicate)) {
+    assert.ok(parseMembershipPredicate(o.predicate), `${o.key}'s predicate parses under the REAL grammar`);
+  }
+  assert.deepEqual(parseMembershipPredicate(FRANCHISE_OPTIONS.find((o) => o.key === 'everyone').predicate).rankKeys,
+    ['xenos', 'thetes', 'metic', 'archon'], '"every builder" really seats every rank (the + is load-bearing)');
+  // The band's pass-rule words (task 1004429) are these options' explanations —
+  // one sentence per rule, written once.
+  for (const o of PASS_RULE_OPTIONS) assert.equal(board.PASS_RULE_WORDS[o.key], o.explanation);
+});
+
+// ── invariant 3: the name follows the settings ───────────────────────────────
+
+test('the shipped default reads as Monarchy / BDFL, and each available form reads as itself', () => {
+  assert.equal(readCharter(config.BOARD_DEFAULTS).form, 'monarchy');
+  for (const f of FORMS.filter((x) => x.available)) {
+    const built = buildCharterProposal(MONARCHY, { form: f.key, councilRank: 'trustees' });
+    assert.equal(built.ok, true, f.key);
+    assert.equal(readCharter(built.proposal).form, f.key, `choosing ${f.key} makes the constitution read as ${f.key}`);
+  }
+});
+
+test('the name reads what the board SEATS, so two spellings of one board read the same', () => {
+  const tim = { ...MONARCHY, pass_rule: 'consent' };
+  assert.equal(readCharter({ ...tim, membership: 'rank:metic+' }).form, 'timocratic-republic');
+  assert.equal(readCharter({ ...tim, membership: 'rank:metic,archon' }).form, 'timocratic-republic');
+  assert.equal(readCharter({ ...tim, membership: 'rank:xenos+' }).form, 'direct-democracy');
+  assert.equal(readCharter({ ...tim, membership: 'rank:trustees' }).form, 'foundation');
+});
+
+test('any other combination reads "custom" — never the nearest name', () => {
+  const custom = [
+    { ...MONARCHY, pass_rule: 'consent' },                          // Archons by consent
+    { ...MONARCHY, membership: 'rank:xenos+', pass_rule: 'majority' },
+    { ...MONARCHY, membership: 'rank:metic' },                       // exactly metic, no Archons
+    { ...MONARCHY, membership: 'rank:metic+', pass_rule: 'first_ratifier' },
+    { ...MONARCHY, membership: 'not a predicate' },
+  ];
+  for (const b of custom) {
+    const r = readCharter(b);
+    assert.equal(r.form, 'custom', JSON.stringify(b));
+    assert.equal(r.name, 'Custom');
+    assertExplained(r, 'the custom reading');
+  }
+  const r = readCharter({ ...MONARCHY, membership: 'rank:xenos+', pass_rule: 'majority' });
+  assert.equal(r.franchise, 'everyone', 'the settings are still read individually');
+  assert.equal(r.pass_rule, 'majority');
+});
+
+// ── invariant 4: applying writes the real constitution via an amendment ──────
+
+test('a charter choice builds a whole, strictly-valid constitution that keeps the fields it does not set', () => {
+  const live = { ...MONARCHY, window_minutes: 90, close_early_on_full_turnout: false };
+  const out = buildCharterProposal(live, { form: 'direct-democracy' });
+  assert.equal(out.ok, true);
+  assert.deepEqual(out.proposal, {
+    membership: 'rank:xenos+', pass_rule: 'consent', window_minutes: 90, close_early_on_full_turnout: false,
+  }, 'the clock and turnout rules are not the charter\'s to change — they are kept');
+  assert.equal(board.validateProposedConstitution(out.proposal).ok, true);
+  // Legislation fine-tunes on top of a form.
+  const tuned = buildCharterProposal(live, { form: 'direct-democracy', passRule: 'majority', windowMinutes: 1440 });
+  assert.deepEqual([tuned.proposal.pass_rule, tuned.proposal.window_minutes], ['majority', 1440]);
+  assert.equal(readCharter(tuned.proposal).form, 'custom');
+});
+
+test('choices that are not real are refused by name, before anything is filed', () => {
+  const cases = [
+    [{ form: 'presidential' }, 'form_not_available'],
+    [{ form: 'anarchy' }, 'unknown_form'],
+    [{ franchise: 'the loudest' }, 'unknown_franchise'],
+    [{ franchise: 'council' }, 'council_needs_a_rank'],
+    [{ franchise: 'council', councilRank: 'metic' }, 'council_needs_a_custom_rank'],
+    [{ franchise: 'council', councilRank: 'Not A Key' }, 'council_needs_a_custom_rank'],
+    [{ passRule: 'acclamation' }, 'unknown_pass_rule'],
+    [{}, 'nothing_chosen'],
+  ];
+  for (const [choice, reason] of cases) {
+    const out = buildCharterProposal(MONARCHY, choice);
+    assert.equal(out.ok, false, JSON.stringify(choice));
+    assert.equal(out.reason, reason, JSON.stringify(choice));
+  }
+});
+
+test('the founder picks Direct Democracy and ratifies it: the amendment path writes the real constitution', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gov-charter-'));
+  const target = path.join(dir, 'government.json');
+  const originalApply = config.applyBoardAmendment;
+  const applied = [];
+  config.applyBoardAmendment = (proposed) => { applied.push(proposed); fs.writeFileSync(target, JSON.stringify({ board: proposed })); return proposed; };
+  let filed = null;
+  const votes = [];
+  try {
+    await withDb({
+      builderHoldsRankActive: async () => true, // the founder keeps their seat either way
+      createAmendment: async (args) => { filed = args; return { id: '5', proposed: args.proposed, proposed_by: args.proposedBy }; },
+      openBoardItem: async (args) => ({ id: '21', subject_type: args.subjectType, subject_id: '5', opened_by: args.openedBy, constitution: args.constitution, closes_at: null, closed_at: null }),
+      getBoardItemForVote: async () => ({ id: '21', subject_type: 'constitutional_amendment', subject_id: '5', opened_by: '42', constitution: MONARCHY, closed_at: null, expired: false }),
+      insertBoardVote: async (row) => { const v = { voter_id: row.voterId, direction: row.direction }; votes.push(v); return v; },
+      insertVoteKarma: async () => {},
+      getVotesForItem: async () => votes,
+      getActiveBuildersWithRank: async () => [{ builder_id: '42', github_login: 'founder', display_name: 'Founder' }],
+      getBoardItemAuthor: async () => '42',
+      closeBoardItem: async ({ outcome }) => ({ id: '21', subject_type: 'constitutional_amendment', subject_id: '5', opened_by: '42', closed_at: 'T', outcome }),
+      insertAuthorRatifyKarma: async () => true,
+      getAmendment: async () => ({ id: '5', proposed: filed.proposed }),
+    }, async () => {
+      const out = await board.proposeCharter({ form: 'direct-democracy', proposedBy: '42' });
+      assert.equal(out.ok, true);
+      assert.equal(out.reads_as.form, 'direct-democracy');
+      assert.equal(filed.proposed.membership, 'rank:xenos+');
+      assert.match(filed.rationaleMd, /Direct Democracy/, 'the record says in words what was chosen');
+      assert.equal(out.item.constitution.pass_rule, config.loadGovernmentConfig().board.pass_rule,
+        'decided under the constitution IN FORCE, not the one proposed');
+      await board.castVote({ itemId: '21', voterId: '42', direction: 'yes' });
+      const closed = await board.maybeCloseAfterVote('21');
+      assert.equal(closed.outcome, 'passed');
+    });
+    assert.deepEqual(applied, [filed.proposed], 'the ratified text is exactly what was filed');
+    assert.equal(JSON.parse(fs.readFileSync(target, 'utf8')).board.membership, 'rank:xenos+');
+  } finally {
+    config.applyBoardAmendment = originalApply;
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('a charter that changes nothing files nothing, and a council must be a rank that exists', async () => {
+  // This checkout runs the neutral monarchy (a guard test pins the vanilla state).
+  assert.equal(readCharter(config.loadGovernmentConfig().board).form, 'monarchy');
+  await withDb({
+    createAmendment: async () => { throw new Error('must not be reached'); },
+    getRankByKey: async (key) => (key === 'trustees' ? { rank_key: 'trustees' } : null),
+    builderHoldsRankActive: async () => true,
+  }, async () => {
+    assert.equal((await board.proposeCharter({ form: 'monarchy', proposedBy: '42' })).reason, 'no_change',
+      'a sitting on the constitution already in force would decide nothing');
+    assert.equal((await board.proposeCharter({ form: 'foundation', councilRank: 'ghosts', proposedBy: '42' })).reason, 'unknown_council_rank');
+    assert.equal((await board.proposeCharter({ form: 'direct-democracy', proposedBy: null })).reason, 'missing_proposer');
+  });
+});
+
+// ── the surfaces ─────────────────────────────────────────────────────────────
+
+test('the constitution view carries the charter: forms, variables, and what the rule in force reads as', async () => {
+  await withDb({ listAmendmentHistory: async () => [], countActiveBuilders: async () => 1 }, async () => {
+    const view = await board.constitutionView();
+    assert.equal(view.charter.forms.length, FORMS.length);
+    assert.equal(view.charter.variables.length, VARIABLES.length);
+    assert.deepEqual(view.charter.reads_as, readCharter(view.board));
+  });
+  const routes = fs.readFileSync(path.join(GOV, 'routes', 'government.js'), 'utf8');
+  assert.match(routes, /router\.post\('\/government\/board\/charter', api\.requireBuilder, api\.requirePermission\('board\.item\.open'\)/);
+  assert.match(routes, /proposeCharter: board\.proposeCharter/);
+  const pins = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'), 'utf8');
+  assert.match(pins, /'POST \/government\/board\/charter': 'perm:board\.item\.open'/);
+});
+
+test('the Constitution tab names the form of government in force', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'government.js'), 'utf8');
+  const start = src.indexOf('function formOfGovernmentSentence');
+  assert.ok(start > 0, 'the tab has a form-of-government line');
+  const fnSrc = src.slice(start, src.indexOf('\n  }\n', start) + 4);
+  const ctx = { escapeHtml: (s) => String(s) };
+  vm.createContext(ctx);
+  vm.runInContext(`${fnSrc}; this.f = formOfGovernmentSentence;`, ctx);
+  const monarchy = readCharter(MONARCHY);
+  assert.match(ctx.f({ reads_as: monarchy }), /Monarchy \/ BDFL/);
+  assert.match(ctx.f({ reads_as: monarchy }), new RegExp(monarchy.explanation.slice(0, 20).replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')));
+  assert.match(ctx.f({ reads_as: readCharter({ ...MONARCHY, pass_rule: 'consent' }) }), /Custom/);
+  assert.equal(ctx.f({}), 'Not available from this server yet.', 'an older server without the charter block is said plainly');
+});

package/tests/hub_invite_notices.mjs

@@ -107,8 +107,11 @@ test('notify seeds a PENDING row on the calling project, and cannot touch a real
   const w = writes();
   assert.equal(w.length, 1);
   assert.match(w[0].sql, /VALUES \(\$1, \$2, 'pending'\)/, 'a notice is a pending row, never a membership');
-  assert.match(w[0].sql, /ON CONFLICT \(client_id, github_id\) DO NOTHING/, 'a current member is left exactly as they are');
-  assert.deepEqual(w[0].params, ['mercury', '4242'], 'keyed on the authenticated client and the account the LOGIN resolves to');
+  // The conflict branch restamps ONLY joined_at, and only on a pending row past its 30
+  // days (a re-invite, task 1002969): a current member is left exactly as they are.
+  assert.match(w[0].sql, /ON CONFLICT \(client_id, github_id\) DO UPDATE SET joined_at = now\(\)\s+WHERE m\.membership_kind = 'pending' AND m\.joined_at <= now\(\) - make_interval\(days => \$3\)/,
+    'a current member is left exactly as they are');
+  assert.deepEqual(w[0].params, ['mercury', '4242', 30], 'keyed on the authenticated client and the account the LOGIN resolves to');
 });
 
 test('clear drops ONLY a pending row on the calling project', async () => {

package/tests/invite_expiry.mjs

@@ -0,0 +1,37 @@
+// tests/invite_expiry.mjs — task 1002969 (privacy spec D4, ADR 0356). DB-free.
+//
+// The one definition of when a recruit invite's door closes. The behaviour is proved
+// in tests/application_lifecycle.mjs (interpreted) and tests/invite_expiry_db.mjs
+// (real Postgres); this pins the definition itself: the owner-signed window, that
+// only an invite can expire, that "live" is exactly "not expired", and that a table
+// alias can never carry SQL into the statements that interpolate it.
+//
+// Run:  node --test tests/invite_expiry.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const expiry = require('../src/bongos/invite-expiry.js');
+const api = require('../src/module-api.js');
+
+test('the window is the owner-signed 30 days, and the doorway serves this same module', () => {
+  assert.equal(expiry.INVITE_EXPIRY_DAYS, 30);
+  for (const k of ['INVITE_EXPIRY_DAYS', 'inviteExpiredSql', 'inviteLiveSql', 'inviteExpiresAtSql']) {
+    assert.equal(api.inviteExpiry[k], expiry[k], `${k}: modules read the definition core reads, not a copy`);
+  }
+});
+
+test('only an invite expires, and live is exactly not-expired', () => {
+  assert.equal(expiry.inviteExpiredSql(), "(kind = 'invite' AND created_at <= now() - interval '30 days')");
+  assert.equal(expiry.inviteLiveSql('ar'), `NOT ${expiry.inviteExpiredSql('ar')}`);
+  assert.match(expiry.inviteExpiresAtSql('ar'), /^\(CASE WHEN ar\.kind = 'invite' THEN ar\.created_at \+ interval '30 days' END\)$/,
+    'an application has no closing day');
+});
+
+test('an alias is an identifier or nothing', () => {
+  assert.match(expiry.inviteLiveSql('x'), /x\.kind = 'invite' AND x\.created_at/);
+  for (const bad of ['ar;', "a'", 'a b', 'A', '1a', 'a.b']) {
+    assert.throws(() => expiry.inviteExpiredSql(bad), /bad table alias/, JSON.stringify(bad));
+  }
+});

package/tests/invite_expiry_db.mjs

@@ -0,0 +1,196 @@
+// tests/invite_expiry_db.mjs — task 1002969 (privacy spec D4, ADR 0356). Real DB.
+//
+// A recruit invite's door closes 30 days after it is sent, computed at read time.
+// tests/application_lifecycle.mjs pins the behaviour over an interpreter that reads
+// each statement's WHERE; this file runs the SAME statements on Postgres, because an
+// interpreter cannot tell you that Postgres would reject a statement, or what
+// `now() - interval '30 days'` does at the boundary. Two halves:
+//
+//   the instance — the real onboarding router and the real db-kernel admission reads,
+//                  over access_requests built from its real migrations;
+//   the hub      — inviteToProject and listPendingInvitesForAccount over the real
+//                  memberships table: an expired notice is hidden, a re-invite
+//                  restamps it, and a member's row is never touched.
+//
+// Each half builds its tables in a throwaway schema, so a shared database's rows are
+// never seen or changed.
+//
+// Real-DB integration test: self-skips without a reachable Postgres; in the
+// INTEGRATION set (scripts/gds/run-unit-tests.js) so the default DB-free lane
+// never runs it.
+//
+// Run:  DATABASE_URL=... node tests/invite_expiry_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';
+import http from 'node:http';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+const express = require('express');
+
+const here = dirname(fileURLToPath(import.meta.url));
+const coreSql = (f) => readFileSync(join(here, '..', 'migrations', `${f}.sql`), 'utf8');
+const piSql = (f) => readFileSync(join(here, '..', 'modules', 'platform-identity', 'migrations', `platform_identity_${f}.sql`), 'utf8');
+
+const pgPool = new Pool({ connectionString: process.env.DATABASE_URL || undefined, max: 1 });
+let client;
+try {
+  client = await pgPool.connect();
+} catch (e) {
+  console.log(`invite_expiry_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pgPool.end().catch(() => {});
+  process.exit(0);
+}
+
+const q = (sql, params) => client.query(sql, params);
+const SCHEMA = `t1002969_${process.pid}`;
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); pass++; console.log(`  ok - ${msg}`); };
+
+// Core's admission reads go through ./pool, and the router through the doorway's
+// pool: both are pointed at this one connection, whose search_path is the schema.
+const poolPath = require.resolve('../src/bongos/pool.js');
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: client } };
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+let notices = [];
+require.cache[apiPath].exports = {
+  ...realApi,
+  pool: client,
+  projectJoinDoor: () => 'apply',
+  logger: () => ({ error() {}, warn() {}, info() {}, debug() {} }),
+  requireBuilder: (req, _res, next) => { req.builder = { id: 42, github_login: 'owner' }; next(); },
+  requirePermission: () => (_req, _res, next) => next(),
+  readApplicationVouch: () => null,
+  notifyHubOfInvite: (login, opts) => { notices.push({ login, invited: opts && opts.invited }); },
+};
+const broadcastPath = require.resolve('../modules/onboarding/approval-broadcast.js');
+require.cache[broadcastPath] = { id: broadcastPath, filename: broadcastPath, loaded: true, exports: { postMemberApprovalRequest: async () => ({}) } };
+
+const dbKernel = require('../src/bongos/db-kernel.js');
+const buildAccessRequestsRouter = require('../modules/onboarding/routes/access-requests.js');
+const pi = require('../modules/platform-identity/platform-identity.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/gds', buildAccessRequestsRouter());
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const port = server.address().port;
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : Buffer.from(JSON.stringify(body));
+    const req = http.request({ host: '127.0.0.1', port, method, path,
+      headers: payload ? { 'content-type': 'application/json', 'content-length': payload.length } : {} }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => resolve({ status: res.statusCode, json: JSON.parse(Buffer.concat(chunks).toString('utf8') || 'null') }));
+    });
+    req.on('error', reject);
+    req.end(payload);
+  });
+}
+
+// Backdate one login's rows by `days` (an invite's resolved_at is its created_at).
+const age = (login, days) => q(
+  `UPDATE access_requests SET created_at = now() - make_interval(days => $2),
+          resolved_at = CASE WHEN kind = 'invite' THEN now() - make_interval(days => $2) ELSE resolved_at END
+    WHERE github_login = $1`, [login, days]);
+
+try {
+  await q(`CREATE SCHEMA ${SCHEMA}`);
+  await q(`SET search_path TO ${SCHEMA}`);
+  await q('CREATE TABLE schema_migrations (version text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())');
+  await q('CREATE TABLE builders (id bigserial PRIMARY KEY, github_login text NOT NULL)');
+  await q(`INSERT INTO builders (id, github_login) VALUES (42, 'owner')`);
+  for (const f of ['060_access_requests', 'core_230_access_requests_applicant_vouch',
+    'core_254_access_requests_applicant_handle', 'core_255_access_requests_invite_kind',
+    'core_266_access_requests_invited_login_idx']) await q(coreSql(f));
+
+  // ── The instance: the door, the queues, the probe ────────────────────────
+  console.log('the instance:');
+  for (const login of ['eve', 'fay']) assert.equal((await call('POST', '/api/gds/access-requests/invite', { github_login: login })).status, 201);
+  await q(`INSERT INTO access_requests (github_login, status, resolved_at, created_at) VALUES ('cy', 'invited', now(), now() - interval '60 days')`);
+  await age('eve', 29);
+  await age('fay', 31);
+  ok(await dbKernel.hasInvitedAccessRequest('eve') === true, 'day 29: the invite still admits');
+  ok(await dbKernel.hasInvitedAccessRequest('fay') === false, 'day 31: the sign-in gate refuses it');
+  ok(await dbKernel.hasInvitedAccessRequest('cy') === true, 'an application approved 60 days ago is not an invite and still admits');
+  ok((await dbKernel.accessStateByLogin('fay')).invited === false, 'the waiting page agrees with the gate');
+
+  // core_266: the gate's own statement, captured as it runs, can use the invited-login
+  // index. Seq scans are switched off only so a tiny table still shows the plan.
+  const seen = [];
+  const realQuery = client.query.bind(client);
+  client.query = (text, params) => { seen.push({ text, params }); return realQuery(text, params); };
+  await dbKernel.hasInvitedAccessRequest('eve');
+  client.query = realQuery;
+  await q('SET enable_seqscan = off');
+  const plan = (await q(`EXPLAIN ${seen[0].text}`, seen[0].params)).rows.map((r) => r['QUERY PLAN']).join('\n');
+  await q('RESET enable_seqscan');
+  ok(/idx_access_requests_invited_login/.test(plan), 'the sign-in gate can read invited rows through core_266\'s index');
+
+  const hist = Object.fromEntries((await call('GET', '/api/gds/access-requests?status=invited')).json.requests.map((r) => [r.github_login, r]));
+  ok(hist.fay.expired === true && hist.eve.expired === false && hist.cy.expired === false, 'the queue marks only the expired invite');
+  ok(hist.cy.expires_at === null && new Date(hist.fay.expires_at) <= new Date() && new Date(hist.eve.expires_at) > new Date(),
+    'and says when each invite closes; an application has no such day');
+
+  const probe = (await call('GET', '/api/gds/access-requests/status?github_login=fay')).json;
+  ok(probe.status === 'expired' && probe.admitted === false, 'the status probe reports expired, not invited');
+
+  notices = [];
+  const again = await call('POST', '/api/gds/access-requests/invite', { github_login: 'fay' });
+  ok(again.status === 201 && await dbKernel.hasInvitedAccessRequest('fay') === true, 're-inviting an expired login opens a fresh door');
+  ok(notices.length === 1 && notices[0].invited === true, 'and tells the hub');
+  const out = (await call('GET', '/api/gds/access-requests/invites')).json.invites;
+  ok(out.filter((r) => r.github_login === 'fay').length === 1 && out.find((r) => r.github_login === 'fay').expired === false,
+    'the outstanding list shows the live invite in place of the expired one');
+  const mine = (await call('GET', '/api/gds/access-requests/invites?mine=1')).json.invites;
+  ok(mine.filter((r) => r.github_login === 'fay').length === 1, 'and so does the sender\'s own list (?mine=1)');
+
+  notices = [];
+  await call('PATCH', `/api/gds/access-requests/${again.json.request.id}`, { status: 'dismissed' });
+  ok(notices.length === 1 && notices[0].invited === false, 'rescinding the live invite clears the hub notice; the expired row does not stand');
+
+  // ── The hub: the notice follows the door ──────────────────────────────────
+  console.log('the hub:');
+  for (const f of ['001_tables', '003_project_memberships', '010_membership_kind', '021_drop_legacy_role']) await q(piSql(f));
+  const joined = async (id) => (await q(
+    `SELECT membership_kind, joined_at FROM platform_identity_project_memberships WHERE client_id = 'demo' AND github_id = $1`, [id])).rows[0];
+  const backdate = (id, days) => q(
+    `UPDATE platform_identity_project_memberships SET joined_at = now() - make_interval(days => $2) WHERE client_id = 'demo' AND github_id = $1`, [id, days]);
+
+  ok((await pi.inviteToProject({ clientId: 'demo', githubId: 1 }, { pool: client })).invited === true, 'a first invite writes a notice');
+  await backdate(1, 10);
+  const before = (await joined(1)).joined_at;
+  ok((await pi.inviteToProject({ clientId: 'demo', githubId: 1 }, { pool: client })).invited === false
+    && (await joined(1)).joined_at.getTime() === before.getTime(), 'a re-send while the invite is live leaves the notice as it was');
+
+  await pi.inviteToProject({ clientId: 'demo', githubId: 2 }, { pool: client });
+  await backdate(2, 31);
+  const listed = async (id) => (await pi.listPendingInvitesForAccount(id, { pool: client })).length;
+  ok(await listed(1) === 1, 'a 10-day-old notice is listed');
+  ok(await listed(2) === 0, 'a 31-day-old notice is not: its door no longer opens');
+  ok((await pi.inviteToProject({ clientId: 'demo', githubId: 2 }, { pool: client })).invited === true && await listed(2) === 1,
+    'a re-invite after the 30 days restamps the notice, so it shows again');
+
+  await q(`INSERT INTO platform_identity_project_memberships (client_id, github_id, membership_kind, joined_at)
+           VALUES ('demo', 3, 'member', now() - interval '400 days')`);
+  const member = await joined(3);
+  ok((await pi.inviteToProject({ clientId: 'demo', githubId: 3 }, { pool: client })).invited === false, 'inviting a member writes nothing');
+  const after = await joined(3);
+  ok(after.membership_kind === 'member' && after.joined_at.getTime() === member.joined_at.getTime(),
+    'and their row is untouched, however old it is');
+
+  console.log(`\ninvite_expiry_db.mjs: ${pass} passed`);
+} finally {
+  await new Promise((r) => server.close(r));
+  await q(`DROP SCHEMA IF EXISTS ${SCHEMA} CASCADE`).catch(() => {});
+  client.release();
+  await pgPool.end().catch(() => {});
+}

package/tests/module_api.mjs

@@ -49,6 +49,7 @@ const PUBLISHED_SURFACE = [
   'artistGate', // added by task 1003575 (ADR 0241): the artist gate — off | advisory | strict, plus the pure verdict helpers over it. Two modules ask it two different questions ("file this review?" and "does an open one hold the deploy?") and both must resolve the knob through this one reader, never branding().project
   'readApplicantProfileFromHub', // added by task 1002972 (privacy spec D7): the reviewer queue's LIVE per-render read of one applicant's hub profile view. NARROW by design — the underlying call is authenticated with this instance's hub client secret, and loadIdpConfig stays OFF the doorway so no module ever holds the credential that speaks for the whole project
   'notifyHubOfInvite', // added by task 1002818 (ADR 0353): tell the hub about one of THIS project's invites (or its rescind) so the invitee sees it in My Projects. The same NARROW-port reason as readApplicantProfileFromHub: the call carries this instance's hub client secret, so a module passes one login and one direction and can neither widen nor re-address it
+  'inviteExpiry', // added by task 1002969 (ADR 0356): the ONE read-time definition of when a recruit invite's door closes. The sign-in gate reads it in core; the onboarding queues and the hub's notice list are modules, so without the doorway each would restate the 30 days and the predicate, and two copies can close a door on different days
   'readApplicationVouch', // added by task 1002285 (ADR 0201 D2): the public access-request write's check of the hub's application vouch. NARROW for the same reason — core supplies the hub key and this instance's client_id, so a module passes a token and a login and can neither swap the key nor re-address the audience
   'enabledDisciplines', // BV1.R81: instance offered-disciplines (1.9.0; onboarding restock backstop)
   'isModuleEnabled', // task 1003881: is ANOTHER module present? onboarding's Discord approve/decline control is only actionable when the `discord` module's reaction handler is loaded, so the posting half has to be able to ask