toiljs 0.0.67 → 0.0.69

package/src/devserver/runtime/module.ts

@@ -13,7 +13,14 @@
 
 import fs from 'node:fs';
 
-import { DbFunctionKind, persistDb, setDbCatalog } from '../db/index.js';
+import {
+    DbFunctionKind,
+    type DeriveEntry,
+    derivesForWrites,
+    parseDerives,
+    persistDb,
+    setDbCatalog,
+} from '../db/index.js';
 import { parseRouteKinds, routeKindForRequest, type RouteKindEntry } from '../db/routeKinds.js';
 import {
     decodeResponseEnvelope,
@@ -76,6 +83,13 @@ interface HandleExports {
     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',
@@ -143,6 +157,10 @@ export class WasmServerModule {
     private module: WebAssembly.Module | null = null;
     private loadedMtimeMs = -1;
     private routeKinds: readonly RouteKindEntry[] = [];
+    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) {}
 
@@ -164,6 +182,8 @@ export class WasmServerModule {
         } catch {
             this.module = null;
             this.routeKinds = [];
+            this.derives = [];
+            this.derivesDirty = false;
             this.loadedMtimeMs = -1;
             return false;
         }
@@ -177,8 +197,13 @@ export class WasmServerModule {
         // after a @data type evolves + rebuild, old on-disk rows now look out of date.
         setDbCatalog(bytes);
         this.routeKinds = parseRouteKinds(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;
     }
 
@@ -190,6 +215,10 @@ export class WasmServerModule {
     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 };
@@ -232,6 +261,13 @@ export class WasmServerModule {
 
         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();
@@ -284,6 +320,64 @@ export class WasmServerModule {
         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;
+        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);
+    }
+
     /** 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)

package/src/devserver/server.ts

@@ -19,31 +19,30 @@
  * surface, trap isolation) is identical so a server that runs here runs there.
  */
 
-import fs from 'node:fs';
 import path from 'node:path';
 
-import { type Request, type Response, Server } from '@dacely/hyper-express';
+import { Server } from '@dacely/hyper-express';
 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 { startDaemonRuntime } from './daemon/runtime.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;
+    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
@@ -52,26 +51,6 @@ const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
  */
 const VITE_PREFIXES = ['/@', '/node_modules/', '/__toil/'];
 
-/** Minimal type map for `respond_file` bodies when the guest set no content-type. */
-const MIME: Readonly<Record<string, string>> = {
-    '.html': 'text/html; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.mjs': 'text/javascript; charset=utf-8',
-    '.css': 'text/css; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.txt': 'text/plain; charset=utf-8',
-    '.svg': 'image/svg+xml',
-    '.png': 'image/png',
-    '.jpg': 'image/jpeg',
-    '.jpeg': 'image/jpeg',
-    '.webp': 'image/webp',
-    '.avif': 'image/avif',
-    '.gif': 'image/gif',
-    '.ico': 'image/x-icon',
-    '.wasm': 'application/wasm',
-    '.woff2': 'font/woff2',
-};
-
 /** Options for {@link startDevServer}. */
 export interface DevServerOptions {
     /** Project root; `respond_file` paths resolve against it (and may not escape it). */
@@ -88,7 +67,13 @@ export interface DevServerOptions {
      * (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`. */
+    /**
+     * 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;
@@ -124,92 +109,6 @@ function isViteInternal(url: string): boolean {
     return VITE_PREFIXES.some((p) => url.startsWith(p));
 }
 
-/** Resolves a guest `respond_file` path inside `root`, refusing traversal outside it. */
-function resolveSendfile(root: string, file: string): string | null {
-    const resolved = path.resolve(root, file);
-    if (resolved !== root && !resolved.startsWith(root + path.sep)) return null;
-    if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) return null;
-    return resolved;
-}
-
-/** Builds the envelope request for one incoming HTTP request. */
-async function toEnvelopeRequest(request: Request): Promise<EnvelopeRequest> {
-    const hasBody = request.method !== 'GET' && request.method !== 'HEAD';
-    const body = hasBody ? new Uint8Array(await request.buffer()) : new Uint8Array(0);
-    // Dev parity for `client_ip`: the edge keys on the unspoofable socket peer,
-    // but the dev server has no DPDK socket, so best-effort from a proxy's
-    // `x-forwarded-for`, else localhost, so `ctx.clientIp()` returns a value.
-    const xff = request.headers['x-forwarded-for'];
-    const clientIp =
-        typeof xff === 'string' && xff.length > 0 ? xff.split(',')[0]!.trim() : '127.0.0.1';
-    return {
-        method: request.method,
-        // `url` keeps the query string; the guest's RouteContext parses it off the path.
-        path: request.url,
-        headers: Object.entries(request.headers),
-        body,
-        clientIp,
-    };
-}
-
-/** Sends a shaped wasm response, mirroring the edge's response defaults. */
-function sendWasmResponse(
-    response: Response,
-    root: string,
-    result: {
-        status: number;
-        headers: readonly (readonly [string, string])[];
-        body: Uint8Array;
-        sendfile: string | null;
-    },
-): void {
-    response.status(result.status);
-    let hasContentType = false;
-    for (const [name, value] of result.headers) {
-        if (name.toLowerCase() === 'content-type') hasContentType = true;
-        response.header(name, value);
-    }
-    response.header('server', 'toil-dev');
-
-    if (result.sendfile !== null) {
-        const file = resolveSendfile(root, result.sendfile);
-        if (file === null) {
-            response.status(404).send('not found\n');
-            return;
-        }
-        if (!hasContentType) {
-            // The edge defaults file bodies to application/octet-stream; in dev we
-            // guess from the extension so a guest-served asset renders in the browser.
-            response.header(
-                'content-type',
-                MIME[path.extname(file).toLowerCase()] ?? 'application/octet-stream',
-            );
-        }
-        response.sendFile(file);
-        return;
-    }
-
-    if (!hasContentType) response.header('content-type', 'text/plain; charset=utf-8');
-    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
@@ -269,84 +168,43 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
     };
     refresh();
 
-    const app = new Server({
-        max_body_length: options.maxBodyLength ?? DEFAULT_MAX_BODY_LENGTH,
-        max_body_buffer: 1024 * 32,
-        fast_abort: true,
-    });
-
-    app.set_error_handler((_request: Request, response: Response, error: Error) => {
-        if (response.completed) return;
-        response.atomic(() => {
-            response.status(500).send(`internal error: ${error.message}\n`);
-        });
-    });
-
-    wireWebsocketProxy(app, options.vite);
+    const app = new Server(runtimeServerOptions(options));
+    installRuntimeErrorHandler(app);
 
-    // 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?.();
+
+    // 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);
     }
 
-    app.any('/*', async (request: Request, response: Response) => {
+    const daemon = startDaemonRuntime({
+        coldWasmFile: options.coldWasmFile,
+        nodeMode,
+        daemon: options.daemon,
+    });
+
+    app.any('/*', async (request, response) => {
         response.removeHeader('uWebSockets');
 
-        const dispatchable =
-            !isViteInternal(request.url) && METHOD_CODES[request.method] !== undefined;
+        const dispatchable = !isViteInternal(request.url) && isDispatchableMethod(request.method);
         if (dispatchable) refresh();
 
         if (dispatchable && module.available) {
-            const envelopeReq = await toEnvelopeRequest(request);
-            // Honor the tenant cache directive locally, same rules as the
-            // edge: serve an identical request from the per-process cache,
-            // else dispatch and apply/strip the directive on the response.
-            const cacheHost = request.headers.host ?? 'dev';
-            const hasAuth =
-                request.headers.cookie !== undefined || request.headers.authorization !== undefined;
-            const cached = lookupCache(cacheHost, request.method, request.url, envelopeReq.body);
-            if (cached !== null) {
-                sendWasmResponse(response, root, cached);
-                return;
-            }
-            try {
-                const result = module.dispatch(envelopeReq);
-                if (!result.unhandled) {
-                    const finalized = applyCacheRule(
-                        cacheHost,
-                        request.method,
-                        request.url,
-                        envelopeReq.body,
-                        hasAuth,
-                        result,
-                    );
-                    sendWasmResponse(response, root, finalized);
-                    return;
-                }
-            } catch (e) {
-                // A trap (ToilScript abort, OOB, malformed envelope) is isolated to
-                // this request, exactly like the edge poisoning one instance.
-                process.stdout.write(
-                    pc.red(`  ✗ ${request.method} ${request.path} server error: ${String(e)}`) +
-                        '\n',
-                );
-                response.status(500).send('internal error\n');
+            const dispatch = await dispatchWasmRequest({
+                module,
+                request,
+                response,
+                root,
+                cacheHost: request.headers.host ?? 'dev',
+                serverHeader: 'toil-dev',
+                errorPrefix: '✗',
+            });
+            if (dispatch.handled) {
                 return;
             }
 
@@ -355,10 +213,7 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
             // 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
-            ) {
+            if ((request.method === 'GET' || request.method === 'HEAD') && ssrRoutes.length > 0) {
                 const route = ssrRoutes.find((r) => r.test(pathnameOf(request.url)));
                 if (route) {
                     try {
@@ -366,12 +221,9 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
                         // 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: SsrResult | null =
-                            route.entries.length === 0
-                                ? { status: 200, headers: [], html: route.tmpl }
-                                : assembleSsr(route, module.dispatchRender(envelopeReq));
+                        const out = assembleRouteSsr(route, module, dispatch.envelopeReq);
                         if (out !== null) {
-                            sendSsr(response, out, request.method === 'HEAD');
+                            sendSsr(response, out, request.method === 'HEAD', 'toil-dev');
                             return;
                         }
                     } catch (e) {
@@ -392,8 +244,7 @@ export async function startDevServer(options: DevServerOptions): Promise<Running
         port: options.port,
         host,
         close: async (): Promise<void> => {
-            if (daemonTimer !== null) clearInterval(daemonTimer);
-            daemonHost?.close();
+            daemon?.close();
             await app.shutdown();
         },
     };

package/src/devserver/ssr.ts

@@ -20,6 +20,8 @@ export interface DevSsrTemplate {
     name: string;
     tmpl: Uint8Array;
     entries: { id: number; offset: number }[];
+    /** Optional deployed template hash. Present for built/self-host SSR, omitted in dev. */
+    hash?: Uint8Array;
 }
 
 /** A matchable SSR route. */
@@ -28,6 +30,8 @@ export interface SsrRoute {
     test: (pathname: string) => boolean;
     tmpl: Uint8Array;
     entries: { id: number; offset: number }[];
+    /** Optional deployed template hash. When present, guest values must match it. */
+    hash?: Uint8Array;
 }
 
 /** The pathname of a request URL (strip the query string). */
@@ -71,12 +75,18 @@ function patternToTest(pattern: string): (pathname: string) => boolean {
 
 /** 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 }));
+    return templates.map((t) => ({
+        test: patternToTest(t.pattern),
+        tmpl: t.tmpl,
+        entries: t.entries,
+        hash: t.hash,
+    }));
 }
 
 /** A decoded guest values envelope. */
 interface DecodedValues {
     status: number;
+    hash: Uint8Array;
     headers: [string, string][];
     /** Slot value bytes keyed by numeric slot id. */
     values: Map<number, Uint8Array>;
@@ -92,7 +102,8 @@ function decodeValues(buf: Uint8Array): DecodedValues | null {
         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 hash = buf.subarray(o, o + 32);
+        o += 32;
         const nHeaders = dv.getUint16(o, true);
         o += 2;
         const headers: [string, string][] = [];
@@ -124,12 +135,20 @@ function decodeValues(buf: Uint8Array): DecodedValues | null {
             values.set(id, buf.subarray(o, o + len));
             o += len;
         }
-        return { status, headers, values };
+        return { status, hash, headers, values };
     } catch {
         return null;
     }
 }
 
+function sameBytes(a: Uint8Array, b: Uint8Array): boolean {
+    if (a.byteLength !== b.byteLength) return false;
+    for (let i = 0; i < a.byteLength; i++) {
+        if (a[i] !== b[i]) return false;
+    }
+    return true;
+}
+
 /** Splice ascending-offset inserts into the template (mirrors the host `assemble`). */
 function splice(tmpl: Uint8Array, inserts: { offset: number; value: Uint8Array }[]): Uint8Array {
     const parts: Uint8Array[] = [];
@@ -159,6 +178,7 @@ export function assembleSsr(route: SsrRoute, envelope: Uint8Array): SsrResult |
     const decoded = decodeValues(envelope);
     if (decoded === null) return null;
     if (decoded.status >= 500 || decoded.values.size === 0) return null;
+    if (route.hash !== undefined && !sameBytes(decoded.hash, route.hash)) 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);

package/src/devserver/stream/catalog.ts

@@ -0,0 +1,106 @@
+/**
+ * Parse a compiled HOT server wasm's `toilstream.catalog` custom section into the dev stream router's
+ * route table (doc 08 section 3.1; emitted by the toilscript hot pass per RECONCILIATION Part 5 when
+ * any `@stream` class exists). The dev router keys on `route` (the `@stream` class's fixed mount path)
+ * to intercept matching WebSocket upgrades (section 4.1/4.2) and ignore the rest (Vite HMR).
+ *
+ * Byte layout (Part 5, all little-endian; mirrors the toilscript emitter + the edge decoder):
+ *
+ *   u16 format_version (= 1)
+ *   u16 n_streams
+ *   per stream:
+ *     str name                     (the @stream class name)
+ *     str route                    (the mount path, e.g. "/echo")
+ *     u8  hook_presence_bitmask    (bit0 connect, bit1 message, bit2 close, bit3 disconnect)
+ *     u8  declared_scope           (0 = L2 regional, 1 = L3 continental)
+ *     u8  message_mode             (0 = raw bytes default, 1 = @data-typed)
+ *     u32 max_frame_bytes
+ *     u32 ingress_ring_bytes
+ *     u32 message_value_data_id    (0 when message_mode = 0)
+ *     u32 message_schema_version   (0 when message_mode = 0)
+ *     u16 stream_index
+ *
+ * Fails closed via `DataReader.ok`: a short read mid-record stops the loop and yields the cleanly
+ * decoded prefix; an absent/unparseable section yields an empty map (the dev router serves no stream).
+ */
+
+import { DataReader } from 'toiljs/io';
+
+import { customSection } from '../wasm/sections.js';
+
+/** One `@stream` class's catalog entry (doc 08 section 3.1). */
+export interface StreamDef {
+    readonly name: string;
+    readonly route: string;
+    readonly hooks: {
+        readonly connect: boolean;
+        readonly message: boolean;
+        readonly close: boolean;
+        readonly disconnect: boolean;
+    };
+    readonly scope: 'regional' | 'continental';
+    readonly messageMode: 'raw' | 'data';
+    readonly maxFrameBytes: number;
+    readonly ingressRingBytes: number;
+    readonly messageValueDataId: number;
+    readonly messageSchemaVersion: number;
+    readonly streamIndex: number;
+}
+
+/** The dev router's route table, keyed by the `@stream` mount path. */
+export type StreamCatalog = Map<string, StreamDef>;
+
+/** Parse `toilstream.catalog` into a route table. Absent/unparseable -> empty (serve no stream). */
+export function parseStreamCatalog(wasm: Buffer): StreamCatalog {
+    const out: StreamCatalog = new Map();
+    let sec: Buffer | null;
+    try {
+        sec = customSection(wasm, 'toilstream.catalog');
+    } catch {
+        return out;
+    }
+    if (sec === null) return out;
+    const r = new DataReader(sec);
+    r.readU16(); // format_version
+    const n = r.readU16();
+    for (let i = 0; i < n && r.ok; i++) {
+        const name = r.readString();
+        const route = r.readString();
+        const bits = r.readU8();
+        const scope = r.readU8() === 1 ? 'continental' : 'regional';
+        const messageMode = r.readU8() === 1 ? 'data' : 'raw';
+        const maxFrameBytes = r.readU32();
+        const ingressRingBytes = r.readU32();
+        const messageValueDataId = r.readU32();
+        const messageSchemaVersion = r.readU32();
+        const streamIndex = r.readU16();
+        if (!r.ok) break;
+        out.set(route, {
+            name,
+            route,
+            hooks: {
+                connect: (bits & 1) !== 0,
+                message: (bits & 2) !== 0,
+                close: (bits & 4) !== 0,
+                disconnect: (bits & 8) !== 0,
+            },
+            scope,
+            messageMode,
+            maxFrameBytes,
+            ingressRingBytes,
+            messageValueDataId,
+            messageSchemaVersion,
+            streamIndex,
+        });
+    }
+    return out;
+}
+
+/** Exact-path route match (doc 08 section 4.2): strip the query string, then look the path up in the
+ *  catalog. Returns the matched `@stream` def, or `null` when the path is not a stream route (the dev
+ *  router then proxies the upgrade to Vite). */
+export function matchStreamRoute(catalog: StreamCatalog, path: string): StreamDef | null {
+    const q = path.indexOf('?');
+    const exact = q >= 0 ? path.slice(0, q) : path;
+    return catalog.get(exact) ?? null;
+}