@tanstack/db-sqlite-persistence-core 0.4.3 → 0.4.5

package/README.md

@@ -260,12 +260,20 @@ source publication and its durable suffix. A source may mark a transaction
 optimistic layer. The wrapper still gives that transaction one FIFO turn and
 writes its durable suffix before admitting the next source turn.
 
-The wrapper deliberately rejects schedules that would require a second
-ordering mechanism. An `immediate` source transaction cannot enter while an
-earlier normal source publication is waiting, and a source transaction cannot
-cross a hydration cycle. These cases throw
-`InvalidPersistedCollectionConfigError` instead of reordering data or waiting
-in a dependency cycle.
+Persisted rows establish a baseline for newer changes from the sync adapter.
+Once an ordinary sync transaction is accepted at `commit()`, queued reads of
+that baseline cannot revoke acceptance. This includes subset reads and rereads
+requested by coordinator reset or full-reload notifications. This rule assumes
+a compatible baseline; it does not authorize using an invalidated resume point.
+A truncate replay replaces earlier source rows in the same sync run. Sync
+transactions ordered after that replacement apply to the replacement.
+
+An `immediate` sync transaction cannot enter while an earlier normal source
+publication is waiting. The wrapper also currently rejects a sync transaction
+that remains open across another persistence read. These admission restrictions
+throw `InvalidPersistedCollectionConfigError`; an internal wait after accepted
+`commit()` is not an admission failure. The open-transaction restriction is
+separate from the accepted-transaction precedence rule.
 
 ### Atomic resume snapshots
 

