@bongos/core 1.18.0 → 1.18.18

package/modules/governance/rank-roles.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// modules/governance/rank-roles.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:
+// given a builder's CURRENT assignments and a rank, which seeded role to ADD and
+// which to REMOVE.
+//
+// THE REMOVAL IS THE SECURITY HALF. An additive-only sync would leave a demoted
+// Archon still holding the `archon` role, so resolveBuilderPermissions() would keep
+// returning Archon permissions. That is the exact privilege retention ADR 0016's
+// "a demotion takes effect on the builder's very next request" promise forbids: the
+// resolver is correctly per-request and uncached, but it reads an ASSIGNMENT, and a
+// stale assignment breaks the freshness guarantee one layer beneath the resolver.
+//
+// CUSTOM ROLES ARE NEVER TOUCHED. An Archon-assigned role (is_system=false, the
+// R110 tab's output) must survive a rank change — only rows that are BOTH
+// is_system AND carry a seeded_rank rotate. Keying the removal on "every role this
+// builder holds" would silently revoke delegated authority on every promotion.
+//
+// A rank with NO seeded role — one of the twelve reserved ranks migration 023's
+// CHECK still admits — yields target=null: every seeded role is removed and none is
+// added, so the builder resolves to ZERO permissions. That is governance_002's
+// deliberate fail-closed divergence (ADR 0151), preserved rather than re-derived —
+// never invent a role for a rank the seed does not define.
+//
+// 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
+// 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) {
+  return !!row
+    && row.is_system === true
+    && typeof row.seeded_rank === 'string'
+    && row.seeded_rank.length > 0;
+}
+
+// planRankRoleSync({ rank, currentRoles, seededRoles }) → { 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,
+//                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
+//           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;
+
+  const held = currentRoles.filter((r) => r && typeof r.role_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] : [];
+
+  const removed = new Set(remove);
+  const next = held
+    .map((r) => r.role_key)
+    .filter((key) => !removed.has(key))
+    .concat(add)
+    .sort();
+
+  return Object.freeze({
+    target,
+    add: Object.freeze(add),
+    remove: Object.freeze(remove),
+    next: Object.freeze(next),
+  });
+}
+
+module.exports = { planRankRoleSync, isSeededRankRole };

package/modules/governance/resolver.js

