toiljs 0.0.59 → 0.0.61

package/test/devserver-database.test.ts

@@ -1,9 +1,38 @@
-import { afterEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
-import { __resetDbForTests, buildDatabaseImports, freshDbState } from '../src/devserver/database.js';
-import type { MemoryRef } from '../src/devserver/host.js';
+import { afterEach, describe, expect, it } from 'vitest';
 
-function setup() {
+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';
+
+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();
@@ -12,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);
@@ -19,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');
@@ -37,7 +267,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);
@@ -59,12 +289,33 @@ 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');
         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', () => {
@@ -81,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');
@@ -116,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');
@@ -124,7 +406,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 +444,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 +477,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));
@@ -250,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);
     });
@@ -274,6 +566,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 +594,39 @@ 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);
+        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(3);
+
+        // 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>;
@@ -332,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.
@@ -342,10 +678,10 @@ 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);
-        // a confirmed hold cannot be cancelled nor re-confirmed.
+        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(0);
+        expect(imports['data.capacity_confirm'](h, kPtr, kLen, id2, 0)).toBe(1);
     });
 
     it('never oversells (a reserve beyond available is refused)', () => {
@@ -357,8 +693,168 @@ 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);
     });
+
+    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)', () => {
+    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 });
+        }
+    });
+
+    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/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