@bongos/core 1.18.3 → 1.18.18

package/modules/governance/db.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// modules/governance/db.js — the governance db slice (ADR 0151, BV1.R95).
+//
+// Reads the role/grant/assignment rows governance_001_tables.sql defines. The
+// per-domain db-slice pattern (ADR 0091 §2): the pool comes through the published
+// doorway (src/module-api.js), never `../../src/bongos/db`.
+//
+// NO CACHING, deliberately. Every read here runs against the live DB on the
+// request that needs it, so a revoked role takes effect on the builder's very
+// next request — the ADR 0016 trust-boundary rule the resolver inherits.
+
+const { pool } = require('../../src/module-api');
+const { planRankRoleSync } = require('./rank-roles');
+
+// Every permission_key granted to any role the builder holds. Duplicates across
+// roles are collapsed by the DISTINCT — the resolver's UNION semantics. Returns
+// a flat array of raw key strings (validated against the catalog by resolver.js);
+// [] for a builder with no roles, which fails closed to zero authority.
+async function getPermissionKeysForBuilder(builderId) {
+  const { rows } = await pool.query(
+    `SELECT DISTINCT rp.permission_key
+       FROM governance_builder_roles br
+       JOIN governance_role_permissions rp ON rp.role_key = br.role_key
+      WHERE br.builder_id = $1`,
+    [builderId],
+  );
+  return rows.map((r) => r.permission_key);
+}
+
+// The role keys a builder holds, for introspection surfaces (the Archon tab,
+// R110/R111) and for explaining a 403. Not part of the resolve path.
+async function getRoleKeysForBuilder(builderId) {
+  const { rows } = await pool.query(
+    `SELECT role_key FROM governance_builder_roles WHERE builder_id = $1 ORDER BY role_key`,
+    [builderId],
+  );
+  return rows.map((r) => r.role_key);
+}
+
+// --- the rank→role WRITE half (BV1.R95b) ------------------------------------
+//
+// Everything above this line only READS. Until R95b the only write to
+// governance_builder_roles in the whole repo was governance_002's run-once
+// backfill, so a builder created after it had NO role (locked out of every
+// permission gate) and a builder whose rank CHANGED kept their OLD rank-role
+// (a demoted Archon still resolving Archon permissions — the ADR 0016 defect).
+//
+// The writer below is a TRANSACTION PARTICIPANT: every caller hands it the client
+// its own BEGIN/COMMIT is running on, so the role rotation commits — or rolls back
+// — atomically with the rank write it accompanies. Core reaches it through the
+// `governance.roleSync` kernel port (routes/role-sync.js); it never imports this
+// module (ADR 0083).
+
+// The seeded rank-roles as the DB actually defines them. Read per call rather than
+// cached: it is the same authority data the resolver refuses to memoise, and this
+// runs on rank writes + sign-in, never in a hot loop.
+async function getSeededRankRoles(q) {
+  const { rows } = await q.query(
+    `SELECT role_key, seeded_rank, is_system
+       FROM governance_roles
+      WHERE is_system = true AND seeded_rank IS NOT NULL`,
+  );
+  return rows;
+}
+
+// A builder's assignments joined to their role definitions, so the plan can tell a
+// seeded rank-role from an Archon-assigned custom one.
+async function getRoleAssignmentsForBuilder(q, builderId) {
+  const { rows } = await q.query(
+    `SELECT br.role_key, r.is_system, r.seeded_rank
+       FROM governance_builder_roles br
+       JOIN governance_roles r ON r.role_key = br.role_key
+      WHERE br.builder_id = $1`,
+    [builderId],
+  );
+  return rows;
+}
+
+// syncRankRole(client, { builderId, rank }) — make the builder's seeded rank-role
+// match `rank`: add the matching one, DELETE every other seeded one, leave custom
+// roles alone. `client` is the caller's open transaction client; pass null/undefined
+// to run on the pool (the sign-in path, which has no surrounding transaction).
+//
+// Idempotent — a builder whose role already matches costs two SELECTs and no write,
+// so calling it on every sign-in quietly repairs drift instead of accumulating it.
+// The DELETE is keyed on the plan's `remove` list, which is built only from rows the
+// join proved are is_system seeded roles, so a custom role can never be caught by it.
+// assigned_by is left NULL: a rank-derived assignment is the system's, not a person's
+// (governance_002's backfill uses the same convention; the human decision is audited
+// in credit_log's rank_change row).
+async function syncRankRole(client, { builderId, rank } = {}) {
+  if (builderId === null || builderId === undefined || builderId === '') {
+    return { target: null, added: [], removed: [] };
+  }
+  const q = client || pool;
+  const seededRoles = await getSeededRankRoles(q);
+  const currentRoles = await getRoleAssignmentsForBuilder(q, builderId);
+  const plan = planRankRoleSync({ rank, currentRoles, seededRoles });
+
+  if (plan.remove.length > 0) {
+    await q.query(
+      `DELETE FROM governance_builder_roles
+        WHERE builder_id = $1 AND role_key = ANY($2::text[])`,
+      [builderId, [...plan.remove]],
+    );
+  }
+  if (plan.add.length > 0) {
+    await q.query(
+      `INSERT INTO governance_builder_roles (builder_id, role_key)
+       SELECT $1, unnest($2::text[])
+       ON CONFLICT (builder_id, role_key) DO NOTHING`,
+      [builderId, [...plan.add]],
+    );
+  }
+  return { target: plan.target, added: [...plan.add], removed: [...plan.remove] };
+}
+
+module.exports = {
+  getPermissionKeysForBuilder,
+  getRoleKeysForBuilder,
+  getSeededRankRoles,
+  getRoleAssignmentsForBuilder,
+  syncRankRole,
+};

