@minnowdb/core 0.10.0 → 0.10.2

package/dist/storage/opfs/coordination-helpers.js

@@ -0,0 +1,54 @@
+import { OpfsBlockStore } from "./store.js";
+function table(name) {
+  return {
+    id: `table-${name}`,
+    name,
+    columns: [{ id: "c1", name: "id", type: "number", nullable: false }],
+    managed: false,
+    revision: 0,
+    createdAt: "2026-08-19T00:00:00.000Z"
+  };
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function waitFor(condition, what, attempts = 800) {
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (await condition())
+      return;
+    await sleep(5);
+  }
+  throw new Error(`Timed out waiting for ${what}`);
+}
+function opener(shim, name, overrides = {}) {
+  return () => OpfsBlockStore.open({ name, root: shim.root, rpcTimeoutMs: 200, ...overrides });
+}
+async function outcome(work) {
+  return work.then(() => "ok", (error) => error instanceof Error ? error.name : String(error));
+}
+async function outcomeMessage(work) {
+  return work.then(() => "ok", (error) => error instanceof Error ? `${error.name}: ${error.message}` : String(error));
+}
+async function delaySyncHandleOpens(shim, matches, delayMs) {
+  const probe = await shim.root.getFileHandle("__delay-probe__", { create: true });
+  const prototype = Object.getPrototypeOf(probe);
+  const original = prototype.createSyncAccessHandle;
+  prototype.createSyncAccessHandle = async function patched() {
+    if (matches(this.name))
+      await sleep(delayMs);
+    return original.call(this);
+  };
+  await shim.root.removeEntry("__delay-probe__");
+  return () => {
+    prototype.createSyncAccessHandle = original;
+  };
+}
+export {
+  delaySyncHandleOpens,
+  opener,
+  outcome,
+  outcomeMessage,
+  sleep,
+  table,
+  waitFor
+};

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

@@ -1,3 +1,3 @@
-export { OpfsBlockStore, deleteOpfsDatabase, type OpfsBlockStoreOptions } from "./store.js";
+export { OpfsBlockStore, deleteOpfsDatabase, opfsDatabaseExists, type OpfsBlockStoreOptions, } from "./store.js";
 export { OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError, } from "../types.js";
 export { OpfsTree, type ReadFileOptions, type WriteFileOptions } from "./files.js";

package/dist/storage/opfs/index.js

