toiljs 0.0.62 → 0.0.64

package/docs/streams.md

@@ -0,0 +1,147 @@
+# Streams
+
+A `@stream` declares a long-lived, stateful protocol handler over WebTransport -
+the **L2/L3** (regional / continental) stream tier of the Toil edge. Unlike a
+`@rest` route, which is a fresh handler per request, a `@stream` is a **resident
+WebAssembly box per connection**: it is created when the connection opens, lives
+for the whole connection, and is torn down on close. State stored on its fields
+**persists across events**, because it is the same box every time.
+
+```ts
+@stream('echo')
+class Echo {
+  private count: i32 = 0;
+
+  @connect
+  onConnect(): void {
+    this.count = 0;
+  }
+
+  @message
+  onMessage(): void {
+    this.count = this.count + 1;
+  }
+
+  @close
+  onClose(): void {}
+}
+```
+
+## Declaring a stream
+
+`@stream(name)` marks a class as a stream handler and mounts it at the given
+name/route. The class becomes a resident box; its fields are the connection's
+state.
+
+```ts
+@stream('echo')            // mounted at /echo
+class Echo { /* ... */ }
+```
+
+A stream lives on the **L2/L3 stream tier** and its default scope is **Regional
+(L2)**. See [Tiers](./tiers.md) for the full tier model.
+
+## Lifecycle hooks
+
+A stream method is a lifecycle hook, chosen by its decorator. All hooks are
+optional - declare only the ones you need; a missing hook is a no-op.
+
+| Decorator | Fires when |
+| --- | --- |
+| `@connect` | the connection opens (the box has just been created). |
+| `@message` | an inbound frame arrives. |
+| `@close` | the connection closes gracefully (the box is torn down after this hook). |
+| `@disconnect` | the transport is lost abruptly. |
+| `@channel` | an opt-in distributed channel delivers a message (advanced; see below). |
+
+The `Echo` example above shows why state survives: `count` is set to `0` in
+`@connect`, incremented on every `@message`, and the increments **accumulate**.
+That is only possible because the same resident box handles every event for the
+connection. A `@rest` handler's fields would reset on each request, since a
+fresh handler is constructed per request.
+
+`@channel` is an opt-in **distributed** channel (advanced) - a way for boxes to
+exchange messages beyond a single connection. It is mentioned here for
+completeness; most streams use only the four connection-lifecycle hooks.
+
+## Placement
+
+A `@stream` is distributed across the eligible L2/L3 stream nodes and pinned to
+**ONE worker** for the connection's lifetime via QUIC connection-id steering. The
+connection always lands on the same worker, so the box - and the state on its
+fields - survives every event. You do not manage placement; the edge steers each
+connection to its resident box automatically.
+
+## The entry: `main.stream.ts`
+
+The stream surface has its own entry, `server/main.stream.ts`, distinct from the
+request entry (`server/main.ts`). It re-exports the WASM runtime exports and
+imports the `@stream` classes, which pulls their compiler-generated
+`stream_dispatch` export into the artifact.
+
+```ts
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+
+import './streams/Echo';
+
+// Re-export the WASM entry points the host binds, exactly like main.ts.
+export * from 'toiljs/server/runtime/exports';
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+  revertOnError(message, fileName, line, column);
+}
+```
+
+This entry compiles into its **own artifact**, `build/server/release-stream.wasm`
+- the resident stream box - separate from the request build,
+`build/server/release.wasm`. Add a stream as you grow by importing it here:
+
+```ts
+import './streams/Echo';
+```
+
+## Build
+
+`toiljs build` produces `release-stream.wasm` automatically when the project
+declares a `@stream` surface. The single build runs one toilscript pass per tier,
+handing each pass only the entries that belong to it, so `release.wasm` never
+contains `stream_dispatch` and the stream artifact never contains the request
+`handle`. Plain `@data` and helper modules are shared into every artifact.
+
+```sh
+$ toiljs build
+$ ls build/server/*.wasm
+build/server/release.wasm          # L1 request   (exports: handle)
+build/server/release-stream.wasm   # L2/L3 stream  (exports: stream_dispatch)
+build/server/release-cold.wasm     # L4 daemon     (exports: daemon_start, scheduled_tick)
+```
+
+See [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.
+
+## What runs today
+
+The stream lifecycle hooks (`@connect` / `@message` / `@close` / `@disconnect`)
+run **today**, and this proves a resident box keeps state across events - that is
+exactly what the `Echo` example demonstrates by counting frames.
+
+Reading the inbound frame **bytes** and replying is the **next increment**, not
+yet available. That bridge is the `StreamPacket` / `StreamOutbound` API and the
+typed `Server.STREAM.echo.connect()` client. The intended shape, once it lands:
+
+```ts
+@message reply(packet: StreamPacket): StreamOutbound {
+  return StreamOutbound.reply(packet.bytes());   // echo the bytes back
+}
+```
+
+```ts
+const stream = await Server.STREAM.echo.connect();
+stream.send(new TextEncoder().encode('hello'));
+```
+
+Until then, the hooks run on the connection lifecycle and you observe state
+through fields, as `Echo` does. See the comments in
+`examples/streams/server/streams/Echo.ts` for the authoritative note.
+
+---
+
+See also: [Tiers](./tiers.md), [Daemon](./daemon.md), [Routing](./routing.md).

package/docs/tiers.md

@@ -0,0 +1,127 @@
+# Deployment tiers
+
+A Toil app's server runs across several deployment **tiers** from one source
+tree. Each tier has a different lifetime and placement on the edge, and compiles
+into its own WebAssembly artifact. You write one project; `toiljs build` decides
+which entries belong to which tier and emits one `.wasm` per tier. You opt into a
+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). |
+
+The three tiers differ in how long a box lives and how many of it exist:
+
+- **L1 request** is stateless. A `@rest` handler's fields reset each request,
+  because a fresh box serves each one, anywhere on the edge.
+- **L2/L3 stream** is resident per connection. A `@stream` box is created when a
+  connection opens, lives for its lifetime, and is torn down on close, so its
+  fields persist across every event.
+- **L4 daemon** is a single elected leader per domain - the global coordination
+  tier - running recurring background work on a cadence.
+
+## How the build works
+
+`toiljs build` runs one toilscript pass per tier, handing each pass only the
+entries that belong to it. Tier membership is decided by the surface decorator or
+by the entry naming convention:
+
+- a runtime-export entry that is **not** `*.stream.ts` or `*.daemon.ts` is the
+  **request** entry (`main.ts`), which compiles `@rest` / `@service` / `@remote`;
+- `*.stream.ts` is the **stream** entry, which compiles `@stream`;
+- `*.daemon.ts` is the **daemon** entry, which compiles `@daemon` / `@scheduled`.
+
+Plain `@data` and helper modules carry no tier of their own, so they are shared
+into every artifact. Routing each entry to exactly one tier is what keeps
+`release.wasm` free of `stream_dispatch` and keeps the daemon artifact free of
+the request `handle`.
+
+Each entry is a thin file that imports its tier's modules and re-exports the
+right runtime hooks. The stream and request entries re-export the request runtime
+exports; the daemon entry does not, because a cold artifact exposes
+`daemon_start` / `scheduled_tick`, not `handle`:
+
+```ts
+// server/main.stream.ts - the L2/L3 stream entry
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import './streams/Echo';
+
+export * from 'toiljs/server/runtime/exports';
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}
+```
+
+```ts
+// server/main.daemon.ts - the L4 daemon entry
+import { revertOnError } from 'toiljs/server/runtime/abort/abort';
+import './daemon/Jobs';
+
+// NOTE: no `export *` from the request runtime - a cold artifact exposes
+// daemon_start/scheduled_tick, not the request `handle`.
+export function abort(message: string, fileName: string, line: u32, column: u32): void {
+    revertOnError(message, fileName, line, column);
+}
+```
+
+A single build produces the artifacts side by side:
+
+```sh
+$ ls build/server/*.wasm
+build/server/release.wasm          # L1 request    (exports: handle)
+build/server/release-stream.wasm   # L2/L3 stream   (exports: stream_dispatch)
+build/server/release-cold.wasm     # L4 daemon      (exports: daemon_start, scheduled_tick)
+```
+
+## Single-artifact default
+
+A project with no `@stream` and no `@daemon` surface keeps the legacy
+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
+`release-cold.wasm`. Existing request-only apps build exactly as before.
+
+## When to use each tier
+
+- **L1 request** for request/response and RPC: `@rest` controllers, `@service` /
+  `@remote` callable surface. The default tier; most code lives here.
+- **L2/L3 stream** for stateful, long-lived connections where per-connection
+  state must survive across events - the resident box is pinned to one worker for
+  the connection's lifetime.
+- **L4 daemon** for scheduled and coordination work: rollups, cleanup, polling an
+  upstream, anything that should run exactly once per domain on a cadence rather
+  than per request.
+
+```ts
+// server/streams/Echo.ts - L2/L3: the box is resident, so `count` persists.
+@stream('echo')
+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 */ }
+}
+```
+
+```ts
+// server/daemon/Jobs.ts - L4: one leader per domain runs this hourly.
+@daemon
+class Jobs {
+    @scheduled('1h')
+    hourly(): void {
+        // Recurring background work: rollups, cleanup, polling an upstream, ...
+    }
+}
+```
+
+## See also
+
+- [Streams](./streams.md) - the `@stream` surface and the L2/L3 tier.
+- [Daemon](./daemon.md) - the `@daemon` surface and the L4 tier.
+- [Routing](./routing.md) - `@rest` controllers on the L1 request tier.
+- [RPC](./rpc.md) - `@service` / `@remote` and the generated client.

