toiljs 0.0.115 → 0.0.117

package/src/devserver/runtime/module.ts

@@ -1,442 +0,0 @@
-/**
- * Loads the ToilScript-compiled server wasm and dispatches request envelopes
- * into it, the dev-mode equivalent of the edge's fresh dispatcher
- * (`toil-backend/src/wasm/dispatcher/fresh.rs`): one fresh instance per
- * request, so guest state can never leak between requests and a trapped
- * instance is simply dropped. Instantiation of a compiled module is
- * microseconds, irrelevant next to dev-mode I/O.
- *
- * The compiled module is cached and transparently recompiled when the wasm
- * file's mtime changes (the `toiljs dev` watcher rebuilds it via toilscript on
- * server-source edits), which is the server-side hot reload.
- */
-
-import fs from 'node:fs';
-
-import {
-    commitDeriveCheckpoints,
-    DbFunctionKind,
-    type DeriveEntry,
-    derivesForWrites,
-    parseDerives,
-    persistDb,
-    setDbCatalog,
-} from '../db/index.js';
-import {
-    parseRouteKinds,
-    parseRpcKinds,
-    routeKindForRequest,
-    rpcKindForId,
-    type RouteKindEntry,
-    type RpcKindEntry,
-} from '../db/routeKinds.js';
-import {
-    decodeResponseEnvelope,
-    encodeRequestEnvelope,
-    type EnvelopeRequest,
-    unpackHandleResult,
-} from '../http/envelope.js';
-import { buildHostImports, freshDispatchState, type MemoryRef } from './host.js';
-
-export { WasmAbortError } from './host.js';
-
-/**
- * Marker header the server runtime puts on its fallback 404 (no `@rest` route
- * matched and no custom handler produced a response). The dev server strips it
- * and falls through to Vite; a deliberate `Response.notFound()` does not carry
- * it and is sent to the client as-is. Mirrors `TOIL_UNHANDLED_HEADER` in
- * `server/runtime/response.ts`.
- */
-export const UNHANDLED_HEADER = 'x-toil-unhandled';
-
-const WASM_PAGE = 65536;
-
-function dbKindForHttpMethod(method: string): DbFunctionKind {
-    switch (method.toUpperCase()) {
-        case 'GET':
-        case 'HEAD':
-        case 'OPTIONS':
-            return DbFunctionKind.Query;
-        case 'POST':
-        case 'PUT':
-        case 'PATCH':
-        case 'DELETE':
-        default:
-            return DbFunctionKind.Action;
-    }
-}
-
-export function dbFunctionKindForRequest(
-    routes: readonly RouteKindEntry[],
-    method: string,
-    path: string,
-): DbFunctionKind {
-    const routeKind = routeKindForRequest(routes, method, path);
-    return routeKind === DbFunctionKind.Query ? DbFunctionKind.Query : dbKindForHttpMethod(method);
-}
-
-/** The shaped outcome of one guest dispatch. */
-export interface WasmDispatchResult {
-    readonly status: number;
-    readonly headers: readonly (readonly [string, string])[];
-    readonly body: Uint8Array;
-    /** Path from a guest `respond_file` call; when set it replaces `body`. */
-    readonly sendfile: string | null;
-    /** True when the guest reported "no route matched" (the {@link UNHANDLED_HEADER} marker). */
-    readonly unhandled: boolean;
-}
-
-interface HandleExports {
-    readonly memory: WebAssembly.Memory;
-    readonly handle: (reqOfs: number, reqLen: number) => bigint;
-}
-
-/** A `@database` with `@derive` methods exports `derive_run` (optional: absent
- *  when the program declares no derive). See toilscript `injectDeriveHandler`. */
-interface DeriveExports {
-    readonly memory: WebAssembly.Memory;
-    readonly derive_run?: (deriveId: number) => bigint;
-}
-
-/** Host functions the dev server provides under `env` (see `host.ts`). */
-const PROVIDED_IMPORTS = new Set([
-    'abort',
-    'set_status',
-    'set_header',
-    'respond_file',
-    'thread_spawn',
-    'Date.now',
-    'client_ip',
-    'ratelimit_check',
-    'email_send',
-    'email_send_detached',
-    'env_get',
-    'env_get_secure',
-    // Per-domain analytics (see ./analytics/index.ts).
-    'analytics_read',
-    'analytics_series',
-    'analytics_list_sites',
-    // Web Crypto host functions (see ./crypto.ts).
-    'crypto.fill_random',
-    'crypto.random_uuid',
-    'crypto.take_result',
-    'crypto.digest',
-    'crypto.import_key',
-    'crypto.export_key',
-    'crypto.encrypt',
-    'crypto.decrypt',
-    'crypto.sign',
-    'crypto.verify',
-    'crypto.derive_bits',
-    'crypto.mldsa_verify',
-    'crypto.mlkem_decapsulate',
-    'crypto.voprf_evaluate',
-    // ToilDB data API (see ./database.ts). Backed by ScyllaDB on the production
-    // edge; backs the auth example's accounts + login challenges in dev.
-    'data.resolve_collection',
-    'data.get',
-    'data.get_many',
-    'data.exists',
-    'data.create',
-    'data.patch',
-    'data.upsert',
-    'data.delete',
-    'data.get_delete',
-    'data.unique_lookup',
-    'data.unique_claim',
-    'data.unique_release',
-    'data.view_get',
-    'data.view_publish',
-    'data.membership_contains',
-    'data.membership_add',
-    'data.membership_remove',
-    'data.membership_list',
-    'data.counter_get',
-    'data.counter_add',
-    'data.append',
-    'data.append_once',
-    'data.enqueue',
-    'data.latest',
-    'data.events_since',
-    'data.capacity_set_total',
-    'data.capacity_available',
-    'data.capacity_reserve',
-    'data.capacity_confirm',
-    'data.capacity_cancel',
-    'data.take_result',
-    'data.result_schema_version',
-    'data.write_allowed',
-]);
-
-export class WasmServerModule {
-    private module: WebAssembly.Module | null = null;
-    private loadedMtimeMs = -1;
-    private routeKinds: readonly RouteKindEntry[] = [];
-    private rpcKinds: readonly RpcKindEntry[] = [];
-    private derives: readonly DeriveEntry[] = [];
-    // Set when a (re)compile loaded a module with @derive methods; the first
-    // dispatch afterward rebuilds every materialized view from its sources.
-    private derivesDirty = false;
-
-    constructor(private readonly wasmPath: string) {}
-
-    /** Whether a compiled module is currently available to dispatch into. */
-    get available(): boolean {
-        return this.module !== null;
-    }
-
-    /**
-     * (Re)compile when the wasm file appeared or changed since the last load.
-     * Returns `true` when a (re)compile happened, `false` when the cached
-     * module is still current or the file is missing (`available` tells the
-     * caller which).
-     */
-    refresh(): boolean {
-        let mtimeMs: number;
-        try {
-            mtimeMs = fs.statSync(this.wasmPath).mtimeMs;
-        } catch {
-            this.module = null;
-            this.routeKinds = [];
-            this.rpcKinds = [];
-            this.derives = [];
-            this.derivesDirty = false;
-            this.loadedMtimeMs = -1;
-            return false;
-        }
-        if (this.module !== null && mtimeMs === this.loadedMtimeMs) return false;
-
-        const bytes = fs.readFileSync(this.wasmPath);
-        const module = new WebAssembly.Module(bytes);
-        this.assertImportSurface(module);
-        this.assertExportSurface(module);
-        // Refresh collection -> current schema_version so writes stamp the live layout;
-        // after a @data type evolves + rebuild, old on-disk rows now look out of date.
-        setDbCatalog(bytes);
-        this.routeKinds = parseRouteKinds(bytes);
-        this.rpcKinds = parseRpcKinds(bytes);
-        this.derives = parseDerives(bytes);
-        this.module = module;
-        this.loadedMtimeMs = mtimeMs;
-        // Rebuild materialized views from their sources on the first dispatch
-        // (after persistence is configured), so a freshly-loaded box serves
-        // up-to-date views even after an out-of-band change to the source data.
-        this.derivesDirty = this.derives.length > 0;
-        return true;
-    }
-
-    /**
-     * Run one request through a fresh guest instance. Throws on a guest trap
-     * (including ToilScript `abort`), a malformed response envelope, or a
-     * missing module; the caller shapes those into a 500.
-     */
-    dispatch(req: EnvelopeRequest): WasmDispatchResult {
-        if (this.module === null) throw new Error(`server wasm not loaded (${this.wasmPath})`);
-
-        // First dispatch after a (re)load: materialize views from their sources
-        // before serving the request, so reads see fresh views.
-        this.rebuildDerivedViewsIfStale();
-
-        const envelope = encodeRequestEnvelope(req);
-
-        const ref: MemoryRef = { memory: null };
-        const state = freshDispatchState();
-        state.clientIp = req.clientIp ?? '';
-        // Match the edge DB gate: the HTTP method is the baseline authority, and `toildb.route_kinds`
-        // can only tighten a mutating route to query. The reserved /__toil_rpc endpoint is the inverse -
-        // a @remote defaults to read-only (Query); only an @action @remote (in rpc_kinds) may write.
-        const rpcPath = req.path.split('?')[0] ?? req.path;
-        const rpcMethod = req.method.toUpperCase();
-        const rpcMutating =
-            rpcMethod === 'POST' || rpcMethod === 'PUT' || rpcMethod === 'PATCH' || rpcMethod === 'DELETE';
-        if (rpcPath === '/__toil_rpc' && rpcMutating) {
-            const idHeader = req.headers.find(([n]) => n.toLowerCase() === 'dacely-rpc')?.[1];
-            // Strict u32 parse, mirroring the host's `v.parse::<u32>()`: reject trailing garbage/whitespace
-            // and out-of-range ids so a malformed header falls through to read-only Query, exactly as prod.
-            const id = idHeader !== undefined && /^\d+$/.test(idHeader) ? Number(idHeader) : NaN;
-            state.db.functionKind =
-                Number.isInteger(id) && id <= 0xffffffff
-                    ? rpcKindForId(this.rpcKinds, id)
-                    : DbFunctionKind.Query;
-        } else {
-            state.db.functionKind = dbFunctionKindForRequest(this.routeKinds, req.method, req.path);
-        }
-        const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
-        const exports = instance.exports as unknown as HandleExports;
-        ref.memory = exports.memory;
-
-        // The edge writes the envelope at offset 0, which only holds for tiny
-        // requests: ToilScript static data starts at offset 1024, so anything
-        // larger would corrupt the guest. `handle(req_ofs, req_len)` takes the
-        // offset as a parameter, so we stay ABI-compatible and write past the
-        // current end of linear memory instead (grown to fit). The guest heap
-        // grows upward from its data section and copies the envelope into
-        // managed objects on decode, well before it could reach this region.
-        const reqOfs = exports.memory.buffer.byteLength;
-        exports.memory.grow(Math.ceil(envelope.length / WASM_PAGE) || 1);
-        Buffer.from(exports.memory.buffer).set(envelope, reqOfs);
-
-        const packed = exports.handle(reqOfs, envelope.length);
-        const { ptr, len } = unpackHandleResult(packed);
-
-        // Same bounds validation as the edge: never trust the guest's pointer.
-        const memSize = exports.memory.buffer.byteLength;
-        if (len > memSize || ptr + len > memSize)
-            throw new Error(
-                `guest returned an out-of-bounds response: ptr=${String(ptr)} len=${String(len)}`,
-            );
-
-        const resp = decodeResponseEnvelope(new Uint8Array(exports.memory.buffer, ptr, len));
-
-        // Merge the imperative host-import state on top of the envelope (a
-        // toiljs guest answers fully in-band, so this is usually a no-op).
-        const headers: (readonly [string, string])[] = [...resp.headers, ...state.headers];
-        const status = state.status ?? resp.status;
-
-        const unhandled = headers.some(([n]) => n.toLowerCase() === UNHANDLED_HEADER);
-
-        // Materialize: re-run any @derive whose @database had a source
-        // collection written this request, under FunctionKind=Derive, so its
-        // view.publish lands BEFORE the single persistDb() below flushes both the
-        // request's writes and the derive's view to disk. A read writes nothing,
-        // so this is a no-op for GETs.
-        this.runAffectedDerives(state.db.writtenCollections);
-
-        // Flush any DB writes this request made to disk, so dev data survives a
-        // restart (and a crash never loses an already-served write).
-        persistDb();
-
-        return {
-            status,
-            headers: headers.filter(([n]) => n.toLowerCase() !== UNHANDLED_HEADER),
-            body: resp.body,
-            sendfile: state.sendfile,
-            unhandled,
-        };
-    }
-
-    /**
-     * Run one request through the guest `render` entrypoint (edge SSR). Returns
-     * the raw values-envelope bytes (status + template_hash + headers + slot
-     * values) that the edge splices against the template manifest. Throws if
-     * the module has no `render` export. Mirrors {@link dispatch}'s fresh-
-     * instance + grow-and-write-envelope contract.
-     */
-    dispatchRender(req: EnvelopeRequest): Uint8Array {
-        if (this.module === null) throw new Error(`server wasm not loaded (${this.wasmPath})`);
-
-        const envelope = encodeRequestEnvelope(req);
-        const ref: MemoryRef = { memory: null };
-        const state = freshDispatchState();
-        state.clientIp = req.clientIp ?? '';
-        state.db.functionKind = DbFunctionKind.Query;
-        const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
-        const exports = instance.exports as unknown as HandleExports & {
-            render?: (reqOfs: number, reqLen: number) => bigint;
-        };
-        if (typeof exports.render !== 'function')
-            throw new Error(`guest wasm has no 'render' export (${this.wasmPath})`);
-        ref.memory = exports.memory;
-
-        const reqOfs = exports.memory.buffer.byteLength;
-        exports.memory.grow(Math.ceil(envelope.length / WASM_PAGE) || 1);
-        Buffer.from(exports.memory.buffer).set(envelope, reqOfs);
-
-        const packed = exports.render(reqOfs, envelope.length);
-        const { ptr, len } = unpackHandleResult(packed);
-
-        const memSize = exports.memory.buffer.byteLength;
-        if (len > memSize || ptr + len > memSize)
-            throw new Error(
-                `guest returned out-of-bounds values: ptr=${String(ptr)} len=${String(len)}`,
-            );
-        // Copy out of the (about-to-be-dropped) instance's memory.
-        return new Uint8Array(exports.memory.buffer, ptr, len).slice();
-    }
-
-    /**
-     * After a mutating dispatch, re-run each `@derive` whose `@database` had a
-     * source collection written, on a fresh instance under FunctionKind=Derive.
-     * Each derive recomputes + `view.publish`es its materialized view (a later
-     * Query route reads it via the non-scan `view.get`). A trapped derive is
-     * logged and skipped: the request has already succeeded and the next write
-     * re-derives, so a stale view is the worst case. Mirrors the edge runner,
-     * which folds events into the view off the request path; in single-process
-     * dev, running it synchronously-after-the-write is observably equivalent.
-     */
-    private runAffectedDerives(written: ReadonlySet<string>): void {
-        if (this.module === null) return;
-        for (const derive of derivesForWrites(this.derives, written)) {
-            try {
-                this.runDerive(derive.deriveId);
-            } catch (err) {
-                console.error(`[toil] derive ${derive.dbName}#${derive.methodName} failed:`, err);
-            }
-        }
-    }
-
-    /**
-     * On the first dispatch after a (re)compile, rebuild every materialized view
-     * from its sources (server start, hot-reload, or an out-of-band change to the
-     * persisted source data). Runs once per load; ongoing writes are materialized
-     * incrementally by {@link runAffectedDerives}. Mirrors the edge rebuilding a
-     * view from its event log when a box first comes up.
-     */
-    private rebuildDerivedViewsIfStale(): void {
-        if (!this.derivesDirty) return;
-        this.derivesDirty = false;
-        for (const derive of this.derives) {
-            try {
-                this.runDerive(derive.deriveId);
-            } catch (err) {
-                console.error(
-                    `[toil] derive ${derive.dbName}#${derive.methodName} failed on load:`,
-                    err,
-                );
-            }
-        }
-    }
-
-    /** One derive invocation: a fresh instance under Derive kind, calling the
-     *  synthesized `derive_run(derive_id)` export (writes flow to the shared dev
-     *  store via the `data.*` imports; the caller's persistDb() flushes them). */
-    private runDerive(deriveId: number): void {
-        if (this.module === null) return;
-        const ref: MemoryRef = { memory: null };
-        const state = freshDispatchState();
-        state.db.functionKind = DbFunctionKind.Derive;
-        state.db.deriveId = deriveId;
-        const instance = new WebAssembly.Instance(this.module, buildHostImports(ref, state));
-        const exports = instance.exports as unknown as DeriveExports;
-        ref.memory = exports.memory;
-        if (typeof exports.derive_run !== 'function') return;
-        exports.derive_run(deriveId);
-        // Publish-then-persist: derive_run returned (its `view.publish`es landed synchronously in the dev
-        // store), so commit the `events.since` cursor advances staged this run. A trapped fold throws above
-        // and never reaches here, leaving the durable cursor for a re-read on the next trigger.
-        commitDeriveCheckpoints(state.db);
-    }
-
-    /** Fail instantiation up front, with names, when the guest needs imports we do not provide. */
-    private assertImportSurface(module: WebAssembly.Module): void {
-        const missing = WebAssembly.Module.imports(module)
-            .filter(
-                (i) =>
-                    i.kind === 'function' && (i.module !== 'env' || !PROVIDED_IMPORTS.has(i.name)),
-            )
-            .map((i) => `${i.module}.${i.name}`);
-        if (missing.length > 0)
-            throw new Error(
-                `server wasm imports unsupported host functions: ${missing.join(', ')}`,
-            );
-    }
-
-    /** The dispatcher needs the `handle` entrypoint and the exported linear memory. */
-    private assertExportSurface(module: WebAssembly.Module): void {
-        const names = new Set(WebAssembly.Module.exports(module).map((e) => e.name));
-        for (const required of ['handle', 'memory']) {
-            if (!names.has(required))
-                throw new Error(`server wasm does not export \`${required}\``);
-        }
-    }
-}

