@bongos/core 1.19.882 → 1.19.884

package/src/bongos/module-overrides.js

@@ -0,0 +1,117 @@
+// src/bongos/module-overrides.js — durable module enablement (task 1002857,
+// migration core_248).
+//
+// WHAT THIS FIXES. The hall's Modules-tab toggle wrote config/modules.json and
+// reloaded the cache, so the effect was immediate on the box — but that file is
+// the committed instance pack, and the pull-deploy runs `git reset --hard
+// origin/main`. The toggle therefore reverted on the next deploy, silently,
+// unless a human remembered to commit it. This module moves the durable half of
+// that decision into the database, where the rest of this instance's live state
+// already lives.
+//
+// THE SHAPE, and why it is this shape. src/modules.js's loadModules() is
+// SYNCHRONOUS — a lazy cached singleton every caller reaches through modules() —
+// and making it async would ripple into effectively every consumer of a module
+// flag. So the database is never read inline. Instead this file reads the
+// overrides ONCE per refresh and hands src/modules.js a plain snapshot, which its
+// pure resolver treats as one more precedence layer. The refresh points are the
+// two moments the answer can change: server boot, and a write through this file.
+//
+// FAILURE IS A NO-OP, DELIBERATELY. Every function here swallows its database
+// error and leaves the snapshot alone. An empty snapshot means "no opinion", not
+// "everything off", so an unreachable database resolves modules exactly as this
+// instance resolved them before the table existed. The alternative — letting a
+// DB outage change which modules are mounted — would make a read-path dependency
+// out of a feature whose entire purpose is durability.
+
+const { pool } = require('./pool');
+// Named imports rather than a namespace object (task 1004052 strand walk): knip cannot
+// follow property access on a CommonJS namespace, so reaching these through one made
+// moduleScopeKey and setModuleOverrides read as unused exports of src/modules.js and
+// tripped the dead-code ratchet — which is what held this branch out of main for 20h.
+const { moduleScopeKey, setModuleOverrides } = require('../modules');
+
+// One log line per distinct failure reason, not per call: refreshOverrides() runs
+// on boot and after every toggle, and a persistently unreachable database would
+// otherwise fill the log with the same sentence.
+const _warned = new Set();
+function warnOnce(reason, err, log = console) {
+  if (_warned.has(reason)) return;
+  _warned.add(reason);
+  log.warn(
+    `[bongos] module overrides ${reason}: ${err && err.message}. Module enablement falls back to the `
+    + 'config packs and env for now — no module changes state because of this.',
+  );
+}
+
+// Read every override for THIS instance's scope and install it as the live
+// snapshot. Returns the resolved module set on success, or null if the database
+// could not be read (in which case the previous snapshot stands).
+async function refreshOverrides({ scope = moduleScopeKey() } = {}) {
+  let rows;
+  try {
+    ({ rows } = await pool.query(
+      'SELECT module_key, enabled FROM module_enablement_overrides WHERE scope = $1',
+      [scope],
+    ));
+  } catch (err) {
+    warnOnce('could not be read', err);
+    return null;
+  }
+  const map = {};
+  for (const r of rows) map[r.module_key] = r.enabled;
+  return setModuleOverrides(map);
+}
+
+// Record an operator's toggle and make it live in the same call. The UPSERT is
+// keyed on (scope, module_key) so a second toggle of the same module updates the
+// row rather than accumulating history — the audit trail this table carries is
+// "who set the CURRENT state, and when", which is what an operator looking at a
+// surprising module needs. Throws on a write failure: unlike a read, a write that
+// silently did nothing would tell the operator their toggle was durable when it
+// was not, which is the original bug wearing a different hat.
+async function setOverride(moduleKey, enabled, { builderId = null, scope = moduleScopeKey() } = {}) {
+  await pool.query(
+    `INSERT INTO module_enablement_overrides (scope, module_key, enabled, set_by, set_at)
+          VALUES ($1, $2, $3, $4, now())
+     ON CONFLICT (scope, module_key)
+       DO UPDATE SET enabled = EXCLUDED.enabled, set_by = EXCLUDED.set_by, set_at = now()`,
+    [scope, moduleKey, enabled, builderId],
+  );
+  return refreshOverrides({ scope });
+}
+
+// Drop the override and fall back to whatever the packs and env say. This is the
+// only way back to "no opinion": setting the override to the pack's own value
+// would look identical in the UI but would keep outranking a later edit to the
+// committed pack.
+async function clearOverride(moduleKey, { scope = moduleScopeKey() } = {}) {
+  await pool.query(
+    'DELETE FROM module_enablement_overrides WHERE scope = $1 AND module_key = $2',
+    [scope, moduleKey],
+  );
+  return refreshOverrides({ scope });
+}
+
+// The rows behind the current snapshot, for the hall's Modules tab: who set each
+// override and when, which the file-write path never recorded. Read-only and
+// failure-tolerant for the same reason refreshOverrides is — a broken audit read
+// must not break the page that lists the modules.
+async function listOverrides({ scope = moduleScopeKey() } = {}) {
+  try {
+    const { rows } = await pool.query(
+      `SELECT o.module_key, o.enabled, o.set_by, o.set_at, b.github_login AS set_by_login
+         FROM module_enablement_overrides o
+         LEFT JOIN builders b ON b.id = o.set_by
+        WHERE o.scope = $1
+        ORDER BY o.module_key`,
+      [scope],
+    );
+    return rows;
+  } catch (err) {
+    warnOnce('could not be listed', err);
+    return [];
+  }
+}
+
+module.exports = { refreshOverrides, setOverride, clearOverride, listOverrides };

