@minnowdb/core 0.9.0 → 0.10.0

package/dist/storage/opfs/leader.js

@@ -3,6 +3,7 @@ import { dateIsoString } from "../../date-value.js";
 import { decodeSnapshotMetadataItems, encodeSnapshotMetadataPage, extendSnapshotFrameStreamChecksum, prepareSnapshotFrameStreamHeader, snapshotFrameEnvelopeParts, snapshotFrameStreamHeaderIdentity } from "../snapshot-stream.js";
 import { RecordCore, validateBeginTransactionInput, validateBlockWriteBytes, validateFtsBaseInput, validateFtsPostingChunks, validateId, validateTempRunPage, validateTempRunPageIdentity } from "../toolkit/record-core.js";
 import { encodeSegment, decodeSegment } from "./files.js";
+import { estimateRpcValueBytes } from "./rpc.js";
 import { SnapshotFrameLedger, snapshotLedgerPath } from "./snapshot-ledger.js";
 import { decodePostingChunk, decodeSyncCheckpoint, encodePostingChunk, encodeSyncCheckpoint } from "../toolkit/wire.js";
 import { WalWriter, iterateWalFrames } from "../toolkit/wal.js";
@@ -20,6 +21,10 @@ const FTS_CHUNK_CACHE_SIZE = 64;
 const MAX_RELOCATION_PAYLOADS = 256;
 const SNAPSHOT_POSTING_TERMS_PER_CHUNK = 128;
 const TEMP_FILE_CLEANUP_DEBT_FLOOR_BYTES = 64 * 1024;
