@bongos/core 1.19.754 → 1.19.756

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.754",
-  "core_contract": "1.19.754",
-  "source_commit": "8fd1dd9b3ddbc313d9e3bb09ba2a339cb9793e7f",
+  "core_version": "1.19.756",
+  "core_contract": "1.19.756",
+  "source_commit": "701a77495faed74b1cad4941c564f5a8a1a99158",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T00:24:38.617Z",
+  "built_at": "2026-09-16T02:21:20.653Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2111,
+    "functional_verbatim": 2114,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2619,
-  "tree_sha256": "a2f5f1ae36d83e33d7e61bab1264bf62287f10d175f2c9e1f3cabd695bc2b757",
+  "file_count": 2622,
+  "tree_sha256": "0124e1a9cd241c6125c6a7a1351be80d37c9a40ba36c2f2def3ccb768417105c",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f367478f9031a67c77c1b43521aa215ea65068e9ad1b6b21540c81abd8a22dde"
+      "sha256": "cbc6427898e270a22852c496e1405b927c41e295a1a8808fb260b4f83f6f6429"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7567,12 +7567,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "0b25947dcf9f2906d39aec4e4ad10e63dc42831cf593c5404ba77dc51c2be946"
+      "sha256": "cc3fcdaac4eeb204e96790fe0203978514bb550acc078a68d5577cd02d229f7c"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f340a8707e0abe69d0e7d1028a0a96675b66099ce87af7932004393e02dc2a19"
+      "sha256": "0e01d62b067f43577be10f62f417f36dbdcbadc0ba03d290ba902b9447d9ac34"
     },
     {
       "path": "public-docs/index.html",
@@ -8024,11 +8024,21 @@
       "mode": "0000644",
       "sha256": "b8b1a7ed1d8dd217b24757a3ec9f4b3aa58b26a3e2a7b2cef9de217792e5ea43"
     },
+    {
+      "path": "scripts/gds/fitness-checks-error-envelope.js",
+      "mode": "0000644",
+      "sha256": "ab11c75ae177397fdd507505732450fee3531d42b99ba0b34811d06563ebd21c"
+    },
     {
       "path": "scripts/gds/fitness-checks-identity.js",
       "mode": "0000644",
       "sha256": "583b21bf6527b657058ebfab50aff8c51cec96a0b1baa4d01daea55e90d0ccf7"
     },