@@ -0,0 +1,221 @@
+'use strict';
+
+// modules/governance/resolver.js — the permission resolver (ADR 0151, BV1.R95).
+//
+// Turns a builder's ROLES into their effective PERMISSION SET: the union of every
+// permission granted to every role they hold. This is the heart of the
+// permissions-as-atom model — `requirePermission()` (R97) and every migrated gate
+// (R104-R107) resolve authority through here.
+//
+// TWO AXES, two entry points (R98, ADR 0151 §3). Roles are one axis; a machine
+// PRINCIPAL's capability is the other, resolved from its exact `system_role` and
+// never from a role. They are kept apart on purpose — see resolvePrincipalPermissions
+// below, and the principal keys effectivePermissions drops.
+//
+// It preserves ADR 0016 exactly:
+//   • server-side — the answer is computed on the server from DB rows, never from
+//     a token claim or anything the client can influence;
+//   • per request — resolveBuilderPermissions() is called on the request that
+//     needs it, so a revoked role takes effect on the builder's very next request;
+//   • UNCACHED — there is no memo, no TTL, no process-local map. Caching authority
+//     is the one optimisation this file must never take (a cached grant survives
+//     its revocation, which is the failure mode the trust boundary exists to
+//     prevent). If a future profile shows the join is hot, the answer is a DB
+//     index, not a cache.
+//
+// Fail-closed throughout: a builder with no roles resolves to the EMPTY set, and a
+// grant naming a key the code catalog doesn't define is DROPPED (see
+// effectivePermissions below) rather than admitted on trust.
+
+const catalog = require('./catalog');
+const db = require('./db');
+const sessionScopes = require('./session-scopes');
+
+// Pure core of the ROLE axis, split out so it is unit-testable without a database.
+//
+// Filters raw grant rows against the code catalog: the catalog is the source of
+// truth for what a permission IS (every key maps to a real route — modules/
+// governance/CLAUDE.md), so a DB row naming an unknown key is stale or hand-
+// inserted and grants NOTHING. Returns a frozen, sorted, de-duplicated array.
+//
+// It also DROPS every principal key (R98). A machine identity's capability is the
+// other axis — it comes from `builders.system_role`, never from a role — so a grant
+// row naming `principal.*` confers nothing here no matter how it got written (a
+// hand-inserted row, a future bug in the governance CRUD's system-permission
+// rejection). That makes "a role cannot confer a principal permission" structural
+// rather than merely policed at the write side.
+function effectivePermissions(rawKeys) {
+  const known = new Set();
+  for (const key of rawKeys || []) {
+    if (!catalog.byKey(key)) continue;
+    if (catalog.isPrincipalKey(key)) continue;
+    known.add(key);
+  }
+  return Object.freeze([...known].sort());
+}
+
+// The PRINCIPAL axis (R98, ADR 0151 §3) — deliberately a SEPARATE entry point, not
+// a branch inside the role resolve. A builder's authority is the union of their
+// roles; a machine principal's authority is its identity, and collapsing the two
+// into one lookup is exactly the mistake that would let a rank reach a principal
+// capability.
+//
+// Pure and DB-free: the only input is `builders.system_role`, which requireBuilder
+// already reads fresh from the DB per request (alongside rank), and which no API
+// route writes — a principal is provisioned out-of-band by migration, under a DB
+// CHECK allowlist. The match is EXACT string equality, so NULL (every human,
+// including an Archon), a differently-cased value, or an unknown role resolves to
+// the empty set. Mirrors requireBfgPrincipal / requireDiscordBot in src/bongos/
+// auth.js, which stay the HTTP enforcement point.
+function resolvePrincipalPermissions(systemRole) {
+  const principal = catalog.principalByRole(systemRole);
+  return principal ? Object.freeze([principal.permission]) : Object.freeze([]);
+}
+
+// Does this exact machine identity hold this permission? Fail-closed on a blank or
+// unknown identity, and on a key the identity does not own (one principal never
+// reaches another's capability).
+function principalHasPermission(systemRole, key) {
+  return resolvePrincipalPermissions(systemRole).includes(key);
+}
+
+// The resolve entry point. Returns the builder's effective permission set as a
+// frozen sorted array of catalog keys. A null/invalid builder id resolves to the
+// empty set (fail-closed) without touching the DB.
+async function resolveBuilderPermissions(builderId) {
+  if (builderId === null || builderId === undefined || builderId === '') return Object.freeze([]);
+  const raw = await db.getPermissionKeysForBuilder(builderId);
+  return effectivePermissions(raw);
+}
+
+// Convenience for gate code: does this builder hold EVERY one of `required`?
+// An empty `required` list is a programming error, not an open gate — it returns
+// false so a mis-authored gate denies rather than admits (the same posture
+// requireRank takes on an all-unknown allow-list).
+//
+// It also REFUSES ownership-scoped keys (R100). "Do you hold box.manage.own" has
+// no unconditional answer — the permission is parameterized by a resource this
+// function was never given — and returning true would be precisely the collapse
+// of `.own` into an unconditional grant the axis exists to prevent. The caller
+// wants authorizeOwned(), which cannot be called without naming the owner.
+async function builderHasPermissions(builderId, required) {
+  if (!Array.isArray(required) || required.length === 0) return false;
+  if (required.some((k) => catalog.isOwnershipScoped(k))) return false;
+  const held = new Set(await resolveBuilderPermissions(builderId));
+  return required.every((k) => held.has(k));
+}
+
+// ── the OWNERSHIP axis (R100, ADR 0151 §3) ──────────────────────────────────────
+// The third entry point, and a SEPARATE one for the same reason the principal axis
+// is separate: an ownership-scoped permission is a conjunction of two facts from
+// two different places, and folding it into the plain resolve would silently drop
+// the second one.
+//
+//   1. the ROLE fact  — does the builder hold the key? (this file, from the DB)
+//   2. the OWNER fact — is the concrete row theirs? (REQUEST-scoped; only the
+//                       handler that loaded the row knows it)
+//
+// The resolver structurally cannot know (2): it is handed a builder id, never a
+// box/claim/memory row. So the caller SUPPLIES the owner and the model refuses to
+// answer without it — `ownerId` is not an option, it is the second half of the
+// question. That is what keeps `.own` from degrading into `.any`: there is no code
+// path here that turns an ownership-scoped key into an admit on its own.
+//
+// Pure + DB-free where it can be: the comparison below never touches Postgres, and
+// the role fact reuses resolveBuilderPermissions, so ADR 0016 holds unchanged —
+// per-request, server-side, no stored answer.
+
+// The owner comparison, normalized once so ~15 sites stop hand-rolling it. STRICT:
+// only a scalar id (Postgres hands bigints back as strings, JS code carries them as
+// numbers, so 7 and '7' must match) — anything else, including null/undefined, an
+// object, an array, a boolean, NaN or an empty/blank string, has NO identity and
+// therefore matches NOTHING. No trimming and no case-folding: normalizing harder
+// than the data warrants is how a comparison quietly widens.
+function ownerIdentity(value) {
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value) : null;
+  if (typeof value === 'bigint') return String(value);
+  if (typeof value === 'string') return value === '' ? null : value;
+  return null;
+}
+function sameOwner(a, b) {
+  const left = ownerIdentity(a);
+  const right = ownerIdentity(b);
+  return left !== null && right !== null && left === right;
+}
+
+// Does this builder hold `key` AND own the resource `ownerId` identifies?
+// Fail-closed on every unhappy path — an unknown key, a key that is NOT
+// ownership-scoped (wrong entry point; the plain resolve answers those), a missing
+// or unidentifiable owner, or a builder who simply does not hold the key.
+async function authorizeOwned(builderId, key, context) {
+  const permission = catalog.byKey(key);
+  if (!permission || permission.scope !== 'own') return false;
+  if (!sameOwner(context && context.ownerId, builderId)) return false;
+  return (await resolveBuilderPermissions(builderId)).includes(key);
+}
+
+// The composition every own-scoped route actually wants: reach this row because it
+// is YOURS, or because you hold the cross-owner permission over its resource
+// family (claim.release.any, memory.read.any, box.fleet.manage). One resolve, both
+// branches. A resource with no cross-owner form by design (credential) simply has
+// no second branch, so the answer stays own-only.
+async function authorizeOwnedOrAny(builderId, ownKey, context) {
+  const permission = catalog.byKey(ownKey);
+  if (!permission || permission.scope !== 'own') return false;
+  const held = await resolveBuilderPermissions(builderId);
+  if (catalog.crossOwnerKeysFor(ownKey).some((k) => held.includes(k))) return true;
+  return sameOwner(context && context.ownerId, builderId) && held.includes(ownKey);
+}
+
+// ── the SESSION-SCOPE axis (R99, ADR 0151 §3) ───────────────────────────────────
+// The FOURTH entry point, separate for the same reason the other three are: it
+// answers a different question with a different input. Roles answer "what may this
+// PERSON do"; a principal answers "what may this MACHINE do"; an ownership scope
+// answers "whose row may it be done to"; a session-scope answers "how much of that
+// does THIS CREDENTIAL carry". A dev-box token is minted onto a machine outside the
+// ADR 0016 trust boundary (#919/SR#2, ADR 0053), so it must stay limited even when
+// its builder is an Archon — which no role-shaped answer can express.
+//
+// A SESSION-SCOPE CAN ONLY EVER NARROW, in both directions:
+//   • INTERSECTION, never union. The scope may not GRANT a permission the roles do
+//     not confer — so the composition below is written as a FILTER of the ROLE
+//     answer. There is no branch here that can add a key, which is what makes
+//     "a box token cannot escalate" structural rather than merely intended.
+//   • DENY-BY-DEFAULT. A key the allow-list does not name is denied; an
+//     unrecognised session source resolves to NOTHING rather than to "full".
+// Widening is therefore not expressible without deleting the filter, and R103's
+// parity is untouched: effectivePermissions is the unchanged ROLE answer this
+// composes ON TOP of, never inside.
+//
+// Pure and DB-free (the DB half is resolveBuilderPermissions'), so an unknown key
+// on an allow-list is inert as well as refused at load: it can never appear in the
+// catalog-filtered role answer, so it can never survive the intersection.
+function narrowToSessionScope(rawKeys, source) {
+  const scope = sessionScopes.scopeFor(source);
+  if (!scope) return Object.freeze([]); // unrecognised source → no authority at all
+  const held = effectivePermissions(rawKeys);
+  if (scope.unscoped) return held; // this credential narrows nothing (cli/web)
+  const allowed = new Set(scope.permissions);
+  return Object.freeze(held.filter((key) => allowed.has(key)));
+}
+
+// What can THIS SESSION actually do? The builder's roles ∩ this session's scope,
+// as a frozen sorted array of catalog keys. Fails closed BEFORE touching the DB on
+// a source the registry does not declare.
+async function resolveSessionPermissions(builderId, source) {
+  if (!sessionScopes.scopeFor(source)) return Object.freeze([]);
+  return narrowToSessionScope(await resolveBuilderPermissions(builderId), source);
+}
+
+module.exports = {
+  resolveBuilderPermissions,
+  builderHasPermissions,
+  effectivePermissions,
+  resolvePrincipalPermissions,
+  principalHasPermission,
+  sameOwner,
+  authorizeOwned,
+  authorizeOwnedOrAny,
+  narrowToSessionScope,
+  resolveSessionPermissions,
+};

