@bongos/core 1.19.183 → 1.19.185

package/modules/government/migrations/government_002_rename_permission_keys.sql

@@ -0,0 +1,112 @@
+-- government_002_rename_permission_keys.sql
+-- Goal 1000068 R05 (task 1003006) — ADR 0174.
+--
+-- Renames the two permission KEYS that still carried the old vocabulary, in the
+-- grant rows that hold them:
+--
+--   governance.manage     -> government.manage
+--   page.view.governance  -> page.view.government
+--
+-- These are DATA, not schema: `government_rank_permissions.permission_key` is
+-- free text validated app-side against the code catalog (it is deliberately not
+-- a foreign key — the catalog is CODE, not a table; see governance_001).
+--
+-- ── WHY THIS IS SEPARATE FROM government_001 ────────────────────────────────
+-- 001 renamed the tables and pairs with the code that QUERIES them. This one
+-- pairs with `modules/government/catalog.js`, which declares the key strings,
+-- and it must land in the SAME release as that edit. The coupling is sharper
+-- than it looks: `resolver.js` DROPS any grant naming a key the catalog does not
+-- define (the fail-closed rule). So if these rows were renamed while the catalog
+-- still said `governance.manage`, every renamed grant would resolve to nothing —
+-- and because that key is what gates the Government tab, the owner would be
+-- locked out of the very surface used to diagnose it. The inverse is equally
+-- true: shipping the catalog edit without this migration leaves the live rows
+-- naming keys the catalog no longer defines, with the same result.
+--
+-- Both halves are in this commit, and the live instance's auto-upgrade sweep
+-- stays paused (task 1003011) until the whole rename is released together.
+--
+-- ── ROW-COUNT SAFETY ────────────────────────────────────────────────────────
+-- These are PRIMARY KEY columns (rank_key, permission_key). A rank that somehow
+-- held BOTH the old and the new key would collide on UPDATE, so the update is
+-- written to skip any row whose target already exists, and the assertion at the
+-- end proves the old keys are gone and the new counts match what was there
+-- before. Live baseline captured 2026-08-16 before the rename:
+--   governance.manage      -> 1 grant  (the archon rank only)
+--   page.view.governance   -> 2 grants (metic + archon)
+--
+-- IDEMPOTENT: re-running finds no old keys and changes nothing.
+--
+-- ROLLBACK: reverse the two UPDATEs (new key -> old key). Lossless.
+--   UPDATE government_rank_permissions SET permission_key = 'governance.manage'
+--    WHERE permission_key = 'government.manage';
+--   UPDATE government_rank_permissions SET permission_key = 'page.view.governance'
+--    WHERE permission_key = 'page.view.government';
+
+BEGIN;
+
+-- Capture the before-counts so the assertion below can prove nothing was lost.
+CREATE TEMP TABLE _govt_key_rename_before ON COMMIT DROP AS
+SELECT
+  count(*) FILTER (WHERE permission_key = 'governance.manage')    AS old_manage,
+  count(*) FILTER (WHERE permission_key = 'page.view.governance') AS old_page,
+  count(*) FILTER (WHERE permission_key = 'government.manage')    AS new_manage,
+  count(*) FILTER (WHERE permission_key = 'page.view.government') AS new_page
+FROM government_rank_permissions;
+
+UPDATE government_rank_permissions g
+   SET permission_key = 'government.manage'
+ WHERE g.permission_key = 'governance.manage'
+   AND NOT EXISTS (
+     SELECT 1 FROM government_rank_permissions x
+      WHERE x.rank_key = g.rank_key AND x.permission_key = 'government.manage');
+
+UPDATE government_rank_permissions g
+   SET permission_key = 'page.view.government'
+ WHERE g.permission_key = 'page.view.governance'
+   AND NOT EXISTS (
+     SELECT 1 FROM government_rank_permissions x
+      WHERE x.rank_key = g.rank_key AND x.permission_key = 'page.view.government');
+
+-- Any row the collision guard skipped would be a duplicate grant; drop it so the
+-- old key cannot survive. (Expected to affect zero rows — a rank holding both
+-- spellings should not exist. Written so the assertion below can be absolute.)
+DELETE FROM government_rank_permissions
+ WHERE permission_key IN ('governance.manage', 'page.view.governance');
+
+DO $$
+DECLARE
+  b record;
+  a_manage int;
+  a_page   int;
+  leftover int;
+BEGIN
+  SELECT * INTO b FROM _govt_key_rename_before;
+  SELECT count(*) INTO a_manage FROM government_rank_permissions WHERE permission_key = 'government.manage';
+  SELECT count(*) INTO a_page   FROM government_rank_permissions WHERE permission_key = 'page.view.government';
+  SELECT count(*) INTO leftover FROM government_rank_permissions
+    WHERE permission_key IN ('governance.manage', 'page.view.governance');
+
+  IF leftover <> 0 THEN
+    RAISE EXCEPTION 'government key rename: % row(s) still carry an old key — rolling back.', leftover;
+  END IF;
+
+  -- Every grant that existed under either spelling must exist under the new one.
+  IF a_manage <> GREATEST(b.old_manage, b.new_manage) THEN
+    RAISE EXCEPTION 'government.manage grant count is % but % was expected (before: old=%, new=%) — rolling back.',
+      a_manage, GREATEST(b.old_manage, b.new_manage), b.old_manage, b.new_manage;
+  END IF;
+  IF a_page <> GREATEST(b.old_page, b.new_page) THEN
+    RAISE EXCEPTION 'page.view.government grant count is % but % was expected (before: old=%, new=%) — rolling back.',
+      a_page, GREATEST(b.old_page, b.new_page), b.old_page, b.new_page;
+  END IF;
+
+  -- The lockout guard: SOMEONE must still hold the key that opens this tab.
+  IF a_manage = 0 THEN
+    RAISE EXCEPTION 'no rank holds government.manage after the rename — that is a lockout. Rolling back.';
+  END IF;
+
+  RAISE NOTICE 'government key rename OK: government.manage=% page.view.government=%', a_manage, a_page;
+END $$;
+
+COMMIT;

