@bongos/core 1.19.91 → 1.19.92

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.91",
-  "core_contract": "1.19.91",
-  "source_commit": "157eeaee12b32ba8b9e23f62cf8476cc689e3e07",
+  "core_version": "1.19.92",
+  "core_contract": "1.19.92",
+  "source_commit": "3458c7057c3f26cc4304f95dc80ea9b5d6928d7c",
   "source_ref": "HEAD",
-  "built_at": "2026-08-13T16:52:49.920Z",
+  "built_at": "2026-08-13T17:47:34.165Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 298,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1559,
-  "tree_sha256": "a915672ef661add366011ce3030a79b196e486e67a437c4531c54de0b0bc3f87",
+  "tree_sha256": "475c679379a933a41a8c0c717e122af3bee2bfa56999f07d1e800961300c989e",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4112,12 +4112,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "9d710f118a6ae91aadb6111cde0ee0db020c018ce405b687236c84f75c8f69f1"
+      "sha256": "64b1a11a2b4a426879abf792df6861e28ffa1539b32f0527b9044baa2c1533ef"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1c7c2996a68dde5369dd07c387737614af9292244de4db2fa9fb0a70912e94aa"
+      "sha256": "fe0b5e65bcb64aff0ccc7609387e31656d5eaa7a48441a48a3b46862b9000323"
     },
     {
       "path": "public-docs/index.html",
@@ -5387,7 +5387,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "b539715de4893f8fa68c53c145ac2f54de39ccc5517f9e5ad17540c487dc24b0"
+      "sha256": "04ee659f61c79a1dbc2302f047d1d7870352d0892c2df974f6f000184794d3f8"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -5417,7 +5417,7 @@
     {
       "path": "scripts/migrate.sh",
       "mode": "0000644",
-      "sha256": "1c0ffd6822949c0aeb0bd89f48e12c2923c6d623228619729e9812056351fe9d"
+      "sha256": "0768bf9c9d6368ae673e1e5ac161cfe9bae4d113129f11f8b89afeeef1f9dc1b"
     },
     {
       "path": "scripts/migrate_cost_ledger.sh",
@@ -5752,7 +5752,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "d1f73a5d0f57613d96dd88738b593dd343e8330bc5452d414fd8752aa78da7f0"
+      "sha256": "e334fc7dbd4247d7f9362c0304fa635f5470b058ebaf6d08e70a9276846531e7"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -7007,7 +7007,7 @@
     {
       "path": "tests/migrate_root_resolution.mjs",
       "mode": "0000644",
-      "sha256": "eec69562f86d218a0f22411bbf6707d864e42e5f0b3f841692ca938d775a45ad"
+      "sha256": "e5cfa24bb69d6fade0f2f8bffd668bbda9490aca335d301abcf6f79154b60690"
     },
     {
       "path": "tests/migration_allocation.mjs",
@@ -7762,7 +7762,7 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "60e55591174f59238486d318fb92dc8fd8251eb73435d690e38ea83a2a5f235e"
+      "sha256": "a565b3a5e93a41feccaa8b616272390ea27cf2d50950a96f04856d18caa67744"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.91",
+  "version": "1.19.92",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.91",
+      "version": "1.19.92",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.91",
+  "version": "1.19.92",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/upgrade.js

@@ -324,6 +324,42 @@ function runMigrate(instanceDir, run = spawnSync) {
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
+// WHICH database will migrate target? (task 1002755)
+//
+// The pre-flight probe below is only meaningful if it tests the SAME database the migration
+// will later 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 with "psql failed for another reason". migrate then picked its own name and
+// hit a database that did not exist. Two soft failures composing into a hard one, discovered
+// only AFTER the pin had moved.
+//
+// So resolve it here, up front, by asking the core's OWN resolver in a child pointed at this
+// instance — the same precedence migrate.sh uses (PGDATABASE wins, else the instance's branding
+// pack) and the same function, so the probe and the migration cannot disagree. Spawned rather
+// than required because requiring pool.js constructs a pg Pool in this process.
+// Returns { db, ran }:
+//   { db: 'name', ran: true }  — resolved
+//   { db: null,  ran: true  }  — the resolver RAN and this instance names no database. Fatal:
+//                                migrate cannot proceed and we know it before the pin moves.
+//   { db: null,  ran: false }  — the resolver could not run at all (no node_modules yet, a
+//                                stubbed spawn in tests). NOT fatal: that is a different problem
+//                                from "no database configured", and guessing which one it is would
+//                                block bumps for the wrong reason. migrate.sh makes the same
+//                                distinction and still fails loudly later, so the net holds.
+function resolveInstanceDb({ instanceDir }, run = spawnSync) {
+  if (process.env.PGDATABASE) return { db: process.env.PGDATABASE, ran: true };
+  const poolPath = path.join(instanceDir, 'node_modules', CORE_PKG, 'src', 'bongos', 'pool');
+  // the module path rides as argv, never interpolated into JS source — a Windows-shaped path's
+  // backslashes are escape sequences inside a string literal
+  const r = run(process.execPath, ['-e', "process.stdout.write(require(process.argv[1]).instanceDbName() || '')", poolPath], {
+    cwd: instanceDir,
+    encoding: 'utf8',
+    env: { ...process.env, CLOUDBONGOS_INSTANCE_ROOT: instanceDir },
+  });
+  if (!r || r.error || r.status !== 0 || typeof r.stdout !== 'string') return { db: null, ran: false };
+  return { db: String(r.stdout).trim() || null, ran: true };
+}
+
 // Regenerate the per-instance API artifacts (OpenAPI spec + api-reference + typed
 // client) from the NEW core's routes — the claude-materialize sibling (task 2051).
 // WHY: the routes + generators ship WITH core, and the generated spec/docs/client also
@@ -748,10 +784,17 @@ async function runUpgrade(opts, deps = {}) {
   // mistake, and finding it at migrate means unwinding a pin that never should have
   // been written (task 1002712).
   if (!opts.skipMigrate) {
-    const dbId = (deps.preflightDbIdentity || preflightDbIdentity)({ instanceDir, db: process.env.PGDATABASE }, run);
+    const { db, ran } = (deps.resolveInstanceDb || resolveInstanceDb)({ instanceDir }, run);
+    if (ran && !db) {
+      return { ok: false, error: 'cannot determine which database to migrate.\n'
+        + '    Set PGDATABASE, or give this instance a db.database in config/branding.json.\n'
+        + '    Checked BEFORE the pin moves: migrate runs after the install, so a name that\n'
+        + '    cannot be resolved there costs a full rollback to discover (task 1002755).' };
+    }
+    const dbId = (deps.preflightDbIdentity || preflightDbIdentity)({ instanceDir, db }, run);
     if (!dbId.ok) return { ok: false, error: dbId.reason };
-    if (dbId.skipped) log(`  • db identity pre-check: ${dbId.skipped}`);
-    else log('  ✓ pre-flight: database reachable as the current user');
+    if (dbId.skipped) log(`  • db identity pre-check${db ? ` (${db})` : ''}: ${dbId.skipped}`);
+    else log(`  ✓ pre-flight: database${db ? ` "${db}"` : ''} reachable as the current user`);
   }
 
   // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
@@ -1005,7 +1048,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
+  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity, resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth,
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification
   CORE_PKG, ARTIFACT,
 };

package/scripts/migrate.sh

@@ -32,7 +32,13 @@ INVOKE_CWD="${INIT_CWD:-$PWD}"
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 DEFAULT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 CORE_ROOT="$(cd "$DEFAULT_ROOT" && node -e "process.stdout.write(require('./src/instance-config').resolveCoreRoot())" 2>/dev/null || echo "$DEFAULT_ROOT")"
-INSTANCE_ROOT="$(cd "$INVOKE_CWD" && node -e "process.stdout.write(require('$DEFAULT_ROOT/src/instance-config').resolveInstanceRootExplicit() || '')" 2>/dev/null || true)"
+# The module path rides in as argv rather than being interpolated into the JS source: a
+# Windows-shaped DEFAULT_ROOT contains backslashes, which are ESCAPE SEQUENCES inside a JS
+# string literal ("\U", "\r", "\D"), so interpolating corrupts the path, the require throws,
+# and this silently falls back to DEFAULT_ROOT — precisely the F6 shape described above, just
+# triggered by the path separator instead of the cwd. Fixed alongside task 1002755, which hit
+# the identical bug one resolution further down.
+INSTANCE_ROOT="$(cd "$INVOKE_CWD" && node -e "process.stdout.write(require(process.argv[1]).resolveInstanceRootExplicit() || '')" "$DEFAULT_ROOT/src/instance-config" 2>/dev/null || true)"
 INSTANCE_ROOT="${INSTANCE_ROOT:-$DEFAULT_ROOT}"
 # Run from the instance root so instance-relative paths resolve (the post-deploy art check below)
 # AND so the enabledModules() read finds the instance's config/modules.json (resolveInstanceRoot
@@ -49,17 +55,68 @@ if [ "${1:-}" = "--print-roots" ]; then
   exit 0
 fi
 
-DB="${PGDATABASE:-amazonprimea}"
-
 # Test/ops seam (added with the 1.18.19 space-in-path fix): --print-migrations walks the REAL core-migration loop but reports
 # each path instead of applying it, and touches NO DB. tests/migrate_root_resolution.mjs uses it to
 # assert that a checkout whose path contains a space still yields whole, readable paths. Reporting
 # through the real loop (rather than a copy of it in the test) is the point: if the loop ever reverts
 # to an unquoted `for f in $MIGRATIONS`, this seam fragments the paths and the test fails. Also handy
 # in the field — `npm run migrate -- --print-migrations` shows exactly what migrate would apply.
+#
+# Resolved BEFORE the database name below, because a dry run touches no DB (every psql call is
+# guarded by DRY_RUN) and so must not require one.
 DRY_RUN=0
 if [ "${1:-}" = "--print-migrations" ]; then DRY_RUN=1; fi
 
+# --- Which database? (task 1002755) ---------------------------------------
+# SAME precedence as src/bongos/pool.js: an explicit PGDATABASE wins, else the instance's own
+# branding pack names it (config/branding.json db.database, else the neutral starter). Resolved by
+# CALLING pool.instanceDbName() rather than re-reading the config here, so the migrator and the
+# running server can never disagree about which database this instance is.
+#
+# There is deliberately NO literal fallback. This script ships inside the core to EVERY instance,
+# so a baked-in default is one host's database name pointed at everyone else's box: on a co-hosted
+# machine it silently targets a stranger's data, and everywhere else it dies with a confusing
+# "database ... does not exist" long after the caller has moved its version pin. pool.js already
+# made exactly this call for the server ("NOT hard-defaulting to a host's DB name", pool.js:10-16);
+# this is the migrator catching up, not a new policy.
+# The module path rides in as argv, NOT interpolated into the JS source: a Windows-shaped
+# CORE_ROOT contains backslashes, and inside a JS string literal those are escape sequences
+# ("\U", "\r"), so interpolating silently corrupts the path and this resolution degrades to
+# empty. argv values are never parsed as JS.
+DB="${PGDATABASE:-}"
+DB_RESOLVER_ERR=""
+if [ -z "$DB" ]; then
+  # stderr is CAPTURED, not discarded: "the pack names no database" and "the resolver could not
+  # run at all" are different problems with different fixes, and collapsing both into an empty
+  # string sends the operator to edit a config file when the real answer is `npm install`.
+  # (pool.js requires pg, so an instance with no node_modules fails here rather than resolving.)
+  if DB_RESOLVED="$(node -e "process.stdout.write(require(process.argv[1]).instanceDbName() || '')" "$CORE_ROOT/src/bongos/pool" 2>&1)"; then
+    DB="$DB_RESOLVED"
+  else
+    DB_RESOLVER_ERR="$DB_RESOLVED"
+  fi
+fi
+if [ -z "$DB" ] && [ "$DRY_RUN" = 0 ]; then
+  echo "migrate: cannot determine which database to migrate." >&2
+  if [ -n "$DB_RESOLVER_ERR" ]; then
+    echo "  the db-name resolver did not run: $(printf '%s' "$DB_RESOLVER_ERR" | head -n 1)" >&2
+    echo "  if the core's dependencies are not installed yet, run: npm install" >&2
+  else
+    echo "  Set PGDATABASE, or give this instance a db.database in config/branding.json." >&2
+  fi
+  echo "  Refusing to guess: a baked-in default would target another instance's database." >&2
+  exit 2
+fi
+
+# Test/ops seam: --print-db reports the database this run WOULD migrate, and exits before any DB
+# work. `bongos upgrade` calls it to learn the name up front, so its pre-flight can prove the DB is
+# reachable BEFORE the version pin moves — otherwise an unresolvable name is only discovered at
+# migrate time, and the pin has to be unwound (task 1002755).
+if [ "${1:-}" = "--print-db" ]; then
+  printf '%s\n' "$DB"
+  exit 0
+fi
+
 # --- Instance-seed policy (task 1704 / ADR 0105) --------------------------
 # OTB/product scope-truth (versions, goals, done_when_criteria) lives in seed
 # migrations under migrations/instance/ (plus a few guarded blocks embedded in the

package/src/module-api.js

@@ -609,8 +609,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.89 with no explicit bump. run 31717551308. (task 1002620)
 //   1.19.91 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.90 with no explicit bump. run 31722841411. (task 1002620)
+//   1.19.92 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.91 with no explicit bump. run 31727411036. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.91'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.92'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

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