@bongos/core 1.19.882 → 1.19.883

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.');

package/tests/collab_page.mjs

@@ -23,6 +23,16 @@ function lib() {
   new Function('window', src)(win);
   return win.OTBCollabLib;
 }
+
+// The role vocabulary is pure too, so RUN it for the same reason — a grep over
+// roleWord()'s source would agree with a roleWord() that was wrong.
+function domUtils() {
+  const src = read('modules', 'hall-ui', 'public', 'dom-utils.js');
+  const win = { location: { search: '', hash: '', pathname: '/' }, addEventListener() {}, localStorage: null };
+  const doc = { addEventListener() {}, querySelector: () => null, querySelectorAll: () => [], documentElement: { dataset: {} } };
+  new Function('window', 'document', src)(win, doc);
+  return win.OTB;
+}
 const NOW = Date.parse('2026-08-24T12:00:00Z');
 const daysAgo = (d) => new Date(NOW - d * 86400000).toISOString();
 
@@ -71,8 +81,75 @@ test('ageing changes how a row LOOKS, not only where it sits', () => {
 test('the row markup carries the band class and the label', () => {
   const js = read('modules', 'hall-ui', 'public', 'collab.js');
   assert.match(js, /cb-age cb-age--\$\{band\.id\}/, 'the pill\'s class comes from the band');
-  assert.match(js, /escapeHtml\(band\.label\)/, 'the label is rendered, escaped');
+  assert.match(js, /escapeHtml\(L\.ageLabel\(req\.created_at, nowMs\)\)/, 'the label is rendered, escaped');
   assert.match(js, /L\.ageBand\(req\.created_at, nowMs\)/, 'through the lib, so the boundaries are the tested ones');
+  // THE BAND AND THE LABEL ARE TWO SOURCES ON PURPOSE (task 1004041). Until then
+  // the pill rendered `band.label`, so the band decided both how loud the row
+  // looked AND what it said — which is why fourteen rows past a week carried
+  // fourteen copies of "waiting over a week". The class still comes from the
+  // band (four treatments, readable down a column) and the words now come from
+  // ageLabel (the real age, different on every row). Asserting only one of the
+  // two would let them be collapsed back onto each other.
+  assert.ok(!/escapeHtml\(band\.label\)/.test(js), 'the words are the real age, not the band name again');
+});
+
+test('two rows in the same band do not read identically', () => {
+  // The artist's finding, as an executable claim: a signal that never varies is
+  // not a signal. Every one of these is band 'stale', and no two say the same
+  // thing.
+  const L = lib();
+  const said = [8, 9, 13, 21, 40, 400].map((d) => {
+    assert.equal(L.ageBand(daysAgo(d), NOW).id, 'stale', `${d} days is stale`);
+    return L.ageLabel(daysAgo(d), NOW);
+  });
+  assert.equal(new Set(said).size, said.length, `six stale rows, six different readings: ${said.join(' / ')}`);
+});
+
+test('the age label says how long, coarsely, and never accuses an unknown age', () => {
+  const L = lib();
+  assert.equal(L.ageLabel(daysAgo(0.4), NOW), 'just asked');
+  assert.equal(L.ageLabel(daysAgo(1), NOW), 'waiting a day');
+  assert.equal(L.ageLabel(daysAgo(4), NOW), 'waiting 4 days');
+  assert.equal(L.ageLabel(daysAgo(13), NOW), 'waiting 13 days');
+  // Past a fortnight it goes to weeks: 'waiting 38 days' is a precision nobody
+  // acts on, the same argument the bands were written on.
+  assert.equal(L.ageLabel(daysAgo(21), NOW), 'waiting 3 weeks');
+  for (const bad of [null, undefined, '', 'nonsense']) {
+    assert.equal(L.ageLabel(bad, NOW), 'just asked', `${JSON.stringify(bad)} must not look neglected`);
+  }
+});
+
+test('the two calm bands are not chips, and the date is not said twice', () => {
+  // The chip appears where there is something to say. All four bands keep their
+  // own ink (the test above), but fresh and waiting drop the pill's ring, so a
+  // board of healthy asks does not open as a wall of chips.
+  const css = read('modules', 'hall-ui', 'public', 'collab.css');
+  assert.match(
+    css,
+    /\.cb-age--fresh,\s*\n\.cb-age--waiting\s*\{[^}]*border-color: transparent/,
+    'the calm bands read as quiet text, not as chips',
+  );
+  // And the separate date line is gone: the pill carries the age in words and
+  // the exact timestamp on its title, so a date beside it was one fact twice.
+  const js = read('modules', 'hall-ui', 'public', 'collab.js');
+  assert.ok(!/ov-row__when/.test(js), 'no second rendering of the same fact');
+  assert.match(js, /title="Asked \$\{escapeHtml\(String\(req\.created_at/, 'the exact date is still reachable');
+});
+
+test('the alarm does not sit beside the accent control', () => {
+  // DESIGN.md spends the accent only on what is pressable or live. On "Your
+  // asks" the age pill (danger ink) used to share the right column with the
+  // solid-accent "Someone helped" button, so a warning and a control sat two
+  // centimetres apart in one colour family. The age is a FACT about the ask now;
+  // the right column on that row holds only what you can press.
+  const js = read('modules', 'hall-ui', 'public', 'collab.js');
+  const mine = js.slice(js.indexOf('function mineRow('), js.indexOf('function allRow('));
+  assert.ok(mine.length > 100, 'found mineRow');
+  const right = mine.slice(mine.indexOf('ov-row__right'));
+  assert.ok(!right.includes('ageChip'), 'no age pill in the column that holds the accent button');
+  assert.ok(right.includes('btn-accent'), 'the accent button is still there');
+  const facts = mine.slice(mine.indexOf('ov-row__facts'), mine.indexOf('ov-row__right'));
+  assert.ok(facts.includes('ageChip'), 'the age reads as a fact about the ask');
 });
 
 test('oldest first WITHIN the page, in addition to the band', () => {
@@ -264,6 +341,64 @@ test('the page is the three blocks, led by faces, with the ledes gone', () => {
   assert.match(html, /class="cb-foot"/, 'and it is the foot, not the opener');
 });
 
+test('a person meets the page\'s NUMBERS before its pills', () => {
+  // Task 1003942 promised "a glass figure strip at the top (waiting on you /
+  // your open asks / crafts you answer for)" and shipped without it; the
+  // grader's narc worker caught the omission and the artist's verdict named
+  // what it cost — with nothing calm at the top, the page opens on age pills.
+  const html = read('modules', 'hall-ui', 'public', 'collab.html');
+  const js = read('modules', 'hall-ui', 'public', 'collab.js');
+  assert.match(html, /<div class="stat-row ov-summary cb-figs" id="cb-figs"/, 'the strip is the shell\'s glass band');
+  // Position is the whole claim: before the blocks, not beside them.
+  assert.ok(html.indexOf('id="cb-figs"') < html.indexOf('cb-band'), 'the strip is ABOVE the blocks');
+  assert.ok(html.indexOf('id="cb-figs"') < html.indexOf('id="cb-all"'), 'and above the board');
+  assert.match(js, /function paintFigures\(/, 'the page fills it');
+  assert.match(js, /paintFigures\(rowsOf\(forMe\), rowsOf\(mine\), crafts\)/, 'from the reads it already makes — no fourth fetch');
+  for (const label of ['Waiting on you', 'Your open asks', 'Roles you answer for']) {
+    assert.ok(js.includes(label), `the strip carries "${label}"`);
+  }
+  // It is painted BEFORE the blocks, so the numbers are on screen first even on
+  // a slow paint.
+  assert.ok(js.indexOf('paintFigures(') < js.indexOf("paintBlock('for-me'"), 'and painted first');
+});
+
+test('ONE WORD, ONE CASING: a sentence takes roleWord, a control takes roleLabel', () => {
+  // The artist's third finding, and the design error under it. Collab said
+  // "Asks to Builders" in its sub line and "You asked artists" six lines down,
+  // because task 1003936 routed one call site through roleLabel() — correct for
+  // a picker, wrong in prose — and reasoned about the other separately.
+  const dom = read('modules', 'hall-ui', 'public', 'dom-utils.js');
+  const js = read('modules', 'hall-ui', 'public', 'collab.js');
+  assert.match(dom, /function roleWord\(d\)/, 'prose has its own helper');
+  assert.match(dom, /roleAxisLabel, roleLabel, roleWord,/, 'and it is exported');
+  // The rule is written down next to the helper that made it necessary, which is
+  // the third DONE WHEN clause of task 1004041.
+  const nearby = dom.slice(dom.indexOf('function roleLabel('), dom.indexOf('function roleWord('));
+  assert.match(nearby, /A CONTROL TAKES roleLabel\(\); A SENTENCE TAKES roleWord\(\)/, 'the rule sits beside roleLabel');
+  // The page's sentence no longer capitalises a common noun, and no longer
+  // opens on a clause the next clause repeats.
+  assert.match(js, /roleWord\(c\)\}s/, 'the sub line names roles as common nouns');
+  assert.ok(!/Builders asking builders/.test(js), 'the tautology is gone');
+  // A CALL, not a mention: the comment above the sub line names roleLabel() to
+  // explain why it is not used, and a bare /roleLabel\(/ would read that as the
+  // defect it warns about.
+  assert.ok(!/window\.OTB\.roleLabel\(/.test(js), 'no control-voice label inside a sentence on this page');
+});
+
+test('roleWord and roleLabel disagree exactly where they should', () => {
+  // Executed, not grepped: the acronym exception has to survive both ways, or
+  // "You asked uis" ships the next time a ui task files a help request.
+  const { roleLabel, roleWord } = domUtils();
+  assert.equal(roleLabel('engineer'), 'Engineer');
+  assert.equal(roleWord('engineer'), 'engineer');
+  assert.equal(roleLabel('ui'), 'UI');
+  assert.equal(roleWord('ui'), 'UI', 'an acronym is not a common noun in any sentence');
+  assert.equal(roleLabel('unclassified'), 'No role yet');
+  assert.equal(roleWord('unclassified'), 'no role yet');
+  assert.equal(roleWord(''), '');
+  assert.equal(roleWord(null), '');
+});
+
 test('the by-name ask is the one LIT thing — the accent goes on the personal call', () => {
   const js = read('modules', 'hall-ui', 'public', 'collab.js');
   const css = read('modules', 'hall-ui', 'public', 'collab.css');

package/tests/modules.mjs

@@ -3,6 +3,10 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { existsSync } from 'node:fs';
 import modulesMod from '../src/modules.js';
+// Named, not modulesMod.moduleOverrides (task 1004052 strand walk): knip does not credit
+// property access on a default import as using the named export, so the snapshot getter
+// read as dead code and tripped the ratchet that held this branch out of main.
+import { moduleOverrides } from '../src/modules.js';
 
 const {
   resolveModules, isModuleEnabled, enabledModules, enabledDisciplines, clientModules,
@@ -221,3 +225,109 @@ test('a branded sibling (GDS_BRANDING_FILE set, no GDS_MODULES_FILE) defaults to
   // assertion above never reaches it (task 1003487).
   assert.deepEqual(enabledDisciplines(m), ['engineer', 'artist', 'ideator', 'ui']);
 });
+
+// ── the DB override layer (task 1002857, migration core_248) ────────────────────
+// The toggle used to write config/modules.json, which the pull-deploy's
+// `git reset --hard origin/main` then reverted. These pin the precedence the
+// durable replacement has to hold, because getting the ORDER wrong is the only way
+// this feature can be worse than the bug it replaces.
+
+test('1002857: an override outranks the committed instance pack', () => {
+  // The whole point: the pack is what a deploy restores, so an override that sat
+  // below it would be erased by the very event it exists to survive.
+  const m = resolveModules({ instance: OTB, override: { 'dev-box': false }, registry: SAMPLE_REG });
+  assert.equal(m['dev-box'], false, 'the override wins over the pack');
+  assert.equal(m.discord, true, 'a module with no override still reads the pack');
+});
+
+test('1002857: an override turns a module ON as well as off', () => {
+  const m = resolveModules({ instance: VANILLA, override: { discord: true }, registry: SAMPLE_REG });
+  assert.equal(m.discord, true);
+});
+
+test('1002857: env still outranks an override — the incident knob needs no database', () => {
+  const m = resolveModules({
+    instance: VANILLA,
+    override: { 'dev-box': true },
+    env: { OTB_MODULE_DEV_BOX: '0' },
+    envPrefix: 'OTB',
+    registry: SAMPLE_REG,
+  });
+  assert.equal(m['dev-box'], false, 'env must be able to kill a module the DB turned on');
+});
+
+test('1002857: an override for a module this build does not carry is inert, not fatal', () => {
+  // The database outlives any one build: a module can be uninstalled while its row
+  // remains. fromConfig throws on enabling an unknown key (a hand-authored file is
+  // written for THIS build); a table is not, so it must not stop the process.
+  const m = resolveModules({ override: { 'a-module-that-left': true }, registry: SAMPLE_REG });
+  assert.ok(!('a-module-that-left' in m), 'unknown key dropped');
+  // NOT 'enables nothing': some discovered modules (ui-design and friends) are
+  // default-ON for every instance, so the enabled set is legitimately non-empty.
+  // The claim under test is narrower and the one that matters — the unknown key
+  // did not conjure itself into the enabled list.
+  assert.ok(!enabledModules(m).includes('a-module-that-left'), 'and it enables nothing');
+});
+
+test('1002857: no override is "no opinion" — an unreachable database resolves as before', () => {
+  const withEmpty = resolveModules({ instance: OTB, override: {}, registry: SAMPLE_REG });
+  const without = resolveModules({ instance: OTB, registry: SAMPLE_REG });
+  assert.deepEqual({ ...withEmpty }, { ...without }, 'empty snapshot changes nothing');
+});
+
+test('1002857: each module reports the layer that produced its state', () => {
+  const m = resolveModules({
+    neutral: { modules: { discord: false } },
+    instance: OTB,
+    override: { 'dev-box': false },
+    env: { OTB_MODULE_GAME: '0' },
+    envPrefix: 'OTB',
+    registry: SAMPLE_REG,
+  });
+  assert.equal(m.sources['dev-box'], 'override');
+  assert.equal(m.sources.game, 'env');
+  assert.equal(m.sources.discord, 'instance', 'the instance pack outranks the neutral one');
+  assert.equal(m.sources['art-pipeline'], 'instance');
+  // sources must never join the boolean map: clientModules and every JSON
+  // projection of it would start shipping an object where a boolean belongs.
+  assert.ok(!Object.keys(m).includes('sources'), 'sources is non-enumerable');
+  assert.ok(!('sources' in JSON.parse(JSON.stringify(m))), 'and never serialises');
+});
+
+test('1002857: the scope key separates two instances sharing one database', () => {
+  // One checkout can run the default instance and a vanilla sibling, differentiated
+  // only by env. A single global row per module would let one flip the other's.
+  const dflt = modulesMod.moduleScopeKey({ env: {} });
+  const sibling = modulesMod.moduleScopeKey({ env: { GDS_BRANDING_FILE: 'config/branding.cloudbongos.json' } });
+  assert.notEqual(dflt, sibling, 'the two instances must not share a scope');
+  assert.equal(dflt, 'config/modules.json');
+  assert.equal(sibling, 'config/modules.neutral.json');
+  // Posix separators and no absolute path, so the key is stable across a moved
+  // checkout and across Windows vs Linux.
+  assert.ok(!dflt.includes(String.fromCharCode(92)), "posix separators, not a Windows path");
+  assert.deepEqual(
+    modulesMod.moduleScopeKey({ env: { GDS_MODULES_FILE: 'config/other.json' } }),
+    'config/other.json',
+  );
+});
+
+test('1002857: setModuleOverrides installs the snapshot AND invalidates the cache', () => {
+  // Setting without reloading would leave the live process on a stale answer —
+  // the exact class of bug this feature exists to remove.
+  try {
+    const before = modulesMod.modules();
+    assert.equal(before['dev-box'], false, 'precondition: off on a vanilla resolve');
+    const after = modulesMod.setModuleOverrides({ 'dev-box': true });
+    assert.equal(after['dev-box'], true, 'the returned set reflects the override');
+    assert.equal(modulesMod.modules()['dev-box'], true, 'and so does the live singleton');
+    assert.equal(moduleOverrides()['dev-box'], true);
+  } finally {
+    modulesMod._resetForTests();
+  }
+});
+
+test('1002857: _resetForTests clears the override snapshot too', () => {
+  modulesMod.setModuleOverrides({ 'dev-box': true });
+  modulesMod._resetForTests();
+  assert.deepEqual(moduleOverrides(), {}, 'a leaked snapshot would cross-contaminate tests');
+});