toiljs 0.0.102 → 0.0.103

package/docs/introduction/design-principles.md

@@ -1,55 +1,79 @@
 # Why toil is built this way (the RSG bar)
 
-toil is opinionated on purpose. Almost every design decision traces back to one internal rubric it
-holds itself against, and this page shows the rubric and the choice each axis forces.
+toil is opinionated on purpose, and the purpose is a single one: reach top-tier ("AAA") infrastructure, and ship it as the **default**. AAA-grade tech is normally something you assemble from a dozen vendors and babysit with a team that understands distributed systems. toil makes the good version the version you get out of the box, in one framework, with zero configuration. A solo builder starts from the same baseline as a funded team.
 
-## The rubric in a paragraph
+Every decision on this page traces back to that one goal. This page is the rubric toil holds itself against, and the principles that rubric forces.
 
-**RSG** (Resilience and Scale Grade) is toil's own internal rubric for how resilient, distributed,
-fast, lean, and secure an app really is, scored as a single letter from AAA down to D. It grades
-nine axes, and the one rule that matters is this: **your grade is your weakest axis**, never the
-average and never the best. To earn AAA, all nine must be AAA at the same time. A globally edged
-frontend on a single-region database is capped by the database. A worldwide system serving a
-one-second app is capped by latency. The lowest column sets the grade, every time. RSG is not an
-external certification and no auditor issues it; it is a design mirror the team holds up to find
-the weakest link and fix it first. The full rubric lives at the repository root in
-[`RSG.md`](../../RSG.md).
+## The bar: one grade, set by the weakest link
 
-The reason for the weakest-link rule is the most common lie in this space: calling something
-"global scale" because the read path is global, while the write path is one box in one region.
-Averaging would let that one strong axis hide the weak one. The minimum refuses to.
+**RSG** (Resilience and Scale Grade) is toil's internal rubric for how resilient, distributed, fast, lean, and secure an app actually is, scored as a single letter from **AAA** down to **D**. It grades nine axes, and one rule runs the whole thing: **your grade is your weakest axis**, never the average and never the best. To earn AAA, all nine must be AAA at the same time.
 
-## The nine axes, and the one choice each one forces
+A globally edged frontend on a single-region database is capped by the database. A worldwide system running slow code is capped by latency. The lowest column sets the grade, every time.
 
-Each axis names a way a system can be weak. Each row is the single design decision toil makes so
-that axis cannot be the thing that caps it.
+That rule exists to kill the most common lie in this space: calling a system "global scale" because the read path is global, while the write path is one box in one region. Averaging lets the strong axis hide the weak one. The minimum refuses to. RSG is not an external certification and no auditor issues it; it is a mirror the team holds up to find the weakest link and fix it first. The full rubric lives at the repository root in [`RSG.md`](../../RSG.md).
+
+## The principles the bar forces
+
+Aiming for AAA-as-default is not a slogan. It forces a specific handful of decisions, and they are the reason toil looks the way it does.
+
+### 1. The good, safe, fast version is the default, not an upgrade
+
+On most stacks the resilient path is a paid tier and the secure path is a checklist you get to later. toil inverts that: the strong version is what you get **before** you configure anything.
+
+- **Post-quantum login in about one line.** Enable auth and a password is stretched through an OPRF (ristretto255) and Argon2id into a deterministic ML-DSA-44 keypair. Only the public key ever leaves the device, and login runs ML-KEM-768 mutual auth so the client verifies the server too. The password never reaches the server in a usable form. ML-DSA and ML-KEM are the NIST-standardized algorithms meant to survive a quantum computer. You do not assemble any of that; you switch it on.
+- **Tamper-proofing is on, not opt-in.** Every shipped asset carries SHA-384 Subresource Integrity plus importmap integrity, so a modified script is rejected by the browser instead of run. Nothing to remember to turn on.
+
+### 2. Batteries are included, and owned
+
+Auth, [ToilDB](../database/README.md), email, rate limiting, analytics, realtime streaming, background jobs, materialized views, scheduled jobs, sessions and cookies, an environment and secrets store: all built and owned by toil, all first-party. That is not just convenience. It is the Dependencies axis, where zero third-party code on the critical path is what earns AAA. Nothing you cannot inspect or fix sits between a request and its response.
+
+### 3. One framework, not ten vendors
+
+You write a React frontend and a TypeScript backend in **one** project. toil runs both, plus the database, near your users worldwide. The browser calls the backend through a generated, fully typed `Server` client, so there is no hand-written fetch and no drift between the two halves. One project, one deploy, one mental model, instead of a frontend host plus an API host plus a database vendor plus an auth vendor plus a queue, each glued to the next.
+
+### 4. Modern foundations, not legacy tooling
+
+toil bets on current technology rather than propping up old tooling.
+
+- **WebAssembly backends.** Your TypeScript compiles to a small, sandboxed WASM module. Because the sandbox is real, one edge box safely runs **many** tenants at once, and that multi-tenancy is exactly what makes running near everyone affordable.
+- **Post-quantum crypto** as the login default (see principle 1), not classical crypto you swap out later.
+- **End-to-end types** from the generated `Server` client, so a backend change that breaks the frontend is a compile error, not a production 500.
+- **QUIC and WebTransport** carry realtime ([@stream](../concepts/tiers.md)).
+
+### 5. Honesty about the limits
+
+toil grades itself on honesty, so the docs and the product both state limits plainly rather than overclaim.
+
+- **Distributed writes** are real in design and tested in the core: every key has one home region that orders its writes while data replicates outward for fast local reads (see [How toil is distributed](./distributed.md)). But live multi-region deployment is configuration-gated, not on by default, and the local dev database is a single in-process store. toil is **built** to distribute writes worldwide, and the mechanism is real; it is not the claim that every app is already running a live global write cluster today.
+- **Compute tiers:** the per-request edge (L1) is live and real. Regional, continental, and global-daemon tiers are opt-in and deployment-gated, not always-on for every app.
+- **Analytics** is real on the edge; the dev server returns sample data.
+- **Auth secrets** ship as clearly-insecure dev placeholders so `toiljs dev` just works. A real deployment must set its own.
+- toil is younger than the incumbents and its integration catalog is smaller. [vs other frameworks](./vs-other-frameworks.md) covers when not to reach for it.
+
+## The bar in nine axes
+
+Each axis names a way a system can be weak. Each row is the single design decision toil makes so that axis cannot be the thing that caps it.
 
 | RSG axis | What it grades | The toil design choice that hits it |
 | --- | --- | --- |
