@bongos/core 1.19.995 → 1.19.996

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.995",
-  "core_contract": "1.19.995",
-  "source_commit": "5289c5d78570e086cd6f6d7ee4c154883c7adb78",
+  "core_version": "1.19.996",
+  "core_contract": "1.19.996",
+  "source_commit": "5929da0385a4022562ebd43a5a71d81400e45836",
   "source_ref": "HEAD",
-  "built_at": "2026-09-23T23:25:13.365Z",
+  "built_at": "2026-09-23T23:40:05.075Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 519,
+    "docs_redacted": 520,
     "agent_docs_stubbed": 26,
     "functional_verbatim": 2405,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2950,
-  "tree_sha256": "ca075a6b55f5c4d672bea732dad07148b251ceceabcea4a3823702e708fc28c7",
+  "file_count": 2951,
+  "tree_sha256": "cd26f1916edf3136e53591dc18c37ed45254dd805880bf4b25bc1af1c59baf93",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2717,7 +2717,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "42c93e21972b2c4cf9e69574fbd72957a80d03ce51f5a86e6d28579981de11df"
+      "sha256": "950ea34b2bb315e54fc02aa22753b3370ee009ab06727238002aa3a54e78782e"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2924,6 +2924,11 @@
       "mode": "0000644",
       "sha256": "f6d2bb1da53f03f54080b8e0aec9f63390d3343c32917b64225ac47ae4ba7b42"
     },
