toiljs 0.0.115 → 0.0.117

package/docs/introduction/README.md

@@ -1,66 +0,0 @@
-# Understanding toil
-
-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.
-
-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.
-
-This section explains what that means and why it holds up. Start here, then follow the links at the end.
-
-## 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
-
-A good web app should be fast everywhere, secure by default, and able to grow without a rewrite. Getting there is the hard part, and most of it has nothing to do with your actual product.
-
-You assemble it from rented parts: a host, serverless functions, a database, an auth provider, email, a cache, a queue, analytics, a realtime service. Each is its own account, bill, and SDK, and you keep them all in sync. Under that sits a decade of legacy tooling and a node_modules folder heavier than your app. Worse, the fast and secure version is never the default. A CDN, careful caching, region tuning, hardened auth, current crypto: all of it is extra work, so most apps ship slower and less safe than they should.
-
-toil deletes that assembly. One framework runs your frontend, backend, and database at the edge, next to users. Auth, email, realtime, and background jobs are built in and owned. Login is post-quantum out of the box. There is nothing to wire up and no infrastructure to reason about. The good version is the only version.
-
-Distributing writes worldwide is one of the hard problems it handles under the hood. Most stacks spread reads everywhere but pin every write to one region, so a user far from it waits for a round trip and that region is a single point of failure. ToilDB is built to distribute the writes too: every key has a home region that orders its writes while the data copies outward for fast local reads. You never set any of it up.
-
-```mermaid
-flowchart TB
-    subgraph Assemble["The usual way: rent and wire the parts yourself"]
-        direction TB
-        A["Your app"] --> H["host"]
-        A --> F["functions"]
-        A --> D["database"]
-        A --> Au["auth"]
-        A --> Em["email"]
-        A --> Rt["realtime"]
-        A --> J["jobs"]
-    end
-    subgraph Toil["toil: one framework, at the edge, by default"]
-        direction TB
-        A2["Your app"] --> T["frontend + backend + database + auth +<br/>email + realtime + jobs, built in and near users"]
-    end
-```
-
-## Where to go from here
-
-Read these in order. Each one builds on the last.
-
-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)** One of the hardest problems 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 answer
-
-- **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:** the whole stack is built in and owned, so there is nothing to assemble, and it distributes writes worldwide, 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.
-
-Ready to build? Jump to [Getting started](../getting-started/README.md).

package/docs/introduction/design-principles.md

