@bongos/core 1.18.3 → 1.18.18

package/tests/governance_catalog.mjs

@@ -0,0 +1,129 @@
+// tests/governance_catalog.mjs — the permission catalog + compat seed (BV1.R94, ADR 0151).
+//
+// Guards the "zero day-one behavior change" promise structurally: the seed is
+// DERIVED from per-permission floors, so these invariants prove the derivation is
+// sound before R93 transcribes it into DB rows and R103 runs the live parity test.
+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 cat = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+const { PERMISSIONS, RANK_ORDER, RANK_ROLE_SEED, permissionKeys, byKey, isSystem, isGrantable, systemKeys, grantableKeys, seedForRank } = cat;
+
+test('every permission is well-formed (key, boolean system, valid floor)', () => {
+  assert.ok(PERMISSIONS.length >= 60, `expected a substantial catalog, saw ${PERMISSIONS.length}`);
+  for (const p of PERMISSIONS) {
+    assert.equal(typeof p.key, 'string');
+    assert.ok(p.key.length > 0, 'non-empty key');
+    assert.equal(typeof p.system, 'boolean', `${p.key} system must be boolean`);
+    assert.ok(p.floor === null || RANK_ORDER.includes(p.floor), `${p.key} floor "${p.floor}" invalid`);
+  }
+});
+
+test('keys are unique', () => {
+  const keys = permissionKeys();
+  assert.equal(new Set(keys).size, keys.length, 'duplicate permission key');
+});
+
+test('system and operational partition the catalog exactly', () => {
+  const sys = new Set(systemKeys());
+  const op = new Set(grantableKeys());
+  assert.equal(sys.size + op.size, PERMISSIONS.length);
+  for (const k of sys) assert.ok(!op.has(k), `${k} in both sets`);
+  // union === all
+  assert.deepEqual([...sys, ...op].sort(), permissionKeys().slice().sort());
+});
+
+test('isGrantable: operational→true, system→false, unknown→false', () => {
+  assert.equal(isGrantable('idea.triage'), true);
+  assert.equal(isGrantable('builder.rank.set'), false); // system
+  assert.equal(isGrantable('deploy.push_main'), false); // system
+  assert.equal(isGrantable('nope.not.a.key'), false); // unknown fails closed
+  assert.equal(isSystem('nope.not.a.key'), null); // unknown → null (caller fails closed)
+});
+
+test('the four rank-roles exist; seed keys all reference real permissions', () => {
+  assert.deepEqual(Object.keys(RANK_ROLE_SEED).sort(), [...RANK_ORDER].sort());
+  const all = new Set(permissionKeys());
+  for (const rank of RANK_ORDER) {
+    for (const k of RANK_ROLE_SEED[rank]) assert.ok(all.has(k), `seed[${rank}] references unknown ${k}`);
+  }
+});
+
+test('seed is cumulative: archon ⊇ metic ⊇ thetes ⊇ xenos (nested supersets)', () => {
+  for (let i = 1; i < RANK_ORDER.length; i++) {
+    const lower = new Set(RANK_ROLE_SEED[RANK_ORDER[i - 1]]);
+    const higher = new Set(RANK_ROLE_SEED[RANK_ORDER[i]]);
+    for (const k of lower) assert.ok(higher.has(k), `${RANK_ORDER[i]} missing ${k} that ${RANK_ORDER[i - 1]} has`);
+    assert.ok(higher.size > lower.size, `${RANK_ORDER[i]} should strictly extend ${RANK_ORDER[i - 1]}`);
+  }
+});
+
+test('a role holds a permission iff its floor is a real rank at-or-below (derivation is faithful)', () => {
+  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) {
+      const shouldHold = p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier;
+      assert.equal(held.has(p.key), shouldHold, `${rank} vs ${p.key} (floor ${p.floor})`);
+    }
+  }
+});
+
+test('system permissions are Archon-only in the seed (never in xenos/thetes/metic)', () => {
+  for (const rank of ['xenos', 'thetes', 'metic']) {
+    for (const k of RANK_ROLE_SEED[rank]) {
+      assert.equal(isSystem(k), false, `${rank} seed must not hold system perm ${k}`);
+    }
+  }
+  // and archon DOES hold the archon-floored system perms (that is how Archon gets its power)
+  const archon = new Set(RANK_ROLE_SEED.archon);
+  assert.ok(archon.has('builder.rank.set'));
+  assert.ok(archon.has('deploy.push_main'));
+});
+
+test('machine principals are held by NO rank-role and are system + floor null', () => {
+  for (const p of PERMISSIONS.filter((x) => x.key.startsWith('principal.'))) {
+    assert.equal(p.system, true, `${p.key} must be system`);
+    assert.equal(p.floor, null, `${p.key} must have floor null (held by no rank-role)`);
+    for (const rank of RANK_ORDER) {
+      assert.ok(!RANK_ROLE_SEED[rank].includes(p.key), `${rank} must not hold principal ${p.key}`);
+    }
+  }
+  assert.ok(PERMISSIONS.some((p) => p.key === 'principal.bfg'));
+});
+
+test('threshold spot-checks reproduce today\'s requireRank floors', () => {
+  const has = (rank, k) => RANK_ROLE_SEED[rank].includes(k);
+  // idea.triage: metic+ only (requireRank('metic','archon'))
+  assert.equal(has('xenos', 'idea.triage'), false);
+  assert.equal(has('thetes', 'idea.triage'), false);
+  assert.equal(has('metic', 'idea.triage'), true);
+  assert.equal(has('archon', 'idea.triage'), true);
+  // task.claim.any: thetes+ (the general queue)
+  assert.equal(has('xenos', 'task.claim.any'), false);
+  assert.equal(has('thetes', 'task.claim.any'), true);
+  // builder.rank.set: archon only
+  assert.equal(has('metic', 'builder.rank.set'), false);
+  assert.equal(has('archon', 'builder.rank.set'), true);
+  // task.ship / own-work: everyone incl. xenos
+  assert.equal(has('xenos', 'task.ship'), true);
+  assert.equal(has('xenos', 'task.act.own'), true);
+});
+
+test('an unknown/reserved rank resolves to no permissions (fail-closed; ADR 0151 divergence)', () => {
+  assert.deepEqual(seedForRank('olympian'), []);
+  assert.deepEqual(seedForRank('helot'), []);
+  assert.deepEqual(seedForRank('bogus'), []);
+});
+
+test('byKey returns a frozen record or null', () => {
+  const p = byKey('governance.manage');
+  assert.ok(p && p.system === true && p.floor === 'archon');
+  assert.throws(() => { p.system = false; }, /Cannot assign|read only|frozen/i);
+  assert.equal(byKey('nope'), null);
+});

