toiljs 0.0.102 → 0.0.104

package/docs/introduction/README.md

@@ -1,41 +1,57 @@
 # Understanding toil
 
-This section is the "why." It explains what toil is, the problem it solves, how it works underneath, and why it is built the way it is. If you read nothing else first, read this: it is what turns "another framework" into "oh, that is the point."
+toil is one framework for a whole web app: the frontend, the backend, and the database, in a single project, all running close to your users.
 
-## The one big idea
+You write React for the client and TypeScript for the server. toil compiles the server to WebAssembly and runs it at the edge, next to whoever is asking. Auth, database, email, realtime, and background jobs are already built in. Nothing to wire up, nothing to configure. A pizza site gets the same infrastructure a funded team would rent from ten separate vendors.
 
-Almost every website has a split personality. The pretty part (pages, buttons) is served from servers all over the world, close to you. The important part (the database, where your data lives and changes) sits in **one place**, one region, often one machine. Post a comment in Tokyo when the database is in Virginia and your click flies halfway around the planet and back before anything happens.
+This section explains what that means and why it holds up. Start here, then follow the links at the end.
 
-toil removes the split. Your **frontend** (React) and **backend** (TypeScript, compiled to a tiny WebAssembly program) both run at the **edge**, near your users, and **ToilDB** is distributed too, so writes do not travel to one far-away box. One language, one project, one deploy, running close to everyone.
+## What toil is
+
+A toil project has three parts in one folder:
+
+- `client/` is your React app: file-based routing, data loaders, and a typed client for calling the server.
+- `server/` is your backend, plain TypeScript marked up with decorators like `@rest`, `@data`, and `@auth`. toil compiles it to a small sandboxed WebAssembly module.
+- ToilDB is your database. It is already there. No connection string, no instance to spin up.
+
+Types tie the three together. Change a field on the server and the client stops compiling until you fix it. Edge deployment, post-quantum login, and asset tamper-proofing are on by default, not features you bolt on later.
+
+## The problem it solves
+
+Most apps read fast and write slow. Pages load from caches everywhere, but a write, say a comment or an order, has to reach one database in one region. A user in Tokyo writing to Virginia waits for the trip there and back. That single region is also a single point of failure.
+
+toil closes the gap in two moves. Your code runs at the edge instead of one origin. And ToilDB is built to distribute the writes, not just the reads: every key has a home region that orders its writes, while the data copies outward so reads stay local and quick.
+
+Spreading reads is easy, and everyone does it. Spreading writes is the hard part, and it is why most "global" apps are only global for reading.
 
 ```mermaid
 flowchart TB
     subgraph Ordinary["The ordinary web"]
-        U1["User in Tokyo"] -->|fast| E1["Edge (pretty part)"]
+        U1["User in Tokyo"] -->|fast| E1["Edge (pages)"]
         E1 -->|slow, one region| DB1[("Database in Virginia")]
     end
     subgraph Toil["toil"]
-        U2["User in Tokyo"] -->|fast| E2["Edge near Tokyo<br/>(frontend + backend + data)"]
+        U2["User in Tokyo"] -->|fast| E2["Edge near Tokyo<br/>frontend + backend + data"]
     end
 ```
 
-That is the entire pitch. The rest of these pages is how toil pulls it off, and why almost nobody else does.
+## Where to go from here
 
-## Read these in order
+Read these in order. Each one builds on the last.
 
