@bongos/core 1.17.0

package/src/bongos/path-match.js

@@ -0,0 +1,47 @@
+// Pure path-prefix matcher.
+//
+// touches[] cleanup [4/8] (task 879): relocated from the deleted drift scanner
+// (src/bongos/touches-scan.js). The scanner's predictive drift/expand apparatus is
+// gone — git merge + /merge-mode are the ground-truth collision detector — but
+// matchOne itself is a small, pure "does any path/dir-prefix entry cover this
+// file?" helper still used by the conductor for diff→claim attribution
+// (scripts/gds/conductor-dispatch.js, .claude/hooks/conductor.js). It lives
+// here, on its own, so those consumers don't depend on a scanner that no longer
+// exists.
+//
+// Match rule:
+//   - exact path match           → returns the matching entry
+//   - directory prefix match     → 'src/bongos/' (or bare 'src/bongos') covers 'src/bongos/X'
+//   - no match                   → null
+
+function matchOne(file, touches) {
+  for (const t of touches || []) {
+    if (!t) continue;
+    if (t === file) return t;
+    const dir = t.endsWith('/') ? t : t + '/';
+    if (file.startsWith(dir)) return t;
+  }
+  return null;
+}
+
+// touches[] cleanup [5/8] (task 880): the ONE canonical "do these two touches[]
+// sets overlap?" check, prefix-aware in BOTH directions. Replaces the three
+// disagreeing matchers the audit found — Postgres `&&` (exact-element) at claim
+// time + in the claimable view, JS Set-equality in batch/optimizer, dir-prefix
+// in the (now-deleted) scanner. Under `&&`, ['src/bongos/'] and ['src/bongos/db.js']
+// did NOT conflict; here they do, because one path is a directory-prefix of the
+// other. Used by claimTask / claimTasksBatch / optimizer so the planner, the
+// claim guard, and the parallel runner all agree on what "adjacent" means.
+function touchesOverlap(a, b) {
+  const A = (a || []).filter(Boolean);
+  const B = (b || []).filter(Boolean);
+  for (const ae of A) {
+    for (const be of B) {
+      // ae covers be (ae is an exact match or a dir-prefix of be) OR vice versa.
+      if (matchOne(be, [ae]) || matchOne(ae, [be])) return true;
+    }
+  }
+  return false;
+}
+
+module.exports = { matchOne, touchesOverlap };

package/src/bongos/permission-path-check.js

