@minnowdb/core 0.3.0 → 0.4.0

package/dist/engine/worker-host.js

@@ -1,4 +1,5 @@
-import { parseRpcRequest, rpcEvent, rpcFailure, rpcResult, serializeError, } from "../worker-protocol/index.js";
+import { MAX_SNAPSHOT_STREAM_CHUNK_BYTES } from "../storage/snapshot.js";
+import { parseRpcRequest, MAX_DATABASE_RPC_IN_FLIGHT, rpcEvent, rpcFailure, rpcResult, serializeError, } from "../worker-protocol/index.js";
 import { MinnowDatabase, } from "./database.js";
 import { encodeQueryResult, encodeQueryRows } from "./result-wire.js";
 import { deserializeSchema, serializeMigrationSteps } from "./schema-wire.js";
@@ -22,28 +23,144 @@ class ColumnarResult {
         this.encoded = encoded;
     }
 }
+class CursorBatchResult {
+    encoded;
+    constructor(encoded) {
+        this.encoded = encoded;
+    }
+}
+class SnapshotChunkResult {
+    chunk;
+    constructor(chunk) {
+        this.chunk = chunk;
+    }
+}
 class WriteScopeAbortedError extends Error {
     name = "WriteScopeAbortedError";
     constructor() {
         super("Write scope aborted");
     }
 }
