toiljs 0.0.60 → 0.0.62

package/src/devserver/server.ts

@@ -27,12 +27,21 @@ import pc from 'picocolors';
 
 import type { EmailBackendConfig } from 'toiljs/shared';
 
+import { DaemonHost, daemonEmulationEnabled } from './daemon/index.js';
+import type { ResolvedDaemonConfig } from './daemon/host.js';
 import { configureDbPersistence } from './db/index.js';
 import { initEmailService } from './email/index.js';
 import { applyCacheRule, lookupCache } from './http/cache.js';
 import { type EnvelopeRequest, METHOD_CODES } from './http/envelope.js';
 import { proxyToVite, type ViteTarget, wireWebsocketProxy } from './http/proxy.js';
 import { WasmServerModule } from './runtime/module.js';
+import {
+    assembleSsr,
+    buildSsrRoutes,
+    type DevSsrTemplate,
+    pathnameOf,
+    type SsrResult,
+} from './ssr.js';
 
 const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
 
@@ -73,6 +82,16 @@ export interface DevServerOptions {
     readonly host?: string;
     /** Absolute path to the ToilScript server wasm (toilconfig `targets.release.outFile`). */
     readonly wasmFile: string;
+    /**
+     * Absolute path to the cold daemon artifact (`release-cold.wasm`). When present and the cold
+     * artifact declares a daemon surface, the dev daemon emulator drives its `@scheduled` tasks
+     * (per `nodeMode`). Omit for a project with no `@daemon` (the file is never built).
+     */
+    readonly coldWasmFile?: string;
+    /** Which layer the dev process emulates (gates the daemon emulator). Default `all`. */
+    readonly nodeMode?: string;
+    /** Daemon (L4) config mirror (drives the dev scheduler's budgets/caps). */
+    readonly daemon?: ResolvedDaemonConfig;
     /** The internal Vite dev server to proxy unclaimed traffic to. */
     readonly vite: ViteTarget;
     /** Max request body bytes. Default 8 MB. */
@@ -83,6 +102,13 @@ export interface DevServerOptions {
      * otherwise it stays a log-only mock. See `./email`.
      */
     readonly email?: EmailBackendConfig;
+    /**
+     * Edge-SSR templates (one per `ssr = true` route), extracted at dev startup
+     * against the live dev shell. When a GET/HEAD matches a route the dev server
+     * runs the guest `render`, splices the values, and serves the SSR HTML (same
+     * path as the prod edge). Omit / empty for a project with no SSR route.
+     */
+    readonly ssrTemplates?: readonly DevSsrTemplate[];
 }
 
 /** A running dev server. */
@@ -167,6 +193,23 @@ function sendWasmResponse(
     response.send(Buffer.from(result.body.buffer, result.body.byteOffset, result.body.length));
 }
 
+/** Sends a spliced edge-SSR response (the full server-rendered HTML document). */
+function sendSsr(response: Response, out: SsrResult, headOnly: boolean): void {
+    response.status(out.status);
+    let hasContentType = false;
+    for (const [name, value] of out.headers) {
+        if (name.toLowerCase() === 'content-type') hasContentType = true;
+        response.header(name, value);
+    }
+    if (!hasContentType) response.header('content-type', 'text/html; charset=utf-8');
+    response.header('server', 'toil-dev');
+    if (headOnly) {
+        response.send('');
+        return;
+    }
+    response.send(Buffer.from(out.html.buffer, out.html.byteOffset, out.html.length));
+}
+
 /**
  * Starts the front server. The caller owns the Vite dev server (start it on a
  * loopback port first) and the toilscript rebuild watcher; this watches only
@@ -188,6 +231,16 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
 
     const module = new WasmServerModule(options.wasmFile);
 
+    // Edge-SSR routes (extracted against the live dev shell at startup). When a
+    // GET/HEAD matches one, the dev server runs the guest `render`, splices the
+    // values into the template, and serves the SSR HTML (prod-edge parity).
+    const ssrRoutes = buildSsrRoutes(options.ssrTemplates ?? []);
+    if (ssrRoutes.length > 0) {
+        process.stdout.write(
+            pc.dim(`  edge SSR: ${String(ssrRoutes.length)} route(s) served server-side`) + '\n',
+        );
+    }
+
     // Persist dev DB data under the project's .toil/ so records, events, and their
     // schema_versions survive restarts (delete .toil/devdata.json to reset). Only
     // the running dev server persists; tests that construct WasmServerModule
@@ -231,6 +284,27 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
 
     wireWebsocketProxy(app, options.vite);
 
+    // Dev DAEMON (L4) emulation: load `release-cold.wasm` once, run `daemon_start()`, and drive
+    // its `@scheduled` tasks. Only when `nodeMode` is daemon/all and a cold artifact path is given;
+    // the host stays idle until the cold artifact appears (a `@daemon` build). It has no request to
+    // hang a refresh off, so it polls its own mtime-watch on a low-frequency timer (section 9.3).
+    const nodeMode = options.nodeMode ?? 'all';
+    let daemonHost: DaemonHost | null = null;
+    let daemonTimer: NodeJS.Timeout | null = null;
+    if (options.coldWasmFile !== undefined && daemonEmulationEnabled(nodeMode) && options.daemon) {
+        daemonHost = new DaemonHost(options.coldWasmFile, options.daemon, nodeMode);
+        const pollDaemon = (): void => {
+            try {
+                daemonHost?.refresh();
+            } catch (e) {
+                process.stdout.write(pc.red(`  ✗ daemon reload failed: ${String(e)}`) + '\n');
+            }
+        };
+        pollDaemon();
+        daemonTimer = setInterval(pollDaemon, 500);
+        daemonTimer.unref?.();
+    }
+
     app.any('/*', async (request: Request, response: Response) => {
         response.removeHeader('uWebSockets');
 
@@ -275,6 +349,31 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
                 response.status(500).send('internal error\n');
                 return;
             }
+
+            // Edge SSR: handle() did not claim this path; if it matches an
+            // `ssr = true` route, run the guest `render`, splice the values, and
+            // serve the server-rendered HTML. A fail-safe envelope (no renderer
+            // matched / malformed) returns null, so we fall through to Vite (the
+            // route then client-renders, same as before).
+            if (
+                (request.method === 'GET' || request.method === 'HEAD') &&
+                ssrRoutes.length > 0
+            ) {
+                const route = ssrRoutes.find((r) => r.test(pathnameOf(request.url)));
+                if (route) {
+                    try {
+                        const out = assembleSsr(route, module.dispatchRender(envelopeReq));
+                        if (out !== null) {
+                            sendSsr(response, out, request.method === 'HEAD');
+                            return;
+                        }
+                    } catch (e) {
+                        process.stdout.write(
+                            pc.red(`  ✗ SSR ${request.path}: ${String(e)}`) + '\n',
+                        );
+                    }
+                }
+            }
         }
 
         await proxyToVite(request, response, options.vite);
@@ -286,6 +385,8 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
         port: options.port,
         host,
         close: async (): Promise<void> => {
+            if (daemonTimer !== null) clearInterval(daemonTimer);
+            daemonHost?.close();
             await app.shutdown();
         },
     };

package/src/devserver/ssr.ts

@@ -0,0 +1,166 @@
+/**
+ * Dev-server edge SSR: splice the guest `render` values into a route's
+ * template-with-holes and serve real server-rendered HTML, mirroring the
+ * production edge (`toil-backend/src/host/template/assemble.rs`).
+ *
+ * The templates are extracted once at dev startup against the LIVE (Vite-
+ * transformed) dev shell (see `compiler/template-build.ts extractDevSsrTemplates`)
+ * so the served markup boots the dev client and hydrates in place. At request
+ * time the dev server runs the real `render` export (`WasmServerModule.
+ * dispatchRender`), this module decodes the values envelope and splices each
+ * value at its manifest-fixed offset. The hash-coherence guard the prod edge
+ * enforces is skipped in dev: the guest and the template are built together
+ * here, so there is no deploy skew to catch — only fail-safe envelopes (status
+ * >= 500 or no slots) fall back to client rendering.
+ */
+
+/** One SSR route's spliceable template + its slot insertion points. */
+export interface DevSsrTemplate {
+    pattern: string;
+    name: string;
+    tmpl: Uint8Array;
+    entries: { id: number; offset: number }[];
+}
+
+/** A matchable SSR route. */
+export interface SsrRoute {
+    /** Matches a request pathname (no query) to this route's template. */
+    test: (pathname: string) => boolean;
+    tmpl: Uint8Array;
+    entries: { id: number; offset: number }[];
+}
+
+/** The pathname of a request URL (strip the query string). */
+export function pathnameOf(url: string): string {
+    const q = url.indexOf('?');
+    return q < 0 ? url : url.slice(0, q);
+}
+
+/** Compile a route pattern (`/hello`, `/u/:name`, `/blog/[id]`, `/files/[...path]`,
+ * `/*`) to a pathname matcher. Dynamic segments match one path segment; catch-all
+ * (`[...x]` / `*`) matches the rest. Trailing slashes are ignored. */
+function patternToTest(pattern: string): (pathname: string) => boolean {
+    const norm = (p: string): string => (p.length > 1 && p.endsWith('/') ? p.slice(0, -1) : p);
+    let re = '';
+    // Tokenise into literal runs and dynamic/catch-all holes.
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === ':') {
+            // `:name` — one segment.
+            i++;
+            while (i < pattern.length && /[A-Za-z0-9_]/.test(pattern[i])) i++;
+            re += '[^/]+';
+        } else if (ch === '*') {
+            re += '.*';
+            i++;
+        } else if (ch === '[') {
+            const end = pattern.indexOf(']', i);
+            const inner = end < 0 ? '' : pattern.slice(i + 1, end);
+            re += inner.startsWith('...') ? '.*' : '[^/]+';
+            i = end < 0 ? pattern.length : end + 1;
+        } else {
+            // Literal char, regex-escaped.
+            re += ch.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            i++;
+        }
+    }
+    const compiled = new RegExp(`^${re}$`);
+    return (pathname: string): boolean => compiled.test(norm(pathname));
+}
+
+/** Build matchable SSR routes from the extracted dev templates. */
+export function buildSsrRoutes(templates: readonly DevSsrTemplate[]): SsrRoute[] {
+    return templates.map((t) => ({ test: patternToTest(t.pattern), tmpl: t.tmpl, entries: t.entries }));
+}
+
+/** A decoded guest values envelope. */
+interface DecodedValues {
+    status: number;
+    headers: [string, string][];
+    /** Slot value bytes keyed by numeric slot id. */
+    values: Map<number, Uint8Array>;
+}
+
+/** Decode the guest values envelope (mirrors the prod host `decode_values`). All
+ * fields little-endian, no padding. Returns null on a malformed/short buffer. */
+function decodeValues(buf: Uint8Array): DecodedValues | null {
+    const dv = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    let o = 0;
+    const need = (n: number): boolean => o + n <= buf.byteLength;
+    try {
+        if (!need(2 + 32 + 2)) return null;
+        const status = dv.getUint16(o, true);
+        o += 2;
+        o += 32; // template hash (coherence is built together in dev; not checked)
+        const nHeaders = dv.getUint16(o, true);
+        o += 2;
+        const headers: [string, string][] = [];
+        const dec = new TextDecoder();
+        for (let i = 0; i < nHeaders; i++) {
+            if (!need(4)) return null;
+            const nameLen = dv.getUint16(o, true);
+            const valLen = dv.getUint16(o + 2, true);
+            o += 4;
+            if (!need(nameLen + valLen)) return null;
+            const name = dec.decode(buf.subarray(o, o + nameLen));
+            o += nameLen;
+            const val = dec.decode(buf.subarray(o, o + valLen));
+            o += valLen;
+            headers.push([name, val]);
+        }
+        if (!need(2)) return null;
+        const nSlots = dv.getUint16(o, true);
+        o += 2;
+        const values = new Map<number, Uint8Array>();
+        for (let i = 0; i < nSlots; i++) {
+            if (!need(2 + 1 + 4)) return null;
+            const id = dv.getUint16(o, true);
+            o += 2;
+            o += 1; // kind (the splice is kind-agnostic; the guest pre-escaped/stamped)
+            const len = dv.getUint32(o, true);
+            o += 4;
+            if (!need(len)) return null;
+            values.set(id, buf.subarray(o, o + len));
+            o += len;
+        }
+        return { status, headers, values };
+    } catch {
+        return null;
+    }
+}
+
+/** Splice ascending-offset inserts into the template (mirrors the host `assemble`). */
+function splice(tmpl: Uint8Array, inserts: { offset: number; value: Uint8Array }[]): Uint8Array {
+    const parts: Uint8Array[] = [];
+    let prev = 0;
+    for (const ins of inserts) {
+        if (ins.offset > prev) parts.push(tmpl.subarray(prev, ins.offset));
+        if (ins.value.length > 0) parts.push(ins.value);
+        prev = ins.offset;
+    }
+    if (tmpl.length > prev) parts.push(tmpl.subarray(prev));
+    return Buffer.concat(parts.map((p) => Buffer.from(p.buffer, p.byteOffset, p.byteLength)));
+}
+
+/** A spliced SSR response. */
+export interface SsrResult {
+    status: number;
+    headers: [string, string][];
+    html: Uint8Array;
+}
+
+/**
+ * Decode the guest envelope and splice it into `route`'s template. Returns null
+ * to fall back to client rendering: a fail-safe envelope (status >= 500, e.g. no
+ * renderer matched), no slots, or a decode error.
+ */
+export function assembleSsr(route: SsrRoute, envelope: Uint8Array): SsrResult | null {
+    const decoded = decodeValues(envelope);
+    if (decoded === null) return null;
+    if (decoded.status >= 500 || decoded.values.size === 0) return null;
+    const inserts = route.entries
+        .map((e) => ({ offset: e.offset, value: decoded.values.get(e.id) ?? new Uint8Array(0) }))
+        .sort((a, b) => a.offset - b.offset);
+    return { status: decoded.status, headers: decoded.headers, html: splice(route.tmpl, inserts) };
+}