@@ -0,0 +1,248 @@
+// Permission-sensitive-path gate (SEC #863 — Builder 25 incident).
+//
+// WHY: ADR 0016's trust boundary is HTTP-only. A builder below Metic
+// (xenos/thetes — the sandbox + graduated-newcomer ranks) has no business
+// reading, reasoning about, or *modifying* the surfaces that DEFINE the rank
+// ladder, the ship/grade gates, the trust boundary, or the deploy path. In the
+// #863 incident a Thetes builder edited the rank-tier CASE in src/bongos/db.js and
+// shipped it straight to main. This module makes "a sub-Metic diff touches a
+// permission-sensitive path" a DETECTABLE, GATEABLE event — exactly the way
+// route-rank-check.js makes "an ungated write route" detectable.
+//
+// This module is PURE and dependency-free (no fs, no pg, no network) so it can
+// run in three places with identical logic:
+//   1. the LOCAL pre-push git hook (scripts/gds/hooks/pre-push.js) — fast,
+//      cooperative, blocks the honest builder before the push leaves the box;
+//   2. the GRADER pre-pass (modules/grading/grader.js) — folds a finding into the panel
+//      so a sub-Metic permission-path ship hard-fails the grade;
+//   3. the post-push main AUDIT (scripts/gds/main-audit.js) — the authoritative
+//      net that reads the REAL git history + REAL builder ranks server-side and
+//      flags/reverts what slipped past 1 and 2 (the only layer that catches a
+//      raw `git push origin main`, since a free-plan private repo can't forbid
+//      the push at GitHub itself).
+//
+// Layers 1 and 2 are defense-in-depth / good UX; layer 3 is the enforcement.
+
+'use strict';
+
+// Rank → tier. MUST mirror REQUIRES_RANK_TIER in src/bongos/db.js. We keep a LOCAL
+// copy (not an import) so this module stays dependency-free for the client-side
+// pre-push hook; tests/permission_path.mjs asserts the two never drift (the
+// drift that caused #863 in the first place is exactly what we refuse to
+// reintroduce here).
+const RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
+
+// The floor: a builder must be at least this tier to touch a protected path.
+// metic(3) = the first "trusted working rank" (scope/trust grants begin here).
+// xenos(1) and thetes(2) are below it — sandbox + graduated-newcomer.
+const MIN_TIER = RANK_TIER.metic; // 3
+
+// Permission-sensitive paths. A diff from a sub-Metic builder that touches ANY
+// of these is a blocker. Glob rules (see globToRegExp): a trailing '/' matches
+// the whole subtree; '**' matches across '/'; '*' matches within one segment.
+//
+// Scope rationale: the rank/permission/ship-grade/deploy machinery, DB schema
+// migrations, the server route + middleware layer that carries the gates, and
+// the trust-boundary documentation. Game/art/UI/docs work — what newcomers
+// actually build — is deliberately NOT here. Metic+ is unaffected entirely.
+const PROTECTED_GLOBS = [
+  // --- the rank ladder + authorization machinery ---
+  'src/bongos/auth.js',                 // requireBuilder / requireRank definitions
+  'src/bongos/db.js',                   // rank tiers, REQUIRES_RANK_TIER, the CASE niels edited
+  'src/bongos/route-rank-check.js',     // the route-gate auditor
+  'src/bongos/permission-path-check.js',// THIS gate (self-protect)
+  'src/bongos/middleware/',             // audit + any auth middleware
+  'src/bongos/routes/',                 // routes carry the requireRank gates
+  'modules/lifecycle/routes/',       // BV1.R86: the lifecycle routes (tasks/claims/versions/goals/deps/done-when/gate-approvals) carved out of src/bongos/routes/ — the gates follow the routes
+  'src/bongos/routes.js',               // #863-followup: the route MOUNT table (a new ungated route lands here)
+  'server.js',                       // #863-followup: the Express/Colyseus entrypoint — wires every router + host routing
+  // --- rank-gated source/box access (the crown-jewels clone decision) ---
+  // These moved into the dev-box module (BV1.R43, ADR 0083) but stay protected:
+  // they decide who gets a full source clone + mint the credential, sensitive by
+  // nature wherever they live. (routes/box.js's rank gates are covered separately
+  // by the route-rank fitness check, which scans modules/*/routes/.)
+  'modules/dev-box/boxes.js',        // #863-followup: boxScopeForRank / provision floor — decides who gets a full source clone
+  'modules/dev-box/box-access.js',   // #863-followup: decideSourceAccess (rank → starter|full source)
+  'modules/dev-box/box-credential.js', // #863-followup: mints the box source credential
+  // --- the ship / grade / deploy pipeline ---
+  'modules/grading/grader.js',       // BV1.R73: grading carved to modules/grading/ — the protected glob follows the file
+  'modules/grading/grader-workers/', // #863-followup: the adversarial panel (Narc/Hacker/Quality/Efficiency) — blunting these blunts the gate
+  'modules/grading/grader-rubric.json', // task 1139 (ADR 0058): the grader's scoring rubric — blunting it blunts the grade gate
+  'scripts/gds/ship.js',
+  'scripts/gds/confirm.js',
+  'scripts/gds/merge-mode.js',
+  'scripts/gds/ci-grade.js',         // task 1143 (ADR 0058): CI grade-gate driver — steers the grade check
+  'scripts/gds/grade-smoke.js',      // task 1143 (ADR 0058): grade-smoke driver
+  'scripts/gds/conductor-dispatch.js',// task 1143 (ADR 0058): mid-flight grader dispatch
+  'scripts/gds/main-audit.js',       // the post-push audit (self-protect)
+  'scripts/gds/push-main.js',        // the sanctioned main-push (carries the override)
+  'scripts/gds/run-unit-tests.js',   // task 1139 (ADR 0058): the unit-gate test SELECTOR — muting tests here blunts the CI gate
+  'scripts/gds/gate-review.js',      // task 1139 (ADR 0058): the automatic gatekeeper itself (self-protect)
+  'scripts/gds/setup.js',            // /builder-setup — installs the pre-push hook
+  'scripts/gds/install-git-hooks.js',// the hook installer (self-protect)
+  'scripts/gds/hooks/',              // the git hooks themselves (self-protect)
+  'scripts/gds/cli-lib.js',          // session/token + apiCall the gate relies on
+  'scripts/migrate.sh',              // #863-followup: applies migrations on deploy
+  'scripts/deploy/',                 // task 1139 (ADR 0058): the deploy scripts run on the droplet at deploy
+  // BV1.R86: the ship-pipeline libs carved to modules/lifecycle/ — the protected
+  // globs follow the files (the grading-carve precedent above). github-push is the
+  // server-mediated branch publish (ADR 0055); conflict-resolve/publish-reconciler
+  // self-heal + land merges; merge-lock/ship-preflight serialize + preflight a ship.
+  'modules/lifecycle/merge-lock.js',
+  'modules/lifecycle/ship-preflight.js',
+  'modules/lifecycle/github-push.js',
+  'modules/lifecycle/conflict-resolve.js',
+  'modules/lifecycle/publish-reconciler.js',
+  // --- schema: migrations are never newcomer work ---
+  'migrations/',
+  // --- the deploy substrate ---
+  'infra/',
+  '.github/',                        // #863-followup: CI workflows (deploy-prod.yml, grade gate, secrets-scan) are the pipeline
+  'CODEOWNERS',                      // task 1139 (ADR 0058): the code-owner gate list itself
+  'config/deploy.json',              // task 1139 (ADR 0058): the laptop/ci/bypass deploy switch
+  'package.json',                    // #863-followup: npm scripts + prepare/lifecycle hooks run during install/CI
+  'package-lock.json',               // task 1143 (ADR 0058): the resolved supply chain npm ci installs on the droplet
+  // --- the hooks the gate is DELIVERED through (self-protect Layer 1) ---
+  '.husky/',                         // #863-followup: pre-push (this gate) + pre-commit (secrets guard)
+  // --- the trust-boundary documentation + methodology core ---
+  'docs/canonical-permissions.md',
+  'docs/adr/0016-trust-boundary-server-enforced-permissions.md',
+  'docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md', // #863-followup: this fix's own ADR
+  'CLAUDE.md',
+  // --- local automation that could weaken a gate ---
+  '.claude/hooks/',
+  '.claude/settings.json',
+];
+
+const SPECIALTY =
+  'deterministic: a builder below Metic must not modify rank / permission / ship-grade / deploy / migration surfaces (ADR 0016, SEC #863)';
+
+// glob → RegExp. Supports literal paths, a trailing '/' (subtree prefix),
+// '**' (across separators) and '*' (within a segment). Anchored full-match.
+function globToRegExp(glob) {
+  // A bare directory prefix: 'src/bongos/routes/' matches everything under it.
+  if (glob.endsWith('/')) {
+    return new RegExp('^' + escapeRe(glob) + '.*$');
+  }
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    if (glob[i] === '*' && glob[i + 1] === '*') {
+      re += '.*';
+      i++;
+    } else if (glob[i] === '*') {
+      re += '[^/]*';
+    } else {
+      re += escapeRe(glob[i]);
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+const COMPILED = PROTECTED_GLOBS.map((g) => ({ glob: g, re: globToRegExp(g) }));
+
+// Normalize a path the way git reports it (forward slashes, no leading ./).
+function normalize(p) {
+  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').trim();
+}
+
+// Which of `files` are permission-sensitive? Returns [{ file, glob }].
+function matchProtected(files) {
+  const out = [];
+  for (const raw of files || []) {
+    const f = normalize(raw);
+    if (!f) continue;
+    const hit = COMPILED.find((c) => c.re.test(f));
+    if (hit) out.push({ file: f, glob: hit.glob });
+  }
+  return out;
+}
+
+function tierOf(rank) {
+  return RANK_TIER[rank] ?? null; // null = unknown rank
+}
+
+// Is this rank below the protected-path floor? Unknown ranks are treated as
+// NOT-below here (no finding) — see checkPermissionPaths for why unknown must
+// fail OPEN at the grader layer (the authoritative audit, layer 3, owns the
+// unknown/dishonest case and reads the real rank from the DB).
+function isBelowFloor(rank) {
+  const t = tierOf(rank);
+  return t !== null && t < MIN_TIER;
+}
+
+// The core check. Mirrors route-rank-check.checkRouteRanks' result shape.
+//   { ok, hardFail, builderRank, protectedHits[], findings[] }
+//
+// rankKnown=false (couldn't resolve the live rank) → no finding at this layer.
+// We do NOT flag unknown-rank here because the Archon and every Metic+ do
+// legitimate, frequent work on these files; flagging unknown would false-block
+// them. The post-push audit resolves the REAL author rank from the DB and is
+// the layer that fails-closed on the dishonest path.
+function checkPermissionPaths({ changedFiles, builderRank } = {}) {
+  const protectedHits = matchProtected(changedFiles);
+  const below = isBelowFloor(builderRank);
+  const findings = [];
+  if (below && protectedHits.length > 0) {
+    for (const h of protectedHits) {
+      findings.push({
+        severity: 'blocker',
+        file: h.file,
+        glob: h.glob,
+        summary:
+          `${h.file} is a permission-sensitive surface (matches \`${h.glob}\`). `
+          + `Builder rank '${builderRank}' is below Metic and may not modify the rank / permission / `
+          + `ship-grade / deploy / migration machinery (ADR 0016, SEC #863). `
+          + `If this change is genuinely needed, an Archon must own it.`,
+      });
+    }
+  }
+  return {
+    ok: findings.length === 0,
+    hardFail: findings.length > 0,
+    builderRank: builderRank ?? null,
+    rankKnown: tierOf(builderRank) !== null,
+    protectedHits,
+    findings,
+  };
+}
+
+// Shape as a grader WorkerResult so aggregatePanel's any-fail gate handles it
+// with no gate-logic change (identical contract to route-rank-check).
+function toWorkerResult(result) {
+  const verdict = result.hardFail ? 'fail' : 'pass';
+  const n = result.findings.length;
+  const header = verdict === 'fail'
+    ? `Permission-Path — FAIL (rank '${result.builderRank}' below Metic touched ${n} protected path(s))`
+    : `Permission-Path — PASS`;
+  const body = result.findings.map((f) => `  [${f.severity}] ${f.file} — ${f.summary}`).join('\n');
+  return {
+    kind: 'permission-path',
+    name: 'Permission-Path Check',
+    specialty: SPECIALTY,
+    verdict,
+    scores: {},
+    issues: result.findings.map((f) => ({ severity: f.severity, file: f.file, summary: f.summary })),
+    notes_md: body ? `${header}\n${body}` : header,
+    confidence: 1,
+    model: 'deterministic',
+    run_ms: 0,
+    error: null,
+  };
+}
+
+module.exports = {
+  RANK_TIER,
+  MIN_TIER,
+  PROTECTED_GLOBS,
+  SPECIALTY,
+  globToRegExp,
+  matchProtected,
+  tierOf,
+  isBelowFloor,
+  checkPermissionPaths,
+  toWorkerResult,
+};

package/src/bongos/pool.js

@@ -0,0 +1,55 @@
+'use strict';
+// src/bongos/pool.js — the GDS-owned pg connection pool (ADR 0062 §5, task 1191 / V4.R52).
+//
+// The portable core owns its own Pool so it no longer reaches into the game's src/db.js
+// (require('../db')) for a connection — the §1 cut-line. On a non-game Cloud Bongos instance src/db.js
+// does not exist; the core must still connect. The game module (src/db.js) now sources ITS pool
+// from here, so there is still exactly ONE pool to the database (host → core dependency, the
+// allowed direction).
+//
+// DB resolution (highest wins), NOT hard-defaulting to a host's DB name:
+//   DATABASE_URL  ->  PGHOST/PGDATABASE env  ->  the instance's configured db.database
+//   (config/branding.json, else config/branding.neutral.json)
+// OTB's branding pack carries db.database='amazonprimea', so prod (no DB env set) resolves to the
+// exact same socket+database it used before this carve-out — live prod is unaffected. A fresh
+// instance points this at its own DB via env or its own branding pack; the neutral starter has
+// db.database=null so a misconfigured instance fails loudly rather than silently targeting OTB.
+
+const { Pool } = require('pg');
+const fs = require('node:fs');
+const path = require('node:path');
+const { resolveCoreRoot, resolveInstanceRoot } = require('../instance-config');
+
+// Read db.database from the instance pack, else the neutral starter. Decoupled from the full
+// branding() resolver on purpose: an unrelated branding validation error must not take down the
+// DB pool, and pool.js is required very early by almost every core module.
+//
+// ADR 0108 §1: branding.json is host content (resolveInstanceRoot()); branding.neutral.json
+// ships WITH the core package (resolveCoreRoot()) — the two OPPOSITE directions the ADR calls
+// out. Both resolvers return the repo root today, so this is byte-identical for the live instance.
+function instanceDbName() {
+  for (const [root, f] of [[resolveInstanceRoot(), 'branding.json'], [resolveCoreRoot(), 'branding.neutral.json']]) {
+    try {
+      const j = JSON.parse(fs.readFileSync(path.join(root, 'config', f), 'utf8'));
+      if (j && j.db && j.db.database) return j.db.database;
+    } catch { /* missing/invalid config → fall through to env-only resolution */ }
+  }
+  return undefined;
+}
+
+let pool;
+if (process.env.DATABASE_URL) {
+  pool = new Pool({ connectionString: process.env.DATABASE_URL });
+} else {
+  pool = new Pool({
+    // Peer auth via the local Unix socket on the droplet; PG* env overrides for other environments.
+    host: process.env.PGHOST || '/var/run/postgresql',
+    database: process.env.PGDATABASE || instanceDbName(),
+  });
+}
+
+pool.on('error', (err) => {
+  console.error('[gds/pool] unexpected pool error', err);
+});
+
+module.exports = { pool, instanceDbName };

package/src/bongos/repo-info.js

@@ -0,0 +1,91 @@
+// GDS repo-info — derive the public GitHub URLs for this checkout at runtime.
+//
+// V3.R13-followup-2 (#411) extracted this from the hall's primer.js (then at
+// public-builders/primer.js; the hall surface carved to modules/hall-ui/ in BV1.R85) after
+// the V3.R12 (#236) authorship-attribution audit caught a hardcoded owner
+// identity in primer.js. The rule from CLAUDE.md: implementation code under
+// scripts/, src/, public*/, tests/, .claude/ MUST NOT hardcode references to
+// the original Archon's identity. The primer's link rewriter needs the repo
+// owner / name to build GitHub blob/tree URLs, so it has to come from
+// somewhere — this module is that somewhere, sourcing from the live git
+// remote at boot (the same place git pulls deploys from). When ownership
+// transfers, the deploy's git remote changes and the served links follow,
+// with zero code edits required.
+//
+// Cached on first call. Falls back to env vars (OTB_GITHUB_OWNER /
+// OTB_GITHUB_REPO / OTB_GITHUB_BRANCH) for environments where git isn't
+// available (e.g. a stripped-down container deploy). Returns { error } when
+// neither source resolves, so callers can degrade gracefully.
+
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+const ic = require('../instance-config');
+
+let cached = null;
+
+function parseRemote(remote) {
+  // Accept the common forms:
+  //   git@github.com:owner/repo.git
+  //   https://github.com/owner/repo.git
+  //   https://github.com/owner/repo
+  //   ssh://git@github.com/owner/repo.git
+  if (!remote) return null;
+  const m = String(remote).trim().match(/[:/]([^/:]+)\/([^/]+?)(?:\.git)?\/?$/);
+  if (!m) return null;
+  return { owner: m[1], repo: m[2] };
+}
+
+function loadFromEnv() {
+  // Per-instance env binding (R62 / task 1201): resolve the configured prefix
+  // first (CLOUDBONGOS_ on a fresh instance, OTB_ here), then legacy GDS_/OTB_.
+  const owner = ic.resolveEnv('GITHUB_OWNER');
+  const repo = ic.resolveEnv('GITHUB_REPO');
+  if (owner && repo) return { owner, repo };
+  return null;
+}
+
+function loadFromGit() {
+  try {
+    const remote = execSync('git remote get-url origin', {
+      cwd: path.resolve(__dirname, '..', '..'),
+      encoding: 'utf8',
+      timeout: 2000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return parseRemote(remote);
+  } catch (_) {
+    return null;
+  }
+}
+
+function loadRepoInfo() {
+  if (cached) return cached;
+  const branch = ic.resolveEnv('GITHUB_BRANCH') || 'main';
+  const parsed = loadFromEnv() || loadFromGit();
+  if (!parsed) {
+    cached = { error: 'no_repo_info', detail: 'git remote origin not parseable and <PREFIX>_GITHUB_OWNER/REPO unset' };
+    return cached;
+  }
+  const base = `https://github.com/${parsed.owner}/${parsed.repo}`;
+  cached = {
+    owner: parsed.owner,
+    repo: parsed.repo,
+    branch,
+    blob_base: `${base}/blob/${branch}`,
+    tree_base: `${base}/tree/${branch}`,
+  };
+  return cached;
+}
+
+// Test-only: reset the cache so unit tests can exercise different env / git
+// configurations within one process. Not exported via the public API surface
+// anywhere else.
+function _resetCacheForTests() {
+  cached = null;
+}
+
+module.exports = {
+  loadRepoInfo,
+  parseRemote,
+  _resetCacheForTests,
+};