@bongos/core 1.19.654 → 1.19.655

package/src/instance-config.js

@@ -21,7 +21,11 @@ const path = require('node:path');
 
 // Last-resort default if branding can't be read at all (vanilla, never OTB).
 const FALLBACK_DIR = 'cloudbongos';
-const FALLBACK_ENV_PREFIX = 'CLOUDBONGOS';
+// BONGOS is the CANONICAL env prefix (task 1003703 / criterion C3 of goal
+// 1000073). It was CLOUDBONGOS until then; that spelling moved into
+// LEGACY_ENV_PREFIXES below rather than being dropped, so a vanilla instance
+// already exporting CLOUDBONGOS_* keeps resolving.
+const FALLBACK_ENV_PREFIX = 'BONGOS';
 
 // Historical hard-coded config dir — always also checked on READ so a session /
 // ledger / key written before R61 (or by an instance that later changed its
@@ -30,8 +34,24 @@ const LEGACY_DIRS = ['otb'];
 
 // Legacy env prefixes tried (in order) AFTER the configured one. These cover the
 // three prefixes that coexisted pre-R61 (OTB_ operational, GDS_ API/auth, PMS_
-// the original name). Keeping them means prod's existing env is honored verbatim.
-const LEGACY_ENV_PREFIXES = ['OTB', 'GDS', 'PMS'];
+// the original name) plus CLOUDBONGOS_, which was the canonical default until
+// task 1003703 made it BONGOS_. Keeping them means prod's existing env is
+// honored verbatim.
+//
+// WHY THESE MUST OUTLIVE THIS TASK: these names are set OUTSIDE the repo —
+// /etc/cloudbongos/web.env on the droplet, systemd units, CI secrets, shipped
+// Dev Box binaries, live dev boxes. Deleting a spelling here is an outage the
+// next time one of those restarts. Task 1003706 (C3d) retires them deliberately,
+// after evidence — and asserts their ABSENCE, which is why the fallback needs a
+// test that it FIRES rather than one that merely tolerates it.
+const LEGACY_ENV_PREFIXES = ['CLOUDBONGOS', 'OTB', 'GDS', 'PMS'];
+
+// The core release in which the legacy prefixes above stop being read. Named in
+// every deprecation warning so an operator learns the deadline from the warning
+// itself rather than from a changelog they will not read. This lands in 1.19.x,
+// so 1.21 leaves a full minor of overlap; task 1003706 is the task that both
+// removes the fallback and moves this constant's meaning to "already gone".
+const LEGACY_ENV_SUNSET_RELEASE = '1.21';
 
 // Lazy require (ADR 0108 §1 made this a two-way edge: branding.js now requires
 // resolveCoreRoot()/resolveInstanceRoot() from this module, so a top-level
@@ -135,21 +155,62 @@ function readConfigFileSync(name, { encoding = 'utf8', b = safeBrand() } = {}) {
 }
 
 // Resolve an env var by SUFFIX across the configured prefix + legacy prefixes.
