@bongos/core 1.19.186 → 1.19.188

package/docs/api/openapi.json

@@ -5108,7 +5108,7 @@
           "government"
         ],
         "summary": "GET /government/assignments",
-        "description": "government.manage — every builder↔role assignment row.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — every builder↔rank assignment row.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5147,7 +5147,7 @@
           "government"
         ],
         "summary": "POST /government/assignments",
-        "description": "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).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — assign a CUSTOM rank to a builder. assigned_by is ALWAYS the session builder, never input (the audit trail's \"who did this\" must be the authenticated actor).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5192,7 +5192,7 @@
           "government"
         ],
         "summary": "DELETE /government/assignments/:builderId/:rankKey",
-        "description": "government.manage — remove a custom-role assignment. Idempotent: `removed` says whether a row went away.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — remove a custom-rank assignment. Idempotent: `removed` says whether a row went away.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5256,7 +5256,7 @@
           "government"
         ],
         "summary": "GET /government/permissions",
-        "description": "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 grantability depends on WHICH role is selected: • `grantable` — the CUSTOM-role answer (system:false). Unchanged meaning. • `system` — an in-app Archon power: locked on a custom role, togglable on a sub-Archon rank-role. • `substrate` — locked EVERYWHERE, on every role, forever (ADR 0043).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "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 grantability depends on WHICH rank is selected: • `grantable` — the CUSTOM-rank answer (system:false). Unchanged meaning. • `system` — an in-app Archon power: locked on a custom rank, togglable on a sub-Archon rank. • `substrate` — locked EVERYWHERE, on every rank, forever (ADR 0043).\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5297,7 +5297,7 @@
           "government"
         ],
         "summary": "GET /government/ranks",
-        "description": "government.manage — the full role list with each role's grants.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — the full rank list with each rank's grants.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5336,7 +5336,7 @@
           "government"
         ],
         "summary": "POST /government/ranks",
-        "description": "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.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — create a CUSTOM rank (is_system false, no seeded_rank — the seeded four exist only via governance_002). Grants are added one at a time via the toggle below, so creation carries none.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5388,7 +5388,7 @@
           "government"
         ],
         "summary": "PUT /government/ranks/:rankKey/permissions/:permissionKey",
-        "description": "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.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — grant one permission to a rank (the toggle's ON half). The order of refusals is the authority order: rank exists → rank is not the Archon one → the key exists → the key is grantable TO THIS RANK.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [
@@ -5514,7 +5514,7 @@
           "government"
         ],
         "summary": "POST /government/ranks/:rankKey/reset",