package/modules/governance/migrations/governance_001_tables.sql

@@ -0,0 +1,81 @@
+-- governance_001_tables.sql — the `governance` module's DB slice (ADR 0151, BV1.R93).
+--
+-- The live home for configurable roles/permissions: assignable roles, the role→
+-- permission grants, and builder→role assignments. This is the DB half of the
+-- permissions-as-atom model; the permission CATALOG itself is CODE
+-- (modules/governance/catalog.js — a permission maps to a real route, so it is not
+-- UI-invented data), so `permission_key` here is a string validated app-side against
+-- the catalog, deliberately NOT a foreign key to a permissions table.
+--
+-- Preserves ADR 0016: authority is still resolved server-side, per request, uncached
+-- (R95). These tables only hold the role definitions + assignments the resolver unions;
+-- they grant nothing on their own.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): every object
+-- is governance_-prefixed, there is no down-migration, and the filename is
+-- governance_-prefixed (ADR 0108 §5) so its stem never collides across repos.
+-- `scripts/migrate.sh` discovers + applies this when the governance module is enabled
+-- (default:true). Idempotent: safe to re-run.
+
+BEGIN;
+
+-- ---------------------------------------------------------------------------
+-- governance_roles — an assignable role. Four are seeded as the compat rank-roles
+-- (is_system=true, seeded_rank set); the rest are Archon-authored custom roles.
+-- role_key is the stable natural key the other two tables reference.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS governance_roles (
+  id            bigserial PRIMARY KEY,
+  -- stable slug: 'xenos'/'thetes'/'metic'/'archon' for the seeded rank-roles, or a
+  -- kebab-case slug for an Archon-created custom role.
+  role_key      text NOT NULL UNIQUE,
+  label         text NOT NULL,
+  description   text,
+  -- for a seeded rank-role: the rank it reproduces (xenos/thetes/metic/archon);
+  -- NULL for a custom role. Kept so the resolver + tab can recognise the four
+  -- protected rank-roles (they cannot be deleted/renamed via the tab).
+  seeded_rank   text,
+  -- true for the four seeded rank-roles — a system role the tab renders but cannot
+  -- delete/rename. Custom roles are false.
+  is_system     boolean NOT NULL DEFAULT false,
+  -- who authored a custom role (NULL for the seeded rank-roles).
+  created_by    bigint REFERENCES builders(id) ON DELETE SET NULL,
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+
+-- ---------------------------------------------------------------------------
+-- governance_role_permissions — the grants: which permission KEYS a role holds.
+-- permission_key is a catalog key (modules/governance/catalog.js), validated
+-- app-side (NOT a FK — the catalog is code, not a table). The governance API (R110)
+-- refuses to insert a `system` permission for a custom role; the seeded rank-roles
+-- legitimately hold their archon-floored system perms.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS governance_role_permissions (
+  role_key       text NOT NULL REFERENCES governance_roles(role_key) ON DELETE CASCADE,
+  permission_key text NOT NULL,
+  granted_at     timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (role_key, permission_key)
+);
+
+CREATE INDEX IF NOT EXISTS governance_role_permissions_perm_idx
+  ON governance_role_permissions (permission_key);
+
+-- ---------------------------------------------------------------------------
+-- governance_builder_roles — builder→role assignments. The resolver (R95) unions
+-- the permissions of every role a builder holds. The compat seed backfills exactly
+-- one role per builder (their rank-role) so day-one behaviour is identical.
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS governance_builder_roles (
+  builder_id   bigint NOT NULL REFERENCES builders(id) ON DELETE CASCADE,
+  role_key     text NOT NULL REFERENCES governance_roles(role_key) ON DELETE CASCADE,
+  -- who assigned this role (NULL for the compat-seed backfill).
+  assigned_by  bigint REFERENCES builders(id) ON DELETE SET NULL,
+  assigned_at  timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (builder_id, role_key)
+);
+
+CREATE INDEX IF NOT EXISTS governance_builder_roles_role_idx
+  ON governance_builder_roles (role_key);
+
+COMMIT;

package/modules/governance/migrations/governance_002_seed_and_backfill.sql

@@ -0,0 +1,103 @@
+-- governance_002_seed_and_backfill.sql — the compatibility seed (ADR 0151, BV1.R93).
+--
+-- Seeds the four rank-roles (xenos/thetes/metic/archon) with the grants that
+-- reproduce today's rank thresholds EXACTLY, then backfills every existing builder
+-- the role matching their current rank. This is the "zero day-one behavior change"
+-- guarantee: after this runs, resolveBuilderPermissions() (R95) returns, for every
+-- builder, precisely the powers requireRank granted them before.
+--
+-- The role→permission grants below are MATERIALISED from the code catalog's
+-- RANK_ROLE_SEED (modules/governance/catalog.js), which derives them from each
+-- permission's floor (cumulative nested supersets). tests/governance_seed.mjs parses
+-- this file and asserts the four arrays equal RANK_ROLE_SEED, so this snapshot can
+-- never silently drift from the catalog (the "no second list that drifts" discipline,
+-- SEC #863 / R108). A NEW permission granted to a seeded role is a NEW migration, not
+-- an edit here (migrations are run-once).
+--
+-- Idempotent (ON CONFLICT DO NOTHING throughout): safe to re-run.
+
+BEGIN;
+
+-- ── the four seeded rank-roles ────────────────────────────────────────────────
+-- Labels are the canonical rank names (portable core); an instance may surface its
+-- own display labels via config/governance.json (R96) without changing these keys.
+INSERT INTO governance_roles (role_key, label, description, seeded_rank, is_system) VALUES
+  ('xenos',  'Xenos',  'Seeded rank-role — the sandboxed entry rank. Own-work + public read.', 'xenos',  true),
+  ('thetes', 'Thetes', 'Seeded rank-role — graduated newcomer. Adds the general claim queue.', 'thetes', true),
+  ('metic',  'Metic',  'Seeded rank-role — the trusted working rank. Adds review/triage/authoring.', 'metic',  true),
+  ('archon', 'Archon', 'Seeded rank-role — top authority. Adds the admin + system (non-grantable) powers.', 'archon', true)
+ON CONFLICT (role_key) DO NOTHING;
+
+-- ── the grants (materialised from RANK_ROLE_SEED; guarded by tests/governance_seed.mjs) ──
+
+-- xenos (Xenos) — 12 permissions
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'xenos', unnest(ARRAY[
+  'task.claim.newcomer', 'task.ship', 'task.act.own', 'box.manage.own',
+  'memory.manage.own', 'credential.manage.own', 'me.wandering.set', 'cost.log',
+  'learning.create', 'blocker.file', 'idea.file', 'page.view.public'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+-- thetes (Thetes) — 14 permissions
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'thetes', unnest(ARRAY[
+  'task.claim.any', 'page.view.builder', 'task.claim.newcomer', 'task.ship',
+  'task.act.own', 'box.manage.own', 'memory.manage.own', 'credential.manage.own',
+  'me.wandering.set', 'cost.log', 'learning.create', 'blocker.file',
+  'idea.file', 'page.view.public'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+-- metic (Metic) — 38 permissions
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'metic', unnest(ARRAY[
+  'idea.triage', 'blocker.review', 'task.create', 'task.edit',
+  'task.promote', 'task.demote', 'task.vote', 'task.dependency.manage',
+  'task.criterion.manage', 'criterion.satisfy', 'criterion.review', 'planning.run',
+  'priority.run', 'goal.create', 'goal.archive', 'goal.scope.widen',
+  'module.enable', 'module.submit', 'security.report.file', 'llm_cache.use',
+  'backup.manage', 'source.clone.local', 'box.source.full', 'task.claim.any',
+  'page.view.builder', 'goal.manage.own', 'task.claim.newcomer', 'task.ship',
+  'task.act.own', 'box.manage.own', 'memory.manage.own', 'credential.manage.own',
+  'me.wandering.set', 'cost.log', 'learning.create', 'blocker.file',
+  'idea.file', 'page.view.public'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+-- archon (Archon) — 71 permissions
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'builder.rank.set', 'version.close', 'task.confirm.grade_bypass', 'dependency.cross_tier.manage',
+  'goal.scope.manage', 'governance.manage', 'gate_approval.decide', 'deploy.push_main',
+  'path.protected.modify', 'infra.ssh', 'builder.status.set', 'builder.budget.set',
+  'task.abandon', 'criterion.unsatisfy', 'auth.session.revoke', 'access_request.review',
+  'security.report.adjudicate', 'provisioning.fleet.manage', 'box.fleet.manage', 'autonomy.precheck',
+  'discord.channels.manage', 'project.curate', 'override_request.decide', 'claim.release.any',
+  'idea.ratify', 'task.newcomer_restock', 'task.peer_votes.tally', 'goal.reorder',
+  'builder.roster.read', 'session.search', 'memory.read.any', 'audit_log.read',
+  'idea.triage', 'blocker.review', 'task.create', 'task.edit',
+  'task.promote', 'task.demote', 'task.vote', 'task.dependency.manage',
+  'task.criterion.manage', 'criterion.satisfy', 'criterion.review', 'planning.run',
+  'priority.run', 'goal.create', 'goal.archive', 'goal.scope.widen',
+  'module.enable', 'module.submit', 'security.report.file', 'llm_cache.use',
+  'backup.manage', 'source.clone.local', 'box.source.full', 'task.claim.any',
+  'page.view.builder', 'goal.manage.own', 'task.claim.newcomer', 'task.ship',
+  'task.act.own', 'box.manage.own', 'memory.manage.own', 'credential.manage.own',
+  'me.wandering.set', 'cost.log', 'learning.create', 'blocker.file',
+  'idea.file', 'page.view.public', 'page.view.governance'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+-- ── backfill: every builder gets the role matching their current rank ─────────
+-- The JOIN admits only builders whose rank IS one of the four seeded rank-roles.
+-- A builder on a reserved/unwired rank (none exist today — verified) gets NO row and
+-- resolves to zero permissions: the deliberate fail-closed divergence of ADR 0151
+-- (stricter than today's latent threshold-admit of an unwired rank).
+INSERT INTO governance_builder_roles (builder_id, role_key)
+SELECT b.id, b.rank
+FROM builders b
+JOIN governance_roles r ON r.role_key = b.rank AND r.is_system = true
+ON CONFLICT (builder_id, role_key) DO NOTHING;
+
+COMMIT;

package/modules/governance/migrations/governance_003_task_abandon_metic.sql

@@ -0,0 +1,28 @@
+-- governance_003_task_abandon_metic.sql — grant `task.abandon` to the Metic rank-role
+-- (ADR 0152; task 1002476).
+--
+-- The abandon route was re-ranked Archon→Metic+ in the code gate, and the catalog's
+-- floor for `task.abandon` moved archon→metic to match. The compat seed
+-- (governance_002) is RUN-ONCE, so a floor change cannot be made by editing it —
+-- every already-migrated database would keep the old grant. This is the follow-on
+-- grant migration the 002 header calls for ("a NEW permission granted to a seeded
+-- role is a NEW migration, not an edit here").
+--
+-- Additive only: `archon` already holds `task.abandon` (the seeded roles are
+-- cumulative supersets), so lowering the floor adds exactly one grant — metic —
+-- and revokes nothing. Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT
+-- only, no dropped or retyped state).
+--
+-- The drift guard (tests/governance_seed.mjs) reads the UNION of the seed and every
+-- later governance_* grant migration, so this file is what keeps the SQL snapshot
+-- equal to catalog.js's floor-derived RANK_ROLE_SEED.
+
+BEGIN;
+
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'metic', unnest(ARRAY[
+  'task.abandon'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+COMMIT;

package/modules/governance/migrations/governance_004_criterion_create.sql

@@ -0,0 +1,39 @@
+-- governance_004_criterion_create.sql — grant the new `criterion.create` atom to the
+-- Metic and Archon rank-roles (ADR 0154; task 1002538).
+--
+-- `POST /versions/:id/done-when` was re-gated Archon→Metic+ (walled by goal
+-- ownership: a non-Archon must name a goal they own or manage, on a building
+-- version). In catalog.js the route moved OUT of the bundled `criterion.review`
+-- row — where it had been mis-filed while it was still Archon-only (ADR 0154 §5)
+-- — and into its own atom, `criterion.create`, floor `metic`.
+--
+-- Unlike governance_003 (a floor MOVE, where archon already held the key), this is
+-- a BRAND-NEW key: no role holds it yet, so both rungs the floor implies are
+-- granted here. RANK_ROLE_SEED is a cumulative superset — floor `metic` means
+-- {metic, archon} — and the drift guard (tests/governance_seed.mjs) compares the
+-- UNION of the run-once seed (governance_002) plus every later grant migration
+-- against that floor-derived seed, per role.
+--
+-- Additive only: one new permission key granted to two roles; nothing is revoked.
+-- (`criterion.review` keeps its key and its floor — only its human `guards` note
+-- lost the route.) Idempotent (ON CONFLICT DO NOTHING); forward-safe (INSERT only).
+--
+-- One block PER ROLE, in the governance_003 shape: the drift guard scans for
+-- `SELECT '<role>', unnest(ARRAY[…])` literally, so a combined
+-- `unnest(ARRAY['metic','archon']), 'key'` form parses as zero grants and reds it.
+
+BEGIN;
+
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'metic', unnest(ARRAY[
+  'criterion.create'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+INSERT INTO governance_role_permissions (role_key, permission_key)
+SELECT 'archon', unnest(ARRAY[
+  'criterion.create'
+])
+ON CONFLICT (role_key, permission_key) DO NOTHING;
+
+COMMIT;

package/modules/governance/migrations/governance_005_resync_builder_rank_roles.sql

@@ -0,0 +1,56 @@
+-- governance_005_resync_builder_rank_roles.sql — repair drifted builder→role
+-- assignments (ADR 0151, BV1.R95b).
+--
+-- governance_002 backfilled every builder the seeded role matching their rank, but
+-- it is run-once and nothing kept it true afterwards: the only write to
+-- governance_builder_roles in the repo WAS that backfill. So by now the table can
+-- hold two kinds of wrong row:
+--   • MISSING — a builder admitted after 002 ran has no role at all, and
+--     resolveBuilderPermissions() returns the empty set (denied everywhere).
+--   • STALE — a builder whose rank CHANGED still holds their OLD rank-role. A
+--     demoted Archon keeps resolving Archon permissions, which defeats ADR 0016's
+--     "a demotion takes effect on the very next request" promise one layer beneath
+--     the (correctly uncached) resolver. This is the security half.
+--
+-- BV1.R95b closes the hole going forward (the two _applyRankChangeTx twins rotate
+-- the role inside the rank transaction, and sign-in assigns it at registration);
+-- this migration repairs the rows already written.
+--
+-- IDEMPOTENT: the DELETE only matches rows that disagree with builders.rank and the
+-- INSERT is ON CONFLICT DO NOTHING, so a second run changes nothing.
+--
+-- ADDITIVE per ADR 0083 §Decision #5: no DDL at all, no down path, every object it
+-- names is governance_-prefixed or the core `builders` table it reads. It touches
+-- governance_builder_roles (ASSIGNMENTS) and NOT governance_role_permissions
+-- (GRANTS) — so it revokes no grant and the union model tests/governance_seed.mjs
+-- builds over the grant migrations is untouched.
+
+BEGIN;
+
+-- 1. Drop every SEEDED rank-role a builder holds that no longer matches their rank.
+--    Keyed on is_system + seeded_rank, so an Archon-assigned CUSTOM role
+--    (is_system=false) is never caught by it — only the rank-derived role rotates.
+--    This clause is the security fix: an additive-only repair would leave the
+--    demoted Archon's `archon` row in place, preserving exactly the privilege
+--    retention this migration exists to end.
+DELETE FROM governance_builder_roles br
+ USING governance_roles r, builders b
+ WHERE r.role_key = br.role_key
+   AND b.id = br.builder_id
+   AND r.is_system = true
+   AND r.seeded_rank IS NOT NULL
+   AND r.seeded_rank IS DISTINCT FROM b.rank;
+
+-- 2. (Re)assign the seeded rank-role matching each builder's CURRENT rank.
+--    The INNER JOIN is governance_002's, deliberately: a builder sitting on one of
+--    the twelve legacy ranks migration 023's CHECK still admits matches no seeded
+--    role, so they get NO row and resolve to zero permissions. That is ADR 0151's
+--    intentional fail-closed divergence (stricter than the old latent
+--    threshold-admit of an unwired rank) — preserve it; do not invent a grant here.
+INSERT INTO governance_builder_roles (builder_id, role_key)
+SELECT b.id, r.role_key
+  FROM builders b
+  JOIN governance_roles r ON r.seeded_rank = b.rank AND r.is_system = true
+ON CONFLICT (builder_id, role_key) DO NOTHING;
+
+COMMIT;

package/modules/governance/module.json

@@ -0,0 +1,10 @@
+{
+  "key": "governance",
+  "title": "Governance (configurable roles & permissions)",
+  "description": "Discord-style configurable roles and permissions (ADR 0151, BONGOS-V1 goal 1000030). Permissions are the atomic authority unit and the four ranks (xenos/thetes/metic/archon) become seeded roles; this module owns the code-defined permission catalog (each key flagged `system` = trust-boundary, non-grantable, or operational = delegable) plus the compatibility seed that reproduces today's rank thresholds exactly. A core-domain module, default-on: a Cloud Bongos instance ships configurable roles the way it ships its status page. This first slice (BV1.R94) is the catalog + seed as code constants — the single source the resolver (R95), the requirePermission gate (R97), and the Archon tab (R110/R111) all read. Preserves ADR 0016 (authority resolved server-side, per request, uncached).",
+  "coreVersion": "^1.18.0",
+  "default": true,
+  "contributes": { "migrations": true, "routes": ["governance", "role-sync"] },
+  "provides": ["governance", "governance.roleSync"],
+  "consumes": []
+}

package/modules/governance/protected-surfaces.js

@@ -0,0 +1,88 @@
+'use strict';
+
+// modules/governance/protected-surfaces.js — the protected-surface registry's
+// GOVERNANCE-side API (ADR 0151 §4, BV1.R101).
+//
+// POLICY OWNS / SUBSTRATE ENFORCES — the whole point of this slice.
+//
+//   GOVERNANCE OWNS THE DATA. protected-surfaces.json (next to this file) says
+//   WHICH repo paths are protected, at WHAT rank floor, mapped to WHICH
+//   `system: true` catalog permission. That file is the source of truth; the
+//   Archon governance tab (R110/R111) edits it as policy. Before R101 the same
+//   information was a hardcoded PROTECTED_GLOBS constant inside the kernel.
+//
+//   THE OUT-OF-BAND SUBSTRATE STAYS THE ENFORCER. Nothing here enforces
+//   anything. The enforcers are the git pre-push hook, the grader pre-pass, the
+//   post-push main audit, gate-review.js and the goal-scope check — they read
+//   the registry with no DB, no server and no HTTP, and they are what actually
+//   blocks a sub-floor change (ADR 0043). Re-mapping a floor here changes what
+//   the substrate protects; it can never make the request path the authority.
+//   Moving enforcement into the app is the regression R101 exists to prevent
+//   (ADR 0151 §"Alternatives considered").
+//
+//   NO DB DEPENDENCY. A DB-backed override is a governance-tab concern layered
+//   on top and must never become a dependency of the hook — the hook runs on a
+//   laptop with no database and no network. This module is therefore
+//   synchronous, DB-free and requires nothing but the catalog and the doorway.
+//
+// DEPENDENCY DIRECTION (ADR 0083's one-way rule). Code flows exactly one way:
+// this module → src/module-api.js (the published doorway) → the kernel matcher
+// in src/bongos/permission-path-check.js. Core never requires this module. The
+// kernel loads the JSON data file directly (a static data read, the same way the
+// sibling trust primitive route-rank-check.js reads modules/*/routes/*.js off
+// disk to rank-gate them), and we read the parsed result back through the
+// doorway so there is exactly ONE loader and ONE matcher — no second list to
+// drift (the SEC #863 failure mode).
+
+const api = require('../../src/module-api');
+const catalog = require('./catalog');
+
+const ppc = api.permissionPathCheck;
+
+// The registry, as parsed by the single kernel loader.
+const SURFACES = ppc.PROTECTED_SURFACES;
+
+// ── invariants asserted at module load (fail loud on an authoring typo) ───────
+// The governance module is where the registry meets the permission catalog, so
+// this is where "every protected surface maps to a real, non-grantable
+// permission" is checked. A surface mapping to an unknown key, or to a
+// `system: false` (grantable) key, would mean an Archon could hand a custom role
+// the power the substrate is supposed to reserve — exactly the wall ADR 0151 §4
+// builds. Fail loud rather than silently protecting nothing.
+for (const s of SURFACES) {
+  const perm = catalog.byKey(s.permission);
+  if (!perm) {
+    throw new Error(`protected-surface registry: "${s.glob}" maps to "${s.permission}", which the permission catalog does not define`);
+  }
+  if (perm.system !== true) {
+    throw new Error(`protected-surface registry: "${s.glob}" maps to "${s.permission}", which is not system:true — a protected surface must map to a NON-GRANTABLE permission (ADR 0151 §4)`);
+  }
+  if (!catalog.RANK_ORDER.includes(s.floor)) {
+    throw new Error(`protected-surface registry: "${s.glob}" declares floor "${s.floor}", which is not a rank`);
+  }
+}
+
+// The lowest floor any surface declares — 'metic' today (ADR 0043's Metic floor,
+// now DERIVED from registry data rather than hardcoded).
+const FLOOR = catalog.RANK_ORDER[Math.min(...SURFACES.map((s) => catalog.RANK_ORDER.indexOf(s.floor)))];
+
+// The distinct system permissions the registry maps onto.
+const SYSTEM_PERMISSIONS = Object.freeze([...new Set(SURFACES.map((s) => s.permission))].sort());
+
+// Per-path lookups — the single matcher, reached through the doorway.
+const surfaceFor = (file) => ppc.surfaceFor(file);
+const floorFor = (file) => ppc.floorFor(file);
+const permissionFor = (file) => ppc.permissionFor(file);
+const isProtected = (file) => ppc.surfaceFor(file) !== null;
+
+module.exports = {
+  SURFACES,
+  PROTECTED_GLOBS: ppc.PROTECTED_GLOBS,
+  REGISTRY_PATH: ppc.REGISTRY_PATH,
+  FLOOR,
+  SYSTEM_PERMISSIONS,
+  surfaceFor,
+  floorFor,
+  permissionFor,
+  isProtected,
+};

package/modules/governance/protected-surfaces.json

@@ -0,0 +1,80 @@
+{
+  "_readme": [
+    "The PROTECTED-SURFACE REGISTRY (ADR 0151 §4, BV1.R101). GOVERNANCE OWNS THIS DATA:",
+    "which repo paths are protected, at what rank floor, mapped to which system:true catalog",
+    "permission. It replaces the PROTECTED_GLOBS constant that used to be hardcoded in",
+    "src/bongos/permission-path-check.js.",
+    "",
+    "POLICY OWNS / SUBSTRATE ENFORCES. Editing this file re-maps POLICY. It does NOT move",
+    "enforcement into the app: the pre-push git hook, the grader pre-pass, main-audit.js,",
+    "gate-review.js and the goal-scope check all read this registry OUT OF BAND (no DB, no",
+    "server, no HTTP) and remain the enforcers (ADR 0043). A governance-tab edit can widen or",
+    "narrow the protected set and re-map a floor; it can never make the request path the",
+    "authority.",
+    "",
+    "WHY JSON IN THE REPO AND NOT A DB TABLE: the enforcers run where there is no database and",
+    "no server (a git pre-push hook on a laptop, a CI job). The registry's canonical form must",
+    "therefore be synchronously loadable from the checkout. A DB-backed override is a",
+    "governance-tab concern layered on top — never a dependency of the hook.",
+    "",
+    "SCHEMA: floor/permission at the top level are the defaults; a surface may override either.",
+    "'glob' follows the permission-path-check matcher: an exact path, a trailing '/' subtree,",
+    "'*' within one segment, '**' across segments."
+  ],
+  "version": 1,
+  "floor": "metic",
+  "permission": "path.protected.modify",
+  "surfaces": [
+    { "glob": "src/bongos/auth.js", "group": "authz", "why": "requireBuilder / requireRank definitions" },
+    { "glob": "src/bongos/db.js", "group": "authz", "why": "rank tiers, REQUIRES_RANK_TIER — the CASE edited in the SEC #863 incident" },
+    { "glob": "src/bongos/route-rank-check.js", "group": "authz", "why": "the route-gate auditor" },
+    { "glob": "src/bongos/permission-path-check.js", "group": "authz", "why": "the matcher that reads this registry (self-protect)" },
+    { "glob": "src/bongos/middleware/", "group": "authz", "why": "audit + any auth middleware" },
+    { "glob": "src/bongos/routes/", "group": "authz", "why": "routes carry the requireRank gates" },
+    { "glob": "modules/lifecycle/routes/", "group": "authz", "why": "BV1.R86: the lifecycle routes carved out of src/bongos/routes/ — the gates follow the routes" },
+    { "glob": "src/bongos/routes.js", "group": "authz", "why": "the route MOUNT table (a new ungated route lands here)" },
+    { "glob": "server.js", "group": "authz", "why": "the Express entrypoint — wires every router + host routing" },
+    { "glob": "modules/governance/", "group": "authz", "why": "the governance module (ADR 0151) — its resolver, catalog, gates AND this registry ARE the authz core; the glob is the prospective carve so CREATION is gated as strictly as edits (ADR 0086 §4)" },
+    { "glob": "modules/dev-box/boxes.js", "group": "box-access", "why": "boxScopeForRank / provision floor — decides who gets a full source clone" },
+    { "glob": "modules/dev-box/box-access.js", "group": "box-access", "why": "decideSourceAccess (rank → starter|full source)" },
+    { "glob": "modules/dev-box/box-credential.js", "group": "box-access", "why": "mints the box source credential" },
+    { "glob": "modules/grading/grader.js", "group": "pipeline", "why": "BV1.R73: grading carved to modules/grading/ — the glob follows the file" },
+    { "glob": "modules/grading/grader-workers/", "group": "pipeline", "why": "the adversarial panel (Narc/Hacker/Quality/Efficiency) — blunting these blunts the gate" },
+    { "glob": "modules/grading/grader-rubric.json", "group": "pipeline", "why": "the grader's scoring rubric (ADR 0058)" },
+    { "glob": "scripts/gds/ship.js", "group": "pipeline", "why": "the ship lifecycle driver" },
+    { "glob": "scripts/gds/confirm.js", "group": "pipeline", "why": "the confirm step" },
+    { "glob": "scripts/gds/merge-mode.js", "group": "pipeline", "why": "the manual land fallback" },
+    { "glob": "scripts/gds/ci-grade.js", "group": "pipeline", "why": "CI grade-gate driver — steers the grade check (ADR 0058)" },
+    { "glob": "scripts/gds/grade-smoke.js", "group": "pipeline", "why": "grade-smoke driver (ADR 0058)" },
+    { "glob": "scripts/gds/conductor-dispatch.js", "group": "pipeline", "why": "mid-flight grader dispatch (ADR 0058)" },
+    { "glob": "scripts/gds/main-audit.js", "group": "pipeline", "why": "the post-push audit — the authoritative substrate layer (self-protect)" },
+    { "glob": "scripts/gds/push-main.js", "group": "pipeline", "why": "the sanctioned main-push (carries the override)" },
+    { "glob": "scripts/gds/run-unit-tests.js", "group": "pipeline", "why": "the unit-gate test SELECTOR — muting tests here blunts the CI gate (ADR 0058)" },
+    { "glob": "scripts/gds/gate-review.js", "group": "pipeline", "why": "the automatic gatekeeper itself (self-protect, ADR 0058)" },
+    { "glob": "scripts/gds/setup.js", "group": "pipeline", "why": "/builder-setup — installs the pre-push hook" },
+    { "glob": "scripts/gds/install-git-hooks.js", "group": "pipeline", "why": "the hook installer (self-protect)" },
+    { "glob": "scripts/gds/hooks/", "group": "pipeline", "why": "the git hooks themselves (self-protect)" },
+    { "glob": "scripts/gds/cli-lib.js", "group": "pipeline", "why": "session/token + apiCall the gate relies on" },
+    { "glob": "scripts/migrate.sh", "group": "pipeline", "why": "applies migrations on deploy" },
+    { "glob": "scripts/deploy/", "group": "pipeline", "why": "the deploy scripts run on the droplet at deploy (ADR 0058)" },
+    { "glob": "modules/lifecycle/merge-lock.js", "group": "pipeline", "why": "BV1.R86: serializes a ship" },
+    { "glob": "modules/lifecycle/ship-preflight.js", "group": "pipeline", "why": "BV1.R86: preflights a ship" },
+    { "glob": "modules/lifecycle/github-push.js", "group": "pipeline", "why": "BV1.R86: the server-mediated branch publish (ADR 0055)" },
+    { "glob": "modules/lifecycle/conflict-resolve.js", "group": "pipeline", "why": "BV1.R86: self-heals generated-file conflicts at land time" },
+    { "glob": "modules/lifecycle/publish-reconciler.js", "group": "pipeline", "why": "BV1.R86: lands confirmed merges" },
+    { "glob": "migrations/", "group": "schema", "why": "schema migrations are never newcomer work" },
+    { "glob": "infra/", "group": "substrate", "why": "the deploy substrate" },
+    { "glob": ".github/", "group": "substrate", "why": "CI workflows (deploy-prod.yml, grade gate, secrets-scan) are the pipeline" },
+    { "glob": "CODEOWNERS", "group": "substrate", "why": "the code-owner gate list itself (ADR 0058)" },
+    { "glob": "config/deploy.json", "group": "substrate", "why": "the laptop/ci/bypass deploy switch (ADR 0058)" },
+    { "glob": "package.json", "group": "substrate", "why": "npm scripts + prepare/lifecycle hooks run during install/CI" },
+    { "glob": "package-lock.json", "group": "substrate", "why": "the resolved supply chain npm ci installs on the droplet (ADR 0058)" },
+    { "glob": ".husky/", "group": "substrate", "why": "pre-push (this gate) + pre-commit (secrets guard) — the hooks the gate is DELIVERED through (self-protect Layer 1)" },
+    { "glob": "docs/canonical-permissions.md", "group": "docs", "why": "the trust-boundary documentation" },
+    { "glob": "docs/adr/0016-trust-boundary-server-enforced-permissions.md", "group": "docs", "why": "the trust-boundary decision of record" },
+    { "glob": "docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md", "group": "docs", "why": "this gate's own ADR" },
+    { "glob": "CLAUDE.md", "group": "docs", "why": "the methodology core" },
+    { "glob": ".claude/hooks/", "group": "automation", "why": "local automation that could weaken a gate" },
+    { "glob": ".claude/settings.json", "group": "automation", "why": "local automation that could weaken a gate" }
+  ]
+}