package/src/devserver/server.ts

@@ -1,251 +0,0 @@
-/**
- * The toiljs WASM dev server: a uWebSockets.js front (via @dacely/hyper-express,
- * the same stack as `toiljs/backend`) that dispatches HTTP requests into the
- * ToilScript-compiled server wasm exactly like the production edge does, and
- * proxies everything the server does not claim to an internal Vite dev server,
- * so dev keeps 100% of Vite's behavior (HMR, transforms, toolbar endpoints,
- * public assets, SPA fallback).
- *
- * Request flow:
- *
- *   browser ── uWS :port ──► wasm `handle()` (fresh instance, envelope ABI)
- *                 │                │
- *                 │                └─ "unhandled" marker (no route matched)
- *                 ▼                                   │
- *           Vite dev server (loopback) ◄──────────────┘
- *
- * Dev intentionally skips the edge's metering, gas, pooling and snapshot-reset
- * machinery; the ABI (envelope layout, `handle(ofs, len) -> i64`, host import
- * surface, trap isolation) is identical so a server that runs here runs there.
- */
-
-import path from 'node:path';
-
-import { Server } from '@dacely/hyper-express';
-import pc from 'picocolors';
-
-import type { EmailBackendConfig } from 'toiljs/shared';
-
-import type { ResolvedDaemonConfig } from './daemon/host.js';
-import { startDaemonRuntime } from './daemon/runtime.js';
-import { configureDbPersistence } from './db/index.js';
-import { initEmailService } from './email/index.js';
-import { proxyToVite, type ViteTarget, wireWebsocketProxy } from './http/proxy.js';
-import {
-    assembleRouteSsr,
-    dispatchWasmRequest,
-    installRuntimeErrorHandler,
-    isDispatchableMethod,
-    runtimeServerOptions,
-    sendSsr,
-} from './http/runtime.js';
-import { WasmServerModule } from './runtime/module.js';
-import { StreamRouter } from './stream/router.js';
-import { streamEmulationEnabled, wireStreams } from './stream/wire.js';
-import { buildSsrRoutes, type DevSsrTemplate, pathnameOf } from './ssr.js';
-
-/**
- * Paths that are Vite's own by construction; skipping the wasm round-trip for
- * them keeps the hot path of module serving untouched. Everything else is
- * offered to the server first (it answers or yields via the unhandled marker).
- */
-const VITE_PREFIXES = ['/@', '/node_modules/', '/__toil/'];
-
-/** Options for {@link startDevServer}. */
-export interface DevServerOptions {
-    /** Project root; `respond_file` paths resolve against it (and may not escape it). */
-    readonly root: string;
-    /** Public listening port (the one the browser opens). */
-    readonly port: number;
-    /** Bind host. Default `127.0.0.1`. */
-    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;
-    /**
-     * Absolute path to the stream artifact (`release-stream.wasm`). When present and this dev process
-     * serves streams (`nodeMode` regional/continental/all), the dev stream router (doc 08 4.1) serves
-     * `@stream`-route WebSocket upgrades. Omit for a project with no `@stream` (the file is never built).
-     */
-    readonly streamWasmFile?: string;
-    /** Which layer the dev process emulates (gates the daemon + stream emulators). 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. */
-    readonly maxBodyLength?: number;
-    /**
-     * The `toil.config.ts` `server.email` section (non-secret). When set (and the
-     * API key is in `.env.secrets`), `EmailService.send` really sends in dev;
-     * 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. */
-export interface RunningDevServer {
-    readonly port: number;
-    readonly host: string;
-    /** Gracefully shuts the front server down (the Vite server is owned by the caller). */
-    close(): Promise<void>;
-}
-
-/** True for requests that belong to Vite by construction (never offered to the wasm). */
-function isViteInternal(url: string): boolean {
-    return VITE_PREFIXES.some((p) => url.startsWith(p));
-}
-
-/**
- * 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
- * the wasm artifact and hot-swaps the compiled module when it changes.
- */
-export async function startDevServer(options: DevServerOptions): Promise<RunningDevServer> {
-    const host = options.host ?? '127.0.0.1';
-    const root = path.resolve(options.root);
-
-    // Wire the email service from toil.config `server.email` + `.env.secrets`
-    // (TOIL_EMAIL_*). Configured -> real sends; otherwise the import stays a
-    // log-only mock. A partial-but-invalid config logs why it stayed off.
-    const emailInit = initEmailService(root, options.email);
-    if (emailInit.service !== null) {
-        process.stdout.write(pc.dim(`  ✉ email enabled: ${emailInit.note}`) + '\n');
-    } else if (emailInit.note !== null) {
-        process.stdout.write(pc.yellow('  ! ') + pc.dim(`email off: ${emailInit.note}`) + '\n');
-    }
-
-    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
-    // directly stay purely in-memory.
-    configureDbPersistence(path.join(root, '.toil', 'devdata.json'));
-
-    let warnedMissing = false;
-    let loadedOnce = false;
-    const refresh = (): void => {
-        try {
-            if (module.refresh() && loadedOnce) {
-                process.stdout.write(pc.green('  ✓ ') + pc.dim('server module reloaded') + '\n');
-            }
-            loadedOnce ||= module.available;
-        } catch (e) {
-            process.stdout.write(pc.red(`  ✗ server wasm failed to load: ${String(e)}`) + '\n');
-        }
-        if (!module.available && !warnedMissing) {
-            warnedMissing = true;
-            process.stdout.write(
-                pc.yellow('  ! ') +
-                    pc.dim(`server wasm not found at ${options.wasmFile}; serving client only`) +
-                    '\n',
-            );
-        }
-    };
-    refresh();
-
-    const app = new Server(runtimeServerOptions(options));
-    installRuntimeErrorHandler(app);
-
-    const nodeMode = options.nodeMode ?? 'all';
-
-    // Dev STREAM (L2/L3) emulation (doc 08 4.1): when a stream artifact is built AND this dev process
-    // serves streams, route `@stream`-route WebSocket upgrades to the resident-box stream router and
-    // proxy everything else (Vite HMR) upstream; otherwise the plain Vite proxy (existing behaviour).
-    if (options.streamWasmFile !== undefined && streamEmulationEnabled(nodeMode)) {
-        wireStreams(app, options.vite, new StreamRouter(options.streamWasmFile));
-    } else {
-        wireWebsocketProxy(app, options.vite);
-    }
-
-    const daemon = startDaemonRuntime({
-        coldWasmFile: options.coldWasmFile,
-        nodeMode,
-        daemon: options.daemon,
-    });
-
-    app.any('/*', async (request, response) => {
-        response.removeHeader('uWebSockets');
-
-        const dispatchable = !isViteInternal(request.url) && isDispatchableMethod(request.method);
-        if (dispatchable) refresh();
-
-        if (dispatchable && module.available) {
-            const dispatch = await dispatchWasmRequest({
-                module,
-                request,
-                response,
-                root,
-                cacheHost: request.headers.host ?? 'dev',
-                serverHeader: 'toil-dev',
-                errorPrefix: '✗',
-            });
-            if (dispatch.handled) {
-                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 {
-                        // A static route (its template has no holes -> no slots) needs no guest
-                        // render: serve the prerendered template directly so it paints instantly
-                        // instead of falling through to a (blank-until-JS) client render. Dynamic
-                        // routes run the guest `render` and splice its values in.
-                        const out = assembleRouteSsr(route, module, dispatch.envelopeReq);
-                        if (out !== null) {
-                            sendSsr(response, out, request.method === 'HEAD', 'toil-dev');
-                            return;
-                        }
-                    } catch (e) {
-                        process.stdout.write(
-                            pc.red(`  ✗ SSR ${request.path}: ${String(e)}`) + '\n',
-                        );
-                    }
-                }
-            }
-        }
-
-        await proxyToVite(request, response, options.vite);
-    });
-
-    await app.listen(options.port, host);
-
-    return {
-        port: options.port,
-        host,
-        close: async (): Promise<void> => {
-            daemon?.close();
-            await app.shutdown();
-        },
-    };
-}