@bongos/core 1.19.924 → 1.19.925

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.924",
-  "core_contract": "1.19.924",
-  "source_commit": "c6cacd0f4e168f1f47817662b3eb47afa9b0e325",
+  "core_version": "1.19.925",
+  "core_contract": "1.19.925",
+  "source_commit": "930b42e46feac9ae2474f05b89fc6f34e34411f9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-20T22:26:38.017Z",
+  "built_at": "2026-09-20T22:35:59.969Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 511,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2849,
-  "tree_sha256": "c69c8cf54442568a4116f2e35e4ec1e9e72abbe2fac0bc4e258966118ad5aceb",
+  "tree_sha256": "10cb3a93d6b8e5f9825e7c3be73d087762b6fd943ed12823c7289f19939249f8",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2677,7 +2677,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7fd498d8715f13993c9a6063ec9add31cdc9ee13b1892af2c366e5c8314dc233"
+      "sha256": "7ada2ca77bedfca9dd58ce88e09d04a5449c08198adb55619285a95239a88481"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7917,12 +7917,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "71c16e136b5801d5f4e6c1a7f51259a4806e4455a56667d938f741165fb606c2"
+      "sha256": "37fbca7af4b1aa573094974c42fa895a9eec301c3af4fe8c2ce168753ce47ccc"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5ffcd517937622f074ddafa5e24c388f82e70025be47e2b2903ecb51fca516d1"
+      "sha256": "d667850fddfe0681b9e05312d9558a616f99be4f3eb399a8c6558d7e5745fc5f"
     },
     {
       "path": "public-docs/index.html",
@@ -8867,7 +8867,7 @@
     {
       "path": "scripts/gds/provision-core-upgrade.js",
       "mode": "0000644",
-      "sha256": "1c17b46ebe04bf19abfcfe40a0b3029c052362155b90b6445ea2b105cae7e621"
+      "sha256": "05292d556595bb3ce88a3e0b76c10c7cab2fef7f9d7e1af1e0b3610d48830692"
     },
     {
       "path": "scripts/gds/provision-disconnect.js",
@@ -8892,7 +8892,7 @@
     {
       "path": "scripts/gds/provision-repo.js",
       "mode": "0000644",
-      "sha256": "dd912cf4446f572257b0a9cc7380a331b8ae7e3d834ccff828fddc13ae5bcb19"
+      "sha256": "ef448bfb12437b2a3b83d7d726daff6a38b2a5a2db52096cc0150171d73547ce"
     },
     {
       "path": "scripts/gds/provision-teardown.js",
@@ -9922,7 +9922,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "d846a0cb8672ac4215442311fbc5a8c6bcd00f99e085e98b485095a2573007c5"
+      "sha256": "d365390e6290c57d21c149731cc048b379887d6f3146ba02dafdf89ee869739d"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10837,7 +10837,7 @@
     {
       "path": "tests/core_upgrade_runner.mjs",
       "mode": "0000644",
-      "sha256": "c818ad655da58837122dc40a8d64b0ca89eb643aebba094ed674546cbaa3b1f5"
+      "sha256": "994af91fda0df0ceb8b6e3eb80dd8bd23595a127a0e1d2e0381cb55e97beb557"
     },
     {
       "path": "tests/cosmos_token_contrast.mjs",

package/docs/module-api-changelog.md

@@ -2322,5 +2322,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.922 with no explicit bump. run 35541278656. (task 1002620)
   1.19.924 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.923 with no explicit bump. run 35541674047. (task 1002620)
+  1.19.925 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.924 with no explicit bump. run 35542154729. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.924",
+  "version": "1.19.925",
   "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/provision-core-upgrade.js

@@ -30,7 +30,7 @@
 
 const path = require('path');
 const { CONFIG, MANIFEST_VERIFY_INTERVAL_MS, MANIFEST_VERIFY_TRIES, REPO_ROOT } = require('./provision-config.js');
-const { APP_USER, dbName, instanceUser, standaloneRoot } = require('./provision-repo.js');
+const { APP_USER, dbName, instanceUser, selfInstanceRoot, standaloneRoot } = require('./provision-repo.js');
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 
 // The shapes whose box this runner can actually reach. Mirrors UPGRADE_SHAPES in the
@@ -96,7 +96,19 @@ function targetFault(to, available, installed, channel, channelAllows) {
   if (!available.includes(to)) {
     return `core ${to} is not published yet — nothing was changed. A release tag appears several minutes before the package itself does; try again once it lands.`;
   }
-  if (installed && channelAllows && !channelAllows(installed, to, channel)) {
+  // AN UNREADABLE `installed` IS A FAULT, NOT A FREE PASS (task 1004123).
+  //
+  // This guard used to be written `if (installed && …)`, so a null installed version
+  // skipped the channel check entirely rather than failing it. That is backwards: not
+  // knowing where an instance is today is the one state in which "is this jump
+  // permitted" cannot be answered, and the channel exists precisely to refuse jumps
+  // nobody has looked at. It also hid the defect that motivated this: the control
+  // plane read its installed version from the wrong directory for weeks and got null
+  // every time, and every press sailed past this line.
+  if (!installed) {
+    return `could not read the core version installed at this instance — nothing was changed. An upgrade that cannot say where it is starting from cannot be bounded by the '${channel}' channel.`;
+  }
+  if (channelAllows && !channelAllows(installed, to, channel)) {
     return `core ${to} is outside this project's '${channel}' update channel — nothing was changed. Change the channel first if this is deliberate.`;
   }
   return null;
@@ -156,7 +168,8 @@ async function coreUpgradeInstance(inst, deps, intent) {
 
   // ---- 2. is the target real, and permitted -----------------------------------------
   const channelMod = deps.updateChannel || require('./update-channel.js');
-  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : selfRoot();
   const readInstalled = deps.readInstalledCoreVersion || require('./upgrade.js').readInstalledCoreVersion;
   const installed = readInstalled(instanceDir);
   // THE PLATFORM DEFAULT, NOT A PER-INSTANCE CHANNEL — and saying so beats implying
@@ -190,7 +203,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
     : '';
   // Built by the SAME function the preview uses, so "what you were shown" and "what runs"
   // cannot drift apart into two hand-maintained flag lists (task 1004121).
-  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy });
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, requestedBy, selfRoot });
 
   if (!apply) {
     // A --dry-run runner tick used to only PRINT this command. It now runs the CLI's own
@@ -269,18 +282,31 @@ function parsePreflight(out) {
 // HERE rather than left to instanceUser()'s own throw: that throw is correct today, but
 // a call site whose safety depends on a helper's internals is one refactor away from a
 // shell-injection path (and the apply leg's own guard sits at the route, not here).
-function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '' } = {}) {
+function upgradeInvocation(inst, to, { privileged = false, dryRun = false, requestedBy = '', selfRoot = selfInstanceRoot } = {}) {
   if (!isValidSlug(inst && inst.slug)) {
     throw new Error(`upgradeInvocation: refusing to build a shell command from an invalid slug ${JSON.stringify(inst && inst.slug)}`);
   }
-  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  // WHERE THE CLI LIVES AND WHERE THE TARGET LIVES ARE DIFFERENT PLACES, TWICE OVER.
+  //
+  // `upgrade.js` ships in the CORE, and a provisioned instance root holds no scripts/
+  // directory at all — so the CLI runs from REPO_ROOT and NAMES its target (task
+  // 1004053, which fixed every standalone tenant).
+  //
+  // The second half is that REPO_ROOT is not the instance either (task 1004123). It
+  // names the copy of the core that is EXECUTING, which coincides with the instance
+  // only while the core is a checkout run in place. Once the control plane's runner
+  // moved into its vendored core the two diverged silently — REPO_ROOT still resolved,
+  // just to node_modules/@bongos/core — and the door aimed at the package instead of
+  // the project. So ask, rather than assume; in the legacy shape the answer is
+  // REPO_ROOT and the command below is byte-identical to what it always was.
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : selfRoot();
   // The control plane is not a provisioned tenant and has no `bongos-` account; every
   // other shape runs as its own, which is also its Postgres login role (task 1004119).
   const runAs = inst.hosting_shape === 'control-plane' ? APP_USER : instanceUser(inst);
   const sudoP = privileged ? `sudo -u ${runAs} env PGDATABASE=${dbName(inst)} ` : '';
   const cli = path.posix.join('scripts', 'gds', 'upgrade.js');
   const shared = [`${sudoP}node ${cli}`, '--registry', `--to ${to}`,
-    instanceDir === REPO_ROOT ? '' : `--instance ${instanceDir}`];
+    instanceDir === REPO_ROOT ? '' : `--instance ${instanceDir}`];  // REPO_ROOT is where the CLI runs (runDir below)
   const tail = dryRun
     ? ['--dry-run']
     : [`--service ${inst.slug}`,
@@ -297,7 +323,10 @@ function upgradeInvocation(inst, to, { privileged = false, dryRun = false, reque
 function preflightUpgrade(inst, to, deps) {
   const { exec, privileged } = deps;
   const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
-  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true });
+  // A distinct local name: `deps.selfInstanceRoot || selfInstanceRoot` with a const of
+  // the same name would TDZ-shadow the import and crash every uninjected call.
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const { cmd, runDir } = upgradeInvocation(inst, to, { privileged, dryRun: true, selfRoot });
   const r = boxExec(cmd, { cwd: runDir, allowFail: true });
   const out = `${(r && r.stdout) || ''}\n${(r && r.stderr) || ''}`;
   const { checks, error } = parsePreflight(out);
@@ -353,7 +382,8 @@ async function snapshotCoreVersions(inst, deps) {
   if (!UPGRADE_SHAPES.has(inst.hosting_shape) || inst.status !== 'active') return { ok: true, skipped: true };
   const boxExec = inst.hosting_shape === 'standalone' ? (deps.controlExec || exec) : exec;
   const channelMod = deps.updateChannel || require('./update-channel.js');
-  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : REPO_ROOT;
+  const selfRoot = deps.selfInstanceRoot || selfInstanceRoot;
+  const instanceDir = inst.hosting_shape === 'standalone' ? standaloneRoot(inst) : selfRoot();
   try {
     const probe = boxExec(versionCmd(inst), { allowFail: true });
     const served = parseServedVersion(probe && !probe.softFailed ? (probe.stdout || '') : null);

package/scripts/gds/provision-repo.js

@@ -91,6 +91,31 @@ const CORE_PKG_DIR = 'node_modules/@bongos/core';
 // one constant so the backup dir owner + the backup unit's User= can't drift from it.
 const APP_USER = 'lars';
 function standaloneRoot(inst, { base = CONFIG.standaloneBase } = {}) { return path.posix.join(base, inst.slug); }
+// WHERE THE INSTANCE THIS CORE SERVES ACTUALLY LIVES (task 1004123).
+//
+// REPO_ROOT is `path.resolve(__dirname, '..', '..')` — it points at whatever copy of
+// the core is EXECUTING, which is not the same place as the instance being upgraded.
+// Two shapes, and the code had only ever met the first:
+//
+//   • a core CHECKOUT run in place (`/home/lars/cloudbongos`) — the instance root IS
+//     the checkout, so REPO_ROOT was right by coincidence;
+//   • a VENDORED core (`<instance>/node_modules/@bongos/core`) — REPO_ROOT is the
+//     package, and the instance is three directories up.
+//
+// The live control plane became the second shape when its runner unit was re-homed
+// (`WorkingDirectory=/home/lars/cloudbongos-instance`, ExecStart into the vendored
+// core), and nothing noticed: REPO_ROOT still resolved, just to the wrong tree. So
+// `readInstalledCoreVersion` answered null instead of 1.19.917, every guard that
+// reads `installed` silently stopped guarding, and an upgrade would have pinned and
+// npm-installed INSIDE the core package while the instance's own pin stayed put.
+//
+// This is a string question, not a filesystem one: the vendored layout is the only
+// way a core ends up under `node_modules/`, so the suffix IS the answer. Keeping it
+// pure means the control-plane path is testable without a box.
+function selfInstanceRoot(repoRoot = REPO_ROOT) {
+  const suffix = path.sep + CORE_PKG_DIR.split('/').join(path.sep);
+  return repoRoot.endsWith(suffix) ? repoRoot.slice(0, -suffix.length) : repoRoot;
+}
 // Sync the instance's own repo (host content + the core pin). Mirrors deploy-instance.sh
 // step 1 — assumes the repo is already cloned at standaloneRoot (initial clone is a
 // precondition, like the runbook's `git pull`). Run with cwd = standaloneRoot.
@@ -1107,6 +1132,7 @@ module.exports = {
   safeVersionLabel,
   scaffoldStandaloneRepo,
   seedFirstVersionCmd,
+  selfInstanceRoot,
   standaloneInstallCmd,
   standaloneMigrateCmd,
   standalonePullCmd,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.924'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.925'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/core_upgrade_runner.mjs

@@ -36,6 +36,7 @@ const R = require('../scripts/gds/provision-core-upgrade.js');
 const U = require('../scripts/gds/upgrade.js');
 const P = require('../modules/provisioning/provisioning.js');
 const G = require('../modules/provisioning/control-plane-guard.js');
+const RP = require('../scripts/gds/provision-repo.js');
 
 let passed = 0;
 let failed = 0;
@@ -553,5 +554,98 @@ await t('a preview of nothing is refused rather than cached as a pass', async ()
   assert.equal(d.queries.filter((q) => /INSERT INTO provisioning_core_version_snapshot/.test(q.sql)).length, 0);
 });
 
+console.log('\nwhere the instance actually is (task 1004123):');
+
+// The vendored layout the live control plane runs in: the core is a PACKAGE inside the
+// instance, so the directory the core executes from is three levels below the directory
+// that must be upgraded.
+const VENDORED = '/home/lars/cloudbongos-instance/node_modules/@bongos/core';
+const INSTANCE = '/home/lars/cloudbongos-instance';
+const LEGACY = '/home/lars/cloudbongos';
+
+await t('selfInstanceRoot walks out of a vendored core, and leaves a plain checkout alone', () => {
+  assert.equal(RP.selfInstanceRoot(VENDORED), INSTANCE, 'the package is not the instance');
+  assert.equal(RP.selfInstanceRoot(LEGACY), LEGACY, 'a checkout run in place IS the instance');
+});
+
+await t('a path that merely CONTAINS the package name is not mistaken for one', () => {
+  // Guarding the string test itself: only a trailing segment means "I am the vendored
+  // core", and an instance that happens to live under a similarly-named directory must
+  // not be truncated into nonsense.
+  const decoy = '/srv/node_modules/@bongos/core-tools';
+  assert.equal(RP.selfInstanceRoot(decoy), decoy);
+  assert.equal(RP.selfInstanceRoot('/srv/node_modules/@bongos/core/sub'), '/srv/node_modules/@bongos/core/sub');
+});
+
+await t('the runner reads the installed version from the INSTANCE, not from the core package', async () => {
+  // The defect this replaces: readInstalledCoreVersion was handed REPO_ROOT, which in
+  // the vendored shape holds no node_modules/@bongos/core at all — so it answered null
+  // on the live control plane for as long as the shape has existed.
+  const asked = [];
+  const d = { ...makeDeps({ served: '1.19.762' }), selfInstanceRoot: () => INSTANCE };
+  d.readInstalledCoreVersion = (dir) => { asked.push(dir); return '1.19.760'; };
+  await R.coreUpgradeInstance(inst({ hosting_shape: 'control-plane', slug: 'cloudbongos', port: 3002 }), d, intent());
+  assert.deepEqual(asked, [INSTANCE], 'asked the instance root exactly once');
+});
+
+await t('the CLI runs where it lives and NAMES the instance it is aimed at', async () => {
+  const d = { ...makeDeps({ served: '1.19.762' }), selfInstanceRoot: () => INSTANCE };
+  await R.coreUpgradeInstance(inst({ hosting_shape: 'control-plane', slug: 'cloudbongos', port: 3002 }), d, intent());
+  const cmd = upgradeCall(d);
+  assert.ok(cmd.includes(`--instance ${INSTANCE} `),
+    `without this the upgrade pins and installs inside the core package and the real pin never moves — got: ${cmd}`);
+});
+
+await t('the legacy shape still omits --instance, because there is nothing to disambiguate', async () => {
+  const d = { ...makeDeps({ served: '1.19.762' }), selfInstanceRoot: () => require('../scripts/gds/provision-config.js').REPO_ROOT };
+  await R.coreUpgradeInstance(inst({ hosting_shape: 'control-plane', slug: 'cloudbongos', port: 3002 }), d, intent());
+  assert.doesNotMatch(upgradeCall(d), /--instance /, 'a checkout run in place is its own instance');
+});
+
+await t('the version snapshot asks the registry from the instance, not from inside the package', async () => {
+  // Weakest of the three sites — `recommended` is derived from the box's own /version,
+  // so aiming this one wrongly changes no answer today. It is guarded anyway: npm reads
+  // its configuration from the directory it runs in, and an unguarded line is a line
+  // that regresses quietly. Found by mutating each of the three sites in turn; this was
+  // the one no test noticed.
+  const cwds = [];
+  const d = makeDeps({ served: '1.19.760' });
+  d.selfInstanceRoot = () => INSTANCE;
+  d.updateChannel = { ...d.updateChannel, listAvailableVersions: ({ cwd }) => { cwds.push(cwd); return { ok: true, versions: ['1.19.760', '1.19.762'] }; } };
+  await R.snapshotCoreVersions(inst({ hosting_shape: 'control-plane', slug: 'cloudbongos', port: 3002 }), d);
+  assert.deepEqual(cwds, [INSTANCE]);
+});
+
+await t('the PREVIEW aims at the instance too — a dry run of the wrong directory is the lie', async () => {
+  // This is the shape that made the defect dangerous rather than merely broken: dry-run
+  // against the core package and upgrade.js reports `(none) → <target>` with green
+  // pre-flight ticks, so the owner is shown a clean bill of health for a run that will
+  // restart production and roll back. Both legs share one builder; both must aim.
+  const box = { id: 41, slug: 'cloudbongos', port: 3002, hosting_shape: 'control-plane', db_name: 'cloudbongos' };
+  const selfRoot = () => INSTANCE;
+  const move = R.upgradeInvocation(box, '1.19.922', { privileged: true, selfRoot });
+  const peek = R.upgradeInvocation(box, '1.19.922', { privileged: true, dryRun: true, selfRoot });
+  assert.ok(peek.cmd.includes(`--instance ${INSTANCE} `), `the preview names its target — got: ${peek.cmd}`);
+  assert.equal(move.instanceDir, peek.instanceDir, 'and it is the same target the move would take');
+  assert.equal(peek.instanceDir, INSTANCE);
+});
+
+await t('an unreadable installed version is a REFUSAL, not a skipped channel check', () => {
+  // Fail-closed. This is the guard that would have caught the directory bug on the
+  // first press instead of after four live restarts.
+  const f = R.targetFault('1.19.760', ['1.19.758', '1.19.760'], null, 'patch', () => true);
+  assert.match(f, /could not read the core version installed/);
+  assert.match(f, /cannot be bounded by the 'patch' channel/);
+});
+
+await t('the runner refuses, and runs NOTHING, when it cannot see where the instance is', async () => {
+  const d = makeDeps({ served: '1.19.762' });
+  d.readInstalledCoreVersion = () => null;
+  const r = await R.coreUpgradeInstance(inst({ hosting_shape: 'control-plane', slug: 'cloudbongos', port: 3002 }), d, intent());
+  assert.equal(r.ok, false);
+  assert.match(r.error, /could not read the core version installed/);
+  assert.equal(d.ranWith.filter((c) => /upgrade\.js/.test(c.cmd)).length, 0, 'the box was not touched');
+});
+
 console.log(`\ncore_upgrade_runner: ${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);