@bongos/core 1.18.19 → 1.19.3

package/tests/governance_abuse_matrix.mjs

@@ -0,0 +1,386 @@
+// tests/governance_abuse_matrix.mjs — the abuse matrix (BV1.R112, ADR 0151).
+//
+// Mechanically proves the safety guarantee the governance module asserts in
+// prose: NO configuration surface can grant a `system: true` (trust-boundary)
+// permission — deploy, protected-path, rank-set, grade-bypass, cross-tier,
+// principals — to a custom role or a low-trust builder, and the out-of-band
+// substrate still blocks the action EVEN IF a grant row were forced into the DB.
+//
+// The matrix is enumerated from the catalog, never sampled: every vector below
+// loops over catalog.systemKeys() (and every registry surface), so a system
+// permission added tomorrow is covered the day it lands.
+//
+//   Grant vectors (every one must refuse, server-side, before any DB write):
+//     V1  HTTP: PUT a system permission onto a custom role
+//     V2  HTTP: PUT any grant onto a seeded rank-role (immutable)
+//     V3  HTTP: assign a seeded rank-role to a builder (rank is the only writer)
+//     V4  HTTP: mass-assignment on role create (is_system / permissions in body)
+//     V5  HTTP: every write vector 403s outright for a caller without
+//         governance.manage (the low-trust builder's own attempt)
+//     V6  config: a role template proposing system keys is stripped; a seeded
+//         role's template grants are dropped wholesale; env overrides labels only
+//     V7  session-scope: an allow-list naming a system or principal key THROWS
+//
+//   The wall behind the wall (a grant row forced past every vector above):
+//     V8  a forced principal grant resolves to NOTHING (effectivePermissions)
+//     V9  a box-scoped session narrows away every forced system grant
+//     V10 no route consumes the substrate-enforced keys via requirePermission —
+//         a forced deploy/protected-path/ssh grant admits nothing in-app
+//     V11 the substrate blocks a sub-floor builder on EVERY protected surface,
+//         and is structurally grant-blind (dependency-free — it cannot even
+//         reach the resolver, a DB, or the network)
+//     V12 seed integrity: no rank-role below archon holds a system key; no
+//         rank-role at all holds a principal key
+//
+// DB-free (the governance_routes.mjs pattern): real router + real
+// requirePermission over a stub `governance` port, db sibling monkeypatched.
+//
+// Run:  node tests/governance_abuse_matrix.mjs
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+const govConfig = require(path.join(ROOT, 'modules', 'governance', 'config.js'));
+const sessionScopes = require(path.join(ROOT, 'modules', 'governance', 'session-scopes.js'));
+const resolver = require(path.join(ROOT, 'modules', 'governance', 'resolver.js'));
+const govDb = require(path.join(ROOT, 'modules', 'governance', 'db.js'));
+const ppc = require(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'));
+const rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+const express = require('express');
+
+const SYSTEM_KEYS = catalog.systemKeys();
+const SEEDED_ROLES = catalog.RANK_ORDER; // xenos/thetes/metic/archon
+
+// The keys whose enforcement lives OUTSIDE the app entirely (git pre-push hook,
+// grader pre-pass, post-push main audit, credential placement — ADR 0043). The
+// task names deploy + protected-path; infra.ssh is the same substrate class.
+const SUBSTRATE_KEYS = ['deploy.push_main', 'path.protected.modify', 'infra.ssh'];
+
+// ===========================================================================
+// The matrix rows — sanity on what is being enumerated
+// ===========================================================================
+
+test('the matrix enumerates a non-empty system set including the named powers', () => {
+  assert.ok(SYSTEM_KEYS.length > 0, 'no system keys — the matrix would be vacuous');
+  for (const k of SUBSTRATE_KEYS) {
+    assert.ok(SYSTEM_KEYS.includes(k), `${k} must be system:true`);
+  }
+  for (const k of SYSTEM_KEYS) {
+    assert.equal(catalog.isGrantable(k), false, `${k} must be non-grantable`);
+  }
+});
+
+test('every system permission floors at archon or is a principal (never seeded lower)', () => {
+  for (const k of SYSTEM_KEYS) {
+    const p = catalog.byKey(k);
+    assert.ok(p.floor === 'archon' || p.floor === null,
+      `${k} floors at "${p.floor}" — a system permission must never seed below archon`);
+  }
+});
+
+// ===========================================================================
+// The HTTP vectors — real router, stub port, monkeypatched db
+// ===========================================================================
+
+const calls = [];
+const stub = {
+  getRoleByKey: async (k) => (SEEDED_ROLES.includes(k)
+    ? { role_key: k, label: k, is_system: true, seeded_rank: k }
+    : { role_key: k, label: k, is_system: false, seeded_rank: null }),
+  createRole: async (a) => ({ role_key: a.roleKey, label: a.label, description: a.description ?? null, is_system: false, seeded_rank: null, created_by: a.createdBy, created_at: 't' }),
+  grantRolePermission: async () => true,
+  revokeRolePermission: async () => true,
+  assignRole: async () => true,
+  unassignRole: async () => true,
+  listRolesWithGrants: async () => [],
+  listAssignments: async () => [],
+};
+const REAL = {};
+for (const k of Object.keys(stub)) {
+  REAL[k] = govDb[k];
+  govDb[k] = (...args) => { calls.push([k, ...args]); return stub[k](...args); };
+}
+
+// The attacker holds the MOST privileged legitimate session — an Archon with
+// governance.manage. The matrix must hold even against the admin misusing the
+// API, not just against a low-trust caller (V5 covers that one).
+const realRequireBuilder = api.requireBuilder;
+api.requireBuilder = (req, res, next) => { req.builder = { id: 42, rank: 'archon' }; next(); };
+
+function grant(keys) {
+  seams._reset();
+  seams.registerProvider('governance', { resolveBuilderPermissions: async () => keys });
+}
+grant(['governance.manage']);
+
+const buildGovernanceRouter = require(path.join(ROOT, 'modules', 'governance', 'routes', 'governance.js'));
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildGovernanceRouter());
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const BASE = `http://127.0.0.1:${server.address().port}`;
+
+after(() => {
+  server.close();
+  api.requireBuilder = realRequireBuilder;
+  for (const k of Object.keys(REAL)) govDb[k] = REAL[k];
+  seams._reset();
+});
+
+async function call(method, p, body) {
+  calls.length = 0;
+  const res = await fetch(`${BASE}${p}`, {
+    method,
+    headers: body === undefined ? {} : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  let json = null;
+  try { json = await res.json(); } catch { /* no body */ }
+  return { status: res.status, json };
+}
+
+test('V1: EVERY system permission is refused onto a custom role, before the db', async () => {
+  for (const k of SYSTEM_KEYS) {
+    const r = await call('PUT', `/governance/roles/custom-role/permissions/${k}`);
+    assert.equal(r.status, 400, `${k} must be refused`);
+    assert.equal(r.json.error.code, 'permission_not_grantable', k);
+    assert.equal(calls.filter(([c]) => c === 'grantRolePermission').length, 0,
+      `${k}: the refusal must land BEFORE any db write`);
+  }
+});
+
+test('V2: EVERY seeded rank-role refuses EVERY grant (system and operational alike)', async () => {
+  for (const role of SEEDED_ROLES) {
+    for (const k of [...SYSTEM_KEYS, 'idea.triage']) {
+      const r = await call('PUT', `/governance/roles/${role}/permissions/${k}`);
+      assert.equal(r.status, 403, `${role} ← ${k} must be refused`);
+      assert.equal(r.json.error.code, 'seeded_role_immutable', `${role} ← ${k}`);
+      assert.equal(calls.filter(([c]) => c === 'grantRolePermission').length, 0);
+    }
+  }
+});
+
+test('V3: EVERY seeded rank-role refuses assignment (rank is the only writer — R95b)', async () => {
+  for (const role of SEEDED_ROLES) {
+    const r = await call('POST', '/governance/assignments', { builder_id: 7, role_key: role });
+    assert.equal(r.status, 403, `assigning seeded role ${role} must be refused`);
+    assert.equal(r.json.error.code, 'seeded_role_assignment_forbidden', role);
+    assert.equal(calls.filter(([c]) => c === 'assignRole').length, 0);
+  }
+});
+
+test('V4: mass-assignment on role create is refused outright (strict schema)', async () => {
+  const r = await call('POST', '/governance/roles', {
+    role_key: 'sneaky-role',
+    label: 'Sneaky',
+    is_system: true,
+    seeded_rank: 'archon',
+    permissions: SYSTEM_KEYS,
+  });
+  assert.equal(r.status, 400, 'undeclared fields must be rejected, not silently dropped');
+  assert.equal(r.json.error.code, 'validation_failed');
+  assert.equal(calls.length, 0, 'nothing reached the db');
+});
+
+test('V4: a clean role create is never system and carries no grants', async () => {
+  const r = await call('POST', '/governance/roles', { role_key: 'sneaky-role', label: 'Sneaky' });
+  assert.equal(r.status, 201);
+  assert.equal(r.json.role.is_system, false, 'a created role is never system');
+  assert.equal(r.json.role.seeded_rank, null);
+  assert.deepEqual(r.json.role.permissions, [], 'creation carries no grants');
+  const c = calls.find(([k]) => k === 'createRole');
+  assert.deepEqual(Object.keys(c[1]).sort(), ['createdBy', 'description', 'label', 'roleKey'],
+    'nothing beyond the four whitelisted fields reaches the db');
+  assert.equal(calls.filter(([k]) => k === 'grantRolePermission').length, 0);
+});
+
+test('V5: a caller without governance.manage cannot reach ANY write vector at all', async () => {
+  grant(catalog.grantableKeys().filter((k) => k !== 'governance.manage'));
+  for (const [method, p, body] of [
+    ['POST', '/governance/roles', { role_key: 'x-role', label: 'X' }],
+    ['PUT', '/governance/roles/custom-role/permissions/deploy.push_main', undefined],
+    ['DELETE', '/governance/roles/custom-role/permissions/idea.triage', undefined],
+    ['POST', '/governance/assignments', { builder_id: 7, role_key: 'custom-role' }],
+    ['DELETE', '/governance/assignments/7/custom-role', undefined],
+  ]) {
+    const r = await call(method, p, body);
+    assert.equal(r.status, 403, `${method} ${p} must deny — even holding every operational grant`);
+    assert.equal(r.json.error.code, 'permission_forbidden', `${method} ${p}`);
+  }
+  grant(['governance.manage']);
+});
+
+// ===========================================================================
+// V6 — the config vector (a checkout-writable file must grant nothing)
+// ===========================================================================
+
+test('V6: a config template proposing EVERY system key resolves with all of them stripped', () => {
+  const resolved = govConfig.resolveGovernanceConfig({
+    instance: { roles: { 'evil-template': { label: 'Evil', permissions: [...SYSTEM_KEYS, 'no.such.key', 'idea.triage'] } } },
+    env: {},
+  });
+  const evil = resolved.roles['evil-template'];
+  assert.deepEqual([...evil.permissions], ['idea.triage'],
+    'only the operational key survives; every system + unknown key is stripped');
+});
+
+test('V6: a seeded rank-role template cannot re-grant — its permissions drop wholesale', () => {
+  const resolved = govConfig.resolveGovernanceConfig({
+    instance: { roles: { thetes: { label: 'Upgraded', permissions: ['idea.triage', ...SYSTEM_KEYS] } } },
+    env: {},
+  });
+  assert.deepEqual([...resolved.roles.thetes.permissions], [],
+    'a seeded role takes NO permissions from config, operational ones included');
+});
+
+test('V6: the env layer relabels only — it cannot add a permission or a role', () => {
+  // The role must exist in the merged config for the relabel to land (an env
+  // var can only RELABEL a declared role) — mirror the neutral starter's shape.
+  const resolved = govConfig.resolveGovernanceConfig({
+    neutral: { roles: { metic: { label: 'Metic' } } },
+    instance: {},
+    env: { OTB_GOVERNANCE_ROLE_LABELS: 'metic=Overlord,ghost-role=Ghost' },
+  });
+  assert.equal(resolved.roles.metic.label, 'Overlord', 'relabeling works');
+  assert.equal(resolved.roles['ghost-role'], undefined, 'an env var cannot mint a role');
+  assert.deepEqual([...resolved.roles.metic.permissions], [],
+    'the relabeled seeded role still takes no grants from config or env');
+});
+
+// ===========================================================================
+// V7 — the session-scope vector (an allow-list can never name system power)
+// ===========================================================================
+
+test('V7: a session-scope allow-list naming ANY system key throws at validation', () => {
+  for (const k of SYSTEM_KEYS) {
+    assert.throws(
+      () => sessionScopes.validateAgainstCatalog([
+        sessionScopes.normalizeScope({ source: 'evil', permissions: [k] }),
+      ]),
+      new RegExp(k.replace(/\./g, '\\.')),
+      `a scope allowing ${k} must be refused at load`,
+    );
+  }
+});
+
+test('V7: the LIVE session-scope registry carries no system or principal key', () => {
+  for (const scope of sessionScopes.SESSION_SCOPES) {
+    for (const k of scope.permissions) {
+      assert.equal(catalog.isSystem(k), false, `scope "${scope.source}" allows system key ${k}`);
+      assert.equal(catalog.isPrincipalKey(k), false, `scope "${scope.source}" allows principal key ${k}`);
+    }
+  }
+});
+
+// ===========================================================================
+// V8–V9 — a grant row FORCED past every write-side wall
+// ===========================================================================
+
+test('V8: a forced principal grant resolves to nothing (structurally dropped)', () => {
+  const forced = resolver.effectivePermissions([...catalog.principalKeys(), 'task.ship']);
+  assert.deepEqual([...forced], ['task.ship'],
+    'principal keys confer nothing through the role axis no matter how the row got written');
+});
+
+test('V9: a box-scoped session narrows away EVERY forced system grant', () => {
+  const forcedEverything = catalog.permissionKeys(); // as if every key were granted
+  const boxHolds = resolver.narrowToSessionScope(forcedEverything, 'box');
+  for (const k of boxHolds) {
+    assert.equal(catalog.isSystem(k), false, `a box token surfaced system key ${k}`);
+  }
+  assert.deepEqual([...resolver.narrowToSessionScope(forcedEverything, 'not-a-source')], [],
+    'an unrecognised source resolves to nothing, never to "full"');
+});
+
+// ===========================================================================
+// V10 — no route consumes the substrate keys (a forced grant is inert in-app)
+// ===========================================================================
+
+test('V10: no route gates on deploy/protected-path/ssh via requirePermission', () => {
+  const files = rrc.discoverRouteFiles();
+  assert.ok(files.length > 0, 'no route files discovered');
+  for (const { abs, rel } of files) {
+    const text = fs.readFileSync(abs, 'utf8');
+    for (const m of text.matchAll(/requirePermission\(([^)]*)\)/g)) {
+      for (const k of SUBSTRATE_KEYS) {
+        assert.ok(!m[1].includes(k),
+          `${rel} gates on ${k} — that key is substrate-enforced (ADR 0043); an app route consuming it would make a forced grant spendable`);
+      }
+    }
+  }
+});
+
+// ===========================================================================
+// V11 — the substrate holds, and cannot even see a grant
+// ===========================================================================
+
+// A concrete file that matches a registry glob, so every surface is exercised.
+function sampleFileFor(glob) {
+  if (glob.endsWith('/')) return `${glob}sample.js`;
+  return glob.replace(/\*\*/g, 'deep/nested').replace(/\*/g, 'sample');
+}
+
+test('V11: EVERY protected surface blocks a builder below its floor — grants have no input', () => {
+  assert.ok(ppc.PROTECTED_SURFACES.length > 0, 'empty protected-surface registry');
+  for (const s of ppc.PROTECTED_SURFACES) {
+    const file = sampleFileFor(s.glob);
+    assert.ok(ppc.matchProtected([file]).length > 0, `synthesized ${file} must match ${s.glob}`);
+    const floorTier = ppc.RANK_TIER[s.floor];
+    assert.ok(floorTier > ppc.RANK_TIER.xenos, `${s.glob} floors at ${s.floor} — nothing sits below it to block`);
+    const attacker = Object.keys(ppc.RANK_TIER).find((r) => ppc.RANK_TIER[r] === floorTier - 1);
+    const result = ppc.checkPermissionPaths({ changedFiles: [file], builderRank: attacker });
+    assert.equal(result.hardFail, true, `${attacker} touching ${file} must hard-fail`);
+    assert.ok(result.findings.some((f) => f.file === file && f.severity === 'blocker'),
+      `${file}: a blocker finding must name the file`);
+  }
+});
+
+test('V11: every protected surface maps to a system (non-grantable) permission', () => {
+  for (const s of ppc.PROTECTED_SURFACES) {
+    assert.equal(catalog.isSystem(s.permission), true,
+      `${s.glob} maps to ${s.permission}, which is not system:true — an Archon could hand a custom role the substrate's power`);
+  }
+});
+
+test('V11: the substrate checker is structurally grant-blind (node builtins only)', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'permission-path-check.js'), 'utf8');
+  const required = [...src.matchAll(/require\((['"])([^'"]+)\1\)/g)].map((m) => m[2]);
+  assert.ok(required.length > 0, 'expected the checker to require node builtins');
+  for (const spec of required) {
+    assert.ok(spec.startsWith('node:'),
+      `permission-path-check.js requires "${spec}" — it must stay dependency-free so it CANNOT consult the resolver, a DB, or the network (a forced grant has no channel in)`);
+  }
+});
+
+// ===========================================================================
+// V12 — seed integrity (the compat seed can never leak system power downward)
+// ===========================================================================
+
+test('V12: no rank-role below archon holds a system key; none holds a principal key', () => {
+  for (const rank of SEEDED_ROLES) {
+    const seed = catalog.RANK_ROLE_SEED[rank];
+    for (const k of seed) {
+      assert.equal(catalog.isPrincipalKey(k), false, `${rank} seeds principal key ${k}`);
+      if (rank !== 'archon') {
+        assert.equal(catalog.isSystem(k), false, `${rank} seeds system key ${k}`);
+      }
+    }
+  }
+  const archonSystem = catalog.RANK_ROLE_SEED.archon.filter((k) => catalog.isSystem(k)).sort();
+  const expected = SYSTEM_KEYS.filter((k) => catalog.byKey(k).floor === 'archon').sort();
+  assert.deepEqual(archonSystem, expected,
+    'archon holds exactly the archon-floored system keys — principals stay out of every rank-role');
+});

package/tests/governance_fold.mjs

@@ -0,0 +1,156 @@
+// tests/governance_fold.mjs — the session-load permission FOLD (task 1002556).
+//
+// DB-free. requirePermission used to cost a second round-trip on every gated
+// request (requireBuilder loads the session, then resolveHeldPermissions hits
+// the governance tables). The fold has db-kernel's lookupSession aggregate the
+// builder's raw grant keys in the SAME query; the gate then runs the pure
+// catalog-drop (the port's effectivePermissions) with no second trip.
+//
+// What must hold, and what this file pins:
+//   • the fold is an OPTIMIZATION, never an authority change — same verdicts,
+//     catalog-drop included, as the DB resolve given the same rows;
+//   • every unexpected shape FALLS BACK to the DB resolve (no raw keys on the
+//     session / an older port without the pure half / a throwing pure half) —
+//     the fold can only ever remove a round-trip, never a denial;
+//   • fail-closed posture is untouched: a missing/malformed port still denies
+//     even when raw keys are present (authority must be ESTABLISHED, ADR 0016).
+//
+// The real-DB / real-HTTP complement is tests/governance_live_proof.mjs, which
+// exercises the folded lookupSession end-to-end on a live stack.
+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 resolver = require(path.join(ROOT, 'modules', 'governance', 'resolver.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+
+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;
+}
+
+// One gate run against a stubbed port. `port` null = unregistered.
+async function run(req, port) {
+  seams._reset();
+  if (port !== null) seams.registerProvider('governance', port);
+  const res = fakeRes();
+  let nexted = false;
+  await auth.requirePermission('idea.triage')(req, res, () => { nexted = true; });
+  seams._reset();
+  return { res, nexted };
+}
+
+const BUILDER = { id: 7, rank: 'thetes' };
+// A port whose DB half counts calls and whose pure half is the REAL catalog-drop
+// (resolver.effectivePermissions is DB-free), so fold verdicts are the shipped ones.
+function countingPort(dbKeys, extra = {}) {
+  const port = {
+    dbCalls: 0,
+    resolveBuilderPermissions: async function count() { port.dbCalls += 1; return dbKeys; },
+    effectivePermissions: resolver.effectivePermissions,
+    ...extra,
+  };
+  return port;
+}
+
+test('FAST PATH: raw keys on the request admit with ZERO resolver round-trips', async () => {
+  const port = countingPort(['idea.triage']);
+  const { nexted } = await run({ builder: BUILDER, rawPermissionKeys: ['idea.triage'] }, port);
+  assert.equal(nexted, true, 'the folded grant admits');
+  assert.equal(port.dbCalls, 0, 'the DB resolve must not run — that is the whole point');
+});
+
+test('the catalog-drop still applies on the fold: a junk raw key admits nothing', async () => {
+  const port = countingPort(['idea.triage']);
+  const { res, nexted } = await run(
+    { builder: BUILDER, rawPermissionKeys: ['idea.triage.definitely-not-a-key'] }, port,
+  );
+  assert.equal(nexted, false, 'an undefined catalog key must not admit');
+  assert.equal(res._status, 403);
+  assert.equal(port.dbCalls, 0, 'denial came from the pure path, not a fallback');
+});
+
+test('no raw keys on the request → the DB resolve runs exactly as before', async () => {
+  const port = countingPort(['idea.triage']);
+  const { nexted } = await run({ builder: BUILDER, rawPermissionKeys: null }, port);
+  assert.equal(nexted, true);
+  assert.equal(port.dbCalls, 1, 'fallback = the pre-fold single DB resolve');
+});
+
+test('an older port without the pure half → DB fallback, not a crash or deny', async () => {
+  const port = countingPort(['idea.triage'], { effectivePermissions: undefined });
+  const { nexted } = await run({ builder: BUILDER, rawPermissionKeys: ['idea.triage'] }, port);
+  assert.equal(nexted, true);
+  assert.equal(port.dbCalls, 1);
+});
+
+test('a throwing pure half → DB fallback still answers', async () => {
+  const port = countingPort(['idea.triage'], { effectivePermissions: () => { throw new Error('boom'); } });
+  const { nexted } = await run({ builder: BUILDER, rawPermissionKeys: ['idea.triage'] }, port);
+  assert.equal(nexted, true);
+  assert.equal(port.dbCalls, 1);
+});
+
+test('fail-closed is untouched: raw keys present but NO port still 403s', async () => {
+  const { res, nexted } = await run({ builder: BUILDER, rawPermissionKeys: ['idea.triage'] }, null);
+  assert.equal(nexted, false, 'authority must be ESTABLISHED — raw keys alone admit nothing');
+  assert.equal(res._status, 403);
+  assert.equal(res._json.error.code, 'permission_forbidden');
+});
+
+test('the kernel shape guard: the real fragment embeds; a malformed one degrades to the base query', () => {
+  const dbKernel = require(path.join(ROOT, 'src', 'bongos', 'db-kernel.js'));
+  // A statement separator (the misregistration/injection shape) is refused —
+  // and refusal does NOT latch, so a later good registration still lands.
+  seams._reset();
+  seams.registerProvider('session-grants-sql', {
+    selectFragment: `, (SELECT 1) AS raw_permission_keys; DROP TABLE builders --`,
+  });
+  assert.equal(dbKernel.sessionPermsSelect(), '', 'a fragment with a statement separator is refused');
+  // The REAL registered fragment passes the guard verbatim.
+  seams._reset();
+  const buildGovernanceRouter = require(path.join(ROOT, 'modules', 'governance', 'routes', 'governance.js'));
+  buildGovernanceRouter();
+  const real = seams.resolveOptional('session-grants-sql').selectFragment;
+  assert.equal(dbKernel.sessionPermsSelect(), real, 'the shipped fragment embeds unchanged');
+  seams._reset();
+});
+
+test('the module registers the capability-named SQL seam the kernel embeds', () => {
+  // The kernel resolves 'session-grants-sql' and stays module-agnostic (ADR 0083
+  // §Decision #4); the governance route factory is what registers it. Pin the
+  // registration and the column contract the kernel query depends on.
+  seams._reset();
+  const buildGovernanceRouter = require(path.join(ROOT, 'modules', 'governance', 'routes', 'governance.js'));
+  buildGovernanceRouter();
+  const provider = seams.resolveOptional('session-grants-sql');
+  assert.ok(provider && typeof provider.selectFragment === 'string', 'fragment provider registered');
+  assert.match(provider.selectFragment, /AS raw_permission_keys/, 'yields the column auth.js reads');
+  assert.match(provider.selectFragment, /s\.builder_id/, 'correlates on the session query alias');
+  seams._reset();
+});
+
+test('parity: the fold and the DB resolve return the same verdict for the same rows', async () => {
+  // Same raw rows through both paths — including a junk key and a duplicate,
+  // the two shapes the fold's array_agg(DISTINCT) and the resolve differ on
+  // mechanically but must agree on semantically.
+  const rows = ['idea.triage', 'idea.triage', 'blocker.review', 'not.a.key'];
+  const foldPort = countingPort([]);
+  const dbPort = countingPort(rows);
+  const fold = await run({ builder: BUILDER, rawPermissionKeys: rows }, foldPort);
+  const db = await run({ builder: BUILDER, rawPermissionKeys: null }, dbPort);
+  assert.equal(fold.nexted, db.nexted, 'same admit/deny either way');
+  assert.equal(fold.nexted, true);
+});

package/tests/governance_fold_bench.mjs

@@ -0,0 +1,50 @@
+// tests/governance_fold_bench.mjs — the task-1002556 benchmark, re-runnable.
+//
+// Measures end-to-end latency of a requireBuilder + requirePermission route
+// (GET /governance/roles) against a LIVE server, the way the fold was graded:
+// point it at a stack before and after and compare. Asserts only route health
+// (every request 200) — the numbers are the deliverable, printed for the
+// operator to diff.
+//
+// Captured runs, docker-compose sandbox, 2026-08-06 (n=300 after 30 warmup):
+//   two-trip baseline (pre-fold main): mean 3.36ms  p50 3.30  p95 4.01  p99 5.24
+//   folded (session-load fold):        mean 3.02ms  p50 2.99  p95 3.55  p99 3.74
+// One DB round-trip's worth on a local TCP socket; the delta scales with real
+// DB latency and applies to every migrated permission gate. The companion
+// statement-log check (see the task's ship notes) showed the folded run issues
+// ONE session query (carrying raw_permission_keys) and no resolver query.
+//
+// Integration-class (needs a live server + a session): SELF-SKIPS (exit 0)
+// without GDS_BASE_URL + BENCH_TOKEN; listed in run-unit-tests.js's INTEGRATION
+// set so the DB-free lane never runs it.
+//
+// Run:  GDS_BASE_URL=http://localhost:3000 BENCH_TOKEN=<archon session token> \
+//         node tests/governance_fold_bench.mjs
+//   BENCH_N (default 300) / BENCH_WARMUP (default 30) tune the sample.
+
+import { strict as assert } from 'node:assert';
+
+const BASE = (process.env.GDS_BASE_URL || '').replace(/\/$/, '');
+const TOKEN = process.env.BENCH_TOKEN || '';
+if (!BASE || !TOKEN) {
+  console.log('governance_fold_bench.mjs SKIPPED — set GDS_BASE_URL and BENCH_TOKEN (a session token whose builder holds governance.manage).');
+  process.exit(0);
+}
+const N = Number(process.env.BENCH_N) || 300;
+const WARMUP = Number(process.env.BENCH_WARMUP) || 30;
+
+const times = [];
+for (let i = 0; i < WARMUP + N; i++) {
+  const t0 = process.hrtime.bigint();
+  const res = await fetch(`${BASE}/api/gds/governance/roles`, {
+    headers: { authorization: `Bearer ${TOKEN}` },
+  });
+  await res.json();
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+  assert.equal(res.status, 200, `request ${i} returned ${res.status} — the bench needs a healthy gated route`);
+  if (i >= WARMUP) times.push(ms);
+}
+times.sort((a, b) => a - b);
+const pct = (p) => times[Math.floor(times.length * p)].toFixed(2);
+const mean = (times.reduce((a, b) => a + b, 0) / times.length).toFixed(2);
+console.log(`governance_fold_bench: n=${N} mean=${mean}ms p50=${pct(0.5)}ms p95=${pct(0.95)}ms p99=${pct(0.99)}ms`);