-1. **[Why toil? Who is it for?](./why-toil.md)** The problem with today's stacks, who benefits most, and the honest cases against.
-2. **[The modern stack](./modern-stack.md)** The full catalog of modern tech baked in with zero setup.
-3. **[How toil works](./how-it-works.md)** The whole machine end to end: React client, WebAssembly backend, the edge, ToilDB, the four compute tiers.
-4. **[What makes toil hyper-scalable](./hyperscale.md)** What "hyper-scale" means, and the mechanisms that let one small program serve the planet.
-5. **[How toil is distributed](./distributed.md)** The hardest problem in web infrastructure, distributing the writes, and how ToilDB solves it.
-6. **[toil versus other frameworks](./vs-other-frameworks.md)** An honest comparison with Next.js, Rails, Django, serverless, edge runtimes, and backend-as-a-service.
-7. **[Why toil is built this way (the RSG bar)](./design-principles.md)** The rubric toil grades itself against.
+1. **[Why toil, and who it is for](./why-toil.md)** What is wrong with a modern stack, who gains most from toil, and the honest cases against it.
+2. **[What comes built in](./modern-stack.md)** The full list of what toil owns and runs for you, and what it does not.
+3. **[How toil works](./how-it-works.md)** The whole path, from a React click through WebAssembly to ToilDB and back.
+4. **[Why it scales cheaply](./hyperscale.md)** How one small program can serve the whole planet without a per-app server bill.
+5. **[How toil distributes writes](./distributed.md)** The hardest problem in web infrastructure, and how ToilDB is built to solve it.
+6. **[toil next to other stacks](./vs-other-frameworks.md)** A fair comparison with Next.js, Rails, serverless, and the rest, wins and losses both.
+7. **[The bar toil holds itself to](./design-principles.md)** The RSG rubric, and its one rule: your grade is your weakest part.
 
-## The short version
+## The short answer
 
-- **Who it is for:** people building real products who want global speed and reliability without a platform team or ten stitched-together vendors. See [Why toil](./why-toil.md).
-- **Why it is fast:** the code runs next to the user, with no slow trip to a central origin. See [Hyper-scale](./hyperscale.md).
-- **Why it is different:** it distributes the writes, not just the reads. See [Distributed](./distributed.md).
-- **Why it is safe:** the backend is a sandbox, passwords never reach the server in a usable form, secrets never ship in the code, and the browser verifies every asset it loads. See [Security](../concepts/security.md).
+- **Who it is for:** anyone shipping a real product who wants global speed without a platform team or ten stitched-together services.
+- **Why it is fast:** the code runs next to the user, with no trip to a distant origin.
+- **Why it is different:** it distributes writes, not only reads.
+- **Why it is safe:** the backend is sandboxed, passwords never reach the server in a usable form, secrets never ship in the code, and the browser checks every file it loads.
 
-When you are ready to build, jump to [Getting started](../getting-started/README.md).
+Ready to build? Jump to [Getting started](../getting-started/README.md).

package/docs/introduction/design-principles.md

@@ -1,55 +1,81 @@
-# Why toil is built this way (the RSG bar)
+# Why toil is built this way
 
-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. The purpose is one thing: reach top-tier infrastructure and ship it as the **default**. AAA-grade tech is normally something you assemble from a dozen vendors and keep alive with a team that understands distributed systems. toil makes the good version the version you get out of the box. One framework, 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 goal. Below is the rubric toil grades itself against, and the choices 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).
+## How RSG grades an app
 
-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 stands for Resilience and Scale Grade. It is toil's internal rubric for how resilient and scalable an app really is, scored as a single letter from **AAA** down to **D**. It grades nine axes. One rule runs the whole thing: **your grade is your weakest axis**. Never the average, never the best. To earn AAA, all nine axes must be AAA at once.
 