package/modules/governance/routes/governance.js

@@ -0,0 +1,89 @@
+'use strict';
+
+// The governance module's kernel PORT registration (ADR 0151, BV1.R95).
+//
+// governance exposes the permission RESOLVER as the `governance` kernel PORT.
+// CORE files that must NOT import a module resolve it instead — first among them
+// src/bongos/auth.js, whose `requirePermission()` gate (R97) needs a builder's
+// effective permission set on every gated request. The one-way rule (ADR 0083)
+// forbids core requiring modules/governance/ directly; the port is how the
+// capability crosses that line.
+//
+// Why a route factory for a (currently) routeless capability: `mountModuleRoutes`
+// is the one boot hook that runs BOTH in the live server AND whenever a test
+// rebuilds the GDS router, so registering here keeps the port present for the
+// route-building tests too. Registration is hasProvider-guarded so
+// re-instantiation never trips the seam's single-provider duplicate guard.
+// (Mirrors modules/economy/routes/reward.js.) The governance CRUD endpoints land
+// on this same router in R110.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const resolver = require('../resolver');
+const catalog = require('../catalog');
+const db = require('../db');
+const sessionScopes = require('../session-scopes');
+
+// The port surface. Deliberately narrow: resolution + the catalog reads a gate or
+// the Archon tab needs. It grows with R98-R101 (principals, session-scopes,
+// ownership scoping, the protected-surface registry) — one object port rather
+// than a port per capability, so core resolves `governance` once.
+//
+// The principal half (R98) is READ-ONLY by construction: resolution keyed on an
+// exact system_role, plus `listPrincipals` for the tab to render. There is no
+// create/grant/assign counterpart and there must never be one — a principal is
+// provisioned out-of-band in `builders.system_role` (migration + DB CHECK
+// allowlist), so the tab can SHOW a principal but has nothing to call to make one.
+//
+// The ownership half (R100) is why an own-scoped route reaches the port from
+// INSIDE its handler rather than from a middleware: the second half of the
+// decision is the concrete row's owner, which only the handler that loaded the row
+// knows. `authorizeOwned`/`authorizeOwnedOrAny` take that owner as an argument, so
+// there is no arity at which an ownership-scoped key resolves to an admit on its
+// own (ADR 0151 §3's in-handler pure-gate pattern, made a first-class call).
+// Callers must fail CLOSED when the port is absent, exactly as requirePermission
+// does — a missing authority system is a denial, never an admission.
+//
+// The session-scope half (R99) is READ-ONLY and deliberately NOT the enforcement
+// path: the kernel gate (auth.requireBuilder) reads the same registry as static
+// data, so a request never depends on this port being registered to stay
+// deny-by-default. What the port adds is the composed answer — roles ∩ this
+// session's scope — for the governance tab and for any gate that wants the
+// session's real authority rather than the builder's.
+const governancePort = {
+  resolveBuilderPermissions: resolver.resolveBuilderPermissions,
+  builderHasPermissions: resolver.builderHasPermissions,
+  getRoleKeysForBuilder: db.getRoleKeysForBuilder,
+  isSystem: catalog.isSystem,
+  isGrantable: catalog.isGrantable,
+  permissionKeys: catalog.permissionKeys,
+  resolvePrincipalPermissions: resolver.resolvePrincipalPermissions,
+  principalHasPermission: resolver.principalHasPermission,
+  isPrincipalKey: catalog.isPrincipalKey,
+  listPrincipals: catalog.principals,
+  authorizeOwned: resolver.authorizeOwned,
+  authorizeOwnedOrAny: resolver.authorizeOwnedOrAny,
+  sameOwner: resolver.sameOwner,
+  isOwnershipScoped: catalog.isOwnershipScoped,
+  crossOwnerKeysFor: catalog.crossOwnerKeysFor,
+  resolveSessionPermissions: resolver.resolveSessionPermissions,
+  narrowToSessionScope: resolver.narrowToSessionScope,
+  sessionScopeFor: sessionScopes.scopeFor,
+  listSessionScopes: () => sessionScopes.SESSION_SCOPES,
+};
+
+function registerSeams() {
+  if (!api.hasProvider('governance')) {
+    api.registerProvider('governance', governancePort);
+  }
+}
+
+module.exports = function buildGovernanceRouter() {
+  registerSeams();
+  // No HTTP surface yet — the resolver is a pure kernel port. The empty router is
+  // only the loader's contributes.routes mount vehicle; R110 adds the roles /
+  // permissions / assignments CRUD here behind `governance.manage`.
+  return express.Router();
+};
+
+module.exports.governancePort = governancePort;

