@bongos/core 1.19.90 → 1.19.92

package/tests/landing_page.mjs

@@ -0,0 +1,289 @@
+// tests/landing_page.mjs — the apex landing page (task 1002748, goal 1000061).
+//
+// Contract: docs/design/landing-page-direction.md + docs/design/mocks/landing-page-mock.html.
+// These lock the four properties the direction calls load-bearing, each of which
+// fails SILENTLY in a browser and so cannot be caught by looking at the page:
+//
+//   * the apex conditional — public-landing/ ships wholesale to every instance,
+//     so the platform-only sections must be REMOVED (not hidden) off the hub;
+//   * the server-stamped head — social tags are read before JS runs, so they
+//     cannot be client-filled, and they must not be baked to one instance;
+//   * the branding cascade — a page-local :root silently outranks the pack's
+//     injected theme and defeats re-branding (direction C1);
+//   * no hardcoded apex — the file is portable or it lies to child instances.
+//
+// Deliberately NOT asserted here: that GET / returns the page. It does not — the
+// apex still 302s into the gate until the hub exists (task 1002743 part 3), which
+// is why tests/platform_boot.mjs stays parked in run-unit-tests KNOWN_FAILING.
+// This file tests the artifact that flip will serve.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HTML = fs.readFileSync(path.join(ROOT, 'public-landing', 'index.html'), 'utf8');
+
+const { stripApexOnly } = require('../src/platform-server.js');
+const { applyBrandTokens } = require('../src/bongos/serve-internal.js');
+
+// ── the apex conditional ───────────────────────────────────────────────────
+
+test('the apex-only sentinels are balanced and each one wraps content', () => {
+  const starts = HTML.match(/<!--apex-only:start-->/g) || [];
+  const ends = HTML.match(/<!--apex-only:end-->/g) || [];
+  assert.equal(starts.length, ends.length, 'every apex-only:start needs its end');
+  assert.ok(starts.length >= 4, 'the direction marks four apex-only regions');
+  // no start after an unclosed start — a nested pair would make the non-greedy
+  // strip close on the wrong sentinel and leak the platform's claims.
+  let depth = 0;
+  for (const m of HTML.matchAll(/<!--apex-only:(start|end)-->/g)) {
+    depth += m[1] === 'start' ? 1 : -1;
+    assert.ok(depth === 0 || depth === 1, 'apex-only regions must not nest');
+  }
+  assert.equal(depth, 0);
+});
+
+test('the hub keeps every apex-only section', () => {
+  assert.equal(stripApexOnly(HTML, true), HTML);
+});
+
+test('a child instance is served none of the platform-only claims', () => {
+  const child = stripApexOnly(HTML, false);
+  assert.doesNotMatch(child, /<!--apex-only:(start|end)-->/, 'no sentinel survives the strip');
+  // the four regions, by their load-bearing content
+  assert.doesNotMatch(child, /capture-resistant commons/, 'the commons claim is the platform\'s, not a child\'s');
+  assert.doesNotMatch(child, /Built on Cloud Bongos/, 'a child has no catalog of other instances');
+  assert.doesNotMatch(child, /What you own/, 'the AGPL/ownership pitch is the platform\'s');
+  assert.doesNotMatch(child, /See what's building/, 'the catalog CTA has nothing to point at');
+});
+
+test('a child instance keeps the whole portable spine', () => {
+  const child = stripApexOnly(HTML, false);
+  for (const portable of [
+    'Building software is laying', // the hero tagline
+    'the ledger', 'the gates', 'the grade', // S3, the differentiator
+    'How a change reaches your project', // S4
+    'Build a project', 'Join as a builder', // S7, both doors
+    'Built by agents, on Cloud', // the portable half of the footer
+    'id="who"', // the identity chip
+  ]) {
+    assert.ok(child.includes(portable), `a child instance lost "${portable}"`);
+  }
+});
+
+test('the footer keeps its attribution half and loses only the commons half', () => {
+  const child = stripApexOnly(HTML, false);
+  const foot = child.match(/<div class="foot">([\s\S]*?)<\/div>/);
+  assert.ok(foot, 'the footer survives on a child instance');
+  assert.doesNotMatch(foot[1], /non-profit/);
+  assert.match(foot[1], /Built by agents/);
+});
+
+// ── the server-stamped head ────────────────────────────────────────────────
+
+const BRAND = {
+  identity: { productName: 'Spike Harbor', worldName: 'Spike Harbor' },
+  copy: { tagline: 'A different beat entirely.' },
+};
+
+test('every head tag a crawler reads is stamped, and no token survives', () => {
+  const out = applyBrandTokens(HTML, BRAND, 'https://spike-harbor.example', 'https://builders.spike-harbor.example');
+  assert.doesNotMatch(out, /\{\{[a-zA-Z]+\}\}/, 'an unstamped {{token}} would render literally');
+  assert.match(out, /<title>Spike Harbor — A different beat entirely\.<\/title>/);
+  assert.match(out, /<link rel="canonical" href="https:\/\/spike-harbor\.example\/">/);
+  for (const prop of ['og:type', 'og:site_name', 'og:url', 'og:title', 'og:description', 'og:image']) {
+    assert.match(out, new RegExp(`property="${prop}"`), `missing ${prop}`);
+  }
+  for (const name of ['twitter:card', 'twitter:title', 'twitter:description', 'twitter:image']) {
+    assert.match(out, new RegExp(`name="${name}"`), `missing ${name}`);
+  }
+  // the head must not advertise the authoring instance to a child
+  assert.doesNotMatch(out.split('</head>')[0], /cloudbongos\.com/);
+});
+
+test('every cross-host link is stamped to THIS instance, never the platform', () => {
+  const out = applyBrandTokens(HTML, BRAND, 'https://spike-harbor.example', 'https://builders.spike-harbor.example');
+  const halls = [...out.matchAll(/data-link-hall href="([^"]*)"/g)].map((m) => m[1]);
+  assert.ok(halls.length >= 2, 'the header door and the builders door both point at the hall');
+  for (const href of halls) assert.equal(href, 'https://builders.spike-harbor.example');
+  // C6: this is the bug the stamping fixes — clientBranding() omits domains, so a
+  // client fill can never re-point these and every child sent visitors to the platform.
+  assert.doesNotMatch(out, /builders\.cloudbongos\.com/);
+});
+
+test('a pack with no hall of its own falls back to its own apex, not the platform', () => {
+  const out = applyBrandTokens(HTML, BRAND, 'https://spike-harbor.example', '');
+  assert.match(out, /data-link-hall href="https:\/\/spike-harbor\.example"/);
+});
+
+test('the source link is stamped from the pack repo, never a baked owner/name', () => {
+  // the authorship audit fails a hardcoded owner/name, and a baked one would
+  // point every instance at whoever authored this file
+  assert.doesNotMatch(HTML, /github\.com\/[a-z0-9-]+\/[a-z0-9-]+/i, 'no baked repo path');
+  const out = applyBrandTokens(HTML, BRAND, 'https://o.example', '', 'https://github.com/acme/harbor');
+  assert.match(out, /href="https:\/\/github\.com\/acme\/harbor"/);
+});
+
+test('an unstamped link is removed, not left dangling', () => {
+  const out = applyBrandTokens(HTML, BRAND, 'https://o.example', '', '');
+  assert.match(out, /href=""/, 'the token resolves empty when the pack names no repo');
+  assert.match(CODE, /a\[href=""\]/, 'and the page drops those links');
+  assert.match(CODE, /\.remove\(\)/);
+});
+
+// ── the branding cascade + portability ─────────────────────────────────────
+
+test('the page declares no :root — a page-local one defeats re-branding (C1)', () => {
+  const styles = [...HTML.matchAll(/<style>([\s\S]*?)<\/style>/g)].map((m) => m[1]).join('\n');
+  assert.ok(styles.length > 0, 'the page ships a local stylesheet');
+  // :root[data-mode="dark"] .bongos{…} is a DESCENDANT rule, not a :root declaration
+  // block — it scopes component tokens and cannot outrank the pack's own :root.
+  assert.doesNotMatch(styles, /:root\s*\{/, 'a bare :root{ } block outranks the injected pack');
+  assert.doesNotMatch(styles, /:root\[data-mode="dark"\]\s*\{/, 'same, for the dark tier');
+});
+
+test('every dark-mode rule is written twice — the block and its media twin (C2)', () => {
+  const styles = [...HTML.matchAll(/<style>([\s\S]*?)<\/style>/g)].map((m) => m[1]).join('\n');
+  const explicit = (styles.match(/:root\[data-mode="dark"\]/g) || []).length;
+  const media = (styles.match(/:root:not\(\[data-mode="light"\]\)/g) || []).length;
+  assert.equal(explicit, media, 'a dark rule with no prefers-color-scheme twin only half-works');
+  assert.ok(explicit >= 2, 'the drum skin and the hero glow both flip');
+});
+
+test('the drum head never inherits a card colour — it would turn black in dark', () => {
+  const styles = [...HTML.matchAll(/<style>([\s\S]*?)<\/style>/g)].map((m) => m[1]).join('\n');
+  const skin = styles.match(/\.bongos\{[^}]*\}/);
+  assert.ok(skin, '.bongos carries its own skin tokens');
+  assert.match(skin[0], /--skin-hi:/);
+  assert.doesNotMatch(styles, /--skin-[a-z]+:\s*var\(--bg-card\)/);
+});
+
+test('the page ships the .sky layer the pack backdrop would otherwise show through (C3)', () => {
+  assert.match(HTML, /<div class="sky"/);
+});
+
+// ── the static pose under reduced motion (direction §7) ───────────────────
+// The hero animates by default, so this is an accessibility constraint that
+// fails SILENTLY — nothing about the page looks wrong to a developer who does
+// not have the OS setting on. It holds via a cross-FILE dependency (cosmos.css
+// carries one global motion kill switch rather than every page repeating it),
+// which is the right shape but an invisible one, so both halves are locked here.
+// Verified in a real browser with reducedMotion emulation: every hero element
+// computes animation-name:none, and the ripples additionally display:none.
+
+const COSMOS = fs.readFileSync(path.join(ROOT, 'public-landing', 'assets', 'cosmos.css'), 'utf8');
+const PAGE_STYLES = [...HTML.matchAll(/<style>([\s\S]*?)<\/style>/g)].map((m) => m[1]).join('\n');
+// declarations only — the comments quote the very shapes these tests rule out
+const PAGE_CSS = PAGE_STYLES.replace(/\/\*[\s\S]*?\*\//g, '');
+
+test('cosmos.css still carries the global motion kill switch the hero relies on', () => {
+  const block = COSMOS.match(/@media\s*\(prefers-reduced-motion:\s*reduce\)\s*\{([\s\S]*?)\n\}/);
+  assert.ok(block, 'cosmos.css must keep a prefers-reduced-motion block');
+  assert.match(block[1], /\*[^{]*\{[^}]*animation:\s*none\s*!important/,
+    'the universal selector + !important is what stops the hero; without it the drums keep beating');
+});
+
+test('nothing on the page marks an animation !important and escapes that switch', () => {
+  // the ONE way this page could break the constraint on its own
+  assert.doesNotMatch(PAGE_CSS, /animation[^;:]*:[^;]*!important/,
+    'an !important animation here would outrank the global kill switch');
+});
+
+test('the hero animations are plain declarations, so the switch reaches them', () => {
+  // every animated part of the drum kit, as the mock defines the beat
+  for (const cls of ['drumBig', 'drumSml', 'headBig', 'headSml', 'glow', 'bshadow', 'ring']) {
+    assert.match(PAGE_STYLES, new RegExp(`\\.bongos\\s+\\.${cls}\\s*\\{[^}]*animation:`),
+      `.${cls} should be animated in the default (non-reduced) case`);
+  }
+});
+
+test('the ripples are hidden under reduced motion — they rest at full stroke', () => {
+  const reduced = PAGE_STYLES.match(/@media\s*\(prefers-reduced-motion:reduce\)\{([^}]*\})*/);
+  assert.ok(reduced, 'the page carries its own reduced-motion block');
+  assert.match(reduced[0], /\.bongos\s+\.ring\s*\{\s*display:none/);
+});
+
+test('the self-typing eyebrow degrades to real text, not an empty span', () => {
+  // the script only decorates; markup must already carry the word
+  assert.match(HTML, /<span class="typed" id="typed">bongos<\/span>/);
+  assert.match(CODE, /matchMedia\('\(prefers-reduced-motion: reduce\)'\)/);
+  assert.match(CODE, /if \(!reduce\) \{/, 'the typing loop is skipped under reduced motion');
+});
+
+test('nothing about the platform is hardcoded — the file is portable (C5)', () => {
+  // the source repo link is a real, deliberate attribution; every OTHER mention
+  // of an origin must be a token.
+  const withoutSource = HTML.replace(/https:\/\/github\.com\/[^"]*/g, '');
+  assert.doesNotMatch(withoutSource, /cloudbongos\.com/);
+});
+
+test('the page reads without JavaScript: the spine is markup, not script-built', () => {
+  const body = HTML.split('<body>')[1].split('<script>')[0];
+  for (const copy of [
+    'Building software is laying',
+    'Every change is a claimed task',
+    'A rank ladder the server enforces',
+    'Nothing ships ungraded',
+    'How a change reaches your project',
+    'Start a project',
+    'Enter the Hall',
+  ]) {
+    assert.ok(body.includes(copy), `"${copy}" is only reachable with scripting on`);
+  }
+});
+
+test('the proof band ships hidden so a failed or empty feed leaves no orphan heading', () => {
+  assert.match(HTML, /<section class="band" id="proof" hidden>/);
+  // and it is only ever revealed on a non-empty 200
+  assert.match(HTML, /if \(!list\.length\) return;/);
+  assert.match(HTML, /band\.hidden = false;/);
+});
+
+// The page script minus its comments — these assertions are about what the code
+// DOES, and the comments deliberately quote the shapes being ruled out.
+const CODE = HTML.split('<script>').pop().replace(/\/\*[\s\S]*?\*\//g, '');
+
+test('the catalog claims no liveness the public feed cannot back', () => {
+  // listFeaturedProjects projects {origin, name, tagline, art_url} — no status,
+  // so a verification chip here would be a claim nothing checked.
+  assert.doesNotMatch(CODE, /chip (live|maybe|down)/);
+  assert.doesNotMatch(CODE, /ago/);
+});
+
+test('catalog values are never interpolated as HTML, and hrefs are scheme-checked', () => {
+  assert.doesNotMatch(CODE, /innerHTML/, 'the feed carries third-party strings');
+  assert.match(CODE, /u\.protocol === 'https:' \|\| u\.protocol === 'http:'/);
+});
+
+// ── the shared layer gained the primitives, and the page did not fork it ───
+
+test('the landing links cosmos.css and does not fork the design system', () => {
+  assert.match(HTML, /<link rel="stylesheet" href="assets\/cosmos\.css">/);
+});
+
+test('the five primitives graduated into cosmos.css, not the page (§6)', () => {
+  const css = fs.readFileSync(path.join(ROOT, 'public-landing', 'assets', 'cosmos.css'), 'utf8');
+  assert.match(css, /^\.wrap\{/m, 'the page container');
+  assert.match(css, /^h2\.sec-h\{/m, 'the type scale below h1');
+  assert.match(css, /--pad-xl:/, 'the spacing scale');
+  assert.match(css, /^\.grid\{/m, 'the grid primitive');
+  assert.match(css, /@media \(max-width:900px\)/, 'the mid breakpoint');
+  // and the page must not re-declare them locally
+  const styles = [...HTML.matchAll(/<style>([\s\S]*?)<\/style>/g)].map((m) => m[1]).join('\n');
+  assert.doesNotMatch(styles, /^\.wrap\{/m, '.wrap belongs to the shared layer');
+  assert.doesNotMatch(styles, /^\.grid\{/m, '.grid belongs to the shared layer');
+});
+
+// ── the assertion tests/platform_boot.mjs will make once the apex flips ────
+
+test('the page satisfies the parked platform_boot assertions', () => {
+  assert.match(HTML, /id="who"/);
+  assert.match(HTML, /Enter the Hall/);
+  // an ORG-level action that lives only on the gate — asserted absent there
+  assert.doesNotMatch(HTML, /Create a project/);
+});

package/tests/migrate_root_resolution.mjs

@@ -18,7 +18,7 @@
 import { strict as assert } from 'node:assert';
 import { execFileSync } from 'node:child_process';
 import {
-  mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync, realpathSync,
+  mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, symlinkSync, copyFileSync, realpathSync,
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -116,7 +116,15 @@ function makeCore({ spaced, files = ['001_a.sql', '002_b.sql', '006_pms_v2.sql',
   mkdirSync(path.join(dir, 'scripts'));
   mkdirSync(path.join(dir, 'migrations'));
   mkdirSync(path.join(dir, 'src'));
-  symlinkSync(MIGRATE, path.join(dir, 'scripts', 'migrate.sh'));
+  // Symlink so the fixture can never drift from the real script. Windows refuses symlinks without
+  // elevation (EPERM), so fall back to a COPY taken fresh from MIGRATE on each run — equally
+  // drift-proof, and it is what lets these cases run on a Windows checkout at all.
+  try {
+    symlinkSync(MIGRATE, path.join(dir, 'scripts', 'migrate.sh'));
+  } catch (e) {
+    if (e.code !== 'EPERM' && e.code !== 'EACCES') throw e;
+    copyFileSync(MIGRATE, path.join(dir, 'scripts', 'migrate.sh'));
+  }
   // Pin both roots to the fixture explicitly, so the test does not lean on migrate.sh's
   // node-unavailable fallback to decide what CORE_ROOT is.
   writeFileSync(path.join(dir, 'src', 'instance-config.js'), [
@@ -216,5 +224,95 @@ t('the pre-fix unquoted loop now fails loudly instead of silently skipping', ()
   assert.equal(r.applied.length, 0, 'the unquoted loop applies nothing (that was the bug)');
 });
 
+// ==========================================================================
+// WHICH DATABASE does migrate target? (task 1002755)
+//
+// scripts/migrate.sh:52 used to read `DB="${PGDATABASE:-amazonprimea}"` — one host instance's
+// database name, baked into a script the core ships to EVERY instance. With no PGDATABASE in the
+// environment, a co-hosted box silently aimed at a stranger's database and everywhere else died
+// with a confusing "database ... does not exist" — after the caller had already moved its version
+// pin. ADR 0149:17 had already named the divergence: the server pool resolves from the branding
+// pack while migrate.sh defaulted to a literal, and "they only agree if PGDATABASE is set for both."
+//
+// These drive the `--print-db` seam, which resolves the name and exits before any psql — the
+// --print-roots pattern. The fixture carries a REAL config/branding.json so the assertions
+// exercise the actual resolver (pool.instanceDbName) rather than a stub of it.
+
+// A core fixture that is ALSO an instance: adds the branding pack instanceDbName() reads.
+// db.database === null models the neutral starter — an instance that has not named its database.
+function makeInstance({ database } = {}) {
+  const dir = makeCore({ spaced: false });
+  mkdirSync(path.join(dir, 'config'), { recursive: true });
+  writeFileSync(
+    path.join(dir, 'config', 'branding.json'),
+    `${JSON.stringify({ db: { database: database ?? null } }, null, 2)}\n`,
+  );
+  // migrate.sh resolves the name through <CORE_ROOT>/src/bongos/pool. Re-export the REAL module
+  // so these cases exercise the actual resolver rather than a restatement of it — a stub here
+  // would pass happily while pool.js drifted. The real file resolves its own `pg` from the repo's
+  // node_modules (module resolution walks up from ITS path, not the fixture's), and its
+  // resolveInstanceRoot() falls back to cwd — which migrate.sh has already set to this fixture.
+  mkdirSync(path.join(dir, 'src', 'bongos'), { recursive: true });
+  writeFileSync(
+    path.join(dir, 'src', 'bongos', 'pool.js'),
+    `module.exports = require(${JSON.stringify(path.join(REPO_ROOT, 'src', 'bongos', 'pool.js'))});\n`,
+  );
+  return dir;
+}
+
+function printDb(coreDir, extraEnv = {}) {
+  const env = { ...process.env, ...extraEnv };
+  for (const k of Object.keys(env)) if (/_INSTANCE_ROOT$/.test(k)) delete env[k];
+  if (!('PGDATABASE' in extraEnv)) delete env.PGDATABASE;
+  try {
+    const stdout = execFileSync('bash', [path.join(coreDir, 'scripts', 'migrate.sh'), '--print-db'],
+      { cwd: coreDir, env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return { status: 0, stdout: stdout.trim(), stderr: '' };
+  } catch (e) {
+    return { status: e.status ?? 1, stdout: String(e.stdout || '').trim(), stderr: String(e.stderr || '') };
+  }
+}
+
+t('--print-db reports the database named by the instance\'s own branding pack', () => {
+  const r = printDb(makeInstance({ database: 'acme_instance_db' }));
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.stdout, 'acme_instance_db');
+});
+
+t('an explicit PGDATABASE wins over the pack — same precedence as pool.js', () => {
+  const r = printDb(makeInstance({ database: 'from_the_pack' }), { PGDATABASE: 'from_the_env' });
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.stdout, 'from_the_env');
+});
+
+t('an instance that names no database is REFUSED, never defaulted', () => {
+  const r = printDb(makeInstance({ database: null }));
+  assert.equal(r.status, 2, 'must exit 2 — the seam refuses rather than printing an empty name');
+  assert.doesNotMatch(r.stdout, /\S/, 'nothing is printed as the database name');
+  assert.match(r.stderr, /cannot determine which database/i);
+  assert.match(r.stderr, /Refusing to guess/i);
+  // the regression itself: it must not reach for another instance's database
+  assert.doesNotMatch(`${r.stdout}${r.stderr}`, /amazonprimea/i);
+});
+
+t('--print-migrations stays DB-free — a dry run must not require a database name', () => {
+  // the seam walks the real loop and touches no psql, so an instance with no db.database
+  // must still be able to list what would be applied
+  const core = makeInstance({ database: null });
+  const r = printMigrations(core);
+  assert.equal(r.status, 0, `a dry run must not need a database: ${r.stderr}`);
+  assert.equal(r.listed, 4);
+});
+
+t('migrate.sh hardcodes no instance database name', () => {
+  // the static lock on the original defect — a literal default reintroduced anywhere in the
+  // script points every other instance at a database that is not theirs
+  const src = readFileSync(MIGRATE, 'utf8');
+  const code = src.split(/\r?\n/).filter((l) => !/^\s*#/.test(l)).join('\n');
+  assert.doesNotMatch(code, /PGDATABASE:-\s*[A-Za-z]/,
+    'PGDATABASE must have no literal fallback — resolve from the branding pack instead');
+  assert.doesNotMatch(code, /amazonprimea/i, 'no instance database name in executable lines');
+});
+
 console.log(`\nmigrate_root_resolution: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/upgrade.mjs

@@ -1033,6 +1033,64 @@ t('runUpgrade: a REFUSED bump still reports the non-blocking module findings', a
   assert.match(text, /author unreachable/);
 });
 
+// ── which database will migrate target? (task 1002755) ────────────────────
+// The pre-flight probe is only meaningful if it tests the SAME database migrate will use. It used
+// to be handed process.env.PGDATABASE — undefined on a normal box — so psql fell through to a
+// database named after the OS user, failed for an unrelated reason, and soft-skipped; migrate then
+// picked its own name and died on a database that did not exist, AFTER the pin had moved.
+// The three-way result is the point: "names no database" and "resolver could not run" are
+// different problems and only the first may block a bump.
+
+t('resolveInstanceDb: an explicit PGDATABASE wins without spawning anything', () => {
+  const prev = process.env.PGDATABASE;
+  process.env.PGDATABASE = 'from_the_env';
+  try {
+    let spawned = false;
+    const r = u.resolveInstanceDb({ instanceDir: '/x' }, () => { spawned = true; return { status: 0, stdout: 'other' }; });
+    assert.deepEqual(r, { db: 'from_the_env', ran: true });
+    assert.equal(spawned, false, 'the env answer needs no child process');
+  } finally {
+    if (prev === undefined) delete process.env.PGDATABASE; else process.env.PGDATABASE = prev;
+  }
+});
+
+t('resolveInstanceDb: reports the name the core resolver printed', () => {
+  const prev = process.env.PGDATABASE;
+  delete process.env.PGDATABASE;
+  try {
+    const r = u.resolveInstanceDb({ instanceDir: '/x' }, () => ({ status: 0, stdout: 'acme_db\n' }));
+    assert.deepEqual(r, { db: 'acme_db', ran: true });
+  } finally { if (prev !== undefined) process.env.PGDATABASE = prev; }
+});
+
+t('resolveInstanceDb: ran-but-empty is FATAL, unrunnable is not', () => {
+  const prev = process.env.PGDATABASE;
+  delete process.env.PGDATABASE;
+  try {
+    // the instance genuinely names no database — knowable, and a bump must stop
+    assert.deepEqual(u.resolveInstanceDb({ instanceDir: '/x' }, () => ({ status: 0, stdout: '' })),
+      { db: null, ran: true });
+    // the resolver could not run — a DIFFERENT problem; must not be reported as "no database"
+    assert.deepEqual(u.resolveInstanceDb({ instanceDir: '/x' }, () => ({ status: 1, stdout: '' })),
+      { db: null, ran: false });
+    assert.deepEqual(u.resolveInstanceDb({ instanceDir: '/x' }, () => ({ error: new Error('ENOENT') })),
+      { db: null, ran: false });
+  } finally { if (prev !== undefined) process.env.PGDATABASE = prev; }
+});
+
+t('runUpgrade: refuses BEFORE the pin moves when the instance names no database', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'nodb-'));
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ dependencies: { '@bongos/core': '1.0.0' } }, null, 2));
+  const res = await u.runUpgrade({ to: '1.0.1', instance: dir, registry: true, force: true }, {
+    resolveInstanceDb: () => ({ db: null, ran: true }),
+    log: () => {},
+  });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /cannot determine which database/i);
+  // the pin must be untouched — that is the whole point of checking in pre-flight
+  assert.match(readFileSync(join(dir, 'package.json'), 'utf8'), /"@bongos\/core": "1\.0\.0"/);
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);