@bongos/core 1.19.514 → 1.19.515

package/modules/lifecycle/mingle.js

@@ -0,0 +1,337 @@
+// modules/lifecycle/mingle.js — mingle: two switches, cross-craft, declinable
+// without penalty (task 1003177 / C07, goal 1000075; criterion
+// collab-mingle-two-switches, ADR 0187 §5).
+//
+// THE DECISION. Mingle introduces two builders who do NOT share a craft. The
+// owner's reasoning (ADR 0187 §5) is the goal's founding premise — the person you
+// need is often not another one of you — and it is also what keeps mingle doing
+// something the craft-matched Collab request path does not already do.
+// Same-craft pairing was considered and REJECTED as duplicating
+// collab-page-matches-my-craft; do not "improve" the matcher by adding it back.
+//
+// TWO SWITCHES, AND ONE IS NOT CONSENT. A pair happens only when the PROJECT has
+// enabled mingle AND the individual has opted in. Auto-pairing a person with a
+// stranger a few times a week is a real-world social commitment, so the project
+// enabling it for everyone is not the person agreeing to it, and a person opting
+// in on an instance that never turned it on is not the project offering it. Both
+// are read on every pairing, and both FAIL CLOSED: absent is "no", never
+// "hasn't said no yet" (the ADR 0171 posture, inherited).
+//
+// DECLINING IS FREE, AND THAT IS A PROPERTY OF THE READ, NOT A PROMISE.
+// "Without penalty" means declining affects no rank, no karma, no streak and no
+// future matching weight — and the criterion insists that be verifiable rather
+// than stated. Two things make it so, and both are structural:
+//
+//   1. `decline()` writes ONE row in ONE table — the pair it is settling. It
+//      touches no credit, karma, rank or streak surface, and there is no counter
+//      anywhere to touch (see lifecycle_007_mingle.sql, which says the same thing
+//      about the schema).
+//   2. `eligibleBuilders()` — the matcher's ONLY input about who may be paired —
+//      never reads lifecycle_mingle_pairs at all. A decline therefore cannot make
+//      the decliner less likely to be paired again, because the read that decides
+//      that has no way to see it. The one thing pair history does gate is a second
+//      OPEN proposal for the same two people, which is the unique index's job and
+//      is about not double-introducing, not about declines.
+//
+// tests/mingle.mjs drives both against a recording pool and fails if either stops
+// being true.
+//
+// THE CRAFT VOCABULARY IS NOT REDEFINED HERE. help-requests.js declares itself the
+// one place that knows how a craft maps to `builders.preferred_disciplines`
+// ('builder' the craft is 'engineer' the discipline), so this file consumes
+// `craftMapSql` / `craftForDiscipline` from it rather than re-deriving. Two
+// spellings of the same craft would silently match nobody.
+//
+// Reaches core only through the doorway (ADR 0083). The core tables it reads
+// (builders) are read-only here.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool } = api;
+const { craftMapSql } = require('./help-requests');
+
+// The PROJECT switch. A module-owned knob in the project's own store
+// (project_settings, migration core_231) — deliberately NOT a second settings
+// table, which is the thing src/bongos/project-settings.js exists to prevent, and
+// deliberately not registered in that file's core SETTING_KEYS: the key is
+// namespaced to this surface, and a module's knob is the module's to name.
+const MINGLE_ENABLED_KEY = 'mingle.enabled';
+
+const MAX_ROWS = 100;
+
+// THE MATCHING RULE, RECORDED. The criterion asks for cross-craft to be "chosen
+// deliberately and recorded", so the rule is data a reader can fetch (the route
+// serves this verbatim) rather than a shape you have to infer from the SQL — the
+// same reason closeness-weights.json exists.
+const MATCHING = Object.freeze({
+  rule: 'cross_craft',
+  description:
+    'A pair is two builders whose crafts do not overlap at all — an engineer with '
+    + 'an artist or an ideator, never two of the same. The premise is that the '
+    + 'person you need is often not another one of you.',
+  // Stated because it is the road not taken, and an unexplained absence reads as
+  // an oversight to the next person holding the matcher.
+  rejected: 'same_craft — it duplicates the craft-matched Collab request path (criterion collab-page-matches-my-craft).',
+  // DISJOINT, not merely "different". A builder who is both an artist and an
+  // engineer shares a craft with every engineer, so pairing them would put two of
+  // the same in a room and call it cross-craft.
+  overlap: 'none',
+  consent: 'Both switches required: the project enables mingle AND the builder opts in. Either off means no pair.',
+  decline: 'Terminal and free — no rank, karma, streak or matching effect. The eligibility read never sees pair history.',
+});
+
+function matchingModel() { return MATCHING; }
+
+// ---------------------------------------------------------------------------
+// Switch 1 — the project
+// ---------------------------------------------------------------------------
+
+// TRUE only for an explicit, recognised yes. Everything else — absent, blank,
+// 'maybe', a value that was valid before someone tightened this — is NO.
+//
+// This is the one place mingle deliberately DIVERGES from the rot timer's posture
+// in src/bongos/project-settings.js. That file reports a bad value on the screen
+// of the person who can fix it, because all of its callers are read surfaces. This
+// is a consent gate: an unreadable switch must not open, so it fails closed the
+// way ADR 0171's consent state does. One enforces, one reports.
+function parseEnabled(raw) {
+  if (raw == null) return false;
+  return ['true', '1', 'on', 'yes'].includes(String(raw).trim().toLowerCase());
+}
+
+async function projectEnabled(deps = {}) {
+  const get = deps.getSetting || api.projectSettings.get;
+  let row;
+  try {
+    row = await get(MINGLE_ENABLED_KEY);
+  } catch (_) {
+    // FAIL CLOSED. An unreadable switch is not permission.
+    return false;
+  }
+  return parseEnabled(row && row.value);
+}
+
+async function setProjectEnabled(enabled, builderId = null, deps = {}) {
+  const set = deps.setSetting || api.projectSettings.set;
+  await set(MINGLE_ENABLED_KEY, enabled ? 'true' : 'false', builderId);
+  return { key: MINGLE_ENABLED_KEY, enabled: !!enabled };
+}
+
+// ---------------------------------------------------------------------------
+// Switch 2 — the builder
+// ---------------------------------------------------------------------------
+
+// null = never offered / never answered. Deliberately distinct from false, which
+// is a deliberate withdrawal — a surface that cannot tell them apart cannot ask
+// the right question.
+async function optInState(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    'SELECT opted_in, updated_at FROM lifecycle_mingle_optin WHERE builder_id = $1',
+    [builderId]
+  );
+  if (!rows[0]) return { opted_in: null, updated_at: null };
+  return { opted_in: rows[0].opted_in === true, updated_at: rows[0].updated_at };
+}
+
+async function setOptIn(builderId, optedIn, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_mingle_optin (builder_id, opted_in, updated_at)
+          VALUES ($1, $2, now())
+     ON CONFLICT (builder_id) DO UPDATE
+            SET opted_in = EXCLUDED.opted_in, updated_at = now()
+      RETURNING builder_id, opted_in, updated_at`,
+    [builderId, !!optedIn]
+  );
+  return rows[0];
+}
+
+// BOTH switches, resolved together, for one builder. The surface that asks "can I
+// mingle" gets back which half is off, because "no" with no reason is a dead end
+// for the person who could turn their own half on.
+async function mingleStateFor(builderId, deps = {}) {
+  const [project, mine] = await Promise.all([projectEnabled(deps), optInState(builderId, deps)]);
+  return {
+    enabled: project && mine.opted_in === true,
+    project_enabled: project,
+    opted_in: mine.opted_in,
+    opted_in_at: mine.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The matcher
+// ---------------------------------------------------------------------------
+
+// Everyone the project may introduce right now: opted in, active, and carrying at
+// least one craft.
+//
+// IT DOES NOT JOIN lifecycle_mingle_pairs, AND MUST NOT. This read is the whole of
+// "who may be paired", so the moment it can see a decline, declining has a
+// matching cost and the criterion is broken. See the header.
+//
+// A builder with no `preferred_disciplines` produces no rows through the unnest and
+// is therefore absent — the correct fail-closed answer, and the same one
+// help-requests gives: belonging to a craft is a claim about yourself the system
+// should not assume on your behalf.
+async function eligibleBuilders(deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT b.id::text AS builder_id,
+            array_agg(DISTINCT ${craftMapSql('d')}) FILTER (WHERE ${craftMapSql('d')} IS NOT NULL) AS crafts
+       FROM lifecycle_mingle_optin o
+       JOIN builders b ON b.id = o.builder_id
+       CROSS JOIN LATERAL unnest(b.preferred_disciplines) AS d
+      WHERE o.opted_in = true
+        AND b.status = 'active'
+      GROUP BY b.id
+      ORDER BY b.id`
+  );
+  return rows
+    .map((r) => ({ builder_id: String(r.builder_id), crafts: (r.crafts || []).filter(Boolean).sort() }))
+    .filter((b) => b.crafts.length > 0);
+}
+
+// PURE. Is this pair legal? Disjoint craft sets — see MATCHING.overlap.
+function isCrossCraft(craftsA, craftsB) {
+  const a = new Set(craftsA || []);
+  if (!a.size || !(craftsB || []).length) return false;
+  return !(craftsB || []).some((c) => a.has(c));
+}
+
+// PURE. Given eligible builders, produce cross-craft pairs — each builder in at
+// most one pair. Greedy over a stable order so the same input always yields the
+// same pairing (a matcher that shuffles cannot be tested, and cannot be explained
+// to the person it introduced).
+//
+// `excludePairs` is the set of "lo:hi" keys that already hold an OPEN proposal. It
+// is NOT decline history: settled pairs are absent from it and may be introduced
+// again, because a decline that permanently separated two people would be a
+// consequence, and declining is free.
+function planPairs(eligible, { excludePairs = new Set(), limit = MAX_ROWS } = {}) {
+  const taken = new Set();
+  const out = [];
+  const list = [...eligible].sort((a, b) => String(a.builder_id).localeCompare(String(b.builder_id)));
+  for (let i = 0; i < list.length && out.length < limit; i++) {
+    const a = list[i];
+    if (taken.has(a.builder_id)) continue;
+    for (let j = i + 1; j < list.length; j++) {
+      const b = list[j];
+      if (taken.has(b.builder_id)) continue;
+      if (!isCrossCraft(a.crafts, b.crafts)) continue;
+      const pair = orderPair(a, b);
+      if (excludePairs.has(pairKey(pair.lo.builder_id, pair.hi.builder_id))) continue;
+      taken.add(a.builder_id); taken.add(b.builder_id);
+      out.push({
+        builder_lo: pair.lo.builder_id,
+        builder_hi: pair.hi.builder_id,
+        // One representative craft each. The sets are disjoint, so any pick
+        // differs — recording them is what lets a pair be audited later even if
+        // someone changes their disciplines afterwards.
+        craft_lo: pair.lo.crafts[0],
+        craft_hi: pair.hi.crafts[0],
+      });
+      break;
+    }
+  }
+  return out;
+}
+
+function orderPair(a, b) {
+  return String(a.builder_id).padStart(24, '0') <= String(b.builder_id).padStart(24, '0')
+    ? { lo: a, hi: b } : { lo: b, hi: a };
+}
+
+function pairKey(lo, hi) { return `${lo}:${hi}`; }
+
+async function openPairKeys(deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT builder_lo::text AS lo, builder_hi::text AS hi
+       FROM lifecycle_mingle_pairs WHERE status = 'proposed'`
+  );
+  return new Set(rows.map((r) => pairKey(String(r.lo), String(r.hi))));
+}
+
+// Introduce everyone who can be introduced, and write the pairs. Refuses outright
+// when the PROJECT switch is off — the per-builder switch is already enforced by
+// eligibleBuilders, which only ever returns people who opted in.
+async function runMingleRound({ limit = MAX_ROWS } = {}, deps = {}) {
+  if (!(await projectEnabled(deps))) return { paired: [], skipped: 'project_disabled' };
+  const activePool = deps.pool || pool;
+  const [eligible, open] = await Promise.all([eligibleBuilders(deps), openPairKeys(deps)]);
+  const planned = planPairs(eligible, { excludePairs: open, limit });
+  if (!planned.length) return { paired: [], skipped: null };
+
+  // ONE insert for the whole round, not one per pair. The round is bounded to
+  // MAX_ROWS and runs rarely, so this is not a hot path — but a loop of awaited
+  // INSERTs is also a partial write when the tenth throws, and unnest() makes the
+  // round atomic for free. ON CONFLICT DO NOTHING lets the open-pair unique index
+  // drop a pair another round introduced a moment ago rather than failing all of
+  // them; RETURNING is therefore what was actually written, never what was planned.
+  const { rows } = await activePool.query(
+    `INSERT INTO lifecycle_mingle_pairs (builder_lo, builder_hi, craft_lo, craft_hi)
+     SELECT * FROM unnest($1::bigint[], $2::bigint[], $3::text[], $4::text[])
+     ON CONFLICT DO NOTHING
+      RETURNING id, builder_lo::text AS builder_lo, builder_hi::text AS builder_hi,
+                craft_lo, craft_hi, status, created_at`,
+    [
+      planned.map((p) => p.builder_lo),
+      planned.map((p) => p.builder_hi),
+      planned.map((p) => p.craft_lo),
+      planned.map((p) => p.craft_hi),
+    ]
+  );
+  return { paired: rows, skipped: null };
+}
+
+// The open introductions for one builder, either side of the pair.
+async function openPairsFor(builderId, deps = {}) {
+  const activePool = deps.pool || pool;
+  const { rows } = await activePool.query(
+    `SELECT p.id, p.builder_lo::text AS builder_lo, p.builder_hi::text AS builder_hi,
+            p.craft_lo, p.craft_hi, p.status, p.created_at,
+            lo.github_login AS lo_login, lo.display_name AS lo_name,
+            hi.github_login AS hi_login, hi.display_name AS hi_name
+       FROM lifecycle_mingle_pairs p
+       JOIN builders lo ON lo.id = p.builder_lo
+       JOIN builders hi ON hi.id = p.builder_hi
+      WHERE p.status = 'proposed'
+        AND (p.builder_lo = $1 OR p.builder_hi = $1)
+      ORDER BY p.created_at DESC`,
+    [builderId]
+  );
+  return rows;
+}
+
+// Accept or decline an introduction you are part of.
+//
+// ONE ROW, ONE TABLE. There is nothing else to write, and that absence IS the
+// "without penalty" guarantee — see the header and the migration. Do not add a
+// counter, a cooldown, or a karma/credit call here.
+async function decidePair(pairId, builderId, decision, deps = {}) {
+  const activePool = deps.pool || pool;
+  if (!['accepted', 'declined'].includes(decision)) return { error: 'bad_decision' };
+  const { rows } = await activePool.query(
+    `UPDATE lifecycle_mingle_pairs
+        SET status = $3, decided_by = $2, decided_at = now()
+      WHERE id = $1
+        AND status = 'proposed'
+        AND (builder_lo = $2 OR builder_hi = $2)
+      RETURNING id, builder_lo::text AS builder_lo, builder_hi::text AS builder_hi,
+                craft_lo, craft_hi, status, decided_by::text AS decided_by, decided_at`,
+    [pairId, builderId, decision]
+  );
+  if (!rows[0]) return { error: 'not_found' };
+  return { pair: rows[0] };
+}
+
+module.exports = {
+  MINGLE_ENABLED_KEY, MAX_ROWS, MATCHING, matchingModel,
+  parseEnabled, projectEnabled, setProjectEnabled,
+  optInState, setOptIn, mingleStateFor,
+  eligibleBuilders, isCrossCraft, planPairs, pairKey, openPairKeys,
+  runMingleRound, openPairsFor, decidePair,
+};

package/modules/lifecycle/module.json

@@ -21,6 +21,7 @@
       "help-requests",
       "recommendations",
       "closeness",
+      "mingle",
       "visuals",
       "kickoff-seed",
       "rot"

package/modules/lifecycle/routes/mingle.js

@@ -0,0 +1,116 @@
+// modules/lifecycle/routes/mingle.js — the two switches, the introductions, and
+// the decline (task 1003177 / C07, goal 1000075; criterion
+// collab-mingle-two-switches, ADR 0187 §5).
+//
+// FIVE ROUTES, AND THE SHAPE IS THE POINT:
+//   GET  /mingle                  — where I stand: BOTH switches, my open
+//                                   introductions, and the matching rule itself.
+//   PUT  /mingle/opt-in           — MY half of consent. Own-scoped, any-builder.
+//   PUT  /mingle/project          — the PROJECT's half. `mingle.manage`.
+//   POST /mingle/round            — run a pairing round. `mingle.manage`.
+//   POST /mingle/pairs/:id/decide — accept or decline an introduction I am in.
+//
+// WHY GET /mingle ANSWERS WITH BOTH SWITCHES RATHER THAN ONE BOOLEAN. "You cannot
+// mingle" with no reason is a dead end for the one person who could fix half of
+// it. A builder who has opted in on an instance that never enabled mingle should
+// see that it is the project's half that is off, and not be told to change a
+// setting they already set.
+//
+// THE OPERATOR GATE IS AN ATOM, NOT A RANK. `requireRank` in a modules/*/routes
+// gate is what BV1.R105 exists to remove, and tests/government_require_permission
+// fails the build on a new one — the two files still spelling it that way are
+// documented holdouts, not a pattern to copy. So this mints `mingle.manage`
+// (modules/government/catalog.js) and gates on it.
+//
+// FLOOR: metic, by the `discord.channels.manage` analogue — configuring a
+// project-wide social surface — and not archon. What makes that safe is the OTHER
+// switch: enabling mingle only OFFERS it, and can never pair a builder who has not
+// personally opted in, so this gate cannot put anyone in a room with a stranger.
+//
+// THE DECLINE ROUTE COSTS THE DECLINER NOTHING, and there is deliberately nothing
+// here that could make it cost: no counter to bump, no karma or credit call, no
+// cooldown to write. See mingle.js and lifecycle_007_mingle.sql, which say the
+// same thing about the read and the schema.
+//
+// Reaches core only through the doorway (ADR 0083).
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const mingle = require('../mingle');
+
+const { asyncHandler, validateOrRespond, parseId } = api;
+
+module.exports = function buildMingleRouter() {
+  const router = express.Router();
+
+  // rank: any-builder, and OWN-SCOPED — your own state, never someone else's.
+  // Who else has opted in to being introduced is a fact about them.
+  router.get('/mingle', api.requireBuilder, asyncHandler('GET /mingle', async (req, res) => {
+    const [state, pairs] = await Promise.all([
+      mingle.mingleStateFor(req.builder.id),
+      mingle.openPairsFor(req.builder.id),
+    ]);
+    return res.json({
+      mingle: state,
+      open_pairs: pairs,
+      // Served VERBATIM from the module. The criterion asks for cross-craft to be
+      // chosen deliberately and RECORDED; this is where it is read, and a
+      // restatement here could drift from the matcher that actually runs.
+      matching: mingle.matchingModel(),
+    });
+  }, { errorCode: 'mingle_read_failed' }));
+
+  // rank: any-builder, OWN-SCOPED. Keyed by the SESSION, never a body field —
+  // consent you can give on someone else's behalf is not consent.
+  router.put('/mingle/opt-in', api.requireBuilder, asyncHandler('PUT /mingle/opt-in', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      opted_in: { required: true, type: 'boolean' },
+    })) return;
+    const row = await mingle.setOptIn(req.builder.id, req.body.opted_in === true);
+    return res.json({ opted_in: row.opted_in, updated_at: row.updated_at });
+  }, { errorCode: 'mingle_optin_failed' }));
+
+  // perm: mingle.manage (floor metic) — see the header. Offering the feature to
+  // the project is an operator act; it still cannot pair anyone who has not
+  // opted themselves in.
+  router.put('/mingle/project', api.requireBuilder, api.requirePermission('mingle.manage'), asyncHandler('PUT /mingle/project', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      enabled: { required: true, type: 'boolean' },
+    })) return;
+    const out = await mingle.setProjectEnabled(req.body.enabled === true, req.builder.id);
+    return res.json(out);
+  }, { errorCode: 'mingle_project_switch_failed' }));
+
+  // perm: mingle.manage — running a round writes introductions for other people,
+  // so it is an operator action rather than something a builder does to themselves.
+  // Refuses on its own when the project switch is off (runMingleRound checks).
+  router.post('/mingle/round', api.requireBuilder, api.requirePermission('mingle.manage'), asyncHandler('POST /mingle/round', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      limit: { type: 'integer', min: 1, max: mingle.MAX_ROWS },
+    })) return;
+    const out = await mingle.runMingleRound({ limit: req.body.limit || mingle.MAX_ROWS });
+    return res.json({ paired: out.paired, count: out.paired.length, skipped: out.skipped });
+  }, { errorCode: 'mingle_round_failed' }));
+
+  // rank: any-builder. The UPDATE itself requires the caller to be one of the two
+  // people in the pair, so a builder cannot answer an introduction they are not
+  // part of — enforced in SQL, not by a check here that a later caller could skip.
+  router.post('/mingle/pairs/:id/decide', api.requireBuilder, asyncHandler('POST /mingle/pairs/:id/decide', async (req, res) => {
+    const pairId = parseId(req, res, { param: 'id', code: 'bad_pair_id', positiveInt: true });
+    if (pairId === null) return;
+    if (validateOrRespond(req, res, {
+      decision: { required: true, type: 'string', enum: ['accepted', 'declined'] },
+    })) return;
+
+    const out = await mingle.decidePair(pairId, req.builder.id, req.body.decision);
+    if (out.error === 'bad_decision') return res.fail(400, 'bad_decision', 'decision must be accepted or declined');
+    // ONE answer for "no such pair", "already settled" and "not yours". Telling
+    // them apart would let a caller probe which pair ids exist and who is in them.
+    if (out.error) return res.fail(404, 'pair_not_found', 'no open introduction with that id for you');
+    return res.json({ pair: out.pair });
+  }, { errorCode: 'mingle_decide_failed' }));
+
+  return router;
+};

package/package-lock.json

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

package/package.json

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

package/src/module-api.js

@@ -45,7 +45,7 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.514'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.515'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/government_seed.mjs

@@ -182,3 +182,38 @@ test('migration objects are all governance_-namespaced (ADR 0083 §5)', () => {
     }
   }
 });
+
+// THE GAP THE DRIFT GUARD ABOVE CANNOT SEE (found by the task 1003177 grader).
+//
+// The union model is a regex over `SELECT '<rank>', unnest(ARRAY[…])`. It reads
+// the KEYS and never looks at the table those keys are inserted INTO — so a new
+// grant migration copied from a `governance_*` sibling passes it while writing to
+// `governance_role_permissions (role_key, …)`, the PRE-rename names.
+//
+// government_001_rename_from_governance renamed that table to
+// `government_rank_permissions` and its `role_key` column to `rank_key`, with no
+// compatibility shim. Migrations apply in filename order, so on any database —
+// a fresh install included — a `government_*`-prefixed file writes AFTER the
+// rename and must use the new names or error at apply time. The permission would
+// then never resolve, and its routes would 403 for every rank, Archon included.
+//
+// Scoped to the `government_`-prefixed files on purpose: the historical
+// `governance_*` migrations legitimately name the pre-rename tables (they ran
+// before the rename, and renaming an applied migration re-runs it — the standing
+// rule in modules/government/CLAUDE.md).
+test('a post-rename grant migration writes to the RENAMED table, not the old one', () => {
+  const postRename = grantSqlByFile.filter(([f]) => f.startsWith('government_'));
+  assert.ok(postRename.length > 0, 'there is at least one government_-prefixed grant migration');
+
+  for (const [file, sql] of postRename) {
+    const ddl = sql.replace(/^\s*--.*$/gm, '');   // a comment may CITE the old name
+    assert.ok(!/governance_role_permissions/.test(ddl),
+      `${file}: writes to governance_role_permissions — renamed to government_rank_permissions by government_001`);
+    assert.ok(!/\brole_key\b/.test(ddl),
+      `${file}: names the role_key column — renamed to rank_key by government_001`);
+    if (/INSERT INTO/.test(ddl)) {
+      assert.match(ddl, /INSERT INTO government_rank_permissions \(rank_key, permission_key\)/,
+        `${file}: a grant insert must target government_rank_permissions (rank_key, permission_key)`);
+    }
+  }
+});