@bongos/core 1.18.3 → 1.18.18

package/tests/governance_page_gates.mjs

@@ -0,0 +1,324 @@
+// tests/governance_page_gates.mjs — the three HTML PAGE GATES + the wandering
+// CEILING, re-expressed on the governance model (BV1.R107, ADR 0151).
+//
+// DB-free. Two doubles, both installed the way the existing suites do it:
+//   • db-kernel.lookupSession is stubbed BEFORE auth.js is required, because
+//     auth.js destructures it at load time (tests/auth_page_gate.mjs precedent).
+//   • the `governance` KERNEL PORT is a seam stub, so the gates' authority half
+//     needs no Postgres, no router, no live module
+//     (tests/governance_require_permission.mjs precedent).
+//
+// WHAT THIS FILE HAS TO PROVE, and why the oracles are split.
+//   A page gate that resolves its audience from catalog.floor cannot be checked
+//   against catalog.floor — a wrong floor would move both sides together and the
+//   test would pass while proving nothing. So the expected audience below is a
+//   HAND-WRITTEN LITERAL of the PRE-R107 behaviour (read off the deleted rank
+//   tests: "any session" / "rank !== 'xenos'" / "rank === 'archon'"), and it is
+//   independently cross-checked against auth.rankMeetsThreshold — the real
+//   production threshold function, which knows nothing about the catalog.
+//   The permission SEED fed to the stub is the real catalog seed, i.e. the rows a
+//   builder actually holds; that is the INPUT, not the oracle, so a floor edit
+//   reds this file instead of hiding in it.
+//
+//   The second property is shape, not audience: a page gate must REDIRECT. These
+//   are page navigations and asset loads — a JSON 403 renders as a blank error
+//   body instead of sending the visitor somewhere they can act. res.fail() is
+//   installed on the response double precisely so a regression to JSON shows up
+//   as an assertion rather than a TypeError.
+//
+// Run:  node --test tests/governance_page_gates.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// --- the session double, installed before auth.js loads ---------------------
+const dbKernel = require('../src/bongos/db-kernel.js');
+let nextSession = null;
+let lookupThrows = false;
+dbKernel.lookupSession = async () => {
+  if (lookupThrows) throw new Error('simulated db outage');
+  return nextSession;
+};
+
+const auth = require('../src/bongos/auth.js');
+const seams = require('../src/module-seams.js');
+const catalog = require('../modules/governance/catalog.js');
+const resolver = require('../modules/governance/resolver.js');
+const wandering = require('../modules/builder-settings/wandering-prefs.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const GATES = ['requireBuilderPage', 'requireNonXenosPage', 'requireArchonPage'];
+const LIVE_RANKS = ['xenos', 'thetes', 'metic', 'archon'];
+
+// ═══ the ORACLE — hand-written, from the rank tests R107 deleted ═════════════
+// requireBuilderPage  admitted any session at all       → every live rank
+// requireNonXenosPage admitted rank !== 'xenos'         → thetes and up
+// requireArchonPage   admitted rank === 'archon'        → archon only
+const PRE_R107_AUDIENCE = {
+  requireBuilderPage: { xenos: true, thetes: true, metic: true, archon: true },
+  requireNonXenosPage: { xenos: false, thetes: true, metic: true, archon: true },
+  requireArchonPage: { xenos: false, thetes: false, metic: false, archon: true },
+};
+// Where a SIGNED-IN builder who fails the gate is sent. Never the sign-in flow —
+// they already have a session, so that would loop.
+const DENIED_TO = {
+  requireBuilderPage: '/builders',
+  requireNonXenosPage: '/builders/not-ready',
+  requireArchonPage: '/builders',
+};
+// The equivalent rank floor, for the independent cross-check below.
+const GATE_FLOOR = {
+  requireBuilderPage: 'xenos',
+  requireNonXenosPage: 'thetes',
+  requireArchonPage: 'archon',
+};
+const SIGN_IN = '/api/gds/auth/web/start';
+
+// --- doubles ----------------------------------------------------------------
+function fakeRes() {
+  const res = {
+    _status: null,
+    _json: null,
+    _redirect: null,
+    status(c) { this._status = c; return this; },
+    json(body) { this._json = body; return this; },
+    redirect(a, b) {
+      this._redirect = b === undefined ? { code: 302, loc: a } : { code: a, loc: b };
+      return this;
+    },
+    end() { return this; },
+  };
+  // Installed so a regression that answers JSON instead of redirecting is caught
+  // by an assertion rather than blowing up on an undefined method.
+  attachFail({}, res, () => {});
+  return res;
+}
+
+// Run one page gate. `rank` null = no session. `resolve` overrides the stubbed
+// port (pass null to leave the port UNREGISTERED).
+async function runGate(name, { rank = null, resolve, port = true } = {}) {
+  nextSession = rank === null ? null : { builder_id: 7, rank };
+  lookupThrows = false;
+  seams._reset();
+  if (port) {
+    seams.registerProvider('governance', {
+      // The real seed for that rank — the rows governance_002 gives the one
+      // rank-role a builder holds. The INPUT, not the oracle.
+      resolveBuilderPermissions: resolve || (async () => catalog.seedForRank(rank)),
+    });
+  }
+  const req = { headers: rank === null ? {} : { cookie: 'gds_session=validtoken' } };
+  const res = fakeRes();
+  let nexted = false;
+  await auth[name](req, res, () => { nexted = true; });
+  seams._reset();
+  return { res, nexted };
+}
+
+// ═══ PART A — the audience is unchanged, rank by rank ════════════════════════
+
+test('A0: the hand-written audience table agrees with the real threshold function', () => {
+  // A second, catalog-free oracle for the literal above: auth.rankMeetsThreshold
+  // is the production rank predicate and reads nothing from modules/governance/.
+  for (const gate of GATES) {
+    for (const rank of LIVE_RANKS) {
+      assert.equal(
+        PRE_R107_AUDIENCE[gate][rank],
+        auth.rankMeetsThreshold(rank, [GATE_FLOOR[gate]]),
+        `${gate}/${rank}: the literal audience must match rankMeetsThreshold at floor ${GATE_FLOOR[gate]}`,
+      );
+    }
+  }
+});
+
+test('A1: each page gate admits exactly the ranks it admitted before R107', async () => {
+  const drift = [];
+  for (const gate of GATES) {
+    for (const rank of LIVE_RANKS) {
+      const { nexted } = await runGate(gate, { rank });
+      const expected = PRE_R107_AUDIENCE[gate][rank];
+      if (nexted !== expected) {
+        drift.push(`  ${gate} / ${rank}: was ${expected ? 'ADMIT' : 'deny'}, now ${nexted ? 'ADMIT' : 'deny'}`);
+      }
+    }
+  }
+  assert.equal(drift.length, 0, `a page gate's audience changed:\n${drift.join('\n')}`);
+});
+
+test('A2: a denied SIGNED-IN builder is redirected to an ungated page, not JSON-403ed', async () => {
+  for (const gate of GATES) {
+    for (const rank of LIVE_RANKS) {
+      if (PRE_R107_AUDIENCE[gate][rank]) continue;
+      const { res, nexted } = await runGate(gate, { rank });
+      assert.equal(nexted, false, `${gate}/${rank} must not admit`);
+      assert.deepEqual(res._redirect, { code: 302, loc: DENIED_TO[gate] },
+        `${gate}/${rank} must 302 to ${DENIED_TO[gate]}`);
+      assert.equal(res._status, null, `${gate}/${rank} must not set an HTTP error status`);
+      assert.equal(res._json, null, `${gate}/${rank} must not answer a JSON body`);
+      assert.notEqual(res._redirect.loc, SIGN_IN,
+        `${gate}/${rank}: a signed-in builder must never be bounced to sign-in (it loops)`);
+    }
+  }
+});
+
+test('A3: an UNAUTHENTICATED request redirects into sign-in — never a JSON 401/403', async () => {
+  for (const gate of GATES) {
+    const { res, nexted } = await runGate(gate, { rank: null });
+    assert.equal(nexted, false, `${gate} must not admit an unauthenticated request`);
+    assert.equal(res._redirect.code, 302, `${gate} must 302`);
+    assert.equal(res._redirect.loc, SIGN_IN, `${gate} must send an anonymous visitor to sign-in`);
+    assert.equal(res._status, null, `${gate} must not set an HTTP error status`);
+    assert.equal(res._json, null, `${gate} must not answer a JSON body`);
+  }
+});
+
+// ═══ PART B — fail-closed, in every direction (ADR 0016) ═════════════════════
+
+test('B1: a session-lookup error fails CLOSED (redirect to sign-in, no page)', async () => {
+  for (const gate of GATES) {
+    nextSession = null;
+    seams._reset();
+    seams.registerProvider('governance', { resolveBuilderPermissions: async () => catalog.seedForRank('archon') });
+    lookupThrows = true;
+    const res = fakeRes();
+    let nexted = false;
+    await auth[gate]({ headers: { cookie: 'gds_session=validtoken' } }, res, () => { nexted = true; });
+    lookupThrows = false;
+    seams._reset();
+    assert.equal(nexted, false, `${gate} must not serve the page when the lookup errors`);
+    assert.equal(res._redirect.loc, SIGN_IN, `${gate} must redirect to sign-in on a lookup error`);
+  }
+});
+
+test('B2: an UNREGISTERED governance port denies every gate, it does not admit', async () => {
+  // Same deliberate call requirePermission makes: no port = authority cannot be
+  // established, and admitting there would make disabling a module an escalation.
+  for (const gate of GATES) {
+    const { res, nexted } = await runGate(gate, { rank: 'archon', port: false });
+    assert.equal(nexted, false, `${gate}: a missing authority system must never open a page gate`);
+    assert.equal(res._redirect.loc, DENIED_TO[gate]);
+    assert.equal(res._json, null);
+  }
+});
+
+test('B3: a throwing resolver denies (a DB blip must not open the page)', async () => {
+  for (const gate of GATES) {
+    const { res, nexted } = await runGate(gate, {
+      rank: 'archon',
+      resolve: async () => { throw new Error('connection terminated'); },
+    });
+    assert.equal(nexted, false, `${gate} must fail CLOSED on a resolve failure`);
+    assert.equal(res._redirect.loc, DENIED_TO[gate]);
+  }
+});
+
+test('B4: the page gates resolve per request — no memoised authority (ADR 0016)', async () => {
+  let calls = 0;
+  let keys = catalog.seedForRank('archon');
+  nextSession = { builder_id: 7, rank: 'archon' };
+  lookupThrows = false;
+  seams._reset();
+  seams.registerProvider('governance', {
+    resolveBuilderPermissions: async () => { calls += 1; return keys; },
+  });
+  const req = { headers: { cookie: 'gds_session=validtoken' } };
+  let admitted = false;
+  await auth.requireArchonPage(req, fakeRes(), () => { admitted = true; });
+  assert.equal(admitted, true, 'an Archon should reach the page');
+  keys = []; // the role is revoked between requests
+  const second = fakeRes();
+  let admittedAgain = false;
+  await auth.requireArchonPage(req, second, () => { admittedAgain = true; });
+  seams._reset();
+  assert.equal(calls, 2, 'the resolver must be consulted on every request');
+  assert.equal(admittedAgain, false, 'a revoked role must deny on the very next request');
+  assert.equal(second._redirect.loc, '/builders');
+});
+
+test('B5: every permission a page gate names is a real catalog key', async () => {
+  // Not an oracle — a sanity check that the gates did not migrate onto a typo,
+  // which would silently deny everyone (fail-closed, but a bug all the same).
+  for (const key of ['page.view.public', 'page.view.builder', 'page.view.governance']) {
+    assert.ok(catalog.byKey(key), `${key} must exist in the catalog`);
+  }
+});
+
+// ═══ PART C — the wandering CEILING (role metadata, not a permission) ════════
+// The ceiling is a NUMBER, so it is carried as role metadata rather than as one
+// boolean atom per level. This part pins the values against a hand-written table
+// and proves the clamp is enforcement, not UI copy.
+
+const CEILING_TABLE = {
+  xenos: { default: 0, ceiling: 0 },
+  thetes: { default: 1, ceiling: 1 },
+  metic: { default: 2, ceiling: 3 },
+  archon: { default: 3, ceiling: 3 },
+};
+
+test('C1: the per-role wandering default + ceiling are unchanged', () => {
+  for (const [role, expected] of Object.entries(CEILING_TABLE)) {
+    assert.equal(wandering.defaultLevelForRank(role), expected.default, `${role} default`);
+    assert.equal(wandering.maxLevelForRank(role), expected.ceiling, `${role} ceiling`);
+    assert.deepEqual(
+      { default: wandering.roleWandering(role).default, ceiling: wandering.roleWandering(role).ceiling },
+      expected,
+      `${role} role metadata`,
+    );
+  }
+});
+
+test('C2: a role carrying no wandering metadata falls to the Locked floor', () => {
+  for (const unknown of ['helot', 'olympian', 'nobody', undefined, null, '']) {
+    assert.equal(wandering.defaultLevelForRank(unknown), 0, `default for ${String(unknown)}`);
+    assert.equal(wandering.maxLevelForRank(unknown), 0, `ceiling for ${String(unknown)}`);
+  }
+});
+
+test('C3: a builder cannot raise their OWN level above their role ceiling', () => {
+  // The clamp is the enforcement point: a stored override above the ceiling
+  // resolves DOWN, so opening the setting to self-service stays safe.
+  for (const [role, expected] of Object.entries(CEILING_TABLE)) {
+    for (let want = 0; want <= 3; want += 1) {
+      assert.equal(
+        wandering.effectiveLevel({ wandering: want }, role),
+        Math.min(want, expected.ceiling),
+        `${role} storing ${want} must resolve to at most ${expected.ceiling}`,
+      );
+    }
+  }
+  // And the write path refuses rather than silently clamping.
+  const capped = wandering.validatePatch({ wandering: 3 }, { maxLevel: wandering.maxLevelForRank('thetes') });
+  assert.equal(capped.ok, false, 'a Thetes asking for Exploratory must be refused');
+  assert.equal(capped.errors[0].error, 'above_rank_cap');
+  assert.equal(capped.errors[0].max, 1);
+  assert.equal(
+    wandering.validatePatch({ wandering: 1 }, { maxLevel: wandering.maxLevelForRank('thetes') }).ok,
+    true,
+    'their own ceiling is still writable',
+  );
+});
+
+test('C4: the ceiling is NOT answerable through the boolean permission axis', () => {
+  // me.wandering.set is ownership-scoped (R100), so "do you hold it" has no
+  // unconditional answer and builderHasPermissions REFUSES it. That refusal is
+  // exactly why the numeric ceiling had to be role metadata: there is no boolean
+  // question whose answer is "3".
+  const perm = catalog.byKey('me.wandering.set');
+  assert.equal(perm.scope, 'own', 'me.wandering.set is ownership-scoped');
+  assert.equal(perm.resource, 'builder_prefs');
+  assert.equal(catalog.isOwnershipScoped('me.wandering.set'), true);
+  return resolver.builderHasPermissions(7, ['me.wandering.set']).then((answer) => {
+    assert.equal(answer, false, 'an ownership-scoped key must be refused by the unconditional resolve');
+  });
+});
+
+test('C5: the derived rank projections cannot drift from the role metadata', () => {
+  for (const [role, meta] of Object.entries(wandering.ROLE_WANDERING)) {
+    assert.equal(wandering.RANK_DEFAULT[role], meta.default, `RANK_DEFAULT.${role}`);
+    assert.equal(wandering.RANK_MAX[role], meta.ceiling, `RANK_MAX.${role}`);
+    assert.ok(meta.default <= meta.ceiling, `${role}: default must not exceed the ceiling`);
+  }
+});

package/tests/governance_parity.mjs

@@ -0,0 +1,336 @@
+// tests/governance_parity.mjs — the compat-seed PARITY proof (BV1.R103, ADR 0151).
+//
+// The promise the whole governance cutover rests on: once governance_002 seeds the
+// four rank-roles and backfills every builder the role matching their rank, each
+// builder holds EXACTLY the powers requireRank gave them — no more, no less.
+//
+// "Today's exact powers" has TWO independent halves, and this file proves each
+// against a DIFFERENT oracle. That split is the point — a check whose two sides
+// both read catalog.floor cannot fail, because a wrong floor moves both together.
+//
+//   PART A — the DERIVATION. Does seedForRank's own tier arithmetic reproduce the
+//     REAL production gate, auth.rankMeetsThreshold, over the REAL 16-rank ladder
+//     (db-kernel RANKS)? Oracle: auth.js. Catches a divergence between catalog.js's
+//     private 4-entry RANK_ORDER and the ladder the live system actually enforces,
+//     a flipped comparison, or a seed that stops being a threshold predicate.
+//     Does NOT catch a wrong floor VALUE (both sides read it) — that is Part B.
+//   PART B — the FLOOR VALUES. Is each permission's floor consistent with the rank
+//     gate its route actually carries? Oracle: the live route SOURCE, read through
+//     route-rank-check.js (the grader's own classifier). This is the half that goes
+//     red if someone quietly lowers a floor. BV1.R109 taught that classifier to read
+//     `requirePermission` gates too — and it resolves those THROUGH catalog.floor, so
+//     a migrated route can no longer serve as B1's independent oracle. Migrated routes
+//     move to B3 (which atom does the route name?) and B2's census spans both, so the
+//     R104-R107 migration shifts coverage between oracles instead of erasing it.
+//   PART C — the two REAL middlewares, requirePermission vs requireRank, over the
+//     whole catalog rather than the four hand-picked keys in
+//     tests/governance_require_permission.mjs.
+//   PART D — the deliberate fail-closed divergence governance_002 documents.
+//
+// A third oracle already exists and is NOT duplicated here: tests/governance_seed.mjs
+// pins the catalog against the materialised migration SQL, so a floor edit that
+// reaches no new migration reds there.
+//
+// SCOPE — read before trusting this file.
+//   PROVEN (DB-free, so it always runs in the unit gate): the STRUCTURAL parity.
+//     governance_002's backfill joins builders.rank → governance_roles.role_key, so
+//     every live builder holds exactly one rank-role and "what builder X resolves
+//     to" is fully determined by X's rank. Rank-by-rank parity is therefore the
+//     whole of "no more, no less" — enumerating rows would re-assert it per builder.
+//   NOT PROVEN here: that the LIVE roster contains no builder sitting on a rank
+//     OUTSIDE the four seeded ones. builders.rank's CHECK (migrations/023) still
+//     admits twelve legacy/divine ranks; such a builder resolves to ZERO permissions
+//     (asserted in Part D as the deliberate fail-closed divergence) while requireRank
+//     still admits the divine ones. Confirming the live roster needs Postgres and is
+//     left to R114's live demo.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const auth = require(path.join(ROOT, 'src', 'bongos', 'auth.js'));
+const { RANKS } = require(path.join(ROOT, 'src', 'bongos', 'db-kernel.js'));
+const routeRank = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+const resolver = require(path.join(ROOT, 'modules', 'governance', 'resolver.js'));
+
+const { PERMISSIONS, RANK_ORDER, seedForRank } = catalog;
+const FLOORED = PERMISSIONS.filter((p) => p.floor !== null);
+const PRINCIPALS = PERMISSIONS.filter((p) => p.floor === null);
+// Every rank builders.rank may legally hold, minus the four that get a seeded role.
+const UNSEEDED_RANKS = RANKS.filter((r) => !RANK_ORDER.includes(r));
+
+// What a builder of `rank` actually resolves to today: the REAL resolver's pure
+// core over the REAL seed — i.e. exactly the grant rows governance_002 gives the
+// one rank-role that builder's backfill assigns them.
+const resolvedFor = (rank) => resolver.effectivePermissions(seedForRank(rank));
+
+// What today's rank gates admit for `rank`: a permission's `floor` IS the floor its
+// route spells, so the live verdict is rankMeetsThreshold(rank, [floor]).
+const admits = (rank, floor) => auth.rankMeetsThreshold(rank, [floor]);
+
+// Failure messages must name the drifting key + rank — a parity test that fails with
+// deepEqual on two 71-element arrays is useless when you are trying to ship.
+const nameDrift = (rows) => rows.map(({ rank, key, floor, held, allowed }) =>
+  `  ${rank.padEnd(9)} ${key} (floor ${floor}): seed ${held ? 'GRANTS' : 'withholds'} it, requireRank ${allowed ? 'ADMITS' : 'denies'}`,
+).join('\n');
+
+// ═══ PART A — the derivation, against auth.rankMeetsThreshold ═════════════════
+// Both sides read p.floor, so these prove the DERIVATION is faithful to the live
+// threshold function, not that any individual floor is the right value (Part B).
+
+// The security direction: a seed that grants where the rank gate denies is an
+// escalation, so this runs over every rank builders.rank can legally hold.
+test('A1: no rank resolves to a permission the real threshold function would DENY', () => {
+  const drift = [];
+  for (const rank of RANKS) {
+    const held = new Set(resolvedFor(rank));
+    for (const p of FLOORED) {
+      if (held.has(p.key) && !admits(rank, p.floor)) {
+        drift.push({ rank, key: p.key, floor: p.floor, held: true, allowed: false });
+      }
+    }
+  }
+  assert.equal(drift.length, 0, `the seed GRANTS power requireRank denies (escalation):\n${nameDrift(drift)}`);
+});
+
+// The regression direction: a builder losing a power they hold today.
+test('A2: every seeded rank resolves to every permission the real threshold ADMITS', () => {
+  const drift = [];
+  for (const rank of RANK_ORDER) {
+    const held = new Set(resolvedFor(rank));
+    for (const p of FLOORED) {
+      if (!held.has(p.key) && admits(rank, p.floor)) {
+        drift.push({ rank, key: p.key, floor: p.floor, held: false, allowed: true });
+      }
+    }
+  }
+  assert.equal(drift.length, 0, `the seed WITHHOLDS power requireRank grants (regression):\n${nameDrift(drift)}`);
+});
+
+test('A3: each seeded rank\'s resolved set EQUALS its threshold set exactly, with a readable diff', () => {
+  for (const rank of RANK_ORDER) {
+    const held = resolvedFor(rank);
+    const expected = FLOORED.filter((p) => admits(rank, p.floor)).map((p) => p.key).sort();
+    const heldSet = new Set(held);
+    const expectedSet = new Set(expected);
+    assert.deepEqual(
+      { rank, extra: held.filter((k) => !expectedSet.has(k)), missing: expected.filter((k) => !heldSet.has(k)) },
+      { rank, extra: [], missing: [] },
+      `${rank}: resolved set diverges from what requireRank admits`,
+    );
+    assert.equal(held.length, expected.length, `${rank}: holds ${held.length}, gate admits ${expected.length}`);
+  }
+});
+
+// Routes spell the gate cumulatively — requireRank('metic','archon') — while the
+// catalog stores one floor. Threshold semantics make those identical; asserting it
+// over the whole catalog and the whole ladder makes the catalog's compression
+// provably information-preserving rather than merely conventional.
+test('A4: a single floor reproduces the cumulative requireRank(...) spelling exactly', () => {
+  for (const p of FLOORED) {
+    const cumulative = RANK_ORDER.slice(RANK_ORDER.indexOf(p.floor));
+    for (const rank of RANKS) {
+      assert.equal(auth.rankMeetsThreshold(rank, [p.floor]), auth.rankMeetsThreshold(rank, cumulative),
+        `${p.key}: floor '${p.floor}' and spelling (${cumulative.join(',')}) disagree for rank ${rank}`);
+    }
+  }
+});
+
+test('A5: every principal permission (floor null) is held by NO rank on the whole ladder', () => {
+  assert.ok(PRINCIPALS.length > 0, 'the catalog should define at least one principal permission');
+  for (const rank of RANKS) {
+    const held = new Set(resolvedFor(rank));
+    for (const p of PRINCIPALS) {
+      assert.equal(held.has(p.key), false, `${rank} must not hold principal ${p.key} (gated on system_role, never a rank)`);
+    }
+  }
+});
+
+// ═══ PART B — the floor VALUES, against the live route source ═════════════════
+// The independent oracle. route-rank-check.js is the grader's own classifier: it
+// reads src/bongos/routes/ + modules/*/routes/ and reports the rank middleware each
+// route actually carries. Cross-referencing it with each permission's `guards` note
+// pins the floor to the code that enforces it, so lowering a floor reds the build.
+
+const normRoute = (key) => key.replace(/:[A-Za-z0-9_]+/g, ':p'); // :id vs :criterionId
+// Leading `METHOD /path` of a guards note. Deliberately conservative: a note that
+// lists several routes or wraps them in prose/braces simply doesn't participate.
+const GUARD_ROUTE_RE = /^(GET|POST|PATCH|PUT|DELETE)\s+(\/[^\s,(]+)/;
+// A route's middleware rank → the LOOSEST floor still consistent with it. Only the
+// two rank-gated classifications constrain a floor; 'any-builder' / 'public' /
+// 'unknown' / 'bfg-principal' carry no rank middleware to compare against.
+const MIN_FLOOR_FOR_ROUTE = { archon: 'archon', 'metic+archon': 'metic' };
+
+function liveRoutes() {
+  const map = new Map();
+  for (const f of routeRank.discoverRouteFiles()) {
+    for (const r of routeRank.classifyText(fs.readFileSync(f.abs, 'utf8'))) map.set(normRoute(r.key), r);
+  }
+  return map;
+}
+
+// The cross-reference, split by WHICH ORACLE a route can still serve (BV1.R109).
+//
+//   floorPinned — the route carries a RANK middleware. Its classification is
+//     independent of catalog.floor, so comparing the two is a real check (B1).
+//   atomPinned  — the route has migrated to requirePermission (R104-R107). Its
+//     classification is DERIVED from catalog.floor via the catalog, so a floor
+//     comparison would move both sides together and prove nothing. Such a route is
+//     therefore dropped from B1 and checked by B3 instead, on the property that IS
+//     still independent: the atom the route names must be the permission whose
+//     guards note points at that route.
+function crossReference() {
+  const live = liveRoutes();
+  const floorPinned = [];
+  const atomPinned = [];
+  for (const p of FLOORED) {
+    const m = GUARD_ROUTE_RE.exec(p.guards);
+    if (!m) continue;
+    const routeKey = `${m[1]} ${m[2]}`;
+    const r = live.get(normRoute(routeKey));
+    if (!r) continue;
+    if (r.perms) {
+      atomPinned.push({ permission: p.key, floor: p.floor, routeKey, perms: r.perms });
+      continue;
+    }
+    const minFloor = MIN_FLOOR_FOR_ROUTE[r.rank];
+    if (!minFloor) continue;
+    floorPinned.push({ permission: p.key, floor: p.floor, routeKey, routeRank: r.rank, minFloor });
+  }
+  return { floorPinned, atomPinned };
+}
+
+// ONE-DIRECTIONAL, and deliberately so. A floor STRICTER than the route middleware
+// is legitimate and common: the wall lives in the handler (task.confirm.grade_bypass
+// on an any-builder POST /tasks/:id/confirm; goal.manage.own's owner|manager check;
+// box.source.full's boxScopeForRank). A floor LOOSER than the middleware is never
+// legitimate — it would tell the governance tab a permission is delegable below the
+// rank the route in fact demands.
+test('B1: no permission floor is LOOSER than the rank gate its route actually carries', () => {
+  const { floorPinned } = crossReference();
+  const violations = floorPinned
+    .filter((r) => RANK_ORDER.indexOf(r.floor) < RANK_ORDER.indexOf(r.minFloor))
+    .map((r) => `  ${r.permission}: floor '${r.floor}' but ${r.routeKey} gates at '${r.routeRank}' (needs '${r.minFloor}'+)`);
+  assert.equal(violations.length, 0,
+    `catalog floors are looser than the live routes enforce:\n${violations.join('\n')}`);
+});
+
+// A silent drop to zero coverage would make B1 vacuously green — e.g. if the guards
+// note format changed, or route-rank-check stopped classifying. Pin the floor of the
+// cross-reference itself, including that BOTH rank-gated classes are represented (an
+// all-archon sample would not exercise the metic boundary at all).
+//
+// The CENSUS counts both oracles (B1's rank-gated routes + B3's migrated ones), so the
+// R104-R107 migration moves permissions between them without ever dropping total
+// coverage — the guard stays a guard instead of becoming a migration blocker. The
+// per-class minimums are taken over the union and keyed on the CATALOG floor, since
+// here they measure sample breadth, not authority.
+test('B2: the route cross-reference actually covers a substantial slice of the catalog', () => {
+  const { floorPinned, atomPinned } = crossReference();
+  const covered = [...floorPinned, ...atomPinned];
+  assert.ok(covered.length >= 25,
+    `only ${covered.length} permissions cross-reference a gated route (${floorPinned.length} by rank, ${atomPinned.length} by atom; expected >= 25)`);
+  const archonCovered = covered.filter((r) => r.floor === 'archon');
+  const meticCovered = covered.filter((r) => r.floor === 'metic');
+  assert.ok(archonCovered.length >= 10, `only ${archonCovered.length} archon-floored routes cross-referenced`);
+  assert.ok(meticCovered.length >= 10, `only ${meticCovered.length} metic-floored routes cross-referenced`);
+});
+
+// B3 — the oracle that REPLACES B1 as routes migrate (BV1.R109). For a route gated by
+// requirePermission, route-rank-check derives its rank from catalog.floor, so a floor
+// comparison is circular. What is still independent is WHICH ATOM the route names: the
+// catalog says permission P guards route R, so R's gate must actually name P.
+//
+// VACUOUS UNTIL R104-R107 LAND — zero routes carry a permission gate today, so this
+// passing proves nothing yet. It grows into B1's replacement exactly as B1 shrinks;
+// B2's census is what keeps the pair from silently emptying out.
+test('B3: a MIGRATED route gates on the atom the catalog says guards it', () => {
+  const { atomPinned } = crossReference();
+  const violations = atomPinned
+    .filter((r) => !r.perms.includes(r.permission))
+    .map((r) => `  ${r.permission}: its guards note names ${r.routeKey}, but that route gates on '${r.perms.join(', ')}'`);
+  assert.equal(violations.length, 0,
+    `a migrated route gates on a different atom than the catalog claims guards it:\n${violations.join('\n')}`);
+});
+
+// ═══ PART C — the two REAL middlewares, over the whole catalog ════════════════
+
+function fakeRes() {
+  const res = {
+    _status: null,
+    _json: null,
+    status(code) { this._status = code; return this; },
+    json(body) { this._json = body; return this; },
+  };
+  attachFail({}, res, () => {});
+  return res;
+}
+
+// Runs the real permission gate with the governance port stubbed to return what the
+// live resolver returns for a builder of `rank`. The stub supplies the DB row set,
+// not the logic — resolvedFor() is the real resolver over the real seed.
+async function permissionAdmits(key, rank) {
+  seams._reset();
+  seams.registerProvider('governance', { resolveBuilderPermissions: async () => resolvedFor(rank) });
+  let nexted = false;
+  await auth.requirePermission(key)({ builder: { id: 7, rank } }, fakeRes(), () => { nexted = true; });
+  seams._reset();
+  return nexted;
+}
+
+function rankGateAdmits(floor, rank) {
+  let nexted = false;
+  auth.requireRank(floor)({ builder: { rank } }, fakeRes(), () => { nexted = true; });
+  return nexted;
+}
+
+test('C1: requirePermission and requireRank agree on EVERY catalog key × every seeded rank', async () => {
+  const drift = [];
+  for (const p of FLOORED) {
+    for (const rank of RANK_ORDER) {
+      const viaPermission = await permissionAdmits(p.key, rank);
+      const viaRank = rankGateAdmits(p.floor, rank);
+      if (viaPermission !== viaRank) drift.push({ rank, key: p.key, floor: p.floor, held: viaPermission, allowed: viaRank });
+    }
+  }
+  assert.equal(drift.length, 0, `requirePermission and requireRank disagree at the live gate:\n${nameDrift(drift)}`);
+});
+
+test('C2: the permission gate denies every principal key for every seeded rank', async () => {
+  for (const p of PRINCIPALS) {
+    for (const rank of RANK_ORDER) {
+      assert.equal(await permissionAdmits(p.key, rank), false,
+        `${rank} passed a ${p.key} gate — principals are gated on an exact system_role`);
+    }
+  }
+});
+
+// ═══ PART D — the deliberate fail-closed divergence ═══════════════════════════
+
+test('D1: a builder on a NON-seeded rank gets no role and resolves to ZERO permissions', () => {
+  assert.ok(UNSEEDED_RANKS.length > 0, 'the rank CHECK still reserves ranks with no seeded role');
+  for (const rank of UNSEEDED_RANKS) {
+    assert.deepEqual(resolvedFor(rank), [], `${rank} has no seeded rank-role, so it must resolve to nothing`);
+  }
+});
+
+test('D2: that divergence is strictly a TIGHTENING — the divine ranks lose latent power, none gain', async () => {
+  // requireRank's threshold admits every rank ABOVE archon (#591), so a divine rank
+  // passes an archon gate today yet holds no seeded role tomorrow. That is the
+  // intended stricter posture, not a bug — pin it so a later "fix" that widens the
+  // backfill has to argue with a test instead of slipping through.
+  const divine = UNSEEDED_RANKS.filter((r) => admits(r, 'archon'));
+  assert.ok(divine.length > 0, 'expected at least one above-archon rank requireRank still admits');
+  for (const rank of divine) {
+    assert.equal(resolvedFor(rank).length, 0, `${rank} is admitted by an archon gate but holds no governance role`);
+    assert.equal(await permissionAdmits('builder.rank.set', rank), false,
+      `${rank} must be denied at the permission gate even though requireRank('archon') admits it`);
+  }
+});