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

package/README.md

@@ -291,13 +291,22 @@ separate from the accepted-transaction precedence rule.
 ### Atomic resume snapshots
 
 Persistence adapters implement
-`loadResumeSnapshot(collectionId, options)` to let a sync source certify a
+`loadResumeSnapshot(target, options)` to let a sync source certify a
 persisted resume baseline. One call must read rows, collection metadata, stream
 position, reset epoch, and key-set evidence from the same atomic database
 snapshot. `includeRows: false` requests the same certification data without
 materializing rows; `requiredIndexSignatures` carries the indexes needed by a
 row-bearing snapshot.
 
+The adapter's data methods require an explicit `PersistedStorageTarget`. Use
+`{ kind: 'eager', collectionId }` for an eager Collection, or
+`{ kind: 'managed', storageCollectionId, claimId }` for a claimed on-demand
+persisted cache generation. A bare string ID is rejected. The managed target
+checks the claim even after its generation has been collected from SQLite;
+choosing an eager target explicitly may reuse the same ID. Claim and
+rotation methods take the logical Collection ID; renewal takes the physical
+storage ID and release takes the claim ID.
+
 `PersistedKeySetEvidence.status` has three states:
 
 - `consistent`: the persisted rows match the adapter's durable expected-key

package/dist/cjs/broadcast-coordinator.cjs

@@ -5,6 +5,7 @@ const committedTxAnchor = require("./committed-tx-anchor.cjs");
 const errors = require("./errors.cjs");
 const remoteSubsetWire = require("./remote-subset-wire.cjs");
 const remoteSubsetOwner = require("./remote-subset-owner.cjs");
+const persisted = require("./persisted.cjs");
 const HEARTBEAT_INTERVAL_MS = 3e3;
 const LEADERSHIP_RETRY_DELAY_MS = 200;
 const RPC_TIMEOUT_MS = 1e4;
@@ -23,6 +24,7 @@ class BroadcastCollectionCoordinator {
   constructor(options) {
     this.nodeId = db.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();
@@ -78,9 +80,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)) {
@@ -224,10 +231,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 };
@@ -287,7 +313,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);
@@ -304,21 +332,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(
+          persisted.managedStorageTarget(collectionId, cacheGenerationClaimId),
+          signature,
+          spec,
+          {
+            cacheGenerationClaimId
+          }
+        );
+      } else {
+        await adapter.ensureIndex(
+          persisted.eagerStorageTarget(collectionId),
+          signature,
+          spec
+        );
+      }
       return;
     }
     const response = await this.sendRPC(collectionId, {
       type: `rpc:ensurePersistedIndex:req`,
       rpcId: db.safeRandomUUID(),
       signature,
-      spec
+      spec,
+      cacheGenerationClaimId
     });
     if (!response.ok) {
       throw new Error(
@@ -326,7 +367,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)) {
@@ -334,14 +375,16 @@ class BroadcastCollectionCoordinator {
         type: `rpc:applyLocalMutations:req`,
         rpcId: db.safeRandomUUID(),
         envelopeId: db.safeRandomUUID(),
-        mutations
+        mutations,
+        cacheGenerationClaimId
       });
     }
     return this.sendRPC(collectionId, {
       type: `rpc:applyLocalMutations:req`,
       rpcId: db.safeRandomUUID(),
       envelopeId: db.safeRandomUUID(),
-      mutations
+      mutations,
+      cacheGenerationClaimId
     });
   }
   async requestApplyCommittedTx(collectionId, tx, scopedAdapter) {
@@ -382,14 +425,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: db.safeRandomUUID(),
-          fromRowVersion
+          fromRowVersion,
+          cacheGenerationClaimId
         },
         scopedAdapter
       );
@@ -397,7 +441,8 @@ class BroadcastCollectionCoordinator {
     return this.sendRPC(collectionId, {
       type: `rpc:pullSince:req`,
       rpcId: db.safeRandomUUID(),
-      fromRowVersion
+      fromRowVersion,
+      cacheGenerationClaimId
     });
   }
   // -----------------------------------------------------------------------
@@ -430,6 +475,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);
     }
@@ -490,9 +536,15 @@ class BroadcastCollectionCoordinator {
             const reserveTerm = adapter.reserveLeadershipTerm;
             if (!reserveTerm)
               throw new errors.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 ? persisted.managedStorageTarget(collectionId, claimId) : persisted.eagerStorageTarget(collectionId),
+                state.latestTerm,
+                { cacheGenerationClaimId: claimId }
+              );
+            });
             state.latestTerm = pos.latestTerm;
             state.latestSeq = pos.latestSeq;
             state.latestRowVersion = pos.latestRowVersion;