+const MAX_SERVED_LEDGER_ENTRIES = 65536;
+const MAX_SERVED_LEDGER_AGE_MS = 10 * 60 * 1e3;
+const MAX_SERVED_LEDGER_RESULT_BYTES = 64 * 1024;
+const MAX_SERVED_LEDGER_BYTES = 8 * 1024 * 1024;
 const CORE_READ_METHODS = [
   "getTempOwner",
   "getTable",
@@ -136,7 +141,20 @@ class OpfsLeader {
   #lastCleanupError;
   #cleanupRetryScheduled = false;
   #cleanupDebtBytes = 0;
-  constructor(tree, strict, walHandle, slots, checkpointEntries, cleanupLimitBytes) {
+  #onDiagnostic;
+  servingRequest;
+  #servedLedger = /* @__PURE__ */ new Map();
+  #servedResultBytes = /* @__PURE__ */ new Map();
+  #servedLedgerBytes = 0;
+  #servedLedgerResultBytes;
+  #servedCoverageSince = 0;
+  #servedLedgerAgeMs;
+  onBeforeCheckpoint;
+  #lastCheckpointMs = 0;
+  constructor(tree, strict, walHandle, slots, checkpointEntries, cleanupLimitBytes, onDiagnostic, servedLedgerAgeMs, servedLedgerResultBytes) {
+    this.#onDiagnostic = onDiagnostic;
+    this.#servedLedgerAgeMs = servedLedgerAgeMs ?? MAX_SERVED_LEDGER_AGE_MS;
+    this.#servedLedgerResultBytes = servedLedgerResultBytes ?? MAX_SERVED_LEDGER_RESULT_BYTES;
     this.#checkpointEntries = checkpointEntries ?? CHECKPOINT_ENTRIES;
     this.#cleanupLimitBytes = cleanupLimitBytes ?? MAX_OPFS_CLEANUP_DEBT_BYTES;
     if (!Number.isSafeInteger(this.#cleanupLimitBytes) || this.#cleanupLimitBytes < 1) {
@@ -153,8 +171,8 @@ class OpfsLeader {
       blockChecksum: (id) => this.#blockIndex.get(id)?.checksum ?? (this.#permissivePhysical ? 0 : void 0)
     });
   }
-  static async recover(tree, strict, handles, checkpointEntries, cleanupLimitBytes) {
-    const leader = new OpfsLeader(tree, strict, handles.wal, [handles.slotA, handles.slotB], checkpointEntries, cleanupLimitBytes);
+  static async recover(tree, strict, handles, checkpointEntries, cleanupLimitBytes, onDiagnostic, servedLedgerAgeMs, servedLedgerResultBytes) {
+    const leader = new OpfsLeader(tree, strict, handles.wal, [handles.slotA, handles.slotB], checkpointEntries, cleanupLimitBytes, onDiagnostic, servedLedgerAgeMs, servedLedgerResultBytes);
     try {
       await leader.#loadFromDisk();
     } catch (error) {
@@ -270,6 +288,16 @@ class OpfsLeader {
       this.#applyTempPageUpdates(checkpoint.tempPages);
       this.#seq = checkpoint.lastSeq;
       this.#checkpointGeneration = checkpoint.generation;
+      this.#servedLedger.clear();
+      this.#servedResultBytes.clear();
+      this.#servedLedgerBytes = 0;
+      this.#servedCoverageSince = checkpoint.servedCoverageSince;
+      for (const outcome of checkpoint.servedRequests) {
+        this.#servedLedger.set(outcome.key, { ...outcome });
+        if (outcome.settled && outcome.withheld !== true) {
+          this.#retainServedResult(outcome.key, estimateRpcValueBytes(outcome.result));
+        }
+      }
     }
     const newest = this.#slots[this.#newestSlot];
     this.#lastCheckpointBytes = newest === void 0 ? 0 : newest.getSize();
@@ -328,6 +356,21 @@ class OpfsLeader {
       }
       applied += 1;
       this.#applyReplayed(entry);
+      if (entry.request !== void 0) {
+        this.#recordServed({ ...entry.request, seq: entry.seq, settled: false });
+      }
+      if (entry.op === "servedResult") {
+        const served = this.#servedLedger.get(entry.key);
+        if (served !== void 0) {
+          served.settled = true;
+          if (entry.withheld === true)
+            served.withheld = true;
+          else {
+            served.result = entry.result;
+            this.#retainServedResult(entry.key, estimateRpcValueBytes(entry.result));
+          }
+        }
+      }
       for (const placement of placementsOf(entry)) {
         this.#pool.restorePlacement(placement);
       }
@@ -395,6 +438,65 @@ class OpfsLeader {
       return;
     await this.#run(() => void 0);
   }
+  #recordServed(outcome) {
+    this.#forgetServedResult(outcome.key);
+    this.#servedLedger.delete(outcome.key);
+    this.#servedLedger.set(outcome.key, outcome);
+    this.#trimServedLedger(outcome.sentAt - this.#servedLedgerAgeMs);
+  }
+  #trimServedLedger(horizon) {
+    for (const [key, entry] of this.#servedLedger) {
+      if (this.#servedLedger.size <= MAX_SERVED_LEDGER_ENTRIES && this.#servedLedgerBytes <= MAX_SERVED_LEDGER_BYTES && entry.sentAt >= horizon) {
+        break;
+      }
+      this.#forgetServedResult(key);
+      this.#servedLedger.delete(key);
+      this.#servedCoverageSince = Math.max(this.#servedCoverageSince, entry.sentAt + 1);
+    }
+  }
+  #retainServedResult(key, bytes) {
+    this.#forgetServedResult(key);
+    this.#servedResultBytes.set(key, bytes);
+    this.#servedLedgerBytes += bytes;
+  }
+  #forgetServedResult(key) {
+    const bytes = this.#servedResultBytes.get(key);
+    if (bytes === void 0)
+      return;
+    this.#servedResultBytes.delete(key);
+    this.#servedLedgerBytes -= bytes;
+  }
+  servedOutcome(key) {
+    return this.#servedLedger.get(key);
+  }
+  async completeServed(key, result) {
+    const entry = this.#servedLedger.get(key);
+    if (entry === void 0 || entry.settled)
+      return;
+    const bytes = estimateRpcValueBytes(result);
+    await this.#run(() => {
+      if (bytes > this.#servedLedgerResultBytes) {
+        this.#appendFrame({ op: "servedResult", key, withheld: true }, false);
+        entry.settled = true;
+        entry.withheld = true;
+        return;
+      }
+      this.#appendFrame({ op: "servedResult", key, result }, false);
+      entry.result = result;
+      entry.settled = true;
+      this.#retainServedResult(key, bytes);
+      this.#trimServedLedger(Number.NEGATIVE_INFINITY);
+    });
+  }
+  get servedCoverageSince() {
+    return this.#servedCoverageSince;
+  }
+  #diagnostic(error, context) {
+    try {
+      this.#onDiagnostic?.(error, context);
+    } catch {
+    }
+  }
   #logged(body) {
     if (this.#wal.byteLength >= MAX_OPFS_WAL_BYTES - 64 * 1024 * 1024) {
       this.checkpointNow();
@@ -414,16 +516,21 @@ class OpfsLeader {
     this.#appendFrame(body);
     return result;
   }
-  #appendFrame(body) {
+  #appendFrame(body, flush = this.#strict) {
+    const request = this.servingRequest;
+    this.servingRequest = void 0;
+    let nextSeq;
     try {
-      const nextSeq = safeSuccessor(this.#seq, "OPFS WAL sequence");
-      this.#wal.append({ seq: nextSeq, ...body }, this.#strict);
+      nextSeq = safeSuccessor(this.#seq, "OPFS WAL sequence");
+      this.#wal.append({ seq: nextSeq, ...body, ...request === void 0 ? {} : { request } }, flush);
       this.#seq = nextSeq;
       this.#entriesSinceCheckpoint = safeSuccessor(this.#entriesSinceCheckpoint, "OPFS checkpoint entry count");
     } catch (error) {
       this.#poisoned = true;
       throw error;
     }
+    if (request !== void 0)
+      this.#recordServed({ ...request, seq: nextSeq, settled: false });
     if (this.#checkpointDue() && this.#entriesSinceCheckpoint >= this.#checkpointRetryAtEntries && !this.#checkpointScheduled) {
       this.#checkpointScheduled = true;
       void this.#run(() => {
@@ -431,7 +538,9 @@ class OpfsLeader {
         if (this.#checkpointDue()) {
           this.checkpointNow();
         }
-      }).catch(() => void 0);
+      }).catch((error) => {
+        this.#diagnostic(error, "opfs checkpoint");
+      });
     }
   }
   #checkpointDue() {
