toiljs 0.0.59 → 0.0.60

package/src/devserver/server.ts

@@ -0,0 +1,292 @@
+/**
+ * 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 fs from 'node:fs';
+import path from 'node:path';
+
+import { type Request, type Response, Server } from '@dacely/hyper-express';
+import pc from 'picocolors';
+
+import type { EmailBackendConfig } from 'toiljs/shared';
+
+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';
+
+const DEFAULT_MAX_BODY_LENGTH = 1024 * 1024 * 8;
+
+/**
+ * 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/'];
+
+/** 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). */
+    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;
+    /** 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;
+}
+
+/** 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));
+}
+
+/** 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));
+}
+
+/**
+ * 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);
+
+    // 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({
+        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);
+
+    app.any('/*', async (request: Request, response: Response) => {
+        response.removeHeader('uWebSockets');
+
+        const dispatchable =
+            !isViteInternal(request.url) && METHOD_CODES[request.method] !== undefined;
+        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');
+                return;
+            }
+        }
+
+        await proxyToVite(request, response, options.vite);
+    });
+
+    await app.listen(options.port, host);
+
+    return {
+        port: options.port,
+        host,
+        close: async (): Promise<void> => {
+            await app.shutdown();
+        },
+    };
+}

package/test/devserver-database.test.ts

@@ -1,7 +1,18 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
 import { afterEach, describe, expect, it } from 'vitest';
 
-import { __resetDbForTests, buildDatabaseImports, freshDbState } from '../src/devserver/database.js';
-import type { MemoryRef } from '../src/devserver/host.js';
+import {
+    __resetDbForTests,
+    __setDbCatalogForTests,
+    buildDatabaseImports,
+    configureDbPersistence,
+    freshDbState,
+    persistDb,
+} from '../src/devserver/db/index.js';
+import type { MemoryRef } from '../src/devserver/runtime/host.js';
 
 function setup() {
     const memory = new WebAssembly.Memory({ initial: 1 });
@@ -37,7 +48,7 @@ describe('toildb dev emulator (record family)', () => {
         const [vPtr, vLen] = put(buf, 48, 'hello');
 
         expect(imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0)).toBe(0);
-        expect(imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0)).toBe(-1000); // AlreadyExists
+        expect(imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0)).toBe(-1003); // AlreadyExists
         expect(imports['data.exists'](h, kPtr, kLen)).toBe(1);
 
         expect(imports['data.get'](h, kPtr, kLen)).toBe(5);
@@ -64,7 +75,7 @@ describe('toildb dev emulator (record family)', () => {
         const h = resolve(imports, buf, 'App/users');
         const [kPtr, kLen] = put(buf, 32, 'ghost');
         const [pPtr, pLen] = put(buf, 48, 'x');
-        expect(imports['data.patch'](h, kPtr, kLen, pPtr, pLen, 0)).toBe(-1000);
+        expect(imports['data.patch'](h, kPtr, kLen, pPtr, pLen, 0)).toBe(-2); // NotFound -> ABSENT
     });
 
     it('consume-once get_delete deletes exactly once', () => {
@@ -124,7 +135,7 @@ describe('toildb dev emulator (record family)', () => {
         const [u2Ptr, u2Len] = put(buf, 64, 'user_2');
         imports['data.unique_claim'](h, kPtr, kLen, u1Ptr, u1Len, 0);
 
-        expect(imports['data.unique_release'](h, kPtr, kLen, u2Ptr, u2Len, 0)).toBe(-1000); // not owner
+        expect(imports['data.unique_release'](h, kPtr, kLen, u2Ptr, u2Len, 0)).toBe(-1004); // not owner
         expect(imports['data.unique_release'](h, kPtr, kLen, u1Ptr, u1Len, 0)).toBe(0); // owner releases
         expect(imports['data.unique_lookup'](h, kPtr, kLen)).toBe(-2); // gone
     });
@@ -162,6 +173,7 @@ describe('toildb dev emulator (record family)', () => {
                 got.push(null);
                 continue;
             }
+            p += 4; // per-item schema_version (0 in dev)
             const len = buf.readUInt32LE(p);
             p += 4;
             got.push(buf.toString('utf8', p, p + len));
@@ -194,6 +206,7 @@ describe('toildb dev emulator (record family)', () => {
         expect(count).toBe(2);
         const out: string[] = [];
         for (let i = 0; i < count; i++) {
+            off += 4; // per-item schema_version (0 in dev)
             const len = buf.readUInt32LE(off);
             off += 4;
             out.push(buf.toString('utf8', off, off + len));
@@ -274,6 +287,7 @@ describe('toildb dev emulator (record family)', () => {
         expect(count).toBe(2);
         const out: string[] = [];
         for (let i = 0; i < count; i++) {
+            off += 4; // per-item schema_version (0 in dev)
             const len = buf.readUInt32LE(off);
             off += 4;
             out.push(buf.toString('utf8', off, off + len));
@@ -301,6 +315,36 @@ describe('toildb dev emulator (record family)', () => {
         // the same logical key in another collection is absent.
         expect(imports['data.get'](posts, kPtr, kLen)).toBe(-2);
     });
+
+    it('append_once dedups on eventId; enqueue replaces an existing record', () => {
+        const { imports, buf } = setup();
+        const feed = resolve(imports, buf, 'App/feed');
+        const [kPtr, kLen] = put(buf, 32, 'room1');
+        const [idPtr, idLen] = put(buf, 64, 'evt-1');
+        const [evPtr, evLen] = put(buf, 96, 'hello');
+        // first appendOnce appends (1); the same id is a no-op (0); a new id appends (1).
+        expect(imports['data.append_once'](feed, kPtr, kLen, idPtr, idLen, evPtr, evLen)).toBe(1);
+        expect(imports['data.append_once'](feed, kPtr, kLen, idPtr, idLen, evPtr, evLen)).toBe(0);
+        const [id2P, id2L] = put(buf, 128, 'evt-2');
+        expect(imports['data.append_once'](feed, kPtr, kLen, id2P, id2L, evPtr, evLen)).toBe(1);
+        // latest frames exactly 2 events (the duplicate did not double-append).
+        const total = imports['data.latest'](feed, kPtr, kLen, 10);
+        expect(total).toBeGreaterThan(0);
+        imports['data.take_result'](512, total);
+        expect(buf.readUInt32LE(512)).toBe(2);
+
+        // enqueue: absent -> ABSENT (-2); after create -> replaces (0); get sees the new value.
+        const docs = resolve(imports, buf, 'App/docs');
+        const [dkP, dkL] = put(buf, 160, 'doc1');
+        const [v1P, v1L] = put(buf, 192, 'AAAA');
+        expect(imports['data.enqueue'](docs, dkP, dkL, v1P, v1L, 0)).toBe(-2);
+        expect(imports['data.create'](docs, dkP, dkL, v1P, v1L, 0)).toBe(0);
+        const [v2P, v2L] = put(buf, 224, 'BBBB');
+        expect(imports['data.enqueue'](docs, dkP, dkL, v2P, v2L, 0)).toBe(0);
+        expect(imports['data.get'](docs, dkP, dkL)).toBe(4);
+        imports['data.take_result'](256, 4);
+        expect(buf.toString('utf8', 256, 260)).toBe('BBBB');
+    });
 });
 
 type Imports = Record<string, (...args: number[]) => number>;
@@ -343,9 +387,9 @@ describe('toildb dev emulator (capacity family)', () => {
         const id2 = Number(buf.readBigUInt64LE(512));
         expect(imports['data.capacity_confirm'](h, kPtr, kLen, id2, 0)).toBe(1);
         expect(avail(imports, buf, h, kPtr, kLen)).toBe(6n);
-        // a confirmed hold cannot be cancelled nor re-confirmed.
+        // a confirmed sale cannot be cancelled (0); re-confirm is idempotent (1).
         expect(imports['data.capacity_cancel'](h, kPtr, kLen, id2, 0)).toBe(0);
-        expect(imports['data.capacity_confirm'](h, kPtr, kLen, id2, 0)).toBe(0);
+        expect(imports['data.capacity_confirm'](h, kPtr, kLen, id2, 0)).toBe(1);
     });
 
     it('never oversells (a reserve beyond available is refused)', () => {
@@ -357,8 +401,69 @@ describe('toildb dev emulator (capacity family)', () => {
         // a hold for all 5 succeeds; a further hold for 1 is refused (-2 -> guest 0).
         expect(imports['data.capacity_reserve'](h, kPtr, kLen, 5, 60000, 0)).toBe(8);
         expect(imports['data.capacity_reserve'](h, kPtr, kLen, 1, 60000, 0)).toBe(-2);
-        // a non-positive amount is refused, and an invalid handle is rejected.
-        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 0, 60000, 0)).toBe(-2);
+        // a non-positive amount is a typed error (BadAmount), invalid handle rejected.
+        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 0, 60000, 0)).toBe(-1006);
         expect(imports['data.capacity_available'](999, kPtr, kLen)).toBe(-1001);
     });
 });
+
+describe('toildb dev emulator (migration + persistence)', () => {
+    const rsv = (imports: Imports): bigint =>
+        (imports['data.result_schema_version'] as () => bigint)();
+
+    it('stamps writes with the catalog schema_version and surfaces it on read', () => {
+        const { imports, buf } = setup();
+        __setDbCatalogForTests({ 'App/users': 0x1234 });
+        const h = resolve(imports, buf, 'App/users');
+        const [kPtr, kLen] = put(buf, 32, 'u1');
+        const [vPtr, vLen] = put(buf, 64, 'data');
+        imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0);
+        expect(imports['data.get'](h, kPtr, kLen)).toBe(4);
+        expect(rsv(imports)).toBe(0x1234n); // the woven decoder dispatches on this
+    });
+
+    it('an evolved @data type leaves old rows stamped with the OLD version', () => {
+        const { imports, buf } = setup();
+        __setDbCatalogForTests({ 'App/users': 100 }); // version A
+        const h = resolve(imports, buf, 'App/users');
+        const [kPtr, kLen] = put(buf, 32, 'u1');
+        const [vPtr, vLen] = put(buf, 64, 'old');
+        imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0);
+        // the @data type evolves + the wasm rebuilds -> the catalog version changes.
+        __setDbCatalogForTests({ 'App/users': 200 }); // version B
+        // a read of the existing row still reports the OLD version -> guest migrates it.
+        imports['data.get'](h, kPtr, kLen);
+        expect(rsv(imports)).toBe(100n);
+        // a NEW write stamps the current version.
+        const [k2, kl2] = put(buf, 96, 'u2');
+        imports['data.create'](h, k2, kl2, vPtr, vLen, 0);
+        imports['data.get'](h, k2, kl2);
+        expect(rsv(imports)).toBe(200n);
+    });
+
+    it('persists data + versions to disk and reloads them', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'toildb-'));
+        const file = join(dir, 'devdata.json');
+        try {
+            const a = setup();
+            __setDbCatalogForTests({ 'App/users': 777 });
+            configureDbPersistence(file);
+            const h = resolve(a.imports, a.buf, 'App/users');
+            const [kPtr, kLen] = put(a.buf, 32, 'u1');
+            const [vPtr, vLen] = put(a.buf, 64, 'persisted');
+            a.imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0);
+            persistDb();
+
+            // simulate a restart: wipe memory + catalog, then reload from disk.
+            __resetDbForTests();
+            configureDbPersistence(file);
+            const b = setup();
+            const h2 = resolve(b.imports, b.buf, 'App/users');
+            const [k2, kl2] = put(b.buf, 32, 'u1');
+            expect(b.imports['data.get'](h2, k2, kl2)).toBe(9); // "persisted" survived restart
+            expect(rsv(b.imports)).toBe(777n); // and so did its schema_version stamp
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+});

package/test/devserver-pqauth.test.ts

@@ -10,7 +10,7 @@ import { describe, expect, it } from 'vitest';
 
 import { ml_kem768 } from '@dacely/noble-post-quantum/ml-kem.js';
 
-import { buildCryptoImports, freshCryptoState } from '../src/devserver/crypto.js';
+import { buildCryptoImports, freshCryptoState } from '../src/devserver/runtime/crypto.js';
 
 type Ref = { memory: WebAssembly.Memory | null };
 

package/test/devserver-secrets.test.ts

@@ -1,6 +1,10 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
-import { buildHostImports, freshDispatchState, type MemoryRef } from '../src/devserver/host.js';
+import {
+    buildHostImports,
+    freshDispatchState,
+    type MemoryRef,
+} from '../src/devserver/runtime/host.js';
 
 /**
  * The dev host warns (once) when the guest reads a framework auth secret that is unset, since the

package/test/doctor.test.ts

@@ -6,6 +6,7 @@ import {
     checkDevScripts,
     checkDuplicatePatterns,
     type CheckGroup,
+    checkMigrationsDir,
     checkMountSlots,
     checkNode,
     checkPeer,
@@ -219,6 +220,18 @@ describe('checkAuthSecrets', () => {
     });
 });
 
+describe('checkMigrationsDir', () => {
+    it('passes when the server/migrations/ folder exists', () => {
+        expect(checkMigrationsDir(true).status).toBe('pass');
+    });
+    it('warns (not fails) when missing, naming the convention and the update fix', () => {
+        const c = checkMigrationsDir(false);
+        expect(c.status).toBe('warn');
+        expect(c.detail).toContain('migration.ts');
+        expect(c.fix).toContain('toiljs update');
+    });
+});
+
 describe('summarize', () => {
     it('tallies pass/warn/fail across groups', () => {
         const groups: CheckGroup[] = [

package/test/example-guestbook.test.ts

@@ -7,13 +7,14 @@
  * request". Skips until the example server wasm is built (`npm run build:server`).
  */
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { describe, expect, it, beforeEach } from 'vitest';
 
 import { WasmServerModule } from '../src/devserver/index.js';
