@bongos/core 1.17.0 → 1.17.2

package/tests/upgrade.mjs

@@ -34,13 +34,13 @@ 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` },
+    dependencies: { '@bongos/core': `file:vendor/bongos-core-${pinned}.tgz` },
     scripts: { migrate: 'true', start: 'true' },
   }, null, 2) + '\n');
   if (installed) {
-    const cd = join(dir, 'node_modules', '@cloudbongos', 'core');
+    const cd = join(dir, 'node_modules', '@bongos', 'core');
     mkdirSync(cd, { recursive: true });
-    writeFileSync(join(cd, 'package.json'), JSON.stringify({ name: '@cloudbongos/core', version: installed }) + '\n');
+    writeFileSync(join(cd, 'package.json'), JSON.stringify({ name: '@bongos/core', version: installed }) + '\n');
   }
   return dir;
 }
@@ -52,8 +52,8 @@ function fakeRun(calls, { dirty = '', installTo = null, dir = null } = {}) {
     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');
+      writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'),
+        JSON.stringify({ name: '@bongos/core', version: installTo }) + '\n');
     }
     return { status: 0 };
   };
@@ -61,20 +61,20 @@ function fakeRun(calls, { dirty = '', installTo = null, dir = null } = {}) {
 
 // ---- 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('file:vendor/bongos-core-1.14.1.tgz'), '1.14.1');
+  assert.equal(u.versionFromTgzPath('vendor/bongos-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');
+  const prev = u.writePin(dir, 'vendor/bongos-core-1.15.0.tgz');
+  assert.equal(prev, 'file:vendor/bongos-core-1.14.1.tgz');
   assert.equal(u.readPinnedCoreVersion(dir), '1.15.0');
 });
 
-t('readInstalledCoreVersion: reads node_modules/@cloudbongos/core', () => {
+t('readInstalledCoreVersion: reads node_modules/@bongos/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);
@@ -83,13 +83,13 @@ t('readInstalledCoreVersion: reads node_modules/@cloudbongos/core', () => {
 // ---- 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}');
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZBYTES');
+  writeFileSync(join(src, 'bongos-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'));
+  const rel = u.vendorTarball({ instanceDir: dir, fromTgz: join(src, 'bongos-core-1.15.0.tgz'), targetVersion: '1.15.0' });
+  assert.equal(rel, join('vendor', 'bongos-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');
+  assert.ok(existsSync(join(dir, 'vendor', 'bongos-core-1.15.0.manifest.json')), 'manifest copied too');
 });
 
 // ---- 3. step shims issue the right argv ------------------------------------
@@ -137,11 +137,11 @@ t('guard: already on the target refuses (unless --force)', async () => {
 // ---- 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');
+  writeFileSync(join(src, 'bongos-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 },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, dryRun: true },
     { log: () => {}, err: () => {}, run: fakeRun(calls, { dirty: '' }) }
   );
   assert.equal(res.ok, true);
@@ -153,13 +153,13 @@ t('dry-run: plans without rewriting package.json or spawning npm', async () => {
 // ---- 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');
+  writeFileSync(join(src, 'bongos-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' },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'emersonian.service' },
     {
       log: () => {}, err: () => {},
       run: fakeRun(calls, { dirty: '', installTo: '1.15.0', dir }),
@@ -174,26 +174,26 @@ t('full: pre-flight → pin → install → migrate → materialize → restart
   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');
+  assert.equal(readFileSync(join(dir, 'vendor', 'bongos-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.ok(materialized && materialized.coreRoot.endsWith(join('node_modules', '@bongos', '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')));
+  assert.ok(regenArgs.coreRoot.endsWith(join('node_modules', '@bongos', '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 });
+  const res = u.regenerateApiArtifacts({ instanceDir: '/inst', coreRoot: '/inst/node_modules/@bongos/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);
@@ -225,11 +225,11 @@ t('regenerateApiArtifacts: a generator non-zero exit stops + reports (docs ran,
 
 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');
+  writeFileSync(join(src, 'bongos-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 },
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, skipRegenDocs: true },
     {
       log: () => {}, err: () => {},
       run: fakeRun([], { dirty: '', installTo: '1.15.0', dir }),
@@ -352,6 +352,201 @@ t('pollHealth: a persistent non-2xx status is reported (not treated as ready)',
   assert.equal(res.timedOut, true);
 });
 
+// ---- 7. registry update channel (ADR 0134, task 2090) -----------------------
+t('versionFromDep: parses bare/caret/tilde semver; file: spec → null (tgz path is versionFromTgzPath\'s job)', () => {
+  assert.equal(u.versionFromDep('1.17.0'), '1.17.0');
+  assert.equal(u.versionFromDep('^1.17.0'), '1.17.0');
+  assert.equal(u.versionFromDep('~1.17.0'), '1.17.0');
+  assert.equal(u.versionFromDep('file:vendor/bongos-core-1.17.0.tgz'), null);
+  assert.equal(u.versionFromDep(''), null);
+  assert.equal(u.versionFromDep(null), null);
+});
+
+t('writeRegistryPin / readPinnedCoreVersion: round-trip an exact registry version', () => {
+  const dir = scratchConsumer({ pinned: '1.16.0', installed: '1.16.0' });
+  const prev = u.writeRegistryPin(dir, '1.17.0');
+  assert.equal(prev, 'file:vendor/bongos-core-1.16.0.tgz', 'returns the previous pin');
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '1.17.0', 'pins the exact version (not file:)');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.17.0', 'reads the registry pin back');
+});
+
+t('runUpgrade --registry (dry-run): plans a registry pin, no npm, pin unchanged', async () => {
+  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, dryRun: true },
+    { log: () => {}, err: () => {}, run: fakeRun(calls, { dirty: '' }) }
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.dryRun, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.16.0', 'pin unchanged in dry-run');
+  assert.ok(!existsSync(join(dir, '.npmrc')), 'dry-run writes no .npmrc');
+  assert.ok(!calls.some((c) => c.startsWith('npm')), 'no npm spawned in dry-run');
+});
+
+t('runUpgrade --registry + --from: refuses (mutually exclusive core sources)', async () => {
+  const dir = scratchConsumer({ pinned: '1.16.0', installed: '1.16.0' });
+  const res = await u.runUpgrade(
+    { to: '1.17.0', registry: true, from: '/tmp/x.tgz', instance: dir },
+    { log: () => {}, err: () => {}, run: fakeRun([], { dirty: '' }) }
+  );
+  assert.equal(res.ok, false);
+  assert.match(res.error, /mutually exclusive/);
+});
+
+t('runUpgrade --registry (full): pins the exact version + writes the env-fed .npmrc, then install→migrate→verify', async () => {
+  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' },
+    {
+      log: () => {}, err: () => {},
+      run: fakeRun(calls, { dirty: '', installTo: '1.17.0', dir }),
+      materialize: () => ({ skills: 1, settings: true, hooks: 1 }),
+      regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: '', pgDatabase: '',
+    }
+  );
+  assert.equal(res.ok, true, 'registry upgrade succeeds');
+  assert.equal(res.toVersion, '1.17.0');
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '1.17.0', 'exact registry pin (no file:)');
+  const npmrc = readFileSync(join(dir, '.npmrc'), 'utf8');
+  assert.match(npmrc, /_authToken=\$\{NPM_TOKEN\}/, 'wrote the env-fed .npmrc');
+  assert.ok(calls.some((c) => /^npm install/.test(c)), 'ran npm install (resolves from the registry)');
+  assert.ok(!calls.some((c) => /vendor/.test(c)), 'did not vendor a tarball');
+});
+
+// ---- 9. auto-rollback on failure (task 2149) --------------------------------
+
+// A pin-aware spawn shim: `npm install` installs whatever the CURRENT pin resolves to, so the
+// forward install lands the target and a post-rollback install restores the previous core.
+// Knobs simulate a failing target install or a failing migrate.
+function pinAwareRun(calls, { dir, failMigrate = false, failInstallForVersion = null } = {}) {
+  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 pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      const dep = pkg.dependencies['@bongos/core'];
+      const v = u.versionFromTgzPath(dep) || u.versionFromDep(dep);
+      if (failInstallForVersion && v === failInstallForVersion) return { status: 1 };
+      writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'),
+        JSON.stringify({ name: '@bongos/core', version: v }) + '\n');
+      return { status: 0 };
+    }
+    if (cmd === 'npm' && args[0] === 'run' && args[1] === 'migrate') return { status: failMigrate ? 1 : 0 };
+    return { status: 0 }; // systemctl / restart-cmd / anything else
+  };
+}
+
+// A fake pg that records every ledger INSERT's params (params[3] = note).
+function recordingPg(queries) {
+  return { Pool: class { async query(sql, params) { queries.push({ sql, params }); } async end() {} } };
+}
+
+t('rollback on health failure: reverts pin, restarts again, re-checks health, writes ONE rolled_back ledger row', 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 = [], queries = [];
+  let fetchN = 0;
+  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: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+      // forward health fails (1st fetch); the post-rollback re-check recovers (2nd fetch)
+      fetch: async () => { fetchN++; return fetchN === 1 ? { ok: false, status: 503 } : { ok: true, status: 200 }; },
+      sleep: async () => {}, now: () => 0, healthBudgetMs: 0,
+    }
+  );
+  assert.equal(res.ok, false, 'a failed health check is not a success');
+  assert.equal(res.rolledBack, true, 'the upgrade rolled back');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted to the previous core');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.equal(res.rollback.healthOk, true, 'health recovered after the rollback restart');
+  assert.equal(calls.filter((c) => c === 'systemctl restart demo.service').length, 2, 'restarted twice: forward + rollback');
+  assert.equal(queries.length, 1, 'only the rolled_back row is written (no phantom upgraded row)');
+  assert.equal(queries[0].params[1], '1.15.0', 'to_version = the attempted target');
+  assert.match(queries[0].params[3], /^rolled_back:/, 'note marks the reversal');
+});
+
+t('rollback on migrate failure: reverts pin + reinstalls previous core + rolled_back ledger', 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 = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir, failMigrate: true }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.rolledBack, true);
+  assert.match(res.rollback.reason, /migrate failed/);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.equal(queries.length, 1);
+  assert.match(queries[0].params[3], /^rolled_back: migrate failed/);
+});
+
+t('rollback on npm-install failure: reverts pin + reinstalls previous core', 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 = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir, failInstallForVersion: '1.15.0' }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.rolledBack, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted after the failed install');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.match(queries[0].params[3], /^rolled_back: npm install failed/);
+});
+
+t('--no-rollback-on-failure: a failed health check does NOT revert (records the attempt, leaves the new pin)', 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 queries = [];
+  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', rollbackOnFailure: false },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun([], { dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+      fetch: async () => ({ ok: false, status: 503 }), sleep: async () => {}, now: () => 0, healthBudgetMs: 0,
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(!res.rolledBack, 'no rollback when opted out');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.15.0', 'the new pin is left in place for inspection');
+  assert.equal(queries.length, 1, 'the attempt is still recorded');
+  assert.ok(!/^rolled_back/.test(queries[0].params[3] || ''), 'not marked as a rollback');
+});
+
+t('restorePin: writes a previous dep string back verbatim (file: or registry)', () => {
+  const dir = scratchConsumer({ pinned: '1.15.0' });
+  u.restorePin(dir, 'file:vendor/bongos-core-1.14.1.tgz');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1');
+  u.restorePin(dir, '^1.16.0');
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '^1.16.0');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/workflow_exec_paths.mjs

@@ -0,0 +1,98 @@
+// tests/workflow_exec_paths.mjs — task 2136 (ADR 0108 configurable-root).
+//
+// Proves every .github/workflows/*.yml invocation of a CORE script resolves in a consumer layout
+// after the R89 split: each is routed through the both-layouts resolver (infra/core-node.sh for
+// node targets, infra/core-path.sh for bash targets) AND names a PUBLISHABLE core file that ships
+// in @bongos/core (→ present at node_modules/@bongos/core post-install) and exists at the core root
+// today. No workflow still invokes a core script the bare repo-relative way. Also proves
+// core-path.sh resolves both layouts (the bash-target sibling of core-node.sh).
+//
+// DB-free, no network. Run: node tests/workflow_exec_paths.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { lintWorkflowExec } = require('../scripts/gds/lint-workflow-exec.js');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(__dirname, '..');
+const CORE_PATH_SH = path.join(REPO, 'infra', 'core-path.sh');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+// ---- A. the workflow lint is green on the real tree ---------------------------------------------
+test('lint-workflow-exec: every core invocation is routed + publishable (no bare repo-relative form)', () => {
+  const r = lintWorkflowExec({ instanceRoot: REPO, coreRoot: REPO });
+  assert.deepEqual(r.violations, [], `expected no violations, got: ${JSON.stringify(r.violations, null, 2)}`);
+  assert.ok(r.ok, 'lint should pass');
+  // The security-critical merge gates + the functional gates must all be covered.
+  const rels = r.checked.map((c) => `${c.file}:${c.rel}`);
+  assert.ok(rels.some((s) => s.startsWith('gate-review.yml:') && s.endsWith('scripts/gds/gate-review.js')), 'gate-review routed');
+  assert.ok(rels.some((s) => s.startsWith('grade-gate.yml:') && s.endsWith('scripts/gds/ci-grade.js')), 'grade-gate routed');
+  assert.ok(rels.some((s) => s.endsWith('scripts/migrate.sh')), 'selfhost migrate routed via core-path.sh');
+});
+
+test('lint-workflow-exec: a bare core invocation in a workflow is flagged (counterfactual)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'wf-lint-'));
+  try {
+    fs.mkdirSync(path.join(tmp, '.github', 'workflows'), { recursive: true });
+    fs.mkdirSync(path.join(tmp, 'scripts', 'gds'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'scripts', 'gds', 'gate-review.js'), '// probe\n');
+    fs.writeFileSync(path.join(tmp, '.github', 'workflows', 'legacy.yml'),
+      'jobs:\n  x:\n    steps:\n      - run: node scripts/gds/gate-review.js\n');
+    const r = lintWorkflowExec({ instanceRoot: tmp, coreRoot: tmp });
+    assert.ok(!r.ok, 'a bare core invocation must fail the lint');
+    assert.equal(r.violations.length, 1);
+    assert.match(r.violations[0].why, /bare core invocation/);
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+// ---- B. core-path.sh resolves BOTH layouts ------------------------------------------------------
+function runCorePath(rel, instanceRoot) {
+  return execFileSync('bash', [CORE_PATH_SH, rel], {
+    encoding: 'utf8', env: { ...process.env, BONGOS_INSTANCE_ROOT: instanceRoot },
+  }).trim();
+}
+
+test('core-path.sh prints the monolith path (script at the instance root)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-mono-'));
+  try {
+    fs.mkdirSync(path.join(tmp, 'scripts'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'scripts', 'migrate.sh'), '# probe\n');
+    assert.equal(runCorePath('scripts/migrate.sh', tmp), path.join(tmp, 'scripts', 'migrate.sh'));
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+test('core-path.sh falls back to the consumer path (script only under node_modules/@bongos/core)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-cons-'));
+  try {
+    const pkg = path.join(tmp, 'node_modules', '@bongos', 'core', 'scripts');
+    fs.mkdirSync(pkg, { recursive: true });
+    fs.writeFileSync(path.join(pkg, 'migrate.sh'), '# probe\n');
+    assert.equal(runCorePath('scripts/migrate.sh', tmp), path.join(pkg, 'migrate.sh'));
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+test('core-path.sh exits non-zero (no stdout) when the script is in NO layout', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-none-'));
+  let threw = false;
+  try {
+    execFileSync('bash', [CORE_PATH_SH, 'scripts/nope.sh'], {
+      encoding: 'utf8', stdio: 'pipe', env: { ...process.env, BONGOS_INSTANCE_ROOT: tmp },
+    });
+  } catch (_) { threw = true; }
+  finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+  assert.ok(threw, 'expected a non-zero exit when the script resolves in no layout');
+});
+
+console.log(`\nworkflow_exec_paths: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/docs/design/container-exterior-tiles.md

