toiljs 0.0.60 → 0.0.62

package/test/devserver-database.test.ts

@@ -5,16 +5,34 @@ import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
 
 import {
+    CollectionFamily,
+    DbFunctionKind,
     __resetDbForTests,
     __setDbCatalogForTests,
     buildDatabaseImports,
     configureDbPersistence,
     freshDbState,
     persistDb,
+    setDbCatalog,
 } from '../src/devserver/db/index.js';
+import { parseRouteKinds, routeKindForRequest } from '../src/devserver/db/routeKinds.js';
 import type { MemoryRef } from '../src/devserver/runtime/host.js';
 
-function setup() {
+const DEFAULT_CATALOG = {
+    'App/users': { family: CollectionFamily.Record },
+    'App/posts': { family: CollectionFamily.Record },
+    'App/docs': { family: CollectionFamily.Record },
+    'App/challenges': { family: CollectionFamily.Record },
+    'App/pages': { family: CollectionFamily.View },
+    'App/feed': { family: CollectionFamily.Events },
+    'App/likes': { family: CollectionFamily.Counter },
+    'App/rooms': { family: CollectionFamily.Membership },
+    'App/usernames': { family: CollectionFamily.Unique },
+    'App/seats': { family: CollectionFamily.Capacity },
+    'App/tickets': { family: CollectionFamily.Capacity },
+};
+
+function setupRaw() {
     const memory = new WebAssembly.Memory({ initial: 1 });
     const ref: MemoryRef = { memory };
     const db = freshDbState();
@@ -23,6 +41,11 @@ function setup() {
     return { ref, db, imports, buf };
 }
 
+function setup() {
+    __setDbCatalogForTests(DEFAULT_CATALOG);
+    return setupRaw();
+}
+
 /** Write bytes at `offset`, returning the `[ptr, len]` pair the imports expect. */
 function put(buf: Buffer, offset: number, data: string): [number, number] {
     const b = Buffer.from(data);
@@ -30,17 +53,213 @@ function put(buf: Buffer, offset: number, data: string): [number, number] {
     return [offset, b.length];
 }
 
-function resolve(imports: Record<string, (...a: number[]) => number>, buf: Buffer, name: string): number {
+function resolve(
+    imports: Record<string, (...a: number[]) => number>,
+    buf: Buffer,
+    name: string,
+): number {
     const [p, l] = put(buf, 0, name);
     expect(imports['data.resolve_collection'](p, l, 16)).toBe(0);
     return buf.readUInt32LE(16);
 }
 
+function wasmWithSection(name: string, payload: Uint8Array): Buffer {
+    const nameBytes = Buffer.from(name);
+    const sectionPayload = Buffer.concat([
+        Buffer.from([nameBytes.length]),
+        nameBytes,
+        Buffer.from(payload),
+    ]);
+    return Buffer.concat([
+        Buffer.from([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00, 0x00, sectionPayload.length]),
+        sectionPayload,
+    ]);
+}
+
+function routeKindsSection(routes: readonly (readonly [number, number, string])[]): Buffer {
+    const chunks: Buffer[] = [Buffer.alloc(4)];
+    chunks[0].writeUInt16LE(1, 0);
+    chunks[0].writeUInt16LE(routes.length, 2);
+    for (const [method, kind, pattern] of routes) {
+        const p = Buffer.from(pattern, 'utf8');
+        const header = Buffer.alloc(6);
+        header.writeUInt8(method, 0);
+        header.writeUInt8(kind, 1);
+        header.writeUInt32LE(p.length, 2);
+        chunks.push(header, p);
+    }
+    return Buffer.concat(chunks);
+}
+
+function catalogSectionV2(fillMaxWaitMs: number, fillAllowStale: number): Buffer {
+    const chunks: Buffer[] = [];
+    const u8 = (v: number) => chunks.push(Buffer.from([v & 0xff]));
+    const u16 = (v: number) => {
+        const b = Buffer.alloc(2);
+        b.writeUInt16LE(v);
+        chunks.push(b);
+    };
+    const u32 = (v: number) => {
+        const b = Buffer.alloc(4);
+        b.writeUInt32LE(v >>> 0);
+        chunks.push(b);
+    };
+    const str = (s: string) => {
+        const b = Buffer.from(s, 'utf8');
+        u32(b.length);
+        chunks.push(b);
+    };
+
+    u16(2); // catalog version
+    u16(1); // databases
+    str('App');
+    u16(1); // collections
+    str('users');
+    u8(CollectionFamily.Record);
+    str('UserId');
+    str('User');
+    u32(0xaaaa);
+    u32(0x1234);
+    u32(0); // generation
+    u8(5); // replication = localOnly, accepted by the backend ABI
+    u8(0); // placement = hashKey
+    u32(fillMaxWaitMs);
+    u8(fillAllowStale);
+    u16(0); // fields
+    u16(0); // migrations
+    return Buffer.concat(chunks);
+}
+
 afterEach(() => {
     __resetDbForTests();
 });
 
 describe('toildb dev emulator (record family)', () => {
+    it('parses route-kind metadata and only tightens matching mutating routes', () => {
+        const wasm = wasmWithSection(
+            'toildb.route_kinds',
+            routeKindsSection([
+                [1, 0, '/api/search'],
+                [1, 0, '/api/items/:id'],
+            ]),
+        );
+        const routes = parseRouteKinds(wasm);
+
+        expect(routeKindForRequest(routes, 'POST', '/api/search?q=x')).toBe(DbFunctionKind.Query);
+        expect(routeKindForRequest(routes, 'POST', '/api/items/42')).toBe(DbFunctionKind.Query);
+        expect(routeKindForRequest(routes, 'GET', '/api/search')).toBeNull();
+        expect(routeKindForRequest(routes, 'POST', '/api/items')).toBeNull();
+    });
+
+    it('ignores malformed route-kind metadata like the edge method clamp fallback', () => {
+        expect(
+            parseRouteKinds(wasmWithSection('toildb.route_kinds', Buffer.from([1, 0, 1, 0, 1]))),
+        ).toEqual([]);
+        expect(
+            parseRouteKinds(
+                wasmWithSection('toildb.route_kinds', routeKindsSection([[1, 0, 'relative']])),
+            ),
+        ).toEqual([]);
+        expect(
+            parseRouteKinds(
+                wasmWithSection('toildb.route_kinds', routeKindsSection([[1, 0, '/snowman-☃']])),
+            ),
+        ).toEqual([]);
+
+        const invalidUtf8 = Buffer.concat([
+            Buffer.from([1, 0, 1, 0, 1, 0, 2, 0, 0, 0]),
+            Buffer.from([0xc3, 0x28]),
+        ]);
+        expect(parseRouteKinds(wasmWithSection('toildb.route_kinds', invalidUtf8))).toEqual([]);
+    });
+
+    it('rejects unknown catalog collections instead of minting arbitrary handles', () => {
+        const { imports, buf } = setup();
+        const [p, l] = put(buf, 0, 'App/missing');
+        buf.writeUInt32LE(0xdeadbeef, 16);
+        expect(imports['data.resolve_collection'](p, l, 16)).toBe(-1070);
+        expect(buf.readUInt32LE(16)).toBe(0xdeadbeef);
+    });
+
+    it('rejects a present but malformed catalog section', () => {
+        setDbCatalog(wasmWithSection('toildb.catalog', Buffer.from([0xff, 0x00, 0xde, 0xad])));
+        const { imports, buf } = setupRaw();
+        const [p, l] = put(buf, 0, 'App/users');
+
+        expect(imports['data.resolve_collection'](p, l, 16)).toBe(-1070);
+    });
+
+    it('parses catalog v2 fill policy and backend replication bytes', () => {
+        setDbCatalog(wasmWithSection('toildb.catalog', catalogSectionV2(7, 0)));
+        const { imports, buf, db } = setupRaw();
+        const h = resolve(imports, buf, 'App/users');
+
+        expect(db.handles[h]).toMatchObject({
+            name: 'App/users',
+            family: CollectionFamily.Record,
+            schemaVersion: 0x1234,
+            replication: 5,
+            placement: 0,
+            fillMaxWaitMs: 7,
+            fillAllowStale: false,
+        });
+    });
+
+    it('rejects malformed catalog v2 fill policy', () => {
+        setDbCatalog(wasmWithSection('toildb.catalog', catalogSectionV2(7, 2)));
+        const { imports, buf } = setupRaw();
+        const [p, l] = put(buf, 0, 'App/users');
+
+        expect(imports['data.resolve_collection'](p, l, 16)).toBe(-1070);
+    });
+
+    it('rejects handles used with the wrong collection family', () => {
+        const { imports, buf } = setup();
+        const users = resolve(imports, buf, 'App/users');
+        const likes = resolve(imports, buf, 'App/likes');
+        const [kPtr, kLen] = put(buf, 32, 'k');
+        const [vPtr, vLen] = put(buf, 48, 'v');
+
+        expect(imports['data.counter_add'](users, kPtr, kLen, 1, 0)).toBe(-1010);
+        expect(imports['data.create'](likes, kPtr, kLen, vPtr, vLen, 0)).toBe(-1010);
+    });
+
+    it('query-kind dispatch denies writes and write_allowed is false', () => {
+        const { imports, buf, db } = setup();
+        db.functionKind = DbFunctionKind.Query;
+        const h = resolve(imports, buf, 'App/users');
+        const [kPtr, kLen] = put(buf, 32, 'u1');
+        const [vPtr, vLen] = put(buf, 48, 'hello');
+
+        expect(imports['data.write_allowed']()).toBe(0);
+        expect(imports['data.get'](h, kPtr, kLen)).toBe(-2);
+        expect(imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0)).toBe(-1011);
+    });
+
+    it('query/action dispatch deny scan-class imports', () => {
+        const { imports, buf, db } = setup();
+        const feed = resolve(imports, buf, 'App/feed');
+        const rooms = resolve(imports, buf, 'App/rooms');
+        const [kPtr, kLen] = put(buf, 32, 'room1');
+        const [vPtr, vLen] = put(buf, 48, 'ev1');
+        const [mPtr, mLen] = put(buf, 64, 'alice');
+
+        expect(imports['data.append'](feed, kPtr, kLen, vPtr, vLen, 0)).toBe(0);
+        expect(imports['data.membership_add'](rooms, kPtr, kLen, mPtr, mLen, 0)).toBe(0);
+
+        db.functionKind = DbFunctionKind.Query;
+        expect(imports['data.latest'](feed, kPtr, kLen, 10)).toBe(-1011);
+        expect(imports['data.membership_list'](rooms, kPtr, kLen, 10)).toBe(-1011);
+
+        db.functionKind = DbFunctionKind.Action;
+        expect(imports['data.latest'](feed, kPtr, kLen, 10)).toBe(-1011);
+        expect(imports['data.membership_list'](rooms, kPtr, kLen, 10)).toBe(-1011);
+
+        db.functionKind = DbFunctionKind.Job;
+        expect(imports['data.latest'](feed, kPtr, kLen, 10)).toBeGreaterThan(0);
+        expect(imports['data.membership_list'](rooms, kPtr, kLen, 10)).toBeGreaterThan(0);
+    });
+
     it('resolve + create + get + take_result round-trips', () => {
         const { imports, buf } = setup();
         const h = resolve(imports, buf, 'App/users');
@@ -70,6 +289,27 @@ describe('toildb dev emulator (record family)', () => {
         expect(buf.toString('utf8', 128, 134)).toBe('world!');
     });
 
+    it('record patch idempotency replays and rejects request mismatch', () => {
+        const { imports, buf } = setup();
+        const h = resolve(imports, buf, 'App/users');
+        const [kPtr, kLen] = put(buf, 32, 'u1');
+        const [vPtr, vLen] = put(buf, 48, 'hello');
+        const [idemPtr] = put(buf, 64, '1234567890abcdef');
+        imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0);
+
+        const [pPtr, pLen] = put(buf, 96, 'world!');
+        expect(imports['data.patch'](h, kPtr, kLen, pPtr, pLen, idemPtr)).toBe(6);
+        expect(imports['data.patch'](h, kPtr, kLen, pPtr, pLen, idemPtr)).toBe(6);
+        expect(imports['data.take_result'](128, 64)).toBe(6);
+        expect(buf.toString('utf8', 128, 134)).toBe('world!');
+
+        const [otherPtr, otherLen] = put(buf, 160, 'again!');
+        expect(imports['data.patch'](h, kPtr, kLen, otherPtr, otherLen, idemPtr)).toBe(-1004);
+        expect(imports['data.get'](h, kPtr, kLen)).toBe(6);
+        expect(imports['data.take_result'](192, 64)).toBe(6);
+        expect(buf.toString('utf8', 192, 198)).toBe('world!');
+    });
+
     it('patch on a missing key is NotFound', () => {
         const { imports, buf } = setup();
         const h = resolve(imports, buf, 'App/users');
@@ -92,6 +332,24 @@ describe('toildb dev emulator (record family)', () => {
         expect(imports['data.get_delete'](h, kPtr, kLen, 0)).toBe(-2);
     });
 
+    it('record get_delete idempotency replays the consumed value', () => {
+        const { imports, buf } = setup();
+        const h = resolve(imports, buf, 'App/challenges');
+        const [kPtr, kLen] = put(buf, 32, 'chal');
+        const [vPtr, vLen] = put(buf, 48, 'nonce');
+        const [idemPtr] = put(buf, 80, 'consume-idem-001');
+        imports['data.create'](h, kPtr, kLen, vPtr, vLen, 0);
+
+        expect(imports['data.get_delete'](h, kPtr, kLen, idemPtr)).toBe(5);
+        expect(imports['data.take_result'](96, 64)).toBe(5);
+        expect(buf.toString('utf8', 96, 101)).toBe('nonce');
+
+        expect(imports['data.get_delete'](h, kPtr, kLen, idemPtr)).toBe(5);
+        expect(imports['data.take_result'](128, 64)).toBe(5);
+        expect(buf.toString('utf8', 128, 133)).toBe('nonce');
+        expect(imports['data.get'](h, kPtr, kLen)).toBe(-2);
+    });
+
     it('absent / invalid handle / buffer-too-small return the edge codes', () => {
         const { imports, buf } = setup();
         const h = resolve(imports, buf, 'App/users');
@@ -127,6 +385,19 @@ describe('toildb dev emulator (record family)', () => {
         expect(buf.toString('utf8', 200, 206)).toBe('user_1');
     });
 
+    it('unique claim: same owner must replay only with the same idempotency key', () => {
+        const { imports, buf } = setup();
+        const h = resolve(imports, buf, 'App/usernames');
+        const [kPtr, kLen] = put(buf, 32, 'grace');
+        const [u1Ptr, u1Len] = put(buf, 48, 'user_1');
+        const [idem1Ptr] = put(buf, 80, 'idem-claim-0001');
+        const [idem2Ptr] = put(buf, 112, 'idem-claim-0002');
+
+        expect(imports['data.unique_claim'](h, kPtr, kLen, u1Ptr, u1Len, idem1Ptr)).toBe(0);
+        expect(imports['data.unique_claim'](h, kPtr, kLen, u1Ptr, u1Len, idem1Ptr)).toBe(2);
+        expect(imports['data.unique_claim'](h, kPtr, kLen, u1Ptr, u1Len, idem2Ptr)).toBe(-1004);
+    });
+
     it('unique release: only the owner may release', () => {
         const { imports, buf } = setup();
         const h = resolve(imports, buf, 'App/usernames');
@@ -263,6 +534,14 @@ describe('toildb dev emulator (record family)', () => {
         imports['data.take_result'](72, 8);
         expect(buf.readBigInt64LE(72)).toBe(3n);
 
+        const [idemPtr] = put(buf, 96, 'counter-idem-001');
+        expect(imports['data.counter_add'](h, kPtr, kLen, 7, idemPtr)).toBe(0);
+        expect(imports['data.counter_add'](h, kPtr, kLen, 7, idemPtr)).toBe(0);
+        expect(imports['data.counter_add'](h, kPtr, kLen, 8, idemPtr)).toBe(-1004);
+        expect(imports['data.counter_get'](h, kPtr, kLen)).toBe(8);
+        imports['data.take_result'](104, 8);
+        expect(buf.readBigInt64LE(104)).toBe(10n);
+
         // invalid handle still rejected
         expect(imports['data.counter_add'](999, kPtr, kLen, 1, 0)).toBe(-1001);
     });
@@ -327,11 +606,14 @@ describe('toildb dev emulator (record family)', () => {
         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);
+        const [appendIdemPtr] = put(buf, 144, 'append-idem-0001');
+        expect(imports['data.append'](feed, kPtr, kLen, evPtr, evLen, appendIdemPtr)).toBe(0);
+        expect(imports['data.append'](feed, kPtr, kLen, evPtr, evLen, appendIdemPtr)).toBe(0);
         // 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);
+        expect(buf.readUInt32LE(512)).toBe(3);
 
         // enqueue: absent -> ABSENT (-2); after create -> replaces (0); get sees the new value.
         const docs = resolve(imports, buf, 'App/docs');
@@ -376,9 +658,19 @@ describe('toildb dev emulator (capacity family)', () => {
         expect(id > 0n).toBe(true);
         expect(avail(imports, buf, h, kPtr, kLen)).toBe(7n);
 
+        const [idemPtr] = put(buf, 64, 'reserve-idem-001');
+        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 2, 60000, idemPtr)).toBe(8);
+        expect(imports['data.take_result'](520, 16)).toBe(8);
+        const idemId = buf.readBigUInt64LE(520);
+        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 2, 60000, idemPtr)).toBe(8);
+        expect(imports['data.take_result'](528, 16)).toBe(8);
+        expect(buf.readBigUInt64LE(528)).toBe(idemId);
+        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 1, 60000, idemPtr)).toBe(-1004);
+        expect(avail(imports, buf, h, kPtr, kLen)).toBe(5n);
+
         // cancel returns the hold -> back to 10; a double-cancel is a no-op.
         expect(imports['data.capacity_cancel'](h, kPtr, kLen, Number(id), 0)).toBe(1);
-        expect(avail(imports, buf, h, kPtr, kLen)).toBe(10n);
+        expect(avail(imports, buf, h, kPtr, kLen)).toBe(8n);
         expect(imports['data.capacity_cancel'](h, kPtr, kLen, Number(id), 0)).toBe(0);
 
         // reserve 4 then confirm -> a permanent consume; available holds at 6.
@@ -386,7 +678,7 @@ describe('toildb dev emulator (capacity family)', () => {
         imports['data.take_result'](512, 16);
         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);
+        expect(avail(imports, buf, h, kPtr, kLen)).toBe(4n);
         // 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(1);
@@ -405,6 +697,17 @@ describe('toildb dev emulator (capacity family)', () => {
         expect(imports['data.capacity_reserve'](h, kPtr, kLen, 0, 60000, 0)).toBe(-1006);
         expect(imports['data.capacity_available'](999, kPtr, kLen)).toBe(-1001);
     });
+
+    it('does not cache an idempotent insufficient reserve forever', () => {
+        const { imports, buf } = setup();
+        const h = resolve(imports, buf, 'App/tickets');
+        const [kPtr, kLen] = put(buf, 32, 'late-restock');
+        const [idemPtr] = put(buf, 64, 'reserve-idem-001');
+
+        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 1, 60000, idemPtr)).toBe(-2);
+        expect(imports['data.capacity_set_total'](h, kPtr, kLen, 1, 0)).toBe(0);
+        expect(imports['data.capacity_reserve'](h, kPtr, kLen, 1, 60000, idemPtr)).toBe(8);
+    });
 });
 
 describe('toildb dev emulator (migration + persistence)', () => {
@@ -466,4 +769,92 @@ describe('toildb dev emulator (migration + persistence)', () => {
             rmSync(dir, { recursive: true, force: true });
         }
     });
+
+    it('persists counter idempotency across devserver restart', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'toildb-'));
+        const file = join(dir, 'devdata.json');
+        try {
+            const a = setup();
+            configureDbPersistence(file);
+            const h = resolve(a.imports, a.buf, 'App/likes');
+            const [kPtr, kLen] = put(a.buf, 32, 'post-1');
+            const [idemPtr] = put(a.buf, 64, 'counter-idem-001');
+            expect(a.imports['data.counter_add'](h, kPtr, kLen, 7, idemPtr)).toBe(0);
+            persistDb();
+
+            __resetDbForTests();
+            configureDbPersistence(file);
+            const b = setup();
+            const h2 = resolve(b.imports, b.buf, 'App/likes');
+            const [k2, kl2] = put(b.buf, 32, 'post-1');
+            const [idem2] = put(b.buf, 64, 'counter-idem-001');
+            expect(b.imports['data.counter_add'](h2, k2, kl2, 7, idem2)).toBe(0);
+            expect(b.imports['data.counter_add'](h2, k2, kl2, 8, idem2)).toBe(-1004);
+            expect(b.imports['data.counter_get'](h2, k2, kl2)).toBe(8);
+            expect(b.imports['data.take_result'](96, 8)).toBe(8);
+            expect(b.buf.readBigInt64LE(96)).toBe(7n);
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('persists unique claim idempotency across devserver restart', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'toildb-'));
+        const file = join(dir, 'devdata.json');
+        try {
+            const a = setup();
+            configureDbPersistence(file);
+            const h = resolve(a.imports, a.buf, 'App/usernames');
+            const [kPtr, kLen] = put(a.buf, 32, 'hopper');
+            const [u1Ptr, u1Len] = put(a.buf, 48, 'user_1');
+            const [idemPtr] = put(a.buf, 80, 'idem-claim-0001');
+            expect(a.imports['data.unique_claim'](h, kPtr, kLen, u1Ptr, u1Len, idemPtr)).toBe(0);
+            persistDb();
+
+            __resetDbForTests();
+            configureDbPersistence(file);
+            const b = setup();
+            const h2 = resolve(b.imports, b.buf, 'App/usernames');
+            const [k2, kl2] = put(b.buf, 32, 'hopper');
+            const [u2, u2l] = put(b.buf, 48, 'user_1');
+            const [sameIdem] = put(b.buf, 80, 'idem-claim-0001');
+            const [otherIdem] = put(b.buf, 112, 'idem-claim-0002');
+            expect(b.imports['data.unique_claim'](h2, k2, kl2, u2, u2l, sameIdem)).toBe(2);
+            expect(b.imports['data.unique_claim'](h2, k2, kl2, u2, u2l, otherIdem)).toBe(-1004);
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
+
+    it('replays idempotent capacity reservations across devserver restart', () => {
+        const dir = mkdtempSync(join(tmpdir(), 'toildb-'));
+        const file = join(dir, 'devdata.json');
+        try {
+            const a = setup();
+            configureDbPersistence(file);
+            const h = resolve(a.imports, a.buf, 'App/seats');
+            const [kPtr, kLen] = put(a.buf, 32, 'showB');
+            const [idemPtr] = put(a.buf, 64, 'reserve-idem-001');
+            expect(a.imports['data.capacity_set_total'](h, kPtr, kLen, 3, 0)).toBe(0);
+            expect(a.imports['data.capacity_reserve'](h, kPtr, kLen, 2, 60000, idemPtr)).toBe(8);
+            expect(a.imports['data.take_result'](96, 16)).toBe(8);
+            const firstId = a.buf.readBigUInt64LE(96);
+            persistDb();
+
+            __resetDbForTests();
+            configureDbPersistence(file);
+            const b = setup();
+            const h2 = resolve(b.imports, b.buf, 'App/seats');
+            const [k2, kl2] = put(b.buf, 32, 'showB');
+            const [idem2] = put(b.buf, 64, 'reserve-idem-001');
+            expect(b.imports['data.capacity_reserve'](h2, k2, kl2, 2, 60000, idem2)).toBe(8);
+            expect(b.imports['data.take_result'](96, 16)).toBe(8);
+            expect(b.buf.readBigUInt64LE(96)).toBe(firstId);
+            expect(b.imports['data.capacity_available'](h2, k2, kl2)).toBe(8);
+            expect(b.imports['data.take_result'](112, 16)).toBe(8);
+            expect(b.buf.readBigInt64LE(112)).toBe(1n);
+        } finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    });
 });

package/test/email-preview.test.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 
 import { createServer } from 'vite';
@@ -14,7 +15,11 @@ import { createViteConfig } from '../src/compiler/vite';
 
 const EXAMPLE = path.resolve(__dirname, '../examples/basic');
 
-describe('email preview end-to-end (examples/basic)', () => {
+// Drives a Vite server over examples/basic; skip where the example's deps are
+// not installed (e.g. CI without the example set up).
+describe.skipIf(!existsSync(path.join(EXAMPLE, 'node_modules')))(
+    'email preview end-to-end (examples/basic)',
+    () => {
     it('lists Welcome and inlines its emails/styles/email.css; client/* alias resolves', async () => {
         const cfg = await loadConfig({ root: EXAMPLE });
         const items = listEmails(cfg);

package/test/fixtures/daemon-app.ts

@@ -0,0 +1,56 @@
+// A minimal @daemon fixture for the dev daemon-emulation test. It declares the
+// `daemon.*` / `mstore.*` host imports directly (so it needs no toiljs globals
+// lib) and records its activity into the dev MemoryStore, which the test reads
+// back through `devMemoryStore`. Compiled with `--targetMode cold` by the test.
+//
+//   onStart()          -> mstore.incr("started", 1) and stamps the lease epoch
+//   tick()  @scheduled -> mstore.incr("tick:fast", 1)   (1s interval)
+//   sixHourly() cron   -> mstore.incr("tick:cron", 1)   (0 */6 * * *)
+
+// @ts-nocheck — this is AssemblyScript source compiled by toilscript, not TS.
+
+@external("env", "mstore.incr")
+declare function mstoreIncr(keyPtr: i32, keyLen: i32, delta: i64, ttlSecs: i32): i64;
+
+@external("env", "daemon.is_leader")
+declare function daemonIsLeader(): i32;
+
+@external("env", "daemon.current_epoch")
+declare function daemonCurrentEpoch(): i64;
+
+@external("env", "daemon.task_count")
+declare function daemonTaskCount(): i32;
+
+// Bump the i64 counter stored at the (utf8) `key` by 1. The host reads the key
+// bytes straight out of linear memory (handleless mstore, ttl in seconds).
+function bump(key: string): void {
+    let bytes = String.UTF8.encode(key);
+    mstoreIncr(changetype<i32>(bytes), bytes.byteLength, 1, 0);
+}
+
+@daemon
+class Jobs {
+    onStart(): void {
+        // Prove leader=true and that the epoch import is callable; record both so
+        // the test can assert the stubs from outside.
+        bump("started");
+        if (daemonIsLeader() == 1) bump("leader");
+        let epoch = daemonCurrentEpoch();
+        if (epoch >= 0) bump("epoch:nonneg");
+        if (daemonTaskCount() == 2) bump("taskcount:2");
+    }
+
+    @scheduled("1s")
+    tick(): void {
+        bump("tick:fast");
+    }
+
+    @scheduled("0 */6 * * *")
+    sixHourly(): void {
+        bump("tick:cron");
+    }
+}
+
+export function probe(): i32 {
+    return 1;
+}

package/test/global-setup.ts

@@ -0,0 +1,17 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Vitest global setup: generate `src/compiler/toil-docs.generated.ts` before the
+ * suite runs. `src/compiler/docs.ts` imports that module, but it is gitignored
+ * and only (re)created by the build's `gen:docs` step, so a fresh checkout that
+ * runs the tests without a prior build would otherwise fail to resolve it
+ * ("Cannot find module './toil-docs.generated.js'"). Running the same generator
+ * the npm scripts use keeps the tests self-contained. Runs once per vitest
+ * invocation, so it also covers `npx vitest` / watch mode.
+ */
+export default function setup(): void {
+    const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+    execFileSync('node', ['scripts/gen-toil-docs.mjs'], { cwd: root, stdio: 'ignore' });
+}