toiljs 0.0.67 → 0.0.68

package/build/devserver/stream/index.js

@@ -0,0 +1,220 @@
+import { parseSurface } from '../wasm/surface.js';
+import { buildStreamImports, freshStreamBoxState } from './host.js';
+const EVENT_CONNECT = 1;
+const EVENT_MESSAGE = 2;
+const EVENT_CLOSE = 3;
+const EVENT_DISCONNECT = 4;
+const RING_CTRL_BYTES = 32;
+const RING_FRAME_HEADER = 12;
+const RING_MAGIC = 0x3147_4e52;
+const RING_VERSION = 1;
+const RC_WRITE = 12;
+const RC_READ = 16;
+const FRAME_TYPE_DATA_RELIABLE = 1;
+const MAX_STREAM_FRAME_LEN = 65536;
+const SI_TRANSPORT = 8;
+const SI_AUTH_LEN = 10;
+const SI_PATH_LEN = 12;
+const SI_RESERVED2 = 14;
+const SI_BODY = 16;
+const SI_TRANSPORT_WEBTRANSPORT = 1;
+export function decodeRejectCode(rc) {
+    const raw = Number((-rc - 0x10000n) & 0xffffn);
+    return raw >= 0x0200 && raw <= 0x02ff ? raw : 0x0208;
+}
+export class DevStreamBox {
+    exports;
+    _state;
+    rings;
+    streamInfo;
+    constructor(exports, _state, rings, streamInfo) {
+        this.exports = exports;
+        this._state = _state;
+        this.rings = rings;
+        this.streamInfo = streamInfo;
+    }
+    static load(wasm) {
+        const surface = parseSurface(wasm);
+        if (surface === 'invalid' || surface.targetMode !== 'hot') {
+            throw new Error('stream box requires a hot artifact with a valid toil.surface');
+        }
+        const ref = { memory: null };
+        const state = freshStreamBoxState();
+        const module = new WebAssembly.Module(new Uint8Array(wasm));
+        const instance = new WebAssembly.Instance(module, buildStreamImports(ref, state));
+        const exports = instance.exports;
+        if (typeof exports.stream_dispatch !== 'function' ||
+            !(exports.memory instanceof WebAssembly.Memory)) {
+            throw new Error("stream artifact must export 'stream_dispatch' + 'memory'");
+        }
+        ref.memory = exports.memory;
+        const rings = DevStreamBox.resolveRings(exports);
+        const streamInfo = DevStreamBox.resolveStreamInfo(exports);
+        const box = new DevStreamBox(exports, state, rings, streamInfo);
+        if (rings)
+            box.stampRings();
+        return box;
+    }
+    get hasRings() {
+        return this.rings !== null;
+    }
+    get hasConnectBridge() {
+        return this.streamInfo !== null;
+    }
+    onConnect(streamId, authority, path) {
+        this.writeConnectInfo(streamId, authority, path);
+        const rc = this.dispatch(EVENT_CONNECT, streamId);
+        if (rc < 0n)
+            return { kind: 'reject', code: decodeRejectCode(rc) };
+        this.resetEgressRing();
+        return { kind: 'accept' };
+    }
+    onClose(streamId) {
+        return this.dispatch(EVENT_CLOSE, streamId);
+    }
+    onDisconnect(streamId) {
+        return this.dispatch(EVENT_DISCONNECT, streamId);
+    }
+    onMessage(streamId, inbound) {
+        if (!this.rings) {
+            throw new Error('stream box has no ring runtime; the message bridge is unavailable');
+        }
+        this.ingressWrite(inbound);
+        const ret = this.dispatch(EVENT_MESSAGE, streamId);
+        if (ret < 0n)
+            return { kind: 'reject', code: decodeRejectCode(ret) };
+        return { kind: 'reply', frames: this.egressDrain() };
+    }
+    dispatch(eventKind, streamId) {
+        const lo = Number(streamId & 0xffffffffn) | 0;
+        const hi = Number((streamId >> 32n) & 0xffffffffn) | 0;
+        return this.exports.stream_dispatch(eventKind, lo, hi);
+    }
+    static resolveRings(e) {
+        if (typeof e.stream_ring_offset !== 'function' ||
+            typeof e.stream_ring_capacity !== 'function' ||
+            typeof e.stream_egress_offset !== 'function' ||
+            typeof e.stream_egress_capacity !== 'function') {
+            return null;
+        }
+        return {
+            ingressOff: e.stream_ring_offset() >>> 0,
+            ingressCap: e.stream_ring_capacity() >>> 0,
+            egressOff: e.stream_egress_offset() >>> 0,
+            egressCap: e.stream_egress_capacity() >>> 0,
+        };
+    }
+    static resolveStreamInfo(e) {
+        if (typeof e.stream_info_offset !== 'function' || typeof e.stream_info_capacity !== 'function') {
+            return null;
+        }
+        return { offset: e.stream_info_offset() >>> 0, cap: e.stream_info_capacity() >>> 0 };
+    }
+    stampRings() {
+        const rings = this.rings;
+        if (!rings)
+            return;
+        this.stampOne(rings.ingressOff, rings.ingressCap);
+        this.stampOne(rings.egressOff, rings.egressCap);
+    }
+    stampOne(base, cap) {
+        const dv = new DataView(this.exports.memory.buffer);
+        dv.setUint32(base + 0, RING_MAGIC, true);
+        dv.setUint16(base + 4, RING_VERSION, true);
+        dv.setUint16(base + 6, 0, true);
+        dv.setUint32(base + 8, cap, true);
+        dv.setUint32(base + RC_WRITE, 0, true);
+        dv.setUint32(base + RC_READ, 0, true);
+    }
+    writeConnectInfo(streamId, authority, path) {
+        const info = this.streamInfo;
+        if (!info)
+            return;
+        const base = info.offset;
+        const body = Math.max(0, info.cap - SI_BODY);
+        const authBytes = Buffer.from(authority, 'utf8');
+        const authLen = Math.min(authBytes.length, 0xffff, body);
+        const pathBytes = Buffer.from(path, 'utf8');
+        const pathLen = Math.min(pathBytes.length, 0xffff, body - authLen);
+        const dv = new DataView(this.exports.memory.buffer);
+        dv.setBigUint64(base + 0, streamId, true);
+        dv.setUint8(base + SI_TRANSPORT, SI_TRANSPORT_WEBTRANSPORT);
+        dv.setUint8(base + SI_TRANSPORT + 1, 0);
+        dv.setUint16(base + SI_AUTH_LEN, authLen, true);
+        dv.setUint16(base + SI_PATH_LEN, pathLen, true);
+        dv.setUint16(base + SI_RESERVED2, 0, true);
+        const memU8 = new Uint8Array(this.exports.memory.buffer);
+        if (authLen > 0)
+            memU8.set(authBytes.subarray(0, authLen), base + SI_BODY);
+        if (pathLen > 0)
+            memU8.set(pathBytes.subarray(0, pathLen), base + SI_BODY + authLen);
+    }
+    resetEgressRing() {
+        const rings = this.rings;
+        if (!rings)
+            return;
+        const dv = new DataView(this.exports.memory.buffer);
+        dv.setUint32(rings.egressOff + RC_WRITE, 0, true);
+        dv.setUint32(rings.egressOff + RC_READ, 0, true);
+    }
+    ingressWrite(inbound) {
+        const rings = this.rings;
+        if (!rings)
+            throw new Error('ingressWrite: no ring runtime');
+        const { ingressOff: base, ingressCap: cap } = rings;
+        const dv = new DataView(this.exports.memory.buffer);
+        const n = inbound.length;
+        const frameLen = RING_FRAME_HEADER + n;
+        if (frameLen > cap) {
+            throw new Error(`inbound frame (${String(frameLen)} B) exceeds ingress capacity`);
+        }
+        const w0 = dv.getUint32(base + RC_WRITE, true);
+        const r0 = dv.getUint32(base + RC_READ, true);
+        let w;
+        if (r0 === w0) {
+            dv.setUint32(base + RC_WRITE, 0, true);
+            dv.setUint32(base + RC_READ, 0, true);
+            w = 0;
+        }
+        else {
+            w = w0;
+        }
+        if (w + frameLen > cap)
+            throw new Error('ingress frame would not fit (v1 is no-wrap)');
+        const f = base + RING_CTRL_BYTES + w;
+        dv.setUint8(f + 0, RING_VERSION);
+        dv.setUint8(f + 1, FRAME_TYPE_DATA_RELIABLE);
+        dv.setUint16(f + 2, 0, true);
+        dv.setUint32(f + 4, n, true);
+        dv.setUint32(f + 8, 0, true);
+        if (n > 0)
+            new Uint8Array(this.exports.memory.buffer, f + RING_FRAME_HEADER, n).set(inbound);
+        dv.setUint32(base + RC_WRITE, w + frameLen, true);
+    }
+    egressDrain() {
+        const rings = this.rings;
+        if (!rings)
+            return [];
+        const { egressOff: base, egressCap: cap } = rings;
+        const dv = new DataView(this.exports.memory.buffer);
+        const w = dv.getUint32(base + RC_WRITE, true);
+        let r = dv.getUint32(base + RC_READ, true);
+        const frames = [];
+        while (r < w) {
+            const f = base + RING_CTRL_BYTES + r;
+            if (r + RING_FRAME_HEADER > cap)
+                break;
+            const len = dv.getUint32(f + 4, true);
+            if (len > MAX_STREAM_FRAME_LEN)
+                break;
+            const span = RING_FRAME_HEADER + len;
+            if (r + span > cap)
+                break;
+            const payloadOff = f + RING_FRAME_HEADER;
+            frames.push(Buffer.from(new Uint8Array(this.exports.memory.buffer, payloadOff, len)));
+            r += span;
+        }
+        dv.setUint32(base + RC_READ, r, true);
+        return frames;
+    }
+}

