@tanstack/electric-db-collection 0.4.10 → 0.5.1

package/src/electric.ts

@@ -9,6 +9,8 @@ import {
   DeduplicatedLoadSubset,
   LoadSubsetOperationAbortedError,
   and,
+  validateSyncPersistenceCapability,
+  warnOnce,
   withCollectionConfigFactory,
   withCollectionSyncConfigCleanup,
   withCollectionSyncConfigFactory,
@@ -51,10 +53,8 @@ import type {
   LoadSubsetOptions,
   SyncAppliedReceipt,
   SyncConfig,
-  SyncMetadataApi,
   SyncMode,
   UpdateMutationFnParams,
-  UtilsRecord,
 } from '@tanstack/db'
 import type { StandardSchemaV1 } from '@standard-schema/spec'
 import type {
@@ -67,21 +67,11 @@ import type {
   ShapeStreamOptions,
 } from '@electric-sql/client'
 
-type ElectricSyncMetadataWithHydration = SyncMetadataApi<string | number> & {
-  row: SyncMetadataApi<string | number>[`row`] & {
-    whenHydrated?: () => Promise<void>
-    // Capability marker for wrappers predating the hydration barrier.
-    scanPersisted?: unknown
-  }
-}
-
 // Re-export for user convenience in custom match functions
 export { isChangeMessage, isControlMessage } from '@electric-sql/client'
 
 const debug = DebugModule.debug(`ts/db:electric`)
 
-const FORCE_DISCONNECT_AND_REFRESH_TIMEOUT_MS = 250
-
 /**
  * Symbol for internal test hooks (hidden from public API)
  */
@@ -299,11 +289,11 @@ export type MatchFunction<T extends Row<unknown>> = (
 /**
  * Matching strategies for Electric synchronization
  * Handlers can return:
- * - Txid strategy: { txid: number | number[], timeout?: number } (recommended)
+ * - Txid strategy: { txid: number | number[], timeout?: number } (deprecated compatibility behavior)
  * - Void (no return value) - mutation completes without waiting
  *
  * The optional timeout property specifies how long to wait for the txid(s) in milliseconds.
- * If not specified, defaults to 5000ms.
+ * If not specified, defaults to 15000ms.
  */
 export type MatchingStrategy = {
   txid: Txid | Array<Txid>
@@ -352,13 +342,7 @@ export interface ElectricCollectionConfig<
   T extends Row<unknown> = Row<unknown>,
   TSchema extends StandardSchemaV1 = never,
 > extends Omit<
-  BaseCollectionConfig<
-    T,
-    string | number,
-    TSchema,
-    ElectricCollectionUtils<T>,
-    any
-  >,
+  BaseCollectionConfig<T, string | number, TSchema, ElectricCollectionUtils<T>>,
   `onInsert` | `onUpdate` | `onDelete` | `syncMode`
 > {
   /**
@@ -375,43 +359,82 @@ export interface ElectricCollectionConfig<
 
   /**
    * Optional asynchronous handler function called before an insert operation
+   *
+   * **IMPORTANT - Electric Synchronization:**
+   * This handler **must not resolve** until synchronization is confirmed.
+   * Await one of these synchronization utilities before the handler completes:
+   * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+   * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+   *
+   * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+   *
    * @param params Object containing transaction and collection information
-   * @returns Promise resolving to { txid, timeout? } or void
+   * @returns Promise that should resolve after synchronization is complete
+   *
+   * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+   * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+   *
    * @example
-   * // Basic Electric insert handler with txid (recommended)
-   * onInsert: async ({ transaction }) => {
+   * // Recommended: Wait for txid to sync
+   * onInsert: async ({ transaction, collection }) => {
    *   const newItem = transaction.mutations[0].modified
    *   const result = await api.todos.create({
    *     data: newItem
    *   })
-   *   return { txid: result.txid }
+   *   // Wait for txid to sync before handler completes
+   *   await collection.utils.awaitTxId(result.txid)
    * }
    *
    * @example
    * // Insert handler with custom timeout
-   * onInsert: async ({ transaction }) => {
+   * onInsert: async ({ transaction, collection }) => {
    *   const newItem = transaction.mutations[0].modified
    *   const result = await api.todos.create({
    *     data: newItem
    *   })
-   *   return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
+   *   // Wait up to 10 seconds for txid
+   *   await collection.utils.awaitTxId(result.txid, 10000)
    * }
    *
    * @example
-   * // Insert handler with multiple items - return array of txids
-   * onInsert: async ({ transaction }) => {
+   * // Insert handler with timeout error handling
+   * onInsert: async ({ transaction, collection }) => {
+   *   const newItem = transaction.mutations[0].modified
+   *   const result = await api.todos.create({
+   *     data: newItem
+   *   })
+   *
+   *   try {
+   *     await collection.utils.awaitTxId(result.txid, 5000)
+   *   } catch (error) {
+   *     // Decide sync timeout policy:
+   *     // - Throw to rollback optimistic state
+   *     // - Catch to keep optimistic state (eventual consistency)
+   *     // - Schedule background retry
+   *     console.warn('Sync timeout, keeping optimistic state:', error)
+   *     // Don't throw - allow optimistic state to persist
+   *   }
+   * }
+   *
+   * @example
+   * // Insert handler with multiple items
+   * onInsert: async ({ transaction, collection }) => {
    *   const items = transaction.mutations.map(m => m.modified)
    *   const results = await Promise.all(
    *     items.map(item => api.todos.create({ data: item }))
    *   )
-   *   return { txid: results.map(r => r.txid) }
+   *   // Wait for all txids to sync
+   *   await Promise.all(
+   *     results.map(r => collection.utils.awaitTxId(r.txid))
+   *   )
    * }
    *
    * @example
-   * // Use awaitMatch utility for custom matching
+   * // Alternative: Use awaitMatch utility for custom matching logic
    * onInsert: async ({ transaction, collection }) => {
    *   const newItem = transaction.mutations[0].modified
    *   await api.todos.create({ data: newItem })
+   *   // Wait for specific change to appear in sync stream
    *   await collection.utils.awaitMatch(
    *     (message) => isChangeMessage(message) &&
    *                  message.headers.operation === 'insert' &&
@@ -429,24 +452,39 @@ export interface ElectricCollectionConfig<
 
   /**
    * Optional asynchronous handler function called before an update operation
+   *
+   * **IMPORTANT - Electric Synchronization:**
+   * This handler **must not resolve** until synchronization is confirmed.
+   * Await one of these synchronization utilities before the handler completes:
+   * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+   * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+   *
+   * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+   *
    * @param params Object containing transaction and collection information
-   * @returns Promise resolving to { txid, timeout? } or void
+   * @returns Promise that should resolve after synchronization is complete
+   *
+   * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+   * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+   *
    * @example
-   * // Basic Electric update handler with txid (recommended)
-   * onUpdate: async ({ transaction }) => {
+   * // Recommended: Wait for txid to sync
+   * onUpdate: async ({ transaction, collection }) => {
    *   const { original, changes } = transaction.mutations[0]
    *   const result = await api.todos.update({
    *     where: { id: original.id },
    *     data: changes
    *   })
-   *   return { txid: result.txid }
+   *   // Wait for txid to sync before handler completes
+   *   await collection.utils.awaitTxId(result.txid)
    * }
    *
    * @example
-   * // Use awaitMatch utility for custom matching
+   * // Alternative: Use awaitMatch utility for custom matching logic
    * onUpdate: async ({ transaction, collection }) => {
    *   const { original, changes } = transaction.mutations[0]
    *   await api.todos.update({ where: { id: original.id }, data: changes })
+   *   // Wait for specific change to appear in sync stream
    *   await collection.utils.awaitMatch(
    *     (message) => isChangeMessage(message) &&
    *                  message.headers.operation === 'update' &&
@@ -464,23 +502,38 @@ export interface ElectricCollectionConfig<
 
   /**
    * Optional asynchronous handler function called before a delete operation
+   *
+   * **IMPORTANT - Electric Synchronization:**
+   * This handler **must not resolve** until synchronization is confirmed.
+   * Await one of these synchronization utilities before the handler completes:
+   * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+   * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+   *
+   * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+   *
    * @param params Object containing transaction and collection information
-   * @returns Promise resolving to { txid, timeout? } or void
+   * @returns Promise that should resolve after synchronization is complete
+   *
+   * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+   * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+   *
    * @example
-   * // Basic Electric delete handler with txid (recommended)
-   * onDelete: async ({ transaction }) => {
+   * // Recommended: Wait for txid to sync
+   * onDelete: async ({ transaction, collection }) => {
    *   const mutation = transaction.mutations[0]
    *   const result = await api.todos.delete({
    *     id: mutation.original.id
    *   })
-   *   return { txid: result.txid }
+   *   // Wait for txid to sync before handler completes
+   *   await collection.utils.awaitTxId(result.txid)
    * }
    *
    * @example
-   * // Use awaitMatch utility for custom matching
+   * // Alternative: Use awaitMatch utility for custom matching logic
    * onDelete: async ({ transaction, collection }) => {
    *   const mutation = transaction.mutations[0]
    *   await api.todos.delete({ id: mutation.original.id })
+   *   // Wait for specific change to appear in sync stream
    *   await collection.utils.awaitMatch(
    *     (message) => isChangeMessage(message) &&
    *                  message.headers.operation === 'delete' &&
@@ -599,6 +652,7 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
   commit,
   getCommitCursor,
   waitForCommitsAfter,
+  recordSnapshotRow,
   collectionId,
   encodeColumnName,
   signal,
@@ -615,6 +669,7 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
   commit: (signal?: AbortSignal) => SyncAppliedReceipt
   getCommitCursor: () => number
   waitForCommitsAfter: (cursor: number) => Promise<void>
+  recordSnapshotRow?: (row: T, message: Message<T>) => void
   collectionId?: string
   /**
    * Optional function to encode column names (e.g., camelCase to snake_case).
@@ -676,7 +731,9 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
               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) {
@@ -695,56 +752,6 @@ function createLoadSubsetDedupe<T extends Row<unknown>>({
 
     const { cursor, where, orderBy, limit } = opts
 
-    // When the stream is already up-to-date, it may be in a long-poll wait.
-    // Forcing a disconnect-and-refresh ensures requestSnapshot gets a response
-    // from a fresh server round-trip rather than waiting for the current poll to end.
-    // Some native fetch implementations (notably React Native/Expo) may not abort
-    // long-poll requests promptly. Bound the wait so on-demand live queries don't
-    // remain loading until the long-poll naturally times out.
-    // If the refresh fails or times out, we fall through to requestSnapshot which
-    // still works.
-    if (stream.isUpToDate) {
-      let timeoutId: ReturnType<typeof setTimeout> | undefined
-      const abortSignals = [signal, opts.signal].filter(
-        (candidate): candidate is AbortSignal => candidate !== undefined,
-      )
-      let rejectAbort: (reason: unknown) => void = () => {}
-      const aborted = new Promise<never>((_resolve, reject) => {
-        rejectAbort = reject
-      })
-      const abort = (event: Event) =>
-        rejectAbort(abortReason(event.currentTarget as AbortSignal))
-      for (const abortSignal of abortSignals) {
-        abortSignal.addEventListener(`abort`, abort, { once: true })
-      }
-      try {
-        await Promise.race([
-          stream.forceDisconnectAndRefresh(),
-          new Promise<void>((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()
 
     // Upstream limitation: ShapeStream.requestSnapshot() publishes its rows
@@ -815,7 +822,9 @@ export type AwaitMatchFn<T extends Row<unknown>> = (
  */
 export interface ElectricCollectionUtils<
   T extends Row<unknown> = Row<unknown>,
-> extends UtilsRecord {
+> {
+  // Keep this interface closed: extending UtilsRecord would make every
+  // nonexistent adapter utility appear as `any`.
   awaitTxId: AwaitTxIdFn
   awaitMatch: AwaitMatchFn<T>
 }
@@ -930,7 +939,7 @@ class ElectricLifecycle<T extends Row<unknown>> {
 
   private async awaitTxId(
     txId: Txid,
-    timeout: number = 5000,
+    timeout: number = 15000,
   ): Promise<boolean> {
     debug(
       `${this.collectionId ? `[${this.collectionId}] ` : ``}awaitTxId called with txid %d`,
@@ -958,7 +967,7 @@ class ElectricLifecycle<T extends Row<unknown>> {
 
   private async awaitMatch(
     matchFn: MatchFunction<T>,
-    timeout: number = 3000,
+    timeout: number = 15000,
   ): Promise<boolean> {
     debug(
       `${this.collectionId ? `[${this.collectionId}] ` : ``}awaitMatch called with custom function`,
@@ -1137,17 +1146,32 @@ export function electricCollectionOptions<T extends Row<unknown>>(
    * Process matching strategy and wait for synchronization
    */
   const processMatchingStrategy = async (
-    result: MatchingStrategy,
+    result: unknown,
     waitForTxId: AwaitTxIdFn,
   ): Promise<void> => {
+    const canHaveProperties =
+      (typeof result === `object` && result !== null) ||
+      typeof result === `function`
+
     // Only wait if result contains txid
-    if (result && `txid` in result) {
-      const timeout = result.timeout
+    if (canHaveProperties && `txid` in result) {
+      const strategy = result as Exclude<MatchingStrategy, void>
+      // Warn about deprecated return value pattern
+      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
       // Handle both single txid and array of txids
-      if (Array.isArray(result.txid)) {
-        await Promise.all(result.txid.map((txid) => waitForTxId(txid, timeout)))
+      if (Array.isArray(strategy.txid)) {
+        await Promise.all(
+          strategy.txid.map((txid) => waitForTxId(txid, timeout)),
+        )
       } else {
-        await waitForTxId(result.txid, timeout)
+        await waitForTxId(strategy.txid, timeout)
       }
     }
     // If result is void/undefined, don't wait - mutation completes immediately
@@ -1162,6 +1186,7 @@ export function electricCollectionOptions<T extends Row<unknown>>(
   }
 
   // Create wrapper handlers for direct persistence operations that handle different matching strategies
+  // These wrappers process deprecated return values but don't pass them through
   const wrappedOnInsert = config.onInsert
     ? async (
         params: InsertMutationFnParams<
@@ -1169,13 +1194,12 @@ export function electricCollectionOptions<T extends Row<unknown>>(
           string | number,
           ElectricCollectionUtils<T>
         >,
-      ) => {
+      ): Promise<void> => {
         const handlerResult = await config.onInsert!(params)
         await processMatchingStrategy(
           handlerResult,
           getMutationAwaitTxId(params),
         )
-        return handlerResult
       }
     : undefined
 
@@ -1186,13 +1210,12 @@ export function electricCollectionOptions<T extends Row<unknown>>(
           string | number,
           ElectricCollectionUtils<T>
         >,
-      ) => {
+      ): Promise<void> => {
         const handlerResult = await config.onUpdate!(params)
         await processMatchingStrategy(
           handlerResult,
           getMutationAwaitTxId(params),
         )
-        return handlerResult
       }
     : undefined
 
@@ -1203,13 +1226,12 @@ export function electricCollectionOptions<T extends Row<unknown>>(
           string | number,
           ElectricCollectionUtils<T>
         >,
-      ) => {
+      ): Promise<void> => {
         const handlerResult = await config.onDelete!(params)
         await processMatchingStrategy(
           handlerResult,
           getMutationAwaitTxId(params),
         )
-        return handlerResult
       }
     : undefined
 
@@ -1308,7 +1330,6 @@ function createElectricSync<T extends Row<unknown>>(
   const { getLifecycle, syncMode, collectionId, testHooks } = options
 
   let relationSchema: string | undefined
-  let warnedUnverifiableResume = false
 
   const createTagState = () => {
     const tagCache = new Map<MoveTag, ParsedMoveTag>()
@@ -1679,11 +1700,16 @@ function createElectricSync<T extends Row<unknown>>(
         return parseElectricResumeState(persistedResumeState)
       }
 
-      const persistedMetadata = metadata as
-        | ElectricSyncMetadataWithHydration
-        | undefined
-      const scanPersisted = persistedMetadata?.row.scanPersisted
-      const whenHydrated = persistedMetadata?.row.whenHydrated
+      const persistence =
+        metadata === undefined
+          ? 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(),
@@ -1696,32 +1722,26 @@ function createElectricSync<T extends Row<unknown>>(
       const hasIncompatiblePersistedResume =
         persistedResumeState?.kind === `resume` &&
         persistedResumeState.shapeId !== shapeIdentity
-      const hasUnverifiablePersistedResume =
-        shapeOptions.offset === undefined &&
-        shapeOptions.handle === undefined &&
+      // A pre-ledger `unknown` baseline cannot justify a non-initial cursor.
+      // One fresh replacement establishes consistent evidence for later resumes.
+      const lacksCompletePersistedKeySet =
         persistedResumeState?.kind === `resume` &&
-        scanPersisted !== undefined &&
-        whenHydrated === undefined
-      if (hasUnverifiablePersistedResume && !warnedUnverifiableResume) {
-        warnedUnverifiableResume = true
-        console.warn(
-          `Electric persistence cannot verify hydration for saved resume state. Update the persistence adapter alongside Electric to enable safe resume.`,
-        )
-      }
+        getKeySetEvidence !== undefined &&
+        persistedKeySetEvidence?.status !== `consistent`
       const needsFullSnapshot =
         shapeOptions.offset === undefined &&
         shapeOptions.handle === undefined &&
         persistedResumeState !== undefined &&
         (persistedResumeState.kind === `reset` ||
+          lacksCompletePersistedKeySet ||
           (!retainsTagState && persistedResumeState.requiresTagState !== false))
       const canUsePersistedResume =
         shapeOptions.offset === undefined &&
         shapeOptions.handle === undefined &&
         persistedResumeState?.kind === `resume` &&
         !hasIncompatiblePersistedResume &&
-        !hasUnverifiablePersistedResume &&
         // Cached rows do not contain authoritative tag/active-condition state.
-        // Unknown (older) metadata is conservative; untagged shapes still resume.
+        // Only a complete adapter ledger can justify a persisted cursor.
         !needsFullSnapshot
       const hasExplicitResumeOffset =
         shapeOptions.offset !== undefined && shapeOptions.offset !== `-1`
@@ -1729,6 +1749,8 @@ function createElectricSync<T extends Row<unknown>>(
         clearTagTrackingState()
       }
       const receivesCompleteRows = shapeOptions.params?.replica === `full`
+      const requiresKeySetCertification =
+        canUsePersistedResume && certifyResumeSnapshot !== undefined
       // Eager and progressive streams that start after the initial offset can
       // only apply partial updates when the local materialization is complete.
       const requiresCompleteResume =
@@ -1741,7 +1763,7 @@ function createElectricSync<T extends Row<unknown>>(
         (syncMode === `eager` || needsFullSnapshot) &&
         !canUsePersistedResume &&
         !hasExplicitResumeOffset &&
-        whenHydrated !== undefined
+        hydrateBaseline !== undefined
 
       // Wrap markReady to wait for test hook in progressive mode
       let progressiveReadyGate: Promise<void> | null = null
@@ -1856,6 +1878,54 @@ function createElectricSync<T extends Row<unknown>>(
         !hasReceivedUpToDate &&
         !isResettingSnapshot
       const bufferedMessages: Array<Message<T>> = [] // Buffer change messages during initial sync
+      // Progressive subset rows are provisional: the initial atomic swap
+      // normally discards them. Retain one only when a later stream update
+      // needs that full row as its baseline.
+      const progressiveSnapshotRows = new Map<string | number, Message<T>>()
+
+      // Presence spans the open source transaction and persisted callbacks
+      // whose FIFO receipts have not applied yet. Later callbacks must see
+      // those staged writes even though persistence has not replayed them into
+      // core. Once the newest receipt applies, syncedData is authoritative.
+      const pendingPresence = new Map<string | number, boolean>()
+      let usesBaseline = true
+      let pendingPresenceRevision = 0
+
+      const recordPendingPresence = (
+        rowId: string | number,
+        present: boolean,
+      ) => {
+        pendingPresenceRevision++
+        pendingPresence.set(rowId, present)
+      }
+
+      const recordPendingTruncate = () => {
+        pendingPresenceRevision++
+        pendingPresence.clear()
+        progressiveSnapshotRows.clear()
+        usesBaseline = false
+      }
+
+      const commitSourceTransaction = (): SyncAppliedReceipt => {
+        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, () => undefined)
+        }
+        return applied
+      }
+
+      const beginSourceTransaction = () => {
+        if (metadata?.persistence) begin({ immediate: true })
+        else begin()
+      }
 
       // Track keys that have been synced to handle overlapping subset queries.
       // When multiple subset queries return the same row, the server sends `insert`
@@ -1886,7 +1956,9 @@ function createElectricSync<T extends Row<unknown>>(
         metadata?.collection.set(`electric:resume`, resumeState)
       }
 
-      const commitResetResumeMetadataImmediately = () => {
+      const commitResetResumeMetadataImmediately = (
+        expectInResumeSnapshot = false,
+      ) => {
         const resetState: ElectricResumeState = {
           kind: `reset`,
           updatedAt: Date.now(),
@@ -1896,16 +1968,21 @@ function createElectricSync<T extends Row<unknown>>(
         if (metadata) {
           begin({ immediate: true })
           metadata.collection.set(`electric:resume`, resetState)
+          if (expectInResumeSnapshot) {
+            expectCurrentCommit?.()
+          }
           commit()
         }
       }
 
       if (
         hasIncompatiblePersistedResume ||
-        hasUnverifiablePersistedResume ||
         (needsFullSnapshot && persistedResumeState.kind === `resume`)
       ) {
-        commitResetResumeMetadataImmediately()
+        // This reset is part of the current runtime's startup decision. The
+        // persisted wrapper may commit it before loading the atomic baseline,
+        // so carry ownership of exactly this generation into certification.
+        commitResetResumeMetadataImmediately(true)
       }
 
       /**
@@ -1976,6 +2053,10 @@ function createElectricSync<T extends Row<unknown>>(
         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
@@ -1986,8 +2067,31 @@ function createElectricSync<T extends Row<unknown>>(
 
       const resumeKeysPromise =
         requiresCompleteResume || freshSnapshotPending
-          ? whenHydrated?.()
-          : undefined
+          ? 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`,
+                  )
+                }
+              })()
+            : undefined
+          : requiresKeySetCertification
+            ? (async () => {
+                await certifyResumeSnapshot()
+                const currentKeySetEvidence = getKeySetEvidence?.()
+                if (currentKeySetEvidence?.status !== `consistent`) {
+                  throw new Error(
+                    `Electric persisted resume baseline could not be certified`,
+                  )
+                }
+              })()
+            : undefined
       let areResumeKeysReady = !resumeKeysPromise
       const pendingResumeBatches: Array<Array<Message<T>>> = []
       let unsubscribeStream: () => void = () => {}
@@ -2021,35 +2125,40 @@ function createElectricSync<T extends Row<unknown>>(
 
         if (freshSnapshotPending) {
           freshSnapshotPending = false
-          begin()
+          beginSourceTransaction()
           transactionStarted = true
           truncate()
+          recordPendingTruncate()
           syncedKeys.clear()
           clearTagTrackingState()
           isResettingSnapshot = true
           resetGeneration++
         }
 
-        // Applied rows can also arrive through persistence invalidations.
-        // Overlay only unapplied writes, once per callback rather than once
-        // per message. A queued truncate fences off the previous snapshot.
-        const pendingPresence = new Map<string | number, boolean>()
-        let 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`)
+        // Without persistence, core owns pending source transactions and can
+        // rebuild this callback's presence overlay from them. Persistence owns
+        // queued source transactions until their FIFO turn, so retain the
+        // overlay across callbacks instead. A queued truncate still fences off
+        // the previous snapshot below.
+        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`,
-            )
+          for (const message of bufferedMessages) {
+            if (isChangeMessage(message)) {
+              pendingPresence.set(
+                collection.getKeyFromItem(message.value),
+                message.headers.operation !== `delete`,
+              )
+            }
           }
         }
 
@@ -2091,7 +2200,10 @@ function createElectricSync<T extends Row<unknown>>(
               }
               if (!receivesCompleteRows) continue
             }
-            pendingPresence.set(rowId, operation !== `delete`)
+            recordPendingPresence(rowId, operation !== `delete`)
+            if (operation !== `update`) {
+              progressiveSnapshotRows.delete(rowId)
+            }
           }
 
           if (isChangeMessage(message)) {
@@ -2106,11 +2218,19 @@ function createElectricSync<T extends Row<unknown>>(
             // EXCEPTION: If a transaction is already started (e.g., from must-refetch), write
             // directly to it instead of buffering. This prevents orphan transactions.
             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 {
               // Normal processing: write changes immediately
               if (!transactionStarted) {
-                begin()
+                beginSourceTransaction()
                 transactionStarted = true
               }
 
@@ -2142,11 +2262,11 @@ function createElectricSync<T extends Row<unknown>>(
               // Normal processing: process move-out immediately
               transactionStarted = processMoveOutEvent(
                 message.headers.patterns,
-                begin,
+                beginSourceTransaction,
                 write,
                 transactionStarted,
                 (rowId) => {
-                  pendingPresence.set(rowId, false)
+                  recordPendingPresence(rowId, false)
                   syncedKeys.delete(rowId)
                 },
               )
@@ -2168,7 +2288,7 @@ function createElectricSync<T extends Row<unknown>>(
 
             // Start a transaction and truncate the collection
             if (!transactionStarted) {
-              begin()
+              beginSourceTransaction()
               transactionStarted = true
             }
 
@@ -2179,8 +2299,7 @@ function createElectricSync<T extends Row<unknown>>(
 
             // Clear synced keys tracking since we're starting fresh
             syncedKeys.clear()
-            pendingPresence.clear()
-            usesBaseline = false
+            recordPendingTruncate()
             isResettingSnapshot = true
             resetGeneration++
 
@@ -2192,6 +2311,7 @@ function createElectricSync<T extends Row<unknown>>(
             commitPoint = null
             hasReceivedUpToDate = false // Reset for progressive mode (isBufferingInitialSync will reflect this)
             bufferedMessages.length = 0 // Clear buffered messages
+            progressiveSnapshotRows.clear()
           }
         }
 
@@ -2222,7 +2342,7 @@ function createElectricSync<T extends Row<unknown>>(
             )
 
             // Start atomic swap transaction
-            begin()
+            beginSourceTransaction()
 
             // Truncate to clear all snapshot data
             truncate()
@@ -2257,7 +2377,7 @@ function createElectricSync<T extends Row<unknown>>(
                   // normal-stream transactionStarted flag is still false.
                   true,
                   (rowId) => {
-                    pendingPresence.set(rowId, false)
+                    recordPendingPresence(rowId, false)
                     syncedKeys.delete(rowId)
                   },
                 )
@@ -2269,11 +2389,12 @@ function createElectricSync<T extends Row<unknown>>(
 
             // Commit the atomic swap
             stageResumeMetadata()
-            applied = commit()
+            applied = commitSourceTransaction()
 
             // Exit buffering phase by marking that we've received up-to-date
             // isBufferingInitialSync() will now return false
             bufferedMessages.length = 0
+            progressiveSnapshotRows.clear()
 
             debug(
               `${collectionId ? `[${collectionId}] ` : ``}Progressive mode: Atomic swap complete, now in normal sync mode`,
@@ -2285,12 +2406,12 @@ function createElectricSync<T extends Row<unknown>>(
               if (!isResettingSnapshot || finishesReset) {
                 stageResumeMetadata()
               }
-              applied = commit()
+              applied = commitSourceTransaction()
               transactionStarted = false
             } else if (commitPoint === `up-to-date` && metadata) {
-              begin()
+              beginSourceTransaction()
               stageResumeMetadata()
-              applied = commit()
+              applied = commitSourceTransaction()
             }
           }
           const readyErrorVersion = streamErrorVersion
@@ -2300,7 +2421,15 @@ function createElectricSync<T extends Row<unknown>>(
             void applied.then(
               () =>
                 wrappedMarkReady(wasBufferingInitialSync, readyErrorVersion),
-              () => undefined,
+              (error: unknown) => {
+                if (!isActiveLifecycle() || abortController.signal.aborted) {
+                  return
+                }
+                streamErrorVersion++
+                unsubscribeStream()
+                abortController.abort()
+                if (collection.status !== `error`) markError(error)
+              },
             )
           }