@bongos/core 1.17.0

package/tests/turn_in_place.mjs

@@ -0,0 +1,280 @@
+// tests/turn_in_place.mjs
+//
+// Turn-in-place (#1057): quick-tap a direction to face it without stepping;
+// hold past the threshold to walk as before. Exercises the pure movement
+// helpers (Phaser-free, DB-free) that drive Player.update:
+//   - decideMove(dir, facing, heldMs, threshold) — the tap-vs-hold rule.
+//   - readDirectionFromInput(moveKeys) — WASD + arrow key resolution.
+// Plus a frame-by-frame simulation proving a real tap never steps and a
+// real hold does.
+//
+// Run:  node tests/turn_in_place.mjs
+
+import { strict as assert } from 'node:assert';
+import {
+  decideMove,
+  readDirectionFromInput,
+  TURN_TAP_MS,
+  DIRS,
+} from '../modules/game/public/game/player/movement.js';
+
+let passed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (e) {
+    console.error(`  FAIL ${name}: ${e.message}`);
+    process.exitCode = 1;
+  }
+}
+
+// A Phaser Key stand-in — readDirectionFromInput only reads these two props.
+const key = (isDown, timeDown = 0) => ({ isDown, timeDown });
+const NONE = key(false);
+
+// ---------- decideMove: the tap-vs-hold rule -----------------------------
+
+test('quick tap of a NEW direction turns, never steps (even if heldMs is large)', () => {
+  // A fresh press in a new direction always pivots first and never steps the
+  // same frame — so a quick tap of a new direction can only ever face it.
+  assert.deepEqual(decideMove('left', 'down', 5, TURN_TAP_MS), { turn: true, step: false });
+  assert.deepEqual(decideMove('up', 'down', 9999, TURN_TAP_MS), { turn: true, step: false });
+});
+
+test('already facing + held below threshold = no-op (a quick tap is just a look)', () => {
+  assert.deepEqual(decideMove('down', 'down', 0, TURN_TAP_MS), { turn: false, step: false });
+  assert.deepEqual(decideMove('down', 'down', TURN_TAP_MS - 1, TURN_TAP_MS), { turn: false, step: false });
+});
+
+test('already facing + held at/over threshold = step (walk)', () => {
+  assert.deepEqual(decideMove('down', 'down', TURN_TAP_MS, TURN_TAP_MS), { turn: false, step: true });
+  assert.deepEqual(decideMove('right', 'right', TURN_TAP_MS + 500, TURN_TAP_MS), { turn: false, step: true });
+});
+
+test('no direction held = nothing', () => {
+  assert.deepEqual(decideMove(null, 'down', 9999, TURN_TAP_MS), { turn: false, step: false });
+});
+
+test('threshold sits in the task-specified 120-150ms band', () => {
+  assert.ok(TURN_TAP_MS >= 120 && TURN_TAP_MS <= 150, `TURN_TAP_MS=${TURN_TAP_MS}`);
+});
+
+// ---------- readDirectionFromInput: WASD + arrow bindings ----------------
+
+const dirKeys = (over) => ({
+  up: [NONE, NONE], down: [NONE, NONE], left: [NONE, NONE], right: [NONE, NONE], ...over,
+});
+
+test('nothing held resolves to null', () => {
+  assert.equal(readDirectionFromInput(dirKeys({})), null);
+});
+
+test('WASD drives direction (W = up)', () => {
+  const sel = readDirectionFromInput(dirKeys({ up: [key(true, 100), NONE] }));
+  assert.equal(sel.dir, 'up');
+  assert.equal(sel.t, 100);
+});
+
+test('arrow keys drive the same direction (#1057 added arrow bindings)', () => {
+  // second slot in each direction array is the cursor (arrow) key
+  const sel = readDirectionFromInput(dirKeys({ right: [NONE, key(true, 250)] }));
+  assert.equal(sel.dir, 'right');
+  assert.equal(sel.t, 250);
+});
+
+test('WASD + arrow for one direction use the most-recent press time', () => {
+  const sel = readDirectionFromInput(dirKeys({ down: [key(true, 100), key(true, 400)] }));
+  assert.equal(sel.dir, 'down');
+  assert.equal(sel.t, 400);
+});
+
+test('most-recently-pressed direction wins', () => {
+  const sel = readDirectionFromInput(dirKeys({
+    up:   [key(true, 100), NONE],
+    left: [key(true, 200), NONE],
+  }));
+  assert.equal(sel.dir, 'left');
+});
+
+test('opposing keys cancel (W+S held = no direction)', () => {
+  assert.equal(readDirectionFromInput(dirKeys({
+    up:   [key(true, 100), NONE],
+    down: [key(true, 110), NONE],
+  })), null);
+});
+
+test('opposing pair cancels but a third direction still resolves', () => {
+  const sel = readDirectionFromInput(dirKeys({
+    left:  [key(true, 100), NONE],
+    right: [key(true, 110), NONE],
+    up:    [key(true, 90), NONE],
+  }));
+  assert.equal(sel.dir, 'up');
+});
+
+test('equal timeDown breaks ties deterministically (up before left)', () => {
+  const sel = readDirectionFromInput(dirKeys({
+    up:   [key(true, 100), NONE],
+    left: [key(true, 100), NONE],
+  }));
+  assert.equal(sel.dir, 'up');
+});
+
+// ---------- frame-by-frame: a real tap vs a real hold --------------------
+
+// Drive the same decision loop Player.update runs, over a sequence of
+// frames. Each frame: resolve the held direction, compute heldMs = now - t,
+// decide, and apply (turn updates facing; step counts a tile move).
+function simulate(frames, startFacing = 'down') {
+  let facing = startFacing;
+  let steps = 0;
+  let turns = 0;
+  for (const f of frames) {
+    const sel = readDirectionFromInput(f.keys);
+    if (!sel) continue;
+    const { turn, step } = decideMove(sel.dir, facing, f.now - sel.t, TURN_TAP_MS);
+    if (turn) { facing = sel.dir; turns++; continue; }
+    if (step) { steps++; }
+  }
+  return { facing, steps, turns };
+}
+
+test('a quick tap of a new direction turns once and never steps', () => {
+  const pressedAt = 1000;
+  const held = (now) => dirKeys({ left: [key(true, pressedAt), NONE] });
+  // Press at 1000, sampled at 1000 and 1050, then released before 130ms.
+  const r = simulate([
+    { now: 1000, keys: held(1000) },
+    { now: 1050, keys: held(1050) },
+    { now: 1100, keys: dirKeys({}) }, // released (~100ms tap)
+  ]);
+  assert.equal(r.facing, 'left');
+  assert.equal(r.turns, 1);
+  assert.equal(r.steps, 0); // pure turn-in-place — no tile change
+});
+
+test('a quick tap while already facing that way is a no-op (no step)', () => {
+  const r = simulate([
+    { now: 1000, keys: dirKeys({ down: [key(true, 1000), NONE] }) },
+    { now: 1060, keys: dirKeys({ down: [key(true, 1060), NONE] }) },
+    { now: 1090, keys: dirKeys({}) }, // released (~90ms tap)
+  ], 'down');
+  assert.equal(r.facing, 'down');
+  assert.equal(r.turns, 0);
+  assert.equal(r.steps, 0);
+});
+
+test('holding a direction walks (turn then step past the threshold)', () => {
+  const pressedAt = 1000;
+  const r = simulate([
+    { now: 1000, keys: dirKeys({ left: [key(true, pressedAt), NONE] }) }, // turn
+    { now: 1050, keys: dirKeys({ left: [key(true, pressedAt), NONE] }) }, // still in tap window
+    { now: 1000 + TURN_TAP_MS + 10, keys: dirKeys({ left: [key(true, pressedAt), NONE] }) }, // step
+  ]);
+  assert.equal(r.facing, 'left');
+  assert.equal(r.turns, 1);
+  assert.equal(r.steps, 1);
+});
+
+test('holding the direction you already face walks after the threshold (no extra turn)', () => {
+  const pressedAt = 2000;
+  const r = simulate([
+    { now: 2000, keys: dirKeys({ up: [key(true, pressedAt), NONE] }) }, // within tap window: nothing
+    { now: 2000 + TURN_TAP_MS + 5, keys: dirKeys({ up: [key(true, pressedAt), NONE] }) }, // step
+  ], 'up');
+  assert.equal(r.turns, 0);
+  assert.equal(r.steps, 1);
+});
+
+// DIRS sanity — Player.update derives the target tile from these.
+test('DIRS deltas are the four cardinal unit steps', () => {
+  assert.deepEqual(DIRS.up, { dx: 0, dy: -1 });
+  assert.deepEqual(DIRS.down, { dx: 0, dy: 1 });
+  assert.deepEqual(DIRS.left, { dx: -1, dy: 0 });
+  assert.deepEqual(DIRS.right, { dx: 1, dy: 0 });
+});
+
+// ---------- integration: the real Player class with Phaser/DB mocks ------
+//
+// Player.js is Phaser-free at module load (it only touches the API at
+// runtime), so we can drive the real update() loop with light mocks and
+// assert the wiring: a pure turn sends 'turn' and changes NO position; a
+// held press sends 'move' and steps exactly one tile.
+
+const { Player } = await import('../modules/game/public/game/player/Player.js');
+
+function makePlayer() {
+  const sprite = {
+    x: 0, y: 0,
+    setOrigin() { return this; },
+    setDepth() { return this; },
+    setTexture() { return this; },
+    setFlipX() { return this; },
+    setPosition(x, y) { this.x = x; this.y = y; return this; },
+  };
+  const sent = [];
+  const scene = {
+    add: { image: () => sprite },
+    textures: { exists: () => false }, // canvas-fallback path in spriteTextureFor
+    isBlocked: () => false,
+    // Synchronous tween: fire onComplete immediately so the step settles
+    // within the same call (real Phaser tweens take STEP_MS).
+    tweens: { add: (cfg) => { if (cfg.onComplete) cfg.onComplete(); } },
+  };
+  const player = new Player(scene, 10, 10);
+  player.attachRoom({ send: (type, msg) => sent.push({ type, msg }) });
+  return { player, sent };
+}
+
+const keysFor = (dir, t) => dirKeys({ [dir]: [key(true, t), NONE] });
+
+test('integration: quick tap of a new direction → faces it, sends turn, NO position change', () => {
+  const { player, sent } = makePlayer();
+  assert.equal(player.facing, 'down');
+  player.update(keysFor('left', 1000), 1000); // press; dir != facing → turn
+  assert.equal(player.facing, 'left');
+  assert.equal(player.gridX, 10);
+  assert.equal(player.gridY, 10); // zero position change — the headline acceptance
+  assert.deepEqual(sent, [{ type: 'turn', msg: { dir: 'left' } }]);
+});
+
+test('integration: tap while already facing that way → no message, no move', () => {
+  const { player, sent } = makePlayer(); // starts facing down
+  player.update(keysFor('down', 2000), 2000 + 50); // held 50ms < threshold
+  assert.equal(player.gridX, 10);
+  assert.equal(player.gridY, 10);
+  assert.deepEqual(sent, []);
+});
+
+test('integration: holding past the threshold → sends move and steps one tile', () => {
+  const { player, sent } = makePlayer(); // facing down
+  // Already facing 'down'; hold past threshold → one step down (+1 y).
+  player.update(keysFor('down', 3000), 3000 + TURN_TAP_MS + 10);
+  assert.equal(player.gridY, 11);
+  assert.equal(player.gridX, 10);
+  assert.deepEqual(sent, [{ type: 'move', msg: { dir: 'down' } }]);
+});
+
+test('integration: turn frame never steps even when the key is already held long', () => {
+  const { player, sent } = makePlayer(); // facing down
+  // First time we see 'left' it differs from facing → must turn only, never
+  // step, regardless of how long the (newly-resolved) key reads as held.
+  player.update(keysFor('left', 100), 100 + 5000);
+  assert.equal(player.facing, 'left');
+  assert.equal(player.gridX, 10);
+  assert.equal(player.gridY, 10);
+  assert.deepEqual(sent, [{ type: 'turn', msg: { dir: 'left' } }]);
+});
+
+test('integration: blocked tile → faces direction but does not step', () => {
+  const { player, sent } = makePlayer();
+  player.scene.isBlocked = () => true;
+  player.facing = 'up'; // pretend already facing up
+  player.update(keysFor('up', 4000), 4000 + TURN_TAP_MS + 10); // would step, but blocked
+  assert.equal(player.gridY, 10); // unchanged
+  assert.deepEqual(sent, []); // beginWalk (which sends 'move') never reached
+});
+
+console.log(`\nturn_in_place: ${passed} passed`);