package/build/devserver/stream/manager.d.ts

@@ -0,0 +1,34 @@
+export declare const STREAM_REJECTED = 520;
+export declare const STREAM_HOOK_TRAPPED = 512;
+export type StreamUpgradeOutcome = {
+    readonly kind: 'accepted';
+    readonly streamId: bigint;
+} | {
+    readonly kind: 'rejected';
+    readonly code: number;
+};
+export type StreamDispatchResult = {
+    readonly kind: 'reply';
+    readonly frames: Buffer[];
+} | {
+    readonly kind: 'close';
+    readonly code: number;
+} | {
+    readonly kind: 'noConnection';
+};
+export declare class StreamDevHost {
+    private readonly streamWasmPath;
+    private bytes;
+    private loadedMtimeMs;
+    private readonly conns;
+    private nextStreamId;
+    constructor(streamWasmPath: string);
+    get activeConnections(): number;
+    has(connId: string): boolean;
+    acceptUpgrade(connId: string, authority: string, path: string): StreamUpgradeOutcome;
+    dispatch(connId: string, inbound: Buffer): StreamDispatchResult;
+    close(connId: string): void;
+    disconnect(connId: string): void;
+    private refresh;
+    private allocStreamId;
+}

package/build/devserver/stream/manager.js

@@ -0,0 +1,103 @@
+import fs from 'node:fs';
+import { DevStreamBox } from './index.js';
+export const STREAM_REJECTED = 0x0208;
+export const STREAM_HOOK_TRAPPED = 0x0200;
+export class StreamDevHost {
+    streamWasmPath;
+    bytes = null;
+    loadedMtimeMs = -1;
+    conns = new Map();
+    nextStreamId = 1n;
+    constructor(streamWasmPath) {
+        this.streamWasmPath = streamWasmPath;
+    }
+    get activeConnections() {
+        return this.conns.size;
+    }
+    has(connId) {
+        return this.conns.has(connId);
+    }
+    acceptUpgrade(connId, authority, path) {
+        if (this.conns.has(connId))
+            throw new Error(`stream connection '${connId}' is already open`);
+        this.refresh();
+        if (!this.bytes)
+            return { kind: 'rejected', code: STREAM_REJECTED };
+        let box;
+        try {
+            box = DevStreamBox.load(this.bytes);
+        }
+        catch {
+            return { kind: 'rejected', code: STREAM_REJECTED };
+        }
+        const streamId = this.allocStreamId();
+        let outcome;
+        try {
+            outcome = box.onConnect(streamId, authority, path);
+        }
+        catch {
+            return { kind: 'rejected', code: STREAM_HOOK_TRAPPED };
+        }
+        if (outcome.kind === 'reject')
+            return { kind: 'rejected', code: outcome.code };
+        this.conns.set(connId, { box, streamId });
+        return { kind: 'accepted', streamId };
+    }
+    dispatch(connId, inbound) {
+        const conn = this.conns.get(connId);
+        if (!conn)
+            return { kind: 'noConnection' };
+        try {
+            const out = conn.box.onMessage(conn.streamId, inbound);
+            if (out.kind === 'reply')
+                return { kind: 'reply', frames: out.frames };
+            return { kind: 'close', code: out.code };
+        }
+        catch {
+            this.conns.delete(connId);
+            return { kind: 'close', code: STREAM_HOOK_TRAPPED };
+        }
+    }
+    close(connId) {
+        const conn = this.conns.get(connId);
+        if (!conn)
+            return;
+        try {
+            conn.box.onClose(conn.streamId);
+        }
+        catch {
+        }
+        this.conns.delete(connId);
+    }
+    disconnect(connId) {
+        const conn = this.conns.get(connId);
+        if (!conn)
+            return;
+        try {
+            conn.box.onDisconnect(conn.streamId);
+        }
+        catch {
+        }
+        this.conns.delete(connId);
+    }
+    refresh() {
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(this.streamWasmPath).mtimeMs;
+        }
+        catch {
+            this.bytes = null;
+            this.loadedMtimeMs = -1;
+            return;
+        }
+        if (mtimeMs === this.loadedMtimeMs && this.bytes)
+            return;
+        this.bytes = fs.readFileSync(this.streamWasmPath);
+        this.loadedMtimeMs = mtimeMs;
+    }
+    allocStreamId() {
+        const id = this.nextStreamId;
+        this.nextStreamId = id + 1n;
+        return id;
+    }
+}