-| **Topology + distribution** | How close your code runs to users, and in how many places | Edge compute: your frontend and backend both run on nodes next to users, worldwide, not in one origin region. |
+| **Topology + distribution** | How close your code runs to users, and in how many places | Edge compute: frontend and backend both run on nodes next to users, worldwide, not in one origin region. |
 | **Availability** | What survives a failure | Cross-region failover with no single point of failure, so losing a node or a region does not take the app down. |
 | **Data path** | Where data is read and *written* (the hard one) | ToilDB's per-key-home model distributes the **writes**, not just the reads. See [How toil is distributed](./distributed.md). |
-| **Delivered p99 latency** | The end-to-end time the user actually feels (measured, under 100ms = AAA) | An allocation-free hot path, measured rather than assumed, so the response is fast for real, not just on paper. |
-| **Program performance + efficiency** | Hot-path code quality, and cost per request (no brute-forcing latency with a big server bill) | No blocking work on the request path; the fast path does no wasted work, so speed comes from the code, not from overprovisioning. |
+| **Delivered p99 latency** | The end-to-end time the user actually feels | An allocation-free hot path, measured rather than assumed, so the response is fast for real, not just on paper. |
+| **Program performance + architecture** | Hot-path code quality and cost per request (no brute-forcing latency with a big server bill) | No blocking work on the request path; speed comes from the code, not from overprovisioning. |
 | **Dependencies** | How much of your critical path you own (zero third-party on it = AAA) | An owned, batteries-included stack: nothing third-party sits on the critical request path for you to be unable to inspect or fix. |
-| **Security** | How hard the system is to break, and how bad a breach would be | Post-quantum password login (the password never reaches the server in usable form), sandboxed WebAssembly backends, and Subresource Integrity on every asset. See [Security](../concepts/security.md). |
+| **Security** | How hard the system is to break, and how bad a breach would be | Post-quantum password login, sandboxed WebAssembly backends, and Subresource Integrity on every asset. See [Security](../concepts/security.md). |
 | **Client performance + reach** | How well the shipped app runs on old and low-end devices as data grows | A lean React client: a small bundle and linear-or-better hot paths, so it stays smooth on weak hardware, not just new flagships. |
-| **Modern stack + compatibility** | Current protocols, *with* graceful fallback for older clients | HTTP/3, QUIC, and WebTransport where they fit, negotiating down cleanly so nobody one version behind gets a blank screen. |
+| **Modern stack + compatibility** | Current foundations, *with* graceful fallback for older clients | WebAssembly backends, post-quantum auth, and QUIC/WebTransport realtime, negotiating down cleanly so a client one version behind still works. |
 
 ## The punchline
 
-toil is opinionated because being AAA on **every** axis at once forces these choices. You cannot
-reach the top grade with a fast frontend on a centralized database, or a global system running
-slow code, or a modern stack that only works on the newest browser. The weakest-link rule closes
-every one of those escape hatches. Any framework that lets a single axis slip is, by its own
-honest scoring, not AAA. Holding all nine at once is the whole reason toil looks the way it does.
+toil is opinionated because being AAA on **every** axis at once forces these choices, and it delivers them as the default so you do not have to earn each one by hand. You cannot reach the top grade with a fast frontend on a centralized database, or a global system running slow code, or a modern stack that only works on the newest browser. The weakest-link rule closes every one of those escape hatches. Any framework that lets a single axis slip is, by its own honest scoring, not AAA. Holding all nine at once, out of the box, is the whole reason toil looks the way it does.
 
 ## Related
 
-- [How toil is distributed](./distributed.md): the data-path axis in depth, and why distributing
-  writes is the hard one.
-- [What makes toil hyper-scalable](./hyperscale.md): the topology, latency, and program axes in
-  practice.
+- [How toil is distributed](./distributed.md): the data-path axis in depth, and why distributing writes is the hard one.
+- [What makes toil hyper-scalable](./hyperscale.md): the topology, latency, and program axes in practice.
 - [Security](../concepts/security.md): the security axis and its hard caps.
-- [`RSG.md`](../../RSG.md) at the repository root: the full rubric, the internal mirror this page
-  summarizes.
+- [vs other frameworks](./vs-other-frameworks.md): the honest "when not to use toil".
+- [`RSG.md`](../../RSG.md) at the repository root: the full rubric, the internal mirror this page summarizes.

package/docs/introduction/distributed.md

@@ -1,6 +1,6 @@
 # How toil is distributed
 
-Distributing a website's reads is easy. Distributing its writes is the hard part almost nobody solves, and it is why "global" apps are usually only half global. Here is the problem, and how ToilDB (the database built into toil) actually distributes the writes.
+Distributing a website's reads is easy. Distributing its writes is the hard part almost nobody solves, and it is why "global" apps are usually only half global. Here is the problem, and how ToilDB (the database built into toil) is built to distribute the writes.
 
 ## Reads are easy, writes are hard
 
@@ -8,8 +8,7 @@ A read never changes anything, so you copy your data to servers worldwide and le
 
 A write is a change, and two writes to the *same thing* can collide. A counter says `10`. Tokyo and Paris both read `10`, both add one, both write `11`. The real answer was `12`, so one add vanished with no error. That is a **write conflict**.
 
