toiljs 0.0.67 → 0.0.69

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/derive.md

@@ -0,0 +1,159 @@
+# Derive (materialized views)
+
+`@derive` precomputes a read-optimized **view** from your data so reads stay
+fast and never scan. A request handler (`@get` runs as a *query*, `@post`/`@put`/
+`@delete` as an *action*) is not allowed to scan, reading "the latest N events"
+or "every member of a set" could fan out across unbounded rows, so those scans
+are barred on the request path. A `@derive` does the scan **off** the request
+path: it folds your event log / counters into a `View`, and your route serves
+that view with a single keyed read.
+
+```ts
+@database
+class GuestbookDb {
+  @collection static entries: Events<GuestKey, GuestEntry>;
+  @collection static totals: Counter<GuestKey>;
+  @collection static book: View<GuestKey, GuestbookView>;
+
+  // Recompute the view from the sources. Runs after a signature is written
+  // (and when a box first loads). A derive MAY scan + publish; a route may not.
+  @derive
+  recompute(): void {
+    const key = new GuestKey('main');
+    const view = new GuestbookView();
+    view.total = GuestbookDb.totals.get(key);      // counter read
+    view.entries = GuestbookDb.entries.latest(key, 10); // scan, allowed here
+    GuestbookDb.book.publish(key, view);           // publish the materialized view
+  }
+}
+```
+
+## Why a derive
+
+ToilDB gates every data op by the *function kind* it runs under:
+
+- **query** (`@get`/`@head`) and **action** (`@post`/`@put`/`@patch`/`@delete`)
+  may do keyed reads and (actions only) writes, but **not scans**
+  (`events.latest`, `membership.list`).
+- **derive** may do everything a read can, **plus** scans, plus
+  `view.publish`/`append`/`counter.add`.
+
+So if a page needs "the 10 newest entries" or "the leaderboard", you cannot read
+that directly in the `@get`. Instead a `@derive` builds it once into a `View`,
+and the `@get` reads the view by key, which is not a scan.
+
+## Declaring a derive
+
+A derive is a method on your `@database` class, alongside the collections it
+reads and the `View` it writes:
+
+```ts
+@database
+class MyDb {
+  @collection static events: Events<Key, Fact>;   // a source
+  @collection static home: View<Key, HomePage>;    // the materialized view
+
+  @derive
+  rebuild(): void {
+    // read sources, build the value, publish it
+  }
+}
+```
+
+Rules:
+
+- A `@derive` method takes **no arguments and returns `void`**.
+- A `@database` may declare **multiple** `@derive` methods; each is run
+  independently.
+- The view value (`HomePage` above) and the key are ordinary `@data` types, so
+  they round-trip through the codec like any other stored value.
+
+## `View<K, V>`
+
+A `View` is a published, read-optimized projection. Its API:
+
+```ts
+view.get(key)       // V | null   - the published view, or null if none yet
+view.require(key)   // V          - like get, but traps if nothing is published
+view.publish(key, value) // void  - overwrite the view (derive/job only)
+```
+
+`publish` is only allowed from a `@derive` (or a `@job`); the host assigns the
+version so a later publish always supersedes an earlier one. `get`/`require` are
+plain keyed reads, allowed from any handler, including a `@get` route.
+
+## When derives run
+
+You never call a derive yourself. The runtime runs it for you:
+
+- **After a write to a source.** When a request writes one of a database's
+  source collections (an `events.append`/`append_once`, a `counter.add`, or a
+  record `create`/`patch`), that database's derives run right after the response
+  is produced, so the view reflects the new data on the next read. Many writes to
+  one database in a single request coalesce into one recompute.
+- **On box load.** When a server box starts or hot-reloads (or the underlying
+  source data changed out of band), the views are rebuilt from their sources
+  before the first read is served. This is also where a value type's `@migrate`
+  runs against old stored events, as the derive re-reads and republishes them.
+
+A derive's own writes (its `view.publish`) never re-trigger it.
+
+The same code runs under `toiljs dev` (the in-process emulator) and on the
+production edge, no flags or wiring to change.
+
+## Reading a view from a route
+
+The route just reads the view by key, which is a non-scan read and so is legal in
+a `@get`:
+
+```ts
+@rest('guestbook')
+class Guestbook {
+  @get('/')
+  list(): GuestbookView {
+    const key = new GuestKey('main');
+    const view = GuestbookDb.book.get(key);
+    return view == null ? new GuestbookView() : view; // empty until first publish
+  }
+
+  @post('/')
+  sign(input: NewMessage): GuestbookView {
+    const key = new GuestKey('main');
+    GuestbookDb.entries.append(key, new GuestEntry(input.author, input.message, 0));
+    GuestbookDb.totals.add(key, 1);
+    // The @derive republishes `book` right after this action returns, so the
+    // entries list is served by GET. The action just acks with the new total
+    // (a counter read is allowed here; a scan is not).
+    const view = new GuestbookView();
+    view.total = GuestbookDb.totals.get(key);
+    return view;
+  }
+}
+```
+
+## How it fits together (the guestbook)
+
+The `examples/basic` guestbook is the end-to-end demo:
+
+1. `POST /guestbook` (an action) appends the signature to an `Events` stream and
+   bumps a `Counter`. It returns the running total, but it does **not** read the
+   entry list (that would be a scan).
+2. The runtime then runs `@derive recompute()` under the derive kind: it scans
+   `entries.latest(...)`, reads the `totals` counter, and `publish`es a fresh
+   `GuestbookView`.
+3. `GET /guestbook` (a query) reads `book.get(...)`, a single keyed read, and
+   returns the precomputed total + newest entries.
+
+Sign twice and the total climbs across requests, because the data lives in
+ToilDB (and its view), not in module memory.
+
+## Notes
+
+- A derive **recomputes** the view from whatever its method reads (here, the
+  latest 10 events). It is a fresh recompute on each trigger, so it suits views
+  built from a bounded read (latest N, a counter total, a small set). Folding an
+  unbounded full event log incrementally is a separate, more advanced pattern.
+- Because publishes are last-writer-wins and a derive recomputes from the source
+  of truth, a view always converges to a correct snapshot of its sources.
+- See also: [`data.md`](data.md) for `@data` value types, and the ToilDB host
+  ABI for the exact `derive_run` / `toildb.derives` contract.

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/docs/index.md