-## 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 kills 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).
+
+## What the bar forces
+
+Aiming for AAA as the default is not a slogan. It forces a specific set of decisions, and they are why toil looks the way it does.
+
+### The strong version is the default
+
+On most stacks the resilient path is a paid tier and the secure path is a checklist for later. toil flips 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. 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 built to survive a quantum computer. You do not assemble any of it. You switch it on.
+- **Asset tamper-proofing is on by default.** Every shipped asset carries SHA-384 Subresource Integrity plus importmap integrity. A modified script is rejected by the browser instead of run. There is nothing to remember to turn on.
+
+### Everything is built in and first-party
+
+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. toil builds and owns all of it. This 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.
+
+### One framework instead of 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. There is no hand-written fetch and no drift between the two halves. One project, one deploy, one mental model. The alternative is a frontend host plus an API host plus a database vendor plus an auth vendor plus a queue, each glued to the next.
+
+### Modern foundations
+
+toil bets on current technology instead of 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. That multi-tenancy is what makes running near everyone affordable.
+- **Post-quantum crypto** as the login default, not classical crypto you swap out later.
+- **End-to-end types** from the generated `Server` client. A backend change that breaks the frontend is a compile error, not a production 500.
+- **QUIC and WebTransport** carry realtime ([@stream](../concepts/tiers.md)).
+
+### Honest limits
+
+toil grades itself on honesty, so the docs state the limits plainly.
+
+- **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. The claim is not 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 nine axes
+
+Each axis names a way a system can be weak. Each row is the single design choice 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
+## Why every axis has to hold
 
-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. 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. You cannot reach it with 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 why 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,35 +1,34 @@
 # 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.
+Spreading a website's reads across the world is easy. Spreading its writes is hard, and almost nobody solves it. That is why most "global" apps are only global for reading. This page covers the problem and how ToilDB, the database built into toil, is built to distribute the writes.
 
-## Reads are easy, writes are hard
+## Why writes are the hard part
 
-A read never changes anything, so you copy your data to servers worldwide and let each user read the nearest copy. Every copy agrees: a reader in Tokyo and one in Paris both get a fast, local answer.
+A read changes nothing, so you copy your data to servers worldwide and let each user read the nearest copy. Every copy agrees. A reader in Tokyo and one in Paris both get a fast, local answer.
 
-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**.
+A write is a change, and two writes to the same key can collide. A counter says `10`. Tokyo and Paris both read `10`, both add one, both write `11`. The real answer was `12`. 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. The network, though, will eventually split into a **partition**. During a split the **CAP tradeoff** says you keep only two of three: consistency, availability, and partition tolerance. You either refuse the write, which is correct but unavailable, or accept it on one side and reconcile later, which is available but briefly inconsistent. Distributing writes is a tradeoff to design around. There is no patch that removes it.
 
+## The usual fix: one write database
 
-## So almost everyone centralizes the write database
+So nearly every stack keeps **one** primary write database in **one** region and spreads only read replicas worldwide. Every write funnels to that one box, one at a time, so conflicts cannot happen.
 
-Faced with that, nearly every stack keeps **one** primary write database in **one** region and spreads only read replicas worldwide. All writes funnel to that one box, one at a time, so conflicts cannot happen.
+It is a reasonable choice. It also hides two costs the [RSG rubric](./design-principles.md) flags on its data-path axis:
 
-It is a reasonable choice, and it hides two costs the [RSG rubric](./design-principles.md) flags on its data-path axis:
+- **Far writes are slow.** Post from Tokyo to a primary in Virginia, and the write crosses the planet and back before anything saves. The page loaded locally. The write did not.
+- **The primary is a single point of failure.** One region holds every write. If it has a bad day, nothing anywhere can change.
 
-- **Far writes are slow.** Post from Tokyo to a primary in Virginia and your write crosses the planet and back before anything saves. The page was local; the action was not.
-- **The primary is a single point of failure.** One region holds every write, so if it has a bad day, nothing anywhere can be changed.
+The read path is global. The write path is one machine in one city. Under RSG's weakest-link rule, that single data path caps the whole system.
 
-The read path is global; the write path is one machine in one city. Under RSG's weakest-link rule, that single data path caps the whole system.
+## ToilDB's model: one home per key
 
-## ToilDB's answer: every key has a home
+ToilDB gives **every key its own home**. A key is the label you store data under: a user id, a username, a room name. See the [database overview](../database/README.md). Each key gets one home: the single source of truth that orders its writes.
 
-ToilDB gives **every key its own home**. A key is the label you store data under (a user id, a username, a room name; see the [database overview](../database/README.md)). Each key is assigned one home: the single source of truth that orders its writes.
+Two things follow from that:
 
