@bongos/core 1.17.0

package/scripts/status-probe.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// External uptime prober for amazonprimea.com (incident 2026-06-03, task #565).
+//
+// WHY THIS EXISTS, AND WHY IT IS NOT src/bongos/uptime-poller.js:
+//   The in-process poller (src/bongos/uptime-poller.js) runs INSIDE the Node
+//   process on the droplet and probes 127.0.0.1. When the droplet is down,
+//   that poller is down too, so it records nothing — the outage becomes a data
+//   gap that renders as "100% up". A monitor cannot witness its own death.
+//   This script is the opposite: it runs on a GitHub-hosted runner (off our
+//   infrastructure) and probes the PUBLIC URL from the outside, exactly as a
+//   visitor would. It is the source of truth for real availability.
+//
+// WHAT IT DOES:
+//   - Probes a target URL up to N times (default 3) with a gap between tries.
+//     UP if any attempt returns HTTP 200; DOWN only if every attempt fails.
+//     The in-run retries suppress single transient blips, so a run that
+//     reports DOWN is a confirmed outage worth alerting on.
+//   - Appends the result to <dir>/history.jsonl and rewrites <dir>/status.json
+//     (a small snapshot + rolling uptime summary). These files live on the
+//     off-box `status-data` branch (see .github/workflows/status-probe.yml),
+//     so The Watch can read truthful uptime even while the droplet is dark.
+//   - Prunes history to the trailing 90 days (matches The Watch's window).
+//   - Writes `status=up|down` (+ latency, http_status) to $GITHUB_OUTPUT when
+//     run inside Actions, so the workflow can decide whether to alert.
+//
+// EXIT CODE: 0 on success regardless of up/down (the workflow owns alerting via
+//   the step output). Non-zero only on its own internal error.
+//
+// USAGE:
+//   node scripts/status-probe.mjs [--dir .] [--target https://amazonprimea.com/healthz]
+//                                 [--attempts 3] [--timeout-ms 15000] [--gap-ms 10000]
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULTS = {
+  dir: '.',
+  target: 'https://amazonprimea.com/healthz',
+  attempts: 3,
+  'timeout-ms': 15000,
+  'gap-ms': 10000,
+};
+const PRUNE_DAYS = 90;
+
+export function parseArgs(argv) {
+  const out = { ...DEFAULTS };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      if (key in DEFAULTS) out[key] = argv[++i];
+    }
+  }
+  out.attempts = Number(out.attempts);
+  out['timeout-ms'] = Number(out['timeout-ms']);
+  out['gap-ms'] = Number(out['gap-ms']);
+  return out;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// One HTTP attempt. Resolves { ok, httpStatus, latencyMs }. Never throws.
+async function attempt(target, timeoutMs) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  const start = Date.now();
+  try {
+    const res = await fetch(target, {
+      signal: ac.signal,
+      redirect: 'manual', // a 200 must come from the origin, not a redirect chain
+      headers: { 'User-Agent': 'amazonprimea-status-probe/1.0 (+github-actions)' },
+    });
+    return { ok: res.status === 200, httpStatus: res.status, latencyMs: Date.now() - start };
+  } catch (_) {
+    return { ok: false, httpStatus: null, latencyMs: null };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Probe with confirmation retries. UP if any attempt is a 200.
+async function probe({ target, attempts, timeoutMs, gapMs }) {
+  let last = { ok: false, httpStatus: null, latencyMs: null };
+  for (let i = 0; i < attempts; i++) {
+    const r = await attempt(target, timeoutMs);
+    if (r.ok) return { status: 'up', httpStatus: r.httpStatus, latencyMs: r.latencyMs, tries: i + 1 };
+    last = r;
+    if (i < attempts - 1) await sleep(gapMs);
+  }
+  return { status: 'down', httpStatus: last.httpStatus, latencyMs: last.latencyMs, tries: attempts };
+}
+
+export async function readHistory(file) {
+  if (!existsSync(file)) return [];
+  const text = await readFile(file, 'utf8');
+  const rows = [];
+  for (const line of text.split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { rows.push(JSON.parse(t)); } catch (_) { /* skip corrupt line */ }
+  }
+  return rows;
+}
+
+export function uptimePct(rows, sinceMs) {
+  const inWindow = rows.filter((r) => Date.parse(r.t) >= sinceMs);
+  if (inWindow.length === 0) return null;
+  const up = inWindow.filter((r) => r.status === 'up').length;
+  return Math.round((up / inWindow.length) * 10000) / 100; // 2 d.p.
+}
+
+async function emitGithubOutput(kv) {
+  const f = process.env.GITHUB_OUTPUT;
+  if (!f) return;
+  const lines = Object.entries(kv).map(([k, v]) => `${k}=${v}`).join('\n') + '\n';
+  await writeFile(f, lines, { flag: 'a' });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const dir = path.resolve(args.dir);
+  await mkdir(dir, { recursive: true });
+  const historyFile = path.join(dir, 'history.jsonl');
+  const statusFile = path.join(dir, 'status.json');
+
+  const result = await probe({
+    target: args.target,
+    attempts: args.attempts,
+    timeoutMs: args['timeout-ms'],
+    gapMs: args['gap-ms'],
+  });
+
+  const now = new Date();
+  const record = {
+    t: now.toISOString(),
+    status: result.status,
+    http_status: result.httpStatus,
+    latency_ms: result.latencyMs,
+    tries: result.tries,
+  };
+
+  // Append + prune to the trailing 90 days.
+  const cutoff = now.getTime() - PRUNE_DAYS * 24 * 60 * 60 * 1000;
+  const history = (await readHistory(historyFile)).filter((r) => Date.parse(r.t) >= cutoff);
+  history.push(record);
+  await writeFile(historyFile, history.map((r) => JSON.stringify(r)).join('\n') + '\n');
+
+  const dayMs = 24 * 60 * 60 * 1000;
+  const snapshot = {
+    generated_at: now.toISOString(),
+    target: args.target,
+    current: record,
+    summary: {
+      uptime_24h: uptimePct(history, now.getTime() - dayMs),
+      uptime_7d: uptimePct(history, now.getTime() - 7 * dayMs),
+      uptime_90d: uptimePct(history, now.getTime() - 90 * dayMs),
+      checks_total: history.length,
+    },
+  };
+  await writeFile(statusFile, JSON.stringify(snapshot, null, 2) + '\n');
+
+  await emitGithubOutput({
+    status: result.status,
+    http_status: result.httpStatus ?? '',
+    latency_ms: result.latencyMs ?? '',
+  });
+
+  const icon = result.status === 'up' ? '🟢' : '🔴';
+  console.log(
+    `${icon} ${result.status.toUpperCase()} — ${args.target} ` +
+    `(http=${result.httpStatus ?? 'n/a'}, latency=${result.latencyMs ?? 'n/a'}ms, tries=${result.tries})`
+  );
+  console.log(`   history: ${history.length} checks · 24h ${snapshot.summary.uptime_24h ?? 'n/a'}% · 90d ${snapshot.summary.uptime_90d ?? 'n/a'}%`);
+}
+
+// Run as a CLI only when invoked directly (not when imported by tests).
+const isMain = import.meta.url === pathToFileURL(process.argv[1] || '').href;
+if (isMain) {
+  main().catch((err) => {
+    console.error('[status-probe] internal error:', err.message);
+    process.exit(2);
+  });
+}

package/server.js

@@ -0,0 +1,212 @@
+const http = require('http');
+const path = require('path');
+const express = require('express');
+const { Server, matchMaker } = require('colyseus');
+const { WebSocketTransport } = require('@colyseus/ws-transport');
+const { isApiShapedPath, apiNotFoundBody } = require('./src/bongos/api-path-404');
+const uptimePoller = require('./src/bongos/uptime-poller');
+const moduleLoader = require('./src/module-loader/loader');
+const { mountInternalSurfaces, isStatusHost } = require('./src/bongos/serve-internal');
+const { isModuleEnabled } = require('./src/modules');
+const seams = require('./src/module-seams');
+
+const PORT = Number(process.env.PORT) || 3000;
+const HOST = process.env.HOST || '127.0.0.1';
+
+const app = express();
+app.disable('x-powered-by');
+// Behind Cloudflare → Caddy → Node. Trust the immediate proxy so
+// req.secure / x-forwarded-proto reflect reality for OAuth callbacks.
+app.set('trust proxy', 1);
+
+// All non-game surfaces — /healthz, /version, /api/gds, the Dev Box download
+// redirects, and the status + builders hosts — are served by the shared internal
+// surface module (ADR 0062 R51, task 1190). This also calls mountModuleRoutes,
+// which runs each enabled module's route factory — including the game module's,
+// which registers the game.staticRoot / game.registerRooms / game.precreateWorldRoom
+// seam ports before the code below resolves them (ADR 0083 / BV1.R49).
+// Mounted before the game tail below so /builders/* + the status host
+// short-circuit ahead of the game static middleware.
+mountInternalSurfaces(app);
+
+app.use((req, res, next) => {
+  // From here down: only the game host. Skip if request was for the status
+  // host (it should already be handled, but defense in depth).
+  if (isStatusHost(req)) return res.status(404).type('text/plain').send('not found');
+  next();
+});
+
+app.use(
+  '/vendor/phaser.min.js',
+  express.static(path.join(__dirname, 'node_modules/phaser/dist/phaser.min.js'), {
+    maxAge: '1d',
+  })
+);
+
+app.use(
+  '/vendor/colyseus.js',
+  express.static(path.join(__dirname, 'node_modules/colyseus.js/dist/colyseus.js'), {
+    maxAge: '1d',
+  })
+);
+
+// Game static files — served from the game module's public/ dir (modules/game/public/).
+// The path is provided by the game module via the game.staticRoot seam port, registered
+// by modules/game/routes/game.js when the loader runs mountModuleRoutes above.
+// If the game module is disabled (vanilla Cloud Bongos boot) these blocks are simply
+// skipped — no game assets served, no 404.html, no client JS. The platform API still
+// works via mountInternalSurfaces above.
+const _gameStaticRoot = seams.resolveOptional('game.staticRoot');
+if (_gameStaticRoot) {
+  const gamePublic = _gameStaticRoot();
+
+  // Tile-asset cache strategy (task #55 + #160 + #176).
+  //
+  // Three buckets:
+  //   1. Content-hashed atlas (atlas-<sha8>.png + atlas-<sha8>.json if any)
+  //      Filename changes with content → safe to cache forever. Marked
+  //      immutable so browsers / CF skip revalidation entirely.
+  //   2. Stable-URL files paired with bucket 1 (atlas-index.json, manifest.json,
+  //      atlas.json). URLs don't change across deploys but contents do, so
+  //      they get a short TTL — a deploy is visible within ~1 minute. atlas.json
+  //      lives here because tilePalette.js still hardcodes its URL; until the
+  //      build hashes it (idea_inbox follow-up), the short TTL is what prevents
+  //      the post-deploy "new PNG + stale frame coords" mismatch window.
+  //   3. Legacy unhashed per-tile PNGs + everything else under /assets/tiles
+  //      Short TTL (5 min) until they migrate to content-hashed names. The
+  //      old 1-day TTL is what caused the 2026-05-10 stale-atlas incident.
+  app.use(
+    '/assets/tiles',
+    express.static(path.join(gamePublic, 'assets/tiles'), {
+      setHeaders: (res, filePath) => {
+        const name = path.basename(filePath);
+        if (/^atlas-[a-f0-9]{8,}\.(png|json)$/.test(name)) {
+          res.setHeader('Cache-Control', 'public, max-age=31536000, immutable');
+        } else if (
+          name === 'atlas-index.json' ||
+          name === 'manifest.json' ||
+          name === 'atlas.json'
+        ) {
+          res.setHeader('Cache-Control', 'public, max-age=60');
+        } else {
+          res.setHeader('Cache-Control', 'public, max-age=300');
+        }
+      },
+    })
+  );
+
+  // HTML + game JS — short TTL so deploys are visible quickly. .js files in
+  // game/ are not content-hashed today (V1 shortcut), so a long TTL would
+  // compound the stale-art class of bugs into stale-code bugs.
+  app.use(
+    express.static(gamePublic, {
+      extensions: ['html'],
+      setHeaders: (res, filePath) => {
+        if (/\.(html|js|json)$/.test(filePath)) {
+          res.setHeader('Cache-Control', 'public, max-age=60');
+        } else {
+          res.setHeader('Cache-Control', 'public, max-age=300');
+        }
+      },
+    })
+  );
+}
+
+// Themed 404 for the game host. Anything that didn't resolve to an API route,
+// the status/builders hosts, or a static file lands here.
+// The status host has its own plain-text 404 above; we don't poach it.
+// API-SHAPED paths get a JSON 404 with a corrective hint — never the HTML island
+// page — so a caller that missed the /api/gds mount (curl /tasks, /gds/*, an
+// /api/* typo) gets a self-describing error instead of HTML that JSON.parse-faults
+// on the client (V4.R14 / #952). The match is broader than the old `/api/` test:
+// it also catches the bare GDS resource roots a human hits without the prefix.
+app.use((req, res) => {
+  if (isStatusHost(req)) return res.status(404).type('text/plain').send('not found');
+  res.status(404);
+  if (isApiShapedPath(req.path)) {
+    return res.json(apiNotFoundBody(req.path));
+  }
+  if (req.method === 'GET' && req.accepts('html')) {
+    res.setHeader('Cache-Control', 'public, max-age=60');
+    const gameStaticRoot = seams.resolveOptional('game.staticRoot');
+    if (gameStaticRoot) {
+      return res.sendFile(path.join(gameStaticRoot(), '404.html'));
+    }
+    return res.type('text/plain').send('404 — not found');
+  }
+  return res.type('text/plain').send('404 — you have washed ashore on the wrong island');
+});
+
+const httpServer = http.createServer(app);
+
+const gameServer = new Server({
+  transport: new WebSocketTransport({ server: httpServer }),
+});
+
+// The PRODUCT/game rooms (world + queue) — registered via the game module's seam
+// port (game.registerRooms), wired by modules/game/routes/game.js at loader mount
+// time. Only called when the game module is enabled (OTB does; vanilla skips).
+// The game-less platform entrypoint (src/platform-server.js) never constructs a
+// Colyseus server at all. The builders' hall live channel is NOT a Colyseus room —
+// it rides the SSE endpoint (src/bongos/routes/live.js, ADR 0069).
+const _registerRooms = seams.resolveOptional('game.registerRooms');
+if (_registerRooms) {
+  _registerRooms(gameServer);
+} else {
+  console.log('[game] game module disabled — no Colyseus rooms registered');
+}
+
+uptimePoller.start();
+
+// task 1134 — the server-owned publish reconciler (drives 'confirmed' tasks whose
+// branch has merged + deployed to 'shipped' on a timer, ADR 0055). CARVED into the
+// lifecycle module at BV1.R86 (ADR 0093 §1): it now starts via the loader's
+// startModulePollers (a declared poller — modules/lifecycle/pollers/publish-
+// reconciler.js), in the listen callback below alongside the Discord bot + routine
+// timers — so server.js no longer reaches into the lifecycle module to start it.
+// No-op without a push credential (local dev/tests); kill-switch via
+// PUBLISH_RECONCILER_DISABLED. Unref'd timers, best-effort — never takes the
+// game/API down.
+
+// task 1382 (ADR 0078 amendment) — server-internal routine timers (peer-vote-tally,
+// weekly, in-process; no model, no external cron). CARVED into the autonomy module
+// at BV1.R83 (ADR 0093 §1): it now starts via the loader's startModulePollers (a
+// declared poller — modules/autonomy/pollers/routine-timers.js), in the listen
+// callback below alongside the Discord bot poller. server.js is still the only
+// startModulePollers caller (not the game-less platform entrypoint), so a second
+// always-on instance can't double-run. Kill-switch ROUTINE_TIMERS_DISABLED stays.
+
+httpServer.listen(PORT, HOST, async () => {
+  console.log(`Amazonprimea listening on ${HOST}:${PORT}`);
+  // Pre-create the singleton WorldRoom so clients can use
+  // `client.join('world')` (existing-only, no auto-create on overflow). The
+  // precreate function is provided by the game module via the seam port
+  // game.precreateWorldRoom; idempotent + failure-tolerant.
+  const _precreate = seams.resolveOptional('game.precreateWorldRoom');
+  if (_precreate) {
+    await _precreate(matchMaker);
+  }
+
+  // Start each ENABLED module's web-process background pollers through the loader
+  // — module-agnostic: it requires modules/<key>/pollers/<name>.js and fires
+  // start(). The Discord bot (ADR 0033) is one such poller; a vanilla instance
+  // with discord off simply has no poller to start, and never reads a webhook/bot
+  // token. Non-blocking + failure-isolated by the loader (a poller problem must
+  // never take the game/API down) — the module-agnostic successor to the
+  // hardcoded discordBot.start() block (ADR 0083 / BV1.R47, task 1416).
+  moduleLoader.startModulePollers({}, { isEnabled: isModuleEnabled });
+});
+
+// Graceful shutdown — stop the in-process pollers, then stop each module poller
+// (e.g. close the Discord gateway socket cleanly on a systemd restart / Ctrl-C so
+// we don't leave a zombie session for Discord to reap). stopModulePollers awaits
+// each stop and isolates errors, so a stuck poller never blocks the exit (BV1.R47).
+for (const sig of ['SIGTERM', 'SIGINT']) {
+  process.on(sig, () => {
+    // The publish reconciler + routine timers now stop via
+    // moduleLoader.stopModulePollers() — the lifecycle module's publish-reconciler
+    // poller (carved BV1.R86) + the autonomy module's routine-timers poller
+    // (carved BV1.R83 / ADR 0093 §1).
+    moduleLoader.stopModulePollers().finally(() => process.exit(0));
+  });
+}

package/src/asset-version.js

@@ -0,0 +1,71 @@
+// src/asset-version.js — content-hash cache-busting for the static HTML
+// surfaces (#521). Stamps each local css/js ref's ?v= with a hash of the file's
+// content so a change always changes the URL, defeating Cloudflare's 4h browser
+// TTL override (which made hand-typed ?v= strings serve stale bytes for hours).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// Short, collision-safe content hash. 12 hex chars of sha256 is ample for
+// cache-busting (we only need "did the bytes change", not cryptographic
+// uniqueness). Returns null if the file can't be read.
+function hashFile(absPath) {
+  try {
+    const buf = fs.readFileSync(absPath);
+    return crypto.createHash('sha256').update(buf).digest('hex').slice(0, 12);
+  } catch {
+    return null;
+  }
+}
+
+// Rewrite every local css/js asset ref in `html` so its ?v= query is the
+// referenced file's content hash.
+//
+//   assetDir  — directory the urlPrefix maps to on disk (e.g. modules/hall-ui/public/)
+//   urlPrefix — the URL path that maps to assetDir (e.g. '/builders/' or '/')
+//
+// Only refs that (a) live under urlPrefix and (b) resolve to a readable file
+// are rewritten; cross-origin refs (https://fonts…), unknown files, and
+// non-css/js assets are left exactly as-is. Idempotent: an already-stamped ref
+// is re-stamped to the same value.
+function stampHtml(html, { assetDir, urlPrefix }) {
+  // Match  href="…"  or  src="…"  pointing at a .css/.js file, with an optional
+  // existing ?v=… query. The urlPath capture stops at ? or " so an existing
+  // query is dropped and replaced.
+  const re = /\b(href|src)="([^"?#]+\.(?:css|js))(?:\?[^"#]*)?(#[^"]*)?"/g;
+  return html.replace(re, (whole, attr, urlPath, frag) => {
+    if (!urlPath.startsWith(urlPrefix)) return whole;
+    const rel = urlPath.slice(urlPrefix.length);
+    // Guard against path traversal in a ref (defensive; these are our own files).
+    if (rel.includes('..')) return whole;
+    const h = hashFile(path.join(assetDir, rel));
+    if (!h) return whole;
+    return `${attr}="${urlPath}?v=${h}"${frag || ''}`;
+  });
+}
+
+// Build an in-memory map { '<basename>.html': '<stamped html string>' } for
+// every .html file in `dir`, stamping its asset refs against `urlPrefix`.
+// Called once at boot. A file that can't be read is simply omitted (the caller
+// then falls back to the on-disk static handler).
+function buildStampedHtml(dir, urlPrefix) {
+  const out = {};
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((f) => f.endsWith('.html'));
+  } catch {
+    return out;
+  }
+  for (const name of names) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, name), 'utf8');
+      out[name] = stampHtml(raw, { assetDir: dir, urlPrefix });
+    } catch {
+      // skip unreadable file
+    }
+  }
+  return out;
+}
+
+module.exports = { hashFile, stampHtml, buildStampedHtml };