package/src/bongos/routes/modules.js

@@ -23,23 +23,28 @@
 // /backup/trigger — it changes running behavior for the whole instance (or
 // files something into a shared review queue), not just the caller.
 //
-// Persistence note: /modules/:key/enable writes config/modules.json on disk
-// and reloads the in-process cache, so the effect is immediate on this box.
-// Like any other hand-edit of that file, surviving the next `git reset --hard`
-// deploy needs the change committed — this route does not auto-commit (an
-// HTTP handler auto-pushing to main bypasses the ship/grade/deploy pipeline,
-// which the project's trust boundary treats as a bigger risk than a toggle
-// that needs a human/agent to land it properly). Captured as a follow-up
-// idea: durable (DB-backed) module enablement that survives a deploy with no
-// extra step.
+// Persistence note (task 1002857, migration core_248, ADR 0309):
+// /modules/:key/enable writes a row in module_enablement_overrides and reloads
+// the in-process cache, so the toggle is both immediate on this box AND durable
+// past the next deploy. It used to write config/modules.json, which the
+// pull-deploy's `git reset --hard origin/main` then reverted unless a human
+// remembered to commit it — silently, which was the bug.
+//
+// The route still does not auto-commit, and that has not changed: an HTTP
+// handler pushing to main would bypass the ship/grade/deploy pipeline and the
+// ADR 0016 trust boundary. Durability comes from the database, where this
+// instance's live state already lives, not from a writer on main.
+//
+// Precedence, stated where the toggle is: neutral pack -> instance pack -> THIS
+// override -> env. An operator can still force a module off on one box with
+// <PREFIX>_MODULE_<KEY>, and that env knob outranks anything this route writes —
+// deliberately, because the incident lever must not need a reachable database.
 //
 // Why the review queue is a table in THIS instance's own DB (not a live
 // cross-repo call to the extracted core repo): see
 // docs/adr/0135-module-upstream-submission-interim-queue.md.
 
 const express = require('express');
-const fs = require('node:fs');
-const path = require('node:path');
 const auth = require('../auth');
 const { asyncHandler, validateOrRespond, LIMITS } = require('./_helpers');
 const loader = require('../../module-loader/loader');
@@ -53,6 +58,10 @@ const modulesLib = require('../../modules');
 // server process.
 const moduleCli = require('../../../scripts/gds/module');
 const moduleSubmissions = require('../module-submissions');
+// Named imports, not a namespace object (task 1004052 strand walk): knip cannot follow
+// property access on a CommonJS namespace, so reaching these through one made them read
+// as unused exports and tripped the dead-code ratchet that held this branch out of main.
+const { listOverrides, setOverride } = require('../module-overrides');
 
 // A packaged submission embeds every file's content (base64) — cap the total
 // so a runaway/misbuilt module can't bloat the review-queue table. Generous
