@bongos/core 1.19.940 → 1.19.941

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "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.941",
+  "core_contract": "1.19.941",
+  "source_commit": "4063c1c70284ec0850ace02a6ac26e9ecf0ecc20",
   "source_ref": "HEAD",
-  "built_at": "2026-09-21T19:54:33.696Z",
+  "built_at": "2026-09-21T20:39:58.651Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 511,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2876,
-  "tree_sha256": "a7edb7e2d7278cda02f1dc7d69eb957b0702345c2f059ead3049463b6fb17ff7",
+  "tree_sha256": "ede1bb5b48026ef02ab4df39fae783c3eb2e648c7bafec28010174f4ab8ed076",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2677,7 +2677,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b0dcdad0ab90dc948a111f4bb26a39ffa028bd17907ad7ffbadbc3ec424d54c6"
+      "sha256": "57bcf700f7f794da9b36f6cd6a88d5c44ac153a6ef246c7be7841ace8e6908ce"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2927,7 +2927,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "147fe7408c7e86487c2cd99198074f3591c7b956c0debd80b7b0730803940571"
+      "sha256": "f16df23bfcb5e1ce02813222bf9a8b190b458749939f5074fbe142d9430b1bad"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -8002,12 +8002,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d319db2c2f341bea9b0f59dd6f2c826a68a155e620b3b6e8809ef8e35390b7bf"
+      "sha256": "7930ba5349243c9641adef8865a4d868521f9c841c174dda327942a599304ae8"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0692c686bc978e5f8ada5fa1f563bf40bdc9fde2a548a8ca47f21e089010bbbb"
+      "sha256": "f19114e6c03c1eb79f70855f08efae1b58167aa4939cb149bcd50894f2ca7c36"
     },
     {
       "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": "40d1b5bf4c82536cac2a666e81c4909f99bc26796db0c9e9c928678032948c91"
     },
     {
       "path": "scripts/gds/runner-drift.js",
@@ -9972,7 +9972,7 @@
     {
       "path": "src/bongos/schema-lag.js",
       "mode": "0000644",
-      "sha256": "bafe3453eff53cb80ef0eb3ca5894d7ff2fc4a2480e80595869d8d9838d06a42"
+      "sha256": "b6443663bc60287242164c530f864504514050b648b6c9736454fd0e9ab4319f"
     },
     {
       "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": "168b1b8002437b7a7bc5b42ae2f68af01c31b007473a09cdc0f1bb98338f662a"
     },
     {
       "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",
@@ -13452,12 +13452,12 @@
     {
       "path": "tests/schema_lag.mjs",
       "mode": "0000644",
-      "sha256": "90e5cdc6648856a027c67df41e39fee6699d7bae56b79bc41cefbb2d249c86a9"
+      "sha256": "d592f20f08695dfbe2806e195c4d2a6e81bc0ea6cec4f1c2168609280a197c09"
     },
     {
       "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,7 @@ 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)
 ---------------------------------------------------------------------------
 ```

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. Exception: `migrate` does not read DB overrides yet ([task 1004137](https://cloudbongos.com/builders#/task/1004137)), so a module switched on only by the hall's Modules toggle stays pending. Until that lands, also switch it on in `config/modules.json` (or the `<PREFIX>_MODULE_<KEY>` env) before migrating. 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.941",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.940",
+      "version": "1.19.941",
       "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.941",
   "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,7 +181,7 @@ 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',
   'scouting_rollup_fanout', 'session_records',

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,16 @@
 // 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.
+//
+// KNOWN GAP: migrate.sh does not read DB overrides (task 1004137), so for a module on ONLY by
+// override this reports a true gap that running migrate does not yet close.
 //
 // 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 +25,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 +35,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 +65,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 +95,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.941'; // 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/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. A DB
+  // override is the layer migrate.sh's fresh process never loads (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 {