@bongos/core 1.19.748 → 1.19.750

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.748",
-  "core_contract": "1.19.748",
-  "source_commit": "c7239277baa5d7123d6e0d1a60749b6aba472f70",
+  "core_version": "1.19.750",
+  "core_contract": "1.19.750",
+  "source_commit": "70d84110fa87578e522d55cec0236a0719f25767",
   "source_ref": "HEAD",
-  "built_at": "2026-09-15T21:40:07.956Z",
+  "built_at": "2026-09-15T22:23:58.558Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 482,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2109,
+    "functional_verbatim": 2110,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2616,
-  "tree_sha256": "f52311a51ab40e147838cb38e88a7327f02df848a8bba552a509cc0185fcdc6b",
+  "file_count": 2617,
+  "tree_sha256": "a8d1e331aab73c6da3b924d2defdcf6ac1d55f6a9ccfed12c7922e90314e7417",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2507,7 +2507,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "958174405a14b2dae06adc92ccbf638cb3289a38e68b8ebb9c6c314a1479ae40"
+      "sha256": "996dff9026c0402289d079b4a3cab9b437def3df20adbc465c841b5064ff1b48"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2652,7 +2652,7 @@
     {
       "path": "docs/recipes/gds-db-backup.md",
       "mode": "0000644",
-      "sha256": "9f77ee1dd01d47f38679387e0b96a739924056a52f2af2e174a7f52248f4345a"
+      "sha256": "0f2dfdeca8d49a07a0da043eaa9f2b16669228c358cb56a7786c6c59e5e29808"
     },
     {
       "path": "docs/recipes/instance-deploy.md",
@@ -2767,7 +2767,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "3691b017562bde760fbe3ff29a5efb80d886dd770f1187dc4673459871cec513"
+      "sha256": "408b4792ffb869f2fa13201485c1ab5b8306b93996bb75f01b4117de3fd39303"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -7562,12 +7562,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ad67710386b227895b4042eaad4f4461a4435433be5e1eafaf6970118b63a759"
+      "sha256": "f0450a8f923e11ca0b92de0ead3f2b9b49a8c01f721be06ddd2566845a082775"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7ffeb06be165b48faa187f3faa8526b293bc6ccd467ecb6ac7a880036f805ad8"
+      "sha256": "4bc87648a58a6f4b15ffe9f9bda38a0edace87d66e9e319317804d3f1ee347ac"
     },
     {
       "path": "public-docs/index.html",
@@ -7912,7 +7912,7 @@
     {
       "path": "scripts/gds/db-backup-nightly.sh",
       "mode": "0000644",
-      "sha256": "0a4b3490ad5d4724c693053b16af61f6632e4933d18bedbdc5737a84111f03ae"
+      "sha256": "ff4785dbde6a5c52036ce4c4aacca317c62e725f49d3e32201909ec444d85d44"
     },
     {
       "path": "scripts/gds/db-backup-offsite.sh",
@@ -8927,7 +8927,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "7a82fb0cf919e14700ceba718e28da1324df2eab669a847348271c85b2f7bd66"
+      "sha256": "fe3abe00b43163eb1b24dd2da57d4c8fd51194e79bab8a6683355980787a9e8c"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9367,7 +9367,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "fddd61204720aa0027e000d95f5933d756b3ed59befe634229c4492ae50afa5f"
+      "sha256": "de52088bfb2f473ad6960e60ee94153cdf1b74d4634ed4934d22e977988278a9"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10224,6 +10224,11 @@
       "mode": "0000644",
       "sha256": "434130945232d2a6959281070e6dbee31697904b3455fb3fd09f198a64bb0e33"
     },
+    {
+      "path": "tests/db_backup_nightly.mjs",
+      "mode": "0000644",
+      "sha256": "020dc551d105cc4a29e0f9c750a03cd14a91511d3edc47eb6719a1e430461936"
+    },
     {
       "path": "tests/dead_deps.mjs",
       "mode": "0000644",
@@ -12942,12 +12947,12 @@
     {
       "path": "tests/upgrade.mjs",
       "mode": "0000644",
-      "sha256": "def73ab0f532c04df167d77917981eaf7e0dc7e1d2a7e7c85f3f962d7d65ce2a"
+      "sha256": "bcbba7b1c952088f43300405184849bbcbb2da789097fcc4cf38d95441e0c158"
     },
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "c0a96fbdc6a9f851925babfb0857c9a168374c4165c84884f5c4c56c7177dd58"
+      "sha256": "864b9471fcd6bfc41e99fd5356a3124c25d288946326c2797cc2bacb86120d05"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/docs/module-api-changelog.md

@@ -1970,5 +1970,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.746 with no explicit bump. run 35025151628. (task 1002620)
   1.19.748 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.747 with no explicit bump. run 35026862340. (task 1002620)
+  1.19.749 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.748 with no explicit bump. run 35028684745. (task 1002620)
+  1.19.750 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.749 with no explicit bump. run 35030717430. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/gds-db-backup.md

@@ -21,7 +21,7 @@ This closes the **most likely** loss-of-data risks: schema corruption, an accide
 
 - **Filename format:** `<dbname>-<UTC-timestamp>.sql.gz`. UTC is used so the dumps sort chronologically regardless of the droplet's timezone.
 - **Permissions:** dir is `lars:lars 0750`; files are `lars:lars 0640`. No root needed for routine inspection.
-- **Size:** each gzipped dump is well under 1 MB, and 30 days of them fit comfortably — pruning is hygiene, not disk pressure. **The dump excludes `search_chunks` data** (the `/recall` lexical index, migration 103) via `--exclude-table-data=search_chunks` ([#973](https://example.com/builders#/task/973)): it is regenerable derived data — chunked copies of DB prose (already dumped) and repo markdown (already in git) — and dumping its rows roughly duplicated the prose corpus, making it the dump's dominant growth vector. The table schema + GIN indexes are still dumped, so a restore recreates it empty; the index rebuilds from source (see the restore drill below). A size guard in the backup script WARNs to journald if a dump ever exceeds `GDS_BACKUP_WARN_BYTES` (default 25 MiB) — a generous tripwire for unexpected growth from some *other* table.
+- **Size:** each gzipped dump is well under 1 MB, and 30 days of them fit comfortably — pruning is hygiene, not disk pressure. **The dump excludes `search_chunks` data** (the `/recall` lexical index, migration 103) via `--exclude-table-data=search_chunks` ([#973](https://example.com/builders#/task/973)): it is regenerable derived data — chunked copies of DB prose (already dumped) and repo markdown (already in git) — and dumping its rows roughly duplicated the prose corpus, making it the dump's dominant growth vector. The table schema + GIN indexes are still dumped, so a restore recreates it empty; the index rebuilds from source (see the restore drill below). A size guard in the backup script WARNs to journald if a dump ever exceeds `GDS_BACKUP_WARN_BYTES` (default 25 MiB) — a generous tripwire for unexpected growth from some *other* table. A dump is refused (and deleted) only when it is **incomplete** — missing pg_dump's closing `dump complete` line — never for being small: a fresh project's whole database gzips to ~36 KB, and the fixed 1 MiB floor this replaced failed and deleted every project's nightly dump ([task 1003925](https://cloudbongos.com/builders#/task/1003925)). An optional extra size floor can still be set in the unit's environment (see the script).
 
 ## What's scheduled
 

package/docs/recipes/upgrading-the-core.md

@@ -55,7 +55,7 @@ The instance runs on the droplet (co-tenant): systemd `emersonian-circles.servic
 
    > **The pin MUST reach the repo of record, or the bump silently un-does itself** (task 1002712). A pull-deploy instance resets to `origin/main`; a pin that lives only in the working tree is reverted the next time anything lands, and the lockfile change then trips `npm ci`, which reinstalls the OLD core. Nothing errors. cloudbongos.com lost thirteen releases exactly this way — the `core_upgrades` ledger held two successful `auto-subscription (patch)` rows whose result no longer existed on disk, because deploy.sh short-circuits while `HEAD == origin/main` so the upgrade *looks* fine right up until someone else pushes.
    >
-   > `bongos upgrade` now **warns loudly** whenever it leaves the pin uncommitted in a git repo, and `--commit-pin` (optionally `--git-remote <name>`) commits + pushes `package.json` + `package-lock.json` for you. A commit that fails to push is reported as a failure too — deploy.sh resets to the *remote*, so committing locally saves nothing. Verify durability by forcing a deploy tick (`sudo systemctl start <instance>-deploy.service`) and re-reading the pin.
+   > `bongos upgrade` now **warns loudly** whenever it leaves the pin uncommitted in a git repo, and `--commit-pin` (optionally `--git-remote <name>`) commits + pushes `package.json` + `package-lock.json` for you, together with any regenerated API spec, reference and typed client the bump rewrote (task 1003926 — left uncommitted, they made the next upgrade fail its clean-tree pre-flight). A commit that fails to push is reported as a failure too — deploy.sh resets to the *remote*, so committing locally saves nothing. Verify durability by forcing a deploy tick (`sudo systemctl start <instance>-deploy.service`) and re-reading the pin.
 7. **Align the droplet checkout** — the droplet has no deploy key (`git pull` fails; idea 509), so `git bundle` the new commit on the laptop, `scp`, `git fetch <bundle> && git reset --hard FETCH_HEAD`. `node_modules` is already the new version, so no re-`npm ci`; a final restart makes `/version` report the new commit.
 
 ## Auto-rollback on failure (task 2149)

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.748",
+  "version": "1.19.750",
   "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/db-backup-nightly.sh

@@ -130,13 +130,27 @@ mv "$OUT.partial" "$OUT"
 BYTES=$(stat -c '%s' "$OUT")
 echo "[$(date -u +%FT%TZ)] gds-db-backup: wrote ${OUT} (${BYTES} bytes)"
 
-# Min-size sanity guard (incident 2026-07-02, task 1711). pipefail already aborts
-# on a pg_dump error, but this is belt-and-suspenders: a real dump is ~12-20 MB
-# gzipped, so a sub-1-MiB file means an empty/truncated dump slipped through.
-# Fail loudly and delete it so a broken dump can never masquerade as a good one.
-MIN_BYTES="${GDS_BACKUP_MIN_BYTES:-1048576}"
-if [ "$BYTES" -lt "$MIN_BYTES" ]; then
-  echo "[$(date -u +%FT%TZ)] gds-db-backup: ERROR latest dump is only ${BYTES} bytes (< ${MIN_BYTES} floor) — treating as FAILED." >&2
+# Completeness guard (incident 2026-07-02, task 1711; task 1003925). pipefail already
+# aborts on a pg_dump error; this is belt-and-suspenders against a dump cut short. A
+# plain-format dump always closes with pg_dump's own "dump complete" comment (patched
+# servers append a \unrestrict line after it), whatever its size. The fixed 1 MiB floor
+# this replaces was sized for the platform database and failed — and deleted — every
+# valid dump of a small project (~36 KB gzipped). Fail loudly and delete a broken dump
+# so it can never masquerade as a good one.
+DUMP_TAIL=$(gzip -dc "$OUT" 2>/dev/null | tail -n 10) || DUMP_TAIL=''
+FAIL_REASON=''
+case "$DUMP_TAIL" in
+  *'-- PostgreSQL database dump complete'*) ;;
+  *) FAIL_REASON="(${BYTES} bytes) is incomplete — no pg_dump completion line" ;;
+esac
+
+# Optional operator floor. Unset means none: no single size fits every instance.
+MIN_BYTES="${GDS_BACKUP_MIN_BYTES:-0}"
+if [ -z "$FAIL_REASON" ] && [ "$BYTES" -lt "$MIN_BYTES" ]; then
+  FAIL_REASON="is only ${BYTES} bytes (< ${MIN_BYTES} floor)"
+fi
+if [ -n "$FAIL_REASON" ]; then
+  echo "[$(date -u +%FT%TZ)] gds-db-backup: ERROR latest dump ${FAIL_REASON} — treating as FAILED." >&2
   rm -f "$OUT"
   exit 1
 fi

package/scripts/gds/upgrade.js

@@ -157,6 +157,17 @@ function gitTreeClean(instanceDir, run = spawnSync) {
 // Hence: --commit-pin lands it, and its absence WARNS rather than staying quiet.
 const PIN_FILES = ['package.json', 'package-lock.json'];
 
+// The tracked files regenerateApiArtifacts' generators rewrite WHOLE, by generator (task
+// 1003926). Committing only the pin left these dirty, so the NEXT `bongos upgrade` refused
+// its clean-tree pre-flight. They are generated end to end, so once a generator has run
+// their content is its output whatever they held before: committing them can never carry
+// an owner's edit. tests/upgrade_persist_pin.mjs pins this list against both generators.
+const API_ARTIFACT_FILES = {
+  'gen-api-docs.js': ['docs/api/openapi.json', 'docs/api-reference.md', 'docs/routes-permissions.md'],
+  'gen-api-client.js': ['index.mjs', 'index.cjs', 'bongos-client.global.js', 'index.d.ts', 'package.json', 'README.md']
+    .map((f) => `clients/bongos-client/${f}`),
+};
+
 function gitCurrentBranch(instanceDir, run = spawnSync) {
   const r = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: instanceDir, encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return null;
@@ -164,13 +175,17 @@ function gitCurrentBranch(instanceDir, run = spawnSync) {
   return b && b !== 'HEAD' ? b : null;
 }
 
-// Which of the pin files git currently reports as modified.
-function dirtyPinFiles(instanceDir, run = spawnSync) {
-  const r = run('git', ['status', '--porcelain', '--', ...PIN_FILES], { cwd: instanceDir, encoding: 'utf8' });
+// Which of `paths` git currently reports as changed — never a path it was not asked about,
+// and no git call for an empty list (a pathspec of nothing is the whole tree).
+function dirtyPaths(instanceDir, paths, run = spawnSync) {
+  if (!paths.length) return [];
+  const r = run('git', ['status', '--porcelain', '--', ...paths], { cwd: instanceDir, encoding: 'utf8' });
   if (!r || r.error || r.status !== 0) return null; // not a git repo — nothing to persist
-  return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+  return (r.stdout || '').split('\n').map((l) => l.slice(3).trim()).filter((p) => paths.includes(p));
 }
 
+function dirtyPinFiles(instanceDir, run = spawnSync) { return dirtyPaths(instanceDir, PIN_FILES, run); }
+
 // ---- which credential the pin push rides (task 1003081, ADR 0176 follow-up) ----
 //
 // THE BUG THIS EXISTS FOR. A PRIVATE standalone instance's `origin` authenticates with
@@ -285,11 +300,16 @@ function gitSaid(r) {
 // GitHub token over HTTPS (task 1003081); null pushes via `remote`. The result carries
 // `via: 'owner-token'` on the token path and `refused` ('read-only-deploy-key' |
 // 'owner-token') with a plain-sentence `error` when GitHub turned the push away.
-function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false, pushAuth = null },
+// `artifactPaths` (task 1003926) are the generated files this upgrade rewrote; the ones
+// that changed are staged and committed with the pin.
+function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = true, remote = 'origin', dryRun = false, pushAuth = null, artifactPaths = [] },
   run = spawnSync, log = console.log, err = console.error) {
-  const dirty = dirtyPinFiles(instanceDir, run);
-  if (dirty === null) return { applicable: false, reason: 'not a git repo' };
+  const dirtyPins = dirtyPinFiles(instanceDir, run);
+  if (dirtyPins === null) return { applicable: false, reason: 'not a git repo' };
+  const dirtyArtifacts = dirtyPaths(instanceDir, artifactPaths, run) || [];
+  const dirty = [...dirtyPins, ...dirtyArtifacts];
   if (!dirty.length) return { applicable: false, reason: 'pin files already match the repo' };
+  const toStage = [...PIN_FILES, ...dirtyArtifacts];
 
   const branch = gitCurrentBranch(instanceDir, run);
   const target = `HEAD:${branch || 'main'}`;
@@ -314,7 +334,7 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = tru
     err('    On a pull-deploy instance the next push to the repo of record makes deploy.sh');
     err(`    'git reset --hard ${remote}/${branch || 'main'}', which REVERTS this pin and lets npm ci`);
     err(`    reinstall ${fromVersion || 'the previous core'}. Re-run with --commit-pin, or commit + push:`);
-    err(`      ${at} add ${PIN_FILES.map(q).join(' ')} && ${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(target)}`);
+    err(`      ${at} add ${toStage.map(q).join(' ')} &&${at} commit -m ${q(`pin @bongos/core ${toVersion}`)} && ${at} push ${q(remote)} ${q(target)}`);
     return { applicable: true, committed: false, pushed: false, dirty, warned: true };
   }
 
@@ -326,7 +346,7 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = tru
   }
 
   const message = `pin @bongos/core ${toVersion}${fromVersion ? ` (was ${fromVersion})` : ''}`;
-  const add = run('git', ['add', ...PIN_FILES], { cwd: instanceDir, encoding: 'utf8' });
+  const add = run('git', ['add', ...toStage], { cwd: instanceDir, encoding: 'utf8' });
   if (!add || add.error || add.status !== 0) {
     err('  ! could not stage the pin files — commit + push them by hand or the next deploy reverts this bump.');
     return { applicable: true, committed: false, pushed: false, dirty, error: 'git add failed' };
@@ -572,7 +592,7 @@ function resolveInstanceDb({ instanceDir }, run = spawnSync) {
 function regenerateApiArtifacts({ instanceDir, coreRoot }, run = spawnSync, fsImpl = fs) {
   const env = { ...process.env, BONGOS_INSTANCE_ROOT: instanceDir };
   const ran = [];
-  for (const gen of ['gen-api-docs.js', 'gen-api-client.js']) {
+  for (const gen of Object.keys(API_ARTIFACT_FILES)) {
     const script = path.join(coreRoot, 'scripts', 'gds', gen);
     if (!fsImpl.existsSync(script)) return { ok: false, ran, reason: `${gen} not found in core (${coreRoot})` };
     const r = run(process.execPath, [script], { cwd: instanceDir, env, stdio: 'inherit' });
@@ -1185,9 +1205,11 @@ async function runUpgrade(opts, deps = {}) {
   // 5b. regenerate the per-instance API artifacts (OpenAPI spec + typed client) from the
   // new core's routes — the claude-materialize sibling (task 2051). Best-effort: a regen
   // hiccup is a warning, not a failed bump (the next ship's fitness gate refreshes them).
+  let regenArtifacts = [];
   if (!opts.skipRegenDocs) {
     const coreRoot = path.join(instanceDir, 'node_modules', CORE_PKG);
     const regen = (deps.regenerateApiArtifacts || regenerateApiArtifacts)({ instanceDir, coreRoot }, run);
+    regenArtifacts = (regen.ran || []).flatMap((gen) => API_ARTIFACT_FILES[gen] || []);
     if (regen.ok) log(`  ✓ regenerated API docs + typed client from core ${targetVersion}`);
     else err(`  ! API-artifact regen incomplete (${regen.reason}) — ran ${regen.ran.join(', ') || 'nothing'}; the next ship's fitness gate refreshes them.`);
     // 5c. regenerate the whole-file navigation docs (repo-map + session-index) from the new
@@ -1301,7 +1323,8 @@ async function runUpgrade(opts, deps = {}) {
   // actually coming: --commit-pin without --pin-no-push, not a dry run, and the pin
   // files really are dirty. Nothing reads a credential it will not spend (task 1003081).
   const remote = opts.gitRemote || 'origin';
-  const pushComing = !!opts.commitPin && !opts.pinNoPush && !dryRun && (dirtyPinFiles(instanceDir, run) || []).length > 0;
+  const pushComing = !!opts.commitPin && !opts.pinNoPush && !dryRun
+    && ((dirtyPinFiles(instanceDir, run) || []).length > 0 || (dirtyPaths(instanceDir, regenArtifacts, run) || []).length > 0);
   const pushAuth = pushComing ? await (deps.resolvePinPushAuth || resolvePinPushAuth)({ instanceDir, remote }, deps, run) : null;
   const pin = persistPin({
     instanceDir,
@@ -1312,6 +1335,7 @@ async function runUpgrade(opts, deps = {}) {
     remote,
     dryRun: opts.dryRun,
     pushAuth,
+    artifactPaths: regenArtifacts,
   }, run, log, err);
 
   const ok = versionOk && healthOk !== false && servedOk !== false;
@@ -1394,7 +1418,7 @@ async function main(argv = process.argv.slice(2)) {
 module.exports = {
   runUpgrade, parseArgs, main, rollback,
   versionFromTgzPath, versionFromDep, readInstalledCoreVersion, readPinnedCoreVersion, writePin, writeRegistryPin, restorePin,
-  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, preflightDbIdentity,
+  vendorTarball, gitTreeClean, persistPin, dirtyPinFiles, gitCurrentBranch, PIN_FILES, API_ARTIFACT_FILES, preflightDbIdentity,
   resolveInstanceDb, preflightModules, reportModulePreflight, npmInstall, runMigrate, regenerateApiArtifacts, regenerateNavDocs, NAV_WHOLE_FILE_GENERATORS, missingDocAssets, healDocAssets, DOC_ASSET_GENERATORS, restartService, recordLedger, pollHealth, deriveVersionUrl, pollServedVersion,
   resolvePinPushAuth, remoteGithubRepo, pinnedDeployKey, // task 1003081 — the pin push prefers the owner's GitHub token (ADR 0176 follow-up)
   readManifest, resolveReferenceManifest, verifyInstalledPin, // task 1002216 (audit H8) — integrity-pin verification

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.748'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.750'; // 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/db_backup_nightly.mjs

@@ -0,0 +1,79 @@
+// tests/db_backup_nightly.mjs — the nightly dump's sanity guard (task 1003925).
+//
+// THE BUG. db-backup-nightly.sh refused any dump under a fixed 1 MiB floor, sized for the
+// platform's own database. A small project's whole database gzips to ~36 KB, so every
+// project's nightly unit failed AND the valid dump was deleted: on 2026-09-15 twelve backup
+// units were failed and no project had a single retained dump. The guard now asks whether
+// the dump is COMPLETE (pg_dump's closing comment), which is true of a valid dump at any size
+// and false of one cut short.
+//
+// The script runs for real against a fake `pg_dump` on PATH, so nothing touches a database.
+//
+// Run:  node --test tests/db_backup_nightly.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SCRIPT = path.join(ROOT, 'scripts', 'gds', 'db-backup-nightly.sh');
+const skip = process.platform === 'win32' ? 'needs a POSIX bash + coreutils (runs in CI)' : false;
+// The script's env-var prefix, built rather than written so the legacy-literal ratchet
+// does not count a test that has to speak the script's own variable names.
+const ENV = 'gds_backup_'.toUpperCase();
+
+// A fake pg_dump: a plain-format dump of `rows` rows, closed the way pg_dump closes one
+// (including the \unrestrict line patched servers append) unless it is `cut` short, and
+// exiting `exitCode`.
+function runBackup({ rows = 40, cut = false, exitCode = 0, env = {} } = {}) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'db-backup-'));
+  const bin = path.join(tmp, 'bin');
+  const dir = path.join(tmp, 'backups');
+  fs.mkdirSync(bin);
+  fs.mkdirSync(dir);
+  const body = Array.from({ length: rows }, (_, i) => `INSERT INTO public.t VALUES (${i});`).join('\n');
+  const close = cut ? '' : '\n--\n-- PostgreSQL database dump complete\n--\n\n\\unrestrict abc123\n';
+  fs.writeFileSync(path.join(bin, 'pg_dump'),
+    `#!/bin/bash\ncat <<'EOF'\n--\n-- PostgreSQL database dump\n--\n${body}\n${close}EOF\nexit ${exitCode}\n`, { mode: 0o755 });
+  const r = spawnSync('bash', [SCRIPT], {
+    encoding: 'utf8',
+    env: { ...process.env, PATH: `${bin}:${process.env.PATH}`, [`${ENV}DB`]: 'smallproj', [`${ENV}DIR`]: dir, ...env },
+  });
+  return { status: r.status, stdout: r.stdout, stderr: r.stderr, dumps: fs.readdirSync(dir).filter((f) => f.endsWith('.sql.gz')) };
+}
+
+test('a complete dump of a small project is kept, however small', { skip }, () => {
+  const r = runBackup();
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.dumps.length, 1, 'the valid dump is retained');
+  assert.match(r.stdout, /gds-db-backup: ok/);
+});
+
+test('a dump cut short fails and is removed, whatever its size', { skip }, () => {
+  const r = runBackup({ rows: 50000, cut: true });
+  assert.equal(r.status, 1);
+  assert.equal(r.dumps.length, 0, 'an incomplete dump never masquerades as a good one');
+  assert.match(r.stderr, /incomplete/i);
+});
+
+test('a pg_dump that fails mid-stream still fails the run (pipefail, task 1711)', { skip }, () => {
+  const r = runBackup({ cut: true, exitCode: 1 });
+  assert.notEqual(r.status, 0);
+  assert.equal(r.dumps.length, 0);
+});
+
+test('an explicit operator size floor is still enforced', { skip }, () => {
+  const r = runBackup({ env: { [`${ENV}MIN_BYTES`]: String(10 * 1024 * 1024) } });
+  assert.equal(r.status, 1);
+  assert.equal(r.dumps.length, 0);
+  assert.match(r.stderr, /floor/);
+});
+
+test('no fixed size floor is baked in for every instance', () => {
+  const src = fs.readFileSync(SCRIPT, 'utf8');
+  assert.doesNotMatch(src, new RegExp(`${ENV}MIN_BYTES:-[1-9]`), 'a default floor fails every database smaller than it');
+});

package/tests/upgrade.mjs

@@ -228,7 +228,9 @@ t('full: pre-flight → pin → install → migrate → materialize → restart
     // pin is committed (task 1002712). It runs LAST — after verify — and without
     // --commit-pin it only warns, so no git add/commit/push appears here.
     ['git status --porcelain', 'npm install --no-audit --no-fund', 'npm run migrate', 'systemctl restart emersonian.service',
-      'git status --porcelain -- package.json package-lock.json']
+      'git status --porcelain -- package.json package-lock.json',
+      // task 1003926: both generators ran, so the files they rewrote are the pin commit's too
+      `git status --porcelain -- ${Object.values(u.API_ARTIFACT_FILES).flat().join(' ')}`]
   );
   // materialize pointed at the freshly-installed core
   assert.ok(materialized && materialized.coreRoot.endsWith(join('node_modules', '@bongos', 'core')));
@@ -1676,6 +1678,42 @@ t('runUpgrade: the token store is consulted only when a push is actually coming'
   }
 });
 
+// task 1003926 — the pin commit carries the files the generators that RAN rewrote, and no others.
+t('runUpgrade --commit-pin --pin-no-push: a generator that did not run contributes nothing to the pin commit', async () => {
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const src = mkdtempSync(join(tmpdir(), 'otb-upgrade-src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const calls = [];
+  const changed = ['package.json', 'package-lock.json', 'docs/api/openapi.json', 'clients/bongos-client/package.json'];
+  const run = (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') {
+      if (!args.includes('--')) return { status: 0, stdout: '' }; // pre-flight: clean
+      const asked = args.slice(args.indexOf('--') + 1);
+      return { status: 0, stdout: changed.filter((p) => asked.includes(p)).map((p) => ` M ${p}\n`).join('') };
+    }
+    if (cmd === 'git' && args[0] === 'rev-parse') return { status: 0, stdout: 'main\n' };
+    if (cmd === 'npm' && args[0] === 'install') {
+      writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'), JSON.stringify({ name: '@bongos/core', version: '1.15.0' }) + '\n');
+    }
+    return { status: 0 };
+  };
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'acme.service', healthCheck: false, commitPin: true, pinNoPush: true },
+    {
+      log: hush, err: hush, run, materialize: () => ({}),
+      // the client generator failed, so its files are not the upgrade's output
+      regenerateApiArtifacts: () => ({ ok: false, ran: ['gen-api-docs.js'], reason: 'gen-api-client.js exited 1' }),
+      databaseUrl: '', pgDatabase: '',
+    },
+  );
+  assert.equal(res.ok, true, `upgrade should succeed: ${res.error}`);
+  assert.equal(res.pin && res.pin.committed, true);
+  assert.ok(calls.includes('git add package.json package-lock.json docs/api/openapi.json'),
+    `got ${JSON.stringify(calls.filter((c) => c.startsWith('git add')))}`);
+  assert.ok(!calls.some((c) => c.startsWith('git push')), '--pin-no-push');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/upgrade_persist_pin.mjs

@@ -21,9 +21,14 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { API_ARTIFACT_FILES } from '../scripts/gds/upgrade.js';
 
 const require = createRequire(import.meta.url);
-const { persistPin, dirtyPinFiles, preflightDbIdentity, PIN_FILES } = require('../scripts/gds/upgrade.js');
+const { persistPin, dirtyPinFiles, preflightDbIdentity, gitTreeClean, PIN_FILES } = require('../scripts/gds/upgrade.js');
 
 // A fake `run` driven by a table of [matcher, result]. Records every invocation.
 function fakeRun(handlers = {}) {
@@ -250,3 +255,99 @@ test('dirtyPinFiles only ever reports the pin files', () => {
   const statusCall = run.calls.find((c) => c.startsWith('git status'));
   assert.match(statusCall, /--\s+package\.json package-lock\.json$/, 'pathspec-limited');
 });
+
+// ── the upgrade's own regenerated files ride the pin commit (task 1003926) ───────
+//
+// regenerateApiArtifacts rewrites the instance's TRACKED spec, reference and typed client
+// WHOLE. With only the pin committed they stayed dirty, and the next `bongos upgrade`
+// refused its clean-tree pre-flight: the stranding the pin commit exists to prevent.
+
+const ARTIFACTS = Object.values(API_ARTIFACT_FILES).flat();
+// A `git status --porcelain -- <paths>` fake that reports only what was asked AND changed.
+const statusOf = (changed) => (args) => {
+  const asked = args.slice(args.indexOf('--') + 1);
+  return { status: 0, stdout: changed.filter((p) => asked.includes(p)).map((p) => ` M ${p}\n`).join('') };
+};
+
+test('API_ARTIFACT_FILES names exactly the files the two generators write', () => {
+  const client = require('../scripts/gds/gen-api-client.js').build();
+  assert.deepEqual(API_ARTIFACT_FILES['gen-api-client.js'], Object.keys(client.files).map((f) => `clients/bongos-client/${f}`));
+  const docsSrc = readFileSync(new URL('../scripts/gds/gen-api-docs.js', import.meta.url), 'utf8');
+  assert.deepEqual(API_ARTIFACT_FILES['gen-api-docs.js'], [...docsSrc.matchAll(/\brel: '([^']+)'/g)].map((m) => m[1]));
+});
+
+test('the generated files that changed are staged and committed WITH the pin', () => {
+  const run = fakeRun({ status: statusOf([...PIN_FILES, 'docs/api/openapi.json', 'clients/bongos-client/package.json']), 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, artifactPaths: ARTIFACTS }, run, quiet, quiet);
+  assert.equal(r.committed, true);
+  assert.deepEqual(r.dirty, [...PIN_FILES, 'docs/api/openapi.json', 'clients/bongos-client/package.json']);
+  assert.ok(run.calls.includes(`git add ${PIN_FILES.join(' ')} docs/api/openapi.json clients/bongos-client/package.json`),
+    `stages the pin + only the generated files that changed; got ${JSON.stringify(run.calls)}`);
+});
+
+test('generated files that did not change add nothing to the staging argv', () => {
+  const run = fakeRun({ status: statusOf([...PIN_FILES]), 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: true, push: false, artifactPaths: ARTIFACTS }, run, quiet, quiet);
+  assert.ok(run.calls.includes(`git add ${PIN_FILES.join(' ')}`));
+});
+
+test('an already-committed pin still commits the generated files the upgrade rewrote', () => {
+  const run = fakeRun({ status: statusOf(['docs/api-reference.md']), 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, artifactPaths: ARTIFACTS }, run, quiet, quiet);
+  assert.equal(r.committed, true, 'a dirty generated file alone is still the upgrade\'s to persist');
+  assert.ok(run.calls.includes(`git add ${PIN_FILES.join(' ')} docs/api-reference.md`));
+});
+
+test('a path nobody asked about is never reported, and no artifact paths means no extra git call', () => {
+  const run = fakeRun({ status: { status: 0, stdout: ' M config/branding.json\n M docs/api/openapi.json\n' }, 'rev-parse': ON_MAIN });
+  const r = persistPin({ ...base, commitPin: true, push: false, artifactPaths: ['docs/api/openapi.json'] }, run, quiet, quiet);
+  assert.deepEqual(r.dirty, ['docs/api/openapi.json'], 'config/branding.json is not the upgrade\'s to commit');
+  const bare = fakeRun({ status: DIRTY, 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: true, push: false }, bare, quiet, quiet);
+  assert.equal(bare.calls.filter((c) => c.startsWith('git status')).length, 1, 'an empty pathspec would mean the WHOLE tree');
+});
+
+test('without --commit-pin, the paste-ready fix stages the changed generated files too', () => {
+  const warnings = [];
+  const run = fakeRun({ status: statusOf([...PIN_FILES, 'docs/api/openapi.json']), 'rev-parse': ON_MAIN });
+  persistPin({ ...base, commitPin: false, artifactPaths: ARTIFACTS }, run, quiet, (m) => warnings.push(m));
+  const cmd = warnings.find((w) => w.includes('git -C'));
+  assert.match(cmd, /add 'package\.json' 'package-lock\.json' 'docs\/api\/openapi\.json' &&/);
+});
+
+// Real git, no fakes: the task's done-when, reproduced on a scratch repo.
+function git(dir, ...args) { return spawnSync('git', args, { cwd: dir, encoding: 'utf8' }); }
+function put(dir, rel, content) { mkdirSync(dirname(join(dir, rel)), { recursive: true }); writeFileSync(join(dir, rel), content); }
+function scratchInstance() {
+  const dir = mkdtempSync(join(tmpdir(), 'upgrade-regen-'));
+  git(dir, 'init', '-q');
+  git(dir, 'config', 'user.email', 'upgrade-test@example.invalid');
+  git(dir, 'config', 'user.name', 'upgrade test');
+  git(dir, 'config', 'core.autocrlf', 'false');
+  for (const f of [...PIN_FILES, ...ARTIFACTS, 'config/branding.json']) put(dir, f, 'scaffold\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '-q', '-m', 'scaffold');
+  return dir;
+}
+// What one upgrade writes: the moved pin, and the generators' whole files.
+const upgradeWrites = (dir, version) => { for (const f of [...PIN_FILES, ...ARTIFACTS]) put(dir, f, `${version}\n`); };
+
+test('real git: two consecutive co-tenant upgrades each leave the tree clean, so the next pre-flight passes', () => {
+  const dir = scratchInstance();
+  for (const [from, to] of [['1.19.737', '1.19.745'], ['1.19.745', '1.19.746']]) {
+    assert.equal(gitTreeClean(dir).ok, true, `pre-flight before ${to}`);
+    upgradeWrites(dir, to);
+    const r = persistPin({ instanceDir: dir, fromVersion: from, toVersion: to, commitPin: true, push: false, artifactPaths: ARTIFACTS }, spawnSync, quiet, quiet);
+    assert.equal(r.committed, true, `upgrade to ${to} committed`);
+    assert.equal(git(dir, 'status', '--porcelain').stdout, '', `upgrade to ${to} leaves nothing uncommitted`);
+  }
+});
+
+test('real git: an owner edit outside the generated files is never swept into the pin commit', () => {
+  const dir = scratchInstance();
+  put(dir, 'config/branding.json', 'the owner was here\n');
+  upgradeWrites(dir, '1.19.745');
+  persistPin({ instanceDir: dir, fromVersion: '1.19.737', toVersion: '1.19.745', commitPin: true, push: false, artifactPaths: ARTIFACTS }, spawnSync, quiet, quiet);
+  assert.equal(git(dir, 'status', '--porcelain').stdout, ' M config/branding.json\n');
+  assert.ok(!git(dir, 'show', '--name-only', '--format=', 'HEAD').stdout.includes('config/branding.json'));
+});