@tanstack/db-sqlite-persistence-core 0.4.8 → 0.4.9

package/dist/esm/persisted.js

@@ -1,8 +1,60 @@
-import { safeRandomUUID, withCollectionConfigFactory, whenSyncAccepted, SyncTransactionAbortedError, getLoadSubsetDemandKey, equalPersistedSnapshotValues, compileSingleRowExpression, toBooleanPredicate, SYNC_PERSISTENCE_VERSION, SYNC_PERSISTENCE_PROTOCOL, PERSISTED_READINESS, NoPendingSyncTransactionCommitError, NoPendingSyncTransactionWriteError, withAcceptedReceipt } from "@tanstack/db";
+import { safeRandomUUID, withCollectionConfigFactory, whenSyncAccepted, SyncTransactionAbortedError, collectionOptionsClaim, getLoadSubsetDemandKey, equalPersistedSnapshotValues, compileSingleRowExpression, PERSISTED_READINESS, toBooleanPredicate, SYNC_PERSISTENCE_VERSION, SYNC_PERSISTENCE_PROTOCOL, NoPendingSyncTransactionCommitError, NoPendingSyncTransactionWriteError, withAcceptedReceipt } from "@tanstack/db";
 import { InvalidPersistedCollectionConfigError, DuplicateRemoteSubsetOwnerError, toPersistedCollectionDurabilityError, InvalidPersistedStorageKeyEncodingError, InvalidPersistedStorageKeyError, InvalidSyncConfigError, InvalidPersistedCollectionCoordinatorError, PersistedCollectionDurabilityError, IndeterminateCommitError, InvalidPersistenceAdapterError } from "./errors.js";
 import { serializeSQLiteBigInt, serializeSQLiteTemporal } from "./sqlite-value.js";
 import { toTransportedLoadSubsetOptions, toProcessLocalLoadSubsetOptions, validateRemoteSubsetOptions } from "./remote-subset-wire.js";
 import { reportRemoteSubsetOwnerError, unloadRemoteSubsetOwner } from "./remote-subset-owner.js";
+function eagerStorageTarget(collectionId) {
+  return { kind: `eager`, collectionId };
+}
+function managedStorageTarget(storageCollectionId, claimId) {
+  return { kind: `managed`, storageCollectionId, claimId };
+}
+function resolvePersistedStorageTarget(target, legacyClaimId) {
+  const input = target;
+  if (typeof input !== `object` || input === null) {
+    throw new InvalidPersistedCollectionConfigError(
+      `SQLite persistence requires an explicit eager or managed storage target`
+    );
+  }
+  const fields = input;
+  if (fields.kind === `eager`) {
+    if (typeof fields.collectionId !== `string` || fields.collectionId.trim().length === 0) {
+      throw new InvalidPersistedCollectionConfigError(
+        `An eager storage target requires a nonempty collectionId`
+      );
+    }
+    if (legacyClaimId !== void 0 || `claimId` in fields || `storageCollectionId` in fields) {
+      throw new InvalidPersistedCollectionConfigError(
+        `An eager storage target cannot carry a persisted cache claim`
+      );
+    }
+    return { collectionId: fields.collectionId };
+  }
+  if (fields.kind !== `managed`) {
+    throw new InvalidPersistedCollectionConfigError(
+      `Unknown SQLite persistence storage target kind`
+    );
+  }
+  if (typeof fields.storageCollectionId !== `string` || fields.storageCollectionId.trim().length === 0 || typeof fields.claimId !== `string` || fields.claimId.trim().length === 0) {
+    throw new InvalidPersistedCollectionConfigError(
+      `A managed storage target requires a storageCollectionId and persisted cache claim`
+    );
+  }
+  if (`collectionId` in fields) {
+    throw new InvalidPersistedCollectionConfigError(
+      `A managed storage target cannot carry an eager collectionId`
+    );
+  }
+  if (legacyClaimId !== void 0 && legacyClaimId !== fields.claimId) {
+    throw new InvalidPersistedCollectionConfigError(
+      `The persisted cache claim does not match its storage target`
+    );
+  }
+  return {
+    collectionId: fields.storageCollectionId,
+    claimId: fields.claimId
+  };
+}
 const SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY = /* @__PURE__ */ Symbol.for(
   `tanstack-db.sqlite-driver-supports-shared-logical-scheduling`
 );
@@ -44,6 +96,7 @@ class PersistedReadinessTracker {
   }
 }
 const DEFAULT_NETWORK_TIMEOUT_MS = 3e3;
+const CACHE_CLAIM_RENEW_WINDOW_MS = 6e4;
 const MAX_TIMER_TIMEOUT_MS = 2147483647;
 function getNetworkTimeoutMs(initialRender) {
   if (initialRender === void 0) return void 0;
@@ -144,10 +197,6 @@ class SingleProcessCoordinator {
     if (acquisitions.size === 0) {
       this.remoteSubsetAcquisitions.delete(collectionId);
     }
-    try {
-      await acquisition.load;
-    } catch {
-    }
     await unloadRemoteSubsetOwner(acquisition.owner, acquisition.options);
   }
   registerRemoteSubsetOwner(collectionId, owner) {
@@ -161,13 +210,9 @@ class SingleProcessCoordinator {
       this.remoteSubsetAcquisitions.delete(collectionId);
       this.remoteSubsetOwners.delete(collectionId);
       for (const acquisition of acquisitions?.values() ?? []) {
-        void (async () => {
-          try {
-            await acquisition.load;
-          } catch {
-          }
-          await unloadRemoteSubsetOwner(owner, acquisition.options);
-        })().catch(() => void 0);
+        void unloadRemoteSubsetOwner(owner, acquisition.options).catch(
+          () => void 0
+        );
       }
     };
   }
@@ -184,7 +229,10 @@ class SingleProcessCoordinator {
       );
     }
     try {
-      await adapter.applyCommittedTx(collectionId, tx);
+      await adapter.applyCommittedTx(
+        tx.cacheGenerationClaimId ? managedStorageTarget(collectionId, tx.cacheGenerationClaimId) : eagerStorageTarget(collectionId),
+        tx
+      );
     } catch (error) {
       throw toPersistedCollectionDurabilityError(collectionId, error);
     }
@@ -317,6 +365,13 @@ class ApplyMutex {
     return this.reserve().run(task);
   }
 }