package/modules/governance/routes/role-sync.js

@@ -0,0 +1,49 @@
+'use strict';
+
+// The governance module's rank-role SYNC port (ADR 0151, BV1.R95b).
+//
+// A second, deliberately tiny kernel port beside `governance` (routes/governance.js).
+// `governance` is the READ surface every gate resolves on every request; this is the
+// single WRITE core needs — "this builder's rank is now X, make their seeded
+// rank-role match". They are kept apart on purpose:
+//   • the read port is on the hot path of every permission-gated request and is
+//     resolved by requirePermission(); a mutation has no business hanging off it;
+//   • this one is resolved by exactly three writers (the two _applyRankChangeTx
+//     twins + the sign-in path) and is a TRANSACTION PARTICIPANT — it takes the
+//     caller's client so the role rotation commits or rolls back with the rank write.
+// The port name is namespaced (`governance.roleSync`) like the `ideas.capture` /
+// `art.getBuilderGeminiKeyRow` / `grade.builderRollingAvgGrade` ports.
+//
+// Registered from a route factory for the same reason routes/governance.js is:
+// mountModuleRoutes is the one boot hook that runs BOTH in the live server and
+// whenever a test rebuilds the router, and registration is hasProvider-guarded so a
+// rebuild never trips the seam's single-provider duplicate guard.
+//
+// The router is EMPTY and must stay empty. Rank-derived assignment is automatic and
+// has no HTTP surface; the MANUAL assignment CRUD is R110's Archon-gated tab on the
+// governance router. An endpoint here would be a way to hand out a rank-role without
+// changing the rank.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const db = require('../db');
+
+// DELEGATE, never spread — a test that stubs db.syncRankRole must still bite at call
+// time (the modules/onboarding/port.js precedent; a spread captures the original
+// reference at module-load).
+const rankRoleSyncPort = {
+  syncRankRole: (...a) => db.syncRankRole(...a),
+};
+
+function registerSeams() {
+  if (!api.hasProvider('governance.roleSync')) {
+    api.registerProvider('governance.roleSync', rankRoleSyncPort);
+  }
+}
+
+module.exports = function buildGovernanceRoleSyncRouter() {
+  registerSeams();
+  return express.Router();
+};
+
+module.exports.rankRoleSyncPort = rankRoleSyncPort;