+/** One-chunk rendezvous. The sender is acknowledged only when the decoder asks for more. */
+class SnapshotImportChunkQueue {
+    #queued;
+    #consumed;
+    #reader;
+    #finished = false;
+    #failure;
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+    push(chunk) {
+        if (chunk.byteLength > MAX_SNAPSHOT_STREAM_CHUNK_BYTES) {
+            throw new RangeError("Snapshot transfer chunk exceeds the 1 MiB limit");
+        }
+        if (this.#failure !== undefined)
+            return Promise.reject(snapshotQueueError(this.#failure));
+        if (this.#finished)
+            return Promise.reject(new Error("Snapshot import transfer is closed"));
+        if (this.#queued !== undefined) {
+            return Promise.reject(new Error("Snapshot import transfer already has a queued chunk"));
+        }
+        return new Promise((resolve, reject) => {
+            const reader = this.#reader;
+            if (reader === undefined) {
+                this.#queued = { chunk, resolve, reject };
+                return;
+            }
+            this.#reader = undefined;
+            this.#consumed = { resolve, reject };
+            reader.resolve({ done: false, value: chunk });
+        });
+    }
+    async next() {
+        this.#consumed?.resolve();
+        this.#consumed = undefined;
+        if (this.#failure !== undefined)
+            throw snapshotQueueError(this.#failure);
+        const queued = this.#queued;
+        if (queued !== undefined) {
+            this.#queued = undefined;
+            this.#consumed = { resolve: queued.resolve, reject: queued.reject };
+            return { done: false, value: queued.chunk };
+        }
+        if (this.#finished)
+            return { done: true, value: undefined };
+        return new Promise((resolve, reject) => {
+            this.#reader = { resolve, reject };
+        });
+    }
+    async return() {
+        this.finish();
+        return { done: true, value: undefined };
+    }
+    finish() {
+        if (this.#finished)
+            return;
+        this.#finished = true;
+        if (this.#queued === undefined) {
+            const reader = this.#reader;
+            this.#reader = undefined;
+            reader?.resolve({ done: true, value: undefined });
+        }
+    }
+    fail(error) {
+        if (this.#failure !== undefined)
+            return;
+        this.#failure = error;
+        this.#finished = true;
+        this.#queued?.reject(error);
+        this.#queued = undefined;
+        this.#consumed?.reject(error);
+        this.#consumed = undefined;
+        this.#reader?.reject(error);
+        this.#reader = undefined;
+    }
+}
+function snapshotQueueError(value) {
+    return value instanceof Error ? value : new Error("Snapshot transfer failed", { cause: value });
+}
+/** Hard per-connection ceiling for resident worker resources abandoned by a client. */
+export const MAX_WORKER_HANDLES_PER_CONNECTION = 256;
+const DEFAULT_WRITE_HANDLE_IDLE_TIMEOUT_MS = 30_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 class DatabaseRpcServer {
     database;
     scope;
     options;
     #handles = new Map();
+    #reservedHandleIds = new Set();
+    #openingHandlePromises = new Set();
+    #settlingWritePromises = new Set();
     #disposed = false;
+    #inFlightRpcCount = 0;
+    #inFlightRpcDrain;
+    #resolveInFlightRpcDrain;
+    #writeHandleIdleTimeoutMs;
     constructor(database, scope, options) {
         this.database = database;
         this.scope = scope;
         this.options = options;
+        this.#writeHandleIdleTimeoutMs =
+            options.writeHandleIdleTimeoutMs ?? DEFAULT_WRITE_HANDLE_IDLE_TIMEOUT_MS;
+        if (!Number.isSafeInteger(this.#writeHandleIdleTimeoutMs) ||
+            this.#writeHandleIdleTimeoutMs <= 0 ||
+            this.#writeHandleIdleTimeoutMs > MAX_TIMER_DELAY_MS) {
+            throw new RangeError(`Worker write-handle idle timeout must be a positive whole number no greater than ${String(MAX_TIMER_DELAY_MS)}`);
+        }
     }
     async handle(request) {
         if (request.kind === "rpc-init") {
             this.scope.postMessage(rpcResult(request.requestId, { ready: true }));
             return;
         }
+        const bypassLimit = request.method === "dispose";
+        if (!bypassLimit && this.#inFlightRpcCount >= MAX_DATABASE_RPC_IN_FLIGHT) {
+            this.scope.postMessage(rpcFailure(request.requestId, new RangeError(`A database worker connection cannot hold more than ${String(MAX_DATABASE_RPC_IN_FLIGHT)} in-flight requests`)));
+            return;
+        }
+        if (!bypassLimit)
+            this.#inFlightRpcCount += 1;
         try {
             if (this.#disposed)
                 throw new Error("Database connection is disposed");
@@ -55,6 +172,16 @@ class DatabaseRpcServer {
                     transfer: result.encoded.transfer,
                 });
             }
+            else if (result instanceof CursorBatchResult) {
+                this.scope.postMessage(rpcResult(request.requestId, result.encoded === undefined
+                    ? { done: true }
+                    : { done: false, batch: result.encoded.payload }), result.encoded === undefined ? undefined : { transfer: result.encoded.transfer });
+            }
+            else if (result instanceof SnapshotChunkResult) {
+                this.scope.postMessage(rpcResult(request.requestId, { done: false, chunk: result.chunk }), {
+                    transfer: [result.chunk.buffer],
+                });
+            }
             else {
                 this.scope.postMessage(rpcResult(request.requestId, result));
             }
@@ -62,6 +189,16 @@ class DatabaseRpcServer {
         catch (error) {
             this.scope.postMessage(rpcFailure(request.requestId, error));
         }
+        finally {
+            if (!bypassLimit)
+                this.#inFlightRpcCount -= 1;
+            if (this.#inFlightRpcCount === 0 && this.#resolveInFlightRpcDrain !== undefined) {
+                const resolve = this.#resolveInFlightRpcDrain;
+                this.#inFlightRpcDrain = undefined;
+                this.#resolveInFlightRpcDrain = undefined;
+                resolve();
+            }
+        }
     }
     async #callRoot(method, args) {
         const database = this.database;
@@ -76,10 +213,11 @@ class DatabaseRpcServer {
             case "updateBatch":
             case "update":
             case "deleteBatch":
+            case "delete":
             case "runStatement":
             case "explain":
             case "execute":
-            case "listVisibleSegments":
+            case "listVisibleSegmentPage":
             case "cleanupQuerySpill":
             case "compactTable":
             case "compactTableStep":
@@ -90,12 +228,30 @@ class DatabaseRpcServer {
             case "collectGarbageStep":
             case "resumeGarbageCollectionJob":
             case "bufferPoolStats":
+            case "maintenanceStatus":
+            case "checkIntegrity":
+            case "storageStats":
+            case "inspectInterruptedImport":
+            case "abortInterruptedImport":
             case "listGarbageCollectionJobs":
                 return database[method]?.(...args);
             case "query": {
                 const [sql, options] = args;
                 return new ColumnarResult(encodeQueryResult(await this.database.query(sql, options)));
             }
+            case "queryCursorOpen": {
+                const handleId = this.#claimHandleId(args[0]);
+                const [sql, options] = args.slice(1);
+                try {
+                    const iterator = this.database.queryCursor(sql, options);
+                    this.#publishHandle(handleId, { type: "query-cursor", iterator });
+                }
+                catch (error) {
+                    this.#releaseHandleId(handleId);
+                    throw error;
+                }
+                return { handleId };
+            }
             case "run": {
                 const query = args[0];
                 return new ColumnarResult(encodeQueryRows(await this.database.run(query)));
@@ -118,90 +274,91 @@ class DatabaseRpcServer {
                     steps: serializeMigrationSteps(result.steps),
                 };
             }
-            case "writeOpen": {
-                // Same deferred-callback shape as snapshotOpen: the scoped write() stays pending
-                // until the client commits or aborts, so its staged transaction spans the RPC session.
-                const handleId = crypto.randomUUID();
-                let sessionResolve;
-                const sessionReady = new Promise((resolveSession) => {
-                    sessionResolve = resolveSession;
-                });
-                let finish;
-                const done = this.database
-                    .write(async (session) => {
-                    sessionResolve(session);
-                    await new Promise((resolveCommit, rejectAbort) => {
-                        finish = (commit) => {
-                            if (commit)
-                                resolveCommit();
-                            else
-                                rejectAbort(new WriteScopeAbortedError());
-                        };
+            case "writeOpen":
+                return this.#trackOpeningHandle(this.#openWriteHandle());
+            case "snapshotOpen":
+                return this.#trackOpeningHandle(this.#openSnapshotHandle());
+            case "exportSnapshotOpen": {
+                const handleId = this.#claimGeneratedHandleId();
+                const iterator = this.database.exportSnapshotStream()[Symbol.asyncIterator]();
+                try {
+                    this.#publishHandle(handleId, {
+                        type: "snapshot-export",
+                        iterator,
+                        reading: false,
+                        done: false,
                     });
-                })
-                    .then((outcome) => ({ version: outcome.version }));
-                const session = await sessionReady;
-                this.#handles.set(handleId, { type: "write", session, finish, done });
+                }
+                catch (error) {
+                    await iterator.return(undefined);
+                    this.#releaseHandleId(handleId);
+                    throw error;
+                }
                 return { handleId };
             }
-            case "snapshotOpen": {
-                // The scoped snapshot() holds its lease until the callback settles; the handle keeps
-                // the callback pending until the client closes it, so the pin spans the RPC session.
-                const handleId = crypto.randomUUID();
-                let release;
-                const version = await new Promise((resolveVersion, rejectVersion) => {
-                    void this.database
-                        .snapshot(async (session) => {
-                        resolveVersion(session.version);
-                        await new Promise((resolveRelease) => {
-                            release = resolveRelease;
-                        });
-                    })
-                        .catch((error) => {
-                        rejectVersion(error instanceof Error ? error : new Error(String(error)));
-                    });
-                });
-                this.#handles.set(handleId, { type: "snapshot", release });
-                return { handleId, version };
-            }
-            case "exportSnapshotOpen": {
-                // The snapshot is encoded here and held by the handle so the client can pull it across
-                // in slices. One result frame carrying the whole thing would be a structured clone the
-                // size of the database, and the main thread would sit still for all of it.
-                const handleId = crypto.randomUUID();
-                const bytes = await this.database.exportSnapshot();
-                this.#handles.set(handleId, { type: "snapshot-export", bytes });
-                return { handleId, byteLength: bytes.byteLength };
-            }
             case "importSnapshotOpen": {
                 // Named by the client, like the other event-producing handles, so its progress route
                 // exists before the first frame the load can emit.
                 const handleId = this.#claimHandleId(args[0]);
-                this.#handles.set(handleId, { type: "snapshot-import", chunks: [], byteLength: 0 });
+                const queue = new SnapshotImportChunkQueue();
+                const abort = new AbortController();
+                const task = this.database.importSnapshotStream(queue, {
+                    signal: abort.signal,
+                    onProgress: (progress) => {
+                        this.scope.postMessage(rpcEvent(handleId, "progress", progress));
+                    },
+                });
+                void task.catch((error) => queue.fail(error));
+                try {
+                    this.#publishHandle(handleId, { type: "snapshot-import", queue, task, abort });
+                }
+                catch (error) {
+                    abort.abort(error);
+                    queue.fail(error);
+                    await task.catch(() => undefined);
+                    this.#releaseHandleId(handleId);
+                    throw error;
+                }
                 return { handleId };
             }
             case "bufferedWriter": {
                 // Event-producing handles are named by the client so its event routes exist before the
                 // first frame the handle can emit.
                 const handleId = this.#claimHandleId(args[0]);
-                const writer = this.database.bufferedWriter(args[1], {
-                    ...args[2],
-                    onError: (error) => {
-                        this.scope.postMessage(rpcEvent(handleId, "error", serializeError(error)));
-                    },
-                });
-                this.#handles.set(handleId, { type: "writer", writer });
+                let writer;
+                try {
+                    writer = this.database.bufferedWriter(args[1], {
+                        ...args[2],
+                        onError: (error) => {
+                            this.scope.postMessage(rpcEvent(handleId, "error", serializeError(error)));
+                        },
+                    });
+                    this.#publishHandle(handleId, { type: "writer", writer });
+                }
+                catch (error) {
+                    await writer?.close().catch(() => undefined);
+                    this.#releaseHandleId(handleId);
+                    throw error;
+                }
                 return { handleId };
             }
             case "liveQueries": {
                 const handleId = this.#claimHandleId(args[0]);
                 const { pollIntervalMs, channelName } = (args[1] ?? {});
                 // The database owns channelName resolution (and closes the channel with the set).
-                const set = this.database.liveQueries({
-                    ...(channelName === undefined ? {} : { channelName }),
-                    ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
-                });
-                this.#handles.set(handleId, { type: "live-set", set, subscriptionIds: new Set() });
+                let set;
+                try {
+                    set = this.database.liveQueries({
+                        ...(channelName === undefined ? {} : { channelName }),
+                        ...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),
+                    });
+                    this.#publishHandle(handleId, { type: "live-set", set, subscriptionIds: new Set() });
+                }
+                catch (error) {
+                    set?.close();
+                    this.#releaseHandleId(handleId);
+                    throw error;
+                }
                 return { handleId };
             }
             case "dispose": {
@@ -216,56 +373,142 @@ class DatabaseRpcServer {
                 throw new Error(`Unsupported database method: ${method}`);
         }
     }
+    async #openWriteHandle() {
+        // Same deferred-callback shape as snapshotOpen: the scoped write() stays pending until the
+        // client commits or aborts, so its staged transaction spans the RPC session.
+        const handleId = this.#claimGeneratedHandleId();
+        let sessionResolve;
+        let sessionReject;
+        const sessionReady = new Promise((resolveSession, rejectSession) => {
+            sessionResolve = resolveSession;
+            sessionReject = rejectSession;
+        });
+        let finish;
+        const done = this.database
+            .write(async (session) => {
+            sessionResolve(session);
+            await new Promise((resolveCommit, rejectAbort) => {
+                finish = (commit) => {
+                    if (commit)
+                        resolveCommit();
+                    else
+                        rejectAbort(new WriteScopeAbortedError());
+                };
+            });
+        })
+            .then((outcome) => ({ version: outcome.version }));
+        // beginDeferred can fail before the callback starts (for example at the durable reader-lease
+        // ceiling). Reject the open rendezvous too and observe `done` immediately.
+        void done.catch((error) => sessionReject(error));
+        try {
+            const session = await sessionReady;
+            if (finish === undefined)
+                throw new Error("Write scope did not install its settlement");
+            this.#publishHandle(handleId, {
+                type: "write",
+                session,
+                finish,
+                done,
+                activeCalls: 0,
+                activeCallDone: undefined,
+                finishActiveCall: undefined,
+                open: true,
+                idleTimer: undefined,
+            });
+            return { handleId };
+        }
+        catch (error) {
+            // Publication can lose a race with connection disposal. If the callback started, abort and
+            // join it before the opening task releases its lifecycle slot.
+            finish?.(false);
+            await done.catch(() => undefined);
+            this.#releaseHandleId(handleId);
+            throw error;
+        }
+    }
+    async #openSnapshotHandle() {
+        // The scoped snapshot() holds its lease until the callback settles; the handle keeps the
+        // callback pending until close, so the pin spans the RPC session.
+        const handleId = this.#claimGeneratedHandleId();
+        let release;
+        let resolveVersion;
+        let rejectVersion;
+        const versionReady = new Promise((resolve, reject) => {
+            resolveVersion = resolve;
+            rejectVersion = reject;
+        });
+        const done = this.database.snapshot(async (session) => {
+            resolveVersion(session.version);
+            await new Promise((resolveRelease) => {
+                release = resolveRelease;
+            });
+        });
+        // Lease admission may fail before the callback installs `release`. Preserve that typed error
+        // through the rendezvous and keep the task observed from creation.
+        void done.catch((error) => rejectVersion(error));
+        try {
+            const version = await versionReady;
+            if (release === undefined)
+                throw new Error("Snapshot scope did not install its release");
+            this.#publishHandle(handleId, { type: "snapshot", release, done });
+            return { handleId, version };
+        }
+        catch (error) {
+            release?.();
+            await done.catch(() => undefined);
+            this.#releaseHandleId(handleId);
+            throw error;
+        }
+    }
+    #trackOpeningHandle(opening) {
+        this.#openingHandlePromises.add(opening);
+        void opening.then(() => this.#openingHandlePromises.delete(opening), () => this.#openingHandlePromises.delete(opening));
+        return opening;
+    }
     async #callHandle(handleId, method, args) {
         const handle = this.#handles.get(handleId);
         if (handle === undefined)
             throw new Error(`Unknown handle: ${handleId}`);
+        if (handle.type === "write") {
+            this.#beginWriteHandleCall(handle);
+            try {
+                return await this.#callWriteHandle(handleId, handle, method, args);
+            }
+            finally {
+                this.#endWriteHandleCall(handleId, handle);
+            }
+        }
         switch (handle.type) {
             case "snapshot": {
                 if (method !== "close")
                     throw new Error(`Unsupported snapshot method: ${method}`);
                 handle.release();
                 this.#handles.delete(handleId);
+                await handle.done;
                 return undefined;
             }
-            case "write": {
-                if (method === "query") {
-                    const [sql, options] = args;
-                    return new ColumnarResult(encodeQueryResult(await handle.session.query(sql, options)));
-                }
-                if (method === "execute") {
-                    const [sql, params] = args;
-                    return handle.session.execute(sql, params);
-                }
-                if (method === "stage") {
-                    const [op, tableName, input] = args;
-                    if (!isStageOp(op)) {
-                        throw new Error(`Unsupported write stage operation: ${String(op)}`);
-                    }
-                    return handle.session[op](tableName, input);
-                }
-                if (method === "commit") {
-                    handle.finish(true);
-                    this.#handles.delete(handleId);
-                    return handle.done;
-                }
-                if (method === "abort") {
-                    handle.finish(false);
-                    this.#handles.delete(handleId);
-                    return handle.done.catch((error) => {
-                        if (error instanceof WriteScopeAbortedError)
-                            return undefined;
-                        throw error;
-                    });
-                }
-                throw new Error(`Unsupported write method: ${method}`);
-            }
             case "snapshot-export":
                 return this.#callSnapshotExport(handleId, handle, method, args);
             case "snapshot-import":
                 return this.#callSnapshotImport(handleId, handle, method, args);
             case "writer":
                 return this.#callWriter(handleId, handle.writer, method, args);
+            case "query-cursor": {
+                if (method === "next") {
+                    const next = await handle.iterator.next();
+                    if (next.done) {
+                        this.#handles.delete(handleId);
+                        return new CursorBatchResult(undefined);
+                    }
+                    return new CursorBatchResult(encodeQueryResult(next.value));
+                }
+                if (method === "close") {
+                    await handle.iterator.return?.();
+                    this.#handles.delete(handleId);
+                    return undefined;
+                }
+                throw new Error(`Unsupported query cursor method: ${method}`);
+            }
             case "live-set":
                 return this.#callLiveSet(handleId, handle, method, args);
             case "live-subscription": {
@@ -280,25 +523,61 @@ class DatabaseRpcServer {
             }
         }
     }
+    async #callWriteHandle(handleId, handle, method, args) {
+        if (method === "query") {
+            const [sql, options] = args;
+            return new ColumnarResult(encodeQueryResult(await handle.session.query(sql, options)));
+        }
+        if (method === "execute") {
+            const [sql, params] = args;
+            return handle.session.execute(sql, params);
+        }
+        if (method === "stage") {
+            const [op, tableName, input] = args;
+            if (!isStageOp(op)) {
+                throw new Error(`Unsupported write stage operation: ${String(op)}`);
+            }
+            return handle.session[op](tableName, input);
+        }
+        if (method === "commit")
+            return this.#settleWriteHandle(handleId, handle, true);
+        if (method === "abort")
+            return this.#settleWriteHandle(handleId, handle, false);
+        throw new Error(`Unsupported write method: ${method}`);
+    }
     /**
      * Hands one slice of an encoded snapshot back. The slice is copied rather than viewed: a
      * subarray shares the whole buffer, and structured clone copies the buffer behind a view, not
      * the window into it — so every read would post the entire snapshot again.
      */
-    #callSnapshotExport(handleId, handle, method, args) {
+    async #callSnapshotExport(handleId, handle, method, args) {
         switch (method) {
             case "read": {
-                const [offset, length] = args;
-                if (!Number.isSafeInteger(offset) || offset < 0) {
-                    throw new RangeError("Snapshot read offset must be a non-negative whole number");
+                if (args.length !== 0)
+                    throw new TypeError("Snapshot stream read takes no arguments");
+                if (handle.reading)
+                    throw new Error("Snapshot stream already has a read in flight");
+                if (handle.done)
+                    return { done: true };
+                handle.reading = true;
+                try {
+                    const next = await handle.iterator.next();
+                    if (next.done === true) {
+                        handle.done = true;
+                        return { done: true };
+                    }
+                    // The iterator may yield a view into a 64 MiB block. Transfer only this bounded slice;
+                    // detaching the larger backing buffer would corrupt subsequent slices.
+                    const chunk = new Uint8Array(next.value.byteLength);
+                    chunk.set(next.value);
+                    return new SnapshotChunkResult(chunk);
                 }
-                if (!Number.isSafeInteger(length) || length <= 0) {
-                    throw new RangeError("Snapshot read length must be a positive whole number");
+                finally {
+                    handle.reading = false;
                 }
-                const start = offset;
-                return handle.bytes.slice(start, start + length);
             }
             case "close": {
+                await handle.iterator.return?.();
                 this.#handles.delete(handleId);
                 return undefined;
             }
@@ -314,26 +593,13 @@ class DatabaseRpcServer {
                 if (!(chunk instanceof Uint8Array)) {
                     throw new TypeError("Snapshot chunk must be a Uint8Array");
                 }
-                handle.chunks.push(chunk);
-                handle.byteLength += chunk.byteLength;
+                await handle.queue.push(chunk);
                 return undefined;
             }
             case "finish": {
-                const bytes = new Uint8Array(handle.byteLength);
-                let offset = 0;
-                for (const chunk of handle.chunks) {
-                    bytes.set(chunk, offset);
-                    offset += chunk.byteLength;
-                }
-                // Dropped before the load starts: the decoded snapshot is another copy of these bytes,
-                // and holding the chunks too would make three of them.
-                handle.chunks.length = 0;
                 try {
-                    await this.database.importSnapshot(bytes, {
-                        onProgress: (progress) => {
-                            this.scope.postMessage(rpcEvent(handleId, "progress", progress));
-                        },
-                    });
+                    handle.queue.finish();
+                    await handle.task;
                 }
                 finally {
                     this.#handles.delete(handleId);
@@ -341,6 +607,15 @@ class DatabaseRpcServer {
                 return undefined;
             }
             case "close": {
+                handle.queue.fail(new Error("Snapshot import transfer was cancelled"));
+                await handle.task.catch(() => undefined);
+                this.#handles.delete(handleId);
+                return undefined;
+            }
+            case "cancel": {
+                handle.abort.abort(new Error("Snapshot import was cancelled"));
+                handle.queue.fail(handle.abort.signal.reason);
+                await handle.task.catch(() => undefined);
                 this.#handles.delete(handleId);
                 return undefined;
             }
@@ -377,29 +652,71 @@ class DatabaseRpcServer {
                 // posted before this call's own result frame.
                 const subscriptionId = this.#claimHandleId(args[0]);
                 const query = args[1];
-                const subscription = await handle.set.subscribe(query, {
-                    onChange: (result) => {
-                        const encoded = encodeQueryResult(result);
-                        this.scope.postMessage(rpcEvent(subscriptionId, "change", encoded.payload), {
-                            transfer: encoded.transfer,
-                        });
-                    },
-                    onError: (error) => {
-                        this.scope.postMessage(rpcEvent(subscriptionId, "error", serializeError(error)));
-                    },
-                    onComplete: () => {
-                        this.scope.postMessage(rpcEvent(subscriptionId, "complete", null));
-                        this.#handles.delete(subscriptionId);
-                        const parent = this.#handles.get(handleId);
-                        if (parent?.type === "live-set")
-                            parent.subscriptionIds.delete(subscriptionId);
-                    },
-                });
-                this.#handles.set(subscriptionId, {
-                    type: "live-subscription",
-                    subscription,
-                    setId: handleId,
-                });
+                let subscription;
+                try {
+                    subscription = await handle.set.subscribe(query, {
+                        onChange: (result) => {
+                            const encoded = encodeQueryResult(result);
+                            this.scope.postMessage(rpcEvent(subscriptionId, "change", encoded.payload), {
+                                transfer: encoded.transfer,
+                            });
+                        },
+                        onError: (error) => {
+                            this.scope.postMessage(rpcEvent(subscriptionId, "error", serializeError(error)));
+                        },
+                        onComplete: () => {
+                            this.scope.postMessage(rpcEvent(subscriptionId, "complete", null));
+                            this.#handles.delete(subscriptionId);
+                            const parent = this.#handles.get(handleId);
+                            if (parent?.type === "live-set")
+                                parent.subscriptionIds.delete(subscriptionId);
+                        },
+                    });
+                    this.#publishHandle(subscriptionId, {
+                        type: "live-subscription",
+                        subscription,
+                        setId: handleId,
+                    });
+                }
+                catch (error) {
+                    subscription?.close();
+                    this.#releaseHandleId(subscriptionId);
+                    throw error;
+                }
+                handle.subscriptionIds.add(subscriptionId);
+                return { dependencyTableIds: subscription.dependencyTableIds };
+            }
+            case "observe": {
+                const subscriptionId = this.#claimHandleId(args[0]);
+                const query = args[1];
+                let subscription;
+                try {
+                    subscription = await handle.set.observe(query, {
+                        onInvalidate: (invalidation) => {
+                            this.scope.postMessage(rpcEvent(subscriptionId, "invalidate", invalidation));
+                        },
+                        onError: (error) => {
+                            this.scope.postMessage(rpcEvent(subscriptionId, "error", serializeError(error)));
+                        },
+                        onComplete: () => {
+                            this.scope.postMessage(rpcEvent(subscriptionId, "complete", null));
+                            this.#handles.delete(subscriptionId);
+                            const parent = this.#handles.get(handleId);
+                            if (parent?.type === "live-set")
+                                parent.subscriptionIds.delete(subscriptionId);
+                        },
+                    });
+                    this.#publishHandle(subscriptionId, {
+                        type: "live-subscription",
+                        subscription,
+                        setId: handleId,
+                    });
+                }
+                catch (error) {
+                    subscription?.close();
+                    this.#releaseHandleId(subscriptionId);
+                    throw error;
+                }
                 handle.subscriptionIds.add(subscriptionId);
                 return { dependencyTableIds: subscription.dependencyTableIds };
             }
@@ -421,10 +738,96 @@ class DatabaseRpcServer {
         if (typeof value !== "string" || value.length === 0) {
             throw new TypeError("Handle ID must be a non-empty string");
         }
-        if (this.#handles.has(value))
+        if (this.#handles.has(value) || this.#reservedHandleIds.has(value)) {
             throw new Error(`Handle ID already exists: ${value}`);
+        }
+        if (this.#handles.size + this.#reservedHandleIds.size + this.#settlingWritePromises.size >=
+            MAX_WORKER_HANDLES_PER_CONNECTION) {
+            throw new Error(`Database connection cannot hold more than ${String(MAX_WORKER_HANDLES_PER_CONNECTION)} open handles (active or settling)`);
+        }
+        this.#reservedHandleIds.add(value);
         return value;
     }
+    #claimGeneratedHandleId() {
+        for (;;) {
+            const id = crypto.randomUUID();
+            if (!this.#handles.has(id) && !this.#reservedHandleIds.has(id))
+                return this.#claimHandleId(id);
+        }
+    }
+    #publishHandle(id, handle) {
+        if (this.#disposed)
+            throw new Error("Database connection is disposed");
+        if (!this.#reservedHandleIds.delete(id))
+            throw new Error(`Handle ID was not reserved: ${id}`);
+        this.#handles.set(id, handle);
+        if (handle.type === "write")
+            this.#armWriteHandleIdleTimer(id, handle);
+    }
+    #releaseHandleId(id) {
+        this.#reservedHandleIds.delete(id);
+    }
+    #beginWriteHandleCall(handle) {
+        if (!handle.open)
+            throw new Error("Write handle is closed");
+        if (handle.activeCalls !== 0) {
+            throw new Error("Write handle already has a call in flight");
+        }
+        handle.activeCalls = 1;
+        handle.activeCallDone = new Promise((resolve) => {
+            handle.finishActiveCall = resolve;
+        });
+        if (handle.idleTimer !== undefined) {
+            clearTimeout(handle.idleTimer);
+            handle.idleTimer = undefined;
+        }
+    }
+    #endWriteHandleCall(handleId, handle) {
+        handle.activeCalls -= 1;
+        if (handle.activeCalls < 0)
+            throw new Error("Write handle activity count underflow");
+        const finishActiveCall = handle.finishActiveCall;
+        handle.activeCallDone = undefined;
+        handle.finishActiveCall = undefined;
+        finishActiveCall?.();
+        if (handle.open && handle.activeCalls === 0)
+            this.#armWriteHandleIdleTimer(handleId, handle);
+    }
+    #armWriteHandleIdleTimer(handleId, handle) {
+        if (!handle.open || handle.activeCalls !== 0 || this.#handles.get(handleId) !== handle)
+            return;
+        if (handle.idleTimer !== undefined)
+            clearTimeout(handle.idleTimer);
+        handle.idleTimer = setTimeout(() => {
+            handle.idleTimer = undefined;
+            if (!handle.open || handle.activeCalls !== 0 || this.#handles.get(handleId) !== handle)
+                return;
+            // Delete first: a late commit or stage frame must fail rather than revive an expired scope
+            // while its asynchronous durable rollback is still joining.
+            void this.#settleWriteHandle(handleId, handle, false).catch(() => undefined);
+        }, this.#writeHandleIdleTimeoutMs);
+        unrefTimer(handle.idleTimer);
+    }
+    async #settleWriteHandle(handleId, handle, commit) {
+        if (!handle.open)
+            throw new Error("Write handle is closed");
+        handle.open = false;
+        if (handle.idleTimer !== undefined) {
+            clearTimeout(handle.idleTimer);
+            handle.idleTimer = undefined;
+        }
+        if (this.#handles.get(handleId) === handle)
+            this.#handles.delete(handleId);
+        handle.finish(commit);
+        const settlement = handle.done.catch((error) => {
+            if (!commit && error instanceof WriteScopeAbortedError)
+                return undefined;
+            throw error;
+        });
+        this.#settlingWritePromises.add(settlement);
+        void settlement.then(() => this.#settlingWritePromises.delete(settlement), () => this.#settlingWritePromises.delete(settlement));
+        return settlement;
+    }
     #closeLiveSet(handleId, handle) {
         handle.set.close();
         for (const subscriptionId of handle.subscriptionIds)
@@ -433,18 +836,51 @@ class DatabaseRpcServer {
     }
     async #dispose() {
         this.#disposed = true;
+        this.#reservedHandleIds.clear();
         const handles = [...this.#handles.entries()];
         this.#handles.clear();
+        const handleCleanup = [];
+        // Stop every abandoned-write deadline before waiting on active calls. The cleared handle map
+        // also prevents their completions from rearming one while disposal is in progress.
+        for (const [, handle] of handles) {
+            if (handle.type === "write" && handle.idleTimer !== undefined) {
+                clearTimeout(handle.idleTimer);
+                handle.idleTimer = undefined;
+            }
+        }
+        // Signal every handle before awaiting any cleanup. Imports and iterators can have an admitted
+        // RPC blocked inside them; closing sequentially could wait on the first while never reaching
+        // the signal that lets a later one finish.
         for (const [handleId, handle] of handles) {
             try {
-                if (handle.type === "snapshot")
+                if (handle.type === "snapshot") {
                     handle.release();
+                    handleCleanup.push(handle.done.catch(() => undefined));
+                }
                 else if (handle.type === "write") {
-                    handle.finish(false);
-                    await handle.done.catch(() => undefined);
+                    // A session operation owns the transaction revision until it returns. Aborting sooner
+                    // can race its final journal update and leave an active owner until TTL. Once it exits,
+                    // abort only if commit/abort/idle expiry has not already chosen a terminal outcome.
+                    handleCleanup.push((async () => {
+                        await handle.activeCallDone;
+                        if (handle.open) {
+                            await this.#settleWriteHandle(handleId, handle, false).catch(() => undefined);
+                        }
+                    })());
                 }
                 else if (handle.type === "writer")
-                    await handle.writer.close();
+                    handleCleanup.push(handle.writer.close());
+                else if (handle.type === "query-cursor") {
+                    handleCleanup.push(Promise.resolve(handle.iterator.return?.()));
+                }
+                else if (handle.type === "snapshot-export") {
+                    handleCleanup.push(Promise.resolve(handle.iterator.return?.()));
+                }
+                else if (handle.type === "snapshot-import") {
+                    handle.abort.abort(new Error("Database connection was disposed"));
+                    handle.queue.fail(new Error("Database connection was disposed"));
+                    handleCleanup.push(handle.task.catch(() => undefined));
+                }
                 else if (handle.type === "live-set")
                     this.#closeLiveSet(handleId, handle);
             }
@@ -452,9 +888,30 @@ class DatabaseRpcServer {
                 // Dispose every handle even when one close fails; the client is already gone.
             }
         }
+        await Promise.allSettled(handleCleanup);
+        // Commit/abort/expiry removes its handle before durable settlement completes so late RPCs
+        // fail closed. Join those detached operations before closing the database or injected store.
+        while (this.#settlingWritePromises.size > 0) {
+            await Promise.allSettled([...this.#settlingWritePromises]);
+        }
+        // A handle whose lease admission was already in flight when disposal began is not yet in the
+        // handle map. Its opener observes the disposed publication, releases any admitted lease, and
+        // settles only after that cleanup is complete.
+        while (this.#openingHandlePromises.size > 0) {
+            await Promise.allSettled([...this.#openingHandlePromises]);
+        }
+        await this.#waitForInFlightRpcs();
         await this.database.close();
         await this.options.onDispose?.();
     }
+    #waitForInFlightRpcs() {
+        if (this.#inFlightRpcCount === 0)
+            return Promise.resolve();
+        this.#inFlightRpcDrain ??= new Promise((resolve) => {
+            this.#resolveInFlightRpcDrain = resolve;
+        });
+        return this.#inFlightRpcDrain;
+    }
 }
 /**
  * Answers client RPC frames against a database you constructed yourself. Use this in a custom
@@ -535,6 +992,9 @@ async function createServer(scope, payload, options) {
     const store = await createStore(payload.store, options);
     const database = new MinnowDatabase(store, payload.options ?? {});
     return new DatabaseRpcServer(database, scope, {
+        ...(payload.options?.transactionIdleTimeoutMs === undefined
+            ? {}
+            : { writeHandleIdleTimeoutMs: payload.options.transactionIdleTimeoutMs }),
         onDispose: () => store.close(),
         onVisibility: (visible) => {
             store.setForeground?.(visible);
@@ -576,4 +1036,8 @@ function requestIdOf(value) {
     }
     return undefined;
 }
-//# sourceMappingURL=worker-host.js.map
+/** A worker cleanup deadline must not keep a Node process alive by itself. */
+function unrefTimer(timer) {
+    const candidate = timer;
+    candidate.unref?.();
+}