@bongos/core 1.18.3 → 1.18.19

package/tests/governance_principals.mjs

@@ -0,0 +1,232 @@
+// tests/governance_principals.mjs — machine principals as a first-class type
+// (BV1.R98, ADR 0151 §3). DB-free.
+//
+// A builder's authority is the UNION of their ROLES. A machine principal's authority
+// is its IDENTITY — the exact `builders.system_role` value. Those are two axes, and
+// every test here exists to prove they never collapse into one lookup:
+//
+//   • no rank-role holds a principal permission — not even archon's;
+//   • a role/assignment cannot confer one either, however the grant row got written;
+//   • a principal resolves its capability from system_role alone, by EXACT match;
+//   • nothing in this module can create, grant, or assign a principal — the column
+//     is provisioned out-of-band by migration, under a DB CHECK allowlist.
+//
+// The HTTP enforcement point stays requireBfgPrincipal / requireDiscordBot in
+// src/bongos/auth.js; this file guards the model those gates express.
+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 GOV = path.join(ROOT, 'modules', 'governance');
+const catalog = require(path.join(GOV, 'catalog.js'));
+const resolver = require(path.join(GOV, 'resolver.js'));
+
+const { PERMISSIONS, RANK_ORDER, RANK_ROLE_SEED, PRINCIPALS, principalKeys, principalRoles, isPrincipalKey, principalByRole, seedForRank, isGrantable, isSystem, systemKeys, grantableKeys, permissionKeys } = catalog;
+const { effectivePermissions, resolvePrincipalPermissions, principalHasPermission } = resolver;
+
+// ── the catalog side: principals are a distinct, well-formed type ───────────────
+
+test('every principal.* key is system:true with floor:null and a principal identity', () => {
+  const prefixed = PERMISSIONS.filter((p) => p.key.startsWith('principal.'));
+  assert.ok(prefixed.length >= 2, 'expected the bfg + discord_bot principals');
+  for (const p of prefixed) {
+    assert.equal(p.system, true, `${p.key} must be system (non-grantable)`);
+    assert.equal(p.floor, null, `${p.key} must have floor null (held by no rank-role)`);
+    assert.equal(typeof p.principal, 'string', `${p.key} must name its system_role`);
+    assert.ok(p.principal.length > 0, `${p.key} principal identity must be non-empty`);
+  }
+});
+
+test('floor:null and principal identity are a partition — neither exists without the other', () => {
+  for (const p of PERMISSIONS) {
+    assert.equal(p.floor === null, p.principal != null,
+      `${p.key}: a permission is held by a rank-role (real floor) XOR by a machine identity`);
+    assert.equal(p.key.startsWith('principal.'), p.principal != null,
+      `${p.key}: the principal.* namespace and the principal identity must agree`);
+  }
+});
+
+test('the bfg and discord_bot principals are the modelled identities', () => {
+  assert.deepEqual([...principalRoles()].sort(), ['bfg', 'discord_bot']);
+  assert.deepEqual([...principalKeys()].sort(), ['principal.bfg', 'principal.discord_bot']);
+  assert.equal(principalByRole('bfg').permission, 'principal.bfg');
+  assert.equal(principalByRole('discord_bot').permission, 'principal.discord_bot');
+});
+
+test('isPrincipalKey separates the axes; an unknown key fails closed', () => {
+  assert.equal(isPrincipalKey('principal.bfg'), true);
+  assert.equal(isPrincipalKey('principal.discord_bot'), true);
+  assert.equal(isPrincipalKey('idea.triage'), false);
+  assert.equal(isPrincipalKey('deploy.push_main'), false); // system, but rank-held
+  assert.equal(isPrincipalKey('nope.not.a.key'), false);
+  assert.equal(isPrincipalKey(null), false);
+});
+
+// ── no role, at any rank, holds a principal permission ──────────────────────────
+
+test('no rank-role holds a principal permission — an Archon must not hold principal.bfg', () => {
+  for (const rank of RANK_ORDER) {
+    const held = new Set(RANK_ROLE_SEED[rank]);
+    for (const key of principalKeys()) {
+      assert.ok(!held.has(key), `the ${rank} rank-role must not hold ${key}`);
+    }
+    // and the same via the derivation, so a future seed refactor is covered too
+    const derived = new Set(seedForRank(rank));
+    for (const key of principalKeys()) {
+      assert.ok(!derived.has(key), `seedForRank('${rank}') must not derive ${key}`);
+    }
+  }
+  assert.ok(!RANK_ROLE_SEED.archon.includes('principal.bfg'),
+    'the top rank is the case that matters: identity is not seniority');
+});
+
+test('a principal permission is never grantable to a custom role', () => {
+  for (const key of principalKeys()) {
+    assert.equal(isGrantable(key), false, `${key} must not be grantable`);
+    assert.equal(isSystem(key), true, `${key} must be flagged system`);
+    assert.ok(!grantableKeys().includes(key), `grantableKeys() must exclude ${key}`);
+    assert.ok(systemKeys().includes(key), `systemKeys() must include ${key}`);
+  }
+});
+
+test('a role/assignment cannot confer a principal permission, however the grant row got written', () => {
+  // The write side rejects a system permission, but the resolve side must not depend
+  // on that: a hand-inserted grant row must still confer nothing.
+  assert.deepEqual(effectivePermissions(['principal.bfg']), []);
+  assert.deepEqual(effectivePermissions(['principal.bfg', 'principal.discord_bot']), []);
+  assert.deepEqual(effectivePermissions(['idea.triage', 'principal.bfg', 'task.ship']), ['idea.triage', 'task.ship']);
+  // even the whole catalog granted at once yields no principal key
+  const everything = new Set(effectivePermissions(permissionKeys()));
+  for (const key of principalKeys()) {
+    assert.ok(!everything.has(key), `${key} must never survive the role resolve`);
+  }
+  // ...while every non-principal key still does (the role axis is otherwise unchanged)
+  const nonPrincipal = permissionKeys().filter((k) => !isPrincipalKey(k));
+  assert.deepEqual(effectivePermissions(permissionKeys()), [...nonPrincipal].sort());
+});
+
+// ── the identity axis: system_role alone, matched exactly ───────────────────────
+
+test('a principal resolves its capability from system_role alone', () => {
+  assert.deepEqual(resolvePrincipalPermissions('bfg'), ['principal.bfg']);
+  assert.deepEqual(resolvePrincipalPermissions('discord_bot'), ['principal.discord_bot']);
+  assert.equal(principalHasPermission('bfg', 'principal.bfg'), true);
+  assert.equal(principalHasPermission('discord_bot', 'principal.discord_bot'), true);
+});
+
+test('one principal never reaches another principal\'s capability, or any role permission', () => {
+  assert.equal(principalHasPermission('bfg', 'principal.discord_bot'), false);
+  assert.equal(principalHasPermission('discord_bot', 'principal.bfg'), false);
+  assert.equal(principalHasPermission('bfg', 'idea.triage'), false);
+  assert.equal(principalHasPermission('bfg', 'deploy.push_main'), false);
+  // a principal's set is exactly its own key — the identity axis grants nothing else
+  assert.equal(resolvePrincipalPermissions('bfg').length, 1);
+});
+
+test('the match is EXACT — a human token (system_role NULL) resolves nothing', () => {
+  for (const notAPrincipal of [null, undefined, '', 'BFG', 'Bfg', ' bfg', 'bfg ', 'bfg\n', 'bfgx', 'discord', 'archon', 'metic', 'admin', 0, 1, {}, [], true]) {
+    assert.deepEqual(resolvePrincipalPermissions(notAPrincipal), [],
+      `${JSON.stringify(notAPrincipal)} must resolve to no principal capability`);
+  }
+  // the concrete claim ADR 0026 §6C makes: an Archon token cannot be the BFG
+  assert.equal(principalHasPermission(null, 'principal.bfg'), false);
+  assert.equal(principalHasPermission('archon', 'principal.bfg'), false);
+});
+
+test('resolved principal sets are frozen — a caller cannot widen one', () => {
+  const held = resolvePrincipalPermissions('bfg');
+  assert.ok(Object.isFrozen(held));
+  assert.throws(() => held.push('deploy.push_main'), TypeError);
+  assert.ok(Object.isFrozen(PRINCIPALS));
+  for (const p of PRINCIPALS) assert.ok(Object.isFrozen(p), `${p.system_role} descriptor must be frozen`);
+});
+
+// ── show, never grant ───────────────────────────────────────────────────────────
+
+test('the tab surface is a read-only projection: shown, flagged non-grantable', () => {
+  const { governancePort } = require(path.join(GOV, 'routes', 'governance.js'));
+  assert.equal(typeof governancePort.listPrincipals, 'function');
+  assert.equal(typeof governancePort.resolvePrincipalPermissions, 'function');
+  const listed = governancePort.listPrincipals();
+  assert.deepEqual(listed.map((p) => p.system_role).sort(), ['bfg', 'discord_bot']);
+  for (const p of listed) {
+    assert.equal(p.grantable, false, `${p.system_role} must be rendered non-grantable`);
+    assert.match(p.provisioned, /out-of-band/, 'the descriptor must say where a principal comes from');
+    assert.ok(p.permission && p.guards, 'the tab needs the key + what it guards to render the row');
+  }
+});
+
+test('the governance port exposes no way to create, grant, or assign a principal', () => {
+  const { governancePort } = require(path.join(GOV, 'routes', 'governance.js'));
+  const mutator = /(create|grant|assign|add|set|write|provision|revoke|delete|update)/i;
+  for (const name of Object.keys(governancePort)) {
+    if (!/principal/i.test(name)) continue;
+    assert.ok(!mutator.test(name), `port method "${name}" looks like a principal mutator — principals are provisioned out-of-band only`);
+  }
+});
+
+test('the module writes builders.system_role nowhere — provisioning is out-of-band', () => {
+  // Structural, not behavioural: the guarantee is that governance has no code path
+  // to mint an identity at all, so a future CRUD slice (R110) cannot quietly grow one.
+  const files = [];
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full);
+      else if (e.name.endsWith('.js') || e.name.endsWith('.sql')) files.push(full);
+    }
+  };
+  walk(GOV);
+  assert.ok(files.length > 0, 'expected to scan the governance module sources');
+  for (const f of files) {
+    const code = fs.readFileSync(f, 'utf8')
+      .split('\n').filter((l) => !l.trim().startsWith('//') && !l.trim().startsWith('--')).join('\n');
+    assert.ok(!/\b(INSERT\s+INTO|UPDATE|ALTER\s+TABLE)\s+builders\b/i.test(code),
+      `${path.basename(f)} writes the builders table — governance may read an identity, never mint one`);
+  }
+});
+
+test('the catalog models exactly the principals the substrate can provision', () => {
+  // builders.system_role carries a DB CHECK allowlist (migration 065, widened by 067).
+  // A principal the substrate cannot provision would be a permission nothing can hold;
+  // an identity the substrate CAN provision but the catalog omits would be invisible
+  // to the tab. Either way the two lists must agree.
+  const sql = fs.readFileSync(path.join(ROOT, 'migrations', '067_discord_bot_foundation.sql'), 'utf8');
+  const m = sql.match(/CHECK \(system_role IS NULL OR system_role IN \(([^)]*)\)\)/);
+  assert.ok(m, 'expected the system_role CHECK allowlist in migration 067');
+  const allowed = [...m[1].matchAll(/'([^']+)'/g)].map((x) => x[1]).sort();
+  assert.deepEqual([...principalRoles()].sort(), allowed,
+    'catalog principals must match the builders.system_role CHECK allowlist');
+});
+
+// ── the R94/R95 invariants this slice must not have disturbed ───────────────────
+
+test('the rank-role seed is still cumulative and floor-derived (R94 invariants hold)', () => {
+  for (let i = 1; i < RANK_ORDER.length; i++) {
+    const lower = new Set(RANK_ROLE_SEED[RANK_ORDER[i - 1]]);
+    for (const k of RANK_ROLE_SEED[RANK_ORDER[i]]) assert.ok(typeof k === 'string');
+    for (const k of lower) {
+      assert.ok(RANK_ROLE_SEED[RANK_ORDER[i]].includes(k), `${RANK_ORDER[i]} lost ${k}`);
+    }
+  }
+  for (const rank of RANK_ORDER) {
+    const held = new Set(RANK_ROLE_SEED[rank]);
+    const tier = RANK_ORDER.indexOf(rank);
+    for (const p of PERMISSIONS) {
+      assert.equal(held.has(p.key), p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier,
+        `${rank} vs ${p.key} (floor ${p.floor})`);
+    }
+  }
+});
+
+test('the role resolve is otherwise unchanged: unknown keys drop, no roles is empty', () => {
+  assert.deepEqual(effectivePermissions(['idea.triage', 'not.a.real.permission']), ['idea.triage']);
+  assert.deepEqual(effectivePermissions([]), []);
+  assert.deepEqual(effectivePermissions(null), []);
+  assert.ok(Object.isFrozen(effectivePermissions(['task.ship'])));
+});