package/modules/government/module.json

@@ -0,0 +1,22 @@
+{
+  "key": "government",
+  "title": "Government (configurable ranks & permissions)",
+  "description": "Discord-style configurable ranks and permissions (ADR 0151, BONGOS-V1 goal 1000030; renamed governance\u2192government by ADR 0174). Permissions are the atomic authority unit and the four ranks (xenos/thetes/metic/archon) are the positions in the government; this module owns the code-defined permission catalog (each key flagged `system` = trust-boundary, `substrate` = enforced out of band, or operational = delegable) plus the compatibility seed that reproduces the rank thresholds exactly. A core-domain module, default-on: a Cloud Bongos instance ships configurable ranks the way it ships its status page. The word `role` is deliberately absent here \u2014 it is reserved for the three crafts (Artist, Ideator, Builder). Preserves ADR 0016 (authority resolved server-side, per request, uncached).",
+  "coreVersion": "^1.18.0",
+  "default": true,
+  "maintenance": {
+    "status": "core-maintained"
+  },
+  "contributes": {
+    "migrations": true,
+    "routes": [
+      "government",
+      "rank-sync"
+    ]
+  },
+  "provides": [
+    "government",
+    "government.rankSync"
+  ],
+  "consumes": []
+}

package/modules/{governance → government}/protected-surfaces.json

@@ -34,7 +34,6 @@
     { "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/governance/", "group": "authz", "why": "the governance module (ADR 0151) — its resolver, catalog, gates AND this registry ARE the authz core; the glob is the prospective carve so CREATION is gated as strictly as edits (ADR 0086 §4). Renamed to modules/government/ by goal 1000068 (ADR 0174); BOTH globs are listed for the transition and this one is dropped with the folder in R04." },
     { "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/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)" },

package/modules/{governance/rank-roles.js → government/ranks.js}

@@ -1,12 +1,12 @@
 'use strict';
 
-// modules/governance/rank-roles.js — the PURE rank→role rotation decision
+// modules/governance/ranks.js — the PURE rank→role rotation decision
 // (ADR 0151, BV1.R95b).
 //
 // A builder holds exactly ONE seeded rank-role. 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.syncRankRole) executes to keep it true:
+// 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
 // which to REMOVE.
 //
@@ -31,43 +31,43 @@
 // 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 governance_roles, or a role row) is a SEEDED
+// 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.
 // 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.
