@bongos/core 1.19.1073 → 1.19.1075

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

@@ -436,3 +436,4 @@ This keeps the decision history honest and traceable.
 | 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 |