@bongos/core 1.19.592 → 1.19.593

package/scripts/gds/triage.js

@@ -220,15 +220,37 @@ async function resolveGoalDefault(idea, versionId, { client = cliClient } = {})
 // default — declining has to be said ('-' or 'none'), because silently dropping a
 // real default on a bare Enter is how work ends up in the general bucket by
 // accident. Declining is legal: the server then applies the catch-all itself.
+// applyGoalAnswer — read the operator's goal answer at the triage prompt.
+//
+// BV1.R22 (task 1003609, goal 1000086): THE GENERAL BUCKET IS GONE. Every branch
+// that used to resolve to `goalId: null` did so because a goal-less create fell
+// into the version's catch-all "<version> — general" goal. R11 (task 1003598)
+// deleted that fallback and made `goal_id` required, so `null` is no longer an
+// opt-out — it is a `400 goal_id_required` from the server, arriving after the
+// operator has typed a title, a description and a priority, and losing all of it.
+//
+// So the two escapes become refusals, and they refuse HERE, before the round trip:
+//   '-' / 'none'  — was "file it in the general bucket"; there is no bucket.
+//   a junk answer — was silently downgraded to the bucket with a warning, which
+//                   is the worse of the two: a typo'd goal id read as a decision.
+//
+// `ok: false` means re-ask. The caller loops rather than aborting the whole
+// triage run, because the operator's other answers are still good.
 function applyGoalAnswer(defaultGoalId, rawAnswer) {
   const answer = String(rawAnswer == null ? '' : rawAnswer).trim();
-  if (answer === '') return { goalId: defaultGoalId, warn: null };
-  if (answer === '-' || answer.toLowerCase() === 'none') return { goalId: null, warn: null };
+  if (answer === '') {
+    return defaultGoalId != null
+      ? { ok: true, goalId: defaultGoalId, warn: null }
+      : { ok: false, goalId: null, warn: 'a goal is required — every task belongs to one. Enter a goal id (GET /goals?version=<id> lists them), or "s" to skip this idea.' };
+  }
+  if (answer === '-' || answer.toLowerCase() === 'none') {
+    return { ok: false, goalId: null, warn: 'the version\'s "general" catch-all no longer exists (task 1003598) — a task must name a real goal. Enter a goal id, or "s" to skip this idea.' };
+  }
   const parsed = Number(answer);
   if (!Number.isInteger(parsed) || parsed <= 0) {
-    return { goalId: null, warn: "not a goal id — falling back to the version's general bucket" };
+    return { ok: false, goalId: null, warn: `"${answer}" is not a goal id. Enter a number, or "s" to skip this idea.` };
   }
-  return { goalId: parsed, warn: null };
+  return { ok: true, goalId: parsed, warn: null };
 }
 
 async function createTask({ versionId, title, description, priority, sourceRef, goalId = null }) {
@@ -239,13 +261,13 @@ async function createTask({ versionId, title, description, priority, sourceRef,
   // make, and the server classifier still runs. Corrected rather than deleted so
   // the next reader does not re-derive it.)
   //
-  // task 1003071 (R13): goal_id is the point of this task. Omitting it does NOT
-  // leave the task goal-less — db.createTask (modules/lifecycle/db.js) defaults a
-  // goal-less create into the version's catch-all "<version> — general" goal. That
-  // bucket is the actual defect: it carries no done-when criteria, so since ADR
-  // 0183 made criteria close themselves off LINKED tasks, work parked there can
-  // never advance anything, and it does not read as real goal work on the board.
-  // Naming the goal here is what stops a triaged promotion falling into it.
+  // task 1003071 (R13) named the goal here; BV1.R22 (task 1003609) makes it
+  // MANDATORY. R11 (task 1003598) deleted the "<version> — general" catch-all that
+  // a goal-less create used to fall into, so omitting goal_id is now a server
+  // `400 goal_id_required` rather than a quiet mis-filing. Reaching this function
+  // without one is a bug in the caller, and it throws rather than posting: the
+  // prompt above re-asks until it has a real id, so the only way here with null is
+  // a new call site that forgot — which should fail at its author, not in prod.
   const body = {
     version_id: versionId,
     title,
@@ -255,7 +277,10 @@ async function createTask({ versionId, title, description, priority, sourceRef,
     source: 'idea_inbox',
     source_ref: sourceRef ?? null,
   };
-  if (goalId != null) body.goal_id = Number(goalId);
+  if (goalId == null) {
+    throw new Error('createTask: goal_id is required — every task belongs to a goal (task 1003598 deleted the catch-all fallback).');
+  }
+  body.goal_id = Number(goalId);
   const api = await cliClient();
   const r = await api.tasks.postTasks({ body });
   if (!r.ok) {
@@ -612,21 +637,30 @@ async function main() {
           const title = titleAns || idea.title;
 
           // task 1003071 (R13): a triaged promotion NAMES its goal. The default
-          // comes from the stored hint, else the R07 suggester; '-' opts out
-          // explicitly, which falls through to the version's catch-all "general"
-          // bucket — now a choice someone typed rather than the silent default.
-          // The EFFECTIVE title, not idea.title: the suggester matches on title
-          // terms, and the operator may just have retitled this.
+          // comes from the stored hint, else the R07 suggester. The EFFECTIVE
+          // title, not idea.title: the suggester matches on title terms, and the
+          // operator may just have retitled this.
+          //
+          // BV1.R22 (task 1003609): the opt-out is gone, so this RE-ASKS instead of
+          // falling through. Skipping is still available and is now spelled 's' —
+          // it leaves the idea open for the next pass rather than filing it
+          // somewhere it does not belong, which is what the general bucket was.
           const gd = await resolveGoalDefault({ ...idea, title }, versionId);
           if (gd.source === 'suggester') console.log(`  suggested goal: ${gd.label}`);
-          if (gd.source === 'unavailable') console.log('  (goal suggester unreachable — enter a goal id, or "-" to accept the general bucket)');
-          const goalPrompt = gd.goalId != null
-            ? `  goal [${gd.goalId}] ("-" for the version's general bucket): `
-            : '  goal (blank/"-" for the version\'s general bucket): ';
-          const goalAns = (await prompt(rl, goalPrompt)).trim();
-          const picked = applyGoalAnswer(gd.goalId, goalAns);
-          if (picked.warn) console.log(`  ! ${picked.warn}`);
-          const goalId = picked.goalId;
+          if (gd.source === 'unavailable') console.log('  (goal suggester unreachable — enter a goal id yourself; GET /goals?version=<id> lists them)');
+          let goalId = null;
+          let skipIdea = false;
+          for (;;) {
+            const goalPrompt = gd.goalId != null
+              ? `  goal [${gd.goalId}] ("s" to skip this idea): `
+              : '  goal id ("s" to skip this idea): ';
+            const goalAns = (await prompt(rl, goalPrompt)).trim();
+            if (goalAns.toLowerCase() === 's') { skipIdea = true; break; }
+            const picked = applyGoalAnswer(gd.goalId, goalAns);
+            if (picked.ok) { goalId = picked.goalId; break; }
+            console.log(`  ! ${picked.warn}`);
+          }
+          if (skipIdea) { console.log('  – skipped (still open in the inbox)'); summary.skipped++; continue; }
 
           try {
             const task = await createTask({
@@ -644,7 +678,7 @@ async function main() {
             });
             summary.promoted++;
             promotedIds.push({ ideaId: idea.id, taskId: task.id });
-            console.log(`  ✓ promoted #${idea.id} → task #${task.id} (${versionId}, P${priority}${goalId != null ? `, goal ${goalId}` : ', → general bucket'})`);
+            console.log(`  ✓ promoted #${idea.id} → task #${task.id} (${versionId}, P${priority}, goal ${goalId})`);
           } catch (err) {
             console.error(`  ! ${err.message}`);
           }

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // 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.592'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.593'; // 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/goal_archive_hall.mjs

@@ -0,0 +1,198 @@
+// tests/goal_archive_hall.mjs — the goal page tells the truth about what is
+// holding a goal open, and walks the archive two-step without curl
+// (BV1.R24, task 1003611, goal 1000086, ADR 0250 D2/D3).
+//
+// TWO THINGS THIS PAGE COULD NOT SAY BEFORE.
+//
+//   1. WHY A GOAL IS STILL OPEN. Until R08/R09 (tasks 1003595, 1003596) a goal
+//      closed on its criteria alone, so "N of M criteria satisfied" was the whole
+//      answer. ADR 0250 D2 added "AND no task in it is non-terminal" — and a task
+//      linked to NO criterion appears nowhere in that rollup. A builder could read
+//      5-of-5 satisfied, watch the goal stay open, and find nothing on the page
+//      explaining it. That reads as a bug in the gate rather than the gate working.
+//
+//   2. HOW TO RETIRE ONE. R10 made archive refuse and return the work; R14 made it
+//      apply a disposition. Both were API-only, so the only way to retire a goal
+//      holding work was hand-written JSON — which is why the ADR 0264 goal cut
+//      needed a terminal.
+//
+// Static assertions over the shipped browser source, the promote_goal_id.mjs
+// precedent: these are DOM strings a unit test cannot invoke, and the properties
+// worth pinning are structural — which read feeds the panel, what the move-target
+// filter excludes, and that the server's refusal is shown rather than paraphrased.
+//
+// Run:  node tests/goal_archive_hall.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+const { test, summary } = makeRunner();
+const src = (rel) => readFileSync(new URL('../' + rel, import.meta.url), 'utf8');
+const RENDER = src('modules/hall-ui/public/goals-render.js');
+const CSS = src('modules/hall-ui/public/goals.css');
+const ROUTES = src('modules/lifecycle/routes/goals.js');
+
+// ---- the server hands the page the same facts the refusal uses --------------
+
+await test('GET /goals/:id carries the open tasks, from the SAME read the refusal returns', () => {
+  const detail = ROUTES.slice(ROUTES.indexOf("router.get('/goals/:id'"), ROUTES.indexOf("router.get('/goals/:id/suggest-criteria'"));
+  assert.match(detail, /db\.openTasksInGoal\(id\)/,
+    'the page must not compute "what is in the way" a second way');
+  assert.match(detail, /open_tasks: openTasks/, 'and it must reach the client');
+  // If the page used a different read, it could show a builder a list the archive
+  // refusal then disagrees with — the exact confusion the two-step exists to end.
+  const archive = ROUTES.slice(ROUTES.indexOf("router.post('/goals/:id/archive'"));
+  assert.match(archive, /db\.openTasksInGoal\(id/, 'the refusal reads it too');
+});
+
+// ---- 1. why the goal is open ------------------------------------------------
+
+await test('the completion band names the unfinished work, with each task status', () => {
+  const fn = RENDER.slice(RENDER.indexOf('function heldOpenHtml'), RENDER.indexOf('function completionSummaryHtml'));
+  assert.match(fn, /holding this goal open/, 'it has to say what the tasks are doing, not merely list them');
+  assert.match(fn, /held__status/,
+    'the status is the surprising part — `completed` and `confirmed` still hold a goal open');
+  assert.match(fn, /#\/task\//, 'and each is reachable, so the next move is one click');
+});
+
+await test('it is SILENT when nothing is held, and on a closed goal', () => {
+  const fn = RENDER.slice(RENDER.indexOf('function heldOpenHtml'), RENDER.indexOf('function completionSummaryHtml'));
+  assert.match(fn, /if \(!openTasks \|\| !openTasks\.total \|\| g\.status !== 'open'\) return '';/,
+    'an empty "0 tasks" row on the common goal is noise, and this band renders on every goal');
+});
+
+await test('the summary line stops claiming criteria are the only thing left', () => {
+  const fn = RENDER.slice(RENDER.indexOf('function completionSummaryHtml'), RENDER.indexOf('function critListHtml'));
+  assert.match(fn, /const held = openTasks && openTasks\.total \? openTasks\.total : 0;/);
+  assert.match(fn, /still will not close while work is unfinished/,
+    'satisfied criteria plus an open goal is exactly the state that reads as a bug unexplained');
+  // The old sentence must survive for the case it is still true for.
+  assert.match(fn, /a criterion becomes confirmable once every task linked to it has shipped/);
+});
+
+await test('both the band and the full view are passed the open tasks', () => {
+  // A detail view that renders the summary WITHOUT them silently drops the
+  // explanation on the surface a builder opens to investigate.
+  const calls = RENDER.match(/completionSummaryHtml\(g, crit, sat, \d+, d\.criterionless_task_count, d\.open_tasks\)/g) || [];
+  assert.equal(calls.length, 2, 'the compact band and the full view');
+});
+
+// ---- 2. the archive two-step ------------------------------------------------
+
+await test('the Archive control appears only for someone who can manage an OPEN goal', () => {
+  const fn = RENDER.slice(RENDER.indexOf('function renderActions'), RENDER.indexOf('function archiveRowHtml'));
+  assert.match(fn, /if \(canManage && g\.status === 'open'\) \{/,
+    'a Xenos sees the state, not the control — the server enforces either way');
+  assert.match(fn, /id="goal-archive-btn"/);
+});
+
+await test('a goal holding NOTHING archives in one step, with an optional reason', () => {
+  const fn = RENDER.slice(RENDER.indexOf('async function openArchivePanel'), RENDER.indexOf('async function submitArchive'));
+  assert.match(fn, /held\.total === 0/, 'the common case must not become a two-step');
+  assert.match(fn, /Why \(optional\)/);
+  assert.match(fn, /reversible/, 'and say so — an archive that reads as permanent is one nobody uses');
+});
+
+await test('move targets exclude closed goals AND the goal being archived', () => {
+  const fn = RENDER.slice(RENDER.indexOf('async function openArchivePanel'), RENDER.indexOf('async function submitArchive'));
+  assert.match(fn, /o\.status === 'open' && !sameId\(o\.id, g\.id\)/,
+    'a closed goal takes no new work, and moving INTO the goal being archived is the silent discard renamed');
+});
+
+await test('every task needs a decision before the panel will submit', () => {
+  const fn = RENDER.slice(RENDER.indexOf('async function submitArchive'));
+  assert.match(fn, /undecided\.push\(id\)/);
+  assert.match(fn, /a decision: \$\{undecided\.map/, 'and the refusal names WHICH');
+  assert.match(fn, /if \(!reason\) return say\(/, 'an abandon without a reason is the silent discard D3 forbids');
+});
+
+await test('the client check is a courtesy — the server refusal is shown VERBATIM', () => {
+  const fn = RENDER.slice(RENDER.indexOf('async function submitArchive'));
+  assert.match(fn, /say\(\(e && e\.message\)/,
+    'the server knows things this panel does not — a task claimed since load, a target that just closed');
+  // A UI that believes it is the enforcement is how a second, drifting copy of a
+  // rule gets written — the panel's own header says so, above the flow.
+  const flow = RENDER.slice(RENDER.indexOf('// ---- BV1.R24: the archive two-step'));
+  assert.match(flow, /COURTESY, never the gate/);
+});
+
+await test('the disposition payload is exactly the shape the route validates', () => {
+  const fn = RENDER.slice(RENDER.indexOf('async function submitArchive'));
+  assert.match(fn, /\{ verb: 'abandon' \}/);
+  assert.match(fn, /\{ verb: 'move', goal_id: Number\(v\) \}/);
+  assert.match(fn, /body\.dispositions = dispositions;/);
+  // The route declares `reason` and `dispositions` and rejects anything else
+  // (ADR 0118), so an extra field here would 400 the whole call.
+  const sent = fn.slice(0, fn.indexOf('postJSON'));
+  assert.equal(/body\.(?!dispositions|reason)[a-z_]+ =/.test(sent), false, 'no field the route does not declare');
+});
+
+await test('archiving re-reads the goal rather than patching the page from the response', () => {
+  const fn = RENDER.slice(RENDER.indexOf('async function submitArchive'));
+  assert.match(fn, /loadDetail\(g\.id, \{ force: true \}\)/,
+    'the archive moved tasks between goals — a local patch would leave the page lying about both');
+});
+
+await test('the panel uses the page\'s own tokens, not colours of its own', () => {
+  const block = CSS.slice(CSS.indexOf('.arch-panel {'));
+  assert.equal(/#[0-9a-fA-F]{6}/.test(block.slice(0, block.indexOf('.arch-panel__err'))), false,
+    'a panel that announces itself is one people click by accident');
+  assert.match(CSS, /\.held-open \{/);
+  assert.match(CSS, /\.arch-row__verb \{/);
+});
+
+// ---- 3. it actually RENDERS ------------------------------------------------
+//
+// The assertions above prove the source contains the right strings. These run the
+// two pure builders and check the MARKUP — grammar, escaping, the overflow line,
+// and that no verb is preselected. A static regex passes just as happily on a
+// function that throws.
+
+const escapeHtmlFn = (x) => String(x).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+const fmtNumFn = (n) => String(n);
+const lift = (name, end, args, vals) => new Function(...args, `${RENDER.slice(RENDER.indexOf(`function ${name}`), RENDER.indexOf(end))}; return ${name};`)(...vals);
+const heldOpenHtml = lift('heldOpenHtml', 'function completionSummaryHtml', ['escapeHtml', 'fmtNum'], [escapeHtmlFn, fmtNumFn]);
+const archiveRowHtml = lift('archiveRowHtml', 'async function openArchivePanel', ['escapeHtml'], [escapeHtmlFn]);
+const OPEN = { status: 'open' };
+
+await test('RENDERS: a goal holding nothing produces no band at all', () => {
+  assert.equal(heldOpenHtml(OPEN, { total: 0, tasks: [] }), '');
+  assert.equal(heldOpenHtml(OPEN, null), '');
+});
+
+await test('RENDERS: an archived goal shows no band even while holding work', () => {
+  assert.equal(heldOpenHtml({ status: 'archived' }, { total: 3, tasks: [{ id: 1, title: 'x', status: 'ready' }] }), '');
+});
+
+await test('RENDERS: held tasks come out linked, status-tagged and ESCAPED', () => {
+  const html = heldOpenHtml(OPEN, { total: 2, tasks: [
+    { id: 1001, title: 'The <b>unescaped</b> one', status: 'confirmed' },
+    { id: 1002, title: 'second', status: 'ready' },
+  ] });
+  assert.match(html, /2 unfinished tasks are holding this goal open/);
+  assert.match(html, /#\/task\/1001/);
+  assert.match(html, /confirmed/, 'the mid-ship status is the surprising part and must show');
+  assert.doesNotMatch(html, /<b>unescaped<\/b>/, 'a task title is user input on a page everyone reads');
+  assert.match(html, /&lt;b&gt;/);
+});
+
+await test('RENDERS: the grammar is singular for one', () => {
+  const one = heldOpenHtml(OPEN, { total: 1, tasks: [{ id: 5, title: 'solo', status: 'active' }] });
+  assert.match(one, /1 unfinished task is holding this goal open/);
+});
+
+await test('RENDERS: a long list is capped and says how many are hidden', () => {
+  const many = heldOpenHtml(OPEN, { total: 30, tasks: Array.from({ length: 8 }, (_, i) => ({ id: i, title: 't', status: 'ready' })) });
+  assert.match(many, /and 22 more/, 'a truncated list that does not say it is truncated is a wrong answer');
+});
+
+await test('RENDERS: an archive row preselects NOTHING and offers each open goal', () => {
+  const row = archiveRowHtml({ id: 77, title: 'row', status: 'blocked' }, [{ id: 42, title: 'survivor' }]);
+  assert.match(row, /value="" selected/, 'a preselected verb is a decision nobody made');
+  assert.match(row, /value="abandon"/);
+  assert.match(row, /move → #42 survivor/);
+  assert.match(row, /data-task="77"/, 'the row carries its id, which is how the map is collected');
+});
+
+summary();

package/tests/government_require_permission.mjs

@@ -231,6 +231,13 @@ test('over the four seeded ranks, requirePermission admits exactly who requireRa
   const REPLACED_ARCHON = [
     'dependency.cross_tier.manage', 'gate_approval.decide',
     'task.confirm.grade_bypass', 'access_request.review',
+    // BV1.R21 (task 1003608): `version.create` RETURNED here. ADR 0157 had lowered it
+    // to metic on "authoring delegates, disposition does not"; ADR 0250 §6 amends that
+    // for this one key, because D1 makes the version boundary the scope gate and
+    // cutting a version is then the way AROUND the gate rather than authoring. Moving
+    // it back is an owner decision, which is exactly what this hand-written oracle
+    // exists to require — a floor that moved without one still reds the build.
+    'version.create',
   ];
   // ADR 0157 (owner decision, 2026-08-05) — "the Archon rank is responsible for rank and
   // identity only". Each of these replaced a requireRank('archon') gate in R104/R105 and
@@ -249,9 +256,6 @@ test('over the four seeded ranks, requirePermission admits exactly who requireRa
     'task.peer_votes.tally', 'override_request.decide', 'memory.read.any',
     'project.curate', 'provisioning.fleet.manage', 'security.report.adjudicate',
     'session.search',
-    // Minted by R105 (POST /versions had no atom); ADR 0157 then lowered it to metic.
-    // Its sibling `version.close` stayed archon — authoring delegates, disposition does not.
-    'version.create',
     // Minted BY ADR 0157, splitting the Gate page's READ off `gate_approval.decide` so a
     // Metic can open /gate while approving a held PR stays Archon.
     'gate_approval.read',

package/tests/government_seed.mjs

@@ -74,6 +74,53 @@ function grantBlocksForRole(role) {
   return blocks;
 }
 
+// REVOCATIONS (BV1.R21, task 1003608). The union model below was append-only, and
+// the guard said in advance what would happen if that stopped being true: "A
+// future migration that REVOKES (raising a floor) would make the union overstate
+// what the DB holds." `government_012_version_create_archon.sql` is the first one
+// — ADR 0250 §6 raises `version.create` back to the Archon floor, reversing the
+// ADR 0157 delegation — so the model now subtracts.
+//
+// Matches BOTH table spellings on purpose. The old revoke-detector watched only
+// `governance_role_permissions`, but government_001_rename_from_governance renamed
+// it to `government_rank_permissions` with no shim, so a DELETE written against
+// the CURRENT table name would have sailed straight past the tripwire that exists
+// to catch exactly this. A guard that only recognises the historical spelling is
+// not a guard.
+const REVOKE_RE =
+  /DELETE\s+FROM\s+govern(?:ance_role|ment_rank)_permissions\s+WHERE\s+(?:rank_key|role_key)\s*=\s*'([^']+)'\s+AND\s+permission_key\s*=\s*'([^']+)'/gi;
+
+function revokeBlocksForRole(role) {
+  const blocks = [];
+  for (const [file, sql] of grantSqlByFile) {
+    const code = sql.replace(/--[^\n]*/g, '');
+    for (const m of code.matchAll(new RegExp(REVOKE_RE.source, 'gi'))) {
+      if (m[1] === role) blocks.push({ file, key: m[2] });
+    }
+  }
+  return blocks;
+}
+
+// The EFFECTIVE grant set: walk the migrations in filename order, adding each
+// file's grants and removing its revocations, so a key granted early and revoked
+// later ends up absent — and one revoked and then deliberately re-granted ends up
+// present. A set-difference over the whole union would get the first case right
+// and the second silently wrong.
+function effectiveKeysForRole(role) {
+  const grantRe = new RegExp(`SELECT '${role}', unnest\\(ARRAY\\[([\\s\\S]*?)\\]\\)`, 'g');
+  const held = new Set();
+  for (const [, sql] of grantSqlByFile) {
+    const code = sql.replace(/--[^\n]*/g, '');
+    for (const m of code.matchAll(grantRe)) {
+      for (const k of [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1])) held.add(RENAMED_KEYS.get(k) || k);
+    }
+    for (const m of code.matchAll(new RegExp(REVOKE_RE.source, 'gi'))) {
+      if (m[1] === role) held.delete(RENAMED_KEYS.get(m[2]) || m[2]);
+    }
+  }
+  return held;
+}
+
 test('the union of every grant migration matches RANK_SEED exactly (no drift)', () => {
   for (const role of RANK_ORDER) {
     const blocks = grantBlocksForRole(role);
@@ -82,26 +129,64 @@ test('the union of every grant migration matches RANK_SEED exactly (no drift)',
       assert.equal(b.keys.length, new Set(b.keys).size, `${role}: duplicate permission in the ${b.file} array`);
     }
     const granted = applyRenames(blocks.flatMap((b) => b.keys));
+    // The EFFECTIVE set — grants minus revocations, applied in file order. Since
+    // BV1.R21 (task 1003608) this is no longer the same thing as the union of the
+    // INSERTs: `version.create` is granted to metic by governance_007 and taken
+    // back by government_012.
+    const effective = effectiveKeysForRole(role);
     // set-equality (order in SQL is illustrative; the grant set is what matters)
-    assert.deepEqual(new Set(granted), new Set(RANK_SEED[role]),
+    assert.deepEqual(effective, new Set(RANK_SEED[role]),
       `${role}: grant migrations drift from catalog RANK_SEED`);
     // no key re-granted in a LATER migration (a no-op INSERT that muddies the ledger)
     assert.equal(granted.length, new Set(granted).size, `${role}: the same permission is granted twice across migrations`);
-    assert.equal(new Set(granted).size, RANK_SEED[role].length, `${role}: grant count mismatch`);
+    assert.equal(effective.size, RANK_SEED[role].length, `${role}: grant count mismatch`);
   }
 });
 
-// The union model above is only faithful while grant migrations are ADDITIVE. A future
-// migration that REVOKES (raising a floor) would make the union overstate what the DB
-// holds, so fail loudly here rather than let the guard quietly go wrong.
-test('no grant migration revokes — the union model stays faithful', () => {
+// This test used to assert that NO migration revokes, with the note: "teach
+// grantBlocksForRole to subtract before allowing this". BV1.R21 (task 1003608) is
+// the first revocation and the subtraction is now taught, so the tripwire becomes
+// its own follow-through: every DELETE in a grant migration must be in the exact
+// shape effectiveKeysForRole can read. A revoke the model cannot parse is worse
+// than one it forbids — it would leave the union overstating the DB while every
+// test stayed green, which is the failure the original note was written to avoid.
+test('every revoking migration is in the shape the union model subtracts', () => {
   for (const [file, sql] of grantSqlByFile) {
     const code = sql.replace(/--[^\n]*/g, '');
-    assert.ok(!/DELETE\s+FROM\s+governance_role_permissions/i.test(code),
-      `${file} revokes a grant — teach grantBlocksForRole to subtract before allowing this`);
+    // Only DELETEs against the PERMISSION tables matter here. A migration may
+    // legitimately delete from the ASSIGNMENT tables — governance_005 re-syncs
+    // `governance_builder_roles`, which is who holds a rank, not what a rank
+    // holds — and that has nothing to do with the grant union.
+    const deletes = [...code.matchAll(/DELETE\s+FROM\s+(govern(?:ance_role|ment_rank)_permissions)\b/gi)];
+    if (deletes.length === 0) continue;
+    const parsed = [...code.matchAll(new RegExp(REVOKE_RE.source, 'gi'))];
+    assert.equal(parsed.length, deletes.length,
+      `${file}: ${deletes.length} DELETE(s) but only ${parsed.length} parseable by REVOKE_RE — `
+      + 'the union model would silently overstate the grant set. Match the '
+      + "`DELETE FROM government_rank_permissions WHERE rank_key = '…' AND permission_key = '…'` shape.");
+    for (const m of parsed) {
+      assert.ok(RANK_ORDER.includes(m[1]), `${file}: revokes from unknown rank '${m[1]}'`);
+    }
   }
 });
 
+test('a revocation actually removes the key from the effective set', () => {
+  // The specific fact BV1.R21 turned on, asserted directly rather than only as a
+  // consequence of the drift comparison: governance_007 grants `version.create`
+  // to metic, government_012 takes it back, and the effective set must not hold
+  // it — while archon, which was granted it by governance_006, keeps it.
+  assert.equal(effectiveKeysForRole('metic').has('version.create'), false,
+    'ADR 0250 §6 raised version.create to the archon floor — a metic grant row would make that floor decorative');
+  assert.equal(effectiveKeysForRole('archon').has('version.create'), true,
+    'archon must still hold it, or POST /versions is unreachable by anyone');
+  // …and the raw union still CONTAINS it, which is the whole reason the model
+  // needed to change: if this ever stops being true the revoke migration was
+  // edited away rather than superseded.
+  const rawUnion = applyRenames(grantBlocksForRole('metic').flatMap((b) => b.keys));
+  assert.ok(rawUnion.includes('version.create'),
+    'the historical grant must remain in governance_007 — migrations are run-once and are never rewritten');
+});
+
 test('the seed inserts exactly the four seeded rank-roles', () => {
   const roleRows = [...seedSql.matchAll(/\('(xenos|thetes|metic|archon)',\s*'[^']+',/g)].map((m) => m[1]);
   assert.deepEqual(new Set(roleRows), new Set(RANK_ORDER));
@@ -140,7 +225,14 @@ test('later grant migrations are idempotent + transactional', () => {
     const code = stripComments(sql);
     const inserts = code.match(/INSERT INTO/g) || [];
     const onConflict = code.match(/ON CONFLICT/g) || [];
-    assert.ok(inserts.length > 0, `${file}: a grant migration must INSERT something`);
+    const revokes = [...code.matchAll(new RegExp(REVOKE_RE.source, 'gi'))];
+    // A migration must DO something to the grant set — but since BV1.R21 (task
+    // 1003608) "something" includes taking a permission away, not only adding
+    // one. A REVOKE-only migration inserts nothing by design and needs no ON
+    // CONFLICT: deleting a row that is not there affects zero rows and raises
+    // nothing, so it is already naturally re-runnable.
+    assert.ok(inserts.length > 0 || revokes.length > 0,
+      `${file}: a grant migration must INSERT or REVOKE something`);
     assert.equal(inserts.length, onConflict.length, `${file}: every INSERT must be ON CONFLICT DO NOTHING`);
     assert.ok(/BEGIN;/.test(code) && /COMMIT;/.test(code), `${file}: must be transactional`);
   }