@bongos/core 1.18.0 → 1.18.18

package/tests/upgrade.mjs

@@ -16,10 +16,11 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 
 const require = createRequire(import.meta.url);
 const u = require('../scripts/gds/upgrade.js');
+const pc = require('../scripts/gds/package-core.js'); // the packager — reuse its EXACT hash fns to build reference pins
 
 let passed = 0, failed = 0;
 const pending = [];
@@ -159,7 +160,9 @@ t('full: pre-flight → pin → install → migrate → materialize → restart
   let materialized = null;
   let regenArgs = null;
   const res = await u.runUpgrade(
-    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'emersonian.service' },
+    // healthCheck:false — this test exercises the full pipeline, not the health poll (which would need
+    // a fetch mock); a managed-restart bump now requires a --health-url unless health is opted out (H9).
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'emersonian.service', healthCheck: false },
     {
       log: () => {}, err: () => {},
       run: fakeRun(calls, { dirty: '', installTo: '1.15.0', dir }),
@@ -398,7 +401,7 @@ t('runUpgrade --registry (full): pins the exact version + writes the env-fed .np
   const dir = scratchConsumer({ pinned: '1.16.0', installed: '1.16.0' });
   const calls = [];
   const res = await u.runUpgrade(
-    { to: '1.17.0', registry: true, instance: dir, service: 'demo.service' },
+    { to: '1.17.0', registry: true, instance: dir, service: 'demo.service', healthCheck: false }, // H9: opt out (no health poll under test)
     {
       log: () => {}, err: () => {},
       run: fakeRun(calls, { dirty: '', installTo: '1.17.0', dir }),
@@ -479,7 +482,7 @@ t('rollback on migrate failure: reverts pin + reinstalls previous core + rolled_
   const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
   const calls = [], queries = [];
   const res = await u.runUpgrade(
-    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthCheck: false }, // H9: opt out — this test is about migrate-failure rollback, not health
     {
       log: () => {}, err: () => {},
       run: pinAwareRun(calls, { dir, failMigrate: true }),
@@ -502,7 +505,7 @@ t('rollback on npm-install failure: reverts pin + reinstalls previous core', asy
   const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
   const calls = [], queries = [];
   const res = await u.runUpgrade(
-    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthCheck: false }, // H9: opt out — this test is about install-failure rollback, not health
     {
       log: () => {}, err: () => {},
       run: pinAwareRun(calls, { dir, failInstallForVersion: '1.15.0' }),
@@ -547,6 +550,391 @@ t('restorePin: writes a previous dep string back verbatim (file: or registry)',
   assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '^1.16.0');
 });
 
+// ---- 7. integrity-pin verification (task 1002216 / audit H8, finding F1) ----
+// Build a reference pin exactly as the packager does — canonicalTreeHash over the pinned
+// files' sha256, so a matching installed tree recomputes byte-identically.
+function pinManifestFor(files, { tarballSha = null, tarballBytes = 0 } = {}) {
+  const meta = files
+    .map((f) => ({ path: f.path, mode: f.mode || '0000644', sha256: pc.sha256hex(Buffer.from(f.content)) }))
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const m = { artifact: 'bongos-core', tree_sha256: pc.canonicalTreeHash(meta), files: meta };
+  if (tarballSha) m.tarball = { name: 'bongos-core.tgz', sha256: tarballSha, bytes: tarballBytes };
+  return m;
+}
+function writeCoreTree(coreDir, files) {
+  for (const f of files) {
+    const abs = join(coreDir, ...f.path.split('/'));
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, f.content);
+  }
+}
+const PIN_FILES = [{ path: 'a.js', content: 'console.log(1)\n' }, { path: 'sub/b.json', content: '{"x":1}\n' }];
+
+t('verifyInstalledPin: matching installed tree + tarball bytes → ok (both checks)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, PIN_FILES);
+  const tgzBytes = Buffer.from('deterministic-fake-tgz');
+  const tgz = join(dir, 'vendor', 'bongos-core-1.15.0.tgz');
+  mkdirSync(dirname(tgz), { recursive: true });
+  writeFileSync(tgz, tgzBytes);
+  const m = pinManifestFor(PIN_FILES, { tarballSha: pc.sha256hex(tgzBytes), tarballBytes: tgzBytes.length });
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: m, tgzPath: tgz });
+  assert.equal(res.ran, true);
+  assert.equal(res.ok, true, res.problems.join('; '));
+  assert.deepEqual(res.checks.map((c) => c.name).sort(), ['tarball.sha256', 'tree_sha256']);
+});
+
+t('verifyInstalledPin: a corrupted installed file → mismatch (ran, not ok)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, PIN_FILES);
+  const m = pinManifestFor(PIN_FILES);
+  writeFileSync(join(coreDir, 'a.js'), 'console.log(999) // tampered\n'); // corrupt AFTER pinning
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: m, tgzPath: null });
+  assert.equal(res.ran, true);
+  assert.equal(res.ok, false);
+  assert.ok(res.problems.some((p) => /content mismatch: a\.js/.test(p)), res.problems.join('; '));
+});
+
+t('verifyInstalledPin: a missing installed file → mismatch', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, [PIN_FILES[0]]); // omit sub/b.json
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: pinManifestFor(PIN_FILES), tgzPath: null });
+  assert.equal(res.ok, false);
+  assert.ok(res.problems.some((p) => /missing installed file: sub\/b\.json/.test(p)), res.problems.join('; '));
+});
+
+t('verifyInstalledPin: tarball bytes differ from the pin → mismatch', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  writeCoreTree(coreDir, PIN_FILES);
+  const tgz = join(dir, 'vendor', 'bongos-core-1.15.0.tgz');
+  mkdirSync(dirname(tgz), { recursive: true });
+  writeFileSync(tgz, Buffer.from('the-actual-bytes'));
+  const m = pinManifestFor(PIN_FILES, { tarballSha: pc.sha256hex(Buffer.from('DIFFERENT-bytes')), tarballBytes: 9 });
+  const res = u.verifyInstalledPin({ coreDir, referenceManifest: m, tgzPath: tgz });
+  assert.equal(res.ok, false);
+  assert.ok(res.problems.some((p) => /tarball bytes/.test(p)), res.problems.join('; '));
+});
+
+t('verifyInstalledPin: no pin in the reference manifest → ran:false (nothing to check)', () => {
+  const res = u.verifyInstalledPin({ coreDir: '/nonexistent', referenceManifest: {}, tgzPath: null });
+  assert.equal(res.ran, false);
+  assert.equal(res.ok, false);
+});
+
+t('resolveReferenceManifest: prefers the committed vendored side-car (strong)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json'), JSON.stringify(pinManifestFor(PIN_FILES)));
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'x');
+  const ref = u.resolveReferenceManifest({ instanceDir: dir, coreDir, targetVersion: '1.15.0' });
+  assert.equal(ref.source, 'vendored side-car manifest');
+  assert.equal(ref.strong, true);
+  assert.ok(ref.tgzPath && existsSync(ref.tgzPath));
+});
+
+t('resolveReferenceManifest: falls back to the installed inner manifest (not strong)', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-pin-'));
+  const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+  mkdirSync(coreDir, { recursive: true });
+  writeFileSync(join(coreDir, '.bongos-core.json'), JSON.stringify(pinManifestFor(PIN_FILES)));
+  const ref = u.resolveReferenceManifest({ instanceDir: dir, coreDir, targetVersion: '1.15.0' });
+  assert.equal(ref.source, 'installed inner manifest');
+  assert.equal(ref.strong, false);
+  assert.equal(ref.tgzPath, null);
+});
+
+// A spawn shim whose `npm install` writes an installed core tree (+ version) so the
+// real pin-verify step can run against it. `files` is what actually lands on disk.
+function installWritingTree(calls, { dir, version, files }) {
+  return (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: '' };
+    if (cmd === 'npm' && args[0] === 'install') {
+      const coreDir = join(dir, 'node_modules', '@bongos', 'core');
+      writeCoreTree(coreDir, files);
+      writeFileSync(join(coreDir, 'package.json'), JSON.stringify({ name: '@bongos/core', version }) + '\n');
+    }
+    return { status: 0 };
+  };
+}
+
+t('runUpgrade: a matching pin passes verification (upgrade proceeds)', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz');
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json'),
+    JSON.stringify(pinManifestFor(PIN_FILES, { tarballSha: pc.sha256hex(Buffer.from('fake-tgz')), tarballBytes: 8 })));
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir },
+    {
+      log: (m) => logs.push(m), err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: PIN_FILES }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.ok(logs.some((m) => /integrity pin verified.*tarball\.sha256.*tree_sha256/.test(m)), logs.join('\n'));
+});
+
+t('runUpgrade: a pin MISMATCH after install fails and auto-rolls-back', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz');
+  // The reference pin is for PIN_FILES, but install writes DIFFERENT content → tree mismatch.
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json'), JSON.stringify(pinManifestFor(PIN_FILES)));
+  const corrupted = [{ path: 'a.js', content: 'console.log(666)\n' }, { path: 'sub/b.json', content: '{"x":1}\n' }];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir },
+    {
+      log: () => {}, err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: corrupted }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(/integrity pin MISMATCH/.test(res.error || ''), res.error);
+  assert.equal(res.rolledBack, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted to the previous version on rollback');
+});
+
+t('runUpgrade: --require-pin makes a MISSING reference manifest fatal', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz'); // tgz present, but NO manifest
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir, requirePin: true },
+    {
+      log: () => {}, err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: PIN_FILES }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(/no reference manifest/.test(res.error || ''), res.error);
+  assert.equal(res.rolledBack, true, 'unverifiable pin rolls back under --require-pin');
+});
+
+t('runUpgrade: --skip-pin-verify bypasses the check (no manifest, still succeeds)', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  mkdirSync(join(dir, 'vendor'), { recursive: true });
+  writeFileSync(join(dir, 'vendor', 'bongos-core-1.15.0.tgz'), 'fake-tgz');
+  const res = await u.runUpgrade(
+    { to: '1.15.0', instance: dir, skipPinVerify: true },
+    {
+      log: () => {}, err: () => {},
+      run: installWritingTree([], { dir, version: '1.15.0', files: PIN_FILES }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+    }
+  );
+  assert.equal(res.ok, true, res.error);
+});
+
+// ---- 8. mandatory post-restart health check (task 1002222 / audit H9, finding F5) ----
+t('runUpgrade: a managed-restart bump WITHOUT --health-url is refused up front (H9 mandatory)', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' }, // restarts, no --health-url, not opted out
+    { log: () => {}, err: () => {}, run: fakeRun(calls, { dirty: '', installTo: '1.15.0', dir }), materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }) }
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /health check is mandatory/);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'refused in pre-flight → pin untouched');
+  assert.ok(!calls.some((c) => /npm install/.test(c)), 'refused before any install');
+});
+
+t('runUpgrade: --no-health-check lets a managed-restart bump proceed without a URL', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthCheck: false },
+    { log: (m) => logs.push(m), err: () => {}, run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }), materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }) }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.ok(logs.some((m) => /health check skipped \(--no-health-check\)/.test(m)), logs.join('\n'));
+});
+
+t('runUpgrade: a managed-restart bump WITH a healthy --health-url confirms + succeeds', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthUrl: 'http://x/healthz' },
+    {
+      log: (m) => logs.push(m), err: () => {}, run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      fetch: async () => ({ ok: true, status: 200 }), sleep: async () => {}, now: () => 0,
+    }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.equal(res.healthOk, true);
+  assert.ok(logs.some((m) => /health http:\/\/x\/healthz → 200/.test(m)), logs.join('\n'));
+});
+
+t('runUpgrade: no managed restart + no --health-url proceeds but flags the bump as unconfirmed', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const logs = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir }, // no service/restart-cmd, no --health-url
+    { log: (m) => logs.push(m), err: () => {}, run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }), materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }) }
+  );
+  assert.equal(res.ok, true, res.error);
+  assert.equal(res.healthOk, null);
+  assert.ok(logs.some((m) => /not confirmed serving/.test(m)), logs.join('\n'));
+});
+
+// ---- regenerateNavDocs (ADR 0147 / task 1002314) ----------------------------
+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', () => {
+  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 };
+  const res = u.regenerateNavDocs({ instanceDir: '/inst', coreRoot: '/core', generators: ['gen-session-index.js'] }, run, fsImpl);
+  assert.equal(res.ok, true);
+  assert.deepEqual(res.ran, ['gen-session-index.js']);
+  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].arg0, join('/core', 'scripts', 'gds', 'gen-session-index.js'), 'spawns the generator from the CORE package');
+});
+
+t('regenerateNavDocs: a MISSING generator is recorded as failed but the others still run (best-effort)', () => {
+  const spawned = [];
+  const run = (_cmd, args) => { spawned.push(args[0]); return { status: 0 }; };
+  const fsImpl = { existsSync: (p) => !String(p).endsWith('gen-missing.js') };
+  const res = u.regenerateNavDocs({ instanceDir: '/inst', coreRoot: '/core', generators: ['gen-missing.js', 'gen-session-index.js'] }, run, fsImpl);
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['gen-session-index.js']);
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].gen, 'gen-missing.js');
+  assert.equal(spawned.length, 1, 'the missing generator is not spawned; the present one still is');
+});
+
+t('regenerateNavDocs: a generator that exits nonzero is LOUD-failed (ok:false) without aborting the rest', () => {
+  const run = (_cmd, args) => ({ status: String(args[0]).endsWith('gen-boom.js') ? 2 : 0 });
+  const fsImpl = { existsSync: () => true };
+  const res = u.regenerateNavDocs({ instanceDir: '/inst', coreRoot: '/core', generators: ['gen-boom.js', 'gen-session-index.js'] }, run, fsImpl);
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['gen-session-index.js']);
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].gen, 'gen-boom.js');
+  assert.match(res.failed[0].reason, /exited 2/);
+});
+
+// ---- healDocAssets (task 1002441) -------------------------------------------
+// An upgrade replaces node_modules wholesale, so it WIPES the two gitignored, core-scoped
+// generated doc assets (atlas.json + the diagram .svg/.png renders) and the new tarball carries
+// only the .mmd sources. These pin that the upgrade puts them back.
+
+// A fake core tree. `renders` controls whether each .mmd already has its .svg + .png beside it.
+function docAssetFs({ atlas = true, sources = ['01-a.mmd', '02-b.mmd'], renders = true } = {}) {
+  const present = new Set();
+  if (atlas) present.add(join('/core', 'modules', 'hall-ui', 'public', 'atlas.json'));
+  present.add(join('/core', 'scripts', 'gds', 'gen-atlas.js'));
+  present.add(join('/core', 'scripts', 'render-diagrams.sh'));
+  if (renders) {
+    for (const s of sources) {
+      const base = join('/core', 'docs', 'onboarding', 'diagrams', s.replace(/\.mmd$/, ''));
+      present.add(`${base}.svg`); present.add(`${base}.png`);
+    }
+  }
+  return { existsSync: (p) => present.has(String(p)), readdirSync: () => sources, _present: present };
+}
+
+t('missingDocAssets: a freshly-upgraded core (only .mmd sources, no atlas.json) reports BOTH groups missing', () => {
+  const fsImpl = docAssetFs({ atlas: false, renders: false });
+  assert.deepEqual(u.missingDocAssets('/core', fsImpl), ['atlas', 'diagrams']);
+});
+
+t('missingDocAssets: a fully-generated core reports nothing missing (steady state — no work)', () => {
+  assert.deepEqual(u.missingDocAssets('/core', docAssetFs()), []);
+});
+
+t('missingDocAssets: only atlas.json gone → only the atlas group', () => {
+  assert.deepEqual(u.missingDocAssets('/core', docAssetFs({ atlas: false })), ['atlas']);
+});
+
+t('missingDocAssets: a half-rendered diagram set (one .mmd lacking its .png) counts as missing', () => {
+  const fsImpl = docAssetFs();
+  fsImpl._present.delete(join('/core', 'docs', 'onboarding', 'diagrams', '02-b.png'));
+  assert.deepEqual(u.missingDocAssets('/core', fsImpl), ['diagrams']);
+});
+
+t('missingDocAssets: a core with NO diagram dir does not report diagrams (readdir throws → nothing to render)', () => {
+  const fsImpl = docAssetFs();
+  fsImpl.readdirSync = () => { throw new Error('ENOENT'); };
+  assert.deepEqual(u.missingDocAssets('/core', fsImpl), []);
+});
+
+t('healDocAssets: the post-upgrade case regenerates BOTH, node for the atlas and bash for the renders, cwd = coreRoot', () => {
+  const calls = [];
+  const run = (cmd, args, opts) => { calls.push({ cmd, arg0: args[0], cwd: opts && opts.cwd }); return { status: 0 }; };
+  const res = u.healDocAssets({ coreRoot: '/core' }, run, docAssetFs({ atlas: false, renders: false }));
+  assert.equal(res.ok, true);
+  assert.deepEqual(res.ran, ['atlas', 'diagrams']);
+  assert.equal(calls.length, 2);
+  assert.equal(calls[0].cmd, process.execPath, 'atlas generator runs under node');
+  assert.equal(calls[0].arg0, join('/core', 'scripts', 'gds', 'gen-atlas.js'));
+  assert.equal(calls[1].cmd, 'bash', 'the diagram renderer is a shell script');
+  assert.equal(calls[1].arg0, join('/core', 'scripts', 'render-diagrams.sh'));
+  assert.ok(calls.every((c) => c.cwd === '/core'), 'both run against the CORE root, where the assets live');
+});
+
+t('healDocAssets: nothing missing → spawns NOTHING (safe to call from a deploy loop)', () => {
+  let spawned = 0;
+  const res = u.healDocAssets({ coreRoot: '/core' }, () => { spawned++; return { status: 0 }; }, docAssetFs());
+  assert.equal(spawned, 0);
+  assert.deepEqual(res.missing, []);
+  assert.equal(res.ok, true);
+});
+
+t('healDocAssets: only the MISSING group is regenerated (atlas present → renderer only)', () => {
+  const spawned = [];
+  const run = (_c, args) => { spawned.push(args[0]); return { status: 0 }; };
+  const res = u.healDocAssets({ coreRoot: '/core' }, run, docAssetFs({ renders: false }));
+  assert.deepEqual(res.ran, ['diagrams']);
+  assert.equal(spawned.length, 1);
+  assert.match(String(spawned[0]), /render-diagrams\.sh$/);
+});
+
+t('healDocAssets: a failing renderer (no Chromium) is LOUD-failed but the atlas still heals — never aborts the bump', () => {
+  const run = (_c, args) => ({ status: String(args[0]).endsWith('render-diagrams.sh') ? 1 : 0 });
+  const res = u.healDocAssets({ coreRoot: '/core' }, run, docAssetFs({ atlas: false, renders: false }));
+  assert.equal(res.ok, false, 'reported as incomplete');
+  assert.deepEqual(res.ran, ['atlas'], 'the independent atlas still regenerated');
+  assert.equal(res.failed.length, 1);
+  assert.equal(res.failed[0].group, 'diagrams');
+  assert.match(res.failed[0].reason, /exited 1/);
+});
+
+t('healDocAssets: a generator absent from this core is recorded, not spawned', () => {
+  const fsImpl = docAssetFs({ atlas: false, renders: false });
+  fsImpl._present.delete(join('/core', 'scripts', 'render-diagrams.sh'));
+  const spawned = [];
+  const res = u.healDocAssets({ coreRoot: '/core' }, (_c, args) => { spawned.push(args[0]); return { status: 0 }; }, fsImpl);
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['atlas']);
+  assert.match(res.failed[0].reason, /not found in core/);
+  assert.equal(spawned.length, 1, 'the absent script is never spawned');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/web_admission_status.mjs

@@ -0,0 +1,162 @@
+// tests/web_admission_status.mjs — auth.webAdmissionStatus (task 1002097).
+//
+// The stub must go into require.cache BEFORE auth.js loads: auth.js destructures
+// accessStateByLogin at require time, so patching the export object afterwards
+// would not rebind what it already captured.
+//
+// Run:  node tests/web_admission_status.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+// --- stub the kernel BEFORE auth.js captures its bindings ------------------
+const kernelPath = require.resolve('../src/bongos/db-kernel.js');
+const realKernel = require(kernelPath);
+
+let dbState = { member: false, invited: false, pending: false };
+let dbThrows = false;
+
+require.cache[kernelPath].exports = {
+  ...realKernel,
+  accessStateByLogin: async () => {
+    if (dbThrows) throw new Error('simulated DB outage');
+    return dbState;
+  },
+};
+
+const auth = require('../src/bongos/auth.js');
+
+const FIRST_ADMIN = 'ownerlogin';
+// OTB is a permanent entry in LEGACY_ENV_PREFIXES, so this resolves regardless
+// of the instance's own env prefix — and regardless of whether the branding
+// pack configures a firstAdmin (this repo's does not).
+process.env.OTB_FIRST_ADMIN = FIRST_ADMIN;
+
+function setDb({ member = false, invited = false, pending = false } = {}) {
+  dbState = { member, invited, pending };
+  dbThrows = false;
+}
+
+function withOpenEnrollment(val, fn) {
+  const prev = process.env.OTB_OPEN_XENOS_ENROLLMENT;
+  if (val === undefined) delete process.env.OTB_OPEN_XENOS_ENROLLMENT;
+  else process.env.OTB_OPEN_XENOS_ENROLLMENT = val;
+  return Promise.resolve()
+    .then(fn)
+    .finally(() => {
+      if (prev === undefined) delete process.env.OTB_OPEN_XENOS_ENROLLMENT;
+      else process.env.OTB_OPEN_XENOS_ENROLLMENT = prev;
+    });
+}
+
+let passed = 0;
+let failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+await t('a blank or missing login is never admitted', async () => {
+  setDb({ member: true });
+  for (const bad of ['', '   ', null, undefined]) {
+    assert.deepEqual(await auth.webAdmissionStatus(bad), { admitted: false, expectedSoon: false });
+  }
+});
+
+await t('an existing builder is admitted', async () => {
+  setDb({ member: true });
+  assert.deepEqual(await auth.webAdmissionStatus('someone'), { admitted: true, expectedSoon: true });
+});
+
+await t('an invited login is admitted', async () => {
+  setDb({ invited: true });
+  assert.deepEqual(await auth.webAdmissionStatus('someone'), { admitted: true, expectedSoon: true });
+});
+
+await t('PENDING is the keep-polling case: not admitted, but expected soon', async () => {
+  // The whole point of the waiting page — an Archon is about to flip this to
+  // invited, so the visitor should wait rather than see a rejection.
+  setDb({ pending: true });
+  assert.deepEqual(await auth.webAdmissionStatus('someone'), { admitted: false, expectedSoon: true });
+});
+
+await t('a genuine stranger is neither admitted nor expected', async () => {
+  // Must be false, or the stranger gets a spinner that never resolves instead
+  // of the request-access page.
+  setDb({});
+  assert.deepEqual(await auth.webAdmissionStatus('nobody'), { admitted: false, expectedSoon: false });
+});
+
+await t('the configured firstAdmin is admitted with nothing in the DB', async () => {
+  // The bootstrap window this task was filed for: a fresh instance where the
+  // owner has no builder row and no access_request yet.
+  setDb({});
+  assert.deepEqual(await auth.webAdmissionStatus(FIRST_ADMIN), { admitted: true, expectedSoon: true });
+});
+
+await t('the firstAdmin match is case-insensitive and trims', async () => {
+  setDb({});
+  assert.equal((await auth.webAdmissionStatus('OwNerLogin')).admitted, true);
+  assert.equal((await auth.webAdmissionStatus(`  ${FIRST_ADMIN.toUpperCase()}  `)).admitted, true);
+});
+
+await t('open enrollment admits anyone', async () => {
+  setDb({});
+  await withOpenEnrollment('1', async () => {
+    assert.deepEqual(await auth.webAdmissionStatus('anyone'), { admitted: true, expectedSoon: true });
+  });
+});
+
+await t('a DB outage fails CLOSED on admitted', async () => {
+  // Never let an error read as "you're in".
+  dbThrows = true;
+  // The helper logs the outage by design; mute it so the unit gate's output
+  // stays readable (the assertions below are what prove the behaviour).
+  const realError = console.error;
+  console.error = () => {};
+  try {
+    const stranger = await auth.webAdmissionStatus('nobody');
+    assert.equal(stranger.admitted, false);
+    assert.equal(stranger.expectedSoon, false);
+    // ...but the owner may still keep polling through a transient outage, since
+    // the bootstrap window is exactly when the DB may be settling.
+    const owner = await auth.webAdmissionStatus(FIRST_ADMIN);
+    assert.equal(owner.admitted, false);
+    assert.equal(owner.expectedSoon, true);
+  } finally {
+    console.error = realError;
+    dbThrows = false;
+  }
+});
+
+await t('ANTI-DRIFT: admitted always equals the real gate\'s verdict', async () => {
+  // The probe must never disagree with firstTimeAdmissionBlocked — that is the
+  // one gate both sign-in flows call. Sweep the full input space.
+  for (const member of [false, true]) {
+    for (const invited of [false, true]) {
+      for (const openEnroll of [undefined, '1']) {
+        for (const login of ['nobody', FIRST_ADMIN]) {
+          setDb({ member, invited });
+          await withOpenEnrollment(openEnroll, async () => {
+            const probe = await auth.webAdmissionStatus(login);
+            const blocked = auth.firstTimeAdmissionBlocked({
+              existing: member ? { id: 1 } : null,
+              approved: invited,
+              login,
+            });
+            assert.equal(
+              probe.admitted, !blocked,
+              `drift: member=${member} invited=${invited} open=${openEnroll} login=${login} `
+              + `→ probe.admitted=${probe.admitted} but gate blocked=${blocked}`,
+            );
+          });
+        }
+      }
+    }
+  }
+});
+
+console.log(`\nweb admission status (task 1002097): ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);