package/build/devserver/stream/router.d.ts

@@ -0,0 +1,25 @@
+import { type StreamDef } from './catalog.js';
+export interface StreamWs {
+    send(data: Buffer, isBinary: boolean): void;
+    close(code: number): void;
+    on(event: 'message', cb: (message: Buffer, isBinary: boolean) => void): void;
+    on(event: 'close', cb: () => void): void;
+}
+export interface StreamUpgradeContext {
+    readonly kind: 'stream';
+    readonly route: string;
+    readonly url: string;
+    readonly authority: string;
+}
+export declare class StreamRouter {
+    private readonly streamWasmPath;
+    private catalog;
+    private catalogMtimeMs;
+    private readonly host;
+    private connSeq;
+    constructor(streamWasmPath: string);
+    get activeConnections(): number;
+    matchRoute(path: string): StreamDef | null;
+    onUpgrade(ws: StreamWs, ctx: StreamUpgradeContext): void;
+    private refreshCatalog;
+}

package/build/devserver/stream/router.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import { matchStreamRoute, parseStreamCatalog, } from './catalog.js';
+import { StreamDevHost } from './manager.js';
+import { StreamWsSession } from './ws.js';
+export class StreamRouter {
+    streamWasmPath;
+    catalog = new Map();
+    catalogMtimeMs = -1;
+    host;
+    connSeq = 0;
+    constructor(streamWasmPath) {
+        this.streamWasmPath = streamWasmPath;
+        this.host = new StreamDevHost(streamWasmPath);
+        this.refreshCatalog();
+    }
+    get activeConnections() {
+        return this.host.activeConnections;
+    }
+    matchRoute(path) {
+        this.refreshCatalog();
+        return matchStreamRoute(this.catalog, path);
+    }
+    onUpgrade(ws, ctx) {
+        const connId = `s${String(++this.connSeq)}`;
+        const q = ctx.url.indexOf('?');
+        const path = q >= 0 ? ctx.url.slice(0, q) : ctx.url;
+        const session = new StreamWsSession(this.host, connId, ctx.authority, path, {
+            send: (frame) => {
+                ws.send(frame, true);
+            },
+            close: (code) => {
+                ws.close(code);
+            },
+        });
+        if (!session.onOpen())
+            return;
+        ws.on('message', (message) => {
+            session.onMessage(message);
+        });
+        ws.on('close', () => {
+            session.onClose();
+        });
+    }
+    refreshCatalog() {
+        let mtimeMs;
+        try {
+            mtimeMs = fs.statSync(this.streamWasmPath).mtimeMs;
+        }
+        catch {
+            this.catalog = new Map();
+            this.catalogMtimeMs = -1;
+            return;
+        }
+        if (mtimeMs === this.catalogMtimeMs && this.catalog.size > 0)
+            return;
+        try {
+            this.catalog = parseStreamCatalog(fs.readFileSync(this.streamWasmPath));
+        }
+        catch {
+            this.catalog = new Map();
+        }
+        this.catalogMtimeMs = mtimeMs;
+    }
+}