package/tests/governance_claim_eligibility.mjs

@@ -0,0 +1,262 @@
+// tests/governance_claim_eligibility.mjs — claim eligibility as PERMISSIONS
+// (BV1.R106, ADR 0151).
+//
+// DB-free. The whole point of R106 is that the queue half of claim-time authority
+// stops asking "what rank is this builder" and starts asking "does this builder
+// hold `task.claim.any` / `task.claim.newcomer`" — WITHOUT changing who can claim
+// what, and WITHOUT swallowing the per-task `requires_rank` floor, which is a
+// property of the TASK and a separate axis entirely.
+//
+// Three things are proved here:
+//
+//   A. THE TWO AXES STAY SEPARATE. Holding `task.claim.any` does not lift a task's
+//      `requires_rank` floor. Behavioural (the composed gate) + structural (the
+//      permission predicate cannot even see requires_rank, and db.js still calls
+//      rankAllowsTask as its own gate at every claim site).
+//   B. THE PERMISSION PREDICATE IS CORRECT on its own terms — newcomer-only vs the
+//      general queue, and fail-closed for a builder holding no claim permission.
+//   C. RANK-BY-RANK PARITY: the new predicate admits exactly the set the old rank
+//      rule admitted. Two INDEPENDENT oracles, deliberately:
+//        • a hand-written literal table (written from ADR 0018/0034, not from any
+//          code in the repo), and
+//        • db.xenosClaimAllowed itself — the real incumbent function, which reads
+//          GENERAL_QUEUE_RANKS and knows nothing about catalog floors.
+//      The new side reads catalog.seedForRank. A check whose two sides both read
+//      catalog.floor would pass while proving nothing (the lesson tests/
+//      governance_parity.mjs writes down); neither oracle here does.
+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 LIFECYCLE = path.join(ROOT, 'modules', 'lifecycle');
+const eligibility = require(path.join(LIFECYCLE, 'claim-eligibility.js'));
+const db = require(path.join(LIFECYCLE, 'db.js'));
+const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+
+const { CLAIM_ANY, CLAIM_NEWCOMER, permissionAllowsClaim, claimEligibilityAllows } = eligibility;
+
+// The four live ranks (ADR 0018 + ADR 0034), and the newcomer_friendly values the
+// column can actually hold — it is nullable, so null/undefined must read falsey.
+const LIVE_RANKS = ['xenos', 'thetes', 'metic', 'archon'];
+const NF_VALUES = [true, false, null, undefined];
+
+// A builder's seeded permission set, as the compat seed grants it.
+const seedSet = (rank) => new Set(catalog.seedForRank(rank));
+
+// The composed claim gate, OLD and NEW, so parity is compared end to end rather
+// than one half at a time. Both call rankAllowsTask as a SEPARATE conjunct — that
+// shape is the thing under test.
+const oldGate = (rank, nf, requiresRank) =>
+  db.xenosClaimAllowed(rank, nf) && db.rankAllowsTask(rank, requiresRank);
+
+const newGate = (rank, nf, requiresRank) =>
+  claimEligibilityAllows({
+    heldPermissions: seedSet(rank),
+    newcomerFriendly: nf,
+    rankRuleAllows: db.xenosClaimAllowed(rank, nf),
+  }) && db.rankAllowsTask(rank, requiresRank);
+
+// ── the catalog anchor ───────────────────────────────────────────────────────
+
+test('the two claim keys exist in the catalog at the floors this gate assumes', () => {
+  const any = catalog.byKey(CLAIM_ANY);
+  const newcomer = catalog.byKey(CLAIM_NEWCOMER);
+  assert.ok(any, `${CLAIM_ANY} must be a real catalog permission`);
+  assert.ok(newcomer, `${CLAIM_NEWCOMER} must be a real catalog permission`);
+  assert.equal(any.floor, 'thetes', 'task.claim.any is the general queue — thetes and up');
+  assert.equal(newcomer.floor, 'xenos', 'task.claim.newcomer is held by every authenticated builder');
+  // Operational, not trust-boundary: a custom role may legitimately grant either.
+  assert.equal(any.system, false);
+  assert.equal(newcomer.system, false);
+});
+
+// ── B. the permission predicate on its own terms ─────────────────────────────
+
+test('a xenos (task.claim.newcomer only) may claim a newcomer_friendly task', () => {
+  const held = seedSet('xenos');
+  assert.ok(held.has(CLAIM_NEWCOMER));
+  assert.ok(!held.has(CLAIM_ANY), 'the xenos role must NOT hold the general-queue permission');
+  assert.equal(permissionAllowsClaim(held, true), true);
+});
+
+test('a xenos may NOT claim a general-queue task', () => {
+  const held = seedSet('xenos');
+  assert.equal(permissionAllowsClaim(held, false), false);
+  assert.equal(permissionAllowsClaim(held, null), false, 'a NULL newcomer_friendly is not "open"');
+  assert.equal(permissionAllowsClaim(held, undefined), false);
+});
+
+test('thetes and up (task.claim.any) may claim the general queue', () => {
+  for (const rank of ['thetes', 'metic', 'archon']) {
+    const held = seedSet(rank);
+    assert.ok(held.has(CLAIM_ANY), `${rank} must hold ${CLAIM_ANY}`);
+    assert.equal(permissionAllowsClaim(held, false), true, `${rank} claims the general queue`);
+    assert.equal(permissionAllowsClaim(held, true), true, `${rank} also claims newcomer rows`);
+  }
+});
+
+test('a builder holding NO claim permission is refused (fail-closed)', () => {
+  for (const nf of NF_VALUES) {
+    assert.equal(permissionAllowsClaim(new Set(), nf), false, 'empty permission set');
+    assert.equal(permissionAllowsClaim([], nf), false, 'empty array');
+    assert.equal(permissionAllowsClaim(null, nf), false, 'no set at all');
+    assert.equal(permissionAllowsClaim(['idea.triage', 'cost.log'], nf), false, 'unrelated grants');
+    assert.equal(permissionAllowsClaim(['task.claim.everything'], nf), false, 'an invented key grants nothing');
+  }
+});
+
+test('an array of keys is accepted as well as a Set (the resolver returns an array)', () => {
+  assert.equal(permissionAllowsClaim([CLAIM_ANY], false), true);
+  assert.equal(permissionAllowsClaim([CLAIM_NEWCOMER], true), true);
+  assert.equal(permissionAllowsClaim([CLAIM_NEWCOMER], false), false);
+});
+
+// ── A. the per-task requires_rank floor is a SEPARATE axis ───────────────────
+
+test('requires_rank still refuses a builder below it EVEN when they hold task.claim.any', () => {
+  // The load-bearing case. A thetes holds the general-queue permission outright,
+  // so the queue axis says yes — and the task's own floor must still say no.
+  const held = seedSet('thetes');
+  assert.ok(held.has(CLAIM_ANY));
+  assert.equal(permissionAllowsClaim(held, false), true, 'the queue axis admits them');
+  assert.equal(db.rankAllowsTask('thetes', 'metic'), false, 'the task floor does not');
+  assert.equal(newGate('thetes', false, 'metic'), false, 'the composed gate refuses');
+
+  // Same shape one rung up: a metic holds task.claim.any and is still below an
+  // archon-floored task.
+  assert.equal(permissionAllowsClaim(seedSet('metic'), false), true);
+  assert.equal(newGate('metic', false, 'archon'), false);
+
+  // ...and a newcomer_friendly flag does NOT open a floored task either: the two
+  // gates are AND-ed, so opening the door does not lower the floor.
+  assert.equal(permissionAllowsClaim(seedSet('xenos'), true), true);
+  assert.equal(newGate('xenos', true, 'metic'), false);
+});
+
+test('the permission predicate cannot see requires_rank at all (structural)', () => {
+  const src = fs.readFileSync(path.join(LIFECYCLE, 'claim-eligibility.js'), 'utf8')
+    .split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+  for (const banned of ['requires_rank', 'rankAllowsTask', 'REQUIRES_RANK_TIER']) {
+    assert.ok(!src.includes(banned), `claim-eligibility.js must not reach into the task-floor axis ("${banned}")`);
+  }
+});
+
+test('every claim path in db.js still gates on requires_rank as its own check', () => {
+  const src = fs.readFileSync(path.join(LIFECYCLE, 'db.js'), 'utf8');
+  // claimTask, claimTasksBatch, validateClaimBatch — three call sites, three
+  // separate rankAllowsTask conjuncts. If a refactor ever folds the floor into the
+  // permission predicate, this count drops and the test reds.
+  const floorChecks = src.match(/rankAllowsTask\((builderRank|builderRank), (task|t)\.requires_rank\)/g) || [];
+  assert.equal(floorChecks.length, 3, `expected 3 requires_rank gates in the claim paths, found ${floorChecks.length}`);
+  const queueChecks = src.match(/claimEligibilityAllows\(\{/g) || [];
+  assert.equal(queueChecks.length, 3, `expected 3 permission-expressed queue gates, found ${queueChecks.length}`);
+});
+
+// ── the "authority could not be established" fallback ────────────────────────
+
+test('a null permission set falls back to the incumbent rank rule, never to allow', () => {
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      const rankRuleAllows = db.xenosClaimAllowed(rank, nf);
+      assert.equal(
+        claimEligibilityAllows({ heldPermissions: null, newcomerFriendly: nf, rankRuleAllows }),
+        rankRuleAllows,
+        `${rank}/${String(nf)}: the fallback must reproduce the rank rule exactly`,
+      );
+    }
+  }
+  // ...and it is a fallback to the RULE, not an open door.
+  assert.equal(claimEligibilityAllows({ heldPermissions: null, newcomerFriendly: false, rankRuleAllows: false }), false);
+  assert.equal(claimEligibilityAllows({ heldPermissions: undefined, newcomerFriendly: true, rankRuleAllows: false }), false);
+});
+
+test('a reserved/unwired rank keeps TODAY behaviour through the fallback (no silent narrowing)', () => {
+  // A rank outside the four seeded ones resolves to zero permissions (the
+  // deliberate divergence governance_002 documents), so the claim path sees NULL
+  // and falls back — which is what keeps this swap behaviour-identical rather than
+  // quietly locking such a builder out of the newcomer queue.
+  for (const rank of ['helot', 'doulos', 'olympian', null, undefined]) {
+    assert.deepEqual(catalog.seedForRank(rank), [], `${String(rank)} has no seeded role`);
+    for (const nf of NF_VALUES) {
+      const rankRuleAllows = db.xenosClaimAllowed(rank, nf);
+      assert.equal(
+        claimEligibilityAllows({ heldPermissions: null, newcomerFriendly: nf, rankRuleAllows }),
+        rankRuleAllows,
+        `${String(rank)}/${String(nf)}`,
+      );
+    }
+  }
+});
+
+// ── C. rank-by-rank parity, against two independent oracles ──────────────────
+
+test('PARITY vs a hand-written table — the new predicate admits exactly today\'s set', () => {
+  // Written from the rules, not from the code: the sandboxed entry rank reaches
+  // only rows opened to it; thetes and up reach everything (ADR 0018 / ADR 0034).
+  // [rank][newcomer_friendly] → may claim (ignoring the task floor, tested above).
+  const EXPECTED = {
+    xenos: { true: true, false: false },
+    thetes: { true: true, false: true },
+    metic: { true: true, false: true },
+    archon: { true: true, false: true },
+  };
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      const expected = EXPECTED[rank][nf === true ? 'true' : 'false'];
+      assert.equal(
+        permissionAllowsClaim(seedSet(rank), nf),
+        expected,
+        `${rank} / newcomer_friendly=${String(nf)} should be ${expected}`,
+      );
+    }
+  }
+});
+
+test('PARITY vs db.xenosClaimAllowed — the real incumbent gate, over every live rank', () => {
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      assert.equal(
+        permissionAllowsClaim(seedSet(rank), nf),
+        db.xenosClaimAllowed(rank, nf),
+        `${rank} / newcomer_friendly=${String(nf)} diverges from the rank rule`,
+      );
+    }
+  }
+});
+
+test('PARITY of the COMPOSED gate — rank x newcomer_friendly x requires_rank', () => {
+  const REQUIRES_RANK = ['xenos', 'thetes', 'metic', 'archon', null];
+  let checked = 0;
+  for (const rank of LIVE_RANKS) {
+    for (const nf of NF_VALUES) {
+      for (const rr of REQUIRES_RANK) {
+        assert.equal(
+          newGate(rank, nf, rr),
+          oldGate(rank, nf, rr),
+          `${rank} / nf=${String(nf)} / requires_rank=${String(rr)}: permission gate diverges from the rank gate`,
+        );
+        checked++;
+      }
+    }
+  }
+  assert.equal(checked, LIVE_RANKS.length * NF_VALUES.length * REQUIRES_RANK.length);
+});
+
+test('the abuse case stays blocked: a xenos cannot reach the general queue by any route', () => {
+  const held = seedSet('xenos');
+  for (const rr of ['xenos', 'thetes', 'metic', 'archon']) {
+    assert.equal(newGate('xenos', false, rr), false, `xenos must not claim a general-queue task (requires_rank=${rr})`);
+  }
+  // Not even by holding every OTHER permission the catalog defines — only
+  // task.claim.any opens the general queue.
+  const everythingElse = catalog.permissionKeys().filter((k) => k !== CLAIM_ANY);
+  assert.equal(permissionAllowsClaim(everythingElse, false), false);
+  // And the one permission they do hold is scoped to opened rows only.
+  assert.equal(permissionAllowsClaim(held, false), false);
+  assert.equal(permissionAllowsClaim(held, true), true);
+});