package/src/devserver/wasm/sections.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared, bounds-checked wasm custom-section walker. Factored out of
+ * `db/catalog.ts` so the three Toil section parsers (`toildb.catalog`,
+ * `toilstream.catalog`, `toildaemon.catalog`, `toil.surface`) share ONE
+ * magic-skipping loop instead of drifting copies.
+ *
+ * Every input is a tenant-built, possibly mid-rebuild wasm, so the walker must
+ * never read past the buffer: a truncated/garbage section table returns `null`
+ * (treated by callers as "no section"). Mirrors the host-side walker
+ * (`toil-backend` custom-section reader) and the toilscript-side test walker.
+ */
+
+/** Read a LEB128 from `buf` at `pos`; throws on overrun so a truncated module
+ *  can never over-read (the caller catches and treats it as "no section"). */
+export function leb(buf: Buffer, pos: number): [number, number] {
+    let result = 0;
+    let shift = 0;
+    let p = pos;
+    for (;;) {
+        if (p >= buf.length) throw new RangeError('leb128 past end of buffer');
+        const b = buf[p++];
+        result |= (b & 0x7f) << shift;
+        if ((b & 0x80) === 0) break;
+        shift += 7;
+        if (shift > 35) throw new RangeError('leb128 too long');
+    }
+    return [result >>> 0, p];
+}
+
+/** The bytes of the named wasm custom section, or `null` if absent. Bounds-checked
+ *  so a truncated/garbage module can never read past the buffer. */
+export function customSection(wasm: Buffer, want: string): Buffer | null {
+    if (
+        wasm.length < 8 ||
+        wasm[0] !== 0x00 ||
+        wasm[1] !== 0x61 ||
+        wasm[2] !== 0x73 ||
+        wasm[3] !== 0x6d
+    )
+        return null;
+    let pos = 8; // skip the 8-byte magic + version header
+    while (pos < wasm.length) {
+        const id = wasm[pos++];
+        let size: number;
+        [size, pos] = leb(wasm, pos);
+        const end = pos + size;
+        if (end > wasm.length || end < pos) return null; // truncated section table
+        if (id === 0) {
+            const [nameLen, namePos] = leb(wasm, pos);
+            if (
+                namePos + nameLen <= end &&
+                wasm.toString('latin1', namePos, namePos + nameLen) === want
+            )
+                return wasm.subarray(namePos + nameLen, end);
+        }
+        pos = end;
+    }
+    return null;
+}