@@ -937,6 +1046,8 @@ class OpfsLeader {
         this.#snapshotFrameImport = void 0;
         return void 0;
       }
+      case "servedResult":
+        return void 0;
       case "cancelSnapshotFrameImport": {
         const session = this.#snapshotFrameImport;
         if (session?.identity !== body.input.identity) {
@@ -1085,8 +1196,9 @@ class OpfsLeader {
   #applyReplayed(entry) {
     this.#permissivePhysical = true;
     try {
-      const { seq: _seq, ...body } = entry;
+      const { seq: _seq, request: _request, ...body } = entry;
       void _seq;
+      void _request;
       this.#applyBody(body);
       this.#clearCompletedSnapshotImportIfAdvanced();
     } finally {
@@ -1416,7 +1528,10 @@ class OpfsLeader {
   }
   checkpointNow() {
     try {
+      this.onBeforeCheckpoint?.(this.#lastCheckpointMs);
+      const started = Date.now();
       this.#checkpointNowUnchecked();
+      this.#lastCheckpointMs = Date.now() - started;
       this.#checkpointFailures = 0;
       this.#lastCheckpointError = void 0;
       this.#checkpointRetryAtEntries = 0;
@@ -1448,7 +1563,9 @@ class OpfsLeader {
       ...this.#completedSnapshotFrameImport === void 0 ? {} : {
         completedSnapshotFrameImport: structuredClone(this.#completedSnapshotFrameImport)
       },
-      extents: this.#pool.meta()
+      extents: this.#pool.meta(),
+      servedRequests: [...this.#servedLedger.values()],
+      servedCoverageSince: this.#servedCoverageSince
     };
     const bytes = encodeSyncCheckpoint(state);
     if (bytes.byteLength > MAX_OPFS_CHECKPOINT_BYTES) {
@@ -1532,6 +1649,7 @@ class OpfsLeader {
     } catch (error) {
       this.#cleanupFailures += 1;
       this.#lastCleanupError = error;
+      this.#diagnostic(error, "opfs cleanup");
       await this.#refreshCleanupDebtAfterFailure();
     }
     if (this.#cleanupRetryScheduled || this.#closed)
@@ -1547,9 +1665,12 @@ class OpfsLeader {
       } catch (error) {
         this.#cleanupFailures += 1;
         this.#lastCleanupError = error;
+        this.#diagnostic(error, "opfs cleanup retry");
         await this.#refreshCleanupDebtAfterFailure();
       }
-    }).catch(() => void 0);
+    }).catch((error) => {
+      this.#diagnostic(error, "opfs cleanup retry");
+    });
   }
   async #refreshCleanupDebtAfterFailure() {
     try {
@@ -3228,11 +3349,15 @@ class OpfsLeader {
       }
     };
   }
+  isClosed() {
+    return this.#closed;
+  }
   async shutdown() {
     await this.#run(() => {
       this.checkpointNow();
       this.#closed = true;
-    }).catch(() => {
+    }).catch((error) => {
+      this.#diagnostic(error, "opfs shutdown checkpoint");
       this.#closed = true;
     });
     this.#walHandle.close();
@@ -3347,7 +3472,8 @@ const WAL_BODY_KEYS = {
   renewSnapshotFrameImport: ["input"],
   appendSnapshotImportFrames: ["input", "state", "blockPlacements", "replay"],
   finishSnapshotFrameImport: ["input"],
-  cancelSnapshotFrameImport: ["input"]
+  cancelSnapshotFrameImport: ["input"],
+  servedResult: ["key", "result", "withheld"]
 };
 function validateWalEntry(value) {
   if (!isRecord(value))
@@ -3543,6 +3669,14 @@ function validateWalEntry(value) {
       requireTimestamp(entry.input.expiresAtCutoff, "finishSnapshotFrameImport cutoff");
       requireRecord(entry.input.footer, "finishSnapshotFrameImport footer");
       break;
+    case "servedResult":
+      if (typeof entry.key !== "string" || entry.key.length === 0 || entry.key.length > 4096) {
+        throw new Error("servedResult key is invalid");
+      }
+      if (Object.hasOwn(entry, "withheld") && (entry.withheld !== true || Object.hasOwn(entry, "result"))) {
+        throw new Error("servedResult withholding is invalid");
+      }
+      break;
     case "cancelSnapshotFrameImport":
       requireRecord(entry.input, "cancelSnapshotFrameImport input");
       assertExactRecordKeys(entry.input, ["identity", "ownerId"], "cancelSnapshotFrameImport input");
@@ -3570,11 +3704,46 @@ function validateIdPlacements(value, label) {
   }
 }
 function assertWalKeys(value, bodyKeys) {
-  const allowed = /* @__PURE__ */ new Set(["seq", "op", ...bodyKeys]);
+  const allowed = /* @__PURE__ */ new Set(["seq", "op", ...bodyKeys, "request"]);
   for (const key of Object.keys(value)) {
     if (!allowed.has(key))
       throw new Error(`Unexpected ${String(value.op)} WAL field: ${key}`);
   }
+  if (value.request !== void 0)
+    validateServedRequest(value.request);
+}
+function validateServedRequest(value) {
+  if (!isRecord(value))
+    throw new Error("OPFS WAL served request is not an object");
+  assertExactRecordKeys(value, ["key", "method", "signature", "requestBytes", "sentAt"], "OPFS WAL served request");
+  if (typeof value.key !== "string" || value.key.length === 0 || value.key.length > 4096) {
+    throw new Error("OPFS WAL served request has an invalid key");
+  }
+  if (typeof value.method !== "string" || value.method.length === 0) {
+    throw new Error("OPFS WAL served request has an invalid method");
+  }
+  if (typeof value.signature !== "string" || value.signature.length === 0) {
+    throw new Error("OPFS WAL served request has an invalid signature");
+  }
+  if (!isNonNegativeSafeInteger(value.requestBytes) || !isNonNegativeSafeInteger(value.sentAt)) {
+    throw new Error("OPFS WAL served request has invalid numbers");
+  }
+}
+function validateServedOutcome(value) {
+  if (!isRecord(value))
+    throw new Error("OPFS served outcome is not an object");
+  const { seq, settled, withheld, result: _result, ...request } = value;
+  void _result;
+  validateServedRequest(request);
+  if (!Number.isSafeInteger(seq) || seq < 1) {
+    throw new Error("OPFS served outcome has an invalid sequence");
+  }
+  if (typeof settled !== "boolean" || !settled && Object.hasOwn(value, "result")) {
+    throw new Error("OPFS served outcome has an invalid settlement");
+  }
+  if (withheld !== void 0 && (withheld !== true || !settled || Object.hasOwn(value, "result"))) {
+    throw new Error("OPFS served outcome has an invalid withholding");
+  }
 }
 function assertExactRecordKeys(value, keys, label) {
   const expected = new Set(keys);
@@ -3757,6 +3926,20 @@ function validateCheckpointState(value) {
   if (!Array.isArray(value.tempPages)) {
     throw new Error("Invalid OPFS checkpoint temp-page ledger");
   }
+  if (!Array.isArray(value.servedRequests)) {
+    throw new Error("Invalid OPFS checkpoint served-request ledger");
+  }
+  if (!isNonNegativeSafeInteger(value.servedCoverageSince)) {
+    throw new Error("Invalid OPFS checkpoint served-request coverage");
+  }
+  const seenServed = /* @__PURE__ */ new Set();
+  for (const entry of value.servedRequests) {
+    validateServedOutcome(entry);
+    if (seenServed.has(entry.key)) {
+      throw new Error(`Duplicate OPFS checkpoint served request: ${entry.key}`);
+    }
+    seenServed.add(entry.key);
+  }
   assertExactRecordKeys(value, [
     "formatVersion",
     "generation",
@@ -3769,7 +3952,9 @@ function validateCheckpointState(value) {
     ...value.snapshotFrameExport === void 0 ? [] : ["snapshotFrameExport"],
     ...value.snapshotFrameImport === void 0 ? [] : ["snapshotFrameImport"],
     ...value.completedSnapshotFrameImport === void 0 ? [] : ["completedSnapshotFrameImport"],
-    "extents"
+    "extents",
+    "servedRequests",
+    "servedCoverageSince"
   ], "OPFS checkpoint");
   assertValidExtentMeta(value.extents);
   const blockIds = /* @__PURE__ */ new Set();
@@ -4542,6 +4727,8 @@ function parseTempPageFilePath(path) {
 }
 function placementsOf(entry) {
   switch (entry.op) {
+    case "servedResult":
+      return [];
     case "stageTransactionArtifacts":
     case "writeTransaction":
       return entry.blocks.map(({ placement }) => placement);

package/dist/storage/opfs/rpc.js

@@ -1,6 +1,9 @@
-import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError, PostingBuildConflictError, SnapshotImportConflictError, SnapshotManifestMissingError, StorageCorruptionError, StorageFormatVersionError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, SchemaConflictError } from "../types.js";
+import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, ConnectionLostError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError, PostingBuildConflictError, SchemaConflictError, SnapshotImportConflictError, SnapshotManifestMissingError, StorageCorruptionError, StorageFormatVersionError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueIndexCoverageError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UnknownOutcomeError, WriteConflictError } from "../types.js";
 import { dateIsoString } from "../../date-value.js";
+import { MAX_SERIALIZED_CAUSE_DEPTH, rehydrateError, serializeError } from "../../worker-protocol/index.js";
+const MAX_OPFS_RPC_STACK_CHARACTERS = 64 * 1024;
 const MAX_OPFS_RPC_MESSAGE_BYTES = 66 * 1024 * 1024;
+const MAX_OPFS_RPC_HOLD_MS = 6e4;
 const MAX_OPFS_RPC_IDENTIFIER_CHARACTERS = 1024;
 const MAX_OPFS_RPC_DEPTH = 64;
 const MAX_OPFS_RPC_NODES = 11e5;
@@ -66,12 +69,13 @@ function estimateRpcValueBytes(value) {
   }
   return bytes;
 }
-function validSerializedError(value) {
+function validSerializedError(value, depth = 0) {
   if (typeof value !== "object" || value === null || Array.isArray(value))
     return false;
   const record = value;
-  const allowed = record.props === void 0 ? record.domException === void 0 ? ["name", "message"] : ["name", "message", "domException"] : record.domException === void 0 ? ["name", "message", "props"] : ["name", "message", "domException", "props"];
-  return exactKeys(record, allowed) && boundedRpcString(record.name) && typeof record.message === "string" && record.message.length <= MAX_OPFS_RPC_IDENTIFIER_CHARACTERS * 4 && (record.domException === void 0 || record.domException === true) && (record.props === void 0 || typeof record.props === "object" && record.props !== null && !Array.isArray(record.props));
+  const optional = ["stack", "domException", "props", "cause"];
+  const allowed = ["name", "message", ...optional.filter((key) => record[key] !== void 0)];
+  return exactKeys(record, allowed) && boundedRpcString(record.name) && typeof record.message === "string" && record.message.length <= MAX_OPFS_RPC_IDENTIFIER_CHARACTERS * 4 && (record.stack === void 0 || typeof record.stack === "string" && record.stack.length <= MAX_OPFS_RPC_STACK_CHARACTERS) && (record.domException === void 0 || record.domException === true) && (record.props === void 0 || typeof record.props === "object" && record.props !== null && !Array.isArray(record.props)) && (record.cause === void 0 || depth < MAX_SERIALIZED_CAUSE_DEPTH && validSerializedError(record.cause, depth + 1));
 }
 function parseStoreRpcMessage(value, knownMethods) {
   try {
@@ -81,7 +85,7 @@ function parseStoreRpcMessage(value, knownMethods) {
     estimateRpcValueBytes(record);
     switch (record.kind) {
       case "op":
-        if (!exactKeys(record, ["kind", "requestId", "from", "method", "args"]) || !boundedRpcString(record.requestId) || !boundedRpcString(record.from) || !boundedRpcString(record.method) || !knownMethods.has(record.method) || !Array.isArray(record.args) || estimateRpcValueBytes(record.args) > MAX_OPFS_RPC_MESSAGE_BYTES)
+        if (!exactKeys(record, ["kind", "requestId", "from", "method", "args", "sentAt"]) || !boundedRpcString(record.requestId) || !boundedRpcString(record.from) || !boundedRpcString(record.method) || !knownMethods.has(record.method) || !Array.isArray(record.args) || !Number.isSafeInteger(record.sentAt) || record.sentAt < 0 || estimateRpcValueBytes(record.args) > MAX_OPFS_RPC_MESSAGE_BYTES)
           return void 0;
         return record;
       case "result":
@@ -96,6 +100,14 @@ function parseStoreRpcMessage(value, knownMethods) {
         return record;
       case "busy":
         return exactKeys(record, ["kind", "requestId"]) && boundedRpcString(record.requestId) ? record : void 0;
+      case "hold":
+        return exactKeys(record, ["kind", "requestId", "ms"]) && boundedRpcString(record.requestId) && typeof record.ms === "number" && Number.isSafeInteger(record.ms) && record.ms >= 0 && record.ms <= MAX_OPFS_RPC_HOLD_MS ? record : void 0;
+      case "uncertain":
+        return exactKeys(record, ["kind", "requestId"]) && boundedRpcString(record.requestId) ? record : void 0;
+      case "declined":
+        return exactKeys(record, ["kind", "requestId", "reason"]) && boundedRpcString(record.requestId) && record.reason === "not-leader" ? record : void 0;
+      case "state":
+        return exactKeys(record, ["kind", "leaderId", "foreground"]) && boundedRpcString(record.leaderId) && typeof record.foreground === "boolean" ? record : void 0;
       case "leader":
       case "released":
         return exactKeys(record, ["kind", "leaderId"]) && boundedRpcString(record.leaderId) ? record : void 0;
@@ -192,50 +204,18 @@ const errorRegistry = new Map([
   StorageFormatVersionError,
   OpfsCoordinationError,
   OpfsDatabaseInUseError,
-  OpfsUncertainOutcomeError
+  OpfsUncertainOutcomeError,
+  UnknownOutcomeError,
+  ConnectionLostError
 ].map((constructor) => [constructor.name, constructor]));
 function serializeStoreError(error) {
-  if (error instanceof DOMException) {
-    return { name: error.name, message: error.message, domException: true };
-  }
-  if (!(error instanceof Error))
-    return { name: "Error", message: String(error) };
-  const props = {};
-  for (const key of Object.keys(error)) {
-    const value = error[key];
-    try {
-      structuredClone(value);
-      props[key] = value;
-    } catch {
-    }
-  }
-  return {
-    name: error.name,
-    message: error.message,
-    ...Object.keys(props).length === 0 ? {} : { props }
-  };
+  return serializeError(error);
 }
 function rehydrateStoreError(serialized) {
-  if (serialized.domException === true) {
-    return new DOMException(serialized.message, serialized.name);
-  }
-  const constructor = errorRegistry.get(serialized.name);
-  const error = constructor === void 0 ? new Error(serialized.message) : Object.create(constructor.prototype);
-  Object.defineProperty(error, "message", {
-    value: serialized.message,
-    writable: true,
-    configurable: true
-  });
-  Object.defineProperty(error, "name", {
-    value: serialized.name,
-    writable: true,
-    configurable: true
-  });
-  if (serialized.props !== void 0)
-    Object.assign(error, serialized.props);
-  return error;
+  return rehydrateError(serialized, errorRegistry);
 }
 export {
+  MAX_OPFS_RPC_HOLD_MS,
   MAX_OPFS_RPC_IDENTIFIER_CHARACTERS,
   MAX_OPFS_RPC_MESSAGE_BYTES,
   estimateRpcValueBytes,

package/dist/storage/opfs/store.d.ts

@@ -15,8 +15,24 @@ export interface OpfsBlockStoreOptions {
     checkpointEntries?: number;
     /** @internal Test seam: cleanup-debt backpressure limit (default 64 MiB). */
     cleanupLimitBytes?: number;
+    /** @internal Test seam: how long served requests stay answerable (default 10 minutes). */
+    servedLedgerAgeMs?: number;
+    /** @internal Test seam: the largest served result the ledger retains (default 64 KiB). */
+    servedLedgerResultBytes?: number;
     /** @internal Test seam: how long a follower waits for the leader (default 1000ms). */
     rpcTimeoutMs?: number;
+    /** @internal Test seam: minimum spacing between foreground yields (default 3000ms). */
+    yieldCooldownMs?: number;
+    /** @internal Test seam: idle time before a hidden leader releases (default 15000ms). */
+    hiddenIdleReleaseMs?: number;
+    /** @internal Test seam: how long an ex-leader stays out of elections (default 1500ms). */
+    handoverGraceMs?: number;
+    /**
+     * Hears failures no operation reports: a background checkpoint or cleanup that failed, an
+     * election or handover that threw, a served request that could not be answered. The worker
+     * host wires it to the client's `onWorkerError`; a direct caller may log it.
+     */
+    onDiagnostic?: (error: unknown, context: string) => void;
 }
 /**
  * The OPFS block store: one leader per database holds every file handle and does all storage
@@ -50,6 +66,8 @@ export declare class OpfsBlockStore {
     readonly liveQueryChannelName: string;
     private constructor();
     static open(options: OpfsBlockStoreOptions): Promise<OpfsBlockStore>;
+    /** @internal Simulates a leader from a release without keepalives. */
+    _suppressKeepaliveForTests(): void;
     /** Marks this connection as the one the user is looking at — a leadership preference. */
     setForeground(foreground: boolean): void;
     putTempRunPage(page: TempRunPage): Promise<void>;
@@ -69,6 +87,8 @@ export declare class OpfsBlockStore {
     _dropNextRpcResultForTests(): void;
     /** Test-only: holds newly admitted served mutations until the returned release is called. */
     _holdServedMutationsForTests(): () => void;
+    /** Test-only: the request id of the oldest pending request, for hand-posted answers. */
+    _oldestPendingRequestIdForTests(): string | undefined;
     /** Test-only: retransmits the oldest request with its stable deduplication identity. */
     _resendOldestPendingForTests(): void;
     /** Test-only counters that pin the connection's bounded RPC state and close-time cleanup. */