@bongos/core 1.19.941 → 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.941",
-  "core_contract": "1.19.941",
-  "source_commit": "4063c1c70284ec0850ace02a6ac26e9ecf0ecc20",
+  "core_version": "1.19.942",
+  "core_contract": "1.19.942",
+  "source_commit": "1e45821468069b9d8f26ed2f7dbf1bbf647ea4b8",
   "source_ref": "HEAD",
-  "built_at": "2026-09-21T20:39:58.651Z",
+  "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": "ede1bb5b48026ef02ab4df39fae783c3eb2e648c7bafec28010174f4ab8ed076",
+  "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": "57bcf700f7f794da9b36f6cd6a88d5c44ac153a6ef246c7be7841ace8e6908ce"
+      "sha256": "cf5f371ef80387f8344682a639e736c8cc3240debb4ee97106dfc2525e402e97"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2927,7 +2927,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "f16df23bfcb5e1ce02813222bf9a8b190b458749939f5074fbe142d9430b1bad"
+      "sha256": "0df57ea34114fb1ae81389458334b392d768fc83d9e82eb00fa917219189de87"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -8002,12 +8002,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "7930ba5349243c9641adef8865a4d868521f9c841c174dda327942a599304ae8"
+      "sha256": "04da7afdf07b5eacb7b5d8e18f034a45e62c318eed546facfa4e65480f5a6292"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f19114e6c03c1eb79f70855f08efae1b58167aa4939cb149bcd50894f2ca7c36"
+      "sha256": "79d643dab7e8bf794763c95cfa6f05200054d4aa2be271b61805954b1b82eb83"
     },
     {
       "path": "public-docs/index.html",
@@ -9107,7 +9107,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "40d1b5bf4c82536cac2a666e81c4909f99bc26796db0c9e9c928678032948c91"
+      "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": "b6443663bc60287242164c530f864504514050b648b6c9736454fd0e9ab4319f"
+      "sha256": "b84a237b9fe9ce9f905ae0ca72e7f82eb08670397eb7e6c88c114c62afcf81a8"
     },
     {
       "path": "src/bongos/secret-box.js",
@@ -10012,7 +10012,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "168b1b8002437b7a7bc5b42ae2f68af01c31b007473a09cdc0f1bb98338f662a"
+      "sha256": "ea1889449a3dab8921a6d4ce4fc539c8c550aef3eedc14d22493a26cd6af1bcc"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -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,7 +13457,7 @@
     {
       "path": "tests/schema_lag.mjs",
       "mode": "0000644",
-      "sha256": "d592f20f08695dfbe2806e195c4d2a6e81bc0ea6cec4f1c2168609280a197c09"
+      "sha256": "af0db545b71f9cc3b88ae0a9cd09e909d9956326dd0aba8bb02a330e2cb21c8b"
     },
     {
       "path": "tests/schema_lag_db.mjs",

package/docs/module-api-changelog.md

@@ -2356,5 +2356,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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 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.
+- **`/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.941",
+  "version": "1.19.942",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.941",
+      "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.941",
+  "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/run-unit-tests.js

@@ -184,6 +184,9 @@ const INTEGRATION = new Set([
   // 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

@@ -16,9 +16,6 @@
 // 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.
 

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.941'; // 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/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

@@ -84,8 +84,8 @@ test('an enabled module whose migrations never ran is counted beside the core ga
 });
 
 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).
+  // `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 });