@@ -1,4 +1,4 @@
-import { OpfsBlockStore, deleteOpfsDatabase } from "./store.js";
+import { OpfsBlockStore, deleteOpfsDatabase, opfsDatabaseExists } from "./store.js";
 import { OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError } from "../types.js";
 import { OpfsTree } from "./files.js";
 export {
@@ -7,5 +7,6 @@ export {
   OpfsDatabaseInUseError,
   OpfsTree,
   OpfsUncertainOutcomeError,
-  deleteOpfsDatabase
+  deleteOpfsDatabase,
+  opfsDatabaseExists
 };

package/dist/storage/opfs/leader.js

@@ -85,6 +85,36 @@ const LOGGED_BODY_BUILDERS = {
   removeGarbageCollectionJob: ([id]) => ({ op: "removeGarbageCollectionJob", id }),
   removePrunedManifestRecords: ([maxItems]) => ({ op: "removePrunedManifestRecords", maxItems })
 };
+const STATE_SHRINKING_OPS = /* @__PURE__ */ new Set([
+  "rollbackTransactionArtifacts",
+  "abortTransactionIfExpired",
+  "removeLease",
+  "removeLeaseIfExpired",
+  "removeTempRun",
+  "removeTempOwner",
+  "removeTempOwnerIfExpired",
+  "removeCompactionJob",
+  "cancelCompactionJob",
+  "removeGarbageCollectionJob",
+  "removePrunedManifestRecords",
+  "removeAbortedSegment",
+  "abortFtsBaseBuild",
+  "abortUniqueKeyBuild",
+  "cancelSnapshotFrameImport",
+  "closeSnapshotFrameExport",
+  "garbageCollectionStep"
+]);
+function shrinksLoggedState(body) {
+  if (body.op === "updateTransaction")
+    return body.update.status === "aborted";
+  return STATE_SHRINKING_OPS.has(body.op);
+}
+class OpfsLeaderClosedError extends Error {
+  name = "OpfsLeaderClosedError";
+  constructor() {
+    super("This OPFS store connection is closed");
+  }
+}
 class OpfsLeader {
   #tree;
   #strict;
@@ -425,7 +455,7 @@ class OpfsLeader {
   #run(work) {
     const result = this.#chain.then(async () => {
       if (this.#closed)
-        throw new Error("This OPFS store connection is closed");
+        throw new OpfsLeaderClosedError();
       if (this.#poisoned)
         await this.#loadFromDisk();
       return work();
@@ -470,11 +500,13 @@ class OpfsLeader {
     return this.#servedLedger.get(key);
   }
   async completeServed(key, result) {
-    const entry = this.#servedLedger.get(key);
-    if (entry === void 0 || entry.settled)
+    if (!this.#servedLedger.has(key))
       return;
     const bytes = estimateRpcValueBytes(result);
     await this.#run(() => {
+      const entry = this.#servedLedger.get(key);
+      if (entry === void 0 || entry.settled)
+        return;
       if (bytes > this.#servedLedgerResultBytes) {
         this.#appendFrame({ op: "servedResult", key, withheld: true }, false);
         entry.settled = true;
@@ -499,7 +531,13 @@ class OpfsLeader {
   }
   #logged(body) {
     if (this.#wal.byteLength >= MAX_OPFS_WAL_BYTES - 64 * 1024 * 1024) {
-      this.checkpointNow();
+      try {
+        this.checkpointNow();
+      } catch (error) {
+        if (!shrinksLoggedState(body) || this.#wal.byteLength >= MAX_OPFS_WAL_BYTES - 16 * 1024 * 1024) {
+          throw error;
+        }
+      }
     }
     if (this.#strict) {
       try {
@@ -1569,7 +1607,7 @@ class OpfsLeader {
     };
     const bytes = encodeSyncCheckpoint(state);
     if (bytes.byteLength > MAX_OPFS_CHECKPOINT_BYTES) {
-      throw new Error(`OPFS checkpoint exceeds its ${String(MAX_OPFS_CHECKPOINT_BYTES)} byte limit: ` + String(bytes.byteLength));
+      throw new StorageResourceLimitError("checkpoint byte", bytes.byteLength, MAX_OPFS_CHECKPOINT_BYTES);
     }
     const slotIndex = this.#newestSlot === 0 ? 1 : 0;
     const mirrorIndex = slotIndex === 0 ? 1 : 0;
@@ -4802,5 +4840,6 @@ export {
   MAX_OPFS_CHECKPOINT_BYTES,
   MAX_OPFS_WAL_BYTES,
   OpfsLeader,
+  OpfsLeaderClosedError,
   assertBlockReadBatchByteLimit
 };

package/dist/storage/opfs/rpc.js

@@ -1,4 +1,4 @@
-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 { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, ConnectionLostError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError, PostingBuildConflictError, SchemaConflictError, SnapshotImportConflictError, SnapshotManifestMissingError, StorageCorruptionError, StorageUnresponsiveError, 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;
@@ -109,6 +109,7 @@ function parseStoreRpcMessage(value, knownMethods) {
       case "state":
         return exactKeys(record, ["kind", "leaderId", "foreground"]) && boundedRpcString(record.leaderId) && typeof record.foreground === "boolean" ? record : void 0;
       case "leader":
+      case "wait":
       case "released":
         return exactKeys(record, ["kind", "leaderId"]) && boundedRpcString(record.leaderId) ? record : void 0;
       case "ping":
@@ -202,6 +203,7 @@ const errorRegistry = new Map([
   PostingBuildConflictError,
   StorageCorruptionError,
   StorageFormatVersionError,
+  StorageUnresponsiveError,
   OpfsCoordinationError,
   OpfsDatabaseInUseError,
   OpfsUncertainOutcomeError,

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

@@ -27,6 +27,8 @@ export interface OpfsBlockStoreOptions {
     hiddenIdleReleaseMs?: number;
     /** @internal Test seam: how long an ex-leader stays out of elections (default 1500ms). */
     handoverGraceMs?: number;
+    /** @internal Test seam: how long an operation looks for a leader (default 10000ms). */
+    dispatchBudgetMs?: 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
@@ -108,3 +110,13 @@ export declare function deleteOpfsDatabase(options: {
     name: string;
     root?: FileSystemDirectoryHandle;
 }): Promise<void>;
+/**
+ * Whether a database directory of this name exists in the origin's private file system (or
+ * under `root`). Nothing is created: an `auto` descriptor asks this before choosing a store for
+ * a name it has no record of, so a database an explicit `opfs` descriptor created is found
+ * rather than shadowed by an empty one.
+ */
+export declare function opfsDatabaseExists(options: {
+    name: string;
+    root?: FileSystemDirectoryHandle;
+}): Promise<boolean>;

package/dist/storage/opfs/store.js

@@ -2,11 +2,11 @@ import { assertStorageBulkReadItems, assertTempRunPageBatchLimits, OpfsCoordinat
 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 { OpfsLeader, OpfsLeaderClosedError } from "./leader.js";
 import { rehydrateStoreError, estimateRpcValueBytes, fingerprintStoreRequest, MAX_OPFS_RPC_HOLD_MS, MAX_OPFS_RPC_MESSAGE_BYTES, parseStoreRpcMessage, serializeStoreError } from "./rpc.js";
 const RPC_TIMEOUT_MS = 1e3;
 const DISCOVERY_WAIT_MS = 150;
-const DISPATCH_ATTEMPTS = 10;
+const DISPATCH_BUDGET_MS = 1e4;
 const YIELD_COOLDOWN_MS = 3e3;
 const HANDOVER_GRACE_MS = 1500;
 const HIDDEN_IDLE_RELEASE_MS = 15e3;
@@ -185,6 +185,7 @@ class OpfsBlockStore {
   #yieldCooldownMs;
   #hiddenIdleReleaseMs;
   #handoverGraceMs;
+  #dispatchBudgetMs;
   #onDiagnostic;
   #instanceId = crypto.randomUUID();
   #channelName;
@@ -197,6 +198,8 @@ class OpfsBlockStore {
   #closed = false;
   #lastYieldAt = 0;
   #electing;
+  #recovering = false;
+  #waitHeardAt = 0;
   #pending = /* @__PURE__ */ new Map();
   #inFlightMutations = /* @__PURE__ */ new Map();
   #settledMutations = /* @__PURE__ */ new Map();
@@ -230,6 +233,7 @@ class OpfsBlockStore {
     this.#yieldCooldownMs = options.yieldCooldownMs ?? YIELD_COOLDOWN_MS;
     this.#hiddenIdleReleaseMs = options.hiddenIdleReleaseMs ?? HIDDEN_IDLE_RELEASE_MS;
     this.#handoverGraceMs = options.handoverGraceMs ?? HANDOVER_GRACE_MS;
+    this.#dispatchBudgetMs = options.dispatchBudgetMs ?? DISPATCH_BUDGET_MS;
     this.#onDiagnostic = options.onDiagnostic;
     this.#channelName = `minnowdb-store:${options.name}`;
     this.liveQueryChannelName = `minnowdb-live:opfs:${options.name}`;
@@ -311,7 +315,9 @@ class OpfsBlockStore {
     }
     let slotA;
     let slotB;
+    this.#recovering = true;
     try {
+      this.#post({ kind: "wait", leaderId: this.#instanceId });
       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.#cleanupLimitBytes, this.#onDiagnostic, this.#servedLedgerAgeMs, this.#servedLedgerResultBytes);
@@ -322,6 +328,8 @@ class OpfsBlockStore {
       if (isLockContention(error))
         return false;
       throw error;
+    } finally {
+      this.#recovering = false;
     }
     if (this.#closed) {
       const leader = this.#leader;
@@ -409,7 +417,7 @@ class OpfsBlockStore {
       return;
     this.#leader = void 0;
     this.#knownLeader = void 0;
-    const shutdown = leader.shutdown().catch((error) => {
+    const shutdown = this.#shutdownAfterMutations(leader).catch((error) => {
       this.#diagnostic(error, "opfs idle release shutdown");
       leader.crash();
     });
@@ -494,7 +502,7 @@ class OpfsBlockStore {
     this.#leader = void 0;
     this.#knownLeader = void 0;
     this.#lastYieldAt = Date.now();
-    const shutdown = leader.shutdown().catch((error) => {
+    const shutdown = this.#shutdownAfterMutations(leader).catch((error) => {
       this.#diagnostic(error, "opfs yield shutdown");
       leader.crash();
     });
@@ -516,6 +524,14 @@ class OpfsBlockStore {
     }, this.#handoverGraceMs);
   }
   #yielding;
+  #shutdownAfterMutations(leader) {
+    return this.#withMutationTurn(() => leader.shutdown());
+  }
+  async #servedDrained() {
+    const deadline = Date.now() + DECLINE_AFTER_CLOSE_MS;
+    while (this.#served.size > 0 && Date.now() < deadline)
+      await sleep(5);
+  }
   #onMessage(message) {
     if (this.#closed) {
       if (message.kind === "op")
@@ -645,9 +661,16 @@ class OpfsBlockStore {
       case "ping": {
         if (this.#leader !== void 0) {
           this.#post({ kind: "leader", leaderId: this.#instanceId });
+        } else if (this.#recovering || this.#yielding !== void 0) {
+          this.#post({ kind: "wait", leaderId: this.#instanceId });
         }
         return;
       }
+      case "wait": {
+        if (message.leaderId !== this.#instanceId)
+          this.#waitHeardAt = Date.now();
+        return;
+      }
       case "bid": {
         if (message.foreground && message.bidderId !== this.#instanceId) {
           this.#considerBid(message.bidderId);
@@ -1036,7 +1059,7 @@ class OpfsBlockStore {
     let sentRemotely = false;
     let mayHaveRun = false;
     this.#lastActivityAt = sentAt;
-    for (let attempt = 0; attempt < DISPATCH_ATTEMPTS; attempt += 1) {
+    while (Date.now() - Math.max(sentAt, this.#waitHeardAt) < this.#dispatchBudgetMs) {
       this.#assertOpen();
       const leader = this.#leader;
       if (leader !== void 0) {
@@ -1058,7 +1081,16 @@ class OpfsBlockStore {
             if (sentAt < leader.servedCoverageSince)
               throw new OpfsUncertainOutcomeError(method);
           }
-          return await this.#withMutationTurn(() => bound.apply(leader, args));
+          return await this.#withMutationTurn(() => {
+            if (leader.isClosed() || !this.#leads(leader))
+              throw new OpfsLeaderClosedError();
+            return bound.apply(leader, args);
+          });
+        } catch (error) {
+          if (!this.#leads(leader) && (isRead || error instanceof OpfsLeaderClosedError)) {
+            continue;
+          }
+          throw error;
         } finally {
           this.#lastActivityAt = Date.now();
         }
@@ -1187,10 +1219,11 @@ class OpfsBlockStore {
     const leader = this.#leader;
     this.#leader = void 0;
     if (leader !== void 0) {
-      void leader.shutdown().catch((error) => {
+      void this.#shutdownAfterMutations(leader).catch((error) => {
         this.#diagnostic(error, "opfs close shutdown");
         leader.crash();
-      }).then(() => {
+      }).then(() => this.#servedDrained()).then(() => {
+        this.#stopKeepalive();
         this.#post({ kind: "released", leaderId: this.#instanceId });
         this.#closeChannels();
         this.#releaseWhenHandlesClose();
@@ -1198,13 +1231,15 @@ class OpfsBlockStore {
       return;
     }
     if (this.#yielding !== void 0) {
-      void this.#yielding.then(() => {
+      void this.#yielding.then(() => this.#servedDrained()).then(() => {
+        this.#stopKeepalive();
         this.#post({ kind: "released", leaderId: this.#instanceId });
         this.#closeChannels();
         this.#releaseWhenHandlesClose();
       });
       return;
     }
+    this.#stopKeepalive();
     this.#closeChannels();
     this.#releaseWhenHandlesClose();
   }
@@ -1212,10 +1247,8 @@ class OpfsBlockStore {
     if (this.#reacquireTimer !== void 0)
       clearTimeout(this.#reacquireTimer);
     this.#reacquireTimer = void 0;
-    this.#stopKeepalive();
     this.#clearDeferredBid();
     this.#clearHiddenIdleTimer();
-    this.#served.clear();
   }
   #releaseWhenHandlesClose() {
     const release = this.#releaseConnectionLock;
@@ -1275,6 +1308,8 @@ class OpfsBlockStore {
   _crashForTests() {
     this.#closed = true;
     this.#clearCoordinationTimers();
+    this.#stopKeepalive();
+    this.#served.clear();
     for (const pending of this.#pending.values())
       clearTimeout(pending.timer);
     this.#pending.clear();
@@ -1423,6 +1458,17 @@ async function resolveDatabaseRoot(options) {
   const namespace = await root.getDirectoryHandle("minnowdb", { create: true });
   return namespace.getDirectoryHandle(encodedName, { create: true });
 }
+async function opfsDatabaseExists(options) {
+  const encodedName = encodeSegment(validateStorageDatabaseName(options.name));
+  try {
+    const root = options.root ?? await navigator.storage.getDirectory();
+    const namespace = await root.getDirectoryHandle("minnowdb");
+    await namespace.getDirectoryHandle(encodedName);
+    return true;
+  } catch {
+    return false;
+  }
+}
 function isLockContention(error) {
   return isDomError(error, "NoModificationAllowedError") || isDomError(error, "InvalidStateError");
 }
@@ -1431,5 +1477,6 @@ function sleep(ms) {
 }
 export {
   OpfsBlockStore,
-  deleteOpfsDatabase
+  deleteOpfsDatabase,
+  opfsDatabaseExists
 };

package/dist/storage/toolkit/wal.js

@@ -79,6 +79,8 @@ function* iterateWalFrames(handle) {
   while (offset + FRAME_HEADER_BYTES <= size) {
     readFully(handle, header, offset, "reading a WAL frame header for recovery");
     if (headerView.getUint32(0, true) !== FRAME_MAGIC) {
+      if (isZeroFilled(handle, offset, size))
+        break;
       throw new Error(`WAL frame marker mismatch at offset ${String(offset)}`);
     }
     const length = headerView.getUint32(4, true);
@@ -92,12 +94,26 @@ function* iterateWalFrames(handle) {
     const payloadBytes = new Uint8Array(length);
     readFully(handle, payloadBytes, offset + FRAME_HEADER_BYTES, "reading a WAL frame payload for recovery");
     if (crc32(payloadBytes) !== checksum) {
+      if (payloadBytes.every((byte) => byte === 0) && isZeroFilled(handle, end, size))
+        break;
       throw new Error(`WAL frame checksum mismatch at offset ${String(offset)}`);
     }
     yield { payload: decodeRecordJson(payloadBytes), frameEnd: end };
     offset = end;
   }
 }
+function isZeroFilled(handle, offset, size) {
+  const chunk = new Uint8Array(Math.min(64 * 1024, Math.max(0, size - offset)));
+  for (let at = offset; at < size; at += chunk.byteLength) {
+    const length = Math.min(chunk.byteLength, size - at);
+    const window = length === chunk.byteLength ? chunk : chunk.subarray(0, length);
+    readFully(handle, window, at, "reading a WAL tail for recovery");
+    for (let index = 0; index < length; index += 1)
+      if (window[index] !== 0)
+        return false;
+  }
+  return true;
+}
 export {
   MAX_WAL_FRAME_BYTES,
   WalWriter,

package/dist/storage/toolkit/wire.js

@@ -58,15 +58,15 @@ function decodeEnvelope(magic, bytes) {
   }
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   const version = view.getUint32(8, true);
-  if (version !== LOG_FORMAT_VERSION) {
-    throw new StorageFormatVersionError("opfs", `envelope/${magic}`, version, LOG_FORMAT_VERSION, version < LOG_FORMAT_VERSION ? "older" : "newer");
-  }
   const payloadLength = view.getUint32(12, true);
   if (bytes.byteLength !== ENVELOPE_HEADER_BYTES + payloadLength)
     return void 0;
   const payload = bytes.subarray(ENVELOPE_HEADER_BYTES, ENVELOPE_HEADER_BYTES + payloadLength);
   if (crc32(payload) !== view.getUint32(16, true))
     return void 0;
+  if (version !== LOG_FORMAT_VERSION) {
+    throw new StorageFormatVersionError("opfs", `envelope/${magic}`, version, LOG_FORMAT_VERSION, version < LOG_FORMAT_VERSION ? "older" : "newer");
+  }
   return payload;
 }
 const CHUNK_MAGIC = "MNWCHNK1";

package/dist/storage/types.d.ts

@@ -254,8 +254,16 @@ export interface SecondaryIndexRecord {
     unique?: true;
     /** The membership set has been seeded and must be enforced, independent of postings state. */
     uniqueEnforced?: true;
-    /** Prefix-free composite encoding used by every v1 secondary index. */
-    termEncoding: "tuple-v1";
+    /**
+     * Prefix-free composite term encoding.
+     *
+     * `tuple-v1` encodes non-null components only: a row with a NULL in any indexed column has no
+     * posting at all, so a prefix lookup through the index cannot see it. `tuple-v2` keeps every
+     * non-null component byte-identical and adds a one-character marker for a NULL component, so a
+     * row with a NULL trailing component is named under its non-null prefix. Both stay readable;
+     * only `tuple-v2` may serve a prefix lookup whose unconstrained trailing columns are nullable.
+     */
+    termEncoding: "tuple-v1" | "tuple-v2";
     storage: "postings-v1";
     storageColumnId: string;
     locator: "row-id" | "key-hash-v1";
@@ -502,11 +510,11 @@ export declare const MAX_PINNED_RETIRED_BYTES: number;
 export declare const MAX_RETIRED_HISTORY_BYTES: number;
 /** A durable resource family reached its fixed corruption/growth safety ceiling. */
 export declare class StorageResourceLimitError extends Error {
-    readonly resource: "lease" | "temp owner" | "temp run" | "temp page" | "temporary run total" | "temporary page total" | "temp owner byte" | "temporary byte" | "compaction job" | "garbage collection job" | "unique-key build" | "full-text build" | "secondary-index build" | "accelerator build byte" | "accelerator build entry" | "transaction" | "staged artifact byte" | "staged block" | "staged segment" | "catalog record" | "catalog byte" | "manifest record" | "manifest byte" | "segment record" | "segment byte" | "terminal transaction" | "terminal compaction job" | "completed garbage collection job" | "pinned manifest version lag" | "pinned retired block" | "pinned retired byte" | "snapshot accelerator byte" | "snapshot accelerator entry" | "retired history byte";
+    readonly resource: "lease" | "temp owner" | "temp run" | "temp page" | "temporary run total" | "temporary page total" | "temp owner byte" | "temporary byte" | "compaction job" | "garbage collection job" | "unique-key build" | "full-text build" | "secondary-index build" | "accelerator build byte" | "accelerator build entry" | "transaction" | "staged artifact byte" | "staged block" | "staged segment" | "catalog record" | "catalog byte" | "manifest record" | "manifest byte" | "segment record" | "segment byte" | "terminal transaction" | "terminal compaction job" | "completed garbage collection job" | "pinned manifest version lag" | "pinned retired block" | "pinned retired byte" | "snapshot accelerator byte" | "snapshot accelerator entry" | "retired history byte" | "checkpoint byte";
     readonly count: number;
     readonly limit: number;
     readonly name = "StorageResourceLimitError";
-    constructor(resource: "lease" | "temp owner" | "temp run" | "temp page" | "temporary run total" | "temporary page total" | "temp owner byte" | "temporary byte" | "compaction job" | "garbage collection job" | "unique-key build" | "full-text build" | "secondary-index build" | "accelerator build byte" | "accelerator build entry" | "transaction" | "staged artifact byte" | "staged block" | "staged segment" | "catalog record" | "catalog byte" | "manifest record" | "manifest byte" | "segment record" | "segment byte" | "terminal transaction" | "terminal compaction job" | "completed garbage collection job" | "pinned manifest version lag" | "pinned retired block" | "pinned retired byte" | "snapshot accelerator byte" | "snapshot accelerator entry" | "retired history byte", count: number, limit: number);
+    constructor(resource: "lease" | "temp owner" | "temp run" | "temp page" | "temporary run total" | "temporary page total" | "temp owner byte" | "temporary byte" | "compaction job" | "garbage collection job" | "unique-key build" | "full-text build" | "secondary-index build" | "accelerator build byte" | "accelerator build entry" | "transaction" | "staged artifact byte" | "staged block" | "staged segment" | "catalog record" | "catalog byte" | "manifest record" | "manifest byte" | "segment record" | "segment byte" | "terminal transaction" | "terminal compaction job" | "completed garbage collection job" | "pinned manifest version lag" | "pinned retired block" | "pinned retired byte" | "snapshot accelerator byte" | "snapshot accelerator entry" | "retired history byte" | "checkpoint byte", count: number, limit: number);
 }
 export interface LeaseRecord {
     id: string;
@@ -1361,6 +1369,29 @@ export declare class UnknownOutcomeError extends Error {
 export declare class ConnectionLostError extends Error {
     readonly name: string;
 }
+/**
+ * The store stopped answering: the whole connection went the adapter's unresponsive deadline
+ * without a single storage event while it had work outstanding. The remedy is to reload the
+ * page, not to retry — the connection cannot recover, and a fresh one in the same page may be
+ * wedged by the same cause.
+ *
+ * The known cause is a worker terminated with a write in flight. WebKit keeps the dead worker's
+ * IndexedDB connection, and its unfinished transaction, registered until the owning document
+ * goes away, and while it is registered every connection to that database blocks — including
+ * connections opened afterwards in other tabs. A store cannot unwedge the browser, so it bounds
+ * the wait and says so instead of hanging.
+ *
+ * It extends `UnknownOutcomeError` because a write that stalled may still be committed by the
+ * browser once the wedge clears, and carries a `ConnectionLostError` cause so `classifyError`
+ * reports the connection as unusable.
+ */
+export declare class StorageUnresponsiveError extends UnknownOutcomeError {
+    readonly backend: string;
+    readonly databaseName: string;
+    readonly waitedMs: number;
+    readonly name = "StorageUnresponsiveError";
+    constructor(backend: string, databaseName: string, waitedMs: number);
+}
 /**
  * A remote OPFS leader may have committed a mutation whose acknowledgement was lost.
  * Reconcile stable identities or revisions before retrying the named operation.

package/dist/storage/types.js

@@ -226,7 +226,7 @@ function secondaryIndexWriteContractChanged(previous, next) {
     if (rightEntry?.[0] !== id)
       return true;
     const right = rightEntry[1];
-    return left.name !== right.name || left.columnId !== right.columnId || left.columnIds.length !== right.columnIds.length || left.columnIds.some((columnId, index) => columnId !== right.columnIds[index]) || left.directions.length !== right.directions.length || left.directions.some((direction, index) => direction !== right.directions[index]) || left.unique !== right.unique || left.uniqueEnforced !== right.uniqueEnforced || left.storageColumnId !== right.storageColumnId || left.locator !== right.locator;
+    return left.name !== right.name || left.columnId !== right.columnId || left.columnIds.length !== right.columnIds.length || left.columnIds.some((columnId, index) => columnId !== right.columnIds[index]) || left.directions.length !== right.directions.length || left.directions.some((direction, index) => direction !== right.directions[index]) || left.termEncoding !== right.termEncoding || left.unique !== right.unique || left.uniqueEnforced !== right.uniqueEnforced || left.storageColumnId !== right.storageColumnId || left.locator !== right.locator;
   });
 }
 function validateTableForeignKey(childTable, key, parentTable) {
@@ -461,7 +461,7 @@ function validateSecondaryIndexes(record) {
     }
     const directions = index.directions;
     const termEncoding = index.termEncoding;
-    if (directions.length !== indexedColumnIds.length || directions.some((direction) => direction !== "asc" && direction !== "desc") || termEncoding !== "tuple-v1") {
+    if (directions.length !== indexedColumnIds.length || directions.some((direction) => direction !== "asc" && direction !== "desc") || termEncoding !== "tuple-v1" && termEncoding !== "tuple-v2") {
       throw new TypeError(`Secondary index ${index.name} has invalid key metadata`);
     }
     if (index.uniqueEnforced === true && index.unique !== true) {
@@ -993,6 +993,18 @@ class UnknownOutcomeError extends Error {
 class ConnectionLostError extends Error {
   name = "ConnectionLostError";
 }
+class StorageUnresponsiveError extends UnknownOutcomeError {
+  backend;
+  databaseName;
+  waitedMs;
+  name = "StorageUnresponsiveError";
+  constructor(backend, databaseName, waitedMs) {
+    super(`The ${backend} database ${databaseName} answered nothing for ${String(waitedMs)}ms and is treated as unresponsive; reload the page to open it again`, { cause: new ConnectionLostError(`The ${backend} connection stopped answering`) });
+    this.backend = backend;
+    this.databaseName = databaseName;
+    this.waitedMs = waitedMs;
+  }
+}
 class OpfsUncertainOutcomeError extends UnknownOutcomeError {
   method;
   name = "OpfsUncertainOutcomeError";
@@ -2428,7 +2440,7 @@ function normalizeMergeCompactionRewritePlan(value) {
   for (let index = 1; index < sourceSegments.length; index += 1) {
     const previous = sourceSegments[index - 1];
     const current = sourceSegments[index];
-    if (previous !== void 0 && current !== void 0 && compareMergeSourceSegments(previous, current) >= 0) {
+    if (previous !== void 0 && current !== void 0 && compareMergeSourceSegments(previous, current) > 0) {
       throw new TypeError("Merge source segments must use canonical logical order");
     }
   }
@@ -2739,7 +2751,7 @@ function normalizeRowIdSpans(value, totalRows, rowIdStart, rowIdEndExclusive, la
   return spans;
 }
 function compareMergeSourceSegments(left, right) {
-  return left.logicalOrder - right.logicalOrder || left.committedVersion - right.committedVersion || left.segmentId.localeCompare(right.segmentId);
+  return left.logicalOrder - right.logicalOrder || left.committedVersion - right.committedVersion;
 }
 function normalizeCompactionOutputCursor(value, plan) {
   if (plan.kind === "copy-v1") {
@@ -3065,6 +3077,7 @@ export {
   StorageCorruptionError,
   StorageFormatVersionError,
   StorageResourceLimitError,
+  StorageUnresponsiveError,
   TableInUseError,
   TableRecordConflictError,
   TempOwnerConflictError,

package/dist/testing/block-store-conformance.js

@@ -1,4 +1,4 @@
-import { CompactionJobConflictError, LeaseConflictError, LeaseOwnerConflictError, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_STORAGE_BULK_READ_ITEMS, PostingBuildConflictError, SnapshotManifestMissingError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, secondaryUniqueKeyNamespace, WriteConflictError } from "../storage/types.js";
+import { CompactionJobConflictError, GarbageCollectionJobConflictError, LeaseConflictError, LeaseOwnerConflictError, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_STORAGE_BULK_READ_ITEMS, PostingBuildConflictError, SnapshotManifestMissingError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, secondaryUniqueKeyNamespace, WriteConflictError } from "../storage/types.js";
 async function runBlockStoreConformance(target) {
   for (const conformanceCase of blockStoreConformanceCases()) {
     try {
@@ -768,6 +768,36 @@ function blockStoreConformanceCases() {
           limit: 1
         });
         checkEqual(retiredBeforeCollection.records.map((record) => record.blockId), [first.blockId], "retired provenance must remain independently pageable before collection");
+        const discovering = await store.createGarbageCollectionJob({
+          id: "gc-discovering",
+          candidateManifestVersions: [],
+          candidateSegmentIds: [],
+          candidateBlockIds: [],
+          leaseCutoff: LATER,
+          createdAt: LATER,
+          discovery: {
+            phase: "manifests",
+            currentManifestVersion: null,
+            retainAboveVersion: 0,
+            retainAfter: 0,
+            maxPlanningItems: 16,
+            manifestCursor: null,
+            segmentCursor: null,
+            transactionCursor: null,
+            compactionCursor: null,
+            visitedRecords: 0,
+            resumePhase: null,
+            postManifestPhase: null,
+            artifactCursor: null
+          }
+        });
+        const discovered = await store.updateGarbageCollectionPlanning({
+          jobId: discovering.id,
+          expectedRevision: discovering.revision,
+          discovery: { ...discovering.discovery ?? {}, phase: "complete" },
+          updatedAt: LATER
+        });
+        check(discovered.state === "completed", "a discovery that found nothing must complete its job");
         const job = await store.createGarbageCollectionJob({
           id: "gc-1",
           candidateManifestVersions: [first.version],
@@ -778,6 +808,15 @@ function blockStoreConformanceCases() {
         });
         await checkThrows(() => store.removeGarbageCollectionJob(job.id), Error, "removing a non-completed garbage-collection job");
         check((await store.getGarbageCollectionJob(job.id))?.state === "planned", "a refused garbage-collection job removal mutated the record");
+        await checkThrows(() => store.createGarbageCollectionJob({
+          id: "gc-2",
+          candidateManifestVersions: [first.version],
+          candidateSegmentIds: [],
+          candidateBlockIds: [first.blockId],
+          leaseCutoff: LATER,
+          createdAt: LATER
+        }), GarbageCollectionJobConflictError, "a second active garbage-collection job");
+        check(await store.getGarbageCollectionJob("gc-2") === void 0, "a refused second garbage-collection job left a record behind");
         const step = await store.runGarbageCollectionStep({
           jobId: job.id,
           expectedRevision: job.revision,