@@ -1,49 +0,0 @@
-# Container building — exterior tile spec (pixel-precise, V2)
-
-- **Task:** [#643](https://example.com/builders#/task/643) (V2 · product). Promoted from idea_inbox [#162](https://example.com/builders#/idea/162) (builder 25 art/design brief, 2026-06-04).
-- **Date:** 2026-06-18
-- **Builds on:** [`container-exterior.md`](container-exterior.md) (the structure-level design, task [#641](https://example.com/builders#/task/641)) — this is the **tile-level** layer it calls out. Colour is governed by the locked decisions below.
-- **Status:** Spec ready. **Generation waits for [#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md)** (every tile here re-quantizes against the replacement palette — per `container-exterior.md` §Pipeline). Spec work proceeds now.
-
-## ⚠️ Colour: the original brief is superseded — weathered charcoal, not clean red
-
-idea [#162](https://example.com/builders#/idea/162)'s brief (this task's source) asked for **"saturated industrial red (or black) — clean, no weathering, no rust."** That was written **before** Lars resolved the question. The authoritative decision (later wins):
-
-- **Blocker [#7](https://example.com/builders#/blocker/7) (Lars, 2026-06-10, now a locked `style_guide.md` rule):** the container body is **weathered BLACK/CHARCOAL corrugated metal with rust streaks** — *not* red, *not* teal. Faded **Hermes-teal is an ACCENT only** (the door panel + a faint caduceus etch). It must read as an *ancient, heavy, discovered relic*, not factory-new cargo.
-- **`style_guide.md` (Lars, 2026-06-14):** **no white / light edge rim** on container (or other large-object) tiles — strip near-white edge pixels in post ("the white on the container actually sucks").
-- **`style_guide.md`:** non-ground objects carry a **1-px darker outline** against their interior (FireRed rock/tree convention); ground tiles do not.
-
-So every tile below is **weathered charcoal corrugated metal with rust streaks**; the brief's "clean red, no weathering, single-pixel white highlight" wording does **not** apply. The brief's *geometry* (corrugation, glass panels, deck, roof, staircase) is still the source — only the colour/finish is corrected.
-
-## Per-tile pixel specs (32×32 base)
-
-### Container wall tile
-- **Base:** weathered charcoal/gunmetal (a matte near-black with a faint blue-grey undertone), drawn from the replacement palette's charcoal/grey value steps (ADR 0044 guarantees enough steps).
-- **Corrugation:** 4–5 vertical ridges per tile. Each ridge: 1px lighter charcoal on the left (highlight), 1px darker on the right (shadow); flat panels between are the base.
-- **Weathering:** sparse vertical **rust streaks** (a desaturated orange-brown from the palette) bleeding downward from ridge tops + seams — irregular, 1–2px wide, not on every ridge. Reads as age, not damage.
-- **Edges:** 1px darker-charcoal **outline** on the object silhouette (per the style rule). Top edge 2px darker (top face in oblique light); bottom edge 1px near-black ground shadow. **No white/light rim** anywhere on the silhouette.
-- **Stacked-unit seam:** a 2px dark recessed line with a 1px shadow below, where the ground-floor container meets the second storey.
-
-### Glass storefront / window panel (32×32, or 64×32 wide)
-- **Fill:** semi-transparent blue-grey (≈40–50% over what's behind). Through dark glass, a faint **warm amber interior glow** (the "dark exterior, warm interior" mood from `container-exterior.md`).
-- **Frame:** 3px matte-charcoal border (the frames dissolve into the dark facade rather than reading as separate elements).
-- **Interior hint:** extremely faint 1–2-shade-darker silhouettes (a plant, shelving) — not detailed.
-- **Reflection highlight — FLAG for Lars:** the brief wanted a white upper-left reflection strip; the no-white-rim rule targets the *object silhouette*, not interior glass. Proposed: a restrained **pale-blue** (not white) 1px upper-left reflection inside the frame. If Lars wants zero light pixels here, drop it. *(Open pixel-detail decision.)*
-
-### Door tile (the one Hermes-teal accent)
-- Charcoal frame; the door panel is **faded Hermes-teal** (the single body-color exception), with a **faint caduceus etch** (1–2px lighter teal lines) where space allows, and a warm interior glow at the threshold. This is the only teal on the building.
-
-### Deck tile (wood apron, walkable)
-- Horizontal planks: light warm tan base, 4–5 planks/tile, 1px dark gap between; very subtle 1–2px grain lines; 2px darker far-edge shadow. Drawn as an alpha-margined object overlay over sand (the `marble_path` technique, [ADR 0013](../adr/<redacted>.md)) so it works on any ground.
-
-### Roof tile (top-down)
-- Flat charcoal surface, 1 shade darker than the wall face (less direct light); small 3×3 dark **container corner castings** at each corner; a faint 2px panel seam every 8px; 1px railing line on edge tiles (per `container-exterior.md` rooftop band).
-
-### Exterior staircase (object overlay)
-- Dark charcoal steel: two parallel rails with treads between (top-down ladder look); 1px railing line each outer edge, 1px lighter than the tread. Arrives at the rooftop stair-landing tile.
-
-## Mood target
-A **designed object, not a found one** — presence from its *shape and glass*, not from bright paint. The charcoal recedes into the coastal scene; at dusk the warm interior light through dark glass is the most dramatic visual in the game. The contradiction (an *ancient* shipping container) lives in the weathering + the teal-and-caduceus door.
-
-## Pipeline mapping (generate after [#640](https://example.com/builders#/task/640))
-Per [ADR 0008](../adr/<redacted>.md) (families, not per-tile): `container_building_facade` (wall · glass · door · light-fixture · staircase), `container_building_roof` (field · railing · landing), `deck_wood` (16-autotile alpha-tile line family). Furniture singletons (table, chairs) per-tile. **Nothing generates until the palette swap ([#640](https://example.com/builders#/task/640)/ADR 0044) lands** — else every tile re-quantizes against the old palette and is redone.

package/docs/design/container-exterior.md

@@ -1,81 +0,0 @@
-# Container building — exterior structure design (V2)
-
-- **Task:** [#641](https://example.com/builders#/task/641) (V2 · product · creative). Promoted from idea_inbox [#160](https://example.com/builders#/idea/160) (builder 25 art/design brief, 2026-06-04).
-- **Date:** 2026-06-11
-- **Status:** Design locked at the structure level. Pixel-precise tile specs are [#643](https://example.com/builders#/task/643) (facade); interior is [#642](https://example.com/builders#/task/642)/[#644](https://example.com/builders#/task/644)/[#645](https://example.com/builders#/task/645); palette implementation is [#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md).
-
-## What changes
-
-The container is no longer a single beached 4×2 object (the current `CONTAINER_LAYOUT` in
-`src/world/terrain.js`). It becomes a **two-storey trading house built from stacked
-shipping containers** — a designed building with a glass storefront, a wooden deck,
-an exterior staircase, and a flat rooftop. It reads as a *destination*, not salvage.
-
-The narrative survives intact: Hermes placed the containers; the Examplens stacked
-them into a trading house. The mythic contradiction (an *ancient* shipping container)
-stays — see the colour note below.
-
-## Colour: weathered black/charcoal (decided)
-
-The original brief asked for "bold, uniform red or black — not rusted or weathered."
-That option was resolved **after** the brief was written: blocker [#7](https://example.com/builders#/blocker/7) (Lars, 2026-06-10,
-recorded as a style-guide rule) fixed the container as **weathered black/charcoal
-corrugated metal with rust streaks**, with faded Hermes-teal as an *accent only* (the
-door + the caduceus etch). The later decision wins. So the building is charcoal and
-weathered — it is "designed architecture" by its *shape and glass*, not by looking
-factory-new. ADR 0044 already constrains the replacement palette to carry enough
-charcoal/grey value steps for this.
-
-## Top-down structure (32×32 tiles, FireRed building anatomy)
-
-FireRed conveys buildings top-down as **facade rows (what you'd see standing in front)
-topped by roof rows**. A second storey = a taller facade. The reference is the Celadon
-department store: tall glass-fronted facade, flat roof.
-
-The building is an **8-wide × 6-tall** visual block (up from 4×2):
-
-| Rows (top→bottom) | Band | Content |
-|---|---|---|
-| 1–2 | **Rooftop** | Flat container roof; 1-px railing along the edge tiles; a stair landing tile at the right edge where the exterior staircase arrives. Future rooftop deck props (parasol, crates) are object overlays, not part of this family. |
-| 3–4 | **Upper-storey facade** | Charcoal corrugated container walls with a continuous band of **large glass panels** (semi-transparent blue-grey, single white highlight stripe). Container seams visible at the stacked-unit joints. |
-| 5–6 | **Ground-storey facade** | Glass storefront panels flanking a centred **door** (the one Hermes-teal accent, faint caduceus etch, warm interior glow). Wall-mounted light fixtures as small details on the wall tiles either side — lit at dusk/night. |
-
-Attached, outside the 8×6 block:
-
-- **Exterior staircase** — a 1-tile-wide steel stair strip climbing the building's right
-  side from ground to the rooftop landing. Purely visual in V2 (blocking); the rooftop
-  becomes walkable in a later version, the art shouldn't need to change for that.
-- **Wooden deck** — a 2-row walkable apron in front of the ground facade, drawn as an
-  alpha-margined object overlay over sand (the marble-path technique, [ADR 0013](../adr/<redacted>.md)),
-  so it works on any ground. Outdoor furniture (table, two chairs) are blocking
-  object singletons placed on the deck, off the door's walking line.
-
-### Placement and collision
-
-Anchor at **(11, 4)** in the current 30×18 world: the building spans cols 11–18,
-rows 4–9 (grass behind, sand in front), the deck spans rows 10–11, and the existing
-marble path (col 13, rows 10–13) shifts to meet the door at col 14–15. All building
-tiles **block**, including the door — interaction stays "stand adjacent and face it,"
-exactly like the current container door. Deck tiles are walkable; furniture blocks.
-
-## Pipeline mapping (what gets generated, later)
-
-Per [ADR 0008](../adr/<redacted>.md), coherent groups are families, not per-tile calls:
-
-1. **`container_building_facade`** family — wall, glass-panel, door, light-fixture, and
-   staircase tiles (replaces the 2×4 `container` family in `art/template/families.json`).
-2. **`container_building_roof`** family — roof field, railing edges/corners, stair landing.
-3. **`deck_wood`** — 16-autotile alpha-tile line family (same recipe as `marble_path`).
-4. **Furniture singletons** (table, chair) — per-tile pipeline.
-
-**Sequencing rule: generate nothing until [#640](https://example.com/builders#/task/640) / ADR 0044 lands.** Every one of these
-tiles would be quantized against the old palette and re-done after the Mediterranean
-swap. Spec work ([#643](https://example.com/builders#/task/643)) can proceed now; generation waits.
-
-## Engineering follow-up (not this task)
-
-The world model needs a matching change in **both** `map.js`/`terrain.js` twins
-(server + client): new OBJECT ids, an 8×6 building layout replacing
-`CONTAINER_PANELS_ROWMAJOR`/`CONTAINER_LAYOUT`, deck overlay placement, and blocking
-rules as above. That is an engineering task to be filed when the facade family's tile
-ids are final (after [#643](https://example.com/builders#/task/643)).