@bongos/core 1.18.3 → 1.18.18

package/tests/reward_mode_surfacing.mjs

@@ -0,0 +1,168 @@
+// tests/reward_mode_surfacing.mjs
+//
+// Task 1002469 — "say that this instance pays cost-plus only". ADR 0146 lets an
+// instance withhold the per-task ESTIMATE payout (`mode: 'cost-plus-only'`), but
+// every builder-facing surface still advertised that estimate as if it were the
+// payout. A builder claimed a 60-credit task, shipped clean, saw `Credits +0`,
+// and spent a real session (2026-07-26) diagnosing a reward gate that was
+// working exactly as configured.
+//
+// These prove the three display seams tell the truth in cost-plus-only mode AND
+// are byte-unchanged on a default (paying) instance — the ADR's hard
+// compatibility requirement.
+//
+// Run:  node tests/reward_mode_surfacing.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const card = require('../modules/lifecycle/ship-card.js');
+const credits = require('../modules/economy/credits.js');
+const reward = require('../modules/economy/reward.js');
+const cli = require('../scripts/gds/cli-lib.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`PASS  ${name}`); }
+  catch (err) { failed++; console.log(`FAIL  ${name}\n      ${err.message}`); }
+}
+
+const CPO = { mode: 'cost-plus-only', perTaskCredit: false };
+const PAYS = { mode: 'cost-plus-and-estimate', perTaskCredit: true };
+
+// --- (1) the port exposes the policy, so nobody re-derives it ----------------
+// ADR 0146 put the mode→perTaskCredit mapping INSIDE economy on purpose. Display
+// surfaces must ASK, not reimplement `mode !== 'cost-plus-only'`.
+
+test('reward port exposes rewardConfig + rewardPolicy (display surfaces can ask)', () => {
+  assert.equal(typeof reward.rewardConfig, 'function');
+  assert.equal(typeof reward.rewardPolicy, 'function');
+  assert.equal(reward.rewardPolicy({ mode: 'cost-plus-only' }).perTaskCredit, false);
+  assert.equal(reward.rewardPolicy({}).perTaskCredit, true);
+});
+
+test('port delegates to credits (a stub bites at call time, per the reward.js contract)', () => {
+  const original = credits.rewardPolicy;
+  try {
+    credits.rewardPolicy = () => ({ mode: 'stubbed', perTaskCredit: false });
+    assert.equal(reward.rewardPolicy({}).mode, 'stubbed', 'port must delegate, not capture at load');
+  } finally { credits.rewardPolicy = original; }
+});
+
+// --- (2) the CLI prefers the SERVER's answer --------------------------------
+// The mode is INSTANCE config and config/branding.json is NOT in a builder's
+// checkout — only config/branding.neutral.json is. A laptop resolving locally
+// therefore reports the paying default on the very instance that withholds, so
+// the server value must win.
+
+test('cli rewardPolicy: a server-supplied cost-plus-only wins over local config', () => {
+  assert.equal(cli.rewardPolicy(CPO).perTaskCredit, false);
+  assert.equal(cli.rewardPolicy(CPO).mode, 'cost-plus-only');
+});
+
+test('cli rewardPolicy: no server value → falls back, never crashes', () => {
+  const p = cli.rewardPolicy(null);
+  assert.equal(typeof p.mode, 'string');
+  assert.equal(p.perTaskCredit, true, 'fallback must be the PAYING default');
+});
+
+test('cli rewardPolicy: a malformed server block degrades to the paying default', () => {
+  for (const bad of [{}, { mode: 42 }, { perTaskCredit: false }, 'nonsense', 0]) {
+    assert.equal(cli.rewardPolicy(bad).perTaskCredit, true,
+      `malformed ${JSON.stringify(bad)} must never claim "not paid"`);
+  }
+});
+
+test('cli costPlusOnlyNote: names the real payer in cost-plus-only, silent otherwise', () => {
+  const note = cli.costPlusOnlyNote(CPO);
+  assert.ok(note && /cost-plus only/i.test(note), 'must name the mode');
+  assert.ok(/not the estimate/i.test(note), 'must say the estimate is not what pays');
+  assert.equal(cli.costPlusOnlyNote(PAYS), null, 'a paying instance shows nothing');
+  assert.equal(cli.costPlusOnlyNote(null), null);
+});
+
+// --- (3) the ship completion card explains a correct +0 ---------------------
+
+const shipped = {
+  postGradeStatus: 'shipped', taskId: 1002469, title: 't', valueSummary: 'v',
+  grade: { passed: true }, fileCount: 1, added: 1, removed: 0,
+  usage: { tokens: 1000, costUsd: 0.1 }, deploy: { commit: 'abc1234' },
+};
+const creditsRow = (m) => { const r = m.rows.find((x) => x.k === 'Credits'); return r ? r.v : undefined; };
+
+test('ship card: cost-plus-only annotates the +0 so it does not read as a bug', () => {
+  const v = creditsRow(card.buildCardModel({
+    ...shipped, credits: { awarded: 0, total: 5321, perTaskCredit: false },
+  }));
+  assert.match(v, /est\. not paid \(cost-plus only\)/, 'the 0 must explain itself');
+});
+
+test('ship card: a PAYING instance is byte-unchanged (ADR 0146 compatibility)', () => {
+  const withFlag = creditsRow(card.buildCardModel({
+    ...shipped, credits: { awarded: 18, total: 5321, perTaskCredit: true },
+  }));
+  const withoutFlag = creditsRow(card.buildCardModel({
+    ...shipped, credits: { awarded: 18, total: 5321 },
+  }));
+  assert.equal(withFlag, withoutFlag, 'the flag must not perturb a paying instance');
+  assert.doesNotMatch(withFlag, /cost-plus only/);
+});
+
+test('ship card: an ABSENT perTaskCredit (older caller) assumes paying, adds nothing', () => {
+  const v = creditsRow(card.buildCardModel({ ...shipped, credits: { awarded: 0, total: 5321 } }));
+  assert.doesNotMatch(v, /cost-plus only/, 'absent ⇒ paying default, never a wrong "not paid"');
+});
+
+// --- (4) the hall never drops "Est." when the instance does not pay ---------
+// The live bug: taskCreditValue falls back to the ESTIMATE when a settled task
+// has credits_awarded === 0, and under cost-plus-only that is EVERY shipped
+// task. The plain (non-"Est.") label then presents that estimate as the actual
+// ledger payout. Driven against the real file so the assertion can't drift.
+
+function loadBrandApply(rewardBlock) {
+  const src = fs.readFileSync(new URL('../modules/hall-ui/public/brand-apply.js', import.meta.url), 'utf8');
+  const window = { __BRANDING__: { currency: { label: 'credits' }, reward: rewardBlock } };
+  const document = {
+    getElementById: () => null, querySelector: () => null, querySelectorAll: () => [],
+    readyState: 'complete', addEventListener: () => {}, title: '',
+    createTreeWalker: () => ({ nextNode: () => null }),
+  };
+  new Function('window', 'document', 'NodeFilter', src)(window, document, { SHOW_TEXT: 4 });
+  return window.OTBBranding;
+}
+
+const SHIPPED_TASK = { status: 'shipped', credits_awarded: 0, credits_reward: 60 };
+const READY_TASK = { status: 'ready', credits_reward: 60 };
+
+test('hall: cost-plus-only keeps "Est." on a SHIPPED task (the 60 is not a payout)', () => {
+  const B = loadBrandApply(CPO);
+  assert.equal(B.taskCreditLabel(SHIPPED_TASK), 'credits Est.',
+    'dropping "Est." presents the unpaid estimate as the real payout');
+  assert.equal(B.taskCreditLabel(READY_TASK), 'credits Est.');
+  assert.equal(B.perTaskCredit(), false);
+});
+
+test('hall: a PAYING instance keeps the original settled/unsettled split', () => {
+  const B = loadBrandApply(PAYS);
+  assert.equal(B.taskCreditLabel(SHIPPED_TASK), 'credits', 'settled ⇒ plain label, unchanged');
+  assert.equal(B.taskCreditLabel(READY_TASK), 'credits Est.');
+  assert.equal(B.perTaskCredit(), true);
+});
+
+test('hall: an OLDER server (no reward block) behaves exactly as before', () => {
+  const B = loadBrandApply(undefined);
+  assert.equal(B.perTaskCredit(), true, 'absent ⇒ paying default');
+  assert.equal(B.taskCreditLabel(SHIPPED_TASK), 'credits');
+  assert.equal(B.rewardModeNote(), '', 'no note on a paying/unknown instance');
+});
+
+test('hall: the tooltip names the mode and what actually pays', () => {
+  const note = loadBrandApply(CPO).rewardModeNote();
+  assert.match(note, /cost-plus only/i);
+  assert.match(note, /guide, not a payout/i);
+});
+
+console.log(`\nreward_mode_surfacing: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/route_permission_check.mjs

@@ -0,0 +1,301 @@
+// tests/route_permission_check.mjs — the route auditor understands PERMISSION gates
+// (BV1.R109, ADR 0151).
+//
+// WHY THIS FILE EXISTS. src/bongos/route-rank-check.js is a trust primitive: a CI gate
+// that hard-fails the build when a write route is ungated or silently downgraded. Before
+// R109 it only recognised requireRank/requireBuilder/requireBfgPrincipal. Because
+// `requirePermission` must mount AFTER `requireBuilder`, a route migrated to the
+// permission gate fell through to the requireBuilder arm and classified 'any-builder' —
+// a downgrade that reads as legitimate, and a published API doc that misstates authority.
+//
+// THE ORACLE PROBLEM (the trap R103 fell into). The classifier DERIVES a permission's
+// rank from modules/governance/catalog.js, so asserting it back against catalog.floor
+// would move both sides together and prove nothing. Every expectation below is therefore
+// either a HAND-WRITTEN literal (a floor read off the catalog once, by a human, and
+// frozen here — so a floor edit reds this file and has to be argued with) or
+// auth.rankMeetsThreshold, the real production threshold function. The ONE place the
+// catalog is used as an oracle is the source-parser drift check (P0), where the two
+// sides are genuinely different mechanisms: a regex over the file's text vs. Node
+// evaluating the module.
+//
+// DB-free. Run:  node --test tests/route_permission_check.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+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 rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+const auth = require(path.join(ROOT, 'src', 'bongos', 'auth.js'));
+const genApiDocs = require(path.join(ROOT, 'scripts', 'gds', 'gen-api-docs.js'));
+
+const rankOf = (src) => rrc.classifyText(src)[0].rank;
+const rowOf = (src) => rrc.classifyText(src)[0];
+
+// A hand-written floor table: each atom's floor as declared in catalog.js, transcribed
+// here ONCE by hand. This is the independent side of every classification assertion
+// below — if someone lowers `backup.manage` to 'xenos', the classifier follows the
+// catalog and this file goes red, which is the whole point.
+const HAND_WRITTEN_FLOORS = {
+  'builder.rank.set': 'archon',
+  'audit_log.read': 'archon',
+  'auth.session.revoke': 'archon',
+  'builder.roster.read': 'archon',
+  'builder.status.set': 'archon',
+  'backup.manage': 'metic',
+  'idea.triage': 'metic',
+  'security.report.file': 'metic',
+  'task.claim.any': 'thetes',
+  'idea.file': 'xenos',
+  'cost.log': 'xenos',
+};
+
+// ═══ P0 — the source parser is faithful to the catalog it reads ═══════════════
+// route-rank-check reads catalog.js as DATA (fs + regex), never require() — ADR 0083's
+// one-way rule forbids core importing a module, and fitness.js enforces it on require
+// edges. That parse must not silently drop or mis-read an atom, so pin it against the
+// catalog as Node actually evaluates it. Two different mechanisms, so this is a real
+// oracle, not a tautology.
+
+test('P0: the parsed floor map matches the catalog module exactly (key set and floors)', () => {
+  const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+  const parsed = rrc.permissionFloors();
+  const evaluated = new Map(catalog.PERMISSIONS.map((p) => [p.key, p.floor]));
+  assert.equal(parsed.size, evaluated.size,
+    `parser found ${parsed.size} atoms, the catalog defines ${evaluated.size} — the source-shape parse has drifted`);
+  const drift = [];
+  for (const [key, floor] of evaluated) {
+    if (parsed.get(key) !== floor) drift.push(`${key}: catalog '${floor}' vs parsed '${parsed.get(key)}'`);
+  }
+  assert.deepEqual(drift, []);
+});
+
+test('P0: core reads the catalog as DATA — no require() edge into modules/', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'), 'utf8');
+  const codeLines = src.split('\n').filter((l) => !/^\s*(\/\/|\*|\/\*)/.test(l));
+  assert.equal(codeLines.some((l) => /require\(\s*['"][^'"]*modules\//.test(l)), false,
+    'route-rank-check.js must not require() a module — read the catalog off disk (ADR 0083)');
+});
+
+test('P0: an unreadable or empty catalog THROWS rather than degrading to "nothing is gated"', () => {
+  assert.throws(() => rrc.permissionFloors(path.join(os.tmpdir(), 'definitely-not-a-catalog.js')),
+    /unreadable/, 'a missing catalog must be a broken install, not an opted-out module');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpc-cat-'));
+  const emptyCatalog = path.join(dir, 'catalog.js');
+  fs.writeFileSync(emptyCatalog, '// a catalog with no entries\n');
+  assert.throws(() => rrc.permissionFloors(emptyCatalog), /declares no permissions/);
+  fs.rmSync(dir, { recursive: true, force: true });
+  // And the pure half: with no floor data, every atom is unverifiable — never gated.
+  const empty = rrc.parsePermissionFloors('// a catalog with no entries\n');
+  assert.equal(empty.size, 0);
+  assert.equal(rrc.rankForPermissions(['backup.manage'], empty), 'unknown');
+});
+
+// ═══ P1 — classification: a permission gate resolves to its real floor ════════
+
+test('P1: requirePermission resolves to the atom floor, NOT any-builder', () => {
+  for (const [key, floor] of Object.entries(HAND_WRITTEN_FLOORS)) {
+    const src = `router.post('/x', auth.requireBuilder, auth.requirePermission('${key}'), h);`;
+    const expected = floor === 'archon' ? 'archon' : floor === 'metic' ? 'metic+archon' : 'any-builder';
+    assert.equal(rankOf(src), expected,
+      `requirePermission('${key}') (floor ${floor}) must classify '${expected}'`);
+  }
+});
+
+test('P1: the label agrees with the REAL threshold function over the whole rank ladder', () => {
+  // auth.rankMeetsThreshold is the production gate. For every atom, the label the
+  // classifier emits must admit exactly the ranks the atom's floor admits — so the
+  // label is a faithful restatement of enforcement, not a parallel opinion.
+  const { RANKS } = require(path.join(ROOT, 'src', 'bongos', 'db-kernel.js'));
+  const LABEL_ADMITS = {
+    archon: (rank) => auth.rankMeetsThreshold(rank, ['archon']),
+    'metic+archon': (rank) => auth.rankMeetsThreshold(rank, ['metic']),
+    'any-builder': (rank) => auth.rankMeetsThreshold(rank, ['xenos']),
+  };
+  for (const [key, floor] of Object.entries(HAND_WRITTEN_FLOORS)) {
+    const label = rankOf(`router.post('/x', auth.requireBuilder, auth.requirePermission('${key}'), h);`);
+    for (const rank of RANKS) {
+      // 'thetes'-floored atoms are the one documented approximation: the label
+      // vocabulary has no thetes tier, so they read 'any-builder' — the label may
+      // UNDER-report strictness, never over-report it.
+      const strictEnough = auth.rankMeetsThreshold(rank, [floor]);
+      if (LABEL_ADMITS[label](rank)) continue; // label denies nothing the floor allows
+      assert.equal(strictEnough, false,
+        `${key}: rank ${rank} clears the real floor '${floor}' but label '${label}' would deny it`);
+    }
+  }
+});
+
+test('P1: AND semantics — a multi-atom gate takes the STRICTEST floor', () => {
+  const src = "router.post('/x', auth.requireBuilder, auth.requirePermission('idea.file', 'audit_log.read'), h);";
+  assert.equal(rankOf(src), 'archon',
+    'requirePermission ANDs, so the gate is as strict as its strictest atom (archon), not its loosest');
+  const src2 = "router.post('/x', auth.requireBuilder, auth.requirePermission('cost.log', 'backup.manage'), h);";
+  assert.equal(rankOf(src2), 'metic+archon');
+  // order must not matter
+  const src3 = "router.post('/x', auth.requireBuilder, auth.requirePermission('audit_log.read', 'idea.file'), h);";
+  assert.equal(rankOf(src3), 'archon');
+});
+
+test('P1: the module doorway spelling (api.requirePermission) classifies identically', () => {
+  assert.equal(rankOf("router.post('/x', api.requireBuilder, api.requirePermission('backup.manage'), h);"), 'metic+archon');
+});
+
+test('P1: a stricter requireRank beside a permission gate is NOT understated', () => {
+  // The two gates AND. Reporting the looser one would understate authority in the docs.
+  const src = "router.post('/x', auth.requireBuilder, auth.requireRank('archon'), auth.requirePermission('idea.file'), h);";
+  assert.equal(rankOf(src), 'archon');
+});
+
+test('P1: the row carries the atoms it gates on', () => {
+  const r = rowOf("router.post('/x', auth.requireBuilder, auth.requirePermission('backup.manage'), h);");
+  assert.deepEqual(r.perms, ['backup.manage']);
+  assert.equal(rowOf("router.post('/x', auth.requireRank('archon'), h);").perms, null,
+    'a rank-gated route names no atoms');
+});
+
+// ═══ P2 — fail-closed: unverifiable never reads as gated ══════════════════════
+
+test('P2: an UNKNOWN/typo permission key fails closed to unknown, even beside requireBuilder', () => {
+  // The dangerous shape: requirePermission MUST mount after requireBuilder, so a typo'd
+  // atom (which grants nothing) sits next to a real authentication middleware. If the
+  // classifier deferred to that requireBuilder the route would read 'any-builder' — i.e.
+  // gated — while enforcing a permission nobody holds.
+  const src = "router.post('/x', auth.requireBuilder, auth.requirePermission('backup.manag'), h);";
+  assert.equal(rankOf(src), 'unknown', "a misspelled atom must surface, not hide behind requireBuilder");
+  assert.equal(rrc.rankForPermissions(['not.a.real.permission']), 'unknown');
+  // ...and one bad atom poisons the whole gate, even mixed with good ones.
+  assert.equal(rrc.rankForPermissions(['audit_log.read', 'not.a.real.permission']), 'unknown');
+});
+
+test('P2: a PRINCIPAL atom (floor null) fails closed — no rank-role holds it', () => {
+  // principal.* is gated on an exact builders.system_role, never on a role, so
+  // requirePermission('principal.bfg') would deny everyone. A route wanting it must use
+  // requireBfgPrincipal; classifying it as some rank would be a lie either way.
+  assert.equal(rrc.rankForPermissions(['principal.bfg']), 'unknown');
+  assert.equal(rankOf("router.post('/x', auth.requireBuilder, auth.requirePermission('principal.bfg'), h);"), 'unknown');
+});
+
+test('P2: an EMPTY permission gate fails closed', () => {
+  assert.equal(rankOf("router.post('/x', auth.requireBuilder, auth.requirePermission(), h);"), 'unknown');
+  assert.equal(rrc.rankForPermissions([]), 'unknown');
+});
+
+test('P2: a write route with NO gate at all still hard-fails the build', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpc-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'), "  router.post('/demo/ping', h);\n");
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, 'no-modules') });
+  fs.rmSync(dir, { recursive: true, force: true });
+  const ping = res.findings.find((f) => f.route === 'POST /demo/ping');
+  assert.ok(ping, 'an ungated write route must surface a finding');
+  assert.equal(ping.severity, 'blocker');
+  assert.equal(res.hardFail, true);
+});
+
+test('P2: a write route gated on a TYPO permission also hard-fails the build', () => {
+  // The regression this task exists to prevent: the migration must not be able to turn
+  // a gated write route into an ungated one that still looks gated.
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpc-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'),
+    "  router.post('/demo/ping', auth.requireBuilder, auth.requirePermission('bakcup.manage'), h);\n");
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, 'no-modules') });
+  fs.rmSync(dir, { recursive: true, force: true });
+  assert.equal(res.hardFail, true, 'an unresolvable permission gate on a write route is a hard fail');
+  assert.equal(res.findings[0].severity, 'blocker');
+});
+
+test('P2: a correctly permission-gated write route does NOT trip a false blocker', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpc-'));
+  fs.writeFileSync(path.join(dir, 'shim.js'),
+    "  router.post('/demo/ping', auth.requireBuilder, auth.requirePermission('backup.manage'), h);\n");
+  const res = rrc.checkRouteRanks({ routesDir: dir, modulesDir: path.join(dir, 'no-modules') });
+  fs.rmSync(dir, { recursive: true, force: true });
+  assert.equal(res.findings.filter((f) => f.route === 'POST /demo/ping').length, 0);
+});
+
+// ═══ P3 — pins are satisfied by BOTH gate forms (the migration window) ════════
+
+test('P3: a permission pin is satisfied by the requirePermission form', () => {
+  const r = rowOf("router.patch('/builders/:id/rank', auth.requireBuilder, auth.requirePermission('builder.rank.set'), h);");
+  assert.equal(rrc.pinMismatch('perm:builder.rank.set', r), null);
+});
+
+test('P3: the SAME permission pin is satisfied by the pre-migration requireRank form', () => {
+  const r = rowOf("router.patch('/builders/:id/rank', auth.requireBuilder, auth.requireRank('archon'), h);");
+  assert.equal(rrc.pinMismatch('perm:builder.rank.set', r), null,
+    'an un-migrated route must still clear its permission pin, or R104/R105 deadlock');
+});
+
+test('P3: a rank pin is satisfied by BOTH forms too', () => {
+  const viaRank = rowOf("router.get('/backup/status', auth.requireBuilder, auth.requireRank('metic', 'archon'), h);");
+  const viaPerm = rowOf("router.get('/backup/status', auth.requireBuilder, auth.requirePermission('backup.manage'), h);");
+  assert.equal(rrc.pinMismatch('metic+archon', viaRank), null);
+  assert.equal(rrc.pinMismatch('metic+archon', viaPerm), null);
+});
+
+test('P3: a permission pin still catches a DOWNGRADE in either form', () => {
+  const downgradedRank = rowOf("router.patch('/builders/:id/rank', auth.requireBuilder, h);");
+  assert.match(rrc.pinMismatch('perm:builder.rank.set', downgradedRank) || '', /any-builder/);
+  const wrongAtom = rowOf("router.patch('/builders/:id/rank', auth.requireBuilder, auth.requirePermission('idea.file'), h);");
+  assert.ok(rrc.pinMismatch('perm:builder.rank.set', wrongAtom), 'gating on a different atom must red');
+});
+
+test('P3: a pin naming an atom the catalog does not define is itself a finding', () => {
+  const r = rowOf("router.patch('/x', auth.requireBuilder, auth.requireRank('archon'), h);");
+  assert.match(rrc.pinMismatch('perm:no.such.atom', r) || '', /does not define/);
+});
+
+test('P3: parsePin round-trips both spellings', () => {
+  assert.deepEqual(rrc.parsePin('archon'), { kind: 'rank', rank: 'archon' });
+  assert.deepEqual(rrc.parsePin('perm:a.b, c.d'), { kind: 'permission', perms: ['a.b', 'c.d'] });
+});
+
+// ═══ P4 — the published docs stop lying ══════════════════════════════════════
+
+test('P4: gen-api-docs labels a permission-gated route by its floor, not any-builder', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpc-doc-'));
+  const abs = path.join(dir, 'demo.js');
+  fs.writeFileSync(abs, [
+    "  // Trigger a backup.",
+    "  router.post('/backup/trigger', auth.requireBuilder, auth.requirePermission('backup.manage'), h);",
+    '',
+    "  // Read the audit log.",
+    "  router.get('/audit-log', auth.requireBuilder, auth.requirePermission('audit_log.read'), h);",
+    '',
+  ].join('\n'));
+  const model = genApiDocs.extractModel({ routeFiles: [{ abs, rel: 'src/bongos/routes/demo.js' }] });
+  fs.rmSync(dir, { recursive: true, force: true });
+
+  const trigger = model.find((r) => r.route === '/backup/trigger');
+  const audit = model.find((r) => r.route === '/audit-log');
+  assert.equal(trigger.rank, 'metic+archon', 'the published rank must be the real floor');
+  assert.equal(audit.rank, 'archon');
+  assert.deepEqual(trigger.perms, ['backup.manage'], 'the docs also name the authority atom');
+
+  const spec = genApiDocs.buildOpenapi(model);
+  const op = spec.paths['/backup/trigger'].post;
+  assert.equal(op['x-rank'], 'metic+archon');
+  assert.deepEqual(op['x-permissions'], ['backup.manage']);
+  assert.match(op.description, /backup\.manage/);
+
+  const md = genApiDocs.buildReferenceMd(model, spec);
+  assert.match(md, /\/backup\/trigger` \| `metic\+archon`/,
+    'the reference table must print the real gate, not any-builder');
+});
+
+test('P4: a rank-gated route carries no x-permissions (todays spec stays byte-identical)', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rpc-doc-'));
+  const abs = path.join(dir, 'demo.js');
+  fs.writeFileSync(abs, "  router.post('/legacy', auth.requireBuilder, auth.requireRank('archon'), h);\n");
+  const model = genApiDocs.extractModel({ routeFiles: [{ abs, rel: 'src/bongos/routes/demo.js' }] });
+  fs.rmSync(dir, { recursive: true, force: true });
+  const spec = genApiDocs.buildOpenapi(model);
+  const op = spec.paths['/legacy'].post;
+  assert.equal(op['x-rank'], 'archon');
+  assert.equal('x-permissions' in op, false);
+});