@bongos/core 1.18.0 → 1.18.18

package/modules/governance/catalog.js

@@ -0,0 +1,419 @@
+// modules/governance/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
+// 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, NON-GRANTABLE. The governance API (R110)
+//               rejects adding it to a CUSTOM role and the tab renders it LOCKED;
+//               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 HOLDS the archon-floored system perms — "non-grantable"
+//               constrains custom roles, not the seed.
+//             — false = operational, freely composable into a custom role.
+//   • 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
+//               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
+// 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`).
+// 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
+// (provisioned out-of-band by migration 065/067, constrained by the DB CHECK
+// allowlist + a UNIQUE index). Nothing in this module can create, grant, or assign
+// one; the Archon tab reads `PRINCIPALS` to SHOW them and has no counterpart write.
+//
+// OWNERSHIP SCOPE — the third AXIS (BV1.R100, ADR 0151 §3). "May act on OWN X" is a
+// PARAMETERIZED permission, not a global grant: box.manage.own ≠ the cross-owner
+// box authority. Two optional fields make that axis explicit DATA (the way
+// `principal` made the identity axis data) rather than something inferred from a
+// key's spelling:
+//   • scope    — 'own'  = ownership-scoped. Holding it authorizes acting ONLY on a
+//                         resource the holder owns. The permission alone is NEVER
+//                         sufficient: a second, REQUEST-scoped fact (does this
+//                         concrete row belong to the caller?) must also hold, and
+//                         the resolver cannot know it — only the handler that
+//                         loaded the row does. resolver.authorizeOwned() is the one
+//                         entry point that answers an 'own' key, and it demands the
+//                         owner alongside the key.
+//                'any' = the CROSS-OWNER counterpart over the same resource: it
+//                         reaches every owner's row, so no predicate applies.
+//                null  = not ownership-scoped (the resource has no owner axis).
+//   • resource — WHAT is owned ('claim', 'box', 'memory', …). It is what LINKS an
+//                'own' key to its 'any' counterpart, which a name cannot: the
+//                cross-owner box authority is spelled `box.fleet.manage`, while
+//                `task.claim.any` ends in `.any` and means "any task in the pool",
+//                not "any owner's resource". Inferring the axis from the suffix
+//                would get both of those wrong — hence data.
+// Asserted at load: scope ⟺ resource; a `.own`-suffixed key MUST declare scope
+// 'own' (a namespace can never outrun the data); a scoped key needs a real rank
+// floor; every 'any' needs an 'own' in its family; and no family's cross-owner
+// floor sits BELOW its own-only floor (wider authority is never cheaper). The
+// converse of that last pairing rule is deliberately NOT asserted — some resources
+// have no cross-owner form by design (nobody manages another builder's credential,
+// 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
+// "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
+// at-or-above threshold exactly.
+
+'use strict';
+
+// Low→high; index is the tier. Mirrors LIVE_RANK_LADDER (db-kernel.js) — the ONE
+// ladder the resolver will collapse the ~13 duplicated tier maps onto (R108).
+const RANK_ORDER = Object.freeze(['xenos', 'thetes', 'metic', 'archon']);
+
+// key → capability. `guards` is a human note of the route(s)/surface the key maps to
+// (the exhaustive 1:1 list lives in the authority sweep). Order: system first, then
+// operational by floor (archon → metic → thetes/own/any), matching the ADR appendix.
+const PERMISSIONS = [
+  // ── system: true — non-grantable (substrate- or Archon-enforced) ──────────────
+  { key: 'builder.rank.set', system: true, floor: 'archon', guards: 'PATCH /builders/:id/rank — the single rank writer' },
+  { key: 'version.close', system: true, floor: 'archon', guards: 'version close disposition (never delegated below Archon)' },
+  { key: 'task.confirm.grade_bypass', system: true, floor: 'archon', guards: 'POST /tasks/:id/confirm — ratify past a failed grade (env-relaxable, ADR 0041)' },
+  { key: 'dependency.cross_tier.manage', system: true, floor: 'archon', guards: 'POST|DELETE /dependencies — cross-tier structural edges (ADR 0086)' },
+  { key: 'goal.scope.manage', system: true, floor: 'archon', guards: 'cross-tier goal-scope edges + protected-scope admission (ADR 0086)' },
+  { key: 'governance.manage', system: true, floor: 'archon', guards: 'the governance tab write routes (roles/perms/assignments) — meta-escalation' },
+  { key: 'gate_approval.decide', system: true, floor: 'archon', guards: 'POST /gate-approvals/:pr/approve — CI deploy-gate override' },
+  { key: 'deploy.push_main', system: true, floor: 'archon', guards: 'git push origin main / the deploy — substrate-enforced (pre-push, main-audit)' },
+  { key: 'path.protected.modify', system: true, floor: 'archon', guards: 'modifying a PROTECTED_GLOBS path below the Metic floor — substrate (ADR 0043)' },
+  { key: 'infra.ssh', system: true, floor: 'archon', guards: 'ssh to the droplet / operator surface — substrate (credential placement)' },
+  { key: 'principal.bfg', system: true, floor: null, principal: 'bfg', guards: '/memory/bfg/* — requireBfgPrincipal (exact system_role=bfg; NO rank-role 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) ────────
+  { key: 'builder.status.set', system: false, floor: 'archon', guards: 'PATCH /builders/:id/status — offboard / (de)activate' },
+  { key: 'builder.budget.set', system: false, floor: 'archon', guards: 'PATCH /builders/:id/budget' },
+  { key: 'criterion.unsatisfy', system: false, floor: 'archon', guards: 'POST /done-when/:id/unsatisfy' },
+  { key: 'auth.session.revoke', system: false, floor: 'archon', guards: 'POST /auth/revoke, /auth/revoke-all' },
+  { key: 'access_request.review', system: false, floor: 'archon', guards: 'GET/PATCH /access-requests/:id — admit a builder' },
+  { key: 'security.report.adjudicate', system: false, floor: 'archon', guards: 'POST /security/reports/:id/{confirm,dispute,fix,link-fix}, /security/docs CRUD' },
+  { key: 'provisioning.fleet.manage', system: false, floor: 'archon', guards: 'GET /provisioning/fleet[/cost-ledger], POST .../force-teardown' },
+  { key: 'box.fleet.manage', system: false, floor: 'archon', scope: 'any', resource: 'box', guards: 'GET /boxes[/cost-ledger], POST /boxes/:b/close, PATCH .../block' },
+  { key: 'autonomy.precheck', system: false, floor: 'archon', guards: 'GET /autonomy/precheck — unsupervised-runner gate' },
+  { key: 'discord.channels.manage', system: false, floor: 'archon', guards: 'GET /discord/channels/plan, POST .../reconcile' },
+  { key: 'project.curate', system: false, floor: 'archon', guards: 'platform-identity: POST /projects, /projects/invite, PATCH /projects/:id/featured, GET /scouting' },
+  { key: 'override_request.decide', system: false, floor: 'archon', guards: 'GET /override-requests, POST .../:id/decide' },
+  { key: 'claim.release.any', system: false, floor: 'archon', scope: 'any', resource: 'claim', guards: 'POST /claims/:id/release-on-behalf' },
+  { key: 'idea.ratify', system: false, floor: 'archon', guards: 'POST /inbox/:id/ratify' },
+  { key: 'task.newcomer_restock', system: false, floor: 'archon', guards: 'POST /tasks/newcomer-restock' },
+  { key: 'task.peer_votes.tally', system: false, floor: 'archon', guards: 'POST /tasks/peer-votes/tally' },
+  { key: 'goal.reorder', system: false, floor: 'archon', guards: 'POST /goals/reorder' },
+  { key: 'builder.roster.read', system: false, floor: 'archon', guards: 'GET /builders/roster, /grades/by-builder, /builders/:id/active-claims' },
+  { key: 'session.search', system: false, floor: 'archon', guards: 'GET /sessions/search' },
+  { key: 'memory.read.any', system: false, floor: 'archon', scope: 'any', resource: 'memory', guards: 'GET /memory/builders/:id/file[s] — cross-builder memory read' },
+  { key: 'audit_log.read', system: false, floor: 'archon', guards: 'GET /audit-log' },
+
+  // ── operational — floor metic (the working rank's review/triage/authoring) ────
+  { key: 'idea.triage', system: false, floor: 'metic', guards: 'PATCH /inbox/:id' },
+  { key: 'blocker.review', system: false, floor: 'metic', guards: 'POST /blockers/:id/{resolve,link}' },
+  { key: 'task.create', system: false, floor: 'metic', guards: 'POST /tasks (incl. newcomer_friendly) — ADR 0090' },
+  { key: 'task.edit', system: false, floor: 'metic', guards: 'PATCH /tasks/:id' },
+  { key: 'task.promote', system: false, floor: 'metic', guards: 'POST /tasks/:id/promote' },
+  { key: 'task.demote', system: false, floor: 'metic', guards: 'POST /tasks/:id/demote' },
+  { key: 'task.abandon', system: false, floor: 'metic', guards: 'POST /tasks/:id/abandon — scope removal; undo = POST /tasks/:id/promote (ADR 0152, was archon)' },
+  { key: 'task.vote', system: false, floor: 'metic', guards: 'POST /tasks/:id/vote' },
+  { key: 'task.dependency.manage', system: false, floor: 'metic', guards: 'POST|PUT|DELETE /tasks/:id/dependencies (same-tier)' },
+  { key: 'task.criterion.manage', system: false, floor: 'metic', guards: 'POST|DELETE /tasks/:id/criteria' },
+  { key: 'criterion.satisfy', system: false, floor: 'metic', guards: 'POST /done-when/:id/satisfy' },
+  { key: 'criterion.review', system: false, floor: 'metic', guards: 'GET /done-when/pending-review' },
+  // ADR 0154. Split out of criterion.review, where the route sat while it was still
+  // Archon-only (a slip against the sweep — ADR 0154 §5). floor 'metic' is real but
+  // NOT the whole gate: a non-Archon must also name a goal_id they own or manage, in
+  // an open goal on a planning/building version (authorizeCriterionCreate, in-handler).
+  { key: 'criterion.create', system: false, floor: 'metic', guards: 'POST /versions/:id/done-when (goal owner|manager)' },
+  { key: 'planning.run', system: false, floor: 'metic', guards: 'planning-session surface' },
+  { key: 'priority.run', system: false, floor: 'metic', guards: 'priority-session surface' },
+  { key: 'goal.create', system: false, floor: 'metic', guards: 'POST /goals (protected scope → Archon in-handler; ADR 0086)' },
+  { key: 'goal.archive', system: false, floor: 'metic', guards: 'POST /goals/:id/{archive,reopen}' },
+  { key: 'goal.scope.widen', system: false, floor: 'metic', guards: 'POST /goals/:id/scope (same-tier; cross-tier = goal.scope.manage, system)' },
+  { key: 'module.enable', system: false, floor: 'metic', guards: 'POST /modules/:key/enable' },
+  { key: 'module.submit', system: false, floor: 'metic', guards: 'POST /modules/:key/submit, GET /modules/submissions' },
+  { key: 'security.report.file', system: false, floor: 'metic', guards: 'POST /security/reports, GET /security/adr' },
+  { key: 'llm_cache.use', system: false, floor: 'metic', guards: 'POST /llm-cache/{lookup,store}' },
+  { key: 'backup.manage', system: false, floor: 'metic', guards: 'GET /backup/status, POST /backup/trigger' },
+  { key: 'source.clone.local', system: false, floor: 'metic', guards: 'Metic+ local clone / collaborator invite (ADR 0035)' },
+  { key: 'box.source.full', system: false, floor: 'metic', guards: 'GET /box/source-access → full (vs starter); boxScopeForRank' },
+
+  // ── ownership-scoped + baseline own-work (floor thetes / xenos) ───────────────
+  { key: 'task.claim.any', system: false, floor: 'thetes', guards: 'claim the general queue (per-task requires_rank floor still applies)' },
+  { key: 'page.view.builder', system: false, floor: 'thetes', guards: 'authenticated hall pages (requireNonXenosPage / requireBuilderPage)' },
+  { key: 'goal.manage.own', system: false, floor: 'metic', scope: 'own', resource: 'goal', guards: 'PATCH /goals/:id/members/:b, POST /goals/:id/transfer — owner/manager, in-handler (ADR 0106)' },
+  { key: 'task.claim.newcomer', system: false, floor: 'xenos', guards: 'claim a newcomer_friendly task (xenosClaimAllowed; xenos = one active claim)' },
+  { key: 'task.ship', system: false, floor: 'xenos', guards: '/builder-ship own claim' },
+  { key: 'task.act.own', system: false, floor: 'xenos', scope: 'own', resource: 'claim', guards: 'act on OWN active claim (release, cost, notes) — ownership-scoped' },
+  { key: 'box.manage.own', system: false, floor: 'xenos', scope: 'own', resource: 'box', guards: 'own dev-box lifecycle — ownership-scoped' },
+  { key: 'memory.manage.own', system: false, floor: 'xenos', scope: 'own', resource: 'memory', guards: 'own builder memory — ownership-scoped' },
+  // No cross-owner counterpart, deliberately: nobody manages another builder's
+  // credential, Archon included. A `credential.manage.any` would be a key no route
+  // consumes — the catalog's first rule forbids minting one for symmetry.
+  { key: 'credential.manage.own', system: false, floor: 'xenos', scope: 'own', resource: 'credential', guards: 'own API key / credential — ownership-scoped' },
+  // Own-scoped WITHOUT a `.own` suffix — the `me.` namespace is the ownership
+  // marker here. Exactly why scope is declared data: the suffix rule only runs the
+  // safe direction ('.own' ⇒ scope 'own'), never the converse.
+  { key: 'me.wandering.set', system: false, floor: 'xenos', scope: 'own', resource: 'builder_prefs', guards: 'PATCH /me/wandering (clamped by maxLevelForRank) — ownership-scoped' },
+  { key: 'cost.log', system: false, floor: 'xenos', guards: 'POST /costs' },
+  { key: 'learning.create', system: false, floor: 'xenos', guards: 'POST /learnings' },
+  { key: 'blocker.file', system: false, floor: 'xenos', guards: 'POST /blockers' },
+  { key: 'idea.file', system: false, floor: 'xenos', guards: 'POST /inbox (own idea capture)' },
+  { key: 'page.view.public', system: false, floor: 'xenos', guards: 'public read surfaces (incl. xenos)' },
+  { key: 'page.view.governance', system: false, floor: 'archon', guards: 'the Archon governance page (requireArchonPage; write = governance.manage)' },
+];
+
+// ── invariants asserted at module load (fail loud on an authoring typo) ─────────
+const PRINCIPAL_KEY_PREFIX = 'principal.';
+const OWN_KEY_SUFFIX = '.own';
+const OWNERSHIP_SCOPES = Object.freeze(['own', 'any']);
+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}"`);
+  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`);
+  }
+  // The two axes PARTITION the catalog: a permission is held by a rank-role (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.
+  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)`);
+  }
+  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`);
+  }
+  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}"`);
+  }
+  // ── 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)`);
+  }
+  // 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)`);
+  }
+  if (resource !== null && (typeof resource !== 'string' || !resource)) {
+    throw new Error(`governance 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`);
+  }
+  // An ownership scope NARROWS a role-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`);
+  }
+  const frozen = Object.freeze({ ...p, principal, scope, resource });
+  _byKey.set(p.key, frozen);
+  if (principal !== null) _byPrincipal.set(principal, frozen);
+  if (resource !== null) {
+    if (!_byResource.has(resource)) _byResource.set(resource, { own: [], any: [] });
+    _byResource.get(resource)[scope].push(p.key);
+  }
+}
+Object.freeze(PERMISSIONS);
+
+// ── the ownership axis's cross-row invariants ──────────────────────────────────
+// A 'any' row is BY DEFINITION the cross-owner counterpart of an 'own' one, so a
+// family with no 'own' side is a mis-declaration. The converse is NOT required:
+// some resources have no cross-owner form at all (credential), and minting a key
+// no route consumes purely for symmetry would break this module's first rule.
+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`);
+  }
+  // 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.
+  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`);
+      }
+    }
+  }
+}
+
+// resource → { own: [keys], any: [keys] }. The pairing data a gate, a test, or the
+// Archon tab reads to relate "act on own X" to "act on any X"; DERIVED from the
+// rows above so it cannot drift from them.
+const RESOURCE_FAMILIES = Object.freeze(Object.fromEntries(
+  [..._byResource.entries()].map(([resource, fam]) => [resource, Object.freeze({
+    own: Object.freeze([...fam.own]),
+    any: Object.freeze([...fam.any]),
+  })]),
+));
+
+// The principal registry — the read-only projection the Archon tab renders (R110/
+// R111) and the resolver's identity axis reads. Derived from the catalog so it
+// cannot drift, and deliberately WITHOUT a counterpart writer: a principal is
+// provisioned out-of-band in `builders.system_role` (migration-only, DB CHECK
+// allowlist), so `grantable: false` here is a statement of fact, not a policy flag.
+const PRINCIPALS = Object.freeze(
+  [..._byPrincipal.values()].map((p) => Object.freeze({
+    system_role: p.principal,
+    permission: p.key,
+    guards: p.guards,
+    grantable: false,
+    provisioned: 'out-of-band: builders.system_role (no API writes it)',
+  })),
+);
+const _principalByRole = new Map(PRINCIPALS.map((p) => [p.system_role, p]));
+
+function permissionKeys() {
+  return PERMISSIONS.map((p) => p.key);
+}
+function byKey(key) {
+  return _byKey.get(key) || null;
+}
+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).
+function isGrantable(key) {
+  const p = _byKey.get(key);
+  return !!p && !p.system;
+}
+function systemKeys() {
+  return PERMISSIONS.filter((p) => p.system).map((p) => p.key);
+}
+function grantableKeys() {
+  return PERMISSIONS.filter((p) => !p.system).map((p) => p.key);
+}
+
+// ── the principal axis (identity, not roles) ────────────────────────────────────
+// 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() {
+  return PRINCIPALS;
+}
+function principalRoles() {
+  return PRINCIPALS.map((p) => p.system_role);
+}
+function principalKeys() {
+  return PRINCIPALS.map((p) => p.permission);
+}
+// Is this key held by a machine identity rather than by any role? Unknown → false.
+function isPrincipalKey(key) {
+  const p = _byKey.get(key);
+  return !!p && p.principal !== null;
+}
+// EXACT match on the system_role string — never a prefix, case-fold, or coercion.
+// That exactness is the security property: it is what makes an Archon token (whose
+// system_role is NULL) unable to resolve a principal permission.
+function principalByRole(systemRole) {
+  if (typeof systemRole !== 'string' || !systemRole) return null;
+  return _principalByRole.get(systemRole) || null;
+}
+
+// ── the ownership axis (scope, not identity) ───────────────────────────────────
+// Reads only, and fail-closed on an unknown key in the direction that matters:
+// isOwnershipScoped() answers FALSE for a key it does not know, but the resolver
+// never reaches a gate decision off that alone — resolver.authorizeOwned() looks
+// the row up itself and denies an unknown key outright.
+function scopeOf(key) {
+  const p = _byKey.get(key);
+  return p ? p.scope : null;
+}
+function resourceOf(key) {
+  const p = _byKey.get(key);
+  return p ? p.resource : null;
+}
+// Does holding this key require an ownership predicate against the concrete row?
+// This is the question a gate must ask BEFORE treating a held permission as an
+// admit — an ownership-scoped key is never sufficient on its own.
+function isOwnershipScoped(key) {
+  return scopeOf(key) === 'own';
+}
+// The cross-owner counterpart: reaches every owner's row, so no predicate applies.
+function isCrossOwner(key) {
+  return scopeOf(key) === 'any';
+}
+function ownershipScopedKeys() {
+  return PERMISSIONS.filter((p) => p.scope === 'own').map((p) => p.key);
+}
+function crossOwnerKeys() {
+  return PERMISSIONS.filter((p) => p.scope === 'any').map((p) => p.key);
+}
+// The cross-owner keys over the SAME resource as `key` — what a route offers as
+// the escalation path ("your own claim, or claim.release.any"). Empty when the
+// resource has no cross-owner form by design.
+const NO_KEYS = Object.freeze([]);
+function crossOwnerKeysFor(key) {
+  const resource = resourceOf(key);
+  const fam = resource === null ? null : RESOURCE_FAMILIES[resource];
+  return fam ? fam.any : NO_KEYS;
+}
+
+// The compat seed, DERIVED from floors (cumulative supersets). A rank-role 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).
+function seedForRank(rank) {
+  const tier = RANK_ORDER.indexOf(rank);
+  if (tier < 0) return []; // unknown/reserved rank → no role → 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(
+  Object.fromEntries(RANK_ORDER.map((r) => [r, Object.freeze(seedForRank(r))])),
+);
+
+module.exports = {
+  RANK_ORDER,
+  PERMISSIONS,
+  permissionKeys,
+  byKey,
+  isSystem,
+  isGrantable,
+  systemKeys,
+  grantableKeys,
+  seedForRank,
+  RANK_ROLE_SEED,
+  PRINCIPALS,
+  principals,
+  principalRoles,
+  principalKeys,
+  isPrincipalKey,
+  principalByRole,
+  RESOURCE_FAMILIES,
+  scopeOf,
+  resourceOf,
+  isOwnershipScoped,
+  isCrossOwner,
+  ownershipScopedKeys,
+  crossOwnerKeys,
+  crossOwnerKeysFor,
+};

