@bongos/core 1.17.1 → 1.17.2

package/scripts/gds/cutover-codemod.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+'use strict';
+// cutover-codemod.js — rewrite HOST files' core-internal require()s to the @bongos/core
+// package subpaths at cutover (R89 / task 2159 [F1], task 2161 [F3]).
+//
+// WHY. Post-split (task 1728) a host file lives at `<instance>/…` with NO co-located `src/`.
+// Its relative core require()s — `require('../../src/module-api')` (host modules, F1),
+// `require('./src/bongos/…')` (the game entrypoint server.js, F3) — point at the DELETED
+// instance `src/` → boot crash (the 2026-07-10 rehearsal, findings F1+F3:
+// docs/reviews/2026-07-10-amazonprimea-decouple-r89-rehearsal.md). Core modules are UNAFFECTED:
+// they ship INSIDE @bongos/core, where `src/` sits next to `modules/`, so their identical
+// relative requires still resolve. The fix is to rewrite the host files' core requires to the
+// package's EXPORTED subpaths (`@bongos/core/module-api`, `@bongos/core/serve-internal`, …).
+//
+// WHY A CUTOVER TRANSFORM, NOT AN IN-PLACE MONOLITH EDIT. In the monolith `@bongos/core` is not
+// a dependency (the specifier resolves nowhere) and fitness's "modules import only
+// src/module-api.js" check would fail the rewritten form. So this must run AT CUTOVER on the
+// partitioned consumer tree — never on the committed monolith source. Mirrors the `.claude/hooks`
+// `_core-resolve.js` step (task 2139); `claude-materialize.js` rewrites `.claude/`, this rewrites
+// host-module + server.js source — the gap that rehearsal F1/F3 named.
+//
+// TWO GUARDS make it structurally impossible to corrupt the monolith:
+//   1. SCOPE ORACLE = publish-manifest. A file is rewritten only when `isPublishable(rel) === false`
+//      (host: game / art-pipeline / character-anim / demo + server.js). Core files (publishable)
+//      ship with the package and are left untouched — reusing the exact partition logic as the
+//      core-vs-host oracle, so this can never drift from what the cutover actually deletes/keeps.
+//   2. PRECONDITION = post-split consumer. Refuse unless the instance core doorway is gone
+//      (`src/module-api.js` absent at the root) — the definitive signal core was partitioned out.
+//      In the monolith that file exists, so the codemod refuses. `--force` overrides for a
+//      read-only preview only.
+//
+// The rewrite is TABLE-DRIVEN (CORE_INTERNAL_MAP), not a blind `src/X → @bongos/core/X` path swap,
+// because the core's export names do not all mirror the src layout: `src/bongos/serve-internal.js`
+// is exported as `./serve-internal`, not `./bongos/serve-internal`. The table encodes each mapping
+// so a rewrite can never produce a specifier the package doesn't export. Idempotent (a rewritten
+// `@bongos/core/*` require no longer matches the relative-into-src pattern) and quote-preserving.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { isPublishable } = require('./publish-manifest');
+
+const CORE_PKG = '@bongos/core';
+
+// <subpath after `src/` in the relative require> → <the @bongos/core export subpath>.
+// The core exports map (scripts/gds/package-core.js buildPackageJson) MUST export every value
+// here, or the rewritten require won't resolve. Kept deliberately small + explicit.
+//   F1 (task 2159): the host-module doorway.
+//   F3 (task 2161): the six core internals the game entrypoint server.js wires — added there,
+//     in lockstep with widening the core exports map, so a rewrite never outruns an export.
+const CORE_INTERNAL_MAP = {
+  // F1 — every host module imports the core doorway; the ONLY core import a module is allowed.
+  'module-api': 'module-api',
+  // F3 (task 2161) — the six core internals the game entrypoint server.js wires. Each LHS is the
+  // subpath after `src/` in server.js's relative require; each RHS is the core's EXPORTED subpath
+  // (widened in package-core.js buildPackageJson in lockstep). Note the divergence: the file at
+  // `src/bongos/serve-internal.js` is exported as `./serve-internal` (a curated name), NOT
+  // `./bongos/serve-internal` — this table encodes that so the rewrite can't emit an unexported
+  // specifier. The other five mirror their src/ path.
+  'bongos/api-path-404': 'bongos/api-path-404',
+  'bongos/uptime-poller': 'bongos/uptime-poller',
+  'bongos/serve-internal': 'serve-internal',
+  'module-loader/loader': 'module-loader/loader',
+  'modules': 'modules',
+  'module-seams': 'module-seams',
+};
+
+// require('<./ or ../…>src/<key>')  — a RELATIVE require that reaches into a `src/` dir.
+// Group 1 = quote (preserved), group 2 = the `./`/`../…` prefix, group 3 = the key after `src/`.
+// An already-rewritten `require('@bongos/core/…')` has no `../src/` and never matches → idempotent.
+const REQUIRE_RE = /require\((['"])((?:\.\.?\/)+)src\/([^'"]+)\1\)/g;
+
+// Pure. Rewrite the core-internal require()s in one file's text per `map`.
+// Returns { text, changes:[{from,to,key}], unmapped:[{key,spec}] }.
+//   - changes: requires rewritten to `@bongos/core/<mapped>`.
+//   - unmapped: relative-into-`src/` requires whose key is NOT in the table — left UNCHANGED and
+//     surfaced so a new core internal a host file starts depending on can't be silently missed
+//     (it would still crash at boot; the codemod flags "add an export + a table entry").
+function rewriteCoreRequires(text, map = CORE_INTERNAL_MAP) {
+  const changes = [];
+  const unmapped = [];
+  const out = String(text == null ? '' : text).replace(REQUIRE_RE, (whole, q, _prefix, key) => {
+    const mapped = Object.prototype.hasOwnProperty.call(map, key) ? map[key] : null;
+    if (mapped == null) {
+      unmapped.push({ key, spec: whole });
+      return whole; // leave unknown core internals untouched — never guess a specifier
+    }
+    const to = `require(${q}${CORE_PKG}/${mapped}${q})`;
+    changes.push({ from: whole, to, key });
+    return to;
+  });
+  return { text: out, changes, unmapped };
+}
+
+// A file is in scope iff the partition classifies it HOST (not shipped in the core package).
+function isHostFile(rel, isPublishableFn = isPublishable) {
+  return isPublishableFn(rel) === false;
+}
+
+// Post-split consumer signal: the instance's own core doorway is gone. In the monolith
+// `src/module-api.js` exists, so this is false and the CLI refuses (protecting the monolith).
+function looksLikeConsumer(root, { existsFn = fs.existsSync } = {}) {
+  return !existsFn(path.join(root, 'src', 'module-api.js'));
+}
+
+// Skip vendored deps, VCS metadata, the `.claude/` topology surface (materialize's job), and
+// build output. `dist/` in particular holds an extracted @bongos/core tarball whose bundled
+// core modules carry the SAME `../../src/module-api` requires — scanning it would be noise
+// (it's gitignored throwaway, never part of the consumer).
+const SKIP_DIRS = new Set(['node_modules', '.git', '.claude', 'dist', 'coverage']);
+
+// Preferred source scope: git-TRACKED *.js files. A consumer tree is a git repo at cutover, and
+// tracking is the honest "source" oracle — it excludes every gitignored build artifact (dist/,
+// coverage/, …) without enumerating them. Returns repo-relative POSIX paths, or null when git is
+// unavailable / this isn't a repo (→ caller falls back to the filesystem walk).
+function gitTrackedJsFiles(root, { runGit } = {}) {
+  const run = runGit || ((args) => execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }));
+  let out;
+  try { out = run(['ls-files', '-z', '*.js']); } catch { return null; }
+  if (typeof out !== 'string') return null;
+  return out.split('\0').filter(Boolean).map((p) => p.split(path.sep).join('/')).sort();
+}
+
+// Recursively collect *.js files under `root`, skipping SKIP_DIRS. Returns repo-relative POSIX
+// paths (what isPublishable expects). The fallback when git tracking is unavailable.
+function collectJsFiles(root, { fsImpl = fs } = {}) {
+  const found = [];
+  const walk = (absDir) => {
+    let entries;
+    try { entries = fsImpl.readdirSync(absDir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (SKIP_DIRS.has(ent.name)) continue;
+        walk(path.join(absDir, ent.name));
+      } else if (ent.isFile() && ent.name.endsWith('.js')) {
+        found.push(path.relative(root, path.join(absDir, ent.name)).split(path.sep).join('/'));
+      }
+    }
+  };
+  walk(root);
+  return found.sort();
+}
+
+function underSkipDir(rel) {
+  return SKIP_DIRS.has(rel.split('/')[0]);
+}
+
+// The candidate *.js set to consider: git-tracked source when available, else the filesystem walk.
+// SKIP_DIRS is enforced on BOTH paths — git ls-files does not know about it, and `.claude/` in
+// particular is materialize's + _core-resolve.js's domain (task 2139), never the codemod's.
+function candidateJsFiles(root, { fsImpl = fs, runGit } = {}) {
+  const tracked = gitTrackedJsFiles(root, { runGit });
+  const list = tracked && tracked.length ? tracked : collectJsFiles(root, { fsImpl });
+  return list.filter((rel) => !underSkipDir(rel));
+}
+
+// Plan the codemod over a consumer `root`: which host files change, and any unmapped core requires.
+// Pure-ish (reads disk via injectable deps for tests). Does NOT write.
+function planCodemod({ root, fsImpl = fs, runGit, isPublishableFn = isPublishable, map = CORE_INTERNAL_MAP } = {}) {
+  const files = [];
+  const unmapped = [];
+  for (const rel of candidateJsFiles(root, { fsImpl, runGit })) {
+    if (!isHostFile(rel, isPublishableFn)) continue; // core file → ships with the package, leave it
+    let raw;
+    try { raw = fsImpl.readFileSync(path.join(root, rel), 'utf8'); } catch { continue; }
+    const res = rewriteCoreRequires(raw, map);
+    if (res.unmapped.length) for (const u of res.unmapped) unmapped.push({ rel, ...u });
+    if (res.changes.length) files.push({ rel, changes: res.changes, newText: res.text });
+  }
+  return { files, unmapped };
+}
+
+// ---- CLI -------------------------------------------------------------------
+function parseArgs(argv) {
+  const a = { root: process.cwd(), apply: false, force: false };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root') a.root = argv[++i];
+    else if (argv[i] === '--apply') a.apply = true;
+    else if (argv[i] === '--force') a.force = true;
+  }
+  return a;
+}
+
+function main(argv = process.argv.slice(2), { log = console.log, err = console.error } = {}) {
+  const args = parseArgs(argv);
+  const root = path.resolve(args.root);
+
+  if (!looksLikeConsumer(root) && !args.force) {
+    err(`[cutover-codemod] REFUSING: ${path.join(root, 'src/module-api.js')} still exists — this looks like the monolith,`);
+    err('  not a post-split consumer. This codemod is a CUTOVER transform and must not edit the monolith');
+    err('  (there @bongos/core is not a dep and fitness would reject the rewrite). Run it after the partition,');
+    err('  or pass --force for a read-only preview only.');
+    return 2;
+  }
+
+  const plan = planCodemod({ root });
+
+  for (const u of plan.unmapped) {
+    err(`[cutover-codemod] WARNING ${u.rel}: unmapped core-internal require ${u.spec} — add a CORE_INTERNAL_MAP`);
+    err(`  entry + a matching core export before cutover, or this require will crash at boot.`);
+  }
+
+  if (!plan.files.length) {
+    log('[cutover-codemod] no host files need rewriting (already converted, or none present).');
+    return 0;
+  }
+
+  const verb = args.apply ? 'rewrote' : 'would rewrite';
+  for (const f of plan.files) {
+    log(`[cutover-codemod] ${verb} ${f.rel} (${f.changes.length} require${f.changes.length === 1 ? '' : 's'}):`);
+    for (const c of f.changes) log(`    ${c.from}  →  ${c.to}`);
+    if (args.apply) fs.writeFileSync(path.join(root, f.rel), f.newText);
+  }
+
+  const total = plan.files.reduce((n, f) => n + f.changes.length, 0);
+  if (args.apply) {
+    log(`[cutover-codemod] ✓ rewrote ${total} require(s) across ${plan.files.length} host file(s).`);
+  } else {
+    log(`[cutover-codemod] dry-run: ${total} require(s) across ${plan.files.length} host file(s). Re-run with --apply to write.`);
+  }
+  return 0;
+}
+
+module.exports = {
+  CORE_PKG,
+  CORE_INTERNAL_MAP,
+  REQUIRE_RE,
+  rewriteCoreRequires,
+  isHostFile,
+  looksLikeConsumer,
+  gitTrackedJsFiles,
+  collectJsFiles,
+  candidateJsFiles,
+  planCodemod,
+  parseArgs,
+  main,
+};
+
+if (require.main === module) {
+  process.exit(main());
+}