package/tests/governance_config.mjs

@@ -0,0 +1,187 @@
+// tests/governance_config.mjs — the governance config contract (BV1.R96, ADR 0151).
+//
+// DB-free: exercises the PURE resolver (all inputs injected) plus the disk loader
+// against the real neutral starter. The invariants that matter here are trust-boundary
+// invariants — a config file is editable by anyone who can write the checkout, so it
+// must never be able to grant a system permission, invent a permission the catalog
+// does not define, or re-grant a seeded rank-role.
+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 config = require(path.join(GOV, 'config.js'));
+const catalog = require(path.join(GOV, 'catalog.js'));
+const { envPrefix } = require(path.join(ROOT, 'src', 'instance-config'));
+const { resolveGovernanceConfig, loadGovernanceConfig, grantableOnly, NEUTRAL_PATH, INSTANCE_PATH } = config;
+
+const NEUTRAL = JSON.parse(fs.readFileSync(NEUTRAL_PATH, 'utf8'));
+// No env by default — every precedence test injects exactly the env it is asserting on.
+const NO_ENV = {};
+
+// ── precedence: neutral -> instance -> env ──────────────────────────────────────
+
+test('neutral-only resolution yields sane defaults (the vanilla boot R102 proves)', () => {
+  const out = resolveGovernanceConfig({ neutral: NEUTRAL, env: NO_ENV });
+  assert.deepEqual(Object.keys(out.roles).sort(), [...catalog.RANK_ORDER].sort());
+  assert.equal(out.roles.metic.label, 'Metic');
+  assert.equal(out.roles.archon.seeded, true);
+  for (const rank of catalog.RANK_ORDER) {
+    assert.ok(out.roles[rank].description, `${rank} template must carry a description`);
+  }
+});
+
+test('an empty config still resolves the four rank-roles to their canonical names', () => {
+  // governance_002 seeds them unconditionally, so a missing/mangled config must fall
+  // back rather than drop a role out of the set.
+  const out = resolveGovernanceConfig({ env: NO_ENV });
+  assert.deepEqual(Object.keys(out.roles).sort(), [...catalog.RANK_ORDER].sort());
+  assert.equal(out.roles.xenos.label, 'xenos');
+});
+
+test('the instance file overrides the neutral starter, per role and per field', () => {
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { metic: { label: 'Trusted' } } },
+    env: NO_ENV,
+  });
+  assert.equal(out.roles.metic.label, 'Trusted');
+  // The untouched field survives the merge, and so do the other three roles.
+  assert.equal(out.roles.metic.description, NEUTRAL.roles.metic.description);
+  assert.equal(out.roles.archon.label, 'Archon');
+});
+
+test('the instance file may add a custom role template the neutral starter has not', () => {
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { triager: { label: 'Triager', permissions: ['idea.triage', 'blocker.review'] } } },
+    env: NO_ENV,
+  });
+  assert.equal(out.roles.triager.seeded, false);
+  assert.deepEqual(out.roles.triager.permissions, ['blocker.review', 'idea.triage']);
+});
+
+test('an env override beats both the instance file and the neutral starter', () => {
+  const env = { [`${envPrefix()}_GOVERNANCE_ROLE_LABELS`]: 'metic=Crew,archon=Captain' };
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { metic: { label: 'Trusted' } } },
+    env,
+  });
+  assert.equal(out.roles.metic.label, 'Crew');
+  assert.equal(out.roles.archon.label, 'Captain');
+  assert.equal(out.roles.xenos.label, 'Xenos', 'an unnamed role keeps its resolved label');
+});
+
+test('the env layer can relabel a role but can never grant it a permission', () => {
+  // The whole point of restricting env to labels: an env var must not widen authority.
+  const env = { [`${envPrefix()}_GOVERNANCE_ROLE_LABELS`]: 'triager=Renamed' };
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { triager: { label: 'Triager', permissions: ['idea.triage'] } } },
+    env,
+  });
+  assert.equal(out.roles.triager.label, 'Renamed');
+  assert.deepEqual(out.roles.triager.permissions, ['idea.triage']);
+});
+
+test('an env label naming a role no config defines is inert (a typo cannot grow the role set)', () => {
+  const env = { [`${envPrefix()}_GOVERNANCE_ROLE_LABELS`]: 'metics=Typo' };
+  const out = resolveGovernanceConfig({ neutral: NEUTRAL, env });
+  assert.deepEqual(Object.keys(out.roles).sort(), [...catalog.RANK_ORDER].sort());
+});
+
+// ── fail-closed: config is not a trust boundary ─────────────────────────────────
+
+test('a template naming a system permission is stripped (config cannot grant system power)', () => {
+  const systemKeys = catalog.systemKeys();
+  assert.ok(systemKeys.includes('deploy.push_main'), 'fixture guard: the catalog still flags deploy.push_main');
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { sneaky: { label: 'Sneaky', permissions: ['deploy.push_main', 'builder.rank.set', 'idea.triage'] } } },
+    env: NO_ENV,
+  });
+  assert.deepEqual(out.roles.sneaky.permissions, ['idea.triage']);
+  // Belt and braces: NO system key survives a template, whichever one is named.
+  const all = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { everything: { permissions: catalog.permissionKeys() } } },
+    env: NO_ENV,
+  });
+  for (const k of systemKeys) {
+    assert.ok(!all.roles.everything.permissions.includes(k), `config must not be able to grant system permission "${k}"`);
+  }
+  assert.deepEqual(all.roles.everything.permissions, [...catalog.grantableKeys()].sort());
+});
+
+test('a template naming an unknown permission key is dropped (the catalog is the truth)', () => {
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { odd: { permissions: ['idea.triage', 'not.a.real.permission', 'deploy.everything'] } } },
+    env: NO_ENV,
+  });
+  assert.deepEqual(out.roles.odd.permissions, ['idea.triage']);
+});
+
+test('permissions on a SEEDED rank-role are dropped wholesale (grants derive from floors)', () => {
+  const out = resolveGovernanceConfig({
+    neutral: NEUTRAL,
+    instance: { roles: { xenos: { label: 'Newcomer', permissions: ['task.create', 'audit_log.read'] } } },
+    env: NO_ENV,
+  });
+  assert.equal(out.roles.xenos.label, 'Newcomer', 'a seeded role may be relabelled');
+  assert.deepEqual(out.roles.xenos.permissions, [], 'a seeded role may never be re-granted from config');
+});
+
+test('grantableOnly de-duplicates, sorts, and rejects non-string entries', () => {
+  assert.deepEqual(grantableOnly(['cost.log', 'idea.triage', 'cost.log', 42, null]), ['cost.log', 'idea.triage']);
+  assert.deepEqual(grantableOnly(undefined), []);
+  assert.deepEqual(grantableOnly('idea.triage'), [], 'a bare string is not a permission list');
+});
+
+test('the resolved config is frozen — a caller cannot mutate it into a grant', () => {
+  const out = resolveGovernanceConfig({ neutral: NEUTRAL, env: NO_ENV });
+  assert.ok(Object.isFrozen(out) && Object.isFrozen(out.roles) && Object.isFrozen(out.roles.metic));
+  assert.throws(() => out.roles.metic.permissions.push('deploy.push_main'), TypeError);
+});
+
+// ── the neutral starter itself ──────────────────────────────────────────────────
+
+test('the neutral starter carries no host-specific identity (a vanilla instance boots from it alone)', () => {
+  // Reuses fitness.js's own definition of "host identity" so this cannot drift from
+  // the CI gate (which does not scan .json itself — IDENTITY_SCAN_EXTS is js/html/css).
+  const { scanPromptIdentity } = require(path.join(ROOT, 'scripts', 'gds', 'fitness.js'));
+  const raw = fs.readFileSync(NEUTRAL_PATH, 'utf8');
+  assert.deepEqual(scanPromptIdentity('config/governance.neutral.json', raw, '.json'), []);
+  // And it carries only templates — never a live per-builder assignment.
+  assert.deepEqual(Object.keys(NEUTRAL).filter((k) => k !== '_note'), ['roles']);
+  for (const role of Object.values(NEUTRAL.roles)) {
+    assert.ok(!('permissions' in role), 'the neutral seeded roles carry labels only, never grants');
+  }
+});
+
+test('the two config paths are the branding-shaped neutral/instance pair under config/', () => {
+  assert.equal(path.relative(ROOT, NEUTRAL_PATH).split(path.sep).join('/'), 'config/governance.neutral.json');
+  assert.equal(path.relative(ROOT, INSTANCE_PATH).split(path.sep).join('/'), 'config/governance.json');
+  assert.ok(fs.existsSync(NEUTRAL_PATH), 'the neutral starter must ship — it is the vanilla default');
+});
+
+test('loadGovernanceConfig reads the real neutral starter and tolerates a missing instance pack', () => {
+  // A vanilla instance has no config/governance.json at all — the default INSTANCE_PATH
+  // is genuinely absent in this checkout, so the default call exercises that path.
+  assert.equal(fs.existsSync(INSTANCE_PATH), false, 'fixture guard: this checkout is the vanilla case');
+  const out = loadGovernanceConfig({ env: NO_ENV });
+  assert.equal(out.roles.archon.label, 'Archon');
+  assert.deepEqual(Object.keys(out.roles).sort(), [...catalog.RANK_ORDER].sort());
+});
+
+test('the neutral starter publishes with the core (a packaged vanilla instance needs it)', () => {
+  const { isPublishable } = require(path.join(ROOT, 'scripts', 'gds', 'publish-manifest.js'));
+  assert.equal(isPublishable('config/governance.neutral.json'), true);
+  assert.equal(isPublishable('config/governance.json'), false, "a host's filled-in pack is instance content");
+});