package/dist/cjs/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from '@tanstack/db'\n\nexport class PersistedCollectionCoreError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `PersistedCollectionCoreError`\n  }\n}\n\nexport class InvalidPersistedCollectionConfigError extends PersistedCollectionCoreError {\n  constructor(message: string) {\n    super(message)\n    this.name = `InvalidPersistedCollectionConfigError`\n  }\n}\n\nexport class InvalidSyncConfigError extends InvalidPersistedCollectionConfigError {\n  constructor(details?: string) {\n    super(\n      details\n        ? `Invalid sync config: ${details}`\n        : `Invalid sync config: expected an object with a callable sync function`,\n    )\n    this.name = `InvalidSyncConfigError`\n  }\n}\n\nexport class InvalidPersistedCollectionCoordinatorError extends InvalidPersistedCollectionConfigError {\n  constructor(methodName: string) {\n    super(\n      `Invalid persisted collection coordinator: missing required \"${methodName}\" method`,\n    )\n    this.name = `InvalidPersistedCollectionCoordinatorError`\n  }\n}\n\nexport class InvalidPersistenceAdapterError extends InvalidPersistedCollectionConfigError {\n  constructor(methodName: string) {\n    super(\n      `Invalid persistence adapter: missing required \"${methodName}\" method`,\n    )\n    this.name = `InvalidPersistenceAdapterError`\n  }\n}\n\nexport type PersistedCollectionDurabilityErrorOptions = {\n  cause?: unknown\n  code?: unknown\n  path?: unknown\n}\n\nexport class PersistedCollectionDurabilityError extends PersistedCollectionCoreError {\n  override readonly cause: unknown\n  readonly code: unknown\n  readonly path: unknown\n\n  constructor(\n    message: string,\n    options: PersistedCollectionDurabilityErrorOptions = {},\n  ) {\n    super(message)\n    this.name = `PersistedCollectionDurabilityError`\n    this.cause = options.cause\n    this.code = options.code\n    this.path = options.path\n  }\n}\n\nexport function toPersistedCollectionDurabilityError(\n  collectionId: string,\n  cause: unknown,\n): PersistedCollectionDurabilityError {\n  if (cause instanceof PersistedCollectionDurabilityError) {\n    return cause\n  }\n\n  const details =\n    typeof cause === `object` && cause !== null\n      ? (cause as Record<string, unknown>)\n      : undefined\n  const message = cause instanceof Error ? cause.message : String(cause)\n  return new PersistedCollectionDurabilityError(\n    `Failed to durably persist collection \"${collectionId}\": ${message}`,\n    {\n      cause,\n      code: details?.code,\n      path: details?.path,\n    },\n  )\n}\n\nexport type IndeterminateCommitRequestType =\n  | `rpc:applyLocalMutations:req`\n  | `rpc:applyCommittedTx:req`\n\nexport type IndeterminateCommitErrorOptions = {\n  collectionId: string\n  requestType: IndeterminateCommitRequestType\n  previousLeaderId: string | null\n  previousTerm: number | null\n  currentLeaderId: string | null\n  currentTerm: number | null\n  cause: unknown\n}\n\nexport class IndeterminateCommitError extends PersistedCollectionCoreError {\n  readonly code: `INDETERMINATE_COMMIT` = `INDETERMINATE_COMMIT`\n  readonly collectionId: string\n  readonly requestType: IndeterminateCommitRequestType\n  readonly previousLeaderId: string | null\n  readonly previousTerm: number | null\n  readonly currentLeaderId: string | null\n  readonly currentTerm: number | null\n  override readonly cause: unknown\n\n  constructor(options: IndeterminateCommitErrorOptions) {\n    super(\n      `Commit outcome is indeterminate for collection \"${options.collectionId}\": ${options.requestType} crossed leadership from ${formatLeader(options.previousLeaderId, options.previousTerm)} to ${formatLeader(options.currentLeaderId, options.currentTerm)}`,\n    )\n    this.name = `IndeterminateCommitError`\n    this.collectionId = options.collectionId\n    this.requestType = options.requestType\n    this.previousLeaderId = options.previousLeaderId\n    this.previousTerm = options.previousTerm\n    this.currentLeaderId = options.currentLeaderId\n    this.currentTerm = options.currentTerm\n    this.cause = options.cause\n  }\n}\n\nfunction formatLeader(leaderId: string | null, term: number | null): string {\n  return `${leaderId ?? `unknown leader`} (term ${term ?? `unknown`})`\n}\n\nexport class DuplicateRemoteSubsetOwnerError extends PersistedCollectionCoreError {\n  readonly collectionId: string\n\n  constructor(collectionId: string) {\n    super(\n      `A remote subset owner is already registered for collection \"${collectionId}\"`,\n    )\n    this.name = `DuplicateRemoteSubsetOwnerError`\n    this.collectionId = collectionId\n  }\n}\n\nexport class RetryableRemoteSubsetAcquisitionError extends PersistedCollectionCoreError {\n  override readonly cause: unknown\n\n  constructor(message: string, cause?: unknown) {\n    super(message)\n    this.name = `RetryableRemoteSubsetAcquisitionError`\n    this.cause = cause\n  }\n}\n\nexport class InvalidPersistedStorageKeyError extends InvalidPersistedCollectionConfigError {\n  constructor(key: string | number) {\n    super(\n      `Invalid persisted storage key \"${String(key)}\": numeric keys must be finite`,\n    )\n    this.name = `InvalidPersistedStorageKeyError`\n  }\n}\n\nexport class InvalidPersistedStorageKeyEncodingError extends InvalidPersistedCollectionConfigError {\n  constructor(encoded: string) {\n    super(\n      `Invalid persisted storage key encoding \"${encoded}\": expected prefix \"n:\" or \"s:\"`,\n    )\n    this.name = `InvalidPersistedStorageKeyEncodingError`\n  }\n}\n\nexport class SQLiteBigIntOutOfRangeError extends PersistedCollectionCoreError {\n  constructor(value: bigint, minimum: bigint, maximum: bigint) {\n    super(\n      `SQLite BigInt value ${value} is outside the signed 64-bit range [${minimum}, ${maximum}]`,\n    )\n    this.name = `SQLiteBigIntOutOfRangeError`\n  }\n}\n\nexport class PersistenceUnavailableError extends PersistedCollectionCoreError {\n  constructor(details?: string) {\n    super(\n      details\n        ? `Persistence unavailable: ${details}`\n        : `Persistence unavailable in this runtime`,\n    )\n    this.name = `PersistenceUnavailableError`\n  }\n}\n"],"names":["TanStackDBError"],"mappings":"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"}
+{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from '@tanstack/db'\n\nexport class PersistedCollectionCoreError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `PersistedCollectionCoreError`\n  }\n}\n\nexport class InvalidPersistedCollectionConfigError extends PersistedCollectionCoreError {\n  constructor(message: string) {\n    super(message)\n    this.name = `InvalidPersistedCollectionConfigError`\n  }\n}\n\nexport class InvalidSyncConfigError extends InvalidPersistedCollectionConfigError {\n  constructor(details?: string) {\n    super(\n      details\n        ? `Invalid sync config: ${details}`\n        : `Invalid sync config: expected an object with a callable sync function`,\n    )\n    this.name = `InvalidSyncConfigError`\n  }\n}\n\nexport class InvalidPersistedCollectionCoordinatorError extends InvalidPersistedCollectionConfigError {\n  constructor(methodName: string) {\n    super(\n      `Invalid persisted collection coordinator: missing required \"${methodName}\" method`,\n    )\n    this.name = `InvalidPersistedCollectionCoordinatorError`\n  }\n}\n\nexport class InvalidPersistenceAdapterError extends InvalidPersistedCollectionConfigError {\n  constructor(methodName: string) {\n    super(\n      `Invalid persistence adapter: missing required \"${methodName}\" method`,\n    )\n    this.name = `InvalidPersistenceAdapterError`\n  }\n}\n\nexport type PersistedCollectionDurabilityErrorOptions = {\n  cause?: unknown\n  code?: unknown\n  path?: unknown\n}\n\nexport class PersistedCollectionDurabilityError extends PersistedCollectionCoreError {\n  override readonly cause: unknown\n  readonly code: unknown\n  readonly path: unknown\n\n  constructor(\n    message: string,\n    options: PersistedCollectionDurabilityErrorOptions = {},\n  ) {\n    super(message)\n    this.name = `PersistedCollectionDurabilityError`\n    this.cause = options.cause\n    this.code = options.code\n    this.path = options.path\n  }\n}\n\nexport function toPersistedCollectionDurabilityError(\n  collectionId: string,\n  cause: unknown,\n): PersistedCollectionDurabilityError {\n  if (cause instanceof PersistedCollectionDurabilityError) {\n    return cause\n  }\n\n  const details =\n    typeof cause === `object` && cause !== null\n      ? (cause as Record<string, unknown>)\n      : undefined\n  const message = cause instanceof Error ? cause.message : String(cause)\n  return new PersistedCollectionDurabilityError(\n    `Failed to durably persist collection \"${collectionId}\": ${message}`,\n    {\n      cause,\n      code: details?.code,\n      path: details?.path,\n    },\n  )\n}\n\nexport type IndeterminateCommitRequestType =\n  `rpc:applyLocalMutations:req` | `rpc:applyCommittedTx:req`\n\nexport type IndeterminateCommitErrorOptions = {\n  collectionId: string\n  requestType: IndeterminateCommitRequestType\n  previousLeaderId: string | null\n  previousTerm: number | null\n  currentLeaderId: string | null\n  currentTerm: number | null\n  cause: unknown\n}\n\nexport class IndeterminateCommitError extends PersistedCollectionCoreError {\n  readonly code: `INDETERMINATE_COMMIT` = `INDETERMINATE_COMMIT`\n  readonly collectionId: string\n  readonly requestType: IndeterminateCommitRequestType\n  readonly previousLeaderId: string | null\n  readonly previousTerm: number | null\n  readonly currentLeaderId: string | null\n  readonly currentTerm: number | null\n  override readonly cause: unknown\n\n  constructor(options: IndeterminateCommitErrorOptions) {\n    super(\n      `Commit outcome is indeterminate for collection \"${options.collectionId}\": ${options.requestType} crossed leadership from ${formatLeader(options.previousLeaderId, options.previousTerm)} to ${formatLeader(options.currentLeaderId, options.currentTerm)}`,\n    )\n    this.name = `IndeterminateCommitError`\n    this.collectionId = options.collectionId\n    this.requestType = options.requestType\n    this.previousLeaderId = options.previousLeaderId\n    this.previousTerm = options.previousTerm\n    this.currentLeaderId = options.currentLeaderId\n    this.currentTerm = options.currentTerm\n    this.cause = options.cause\n  }\n}\n\nfunction formatLeader(leaderId: string | null, term: number | null): string {\n  return `${leaderId ?? `unknown leader`} (term ${term ?? `unknown`})`\n}\n\nexport class DuplicateRemoteSubsetOwnerError extends PersistedCollectionCoreError {\n  readonly collectionId: string\n\n  constructor(collectionId: string) {\n    super(\n      `A remote subset owner is already registered for collection \"${collectionId}\"`,\n    )\n    this.name = `DuplicateRemoteSubsetOwnerError`\n    this.collectionId = collectionId\n  }\n}\n\nexport class RetryableRemoteSubsetAcquisitionError extends PersistedCollectionCoreError {\n  override readonly cause: unknown\n\n  constructor(message: string, cause?: unknown) {\n    super(message)\n    this.name = `RetryableRemoteSubsetAcquisitionError`\n    this.cause = cause\n  }\n}\n\nexport class InvalidPersistedStorageKeyError extends InvalidPersistedCollectionConfigError {\n  constructor(key: string | number) {\n    super(\n      `Invalid persisted storage key \"${String(key)}\": numeric keys must be finite`,\n    )\n    this.name = `InvalidPersistedStorageKeyError`\n  }\n}\n\nexport class InvalidPersistedStorageKeyEncodingError extends InvalidPersistedCollectionConfigError {\n  constructor(encoded: string) {\n    super(\n      `Invalid persisted storage key encoding \"${encoded}\": expected prefix \"n:\" or \"s:\"`,\n    )\n    this.name = `InvalidPersistedStorageKeyEncodingError`\n  }\n}\n\nexport class SQLiteBigIntOutOfRangeError extends PersistedCollectionCoreError {\n  constructor(value: bigint, minimum: bigint, maximum: bigint) {\n    super(\n      `SQLite BigInt value ${value} is outside the signed 64-bit range [${minimum}, ${maximum}]`,\n    )\n    this.name = `SQLiteBigIntOutOfRangeError`\n  }\n}\n\nexport class PersistenceUnavailableError extends PersistedCollectionCoreError {\n  constructor(details?: string) {\n    super(\n      details\n        ? `Persistence unavailable: ${details}`\n        : `Persistence unavailable in this runtime`,\n    )\n    this.name = `PersistenceUnavailableError`\n  }\n}\n"],"names":["TanStackDBError"],"mappings":"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"}