package/build/devserver/stream/wire.d.ts

@@ -0,0 +1,5 @@
+import { type Server } from '@dacely/hyper-express';
+import { type ViteTarget } from '../http/proxy.js';
+import { type StreamRouter } from './router.js';
+export declare function streamEmulationEnabled(nodeMode: string): boolean;
+export declare function wireStreams(app: Server, vite: ViteTarget, router: StreamRouter): void;

package/build/devserver/stream/wire.js

@@ -0,0 +1,33 @@
+import { pipeToVite } from '../http/proxy.js';
+export function streamEmulationEnabled(nodeMode) {
+    return nodeMode === 'regional' || nodeMode === 'continental' || nodeMode === 'all';
+}
+export function wireStreams(app, vite, router) {
+    app.upgrade('/*', (request, response) => {
+        const def = router.matchRoute(request.path);
+        if (def !== null) {
+            response.upgrade({
+                kind: 'stream',
+                route: def.route,
+                url: request.url,
+                authority: request.headers['host'] ?? '',
+            });
+        }
+        else {
+            response.upgrade({
+                kind: 'vite',
+                url: request.url,
+                protocol: request.headers['sec-websocket-protocol'] ?? '',
+            });
+        }
+    });
+    app.ws('/*', { message_type: 'Buffer', idle_timeout: 0, max_payload_length: 16 * 1024 * 1024 }, (ws) => {
+        const ctx = ws.context;
+        if (ctx.kind === 'stream') {
+            router.onUpgrade(ws, ws.context);
+        }
+        else {
+            pipeToVite(ws, vite, ws.context);
+        }
+    });
+}

