@minnowdb/core 0.10.1 → 0.10.2

package/dist/storage/indexeddb.js

@@ -1,4 +1,4 @@
-import { CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, CompactionBacklogError, createManifest, createGarbageCollectionJobRecord, storeNames, advanceGarbageCollectionJobRecord as advanceGarbageCollectionJobRecordUnchecked, BlockReadBatchTooLargeError, activePostingStorageColumnIds, assertTempRunPageBatchLimits, assertStorageBulkReadItems, assertTransactionArtifactBatchLimits, boundedMaintenanceBatchItems, canonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, collectFtsPostings, ftsPostingQueryMatches, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_FTS_CANDIDATE_ROW_IDS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_CHUNK_BYTES, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_ORDERED_READ_BYTES, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_BLOCK_READ_BATCH_BYTES, MAX_STORAGE_ID_CHARACTERS, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TRANSACTIONS, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_RETIRED_HISTORY_BYTES, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_GARBAGE_COLLECTION_JOBS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_ACTIVE_FTS_BASE_BUILDS, MAX_ACTIVE_SECONDARY_INDEX_BUILDS, MAX_ACCELERATOR_BUILD_STAGED_BYTES_TOTAL, MAX_ACCELERATOR_BUILD_STAGED_ENTRIES_TOTAL, MAX_POSTING_BUILD_TTL_MS, MAX_SNAPSHOT_SESSION_TTL_MS, MAX_SNAPSHOT_FRAME_BATCH_BYTES, MAX_SNAPSHOT_FRAME_BATCH_ITEMS, MAX_SNAPSHOT_METADATA_BATCH_BYTES, MAX_SNAPSHOT_METADATA_FRAME_BYTES, SNAPSHOT_FRAME_KINDS, MAX_LEVEL_ZERO_SEGMENTS, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, StorageCorruptionError, StorageFormatVersionError, IndexedDbSchemaUpgradeBlockedError, StorageResourceLimitError, SnapshotManifestMissingError, SnapshotImportConflictError, PostingBuildConflictError, validateTableForeignKey, TableInUseError, TableRecordConflictError, TempOwnerConflictError, MAX_TEMP_OWNER_TTL_MS, MAX_ACTIVE_TEMP_OWNERS, MAX_TEMP_RUNS_PER_OWNER, MAX_TEMP_PAGES_PER_OWNER, MAX_TEMP_RUNS_TOTAL, MAX_TEMP_PAGES_TOTAL, MAX_TEMP_BYTES_PER_OWNER, MAX_TEMP_BYTES_TOTAL, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, SchemaConflictError, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord as updateCompactionJobRecordUnchecked, updateGarbageCollectionPlanningRecord, updateTransactionRecord as updateTransactionRecordUnchecked, validateColumnDefault, validateCatalogName, validateCanonicalManifestChangedTableIds, validateEnumValues, validateFtsCandidateLimit, validateFtsOrderedReadLimits, validateFtsReadVersion, validateFtsPostingQueries, validateStorageId, validateStorageDatabaseName, validateTableColumns, validateSecondaryIndexes, validateTableRecordBounds, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, WriteConflictError } from "./types.js";
+import { CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, CompactionBacklogError, createManifest, createGarbageCollectionJobRecord, storeNames, advanceGarbageCollectionJobRecord as advanceGarbageCollectionJobRecordUnchecked, BlockReadBatchTooLargeError, activePostingStorageColumnIds, assertTempRunPageBatchLimits, assertStorageBulkReadItems, assertTransactionArtifactBatchLimits, boundedMaintenanceBatchItems, canonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, collectFtsPostings, ftsPostingQueryMatches, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_FTS_CANDIDATE_ROW_IDS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_CHUNK_BYTES, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_ORDERED_READ_BYTES, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_BLOCK_READ_BATCH_BYTES, MAX_STORAGE_ID_CHARACTERS, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TRANSACTIONS, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_RETIRED_HISTORY_BYTES, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_GARBAGE_COLLECTION_JOBS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_ACTIVE_FTS_BASE_BUILDS, MAX_ACTIVE_SECONDARY_INDEX_BUILDS, MAX_ACCELERATOR_BUILD_STAGED_BYTES_TOTAL, MAX_ACCELERATOR_BUILD_STAGED_ENTRIES_TOTAL, MAX_POSTING_BUILD_TTL_MS, MAX_SNAPSHOT_SESSION_TTL_MS, MAX_SNAPSHOT_FRAME_BATCH_BYTES, MAX_SNAPSHOT_FRAME_BATCH_ITEMS, MAX_SNAPSHOT_METADATA_BATCH_BYTES, MAX_SNAPSHOT_METADATA_FRAME_BYTES, SNAPSHOT_FRAME_KINDS, MAX_LEVEL_ZERO_SEGMENTS, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, StorageCorruptionError, StorageFormatVersionError, StorageUnresponsiveError, IndexedDbSchemaUpgradeBlockedError, StorageResourceLimitError, SnapshotManifestMissingError, SnapshotImportConflictError, PostingBuildConflictError, validateTableForeignKey, TableInUseError, TableRecordConflictError, TempOwnerConflictError, MAX_TEMP_OWNER_TTL_MS, MAX_ACTIVE_TEMP_OWNERS, MAX_TEMP_RUNS_PER_OWNER, MAX_TEMP_PAGES_PER_OWNER, MAX_TEMP_RUNS_TOTAL, MAX_TEMP_PAGES_TOTAL, MAX_TEMP_BYTES_PER_OWNER, MAX_TEMP_BYTES_TOTAL, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, SchemaConflictError, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord as updateCompactionJobRecordUnchecked, updateGarbageCollectionPlanningRecord, updateTransactionRecord as updateTransactionRecordUnchecked, validateColumnDefault, validateCatalogName, validateCanonicalManifestChangedTableIds, validateEnumValues, validateFtsCandidateLimit, validateFtsOrderedReadLimits, validateFtsReadVersion, validateFtsPostingQueries, validateStorageId, validateStorageDatabaseName, validateTableColumns, validateSecondaryIndexes, validateTableRecordBounds, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, WriteConflictError } from "./types.js";
 import { crc32, verifyStoredBlock } from "../block-format/index.js";
 import { dateIsoString } from "../date-value.js";
 import { decodeSnapshotMetadataItems, encodeSnapshotMetadataPage, extendSnapshotFrameStreamChecksum, prepareSnapshotFrameStreamHeader, snapshotFrameEnvelopeParts, snapshotFrameStreamHeaderIdentity } from "./snapshot-stream.js";
