@bongos/core 1.21.85 → 1.21.86

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.85",
-  "core_contract": "1.21.85",
-  "source_commit": "8a47b19700478214f214b9df7bbfc4cd5ed93958",
+  "core_version": "1.21.86",
+  "core_contract": "1.21.86",
+  "source_commit": "7183f6e501a4de2ea256ffa4c2d19ccc62d7fdc1",
   "source_ref": "HEAD",
-  "built_at": "2026-10-09T04:31:08.324Z",
+  "built_at": "2026-10-09T04:48:08.126Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 590,
     "agent_docs_stubbed": 28,
-    "functional_verbatim": 2997,
+    "functional_verbatim": 2998,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3616,
-  "tree_sha256": "22dc94ef353678e33bf64bb41ca709aa63dc8f29cc4bebcd10a09a84f2dc32c9",
+  "file_count": 3617,
+  "tree_sha256": "391c304f1f86515a2c812e6764e83ba98b5fe6a67757909baf15d8e88009694b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2327,7 +2327,7 @@
     {
       "path": "docs/architecture.md",
       "mode": "0000644",
-      "sha256": "5236bf63df238c4b93e515a9982e76e0908382d049bf38035b5bda2a3ceda11b"
+      "sha256": "0dac6b0ee55d7836cf6352c695f592000bfd61d0c3ec06d9c17d37b476b1134a"
     },
     {
       "path": "docs/branding-contract.md",
@@ -2862,7 +2862,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "cbcee180651b88158a4cc173e12c3f73ee842743bcaf9e13629d5ef96ee26e56"
+      "sha256": "007f5683bb299be37f78f220958ae14bb8a8069fc59b81cc6fb94a12c5b3712f"
     },
     {
       "path": "docs/modules-contract.md",
@@ -10097,12 +10097,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "2784cf3cf476fda15614a347da7e556824a63f50a49cbb74323ceeec704c4b8e"
+      "sha256": "9d3ecc5f558e51dc8e4e66a6f3f0a6e9773e517ce9571ae4ec130b33128536ff"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "8fe03b497ac409587e5ded79331fb0ff035d19052cb7c575daf50f07fe8439ee"
+      "sha256": "ce90ad007650b7bcf0705bf0743acf66507496e0a043d7d6c2d9b84795b94f9b"
     },
     {
       "path": "public-docs/index.html",
@@ -10122,7 +10122,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "24198ec47220ec2534ed8d6bf187965bf03d9044831ac3eaa50fd45ea141959d"
+      "sha256": "99cc3e08c1384339c868c499061c081eade1bcb0a996c47d3e644066d22ca536"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -12137,7 +12137,7 @@
     {
       "path": "src/bongos/module-store.js",
       "mode": "0000644",
-      "sha256": "373a0ff03c6644ea622ff859edfe9003fcfa94ea7eb5ca937059865c3eeb317f"
+      "sha256": "c45fffd2d1320cfadd2177421e8b58643676a71fa1bac7a01e4219c60bfe20b1"
     },
     {
       "path": "src/bongos/module-submissions.js",
@@ -12292,7 +12292,7 @@
     {
       "path": "src/bongos/routes/modules.js",
       "mode": "0000644",
-      "sha256": "469a276bc6293c5148288021775d9d5ceca6b81e452533f02e36fbd9e71702dd"
+      "sha256": "aea0a0f28621500bee51e4fec8e794139cf90c3360fdc55caecbbd5a5fc82b69"
     },
     {
       "path": "src/bongos/routes/my-sessions.js",
@@ -12372,7 +12372,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "901e1e5ef994837bd4ae48f226af1cd104c34a0dd993383c7980eca13bc61d2f"
+      "sha256": "2fd52ee0afe6fc9ade992a558ebb0fc3ad5904f876f7c5093dd60ea5d201b448"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -15754,6 +15754,11 @@
       "mode": "0000644",
       "sha256": "43828c1a95652180d558e7676cc2053d0599a61c0edf4cd1ab100820fc7de493"
     },
+    {
+      "path": "tests/module_store_instance_root.mjs",
+      "mode": "0000644",
+      "sha256": "aa66cdb054eeaef8c3c8babf5238f029d13b668a45a97230efe5f8cfa8908d48"
+    },
     {
       "path": "tests/module_store_listing.mjs",
       "mode": "0000644",

package/docs/architecture.md

@@ -291,7 +291,7 @@ Bongos views: `claimable_tasks` (rebuilt in 006 to use SELECT t.*; rebuilt again
 - Own-scoped session self-service ([ADR 0206](adr/0206-own-scoped-session-revocation-no-absolute-ceiling.md), task 1003341), in [`src/bongos/routes/my-sessions.js`](../src/bongos/routes/my-sessions.js): `GET /me/sessions` (every live session on the caller's own account — source, user agent, created/last-used/expires, a `current` flag; the token value is never selected), `POST /me/sessions/revoke` (`{session_id}` — one of your own; a miss answers `revoked: 0` so a stranger's id cannot be probed) and `POST /me/sessions/revoke-all` (sign out everywhere, the requesting session included). All three gate on `requireBuilder` alone and key every statement on `req.builder.id` — an account is never named in the query, body or path. They exist because a bearer refreshes to `now()+24h` on every call, so a leaked one never expires, and the cross-builder pair (`POST /auth/revoke`, `/auth/revoke-all`, both still gated on the admin `auth.session.revoke` atom) needed an Archon the victim might not have. Surfaced in the hall at Settings → Active sessions.
 - Authenticated CLI/web: `GET /me` (returns `rank`), `GET /versions[/progress]`, `GET /tasks[?version=&status=&kind=&discipline=]`, `GET /tasks/claimable[?version=&discipline=]`, `GET /tasks/:id`, `POST /tasks` (accepts `discipline` + `criterion_ids`; **metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)), `PATCH /tasks/:id` (supports `parent_task_id`, `kind`, `discipline`, `goal_id` — (re)assign the task's goal; must be a goal in the task's own version, task 1763; **metic+**), `POST /tasks/:id/promote` (**metic+**), `POST /claims`, `POST /claims/:id/resolve`, `POST /cost`.
 - Criterion rollup + task↔criterion links ([ADR 0025](adr/0025-structured-criterion-task-link.md), [#435](https://example.com/builders#/task/435)/[#438](https://example.com/builders#/task/438)): `GET /versions/:id/progress` rolls up each done-when criterion → its gating tasks (via `task_criteria`) → live status counts + the not-yet-shipped `remaining[]` + `unattributed_tasks` (the read behind the `/status` skill, in `src/bongos/done-when.js criterionProgress`). The link CRUD mirrors the dependency endpoints: `GET /tasks/:id/criteria`, `POST /tasks/:id/criteria` (**metic+** — [ADR 0090](adr/0090-metic-task-authoring.md)) and `DELETE /tasks/:id/criteria/:criterionId` (**metic+**). A criterion ref is a numeric `done_when_criteria.id`, a positional `"Cn"` token, or a `criterion_id` slug, resolved against the task's version (`POST /tasks` links at create time so `/status` counts the task with no backfill).
-- Module store publish (ADR 0338 D1, task 1004271): `POST /store/modules/:key/versions` (`requireBuilder` + `requirePermission('module.submit')`, Metic floor). The body is the raw gzip tarball `bongos module publish` builds (own `express.raw` parser, 5 MB cap; 16 MB / 2000 files unpacked). `scripts/gds/module-artifact.js` re-verifies every hash and the publish gate, then `src/bongos/module-store.js` keeps the file under `var/module-store/` and inserts the `store_module_versions` row in one transaction. The first publish makes the caller the author; later versions are author-only, newer than the last and never overwritten; a delisted key takes none.
+- Module store publish (ADR 0338 D1, task 1004271): `POST /store/modules/:key/versions` (`requireBuilder` + `requirePermission('module.submit')`, Metic floor). The body is the raw gzip tarball `bongos module publish` builds (own `express.raw` parser, 5 MB cap; 16 MB / 2000 files unpacked). `scripts/gds/module-artifact.js` re-verifies every hash and the publish gate, then `src/bongos/module-store.js` keeps the file under the INSTANCE root's `var/module-store/` (`MODULE_STORE_DIR` overrides; never inside the installed core package, which every upgrade replaces, and a boot move carries files from that old path, task 1004399) and inserts the `store_module_versions` row in one transaction. The first publish makes the caller the author; later versions are author-only, newer than the last and never overwritten; a delisted key takes none.
 - Module store install (ADR 0338 D1, task 1003785), all `requireBuilder` and own-scoped (the holder is the caller): `POST /store/modules/:key/acquire` (`{version?}`; grants a free entitlement — no price row, or a zero price, is free — or `402 payment_required` for a priced module; refuses a delisted one), `GET /store/modules/:key/versions/:version/tarball` (served only to a live entitlement holder; `X-Tarball-Sha256`), `POST /store/modules/:key/acquired` (`{version}` → `recordAcquired`). Read side in `src/bongos/module-store.js` (`resolveAcquirable`, `isFreePrice`, `versionArtifactFile`). No channel check yet (tasks 1003815, 1003805). `bongos module update` (task 1003786) reuses the same three calls; the acquire route reads price only for a caller with no entitlement, so a holder is never charged again.
 - Module store delist (ADR 0338 D2, task 1003797): `POST /store/modules/:key/delist` (`requireBuilder` + `requirePermission('module.delist')`, Metic floor, granted by `government_022`; strict body `{reason}`, reason required, recorded by the audit middleware). Sets `store_modules.status='delisted'` and `delisted_at` — one-way, no relist route. Every store read already refuses a delisted key (acquire, tarball, acquired, publish), while `GET /store/modules/latest` still answers with the status so `bongos upgrade` warns the holder. `GET /modules` sets `store_delisted` on an instance-tree module the store delisted (hall pill "delisted · no more updates"), and `bongos module list` marks it DELISTED (fail-soft store check, instance modules only). Never revokes an entitlement, never reaches an installed copy, never writes a score (ADR 0359). 404 unknown key, 409 `already_delisted`.
 - Server-mediated branch publish (ADR 0055 / [#1025](https://example.com/builders#/task/1025) — lets a checkout with no GitHub push credential ship). Owner-gated like ship: `POST /tasks/:id/publish-branch` (`requireBuilder` + `gateTaskOwnership`; own 32 MB json parser for the base64 thin-bundle body, 20 MB decoded cap; the server pushes the branch + opens the PR + auto-merges with a server-side push credential — a **GitHub App** installation token (short-lived, repo-scoped; preferred, [ADR 0055](adr/0055-server-mediated-branch-publish.md) update / task 1028) or the `GITHUB_PUSH_TOKEN` PAT fallback; `503 push_unconfigured` when neither is set; `400 tip_mismatch` if the bundle tip ≠ the claimed `head_sha`) and `GET /tasks/:id/publish-status?branch=…` (polls PR + deploy-prod state derived live from GitHub). `branch` is optional: without it the server finds the task's own PR by its `task <id>: …` title, and the answer names the `branch` it used and its `branch_source` (`query` / `task_pr`, or `null` with a `branch_hint` when there is no such PR) — never a `400` (task 1003764). When the PR is still open it also carries `merge_driver`, whose `reason` says why it has not merged; on a red PR `failing_tests` names the failing unit tests (read from the `unit-report` commit status the `unit` workflow posts) and `checks_unreadable: true` says the check list is blind because the App lacks `Checks: read` — so an empty `checks[]` is never read as "nothing failed" (task 1003988, ADR 0301). Because the server's credential is the PR's AUTHOR, publish also **assigns the PR to the task's claim holder** and names them in the body (`modules/lifecycle/pr-assign.js`, task 1003991) — best-effort: the 201 carries `pr_assignee` (the login, or `null` when GitHub would not assign it) and a failed assignment never fails the publish. `ship.js` uses these in `ci` mode only when `pushVia()` resolves to server (no authenticated `gh` on the machine, or `<PREFIX>_PUSH_VIA_SERVER=1`); a machine with `gh` keeps the local push path unchanged. Implementation in `src/bongos/github-push.js`.

package/docs/module-api-changelog.md

@@ -3002,5 +3002,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.83 with no explicit bump. run 37876887587. (task 1002620)
   1.21.85 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.84 with no explicit bump. run 37884200093. (task 1002620)
+  1.21.86 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.85 with no explicit bump. run 37885516955. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.85",
+  "version": "1.21.86",
   "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/release-notes.json

@@ -9336,5 +9336,11 @@
       "id": "1004379",
       "text": "A page tweak that passed its grade and is waiting for its artist no longer reports itself as a failed grade: the closing card, the PR description and the credits line now all say it passed and is waiting for the artist's appro"
     }
+  ],
+  "1.21.86": [
+    {
+      "id": "1004399",
+      "text": "Published module packages are now kept in the project's own data folder instead of inside the installed core, so a core upgrade no longer deletes them; any already stored in the old place are moved over when the server starts."
+    }
   ]
 }

package/src/bongos/module-store.js

@@ -8,9 +8,8 @@
 //   1. stageArtifact — write the tarball under the store dir (a temp name first;
 //      commitArtifact moves it into place inside step 2's transaction). ADR 0338 lets the
 //      store keep tarballs on the control plane's disk while volume is small, so it
-//      does: <MODULE_STORE_DIR or var/module-store>/<key>/<key>-<version>.tgz. Outside
-//      the git tree, like var/task-visuals, so a deploy's `git reset --hard` never
-//      wipes it.
+//      does: <MODULE_STORE_DIR or <instance root>/var/module-store>/<key>/<key>-<version>.tgz
+//      (see storeDirFor for why the INSTANCE root, task 1004399).
 //   2. publishVersion — one transaction over the registry tables (core_257): create
 //      the store_modules row on a key's first publish (the publisher becomes its
 //      author), refuse anyone else's key, refuse a delisted key (ADR 0338 D2: delisting
@@ -26,9 +25,105 @@ const crypto = require('node:crypto');
 const { parseVersion, cmp } = require('../module-loader/semver');
 const { KEY_RE } = require('../module-loader/manifest-schema');
 
+// Where the store lives: <INSTANCE ROOT>/var/module-store (task 1004399).
+//
+// THE BUG THIS FIXES. This used to be path.join(__dirname, '..', '..', 'var',
+// 'module-store') — the CORE root. Right in a single checkout, where core root and
+// instance root are one directory; wrong in the consumer layout, where __dirname is
+// node_modules/@bongos/core/src/bongos, so every published tarball was written INSIDE
+// the installed package and every core upgrade (npm ci replaces it) erased them all,
+// leaving registry rows pointing at nothing. Task 1004381 found and fixed the same
+// failure for task visuals (modules/lifecycle/task-visuals.js); this follows it.
+//
+// MODULE_STORE_DIR stays the override (tests, or an operator who wants the tarballs on
+// another disk). The default store carries a `*` .gitignore, because the instance root
+// is a git checkout whose tree `bongos upgrade` requires to be clean.
+let instanceRootCache;
+function instanceRoot() {
+  if (instanceRootCache === undefined) {
+    try {
+      instanceRootCache = require('../instance-config').resolveInstanceRoot();
+    } catch (e) {
+      // A storage-path lookup must never take the server down: fall back to the
+      // historical location, which is right in a single checkout.
+      instanceRootCache = path.join(__dirname, '..', '..');
+    }
+  }
+  return instanceRootCache;
+}
+
+// PURE given its inputs, so the consumer-layout test can prove where it lands.
+function storeDirFor({ env = process.env, root } = {}) {
+  if (env.MODULE_STORE_DIR) return env.MODULE_STORE_DIR;
+  return path.join(root || instanceRoot(), 'var', 'module-store');
+}
 
 function storeDir() {
-  return process.env.MODULE_STORE_DIR || path.join(__dirname, '..', '..', 'var', 'module-store');
+  return storeDirFor();
+}
+
+// The old, in-package location. Read only by migrateLegacyStore.
+function legacyStoreDir() {
+  return path.join(__dirname, '..', '..', 'var', 'module-store');
+}
+
+// mkdir -p the store and, for the DEFAULT store, drop a `*` .gitignore in it so the
+// tarballs never show as untracked in the instance's git tree (an untracked path
+// there halts the next `bongos upgrade` pre-flight). An override is the operator's
+// own directory and is left bare. Idempotent; the .gitignore write is best-effort.
+const DIR_GITIGNORE = '# Module store tarballs (task 1004399): runtime data, never committed.\n*\n';
+async function ensureStoreDir(dir, { env = process.env } = {}) {
+  await fs.promises.mkdir(dir, { recursive: true });
+  if (env.MODULE_STORE_DIR || path.resolve(dir) !== path.resolve(storeDirFor({ env }))) return;
+  try {
+    await fs.promises.writeFile(path.join(dir, '.gitignore'), DIR_GITIGNORE, { flag: 'wx' });
+  } catch { /* EEXIST is the steady state; anything else is non-fatal */ }
+}
+
+// One-time boot move: every tarball still at the old in-package path moves into the
+// instance store, keeping its <key>/<key>-<version>.tgz place — the registry stores
+// artifact_path RELATIVE to the store dir, so the rows stay right with no data
+// migration. Only well-formed artifacts move (a key directory matching KEY_RE holding
+// "<key>-<version>.tgz"); a leftover .partial is not one. A no-op when both paths are
+// the same directory (a single checkout), the old one is absent, or MODULE_STORE_DIR
+// is set (the old code honoured it too, so nothing was ever written to the legacy
+// path). Never overwrites, never throws: returns { moved, skipped, failed }.
+async function migrateLegacyStore({ from, to = storeDir(), env = process.env } = {}) {
+  const out = { moved: 0, skipped: 0, failed: 0 };
+  if (from === undefined) {
+    if (env.MODULE_STORE_DIR) return out;
+    from = legacyStoreDir();
+  }
+  if (path.resolve(from) === path.resolve(to)) return out;
+  let keys;
+  try { keys = await fs.promises.readdir(from); } catch { return out; }
+  for (const key of keys.filter((k) => KEY_RE.test(k))) {
+    let names;
+    try { names = await fs.promises.readdir(path.join(from, key)); } catch { continue; }
+    for (const name of names) {
+      const m = name.startsWith(`${key}-`) && name.endsWith('.tgz') ? name.slice(key.length + 1, -4) : null;
+      if (!m || !parseVersion(m)) continue;
+      const src = path.join(from, key, name);
+      const dest = artifactPath(key, m, { dir: to });
+      try {
+        try { await fs.promises.access(dest); out.skipped += 1; continue; } catch { /* absent: move it */ }
+        await ensureStoreDir(to, { env });
+        await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+        try {
+          await fs.promises.rename(src, dest);
+        } catch (err) {
+          if (!err || err.code !== 'EXDEV') throw err;
+          // Another filesystem: copy, then remove the original.
+          await fs.promises.copyFile(src, dest, fs.constants.COPYFILE_EXCL);
+          await fs.promises.unlink(src);
+        }
+        out.moved += 1;
+      } catch {
+        out.failed += 1;
+      }
+    }
+  }
+  return out;
 }
 
 // Where one version's tarball lives. Key and version are re-validated here so this
@@ -48,6 +143,7 @@ function artifactPath(key, version, { dir = storeDir() } = {}) {
 // Async throughout so a multi-MB write never holds the web process's event loop.
 async function stageArtifact(buf, { key, version, dir = storeDir() } = {}) {
   const final = artifactPath(key, version, { dir });
+  await ensureStoreDir(dir);
   await fs.promises.mkdir(path.dirname(final), { recursive: true });
   const tmp = `${final}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.partial`;
   await fs.promises.writeFile(tmp, buf, { flag: 'wx', mode: 0o640 });
@@ -276,5 +372,5 @@ function versionArtifactFile(row, { dir = storeDir() } = {}) {
 module.exports = {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
   isFreePrice, resolveAcquirable, resolveReadable, publishedVersionSet, latestVersions, versionArtifactFile,
-  delistModule, delistedKeySet,
+  delistModule, delistedKeySet, storeDir, storeDirFor, migrateLegacyStore,
 };

package/src/bongos/routes/modules.js

@@ -95,7 +95,7 @@ const { checkEntitlement, listEntitlements, grantEntitlement, recordAcquired } =
 const {
   stageArtifact, commitArtifact, removeArtifact, relativeArtifactPath, publishVersion,
   resolveAcquirable, resolveReadable, publishedVersionSet, latestVersions, versionArtifactFile,
-  delistModule, delistedKeySet,
+  delistModule, delistedKeySet, migrateLegacyStore,
 } = require('../module-store');
 const {
   isOptedOut, setReporting, installReportError, errorCountError, recordInstallReport, recordErrorCount,
@@ -210,6 +210,12 @@ function contributeModuleDesk() {
 module.exports = function buildModulesRouter() {
   contributeModuleRechecksToDocket();
   contributeModuleDesk();
+  // Task 1004399: carry tarballs written inside the installed core package (the old
+  // store path) into the instance store before the next upgrade erases them. Async and
+  // never fatal; a no-op in a single checkout, where the two paths are one directory.
+  migrateLegacyStore()
+    .then((r) => { if (r.moved || r.failed) log.info(r, 'module store: moved from the old in-package store'); })
+    .catch((err) => log.error({ err: err && err.message }, 'module store: boot move failed'));
   const router = express.Router();
   // Checked how-tos by "key@version:tarball_sha256". Per router, so a test's fresh
   // router starts empty.

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.85'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.86'; // 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('discord'); log.info('mounted');

package/tests/module_store_instance_root.mjs

@@ -0,0 +1,163 @@
+// tests/module_store_instance_root.mjs
+//
+// Task 1004399: published module tarballs must be stored under the INSTANCE root,
+// never inside the installed core package, so they survive a core upgrade. The
+// sibling of tests/task_visuals_instance_root.mjs (task 1004381), which found the
+// same bug in the task-visuals store.
+//
+// This builds a real consumer tree in a temp dir: a fake installed core package
+// carrying the REAL src/bongos/module-store.js, with its three core requires
+// re-exporting the real files, then proves, through that installed copy:
+//   1. the store is the instance's var/module-store, not inside the package;
+//   2. a published tarball survives the package being deleted and reinstalled,
+//      and the registry row's artifact_path still resolves to it;
+//   3. the boot move carries tarballs from the old in-package path, keeping their
+//      <key>/ place, once, without overwriting, skipping anything not an artifact,
+//      and is a no-op in a single checkout or under MODULE_STORE_DIR;
+//   4. the store keeps the instance's git tree clean (upgrade pre-flight).
+//
+// Run:  node tests/module_store_instance_root.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const REAL = (...p) => path.join(REPO, 'src', ...p);
+
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e && e.stack ? e.stack.split('\n').slice(0, 3).join('\n        ') : e}`); }
+}
+
+const TGZ = Buffer.from('1f8b0800000000000003', 'hex');
+
+const WORK = fs.mkdtempSync(path.join(os.tmpdir(), 'ms-instance-root-'));
+const CONSUMER = path.join(WORK, 'consumer');
+const CORE = path.join(CONSUMER, 'node_modules', '@bongos', 'core');
+const reexport = (real) => `module.exports = require(${JSON.stringify(real)});\n`;
+
+// "npm ci": (re)install the fake core package — the real store, its requires stubbed through.
+function installCore() {
+  fs.rmSync(CORE, { recursive: true, force: true });
+  fs.mkdirSync(path.join(CORE, 'src', 'bongos'), { recursive: true });
+  fs.mkdirSync(path.join(CORE, 'src', 'module-loader'), { recursive: true });
+  fs.copyFileSync(REAL('bongos', 'module-store.js'), path.join(CORE, 'src', 'bongos', 'module-store.js'));
+  fs.writeFileSync(path.join(CORE, 'src', 'module-loader', 'semver.js'), reexport(REAL('module-loader', 'semver.js')));
+  fs.writeFileSync(path.join(CORE, 'src', 'module-loader', 'manifest-schema.js'), reexport(REAL('module-loader', 'manifest-schema.js')));
+  fs.writeFileSync(path.join(CORE, 'src', 'instance-config.js'), reexport(REAL('instance-config.js')));
+}
+// A fresh require of the INSTALLED copy (a restarted server).
+function loadInstalled() {
+  const p = path.join(CORE, 'src', 'bongos', 'module-store.js');
+  delete require.cache[p];
+  return require(p);
+}
+const inside = (child, parent) => {
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+
+fs.mkdirSync(CONSUMER, { recursive: true });
+installCore();
+delete process.env.MODULE_STORE_DIR;
+process.env.BONGOS_INSTANCE_ROOT = CONSUMER;
+
+await t('consumer layout: the store is <instance>/var/module-store, NOT inside the core package', () => {
+  const ms = loadInstalled();
+  const dir = ms.storeDir();
+  assert.equal(path.resolve(dir), path.join(CONSUMER, 'var', 'module-store'));
+  assert.ok(!inside(dir, CORE), `store ${dir} is inside the core package ${CORE}`);
+});
+
+await t('MODULE_STORE_DIR still overrides', () => {
+  const ms = loadInstalled();
+  assert.equal(ms.storeDirFor({ env: { MODULE_STORE_DIR: '/elsewhere/x' } }), '/elsewhere/x');
+});
+
+await t('the checkout copy resolves the same way: an instance root, or the override', () => {
+  const { storeDir, storeDirFor } = require('../src/bongos/module-store.js');
+  assert.equal(storeDirFor({ env: {}, root: '/inst' }), path.join('/inst', 'var', 'module-store'));
+  assert.equal(path.resolve(storeDir()), path.join(CONSUMER, 'var', 'module-store'));
+});
+
+let row;
+await t('a published tarball survives a core upgrade (package deleted and reinstalled)', async () => {
+  const ms = loadInstalled();
+  const staged = await ms.stageArtifact(TGZ, { key: 'weather', version: '1.2.0' });
+  await ms.commitArtifact(staged);
+  row = { module_key: 'weather', version: '1.2.0', artifact_path: ms.relativeArtifactPath(staged.final) };
+  assert.equal(row.artifact_path, 'weather/weather-1.2.0.tgz');
+  installCore(); // the upgrade
+  const after = loadInstalled();
+  const file = after.versionArtifactFile(row);
+  assert.ok(fs.existsSync(file), 'the tarball is gone after the upgrade');
+  assert.deepEqual(fs.readFileSync(file), TGZ);
+});
+
+await t('the default store carries a * .gitignore, so the instance git tree stays clean', () => {
+  const gi = fs.readFileSync(path.join(CONSUMER, 'var', 'module-store', '.gitignore'), 'utf8');
+  assert.match(gi, /^\*$/m);
+  const init = spawnSync('git', ['init', '-q'], { cwd: CONSUMER, encoding: 'utf8' });
+  if (init.status !== 0) { console.log('        (git unavailable: .gitignore content checked only)'); return; }
+  fs.writeFileSync(path.join(CONSUMER, '.gitignore'), 'node_modules/\n');
+  const st = spawnSync('git', ['status', '--porcelain', '--untracked-files=all', '--', 'var'], { cwd: CONSUMER, encoding: 'utf8' });
+  assert.equal(st.status, 0);
+  assert.equal(st.stdout.trim(), '', `var/ shows in git status:\n${st.stdout}`);
+});
+
+await t('boot move: tarballs at the old in-package path move into the instance store, once', async () => {
+  const ms = loadInstalled();
+  const legacy = path.join(CORE, 'var', 'module-store');
+  fs.mkdirSync(path.join(legacy, 'notes'), { recursive: true });
+  fs.mkdirSync(path.join(legacy, 'weather'), { recursive: true });
+  fs.mkdirSync(path.join(legacy, 'Bad Key'), { recursive: true });
+  fs.writeFileSync(path.join(legacy, 'notes', 'notes-0.1.0.tgz'), TGZ);
+  fs.writeFileSync(path.join(legacy, 'notes', 'notes-0.1.0.tgz.123.456.ab.partial'), 'half');
+  fs.writeFileSync(path.join(legacy, 'notes', 'other-0.1.0.tgz'), 'not this key');
+  fs.writeFileSync(path.join(legacy, 'Bad Key', 'Bad Key-1.0.0.tgz'), 'x');
+  // weather 1.2.0 already exists in the new store: kept, never overwritten.
+  fs.writeFileSync(path.join(legacy, 'weather', 'weather-1.2.0.tgz'), 'legacy copy');
+
+  const r = await ms.migrateLegacyStore();
+  assert.deepEqual(r, { moved: 1, skipped: 1, failed: 0 });
+  const store = ms.storeDir();
+  assert.deepEqual(fs.readFileSync(path.join(store, 'notes', 'notes-0.1.0.tgz')), TGZ);
+  assert.ok(!fs.existsSync(path.join(legacy, 'notes', 'notes-0.1.0.tgz')), 'moved, not copied');
+  assert.deepEqual(fs.readFileSync(path.join(store, 'weather', 'weather-1.2.0.tgz')), TGZ, 'the existing file is not overwritten');
+  assert.ok(!fs.existsSync(path.join(store, 'notes', 'notes-0.1.0.tgz.123.456.ab.partial')), 'a .partial is not an artifact');
+  assert.ok(!fs.existsSync(path.join(store, 'Bad Key')), 'a directory that is not a module key is left alone');
+
+  // A moved tarball is served through its unchanged registry row.
+  const moved = ms.versionArtifactFile({ module_key: 'notes', version: '0.1.0', artifact_path: 'notes/notes-0.1.0.tgz' });
+  assert.ok(fs.existsSync(moved));
+
+  const again = await ms.migrateLegacyStore();
+  assert.equal(again.moved, 0, 'the second boot moves nothing');
+});
+
+await t('boot move is a no-op in a single checkout and under MODULE_STORE_DIR', async () => {
+  const ms = loadInstalled();
+  const dir = fs.mkdtempSync(path.join(WORK, 'same-'));
+  fs.mkdirSync(path.join(dir, 'notes'));
+  fs.writeFileSync(path.join(dir, 'notes', 'notes-0.2.0.tgz'), TGZ);
+  assert.deepEqual(await ms.migrateLegacyStore({ from: dir, to: dir }), { moved: 0, skipped: 0, failed: 0 });
+  assert.deepEqual(await ms.migrateLegacyStore({ env: { MODULE_STORE_DIR: dir } }), { moved: 0, skipped: 0, failed: 0 });
+  assert.ok(fs.existsSync(path.join(dir, 'notes', 'notes-0.2.0.tgz')));
+});
+
+await t('the modules router runs the boot move when it is built', () => {
+  const src = fs.readFileSync(path.join(REPO, 'src', 'bongos', 'routes', 'modules.js'), 'utf8');
+  const body = src.slice(src.indexOf('module.exports = function buildModulesRouter('));
+  assert.ok(body.indexOf('migrateLegacyStore()') > 0 && body.indexOf('migrateLegacyStore()') < body.indexOf('express.Router()'));
+});
+
+fs.rmSync(WORK, { recursive: true, force: true });
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) process.exitCode = 1;