-Two things follow, and together they are the whole trick:
-
-- **Writes to one key are safe.** Every write to a key travels to that key's home, which **serializes** them (applies them one at a time, in order). Both counter adds are ordered at the counter's home, so the result is `12`. No global lock over the whole database.
-- **Writes spread worldwide.** Different keys get different homes, so total write load spreads out. Tokyo users' data can home near Tokyo, Paris users' near Paris. No single box every write funnels through, so no single bottleneck.
+- **Writes to one key are safe.** Every write to a key travels to that key's home, which **serializes** them: it applies them one at a time, in order. Both counter adds are ordered at the counter's home, so the result is `12`. No global lock over the whole database.
+- **Writes spread worldwide.** Different keys get different homes, so total write load spreads out. Tokyo users' data can home near Tokyo, Paris users' near Paris. No single box carries every write, so no single bottleneck.
 
 ```mermaid
 flowchart TB
@@ -40,13 +39,13 @@ flowchart TB
     KA -.-> KC
 ```
 
-Reads stay local: each key still replicates out, so a reader anywhere gets a nearby copy. Those copies are **eventually consistent**, meaning that for a brief moment (usually milliseconds) after a write lands at the home, a far read can lag before it catches up. For almost all app data this is invisible; the [database overview](../database/README.md) has the full picture.
+Reads stay local. Each key still replicates outward, so a reader anywhere gets a nearby copy. Those copies are **eventually consistent**. For a brief moment after a write lands at the home, a far read can lag before it catches up. That moment is usually a few milliseconds, and for almost all app data it is invisible. The [database overview](../database/README.md) has the full picture.
 
-Which location owns a key is decided by a shared formula (rendezvous hashing) every node computes the same way, so any node routes a write to the right home with no central coordinator. A key's home can move to follow demand, without rehashing the database.
+A shared formula decides which location owns a key. It is called rendezvous hashing, and every node computes it the same way, so any node routes a write to the right home with no central coordinator. A key's home can move to follow demand, without rehashing the database.
 
-## The seven families pick the right consistency tool
+## The seven families
 
-One "home orders the writes" rule fixes the counter, but different jobs want different guarantees. So ToilDB ships **seven families**, each a collection type tuned for one shape of data, each exposing only the operations that are safe and fast for it:
+One "home orders the writes" rule fixes the counter. Different jobs, though, want different guarantees. So ToilDB ships **seven families**. Each is a collection type tuned for one shape of data, and each exposes only the operations that are safe and fast for it.
 
 | Family | What it gives |
 | --- | --- |
@@ -58,13 +57,31 @@ One "home orders the writes" rule fixes the counter, but different jobs want dif
 | [Membership](../database/membership.md) | Sets of who belongs to what |
 | [View](../database/views.md) | A read-optimized result a background job builds |
 
-Distributing writes is not one problem with one answer; each family is the right tool for one shape.
+Distributing writes has no single answer. Each family is the right tool for one shape of data.
+
+## The machinery underneath
+
+The per-key-home model only works if a lot of unglamorous machinery runs reliably across a flaky network. ToilDB owns all of 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 a redelivered write cannot double-count.
+- **Capacity escrow** and **tenant quotas**.
+- **Failover** with snapshot re-seeding for a cell that has fallen too far behind.
+
+Getting all of these right at once is why truly distributed websites are rare.
+
+## What is real today
+
+This is the hard part that almost nobody ships, so here is a straight account of where it stands.
+
+The per-key-home model and all its core logic are **built and tested**: placement, rehoming, replication, idempotent apply, escrow, quotas, failover. This is running code, and it passes its tests.
 