package/src/devserver/wasm/surface.ts

@@ -0,0 +1,88 @@
+/**
+ * Parse a compiled artifact's `toil.surface` custom section. Emitted into EVERY
+ * Toil artifact by the toilscript `buildToilSurface` pass (hot AND cold). The dev
+ * server reads it to decide whether each artifact carries the daemon surface
+ * (start the daemon emulator) or the stream surface (Phase 4, deferred).
+ *
+ * Byte layout (RECONCILIATION Part 5, all little-endian; mirrors the toilscript
+ * `CatWriter` emitter byte-for-byte):
+ *
+ *   u16 format_version = 1
+ *   u8  target_mode            (0 = hot, 1 = cold; there is no target_mode = 2)
+ *   u8  reserved0
+ *   u32 surface_flags          (bit0 rest, bit1 stream, bit2 daemon,
+ *                               bit3 scheduled, bit4 database, bit5 render)
+ *   u16 abi_version
+ *   str build_id               (u32 len + UTF-8)
+ *   u32 fingerprint
+ *   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.
+ */
+
+import { DataReader } from 'toiljs/io';
+
+import { customSection } from './sections.js';
+
+export interface SurfaceFlags {
+    readonly rest: boolean;
+    readonly stream: boolean;
+    readonly daemon: boolean;
+    readonly scheduled: boolean;
+    readonly database: boolean;
+    readonly render: boolean;
+}
+
+export interface Surface {
+    /** 0 = hot, 1 = cold. */
+    readonly targetMode: 'hot' | 'cold';
+    readonly flags: SurfaceFlags;
+    readonly abiVersion: number;
+    readonly buildId: string;
+    readonly fingerprint: number;
+    readonly dataCoherenceHash: number;
+    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' {
+    let sec: Buffer | null;
+    try {
+        sec = customSection(wasm, 'toil.surface');
+    } catch {
+        return 'invalid'; // garbage section table
+    }
+    if (sec === null) return 'absent';
+
+    const r = new DataReader(sec);
+    r.readU16(); // format_version
+    const targetMode = r.readU8() === 1 ? 'cold' : 'hot';
+    r.readU8(); // reserved0
+    const f = r.readU32(); // surface_flags
+    const abiVersion = r.readU16();
+    const buildId = r.readString();
+    const fingerprint = r.readU32();
+    const dataCoherenceHash = r.readU32(); // exactly THREE u32 after build_id
+    const pairCoherenceHash = r.readU32();
+    if (!r.ok) return 'invalid'; // PRESENT but corrupt => fail closed
+    return {
+        targetMode,
+        flags: {
+            rest: !!(f & 1),
+            stream: !!(f & 2),
+            daemon: !!(f & 4),
+            scheduled: !!(f & 8),
+            database: !!(f & 16),
+            render: !!(f & 32),
+        },
+        abiVersion,
+        buildId,
+        fingerprint,
+        dataCoherenceHash,
+        pairCoherenceHash,
+    };
+}