package/examples/basic/server/services/Stats.ts

@@ -1,11 +1,10 @@
 import { store } from '../core/store';
 
 /** Typed RPC service (transport still a TODO): reached as `Server.stats.playerCount()` on the client. */
-@service
+/*@service
 class Stats {
-    /** Number of seeded players (the RPC transport is a TODO, so this throws on the client for now). */
     @remote
     public playerCount(): i32 {
         return store.size;
     }
-}
+}*/

package/examples/basic/server/services/remotes.ts

@@ -1,7 +1,7 @@
 /** Free `@remote` functions: callable as `Server.<name>()` on the client. */
 
 /** `Server.ping(n)` on the client. */
-@remote
+/*@remote
 function ping(n: i32): i32 {
     return n + 1;
-}
+}*/

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "toiljs",
     "type": "module",
-    "version": "0.0.62",
+    "version": "0.0.64",
     "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.39",
+        "toilscript": "^0.1.41",
         "typescript-eslint": "^8.62.0",
         "vite": "^8.1.0",
         "vite-imagetools": "^10.0.1",

package/scripts/gen-toil-docs.mjs

@@ -42,6 +42,9 @@ const ORDER = [
     'server.md',
     'ssr.md',
     'rpc.md',
+    'tiers.md',
+    'streams.md',
+    'daemon.md',
     'data.md',
     'caching.md',
     'ratelimit.md',

package/src/client/index.ts

@@ -40,6 +40,7 @@ export {
     useSearchParams,
     useRouter,
     useNavigationPending,
+    __setSsrLocation,
 } from './routing/hooks.js';
 export type { RouterInstance } from './routing/hooks.js';
 export {

package/src/client/routing/hooks.ts

@@ -101,12 +101,25 @@ function useLocationSubscription(): void {
     );
 }
 
+/** Build-only override for the SSR pathname, set by the template extractor per route via
+ * {@link __setSsrLocation}. Lets location-dependent markup (a `NavLink`'s active class /
+ * `aria-current`) render as the route's own URL so it matches what the client computes on
+ * hydration, instead of the `/` default. Ignored in the browser (the live URL wins). */
+let ssrLocationOverride: string | null = null;
+
+/** Build-only: set the pathname the extractor is currently rendering (or `null` to clear).
+ * No effect in the browser. Exported through `toiljs/client` for the compiler. */
+export function __setSsrLocation(path: string | null): void {
+    ssrLocationOverride = path;
+}
+
 /** Subscribes to and returns the current `location.pathname`. SSR-safe: during a
- *  server render (build-time template extraction / edge SSR) there is no `window`,
- *  so it reports `/`; the client recomputes on hydration. */
+ *  server render there is no `window`, so it reports the extractor's override (the route
+ *  being rendered) or `/`; the client recomputes on hydration. */
 export function useLocation(): string {
     useLocationSubscription();
-    return typeof window === 'undefined' ? '/' : window.location.pathname;
+    if (typeof window === 'undefined') return ssrLocationOverride ?? '/';
+    return window.location.pathname;
 }
 
 /** Alias of {@link useLocation}: the current `location.pathname`. */