package/scripts/gds/fitness.js

@@ -1170,6 +1170,59 @@ function checkCoreRequiresExcludedConfig() {
   };
 }
 
+// ============================================================================
+// Check 16b — core code must not require an instance-EXCLUDED module (task 2135)
+// ============================================================================
+//
+// Sibling of Check 16 for the code→MODULE class. A publishable core file that
+// require()s a boundary-EXCLUDED module (modules/game, modules/art-pipeline,
+// modules/character-anim, …) throws MODULE_NOT_FOUND once that module lives in the
+// consumer's instance repo rather than the core package (R89 split). The cure is
+// either to reclassify the module INTO core (if it belongs there — e.g. provisioning,
+// sibling of dev-box) or to exclude the requiring file with the feature it serves
+// (art tooling). Catches BOTH require forms: a direct literal
+// require('../modules/<key>/…') AND a require(path.join(<root>, 'modules/<key>/…')).
+// Only an EXCLUDED module required from a PUBLISHABLE file is a violation; requiring a
+// publishable (core) module is fine, and the loader's DYNAMIC dispatch
+// (path.join(dir,'routes',rk) — no literal modules/<key>/ string) is invisible here.
+const MODULE_PATH_IN_STRING_RE = /['"](?:[^'"]*\/)?modules\/([a-z0-9][a-z0-9-]*)\/[^'"]*['"]/g;
+
+function checkCoreRequiresExcludedModule() {
+  const { isPublishable } = require('./publish-manifest');
+  const violations = [];
+  const seen = new Set();
+  const allAbs = [
+    ...['src', 'scripts'].flatMap((d) => walkJs(path.join(CORE_ROOT, d))),
+    ...walkJsAllRoots('modules'),
+  ];
+  for (const abs of allAbs) {
+    const relFile = rel(abs);
+    if (seen.has(relFile)) continue;
+    seen.add(relFile);
+    if (!isPublishable(relFile)) continue; // only CORE (publishable) code can crash a vanilla boot
+    for (const raw of fs.readFileSync(abs, 'utf8').split('\n')) {
+      const trimmed = raw.trim();
+      if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/*')) continue;
+      if (!/require\s*\(/.test(raw)) continue; // only lines that actually require()
+      let m;
+      MODULE_PATH_IN_STRING_RE.lastIndex = 0;
+      while ((m = MODULE_PATH_IN_STRING_RE.exec(raw))) {
+        const key = m[1];
+        if (isPublishable(`modules/${key}/module.json`)) continue; // requiring a CORE module is fine
+        violations.push(`${relFile} → require(...'modules/${key}/…') pulls in an instance-EXCLUDED module — reclassify it into core (if it belongs there) or exclude ${relFile} with the feature it serves, so a fresh core boots (task 2135).`);
+      }
+    }
+  }
+  return {
+    name: 'core never requires an excluded module (task 2135)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: "a publishable src/·scripts/·modules/ .js must not require('…modules/<key>/…') when that module is boundary-excluded — MODULE_NOT_FOUND post-split (R89).",
+  };
+}
+
 // ============================================================================
 // Check 17 — no route hand-rolls a FLAT error (BV1 R03 / task 1990 / ADR 0116)
 // ============================================================================
@@ -1360,6 +1413,7 @@ const CHECKS = [
   checkKernelPromptsNoHardcodedIdentity, // BV1.R76 — kernel prompts read identity from branding()
   checkHallSectionRegistry,
   checkCoreRequiresExcludedConfig, // task 1824 — core→instance-config require guard
+  checkCoreRequiresExcludedModule, // Check 16b — task 2135: core→excluded-module require guard (R89 split)
   checkErrorEnvelope, // Check 17 — BV1 R03 / task 1990: no route hand-rolls a flat error (ADR 0116)
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
 ];

package/scripts/gds/init.js

@@ -133,7 +133,13 @@ const INSTANCE_MIGRATE_SCRIPT = `bash ${INSTANCE_CORE_PKG_DIR}/scripts/migrate.s
 // standalone instance runs. Preserves any pre-existing fields + scripts (fills only what
 // is missing); greenfield OWNS the core dep, so it is always (re)set to `coreDep`. Never
 // spawns npm — generating the lockfile is a separate imperative step in main().
-function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', coreDep } = {}) {
+// `moduleDeps` (ADR 0138 / task 2160): the merged external npm deps of the modules this
+// instance ENABLES. @bongos/core ships lean (express+pg, ADR 0108), so a bundled module that
+// needs more (e.g. discord → discord.js) declares it in its module.json `dependencies`, and the
+// consumer's package.json must carry it or boot crashes on the missing module (rehearsal F2).
+// Precedence: module deps FILL gaps, an explicit pre-existing pin WINS over them, @bongos/core
+// is always (re)set. With no moduleDeps this is byte-identical to before.
+function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', coreDep, moduleDeps } = {}) {
   const dep = coreDep || coreDepRange();
   const pkg = isObj(existing) ? { ...existing } : {};
   if (!pkg.name) pkg.name = name;
@@ -141,10 +147,37 @@ function buildInstancePackageJson(existing, { name = 'cloudbongos-instance', cor
   pkg.scripts = { ...(isObj(pkg.scripts) ? pkg.scripts : {}) };
   if (!pkg.scripts.start) pkg.scripts.start = INSTANCE_START_SCRIPT;
   if (!pkg.scripts.migrate) pkg.scripts.migrate = INSTANCE_MIGRATE_SCRIPT;
-  pkg.dependencies = { ...(isObj(pkg.dependencies) ? pkg.dependencies : {}), [CORE_PKG]: dep };
+  pkg.dependencies = {
+    ...(isObj(moduleDeps) ? moduleDeps : {}),
+    ...(isObj(pkg.dependencies) ? pkg.dependencies : {}),
+    [CORE_PKG]: dep,
+  };
   return pkg;
 }
 
+// The external npm deps a single module declares in its module.json `dependencies` (ADR 0138).
+// I/O (reads the core-package module manifest); fail-soft → {} when absent/unreadable.
+function moduleDeclaredDeps(moduleKey, { coreRoot = resolveCoreRoot(), fsImpl = fs } = {}) {
+  try {
+    const mj = JSON.parse(fsImpl.readFileSync(path.join(coreRoot, 'modules', moduleKey, 'module.json'), 'utf8'));
+    return isObj(mj.dependencies) ? mj.dependencies : {};
+  } catch {
+    return {};
+  }
+}
+
+// Merge the declared deps of every ENABLED module (modulesConfig = { modules: { key: bool } })
+// into one object. PURE — `readDeps(key)` is injected (defaults to moduleDeclaredDeps) so this is
+// testable with no disk. A later-enabled module's range wins on a key collision (rare).
+function enabledModuleDeps(modulesConfig, { readDeps = (k) => moduleDeclaredDeps(k) } = {}) {
+  const enabled = isObj(modulesConfig) && isObj(modulesConfig.modules) ? modulesConfig.modules : {};
+  const out = {};
+  for (const [key, on] of Object.entries(enabled)) {
+    if (on === true) Object.assign(out, readDeps(key));
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // Pure builders (exported for tests — no I/O, no network)
 // ---------------------------------------------------------------------------
@@ -525,7 +558,11 @@ function writeConfigs(spec, { dir, force, dryRun, coreDep, log = console.log })
   const pkgName = slugify((spec.identity && spec.identity.productName) || '', 'cloudbongos-instance');
   let existingPkg = null;
   if (fs.existsSync(pkgPath)) { try { existingPkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { existingPkg = null; } }
-  const pkg = buildInstancePackageJson(existingPkg, { name: pkgName, coreDep });
+  // Compose the deps of the ENABLED modules (ADR 0138 / task 2160) so an instance that turns a
+  // bundled module on gets that module's npm deps (e.g. discord → discord.js) in its package.json,
+  // rather than crashing at boot on a dep @bongos/core deliberately doesn't carry (rehearsal F2).
+  const moduleDeps = enabledModuleDeps(modules);
+  const pkg = buildInstancePackageJson(existingPkg, { name: pkgName, coreDep, moduleDeps });
   const pinNote = pkg.dependencies[CORE_PKG];
 
   if (dryRun) {
@@ -908,6 +945,23 @@ async function main(argv) {
   console.log('\nMaterializing the .claude/ methodology surface:');
   materializeClaude({ coreRoot: resolveCoreRoot(), instanceDir: dir, dryRun, log: console.log });
 
+  // Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
+  // client) from the PINNED core's routes so this fresh consumer's COMMITTED artifacts
+  // match its core from day one — not the core package's build-time snapshot (task 2141).
+  // They ship as CORE starters (task 2078 — the hall/docs must render before first regen)
+  // yet are per-instance GENERATED; `bongos upgrade` does the same on a bump, this closes
+  // the gap at standup. Best-effort: a hiccup warns, never fails init — the instance-root
+  // drift guard (fitness `gen-api-docs --check` + the api_client byte-identity test)
+  // catches any lag on the consumer's first CI.
+  if (dryRun) {
+    console.log('\n[dry-run] would regenerate the API artifacts (OpenAPI spec + reference + typed client) from the pinned core');
+  } else {
+    console.log('\nRegenerating the API artifacts from the pinned core (OpenAPI spec + reference + typed client):');
+    const regen = upgrade.regenerateApiArtifacts({ instanceDir: dir, coreRoot: resolveCoreRoot() });
+    if (regen.ok) console.log(`  ✓ regenerated (${regen.ran.join(', ')}) → docs/api/ + docs/api-reference.md + clients/bongos-client/`);
+    else console.error(`  ! API-artifact regen skipped (${regen.reason}) — regenerate in ${dir} by hand; the instance-root fitness gate flags the lag otherwise.`);
+  }
+
   let seedResult = {};
   if (!noSeed) seedResult = (await seedViaApi(spec, { dryRun })) || {};
   else console.log('  (--no-seed: skipped version/task seeding)');
@@ -933,6 +987,8 @@ module.exports = {
   KNOWN_MODULES, HOSTING_SHAPES, CORE_PKG,
   // greenfield installability (ADR 0108 gap 1/4, task 2053)
   buildInstancePackageJson, coreVersionSafe, INSTANCE_START_SCRIPT, INSTANCE_MIGRATE_SCRIPT,
+  // enabled-module dep composition (ADR 0138 / task 2160)
+  moduleDeclaredDeps, enabledModuleDeps,
 };
 
 if (require.main === module) {

package/scripts/gds/lint-infra-exec.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+'use strict';
+// lint-infra-exec.js — task 2137 (ADR 0108 configurable-root). The dry-run/lint that proves every
+// host systemd unit running a CORE script still resolves AFTER the R89 split.
+//
+// The units (box-*, cohost-*, provision-*, search-index-db) keep living in the instance repo
+// (infra/ is host topology) while scripts/gds/ moves into node_modules/@bongos/core, so each
+// ExecStart runs through infra/core-node.sh, which resolves the script under the instance root OR
+// its node_modules/@bongos/core (both layouts). "Resolves in a consumer layout" is provable from
+// the package manifest: the referenced core script must be a PUBLISHABLE core file (isPublishable →
+// it ships inside @bongos/core → present at node_modules/@bongos/core/<rel> post-install). We also
+// assert it exists at the core root today (monolith resolution + a typo catch) and that NO unit
+// still uses the bare repo-relative `node scripts/…` form (which resolves nothing post-split).
+//
+// Usage: node scripts/gds/lint-infra-exec.js   (exit 0 = every unit resolves; 1 = violation)
+
+const fs = require('fs');
+const path = require('path');
+const { isPublishable } = require('./publish-manifest');
+const { resolveInstanceRoot, resolveCoreRoot } = require('../../src/instance-config');
+
+const LAUNCHER = 'infra/core-node.sh';
+// Repointed form:  ExecStart=/usr/bin/env bash infra/core-node.sh <core-rel> [args]
+const LAUNCHER_EXEC = /^ExecStart=.*\binfra\/core-node\.sh\s+(\S+)/;
+// Old bare form:   ExecStart=<node> scripts/…  — must no longer appear on a core-script unit.
+const BARE_EXEC = /^ExecStart=\S*node\s+(scripts\/\S+)/;
+
+// Pure-ish (reads the fs): classify every infra/*.service ExecStart. Returns
+// { ok, checked:[{unit,rel}], violations:[{unit,rel,why}] }. Roots are injectable for tests.
+function lintInfraExec({ instanceRoot, coreRoot } = {}) {
+  const iRoot = instanceRoot || resolveInstanceRoot();
+  const cRoot = coreRoot || resolveCoreRoot();
+  const dir = path.join(iRoot, 'infra');
+  const checked = [];
+  const violations = [];
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => f.endsWith('.service')).sort() : [];
+  for (const f of files) {
+    for (const raw of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+      const L = raw.trim();
+      if (!L.startsWith('ExecStart=')) continue;
+      const viaLauncher = LAUNCHER_EXEC.exec(L);
+      if (viaLauncher) {
+        const rel = viaLauncher[1];
+        if (!isPublishable(rel)) {
+          violations.push({ unit: f, rel, why: 'not a publishable core file — ABSENT from node_modules/@bongos/core in a consumer layout' });
+        } else if (!fs.existsSync(path.join(cRoot, rel))) {
+          violations.push({ unit: f, rel, why: `does not exist at the core root (${cRoot})` });
+        } else {
+          checked.push({ unit: f, rel });
+        }
+        continue;
+      }
+      const bare = BARE_EXEC.exec(L);
+      if (bare && bare[1].startsWith('scripts/')) {
+        violations.push({ unit: f, rel: bare[1], why: `bare repo-relative ExecStart — route it through ${LAUNCHER}` });
+      }
+    }
+  }
+  return { ok: violations.length === 0, checked, violations };
+}
+
+if (require.main === module) {
+  const r = lintInfraExec();
+  for (const c of r.checked) console.log(`  ✓ ${c.unit.padEnd(38)} ${c.rel}  (publishable → resolves in a consumer layout)`);
+  for (const v of r.violations) console.error(`  ✗ ${v.unit.padEnd(38)} ${v.rel}  — ${v.why}`);
+  console.log(`\nlint-infra-exec: ${r.checked.length} core-script unit(s) resolve; ${r.violations.length} violation(s)`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = { lintInfraExec };

package/scripts/gds/lint-workflow-exec.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+// lint-workflow-exec.js — task 2136 (ADR 0108 configurable-root). The dry-run/lint that proves
+// every .github/workflows/*.yml invocation of a CORE script still resolves AFTER the R89 split.
+//
+// Workflows keep living in the instance repo (.github/ is host topology) while scripts/gds/* +
+// scripts/migrate.sh move into @bongos/core, so each core invocation runs through the both-layouts
+// resolver: infra/core-node.sh for node targets, infra/core-path.sh for bash targets. "Resolves in
+// a consumer layout" is provable from the package manifest: the referenced core script must be a
+// PUBLISHABLE core file (ships in @bongos/core → present at node_modules/@bongos/core post-install)
+// AND exist at the core root today. A BARE `node scripts/gds/x.js` / `bash scripts/migrate.sh` (not
+// routed through the resolver) is a violation — it resolves nothing from the instance root
+// post-split. Host scripts (scripts/art/*) stay at the instance root, so they are NOT flagged.
+//
+// Usage: node scripts/gds/lint-workflow-exec.js   (exit 0 = all routed + resolve; 1 = violation)
+
+const fs = require('fs');
+const path = require('path');
+const { isPublishable } = require('./publish-manifest');
+const { resolveInstanceRoot, resolveCoreRoot } = require('../../src/instance-config');
+
+// Routed:  `… core-node.sh <rel>` / `… core-path.sh <rel>` (rel = a scripts/… core path).
+const ROUTED = /core-(?:node|path)\.sh\s+(scripts\/[^\s"')]+)/g;
+// Bare core invocation the resolver should have wrapped. Core scripts = scripts/gds/*.{js,sh} +
+// scripts/migrate.sh; host scripts/art/* deliberately excluded (they stay at the instance root).
+const BARE = /(?:^|[^/\w])(?:node|bash)\s+(scripts\/(?:gds\/[^\s"']+\.(?:js|sh)|migrate\.sh))/;
+
+function lintWorkflowExec({ instanceRoot, coreRoot } = {}) {
+  const iRoot = instanceRoot || resolveInstanceRoot();
+  const cRoot = coreRoot || resolveCoreRoot();
+  const dir = path.join(iRoot, '.github', 'workflows');
+  const checked = [];
+  const violations = [];
+  const files = fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => /\.ya?ml$/.test(f)).sort() : [];
+  for (const f of files) {
+    for (const raw of fs.readFileSync(path.join(dir, f), 'utf8').split('\n')) {
+      const line = raw.replace(/\s+$/, '');
+      if (line.trim().startsWith('#')) continue; // a YAML/shell comment — reference, not an invocation
+      let m;
+      ROUTED.lastIndex = 0;
+      while ((m = ROUTED.exec(line)) !== null) {
+        const rel = m[1];
+        if (!isPublishable(rel)) violations.push({ file: f, rel, why: 'routed but NOT a publishable core file — absent from @bongos/core in a consumer layout' });
+        else if (!fs.existsSync(path.join(cRoot, rel))) violations.push({ file: f, rel, why: `routed but does not exist at the core root (${rel})` });
+        else checked.push({ file: f, rel });
+      }
+      if (/core-(?:node|path)\.sh/.test(line)) continue; // routed line — the arg was handled above
+      const bare = BARE.exec(line);
+      if (bare) violations.push({ file: f, rel: bare[1], why: 'bare core invocation — route it through infra/core-node.sh (node) or infra/core-path.sh (bash)' });
+    }
+  }
+  return { ok: violations.length === 0, checked, violations };
+}
+
+if (require.main === module) {
+  const r = lintWorkflowExec();
+  for (const c of r.checked) console.log(`  ✓ ${c.file.padEnd(26)} ${c.rel}  (publishable → resolves in a consumer layout)`);
+  for (const v of r.violations) console.error(`  ✗ ${v.file.padEnd(26)} ${v.rel}  — ${v.why}`);
+  console.log(`\nlint-workflow-exec: ${r.checked.length} routed core invocation(s) resolve; ${r.violations.length} violation(s)`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+module.exports = { lintWorkflowExec };

package/scripts/gds/mirror-lineage-check.js

@@ -55,9 +55,11 @@ const { nextFree } = require(path.join(REPO_ROOT, 'scripts/gds/next-number.js'))
 // deterministic regardless of file order.
 const KNOWN_SECRET_SHAPES = SECRET_PATTERNS.map((re) => new RegExp(re.source, re.flags.replace('g', '')));
 
-// Core migrations are migrations/NNN_slug.sql (3+ digit prefix). Module migrations
-// live under modules/<key>/migrations/ and are numbered independently — the
-// claim-time allocator only reads the core dir, so only core numbering can diverge.
+// Core migrations are migrations/NNN_slug.sql (3+ digit prefix) DIRECTLY under
+// migrations/. Module migrations live under modules/<key>/migrations/ and instance
+// SEEDS under migrations/instance/ (ADR 0105) — both numbered independently and
+// excluded from the publishable mirror; the claim-time allocator only reads the
+// top-level core dir, so only core numbering can diverge.
 const MIGRATION_BASENAME_RE = /^(\d{3,})_.*\.sql$/;
 
 // ---- pure helpers (exported for tests) ------------------------------------
@@ -67,8 +69,15 @@ function migrationNumbersFromPaths(paths) {
   const out = new Set();
   for (const p of paths || []) {
     const s = String(p);
-    if (!s.startsWith('migrations/')) continue; // core dir only
-    const m = MIGRATION_BASENAME_RE.exec(s.split('/').pop());
+    if (!s.startsWith('migrations/')) continue; // the migrations dir …
+    // … and ONLY its top level. migrations/instance/NNN_*.sql are this instance's host
+    // seeds (ADR 0105), excluded from the publishable mirror (task 2140) — counting them
+    // here put every instance seed in the PRIVATE set but not the MIRROR set, a false
+    // private⇄mirror divergence that red-lined the unit gate (task 2152). A path with a
+    // further slash is a subdir, never a core migration.
+    const rest = s.slice('migrations/'.length);
+    if (rest.includes('/')) continue;
+    const m = MIGRATION_BASENAME_RE.exec(rest);
     if (m) out.add(parseInt(m[1], 10));
   }
   return out;

package/scripts/gds/mirror-redact.js

@@ -171,6 +171,14 @@ function deriveInstanceLiterals(branding = {}, extra = {}) {
   add(owners, branding.firstAdmin);
   const identity = branding.identity || {};
   add(tokens, identity.worldName);
+  // The PRODUCT name is instance identity too. It was leaking into the published core (the
+  // onboarding primer described this instance's product as the reader's own project) because
+  // only worldName was derived — the redactor never saw it AND findLeaks couldn't gate it.
+  // Deriving it here closes both in one place. (task 2153)
+  add(tokens, identity.productName);
+  // The reward-currency label is per-instance identity as well; a vanilla core must not ship
+  // another instance's currency name (the currency/karma onboarding doc carried it verbatim).
+  add(tokens, (branding.currency || {}).label);
   // The fulfillment/parent company is instance identity too (a coined single word like
   // "Acme"); redact its name + its site's registrable label.
   const company = identity.company || {};

package/scripts/gds/onboard.js

@@ -163,6 +163,10 @@ async function run() {
       log('   RECOMMENDED — one click: in the control-plane hall, open “Start a project” →');
       log('   “Set up GitHub sign-in”. Approve the pre-filled GitHub App; the control plane');
       log('   places the credentials automatically (no secret to paste). Then skip to ⑦.');
+      log('   ⚠ Terminal CLI only: the one-click App cannot enable Device Flow via the manifest,');
+      log('     but `bongos login` needs it. After approving, open the app (github.com → Settings');
+      log('     → Developer settings → GitHub Apps → your app), check "Enable Device Flow", save.');
+      log('     Web sign-in works without this.');
       log('   — or, to create an OAuth app BY HAND —');
       log(`   ${oa.location}`);
       log('   (Developer settings is under your ACCOUNT, not the repository.)');

package/scripts/gds/package-core.js

@@ -240,13 +240,28 @@ function buildPackageJson({ version, sourceDeps, sourceOverrides }) {
     main: 'src/platform-server.js',
     bin: { bongos: 'bin/bongos.js' },
     // Named exports a consumer imports directly, alongside the default entry
-    // (buildPlatformApp, from `main`): mountInternalSurfaces (the shared
-    // host-routing surface both server.js and platform-server.js call) and the
-    // module-api doorway a module's routes/seams are authored against.
+    // (buildPlatformApp, from `main`). Two groups:
+    //   • the platform surface — serve-internal (the shared host-routing surface
+    //     both server.js and platform-server.js call) + the module-api doorway a
+    //     module's routes/seams are authored against.
+    //   • the GAME-HOST KIT (rehearsal F3, task 2161) — the core internals a
+    //     game-bearing instance's own entrypoint (server.js, kept host per task
+    //     2134) wires directly: the API-404 shaping, the uptime poller, the module
+    //     loader, the enabled-module gate, and the seam registry. A game-less
+    //     instance boots via `.`/platform-server.js and never imports these; a game
+    //     instance's server.js requires them, and the cutover codemod
+    //     (scripts/gds/cutover-codemod.js) rewrites its relative `./src/*` requires
+    //     to exactly these subpaths. Every subpath the codemod's CORE_INTERNAL_MAP
+    //     targets MUST appear here or the rewritten require won't resolve.
     exports: {
       '.': './src/platform-server.js',
       './serve-internal': './src/bongos/serve-internal.js',
       './module-api': './src/module-api.js',
+      './bongos/api-path-404': './src/bongos/api-path-404.js',
+      './bongos/uptime-poller': './src/bongos/uptime-poller.js',
+      './module-loader/loader': './src/module-loader/loader.js',
+      './modules': './src/modules.js',
+      './module-seams': './src/module-seams.js',
     },
     engines: { node: '>=22' },
     // Pre-launch distribution posture (task 2089 / ADR 0134): publish PRIVATE by