-        "description": "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 the catalog can answer. Restores catalog.seedForRank(role.seeded_rank) — the same derivation governance_002 seeded from, so the answer cannot drift from the floors even after later catalog edits. Deliberately NOT offered for a CUSTOM role: a custom role has no catalog 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.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
+        "description": "government.manage — restore a SEEDED rank to its catalog default (ADR 0172). The counterweight to making the ranks editable: a rank's grant set is ~60 rows, so an owner who drifts one has no practical way back by clicking, and \"what does Trusted mean by default\" is a question only the catalog can answer. Restores catalog.seedForRank(rank.seeded_rank) — the same derivation governance_002 seeded from, so the answer cannot drift from the floors even after later catalog edits. Deliberately NOT offered for a CUSTOM rank: a custom rank has no catalog default to return to (its \"default\" is the empty set it was created with), so the honest verb there is revoking the grants, which the toggle already does.\n\n**Rank:** `archon` — Archon only (rank and identity management + the escalation keys — the trust boundary).\n\n**Permissions:** `government.manage` (all required).",
         "x-rank": "archon",
         "x-source": "modules/government/routes/government.js",
         "x-permissions": [

package/docs/api-reference.md

@@ -218,15 +218,15 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
-| GET | `/api/bongos/government/assignments` | `archon` | — | government.manage — every builder↔role assignment row. |
-| POST | `/api/bongos/government/assignments` | `archon` | `builder_id`, `rank_key` | government.manage — assign a CUSTOM role to a builder. |
-| DELETE | `/api/bongos/government/assignments/:builderId/:rankKey` | `archon` | — | government.manage — remove a custom-role assignment. |
+| GET | `/api/bongos/government/assignments` | `archon` | — | government.manage — every builder↔rank assignment row. |
+| POST | `/api/bongos/government/assignments` | `archon` | `builder_id`, `rank_key` | government.manage — assign a CUSTOM rank to a builder. |
+| DELETE | `/api/bongos/government/assignments/:builderId/:rankKey` | `archon` | — | government.manage — remove a custom-rank assignment. |
 | GET | `/api/bongos/government/permissions` | `archon` | — | government.manage — the permission catalog + principals, straight from code (the catalog is CODE, not a table); no DB read. |
-| GET | `/api/bongos/government/ranks` | `archon` | — | government.manage — the full role list with each role's grants. |
-| POST | `/api/bongos/government/ranks` | `archon` | `rank_key`, `label`, `description` | government.manage — create a CUSTOM role (is_system false, no seeded_rank — the seeded four exist only via governance_002). |
-| PUT | `/api/bongos/government/ranks/:rankKey/permissions/:permissionKey` | `archon` | — | government.manage — grant one permission to a role (the toggle's ON half). |
+| GET | `/api/bongos/government/ranks` | `archon` | — | government.manage — the full rank list with each rank's grants. |
+| POST | `/api/bongos/government/ranks` | `archon` | `rank_key`, `label`, `description` | government.manage — create a CUSTOM rank (is_system false, no seeded_rank — the seeded four exist only via governance_002). |
+| PUT | `/api/bongos/government/ranks/:rankKey/permissions/:permissionKey` | `archon` | — | government.manage — grant one permission to a rank (the toggle's ON half). |
 | DELETE | `/api/bongos/government/ranks/:rankKey/permissions/:permissionKey` | `archon` | — | government.manage — revoke a grant (the toggle's OFF half). |
-| POST | `/api/bongos/government/ranks/:rankKey/reset` | `archon` | — | government.manage — restore a SEEDED rank-role to its catalog default (ADR 0172). |
+| POST | `/api/bongos/government/ranks/:rankKey/reset` | `archon` | — | government.manage — restore a SEEDED rank to its catalog default (ADR 0172). |
 
 ## `grades` (1)
 

package/docs/architecture.md

@@ -231,7 +231,7 @@ markdown describes, the DB enforces.**
 
 - **`example.com`** — game (Phaser + Colyseus). Static files from `public/`. `/builders` + `/builders/*` now **301-redirect to `builders.example.com/<rest>`** ([#739](https://example.com/builders#/task/739) then promoted to permanent 301 in [#741](https://example.com/builders#/task/741), ADR 0036 cutover); the apex no longer serves the builder surface directly.
 - **`status.example.com`** — public build dashboard. **Carved to the `status-ui` module in BV1.R84** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-status/` to `modules/status-ui/public/`, now served by the loader's web-surface seam (`moduleWebSurfaces` → `serve-internal.js`, routed on the `status.` Host prefix the manifest declares) instead of a hardcoded block — no behavior change. Layout reorganized in [#726](https://example.com/builders#/task/726) (ADR 0036): Pulse / Watch(uptime) / Architects / Works / Treasury / Lately Inscribed / The World — the grade-aggregate, estimation-drift, and repo-health tablets moved to the Archon `/watch` page. **⚠ Served OFF the droplet** (ADR 0029, outage resilience): the live page is **GitHub Pages from the separate repo `example-owner/example-status`** (CNAME → Fastly), reading data cross-origin from the droplet's `/api/gds/public/*` (CORS open) and an availability banner from the prober's `status-data` branch. The droplet still serves `modules/status-ui/public/` (on the `status.` host) as a same-origin fallback, but **DNS points at Pages, not the droplet** — so a droplet deploy does NOT update the live page. Changes to the surface publish to the mirror via `scripts/status-mirror-sync.js` (re-pointed at `modules/status-ui/public/`; status.js/style.css/cursors are byte-identical copies; index.html gets the off-box bits injected), run automatically by `.github/workflows/sync-status-mirror.yml` (needs the `STATUS_MIRROR_TOKEN` secret) ([#737](https://example.com/builders#/task/737)). **⚠ FOLLOW-UP (R84):** that workflow's path trigger still watches `public-status/**` and must be re-pointed at `modules/status-ui/public/**` by an owner/Archon — the GitHub App can't push `.github/workflows/*` (learning 107), so until then the mirror sync won't auto-fire on future status edits.
-- **`builders.example.com`** — dedicated builder surface (`isBuildersHost`, ADR 0036). **Carved to the `hall-ui` module in BV1.R85** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-builders/` to `modules/hall-ui/public/` (~13k LOC, the largest module) and is a loader-discovered web-surface module (`contributes.webSurfaces` host `builders.`). UNLIKE the generic status surface it keeps its **dedicated** serving block in `serve-internal.js` (`BUILDERS_DIR = modules/hall-ui/public/`), partitioned out of the generic web-surface loop on the `isBuildersHost` predicate. A thin rewrite shim maps every non-API path onto the existing `/builders/*` tree (so all serving + gating + asset-stamping is reused), serving the hall (`/`), the Metic+ **`/watch`** monitoring page (gated by `requireGovernancePage`), **`/settings`** (Voices + Craft prefs), plus ranks/sessions/primer/diagrams. No behavior change — byte-identical (only `window.__MODULES__.enabled` gains `hall-ui:true`). **Additive** — until its DNS A record + cert are live, the whole surface stays reachable at `example.com/builders/*`. No `.github/workflows/*` follow-up: unlike R84, no workflow path-trigger watches `public-builders/**`.
+- **`builders.example.com`** — dedicated builder surface (`isBuildersHost`, ADR 0036). **Carved to the `hall-ui` module in BV1.R85** ([ADR 0093](adr/<redacted>.md) §1): the surface moved from `public-builders/` to `modules/hall-ui/public/` (~13k LOC, the largest module) and is a loader-discovered web-surface module (`contributes.webSurfaces` host `builders.`). UNLIKE the generic status surface it keeps its **dedicated** serving block in `serve-internal.js` (`BUILDERS_DIR = modules/hall-ui/public/`), partitioned out of the generic web-surface loop on the `isBuildersHost` predicate. A thin rewrite shim maps every non-API path onto the existing `/builders/*` tree (so all serving + gating + asset-stamping is reused), serving the hall (`/`), the Metic+ **`/watch`** monitoring page (gated by `requireGovernmentPage`), **`/settings`** (Voices + Craft prefs), plus ranks/sessions/primer/diagrams. No behavior change — byte-identical (only `window.__MODULES__.enabled` gains `hall-ui:true`). **Additive** — until its DNS A record + cert are live, the whole surface stays reachable at `example.com/builders/*`. No `.github/workflows/*` follow-up: unlike R84, no workflow path-trigger watches `public-builders/**`.
 - **`/downloads/devbox/*`** (every host, mounted right after the API so the builders-host shim can't rewrite it — [#904](https://example.com/builders#/task/904), [ADR 0045](adr/<redacted>.md)): branded download surface for the Dev Box desktop app. `/{mac-arm64,mac-x64,win-x64}` (+ `mac`/`win` aliases) 302 to the release assets on the public releases repo named in [`config/devbox-app.json`](../config/devbox-app.json); `latest.json` feeds the app's update check. Logic in [`src/devbox-downloads.js`](../src/devbox-downloads.js); the installers never ride the git deploy.
 - The `/api/gds/*` surface is reachable from every host. **Cross-subdomain sign-in:** the `gds_session` cookie is scoped to `.example.com` on the production hosts (apex/www/builders/status) and host-only on localhost/staging (no cross-env token bleed); the OAuth handshake runs on the canonical origin with a validated `?return=` (open-redirect-guarded) so the subdomain can land a builder back on itself.
 - Caddy gets a site block per host ([`infra/Caddyfile`](../infra/Caddyfile)), all reverse-proxying to `127.0.0.1:3000`.

package/docs/canonical-permissions.md

@@ -141,7 +141,7 @@ or missing ranks fail closed.
   - **the four escalation keys**, which look operational but are not: `POST /api/gds/tasks/:id/confirm`
     (grader-bypass), `POST /api/gds/gate-approvals/:pr/approve` (CI deploy-gate override), protected-module
     **goal scope** ([ADR 0086](adr/<redacted>.md)), and `government.manage` (the
-    roles/permissions tab). Delegating any one of them lets a Metic reach Archon in four steps — create a
+    ranks/permissions tab). Delegating any one of them lets a Metic reach Archon in four steps — create a
     protected-scope goal in the permission core, claim a task there (protected paths already floor at
     *metic* per [ADR 0043](adr/<redacted>.md)), confirm
     past the failed grade, approve their own red gate — so keeping rank Archon-only depends on keeping
@@ -152,17 +152,17 @@ or missing ranks fail closed.
 
   > **Amended by [ADR 0172](adr/<redacted>.md) (owner decision, 2026-08-16).**
   > The paragraphs above describe the SEEDED ladder, which is still what a fresh instance boots with — but
-  > they are no longer a guarantee about a running one. The owner made the three sub-Archon **rank roles**
-  > editable from the governance tab and chose to include the seven in-app Archon powers, `government.manage`
+  > they are no longer a guarantee about a running one. The owner made the three sub-Archon **ranks**
+  > editable from the Government tab and chose to include the seven in-app Archon powers, `government.manage`
   > and `builder.rank.set` among them. So "no system permission is grantable below archon" now reads:
-  > *no system permission is grantable to a CUSTOM role, and none is seeded below archon* — an Archon may
-  > nonetheless hand one to a rank role deliberately. The four-step escalation chain described above is
+  > *no system permission is grantable to a CUSTOM rank, and none is seeded below archon* — an Archon may
+  > nonetheless hand one to a rank deliberately. The four-step escalation chain described above is
   > therefore **open by decision, not by accident**: whoever holds `government.manage` can reach the rest.
-  > Two things that did NOT move, and that bound the blast radius: the **Archon** rank-role is immutable
+  > Two things that did NOT move, and that bound the blast radius: the **Archon** rank is immutable
   > (nothing clickable revokes the permission needed to reach the tab), and the three **substrate** keys stay
-  > non-grantable to every role — ADR 0043's enforcers read the rank ladder and never consult this database,
+  > non-grantable to every rank — ADR 0043's enforcers read the rank ladder and never consult this database,
   > so no amount of in-app escalation produces a push to `main`, a protected-path edit, or an ssh session.
-  > `builders.rank` remains the only writer of who holds a rank role (R95b).
+  > `builders.rank` remains the only writer of who holds a rank (R95b).
 
   Earlier one-power delegations that ADR 0157 generalises: **task authoring** — `POST /api/gds/tasks`,
   `PATCH /api/gds/tasks/:id` (incl. the `newcomer_friendly` flag), `POST /api/gds/tasks/:id/promote`, and the
@@ -192,7 +192,7 @@ or missing ranks fail closed.
 
   **[ADR 0157](adr/<redacted>.md) added the whole operational block here** —
   20 permissions that had been Archon-gated only by ADR 0016's fail-closed default, never by a decision:
-  the governance/monitoring **pages** (`/watch`, `/harbor`, `/gate` — `page.view.government`) and
+  the government/monitoring **pages** (`/watch`, `/harbor`, `/gate` — `page.view.government`) and
   `GET /api/gds/sessions/search` (whose own `/sessions` page had no server gate at all until
   task 1002710 put it behind `page.view.government` alongside its three group-mates); the
   **dev-box + provisioning fleets** (`GET /boxes[/cost-ledger]`,

package/docs/file-map.md

@@ -37,7 +37,7 @@
 ├── brand/                       ← repo-canonical design system (ADR 0081)
 │   └── cloud-bongos/            ← Cloud Bongos brand: README design guide + tokens.json + regen_*.py + assets/ (mascot, 9 animation states, Docker-homage sky-whale, coin logo + Baloo 2 wordmark, painted code-glyph charms). Built under task 1506 (mascot restyle 1529, code glyphs 1527); illustrations generated via Gemini (modules/art-pipeline/pipeline gen_api).
 │
-├── config/                      ← per-instance config packs. Each pair resolves env → `X.json` (this host's, boundary-excluded) → `X.neutral.json` (the portable starter, the twin that publishes with the core): branding (ADR 0062 §3), modules, design-tokens, and governance role templates (BV1.R96 — labels/descriptions/custom-role templates only; live grants + assignments are DB rows).
+├── config/                      ← per-instance config packs. Each pair resolves env → `X.json` (this host's, boundary-excluded) → `X.neutral.json` (the portable starter, the twin that publishes with the core): branding (ADR 0062 §3), modules, design-tokens, and government rank templates (BV1.R96 — labels/descriptions/custom-rank templates only; live grants + assignments are DB rows).
 │
 ├── docs/
 │   ├── adr/                     ← Architecture Decision Records

package/modules/builder-settings/wandering-prefs.js

@@ -125,27 +125,27 @@ const LEVEL_CONTRACT = Object.freeze({
 // not name carries NO wandering metadata and resolves to the safest floor
 // (Locked), the same fail-closed posture the resolver takes for a rank with no
 // seeded role.
-const ROLE_WANDERING = Object.freeze({
+const RANK_WANDERING = Object.freeze({
   xenos: Object.freeze({ default: 0, ceiling: 0 }),
   thetes: Object.freeze({ default: 1, ceiling: 1 }),
   metic: Object.freeze({ default: 2, ceiling: 3 }),
   archon: Object.freeze({ default: 3, ceiling: 3 }),
 });
-const NO_ROLE_WANDERING = Object.freeze({ default: 0, ceiling: 0 });
+const NO_RANK_WANDERING = Object.freeze({ default: 0, ceiling: 0 });
 
-function roleWandering(roleKey) {
-  return Object.prototype.hasOwnProperty.call(ROLE_WANDERING, roleKey)
-    ? ROLE_WANDERING[roleKey]
-    : NO_ROLE_WANDERING;
+function rankWandering(rankKey) {
+  return Object.prototype.hasOwnProperty.call(RANK_WANDERING, rankKey)
+    ? RANK_WANDERING[rankKey]
+    : NO_RANK_WANDERING;
 }
 
 // DERIVED projections of the metadata above, kept because scripts/gds/session-eval.js
 // and the /me payload read them by rank. Deriving them means the two views cannot drift.
 const RANK_DEFAULT = Object.freeze(
-  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.default])),
+  Object.fromEntries(Object.entries(RANK_WANDERING).map(([role, meta]) => [role, meta.default])),
 );
 const RANK_MAX = Object.freeze(
-  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.ceiling])),
+  Object.fromEntries(Object.entries(RANK_WANDERING).map(([role, meta]) => [role, meta.ceiling])),
 );
 
 const TOP_LEVEL = LEVELS.length - 1; // 3
@@ -160,7 +160,7 @@ for (const key of LEVELS) {
 for (let i = 0; i < LEVELS.length; i++) {
   if (LEVEL_META[LEVELS[i]].n !== i) throw new Error(`wandering-prefs: LEVEL_META.${LEVELS[i]}.n must equal its index ${i}`);
 }
-for (const [role, meta] of Object.entries(ROLE_WANDERING)) {
+for (const [role, meta] of Object.entries(RANK_WANDERING)) {
   if (!isLevelInt(meta.default)) throw new Error(`wandering-prefs: role '${role}' has a non-level default`);
   if (!isLevelInt(meta.ceiling)) throw new Error(`wandering-prefs: role '${role}' has a non-level ceiling`);
   if (meta.default > meta.ceiling) throw new Error(`wandering-prefs: default > ceiling for role '${role}'`);
@@ -182,11 +182,11 @@ function levelIndex(key) {
 }
 
 function defaultLevelForRank(rank) {
-  return roleWandering(rank).default;
+  return rankWandering(rank).default;
 }
 
 function maxLevelForRank(rank) {
-  return roleWandering(rank).ceiling;
+  return rankWandering(rank).ceiling;
 }
 
 // The override a builder has stored (the raw 'wandering' key off behavior_prefs),
@@ -303,8 +303,8 @@ module.exports = {
   LEVELS,
   LEVEL_META,
   LEVEL_CONTRACT,
-  ROLE_WANDERING,
-  roleWandering,
+  RANK_WANDERING,
+  rankWandering,
   RANK_DEFAULT,
   RANK_MAX,
   TOP_LEVEL,

package/modules/government/catalog.js

@@ -1,44 +1,44 @@
-// modules/governance/catalog.js — the permission catalog + compatibility seed.
+// modules/government/catalog.js — the permission catalog + compatibility seed.
 //
 // The single CODE source of truth for authority atoms (ADR 0151, BV1.R94). Every
 // permission is a stable string key that maps to a REAL server capability (a route,
 // a claim rule, a page) — a permission no route consumes does not exist. The
-// resolver (R95), the requirePermission gate (R97), R93's role seed, and the Archon
+// resolver (R95), the requirePermission gate (R97), R93's rank seed, and the Archon
 // tab (R110/R111) all read from here; the enumerated catalog it transcribes is
 // docs/adr/0151-governance-permissions-as-atom-ranks-as-roles.md, grounded in
 // docs/governance/authority-sweep-2026-07-24.md.
 //
 // Two orthogonal axes per permission:
-//   • system  — true  = trust-boundary. The governance API (R110) rejects adding it
-//               to a CUSTOM role and the tab renders it LOCKED there; it is deploy/
+//   • system  — true  = trust-boundary. The government API (R110) rejects adding it
+//               to a CUSTOM rank and the tab renders it LOCKED there; it is deploy/
 //               protected-path/rank-set/version-close/grade-bypass/cross-tier/
 //               principal power, enforced by the out-of-band substrate (ADR 0043)
-//               or reserved to Archon. The built-in `archon` rank-role legitimately
+//               or reserved to Archon. The built-in `archon` rank legitimately
 //               HOLDS the archon-floored system perms.
-//             — false = operational, freely composable into a custom role.
+//             — false = operational, freely composable into a custom rank.
 //             `system` is NOT the whole grantability answer any more — see the
-//             `substrate` axis below and `isGrantableTo()`, which is per-ROLE.
+//             `substrate` axis below and `isGrantableTo()`, which is per-RANK.
 //   • substrate — true = this key's authority is enforced OUTSIDE the app, by the
 //               pre-push hook / main-audit / the rank floor the git and ssh layers
 //               read (ADR 0043). A grant row for one is INERT: no route consumes it
 //               through requirePermission, so granting it would be a toggle that
 //               looks like it worked and changes nothing. Therefore non-grantable to
-//               EVERY role, seeded rank-roles included — the one wall ADR 0172's
+//               EVERY rank, seeded ranks included — the one wall ADR 0172's
 //               widening deliberately did not move, because moving it would make the
 //               tab lie rather than delegate. Implies system:true + floor 'archon'.
 //   • floor   — the rank that holds this permission TODAY via the compat seed
 //               ('xenos' < 'thetes' < 'metic' < 'archon'), or null for a machine
-//               PRINCIPAL permission held by NO rank-role (gated on exact
-//               system_role, never a human/role — ADR 0151 §3). floor drives the
+//               PRINCIPAL permission held by NO rank (gated on exact
+//               system_role, never a human/rank — ADR 0151 §3). floor drives the
 //               seed derivation below; it is seed DATA, not grantability (the
 //               `system` flag is the wall). Ownership-scoped + baseline own-work
 //               perms floor at 'xenos' (every authenticated builder holds them).
 //
 // PRINCIPALS — the second authority AXIS (BV1.R98, ADR 0151 §3). A builder's
-// authority is the UNION of their ROLES; a machine principal's authority is its
+// authority is the UNION of their RANKS; a machine principal's authority is its
 // IDENTITY. Those are different axes and the model keeps them apart: a principal
 // permission carries `principal: '<system_role>'` and `floor: null`, so it is in
-// NO rank-role (not even archon's) and no custom role may hold it (`system:true`).
+// NO rank (not even archon's) and no custom rank may hold it (`system:true`).
 // The two are a PARTITION, asserted at load: floor:null ⟺ principal set. The only
 // source of a principal permission is resolver.resolvePrincipalPermissions(), keyed
 // on the exact `builders.system_role` value — a column with no API writer at all
@@ -77,10 +77,10 @@
 // Archon included), and minting a key no route consumes to satisfy a symmetry
 // check would violate this module's first rule.
 //
-// The RANK_ROLE_SEED is DERIVED from floors (cumulative nested supersets), so the
+// The RANK_SEED is DERIVED from floors (cumulative nested supersets), so the
 // "zero day-one behavior change" parity (R103) is structural, not hand-maintained:
-// role(rank) = { p : p.floor !== null and tier(p.floor) <= tier(rank) }, and the
-// resolver's UNION over a builder's one rank-role reproduces requireRank's
+// rank(rank) = { p : p.floor !== null and tier(p.floor) <= tier(rank) }, and the
+// resolver's UNION over a builder's one rank reproduces requireRank's
 // at-or-above threshold exactly.
 
 'use strict';
@@ -96,7 +96,7 @@ const PERMISSIONS = [
   // ── system: true — trust-boundary (substrate- or Archon-enforced) ─────────────
   //
   // The seven WITHOUT `substrate` are in-app Archon powers: a real route reads them
-  // through requirePermission, so granting one to a sub-Archon rank-role genuinely
+  // through requirePermission, so granting one to a sub-Archon rank genuinely
   // delegates it (ADR 0172, the owner's lever). The three WITH `substrate: true` are
   // enforced out of band and can never be delegated by a row in this database.
   { key: 'builder.rank.set', system: true, floor: 'archon', guards: 'PATCH /builders/:id/rank — the single rank writer' },
@@ -112,7 +112,7 @@ const PERMISSIONS = [
   { key: 'principal.bfg', system: true, floor: null, principal: 'bfg', guards: '/memory/bfg/* — requireBfgPrincipal (exact system_role=bfg; NO rank holds it)' },
   { key: 'principal.discord_bot', system: true, floor: null, principal: 'discord_bot', guards: 'Discord bot routes — requireDiscordBot (exact system_role; dormant)' },
 
-  // ── operational — floor archon (admin ops; grantable to a custom role) ────────
+  // ── operational — floor archon (admin ops; grantable to a custom rank) ────────
   //
   // ADR 0157 (owner decision, 2026-08-05) narrowed this block to IDENTITY: the Archon
   // rank is responsible for rank and identity only. Nineteen keys that sat here for
@@ -166,15 +166,15 @@ const PERMISSIONS = [
   // and operations: they spend, read, adjudicate, and shuffle work, but none of them
   // decides WHO HOLDS AUTHORITY, so the trusted working rank carries them. All were
   // floor 'archon' before this ADR; none is system:true, so all were already
-  // delegable to a custom role — this only lowers the seeded floor.
+  // delegable to a custom rank — this only lowers the seeded floor.
   //
   // Deliberately NOT in this block, though the owner's rule would otherwise reach them:
   //   • `version.close` — retained at archon; it is the DISPOSITION that finalises a
   //     version's scope-truth, and canonical-permissions has long paired it with rank
   //     as the two powers that never delegate. ADR 0157 keeps that pairing.
   //   • `dependency.cross_tier.manage` — system:true, and the catalog's own invariant
-  //     (tests/governance_catalog.mjs) forbids granting a system key to metic. Moving
-  //     it would mean clearing the system flag, which widens what any CUSTOM role can
+  //     (tests/government_catalog.mjs) forbids granting a system key to metic. Moving
+  //     it would mean clearing the system flag, which widens what any CUSTOM rank can
   //     be granted — a second-order change beyond the delegation that was asked for.
   { key: 'builder.budget.set', system: false, floor: 'metic', guards: 'PATCH /builders/:id/budget (ADR 0157, was archon)' },
   { key: 'criterion.unsatisfy', system: false, floor: 'metic', guards: 'POST /done-when/:id/unsatisfy (ADR 0157, was archon)' },
@@ -185,7 +185,7 @@ const PERMISSIONS = [
   // siblings are `goal.create` and `task.create`, both operational. Close is the
   // DISPOSITION that finalises a version's scope-truth; create opens it — the symmetry
   // argument was considered and rejected, because system:true would permanently bar
-  // delegating version authoring to a custom role for no trust-boundary reason.
+  // delegating version authoring to a custom rank for no trust-boundary reason.
   // ADR 0157 then lowered create's floor to metic while close stayed archon, which is
   // the same asymmetry read from the other side: authoring delegates, disposition does not.
   { key: 'version.create', system: false, floor: 'metic', guards: 'POST /versions — create a version + its done-when criteria (ADR 0157, was archon)' },
@@ -237,7 +237,7 @@ const PERMISSIONS = [
   // working rank. The gate FUNCTION was renamed to match (`requireArchonPage` →
   // `requireGovernmentPage`) once the floor moved. Viewing is all this grants: every
   // write those pages reach is its own atom, and `government.manage` (the
-  // roles/permissions tab) stayed archon.
+  // ranks/permissions tab) stayed archon.
   { key: 'page.view.government', system: false, floor: 'metic', guards: 'the government/monitoring pages — /watch, /harbor, /gate (requireGovernmentPage; write = government.manage, archon)' },
 ];
 
@@ -249,70 +249,70 @@ const _byKey = new Map();
 const _byPrincipal = new Map();
 const _byResource = new Map();
 for (const p of PERMISSIONS) {
-  if (typeof p.key !== 'string' || !p.key) throw new Error(`governance catalog: permission missing a key`);
-  if (typeof p.system !== 'boolean') throw new Error(`governance catalog: ${p.key} missing boolean 'system'`);
-  if (p.floor !== null && !RANK_ORDER.includes(p.floor)) throw new Error(`governance catalog: ${p.key} has invalid floor "${p.floor}"`);
-  if (_byKey.has(p.key)) throw new Error(`governance catalog: duplicate key "${p.key}"`);
+  if (typeof p.key !== 'string' || !p.key) throw new Error(`government catalog: permission missing a key`);
+  if (typeof p.system !== 'boolean') throw new Error(`government catalog: ${p.key} missing boolean 'system'`);
+  if (p.floor !== null && !RANK_ORDER.includes(p.floor)) throw new Error(`government catalog: ${p.key} has invalid floor "${p.floor}"`);
+  if (_byKey.has(p.key)) throw new Error(`government catalog: duplicate key "${p.key}"`);
   const principal = p.principal ?? null;
   if (principal !== null && (typeof principal !== 'string' || !principal)) {
-    throw new Error(`governance catalog: ${p.key} has a non-string principal identity`);
+    throw new Error(`government catalog: ${p.key} has a non-string principal identity`);
   }
-  // The two axes PARTITION the catalog: a permission is held by a rank-role (a real
+  // The two axes PARTITION the catalog: a permission is held by a rank (a real
   // floor) XOR by a machine identity (floor null + a principal). Neither-nor would be
-  // a permission nothing can ever hold; both-and would let a role reach an identity.
+  // a permission nothing can ever hold; both-and would let a rank reach an identity.
   if ((p.floor === null) !== (principal !== null)) {
-    throw new Error(`governance catalog: ${p.key} — floor:null and a principal identity must come together (roles and identities are separate axes)`);
+    throw new Error(`government catalog: ${p.key} — floor:null and a principal identity must come together (ranks and identities are separate axes)`);
   }
   if (p.key.startsWith(PRINCIPAL_KEY_PREFIX) !== (principal !== null)) {
-    throw new Error(`governance catalog: ${p.key} — a "${PRINCIPAL_KEY_PREFIX}*" key and a principal identity must come together`);
+    throw new Error(`government catalog: ${p.key} — a "${PRINCIPAL_KEY_PREFIX}*" key and a principal identity must come together`);
   }
   if (principal !== null) {
-    if (!p.system) throw new Error(`governance catalog: ${p.key} is a principal permission and must be system:true (never grantable to a role)`);
-    if (_byPrincipal.has(principal)) throw new Error(`governance catalog: duplicate principal identity "${principal}"`);
+    if (!p.system) throw new Error(`government catalog: ${p.key} is a principal permission and must be system:true (never grantable to a rank)`);
+    if (_byPrincipal.has(principal)) throw new Error(`government catalog: duplicate principal identity "${principal}"`);
   }
   // ── the SUBSTRATE axis (ADR 0172) ─────────────────────────────────────────
   // A substrate key is enforced by the out-of-band layer (pre-push hook, main-audit,
-  // the rank floor git/ssh read), so no role row can confer it. Three shape rules,
+  // the rank floor git/ssh read), so no rank row can confer it. Three shape rules,
   // each closing a way the marker could quietly stop meaning that:
   const substrate = p.substrate ?? false;
-  if (typeof substrate !== 'boolean') throw new Error(`governance catalog: ${p.key} has a non-boolean 'substrate'`);
+  if (typeof substrate !== 'boolean') throw new Error(`government catalog: ${p.key} has a non-boolean 'substrate'`);
   if (substrate) {
     // Substrate power is trust-boundary power by definition — a substrate key that
-    // was somehow operational would be freely grantable to a custom role.
-    if (!p.system) throw new Error(`governance catalog: ${p.key} is substrate-enforced and must be system:true`);
+    // was somehow operational would be freely grantable to a custom rank.
+    if (!p.system) throw new Error(`government catalog: ${p.key} is substrate-enforced and must be system:true`);
     // A substrate key belongs to no machine identity: the two are different reasons
     // a key is unreachable, and collapsing them would hide one behind the other.
-    if (principal !== null) throw new Error(`governance catalog: ${p.key} cannot be both substrate-enforced and a machine principal`);
+    if (principal !== null) throw new Error(`government catalog: ${p.key} cannot be both substrate-enforced and a machine principal`);
     // The out-of-band enforcers all compare against the top of the ladder. A lower
-    // floor would seed the key into a rank-role that the substrate then still denies.
-    if (p.floor !== 'archon') throw new Error(`governance catalog: ${p.key} is substrate-enforced and must floor at 'archon' (the substrate compares against the top of the ladder)`);
+    // floor would seed the key into a rank that the substrate then still denies.
+    if (p.floor !== 'archon') throw new Error(`government catalog: ${p.key} is substrate-enforced and must floor at 'archon' (the substrate compares against the top of the ladder)`);
   }
   // ── the OWNERSHIP axis (R100) ─────────────────────────────────────────────
   const scope = p.scope ?? null;
   const resource = p.resource ?? null;
   if (scope !== null && !OWNERSHIP_SCOPES.includes(scope)) {
-    throw new Error(`governance catalog: ${p.key} has invalid scope "${scope}" (expected 'own', 'any', or absent)`);
+    throw new Error(`government catalog: ${p.key} has invalid scope "${scope}" (expected 'own', 'any', or absent)`);
   }
   // An ownership SCOPE and the RESOURCE it is scoped over are one fact spelled in
   // two fields; either alone is meaningless ('own' of what? / a resource nothing
   // is scoped over). Same partition posture as floor ⟺ principal above.
   if ((scope === null) !== (resource === null)) {
-    throw new Error(`governance catalog: ${p.key} — scope and resource must come together (an ownership scope is always scoped over a named resource)`);
+    throw new Error(`government catalog: ${p.key} — scope and resource must come together (an ownership scope is always scoped over a named resource)`);
   }
   if (resource !== null && (typeof resource !== 'string' || !resource)) {
-    throw new Error(`governance catalog: ${p.key} has a non-string resource family`);
+    throw new Error(`government catalog: ${p.key} has a non-string resource family`);
   }
   // The namespace can never outrun the data: a key that CALLS itself own-scoped
   // must BE declared own-scoped, or a gate reading the declared axis would treat a
   // parameterized permission as an unconditional grant. Deliberately one-way — the
   // converse would be false (me.wandering.set is own-scoped without the suffix).
   if (p.key.endsWith(OWN_KEY_SUFFIX) && scope !== 'own') {
-    throw new Error(`governance catalog: ${p.key} ends in "${OWN_KEY_SUFFIX}" but does not declare scope:'own' — an ownership-scoped key must say so in data`);
+    throw new Error(`government catalog: ${p.key} ends in "${OWN_KEY_SUFFIX}" but does not declare scope:'own' — an ownership-scoped key must say so in data`);
   }
-  // An ownership scope NARROWS a role-held permission; a machine identity has no
+  // An ownership scope NARROWS a rank-held permission; a machine identity has no
   // owner axis, so the two never compose.
   if (scope !== null && p.floor === null) {
-    throw new Error(`governance catalog: ${p.key} is ownership-scoped but has no rank floor — the ownership axis narrows a ROLE permission, never an identity one`);
+    throw new Error(`government catalog: ${p.key} is ownership-scoped but has no rank floor — the ownership axis narrows a RANK permission, never an identity one`);
   }
   const frozen = Object.freeze({ ...p, principal, scope, resource, substrate });
   _byKey.set(p.key, frozen);
@@ -332,15 +332,15 @@ Object.freeze(PERMISSIONS);
 const floorTier = (rank) => RANK_ORDER.indexOf(rank);
 for (const [resource, fam] of _byResource) {
   if (fam.any.length > 0 && fam.own.length === 0) {
-    throw new Error(`governance catalog: resource "${resource}" declares a cross-owner permission (${fam.any.join(', ')}) with no ownership-scoped counterpart`);
+    throw new Error(`government catalog: resource "${resource}" declares a cross-owner permission (${fam.any.join(', ')}) with no ownership-scoped counterpart`);
   }
   // Reaching EVERY owner's row must never be cheaper than reaching your own. If it
   // were, a rank could manage the whole fleet but not its own box — the model
-  // inverted, and the governance tab would render the wider grant as the safer one.
+  // inverted, and the Government tab would render the wider grant as the safer one.
   for (const anyKey of fam.any) {
     for (const ownKey of fam.own) {
       if (floorTier(_byKey.get(anyKey).floor) < floorTier(_byKey.get(ownKey).floor)) {
-        throw new Error(`governance catalog: ${anyKey} (floor ${_byKey.get(anyKey).floor}) sits BELOW ${ownKey} (floor ${_byKey.get(ownKey).floor}) — cross-owner authority must never be cheaper than own-only`);
+        throw new Error(`government catalog: ${anyKey} (floor ${_byKey.get(anyKey).floor}) sits BELOW ${ownKey} (floor ${_byKey.get(ownKey).floor}) — cross-owner authority must never be cheaper than own-only`);
       }
     }
   }
@@ -382,9 +382,9 @@ function isSystem(key) {
   const p = _byKey.get(key);
   return p ? p.system : null; // null = unknown key (caller fails closed)
 }
-// Grantable to a CUSTOM role = exists and not system. Unknown key → false (fail-closed).
-// This is the NARROW question — the custom-role wall, unchanged by ADR 0172 and
-// still what config.js strips against. For the per-role answer use isGrantableTo().
+// Grantable to a CUSTOM rank = exists and not system. Unknown key → false (fail-closed).
+// This is the NARROW question — the custom-rank wall, unchanged by ADR 0172 and
+// still what config.js strips against. For the per-rank answer use isGrantableTo().
 function isGrantable(key) {
   const p = _byKey.get(key);
   return !!p && !p.system;
@@ -406,40 +406,40 @@ function substrateKeys() {
   return PERMISSIONS.filter((p) => p.substrate).map((p) => p.key);
 }
 
-// ── grantability, per ROLE (ADR 0172) ──────────────────────────────────────────
+// ── grantability, per RANK (ADR 0172) ──────────────────────────────────────────
 //
-// The owner's 2026-08-16 decision made the three sub-Archon RANK roles editable, so
-// "is this grantable" stopped being a property of the key alone. `role` is a
+// The owner's 2026-08-16 decision made the three sub-Archon RANK ranks editable, so
+// "is this grantable" stopped being a property of the key alone. `rank` is a
 // government_ranks row ({ is_system, seeded_rank }); the four answers:
 //
-//   • NEVER, to any role — a machine-principal key (held by an identity, not a role)
+//   • NEVER, to any rank — a machine-principal key (held by an identity, not a rank)
 //     and a SUBSTRATE key. The substrate three are inert as grant rows: no route
 //     consumes them through requirePermission, so a toggle for one would report
 //     success and delegate nothing. Refusing them keeps the tab honest.
-//   • the ARCHON rank-role — nothing. It is immutable and already holds everything,
-//     and that immutability is also the LOCKOUT GUARD: the only role carrying
+//   • the ARCHON rank — nothing. It is immutable and already holds everything,
+//     and that immutability is also the LOCKOUT GUARD: the only rank carrying
 //     `government.manage` by seed can never have it revoked, so no sequence of
 //     clicks in this tab can lock the owner out of the tab.
-//   • a SEEDED rank-role BELOW archon — everything else, the seven in-app Archon
+//   • a SEEDED rank BELOW archon — everything else, the seven in-app Archon
 //     powers included. This is the delegation lever the owner asked for.
-//   • a CUSTOM role — operational only: the pre-existing R110 wall, deliberately NOT
-//     widened. A rank-role is the owner's own coarse ladder, moved by a rank write;
-//     a custom role is ad-hoc and assignable by anyone holding `government.manage`,
+//   • a CUSTOM rank — operational only: the pre-existing R110 wall, deliberately NOT
+//     widened. A rank is the owner's own coarse ladder, moved by a rank write;
+//     a custom rank is ad-hoc and assignable by anyone holding `government.manage`,
 //     so widening it would hand the second group the first group's lever.
 //
-// Fail-closed on everything unrecognised: unknown key, missing role, or a system role
+// Fail-closed on everything unrecognised: unknown key, missing rank, or a system rank
 // whose seeded_rank is not a real rank all answer false.
-function isGrantableTo(key, role) {
+function isGrantableTo(key, rank) {
   const p = _byKey.get(key);
-  if (!p || !role || typeof role !== 'object') return false;
+  if (!p || !rank || typeof rank !== 'object') return false;
   if (p.principal !== null || p.substrate) return false;
-  if (role.is_system) {
-    return RANK_ORDER.includes(role.seeded_rank) && role.seeded_rank !== 'archon';
+  if (rank.is_system) {
+    return RANK_ORDER.includes(rank.seeded_rank) && rank.seeded_rank !== 'archon';
   }
   return !p.system;
 }
 
-// ── the principal axis (identity, not roles) ────────────────────────────────────
+// ── the principal axis (identity, not ranks) ────────────────────────────────────
 // Reads only. Unknown/blank input fails closed to null/false — the same posture the
 // rest of the catalog takes, and the one the identity gates depend on.
 function principals() {
@@ -451,7 +451,7 @@ function principalRoles() {
 function principalKeys() {
   return PRINCIPALS.map((p) => p.permission);
 }
-// Is this key held by a machine identity rather than by any role? Unknown → false.
+// Is this key held by a machine identity rather than by any rank? Unknown → false.
 function isPrincipalKey(key) {
   const p = _byKey.get(key);
   return !!p && p.principal !== null;
@@ -503,17 +503,17 @@ function crossOwnerKeysFor(key) {
   return fam ? fam.any : NO_KEYS;
 }
 
-// The compat seed, DERIVED from floors (cumulative supersets). A rank-role holds
+// The compat seed, DERIVED from floors (cumulative supersets). A rank holds
 // every permission whose floor is a real rank at-or-below it; principals (floor
-// null) are held by NO rank-role. This is the "zero day-one change" guarantee —
-// role(rank) reproduces requireRank(rank)'s at-or-above threshold exactly (R103).
+// null) are held by NO rank. This is the "zero day-one change" guarantee —
+// rank(rank) reproduces requireRank(rank)'s at-or-above threshold exactly (R103).
 function seedForRank(rank) {
   const tier = RANK_ORDER.indexOf(rank);
-  if (tier < 0) return []; // unknown/reserved rank → no role → no permissions (fail-closed; ADR 0151)
+  if (tier < 0) return []; // unknown/reserved rank → no rank → no permissions (fail-closed; ADR 0151)
   return PERMISSIONS.filter((p) => p.floor !== null && RANK_ORDER.indexOf(p.floor) <= tier).map((p) => p.key);
 }
 
-const RANK_ROLE_SEED = Object.freeze(
+const RANK_SEED = Object.freeze(
   Object.fromEntries(RANK_ORDER.map((r) => [r, Object.freeze(seedForRank(r))])),
 );
 
@@ -530,7 +530,7 @@ module.exports = {
   systemKeys,
   grantableKeys,
   seedForRank,
-  RANK_ROLE_SEED,
+  RANK_SEED,
   PRINCIPALS,
   principals,
   principalRoles,