package/src/client/ssr/markers.tsx

@@ -145,7 +145,10 @@ export function Repeat<T>(props: RepeatProps<T>): ReactNode {
     return createElement(
         Fragment,
         null,
-        props.each.map((item, i) => props.children(item, i)),
+        // Each row is wrapped in a keyed Fragment so React has a stable list key (the
+        // row markup itself need not carry one). Index keys are fine here: an SSR'd
+        // region hydrates 1:1 against the host's pre-stamped rows and does not reorder.
+        props.each.map((item, i) => createElement(Fragment, { key: i }, props.children(item, i))),
     );
 }
 

package/src/compiler/index.ts

@@ -137,30 +137,42 @@ export async function buildServer(root: string): Promise<void> {
     // (optimization, features, runtime) still come from the toilconfig's `release` target.
     const files = serverEntryFiles(root);
 
-    // A project that declares a `@daemon` (cold surface) compiles the ONE source tree into TWO
-    // artifacts via two toilscript passes (one per --targetMode); a project with only the legacy
-    // request surface keeps the single-artifact path (byte-identical to before). The cold pass
-    // runs FIRST (cheap, no client surface); the hot pass runs LAST because it (re)writes
-    // shared/server.ts via --rpcModule, which the downstream client build imports.
+    // 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:
+    //   - 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`
+    // toilscript's gating matrix HARD-ERRORS a class compiled under the wrong --targetMode, so each
+    // pass is handed only the files eligible for its tier (`@data`/`@database`/plain helpers are
+    // SHARED into every pass). The request pass runs LAST because it (re)writes shared/server.ts via
+    // --rpcModule, which the downstream client build imports.
     const split = splitSurfaceFiles(root, files);
-    if (split.hasDaemon) {
+    if (split.hasDaemon || split.hasStream) {
         const artifacts = serverArtifacts(root);
-        // toilscript's gating matrix HARD-ERRORS a `@daemon`/`@scheduled` class compiled under
-        // `--targetMode hot` (and a `@rest`/`@stream`/`@service`/`@remote` class under cold). So
-        // each pass is handed only the files eligible for that mode: the cold pass drops hot-only
-        // files, the hot pass drops daemon-only files. `@data`/`@database`/plain files are shared.
-        await runToilscriptPass(root, binJs, split.cold, {
-            mode: 'cold',
-            outFile: artifacts.cold,
-            withRpc: false,
-        });
-        // The hot pass writes the legacy `outFile` (= hotFile alias, AN-1) so the request path
-        // and the dev server's `serverWasmFile` are unchanged; the request box loads it as today.
-        // A daemon-only project (no request/stream surface) has no hot files; skip the hot pass so
-        // toilscript is not handed an empty entry set. The request path then stays idle (no
-        // `handle` export), which is correct for a pure background worker.
-        if (split.hot.length > 0)
-            await runToilscriptPass(root, binJs, split.hot, {
+        // DAEMON (cold) pass: --targetMode cold, no client RPC surface.
+        if (split.hasDaemon)
+            await runToilscriptPass(root, binJs, split.cold, {
+                mode: 'cold',
+                outFile: artifacts.cold,
+                withRpc: false,
+            });
+        // STREAM pass: --targetMode hot into its OWN `release-stream.wasm`, no client RPC surface
+        // (a resident stream box exposes `stream_dispatch`, not the request client surface). Driven
+        // by `server/main.stream.ts` + the `@stream` classes; the request box never loads it.
+        if (split.hasStream && split.stream.length > 0)
+            await runToilscriptPass(root, binJs, split.stream, {
+                mode: 'hot',
+                outFile: artifacts.stream,
+                withRpc: false,
+            });
+        // REQUEST pass: the L1 artifact (= the legacy `outFile`, AN-1), 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.
+        if (split.request.length > 0)
+            await runToilscriptPass(root, binJs, split.request, {
                 mode: 'hot',
                 outFile: serverWasmFile(root),
                 withRpc: true,
@@ -168,7 +180,7 @@ export async function buildServer(root: string): Promise<void> {
         return;
     }
 
-    // Legacy single-artifact path (no daemon surface): exactly today's invocation.
+    // Legacy single-artifact path (no daemon/stream surface): exactly today's invocation.
     await runToilscriptPass(root, binJs, files, { mode: null, outFile: null, withRpc: true });
 }
 
@@ -191,54 +203,85 @@ function resolveToilscriptBin(root: string): string {
     }
 }
 
-/** Files classified per target mode for the two-pass build. */
+/** Files classified per deployment TIER for the multi-artifact build. */
 interface SurfaceSplit {
-    /** Whether any file declares a `@daemon` (so a cold pass is needed at all). */
+    /** Whether any file declares a `@daemon` (so a cold/daemon pass is needed at all). */
     readonly hasDaemon: boolean;
-    /** Files eligible for the COLD pass (everything except hot-only request files). */
+    /** Whether any file declares a `@stream` (or is a `*.stream.ts` entry), so a stream pass is needed. */
+    readonly hasStream: boolean;
+    /** Files for the DAEMON (cold) pass: `@daemon`/`@scheduled` surfaces + shared helpers. */
     readonly cold: string[];
-    /** Files eligible for the HOT pass (everything except daemon-only cold files). */
-    readonly hot: string[];
+    /** Files for the STREAM pass: `@stream` surfaces + the `*.stream.ts` entry + shared helpers. */
+    readonly stream: string[];
+    /** Files for the REQUEST pass: `@rest`/`@service`/`@remote` surfaces + the request entry + shared helpers. */
+    readonly request: string[];
 }
 
-/** A `@daemon`/`@scheduled` decorator at line start (a cold-only surface). */
+/** A `@daemon`/`@scheduled` decorator at line start (the L4 cold/daemon surface). */
 const COLD_DECORATOR = /^[ \t]*@(daemon|scheduled)\b/m;
-/** A request/stream-surface decorator at line start (a hot-only surface). */
-const HOT_DECORATOR = /^[ \t]*@(rest|route|stream|service|remote)\b/m;
+/** A `@stream` decorator at line start (the L2/L3 stream surface). */
+const STREAM_DECORATOR = /^[ \t]*@stream\b/m;
+/** A request-surface decorator at line start (`@rest`/`@route`/`@service`/`@remote`, the L1 tier). */
+const REQUEST_DECORATOR = /^[ \t]*@(rest|route|service|remote)\b/m;
+/** A server ENTRY re-exports the runtime WASM entry points; this marks `main.ts` / `main.stream.ts`
+ *  (vs a plain `@data`/helper), so each entry is routed to exactly ONE tier and two entries never
+ *  collide on a duplicate `export *` in the same pass. */
+const RUNTIME_ENTRY = /from\s+['"]toiljs\/server\/runtime\/exports['"]/;
+
+/** True for a STREAM-tier entry by the `*.stream.ts` naming convention (e.g. `main.stream.ts`). */
+function isStreamEntryFile(rel: string): boolean {
+    return rel.endsWith('.stream.ts');
+}
+
+/** True for a COLD/daemon-tier entry by the `*.daemon.ts` naming convention (e.g. `main.daemon.ts`). */
+function isDaemonEntryFile(rel: string): boolean {
+    return rel.endsWith('.daemon.ts');
+}
 
 /**
- * Classify each server source file by the surface decorators it declares, so each toilscript pass
- * is handed only the files valid for its `--targetMode` (toilscript HARD-ERRORS a cold class in
- * the hot artifact and vice versa). A file with a cold-only surface (`@daemon`/`@scheduled` and no
- * hot decorator) is dropped from the hot pass; a file with a hot-only surface is dropped from the
- * cold pass. Shared files (`@data`/`@database`/plain helpers, or a file mixing both surfaces) stay
- * in both passes, matching toilscript's class-level gating which admits `@data`/`@database`
- * everywhere.
+ * Classify each server source file by its deployment TIER, so each toilscript pass is handed only
+ * the files valid for its `--targetMode` (toilscript HARD-ERRORS a class compiled under the wrong
+ * mode). Three tiers:
+ *   - COLD/daemon: a file declaring `@daemon`/`@scheduled` -> `release-cold.wasm`.
+ *   - STREAM (L2/L3): a file declaring `@stream`, OR a `*.stream.ts` entry (`main.stream.ts`) ->
+ *     `release-stream.wasm`.
+ *   - REQUEST (L1): a file declaring `@rest`/`@service`/`@remote`, OR a non-`*.stream.ts` runtime
+ *     ENTRY (`main.ts`) -> `release.wasm`.
+ * A file with NONE of these (a plain `@data`/`@database`/helper) is SHARED into every pass, matching
+ * toilscript's class-level gating. Routing each entry to exactly one tier keeps `release.wasm` free
+ * of `stream_dispatch` and stops two entries re-exporting the runtime in the same pass.
  */
 export function splitSurfaceFiles(root: string, files: string[]): SurfaceSplit {
     let hasDaemon = false;
+    let hasStream = false;
     const cold: string[] = [];
-    const hot: string[] = [];
+    const stream: string[] = [];
+    const request: string[] = [];
     for (const rel of files) {
         let src = '';
         try {
             src = fs.readFileSync(path.join(root, rel), 'utf8');
         } catch {
-            // unreadable: keep it in both passes (let toilscript surface the error).
+            // unreadable: keep it in EVERY pass (let toilscript surface the error).
             cold.push(rel);
-            hot.push(rel);
+            stream.push(rel);
+            request.push(rel);
             continue;
         }
-        const isCold = COLD_DECORATOR.test(src);
-        const isHot = HOT_DECORATOR.test(src);
-        if (isCold) hasDaemon ||= /^[ \t]*@daemon\b/m.test(src);
-        // Drop a file from the hot pass only when it is cold-only (cold surface, no hot surface);
-        // a mixed file stays in both (toilscript gates per class, not per file).
-        if (!(isCold && !isHot)) hot.push(rel);
-        // Drop a file from the cold pass only when it is hot-only.
-        if (!(isHot && !isCold)) cold.push(rel);
+        const isCold = COLD_DECORATOR.test(src) || isDaemonEntryFile(rel);
+        const isStream = STREAM_DECORATOR.test(src) || isStreamEntryFile(rel);
+        const isRequest =
+            REQUEST_DECORATOR.test(src) ||
+            (RUNTIME_ENTRY.test(src) && !isStreamEntryFile(rel) && !isDaemonEntryFile(rel));
+        if (isCold) hasDaemon ||= /^[ \t]*@daemon\b/m.test(src) || isDaemonEntryFile(rel);
+        if (isStream) hasStream = true;
+        // A file with no tier-specific surface is a SHARED helper, compiled into every pass.
+        const shared = !isCold && !isStream && !isRequest;
+        if (isCold || shared) cold.push(rel);
+        if (isStream || shared) stream.push(rel);
+        if (isRequest || shared) request.push(rel);
     }
-    return { hasDaemon, cold, hot };
+    return { hasDaemon, hasStream, cold, stream, request };
 }
 
 interface PassOptions {
@@ -264,6 +307,11 @@ function runToilscriptPass(
     if (opts.mode !== null) args.push('--targetMode', opts.mode);
     if (opts.outFile !== null) args.push('--outFile', opts.outFile);
     if (opts.withRpc) args.push('--rpcModule', 'shared/server.ts');
+    // Each pass is handed its OWN entry subset (the per-tier `files`); suppress the toilconfig
+    // `entries` so toilscript does not ALSO append every project entry to every pass (which would
+    // pull, e.g., a `@stream` class into the cold daemon pass). serverEntryFiles already folds
+    // config.entries into `files`, so no entry is lost by ignoring them here.
+    args.push('--noConfigEntries');
     args.push('--disableWarning', '235');
 
     return new Promise<void>((resolve, reject) => {
@@ -417,32 +465,40 @@ function serverWasmFile(root: string): string {
  *  present in the toilconfig `release` target; otherwise derived from `outFile` by inserting the
  *  mode before the extension (`release.wasm` -> `release-hot.wasm` / `release-cold.wasm`). */
 export interface ServerArtifacts {
-    /** Absolute path to the hot (request/stream) artifact. */
+    /** Absolute path to the hot (request) artifact. */
     readonly hot: string;
     /** Absolute path to the cold (daemon) artifact. */
     readonly cold: string;
+    /** Absolute path to the stream (L2/L3 `@stream`) artifact (`release-stream.wasm`). */
+    readonly stream: string;
 }
 export function serverArtifacts(root: string): ServerArtifacts {
     let out = 'build/server/release.wasm';
     let hot: string | undefined;
     let cold: string | undefined;
+    let stream: string | undefined;
     try {
         const cfg = JSON.parse(fs.readFileSync(path.join(root, 'toilconfig.json'), 'utf8')) as {
-            targets?: Record<string, { outFile?: string; hotFile?: string; coldFile?: string }>;
+            targets?: Record<
+                string,
+                { outFile?: string; hotFile?: string; coldFile?: string; streamFile?: string }
+            >;
         };
         out = cfg.targets?.release?.outFile ?? out;
         hot = cfg.targets?.release?.hotFile;
         cold = cfg.targets?.release?.coldFile;
+        stream = cfg.targets?.release?.streamFile;
     } catch {
         // No readable toilconfig: caller already gated on its existence; keep defaults.
     }
-    const ins = (mode: 'hot' | 'cold'): string => {
+    const ins = (mode: 'hot' | 'cold' | 'stream'): string => {
         const ext = path.extname(out);
         return out.slice(0, ext ? -ext.length : undefined) + '-' + mode + (ext || '.wasm');
     };
     return {
         hot: path.resolve(root, hot ?? ins('hot')),
         cold: path.resolve(root, cold ?? ins('cold')),
+        stream: path.resolve(root, stream ?? ins('stream')),
     };
 }