@@ -1,81 +0,0 @@
-# Why toil is built this way
-
-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.
-
-Every decision on this page traces back to that goal. Below is the rubric toil grades itself against, and the choices that rubric forces.
-
-## How RSG grades an app
-
-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.
-
-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.
-
-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: 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 | 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, 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 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. |
-
-## Why every axis has to hold
-
-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.
-- [Security](../concepts/security.md): the security axis and its hard caps.
-- [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,91 +0,0 @@
-# How toil is distributed
-
-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.
-
-## Why writes are the hard part
-
-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 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. 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 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.
-
-It is a reasonable choice. It also 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.
-
-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 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.
-
-Two things follow from that:
-
-- **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
-    WA["write user:aiko"] --> KA["home near Tokyo<br/>key: user:aiko"]
-    WB["write user:bruno"] --> KB["home near Paris<br/>key: user:bruno"]
-    WC["write room:general"] --> KC["home near Ohio<br/>key: room:general"]
-    KA -.->|"replicate for<br/>local reads"| KB
-    KA -.-> KC
-```
-
-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.
-
-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
-
-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 |
-| --- | --- |
-| [Documents](../database/documents.md) | A record you look up by id |
-| [Counters](../database/counters.md) | Conflict-free tallies: adds from anywhere merge, no lost updates |
-| [Unique](../database/unique.md) | A one-of-a-kind claim (a username); the home picks exactly one winner |
-| [Capacity](../database/capacity.md) | Limited stock (tickets); reserve/confirm/cancel holds prevent overselling |
-| [Events](../database/events.md) | An append-only log in one agreed order |
-| [Membership](../database/membership.md) | Sets of who belongs to what |
-| [View](../database/views.md) | A read-optimized result a background job builds |
-
-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 **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.
-
-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.
-
-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
-
-- [The database (ToilDB)](../database/README.md): families, keys and values, and eventual consistency in depth.
-- [Compute tiers](../concepts/tiers.md): where your code runs, the compute side of the same story.
-- [What makes toil hyper-scalable](./hyperscale.md): the mechanisms that let one small program serve the planet.
-- [Why toil is built this way (the RSG bar)](./design-principles.md): the rubric behind the data-path axis.

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

@@ -1,121 +0,0 @@
-# How toil works
-
-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.
-
-## The client and the server
-
-A toil app is one project. Your code lives in two folders.
-
-- **`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.
-
-That is the whole surface. One repo, one language family, one `toiljs dev`.
-
-## What the build produces
-
-`toiljs build` turns that one project into three kinds of output. The browser and the edge need different things.
-
-**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 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 (Rust)
-    participant W as WASM host
-    participant G as Your guest module
-    participant DB as ToilDB (local copy)
-
-    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 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
-
-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.
-
-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 |
-
-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 parts of a running app
-
-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 `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 |
-
-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): 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

@@ -1,70 +0,0 @@
-# What makes toil hyper-scalable
-
-Hyper-scale means serving very large worldwide traffic at low latency without rebuilding your app as it grows. Picture traffic climbing from a thousand users to a hundred million across every continent. Do you rewrite the system, or just run more of it?
-
-Any stack can reach that scale if you spend enough: dedicated infrastructure per app, a rented vendor for each moving part, and an ops team to keep the seams from tearing. toil reaches the same scale from the other direction, cheaply. The whole design aims to make worldwide reach a default, not a budget line. This page is about cost.
-
-## Why serving the whole world is normally expensive
-
-Running near your users usually means paying 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 rent a lot of mostly-idle hardware.
-- **A far-away origin.** Most stacks serve pages from everywhere but send anything real back to one origin in one region. Every write and every dynamic call pays for a round trip across the planet.
-- **A centralized write database.** Reads scale out. Writes funnel into one primary in one city. That box is both the bottleneck and the thing you overprovision to stay ahead of.
-
-These are cost multipliers, and they stack. toil removes all three.
-
-## The three things that make toil 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. It 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 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, and the 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. Every key has one home region that orders its writes, and the data replicates out for fast local reads. You get nearby reads everywhere without a single primary that every write funnels through, and without paying to overprovision one. The [distributed writes](./distributed.md) page covers the mechanism and its honest trade-off, eventual consistency.
-
-```mermaid
-flowchart LR
-    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["The cheap shape: shared edge + homed writes"]
-        direction TB
-        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, plus its dedicated fleet. No amount of caching removes that cost. 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.
-
-## Why each mechanism lowers the cost
-
-- **Density** splits the cost of an edge presence across many tenants instead of loading it on one app.
-- **Edge locality** means no origin fleet to run and no cross-planet round trip on every real request.
-- **No dedicated infrastructure** means you scale by adding interchangeable shared nodes, not by standing up a new stack per app.
-
-Take any one away and a cost comes back. Without density, running near everyone is a luxury again. Without edge locality, you pay for an origin. With a centralized write path, the database caps you and gets overprovisioned to compensate.
-
-## What is real today
-
-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, and it does not repeal the speed of light between continents.
-
-Some parts are honestly staged, not already everywhere.
-
-- 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. Live multi-cell deployment, meaning WAN routing and 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.
-- [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,85 +0,0 @@
-# The modern stack: what toil gives you that others do not
-
-Most frameworks give you a way to write code, then send you shopping. A database, an auth provider, email, a rate limiter, analytics, a realtime service, a job runner. Each one is its own account, its own bill, and its own SDK, and you keep them all in sync.
-
-toil owns those parts instead. They ship in the framework, they are toil's own code, and they run from the first line with no configuration. Nothing third-party sits on your critical path.
-
-The good version is the default version. A solo builder gets the same baseline a funded team would rent from ten vendors, with nothing to assemble or babysit. This page is the full catalog. For how the edge and worldwide distribution work, see [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
-
-## Built-in backend features
-
-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 |
-| --- | --- | --- |
-| [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](../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 family is tuned to its own access pattern instead of forced out of a single table model.
-
-| 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`. |
-
-## Built-in frontend features
-
-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. |
-
-## toil versus a typical stack
-
-Everything above is toil's own code on your critical path. You can inspect it, patch it, and secure it. The table below draws the difference.
-
-| Capability | toil (built in, zero setup) | Typical stack (you assemble it) |
-| --- | --- | --- |
-| 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`, `@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 |
-
-Owned means the core of a working app is toil's. It does not mean outside services are banned. You can still call a payment provider or any other API.
-
-## Honest limits
-
-toil grades itself on honesty. 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. 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 these ship by default
-
-None of this is an upgrade you unlock later. toil grades itself against [RSG](./design-principles.md), the Resilience and Scale Grade. Its one rule: your grade is your weakest axis, never the average. These built-in parts exist so no single axis quietly caps the whole.
-
-The trades are real. ToilDB is not general SQL. The server language is a strict TypeScript subset. The catalog is younger than long-established platforms. Where those trades fit your project, the built-in stack earns its place. [Why toil](./why-toil.md) covers where it does not.

package/docs/introduction/vs-other-frameworks.md

@@ -1,64 +0,0 @@
-# toil versus other stacks
-
-This page compares toil to the stacks you already use, axis by axis. Every tool below is good at what it was built for. The aim is to be concrete about what you gain and what you give up. toil is younger than all of them, and that shows in a few rows.
-
-toil trades a large, mature ecosystem for one owned framework where the fast, secure, global version is the default. You give up SQL, the Node package universe, and a big integration catalog. You gain a stack that is built in and yours, runs near users, ships post-quantum auth and end-to-end types with no setup, and distributes writes worldwide instead of pinning them to one region. Whether that trade fits your project is what this page answers.
-
-## The comparison table
-
-| Axis | A typical modern stack | toil |
-| --- | --- | --- |
-| Pieces on the critical path | A dozen rented vendors (host, functions, database, auth, email, queue, cache, analytics, realtime), each its own account, bill, and SDK | One framework you write in; the core services are toil's own, so nothing third-party sits on the critical path |
-| Where writes land | One primary region: reads go global, writes crawl back to that box | Every key has one home region that orders its writes, while data replicates outward for fast local reads (built to distribute; live multi-cell is configuration-gated) |
-| Server runtime | A Node process, container, or VM per app | A small sandboxed WebAssembly module; one edge box safely runs many apps (multi-tenant), which is what makes running near everyone affordable |
-| Client-to-server calls | Hand-written fetch/REST, types drift until something breaks in production | A generated, fully typed `Server` client with no raw fetch: change a field on the server and the frontend stops compiling until you fix it |
-| Auth | Bolt on a provider or roll your own | Post-quantum login (ML-DSA + ML-KEM) built in, enabled in about one line |
-| Getting to production | Assemble CDN, cache, regions, hardened auth, and CI yourself | Zero config: the good version is the default version |
-| Toolchain | A decade of bundler configs, transpiler shims, CommonJS-versus-ESM interop, and `node_modules` churn | Built on modern web tech (React + Vite client, one CLI), far less legacy to fight |
-| Database | Mature SQL: joins, ad-hoc queries, huge tooling | Seven purpose-built families (Documents, Unique, Counter, Events, Membership, Capacity, View): fast and distributed, but not relational |
-| Package ecosystem | The full npm and Node universe | A strict TypeScript subset with built-in globals; no arbitrary npm packages or Node APIs on the server |
-| Integration catalog | Large, mature, well documented | Smaller and younger |
-| Single-region app | Dead simple, nothing to distribute | Distribution you may not need |
-
-The top rows lean toil's way. The bottom rows lean the incumbents' way. toil wins the structural axes: one owned stack, distributed writes, a multi-tenant sandbox, end-to-end types, and built-in modern auth. It concedes the ecosystem axes that maturity buys: SQL, the Node universe, and catalog size.
-
-## How toil compares to each stack
-
-**Next.js / Vercel.** Superb React DX and global edge reads. The backend, though, is still yours to assemble: a database, auth, email, a queue, and a realtime service, each rented and wired up on its own. Serverless cold starts add latency and per-invocation cost right when a spike hits, and writes still resolve against one primary region. toil keeps a React-first client but ships the whole backend built in, running near the data with no cold start.
-
-**Rails / Django.** Mature, productive, and batteries included, with a deep hiring pool. If one region suits you, this is a great and boring choice. The default shape is a single-region monolith with one primary that every write must reach. You can add replicas and standbys to scale, but distributed writes are not in the model.
-
-**Serverless functions (Lambda, Cloud Functions).** Elastic, stateless compute that scales to zero. It still sits in front of a central database, so a write burst bottlenecks on that store. Each cold invocation bills and lags on its own.
-
-**Edge runtimes (Workers, Deno Deploy).** The closest in spirit to toil's compute model: your code runs near users. The catch is everything you bolt on around it. The database you attach is usually single-region, and auth, email, realtime, and typed client calls are still yours to assemble. toil ships those built in, on a database designed to distribute writes.
-
-Cloudflare Durable Objects and D1 are the closest mainstream analog to toil's idea, and credit is due. A Durable Object gives one object a single-writer home that orders its writes, the same shape as ToilDB's per-key home. The difference is packaging. With the edge-runtime approach you assemble the pieces yourself: runtime, object or database product, auth, email, and realtime. toil ships distributed writes, the seven database families, auth, email, streaming, and background jobs as one owned stack. Which you prefer is a real trade-off.
-
-**Backend-as-a-service (Supabase, Firebase).** The fastest thing to start with, and often the right call for a prototype. The convenience is a managed service on your critical path that you cannot inspect or patch, and writes still resolve against a primary.
-
-## What incumbents do better
-
-toil does not win every axis. Some gaps are real today:
-
-- **Mature ecosystems.** More tutorials, more answered questions, more hosting options, and more people who already know the tool.
-- **SQL and joins.** If your data is relational and you live in ad-hoc queries and joins, a SQL database is the right tool. ToilDB is seven purpose-built families, not a relational engine (see the [database overview](../database/README.md)).
-- **The Node package universe.** The toil server is a strict TypeScript subset compiled to WebAssembly: no arbitrary npm packages or Node APIs, built-in globals instead. That is the price of the small, fast, multi-tenant sandbox.
-- **Bigger integration catalogs.** toil is younger, so the catalog of ready-made integrations is smaller. If your project is defined by a large existing integration catalog, that gap matters.
-- **Single-region simplicity.** If one region already fits your users, toil's distribution is effort you do not need.
-
-None of these are permanent, and the right tool is the one that fits the job in front of you.
-
-## The trade toil makes
-
-Most stacks cap in the same place. The write path is one box in one region, or the critical path leans on services you rent and cannot fix. toil refuses both. It owns the whole stack and distributes the writes, so the structural caps are designed out. The limits left are the ones your own code sets.
-
-One caveat, to keep the mechanism honest. The home-region model and its core logic are real and tested. Live multi-region deployment is configuration-gated rather than on by default: the WAN routing and the ScyllaDB backing are opt-in, and the local dev database is a single in-process store. Compute works the same way. Your code runs at the edge on every request, while the regional, continental, and global-daemon tiers are opt-in. So the honest claim is that toil is built to distribute writes worldwide and the mechanism is real. It does not mean every app is already running a live global write cluster today.
-
-Whether the trade fits your project is the checklist in [Why toil](./why-toil.md).
-
-## Related pages
-
-- [Why toil? Who is it for?](./why-toil.md): the problem toil solves and the honest cases where you should not use it.
-- [The modern stack](./modern-stack.md): the full, verified catalog of what is built in.
-- [How toil is distributed](./distributed.md): the mechanism behind distributed writes (every key's single home region).
-- [Why toil is built this way](./design-principles.md): the bar toil grades itself against.