@bongos/core 1.19.1072 → 1.19.1074

package/modules/dev-box/box-access.js

@@ -1,623 +0,0 @@
-// src/bongos/box-access.js — rank-gated SOURCE access for the per-builder dev box
-// (ADR 0031 §6 + open-question §9.2, task #600). Builds on #598's box lifecycle.
-//
-// THE DECISION #598 RECORDED, #600 ENFORCES
-// -----------------------------------------
-// #598 stamps a box with a `scope` ('starter' | 'full') and the `provisioned_rank`
-// at provision time, but injects NO GitHub credential — the cloud-init "logs
-// guidance rather than cloning, and #600 wires the scoped credential." This module
-// is that enforcement: it decides, on the builder's LIVE rank, whether a box may
-// reach source at all and WHICH surface it may materialize, and it drives the
-// offboarding clawback (revoke rank → de-provision box → source gone).
-//
-// THE MODEL (ADR 0016 extended from "writes are gated" to "source is gated")
-// --------------------------------------------------------------------------
-// A box holds NO permanent baked credential. At boot — and on a refresh cron —
-// the box calls GET /api/bongos/box/source-access authenticated as the builder. The
-// GDS reads the builder's LIVE rank+status (their machine cannot forge it) and
-// either DENIES (403 → the box scrubs its credential + clone) or returns a
-// scope-appropriate clone spec plus a short-lived, operator-supplied credential
-// (src/bongos/box-credential.js; the secret lives in the prod ENV, never the repo —
-// ADR 0022). Because the check is live and per-fetch, revocation is INSTANT at the
-// credential layer: demote/deactivate a builder and their next refresh 403s, even
-// before the droplet teardown (the async cleanup) runs.
-//
-// THE HONEST LIMIT (recorded in ADR 0031 §6, preserved here)
-// ----------------------------------------------------------
-// Git cannot sub-path-scope a single private repo: any read credential for the
-// repo can, in principle, read all of it, and sparse-checkout is client-side. So
-// the 'starter' surface is DEFENSE-IN-DEPTH + AUDIT + REVOCATION, NOT insider-proof
-// DRM. A 'starter' box is issued the starter credential and told to sparse-checkout
-// only the safe surface; an authorized builder who fights the tooling could still
-// over-reach. The real day-one protection is (a) full-repo credentials are gated to
-// graduation and (b) every grant/denial is audited. A hard boundary would require a
-// physically separate starter repo — supported via the provider's STARTER_REPO_URL
-// override, left as an operator choice (see box-credential.js).
-
-const {
-  DEFAULT_PROVISION_FLOOR,
-  rankMeetsBoxFloor,
-  boxScopeForRank,
-  getBoxByBuilderId,
-  recordEvent,
-} = require('./boxes');
-
-// ---------------------------------------------------------------------------
-// PURE: the scoped surface catalog
-// ---------------------------------------------------------------------------
-
-// The repo surface a 'starter' (Xenos/Thetes) box may sparse-checkout — the
-// "first tasks on a scoped surface" of ADR 0031 §9.2: the art pipeline,
-// docs/design records, the public status surface, the curiosity inbox, and
-// .devcontainer so the box can build its environment — PLUS the builder WORKFLOW
-// TOOLING (#818-followup): the /builder-* skills (.claude), the GDS CLI (scripts),
-// and the GDS lib those scripts require (src/bongos + cone-mode pulls the src/*.js
-// root files like src/db.js). Without that tooling a newcomer's box can't run
-// /builder-start|claim|ship — the whole point of being on the box.
-//
-// SANDBOX-FOR-EVERYONE (ADR 0052, task #1001 — Lars, 2026-06-13): the PRODUCT/game
-// code is now in the starter scope too — `src/world`, `src/rooms`, and the
-// `public/` game client — so EVERY box (not just Metic+ full-clone boxes) can run
-// the live sandbox (sandbox-<login>.example.com, ADR 0044). The box serves
-// the game from a GAME-ONLY entry (src/preview-server.js) that never mounts
-// /api/bongos, so the privacy boundary that matters for a PUBLIC sandbox URL is the
-// RUNTIME (what the box process exposes), NOT source exclusion. That is consistent
-// with the rest of this list: newcomers already hold the build-tooling source
-// (scripts, .claude, src/bongos — no secrets), so adding the game source changes no
-// secret posture. The locked decision (#1001) leaves the broader source-tightening
-// (idea #213) deferred and out of scope.
-//
-// STILL EXCLUDES `migrations/` — a degraded-DB preview needs no schema, and the
-// migrations are the build-pipeline internal that idea #213 would tighten. No DB
-// runs on the box anyway (ADR 0044 §1), so the game preview never reads it.
-//
-// Paths are git cone-mode sparse-checkout entries. ONLY directories — cone mode
-// rejects a file path ("'<file>' is not a directory") which aborts the whole
-// `git sparse-checkout set`. Top-level files (CLAUDE.md, README.md, package.json,
-// server.js, generative-ideas.md, …) are included AUTOMATICALLY by cone mode, so
-// they need not (and must not) be listed here. Cone mode also includes the direct
-// files of every ancestor directory — so listing src/bongos (or src/world, src/rooms)
-// pulls src/*.js root files like src/db.js + src/seats.js, which the game rooms
-// require.
-const STARTER_SPARSE_PATHS = [
-  // status surface moved to modules/status-ui/ in BV1.R84 (was public-status/).
-  '.devcontainer', 'art', 'docs', 'modules/status-ui',
-  '.claude', 'scripts', 'src/bongos',
-  // The product/game runtime so the box can serve the live sandbox (ADR 0052).
-  // The game-only entry (src/preview-server.js) registers WorldRoom + QueueRoom
-  // from src/rooms and renders src/world + the public/ client; none of it mounts
-  // /api/bongos. `public/` is the game client (NOT modules/hall-ui/public/, the hall
-  // surface carved in BV1.R85, which stays out of a starter box).
-  'src/world', 'src/rooms', 'public',
-  // infra/ carries the box's own bring-up scripts (box-heartbeat.sh,
-  // box-report-terminal.sh, the terminal + game-preview units) that
-  // box-source-fetch installs post-clone. Without it the heartbeat cron never
-  // installs, so claude_active is never reported, first_connected_at is never
-  // stamped, and the "Connect to thy dev box" onboarding step never ticks. No
-  // secrets live in infra/ (ADR 0022).
-  'infra',
-  // tests/ — so a starter box can RUN the suite for the code it holds (BV1.R99,
-  // goal 1000052; same rationale as BASE_SPARSE_PATHS). Onboarding is "bare
-  // machine → first ship", and a newcomer proving their first change needs the
-  // top-level tests/ (tests/*.mjs + helpers.mjs), which sits beside src, not in it.
-  'tests',
-];
-
-// States in which a box is (or is becoming) a running droplet that can actually
-// hold a clone. The source credential is issued ONLY to a builder whose box is in
-// one of these — a stolen token used OFF a live box, or a builder with no / parked /
-// destroyed box, gets no credential. Defense-in-depth on top of the rank gate, and
-// it aligns the model: "the BOX holds the credential", so there must be a live box.
-const SOURCE_HOLDING_STATES = ['active', 'provisioning', 'waking'];
-function boxCanHoldSource(state) {
-  return SOURCE_HOLDING_STATES.includes(state);
-}
-
-// What a given scope is allowed to materialize. Fail-closed: any unknown/missing
-// scope collapses to 'starter' (least privilege), never to 'full'.
-function cloneSpecForScope(scope) {
-  if (scope === 'full') {
-    return { scope: 'full', mode: 'full', sparsePaths: null };
-  }
-  return { scope: 'starter', mode: 'sparse', sparsePaths: [...STARTER_SPARSE_PATHS] };
-}
-
-// ---------------------------------------------------------------------------
-// PURE: the TASK-scoped surface (ADR 0148 / goal 1000051) — layered on BASE
-// ---------------------------------------------------------------------------
-
-// BASE_SPARSE_PATHS — the "pre-existing Bongos instance" every box carries no
-// matter what the builder claimed: enough for Claude to hold methodology context
-// and run the /builder-* CLI, but NONE of the product/game surface. It is the
-// NON-PRODUCT subset of STARTER_SPARSE_PATHS — .devcontainer, .claude, scripts,
-// src/bongos, docs, infra. (Top-level files like CLAUDE.md/server.js + the src/*.js
-// root files come AUTOMATICALLY via cone-mode ancestor inclusion, because src/bongos
-// is listed — see the STARTER note above.) A task's own module code (including the
-// product/game when a game task is claimed) layers on top via sparsePathsForScopeKeys.
-// This is the ADR 0148 move: scope the box to the code the claimed task needs, not
-// the whole repo.
-//
-// BEHAVIOR vs ADR 0052 (sandbox-for-everyone): BASE deliberately drops the game
-// (src/world, src/rooms, public) + art + modules/status-ui — a task-scoped box only
-// carries the live sandbox when the claimed work is scoped to the `game` module. The
-// pre-ADR-0148 "every box runs the sandbox" survives on the RANK fallback path
-// (decideSourceAccess with NO scopeKeys), so a vanilla instance without the lifecycle
-// port is unchanged.
-const BASE_SPARSE_PATHS = [
-  '.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra',
-  // tests/ — so a pulled module's build/test commands actually RUN on the box
-  // (BV1.R99, goal 1000052). Module tests live in the TOP-LEVEL tests/ dir
-  // (tests/box_*.mjs + the tests/helpers.mjs harness), NOT inside modules/<key>/,
-  // so a box holding the module source but not tests/ cannot verify a change.
-  // A cone-mode directory; it carries no product runtime, only test code.
-  'tests',
-  // clients/ — the generated bongos-client (ADR 0118) that cli-lib.js hard-imports
-  // since task 1996 made it the CLI's one HTTP client. Without it EVERY /builder-*
-  // command on the box dies at import, and the builder cannot self-heal: the
-  // workspace is a token-less blob:none clone (sparse-checkout add can't fetch)
-  // and box-source-fetch re-applies this server-computed list every tick
-  // (task 1002745). Generated ESM only, no product runtime.
-  'clients',
-  // config/ — task 1003227. Without it a box CANNOT RUN ITS OWN QUALITY GATE:
-  // `scripts/gds/fitness.js` compares against config/fitness-baselines.json, and
-  // with the file absent the ratchet used to report PASS (it read the baselines
-  // through a try/catch that returned {}, so every metric had no floor to breach).
-  // A planted 5,000-line + 94-cycle regression sailed straight through. So a boxed
-  // builder shipped believing they were clean and learned otherwise from red CI,
-  // with nothing on the box to reproduce it. The fail-closed half is fixed in
-  // fitness-ratchets.js; this is the half that lets the gate actually run.
-  //
-  // Precedent, and why the "a module glob will pull it" argument does not hold:
-  // ADR 0174 put config/government.json in the `government` key's globs and the
-  // parent-directory emission below exists precisely because `config` was not in
-  // BASE — task 1003018 was RELEASED because its box could never see the file that
-  // was its entire deliverable. BASE is the right home, not a per-module accident.
-  //
-  // Secret posture unchanged: a cone-mode directory of JSON config. The NEUTRAL
-  // packs are already public, and an instance pack (config/branding.json,
-  // config/government.json) is host content the box's own builder authors — no
-  // credentials live here (ADR 0022); those are in /etc and the box env.
-  'config',
-  // modules/lifecycle — task 1003085. BASE's whole charter is "enough to run the
-  // /builder-* CLI", and the CLI does not run without this module:
-  // scripts/gds/context-pack.js reads the task enums from
-  // modules/lifecycle/task-classifier, and context-pack is on the /builder-start
-  // AND /builder-claim paths. On a task-scoped box with NO active claim nothing
-  // put lifecycle in scope, so both commands died at import with MODULE_NOT_FOUND
-  // — and neither could be used to fix it, because a CLAIM is what fetches the
-  // module. The only way out was POST /claims by hand.
-  //
-  // This is the structural half; context-pack.js also degrades now if the module
-  // is absent for any OTHER reason. Both, deliberately: the degrade keeps the CLI
-  // alive against a future module gap, and this line is what makes the pack
-  // actually COMPLETE on every box rather than quietly reduced.
-  //
-  // Same posture as the entries above — core-domain work-tracking code, which is
-  // methodology and not product runtime, so it belongs in BASE by the same reading
-  // that put scripts/ and src/bongos/ here. No secrets; a cone-mode directory.
-  'modules/lifecycle',
-];
-
-// sparsePathsForScopeKeys — PURE. Given the module KEYS a builder's active claims
-// put in scope (from the lifecycle port `moduleScopeForActiveClaims`, R92) and the
-// doorway `moduleScopeMap` (PASSED IN by the route — box-access imports no core
-// internal), compute the git cone-mode sparse-checkout set: BASE ∪ the DIRECTORY
-// globs of every scoped module.
-//
-// Cone-mode constraint (load-bearing, ADR 0148): `git sparse-checkout set` accepts
-// ONLY directories — a file path aborts the whole set. A module's scope_modules →
-// globs come in two shapes: directory globs (trailing '/', e.g. 'modules/dev-box/')
-// and file-list globs (exact paths, e.g. the kernel key's 'src/bongos/db.js'). We
-// KEEP the directory globs (normalized to no trailing slash, matching the BASE
-// style). A FILE glob cannot be emitted as-is, so it contributes its PARENT
-// DIRECTORY instead — unless BASE or another emitted dir already covers it.
-//
-// It used to be dropped outright, on the reasoning that "every file glob in the
-// map sits under a BASE directory (src/bongos, scripts) or is a top-level file
-// cone mode pulls automatically". That was true when written and **silently
-// stopped being true**: ADR 0174 gave the `government` key the file globs
-// `config/government.json` + `config/government.neutral.json`, and `config` is
-// not in BASE. The result was a goal walled to `government` whose box could never
-// see two files inside its own scope wall — which released task 1003018 (R05 of
-// goal 1000069), whose entire deliverable was one of them. Rather than restore an
-// invariant that expires again the next time a module claims a config file, the
-// parent is emitted and the class is covered by construction.
-//
-// TRADE-OFF, stated rather than implied: the parent directory is a SUPERSET of
-// the glob — asking for `config/government.json` materializes all of `config/`.
-// The box's view is already a superset of the wall (BASE hands out `scripts`,
-// `docs` and `tests` wholesale regardless of scope), so this is consistent with
-// the existing posture, not a new concession. The WALL is unchanged: what a
-// builder may author is still decided by goal-scope-check against the globs, not
-// by what happens to be on disk.
-//
-// Top-level file globs (no '/') contribute nothing — cone mode includes root
-// files automatically. Deterministic: BASE in declared order, then the module
-// dirs sorted + deduped.
-function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
-  const base = [...BASE_SPARSE_PATHS];
-  const seen = new Set(base);
-  const extra = [];
-  // Cone mode materializes a directory and everything under it, so a path is
-  // already covered when IT or any ancestor has been emitted. This is what keeps
-  // `scripts/gds/box.js` from adding `scripts/gds` — BASE's `scripts` covers it.
-  const covered = (dir) => {
-    let p = dir;
-    for (;;) {
-      if (seen.has(p)) return true;
-      const cut = p.lastIndexOf('/');
-      if (cut < 0) return false;
-      p = p.slice(0, cut);
-    }
-  };
-  const add = (dir) => {
-    if (!dir || covered(dir)) return;
-    seen.add(dir);
-    extra.push(dir);
-  };
-  for (const key of Array.isArray(scopeKeys) ? scopeKeys : []) {
-    const entry = moduleScopeMap && typeof moduleScopeMap.scopeForModule === 'function'
-      ? moduleScopeMap.scopeForModule(key)
-      : null;
-    if (!entry || !Array.isArray(entry.globs)) continue;
-    for (const glob of entry.globs) {
-      if (typeof glob !== 'string' || !glob) continue;
-      if (glob.endsWith('/')) { add(glob.replace(/\/+$/, '')); continue; }
-      const cut = glob.lastIndexOf('/');
-      if (cut < 0) continue; // a root file — cone mode already includes it
-      add(glob.slice(0, cut));
-    }
-  }
-  extra.sort();
-  return [...base, ...extra];
-}
-
-// ---------------------------------------------------------------------------
-// PURE: builder-requested WIDENING (task 1003087 / idea 1000793)
-// ---------------------------------------------------------------------------
-
-// A builder sometimes needs a directory their task scope did not pull — to run
-// the full suite, to read a caller, to regenerate a TREE-DEPENDENT artifact. The
-// obvious move, `git sparse-checkout add <path>`, does not survive: the */10
-// source-fetch cron re-applies the SERVER-computed set and deletes the addition,
-// including WHILE A COMMAND IS RUNNING (a live suite died mid-run with
-// MODULE_NOT_FOUND that read exactly like a code bug; a box-committed
-// gen-repo-map regen off a narrow tree reds CI's freshness gate — learning
-// 1000192, which stranded PR #254).
-//
-// So the widening is recorded SERVER-side and unioned in HERE, which is what
-// makes it tick-surviving: the cron asks this endpoint for the set on every tick,
-// so it gets the union too. Nothing in the instance-owned fetch script changes —
-// which matters, because the neutral core does not ship it (ADR 0150).
-
-// Bounds. Small on purpose: this is an escape hatch for a handful of dirs, not a
-// second scope system. Over the cap the extras are dropped, not an error — a
-// truncated widen still fetches, and failing the source pull over it would be a
-// far worse trade than materializing less.
-const MAX_WIDEN_PATHS = 24;
-const MAX_WIDEN_PATH_LEN = 200;
-
-// withinAny(p, roots) — is p one of roots, or underneath one? Cone mode
-// materializes a directory and everything below it, so "already covered" and
-// "inside the allowed surface" are the same ancestor walk.
-function withinAny(p, roots) {
-  let q = p;
-  for (;;) {
-    if (roots.includes(q)) return true;
-    const cut = q.lastIndexOf('/');
-    if (cut < 0) return false;
-    q = q.slice(0, cut);
-  }
-}
-
-// normalizeWidenPath — repo-relative POSIX directory, or null when it is not one.
-//
-// This is a path that reaches `git sparse-checkout set` on a box, so it is
-// validated as INPUT rather than trusted: absolute paths, Windows drive letters,
-// '..' traversal and empty segments are all refused rather than normalized away,
-// because "cleaned up into something that still works" is how a traversal becomes
-// a shrug. Backslashes are folded to '/' first so a Windows-typed path is judged
-// on what it means, not on its separator.
-function normalizeWidenPath(raw) {
-  if (typeof raw !== 'string') return null;
-  // BACKSLASH by char code, not as a literal: this file is edited through
-  // tooling that has silently collapsed a doubled backslash before, and a
-  // separator fold that quietly stops folding is invisible until a Windows
-  // path slips through as one long segment.
-  const BACKSLASH = String.fromCharCode(92);
-  let p = raw.trim().split(BACKSLASH).join('/');
-  while (p.startsWith('./')) p = p.slice(2);
-  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
-  if (!p || p === '.' || p.length > MAX_WIDEN_PATH_LEN) return null;
-  if (p.startsWith('/') || /^[A-Za-z]:/.test(p)) return null;
-  const segs = p.split('/');
-  if (!segs.every((s) => s && s !== '.' && s !== '..' && /^[A-Za-z0-9._-]+$/.test(s))) return null;
-  return p;
-}
-
-// admissibleWidenPaths — the widen requests this builder's RANK actually permits,
-// normalized, deduped, capped and sorted.
-//
-// THIS IS THE SECURITY BOUNDARY OF THE FEATURE, so it is stated plainly: widening
-// changes what is MATERIALIZED on a box, and rank decides how much of the repo a
-// box may hold at all (ADR 0031 section 9.2 — 'full' for Metic+, the 'starter'
-// surface below that). Honoring an arbitrary widen would hand a Xenos the whole
-// tree through a convenience flag, which is a rank escalation dressed as
-// ergonomics. So:
-//   - a builder whose RANK scope is 'full' may widen anywhere (they are already
-//     entitled to the entire repo; the widen only decides what gets pulled);
-//   - anyone else may widen only INSIDE the starter surface. That is not a null
-//     grant: a task-scoped box is BASE union its modules, which is NARROWER than
-//     starter, so this is exactly the room to climb back to what their rank
-//     already allowed — and no further.
-// The authoring wall is untouched either way. What a builder may CHANGE is still
-// goal-scope-check against the module globs, never what happens to be on disk
-// (ADR 0148).
-function admissibleWidenPaths(widenPaths, rank) {
-  const unrestricted = boxScopeForRank(rank) === 'full';
-  const out = [];
-  const seen = new Set();
-  for (const raw of Array.isArray(widenPaths) ? widenPaths : []) {
-    const p = normalizeWidenPath(raw);
-    if (!p || seen.has(p)) continue;
-    if (!unrestricted && !withinAny(p, STARTER_SPARSE_PATHS)) continue;
-    seen.add(p);
-    out.push(p);
-    if (out.length >= MAX_WIDEN_PATHS) break;
-  }
-  return out.sort();
-}
-
-// withWidenPaths — union admitted widen dirs into a computed sparse set, skipping
-// any the set already covers (cone mode pulls a dir and everything under it, so
-// adding 'scripts/gds' when 'scripts' is present is noise in the git command and
-// noise in the box's scope readout). A null set is the 'full' clone — there is
-// nothing to widen into, so it passes through untouched.
-function withWidenPaths(sparsePaths, admitted) {
-  if (!Array.isArray(sparsePaths) || !admitted || admitted.length === 0) return sparsePaths;
-  const out = [...sparsePaths];
-  for (const dir of admitted) {
-    if (withinAny(dir, out)) continue;
-    out.push(dir);
-  }
-  return out;
-}
-
-// ---------------------------------------------------------------------------
-// PURE: the per-fetch access decision (consumed by GET /box/source-access)
-// ---------------------------------------------------------------------------
-
-// Decide what source access a builder gets RIGHT NOW. The route reads the live
-// rank+status from the DB and passes them in; this stays pure + unit-tested so the
-// route and any future caller enforce the SAME rule.
-//
-// Rank still governs ALLOW/DENY + the provision floor (an inactive/below-floor
-// builder is still 403, unchanged). What rank NO LONGER decides — once a claim
-// drives it — is the module BREADTH (ADR 0148 / goal 1000051). The optional
-// `scopeKeys` (from the lifecycle port `moduleScopeForActiveClaims`, R92, resolved
-// + passed by the route in R94) selects the surface, three ways:
-//   - scopeKeys is a NON-EMPTY array → TASK scope: BASE ∪ the claims' module dirs
-//     (via sparsePathsForScopeKeys + the passed-in `moduleScopeMap`).
-//   - scopeKeys is an EMPTY array     → depends on whether the builder is actually
-//     working (see `hasActiveClaims` below).
-//   - scopeKeys is ABSENT (undefined) → the pre-ADR-0148 RANK fallback (full for
-//     Metic+, else the starter sparse surface). This is the path a vanilla instance
-//     with no lifecycle port takes, and it preserves the old behavior EXACTLY — so
-//     shipping R93 before R94 wires the route changes nothing in production.
-//
-// TASK 1002729 — the empty-array case is NOT one case, it is two, and collapsing
-// them was a live defect. moduleScopeForActiveClaims returns [] both when the
-// builder holds no claim AND when they hold claims whose goals declare no
-// scope_modules (the goal wall is optional; only 13 of 46 goals on the live
-// instance declared one). Treating the second as "no scope" handed a working
-// builder a box with NO modules/ directory at all — less code than the rank
-// fallback would have given a newcomer. On the live fleet that was 247 of 248
-// source grants, including an Archon holding 7 active claims.
-//   - [] + hasActiveClaims true  → RANK fallback. The builder is working; an
-//     undeclared goal wall is a planning gap, and it must not cripple their box.
-//   - [] + hasActiveClaims false → BASE-only, as before (a genuinely unscoped box
-//     — the pre-existing Bongos instance, nothing extra). Least privilege holds.
-// `hasActiveClaims` is optional: omitted (undefined) preserves the old BASE-only
-// reading, so a caller that hasn't been taught the signal is unchanged.
-//
-// Returns one of:
-//   { allowed:false, reason:'BUILDER_INACTIVE' }
-//   { allowed:false, reason:'INSUFFICIENT_RANK', required, actual }
-//   { allowed:true,  scope, spec }
-function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, hasActiveClaims, moduleScopeMap, widenPaths } = {}) {
-  if (status && status !== 'active') {
-    return { allowed: false, reason: 'BUILDER_INACTIVE' };
-  }
-  if (!rankMeetsBoxFloor(rank, floor)) {
-    return {
-      allowed: false,
-      reason: 'INSUFFICIENT_RANK',
-      required: floor,
-      actual: rank ?? null,
-    };
-  }
-  // The builder's own widening, narrowed to what their rank already reaches
-  // (task 1003087). Computed once here so every sparse branch below unions the
-  // SAME set — a widen that applied to one scope and not another would be a
-  // surprise that only surfaces when a claim changes.
-  const widen = admissibleWidenPaths(widenPaths, rank);
-
-  // Claim-driven task scope (present → the box asks for exactly its work's code).
-  if (Array.isArray(scopeKeys)) {
-    if (scopeKeys.length > 0) {
-      const sparsePaths = withWidenPaths(sparsePathsForScopeKeys(scopeKeys, moduleScopeMap), widen);
-      return { allowed: true, scope: 'task', spec: { scope: 'task', mode: 'sparse', sparsePaths } };
-    }
-    // Empty. A builder mid-claim whose goals declare no wall gets the rank scope,
-    // NOT a stripped box — the planning gap is not theirs to pay for.
-    if (!hasActiveClaims) {
-      const sparsePaths = withWidenPaths(sparsePathsForScopeKeys([], moduleScopeMap), widen);
-      return { allowed: true, scope: 'base', spec: { scope: 'base', mode: 'sparse', sparsePaths } };
-    }
-  }
-  // No claim signal (no lifecycle port on this instance), or claims with an
-  // undeclared goal wall: the pre-ADR-0148 rank fallback.
-  const scope = boxScopeForRank(rank);
-  const spec = cloneSpecForScope(scope);
-  // 'full' carries sparsePaths null (the whole repo) — withWidenPaths passes it
-  // through, because there is no sparse set to widen INTO.
-  return { allowed: true, scope, spec: { ...spec, sparsePaths: withWidenPaths(spec.sparsePaths, widen) } };
-}
-
-// scopeMetadata — PURE. The credential-FREE projection of a source-access
-// decision, for the read-only GET /box/scope companion (BV1.R100 / goal 1000051):
-// the laptop app (and R104's proof) needs to KNOW what a box holds — which module
-// dirs, which sparse set — WITHOUT being issued the pull credential. It is computed
-// from the SAME decideSourceAccess result the real fetch uses, so the answer can
-// never drift from the actual checkout.
-//
-// `modules` reports the resolved module KEYS a task-scope pulls (the raw scopeKeys
-// from moduleScopeForActiveClaims, deduped + sorted for a stable display) — or null
-// when the decision came from the RANK fallback (scopeKeys absent), where breadth is
-// rank-driven, not module-driven, so there is no per-module list to name.
-function scopeMetadata({ decision, scopeKeys } = {}) {
-  if (!decision || !decision.allowed) return null;
-  const modules = Array.isArray(scopeKeys)
-    ? [...new Set(scopeKeys.filter((k) => typeof k === 'string'))].sort()
-    : null;
-  return {
-    scope: decision.scope,
-    mode: decision.spec ? decision.spec.mode : null,
-    modules,
-    sparse_paths: decision.spec ? decision.spec.sparsePaths : null,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// PURE: the clawback / reconcile decision (consumed by `box.js reconcile`)
-// ---------------------------------------------------------------------------
-
-// Given a box's CURRENT stored scope+state and the builder's LIVE rank+status,
-// what must the control plane do TO THE BOX ITSELF? (The credential layer is
-// already gated live on every fetch; this is the slower droplet-level cleanup.)
-//
-//   - no box (state none/destroyed)                 → 'none'   (nothing to do)
-//   - builder inactive, or rank below the floor      → 'deprovision'
-//        (the clawback: revoke rank → de-provision box → source access gone)
-//   - stored 'full' but live rank no longer Metic+   → 'deprovision'
-//        (a full box already holds the crown jewels on disk — it cannot be safely
-//         "downgraded" in place; destroy it, a fresh starter box can be provisioned)
-//   - stored 'starter' but live rank is now Metic+   → 'rescope' to 'full'
-//        (graduation: the next source-access fetch returns the full spec; the box
-//         re-clones on its refresh)
-//   - otherwise                                      → 'none'   (in sync)
-function reconcileSourceAccess({ boxScope, boxState, rank, status, floor = DEFAULT_PROVISION_FLOOR } = {}) {
-  const hasBox = boxState && boxState !== 'none' && boxState !== 'destroyed';
-  if (!hasBox) return { action: 'none', reason: 'no-box' };
-
-  if (status && status !== 'active') {
-    return { action: 'deprovision', reason: 'builder-inactive' };
-  }
-  if (!rankMeetsBoxFloor(rank, floor)) {
-    return { action: 'deprovision', reason: 'below-floor' };
-  }
-
-  const liveScope = boxScopeForRank(rank);
-  if (boxScope === 'full' && liveScope !== 'full') {
-    return { action: 'deprovision', reason: 'scope-downgrade-needs-fresh-box' };
-  }
-  if (boxScope === 'starter' && liveScope === 'full') {
-    return { action: 'rescope', reason: 'graduation', newScope: 'full' };
-  }
-  return { action: 'none', reason: 'in-sync' };
-}
-
-// ---------------------------------------------------------------------------
-// DB helpers (async; take the pg pool or a client)
-// ---------------------------------------------------------------------------
-
-// Roster of every box that currently has compute/snapshot state, joined to the
-// builder's LIVE rank+status — the input to `box.js reconcile`. Excludes 'none'
-// and 'destroyed' (nothing to reconcile). Distinct from boxes.listBoxes() because
-// reconcile MUST see `status` (a deactivated builder keeps rank='xenos' but
-// status='inactive', and the clawback turns on status, not just rank).
-async function listBoxesForReconcile(db) {
-  const { rows } = await db.query(
-    `SELECT bb.*, b.github_login, b.display_name, b.rank, b.status
-       FROM builder_boxes bb
-       JOIN builders b ON b.id = bb.builder_id
-      WHERE bb.state NOT IN ('none', 'destroyed')
-      ORDER BY bb.updated_at DESC
-      LIMIT 1000`
-  );
-  return rows;
-}
-
-// Append a source-access audit row to box_events (event vocabulary extends the
-// #598 set with: source_grant | source_deny | source_reconcile | source_rescope).
-// Thin wrapper over boxes.recordEvent so callers share ONE audit path.
-async function recordSourceEvent(db, { box, builderId, event, detail, actor }) {
-  await recordEvent(db, {
-    boxId: box.id,
-    builderId: builderId ?? box.builder_id ?? null,
-    event,
-    detail: detail ?? null,
-    actor: actor ?? null,
-  });
-}
-
-// Best-effort post-commit hook called by setBuilderRank / deactivateBuilder. Reads
-// the builder's box (if any) + the just-written live rank/status, computes the
-// reconcile action, and — when one is needed — writes a 'source_reconcile' audit
-// row so an operator (and `box.js reconcile`) has an immediate, queryable signal
-// that this rank/status change requires a box action. NEVER THROWS: it runs on its
-// own connection AFTER the rank-change transaction has committed, so a failure here
-// can never roll back the rank change (mirrors the fire-and-forget Discord broadcast).
-//
-// It does NOT itself touch DigitalOcean — the web process must never shell out to
-// the DO API (routes/box.js design); the actual deprovision/rescope is the control-
-// plane CLI's job. This is the signal + the audit trail, not the teardown.
-async function flagBoxReconcileForBuilder(db, builderId, { rank, status, floor = DEFAULT_PROVISION_FLOOR, actor = 'rank-change' } = {}) {
-  try {
-    const box = await getBoxByBuilderId(db, builderId);
-    if (!box) return { action: 'none', reason: 'no-box' };
-    const decision = reconcileSourceAccess({
-      boxScope: box.scope,
-      boxState: box.state,
-      rank,
-      status,
-      floor,
-    });
-    if (decision.action === 'none') return decision;
-    await recordSourceEvent(db, {
-      box,
-      builderId,
-      event: 'source_reconcile',
-      detail: `${decision.action}: ${decision.reason} (live rank=${rank ?? 'unknown'}, status=${status ?? 'unknown'})`,
-      actor,
-    });
-    return decision;
-  } catch (err) {
-    // Swallow — the rank change already committed; this is best-effort audit.
-    // eslint-disable-next-line no-console
-    console.error('[gds] flagBoxReconcileForBuilder (non-fatal)', err && err.message ? err.message : err);
-    return { action: 'error', reason: err && err.message ? err.message : String(err) };
-  }
-}
-
-module.exports = {
-  // pure — surface catalog
-  STARTER_SPARSE_PATHS,
-  BASE_SPARSE_PATHS, // ADR 0148 / goal 1000051 — the non-product base a task-scoped box layers on
-  SOURCE_HOLDING_STATES,
-  boxCanHoldSource,
-  cloneSpecForScope,
-  sparsePathsForScopeKeys, // ADR 0148 — BASE ∪ the claims' module dirs (cone-mode)
-  MAX_WIDEN_PATHS,         // task 1003087 — the builder-widening cap
-  normalizeWidenPath,      // task 1003087 — repo-relative dir, or null
-  admissibleWidenPaths,    // task 1003087 — the widen requests this RANK permits
-  withWidenPaths,          // task 1003087 — union a widen set into a sparse set
-  scopeMetadata, // BV1.R100 — credential-free projection for GET /box/scope
-  // pure — decisions
-  decideSourceAccess,
-  reconcileSourceAccess,
-  // db
-  listBoxesForReconcile,
-  recordSourceEvent,
-  flagBoxReconcileForBuilder,
-};