@bongos/core 1.19.186 → 1.19.187

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' },
@@ -112,7 +112,7 @@ const PERMISSIONS = [
   { 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)' },
@@ -237,7 +237,7 @@ const PERMISSIONS = [
   // working rank. The gate FUNCTION was renamed to match (`requireArchonPage` →
   // `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.
+  // 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)' },
 ];
 
@@ -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,

package/modules/government/config.js

@@ -1,22 +1,22 @@
 'use strict';
 
-// modules/governance/config.js — the governance config contract (ADR 0151, BV1.R96).
+// modules/government/config.js — the government config contract (ADR 0151, BV1.R96).
 //
-// Role TEMPLATES and their display labels are per-instance CONFIG; live grants and
+// Rank TEMPLATES and their display labels are per-instance CONFIG; live grants and
 // assignments are DB rows. This file resolves the config half, mirroring
 // src/branding.js precedence exactly:
 //
 //   env override  ->  instance config (config/government.json)  ->  neutral
 //   starter (config/government.neutral.json)
 //
-// A fresh instance with NO config resolves to the PLAIN neutral role set — never to
+// A fresh instance with NO config resolves to the PLAIN neutral rank set — never to
 // a host's labels (fail-to-vanilla, the same posture branding takes). R102 proves
 // that boot.
 //
 // WHAT LIVES HERE vs WHAT LIVES IN THE DB — get this wrong and config becomes a
 // second source of authority truth, which is exactly what ADR 0016 forbids:
-//   • config — TEMPLATES/DEFAULTS: a role's display label, its description, and the
-//     permission list a starting CUSTOM role template proposes. Shapes only.
+//   • config — TEMPLATES/DEFAULTS: a rank's display label, its description, and the
+//     permission list a starting CUSTOM rank template proposes. Shapes only.
 //   • DB     — LIVE STATE: government_ranks / government_rank_permissions /
 //     government_builder_ranks (R93). WHO HOLDS WHAT is a row, resolved server-side
 //     per request by resolver.js. Nothing in this file grants anything to anybody.
@@ -25,21 +25,21 @@
 //   1. A template naming a `system: true` catalog key is STRIPPED. An instance's
 //      config file is editable by anyone who can write the checkout, so it must never
 //      be able to hand out deploy / rank-set / protected-path power. catalog
-//      .isGrantable() is that wall — the same one the governance API and the Archon
+//      .isGrantable() is that wall — the same one the government API and the Archon
 //      tab use, so this cannot drift from the catalog.
 //   2. A template naming a key the catalog does not define is DROPPED (the catalog is
 //      the source of truth for what a permission IS — resolver.js, same rule).
-//   3. A `permissions` list on one of the four SEEDED rank-roles is DROPPED wholesale.
+//   3. A `permissions` list on one of the four SEEDED ranks is DROPPED wholesale.
 //      Their grants are DERIVED from catalog floors and materialised by
-//      governance_002; config may relabel a seeded role, never re-grant it.
+//      governance_002; config may relabel a seeded rank, never re-grant it.
 //
 // Stripping rather than throwing matches resolver.js: a typo in a config file must
 // fail CLOSED, not brick the boot.
 //
 // SLICE BOUNDARY: this file is the config CONTRACT, and deliberately has no production
-// caller yet — R96 is the "what shape is a role template, and what can config never
+// caller yet — R96 is the "what shape is a rank template, and what can config never
 // do" decision, landed before the surfaces that read it. R110/R111 (the Archon
-// governance tab) is the first intended consumer, and R102 (the vanilla-boot proof)
+// Government tab) is the first intended consumer, and R102 (the vanilla-boot proof)
 // asserts against the neutral starter. Wiring a speculative caller now would guess at
 // their needs; the tests pin the contract until they land.
 
@@ -62,7 +62,7 @@ const SEEDED_RANK_ROLES = new Set(catalog.RANK_ORDER);
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
 
-// Instance roles merge over neutral PER ROLE KEY and per field, so an instance can
+// Instance ranks merge over neutral PER RANK KEY and per field, so an instance can
 // relabel `metic` without restating the other three. The shape is exactly two levels
 // deep, so this is a targeted merge rather than branding's generic deepMerge.
 function mergeRoles(neutral, instance) {
@@ -80,13 +80,18 @@ function mergeRoles(neutral, instance) {
 // widen authority, so there is no env knob that adds a permission. It exists for the
 // co-tenant case branding's AUTH_IDP override exists for — several hosted instances
 // sharing the neutral pack, differentiated only by env, with no config file of their
-// own. Format: "<PREFIX>_GOVERNANCE_ROLE_LABELS=metic=Trusted,archon=Owner". It can
-// only RELABEL a role the merged config already defines — a typo names no role and is
-// inert, rather than quietly growing the role set from an env string.
-function applyLabelOverrides(roles, env) {
-  const raw = api.resolveEnv('GOVERNANCE_ROLE_LABELS', { env });
-  if (!raw) return roles;
-  const out = { ...roles };
+// own. Format: "<PREFIX>_GOVERNMENT_RANK_LABELS=metic=Trusted,archon=Owner". It can
+// only RELABEL a rank the merged config already defines — a typo names no rank and is
+// inert, rather than quietly growing the rank set from an env string.
+function applyLabelOverrides(ranks, env) {
+  // GOVERNMENT_RANK_LABELS is the post-ADR-0174 name. The pre-rename spelling is
+  // still read because an instance sets this in its own shell/env file, OUTSIDE
+  // this repo — dropping it would silently stop honouring a label override an
+  // operator already configured. Remove once instances have migrated.
+  const raw = api.resolveEnv('GOVERNMENT_RANK_LABELS', { env })
+    || api.resolveEnv('GOVERNANCE_ROLE_LABELS', { env });
+  if (!raw) return ranks;
+  const out = { ...ranks };
   for (const pair of String(raw).split(',')) {
     const eq = pair.indexOf('=');
     if (eq <= 0) continue;
@@ -116,27 +121,32 @@ function sanitizeRole(key, raw) {
     seeded,
     label: typeof raw.label === 'string' && raw.label ? raw.label : key,
     description: typeof raw.description === 'string' ? raw.description : '',
-    // Rule 3: a seeded rank-role's grants come from catalog floors via governance_002.
+    // Rule 3: a seeded rank's grants come from catalog floors via governance_002.
     permissions: seeded ? Object.freeze([]) : grantableOnly(raw.permissions),
   });
 }
 
 // Pure resolver — all inputs injected, so tests drive it with zero I/O (the
 // resolveBranding pattern).
-function resolveGovernanceConfig({ neutral, instance, env = process.env } = {}) {
-  const merged = applyLabelOverrides(mergeRoles((neutral || {}).roles, (instance || {}).roles), env);
-  const roles = {};
+function resolveGovernmentConfig({ neutral, instance, env = process.env } = {}) {
+  // `ranks` is the post-ADR-0174 key. An INSTANCE file authored before the rename
+  // may still say `roles`; accept it so an external self-hosted instance does not
+  // silently lose its templates on upgrade. The neutral file shipped in core is
+  // always `ranks`, so this fallback only ever reads host-owned config.
+  const instanceRanks = (instance || {}).ranks || (instance || {}).roles;
+  const merged = applyLabelOverrides(mergeRoles((neutral || {}).ranks, instanceRanks), env);
+  const ranks = {};
   for (const key of Object.keys(merged).sort()) {
-    if (!isObj(merged[key])) continue; // a malformed entry is not a role, and grants nothing
-    roles[key] = sanitizeRole(key, merged[key]);
+    if (!isObj(merged[key])) continue; // a malformed entry is not a rank, and grants nothing
+    ranks[key] = sanitizeRole(key, merged[key]);
   }
-  // The four rank-roles ALWAYS exist (governance_002 seeds them unconditionally), so a
+  // The four ranks ALWAYS exist (governance_002 seeds them unconditionally), so a
   // config that omits or mangles one falls back to the canonical rank name rather than
-  // dropping the role out of the display set.
+  // dropping the rank out of the display set.
   for (const key of catalog.RANK_ORDER) {
-    if (!roles[key]) roles[key] = sanitizeRole(key, {});
+    if (!ranks[key]) ranks[key] = sanitizeRole(key, {});
   }
-  return Object.freeze({ roles: Object.freeze(roles) });
+  return Object.freeze({ ranks: Object.freeze(ranks) });
 }
 
 // READ, never require(): a bare require('../../config/X.json') of a boundary-excluded
@@ -148,7 +158,7 @@ function readJson(p) {
 
 // Disk loader with the documented precedence. BOTH files are optional: the instance
 // pack because a vanilla instance ships only the neutral starter, and the neutral
-// starter because the four rank-roles still resolve to their canonical names without
+// starter because the four ranks still resolve to their canonical names without
 // it. Unlike branding — where a missing identity is fatal — no value here is required,
 // so the loader fails to sane defaults rather than throwing.
 //
@@ -157,8 +167,8 @@ function readJson(p) {
 // consumer needs it on a hot path, resolve once at boot and pass the frozen result —
 // do NOT add a cache here (this file sits next to resolver.js, whose no-cache rule is
 // absolute; keeping config cache-free too means nobody has to check which is which).
-function loadGovernanceConfig({ neutralPath = NEUTRAL_PATH, instancePath = INSTANCE_PATH, env = process.env } = {}) {
-  return resolveGovernanceConfig({
+function loadGovernmentConfig({ neutralPath = NEUTRAL_PATH, instancePath = INSTANCE_PATH, env = process.env } = {}) {
+  return resolveGovernmentConfig({
     neutral: readJson(neutralPath) || {},
     instance: readJson(instancePath) || {},
     env,
@@ -166,8 +176,8 @@ function loadGovernanceConfig({ neutralPath = NEUTRAL_PATH, instancePath = INSTA
 }
 
 module.exports = {
-  resolveGovernanceConfig,
-  loadGovernanceConfig,
+  resolveGovernmentConfig,
+  loadGovernmentConfig,
   grantableOnly,
   NEUTRAL_PATH,
   INSTANCE_PATH,