package/modules/governance/session-scopes.js

@@ -0,0 +1,127 @@
+'use strict';
+
+// modules/governance/session-scopes.js — the SESSION-SCOPE axis (ADR 0151 §3, BV1.R99).
+//
+// The FOURTH axis, and the only one attached to the TOKEN rather than to the
+// builder. Roles say what a person may do (R95); a principal's identity says what
+// a machine may do (R98); an ownership scope says whose row it may be done to
+// (R100); a SESSION-SCOPE says how much of that authority this particular
+// credential carries. A dev-box session is minted onto a machine OUTSIDE the ADR
+// 0016 trust boundary (#919/SR#2, ADR 0053), so it must stay limited even when its
+// builder is an Archon.
+//
+// A SESSION-SCOPE CAN ONLY EVER NARROW. That is the whole load-bearing property,
+// and it has two halves that fail in opposite directions:
+//   • INTERSECTION, never union — the scope may not GRANT a permission the
+//     builder's roles do not already confer, or a box token would escalate;
+//   • DENY-BY-DEFAULT — a permission the allow-list does not name is denied, or an
+//     unlisted permission leaks through.
+// resolver.narrowToSessionScope() is the one place the two compose, and it is
+// written as a FILTER of the role answer so widening is not expressible there.
+//
+// EXPLICIT DATA, not `if (source === 'box')`. session-scopes.json (next to this
+// file) is the declaration; this module validates it against the permission
+// catalog at load. GOVERNANCE OWNS THE POLICY, THE KERNEL STAYS THE ENFORCER —
+// the same split R101 draws for the protected-surface registry: src/bongos/auth.js
+// reads the same JSON as DATA (fs, never `require` — ADR 0083's one-way rule) and
+// requireBuilder remains the gate every route composes. Nothing here enforces
+// anything; re-mapping a scope here changes what the gate admits, it can never
+// move the gate.
+//
+// FAIL-CLOSED at load: a key the catalog does not define, a `system: true`
+// trust-boundary key, or a machine-principal key on a session-scope allow-list all
+// THROW. Silently dropping the row would quietly shrink (or, for a principal,
+// blur) the surface a token outside the trust boundary may reach — an unreadable
+// policy is a broken install, not an opted-out one.
+
+const catalog = require('./catalog');
+const registry = require('./session-scopes.json');
+
+// Normalize the declared rows into the same shape the kernel loader produces:
+// `source` null for the legacy sourceless row, `permissions` always an array.
+function normalizeScope(row) {
+  return Object.freeze({
+    source: row && row.source !== undefined ? row.source : null,
+    label: row && typeof row.label === 'string' ? row.label : null,
+    unscoped: !!(row && row.unscoped === true),
+    permissions: Object.freeze(row && Array.isArray(row.permissions) ? [...row.permissions] : []),
+  });
+}
+
+// The catalog cross-check. Exported so the shipped assertion itself is what the
+// tests exercise, rather than a re-implementation of it (the fixture would
+// otherwise have to rewrite this file on disk to be loaded).
+function validateAgainstCatalog(scopes) {
+  for (const scope of scopes) {
+    const where = `session-scope registry: scope "${scope.source}"`;
+    // unscoped XOR an allow-list. Both would be ambiguous (does it narrow?);
+    // neither would be a scope that can never admit anything.
+    if (scope.unscoped === (scope.permissions.length > 0)) {
+      throw new Error(`${where} must declare EITHER unscoped:true OR a non-empty permissions allow-list, never both/neither`);
+    }
+    for (const key of scope.permissions) {
+      if (!catalog.byKey(key)) {
+        throw new Error(`${where} allows "${key}", which the permission catalog does not define`);
+      }
+      // R98's rule, kept structural: a machine principal's capability comes from
+      // its exact system_role, never from a role — so a box-scoped session
+      // carrying one must not be expressible on a scope allow-list either.
+      if (catalog.isPrincipalKey(key)) {
+        throw new Error(`${where} allows the machine-principal permission "${key}" — a session-scope narrows a builder's ROLE authority and never composes with the identity axis`);
+      }
+      // A session-scope IS the surface a credential outside the ADR 0016 trust
+      // boundary may reach. A trust-boundary permission must never appear on one,
+      // even though the intersection would make listing it inert today.
+      if (catalog.isSystem(key)) {
+        throw new Error(`${where} allows the system:true permission "${key}" — a session-scope may only list operational capability (a scoped token lives outside the trust boundary)`);
+      }
+    }
+  }
+  return scopes;
+}
+
+const SESSION_SCOPES = Object.freeze(
+  validateAgainstCatalog(Object.freeze((registry.scopes || []).map(normalizeScope))),
+);
+
+const _bySource = new Map(SESSION_SCOPES.map((s) => [s.source, s]));
+
+// The scope a session's `source` declares, or null when the registry does not
+// declare it. An UNRECOGNISED source resolves to null and therefore to NO
+// permissions — it never defaults to "full" (a null/absent source is a DECLARED
+// row here, not an implicit default: it predates the box source existing).
+function scopeFor(source) {
+  const key = source === undefined ? null : source;
+  if (key !== null && typeof key !== 'string') return null;
+  return _bySource.get(key) || null;
+}
+
+// Does this session's scope narrow at all? Unknown source → true (fail-closed:
+// treated as narrowing to nothing, which is what scopeFor/narrowToSessionScope do).
+function isScoped(source) {
+  const scope = scopeFor(source);
+  return !scope || !scope.unscoped;
+}
+
+// The deny-by-default allow-list for a source; empty for an unscoped source (it
+// narrows nothing) AND for an unrecognised one (it admits nothing) — callers must
+// consult scopeFor()/isScoped() to tell those apart, exactly as the resolver does.
+const NO_KEYS = Object.freeze([]);
+function allowedKeys(source) {
+  const scope = scopeFor(source);
+  return scope ? scope.permissions : NO_KEYS;
+}
+
+function sources() {
+  return SESSION_SCOPES.map((s) => s.source);
+}
+
+module.exports = {
+  SESSION_SCOPES,
+  validateAgainstCatalog,
+  normalizeScope,
+  scopeFor,
+  isScoped,
+  allowedKeys,
+  sources,
+};