@@ -639,6 +691,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);
@@ -1052,10 +1105,7 @@ class BroadcastCollectionCoordinator {
     acquisition.released = true;
     acquisition.release = (async () => {
       try {
-        await acquisition.load;
-      } catch {
-      }
-      try {
+        await acquisition.admitted;
         if (acquisition.transferred) {
           await remoteSubsetOwner.unloadRemoteSubsetOwner(acquisition.owner, acquisition.options);
         }
@@ -1171,6 +1221,7 @@ class BroadcastCollectionCoordinator {
       owner: options.owner,
       options: options.options,
       load: Promise.resolve(),
+      admitted: Promise.resolve(),
       transferred: false,
       released: false,
       terminalRelease: false,
@@ -1178,6 +1229,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) => {
@@ -1190,6 +1245,8 @@ class BroadcastCollectionCoordinator {
       void Promise.resolve(load).then(resolveLoad, rejectLoad);
     } catch (error) {
       rejectLoad(error);
+    } finally {
+      resolveAdmission();
     }
     try {
       await acquisition.load;
@@ -1214,10 +1271,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(
+          persisted.managedStorageTarget(collectionId, request.cacheGenerationClaimId),
+          request.signature,
+          request.spec,
+          {
+            cacheGenerationClaimId: request.cacheGenerationClaimId
+          }
+        );
+      }
+      return adapter.ensureIndex(
+        persisted.eagerStorageTarget(collectionId),
+        request.signature,
+        request.spec
+      );
+    });
     return {
       type: `rpc:ensurePersistedIndex:res`,
       rpcId: request.rpcId,
@@ -1246,6 +1316,11 @@ class BroadcastCollectionCoordinator {
     });
   }
   async applyLocalMutationsOnce(collectionId, request) {
+    if (this.collectionClaimIds.has(collectionId) && !request.cacheGenerationClaimId) {
+      throw new errors.InvalidPersistedCollectionConfigError(
+        `A managed local mutation requires a persisted cache claim`
+      );
+    }
     const state = this.collections.get(collectionId);
     if (!state || !state.isLeader) {
       return {
@@ -1271,6 +1346,7 @@ class BroadcastCollectionCoordinator {
     }
     const pendingTx = {
       txId: db.safeRandomUUID(),
+      cacheGenerationClaimId: request.cacheGenerationClaimId,
       mutations: request.mutations.map((m) => ({
         type: m.type,
         key: m.key,
@@ -1503,7 +1579,10 @@ class BroadcastCollectionCoordinator {
         if (!adapter.reconcileCommittedTx) return { kind: `unknown` };
         try {
           const reconciled = await adapter.reconcileCommittedTx(
-            collectionId,
+            candidate.cacheGenerationClaimId ? persisted.managedStorageTarget(
+              collectionId,
+              candidate.cacheGenerationClaimId
+            ) : persisted.eagerStorageTarget(collectionId),
             candidate,
             request.anchor
           );
@@ -1579,7 +1658,10 @@ class BroadcastCollectionCoordinator {
         );
         if (tx === null) return null;
         try {
-          await adapter.applyCommittedTx(collectionId, tx);
+          await adapter.applyCommittedTx(
+            tx.cacheGenerationClaimId ? persisted.managedStorageTarget(collectionId, tx.cacheGenerationClaimId) : persisted.eagerStorageTarget(collectionId),
+            tx
+          );
         } catch (error) {
           throw errors.toPersistedCollectionDurabilityError(collectionId, error);
         }
@@ -1604,7 +1686,13 @@ class BroadcastCollectionCoordinator {
         requiresFullReload: true
       };
     }
-    const result = await adapter.pullSince(collectionId, request.fromRowVersion);
+    const result = await adapter.pullSince(
+      request.cacheGenerationClaimId ? persisted.managedStorageTarget(collectionId, request.cacheGenerationClaimId) : persisted.eagerStorageTarget(collectionId),
+      request.fromRowVersion,
+      {
+        cacheGenerationClaimId: request.cacheGenerationClaimId
+      }
+    );
     if (result.requiresFullReload) {
       return {
         type: `rpc:pullSince:res`,