@@ -129,11 +129,18 @@ class IndexedDbBlockStore {
   #snapshotPeakRetainedItems = 0;
   #snapshotPeakRetainedBytes = 0;
   #closed = false;
-  constructor(db, durability, uniqueKeyCacheBytes) {
+  #unresponsive;
+  #stallGuard;
+  constructor(db, durability, uniqueKeyCacheBytes, unresponsiveAfterMs) {
     this.#db = db;
     this.liveQueryChannelName = `minnowdb-live:indexeddb:${db.name}`;
     this.#durability = durability;
     this.#uniqueKeyCacheBytes = uniqueKeyCacheBytes;
+    this.#stallGuard = new ConnectionStallGuard(db.name, unresponsiveAfterMs, (error) => {
+      this.#unresponsive = error;
+      this.close();
+    });
+    stallGuards.set(db, this.#stallGuard);
     db.addEventListener("versionchange", () => {
       this.close();
     });
@@ -144,6 +151,10 @@ class IndexedDbBlockStore {
     if (!Number.isSafeInteger(uniqueKeyCacheBytes) || uniqueKeyCacheBytes < 0) {
       throw new RangeError("Unique-key cache bytes must be a non-negative whole number");
     }
+    const unresponsiveAfterMs = options.unresponsiveAfterMs ?? INDEXEDDB_UNRESPONSIVE_AFTER_MS;
+    if (!Number.isSafeInteger(unresponsiveAfterMs) || unresponsiveAfterMs <= 0) {
+      throw new RangeError("The unresponsive deadline must be a positive whole number of ms");
+    }
     const factory = options.indexedDB ?? getGlobalIndexedDb();
     if (factory === void 0)
       throw new Error("IndexedDB is unavailable");
@@ -177,7 +188,7 @@ class IndexedDbBlockStore {
       db = await openDatabaseRequest(request, (event) => {
         abandoned = true;
         return new IndexedDbSchemaUpgradeBlockedError(options.name, event.oldVersion, event.newVersion ?? SCHEMA_VERSION);
-      });
+      }, options.name, unresponsiveAfterMs);
     } catch (error) {
       if (upgradeError !== void 0)
         throw upgradeError;
@@ -187,7 +198,7 @@ class IndexedDbBlockStore {
       }
       throw error;
     }
-    const store = new IndexedDbBlockStore(db, options.durability ?? "strict", uniqueKeyCacheBytes);
+    const store = new IndexedDbBlockStore(db, options.durability ?? "strict", uniqueKeyCacheBytes, unresponsiveAfterMs);
     try {
       await validateCurrentIndexedDbSchema(db);
       await store.#validateCatalogResourceLedger();
@@ -1164,8 +1175,8 @@ class IndexedDbBlockStore {
       this.#journalCache = void 0;
       if (this.#uniqueKeyCache?.tableId === input.tableId || this.#uniqueKeyCache?.tableId.startsWith(`${input.tableId}\0secondary-index\0`) === true) {
         this.#uniqueKeyCache = void 0;
-      } else if (this.#uniqueKeyCache !== void 0) {
-        this.#uniqueKeyCache.version = manifest.version;
+      } else {
+        this.#carryUniqueKeyCache(input.expectedManifestVersion, manifest.version);
       }
       return manifest;
     } catch (error) {
@@ -1302,8 +1313,7 @@ class IndexedDbBlockStore {
       await transactionDone(transaction);
       this.#manifestCache = void 0;
       this.#journalCache = void 0;
-      if (this.#uniqueKeyCache !== void 0)
-        this.#uniqueKeyCache.version = manifest.version;
+      this.#carryUniqueKeyCache(input.expectedManifestVersion, manifest.version);
       return manifest;
     } catch (error) {
       abortIfActive(transaction);
@@ -2124,6 +2134,16 @@ class IndexedDbBlockStore {
       throw await refusalBehindAbort(transaction, error);
     }
   }
+  #carryUniqueKeyCache(basedOn, version) {
+    const cache = this.#uniqueKeyCache;
+    if (cache === void 0 || cache.version === version)
+      return;
+    if (basedOn !== null && basedOn !== void 0 && cache.version === basedOn) {
+      cache.version = version;
+    } else {
+      this.#uniqueKeyCache = void 0;
+    }
+  }
   async getExistingUniqueKeys(tableId, keyTokens) {
     validateId(tableId, "Table ID");
     assertStorageBulkReadItems(keyTokens, "Unique-key read");
@@ -3470,13 +3490,11 @@ class IndexedDbBlockStore {
           } : void 0;
         } else if (this.#uniqueKeyCache?.tableId === uniqueKeyChanges.tableId) {
           this.#uniqueKeyCache = void 0;
-        } else if (this.#uniqueKeyCache !== void 0) {
-          this.#uniqueKeyCache.version = manifest.version;
+        } else {
+          this.#carryUniqueKeyCache(input.expectedManifestVersion, manifest.version);
         }
-      } else if (uniqueKeyChanges !== void 0 && this.#uniqueKeyCache?.tableId === uniqueKeyChanges.tableId) {
-        this.#uniqueKeyCache.version = manifest.version;
-      } else if (this.#uniqueKeyCache !== void 0) {
-        this.#uniqueKeyCache.version = manifest.version;
+      } else {
+        this.#carryUniqueKeyCache(input.expectedManifestVersion, manifest.version);
       }
       this.#manifestCache = void 0;
       this.#journalCache = void 0;
@@ -3910,13 +3928,13 @@ class IndexedDbBlockStore {
       const quota = await readMaintenanceQuota(gcStore);
       let activeGarbageCollectionJobs;
       if (record.state !== "completed") {
-        activeGarbageCollectionJobs = checkedQuotaIncrement(quota.activeGarbageCollectionJobs, "Active garbage collection job count");
-        assertMaintenanceLimit("garbage collection job", activeGarbageCollectionJobs, MAX_ACTIVE_GARBAGE_COLLECTION_JOBS);
         const markerValue = await requestResult(gcStore.get(ACTIVE_GARBAGE_COLLECTION_KEY));
         if (markerValue !== void 0) {
           const marker = asActiveGarbageCollectionMarker(markerValue);
-          throw new Error(`Garbage collection job ${marker.jobId} is already active`);
+          throw new GarbageCollectionJobConflictError(marker.jobId, record.revision, null);
         }
+        activeGarbageCollectionJobs = checkedQuotaIncrement(quota.activeGarbageCollectionJobs, "Active garbage collection job count");
+        assertMaintenanceLimit("garbage collection job", activeGarbageCollectionJobs, MAX_ACTIVE_GARBAGE_COLLECTION_JOBS);
       }
       await assertGarbageCollectionCandidateProvenanceInTransaction(transaction, record);
       if (record.state !== "completed") {
@@ -3959,6 +3977,9 @@ class IndexedDbBlockStore {
         candidateTransactionIds: input.candidateTransactionIds ?? []
       });
       gcStore.put(garbageCollectionJobEnvelope(updated), key);
+      if (updated.state === "completed" && current.state !== "completed") {
+        await releaseGarbageCollectionAdmission(gcStore);
+      }
       await transactionDone(transaction);
       return structuredClone(updated);
     } catch (error) {
@@ -4183,17 +4204,8 @@ class IndexedDbBlockStore {
         updatedAt: input.updatedAt
       });
       gcStore.put(garbageCollectionJobEnvelope(updated), key);
-      if (updated.state === "completed") {
-        const quota = await readMaintenanceQuota(gcStore);
-        const completedGarbageCollectionJobs = checkedQuotaIncrement(quota.completedGarbageCollectionJobs, "Completed garbage collection job count");
-        assertMaintenanceLimit("completed garbage collection job", completedGarbageCollectionJobs, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS);
-        gcStore.put({
-          ...quota,
-          activeGarbageCollectionJobs: checkedQuotaDecrement(quota.activeGarbageCollectionJobs, "active garbage collection job count"),
-          completedGarbageCollectionJobs
-        }, MAINTENANCE_QUOTA_KEY);
-        await requestResult(gcStore.delete(ACTIVE_GARBAGE_COLLECTION_KEY));
-      }
+      if (updated.state === "completed")
+        await releaseGarbageCollectionAdmission(gcStore);
       await transactionDone(transaction);
       return {
         job: structuredClone(updated),
@@ -6055,6 +6067,7 @@ class IndexedDbBlockStore {
     this.#uniqueKeyCache = void 0;
     this.#manifestCache = void 0;
     this.#journalCache = void 0;
+    this.#stallGuard.dispose();
     this.#db.close();
   }
   _residentStateForTests() {
@@ -6333,6 +6346,8 @@ class IndexedDbBlockStore {
     }
   }
   #transaction(stores, mode, options = {}) {
+    if (this.#unresponsive !== void 0)
+      throw this.#unresponsive;
     if (this.#closed)
       throw new Error("This IndexedDB store connection is closed");
     const requested = typeof stores === "string" ? [stores] : stores;
@@ -6454,49 +6469,156 @@ async function readIndexedDbVersion(factory, name) {
     return null;
   }
 }
-function openDatabaseRequest(request, blockedError) {
+const INDEXEDDB_UNRESPONSIVE_AFTER_MS = 3e4;
+class ConnectionStallGuard {
+  #databaseName;
+  #afterMs;
+  #onTrip;
+  #waiting = /* @__PURE__ */ new Set();
+  #timer;
+  #tripped;
+  #disposed = false;
+  constructor(databaseName, afterMs, onTrip) {
+    this.#databaseName = databaseName;
+    this.#afterMs = afterMs;
+    this.#onTrip = onTrip;
+  }
+  wait(reject) {
+    if (this.#tripped !== void 0) {
+      const tripped = this.#tripped;
+      queueMicrotask(() => reject(tripped));
+      return () => void 0;
+    }
+    if (this.#disposed)
+      return () => void 0;
+    this.#waiting.add(reject);
+    this.#arm();
+    let released = false;
+    return () => {
+      if (released)
+        return;
+      released = true;
+      this.#waiting.delete(reject);
+      this.#progress();
+    };
+  }
+  dispose() {
+    this.#disposed = true;
+    this.#waiting.clear();
+    this.#disarm();
+  }
+  #arm() {
+    if (this.#timer !== void 0 || this.#waiting.size === 0)
+      return;
+    this.#timer = setTimeout(() => {
+      this.#timer = void 0;
+      this.#trip();
+    }, this.#afterMs);
+    this.#timer.unref?.();
+  }
+  #disarm() {
+    if (this.#timer === void 0)
+      return;
+    clearTimeout(this.#timer);
+    this.#timer = void 0;
+  }
+  #progress() {
+    if (this.#tripped !== void 0)
+      return;
+    this.#disarm();
+    this.#arm();
+  }
+  #trip() {
+    if (this.#tripped !== void 0)
+      return;
+    const error = new StorageUnresponsiveError("indexeddb", this.#databaseName, this.#afterMs);
+    this.#tripped = error;
+    const waiting = [...this.#waiting];
+    this.#waiting.clear();
+    this.#onTrip(error);
+    for (const reject of waiting)
+      reject(error);
+  }
+}
+const stallGuards = /* @__PURE__ */ new WeakMap();
+function stallGuardFor(db) {
+  return db === null || db === void 0 ? void 0 : stallGuards.get(db);
+}
+function openDatabaseRequest(request, blockedError, databaseName, unresponsiveAfterMs) {
   return new Promise((resolve, reject) => {
     let settled = false;
+    const timer = setTimeout(() => {
+      if (settled)
+        return;
+      settled = true;
+      reject(new StorageUnresponsiveError("indexeddb", databaseName, unresponsiveAfterMs));
+    }, unresponsiveAfterMs);
+    timer.unref?.();
+    const settle = () => {
+      if (settled)
+        return false;
+      settled = true;
+      clearTimeout(timer);
+      return true;
+    };
     request.addEventListener("success", () => {
-      if (settled) {
+      if (!settle()) {
         request.result.close();
         return;
       }
-      settled = true;
       resolve(request.result);
     }, { once: true });
     request.addEventListener("error", () => {
-      if (settled)
+      if (!settle())
         return;
-      settled = true;
       reject(request.error ?? new Error("IndexedDB open failed"));
     }, { once: true });
     request.addEventListener("blocked", (event) => {
-      if (settled)
+      if (!settle())
         return;
-      settled = true;
       reject(blockedError(event));
     }, { once: true });
   });
 }
 function requestResult(request) {
+  const guard = stallGuardFor(request.transaction?.db);
   return new Promise((resolve, reject) => {
-    request.addEventListener("success", () => resolve(request.result), { once: true });
-    request.addEventListener("error", () => reject(request.error ?? new Error("IndexedDB request failed")), {
+    const release = guard?.wait(reject);
+    request.addEventListener("success", () => {
+      release?.();
+      resolve(request.result);
+    }, { once: true });
+    request.addEventListener("error", () => {
+      release?.();
+      reject(request.error ?? new Error("IndexedDB request failed"));
+    }, {
       once: true
     });
   });
 }
 function readCursorPage(store, limit, decode, acceptKey, seekKey) {
+  const guard = stallGuardFor(store.transaction.db);
   return new Promise((resolve, reject) => {
     const records = [];
     const request = store.openCursor();
     let seekPending = seekKey !== void 0;
-    request.onerror = () => reject(request.error ?? new Error("IndexedDB cursor failed"));
+    let release = guard?.wait(reject);
+    const settle = (value) => {
+      release?.();
+      release = void 0;
+      resolve(value);
+    };
+    request.onerror = () => {
+      release?.();
+      release = void 0;
+      reject(request.error ?? new Error("IndexedDB cursor failed"));
+    };
     request.onsuccess = () => {
+      release?.();
+      release = guard?.wait(reject);
       const cursor = request.result;
       if (cursor === null || records.length === limit) {
-        resolve(records);
+        settle(records);
         return;
       }
       try {
@@ -6510,10 +6632,12 @@ function readCursorPage(store, limit, decode, acceptKey, seekKey) {
         if (acceptKey(cursor.key))
           records.push(decode(cursor.value, cursor.key));
         if (records.length === limit)
-          resolve(records);
+          settle(records);
         else
           cursor.continue();
       } catch (error) {
+        release?.();
+        release = void 0;
         reject(error instanceof Error ? error : new Error(String(error)));
       }
     };
@@ -6973,9 +7097,17 @@ function transactionDone(transaction) {
   const existing = transactionCompletions.get(transaction);
   if (existing !== void 0)
     return existing;
+  const guard = stallGuardFor(transaction.db);
   const done = new Promise((resolve, reject) => {
-    transaction.addEventListener("complete", () => resolve(), { once: true });
-    transaction.addEventListener("abort", () => reject(transaction.error ?? new Error("Transaction aborted")), {
+    const release = guard?.wait(reject);
+    transaction.addEventListener("complete", () => {
+      release?.();
+      resolve();
+    }, { once: true });
+    transaction.addEventListener("abort", () => {
+      release?.();
+      reject(transaction.error ?? new Error("Transaction aborted"));
+    }, {
       once: true
     });
   });
@@ -9737,6 +9869,17 @@ async function assertActiveCompactionMarker(store, record) {
     throw corruption(`gc/${activeCompactionKey(record.tableId)}`, `marker names job ${marker.jobId} instead of ${record.id}`);
   }
 }
+async function releaseGarbageCollectionAdmission(gcStore) {
+  const quota = await readMaintenanceQuota(gcStore);
+  const completedGarbageCollectionJobs = checkedQuotaIncrement(quota.completedGarbageCollectionJobs, "Completed garbage collection job count");
+  assertMaintenanceLimit("completed garbage collection job", completedGarbageCollectionJobs, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS);
+  gcStore.put({
+    ...quota,
+    activeGarbageCollectionJobs: checkedQuotaDecrement(quota.activeGarbageCollectionJobs, "active garbage collection job count"),
+    completedGarbageCollectionJobs
+  }, MAINTENANCE_QUOTA_KEY);
+  await requestResult(gcStore.delete(ACTIVE_GARBAGE_COLLECTION_KEY));
+}
 async function assertActiveGarbageCollectionMarker(store, record) {
   const marker = asActiveGarbageCollectionMarker(await requestResult(store.get(ACTIVE_GARBAGE_COLLECTION_KEY)));
   if (marker.jobId !== record.id) {
@@ -12897,5 +13040,6 @@ function utf8Bytes(value) {
   return storageTextEncoder.encode(value).byteLength;
 }
 export {
+  INDEXEDDB_UNRESPONSIVE_AFTER_MS,
   IndexedDbBlockStore
 };

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;
@@ -203,6 +203,7 @@ const errorRegistry = new Map([
   PostingBuildConflictError,
   StorageCorruptionError,
   StorageFormatVersionError,
+  StorageUnresponsiveError,
   OpfsCoordinationError,
   OpfsDatabaseInUseError,
   OpfsUncertainOutcomeError,

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";
@@ -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,

package/dist/testing/index.d.ts

@@ -96,4 +96,5 @@ export declare class FaultInjectingBlockStore implements BlockStore {
 export { blockStoreConformanceCases, runBlockStoreConformance, type BlockStoreConformanceCase, type BlockStoreConformanceTarget, } from "./block-store-conformance.js";
 export { MemoryOpfs, type TransferLimit, type WriteFault } from "./opfs-shim.js";
 export { DeterministicScheduler, generateSimulationPlan, parseSimulationPlan, runSimulation, scheduledBlockStore, type CollectionPassSummary, type SimulationDelete, type SimulationMutation, type SimulationOptions, type SimulationPlan, type SimulationPut, type SimulationResult, type SimulationStep, type SimulationTraceEvent, } from "./simulator.js";
+export { InteractionFailure, createDatabaseDriver, evaluate as evaluatePlanPredicate, generateInteractionPlan, parseInteractionPlan, renderLiteral as renderPlanLiteral, renderPredicate as renderPlanPredicate, runInteractionPlan, type Assignment, type ColumnType, type CompareOperator, type DatabaseDriverOptions, type DriverStoreSource, type FaultPointName, type Interaction, type InteractionPlan, type InteractionPlanOptions, type InteractionRunOptions, type InteractionRunResult, type KeyedMutation, type PlanColumn, type PlanRow, type PlanTable, type PlanValue, type Predicate, type SimulatedConnection, type SimulatedExecuteResult, type SimulatedFaults, type SimulatedQueryResult, type SimulationDriver, type TransactionStatement, } from "./interaction-simulator.js";
 export { SqlLogicFailure, SqlLogicParseError, md5Hex, parseSqlLogicTest, parseSqlLogicTestLines, renderSqlLogicValue, runSqlLogicTest, type SqlLogicCondition, type SqlLogicDatabase, type SqlLogicExpectedHash, type SqlLogicExpectedValues, type SqlLogicHalt, type SqlLogicHashThreshold, type SqlLogicLocation, type SqlLogicQuery, type SqlLogicRecord, type SqlLogicRunStatistics, type SqlLogicRunOptions, type SqlLogicSortMode, type SqlLogicStatement, type SqlLogicType, } from "./sqllogictest.js";

package/dist/testing/index.js

@@ -290,22 +290,31 @@ class FaultInjectingBlockStore {
 import { blockStoreConformanceCases, runBlockStoreConformance } from "./block-store-conformance.js";
 import { MemoryOpfs } from "./opfs-shim.js";
 import { DeterministicScheduler, generateSimulationPlan, parseSimulationPlan, runSimulation, scheduledBlockStore } from "./simulator.js";
+import { InteractionFailure, createDatabaseDriver, evaluate, generateInteractionPlan, parseInteractionPlan, renderLiteral, renderPredicate, runInteractionPlan } from "./interaction-simulator.js";
 import { SqlLogicFailure, SqlLogicParseError, md5Hex, parseSqlLogicTest, parseSqlLogicTestLines, renderSqlLogicValue, runSqlLogicTest } from "./sqllogictest.js";
 export {
   DeterministicScheduler,
   FaultInjectingBlockStore,
+  InteractionFailure,
   MemoryOpfs,
   SqlLogicFailure,
   SqlLogicParseError,
   blockStoreConformanceCases,
+  createDatabaseDriver,
+  evaluate as evaluatePlanPredicate,
   faultPoints,
+  generateInteractionPlan,
   generateSimulationPlan,
   md5Hex,
+  parseInteractionPlan,
   parseSimulationPlan,
   parseSqlLogicTest,
   parseSqlLogicTestLines,
+  renderLiteral as renderPlanLiteral,
+  renderPredicate as renderPlanPredicate,
   renderSqlLogicValue,
   runBlockStoreConformance,
+  runInteractionPlan,
   runSimulation,
   runSqlLogicTest,
   scheduledBlockStore