@bongos/core 1.17.0

package/tests/parallel-load.mjs

@@ -0,0 +1,402 @@
+// Parallel-load harness — N concurrent simulated "builder" sessions hammering
+// the GDS claim/ship lifecycle, to surface races under load. This is the
+// runnable test the C6 parallel-load smoke (#272) drives; #272's full
+// acceptance is a 30-min run against STAGING, which is gated on staging data
+// seeding (#262). This file is built ahead of that so it's reviewed and its
+// own accounting is proven correct before the live run. (Prep task #472.)
+//
+// Two modes:
+//   --self-test  (default when no BASE_URL): NO network. Drives the harness's
+//                collision-accounting against a deterministic in-process mock
+//                "server" whose claim semantics mirror the real DB (one active
+//                claim per task; touches-overlap → conflict). Proves the
+//                harness classifies success / 409-collision / 5xx correctly.
+//   live         (BASE_URL set): spawns `--workers N` async loops against a
+//                real GDS instance. Each loop: list claimable → claim one →
+//                simulate work → ship or release → repeat, until --duration.
+//
+// SAFETY: never point the live mode at production. It mutates real claim/task
+// state. Target staging (once #262 seeds it) or a local instance. The harness
+// refuses a BASE_URL containing "amazonprimea.com" without --i-know (the prod
+// host), so a fat-fingered run can't churn the live game's GDS.
+//
+// Usage:
+//   node tests/parallel-load.mjs                         # self-test (CI-safe)
+//   BASE_URL=https://staging.amazonprimea.com TOKEN=… \
+//     node tests/parallel-load.mjs --workers 5 --duration 1800   # live (staging)
+//
+// Exit 0 = no anomalies (no 5xx, no unexpected outcome class). Exit 1 = a
+// 5xx / race / harness self-test failure was observed.
+
+import process from 'node:process';
+
+// ---------- arg parsing ----------
+
+function arg(name, def = null) {
+  const i = process.argv.indexOf(name);
+  if (i < 0) return def;
+  const next = process.argv[i + 1];
+  return next && !next.startsWith('--') ? next : true;
+}
+
+const BASE_URL = process.env.BASE_URL || null;
+const TOKENS = (process.env.TOKENS || process.env.TOKEN || '')
+  .split(',')
+  .map((s) => s.trim())
+  .filter(Boolean);
+const WORKERS = Number(arg('--workers', 5));
+const DURATION_S = Number(arg('--duration', 60));
+const WORK_MS = Number(arg('--work-ms', 200)); // simulated per-task "work"
+const SELF_TEST = arg('--self-test', false) || !BASE_URL;
+const KNOW_PROD = arg('--i-know', false);
+// --contend: every worker targets the SAME claimable task (claimable[0]) so
+// concurrent claims race the same row — the canonical "two builders, one task"
+// case. Without it, workers spread across distinct tasks (throughput-style).
+const CONTEND = arg('--contend', false);
+
+// ---------- outcome classification ----------
+//
+// Every claim attempt lands in exactly one bucket. "collision" is the SAFE
+// outcome under contention — the server refused cleanly. "fail" (5xx or a
+// thrown/none outcome) is the anomaly we're hunting.
+
+const COLLISION_CODES = new Set([
+  'ALREADY_CLAIMED',
+  'TOUCHES_CONFLICT',
+  'DEPS_NOT_SHIPPED',
+  'rank_too_low_for_task',
+  'BATCH_TOUCHES_CONFLICT',
+]);
+
+function classifyClaim({ status, code }) {
+  if (status >= 200 && status < 300) return 'success';
+  // Every collision code the claim route emits arrives on 409 (ALREADY_CLAIMED
+  // / TOUCHES_CONFLICT / DEPS_NOT_SHIPPED) or 403 (rank_too_low_for_task), both
+  // handled here — so there's no separate code-only fallthrough.
+  if (status === 409 || (status === 403 && COLLISION_CODES.has(code))) return 'collision';
+  // 429 = the server's rate limiter shedding excess WRITE load. This is a CLEAN
+  // outcome for a parallel-safety test (the server protected itself rather than
+  // racing or 500ing), so it's its own bucket — not an anomaly.
+  if (status === 429) return 'throttled';
+  if (status >= 500) return 'server_error';
+  if (status === 400 || status === 404 || status === 401 || status === 403) return 'client_error';
+  return 'other';
+}
+
+const MAX_ANOMALIES = 200; // bound the buffer for a 30-min live run under a 5xx storm
+
+function newStats() {
+  return {
+    attempts: 0,
+    success: 0,
+    collision: 0,
+    throttled: 0,
+    server_error: 0,
+    client_error: 0,
+    other: 0,
+    releases: 0,
+    releasesThrottled: 0,
+    anomalies: [],
+    anomaliesDropped: 0,
+  };
+}
+
+function record(stats, outcome) {
+  stats.attempts++;
+  stats[outcome]++;
+}
+
+// Append an anomaly, bounded — a sustained failure during a long live run must
+// not grow the buffer without limit. Overflow is counted, not stored.
+function pushAnomaly(stats, msg) {
+  if (stats.anomalies.length < MAX_ANOMALIES) stats.anomalies.push(msg);
+  else stats.anomaliesDropped++;
+}
+
+// ---------- in-process mock server (self-test) ----------
+//
+// Mirrors the real claim invariants WITHOUT a DB: one active claim per task,
+// and touches-overlap across active claims → conflict. Concurrency is modeled
+// by interleaving async workers on one event loop, which is exactly the
+// race-accounting we want to prove the harness handles. Returns {status, code}
+// shaped like the real API error envelope.
+
+function makeMockServer(tasks) {
+  const activeByTask = new Map(); // task_id -> claimId
+  const activeTouches = new Set(); // touched paths held by active claims
+  let nextClaimId = 1;
+
+  return {
+    claimable() {
+      return tasks.filter((t) => t.status === 'ready' && !activeByTask.has(t.id));
+    },
+    async claim(taskId) {
+      const t = tasks.find((x) => x.id === taskId);
+      if (!t) return { status: 404, code: 'TASK_NOT_FOUND' };
+      if (t.status !== 'ready') return { status: 409, code: 'TASK_NOT_READY' };
+      if (activeByTask.has(taskId)) return { status: 409, code: 'ALREADY_CLAIMED' };
+      if (t.touches.some((p) => activeTouches.has(p)))
+        return { status: 409, code: 'TOUCHES_CONFLICT' };
+      const claimId = nextClaimId++;
+      activeByTask.set(taskId, claimId);
+      t.touches.forEach((p) => activeTouches.add(p));
+      t.status = 'active';
+      return { status: 201, code: null, claimId };
+    },
+    async release(taskId) {
+      const t = tasks.find((x) => x.id === taskId);
+      if (!t || !activeByTask.has(taskId)) return { status: 404, code: 'NO_CLAIM' };
+      activeByTask.delete(taskId);
+      t.touches.forEach((p) => activeTouches.delete(p));
+      t.status = 'ready';
+      return { status: 200, code: null };
+    },
+    invariantOk() {
+      // The real invariant the DB guarantees: activeTouches must be EXACTLY the
+      // union of touch-paths over all currently-active claims — no stale path
+      // left behind by a release, no path held by two active claims. Rebuild
+      // the union from scratch and compare to the live set; any mismatch (e.g.
+      // a release that forgot to drop a path, or a claim that double-counted)
+      // fails here. Also: every active task must actually be in 'active' state.
+      const expected = new Set();
+      for (const taskId of activeByTask.keys()) {
+        const t = tasks.find((x) => x.id === taskId);
+        if (!t || t.status !== 'active') return false;
+        for (const p of t.touches) {
+          if (expected.has(p)) return false; // same path held by two actives
+          expected.add(p);
+        }
+      }
+      if (expected.size !== activeTouches.size) return false;
+      for (const p of expected) if (!activeTouches.has(p)) return false;
+      return true;
+    },
+  };
+}
+
+// ---------- live HTTP client ----------
+
+async function api(method, path, token, body) {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  let data = null;
+  try {
+    data = await res.json();
+  } catch (_) {
+    /* non-JSON body */
+  }
+  return { status: res.status, code: data?.error || data?.code || null, data };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// ---------- worker loop ----------
+
+async function runWorker({ id, server, token, deadline, stats }) {
+  while (Date.now() < deadline) {
+    let claimable;
+    try {
+      if (server) {
+        claimable = server.claimable();
+      } else {
+        // GET /tasks/claimable returns { claimable: [...] }. (Other list routes
+        // use { tasks: [...] }, so accept either defensively.)
+        const cl = (await api('GET', '/api/gds/tasks/claimable', token)).data;
+        claimable = cl?.claimable ?? cl?.tasks ?? [];
+      }
+    } catch (e) {
+      pushAnomaly(stats, `worker ${id}: claimable threw ${e.message}`);
+      record(stats, 'server_error');
+      continue;
+    }
+    if (!claimable.length) {
+      await sleep(50);
+      continue;
+    }
+    // Pick a task. In --contend mode all workers target claimable[0] (race the
+    // same row → exactly-one-wins). Otherwise bias toward the same first few so
+    // workers still contend somewhat while spreading load.
+    const pick = CONTEND
+      ? claimable[0]
+      : (claimable[Math.min(id, claimable.length - 1) % claimable.length] || claimable[0]);
+
+    let res;
+    try {
+      res = server ? await server.claim(pick.id) : await api('POST', '/api/gds/claims', token, { task_id: pick.id });
+    } catch (e) {
+      pushAnomaly(stats, `worker ${id}: claim threw ${e.message}`);
+      record(stats, 'server_error');
+      continue;
+    }
+    const outcome = classifyClaim(res);
+    record(stats, outcome);
+    if (outcome === 'server_error') {
+      pushAnomaly(stats, `worker ${id}: 5xx claiming #${pick.id} (${res.status} ${res.code || ''})`);
+    }
+    if (outcome !== 'success') {
+      // Lost the race or refused — back off briefly and try another task.
+      await sleep(10);
+      continue;
+    }
+
+    // Where the claim id lives differs by mode: the mock returns it as
+    // `claimId`; the real API returns `{ claim: { id } }` (claims.js:107),
+    // which api() exposes under `.data`. Validate it's a bare positive integer
+    // before interpolating into the resolve URL — a malformed/hostile id from a
+    // misconfigured server must not be able to shape the request path.
+    const rawClaimId = server ? res.claimId : res.data?.claim?.id;
+    const claimId = /^[0-9]+$/.test(String(rawClaimId)) ? String(rawClaimId) : null;
+    if (!server && claimId === null) {
+      pushAnomaly(stats, `worker ${id}: claimed #${pick.id} but got no usable claim id (${JSON.stringify(rawClaimId)}) — cannot release`);
+      await sleep(10);
+      continue;
+    }
+
+    // Hold the claim for a simulated work window, then release it (we don't
+    // run the full ship/grade/merge chain under load — that mutates main and
+    // isn't what the claim-concurrency smoke is exercising). The real release
+    // is POST /claims/:id/resolve with outcome 'abandoned' (returns the task to
+    // ready), matching scripts/gds/release.js.
+    await sleep(WORK_MS);
+    try {
+      const rel = server
+        ? await server.release(pick.id)
+        : await api('POST', `/api/gds/claims/${claimId}/resolve`, token, { outcome: 'abandoned' });
+      if (rel.status >= 500) {
+        pushAnomaly(stats, `worker ${id}: 5xx releasing #${pick.id}`);
+        record(stats, 'server_error');
+      } else if (rel.status === 429) {
+        // Clean rate-limit shed on the release write — not an anomaly. The task
+        // stays 'active'; the stale-claim reaper / next pass handles it.
+        stats.releasesThrottled++;
+      } else if (rel.status >= 400) {
+        pushAnomaly(stats, `worker ${id}: release of #${pick.id} failed (${rel.status} ${rel.code || ''})`);
+      } else {
+        stats.releases++;
+      }
+    } catch (e) {
+      pushAnomaly(stats, `worker ${id}: release threw ${e.message}`);
+    }
+    // Invariant check only applies to the in-process mock (live mode has no
+    // local view of server state). Guard `server` FIRST so we never deref null.
+    if (server && !server.invariantOk()) {
+      pushAnomaly(stats, `INVARIANT VIOLATION after worker ${id} cycle on #${pick.id}`);
+    }
+  }
+}
+
+// ---------- report ----------
+
+function report(stats, wallMs) {
+  const tput = stats.attempts / (wallMs / 1000);
+  const collisionRate = stats.attempts ? stats.collision / stats.attempts : 0;
+  console.log('');
+  console.log('=== parallel-load report ===');
+  console.log(`mode:             ${SELF_TEST ? 'self-test (mock, no network)' : `live → ${BASE_URL}`}`);
+  console.log(`workers:          ${WORKERS}`);
+  console.log(`wall:             ${(wallMs / 1000).toFixed(1)}s`);
+  console.log(`claim attempts:   ${stats.attempts}`);
+  console.log(`  success:        ${stats.success}`);
+  console.log(`  collision(409): ${stats.collision}   (${(collisionRate * 100).toFixed(1)}% — SAFE: exactly-one-wins refusals)`);
+  console.log(`  throttled(429): ${stats.throttled}   (SAFE: rate-limiter shed excess writes)`);
+  console.log(`  client_error:   ${stats.client_error}`);
+  console.log(`  server_error:   ${stats.server_error}   <-- must be 0`);
+  console.log(`  other:          ${stats.other}`);
+  console.log(`releases:         ${stats.releases} ok, ${stats.releasesThrottled} throttled(429)`);
+  console.log(`throughput:       ${tput.toFixed(1)} claim-attempts/s`);
+  if (stats.anomalies.length) {
+    const dropped = stats.anomaliesDropped ? ` (+${stats.anomaliesDropped} dropped past the ${MAX_ANOMALIES} buffer cap)` : '';
+    console.log(`\nANOMALIES (${stats.anomalies.length}${dropped}):`);
+    for (const a of stats.anomalies.slice(0, 30)) console.log(`  - ${a}`);
+    if (stats.anomalies.length > 30) console.log(`  … ${stats.anomalies.length - 30} more`);
+  } else {
+    console.log('\nno anomalies — every claim resolved success or clean collision.');
+  }
+}
+
+// ---------- main ----------
+
+(async () => {
+  if (!SELF_TEST && !KNOW_PROD) {
+    // Parse the actual HOSTNAME — a substring match on "amazonprimea.com" /
+    // "staging." can be fooled by query strings or paths (e.g.
+    // https://amazonprimea.com/x?ref=staging.foo). Refuse the prod apex/www
+    // host; allow the staging subdomain and anything else (localhost, etc.).
+    let host = '';
+    try {
+      host = new URL(BASE_URL).hostname.toLowerCase();
+    } catch (_) {
+      console.error(`REFUSING: BASE_URL "${BASE_URL}" is not a valid URL.`);
+      process.exit(2);
+    }
+    const isProd = host === 'amazonprimea.com' || host === 'www.amazonprimea.com';
+    if (isProd) {
+      console.error(`REFUSING: BASE_URL host "${host}" is PRODUCTION. This harness mutates claim/task state.`);
+      console.error('Point it at staging (staging.amazonprimea.com, once #262 seeds it) or a local instance.');
+      console.error('If you really mean it, pass --i-know (you almost certainly do not).');
+      process.exit(2);
+    }
+  }
+
+  const stats = newStats();
+  let server = null;
+  if (SELF_TEST) {
+    // A small board with deliberate touches-overlap so collisions are forced:
+    // tasks 1 & 2 share a path → only one can be held at a time.
+    server = makeMockServer([
+      { id: 1, status: 'ready', touches: ['src/a.js'] },
+      { id: 2, status: 'ready', touches: ['src/a.js'] }, // overlaps #1
+      { id: 3, status: 'ready', touches: ['src/b.js'] },
+      { id: 4, status: 'ready', touches: ['src/c.js'] },
+      { id: 5, status: 'ready', touches: ['src/d.js'] },
+    ]);
+  } else if (!TOKENS.length) {
+    console.error('live mode needs TOKEN (or TOKENS=tok1,tok2,…) for the simulated builders.');
+    process.exit(2);
+  }
+
+  const t0 = Date.now();
+  const deadline = t0 + DURATION_S * 1000;
+  const workers = Array.from({ length: WORKERS }, (_, i) =>
+    runWorker({
+      id: i,
+      server,
+      token: TOKENS.length ? TOKENS[i % TOKENS.length] : null,
+      deadline,
+      stats,
+    })
+  );
+  await Promise.all(workers);
+  const wallMs = Date.now() - t0;
+
+  report(stats, wallMs);
+
+  // Self-test assertions: prove the harness's own accounting is correct.
+  let selfTestFail = false;
+  if (SELF_TEST) {
+    const checks = [];
+    checks.push(['saw at least one success', stats.success > 0]);
+    checks.push(['saw at least one collision (forced by overlap)', stats.collision > 0]);
+    checks.push(['zero server_error', stats.server_error === 0]);
+    checks.push(['no invariant violations', !stats.anomalies.some((a) => a.includes('INVARIANT'))]);
+    checks.push(['attempts == sum of classes',
+      stats.attempts === stats.success + stats.collision + stats.throttled + stats.client_error + stats.server_error + stats.other]);
+    console.log('\nself-test assertions:');
+    for (const [name, ok] of checks) {
+      console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}`);
+      if (!ok) selfTestFail = true;
+    }
+  }
+
+  const anomalous = stats.server_error > 0 || stats.anomalies.length > 0 || selfTestFail;
+  process.exit(anomalous ? 1 : 0);
+})().catch((e) => {
+  console.error('fatal:', e);
+  process.exit(1);
+});

package/tests/path_match.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// Unit tests for src/bongos/path-match.js — matchOne and touchesOverlap.
+// Pure, DB-free. Exits non-zero on any assertion failure.
+
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { matchOne, touchesOverlap } = require('../src/bongos/path-match.js');
+
+// ---- matchOne ----
+
+// exact match returns the entry
+assert.strictEqual(matchOne('src/bongos/db.js', ['src/bongos/db.js']), 'src/bongos/db.js');
+
+// directory prefix with trailing slash covers a file beneath it
+assert.strictEqual(matchOne('src/bongos/foo.js', ['src/bongos/']), 'src/bongos/');
+
+// bare directory name (no trailing slash) is normalised and also matches
+assert.strictEqual(matchOne('src/bongos/foo.js', ['src/bongos']), 'src/bongos');
+
+// first matching entry wins (returns the entry, not the file path)
+assert.strictEqual(matchOne('a/b.js', ['a/', 'a/b.js']), 'a/');
+
+// no match returns null
+assert.strictEqual(matchOne('src/game/map.js', ['src/bongos/']), null);
+
+// edge: empty touches array → null
+assert.strictEqual(matchOne('anything.js', []), null);
+
+// edge: null touches → null (nullish guard)
+assert.strictEqual(matchOne('anything.js', null), null);
+
+// edge: prefix similarity must not false-positive ('src/bongosx' must NOT match 'src/bongos/')
+assert.strictEqual(matchOne('src/bongosx/foo.js', ['src/bongos/']), null);
+
+// ---- touchesOverlap ----
+
+// exact-element overlap
+assert.ok(touchesOverlap(['src/bongos/db.js'], ['src/bongos/db.js']));
+
+// directory prefix covers specific file (a is dir, b is file beneath it)
+assert.ok(touchesOverlap(['src/bongos/'], ['src/bongos/db.js']));
+
+// direction is symmetric (b is dir, a is file)
+assert.ok(touchesOverlap(['src/bongos/db.js'], ['src/bongos/']));
+
+// no overlap between disjoint paths
+assert.ok(!touchesOverlap(['src/bongos/'], ['public/game/']));
+
+// edge: both empty → no overlap
+assert.ok(!touchesOverlap([], []));
+
+// edge: null inputs → no overlap (nullish guard)
+assert.ok(!touchesOverlap(null, null));
+
+// edge: bare dir name (no trailing slash) still overlaps a file inside it
+assert.ok(touchesOverlap(['src/bongos'], ['src/bongos/db.js']));
+
+// edge: prefix similarity must not false-positive
+assert.ok(!touchesOverlap(['src/bongos/'], ['src/bongosx/foo.js']));
+
+console.log('path_match: all assertions passed.');

package/tests/permission_path.mjs

@@ -0,0 +1,151 @@
+// tests/permission_path.mjs
+//
+// Unit smoke for src/bongos/permission-path-check.js — the sub-Metic
+// permission-sensitive-path gate (SEC #863, the Builder 25 incident).
+//
+// Pure module: no DB, no network. We verify (1) the glob matcher, (2) the
+// rank-floor gate, (3) the grader WorkerResult shape, and (4) — critically —
+// that the module's local RANK_TIER never drifts from db.REQUIRES_RANK_TIER.
+// That drift (thetes missing from a tier map) is the EXACT bug that let the
+// incident happen; a test owns it now.
+//
+// Run:  node tests/permission_path.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ppc = require('../src/bongos/permission-path-check.js');
+const db = require('../modules/lifecycle/db.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---------- anti-drift: the bug that caused #863 ----------
+
+t('RANK_TIER mirrors db.REQUIRES_RANK_TIER exactly (no thetes-style drift)', () => {
+  assert.deepEqual(ppc.RANK_TIER, db.REQUIRES_RANK_TIER,
+    'permission-path RANK_TIER drifted from db.REQUIRES_RANK_TIER — this is the #863 failure class');
+});
+
+t('MIN_TIER is metic and every live rank has a tier', () => {
+  assert.equal(ppc.MIN_TIER, ppc.RANK_TIER.metic);
+  for (const r of ['xenos', 'thetes', 'metic', 'archon']) {
+    assert.equal(typeof ppc.tierOf(r), 'number', `${r} must have a tier`);
+  }
+});
+
+// ---------- glob matcher ----------
+
+t('matchProtected catches exact-file protected paths', () => {
+  const hits = ppc.matchProtected(['src/bongos/db.js', 'public/game/world/terrain.js']);
+  assert.equal(hits.length, 1);
+  assert.equal(hits[0].file, 'src/bongos/db.js');
+});
+
+t('matchProtected catches subtree (trailing-slash) globs', () => {
+  const hits = ppc.matchProtected([
+    'src/bongos/routes/tasks.js',
+    'migrations/075_whatever.sql',
+    'src/bongos/middleware/audit.js',
+    '.claude/hooks/conductor.js',
+  ]);
+  assert.equal(hits.length, 4);
+});
+
+t('matchProtected normalizes Windows backslashes + ./ prefixes', () => {
+  const hits = ppc.matchProtected(['.\\src\\bongos\\auth.js']);
+  assert.equal(hits.length, 1);
+  assert.equal(hits[0].file, 'src/bongos/auth.js');
+});
+
+t('#863-followup: newly-added protected surfaces are covered (findings #3/#9/#10/#11/#12)', () => {
+  const newlyProtected = [
+    'server.js',
+    'src/bongos/routes.js',
+    'scripts/migrate.sh',
+    '.github/workflows/deploy-prod.yml',
+    'package.json',
+    '.husky/pre-push',
+    '.husky/pre-commit',
+    'modules/grading/grader-workers/hacker.js',
+    'modules/dev-box/boxes.js',
+    'modules/dev-box/box-access.js',
+    'modules/dev-box/box-credential.js',
+  ];
+  for (const f of newlyProtected) {
+    const hits = ppc.matchProtected([f]);
+    assert.equal(hits.length, 1, `${f} must be protected`);
+  }
+  // And a sub-Metic touching any of them hard-fails.
+  const r = ppc.checkPermissionPaths({ changedFiles: ['server.js'], builderRank: 'thetes' });
+  assert.equal(r.hardFail, true);
+});
+
+t('matchProtected ignores innocent game/art/UI/doc files', () => {
+  const hits = ppc.matchProtected([
+    'public/game/main.js',
+    'art/template/style_guide.md',
+    'docs/session-logs/2026-06-08-x.md',
+    'src/world/terrain.js',
+  ]);
+  assert.equal(hits.length, 0);
+});
+
+// ---------- rank-floor gate ----------
+
+t('sub-Metic (thetes) touching a protected path → hardFail blocker', () => {
+  const r = ppc.checkPermissionPaths({ changedFiles: ['src/bongos/db.js'], builderRank: 'thetes' });
+  assert.equal(r.hardFail, true);
+  assert.equal(r.ok, false);
+  assert.equal(r.findings.length, 1);
+  assert.equal(r.findings[0].severity, 'blocker');
+});
+
+t('sub-Metic (xenos) touching a protected path → hardFail', () => {
+  const r = ppc.checkPermissionPaths({ changedFiles: ['scripts/gds/ship.js'], builderRank: 'xenos' });
+  assert.equal(r.hardFail, true);
+});
+
+t('Metic touching a protected path → PASS (trusted working rank)', () => {
+  const r = ppc.checkPermissionPaths({ changedFiles: ['src/bongos/db.js'], builderRank: 'metic' });
+  assert.equal(r.ok, true);
+  assert.equal(r.hardFail, false);
+});
+
+t('Archon touching a protected path → PASS', () => {
+  const r = ppc.checkPermissionPaths({ changedFiles: ['src/bongos/auth.js', 'CLAUDE.md'], builderRank: 'archon' });
+  assert.equal(r.ok, true);
+});
+
+t('sub-Metic touching ONLY innocent files → PASS', () => {
+  const r = ppc.checkPermissionPaths({ changedFiles: ['public/game/main.js'], builderRank: 'xenos' });
+  assert.equal(r.ok, true);
+});
+
+t('unknown rank fails OPEN at this layer (audit owns the real-rank case)', () => {
+  const r = ppc.checkPermissionPaths({ changedFiles: ['src/bongos/db.js'], builderRank: undefined });
+  assert.equal(r.ok, true, 'unknown rank must not false-block Metic+/Archon at the grader layer');
+  assert.equal(r.rankKnown, false);
+});
+
+// ---------- the exact incident, reconstructed ----------
+
+t('reconstructs #863: thetes editing the rank-tier CASE in db.js is blocked', () => {
+  const r = ppc.checkPermissionPaths({
+    changedFiles: ['src/bongos/db.js', 'tests/rank_gate.mjs'],
+    builderRank: 'thetes',
+  });
+  assert.equal(r.hardFail, true);
+  const wr = ppc.toWorkerResult(r);
+  assert.equal(wr.verdict, 'fail');
+  assert.equal(wr.kind, 'permission-path');
+  assert.ok(wr.notes_md.includes('below Metic'));
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);