@@ -27,4 +27,4 @@ toilscript-to-WebAssembly server target.
 
 See [routing.md](./routing.md), [client.md](./client.md), [styling.md](./styling.md),
 [server.md](./server.md), [ssr.md](./ssr.md), [rpc.md](./rpc.md), [tiers.md](./tiers.md),
-[streams.md](./streams.md), [daemon.md](./daemon.md), [cli.md](./cli.md).
+[streams.md](./streams.md), [daemon.md](./daemon.md), [derive.md](./derive.md), [cli.md](./cli.md).

package/docs/streams.md

@@ -117,30 +117,62 @@ build/server/release-cold.wasm     # L4 daemon     (exports: daemon_start, sched
 
 See [Tiers](./tiers.md) for how the three artifacts map to the deployment tiers.
 
-## What runs today
+## Reading and replying to messages
 
-The stream lifecycle hooks (`@connect` / `@message` / `@close` / `@disconnect`)
-run **today**, and this proves a resident box keeps state across events - that is
-exactly what the `Echo` example demonstrates by counting frames.
-
-Reading the inbound frame **bytes** and replying is the **next increment**, not
-yet available. That bridge is the `StreamPacket` / `StreamOutbound` API and the
-typed `Server.STREAM.echo.connect()` client. The intended shape, once it lands:
+`@message` receives the inbound frame as a `StreamPacket` and returns a
+`StreamOutbound`. `StreamPacket.bytes()` is the raw frame payload;
+`StreamOutbound.reply(bytes)` stages one frame back to the client (return an empty
+`StreamOutbound` to accept the frame without replying). The same resident box
+handles every frame, so state on its fields persists across messages.
 
 ```ts
-@message reply(packet: StreamPacket): StreamOutbound {
+@message
+reply(packet: StreamPacket): StreamOutbound {
   return StreamOutbound.reply(packet.bytes());   // echo the bytes back
 }
 ```
 
+## Typed messages
+
+By default a `@message` payload is **raw bytes**. Opt into a decoded `@data` value
+with `@stream({ message: T })`: the `@message` hook then receives the named `@data`
+class, decoded from the frame for you. The reply stays raw (`StreamOutbound`).
+
+```ts
+@data
+class ChatMsg { text: string = ''; }
+
+@stream({ message: ChatMsg })
+class Chat {
+  @message
+  onMessage(msg: ChatMsg): StreamOutbound {       // decoded @data, not raw bytes
+    return StreamOutbound.reply(new TextEncoder().encode(msg.text));
+  }
+}
+```
+
+## The client
+
+A `@stream` class is reachable from the browser as `Server.Stream.<ClassName>`. The
+typed client is generated into `shared/server.ts` (the same place `Server.REST`
+lands), so no manual wiring is needed. `connect()` opens a WebSocket to the class's
+route and resolves a channel:
+
 ```ts
-const stream = await Server.STREAM.echo.connect();
-stream.send(new TextEncoder().encode('hello'));
+const chat = await Server.Stream.Chat.connect();
+chat.onMessage((bytes) => { /* a reply frame, always raw bytes */ });
+chat.send(new ChatMsg('hello'));   // a typed stream: send() encodes the @data for you
+chat.onClose((code) => { /* a 0x02xx stream close code */ });
+chat.close();
 ```
 
-Until then, the hooks run on the connection lifecycle and you observe state
-through fields, as `Echo` does. See the comments in
-`examples/streams/server/streams/Echo.ts` for the authoritative note.
+- The channel key is the **class name** (`Server.Stream.Chat`); it connects to the
+  class's mount route (`/Chat`).
+- A **raw** `@stream` channel sends `Uint8Array`; a **typed** `@stream({ message: T })`
+  channel sends the `@data` class and encodes it on the wire for you.
+- The inbound reply is **always raw bytes** - the server's `StreamOutbound` is raw.
+- `connect()` resolves once the upgrade completes; a `@connect` reject (or any
+  later server close) surfaces through `onClose(code)`.
 
 ---
 

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;
     }
 }