toiljs 0.0.66 → 0.0.67

package/build/devserver/db/catalog.js

@@ -1,6 +1,6 @@
 import { DataReader } from 'toiljs/io';
 import { customSection } from '../wasm/sections.js';
-import { DEFAULT_FILL_WAIT_MS, isCollectionFamily, MAX_FILL_WAIT_MS, } from './types.js';
+import { isCollectionFamily, MAX_FILL_WAIT_MS, } from './types.js';
 function validReplication(value) {
     return value === 0 || value === 1 || value === 2 || value === 5;
 }
@@ -20,7 +20,7 @@ export function parseCatalog(wasm) {
         return { kind: 'no-section' };
     const r = new DataReader(sec);
     const version = r.readU16();
-    if (!r.ok || (version !== 1 && version !== 2))
+    if (!r.ok || version !== 1)
         return { kind: 'malformed' };
     const ndb = r.readU16();
     for (let d = 0; d < ndb && r.ok; d++) {
@@ -36,16 +36,12 @@ export function parseCatalog(wasm) {
             r.readU32();
             const replication = r.readU8();
             const placement = r.readU8();
-            let fillMaxWaitMs = DEFAULT_FILL_WAIT_MS;
-            let fillAllowStale = true;
-            if (version >= 2) {
-                fillMaxWaitMs = r.readU32();
-                const fillAllowStaleByte = r.readU8();
-                if (fillMaxWaitMs > MAX_FILL_WAIT_MS ||
-                    (fillAllowStaleByte !== 0 && fillAllowStaleByte !== 1))
-                    return { kind: 'malformed' };
-                fillAllowStale = fillAllowStaleByte === 1;
-            }
+            const fillMaxWaitMs = r.readU32();
+            const fillAllowStaleByte = r.readU8();
+            if (fillMaxWaitMs > MAX_FILL_WAIT_MS ||
+                (fillAllowStaleByte !== 0 && fillAllowStaleByte !== 1))
+                return { kind: 'malformed' };
+            const fillAllowStale = fillAllowStaleByte === 1;
             const nFields = r.readU16();
             for (let f = 0; f < nFields; f++) {
                 r.readString();

package/build/devserver/wasm/surface.d.ts

@@ -15,4 +15,4 @@ export interface Surface {
     readonly dataCoherenceHash: number;
     readonly pairCoherenceHash: number;
 }
-export declare function parseSurface(wasm: Buffer): Surface | 'absent' | 'invalid';
+export declare function parseSurface(wasm: Buffer): Surface | 'invalid';

package/build/devserver/wasm/surface.js

@@ -9,7 +9,7 @@ export function parseSurface(wasm) {
         return 'invalid';
     }
     if (sec === null)
-        return 'absent';
+        return 'invalid';
     const r = new DataReader(sec);
     r.readU16();
     const targetMode = r.readU8() === 1 ? 'cold' : 'hot';

package/docs/tiers.md

@@ -8,11 +8,11 @@ tier purely by adding its entry file and surface decorator; nothing else changes
 
 ## The tiers
 
-| Entry (`server/`) | Surface | Artifact | Tier | Lifetime / placement |
-| --- | --- | --- | --- | --- |
-| `main.ts` | `@rest` / `@service` / `@remote` | `build/server/release.wasm` | **L1** request | A fresh handler per request, anywhere on the edge. |
-| `main.stream.ts` | `@stream` | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |
-| `main.daemon.ts` | `@daemon` / `@scheduled` | `build/server/release-cold.wasm` | **L4** daemon | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md). |
+| Entry (`server/`) | Surface                          | Artifact                           | Tier             | Lifetime / placement                                                                                                                              |
+| ----------------- | -------------------------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `main.ts`         | `@rest` / `@service` / `@remote` | `build/server/release.wasm`        | **L1** request   | A fresh handler per request, anywhere on the edge.                                                                                                |
+| `main.stream.ts`  | `@stream`                        | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |
+| `main.daemon.ts`  | `@daemon` / `@scheduled`         | `build/server/release-cold.wasm`   | **L4** daemon    | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md).             |
 
 The three tiers differ in how long a box lives and how many of it exist:
 
@@ -79,7 +79,7 @@ build/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, sche
 
 ## Single-artifact default
 
-A project with no `@stream` and no `@daemon` surface keeps the legacy
+A project with no `@stream` and no `@daemon` surface keeps the default
 single-artifact build - just `build/server/release.wasm`. The stream and daemon
 tiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get
 `release-stream.wasm`, add `main.daemon.ts` (and a `@daemon` class) to get
@@ -102,9 +102,15 @@ tiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get
 class Echo {
     private count: i32 = 0;
 
-    @connect onConnect(): void { this.count = 0; }
-    @message onMessage(): void { this.count = this.count + 1; }
-    @close   onClose(): void { /* box torn down after this hook */ }
+    @connect onConnect(): void {
+        this.count = 0;
+    }
+    @message onMessage(): void {
+        this.count = this.count + 1;
+    }
+    @close onClose(): void {
+        /* box torn down after this hook */
+    }
 }
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.66",
+    "version": "0.0.67",
     "author": "Dacely",
     "description": "The modern React framework: a file-based React frontend and a ToilScript-compiled WebAssembly backend.",
     "repository": {
@@ -134,7 +134,7 @@
         "nodemailer": "^9.0.1",
         "picocolors": "^1.1.1",
         "sharp": "^0.35.2",
-        "toilscript": "^0.1.41",
+        "toilscript": "^0.1.42",
         "typescript-eslint": "^8.62.0",
         "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",

package/src/compiler/index.ts

@@ -139,8 +139,8 @@ export async function buildServer(root: string): Promise<void> {
 
     // A project that declares a `@daemon` (L4 cold surface) and/or a `@stream` (L2/L3 stream
     // surface) compiles the ONE source tree into SEPARATE artifacts, one per deployment tier, via
-    // one toilscript pass each; a project with only the legacy request surface keeps the
-    // single-artifact path (byte-identical to before). The three tiers:
+    // one toilscript pass each; a project with only the request surface keeps the default
+    // single-artifact path. The three tiers:
     //   - REQUEST (L1)   `server/main.ts`    + `@rest`/`@service`/`@remote` -> `release.wasm`
     //   - STREAM  (L2/L3) `server/main.stream.ts` + `@stream`              -> `release-stream.wasm`
     //   - DAEMON  (L4)   `@daemon`/`@scheduled`                            -> `release-cold.wasm`
@@ -167,7 +167,7 @@ export async function buildServer(root: string): Promise<void> {
                 outFile: artifacts.stream,
                 withRpc: false,
             });
-        // REQUEST pass: the L1 artifact (= the legacy `outFile`, AN-1), WITH the client RPC surface.
+        // REQUEST pass: the L1 artifact (= `outFile`), WITH the client RPC surface.
         // A pure daemon/stream project (no request files) skips it so toilscript is not handed an
         // empty entry set; the request path then stays idle (no `handle` export), correct for a
         // background-only worker.
@@ -180,7 +180,7 @@ export async function buildServer(root: string): Promise<void> {
         return;
     }
 
-    // Legacy single-artifact path (no daemon/stream surface): exactly today's invocation.
+    // Default request-only single-artifact path (no daemon/stream surface).
     await runToilscriptPass(root, binJs, files, { mode: null, outFile: null, withRpc: true });
 }
 
@@ -285,11 +285,11 @@ export function splitSurfaceFiles(root: string, files: string[]): SurfaceSplit {
 }
 
 interface PassOptions {
-    /** `--targetMode` value; `null` keeps the legacy single-artifact invocation (no flag). */
+    /** `--targetMode` value; `null` keeps the default request-artifact invocation (no flag). */
     readonly mode: 'hot' | 'cold' | null;
     /** Explicit `--outFile` for a two-pass build; `null` uses the toilconfig default. */
     readonly outFile: string | null;
-    /** Only the hot/legacy pass carries `--rpcModule` (the cold artifact has no client surface). */
+    /** Only the hot/default request pass carries `--rpcModule` (the cold artifact has no client surface). */
     readonly withRpc: boolean;
 }
 
@@ -447,7 +447,7 @@ function installDevShutdown(close: () => Promise<void> | void): void {
 }
 
 /** The server wasm artifact path from the toilconfig `release` target (toilscript's output).
- *  This is the LEGACY single-artifact path (= the hot artifact under the two-pass build). */
+ *  This is the default request artifact path (= the hot artifact under the two-pass build). */
 function serverWasmFile(root: string): string {
     let outFile = 'build/server/release.wasm';
     try {
@@ -598,16 +598,22 @@ async function collectDevCss(server: ViteDevServer): Promise<string> {
             }
         }
     }
-    // Fetch each stylesheet's raw text (`?direct` serves real CSS, not the HMR JS shim) at startup,
-    // while Vite is already warm, so it can be inlined rather than fetched on the paint critical path.
+    // Extract each stylesheet's real CSS from its normal (non-`?direct`) module. Vite serves a
+    // JS-imported CSS file as a JS module that carries the CSS in a `const __vite__css = "..."`
+    // literal (JSON-encoded); that module is valid JS, so vite-plugin-node-polyfills' inject plugin
+    // passes it through intact. We deliberately AVOID the `?direct` variant: it serves raw CSS, which
+    // the inject plugin then fails to parse-as-JS and truncates to the leading comment (whether via
+    // transformRequest OR an HTTP fetch). We inline this at startup so the SSR first paint is styled.
     let css = '';
     for (const url of cssUrls) {
-        const direct = `${url}${url.includes('?') ? '&' : '?'}direct`;
         try {
-            const result = await server.transformRequest(direct, { ssr: false });
-            if (result?.code) css += `${result.code}\n`;
+            const result = await server.transformRequest(url);
+            const m = result?.code
+                ? /const __vite__css = ("(?:[^"\\]|\\.)*")/.exec(result.code)
+                : null;
+            if (m) css += `${JSON.parse(m[1]) as string}\n`;
         } catch {
-            // skip a stylesheet that fails to transform; inline what we can
+            // skip a stylesheet whose CSS can't be extracted; inline what we can
         }
     }
     return css;

package/src/compiler/toil-docs.generated.ts

@@ -13,7 +13,7 @@ export const TOIL_DOCS: Record<string, string> = {
     "server.md": "# Server (toilscript → WebAssembly)\n\n`server/` is the toilscript source, compiled to WebAssembly by `toilscript`.\n\n- `server/main.ts`, the `@main` entry, exported as the WASM `main`.\n- `server/index.ts`, your functions.\n- `server/tsconfig.json`, extends `toilscript/std/assembly.json` (AssemblyScript/toilscript\n  globals like `i32`, not the DOM), so editors resolve server types correctly.\n- `npm run build:server` (or `npm run build`) emits `build/server/release.wasm` and\n  regenerates `shared/server.ts` (the typed client RPC module).\n\n## Typed RPC (`@data` / `@remote` / `@service`)\n\nTag server code and the build generates a typed client `Server` surface:\n\n- `@data class X {}`, a serializable struct. Generates a client class with the same fields\n  plus `encode`/`decode`; construct it on the client: `import { X } from \"shared/server\"`.\n- `@remote function f(a: T): R`, a client-callable endpoint, becomes `Server.f(a)`.\n- `@service class S { @remote m(...) {} }`, namespaces methods: `Server.s.m(...)`.\n\nOn the client, `Server` is a global (no import) and fully typed; every call is async\n(`Promise<R>`). Inputs/outputs are scalars, arrays, or `@data` classes, both directions.\n\nNote: the client↔server transport is not wired yet, so calling a `Server` method throws\nuntil it lands; the typed surface + codec are generated and ready.\n\n## HTTP REST (`@rest` / `@route`)\n\nTag a class `@rest` and its methods with a verb to expose a real HTTP API. Unlike RPC,\nthe generated client is working `fetch` code (it is just HTTP).\n\n- `@rest(\"api\") class Todos {}`, mounts the controller at `/api` (bare `@rest` → `/`).\n- `@get(\"/todos/:id\")` / `@post` / `@del` / `@put` / `@patch` / `@head` / `@options`, verb\n  shortcuts; or `@route({ method: Methods.GET, path: \"/todos\", stream: DataStream.JSON })`.\n- A method takes an optional `@data` body + an optional `ctx: RouteContext` (path params via\n  `ctx.param(\"id\")`, `ctx.query(...)`, `ctx.header(...)`). It returns either a `@data` type,\n  which the compiler encodes per `stream` (`DataStream.JSON` default, or `DataStream.Binary`,\n  lossless for large `u64`/bignum), or a `Response` for full control - custom status and\n  headers, e.g. `Response.json(value.toJSON().toString()).setHeader(\"cache-control\", \"no-store\")`\n  or `Response.notFound()`. (The editor sees the compiler-injected `@data` `toJSON`/`encode`\n  members via the toilscript plugin, so serializing into a `Response` is editor-clean.)\n\nEach `@rest` class self-registers; dispatch them from your handler - it composes, it never\ntakes over `handle()`:\n\n```ts\nimport { ToilHandler, Request, Response, Rest } from \"toiljs/server/runtime\";\nexport class App extends ToilHandler {\n    public handle(req: Request): Response {\n        const hit = Rest.dispatch(req); // try every @rest controller\n        if (hit != null) return hit;\n        return Response.notFound();     // your own logic / static fallback\n    }\n}\n```\n\nFor a REST-only project, `Server.handler = () => new RestHandler()` does the same with no\nboilerplate. On the client: `Server.REST.todos.getTodo({ params: { id } })` (see [client.md](./client.md)).\n\nFor the full reference (`@rest`/verb decorators, `RouteContext`, `Request`, `Response`,\ndispatch + the 404 fallback) see [routing.md](./routing.md).\n",
     "ssr.md": "# Server-side rendering (SSR)\n\ntoiljs server-renders a route by splitting it into two halves that the build\nkeeps coherent:\n\n- **the template**, the HTML shell with the dynamic bits punched out (named\n  *holes*). It is React's own `renderToStaticMarkup` output with the holes\n  removed, precompiled at build time and held (mmap'd) by the edge.\n- **the values**, the hole values for one request (text, attributes, repeated\n  rows, headers, status). The wasm guest's `render` entrypoint returns *only*\n  these. The edge splices them into the template.\n\nA 32-byte template **hash** travels with the values so the edge can reject a\nguest that was compiled against a different template than the one deployed.\n\nThis split is the whole point. The guest never re-runs React and never emits the\nstatic page bytes, it stamps a tiny `(slot_id, kind, value)` list, so the wasm\nstays small and a request is served about as fast as a static file, while still\ndelivering real first-paint HTML and SEO. The browser then hydrates the spliced\nmarkup in place with no flash and no client re-render, because the holes are\nescaped exactly the way React escapes them, so the bytes match.\n\nThis page is about server-rendered HTML. JSON / binary API endpoints use\n[Routing](./routing.md) and `@rest` (see [Server](./server.md)) instead.\n\nThe running example throughout is the basic example's `/hello` route:\n\n- `examples/basic/client/routes/hello.tsx`, the route (`ssr = true`, holes, loader)\n- `examples/basic/server/SsrHelloRender.ts`, the server `render` + `Ssr.register`\n- `examples/basic/server/_ssr/hello.slots.ts`, the generated `Slot` + `HASH` (gitignored, never hand-edited)\n\n---\n\n## 1. Authoring an SSR route\n\nOpt a route in with `export const ssr = true`. At build time toiljs renders the\npage ONCE (under its real layout chain, with sample loader data) into the\ntemplate, generates the route's typed `Slot` module, and writes the template\nmanifest the edge serves. Routes without `ssr = true` are untouched and render\npurely on the client as before.\n\nMark the dynamic bits with the four hole markers from `toiljs/client`. They are\n**transparent in the browser**, `<Hole>` renders its children, `<Repeat>`\nrenders `each.map(...)`, `<RawHtml>` renders a `dangerouslySetInnerHTML`\nwrapper, `<Island>` renders its children, so the same component is your normal\nclient UI. Only the build extractor and the server `render` treat them\nspecially.\n\n```tsx\nimport { Hole, Island, RawHtml, Repeat, useLoaderData } from 'toiljs/client';\n\nexport const ssr = true;\n\nexport const loader = ({ params }: { params: Record<string, string> }) => ({\n  name: params.name ?? 'world',\n  blurbHtml: 'Rendered at the <strong>edge</strong>.',\n  services: [{ name: 'record', region: 'us-east' }],\n});\n\nexport default function Hello() {\n  const d = useLoaderData<typeof loader>();\n  return (\n    <section className=\"hello\">\n      <h1>Hello, <Hole id=\"name\">{d.name}</Hole>!</h1>\n\n      <p><RawHtml id=\"blurb\" html={d.blurbHtml} as=\"span\" /></p>\n\n      <ul>\n        <Repeat id=\"services\" each={d.services}>\n          {(s) => (\n            <li>\n              <strong><Hole id=\"svcName\">{s.name}</Hole></strong>\n              <span className=\"hello-region\"><Hole id=\"svcRegion\">{s.region}</Hole></span>\n            </li>\n          )}\n        </Repeat>\n      </ul>\n\n      <Island>\n        <p>Hydrated at {new Date().toLocaleTimeString()}.</p>\n      </Island>\n    </section>\n  );\n}\n```\n\n### The loader at build time\n\nThe build calls your `loader` once with synthesized sample params to obtain\nrepresentative data, then renders the page with it. Only the **shape** of the\ndata matters at build time, it drives which holes exist and (for `<Repeat>`)\ncaptures the row sub-template. The real per-request values come from the\n**server** `render`, not from this loader. Note in particular that `<Repeat>`\nneeds the sample to have **at least one row** so the build can capture the row\nmarkup; an empty array at build time leaves nothing to stamp.\n\n### The four hole markers\n\n| Marker | Prop(s) | Server (build + render) | Browser |\n| --- | --- | --- | --- |\n| `<Hole id>` | `id` | a text insertion point; the guest fills it with the **escaped** value | renders `children` |\n| `<RawHtml id html as?>` | `id`, `html`, `as?` (wrapper tag, default `div`) | emits `<as>…</as>`; the guest fills the inner HTML **verbatim** (you sanitize) | `<as dangerouslySetInnerHTML>` |\n| `<Repeat id each>` | `id`, `each`, child `(item, index) => node` | captures the **one** row sub-template; the guest stamps it per item and concatenates | renders `each.map(children)` |\n| `<Island>` | `children` | renders **nothing** (empty in the server HTML) | renders `children` |\n\n`<RawHtml>` always needs a host element so the server and client DOM agree; that\nis the `as` wrapper (defaults to `div`). The captured `<as>` tag is part of the\ntemplate, only its inner HTML is a hole.\n\n### Attribute holes (`attr()`)\n\nAn attribute value is not a child node, so it cannot be a JSX marker element.\nUse the `attr(id, value)` helper from `toiljs/client` in attribute position\ninstead:\n\n```tsx\nimport { attr } from 'toiljs/client';\n\n<a href={attr('profileUrl', d.url)} class={attr('cls', d.cls)}>…</a>\n```\n\nBrowser: `attr` returns `value` unchanged. Build: it emits an `attr` hole at the\nattribute's byte offset (stripping to an empty value in the `.tmpl`). The server\n`render` fills it with `v.setAttr(Slot.profileUrl, url)` (React-escaped, the same\nas `setText`), and the host splices it between the quotes. It composes with\nliteral text in the same attribute (`` class={`btn ${attr('x', v)}`} ``).\n\n### SSR-safe routes (and `<Island>`)\n\nFor hydration to be byte-clean, the route **and the layouts above it** must\nrender under static markup: use the hole markers and `useLoaderData`, and put\nanything that needs router hooks (`useRouter`, `usePathname`, …) or browser-only\nAPIs (`window`, `Date.now`, …) inside an `<Island>`. An island is empty in the\nfirst paint and appears only after hydration, so it gets no first-paint HTML or\nSEO, which is exactly right for \"client only\" content.\n\nOpting in is always safe: a route (or a layout in its chain) that **throws**\nunder static markup is **skipped at build with a warning** and falls back to\nnormal client rendering. You never get a broken page from adding `ssr = true`;\nworst case you get client rendering and a build warning telling you why.\n\n---\n\n## 2. The server `render`\n\nThe wasm `render(req_ofs, req_len) -> i64` export is surfaced by your\n`server/main.ts` via `export * from 'toiljs/server/runtime/exports'` (the same\nline that surfaces `handle`). At request time it decodes the request, runs the\n`Ssr` router to find a matching render function, serializes that function's\n`SlotValues` into the values envelope, and returns it packed as\n`(ptr << 32) | len`.\n\nA render function takes the `Request`, returns a filled `SlotValues` for a path\nit owns, or `null` to let the next registered renderer try.\n\n```ts\nimport { HtmlBuilder, Request, SlotValues, Ssr } from 'toiljs/server/runtime';\nimport { HASH, Slot } from './_ssr/hello.slots';\n\nfunction renderHello(req: Request): SlotValues | null {\n  // The guest re-derives WHICH route this is from the path (the template name\n  // is not in the request envelope), exactly as a @rest controller matches its\n  // own prefix. req.path includes the query string, so match both forms.\n  if (req.path != '/hello' && !req.path.startsWith('/hello?')) return null;\n\n  const v = new SlotValues(HASH);\n\n  v.setText(Slot.name, greetingName(req));                 // escaped\n  v.setRaw(Slot.blurb, 'Rendered at the <strong>edge</strong>.'); // verbatim\n\n  const rows = new HtmlBuilder();\n  for (let i = 0; i < services.length; i++) {\n    const s = services[i];\n    rows.raw('<li><strong>').text(s.name)\n        .raw('</strong><span class=\"hello-region\">').text(s.region)\n        .raw('</span></li>');\n  }\n  v.setRepeat(Slot.services, rows);\n\n  return v;\n}\n\nSsr.register(renderHello); // side-effect registration\n```\n\n### Registration is manual; the import is load-bearing\n\n`ssr-codegen` generates ONLY the `Slot` enum and the `HASH`, it does **not**\nemit the render body and does **not** auto-register it. You write `renderHello`\nand call `Ssr.register(renderHello)` yourself.\n\nCrucially, `Ssr.register` runs as a **module side effect**, so the module must\nbe imported somewhere the build reaches. Non-surface files (a plain render\nmodule is not a `@rest`/`@service`/`@data` file) are **not** auto-discovered, so\nyou must `import './SsrHelloRender'` in `server/main.ts`. Forgetting the import\nmeans the renderer never registers, `Ssr.dispatch` returns `null`, and the route\nfalls back to the fail-safe 500.\n\n### What `render` does for a request the router misses\n\nIf no registered renderer matches, the `render` export emits a **fail-safe**\nenvelope: status 500 with a **zeroed** 32-byte hash and no slots (a malformed\nrequest envelope yields the same fail-safe with status 400). The edge rejects\nthe zero hash as a coherence mismatch, so a miss surfaces as a clean error\nrather than a corrupt page.\n\n---\n\n## 3. Reference: `SlotValues`\n\nConstruct it with the route's compiled-in hash: `new SlotValues(HASH)`. Each\nsetter targets a slot id (a `Slot` enum member); the **kind** determines how the\nedge splices it. All setters return `this` for chaining.\n\n| Method | Signature | Escaping | Use |\n| --- | --- | --- | --- |\n| `setText` | `setText(slotId, value: string)` | **React-escaped** | text content (safe by default) |\n| `setRaw` | `setRaw(slotId, html: string)` | **none (verbatim)** | raw HTML, *you* sanitize |\n| `setAttr` | `setAttr(slotId, value: string)` | **React-escaped** | an attribute value |\n| `setRepeat` | `setRepeat(slotId, rows: HtmlBuilder)` | per `HtmlBuilder` calls | a repeat region, pre-stamped row by row |\n| `setHeader` | `setHeader(name, value)` |, | a response header (e.g. `Cache-Control`, `Set-Cookie`) |\n| `setStatus` | `setStatus(code)` |, | the HTTP status (default 200) |\n\n`setText` and `setAttr` escape identically (React escapes text and attributes\nthe same way). Slot ids passed are the `Slot` enum members; AS enums are `i32`,\nso they pass without a cast and are narrowed to `u16` only at encode time.\n\n### `HtmlBuilder`\n\nAssembles a repeat region (or any HTML fragment) with the same escaping\nguarantees. Chain `raw` (verbatim template bytes) and `text` / `attr`\n(React-escaped values):\n\n```ts\nconst rows = new HtmlBuilder();\nfor (let i = 0; i < items.length; i++) {\n  rows.raw('<li>').text(items[i]).raw('</li>'); // items[i] is escaped\n}\nv.setRepeat(Slot.list, rows);\n```\n\nYou are hand-writing the row markup, so it must match what `<Repeat>`'s child\nproduces for the same item, the build captured exactly that markup as the row\nsub-template, and the edge inserts your stamped rows verbatim at the region\noffset. Keep the **structure** the same across rows; only the leaf hole values\nvary.\n\n| Method | Signature | Escaping |\n| --- | --- | --- |\n| `raw` | `raw(s: string): HtmlBuilder` | verbatim |\n| `text` | `text(s: string): HtmlBuilder` | React-escaped |\n| `attr` | `attr(s: string): HtmlBuilder` | React-escaped (identical to `text`) |\n\n---\n\n## 4. Escaping (React-exact)\n\n`setText`, `setAttr`, and `HtmlBuilder.text` / `.attr` escape **exactly as\nReact does** (`react-dom/server`'s `escapeTextForBrowser`, regex `/[\"'&<>]/`),\nso the server-rendered markup and the client hydration agree byte-for-byte:\n\n```\n\"  →  &quot;        &  →  &amp;        '  →  &#x27;\n<  →  &lt;          >  →  &gt;\n```\n\nThe detail that bites: `'` becomes `&#x27;` (React's exact choice), **not**\n`&#39;`. If your escaping deviates from this by even one entity, `hydrateRoot`\nsees different markup and React throws a hydration mismatch and re-renders the\nsubtree. The guest's `escapeHtml` and the build's `reactEscapeHtml` are pinned\nto be byte-identical for exactly this reason.\n\n`setRaw` and `HtmlBuilder.raw` do **not** escape, they insert your bytes\nverbatim. That is the right tool for markup you produced or sanitized yourself\n(the same contract as `dangerouslySetInnerHTML`), and the wrong tool for\nanything derived from request input.\n\n---\n\n## 5. The build flow and generated artifacts\n\n`extractTemplates` (driven by `toiljs build`) does, for each `ssr = true` route:\n\n1. loads the route + its layout chain through a short-lived Vite SSR server;\n2. calls the `loader` with sample params to get representative data;\n3. renders the page under its layouts with the markers in **sentinel mode**\n   (`__setSsrBuild(true)`), each marker emits a Private-Use-Area sentinel token\n   instead of rendering normally;\n4. splices that into the built shell's `<div id=\"root\">` and adds the SSR marker\n   `<template id=\"__toil_ssr\"></template>` (this is what the client `mount` looks\n   for to switch to `hydrateRoot`);\n5. strips the sentinel tokens, records their **byte offsets**, and writes the\n   artifacts.\n\n### Where the artifacts land\n\nFor a route named `<name>` (see below), under `build/client/_ssr/`:\n\n| File | Consumer | Contents |\n| --- | --- | --- |\n| `<name>.tmpl` | edge host (mmap'd) | the stripped static HTML shell, holes removed |\n| `<name>.slots` | edge host | the binary manifest (offsets, ids, kinds, tmpl_len, hash) |\n| `<name>.slots.ts` | guest build | the generated `Slot` enum + `HASH` AssemblyScript module |\n| `templates.json` | index | `[{ route, name, hash }]` for every extracted template |\n\nThe `.tmpl` and `.slots` are then **copied** into the edge host bundle at\n`hosts/edge/_tmpl/<name>.{tmpl,slots}`.\n\nThe build also writes the **server-importable** `Slot` + `HASH` module to\n`server/_ssr/<name>.slots.ts`, the one your `render` imports. It is generated\nand gitignored; never hand-edit it (see the two-pass note below).\n\n### Route name derivation (`routeTemplateName`)\n\nThe `<name>` is a file-safe slug of the route pattern: non-alphanumerics collapse\nto `_`, leading/trailing `_` are trimmed, empty → `index`.\n\n| Route pattern | `<name>` |\n| --- | --- |\n| `/hello` | `hello` |\n| `/` | `index` |\n| `/u/:name` | `u_name` |\n| `/blog/[id]` | `blog_id` |\n\n### The two-pass build: no hand-kept slots\n\nThe final extraction runs **after** the Vite client build (the built shell's\nhashed `<script>`/`<link>` tags are part of the template, so they must be in the\n`HASH`), but the server (guest wasm) is compiled **before** it. A naive build\ntherefore can't generate `<name>.slots.ts` in time for the `render` to import\nit. toiljs closes this with a **two-pass** build, so a clean build needs **zero\nhand-maintained slots**:\n\n1. **Slots pre-pass** (before the server build) renders every `ssr = true`\n   route to its `Slot` enum + `HASH` and writes the server-importable module at\n   `server/_ssr/<name>.slots.ts`. This is the file your `render` imports, it is\n   **generated, gitignored, and never hand-edited**.\n2. The server compiles against that module.\n3. The client (Vite) builds.\n4. **Final extraction** re-renders against the real built shell and rewrites\n   `server/_ssr/<name>.slots.ts` with the authoritative `HASH`. If the hash\n   rotated since the pre-pass, the build recompiles the server **once** so the\n   guest bakes the deployed hash.\n\nSo authoring an SSR route is just the route + the `render`; the `Slot` / `HASH`\nmodule is entirely build-managed. (On an unchanged rebuild the pre-pass reuses\nthe prior build's shell, so the hashes already match and step 4's recompile is\nskipped.)\n\n---\n\n## 6. Hash coherence and the values envelope\n\nEvery values envelope carries the guest's compiled-in 32-byte `HASH`. The edge\ncompares it against the deployed template's hash and **rejects a mismatch** with\na fail-safe 500 rather than splicing values into the wrong template. A mismatch\nmeans deploy skew: the guest was built against one version of the template and a\ndifferent one is deployed.\n\nThe hash is `sha256(tmpl || \\0 || canonicalManifest(slots))`, so any change to\nthe static HTML, a hole's id/kind, or the repeat nesting rotates it.\n\nThe guest serializes `SlotValues` to this little-endian, no-padding layout (the\nedge decodes it and splices against the template manifest):\n\n```\nu16  status\n[32] template_hash\nu16  n_headers\n  for each header: u16 name_len, u16 val_len, name bytes, val bytes\nu16  n_slots\n  for each value:  u16 slot_id, u8 kind, u32 value_len, value bytes\n```\n\n`kind` is `0=text, 1=raw, 2=attr, 3=repeat`. The host keys values by `slot_id`\nand inserts each at the **manifest-fixed** offset, so the guest can never choose\n*where* bytes land, only what they are. If a value cannot be represented\n(a count or length overflows its field width, or the hash is the wrong size),\nthe encoder writes the same fail-safe 500/zero-hash envelope instead of corrupt\nbytes.\n\nThe matching `.slots` manifest the host reads is a 46-byte header\n(`\"TSLT\"` magic, u16 version, u16 flags, u32 tmpl_len, 32-byte hash, u16 n_slots)\nfollowed by 8-byte entries (`u32 offset, u16 slot_id, u8 kind, u8 reserved`).\n\n---\n\n## 7. Dev server and testing\n\n`toiljs dev` serves SSR routes the same way the edge does. It runs the **real**\n`render` export (`WasmServerModule.dispatchRender`), decodes the values\nenvelope, and splices the values into the route's template, so you get real\nserver-rendered HTML locally (`curl` a route, or view source), which then\nhydrates in place. The dev template is extracted once at startup against the\nlive (Vite-transformed) dev shell rather than a built one; a route's per-request\n**values** are always live, but a change to its **markup** needs a dev restart\nto re-extract. A fail-safe envelope (no renderer matched) falls back to client\nrendering.\n\nThe end-to-end test (`test/ssr-render.test.ts`) drives the same `dispatchRender`\npath directly: it calls `dispatchRender({ path: '/hello' })`, decodes the\nenvelope, asserts the slots, and splices against the built `hello.tmpl`.\n\n---\n\n## 8. Complete worked example: `/hello`\n\nThis is the full, copy-pasteable chain. All four files are real and tested.\n\n### `client/routes/hello.tsx` (the route)\n\n```tsx\nimport { Hole, Island, RawHtml, Repeat, useLoaderData } from 'toiljs/client';\n\nexport const ssr = true;\n\nexport const metadata: Toil.Metadata = {\n  title: 'Edge SSR',\n  description: 'A server-rendered greeting, filled at the edge.',\n};\n\ninterface Service { name: string; region: string; }\ninterface GreetingData {\n  name: string;\n  blurbHtml: string;\n  services: Service[];\n}\n\n// Build-time sample data, only the SHAPE matters; the real per-request values\n// come from the SERVER render. The repeat sample needs at least one row.\nexport const loader = ({ params }: { params: Record<string, string> }): GreetingData => ({\n  name: params.name ?? 'world',\n  blurbHtml: 'Rendered at the <strong>edge</strong> from a tiny values envelope.',\n  services: [\n    { name: 'record', region: 'us-east' },\n    { name: 'unique', region: 'eu-west' },\n    { name: 'counter', region: 'ap-south' },\n  ],\n});\n\nexport default function Hello(): React.JSX.Element {\n  const d = useLoaderData<typeof loader>();\n  return (\n    <section className=\"hello\">\n      <h1>Hello, <Hole id=\"name\">{d.name}</Hole>!</h1>\n\n      <p className=\"hello-blurb\">\n        <RawHtml id=\"blurb\" html={d.blurbHtml} as=\"span\" />\n      </p>\n\n      <h2>Service snapshot</h2>\n      <ul className=\"hello-services\">\n        <Repeat id=\"services\" each={d.services}>\n          {(s: Service) => (\n            <li>\n              <strong><Hole id=\"svcName\">{s.name}</Hole></strong>\n              <span className=\"hello-region\"><Hole id=\"svcRegion\">{s.region}</Hole></span>\n            </li>\n          )}\n        </Repeat>\n      </ul>\n\n      <Island>\n        <p className=\"hello-island\">\n          Hydrated in your browser at {new Date().toLocaleTimeString()}.\n        </p>\n      </Island>\n    </section>\n  );\n}\n```\n\n### `server/_ssr/hello.slots.ts` (generated by the build; do not edit)\n\n```ts\n// AUTO-GENERATED by toil (edge SSR). Do not edit.\n\n/** Stable hole ids for this route's template (document order). */\nexport enum Slot {\n  name = 0,\n  blurb = 1,\n  services = 2,\n}\n\n/** Coherence hash (32 bytes), written by the build's slots pre-pass; the host\n * rejects a response whose hash != the deployed template. */\nexport const HASH: StaticArray<u8> = [\n  0xcb, 0x12, 0x5e, 0x19, 0x46, 0x32, 0x58, 0x25, 0xd3, 0xf0, 0x44, 0xc5, 0x41, 0x0c, 0x34, 0x3b,\n  0x69, 0xd3, 0x62, 0xb3, 0x24, 0x25, 0x79, 0xc4, 0x76, 0x89, 0xfb, 0x25, 0x6e, 0x35, 0x02, 0x31,\n];\n```\n\n(Only the **top-level** holes get a `Slot` id, `name`, `blurb`, `services`. The\nnested `svcName` / `svcRegion` live inside the repeat row sub-template, which the\nguest stamps with `HtmlBuilder`, so they are not separate slots.)\n\n### `server/SsrHelloRender.ts` (the render)\n\n```ts\nimport { HtmlBuilder, Request, SlotValues, Ssr } from 'toiljs/server/runtime';\nimport { HASH, Slot } from './_ssr/hello.slots';\n\nclass Service {\n  constructor(public name: string, public region: string) {}\n}\n\n/** Pull `?name=...`, defaulting to `world` (matches the route loader default). */\nfunction greetingName(req: Request): string {\n  const q = req.path.indexOf('?');\n  if (q < 0) return 'world';\n  const parts = req.path.substring(q + 1).split('&');\n  for (let i = 0; i < parts.length; i++) {\n    if (parts[i].startsWith('name=')) {\n      const v = parts[i].substring(5);\n      return v.length > 0 ? v : 'world';\n    }\n  }\n  return 'world';\n}\n\nfunction renderHello(req: Request): SlotValues | null {\n  if (req.path != '/hello' && !req.path.startsWith('/hello?')) return null;\n\n  const v = new SlotValues(HASH);\n\n  // Text hole, React-escaped (so ?name=<a>&b is safe).\n  v.setText(Slot.name, greetingName(req));\n\n  // Raw hole, verbatim; a fixed, trusted blurb (no request data).\n  v.setRaw(Slot.blurb, 'Rendered at the <strong>edge</strong> from a tiny values envelope.');\n\n  // Repeat, stamp the captured row markup once per item. The row sub-template\n  // is <li><strong>{svcName}</strong><span class=\"hello-region\">{svcRegion}</span></li>;\n  // .text(...) escapes each nested hole exactly as React does.\n  const services: Service[] = [\n    new Service('record', 'us-east'),\n    new Service('unique', 'eu-west'),\n    new Service('counter', 'ap-south'),\n  ];\n  const rows = new HtmlBuilder();\n  for (let i = 0; i < services.length; i++) {\n    const s = services[i];\n    rows.raw('<li><strong>').text(s.name)\n        .raw('</strong><span class=\"hello-region\">').text(s.region)\n        .raw('</span></li>');\n  }\n  v.setRepeat(Slot.services, rows);\n\n  return v;\n}\n\n// Side-effect registration: main.ts imports this module so the build compiles\n// it in and this renderer joins the SSR router.\nSsr.register(renderHello);\n```\n\n### `server/main.ts` (the load-bearing import)\n\n```ts\nimport { Server } from 'toiljs/server/runtime';\n// ... other surface imports ...\n\n// Edge SSR: importing the render module compiles it in and self-registers its\n// /hello renderer. Without this import the renderer never registers.\nimport './SsrHelloRender';\n\nServer.handler = () => new AppHandler();\n\nexport * from 'toiljs/server/runtime/exports'; // surfaces `handle` AND `render`\n```\n\nThe spliced first-paint HTML for `GET /hello` is byte-identical to what React\nrenders for the same data:\n\n```html\n<section class=\"hello\"><h1>Hello, world!</h1>\n<p class=\"hello-blurb\"><span>Rendered at the <strong>edge</strong> from a tiny values envelope.</span></p>\n<h2>Service snapshot</h2>\n<ul class=\"hello-services\">\n<li><strong>record</strong><span class=\"hello-region\">us-east</span></li>\n<li><strong>unique</strong><span class=\"hello-region\">eu-west</span></li>\n<li><strong>counter</strong><span class=\"hello-region\">ap-south</span></li>\n</ul></section>\n```\n\nThe `<Island>` is empty here (no first paint); it fills in after hydration.\n\n---\n\n## 9. Pitfalls and debugging\n\n- **Route skipped at build (warning, no SSR).** The route or a layout above it\n  threw under static markup, almost always a router hook (`useRouter`,\n  `usePathname`, …) or a browser-only API rendered outside an `<Island>`. The\n  build prints `toil: SSR skipped <pattern> (...)` and the route falls back to\n  client rendering. Move the offending content into an `<Island>`.\n\n- **Hash mismatch / clean 500 after editing a template.** Any change to the\n  page's static markup, a hole id/kind, or the repeat structure rotates the\n  `HASH`. The host rejects a stale guest hash. A normal `toiljs build`\n  regenerates `server/_ssr/<name>.slots.ts` and rebakes the guest, so this only\n  surfaces from a partial or stale deploy (a guest built against a different\n  template than the one deployed), never from hand-copied slots.\n\n- **Hydration mismatch (flash / React re-render in the browser).** Two common\n  causes. (1) The client **loader** does not reproduce the values the server\n  `render` stamped. Hydration re-renders the route with the loader's data, so for\n  any request-derived hole the loader must derive the **same** value the server\n  `render` does (e.g. read the same `?query` / param). The two are separate\n  sources (the client loader is TypeScript; the server `render` is the wasm\n  guest), so keeping them in sync is the author's contract; if the client cannot\n  reproduce a value, put that content in an `<Island>`. (2) A marker (or a\n  non-static node) rendered outside an `<Island>`, or hole escaping that does not\n  match React's (e.g. emitting `&#39;` instead of `&#x27;`, or using `setRaw`\n  where the client would escape). Keep dynamic text in `<Hole>` / `setText` and\n  client-only content in `<Island>`.\n\n- **Route renders client-side only even though `ssr = true`.** You forgot to\n  `import './SsrHelloRender'` in `server/main.ts`, so `Ssr.register` never ran\n  and `Ssr.dispatch` returns `null`. Add the import. (Plain render modules are\n  not auto-discovered the way `@rest`/`@service` files are.)\n\n- **`setRaw` injecting unsanitized request data.** `setRaw` is verbatim, never\n  pass it anything derived from request input you have not sanitized. Use\n  `setText` for request-derived text.\n\n- **Empty `<Repeat>` sample at build.** The build captures the row sub-template\n  from the **first** sample row. If your build-time `loader` returns an empty\n  array for a `<Repeat>`, there is no row to capture. Give the build sample at\n  least one representative row.\n</content>\n</invoke>\n",
     "rpc.md": "# RPC and the generated client\n\nThe server build with `--rpcModule shared/server.ts` scans your decorated\nsurface (`@data`, `@user`, `@service`/`@remote`, `@rest`) and emits one\nTypeScript module: a typed `Server` proxy, the `@data` codec classes, the REST\nfetch client, and the `getUser()` accessor. The client imports that file and\ncalls the server with full type-safety and editor autocomplete. The file is\nregenerated on every server build, so it never drifts from the server.\n\n```sh\ntoilscript --target release --rpcModule shared/server.ts\n```\n\n## `@service` and `@remote`\n\nA `@service` class exposes its `@remote` methods as callable RPC. A top-level\n`@remote` function is exposed directly.\n\n```ts\n@service\nclass Stats {\n  @remote\n  public playerCount(): i32 { return store.size; }\n}\n\n@remote\nfunction ping(n: i32): i32 { return n + 1; }\n```\n\nThe generated client surfaces these on the global `Server` proxy. A service is\nkeyed by its class name with the first letter lowercased (`Stats` → `stats`):\n\n```ts\nawait Server.stats.playerCount(); // Promise<number>\nawait Server.ping(42);            // Promise<number>\n```\n\nArguments and return values are `@data`-typed; scalars map to TS as below.\n\n## The generated `Server` surface\n\n`shared/server.ts` declares a global `Server` whose shape is, schematically:\n\n```ts\ndeclare global {\n  const Server: {\n    // top-level @remote functions\n    ping(n: number): Promise<number>;\n\n    // @service classes (keyed by lowercased name)\n    readonly stats: {\n      playerCount(): Promise<number>;\n    };\n\n    // @rest controllers, under REST\n    readonly REST: {\n      readonly players: {\n        get(args: { params: { id: string | number | bigint }; query?: …; headers?: … }): Promise<Response>;\n        create(args: { body: NewPlayer; query?: …; headers?: … }): Promise<Player>;\n      };\n    };\n  };\n}\n```\n\n### Type mapping (ToilScript → TypeScript)\n\n| ToilScript | TypeScript |\n| --- | --- |\n| `u8`,`u16`,`u32`,`i8`,`i16`,`i32`,`f32`,`f64` | `number` |\n| `u64`,`i64`,`u128`,`i128`,`u256`,`i256` | `bigint` |\n| `bool` | `boolean` |\n| `string` | `string` |\n| a `@data` class `T` | `T` (the emitted class) |\n| `T[]` | `T[]` |\n\n64-bit-and-larger integers are `bigint` on the client and travel as decimal\nstrings on the JSON wire, so they are exact at any magnitude.\n\n### Emitted `@data` classes\n\nEach `@data` (and `@user`) class becomes an exported TS class with the fields, a\ndefaulted constructor, and the matching codec:\n\n```ts\nexport class Player {\n  constructor(public username = '', public admin = false, public score = 0n) {}\n  encodeInto(w: DataWriter): void { /* … */ }\n  encode(): Uint8Array { /* dataId prefix + fields */ }\n  static decodeFrom(r: DataReader): Player { /* … */ }\n  static decode(buf: Uint8Array): Player { /* … */ }\n  static dataId(): number { /* FNV-1a of \"Player\" */ }\n  static fromJSONValue(v: any): Player { /* revive, 64-bit from strings */ }\n  toJSONValue(): any { /* 64-bit as decimal strings */ }\n}\n```\n\nThe codec is byte-compatible with the server's `@data` codec, so binary bodies\nround-trip exactly between client and wasm.\n\n## The REST fetch client\n\nEvery `@rest` route also gets a typed fetch wrapper under `Server.REST.<key>`,\nkeyed by the controller name lowercased. The call argument is an object:\n\n```ts\nServer.REST.players.create({\n  body: new NewPlayer('alice'),     // present iff the route takes a body\n  // params: { id: 7 },             // present iff the path has :params\n  query: { ref: 'home' },           // optional\n  headers: { 'x-trace': traceId },  // optional\n});\n```\n\n- If the route has no params and no body, the whole argument is optional\n  (`args?`).\n- The wrapper builds the URL (substituting `:params`, appending `query`),\n  `fetch`es with `credentials` as configured, throws on a non-2xx status, and\n  decodes the response into the route's return type.\n- A route declared to return `Response` resolves to the raw `fetch` `Response`,\n  so you can stream or inspect headers yourself.\n\n```ts\nconst player = await Server.REST.players.create({ body: new NewPlayer('alice') });\n//    ^? Player\n```\n\n## `getUser()`\n\nWhen the server declares a `@user` class, the generated module also exports a\ntyped, no-argument `getUser()` that reads the readable companion cookie and\ndecodes it with the generated codec:\n\n```ts\nimport { getUser } from './shared/server';\n\nconst user = getUser(); // Account | null, fully typed\n```\n\nThis is **display-only**: the server re-verifies the signed session on every\n`@auth` request. See [Auth](./auth.md) for the full picture.\n\n## Notes\n\n- `shared/server.ts` is generated; never edit it by hand. Re-run the server\n  build (or `toiljs dev`, which does it on save) to refresh it.\n- The `Server` proxy is declared as an ambient global on the client; the runtime\n  implementation is provided by toiljs. The REST client and `getUser` are real\n  exported values in the generated module.\n",
-    "tiers.md": "# Deployment tiers\n\nA Toil app's server runs across several deployment **tiers** from one source\ntree. Each tier has a different lifetime and placement on the edge, and compiles\ninto its own WebAssembly artifact. You write one project; `toiljs build` decides\nwhich entries belong to which tier and emits one `.wasm` per tier. You opt into a\ntier purely by adding its entry file and surface decorator; nothing else changes.\n\n## The tiers\n\n| Entry (`server/`) | Surface | Artifact | Tier | Lifetime / placement |\n| --- | --- | --- | --- | --- |\n| `main.ts` | `@rest` / `@service` / `@remote` | `build/server/release.wasm` | **L1** request | A fresh handler per request, anywhere on the edge. |\n| `main.stream.ts` | `@stream` | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |\n| `main.daemon.ts` | `@daemon` / `@scheduled` | `build/server/release-cold.wasm` | **L4** daemon | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md). |\n\nThe three tiers differ in how long a box lives and how many of it exist:\n\n- **L1 request** is stateless. A `@rest` handler's fields reset each request,\n  because a fresh box serves each one, anywhere on the edge.\n- **L2/L3 stream** is resident per connection. A `@stream` box is created when a\n  connection opens, lives for its lifetime, and is torn down on close, so its\n  fields persist across every event.\n- **L4 daemon** is a single elected leader per domain - the global coordination\n  tier - running recurring background work on a cadence.\n\n## How the build works\n\n`toiljs build` runs one toilscript pass per tier, handing each pass only the\nentries that belong to it. Tier membership is decided by the surface decorator or\nby the entry naming convention:\n\n- a runtime-export entry that is **not** `*.stream.ts` or `*.daemon.ts` is the\n  **request** entry (`main.ts`), which compiles `@rest` / `@service` / `@remote`;\n- `*.stream.ts` is the **stream** entry, which compiles `@stream`;\n- `*.daemon.ts` is the **daemon** entry, which compiles `@daemon` / `@scheduled`.\n\nPlain `@data` and helper modules carry no tier of their own, so they are shared\ninto every artifact. Routing each entry to exactly one tier is what keeps\n`release.wasm` free of `stream_dispatch` and keeps the daemon artifact free of\nthe request `handle`.\n\nEach entry is a thin file that imports its tier's modules and re-exports the\nright runtime hooks. The stream and request entries re-export the request runtime\nexports; the daemon entry does not, because a cold artifact exposes\n`daemon_start` / `scheduled_tick`, not `handle`:\n\n```ts\n// server/main.stream.ts - the L2/L3 stream entry\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\nimport './streams/Echo';\n\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\n```ts\n// server/main.daemon.ts - the L4 daemon entry\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\nimport './daemon/Jobs';\n\n// NOTE: no `export *` from the request runtime - a cold artifact exposes\n// daemon_start/scheduled_tick, not the request `handle`.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\nA single build produces the artifacts side by side:\n\n```sh\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request    (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)\n```\n\n## Single-artifact default\n\nA project with no `@stream` and no `@daemon` surface keeps the legacy\nsingle-artifact build - just `build/server/release.wasm`. The stream and daemon\ntiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get\n`release-stream.wasm`, add `main.daemon.ts` (and a `@daemon` class) to get\n`release-cold.wasm`. Existing request-only apps build exactly as before.\n\n## When to use each tier\n\n- **L1 request** for request/response and RPC: `@rest` controllers, `@service` /\n  `@remote` callable surface. The default tier; most code lives here.\n- **L2/L3 stream** for stateful, long-lived connections where per-connection\n  state must survive across events - the resident box is pinned to one worker for\n  the connection's lifetime.\n- **L4 daemon** for scheduled and coordination work: rollups, cleanup, polling an\n  upstream, anything that should run exactly once per domain on a cadence rather\n  than per request.\n\n```ts\n// server/streams/Echo.ts - L2/L3: the box is resident, so `count` persists.\n@stream('echo')\nclass Echo {\n    private count: i32 = 0;\n\n    @connect onConnect(): void { this.count = 0; }\n    @message onMessage(): void { this.count = this.count + 1; }\n    @close   onClose(): void { /* box torn down after this hook */ }\n}\n```\n\n```ts\n// server/daemon/Jobs.ts - L4: one leader per domain runs this hourly.\n@daemon\nclass Jobs {\n    @scheduled('1h')\n    hourly(): void {\n        // Recurring background work: rollups, cleanup, polling an upstream, ...\n    }\n}\n```\n\n## See also\n\n- [Streams](./streams.md) - the `@stream` surface and the L2/L3 tier.\n- [Daemon](./daemon.md) - the `@daemon` surface and the L4 tier.\n- [Routing](./routing.md) - `@rest` controllers on the L1 request tier.\n- [RPC](./rpc.md) - `@service` / `@remote` and the generated client.\n",
+    "tiers.md": "# Deployment tiers\n\nA Toil app's server runs across several deployment **tiers** from one source\ntree. Each tier has a different lifetime and placement on the edge, and compiles\ninto its own WebAssembly artifact. You write one project; `toiljs build` decides\nwhich entries belong to which tier and emits one `.wasm` per tier. You opt into a\ntier purely by adding its entry file and surface decorator; nothing else changes.\n\n## The tiers\n\n| Entry (`server/`) | Surface                          | Artifact                           | Tier             | Lifetime / placement                                                                                                                              |\n| ----------------- | -------------------------------- | ---------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `main.ts`         | `@rest` / `@service` / `@remote` | `build/server/release.wasm`        | **L1** request   | A fresh handler per request, anywhere on the edge.                                                                                                |\n| `main.stream.ts`  | `@stream`                        | `build/server/release-stream.wasm` | **L2/L3** stream | One resident box per connection, pinned to a worker via QUIC connection-id steering; its state survives every event. See [Streams](./streams.md). |\n| `main.daemon.ts`  | `@daemon` / `@scheduled`         | `build/server/release-cold.wasm`   | **L4** daemon    | Exactly one leader-elected box per domain (warm standby, at-most-once failover) firing `@scheduled` tasks. See [Daemon](./daemon.md).             |\n\nThe three tiers differ in how long a box lives and how many of it exist:\n\n- **L1 request** is stateless. A `@rest` handler's fields reset each request,\n  because a fresh box serves each one, anywhere on the edge.\n- **L2/L3 stream** is resident per connection. A `@stream` box is created when a\n  connection opens, lives for its lifetime, and is torn down on close, so its\n  fields persist across every event.\n- **L4 daemon** is a single elected leader per domain - the global coordination\n  tier - running recurring background work on a cadence.\n\n## How the build works\n\n`toiljs build` runs one toilscript pass per tier, handing each pass only the\nentries that belong to it. Tier membership is decided by the surface decorator or\nby the entry naming convention:\n\n- a runtime-export entry that is **not** `*.stream.ts` or `*.daemon.ts` is the\n  **request** entry (`main.ts`), which compiles `@rest` / `@service` / `@remote`;\n- `*.stream.ts` is the **stream** entry, which compiles `@stream`;\n- `*.daemon.ts` is the **daemon** entry, which compiles `@daemon` / `@scheduled`.\n\nPlain `@data` and helper modules carry no tier of their own, so they are shared\ninto every artifact. Routing each entry to exactly one tier is what keeps\n`release.wasm` free of `stream_dispatch` and keeps the daemon artifact free of\nthe request `handle`.\n\nEach entry is a thin file that imports its tier's modules and re-exports the\nright runtime hooks. The stream and request entries re-export the request runtime\nexports; the daemon entry does not, because a cold artifact exposes\n`daemon_start` / `scheduled_tick`, not `handle`:\n\n```ts\n// server/main.stream.ts - the L2/L3 stream entry\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\nimport './streams/Echo';\n\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\n```ts\n// server/main.daemon.ts - the L4 daemon entry\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\nimport './daemon/Jobs';\n\n// NOTE: no `export *` from the request runtime - a cold artifact exposes\n// daemon_start/scheduled_tick, not the request `handle`.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n    revertOnError(message, fileName, line, column);\n}\n```\n\nA single build produces the artifacts side by side:\n\n```sh\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request    (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)\n```\n\n## Single-artifact default\n\nA project with no `@stream` and no `@daemon` surface keeps the default\nsingle-artifact build - just `build/server/release.wasm`. The stream and daemon\ntiers are opt-in: add `main.stream.ts` (and a `@stream` class) to get\n`release-stream.wasm`, add `main.daemon.ts` (and a `@daemon` class) to get\n`release-cold.wasm`. Existing request-only apps build exactly as before.\n\n## When to use each tier\n\n- **L1 request** for request/response and RPC: `@rest` controllers, `@service` /\n  `@remote` callable surface. The default tier; most code lives here.\n- **L2/L3 stream** for stateful, long-lived connections where per-connection\n  state must survive across events - the resident box is pinned to one worker for\n  the connection's lifetime.\n- **L4 daemon** for scheduled and coordination work: rollups, cleanup, polling an\n  upstream, anything that should run exactly once per domain on a cadence rather\n  than per request.\n\n```ts\n// server/streams/Echo.ts - L2/L3: the box is resident, so `count` persists.\n@stream('echo')\nclass Echo {\n    private count: i32 = 0;\n\n    @connect onConnect(): void {\n        this.count = 0;\n    }\n    @message onMessage(): void {\n        this.count = this.count + 1;\n    }\n    @close onClose(): void {\n        /* box torn down after this hook */\n    }\n}\n```\n\n```ts\n// server/daemon/Jobs.ts - L4: one leader per domain runs this hourly.\n@daemon\nclass Jobs {\n    @scheduled('1h')\n    hourly(): void {\n        // Recurring background work: rollups, cleanup, polling an upstream, ...\n    }\n}\n```\n\n## See also\n\n- [Streams](./streams.md) - the `@stream` surface and the L2/L3 tier.\n- [Daemon](./daemon.md) - the `@daemon` surface and the L4 tier.\n- [Routing](./routing.md) - `@rest` controllers on the L1 request tier.\n- [RPC](./rpc.md) - `@service` / `@remote` and the generated client.\n",
     "streams.md": "# Streams\n\nA `@stream` declares a long-lived, stateful protocol handler over WebTransport -\nthe **L2/L3** (regional / continental) stream tier of the Toil edge. Unlike a\n`@rest` route, which is a fresh handler per request, a `@stream` is a **resident\nWebAssembly box per connection**: it is created when the connection opens, lives\nfor the whole connection, and is torn down on close. State stored on its fields\n**persists across events**, because it is the same box every time.\n\n```ts\n@stream('echo')\nclass Echo {\n  private count: i32 = 0;\n\n  @connect\n  onConnect(): void {\n    this.count = 0;\n  }\n\n  @message\n  onMessage(): void {\n    this.count = this.count + 1;\n  }\n\n  @close\n  onClose(): void {}\n}\n```\n\n## Declaring a stream\n\n`@stream(name)` marks a class as a stream handler and mounts it at the given\nname/route. The class becomes a resident box; its fields are the connection's\nstate.\n\n```ts\n@stream('echo')            // mounted at /echo\nclass Echo { /* ... */ }\n```\n\nA stream lives on the **L2/L3 stream tier** and its default scope is **Regional\n(L2)**. See [Tiers](./tiers.md) for the full tier model.\n\n## Lifecycle hooks\n\nA stream method is a lifecycle hook, chosen by its decorator. All hooks are\noptional - declare only the ones you need; a missing hook is a no-op.\n\n| Decorator | Fires when |\n| --- | --- |\n| `@connect` | the connection opens (the box has just been created). |\n| `@message` | an inbound frame arrives. |\n| `@close` | the connection closes gracefully (the box is torn down after this hook). |\n| `@disconnect` | the transport is lost abruptly. |\n| `@channel` | an opt-in distributed channel delivers a message (advanced; see below). |\n\nThe `Echo` example above shows why state survives: `count` is set to `0` in\n`@connect`, incremented on every `@message`, and the increments **accumulate**.\nThat is only possible because the same resident box handles every event for the\nconnection. A `@rest` handler's fields would reset on each request, since a\nfresh handler is constructed per request.\n\n`@channel` is an opt-in **distributed** channel (advanced) - a way for boxes to\nexchange messages beyond a single connection. It is mentioned here for\ncompleteness; most streams use only the four connection-lifecycle hooks.\n\n## Placement\n\nA `@stream` is distributed across the eligible L2/L3 stream nodes and pinned to\n**ONE worker** for the connection's lifetime via QUIC connection-id steering. The\nconnection always lands on the same worker, so the box - and the state on its\nfields - survives every event. You do not manage placement; the edge steers each\nconnection to its resident box automatically.\n\n## The entry: `main.stream.ts`\n\nThe stream surface has its own entry, `server/main.stream.ts`, distinct from the\nrequest entry (`server/main.ts`). It re-exports the WASM runtime exports and\nimports the `@stream` classes, which pulls their compiler-generated\n`stream_dispatch` export into the artifact.\n\n```ts\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport './streams/Echo';\n\n// Re-export the WASM entry points the host binds, exactly like main.ts.\nexport * from 'toiljs/server/runtime/exports';\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n  revertOnError(message, fileName, line, column);\n}\n```\n\nThis entry compiles into its **own artifact**, `build/server/release-stream.wasm`\n- the resident stream box - separate from the request build,\n`build/server/release.wasm`. Add a stream as you grow by importing it here:\n\n```ts\nimport './streams/Echo';\n```\n\n## Build\n\n`toiljs build` produces `release-stream.wasm` automatically when the project\ndeclares a `@stream` surface. The single build runs one toilscript pass per tier,\nhanding each pass only the entries that belong to it, so `release.wasm` never\ncontains `stream_dispatch` and the stream artifact never contains the request\n`handle`. Plain `@data` and helper modules are shared into every artifact.\n\n```sh\n$ toiljs build\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request   (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream  (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon     (exports: daemon_start, scheduled_tick)\n```\n\nSee [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.\n\n## What runs today\n\nThe stream lifecycle hooks (`@connect` / `@message` / `@close` / `@disconnect`)\nrun **today**, and this proves a resident box keeps state across events - that is\nexactly what the `Echo` example demonstrates by counting frames.\n\nReading the inbound frame **bytes** and replying is the **next increment**, not\nyet available. That bridge is the `StreamPacket` / `StreamOutbound` API and the\ntyped `Server.STREAM.echo.connect()` client. The intended shape, once it lands:\n\n```ts\n@message reply(packet: StreamPacket): StreamOutbound {\n  return StreamOutbound.reply(packet.bytes());   // echo the bytes back\n}\n```\n\n```ts\nconst stream = await Server.STREAM.echo.connect();\nstream.send(new TextEncoder().encode('hello'));\n```\n\nUntil then, the hooks run on the connection lifecycle and you observe state\nthrough fields, as `Echo` does. See the comments in\n`examples/streams/server/streams/Echo.ts` for the authoritative note.\n\n---\n\nSee also: [Tiers](./tiers.md), [Daemon](./daemon.md), [Routing](./routing.md).\n",
     "daemon.md": "# Daemon\n\n`@daemon` declares a single, leader-elected background worker for your domain -\nthe **L4** (global) coordination tier of the Toil edge. Where a `@rest` handler\nis a fresh instance per request and a `@stream` box is one instance per\nconnection, there is exactly **one** daemon per domain at a time. The edge keeps\na warm standby ready and fails over at-most-once, so the daemon is the right\nplace for work that must happen once globally rather than once per request.\n\n```ts\n@daemon\nclass Jobs {\n  @scheduled('1h')\n  hourly(): void {\n    // Runs once an hour on the elected leader. Put recurring background work\n    // here (rollups, cleanup, polling an upstream, ...).\n  }\n}\n```\n\n## `@daemon` classes\n\n`@daemon` marks a class as the domain's background worker. The class is resident:\nit is created once on the elected leader and lives for as long as that leader\nholds the lease, so its fields persist across scheduled runs (a `@rest`\nhandler's fields would reset every request).\n\nExactly one daemon instance runs per domain at any moment. A second node stays a\nwarm standby and only becomes active if the current leader's lease lapses. You do\nnot start, stop, or place the daemon yourself - the edge elects the leader and\ndrives it.\n\n## `@scheduled`\n\nA `@scheduled` method declares a task that fires on a cadence, always on the\n**elected leader**. The single string argument is the cadence:\n\n```ts\n@scheduled('1h')\nhourly(): void { /* ... */ }\n```\n\n- **Interval strings** like `'1h'` fire on that fixed period.\n- **Cron expressions** are also supported when you need a wall-clock schedule\n  rather than a fixed interval.\n\nA class can declare several `@scheduled` methods; each runs on its own cadence.\nBecause only the leader fires them, a task runs once per domain per tick, not\nonce per node.\n\n## The daemon entry\n\nThe daemon surface has its own entry module, `server/main.daemon.ts`. It imports\nthe `@daemon` classes so the compiler-generated `daemon_start` / `scheduled_tick`\nexports are pulled into the artifact:\n\n```ts\n// server/main.daemon.ts\nimport { revertOnError } from 'toiljs/server/runtime/abort/abort';\n\nimport './daemon/Jobs';\n\n// The abort hook (the daemon box reports a trap through it). NOTE: unlike main.ts /\n// main.stream.ts, the daemon entry does NOT re-export the request runtime - a cold\n// artifact exposes daemon_start/scheduled_tick, not the request `handle`.\nexport function abort(message: string, fileName: string, line: u32, column: u32): void {\n  revertOnError(message, fileName, line, column);\n}\n```\n\nNote what is **not** here: unlike `main.ts` and `main.stream.ts`, the daemon\nentry does not `export * from 'toiljs/server/runtime/exports'`. A daemon (cold)\nartifact exposes `daemon_start` and `scheduled_tick`, not the request `handle`.\nAdd a daemon as you grow by importing its module here.\n\n## Build\n\n`toiljs build` runs one toilscript pass per tier and hands each pass only the\nentries that belong to it. When the project declares a `@daemon` / `@scheduled`\nsurface, the daemon pass compiles `server/main.daemon.ts` into its own artifact,\n`build/server/release-cold.wasm`:\n\n```sh\n$ ls build/server/*.wasm\nbuild/server/release.wasm          # L1 request    (exports: handle)\nbuild/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)\nbuild/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)\n```\n\nSo `release.wasm` never contains `scheduled_tick` and the daemon artifact never\ncontains the request `handle`. Plain `@data` and helper modules are shared into\nevery artifact. See [Tiers](./tiers.md) for how the three artifacts are produced\nfrom one source tree.\n\n## Use cases\n\nThe daemon is the once-per-domain tier, so it fits work you want to happen\nglobally on a cadence rather than per request:\n\n- **Periodic rollups** - aggregate counters or events into summaries.\n- **Cleanup** - expire stale rows, prune logs, reclaim resources.\n- **Polling an upstream** - pull from an external API on a schedule.\n- **Global coordination** - any task that must run exactly once across the\n  domain, not once per node.\n\n## Failover\n\nScheduling is **at-most-once**. A `@scheduled` task fires on whichever node\ncurrently holds the leader lease. If that leader fails, the warm standby takes\nover and fires the **subsequent** runs; the edge does not retry or duplicate the\ntick that was in flight when the leader was lost. This trades exactly-once\ndelivery for the guarantee that two nodes never run the same scheduled tick at\nonce, so design tasks to be safe to skip an occasional run and to be idempotent\nwhere a missed run matters.\n\n---\n\nSee also:\n\n- [Tiers](./tiers.md) - the three deployment tiers and how one source tree\n  compiles to a separate artifact per tier.\n- [Streams](./streams.md) - the L2/L3 `@stream` tier (one resident box per\n  connection).\n",
     "data.md": "# Data codec (`@data`)\n\n`@data` turns a plain class into a typed, versionable value with a deterministic\nbinary codec and a JSON codec. It is the backbone of request/response bodies,\nRPC arguments, sessions, and anything you persist. The same class becomes a\nfully typed client type in the generated `shared/server.ts` (see\n[RPC](./rpc.md)).\n\n```ts\n@data\nclass Player {\n  username: string = '';\n  admin: bool = false;\n  score: u64 = 0;\n}\n```\n\nFrom that the compiler synthesizes, on the class:\n\n- `encode(): Uint8Array` / `static decode(buf): T`, the binary codec (with a\n  4-byte type id prefix).\n- `encodeInto(w: DataWriter)` / `static decodeFrom(r: DataReader)`, the codec\n  without the type-id frame, for nesting.\n- `toJSON()` / `static fromJSON(v)`, the JSON codec (64-bit-and-larger integers\n  as decimal strings, so they survive `JSON.parse` exactly).\n- `static dataId(): u32`, a stable FNV-1a hash of the class name, written as the\n  type-id prefix by `encode()`.\n\nFields may be scalars (`u8`..`u256`, `i8`..`i256`, `f32`, `f64`, `bool`),\n`string`, a nested `@data` class, or an array `T[]` of any of these. Give every\nfield a default; the generated decoder and the client constructor use them.\n\n## Using `@data` in routes\n\nIn a **JSON** route, a `@data` parameter is revived from the parsed body and a\n`@data` return value is serialized with `toJSON()`. In a **Binary** route, the\nparameter is `decode`d from the raw body and the return value is `encode`d. The\nroute's stream mode (see [Routing](./routing.md#data-streams)) picks which.\n\n```ts\n@post('/')                       // JSON route\npublic create(input: NewPlayer): Player { /* input from JSON, Player to JSON */ }\n\n@route({ method: Methods.POST, path: '/blob', stream: DataStream.Binary })\npublic blob(input: FileData): FileResult { /* input.decode, result.encode */ }\n```\n\n## The binary codec: `DataWriter` / `DataReader`\n\nWhen you need to lay out bytes yourself, custom bodies, session payloads,\nchallenge messages, use the codec directly. It lives in the `data` module:\n\n```ts\nimport { DataWriter, DataReader } from 'data';\n```\n\nThe codec has a byte-for-byte identical TypeScript implementation in\n`toiljs/io` (`src/io/codec.ts`), so the client can read and write the exact same\nwire format the wasm guest does.\n\n### `DataWriter`\n\nEvery writer method returns the writer for chaining.\n\n| Method | Signature | Wire format |\n| --- | --- | --- |\n| `writeU8` / `writeI8` | `(v): DataWriter` | 1 byte |\n| `writeU16` / `writeI16` | `(v): DataWriter` | 2 bytes, little-endian |\n| `writeU32` / `writeI32` | `(v): DataWriter` | 4 bytes, LE |\n| `writeU64` / `writeI64` | `(v): DataWriter` | 8 bytes, LE |\n| `writeF32` / `writeF64` | `(v): DataWriter` | 4 / 8 bytes, IEEE-754 LE |\n| `writeBool` | `(v): DataWriter` | 1 byte (`1`/`0`) |\n| `writeBytes` | `(b: Uint8Array): DataWriter` | `u32` length (LE) + raw bytes |\n| `writeString` | `(s: string): DataWriter` | `u32` length (LE) + UTF-8 bytes |\n| `writeU128` / `writeI128` | `(v): DataWriter` | two `u64` limbs (lo, hi) |\n| `writeU256` / `writeI256` | `(v): DataWriter` | four `u64` limbs (lo1, lo2, hi1, hi2) |\n| `length` | `(): i32` | bytes written so far |\n| `toBytes` | `(): Uint8Array` | an exact-length copy of the buffer |\n\n### `DataReader`\n\nReads are bounds-safe: an over-read never traps. It returns a zero/empty default\nand sets the public `ok` flag to `false`. Check `ok` after a sequence of reads\nto detect a truncated or malformed buffer.\n\n| Method | Signature | On over-read |\n| --- | --- | --- |\n| `readU8` / `readI8` | `(): u8 / i8` | `0` |\n| `readU16`..`readU64`, `readI16`..`readI64` | `(): integer` | `0` |\n| `readF32` / `readF64` | `(): f32 / f64` | `0` |\n| `readBool` | `(): bool` | `false` |\n| `readBytes` | `(): Uint8Array` | empty array |\n| `readString` | `(): string` | `\"\"` |\n| `readU128`/`readI128`/`readU256`/`readI256` | `(): bignum` | `0` |\n| `remaining` | `(): i32` | bytes left unread |\n| `ok` | `bool` (field) | `false` once any read over-ran |\n\n### Example\n\n```ts\nimport { DataWriter, DataReader } from 'data';\n\n// Write: u8 version, str name, u64 score, bytes blob\nconst out = new DataWriter()\n  .writeU8(1)\n  .writeString('alice')\n  .writeU64(1234)\n  .writeBytes(payload)\n  .toBytes();\n\n// Read it back\nconst r = new DataReader(out);\nconst version = r.readU8();\nconst name = r.readString();\nconst score = r.readU64();\nconst blob = r.readBytes();\nif (!r.ok) return Response.badRequest('truncated');\n```\n\n## Notes\n\n- **Endianness.** The AS guest codec is little-endian. The TypeScript `toiljs/io`\n  codec defaults to little-endian and also accepts a per-call `be` flag for\n  big-endian network formats; keep both ends on the same setting.\n- **Field order is the format.** The binary layout is exactly the field\n  declaration order. Reordering fields, or changing a type, is a breaking format\n  change. Add new fields at the end and bump a leading version byte if you need\n  to evolve a hand-rolled payload.\n- **`encode()` carries a type id.** The 4-byte `dataId()` prefix lets a decoder\n  confirm it is reading the type it expects. `encodeInto`/`decodeFrom` skip the\n  frame for nesting one `@data` value inside another.\n",

package/src/devserver/daemon/index.ts

@@ -139,20 +139,21 @@ export class DaemonHost implements DaemonRuntime {
         // else the emulator stays off (fail-closed; section 3.3 / 5.1).
         const surface = parseSurface(bytes);
         if (surface === 'invalid') {
-            this.log(pc.red('  ✗ cold artifact toil.surface is corrupt; daemon not started') + '\n');
+            this.log(
+                pc.red('  ✗ cold artifact toil.surface is corrupt; daemon not started') + '\n',
+            );
             if (this.running) this.stop();
             this.loadedMtimeMs = mtimeMs;
             return false;
         }
-        if (surface !== 'absent' && surface.targetMode !== 'cold')
+        if (surface.targetMode !== 'cold')
             this.log(
                 pc.yellow('  ! ') +
                     pc.dim('cold slot holds a hot-mode artifact; ignoring daemon emulator') +
                     '\n',
             );
         const catalog = parseDaemonCatalog(bytes);
-        const declaresDaemon =
-            (surface === 'absent' ? false : surface.flags.daemon) || (catalog?.hasDaemon ?? false);
+        const declaresDaemon = surface.flags.daemon || (catalog?.hasDaemon ?? false);
 
         // A restart: stop the old box (timers + instance), bump epoch, start fresh.
         if (this.running) this.stop();
@@ -318,9 +319,8 @@ export class DaemonHost implements DaemonRuntime {
             const ret = this.exports.scheduled_tick(task.taskIndex); // packed-i64
             if (ret < 0n)
                 this.log(
-                    pc.yellow(
-                        `  ⏱ @scheduled ${task.name} returned error ${decodeAbiError(ret)}`,
-                    ) + '\n',
+                    pc.yellow(`  ⏱ @scheduled ${task.name} returned error ${decodeAbiError(ret)}`) +
+                        '\n',
                 );
         } catch (e) {
             // A trapped tick does NOT tear down the long-lived daemon box (unlike a

package/src/devserver/db/catalog.ts

@@ -48,7 +48,7 @@ export function parseCatalog(wasm: Buffer): DbCatalogState {
 
     const r = new DataReader(sec);
     const version = r.readU16();
-    if (!r.ok || (version !== 1 && version !== 2)) return { kind: 'malformed' };
+    if (!r.ok || version !== 1) return { kind: 'malformed' };
     const ndb = r.readU16();
     for (let d = 0; d < ndb && r.ok; d++) {
         const db = r.readString();
@@ -63,18 +63,14 @@ export function parseCatalog(wasm: Buffer): DbCatalogState {
             r.readU32(); // generation
             const replication = r.readU8(); // emitter order: replication then placement
             const placement = r.readU8();
-            let fillMaxWaitMs = DEFAULT_FILL_WAIT_MS;
-            let fillAllowStale = true;
-            if (version >= 2) {
-                fillMaxWaitMs = r.readU32();
-                const fillAllowStaleByte = r.readU8();
-                if (
-                    fillMaxWaitMs > MAX_FILL_WAIT_MS ||
-                    (fillAllowStaleByte !== 0 && fillAllowStaleByte !== 1)
-                )
-                    return { kind: 'malformed' };
-                fillAllowStale = fillAllowStaleByte === 1;
-            }
+            const fillMaxWaitMs = r.readU32();
+            const fillAllowStaleByte = r.readU8();
+            if (
+                fillMaxWaitMs > MAX_FILL_WAIT_MS ||
+                (fillAllowStaleByte !== 0 && fillAllowStaleByte !== 1)
+            )
+                return { kind: 'malformed' };
+            const fillAllowStale = fillAllowStaleByte === 1;
             const nFields = r.readU16();
             for (let f = 0; f < nFields; f++) {
                 r.readString(); // field name

package/src/devserver/wasm/surface.ts

@@ -18,9 +18,8 @@
  *   u32 data_coherence_hash
  *   u32 pair_coherence_hash    (exactly THREE u32 after build_id, not four)
  *
- * Fail-closed per Part 5's host rule: an ABSENT section is "legacy single
- * artifact, load as hot" (NOT a hard reject); a PRESENT-but-unparseable section is
- * a corrupt artifact -> do not start that artifact's emulator.
+ * Fail-closed per Part 5's host rule: an absent or unparseable section is a
+ * corrupt Toil artifact -> do not start that artifact's emulator.
  */
 
 import { DataReader } from 'toiljs/io';
@@ -47,16 +46,15 @@ export interface Surface {
     readonly pairCoherenceHash: number;
 }
 
-/** `'absent'` => legacy single artifact (load as hot, no emulators).
- *  `'invalid'` => present but corrupt (fail closed). Otherwise the parsed surface. */
-export function parseSurface(wasm: Buffer): Surface | 'absent' | 'invalid' {
+/** `'invalid'` => absent or corrupt (fail closed). Otherwise the parsed surface. */
+export function parseSurface(wasm: Buffer): Surface | 'invalid' {
     let sec: Buffer | null;
     try {
         sec = customSection(wasm, 'toil.surface');
     } catch {
         return 'invalid'; // garbage section table
     }
-    if (sec === null) return 'absent';
+    if (sec === null) return 'invalid';
 
     const r = new DataReader(sec);
     r.readU16(); // format_version

package/test/daemon-build.test.ts

@@ -9,7 +9,7 @@
  *     passes (one `--targetMode cold`, one `--targetMode hot`) and produces BOTH
  *     `release-hot.wasm` and `release-cold.wasm`; the cold artifact decodes to a
  *     daemon catalog and its `toil.surface` is target_mode = cold.
- *   - a project with only the legacy request surface keeps the single-artifact
+ *   - a project with only the default request surface keeps the single-artifact
  *     path (no cold pass, no cold artifact).
  *
  * The build invokes the LOCAL toilscript (branch feat/streams-phase0-compiler),
@@ -17,7 +17,15 @@
  * `node_modules` the same way the dev build resolves it (`require.resolve`).
  */
 
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import {
+    existsSync,
+    mkdirSync,
+    mkdtempSync,
+    readFileSync,
+    rmSync,
+    symlinkSync,
+    writeFileSync,
+} from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -190,8 +198,8 @@ describe.skipIf(!existsSync(LOCAL_TOILSCRIPT))('buildServer two-pass (daemon pro
         // The cold artifact carries the daemon surface + catalog (decoded byte-for-byte).
         const coldBytes = readFileSync(cold);
         const surface = parseSurface(coldBytes);
-        expect(surface !== 'absent' && surface !== 'invalid' && surface.targetMode).toBe('cold');
-        expect(surface !== 'absent' && surface !== 'invalid' && surface.flags.daemon).toBe(true);
+        expect(surface !== 'invalid' && surface.targetMode).toBe('cold');
+        expect(surface !== 'invalid' && surface.flags.daemon).toBe(true);
 
         const catalog = parseDaemonCatalog(coldBytes);
         expect(catalog).not.toBeNull();
@@ -201,12 +209,12 @@ describe.skipIf(!existsSync(LOCAL_TOILSCRIPT))('buildServer two-pass (daemon pro
         expect(catalog!.tasks[1].schedule.kind).toBe('cron');
 
         // A daemon-only project (no request/stream surface) has no hot files, so the hot pass is
-        // skipped (toilscript would HARD-ERROR a @daemon class under --targetMode hot). The legacy
-        // single-artifact `release.wasm` is therefore not produced for a pure background worker.
+        // skipped (toilscript would HARD-ERROR a @daemon class under --targetMode hot). The default
+        // request artifact `release.wasm` is therefore not produced for a pure background worker.
         expect(existsSync(join(tmp, 'build/server/release.wasm'))).toBe(false);
     }, 60_000);
 
-    it('keeps the single-artifact path for a legacy (no-daemon) project', async () => {
+    it('keeps the single-artifact path for a request-only project', async () => {
         scaffold(LEGACY_SRC, BASE_TOILCONFIG);
         await buildServer(tmp);
 

package/test/daemon-catalog.test.ts

@@ -117,7 +117,13 @@ describe('parseDaemonCatalog (Part 5)', () => {
                 name: 'lateMinute',
                 taskIndex: 0,
                 kind: 1,
-                cron: { minute: minuteMask, hour: 0xffffff, dom: 0xfffffffe, month: 0x1ffe, dow: 0x7f },
+                cron: {
+                    minute: minuteMask,
+                    hour: 0xffffff,
+                    dom: 0xfffffffe,
+                    month: 0x1ffe,
+                    dow: 0x7f,
+                },
             },
         ]);
         const cat = parseDaemonCatalog(wasmWithSection('toildaemon.catalog', payload));
@@ -173,10 +179,11 @@ function buildSurfaceBytes(opts: {
 describe('parseSurface (Part 5)', () => {
     it('decodes a cold daemon surface with exactly three trailing u32 hashes', () => {
         const flags = 0b000100 | 0b001000; // daemon (bit2) + scheduled (bit3)
-        const s = parseSurface(wasmWithSection('toil.surface', buildSurfaceBytes({ mode: 1, flags })));
-        expect(s).not.toBe('absent');
+        const s = parseSurface(
+            wasmWithSection('toil.surface', buildSurfaceBytes({ mode: 1, flags })),
+        );
         expect(s).not.toBe('invalid');
-        if (s !== 'absent' && s !== 'invalid') {
+        if (s !== 'invalid') {
             expect(s.targetMode).toBe('cold');
             expect(s.flags.daemon).toBe(true);
             expect(s.flags.scheduled).toBe(true);
@@ -188,13 +195,15 @@ describe('parseSurface (Part 5)', () => {
     });
 
     it('decodes a hot surface (target_mode 0)', () => {
-        const s = parseSurface(wasmWithSection('toil.surface', buildSurfaceBytes({ mode: 0, flags: 1 })));
-        expect(s !== 'absent' && s !== 'invalid' && s.targetMode).toBe('hot');
+        const s = parseSurface(
+            wasmWithSection('toil.surface', buildSurfaceBytes({ mode: 0, flags: 1 })),
+        );
+        expect(s !== 'invalid' && s.targetMode).toBe('hot');
     });
 
-    it("treats an ABSENT section as 'absent' (legacy single artifact, load as hot)", () => {
+    it('fails closed when toil.surface is absent', () => {
         const wasm = wasmWithSection('toildb.catalog', Buffer.from([0x01, 0x00]));
-        expect(parseSurface(wasm)).toBe('absent');
+        expect(parseSurface(wasm)).toBe('invalid');
     });
 
     it("fails closed: a PRESENT but truncated section is 'invalid'", () => {