@bongos/core 1.19.185 → 1.19.187

package/modules/government/resolver.js

@@ -1,29 +1,29 @@
 'use strict';
 
-// modules/governance/resolver.js — the permission resolver (ADR 0151, BV1.R95).
+// modules/government/resolver.js — the permission resolver (ADR 0151, BV1.R95).
 //
-// Turns a builder's ROLES into their effective PERMISSION SET: the union of every
-// permission granted to every role they hold. This is the heart of the
+// Turns a builder's RANKS into their effective PERMISSION SET: the union of every
+// permission granted to every rank they hold. This is the heart of the
 // permissions-as-atom model — `requirePermission()` (R97) and every migrated gate
 // (R104-R107) resolve authority through here.
 //
-// TWO AXES, two entry points (R98, ADR 0151 §3). Roles are one axis; a machine
+// TWO AXES, two entry points (R98, ADR 0151 §3). Ranks are one axis; a machine
 // PRINCIPAL's capability is the other, resolved from its exact `system_role` and
-// never from a role. They are kept apart on purpose — see resolvePrincipalPermissions
+// never from a rank. They are kept apart on purpose — see resolvePrincipalPermissions
 // below, and the principal keys effectivePermissions drops.
 //
 // It preserves ADR 0016 exactly:
 //   • server-side — the answer is computed on the server from DB rows, never from
 //     a token claim or anything the client can influence;
 //   • per request — resolveBuilderPermissions() is called on the request that
-//     needs it, so a revoked role takes effect on the builder's very next request;
+//     needs it, so a revoked rank takes effect on the builder's very next request;
 //   • UNCACHED — there is no memo, no TTL, no process-local map. Caching authority
 //     is the one optimisation this file must never take (a cached grant survives
 //     its revocation, which is the failure mode the trust boundary exists to
 //     prevent). If a future profile shows the join is hot, the answer is a DB
 //     index, not a cache.
 //
-// Fail-closed throughout: a builder with no roles resolves to the EMPTY set, and a
+// Fail-closed throughout: a builder with no ranks resolves to the EMPTY set, and a
 // grant naming a key the code catalog doesn't define is DROPPED (see
 // effectivePermissions below) rather than admitted on trust.
 
@@ -31,18 +31,18 @@ const catalog = require('./catalog');
 const db = require('./db');
 const sessionScopes = require('./session-scopes');
 
-// Pure core of the ROLE axis, split out so it is unit-testable without a database.
+// Pure core of the RANK axis, split out so it is unit-testable without a database.
 //
 // Filters raw grant rows against the code catalog: the catalog is the source of
 // truth for what a permission IS (every key maps to a real route — modules/
-// governance/CLAUDE.md), so a DB row naming an unknown key is stale or hand-
+// government/CLAUDE.md), so a DB row naming an unknown key is stale or hand-
 // inserted and grants NOTHING. Returns a frozen, sorted, de-duplicated array.
 //
 // It also DROPS every principal key (R98). A machine identity's capability is the
-// other axis — it comes from `builders.system_role`, never from a role — so a grant
+// other axis — it comes from `builders.system_role`, never from a rank — so a grant
 // row naming `principal.*` confers nothing here no matter how it got written (a