package/build/devserver/stream/ws.d.ts

@@ -0,0 +1,18 @@
+import type { StreamDevHost } from './manager.js';
+export interface StreamWsTransport {
+    send(frame: Buffer): void;
+    close(code: number): void;
+}
+export declare class StreamWsSession {
+    private readonly host;
+    private readonly connId;
+    private readonly authority;
+    private readonly path;
+    private readonly transport;
+    private open;
+    constructor(host: StreamDevHost, connId: string, authority: string, path: string, transport: StreamWsTransport);
+    get isOpen(): boolean;
+    onOpen(): boolean;
+    onMessage(inbound: Buffer): void;
+    onClose(): void;
+}

package/build/devserver/stream/ws.js

@@ -0,0 +1,46 @@
+export class StreamWsSession {
+    host;
+    connId;
+    authority;
+    path;
+    transport;
+    open = false;
+    constructor(host, connId, authority, path, transport) {
+        this.host = host;
+        this.connId = connId;
+        this.authority = authority;
+        this.path = path;
+        this.transport = transport;
+    }
+    get isOpen() {
+        return this.open;
+    }
+    onOpen() {
+        const up = this.host.acceptUpgrade(this.connId, this.authority, this.path);
+        if (up.kind === 'rejected') {
+            this.transport.close(up.code);
+            return false;
+        }
+        this.open = true;
+        return true;
+    }
+    onMessage(inbound) {
+        if (!this.open)
+            return;
+        const r = this.host.dispatch(this.connId, inbound);
+        if (r.kind === 'reply') {
+            for (const frame of r.frames)
+                this.transport.send(frame);
+        }
+        else if (r.kind === 'close') {
+            this.open = false;
+            this.transport.close(r.code);
+        }
+    }
+    onClose() {
+        if (!this.open && !this.host.has(this.connId))
+            return;
+        this.open = false;
+        this.host.close(this.connId);
+    }
+}

