@bongos/core 1.19.765 → 1.19.766

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.765",
-  "core_contract": "1.19.765",
-  "source_commit": "3b3d14502e395142e33386df046a8b1d89b05608",
+  "core_version": "1.19.766",
+  "core_contract": "1.19.766",
+  "source_commit": "02a01e26d1d999916c8c67e1e02b06d0db40b694",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T13:30:48.350Z",
+  "built_at": "2026-09-16T13:48:32.669Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2121,
+    "functional_verbatim": 2122,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2629,
-  "tree_sha256": "39fa9398befe5e5189039c4da72c998c4449f48299694a1c6a9d30d10723d49d",
+  "file_count": 2630,
+  "tree_sha256": "56708a327bb43ff2237f2ef0cdd0fac079947882699533e825262e7a16bcf724",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "650ec2daa3a256932ccb33c3d25a4364565d0a2cf9ff8717493144f48f4738b4"
+      "sha256": "10fb4078df266a5663d8079411fdf7698adb1aa8e20a19ca63ff722e1ecb8134"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7577,12 +7577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "025da0b521b730f0ef2a24421607242c01cbc6d23a501c9a3f25d88a0a386b46"
+      "sha256": "6e4cfa58c41e8fbe29dc94bbe4bd7a4eafedb88034b7d1ba3334d4a0764f5b56"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "69ee9c8d4847dabb4965d646a635dbe39a539070a2966df5d6c277101cb62019"
+      "sha256": "b61349c8315ac531b941ca35f84a7323b2192e0ab7507c4d76e1c592c2a9f2e7"
     },
     {
       "path": "public-docs/index.html",
@@ -8412,7 +8412,7 @@
     {
       "path": "scripts/gds/provision-config.js",
       "mode": "0000644",
-      "sha256": "cda8e1022a26dce2252954351c70aa3827067ca300ebfe86b9fc7fa0ae05abeb"
+      "sha256": "c870abebd21411e1fec744281130d116f3b9e8f255ddb6823aae4072a420cc15"
     },
     {
       "path": "scripts/gds/provision-net.js",
@@ -8432,7 +8432,7 @@
     {
       "path": "scripts/gds/provision-units.js",
       "mode": "0000644",
-      "sha256": "f6a26c5a6e6cb57fbcef1cff93738d4dc0ce955486535fca7796d72c5a280cad"
+      "sha256": "e299687a54305e45ea57ff0a439f5ff099cb5d51be64bb0a48056c93309a67e3"
     },
     {
       "path": "scripts/gds/provision.js",
@@ -9237,7 +9237,7 @@
     {
       "path": "src/bongos/pool.js",
       "mode": "0000644",
-      "sha256": "96d41f41c4e93358c66e5101b2fc43d4ff8a1c6301a1fd3ec7020ebff6029c8c"
+      "sha256": "f3fa3e0360c1bd7fb9bdf5756edccb8c5f5cad4d9ef2b89b7f0c6382c5240294"
     },
     {
       "path": "src/bongos/prelaunch-gate.js",
@@ -9397,7 +9397,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ad1c50e46ad096b7ba3032b8e225fec5fa74b8c50640cc577e9323a439f5b8f0"
+      "sha256": "9c4c56d73c466a19a699f6c37e439d54d88211a363a869f9d87e3e840f493a2a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -11874,6 +11874,11 @@
       "mode": "0000644",
       "sha256": "ff9d438a33a32fecc04caa6e652eeaaded6394438bcec0d508ae7c516fa62333"
     },
+    {
+      "path": "tests/pool_max.mjs",
+      "mode": "0000644",
+      "sha256": "68e5b941a1889ddc44fd548e10bb1fdb33822628b0da392592f747a32f7ccd1a"
+    },
     {
       "path": "tests/post_login_landing.mjs",
       "mode": "0000644",
@@ -12052,7 +12057,7 @@
     {
       "path": "tests/provision.mjs",
       "mode": "0000644",
-      "sha256": "25fbd2adccf79e921c642f8f57b082f5f19fa01cd981cd5b813dc1070511aadb"
+      "sha256": "245deb7b090f528180dde1457b821a8c8c2bd74a643524f441519859659643e8"
     },
     {
       "path": "tests/provision_restart.mjs",

package/docs/module-api-changelog.md

@@ -2004,5 +2004,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.763 with no explicit bump. run 35059447999. (task 1002620)
   1.19.765 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.764 with no explicit bump. run 35102327521. (task 1002620)
+  1.19.766 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.765 with no explicit bump. run 35104246900. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.765",
+  "version": "1.19.766",
   "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-config.js

@@ -134,6 +134,14 @@ const CONFIG = {
   // mirror an override into web.env so the fleet API reports the same number.
   boxCeiling: numEnv('PROVISION_BOX_CEILING', null),
   memFloorMb: numEnv('PROVISION_MEM_FLOOR_MB', null),
+  // The Postgres pool cap written into a CO-LOCATED instance's web.env as PGPOOL_MAX
+  // (task 1003928, ADR 0285 §3). pg's default is 10 per process and the shared server
+  // allows 97 non-superuser backends, so nine busy projects exhaust it whatever the
+  // RAM headroom. Idle projects hold zero backends, so this bounds bursts, not the
+  // steady state: 3 × 15 slots + the control plane's own 10 stays under the 97. The
+  // control plane keeps pg's default (it is not provisioned by this runner), and a
+  // dedicated droplet has its own server, so neither is written.
+  instancePoolMax: numEnv('PROVISION_INSTANCE_PGPOOL_MAX', 3),
 };
 
 // task 1002757 — the provisioner's git identity resolves from the instance's own

package/scripts/gds/provision-units.js

@@ -267,13 +267,18 @@ GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
   const dbLines = dbPassword
     ? `PGUSER=${instanceDbRole(inst)}\nPGPASSWORD=${dbPassword}\n`
     : '';
+  // The pool cap (task 1003928, ADR 0285 §3): a co-located instance shares the box's
+  // Postgres with every sibling and the control plane, so its pool may not take pg's
+  // default 10 of the server's 97. src/bongos/pool.js reads it bare. A dedicated
+  // droplet has its own server and keeps the default — the line is not written.
+  const poolLine = inst.hosting_shape === 'dedicated' ? '' : `PGPOOL_MAX=${CONFIG.instancePoolMax}\n`;
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
 ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
 ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}${originLines}${appLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
-${dbLines}${fedLines}${settingsEnvLines(inst, prefix)}`;
+${poolLine}${dbLines}${fedLines}${settingsEnvLines(inst, prefix)}`;
 }
 function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
   return path.posix.join(etcBase, inst.slug, 'web.env');

package/src/bongos/pool.js

@@ -37,11 +37,27 @@ function instanceDbName() {
   return undefined;
 }
 
+// The pool's connection cap (task 1003928, ADR 0285 §3). pg's default `max` is 10 and
+// the shared server allows 97 non-superuser backends, so nine busy co-located
+// instances exhaust it whatever the RAM headroom — connections are the second wall
+// after memory. A provisioned instance's web.env carries PGPOOL_MAX (the runner
+// writes a small cap, PROVISION_INSTANCE_PGPOOL_MAX); UNSET — self-host, dev, the
+// control plane itself — returns undefined so pg keeps its own default and nothing
+// outside a co-located box changes. Read bare like the PG* family beside it: it is
+// a pg option, not a branding one, so it does not ride resolveEnv's prefix.
+// Anything that is not a positive integer is ignored rather than passed to pg.
+function poolMax(env = process.env) {
+  const n = Number(env.PGPOOL_MAX);
+  return Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
 let pool;
+const max = poolMax();
 if (process.env.DATABASE_URL) {
-  pool = new Pool({ connectionString: process.env.DATABASE_URL });
+  pool = new Pool({ connectionString: process.env.DATABASE_URL, ...(max ? { max } : {}) });
 } else {
   pool = new Pool({
+    ...(max ? { max } : {}),
     // Peer auth via the local Unix socket on the droplet; PG* env overrides for other environments.
     host: process.env.PGHOST || '/var/run/postgresql',
     database: process.env.PGDATABASE || instanceDbName(),
@@ -66,4 +82,4 @@ pool.on('error', (err) => {
   console.error('[gds/pool] unexpected pool error', err);
 });
 
-module.exports = { pool, instanceDbName };
+module.exports = { pool, instanceDbName, poolMax };

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

@@ -0,0 +1,79 @@
+// tests/pool_max.mjs
+//
+// The Postgres pool cap (task 1003928, ADR 0285 §3). Every co-located instance used
+// to open pg's default 10 connections against a shared server that allows 97, so
+// nine busy projects exhausted it whatever the RAM headroom. src/bongos/pool.js now
+// honours PGPOOL_MAX; the runner writes it into a co-located instance's web.env
+// (tests/provision.mjs pins that half). These pin the pool half:
+//
+//   • the env reaches pg's `max` — asserted on a REAL Pool built by requiring the
+//     module in a child process with the env set (pool.js builds its Pool at require
+//     time, so the assertion has to cross a process boundary; no connection is ever
+//     opened — a Pool connects lazily);
+//   • absence leaves pg's default (10), so self-host, dev and the control plane are
+//     unchanged;
+//   • garbage is ignored, never handed to pg.
+//
+// DB-free. Run:  node tests/pool_max.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { poolMax } from '../src/bongos/pool.js';
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const ROOT = path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+const POOL = path.join(ROOT, 'src', 'bongos', 'pool.js');
+
+// Build the pool in a child with a controlled env and report what pg was handed.
+// The DB name is pinned so instanceDbName() never reads a pack; nothing connects.
+function poolMaxInChild(extraEnv) {
+  const env = { ...process.env, PGDATABASE: 'pool_max_probe' };
+  delete env.PGPOOL_MAX; delete env.DATABASE_URL; delete env.NODE_TEST_CONTEXT;
+  Object.assign(env, extraEnv);
+  const out = execFileSync(process.execPath, [
+    '-e', 'const { pool } = require(process.argv[1]); console.log(JSON.stringify({ max: pool.options.max })); pool.end();',
+    POOL,
+  ], { env, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return JSON.parse(out.trim().split('\n').pop()).max;
+}
+
+console.log('poolMax (pure):');
+
+t('a positive integer is the cap; absent/blank/garbage/zero/negative/fractional → undefined (pg keeps its default)', () => {
+  assert.equal(poolMax({ PGPOOL_MAX: '3' }), 3);
+  assert.equal(poolMax({ PGPOOL_MAX: '10' }), 10);
+  assert.equal(poolMax({}), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: 'three' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '0' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '-2' }), undefined);
+  assert.equal(poolMax({ PGPOOL_MAX: '2.5' }), undefined);
+});
+
+console.log('\nthe env reaches the real Pool (child process, no connection):');
+
+t('PGPOOL_MAX=3 → pool.options.max is 3 (the co-located instance shape)', () => {
+  assert.equal(poolMaxInChild({ PGPOOL_MAX: '3' }), 3);
+});
+
+t('unset → pg\'s default 10 (self-host, dev, the control plane: unchanged)', () => {
+  assert.equal(poolMaxInChild({}), 10);
+});
+
+t('garbage → pg\'s default, never a NaN handed to pg', () => {
+  assert.equal(poolMaxInChild({ PGPOOL_MAX: 'lots' }), 10);
+});
+
+t('the cap applies on the DATABASE_URL branch too', () => {
+  assert.equal(poolMaxInChild({ PGPOOL_MAX: '4', DATABASE_URL: 'postgres://u:p@127.0.0.1:1/pool_max_probe' }), 4);
+});
+
+console.log(`\npool_max: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provision.mjs

@@ -2618,6 +2618,27 @@ t('webEnvBody: NO password ⇒ no PG credential lines — an instance provisione
   assert.match(b, /^PGDATABASE=mercury$/m, 'the DB name is unchanged either way');
 });
 
+// ── the Postgres pool cap (task 1003928, ADR 0285 §3) ─────────────────────────
+t('webEnvBody: a CO-LOCATED instance (co-tenant or standalone) carries PGPOOL_MAX at the runner\'s cap, beside PGDATABASE', () => {
+  for (const shape of ['co-tenant', 'standalone']) {
+    const b = P.webEnvBody({ ...coTenant, hosting_shape: shape });
+    assert.match(b, new RegExp(`^PGPOOL_MAX=${P.CONFIG.instancePoolMax}$`, 'm'), `${shape} carries the cap`);
+    const lines = b.split('\n');
+    assert.equal(lines[lines.indexOf('PGDATABASE=mercury') + 1], `PGPOOL_MAX=${P.CONFIG.instancePoolMax}`, 'written right after the DB name, with or without a credential');
+  }
+  assert.equal(P.CONFIG.instancePoolMax, 3, 'the default cap: 3 × 15 slots + the control plane\'s 10 stays under the server\'s 97');
+  // …and it rides along with the credential lines, not instead of them.
+  const withCred = P.webEnvBody(coTenant, { dbPassword: 'pw_ABC-123' });
+  assert.match(withCred, /^PGPOOL_MAX=3$/m);
+  assert.match(withCred, /^PGUSER=bongos-mercury$/m);
+});
+
+t('webEnvBody: a DEDICATED droplet has its own Postgres — no PGPOOL_MAX line, pg keeps its default', () => {
+  const b = P.webEnvBody({ ...coTenant, hosting_shape: 'dedicated' });
+  assert.doesNotMatch(b, /^PGPOOL_MAX=/m);
+  assert.match(b, /^PGDATABASE=mercury$/m);
+});
+
 t('dedicatedUserData: the droplet runs the SAME account + role steps, in the same order around the migrate', () => {
   const ud = P.dedicatedUserData(coTenant);
   const at = (needle) => ud.indexOf(needle);