@tanstack/electric-db-collection 0.4.8 → 0.5.1

package/dist/esm/electric.js

@@ -1,14 +1,26 @@
-import { ShapeStream, isChangeMessage, isVisibleInSnapshot, isControlMessage } from "@electric-sql/client";
+import { isVisibleInSnapshot, isChangeMessage, ShapeStream, isControlMessage } from "@electric-sql/client";
 import { isChangeMessage as isChangeMessage2, isControlMessage as isControlMessage2 } from "@electric-sql/client";
-import { Store } from "@tanstack/store";
 import DebugModule from "debug";
-import { withCollectionConfigFactory, DeduplicatedLoadSubset, and, LoadSubsetOperationAbortedError } from "@tanstack/db";
+import { withCollectionSyncConfigFactory, withCollectionConfigFactory, validateSyncPersistenceCapability, warnOnce, withCollectionSyncConfigCleanup, DeduplicatedLoadSubset, and, LoadSubsetOperationAbortedError } from "@tanstack/db";
 import { StreamAbortedError, ExpectedNumberInAwaitTxIdError, TimeoutWaitingForTxIdError, TimeoutWaitingForMatchError } from "./errors.js";
 import { compileSQL } from "./sql-compiler.js";
 import { isMoveOutMessage, isMoveInMessage, deriveDisjunctPositions, getTagLength, addTagToIndex, parseTag, removeTagFromIndex, findRowsMatchingPattern, rowVisible, tagMatchesPattern } from "./tag-index.js";
 const debug = DebugModule.debug(`ts/db:electric`);
-const FORCE_DISCONNECT_AND_REFRESH_TIMEOUT_MS = 250;
 const ELECTRIC_TEST_HOOKS = /* @__PURE__ */ Symbol(`electricTestHooks`);