-function isSeededRankRole(row) {
+function isSeededRank(row) {
   return !!row
     && row.is_system === true
     && typeof row.seeded_rank === 'string'
     && row.seeded_rank.length > 0;
 }
 
-// planRankRoleSync({ rank, currentRoles, seededRoles }) → { target, add, remove, next }
+// planRankSync({ rank, currentRanks, seededRanks }) → { target, add, remove, next }
 //
 //   rank         the builder's rank AFTER the write being synced.
-//   currentRoles the builder's assignments, each { role_key, is_system, seeded_rank }.
-//   seededRoles  the seeded rank-roles the DB defines, each { role_key, seeded_rank,
+//   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
 //                stay DB truth — this file never re-declares the seed.
 //
-//   target  the seeded role_key the builder should end up with, or null when the
+//   target  the seeded rank_key the builder should end up with, or null when the
 //           rank has no seeded role (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 role_key set, sorted — "what the role set becomes".
-function planRankRoleSync({ rank, currentRoles = [], seededRoles = [] } = {}) {
-  const match = seededRoles.find((r) => isSeededRankRole(r) && r.seeded_rank === rank);
-  const target = match ? match.role_key : null;
+//   next    the resulting rank_key set, sorted — "what the role 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;
 
-  const held = currentRoles.filter((r) => r && typeof r.role_key === 'string');
+  const held = currentRanks.filter((r) => r && typeof r.rank_key === 'string');
   const remove = held
-    .filter((r) => isSeededRankRole(r) && r.role_key !== target)
-    .map((r) => r.role_key);
-  const add = target && !held.some((r) => r.role_key === target) ? [target] : [];
+    .filter((r) => isSeededRank(r) && r.rank_key !== target)
+    .map((r) => r.rank_key);
+  const add = target && !held.some((r) => r.rank_key === target) ? [target] : [];
 
   const removed = new Set(remove);
   const next = held
-    .map((r) => r.role_key)
+    .map((r) => r.rank_key)
     .filter((key) => !removed.has(key))
     .concat(add)
     .sort();
@@ -80,4 +80,4 @@ function planRankRoleSync({ rank, currentRoles = [], seededRoles = [] } = {}) {
   });
 }
 
-module.exports = { planRankRoleSync, isSeededRankRole };
+module.exports = { planRankSync, isSeededRank };

package/modules/{governance/routes/governance.js → government/routes/government.js}