package/dist/cjs/index.cjs

@@ -37,10 +37,15 @@ exports.PERSISTED_VALUE_TAG = sqliteValue.PERSISTED_VALUE_TAG;
 exports.SQLITE_BIGINT_MAX = sqliteValue.SQLITE_BIGINT_MAX;
 exports.SQLITE_BIGINT_MIN = sqliteValue.SQLITE_BIGINT_MIN;
 exports.assertSQLiteBigIntInRange = sqliteValue.assertSQLiteBigIntInRange;
+exports.reviveSQLiteTemporal = sqliteValue.reviveSQLiteTemporal;
 exports.serializeSQLiteBigInt = sqliteValue.serializeSQLiteBigInt;
+exports.serializeSQLiteTemporal = sqliteValue.serializeSQLiteTemporal;
+exports.sqliteTemporalIdentity = sqliteValue.sqliteTemporalIdentity;
+exports.sqliteTemporalKind = sqliteValue.sqliteTemporalKind;
 exports.RemoteSubsetWireValueError = remoteSubsetWire.RemoteSubsetWireValueError;
 exports.toProcessLocalLoadSubsetOptions = remoteSubsetWire.toProcessLocalLoadSubsetOptions;
 exports.toTransportedLoadSubsetOptions = remoteSubsetWire.toTransportedLoadSubsetOptions;
