@bongos/core 1.19.1072 → 1.19.1074

package/docs/adr/0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md

@@ -0,0 +1,94 @@
+# ADR 0345 — We host every project's hall, and its app deploys where the owner chooses
+
+- **Status:** accepted
+- **Date:** 2026-09-28
+- **Task:** [task 1004349](https://cloudbongos.com/builders#/task/1004349) (goal 1000106 — working area 1, Project creation)
+- **Deciders:** Lars (Archon) made decisions 1 to 5 and the rulings on the two older tasks. Claude ran the measurements behind decisions 6 and 7 and wrote the record.
+- **Supersedes in part:** [ADR 0323](0323-hosting-is-three-shapes-and-we-are-not-the-landlord.md) §2 ("DigitalOcean hosts hubs only") · [ADR 0327](0327-a-cloud-host-runs-on-the-owners-account-and-the-key-is-borrowed.md) (what a cloud-host puts on the owner's Render account: the app, not the hall)
+- **Keeps:** ADR 0327 §2 (the key is borrowed, never stored) and §3 (we never destroy an owner's infrastructure) · ADR 0323 §4 (Cloudflare is the front door) and §6 (Bongos stores env var names, never values; [task 1004062](https://cloudbongos.com/builders#/task/1004062))
+- **Related:** [ADR 0145](0145-free-hosted-project-tier-isolation-and-domain-separation.md) (Finding 1, which decision 6 re-opens) · [ADR 0285](0285-a-shared-box-holds-about-twelve-projects-per-gb-and-memory-is-the-wall.md) (the box's ceiling) · [`docs/recipes/render-pilot.md`](../recipes/render-pilot.md)
+- **Gates:** [task 1004350](https://cloudbongos.com/builders#/task/1004350) · [task 1004351](https://cloudbongos.com/builders#/task/1004351) · [task 1004352](https://cloudbongos.com/builders#/task/1004352) · [task 1004353](https://cloudbongos.com/builders#/task/1004353) · [task 1004184](https://cloudbongos.com/builders#/task/1004184)
+- **Filed by this ADR:** [task 1004357](https://cloudbongos.com/builders#/task/1004357) (the hub cookie reaches project halls; decision 6)
+
+## Context
+
+ADR 0323 decided the platform should not host other people's projects, and planned to move every project off the shared DigitalOcean box to Render. ADR 0327 then put each project on its owner's own Render account, with the key borrowed for setup. Under both, what went to Render was the **whole Bongos instance**: the project's Builders Hall.
+
+The pilot ([task 1004142](https://cloudbongos.com/builders#/task/1004142)) proved that works. It also made plain what it asks of a new owner. Before they have seen their Builders Hall, they need a paid Render account, a Render API key and a hosting bill, and all of that is just to reach the place where the work happens.
+
+A project really has two things that run:
+
+- **The hall** is where the project is built: tasks, builders, the ledger. It runs Bongos, which we write.
+- **The app** is what the project builds. It runs the owner's code, and most owners already have somewhere they deploy it.
+
+The owner's direction, 2026-09-28: those two go to different places.
+
+## Decision
+
+### 1. We host every project's hall
+
+A project's Builders Hall runs on our shared server, the way the live projects already do. Creating a project does not need a platform account, a key or a bill. We pay for it, about $0.80 per project per month (ADR 0285's measurement).
+
+This reverses ADR 0323 §2's plan to move the projects off the box. The `cloud-host` shape keeps its stored value and now means **the hall is hosted by us**.
+
+### 2. The hall's address is the owner's choice
+
+The owner chooses between one of our addresses (`<handle>.cloudbongos.com`) and their own domain, as the wizard's Address step offers today. The hall is hosted by us either way.
+
+### 3. The owner picks where their app deploys, and Render is the first option
+
+The setup wizard gets a step that asks where the app runs. At launch the only option is **Render**. The step is laid out so that a second platform is an added option, not a redesign.
+
+Choosing Render creates **the app** on the owner's own Render account. It does not create the hall. The mechanism is ADR 0327's, unchanged: the key is borrowed for setup, cleared within one run and never stored; the owner picks the workspace; nothing in their account is ever deleted by us. After setup, Render redeploys the app from Git by itself, so Bongos needs no credential to keep it running.
+
+### 4. "Decide later" is allowed
+
+An owner can create a project without connecting Render. The hall is created either way. They can connect Render later from the project page ([task 1004184](https://cloudbongos.com/builders#/task/1004184)).
+
+### 5. No project is moved
+
+Nothing happens to an existing project whose owner has not asked. There is no bulk move to Render. An owner who wants their app on Render connects it themselves.
+
+### 6. Our addresses need the hub cookie fixed, and the owner's own domain does not (measured)
+
+ADR 0145 Finding 1 is live, and this decision makes it permanent rather than temporary:
+
+- The hub scopes its cookies to the whole domain. `GET https://cloudbongos.com/api/gds/auth/web/start` answers `Set-Cookie: <redacted>; Domain=.cloudbongos.com`, and the session cookie takes the same options (`sessionCookieDomainOpts`, `src/bongos/routes/auth.js`). So the browser sends a hub builder's session to every `*.cloudbongos.com` host, and a project's hall is one of them.
+- A hall runs code from its project's repository. `src/module-loader/loader.js` discovers modules under the **instance root** as well as the core, and loads their routes into the hall process. For an adopted project, the instance root is the owner's repository.
+
+So anyone who can land code in a project's repository can read the hub session of any hub builder who opens that hall. ADR 0323 closed this by removing its precondition, customer halls on our domain. Decision 1 brings the precondition back for good, so the fix is now required rather than optional. It is filed as [task 1004357](https://cloudbongos.com/builders#/task/1004357), which carries both remedies: host-only hub cookies, or a separate registrable domain for project halls.
+
+**A hall on the owner's own domain is safe today.** The browser never sends our cookie to a different registrable domain. Until task 1004357 ships, a new project should get one of our addresses only if the owner rules that it may. Task 1004357's done-when says so.
+
+### 7. Capacity: at the ceiling the wizard says so, and a resize raises it (measured)
+
+The box's ceiling is `floor((usable MiB − fixed) / 80)` (`modules/provisioning/capacity.js`), about fifteen on today's 2 GB box. At the ceiling, `modules/provisioning/capacity-gate.js` refuses the create request with `box_full` **before** any row or intent exists, so the owner is told at once rather than minutes later. The queued resize to 2 vCPU / 4 GB ([task 1003923](https://cloudbongos.com/builders#/task/1003923)) raises the ceiling by itself, because it is computed from measured memory.
+
+The resize is **not a prerequisite** for this decision. There are well under fifteen live projects. It becomes the next step when the count nears the ceiling, and `box_full` is the signal.
+
+## Rulings on the tasks this reverses
+
+- **[Task 1004184](https://cloudbongos.com/builders#/task/1004184), "move the remaining cloud-host projects to Render": re-scoped, not abandoned.** It now lets an existing project connect Render for its app from its project page, reusing the wizard's flow.
+- **[Task 1004185](https://cloudbongos.com/builders#/task/1004185), "delete the landlord-only provisioning legs": on hold, waiting on the owner.** Under decision 1, most of what it would delete is what serves the halls.
+
+## What "cloud host" means now
+
+| Stored value | Owner-facing label | Meaning |
+|---|---|---|
+| `cloud-host` | **Hosted by us** | The hall runs on our server, at our address or the owner's domain. |
+| `byo-host` | Your own host | The owner runs the hall themselves. Unchanged, and not offered by the wizard. |
+
+Where the **app** deploys is a separate fact about the project (for example "Render", or "not connected yet"). It is not a hosting shape. [Task 1004350](https://cloudbongos.com/builders#/task/1004350) records it on the project row.
+
+## Consequences
+
+- **We are the landlord for halls again, and not for apps.** The provisioning legs ADR 0323 wanted to delete (systemd units, per-instance accounts, Caddy snippets, backup timers, the capacity ceiling) stay load-bearing. What we never host is the owner's product.
+- **Our cost per project is the hall's, about $0.80 a month.** The owner's Render bill is for their app, and Render bills them directly. The fleet cost ledger's two columns (ours and the owner's, [task 1004148](https://cloudbongos.com/builders#/task/1004148)) already separate the two.
+- **Task 1004183's Render code is aimed at the app.** [Task 1004350](https://cloudbongos.com/builders#/task/1004350) points it there: a web service from the project's own repository, a database only if the owner asks, and adopt for an app already on Render.
+- **The Render deploy page ([task 1004270](https://cloudbongos.com/builders#/task/1004270)) already fits.** It manages an app that deploys through Render, from that project's hall.
+- **Security work moves up the queue.** Task 1004357 is the one piece of this direction that protects the hub from the projects it hosts.
+
+## Alternatives considered
+
+- **Keep ADR 0327: the hall on the owner's Render account.** Rejected by the owner. It puts a platform account, a key and a bill in front of a new owner before they reach their hall, and it makes us support Bongos running on a platform we do not control.
+- **Offer several app platforms at launch.** Deferred. Render is the only one piloted, and each platform is its own setup flow. Vercel and Netlify owners can still link their repository on that platform's own site, and Bongos just pushes code (ADR 0323 §5).

package/docs/adr/README.md

@@ -432,7 +432,8 @@ This keeps the decision history honest and traceable.
 | 0338 | [**Modules travel through a Bongos-hosted store, and an acquired module keeps working forever** ([task 1003782](https://cloudbongos.com/builders#/task/1003782), goal 1000091 — working area 5, owner Will). A module had no transport of its own: it reached an instance only inside the core (ADR 0107 §6) or in the instance's repo. Weighed npm packages, a Bongos-hosted store and git refs against the four things area 5's criteria require — entitlement before install, a per-version score, a tester channel, and a delist that stops distribution. npm and git refs fail entitlement and delist by construction. **D1:** Cloud Bongos hosts the store; a module version is a tarball + hash manifest in the same format `package-core.js` already emits (same `isPublishable()` gate), registry rows on the control-plane DB, artifacts in the already-paid DO Spaces bucket, served by the control plane only after an entitlement + channel check; free modules take the same path at price zero; install/update verify hashes on arrival; modules' own npm deps still travel via npm (ADR 0138). No new fixed cost. **D2 (owner):** delisting, author withdrawal or deletion removes a module from the catalog and stops new acquisitions and updates, but **an acquired module keeps working forever** — the store never disables or removes an installed copy and a delist never revokes an entitlement; the holder is told no more updates will come. Security issues are not a special case; a remote kill switch would need a superseding ADR. Rejected: npm, git refs, remote disable on delist.](0338-modules-travel-through-a-bongos-hosted-store.md) | modules / distribution / economy |
 | 0339 | [**A project's owner upgrades it, and a hosted project hands off to the hub's door** ([task 1004174](https://cloudbongos.com/builders#/task/1004174), goal 1000090 — the owner's ruling of 2026-09-26 that only a project's owner upgrades it). Amends ADR 0293 D5. **D1:** the deploy door's preview and move routes admit the OWNER of a tenant row (`co-tenant`/`cloud-host`) for that row, asked first; every other caller meets the unmodified `core.pin.move` gate, so a non-owner's refusal is unchanged whether or not the id exists and the widening can only admit. **D2:** the platform's own row stays atom-only. **D3:** `GET /core-update` names `<hub>/deploy?project=<slug>` on a federated project, and the hosted hall's banner and rail hand off there (the dead local Deploy item is gone); the hub's `/deploy` shell admits a project owner through `alsoAdmits: 'isProjectOwner'`. **D4:** the intent's actor records the door (`api:owner:<id>` / `api:archon:<id>`), both attributed on the `core_upgrades` ledger. Rejected: a tenant-side API that performs the upgrade, granting the system atom to owners, owners moving the platform row. ADR 0328 Phase 1 (task 1004159) should fold this gate into `requireProjectOwner`.](0339-a-projects-owner-upgrades-it-and-a-hosted-project-hands-off-to-the-hub-door.md) | provisioning / deploy door / permissions |
 | 0340 | [**Every hall takes its update from Settings, and /deploy is the platform hall's page** ([task 1004296](https://cloudbongos.com/builders#/task/1004296), goal 1000090 — the owner's 2026-09-25 asks: a Settings version panel "just like iOS", and /deploy only in the Bongos hall). Amends ADR 0339 D3 and the reach of ADR 0293's page. **D1:** Settings → Software update in the core — the running core, the newest release the runner's own channel rule allows, and what each version in between carries from the newest package's release notes; every signed-in builder reads it, and "up to date" is said only from an answer. **D2:** its Update button leads to the door (local /deploy, the hub's /deploy?project=, or a `bongos upgrade` sentence), drawn only for holders of core.pin.move. **D3:** /deploy 302s to Settings on a hall without the provisioning module. **D4:** the banner links Settings everywhere but the platform; the rail is no longer re-pointed; /core-update drops deploy_url. **D5:** the registry reader moved into the core (module-api readPackageRegistry). Rejected: a second copy of the two-step door, gating the panel on the atom, a "moved" page.](0340-every-hall-takes-its-update-from-settings-and-deploy-is-the-platform-halls-page.md) | deploy door / settings / core update |
-| 0341 | [**The page is the unit of Tweak Mode: one tweak task per page round, its status derived from the ledger** ([task 1004332](https://cloudbongos.com/builders#/task/1004332), goal 1000095 — BV2.TW03, the owner's Tweak Mode decisions of 2026-09-27 written down). Amends ADR 0233 (a proposal becomes a page batch); replaces the artist-review-on-ship cascade rule. **D1-D3:** every record keys on a page id from docs/page-inventory.json; a round is a `page-tweak` task (`source_ref page-tweak/<page>/r<n>`, 30c, catch-all goal, one open round per page under an advisory lock); TW04 commits docs/page-readings.json (line keys, placed/shared/unplaced, reading and files hashes, no browser in ship-check). **D4:** the draft, the frozen batch, the apply record and each send-back are fenced blocks on the task, parsed by a pure pages.js; unplaced rewrites file their own engineer task; copy_no_cms.mjs grows in reviewed diffs. **D5-D6:** artist-craft builders claim with a web claim; anyone asks, and a page ask is a copy_desk_flags row with scope page. **D7:** round states are derived; a passed grade on a page tweak holds at completed until the artist approves (the confirm) or sends it back to the apply queue, with the owner override as the escape hatch. **D8:** count, status, changelog, drift (against the last round's lines_after), N of M per surface, the tally and the recommendation order are all reads. **D9:** the cascade rule is removed; hasCopyOrVisualWork stays for the reader lens. **D10:** the reviews paid 30c per task on the estimate stream (withheld under cost-plus-only) plus the session's cost-plus; an approved page pays its artist 30c on a new artist lane that cost-plus-only does not suppress, payee from the claims table, applier keeps its session reward. **D11-D12:** the route table; a dependency-free .docx with content-control line tags, refused as structure_changed, wrong_page or reading_moved. Twelve builder picks are listed for the owner to confirm.](0341-the-page-is-the-unit-of-tweak-mode.md) | copy desk / artist loop / economy |
+| 0341 | [**The page is the unit of Tweak Mode: one tweak task per page round, its status derived from the ledger** ([task 1004332](https://cloudbongos.com/builders#/task/1004332), goal 1000095 — BV2.TW03, the owner's Tweak Mode decisions of 2026-09-27 written down). Amends ADR 0233 (a proposal becomes a page batch); replaces the artist-review-on-ship cascade rule. **D1-D3:** every record keys on a page id from docs/page-inventory.json; a round is a `page-tweak` task (`source_ref page-tweak/<page>/r<n>`, 30c, catch-all goal, one open round per page under an advisory lock); TW04 commits docs/page-readings.json (line keys, placed/shared/unplaced, reading and files hashes, no browser in ship-check). **D4:** the draft, the frozen batch, the apply record and each send-back are fenced blocks on the task, parsed by a pure pages.js; unplaced rewrites file their own engineer task; copy_no_cms.mjs grows in reviewed diffs. **D5-D6:** artist-craft builders claim with a web claim; anyone asks, and a page ask is a copy_desk_flags row with scope page. **D7:** round states are derived; a passed grade on a page tweak holds at completed until the artist approves (the confirm) or sends it back to the apply queue, with the owner override as the escape hatch. **D8:** count, status, changelog, drift (against the last round's lines_after), N of M per surface, the tally and the recommendation order are all reads. **D9:** the cascade rule is removed; hasCopyOrVisualWork stays for the reader lens. **D10:** the reviews paid 30c per task on the estimate stream (withheld under cost-plus-only) plus the session's cost-plus; an approved page pays its artist 30c on a new artist lane that cost-plus-only does not suppress, payee from the claims table, applier keeps its session reward. **D11-D12:** the route table; a dependency-free .docx with content-control line tags, refused as structure_changed, wrong_page or reading_moved. Twelve builder picks were listed and the owner confirmed them all on 2026-09-28.](0341-the-page-is-the-unit-of-tweak-mode.md) | copy desk / artist loop / economy |
 | 0342 | [**Module categories are eight fixed parents, with narrow sub-categories an author proposes and Metic+ approves** ([task 1003783](https://cloudbongos.com/builders#/task/1003783), goal 1000091 — working area 5, owner Will). The owner's cap of ten listed modules needs a comparable set, and nothing carried a category. **D1:** eight parents derived from the live roster — Work & planning, Team & people, Quality & review, Money, Communication, Pages & design, Hosting & deploy, Knowledge — for browsing only; the cap never applies to a parent. **D2:** the sub-category (the narrow set a buyer chooses between, e.g. "Stripe payments") is where the cap, ranking and comparison run. **D3 (owner):** an author proposes a sub-category and a Metic+ builder approves, renames or merges it, because free-naming would split one comparable set into near-duplicates and the cap would never bite; a pending module lists under its parent and counts toward no cap. **D4:** one sub-category per module. Rejected: free naming, Metic+-only creation, a flat list, parent-level caps.](0342-module-categories-are-eight-parents-with-approved-sub-categories.md) | modules / store / economy |
 | 0343 | [**A module's score is a security gate, then an average of parts every buyer can see** ([task 1003790](https://cloudbongos.com/builders#/task/1003790), goal 1000091 — working area 5, owner Will). No module score existed; the floor, ranking and cap all derive from this one. **D1:** five parts, each 0–100 per version — Security and Tests day one; Install, Reliability (from real installs) and Tester feedback later. **D2 (owner):** failing Security means not listed, never averaged in. **D3 (owner):** overall = unweighted average of the other parts that have data; a missing part is left out, not zero. **D4 (owner):** every part's score is shown to buyers beside the overall, so they can pick the module strongest where they care (tasks 1003798/1003799). **D5:** a version without real-world data is labelled "New". **D6:** price is never an input; the Metic+ override/delist sits on top and is audited. Rejected: security in the average, day-one weights, a single number, missing-as-zero.](0343-a-module-score-is-a-security-gate-then-an-average-of-visible-parts.md) | modules / store / quality |
 | 0344 | [**A tester is a project that opts in once; an untested version reaches everyone after seven days** ([task 1003801](https://cloudbongos.com/builders#/task/1003801), goal 1000091 — working area 5, owner Will). Settles "willing user" for criterion `wa5-staged-rollout`. **D1 (owner):** a project's own admin switches on "tester" once and gets tester versions of every module it has, with a per-module "general only" override; never on by default; a builder cannot opt in someone else's project. **D2:** first releases and updates alike go to testers first. **D3 (owner):** a version moves to general after seven days if it still passes the security gate and tests, tested or not; the promotion gate may promote earlier or hold on evidence, never forever. **D4:** testers pay the normal price; any tester discount is area 8's call, named not decided. **D5:** tester installs, errors and crashes feed the score (ADR 0343). Rejected: per-module-only opt-in, one all-or-nothing switch, waiting for a tester, releasing at once.](0344-a-tester-is-a-project-that-opts-in-once.md) | modules / store / rollout |
+| 0345 | [**We host every project's hall, and its app deploys where the owner chooses** ([task 1004349](https://cloudbongos.com/builders#/task/1004349), goal 1000106 — working area 1, owner Lars). Reverses ADR 0323 §2 and the hall half of ADR 0327. **D1 (owner):** every project's Builders Hall runs on our shared server; `cloud-host` now means "hosted by us". **D2 (owner):** the hall's address is ours or the owner's own domain. **D3 (owner):** the setup wizard asks where the APP deploys; Render only at launch; choosing it creates the app on the owner's own Render account with ADR 0327's borrowed key. **D4 (owner):** "decide later" is allowed. **D5 (owner):** no project is moved. **D6 (measured):** ADR 0145 Finding 1 is live — the hub cookie is `Domain=.cloudbongos.com` and a hall loads modules from its own repo — so our-address halls need task 1004357; an owner domain is safe. **D7 (measured):** at the ceiling the create route refuses `box_full` up front, and the resize is not a prerequisite. Task 1004184 re-scoped, task 1004185 on hold.](0345-we-host-every-projects-hall-and-its-app-deploys-where-the-owner-chooses.md) | hosting / provisioning / security |