@@ -75,11 +84,6 @@ function sourceRepoLabel() {
   } catch { return null; }
 }
 
-function readInstanceConfig() {
-  try { return JSON.parse(fs.readFileSync(modulesLib.INSTANCE_PATH, 'utf8')); }
-  catch (e) { if (e.code === 'ENOENT') return { modules: {} }; throw e; }
-}
-
 // The catalog model (src/module-loader/catalog.js) is the SINGLE builder behind
 // both surfaces — this route and `bongos module list` — so the hall and the
 // terminal can never disagree about who built a module or which tree it ships
@@ -108,8 +112,25 @@ module.exports = function buildModulesRouter() {
   // rank: any-builder — list every on-disk module with attribution + provenance (same read gate as the atlas/primer pages).
   router.get('/modules', auth.requireBuilder, asyncHandler('GET /modules', async (_req, res) => {
     const all = listModules();
+    // WHICH LAYER PRODUCED EACH STATE, so an operator can tell a durable override
+    // from a committed pack value from an env knob without opening a shell
+    // (task 1002857). Both reads are failure-tolerant, so a broken override table
+    // degrades this to the listing it was before rather than breaking the tab.
+    const resolvedSet = modulesLib.modules();
+    const sources = (resolvedSet && resolvedSet.sources) || {};
+    const overrideRows = await listOverrides();
+    const byKey = new Map(overrideRows.map((r) => [r.module_key, r]));
+    for (const m of all) {
+      m.enabled_source = sources[m.key] || 'default';
+      m.override = byKey.has(m.key)
+        ? { enabled: byKey.get(m.key).enabled, set_by: byKey.get(m.key).set_by_login || null, set_at: byKey.get(m.key).set_at }
+        : null;
+    }
     res.json({
       modules: all,
+      // The override scope this process runs under — two instances sharing one
+      // database differ only here, so a surprising answer is diagnosable.
+      scope: modulesLib.moduleScopeKey(),
       own_built: all.filter((m) => m.provenance === 'own').length,
       core_loaded: all.filter((m) => m.provenance === 'core').length,
       // The catalog roll-up (task 1001772): how many modules the core ships that
@@ -137,15 +158,27 @@ module.exports = function buildModulesRouter() {
         return res.fail('not_found', { status: 404, message: `No on-disk module "${key}" — only a real modules/<key>/ can be toggled.` });
       }
 
-      const cfg = readInstanceConfig();
-      if (!cfg.modules || typeof cfg.modules !== 'object') cfg.modules = {};
-      cfg.modules[key] = enabled;
-      fs.mkdirSync(path.dirname(modulesLib.INSTANCE_PATH), { recursive: true });
-      fs.writeFileSync(modulesLib.INSTANCE_PATH, JSON.stringify(cfg, null, 2) + '\n');
-      modulesLib.reload();
+      // setOverride throws if the write fails, and that is the point: a toggle
+      // that reported success while persisting nothing would be the original bug
+      // with better manners. The read path (refreshOverrides) is failure-tolerant;
+      // the write path deliberately is not.
+      const resolvedSet = await setOverride(key, enabled, { builderId: req.builder && req.builder.id });
+      const effective = resolvedSet ? resolvedSet[key] === true : enabled;
 
       console.log(`[gds] module "${key}" ${enabled ? 'enabled' : 'disabled'} by builder ${req.builder && req.builder.id}`);
-      res.json({ ok: true, key, enabled, note: 'Live on this box now. Persisting past the next deploy needs config/modules.json committed.' });
+      res.json({
+        ok: true,
+        key,
+        enabled,
+        // What the module ACTUALLY resolved to, which is not always what was asked:
+        // an env override or the spend guard outranks this write, and an operator
+        // who is not told so will re-click the toggle and blame the feature.
+        effective,
+        source: (resolvedSet && resolvedSet.sources && resolvedSet.sources[key]) || 'override',
+        note: effective === enabled
+          ? 'Live on this box now, and durable — it survives the next deploy.'
+          : `Recorded, but "${key}" still resolves to ${effective}: a higher-precedence layer (env, or the spend guard) is winning.`,
+      });
     }));
 
   // POST /api/bongos/modules/:key/submit — ADR 0107 §1 upstreaming submission.

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.882'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.884'; // 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/src/modules.js

@@ -186,6 +186,12 @@ function resolveModules({
   // is the one that reads the real posture, and the one that fails closed when it
   // cannot.
   spendGuard = NO_SPEND_RISK, warn = warnSpendRefusal,
+  // THE DB OVERRIDE LAYER (task 1002857) — a { <moduleKey>: boolean } snapshot of
+  // module_enablement_overrides for this scope, injected rather than read, so this
+  // resolver stays pure and synchronous. Defaulted to {} so every existing caller
+  // resolves byte-identically to before; an unreachable database passes {} too,
+  // which is what makes the DB a durable ADDITION rather than a boot dependency.
+  override = {},
 } = {}) {
   // The known-key set + defaults come from the passed registry: callers inject
   // the built-in MODULE_REGISTRY (the default, what the pure unit tests use) or
@@ -217,7 +223,38 @@ function resolveModules({
     return out;
   };
 
-  const merged = { ...fromConfig(neutral, 'neutral'), ...fromConfig(instance, 'instance') };
+  // PRECEDENCE: neutral pack -> instance pack -> DB override -> env -> registry default.
+  //
+  // ABOVE THE INSTANCE PACK, because outranking the committed file is the entire
+  // point: the file is what `git reset --hard` restores on every deploy, so an
+  // override that sat below it would be erased by the very event it exists to
+  // survive.
+  //
+  // BELOW ENV, because env is the incident knob. An operator must always be able
+  // to force a module off on one box without a working database — and if the DB
+  // outranked env, the failure mode would be "the module I am trying to kill is
+  // being switched back on by a row I cannot reach to delete".
+  const fromOverride = (o) => {
+    const out = {};
+    for (const [k, v] of Object.entries(isObj(o) ? o : {})) {
+      // A row for a module this build does not carry is INERT, not an error. The
+      // DB outlives any one build: a module can be uninstalled while its override
+      // row remains, and that must not stop the process booting. This is the one
+      // place the unknown-key rule is deliberately softer than fromConfig's, which
+      // throws on enabling an unknown module — a config file is authored by hand
+      // for THIS build, a table is not.
+      if (known.includes(k)) out[k] = v;
+    }
+    return out;
+  };
+  const layers = [
+    ['neutral', fromConfig(neutral, 'neutral')],
+    ['instance', fromConfig(instance, 'instance')],
+    ['override', fromOverride(override)],
+    ['env', {}], // filled by the env pass below; named here so the order is stated once
+  ];
+  const envLayer = layers[3][1];
+  const merged = Object.assign({}, ...layers.map(([, m]) => m));
 
   // Env overrides: <PREFIX>_MODULE_<KEY> where KEY is upper-snake of the module
   // name (dev-box -> DEV_BOX). Highest precedence.
@@ -232,6 +269,7 @@ function resolveModules({
       const b = coerceBool(raw);
       if (b === undefined) throw new Error(`modules: ${envName}="${raw}" is not a boolean (use 1/0, on/off, true/false)`);
       merged[key] = b;
+      envLayer[key] = b;
     }
   }
 
@@ -240,14 +278,27 @@ function resolveModules({
     const v = key in merged ? coerceBool(merged[key]) : undefined;
     resolved[key] = v === undefined ? registry[key].default : v;
   }
+  // WHICH LAYER WON, computed in the SAME pass as the value so the two cannot
+  // disagree (task 1002857). An operator looking at a module that is on needs to
+  // know whether that came from the committed pack, a durable override or an env
+  // knob on this box — without it, "why is this on?" costs a shell and a grep.
+  // Non-enumerable so every existing consumer (Object.keys, JSON.stringify, the
+  // clientModules projection) sees exactly the boolean map it saw before.
+  const sources = {};
+  for (const key of known) {
+    const hit = [...layers].reverse().find(([, m]) => key in m);
+    sources[key] = hit ? hit[0] : 'default';
+  }
   // THE SPEND GUARD, applied LAST — after config, after env, after the default.
   // It is deliberately not another precedence level: a refusal that env could
   // outrank would be a suggestion, and the whole point is that the one knob an
   // untrusted-but-cheap deploy would reach for cannot turn it back on.
   for (const key of spendRefusals(resolved, registry, spendGuard)) {
     resolved[key] = false;
+    sources[key] = 'spend-refusal'; // the guard outranks every layer, so it owns the answer
     warn(key, envPrefix);
   }
+  Object.defineProperty(resolved, 'sources', { value: Object.freeze(sources), enumerable: false });
   return Object.freeze(resolved);
 }
 
@@ -276,19 +327,53 @@ function readJson(p) {
 // Like branding's selector, these are FIXED env names (read before the resolved
 // envPrefix is known), not <PREFIX>_ ones. A relative path resolves against the
 // repo root.
+// WHICH instance pack this process runs, by the precedence documented above.
+// Extracted from loadModules (task 1002857) so moduleScopeKey() and the actual
+// read cannot disagree about which pack is in play — a scope key derived from a
+// second, parallel copy of this ladder would drift the first time one changed.
+function resolveInstancePackPath({ instancePath, env = process.env } = {}) {
+  if (instancePath !== undefined) return instancePath;
+  // Canonical spelling pinned to FALLBACK_ENV_PREFIX for the same reason as
+  // branding's selector — read before the pack that names the prefix. The
+  // legacy prefixes still resolve (one warning each), so an already-deployed
+  // BONGOS_MODULES_FILE / BONGOS_BRANDING_FILE keeps selecting the same pack.
+  const fromEnv = resolveEnv('MODULES_FILE', { env, prefix: FALLBACK_ENV_PREFIX });
+  if (fromEnv) return path.resolve(resolveInstanceRoot(), fromEnv);
+  if (resolveEnv('BRANDING_FILE', { env, prefix: FALLBACK_ENV_PREFIX })) return NEUTRAL_PATH;
+  return INSTANCE_PATH;
+}
+
+// THE SCOPE KEY for module_enablement_overrides (task 1002857).
+//
+// One deployed checkout can run two instances against ONE database, differentiated
+// only by BONGOS_MODULES_FILE / BONGOS_BRANDING_FILE — the default instance on
+// config/modules.json and a vanilla sibling on config/modules.neutral.json. The
+// pack path is therefore not an incidental detail: it is the ONLY axis those two
+// processes differ on, which makes it the honest scope key. A single global row
+// per module would let one sibling's toggle flip the other's module.
+//
+// Normalised — relative to the instance root, posix separators — so the key is
+// stable across a moved checkout, an absolute-vs-relative env value, and Windows
+// vs Linux. A path OUTSIDE the instance root (possible via an absolute
+// BONGOS_MODULES_FILE) keeps its absolute form rather than a '../../..' walk, which
+// would encode the checkout's position on disk into a database row.
+function moduleScopeKey({ instancePath, env = process.env } = {}) {
+  const p = resolveInstancePackPath({ instancePath, env });
+  const rel = path.relative(resolveInstanceRoot(), p);
+  const key = rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : p;
+  return key.split(path.sep).join('/');
+}
+
+// The DB override snapshot, read SYNCHRONOUSLY by loadModules and refreshed
+// asynchronously by src/bongos/module-overrides.js. It starts empty and stays
+// empty if the database is never reached, which is what keeps this a durable
+// addition rather than a boot-time dependency: no row, no opinion, resolve as
+// before.
+let _overrides = {};
+
 function loadModules({ neutralPath = NEUTRAL_PATH, instancePath, env = process.env } = {}) {
   const neutral = readJson(neutralPath) || {};
-  let ip = instancePath;
-  if (ip === undefined) {
-    // Canonical spelling pinned to FALLBACK_ENV_PREFIX for the same reason as
-    // branding's selector — read before the pack that names the prefix. The
-    // legacy prefixes still resolve (one warning each), so an already-deployed
-    // GDS_MODULES_FILE / GDS_BRANDING_FILE keeps selecting the same pack.
-    const override = resolveEnv('MODULES_FILE', { env, prefix: FALLBACK_ENV_PREFIX });
-    if (override) ip = path.resolve(resolveInstanceRoot(), override);
-    else if (resolveEnv('BRANDING_FILE', { env, prefix: FALLBACK_ENV_PREFIX })) ip = NEUTRAL_PATH;
-    else ip = INSTANCE_PATH;
-  }
+  const ip = resolveInstancePackPath({ instancePath, env });
   const instance = readJson(ip) || {};
   // Reuse the branding env prefix so an instance has ONE prefix, not two.
   let envPrefix = FALLBACK_ENV_PREFIX;
@@ -323,7 +408,9 @@ function loadModules({ neutralPath = NEUTRAL_PATH, instancePath, env = process.e
   } catch { /* unreadable posture — the fail-closed default above stands */ }
   // Resolve against the EFFECTIVE registry (built-in + discovered) so a config
   // flag for a discovered module is honored. No-op until a module exists.
-  return resolveModules({ neutral, instance, env, envPrefix, registry: effectiveRegistry(), spendGuard });
+  return resolveModules({
+    neutral, instance, env, envPrefix, registry: effectiveRegistry(), spendGuard, override: _overrides,
+  });
 }
 
 // Resolved singleton for app code; lazy so require-time never crashes tooling.
@@ -333,7 +420,22 @@ const modules = () => (_cached ||= loadModules());
 // read (a config-file write from the hall's Modules-tab toggle, ADR 0107 §9;
 // also used by tests). Cheap: the next modules() call just re-reads disk.
 const reload = () => { _cached = null; return modules(); };
-const _resetForTests = () => { _cached = null; };
+// Replace the override snapshot and invalidate, in one step — a caller that set
+// the snapshot without reloading would leave the live process on a stale answer,
+// which is the exact class of bug this feature exists to remove. Returns the newly
+// resolved set so a route can report what it actually produced rather than what it
+// asked for.
+const setModuleOverrides = (map) => {
+  const clean = {};
+  for (const [k, v] of Object.entries(map && typeof map === 'object' ? map : {})) {
+    const b = coerceBool(v);
+    if (b !== undefined) clean[k] = b;
+  }
+  _overrides = Object.freeze(clean);
+  return reload();
+};
+const moduleOverrides = () => _overrides;
+const _resetForTests = () => { _cached = null; _overrides = {}; };
 
 function isModuleEnabled(name, set = modules()) {
   const known = knownModules();
@@ -388,6 +490,10 @@ module.exports = {
   spendRefusals,
   warnSpendRefusal,
   resolveModules,
+  resolveInstancePackPath,
+  moduleScopeKey,
+  setModuleOverrides,
+  moduleOverrides,
   loadModules,
   modules,
   reload,

package/src/platform-server.js

@@ -49,6 +49,13 @@ const { mountInternalSurfaces, isStatusHost, isBuildersHost, injectBrandingGloba
 const { isApiShapedPath, apiNotFoundBody } = require('./bongos/api-path-404');
 const moduleLoader = require('./module-loader/loader');
 const { isModuleEnabled } = require('./modules');
+// Hoisted out of an inline require inside the boot IIFE below (task 1004052 strand walk).
+// knip does not follow an inline require(), so every export of module-overrides.js read as
+// dead code and tripped the ratchet that held this branch out of main. Requiring it here
+// does not weaken the property the comment at the call site protects: refreshOverrides()
+// still swallows its own database error, and node-postgres constructs a Pool without
+// connecting, so a box with no reachable database still boots on the packs and env alone.
+const { refreshOverrides } = require('./bongos/module-overrides');
 const { logger, requestIdMiddleware } = require('./bongos/logger');
 
 const PORT = Number(process.env.PORT) || 3000;
@@ -311,11 +318,46 @@ function startBackgroundServices() {
 // Start only when run as the entry (`node src/platform-server.js`). Importing the
 // module (the smoke test) must NOT bind a port.
 if (require.main === module) {
-  const app = buildPlatformApp();
-  const httpServer = http.createServer(app);
-  httpServer.listen(PORT, HOST, () => {
-    logger.info({ host: HOST, port: PORT }, 'Cloud Bongos platform (GDS-only, no game; ADR 0062 R51) listening');
-    startBackgroundServices();
+  // DURABLE MODULE ENABLEMENT, read BEFORE the app is built (task 1002857).
+  //
+  // It has to be before: buildPlatformApp() mounts routes from the resolved module
+  // set, so an override that landed after construction would not change what is
+  // mounted until the next restart — which is precisely the "my toggle did not
+  // stick" complaint this feature exists to answer.
+  //
+  // And it is NOT a boot dependency. refreshOverrides() swallows its own database
+  // error and returns null, so an unreachable database boots this process exactly
+  // as it booted before the table existed — on the config packs and env alone. The
+  // await buys a better answer when the database is there; it never withholds the
+  // server when it is not.
+  (async () => {
+    await refreshOverrides();
+    const app = buildPlatformApp();
+    const httpServer = http.createServer(app);
+    httpServer.listen(PORT, HOST, () => {
+      logger.info({ host: HOST, port: PORT }, 'Cloud Bongos platform (GDS-only, no game; ADR 0062 R51) listening');
+      startBackgroundServices();
+    });
+  })().catch((err) => {
+    // THE AWAIT ABOVE MUST NOT SOFTEN A FATAL BOOT (task 1002857, caught by
+    // tests/platform_boot.mjs's 1003820 case). buildPlatformApp() THROWS when an
+    // enabled module consumes a port nothing provided, and before this block was
+    // async that throw was an uncaught exception: the process died, non-zero, which
+    // is the correct answer to "half the instance cannot be wired". Inside a promise
+    // it became a rejection instead, and the unhandled-rejection backstop below
+    // explicitly keeps the process UP — so the server came up half-wired and told
+    // nobody. Re-assert the old contract explicitly: a boot failure is fatal.
+    //
+    // RETHROWN, not logged-and-exited. Before the await this WAS an uncaught
+    // exception, and Node's own handling of one is exactly the behaviour wanted:
+    // the raw stack on stderr, then a non-zero exit. Re-logging it instead would
+    // mean choosing between logger.fatal — which JSON-escapes the module-loader's
+    // carefully written "module X consumes port Y, here is how to fix it" into a
+    // wall of backslashes at the moment an operator has to read it — and a
+    // console call that says less than Node already says. A throw from nextTick
+    // is an uncaughtException, NOT an unhandledRejection, so the backstop below
+    // (which deliberately keeps the process up) never sees it.
+    process.nextTick(() => { throw err; });
   });
 
   // Graceful shutdown — stop each module poller (e.g. close the Discord gateway

package/tests/box_sweep_docs.mjs

@@ -35,7 +35,11 @@ const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
 const BOX_JS = 'scripts/gds/box.js';
 const IDLE_SKILL = '.claude/scheduled-tasks/box-idle-suspend/SKILL.md';
 const DORMANT_SKILL = '.claude/scheduled-tasks/box-dormant-reclaim/SKILL.md';
-const RECIPE = 'docs/recipes/builder-box-lifecycle.md';
+// The fourth surface this guard used to read, docs/recipes/builder-box-lifecycle.md,
+// was deleted with the other three published dev-box recipes (task 1004013,
+// ADR 0305: a recipe lives with what it documents). A file that does not exist
+// cannot invert against box.js, so it drops out of the lists below rather than
+// weakening them — the two SKILL.md surfaces are still read in full.
 
 // Comments are stripped before scanning prose: each surface deliberately keeps a
 // sentence SAYING which model it used to describe, and a naive substring check
@@ -76,7 +80,7 @@ test('no box-sweep doc claims the IDLE sweep destroys, while the code parks', ()
     /single job is to DESTROY/i,
   ];
 
-  for (const file of [IDLE_SKILL, DORMANT_SKILL, RECIPE]) {
+  for (const file of [IDLE_SKILL, DORMANT_SKILL]) {
     const prose = stripHtmlComments(read(file));
     for (const lie of lies) {
       assert.doesNotMatch(prose, lie,
@@ -107,7 +111,7 @@ test('every surface names sweep-dormant as the only automated snapshot delete',
   // The safety property box.js implements in prose: full reclaim warns first, so
   // no automated path takes uncommitted work silently. A reader who misses this
   // is the reader who reaches for deprovision.
-  for (const file of [IDLE_SKILL, DORMANT_SKILL, RECIPE]) {
+  for (const file of [IDLE_SKILL, DORMANT_SKILL]) {
     assert.match(stripHtmlComments(read(file)), /only automated path that destroys a snapshot|only automated snapshot delete/i,
       `${file} never tells the reader that sweep-dormant is the only automated path that `
       + 'destroys a snapshot (and that it warns first) — the safety property this subsystem rests on.');