package/tests/upgrade.mjs

@@ -0,0 +1,357 @@
+// tests/upgrade.mjs
+//
+// task 1690 / ADR 0100 §2 + ADR 0103 §4 — the real `bongos upgrade` update-consumption channel.
+// Pins the behavior a two-repo consumer relies on for its first core bump:
+//   1. pure pin helpers — version parsing, read/write the `file:` dependency pin.
+//   2. vendorTarball — copies the .tgz (+ side-car manifest) into vendor/ under the canonical name.
+//   3. step shims — gitTreeClean / npmInstall / runMigrate / restartService issue the right argv.
+//   4. guards — missing --to, dirty tree, and already-on-target all refuse (fail-closed).
+//   5. dry-run — plans without mutating package.json or spawning npm.
+//   6. full happy-path — pre-flight → pin → install → migrate → materialize → restart → verify,
+//      with every side effect injected (DB-free: the ledger is skipped when no DATABASE_URL).
+//
+// Run:  node tests/upgrade.mjs
+
+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';
+
+const require = createRequire(import.meta.url);
+const u = require('../scripts/gds/upgrade.js');
+
+let passed = 0, failed = 0;
+const pending = [];
+function t(name, fn) {
+  pending.push(Promise.resolve().then(fn).then(
+    () => { passed++; console.log(`  PASS  ${name}`); },
+    (e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+  ));
+}
+
+function scratchConsumer({ pinned = '1.14.1', installed = '1.14.1' } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-upgrade-'));
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({
+    name: 'test-consumer', version: '0.1.0',
+    dependencies: { '@cloudbongos/core': `file:vendor/cloudbongos-core-${pinned}.tgz` },
+    scripts: { migrate: 'true', start: 'true' },
+  }, null, 2) + '\n');
+  if (installed) {
+    const cd = join(dir, 'node_modules', '@cloudbongos', 'core');
+    mkdirSync(cd, { recursive: true });
+    writeFileSync(join(cd, 'package.json'), JSON.stringify({ name: '@cloudbongos/core', version: installed }) + '\n');
+  }
+  return dir;
+}
+
+// A recording spawn shim. `git status` reports clean by default; `npm install` simulates the version
+// flip by rewriting the staged node_modules package.json to `installTo`.
+function fakeRun(calls, { dirty = '', installTo = null, dir = null } = {}) {
+  return (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: dirty };
+    if (cmd === 'npm' && args[0] === 'install' && installTo && dir) {
+      writeFileSync(join(dir, 'node_modules', '@cloudbongos', 'core', 'package.json'),
+        JSON.stringify({ name: '@cloudbongos/core', version: installTo }) + '\n');
+    }
+    return { status: 0 };
+  };
+}
+
+// ---- 1. pure pin helpers ----------------------------------------------------
+t('versionFromTgzPath: extracts the version from a vendored tarball path', () => {
+  assert.equal(u.versionFromTgzPath('file:vendor/cloudbongos-core-1.14.1.tgz'), '1.14.1');
+  assert.equal(u.versionFromTgzPath('vendor/cloudbongos-core-1.15.0.tgz'), '1.15.0');
+  assert.equal(u.versionFromTgzPath('^1.2.3'), null);
+});
+
+t('readPinnedCoreVersion / writePin: round-trip the file: dependency', () => {
+  const dir = scratchConsumer({ pinned: '1.14.1' });
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1');
+  const prev = u.writePin(dir, 'vendor/cloudbongos-core-1.15.0.tgz');
+  assert.equal(prev, 'file:vendor/cloudbongos-core-1.14.1.tgz');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.15.0');
+});
+
+t('readInstalledCoreVersion: reads node_modules/@cloudbongos/core', () => {
+  const dir = scratchConsumer({ installed: '1.14.1' });
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1');
+  assert.equal(u.readInstalledCoreVersion(mkdtempSync(join(tmpdir(), 'empty-'))), null);
+});
+
+// ---- 2. vendorTarball -------------------------------------------------------
+t('vendorTarball: copies the .tgz + side-car manifest under the canonical name', () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'cloudbongos-core-1.15.0.tgz'), 'TGZBYTES');
+  writeFileSync(join(src, 'cloudbongos-core-1.15.0.manifest.json'), '{"v":1}');
+  const dir = scratchConsumer();
+  const rel = u.vendorTarball({ instanceDir: dir, fromTgz: join(src, 'cloudbongos-core-1.15.0.tgz'), targetVersion: '1.15.0' });
+  assert.equal(rel, join('vendor', 'cloudbongos-core-1.15.0.tgz'));
+  assert.equal(readFileSync(join(dir, rel), 'utf8'), 'TGZBYTES');
+  assert.ok(existsSync(join(dir, 'vendor', 'cloudbongos-core-1.15.0.manifest.json')), 'manifest copied too');
+});
+
+// ---- 3. step shims issue the right argv ------------------------------------
+t('npmInstall / runMigrate / restartService: correct commands', () => {
+  const calls = [];
+  const run = fakeRun(calls);
+  u.npmInstall('/x', run);
+  u.runMigrate('/x', run);
+  u.restartService({ service: 'emersonian.service' }, run);
+  u.restartService({ restartCmd: 'kubectl rollout restart deploy/x' }, run);
+  assert.ok(calls.includes('npm install --no-audit --no-fund'));
+  assert.ok(calls.includes('npm run migrate'));
+  assert.ok(calls.includes('systemctl restart emersonian.service'));
+  assert.ok(calls.includes('kubectl rollout restart deploy/x'));
+});
+
+t('restartService: no service/cmd → skipped (no spawn)', () => {
+  const calls = [];
+  const res = u.restartService({}, fakeRun(calls));
+  assert.equal(res.skipped, true);
+  assert.equal(calls.length, 0);
+});
+
+// ---- 4. guards --------------------------------------------------------------
+t('guard: missing --to refuses', async () => {
+  const res = await u.runUpgrade({ instance: scratchConsumer() }, { log: () => {}, err: () => {} });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /--to/);
+});
+
+t('guard: dirty tree refuses (unless --force)', async () => {
+  const dir = scratchConsumer();
+  const res = await u.runUpgrade({ to: '1.15.0', instance: dir }, { log: () => {}, err: () => {}, run: fakeRun([], { dirty: ' M package.json' }) });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /not clean/);
+});
+
+t('guard: already on the target refuses (unless --force)', async () => {
+  const dir = scratchConsumer({ installed: '1.15.0' });
+  const res = await u.runUpgrade({ to: '1.15.0', instance: dir }, { log: () => {}, err: () => {}, run: fakeRun([], { dirty: '' }) });
+  assert.equal(res.ok, false);
+  assert.match(res.error, /already on 1\.15\.0/);
+});
+
+// ---- 5. dry-run mutates nothing --------------------------------------------
+t('dry-run: plans without rewriting package.json or spawning npm', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'cloudbongos-core-1.15.0.tgz'), 'X');
+  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, 'cloudbongos-core-1.15.0.tgz'), instance: dir, dryRun: true },
+    { log: () => {}, err: () => {}, run: fakeRun(calls, { dirty: '' }) }
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.dryRun, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin unchanged in dry-run');
+  assert.ok(!calls.some((c) => c.startsWith('npm')), 'no npm spawned in dry-run');
+});
+
+// ---- 6. full happy-path (every side effect injected; ledger skipped, DB-free) ----
+t('full: pre-flight → pin → install → migrate → materialize → restart → verify', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'cloudbongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [];
+  let materialized = null;
+  let regenArgs = null;
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'cloudbongos-core-1.15.0.tgz'), instance: dir, service: 'emersonian.service' },
+    {
+      log: () => {}, err: () => {},
+      run: fakeRun(calls, { dirty: '', installTo: '1.15.0', dir }),
+      materialize: (a) => { materialized = a; return { skills: 35, settings: true, hooks: 3 }; },
+      regenerateApiArtifacts: (a) => { regenArgs = a; return { ok: true, ran: ['gen-api-docs.js', 'gen-api-client.js'] }; },
+      databaseUrl: '', pgDatabase: '', // skip the ledger — keeps the test DB-free even if PGDATABASE is set in the env
+    }
+  );
+  assert.equal(res.ok, true, 'upgrade should succeed');
+  assert.equal(res.fromVersion, '1.14.1');
+  assert.equal(res.toVersion, '1.15.0');
+  assert.equal(res.versionOk, true, 'installed version must equal the target after install');
+  // pin rewritten, tarball vendored
+  assert.equal(u.readPinnedCoreVersion(dir), '1.15.0');
+  assert.equal(readFileSync(join(dir, 'vendor', 'cloudbongos-core-1.15.0.tgz'), 'utf8'), 'TGZ');
+  // steps ran, in the expected order
+  assert.deepEqual(
+    calls.filter((c) => c.startsWith('npm') || c.startsWith('git') || c.startsWith('systemctl')),
+    ['git status --porcelain', 'npm install --no-audit --no-fund', 'npm run migrate', 'systemctl restart emersonian.service']
+  );
+  // materialize pointed at the freshly-installed core
+  assert.ok(materialized && materialized.coreRoot.endsWith(join('node_modules', '@cloudbongos', 'core')));
+  assert.equal(materialized.instanceDir, dir);
+  // task 2051: the API docs+client regen ran too, pointed at the same new core + instance
+  assert.ok(regenArgs, 'regenerateApiArtifacts step invoked');
+  assert.equal(regenArgs.instanceDir, dir);
+  assert.ok(regenArgs.coreRoot.endsWith(join('node_modules', '@cloudbongos', 'core')));
+});
+
+// ---- 6b. regenerate the API artifacts on upgrade (task 2051) ----------------
+t('regenerateApiArtifacts: spawns docs then client from the new core, targeting the instance', () => {
+  const calls = [];
+  const run = (cmd, args, opts) => { calls.push({ cmd, args, opts }); return { status: 0 }; };
+  const res = u.regenerateApiArtifacts({ instanceDir: '/inst', coreRoot: '/inst/node_modules/@cloudbongos/core' }, run, { existsSync: () => true });
+  assert.equal(res.ok, true);
+  assert.deepEqual(res.ran, ['gen-api-docs.js', 'gen-api-client.js']);
+  assert.equal(calls.length, 2);
+  // docs BEFORE client (the client reads the spec docs produce)
+  assert.ok(calls[0].args[0].endsWith(join('scripts', 'gds', 'gen-api-docs.js')));
+  assert.ok(calls[1].args[0].endsWith(join('scripts', 'gds', 'gen-api-client.js')));
+  for (const c of calls) {
+    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');
+  }
+});
+
+t('regenerateApiArtifacts: a missing generator in core is a graceful failure (never throws)', () => {
+  const res = u.regenerateApiArtifacts({ instanceDir: '/inst', coreRoot: '/core' }, () => ({ status: 0 }), { existsSync: () => false });
+  assert.equal(res.ok, false);
+  assert.match(res.reason, /gen-api-docs\.js not found/);
+  assert.deepEqual(res.ran, []);
+});
+
+t('regenerateApiArtifacts: a generator non-zero exit stops + reports (docs ran, client did not)', () => {
+  const run = (cmd, args) => ({ status: args[0].endsWith('gen-api-client.js') ? 1 : 0 });
+  const res = u.regenerateApiArtifacts({ instanceDir: '/inst', coreRoot: '/core' }, run, { existsSync: () => true });
+  assert.equal(res.ok, false);
+  assert.deepEqual(res.ran, ['gen-api-docs.js'], 'docs succeeded before the client failed');
+  assert.match(res.reason, /gen-api-client\.js exited 1/);
+});
+
+t('runUpgrade: --skip-regen-docs skips the regen step', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'cloudbongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  let regenCalled = false;
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'cloudbongos-core-1.15.0.tgz'), instance: dir, skipRegenDocs: true },
+    {
+      log: () => {}, err: () => {},
+      run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }),
+      materialize: () => ({ skills: 1 }),
+      regenerateApiArtifacts: () => { regenCalled = true; return { ok: true, ran: [] }; },
+      databaseUrl: '', pgDatabase: '',
+    }
+  );
+  assert.equal(res.ok, true);
+  assert.equal(regenCalled, false, '--skip-regen-docs must skip the regen step');
+});
+
+// ---- 7. recordLedger resolves the DB two ways (task 1984) -------------------
+t('recordLedger: skips when neither DATABASE_URL nor PGDATABASE is set', async () => {
+  const res = await u.recordLedger({ toVersion: '1.16.0' }, { databaseUrl: '', pgDatabase: '' });
+  assert.equal(res.ok, false);
+  assert.equal(res.skipped, true);
+  assert.match(res.reason, /DATABASE_URL or PGDATABASE/);
+});
+
+t('recordLedger: PGDATABASE path shells out to `psql -d <db>` with the INSERT on stdin', async () => {
+  const calls = [];
+  const run = (cmd, args, opts) => { calls.push({ cmd, args, opts }); return { status: 0, stdout: 'INSERT 0 1\n' }; };
+  const res = await u.recordLedger(
+    { fromVersion: '1.15.0', toVersion: '1.16.0', sourceCommit: 'abc123', note: "ran by lars; it's live" },
+    { databaseUrl: '', pgDatabase: 'emersonian_circles', run }
+  );
+  assert.equal(res.ok, true);
+  assert.equal(calls.length, 1);
+  const { cmd, args, opts } = calls[0];
+  assert.equal(cmd, 'psql');
+  // connects by db name (socket/peer auth — the migrate.sh shape), not a URL
+  const dIdx = args.indexOf('-d');
+  assert.equal(args[dIdx + 1], 'emersonian_circles');
+  // values are fed as psql :'var's (safely quoted), not concatenated into the SQL string
+  assert.ok(args.includes('--set') && args.includes('from_version=1.15.0'));
+  assert.ok(args.includes("note=ran by lars; it's live"), 'note passes verbatim as its own argv (no shell)');
+  // SQL is on STDIN (not -c), because psql only runs :'var' interpolation in script/stdin mode
+  assert.ok(!args.includes('-c'), 'must NOT use -c (no interpolation there)');
+  const sql = opts.input;
+  assert.match(sql, /INSERT INTO core_upgrades/);
+  assert.match(sql, /:'to_version'/);
+  assert.match(sql, /NULLIF\(:'from_version',''\)/);
+  assert.ok(!sql.includes('1.15.0'), 'no interpolated value baked into the SQL text (injection-safe)');
+});
+
+t('recordLedger: psql non-zero exit → failed (skipped:false so the caller surfaces it)', async () => {
+  const run = () => ({ status: 1, stderr: 'ERROR:  relation "core_upgrades" does not exist\n' });
+  const res = await u.recordLedger({ toVersion: '1.16.0' }, { databaseUrl: '', pgDatabase: 'x', run });
+  assert.equal(res.ok, false);
+  assert.equal(res.skipped, false);
+  assert.match(res.reason, /does not exist/);
+});
+
+t('recordLedger: psql missing (ENOENT) → skipped (benign, clear reason)', async () => {
+  const run = () => ({ error: Object.assign(new Error('spawn psql ENOENT'), { code: 'ENOENT' }) });
+  const res = await u.recordLedger({ toVersion: '1.16.0' }, { databaseUrl: '', pgDatabase: 'x', run });
+  assert.equal(res.ok, false);
+  assert.equal(res.skipped, true);
+  assert.match(res.reason, /psql not found/);
+});
+
+t('recordLedger: DATABASE_URL path still uses the pg driver (back-compat)', async () => {
+  const queries = [];
+  const fakePg = { Pool: class { async query(sql, params) { queries.push({ sql, params }); } async end() {} } };
+  const res = await u.recordLedger(
+    { fromVersion: '1.15.0', toVersion: '1.16.0', sourceCommit: 'abc', note: 'n' },
+    { databaseUrl: 'postgres://x/y', pg: fakePg }
+  );
+  assert.equal(res.ok, true);
+  assert.equal(queries.length, 1);
+  assert.match(queries[0].sql, /INSERT INTO core_upgrades/);
+  assert.deepEqual(queries[0].params, ['1.15.0', '1.16.0', 'abc', 'n']);
+});
+
+// ---- 8. pollHealth retries past the restart race (task 1984) ----------------
+t('pollHealth: returns on the first 2xx (no wasted retries)', async () => {
+  let n = 0;
+  const res = await u.pollHealth('http://x/healthz', {
+    fetch: async () => { n++; return { ok: true, status: 200 }; },
+    sleep: async () => {}, now: () => 0,
+  });
+  assert.equal(res.ok, true);
+  assert.equal(res.status, 200);
+  assert.equal(res.attempts, 1);
+  assert.equal(n, 1);
+});
+
+t('pollHealth: retries past early failures, then succeeds (the restart race)', async () => {
+  let n = 0, slept = 0;
+  const res = await u.pollHealth('http://x/healthz', {
+    // first two attempts throw (port not bound yet), third is 2xx
+    fetch: async () => { n++; if (n < 3) throw new Error('fetch failed'); return { ok: true, status: 200 }; },
+    sleep: async () => { slept++; }, now: () => 0, healthBudgetMs: 30_000,
+  });
+  assert.equal(res.ok, true);
+  assert.equal(res.attempts, 3);
+  assert.equal(slept, 2, 'backed off between the two failed attempts');
+});
+
+t('pollHealth: gives up after the budget with a timedOut failure (never hangs)', async () => {
+  let clock = 0;
+  const res = await u.pollHealth('http://x/healthz', {
+    fetch: async () => { throw new Error('ECONNREFUSED'); },
+    sleep: async () => { clock += 1_000; }, now: () => clock, healthBudgetMs: 3_000,
+  });
+  assert.equal(res.ok, false);
+  assert.equal(res.timedOut, true);
+  assert.match(res.error, /ECONNREFUSED/);
+});
+
+t('pollHealth: a persistent non-2xx status is reported (not treated as ready)', async () => {
+  let clock = 0;
+  const res = await u.pollHealth('http://x/healthz', {
+    fetch: async () => ({ ok: false, status: 503 }),
+    sleep: async () => { clock += 1_000; }, now: () => clock, healthBudgetMs: 2_000,
+  });
+  assert.equal(res.ok, false);
+  assert.equal(res.status, 503);
+  assert.equal(res.timedOut, true);
+});
+
+await Promise.all(pending);
+console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);