+function matchesAnySubset(value, evaluators) {
+  return evaluators.some(
+    (evaluator) => !evaluator || toBooleanPredicate(
+      evaluator(value)
+    )
+  );
+}
 function toStableSerializable(value) {
   if (value == null) {
     return value;
@@ -409,23 +464,28 @@ function toPersistedMutationEnvelope(mutation) {
   };
 }
 class PersistedCollectionRuntime {
-  constructor(mode, collectionId, persistence, syncMode, dbName, persistedReadiness) {
+  constructor(mode, collectionId, persistence, syncMode, dbName, persistedReadiness, optionsClaim) {
     this.mode = mode;
     this.collectionId = collectionId;
     this.persistence = persistence;
     this.syncMode = syncMode;
     this.dbName = dbName;
     this.persistedReadiness = persistedReadiness;
+    this.optionsClaim = optionsClaim;
     this.applyMutex = new ApplyMutex();
     this.activeSubsets = /* @__PURE__ */ new Map();
     this.hydrationSequence = 0;
     this.resetSequence = 0;
     this.pendingRemoteSubsetEnsures = /* @__PURE__ */ new Map();
+    this.scopedRefreshes = /* @__PURE__ */ new Map();
+    this.rotatedAcquisitions = /* @__PURE__ */ new Map();
+    this.rotatedEnsures = /* @__PURE__ */ new WeakMap();
     this.queuedHydrationTransactions = [];
     this.queuedTxCommitted = [];
     this.requestIds = /* @__PURE__ */ new WeakMap();
     this.hydratedDemands = /* @__PURE__ */ new Set();
     this.collection = null;
+    this.boundCollection = null;
     this.syncControls = {
       begin: null,
       write: null,
@@ -451,9 +511,16 @@ class PersistedCollectionRuntime {
     this.indexAddedUnsubscribe = null;
     this.indexRemovedUnsubscribe = null;
     this.remoteEnsureRetryTimer = null;
+    this.cacheClaimRenewTimer = null;
+    this.cacheClaimRecovery = null;
     this.nextRequestId = 0;
     this.startupSettled = false;
     this.sourceTruncateGeneration = 0;
+    this.scopedRecovery = false;
+    this.scopedRecoveryPending = false;
+    this.scopedRecoverySequence = 0;
+    this.recoverQueuedAfterLocalLoadFailure = false;
+    this.startupCacheGenerationRotated = false;
     this.latestTerm = 0;
     this.latestSeq = 0;
     this.latestRowVersion = 0;
@@ -462,6 +529,167 @@ class PersistedCollectionRuntime {
     this.localSeq = 0;
     this.localRowVersion = 0;
   }
+  get storageCollectionId() {
+    return this.cacheGenerationClaim?.storageCollectionId ?? this.collectionId;
+  }
+  storageTargetFor(storageCollectionId = this.storageCollectionId, claimId = this.cacheGenerationClaim?.claimId) {
+    if (this.mode === `sync-present` && this.syncMode === `on-demand` && this.persistence.adapter.claimCacheGeneration) {
+      if (!claimId) {
+        throw new InvalidPersistedCollectionConfigError(
+          `A managed on-demand cache operation requires a persisted cache claim`
+        );
+      }
+      return { kind: `managed`, storageCollectionId, claimId };
+    }
+    return { kind: `eager`, collectionId: storageCollectionId };
+  }
+  cacheGenerationNow() {
+    return this.persistence.adapter.getCacheGenerationNow?.() ?? Date.now();
+  }
+  hasExpiredCacheClaim() {
+    const expiresAtMs = this.cacheGenerationClaim?.expiresAtMs;
+    return expiresAtMs !== void 0 && this.cacheGenerationNow() >= expiresAtMs;
+  }
+  async claimCacheGeneration(lifecycleGeneration) {
+    if (this.mode !== `sync-present` || this.syncMode !== `on-demand`) return;
+    const adapter = this.persistence.adapter;
+    const capabilities = [
+      adapter.claimCacheGeneration,
+      adapter.rotateCacheGeneration,
+      adapter.renewCacheGenerationClaim,
+      adapter.releaseCacheGenerationClaim
+    ];
+    if (capabilities.some(Boolean) && !capabilities.every(Boolean)) {
+      throw new InvalidPersistedCollectionConfigError(
+        `An on-demand managed cache generation adapter must implement claimCacheGeneration, rotateCacheGeneration, renewCacheGenerationClaim, and releaseCacheGenerationClaim together`
+      );
+    }
+    if (!adapter.claimCacheGeneration) return;
+    const claim = await adapter.claimCacheGeneration(this.collectionId);
+    if (lifecycleGeneration !== this.lifecycleGeneration) {
+      await adapter.releaseCacheGenerationClaim?.(claim.claimId);
+      return;
+    }
+    this.cacheGenerationClaim = claim;
+    this.scheduleCacheClaimRenewal(claim);
+    this.attachCoordinatorSubscription();
+  }
+  clearCacheClaimRenewal() {
+    if (this.cacheClaimRenewTimer !== null) {
+      clearTimeout(this.cacheClaimRenewTimer);
+      this.cacheClaimRenewTimer = null;
+    }
+  }
+  scheduleCacheClaimRenewal(claim) {
+    this.clearCacheClaimRenewal();
+    if (claim.expiresAtMs === void 0 || !this.persistence.adapter.renewCacheGenerationClaim) {
+      return;
+    }
+    const remaining = claim.expiresAtMs - this.cacheGenerationNow();
+    const delay = remaining <= 0 ? 1e3 : Math.max(
+      1,
+      Math.min(CACHE_CLAIM_RENEW_WINDOW_MS, Math.floor(remaining / 2))
+    );
+    const lifecycleGeneration = this.lifecycleGeneration;
+    this.cacheClaimRenewTimer = setTimeout(() => {
+      this.cacheClaimRenewTimer = null;
+      void this.ensureCacheClaimActive().catch(() => {
+        if (lifecycleGeneration === this.lifecycleGeneration && this.cacheGenerationClaim === claim) {
+          this.scheduleCacheClaimRenewal(claim);
+        }
+      });
+    }, delay);
+  }
+  async ensureCacheClaimActive() {
+    if (this.cacheClaimRecovery) {
+      await this.cacheClaimRecovery;
+      return;
+    }
+    if (await this.renewCacheClaim(this.persistence.adapter)) return;
+    if (!this.cacheClaimRecovery) {
+      const recovery = this.restartSourceAfterScopedRecovery === void 0 ? this.reclaimStartupCacheGeneration() : this.startScopedRecovery();
+      this.cacheClaimRecovery = recovery;
+      void recovery.finally(() => {
+        if (this.cacheClaimRecovery === recovery) {
+          this.cacheClaimRecovery = null;
+        }
+      }).catch(() => void 0);
+    }
+    await this.cacheClaimRecovery;
+  }
+  scheduleCacheClaimRecovery(lifecycleGeneration) {
+    queueMicrotask(() => {
+      if (lifecycleGeneration !== this.lifecycleGeneration) return;
+      void this.ensureCacheClaimActive().then(
+        () => this.applyMutex.run(() => this.flushQueuedTxCommittedUnsafe())
+      ).catch((error) => {
+        this.markTerminalFailure(error, lifecycleGeneration);
+      });
+    });
+  }
+  async reclaimStartupCacheGeneration() {
+    const lifecycleGeneration = this.lifecycleGeneration;
+    const previous = this.cacheGenerationClaim;
+    if (!previous) return;
+    if (!this.persistence.adapter.rotateCacheGeneration) {
+      throw new InvalidPersistedCollectionConfigError(
+        `A managed on-demand cache adapter must rotate expired startup claims`
+      );
+    }
+    this.clearCacheClaimRenewal();
+    this.coordinatorUnsubscribe?.();
+    this.coordinatorUnsubscribe = null;
+    const rotated = await this.persistence.adapter.rotateCacheGeneration(
+      this.collectionId,
+      previous.claimId,
+      void 0,
+      previous.storageCollectionId
+    );
+    if (lifecycleGeneration !== this.lifecycleGeneration) {
+      await this.persistence.adapter.releaseCacheGenerationClaim?.(
+        rotated.claimId
+      );
+      return;
+    }
+    this.cacheGenerationClaim = rotated;
+    this.startupCacheGenerationRotated = true;
+    this.resetSequence++;
+    this.latestTerm = 0;
+    this.latestSeq = 0;
+    this.latestRowVersion = 0;
+    this.localTerm = 1;
+    this.localSeq = 0;
+    this.localRowVersion = 0;
+    this.persistedResumeGeneration = void 0;
+    this.persistedKeySetEvidence = { status: `incompatible` };
+    this.scheduleCacheClaimRenewal(rotated);
+    this.attachCoordinatorSubscription();
+  }
+  async renewCacheClaim(adapter) {
+    const claim = this.cacheGenerationClaim;
+    if (!claim || !adapter.renewCacheGenerationClaim || this.scopedRecoveryPending)
+      return true;
+    if (claim.expiresAtMs !== void 0 && claim.expiresAtMs - this.cacheGenerationNow() > CACHE_CLAIM_RENEW_WINDOW_MS) {
+      if (this.cacheClaimRenewTimer === null) {
+        this.scheduleCacheClaimRenewal(claim);
+      }
+      return true;
+    }
+    const lifecycleGeneration = this.lifecycleGeneration;
+    const expiresAtMs = await adapter.renewCacheGenerationClaim(
+      claim.storageCollectionId,
+      claim.claimId
+    );
+    if (lifecycleGeneration !== this.lifecycleGeneration || this.cacheGenerationClaim?.claimId !== claim.claimId || this.cacheGenerationClaim.storageCollectionId !== claim.storageCollectionId) {
+      return true;
+    }
+    if (expiresAtMs === void 0) {
+      return false;
+    }
+    this.cacheGenerationClaim = { ...claim, expiresAtMs };
+    this.scheduleCacheClaimRenewal(this.cacheGenerationClaim);
+    return true;
+  }
   setSyncControls(syncControls) {
     this.advanceLifecycle();
     this.syncErrorReported = false;
@@ -472,6 +700,12 @@ class PersistedCollectionRuntime {
       commit: commit ? (signal) => this.trackAppliedReceipt(commit(signal)) : null
     };
   }
+  setSourceRestartAfterScopedRecovery(restart) {
+    this.restartSourceAfterScopedRecovery = restart ?? null;
+  }
+  clearSourceRestartAfterScopedRecovery() {
+    this.restartSourceAfterScopedRecovery = void 0;
+  }
   reportSyncError(error) {
     const markError = this.syncControls.markError;
     if (this.syncErrorReported) return this.reportedSyncError;
@@ -486,8 +720,9 @@ class PersistedCollectionRuntime {
   }
   registerRemoteSubsetOwner(owner) {
     this.remoteSubsetOwnerUnsubscribe?.();
+    this.remoteSubsetOwner = owner;
     this.remoteSubsetOwnerUnsubscribe = this.persistence.coordinator.registerRemoteSubsetOwner(
-      this.collectionId,
+      this.storageCollectionId,
       owner
     );
   }
@@ -512,6 +747,23 @@ class PersistedCollectionRuntime {
       )
     );
   }
+  // An ensure reply settles a follower's load (law 7). A source's loadSubset
+  // must await every commit receipt that establishes its result, so the
+  // leader broadcasts those commits before it replies on the same channel.
+  // They are already queued on the apply mutex; settle after they show here.
+  async applyLeaderCommitsBeforeReply(options) {
+    try {
+      if (this.hasExpiredCacheClaim() || this.cacheClaimRecovery) {
+        await this.ensureCacheClaimActive();
+      }
+      await this.applyMutex.run(() => this.flushQueuedTxCommittedUnsafe());
+      this.throwIfTerminal();
+    } catch (error) {
+      if (this.getCurrentTerminalFailure()) this.unloadSubset(options);
+      else this.queueRemoteSubsetEnsure(options);
+      throw error;
+    }
+  }
   clearSyncControls() {
     this.syncControls = {
       begin: null,
@@ -570,17 +822,46 @@ class PersistedCollectionRuntime {
   isApplyingInternally() {
     return this.internalApplyDepth > 0;
   }
-  setCollection(collection) {
+  isScopedRecoveryPending() {
+    return this.scopedRecoveryPending;
+  }
+  hasBoundCollection() {
+    return this.boundCollection !== null;
+  }
+  setCollection(collection, syncControls) {
+    if (collection.config[collectionOptionsClaim] !== this.optionsClaim) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Persisted sync belongs to its options Collection`
+      );
+    }
+    if (this.boundCollection && this.boundCollection !== collection) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Persisted options cannot own more than one Collection`
+      );
+    }
+    const previousCollection = this.collection;
+    const previousControls = this.syncControls;
+    this.setSyncControls(syncControls);
     if (this.collection === collection) {
+      this.boundCollection ??= collection;
       return;
     }
     this.collection = collection;
-    this.attachCoordinatorSubscription();
+    try {
+      if (!this.persistence.adapter.claimCacheGeneration || this.mode !== `sync-present` || this.syncMode !== `on-demand`) {
+        this.attachCoordinatorSubscription();
+      }
+    } catch (error) {
+      this.collection = previousCollection;
+      this.syncControls = previousControls;
+      throw error;
+    }
+    this.boundCollection ??= collection;
   }
   getLeadershipState() {
     return {
       nodeId: this.persistence.coordinator.getNodeId(),
-      isLeader: this.persistence.coordinator.isLeader(this.collectionId)
+      isLeader: this.persistence.coordinator.isLeader(this.storageCollectionId)
     };
   }
   runInHydrationScope(task, adapter = this.persistence.adapter) {
@@ -595,6 +876,7 @@ class PersistedCollectionRuntime {
       return this.startPromise;
     }
     const lifecycleGeneration = this.lifecycleGeneration;
+    this.startupCacheGenerationRotated = false;
     const isRestart = this.hasAttemptedStartup;
     this.hasAttemptedStartup = true;
     let resolveStartupMetadata;
@@ -605,63 +887,98 @@ class PersistedCollectionRuntime {
     });
     void this.startupMetadataPromise.catch(() => void 0);
     this.startPromise = (async () => {
+      await this.claimCacheGeneration(lifecycleGeneration);
+      if (lifecycleGeneration !== this.lifecycleGeneration) {
+        resolveStartupMetadata();
+        return;
+      }
+      let metadataExpired = false;
       const loadStartupMetadata = async (adapter) => {
         if (lifecycleGeneration !== this.lifecycleGeneration) {
           resolveStartupMetadata();
           return false;
         }
         try {
-          await this.loadStartupMetadataInternal(lifecycleGeneration, adapter);
+          if (!await this.loadStartupMetadataInternal(
+            lifecycleGeneration,
+            adapter
+          )) {
+            metadataExpired = true;
+            return false;
+          }
           return lifecycleGeneration === this.lifecycleGeneration;
         } catch (error) {
+          if (this.cacheGenerationClaim && this.hasExpiredCacheClaim()) {
+            metadataExpired = true;
+            return false;
+          }
           rejectStartupMetadata(error);
           throw error;
         }
       };
       let startup;
       const scheduleStartupAsOneHydrate = this.persistence.adapter.runInHydrationScope !== void 0 && (!isRestart || (this.persistence.adapter.isHydrationScopeScheduled?.() ?? true));
-      if (scheduleStartupAsOneHydrate) {
-        startup = await this.applyMutex.run(async () => {
-          const result = await this.runInHydrationScope(async (adapter) => {
-            if (!await loadStartupMetadata(adapter)) return void 0;
-            return this.startInternal(
-              lifecycleGeneration,
-              adapter,
-              resolveStartupMetadata
-            );
+      for (; ; ) {
+        metadataExpired = false;
+        const storageAtAttempt = this.storageCollectionId;
+        if (scheduleStartupAsOneHydrate) {
+          startup = await this.applyMutex.run(async () => {
+            const result = await this.runInHydrationScope(async (adapter) => {
+              if (!await loadStartupMetadata(adapter)) return void 0;
+              return this.startInternal(
+                lifecycleGeneration,
+                adapter,
+                resolveStartupMetadata
+              );
+            });
+            if (lifecycleGeneration === this.lifecycleGeneration) {
+              await this.flushQueuedTxCommittedUnsafe();
+            }
+            return result;
           });
-          if (lifecycleGeneration === this.lifecycleGeneration) {
-            await this.flushQueuedTxCommittedUnsafe();
-          }
-          return result;
-        });
-      } else {
-        if (await loadStartupMetadata(this.persistence.adapter)) {
-          if (this.persistence.adapter.isHydrationScopeScheduled?.()) {
-            startup = await this.applyMutex.run(async () => {
-              const result = await this.runInHydrationScope(
-                (adapter) => this.startInternal(
-                  lifecycleGeneration,
-                  adapter,
-                  resolveStartupMetadata
-                )
+        } else {
+          if (await loadStartupMetadata(this.persistence.adapter)) {
+            if (this.persistence.adapter.isHydrationScopeScheduled?.()) {
+              startup = await this.applyMutex.run(async () => {
+                const result = await this.runInHydrationScope(
+                  (adapter) => this.startInternal(
+                    lifecycleGeneration,
+                    adapter,
+                    resolveStartupMetadata
+                  )
+                );
+                if (lifecycleGeneration === this.lifecycleGeneration) {
+                  await this.flushQueuedTxCommittedUnsafe();
+                }
+                return result;
+              });
+            } else {
+              startup = await this.startInternal(
+                lifecycleGeneration,
+                this.persistence.adapter,
+                resolveStartupMetadata
               );
               if (lifecycleGeneration === this.lifecycleGeneration) {
                 await this.flushQueuedTxCommittedUnsafe();
               }
-              return result;
-            });
-          } else {
-            startup = await this.startInternal(
-              lifecycleGeneration,
-              this.persistence.adapter,
-              resolveStartupMetadata
-            );
-            if (lifecycleGeneration === this.lifecycleGeneration) {
-              await this.flushQueuedTxCommittedUnsafe();
             }
           }
         }
+        if (this.cacheGenerationClaim && this.syncMode === `on-demand` && // Hydration may have changed this through loadStartupMetadata().
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        !metadataExpired) {
+          await this.ensureCacheClaimActive();
+          metadataExpired = storageAtAttempt !== this.storageCollectionId;
+        }
+        if (!metadataExpired) break;
+        await this.ensureCacheClaimActive();
+        if (lifecycleGeneration !== this.lifecycleGeneration) {
+          resolveStartupMetadata();
+          return;
+        }
+      }
+      if (this.cacheGenerationClaim && this.syncMode === `on-demand` && lifecycleGeneration === this.lifecycleGeneration) {
+        resolveStartupMetadata();
       }
       if (startup !== void 0 && lifecycleGeneration === this.lifecycleGeneration) {
         await this.requestCoordinatorPersistedIndexes(
@@ -697,6 +1014,7 @@ class PersistedCollectionRuntime {
       await this.ensureStarted();
       if (lifecycleGeneration !== this.lifecycleGeneration) return;
       if (this.syncMode !== `on-demand`) return;
+      if (this.scopedRecovery) return;
       const appliedCursor = await this.applyMutex.run(async () => {
         const result = await this.runInHydrationScope(
           (adapter) => this.hydrateBaseline(lifecycleGeneration, adapter)
@@ -706,6 +1024,10 @@ class PersistedCollectionRuntime {
         }
         return result;
       });
+      if (appliedCursor === false) {
+        await this.ensureCacheClaimActive();
+        return;
+      }
       if (appliedCursor !== void 0 && lifecycleGeneration === this.lifecycleGeneration) {
         await this.waitForAppliedReceiptsAfter(appliedCursor, `accepted`);
       }
@@ -722,14 +1044,32 @@ class PersistedCollectionRuntime {
     this.resumeCertificationPromise = (async () => {
       await this.ensureStarted();
       if (lifecycleGeneration !== this.lifecycleGeneration) return;
-      const snapshot = await this.persistence.adapter.loadResumeSnapshot(
-        this.collectionId,
-        {
-          requiredIndexSignatures: this.getRequiredIndexSignatures(),
-          includeRows: false
-        }
-      );
-      if (lifecycleGeneration !== this.lifecycleGeneration) return;
+      if (this.scopedRecovery) return;
+      const storageCollectionId = this.storageCollectionId;
+      const claimId = this.cacheGenerationClaim?.claimId;
+      const certificationIsCurrent = () => lifecycleGeneration === this.lifecycleGeneration && !this.scopedRecovery && storageCollectionId === this.storageCollectionId && claimId === this.cacheGenerationClaim?.claimId;
+      let snapshot;
+      try {
+        snapshot = await this.persistence.adapter.loadResumeSnapshot(
+          this.storageTargetFor(storageCollectionId, claimId),
+          {
+            requiredIndexSignatures: this.getRequiredIndexSignatures(),
+            includeRows: false,
+            cacheGenerationClaimId: claimId
+          }
+        );
+      } catch (error) {
+        if (!certificationIsCurrent()) return;
+        if (!claimId || !this.hasExpiredCacheClaim()) throw error;
+        await this.ensureCacheClaimActive();
+        return;
+      }
+      if (!certificationIsCurrent()) return;
+      if (claimId && !await this.renewCacheClaim(this.persistence.adapter)) {
+        await this.ensureCacheClaimActive();
+        return;
+      }
+      if (!certificationIsCurrent()) return;
       this.bindResumeSnapshotEvidence(snapshot);
     })();
     return this.resumeCertificationPromise;
@@ -737,6 +1077,162 @@ class PersistedCollectionRuntime {
   getKeySetEvidence() {
     return this.persistedKeySetEvidence;
   }
+  hasManagedCacheGeneration() {
+    return this.cacheGenerationClaim !== void 0;
+  }
+  hasRotatedStartupCacheGeneration() {
+    return this.startupCacheGenerationRotated;
+  }
+  async startScopedRecovery(resetMetadata) {
+    this.throwIfTerminal();
+    this.clearCacheClaimRenewal();
+    const lifecycleGeneration = this.lifecycleGeneration;
+    const restartSource = this.restartSourceAfterScopedRecovery;
+    this.scopedRecovery = true;
+    this.scopedRecoveryPending = true;
+    const recoverySequence = ++this.scopedRecoverySequence;
+    this.hydratedDemands.clear();
+    this.resetSequence++;
+    let resolveCacheRotated;
+    let rejectCacheRotated;
+    let sourceRestart;
+    try {
+      if (restartSource) {
+        const cacheRotated = new Promise((resolve, reject) => {
+          resolveCacheRotated = resolve;
+          rejectCacheRotated = reject;
+        });
+        void cacheRotated.catch(() => void 0);
+        sourceRestart = Promise.resolve(restartSource(cacheRotated));
+        void sourceRestart.catch(() => void 0);
+      }
+      await this.applyMutex.run(async () => {
+        this.throwIfLifecycleReplaced(lifecycleGeneration);
+        const claim = this.cacheGenerationClaim;
+        if (claim && this.persistence.adapter.rotateCacheGeneration) {
+          const previousStorageId = claim.storageCollectionId;
+          const rotated = await this.persistence.adapter.rotateCacheGeneration(
+            this.collectionId,
+            claim.claimId,
+            resetMetadata,
+            previousStorageId
+          );
+          if (lifecycleGeneration !== this.lifecycleGeneration) {
+            await this.persistence.adapter.releaseCacheGenerationClaim?.(
+              rotated.claimId
+            );
+            throw new SyncTransactionAbortedError();
+          }
+          for (const options of this.activeSubsets.values()) {
+            void this.persistence.coordinator.requestReleaseRemoteSubset(
+              previousStorageId,
+              this.rotatedAcquisitions.get(options) ?? options
+            ).catch(() => void 0);
+            if (options.signal?.aborted) {
+              this.rotatedAcquisitions.delete(options);
+              continue;
+            }
+            this.rotatedAcquisitions.set(options, {
+              ...options,
+              refetch: true
+            });
+          }
+          this.remoteSubsetOwnerUnsubscribe?.();
+          this.remoteSubsetOwnerUnsubscribe = null;
+          this.coordinatorUnsubscribe?.();
+          this.coordinatorUnsubscribe = null;
+          this.cacheGenerationClaim = rotated;
+          this.latestTerm = 0;
+          this.latestSeq = 0;
+          this.latestRowVersion = 0;
+          this.publicRowVersion = 0;
+          this.resetTermFence = void 0;
+          this.localTerm = 1;
+          this.localSeq = 0;
+          this.localRowVersion = 0;
+          this.queuedTxCommitted.length = 0;
+          this.persistedResumeGeneration = void 0;
+          this.persistedKeySetEvidence = { status: `incompatible` };
+          this.resumeCertificationPromise = null;
+          this.resumeGenerationOwner = /* @__PURE__ */ Symbol(
+            `persisted resume generation owner`
+          );
+          this.attachCoordinatorSubscription();
+          if (this.remoteSubsetOwner) {
+            this.registerRemoteSubsetOwner(this.remoteSubsetOwner);
+          }
+        }
+        if (this.syncControls.begin && this.syncControls.commit) {
+          const applied = this.withInternalApply(() => {
+            this.syncControls.begin?.();
+            this.syncControls.truncate?.({ markReady: false });
+            if (resetMetadata) {
+              this.syncControls.metadata?.collection.set(
+                resetMetadata.key,
+                resetMetadata.value
+              );
+            }
+            return this.syncControls.commit?.() ?? true;
+          });
+          await whenSyncAccepted(applied);
+          if (!this.cacheGenerationClaim && recoverySequence === this.scopedRecoverySequence) {
+            this.scopedRecoveryPending = false;
+          }
+          await this.runInHydrationScope(async (adapter) => {
+            if (this.recoverQueuedAfterLocalLoadFailure) {
+              this.recoverQueuedAfterLocalLoadFailure = false;
+              await this.recoverBufferedTransactionsAfterLocalLoadFailureUnsafe(
+                lifecycleGeneration,
+                adapter
+              );
+            } else {
+              await this.flushQueuedHydrationTransactionsUnsafe(adapter);
+            }
+          });
+          await this.flushQueuedTxCommittedUnsafe();
+        }
+        if (recoverySequence === this.scopedRecoverySequence) {
+          this.scopedRecoveryPending = false;
+          if (this.cacheGenerationClaim) {
+            const currentIndexes = this.collection?.getIndexMetadata() ?? [];
+            const completedIndexes = await this.bootstrapPersistedIndexes(
+              currentIndexes,
+              this.persistence.adapter
+            );
+            await this.requestCoordinatorPersistedIndexes(
+              currentIndexes,
+              completedIndexes
+            );
+          }
+        }
+      });
+      this.throwIfLifecycleReplaced(lifecycleGeneration);
+      resolveCacheRotated?.();
+      await sourceRestart;
+      if (recoverySequence === this.scopedRecoverySequence && this.cacheGenerationClaim) {
+        this.scheduleCacheClaimRenewal(this.cacheGenerationClaim);
+      }
+      if (recoverySequence !== this.scopedRecoverySequence) return;
+      for (const options of this.activeSubsets.values()) {
+        if (options.signal?.aborted) continue;
+        const rotatedOptions = this.rotatedAcquisitions.get(options);
+        if (rotatedOptions) {
+          const ensure = this.persistence.coordinator.requestEnsureRemoteSubset(
+            this.storageCollectionId,
+            rotatedOptions
+          );
+          this.rotatedEnsures.set(options, ensure);
+          void ensure.catch((error) => this.reportSyncError(error));
+        } else {
+          this.refreshScopedSubsets();
+          break;
+        }
+      }
+    } catch (error) {
+      rejectCacheRotated?.(error);
+      throw this.markTerminalFailure(error, lifecycleGeneration);
+    }
+  }
   getResumeGenerationOwner() {
     return this.resumeGenerationOwner;
   }
@@ -745,7 +1241,7 @@ class PersistedCollectionRuntime {
     const baseline = {};
     this.activeSubsets.set(this.getSubsetKey(baseline), baseline);
     const appliedCursor = this.appliedReceiptSequence;
-    await this.hydrateSubsetUnsafe(
+    const hydrated = await this.hydrateSubsetUnsafe(
       baseline,
       {
         lifecycleGeneration,
@@ -753,6 +1249,7 @@ class PersistedCollectionRuntime {
       },
       adapter
     );
+    if (!hydrated) return false;
     return lifecycleGeneration === this.lifecycleGeneration ? appliedCursor : void 0;
   }
   async ensureStartupMetadataLoaded() {
@@ -772,19 +1269,33 @@ class PersistedCollectionRuntime {
       adapter
     );
     if (lifecycleGeneration !== this.lifecycleGeneration) return void 0;
-    onStartupMetadataLoaded();
+    if (!this.cacheGenerationClaim || this.syncMode !== `on-demand`) {
+      onStartupMetadataLoaded();
+    }
     const appliedCursor = this.syncMode !== `on-demand` ? await this.hydrateBaseline(lifecycleGeneration, adapter) : void 0;
     return lifecycleGeneration === this.lifecycleGeneration ? {
-      appliedCursor,
+      appliedCursor: appliedCursor === false ? void 0 : appliedCursor,
       indexBootstrapSnapshot,
       completedLocalIndexSignatures
     } : void 0;
   }
   async loadStartupMetadataInternal(lifecycleGeneration, adapter) {
-    const snapshot = await adapter.loadResumeSnapshot(this.collectionId, {
-      includeRows: false
-    });
-    if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    const claimId = this.cacheGenerationClaim?.claimId;
+    const storageCollectionId = this.storageCollectionId;
+    const snapshot = await adapter.loadResumeSnapshot(
+      this.storageTargetFor(storageCollectionId, claimId),
+      {
+        includeRows: false,
+        cacheGenerationClaimId: claimId
+      }
+    );
+    if (lifecycleGeneration !== this.lifecycleGeneration) return false;
+    if (claimId !== this.cacheGenerationClaim?.claimId) return false;
+    if (storageCollectionId !== this.storageCollectionId) return false;
+    if (claimId && !await this.renewCacheClaim(adapter)) return false;
+    if (lifecycleGeneration !== this.lifecycleGeneration) return false;
+    if (claimId !== this.cacheGenerationClaim?.claimId) return false;
+    if (storageCollectionId !== this.storageCollectionId) return false;
     this.persistedResumeGeneration = this.getResumeSnapshotGeneration(snapshot);
     this.persistedKeySetEvidence = snapshot.keySet;
     this.observeStreamPosition(
@@ -796,36 +1307,42 @@ class PersistedCollectionRuntime {
       snapshot.collectionMetadata
     );
     await whenSyncAccepted(applied);
+    return true;
   }
   async loadCollectionMetadataSnapshot(adapter) {
     if (!adapter.loadCollectionMetadata) {
       return [];
     }
-    return adapter.loadCollectionMetadata(this.collectionId);
+    return adapter.loadCollectionMetadata(this.storageTargetFor(), {
+      cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
+    });
   }
   replaceCollectionMetadataSnapshot(collectionMetadata) {
     if (!this.syncControls.begin || !this.syncControls.commit || !this.syncControls.metadata) {
       return true;
     }
-    const nextMetadata = new Map(
-      collectionMetadata.map(({ key, value }) => [key, value])
-    );
-    const currentKeys = this.syncControls.metadata.collection.list().map(({ key }) => key);
     return this.withInternalApply(() => {
       this.syncControls.begin?.();
-      currentKeys.forEach((key) => {
-        if (!nextMetadata.has(key)) {
-          this.syncControls.metadata?.collection.delete(key);
-        }
-      });
-      nextMetadata.forEach((value, key) => {
-        this.syncControls.metadata?.collection.set(key, value);
-      });
+      this.applyCollectionMetadataSnapshot(collectionMetadata);
       return this.syncControls.commit?.() ?? true;
     });
   }
-  async loadSubset(options, upstreamLoadSubset) {
+  applyCollectionMetadataSnapshot(collectionMetadata) {
+    const metadata = this.syncControls.metadata;
+    if (!metadata) return;
+    const next = new Map(
+      collectionMetadata.map(({ key, value }) => [key, value])
+    );
+    for (const { key } of metadata.collection.list()) {
+      if (!next.has(key)) metadata.collection.delete(key);
+    }
+    for (const [key, value] of next) metadata.collection.set(key, value);
+  }
+  async loadSubset(options, upstreamLoadSubset, onHydrationStarted, isDemandRetained) {
     this.throwIfTerminal();
+    await this.ensureCacheClaimActive();
+    if (options.signal?.aborted || isDemandRetained && !isDemandRetained())
+      return;
     const lifecycleGeneration = this.lifecycleGeneration;
     const subsetKey = this.getSubsetKey(options);
     const truncateGeneration = this.sourceTruncateGeneration;
@@ -834,25 +1351,52 @@ class PersistedCollectionRuntime {
     this.activeSubsets.set(subsetKey, options);
     const appliedCursor = this.appliedReceiptSequence;
     try {
-      await this.applyMutex.run(async () => {
-        try {
-          await this.runInHydrationScope(
-            (adapter) => this.hydrateSubsetUnsafe(
-              options,
-              {
-                lifecycleGeneration,
-                requestLocalLoadFailure: true,
-                rejectBufferedReplayFailure: true
-              },
-              adapter
-            )
-          );
-        } finally {
-          if (lifecycleGeneration === this.lifecycleGeneration && !this.getCurrentTerminalFailure()) {
-            await this.flushQueuedTxCommittedUnsafe();
+      const hydrated = await this.applyMutex.run(
+        async () => {
+          if (options.signal?.aborted) return `aborted`;
+          try {
+            return await this.runInHydrationScope(
+              (adapter) => {
+                if (options.signal?.aborted) {
+                  return Promise.resolve(`aborted`);
+                }
+                onHydrationStarted?.();
+                return this.hydrateSubsetUnsafe(
+                  options,
+                  {
+                    lifecycleGeneration,
+                    requestLocalLoadFailure: true,
+                    rejectBufferedReplayFailure: true
+                  },
+                  adapter
+                );
+              }
+            );
+          } finally {
+            if (lifecycleGeneration === this.lifecycleGeneration && !this.getCurrentTerminalFailure()) {
+              await this.flushQueuedTxCommittedUnsafe();
+            }
           }
         }
-      });
+      );
+      if (hydrated === `aborted`) {
+        if (this.activeSubsets.get(subsetKey) === options) {
+          this.activeSubsets.delete(subsetKey);
+        }
+        return;
+      }
+      if (!hydrated) {
+        await this.ensureCacheClaimActive();
+        const rotatedOptions = this.rotatedAcquisitions.get(options);
+        if (rotatedOptions && this.activeSubsets.get(subsetKey) === options && !options.signal?.aborted) {
+          await (this.rotatedEnsures.get(options) ?? this.persistence.coordinator.requestEnsureRemoteSubset(
+            this.storageCollectionId,
+            rotatedOptions
+          ));
+          await this.applyLeaderCommitsBeforeReply(options);
+        }
+        return;
+      }
       if (lifecycleGeneration !== this.lifecycleGeneration) return;
       await this.waitForAppliedReceiptsAfter(appliedCursor);
       if (!routeRemoteDemandDuringHydration && this.canRouteRemoteDemandThroughCoordinator()) {
@@ -865,13 +1409,16 @@ class PersistedCollectionRuntime {
       throw error;
     }
     if (options.signal?.aborted || this.activeSubsets.get(this.getSubsetKey(options)) !== options) {
+      if (options.signal?.aborted && this.activeSubsets.get(subsetKey) === options) {
+        this.activeSubsets.delete(subsetKey);
+      }
       return;
     }
     if (this.canRouteRemoteDemandThroughCoordinator()) {
       try {
         await this.persistence.coordinator.requestEnsureRemoteSubset(
-          this.collectionId,
-          options
+          this.storageCollectionId,
+          this.rotatedAcquisitions.get(options) ?? options
         );
       } catch (error) {
         if (options.signal?.aborted || typeof error === `object` && error !== null && `name` in error && error.name === `AbortError`) {
@@ -881,6 +1428,7 @@ class PersistedCollectionRuntime {
         this.queueRemoteSubsetEnsure(options);
         throw error;
       }
+      await this.applyLeaderCommitsBeforeReply(options);
       return;
     }
     if (truncateGeneration === this.sourceTruncateGeneration && this.activeSubsets.get(subsetKey) === options) {
@@ -898,7 +1446,7 @@ class PersistedCollectionRuntime {
   loadHydratedSubset(options, upstreamLoadSubset) {
     const failure = this.getCurrentTerminalFailure();
     if (failure) return Promise.reject(failure.error);
-    if (!this.startupSettled || this.isHydratingNow() || this.canRouteRemoteDemandThroughCoordinator() || options.refetch === true || !this.hydratedDemands.has(getLoadSubsetDemandKey(options))) {
+    if (this.hasExpiredCacheClaim() || !this.startupSettled || this.isHydratingNow() || this.canRouteRemoteDemandThroughCoordinator() || options.refetch === true || !this.hydratedDemands.has(getLoadSubsetDemandKey(options))) {
       return;
     }
     this.activeSubsets.set(this.getSubsetKey(options), options);
@@ -938,13 +1486,15 @@ class PersistedCollectionRuntime {
     const subsetKey = this.getSubsetKey(options);
     this.activeSubsets.delete(subsetKey);
     this.pendingRemoteSubsetEnsures.delete(subsetKey);
+    const remoteOptions = this.rotatedAcquisitions.get(options) ?? options;
+    this.rotatedAcquisitions.delete(options);
     const demandKey = getLoadSubsetDemandKey(options);
     const stillActive = Array.from(this.activeSubsets.values()).some(
       (active) => getLoadSubsetDemandKey(active) === demandKey
     );
     if (!stillActive) this.hydratedDemands.delete(demandKey);
     if (this.mode === `sync-present`) {
-      void this.persistence.coordinator.requestReleaseRemoteSubset(this.collectionId, options).catch((error) => {
+      void this.persistence.coordinator.requestReleaseRemoteSubset(this.storageCollectionId, remoteOptions).catch((error) => {
         this.reportSyncError(error);
       });
     }
@@ -961,9 +1511,10 @@ class PersistedCollectionRuntime {
   }
   async forceReloadSubset(options) {
     this.throwIfTerminal();
+    await this.ensureCacheClaimActive();
     const lifecycleGeneration = this.lifecycleGeneration;
-    await this.applyMutex.run(async () => {
-      await this.runInHydrationScope(
+    const hydrated = await this.applyMutex.run(async () => {
+      const result = await this.runInHydrationScope(
         (adapter) => this.hydrateSubsetUnsafe(
           options,
           {
@@ -976,7 +1527,9 @@ class PersistedCollectionRuntime {
       if (lifecycleGeneration === this.lifecycleGeneration) {
         await this.flushQueuedTxCommittedUnsafe();
       }
+      return result;
     });
+    if (!hydrated) await this.ensureCacheClaimActive();
   }
   queueHydrationBufferedTransaction(transaction) {
     const failure = this.getCurrentTerminalFailure();
@@ -984,11 +1537,13 @@ class PersistedCollectionRuntime {
       transaction.rejectApplied?.(failure.error);
       return;
     }
+    transaction.admittedStorageCollectionId = this.storageCollectionId;
     this.queuedHydrationTransactions.push(transaction);
   }
   applyHydrationBufferedTransaction(transaction) {
     const failure = this.getCurrentTerminalFailure();
     if (failure) return Promise.reject(failure.error);
+    transaction.admittedStorageCollectionId = this.storageCollectionId;
     return this.applyMutex.run(async () => {
       await this.applyBufferedSyncTransactionUnsafe(transaction);
     });
@@ -1093,7 +1648,10 @@ class PersistedCollectionRuntime {
       for (const options of this.activeSubsets.values()) {
         attempt(() => {
           remoteReleases.push(
-            this.persistence.coordinator.requestReleaseRemoteSubset(this.collectionId, options).catch((error) => {
+            this.persistence.coordinator.requestReleaseRemoteSubset(
+              this.storageCollectionId,
+              this.rotatedAcquisitions.get(options) ?? options
+            ).catch((error) => {
               this.reportSyncError(error);
             })
           );
@@ -1104,6 +1662,7 @@ class PersistedCollectionRuntime {
     this.coordinatorUnsubscribe = null;
     attempt(() => this.remoteSubsetOwnerUnsubscribe?.());
     this.remoteSubsetOwnerUnsubscribe = null;
+    this.remoteSubsetOwner = void 0;
     attempt(() => this.indexAddedUnsubscribe?.());
     this.indexAddedUnsubscribe = null;
     attempt(() => this.indexRemovedUnsubscribe?.());
@@ -1113,6 +1672,16 @@ class PersistedCollectionRuntime {
       this.remoteEnsureRetryTimer = null;
     }
     this.pendingRemoteSubsetEnsures.clear();
+    this.rotatedAcquisitions.clear();
+    for (const [options, storageId] of this.scopedRefreshes) {
+      remoteReleases.push(
+        this.persistence.coordinator.requestReleaseRemoteSubset(
+          storageId,
+          options
+        )
+      );
+    }
+    this.scopedRefreshes.clear();
     this.activeSubsets.clear();
     this.hydratedDemands.clear();
     for (const transaction of this.queuedHydrationTransactions) {
@@ -1122,6 +1691,15 @@ class PersistedCollectionRuntime {
     this.queuedTxCommitted.length = 0;
     this.clearSyncControls();
     this.collection = null;
+    const claim = this.cacheGenerationClaim;
+    this.cacheGenerationClaim = void 0;
+    this.clearCacheClaimRenewal();
+    this.cacheClaimRecovery = null;
+    if (claim && this.persistence.adapter.releaseCacheGenerationClaim) {
+      remoteReleases.push(
+        this.persistence.adapter.releaseCacheGenerationClaim(claim.claimId)
+      );
+    }
     return Promise.all(remoteReleases).then(() => {
       if (failures.length === 1) throw failures[0];
       if (failures.length > 1) {
@@ -1133,6 +1711,12 @@ class PersistedCollectionRuntime {
   }
   advanceLifecycle() {
     this.lifecycleGeneration++;
+    this.clearCacheClaimRenewal();
+    this.cacheClaimRecovery = null;
+    this.scopedRecovery = false;
+    this.scopedRecoveryPending = false;
+    this.scopedRecoverySequence++;
+    this.recoverQueuedAfterLocalLoadFailure = false;
     this.persistedReadiness?.set({ status: `loading` });
     this.startupSettled = false;
     this.publicRowVersion = 0;
@@ -1162,22 +1746,40 @@ class PersistedCollectionRuntime {
     return this.collection.getIndexMetadata().map((metadata) => metadata.signature);
   }
   loadSubsetRowsUnsafe(options, adapter) {
-    return adapter.loadSubset(this.collectionId, options, {
-      requiredIndexSignatures: this.getRequiredIndexSignatures()
+    if (this.scopedRecovery) return Promise.resolve([]);
+    return adapter.loadSubset(this.storageTargetFor(), options, {
+      requiredIndexSignatures: this.getRequiredIndexSignatures(),
+      cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
     });
   }
   async scanPersistedRowsUnsafe(options) {
     if (!this.persistence.adapter.scanRows) {
       return [];
     }
-    return this.persistence.adapter.scanRows(
-      this.collectionId,
-      options
-    );
+    return this.persistence.adapter.scanRows(this.storageTargetFor(), options, {
+      cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
+    });
   }
   async scanPersistedRows(options) {
-    this.throwIfTerminal();
-    return this.applyMutex.run(() => this.scanPersistedRowsUnsafe(options));
+    for (; ; ) {
+      this.throwIfTerminal();
+      await this.ensureCacheClaimActive();
+      const claimId = this.cacheGenerationClaim?.claimId;
+      const storageCollectionId = this.storageCollectionId;
+      const rows = await this.applyMutex.run(
+        () => this.scanPersistedRowsUnsafe(options)
+      );
+      if (this.scopedRecoveryPending) {
+        throw new SyncTransactionAbortedError();
+      }
+      if (claimId !== this.cacheGenerationClaim?.claimId || storageCollectionId !== this.storageCollectionId) {
+        continue;
+      }
+      if (claimId && !await this.renewCacheClaim(this.persistence.adapter)) {
+        continue;
+      }
+      return rows;
+    }
   }
   async hydrateSubsetUnsafe(options, config, adapter) {
     let rowsLoaded = false;
@@ -1192,27 +1794,41 @@ class PersistedCollectionRuntime {
       this.hydratingGeneration = config.lifecycleGeneration;
       try {
         let rows;
-        if (config.bindKeySetEvidence) {
-          const snapshot = await adapter.loadResumeSnapshot(this.collectionId, {
-            requiredIndexSignatures: this.getRequiredIndexSignatures(),
-            includeRows: true
-          });
+        let bindResumeSnapshot;
+        if (config.bindKeySetEvidence && !this.scopedRecovery) {
+          const snapshot = await adapter.loadResumeSnapshot(
+            this.storageTargetFor(),
+            {
+              requiredIndexSignatures: this.getRequiredIndexSignatures(),
+              includeRows: true,
+              cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
+            }
+          );
           rows = snapshot.rows;
-          if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
-          if (resetSequence !== this.resetSequence) return;
-          this.bindResumeSnapshotEvidence(snapshot);
+          if (config.lifecycleGeneration !== this.lifecycleGeneration)
+            return true;
+          if (resetSequence !== this.resetSequence) return true;
+          bindResumeSnapshot = () => this.bindResumeSnapshotEvidence(snapshot);
           boundRowVersion = snapshot.latestRowVersion;
         } else {
           rows = await this.loadSubsetRowsUnsafe(options, adapter);
         }
+        const complete = this.syncMode === `on-demand` && !this.scopedRecovery && options.where === void 0 && options.limit === void 0 && options.offset === void 0 && options.cursor === void 0;
+        const validationRows = complete ? rows : void 0;
         rowsLoaded = true;
-        if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
-        if (resetSequence !== this.resetSequence) return;
+        if (config.lifecycleGeneration !== this.lifecycleGeneration) return true;
+        if (resetSequence !== this.resetSequence) return true;
+        if (this.cacheGenerationClaim && !await this.renewCacheClaim(adapter)) {
+          return false;
+        }
+        if (config.lifecycleGeneration !== this.lifecycleGeneration) return true;
+        if (resetSequence !== this.resetSequence) return true;
+        bindResumeSnapshot?.();
         if (!config.bindKeySetEvidence || this.persistedKeySetEvidence?.status !== `incompatible`) {
           for (const row of rows) {
             hydrationContext.suppliedRowKeys.add(row.key);
           }
-          const applied = this.applyRowsToCollection(rows);
+          const applied = this.applyRowsToCollection(rows, validationRows);
           await whenSyncAccepted(applied);
           if (boundRowVersion !== void 0) {
             this.publicRowVersion = Math.max(
@@ -1226,11 +1842,20 @@ class PersistedCollectionRuntime {
           this.hydratingGeneration = null;
         }
       }
-      if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
-      replayFailure = await this.flushQueuedHydrationTransactionsUnsafe(adapter);
-      if (config.lifecycleGeneration !== this.lifecycleGeneration) return;
+      if (config.lifecycleGeneration !== this.lifecycleGeneration) return true;
+      if (!this.scopedRecoveryPending) {
+        replayFailure = await this.flushQueuedHydrationTransactionsUnsafe(adapter);
+      }
+      if (config.lifecycleGeneration !== this.lifecycleGeneration) return true;
     } catch (error) {
+      if (config.requestLocalLoadFailure && !rowsLoaded && this.cacheGenerationClaim && this.hasExpiredCacheClaim()) {
+        return false;
+      }
       if (config.requestLocalLoadFailure && !rowsLoaded) {
+        if (this.scopedRecoveryPending) {
+          this.recoverQueuedAfterLocalLoadFailure = true;
+          throw error;
+        }
         this.hydratingGeneration = config.lifecycleGeneration;
         try {
           await this.recoverBufferedTransactionsAfterLocalLoadFailureUnsafe(
@@ -1259,6 +1884,7 @@ class PersistedCollectionRuntime {
     if (replayFailure && config.rejectBufferedReplayFailure) {
       throw replayFailure.reason;
     }
+    return true;
   }
   async recoverBufferedTransactionsAfterLocalLoadFailureUnsafe(lifecycleGeneration, adapter) {
     let snapshotRows;
@@ -1293,18 +1919,15 @@ class PersistedCollectionRuntime {
             const key = operation.key;
             if (operation.type === `update` && transaction.partialUpdateOperationIndexes.has(index) && getPresence(key) === `unknown`) {
               if (snapshotRows === void 0) {
-                const snapshot = await adapter.loadResumeSnapshot(
-                  this.collectionId,
-                  {
-                    requiredIndexSignatures: this.getRequiredIndexSignatures(),
-                    includeRows: true
-                  }
-                );
+                const snapshot = this.scopedRecovery ? void 0 : await adapter.loadResumeSnapshot(this.storageTargetFor(), {
+                  requiredIndexSignatures: this.getRequiredIndexSignatures(),
+                  includeRows: true,
+                  cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
+                });
                 this.throwIfLifecycleReplaced(lifecycleGeneration);
                 if (transaction.signal?.aborted) break;
-                snapshotRows = new Map(
-                  snapshot.rows.map((row) => [row.key, row])
-                );
+                const rows = snapshot && !this.scopedRecovery ? snapshot.rows : [];
+                snapshotRows = new Map(rows.map((row) => [row.key, row]));
               }
               const baseline = snapshotRows.get(key);
               if (baseline === void 0) {
@@ -1354,22 +1977,65 @@ class PersistedCollectionRuntime {
     }
     this.queuedHydrationTransactions.length = 0;
   }
-  applyRowsToCollection(rows) {
+  applyRowsToCollection(rows, validationRows, collectionMetadata) {
     if (!this.syncControls.begin || !this.syncControls.write || !this.syncControls.commit) {
       return true;
     }
     return this.withInternalApply(() => {
       this.syncControls.begin?.();
+      if (validationRows) {
+        const durableRows = new Map(validationRows.map((row) => [row.key, row]));
+        for (const key of this.collection?.base.keys() ?? []) {
+          if (this.collection?._hasHydratedKey(key)) continue;
+          const durable = durableRows.get(key);
+          if (!durable) {
+            this.syncControls.write?.({ type: `delete`, key });
+          } else {
+            const valueChanged = !equalPersistedSnapshotValues(
+              this.collection?.base.get(key),
+              durable.value
+            );
+            const metadataChanged = !equalPersistedSnapshotValues(
+              this.syncControls.metadata?.row.get(key),
+              durable.metadata
+            );
+            if (valueChanged || metadataChanged && durable.metadata !== void 0) {
+              if (valueChanged) {
+                this.syncControls.write?.({ type: `delete`, key });
+              }
+              this.syncControls.write?.({
+                type: `update`,
+                value: durable.value,
+                metadata: durable.metadata
+              });
+            }
+            if (metadataChanged && durable.metadata === void 0) {
+              this.syncControls.metadata?.row.delete(key);
+            }
+          }
+        }
+        for (const key of this.collection?._syncedRowMetadataKeysOutsideBase() ?? []) {
+          this.syncControls.metadata?.row.delete(key);
+        }
+      }
       for (const row of rows) {
-        if (this.collection?._hasHydratedKey(row.key)) {
+        if (validationRows && this.collection?.base.has(row.key) || this.collection?._hasHydratedKey(row.key)) {
           continue;
         }
+        if (this.collection?.base.has(row.key) && !equalPersistedSnapshotValues(
+          this.collection.base.get(row.key),
+          row.value
+        )) {
+          this.syncControls.write?.({ type: `delete`, key: row.key });
+        }
         this.syncControls.write?.({
           type: `update`,
           value: row.value,
           metadata: row.metadata
         });
       }
+      if (collectionMetadata)
+        this.applyCollectionMetadataSnapshot(collectionMetadata);
       return this.syncControls.commit?.() ?? true;
     });
   }
@@ -1398,32 +2064,45 @@ class PersistedCollectionRuntime {
     );
     this.persistedKeySetEvidence = this.isExpectedResumeGeneration(generation) || mayAcceptUnownedGeneration ? snapshot.keySet : { status: `incompatible` };
   }
-  replaceCollectionSnapshot(rows, collectionMetadata) {
+  replaceCollectionSnapshot(rows, collectionMetadata, replayDemand) {
     if (!this.syncControls.begin || !this.syncControls.write || !this.syncControls.commit || !this.syncControls.metadata) {
       return true;
     }
-    const nextMetadata = new Map(
-      collectionMetadata.map(({ key, value }) => [key, value])
+    const base = this.collection?.base;
+    const hydratedKeys = new Set(
+      Array.from(base?.keys() ?? []).filter(
+        (key) => this.collection?._hasHydratedKey(key) === true
+      )
     );
-    const currentKeys = this.syncControls.metadata.collection.list().map(({ key }) => key);
+    const rowKeys = new Set(rows.map((row) => row.key));
+    const followsLeader = this.canRouteRemoteDemandThroughCoordinator() && !this.persistence.coordinator.isLeader(this.storageCollectionId);
+    const truncate = hydratedKeys.size === 0 && (replayDemand || !followsLeader);
     return this.withInternalApply(() => {
       this.syncControls.begin?.();
-      this.syncControls.truncate?.();
+      if (truncate) {
+        this.syncControls.truncate?.();
+      } else {
+        for (const key of base?.keys() ?? []) {
+          if (!hydratedKeys.has(key) && !rowKeys.has(key)) {
+            this.syncControls.write?.({ type: `delete`, key });
+          }
+        }
+        for (const key of this.collection?._syncedRowMetadataKeysOutsideBase() ?? []) {
+          this.syncControls.metadata?.row.delete(key);
+        }
+      }
       for (const row of rows) {
+        if (hydratedKeys.has(row.key)) continue;
+        if (!truncate && base?.has(row.key)) {
+          this.syncControls.write?.({ type: `delete`, key: row.key });
+        }
         this.syncControls.write?.({
           type: `update`,
           value: row.value,
           metadata: row.metadata
         });
       }
-      currentKeys.forEach((key) => {
-        if (!nextMetadata.has(key)) {
-          this.syncControls.metadata?.collection.delete(key);
-        }
-      });
-      nextMetadata.forEach((value, key) => {
-        this.syncControls.metadata?.collection.set(key, value);
-      });
+      this.applyCollectionMetadataSnapshot(collectionMetadata);
       return this.syncControls.commit?.() ?? true;
     });
   }
@@ -1475,6 +2154,31 @@ class PersistedCollectionRuntime {
   async applyBufferedSyncTransactionUnsafe(transaction, scopedAdapter) {
     this.throwIfTerminal();
     this.throwIfLifecycleReplaced(transaction.lifecycleGeneration);
+    if (transaction.admittedStorageCollectionId !== void 0 && transaction.admittedStorageCollectionId !== this.storageCollectionId) {
+      const error = new SyncTransactionAbortedError();
+      if (!transaction.rejectApplied) throw error;
+      transaction.rejectApplied(error);
+      return { applied: false };
+    }
+    if (!transaction.internal && this.scopedRecoveryPending) {
+      const error = new SyncTransactionAbortedError();
+      if (!transaction.rejectApplied) throw error;
+      transaction.rejectApplied(error);
+      return { applied: false };
+    }
+    if (!transaction.internal && this.cacheGenerationClaim && (scopedAdapter ?? this.persistence.adapter).renewCacheGenerationClaim && !await this.renewCacheClaim(scopedAdapter ?? this.persistence.adapter)) {
+      const error = new SyncTransactionAbortedError();
+      queueMicrotask(() => {
+        if (transaction.lifecycleGeneration !== this.lifecycleGeneration) return;
+        if (this.scopedRecoveryPending) return;
+        void this.startScopedRecovery().catch((failure) => {
+          this.markTerminalFailure(failure, transaction.lifecycleGeneration);
+        });
+      });
+      if (!transaction.rejectApplied) throw error;
+      transaction.rejectApplied(error);
+      return { applied: false };
+    }
     const abortedBeforeApplication = transaction.signal?.aborted === true;
     let abortedDuringApplication = false;
     let applicationReturned = false;
@@ -1538,10 +2242,11 @@ class PersistedCollectionRuntime {
     };
     const streamPosition = this.nextLocalStreamPosition();
     const tx = this.createPersistedTxFromOperations(transaction, streamPosition);
+    const storageCollectionId = this.storageCollectionId;
     let response;
     try {
       response = await this.persistence.coordinator.requestApplyCommittedTx(
-        this.collectionId,
+        storageCollectionId,
         tx,
         // A hydration-scoped adapter is already inside the shared scheduler.
         // Ordinary source commits enter it before taking the writer lock.
@@ -1554,7 +2259,7 @@ class PersistedCollectionRuntime {
       let reconciled;
       try {
         reconciled = await this.persistence.coordinator.reconcileCommittedTx(
-          this.collectionId,
+          storageCollectionId,
           tx,
           anchor,
           scopedAdapter
@@ -1622,7 +2327,10 @@ class PersistedCollectionRuntime {
     this.throwIfTerminal();
     this.throwIfLifecycleReplaced(lifecycleGeneration);
     try {
-      await this.persistence.adapter.applyCommittedTx(this.collectionId, tx);
+      await this.persistence.adapter.applyCommittedTx(
+        this.storageTargetFor(),
+        tx
+      );
     } catch (error) {
       throw this.markTerminalFailure(
         toPersistedCollectionDurabilityError(this.collectionId, error),
@@ -1637,6 +2345,7 @@ class PersistedCollectionRuntime {
       term: streamPosition.term,
       seq: streamPosition.seq,
       rowVersion: streamPosition.rowVersion,
+      cacheGenerationClaimId: this.cacheGenerationClaim?.claimId,
       truncate: transaction.truncate,
       mutations: transaction.operations.map(
         (operation) => operation.type === `update` ? {
@@ -1671,6 +2380,7 @@ class PersistedCollectionRuntime {
       term: streamPosition.term,
       seq: streamPosition.seq,
       rowVersion: streamPosition.rowVersion,
+      cacheGenerationClaimId: this.cacheGenerationClaim?.claimId,
       mutations: mutations.map((mutation) => {
         if (mutation.type === `delete`) {
           return {
@@ -1730,14 +2440,16 @@ class PersistedCollectionRuntime {
   async persistCollectionMutationsUnsafe(mutations, lifecycleGeneration) {
     this.throwIfLifecycleReplaced(lifecycleGeneration);
     if (this.persistence.coordinator.requestApplyLocalMutations) {
+      const target = this.storageTargetFor();
       const envelopeMutations = mutations.map(
         (mutation) => toPersistedMutationEnvelope(
           mutation
         )
       );
       const response = await this.persistence.coordinator.requestApplyLocalMutations(
-        this.collectionId,
-        envelopeMutations
+        this.storageCollectionId,
+        envelopeMutations,
+        target.kind === `managed` ? target.claimId : void 0
       );
       this.throwIfLifecycleReplaced(lifecycleGeneration);
       if (!response.ok) {
@@ -1834,12 +2546,12 @@ class PersistedCollectionRuntime {
     const envelope = {
       v: 1,
       dbName: this.dbName,
-      collectionId: this.collectionId,
+      collectionId: this.storageCollectionId,
       senderId: this.persistence.coordinator.getNodeId(),
       ts: Date.now(),
       payload: txCommitted
     };
-    this.persistence.coordinator.publish(this.collectionId, envelope);
+    this.persistence.coordinator.publish(this.storageCollectionId, envelope);
   }
   observeStreamPosition(term, seq, rowVersion) {
     if (term > this.latestTerm || term === this.latestTerm && seq > this.latestSeq) {
@@ -1881,7 +2593,7 @@ class PersistedCollectionRuntime {
     if (this.getCurrentTerminalFailure() || this.mode !== `sync-present` || this.persistence.coordinator instanceof SingleProcessCoordinator) {
       return false;
     }
-    return !this.persistence.coordinator.isLeader(this.collectionId) || this.remoteSubsetOwnerUnsubscribe !== null;
+    return !this.persistence.coordinator.isLeader(this.storageCollectionId) || this.remoteSubsetOwnerUnsubscribe !== null;
   }
   queueRemoteSubsetEnsure(options) {
     if (options.signal?.aborted || !this.canRouteRemoteDemandThroughCoordinator() || this.activeSubsets.get(this.getSubsetKey(options)) !== options) {
@@ -1920,8 +2632,8 @@ class PersistedCollectionRuntime {
       }
       try {
         await this.persistence.coordinator.requestEnsureRemoteSubset(
-          this.collectionId,
-          options
+          this.storageCollectionId,
+          this.rotatedAcquisitions.get(options) ?? options
         );
         this.pendingRemoteSubsetEnsures.delete(subsetKey);
       } catch (error) {
@@ -1939,18 +2651,19 @@ class PersistedCollectionRuntime {
       return;
     }
     this.persistence.coordinator.setAdapterForCollection?.(
-      this.collectionId,
-      this.persistence.adapter
+      this.storageCollectionId,
+      this.persistence.adapter,
+      this.cacheGenerationClaim?.claimId
     );
     this.coordinatorUnsubscribe = this.persistence.coordinator.subscribe(
-      this.collectionId,
+      this.storageCollectionId,
       (message) => {
         this.onCoordinatorMessage(message);
       }
     );
   }
   onCoordinatorMessage(message) {
-    if (message.collectionId !== this.collectionId) {
+    if (message.collectionId !== this.storageCollectionId) {
       return;
     }
     if (this.getCurrentTerminalFailure()) {
@@ -1959,17 +2672,24 @@ class PersistedCollectionRuntime {
     const { payload } = message;
     const lifecycleGeneration = this.lifecycleGeneration;
     const isSelf = message.senderId === this.persistence.coordinator.getNodeId();
+    const claimExpired = this.hasExpiredCacheClaim();
+    if (claimExpired && !isTxCommittedPayload(payload)) {
+      this.scheduleCacheClaimRecovery(lifecycleGeneration);
+      return;
+    }
     if (isTxCommittedPayload(payload)) {
-      if (this.isHydratingNow()) {
-        this.queuedTxCommitted.push({
-          txCommitted: payload,
-          lifecycleGeneration
+      this.queuedTxCommitted.push({
+        txCommitted: payload,
+        lifecycleGeneration,
+        storageCollectionId: message.collectionId
+      });
+      if (claimExpired) {
+        this.scheduleCacheClaimRecovery(lifecycleGeneration);
+      } else if (!this.isHydratingNow()) {
+        void this.applyMutex.run(() => this.flushQueuedTxCommittedUnsafe()).catch((error) => {
+          this.markTerminalFailure(error, lifecycleGeneration);
         });
-        return;
       }
-      void this.applyMutex.run(() => this.processCommittedTxUnsafe(payload, lifecycleGeneration)).catch((error) => {
-        this.markTerminalFailure(error, lifecycleGeneration);
-      });
       return;
     }
     if (isSelf) {
@@ -1977,6 +2697,7 @@ class PersistedCollectionRuntime {
     }
     if (isCollectionResetPayload(payload)) {
       void this.applyMutex.run(async () => {
+        if (message.collectionId !== this.storageCollectionId) return;
         await this.runInHydrationScope(async (adapter) => {
           await this.truncateAndReloadUnsafe(adapter, lifecycleGeneration);
           await this.rebaseDurableStreamFromSnapshotUnsafe(
@@ -1998,14 +2719,23 @@ class PersistedCollectionRuntime {
   }
   async flushQueuedTxCommittedUnsafe() {
     while (this.queuedTxCommitted.length > 0) {
+      if (this.hasExpiredCacheClaim()) {
+        this.scheduleCacheClaimRecovery(this.lifecycleGeneration);
+        return;
+      }
       const queued = this.queuedTxCommitted.shift();
       if (!queued) {
         continue;
       }
-      await this.processCommittedTxUnsafe(
-        queued.txCommitted,
-        queued.lifecycleGeneration
-      );
+      if (queued.storageCollectionId !== this.storageCollectionId) continue;
+      try {
+        await this.processCommittedTxUnsafe(
+          queued.txCommitted,
+          queued.lifecycleGeneration
+        );
+      } catch (error) {
+        throw this.markTerminalFailure(error, queued.lifecycleGeneration);
+      }
     }
   }
   async processCommittedTxUnsafe(txCommitted, lifecycleGeneration = this.lifecycleGeneration) {
@@ -2043,7 +2773,7 @@ class PersistedCollectionRuntime {
     const hasGapAcrossTerms = txCommitted.term > this.latestTerm && txCommitted.seq > 1;
     const hasGap = observedButUnpublished || txCommitted.latestRowVersion > this.publicRowVersion + 1 || hasGapInCurrentTerm || hasGapAcrossTerms;
     if (hasGap) {
-      await this.recoverFromSeqGapUnsafe(lifecycleGeneration);
+      if (!await this.recoverFromSeqGapUnsafe(lifecycleGeneration)) return;
       if (lifecycleGeneration !== this.lifecycleGeneration) return;
       if (txCommitted.latestRowVersion <= this.publicRowVersion) return;
     }
@@ -2066,8 +2796,9 @@ class PersistedCollectionRuntime {
   }
   async rebaseDurableStreamFromSnapshotUnsafe(adapter, lifecycleGeneration) {
     if (lifecycleGeneration !== this.lifecycleGeneration) return;
-    const snapshot = await adapter.loadResumeSnapshot(this.collectionId, {
-      includeRows: false
+    const snapshot = await adapter.loadResumeSnapshot(this.storageTargetFor(), {
+      includeRows: false,
+      cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
     });
     if (lifecycleGeneration !== this.lifecycleGeneration) return;
     this.latestRowVersion = snapshot.latestRowVersion;
@@ -2079,19 +2810,26 @@ class PersistedCollectionRuntime {
     );
   }
   async recoverFromSeqGapUnsafe(lifecycleGeneration) {
-    if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    if (lifecycleGeneration !== this.lifecycleGeneration) return false;
     if (this.persistence.coordinator.pullSince && this.latestRowVersion >= 0) {
       let pullResponse;
       try {
         pullResponse = await this.persistence.coordinator.pullSince(
-          this.collectionId,
-          this.publicRowVersion
+          this.storageCollectionId,
+          this.publicRowVersion,
+          void 0,
+          this.cacheGenerationClaim?.claimId
         );
       } catch (error) {
         console.warn(`Failed pullSince recovery attempt:`, error);
       }
+      if (this.scopedRecoveryPending) return false;
+      if (this.cacheGenerationClaim && !await this.renewCacheClaim(this.persistence.adapter)) {
+        this.scheduleCacheClaimRecovery(lifecycleGeneration);
+        return false;
+      }
       if (pullResponse) {
-        if (lifecycleGeneration !== this.lifecycleGeneration) return;
+        if (lifecycleGeneration !== this.lifecycleGeneration) return false;
         if (pullResponse.ok) {
           this.observeStreamPosition(
             pullResponse.latestTerm,
@@ -2106,7 +2844,7 @@ class PersistedCollectionRuntime {
               this.publicRowVersion,
               pullResponse.latestRowVersion
             );
-            return;
+            return true;
           }
           const deltas = pullResponse.deltas;
           if (!deltas) {
@@ -2117,7 +2855,7 @@ class PersistedCollectionRuntime {
               this.publicRowVersion,
               pullResponse.latestRowVersion
             );
-            return;
+            return true;
           }
           await this.runInHydrationScope(async (adapter) => {
             for (const delta of deltas) {
@@ -2144,11 +2882,11 @@ class PersistedCollectionRuntime {
             this.publicRowVersion,
             pullResponse.latestRowVersion
           );
-          return;
+          return true;
         }
       }
     }
-    if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    if (lifecycleGeneration !== this.lifecycleGeneration) return false;
     await this.runInHydrationScope(
       (adapter) => this.reloadActiveSubsetsUnsafe(adapter)
     );
@@ -2161,12 +2899,48 @@ class PersistedCollectionRuntime {
         this.queueRemoteSubsetEnsure(options);
       }
     }
+    return true;
+  }
+  refreshScopedSubsets() {
+    if (!this.remoteSubsetOwner) return;
+    const lifecycleGeneration = this.lifecycleGeneration;
+    const storageId = this.storageCollectionId;
+    for (const [subsetKey, options] of this.activeSubsets) {
+      if (options.signal?.aborted) continue;
+      this.hydratedDemands.delete(getLoadSubsetDemandKey(options));
+      const refreshOptions = { ...options, refetch: true };
+      this.scopedRefreshes.set(refreshOptions, storageId);
+      void Promise.resolve().then(() => {
+        if (lifecycleGeneration !== this.lifecycleGeneration || this.activeSubsets.get(subsetKey) !== options) {
+          return;
+        }
+        return this.persistence.coordinator.requestEnsureRemoteSubset(
+          storageId,
+          refreshOptions
+        );
+      }).catch((error) => {
+        if (lifecycleGeneration === this.lifecycleGeneration && !options.signal?.aborted) {
+          this.reportSyncError(error);
+        }
+      }).finally(() => {
+        if (!this.scopedRefreshes.delete(refreshOptions)) return;
+        void this.persistence.coordinator.requestReleaseRemoteSubset(storageId, refreshOptions).catch((error) => {
+          if (lifecycleGeneration === this.lifecycleGeneration) {
+            this.reportSyncError(error);
+          }
+        });
+      });
+    }
   }
   async truncateAndReloadUnsafe(adapter, lifecycleGeneration = this.lifecycleGeneration) {
     if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    if (this.scopedRecovery) {
+      this.refreshScopedSubsets();
+      return;
+    }
     this.hydratedDemands.clear();
     this.resetSequence++;
-    if (this.syncControls.begin && this.syncControls.commit) {
+    if (this.syncMode === `eager` && this.syncControls.begin && this.syncControls.commit) {
       const applied = this.withInternalApply(() => {
         this.syncControls.begin?.();
         this.syncControls.truncate?.();
@@ -2175,9 +2949,18 @@ class PersistedCollectionRuntime {
       await whenSyncAccepted(applied);
     }
     if (lifecycleGeneration !== this.lifecycleGeneration) return;
-    await this.reloadActiveSubsetsUnsafe(adapter);
+    await this.reloadActiveSubsetsUnsafe(
+      adapter,
+      false,
+      this.syncMode === `eager`,
+      true
+    );
   }
   async invalidateFromCommittedTxUnsafe(txCommitted, adapter) {
+    if (this.scopedRecovery) {
+      this.refreshScopedSubsets();
+      return;
+    }
     const reloadActiveSubsets = (skipUnchangedReplace = false) => this.runInHydrationScope(
       (scopedAdapter) => this.reloadActiveSubsetsUnsafe(scopedAdapter, skipUnchangedReplace),
       adapter
@@ -2194,6 +2977,21 @@ class PersistedCollectionRuntime {
     const hasPaginatedSubset = Array.from(this.activeSubsets.values()).some(
       (opt) => opt.limit != null || opt.offset != null || opt.cursor != null
     );
+    const changedKeys = new Set(txCommitted.changedRows.map((row) => row.key));
+    const hasRepeatedChange = changedKeys.size !== txCommitted.changedRows.length;
+    const hasChangedAndDeletedKey = txCommitted.deletedKeys.some(
+      (key) => changedKeys.has(key)
+    );
+    const hasChangedPublicKey = txCommitted.changedRows.some(
+      (row) => this.collection?.base.has(row.key)
+    );
+    const hasUnseenDemandedKey = this.activeSubsets.size > 0 && txCommitted.changedRows.some(
+      (row) => !this.collection?.base.has(row.key) && !this.collection?._hasHydratedKey(row.key)
+    );
+    if (hasRepeatedChange || hasChangedAndDeletedKey || hasChangedPublicKey || this.syncMode === `on-demand` && hasUnseenDemandedKey) {
+      await reloadActiveSubsets();
+      return;
+    }
     if (!hasPaginatedSubset || changedKeyCount === 0) {
       await this.applyTargetedInvalidationUnsafe(txCommitted);
       return;
@@ -2210,20 +3008,33 @@ class PersistedCollectionRuntime {
         key: changedKey,
         value: newValue
       } of txCommitted.changedRows) {
-        const matchesAnySubset = subsetEvaluators.some((evaluator) => {
-          if (!evaluator) return true;
-          return toBooleanPredicate(evaluator(newValue));
-        });
-        if (matchesAnySubset) {
-          this.syncControls.write?.({ type: `update`, value: newValue });
-        } else if (this.collection?.get(changedKey) !== void 0) {
-          this.syncControls.write?.({ type: `delete`, key: changedKey });
+        const key = changedKey;
+        if (this.collection?._hasHydratedKey(key)) continue;
+        const previous = this.collection?.base.get(key);
+        if (previous === void 0 && this.activeSubsets.size === 0) continue;
+        const completeValue = {
+          ...previous,
+          ...newValue
+        };
+        const currentlyDemanded = matchesAnySubset(
+          completeValue,
+          subsetEvaluators
+        );
+        const previouslyOutsideDemand = previous !== void 0 && !matchesAnySubset(previous, subsetEvaluators);
+        if (currentlyDemanded || previouslyOutsideDemand) {
+          this.syncControls.write?.({ type: `update`, value: completeValue });
+        } else if (previous !== void 0) {
+          this.syncControls.write?.({ type: `delete`, key });
         }
       }
       for (const deletedKey of txCommitted.deletedKeys) {
-        this.syncControls.write?.({ type: `delete`, key: deletedKey });
+        const key = deletedKey;
+        if (!this.collection?._hasHydratedKey(key)) {
+          this.syncControls.write?.({ type: `delete`, key });
+        }
       }
       txCommitted.rowMetadataMutations?.forEach((mutation) => {
+        if (this.collection?._hasHydratedKey(mutation.key)) return;
         if (mutation.type === `delete`) {
           this.syncControls.metadata?.row.delete(mutation.key);
         } else {
@@ -2247,10 +3058,25 @@ class PersistedCollectionRuntime {
     });
     await whenSyncAccepted(applied);
   }
-  async reloadActiveSubsetsUnsafe(adapter, skipUnchangedReplace = false) {
+  async reloadActiveSubsetsUnsafe(adapter, skipUnchangedReplace = false, restoreResetBaseline = false, replayDemand = false) {
+    if (this.scopedRecovery) {
+      this.refreshScopedSubsets();
+      return;
+    }
     const lifecycleGeneration = this.lifecycleGeneration;
     const truncateGeneration = this.sourceTruncateGeneration;
-    const activeSubsetOptions = this.activeSubsets.size > 0 ? Array.from(this.activeSubsets.values()) : [{}];
+    const activeSubsetOptions = Array.from(this.activeSubsets.values());
+    if (restoreResetBaseline && activeSubsetOptions.length === 0) {
+      activeSubsetOptions.push({});
+    }
+    const evaluators = activeSubsetOptions.map(
+      (options) => options.where ? compileSingleRowExpression(options.where) : null
+    );
+    const outsideDemandKeys = activeSubsetOptions.some(
+      (options) => options.limit != null || options.offset != null || options.cursor != null
+    ) ? [] : Array.from(this.collection?.base ?? []).filter(
+      ([key, row]) => !this.collection?._hasHydratedKey(key) && !matchesAnySubset(row, evaluators)
+    ).map(([key]) => key);
     this.hydratedDemands.clear();
     this.hydrationSequence++;
     const hydrationContext = { suppliedRowKeys: /* @__PURE__ */ new Set() };
@@ -2258,22 +3084,68 @@ class PersistedCollectionRuntime {
     this.hydratingGeneration = lifecycleGeneration;
     try {
       const mergedRows = /* @__PURE__ */ new Map();
-      const collectionMetadata = await this.loadCollectionMetadataSnapshot(adapter);
-      if (lifecycleGeneration !== this.lifecycleGeneration) return;
-      for (const options of activeSubsetOptions) {
-        const subsetRows = await this.loadSubsetRowsUnsafe(options, adapter);
+      let validationSnapshot;
+      let collectionMetadata = [];
+      try {
+        validationSnapshot = (activeSubsetOptions.length === 0 || outsideDemandKeys.length > 0) && this.collection?.base.size ? await adapter.loadResumeSnapshot(this.storageTargetFor(), {
+          requiredIndexSignatures: this.getRequiredIndexSignatures(),
+          includeRows: true,
+          cacheGenerationClaimId: this.cacheGenerationClaim?.claimId
+        }) : void 0;
+        collectionMetadata = validationSnapshot ? validationSnapshot.collectionMetadata : await this.loadCollectionMetadataSnapshot(adapter);
         if (lifecycleGeneration !== this.lifecycleGeneration) return;
-        for (const row of subsetRows) {
-          mergedRows.set(row.key, {
-            value: row.value,
-            metadata: row.metadata
-          });
+        for (const options of activeSubsetOptions) {
+          const subsetRows = await this.loadSubsetRowsUnsafe(options, adapter);
+          if (lifecycleGeneration !== this.lifecycleGeneration) return;
+          for (const row of subsetRows) {
+            mergedRows.set(row.key, {
+              value: row.value,
+              metadata: row.metadata
+            });
+          }
+        }
+        if (outsideDemandKeys.length > 0 && validationSnapshot) {
+          const durableRows = new Map(
+            validationSnapshot.rows.map((row) => [row.key, row])
+          );
+          for (const key of outsideDemandKeys) {
+            if (mergedRows.has(key)) continue;
+            const row = durableRows.get(key);
+            if (row) {
+              mergedRows.set(key, {
+                value: row.value,
+                metadata: row.metadata
+              });
+            }
+          }
+        }
+      } catch (error) {
+        if (this.scopedRecovery) return;
+        if (!this.cacheGenerationClaim || !this.hasExpiredCacheClaim()) {
+          throw error;
         }
+        this.scheduleCacheClaimRecovery(lifecycleGeneration);
+        return;
+      }
+      if (this.isScopedRecoveryPending()) return;
+      if (this.cacheGenerationClaim && !await this.renewCacheClaim(adapter)) {
+        this.scheduleCacheClaimRecovery(lifecycleGeneration);
+        return;
       }
+      if (this.isScopedRecoveryPending() || lifecycleGeneration !== this.lifecycleGeneration)
+        return;
       for (const key of mergedRows.keys()) {
         hydrationContext.suppliedRowKeys.add(key);
       }
-      if (skipUnchangedReplace && this.matchesCollectionSnapshot(mergedRows, collectionMetadata)) {
+      if (activeSubsetOptions.length === 0) {
+        await whenSyncAccepted(
+          this.applyRowsToCollection(
+            [],
+            validationSnapshot?.rows ?? [],
+            collectionMetadata
+          )
+        );
+      } else if (skipUnchangedReplace && this.matchesCollectionSnapshot(mergedRows, collectionMetadata)) {
         const orphanKeys = this.collection?._syncedRowMetadataKeysOutsideBase() ?? [];
         if (orphanKeys.length > 0) {
           const applied = this.withInternalApply(() => {
@@ -2292,7 +3164,8 @@ class PersistedCollectionRuntime {
             value: row.value,
             metadata: row.metadata
           })),
-          collectionMetadata
+          collectionMetadata,
+          replayDemand
         );
         await whenSyncAccepted(applied);
       }
@@ -2320,7 +3193,12 @@ class PersistedCollectionRuntime {
       return;
     }
     this.indexAddedUnsubscribe = this.collection.on(`index:added`, (event) => {
-      void this.ensurePersistedIndex(event.index);
+      void this.ensurePersistedIndex(event.index).catch((error) => {
+        console.warn(
+          `Failed to ensure persisted index after index:added:`,
+          error
+        );
+      });
     });
     this.indexRemovedUnsubscribe = this.collection.on(
       `index:removed`,
@@ -2336,20 +3214,69 @@ class PersistedCollectionRuntime {
     }
     const indexMetadata = indexMetadataSnapshot ?? collection?.getIndexMetadata() ?? [];
     const completedLocalIndexSignatures = /* @__PURE__ */ new Set();
+    const lifecycleGeneration = this.lifecycleGeneration;
     for (const metadata of indexMetadata) {
-      if (await this.ensureLocalPersistedIndex(metadata, adapter)) {
+      const storageCollectionId = this.storageCollectionId;
+      const claimId = this.cacheGenerationClaim?.claimId;
+      const ensured = await this.ensureLocalPersistedIndex(metadata, adapter);
+      if (ensured && await this.reconcilePersistedIndex(
+        metadata,
+        adapter,
+        storageCollectionId,
+        claimId,
+        lifecycleGeneration,
+        true
+      )) {
         completedLocalIndexSignatures.add(metadata.signature);
       }
     }
     return completedLocalIndexSignatures;
   }
   async requestCoordinatorPersistedIndexes(indexMetadata, completedLocalIndexSignatures) {
+    const lifecycleGeneration = this.lifecycleGeneration;
     for (const metadata of indexMetadata) {
+      if (!this.hasCurrentIndex(metadata)) continue;
+      const storageCollectionId = this.storageCollectionId;
+      const claimId = this.cacheGenerationClaim?.claimId;
       await this.requestCoordinatorPersistedIndex(
         metadata,
         completedLocalIndexSignatures.has(metadata.signature)
       );
+      await this.reconcilePersistedIndex(
+        metadata,
+        this.persistence.adapter,
+        storageCollectionId,
+        claimId,
+        lifecycleGeneration,
+        true
+      );
+    }
+  }
+  /** Settle a late index operation against the Collection's current declaration. */
+  async reconcilePersistedIndex(indexMetadata, adapter, storageCollectionId, claimId, lifecycleGeneration, indexPresent) {
+    while (lifecycleGeneration === this.lifecycleGeneration && storageCollectionId === this.storageCollectionId) {
+      const declared = this.hasCurrentIndex(indexMetadata);
+      if (declared === indexPresent) return declared;
+      if (declared) {
+        if (!await this.ensureLocalPersistedIndex(indexMetadata, adapter)) {
+          return false;
+        }
+      } else {
+        if (!adapter.markIndexRemoved) return false;
+        try {
+          await adapter.markIndexRemoved(
+            this.storageTargetFor(storageCollectionId, claimId),
+            indexMetadata.signature,
+            { cacheGenerationClaimId: claimId }
+          );
+        } catch (error) {
+          console.warn(`Failed to mark persisted index removed:`, error);
+          return false;
+        }
+      }
+      indexPresent = declared;
     }
+    return false;
   }
   buildPersistedIndexSpec(index) {
     return {
@@ -2362,19 +3289,36 @@ class PersistedCollectionRuntime {
     };
   }
   async ensurePersistedIndex(indexMetadata, adapter = this.persistence.adapter) {
+    if (this.scopedRecoveryPending) return;
+    const lifecycleGeneration = this.lifecycleGeneration;
+    await this.ensureCacheClaimActive();
+    if (lifecycleGeneration !== this.lifecycleGeneration || !this.hasCurrentIndex(indexMetadata))
+      return;
     const completedLocally = await this.ensureLocalPersistedIndex(
       indexMetadata,
       adapter
     );
+    if (lifecycleGeneration !== this.lifecycleGeneration) return;
+    if (!this.hasCurrentIndex(indexMetadata)) {
+      await this.markIndexRemoved(indexMetadata);
+      return;
+    }
     await this.requestCoordinatorPersistedIndex(indexMetadata, completedLocally);
+    if (lifecycleGeneration === this.lifecycleGeneration && !this.hasCurrentIndex(indexMetadata)) {
+      await this.markIndexRemoved(indexMetadata);
+    }
+  }
+  hasCurrentIndex(indexMetadata) {
+    return this.collection?.getIndexMetadata().some((current) => current.signature === indexMetadata.signature) ?? false;
   }
   async ensureLocalPersistedIndex(indexMetadata, adapter) {
     try {
       const spec = this.buildPersistedIndexSpec(indexMetadata);
       await adapter.ensureIndex(
-        this.collectionId,
+        this.storageTargetFor(),
         indexMetadata.signature,
-        spec
+        spec,
+        { cacheGenerationClaimId: this.cacheGenerationClaim?.claimId }
       );
       return true;
     } catch (error) {
@@ -2386,11 +3330,12 @@ class PersistedCollectionRuntime {
     try {
       const spec = this.buildPersistedIndexSpec(indexMetadata);
       await this.persistence.coordinator.requestEnsurePersistedIndex(
-        this.collectionId,
+        this.storageCollectionId,
         indexMetadata.signature,
         spec,
         completedLocally ? this.persistence.adapter : void 0,
-        completedLocally
+        completedLocally,
+        this.cacheGenerationClaim?.claimId
       );
     } catch (error) {
       console.warn(
@@ -2404,10 +3349,19 @@ class PersistedCollectionRuntime {
       return;
     }
     try {
+      if (this.scopedRecoveryPending) return;
+      const lifecycleGeneration = this.lifecycleGeneration;
+      await this.ensureCacheClaimActive();
+      if (lifecycleGeneration !== this.lifecycleGeneration || this.hasCurrentIndex(indexMetadata))
+        return;
       await this.persistence.adapter.markIndexRemoved(
-        this.collectionId,
-        indexMetadata.signature
+        this.storageTargetFor(),
+        indexMetadata.signature,
+        { cacheGenerationClaimId: this.cacheGenerationClaim?.claimId }
       );
+      if (lifecycleGeneration === this.lifecycleGeneration && this.hasCurrentIndex(indexMetadata)) {
+        await this.ensurePersistedIndex(indexMetadata);
+      }
     } catch (error) {
       console.warn(`Failed to mark persisted index removed:`, error);
     }
@@ -2610,20 +3564,26 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           throw error;
         }
       };
-      runtime.setSyncControls({
-        begin: params.begin,
-        write: params.write,
-        commit: params.commit,
-        truncate: params.truncate,
-        metadata: params.metadata ?? null,
-        markError: params.markError
-      });
       runtime.setCollection(
-        params.collection
+        params.collection,
+        {
+          begin: params.begin,
+          write: params.write,
+          commit: params.commit,
+          truncate: params.truncate,
+          metadata: params.metadata ?? null,
+          markError: params.markError
+        }
       );
       const persistenceCapability = {
         protocol: SYNC_PERSISTENCE_PROTOCOL,
         version: SYNC_PERSISTENCE_VERSION,
+        get managedCacheGeneration() {
+          return runtime.hasManagedCacheGeneration();
+        },
+        get startupCacheGenerationRotated() {
+          return runtime.hasRotatedStartupCacheGeneration();
+        },
         reserveCommitTurn: () => {
           const openTransaction = getOpenTransaction();
           if (openTransaction && !openTransaction.internal)
@@ -2637,6 +3597,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             throw runtime.reportSyncError(error);
           }
         },
+        startScopedRecovery: (resetMetadata) => startupState.cleanedUp ? Promise.resolve() : runtime.startScopedRecovery(resetMetadata),
         scanPersistedRows: (options) => startupState.cleanedUp ? Promise.resolve([]) : runtime.scanPersistedRows(options),
         resumeSnapshot: {
           certify: async () => {
@@ -2660,6 +3621,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           }
         }
       };
+      let sourceSession = 0;
       const wrappedParams = {
         ...params,
         markError: reportUpstreamError,
@@ -2931,6 +3893,12 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             settlePublicationAdmissionWaiters(openTransaction, error);
             return createHandledRejection(error);
           }
+          if (runtime.isScopedRecoveryPending()) {
+            settlePendingTransaction(openTransaction);
+            const error = new SyncTransactionAbortedError();
+            settlePublicationAdmissionWaiters(openTransaction, error);
+            return createHandledRejection(error);
+          }
           try {
             bindToCurrentHydration(openTransaction);
             assertHydrationSequenceCurrent(openTransaction);
@@ -3005,48 +3973,150 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           return visibleAfterDurable(openTransaction, applied);
         }
       };
+      const sourceParamsFor = (session) => {
+        const active = () => !startupState.cleanedUp && session === sourceSession;
+        const metadata = wrappedParams.metadata;
+        return {
+          ...wrappedParams,
+          markReady: () => {
+            if (active()) wrappedParams.markReady();
+          },
+          markError: (error) => {
+            if (active()) wrappedParams.markError(error);
+          },
+          begin: () => {
+            if (active()) wrappedParams.begin();
+          },
+          write: (message) => {
+            if (active()) wrappedParams.write(message);
+          },
+          truncate: () => {
+            if (active()) wrappedParams.truncate();
+          },
+          commit: (signal) => active() ? wrappedParams.commit(signal) : true,
+          metadata: metadata && {
+            ...metadata,
+            row: {
+              get: (key) => active() ? metadata.row.get(key) : void 0,
+              set: (key, value) => {
+                if (active()) metadata.row.set(key, value);
+              },
+              delete: (key) => {
+                if (active()) metadata.row.delete(key);
+              }
+            },
+            collection: {
+              get: (key) => active() ? metadata.collection.get(key) : void 0,
+              set: (key, value) => {
+                if (active()) metadata.collection.set(key, value);
+              },
+              delete: (key) => {
+                if (active()) metadata.collection.delete(key);
+              },
+              list: (prefix) => active() ? metadata.collection.list(prefix) : []
+            },
+            persistence: {
+              ...metadata.persistence,
+              reserveCommitTurn: () => {
+                if (active()) metadata.persistence.reserveCommitTurn();
+              },
+              hydrateBaseline: () => active() ? metadata.persistence.hydrateBaseline() : Promise.resolve(),
+              startScopedRecovery: (resetMetadata) => active() ? metadata.persistence.startScopedRecovery?.(
+                resetMetadata
+              ) ?? Promise.resolve() : Promise.resolve(),
+              scanPersistedRows: (options) => active() ? metadata.persistence.scanPersistedRows(options) : Promise.resolve([]),
+              resumeSnapshot: {
+                certify: () => active() ? metadata.persistence.resumeSnapshot.certify() : Promise.resolve(),
+                getKeySetEvidence: () => active() ? metadata.persistence.resumeSnapshot.getKeySetEvidence() : void 0,
+                expectCurrentCommit: () => {
+                  if (active())
+                    metadata.persistence.resumeSnapshot.expectCurrentCommit();
+                }
+              }
+            }
+          }
+        };
+      };
       let sourceResult = {};
       let sourceResultSettled = false;
       let activeSourceSyncEntry;
-      fullStartPromise = runtime.ensureStarted();
-      void fullStartPromise.catch(() => void 0);
-      sourceResultPromise = (async () => {
-        await runtime.ensureStartupMetadataLoaded();
-        if (startupState.cleanedUp) {
-          sourceResultSettled = true;
-          return sourceResult;
-        }
+      let sourceCleanupPromise;
+      let customRestartSequence = 0;
+      const enterSourceSession = () => {
+        const session = ++sourceSession;
         let settleSourceSyncEntry;
         activeSourceSyncEntry = new Promise((resolve) => {
           settleSourceSyncEntry = resolve;
         });
         try {
           sourceResult = normalizeSyncFnResult(
-            sourceSyncConfig.sync(wrappedParams)
+            sourceSyncConfig.sync(
+              runtime.hasManagedCacheGeneration() ? sourceParamsFor(session) : wrappedParams
+            )
           );
+          if (!startupState.cleanedUp && sourceResult.loadSubset) {
+            const ownerSource = sourceResult;
+            const loadSubset = async (options) => {
+              if (startupState.cleanedUp || session !== sourceSession) {
+                throw new Error(`persisted sync source is no longer active`);
+              }
+              await ownerSource.loadSubset?.(
+                options
+              );
+            };
+            runtime.registerRemoteSubsetOwner(
+              Object.assign(loadSubset, {
+                unloadSubset: (options) => ownerSource.unloadSubset?.(
+                  options
+                ),
+                onError: (error) => {
+                  if (session === sourceSession) reportUpstreamError(error);
+                }
+              })
+            );
+          }
         } finally {
           activeSourceSyncEntry = void 0;
           settleSourceSyncEntry();
         }
-        if (!startupState.cleanedUp && sourceResult.loadSubset) {
-          const loadSubset = async (options) => {
-            if (startupState.cleanedUp) {
-              throw new Error(`persisted sync source is no longer active`);
-            }
-            await sourceResult.loadSubset?.(
-              options
-            );
-          };
-          runtime.registerRemoteSubsetOwner(
-            Object.assign(loadSubset, {
-              unloadSubset: (options) => sourceResult.unloadSubset?.(
-                options
-              ),
-              onError: reportUpstreamError
-            })
+      };
+      const restartCustomSource = (cacheRotated) => {
+        const restartSequence = ++customRestartSequence;
+        if (!sourceCleanupPromise) {
+          sourceSession++;
+          const abortError = new SyncTransactionAbortedError();
+          for (const transaction of transactionStack) {
+            settlePublicationAdmissionWaiters(transaction, abortError);
+          }
+          transactionStack.length = 0;
+          const retiredResult = sourceResult;
+          sourceCleanupPromise = Promise.resolve().then(
+            () => retiredResult.cleanup?.()
+          );
+        }
+        return Promise.all([sourceCleanupPromise, cacheRotated]).then(() => {
+          if (startupState.cleanedUp || restartSequence !== customRestartSequence)
+            return;
+          sourceCleanupPromise = void 0;
+          enterSourceSession();
+          runtime.setSourceRestartAfterScopedRecovery(
+            sourceResult.restartAfterScopedRecovery ?? (runtime.hasManagedCacheGeneration() ? restartCustomSource : void 0)
           );
+        });
+      };
+      fullStartPromise = runtime.ensureStarted();
+      void fullStartPromise.catch(() => void 0);
+      sourceResultPromise = (async () => {
+        await runtime.ensureStartupMetadataLoaded();
+        if (startupState.cleanedUp) {
+          sourceResultSettled = true;
+          return sourceResult;
         }
+        enterSourceSession();
         sourceResultSettled = true;
+        runtime.setSourceRestartAfterScopedRecovery(
+          sourceResult.restartAfterScopedRecovery ?? (runtime.hasManagedCacheGeneration() ? restartCustomSource : void 0)
+        );
         return sourceResult;
       })();
       resolveSourceResultAssigned();
@@ -3056,6 +4126,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
       return {
         cleanup: async () => {
           startupState.cleanedUp = true;
+          runtime.clearSourceRestartAfterScopedRecovery();
           const sourceSyncEntry = activeSourceSyncEntry;
           const cleanupError = new SyncTransactionAbortedError();
           for (const acquisition of acquisitions.values()) {
@@ -3069,7 +4140,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           transactionStack.length = 0;
           let sourceCleanup;
           try {
-            sourceCleanup = sourceSyncEntry ? sourceSyncEntry.then(() => sourceResult.cleanup?.()) : Promise.resolve(sourceResult.cleanup?.());
+            sourceCleanup = sourceCleanupPromise ?? (sourceSyncEntry ? sourceSyncEntry.then(() => sourceResult.cleanup?.()) : Promise.resolve(sourceResult.cleanup?.()));
           } catch (error) {
             sourceCleanup = Promise.reject(error);
           }
@@ -3096,31 +4167,63 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
         loadSubset: (options) => {
           const acquisition = { forwarded: false };
           acquisitions.set(options, acquisition);
-          const forwardUpstream = (resolvedSourceResult, loadOptions) => {
+          const forwardUpstream = (loadOptions) => {
             if (startupState.cleanedUp || acquisitions.get(options) !== acquisition) {
               return true;
             }
-            if (!resolvedSourceResult.loadSubset) return true;
+            const currentSource = sourceResult;
+            if (!currentSource.loadSubset) return true;
             acquisition.forwarded = true;
+            acquisition.source = currentSource;
             try {
-              return resolvedSourceResult.loadSubset(loadOptions);
+              return currentSource.loadSubset(loadOptions);
             } catch (error) {
               acquisition.forwarded = false;
+              acquisition.source = void 0;
               throw error;
             }
           };
           const openTransaction = getOpenTransaction();
           const needsPublicationAdmission = openTransaction?.reservesCommitTurn === true;
+          let hydrationStarted = false;
+          const raceRetainedLoad = (work2, canAbortPromptly = () => true) => {
+            const signal = options.signal;
+            const abortable = !signal ? work2 : new Promise((resolve, reject) => {
+              const abortError = () => signal.reason ?? new SyncTransactionAbortedError();
+              const onAbort = () => {
+                if (canAbortPromptly()) reject(abortError());
+              };
+              signal.addEventListener(`abort`, onAbort, { once: true });
+              if (signal.aborted) onAbort();
+              void work2.then(
+                () => {
+                  signal.removeEventListener(`abort`, onAbort);
+                  if (signal.aborted) reject(abortError());
+                  else resolve();
+                },
+                (error) => {
+                  signal.removeEventListener(`abort`, onAbort);
+                  reject(signal.aborted ? abortError() : error);
+                }
+              );
+            });
+            return abortable.catch((error) => {
+              if (startupState.cleanedUp || acquisitions.get(options) !== acquisition) {
+                return;
+              }
+              throw error;
+            });
+          };
           const hydrated = sourceResultSettled && !needsPublicationAdmission ? runtime.loadHydratedSubset(
             options,
-            (loadOptions) => forwardUpstream(sourceResult, loadOptions)
+            (loadOptions) => forwardUpstream(loadOptions)
           ) : void 0;
           if (hydrated !== void 0) {
-            return hydrated;
+            return hydrated === true ? true : raceRetainedLoad(hydrated);
           }
-          return (async () => {
+          const work = (async () => {
             await fullStartPromise;
-            const resolvedSourceResult = await sourceResultPromise;
+            await sourceResultPromise;
             if (startupState.cleanedUp || acquisitions.get(options) !== acquisition) {
               return;
             }
@@ -3137,9 +4240,14 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
             }
             return runtime.loadSubset(
               options,
-              (loadOptions) => forwardUpstream(resolvedSourceResult, loadOptions)
+              (loadOptions) => forwardUpstream(loadOptions),
+              () => {
+                hydrationStarted = true;
+              },
+              () => !startupState.cleanedUp && acquisitions.get(options) === acquisition
             );
           })();
+          return raceRetainedLoad(work, () => !hydrationStarted);
         },
         unloadSubset: (options) => {
           const acquisition = acquisitions.get(options);
@@ -3147,7 +4255,7 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
           acquisitions.delete(options);
           runtime.unloadSubset(
             options,
-            acquisition?.forwarded ? sourceResult.unloadSubset : void 0
+            acquisition?.forwarded ? acquisition.source?.unloadSubset : void 0
           );
         }
       };
@@ -3157,16 +4265,16 @@ function createWrappedSyncConfig(sourceSyncConfig, runtime, persistedReadiness)
 function createLoopbackSyncConfig(runtime) {
   return {
     sync: (params) => {
-      runtime.setSyncControls({
-        begin: params.begin,
-        write: params.write,
-        commit: params.commit,
-        truncate: params.truncate,
-        metadata: params.metadata ?? null,
-        markError: params.markError
-      });
       runtime.setCollection(
-        params.collection
+        params.collection,
+        {
+          begin: params.begin,
+          write: params.write,
+          commit: params.commit,
+          truncate: params.truncate,
+          metadata: params.metadata ?? null,
+          markError: params.markError
+        }
       );
       void runtime.ensureStarted().then(() => {
         if (runtime.getCurrentTerminalFailure()) return;
@@ -3196,6 +4304,19 @@ function persistedCollectionOptions(options) {
     );
   }
   const persistedReadinessTracker = networkTimeoutMs !== void 0 ? new PersistedReadinessTracker(networkTimeoutMs) : void 0;
+  let claimed = false;
+  let claimedRuntime;
+  const claimOptions = () => {
+    if (claimed) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Persisted options can create only one Collection. Create fresh options for each Collection.`
+      );
+    }
+    claimed = true;
+    return () => {
+      if (!claimedRuntime?.hasBoundCollection()) claimed = false;
+    };
+  };
   if (hasOwnSyncKey(options)) {
     if (!isValidSyncConfig(options.sync)) {
       throw new InvalidSyncConfigError(
@@ -3222,8 +4343,10 @@ function persistedCollectionOptions(options) {
       persistence2,
       syncOptions.syncMode ?? `eager`,
       collectionId2,
-      persistedReadinessTracker
+      persistedReadinessTracker,
+      claimOptions
     );
+    claimedRuntime = runtime2;
     const result2 = {
       ...syncOptions,
       id: collectionId2,
@@ -3240,7 +4363,8 @@ function persistedCollectionOptions(options) {
       () => persistedCollectionOptions({
         ...options,
         id: collectionId2
-      })
+      }),
+      claimOptions
     );
   }
   const {
@@ -3263,8 +4387,10 @@ function persistedCollectionOptions(options) {
     persistence,
     localOnlyOptions.syncMode ?? `eager`,
     localOnlyOptions.id ?? DEFAULT_DB_NAME,
-    persistedReadinessTracker
+    persistedReadinessTracker,
+    claimOptions
   );
+  claimedRuntime = runtime;
   const wrappedOnInsert = async (params) => {
     const lifecycleGeneration = runtime.getLifecycleGeneration();
     const handlerResult = localOnlyOptions.onInsert ? await localOnlyOptions.onInsert(
@@ -3328,7 +4454,8 @@ function persistedCollectionOptions(options) {
     () => persistedCollectionOptions({
       ...options,
       id: collectionId
-    })
+    }),
+    claimOptions
   );
 }
 function encodePersistedStorageKey(key) {
@@ -3391,9 +4518,12 @@ export {
   SingleProcessCoordinator,
   createPersistedTableName,
   decodePersistedStorageKey,
+  eagerStorageTarget,
   encodePersistedStorageKey,
   forwardSQLiteDriverSharedLogicalScheduling,
+  managedStorageTarget,
   persistedCollectionOptions,
+  resolvePersistedStorageTarget,
   validatePersistedCollectionCoordinator
 };
 //# sourceMappingURL=persisted.js.map