@bongos/core 1.19.654 → 1.19.656

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.656'; // 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/government_claim_eligibility.mjs

@@ -37,6 +37,13 @@ const LIFECYCLE = path.join(ROOT, 'modules', 'lifecycle');
 const eligibility = require(path.join(LIFECYCLE, 'claim-eligibility.js'));
 const db = require(path.join(LIFECYCLE, 'db.js'));
 const catalog = require(path.join(ROOT, 'modules', 'government', 'catalog.js'));
+// The doorway, so section D can stand a stub `government` port up in front of the
+// REAL claimPermissionsFor instead of re-implementing its branches in the test.
+const moduleApi = require(path.join(ROOT, 'src', 'module-api.js'));
+// claimPermissionsFor is NOT on the db.js facade — db-claims.js imports it from
+// the authz module directly, so the test reads it from the same place the real
+// caller does rather than from a re-export that does not exist.
+const rankAuthz = require(path.join(LIFECYCLE, 'db-rank-authz.js'));
 import { lifecycleDbSource } from './helpers.mjs';
 
 const { CLAIM_ANY, CLAIM_NEWCOMER, permissionAllowsClaim, claimEligibilityAllows } = eligibility;
@@ -262,3 +269,78 @@ test('the abuse case stays blocked: a xenos cannot reach the general queue by an
   assert.equal(permissionAllowsClaim(held, false), false);
   assert.equal(permissionAllowsClaim(held, true), true);
 });
+
+// --- D. claimPermissionsFor's three-way answer (task 1003816) ---------------
+//
+// The function this section covers had NO test of its own: every case above
+// drives the pure consumer (claimEligibilityAllows) with a hand-made
+// heldPermissions value, so nothing proved which value the REAL reader produces.
+// That is exactly where the bug lived — an empty permission set was folded in
+// with "could not establish authority" and silently became a rank-rule fallback.
+//
+// The distinction is the whole point, so it is asserted as a distinction: null
+// (fall back) for the two unestablished cases, a Set (a real verdict, denied when
+// empty) whenever the resolver actually answered.
+const realResolveOptional = moduleApi.resolveOptional;
+async function withGovernance(stub, fn) {
+  moduleApi.resolveOptional = (name) => (name === 'government' ? stub : realResolveOptional.call(moduleApi, name));
+  try { return await fn(); } finally { moduleApi.resolveOptional = realResolveOptional; }
+}
+
+test('no governance port — authority cannot be established, so the rank rule decides', async () => {
+  await withGovernance(undefined, async () => {
+    assert.equal(await rankAuthz.claimPermissionsFor('42'), null);
+  });
+  // A port object that does not implement the resolver is the same situation.
+  await withGovernance({}, async () => {
+    assert.equal(await rankAuthz.claimPermissionsFor('42'), null);
+  });
+});
+
+test('the resolver throwing is UNKNOWN, not empty — still the rank rule', async () => {
+  await withGovernance({ resolveBuilderPermissions: async () => { throw new Error('synthetic resolver outage'); } }, async () => {
+    assert.equal(await rankAuthz.claimPermissionsFor('42'), null);
+  });
+});
+
+test('a broken port contract (non-array) is unknown, never a deny', async () => {
+  for (const bad of [null, undefined, 'task.claim.any', 42, {}]) {
+    await withGovernance({ resolveBuilderPermissions: async () => bad }, async () => {
+      assert.equal(await rankAuthz.claimPermissionsFor('42'), null, `a ${typeof bad} return must not read as "denied"`);
+    });
+  }
+});
+
+test('ZERO permissions is a real verdict now, not a fallback (the 1003816 fix)', async () => {
+  await withGovernance({ resolveBuilderPermissions: async () => [] }, async () => {
+    const held = await rankAuthz.claimPermissionsFor('42');
+    assert.ok(held instanceof Set, 'an answered resolve returns a Set, so the rank rule is NOT consulted');
+    assert.equal(held.size, 0);
+    // And the consumer turns that into a deny for every queue, however permissive
+    // the incumbent rank rule would have been.
+    for (const nf of NF_VALUES) {
+      assert.equal(
+        claimEligibilityAllows({ heldPermissions: held, newcomerFriendly: nf, rankRuleAllows: true }),
+        false,
+        'a builder with no role row is denied even where the rank rule would allow',
+      );
+    }
+  });
+});
+
+test('a real permission set is passed through as the verdict', async () => {
+  await withGovernance({ resolveBuilderPermissions: async () => [CLAIM_ANY] }, async () => {
+    const held = await rankAuthz.claimPermissionsFor('42');
+    assert.ok(held instanceof Set);
+    assert.equal(held.has(CLAIM_ANY), true);
+    assert.equal(claimEligibilityAllows({ heldPermissions: held, newcomerFriendly: false, rankRuleAllows: false }), true);
+  });
+});
+
+test('the doc comment no longer argues for the fallback it describes retiring', () => {
+  const src = fs.readFileSync(path.join(LIFECYCLE, 'db-rank-authz.js'), 'utf8');
+  assert.ok(
+    !/nothing yet re-assigns a rank-role/.test(src),
+    'the stale "nothing yet re-assigns a rank-role" claim is false since BV1.R95b + task 1003193 — it must not survive the fix',
+  );
+});

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);
 });