package/docs/cli.md

@@ -8,7 +8,9 @@
 - `toiljs build`, production build. With a `toilconfig.json` it builds the server (toilscript,
   regenerating `shared/server.ts`) first, then the client → `build/client`. `--server` builds
   only the server. Every `server/` file declaring a surface (`@data`/`@rest`/...) is compiled.
-- `toiljs start`, self-host the built app (hyper-express) with a `/_toil` WebSocket channel.
+- `toiljs start`, self-host the built app with production hyper-express/uWS static workers,
+  SSR/wasm dispatch, daemon support, and a `/_toil` WebSocket channel. Use `--threads <n>`
+  (or `server.threads`) to set the worker count; `1` disables the pool.
 - `toiljs configure`, toggle styling features on an existing project (see [styling.md](./styling.md)).
 - `toiljs doctor`, diagnose project setup (`--json` for CI). `--fix` auto-wires the typed-RPC
   setup (build scripts, tsconfig `shared` + alias, `.gitignore`, toilscript version, and the

package/docs/getting-started.md

@@ -95,13 +95,13 @@ store reached through a host binding.
 
 The `toiljs` CLI drives both halves:
 
-| Command | What it does |
-| --- | --- |
-| `toiljs create [name]` | Scaffold a new app (templates, styling, options). |
-| `toiljs dev` | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |
-| `toiljs build` | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only). |
-| `toiljs start` | Self-host a built app. Flags: `--root`, `--port`, `--host`. |
-| `toiljs doctor` | Diagnose setup/deps (`--json`, `--fix`). |
+| Command                | What it does                                                                                                                                                                                  |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `toiljs create [name]` | Scaffold a new app (templates, styling, options).                                                                                                                                             |
+| `toiljs dev`           | Dev server with hot reload: watches `server/`, rebuilds the wasm via toilscript, regenerates `shared/server.ts`, and runs Vite for the client. Flags: `--root <dir>`, `--port <n>`, `--host`. |
+| `toiljs build`         | Production build: server wasm first (so `shared/server.ts` is fresh), then the Vite client + static prerender. Flags: `--root <dir>`, `--server` (server only).                               |
+| `toiljs start`         | Self-host a built app with production uWS/static workers, no Vite. Flags: `--root`, `--port`, `--host`, `--threads`.                                                                          |
+| `toiljs doctor`        | Diagnose setup/deps (`--json`, `--fix`).                                                                                                                                                      |
 
 In dev, requests whose method matches a dispatchable verb go into the wasm
 first; if the guest reports "no route matched" (the `x-toil-unhandled` marker)