-// hand-inserted row, a future bug in the governance CRUD's system-permission
-// rejection). That makes "a role cannot confer a principal permission" structural
+// hand-inserted row, a future bug in the government CRUD's system-permission
+// rejection). That makes "a rank cannot confer a principal permission" structural
 // rather than merely policed at the write side.
 function effectivePermissions(rawKeys) {
   const known = new Set();
@@ -55,8 +55,8 @@ function effectivePermissions(rawKeys) {
 }
 
 // The PRINCIPAL axis (R98, ADR 0151 §3) — deliberately a SEPARATE entry point, not
-// a branch inside the role resolve. A builder's authority is the union of their
-// roles; a machine principal's authority is its identity, and collapsing the two
+// a branch inside the rank resolve. A builder's authority is the union of their
+// ranks; a machine principal's authority is its identity, and collapsing the two
 // into one lookup is exactly the mistake that would let a rank reach a principal
 // capability.
 //
@@ -64,7 +64,7 @@ function effectivePermissions(rawKeys) {
 // already reads fresh from the DB per request (alongside rank), and which no API
 // route writes — a principal is provisioned out-of-band by migration, under a DB
 // CHECK allowlist. The match is EXACT string equality, so NULL (every human,
-// including an Archon), a differently-cased value, or an unknown role resolves to
+// including an Archon), a differently-cased value, or an unknown rank resolves to
 // the empty set. Mirrors requireBfgPrincipal / requireDiscordBot in src/bongos/
 // auth.js, which stay the HTTP enforcement point.
 function resolvePrincipalPermissions(systemRole) {
@@ -111,7 +111,7 @@ async function builderHasPermissions(builderId, required) {
 // two different places, and folding it into the plain resolve would silently drop
 // the second one.
 //
-//   1. the ROLE fact  — does the builder hold the key? (this file, from the DB)
+//   1. the RANK fact  — does the builder hold the key? (this file, from the DB)
 //   2. the OWNER fact — is the concrete row theirs? (REQUEST-scoped; only the
 //                       handler that loaded the row knows it)
 //
@@ -122,7 +122,7 @@ async function builderHasPermissions(builderId, required) {
 // path here that turns an ownership-scoped key into an admit on its own.
 //
 // Pure + DB-free where it can be: the comparison below never touches Postgres, and
-// the role fact reuses resolveBuilderPermissions, so ADR 0016 holds unchanged —
+// the rank fact reuses resolveBuilderPermissions, so ADR 0016 holds unchanged —
 // per-request, server-side, no stored answer.
 
 // The owner comparison, normalized once so ~15 sites stop hand-rolling it. STRICT:
@@ -169,27 +169,27 @@ async function authorizeOwnedOrAny(builderId, ownKey, context) {
 
 // ── the SESSION-SCOPE axis (R99, ADR 0151 §3) ───────────────────────────────────
 // The FOURTH entry point, separate for the same reason the other three are: it
-// answers a different question with a different input. Roles answer "what may this
+// answers a different question with a different input. Ranks answer "what may this
 // PERSON do"; a principal answers "what may this MACHINE do"; an ownership scope
 // answers "whose row may it be done to"; a session-scope answers "how much of that
 // does THIS CREDENTIAL carry". A dev-box token is minted onto a machine outside the
 // ADR 0016 trust boundary (#919/SR#2, ADR 0053), so it must stay limited even when
-// its builder is an Archon — which no role-shaped answer can express.
+// its builder is an Archon — which no rank-shaped answer can express.
 //
 // A SESSION-SCOPE CAN ONLY EVER NARROW, in both directions:
-//   • INTERSECTION, never union. The scope may not GRANT a permission the roles do
-//     not confer — so the composition below is written as a FILTER of the ROLE
+//   • INTERSECTION, never union. The scope may not GRANT a permission the ranks do
+//     not confer — so the composition below is written as a FILTER of the RANK
 //     answer. There is no branch here that can add a key, which is what makes
 //     "a box token cannot escalate" structural rather than merely intended.
 //   • DENY-BY-DEFAULT. A key the allow-list does not name is denied; an
 //     unrecognised session source resolves to NOTHING rather than to "full".
 // Widening is therefore not expressible without deleting the filter, and R103's
-// parity is untouched: effectivePermissions is the unchanged ROLE answer this
+// parity is untouched: effectivePermissions is the unchanged RANK answer this
 // composes ON TOP of, never inside.
 //
 // Pure and DB-free (the DB half is resolveBuilderPermissions'), so an unknown key
 // on an allow-list is inert as well as refused at load: it can never appear in the
-// catalog-filtered role answer, so it can never survive the intersection.
+// catalog-filtered rank answer, so it can never survive the intersection.
 function narrowToSessionScope(rawKeys, source) {
   const scope = sessionScopes.scopeFor(source);
   if (!scope) return Object.freeze([]); // unrecognised source → no authority at all
@@ -199,7 +199,7 @@ function narrowToSessionScope(rawKeys, source) {
   return Object.freeze(held.filter((key) => allowed.has(key)));
 }
 
-// What can THIS SESSION actually do? The builder's roles ∩ this session's scope,
+// What can THIS SESSION actually do? The builder's ranks ∩ this session's scope,
 // as a frozen sorted array of catalog keys. Fails closed BEFORE touching the DB on
 // a source the registry does not declare.
 async function resolveSessionPermissions(builderId, source) {

package/modules/government/routes/government.js

@@ -1,12 +1,12 @@
 'use strict';
 
-// The governance module's kernel PORT registration (ADR 0151, BV1.R95).
+// The government module's kernel PORT registration (ADR 0151, BV1.R95).
 //
-// governance exposes the permission RESOLVER as the `governance` kernel PORT.
+// government exposes the permission RESOLVER as the `government` kernel PORT.
 // CORE files that must NOT import a module resolve it instead — first among them
 // src/bongos/auth.js, whose `requirePermission()` gate (R97) needs a builder's
 // effective permission set on every gated request. The one-way rule (ADR 0083)
-// forbids core requiring modules/governance/ directly; the port is how the
+// forbids core requiring modules/government/ directly; the port is how the
 // capability crosses that line.
 //
 // Why a route factory for a (currently) routeless capability: `mountModuleRoutes`
@@ -14,7 +14,7 @@
 // rebuilds the GDS router, so registering here keeps the port present for the
 // route-building tests too. Registration is hasProvider-guarded so
 // re-instantiation never trips the seam's single-provider duplicate guard.
-// (Mirrors modules/economy/routes/reward.js.) The R110 governance CRUD
+// (Mirrors modules/economy/routes/reward.js.) The R110 government CRUD
 // endpoints live on this same router, below.
 
 const express = require('express');
@@ -27,7 +27,7 @@ const sessionScopes = require('../session-scopes');
 // The port surface. Deliberately narrow: resolution + the catalog reads a gate or
 // the Archon tab needs. It grows with R98-R101 (principals, session-scopes,
 // ownership scoping, the protected-surface registry) — one object port rather
-// than a port per capability, so core resolves `governance` once.
+// than a port per capability, so core resolves `government` once.
 //
 // The principal half (R98) is READ-ONLY by construction: resolution keyed on an
 // exact system_role, plus `listPrincipals` for the tab to render. There is no
@@ -47,10 +47,10 @@ const sessionScopes = require('../session-scopes');
 // The session-scope half (R99) is READ-ONLY and deliberately NOT the enforcement
 // path: the kernel gate (auth.requireBuilder) reads the same registry as static
 // data, so a request never depends on this port being registered to stay
-// deny-by-default. What the port adds is the composed answer — roles ∩ this
-// session's scope — for the governance tab and for any gate that wants the
+// deny-by-default. What the port adds is the composed answer — ranks ∩ this
+// session's scope — for the Government tab and for any gate that wants the
 // session's real authority rather than the builder's.
-const governancePort = {
+const governmentPort = {
   resolveBuilderPermissions: resolver.resolveBuilderPermissions,
   // The pure catalog-drop half, for the session-load fold (task 1002556): the
   // kernel feeds it the raw grant keys its own session query carried, so a
@@ -58,7 +58,7 @@ const governancePort = {
   // resolveBuilderPermissions given the same rows — DB-free by construction.
   effectivePermissions: resolver.effectivePermissions,
   builderHasPermissions: resolver.builderHasPermissions,
-  getRoleKeysForBuilder: db.getRoleKeysForBuilder,
+  getRankKeysForBuilder: db.getRankKeysForBuilder,
   isSystem: catalog.isSystem,
   isGrantable: catalog.isGrantable,
   permissionKeys: catalog.permissionKeys,
@@ -82,13 +82,13 @@ const governancePort = {
 
 function registerSeams() {
   if (!api.hasProvider('government')) {
-    api.registerProvider('government', governancePort);
+    api.registerProvider('government', governmentPort);
   }
   // The session-load fold (task 1002556): the kernel's lookupSession embeds this
   // fragment so the SAME round-trip carries the builder's raw grant keys, and
   // requirePermission runs the pure effectivePermissions instead of a second
   // query. Registered HERE — capability-named, module-agnostic on the kernel
-  // side (ADR 0083 §Decision #4) — because this module owns the governance SQL.
+  // side (ADR 0083 §Decision #4) — because this module owns the government SQL.
   // Contract: a boot-time CONSTANT (never user input) yielding one
   // `raw_permission_keys` column against the kernel query's alias `s`
   // (builder_sessions). Raw keys only — the catalog-drop stays in the resolver.
@@ -103,38 +103,38 @@ function registerSeams() {
   }
 }
 
-// ── the R110 CRUD surface (ADR 0151 §2 — the governance tab's server half) ────
+// ── the R110 CRUD surface (ADR 0151 §2 — the Government tab's server half) ────
 //
 // Every route — the three reads included — gates on the `government.manage`
-// atom (system, floor archon): this surface EDITS the role/permission graph
+// atom (system, floor archon): this surface EDITS the rank/permission graph
 // itself, the meta-escalation the catalog flags non-grantable, and even listing
 // it exposes the full authority map. The invariants are enforced HERE, against
 // the catalog, not in the db layer (governance_001's app-side-validation split).
 //
 // ADR 0172 (owner decision, 2026-08-16) split what used to be ONE wall — "a seeded
-// rank-role is immutable" — into two, because grants and assignment are immutable
+// rank is immutable" — into two, because grants and assignment are immutable
 // for different reasons and only one of those reasons still holds:
 //
-//   • GRANTS on the three sub-Archon rank-roles are now EDITABLE. Their rows were
+//   • GRANTS on the three sub-Archon ranks are now EDITABLE. Their rows were
 //     always ordinary `government_rank_permissions` rows (the governance_002 seed
 //     writes them); the old refusal was policy, not structure. What a rank means is
 //     now the owner's to set from the tab, and `catalog.isGrantableTo()` answers
-//     which keys per role. The ARCHON rank-role stays immutable — it holds
+//     which keys per rank. The ARCHON rank stays immutable — it holds
 //     everything, and its immutability is what makes lockout impossible.
-//   • ASSIGNMENT of every seeded rank-role is still refused, unchanged: it derives
+//   • ASSIGNMENT of every seeded rank is still refused, unchanged: it derives
 //     from `builders.rank` via the R95b sync, so a second writer here would fork
 //     authority truth and the sync would silently undo it on the next rank write.
-//     Changing who holds a rank-role is still `PATCH /builders/:id/rank`.
+//     Changing who holds a rank is still `PATCH /builders/:id/rank`.
 //
-// The custom-role wall is unchanged: a `system:true` key stays non-grantable there
-// (R94's wall — "The governance API (R110) rejects granting it"), and the three
-// SUBSTRATE keys stay non-grantable to everything, rank-roles included, because a
+// The custom-rank wall is unchanged: a `system:true` key stays non-grantable there
+// (R94's wall — "The government API (R110) rejects granting it"), and the three
+// SUBSTRATE keys stay non-grantable to everything, ranks included, because a
 // grant row for one delegates nothing (ADR 0043 enforces them out of band).
 const { validateOrRespond, LIMITS, parseId } = api;
 const RANK_KEY_RE = /^[a-z][a-z0-9-]*$/;
 const RANK_KEY_MAX = 64;
 
-module.exports = function buildGovernanceRouter() {
+module.exports = function buildGovernmentRouter() {
   registerSeams();
   const router = express.Router();
 
@@ -150,40 +150,40 @@ module.exports = function buildGovernanceRouter() {
     return rankKey;
   }
 
-  // Load a role whose GRANTS this API may edit (ADR 0172): 404 on a missing role,
-  // refuse only the Archon rank-role. Every other role — the three sub-Archon
-  // rank-roles and every custom one — is grant-editable; WHICH keys is then
-  // `catalog.isGrantableTo(key, role)`, per role. Returns null after responding.
-  async function loadGrantEditableRole(res, rankKey) {
-    const role = await db.getRoleByKey(rankKey);
-    if (!role) {
+  // Load a rank whose GRANTS this API may edit (ADR 0172): 404 on a missing rank,
+  // refuse only the Archon rank. Every other rank — the three sub-Archon
+  // ranks and every custom one — is grant-editable; WHICH keys is then
+  // `catalog.isGrantableTo(key, rank)`, per rank. Returns null after responding.
+  async function loadGrantEditableRank(res, rankKey) {
+    const rank = await db.getRankByKey(rankKey);
+    if (!rank) {
       res.fail('rank_not_found', 404, { rank_key: rankKey });
       return null;
     }
-    if (role.is_system && role.seeded_rank === ARCHON) {
+    if (rank.is_system && rank.seeded_rank === ARCHON) {
       res.fail('archon_rank_immutable', 403, { rank_key: rankKey, reason: ARCHON_REASON });
       return null;
     }
-    return role;
+    return rank;
   }
 
-  // Load a role this API may ASSIGN. Unchanged from R110: every seeded rank-role is
+  // Load a rank this API may ASSIGN. Unchanged from R110: every seeded rank is
   // refused, because assignment derives from builders.rank via the R95b sync.
-  async function loadAssignableRole(res, rankKey) {
-    const role = await db.getRoleByKey(rankKey);
-    if (!role) {
+  async function loadAssignableRank(res, rankKey) {
+    const rank = await db.getRankByKey(rankKey);
+    if (!rank) {
       res.fail('rank_not_found', 404, { rank_key: rankKey });
       return null;
     }
-    if (role.is_system) {
+    if (rank.is_system) {
       res.fail('seeded_rank_assignment_forbidden', 403, { rank_key: rankKey, reason: ASSIGN_REASON });
       return null;
     }
-    return role;
+    return rank;
   }
   const ARCHON = 'archon';
-  const ARCHON_REASON = 'the Archon rank-role holds every permission and is immutable — it is the role that can never be locked out of this tab (ADR 0172)';
-  const ASSIGN_REASON = 'a seeded rank-role is assigned by rank (R95b sync); change the builder\'s rank instead';
+  const ARCHON_REASON = 'the Archon rank-rank holds every permission and is immutable — it is the rank that can never be locked out of this tab (ADR 0172)';
+  const ASSIGN_REASON = 'a seeded rank-rank is assigned by rank (R95b sync); change the builder\'s rank instead';
 
   // ── one-release compatibility aliases: /governance/* -> /government/* ──────
   // ADR 0174 committed to keeping the pre-rename paths answering for exactly one
@@ -205,19 +205,19 @@ module.exports = function buildGovernanceRouter() {
   router.all(`${LEGACY_PATH_PREFIX}/*rest`, (req, res, next) => {
     const rest = req.originalUrl.slice(req.originalUrl.indexOf(LEGACY_PATH_PREFIX) + LEGACY_PATH_PREFIX.length);
     if (!rest) return next();
-    const target = `/government${rest.replace(/^\/roles(?=\/|$)/, '/ranks')}`;
+    const target = `/government${rest.replace(/^\/ranks(?=\/|$)/, '/ranks')}`;
     console.warn(`[government] legacy path hit: ${req.method} ${req.originalUrl} -> ${target} (ADR 0174 alias; remove one release after the rename)`);
     return res.redirect(308, target);
   });
 
-  // rank: perm government.manage — the full role list with each role's grants.
+  // rank: perm government.manage — the full rank list with each rank's grants.
   router.get('/government/ranks', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     try {
-      const roles = await db.listRolesWithGrants();
-      res.json({ roles });
+      const ranks = await db.listRanksWithGrants();
+      res.json({ ranks });
     } catch (err) {
       console.error('[gds] GET /government/ranks', err);
-      res.fail('roles_list_failed', { status: 500, message: 'internal error' });
+      res.fail('ranks_list_failed', { status: 500, message: 'internal error' });
     }
   });
 
@@ -225,11 +225,11 @@ module.exports = function buildGovernanceRouter() {
   // from code (the catalog is CODE, not a table); no DB read. Principals are
   // read-only by construction. Three flags the tab renders its locks from, and the
   // tab must read all three rather than just `grantable`, because since ADR 0172
-  // grantability depends on WHICH role is selected:
-  //   • `grantable` — the CUSTOM-role answer (system:false). Unchanged meaning.
-  //   • `system`    — an in-app Archon power: locked on a custom role, togglable on
-  //                   a sub-Archon rank-role.
-  //   • `substrate` — locked EVERYWHERE, on every role, forever (ADR 0043).
+  // grantability depends on WHICH rank is selected:
+  //   • `grantable` — the CUSTOM-rank answer (system:false). Unchanged meaning.
+  //   • `system`    — an in-app Archon power: locked on a custom rank, togglable on
+  //                   a sub-Archon rank.
+  //   • `substrate` — locked EVERYWHERE, on every rank, forever (ADR 0043).
   router.get('/government/permissions', api.requireBuilder, api.requirePermission('government.manage'), (req, res) => {
     const permissions = catalog.PERMISSIONS.map((p) => ({
       key: p.key,
@@ -244,7 +244,7 @@ module.exports = function buildGovernanceRouter() {
     res.json({ permissions, principals: catalog.principals() });
   });
 
-  // rank: perm government.manage — every builder↔role assignment row.
+  // rank: perm government.manage — every builder↔rank assignment row.
   router.get('/government/assignments', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     try {
       const assignments = await db.listAssignments();
@@ -255,7 +255,7 @@ module.exports = function buildGovernanceRouter() {
     }
   });
 
-  // rank: perm government.manage — create a CUSTOM role (is_system false, no
+  // rank: perm government.manage — create a CUSTOM rank (is_system false, no
   // seeded_rank — the seeded four exist only via governance_002). Grants are
   // added one at a time via the toggle below, so creation carries none.
   router.post('/government/ranks', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
@@ -269,50 +269,50 @@ module.exports = function buildGovernanceRouter() {
       return res.fail('bad_rank_key', 400, { rank_key: rankKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
     }
     try {
-      const role = await db.createRole({
+      const rank = await db.createRank({
         rankKey,
         label: req.body.label,
         description: req.body.description ?? null,
         createdBy: req.builder.id,
       });
-      res.status(201).json({ role: { ...role, permissions: [] } });
+      res.status(201).json({ rank: { ...rank, permissions: [] } });
     } catch (err) {
       if (err && err.code === '23505') {
         return res.fail('rank_exists', 409, { rank_key: rankKey });
       }
       console.error('[gds] POST /government/ranks', err);
-      res.fail('role_create_failed', { status: 500, message: 'internal error' });
+      res.fail('rank_create_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm government.manage — grant one permission to a role (the toggle's ON
-  // half). The order of refusals is the authority order: role exists → role is not
-  // the Archon one → the key exists → the key is grantable TO THIS ROLE.
+  // rank: perm government.manage — grant one permission to a rank (the toggle's ON
+  // half). The order of refusals is the authority order: rank exists → rank is not
+  // the Archon one → the key exists → the key is grantable TO THIS RANK.
   router.put('/government/ranks/:rankKey/permissions/:permissionKey', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     const rankKey = rankKeyParam(req, res);
     if (rankKey === null) return;
     const permissionKey = req.params.permissionKey;
     try {
-      const role = await loadGrantEditableRole(res, rankKey);
-      if (role === null) return;
+      const rank = await loadGrantEditableRank(res, rankKey);
+      if (rank === null) return;
       if (!catalog.byKey(permissionKey)) {
         return res.fail('unknown_permission', 400, { permission_key: permissionKey });
       }
-      if (!catalog.isGrantableTo(permissionKey, role)) {
+      if (!catalog.isGrantableTo(permissionKey, rank)) {
         return res.fail('permission_not_grantable', 400, {
           permission_key: permissionKey,
           rank_key: rankKey,
           // Name the ACTUAL wall. "Not grantable" now has three distinct causes and
           // a caller that cannot tell them apart cannot tell a policy choice
-          // (widen the role) from a structural one (nothing will ever work).
+          // (widen the rank) from a structural one (nothing will ever work).
           reason: catalog.isSubstrate(permissionKey)
-            ? 'substrate-enforced (ADR 0043) — enforced outside the app by the pre-push hook / main-audit / the rank floor, so a grant row here would confer nothing. Non-grantable to EVERY role.'
+            ? 'substrate-enforced (ADR 0043) — enforced outside the app by the pre-push hook / main-audit / the rank floor, so a grant row here would confer nothing. Non-grantable to EVERY rank.'
             : catalog.isPrincipalKey(permissionKey)
-              ? 'a machine-principal permission — held by an exact builders.system_role identity, never by a role (ADR 0151 §3)'
-              : 'a system (trust-boundary) permission is non-grantable to a CUSTOM role; only a sub-Archon rank-role may carry one (ADR 0172)',
+              ? 'a machine-principal permission — held by an exact builders.system_role identity, never by a rank (ADR 0151 §3)'
+              : 'a system (trust-boundary) permission is non-grantable to a CUSTOM rank; only a sub-Archon rank-rank may carry one (ADR 0172)',
         });
       }
-      const granted = await db.grantRolePermission({ rankKey, permissionKey });
+      const granted = await db.grantRankPermission({ rankKey, permissionKey });
       res.json({ ok: true, rank_key: rankKey, permission_key: permissionKey, granted });
     } catch (err) {
       console.error('[gds] PUT /government/ranks/:rankKey/permissions/:permissionKey', err);
@@ -329,9 +329,9 @@ module.exports = function buildGovernanceRouter() {
     if (rankKey === null) return;
     const permissionKey = req.params.permissionKey;
     try {
-      const role = await loadGrantEditableRole(res, rankKey);
-      if (role === null) return;
-      const removed = await db.revokeRolePermission({ rankKey, permissionKey });
+      const rank = await loadGrantEditableRank(res, rankKey);
+      if (rank === null) return;
+      const removed = await db.revokeRankPermission({ rankKey, permissionKey });
       res.json({ ok: true, rank_key: rankKey, permission_key: permissionKey, removed });
     } catch (err) {
       console.error('[gds] DELETE /government/ranks/:rankKey/permissions/:permissionKey', err);
@@ -339,42 +339,42 @@ module.exports = function buildGovernanceRouter() {
     }
   });
 
-  // rank: perm government.manage — restore a SEEDED rank-role to its catalog
-  // default (ADR 0172). The counterweight to making the rank-roles editable: a
+  // rank: perm government.manage — restore a SEEDED rank to its catalog
+  // default (ADR 0172). The counterweight to making the ranks editable: a
   // rank's grant set is ~60 rows, so an owner who drifts one has no practical way
   // back by clicking, and "what does Trusted mean by default" is a question only
-  // the catalog can answer. Restores catalog.seedForRank(role.seeded_rank) — the
+  // the catalog can answer. Restores catalog.seedForRank(rank.seeded_rank) — the
   // same derivation governance_002 seeded from, so the answer cannot drift from
   // the floors even after later catalog edits.
   //
-  // Deliberately NOT offered for a CUSTOM role: a custom role has no catalog
+  // Deliberately NOT offered for a CUSTOM rank: a custom rank has no catalog
   // default to return to (its "default" is the empty set it was created with), so
   // the honest verb there is revoking the grants, which the toggle already does.
   router.post('/government/ranks/:rankKey/reset', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     const rankKey = rankKeyParam(req, res);
     if (rankKey === null) return;
     try {
-      const role = await loadGrantEditableRole(res, rankKey);
-      if (role === null) return;
-      if (!role.is_system || !catalog.RANK_ORDER.includes(role.seeded_rank)) {
+      const rank = await loadGrantEditableRank(res, rankKey);
+      if (rank === null) return;
+      if (!rank.is_system || !catalog.RANK_ORDER.includes(rank.seeded_rank)) {
         return res.fail('rank_has_no_default', 400, {
           rank_key: rankKey,
-          reason: 'only a seeded rank-role has a catalog default to reset to; revoke a custom role\'s grants instead',
+          reason: 'only a seeded rank-rank has a catalog default to reset to; revoke a custom rank\'s grants instead',
         });
       }
       // The seed is the floor derivation, which never contains a principal key and
       // — below archon — never a system one. Filtering by isGrantableTo anyway keeps
       // reset from being a back door that writes what the toggle refuses.
-      const keys = catalog.seedForRank(role.seeded_rank).filter((k) => catalog.isGrantableTo(k, role));
-      const count = await db.resetRoleGrants({ rankKey, permissionKeys: keys });
-      res.json({ ok: true, rank_key: rankKey, seeded_rank: role.seeded_rank, permission_count: count });
+      const keys = catalog.seedForRank(rank.seeded_rank).filter((k) => catalog.isGrantableTo(k, rank));
+      const count = await db.resetRankGrants({ rankKey, permissionKeys: keys });
+      res.json({ ok: true, rank_key: rankKey, seeded_rank: rank.seeded_rank, permission_count: count });
     } catch (err) {
       console.error('[gds] POST /government/ranks/:rankKey/reset', err);
       res.fail('reset_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm government.manage — assign a CUSTOM role to a builder.
+  // rank: perm government.manage — assign a CUSTOM rank to a builder.
   // assigned_by is ALWAYS the session builder, never input (the audit trail's
   // "who did this" must be the authenticated actor).
   router.post('/government/assignments', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
@@ -387,9 +387,9 @@ module.exports = function buildGovernanceRouter() {
       return res.fail('bad_rank_key', 400, { rank_key: rankKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
     }
     try {
-      const role = await loadAssignableRole(res, rankKey);
-      if (role === null) return;
-      const assigned = await db.assignRole({
+      const rank = await loadAssignableRank(res, rankKey);
+      if (rank === null) return;
+      const assigned = await db.assignRank({
         builderId: req.body.builder_id,
         rankKey,
         assignedBy: req.builder.id,
@@ -404,7 +404,7 @@ module.exports = function buildGovernanceRouter() {
     }
   });
 
-  // rank: perm government.manage — remove a custom-role assignment. Idempotent:
+  // rank: perm government.manage — remove a custom-rank assignment. Idempotent:
   // `removed` says whether a row went away.
   router.delete('/government/assignments/:builderId/:rankKey', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     const builderId = parseId(req, res, { param: 'builderId', code: 'bad_builder_id', positiveInt: true });
@@ -412,9 +412,9 @@ module.exports = function buildGovernanceRouter() {
     const rankKey = rankKeyParam(req, res);
     if (rankKey === null) return;
     try {
-      const role = await loadAssignableRole(res, rankKey);
-      if (role === null) return;
-      const removed = await db.unassignRole({ builderId, rankKey });
+      const rank = await loadAssignableRank(res, rankKey);
+      if (rank === null) return;
+      const removed = await db.unassignRank({ builderId, rankKey });
       res.json({ ok: true, builder_id: builderId, rank_key: rankKey, removed });
     } catch (err) {
       console.error('[gds] DELETE /government/assignments/:builderId/:rankKey', err);
@@ -425,4 +425,4 @@ module.exports = function buildGovernanceRouter() {
   return router;
 };
 
-module.exports.governancePort = governancePort;
+module.exports.governmentPort = governmentPort;

package/modules/government/routes/rank-sync.js

@@ -1,27 +1,27 @@
 'use strict';
 
-// The governance module's rank-role SYNC port (ADR 0151, BV1.R95b).
+// The government module's rank SYNC port (ADR 0151, BV1.R95b).
 //
-// A second, deliberately tiny kernel port beside `governance` (routes/governance.js).
-// `governance` is the READ surface every gate resolves on every request; this is the
+// A second, deliberately tiny kernel port beside `government` (routes/government.js).
+// `government` is the READ surface every gate resolves on every request; this is the
 // single WRITE core needs — "this builder's rank is now X, make their seeded
-// rank-role match". They are kept apart on purpose:
+// rank match". They are kept apart on purpose:
 //   • the read port is on the hot path of every permission-gated request and is
 //     resolved by requirePermission(); a mutation has no business hanging off it;
 //   • this one is resolved by exactly three writers (the two _applyRankChangeTx
 //     twins + the sign-in path) and is a TRANSACTION PARTICIPANT — it takes the
-//     caller's client so the role rotation commits or rolls back with the rank write.
+//     caller's client so the rank rotation commits or rolls back with the rank write.
 // The port name is namespaced (`government.rankSync`) like the `ideas.capture` /
 // `art.getBuilderGeminiKeyRow` / `grade.builderRollingAvgGrade` ports.
 //
-// Registered from a route factory for the same reason routes/governance.js is:
+// Registered from a route factory for the same reason routes/government.js is:
 // mountModuleRoutes is the one boot hook that runs BOTH in the live server and
 // whenever a test rebuilds the router, and registration is hasProvider-guarded so a
 // rebuild never trips the seam's single-provider duplicate guard.
 //
 // The router is EMPTY and must stay empty. Rank-derived assignment is automatic and
 // has no HTTP surface; the MANUAL assignment CRUD is R110's Archon-gated tab on the
-// governance router. An endpoint here would be a way to hand out a rank-role without
+// government router. An endpoint here would be a way to hand out a rank without
 // changing the rank.
 
 const express = require('express');
@@ -41,7 +41,7 @@ function registerSeams() {
   }
 }
 
-module.exports = function buildGovernanceRoleSyncRouter() {
+module.exports = function buildGovernmentRankSyncRouter() {
   registerSeams();
   return express.Router();
 };