package/modules/governance/config.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// modules/governance/config.js — the governance config contract (ADR 0151, BV1.R96).
+//
+// Role 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/governance.json)  ->  neutral
+//   starter (config/governance.neutral.json)
+//
+// A fresh instance with NO config resolves to the PLAIN neutral role 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.
+//   • DB     — LIVE STATE: governance_roles / governance_role_permissions /
+//     governance_builder_roles (R93). WHO HOLDS WHAT is a row, resolved server-side
+//     per request by resolver.js. Nothing in this file grants anything to anybody.
+//
+// Three fail-closed rules, in the same spirit as resolver.js's drop-unknown-key rule:
+//   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
+//      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.
+//      Their grants are DERIVED from catalog floors and materialised by
+//      governance_002; config may relabel a seeded role, 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
+// 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)
+// asserts against the neutral starter. Wiring a speculative caller now would guess at
+// their needs; the tests pin the contract until they land.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const api = require('../../src/module-api');
+const catalog = require('./catalog');
+
+// Both the neutral starter and the instance pack sit at the repo root's config/
+// today (src/instance-config.js resolveCoreRoot() === resolveInstanceRoot() === this
+// checkout), so this is the established module idiom for a repo-root read
+// (modules/lifecycle, modules/onboarding, modules/discord). When ADR 0108's root
+// split lands, the INSTANCE path routes through resolveInstanceRoot() — the module
+// doorway does not re-export the root resolvers yet.
+const ROOT = path.resolve(__dirname, '..', '..');
+const NEUTRAL_PATH = path.join(ROOT, 'config', 'governance.neutral.json');
+const INSTANCE_PATH = path.join(ROOT, 'config', 'governance.json');
+
+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
+// 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) {
+  const out = {};
+  const keys = new Set([...Object.keys(neutral || {}), ...Object.keys(instance || {})]);
+  for (const key of keys) {
+    const n = isObj((neutral || {})[key]) ? neutral[key] : {};
+    const i = isObj((instance || {})[key]) ? instance[key] : {};
+    out[key] = { ...n, ...i };
+  }
+  return out;
+}
+
+// The env layer overrides LABELS ONLY, deliberately: an env var must never be able to
+// 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 };
+  for (const pair of String(raw).split(',')) {
+    const eq = pair.indexOf('=');
+    if (eq <= 0) continue;
+    const key = pair.slice(0, eq).trim();
+    const label = pair.slice(eq + 1).trim();
+    if (!label || !isObj(out[key])) continue;
+    out[key] = { ...out[key], label };
+  }
+  return out;
+}
+
+// Filter a template's proposed permissions against the code catalog. isGrantable() is
+// false for BOTH an unknown key and a `system: true` key, so rules 1 and 2 above are
+// one call — and they can never drift from the catalog. Returns a frozen sorted array.
+function grantableOnly(keys) {
+  const seen = new Set();
+  for (const k of Array.isArray(keys) ? keys : []) {
+    if (typeof k === 'string' && catalog.isGrantable(k)) seen.add(k);
+  }
+  return Object.freeze([...seen].sort());
+}
+
+function sanitizeRole(key, raw) {
+  const seeded = SEEDED_RANK_ROLES.has(key);
+  return Object.freeze({
+    key,
+    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.
+    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 = {};
+  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]);
+  }
+  // The four rank-roles 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.
+  for (const key of catalog.RANK_ORDER) {
+    if (!roles[key]) roles[key] = sanitizeRole(key, {});
+  }
+  return Object.freeze({ roles: Object.freeze(roles) });
+}
+
+// READ, never require(): a bare require('../../config/X.json') of a boundary-excluded
+// config crashes a vanilla boot with MODULE_NOT_FOUND (fitness Check 16 / task 1824).
+function readJson(p) {
+  try { return JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+}
+
+// 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
+// it. Unlike branding — where a missing identity is fatal — no value here is required,
+// so the loader fails to sane defaults rather than throwing.
+//
+// CALL THIS AT BOOT, NOT PER REQUEST. The two reads are synchronous, which is correct
+// for a startup read of a committed file and wrong inside a request handler. If a
+// 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({
+    neutral: readJson(neutralPath) || {},
+    instance: readJson(instancePath) || {},
+    env,
+  });
+}
+
+module.exports = {
+  resolveGovernanceConfig,
+  loadGovernanceConfig,
+  grantableOnly,
+  NEUTRAL_PATH,
+  INSTANCE_PATH,
+};