@minnowdb/core 0.2.1 → 0.4.0

package/dist/storage/opfs/store.js

@@ -1,8 +1,9 @@
-import { validateId, validateTempRunPage, validateTempRunPageIdentity, } from "../toolkit/record-core.js";
+import { assertStorageBulkReadItems, assertTempRunPageBatchLimits, OpfsUncertainOutcomeError, StorageCorruptionError, StorageFormatVersionError, validateStorageDatabaseName, } from "../types.js";
+import { validateTempRunPage, validateTempRunPageIdentity } from "../toolkit/record-core.js";
 import { OpfsTree, encodeSegment, isDomError } from "./files.js";
 import { LOG_FORMAT_VERSION } from "../toolkit/wire.js";
 import { OpfsLeader } from "./leader.js";
-import { rehydrateStoreError, serializeStoreError, } from "./rpc.js";
+import { rehydrateStoreError, estimateRpcValueBytes, fingerprintStoreRequest, MAX_OPFS_RPC_MESSAGE_BYTES, parseStoreRpcMessage, serializeStoreError, } from "./rpc.js";
 /** How long a follower waits for a leader's answer before assuming it is gone. */
 const RPC_TIMEOUT_MS = 1_000;
 /** How long a ping waits for a leadership announcement. */
@@ -13,52 +14,81 @@ const DISPATCH_ATTEMPTS = 10;
 const YIELD_COOLDOWN_MS = 3_000;
 /** Results remembered for retried requests whose acknowledgement was lost. */
 const DEDUPE_CACHE_SIZE = 512;
+/** Requests admitted concurrently by either side of the follower protocol. */
+const RPC_IN_FLIGHT_LIMIT = 512;
+const RPC_IN_FLIGHT_MUTATION_BYTES = 128 * 1024 * 1024;
+const RPC_IN_FLIGHT_READ_BYTES = 256 * 1024 * 1024;
+const RPC_SETTLED_OUTCOME_BYTES = 128 * 1024 * 1024;
+const RPC_SERVER_ADMISSION_LIMIT = 1024;
+const RPC_SERVER_ADMISSION_BYTES = 256 * 1024 * 1024;
 /** Channels into requesters' inboxes a leader keeps open between answers. */
 const ANSWER_CHANNEL_CACHE_SIZE = 64;
