@bongos/core 1.20.26 → 1.20.28

package/modules/government/charter.js

@@ -0,0 +1,232 @@
+'use strict';
+
+// modules/government/charter.js — the genesis charter and legislation stages'
+// vocabulary, on the REAL constitution (task 1004427 / BV2.PS13, spec decision
+// D10 in docs/specs/bongos-v2-project-startup.md).
+//
+// REAL NAMES, EACH EXPLAINED PLAINLY. Real-world governments are the model for
+// a project's structure, so every form and every setting is called what it
+// actually is — Monarchy / BDFL, Timocratic Republic, franchise, judicial
+// review — and carries a one- or two-sentence explanation of how it works in a
+// project. The explanation is simpler than the academic definition and never a
+// replacement for the name.
+//
+// ONLY WHAT IS BUILT CLAIMS TO BE. Two variables are the live board block:
+// franchise (`membership`) and pass rule (`pass_rule`). Loyalty of enforcement
+// is always on — authority is resolved from the rank you hold, per request and
+// uncached (ADR 0016), so nobody keeps a rank's powers after leaving it. The
+// other four are shown as coming later, and so are the three forms that need
+// machinery this system does not have (elections, member shares, federated
+// chambers).
+//
+// THE NAME FOLLOWS THE SETTINGS. `readCharter` reads what a constitution SEATS
+// (through the real membership parser) and its pass rule, and names the form
+// those make — or "Custom" when they make none. It reads the seated set, not
+// the spelling, so `rank:metic+` and `rank:metic,archon` read the same.
+//
+// APPLYING IS AN AMENDMENT. `buildCharterProposal` only BUILDS a whole
+// constitution from a choice; board.js `proposeCharter` files it through the
+// ordinary amendment path, so the choice is validated strictly and decided
+// under the constitution in force (under monarchy, the founder's one yes
+// applies it). There is no second write path to the constitution.
+//
+// Pure and DB-free: it requires only the catalog's ladder and the membership
+// grammar, so a test (or a boot-time caller) can use it without a database.
+//
+// The form names are held equal to the hall's charter library
+// (modules/hall-ui/public/government.js CHARTERS) by
+// tests/government_charter_forms.mjs — browser code cannot require this file,
+// and one form must never go by two names.
+
+const { RANK_ORDER } = require('./catalog');
+const { parseMembershipPredicate } = require('./membership-predicate');
+
+const freezeAll = (list) => Object.freeze(list.map((x) => Object.freeze({ ...x })));
+
+// ── franchise: who gets a vote ───────────────────────────────────────────────
+// `predicate` is the exact membership string written to the constitution, and
+// `seats` is what it must resolve to. `council` names a custom rank the owner
+// chooses, so its predicate is built from that choice.
+const FRANCHISE_OPTIONS = freezeAll([
+  { key: 'founder', name: 'The founder', predicate: 'rank:archon', seats: ['archon'],
+    explanation: 'Only the founder votes (the Archon rank). Right for a solo start, when there is nobody else to ask.' },
+  { key: 'trusted', name: 'Trusted builders and up', predicate: 'rank:metic+', seats: ['metic', 'archon'],
+    explanation: 'Builders who have earned the trusted rank by shipping get a vote, along with the founder.' },
+  { key: 'everyone', name: 'Every builder', predicate: 'rank:xenos+', seats: [...RANK_ORDER],
+    explanation: 'Everyone on the project gets a vote, from the newest builder to the founder.' },
+  { key: 'council', name: 'A council you name', predicate: null, seats: null,
+    explanation: 'Only the members of a council rank you create get a vote. You choose who sits on it.' },
+]);
+
+// ── pass rule (winning coalition): how many must agree ───────────────────────
+// Exactly the four rules config.js PASS_RULES knows (held equal by test).
+const PASS_RULE_OPTIONS = freezeAll([
+  { key: 'first_ratifier', name: 'One yes is enough',
+    explanation: 'One yes from any member decides it.' },
+  { key: 'consent', name: 'Passes unless someone objects',
+    explanation: 'It passes unless a member objects, once everyone has voted or the clock runs out.' },
+  { key: 'majority', name: 'More than half',
+    explanation: 'More than half of all members must say yes.' },
+  { key: 'unanimous', name: 'Everyone who votes agrees',
+    explanation: 'Everyone who votes must agree, and at least one member must say yes.' },
+]);
+
+// ── trajectory: how the government changes as the project grows ─────────────
+const TRAJECTORIES = freezeAll([
+  { key: 'locked', name: 'Locked',
+    explanation: 'The government stays as founded until the project votes to change it.' },
+  { key: 'laddered', name: 'Laddered',
+    explanation: 'The government steps up automatically as the team crosses each size threshold.' },
+  { key: 'scheduled', name: 'Scheduled',
+    explanation: 'The government changes on dates the project commits to in advance.' },
+]);
+
+// ── the government doc's seven variables ─────────────────────────────────────
+// status: 'live' (a real setting of the constitution today) | 'always_on' |
+// 'later' (shown, explained, and not yet settable).
+const VARIABLES = freezeAll([
+  { key: 'franchise', name: 'Franchise', question: 'Who gets a vote?', status: 'live',
+    explanation: 'Who sits on the board and votes on the project\'s decisions.' },
+  { key: 'pass_rule', name: 'Pass rule (winning coalition)', question: 'How many must agree?', status: 'live',
+    explanation: 'How much agreement a decision needs before it passes.' },
+  { key: 'veto_points', name: 'Veto points', question: 'How many checkpoints must a big change pass?', status: 'later',
+    explanation: 'How many separate approvals a big change must collect before it happens.' },
+  { key: 'executive_legislative', name: 'Executive–legislative relationship',
+    question: 'Does the leader serve at the team\'s confidence?', status: 'later',
+    explanation: 'Whether the team can replace its leader by vote, or the leader holds office for a set term.' },
+  { key: 'judicial_review', name: 'Judicial review', question: 'Who can void a decision that breaks the charter?', status: 'later',
+    explanation: 'Who may cancel a decision that goes against the project\'s charter.' },
+  { key: 'loyalty_of_enforcement', name: 'Loyalty of enforcement',
+    question: 'Does power belong to the office or the person?', status: 'always_on',
+    explanation: 'Whoever holds a rank holds its powers, and nobody keeps them after leaving it.' },
+  { key: 'trajectory', name: 'Trajectory', question: 'How does the government change as you grow?', status: 'later',
+    explanation: 'Whether the government stays put, grows with the team, or changes on a schedule.' },
+]);
+
+// ── the forms ────────────────────────────────────────────────────────────────
+// An available form is a franchise + a pass rule; choosing it sets exactly
+// those two. `key` matches the hall charter library's key.
+const FORMS = freezeAll([
+  { key: 'monarchy', name: 'Monarchy / BDFL', available: true, franchise: 'founder', pass_rule: 'first_ratifier',
+    explanation: 'One leader decides. In a project the founder makes the calls, which is fast, clear and honest for a solo start.' },
+  { key: 'timocratic-republic', name: 'Timocratic Republic', available: true, franchise: 'trusted', pass_rule: 'consent',
+    explanation: 'A say is earned, not given. Builders who have reached the trusted rank decide together.' },
+  { key: 'direct-democracy', name: 'Direct Democracy', available: true, franchise: 'everyone', pass_rule: 'consent',
+    explanation: 'Every builder votes directly. A decision passes unless someone objects with a reason.' },
+  { key: 'foundation', name: 'Foundation', available: true, franchise: 'council', pass_rule: 'consent',
+    explanation: 'A written charter looked after by a small council of trustees you appoint.' },
+  { key: 'presidential', name: 'Presidential', available: false,
+    explanation: 'The team elects a leader for a fixed term. Coming later, because it needs elections.' },
+  { key: 'cooperative', name: 'Cooperative', available: false,
+    explanation: 'Every member holds a share and gets one vote. Coming later, because it needs member shares.' },
+  { key: 'federation', name: 'Federation', available: false,
+    explanation: 'Self-governing teams coordinate under one shared pact. Coming later, for projects with many teams.' },
+]);
+
+const CUSTOM_EXPLANATION = 'These settings match no named form of government. They are still the real rules the board runs under.';
+
+const byKey = (list, key) => list.find((x) => x.key === key) || null;
+const sameSet = (a, b) => a.length === b.length && a.every((k) => b.includes(k));
+
+// Is this a single CUSTOM rank (a council)? A custom rank is a DB row this file
+// cannot see, so "not on the standard ladder" is the whole test here; whether
+// it exists is board.js's check against the live rows.
+const isCustomRankKey = (key) => typeof key === 'string' && !RANK_ORDER.includes(key);
+
+// Which franchise option does a membership predicate SEAT? Read through the
+// real parser, so an equivalent spelling reads the same and an unparseable one
+// reads as custom rather than as a guess.
+function franchiseOf(membership) {
+  const parsed = parseMembershipPredicate(membership);
+  if (!parsed) return 'custom';
+  const seats = [...parsed.rankKeys];
+  for (const o of FRANCHISE_OPTIONS) if (o.seats && sameSet(o.seats, seats)) return o.key;
+  if (seats.length === 1 && isCustomRankKey(seats[0])) return 'council';
+  return 'custom';
+}
+
+// The name follows the settings: which form does this board block make?
+function readCharter(board) {
+  const b = board || {};
+  const franchise = franchiseOf(b.membership);
+  const passRule = byKey(PASS_RULE_OPTIONS, b.pass_rule) ? b.pass_rule : 'custom';
+  const form = FORMS.find((f) => f.available && f.franchise === franchise && f.pass_rule === passRule);
+  return Object.freeze(form
+    ? { form: form.key, name: form.name, explanation: form.explanation, franchise, pass_rule: passRule }
+    : { form: 'custom', name: 'Custom', explanation: CUSTOM_EXPLANATION, franchise, pass_rule: passRule });
+}
+
+// Build the WHOLE constitution a charter choice makes, on top of the live one.
+// A choice is a form, a franchise, a pass rule, a window, or a form fine-tuned by
+// the others (the legislation stage tunes what the charter stage picked). The
+// fields a charter does not speak to — the clock and the full-turnout early
+// close — are KEPT from the live constitution unless a window is named, because
+// a constitution is ratified whole and the choice must not quietly change them.
+// Returns { ok: true, proposal } or { ok: false, reason }; the caller validates
+// the result strictly and files it as an amendment.
+function buildCharterProposal(liveBoard, { form, franchise, councilRank, passRule, windowMinutes } = {}) {
+  const live = liveBoard || {};
+  let franchiseKey = franchise;
+  let rule = passRule;
+  if (form !== undefined && form !== null) {
+    const f = byKey(FORMS, form);
+    if (!f) return { ok: false, reason: 'unknown_form' };
+    if (!f.available) return { ok: false, reason: 'form_not_available' };
+    if (franchiseKey == null) franchiseKey = f.franchise;
+    if (rule == null) rule = f.pass_rule;
+  }
+  if (franchiseKey == null && rule == null && windowMinutes === undefined) return { ok: false, reason: 'nothing_chosen' };
+
+  let membership = live.membership;
+  if (franchiseKey != null) {
+    const option = byKey(FRANCHISE_OPTIONS, franchiseKey);
+    if (!option) return { ok: false, reason: 'unknown_franchise' };
+    if (option.key === 'council') {
+      if (councilRank == null || councilRank === '') return { ok: false, reason: 'council_needs_a_rank' };
+      const predicate = `rank:${councilRank}`;
+      const parsed = parseMembershipPredicate(predicate);
+      if (!parsed || parsed.rankKeys.length !== 1 || !isCustomRankKey(parsed.rankKeys[0])) {
+        return { ok: false, reason: 'council_needs_a_custom_rank' };
+      }
+      membership = predicate;
+    } else {
+      membership = option.predicate;
+    }
+  }
+  if (rule != null && !byKey(PASS_RULE_OPTIONS, rule)) return { ok: false, reason: 'unknown_pass_rule' };
+
+  return {
+    ok: true,
+    proposal: {
+      membership,
+      pass_rule: rule != null ? rule : live.pass_rule,
+      window_minutes: windowMinutes !== undefined ? windowMinutes : (live.window_minutes ?? null),
+      close_early_on_full_turnout: live.close_early_on_full_turnout,
+    },
+  };
+}
+
+// The whole vocabulary plus what the constitution in force reads as — the
+// payload the genesis charter and legislation stages render from.
+function charterView(liveBoard) {
+  return {
+    forms: FORMS,
+    variables: VARIABLES.map((v) => (
+      v.key === 'franchise' ? { ...v, options: FRANCHISE_OPTIONS }
+        : v.key === 'pass_rule' ? { ...v, options: PASS_RULE_OPTIONS }
+          : v.key === 'trajectory' ? { ...v, options: TRAJECTORIES }
+            : v)),
+    reads_as: readCharter(liveBoard),
+  };
+}
+
+module.exports = {
+  FORMS,
+  VARIABLES,
+  FRANCHISE_OPTIONS,
+  PASS_RULE_OPTIONS,
+  TRAJECTORIES,
+  readCharter,
+  buildCharterProposal,
+  charterView,
+};

