@bongos/core 1.19.749 → 1.19.751

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.749",
-  "core_contract": "1.19.749",
-  "source_commit": "238806532985c069a1b8a778e5a3d223cd6b01c4",
+  "core_version": "1.19.751",
+  "core_contract": "1.19.751",
+  "source_commit": "737b578919a197afeddbf0c94a548290a9161998",
   "source_ref": "HEAD",
-  "built_at": "2026-09-15T22:00:53.285Z",
+  "built_at": "2026-09-15T22:52:21.404Z",
   "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": "ddc2e6cffdc346ee09a971dd7f237459cf8c142ad8cf058845f48638fa01a3e7",
+  "file_count": 2617,
+  "tree_sha256": "741bce83585c646386bc2ddbe75a07bf458400bd8ed19f78d47da79ba5c9e5de",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2507,7 +2507,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "207ce89a17ab5bd75cb956f9e41497ef39eb10d4f59eb634f0d1c1933304ced0"
+      "sha256": "6864b03a8e3bcca555963a85cbd1d3c1ac609b355e61ff4abb60299626979752"
     },
     {
       "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",
@@ -7562,12 +7562,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "1cf816c4ca4b4b56d3fefe33e86e8ce4caa511ee69fd8dd6c2ecc2940dc07f7f"
+      "sha256": "197208273eadd947af33002bde4c49421f0a5f846946b5852fc2422bcf4bdafc"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d890fe5b32e9b8158a19a40b765570972673f8558cb5d2e8e13ba396eee4476f"
+      "sha256": "c91859f22d3a06e3e9c64c628dff657f7aecbda25afafd287f571a473148bdee"
     },
     {
       "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": "fe3abe00b43163eb1b24dd2da57d4c8fd51194e79bab8a6683355980787a9e8c"
+      "sha256": "3146778317a4dfd01673553e94966ea40d27add12a7ca6c52ec8581eded085ac"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -9367,7 +9367,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "6c9cce81108782c099d58259ce776bed22f815f7276fa9fb9a50264aeedd3835"
+      "sha256": "e80ba785ccd39c20b2ca31f3c645257f84e72004e75c71ba52fb10647a6b3297"
     },
     {
       "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",
@@ -12947,7 +12952,7 @@
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",
-      "sha256": "864b9471fcd6bfc41e99fd5356a3124c25d288946326c2797cc2bacb86120d05"
+      "sha256": "d30debaa35407998dcdd1949f9bcbf45c09b4a001d22cfdea9541b5bdbaa1274"
     },
     {
       "path": "tests/verify_task_guard.mjs",

package/docs/module-api-changelog.md

@@ -1972,5 +1972,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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)
+  1.19.751 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.750 with no explicit bump. run 35033016299. (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/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.749",
+  "version": "1.19.751",
   "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

@@ -334,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 ${toStage.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 };
   }
 

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

@@ -312,7 +312,7 @@ test('without --commit-pin, the paste-ready fix stages the changed generated fil
   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' &&/);
+  assert.match(cmd, /add 'package\.json' 'package-lock\.json' 'docs\/api\/openapi\.json' && git -C \S+ commit -m .+ && git -C \S+ push /);
 });
 
 // Real git, no fakes: the task's done-when, reproduced on a scratch repo.