+    {
+      "path": "scripts/gds/fitness-checks-packaging.js",
+      "mode": "0000644",
+      "sha256": "1f0611c9b8cb30e20119d50f67bc3a1148d6b5d869337361ae0ac58724aaca12"
+    },
     {
       "path": "scripts/gds/fitness-checks-route-pins.js",
       "mode": "0000644",
@@ -8057,7 +8067,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "69c24b7d4a273520284cf2e07be151ffd70128e495b6bb12aa6da83b7d62cf71"
+      "sha256": "4856485e5bb5bb03e47cd6953659c25214411d0b63287f6ab2faa4c34e1e27bc"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -9342,7 +9352,7 @@
     {
       "path": "src/bongos/serve-internal.js",
       "mode": "0000644",
-      "sha256": "61b13299ffdd7f036d5bc3d364135bd8ca4d3470223001b8ff6cc45d858d6107"
+      "sha256": "9edf07966de8d137ba6d987557bb4a9fefeedd19e640f10302dbfd340e0343f9"
     },
     {
       "path": "src/bongos/uptime-poller.js",
@@ -9372,7 +9382,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "df078d4bd7a6e0fda01ce242821141c66b6dc0f2d07ebfaf8de1a89ae279499e"
+      "sha256": "a4071a82922c3333e62a1657f6ce674b19831dbf0152ab3c6c270904193d3f2c"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11619,6 +11629,11 @@
       "mode": "0000644",
       "sha256": "40c396fda3a618bf9fa2d2ae3d8d30b50e62c4210199d70b5e29cb82a046d037"
     },
+    {
+      "path": "tests/module_asset_subdomain.mjs",
+      "mode": "0000644",
+      "sha256": "420e17095b054f87be386913077966d456ae687b030b476e1bc33b15ae35ed9f"
+    },
     {
       "path": "tests/module_catalog.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1982,5 +1982,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.752 with no explicit bump. run 35036151976. (task 1002620)
   1.19.754 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.753 with no explicit bump. run 35039836268. (task 1002620)
+  1.19.755 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.754 with no explicit bump. run 35047010813. (task 1002620)
+  1.19.756 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.755 with no explicit bump. run 35047623582. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.754",
+  "version": "1.19.756",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.754",
+      "version": "1.19.756",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.754",
+  "version": "1.19.756",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/fitness-checks-error-envelope.js

@@ -0,0 +1,134 @@
+// scripts/gds/fitness-checks-error-envelope.js — Check 17: no route hand-rolls a
+// FLAT error (BV1 R03 / task 1990 / ADR 0116).
+//
+// Carved out of scripts/gds/fitness.js by task 1003825 alongside the packaging pair,
+// for the headroom reason documented there. Self-contained: the scan needs only
+// CORE_ROOT / rel / walkJs / walkJsAllRoots from fitness-lib.js, and FLAT_ERROR_BASELINE
+// travels WITH the check rather than staying behind — the baseline and the gate that
+// reads it are one decision, and splitting them is how a ratchet quietly loses its floor.
+//
+// fitness.js requires the four public names straight back (checkErrorEnvelope,
+// scanFlatErrorSites, countFlatErrors, FLAT_ERROR_BASELINE — the last three are read by
+// the R04 sweep and its tests), so nothing outside this file changes shape.
+// stripCommentsForFlat stays PRIVATE here: it was never on fitness.js's exports, and
+// exporting it now to mirror the carve would be a new public name nothing consumes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { CORE_ROOT, rel, walkJs, walkJsAllRoots } = require('./fitness-lib.js');
+// ============================================================================
+// Check 17 — no route hand-rolls a FLAT error (BV1 R03 / task 1990 / ADR 0116)
+// ============================================================================
+//
+// The error-envelope contract (ADR 0116) says every failure is the ONE envelope
+// `{error:{code,message,details}}`, emitted via res.fail() or a thrown ApiError
+// (the R02 middleware, task 1989). A hand-rolled flat error —
+// `res.status(n).json({ error: 'x' })` or `.json({ error })` — breaks the
+// contract: the caller gets a bare string where the envelope should be.
+//
+// RATCHET, not big-bang. The R04 sweep (task 1991) migrates the ~562 existing
+// sites; until it finishes they'd all "fail" a strict check, so this HOLDS THE
+// LINE: it fails only when the count rises ABOVE the committed baseline (a NEW
+// hand-rolled flat error), and nudges the baseline DOWN as the sweep shrinks it.
+// When the sweep reaches 0, FLAT_ERROR_BASELINE is 0 and any new flat error
+// hard-fails immediately. Detector is shared with the sweep + its test.
+const FLAT_ERROR_BASELINE = 0; // R04 sweep (task 1991) landed the surface at 0 — the gate is now hard-zero: any new hand-rolled flat error fails the build immediately.
+// A flat error is a `.json({ … })` whose FIRST key is `error` with a value that
+// is NOT an object literal (a string/var/shorthand). The envelope's nested
+// `error: { … }` and `.json(envelope(…))` deliberately do NOT match.
+// The `(?!\s*\{)` lookahead is whitespace-aware: without the inner `\s*` the
+// preceding `\s*` backtracks to zero and the lookahead is tested at the space in
+// `error: {`, so the compliant nested envelope was wrongly flagged (task 2029).
+const FLAT_ERROR_VALUE_RE = /\.json\(\s*\{\s*error\s*:\s*(?!\s*\{)/g; // error: 'x' | error: code
+const FLAT_ERROR_SHORTHAND_RE = /\.json\(\s*\{\s*error\s*[,}]/g;   // { error } | { error, … }
+
+// Strip // line comments + /* */ block comments AND blank out string/template
+// contents (keeping the delimiters) so neither a DOC example of the anti-pattern
+// — e.g. the res.fail() usage note in middleware/error-envelope.js — nor a
+// pattern quoted inside a string literal is counted as a real flat error once
+// the gate is hard-zero (task 1991). Real flat errors are unaffected: in
+// `res.status(404).json({ error: 'x' })` the `.json({ error:` the detector keys
+// on is CODE (outside the string), so blanking the `'x'` content still matches.
+function stripCommentsForFlat(src) {
+  let out = '';
+  let i = 0;
+  let quote = null;
+  while (i < src.length) {
+    const c = src[i];
+    const d = src[i + 1];
+    if (quote) {
+      // inside a string/template: drop content, keep only the closing delimiter
+      if (c === '\\') { i += 2; continue; }
+      if (c === quote) { out += c; quote = null; }
+      i++; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i++; continue; }
+    if (c === '/' && d === '/') { while (i < src.length && src[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { i += 2; while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++; i += 2; continue; }
+    out += c; i++;
+  }
+  return out;
+}
+
+function countFlatErrors(text) {
+  const code = stripCommentsForFlat(text);
+  return (code.match(FLAT_ERROR_VALUE_RE) || []).length
+       + (code.match(FLAT_ERROR_SHORTHAND_RE) || []).length;
+}
+
+// scanFlatErrorSites() — per-file flat-error counts across the API surface
+// (core src/bongos + every module), skipping tests. Shared by the check below, the
+// R04 codemod, and tests/api_error_envelope_buildcheck.mjs.
+function scanFlatErrorSites() {
+  const seen = new Set();
+  const byFile = {};
+  let total = 0;
+  const files = [
+    ...walkJs(path.join(CORE_ROOT, 'src', 'bongos')),
+    ...walkJsAllRoots('modules'),
+  ];
+  for (const abs of files) {
+    const relFile = rel(abs);
+    if (seen.has(relFile)) continue;
+    seen.add(relFile);
+    if (relFile.includes('/tests/') || relFile.endsWith('.test.js')) continue;
+    const n = countFlatErrors(fs.readFileSync(abs, 'utf8'));
+    if (n) { byFile[relFile] = n; total += n; }
+  }
+  return { total, byFile };
+}
+
+function checkErrorEnvelope() {
+  const { total, byFile } = scanFlatErrorSites();
+  const violations = [];
+  const warnings = [];
+  if (total > FLAT_ERROR_BASELINE) {
+    const top = Object.entries(byFile).sort((a, b) => b[1] - a[1]).slice(0, 8)
+      .map(([f, n]) => `${f} (${n})`).join(', ');
+    violations.push(
+      `${total} hand-rolled flat-error sites — ABOVE the ${FLAT_ERROR_BASELINE} baseline. A new route emitted a flat \`res.status(n).json({error:'x'})\` instead of \`res.fail('x', n)\` / \`throw new ApiError('x')\` (ADR 0116). Top files: ${top}. Use the envelope helper (src/bongos/middleware/error-envelope.js).`
+    );
+  } else if (total < FLAT_ERROR_BASELINE) {
+    warnings.push(
+      `${total} flat-error sites — BELOW the ${FLAT_ERROR_BASELINE} baseline. The sweep tightened; lower FLAT_ERROR_BASELINE to ${total} in fitness.js so the ratchet can't slip back (BV1 R04 / task 1991).`
+    );
+  }
+  return {
+    name: 'no route hand-rolls a flat error (ADR 0116 / R03)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `≤ ${FLAT_ERROR_BASELINE} flat \`.json({error:'…'})\` sites (ratchet → 0 as the R04 sweep lands); currently ${total}. New failures must use res.fail()/ApiError (the R02 envelope).`,
+  };
+}
+
+module.exports = {
+  checkErrorEnvelope,
+  scanFlatErrorSites,
+  countFlatErrors,
+  FLAT_ERROR_BASELINE,
+};

package/scripts/gds/fitness-checks-packaging.js

@@ -0,0 +1,132 @@
+// scripts/gds/fitness-checks-packaging.js — Checks 16 + 16b: core code must not
+// HARD-require a boundary-EXCLUDED config or module.
+//
+// Carved out of scripts/gds/fitness.js by task 1003825, on the task-1003192
+// precedent. That file had returned to the 1,500-line ratchet with ONE line of
+// headroom (1,499 of 1,500, fitness-ratchets.js OVERSIZE_LINES), so the next check
+// registered there would have tipped it over and redded the ratchet for whoever
+// wrote it. These two checks left together because they are one subject — the same
+// question asked of a config and of a module — and because the pair depends only on
+// CORE_ROOT / rel / walkJs / walkJsAllRoots, all already public on fitness-lib.js,
+// so the carve adds no import cycle.
+//
+// fitness.js requires both names straight back, so the CHECKS registry and the
+// module surface the tests read are unchanged.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { CORE_ROOT, rel, walkJs, walkJsAllRoots } = require('./fitness-lib.js');
+// ============================================================================
+// Check 16 — core code must not HARD-require an instance-excluded config/*.json
+// ============================================================================
+//
+// A vanilla self-host boot ships only the PUBLISHABLE tree (publish-manifest.js). An
+// instance-only config (config/devbox-app.json, config/bongos-cli.json, config/branding.json,
+// config/modules.json, …) is boundary-EXCLUDED, so a bare `require('../../config/<excluded>.json')`
+// in core code throws MODULE_NOT_FOUND and CRASHES the boot on a fresh instance — the exact
+// class that shipped in R88 (two hard-requires in src/bongos/serve-internal.js; task 1824). The
+// cure is to READ the config instead of requiring it, tolerating a missing file
+// (tryLoadInstanceConfig in src/bongos/serve-internal.js / fs.existsSync → fail-to-vanilla), which
+// also drops the require() literal so it no longer matches here. Check 1 (core↔host) scans
+// code→code IMPORTS and misses this code→config class. Only an EXCLUDED config is a violation;
+// a publishable neutral.*/schema config (which ships with the core) is fine.
+const CONFIG_REQUIRE_RE = /require\(\s*['"]([^'"]*config\/[^'"]*\.json)['"]\s*\)/g;
+
+function checkCoreRequiresExcludedConfig() {
+  const { isPublishable } = require('./publish-manifest');
+  const violations = [];
+  // src/ + scripts/ are CORE; modules ship from BOTH roots (ADR 0108 §Consequences #4). Dedup by
+  // repo-relative path so a shared checkout scans each file once.
+  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;
+      let m;
+      CONFIG_REQUIRE_RE.lastIndex = 0;
+      while ((m = CONFIG_REQUIRE_RE.exec(raw))) {
+        const relCfg = rel(path.resolve(path.dirname(abs), m[1]));
+        if (!isPublishable(relCfg)) {
+          violations.push(`${relFile} → require('${m[1]}') hard-requires an instance-excluded config (${relCfg}) — guard the read (tryLoadInstanceConfig in src/bongos/serve-internal.js / fs.existsSync, fail-to-vanilla) so a fresh core boots (task 1824).`);
+        }
+      }
+    }
+  }
+  return {
+    name: 'core never hard-requires an excluded config (task 1824)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: "a publishable src/·scripts/·modules/ .js must not require('…config/X.json') when X.json is boundary-excluded — guard the read so a vanilla core boots.",
+  };
+}
+
+// ============================================================================
+// 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).",
+  };
+}
+
+module.exports = {
+  checkCoreRequiresExcludedConfig,
+  checkCoreRequiresExcludedModule,
+};

package/scripts/gds/fitness.js

@@ -37,6 +37,8 @@ const { CORE_ROOT, INSTANCE_ROOT, MODULE_ROOTS, REPO_ROOT, rel, walkJs, walkJsAl
 const { IDENTITY_SCAN_ALLOWED, IDENTITY_SCAN_EXCLUDE, IDENTITY_SCAN_EXTRA_FILES, IDENTITY_SCAN_EXTS, IDENTITY_SCAN_ROOTS, IDENTITY_SCAN_SKIP_DIRS, PROMPT_IDENTITY_LITERALS, checkDesignContract, checkKernelPromptsNoHardcodedIdentity, checkNeutralConfigsNoHostIdentity, collectIdentityFiles, scanPromptIdentity, stripCommentsForIdentity } = require('./fitness-checks-identity.js');
 const { WRITE_VALIDATION_BASELINE, WRITE_VALIDATION_EXEMPT, checkWriteRoutesValidated, scanUnvalidatedWriteRoutes } = require('./fitness-checks-write-validation.js');
 const { GOAL_VOCAB_CITATION, GOAL_VOCAB_LINE_SCOPED, GOAL_VOCAB_SURFACE, LIFECYCLE_DB_FILES, PRELAUNCH_SURFACE, RENAME_IDENTITY_RE, VOCAB_ALLOW, VOCAB_BANNED, VOCAB_CITATION, VOCAB_EXTS, VOCAB_HISTORICAL_REF, VOCAB_SURFACE, checkGoalMembershipVocabulary, checkGovernmentRenameIdentity, checkPrelaunchVocabulary, checkVocabularyWall, vocabFilesToScan } = require('./fitness-checks-vocabulary.js');
+const { checkCoreRequiresExcludedConfig, checkCoreRequiresExcludedModule } = require('./fitness-checks-packaging.js'); // Checks 16 + 16b — carved out by task 1003825 (the 1,500-line ratchet)
+const { FLAT_ERROR_BASELINE, checkErrorEnvelope, countFlatErrors, scanFlatErrorSites } = require('./fitness-checks-error-envelope.js'); // Check 17 — carved out by task 1003825
 // ============================================================================
 // Check 1 — core ↔ host/game import boundary (ADR 0062 §1 cut-line)
 // ============================================================================
@@ -1084,219 +1086,6 @@ function checkHallSectionRegistry() {
   };
 }
 
-// ============================================================================
-// Check 16 — core code must not HARD-require an instance-excluded config/*.json
-// ============================================================================
-//
-// A vanilla self-host boot ships only the PUBLISHABLE tree (publish-manifest.js). An
-// instance-only config (config/devbox-app.json, config/bongos-cli.json, config/branding.json,
-// config/modules.json, …) is boundary-EXCLUDED, so a bare `require('../../config/<excluded>.json')`
-// in core code throws MODULE_NOT_FOUND and CRASHES the boot on a fresh instance — the exact
-// class that shipped in R88 (two hard-requires in src/bongos/serve-internal.js; task 1824). The
-// cure is to READ the config instead of requiring it, tolerating a missing file
-// (tryLoadInstanceConfig in src/bongos/serve-internal.js / fs.existsSync → fail-to-vanilla), which
-// also drops the require() literal so it no longer matches here. Check 1 (core↔host) scans
-// code→code IMPORTS and misses this code→config class. Only an EXCLUDED config is a violation;
-// a publishable neutral.*/schema config (which ships with the core) is fine.
-const CONFIG_REQUIRE_RE = /require\(\s*['"]([^'"]*config\/[^'"]*\.json)['"]\s*\)/g;
-
-function checkCoreRequiresExcludedConfig() {
-  const { isPublishable } = require('./publish-manifest');
-  const violations = [];
-  // src/ + scripts/ are CORE; modules ship from BOTH roots (ADR 0108 §Consequences #4). Dedup by
-  // repo-relative path so a shared checkout scans each file once.
-  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;
-      let m;
-      CONFIG_REQUIRE_RE.lastIndex = 0;
-      while ((m = CONFIG_REQUIRE_RE.exec(raw))) {
-        const relCfg = rel(path.resolve(path.dirname(abs), m[1]));
-        if (!isPublishable(relCfg)) {
-          violations.push(`${relFile} → require('${m[1]}') hard-requires an instance-excluded config (${relCfg}) — guard the read (tryLoadInstanceConfig in src/bongos/serve-internal.js / fs.existsSync, fail-to-vanilla) so a fresh core boots (task 1824).`);
-        }
-      }
-    }
-  }
-  return {
-    name: 'core never hard-requires an excluded config (task 1824)',
-    ok: violations.length === 0,
-    hardFail: violations.length > 0,
-    violations,
-    warnings: [],
-    note: "a publishable src/·scripts/·modules/ .js must not require('…config/X.json') when X.json is boundary-excluded — guard the read so a vanilla core boots.",
-  };
-}
-
-// ============================================================================
-// 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)
-// ============================================================================
-//
-// The error-envelope contract (ADR 0116) says every failure is the ONE envelope
-// `{error:{code,message,details}}`, emitted via res.fail() or a thrown ApiError
-// (the R02 middleware, task 1989). A hand-rolled flat error —
-// `res.status(n).json({ error: 'x' })` or `.json({ error })` — breaks the
-// contract: the caller gets a bare string where the envelope should be.
-//
-// RATCHET, not big-bang. The R04 sweep (task 1991) migrates the ~562 existing
-// sites; until it finishes they'd all "fail" a strict check, so this HOLDS THE
-// LINE: it fails only when the count rises ABOVE the committed baseline (a NEW
-// hand-rolled flat error), and nudges the baseline DOWN as the sweep shrinks it.
-// When the sweep reaches 0, FLAT_ERROR_BASELINE is 0 and any new flat error
-// hard-fails immediately. Detector is shared with the sweep + its test.
-const FLAT_ERROR_BASELINE = 0; // R04 sweep (task 1991) landed the surface at 0 — the gate is now hard-zero: any new hand-rolled flat error fails the build immediately.
-// A flat error is a `.json({ … })` whose FIRST key is `error` with a value that
-// is NOT an object literal (a string/var/shorthand). The envelope's nested
-// `error: { … }` and `.json(envelope(…))` deliberately do NOT match.
-// The `(?!\s*\{)` lookahead is whitespace-aware: without the inner `\s*` the
-// preceding `\s*` backtracks to zero and the lookahead is tested at the space in
-// `error: {`, so the compliant nested envelope was wrongly flagged (task 2029).
-const FLAT_ERROR_VALUE_RE = /\.json\(\s*\{\s*error\s*:\s*(?!\s*\{)/g; // error: 'x' | error: code
-const FLAT_ERROR_SHORTHAND_RE = /\.json\(\s*\{\s*error\s*[,}]/g;   // { error } | { error, … }
-
-// Strip // line comments + /* */ block comments AND blank out string/template
-// contents (keeping the delimiters) so neither a DOC example of the anti-pattern
-// — e.g. the res.fail() usage note in middleware/error-envelope.js — nor a
-// pattern quoted inside a string literal is counted as a real flat error once
-// the gate is hard-zero (task 1991). Real flat errors are unaffected: in
-// `res.status(404).json({ error: 'x' })` the `.json({ error:` the detector keys
-// on is CODE (outside the string), so blanking the `'x'` content still matches.
-function stripCommentsForFlat(src) {
-  let out = '';
-  let i = 0;
-  let quote = null;
-  while (i < src.length) {
-    const c = src[i];
-    const d = src[i + 1];
-    if (quote) {
-      // inside a string/template: drop content, keep only the closing delimiter
-      if (c === '\\') { i += 2; continue; }
-      if (c === quote) { out += c; quote = null; }
-      i++; continue;
-    }
-    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i++; continue; }
-    if (c === '/' && d === '/') { while (i < src.length && src[i] !== '\n') i++; continue; }
-    if (c === '/' && d === '*') { i += 2; while (i < src.length && !(src[i] === '*' && src[i + 1] === '/')) i++; i += 2; continue; }
-    out += c; i++;
-  }
-  return out;
-}
-
-function countFlatErrors(text) {
-  const code = stripCommentsForFlat(text);
-  return (code.match(FLAT_ERROR_VALUE_RE) || []).length
-       + (code.match(FLAT_ERROR_SHORTHAND_RE) || []).length;
-}
-
-// scanFlatErrorSites() — per-file flat-error counts across the API surface
-// (core src/bongos + every module), skipping tests. Shared by the check below, the
-// R04 codemod, and tests/api_error_envelope_buildcheck.mjs.
-function scanFlatErrorSites() {
-  const seen = new Set();
-  const byFile = {};
-  let total = 0;
-  const files = [
-    ...walkJs(path.join(CORE_ROOT, 'src', 'bongos')),
-    ...walkJsAllRoots('modules'),
-  ];
-  for (const abs of files) {
-    const relFile = rel(abs);
-    if (seen.has(relFile)) continue;
-    seen.add(relFile);
-    if (relFile.includes('/tests/') || relFile.endsWith('.test.js')) continue;
-    const n = countFlatErrors(fs.readFileSync(abs, 'utf8'));
-    if (n) { byFile[relFile] = n; total += n; }
-  }
-  return { total, byFile };
-}
-
-function checkErrorEnvelope() {
-  const { total, byFile } = scanFlatErrorSites();
-  const violations = [];
-  const warnings = [];
-  if (total > FLAT_ERROR_BASELINE) {
-    const top = Object.entries(byFile).sort((a, b) => b[1] - a[1]).slice(0, 8)
-      .map(([f, n]) => `${f} (${n})`).join(', ');
-    violations.push(
-      `${total} hand-rolled flat-error sites — ABOVE the ${FLAT_ERROR_BASELINE} baseline. A new route emitted a flat \`res.status(n).json({error:'x'})\` instead of \`res.fail('x', n)\` / \`throw new ApiError('x')\` (ADR 0116). Top files: ${top}. Use the envelope helper (src/bongos/middleware/error-envelope.js).`
-    );
-  } else if (total < FLAT_ERROR_BASELINE) {
-    warnings.push(
-      `${total} flat-error sites — BELOW the ${FLAT_ERROR_BASELINE} baseline. The sweep tightened; lower FLAT_ERROR_BASELINE to ${total} in fitness.js so the ratchet can't slip back (BV1 R04 / task 1991).`
-    );
-  }
-  return {
-    name: 'no route hand-rolls a flat error (ADR 0116 / R03)',
-    ok: violations.length === 0,
-    hardFail: violations.length > 0,
-    violations,
-    warnings,
-    note: `≤ ${FLAT_ERROR_BASELINE} flat \`.json({error:'…'})\` sites (ratchet → 0 as the R04 sweep lands); currently ${total}. New failures must use res.fail()/ApiError (the R02 envelope).`,
-  };
-}
 
 // ============================================================================
 // Check 2c — every SKILL.md frontmatter parses the way Claude Code's YAML reader reads it (task 1003548)

package/src/bongos/serve-internal.js

@@ -826,6 +826,20 @@ function mountInternalSurfaces(app) {
   app.use((req, res, next) => {
     if (!isBuildersHost(req)) return next();
     if (req.path.startsWith('/api/') || req.path === '/healthz') return next();
+    // Module browser assets are addressed at the ROOT on every host — the URL the
+    // loader's hallWidgetScripts projection emits is an absolute /modules/<key>/…
+    // and injectModuleHallWidgets puts that same tag in the hall index on BOTH
+    // hosts (task 1002848). Without this line the shim rewrites it to
+    // /builders/modules/… before the MODULE_ASSET_RE handler below can match, so
+    // the tag is injected on the subdomain and the asset 404s there — injection
+    // works on both hosts, serving works only on the apex. The handler keeps all
+    // its own defences (the isModuleEnabled gate, the traversal check); this only
+    // lets the request reach it.
+    //
+    // The general hazard: ANY apex-rooted route registered BELOW this shim is
+    // eaten the same way. Today that is this one and the /docs family (idea 529
+    // → task 1002861); /downloads/* dodges it by being registered ABOVE instead.
+    if (req.path.startsWith('/modules/')) return next();
     if (req.path === '/builders' || req.path.startsWith('/builders/')) return next();
     // Prefix with /builders so the handlers below match. req.url carries the
     // query string; preserve it. '/' → '/builders/', '/watch' → '/builders/watch'.

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.754'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.756'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/module_asset_subdomain.mjs

@@ -0,0 +1,155 @@
+// tests/module_asset_subdomain.mjs — module browser assets must route identically
+// on the apex and on builders.<apex> (task 1002848).
+//
+// THE BUG. A module-contributed hall widget's <script src="/modules/<key>/public/
+// hall-widget.js"> is injected into the hall index on BOTH hosts by
+// injectModuleHallWidgets, but only SERVED on the apex. The builders-subdomain
+// rewrite shim in serve-internal.js runs as app.use middleware, ahead of the
+// MODULE_ASSET_RE route, and rewrites every path on that host onto the /builders/*
+// tree — exempting only /api/, /healthz and paths already under /builders. So
+// /modules/demo/public/hall-widget.js became /builders/modules/... , stopped
+// matching ^/modules/, and fell through to a 404.
+//
+// WHY THIS TEST HAS TO EXIST. The seam is a live no-op today: no module ships a
+// hall-widget.js, so nothing on either host currently requests one, and a
+// regression here would be completely invisible until the first module that does
+// ship one — at which point it would look like a bug in that module. The test
+// therefore drives a module asset that DOES exist (hall-ui's own public/ dir) and
+// asserts the two hosts agree, which is the property the fix is really about.
+//
+// serve-internal is DB-free (the pg pool connects lazily), so we mount it on a
+// throwaway express app and hit it over loopback — same pattern as
+// tests/docs_openapi_route.mjs.
+//
+// USE node:http, NOT fetch. `Host` is a forbidden header name in the fetch spec,
+// so `fetch(url, { headers: { host } })` SILENTLY drops the override and sends the
+// real one (127.0.0.1:<port>). A host-routing test written with fetch therefore
+// compares the apex against itself, passes, and keeps passing with the fix
+// reverted — which is exactly what the first draft of this file did until the
+// mutation probe caught it. node:http honours an explicit Host in options.headers.
+//
+// Run:  node --test tests/module_asset_subdomain.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+
+// Any host starting with "builders." is the subdomain; anything else is the apex.
+const APEX = 'example.com';
+const SUBDOMAIN = 'builders.example.com';
+
+// A file the hall-ui module really ships, so a 200 proves the request reached the
+// MODULE_ASSET_RE handler AND the handler found bytes — not merely that it matched.
+const REAL_ASSET = '/modules/hall-ui/public/atlas.css';
+
+async function withServer(fn) {
+  const express = require('express');
+  const { mountInternalSurfaces } = require('../src/bongos/serve-internal.js');
+  const app = express();
+  mountInternalSurfaces(app);
+  const server = await new Promise((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  try {
+    await fn(server.address().port);
+  } finally {
+    await new Promise((r) => server.close(r));
+  }
+}
+
+// One loopback request with a REAL Host header. Never follows redirects — a 301 is
+// itself a routing decision we want to see.
+function get(port, path, host) {
+  return new Promise((resolve, reject) => {
+    const req = http.request({ host: '127.0.0.1', port, path, headers: { Host: host } }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body, headers: res.headers }));
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+// The harness is only meaningful if the Host header actually reaches the app, and
+// the fetch trap above proves that is not self-evident. Assert it directly, so a
+// future change that breaks host propagation fails HERE with a clear reason rather
+// than turning every test below into a silent apex-vs-apex tautology.
+test('the harness really varies the Host — without this the rest is vacuous', async () => {
+  await withServer(async (port) => {
+    const { isBuildersHost } = require('../src/bongos/serve-internal.js');
+    assert.equal(isBuildersHost({ headers: { host: SUBDOMAIN } }), true);
+    assert.equal(isBuildersHost({ headers: { host: APEX } }), false);
+    // and end-to-end: both hosts 301 /builders/, but to DIFFERENT places — the apex
+    // sends you to the subdomain, the subdomain strips the redundant prefix. Equal
+    // targets would mean the Host never reached the app.
+    const sub = await get(port, '/builders/', SUBDOMAIN);
+    const apex = await get(port, '/builders/', APEX);
+    assert.notEqual(sub.headers.location, apex.headers.location,
+      'the two hosts must route differently, or the Host header is being dropped');
+  });
+});
+
+test('a real module asset serves on the apex AND on builders.<apex>', async () => {
+  await withServer(async (port) => {
+    const apex = await get(port, REAL_ASSET, APEX);
+    const sub = await get(port, REAL_ASSET, SUBDOMAIN);
+    assert.equal(apex.status, 200, 'precondition: the asset serves on the apex');
+    assert.equal(sub.status, 200,
+      'the subdomain must serve it too — the rewrite shim used to turn this into /builders/modules/... and 404');
+  });
+});
+
+test('the two hosts return the same body, not just the same status', async () => {
+  await withServer(async (port) => {
+    const apex = await get(port, REAL_ASSET, APEX);
+    const sub = await get(port, REAL_ASSET, SUBDOMAIN);
+    assert.ok(apex.body.length > 0, 'precondition: the asset is not empty');
+    assert.equal(sub.body, apex.body, 'the subdomain must serve the same bytes, not a rewritten page');
+  });
+});
+
+test('an unknown module 404s on BOTH hosts — the exemption grants no new reach', async () => {
+  await withServer(async (port) => {
+    const p = '/modules/no-such-module/public/x.css';
+    assert.equal((await get(port, p, APEX)).status, 404);
+    assert.equal((await get(port, p, SUBDOMAIN)).status, 404,
+      'the shim exemption must not turn an unknown module into anything but a 404');
+  });
+});
+
+test('a missing file inside a REAL module 404s on both hosts', async () => {
+  await withServer(async (port) => {
+    const p = '/modules/hall-ui/public/definitely-not-here.css';
+    assert.equal((await get(port, p, APEX)).status, 404);
+    assert.equal((await get(port, p, SUBDOMAIN)).status, 404);
+  });
+});
+
+test('path traversal out of the module dir is refused on the subdomain too', async () => {
+  await withServer(async (port) => {
+    // The handler normalizes and rejects a rel path escaping modules/<key>/public.
+    // Worth pinning on the SUBDOMAIN specifically: that request now reaches the
+    // handler where it previously never did, so this is newly-exercised ground.
+    for (const p of ['/modules/hall-ui/public/../../../package.json',
+                     '/modules/hall-ui/public/..%2f..%2f..%2fpackage.json']) {
+      const r = await get(port, p, SUBDOMAIN);
+      assert.notEqual(r.status, 200, `traversal must not serve a file outside the module dir (${p})`);
+      assert.ok(!/"name":\s*"@bongos/.test(r.body), 'package.json bytes must never appear in the body');
+    }
+  });
+});
+
+test('the exemption is scoped to /modules/ — a lookalike path is still rewritten', async () => {
+  await withServer(async (port) => {
+    // If the exemption had been written as a bare `includes('modules')` or without
+    // the trailing slash, this path would escape the shim too.
+    const r = await get(port, '/moduleslike', SUBDOMAIN);
+    assert.notEqual(r.status, 200,
+      'a path merely starting with "modules" but outside /modules/ is not a module asset');
+  });
+});