@bongos/core 1.17.1 → 1.17.2

package/docs/recipes/cloudbongos-staging-gate.md

@@ -1,139 +0,0 @@
-# Recipe — stand up staging.cloudbongos.com (password-locked landing-page preview)
-
-> Brings up **staging.cloudbongos.com** — a password-locked preview of the Cloud Bongos
-> landing **gate** (`brand/cloud-bongos/gate`, the cel-glass + `> cloud bongos` terminal
-> prototype from tasks [#1532](https://example.com/builders#/task/1532) +
-> [#1534](https://example.com/builders#/task/1534)). This is the future
-> cloudbongos.com landing page, parked behind a shared password so it can be shared for
-> review before it goes public. Task [#1540](https://example.com/builders#/task/1540).
-
-## Architecture (what we're building)
-
-The **cheapest possible** host: no app process, no new port, no new certificate. Caddy
-**static-serves** the brand-art folder that already ships in the checkout, behind HTTP
-basic auth (the password lock).
-
-| Thing | Value |
-|---|---|
-| URL | `https://staging.cloudbongos.com` (redirects to `/gate/`, where the gate is served) |
-| Served by | Caddy `file_server`, web root `/home/lars/example/brand/cloud-bongos` |
-| Lock | HTTP basic auth — username `bongos` + a shared password |
-| TLS | the existing `*.cloudbongos.com` origin + Cloudflare edge certs (already cover it) |
-| Cost | **$0/mo** — same droplet, no process, no port |
-
-Why static (not a reverse-proxy block like the others): the gate is plain HTML/CSS/JS +
-PNGs. There is nothing to run. Caddy serves the files directly.
-
-## Why the web root is the brand folder, not `gate/`
-
-The gate page lives at `gate/index.html` but references its art **relative to `/gate/`** —
-sprites **beside it** (`sprites/…`, `dispmaps/…`) and the world **one level up**
-(`../world/…`). So the folder that must be the web root is `brand/cloud-bongos/` (the
-parent), and the page must actually be served **at `/gate/`** for those relative paths to
-resolve. The Caddy block therefore **redirects the apex `/` → `/gate/`** (`redir / /gate/`)
-rather than serving the gate's HTML at the apex.
-
-> History (task 1545): the block first tried to serve the gate AT the apex via
-> `rewrite / /gate/index.html` plus per-folder rewrites (`/dispmaps/*` → `/gate/dispmaps/*`).
-> That was fragile — when the gate gained `sprites/` (task 1541) those 404'd at the apex
-> (the browser asked `/sprites/*`, not `/gate/sprites/*`). The redirect serves the gate at
-> its native path so **all** relative folders resolve, with nothing to keep in sync.
-
-## Phase ① — DNS (Cloudflare dashboard, ~30 s)
-
-cloudbongos.com is on Cloudflare. Add **one** record:
-
-1. Cloudflare → pick the **cloudbongos.com** zone → **DNS** → **Add record**.
-2. Type **A**, Name **`staging`**, IPv4 **`REDACTED_IP`**, Proxy status **Proxied** (orange cloud ON), TTL Auto.
-3. Save.
-
-No new certificate is needed — the cloudbongos origin cert is already
-`cloudbongos.com, *.cloudbongos.com`, and Cloudflare's edge cert covers
-`staging.cloudbongos.com` too.
-
-## Phase ② — the password (droplet, one-time)
-
-The `staging.cloudbongos.com` block ships in `infra/Caddyfile` with a **dummy** bcrypt hash,
-so no real secret is in git. Generate the real hash and keep it handy for Phase ③:
-
-```bash
-caddy hash-password --plaintext 'YOUR_PASSWORD'
-#  → prints  $2a$14$………   (copy the whole thing)
-```
-
-Username is `bongos`; the password is whatever you hashed. The real hash lives **only** in
-the live `/etc/caddy/Caddyfile` — never committed.
-
-## Phase ③ — apply the Caddy block + reload
-
-The `staging.cloudbongos.com` block is already in `infra/Caddyfile`. The live
-`/etc/caddy/Caddyfile` has drifted slightly from the repo copy (comment wording + block
-order), so **do not blindly `cp` the whole file** — append just the new block, swap the
-dummy hash for the real one, then reload:
-
-```bash
-cd /home/lars/example
-# 1. append only the staging.cloudbongos.com block (idempotent: skip if present)
-grep -q 'staging.cloudbongos.com {' /etc/caddy/Caddyfile || \
-  awk '/^# ── Cloud Bongos — STAGING/{p=1} p' infra/Caddyfile >> /etc/caddy/Caddyfile
-
-# 2. replace the dummy hash: open the file, find the staging.cloudbongos.com
-#    block's `basic_auth { bongos … }` line, and paste the real $2a$… hash from
-#    Phase ② in place of the dummy one.
-sudo nano /etc/caddy/Caddyfile          # or any editor
-
-# 3. let the caddy user READ the static files. Caddy runs as user `caddy`, which
-#    cannot traverse the 750 home dir — without this, authenticated requests get
-#    403. Everything under /home/lars/example is already world-readable, so
-#    ONLY the home dir itself needs to be traversable (one-time, persists):
-sudo setfacl -m u:caddy:x /home/lars 2>/dev/null \
-  || sudo chmod o+x /home/lars          # fallback if the `acl` package is absent
-#    o+x allows traverse, not listing. For strict least-privilege instead of the
-#    broad o+x, `sudo apt-get install -y acl` first so the setfacl path is taken.
-
-# 4. validate (as root — it must read the 640 root:caddy origin key), then reload
-sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
-sudo systemctl reload caddy             # fails closed on a bad config
-```
-
-> A bad config makes `reload` error out and **keep serving the old config** — the live
-> sites never go down. Leaving the dummy hash in place is also safe: it just means no one
-> can log in (fail-closed) until you paste the real one.
-
-## Phase ④ — verify
-
-```bash
-# from anywhere:
-curl -sS -o /dev/null -w '%{http_code}\n' https://staging.cloudbongos.com/          # 401 (locked) ✓
-curl -sS -u bongos:YOUR_PASSWORD https://staging.cloudbongos.com/ | grep -o 'cloud bongos'   # matches ✓
-curl -sS -o /dev/null -w '%{http_code}\n' -u bongos:YOUR_PASSWORD \
-     https://staging.cloudbongos.com/world/assets/plates/scene-establishing.png      # 200 (art loads) ✓
-```
-
-Then open `https://staging.cloudbongos.com` in **Chrome or Edge** (the live-glass
-refraction needs Chromium `backdrop-filter` + SVG displacement; Safari falls back to a
-plain frost, which still looks fine). The browser shows a username/password box — enter
-`bongos` + the password — and the gate appears.
-
-## Rotating / removing the password
-
-- **Change the password:** regenerate the hash (Phase ②), edit the `bongos …` line in the
-  `staging.cloudbongos.com` block of `/etc/caddy/Caddyfile`, `sudo systemctl reload caddy`.
-- **Take the site down:** delete the `staging.cloudbongos.com` block from
-  `/etc/caddy/Caddyfile`, `sudo systemctl reload caddy`, and remove the Cloudflare
-  `staging` A record.
-
-## Later — promote to the real public landing page
-
-When the gate is approved as the public landing page, that is a **separate task**: fold the
-gate into `public-landing/index.html` (served at the cloudbongos.com apex by
-`platform-server.js`), bring the world art it needs under a served path, and drop the basic
-auth. Until then, this staging block is the review surface and `public-landing/index.html`
-stays the minimal buddha placeholder.
-
-## Files this recipe uses
-
-- `infra/Caddyfile` — the `staging.cloudbongos.com` block (ships with a dummy hash; the
-  live file carries the real one).
-- `brand/cloud-bongos/gate/` — the gate prototype (`index.html` + `dispmaps/`).
-- `brand/cloud-bongos/world/assets/` — the art the gate refracts.

package/docs/recipes/cloudbongos-standup.md

@@ -1,111 +0,0 @@
-# Recipe — stand up cloudbongos.com (Customer 0, the vanilla dogfood instance)
-
-> Brings **cloudbongos.com** live as a real Cloud Bongos instance: the vanilla brand, its own database, no game code — Cloud Bongos running on Cloud Bongos (the C8 proof, [ADR 0062](../adr/<redacted>.md) §2, task [#1374](https://example.com/builders#/task/1374) + the proof ship [#1206](https://example.com/builders#/task/1206)). Owner-only inputs are tracked in blocker [#40](https://example.com/builders#/blocker/40).
-
-## Architecture (what we're building)
-
-Same droplet as OTB (`REDACTED_IP`), **separate process + separate database**, no new monthly cost. One checkout (`/home/lars/example`) runs **two** processes:
-
-| Instance | Entrypoint | Brand | Port | DB | Domain |
-|---|---|---|---|---|---|
-| OTB (game) | `server.js` | `config/branding.json` (default) | 3000 | `example` | example.com |
-| **Cloud Bongos** | `src/platform-server.js` | `config/branding.cloudbongos.json` (via `GDS_BRANDING_FILE`) | **3002** | **`cloudbongos`** | **cloudbongos.com** |
-
-The only difference between the two processes is **environment** — no divergent clone. The brand switch is `src/branding.js`'s `GDS_BRANDING_FILE` knob (task 1374). The landing page is served at the apex by `platform-server.js`; the Hall + status ride `builders.`/`status.` (host routing in `src/bongos/serve-internal.js`).
-
-## Phase ① — DNS  ✅ done
-
-Domain on Cloudflare (Free plan), nameservers switched, **SSL/TLS = Full (strict)**, three **proxied** A records → `REDACTED_IP`:
-`cloudbongos.com` (`@`), `builders`, `status`. (Until the origin cert + process are up, the site shows a TLS error — expected.)
-
-## Phase ② — GitHub OAuth App (builder sign-in)
-
-GitHub → Settings → Developer settings → **OAuth Apps** → **New OAuth App**:
-- **Application name:** `Cloud Bongos`
-- **Homepage URL:** `https://cloudbongos.com`
-- **Authorization callback URL:** `https://cloudbongos.com/api/gds/auth/web/callback` (PINNED — `auth.js` `WEB_REDIRECT_ORIGIN`; sign-in begun on `builders.` still calls back to the apex)
-- **Enable Device Flow:** ✅ (the CLI login uses it)
-
-Copy the **Client ID** + generate a **Client Secret** → they go in `/etc/cloudbongos/web.env` as `CLOUDBONGOS_GITHUB_CLIENT_ID` / `CLOUDBONGOS_GITHUB_CLIENT_SECRET` (resolved as `<ENVPREFIX>_GITHUB_*`; vanilla envPrefix = `CLOUDBONGOS`).
-
-## Phase ③ — Cloudflare Origin Certificate (own domain → own cert)
-
-cloudbongos.com is a different domain, so it needs its **own** Origin Cert (the example cert's SANs don't cover it). Cloudflare → **SSL/TLS → Origin Server → Create Certificate**:
-- Hostnames: `cloudbongos.com` **and** `*.cloudbongos.com`
-- Let Cloudflare generate the key; **copy both** the certificate and the private key.
-
-Install on the droplet (operator). **Caddy runs as user `caddy` and must be able to READ the key** — match the existing `origin.key` ownership (`640 root:caddy`). A root-only `600` key makes Caddy's reload fail and loop (the OTB site keeps serving the old config, but the new site never comes up — seen during the first bring-up). The `.crt` can be world-readable.
-```bash
-sudo install -m 644 -g caddy /dev/stdin /etc/caddy/cloudbongos-origin.crt   # paste cert, Ctrl-D
-sudo install -m 640 -g caddy /dev/stdin /etc/caddy/cloudbongos-origin.key   # paste key,  Ctrl-D
-```
-
-## Phase ④ — Droplet bring-up (operator)
-
-```bash
-# 1. The instance database (peer auth via the local socket, same as OTB)
-createdb cloudbongos
-
-# 2. GDS-only schema (skips migrations/game/*.sql — no game tables on this instance)
-cd /home/lars/example
-PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh
-
-# 3. Secrets file (from infra/cloudbongos.env.example)
-sudo mkdir -p /etc/cloudbongos
-sudo cp infra/cloudbongos.env.example /etc/cloudbongos/web.env
-sudo $EDITOR /etc/cloudbongos/web.env       # fill the OAuth client id + secret
-sudo chmod 600 /etc/cloudbongos/web.env && sudo chown lars:lars /etc/cloudbongos/web.env
-
-# 4. systemd service (from infra/cloudbongos.service)
-sudo cp infra/cloudbongos.service /etc/systemd/system/cloudbongos.service
-sudo systemctl daemon-reload
-sudo systemctl enable --now cloudbongos
-curl -sS http://127.0.0.1:3002/healthz        # → "ok"
-
-# 5. Caddy — the three cloudbongos blocks are in infra/Caddyfile; apply + reload
-sudo cp infra/Caddyfile /etc/caddy/Caddyfile  # or merge the cloudbongos blocks in
-sudo systemctl reload caddy
-```
-
-## Phase ⑤ — Verify + first sign-in
-
-```bash
-curl -sS https://cloudbongos.com/healthz              # "ok" (through Cloudflare now)
-curl -sS https://cloudbongos.com/ | grep -o 'cloud bongos'   # the landing
-```
-- `https://cloudbongos.com` → the buddha landing.
-- `https://builders.cloudbongos.com` → the Hall. **Sign in with GitHub.** Because the pack sets `firstAdmin: "example-owner"`, that first sign-in auto-seats example-owner as **Owner/Archon** on the (empty) cloudbongos DB — no manual step (`auth.js` `maybeSeatFirstAdmin`).
-- `https://status.cloudbongos.com` → the dashboard.
-
-## Deploy automation (important — updated for the dedicated box)
-
-> **This changed with [ADR 0126](../adr/<redacted>.md).** cloudbongos.com no longer runs co-tenant on the OTB box. It runs on its **own dedicated droplet** (`REDACTED_IP`, checkout `/home/lars/cloudbongos`) and tracks `main` via a **pull-based `systemd` timer** — [ADR 0129](../adr/<redacted>.md), task [#2064](https://example.com/builders#/task/2064). The co-hosting box's CI deploy no longer touches it. (The historical "wire `sudo systemctl restart cloudbongos` into `~/deploy.sh`" note applied only while it was a co-tenant.)
-
-Once the box exists, the deploy is [`scripts/deploy/deploy-cloudbongos.sh`](../../scripts/deploy/deploy-cloudbongos.sh) fired by [`infra/cloudbongos-deploy.timer`](../../infra/cloudbongos-deploy.timer) every ~2 min: `git fetch` + reset `origin/main` → `npm ci` (if the lockfile changed) → `PGDATABASE=cloudbongos MEDUSA_GDS_ONLY=1 ./scripts/migrate.sh` → `sudo systemctl restart cloudbongos` → 3002 healthz. After the first install it **self-heals** (each run refreshes `/home/lars/deploy.sh` + the units from the checkout).
-
-**One-time bootstrap** (operator, over SSH to the box — the box can't install its own first deploy automation). Run once the deploy files are on `main`:
-```bash
-# Executed as a STABLE copy outside the checkout (so `git reset --hard` can't
-# corrupt the running script — see ADR 0129):
-sudo -u lars install -m 0755 /home/lars/cloudbongos/scripts/deploy/deploy-cloudbongos.sh /home/lars/deploy.sh
-sudo install -m 0644 /home/lars/cloudbongos/infra/cloudbongos-deploy.service /etc/systemd/system/
-sudo install -m 0644 /home/lars/cloudbongos/infra/cloudbongos-deploy.timer   /etc/systemd/system/
-sudo systemctl daemon-reload
-sudo systemctl enable --now cloudbongos-deploy.timer
-# Verify: one forced run brings the box current + smokes the chain
-sudo -u lars FORCE_DEPLOY=1 /home/lars/deploy.sh
-systemctl list-timers cloudbongos-deploy.timer --no-pager
-curl -sS https://cloudbongos.com/healthz     # → "ok"
-```
-
-## The C8 proof (task 1206) — ✅ DONE 2026-06-21
-
-With the instance live, **one real task** went through the full lifecycle **on cloudbongos.com** — claim → grade (the real 4-worker panel, PASS) → merge → ship, credits awarded — carrying zero game code: **cloudbongos task [#1](https://example.com/builders#/task/1)** (under version CB-V1), the `GDS_MODULES_FILE` fix that made Customer-0 advertise its modules correctly all-off. That shipped task is the C8 acceptance ("the GDS builds itself"). Full record + the operational mechanics for driving cloudbongos.com's GDS from the CLI: [2026-06-21 — C8 self-build proof](../session-logs/<redacted>.md). Closes task [#1206](https://example.com/builders#/task/1206).
-
-## Files this recipe uses
-
-- `config/branding.cloudbongos.json` — the customer-0 brand pack (deltas over `config/branding.neutral.json`).
-- `src/branding.js` — the `GDS_BRANDING_FILE` selector.
-- `src/platform-server.js` — GDS-only entrypoint + the apex landing mount.
-- `public-landing/index.html` — the landing page (mascot at `public-landing/buddha.png`).
-- `infra/cloudbongos.service`, `infra/cloudbongos.env.example`, `infra/Caddyfile` (the cloudbongos blocks).

package/docs/recipes/parallel-load-results-2026-05-30.md

@@ -1,63 +0,0 @@
-# Parallel-load test results — 2026-05-30 ([#272](https://example.com/builders#/task/272), criterion C6)
-
-> **Harness:** [`tests/parallel-load.mjs`](../../tests/parallel-load.mjs) · **Procedure:** [parallel-load-test.md](parallel-load-test.md) · **Target:** seeded staging ([#262](https://example.com/builders#/task/262)) at `http://127.0.0.1:3001` on the droplet (direct, bypassing Cloudflare).
-
-This is the live run that closes **[#272](https://example.com/builders#/task/272) (V3.R53)** and satisfies criterion **C6 — parallel-safe-under-load**. It exercises the deterministic claim concurrency audited in [#269](https://example.com/builders#/task/269) (the `claimTask()` transaction + `uniq_active_claim_per_task` index) against a real running server under concurrent load.
-
-## Bottom line
-
-**Across both runs: ZERO `server_error` (5xx), ZERO races, ZERO anomalies.** Every claim resolved to exactly one of: `success`, `collision` (409 — exactly-one-wins), or `throttled` (429 — the rate limiter cleanly shedding excess writes). Staging's journal logged **0** 5xx responses over the full window. C6's bar — "all claims succeed or 409 cleanly; no 500s, no race conditions" — holds, with the added finding that excess write load is shed cleanly via 429 rather than ever degrading into a race or crash.
-
-## Run A — sustained 30-minute run (the [#272](https://example.com/builders#/task/272) acceptance run)
-
-`--workers 5 --duration 1800 --work-ms 150` (natural claim→work→release→repeat loop across distinct tasks):
-
-| metric | value |
-|---|---|
-| wall | 1800.1s (30 min) |
-| claim attempts | 144 |
-| success | 13 |
-| collision (409, exactly-one-wins) | 8 (5.6%) |
-| throttled (429) | 123 |
-| **server_error (5xx)** | **0** |
-| client_error / other | 0 / 0 |
-| anomalies | 0 |
-| staging 5xx in journal | 0 |
-
-The system stayed healthy (`/healthz` 200) for the entire 30 minutes with no degradation. Low attempt volume is expected: the per-IP rate limiter (below) caps writes, and releases that get throttled leave tasks `active`, draining the claimable pool — so workers spend most cycles idling on an empty queue rather than hammering. That's the system behaving correctly under its own backpressure.
-
-## Run B — high-intensity contention burst (forces collisions)
-
-`--workers 5 --duration 25 --work-ms 100 --contend` (all 5 workers race the SAME task — the canonical "two builders, one task" case):
-
-| metric | value |
-|---|---|
-| claim attempts | 2733 |
-| success | 8 |
-| collision (409, exactly-one-wins) | 17 |
-| throttled (429) | 2708 |
-| **server_error (5xx)** | **0** |
-| anomalies | 0 |
-
-This is the direct demonstration of the C6 invariant: when multiple workers race the same task row, **exactly one wins and the rest get a clean 409 `ALREADY_CLAIMED`** — never two winners, never a 5xx.
-
-## The rate limiter (a relevant, healthy finding)
-
-`src/bongos/middleware/rate-limit.js` enforces **30 writes / 60s per-IP** and **60 writes / 60s per-session** on write methods (GET is unlimited). Because all simulated workers run from the droplet's single IP, the per-IP limit binds first, so most write attempts under load return **429** (`throttled` above). For a parallel-safety test this is a *positive* result: under sustained overload the server sheds excess writes cleanly (429 + `Retry-After`) instead of racing or 500ing. To exercise the claim logic at higher volume in a future run, raise the limit on staging or distribute workers across IPs.
-
-## Harness fixes made while running this (committed under [#272](https://example.com/builders#/task/272))
-
-Running against the real server surfaced live-path bugs the self-test (mock) couldn't:
-
-- **claimable parsing:** the harness read `.data.tasks`, but `GET /tasks/claimable` returns `{ claimable: [...] }` → it saw 0 tasks and never claimed. Fixed to read `.claimable` (with `.tasks` fallback).
-- **429 classification:** 429 was bucketed as `other` / flagged as a release anomaly. Added a dedicated `throttled` outcome (clean) so the report and the pass/fail conclusion are accurate.
-- **`--contend` mode:** added so workers can be pointed at one task to demonstrate exactly-one-wins collisions on demand (Run B).
-
-## Reproduce
-
-```bash
-# On the droplet (staging seeded per #262, service running, alphanumeric token minted):
-cd /home/lars/example-staging
-BASE_URL=http://127.0.0.1:3001 TOKEN=<redacted> node tests/parallel-load.mjs --workers 5 --duration 1800 --work-ms 150
-# add --contend to force same-task collisions
-```

package/docs/recipes/parallel-load-test.md

@@ -1,32 +0,0 @@
-# Parallel-load test — exercising claim concurrency under N builders
-
-> **Harness:** [`tests/parallel-load.mjs`](../../tests/parallel-load.mjs) (built under prep task [#472](https://example.com/builders#/task/472)).
-> **Live run:** criterion **C6** task **[#272](https://example.com/builders#/task/272)** (V3.R53) — a 30-min, 5-builder run against **staging**, gated on **[#262](https://example.com/builders#/task/262)** (staging data seeding).
-
-The harness spawns N concurrent simulated "builder" loops that hammer the GDS claim lifecycle (claim → simulated work → release → repeat) and classifies every claim outcome into `success` / `collision` (clean 409/refusal) / `server_error` (the anomaly we hunt) / `client_error` / `other`. It validates the deterministic claim concurrency C6 requires — the same `claimTask()` transaction + `uniq_active_claim_per_task` index audited in [multi-builder-merge.md](multi-builder-merge.md).
-
-## Self-test (CI-safe, no network)
-
-```bash
-node tests/parallel-load.mjs                      # defaults: 5 workers, 60s
-node tests/parallel-load.mjs --workers 5 --duration 3 --work-ms 50
-```
-
-With no `BASE_URL`, the harness drives an **in-process mock server** whose claim semantics mirror the DB (one active claim per task; touches-overlap → conflict). The board deliberately has two tasks sharing a path so collisions are *forced*, then asserts: ≥1 success, ≥1 collision, **zero** server_error, no invariant violation, and that attempts == sum of classes. Exit 0 = harness accounting proven correct. This runs in CI without a droplet.
-
-## Live run against staging ([#272](https://example.com/builders#/task/272) — once [#262](https://example.com/builders#/task/262) has seeded staging)
-
-```bash
-# Get builder tokens (one or more simulated builders share the load).
-# NEVER point this at production — it mutates real claim/task state. The
-# harness refuses a prod example.com host unless you pass --i-know.
-BASE_URL=https://staging.example.com \
-TOKENS=$tokA,$tokB,$tokC,$tokD,$tokE \
-  node tests/parallel-load.mjs --workers 5 --duration 1800
-```
-
-`#272` acceptance: run 30 min (`--duration 1800`); **every claim resolves to `success` or a clean `collision` — zero `server_error`, no races**; the report's throughput + collision-rate are the deliverable. A single anomaly (any 5xx, thrown error, or invariant violation) exits 1 and fails the run.
-
-## Why the split (prep [#472](https://example.com/builders#/task/472) vs live [#272](https://example.com/builders#/task/272))
-
-`#272`'s done-when explicitly requires a seeded staging environment, which `#262` (backlog) provides. Rather than block the runnable harness behind infra, [#472](https://example.com/builders#/task/472) built + self-validated the harness now; [#272](https://example.com/builders#/task/272) stays the live-staging run. When [#262](https://example.com/builders#/task/262) ships, point the harness at staging per above to close [#272](https://example.com/builders#/task/272) and satisfy C6.