@bongos/core 1.19.185 → 1.19.187

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,

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
-// through the API) are enforced in routes/governance.js against the catalog —
+// 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;