+function exportElectricSyncMeta(evidence) {
+  const resume = evidence.hydratedResumeState;
+  return {
+    version: 1,
+    ...resume ? { resume } : {},
+    seenTxids: Array.from(evidence.seenTxids).sort((a, b) => a - b)
+  };
+}
+function importElectricSyncMeta(evidence, meta) {
+  const parsed = parseElectricSyncMeta(meta);
+  if (!parsed) return;
+  evidence.hydratedResumeState = parsed.resume;
+  evidence.seenTxids = new Set(parsed.seenTxids);
+}
 function parseElectricResumeState(value) {
   if (!value || typeof value !== `object`) {
     return void 0;
@@ -20,7 +32,10 @@ function parseElectricResumeState(value) {
       offset: record.offset,
       handle: record.handle,
       shapeId: record.shapeId,
-      updatedAt: record.updatedAt
+      updatedAt: record.updatedAt,
+      ...typeof record.requiresTagState === `boolean` && {
+        requiresTagState: record.requiresTagState
+      }
     };
   }
   if (record.kind === `reset` && typeof record.updatedAt === `number` && Number.isFinite(record.updatedAt)) {
@@ -75,7 +90,10 @@ function mergeElectricSyncMeta(current, incoming) {
 function getNewestElectricResumeState(current, incoming) {
   if (!current) return incoming;
   if (!incoming) return current;
-  return incoming.updatedAt >= current.updatedAt ? incoming : current;
+  if (incoming.updatedAt > current.updatedAt) return incoming;
+  if (incoming.updatedAt < current.updatedAt) return current;
+  const isSameState = current.kind === incoming.kind && (current.kind === `reset` || incoming.kind === `resume` && current.offset === incoming.offset && current.handle === incoming.handle && current.shapeId === incoming.shapeId);
+  return isSameState ? current : { kind: `reset`, updatedAt: current.updatedAt };
 }
 function isUpToDateMessage(message) {
   return isControlMessage(message) && message.headers.control === `up-to-date`;
@@ -139,6 +157,7 @@ function createLoadSubsetDedupe({
   commit,
   getCommitCursor,
   waitForCommitsAfter,
+  recordSnapshotRow,
   collectionId,
   encodeColumnName,
   signal
@@ -181,7 +200,9 @@ function createLoadSubsetDedupe({
               metadata: { ...row.headers }
             });
           }
-          await commit(opts.signal);
+          const applied = commit(opts.signal);
+          for (const row of rows) recordSnapshotRow?.(row.value, row);
+          if (applied !== true) await applied;
           debug(`${logPrefix}Applied snapshot with ${rows.length} rows`);
         }
       } catch (error) {
@@ -197,47 +218,6 @@ function createLoadSubsetDedupe({
       return;
     }
     const { cursor, where, orderBy, limit } = opts;
-    if (stream.isUpToDate) {
-      let timeoutId;
-      const abortSignals = [signal, opts.signal].filter(
-        (candidate) => candidate !== void 0
-      );
-      let rejectAbort = () => {
-      };
-      const aborted = new Promise((_resolve, reject) => {
-        rejectAbort = reject;
-      });
-      const abort = (event) => rejectAbort(abortReason(event.currentTarget));
-      for (const abortSignal of abortSignals) {
-        abortSignal.addEventListener(`abort`, abort, { once: true });
-      }
-      try {
-        await Promise.race([
-          stream.forceDisconnectAndRefresh(),
-          new Promise((resolve) => {
-            timeoutId = setTimeout(
-              resolve,
-              FORCE_DISCONNECT_AND_REFRESH_TIMEOUT_MS
-            );
-          }),
-          aborted
-        ]);
-      } catch (error) {
-        if (signal.aborted || opts.signal?.aborted) throw error;
-        if (handleSnapshotError(error, `forceDisconnectAndRefresh`)) {
-          return;
-        }
-        debug(
-          `${logPrefix}forceDisconnectAndRefresh failed, proceeding to requestSnapshot: %o`,
-          error
-        );
-      } finally {
-        clearTimeout(timeoutId);
-        for (const abortSignal of abortSignals) {
-          abortSignal.removeEventListener(`abort`, abort);
-        }
-      }
-    }
     throwIfAborted();
     try {
       if (cursor) {
@@ -278,204 +258,245 @@ function createLoadSubsetDedupe({
   };
   return new DeduplicatedLoadSubset({ loadSubset });
 }
-function electricCollectionOptions(config) {
-  const seenTxids = new Store(/* @__PURE__ */ new Set([]));
-  const seenSnapshots = new Store([]);
-  const hydratedResumeState = new Store(
-    void 0
-  );
-  const internalSyncMode = config.syncMode ?? `eager`;
-  const finalSyncMode = internalSyncMode === `progressive` ? `on-demand` : internalSyncMode;
-  const pendingMatches = new Store(/* @__PURE__ */ new Map());
-  const currentBatchMessages = new Store([]);
-  const batchCommitted = new Store(false);
-  const removePendingMatches = (matchIds) => {
-    if (matchIds.length > 0) {
-      pendingMatches.setState((current) => {
-        const newMatches = new Map(current);
-        matchIds.forEach((id) => newMatches.delete(id));
-        return newMatches;
-      });
+class ElectricLifecycle {
+  constructor(collectionId) {
+    this.collectionId = collectionId;
+    this.evidence = {
+      seenTxids: /* @__PURE__ */ new Set(),
+      seenSnapshots: []
+    };
+    this.pendingMatches = /* @__PURE__ */ new Map();
+    this.pendingTxidWaits = /* @__PURE__ */ new Map();
+    this.matchBuffer = {
+      committedMessages: [],
+      pendingMessages: []
+    };
+    this.nextWaiterId = 0;
+    this.epoch = 0;
+    this.active = false;
+    this.utils = {
+      awaitTxId: (txId, timeout) => this.awaitTxId(txId, timeout),
+      awaitMatch: (matchFn, timeout) => this.awaitMatch(matchFn, timeout)
+    };
+  }
+  start() {
+    if (this.active) this.retire();
+    this.active = true;
+    this.epoch++;
+    this.matchBuffer = { committedMessages: [], pendingMessages: [] };
+    return this.epoch;
+  }
+  isActive(epoch) {
+    return this.active && this.epoch === epoch;
+  }
+  retire(epoch) {
+    if (epoch !== void 0 && !this.isActive(epoch)) return;
+    this.active = false;
+    this.epoch++;
+    for (const match of this.pendingMatches.values()) {
+      clearTimeout(match.timeoutId);
+      match.reject(new StreamAbortedError(this.collectionId));
     }
-  };
-  const resolveMatchedPendingMatches = () => {
-    const matchesToResolve = [];
-    pendingMatches.state.forEach((match, matchId) => {
-      if (match.matched) {
-        clearTimeout(match.timeoutId);
-        match.resolve(true);
-        matchesToResolve.push(matchId);
-        debug(
-          `${config.id ? `[${config.id}] ` : ``}awaitMatch resolved on up-to-date for match %s`,
-          matchId
-        );
-      }
-    });
-    removePendingMatches(matchesToResolve);
-  };
-  const sync = createElectricSync(config.shapeOptions, {
-    seenTxids,
-    seenSnapshots,
-    hydratedResumeState,
-    syncMode: internalSyncMode,
-    pendingMatches,
-    currentBatchMessages,
-    batchCommitted,
-    removePendingMatches,
-    resolveMatchedPendingMatches,
-    collectionId: config.id,
-    testHooks: config[ELECTRIC_TEST_HOOKS]
-  });
-  const awaitTxId = async (txId, timeout = 5e3) => {
+    this.pendingMatches.clear();
+    for (const waiter of this.pendingTxidWaits.values()) {
+      clearTimeout(waiter.timeoutId);
+      waiter.reject(new StreamAbortedError(this.collectionId));
+    }
+    this.pendingTxidWaits.clear();
+    this.matchBuffer = { committedMessages: [], pendingMessages: [] };
+    this.evidence.hydratedResumeState = void 0;
+  }
+  exportMeta() {
+    return exportElectricSyncMeta(this.evidence);
+  }
+  importMeta(meta) {
+    importElectricSyncMeta(this.evidence, meta);
+    this.resolveTxidWaiters();
+  }
+  get resumeState() {
+    return this.evidence.hydratedResumeState;
+  }
+  set resumeState(value) {
+    this.evidence.hydratedResumeState = value;
+  }
+  publishEvidence(txids, snapshots) {
+    txids.forEach((txid) => this.evidence.seenTxids.add(txid));
+    this.evidence.seenSnapshots.push(...snapshots);
+    this.resolveTxidWaiters();
+  }
+  hasTxid(txId) {
+    return this.evidence.seenTxids.has(txId) || this.evidence.seenSnapshots.some(
+      (snapshot) => isVisibleInSnapshot(txId, snapshot)
+    );
+  }
+  resolveTxidWaiters() {
+    for (const [waitId, waiter] of this.pendingTxidWaits) {
+      if (!this.hasTxid(waiter.txId)) continue;
+      clearTimeout(waiter.timeoutId);
+      this.pendingTxidWaits.delete(waitId);
+      waiter.resolve(true);
+    }
+  }
+  async awaitTxId(txId, timeout = 15e3) {
     debug(
-      `${config.id ? `[${config.id}] ` : ``}awaitTxId called with txid %d`,
+      `${this.collectionId ? `[${this.collectionId}] ` : ``}awaitTxId called with txid %d`,
       txId
     );
     if (typeof txId !== `number`) {
-      throw new ExpectedNumberInAwaitTxIdError(typeof txId, config.id);
+      throw new ExpectedNumberInAwaitTxIdError(typeof txId, this.collectionId);
     }
-    const hasTxid = seenTxids.state.has(txId);
-    if (hasTxid) return true;
-    const hasSnapshot = seenSnapshots.state.some(
-      (snapshot) => isVisibleInSnapshot(txId, snapshot)
-    );
-    if (hasSnapshot) return true;
+    if (this.hasTxid(txId)) return true;
     return new Promise((resolve, reject) => {
-      const cleanup = () => {
-        clearTimeout(timeoutId);
-        subSeenTxids.unsubscribe();
-        subSeenSnapshots.unsubscribe();
-      };
+      const waitId = this.nextWaiterId++;
       const timeoutId = setTimeout(() => {
-        cleanup();
-        reject(new TimeoutWaitingForTxIdError(txId, config.id));
+        this.pendingTxidWaits.delete(waitId);
+        reject(new TimeoutWaitingForTxIdError(txId, this.collectionId));
       }, timeout);
-      const subSeenTxids = seenTxids.subscribe(() => {
-        if (seenTxids.state.has(txId)) {
-          debug(
-            `${config.id ? `[${config.id}] ` : ``}awaitTxId found match for txid %o`,
-            txId
-          );
-          cleanup();
-          resolve(true);
-        }
-      });
-      const subSeenSnapshots = seenSnapshots.subscribe(() => {
-        const visibleSnapshot = seenSnapshots.state.find(
-          (snapshot) => isVisibleInSnapshot(txId, snapshot)
-        );
-        if (visibleSnapshot) {
-          debug(
-            `${config.id ? `[${config.id}] ` : ``}awaitTxId found match for txid %o in snapshot %o`,
-            txId,
-            visibleSnapshot
-          );
-          cleanup();
-          resolve(true);
-        }
+      this.pendingTxidWaits.set(waitId, {
+        txId,
+        resolve,
+        reject,
+        timeoutId
       });
     });
-  };
-  const awaitMatch = async (matchFn, timeout = 3e3) => {
+  }
+  async awaitMatch(matchFn, timeout = 15e3) {
     debug(
-      `${config.id ? `[${config.id}] ` : ``}awaitMatch called with custom function`
+      `${this.collectionId ? `[${this.collectionId}] ` : ``}awaitMatch called with custom function`
     );
+    for (const message of this.matchBuffer.committedMessages) {
+      if (!matchFn(message)) continue;
+      return true;
+    }
+    for (const message of this.matchBuffer.pendingMessages) {
+      if (matchFn(message)) return this.registerMatch(matchFn, timeout, true);
+    }
+    return this.registerMatch(matchFn, timeout, false);
+  }
+  registerMatch(matchFn, timeout, matched) {
     return new Promise((resolve, reject) => {
-      const matchId = Math.random().toString(36);
-      const cleanupMatch = () => {
-        pendingMatches.setState((current) => {
-          const newMatches = new Map(current);
-          newMatches.delete(matchId);
-          return newMatches;
-        });
-      };
-      const onTimeout = () => {
-        cleanupMatch();
-        reject(new TimeoutWaitingForMatchError(config.id));
-      };
-      const timeoutId = setTimeout(onTimeout, timeout);
-      const checkMatch = (message) => {
-        if (matchFn(message)) {
-          debug(
-            `${config.id ? `[${config.id}] ` : ``}awaitMatch found matching message, waiting for up-to-date`
-          );
-          pendingMatches.setState((current) => {
-            const newMatches = new Map(current);
-            const existing = newMatches.get(matchId);
-            if (existing) {
-              newMatches.set(matchId, { ...existing, matched: true });
-            }
-            return newMatches;
-          });
-          return true;
-        }
-        return false;
-      };
-      for (const message of currentBatchMessages.state) {
-        if (matchFn(message)) {
-          if (batchCommitted.state) {
-            debug(
-              `${config.id ? `[${config.id}] ` : ``}awaitMatch found immediate match in committed batch, resolving immediately`
-            );
-            clearTimeout(timeoutId);
-            resolve(true);
-            return;
-          }
-          debug(
-            `${config.id ? `[${config.id}] ` : ``}awaitMatch found immediate match in current batch, waiting for up-to-date`
-          );
-          pendingMatches.setState((current) => {
-            const newMatches = new Map(current);
-            newMatches.set(matchId, {
-              matchFn: checkMatch,
-              resolve,
-              reject,
-              timeoutId,
-              matched: true
-              // Already matched, will resolve on up-to-date
-            });
-            return newMatches;
-          });
-          return;
-        }
-      }
-      pendingMatches.setState((current) => {
-        const newMatches = new Map(current);
-        newMatches.set(matchId, {
-          matchFn: checkMatch,
-          resolve,
-          reject,
-          timeoutId,
-          matched: false
-        });
-        return newMatches;
+      const matchId = this.nextWaiterId++;
+      const timeoutId = setTimeout(() => {
+        this.pendingMatches.delete(matchId);
+        reject(new TimeoutWaitingForMatchError(this.collectionId));
+      }, timeout);
+      this.pendingMatches.set(matchId, {
+        matchFn,
+        resolve,
+        reject,
+        timeoutId,
+        matched
       });
     });
-  };
-  const processMatchingStrategy = async (result) => {
-    if (result && `txid` in result) {
-      const timeout = result.timeout;
-      if (Array.isArray(result.txid)) {
-        await Promise.all(result.txid.map((txid) => awaitTxId(txid, timeout)));
+  }
+  beginMatchGeneration(messages) {
+    if (!messages.some(isMustRefetchMessage)) return;
+    this.matchBuffer = { committedMessages: [], pendingMessages: [] };
+    for (const match of this.pendingMatches.values()) match.matched = false;
+  }
+  observeMatchMessage(message) {
+    if (isChangeMessage(message) || isMoveOutMessage(message) || isMoveInMessage(message)) {
+      this.matchBuffer.pendingMessages.push(message);
+      let overflow = this.matchBuffer.committedMessages.length + this.matchBuffer.pendingMessages.length - 1e3;
+      if (overflow > 0) {
+        const committedOverflow = Math.min(
+          overflow,
+          this.matchBuffer.committedMessages.length
+        );
+        this.matchBuffer.committedMessages.splice(0, committedOverflow);
+        overflow -= committedOverflow;
+        if (overflow > 0) {
+          this.matchBuffer.pendingMessages.splice(0, overflow);
+        }
+      }
+    }
+    const epoch = this.epoch;
+    for (const [matchId, match] of this.pendingMatches) {
+      if (match.matched) continue;
+      try {
+        match.matched = match.matchFn(message);
+      } catch (error) {
+        clearTimeout(match.timeoutId);
+        this.pendingMatches.delete(matchId);
+        match.reject(error instanceof Error ? error : new Error(String(error)));
+      }
+      if (!this.isActive(epoch)) return;
+    }
+  }
+  commitMatches() {
+    this.matchBuffer.committedMessages.push(...this.matchBuffer.pendingMessages);
+    this.matchBuffer.pendingMessages = [];
+    if (this.matchBuffer.committedMessages.length > 1e3) {
+      this.matchBuffer.committedMessages.splice(
+        0,
+        this.matchBuffer.committedMessages.length - 1e3
+      );
+    }
+    for (const [matchId, match] of this.pendingMatches) {
+      if (!match.matched) continue;
+      clearTimeout(match.timeoutId);
+      this.pendingMatches.delete(matchId);
+      match.resolve(true);
+    }
+  }
+}
+function electricCollectionOptions(config) {
+  let descriptorLifecycle = new ElectricLifecycle(config.id);
+  let utilityLifecycle = descriptorLifecycle;
+  const internalSyncMode = config.syncMode ?? `eager`;
+  const finalSyncMode = internalSyncMode === `progressive` ? `on-demand` : internalSyncMode;
+  const boundLifecycles = /* @__PURE__ */ new WeakMap();
+  const awaitTxId = (txId, timeout) => utilityLifecycle.utils.awaitTxId(txId, timeout);
+  const awaitMatch = (matchFn, timeout) => utilityLifecycle.utils.awaitMatch(matchFn, timeout);
+  const createSync = () => createElectricSync(config.shapeOptions, {
+    getLifecycle: (collection) => boundLifecycles.get(collection) ?? descriptorLifecycle,
+    syncMode: internalSyncMode,
+    collectionId: config.id,
+    testHooks: config[ELECTRIC_TEST_HOOKS]
+  });
+  const sync = createSync();
+  const processMatchingStrategy = async (result, waitForTxId) => {
+    const canHaveProperties = typeof result === `object` && result !== null || typeof result === `function`;
+    if (canHaveProperties && `txid` in result) {
+      const strategy = result;
+      warnOnce(
+        "electric-collection-txid-return",
+        "[TanStack DB] DEPRECATED: Returning { txid } from mutation handlers is deprecated and will be removed in v1.0. Use `await collection.utils.awaitTxId(txid)` instead of returning { txid }. See migration guide: https://tanstack.com/db/latest/docs/collections/electric-collection#persistence-handlers--synchronization"
+      );
+      const timeout = strategy.timeout;
+      if (Array.isArray(strategy.txid)) {
+        await Promise.all(
+          strategy.txid.map((txid) => waitForTxId(txid, timeout))
+        );
       } else {
-        await awaitTxId(result.txid, timeout);
+        await waitForTxId(strategy.txid, timeout);
       }
     }
   };
+  const getMutationAwaitTxId = (params) => {
+    const collection = params.collection;
+    return collection?.utils?.awaitTxId ?? awaitTxId;
+  };
   const wrappedOnInsert = config.onInsert ? async (params) => {
     const handlerResult = await config.onInsert(params);
-    await processMatchingStrategy(handlerResult);
-    return handlerResult;
+    await processMatchingStrategy(
+      handlerResult,
+      getMutationAwaitTxId(params)
+    );
   } : void 0;
   const wrappedOnUpdate = config.onUpdate ? async (params) => {
     const handlerResult = await config.onUpdate(params);
-    await processMatchingStrategy(handlerResult);
-    return handlerResult;
+    await processMatchingStrategy(
+      handlerResult,
+      getMutationAwaitTxId(params)
+    );
   } : void 0;
   const wrappedOnDelete = config.onDelete ? async (params) => {
     const handlerResult = await config.onDelete(params);
-    await processMatchingStrategy(handlerResult);
-    return handlerResult;
+    await processMatchingStrategy(
+      handlerResult,
+      getMutationAwaitTxId(params)
+    );
   } : void 0;
   const {
     shapeOptions: _shapeOptions,
@@ -484,236 +505,274 @@ function electricCollectionOptions(config) {
     onDelete: _onDelete,
     ...restConfig
   } = config;
-  const options = {
-    ...restConfig,
-    syncMode: finalSyncMode,
-    sync: {
-      ...sync,
-      exportSyncMeta: () => ({
-        version: 1,
-        ...hydratedResumeState.state ? { resume: hydratedResumeState.state } : {},
-        seenTxids: Array.from(seenTxids.state).sort((a, b) => a - b)
-      }),
-      importSyncMeta: (meta) => {
-        const parsed = parseElectricSyncMeta(meta);
-        if (!parsed) {
-          return;
+  const utilityTemplate = {
+    awaitTxId,
+    awaitMatch
+  };
+  const consumeDescriptorLifecycle = () => {
+    const lifecycle = descriptorLifecycle;
+    descriptorLifecycle = new ElectricLifecycle(config.id);
+    utilityLifecycle = lifecycle;
+    return lifecycle;
+  };
+  const createBoundSync = (source, utilities) => {
+    const lifecycle = consumeDescriptorLifecycle();
+    let collectionKey;
+    Object.assign(utilities, lifecycle.utils);
+    const boundSync = {
+      ...source,
+      sync: (params) => {
+        if (!boundLifecycles.has(params.collection)) {
+          collectionKey = params.collection;
+          boundLifecycles.set(params.collection, lifecycle);
         }
-        hydratedResumeState.setState(() => parsed.resume);
-        seenTxids.setState(() => new Set(parsed.seenTxids));
+        return source.sync(params);
       },
+      exportSyncMeta: () => lifecycle.exportMeta(),
+      importSyncMeta: (meta) => lifecycle.importMeta(meta),
+      mergeSyncMeta: mergeElectricSyncMeta
+    };
+    return withCollectionSyncConfigCleanup(boundSync, () => {
+      lifecycle.retire();
+      if (collectionKey) boundLifecycles.delete(collectionKey);
+    });
+  };
+  const syncTemplate = withCollectionSyncConfigFactory(
+    {
+      ...sync,
+      exportSyncMeta: () => descriptorLifecycle.exportMeta(),
+      importSyncMeta: (meta) => descriptorLifecycle.importMeta(meta),
       mergeSyncMeta: mergeElectricSyncMeta
     },
+    createBoundSync
+  );
+  const options = {
+    ...restConfig,
+    syncMode: finalSyncMode,
+    sync: syncTemplate,
     onInsert: wrappedOnInsert,
     onUpdate: wrappedOnUpdate,
     onDelete: wrappedOnDelete,
-    utils: {
-      awaitTxId,
-      awaitMatch
-    }
+    utils: utilityTemplate
   };
+  Object.defineProperty(options, `utils`, {
+    enumerable: true,
+    get: () => ({ ...utilityTemplate })
+  });
   return withCollectionConfigFactory(
     options,
     () => electricCollectionOptions(config)
   );
 }
 function createElectricSync(shapeOptions, options) {
-  const {
-    seenTxids,
-    seenSnapshots,
-    hydratedResumeState,
-    syncMode,
-    pendingMatches,
-    currentBatchMessages,
-    batchCommitted,
-    removePendingMatches,
-    resolveMatchedPendingMatches,
-    collectionId,
-    testHooks
-  } = options;
-  const MAX_BATCH_MESSAGES = 1e3;
-  const relationSchema = new Store(void 0);
-  const tagCache = /* @__PURE__ */ new Map();
-  const parseTag$1 = (tag) => {
-    const cachedTag = tagCache.get(tag);
-    if (cachedTag) {
-      return cachedTag;
-    }
-    const parsedTag = parseTag(tag);
-    tagCache.set(tag, parsedTag);
-    return parsedTag;
-  };
-  const rowTagSets = /* @__PURE__ */ new Map();
-  const tagIndex = [];
-  let tagLength = void 0;
-  const rowActiveConditions = /* @__PURE__ */ new Map();
-  let disjunctPositions = void 0;
-  const initializeTagIndex = (length) => {
-    if (tagIndex.length < length) {
-      for (let i = tagIndex.length; i < length; i++) {
-        tagIndex[i] = /* @__PURE__ */ new Map();
+  const { getLifecycle, syncMode, collectionId, testHooks } = options;
+  let relationSchema;
+  const createTagState = () => {
+    const tagCache = /* @__PURE__ */ new Map();
+    const parseTag$1 = (tag) => {
+      const cachedTag = tagCache.get(tag);
+      if (cachedTag) {
+        return cachedTag;
       }
-    }
-  };
-  const addTagsToRow = (tags, rowId, rowTagSet) => {
-    for (const tag of tags) {
-      const parsedTag = parseTag$1(tag);
-      if (tagLength === void 0) {
-        tagLength = getTagLength(parsedTag);
-        initializeTagIndex(tagLength);
+      const parsedTag = parseTag(tag);
+      tagCache.set(tag, parsedTag);
+      return parsedTag;
+    };
+    const rowTagSets = /* @__PURE__ */ new Map();
+    const tagIndex = [];
+    let tagLength = void 0;
+    const rowActiveConditions = /* @__PURE__ */ new Map();
+    let disjunctPositions = void 0;
+    const initializeTagIndex = (length) => {
+      if (tagIndex.length < length) {
+        for (let i = tagIndex.length; i < length; i++) {
+          tagIndex[i] = /* @__PURE__ */ new Map();
+        }
       }
-      const currentTagLength = getTagLength(parsedTag);
-      if (currentTagLength !== tagLength) {
-        debug(
-          `${collectionId ? `[${collectionId}] ` : ``}Tag length mismatch: expected ${tagLength}, got ${currentTagLength}`
-        );
-        continue;
+    };
+    const addTagsToRow = (tags, rowId, rowTagSet) => {
+      for (const tag of tags) {
+        const parsedTag = parseTag$1(tag);
+        if (tagLength === void 0) {
+          tagLength = getTagLength(parsedTag);
+          initializeTagIndex(tagLength);
+        }
+        const currentTagLength = getTagLength(parsedTag);
+        if (currentTagLength !== tagLength) {
+          debug(
+            `${collectionId ? `[${collectionId}] ` : ``}Tag length mismatch: expected ${tagLength}, got ${currentTagLength}`
+          );
+          continue;
+        }
+        rowTagSet.add(tag);
+        addTagToIndex(parsedTag, rowId, tagIndex, tagLength);
       }
-      rowTagSet.add(tag);
-      addTagToIndex(parsedTag, rowId, tagIndex, tagLength);
-    }
-  };
-  const removeTagsFromRow = (removedTags, rowId, rowTagSet) => {
-    if (tagLength === void 0) {
-      return;
-    }
-    for (const tag of removedTags) {
-      const parsedTag = parseTag$1(tag);
-      rowTagSet.delete(tag);
-      removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength);
-      tagCache.delete(tag);
-    }
-  };
-  const processTagsForChangeMessage = (tags, removedTags, rowId, activeConditions) => {
-    if (!rowTagSets.has(rowId)) {
-      rowTagSets.set(rowId, /* @__PURE__ */ new Set());
-    }
-    const rowTagSet = rowTagSets.get(rowId);
-    if (tags) {
-      addTagsToRow(tags, rowId, rowTagSet);
-      if (disjunctPositions === void 0) {
-        const parsedTags = tags.map(parseTag$1);
-        disjunctPositions = deriveDisjunctPositions(parsedTags);
+    };
+    const removeTagsFromRow = (removedTags, rowId, rowTagSet) => {
+      if (tagLength === void 0) {
+        return;
       }
-    }
-    if (removedTags) {
-      removeTagsFromRow(removedTags, rowId, rowTagSet);
-    }
-    if (activeConditions && activeConditions.length > 0) {
-      rowActiveConditions.set(rowId, [...activeConditions]);
-    }
-    return rowTagSet;
-  };
-  const clearTagTrackingState = () => {
-    rowTagSets.clear();
-    tagIndex.length = 0;
-    tagLength = void 0;
-    rowActiveConditions.clear();
-    disjunctPositions = void 0;
-  };
-  const clearTagsForRow = (rowId) => {
-    if (tagLength === void 0) {
-      return;
-    }
-    const rowTagSet = rowTagSets.get(rowId);
-    if (!rowTagSet) {
-      return;
-    }
-    for (const tag of rowTagSet) {
-      const parsedTag = parseTag$1(tag);
-      const currentTagLength = getTagLength(parsedTag);
-      if (currentTagLength === tagLength) {
+      for (const tag of removedTags) {
+        const parsedTag = parseTag$1(tag);
+        rowTagSet.delete(tag);
         removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength);
+        tagCache.delete(tag);
       }
-      tagCache.delete(tag);
-    }
-    rowTagSets.delete(rowId);
-    rowActiveConditions.delete(rowId);
-  };
-  const removeMatchingTagsFromRow = (rowId, pattern) => {
-    const rowTagSet = rowTagSets.get(rowId);
-    if (!rowTagSet) {
-      return false;
-    }
-    const activeConditions = rowActiveConditions.get(rowId);
-    if (activeConditions && disjunctPositions) {
-      activeConditions[pattern.pos] = false;
-      if (!rowVisible(activeConditions, disjunctPositions)) {
-        for (const tag of rowTagSet) {
-          const parsedTag = parseTag$1(tag);
+    };
+    const processTagsForChangeMessage = (tags, removedTags, rowId, activeConditions) => {
+      if (!rowTagSets.has(rowId)) {
+        rowTagSets.set(rowId, /* @__PURE__ */ new Set());
+      }
+      const rowTagSet = rowTagSets.get(rowId);
+      if (tags) {
+        addTagsToRow(tags, rowId, rowTagSet);
+        if (disjunctPositions === void 0) {
+          const parsedTags = tags.map(parseTag$1);
+          disjunctPositions = deriveDisjunctPositions(parsedTags);
+        }
+      }
+      if (removedTags) {
+        removeTagsFromRow(removedTags, rowId, rowTagSet);
+      }
+      if (activeConditions && activeConditions.length > 0) {
+        rowActiveConditions.set(rowId, [...activeConditions]);
+      }
+      return rowTagSet;
+    };
+    const clearTagTrackingState = () => {
+      rowTagSets.clear();
+      tagIndex.length = 0;
+      tagLength = void 0;
+      rowActiveConditions.clear();
+      disjunctPositions = void 0;
+    };
+    const clearTagsForRow = (rowId) => {
+      if (tagLength === void 0) {
+        return;
+      }
+      const rowTagSet = rowTagSets.get(rowId);
+      if (!rowTagSet) {
+        return;
+      }
+      for (const tag of rowTagSet) {
+        const parsedTag = parseTag$1(tag);
+        const currentTagLength = getTagLength(parsedTag);
+        if (currentTagLength === tagLength) {
           removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength);
-          tagCache.delete(tag);
         }
+        tagCache.delete(tag);
+      }
+      rowTagSets.delete(rowId);
+      rowActiveConditions.delete(rowId);
+    };
+    const removeMatchingTagsFromRow = (rowId, pattern) => {
+      const rowTagSet = rowTagSets.get(rowId);
+      if (!rowTagSet) {
+        return false;
+      }
+      const activeConditions = rowActiveConditions.get(rowId);
+      if (activeConditions && disjunctPositions) {
+        activeConditions[pattern.pos] = false;
+        if (!rowVisible(activeConditions, disjunctPositions)) {
+          for (const tag of rowTagSet) {
+            const parsedTag = parseTag$1(tag);
+            removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength);
+            tagCache.delete(tag);
+          }
+          rowTagSets.delete(rowId);
+          rowActiveConditions.delete(rowId);
+          return true;
+        }
+        return false;
+      }
+      for (const tag of rowTagSet) {
+        const parsedTag = parseTag$1(tag);
+        if (tagMatchesPattern(parsedTag, pattern)) {
+          rowTagSet.delete(tag);
+          removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength);
+        }
+      }
+      if (rowTagSet.size === 0) {
         rowTagSets.delete(rowId);
-        rowActiveConditions.delete(rowId);
         return true;
       }
       return false;
-    }
-    for (const tag of rowTagSet) {
-      const parsedTag = parseTag$1(tag);
-      if (tagMatchesPattern(parsedTag, pattern)) {
-        rowTagSet.delete(tag);
-        removeTagFromIndex(parsedTag, rowId, tagIndex, tagLength);
+    };
+    const processMoveOutEvent = (patterns, begin, write, transactionStarted, onDelete) => {
+      if (tagLength === void 0) {
+        debug(
+          `${collectionId ? `[${collectionId}] ` : ``}Received move-out message but no tag length set yet, ignoring`
+        );
+        return transactionStarted;
       }
-    }
-    if (rowTagSet.size === 0) {
-      rowTagSets.delete(rowId);
-      return true;
-    }
-    return false;
-  };
-  const processMoveOutEvent = (patterns, begin, write, transactionStarted) => {
-    if (tagLength === void 0) {
-      debug(
-        `${collectionId ? `[${collectionId}] ` : ``}Received move-out message but no tag length set yet, ignoring`
-      );
-      return transactionStarted;
-    }
-    let txStarted = transactionStarted;
-    for (const pattern of patterns) {
-      const affectedRowIds = findRowsMatchingPattern(pattern, tagIndex);
-      for (const rowId of affectedRowIds) {
-        if (removeMatchingTagsFromRow(rowId, pattern)) {
-          if (!txStarted) {
-            begin();
-            txStarted = true;
+      let txStarted = transactionStarted;
+      for (const pattern of patterns) {
+        const affectedRowIds = findRowsMatchingPattern(pattern, tagIndex);
+        for (const rowId of affectedRowIds) {
+          if (removeMatchingTagsFromRow(rowId, pattern)) {
+            if (!txStarted) {
+              begin();
+              txStarted = true;
+            }
+            write({
+              type: `delete`,
+              key: rowId
+            });
+            onDelete(rowId);
           }
-          write({
-            type: `delete`,
-            key: rowId
-          });
         }
       }
-    }
-    return txStarted;
-  };
-  const processMoveInEvent = (patterns) => {
-    if (tagLength === void 0) {
-      debug(
-        `${collectionId ? `[${collectionId}] ` : ``}Received move-in message but no tag length set yet, ignoring`
-      );
-      return;
-    }
-    for (const pattern of patterns) {
-      const affectedRowIds = findRowsMatchingPattern(pattern, tagIndex);
-      for (const rowId of affectedRowIds) {
-        const activeConditions = rowActiveConditions.get(rowId);
-        if (activeConditions) {
-          activeConditions[pattern.pos] = true;
+      return txStarted;
+    };
+    const processMoveInEvent = (patterns) => {
+      if (tagLength === void 0) {
+        debug(
+          `${collectionId ? `[${collectionId}] ` : ``}Received move-in message but no tag length set yet, ignoring`
+        );
+        return;
+      }
+      for (const pattern of patterns) {
+        const affectedRowIds = findRowsMatchingPattern(pattern, tagIndex);
+        for (const rowId of affectedRowIds) {
+          const activeConditions = rowActiveConditions.get(rowId);
+          if (activeConditions) {
+            activeConditions[pattern.pos] = true;
+          }
         }
       }
-    }
-  };
-  const getSyncMetadata = () => {
-    const schema = relationSchema.state || `public`;
+    };
     return {
-      relation: shapeOptions.params?.table ? [schema, shapeOptions.params.table] : void 0
+      hasTags: () => tagLength !== void 0,
+      processTagsForChangeMessage,
+      clearTagTrackingState,
+      clearTagsForRow,
+      processMoveOutEvent,
+      processMoveInEvent
     };
   };
-  let unsubscribeStream;
+  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 {
+        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,
@@ -749,16 +808,35 @@ function createElectricSync(shapeOptions, options) {
         const persistedResumeState2 = metadata?.collection.get(`electric:resume`);
         return parseElectricResumeState(persistedResumeState2);
       };
+      const persistence = metadata === void 0 ? null : 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(),
-        hydratedResumeState.state
+        lifecycle.resumeState
       );
       const shapeIdentity = getStableShapeIdentity({
         url: shapeOptions.url,
         params: shapeOptions.params
       });
       const hasIncompatiblePersistedResume = persistedResumeState?.kind === `resume` && persistedResumeState.shapeId !== shapeIdentity;
-      const canUsePersistedResume = shapeOptions.offset === void 0 && shapeOptions.handle === void 0 && persistedResumeState?.kind === `resume` && !hasIncompatiblePersistedResume;
+      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) => {
@@ -785,21 +863,16 @@ function createElectricSync(shapeOptions, options) {
         }
       }
       abortController.signal.addEventListener(`abort`, () => {
-        pendingMatches.setState((current) => {
-          current.forEach((match) => {
-            clearTimeout(match.timeoutId);
-            match.reject(new StreamAbortedError());
-          });
-          return /* @__PURE__ */ new Map();
-        });
+        lifecycle.retire(lifecycleEpoch);
       });
       const stream = new ShapeStream({
         ...shapeOptions,
-        // In on-demand mode, we only want to sync changes, so we set the log to `changes_only`
-        log: syncMode === `on-demand` ? `changes_only` : void 0,
+        // 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` ? `now` : void 0),
+        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) => {
@@ -825,11 +898,50 @@ function createElectricSync(shapeOptions, options) {
       let transactionStarted = false;
       const newTxids = /* @__PURE__ */ new Set();
       const newSnapshots = [];
-      let hasReceivedUpToDate = syncMode === `progressive` && canUsePersistedResume;
-      const isBufferingInitialSync = () => syncMode === `progressive` && !hasReceivedUpToDate;
+      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;
+      };
+      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 = () => {
+        if (metadata?.persistence) begin({ immediate: true });
+        else begin();
+      };
       const syncedKeys = /* @__PURE__ */ new Set();
+      let resumeInvalid = false;
       const stageResumeMetadata = () => {
+        if (!isActiveLifecycle() || resumeInvalid) {
+          return;
+        }
         const shapeHandle = stream.shapeHandle;
         const lastOffset = stream.lastOffset;
         if (!shapeHandle || lastOffset === `-1`) {
@@ -840,25 +952,29 @@ function createElectricSync(shapeOptions, options) {
           offset: lastOffset,
           handle: shapeHandle,
           shapeId: shapeIdentity,
-          updatedAt: Date.now()
+          updatedAt: Date.now(),
+          requiresTagState: tagState.hasTags()
         };
-        hydratedResumeState.setState(() => resumeState);
+        lifecycle.resumeState = resumeState;
         metadata?.collection.set(`electric:resume`, resumeState);
       };
-      const commitResetResumeMetadataImmediately = () => {
+      const commitResetResumeMetadataImmediately = (expectInResumeSnapshot = false) => {
         const resetState = {
           kind: `reset`,
           updatedAt: Date.now()
         };
-        hydratedResumeState.setState(() => resetState);
+        lifecycle.resumeState = resetState;
         if (metadata) {
           begin({ immediate: true });
           metadata.collection.set(`electric:resume`, resetState);
+          if (expectInResumeSnapshot) {
+            expectCurrentCommit?.();
+          }
           commit();
         }
       };
-      if (hasIncompatiblePersistedResume) {
-        commitResetResumeMetadataImmediately();
+      if (hasIncompatiblePersistedResume || needsFullSnapshot && persistedResumeState.kind === `resume`) {
+        commitResetResumeMetadataImmediately(true);
       }
       const processChangeMessage = (changeMessage) => {
         if (!isChangeMessage(changeMessage)) {
@@ -905,6 +1021,10 @@ function createElectricSync(shapeOptions, options) {
         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
@@ -912,48 +1032,126 @@ function createElectricSync(shapeOptions, options) {
         // Pass abort signal so requestSnapshot errors can be ignored during cleanup
         signal: abortController.signal
       });
-      unsubscribeStream = stream.subscribe((messages) => {
+      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 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`);
+            }
+          }
+          for (const message of bufferedMessages) {
+            if (isChangeMessage(message)) {
+              pendingPresence.set(
+                collection.getKeyFromItem(message.value),
+                message.headers.operation !== `delete`
+              );
+            }
+          }
+        }
         let commitPoint = null;
-        batchCommitted.setState(() => false);
+        lifecycle.beginMatchGeneration(messages);
         for (const message of messages) {
-          if (isChangeMessage(message) || isMoveOutMessage(message) || isMoveInMessage(message)) {
-            currentBatchMessages.setState((currentBuffer) => {
-              const newBuffer = [...currentBuffer, message];
-              if (newBuffer.length > MAX_BATCH_MESSAGES) {
-                newBuffer.splice(0, newBuffer.length - MAX_BATCH_MESSAGES);
-              }
-              return newBuffer;
-            });
-          }
+          lifecycle.observeMatchMessage(message);
+          if (!isActiveLifecycle()) return;
           if (hasTxids(message) && (!isBufferingInitialSync() || transactionStarted)) {
             message.headers.txids?.forEach((txid) => newTxids.add(txid));
           }
-          const matchesToRemove = [];
-          pendingMatches.state.forEach((match, matchId) => {
-            if (!match.matched) {
-              try {
-                match.matchFn(message);
-              } catch (err) {
-                clearTimeout(match.timeoutId);
-                match.reject(
-                  err instanceof Error ? err : new Error(String(err))
-                );
-                matchesToRemove.push(matchId);
-                debug(`matchFn error: %o`, err);
+          if (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;
             }
-          });
-          removePendingMatches(matchesToRemove);
+            recordPendingPresence(rowId, operation !== `delete`);
+            if (operation !== `update`) {
+              progressiveSnapshotRows.delete(rowId);
+            }
+          }
           if (isChangeMessage(message)) {
             const schema = message.headers.schema;
             if (schema && typeof schema === `string`) {
-              relationSchema.setState(() => schema);
+              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);
+                }
+              }
               bufferedMessages.push(message);
             } else {
               if (!transactionStarted) {
-                begin();
+                beginSourceTransaction();
                 transactionStarted = true;
               }
               processChangeMessage(message);
@@ -974,9 +1172,13 @@ function createElectricSync(shapeOptions, options) {
             } else {
               transactionStarted = processMoveOutEvent(
                 message.headers.patterns,
-                begin,
+                beginSourceTransaction,
                 write,
-                transactionStarted
+                transactionStarted,
+                (rowId) => {
+                  recordPendingPresence(rowId, false);
+                  syncedKeys.delete(rowId);
+                }
               );
             }
           } else if (isMoveInMessage(message)) {
@@ -991,26 +1193,34 @@ function createElectricSync(shapeOptions, options) {
             );
             commitResetResumeMetadataImmediately();
             if (!transactionStarted) {
-              begin();
+              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`
             );
-            begin();
+            beginSourceTransaction();
             truncate();
             clearTagTrackingState();
             syncedKeys.clear();
@@ -1029,27 +1239,36 @@ function createElectricSync(shapeOptions, options) {
                   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 (isMoveInMessage(bufferedMsg)) {
                 processMoveInEvent(bufferedMsg.headers.patterns);
               }
             }
             stageResumeMetadata();
-            applied = commit();
+            applied = commitSourceTransaction();
             bufferedMessages.length = 0;
+            progressiveSnapshotRows.clear();
             debug(
               `${collectionId ? `[${collectionId}] ` : ``}Progressive mode: Atomic swap complete, now in normal sync mode`
             );
           } else {
             if (transactionStarted) {
-              stageResumeMetadata();
-              applied = commit();
+              if (!isResettingSnapshot || finishesReset) {
+                stageResumeMetadata();
+              }
+              applied = commitSourceTransaction();
               transactionStarted = false;
             } else if (commitPoint === `up-to-date` && metadata) {
-              begin();
+              beginSourceTransaction();
               stageResumeMetadata();
-              applied = commit();
+              applied = commitSourceTransaction();
             }
           }
           const readyErrorVersion = streamErrorVersion;
@@ -1058,39 +1277,77 @@ function createElectricSync(shapeOptions, options) {
           } else {
             void applied.then(
               () => wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion),
-              () => 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;
+              }
+            };
+            if (applied === true) {
+              finishReset();
+            } else {
+              void applied.then(finishReset, () => void 0);
+            }
+          }
           if (commitPoint === `up-to-date`) {
             hasReceivedUpToDate = true;
           }
-          seenTxids.setState((currentTxids) => {
-            const clonedSeen = new Set(currentTxids);
-            if (newTxids.size > 0) {
-              debug(
-                `${collectionId ? `[${collectionId}] ` : ``}new txids synced from pg %O`,
-                Array.from(newTxids)
-              );
-            }
-            newTxids.forEach((txid) => clonedSeen.add(txid));
-            newTxids.clear();
-            return clonedSeen;
-          });
-          seenSnapshots.setState((currentSnapshots) => {
-            const seen = [...currentSnapshots, ...newSnapshots];
-            newSnapshots.forEach(
-              (snapshot) => debug(
-                `${collectionId ? `[${collectionId}] ` : ``}new snapshot synced from pg %o`,
-                snapshot
-              )
+          if (newTxids.size > 0) {
+            debug(
+              `${collectionId ? `[${collectionId}] ` : ``}new txids synced from pg %O`,
+              Array.from(newTxids)
             );
-            newSnapshots.length = 0;
-            return seen;
-          });
-          batchCommitted.setState(() => true);
-          resolveMatchedPendingMatches();
+          }
+          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);
+          }
+        );
+      }
       return {
         loadSubset: loadSubsetDedupe?.loadSubset,
         cleanup: () => {
@@ -1100,13 +1357,12 @@ function createElectricSync(shapeOptions, options) {
           );
           unsubscribeStream();
           abortController.abort();
+          pendingResumeBatches.length = 0;
           loadSubsetDedupe?.reset();
-          hydratedResumeState.setState(() => void 0);
+          lifecycle.retire(lifecycleEpoch);
         }
       };
-    },
-    // Expose the getSyncMetadata function
-    getSyncMetadata
+    }
   };
 }
 export {