@bongos/core 1.19.185 → 1.19.187

package/docs/api-reference.md

@@ -218,15 +218,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
-| GET | `/api/bongos/government/assignments` | `archon` | — | government.manage — every builder↔role assignment row. |
-| POST | `/api/bongos/government/assignments` | `archon` | `builder_id`, `rank_key` | government.manage — assign a CUSTOM role to a builder. |
-| DELETE | `/api/bongos/government/assignments/:builderId/:rankKey` | `archon` | — | government.manage — remove a custom-role assignment. |
+| GET | `/api/bongos/government/assignments` | `archon` | — | government.manage — every builder↔rank assignment row. |
+| POST | `/api/bongos/government/assignments` | `archon` | `builder_id`, `rank_key` | government.manage — assign a CUSTOM rank to a builder. |
+| DELETE | `/api/bongos/government/assignments/:builderId/:rankKey` | `archon` | — | government.manage — remove a custom-rank assignment. |
 | GET | `/api/bongos/government/permissions` | `archon` | — | government.manage — the permission catalog + principals, straight from code (the catalog is CODE, not a table); no DB read. |
-| GET | `/api/bongos/government/ranks` | `archon` | — | government.manage — the full role list with each role's grants. |
-| POST | `/api/bongos/government/ranks` | `archon` | `rank_key`, `label`, `description` | government.manage — create a CUSTOM role (is_system false, no seeded_rank — the seeded four exist only via governance_002). |
-| PUT | `/api/bongos/government/ranks/:rankKey/permissions/:permissionKey` | `archon` | — | government.manage — grant one permission to a role (the toggle's ON half). |
+| GET | `/api/bongos/government/ranks` | `archon` | — | government.manage — the full rank list with each rank's grants. |
+| POST | `/api/bongos/government/ranks` | `archon` | `rank_key`, `label`, `description` | government.manage — create a CUSTOM rank (is_system false, no seeded_rank — the seeded four exist only via governance_002). |
+| PUT | `/api/bongos/government/ranks/:rankKey/permissions/:permissionKey` | `archon` | — | government.manage — grant one permission to a rank (the toggle's ON half). |
 | DELETE | `/api/bongos/government/ranks/:rankKey/permissions/:permissionKey` | `archon` | — | government.manage — revoke a grant (the toggle's OFF half). |
-| POST | `/api/bongos/government/ranks/:rankKey/reset` | `archon` | — | government.manage — restore a SEEDED rank-role to its catalog default (ADR 0172). |
+| POST | `/api/bongos/government/ranks/:rankKey/reset` | `archon` | — | government.manage — restore a SEEDED rank to its catalog default (ADR 0172). |
 
 ## `grades` (1)
 

package/modules/builder-settings/wandering-prefs.js

@@ -125,27 +125,27 @@ const LEVEL_CONTRACT = Object.freeze({
 // not name carries NO wandering metadata and resolves to the safest floor
 // (Locked), the same fail-closed posture the resolver takes for a rank with no
 // seeded role.
-const ROLE_WANDERING = Object.freeze({
+const RANK_WANDERING = Object.freeze({
   xenos: Object.freeze({ default: 0, ceiling: 0 }),
   thetes: Object.freeze({ default: 1, ceiling: 1 }),
   metic: Object.freeze({ default: 2, ceiling: 3 }),
   archon: Object.freeze({ default: 3, ceiling: 3 }),
 });
-const NO_ROLE_WANDERING = Object.freeze({ default: 0, ceiling: 0 });
+const NO_RANK_WANDERING = Object.freeze({ default: 0, ceiling: 0 });
 
-function roleWandering(roleKey) {
-  return Object.prototype.hasOwnProperty.call(ROLE_WANDERING, roleKey)
-    ? ROLE_WANDERING[roleKey]
-    : NO_ROLE_WANDERING;
+function rankWandering(rankKey) {
+  return Object.prototype.hasOwnProperty.call(RANK_WANDERING, rankKey)
+    ? RANK_WANDERING[rankKey]
+    : NO_RANK_WANDERING;
 }
 
 // DERIVED projections of the metadata above, kept because scripts/gds/session-eval.js
 // and the /me payload read them by rank. Deriving them means the two views cannot drift.
 const RANK_DEFAULT = Object.freeze(
-  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.default])),
+  Object.fromEntries(Object.entries(RANK_WANDERING).map(([role, meta]) => [role, meta.default])),
 );
 const RANK_MAX = Object.freeze(
-  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.ceiling])),
+  Object.fromEntries(Object.entries(RANK_WANDERING).map(([role, meta]) => [role, meta.ceiling])),
 );
 
 const TOP_LEVEL = LEVELS.length - 1; // 3
@@ -160,7 +160,7 @@ for (const key of LEVELS) {
 for (let i = 0; i < LEVELS.length; i++) {
   if (LEVEL_META[LEVELS[i]].n !== i) throw new Error(`wandering-prefs: LEVEL_META.${LEVELS[i]}.n must equal its index ${i}`);
 }
-for (const [role, meta] of Object.entries(ROLE_WANDERING)) {
+for (const [role, meta] of Object.entries(RANK_WANDERING)) {
   if (!isLevelInt(meta.default)) throw new Error(`wandering-prefs: role '${role}' has a non-level default`);
   if (!isLevelInt(meta.ceiling)) throw new Error(`wandering-prefs: role '${role}' has a non-level ceiling`);
   if (meta.default > meta.ceiling) throw new Error(`wandering-prefs: default > ceiling for role '${role}'`);
@@ -182,11 +182,11 @@ function levelIndex(key) {
 }
 
 function defaultLevelForRank(rank) {
-  return roleWandering(rank).default;
+  return rankWandering(rank).default;
 }
 
 function maxLevelForRank(rank) {
-  return roleWandering(rank).ceiling;
+  return rankWandering(rank).ceiling;
 }
 
 // The override a builder has stored (the raw 'wandering' key off behavior_prefs),
@@ -303,8 +303,8 @@ module.exports = {
   LEVELS,
   LEVEL_META,
   LEVEL_CONTRACT,
-  ROLE_WANDERING,
-  roleWandering,
+  RANK_WANDERING,
+  rankWandering,
   RANK_DEFAULT,
   RANK_MAX,
   TOP_LEVEL,

package/modules/government/catalog.js

@@ -1,44 +1,44 @@
-// modules/governance/catalog.js — the permission catalog + compatibility seed.
+// modules/government/catalog.js — the permission catalog + compatibility seed.
 //
 // The single CODE source of truth for authority atoms (ADR 0151, BV1.R94). Every
 // permission is a stable string key that maps to a REAL server capability (a route,
 // a claim rule, a page) — a permission no route consumes does not exist. The
-// resolver (R95), the requirePermission gate (R97), R93's role seed, and the Archon
+// resolver (R95), the requirePermission gate (R97), R93's rank seed, and the Archon
 // tab (R110/R111) all read from here; the enumerated catalog it transcribes is
 // docs/adr/0151-governance-permissions-as-atom-ranks-as-roles.md, grounded in
 // docs/governance/authority-sweep-2026-07-24.md.
 //
 // Two orthogonal axes per permission:
-//   • system  — true  = trust-boundary. The governance API (R110) rejects adding it
-//               to a CUSTOM role and the tab renders it LOCKED there; it is deploy/
+//   • system  — true  = trust-boundary. The government API (R110) rejects adding it
+//               to a CUSTOM rank and the tab renders it LOCKED there; it is deploy/
 //               protected-path/rank-set/version-close/grade-bypass/cross-tier/
 //               principal power, enforced by the out-of-band substrate (ADR 0043)
-//               or reserved to Archon. The built-in `archon` rank-role legitimately
+//               or reserved to Archon. The built-in `archon` rank legitimately
 //               HOLDS the archon-floored system perms.
-//             — false = operational, freely composable into a custom role.
+//             — false = operational, freely composable into a custom rank.
 //             `system` is NOT the whole grantability answer any more — see the
-//             `substrate` axis below and `isGrantableTo()`, which is per-ROLE.
+//             `substrate` axis below and `isGrantableTo()`, which is per-RANK.
 //   • substrate — true = this key's authority is enforced OUTSIDE the app, by the
 //               pre-push hook / main-audit / the rank floor the git and ssh layers
 //               read (ADR 0043). A grant row for one is INERT: no route consumes it
 //               through requirePermission, so granting it would be a toggle that
 //               looks like it worked and changes nothing. Therefore non-grantable to
-//               EVERY role, seeded rank-roles included — the one wall ADR 0172's
+//               EVERY rank, seeded ranks included — the one wall ADR 0172's
 //               widening deliberately did not move, because moving it would make the
 //               tab lie rather than delegate. Implies system:true + floor 'archon'.
 //   • floor   — the rank that holds this permission TODAY via the compat seed
 //               ('xenos' < 'thetes' < 'metic' < 'archon'), or null for a machine
-//               PRINCIPAL permission held by NO rank-role (gated on exact
-//               system_role, never a human/role — ADR 0151 §3). floor drives the
+//               PRINCIPAL permission held by NO rank (gated on exact
+//               system_role, never a human/rank — ADR 0151 §3). floor drives the
 //               seed derivation below; it is seed DATA, not grantability (the
 //               `system` flag is the wall). Ownership-scoped + baseline own-work
 //               perms floor at 'xenos' (every authenticated builder holds them).
 //
 // PRINCIPALS — the second authority AXIS (BV1.R98, ADR 0151 §3). A builder's
-// authority is the UNION of their ROLES; a machine principal's authority is its
+// authority is the UNION of their RANKS; a machine principal's authority is its
 // IDENTITY. Those are different axes and the model keeps them apart: a principal
 // permission carries `principal: '<system_role>'` and `floor: null`, so it is in
-// NO rank-role (not even archon's) and no custom role may hold it (`system:true`).
+// NO rank (not even archon's) and no custom rank may hold it (`system:true`).
 // The two are a PARTITION, asserted at load: floor:null ⟺ principal set. The only
 // source of a principal permission is resolver.resolvePrincipalPermissions(), keyed
 // on the exact `builders.system_role` value — a column with no API writer at all
@@ -77,10 +77,10 @@
 // Archon included), and minting a key no route consumes to satisfy a symmetry
 // check would violate this module's first rule.
 //
-// The RANK_ROLE_SEED is DERIVED from floors (cumulative nested supersets), so the
+// The RANK_SEED is DERIVED from floors (cumulative nested supersets), so the
 // "zero day-one behavior change" parity (R103) is structural, not hand-maintained:
-// role(rank) = { p : p.floor !== null and tier(p.floor) <= tier(rank) }, and the
-// resolver's UNION over a builder's one rank-role reproduces requireRank's
+// rank(rank) = { p : p.floor !== null and tier(p.floor) <= tier(rank) }, and the
+// resolver's UNION over a builder's one rank reproduces requireRank's
 // at-or-above threshold exactly.
 
 'use strict';
@@ -96,7 +96,7 @@ const PERMISSIONS = [
   // ── system: true — trust-boundary (substrate- or Archon-enforced) ─────────────
   //
   // The seven WITHOUT `substrate` are in-app Archon powers: a real route reads them
-  // through requirePermission, so granting one to a sub-Archon rank-role genuinely
+  // through requirePermission, so granting one to a sub-Archon rank genuinely
   // delegates it (ADR 0172, the owner's lever). The three WITH `substrate: true` are
   // enforced out of band and can never be delegated by a row in this database.
   { key: 'builder.rank.set', system: true, floor: 'archon', guards: 'PATCH /builders/:id/rank — the single rank writer' },
@@ -104,15 +104,15 @@ const PERMISSIONS = [
   { key: 'task.confirm.grade_bypass', system: true, floor: 'archon', guards: 'POST /tasks/:id/confirm — ratify past a failed grade (env-relaxable, ADR 0041)' },
   { key: 'dependency.cross_tier.manage', system: true, floor: 'archon', guards: 'POST|DELETE /dependencies — cross-tier structural edges (ADR 0086)' },
   { key: 'goal.scope.manage', system: true, floor: 'archon', guards: 'cross-tier goal-scope edges + protected-scope admission (ADR 0086)' },
-  { key: 'government.manage', system: true, floor: 'archon', guards: 'the governance tab routes (roles/perms/assignments CRUD, reads included — R110) — meta-escalation' },
+  { key: 'government.manage', system: true, floor: 'archon', guards: 'the Government tab routes (ranks/perms/assignments CRUD, reads included — R110) — meta-escalation' },
   { key: 'gate_approval.decide', system: true, floor: 'archon', guards: 'POST /gate-approvals/:pr/approve — CI deploy-gate override' },
   { key: 'deploy.push_main', system: true, substrate: true, floor: 'archon', guards: 'git push origin main / the deploy — substrate-enforced (pre-push, main-audit)' },
   { key: 'path.protected.modify', system: true, substrate: true, floor: 'archon', guards: 'modifying a PROTECTED_GLOBS path below the Metic floor — substrate (ADR 0043)' },
   { key: 'infra.ssh', system: true, substrate: true, floor: 'archon', guards: 'ssh to the droplet / operator surface — substrate (credential placement)' },
-  { key: 'principal.bfg', system: true, floor: null, principal: 'bfg', guards: '/memory/bfg/* — requireBfgPrincipal (exact system_role=bfg; NO rank-role holds it)' },
+  { key: 'principal.bfg', system: true, floor: null, principal: 'bfg', guards: '/memory/bfg/* — requireBfgPrincipal (exact system_role=bfg; NO rank holds it)' },
   { key: 'principal.discord_bot', system: true, floor: null, principal: 'discord_bot', guards: 'Discord bot routes — requireDiscordBot (exact system_role; dormant)' },
 
-  // ── operational — floor archon (admin ops; grantable to a custom role) ────────
+  // ── operational — floor archon (admin ops; grantable to a custom rank) ────────
   //
   // ADR 0157 (owner decision, 2026-08-05) narrowed this block to IDENTITY: the Archon
   // rank is responsible for rank and identity only. Nineteen keys that sat here for
@@ -166,15 +166,15 @@ const PERMISSIONS = [
   // and operations: they spend, read, adjudicate, and shuffle work, but none of them
   // decides WHO HOLDS AUTHORITY, so the trusted working rank carries them. All were
   // floor 'archon' before this ADR; none is system:true, so all were already
-  // delegable to a custom role — this only lowers the seeded floor.
+  // delegable to a custom rank — this only lowers the seeded floor.
   //
   // Deliberately NOT in this block, though the owner's rule would otherwise reach them:
   //   • `version.close` — retained at archon; it is the DISPOSITION that finalises a
   //     version's scope-truth, and canonical-permissions has long paired it with rank
   //     as the two powers that never delegate. ADR 0157 keeps that pairing.
   //   • `dependency.cross_tier.manage` — system:true, and the catalog's own invariant
-  //     (tests/governance_catalog.mjs) forbids granting a system key to metic. Moving
-  //     it would mean clearing the system flag, which widens what any CUSTOM role can
+  //     (tests/government_catalog.mjs) forbids granting a system key to metic. Moving
+  //     it would mean clearing the system flag, which widens what any CUSTOM rank can
   //     be granted — a second-order change beyond the delegation that was asked for.
   { key: 'builder.budget.set', system: false, floor: 'metic', guards: 'PATCH /builders/:id/budget (ADR 0157, was archon)' },
   { key: 'criterion.unsatisfy', system: false, floor: 'metic', guards: 'POST /done-when/:id/unsatisfy (ADR 0157, was archon)' },
@@ -185,7 +185,7 @@ const PERMISSIONS = [
   // siblings are `goal.create` and `task.create`, both operational. Close is the
   // DISPOSITION that finalises a version's scope-truth; create opens it — the symmetry
   // argument was considered and rejected, because system:true would permanently bar
-  // delegating version authoring to a custom role for no trust-boundary reason.
+  // delegating version authoring to a custom rank for no trust-boundary reason.
   // ADR 0157 then lowered create's floor to metic while close stayed archon, which is
   // the same asymmetry read from the other side: authoring delegates, disposition does not.
   { key: 'version.create', system: false, floor: 'metic', guards: 'POST /versions — create a version + its done-when criteria (ADR 0157, was archon)' },
@@ -235,10 +235,10 @@ const PERMISSIONS = [
   { key: 'page.view.public', system: false, floor: 'xenos', guards: 'public read surfaces (incl. xenos)' },
   // ADR 0157: floor archon→metic, which is what opens /watch, /harbor and /gate to the
   // working rank. The gate FUNCTION was renamed to match (`requireArchonPage` →
-  // `requireGovernancePage`) once the floor moved. Viewing is all this grants: every
+  // `requireGovernmentPage`) once the floor moved. Viewing is all this grants: every
   // write those pages reach is its own atom, and `government.manage` (the
-  // roles/permissions tab) stayed archon.
-  { key: 'page.view.government', system: false, floor: 'metic', guards: 'the governance/monitoring pages — /watch, /harbor, /gate (requireGovernancePage; write = government.manage, archon)' },
+  // ranks/permissions tab) stayed archon.
+  { key: 'page.view.government', system: false, floor: 'metic', guards: 'the government/monitoring pages — /watch, /harbor, /gate (requireGovernmentPage; write = government.manage, archon)' },
 ];
 
 // ── invariants asserted at module load (fail loud on an authoring typo) ─────────
@@ -249,70 +249,70 @@ const _byKey = new Map();
 const _byPrincipal = new Map();
 const _byResource = new Map();
 for (const p of PERMISSIONS) {
-  if (typeof p.key !== 'string' || !p.key) throw new Error(`governance catalog: permission missing a key`);
-  if (typeof p.system !== 'boolean') throw new Error(`governance catalog: ${p.key} missing boolean 'system'`);
-  if (p.floor !== null && !RANK_ORDER.includes(p.floor)) throw new Error(`governance catalog: ${p.key} has invalid floor "${p.floor}"`);
-  if (_byKey.has(p.key)) throw new Error(`governance catalog: duplicate key "${p.key}"`);
+  if (typeof p.key !== 'string' || !p.key) throw new Error(`government catalog: permission missing a key`);
+  if (typeof p.system !== 'boolean') throw new Error(`government catalog: ${p.key} missing boolean 'system'`);
+  if (p.floor !== null && !RANK_ORDER.includes(p.floor)) throw new Error(`government catalog: ${p.key} has invalid floor "${p.floor}"`);
+  if (_byKey.has(p.key)) throw new Error(`government catalog: duplicate key "${p.key}"`);
   const principal = p.principal ?? null;
   if (principal !== null && (typeof principal !== 'string' || !principal)) {
-    throw new Error(`governance catalog: ${p.key} has a non-string principal identity`);
+    throw new Error(`government catalog: ${p.key} has a non-string principal identity`);
   }
-  // The two axes PARTITION the catalog: a permission is held by a rank-role (a real
+  // The two axes PARTITION the catalog: a permission is held by a rank (a real
   // floor) XOR by a machine identity (floor null + a principal). Neither-nor would be
-  // a permission nothing can ever hold; both-and would let a role reach an identity.
+  // a permission nothing can ever hold; both-and would let a rank reach an identity.
   if ((p.floor === null) !== (principal !== null)) {
-    throw new Error(`governance catalog: ${p.key} — floor:null and a principal identity must come together (roles and identities are separate axes)`);
+    throw new Error(`government catalog: ${p.key} — floor:null and a principal identity must come together (ranks and identities are separate axes)`);
   }
   if (p.key.startsWith(PRINCIPAL_KEY_PREFIX) !== (principal !== null)) {
-    throw new Error(`governance catalog: ${p.key} — a "${PRINCIPAL_KEY_PREFIX}*" key and a principal identity must come together`);
+    throw new Error(`government catalog: ${p.key} — a "${PRINCIPAL_KEY_PREFIX}*" key and a principal identity must come together`);
   }
   if (principal !== null) {
-    if (!p.system) throw new Error(`governance catalog: ${p.key} is a principal permission and must be system:true (never grantable to a role)`);
-    if (_byPrincipal.has(principal)) throw new Error(`governance catalog: duplicate principal identity "${principal}"`);
+    if (!p.system) throw new Error(`government catalog: ${p.key} is a principal permission and must be system:true (never grantable to a rank)`);
+    if (_byPrincipal.has(principal)) throw new Error(`government catalog: duplicate principal identity "${principal}"`);
   }
   // ── the SUBSTRATE axis (ADR 0172) ─────────────────────────────────────────
   // A substrate key is enforced by the out-of-band layer (pre-push hook, main-audit,
-  // the rank floor git/ssh read), so no role row can confer it. Three shape rules,
+  // the rank floor git/ssh read), so no rank row can confer it. Three shape rules,
   // each closing a way the marker could quietly stop meaning that:
   const substrate = p.substrate ?? false;
-  if (typeof substrate !== 'boolean') throw new Error(`governance catalog: ${p.key} has a non-boolean 'substrate'`);
+  if (typeof substrate !== 'boolean') throw new Error(`government catalog: ${p.key} has a non-boolean 'substrate'`);
   if (substrate) {
     // Substrate power is trust-boundary power by definition — a substrate key that
-    // was somehow operational would be freely grantable to a custom role.
-    if (!p.system) throw new Error(`governance catalog: ${p.key} is substrate-enforced and must be system:true`);
+    // was somehow operational would be freely grantable to a custom rank.
+    if (!p.system) throw new Error(`government catalog: ${p.key} is substrate-enforced and must be system:true`);
     // A substrate key belongs to no machine identity: the two are different reasons
     // a key is unreachable, and collapsing them would hide one behind the other.
-    if (principal !== null) throw new Error(`governance catalog: ${p.key} cannot be both substrate-enforced and a machine principal`);
+    if (principal !== null) throw new Error(`government catalog: ${p.key} cannot be both substrate-enforced and a machine principal`);
     // The out-of-band enforcers all compare against the top of the ladder. A lower
-    // floor would seed the key into a rank-role that the substrate then still denies.
-    if (p.floor !== 'archon') throw new Error(`governance catalog: ${p.key} is substrate-enforced and must floor at 'archon' (the substrate compares against the top of the ladder)`);
+    // floor would seed the key into a rank that the substrate then still denies.
+    if (p.floor !== 'archon') throw new Error(`government catalog: ${p.key} is substrate-enforced and must floor at 'archon' (the substrate compares against the top of the ladder)`);
   }
   // ── the OWNERSHIP axis (R100) ─────────────────────────────────────────────
   const scope = p.scope ?? null;
   const resource = p.resource ?? null;
   if (scope !== null && !OWNERSHIP_SCOPES.includes(scope)) {
-    throw new Error(`governance catalog: ${p.key} has invalid scope "${scope}" (expected 'own', 'any', or absent)`);
+    throw new Error(`government catalog: ${p.key} has invalid scope "${scope}" (expected 'own', 'any', or absent)`);
   }
   // An ownership SCOPE and the RESOURCE it is scoped over are one fact spelled in
   // two fields; either alone is meaningless ('own' of what? / a resource nothing
   // is scoped over). Same partition posture as floor ⟺ principal above.
   if ((scope === null) !== (resource === null)) {
-    throw new Error(`governance catalog: ${p.key} — scope and resource must come together (an ownership scope is always scoped over a named resource)`);
+    throw new Error(`government catalog: ${p.key} — scope and resource must come together (an ownership scope is always scoped over a named resource)`);
   }
   if (resource !== null && (typeof resource !== 'string' || !resource)) {
-    throw new Error(`governance catalog: ${p.key} has a non-string resource family`);
+    throw new Error(`government catalog: ${p.key} has a non-string resource family`);
   }
   // The namespace can never outrun the data: a key that CALLS itself own-scoped
   // must BE declared own-scoped, or a gate reading the declared axis would treat a
   // parameterized permission as an unconditional grant. Deliberately one-way — the
   // converse would be false (me.wandering.set is own-scoped without the suffix).
   if (p.key.endsWith(OWN_KEY_SUFFIX) && scope !== 'own') {
-    throw new Error(`governance catalog: ${p.key} ends in "${OWN_KEY_SUFFIX}" but does not declare scope:'own' — an ownership-scoped key must say so in data`);
+    throw new Error(`government catalog: ${p.key} ends in "${OWN_KEY_SUFFIX}" but does not declare scope:'own' — an ownership-scoped key must say so in data`);
   }
-  // An ownership scope NARROWS a role-held permission; a machine identity has no
+  // An ownership scope NARROWS a rank-held permission; a machine identity has no
   // owner axis, so the two never compose.
   if (scope !== null && p.floor === null) {
-    throw new Error(`governance catalog: ${p.key} is ownership-scoped but has no rank floor — the ownership axis narrows a ROLE permission, never an identity one`);
+    throw new Error(`government catalog: ${p.key} is ownership-scoped but has no rank floor — the ownership axis narrows a RANK permission, never an identity one`);
   }
   const frozen = Object.freeze({ ...p, principal, scope, resource, substrate });
   _byKey.set(p.key, frozen);
@@ -332,15 +332,15 @@ Object.freeze(PERMISSIONS);
 const floorTier = (rank) => RANK_ORDER.indexOf(rank);
 for (const [resource, fam] of _byResource) {
   if (fam.any.length > 0 && fam.own.length === 0) {
-    throw new Error(`governance catalog: resource "${resource}" declares a cross-owner permission (${fam.any.join(', ')}) with no ownership-scoped counterpart`);
+    throw new Error(`government catalog: resource "${resource}" declares a cross-owner permission (${fam.any.join(', ')}) with no ownership-scoped counterpart`);
   }
   // Reaching EVERY owner's row must never be cheaper than reaching your own. If it
   // were, a rank could manage the whole fleet but not its own box — the model
-  // inverted, and the governance tab would render the wider grant as the safer one.
+  // inverted, and the Government tab would render the wider grant as the safer one.
   for (const anyKey of fam.any) {
     for (const ownKey of fam.own) {
       if (floorTier(_byKey.get(anyKey).floor) < floorTier(_byKey.get(ownKey).floor)) {
-        throw new Error(`governance catalog: ${anyKey} (floor ${_byKey.get(anyKey).floor}) sits BELOW ${ownKey} (floor ${_byKey.get(ownKey).floor}) — cross-owner authority must never be cheaper than own-only`);
+        throw new Error(`government catalog: ${anyKey} (floor ${_byKey.get(anyKey).floor}) sits BELOW ${ownKey} (floor ${_byKey.get(ownKey).floor}) — cross-owner authority must never be cheaper than own-only`);
       }
     }
   }
@@ -382,9 +382,9 @@ function isSystem(key) {
   const p = _byKey.get(key);
   return p ? p.system : null; // null = unknown key (caller fails closed)
 }
-// Grantable to a CUSTOM role = exists and not system. Unknown key → false (fail-closed).
-// This is the NARROW question — the custom-role wall, unchanged by ADR 0172 and
-// still what config.js strips against. For the per-role answer use isGrantableTo().
+// Grantable to a CUSTOM rank = exists and not system. Unknown key → false (fail-closed).
+// This is the NARROW question — the custom-rank wall, unchanged by ADR 0172 and
+// still what config.js strips against. For the per-rank answer use isGrantableTo().
 function isGrantable(key) {
   const p = _byKey.get(key);
   return !!p && !p.system;
@@ -406,40 +406,40 @@ function substrateKeys() {
   return PERMISSIONS.filter((p) => p.substrate).map((p) => p.key);
 }
 
-// ── grantability, per ROLE (ADR 0172) ──────────────────────────────────────────
+// ── grantability, per RANK (ADR 0172) ──────────────────────────────────────────
 //
-// The owner's 2026-08-16 decision made the three sub-Archon RANK roles editable, so
-// "is this grantable" stopped being a property of the key alone. `role` is a
+// The owner's 2026-08-16 decision made the three sub-Archon RANK ranks editable, so
+// "is this grantable" stopped being a property of the key alone. `rank` is a
 // government_ranks row ({ is_system, seeded_rank }); the four answers:
 //
-//   • NEVER, to any role — a machine-principal key (held by an identity, not a role)
+//   • NEVER, to any rank — a machine-principal key (held by an identity, not a rank)
 //     and a SUBSTRATE key. The substrate three are inert as grant rows: no route
 //     consumes them through requirePermission, so a toggle for one would report
 //     success and delegate nothing. Refusing them keeps the tab honest.
-//   • the ARCHON rank-role — nothing. It is immutable and already holds everything,
-//     and that immutability is also the LOCKOUT GUARD: the only role carrying
+//   • the ARCHON rank — nothing. It is immutable and already holds everything,
+//     and that immutability is also the LOCKOUT GUARD: the only rank carrying
 //     `government.manage` by seed can never have it revoked, so no sequence of
 //     clicks in this tab can lock the owner out of the tab.
-//   • a SEEDED rank-role BELOW archon — everything else, the seven in-app Archon
+//   • a SEEDED rank BELOW archon — everything else, the seven in-app Archon
 //     powers included. This is the delegation lever the owner asked for.
-//   • a CUSTOM role — operational only: the pre-existing R110 wall, deliberately NOT
-//     widened. A rank-role is the owner's own coarse ladder, moved by a rank write;
-//     a custom role is ad-hoc and assignable by anyone holding `government.manage`,
+//   • a CUSTOM rank — operational only: the pre-existing R110 wall, deliberately NOT
+//     widened. A rank is the owner's own coarse ladder, moved by a rank write;
+//     a custom rank is ad-hoc and assignable by anyone holding `government.manage`,
 //     so widening it would hand the second group the first group's lever.
 //
-// Fail-closed on everything unrecognised: unknown key, missing role, or a system role
+// Fail-closed on everything unrecognised: unknown key, missing rank, or a system rank
 // whose seeded_rank is not a real rank all answer false.
-function isGrantableTo(key, role) {
+function isGrantableTo(key, rank) {
   const p = _byKey.get(key);
-  if (!p || !role || typeof role !== 'object') return false;
+  if (!p || !rank || typeof rank !== 'object') return false;
   if (p.principal !== null || p.substrate) return false;
-  if (role.is_system) {
-    return RANK_ORDER.includes(role.seeded_rank) && role.seeded_rank !== 'archon';
+  if (rank.is_system) {
+    return RANK_ORDER.includes(rank.seeded_rank) && rank.seeded_rank !== 'archon';
   }
   return !p.system;
 }
 
-// ── the principal axis (identity, not roles) ────────────────────────────────────
+// ── the principal axis (identity, not ranks) ────────────────────────────────────
 // Reads only. Unknown/blank input fails closed to null/false — the same posture the
 // rest of the catalog takes, and the one the identity gates depend on.
 function principals() {
@@ -451,7 +451,7 @@ function principalRoles() {
 function principalKeys() {
   return PRINCIPALS.map((p) => p.permission);
 }
-// Is this key held by a machine identity rather than by any role? Unknown → false.
+// Is this key held by a machine identity rather than by any rank? Unknown → false.
 function isPrincipalKey(key) {
   const p = _byKey.get(key);
   return !!p && p.principal !== null;
@@ -503,17 +503,17 @@ function crossOwnerKeysFor(key) {
   return fam ? fam.any : NO_KEYS;
 }
 
-// The compat seed, DERIVED from floors (cumulative supersets). A rank-role holds
+// The compat seed, DERIVED from floors (cumulative supersets). A rank holds
 // every permission whose floor is a real rank at-or-below it; principals (floor
-// null) are held by NO rank-role. This is the "zero day-one change" guarantee —
-// role(rank) reproduces requireRank(rank)'s at-or-above threshold exactly (R103).
+// null) are held by NO rank. This is the "zero day-one change" guarantee —
+// rank(rank) reproduces requireRank(rank)'s at-or-above threshold exactly (R103).
 function seedForRank(rank) {
   const tier = RANK_ORDER.indexOf(rank);
-  if (tier < 0) return []; // unknown/reserved rank → no role → no permissions (fail-closed; ADR 0151)
+  if (tier < 0) return []; // unknown/reserved rank → no rank → no permissions (fail-closed; ADR 0151)
   return PERMISSIONS.filter((p) => p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier).map((p) => p.key);
 }
 
-const RANK_ROLE_SEED = Object.freeze(
+const RANK_SEED = Object.freeze(
   Object.fromEntries(RANK_ORDER.map((r) => [r, Object.freeze(seedForRank(r))])),
 );
 
@@ -530,7 +530,7 @@ module.exports = {
   systemKeys,
   grantableKeys,
   seedForRank,
-  RANK_ROLE_SEED,
+  RANK_SEED,
   PRINCIPALS,
   principals,
   principalRoles,