+exports.validateRemoteSubsetOptions = remoteSubsetWire.validateRemoteSubsetOptions;
 Object.defineProperty(exports, "safeRandomUUID", {
   enumerable: true,
   get: () => db.safeRandomUUID

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/persisted.cjs

@@ -178,8 +178,8 @@ class SingleProcessCoordinator {
   setAdapterForCollection(collectionId, adapter) {
     this.collectionAdapters.set(collectionId, adapter);
   }
-  async requestApplyCommittedTx(collectionId, tx) {
-    const adapter = this.collectionAdapters.get(collectionId);
+  async requestApplyCommittedTx(collectionId, tx, scopedAdapter) {
+    const adapter = scopedAdapter ?? this.collectionAdapters.get(collectionId);
     if (!adapter) {
       throw new errors.InvalidPersistedCollectionConfigError(
         `SingleProcessCoordinator has no persistence adapter configured for collection "${collectionId}"`
@@ -335,6 +335,8 @@ function toStableSerializable(value) {
     case `undefined`:
       return void 0;
   }
+  const temporal = sqliteValue.serializeSQLiteTemporal(value);
+  if (temporal) return temporal;
   if (value instanceof Date) {
     return value.toISOString();
   }
@@ -442,7 +444,6 @@ class PersistedCollectionRuntime {
     this.resumeGenerationOwner = /* @__PURE__ */ Symbol(`persisted resume generation owner`);
     this.lifecycleGeneration = 0;
     this.internalApplyDepth = 0;
-    this.sourcePublicationWaitDepth = 0;
     this.appliedReceiptSequence = 0;
     this.syncErrorReported = false;
     this.pendingAppliedReceipts = /* @__PURE__ */ new Map();
@@ -501,11 +502,14 @@ class PersistedCollectionRuntime {
     void receipt.then(removeReceipt, removeReceipt);
     return receipt;
   }
-  async waitForAppliedReceiptsAfter(cursor) {
+  // Startup waits for acceptance: a local mutation's handler can wait for
+  // startup, and the rows publish when that mutation settles. Readiness waits
+  // for them in core. A subset load waits for visibility.
+  async waitForAppliedReceiptsAfter(cursor, until = `visible`) {
     await Promise.all(
       Array.from(
         this.pendingAppliedReceipts,
-        ([sequence, receipt]) => sequence > cursor ? receipt : void 0
+        ([sequence, receipt]) => sequence <= cursor ? void 0 : until === `accepted` ? db.whenSyncAccepted(receipt) : receipt
       )
     );
   }
@@ -666,7 +670,10 @@ class PersistedCollectionRuntime {
           startup.completedLocalIndexSignatures
         );
         if (startup.appliedCursor !== void 0 && lifecycleGeneration === this.lifecycleGeneration) {
-          await this.waitForAppliedReceiptsAfter(startup.appliedCursor);
+          await this.waitForAppliedReceiptsAfter(
+            startup.appliedCursor,
+            `accepted`
+          );
         }
       }
       if (lifecycleGeneration === this.lifecycleGeneration) {
@@ -701,7 +708,7 @@ class PersistedCollectionRuntime {
         return result;
       });
       if (appliedCursor !== void 0 && lifecycleGeneration === this.lifecycleGeneration) {
-        await this.waitForAppliedReceiptsAfter(appliedCursor);
+        await this.waitForAppliedReceiptsAfter(appliedCursor, `accepted`);
       }
     })().catch((error) => {
       throw this.markTerminalFailure(error, lifecycleGeneration);
@@ -742,7 +749,6 @@ class PersistedCollectionRuntime {
     await this.hydrateSubsetUnsafe(
       baseline,
       {
-        requestRemoteEnsure: false,
         lifecycleGeneration,
         bindKeySetEvidence: true
       },
@@ -790,7 +796,7 @@ class PersistedCollectionRuntime {
     const applied = this.replaceCollectionMetadataSnapshot(
       snapshot.collectionMetadata
     );
-    if (applied !== true) await applied;
+    await db.whenSyncAccepted(applied);
   }
   async loadCollectionMetadataSnapshot(adapter) {
     if (!adapter.loadCollectionMetadata) {
@@ -807,7 +813,7 @@ class PersistedCollectionRuntime {
     );
     const currentKeys = this.syncControls.metadata.collection.list().map(({ key }) => key);
     return this.withInternalApply(() => {
-      this.syncControls.begin?.({ immediate: true });
+      this.syncControls.begin?.();
       currentKeys.forEach((key) => {
         if (!nextMetadata.has(key)) {
           this.syncControls.metadata?.collection.delete(key);
@@ -825,6 +831,7 @@ class PersistedCollectionRuntime {
     const subsetKey = this.getSubsetKey(options);
     const truncateGeneration = this.sourceTruncateGeneration;
     const routeRemoteDemandDuringHydration = this.canRouteRemoteDemandThroughCoordinator();
+    if (routeRemoteDemandDuringHydration) remoteSubsetWire.validateRemoteSubsetOptions(options);
     this.activeSubsets.set(subsetKey, options);
     const appliedCursor = this.appliedReceiptSequence;
     try {
@@ -834,7 +841,6 @@ class PersistedCollectionRuntime {
             (adapter) => this.hydrateSubsetUnsafe(
               options,
               {
-                requestRemoteEnsure: this.mode === `sync-present` && !routeRemoteDemandDuringHydration,
                 lifecycleGeneration,
                 requestLocalLoadFailure: true,
                 rejectBufferedReplayFailure: true
@@ -850,6 +856,9 @@ class PersistedCollectionRuntime {
       });
       if (lifecycleGeneration !== this.lifecycleGeneration) return;
       await this.waitForAppliedReceiptsAfter(appliedCursor);
+      if (!routeRemoteDemandDuringHydration && this.canRouteRemoteDemandThroughCoordinator()) {
+        remoteSubsetWire.validateRemoteSubsetOptions(options);
+      }
     } catch (error) {
       if (this.activeSubsets.get(subsetKey) === options) {
         this.activeSubsets.delete(subsetKey);
@@ -959,7 +968,6 @@ class PersistedCollectionRuntime {
         (adapter) => this.hydrateSubsetUnsafe(
           options,
           {
-            requestRemoteEnsure: false,
             lifecycleGeneration,
             rejectBufferedReplayFailure: true
           },
@@ -982,13 +990,6 @@ class PersistedCollectionRuntime {
   applyHydrationBufferedTransaction(transaction) {
     const failure = this.getCurrentTerminalFailure();
     if (failure) return Promise.reject(failure.error);
-    if (transaction.beginOptions?.immediate && this.sourcePublicationWaitDepth > 0) {
-      return Promise.reject(
-        new errors.InvalidPersistedCollectionConfigError(
-          `immediate persisted source replay cannot enter while an earlier source publication is waiting`
-        )
-      );
-    }
     return this.applyMutex.run(async () => {
       await this.applyBufferedSyncTransactionUnsafe(transaction);
     });
@@ -1209,7 +1210,7 @@ class PersistedCollectionRuntime {
             hydrationContext.suppliedRowKeys.add(row.key);
           }
           const applied = this.applyRowsToCollection(rows);
-          if (applied !== true) await applied;
+          await db.whenSyncAccepted(applied);
         }
       } finally {
         if (this.activeHydrationContext === hydrationContext && this.hydratingGeneration === config.lifecycleGeneration) {
@@ -1219,9 +1220,6 @@ class PersistedCollectionRuntime {
       if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
       replayFailure = await this.flushQueuedHydrationTransactionsUnsafe(adapter);
       if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
-      if (config.requestRemoteEnsure && !replayFailure) {
-        this.queueRemoteSubsetEnsure(options);
-      }
     } catch (error) {
       if (config.requestLocalLoadFailure && !rowsLoaded) {
         this.hydratingGeneration = config.lifecycleGeneration;
@@ -1352,7 +1350,7 @@ class PersistedCollectionRuntime {
       return true;
     }
     return this.withInternalApply(() => {
-      this.syncControls.begin?.({ immediate: true });
+      this.syncControls.begin?.();
       for (const row of rows) {
         if (this.collection?._hasHydratedKey(row.key)) {
           continue;
@@ -1398,7 +1396,7 @@ class PersistedCollectionRuntime {
     );
     const currentKeys = this.syncControls.metadata.collection.list().map(({ key }) => key);
     return this.withInternalApply(() => {
-      this.syncControls.begin?.({ immediate: true });
+      this.syncControls.begin?.();
       this.syncControls.truncate?.();
       for (const row of rows) {
         this.syncControls.write?.({
@@ -1452,14 +1450,9 @@ class PersistedCollectionRuntime {
       const applied = transaction.internal ? this.withInternalApply(transaction.applyToCollection) : transaction.applyToCollection();
       applicationReturned = true;
       abortedDuringApplication = transaction.signal?.aborted === true;
-      if (applied !== true) {
-        this.sourcePublicationWaitDepth++;
-        try {
-          await applied;
-        } finally {
-          this.sourcePublicationWaitDepth--;
-        }
-      }
+      if (transaction.internal) await db.whenSyncAccepted(applied);
+      else if (applied !== true && !this.collection?._state.hasPersistingTransaction())
+        await applied;
       this.throwIfLifecycleReplaced(transaction.lifecycleGeneration);
       if (!transaction.internal) {
         await this.persistAndBroadcastExternalSyncTransactionUnsafe(
@@ -1629,7 +1622,7 @@ class PersistedCollectionRuntime {
       return;
     }
     const applied = this.withInternalApply(() => {
-      this.syncControls.begin?.({ immediate: true });
+      this.syncControls.begin?.();
       for (const mutation of mutations) {
         if (mutation.type === `delete`) {
           this.syncControls.write?.({
@@ -1645,9 +1638,8 @@ class PersistedCollectionRuntime {
       }
       return this.syncControls.commit?.() ?? true;
     });
-    if (applied !== true) {
-      await applied;
-    }
+    const accepted = db.whenSyncAccepted(applied);
+    if (accepted !== true) await accepted;
   }
   filterMutationsForCollection(mutations) {
     const collection = this.collection;
@@ -1820,6 +1812,7 @@ class PersistedCollectionRuntime {
     }
     const subsetKey = this.getSubsetKey(options);
     if (this.activeSubsets.get(subsetKey) !== options) return;
+    remoteSubsetWire.validateRemoteSubsetOptions(options);
     this.pendingRemoteSubsetEnsures.set(subsetKey, options);
     void this.flushPendingRemoteSubsetEnsures();
   }
@@ -2035,11 +2028,11 @@ class PersistedCollectionRuntime {
     this.resetSequence++;
     if (this.syncControls.begin && this.syncControls.commit) {
       const applied = this.withInternalApply(() => {
-        this.syncControls.begin?.({ immediate: true });
+        this.syncControls.begin?.();
         this.syncControls.truncate?.();
         return this.syncControls.commit?.() ?? true;
       });
-      if (applied !== true) await applied;
+      await db.whenSyncAccepted(applied);
     }
     if (lifecycleGeneration !== this.lifecycleGeneration) return;
     await this.reloadActiveSubsetsUnsafe(adapter);
@@ -2072,7 +2065,7 @@ class PersistedCollectionRuntime {
       (opt) => opt.where ? db.compileSingleRowExpression(opt.where) : null
     );
     const applied = this.withInternalApply(() => {
-      this.syncControls.begin?.({ immediate: true });
+      this.syncControls.begin?.();
       for (const {
         key: changedKey,
         value: newValue
@@ -2112,7 +2105,7 @@ class PersistedCollectionRuntime {
       });
       return this.syncControls.commit?.() ?? true;
     });
-    if (applied !== true) await applied;
+    await db.whenSyncAccepted(applied);
   }
   async reloadActiveSubsetsUnsafe(adapter) {
     const lifecycleGeneration = this.lifecycleGeneration;
@@ -2148,7 +2141,7 @@ class PersistedCollectionRuntime {
         })),
         collectionMetadata
       );
-      if (applied !== true) await applied;
+      await db.whenSyncAccepted(applied);
     } finally {
       if (this.activeHydrationContext === hydrationContext && this.hydratingGeneration === lifecycleGeneration) {
         this.hydratingGeneration = null;
@@ -2222,8 +2215,8 @@ class PersistedCollectionRuntime {
     await this.requestCoordinatorPersistedIndex(indexMetadata, completedLocally);
   }
   async ensureLocalPersistedIndex(indexMetadata, adapter) {
-    const spec = this.buildPersistedIndexSpec(indexMetadata);
     try {
+      const spec = this.buildPersistedIndexSpec(indexMetadata);
       await adapter.ensureIndex(
         this.collectionId,
         indexMetadata.signature,
@@ -2236,8 +2229,8 @@ class PersistedCollectionRuntime {
     }
   }
   async requestCoordinatorPersistedIndex(indexMetadata, completedLocally) {
-    const spec = this.buildPersistedIndexSpec(indexMetadata);
     try {
+      const spec = this.buildPersistedIndexSpec(indexMetadata);
       await this.persistence.coordinator.requestEnsurePersistedIndex(
         this.collectionId,
         indexMetadata.signature,
@@ -2314,6 +2307,14 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
       const settlePendingTransaction = (transaction) => {
         removePendingPublicationTransaction(transaction);
       };
+      const visibleAfterDurable = (transaction, durable) => {
+        const visible = durable.then(async () => {
+          const receipt = transaction.applicationReceipt;
+          if (receipt !== void 0 && receipt !== true) await receipt;
+        });
+        void visible.catch(() => void 0);
+        return db.withAcceptedReceipt(visible, durable);
+      };
       const settleRuntimeTransaction = (transaction, applied) => {
         void applied.then(
           () => settlePendingTransaction(transaction),
@@ -2421,9 +2422,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             }
           }
           transaction.deferredHydrationMetadataDeleteKeys.clear();
-          params.begin(
-            transaction.queuedBecauseHydrating ? { immediate: true } : transaction.beginOptions
-          );
+          params.begin();
           if (transaction.truncate) params.truncate();
           for (const operation of transaction.operations) {
             if (operation.type === `delete`) {
@@ -2449,14 +2448,8 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           }
           const applied = params.commit(signal);
           transaction.applicationReceipt = applied;
-          if (applied === true) {
-            removePendingPublicationTransaction(transaction);
-          } else {
-            void applied.then(
-              () => removePendingPublicationTransaction(transaction),
-              () => removePendingPublicationTransaction(transaction)
-            );
-          }
+          removePendingPublicationTransaction(transaction);
+          if (applied !== true) void applied.catch(() => void 0);
           return applied;
         } catch (error) {
           removePendingPublicationTransaction(transaction);
@@ -2477,6 +2470,11 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
       const persistenceCapability = {
         protocol: db.SYNC_PERSISTENCE_PROTOCOL,
         version: db.SYNC_PERSISTENCE_VERSION,
+        reserveCommitTurn: () => {
+          const openTransaction = getOpenTransaction();
+          if (openTransaction && !openTransaction.internal)
+            openTransaction.reservesCommitTurn = true;
+        },
         hydrateBaseline: async () => {
           if (startupState.cleanedUp) return;
           try {
@@ -2526,7 +2524,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             params.markReady();
           }).catch(() => void 0);
         },
-        begin: (options) => {
+        begin: () => {
           if (startupState.cleanedUp) return void 0;
           const terminalFailure = getTerminalFailure();
           const internal = runtime.isApplyingInternally();
@@ -2539,7 +2537,6 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             truncate: false,
             internal,
             lifecycleGeneration: runtime.getLifecycleGeneration(),
-            beginOptions: options,
             operationKeys: /* @__PURE__ */ new Set(),
             hasDependentSuccessor: false,
             queuedBecauseHydrating: terminalFailure === void 0 && !internal && runtime.isHydratingNow(),
@@ -2798,7 +2795,6 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             truncate: openTransaction.truncate,
             internal: false,
             lifecycleGeneration: openTransaction.lifecycleGeneration,
-            beginOptions: openTransaction.beginOptions,
             expectedResumeGenerationOwner: openTransaction.expectedResumeGenerationOwner,
             signal,
             prependHydrationRows: (rows) => {
@@ -2840,8 +2836,9 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             });
             settlePublicationAdmissionWaiters(openTransaction);
             settleRuntimeTransaction(openTransaction, applied2);
-            return applied2;
+            return visibleAfterDurable(openTransaction, applied2);
           }
+          openTransaction.hydrationSequence = void 0;
           let applied;
           try {
             applied = runtime.applyHydrationBufferedTransaction(transaction);
@@ -2851,7 +2848,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           }
           settlePublicationAdmissionWaiters(openTransaction);
           settleRuntimeTransaction(openTransaction, applied);
-          return applied;
+          return visibleAfterDurable(openTransaction, applied);
         }
       };
       let sourceResult = {};
@@ -2959,7 +2956,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             }
           };
           const openTransaction = getOpenTransaction();
-          const needsPublicationAdmission = openTransaction && !openTransaction.internal && openTransaction.beginOptions?.immediate;
+          const needsPublicationAdmission = openTransaction?.reservesCommitTurn === true;
           const hydrated = sourceResultSettled && !needsPublicationAdmission ? runtime.loadHydratedSubset(
             options,
             (loadOptions) => forwardUpstream(sourceResult, loadOptions)
@@ -2974,7 +2971,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
               return;
             }
             const currentTransaction = getOpenTransaction();
-            if (currentTransaction && !currentTransaction.internal && currentTransaction.beginOptions?.immediate) {
+            if (currentTransaction?.reservesCommitTurn) {
               await waitForPublicationAdmission(
                 currentTransaction,
                 options,