package/modules/governance/session-scopes.json

@@ -0,0 +1,38 @@
+{
+  "_comment": [
+    "The SESSION-SCOPE registry (BV1.R99, ADR 0151 §3; the model behind ADR 0053).",
+    "A session's scope is capability attached to the TOKEN, orthogonal to the builder's roles.",
+    "Each row declares EITHER unscoped:true (the session narrows nothing) OR a deny-by-default",
+    "permissions allow-list (unlisted => denied). A scope can only ever NARROW: effective",
+    "authority is (the builder's role permissions) INTERSECT (this allow-list), never a union.",
+    "Every key here is validated against modules/governance/catalog.js at load by",
+    "modules/governance/session-scopes.js — unknown, system:true and principal keys are refused.",
+    "Read as DATA by src/bongos/auth.js (fs, never require — ADR 0083's one-way rule)."
+  ],
+  "scopes": [
+    {
+      "source": "cli",
+      "label": "CLI session",
+      "unscoped": true,
+      "note": "Device Flow token on a builder's own machine — inside the trust boundary, carries the builder's full role authority."
+    },
+    {
+      "source": "web",
+      "label": "web session",
+      "unscoped": true,
+      "note": "Hall browser cookie — same authority as the CLI session."
+    },
+    {
+      "source": null,
+      "label": "legacy session",
+      "unscoped": true,
+      "note": "Rows minted before migration 090 added a source column; they predate the 'box' source existing, so they were never box tokens. Declared explicitly rather than defaulted — an UNRECOGNISED source denies."
+    },
+    {
+      "source": "box",
+      "label": "box-scoped session",
+      "permissions": ["box.manage.own"],
+      "note": "Baked into cloud-init so a dev box can bootstrap (#818/SR#2, ADR 0053). The token lives ON the box — OUTSIDE the ADR 0016 trust boundary — so it reaches only its own box record, whatever its builder's rank."
+    }
+  ]
+}