@bongos/core 1.19.186 → 1.19.187

package/modules/government/db.js

@@ -1,22 +1,22 @@
 'use strict';
 
-// modules/governance/db.js — the governance db slice (ADR 0151, BV1.R95).
+// modules/government/db.js — the government db slice (ADR 0151, BV1.R95).
 //
-// Reads the role/grant/assignment rows governance_001_tables.sql defines. The
+// Reads the rank/grant/assignment rows governance_001_tables.sql defines. The
 // per-domain db-slice pattern (ADR 0091 §2): the pool comes through the published
 // doorway (src/module-api.js), never `../../src/bongos/db`.
 //
 // NO CACHING, deliberately. Every read here runs against the live DB on the
-// request that needs it, so a revoked role takes effect on the builder's very
+// request that needs it, so a revoked rank takes effect on the builder's very
 // next request — the ADR 0016 trust-boundary rule the resolver inherits.
 
 const { pool } = require('../../src/module-api');
 const { planRankSync } = require('./ranks');
 
-// Every permission_key granted to any role the builder holds. Duplicates across
-// roles are collapsed by the DISTINCT — the resolver's UNION semantics. Returns
+// Every permission_key granted to any rank the builder holds. Duplicates across
+// ranks are collapsed by the DISTINCT — the resolver's UNION semantics. Returns
 // a flat array of raw key strings (validated against the catalog by resolver.js);