-You could make every copy agree before accepting a write, but the network will eventually split (a **partition**), and the **CAP tradeoff** says that during a split you keep only two of consistency, availability, and partition tolerance. You either refuse the write (correct but unavailable) or accept it on one side and reconcile later (available but briefly inconsistent). Distributing writes is a real tradeoff to design around.
-
+You could make every copy agree before accepting a write, but the network will eventually split (a **partition**), and the **CAP tradeoff** says that during a split you keep only two of consistency, availability, and partition tolerance. You either refuse the write (correct but unavailable) or accept it on one side and reconcile later (available but briefly inconsistent). Distributing writes is a real tradeoff to design around, not a bug to patch away.
 
 ## So almost everyone centralizes the write database
 
@@ -64,7 +63,17 @@ Distributing writes is not one problem with one answer; each family is the right
 
 The per-key-home model only works if a lot of unglamorous machinery runs reliably across a flaky network, and ToilDB owns it: per-key **placement** and safe **rehoming** (a rising epoch plus a fencing token so the old owner stops the instant the new one takes over), ordered **cross-region replication** with per-stream cursors that detect and backfill gaps, **idempotent apply** so redelivered writes cannot double-count, **capacity escrow** and **tenant quotas**, and **failover** with snapshot re-seeding for a cell that has fallen too far behind. Getting all of these right at once is exactly why truly distributed websites are rare.
 
