@bongos/core 1.19.746 → 1.19.747

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.746",
-  "core_contract": "1.19.746",
-  "source_commit": "4d1f75b454f00b81bcda96e1dadbd49e1eee1731",
+  "core_version": "1.19.747",
+  "core_contract": "1.19.747",
+  "source_commit": "492774317dbad5e66a4cd25638d81545e3561be3",
   "source_ref": "HEAD",
-  "built_at": "2026-09-15T20:43:25.357Z",
+  "built_at": "2026-09-15T21:22:06.627Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 480,
+    "docs_redacted": 481,
     "agent_docs_stubbed": 25,
     "functional_verbatim": 2109,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2614,
-  "tree_sha256": "0006716e0db1f92079035942152af287a85a3e3e57b5c3b7a1328b4e760d2957",
+  "file_count": 2615,
+  "tree_sha256": "839a3564a1926eee62dfb94ddeb8383deb0e2a794820335ab13c4a45fd1fddb5",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -1929,10 +1929,15 @@
       "mode": "0000644",
       "sha256": "9280dd05ac1061a7f4da41ea665612be9cee16631ed2b27a513c3f8ec084b51a"
     },
+    {
+      "path": "docs/adr/0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md",
+      "mode": "0000644",
+      "sha256": "f9141e74643a8055c3e7f7943957e1103d34b4673dd96c673636c30a50d47c36"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "b058befbb0e111c4fba17e3890b02abeda9e828c9f419028183e2cf1f3b02f41"
+      "sha256": "e36f3dffd983d410498269c6923c2b66a18071a25c1ea57eac0c8353b1ebc1bc"
     },
     {
       "path": "docs/api-reference.md",
@@ -2497,7 +2502,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "cf0a15e10db3248e30d6aeb4f4fbc13de0e190a7322c17ebdf59c6c39adb1a4e"
+      "sha256": "8bd715e0a97a235285a67533236b0769798356c3c72e22af8895ae7209bcc7f2"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7552,12 +7557,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "c2d3b75314692c4e7d9658defd555fda8c648e0ef6521738743eb110277c2868"
+      "sha256": "07948a29433225ad3eb2ce1b2d71af8f884e723cd8a12b8d44a7a46331a7e156"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "a35739522d6c79e6cfe8eea8ed34a9e16df1a559bbe89d1589b45e20c7f49860"
+      "sha256": "d20112e72f90d6ffe815316162e30da9ccdd4e0a3dd8a475572c62f39e90419a"
     },
     {
       "path": "public-docs/index.html",
@@ -9357,7 +9362,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9e340d75ea572651792a34774d767edca2c2cac266024d56b3265064ab95d9bc"
+      "sha256": "269664a23f5e22f8499ae3067550f3edfc853d55b128cd6ec6f6556e337df0b9"
     },
     {
       "path": "src/module-loader/catalog.js",

package/docs/adr/0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md

@@ -0,0 +1,81 @@
+# ADR 0285 — A shared box holds about twelve projects per GB, and memory is the wall
+
+- **Status:** accepted
+- **Date:** 2026-09-15
+- **Task:** [1003877](https://cloudbongos.com/builders#/task/1003877) (goal 1000106), a spike. Informs [1003923](https://cloudbongos.com/builders#/task/1003923) (the resize) and [1001949](https://cloudbongos.com/builders#/task/1001949) (managed billing).
+
+## Context
+
+Every live project is `hosting_shape='standalone'`: its own checkout and pinned core, one Node process on its own port and one Postgres database, all on the `s-1vcpu-2gb` control plane beside the control plane itself. Nothing recorded what one more project costs, so creation could not refuse, overflow or price honestly.
+
+The task asked for a throwaway droplet filled one instance at a time. The owner chose instead to **measure the live box read-only**: eleven real projects already give the data points, and nothing was changed to get them.
+
+## Measurement (2026-09-15, live control plane, read-only)
+
+Sources: `/proc/<pid>/smaps_rollup` (`Pss` + `SwapPss`, which avoids `ps` double-counting shared pages), each unit's cgroup `memory.peak`, `/proc/<pid>/stat` CPU ticks over a 60-second `vmstat 5 12` window, `pg_stat_activity` joined to backend PSS, sysstat history (`sa12`–`sa15`) and the kernel journal (retained since 2026-07-14). Box at the time: 1967 MiB RAM, 4 GiB swap, 11 project processes + the control plane, 1.09 GB available.
+
+**One project process:**
+
+| State | Resident (PSS) | Swapped | Total |
+|---|---|---|---|
+| fresh boot, 10 min old (test4) | 65 MB | 0 | 65 MB |
+| same, after 150 local requests | 70 MB | 0 | 70 MB |
+| idle for 33 h+ (ten projects) | 12–28 MB | 21–35 MB | **45–49 MB**, a tight band |
+| boot peak, cgroup `memory.peak` (includes page cache) | — | — | 118–134 MB |
+
+- **CPU:** 0.02–0.05% of one core per project, the same over the 60-second window and over each process's lifetime.
+- **Postgres:** **zero** backends per idle project (pg's pool releases an idle client after 10 s). A busy backend is 7–10 MB PSS.
+- **Disk:** a checkout is 77–140 MB, including an unshared 63 MB `node_modules`. An adopted repo with its own dependencies runs larger (hermeslines-marketing: 936 MB). A fresh database is 45 MB.
+
+**Fixed cost of the box, whatever the project count:** kernel unreclaimable memory ~98 MB (slab, page tables, stacks), OS daemons ~112 MB, Caddy 38 MB, Postgres 139 MB (`shared_buffers` 160 MB), and the control-plane process ~116 MB (boot peak 233 MB). That totals **~500 MB**, and we reserve **~250 MB of page cache** on top (an allowance, not a measurement) so module loads and Postgres reads stay off the disk. **~750 MB fixed**, or ~630 MB on a box that does not run the control plane.
+
+**History:** the box has never OOM-killed a project. The only OOM kill on record was Prometheus on 2026-09-04 (812 MB anon), since removed ([ADR 0284](0284-the-control-plane-carries-no-metrics-stack.md)). The worst pressure since then (2026-09-14 11:40: 279 MB available, commit 316%, load 6.82) came during operator ssh sessions while no fleet unit changed state. It was work on the box, not the fleet. The day-average 4–6% user CPU is the control plane's own 1–2-minute intent-runner and deploy timers, each a fresh Node start, and it does not grow with project count.
+
+## Decision
+
+### 1. The number: ~80 MB per project, about 12 projects per GB above the fixed base
+
+Price a project at its **warm** size, 70 MB for the process plus ~10 MB for one busy Postgres backend. **Swap is not capacity.** An idle project shrinks to ~25 MB resident only because the kernel swaps its cold pages out, which is why the box looks roomier than it is. A reboot (the resize in [1003923](https://cloudbongos.com/builders#/task/1003923) needs one), a fleet core upgrade or a burst of traffic brings every project back to warm at once, on top of a ~130 MB boot peak each.
+
+### 2. The ceiling per tier: `floor((usable MiB − fixed) / 80)`
+
+| Tier | $/mo | Box role | Ceiling | $/project |
+|---|---|---|---|---|
+| `s-1vcpu-2gb` (today) | 12 | control plane | **15** | 0.80 |
+| `s-2vcpu-4gb` | 24 | control plane | **39** | 0.62 |
+| `s-2vcpu-4gb` | 24 | overflow box, no control plane | **41** | 0.59 |
+| `s-4vcpu-8gb` | 48 | control plane | 90 by RAM, **only with a pool cap** (§3) | 0.53 |
+
+Today's box holds **11 of 15**. Resize (or open the next box) when it reaches **12**, which is 80% of the ceiling.
+
+### 3. Memory binds first; connections bind second
+
+- **RAM is the binding constraint** at every tier up to 4 GB.
+- **Postgres connections are the next wall.** `max_connections` is 100 (97 for non-superusers), and every instance pool uses pg's default of `max: 10` with no override ([`src/bongos/pool.js`](../../src/bongos/pool.js)). At idle this costs nothing, but nine projects busy at once can exhaust it, and at 8 GB it binds long before RAM does. Filed as [1003928](https://cloudbongos.com/builders#/task/1003928): cap the provisioned instances' pool size.
+- **Walls that do not bind:**
+  - CPU: 0.03% per idle project.
+  - Ports: lowest-free from 3003 up to the 32768 ephemeral floor, about 29,700.
+  - systemd: three units per project; `TasksMax` is 2315 per unit.
+  - Disk: 26 GB free at ~200 MB per project with its database and dumps, room for ~130.
+  - The 04:00 backup cluster: all twelve timers fire in one window with a 5-minute random delay, adding ~4 points of user CPU for ten minutes. Ten of eleven instance backups currently fail on the size floor ([1003925](https://cloudbongos.com/builders#/task/1003925)), so the per-dump cost is not yet observable, but a dump of a 45 MB database is small.
+
+### 4. The shapes: keep three, and add placement as its own question
+
+The measured cost is the same **unit** for `co-tenant` and `standalone`. What separates them is repository layout, not what they cost the box. So no new shape is needed. What the three shapes never answer is **which box**, and the rule is **standalone until the box reaches its ceiling, then the next box**. The box is the unit of spend, and this ceiling governs placement. Filed as [1003927](https://cloudbongos.com/builders#/task/1003927): the runner refuses to place a control-plane-local project past the ceiling.
+
+`dedicated` stays behind `provisioning.fleet.manage` ([`paid-shape-gate.js`](../../modules/provisioning/paid-shape-gate.js)). It has never been provisioned, and it should not be offered to anyone paying nothing: at $6/mo minimum ($24 at the runner's default tier), one dedicated project costs **8–40× a shared slot**.
+
+`costEstimateUsd` prices a shared project at $0, a visibility choice ([ADR 0111](0111-instance-hosting-provisioning-module.md) §6). It can now become honest: a shared slot costs **box price ÷ ceiling**, $0.62–0.80/mo at today's tiers. That change belongs to the billing work ([1001949](https://cloudbongos.com/builders#/task/1001949)), not this ADR.
+
+## Alternatives considered
+
+- **A throwaway droplet filled one instance at a time** (the task's original method). Declined by the owner. The live box already carried eleven instances at two ages (33 h idle and 10 min fresh), which is the slope data a lab box would have produced, with none of the spend.
+- **Price by idle resident memory (~25 MB, about 40 per GB).** Rejected. It counts swap as capacity, and it breaks exactly when every project wakes at once: on reboot, on a fleet upgrade, or under traffic.
+- **Price by the boot peak (~130 MB).** Rejected. The peak includes reclaimable page cache and lasts seconds, so it would understate capacity by ~40%.
+
+## Consequences
+
+- **+** Provisioning has a number to act on (15 today, 39 after the resize), and the resize in [1003923](https://cloudbongos.com/builders#/task/1003923) has a trigger: 12 projects.
+- **+** Billing has a unit cost for a shared slot.
+- **−** The page-cache reserve is an allowance, not a measurement. If a ceiling is ever approached, re-measure `MemAvailable` then instead of trusting the 250 MB.
+- **−** These are **idle-fleet** numbers. A project with real traffic or large data will sit above 80 MB, so the ceiling is an upper bound for quiet projects. Re-measure the same way (`Pss` + `SwapPss` per unit, `memory.peak`, `pg_stat_activity`) as projects gain users.

package/docs/adr/README.md

@@ -376,3 +376,4 @@ This keeps the decision history honest and traceable.
 | 0282 | [**A module that spends money for its callers DECLARES so, and the core refuses to enable it where anyone can sign up and nobody is on the hook** ([task 1003884](https://cloudbongos.com/builders#/task/1003884), owner decision 2026-09-13). A fire from `modules/agents` costs ~$0.90, `POST /agents/:name/invoke` answers **202** so the caller does not even wait, and the route is gated at `requireBuilder` and nothing else — deliberately, because a v1 agent is hard-read-only by plumbing. That bounds CAPABILITY, not SPEND, and `lib/fire-budget.js` says so in its own header: it is a blast radius, explicitly NOT a budget, and it defers the real cap to `agents_runs.cost_usd`. The cap did not exist. The exposure is three reasonable facts composed: a fire is expensive and async; invoke admits any **any-builder**; and with the join door `open`, any GitHub account IS one seconds after sign-up. **Decision: the MODULE declares `"spend": { "requiresPayer": true }` and the CORE refuses to enable it when the composed join door (ADR 0247 — the door, never the `joinability` knob alone) is `open` with no configured payer.** The declaration lives in the manifest because fitness Check 10 forbids the kernel from naming a discovered module key — a constraint that turns out to be the better design, since the next metered module inherits the guard by declaring one line rather than by someone remembering to widen a list. The refusal is at **config load**, so the routes never mount and the migrations never run: a per-request check would let the module mount, advertise its routes and read as enabled everywhere the UI looks, then refuse callers one at a time — a broken feature, not a closed door. It is applied AFTER config, env and default alike, because `<PREFIX>_MODULE_<KEY>` is exactly the knob a hurried deploy reaches for and a wall env could outrank is a suggestion. An UNREADABLE posture refuses too, inverting this file’s usual fail-to-unchanged default: "I could not tell whether strangers can sign up" has to mean "assume they can", and the cost of being wrong is one module resolving off. `spend_payer` (`none|project|builder`) joins `SETTINGS_VOCAB` on ADR 0241’s transport, and `agents_runs` gains `payer_kind` + `payer_builder_id` — **stored, not derived**, because the setting is a live knob and deriving would make last month’s bill change when an owner flips it. `none` is NOT a third payer: a run always has a real one and `none` attributes to the project, so a CLOSED-door instance is unchanged and `none` is fatal only where it is also dangerous. An EVENT fire has no caller, so it bills the project rather than nobody — otherwise the event path is the one unbounded route. The per-payer monthly ceiling (`lib/spend-ceiling.js`) is a SECOND wall that must never merge into the first: a rate ceiling cannot bound a bill (~$650/month/builder at 10 fires an hour) and a spend ceiling cannot bound a loop (it reads spend already landed). It records NOTHING — the ledger is the tally, and a second tally is the disagreeing answer fire-budget’s header refuses to become. It honours the finding of abandoned [task 1001393](https://cloudbongos.com/builders#/task/1001393), which caught the autonomy brake reading month-to-date spend from a DB it could not reach and **failing open**: every unknown refuses (no cap, non-finite cap, no payer, a read that threw, a sum absent or unparseable), answering **402** rather than fire-budget’s 429 so "the money is gone" and "too fast" stay distinguishable. Writing the absent-sum clause down was not paranoia — the first draft admitted the fire on a null sum because `Number(null)` is `0`, and the test for that clause is what caught it. The overshoot is STATED: in-flight fires are invisible to the read, bounded by concurrency × ~$0.90, and what bounds concurrency is fire-budget — each wall’s blind spot is the other’s window. The cost-needs-a-payer constraint is added `NOT VALID` so it binds every future write without failing the migration of an instance whose history predates the column. **What it does not do:** nobody is billed; `builder` attributes spend, it does not collect.](0282-a-module-that-spends-for-its-callers-declares-a-payer-and-the-core-refuses-it-without-one.md) | modules / spend attribution / agents |
 | 0283 | [**The core publishes publicly, because access was never the thing protecting it** ([task 1003872](https://cloudbongos.com/builders#/task/1003872) · goal 1000090 — *Working area 4, Bongos Core distribution*; owner decision 2026-09-13, resolving [task 1003502](https://cloudbongos.com/builders#/task/1003502)). [ADR 0134](0134-private-first-npm-distribution.md) chose private-first and named "public at launch" as a later deliberate step; this is that step. The restricted posture had a cost that grew quietly because every symptom read as a different bug: a tokenless `npm install` returns a flat **E404**, indistinguishable from "no such package", so every co-tenant and downstream upgrade needed a credential to move at all; the nightly auto-upgrade sweep **died on 2026-08-25 and reported `failed=0`** (its unit passed no `NPM_TOKEN`, the env-fed `.npmrc` expanded to empty, and a skip is not a failure in that script's accounting, so nothing complained while the instance stopped receiving core updates); an Anthropic-hosted cloud session could not install the dependency at all; and a fresh scaffold's README step 1 IS `npm install`, which is also what installs the `bongos` command — so without a token an owner got no working instance rather than a stale one. [ADR 0258](0258-the-public-cli-is-a-generated-client-package-not-the-published-core.md)'s `@cloudbongos/cli`, require-closure delazification and all, exists ONLY because of this. **The decisive point is that access control was never what protected the artifact:** three gates decide what is IN the tarball — the in-build no-leak gate (branding literals + credential shapes, fail-closed, 2,624 files clean), the prior-instance leak scan (**fatal by default since [task 1003870](https://cloudbongos.com/builders#/task/1003870)**, `--no-leak-scan` the only escape), and the fixture confirmation of [task 1003871](https://cloudbongos.com/builders#/task/1003871) (all 14 credential-shape files checked against each provider's real key format: 11 too short to have ever been valid, 3 alphabet sequences or Amazon's own published doc example). `--access restricted` decides who may FETCH it; those three decide what is IN it, and conflating them is what made a launch-timing choice feel like a security control. **Decision: publish public — at all three sites.** `publishConfig.access` and `publishArgs` both say `public` (belt-and-braces of the restricted era pointed the other way, so neither drifting alone reverts it), **and so does `publish.yml`** — the site that ACTUALLY releases, `package-core --publish` being the manual owner path. Flipping only `package-core.js` would have left every real release restricted while the code claimed otherwise: exactly task 1003870's shape, where the workflow did not arm the gate its own header comment advertised. A test reads the workflow and fails if `restricted` reappears anywhere in the lane. **The one-time registry flip stays a separate owner step** (`npm access set status=public`): `--access` governs what THAT publish declares and has historically been a no-op when re-publishing an already-private package — the package read `private` on the registry when this was written — so it is verified by a tokenless install from a clean `HOME`, never by the flag's presence. **Provenance stays off:** the PACKAGE is public, the SOURCE REPO is not, and npm blocks provenance on the repo's visibility — turning it on before the source repository goes public fails every publish. The npm path deliberately does not run [ADR 0099](0099-delayed-redacted-mirror-export.md)'s mirror pipeline (`package-core` runs its own redaction: 476 docs redacted, 24 agent-docs stubbed), which is why gates 1–3 carry the whole safety burden and had to land first. **Going public is effectively one-way** — a published tarball is mirrored and cached beyond our control and `npm unpublish` has a 72-hour window that does not reach mirrors. **Does NOT fix the 22 co-tenants:** twenty pin `file:vendor/bongos-core-<v>.tgz`, a local path with no registry channel to follow, so public access is necessary but not sufficient. Rejected: a **rank-gated registry proxy** (server holds the token, builders authenticate with their existing Bongos session, per-request rank check — the RIGHT design if the core must stay private, rejected because it manages the problem going public deletes); **handing builders the read token gated by rank** (rank-gating the handout does not rank-gate the use — a token once held is held forever and revocation means rotating it for everyone: access control in name only); keeping the vendored tarball as the answer (it is why twenty co-tenants are frozen at their provisioning date); making the REPO public in the same change (a larger decision, not required for any of this, and separating them keeps the provenance question honest).](0283-the-core-publishes-publicly-because-access-was-never-the-thing-protecting-it.md) | core distribution / npm access |
 | 0284 | [**The control plane carries no metrics stack** ([task 1003876](https://cloudbongos.com/builders#/task/1003876) · goal 1000106). Supersedes ADR 0127. Grafana (187 MB, the box's largest process) + Prometheus (110 MB, 2.5 GB data) were removed from the `s-1vcpu-2gb` control plane every provisioned project shares; they scraped none of those projects and nothing in the core read them. Owner chose remove over move-to-own-droplet. The `/metrics` exporter stays in every instance, so a scraper can return from a box that is not the control plane. Leftovers (DNS record, co-hosting-box socat forwarders, instance `infra/` copies) filed as a follow-up.](0284-the-control-plane-carries-no-metrics-stack.md) | infra / Cloud Bongos |
+| 0285 | [**A shared box holds about twelve projects per GB, and memory is the wall** ([task 1003877](https://cloudbongos.com/builders#/task/1003877) · goal 1000106, a spike measured read-only on the live control plane at the owner's call). A project costs ~80 MB warm (70 MB Node + one busy Postgres backend); idle projects look like ~25 MB only because swap holds their cold pages, and swap is not capacity. Fixed base ~750 MB on a control plane. Ceiling per tier `floor((usable − fixed) / 80)`: 15 on today's `s-1vcpu-2gb` (11 live), 39 on `s-2vcpu-4gb`; resize at 12. RAM binds first, Postgres connections (pool default 10 × N vs 97) second; CPU, ports, units, disk and the backup window do not bind. Keep the three shapes, add placement ("standalone until the box is full, then the next box"); a shared slot costs box price ÷ ceiling ($0.62–0.80/mo), `dedicated` 8–40× that.](0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md) | infra / Cloud Bongos |

package/docs/module-api-changelog.md

@@ -1966,5 +1966,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.744 with no explicit bump. run 34990123950. (task 1002620)
   1.19.746 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.745 with no explicit bump. run 35021312150. (task 1002620)
+  1.19.747 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.746 with no explicit bump. run 35025151628. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.746",
+  "version": "1.19.747",
   "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/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.746'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.747'; // 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');