-// resolveEnv('API_BASE') tries <PREFIX>_API_BASE (CLOUDBONGOS_ on vanilla, OTB_
-// on the OTB instance), then OTB_/GDS_/PMS_API_BASE. Returns undefined if none
-// is set to a non-empty value. `extraLegacy` prepends suffix-specific aliases
-// (rare — e.g. a var that had an idiosyncratic legacy name).
-function resolveEnv(suffix, { env = process.env, prefix = envPrefix(), legacy = LEGACY_ENV_PREFIXES } = {}) {
-  const seen = new Set();
-  for (const pfx of [prefix, ...legacy]) {
+// resolveEnv('API_BASE') tries <PREFIX>_API_BASE (BONGOS_ on vanilla, OTB_ on
+// the OTB instance), then CLOUDBONGOS_/OTB_/GDS_/PMS_API_BASE. Returns undefined
+// if none is set to a non-empty value.
+//
+// THE CANONICAL SPELLING ALWAYS WINS, including over a legacy one set to a
+// different value — an operator mid-migration who sets the new name expects it
+// to take effect, and silently preferring the old one would make the rename
+// untestable. Each legacy name that is READ (won or shadowed) emits ONE warning
+// per process naming the old spelling, the new one, and the release the old
+// stops working in; see warnLegacyEnv below. `warn` is injectable so a test can
+// assert the warning fires rather than only that the value resolves.
+function resolveEnv(suffix, { env = process.env, prefix = envPrefix(), legacy = LEGACY_ENV_PREFIXES, warn = warnLegacyEnv } = {}) {
+  const canonical = `${prefix}_${suffix}`;
+  const canonicalValue = prefix ? env[canonical] : undefined;
+  const canonicalSet = canonicalValue !== undefined && canonicalValue !== '';
+  // Every legacy spelling is visited even when the canonical one already won —
+  // a spelling that is merely SHADOWED is still set on some box, and it will
+  // stop being read at the sunset, so it earns its one warning too. Warning only
+  // on the winner would leave the "both set" operator with no notice at all.
+  const seen = new Set([prefix].filter(Boolean));
+  let winner = canonicalSet ? canonicalValue : undefined;
+  for (const pfx of legacy) {
     if (!pfx || seen.has(pfx)) continue;
     seen.add(pfx);
-    const v = env[`${pfx}_${suffix}`];
-    if (v !== undefined && v !== '') return v;
+    const name = `${pfx}_${suffix}`;
+    const v = env[name];
+    if (v === undefined || v === '') continue;
+    warn({ legacyName: name, canonicalName: canonical, shadowed: canonicalSet, differs: canonicalSet && canonicalValue !== v });
+    if (winner === undefined) winner = v;
   }
-  return undefined;
+  return winner;
 }
 
+// One warning per legacy env NAME per process. A silent fallback is how an old
+// spelling survives forever — but a warning per READ would drown a CLI that
+// resolves the same knob in a loop, so the emitted set is the dedupe key.
+const _legacyEnvWarned = new Set();
+
+function warnLegacyEnv({ legacyName, canonicalName, shadowed, differs, log = console } = {}) {
+  if (_legacyEnvWarned.has(legacyName)) return false;
+  _legacyEnvWarned.add(legacyName);
+  const fate = differs
+    ? `${canonicalName} is ALSO set to a different value and WINS`
+    : shadowed
+      ? `${canonicalName} is also set and wins`
+      : `rename it to ${canonicalName}`;
+  log.warn(`[bongos] deprecated env ${legacyName} — ${fate}. The legacy spelling stops being read in core ${LEGACY_ENV_SUNSET_RELEASE}.`);
+  return true;
+}
+
+// NOT exported, deliberately: warnLegacyEnv, LEGACY_ENV_SUNSET_RELEASE and the
+// ledger are internals. resolveEnv's injectable `warn` is the whole test seam a
+// caller needs, and a test of the DEFAULT path captures console.warn — which
+// exercises the real wiring rather than a hand-called helper. Exporting them
+// would also add three untraceable entries to the knip dead-code ratchet.
+
 // resolveCoreRoot() / resolveInstanceRoot() — the ADR 0108 §1 configurable-root
 // resolvers, extending this module's established zero-risk pattern from
 // ~/.config to the in-repo roots. Two OPPOSITE directions, both load-bearing:

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

@@ -27,7 +27,7 @@ const path = require('node:path');
 // resolver below spans built-in + discovered modules (ADR 0083 / BV1.R41). Empty
 // until a module is moved into modules/ — so this is a no-op on the current tree.
 const loader = require('./module-loader/loader');
-const { resolveCoreRoot, resolveInstanceRoot } = require('./instance-config');
+const { resolveCoreRoot, resolveInstanceRoot, resolveEnv, FALLBACK_ENV_PREFIX } = require('./instance-config');
 const { responsibilitiesFor } = require('./role-responsibilities');
 
 // ADR 0108 §1: the neutral starter ships WITH the core package; the instance
@@ -121,7 +121,7 @@ function coerceBool(v) {
 // Pure resolver — all inputs injected, so tests drive it with zero I/O.
 // Returns a frozen { <moduleKey>: boolean } covering EVERY registry key, plus a
 // non-enumerable resolution that throws on an unknown module key (typo guard).
-function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = 'CLOUDBONGOS', registry = MODULE_REGISTRY } = {}) {
+function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = FALLBACK_ENV_PREFIX, registry = MODULE_REGISTRY } = {}) {
   // 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
   // the effective built-in+discovered registry (what loadModules passes). This
@@ -157,8 +157,12 @@ function resolveModules({ neutral = {}, instance = {}, env = {}, envPrefix = 'CL
   // Env overrides: <PREFIX>_MODULE_<KEY> where KEY is upper-snake of the module
   // name (dev-box -> DEV_BOX). Highest precedence.
   for (const key of known) {
-    const envName = `${envPrefix}_MODULE_${key.toUpperCase().replace(/-/g, '_')}`;
-    const raw = env[envName];
+    const suffix = `MODULE_${key.toUpperCase().replace(/-/g, '_')}`;
+    const envName = `${envPrefix}_${suffix}`;
+    // resolveEnv, not env[envName]: a provisioned instance sets these per box
+    // (provision-units.js writes them into the systemd unit), so the pre-rename
+    // spelling must keep switching the same module off. Warns once per legacy name.
+    const raw = resolveEnv(suffix, { env, prefix: envPrefix });
     if (raw !== undefined && raw !== '') {
       const b = coerceBool(raw);
       if (b === undefined) throw new Error(`modules: ${envName}="${raw}" is not a boolean (use 1/0, on/off, true/false)`);
@@ -203,14 +207,18 @@ function loadModules({ neutralPath = NEUTRAL_PATH, instancePath, env = process.e
   const neutral = readJson(neutralPath) || {};
   let ip = instancePath;
   if (ip === undefined) {
-    const override = env.GDS_MODULES_FILE;
+    // 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 (env.GDS_BRANDING_FILE) ip = NEUTRAL_PATH;
+    else if (resolveEnv('BRANDING_FILE', { env, prefix: FALLBACK_ENV_PREFIX })) ip = NEUTRAL_PATH;
     else ip = INSTANCE_PATH;
   }
   const instance = readJson(ip) || {};
   // Reuse the branding env prefix so an instance has ONE prefix, not two.
-  let envPrefix = 'CLOUDBONGOS';
+  let envPrefix = FALLBACK_ENV_PREFIX;
   try { envPrefix = require('./branding').branding().envPrefix || envPrefix; } catch { /* fail-to-default */ }
   // Resolve against the EFFECTIVE registry (built-in + discovered) so a config
   // flag for a discovered module is honored. No-op until a module exists.

package/tests/claude_materialize.mjs

@@ -466,7 +466,7 @@ t('materializeClaude: copied hooks carry NO founder origin/config-dir; a disable
   const dir = mkdtempSync(join(tmpdir(), 'rb-e2e-'));
   // Target instance: demo-branded, art-pipeline OFF (so its otb-* skills must be dropped).
   mkdirSync(join(dir, 'config'), { recursive: true });
-  writeFileSync(join(dir, 'config', 'branding.json'), JSON.stringify({ domains: { publicOrigin: 'https://demo.cloudbongos.com', buildersOrigin: 'https://demo.cloudbongos.com', statusOrigin: 'https://demo.cloudbongos.com', oauthOrigin: 'https://demo.cloudbongos.com' }, configDir: 'cloudbongos', envPrefix: 'CLOUDBONGOS' }));
+  writeFileSync(join(dir, 'config', 'branding.json'), JSON.stringify({ domains: { publicOrigin: 'https://demo.cloudbongos.com', buildersOrigin: 'https://demo.cloudbongos.com', statusOrigin: 'https://demo.cloudbongos.com', oauthOrigin: 'https://demo.cloudbongos.com' }, configDir: 'cloudbongos', envPrefix: 'BONGOS' }));
   writeFileSync(join(dir, 'config', 'modules.json'), JSON.stringify({ modules: { 'art-pipeline': false } }));
   const res = m.materializeClaude({ coreRoot: ROOT, instanceDir: dir, dryRun: false });
   // Founder core → demo: a branding delta exists and rules are built. The NEUTRAL

package/tests/cloud_bongos_pack.mjs

@@ -28,7 +28,7 @@ test('R74: a vanilla boot resolves to the Cloud Bongos identity', () => {
   assert.equal(b.identity.productName, 'Cloud Bongos');
   assert.equal(b.identity.worldName, 'Cloud Bongos');
   assert.equal(b.currency.label, 'credits'); // not "drachmae"
-  assert.equal(b.envPrefix, 'CLOUDBONGOS');
+  assert.equal(b.envPrefix, 'BONGOS'); // canonical since task 1003703; CLOUDBONGOS_ still resolves as a legacy prefix
 });
 
 test('R74: the vanilla pack carries the Cloud Bongos LOOK (chrome palette, Manrope, bongo favicon)', () => {

package/tests/init.mjs

@@ -51,7 +51,7 @@ test('buildBrandingConfig: lean overrides only (no theme block)', () => {
   assert.equal(b.repo.owner, 'lars589');
   assert.equal(b.firstAdmin, 'lars589');
   assert.equal(b.currency.label, 'credits');
-  assert.equal(b.envPrefix, 'CLOUDBONGOS');
+  assert.equal(b.envPrefix, 'BONGOS'); // canonical since task 1003703
   assert.equal(b.copy.tagline, 'Building software is laying down a beat.');
   assert.equal(b.theme, undefined);                       // lean — neutral fills the look
   assert.equal(b.domains.buildersOrigin, 'http://localhost:3000');

package/tests/instance_config.mjs

@@ -8,7 +8,7 @@ import ic from '../src/instance-config.js';
 
 const {
   configDirName, envPrefix, configHome, configReadDirs, configReadPaths,
-  resolveEnv, FALLBACK_DIR, FALLBACK_ENV_PREFIX,
+  resolveEnv, FALLBACK_DIR, FALLBACK_ENV_PREFIX, LEGACY_ENV_PREFIXES,
   resolveInstanceRootExplicit, resolveDocsRoot, resolveCoreRoot,
 } = ic;
 
@@ -22,7 +22,10 @@ test('configDirName: from branding, else the vanilla fallback (never OTB)', () =
 test('envPrefix: from branding, else the vanilla fallback', () => {
   assert.equal(envPrefix({ envPrefix: 'OTB' }), 'OTB');
   assert.equal(envPrefix({}), FALLBACK_ENV_PREFIX);
-  assert.equal(FALLBACK_ENV_PREFIX, 'CLOUDBONGOS');
+  // BONGOS since task 1003703 (criterion C3a). CLOUDBONGOS did not disappear —
+  // it moved into LEGACY_ENV_PREFIXES, which the fallback tests below pin.
+  assert.equal(FALLBACK_ENV_PREFIX, 'BONGOS');
+  assert.ok(LEGACY_ENV_PREFIXES.includes('CLOUDBONGOS'), 'the previous canonical prefix must stay readable');
 });
 
 test('configHome: ~/.config/<dir>', () => {
@@ -61,6 +64,99 @@ test('resolveEnv: legacy PMS prefix still honored (original-name back-compat)',
   assert.equal(resolveEnv('GITHUB_CLIENT_ID', { prefix: 'CLOUDBONGOS', env: { PMS_GITHUB_CLIENT_ID: 'old' } }), 'old');
 });
 
+// ---------------------------------------------------------------------------
+// The legacy-prefix DEPRECATION WARNING (task 1003703 / criterion C3a).
+//
+// These assert the fallback FIRES, not merely that the new spelling works. A
+// happy-path-only test would still pass with the whole legacy path deleted,
+// which is exactly the regression task 1003706 (C3d) exists to catch when it
+// removes the fallback on purpose — at which point these tests must be inverted,
+// not quietly dropped.
+// ---------------------------------------------------------------------------
+
+// Collects warn() payloads instead of printing, so a case can assert on shape.
+function capture() {
+  const calls = [];
+  return { calls, warn: (payload) => { calls.push(payload); return true; } };
+}
+
+// Runs fn with console.warn captured, so a case can assert on the REAL default
+// warn path rather than a hand-called helper. resolveEnv's `warn` option is the
+// only seam the module exports; the renderer and its warn-once ledger are
+// internals, reached here exactly the way production reaches them.
+function captureConsole(fn) {
+  const lines = [];
+  const real = console.warn;
+  console.warn = (m) => lines.push(String(m));
+  try { fn(); } finally { console.warn = real; }
+  return lines;
+}
+
+test('resolveEnv: ONLY the old spelling set — resolves, and warns naming old, new and the sunset', () => {
+  const { calls, warn } = capture();
+  const v = resolveEnv('API_BASE', { prefix: 'BONGOS', env: { GDS_API_BASE: 'legacy' }, warn });
+  assert.equal(v, 'legacy', 'the legacy spelling must still resolve — boxes still export it');
+  assert.equal(calls.length, 1, 'exactly one warning for the one legacy name that was read');
+  assert.deepEqual(calls[0], { legacyName: 'GDS_API_BASE', canonicalName: 'BONGOS_API_BASE', shadowed: false, differs: false });
+
+  // …and the DEFAULT renderer puts all three facts an operator needs on the line.
+  // A suffix used by no other case, so the process-global warn-once ledger cannot
+  // have already spent this name.
+  const lines = captureConsole(() => {
+    resolveEnv('C3A_RENDER_PROBE', { prefix: 'BONGOS', env: { CLOUDBONGOS_C3A_RENDER_PROBE: 'legacy' } });
+  });
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /CLOUDBONGOS_C3A_RENDER_PROBE/, 'names the old spelling');
+  assert.match(lines[0], /BONGOS_C3A_RENDER_PROBE/, 'names the new spelling');
+  assert.match(lines[0], /stops being read in core 1\.21/, 'names the release it stops working in');
+});
+
+test('resolveEnv: ONLY the new spelling set — resolves, and is SILENT', () => {
+  const { calls, warn } = capture();
+  assert.equal(resolveEnv('API_BASE', { prefix: 'BONGOS', env: { BONGOS_API_BASE: 'new' }, warn }), 'new');
+  assert.deepEqual(calls, [], 'the canonical spelling must never warn');
+});
+
+test('resolveEnv: BOTH set and disagreeing — the new one wins, and the warning says so', () => {
+  const { calls, warn } = capture();
+  const v = resolveEnv('API_BASE', { prefix: 'BONGOS', env: { BONGOS_API_BASE: 'new', GDS_API_BASE: 'legacy' }, warn });
+  assert.equal(v, 'new', 'an operator who sets the new name expects it to take effect');
+  assert.equal(calls.length, 1, 'a SHADOWED legacy name still earns its one warning — it is set on some box');
+  assert.equal(calls[0].shadowed, true);
+  assert.equal(calls[0].differs, true);
+  const lines = captureConsole(() => {
+    resolveEnv('C3A_DISAGREE_PROBE', { prefix: 'BONGOS', env: { BONGOS_C3A_DISAGREE_PROBE: 'new', CLOUDBONGOS_C3A_DISAGREE_PROBE: 'legacy' } });
+  });
+  assert.match(lines[0], /ALSO set to a different value and WINS/, 'the disagreement is spelled out, not implied');
+});
+
+test('resolveEnv: both set to the SAME value — warns, but does not claim a disagreement', () => {
+  const { calls, warn } = capture();
+  resolveEnv('API_BASE', { prefix: 'BONGOS', env: { BONGOS_API_BASE: 'same', GDS_API_BASE: 'same' }, warn });
+  assert.equal(calls[0].shadowed, true);
+  assert.equal(calls[0].differs, false);
+});
+
+test('resolveEnv: every legacy spelling set gets its OWN warning, and the first one wins', () => {
+  const { calls, warn } = capture();
+  const v = resolveEnv('API_BASE', { prefix: 'BONGOS', env: { CLOUDBONGOS_API_BASE: 'a', OTB_API_BASE: 'b', PMS_API_BASE: 'c' }, warn });
+  assert.equal(v, 'a', 'LEGACY_ENV_PREFIXES order decides: CLOUDBONGOS before OTB before PMS');
+  assert.deepEqual(calls.map((c) => c.legacyName), ['CLOUDBONGOS_API_BASE', 'OTB_API_BASE', 'PMS_API_BASE']);
+});
+
+test('the deprecation warning is once per NAME per process, not once per read', () => {
+  const env = { CLOUDBONGOS_C3A_ONCE_PROBE: 'x', CLOUDBONGOS_C3A_ONCE_OTHER: 'y' };
+  const lines = captureConsole(() => {
+    resolveEnv('C3A_ONCE_PROBE', { prefix: 'BONGOS', env });
+    resolveEnv('C3A_ONCE_PROBE', { prefix: 'BONGOS', env }); // same name again
+    resolveEnv('C3A_ONCE_PROBE', { prefix: 'BONGOS', env });
+    resolveEnv('C3A_ONCE_OTHER', { prefix: 'BONGOS', env }); // a DIFFERENT name
+  });
+  assert.equal(lines.length, 2, 'three reads of one name warn once; a second name warns again');
+  assert.match(lines[0], /CLOUDBONGOS_C3A_ONCE_PROBE/);
+  assert.match(lines[1], /CLOUDBONGOS_C3A_ONCE_OTHER/);
+});
+
 // task 2051: docs+client are per-instance artifacts written to the instance root when
 // it is EXPLICITLY pointed at (a consumer running `bongos upgrade`), else the coreRoot.
 test('resolveInstanceRootExplicit: env pointer (branded or fallback prefix), else null', () => {

package/tests/upgrade.mjs

@@ -211,7 +211,7 @@ t('regenerateApiArtifacts: spawns docs then client from the new core, targeting
     assert.equal(c.cmd, process.execPath, 'runs node');
     assert.equal(c.opts.cwd, '/inst', 'cwd is the instance');
     // the env points the generators OUTPUT at the instance repo, not node_modules
-    assert.equal(c.opts.env.CLOUDBONGOS_INSTANCE_ROOT, '/inst');
+    assert.equal(c.opts.env.BONGOS_INSTANCE_ROOT, '/inst');
   }
 });
 
@@ -805,7 +805,7 @@ t('regenerateNavDocs: default set is the whole-file nav docs (session-index only
   assert.deepEqual(u.NAV_WHOLE_FILE_GENERATORS, ['gen-session-index.js']);
 });
 
-t('regenerateNavDocs: spawns each generator from the CORE against the INSTANCE root (cwd + CLOUDBONGOS_INSTANCE_ROOT), ok when all succeed', () => {
+t('regenerateNavDocs: spawns each generator from the CORE against the INSTANCE root (cwd + BONGOS_INSTANCE_ROOT), ok when all succeed', () => {
   const calls = [];
   const run = (cmd, args, opts) => { calls.push({ cmd, arg0: args[0], cwd: opts && opts.cwd, env: opts && opts.env }); return { status: 0 }; };
   const fsImpl = { existsSync: () => true };
@@ -815,7 +815,7 @@ t('regenerateNavDocs: spawns each generator from the CORE against the INSTANCE r
   assert.deepEqual(res.failed, []);
   assert.equal(calls.length, 1);
   assert.equal(calls[0].cwd, '/inst', 'runs with cwd = the instance dir');
-  assert.equal(calls[0].env.CLOUDBONGOS_INSTANCE_ROOT, '/inst', 'sets the instance-root env so the generator writes into the instance');
+  assert.equal(calls[0].env.BONGOS_INSTANCE_ROOT, '/inst', 'sets the instance-root env so the generator writes into the instance');
   assert.equal(calls[0].arg0, join('/core', 'scripts', 'gds', 'gen-session-index.js'), 'spawns the generator from the CORE package');
 });
 

package/tests/watch_applications_queue.mjs

@@ -368,8 +368,20 @@ await test('an empty view still offers the invite form and the switch out of it'
 });
 
 await test('a 403 seals the section rather than blanking the page', async () => {
+  // This used to assert the literal "Archons only". Task 1003449 removed that
+  // sentence from the page: the floor is read off the denial's `details.floors`
+  // now, because ADR 0157 moved most of this surface to metic and a page must
+  // not name a floor its gate does not enforce. THIS harness answers 403 with a
+  // null body, so there is no floor to name and the honest render is the subject
+  // clause alone. What the test was really pinning — the section seals, the page
+  // does not blank — is unchanged and is what it asserts.
+  //
+  // The floor-derivation itself is executed in tests/watch_sealed_floor.mjs,
+  // which scripts real envelopes at both floors.
   const h = await boot({ queueStatus: 403 });
-  assert.match(h.gate().textContent, /Archons only/);
+  assert.match(h.gate().textContent, /not visible at your rank/);
+  assert.doesNotMatch(h.gate().textContent, /Archon|Metic/,
+    'a denial with no floor in its body must name no rank');
   assert.equal(h.rows().length, 0);
 });
 

package/tests/watch_sealed_floor.mjs

@@ -0,0 +1,241 @@
+// tests/watch_sealed_floor.mjs — a sealed panel names the floor the SERVER
+// enforced, EXECUTED (task 1003449).
+//
+// THE DEFECT. Every panel on /watch answered a 403 with the literal string
+// "Archons only." ADR 0157 moved most of this surface to metic — five of the
+// atoms behind these panels carry "(ADR 0157, was archon)" in their own catalog
+// entry — so the page was teaching a permission model the server had stopped
+// implementing. The hall audit filed it against watch.html:30 and sessions.html:27;
+// both of those lines are gone (the page heads were rewritten by task 1003307) and
+// scouting.js was deleted by task 1003440, so the copy actually lived in the
+// fourteen `sealedMsg` strings in watch.js. The reported symptom was real; the
+// reported location was not.
+//
+// WHY THE FIX IS NOT "CHANGE archon TO metic". The floors are MIXED, and a blanket
+// rewrite would have been wrong in the other direction:
+//
+//   access_request.review   → archon   ("Archons only" was CORRECT here)
+//   override_request.decide → metic    (ADR 0157, was archon)
+//   builder.roster.read     → metic    (ADR 0157, was archon)
+//   session.search          → metic    (ADR 0157, was archon)
+//   audit_log.read          → metic    (ADR 0157, was archon)
+//   box.fleet.manage        → metic    (ADR 0157, was archon)
+//
+// A hardcoded 'metic' is the same defect one ADR later, which is why the fix reads
+// the floor off the DENIAL: requirePermission already rides `details.floors` on
+// every 403, and its own comment in src/bongos/auth.js names hardcoded prose as
+// "the D-16/N-3 failure shape ADR 0157 left behind". The page just never read it.
+//
+// These run the real watch.js in a vm against the real watch.html — the harness
+// tests/watch_applications_queue.mjs established — because the claim under test is
+// what a denied builder READS. A source grep can see that the string changed; it
+// cannot see which sentence a 403 actually paints.
+//
+// Run:  node tests/watch_sealed_floor.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { makeRunner, makeEl, parseInto } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules/hall-ui/public');
+const SRC = fs.readFileSync(path.join(HALL, 'watch.js'), 'utf8');
+const PAGE = fs.readFileSync(path.join(HALL, 'watch.html'), 'utf8');
+
+const { test, summary } = makeRunner();
+
+const escapeHtml = (s) => String(s == null ? '' : s).replace(/[&<>"']/g,
+  (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+const tick = () => new Promise((r) => setTimeout(r, 0));
+async function settle() { for (let i = 0; i < 40; i++) await tick(); }
+
+const ok = (data) => ({ status: 200, ok: true, data });
+
+// The ADR 0116 envelope requirePermission actually sends: the sentence, plus
+// `details.floors` mapping each MISSING permission key to its catalog floor.
+const denied = (floors) => ({
+  status: 403,
+  ok: false,
+  data: {
+    error: {
+      code: 'permission_forbidden',
+      message: 'missing permission',
+      details: { required: Object.keys(floors || {}), held: [], floors: floors || null },
+    },
+  },
+});
+
+// The label the page is expected to render the rank THROUGH. Distinct from the
+// bare rank key on purpose: if a test passed when the page printed the raw key,
+// it would also pass on an instance that renamed its ranks and got the old word.
+const LABELS = { archon: 'Archon', metic: 'Metic', thetes: 'Thetes', xenos: 'Xenos' };
+
+// ===========================================================================
+// Boot the real page, scripting one answer per route.
+// ===========================================================================
+
+async function boot({ answers = {}, fallback = ok({}) } = {}) {
+  const api = {
+    async request(method, p) {
+      const url = String(p).replace('/api/bongos', '');
+      const route = url.split('?')[0];
+      if (method === 'GET' && route === '/me') {
+        return ok({ builder: { id: 1, rank: 'metic', github_login: 'someone' } });
+      }
+      if (Object.prototype.hasOwnProperty.call(answers, route)) return answers[route];
+      return fallback;
+    },
+  };
+
+  const documentObj = {
+    readyState: 'complete',
+    body: makeEl('body'),
+    documentElement: makeEl('html'),
+    createElement: (tag) => makeEl(tag),
+    getElementById(id) { return this.body.querySelector(`#${id}`); },
+    querySelector(sel) { return this.body.querySelector(sel); },
+    querySelectorAll(sel) { return this.body.querySelectorAll(sel); },
+    addEventListener() {},
+  };
+  parseInto(documentObj.body, PAGE);
+
+  const locationObj = { hostname: 'builders.example.test', pathname: '/builders/watch', search: '', hash: '', assign() {} };
+
+  const kit = {
+    makeTabs: () => ({}),
+    makeLedger: () => ({ render() {} }),
+    makePager: () => ({ page: 1, perPage: 25 }),
+    emptyStateHtml: (msg) => `<div class="empty-state"><p>${escapeHtml(msg)}</p></div>`,
+    makeFilterBar: (o) => ({ el: o.mount, values: () => ({}) }),
+  };
+
+  const windowObj = {
+    __BRANDING__: { project: { joinability: 'apply' } },
+    OTB: {
+      escapeHtml,
+      $: (sel) => documentObj.querySelector(sel),
+      num: (v) => Number(v),
+      fmtInt: (n) => String(n),
+      fmtCompact: (n) => String(n),
+      fmtDate: (iso) => String(iso).slice(0, 10),
+      rankLabel: (r) => LABELS[String(r)] || '',
+      toast: () => {},
+    },
+    OTBKit: kit,
+    OTBBranding: { currencyLabel: () => 'Credits' },
+    BongosClient: { createClient: () => api },
+    location: locationObj,
+    addEventListener() {},
+  };
+
+  const sandbox = {
+    window: windowObj, document: documentObj, location: locationObj,
+    console: { log() {}, warn() {}, error() {} },
+    setTimeout, clearTimeout, Promise, Date, Math, JSON, Error, isNaN,
+    Number, String, Object, Array, Boolean, Set, Map, RegExp,
+    encodeURIComponent, decodeURIComponent, parseInt, parseFloat,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(SRC, sandbox, { filename: 'watch.js' });
+  await settle();
+
+  const sealed = (id) => {
+    const el = documentObj.getElementById(id);
+    const p = el && el.querySelector('.watch-unavailable');
+    return p ? p.textContent : null;
+  };
+  return { sealed, documentObj };
+}
+
+// ===========================================================================
+// The floor comes from the denial
+// ===========================================================================
+
+await test('an archon-floored panel still says Archon', async () => {
+  // access_request.review really is archon-floored, so the old copy happened to
+  // be right HERE. The fix must not "correct" a sentence that was already true.
+  const h = await boot({ answers: { '/access-requests': denied({ 'access_request.review': 'archon' }) } });
+  const msg = h.sealed('gate-body');
+  assert.ok(msg, 'the access-requests panel rendered no sealed message');
+  assert.match(msg, /^Archon and up\./, `expected the archon floor, got: ${msg}`);
+  assert.match(msg, /Access requests are not visible at your rank\./, `the subject clause was lost: ${msg}`);
+});
+
+await test('a metic-floored panel says Metic — the defect, in one assertion', async () => {
+  // This is the sentence a metic used to read as "Archons only" on a page they
+  // could open, having been told the ladder was something it is not.
+  const h = await boot({ answers: { '/audit-log': denied({ 'audit_log.read': 'metic' }) } });
+  const msg = h.sealed('audit-body');
+  assert.ok(msg, 'the audit-log panel rendered no sealed message');
+  assert.match(msg, /^Metic and up\./, `expected the metic floor, got: ${msg}`);
+  assert.doesNotMatch(msg, /Archon/, `the retired floor came back: ${msg}`);
+});
+
+await test('two panels denied at DIFFERENT floors say different things', async () => {
+  // The whole reason the floor is read rather than written: one page, two true
+  // answers. A blanket rewrite in either direction fails this test.
+  const h = await boot({
+    answers: {
+      '/access-requests': denied({ 'access_request.review': 'archon' }),
+      '/builders/roster': denied({ 'builder.roster.read': 'metic' }),
+    },
+  });
+  assert.match(h.sealed('gate-body'), /^Archon and up\./);
+  assert.match(h.sealed('roster-body'), /^Metic and up\./);
+});
+
+// ===========================================================================
+// The honest silences
+// ===========================================================================
+
+await test('a denial carrying NO floor names no rank at all', async () => {
+  // The government port is optional (ADR 0083), so `floors` can legitimately be
+  // absent. Naming a rank anyway is guessing, and guessing is what this task is.
+  const h = await boot({ answers: { '/audit-log': { status: 403, ok: false, data: null } } });
+  const msg = h.sealed('audit-body');
+  assert.equal(msg, 'The audit log is not visible at your rank.',
+    `a floorless denial must render the subject alone, got: ${msg}`);
+});
+
+await test('a denial on keys with CONFLICTING floors names no rank', async () => {
+  // A multi-atom gate can deny on two keys with different floors. There is no
+  // single honest sentence, so the panel says none rather than picking the one
+  // that happens to sort first.
+  const h = await boot({
+    answers: { '/audit-log': denied({ 'audit_log.read': 'metic', 'something.else': 'archon' }) },
+  });
+  const msg = h.sealed('audit-body');
+  assert.equal(msg, 'The audit log is not visible at your rank.',
+    `an ambiguous floor must not be resolved by guessing, got: ${msg}`);
+});
+
+// ===========================================================================
+// The literal cannot come back
+// ===========================================================================
+
+await test('no sealed message on this page hardcodes a rank name', async () => {
+  // The source half of the claim: a future edit that re-writes "Archons only."
+  // into a sealedMsg reds here even if it never renders in a test.
+  const strings = [...SRC.matchAll(/sealedMsg:\s*'([^']*)'/g)].map((m) => m[1]);
+  assert.ok(strings.length >= 10, `expected the page's sealed messages, found ${strings.length}`);
+  for (const s of strings) {
+    assert.doesNotMatch(s, /Archon|Metic|Thetes|Xenos/i,
+      `a sealed message names a rank in its own text: "${s}". The rank comes from `
+      + 'the 403, or the sentence does not claim one.');
+  }
+});
+
+await test('the 403 path carries the floor rather than discarding the body', async () => {
+  // fetchJson used to throw a bare { kind: '403' }, which is what made every
+  // panel's sentence a guess. Pin the shape, not just the rendered output.
+  assert.match(SRC, /details\.floors/,
+    'fetchJson must read details.floors off the denial — otherwise the page is '
+    + 'back to writing the floor itself');
+});
+
+summary('watch sealed floor (task 1003449)');