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

package/dist/cjs/sqlite-core-adapter.d.cts

@@ -1,5 +1,5 @@
 import { LoadSubsetOptions } from '@tanstack/db';
-import { CommittedTxAnchor, HydrationPersistenceAdapter, PersistedIndexSpec, PersistedKeySetEvidence, PersistedRowScanOptions, PersistedScannedRow, PersistedTx, PersistenceAdapter, ReconciledCommittedTx, ReplayableTxDelta, SQLiteDriver } from './persisted.cjs';
+import { CommittedTxAnchor, HydrationPersistenceAdapter, PersistedCacheGenerationClaim, PersistedIndexSpec, PersistedKeySetEvidence, PersistedRowScanOptions, PersistedScannedRow, PersistedStorageTarget, PersistedTx, PersistenceAdapter, ReconciledCommittedTx, ReplayableTxDelta, SQLiteDriver } from './persisted.cjs';
 type SQLiteCoreAdapterSchemaMismatchPolicy = `sync-present-reset` | `sync-absent-error` | `reset`;
 export type SQLiteCoreAdapterOptions = {
     driver: SQLiteDriver;
@@ -8,6 +8,10 @@ export type SQLiteCoreAdapterOptions = {
     appliedTxPruneMaxRows?: number;
     appliedTxPruneMaxAgeSeconds?: number;
     pullSinceReloadThreshold?: number;
+    /** Milliseconds without renewal before a sync run loses cache access. */
+    cacheGenerationClaimTtlMs?: number;
+    /** Host clock, injectable for expiry histories. */
+    now?: () => number;
 };
 export type SQLitePullSinceResult<TKey extends string | number> = {
     latestRowVersion: number;
@@ -19,6 +23,7 @@ export type SQLitePullSinceResult<TKey extends string | number> = {
     deletedKeys: Array<TKey>;
     deltas: Array<ReplayableTxDelta<Record<string, unknown>, TKey>>;
 };
+export declare const DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS: number;
 /**
  * Default cap on retained `applied_tx` rows per collection. The log is a
  * replayable cache, so a bounded row count keeps SQLite files from growing
@@ -43,9 +48,21 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
     private readonly appliedTxPruneMaxAgeSeconds;
     private readonly pullSinceReloadThreshold;
     private readonly replacementBatchSize;
+    private readonly cacheGenerationClaimTtlMs;
+    private readonly now;
     private initialized;
     private readonly collectionTableCache;
     private readonly collectionTableLoads;
+    claimCacheGeneration(collectionId: string): Promise<PersistedCacheGenerationClaim>;
+    rotateCacheGeneration(collectionId: string, claimId: string, resetMetadata?: {
+        key: string;
+        value: unknown;
+    }, expectedStorageCollectionId?: string): Promise<PersistedCacheGenerationClaim>;
+    releaseCacheGenerationClaim(claimId: string): Promise<void>;
+    renewCacheGenerationClaim(storageCollectionId: string, claimId: string): Promise<number | undefined>;
+    private renewCacheGenerationClaimUnscheduled;
+    private collectRetiredCacheGenerations;
+    getCacheGenerationNow(): number;
     constructor(options: SQLiteCoreAdapterOptions);
     runInHydrationScope<T>(task: (adapter: HydrationPersistenceAdapter) => Promise<T>): Promise<T>;
     runInRegularScope<T>(task: (adapter: HydrationPersistenceAdapter) => Promise<T>): Promise<T>;
@@ -54,17 +71,20 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
     private resolveScheduler;
     private runInTransaction;
     private assertCurrentSchemaVersion;
-    loadSubset(collectionId: string, options: LoadSubsetOptions, ctx?: {
+    private assertCacheGenerationReadClaim;
+    loadSubset(target: PersistedStorageTarget, options: LoadSubsetOptions, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
+        cacheGenerationClaimId?: string;
     }): Promise<Array<{
         key: string | number;
         value: Record<string, unknown>;
         metadata?: unknown;
     }>>;
     private loadSubsetUnscheduled;
-    loadResumeSnapshot(collectionId: string, ctx?: {
+    loadResumeSnapshot(target: PersistedStorageTarget, ctx?: {
         requiredIndexSignatures?: ReadonlyArray<string>;
         includeRows?: boolean;
+        cacheGenerationClaimId?: string;
     }): Promise<{
         rows: Array<{
             key: string | number;
@@ -82,29 +102,41 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
         resetEpoch: number;
     }>;
     private loadResumeSnapshotUnscheduled;
-    applyCommittedTx(collectionId: string, tx: PersistedTx): Promise<void>;
-    reconcileCommittedTx(collectionId: string, tx: PersistedTx, anchor: CommittedTxAnchor): Promise<ReconciledCommittedTx>;
+    applyCommittedTx(target: PersistedStorageTarget, tx: PersistedTx): Promise<void>;
+    reconcileCommittedTx(target: PersistedStorageTarget, tx: PersistedTx, anchor: CommittedTxAnchor): Promise<ReconciledCommittedTx>;
     private applyCommittedTxUnscheduled;
     private reconcileCommittedTxUnscheduled;
     private applyCommittedTxInternal;
-    loadCollectionMetadata(collectionId: string): Promise<Array<{
+    loadCollectionMetadata(target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<Array<{
         key: string;
         value: unknown;
     }>>;
     private loadCollectionMetadataUnscheduled;
-    scanRows(collectionId: string, options?: PersistedRowScanOptions): Promise<Array<PersistedScannedRow>>;
+    scanRows(target: PersistedStorageTarget, options?: PersistedRowScanOptions, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<Array<PersistedScannedRow>>;
     private scanRowsUnscheduled;
-    ensureIndex(collectionId: string, signature: string, spec: PersistedIndexSpec): Promise<void>;
+    ensureIndex(target: PersistedStorageTarget, signature: string, spec: PersistedIndexSpec, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<void>;
     private ensureIndexUnscheduled;
-    markIndexRemoved(collectionId: string, signature: string): Promise<void>;
+    markIndexRemoved(target: PersistedStorageTarget, signature: string, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<void>;
     private markIndexRemovedUnscheduled;
-    reserveLeadershipTerm(collectionId: string, observedTerm: number): Promise<{
+    reserveLeadershipTerm(target: PersistedStorageTarget, observedTerm: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
     }>;
     private reserveLeadershipTermUnscheduled;
-    getStreamPosition(collectionId: string): Promise<{
+    getStreamPosition(target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
@@ -113,7 +145,9 @@ export declare class SQLiteCorePersistenceAdapter implements PersistenceAdapter
     private readLatestRowVersion;
     private readStreamPosition;
     private readKeySetEvidence;
-    pullSince(collectionId: string, fromRowVersion: number): Promise<SQLitePullSinceResult<string | number>>;
+    pullSince(target: PersistedStorageTarget, fromRowVersion: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }): Promise<SQLitePullSinceResult<string | number>>;
     private pullSinceUnscheduled;
     private loadSubsetInternal;
     private applyInMemoryWhere;

package/dist/esm/broadcast-coordinator.d.ts

@@ -1,8 +1,10 @@
 import { LoadSubsetOptions } from '@tanstack/db';
 import { RemoteSubsetOwner } from './remote-subset-owner.js';
-import { ApplyCommittedTxResponse, ApplyLocalMutationsResponse, CommittedTxAnchor, HydrationPersistenceAdapter, PersistedCollectionCoordinator, PersistedIndexSpec, PersistedMutationEnvelope, PersistedTx, PersistenceAdapter, ProtocolEnvelope, PullSinceResponse, ReconcileCommittedTxResponse } from './persisted.js';
+import { ApplyCommittedTxResponse, ApplyLocalMutationsResponse, CommittedTxAnchor, HydrationPersistenceAdapter, PersistedCollectionCoordinator, PersistedIndexSpec, PersistedMutationEnvelope, PersistedStorageTarget, PersistedTx, PersistenceAdapter, ProtocolEnvelope, PullSinceResponse, ReconcileCommittedTxResponse } from './persisted.js';
 type CoordinatorAdapter = Pick<PersistenceAdapter, `loadSubset` | `applyCommittedTx` | `reconcileCommittedTx` | `ensureIndex` | `runInRegularScope`> & {
-    pullSince?: (collectionId: string, fromRowVersion: number) => Promise<{
+    pullSince?: (target: PersistedStorageTarget, fromRowVersion: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
         latestRowVersion: number;
         requiresFullReload: true;
     } | {
@@ -11,12 +13,16 @@ type CoordinatorAdapter = Pick<PersistenceAdapter, `loadSubset` | `applyCommitte
         changedKeys: Array<string | number>;
         deletedKeys: Array<string | number>;
     }>;
-    getStreamPosition?: (collectionId: string) => Promise<{
+    getStreamPosition?: (target: PersistedStorageTarget, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
     }>;
-    reserveLeadershipTerm?: (collectionId: string, observedTerm: number) => Promise<{
+    reserveLeadershipTerm?: (target: PersistedStorageTarget, observedTerm: number, ctx?: {
+        cacheGenerationClaimId?: string;
+    }) => Promise<{
         latestTerm: number;
         latestSeq: number;
         latestRowVersion: number;
@@ -35,6 +41,7 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
     private readonly coordinatorName;
     private defaultAdapter;
     private readonly collectionAdapters;
+    private readonly collectionClaimIds;
     private readonly remoteSubsetOwners;
     private readonly remoteSubsetIds;
     private readonly outboundRemoteSubsetAcquisitions;
@@ -61,7 +68,7 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
      */
     setAdapter(adapter: CoordinatorAdapter): void;
     /** Register the persistence adapter that owns one collection. */
-    setAdapterForCollection(collectionId: string, adapter: CoordinatorAdapter): void;
+    setAdapterForCollection(collectionId: string, adapter: CoordinatorAdapter, cacheGenerationClaimId?: string): void;
     registerRemoteSubsetOwner(collectionId: string, owner: RemoteSubsetOwner): () => void;
     getNodeId(): string;
     subscribe(collectionId: string, onMessage: (message: ProtocolEnvelope<unknown>) => void): () => void;
@@ -70,12 +77,13 @@ export declare class BroadcastCollectionCoordinator implements PersistedCollecti
     ensureLeadership(collectionId: string): Promise<void>;
     requestEnsureRemoteSubset(collectionId: string, options: LoadSubsetOptions): Promise<void>;
     requestReleaseRemoteSubset(collectionId: string, options: LoadSubsetOptions): Promise<void>;
+    private scheduleRemoteSubsetReleaseRetry;
     private acquireRemoteSubset;
-    requestEnsurePersistedIndex(collectionId: string, signature: string, spec: PersistedIndexSpec, scopedAdapter?: HydrationPersistenceAdapter, localEnsureCompleted?: boolean): Promise<void>;
-    requestApplyLocalMutations(collectionId: string, mutations: Array<PersistedMutationEnvelope>): Promise<ApplyLocalMutationsResponse>;
+    requestEnsurePersistedIndex(collectionId: string, signature: string, spec: PersistedIndexSpec, scopedAdapter?: HydrationPersistenceAdapter, localEnsureCompleted?: boolean, cacheGenerationClaimId?: string): Promise<void>;
+    requestApplyLocalMutations(collectionId: string, mutations: Array<PersistedMutationEnvelope>, cacheGenerationClaimId?: string): Promise<ApplyLocalMutationsResponse>;
     requestApplyCommittedTx(collectionId: string, tx: PersistedTx, scopedAdapter?: HydrationPersistenceAdapter): Promise<ApplyCommittedTxResponse>;
     reconcileCommittedTx(collectionId: string, tx: PersistedTx, anchor: CommittedTxAnchor, scopedAdapter?: HydrationPersistenceAdapter): Promise<ReconcileCommittedTxResponse>;
-    pullSince(collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter): Promise<PullSinceResponse>;
+    pullSince(collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter, cacheGenerationClaimId?: string): Promise<PullSinceResponse>;
     dispose(): void;
     private getOrCreateCollectionState;
     private ensureCollectionState;

package/dist/esm/broadcast-coordinator.js

@@ -1,8 +1,9 @@
 import { safeRandomUUID } from "@tanstack/db";
 import { isValidCommittedTxAnchor } from "./committed-tx-anchor.js";
-import { DuplicateRemoteSubsetOwnerError, InvalidPersistenceAdapterError, RetryableRemoteSubsetAcquisitionError, IndeterminateCommitError, toPersistedCollectionDurabilityError, PersistedCollectionDurabilityError } from "./errors.js";
+import { DuplicateRemoteSubsetOwnerError, InvalidPersistenceAdapterError, RetryableRemoteSubsetAcquisitionError, IndeterminateCommitError, InvalidPersistedCollectionConfigError, toPersistedCollectionDurabilityError, PersistedCollectionDurabilityError } from "./errors.js";
 import { toTransportedLoadSubsetOptions, toProcessLocalLoadSubsetOptions } from "./remote-subset-wire.js";
 import { unloadRemoteSubsetOwner } from "./remote-subset-owner.js";
+import { managedStorageTarget, eagerStorageTarget } from "./persisted.js";
 const HEARTBEAT_INTERVAL_MS = 3e3;
 const LEADERSHIP_RETRY_DELAY_MS = 200;
 const RPC_TIMEOUT_MS = 1e4;
@@ -21,6 +22,7 @@ class BroadcastCollectionCoordinator {
   constructor(options) {
     this.nodeId = safeRandomUUID();
     this.collectionAdapters = /* @__PURE__ */ new Map();
+    this.collectionClaimIds = /* @__PURE__ */ new Map();
     this.remoteSubsetOwners = /* @__PURE__ */ new Map();
     this.remoteSubsetIds = /* @__PURE__ */ new Map();
     this.outboundRemoteSubsetAcquisitions = /* @__PURE__ */ new Map();
@@ -76,9 +78,14 @@ class BroadcastCollectionCoordinator {
     this.defaultAdapter = adapter;
   }
   /** Register the persistence adapter that owns one collection. */
-  setAdapterForCollection(collectionId, adapter) {
+  setAdapterForCollection(collectionId, adapter, cacheGenerationClaimId) {
     requireDurableElection(adapter);
     this.collectionAdapters.set(collectionId, adapter);
+    if (cacheGenerationClaimId) {
+      this.collectionClaimIds.set(collectionId, cacheGenerationClaimId);
+    } else {
+      this.collectionClaimIds.delete(collectionId);
+    }
   }
   registerRemoteSubsetOwner(collectionId, owner) {
     if (this.remoteSubsetOwners.has(collectionId)) {
@@ -222,10 +229,29 @@ class BroadcastCollectionCoordinator {
     }
     try {
       await acquisition.release;
+    } catch (error) {
+      this.scheduleRemoteSubsetReleaseRetry(acquisition, options);
+      throw error;
     } finally {
       acquisition.release = null;
     }
   }
+  scheduleRemoteSubsetReleaseRetry(acquisition, options) {
+    const key = remoteSubsetAcquisitionKey(
+      acquisition.collectionId,
+      acquisition.acquisitionId
+    );
+    if (this.isDisposed() || this.outboundRemoteSubsetAcquisitions.get(key) !== acquisition || acquisition.retryTimer !== null) {
+      return;
+    }
+    acquisition.retryTimer = setTimeout(() => {
+      acquisition.retryTimer = null;
+      void this.requestReleaseRemoteSubset(
+        acquisition.collectionId,
+        options
+      ).catch(() => void 0);
+    }, RPC_RETRY_DELAY_MS);
+  }
   async acquireRemoteSubset(acquisition) {
     if (acquisition.inFlight) return acquisition.inFlight;
     const route = { localOwner: false };
@@ -285,7 +311,9 @@ class BroadcastCollectionCoordinator {
     try {
       await work;
       acquired = true;
-      this.cancelRemoteSubsetReplayRetry(acquisition);
+      if (!acquisition.releaseRequested) {
+        this.cancelRemoteSubsetReplayRetry(acquisition);
+      }
     } finally {
       if (acquisition.inFlight === work) acquisition.inFlight = null;
       const current = this.collections.get(acquisition.collectionId);
@@ -302,21 +330,34 @@ class BroadcastCollectionCoordinator {
       }
     }
   }
-  async requestEnsurePersistedIndex(collectionId, signature, spec, scopedAdapter, localEnsureCompleted = false) {
+  async requestEnsurePersistedIndex(collectionId, signature, spec, scopedAdapter, localEnsureCompleted = false, cacheGenerationClaimId) {
     if (this.isLeader(collectionId)) {
       if (localEnsureCompleted) return;
-      await (scopedAdapter ?? this.requireAdapter(collectionId)).ensureIndex(
-        collectionId,
-        signature,
-        spec
-      );
+      const adapter = scopedAdapter ?? this.requireAdapter(collectionId);
+      if (cacheGenerationClaimId) {
+        await adapter.ensureIndex(
+          managedStorageTarget(collectionId, cacheGenerationClaimId),
+          signature,
+          spec,
+          {
+            cacheGenerationClaimId
+          }
+        );
+      } else {
+        await adapter.ensureIndex(
+          eagerStorageTarget(collectionId),
+          signature,
+          spec
+        );
+      }
       return;
     }
     const response = await this.sendRPC(collectionId, {
       type: `rpc:ensurePersistedIndex:req`,
       rpcId: safeRandomUUID(),
       signature,
-      spec
+      spec,
+      cacheGenerationClaimId
     });
     if (!response.ok) {
       throw new Error(
@@ -324,7 +365,7 @@ class BroadcastCollectionCoordinator {
       );
     }
   }
-  async requestApplyLocalMutations(collectionId, mutations) {
+  async requestApplyLocalMutations(collectionId, mutations, cacheGenerationClaimId) {
     const initialRoute = this.waitForInitialRoute(collectionId);
     if (initialRoute) await initialRoute;
     if (this.isLeader(collectionId)) {
@@ -332,14 +373,16 @@ class BroadcastCollectionCoordinator {
         type: `rpc:applyLocalMutations:req`,
         rpcId: safeRandomUUID(),
         envelopeId: safeRandomUUID(),
-        mutations
+        mutations,
+        cacheGenerationClaimId
       });
     }
     return this.sendRPC(collectionId, {
       type: `rpc:applyLocalMutations:req`,
       rpcId: safeRandomUUID(),
       envelopeId: safeRandomUUID(),
-      mutations
+      mutations,
+      cacheGenerationClaimId
     });
   }
   async requestApplyCommittedTx(collectionId, tx, scopedAdapter) {
@@ -380,14 +423,15 @@ class BroadcastCollectionCoordinator {
     }
     return response;
   }
-  async pullSince(collectionId, fromRowVersion, scopedAdapter) {
+  async pullSince(collectionId, fromRowVersion, scopedAdapter, cacheGenerationClaimId) {
     if (this.isLeader(collectionId)) {
       return this.handlePullSince(
         collectionId,
         {
           type: `rpc:pullSince:req`,
           rpcId: safeRandomUUID(),
-          fromRowVersion
+          fromRowVersion,
+          cacheGenerationClaimId
         },
         scopedAdapter
       );
@@ -395,7 +439,8 @@ class BroadcastCollectionCoordinator {
     return this.sendRPC(collectionId, {
       type: `rpc:pullSince:req`,
       rpcId: safeRandomUUID(),
-      fromRowVersion
+      fromRowVersion,
+      cacheGenerationClaimId
     });
   }
   // -----------------------------------------------------------------------
@@ -428,6 +473,7 @@ class BroadcastCollectionCoordinator {
     this.channel.close();
     this.collections.clear();
     this.collectionAdapters.clear();
+    this.collectionClaimIds.clear();
     for (const collectionId of this.remoteSubsetOwners.keys()) {
       this.releaseInboundRemoteSubsetAcquisitions(collectionId);
     }
@@ -488,9 +534,15 @@ class BroadcastCollectionCoordinator {
             const reserveTerm = adapter.reserveLeadershipTerm;
             if (!reserveTerm)
               throw new InvalidPersistenceAdapterError(`reserveLeadershipTerm`);
-            const pos = await this.withWriterLock(
-              () => reserveTerm.call(adapter, collectionId, state.latestTerm)
-            );
+            const pos = await this.withWriterLock(() => {
+              const claimId = this.collectionClaimIds.get(collectionId);
+              return reserveTerm.call(
+                adapter,
+                claimId ? managedStorageTarget(collectionId, claimId) : eagerStorageTarget(collectionId),
+                state.latestTerm,
+                { cacheGenerationClaimId: claimId }
+              );
+            });
             state.latestTerm = pos.latestTerm;
             state.latestSeq = pos.latestSeq;
             state.latestRowVersion = pos.latestRowVersion;
@@ -637,6 +689,7 @@ class BroadcastCollectionCoordinator {
     this.releaseLeadership(collectionId, state);
     this.collections.delete(collectionId);
     this.collectionAdapters.delete(collectionId);
+    this.collectionClaimIds.delete(collectionId);
     const prefix = `${JSON.stringify([collectionId]).slice(0, -1)},`;
     for (const key of this.appliedEnvelopes.keys()) {
       if (key.startsWith(prefix)) this.appliedEnvelopes.delete(key);
@@ -1050,10 +1103,7 @@ class BroadcastCollectionCoordinator {
     acquisition.released = true;
     acquisition.release = (async () => {
       try {
-        await acquisition.load;
-      } catch {
-      }
-      try {
+        await acquisition.admitted;
         if (acquisition.transferred) {
           await unloadRemoteSubsetOwner(acquisition.owner, acquisition.options);
         }
@@ -1169,6 +1219,7 @@ class BroadcastCollectionCoordinator {
       owner: options.owner,
       options: options.options,
       load: Promise.resolve(),
+      admitted: Promise.resolve(),
       transferred: false,
       released: false,
       terminalRelease: false,
@@ -1176,6 +1227,10 @@ class BroadcastCollectionCoordinator {
     };
     this.releasedRemoteSubsetAcquisitionTimes.delete(key);
     this.inboundRemoteSubsetAcquisitions.set(key, acquisition);
+    let resolveAdmission;
+    acquisition.admitted = new Promise((resolve) => {
+      resolveAdmission = resolve;
+    });
     let resolveLoad;
     let rejectLoad;
     acquisition.load = new Promise((resolve, reject) => {
@@ -1188,6 +1243,8 @@ class BroadcastCollectionCoordinator {
       void Promise.resolve(load).then(resolveLoad, rejectLoad);
     } catch (error) {
       rejectLoad(error);
+    } finally {
+      resolveAdmission();
     }
     try {
       await acquisition.load;
@@ -1212,10 +1269,23 @@ class BroadcastCollectionCoordinator {
     }
   }
   async handleEnsurePersistedIndex(collectionId, request) {
-    await this.withScheduledWriterLock(
-      collectionId,
-      (adapter) => adapter.ensureIndex(collectionId, request.signature, request.spec)
-    );
+    await this.withScheduledWriterLock(collectionId, (adapter) => {
+      if (request.cacheGenerationClaimId) {
+        return adapter.ensureIndex(
+          managedStorageTarget(collectionId, request.cacheGenerationClaimId),
+          request.signature,
+          request.spec,
+          {
+            cacheGenerationClaimId: request.cacheGenerationClaimId
+          }
+        );
+      }
+      return adapter.ensureIndex(
+        eagerStorageTarget(collectionId),
+        request.signature,
+        request.spec
+      );
+    });
     return {
       type: `rpc:ensurePersistedIndex:res`,
       rpcId: request.rpcId,
@@ -1244,6 +1314,11 @@ class BroadcastCollectionCoordinator {
     });
   }
   async applyLocalMutationsOnce(collectionId, request) {
+    if (this.collectionClaimIds.has(collectionId) && !request.cacheGenerationClaimId) {
+      throw new InvalidPersistedCollectionConfigError(
+        `A managed local mutation requires a persisted cache claim`
+      );
+    }
     const state = this.collections.get(collectionId);
     if (!state || !state.isLeader) {
       return {
@@ -1269,6 +1344,7 @@ class BroadcastCollectionCoordinator {
     }
     const pendingTx = {
       txId: safeRandomUUID(),
+      cacheGenerationClaimId: request.cacheGenerationClaimId,
       mutations: request.mutations.map((m) => ({
         type: m.type,
         key: m.key,
@@ -1501,7 +1577,10 @@ class BroadcastCollectionCoordinator {
         if (!adapter.reconcileCommittedTx) return { kind: `unknown` };
         try {
           const reconciled = await adapter.reconcileCommittedTx(
-            collectionId,
+            candidate.cacheGenerationClaimId ? managedStorageTarget(
+              collectionId,
+              candidate.cacheGenerationClaimId
+            ) : eagerStorageTarget(collectionId),
             candidate,
             request.anchor
           );
@@ -1577,7 +1656,10 @@ class BroadcastCollectionCoordinator {
         );
         if (tx === null) return null;
         try {
-          await adapter.applyCommittedTx(collectionId, tx);
+          await adapter.applyCommittedTx(
+            tx.cacheGenerationClaimId ? managedStorageTarget(collectionId, tx.cacheGenerationClaimId) : eagerStorageTarget(collectionId),
+            tx
+          );
         } catch (error) {
           throw toPersistedCollectionDurabilityError(collectionId, error);
         }
@@ -1602,7 +1684,13 @@ class BroadcastCollectionCoordinator {
         requiresFullReload: true
       };
     }
-    const result = await adapter.pullSince(collectionId, request.fromRowVersion);
+    const result = await adapter.pullSince(
+      request.cacheGenerationClaimId ? managedStorageTarget(collectionId, request.cacheGenerationClaimId) : eagerStorageTarget(collectionId),
+      request.fromRowVersion,
+      {
+        cacheGenerationClaimId: request.cacheGenerationClaimId
+      }
+    );
     if (result.requiresFullReload) {
       return {
         type: `rpc:pullSince:res`,