@@ -81,8 +81,8 @@ const governancePort = {
 };
 
 function registerSeams() {
-  if (!api.hasProvider('governance')) {
-    api.registerProvider('governance', governancePort);
+  if (!api.hasProvider('government')) {
+    api.registerProvider('government', governancePort);
   }
   // 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
@@ -96,8 +96,8 @@ function registerSeams() {
     api.registerProvider('session-grants-sql', {
       selectFragment: `,
             (SELECT COALESCE(array_agg(DISTINCT rp.permission_key), '{}')
-               FROM governance_builder_roles br
-               JOIN governance_role_permissions rp ON rp.role_key = br.role_key
+               FROM government_builder_ranks br
+               JOIN government_rank_permissions rp ON rp.rank_key = br.rank_key
               WHERE br.builder_id = s.builder_id) AS raw_permission_keys`,
     });
   }
@@ -105,7 +105,7 @@ function registerSeams() {
 
 // ── the R110 CRUD surface (ADR 0151 §2 — the governance tab's server half) ────
 //
-// Every route — the three reads included — gates on the `governance.manage`
+// Every route — the three reads included — gates on the `government.manage`
 // atom (system, floor archon): this surface EDITS the role/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
@@ -116,7 +116,7 @@ function registerSeams() {
 // 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
-//     always ordinary `governance_role_permissions` rows (the governance_002 seed
+//     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
@@ -131,37 +131,37 @@ function registerSeams() {
 // SUBSTRATE keys stay non-grantable to everything, rank-roles included, because a
 // grant row for one delegates nothing (ADR 0043 enforces them out of band).
 const { validateOrRespond, LIMITS, parseId } = api;
-const ROLE_KEY_RE = /^[a-z][a-z0-9-]*$/;
-const ROLE_KEY_MAX = 64;
+const RANK_KEY_RE = /^[a-z][a-z0-9-]*$/;
+const RANK_KEY_MAX = 64;
 
 module.exports = function buildGovernanceRouter() {
   registerSeams();
   const router = express.Router();
 
-  // Param guard for :roleKey. Responds bad_role_key and returns null on a
+  // Param guard for :rankKey. Responds bad_rank_key and returns null on a
   // malformed slug (seeded keys like 'metic' pass shape and are refused later,
   // by policy, with the honest code).
-  function roleKeyParam(req, res) {
-    const roleKey = req.params.roleKey;
-    if (roleKey.length > ROLE_KEY_MAX || !ROLE_KEY_RE.test(roleKey)) {
-      res.fail('bad_role_key', 400, { role_key: roleKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
+  function rankKeyParam(req, res) {
+    const rankKey = req.params.rankKey;
+    if (rankKey.length > RANK_KEY_MAX || !RANK_KEY_RE.test(rankKey)) {
+      res.fail('bad_rank_key', 400, { rank_key: rankKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
       return null;
     }
-    return roleKey;
+    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, roleKey) {
-    const role = await db.getRoleByKey(roleKey);
+  async function loadGrantEditableRole(res, rankKey) {
+    const role = await db.getRoleByKey(rankKey);
     if (!role) {
-      res.fail('role_not_found', 404, { role_key: roleKey });
+      res.fail('rank_not_found', 404, { rank_key: rankKey });
       return null;
     }
     if (role.is_system && role.seeded_rank === ARCHON) {
-      res.fail('archon_role_immutable', 403, { role_key: roleKey, reason: ARCHON_REASON });
+      res.fail('archon_rank_immutable', 403, { rank_key: rankKey, reason: ARCHON_REASON });
       return null;
     }
     return role;
@@ -169,14 +169,14 @@ module.exports = function buildGovernanceRouter() {
 
   // Load a role this API may ASSIGN. Unchanged from R110: every seeded rank-role is
   // refused, because assignment derives from builders.rank via the R95b sync.
-  async function loadAssignableRole(res, roleKey) {
-    const role = await db.getRoleByKey(roleKey);
+  async function loadAssignableRole(res, rankKey) {
+    const role = await db.getRoleByKey(rankKey);
     if (!role) {
-      res.fail('role_not_found', 404, { role_key: roleKey });
+      res.fail('rank_not_found', 404, { rank_key: rankKey });
       return null;
     }
     if (role.is_system) {
-      res.fail('seeded_role_assignment_forbidden', 403, { role_key: roleKey, reason: ASSIGN_REASON });
+      res.fail('seeded_rank_assignment_forbidden', 403, { rank_key: rankKey, reason: ASSIGN_REASON });
       return null;
     }
     return role;
@@ -185,18 +185,43 @@ module.exports = function buildGovernanceRouter() {
   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';
 
-  // rank: perm governance.manage — the full role list with each role's grants.
-  router.get('/governance/roles', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
+  // ── one-release compatibility aliases: /governance/* -> /government/* ──────
+  // ADR 0174 committed to keeping the pre-rename paths answering for exactly one
+  // release. The case this actually protects is narrow but real: a browser that
+  // still has the OLD hall page open when the instance upgrades will keep calling
+  // /governance/* against the new server. Everything else that consumed these
+  // paths (the hall bundle, the generated client) ships INSIDE the same core
+  // package and moves in lockstep.
+  //
+  // A 308 preserves the method and body, so a PUT/DELETE grant toggle survives
+  // the hop. The alias carries NO gate of its own — it redirects, and the real
+  // route re-runs requireBuilder + requirePermission on the followed request, so
+  // this cannot become a way around the wall.
+  //
+  // REMOVE THIS BLOCK one release after the rename ships (goal 1000068 follow-up).
+  // The `alias` counter in the log line is how we tell whether anything still
+  // calls them before deleting.
+  const LEGACY_PATH_PREFIX = '/governance';
+  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')}`;
+    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.
+  router.get('/government/ranks', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     try {
       const roles = await db.listRolesWithGrants();
       res.json({ roles });
     } catch (err) {
-      console.error('[gds] GET /governance/roles', err);
+      console.error('[gds] GET /government/ranks', err);
       res.fail('roles_list_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — the permission catalog + principals, straight
+  // rank: perm government.manage — the permission catalog + principals, straight
   // 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
@@ -205,7 +230,7 @@ module.exports = function buildGovernanceRouter() {
   //   • `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).
-  router.get('/governance/permissions', api.requireBuilder, api.requirePermission('governance.manage'), (req, res) => {
+  router.get('/government/permissions', api.requireBuilder, api.requirePermission('government.manage'), (req, res) => {
     const permissions = catalog.PERMISSIONS.map((p) => ({
       key: p.key,
       system: p.system,
@@ -219,33 +244,33 @@ module.exports = function buildGovernanceRouter() {
     res.json({ permissions, principals: catalog.principals() });
   });
 
-  // rank: perm governance.manage — every builder↔role assignment row.
-  router.get('/governance/assignments', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
+  // rank: perm government.manage — every builder↔role assignment row.
+  router.get('/government/assignments', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     try {
       const assignments = await db.listAssignments();
       res.json({ assignments });
     } catch (err) {
-      console.error('[gds] GET /governance/assignments', err);
+      console.error('[gds] GET /government/assignments', err);
       res.fail('assignments_list_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — create a CUSTOM role (is_system false, no
+  // rank: perm government.manage — create a CUSTOM role (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('/governance/roles', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
+  router.post('/government/ranks', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     if (validateOrRespond(req, res, {
-      role_key: { required: true, type: 'string', minLength: 2, maxLength: ROLE_KEY_MAX },
+      rank_key: { required: true, type: 'string', minLength: 2, maxLength: RANK_KEY_MAX },
       label: { required: true, type: 'string', minLength: 1, maxLength: LIMITS.TITLE },
       description: { type: 'string', maxLength: 2000 },
     })) return;
-    const roleKey = req.body.role_key;
-    if (!ROLE_KEY_RE.test(roleKey)) {
-      return res.fail('bad_role_key', 400, { role_key: roleKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
+    const rankKey = req.body.rank_key;
+    if (!RANK_KEY_RE.test(rankKey)) {
+      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({
-        roleKey,
+        rankKey,
         label: req.body.label,
         description: req.body.description ?? null,
         createdBy: req.builder.id,
@@ -253,22 +278,22 @@ module.exports = function buildGovernanceRouter() {
       res.status(201).json({ role: { ...role, permissions: [] } });
     } catch (err) {
       if (err && err.code === '23505') {
-        return res.fail('role_exists', 409, { role_key: roleKey });
+        return res.fail('rank_exists', 409, { rank_key: rankKey });
       }
-      console.error('[gds] POST /governance/roles', err);
+      console.error('[gds] POST /government/ranks', err);
       res.fail('role_create_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — grant one permission to a role (the toggle's ON
+  // 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.
-  router.put('/governance/roles/:roleKey/permissions/:permissionKey', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
-    const roleKey = roleKeyParam(req, res);
-    if (roleKey === null) return;
+  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, roleKey);
+      const role = await loadGrantEditableRole(res, rankKey);
       if (role === null) return;
       if (!catalog.byKey(permissionKey)) {
         return res.fail('unknown_permission', 400, { permission_key: permissionKey });
@@ -276,7 +301,7 @@ module.exports = function buildGovernanceRouter() {
       if (!catalog.isGrantableTo(permissionKey, role)) {
         return res.fail('permission_not_grantable', 400, {
           permission_key: permissionKey,
-          role_key: roleKey,
+          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).
@@ -287,34 +312,34 @@ module.exports = function buildGovernanceRouter() {
               : 'a system (trust-boundary) permission is non-grantable to a CUSTOM role; only a sub-Archon rank-role may carry one (ADR 0172)',
         });
       }
-      const granted = await db.grantRolePermission({ roleKey, permissionKey });
-      res.json({ ok: true, role_key: roleKey, permission_key: permissionKey, granted });
+      const granted = await db.grantRolePermission({ rankKey, permissionKey });
+      res.json({ ok: true, rank_key: rankKey, permission_key: permissionKey, granted });
     } catch (err) {
-      console.error('[gds] PUT /governance/roles/:roleKey/permissions/:permissionKey', err);
+      console.error('[gds] PUT /government/ranks/:rankKey/permissions/:permissionKey', err);
       res.fail('grant_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — revoke a grant (the toggle's OFF half).
+  // rank: perm government.manage — revoke a grant (the toggle's OFF half).
   // Deliberately NOT validated against the catalog: a grant whose key the
   // catalog since retired is exactly the row an Archon most needs to remove
   // (the resolver already drops it — this is hygiene, not authority).
-  router.delete('/governance/roles/:roleKey/permissions/:permissionKey', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
-    const roleKey = roleKeyParam(req, res);
-    if (roleKey === null) return;
+  router.delete('/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, roleKey);
+      const role = await loadGrantEditableRole(res, rankKey);
       if (role === null) return;
-      const removed = await db.revokeRolePermission({ roleKey, permissionKey });
-      res.json({ ok: true, role_key: roleKey, permission_key: permissionKey, removed });
+      const removed = await db.revokeRolePermission({ rankKey, permissionKey });
+      res.json({ ok: true, rank_key: rankKey, permission_key: permissionKey, removed });
     } catch (err) {
-      console.error('[gds] DELETE /governance/roles/:roleKey/permissions/:permissionKey', err);
+      console.error('[gds] DELETE /government/ranks/:rankKey/permissions/:permissionKey', err);
       res.fail('revoke_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — restore a SEEDED rank-role to its catalog
+  // 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'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
@@ -325,15 +350,15 @@ module.exports = function buildGovernanceRouter() {
   // Deliberately NOT offered for a CUSTOM role: a custom role 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('/governance/roles/:roleKey/reset', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
-    const roleKey = roleKeyParam(req, res);
-    if (roleKey === null) return;
+  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, roleKey);
+      const role = await loadGrantEditableRole(res, rankKey);
       if (role === null) return;
       if (!role.is_system || !catalog.RANK_ORDER.includes(role.seeded_rank)) {
-        return res.fail('role_has_no_default', 400, {
-          role_key: roleKey,
+        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',
         });
       }
@@ -341,58 +366,58 @@ module.exports = function buildGovernanceRouter() {
       // — 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({ roleKey, permissionKeys: keys });
-      res.json({ ok: true, role_key: roleKey, seeded_rank: role.seeded_rank, permission_count: count });
+      const count = await db.resetRoleGrants({ rankKey, permissionKeys: keys });
+      res.json({ ok: true, rank_key: rankKey, seeded_rank: role.seeded_rank, permission_count: count });
     } catch (err) {
-      console.error('[gds] POST /governance/roles/:roleKey/reset', err);
+      console.error('[gds] POST /government/ranks/:rankKey/reset', err);
       res.fail('reset_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — assign a CUSTOM role to a builder.
+  // rank: perm government.manage — assign a CUSTOM role 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('/governance/assignments', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
+  router.post('/government/assignments', api.requireBuilder, api.requirePermission('government.manage'), async (req, res) => {
     if (validateOrRespond(req, res, {
       builder_id: { required: true, type: 'integer', min: 1 },
-      role_key: { required: true, type: 'string', minLength: 2, maxLength: ROLE_KEY_MAX },
+      rank_key: { required: true, type: 'string', minLength: 2, maxLength: RANK_KEY_MAX },
     })) return;
-    const roleKey = req.body.role_key;
-    if (!ROLE_KEY_RE.test(roleKey)) {
-      return res.fail('bad_role_key', 400, { role_key: roleKey, expected: 'a kebab-case slug (^[a-z][a-z0-9-]*$)' });
+    const rankKey = req.body.rank_key;
+    if (!RANK_KEY_RE.test(rankKey)) {
+      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, roleKey);
+      const role = await loadAssignableRole(res, rankKey);
       if (role === null) return;
       const assigned = await db.assignRole({
         builderId: req.body.builder_id,
-        roleKey,
+        rankKey,
         assignedBy: req.builder.id,
       });
-      res.status(assigned ? 201 : 200).json({ ok: true, builder_id: req.body.builder_id, role_key: roleKey, assigned });
+      res.status(assigned ? 201 : 200).json({ ok: true, builder_id: req.body.builder_id, rank_key: rankKey, assigned });
     } catch (err) {
       if (err && err.code === '23503') {
         return res.fail('builder_not_found', 404, { builder_id: req.body.builder_id });
       }
-      console.error('[gds] POST /governance/assignments', err);
+      console.error('[gds] POST /government/assignments', err);
       res.fail('assign_failed', { status: 500, message: 'internal error' });
     }
   });
 
-  // rank: perm governance.manage — remove a custom-role assignment. Idempotent:
+  // rank: perm government.manage — remove a custom-role assignment. Idempotent:
   // `removed` says whether a row went away.
-  router.delete('/governance/assignments/:builderId/:roleKey', api.requireBuilder, api.requirePermission('governance.manage'), async (req, res) => {
+  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 });
     if (builderId === null) return;
-    const roleKey = roleKeyParam(req, res);
-    if (roleKey === null) return;
+    const rankKey = rankKeyParam(req, res);
+    if (rankKey === null) return;
     try {
-      const role = await loadAssignableRole(res, roleKey);
+      const role = await loadAssignableRole(res, rankKey);
       if (role === null) return;
-      const removed = await db.unassignRole({ builderId, roleKey });
-      res.json({ ok: true, builder_id: builderId, role_key: roleKey, removed });
+      const removed = await db.unassignRole({ builderId, rankKey });
+      res.json({ ok: true, builder_id: builderId, rank_key: rankKey, removed });
     } catch (err) {
-      console.error('[gds] DELETE /governance/assignments/:builderId/:roleKey', err);
+      console.error('[gds] DELETE /government/assignments/:builderId/:rankKey', err);
       res.fail('unassign_failed', { status: 500, message: 'internal error' });
     }
   });