@bongos/core 1.19.940 → 1.19.942

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.940",
-  "core_contract": "1.19.940",
-  "source_commit": "44e10510143c0775561f28fe1e8d3b55fdbc3190",
+  "core_version": "1.19.942",
+  "core_contract": "1.19.942",
+  "source_commit": "1e45821468069b9d8f26ed2f7dbf1bbf647ea4b8",
   "source_ref": "HEAD",
-  "built_at": "2026-09-21T19:54:33.696Z",
+  "built_at": "2026-09-21T21:46:27.727Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 511,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2339,
+    "functional_verbatim": 2340,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2876,
-  "tree_sha256": "a7edb7e2d7278cda02f1dc7d69eb957b0702345c2f059ead3049463b6fb17ff7",
+  "file_count": 2877,
+  "tree_sha256": "5e3c476a60b0631f79c68b199ba47f437ab6295e2518dfc86e7104e8fe0e9bfe",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2677,7 +2677,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b0dcdad0ab90dc948a111f4bb26a39ffa028bd17907ad7ffbadbc3ec424d54c6"
+      "sha256": "cf5f371ef80387f8344682a639e736c8cc3240debb4ee97106dfc2525e402e97"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2927,7 +2927,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "147fe7408c7e86487c2cd99198074f3591c7b956c0debd80b7b0730803940571"
+      "sha256": "0df57ea34114fb1ae81389458334b392d768fc83d9e82eb00fa917219189de87"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -8002,12 +8002,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d319db2c2f341bea9b0f59dd6f2c826a68a155e620b3b6e8809ef8e35390b7bf"
+      "sha256": "04da7afdf07b5eacb7b5d8e18f034a45e62c318eed546facfa4e65480f5a6292"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0692c686bc978e5f8ada5fa1f563bf40bdc9fde2a548a8ca47f21e089010bbbb"
+      "sha256": "79d643dab7e8bf794763c95cfa6f05200054d4aa2be271b61805954b1b82eb83"
     },
     {
       "path": "public-docs/index.html",
@@ -8442,7 +8442,7 @@
     {
       "path": "scripts/gds/deploy-divergence.js",
       "mode": "0000644",
-      "sha256": "8aae6c1a2cd978e53bce7d788ab5f4fe86ab357821f083d1b414df4f5742beac"
+      "sha256": "bffaceec8b47b238f4a7911aee10a651b45cd75e0c5a67b2b8e3daa90e3cd54a"
     },
     {
       "path": "scripts/gds/deploy-main-audit-gate.sh",
@@ -9107,7 +9107,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "034d5678310329273360d7dd3e60cb0bb13e29fa6895c2c79338f80416b751bd"
+      "sha256": "b536a889714c7f1ddc027b3f29602351d6942e1e52157469a5f82400490ee1d4"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -9617,7 +9617,7 @@
     {
       "path": "scripts/migrate.sh",
       "mode": "0000644",
-      "sha256": "669ba0cd4e0c5ad2c7809364e4ac17b24bfa3f8542fae5ba7ec05e9bcf77053f"
+      "sha256": "6f927d08ea67e4a7081972fb78fd6131c9eee569730932621d1e1ee6334ddd3a"
     },
     {
       "path": "scripts/migrate_cost_ledger.sh",
@@ -9972,7 +9972,7 @@
     {
       "path": "src/bongos/schema-lag.js",
       "mode": "0000644",
-      "sha256": "bafe3453eff53cb80ef0eb3ca5894d7ff2fc4a2480e80595869d8d9838d06a42"
+      "sha256": "b84a237b9fe9ce9f905ae0ca72e7f82eb08670397eb7e6c88c114c62afcf81a8"
     },
     {
       "path": "src/bongos/secret-box.js",
@@ -9987,7 +9987,7 @@
     {
       "path": "src/bongos/serve-internal.js",
       "mode": "0000644",
-      "sha256": "59aa0ee2be23c8c956357eb67ee58720bd2e378a71a9efb6a73ab966c7d4094f"
+      "sha256": "989a1bef0e179efe32fc3edb11f7f46b1732920ca026b36a841c8e0e344a175a"
     },
     {
       "path": "src/bongos/uptime-poller.js",
@@ -10012,7 +10012,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "d4d3c893fb318a929f2721a142191807d04b74c20ace3e77c1afc4d50f747c03"
+      "sha256": "ea1889449a3dab8921a6d4ce4fc539c8c550aef3eedc14d22493a26cd6af1bcc"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11062,7 +11062,7 @@
     {
       "path": "tests/deploy_divergence_line.mjs",
       "mode": "0000644",
-      "sha256": "7e87aa9005acbf2fff537a9b79f19b5901b304b5fb4472224b5f3abaf5fef15a"
+      "sha256": "fd62561dcf5fb935116ec5933393e75cef25eaa807a6d39fc55d9c981e6fe289"
     },
     {
       "path": "tests/deploy_instance.mjs",
@@ -12509,6 +12509,11 @@
       "mode": "0000644",
       "sha256": "a1179788640c3959e21573817e386eece65067ecbe9bda6cd350e16118ac61f1"
     },
+    {
+      "path": "tests/migrate_module_overrides_db.mjs",
+      "mode": "0000644",
+      "sha256": "a998b59c0a6d28a0c0d1fe617059631cff052c68afe954265e92a0cca8ce04e4"
+    },
     {
       "path": "tests/migrate_root_resolution.mjs",
       "mode": "0000644",
@@ -13452,12 +13457,12 @@
     {
       "path": "tests/schema_lag.mjs",
       "mode": "0000644",
-      "sha256": "90e5cdc6648856a027c67df41e39fee6699d7bae56b79bc41cefbb2d249c86a9"
+      "sha256": "af0db545b71f9cc3b88ae0a9cd09e909d9956326dd0aba8bb02a330e2cb21c8b"
     },
     {
       "path": "tests/schema_lag_db.mjs",
       "mode": "0000644",
-      "sha256": "74f4f62025773a917b77120637fcfb3e5cd843aee4ca30c7ed2303fb613f18ec"
+      "sha256": "5e3ada8619ea87eea3026a2ccf3069926d5825a06fe11b5e435020034b2eb7e1"
     },
     {
       "path": "tests/scope_map_guard.mjs",

package/docs/module-api-changelog.md

@@ -2354,5 +2354,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.938 with no explicit bump. run 35641614084. (task 1002620)
   1.19.940 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.939 with no explicit bump. run 35647628385. (task 1002620)
+  1.19.941 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.940 with no explicit bump. run 35652433730. (task 1002620)
+  1.19.942 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.941 with no explicit bump. run 35659043986. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/upgrading-the-core.md

@@ -167,7 +167,7 @@ running a go-live.
 - **Survey co-tenant git state as `lars`, never as root.** `ssh cloudbongos` lands you as root, where `git config --get remote.origin.url` on a `lars`-owned repo returns **nothing** — which reads exactly like "this instance has no remote" and is wrong. They do: `git@github-instances:example-owner/<slug>.git`. Prefix every probe with `sudo -u lars`.
 - **A scaffold's `migrate` script is not guaranteed.** 21 of the 22 co-tenants have `scripts.migrate`; `mercury` has **no `scripts` block at all** and is started directly by its systemd `ExecStart`, so the normal lane cannot complete on it. `--skip-migrate` gets the install through but silently skips every schema change in the window — check what that window carries before reaching for it, rather than after.
 - **An instance's database moves with its code, on every path** (task 1002002). `bongos upgrade` migrates (step 4) before it restarts; the control-plane runner behind the Deploy door drives it with `PGDATABASE` set to the target instance's own database; provisioning migrates at stand-up. A pinned co-tenant needs nothing extra, because its code only moves through `bongos upgrade`. `--skip-migrate` is the one way out of lockstep. Pinned by `tests/instance_db_migrated_on_code_move.mjs`.
-- **`/version` reports `schemaPending`** (task 1002002): how many core migrations the running code ships that this instance's database has not recorded — `null` when unknown (database unreachable, or a core older than the field). Above 0 is the 2026-07-04 outage shape, where the first query touching those tables fails. Fix: `migrate` against that instance DB with `PGDATABASE` set. The SessionStart `deploy-divergence` line alarms on it for the instance a checkout talks to; `--skip-migrate` above is the usual way to cause one.
+- **`/version` reports `schemaPending`** (task 1002002): how many migrations the running code ships — core, plus each module this process has enabled (DB overrides included, task 1004136) — that this instance's database has not recorded — `null` when unknown (database unreachable, or a core older than the field). Above 0 is the 2026-07-04 outage shape, where the first query touching those tables fails. Fix: `migrate` against that instance DB with `PGDATABASE` set — it reads the same DB overrides, so a module switched on by the hall's Modules toggle gets its migrations too (`npm run migrate -- --print-modules` shows the set it will apply). The SessionStart `deploy-divergence` line alarms on it for the instance a checkout talks to; `--skip-migrate` above is the usual way to cause one.
 - **The health check polls the restart** (fixed in task [#1984](https://example.com/builders#/task/1984)). The service binds its port ~1s after `systemctl restart`, so `--health-url` now polls up to ~30s for a 2xx before reporting a warning — an immediate `fetch failed` no longer means a failed upgrade. (Pre-1984 cores fetched once and spuriously reported `fetch failed`; there, confirm with `is-active` + a manual `curl`.)
 - **The ledger auto-inserts via `PGDATABASE` too** (fixed in task [#1984](https://example.com/builders#/task/1984)). A consumer on `PGDATABASE` + peer auth now gets its `core_upgrades` row written automatically — the channel delegates the insert to `psql -d "$PGDATABASE"`, exactly like `migrate.sh`, so no manual `psql INSERT` is needed. (`DATABASE_URL` still works, via the `pg` driver.) Pre-1984 cores only auto-wrote with `DATABASE_URL`; on those, record the row manually.
 - **No deploy key on the droplet** → deploys/upgrades ride a `git bundle`, not `git pull` (idea 509).

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.940",
+  "version": "1.19.942",
   "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/deploy-divergence.js

@@ -16,7 +16,7 @@
 //   2. UNDEPLOYED — the live instance's coreVersion is behind the CORE_VERSION
 //      on main. A release exists; this instance has not moved its pin to it.
 //   3. SCHEMA BEHIND — live's /version reports schemaPending > 0: its database
-//      lacks core migrations its running code ships (the 2026-07-04 502 outage
+//      lacks migrations its running code ships (the 2026-07-04 502 outage
 //      shape; task 1002002). An instance too old to report it is not flagged.
 //
 // Usage:
@@ -267,7 +267,7 @@ function report(r, { quiet = false } = {}) {
   }
   if (r.schemaBehind) {
     const n = r.live.schemaPending;
-    say(`  ⚠ SCHEMA BEHIND — live's database is missing ${n} core migration${n === 1 ? '' : 's'} its running code ships.`);
+    say(`  ⚠ SCHEMA BEHIND — live's database is missing ${n} migration${n === 1 ? '' : 's'} its running code ships.`);
     say('    The first query that touches them fails (the 2026-07-04 502 was this shape).');
     say('    Fix: run migrate against that instance DB with PGDATABASE set (see docs/recipes/upgrading-the-core.md).');
   }
@@ -319,7 +319,7 @@ function line(r) {
   const versionParts = parts.length;
   const pending = r.schemaBehind ? safeCount(r.live?.schemaPending) : null;
   if (pending) {
-    parts.push(`its database is MISSING ${pending} core migration${pending === 1 ? '' : 's'} the running code ships, so the first query that touches ${pending === 1 ? 'it' : 'them'} fails`);
+    parts.push(`its database is MISSING ${pending} migration${pending === 1 ? '' : 's'} the running code ships, so the first query that touches ${pending === 1 ? 'it' : 'them'} fails`);
   }
   if (!parts.length) return null;
 

package/scripts/gds/run-unit-tests.js

@@ -181,9 +181,12 @@ const INTEGRATION = new Set([
   'session_token_hash_db',
   // task 1002002: the no-false-alarm half of the schema-lag detector. The DB-free
   // sibling (schema_lag) covers the arithmetic against a stub; only a database that
-  // migrate.sh has just run can show the expected core stems equal the recorded ones,
+  // migrate.sh has just run can show the expected stems (core + enabled modules) equal the recorded ones,
   // so a healthy instance reads zero rather than a permanent SCHEMA BEHIND.
   'schema_lag_db',
+  // task 1004137: migrate.sh's module set reads the hall's DB overrides — needs the
+  // override table and a database the real migrate.sh can connect to.
+  'migrate_module_overrides_db',
   'scouting_rollup_fanout', 'session_records',
   // task 1003217: the cost-row RAISE against real SQL. Every claim in it IS the
   // SQL — an ON CONFLICT DO UPDATE guarded to move a row only upward, and a

package/scripts/migrate.sh

@@ -117,6 +117,46 @@ if [ "${1:-}" = "--print-db" ]; then
   exit 0
 fi
 
+# The modules whose migrations the module loop below applies: the SAME set the server mounts routes
+# for, DB overrides included (task 1004137). The server awaits refreshOverrides() before building its
+# app; this read used to skip it, so a module switched on only by the hall's Modules toggle was
+# "disabled — skipping" on every deploy while the next restart mounted its routes against tables that
+# did not exist (the 2026-07-04 outage shape, per module).
+# The overrides are read from the database this run migrates: PGDATABASE is pinned to $DB and
+# DATABASE_URL blanked, because pool.js prefers DATABASE_URL and psql never reads it. FAILS OPEN to the
+# config packs — refreshOverrides() swallows a DB error, and a require that throws (no `pg`) is caught
+# here — so an unreadable override never fails a deploy; stderr is left visible so the fallback is not
+# silent. CORE_ROOT rides in as argv, not interpolated, for the backslash reason above.
+enabled_module_set() {
+  DATABASE_URL='' PGDATABASE="$DB" node -e "
+const path = require('path');
+const core = process.argv[1];
+(async () => {
+  const { enabledModules } = require(path.join(core, 'src/modules'));
+  let pool;
+  try {
+    ({ pool } = require(path.join(core, 'src/bongos/pool')));
+    await require(path.join(core, 'src/bongos/module-overrides')).refreshOverrides();
+  } catch (e) {
+    process.stderr.write('migrate.sh: could not read DB module overrides, using the config packs: ' + e.message + '\n');
+  } finally {
+    if (pool) await pool.end().catch(() => {});
+  }
+  process.stdout.write(enabledModules().join(' '));
+})().catch((e) => {
+  process.stderr.write('migrate.sh: could not read module config: ' + e.message + '\n');
+});
+" "$CORE_ROOT" || true
+}
+
+# Test/ops seam (task 1004137): --print-modules reports the module set this run would migrate, after
+# reading the DB overrides, and exits before any schema work. tests/migrate_module_overrides_db.mjs
+# asserts through it that a hall toggle reaches the module loop.
+if [ "${1:-}" = "--print-modules" ]; then
+  printf '%s\n' "$(enabled_module_set)"
+  exit 0
+fi
+
 # --- Instance-seed policy (task 1704 / ADR 0105) --------------------------
 # OTB/product scope-truth (versions, goals, done_when_criteria) lives in seed
 # migrations under migrations/instance/ (plus a few guarded blocks embedded in the
@@ -279,22 +319,15 @@ fi
 [ "$SEED_INSTANCE" = "on" ] || echo "instance seeds skipped (migrations/instance/) — non-owning / vanilla instance"
 
 # Module-owned migrations (modules/<key>/migrations/*.sql) — applied only when the module is
-# enabled. The enablement is read from the instance's config/modules.json (or the neutral
-# starter). The module CODE lives in the core package (require $CORE_ROOT/src/modules), but the
-# config is instance content (resolveInstanceRoot() falls back to cwd == INSTANCE_ROOT, set
-# above). The stem-key guarantee means moving a migration from migrations/game/ to
-# modules/game/migrations/ does NOT re-run it on prod — schema_migrations is keyed by filename
-# stem alone (ADR 0083 / BV1.R49, task 1418). A vanilla instance leaves game disabled via
-# config/modules.neutral.json.
-NODE_ENABLED_MODULES=$(node -e "
-try {
-  const { enabledModules } = require('$CORE_ROOT/src/modules');
-  process.stdout.write(enabledModules().join(' '));
-} catch(e) {
-  process.stderr.write('migrate.sh: could not read module config: ' + e.message + '\n');
-  process.stdout.write('');
-}
-" 2>/dev/null || true)
+# enabled. The enablement is the instance's config/modules.json (or the neutral starter) plus the
+# DB overrides (enabled_module_set above). The module CODE lives in the core package (require
+# $CORE_ROOT/src/modules), but the config is instance content (resolveInstanceRoot() falls back to
+# cwd == INSTANCE_ROOT, set above). Read HERE, after the core loop, so core_248's
+# module_enablement_overrides table exists even on a from-scratch database. The stem-key guarantee
+# means moving a migration from migrations/game/ to modules/game/migrations/ does NOT re-run it on
+# prod — schema_migrations is keyed by filename stem alone (ADR 0083 / BV1.R49, task 1418). A
+# vanilla instance leaves game disabled via config/modules.neutral.json.
+NODE_ENABLED_MODULES=$(enabled_module_set)
 
 # Modules can be shipped by the CORE package or by the INSTANCE repo, so scan modules/ under
 # BOTH roots. Apply each module key ONCE — today the two roots coincide (so instance-root modules

package/src/bongos/schema-lag.js

@@ -1,6 +1,6 @@
 'use strict';
-// src/bongos/schema-lag.js — does this instance's database carry every core migration the
-// running code ships? (task 1002002)
+// src/bongos/schema-lag.js — does this instance's database carry every migration the running
+// code ships? (task 1002002; modules added in task 1004136)
 //
 // WHY. On 2026-07-04 cloudbongos.com returned 502 on every /me: the deploy had moved the code
 // 22 core migrations past the instance's own database, and nothing said so — /healthz answered
@@ -8,11 +8,13 @@
 // moves an instance's core now migrates that instance's own DB first (bongos upgrade, the runner
 // behind the Deploy door, provisioning — pinned by tests/instance_db_migrated_on_code_move.mjs),
 // but a skipped or failed step would recreate that outage just as silently. This is the detector:
-// the core migration stems the installed package ships that schema_migrations does not record.
+// the migration stems the running code expects that schema_migrations does not record.
 //
-// CORE ONLY, on purpose. migrate.sh applies every core migrations/*.sql on every instance, so a
-// missing core stem is always a real gap. Module and instance-seed migrations are per-instance
-// opt-ins, and counting them would alarm on a module that is simply off.
+// WHAT IS EXPECTED is every migration the code this process actually serves depends on: every
+// core migrations/*.sql, plus modules/<key>/migrations/*.sql for each module isModuleEnabled
+// says is on — the same gate its routes mount behind, DB overrides included. A module that is
+// off is expected nothing, so it can never alarm. Instance seeds (migrations/instance/) are an
+// opt-in no running code depends on, so they are never counted.
 //
 // Surfaced as `schemaPending` on /version (a count, never the names) and logged at boot;
 // scripts/gds/deploy-divergence.js turns a non-zero count into the SessionStart alarm.
@@ -20,6 +22,8 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { resolveCoreRoot } = require('../instance-config');
+const { isModuleEnabled } = require('../modules');
+const { discovered } = require('../module-loader/loader');
 const { pool } = require('./pool');
 const log = require('./logger').logger.child({ src: 'schema-lag' });
 
@@ -28,14 +32,23 @@ const CORE_MIGRATIONS_DIR = path.join(resolveCoreRoot(), 'migrations');
 // query runs at most this often; between refreshes the last answer is served.
 const REFRESH_MS = 60 * 1000;
 
-/** The stems migrate.sh keys schema_migrations by, for the core's top-level *.sql files. */
-function coreMigrationStems(dir = CORE_MIGRATIONS_DIR) {
+/** The stems migrate.sh keys schema_migrations by, for the *.sql files directly in `dir`. */
+function migrationStems(dir = CORE_MIGRATIONS_DIR) {
   return fs.readdirSync(dir, { withFileTypes: true })
     .filter((e) => e.isFile() && e.name.endsWith('.sql'))
     .map((e) => e.name.slice(0, -'.sql'.length))
     .sort();
 }
 
+/** Migration stems of every module this process serves, from the dir it was discovered in. */
+function enabledModuleMigrationStems({ loaded = discovered().loaded, isEnabled = isModuleEnabled } = {}) {
+  return loaded
+    .filter((m) => isEnabled(m.key))
+    .map((m) => path.join(m.dir, 'migrations'))
+    .filter((dir) => fs.existsSync(dir))
+    .flatMap((dir) => migrationStems(dir));
+}
+
 /** Shipped stems the database has not recorded. PURE. */
 function pendingStems(shipped, applied) {
   const have = new Set(applied);
@@ -49,25 +62,27 @@ let inflight = null;
  * Re-read schema_migrations and cache the gap. Never throws: an unreadable database or
  * migrations dir caches null — "unknown" — which no reader treats as an alarm.
  */
-async function refreshSchemaLag({ db = pool, dir = CORE_MIGRATIONS_DIR, now = Date.now } = {}) {
+async function refreshSchemaLag({
+  db = pool, dir = CORE_MIGRATIONS_DIR, moduleStems = enabledModuleMigrationStems, now = Date.now,
+} = {}) {
   const before = last.pending;
   let pending = null;
   try {
     const { rows } = await db.query('SELECT version FROM schema_migrations');
-    pending = pendingStems(coreMigrationStems(dir), rows.map((r) => r.version));
+    pending = pendingStems([...migrationStems(dir), ...moduleStems()], rows.map((r) => r.version));
   } catch (err) {
-    log.warn({ err: err && err.message }, 'could not compare schema_migrations with the core migrations');
+    log.warn({ err: err && err.message }, 'could not compare schema_migrations with the migrations the running code ships');
   }
   last = { pending, checkedAt: now() };
   if (pending && pending.length && (!before || before.length !== pending.length)) {
     log.error({ pending: pending.length, first: pending.slice(0, 5) },
-      'this database is missing core migrations the running code ships — run migrate against this instance DB before its next query touches them');
+      'this database is missing migrations the running code ships (core, or an enabled module) — run migrate against this instance DB before its next query touches them');
   }
   return pending;
 }
 
 /**
- * The last-known count of missing core migrations, or null when unknown. Kicks a background
+ * The last-known count of missing migrations, or null when unknown. Kicks a background
  * refresh when the answer is older than REFRESH_MS, and never waits for it.
  */
 function schemaPending({ now = Date.now, refresh = refreshSchemaLag } = {}) {
@@ -77,4 +92,6 @@ function schemaPending({ now = Date.now, refresh = refreshSchemaLag } = {}) {
   return last.pending ? last.pending.length : null;
 }
 
-module.exports = { coreMigrationStems, pendingStems, refreshSchemaLag, schemaPending, REFRESH_MS };
+module.exports = {
+  migrationStems, enabledModuleMigrationStems, pendingStems, refreshSchemaLag, schemaPending, REFRESH_MS,
+};

package/src/bongos/serve-internal.js

@@ -583,7 +583,7 @@ function mountInternalSurfaces(app) {
     //   the throwaway `updateCanary` proof marker was removed in phase E.)
     let coreVersion = null;
     try { coreVersion = require('../module-api').CORE_VERSION; } catch { /* fail-soft: version unknown */ }
-    // schemaPending — core migrations this code ships that the instance DB has not applied
+    // schemaPending — migrations this code ships (core + enabled modules') that the instance DB has not applied
     //   (null = unknown). Non-zero is the 2026-07-04 outage shape (task 1002002).
     res.json({ ...buildInfo(), coreVersion, schemaPending: schemaPending() });
   });

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.940'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.942'; // 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/deploy_divergence_line.mjs

@@ -260,7 +260,7 @@ test('settings.json stays OUT of the published package', () => {
 });
 
 // ── schema behind (task 1002002) ────────────────────────────────────────────
-// /version's schemaPending: core migrations the running code ships that live's DB
+// /version's schemaPending: migrations (core + enabled modules') the running code ships that live's DB
 // lacks. The 2026-07-04 502 was this shape, and nothing reported it.
 
 const schemaOnly = {
@@ -269,17 +269,17 @@ const schemaOnly = {
   behind: false, hasUnreleased: false, unreleased: { count: 0 }, schemaBehind: true,
 };
 
-test('a database missing core migrations is named on the one line, with its own advice', () => {
+test('a database missing migrations is named on the one line, with its own advice', () => {
   const s = line(schemaOnly);
-  assert.match(s, /MISSING 3 core migrations the running code ships/);
+  assert.match(s, /MISSING 3 migrations the running code ships/);
   assert.match(s, /Run migrate against that instance DB/);
   assert.doesNotMatch(s, /Merging to main deploys nothing/, 'the version advice is for version gaps only');
   assert.equal(s.split('\n').length, 1);
-  assert.match(line({ ...schemaOnly, live: { ...schemaOnly.live, schemaPending: 1 } }), /MISSING 1 core migration the/);
+  assert.match(line({ ...schemaOnly, live: { ...schemaOnly.live, schemaPending: 1 } }), /MISSING 1 migration the/);
 
   const both = line({ ...schemaOnly, behind: true, live: { coreVersion: '1.19.56', schemaPending: 2 } });
   assert.match(both, /1\.19\.56/);
-  assert.match(both, /MISSING 2 core migrations/);
+  assert.match(both, /MISSING 2 migrations/);
   assert.match(both, /Merging to main deploys nothing/);
 });
 

package/tests/migrate_module_overrides_db.mjs

@@ -0,0 +1,91 @@
+// tests/migrate_module_overrides_db.mjs — migrate.sh migrates a module the hall switched on (task 1004137).
+//
+// The hall's Modules toggle writes module_enablement_overrides, and the server reads that table
+// before it mounts any routes. migrate.sh used to pick its module set in a fresh process that never
+// read it, so a module on ONLY by override was skipped on every deploy while the next restart
+// mounted its routes against tables that did not exist. This drives the real migrate.sh through its
+// --print-modules seam (the same function its module loop calls) against a real database.
+//
+// Integration lane: needs Postgres plus the PG* env migrate.sh connects with (the lane sets both);
+// self-skips when no Postgres is reachable. Leaves the override table as it found it.
+//
+// Run:  DATABASE_URL=postgres://... node tests/migrate_module_overrides_db.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { pool } = require('../src/bongos/pool.js');
+const { moduleScopeKey } = require('../src/modules.js');
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const MIGRATE = path.join(REPO_ROOT, 'scripts', 'migrate.sh');
+// Ships a migration, meters no spend and is off in the packs, so the override alone decides it.
+const MODULE = 'discord';
+
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`migrate_module_overrides_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const { rows: [{ db }] } = await pool.query('SELECT current_database() AS db');
+const scope = moduleScopeKey();
+
+function printModules(overrides = {}) {
+  const env = { ...process.env, PGDATABASE: db, ...overrides };
+  delete env.INIT_CWD;
+  const out = execFileSync('bash', [MIGRATE, '--print-modules'], {
+    cwd: REPO_ROOT, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return out.trim().split(/\s+/).filter(Boolean);
+}
+
+const setOverride = (enabled) => pool.query(
+  `INSERT INTO module_enablement_overrides (scope, module_key, enabled) VALUES ($1, $2, $3)
+   ON CONFLICT (scope, module_key) DO UPDATE SET enabled = EXCLUDED.enabled`,
+  [scope, MODULE, enabled],
+);
+
+const { rows: prior } = await pool.query(
+  'SELECT enabled, set_by, set_at FROM module_enablement_overrides WHERE scope = $1 AND module_key = $2',
+  [scope, MODULE],
+);
+
+try {
+  await pool.query('DELETE FROM module_enablement_overrides WHERE scope = $1 AND module_key = $2', [scope, MODULE]);
+  const packs = printModules();
+  assert.ok(packs.length > 0, 'with no override the pack set still resolves (not an empty read)');
+  assert.ok(!packs.includes(MODULE), `precondition: ${MODULE} is off in the packs, so only an override can turn it on`);
+  console.log(`  ok  no override: ${MODULE} is not migrated`);
+
+  await setOverride(true);
+  const toggled = printModules();
+  assert.ok(toggled.includes(MODULE), `a hall toggle ON must reach migrate's module set, got: ${toggled.join(' ')}`);
+  assert.deepEqual(toggled.filter((m) => m !== MODULE), packs, 'and changes nothing else');
+  console.log(`  ok  override on: ${MODULE} is migrated`);
+
+  // Fail-open: an override migrate cannot read falls back to the packs, never to "no modules".
+  // The override row is still ON here, so only the fallback can produce the pack set.
+  const unreadable = printModules({ PGHOST: '127.0.0.1', PGPORT: '1' });
+  assert.deepEqual(unreadable, packs, 'an unreachable override database resolves exactly the pack set');
+  console.log('  ok  unreadable overrides fall back to the packs');
+} finally {
+  if (prior.length) {
+    await pool.query(
+      `INSERT INTO module_enablement_overrides (scope, module_key, enabled, set_by, set_at)
+            VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (scope, module_key)
+         DO UPDATE SET enabled = EXCLUDED.enabled, set_by = EXCLUDED.set_by, set_at = EXCLUDED.set_at`,
+      [scope, MODULE, prior[0].enabled, prior[0].set_by, prior[0].set_at],
+    );
+  } else {
+    await pool.query('DELETE FROM module_enablement_overrides WHERE scope = $1 AND module_key = $2', [scope, MODULE]);
+  }
+  await pool.end().catch(() => {});
+}

package/tests/schema_lag.mjs

@@ -1,4 +1,5 @@
-// tests/schema_lag.mjs — the schema-lag detector behind /version's schemaPending (task 1002002).
+// tests/schema_lag.mjs — the schema-lag detector behind /version's schemaPending (task 1002002;
+// enabled modules' migrations, task 1004136).
 //
 // DB-free: every database read goes through an injected stub. The real-SQL half — that a
 // database migrate.sh has just run reports ZERO pending, i.e. the stems this module expects
@@ -13,10 +14,23 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
-  coreMigrationStems, pendingStems, refreshSchemaLag, schemaPending, REFRESH_MS,
+  migrationStems, enabledModuleMigrationStems, pendingStems, refreshSchemaLag, schemaPending, REFRESH_MS,
 } from '../src/bongos/schema-lag.js';
+import { setModuleOverrides } from '../src/modules.js';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const none = () => [];
+
+/** A modules/ root: `on` and `off` each ship a migration; `bare` has no migrations/ dir. */
+function tmpModules() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'schema-lag-mod-'));
+  for (const [key, files] of [['on', ['on_001_a.sql', 'on_002_b.sql']], ['off', ['off_001_a.sql']]]) {
+    fs.mkdirSync(path.join(root, key, 'migrations'), { recursive: true });
+    for (const f of files) fs.writeFileSync(path.join(root, key, 'migrations', f), '-- x\n');
+  }
+  fs.mkdirSync(path.join(root, 'bare'));
+  return ['on', 'off', 'bare'].map((key) => ({ key, dir: path.join(root, key) }));
+}
 
 function tmpMigrations() {
   const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'schema-lag-'));
@@ -36,12 +50,12 @@ test('pendingStems lists shipped stems the database has not recorded', () => {
   assert.deepEqual(pendingStems(['a'], ['a']), []);
 });
 
-test('coreMigrationStems reads top-level .sql stems only, sorted', () => {
-  assert.deepEqual(coreMigrationStems(tmpMigrations()), ['001_init', 'core_002_add', 'core_003_more']);
+test('migrationStems reads top-level .sql stems only, sorted', () => {
+  assert.deepEqual(migrationStems(tmpMigrations()), ['001_init', 'core_002_add', 'core_003_more']);
 });
 
 test('the default directory is the installed core migrations', () => {
-  const stems = coreMigrationStems();
+  const stems = migrationStems();
   const onDisk = fs.readdirSync(path.join(ROOT, 'migrations')).filter((f) => f.endsWith('.sql'));
   assert.equal(stems.length, onDisk.length);
   assert.ok(stems.includes('003_pms'), 'legacy bare stems are core migrations too');
@@ -49,19 +63,49 @@ test('the default directory is the installed core migrations', () => {
 
 test('a database missing core migrations reports them; a current one reports an empty list', async () => {
   const dir = tmpMigrations();
-  assert.deepEqual(await refreshSchemaLag({ db: dbWith(['001_init']), dir }), ['core_002_add', 'core_003_more']);
-  assert.deepEqual(await refreshSchemaLag({ db: dbWith(['001_init', 'core_002_add', 'core_003_more']), dir }), []);
+  assert.deepEqual(await refreshSchemaLag({ db: dbWith(['001_init']), dir, moduleStems: none }), ['core_002_add', 'core_003_more']);
+  assert.deepEqual(await refreshSchemaLag({ db: dbWith(['001_init', 'core_002_add', 'core_003_more']), dir, moduleStems: none }), []);
+});
+
+test('only enabled modules are expected to carry their migrations; a module that is off never alarms', () => {
+  const loaded = tmpModules();
+  const isEnabled = (key) => key !== 'off';
+  assert.deepEqual(enabledModuleMigrationStems({ loaded, isEnabled }), ['on_001_a', 'on_002_b'],
+    'an enabled module with no migrations/ dir contributes nothing and does not throw');
+  assert.deepEqual(enabledModuleMigrationStems({ loaded, isEnabled: () => false }), []);
+});
+
+test('an enabled module whose migrations never ran is counted beside the core gap', async () => {
+  const dir = tmpMigrations();
+  const core = ['001_init', 'core_002_add', 'core_003_more'];
+  const moduleStems = () => enabledModuleMigrationStems({ loaded: tmpModules(), isEnabled: (key) => key === 'on' });
+  assert.deepEqual(await refreshSchemaLag({ db: dbWith([...core, 'on_001_a']), dir, moduleStems }), ['on_002_b']);
+  assert.deepEqual(await refreshSchemaLag({ db: dbWith([...core, 'on_001_a', 'on_002_b']), dir, moduleStems }), []);
+});
+
+test('the default expectation follows the server\'s own enablement, DB overrides included', () => {
+  // `discord` ships a migration and meters no spend, so the override alone decides it. migrate.sh
+  // reads the same override layer (tests/migrate_module_overrides_db.mjs, task 1004137).
+  const STEM = 'discord_001_board_messages';
+  try {
+    setModuleOverrides({ discord: true });
+    assert.ok(enabledModuleMigrationStems().includes(STEM), 'switched on by override: its migration is expected');
+    setModuleOverrides({ discord: false });
+    assert.ok(!enabledModuleMigrationStems().includes(STEM), 'switched off by override: nothing expected');
+  } finally {
+    setModuleOverrides({});
+  }
 });
 
 test('an unreadable database is unknown (null), never an alarm and never a throw', async () => {
   const down = { query: async () => { throw new Error('ECONNREFUSED'); } };
-  assert.equal(await refreshSchemaLag({ db: down, dir: tmpMigrations() }), null);
+  assert.equal(await refreshSchemaLag({ db: down, dir: tmpMigrations(), moduleStems: none }), null);
 });
 
 test('schemaPending serves the cached count and refreshes at most once per window', async () => {
   const dir = tmpMigrations();
   const t0 = 1_000_000;
-  await refreshSchemaLag({ db: dbWith(['001_init']), dir, now: () => t0 });
+  await refreshSchemaLag({ db: dbWith(['001_init']), dir, moduleStems: none, now: () => t0 });
 
   let calls = 0;
   const refresh = () => { calls += 1; return new Promise(() => {}); }; // never settles: stays in flight

package/tests/schema_lag_db.mjs

@@ -29,7 +29,7 @@ try {
 
 try {
   const pending = await refreshSchemaLag();
-  assert.deepEqual(pending, [], `a freshly migrated database must report no pending core migrations, got: ${JSON.stringify(pending)}`);
+  assert.deepEqual(pending, [], `a freshly migrated database must report no pending migrations (core or enabled module), got: ${JSON.stringify(pending)}`);
   assert.equal(schemaPending(), 0, 'and /version serves 0 — known-current, not unknown (null)');
   console.log('  ok  a freshly migrated database reports schemaPending 0');
 } finally {