package/examples/basic/server/routes/Guestbook.ts

@@ -13,6 +13,12 @@ import { NewMessage } from '../models/NewMessage';
  *
  *   await Server.REST.guestbook.sign({ body: new NewMessage('Ada', 'hi!') });
  *   const book = await Server.REST.guestbook.list(); // { total, entries: [...] }
+ *
+ * Reading the newest entries is a SCAN (`events.latest`), which is barred in a
+ * request handler (a `@get` runs as a Query, a `@post` as an Action) because a
+ * scan can fan out across unbounded rows. So a `@derive` does the scan off the
+ * request path and `publish`es a materialized `GuestbookView`; the GET then
+ * serves that view with a single non-scan `view.get`.
  */
 
 // The guestbook is one global stream; a single fixed key addresses it.
@@ -28,33 +34,52 @@ class GuestKey {
 class GuestbookDb {
     @collection static entries: Events<GuestKey, GuestEntry>;
     @collection static totals: Counter<GuestKey>;
-}
+    // The materialized snapshot the GET serves: total + newest entries.
+    @collection static book: View<GuestKey, GuestbookView>;
 
-/** The current total + the 10 newest entries. */
-function snapshot(): GuestbookView {
-    const key = new GuestKey('main');
-    const view = new GuestbookView();
-    view.total = GuestbookDb.totals.get(key);
-    view.entries = GuestbookDb.entries.latest(key, 10);
-    return view;
+    /**
+     * Recompute the materialized view from the source of truth (the event log +
+     * the counter). The runtime runs this under FunctionKind=Derive after a
+     * signature is appended (and rebuilds it when a box first loads), so the
+     * scan (`events.latest`) and the `view.publish` - both barred in a request
+     * handler - are allowed here. This is also where `GuestEntry`'s `@migrate`
+     * fires: `events.latest` decodes each stored event at ITS schema version, so
+     * an old pre-`at` entry is migrated as the view is rebuilt.
+     */
+    @derive
+    recompute(): void {
+        const key = new GuestKey('main');
+        const view = new GuestbookView();
+        view.total = GuestbookDb.totals.get(key);
+        view.entries = GuestbookDb.entries.latest(key, 10);
+        GuestbookDb.book.publish(key, view);
+    }
 }
 
 @rest('guestbook')
 class Guestbook {
-    /** `GET /guestbook` - the running total + the most recent signatures. */
+    /** `GET /guestbook` - the running total + the most recent signatures, served
+     *  from the materialized view (a non-scan `view.get`). */
     @get('/')
     public list(): GuestbookView {
-        return snapshot();
+        const key = new GuestKey('main');
+        const view = GuestbookDb.book.get(key);
+        if (view == null) return new GuestbookView();
+        return view;
     }
 
-    /** `POST /guestbook` - append a signature (PERSISTED) and return the
-     *  updated book. Sign twice and the total keeps climbing across requests. */
+    /** `POST /guestbook` - append a signature (PERSISTED) and acknowledge with
+     *  the new running total. The entries list is served by the GET above from
+     *  the view the `@derive` republishes right after this action. Sign twice
+     *  and the total keeps climbing across requests. */
     @post('/')
     public sign(input: NewMessage): GuestbookView {
         const key = new GuestKey('main');
         const at = <u64>(Date.now() / 1000);
         GuestbookDb.entries.append(key, new GuestEntry(input.author, input.message, at));
         GuestbookDb.totals.add(key, 1);
-        return snapshot();
+        const view = new GuestbookView();
+        view.total = GuestbookDb.totals.get(key); // Counter get: non-scan, action-legal
+        return view;
     }
 }