-// [] for a builder with no roles, which fails closed to zero authority.
+// [] for a builder with no ranks, which fails closed to zero authority.
 async function getPermissionKeysForBuilder(builderId) {
   const { rows } = await pool.query(
     `SELECT DISTINCT rp.permission_key
@@ -28,9 +28,9 @@ async function getPermissionKeysForBuilder(builderId) {
   return rows.map((r) => r.permission_key);
 }
 
-// The role keys a builder holds, for introspection surfaces (the Archon tab,
+// The rank keys a builder holds, for introspection surfaces (the Archon tab,
 // R110/R111) and for explaining a 403. Not part of the resolve path.
-async function getRoleKeysForBuilder(builderId) {
+async function getRankKeysForBuilder(builderId) {
   const { rows } = await pool.query(
     `SELECT rank_key FROM government_builder_ranks WHERE builder_id = $1 ORDER BY rank_key`,
     [builderId],
@@ -38,24 +38,24 @@ async function getRoleKeysForBuilder(builderId) {
   return rows.map((r) => r.rank_key);
 }
 
-// --- the rank→role WRITE half (BV1.R95b) ------------------------------------
+// --- the rank→rank WRITE half (BV1.R95b) ------------------------------------
 //
 // Everything above this line only READS. Until R95b the only write to
 // government_builder_ranks in the whole repo was governance_002's run-once
-// backfill, so a builder created after it had NO role (locked out of every
-// permission gate) and a builder whose rank CHANGED kept their OLD rank-role
+// backfill, so a builder created after it had NO rank (locked out of every
+// permission gate) and a builder whose rank CHANGED kept their OLD rank
 // (a demoted Archon still resolving Archon permissions — the ADR 0016 defect).
 //
 // The writer below is a TRANSACTION PARTICIPANT: every caller hands it the client
-// its own BEGIN/COMMIT is running on, so the role rotation commits — or rolls back
+// its own BEGIN/COMMIT is running on, so the rank rotation commits — or rolls back
 // — atomically with the rank write it accompanies. Core reaches it through the
 // `government.rankSync` kernel port (routes/rank-sync.js); it never imports this
 // module (ADR 0083).
 
-// The seeded rank-roles as the DB actually defines them. Read per call rather than
+// The seeded ranks as the DB actually defines them. Read per call rather than
 // cached: it is the same authority data the resolver refuses to memoise, and this
 // runs on rank writes + sign-in, never in a hot loop.
-async function getSeededRankRoles(q) {
+async function getSeededRanks(q) {
   const { rows } = await q.query(
     `SELECT rank_key, seeded_rank, is_system
        FROM government_ranks
@@ -64,9 +64,9 @@ async function getSeededRankRoles(q) {
   return rows;
 }
 
-// A builder's assignments joined to their role definitions, so the plan can tell a
-// seeded rank-role from an Archon-assigned custom one.
-async function getRoleAssignmentsForBuilder(q, builderId) {
+// A builder's assignments joined to their rank definitions, so the plan can tell a
+// seeded rank from an Archon-assigned custom one.
+async function getRankAssignmentsForBuilder(q, builderId) {
   const { rows } = await q.query(
     `SELECT br.rank_key, r.is_system, r.seeded_rank
        FROM government_builder_ranks br
@@ -77,15 +77,15 @@ async function getRoleAssignmentsForBuilder(q, builderId) {
   return rows;
 }
 
-// syncRank(client, { builderId, rank }) — make the builder's seeded rank-role
+// syncRank(client, { builderId, rank }) — make the builder's seeded rank
 // match `rank`: add the matching one, DELETE every other seeded one, leave custom
-// roles alone. `client` is the caller's open transaction client; pass null/undefined
+// ranks alone. `client` is the caller's open transaction client; pass null/undefined
 // to run on the pool (the sign-in path, which has no surrounding transaction).
 //
-// Idempotent — a builder whose role already matches costs two SELECTs and no write,
+// Idempotent — a builder whose rank already matches costs two SELECTs and no write,
 // so calling it on every sign-in quietly repairs drift instead of accumulating it.
 // The DELETE is keyed on the plan's `remove` list, which is built only from rows the
-// join proved are is_system seeded roles, so a custom role can never be caught by it.
+// join proved are is_system seeded ranks, so a custom rank can never be caught by it.
 // assigned_by is left NULL: a rank-derived assignment is the system's, not a person's
 // (governance_002's backfill uses the same convention; the human decision is audited
 // in credit_log's rank_change row).
@@ -94,8 +94,8 @@ async function syncRank(client, { builderId, rank } = {}) {
     return { target: null, added: [], removed: [] };
   }
   const q = client || pool;
-  const seededRoles = await getSeededRankRoles(q);
-  const currentRoles = await getRoleAssignmentsForBuilder(q, builderId);
+  const seededRoles = await getSeededRanks(q);
+  const currentRoles = await getRankAssignmentsForBuilder(q, builderId);
   const plan = planRankSync({ rank, currentRoles, seededRoles });
 
   if (plan.remove.length > 0) {
@@ -116,16 +116,16 @@ async function syncRank(client, { builderId, rank } = {}) {
   return { target: plan.target, added: [...plan.add], removed: [...plan.remove] };
 }
 
-// --- the R110 CRUD surface (roles / grants / assignments) --------------------
+// --- the R110 CRUD surface (ranks / grants / assignments) --------------------
 //
-// The db half of the governance API routes. Deliberately DUMB writes: the
-// authority invariants (system perms non-grantable, seeded rank-roles immutable
+// The db half of the government API routes. Deliberately DUMB writes: the
+// authority invariants (system perms non-grantable, seeded ranks immutable
 // through the API) are enforced in routes/government.js against the catalog —
 // the same split governance_001 documents (permission_key is validated app-side,
 // not a FK). Grant/assign are ON CONFLICT DO NOTHING so the tab's toggle is
 // idempotent; each returns whether a row actually changed.
 
-async function listRolesWithGrants() {
+async function listRanksWithGrants() {
   const { rows } = await pool.query(
     `SELECT r.rank_key, r.label, r.description, r.is_system, r.seeded_rank,
             r.created_by, r.created_at,
@@ -139,62 +139,62 @@ async function listRolesWithGrants() {
   return rows;
 }
 
-async function getRoleByKey(roleKey) {
+async function getRankByKey(rankKey) {
   const { rows } = await pool.query(
     `SELECT rank_key, label, description, is_system, seeded_rank, created_by, created_at
        FROM government_ranks
       WHERE rank_key = $1`,
-    [roleKey],
+    [rankKey],
   );
   return rows[0] ?? null;
 }
 
-async function createRole({ roleKey, label, description, createdBy }) {
+async function createRank({ rankKey, label, description, createdBy }) {
   const { rows } = await pool.query(
     `INSERT INTO government_ranks (rank_key, label, description, is_system, seeded_rank, created_by)
      VALUES ($1, $2, $3, false, NULL, $4)
      RETURNING rank_key, label, description, is_system, seeded_rank, created_by, created_at`,
-    [roleKey, label, description ?? null, createdBy],
+    [rankKey, label, description ?? null, createdBy],
   );
   return rows[0];
 }
 
-async function grantRolePermission({ roleKey, permissionKey }) {
+async function grantRankPermission({ rankKey, permissionKey }) {
   const { rowCount } = await pool.query(
     `INSERT INTO government_rank_permissions (rank_key, permission_key)
      VALUES ($1, $2)
      ON CONFLICT (rank_key, permission_key) DO NOTHING`,
-    [roleKey, permissionKey],
+    [rankKey, permissionKey],
   );
   return rowCount > 0;
 }
 
-async function revokeRolePermission({ roleKey, permissionKey }) {
+async function revokeRankPermission({ rankKey, permissionKey }) {
   const { rowCount } = await pool.query(
     `DELETE FROM government_rank_permissions
       WHERE rank_key = $1 AND permission_key = $2`,
-    [roleKey, permissionKey],
+    [rankKey, permissionKey],
   );
   return rowCount > 0;
 }
 
-// Replace a role's entire grant set in ONE transaction (ADR 0172's reset). The
-// delete+insert pair must be atomic: a crash between them would leave the role
-// holding NOTHING, and for a rank-role that is every builder at that rank losing
+// Replace a rank's entire grant set in ONE transaction (ADR 0172's reset). The
+// delete+insert pair must be atomic: a crash between them would leave the rank
+// holding NOTHING, and for a rank that is every builder at that rank losing
 // every permission until someone noticed. The caller supplies the keys (the route
 // derives them from catalog.seedForRank), so this stays a dumb write like its
 // neighbours — the authority decision is made against the catalog, in the route.
-async function resetRoleGrants({ roleKey, permissionKeys }) {
+async function resetRankGrants({ rankKey, permissionKeys }) {
   const client = await pool.connect();
   try {
     await client.query('BEGIN');
-    await client.query(`DELETE FROM government_rank_permissions WHERE rank_key = $1`, [roleKey]);
+    await client.query(`DELETE FROM government_rank_permissions WHERE rank_key = $1`, [rankKey]);
     if (permissionKeys.length > 0) {
       await client.query(
         `INSERT INTO government_rank_permissions (rank_key, permission_key)
          SELECT $1, unnest($2::text[])
          ON CONFLICT (rank_key, permission_key) DO NOTHING`,
-        [roleKey, [...permissionKeys]],
+        [rankKey, [...permissionKeys]],
       );
     }
     await client.query('COMMIT');
@@ -210,7 +210,7 @@ async function resetRoleGrants({ roleKey, permissionKeys }) {
 async function listAssignments() {
   const { rows } = await pool.query(
     `SELECT br.builder_id, b.github_login, b.display_name, b.rank,
-            br.rank_key, r.label AS role_label, r.is_system, r.seeded_rank,
+            br.rank_key, r.label AS rank_label, r.is_system, r.seeded_rank,
             br.assigned_by, br.assigned_at
        FROM government_builder_ranks br
        JOIN builders b ON b.id = br.builder_id
@@ -220,38 +220,38 @@ async function listAssignments() {
   return rows;
 }
 
-async function assignRole({ builderId, roleKey, assignedBy }) {
+async function assignRank({ builderId, rankKey, assignedBy }) {
   const { rowCount } = await pool.query(
     `INSERT INTO government_builder_ranks (builder_id, rank_key, assigned_by)
      VALUES ($1, $2, $3)
      ON CONFLICT (builder_id, rank_key) DO NOTHING`,
-    [builderId, roleKey, assignedBy],
+    [builderId, rankKey, assignedBy],
   );
   return rowCount > 0;
 }
 
-async function unassignRole({ builderId, roleKey }) {
+async function unassignRank({ builderId, rankKey }) {
   const { rowCount } = await pool.query(
     `DELETE FROM government_builder_ranks
       WHERE builder_id = $1 AND rank_key = $2`,
-    [builderId, roleKey],
+    [builderId, rankKey],
   );
   return rowCount > 0;
 }
 
 module.exports = {
   getPermissionKeysForBuilder,
-  getRoleKeysForBuilder,
-  getSeededRankRoles,
-  getRoleAssignmentsForBuilder,
+  getRankKeysForBuilder,
+  getSeededRanks,
+  getRankAssignmentsForBuilder,
   syncRank,
-  listRolesWithGrants,
-  getRoleByKey,
-  createRole,
-  grantRolePermission,
-  revokeRolePermission,
-  resetRoleGrants,
+  listRanksWithGrants,
+  getRankByKey,
+  createRank,
+  grantRankPermission,
+  revokeRankPermission,
+  resetRankGrants,
   listAssignments,
-  assignRole,
-  unassignRole,
+  assignRank,
+  unassignRank,
 };

package/modules/government/protected-surfaces.js

@@ -1,14 +1,14 @@
 'use strict';
 
-// modules/governance/protected-surfaces.js — the protected-surface registry's
-// GOVERNANCE-side API (ADR 0151 §4, BV1.R101).
+// modules/government/protected-surfaces.js — the protected-surface registry's
+// GOVERNMENT-side API (ADR 0151 §4, BV1.R101).
 //
 // POLICY OWNS / SUBSTRATE ENFORCES — the whole point of this slice.
 //
-//   GOVERNANCE OWNS THE DATA. protected-surfaces.json (next to this file) says
+//   GOVERNMENT OWNS THE DATA. protected-surfaces.json (next to this file) says
 //   WHICH repo paths are protected, at WHAT rank floor, mapped to WHICH
 //   `system: true` catalog permission. That file is the source of truth; the
-//   Archon governance tab (R110/R111) edits it as policy. Before R101 the same
+//   Archon Government tab (R110/R111) edits it as policy. Before R101 the same
 //   information was a hardcoded PROTECTED_GLOBS constant inside the kernel.
 //
 //   THE OUT-OF-BAND SUBSTRATE STAYS THE ENFORCER. Nothing here enforces
@@ -20,7 +20,7 @@
 //   Moving enforcement into the app is the regression R101 exists to prevent
 //   (ADR 0151 §"Alternatives considered").
 //
-//   NO DB DEPENDENCY. A DB-backed override is a governance-tab concern layered
+//   NO DB DEPENDENCY. A DB-backed override is a government-tab concern layered
 //   on top and must never become a dependency of the hook — the hook runs on a
 //   laptop with no database and no network. This module is therefore
 //   synchronous, DB-free and requires nothing but the catalog and the doorway.
@@ -43,10 +43,10 @@ const ppc = api.permissionPathCheck;
 const SURFACES = ppc.PROTECTED_SURFACES;
 
 // ── invariants asserted at module load (fail loud on an authoring typo) ───────
-// The governance module is where the registry meets the permission catalog, so
+// The government module is where the registry meets the permission catalog, so
 // this is where "every protected surface maps to a real, non-grantable
 // permission" is checked. A surface mapping to an unknown key, or to a
-// `system: false` (grantable) key, would mean an Archon could hand a custom role
+// `system: false` (grantable) key, would mean an Archon could hand a custom rank
 // the power the substrate is supposed to reserve — exactly the wall ADR 0151 §4
 // builds. Fail loud rather than silently protecting nothing.
 for (const s of SURFACES) {

package/modules/government/protected-surfaces.json

@@ -1,6 +1,6 @@
 {
   "_readme": [
-    "The PROTECTED-SURFACE REGISTRY (ADR 0151 §4, BV1.R101). GOVERNANCE OWNS THIS DATA:",
+    "The PROTECTED-SURFACE REGISTRY (ADR 0151 §4, BV1.R101). GOVERNMENT OWNS THIS DATA:",
     "which repo paths are protected, at what rank floor, mapped to which system:true catalog",
     "permission. It replaces the PROTECTED_GLOBS constant that used to be hardcoded in",
     "src/bongos/permission-path-check.js.",
@@ -8,14 +8,14 @@
     "POLICY OWNS / SUBSTRATE ENFORCES. Editing this file re-maps POLICY. It does NOT move",
     "enforcement into the app: the pre-push git hook, the grader pre-pass, main-audit.js,",
     "gate-review.js and the goal-scope check all read this registry OUT OF BAND (no DB, no",
-    "server, no HTTP) and remain the enforcers (ADR 0043). A governance-tab edit can widen or",
+    "server, no HTTP) and remain the enforcers (ADR 0043). A government-tab edit can widen or",
     "narrow the protected set and re-map a floor; it can never make the request path the",
     "authority.",
     "",
     "WHY JSON IN THE REPO AND NOT A DB TABLE: the enforcers run where there is no database and",
     "no server (a git pre-push hook on a laptop, a CI job). The registry's canonical form must",
     "therefore be synchronously loadable from the checkout. A DB-backed override is a",
-    "governance-tab concern layered on top — never a dependency of the hook.",
+    "government-tab concern layered on top — never a dependency of the hook.",
     "",
     "SCHEMA: floor/permission at the top level are the defaults; a surface may override either.",
     "'glob' follows the permission-path-check matcher: an exact path, a trailing '/' subtree,",
@@ -34,7 +34,7 @@
     { "glob": "modules/lifecycle/routes/", "group": "authz", "why": "BV1.R86: the lifecycle routes carved out of src/bongos/routes/ — the gates follow the routes" },
     { "glob": "src/bongos/routes.js", "group": "authz", "why": "the route MOUNT table (a new ungated route lands here)" },
     { "glob": "server.js", "group": "authz", "why": "the Express entrypoint — wires every router + host routing" },
-    { "glob": "modules/government/", "group": "authz", "why": "the same authz core under its post-ADR-0174 name (goal 1000068, task 1003003). Listed BEFORE the folder moves, deliberately: `protected` is DERIVED from this registry, so a module key whose globs are absent here computes protected:false — which would silently drop the Archon gate on goal creation AND the pre-push block on these files for the whole window between the key landing and the folder arriving. The prospective-carve precedent is the modules/governance/ entry directly above (ADR 0086 §4)." },
+    { "glob": "modules/government/", "group": "authz", "why": "the same authz core under its post-ADR-0174 name (goal 1000068, task 1003003). Listed BEFORE the folder moves, deliberately: `protected` is DERIVED from this registry, so a module key whose globs are absent here computes protected:false — which would silently drop the Archon gate on goal creation AND the pre-push block on these files for the whole window between the key landing and the folder arriving. The prospective-carve precedent is the modules/government/ entry directly above (ADR 0086 §4)." },
     { "glob": "modules/dev-box/boxes.js", "group": "box-access", "why": "boxScopeForRank / provision floor — decides who gets a full source clone" },
     { "glob": "modules/dev-box/box-access.js", "group": "box-access", "why": "decideSourceAccess (rank → starter|full source)" },
     { "glob": "modules/dev-box/box-credential.js", "group": "box-access", "why": "mints the box source credential" },

package/modules/government/ranks.js

@@ -1,40 +1,40 @@
 'use strict';
 
-// modules/governance/ranks.js — the PURE rank→role rotation decision
+// modules/government/ranks.js — the PURE rank→rank rotation decision
 // (ADR 0151, BV1.R95b).
 //
-// A builder holds exactly ONE seeded rank-role. governance_002 seeds four of them
+// A builder holds exactly ONE seeded rank. governance_002 seeds four of them
 // (is_system=true, seeded_rank set) and backfills each builder the one matching
 // their rank — but that backfill is run-once, so nothing kept it true afterwards.
 // This is the decision the writer (db.syncRank) executes to keep it true:
-// given a builder's CURRENT assignments and a rank, which seeded role to ADD and
+// given a builder's CURRENT assignments and a rank, which seeded rank to ADD and
 // which to REMOVE.
 //
 // THE REMOVAL IS THE SECURITY HALF. An additive-only sync would leave a demoted
-// Archon still holding the `archon` role, so resolveBuilderPermissions() would keep
+// Archon still holding the `archon` rank, so resolveBuilderPermissions() would keep
 // returning Archon permissions. That is the exact privilege retention ADR 0016's
 // "a demotion takes effect on the builder's very next request" promise forbids: the
 // resolver is correctly per-request and uncached, but it reads an ASSIGNMENT, and a
 // stale assignment breaks the freshness guarantee one layer beneath the resolver.
 //
-// CUSTOM ROLES ARE NEVER TOUCHED. An Archon-assigned role (is_system=false, the
+// CUSTOM RANKS ARE NEVER TOUCHED. An Archon-assigned rank (is_system=false, the
 // R110 tab's output) must survive a rank change — only rows that are BOTH
-// is_system AND carry a seeded_rank rotate. Keying the removal on "every role this
+// is_system AND carry a seeded_rank rotate. Keying the removal on "every rank this
 // builder holds" would silently revoke delegated authority on every promotion.
 //
-// A rank with NO seeded role — one of the twelve reserved ranks migration 023's
-// CHECK still admits — yields target=null: every seeded role is removed and none is
+// A rank with NO seeded rank — one of the twelve reserved ranks migration 023's
+// CHECK still admits — yields target=null: every seeded rank is removed and none is
 // added, so the builder resolves to ZERO permissions. That is governance_002's
 // deliberate fail-closed divergence (ADR 0151), preserved rather than re-derived —
-// never invent a role for a rank the seed does not define.
+// never invent a rank for a rank the seed does not define.
 //
 // Pure: no DB, no I/O, no module state. The writer reads the two row sets and
 // executes this verdict, so the unit tests exercise production logic directly.
 
-// A row (an assignment joined to government_ranks, or a role row) is a SEEDED
-// rank-role only when it is both a system role and names the rank it reproduces.
+// A row (an assignment joined to government_ranks, or a rank row) is a SEEDED
+// rank only when it is both a system rank and names the rank it reproduces.
 // Both halves are required: is_system alone would admit a future non-rank system
-// role, and seeded_rank alone would trust a column a custom role could carry.
+// rank, and seeded_rank alone would trust a column a custom rank could carry.
 function isSeededRank(row) {
   return !!row
     && row.is_system === true
@@ -46,15 +46,15 @@ function isSeededRank(row) {
 //
 //   rank         the builder's rank AFTER the write being synced.
 //   currentRanks the builder's assignments, each { rank_key, is_system, seeded_rank }.
-//   seededRanks  the seeded rank-roles the DB defines, each { rank_key, seeded_rank,
-//                is_system }. Passed in rather than hardcoded so the four role keys
+//   seededRanks  the seeded ranks the DB defines, each { rank_key, seeded_rank,
+//                is_system }. Passed in rather than hardcoded so the four rank keys
 //                stay DB truth — this file never re-declares the seed.
 //
 //   target  the seeded rank_key the builder should end up with, or null when the
-//           rank has no seeded role (fail-closed divergence, above).
+//           rank has no seeded rank (fail-closed divergence, above).
 //   add     [] or [target] — empty when it is already held (idempotence).
-//   remove  every OTHER seeded rank-role currently held. Custom roles never appear.
-//   next    the resulting rank_key set, sorted — "what the role set becomes".
+//   remove  every OTHER seeded rank currently held. Custom ranks never appear.
+//   next    the resulting rank_key set, sorted — "what the rank set becomes".
 function planRankSync({ rank, currentRanks = [], seededRanks = [] } = {}) {
   const match = seededRanks.find((r) => isSeededRank(r) && r.seeded_rank === rank);
   const target = match ? match.rank_key : null;

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) {