package/src/bongos/CLAUDE.md

@@ -0,0 +1,64 @@
+# src/bongos/ — GDS core (agent notes)
+
+> Nested CLAUDE.md — loads on demand when you work here. Root [CLAUDE.md](../../CLAUDE.md) is the index; this is the altitude map for this directory. See [ADR 0061](../../docs/adr/<redacted>.md) for why these exist.
+
+**Purpose.** `src/bongos/` is the Game Development System — the build-methodology backend (builders, tasks, claims, credits, grading, memory, dev boxes), mounted at `/api/gds` in the same Node process as the game. This is where **server-side enforcement lives**: rank/permission gates, the ship/grade pipeline, and credit accounting all run here, never on the client. The DB is the source of truth; this code is its only authoritative writer.
+
+**Key files / public surface.**
+- `db.js` — the **RESIDUE** after the lifecycle carve (BV1.R86): builder IDENTITY + admission, RANK/status management (`setBuilderRank`/`_applyRankChangeTx`), AUTH `builder_sessions`, the social TWINS (Discord link, karma feed, `listAuditLog`, the grade-trend `builderRollingAvgGrade`), the `security_docs` store, and the Gemini-key leak. **The build state machine (tasks·claims·versions·done-when·ship) graduated to [`modules/lifecycle/db.js`](../../modules/lifecycle/CLAUDE.md)** — so the residue here is exactly the kernel identity/auth/twin slice + `db-kernel.js` (ADR 0093 §3). (The **credits/costs** slice graduated to economy; the **session_records** slice graduated to sessions.) Don't read end-to-end — `grep` for the helper name. `withTx(fn)` wraps BEGIN/COMMIT. `sealSessionLog` + `_applyRankChangeTx`(+`RANKS`/`singleRungPromotionError`) + the `gradePassCount` fragment are deliberately TWINNED with `modules/lifecycle/db.js` (ADR 0091 §2 — keep in sync).
+- **Lifecycle graduated out** → [`modules/lifecycle/`](../../modules/lifecycle/CLAUDE.md) (the build state machine — tasks · claims · versions · done-when · goals · dependencies · the claim→ship→grade→credit lifecycle · github-push + merge-lock + conflict-resolve + publish-reconciler + ship-card/preflight + version-close; the LAST + most-coupled domain, BV1.R86). Core reaches it only through the `lifecycle` kernel **port** the module registers — `routes/{public,me,builders}.js` + `cascade-dispatch.js` resolve `seams.resolveOptional('lifecycle')` for the version/ship feed, per-builder claims/grades, the Archon roster, and the task-kind classifier; the moved routes (`routes/{tasks,claims,versions,done-when,goals,dependencies,gate-approvals,analytics}.js`) mount via the loader. It **retired the last three doorway leaks** (`createTask`/`VOTABLE_TASK_STATUSES`/`tallyPeerVotes` → behind the port). As a transaction-participant it RESOLVES the `reward`+`onboarding` ports inside its claim/ship/confirm txns ([ADR 0093](../../docs/adr/<redacted>.md) §1,§3).
+- **Grading graduated out** → [`modules/grading/`](../../modules/grading/CLAUDE.md) (the quality gate: v4 adversarial worker panel Narc/Quality/Hacker/Efficiency + deterministic pre-passes + the rubric; BV1.R73). Core reaches it only through the `grade` kernel **port** — the lifecycle module's `routes/tasks.js` + core `routes/public.js` resolve `seams.resolveOptional('grade')`, never a direct require ([ADR 0091](../../docs/adr/<redacted>.md) §4, [ADR 0024](../../docs/adr/<redacted>.md)). `cascade-dispatch.js` (dormant System 3) stayed core.
+- **Economy graduated out** → [`modules/economy/`](../../modules/economy/CLAUDE.md) (credit allocation + the cost-plus/kind-multiplier model, the cost ledger + dashboard rollups, streaks, achievements, the leaderboard; BV1.R77). Core reaches it only through the `reward` kernel **port** — a **transaction-participant** port: the lifecycle (`applyGrade`/`confirmTask`/`decideOverrideRequest`/`claimTask`/`upsertSessionRecordWithReward`) keeps its state-machine SQL and the `credit_log`/`cost_log` *guards*, but resolves `seams.resolveOptional('reward')` and passes its own tx `client` for every credit/achievement WRITE; the read routes (`me.js`/`public.js`/`builders.js`/`sessions.js`) + `publish-reconciler.js` resolve the same port ([ADR 0093](../../docs/adr/<redacted>.md) §1-2). `llm-pricing.js` stays core shared LLM-cost infra (doorway leak `api.llmPricing`, like `llm-cache.js`).
+- **Ideas graduated out** → [`modules/ideas/`](../../modules/ideas/CLAUDE.md) (the `idea_inbox` capture/triage/criterion-proposal flow + the `blockers` queue; BV1.R78). The discord `#ideas` inbound reaches it only through the `ideas.capture` kernel **port** the module registers — which **retired** the `captureIdea` doorway leak ([ADR 0093](../../docs/adr/<redacted>.md) §5). `routes/public.js` keeps its **own** inline `idea_inbox`/`blockers` SELECTs (core querying a shared table with its own SQL is fine — no import, no twin).
+- **Security FEATURE graduated out** → [`modules/security/`](../../modules/security/CLAUDE.md) (red-team / vulnerability **reports** + the **bounty** payout table, rank-gated Metic+; `security.js` + `routes/reports.js`; BV1.R79). Core reaches the bounty schedule only through the `security` kernel **port** the module registers — `routes/public.js`'s `/public/bounty-table` resolves `seams.resolveOptional('security').bountyTableDetailed()`, never a direct require ([ADR 0093](../../docs/adr/<redacted>.md) §1; [02-module-map §5](../../docs/design/modular-architecture/02-module-map.md)). **<redacted> stays kernel:** `permission-path-check.js`/`route-rank-check.js` (authz) AND `routes/security.js` (the `/security/adr` threat-model reader + the Archon-only `/security/docs` exploit-detail store, backed by core `db.js` `security_docs` queries) all stayed in core.
+- **Builder-settings graduated out** → [`modules/builder-settings/`](../../modules/builder-settings/CLAUDE.md) (the per-builder PREFS domain — wandering · skill · sound · render — + builder-needs + their `db.js` slice; the five `/me/*-prefs` routes; BV1.R80). The `GET /me` aggregator (`routes/me.js`) + `cascade-dispatch.js` reach it only through the `builder-settings` kernel **port** the module registers (`seams.resolveOptional('builder-settings')` for the wandering/render/needs profile slices + the skill ceiling), never a direct require ([ADR 0093](../../docs/adr/<redacted>.md) §1). The five `skill_model_prefs`/`sound_prefs`/`behavior_prefs`/`event_sound_prefs` getter/setter pairs left `db.js`; the `builders` table + the Gemini-key columns (art-pipeline credential infra) stay core.
+- `auth.js` — GitHub Device Flow (CLI) + web OAuth → `builder_sessions`. Exports the request guards: `requireBuilder`, `requireRank`, `allowBoxScope` (box tokens are deny-by-default, [ADR 0053](../../docs/adr/0053-scoped-dev-box-session.md)), plus Discord OAuth helpers.
+- `github-push.js` — server-mediated branch publish ([ADR 0055](../../docs/adr/<redacted>.md)): box uploads a git bundle, server pushes + opens PR + auto-merges via a short-lived **GitHub App** installation token (no standing PAT). Also `mergeIfGreen`, gate commit-status helpers.
+- `routes.js` + `routes/` — **thin mounter**: each feature is a sub-router in `routes/`; adding a feature = one new file + one `.use()` line. Audit + rate-limit middleware mount first. See `routes/`'s own nested CLAUDE.md.
+- `permission-path-check.js` / `route-rank-check.js` — the pure protected-path + route-rank matchers (SEC [#863](https://example.com/builders#/task/863) / [ADR 0043](../../docs/adr/<redacted>.md)), reused by the grading module (via the doorway — `api.routeRankCheck`/`api.permissionPathCheck`), pre-push hook, and `--fit` runner.
+- **Onboarding graduated out** → [`modules/onboarding/`](../../modules/onboarding/CLAUDE.md) (admission · the server-ticked newcomer onboarding state machine · the friction analyzer · the evergreen newcomer-chore restock; `onboarding-state.js` + `onboarding.js` + `newcomer-restock.js` + `routes/access-requests.js` + `approval-broadcast.js` + its `db.js` slice; BV1.R81). The novel shape: it is the FIRST core→module port the LIFECYCLE drives — core reaches the state machine + restock only through the `onboarding` kernel **port** the module registers (`seams.resolveOptional('onboarding')` in `db.js` claim/ship, `auth.js`, `routes/me.js`/`builders.js`/`tasks.js`/`claims.js`), never a direct require ([ADR 0093](../../docs/adr/<redacted>.md) §1). The admission GATE READS (`hasInvitedAccessRequest`/`getBuilderByGithubId`) stay core `db.js` (kernel identity/admission).
+- **Sessions/BFG graduated out** → [`modules/sessions/`](../../modules/sessions/CLAUDE.md) (the `session_records` corpus + its `/sessions` data plane, the BFG cross-builder scorer, the session-pulse/stale-claim helpers; `bfg.js` + `pulse.js` + `routes/sessions.js` + its `db.js` slice; BV1.R82). Like `memory`, it registers **NO port** — core never calls back in: the ship-time session-digest write is an **HTTP POST** to the module's own `/sessions` route. Its one outward edge is the economy `reward` port it *resolves* (`seams.resolveOptional('reward')` in `db.js` `upsertSessionRecordWithReward` + `routes/sessions.js`) for the cost-plus token reward + `sumCreditsForTasks` ([ADR 0093](../../docs/adr/<redacted>.md) §1). **Stays core:** `session_logs` (the per-claim ship LOG, `sealSessionLog` — lifecycle) and `builder_sessions` (auth tokens) are NOT this domain.
+- **Autonomy/MAS graduated out** → [`modules/autonomy/`](../../modules/autonomy/CLAUDE.md) (the Multi-Agent System — the autonomy gate, the conductor/architect/run-routine CLIs, and the in-process routine timers; `routes/autonomy.js` + `pollers/routine-timers.js` + the `autonomy_runs` `db.js` slice; BV1.R83). Like `sessions`/`memory`, it registers **NO port** — core never calls back in. The cross-cutting bit: the **routine timer** (was `routineTimers.start()` in `server.js`) is now a loader-started **poller** (`contributes.pollers`), and the **precheck route** (was mounted in `routes.js`) a module route; both severed their `src/`/`server.js` import. The timer's one outward edge is the lifecycle **`tallyPeerVotes`** capability it resolves through the **doorway** (`api.tallyPeerVotes` — the SAME tx `POST /tasks/peer-votes/tally` runs; a tracked lifecycle leak until R86), never a core require ([ADR 0093](../../docs/adr/<redacted>.md) §1). **Stays core:** `tallyPeerVotes` itself (lifecycle — writes `karma_log`/`peer_votes`/`tasks`); the MAS-domain CLIs travel with the domain but stay under `scripts/gds/`.
+- `boxes.js` · `box-access.js` · `do-api.js` · `cf-tunnel.js` — per-builder cloud dev-box lifecycle, rank-gated source clawback, DigitalOcean client, and the Cloudflare named-tunnel control plane ([ADR 0031](../../docs/adr/<redacted>.md)).
+- **Discord graduated out** → [`modules/discord/`](../../modules/discord/CLAUDE.md) (bot, broadcast, role-sync, channels, bug-attachments, link/role; BV1.R47). Core reaches it only through the doorway seams — ports `discord.isLinked`/`discord.guildJoinSpec`, events `task.shipped`/`builder.role-sync-needed` — never a direct require. Discord is a mirror only, never authority ([ADR 0033](../../docs/adr/<redacted>.md)).
+- `llm-pricing.js` · `task-classifier.js` · `search-chunker.js` · `search.js` · `publish-reconciler.js` · `conflict-resolve.js` — token→USD pricing (cost-plus reward), `tasks.kind` heuristic, retrieval-layer chunker + search ([ADR 0060](../../docs/adr/0060-gds-retrieval-layer.md)), the confirmed→shipped auto-heal sweep, and (`conflict-resolve.js`, [ADR 0082](../../docs/adr/<redacted>.md)) the SERVER-side generated-file/append-index merge-conflict resolver the reconciler calls on `merge_conflict` (temp-clone merge with the `otb-regen` driver + `union`, then push; never bypasses a check).
+
+**Gotchas / invariants.**
+- **Permissions enforced server-side, per-request, no cache** ([ADR 0016](../../docs/adr/<redacted>.md)) — `requireRank`/`requireBuilder` read live `builders.rank`; editing local files grants nothing.
+- `db.js` is huge — **skim by section/grep, never read whole** (see efficiency note above). (`grader.js` graduated to `modules/grading/` — BV1.R73.)
+- Protected-path + route-rank logic is defined **once** in `permission-path-check.js` / `route-rank-check.js`; reuse the matcher, don't re-implement.
+- `routes.js` is deliberately conflict-free — feature logic goes in a `routes/` sub-router, not here.
+- `preview-server.js` is **not** here — it lives at `../preview-server.js` (game-only sandbox).
+
+<!-- BEGIN GENERATED REPO-MAP (scripts/gds/gen-repo-map.js — do not hand-edit) -->
+**Symbol skeleton (generated from the code — do not hand-edit; refresh: `node scripts/gds/gen-repo-map.js`).** Exported signatures, most-referenced first. The interpretive notes above are hand-written; this factual list is regenerated on deploy so it can't drift ([ADR 0063](../../docs/adr/<redacted>.md)).
+
+- `api-errors.js` — `envelope(codeOrError, message, details)`, `classify(code)`, `class ApiError`, `CATEGORIES`, `OVERRIDES`, `isApiError(x)`, `DEFAULT_CATEGORY`, `statusForCode(code, override)`, `categoryForCode(code)`, `isRetriable(code)`
+- `api-path-404.js` — `apiNotFoundBody(p)`, `isApiShapedPath(p)`, `apiPathHint(p)`, `GDS_ROOTS`
+- `api-prefix.js` — `API_PREFIX`, `API_VERSION`, `LEGACY_API_PREFIXES`, `VERSIONED_API_PREFIX`, `ALL_API_PREFIXES`
+- `app-pair.js` — `pairStore`, `createPairStore(opts = {})`, `normalizeCode(raw)`
+- `auth.js` — `requireBuilder(req, res, next)`, `requireRank(...allowed)`, `allowBoxScope(req, _res, next)`, `authConfigured()`, `requireBfgPrincipal(req, res, next)`, `loadDiscordBotToken()`, `requireArchonPage(req, res, next)`, `isValidDiscordUserId(id)`, `requireBuilderPage(req, res, next)`, `completeWebFlow({ code, redirectUri, userAgent })` _(+20 more)_
+- `cascade-dispatch.js` — `dispatch({ prompt, taskKind, title, description, discipline, ceiling = 'opus', expectSchema = null,…)`, `LADDER`, `startRungForTask({ taskKind, title, description } = {})`, `startRungForKind(taskKind)`, `ceilingForBuilder(builderPrefs, skillName)`, `MAX_ESCALATIONS`, `rungIndex(model)`, `shouldEscalate(result, expectSchema)`
+- `db-kernel.js` — `getBuilderById(id)`, `insertAuditLog({)`, `withTx(fn, { pool: p = pool } = {})`, `RANKS`, `LIVE_RANK_LADDER`, `createSession({ builderId, token, source, userAgent, expiresAt })`, `lookupSession(token)`, `upsertBuilder({ githubId, githubLogin, displayName, avatarUrl })`, `getBuilderByGithubId(githubId)`, `hasInvitedAccessRequest(login)` _(+3 more)_
+- `db.js` — `setBuilderRank({ builderId, newRank, actorBuilderId })`, `getDiscordLink(builderId)`, `hasCliSession(builderId)`, `recordApplause({ targetTaskId, discordUserId })`, `singleRungPromotionError(oldRank, newRank)`, `deactivateBuilder({ builderId, reason, actorBuilderId })`, `<redacted>(builderId)`, `listAuditLog({ limit = 100, offset = 0, builderId, method, surface } = {})`, `revokeAllSessionsForBuilder(builderId)`, `unlinkDiscord(builderId)` _(+11 more)_
+- `goal-scope-check.js` — `check(goalScopeModules, touches, builderRank)`, `isCovered(touch, goalGlobs)`, `protectedPathBlock(touches, builderRank)`, `scopeSubset(goalScopeModules, touches)`
+- `hierarchy-config.js` — `tier`, `hierarchy()`, `tiers`, `INSTANCE_PATH`, `DEFAULT_HIERARCHY`, `ROLE_KEYS`, `_resetForTests()`, `STANDARD_KEYS`, `loadHierarchy({ instancePath, env = process.env } = {})`, `membershipTier` _(+9 more)_
+- `live-channel.js` — `subscribe(fn)`, `CHANNEL`, `_state()`
+- `llm-cache.js` — `store(spec, { resultStdout, resultCostUsd = 0 } = {})`, `normalize(taskType, prompt)`, `makeCacheSpec({ prompt, model, task_type, scope_sha, owner_builder_id = null, ttl_ms = null } = {})`, `NORMALIZERS`, `poolReachable()`, `withCache(spec, producer)`, `computeCacheKey({ prompt, model, task_type, scope_sha } = {})`, `recordSaving(spec, { resultCostUsd = 0, hitCount = 0 } = {})`, `scopeShaFor(paths, { runner, cwd } = {})`, `stripVolatile(text)` _(+2 more)_
+- `llm-pricing.js` — `priceUsage(model, usage)`, `PRICES`, `priceModelUsage(modelUsage)`, `componentsFromModelUsage(modelUsage)`, `familyFor(model)`, `canonicalizeModelId(model)`
+- `metrics.js` — `render(p = pool)`, `HIST_BUCKETS`, `authorizeScrape(req)`, `httpMiddleware()`, `incCounter(name, help, labels = {}, by = 1)`, `collectDbGauges(p = pool)`, `metricsHandler()`, `normalizeRoute(p)`, `observeHistogram(name, help, labels, value)`, `__resetForTests()`
+- `module-scope-map.js` — `MODULE_SCOPE_MAP`, `moduleKeys()`, `scopeIncludesProtected(keys)`, `isModuleKey(key)`, `isProtected(globs)`, `MODULE_GLOBS`, `globsForModules(keys)`, `scopeForModule(key)`, `isProtectedModule(key)`, `protectedModules()`
+- `optimizer.js` — `VALID_MODES`, `DEFAULT_MAX_PARALLEL`, `optimizeSession({ builderId, mode, timeBudgetMin, maxParallel })`
+- `path-match.js` — `touchesOverlap(a, b)`, `matchOne(file, touches)`
+- `permission-path-check.js` — `PROTECTED_GLOBS`, `SPECIALTY`, `matchProtected(files)`, `checkPermissionPaths({ changedFiles, builderRank } = {})`, `globToRegExp(glob)`, `RANK_TIER`, `tierOf(rank)`, `toWorkerResult(result)`, `MIN_TIER`, `isBelowFloor(rank)`
+- `pool.js` — `instanceDbName()`
+- `repo-info.js` — `loadRepoInfo()`, `parseRemote(remote)`, `_resetCacheForTests()`
+- `route-rank-check.js` — `EXPECTED_RANKS`, `SPECIALTY`, `MODULES_DIR`, `MODULE_EXPECTED_RANKS`, `checkRouteRanks({ routesDir = ROUTES_DIR, modulesDir } = {})`, `toWorkerResult(result)`, `KNOWN_RANKS`, `WRITE_METHODS`, `classifyRank(lines, i)`, `classifyText(text)` _(+2 more)_
+- `routes.js` — `buildGdsRouter()`
+- `secret-box.js` — `VERSION`, `isConfigured()`, `decrypt(blob)`, `encrypt(plaintext)`, `provisionMasterKey(opts = {})`, `masterKeyFile()`
+- `sensitive-surfaces.js` — `isSensitive(file)`, `SENSITIVE_SURFACES`
+- `serve-internal.js` — `isBuildersHost(req)`, `mountInternalSurfaces(app)`, `isStatusHost(req)`, `injectBrandingGlobal(html, brand = clientBranding()`, `applyBrandTokens(html, brand = clientBranding()`, `injectBrandingInto(stamped, brand = clientBranding()`, `injectModuleHallWidgets(html, scripts = hallWidgetScripts({ isEnabled: isModuleEnabled })`, `themeMarkup(theme)`
+- `uptime-poller.js` — `start()`
+<!-- END GENERATED REPO-MAP -->
+
+**See also.** [ADR 0010](../../docs/adr/0010-pms-architecture.md) (GDS architecture) · [ADR 0016](../../docs/adr/<redacted>.md) (trust boundary) · [docs/architecture.md](../../docs/architecture.md) · `routes/CLAUDE.md` (HTTP surface).