-import { __resetDbForTests } from '../src/devserver/database.js';
+import { __resetDbForTests, configureDbPersistence } from '../src/devserver/db/index.js';
 
 const EXAMPLE_WASM = path.resolve(
     path.dirname(fileURLToPath(import.meta.url)),
@@ -75,4 +76,45 @@ describe.skipIf(!haveWasm)('guestbook demo: ToilDB events + counter persist acro
         // A read-only GET on yet another instance sees the same persisted state.
         expect(json(list(load())).total).toBe('2');
     });
+
+    // End-to-end proof that the `server/migrations/GuestEntry.migration.ts` demo
+    // actually RUNS: write an entry under the current shape, downgrade it on disk to
+    // the original pre-`at` `GuestEntryV1` layout (drop the trailing u64 + re-stamp
+    // with v1's schema_version), then `list()` and confirm the woven decoder ran the
+    // `@migrate` - the entry comes back with the new `at` field defaulted to 0.
+    it('migrates an on-disk pre-`at` entry on read (the GuestEntry.migration demo fires)', () => {
+        const GUEST_ENTRY_V1_VERSION = 631968986; // layoutHash({author:string, message:string})
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gb-mig-'));
+        const file = path.join(dir, 'devdata.json');
+        try {
+            // 1. sign under the CURRENT shape (author, message, at); persistence flushes it.
+            configureDbPersistence(file);
+            expect(sign(load(), 'Ada', 'from the old days').status).toBe(200);
+
+            // 2. downgrade that event on disk to the v1 shape: GuestEntry encodes
+            //    author + message + at(u64), so dropping the trailing 8 bytes yields a
+            //    valid GuestEntryV1; re-stamp it with v1's schema_version.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const snap: any = JSON.parse(fs.readFileSync(file, 'utf8'));
+            const evKey = Object.keys(snap.events)[0];
+            const buf = Buffer.from(snap.events[evKey][0].v, 'base64');
+            snap.events[evKey][0] = {
+                v: buf.subarray(0, buf.length - 8).toString('base64'),
+                sv: GUEST_ENTRY_V1_VERSION,
+            };
+            fs.writeFileSync(file, JSON.stringify(snap));
+
+            // 3. reload + list: the read surfaces v1's version, so the guest's woven
+            //    decoder runs the @migrate, copying author/message and defaulting at=0.
+            __resetDbForTests();
+            configureDbPersistence(file);
+            const v = json(list(load()));
+            expect(v.entries.length).toBe(1);
+            expect(v.entries[0].author).toBe('Ada');
+            expect(v.entries[0].message).toBe('from the old days');
+            expect(String(v.entries[0].at)).toBe('0'); // the migrated-in field
+        } finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+    });
 });

package/test/pqauth-e2e.test.ts

@@ -20,7 +20,7 @@ import { describe, expect, it, beforeEach, afterEach } from 'vitest';
 import { ristretto255_oprf } from '@noble/curves/ed25519.js';
 
 import { WasmServerModule } from '../src/devserver/index.js';
-import { __resetDbForTests } from '../src/devserver/database.js';
+import { __resetDbForTests } from '../src/devserver/db/index.js';
 import { Auth } from '../src/client/auth.js';
 import { DataReader, DataWriter } from '../src/io/codec.js';
 

package/build/devserver/database.d.ts

@@ -1,8 +0,0 @@
-import type { MemoryRef } from './host.js';
-export interface DbDevState {
-    handles: string[];
-    lastResult: Buffer | null;
-}
-export declare function freshDbState(): DbDevState;
-export declare function buildDatabaseImports(ref: MemoryRef, db: DbDevState): Record<string, (...args: number[]) => number | bigint>;
-export declare function __resetDbForTests(): void;