-**Still being finished:** live multi-cell **WAN routing** (wiring many real regions into one running mesh) and the full database-level **leader fencing** on the write path (the host-side leader gate is the current version). The design is settled; the last-mile host wiring is what remains.
+## What is real today, honestly
+
+This is the hard part almost nobody does, so here is a straight account of where it stands.
+
+The per-key-home model and all of its core logic (placement, rehoming, replication, idempotent apply, escrow, quotas, failover) are **built and tested**. The mechanism is real, not a diagram.
+
+What is not on by default is the **live multi-region deployment**: wiring many real regions into one running mesh (WAN routing) and the [ScyllaDB](https://www.scylladb.com/) storage that backs a production cluster are **configuration-gated**, so you switch them on for a real deployment rather than getting a live global write cluster automatically. The full database-level **leader fencing** on the write path is also still landing (a host-side leader gate is the current version). The design is settled; the last-mile host wiring is what remains.
+
+On your laptop, `toiljs dev` runs a single **in-process** database: everything homes in one place, so your code behaves exactly as it will worldwide, but the distribution only spreads out once you deploy with the multi-cell backing configured. You write your app the same way either way; that is the point.
+
+The honest one-liner: toil is **built** to distribute writes worldwide, the mechanism is real, and turning it on across live regions is a deployment step, not a rewrite of your app.
 
 ## Related
 

package/docs/introduction/how-it-works.md

@@ -1,74 +1,121 @@
 # How toil works
 
-What your project compiles into, and what happens when a user makes a request. Every term is defined as it appears.
+The whole machine, end to end: what you write, what the build produces, and what happens when a user makes a request. Every term is defined as it appears. You configure none of the moving parts below; this page just explains them.
 
-## What "build" produces
+## One project, two homes
 
-`toiljs build` turns your one TypeScript project into three outputs, because your code has two homes: the browser and the edge.
+You build a toil app as a single project, and your code lives in two places.
 
-- **Client bundle.** Your React app plus any pages toil renders ahead of time, packaged as ordinary web files (HTML, JS, CSS, images). Runs in the browser.
-- **`server.wasm`.** Your backend. You write it as normal TypeScript classes in `server/`, and the **toilscript** compiler turns it into WebAssembly. It runs on the edge, not in the browser and not in Node.
-- **Generated typed client (`shared/`).** A small browser-side client toil generates from the shape of your backend. Your React code calls a normal-looking async function, and the types line up end to end: rename a field on the server and the frontend stops compiling until you fix it.
+- **`client/`** is a **React** frontend (with Vite): file-based routing, data loaders, the usual components. It runs in the user's browser.
+- **`server/`** is your backend, written in **TypeScript with decorators**. You mark a class `@rest` to expose HTTP endpoints, `@service` for typed RPC, `@stream` for realtime, `@daemon` for background jobs, `@database`/`@collection` for stored data, and `@auth`/`@user` for login. There are no servers to provision and no routes to wire by hand: the decorator is the wiring.
 
-**WebAssembly** (WASM), in two sentences: a compact binary format that runs at close to native speed with no interpreter warm-up, and runs **sandboxed**, in a locked box that cannot open files, reach the operating system, or make network calls on its own. It touches the outside world only through the small, fixed set of functions the host hands it (read the request, build a response, query the database), which is what makes it safe to pack many apps onto one shared box. ([Why that matters for scale](./hyperscale.md).)
+That is the whole surface. One repo, one language family, one `toiljs dev`.
 
-## The request lifecycle
+## What the build produces
+
+`toiljs build` turns that one project into three kinds of output, because the browser and the edge need different things.
+
+**1. The client bundle.** Your React app plus any pages toil renders ahead of time, packaged as ordinary web files (HTML, JS, CSS, images) that run in the browser. Every shipped asset is fingerprinted with SHA-384 Subresource Integrity, so a browser refuses a file that was tampered with in transit.
+
+**2. The server WASM.** Your `server/` backend, compiled by the **toilscript** compiler into a small, sandboxed **WebAssembly** module. It runs on the edge, not in the browser and not in Node. The build emits three artifacts, one per compute tier:
+
+| Artifact | Holds | Runs |
+| --- | --- | --- |
+| `release.wasm` | the hot request path (`@rest`, `@service`) | on every request |
+| `release-stream.wasm` | realtime handlers (`@stream`) | for the life of a connection |
+| `release-cold.wasm` | background and scheduled jobs (`@daemon`) | on a timer, worldwide-singleton |
+
+**3. The generated typed client (`shared/server.ts`).** toil reads the shape of your backend and generates a small browser-side client from it. Your React code calls a normal async function (`Server.REST.*`, `Server.Stream.*`, `Server.<service>`) and the types line up end to end: rename a field on the server and the frontend stops compiling until you fix it. No hand-written `fetch`, no drift.
+
+**WebAssembly, in two sentences:** a compact binary format that runs at close to native speed with no interpreter warm-up, inside a **sandbox**, a locked box that cannot open files, reach the operating system, or make network calls on its own. It touches the outside world only through the small, fixed set of functions the host hands it (read the request, build a response, query the database), which is exactly what makes it safe to pack many apps onto one shared machine. ([Why that matters for scale](./hyperscale.md).)
+
+toilscript is a strict TypeScript dialect (explicit value types, no `any`, no runtime `RegExp`); the [decorators reference](../concepts/decorators.md) covers the full set.
+
+## The edge node
+
+Your WASM does not run on a laptop or in one central data center. It runs on the **edge**: a fleet of Rust runtime nodes spread across many cities, where each user is served by whichever node is physically closest. There is no **origin server**, no single far machine every request funnels back to, because your backend and its data are already at the edge.
 
-It all happens on the **edge node nearest the user**, with no trip to a central origin.
+Two things make this work at the density it needs.
 
-Two terms first:
+- **Multi-tenant on shared boxes.** Because each app is a tiny sandboxed module, one edge box safely runs many apps at once. That shared density is what makes putting compute near everyone affordable instead of a luxury.
+- **A custom userspace datapath.** The node handles network packets itself in userspace (multi-queue, bypassing the operating system's network stack) to keep the per-request cost low as traffic grows. **QUIC** and **WebTransport** ride on top to power realtime `@stream` connections.
 
-- **The edge** is a fleet of servers spread across many cities. A request is served by whichever node is physically closest, which means lower latency (the delay before something happens).
-- An **origin server** is the single far machine a traditional site calls back to for anything real. toil has none: your backend and its database are replicated out to the edge, so there is nothing far away to call.
+## The request lifecycle
+
+A request never leaves the neighborhood. It lands on the nearest edge node, and everything happens right there.
 
 ```mermaid
 sequenceDiagram
     participant U as User's browser
-    participant E as Nearest edge node
-    participant W as server.wasm (your handler)
+    participant E as Nearest edge node (Rust)
+    participant W as WASM host
+    participant G as Your guest module
     participant DB as ToilDB (local copy)
 
-    U->>E: Request (page or API call)
-    alt Path is a page/asset it can serve
-        E-->>U: Prerendered / SSR page or static file
-    else Path is a dynamic API call
-        E->>W: Decode bytes, call your handler
-        W->>DB: Read / write (a local, nearby copy)
-        DB-->>W: Result
-        W-->>E: Response
+    U->>E: Request over the network
+    alt Page or static asset
+        E-->>U: Prerendered / SSR page or file
+    else Dynamic API call
+        E->>W: Decode raw bytes into a Request
+        W->>G: Call your handler
+        G->>DB: Read / write nearby data
+        DB-->>G: Result
+        G-->>W: Response object
+        W-->>E: Encode to bytes
         E-->>U: Response
     end
 ```
 
 1. **The request lands on the closest edge node.** The network routes the user there automatically.
-2. **Page or code?** If the path is a prerendered page, a server-rendered page, or a static asset, the edge serves it and never wakes your backend. This is the fast path for most page loads.
-3. **Otherwise it runs your backend.** The edge decodes the raw bytes into a `Request` object and calls the single entry point of your `server.wasm`, which routes to your handler.
+2. **Page or code?** If the path is a prerendered page, a server-rendered page, or a static asset, the edge serves it directly and never wakes your backend. This is the fast path for most page loads.
+3. **Otherwise the host runs your guest.** The **WASM host** (trusted Rust) decodes the raw bytes into a `Request`, then calls into your **guest module** (your sandboxed WASM) at its single entry point, which routes to the handler you wrote.
 4. **Your handler reads and writes locally.** When it needs stored data it talks to [ToilDB](../database/README.md), which has a copy right there at the edge. No ocean crossing.
-5. **Your handler returns a `Response`,** toil encodes it back to bytes, and the edge sends it to the browser.
+5. **Your handler returns a `Response`,** the host encodes it back to bytes, and the edge sends it to the browser.
 
 The mental model for your backend: a function of the request. Bytes in, bytes out, one request at a time.
 
 ### Stateless by default
 
-A fresh copy of your handler serves each request, and the next request might be served by a node on the other side of the planet. So anything you set on a field does not survive. This is a feature: interchangeable copies with nothing to coordinate are what let the backend scale worldwide. When you need something to persist, write it to ToilDB. See the [backend overview](../backend/README.md#stateless-by-default).
+A fresh copy of your handler serves each request, and the next request might be served by a node on the other side of the planet, so anything you set on an instance field does not survive. This is a feature: interchangeable copies with nothing to coordinate are what let the backend scale worldwide by simply adding more nodes. When you need something to persist, write it to ToilDB. (See the [backend overview](../backend/README.md#stateless-by-default).)
+
+## Where the data lives: ToilDB
+
+State lives in [ToilDB](../database/README.md), toil's own database, replicated next to your code at the edge. It offers seven purpose-built families (Documents, Unique, Counter, Events, Membership, Capacity, View), so you pick the shape that fits instead of forcing everything into one table.
+
+Its hard trick is **distributed writes**. Every key has one **home region** that orders its writes, while the data replicates outward so reads stay fast and local everywhere. Most stacks distribute reads but keep writes pinned to one region; toil is built to distribute both.
+
+Be honest about where this stands. The home-region model and its core logic are real and tested, but a *live* multi-region deployment (WAN routing, the ScyllaDB backing) is configuration-gated, not switched on for every app by default, and a far read can lag its home by a few milliseconds (eventual consistency). Your local `toiljs dev` database is a single in-process store. The write model and its trade-off are covered in [how toil is distributed](./distributed.md).
+
+## The compute tiers
+
+Not all backend code has the same lifespan. toil sorts it into four tiers, and the build assigns each piece automatically from its decorator.
+
+| Tier | What runs here | Status |
+| --- | --- | --- |
+| **L1** | the stateless per-request hot path (`@rest`, `@service`) | live, the default |
+| **L2 / L3** | longer-lived regional and continental work, `@stream` realtime | opt-in, deployment-gated |
+| **L4** | a single worldwide `@daemon` for background and scheduled jobs | opt-in, deployment-gated |
+
+Most apps live entirely on **L1**, and that tier is real and running today. L2 through L4 are built and opt-in, not always-on for every app. Full detail is on the [tiers page](../concepts/tiers.md).
 
 ## The pieces
 
-Five parts make up a running toil app; you have now met all of them.
+Five parts make up a running toil app. You have now met all of them.
 
 | Piece | What it is | Where it runs |
 | --- | --- | --- |
-| **React client** | Your frontend UI, the client bundle from the build. | The user's browser |
-| **toilscript backend** | Your TypeScript backend compiled to `server.wasm`. | The edge |
-| **The Dacely edge** | The Rust runtime that terminates the connection, serves pages, and runs your WASM. | Servers in many cities |
-| **ToilDB** | The globally distributed database, replicated next to your code. | The edge |
-| **The four tiers** | Where and for how long a piece of backend code lives. | L1 nearest, up to L4 worldwide |
+| **React client** | your frontend UI, the client bundle from the build | the user's browser |
+| **toilscript backend** | your `server/` code compiled to sandboxed WASM | the edge |
+| **The edge node** | the Rust runtime that terminates the connection, serves pages, and runs your WASM | servers in many cities |
+| **ToilDB** | the database with distributed writes, replicated next to your code | the edge |
+| **The four tiers** | where and for how long a piece of backend code lives | L1 nearest, up to L4 worldwide |
 
-Most of your backend is the stateless, per-request handler above (tier **L1**). Long-lived connections (L2/L3) and single-worldwide scheduled jobs (L4 daemons) run on other tiers. Full detail, and how the build assigns them, is on the [tiers page](../concepts/tiers.md).
+None of these need configuring to get the good version. You write React and decorated TypeScript; the build, the edge, and the database are the default, not a stack you assemble and babysit.
 
 ## Related
 
 - [Backend overview](../backend/README.md): the request/response model and the sandbox in depth.
-- [The database (ToilDB)](../database/README.md): where persistent, shared state lives.
+- [The database (ToilDB)](../database/README.md): families, home regions, and eventual consistency.
 - [Compute tiers](../concepts/tiers.md): L1 request, L2/L3 stream, L4 daemon.
+- [Realtime streams](../realtime/streams.md) and [background daemons](../background/daemons.md): the other two artifacts.
 - [What makes toil hyper-scalable](./hyperscale.md): why this design serves the planet cheaply.

package/docs/introduction/hyperscale.md

@@ -2,50 +2,69 @@
 
 **Hyper-scale** is serving very large, worldwide traffic at low latency without rebuilding your app as it grows. The test: when traffic goes from a thousand users to a hundred million across every continent, do you rewrite the system, or just run more of it?
 
-Most stacks scale the easy half (serving pages and cached reads from many places) but leave the hard half (writes, where data actually changes) in one region, so they slow down at once when enough far-away users start writing. toil scales both halves out together. It promises a design where scaling is cheap, adding more identical edge nodes with no central part everything funnels through, not a specific requests-per-second number.
+Plenty of stacks can reach that scale if you throw money at it: dedicated infrastructure per app, a rented vendor for each moving part, and an ops team to keep the seams from tearing. toil was built for the same scale from the other direction: **cheaply and efficiently**. The whole design is aimed at making top-tier reach the default, not a budget line. Cost is the point of this page.
 
-## The mechanisms
+## Why hyper-scale is normally expensive
 
-**1. Compute next to the user.** toil has no origin server. Your `server.wasm` and its database are replicated to the [edge](../concepts/tiers.md) and run on the node nearest each user, so there is no slow hop to a faraway box. This is the biggest latency win, and the rest of the design exists to support it.
+Running near your users usually means paying for it in three places at once:
+
+- **Dedicated infrastructure per app.** Each app gets its own boxes, its own containers, its own always-warm capacity. Spread that across many cities and you are renting a lot of mostly-idle hardware.
+- **A far-away origin.** Most stacks serve pages from everywhere but send anything real back to one origin server in one region. Every write and every dynamic call pays for a round trip across the planet.
+- **A centralized write database.** The reads scale out; the writes funnel into one primary in one city. That box is both the bottleneck and the thing you overprovision to keep ahead of.
+
+Each of those is a cost multiplier, and they stack. toil removes all three.
+
+## How toil makes it cheap
+
+Three mechanisms do the work, and they reinforce each other.
+
+**1. Density: one box safely runs many apps.** Your backend compiles to its own tiny, [sandboxed](./how-it-works.md#what-build-produces) WebAssembly module that starts fast, runs at near-native speed, and cannot touch another tenant's files, memory, or network. Because the sandbox is that tight, **one shared edge box holds many apps at once** instead of one app per machine. That multi-tenant density is what makes running near everyone affordable: you are not renting dedicated hardware in fifty cities, you are one tenant on boxes that are already there and already busy.
+
+**2. Edge locality: no trip to a central origin.** toil has no origin server. Every request runs on the [edge](../concepts/tiers.md) node nearest the user, on the per-request **L1 hot path**: the network hands the bytes to the WASM host, your handler runs, a response goes back, all in one place. There is no slow hop to a faraway box to make the request "real." Removing the origin removes both the latency and the standing cost of running one.
+
+**3. Local reads, homed writes.** The data your handlers share lives in [ToilDB](../database/README.md), replicated outward so every edge node reads from a copy right next to it. Writes are not centralized either: every key has one **home region** that orders its writes, while the data replicates out for fast local reads. So you get nearby reads everywhere without a single primary that every write funnels through, and without paying to overprovision one. The mechanism and its honest trade-off (eventual consistency) are in [how toil is distributed](./distributed.md).
 
 ```mermaid
 flowchart LR
-    subgraph Origin["Everything funnels to one origin"]
+    subgraph Origin["The expensive shape: everything funnels to one origin"]
         direction TB
         A1["User (Tokyo)"] -->|slow| O[("Origin + DB<br/>(Virginia)")]
         A2["User (Paris)"] -->|slow| O
         A3["User (Sydney)"] -->|slow| O
     end
-    subgraph Toil["Edge + distributed DB scales out"]
+    subgraph Toil["The cheap shape: shared edge + homed writes"]
         direction TB
-        B1["User (Tokyo)"] --> E1["Edge + data (Tokyo)"]
-        B2["User (Paris)"] --> E2["Edge + data (Paris)"]
-        B3["User (Sydney)"] --> E3["Edge + data (Sydney)"]
+        B1["User (Tokyo)"] --> E1["Edge box + local data (Tokyo)"]
+        B2["User (Paris)"] --> E2["Edge box + local data (Paris)"]
+        B3["User (Sydney)"] --> E3["Edge box + local data (Sydney)"]
         E1 <-.->|"replicate"| E2
         E2 <-.->|"replicate"| E3
     end
 ```
 
-The left side has one hot center every user drags a request to and back from, a bottleneck no amount of caching removes. The right side has no center: add a city, add an edge node.
+The left side has one hot center every user drags a request to and back from, plus its dedicated fleet, a cost no amount of caching removes. The right side has no center and no per-app fleet: add a city, add a shared box, and every tenant on it gets that city for near nothing.
 
-**2. WASM isolation and density.** Each site compiles to its own tiny, [sandboxed](./how-it-works.md#what-build-produces) WASM module that starts fast and cannot touch another tenant's files, memory, or network. Hard per-request limits (a memory cap in the tens of MiB, a **hard compute cap** that cuts off a looping handler, rate limits, and hostile-wasm containment) let one box safely hold many tenants at once, which is what makes compute in many cities affordable instead of a luxury.
+## Why this is cheap, in one line each
 
-**3. Allocation-free hot path.** The code that runs on every request wastes nothing: no per-request allocations, and no garbage-collection pauses (so no random latency spikes under load). This earns latency with lean code rather than by overprovisioning hardware to hide slow code, which is a bar toil holds itself to explicitly ([the RSG rubric](./design-principles.md)).
+- **Density** means the cost of an edge presence is split across many tenants, not carried by one app.
+- **Edge locality** means no origin fleet to run and no cross-planet round trip to pay for on every real request.
+- **No dedicated infra** means you scale by adding interchangeable shared nodes, not by standing up a new stack per app.
 
-**4. Stateless tier over a distributed database.** A fresh copy of your handler serves each request and keeps nothing, so every node is interchangeable and you scale out purely by adding more. The data they share lives in [ToilDB](../database/README.md), which distributes **writes** too, not just reads, so there is no single box every write funnels through. The write mechanism and its honest trade-off (eventual consistency) are in [how toil is distributed](./distributed.md).
+Take any one away and a cost reappears: no density and running near everyone is a luxury again; no edge locality and you are back to paying for an origin; a centralized write path and the database caps you and gets overprovisioned to compensate.
 
-**5. Modern transport.** The edge speaks HTTP/3 over QUIC (with graceful fallback to HTTP/2 and HTTP/1.1, plus WebTransport for realtime), and its networking is tuned to keep the connection-level cost of each request low as traffic grows. You configure none of it.
+## An honest note
 
-The five reinforce each other: take any one away and a bottleneck reappears. No density and edge compute is too expensive to spread; no distributed writes and the database caps you; a wasteful hot path and you are back to buying latency with servers.
+This is the design, not a benchmark. Real throughput and latency depend on your hardware, where your users are, how your data is shaped, and how your handler is written. toil removes the central bottlenecks and keeps per-request cost low; it does not make a slow handler fast or repeal the speed of light between continents.
 
-## An honest note on numbers
+A few things are honestly staged, not "already everywhere":
 
-This describes a design, not a benchmark: real throughput and latency depend on your hardware, where your users are, how your data is shaped, and how your handler is written, and toil removes central bottlenecks and keeps per-request cost low without making a slow handler fast or repealing the speed of light between continents.
+- The per-request **L1** edge path is live and real. The **L2** regional, **L3** continental, and **L4** global-daemon tiers are opt-in and deployment-gated, not always-on for every app. See the [tiers page](../concepts/tiers.md).
+- ToilDB's home-region write model and its core logic are real and tested, but **live multi-cell deployment** (WAN routing, the ScyllaDB backing) is configuration-gated, not on by default. The local dev database is a single in-process store. [How toil is distributed](./distributed.md) is honest about what is finished.
 
 ## Related
 
 - [How toil is distributed](./distributed.md): distributing the writes, the hard problem this rests on.
-- [Why toil is built this way (the RSG bar)](./design-principles.md): the efficiency check behind the hot path.
 - [Compute tiers](../concepts/tiers.md): L1 through L4, and the stateless request model.
 - [How toil works](./how-it-works.md): the build outputs and the request lifecycle.
 - [The database (ToilDB)](../database/README.md): families, homes, and eventual consistency.
+- [Why toil is built this way (the RSG bar)](./design-principles.md): the efficiency check behind the hot path.

package/docs/introduction/modern-stack.md

@@ -1,36 +1,81 @@
 # The modern stack: what toil gives you that others do not
 
-Most frameworks give you a way to write code and then send you shopping: a database, an auth provider, email, a rate limiter, analytics, a realtime service, a job runner, all wired together and kept in sync by you. toil owns those parts instead: built in, and on from the first line. This page is the catalog of what ships; for how the edge and distribution actually work, see [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
+Most frameworks give you a way to write code and then send you shopping: a database, an auth provider, email, a rate limiter, analytics, a realtime service, a job runner, each its own account, bill, and SDK, all wired together and kept in sync by you. toil owns those parts instead. They ship in one framework, they are toil's own (nothing third-party sits on your critical path), and they are on from the first line with zero configuration. This page is the full catalog.
 
-## What is built in
+The point is not that toil bundles a lot. It is that the good version is the default version: a solo builder gets the same baseline as a funded team, without assembling or babysitting ten vendors. For how the edge and worldwide distribution actually work, see [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
+
+## The backend, built in
+
+Your TypeScript backend declares what it needs with a decorator or a one-line config flag. toil provides the machinery.
 
 | Feature | What it is | Why it matters |
 | --- | --- | --- |
-| Edge compute over HTTP/3 | Frontend and backend both run on servers in many cities, over HTTP/3 with automatic fallback to HTTP/2 or HTTP/1.1. | Code runs next to the user, so there is no slow round trip to one origin. |
-| [ToilDB](../database/README.md) | A global database with no connection string and seven families (documents, unique, counter, events, capacity, membership, view). | Distributes writes, not just reads, so a thousand servers can write at once without a single-region bottleneck (trade: eventual consistency). |
-| [Post-quantum auth](../auth/README.md) | Password login via `server: { auth: true }`; the password becomes an ML-DSA-44 key in the browser and the server stores only the public key. | The password never crosses the wire in a replayable form, so a breached server yields no usable passwords, and there is no identity vendor to rent. |
-| Automatic SRI | A SHA-384 fingerprint on every local script, preload, and stylesheet, plus an import map covering the whole module graph. | Tampered assets simply do not run, even if a CDN or cache hop is compromised. |
-| [Email](../services/email.md) | `EmailService.send(...)` or a reusable `EmailTemplate` with `{{placeholder}}` bodies, through a provider you configure once. | Verification codes, resets, and receipts are one call: validated, per-tenant capped, and off the worker while the provider replies. |
+| [Post-quantum auth](../auth/README.md) | Password login via `server: { auth: true }`. The password is stretched (OPRF + Argon2id) into an ML-DSA-44 keypair in the browser; only the public key is sent; login runs ML-KEM-768 mutual auth so the client also verifies the server. | Real post-quantum cryptography (the NIST-standardized algorithms), in about one line. The password never reaches the server in a usable form, so a breached server yields nothing replayable, and there is no identity vendor to rent. |
+| [ToilDB](../database/README.md) | A global database with no connection string and seven purpose-built families. Its differentiator is distributed writes: every key has one home region that orders its writes, while data replicates outward for fast local reads. | Distributes writes, not just reads, so a thousand servers can write at once with no single-region bottleneck. This is the hard part almost nobody does (trade: eventual consistency, a far read can lag a few ms). |
+| [Email](../services/email.md) | `EmailService.send(...)`, or a reusable `EmailTemplate` with `{{placeholder}}` bodies, through a provider you configure once. | Verification codes, resets, and receipts are one validated, per-tenant-capped call, off the worker while the provider replies. |
 | [Rate limiting](../services/ratelimit.md) | `@ratelimit` on a route, counted at the edge in an exact cross-worker limiter keyed on the caller's network address. | Over-limit clients are rejected before your code runs, blunting brute-force and spam. |
-| [Analytics and time series](../services/analytics.md) | The `Analytics` global reads your site's own counters: `self()` for a snapshot, `series(metric, range)` for a graph. | A real usage dashboard with no extra code and no analytics vendor, correct across every edge location. |
-| [Realtime streaming](../realtime/README.md) | A `@stream` class with `@connect`/`@message`/`@close`/`@disconnect` hooks, opened from React with `useChannel`; WebTransport in production, WebSocket in dev. | A resident instance stays alive per connection and remembers state next to the user (chat, presence, progress). |
-| [Daemons and @derive](../background/README.md) | `@daemon` runs one global background worker on a schedule (interval or cron) with lease-based failover; `@derive` re-runs when its source data changes to refresh a View. | Nightly jobs and rollups run once globally, with no cron server, queue, or leader election to run yourself. |
-| [Owned globals](../services/README.md) | No-import cookies (read/set, sign or encrypt), crypto (hash, HMAC, AES, random), time (the edge clock), and environment/secrets. | Your request's small dependencies live in one system, and your compiled program carries no credential. |
-| [Toolchain](../cli/README.md) | `toiljs create` scaffolding, a shared ESLint config, Prettier plus a decorator-aware plugin, an editor plugin, one CLI, and `toiljs doctor --fix`. | Set up for you and wired by types, so a server change is a compile error at your desk, not a production bug. |
-| LLM-friendly docs | A machine-readable `llms.txt` plus a generated `.toil/docs/` folder and pointer files (`CLAUDE.md`, `AGENTS.md`, editor rules), refreshed on every build. | An assistant reads your current conventions instead of guessing from stale training. |
+| [Analytics](../services/analytics.md) | The `Analytics` global reads your site's own counters: `self()` for a snapshot, `series(metric, range)` for a graph. | A real usage dashboard with no extra code and no analytics vendor. |
+| [Realtime streaming](../realtime/README.md) | A `@stream` class with `@connect` / `@message` / `@close` / `@disconnect` hooks, opened from React with `useChannel`. WebTransport (over QUIC) in production, WebSocket in dev. | A resident instance stays alive per connection and remembers state next to the user: chat, presence, live progress. |
+| [Background jobs (`@daemon`)](../background/daemons.md) | One global background worker on a schedule (interval or cron), with lease-based failover so exactly one instance runs worldwide. | Nightly jobs run once globally, with no cron server, queue, or leader election to run yourself. |
+| [Scheduled jobs (`@scheduled`)](../background/daemons.md) | A method that fires on an interval or cron expression, driven by the same lease so it runs once across the fleet. | Recurring work (cleanup, digests, syncs) without standing up a scheduler. |
+| [Materialized views (`@derive`)](../background/derive.md) | A function that re-runs when its source data changes and writes the result into a View family. | Rollups and denormalized read models stay fresh automatically, so reads are cheap without a hand-rolled pipeline. |
+| [Sessions and cookies](../services/cookies.md) | No-import cookie read/set, signed or encrypted, plus the session layer that backs `@auth`. | Login state and small per-user data without a session store to provision. |
+| [Environment and secrets](../services/environment.md) | A per-tenant environment store for config and secrets, read at the edge, never baked into the shipped WASM. | Your compiled program carries no credential; secrets live in one place, disjoint from public config. |
+
+### The seven ToilDB families
+
+One database, seven shapes, each tuned to its access pattern rather than bent out of a single table model.
 
-## Built in versus assemble it yourself
+| Family | For |
+| --- | --- |
+| [Documents](../database/documents.md) | General structured records. |
+| [Unique](../database/unique.md) | Uniqueness constraints (one email, one handle). |
+| [Counter](../database/counters.md) | High-throughput increments (views, likes, quotas). |
+| [Events](../database/events.md) | Append-only logs and feeds. |
+| [Membership](../database/membership.md) | Set membership and relationships (who is in what). |
+| [Capacity](../database/capacity.md) | Bounded resources and seat/slot allocation. |
+| [View](../database/views.md) | Read models materialized by `@derive`. |
+
+## The frontend, built in
+
+The React client is Vite-fast and typed end to end. The pieces that usually take a build config, a fetch layer, and an SEO plugin are already wired.
+
+| Feature | What it is | Why it matters |
+| --- | --- | --- |
+| [File routing](../frontend/routing.md) | Routes are files under `client/routes/`. The tree is your URL map. | No router config to hand-maintain; add a file, get a route. |
+| [Loaders with revalidation](../frontend/data-fetching.md) | A route `loader` fetches its data before render and revalidates on demand. | Data arrives with the page, not after a client-side waterfall. |
+| [Two rendering paths](../frontend/rendering.md) | Build-time prerender for SEO by default, plus opt-in edge SSR with `export const ssr = true`, both hydrated with `hydrateRoot`. | Static-fast pages where you can, live server rendering where you need it, one codebase. |
+| [Typed `Server` client](../frontend/data-fetching.md) | A generated client (`Server.REST.*`, `Server.Stream.*`, `Server.<service>`) so the browser calls the backend with end-to-end types. | No hand-written fetch and no drift: rename a field on the server and the frontend stops compiling until you fix it. |
+| [Image with LQIP](../frontend/images.md) | A built-in `Image` component with blur / low-quality placeholders and reserved aspect ratio. | Fast, layout-stable images with no CLS and no separate image service. |
+| [Metadata and SEO](../frontend/metadata.md) | Per-route title, description, canonical, and Open Graph (including `og:image`), baked into the served HTML head. | Correct SEO and share cards in view-source, not assembled by JavaScript after load. |
+| [Page search](../frontend/search.md) | A static index of each route's title, description, keywords, and Open Graph, generated at build. | In-app search with no search vendor (see the caveat below). |
+| [SHA-384 SRI](../concepts/security.md) | Subresource Integrity plus importmap integrity on every shipped script, preload, and stylesheet, across the whole module graph. | A tampered asset simply does not run, even if a CDN or cache hop is compromised. |
+
+## Owned, not rented
+
+Everything above is toil's own code on your critical path, not a black box you cannot inspect, patch, or secure. That is the difference the table below draws.
 
 | Capability | toil (built in, zero setup) | Typical stack (you assemble it) |
 | --- | --- | --- |
-| Edge and transport | Frontend and backend worldwide over HTTP/3 | A separate edge product, often reads-only |
 | Database | ToilDB: global, distributed writes, seven families | A managed database, usually single-region for writes |
 | Auth | Post-quantum login; the server holds no password | A rented identity provider or hand-rolled hashing |
 | Email, rate limiting, analytics | Built-in primitives, one call each | A separate SDK or vendor per capability |
-| Realtime and background | `@stream`, `@daemon`, `@derive` | A realtime service plus a cron server, queue, and leader election |
-| Asset integrity and toolchain | Automatic SRI, ESLint/Prettier/editor plugins, one CLI | Manual or skipped; configured and maintained by you |
+| Realtime and background | `@stream`, `@daemon`, `@scheduled`, `@derive` | A realtime service plus a cron server, queue, and leader election |
+| Sessions, secrets, cookies | Owned globals, no store to provision | A session store and a secrets manager to run |
+| Frontend integrity and SEO | Automatic SHA-384 SRI, Image/LQIP, metadata, page search | Plugins and services bolted on per concern |
 | Critical-path ownership | The core is toil's own | A mix of vendors you cannot inspect or fix |
 
+Honest boundary: "owned" means the core of a working app is toil's, not that outside services are banned. Call a payment provider or another API and you still can.
+
+## The honest caveats
+
+toil grades itself on honesty, so read these before you count on anything.
+
+- **Distributed writes are built, live multi-cell is config-gated.** The home-region model and its core logic are real and tested, but live multi-region deployment (WAN routing, the ScyllaDB backing) is opt-in, not on by default. The local dev database is a single in-process store. toil is built to distribute writes worldwide; not every app is running a live global write cluster today.
+- **Analytics is a dev stub locally.** It is real on the edge; the local dev server returns sample data.
+- **Auth secrets ship as dev placeholders.** The session HMAC, OPRF seed, and ML-KEM key are clearly-insecure placeholders so `toiljs dev` just works. A real deployment must set its own (per-tenant auto-generation at domain registration is the plan).
+- **Page search indexes static metadata only.** Routes whose metadata comes from a dynamic `generateMetadata` are not in the index.
+
 ## Why it is all a default
 
-None of this is an upgrade you unlock later. toil grades itself against [RSG](./design-principles.md) (Resilience and Scale Grade), whose one rule is that your grade is your weakest axis, never the average, so these batteries exist to keep any single axis from quietly capping the whole. Where the honest trade fits your project (ToilDB is not general SQL, the server language is a strict TypeScript subset, the catalog is younger than long-established platforms), the built-in stack is the whole point; [Why toil](./why-toil.md) says where it does not.
+None of this is an upgrade you unlock later. toil grades itself against [RSG](./design-principles.md) (Resilience and Scale Grade), whose one rule is that your grade is your weakest axis, never the average, so these batteries exist to keep any single axis from quietly capping the whole. Where the honest trade fits your project (ToilDB is not general SQL, the server language is a strict TypeScript subset, the catalog is younger than long-established platforms), the built-in stack is the whole point. [Why toil](./why-toil.md) says where it does not.