@tanstack/electric-db-collection 0.5.8 → 0.6.0

package/dist/cjs/electric.cjs

@@ -149,10 +149,25 @@ function getStableShapeIdentity(shapeOptions) {
 function hasTxids(message) {
   return `txids` in message.headers && Array.isArray(message.headers.txids);
 }
+const abortReason = (abortedSignal) => abortedSignal.reason ?? new db.LoadSubsetOperationAbortedError();
+const waitForDemandOrAbort = (work, demandSignal) => {
+  if (!demandSignal) return work;
+  let removeAbortListener = () => {
+  };
+  const aborted = new Promise((_, reject) => {
+    const onAbort = () => reject(abortReason(demandSignal));
+    demandSignal.addEventListener(`abort`, onAbort, { once: true });
+    removeAbortListener = () => demandSignal.removeEventListener(`abort`, onAbort);
+    if (demandSignal.aborted) onAbort();
+  });
+  return Promise.race([work, aborted]).finally(removeAbortListener);
+};
 function createLoadSubsetDedupe({
   stream,
   syncMode,
   isBufferingInitialSync,
+  waitForFullSnapshot,
+  waitForEstablishedSnapshot,
   begin,
   write,
   commit,
@@ -161,16 +176,18 @@ function createLoadSubsetDedupe({
   recordSnapshotRow,
   collectionId,
   encodeColumnName,
-  signal
+  signal,
+  isCleanupAbort,
+  beforeSnapshot
 }) {
   if (syncMode === `eager`) {
     return null;
   }
   const compileOptions = encodeColumnName ? { encodeColumnName } : void 0;
   const logPrefix = collectionId ? `[${collectionId}] ` : ``;
-  const abortReason = (abortedSignal) => abortedSignal.reason ?? new db.LoadSubsetOperationAbortedError();
+  let snapshotTail;
   function handleSnapshotError(error, operation) {
-    if (signal.aborted) {
+    if (signal.aborted && isCleanupAbort()) {
       debug(`${logPrefix}Ignoring ${operation} error during cleanup: %o`, error);
       return true;
     }
@@ -183,14 +200,48 @@ function createLoadSubsetDedupe({
       if (signal.aborted) throw abortReason(signal);
       if (opts.signal?.aborted) throw abortReason(opts.signal);
     };
+    const stopAfterStreamAbort = () => {
+      if (!signal.aborted) return false;
+      if (!isCleanupAbort()) throw abortReason(signal);
+      return true;
+    };
+    const requestSnapshotInOrder = (params) => {
+      const invoke = () => {
+        throwIfAborted();
+        return stream.requestSnapshot(params);
+      };
+      const request = snapshotTail ? snapshotTail.then(invoke) : invoke();
+      snapshotTail = request.then(
+        () => void 0,
+        () => void 0
+      );
+      return waitForDemandOrAbort(request, opts.signal);
+    };
     throwIfAborted();
+    if (beforeSnapshot) {
+      await beforeSnapshot();
+      throwIfAborted();
+    }
+    const settleWith = async (establishing) => {
+      const demandSignal = opts.signal;
+      try {
+        await waitForDemandOrAbort(establishing, demandSignal);
+      } catch (error) {
+        if (signal.aborted && isCleanupAbort()) return;
+        if (demandSignal?.aborted) throw abortReason(demandSignal);
+        throw error;
+      }
+      if (signal.aborted && isCleanupAbort()) return;
+      if (demandSignal?.aborted) throw abortReason(demandSignal);
+    };
+    if (waitForFullSnapshot) return settleWith(waitForFullSnapshot());
     if (isBufferingInitialSync()) {
       const snapshotParams = sqlCompiler.compileSQL(opts, compileOptions);
       try {
         const { data: rows } = await stream.fetchSnapshot(snapshotParams);
         if (!isBufferingInitialSync()) {
           debug(`${logPrefix}Ignoring snapshot - sync completed while fetching`);
-          return;
+          return settleWith(waitForEstablishedSnapshot());
         }
         throwIfAborted();
         if (rows.length > 0) {
@@ -217,9 +268,8 @@ function createLoadSubsetDedupe({
       if (opts.signal?.aborted) throw abortReason(opts.signal);
       return;
     }
-    if (syncMode === `progressive`) {
-      return;
-    }
+    if (syncMode === `progressive`)
+      return settleWith(waitForEstablishedSnapshot());
     const { cursor, where, orderBy, limit } = opts;
     throwIfAborted();
     try {
@@ -242,22 +292,24 @@ function createLoadSubsetDedupe({
         debug(
           `${logPrefix}Requesting cursor.whereFrom snapshot (with limit ${limit})`
         );
-        await Promise.all([
-          stream.requestSnapshot(whereCurrentParams),
-          stream.requestSnapshot(whereFromParams)
-        ]);
+        await requestSnapshotInOrder(whereCurrentParams);
+        await requestSnapshotInOrder(whereFromParams);
       } else {
         const snapshotParams = sqlCompiler.compileSQL(opts, compileOptions);
-        await stream.requestSnapshot(snapshotParams);
+        await requestSnapshotInOrder(snapshotParams);
       }
     } catch (error) {
-      if (opts.signal?.aborted) return;
+      if (opts.signal?.aborted) throw abortReason(opts.signal);
       if (handleSnapshotError(error, `requestSnapshot`)) {
         return;
       }
       throw error;
     }
-    await waitForCommitsAfter(commitCursor);
+    if (opts.signal?.aborted) throw abortReason(opts.signal);
+    if (stopAfterStreamAbort()) return;
+    await waitForDemandOrAbort(waitForCommitsAfter(commitCursor), opts.signal);
+    if (opts.signal?.aborted) throw abortReason(opts.signal);
+    if (stopAfterStreamAbort()) return;
   };
   return new db.DeduplicatedLoadSubset({ loadSubset });
 }
@@ -309,6 +361,11 @@ class ElectricLifecycle {
     this.matchBuffer = { committedMessages: [], pendingMessages: [] };
     this.evidence.hydratedResumeState = void 0;
   }
+  forgetEvidenceAfterScopedRecovery() {
+    this.evidence.seenTxids.clear();
+    this.evidence.seenSnapshots.length = 0;
+    this.evidence.hydratedResumeState = void 0;
+  }
   exportMeta() {
     return exportElectricSyncMeta(this.evidence);
   }
@@ -754,622 +811,811 @@ function createElectricSync(shapeOptions, options) {
     };
   };
   const collectionTags = /* @__PURE__ */ new WeakMap();
-  return {
-    getSyncMetadata: () => ({
-      relation: shapeOptions.params?.table ? [relationSchema || `public`, shapeOptions.params.table] : void 0
-    }),
-    sync: (params) => {
-      const retainsTagState = collectionTags.has(params.collection);
-      let tagState = collectionTags.get(params.collection);
-      if (!tagState) {
-        tagState = createTagState();
-        collectionTags.set(params.collection, tagState);
+  const startSession = (params, freshScopedGeneration = false) => {
+    const retainsTagState = collectionTags.has(params.collection);
+    let tagState = collectionTags.get(params.collection);
+    if (!tagState) {
+      tagState = createTagState();
+      collectionTags.set(params.collection, tagState);
+    }
+    const {
+      processTagsForChangeMessage,
+      clearTagTrackingState,
+      clearTagsForRow,
+      processMoveOutEvent,
+      processMoveInEvent
+    } = tagState;
+    if (freshScopedGeneration) clearTagTrackingState();
+    const lifecycle = getLifecycle(params.collection);
+    if (freshScopedGeneration) lifecycle.forgetEvidenceAfterScopedRecovery();
+    const lifecycleEpoch = lifecycle.start();
+    const isActiveLifecycle = () => lifecycle.isActive(lifecycleEpoch);
+    Object.assign(params.collection.utils, lifecycle.utils);
+    const {
+      begin,
+      write,
+      commit: commitSyncTransaction,
+      markReady,
+      markError,
+      truncate,
+      collection,
+      metadata
+    } = params;
+    let commitSequence = 0;
+    const pendingAppliedReceipts = /* @__PURE__ */ new Map();
+    const commit = (signal) => {
+      const sequence = ++commitSequence;
+      const applied = commitSyncTransaction(signal);
+      if (applied === true) {
+        return true;
       }
-      const {
-        processTagsForChangeMessage,
-        clearTagTrackingState,
-        clearTagsForRow,
-        processMoveOutEvent,
-        processMoveInEvent
-      } = tagState;
-      const lifecycle = getLifecycle(params.collection);
-      const lifecycleEpoch = lifecycle.start();
-      const isActiveLifecycle = () => lifecycle.isActive(lifecycleEpoch);
-      Object.assign(params.collection.utils, lifecycle.utils);
-      const {
-        begin,
-        write,
-        commit: commitSyncTransaction,
-        markReady,
-        markError,
-        truncate,
-        collection,
-        metadata
-      } = params;
-      let commitSequence = 0;
-      const pendingAppliedReceipts = /* @__PURE__ */ new Map();
-      const commit = (signal) => {
-        const sequence = ++commitSequence;
-        const applied = commitSyncTransaction(signal);
-        if (applied === true) {
-          return true;
-        }
-        pendingAppliedReceipts.set(sequence, applied);
-        const removeReceipt = () => pendingAppliedReceipts.delete(sequence);
-        void applied.then(removeReceipt, removeReceipt);
-        return applied;
-      };
-      const waitForCommitsAfter = async (cursor) => {
-        await Promise.all(
-          Array.from(
-            pendingAppliedReceipts,
-            ([sequence, applied]) => sequence > cursor ? applied : void 0
-          )
-        );
-      };
-      const readPersistedResumeState = () => {
-        const persistedResumeState2 = metadata?.collection.get(`electric:resume`);
-        return parseElectricResumeState(persistedResumeState2);
-      };
-      const persistence = metadata === void 0 ? null : db.validateSyncPersistenceCapability(metadata.persistence);
-      const hydrateBaseline = persistence?.hydrateBaseline;
-      const resumeSnapshot = persistence?.resumeSnapshot;
-      const certifyResumeSnapshot = resumeSnapshot?.certify;
-      const getKeySetEvidence = resumeSnapshot?.getKeySetEvidence;
-      const expectCurrentCommit = resumeSnapshot?.expectCurrentCommit;
-      const persistedKeySetEvidence = getKeySetEvidence?.();
-      const persistedResumeState = getNewestElectricResumeState(
-        readPersistedResumeState(),
-        lifecycle.resumeState
+      pendingAppliedReceipts.set(sequence, applied);
+      const removeReceipt = () => pendingAppliedReceipts.delete(sequence);
+      void applied.then(removeReceipt, removeReceipt);
+      return applied;
+    };
+    const waitForCommitsAfter = async (cursor) => {
+      await Promise.all(
+        Array.from(
+          pendingAppliedReceipts,
+          ([sequence, applied]) => sequence > cursor ? applied : void 0
+        )
       );
-      const shapeIdentity = getStableShapeIdentity({
-        url: shapeOptions.url,
-        params: shapeOptions.params
+    };
+    const persistence = metadata === void 0 ? null : db.validateSyncPersistenceCapability(metadata.persistence);
+    const hydrateBaseline = persistence?.hydrateBaseline;
+    const resumeSnapshot = persistence?.resumeSnapshot;
+    const certifyResumeSnapshot = resumeSnapshot?.certify;
+    const getKeySetEvidence = resumeSnapshot?.getKeySetEvidence;
+    const expectCurrentCommit = resumeSnapshot?.expectCurrentCommit;
+    const persistedKeySetEvidence = getKeySetEvidence?.();
+    const storedResumeRecord = freshScopedGeneration ? void 0 : metadata?.collection.get(`electric:resume`);
+    const storedResumeState = parseElectricResumeState(storedResumeRecord);
+    const malformedPersistedResume = storedResumeRecord !== void 0 && storedResumeState === void 0;
+    const persistedResumeState = getNewestElectricResumeState(
+      storedResumeState,
+      lifecycle.resumeState
+    );
+    const shapeIdentity = getStableShapeIdentity({
+      url: shapeOptions.url,
+      params: shapeOptions.params
+    });
+    const hasIncompatiblePersistedResume = persistedResumeState?.kind === `resume` && persistedResumeState.shapeId !== shapeIdentity;
+    const lacksCompletePersistedKeySet = persistedResumeState?.kind === `resume` && getKeySetEvidence !== void 0 && persistedKeySetEvidence?.status !== `consistent`;
+    const hasIncompatibleManagedCache = persistence?.managedCacheGeneration === true && persistedKeySetEvidence?.status === `incompatible`;
+    const requiresFreshSourceEvidence = !freshScopedGeneration && (hasIncompatibleManagedCache || shapeOptions.offset === void 0 && shapeOptions.handle === void 0 && (persistedResumeState !== void 0 || malformedPersistedResume) && (malformedPersistedResume || hasIncompatiblePersistedResume || persistedResumeState?.kind === `reset` || lacksCompletePersistedKeySet || !retainsTagState && persistedResumeState?.kind === `resume` && persistedResumeState.requiresTagState !== false));
+    const scopedRecovery = syncMode === `on-demand` && requiresFreshSourceEvidence && persistence?.managedCacheGeneration === true && persistence.startScopedRecovery !== void 0;
+    if (scopedRecovery) lifecycle.forgetEvidenceAfterScopedRecovery();
+    const usesChangesOnlyLog = syncMode === `on-demand` && (!requiresFreshSourceEvidence || scopedRecovery);
+    const usesFullLog = syncMode === `on-demand` && !usesChangesOnlyLog;
+    const tracksFullSnapshot = usesFullLog || syncMode === `progressive`;
+    let resolveFullSnapshot = () => {
+    };
+    let rejectFullSnapshot = () => {
+    };
+    let fullSnapshotReady = Promise.resolve();
+    const resetFullSnapshot = () => {
+      if (!tracksFullSnapshot) return;
+      fullSnapshotReady = new Promise((resolve, reject) => {
+        resolveFullSnapshot = (receipt) => resolve(receipt === true ? void 0 : receipt);
+        rejectFullSnapshot = reject;
       });
-      const hasIncompatiblePersistedResume = persistedResumeState?.kind === `resume` && persistedResumeState.shapeId !== shapeIdentity;
-      const lacksCompletePersistedKeySet = persistedResumeState?.kind === `resume` && getKeySetEvidence !== void 0 && persistedKeySetEvidence?.status !== `consistent`;
-      const needsFullSnapshot = shapeOptions.offset === void 0 && shapeOptions.handle === void 0 && persistedResumeState !== void 0 && (persistedResumeState.kind === `reset` || lacksCompletePersistedKeySet || !retainsTagState && persistedResumeState.requiresTagState !== false);
-      const canUsePersistedResume = shapeOptions.offset === void 0 && shapeOptions.handle === void 0 && persistedResumeState?.kind === `resume` && !hasIncompatiblePersistedResume && // Cached rows do not contain authoritative tag/active-condition state.
-      // Only a complete adapter ledger can justify a persisted cursor.
-      !needsFullSnapshot;
-      const hasExplicitResumeOffset = shapeOptions.offset !== void 0 && shapeOptions.offset !== `-1`;
-      if (!canUsePersistedResume && !hasExplicitResumeOffset) {
-        clearTagTrackingState();
-      }
-      const receivesCompleteRows = shapeOptions.params?.replica === `full`;
-      const requiresKeySetCertification = canUsePersistedResume && certifyResumeSnapshot !== void 0;
-      const requiresCompleteResume = syncMode !== `on-demand` && (canUsePersistedResume || hasExplicitResumeOffset && !receivesCompleteRows);
-      let freshSnapshotPending = (syncMode === `eager` || needsFullSnapshot) && !canUsePersistedResume && !hasExplicitResumeOffset && hydrateBaseline !== void 0;
-      let progressiveReadyGate = null;
-      let streamErrorVersion = 0;
-      const wrappedMarkReady = (isBuffering, expectedErrorVersion = streamErrorVersion) => {
-        if (streamErrorVersion !== expectedErrorVersion) return;
-        if (isBuffering && syncMode === `progressive` && testHooks?.beforeMarkingReady) {
-          progressiveReadyGate = testHooks.beforeMarkingReady();
-          progressiveReadyGate.then(() => {
-            if (streamErrorVersion === expectedErrorVersion) {
-              markReady();
-            }
-          });
-        } else {
-          markReady();
-        }
-      };
-      const abortController = new AbortController();
-      const forwardExternalAbort = () => abortController.abort();
-      if (shapeOptions.signal) {
-        shapeOptions.signal.addEventListener(`abort`, forwardExternalAbort, {
-          once: true
+      void fullSnapshotReady.catch(() => void 0);
+    };
+    resetFullSnapshot();
+    const canUsePersistedResume = shapeOptions.offset === void 0 && shapeOptions.handle === void 0 && persistedResumeState?.kind === `resume` && !hasIncompatiblePersistedResume && // Cached rows do not contain authoritative tag/active-condition state.
+    // Only a complete adapter ledger can justify a persisted cursor.
+    !requiresFreshSourceEvidence;
+    const hasExplicitResumeOffset = shapeOptions.offset !== void 0 && shapeOptions.offset !== `-1`;
+    if (!canUsePersistedResume && !hasExplicitResumeOffset) {
+      clearTagTrackingState();
+    }
+    const receivesCompleteRows = shapeOptions.params?.replica === `full`;
+    const requiresKeySetCertification = canUsePersistedResume && certifyResumeSnapshot !== void 0;
+    const requiresCompleteResume = syncMode !== `on-demand` && (canUsePersistedResume || hasExplicitResumeOffset && !receivesCompleteRows);
+    let freshSnapshotPending = (syncMode === `eager` || requiresFreshSourceEvidence && !scopedRecovery) && !canUsePersistedResume && !hasExplicitResumeOffset && hydrateBaseline !== void 0;
+    let progressiveReadyGate = null;
+    let streamErrorVersion = 0;
+    const wrappedMarkReady = (isBuffering, expectedErrorVersion = streamErrorVersion) => {
+      if (!isActiveLifecycle() || streamErrorVersion !== expectedErrorVersion)
+        return;
+      if (isBuffering && syncMode === `progressive` && testHooks?.beforeMarkingReady) {
+        progressiveReadyGate = testHooks.beforeMarkingReady();
+        progressiveReadyGate.then(() => {
+          if (streamErrorVersion === expectedErrorVersion) {
+            markReady();
+          }
         });
-        if (shapeOptions.signal.aborted) {
-          abortController.abort();
-        }
+      } else {
+        markReady();
       }
-      abortController.signal.addEventListener(`abort`, () => {
-        lifecycle.retire(lifecycleEpoch);
+    };
+    const abortController = new AbortController();
+    let cleanupAbortedStream = false;
+    let initialSyncFailedFinally = false;
+    let firstSnapshotCommitted = false;
+    let sessionCleanedUp = false;
+    const failInitialSync = (cause) => {
+      if (firstSnapshotCommitted) return;
+      initialSyncFailedFinally = true;
+      markError(cause);
+    };
+    const settleFirstSnapshot = (isBuffering, failure) => {
+      if (sessionCleanedUp || collection.status !== `loading`) return;
+      if (failure !== void 0) {
+        initialSyncFailedFinally = true;
+        markError(failure);
+      } else if (isActiveLifecycle()) {
+        wrappedMarkReady(isBuffering, streamErrorVersion);
+      } else markReady();
+    };
+    const forwardExternalAbort = () => {
+      const fails = isActiveLifecycle() && collection.status === `loading`;
+      abortController.abort();
+      if (fails) failInitialSync(new errors.StreamAbortedError(collectionId));
+    };
+    if (shapeOptions.signal) {
+      shapeOptions.signal.addEventListener(`abort`, forwardExternalAbort, {
+        once: true
       });
-      const stream = new client.ShapeStream({
-        ...shapeOptions,
-        // Recovery needs a complete snapshot even for on-demand shapes.
-        // Normal on-demand startup still subscribes to changes only.
-        log: syncMode === `on-demand` && !needsFullSnapshot ? `changes_only` : void 0,
-        // In on-demand mode, we only need the changes from the point of time the collection was created
-        // so we default to `now` when there is no saved offset.
-        offset: shapeOptions.offset ?? (canUsePersistedResume ? persistedResumeState.offset : syncMode === `on-demand` && !needsFullSnapshot ? `now` : void 0),
-        handle: shapeOptions.handle ?? (canUsePersistedResume ? persistedResumeState.handle : void 0),
-        signal: abortController.signal,
-        onError: (errorParams) => {
-          streamErrorVersion++;
-          const initialSyncFailed = collection.status === `loading`;
-          if (initialSyncFailed) {
-            markError(errorParams);
+      if (shapeOptions.signal.aborted) forwardExternalAbort();
+    }
+    abortController.signal.addEventListener(`abort`, () => {
+      rejectFullSnapshot(new errors.StreamAbortedError(collectionId));
+      lifecycle.retire(lifecycleEpoch);
+    });
+    const stream = new client.ShapeStream({
+      ...shapeOptions,
+      // Uncertified on-demand cache rows are quarantined and loaded only
+      // through fresh subset snapshots.
+      log: usesChangesOnlyLog ? `changes_only` : void 0,
+      // In on-demand mode, we only need the changes from the point of time the collection was created
+      // so we default to `now` when there is no saved offset.
+      offset: shapeOptions.offset ?? (canUsePersistedResume ? persistedResumeState.offset : usesChangesOnlyLog ? `now` : void 0),
+      handle: shapeOptions.handle ?? (canUsePersistedResume ? persistedResumeState.handle : void 0),
+      signal: abortController.signal,
+      onError: async (errorParams) => {
+        if (!isActiveLifecycle() || abortController.signal.aborted) return;
+        streamErrorVersion++;
+        const fail = (cause) => {
+          rejectFullSnapshot(cause);
+          if (collection.status === `loading`) failInitialSync(cause);
+        };
+        if (shapeOptions.onError) {
+          let retry;
+          try {
+            retry = await shapeOptions.onError(errorParams);
+          } catch (error) {
+            fail(error);
+            throw error;
           }
-          if (shapeOptions.onError) {
-            return shapeOptions.onError(errorParams);
-          } else {
-            console.error(
-              `An error occurred while syncing collection: ${collection.id}, 
+          if (!retry || typeof retry !== `object`) fail(errorParams);
+          return retry;
+        } else {
+          const initialSyncFailed = collection.status === `loading`;
+          fail(errorParams);
+          console.error(
+            `An error occurred while syncing collection: ${collection.id}, 
 ` + (initialSyncFailed ? `the initial sync has been marked as failed. 
 ` : `the last ready snapshot has been preserved. 
 `) + `You can provide an 'onError' handler on the shapeOptions to handle this error, and this message will not be logged.`,
-              errorParams
-            );
-          }
-          return;
+            errorParams
+          );
         }
-      });
-      let transactionStarted = false;
-      const newTxids = /* @__PURE__ */ new Set();
-      const newSnapshots = [];
-      let hasReceivedUpToDate = syncMode === `progressive` && requiresCompleteResume;
-      let isResettingSnapshot = false;
-      let resetGeneration = 0;
-      const isBufferingInitialSync = () => syncMode === `progressive` && !hasReceivedUpToDate && !isResettingSnapshot;
-      const bufferedMessages = [];
-      const progressiveSnapshotRows = /* @__PURE__ */ new Map();
-      const pendingPresence = /* @__PURE__ */ new Map();
-      let usesBaseline = true;
-      let pendingPresenceRevision = 0;
-      const recordPendingPresence = (rowId, present) => {
-        pendingPresenceRevision++;
-        pendingPresence.set(rowId, present);
-      };
-      const recordPendingTruncate = () => {
-        pendingPresenceRevision++;
-        pendingPresence.clear();
-        progressiveSnapshotRows.clear();
-        usesBaseline = false;
+        return;
+      }
+    });
+    let transactionStarted = false;
+    const newTxids = /* @__PURE__ */ new Set();
+    const newSnapshots = [];
+    let hasReceivedUpToDate = syncMode === `progressive` && requiresCompleteResume;
+    if (hasReceivedUpToDate) resolveFullSnapshot(true);
+    let isResettingSnapshot = false;
+    let resetGeneration = 0;
+    const isBufferingInitialSync = () => syncMode === `progressive` && !hasReceivedUpToDate && !isResettingSnapshot;
+    const bufferedMessages = [];
+    const progressiveSnapshotRows = /* @__PURE__ */ new Map();
+    const pendingPresence = /* @__PURE__ */ new Map();
+    let usesBaseline = true;
+    let pendingPresenceRevision = 0;
+    const recordPendingPresence = (rowId, present) => {
+      pendingPresenceRevision++;
+      pendingPresence.set(rowId, present);
+    };
+    const recordPendingTruncate = () => {
+      pendingPresenceRevision++;
+      pendingPresence.clear();
+      progressiveSnapshotRows.clear();
+      usesBaseline = false;
+    };
+    const commitSourceTransaction = () => {
+      const committedPresenceRevision = pendingPresenceRevision;
+      const applied = commit();
+      if (metadata?.persistence) {
+        const retireAppliedPresence = () => {
+          if (pendingPresenceRevision === committedPresenceRevision) {
+            pendingPresence.clear();
+            usesBaseline = true;
+          }
+        };
+        if (applied === true) retireAppliedPresence();
+        else void applied.then(retireAppliedPresence, () => void 0);
+      }
+      return applied;
+    };
+    const beginSourceTransaction = () => {
+      begin();
+      metadata?.persistence?.reserveCommitTurn();
+    };
+    const syncedKeys = /* @__PURE__ */ new Set();
+    let resumeInvalid = false;
+    const stageResumeMetadata = () => {
+      if (!isActiveLifecycle() || resumeInvalid || scopedRecovery || freshScopedGeneration) {
+        return;
+      }
+      const shapeHandle = stream.shapeHandle;
+      const lastOffset = stream.lastOffset;
+      if (!shapeHandle || lastOffset === `-1`) {
+        return;
+      }
+      const resumeState = {
+        kind: `resume`,
+        offset: lastOffset,
+        handle: shapeHandle,
+        shapeId: shapeIdentity,
+        updatedAt: Date.now(),
+        requiresTagState: tagState.hasTags()
       };
-      const commitSourceTransaction = () => {
-        const committedPresenceRevision = pendingPresenceRevision;
-        const applied = commit();
-        if (metadata?.persistence) {
-          const retireAppliedPresence = () => {
-            if (pendingPresenceRevision === committedPresenceRevision) {
-              pendingPresence.clear();
-              usesBaseline = true;
-            }
-          };
-          if (applied === true) retireAppliedPresence();
-          else void applied.then(retireAppliedPresence, () => void 0);
-        }
-        return applied;
+      lifecycle.resumeState = resumeState;
+      metadata?.collection.set(`electric:resume`, resumeState);
+    };
+    const commitResetResumeMetadataImmediately = (expectInResumeSnapshot = false) => {
+      const resetState = {
+        kind: `reset`,
+        updatedAt: Math.max(
+          Date.now(),
+          persistedResumeState?.updatedAt ?? 0,
+          lifecycle.resumeState?.updatedAt ?? 0
+        ) + 1
       };
-      const beginSourceTransaction = () => {
+      lifecycle.resumeState = resetState;
+      if (metadata) {
         begin();
-        metadata?.persistence?.reserveCommitTurn();
-      };
-      const syncedKeys = /* @__PURE__ */ new Set();
-      let resumeInvalid = false;
-      const stageResumeMetadata = () => {
-        if (!isActiveLifecycle() || resumeInvalid) {
-          return;
+        metadata.collection.set(`electric:resume`, resetState);
+        if (expectInResumeSnapshot) {
+          expectCurrentCommit?.();
         }
-        const shapeHandle = stream.shapeHandle;
-        const lastOffset = stream.lastOffset;
-        if (!shapeHandle || lastOffset === `-1`) {
-          return;
-        }
-        const resumeState = {
-          kind: `resume`,
-          offset: lastOffset,
-          handle: shapeHandle,
-          shapeId: shapeIdentity,
-          updatedAt: Date.now(),
-          requiresTagState: tagState.hasTags()
-        };
-        lifecycle.resumeState = resumeState;
-        metadata?.collection.set(`electric:resume`, resumeState);
-      };
-      const commitResetResumeMetadataImmediately = (expectInResumeSnapshot = false) => {
-        const resetState = {
-          kind: `reset`,
-          updatedAt: Date.now()
-        };
-        lifecycle.resumeState = resetState;
-        if (metadata) {
-          begin();
-          metadata.collection.set(`electric:resume`, resetState);
-          if (expectInResumeSnapshot) {
-            expectCurrentCommit?.();
-          }
-          commit();
-        }
-      };
-      if (hasIncompatiblePersistedResume || needsFullSnapshot && persistedResumeState.kind === `resume`) {
-        commitResetResumeMetadataImmediately(true);
+        commit();
       }
-      const processChangeMessage = (changeMessage) => {
-        if (!client.isChangeMessage(changeMessage)) {
-          return;
-        }
-        const tags = changeMessage.headers.tags;
-        const removedTags = changeMessage.headers.removed_tags;
-        const hasTags = tags || removedTags;
-        const activeConditions = changeMessage.headers.active_conditions;
-        const rowId = collection.getKeyFromItem(changeMessage.value);
-        const operation = changeMessage.headers.operation;
-        const isDelete = operation === `delete`;
-        const isDuplicateInsert = operation === `insert` && syncedKeys.has(rowId);
-        if (isDelete) {
-          syncedKeys.delete(rowId);
-        } else {
-          syncedKeys.add(rowId);
-        }
-        if (isDelete) {
-          clearTagsForRow(rowId);
-        } else if (hasTags) {
-          processTagsForChangeMessage(
-            tags,
-            removedTags,
-            rowId,
-            activeConditions
-          );
+    };
+    if (requiresFreshSourceEvidence && !scopedRecovery && (malformedPersistedResume || hasIncompatiblePersistedResume || persistedResumeState?.kind === `resume`)) {
+      commitResetResumeMetadataImmediately(true);
+    }
+    const scopedResetState = scopedRecovery ? persistedResumeState?.kind === `reset` ? persistedResumeState : lifecycle.resumeState?.kind === `reset` ? lifecycle.resumeState : {
+      kind: `reset`,
+      updatedAt: Date.now()
+    } : void 0;
+    if (scopedResetState) lifecycle.resumeState = scopedResetState;
+    const scopedRecoveryPromise = scopedResetState && persistence?.startScopedRecovery ? persistence.startScopedRecovery({
+      key: `electric:resume`,
+      value: scopedResetState
+    }) : void 0;
+    const processChangeMessage = (changeMessage) => {
+      if (!client.isChangeMessage(changeMessage)) {
+        return;
+      }
+      const tags = changeMessage.headers.tags;
+      const removedTags = changeMessage.headers.removed_tags;
+      const hasTags = tags || removedTags;
+      const activeConditions = changeMessage.headers.active_conditions;
+      const rowId = collection.getKeyFromItem(changeMessage.value);
+      const operation = changeMessage.headers.operation;
+      const isDelete = operation === `delete`;
+      const isDuplicateInsert = operation === `insert` && syncedKeys.has(rowId);
+      if (isDelete) {
+        syncedKeys.delete(rowId);
+      } else {
+        syncedKeys.add(rowId);
+      }
+      if (isDelete) {
+        clearTagsForRow(rowId);
+      } else if (hasTags) {
+        processTagsForChangeMessage(tags, removedTags, rowId, activeConditions);
+      }
+      write({
+        type: isDuplicateInsert ? `update` : operation,
+        value: changeMessage.value,
+        // Include the primary key and relation info in the metadata
+        metadata: {
+          ...changeMessage.headers
         }
-        write({
-          type: isDuplicateInsert ? `update` : operation,
-          value: changeMessage.value,
-          // Include the primary key and relation info in the metadata
-          metadata: {
-            ...changeMessage.headers
-          }
-        });
-      };
-      const loadSubsetDedupe = createLoadSubsetDedupe({
-        stream,
-        syncMode,
-        isBufferingInitialSync,
-        begin,
-        write,
-        commit,
-        getCommitCursor: () => commitSequence,
-        waitForCommitsAfter,
-        recordSnapshotRow: (row, message) => {
-          recordPendingPresence(collection.getKeyFromItem(row), true);
-          progressiveSnapshotRows.set(collection.getKeyFromItem(row), message);
-        },
-        collectionId,
-        // Pass the columnMapper's encode function to transform column names
-        // (e.g., camelCase to snake_case) when compiling SQL for subset queries
-        encodeColumnName: shapeOptions.columnMapper?.encode,
-        // Pass abort signal so requestSnapshot errors can be ignored during cleanup
-        signal: abortController.signal
       });
-      const resumeKeysPromise = requiresCompleteResume || freshSnapshotPending ? hydrateBaseline ? (async () => {
-        await hydrateBaseline();
-        const currentKeySetEvidence = getKeySetEvidence?.();
-        if (canUsePersistedResume && currentKeySetEvidence?.status !== `consistent`) {
-          throw new Error(
-            `Electric persisted resume baseline could not be certified during hydration`
-          );
-        }
-      })() : void 0 : requiresKeySetCertification ? (async () => {
-        await certifyResumeSnapshot();
-        const currentKeySetEvidence = getKeySetEvidence?.();
-        if (currentKeySetEvidence?.status !== `consistent`) {
-          throw new Error(
-            `Electric persisted resume baseline could not be certified`
-          );
-        }
-      })() : void 0;
-      let areResumeKeysReady = !resumeKeysPromise;
-      const pendingResumeBatches = [];
-      let unsubscribeStream = () => {
-      };
-      const invalidateResume = () => {
-        resumeInvalid = true;
-        if (transactionStarted) {
-          const cancellation = new AbortController();
-          cancellation.abort();
-          commit(cancellation.signal);
-          transactionStarted = false;
-        }
-        syncedKeys.clear();
-        newTxids.clear();
-        newSnapshots.length = 0;
-        commitResetResumeMetadataImmediately();
-        streamErrorVersion++;
-        unsubscribeStream();
-        abortController.abort();
-        markError(
-          new Error(
-            `Electric resume state referenced an unseen row; a full snapshot is required`
-          )
+    };
+    const loadSubsetDedupe = createLoadSubsetDedupe({
+      stream,
+      syncMode,
+      isBufferingInitialSync,
+      waitForFullSnapshot: usesFullLog ? () => fullSnapshotReady : void 0,
+      waitForEstablishedSnapshot: () => fullSnapshotReady,
+      begin,
+      write,
+      commit,
+      getCommitCursor: () => commitSequence,
+      waitForCommitsAfter,
+      recordSnapshotRow: (row, message) => {
+        recordPendingPresence(collection.getKeyFromItem(row), true);
+        progressiveSnapshotRows.set(collection.getKeyFromItem(row), message);
+      },
+      collectionId,
+      // Pass the columnMapper's encode function to transform column names
+      // (e.g., camelCase to snake_case) when compiling SQL for subset queries
+      encodeColumnName: shapeOptions.columnMapper?.encode,
+      // Pass abort ownership so cleanup stays quiet without certifying an
+      // externally aborted acquisition as successful.
+      signal: abortController.signal,
+      isCleanupAbort: () => cleanupAbortedStream,
+      beforeSnapshot: scopedRecoveryPromise ? () => scopedRecoveryPromise : void 0
+    });
+    const resumeKeysPromise = scopedRecoveryPromise ?? (requiresCompleteResume || freshSnapshotPending ? hydrateBaseline ? (async () => {
+      await hydrateBaseline();
+      const currentKeySetEvidence = getKeySetEvidence?.();
+      if (canUsePersistedResume && currentKeySetEvidence?.status !== `consistent`) {
+        throw new Error(
+          `Electric persisted resume baseline could not be certified during hydration`
         );
-      };
-      const processMessages = (messages) => {
-        if (!isActiveLifecycle() || resumeInvalid) {
-          return;
+      }
+    })() : void 0 : requiresKeySetCertification ? (async () => {
+      await certifyResumeSnapshot();
+      const currentKeySetEvidence = getKeySetEvidence?.();
+      if (currentKeySetEvidence?.status !== `consistent`) {
+        throw new Error(
+          `Electric persisted resume baseline could not be certified`
+        );
+      }
+    })() : void 0);
+    let areResumeKeysReady = !resumeKeysPromise;
+    const pendingResumeBatches = [];
+    let unsubscribeStream = () => {
+    };
+    const invalidateResume = () => {
+      resumeInvalid = true;
+      if (transactionStarted) {
+        const cancellation = new AbortController();
+        cancellation.abort();
+        commit(cancellation.signal);
+        transactionStarted = false;
+      }
+      syncedKeys.clear();
+      newTxids.clear();
+      newSnapshots.length = 0;
+      commitResetResumeMetadataImmediately();
+      streamErrorVersion++;
+      unsubscribeStream();
+      abortController.abort();
+      markError(
+        new Error(
+          `Electric resume state referenced an unseen row; a full snapshot is required`
+        )
+      );
+    };
+    const processMessages = (messages) => {
+      if (!isActiveLifecycle() || resumeInvalid) {
+        return;
+      }
+      if (freshSnapshotPending) {
+        freshSnapshotPending = false;
+        beginSourceTransaction();
+        transactionStarted = true;
+        truncate();
+        recordPendingTruncate();
+        syncedKeys.clear();
+        clearTagTrackingState();
+        isResettingSnapshot = true;
+        resetGeneration++;
+      }
+      if (!metadata?.persistence && !transactionStarted) {
+        pendingPresence.clear();
+        usesBaseline = true;
+        for (const pending of collection._state.pendingSyncedTransactions) {
+          if (pending.truncate) {
+            pendingPresence.clear();
+            usesBaseline = false;
+          }
+          for (const operation of pending.operations) {
+            pendingPresence.set(operation.key, operation.type !== `delete`);
+          }
         }
-        if (freshSnapshotPending) {
-          freshSnapshotPending = false;
-          beginSourceTransaction();
-          transactionStarted = true;
-          truncate();
-          recordPendingTruncate();
-          syncedKeys.clear();
-          clearTagTrackingState();
-          isResettingSnapshot = true;
-          resetGeneration++;
+        for (const message of bufferedMessages) {
+          if (client.isChangeMessage(message)) {
+            pendingPresence.set(
+              collection.getKeyFromItem(message.value),
+              message.headers.operation !== `delete`
+            );
+          }
         }
-        if (!metadata?.persistence && !transactionStarted) {
-          pendingPresence.clear();
-          usesBaseline = true;
-          for (const pending of collection._state.pendingSyncedTransactions) {
-            if (pending.truncate) {
-              pendingPresence.clear();
-              usesBaseline = false;
-            }
-            for (const operation of pending.operations) {
-              pendingPresence.set(operation.key, operation.type !== `delete`);
+      }
+      let commitPoint = null;
+      lifecycle.beginMatchGeneration(messages);
+      for (const message of messages) {
+        lifecycle.observeMatchMessage(message);
+        if (!isActiveLifecycle()) return;
+        if (hasTxids(message) && (!isBufferingInitialSync() || transactionStarted)) {
+          message.headers.txids?.forEach((txid) => newTxids.add(txid));
+        }
+        if (client.isChangeMessage(message)) {
+          const rowId = collection.getKeyFromItem(message.value);
+          const operation = message.headers.operation;
+          const hasKnownRow = pendingPresence.get(rowId) ?? (usesBaseline && collection._state.syncedData.has(rowId));
+          if (operation === `update` && !hasKnownRow) {
+            if (requiresCompleteResume && !isResettingSnapshot) {
+              invalidateResume();
+              return;
             }
+            if (!receivesCompleteRows) continue;
           }
-          for (const message of bufferedMessages) {
-            if (client.isChangeMessage(message)) {
-              pendingPresence.set(
-                collection.getKeyFromItem(message.value),
-                message.headers.operation !== `delete`
-              );
-            }
+          recordPendingPresence(rowId, operation !== `delete`);
+          if (operation !== `update`) {
+            progressiveSnapshotRows.delete(rowId);
           }
         }
-        let commitPoint = null;
-        lifecycle.beginMatchGeneration(messages);
-        for (const message of messages) {
-          lifecycle.observeMatchMessage(message);
-          if (!isActiveLifecycle()) return;
-          if (hasTxids(message) && (!isBufferingInitialSync() || transactionStarted)) {
-            message.headers.txids?.forEach((txid) => newTxids.add(txid));
+        if (client.isChangeMessage(message)) {
+          const schema = message.headers.schema;
+          if (schema && typeof schema === `string`) {
+            relationSchema = schema;
           }
-          if (client.isChangeMessage(message)) {
-            const rowId = collection.getKeyFromItem(message.value);
-            const operation = message.headers.operation;
-            const hasKnownRow = pendingPresence.get(rowId) ?? (usesBaseline && collection._state.syncedData.has(rowId));
-            if (operation === `update` && !hasKnownRow) {
-              if (requiresCompleteResume && !isResettingSnapshot) {
-                invalidateResume();
-                return;
+          if (isBufferingInitialSync() && !transactionStarted) {
+            if (message.headers.operation === `update`) {
+              const rowId = collection.getKeyFromItem(message.value);
+              const snapshotRow = progressiveSnapshotRows.get(rowId);
+              if (snapshotRow) {
+                bufferedMessages.push(snapshotRow);
+                progressiveSnapshotRows.delete(rowId);
               }
-              if (!receivesCompleteRows) continue;
             }
-            recordPendingPresence(rowId, operation !== `delete`);
-            if (operation !== `update`) {
-              progressiveSnapshotRows.delete(rowId);
+            bufferedMessages.push(message);
+          } else {
+            if (!transactionStarted) {
+              beginSourceTransaction();
+              transactionStarted = true;
             }
+            processChangeMessage(message);
           }
-          if (client.isChangeMessage(message)) {
-            const schema = message.headers.schema;
-            if (schema && typeof schema === `string`) {
-              relationSchema = schema;
-            }
-            if (isBufferingInitialSync() && !transactionStarted) {
-              if (message.headers.operation === `update`) {
-                const rowId = collection.getKeyFromItem(message.value);
-                const snapshotRow = progressiveSnapshotRows.get(rowId);
-                if (snapshotRow) {
-                  bufferedMessages.push(snapshotRow);
-                  progressiveSnapshotRows.delete(rowId);
-                }
+        } else if (isSnapshotEndMessage(message)) {
+          if (!isBufferingInitialSync() || transactionStarted) {
+            newSnapshots.push(parseSnapshotMessage(message));
+          }
+        } else if (isUpToDateMessage(message)) {
+          commitPoint = `up-to-date`;
+        } else if (isSubsetEndMessage(message)) {
+          if (commitPoint !== `up-to-date`) {
+            commitPoint = `subset-end`;
+          }
+        } else if (tagIndex.isMoveOutMessage(message)) {
+          if (isBufferingInitialSync() && !transactionStarted) {
+            bufferedMessages.push(message);
+          } else {
+            transactionStarted = processMoveOutEvent(
+              message.headers.patterns,
+              beginSourceTransaction,
+              write,
+              transactionStarted,
+              (rowId) => {
+                recordPendingPresence(rowId, false);
+                syncedKeys.delete(rowId);
               }
-              bufferedMessages.push(message);
-            } else {
-              if (!transactionStarted) {
-                beginSourceTransaction();
-                transactionStarted = true;
+            );
+          }
+        } else if (tagIndex.isMoveInMessage(message)) {
+          if (isBufferingInitialSync() && !transactionStarted) {
+            bufferedMessages.push(message);
+          } else {
+            processMoveInEvent(message.headers.patterns);
+          }
+        } else if (isMustRefetchMessage(message)) {
+          if (hasReceivedUpToDate) resetFullSnapshot();
+          debug(
+            `${collectionId ? `[${collectionId}] ` : ``}Received must-refetch message, starting transaction with truncate`
+          );
+          commitResetResumeMetadataImmediately();
+          if (!transactionStarted) {
+            beginSourceTransaction();
+            transactionStarted = true;
+          }
+          truncate();
+          clearTagTrackingState();
+          syncedKeys.clear();
+          recordPendingTruncate();
+          isResettingSnapshot = true;
+          resetGeneration++;
+          loadSubsetDedupe?.reset();
+          commitPoint = null;
+          hasReceivedUpToDate = false;
+          bufferedMessages.length = 0;
+          progressiveSnapshotRows.clear();
+        }
+      }
+      if (requiresFreshSourceEvidence && !scopedRecovery && isResettingSnapshot && commitPoint === `subset-end`)
+        return;
+      if (commitPoint !== null) {
+        let applied = true;
+        const wasBufferingInitialSync = isBufferingInitialSync();
+        const finishesReset = isResettingSnapshot && commitPoint === `up-to-date`;
+        const finishingResetGeneration = resetGeneration;
+        if (isBufferingInitialSync() && commitPoint === `up-to-date` && !transactionStarted) {
+          debug(
+            `${collectionId ? `[${collectionId}] ` : ``}Progressive mode: Performing atomic swap with ${bufferedMessages.length} buffered messages`
+          );
+          beginSourceTransaction();
+          truncate();
+          clearTagTrackingState();
+          syncedKeys.clear();
+          for (const bufferedMsg of bufferedMessages) {
+            if (client.isChangeMessage(bufferedMsg)) {
+              processChangeMessage(bufferedMsg);
+              if (hasTxids(bufferedMsg)) {
+                bufferedMsg.headers.txids?.forEach((txid) => newTxids.add(txid));
               }
-              processChangeMessage(message);
-            }
-          } else if (isSnapshotEndMessage(message)) {
-            if (!isBufferingInitialSync() || transactionStarted) {
-              newSnapshots.push(parseSnapshotMessage(message));
-            }
-          } else if (isUpToDateMessage(message)) {
-            commitPoint = `up-to-date`;
-          } else if (isSubsetEndMessage(message)) {
-            if (commitPoint !== `up-to-date`) {
-              commitPoint = `subset-end`;
-            }
-          } else if (tagIndex.isMoveOutMessage(message)) {
-            if (isBufferingInitialSync() && !transactionStarted) {
-              bufferedMessages.push(message);
-            } else {
-              transactionStarted = processMoveOutEvent(
-                message.headers.patterns,
-                beginSourceTransaction,
+            } else if (isSnapshotEndMessage(bufferedMsg)) {
+              newSnapshots.push(parseSnapshotMessage(bufferedMsg));
+            } else if (tagIndex.isMoveOutMessage(bufferedMsg)) {
+              processMoveOutEvent(
+                bufferedMsg.headers.patterns,
+                begin,
                 write,
-                transactionStarted,
+                // The swap already opened a transaction, even though the
+                // normal-stream transactionStarted flag is still false.
+                true,
                 (rowId) => {
                   recordPendingPresence(rowId, false);
                   syncedKeys.delete(rowId);
                 }
               );
+            } else if (tagIndex.isMoveInMessage(bufferedMsg)) {
+              processMoveInEvent(bufferedMsg.headers.patterns);
             }
-          } else if (tagIndex.isMoveInMessage(message)) {
-            if (isBufferingInitialSync() && !transactionStarted) {
-              bufferedMessages.push(message);
-            } else {
-              processMoveInEvent(message.headers.patterns);
-            }
-          } else if (isMustRefetchMessage(message)) {
-            debug(
-              `${collectionId ? `[${collectionId}] ` : ``}Received must-refetch message, starting transaction with truncate`
-            );
-            commitResetResumeMetadataImmediately();
-            if (!transactionStarted) {
-              beginSourceTransaction();
-              transactionStarted = true;
-            }
-            truncate();
-            clearTagTrackingState();
-            syncedKeys.clear();
-            recordPendingTruncate();
-            isResettingSnapshot = true;
-            resetGeneration++;
-            loadSubsetDedupe?.reset();
-            commitPoint = null;
-            hasReceivedUpToDate = false;
-            bufferedMessages.length = 0;
-            progressiveSnapshotRows.clear();
           }
-        }
-        if (needsFullSnapshot && isResettingSnapshot && commitPoint === `subset-end`)
-          return;
-        if (commitPoint !== null) {
-          let applied = true;
-          const wasBufferingInitialSync = isBufferingInitialSync();
-          const finishesReset = isResettingSnapshot && commitPoint === `up-to-date`;
-          const finishingResetGeneration = resetGeneration;
-          if (isBufferingInitialSync() && commitPoint === `up-to-date` && !transactionStarted) {
-            debug(
-              `${collectionId ? `[${collectionId}] ` : ``}Progressive mode: Performing atomic swap with ${bufferedMessages.length} buffered messages`
-            );
-            beginSourceTransaction();
-            truncate();
-            clearTagTrackingState();
-            syncedKeys.clear();
-            for (const bufferedMsg of bufferedMessages) {
-              if (client.isChangeMessage(bufferedMsg)) {
-                processChangeMessage(bufferedMsg);
-                if (hasTxids(bufferedMsg)) {
-                  bufferedMsg.headers.txids?.forEach(
-                    (txid) => newTxids.add(txid)
-                  );
-                }
-              } else if (isSnapshotEndMessage(bufferedMsg)) {
-                newSnapshots.push(parseSnapshotMessage(bufferedMsg));
-              } else if (tagIndex.isMoveOutMessage(bufferedMsg)) {
-                processMoveOutEvent(
-                  bufferedMsg.headers.patterns,
-                  begin,
-                  write,
-                  // The swap already opened a transaction, even though the
-                  // normal-stream transactionStarted flag is still false.
-                  true,
-                  (rowId) => {
-                    recordPendingPresence(rowId, false);
-                    syncedKeys.delete(rowId);
-                  }
-                );
-              } else if (tagIndex.isMoveInMessage(bufferedMsg)) {
-                processMoveInEvent(bufferedMsg.headers.patterns);
-              }
+          stageResumeMetadata();
+          applied = commitSourceTransaction();
+          bufferedMessages.length = 0;
+          progressiveSnapshotRows.clear();
+          debug(
+            `${collectionId ? `[${collectionId}] ` : ``}Progressive mode: Atomic swap complete, now in normal sync mode`
+          );
+        } else {
+          if (transactionStarted) {
+            if (!isResettingSnapshot || finishesReset) {
+              stageResumeMetadata();
             }
+            applied = commitSourceTransaction();
+            transactionStarted = false;
+          } else if (commitPoint === `up-to-date` && metadata) {
+            beginSourceTransaction();
             stageResumeMetadata();
             applied = commitSourceTransaction();
-            bufferedMessages.length = 0;
-            progressiveSnapshotRows.clear();
-            debug(
-              `${collectionId ? `[${collectionId}] ` : ``}Progressive mode: Atomic swap complete, now in normal sync mode`
-            );
-          } else {
-            if (transactionStarted) {
-              if (!isResettingSnapshot || finishesReset) {
-                stageResumeMetadata();
-              }
-              applied = commitSourceTransaction();
-              transactionStarted = false;
-            } else if (commitPoint === `up-to-date` && metadata) {
-              beginSourceTransaction();
-              stageResumeMetadata();
-              applied = commitSourceTransaction();
-            }
           }
-          const readyErrorVersion = streamErrorVersion;
-          const accepted = db.whenSyncAccepted(applied);
-          if (accepted === true) {
-            wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion);
-          } else {
-            void accepted.then(
-              () => wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion),
-              () => void 0
-            );
-          }
-          if (applied !== true) {
-            void applied.then(
-              () => void 0,
-              (error) => {
-                if (!isActiveLifecycle() || abortController.signal.aborted) {
-                  return;
-                }
-                streamErrorVersion++;
-                unsubscribeStream();
-                abortController.abort();
-                if (collection.status !== `error`) markError(error);
-              }
-            );
-          }
-          if (finishesReset) {
-            const finishReset = () => {
-              if (resetGeneration === finishingResetGeneration) {
-                isResettingSnapshot = false;
+        }
+        const readyErrorVersion = streamErrorVersion;
+        const accepted = db.whenSyncAccepted(applied);
+        const firstSnapshot = commitPoint === `up-to-date` && collection.status === `loading`;
+        if (commitPoint === `up-to-date`) resolveFullSnapshot(applied);
+        if (accepted === true) {
+          wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion);
+        } else if (firstSnapshot) {
+          firstSnapshotCommitted = true;
+          void accepted.then(
+            () => settleFirstSnapshot(wasBufferingInitialSync),
+            (error) => settleFirstSnapshot(wasBufferingInitialSync, error)
+          );
+        } else {
+          void accepted.then(
+            () => wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion),
+            () => void 0
+          );
+        }
+        if (applied !== true) {
+          void applied.then(
+            () => void 0,
+            (error) => {
+              if (!isActiveLifecycle() || abortController.signal.aborted) {
+                return;
               }
-            };
-            if (applied === true) {
-              finishReset();
-            } else {
-              void applied.then(finishReset, () => void 0);
+              streamErrorVersion++;
+              unsubscribeStream();
+              abortController.abort();
+              if (collection.status !== `error`) markError(error);
             }
+          );
+        }
+        if (finishesReset) {
+          const finishReset = () => {
+            if (resetGeneration === finishingResetGeneration) {
+              isResettingSnapshot = false;
+            }
+          };
+          if (applied === true) {
+            finishReset();
+          } else {
+            void applied.then(finishReset, () => void 0);
           }
-          if (commitPoint === `up-to-date`) {
-            hasReceivedUpToDate = true;
-          }
-          if (newTxids.size > 0) {
-            debug(
-              `${collectionId ? `[${collectionId}] ` : ``}new txids synced from pg %O`,
-              Array.from(newTxids)
-            );
-          }
-          newSnapshots.forEach(
-            (snapshot) => debug(
-              `${collectionId ? `[${collectionId}] ` : ``}new snapshot synced from pg %o`,
-              snapshot
-            )
+        }
+        if (commitPoint === `up-to-date`) {
+          hasReceivedUpToDate = true;
+        }
+        if (newTxids.size > 0) {
+          debug(
+            `${collectionId ? `[${collectionId}] ` : ``}new txids synced from pg %O`,
+            Array.from(newTxids)
           );
-          lifecycle.publishEvidence(newTxids, newSnapshots);
-          newTxids.clear();
-          newSnapshots.length = 0;
-          lifecycle.commitMatches();
         }
-      };
-      unsubscribeStream = stream.subscribe((messages) => {
+        newSnapshots.forEach(
+          (snapshot) => debug(
+            `${collectionId ? `[${collectionId}] ` : ``}new snapshot synced from pg %o`,
+            snapshot
+          )
+        );
+        lifecycle.publishEvidence(newTxids, newSnapshots);
+        newTxids.clear();
+        newSnapshots.length = 0;
+        lifecycle.commitMatches();
+      }
+    };
+    unsubscribeStream = stream.subscribe(
+      (messages) => {
         if (!areResumeKeysReady) {
           pendingResumeBatches.push([...messages]);
           return;
         }
         processMessages(messages);
-      });
-      if (!areResumeKeysReady && resumeKeysPromise) {
-        void resumeKeysPromise.then(
-          () => {
-            if (abortController.signal.aborted) return;
-            areResumeKeysReady = true;
-            const queuedBatches = pendingResumeBatches.splice(0);
-            queuedBatches.forEach(processMessages);
-          },
-          (error) => {
-            if (abortController.signal.aborted) return;
-            pendingResumeBatches.length = 0;
-            resumeInvalid = true;
-            commitResetResumeMetadataImmediately();
-            streamErrorVersion++;
-            unsubscribeStream();
-            abortController.abort();
-            markError(error);
-          }
-        );
+      },
+      (error) => {
+        rejectFullSnapshot(error);
+        if (isActiveLifecycle() && !abortController.signal.aborted && collection.status === `loading`)
+          failInitialSync(error);
       }
-      return {
-        loadSubset: loadSubsetDedupe?.loadSubset,
-        cleanup: () => {
-          shapeOptions.signal?.removeEventListener(
-            `abort`,
-            forwardExternalAbort
-          );
+    );
+    if (!areResumeKeysReady && resumeKeysPromise) {
+      void resumeKeysPromise.then(
+        () => {
+          if (abortController.signal.aborted) return;
+          areResumeKeysReady = true;
+          const queuedBatches = pendingResumeBatches.splice(0);
+          queuedBatches.forEach(processMessages);
+        },
+        (error) => {
+          if (abortController.signal.aborted) return;
+          pendingResumeBatches.length = 0;
+          resumeInvalid = true;
+          rejectFullSnapshot(error);
+          commitResetResumeMetadataImmediately();
+          streamErrorVersion++;
           unsubscribeStream();
           abortController.abort();
-          pendingResumeBatches.length = 0;
-          loadSubsetDedupe?.reset();
-          lifecycle.retire(lifecycleEpoch);
+          markError(error);
+        }
+      );
+    }
+    return {
+      loadSubset: loadSubsetDedupe?.loadSubset,
+      cleanup: () => {
+        sessionCleanedUp = true;
+        if (!abortController.signal.aborted && !initialSyncFailedFinally)
+          cleanupAbortedStream = true;
+        shapeOptions.signal?.removeEventListener(`abort`, forwardExternalAbort);
+        unsubscribeStream();
+        abortController.abort();
+        if (transactionStarted) {
+          transactionStarted = false;
+          const cancellation = new AbortController();
+          cancellation.abort();
+          const abandoned = commit(cancellation.signal);
+          if (abandoned !== true) void abandoned.catch(() => void 0);
+        }
+        pendingResumeBatches.length = 0;
+        loadSubsetDedupe?.reset();
+        lifecycle.retire(lifecycleEpoch);
+      }
+    };
+  };
+  return {
+    getSyncMetadata: () => ({
+      relation: shapeOptions.params?.table ? [relationSchema || `public`, shapeOptions.params.table] : void 0
+    }),
+    sync: (params) => {
+      if (syncMode !== `on-demand` || !params.metadata?.persistence?.managedCacheGeneration) {
+        return startSession(params);
+      }
+      let session = startSession(params);
+      let retireSession;
+      let retired = new Promise((resolve) => {
+        retireSession = resolve;
+      });
+      let restartInFlight;
+      let restartFailure;
+      let restartSequence = 0;
+      let sessionCleaned = false;
+      let cleanedUp = false;
+      const isCleanedUp = () => cleanedUp;
+      const cleanupCurrentSession = () => {
+        if (sessionCleaned) return Promise.resolve();
+        sessionCleaned = true;
+        try {
+          return Promise.resolve(session.cleanup());
+        } catch (error) {
+          return Promise.reject(error);
+        }
+      };
+      const trackRestart = (work) => {
+        const tracked = work.catch((error) => {
+          restartFailure = { error };
+          throw error;
+        }).finally(() => {
+          if (restartInFlight === tracked) restartInFlight = void 0;
+        });
+        restartInFlight = tracked;
+        return tracked;
+      };
+      const startReplacement = (sequence) => {
+        if (isCleanedUp() || sequence !== restartSequence) return;
+        session = startSession(params, true);
+        sessionCleaned = false;
+        retired = new Promise((resolve) => {
+          retireSession = resolve;
+        });
+      };
+      return {
+        loadSubset: async (demand) => {
+          while (!isCleanedUp()) {
+            if (restartFailure) throw restartFailure.error;
+            if (demand.signal?.aborted) {
+              throw demand.signal.reason ?? new db.LoadSubsetOperationAbortedError();
+            }
+            const current = session;
+            const currentRetired = retired;
+            const result = current.loadSubset?.(demand) ?? true;
+            const outcome = await Promise.race([
+              Promise.resolve(result).then(() => `settled`),
+              currentRetired.then(() => `retired`)
+            ]);
+            if (outcome === `settled`) return;
+            if (restartInFlight) {
+              await waitForDemandOrAbort(restartInFlight, demand.signal);
+            }
+          }
+          if (restartFailure) throw restartFailure.error;
+        },
+        restartAfterScopedRecovery: (cacheRotated) => {
+          if (isCleanedUp()) return Promise.resolve();
+          if (restartFailure) return Promise.reject(restartFailure.error);
+          const sequence = ++restartSequence;
+          retireSession();
+          const oldSessionCleanup = cleanupCurrentSession();
+          if (restartInFlight) {
+            const previousRestart = restartInFlight;
+            return trackRestart(
+              (async () => {
+                await Promise.all([previousRestart, oldSessionCleanup]);
+                await cacheRotated;
+                startReplacement(sequence);
+              })()
+            );
+          }
+          return trackRestart(
+            (async () => {
+              await oldSessionCleanup;
+              await cacheRotated;
+              startReplacement(sequence);
+            })()
+          );
+        },
+        cleanup: async () => {
+          cleanedUp = true;
+          retireSession();
+          try {
+            await restartInFlight;
+          } catch (error) {
+            if (!(error instanceof db.SyncTransactionAbortedError)) throw error;
+          }
+          await cleanupCurrentSession();
         }
       };
     }