package/modules/government/routes/government.js

@@ -114,6 +114,11 @@ const governmentPort = {
   // the constitution in force. And the founding band's read: per stage, what it
   // is waiting on. A pass is announced as `board.genesis_stage.passed`.
   openGenesisStageClose: board.openGenesisStageClose,
+  // task 1004427 (BV2.PS13): the genesis charter + legislation choice, filed as
+  // an ordinary amendment under the constitution in force — for the genesis
+  // home, which renders the stages from GET /government/constitution's
+  // `charter` block. Opening a sitting decides nothing; the vote does.
+  proposeCharter: board.proposeCharter,
   genesisStageStatus: board.genesisStageStatus,
 };
 
@@ -536,6 +541,63 @@ module.exports = function buildGovernmentRouter() {
     }
   });
 
+  // rank: perm board.item.open — the genesis charter + legislation choice (task
+  // 1004427, spec D10): a form of government and/or its two live settings
+  // (franchise, pass rule), built into a whole constitution on top of the live
+  // one and filed through the SAME amendment path as the route above — the same
+  // atom, the same strict validation, the same self-removal guard. Nothing here
+  // changes the constitution; the sitting it opens is what decides.
+  router.post('/government/board/charter', api.requireBuilder, api.requirePermission('board.item.open'), async (req, res) => {
+    if (validateOrRespond(req, res, {
+      form: { type: 'string', maxLength: 64 },
+      franchise: { type: 'string', maxLength: 32 },
+      council_rank: { type: 'string', maxLength: RANK_KEY_MAX },
+      pass_rule: { type: 'string', maxLength: 32 },
+      rationale_md: { type: 'string', maxLength: 5000 },
+      acknowledge_self_removal: { type: 'boolean' },
+    })) return;
+    const body = req.body || {};
+    if (body.window_minutes !== undefined && body.window_minutes !== null && !Number.isInteger(body.window_minutes)) {
+      return res.fail('invalid_proposal', 400, { reason: 'bad_window_minutes', expected: 'null (no clock) or a whole number of minutes' });
+    }
+    try {
+      const out = await board.proposeCharter({
+        form: body.form ?? undefined,
+        franchise: body.franchise ?? undefined,
+        councilRank: body.council_rank ?? undefined,
+        passRule: body.pass_rule ?? undefined,
+        windowMinutes: body.window_minutes,
+        rationaleMd: body.rationale_md ?? null,
+        proposedBy: req.builder.id,
+        acknowledgeSelfRemoval: body.acknowledge_self_removal === true,
+      });
+      if (!out.ok) {
+        if (out.reason === 'proposer_would_lose_their_seat') {
+          return res.fail('proposer_would_lose_their_seat', 409, {
+            membership: out.membership,
+            describes: out.describes,
+            what_this_means: out.what_this_means,
+            hint: out.hint,
+            retry_with: { acknowledge_self_removal: true },
+          });
+        }
+        if (out.reason === 'no_change') {
+          return res.fail('no_change', 409, { reason: 'the constitution in force already has these settings' });
+        }
+        return res.fail('invalid_charter', 400, {
+          reason: out.reason,
+          ...(out.field ? { field: out.field } : {}),
+          ...(out.expected ? { expected: out.expected } : {}),
+          ...(out.rank_key ? { rank_key: out.rank_key } : {}),
+        });
+      }
+      res.status(201).json({ ok: true, amendment: out.amendment, item: out.item, reads_as: out.reads_as });
+    } catch (err) {
+      log.error('[gds] POST /government/board/charter', err);
+      res.fail('charter_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // rank: perm board.vote.cast — cast a vote on an open board item (R08 of goal
   // 1000069, ADR 0175). The atom FLOORS AT XENOS deliberately (the R04 carry-
   // note): the permission is only the coarse gate, and the real wall is the

package/modules/hall-ui/public/government.js

@@ -678,6 +678,16 @@
   // hand" note; PASS_RULE_NAME sits beside its sentence-length twin
   // PASS_RULE_PLAIN there, so the two renderings of one pass rule cannot drift.
 
+  // The form of government the constitution in force READS AS (task 1004427):
+  // the real name and its plain explanation, or Custom. The server does the
+  // reading (charter.js readCharter) — the name follows the settings, so this
+  // page never guesses it. An older server without the block is said plainly.
+  function formOfGovernmentSentence(charter) {
+    const r = charter && charter.reads_as;
+    if (!r || !r.name) return 'Not available from this server yet.';
+    return `<strong>${escapeHtml(r.name)}</strong>. ${escapeHtml(r.explanation || '')}`;
+  }
+
   function dialRow(name, sentenceHtml) {
     return `<li class="ov-row"><div class="ov-row__main"><span class="ov-row__title">${escapeHtml(name)}</span><p class="ov-row__sub">${sentenceHtml}</p></div></li>`;
   }
@@ -829,6 +839,7 @@
     live.innerHTML = `
       ${divergenceHtml(data.divergence)}
       <ul class="ov-rows">
+        ${dialRow('Form of government', formOfGovernmentSentence(data.charter))}
         ${dialRow('Who sits on the board', membershipSentence(b))}
         ${dialRow('What counts as passing', passRuleSentence(b))}
         ${dialRow('How long a sitting runs', windowSentence(b, data.clock))}

package/modules/hall-ui/public/watch.js

@@ -474,6 +474,9 @@
   // invite form above, which is what the server's own refusal names.
   function gateRowActions(r) {
     const id = escapeHtml(r.id);
+    // An expired invite's door is already shut: inviting again (the form above) is
+    // the only move, so the row offers none.
+    if (r.expired) return '';
     if (r.status === 'invited') {
       return ghost(`data-gate-action="dismissed" data-gate-from="invited" data-id="${id}"`, 'Rescind', true);
     }
@@ -493,9 +496,12 @@
     // A rescind overwrites the approver with the rescinder (ADR 0208), so this
     // names who put the row in the state it is in now — which is what it says.
     const by = r.resolved_by_login ? ` by <span class="ov-mono">@${escapeHtml(r.resolved_by_login)}</span>` : '';
-    const decided = r.resolved_at
-      ? `<span class="ov-row__when">${r.status === 'invited' ? 'Admitted' : 'Declined'} ${escapeHtml(fmtDate(r.resolved_at))}${by}</span>`
-      : '';
+    // An invite past its 30 days is still 'invited' in storage, but no longer admits.
+    const decided = r.expired
+      ? `<span class="ov-row__when">Invite expired ${escapeHtml(fmtDate(r.expires_at))} — invite them again to reopen the door</span>`
+      : r.resolved_at
+        ? `<span class="ov-row__when">${r.status === 'invited' ? 'Admitted' : 'Declined'} ${escapeHtml(fmtDate(r.resolved_at))}${by}</span>`
+        : '';
     const actions = gateRowActions(r);
     return (
       `<li class="ov-row" data-req-id="${escapeHtml(r.id)}">` +

package/modules/onboarding/routes/access-requests.js

@@ -61,6 +61,9 @@ const api = require('../../../src/module-api');
 const auth = { requireBuilder: api.requireBuilder, requirePermission: api.requirePermission };
 const { pool } = api;
 const { validateOrRespond, parseId, accountExistenceReadRateLimit } = api;
+// A recruit invite's door closes 30 days after it is sent, computed at read time
+// (task 1002969, ADR 0356): one definition, shared with the sign-in gate itself.
+const { inviteLiveSql, inviteExpiredSql, inviteExpiresAtSql } = api.inviteExpiry;
 const approvalBroadcast = require('../approval-broadcast');
 const log = api.logger('onboarding');
 
@@ -161,8 +164,10 @@ async function attachApplicantProfiles(rows) {
 // doorway port that swallows every failure, so the hub can neither slow nor fail an
 // invite. No hub (self-hosted), or an older one without the route, costs the notice
 // alone.
+// "Standing" means the door still opens, so an expired invite neither blocks a
+// re-invite nor keeps the hub's notice alive.
 const STANDING_INVITE_SQL = `SELECT 1 FROM access_requests
-          WHERE lower(github_login) = lower($1) AND status = 'invited' LIMIT 1`;
+          WHERE lower(github_login) = lower($1) AND status = 'invited' AND ${inviteLiveSql()} LIMIT 1`;
 
 function noticeHubInvited(login) {
   api.notifyHubOfInvite(login, { invited: true });
@@ -223,11 +228,8 @@ module.exports = function buildAccessRequestsRouter() {
         return res.fail('already_member', { status: 409, message: 'You already have an account — just sign in with GitHub.' });
       }
       // Already approved (invited) but not yet signed in? No new request needed.
-      const invited = await pool.query(
-        `SELECT 1 FROM access_requests
-          WHERE lower(github_login) = lower($1) AND status = 'invited' LIMIT 1`,
-        [login]
-      );
+      // An expired invite is not an approval any more, so its invitee may ask.
+      const invited = await pool.query(STANDING_INVITE_SQL, [login]);
       if (invited.rows.length > 0) {
         return res.fail('already_approved', { status: 409, message: "You're already approved — sign in with GitHub to enter." });
       }
@@ -267,7 +269,9 @@ module.exports = function buildAccessRequestsRouter() {
   // (the device_code is spent), so the CLI can't re-poll the flow — it polls this
   // instead, then restarts sign-in once admitted. Exposes nothing the public POST
   // above doesn't already reveal through its 409s (already_member / already_approved).
-  // status ∈ member | invited | pending | dismissed | none; admitted = member||invited.
+  // status ∈ member | invited | expired | pending | dismissed | none; admitted =
+  // member||invited. `expired` is an invite past its 30 days (task 1002969): the door
+  // is shut, and the CLI stops waiting rather than polling a door that will not open.
   // rank: public — a would-be builder is by definition outside the system.
   // Declared BEFORE `GET /access-requests` so the literal `/status` path is matched
   // as its own route (not swallowed as a query on the list route).
@@ -294,15 +298,17 @@ module.exports = function buildAccessRequestsRouter() {
       if (member.rows.length > 0) {
         return res.json({ github_login: login, status: 'member', admitted: true });
       }
-      // Prefer an 'invited' row if one exists, else the most recent request.
+      // Prefer an invite that still admits, else the most recent request.
       const ar = await pool.query(
-        `SELECT status FROM access_requests
+        `SELECT status, (status = 'invited' AND ${inviteExpiredSql()}) AS expired
+           FROM access_requests
           WHERE lower(github_login) = lower($1)
-          ORDER BY (status = 'invited') DESC, created_at DESC
+          ORDER BY (status = 'invited' AND ${inviteLiveSql()}) DESC, created_at DESC
           LIMIT 1`,
         [login]
       );
-      const status = ar.rows.length > 0 ? ar.rows[0].status : 'none';
+      const top = ar.rows[0];
+      const status = !top ? 'none' : top.expired ? 'expired' : top.status;
       return res.json({ github_login: login, status, admitted: status === 'invited' });
     } catch (err) {
       console.error('[gds] GET /access-requests/status', err);
@@ -335,9 +341,13 @@ module.exports = function buildAccessRequestsRouter() {
     try {
       // `kind` + `invited_by_login` let the invited history tell an invite from
       // an approved application (ADR 0335 D2) — descriptive, like the vouch.
+      // `expired` + `expires_at` mark an invite whose 30 days are up (task 1002969):
+      // still 'invited' in storage, but its door no longer opens.
       const { rows } = await pool.query(
         `SELECT ar.id, ar.github_login, ar.display_name, ar.note, ar.status,
                 ar.created_at, ar.resolved_at, ar.kind,
+                (ar.status = 'invited' AND ${inviteExpiredSql('ar')}) AS expired,
+                ${inviteExpiresAtSql('ar')} AS expires_at,
                 ar.applicant_github_id, ar.applicant_handle, ar.vouched_at,
                 (ar.applicant_github_id IS NOT NULL) AS vouched,
                 rb.github_login AS resolved_by_login,
@@ -560,21 +570,34 @@ module.exports = function buildAccessRequestsRouter() {
   // still 'invited' (not rescinded), and no builder row yet (not yet accepted by
   // signing in), each naming its sender; ?mine=1 keeps only the caller's own
   // (ADR 0335 D2; task 1002814). Rescind one with PATCH /access-requests/:id.
+  // Each carries `expires_at`, and `expired` once its 30 days are up (task 1002969):
+  // listed so the sender knows to invite again, and dropped once a newer invite
+  // for the same login is live, since that one already replaced it.
   // rank: archon — it names logins that are not members yet.
   router.get('/access-requests/invites', auth.requireBuilder, auth.requirePermission('access_request.review'), async (req, res) => {
     const mine = req.query.mine === '1';
-    const mineClause = mine ? 'AND ar.created_by = $1' : '';
+    // `login_has_live` is a window over the rows this scan already reads, not a
+    // lookup per row: access_requests has no index on lower(github_login) outside
+    // pending rows, and invite rows are kept as history. The sender filter sits
+    // OUTSIDE the window, so another sender's live re-invite still retires yours.
+    const mineClause = mine ? 'AND inv.created_by = $1' : '';
     try {
       const { rows } = await pool.query(
-        `SELECT ar.id, ar.github_login, ar.note, ar.created_at,
-                ib.github_login AS invited_by_login
-           FROM access_requests ar
-           LEFT JOIN builders ib ON ib.id = ar.created_by
-          WHERE ar.kind = 'invite' AND ar.status = 'invited'
-            AND NOT EXISTS (SELECT 1 FROM builders b
-                             WHERE lower(b.github_login) = lower(ar.github_login))
+        `SELECT inv.id, inv.github_login, inv.note, inv.created_at,
+                inv.expires_at, inv.expired, inv.invited_by_login
+           FROM (SELECT ar.id, ar.github_login, ar.note, ar.created_at, ar.created_by,
+                        ${inviteExpiresAtSql('ar')} AS expires_at,
+                        ${inviteExpiredSql('ar')} AS expired,
+                        bool_or(${inviteLiveSql('ar')}) OVER (PARTITION BY lower(ar.github_login)) AS login_has_live,
+                        ib.github_login AS invited_by_login
+                   FROM access_requests ar
+                   LEFT JOIN builders ib ON ib.id = ar.created_by
+                  WHERE ar.kind = 'invite' AND ar.status = 'invited'
+                    AND NOT EXISTS (SELECT 1 FROM builders b
+                                     WHERE lower(b.github_login) = lower(ar.github_login))) inv
+          WHERE NOT (inv.expired AND inv.login_has_live)
             ${mineClause}
-          ORDER BY ar.created_at DESC
+          ORDER BY inv.created_at DESC
           LIMIT 200`,
         mine ? [req.builder.id] : []
       );

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

@@ -0,0 +1,65 @@
+-- platform_identity_028_purge_pre_notice_invites.sql — delete the `pending` rows the
+-- OLD hub invite wrote (task 1004408, the owner's call on ADR 0353's open consequence).
+--
+-- WHY. Before ADR 0353 the hub's POST /projects/invite wrote a `pending` membership
+-- row and nothing on the project. My Projects renders that row as "Open project →",
+-- and on any door but `open` (the default is `apply`) it leads to the project's own
+-- gate, which never heard of the invite: a locked door. Since ADR 0353 a `pending`
+-- row is a NOTICE that only the project writes (POST /sso/invites/notify), after it
+-- wrote its own `invited` row. So a pending row is a dead end exactly when it
+-- predates the hub's first run of ADR 0353 code.
+--
+-- THE CUTOFF IS THAT FIRST RUN, read from the core_upgrades ledger: the earliest
+-- upgrade to core 1.20.22 or later (the first release carrying ADR 0353, PR 1367).
+-- No such row means the hub has never served a notice route, so every pending row
+-- is an old one and all of them go. That is the expected case: the hub served
+-- 1.19.1081 when this was written, and upgrade.js writes the ledger row AFTER
+-- migrate, so the upgrade applying this file is not yet in the ledger. The ledger
+-- row lands just after the restart, so a notice written in those few seconds would
+-- also go; an old-style row cannot survive either way.
+--
+-- WHAT IS LOST. The owner accepted this (option (a)): an old row on an `open` door
+-- did lead somewhere, and it is deleted too. That invitee can still sign in to the
+-- project, and the inviter can re-invite through the project's own hall.
+--
+-- Touches `pending` rows only, so no real membership (owner, member, visitor) can
+-- be removed. One-shot: a replay after this file is recorded does nothing, so a
+-- hand-run later can never sweep up real notices. Deletes data but adds nothing
+-- the previous release cannot read, so it is forward-safe (ADR 0083 §5).
+
+BEGIN;
+
+DO $$
+DECLARE
+  notices_since timestamptz;
+  removed       integer;
+BEGIN
+  IF EXISTS (SELECT 1 FROM schema_migrations
+              WHERE version = 'platform_identity_028_purge_pre_notice_invites') THEN
+    RETURN;
+  END IF;
+
+  -- Only a well-formed x.y.z counts (any suffix ignored); the digit caps keep the
+  -- int cast from overflowing, so a malformed ledger row can never fail the deploy.
+  IF to_regclass('core_upgrades') IS NOT NULL THEN
+    SELECT min(applied_at) INTO notices_since
+      FROM (SELECT applied_at,
+                   substring(to_version FROM '^v?([0-9]{1,6}\.[0-9]{1,6}\.[0-9]{1,6})(?:[^0-9]|$)') AS xyz
+              FROM core_upgrades) u
+     WHERE xyz IS NOT NULL
+       AND string_to_array(xyz, '.')::int[] >= ARRAY[1, 20, 22];
+  END IF;
+
+  DELETE FROM platform_identity_project_memberships
+   WHERE membership_kind = 'pending'
+     AND (notices_since IS NULL OR joined_at < notices_since);
+  GET DIAGNOSTICS removed = ROW_COUNT;
+
+  RAISE NOTICE 'platform_identity_028: removed % pre-ADR-0353 pending invite row(s) (cutoff: %)',
+    removed, COALESCE(notices_since::text, 'none, the hub never ran ADR 0353');
+END $$;
+
+INSERT INTO schema_migrations (version) VALUES ('platform_identity_028_purge_pre_notice_invites')
+  ON CONFLICT DO NOTHING;
+
+COMMIT;

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

@@ -529,22 +529,25 @@ async function listMembershipsForAccount(githubId, { pool = defaultPool } = {})
 
 // Record that a project invited a builder: pre-seed a 'pending' membership, which is
 // a NOTICE shown in My Projects — the project's own row is what admits (ADR 0353;
-// written only from invite-notices.js now). Does NOT clobber an existing membership (ON CONFLICT DO NOTHING) — a
-// current member is left as-is. Returns { invited:true, row } when a pending row was
-// created, or { invited:false, alreadyMember:true } when a membership already existed.
+// written only from invite-notices.js now). Never clobbers a membership: a member is
+// left as-is, and a pending notice is restamped only once its invite's 30 days are up,
+// so a re-invite shows again (ADR 0356). Returns { invited:true, row } when it wrote,
+// or { invited:false, alreadyMember:true } when a membership or live notice stood.
 async function inviteToProject({ clientId, githubId }, { pool = defaultPool } = {}) {
   const { rows } = await pool.query(
-    `INSERT INTO platform_identity_project_memberships (client_id, github_id, membership_kind)
+    `INSERT INTO platform_identity_project_memberships AS m (client_id, github_id, membership_kind)
      VALUES ($1, $2, 'pending')
-     ON CONFLICT (client_id, github_id) DO NOTHING
+     ON CONFLICT (client_id, github_id) DO UPDATE SET joined_at = now()
+       WHERE m.membership_kind = 'pending' AND m.joined_at <= now() - make_interval(days => $3)
      RETURNING id, client_id, github_id, membership_kind`,
-    [clientId, githubId],
+    [clientId, githubId, api.inviteExpiry.INVITE_EXPIRY_DAYS],
   );
   if (rows[0]) return { invited: true, row: rows[0] };
   return { invited: false, alreadyMember: true };
 }
 
-// The pending invitations for one account (joined to the project display fields).
+// The pending invitations for one account (joined to the project display fields),
+// minus any past its invite's 30 days: that door no longer opens (ADR 0356).
 async function listPendingInvitesForAccount(githubId, { pool = defaultPool } = {}) {
   const { rows } = await pool.query(
     `SELECT m.client_id, m.joined_at AS invited_at,
@@ -552,8 +555,9 @@ async function listPendingInvitesForAccount(githubId, { pool = defaultPool } = {
        FROM platform_identity_project_memberships m
        LEFT JOIN platform_identity_sso_clients c ON c.client_id = m.client_id
       WHERE m.github_id = $1 AND m.membership_kind = 'pending'
+        AND m.joined_at > now() - make_interval(days => $2)
       ORDER BY m.joined_at DESC`,
-    [githubId],
+    [githubId, api.inviteExpiry.INVITE_EXPIRY_DAYS],
   );
   return rows;
 }

package/modules/platform-identity/tests/platform-identity.mjs

@@ -538,10 +538,12 @@ await ta('inviteToProject pre-seeds a pending row, never clobbering an existing
   const c = pool.calls[0];
   assert.match(c.text, /INSERT INTO platform_identity_project_memberships/);
   assert.match(c.text, /VALUES \(\$1, \$2, 'pending'\)/);
-  assert.match(c.text, /ON CONFLICT \(client_id, github_id\) DO NOTHING/, 'must not downgrade an existing member');
+  // Only joined_at, only on an expired pending notice (task 1002969); real SQL in
+  // ../../tests/invite_expiry_db.mjs.
+  assert.match(c.text, /ON CONFLICT \(client_id, github_id\) DO UPDATE SET joined_at = now\(\)\s+WHERE m\.membership_kind = 'pending' AND/, 'must not downgrade an existing member');
 });
 
-await ta('inviteToProject reports already-member when the row exists (DO NOTHING → no row)', async () => {
+await ta('inviteToProject reports already-member when the row exists (no row returned)', async () => {
   const pool = mockPool([{ rows: [] }]);
   const out = await P.inviteToProject({ clientId: 'c1', githubId: 42 }, { pool });
   assert.deepEqual(out, { invited: false, alreadyMember: true });