+const BULK_READ_ARGUMENT_INDEX = {
+    getBlocks: 0,
+    getTransactions: 0,
+    getExistingUniqueKeys: 1,
+    hasManifestBlocks: 1,
+};
 /** Methods a follower may invoke on the leader. Temp-page IO is instance-local by design. */
 const RPC_METHODS = new Set([
-    "addBlock",
-    "addBlocks",
     "getBlock",
     "getBlocks",
-    "removeBlock",
-    "listBlockIds",
+    "readManifestBlock",
+    "hasManifestBlocks",
+    "listManifestBlockPage",
+    "listRetiredManifestBlockPage",
     "addTable",
     "getTable",
     "getTableByName",
     "listTables",
     "updateTable",
     "removeTable",
+    "dropTable",
+    "dropTableColumn",
+    "removeFtsColumn",
     "writeFtsBase",
+    "beginFtsBaseBuild",
+    "renewFtsBaseBuild",
+    "writeFtsBaseBuildChunk",
+    "finishFtsBaseBuild",
+    "abortFtsBaseBuild",
     "readFtsCandidates",
-    "addSegment",
+    "readFtsPostings",
     "getSegment",
-    "listSegments",
-    "removeSegment",
+    "listSegmentPage",
+    "listTableSegmentPage",
+    "removeAbortedSegment",
+    "adoptAbortedSegment",
     "reserveRowIds",
     "reserveAutoIncrement",
     "getExistingUniqueKeys",
+    "beginUniqueKeyBuild",
+    "getUniqueKeyBuild",
+    "renewUniqueKeyBuild",
+    "appendUniqueKeyBuildChunk",
+    "finishUniqueKeyBuild",
+    "abortUniqueKeyBuild",
     "getCurrentManifest",
     "getCurrentManifestVersion",
     "getCatalogProbe",
-    "getQueryCatalogState",
     "getManifest",
-    "listManifests",
     "listManifestPage",
-    "publishManifest",
     "createTransaction",
+    "renewTransaction",
+    "abortTransactionIfExpired",
     "beginTransaction",
     "getTransaction",
     "getTransactions",
-    "listTransactions",
     "listTransactionPage",
     "updateTransaction",
     "stageTransactionArtifacts",
+    "rollbackTransactionArtifacts",
     "commitTransaction",
     "writeTransaction",
     "createLease",
     "getLease",
     "listLeases",
+    "listExpiredLeasePage",
     "renewLease",
     "moveLease",
     "removeLeaseIfExpired",
@@ -71,20 +101,35 @@ const RPC_METHODS = new Set([
     "cancelCompactionJob",
     "removeCompactionJob",
     "createGarbageCollectionJob",
+    "updateGarbageCollectionPlanning",
     "getGarbageCollectionJob",
     "listGarbageCollectionJobs",
+    "listGarbageCollectionJobPage",
     "runGarbageCollectionStep",
     "removePrunedManifestRecords",
     "removeGarbageCollectionJob",
     "createTempOwner",
     "getTempOwner",
+    "putTempRunPage",
+    "putTempRunPages",
+    "getTempRunPage",
+    "removeTempRun",
     "renewTempOwner",
     "removeTempOwnerIfExpired",
     "removeTempOwner",
     "listTempOwnerIdsPage",
+    "listExpiredTempOwnerPage",
     "getLogicalStorageBytes",
-    "exportSnapshot",
-    "importSnapshot",
+    "getStorageStats",
+    "checkIntegrity",
+    "beginSnapshotFrameExport",
+    "readSnapshotExportFrame",
+    "closeSnapshotFrameExport",
+    "beginSnapshotFrameImport",
+    "renewSnapshotFrameImport",
+    "appendSnapshotImportFrames",
+    "finishSnapshotFrameImport",
+    "cancelSnapshotFrameImport",
 ]);
 /**
  * Reads are idempotent — a lost-acknowledgement retry can simply run again — so only
@@ -94,68 +139,56 @@ const RPC_METHODS = new Set([
 const READ_METHODS = new Set([
     "getBlock",
     "getBlocks",
-    "listBlockIds",
+    "readManifestBlock",
+    "hasManifestBlocks",
+    "listManifestBlockPage",
+    "listRetiredManifestBlockPage",
     "getTable",
     "getTableByName",
     "listTables",
     "readFtsCandidates",
+    "readFtsPostings",
     "getSegment",
-    "listSegments",
+    "listSegmentPage",
+    "listTableSegmentPage",
     "getExistingUniqueKeys",
+    "getUniqueKeyBuild",
     "getCurrentManifest",
     "getCurrentManifestVersion",
     "getCatalogProbe",
-    "getQueryCatalogState",
     "getManifest",
-    "listManifests",
     "listManifestPage",
     "getTransaction",
     "getTransactions",
-    "listTransactions",
     "listTransactionPage",
     "getLease",
     "listLeases",
+    "listExpiredLeasePage",
     "getCompactionJob",
     "listCompactionJobs",
     "listCompactionJobPage",
     "getGarbageCollectionJob",
     "listGarbageCollectionJobs",
+    "listGarbageCollectionJobPage",
     "getTempOwner",
+    "getTempRunPage",
     "listTempOwnerIdsPage",
+    "listExpiredTempOwnerPage",
     "getLogicalStorageBytes",
-    "exportSnapshot",
+    "getStorageStats",
+    "checkIntegrity",
+    "readSnapshotExportFrame",
 ]);
-/**
- * The OPFS block store: one leader per database holds every file handle and does all storage
- * work at held-handle speed; other connections are thin followers whose operations travel a
- * `BroadcastChannel` to it.
- *
- * Two kinds of channel carry the protocol. One shared channel per database carries what every
- * connection must hear: leader announcements, pings, bids, yields, releases. Every connection
- * also owns an inbox — a channel named for its instance id — where the messages meant for it
- * alone arrive: operations at the leader, results and busy notices at the requester. A block
- * read's bytes are therefore structured-cloned once, into the tab that asked, rather than into
- * every tab of the origin.
- *
- * Leadership is the write-ahead log's own exclusive sync-access handle — enforced by the
- * browser against the actual resource, released the instant its holder dies. Elections are
- * simply attempts to open it. Correctness never rides on a message: an operation is
- * acknowledged only after the leader's WAL holds it, a lost message costs a retry (request
- * ids deduplicate retries while the same leader serves), and a dead leader costs a failover
- * in which the next acquirer replays checkpoint-plus-WAL. A retry that crosses a failover is
- * the one case a duplicate can execute — the same "committed but the response was lost"
- * class the IndexedDB store has — and it resolves the same way: compare-and-swap operations
- * surface a conflict the engine's recovery already reconciles. The channel affects how fast
- * multi-tab work moves, never whether it is right.
- *
- * `setForeground(true)` marks this connection as the one the user is looking at; a background
- * leader yields to a foreground bidder, so the tab doing the work is normally the tab holding
- * the microsecond-fast path.
- */
+function sameServedRequest(remembered, message, signature) {
+    return remembered.method === message.method && remembered.signature === signature;
+}
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class OpfsBlockStore {
+    liveQueryChannelName;
     #tree;
     #durability;
     #checkpointEntries;
+    #cleanupLimitBytes;
     #rpcTimeoutMs;
     #instanceId = crypto.randomUUID();
     #channelName;
@@ -172,14 +205,26 @@ export class OpfsBlockStore {
     #lastYieldAt = 0;
     #electing;
     #pending = new Map();
-    #dedupe = new Map();
+    #inFlightMutations = new Map();
+    #settledMutations = new Map();
+    #servedRequestLocks = new Map();
+    #inFlightMutationBytes = 0;
+    #inFlightReadBytes = 0;
+    #settledMutationBytes = 0;
+    #pendingRpcBytes = 0;
+    #servedRequestCount = 0;
+    #servedRequestBytes = 0;
+    #servedMutationGateForTests;
+    #dropNextRpcResultForTests = false;
     #reacquireTimer;
     constructor(tree, options) {
         this.#tree = tree;
-        this.#durability = options.durability ?? "relaxed";
+        this.#durability = options.durability ?? "strict";
         this.#checkpointEntries = options.checkpointEntries;
+        this.#cleanupLimitBytes = options.cleanupLimitBytes;
         this.#rpcTimeoutMs = options.rpcTimeoutMs ?? RPC_TIMEOUT_MS;
         this.#channelName = `minnowdb-store:${options.name}`;
+        this.liveQueryChannelName = `minnowdb-live:opfs:${options.name}`;
     }
     static async open(options) {
         const tree = new OpfsTree(await resolveDatabaseRoot(options));
@@ -187,7 +232,9 @@ export class OpfsBlockStore {
         await store.#ensureFormatMarker();
         if (typeof BroadcastChannel === "function") {
             const onMessage = (event) => {
-                store.#onMessage(event.data);
+                const message = parseStoreRpcMessage(event.data, RPC_METHODS);
+                if (message !== undefined)
+                    store.#onMessage(message);
             };
             const channel = new BroadcastChannel(store.#channelName);
             channel.onmessage = onMessage;
@@ -235,7 +282,7 @@ export class OpfsBlockStore {
             // them in sequence; the brief retry covers the gap.
             slotA = await this.#openWithRetry(["checkpoint-a"]);
             slotB = await this.#openWithRetry(["checkpoint-b"]);
-            this.#leader = await OpfsLeader.recover(this.#tree, this.#durability === "strict", { wal, slotA, slotB }, this.#checkpointEntries);
+            this.#leader = await OpfsLeader.recover(this.#tree, this.#durability === "strict", { wal, slotA, slotB }, this.#checkpointEntries, this.#cleanupLimitBytes);
         }
         catch (error) {
             wal.close();
@@ -311,15 +358,31 @@ export class OpfsBlockStore {
             return;
         switch (message.kind) {
             case "op": {
-                if (this.#leader !== undefined)
-                    void this.#serveOp(message);
+                if (this.#leader !== undefined) {
+                    const requestBytes = estimateRpcValueBytes(message.args);
+                    if (this.#servedRequestCount >= RPC_SERVER_ADMISSION_LIMIT ||
+                        this.#servedRequestBytes + requestBytes > RPC_SERVER_ADMISSION_BYTES) {
+                        this.#answer(message.from, {
+                            kind: "result",
+                            requestId: message.requestId,
+                            ok: false,
+                            error: { name: "Error", message: "The OPFS leader RPC queue is full" },
+                        });
+                        return;
+                    }
+                    this.#servedRequestCount += 1;
+                    this.#servedRequestBytes += requestBytes;
+                    void this.#serveOp(message).finally(() => {
+                        this.#servedRequestCount = Math.max(0, this.#servedRequestCount - 1);
+                        this.#servedRequestBytes = Math.max(0, this.#servedRequestBytes - requestBytes);
+                    });
+                }
                 return;
             }
             case "result": {
-                const pending = this.#pending.get(message.requestId);
+                const pending = this.#takePending(message.requestId);
                 if (pending === undefined)
                     return;
-                this.#pending.delete(message.requestId);
                 clearTimeout(pending.timer);
                 if (message.ok)
                     pending.resolve(message.value);
@@ -333,8 +396,8 @@ export class OpfsBlockStore {
                     return;
                 clearTimeout(pending.timer);
                 pending.timer = setTimeout(() => {
-                    this.#pending.delete(message.requestId);
-                    pending.reject(RPC_TIMED_OUT);
+                    const expired = this.#takePending(message.requestId);
+                    expired?.reject(RPC_TIMED_OUT);
                 }, this.#rpcTimeoutMs);
                 return;
             }
@@ -344,12 +407,17 @@ export class OpfsBlockStore {
                     clearTimeout(this.#reacquireTimer);
                     this.#reacquireTimer = undefined;
                 }
-                // A new leader never saw our in-flight requests; send those again (ids deduplicate).
-                // Requests already sitting with this same leader stay put — every ping triggers an
-                // announce, and blind re-sends would race their own in-flight executions.
-                for (const pending of this.#pending.values()) {
+                // Reads can move to the new leader. A mutation may already be durable on the old one;
+                // never execute it twice merely because its acknowledgement was lost.
+                for (const [requestId, pending] of this.#pending) {
                     if (pending.sentTo === message.leaderId)
                         continue;
+                    if (!READ_METHODS.has(pending.message.method)) {
+                        this.#takePending(requestId);
+                        clearTimeout(pending.timer);
+                        pending.reject(new OpfsUncertainOutcomeError(pending.message.method));
+                        continue;
+                    }
                     pending.sentTo = message.leaderId;
                     this.#send(message.leaderId, pending.message);
                 }
@@ -387,31 +455,133 @@ export class OpfsBlockStore {
             }
         }
     }
+    #takePending(requestId) {
+        const pending = this.#pending.get(requestId);
+        if (pending === undefined)
+            return undefined;
+        this.#pending.delete(requestId);
+        this.#pendingRpcBytes -= pending.retainedBytes;
+        return pending;
+    }
     async #serveOp(message) {
+        const requestKey = `${String(message.from.length)}:${message.from}${message.requestId}`;
+        // Once an identity is admitted, duplicates can compare their fingerprint immediately and
+        // either attach to the exact execution or fail closed. The short lock below exists only for
+        // the pre-admission fingerprint race between two first deliveries.
+        if (this.#inFlightMutations.has(requestKey) || this.#settledMutations.has(requestKey)) {
+            await this.#serveOpLocked(message, requestKey);
+            return;
+        }
+        const previous = this.#servedRequestLocks.get(requestKey) ?? Promise.resolve();
+        let release;
+        const hold = new Promise((resolve) => {
+            release = resolve;
+        });
+        const tail = previous.then(() => hold);
+        this.#servedRequestLocks.set(requestKey, tail);
+        await previous;
+        try {
+            await this.#serveOpLocked(message, requestKey);
+        }
+        finally {
+            release();
+            if (this.#servedRequestLocks.get(requestKey) === tail) {
+                this.#servedRequestLocks.delete(requestKey);
+            }
+        }
+    }
+    async #serveOpLocked(message, requestKey) {
         const leader = this.#leader;
         if (leader === undefined || !RPC_METHODS.has(message.method))
             return;
-        let outcome = this.#dedupe.get(message.requestId);
-        if (outcome === undefined) {
-            outcome = this.#executeServedOp(leader, message);
-            // Only mutations need at-most-once; reads simply run again on a retried request, and
-            // caching their results (block bytes included) would be pure memory waste.
-            if (!READ_METHODS.has(message.method)) {
-                this.#dedupe.set(message.requestId, outcome);
-                if (this.#dedupe.size > DEDUPE_CACHE_SIZE) {
-                    const [oldest] = this.#dedupe.keys();
-                    if (oldest !== undefined)
-                        this.#dedupe.delete(oldest);
-                }
+        const isRead = READ_METHODS.has(message.method);
+        let fingerprint;
+        try {
+            fingerprint = await fingerprintStoreRequest(message.method, message.args);
+        }
+        catch {
+            return;
+        }
+        const remembered = isRead ? undefined : this.#settledMutations.get(requestKey);
+        let settled;
+        if (remembered !== undefined) {
+            if (!sameServedRequest(remembered, message, fingerprint.signature)) {
+                this.#rejectReusedRequestIdentity(message);
+                return;
             }
+            // Refresh bounded settled outcomes as an LRU. This is the lost-ack retry path.
+            this.#settledMutations.delete(requestKey);
+            this.#settledMutations.set(requestKey, remembered);
+            settled = remembered.outcome;
         }
-        else {
-            // A duplicate of a request that is still running (or already remembered): attach to it
-            // rather than executing twice, and reset the caller's patience meanwhile — the original
-            // may legitimately take longer than one timeout (a snapshot import, a checkpoint pause).
+        else if (!isRead && this.#inFlightMutations.has(requestKey)) {
+            const inFlight = this.#inFlightMutations.get(requestKey);
+            if (inFlight === undefined)
+                throw new Error("In-flight RPC identity disappeared");
+            if (!sameServedRequest(inFlight, message, fingerprint.signature)) {
+                this.#rejectReusedRequestIdentity(message);
+                return;
+            }
+            // Never evict an in-flight mutation. A duplicate attaches to the one execution and resets
+            // the requester's patience while it remains queued or running.
             this.#answer(message.from, { kind: "busy", requestId: message.requestId });
+            settled = await inFlight.outcome;
+        }
+        else {
+            if (!isRead &&
+                (this.#inFlightMutations.size >= RPC_IN_FLIGHT_LIMIT ||
+                    this.#inFlightMutationBytes + fingerprint.retainedBytes > RPC_IN_FLIGHT_MUTATION_BYTES)) {
+                this.#answer(message.from, {
+                    kind: "result",
+                    requestId: message.requestId,
+                    ok: false,
+                    error: { name: "Error", message: "The OPFS leader mutation queue is full" },
+                });
+                return;
+            }
+            if (isRead) {
+                const reservation = Math.max(fingerprint.retainedBytes, MAX_OPFS_RPC_MESSAGE_BYTES);
+                if (this.#inFlightReadBytes + reservation > RPC_IN_FLIGHT_READ_BYTES) {
+                    this.#answer(message.from, {
+                        kind: "result",
+                        requestId: message.requestId,
+                        ok: false,
+                        error: { name: "Error", message: "The OPFS leader read queue is full" },
+                    });
+                    return;
+                }
+                this.#inFlightReadBytes += reservation;
+                try {
+                    settled = await this.#executeServedOpAfterGate(leader, message, true);
+                }
+                finally {
+                    this.#inFlightReadBytes = Math.max(0, this.#inFlightReadBytes - reservation);
+                }
+            }
+            else {
+                this.#inFlightMutationBytes += fingerprint.retainedBytes;
+                const execution = this.#executeServedOpAfterGate(leader, message, false);
+                const outcome = execution.then((result) => {
+                    this.#inFlightMutations.delete(requestKey);
+                    this.#inFlightMutationBytes = Math.max(0, this.#inFlightMutationBytes - fingerprint.retainedBytes);
+                    if (!this.#closed) {
+                        this.#rememberSettledMutation(requestKey, message.method, fingerprint, result);
+                    }
+                    return result;
+                });
+                this.#inFlightMutations.set(requestKey, {
+                    method: message.method,
+                    signature: fingerprint.signature,
+                    requestBytes: fingerprint.retainedBytes,
+                    outcome,
+                });
+                settled = await outcome;
+            }
+        }
+        if (this.#dropNextRpcResultForTests) {
+            this.#dropNextRpcResultForTests = false;
+            return;
         }
-        const settled = await outcome;
         this.#answer(message.from, settled.ok
             ? { kind: "result", requestId: message.requestId, ok: true, value: settled.value }
             : {
@@ -421,6 +591,45 @@ export class OpfsBlockStore {
                 error: settled.error ?? { name: "Error", message: "unknown" },
             });
     }
+    #rememberSettledMutation(requestKey, method, fingerprint, outcome) {
+        const outcomeBytes = estimateRpcValueBytes(outcome);
+        while (this.#settledMutations.size >= DEDUPE_CACHE_SIZE ||
+            this.#settledMutationBytes + outcomeBytes > RPC_SETTLED_OUTCOME_BYTES) {
+            const oldest = this.#settledMutations.keys().next().value;
+            if (oldest === undefined)
+                break;
+            const removed = this.#settledMutations.get(oldest);
+            this.#settledMutations.delete(oldest);
+            this.#settledMutationBytes -= removed?.outcomeBytes ?? 0;
+        }
+        if (outcomeBytes > RPC_SETTLED_OUTCOME_BYTES)
+            return;
+        this.#settledMutations.set(requestKey, {
+            method,
+            signature: fingerprint.signature,
+            requestBytes: fingerprint.retainedBytes,
+            outcome,
+            outcomeBytes,
+        });
+        this.#settledMutationBytes += outcomeBytes;
+    }
+    #rejectReusedRequestIdentity(message) {
+        this.#answer(message.from, {
+            kind: "result",
+            requestId: message.requestId,
+            ok: false,
+            error: {
+                name: "Error",
+                message: "The OPFS RPC request identity was reused with different contents",
+            },
+        });
+    }
+    async #executeServedOpAfterGate(leader, message, isRead) {
+        const gate = this.#servedMutationGateForTests;
+        if (!isRead && gate !== undefined)
+            await gate;
+        return this.#executeServedOp(leader, message);
+    }
     async #executeServedOp(leader, message) {
         try {
             const method = leader[message.method];
@@ -542,6 +751,8 @@ export class OpfsBlockStore {
             catch (error) {
                 if (error === RPC_TIMED_OUT) {
                     this.#knownLeader = undefined;
+                    if (!READ_METHODS.has(method))
+                        throw new OpfsUncertainOutcomeError(method);
                     continue;
                 }
                 throw error;
@@ -554,14 +765,33 @@ export class OpfsBlockStore {
         return this.#knownLeader !== undefined;
     }
     #rpc(requestId, method, args) {
+        let retainedBytes;
+        try {
+            retainedBytes = estimateRpcValueBytes(args);
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+        if (this.#pending.size >= RPC_IN_FLIGHT_LIMIT ||
+            this.#pendingRpcBytes + retainedBytes > RPC_IN_FLIGHT_MUTATION_BYTES) {
+            return Promise.reject(new Error("The OPFS follower request queue is full"));
+        }
         return new Promise((resolve, reject) => {
             const message = { kind: "op", requestId, from: this.#instanceId, method, args };
             const timer = setTimeout(() => {
-                this.#pending.delete(requestId);
-                reject(RPC_TIMED_OUT);
+                const expired = this.#takePending(requestId);
+                expired?.reject(RPC_TIMED_OUT);
             }, this.#rpcTimeoutMs);
             const leaderId = this.#knownLeader;
-            this.#pending.set(requestId, { message, sentTo: leaderId, resolve, reject, timer });
+            this.#pending.set(requestId, {
+                message,
+                retainedBytes,
+                sentTo: leaderId,
+                resolve,
+                reject,
+                timer,
+            });
+            this.#pendingRpcBytes += retainedBytes;
             // The dispatch loop only gets here with a leader known; should it have slipped away in
             // between, the timeout (or the next leader's announcement, which re-sends) takes over.
             if (leaderId !== undefined)
@@ -571,286 +801,35 @@ export class OpfsBlockStore {
     // ---------------------------------------------------------------------------------------
     // The BlockStore surface.
     // ---------------------------------------------------------------------------------------
-    async addBlock(id, bytes) {
-        await this.#dispatch("addBlock", [id, bytes]);
-    }
-    async addBlocks(blocks) {
-        await this.#dispatch("addBlocks", [blocks]);
-    }
-    async getBlock(id) {
-        return (await this.#dispatch("getBlock", [id]));
-    }
-    async getBlocks(ids) {
-        return (await this.#dispatch("getBlocks", [ids]));
-    }
-    async removeBlock(id) {
-        await this.#dispatch("removeBlock", [id]);
-    }
-    async listBlockIds() {
-        return (await this.#dispatch("listBlockIds", []));
-    }
     async putTempRunPage(page) {
         validateTempRunPage(page);
-        await this.#tree.writeFile(["temp", encodeSegment(page.ownerId), encodeSegment(page.runId), String(page.pageIndex)], page.bytes);
+        await this.#dispatch("putTempRunPage", [page]);
     }
     async putTempRunPages(pages) {
         // Spill pages are instance-local files; the batch is a convenience, not a round-trip win.
+        assertTempRunPageBatchLimits(pages);
         for (const page of pages)
-            await this.putTempRunPage(page);
+            validateTempRunPage(page);
+        await this.#dispatch("putTempRunPages", [pages]);
     }
     async getTempRunPage(ownerId, runId, pageIndex) {
         validateTempRunPageIdentity(ownerId, runId, pageIndex);
-        return this.#tree.readFile([
-            "temp",
-            encodeSegment(ownerId),
-            encodeSegment(runId),
-            String(pageIndex),
-        ]);
+        return (await this.#dispatch("getTempRunPage", [ownerId, runId, pageIndex]));
     }
     async removeTempRun(ownerId, runId) {
         validateTempRunPageIdentity(ownerId, runId, 0);
-        await this.#tree.deleteTree(["temp", encodeSegment(ownerId), encodeSegment(runId)]);
-    }
-    async removeTempOwner(ownerId) {
-        validateId(ownerId);
-        await this.#dispatch("removeTempOwner", [ownerId]);
-        await this.#tree.deleteTree(["temp", encodeSegment(ownerId)]);
-    }
-    async createTempOwner(record) {
-        await this.#dispatch("createTempOwner", [record]);
-    }
-    async getTempOwner(ownerId) {
-        return (await this.#dispatch("getTempOwner", [ownerId]));
-    }
-    async renewTempOwner(ownerId, expectedRevision, expiresAt) {
-        return (await this.#dispatch("renewTempOwner", [
-            ownerId,
-            expectedRevision,
-            expiresAt,
-        ]));
-    }
-    async removeTempOwnerIfExpired(ownerId, expiresAtCutoff) {
-        const removed = (await this.#dispatch("removeTempOwnerIfExpired", [
-            ownerId,
-            expiresAtCutoff,
-        ]));
-        if (removed)
-            await this.#tree.deleteTree(["temp", encodeSegment(ownerId)]);
-        return removed;
-    }
-    async listTempOwnerIdsPage(afterOwnerId, limit) {
-        return (await this.#dispatch("listTempOwnerIdsPage", [afterOwnerId, limit]));
-    }
-    async addTable(record) {
-        await this.#dispatch("addTable", [record]);
-    }
-    async getTable(id) {
-        return (await this.#dispatch("getTable", [id]));
-    }
-    async getTableByName(name) {
-        return (await this.#dispatch("getTableByName", [name]));
-    }
-    async listTables() {
-        return (await this.#dispatch("listTables", []));
-    }
-    async updateTable(id, expectedRevision, update) {
-        return (await this.#dispatch("updateTable", [id, expectedRevision, update]));
-    }
-    async removeTable(id, expectedRevision) {
-        await this.#dispatch("removeTable", [id, expectedRevision]);
-    }
-    async writeFtsBase(tableId, columnId, input) {
-        await this.#dispatch("writeFtsBase", [tableId, columnId, input]);
-    }
-    async readFtsCandidates(tableId, columnId, terms, upToVersion) {
-        return (await this.#dispatch("readFtsCandidates", [
-            tableId,
-            columnId,
-            terms,
-            upToVersion,
-        ]));
-    }
-    async addSegment(record) {
-        await this.#dispatch("addSegment", [record]);
-    }
-    async getSegment(id) {
-        return (await this.#dispatch("getSegment", [id]));
-    }
-    async listSegments(tableId) {
-        return (await this.#dispatch("listSegments", [tableId]));
-    }
-    async removeSegment(id) {
-        await this.#dispatch("removeSegment", [id]);
-    }
-    async reserveRowIds(tableId, count) {
-        return (await this.#dispatch("reserveRowIds", [tableId, count]));
-    }
-    async reserveAutoIncrement(tableId, columnId, count, atLeast) {
-        return (await this.#dispatch("reserveAutoIncrement", [
-            tableId,
-            columnId,
-            count,
-            atLeast,
-        ]));
-    }
-    async getExistingUniqueKeys(tableId, keyTokens) {
-        return (await this.#dispatch("getExistingUniqueKeys", [tableId, keyTokens]));
-    }
-    async getCurrentManifest() {
-        return (await this.#dispatch("getCurrentManifest", []));
-    }
-    async getCurrentManifestVersion() {
-        return (await this.#dispatch("getCurrentManifestVersion", []));
-    }
-    async getCatalogProbe() {
-        return (await this.#dispatch("getCatalogProbe", []));
-    }
-    async getQueryCatalogState(tableNames) {
-        return (await this.#dispatch("getQueryCatalogState", [tableNames]));
-    }
-    async getManifest(version) {
-        return (await this.#dispatch("getManifest", [version]));
-    }
-    async listManifests() {
-        return (await this.#dispatch("listManifests", []));
-    }
-    async listManifestPage(afterVersion, limit) {
-        return (await this.#dispatch("listManifestPage", [afterVersion, limit]));
-    }
-    async publishManifest(input) {
-        return (await this.#dispatch("publishManifest", [input]));
-    }
-    async createTransaction(record) {
-        await this.#dispatch("createTransaction", [record]);
-    }
-    async beginTransaction(input) {
-        return (await this.#dispatch("beginTransaction", [input]));
-    }
-    async getTransaction(id) {
-        return (await this.#dispatch("getTransaction", [id]));
-    }
-    async getTransactions(ids) {
-        return (await this.#dispatch("getTransactions", [ids]));
-    }
-    async listTransactions() {
-        return (await this.#dispatch("listTransactions", []));
-    }
-    async listTransactionPage(afterId, limit) {
-        return (await this.#dispatch("listTransactionPage", [afterId, limit]));
-    }
-    async updateTransaction(id, expectedRevision, update) {
-        return (await this.#dispatch("updateTransaction", [
-            id,
-            expectedRevision,
-            update,
-        ]));
-    }
-    async stageTransactionArtifacts(input) {
-        return (await this.#dispatch("stageTransactionArtifacts", [input]));
-    }
-    async commitTransaction(input) {
-        return (await this.#dispatch("commitTransaction", [input]));
-    }
-    async writeTransaction(input) {
-        return (await this.#dispatch("writeTransaction", [input]));
-    }
-    async createLease(record) {
-        await this.#dispatch("createLease", [record]);
-    }
-    async getLease(id) {
-        return (await this.#dispatch("getLease", [id]));
-    }
-    async listLeases() {
-        return (await this.#dispatch("listLeases", []));
-    }
-    async renewLease(id, expectedRevision, expiresAt) {
-        return (await this.#dispatch("renewLease", [id, expectedRevision, expiresAt]));
-    }
-    async moveLease(id, expectedRevision, manifestVersion, expiresAt) {
-        return (await this.#dispatch("moveLease", [
-            id,
-            expectedRevision,
-            manifestVersion,
-            expiresAt,
-        ]));
-    }
-    async removeLeaseIfExpired(id, expectedRevision, expiresAtCutoff) {
-        return (await this.#dispatch("removeLeaseIfExpired", [
-            id,
-            expectedRevision,
-            expiresAtCutoff,
-        ]));
-    }
-    async removeLease(id) {
-        await this.#dispatch("removeLease", [id]);
-    }
-    async createCompactionJob(record) {
-        await this.#dispatch("createCompactionJob", [record]);
-    }
-    async getCompactionJob(id) {
-        return (await this.#dispatch("getCompactionJob", [id]));
-    }
-    async listCompactionJobs(tableId) {
-        return (await this.#dispatch("listCompactionJobs", [tableId]));
-    }
-    async listCompactionJobPage(afterId, limit) {
-        return (await this.#dispatch("listCompactionJobPage", [afterId, limit]));
-    }
-    async updateCompactionJob(id, expectedRevision, update) {
-        return (await this.#dispatch("updateCompactionJob", [
-            id,
-            expectedRevision,
-            update,
-        ]));
-    }
-    async cancelCompactionJob(id, expectedRevision, cancelledAt) {
-        return (await this.#dispatch("cancelCompactionJob", [
-            id,
-            expectedRevision,
-            cancelledAt,
-        ]));
-    }
-    async removeCompactionJob(id) {
-        await this.#dispatch("removeCompactionJob", [id]);
-    }
-    async createGarbageCollectionJob(input) {
-        return (await this.#dispatch("createGarbageCollectionJob", [
-            input,
-        ]));
-    }
-    async getGarbageCollectionJob(id) {
-        return (await this.#dispatch("getGarbageCollectionJob", [id]));
-    }
-    async listGarbageCollectionJobs() {
-        return (await this.#dispatch("listGarbageCollectionJobs", []));
-    }
-    async runGarbageCollectionStep(input) {
-        return (await this.#dispatch("runGarbageCollectionStep", [
-            input,
-        ]));
-    }
-    async removeGarbageCollectionJob(id) {
-        await this.#dispatch("removeGarbageCollectionJob", [id]);
-    }
-    async removePrunedManifestRecords() {
-        return (await this.#dispatch("removePrunedManifestRecords", []));
-    }
-    async getLogicalStorageBytes() {
-        return (await this.#dispatch("getLogicalStorageBytes", []));
-    }
-    async exportSnapshot() {
-        return (await this.#dispatch("exportSnapshot", []));
-    }
-    async importSnapshot(snapshot, options = {}) {
-        const leader = this.#leader;
-        if (leader !== undefined) {
-            return leader.importSnapshot(snapshot, options);
+        await this.#dispatch("removeTempRun", [ownerId, runId]);
+    }
+    /** @internal Shared implementation installed for every ordinary RPC method below. */
+    async _dispatchGenerated(method, args) {
+        const bulkIndex = BULK_READ_ARGUMENT_INDEX[method];
+        if (bulkIndex !== undefined) {
+            const bulkItems = args[bulkIndex];
+            if (!Array.isArray(bulkItems))
+                throw new TypeError(`${method} items must be an array`);
+            assertStorageBulkReadItems(bulkItems, `${method} request`);
         }
-        // The progress callback cannot cross the channel; report the two ends locally.
-        const totalBytes = snapshot.blocks.reduce((total, block) => total + block.bytes.byteLength, 0);
-        options.onProgress?.({ phase: "blocks", writtenBytes: 0, totalBytes });
-        await this.#dispatch("importSnapshot", [snapshot, {}]);
-        options.onProgress?.({ phase: "done", writtenBytes: totalBytes, totalBytes });
+        return this.#dispatch(method, args);
     }
     close() {
         if (this.#closed)
@@ -863,6 +842,15 @@ export class OpfsBlockStore {
             pending.reject(new Error("This OPFS store connection is closed"));
         }
         this.#pending.clear();
+        this.#inFlightMutations.clear();
+        this.#settledMutations.clear();
+        this.#servedRequestLocks.clear();
+        this.#pendingRpcBytes = 0;
+        this.#inFlightMutationBytes = 0;
+        this.#inFlightReadBytes = 0;
+        this.#settledMutationBytes = 0;
+        this.#servedRequestCount = 0;
+        this.#servedRequestBytes = 0;
         const leader = this.#leader;
         this.#leader = undefined;
         if (leader !== undefined) {
@@ -887,6 +875,45 @@ export class OpfsBlockStore {
     _instanceIdForTests() {
         return this.#instanceId;
     }
+    /** Test-only: simulates an acknowledgement lost after the served operation settles. */
+    _dropNextRpcResultForTests() {
+        this.#dropNextRpcResultForTests = true;
+    }
+    /** Test-only: holds newly admitted served mutations until the returned release is called. */
+    _holdServedMutationsForTests() {
+        if (this.#servedMutationGateForTests !== undefined) {
+            throw new Error("Served mutations are already held");
+        }
+        let release;
+        this.#servedMutationGateForTests = new Promise((resolve) => {
+            release = resolve;
+        });
+        return () => {
+            this.#servedMutationGateForTests = undefined;
+            release();
+        };
+    }
+    /** Test-only: retransmits the oldest request with its stable deduplication identity. */
+    _resendOldestPendingForTests() {
+        const pending = this.#pending.values().next().value;
+        if (pending?.sentTo !== undefined)
+            this.#send(pending.sentTo, pending.message);
+    }
+    /** Test-only counters that pin the connection's bounded RPC state and close-time cleanup. */
+    _residentStateForTests() {
+        return {
+            answerChannels: this.#answerChannels.size,
+            dedupeEntries: this.#settledMutations.size,
+            inFlightMutations: this.#inFlightMutations.size,
+            pendingRequests: this.#pending.size,
+            retainedRpcBytes: this.#pendingRpcBytes +
+                this.#inFlightMutationBytes +
+                this.#inFlightReadBytes +
+                this.#settledMutationBytes +
+                this.#servedRequestBytes,
+            closed: this.#closed,
+        };
+    }
     /** Test-only: what tab death looks like — locks release, nothing flushes, no goodbyes. */
     _crashForTests() {
         this.#closed = true;
@@ -895,46 +922,110 @@ export class OpfsBlockStore {
         for (const pending of this.#pending.values())
             clearTimeout(pending.timer);
         this.#pending.clear();
+        this.#inFlightMutations.clear();
+        this.#settledMutations.clear();
+        this.#servedRequestLocks.clear();
+        this.#pendingRpcBytes = 0;
+        this.#inFlightMutationBytes = 0;
+        this.#inFlightReadBytes = 0;
+        this.#settledMutationBytes = 0;
+        this.#servedRequestCount = 0;
+        this.#servedRequestBytes = 0;
         this.#leader?.crash();
         this.#leader = undefined;
         this.#closeChannels();
     }
     async #ensureFormatMarker() {
-        const existing = await this.#tree.readFile(["format.json"], { lockedMeansAbsent: true });
+        const existing = await this.#tree.readFile(["format.json"], {
+            lockedMeansAbsent: true,
+            maxBytes: 1024,
+        });
         if (existing !== undefined) {
             try {
-                const parsed = JSON.parse(new TextDecoder().decode(existing));
-                if (typeof parsed.formatVersion === "number" &&
-                    parsed.formatVersion !== LOG_FORMAT_VERSION) {
-                    throw new Error(`This database uses OPFS layout version ${String(parsed.formatVersion)}; this build ` +
-                        `reads version ${String(LOG_FORMAT_VERSION)}. Delete it with deleteOpfsDatabase() — ` +
-                        `earlier layouts were experimental and carry no compatibility promise.`);
-                }
+                this.#validateFormatMarker(existing);
                 return;
             }
             catch (error) {
                 if (!(error instanceof SyntaxError))
                     throw error;
-                // A torn marker from a crashed first open: rewrite it below.
+                // A torn marker from a crashed first open is repairable only while no database
+                // artifacts exist. Never stamp the current version over an unversioned WAL.
             }
         }
+        let artifact;
+        for await (const name of this.#tree.iterateNames([])) {
+            if (name !== "format.json") {
+                artifact = name;
+                break;
+            }
+        }
+        if (artifact !== undefined) {
+            throw new StorageCorruptionError("opfs", "format.json", `The OPFS format marker is ${existing === undefined ? "missing" : "torn"}, but the ` +
+                `database directory already contains storage artifacts (${artifact}). ` +
+                `Refusing to guess their layout version.`);
+        }
         const bytes = new TextEncoder().encode(JSON.stringify({ formatVersion: LOG_FORMAT_VERSION }));
         try {
             await this.#tree.writeFile(["format.json"], bytes, { flush: true });
         }
         catch (error) {
-            // A concurrent open won the marker; theirs says the same thing.
             if (!isLockContention(error))
                 throw error;
+            // Another opener owns the marker write. Do not assume it writes this build's version:
+            // wait until its handle closes, then validate the bytes it actually published.
+            for (let attempt = 0; attempt < 40; attempt += 1) {
+                await sleep(5 + Math.random() * 10);
+                const published = await this.#tree.readFile(["format.json"], {
+                    lockedMeansAbsent: true,
+                    maxBytes: 1024,
+                });
+                if (published === undefined)
+                    continue;
+                this.#validateFormatMarker(published);
+                return;
+            }
+            throw new Error("A concurrent opener did not publish a readable OPFS format marker", {
+                cause: error,
+            });
+        }
+    }
+    #validateFormatMarker(bytes) {
+        const text = new TextDecoder().decode(bytes);
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed) ||
+            !Number.isSafeInteger(parsed.formatVersion)) {
+            throw new StorageCorruptionError("opfs", "format.json", "The OPFS format marker is invalid: formatVersion must be a safe integer");
+        }
+        const formatVersion = parsed.formatVersion;
+        if (formatVersion !== LOG_FORMAT_VERSION) {
+            throw new StorageFormatVersionError("opfs", "format.json", formatVersion, LOG_FORMAT_VERSION, formatVersion < LOG_FORMAT_VERSION ? "older" : "newer");
+        }
+        if (Object.keys(parsed).length !== 1 ||
+            !Object.hasOwn(parsed, "formatVersion") ||
+            text !== JSON.stringify({ formatVersion })) {
+            throw new StorageCorruptionError("opfs", "format.json", "The OPFS format marker is not the canonical layout marker");
         }
     }
 }
+for (const method of RPC_METHODS) {
+    if (method in OpfsBlockStore.prototype)
+        continue;
+    Object.defineProperty(OpfsBlockStore.prototype, method, {
+        configurable: true,
+        value(...args) {
+            return this._dispatchGenerated(method, args);
+        },
+    });
+}
 /** Removes every file of a database created by `OpfsBlockStore.open` under this name. */
 export async function deleteOpfsDatabase(options) {
+    const encodedName = encodeSegment(validateStorageDatabaseName(options.name));
     const root = options.root ?? (await navigator.storage.getDirectory());
     try {
         const namespace = await root.getDirectoryHandle("minnowdb");
-        await namespace.removeEntry(encodeSegment(options.name), { recursive: true });
+        await namespace.removeEntry(encodedName, { recursive: true });
     }
     catch (error) {
         if (!isDomError(error, "NotFoundError"))
@@ -943,11 +1034,10 @@ export async function deleteOpfsDatabase(options) {
 }
 const RPC_TIMED_OUT = new Error("The leader did not answer in time");
 async function resolveDatabaseRoot(options) {
-    if (options.name.length === 0)
-        throw new TypeError("Database name cannot be empty");
+    const encodedName = encodeSegment(validateStorageDatabaseName(options.name));
     const root = options.root ?? (await navigator.storage.getDirectory());
     const namespace = await root.getDirectoryHandle("minnowdb", { create: true });
-    return namespace.getDirectoryHandle(encodeSegment(options.name), { create: true });
+    return namespace.getDirectoryHandle(encodedName, { create: true });
 }
 function isLockContention(error) {
     return isDomError(error, "NoModificationAllowedError") || isDomError(error, "InvalidStateError");
@@ -955,4 +1045,3 @@ function isLockContention(error) {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-//# sourceMappingURL=store.js.map