package/test/daemon-build.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Two-pass build pipeline (doc 08 section 1). Asserts:
+ *
+ *   - `serverArtifacts` derives the `-hot`/`-cold` paths from `outFile` when
+ *     `hotFile`/`coldFile` are absent, and honors them when present.
+ *   - `SURFACE_DECORATOR` matches `@stream`/`@daemon`/`@scheduled` at line start
+ *     (not in a comment).
+ *   - `buildServer` on a project that declares a `@daemon` runs TWO toilscript
+ *     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
+ *     path (no cold pass, no cold artifact).
+ *
+ * The build invokes the LOCAL toilscript (branch feat/streams-phase0-compiler),
+ * which supports `--targetMode`; the test links it into the fixture project's
+ * `node_modules` the same way the dev build resolves it (`require.resolve`).
+ */
+
+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';
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import {
+    buildServer,
+    serverArtifacts,
+    splitSurfaceFiles,
+    SURFACE_DECORATOR,
+} from '../src/compiler/index.js';
+import { parseDaemonCatalog } from '../src/devserver/daemon/catalog.js';
+import { parseSurface } from '../src/devserver/wasm/surface.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const LOCAL_TOILSCRIPT = join(here, '..', '..', 'toilscript');
+
+let tmp: string;
+
+beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'daemon-build-'));
+});
+afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+});
+
+/** Scaffold a minimal project at `tmp` with `server/main.ts` = `serverSrc`, the
+ *  given toilconfig, and `node_modules/toilscript` symlinked to the local build. */
+function scaffold(serverSrc: string, toilconfig: object): void {
+    writeFileSync(join(tmp, 'package.json'), JSON.stringify({ name: 'fixture', type: 'module' }));
+    writeFileSync(join(tmp, 'toilconfig.json'), JSON.stringify(toilconfig, null, 2));
+    mkdirSync(join(tmp, 'server'), { recursive: true });
+    writeFileSync(join(tmp, 'server', 'main.ts'), serverSrc);
+    mkdirSync(join(tmp, 'node_modules'), { recursive: true });
+    symlinkSync(LOCAL_TOILSCRIPT, join(tmp, 'node_modules', 'toilscript'), 'dir');
+}
+
+const BASE_TOILCONFIG = {
+    entries: ['server/main.ts'],
+    targets: { release: { outFile: 'build/server/release.wasm' } },
+    options: { runtime: 'stub', optimizeLevel: 0, shrinkLevel: 0 },
+};
+
+// A @daemon that declares its host imports directly (no toiljs globals lib needed).
+const DAEMON_SRC = `@daemon
+class Jobs {
+  @scheduled("2s") fast(): void {}
+  @scheduled("0 0 * * *") nightly(): void {}
+}
+export function probe(): i32 { return 1; }
+`;
+
+const LEGACY_SRC = `export function handle(ofs: i32, len: i32): i64 { return 0; }
+export function probe(): i32 { return 1; }
+`;
+
+describe('serverArtifacts path derivation', () => {
+    it('derives -hot/-cold from outFile when hotFile/coldFile are absent', () => {
+        writeFileSync(
+            join(tmp, 'toilconfig.json'),
+            JSON.stringify({ targets: { release: { outFile: 'build/server/release.wasm' } } }),
+        );
+        const a = serverArtifacts(tmp);
+        expect(a.hot).toBe(join(tmp, 'build/server/release-hot.wasm'));
+        expect(a.cold).toBe(join(tmp, 'build/server/release-cold.wasm'));
+    });
+
+    it('honors explicit hotFile/coldFile when present', () => {
+        writeFileSync(
+            join(tmp, 'toilconfig.json'),
+            JSON.stringify({
+                targets: {
+                    release: {
+                        outFile: 'build/server/release.wasm',
+                        hotFile: 'out/hot.wasm',
+                        coldFile: 'out/cold.wasm',
+                    },
+                },
+            }),
+        );
+        const a = serverArtifacts(tmp);
+        expect(a.hot).toBe(join(tmp, 'out/hot.wasm'));
+        expect(a.cold).toBe(join(tmp, 'out/cold.wasm'));
+    });
+});
+
+describe('SURFACE_DECORATOR', () => {
+    it('matches the streams/daemon decorators at line start', () => {
+        for (const deco of ['@stream', '@daemon', '@scheduled', '@rest', '@data']) {
+            expect(SURFACE_DECORATOR.test(`${deco} class X {}`)).toBe(true);
+            expect(SURFACE_DECORATOR.test(`  ${deco}\nclass X {}`)).toBe(true);
+        }
+    });
+
+    it('does NOT match a decorator mentioned only in a comment', () => {
+        expect(SURFACE_DECORATOR.test('// the @daemon decorator marks a cold class')).toBe(false);
+        expect(SURFACE_DECORATOR.test('const s = "uses @scheduled internally";')).toBe(false);
+    });
+});
+
+describe('splitSurfaceFiles per-pass classification', () => {
+    /** Lay down `name -> contents` files under `tmp` and return their relative paths. */
+    function lay(files: Record<string, string>): string[] {
+        mkdirSync(join(tmp, 'server'), { recursive: true });
+        const rels: string[] = [];
+        for (const [name, src] of Object.entries(files)) {
+            writeFileSync(join(tmp, name), src);
+            rels.push(name);
+        }
+        return rels;
+    }
+
+    it('drops daemon-only files from the hot pass and hot-only files from the cold pass', () => {
+        const rels = lay({
+            'server/jobs.ts': '@daemon\nclass J { @scheduled("1s") t(): void {} }\n',
+            'server/api.ts': '@rest\nclass A {}\n',
+            'server/model.ts': '@data\nclass M {}\n',
+            'server/util.ts': 'export function helper(): i32 { return 1; }\n',
+        });
+        const split = splitSurfaceFiles(tmp, rels);
+        expect(split.hasDaemon).toBe(true);
+        // hot pass: everything except the daemon-only jobs.ts.
+        expect(split.hot.sort()).toEqual(
+            ['server/api.ts', 'server/model.ts', 'server/util.ts'].sort(),
+        );
+        // cold pass: everything except the hot-only api.ts.
+        expect(split.cold.sort()).toEqual(
+            ['server/jobs.ts', 'server/model.ts', 'server/util.ts'].sort(),
+        );
+    });
+
+    it('keeps a file that mixes both surfaces in both passes', () => {
+        const rels = lay({ 'server/both.ts': '@daemon\nclass J {}\n@rest\nclass A {}\n' });
+        const split = splitSurfaceFiles(tmp, rels);
+        expect(split.hot).toContain('server/both.ts');
+        expect(split.cold).toContain('server/both.ts');
+    });
+});
+
+// Needs the local toilscript dev build (with --targetMode) linked as a sibling
+// repo; skip where it is absent (e.g. CI, which has only the published dep).
+describe.skipIf(!existsSync(LOCAL_TOILSCRIPT))('buildServer two-pass (daemon project)', () => {
+    it('runs the cold pass and produces the cold artifact with a daemon catalog', async () => {
+        scaffold(DAEMON_SRC, BASE_TOILCONFIG);
+        await buildServer(tmp);
+
+        const cold = join(tmp, 'build/server/release-cold.wasm');
+        expect(existsSync(cold), 'cold artifact missing').toBe(true);
+
+        // 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);
+
+        const catalog = parseDaemonCatalog(coldBytes);
+        expect(catalog).not.toBeNull();
+        expect(catalog!.hasDaemon).toBe(true);
+        expect(catalog!.tasks.map((t) => t.name)).toEqual(['fast', 'nightly']);
+        expect(catalog!.tasks[0].schedule.kind).toBe('interval');
+        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.
+        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 () => {
+        scaffold(LEGACY_SRC, BASE_TOILCONFIG);
+        await buildServer(tmp);
+
+        expect(existsSync(join(tmp, 'build/server/release.wasm'))).toBe(true);
+        // No @daemon -> no cold pass -> no cold artifact.
+        expect(existsSync(join(tmp, 'build/server/release-cold.wasm'))).toBe(false);
+    }, 60_000);
+});