package/tests/governance_protected_surfaces.mjs

@@ -0,0 +1,208 @@
+// tests/governance_protected_surfaces.mjs — the protected-surface registry
+// (BV1.R101, ADR 0151 §4).
+//
+// DB-free. The registry is the data the OUT-OF-BAND substrate reads (a git
+// pre-push hook, CI, the post-push audit), so every invariant here is checked
+// the way the substrate sees it: synchronously, from the repo, with no server
+// and no database.
+//
+// The load-bearing test is BEHAVIOR-IDENTITY. R101 moved WHERE the truth lives
+// (a hardcoded PROTECTED_GLOBS constant in src/bongos/permission-path-check.js →
+// governance-owned data in modules/governance/protected-surfaces.json). It did
+// NOT change WHAT is protected. EXPECTED_GLOBS_BEFORE_R101 below is the literal
+// pre-change constant, pasted verbatim; the registry must reproduce it exactly,
+// in order.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { execFileSync } from 'node:child_process';
+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 GOV = path.join(ROOT, 'modules', 'governance');
+
+const ppc = require(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'));
+const registry = require(path.join(GOV, 'protected-surfaces.js'));
+const catalog = require(path.join(GOV, 'catalog.js'));
+
+// The verbatim PROTECTED_GLOBS array as it stood immediately before R101.
+const EXPECTED_GLOBS_BEFORE_R101 = [
+  'src/bongos/auth.js',
+  'src/bongos/db.js',
+  'src/bongos/route-rank-check.js',
+  'src/bongos/permission-path-check.js',
+  'src/bongos/middleware/',
+  'src/bongos/routes/',
+  'modules/lifecycle/routes/',
+  'src/bongos/routes.js',
+  'server.js',
+  'modules/governance/',
+  'modules/dev-box/boxes.js',
+  'modules/dev-box/box-access.js',
+  'modules/dev-box/box-credential.js',
+  'modules/grading/grader.js',
+  'modules/grading/grader-workers/',
+  'modules/grading/grader-rubric.json',
+  'scripts/gds/ship.js',
+  'scripts/gds/confirm.js',
+  'scripts/gds/merge-mode.js',
+  'scripts/gds/ci-grade.js',
+  'scripts/gds/grade-smoke.js',
+  'scripts/gds/conductor-dispatch.js',
+  'scripts/gds/main-audit.js',
+  'scripts/gds/push-main.js',
+  'scripts/gds/run-unit-tests.js',
+  'scripts/gds/gate-review.js',
+  'scripts/gds/setup.js',
+  'scripts/gds/install-git-hooks.js',
+  'scripts/gds/hooks/',
+  'scripts/gds/cli-lib.js',
+  'scripts/migrate.sh',
+  'scripts/deploy/',
+  'modules/lifecycle/merge-lock.js',
+  'modules/lifecycle/ship-preflight.js',
+  'modules/lifecycle/github-push.js',
+  'modules/lifecycle/conflict-resolve.js',
+  'modules/lifecycle/publish-reconciler.js',
+  'migrations/',
+  'infra/',
+  '.github/',
+  'CODEOWNERS',
+  'config/deploy.json',
+  'package.json',
+  'package-lock.json',
+  '.husky/',
+  'docs/canonical-permissions.md',
+  'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
+  'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md',
+  'CLAUDE.md',
+  '.claude/hooks/',
+  '.claude/settings.json',
+];
+
+// ---------- behavior identity: the same globs, at the same floor ----------
+
+test('the registry reproduces the pre-R101 PROTECTED_GLOBS exactly, in order', () => {
+  assert.deepEqual(registry.PROTECTED_GLOBS, EXPECTED_GLOBS_BEFORE_R101);
+  assert.deepEqual(ppc.PROTECTED_GLOBS, EXPECTED_GLOBS_BEFORE_R101,
+    'the kernel matcher must expose the same derived list the registry declares');
+});
+
+test('every surface floors at metic — the ADR 0043 floor, unchanged by the move', () => {
+  for (const s of registry.SURFACES) {
+    assert.equal(s.floor, 'metic', `${s.glob} must keep the Metic floor`);
+  }
+  assert.equal(registry.FLOOR, 'metic');
+  assert.equal(ppc.MIN_TIER, ppc.RANK_TIER.metic, 'the kernel floor must DERIVE to metic');
+});
+
+// ---------- the system-permission mapping flows from the registry ----------
+
+test('every entry maps to a permission the catalog defines as system:true', () => {
+  for (const s of registry.SURFACES) {
+    const perm = catalog.byKey(s.permission);
+    assert.ok(perm, `${s.glob} maps to unknown permission "${s.permission}"`);
+    assert.equal(perm.system, true,
+      `${s.glob} maps to "${s.permission}", which must be NON-GRANTABLE (system:true) — otherwise a custom role could be handed the power the substrate reserves`);
+  }
+  assert.deepEqual(registry.SYSTEM_PERMISSIONS, ['path.protected.modify']);
+});
+
+test('a surface mapped to a grantable or unknown permission fails loud', () => {
+  // The guard must actually catch a bad mapping, not pass vacuously.
+  const grantable = catalog.grantableKeys()[0];
+  assert.ok(grantable && catalog.isSystem(grantable) === false);
+  assert.equal(catalog.byKey('not.a.real.permission'), null);
+});
+
+// ---------- synchronous, no DB, no server ----------
+
+test('the registry loads synchronously from the repo with no DB and no server', () => {
+  // A cold `node -e` process: no server booted, no pool, no network. This is the
+  // pre-push hook / CI condition — if the registry ever needed a database the
+  // enforcers would silently stop enforcing.
+  const out = execFileSync(process.execPath, ['-e',
+    "const p=require('./src/bongos/permission-path-check');" +
+    "process.stdout.write(String(p.PROTECTED_GLOBS.length)+':'+String(p.floorFor('migrations/001.sql')));",
+  ], { cwd: ROOT, encoding: 'utf8', env: { ...process.env, DATABASE_URL: '', PGHOST: '' } });
+  assert.equal(out, `${EXPECTED_GLOBS_BEFORE_R101.length}:metic`);
+});
+
+test('the registry data file carries no DB/network dependency', () => {
+  const json = fs.readFileSync(path.join(GOV, 'protected-surfaces.json'), 'utf8');
+  assert.doesNotThrow(() => JSON.parse(json), 'the canonical form must be plain parseable data');
+  const code = fs.readFileSync(path.join(GOV, 'protected-surfaces.js'), 'utf8')
+    .split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+  for (const banned of ['./db', 'pool', 'fetch(', 'await ']) {
+    assert.ok(!code.includes(banned),
+      `protected-surfaces.js must not introduce "${banned}" — the substrate reads this with no DB and no server (ADR 0151 §4)`);
+  }
+});
+
+// ---------- policy owns / substrate enforces ----------
+
+test('the kernel does not require the governance module (ADR 0083 one-way rule)', () => {
+  const kernel = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'), 'utf8');
+  const requires = [...kernel.matchAll(/require\(\s*['"]([^'"]+)['"]\s*\)/g)].map((m) => m[1]);
+  assert.deepEqual(requires.filter((r) => r.includes('modules/')), [],
+    'core must never require a module — it reads the registry as data');
+  // …and the flow runs the legal way: governance reaches the matcher through the doorway.
+  const gov = fs.readFileSync(path.join(GOV, 'protected-surfaces.js'), 'utf8');
+  assert.ok(/require\(\s*['"]\.\.\/\.\.\/src\/module-api['"]\s*\)/.test(gov),
+    'governance must reach the kernel matcher through the published doorway');
+});
+
+test('the hardcoded protected list is gone from the kernel — one source, no drift', () => {
+  const kernel = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'), 'utf8');
+  assert.ok(!/(?:const|let|var)\s+PROTECTED_GLOBS\s*=\s*\[\s*$/m.test(kernel),
+    'PROTECTED_GLOBS must be DERIVED from the registry, never re-declared as a literal list');
+  assert.equal(ppc.REGISTRY_PATH, path.join(GOV, 'protected-surfaces.json'));
+});
+
+test('a missing registry fails CLOSED — it never degrades to "nothing is protected"', () => {
+  assert.throws(() => {
+    execFileSync(process.execPath, ['-e',
+      "const fs=require('node:fs');const real=fs.readFileSync;" +
+      "fs.readFileSync=(p,...r)=>{ if(String(p).includes('protected-surfaces.json')) throw new Error('gone'); return real(p,...r); };" +
+      "require('./src/bongos/permission-path-check');",
+    ], { cwd: ROOT, stdio: 'pipe' });
+  }, /unreadable|Refusing/i);
+});
+
+// ---------- the matcher, driven by registry data ----------
+
+test('a known path is protected at the right floor; an unknown path is not', () => {
+  assert.equal(ppc.floorFor('src/bongos/auth.js'), 'metic');
+  assert.equal(ppc.permissionFor('src/bongos/auth.js'), 'path.protected.modify');
+  assert.equal(registry.isProtected('migrations/999_x.sql'), true, 'subtree globs still match');
+  assert.equal(registry.floorFor('modules/governance/catalog.js'), 'metic');
+
+  assert.equal(ppc.floorFor('public/game/main.js'), null);
+  assert.equal(ppc.permissionFor('docs/session-logs/2026-07-30-x.md'), null);
+  assert.equal(registry.isProtected('public/game/main.js'), false);
+  assert.equal(registry.surfaceFor('src/world/terrain.js'), null);
+});
+
+test('every registry glob actually matches something the matcher flags', () => {
+  for (const s of registry.SURFACES) {
+    const sample = s.glob.endsWith('/') ? `${s.glob}sample.js` : s.glob;
+    const hits = ppc.matchProtected([sample]);
+    assert.equal(hits.length, 1, `${s.glob} must match ${sample}`);
+    assert.equal(hits[0].glob, s.glob);
+    assert.equal(hits[0].floor, s.floor);
+    assert.equal(hits[0].permission, s.permission);
+  }
+});
+
+test('the floor decision reads the hit\'s registry floor, so a re-map takes effect', () => {
+  const below = ppc.checkPermissionPaths({ changedFiles: ['migrations/001.sql'], builderRank: 'thetes' });
+  assert.equal(below.hardFail, true);
+  assert.equal(below.findings[0].floor, 'metic');
+  assert.equal(below.findings[0].permission, 'path.protected.modify');
+
+  const atFloor = ppc.checkPermissionPaths({ changedFiles: ['migrations/001.sql'], builderRank: 'metic' });
+  assert.equal(atFloor.hardFail, false);
+});

package/tests/governance_require_permission.mjs

@@ -0,0 +1,223 @@
+// tests/governance_require_permission.mjs — the requirePermission gate (BV1.R97, ADR 0151).
+//
+// DB-free. The gate reaches the resolver through the `governance` KERNEL PORT
+// (the one-way rule — core never requires modules/governance/), so a stub
+// provider registered on the seam is the whole test double: no Postgres, no
+// router, no live module. That is also the point being asserted — if auth.js ever
+// went back to importing the module directly, these tests could not stub it.
+//
+// What matters here is trust-boundary posture (ADR 0016): EVERY unhappy path must
+// 403, including the ones that are not "you lack the permission" — no builder, a
+// mis-authored empty gate, a missing port, a throwing resolver. A gate that
+// admits when authority cannot be established is a privilege escalation.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+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 seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+const { classify } = require(path.join(ROOT, 'src', 'bongos', 'api-errors.js'));
+const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+
+// Minimal res double capturing status + body, with res.fail() installed exactly
+// as the router installs it (mirrors tests/rank_gate.mjs).
+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;
+}
+
+// Register a stub `governance` port for one run. `resolve` is the stubbed
+// resolveBuilderPermissions; pass null to leave the port UNREGISTERED.
+async function run(gate, req, resolve) {
+  seams._reset();
+  if (resolve !== null) seams.registerProvider('governance', { resolveBuilderPermissions: resolve });
+  const res = fakeRes();
+  let nexted = false;
+  await gate(req, res, () => { nexted = true; });
+  seams._reset();
+  return { res, nexted };
+}
+
+const BUILDER = { id: 7, rank: 'metic' };
+const holding = (...keys) => async () => keys;
+
+test('a builder holding the permission passes the gate', async () => {
+  const { res, nexted } = await run(
+    auth.requirePermission('idea.triage'), { builder: BUILDER }, holding('idea.triage', 'cost.log'),
+  );
+  assert.equal(nexted, true, 'next() should be called');
+  assert.equal(res._status, null, 'no status should be set');
+});
+
+test('a missing grant 403s with permission_forbidden and explains the denial', async () => {
+  const { res, nexted } = await run(
+    auth.requirePermission('governance.manage'), { builder: BUILDER }, holding('idea.triage'),
+  );
+  assert.equal(nexted, false, 'next() must NOT be called');
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'permission_forbidden');
+  assert.deepEqual(res._json.error.details.required, ['governance.manage']);
+  assert.deepEqual(res._json.error.details.held, [], 'holds none of the required perms');
+});
+
+test('multiple permissions are AND, not OR — holding one of two still denies', async () => {
+  const gate = auth.requirePermission('task.create', 'task.edit');
+  const partial = await run(gate, { builder: BUILDER }, holding('task.create'));
+  assert.equal(partial.nexted, false, 'holding only one of two must deny');
+  assert.equal(partial.res._status, 403);
+  assert.deepEqual(partial.res._json.error.details.held, ['task.create'],
+    'held reports the intersection with required, not the whole permission set');
+  const both = await run(gate, { builder: BUILDER }, holding('task.create', 'task.edit', 'cost.log'));
+  assert.equal(both.nexted, true, 'holding both must admit');
+});
+
+test('no req.builder fails closed (gate mounted without requireBuilder)', async () => {
+  const { res, nexted } = await run(auth.requirePermission('idea.triage'), {}, holding('idea.triage'));
+  assert.equal(nexted, false);
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'permission_forbidden');
+  assert.equal(res._json.error.details.held, null, 'null held = the set was never resolved');
+});
+
+test('an empty permission list denies — a mis-authored gate must not open', async () => {
+  const { res, nexted } = await run(auth.requirePermission(), { builder: BUILDER }, holding('idea.triage'));
+  assert.equal(nexted, false);
+  assert.equal(res._status, 403);
+  assert.deepEqual(res._json.error.details.required, []);
+  assert.equal(res._json.error.details.held, null);
+});
+
+test('an UNREGISTERED governance port denies, it does not admit', async () => {
+  // The deliberate call: no port = authority cannot be established. Admitting
+  // here would make "disable the governance module" a privilege escalation.
+  const { res, nexted } = await run(auth.requirePermission('idea.triage'), { builder: BUILDER }, null);
+  assert.equal(nexted, false, 'a missing authority system must never open a gate');
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'permission_forbidden');
+  assert.equal(res._json.error.details.held, null);
+});
+
+test('a malformed port (no resolveBuilderPermissions) denies', async () => {
+  seams._reset();
+  seams.registerProvider('governance', { isSystem: () => true });
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requirePermission('idea.triage')({ builder: BUILDER }, res, () => { nexted = true; });
+  seams._reset();
+  assert.equal(nexted, false);
+  assert.equal(res._status, 403);
+});
+
+test('a throwing resolver denies (a DB blip must not open the gate)', async () => {
+  const { res, nexted } = await run(
+    auth.requirePermission('idea.triage'), { builder: BUILDER },
+    async () => { throw new Error('connection terminated'); },
+  );
+  assert.equal(nexted, false, 'a resolve failure must fail CLOSED');
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'permission_forbidden');
+  assert.equal(res._json.error.details.held, null);
+});
+
+test('permission_forbidden is registered as a 403 forbidden code, not a 500', async () => {
+  // Without an OVERRIDES entry the naming heuristic would classify the new code
+  // as `internal` and res.fail() would answer 500 — a denial reported as an outage.
+  assert.equal(classify('permission_forbidden'), 'forbidden');
+});
+
+test('the gate resolves per request — no memoised authority (ADR 0016)', async () => {
+  // A revoked grant must take effect on the very next request, so the gate must
+  // call the resolver every time rather than reusing a first answer.
+  let calls = 0;
+  let keys = ['idea.triage'];
+  seams._reset();
+  seams.registerProvider('governance', { resolveBuilderPermissions: async () => { calls += 1; return keys; } });
+  const gate = auth.requirePermission('idea.triage');
+  const first = fakeRes();
+  let admitted = false;
+  await gate({ builder: BUILDER }, first, () => { admitted = true; });
+  assert.equal(admitted, true);
+  keys = []; // the grant is revoked between requests
+  const second = fakeRes();
+  let admittedAgain = false;
+  await gate({ builder: BUILDER }, second, () => { admittedAgain = true; });
+  seams._reset();
+  assert.equal(calls, 2, 'the resolver must be consulted on every request');
+  assert.equal(admittedAgain, false, 'a revoked grant must deny on the next request');
+  assert.equal(second._status, 403);
+});
+
+// ---------------------------------------------------------------------------
+// The done-when's other half: requireRank is UNCHANGED, and the seeded rank-roles
+// make the two gates equivalent during the R104-R107 migration.
+// ---------------------------------------------------------------------------
+
+test('requireRank still behaves identically — unchanged by R97', () => {
+  const gate = auth.requireRank('metic', 'archon');
+  for (const rank of ['metic', 'archon', 'olympian']) {
+    const res = fakeRes();
+    let nexted = false;
+    gate({ builder: { rank } }, res, () => { nexted = true; });
+    assert.equal(nexted, true, `${rank} should still pass a metic+archon gate`);
+    assert.equal(res._status, null);
+  }
+  const res = fakeRes();
+  let nexted = false;
+  gate({ builder: { rank: 'thetes' } }, res, () => { nexted = true; });
+  assert.equal(nexted, false);
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'rank_forbidden');
+  assert.deepEqual(res._json.error.details.required, ['metic', 'archon']);
+  assert.equal(res._json.error.details.actual, 'thetes');
+  assert.equal(auth.rankMeetsThreshold('archon', []), false, 'still fail-closed on an empty allow-list');
+});
+
+test('over the four seeded ranks, requirePermission admits exactly who requireRank admits', async () => {
+  // The migration-safety guarantee (R103's parity, in its DB-free form): feed the
+  // gate the SEED a rank-role grants and it reproduces the rank gate's verdict.
+  // Scoped to catalog.RANK_ORDER — the reserved/divine ranks above archon hold no
+  // seeded role, so parity is defined only over the four live ranks.
+  const cases = [
+    ['idea.triage', ['metic', 'archon']],
+    ['governance.manage', ['archon']],
+    ['task.claim.any', ['thetes', 'metic', 'archon']],
+    ['cost.log', ['xenos', 'thetes', 'metic', 'archon']],
+  ];
+  for (const [permission, allowedRanks] of cases) {
+    for (const rank of catalog.RANK_ORDER) {
+      const permGate = await run(
+        auth.requirePermission(permission), { builder: { id: 7, rank } },
+        async () => catalog.seedForRank(rank),
+      );
+      const rankRes = fakeRes();
+      let rankNexted = false;
+      auth.requireRank(...allowedRanks)({ builder: { rank } }, rankRes, () => { rankNexted = true; });
+      assert.equal(permGate.nexted, rankNexted,
+        `${rank}: requirePermission('${permission}') and requireRank(${allowedRanks.join(',')}) must agree`);
+    }
+  }
+});
+
+test('a principal permission (floor null) is held by NO rank-role', async () => {
+  // principal.bfg is gated on the exact system_role, never a rank — so no seeded
+  // role grants it and the gate denies every rank, archon included.
+  for (const rank of catalog.RANK_ORDER) {
+    const { nexted, res } = await run(
+      auth.requirePermission('principal.bfg'), { builder: { id: 7, rank } },
+      async () => catalog.seedForRank(rank),
+    );
+    assert.equal(nexted, false, `${rank} must not hold a principal permission`);
+    assert.equal(res._status, 403);
+  }
+});