+    {
+      "path": "docs/recipes/render-pilot.md",
+      "mode": "0000644",
+      "sha256": "7b5f391285931a5f5e1bd31683702d534e9876d55ce5a0794e7d8eeec52fc2f3"
+    },
     {
       "path": "docs/recipes/reranking-a-goals-board.md",
       "mode": "0000644",
@@ -8182,12 +8187,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "1b91fb64b2d18219b4433b0ef6589de4488e9d7d78db9a1af45268a1f2a51944"
+      "sha256": "6d4291f9e503ac170998451d6607d15f831d39cd43aaa2443ada021e10386f13"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "6b994df4ca85e51d032ee640a4aa4b6dfb57d82581a840eb5de5f05a0b831ee3"
+      "sha256": "50946900cdbd241bfe7a8ac94d4b50b65a9adb622f2debdd2048354a2ead38e4"
     },
     {
       "path": "public-docs/index.html",
@@ -10232,7 +10237,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "34e569846f695b7f3b69061619a97ab92cda5a4262a67f6c016f31edaf984714"
+      "sha256": "899926ec43a4f0087125deada1bf430aa5f34bd1b3f32ab65ff2ffea981431a3"
     },
     {
       "path": "src/module-loader/catalog.js",

package/docs/module-api-changelog.md

@@ -2464,5 +2464,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.993 with no explicit bump. run 35929622479. (task 1002620)
   1.19.995 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.994 with no explicit bump. run 35933457545. (task 1002620)
+  1.19.996 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.995 with no explicit bump. run 35934673169. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/render-pilot.md

@@ -0,0 +1,218 @@
+# Recipe — the Render pilot, on a throwaway `mercury` clone
+
+The executable half of [task 1004142](https://cloudbongos.com/builders#/task/1004142): stand one Bongos instance up on Render, end to end, and answer the questions [task 1004183](https://cloudbongos.com/builders#/task/1004183) (the standup leg) will be written against. Governed by [ADR 0327](../adr/0327-a-cloud-host-runs-on-the-owners-account-and-the-key-is-borrowed.md); platform choice from [ADR 0323](../adr/0323-hosting-is-three-shapes-and-we-are-not-the-landlord.md).
+
+**Who runs this.** Whoever holds the Render key — under ADR 0327 that is the *project owner*, and for the pilot it is the platform owner. An agent session cannot run it unless someone has put a key in front of it, and a key must never be pasted into a chat.
+
+**The API shape below was read from Render's own reference on 2026-09-23** (`api-docs.render.com`), not inferred. Where this recipe and a live response disagree, the response wins and this file is the bug.
+
+---
+
+## 0. Before you start — three things worth knowing
+
+**The pilot costs money, and the free tier cannot prove it.** Done-when clause 4 is "its database is backed up by Render rather than by our timer". Render's **free Postgres has no backups of any kind** — no logical backups, no PITR. Only paid databases are continually backed up (3 days of recovery window on Hobby, 7 on Pro). So the pilot must run a **paid** Postgres or clause 4 is unprovable. Budget `0.1c-256mb` ($6/mo) + `0.5c-512mb` web ($7/mo), prorated for the hours the pilot is up, and tear it down when finished.
+
+**The key is account-wide, not workspace-wide.** `GET /owners` returns every workspace the key's *user* can reach, including other people's teams. This is the finding that produced ADR 0327, and step 1 exists to confirm it on live responses before anything is created.
+
+**Do not touch live `mercury`.** Row 31 is a real owner's project, serving from our box today. Clone its *repo* to a scratch repo under an account we control, and stand the clone up under a scratch slug. Nothing in this recipe writes to row 31, to `willHermesLines/mercury_bongos`, or to that owner's Render account.
+
+Set up once:
+
+```bash
+export RENDER_TOKEN=...   # in your shell, not in a file, not in chat
+export R="curl -sS -H \"Authorization: Bearer $RENDER_TOKEN\" -H 'Content-Type: application/json'"
+```
+
+Base URL is `https://api.render.com/v1`; auth is `Authorization: Bearer <key>`.
+
+---
+
+## 1. The `ownerId` guard — confirm the finding BEFORE creating anything
+
+This is the pilot's most important output, because every call the standup leg later writes depends on it.
+
+```bash
+curl -sS -H "Authorization: Bearer $RENDER_TOKEN" https://api.render.com/v1/owners | jq
+```
+
+Each element is `{ owner: { id, name, email, type }, cursor }`, where `type` is `user` or `team`.
+
+**Record:** how many workspaces come back, which are not ours, and their ids. Then pick the Bongos workspace's `id` and pin it:
+
+```bash
+export RENDER_OWNER_ID=...
+```
+
+**Then prove the hazard rather than assuming it.** List a resource *without* `ownerId` and check whether another workspace's resources appear:
+
+```bash
+curl -sS -H "Authorization: Bearer $RENDER_TOKEN" 'https://api.render.com/v1/services?limit=100' \
+  | jq '[.[].service | {id, name, ownerId}] | group_by(.ownerId) | map({ownerId: .[0].ownerId, n: length})'
+```
+
+If more than one `ownerId` comes back from a key that was only ever meant for one workspace, the finding is confirmed and the guard is mandatory. **Record the actual output either way** — a negative result is just as useful and would narrow ADR 0327's §"required guard".
+
+**The rule the standup leg must implement, whatever this shows:**
+
+- Send an explicit `ownerId` on every call. It is *required* on `POST /services` and `POST /postgres`, and it is *optional* on the list calls — which is exactly where the hazard lives.
+- Assert `ownerId` on the **response**, not the request. A request you got right tells you nothing about a response that came from elsewhere.
+- Treat missing or mismatched as a hard error. Never default it, and never derive the workspace by taking the first element of `/owners`.
+
+---
+
+## 2. Clone the repo
+
+`mercury`'s instance row carries `target_ref=willHermesLines/mercury_bongos` and `onboard_mode=adopt`. Clone it to a scratch repo you own — this is the pilot's subject and it is disposable.
+
+```bash
+git clone https://github.com/willHermesLines/mercury_bongos /tmp/mercury-clone
+cd /tmp/mercury-clone && git remote remove origin
+gh repo create <you>/render-pilot --private --source=. --push
+```
+
+**Record:** whether the repo is public or private, and under which account. That feeds the open question in step 5.
+
+---
+
+## 3. Create the Postgres
+
+```bash
+curl -sS -X POST -H "Authorization: Bearer $RENDER_TOKEN" -H 'Content-Type: application/json' \
+  https://api.render.com/v1/postgres -d '{
+    "name": "render-pilot-db",
+    "ownerId": "'"$RENDER_OWNER_ID"'",
+    "plan": "basic_256mb",
+    "region": "virginia",
+    "version": "16"
+  }' | jq
+```
+
+`plan`, `ownerId`, `name` and `version` are all required. `databaseName` and `databaseUser` are generated if omitted. **`plan` must not be `free`** — see §0. Region `virginia` is the closest US region to the current droplet (`PROVISION_REGION=nyc3`).
+
+Then read the connection string:
+
+```bash
+curl -sS -H "Authorization: Bearer $RENDER_TOKEN" \
+  https://api.render.com/v1/postgres/<postgresId>/connection-info | jq
+```
+
+Returns `password`, `internalConnectionString`, `externalConnectionString`, `psqlCommand`, and optionally the pooled variants. **Assert the `ownerId` on the create response before going further.**
+
+---
+
+## 4. Create the web service
+
+Bongos reads `DATABASE_URL` first and falls back to the `PG*` family (`src/bongos/pool.js:56`), so Render's connection string wires in directly — **none of the `PGHOST`/`PGDATABASE`/`PGUSER`/`PGPASSWORD` lines `webEnvBody` writes on the box are needed here.** That is the single biggest simplification Render buys, and it is worth stating in the standup leg's comments.
+
+The env prefix is **`BONGOS`** (`config/branding.neutral.json` → `envPrefix`). The variables below are the Render translation of `webEnvBody` in `scripts/gds/provision-units.js:192` — read that function, not this list, if the two ever disagree.
+
+```bash
+curl -sS -X POST -H "Authorization: Bearer $RENDER_TOKEN" -H 'Content-Type: application/json' \
+  https://api.render.com/v1/services -d '{
+    "type": "web_service",
+    "name": "render-pilot",
+    "ownerId": "'"$RENDER_OWNER_ID"'",
+    "repo": "https://github.com/<you>/render-pilot",
+    "branch": "main",
+    "autoDeploy": "yes",
+    "serviceDetails": {
+      "runtime": "node",
+      "plan": "0.5c-512mb",
+      "region": "virginia",
+      "healthCheckPath": "/healthz",
+      "envSpecificDetails": {
+        "buildCommand": "npm ci",
+        "startCommand": "npm start"
+      }
+    },
+    "envVars": [
+      { "key": "DATABASE_URL",            "value": "<internalConnectionString>" },
+      { "key": "BONGOS_GITHUB_CLIENT_ID", "value": "" },
+      { "key": "BONGOS_GITHUB_CLIENT_SECRET", "value": "" },
+      { "key": "BONGOS_FIRST_ADMIN",      "value": "<your-github-login>" },
+      { "key": "BONGOS_PUBLIC_ORIGIN",    "value": "https://render-pilot.onrender.com" },
+      { "key": "BONGOS_BUILDERS_ORIGIN",  "value": "https://render-pilot.onrender.com" },
+      { "key": "BONGOS_STATUS_ORIGIN",    "value": "https://render-pilot.onrender.com" },
+      { "key": "BONGOS_OAUTH_ORIGIN",     "value": "https://render-pilot.onrender.com" }
+    ]
+  }' | jq
+```
+
+Notes that matter:
+
+- **`PORT` is not set by us.** Render injects it; `webEnvBody` writes it because the box allocates ports itself. One more line the standup leg drops.
+- **The four origin overrides are load-bearing, not cosmetic.** Without them `src/branding.js` stays on neutral localhost and the hall never loads (task 1972). They must be the Render hostname, and they must all four be the same host — a single-host instance has no separate `builders.`/`status.` subdomain.
+- **`BONGOS_FIRST_ADMIN` is what seats you as Archon** on first sign-in. Omit it and the instance has no owner and you can never claim it (the 2026-07-07 `demo` regression).
+- **OAuth creds start blank** and are filled after the app exists — see step 5.
+- `PGPOOL_MAX` is read bare and still applies. On `basic_256mb` the connection ceiling is low; if the app struggles to connect, set it small (the box uses `PROVISION_INSTANCE_PGPOOL_MAX`).
+- Do **not** send a `secretFiles` entry for the GitHub App PEM until you know whether the App path is in scope for the pilot; blank OAuth is enough to prove boot.
+
+---
+
+## 5. Sign-in, and the open question the pilot exists to answer
+
+Create a GitHub OAuth app (or App) whose callback is the Render hostname, then set `BONGOS_GITHUB_CLIENT_ID` / `_SECRET` via `PATCH /services/{id}/env-vars/{key}` and redeploy.
+
+**The question ADR 0327 left for this pilot:** can Render's GitHub App reach a repo under a **personal** account rather than an org, and what does that mean for a project whose repo we do not own? Record:
+
+- Which GitHub account/org the pilot repo sits under, and whether Render's GitHub App installed onto it without friction.
+- Whether a *private* repo under someone else's personal account is reachable at all.
+- What the owner has to click, since under ADR 0327 the repo and the Render account are both theirs.
+
+This is the answer that decides whether `cloud-host` standup is one API sequence or a sequence plus a human step — and therefore how much friction `cloud-host` actually removes over `byo-host`.
+
+---
+
+## 6. Migrations
+
+Run `migrate.sh` against the Render database. Prefer a Render **job** or the service's own shell over your laptop, so the run happens from inside Render's network on the `internalConnectionString`; the `externalConnectionString` works from outside but is not what production will use.
+
+Then confirm no schema lag:
+
+```bash
+curl -sS https://render-pilot.onrender.com/version | jq
+```
+
+---
+
+## 7. Custom domain (optional for the pilot, required for the model)
+
+ADR 0323 keeps **Cloudflare DNS as the front door** and drops the Caddy site block, because Render terminates TLS. Prove the chain end to end at least once:
+
+```bash
+curl -sS -X POST -H "Authorization: Bearer $RENDER_TOKEN" -H 'Content-Type: application/json' \
+  https://api.render.com/v1/services/<serviceId>/custom-domains -d '{"name": "render-pilot.cloudbongos.com"}' | jq
+```
+
+Then point the Cloudflare record at Render and confirm the response header is **no longer `via: 1.1 Caddy`** — that header is precisely how we established the live `mercury` instance is still on our box, and its absence is the cleanest proof the front door moved.
+
+---
+
+## 8. Capture the evidence — the five done-when clauses
+
+Record each in the session log, with the actual output, not a claim that it worked:
+
+| # | Clause | Evidence |
+|---|---|---|
+| 1 | Boots | `GET /healthz` → 200, and the header does **not** say `via: 1.1 Caddy` |
+| 2 | Signs in | the OAuth round trip completes and seats you as Archon |
+| 3 | Migrations run | `migrate.sh` completes; `/version` reports no schema lag |
+| 4 | **Render backs up the DB** | a backup exists in Render's dashboard/API that we did not create — this is the clause that retires `provision-units.js`'s backup service + timer, and it needs a **paid** database |
+| 5 | GitHub App reach | written answer to §5 |
+
+Plus the three the standup leg is written from: the **exact call sequence** above with real request/response shapes, the **`ownerId` guard's live behaviour** from §1, and whether the **default plan sizes** held or mercury's larger choice was right.
+
+---
+
+## 9. Tear the clone down
+
+The pilot is disposable and it is costing money. Delete the web service, delete the Postgres, delete the scratch repo, and remove the Cloudflare record if you made one.
+
+**Note the asymmetry deliberately:** you are deleting resources in *your own* account, by hand. ADR 0327 decision 3 says the platform must never hold the ability to destroy infrastructure it does not own — `provision-teardown.js` retargets to *forgetting*, not to a Render delete call ([task 1004183](https://cloudbongos.com/builders#/task/1004183)). The fact that this step is manual is the design working, not a gap in it.
+
+---
+
+## Sources
+
+- [Render API reference](https://api-docs.render.com/reference/introduction) — endpoints, required fields, plan and region enums, read 2026-09-23
+- [Render Postgres Recovery and Backups](https://render.com/docs/postgresql-backups) — free plans have no backups; paid plans get PITR with 3-day (Hobby) / 7-day (Pro) windows

package/package-lock.json

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

package/package.json

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