-## The hard machinery toil provides so you do not have to
+The **live multi-region deployment** is not on by default. Wiring many real regions into one running mesh (the WAN routing) and the [ScyllaDB](https://www.scylladb.com/) storage that backs a production cluster are **configuration-gated**. You switch them on for a real deployment. You do not get a live global write cluster automatically. The full database-level **leader fencing** on the write path is also still landing, and a host-side leader gate is the current version. The design is settled. What remains is the last-mile host wiring.
 
-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.
+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. The distribution only spreads out once you deploy with the multi-cell backing configured. You write your app the same way either way.
 
-**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.
+toil is **built** to distribute writes worldwide. The mechanism runs today. 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.
+This page walks one app from source to response. What you write, what the build produces, and what happens when a request arrives. Every term is defined where it first appears. You configure none of the machinery below. This page just explains it.
 
-## What "build" produces
+## The client and the server
 
-`toiljs build` turns your one TypeScript project into three outputs, because your code has two homes: the browser and the edge.
+A toil app is one project. Your code lives in two folders.
 
-- **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 built 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**. Mark a class `@rest` for HTTP endpoints, `@service` for typed RPC, `@stream` for realtime, `@daemon` for background jobs, `@database` or `@collection` for stored data, `@auth` or `@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
 
-It all happens on the **edge node nearest the user**, with no trip to a central origin.
+`toiljs build` turns that one project into three kinds of output. The browser and the edge need different things.
 
-Two terms first:
+**The client bundle.** Your React app, plus any pages toil renders ahead of time. It ships as ordinary web files that run in the browser: HTML, JS, CSS, images. Every asset is fingerprinted with SHA-384 Subresource Integrity, so the browser refuses a file that was tampered with in transit.
 
-- **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 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 |
+
+**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.*` or `Server.Stream.*` or `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.
+
+A word on **WebAssembly**. It is a compact binary format that runs at close to native speed with no interpreter warm-up. It runs inside a **sandbox**: a locked box that cannot open files, reach the operating system, or make network calls on its own. The guest touches the outside world only through a small fixed set of functions the host hands it. Read the request, build a response, query the database. That narrow surface is 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 nodes
+
+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. Each user is served by whichever node is physically closest. There is no **origin server**, no single far machine every request funnels back to. Your backend and its data are already at the edge.
+
+Two things make this work at the density it needs.
+
+- **Multi-tenant on shared boxes.** Each app is a tiny sandboxed module, so 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. This keeps the per-request cost low as traffic grows. **QUIC** and **WebTransport** ride on top to power realtime `@stream` connections.
+
+## What happens on a request
+
+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.
-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.
+2. **Page or dynamic call.** A prerendered page, a server-rendered page, or a static asset is served directly by the edge, which 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`. It 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 keeps a copy right there at the edge. No ocean crossing.
+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 is a function of the request. Bytes in, bytes out, one request at a time.
+
+### Why the backend is stateless
+
+A fresh copy of your handler serves each request. The next request might land on a node on the other side of the planet, so anything you set on an instance field does not survive. This is deliberate. Interchangeable copies with nothing to coordinate are what let the backend scale worldwide by adding more nodes. When you need something to persist, write it to ToilDB. See the [backend overview](../backend/README.md#stateless-by-default).
+
+## The database, ToilDB
 
-The mental model for your backend: a function of the request. Bytes in, bytes out, one request at a time.
+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. You pick the shape that fits instead of forcing everything into one table.
 
-### Stateless by default
+The hard part 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 pin writes to one region. toil is built to distribute both.
+
+Where this stands today. The home-region model and its core logic are real and tested. A live multi-region deployment, meaning WAN routing over the ScyllaDB backing, is configuration-gated. It is not switched on for every app by default. A far read can also lag its home by a few milliseconds, the eventual-consistency trade-off. Your local `toiljs dev` database is a single in-process store. The [distributed writes page](./distributed.md) covers the write model and its trade-off in full.
+
+## The four compute tiers
+
+Not all backend code has the same lifespan. toil sorts it into four tiers, and the build assigns each piece from its decorator automatically.
+
+| 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 |
 
-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).
+Most apps live entirely on **L1**, which 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
+## The parts of a running app
 
-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 come as 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.