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

package/dist/esm/sqlite-core-adapter.js

@@ -1,7 +1,8 @@
-import { IR, toBooleanPredicate, compileSingleRowExpression, compareTemporalValues } from "@tanstack/db";
+import { safeRandomUUID, IR, toBooleanPredicate, compileSingleRowExpression, compareTemporalValues } from "@tanstack/db";
 import { InvalidPersistedCollectionConfigError, InvalidPersistedStorageKeyEncodingError } from "./errors.js";
-import { encodePersistedStorageKey, createPersistedTableName, decodePersistedStorageKey, SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY } from "./persisted.js";
-import { serializeSQLiteTemporal, sqliteTemporalIdentity, assertSQLiteBigIntInRange, sqliteTemporalKind, PERSISTED_TYPE_TAG, PERSISTED_VALUE_TAG, reviveSQLiteTemporal, serializeSQLiteBigInt } from "./sqlite-value.js";
+import { isValidCommittedTxAnchor } from "./committed-tx-anchor.js";
+import { resolvePersistedStorageTarget, encodePersistedStorageKey, createPersistedTableName, decodePersistedStorageKey, SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY } from "./persisted.js";
+import { serializeSQLiteTemporal, sqliteTemporalIdentity, assertSQLiteBigIntInRange, sqliteTemporalKind, serializeSQLiteBigInt, PERSISTED_VALUE_TAG, PERSISTED_TYPE_TAG, reviveSQLiteTemporal } from "./sqlite-value.js";
 const REPLACEMENT_BATCH_SIZE = 125;
 class SharedPersistenceScheduler {
   constructor() {
@@ -105,6 +106,12 @@ function observeSharedLogicalSchedulingSupport(driver, onSupport) {
   };
 }
 const DEFAULT_SCHEMA_VERSION = 1;
+const CACHE_GENERATION_ID_PREFIX = `tanstack-db-cache:`;
+const LEGACY_CACHE_GENERATION_ID_PREFIX = `\0tanstack-db-cache:`;
+function hasCacheGenerationIdPrefix(collectionId) {
+  return collectionId.startsWith(CACHE_GENERATION_ID_PREFIX) || collectionId.startsWith(LEGACY_CACHE_GENERATION_ID_PREFIX);
+}
+const DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS = 5 * 6e4;
 const DEFAULT_PULL_SINCE_RELOAD_THRESHOLD = 128;
 const DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS = 1e3;
 const DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS = 24 * 60 * 60;
@@ -1046,6 +1053,13 @@ class SQLiteCorePersistenceAdapter {
       );
     }
     this.replacementBatchSize = maxBoundParameters === void 0 ? REPLACEMENT_BATCH_SIZE : Math.min(REPLACEMENT_BATCH_SIZE, Math.floor(maxBoundParameters / 4));
+    this.cacheGenerationClaimTtlMs = options.cacheGenerationClaimTtlMs ?? DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS;
+    if (!Number.isSafeInteger(this.cacheGenerationClaimTtlMs) || this.cacheGenerationClaimTtlMs <= 0) {
+      throw new InvalidPersistedCollectionConfigError(
+        `SQLite adapter cacheGenerationClaimTtlMs must be a positive safe integer`
+      );
+    }
+    this.now = options.now ?? Date.now;
     const schemaVersion = options.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
     if (!Number.isInteger(schemaVersion) || schemaVersion < 0) {
       throw new InvalidPersistedCollectionConfigError(
@@ -1088,15 +1102,257 @@ class SQLiteCorePersistenceAdapter {
       loadSubset: (collectionId, loadOptions, context) => this.loadSubsetUnscheduled(collectionId, loadOptions, context),
       loadResumeSnapshot: (collectionId, context) => this.loadResumeSnapshotUnscheduled(collectionId, context),
       applyCommittedTx: (collectionId, tx) => this.applyCommittedTxUnscheduled(collectionId, tx),
-      loadCollectionMetadata: (collectionId) => this.loadCollectionMetadataUnscheduled(collectionId),
-      scanRows: (collectionId, scanOptions) => this.scanRowsUnscheduled(collectionId, scanOptions),
-      ensureIndex: (collectionId, signature, spec) => this.ensureIndexUnscheduled(collectionId, signature, spec),
-      markIndexRemoved: (collectionId, signature) => this.markIndexRemovedUnscheduled(collectionId, signature),
-      getStreamPosition: (collectionId) => this.getStreamPositionUnscheduled(collectionId),
-      pullSince: (collectionId, fromRowVersion) => this.pullSinceUnscheduled(collectionId, fromRowVersion),
+      renewCacheGenerationClaim: (storageCollectionId, claimId) => this.renewCacheGenerationClaimUnscheduled(storageCollectionId, claimId),
+      reconcileCommittedTx: (collectionId, tx, anchor) => this.reconcileCommittedTxUnscheduled(collectionId, tx, anchor),
+      loadCollectionMetadata: (collectionId, context) => this.loadCollectionMetadataUnscheduled(collectionId, context),
+      scanRows: (collectionId, scanOptions, context) => this.scanRowsUnscheduled(collectionId, scanOptions, context),
+      ensureIndex: (collectionId, signature, spec, ctx) => this.ensureIndexUnscheduled(collectionId, signature, spec, ctx),
+      markIndexRemoved: (collectionId, signature, ctx) => this.markIndexRemovedUnscheduled(collectionId, signature, ctx),
+      getStreamPosition: (collectionId, ctx) => this.getStreamPositionUnscheduled(collectionId, ctx),
+      pullSince: (collectionId, fromRowVersion, ctx) => this.pullSinceUnscheduled(collectionId, fromRowVersion, ctx),
       runInHydrationScope: async (task) => task(this.hydrationAdapter)
     };
   }
+  claimCacheGeneration(collectionId) {
+    return this.runRegular(async () => {
+      await this.ensureInitialized();
+      return this.driver.transaction(async (driver) => {
+        const expiresAtMs = this.now() + this.cacheGenerationClaimTtlMs;
+        const initialPhysicalId = `${CACHE_GENERATION_ID_PREFIX}${safeRandomUUID()}`;
+        await driver.run(
+          `INSERT INTO cache_generation (logical_id, generation, physical_id, retired)
+           SELECT ?, 0, ?, 0
+           WHERE NOT EXISTS (
+             SELECT 1 FROM cache_generation WHERE logical_id = ?
+           )`,
+          [collectionId, initialPhysicalId, collectionId]
+        );
+        const head = await driver.query(
+          `SELECT physical_id FROM cache_generation
+           WHERE logical_id = ? AND retired = 0`,
+          [collectionId]
+        );
+        const storageCollectionId = head[0]?.physical_id;
+        if (!storageCollectionId) {
+          throw new InvalidPersistedCollectionConfigError(
+            `No active persisted cache generation for collection "${collectionId}"`
+          );
+        }
+        const claimId = safeRandomUUID();
+        await driver.run(
+          `INSERT INTO cache_generation_claim
+             (claim_id, logical_id, physical_id, expires_at_ms)
+           VALUES (?, ?, ?, ?)`,
+          [claimId, collectionId, storageCollectionId, expiresAtMs]
+        );
+        await this.collectRetiredCacheGenerations(driver);
+        return { storageCollectionId, claimId, expiresAtMs };
+      });
+    });
+  }
+  rotateCacheGeneration(collectionId, claimId, resetMetadata, expectedStorageCollectionId) {
+    return this.runRegular(async () => {
+      await this.ensureInitialized();
+      return this.driver.transaction(async (driver) => {
+        const now = this.now();
+        const expiresAtMs = now + this.cacheGenerationClaimTtlMs;
+        const claimed = await driver.query(
+          `SELECT physical_id, expires_at_ms
+           FROM cache_generation_claim
+           WHERE claim_id = ? AND logical_id = ?`,
+          [claimId, collectionId]
+        );
+        const claimedPhysicalId = claimed[0] && claimed[0].expires_at_ms > now ? claimed[0].physical_id : void 0;
+        if (claimedPhysicalId && expectedStorageCollectionId && claimedPhysicalId !== expectedStorageCollectionId) {
+          throw new InvalidPersistedCollectionConfigError(
+            `Persisted cache claim changed generations before recovery`
+          );
+        }
+        const head = await driver.query(
+          `SELECT generation, physical_id FROM cache_generation
+           WHERE logical_id = ? AND retired = 0`,
+          [collectionId]
+        );
+        const active = head[0];
+        if (!active) {
+          throw new InvalidPersistedCollectionConfigError(
+            `No active persisted cache generation for collection "${collectionId}"`
+          );
+        }
+        await driver.run(
+          `INSERT INTO cache_generation_sequence (logical_id, next_generation)
+           SELECT ?, COALESCE(MAX(generation), -1) + 1
+           FROM cache_generation WHERE logical_id = ?
+           ON CONFLICT(logical_id) DO NOTHING`,
+          [collectionId, collectionId]
+        );
+        const nextRows = await driver.query(
+          `SELECT next_generation FROM cache_generation_sequence
+           WHERE logical_id = ?`,
+          [collectionId]
+        );
+        const nextGeneration = nextRows[0].next_generation;
+        await driver.run(
+          `UPDATE cache_generation_sequence SET next_generation = ?
+           WHERE logical_id = ?`,
+          [nextGeneration + 1, collectionId]
+        );
+        const ownedHead = claimedPhysicalId === active.physical_id;
+        const storageCollectionId = `${CACHE_GENERATION_ID_PREFIX}${safeRandomUUID()}`;
+        if (ownedHead) {
+          await driver.run(
+            `UPDATE cache_generation SET retired = 1
+             WHERE logical_id = ? AND generation = ?`,
+            [collectionId, active.generation]
+          );
+        }
+        await driver.run(
+          `INSERT INTO cache_generation (logical_id, generation, physical_id, retired)
+           VALUES (?, ?, ?, ?)`,
+          [
+            collectionId,
+            nextGeneration,
+            storageCollectionId,
+            ownedHead ? 0 : 1
+          ]
+        );
+        const nextClaimId = claimed[0] ? claimId : safeRandomUUID();
+        if (claimed[0]) {
+          await driver.run(
+            `UPDATE cache_generation_claim
+             SET physical_id = ?, expires_at_ms = ? WHERE claim_id = ?`,
+            [storageCollectionId, expiresAtMs, claimId]
+          );
+        } else {
+          await driver.run(
+            `INSERT INTO cache_generation_claim
+               (claim_id, logical_id, physical_id, expires_at_ms)
+             VALUES (?, ?, ?, ?)`,
+            [nextClaimId, collectionId, storageCollectionId, expiresAtMs]
+          );
+        }
+        await driver.run(
+          `INSERT INTO collection_version (
+             collection_id, latest_row_version,
+             key_set_evidence_available, key_set_evidence_incompatible
+           ) VALUES (?, 0, 1, 1)`,
+          [storageCollectionId]
+        );
+        if (resetMetadata) {
+          await driver.run(
+            `INSERT INTO collection_metadata (collection_id, key, value, updated_at)
+             VALUES (?, ?, ?, CAST(strftime('%s', 'now') AS INTEGER))`,
+            [
+              storageCollectionId,
+              resetMetadata.key,
+              serializePersistedRowValue(resetMetadata.value)
+            ]
+          );
+        }
+        await this.collectRetiredCacheGenerations(driver);
+        return { storageCollectionId, claimId: nextClaimId, expiresAtMs };
+      });
+    });
+  }
+  releaseCacheGenerationClaim(claimId) {
+    return this.runRegular(async () => {
+      await this.ensureInitialized();
+      await this.runInTransaction(async (driver) => {
+        await driver.run(
+          `DELETE FROM cache_generation_claim WHERE claim_id = ?`,
+          [claimId]
+        );
+        await this.collectRetiredCacheGenerations(driver);
+      });
+    });
+  }
+  renewCacheGenerationClaim(storageCollectionId, claimId) {
+    return this.runRegular(
+      () => this.renewCacheGenerationClaimUnscheduled(storageCollectionId, claimId)
+    );
+  }
+  async renewCacheGenerationClaimUnscheduled(storageCollectionId, claimId) {
+    await this.ensureInitialized();
+    return this.runInTransaction(async (driver) => {
+      const now = this.now();
+      const rows = await driver.query(
+        `SELECT claim_id FROM cache_generation_claim
+           WHERE claim_id = ? AND physical_id = ? AND expires_at_ms > ?`,
+        [claimId, storageCollectionId, now]
+      );
+      if (!rows[0]) {
+        await this.collectRetiredCacheGenerations(driver);
+        return void 0;
+      }
+      const expiresAtMs = now + this.cacheGenerationClaimTtlMs;
+      await driver.run(
+        `UPDATE cache_generation_claim SET expires_at_ms = ?
+           WHERE claim_id = ?`,
+        [expiresAtMs, claimId]
+      );
+      return expiresAtMs;
+    });
+  }
+  async collectRetiredCacheGenerations(driver) {
+    await driver.run(
+      `DELETE FROM cache_generation_claim WHERE expires_at_ms <= ?`,
+      [this.now()]
+    );
+    const retired = await driver.query(
+      `SELECT generation.physical_id, registry.table_name,
+              registry.tombstone_table_name
+       FROM cache_generation AS generation
+       LEFT JOIN collection_registry AS registry
+         ON registry.collection_id = generation.physical_id
+       WHERE generation.retired = 1
+         AND NOT EXISTS (
+           SELECT 1 FROM cache_generation_claim AS claim
+           WHERE claim.physical_id = generation.physical_id
+         )`
+    );
+    for (const generation of retired) {
+      if (generation.table_name) {
+        await driver.exec(
+          `DROP TABLE IF EXISTS ${quoteIdentifier(generation.table_name)}`
+        );
+      }
+      if (generation.tombstone_table_name) {
+        await driver.exec(
+          `DROP TABLE IF EXISTS ${quoteIdentifier(generation.tombstone_table_name)}`
+        );
+      }
+      for (const table of [
+        `applied_tx`,
+        `collection_expected_keys`,
+        `collection_metadata`,
+        `persisted_index_registry`,
+        `leader_term`
+      ]) {
+        await driver.run(`DELETE FROM ${table} WHERE collection_id = ?`, [
+          generation.physical_id
+        ]);
+      }
+      await driver.run(
+        `DELETE FROM collection_version WHERE collection_id = ?`,
+        [generation.physical_id]
+      );
+      await driver.run(
+        `DELETE FROM collection_reset_epoch WHERE collection_id = ?`,
+        [generation.physical_id]
+      );
+      await driver.run(
+        `DELETE FROM collection_registry WHERE collection_id = ?`,
+        [generation.physical_id]
+      );
+      await driver.run(`DELETE FROM cache_generation WHERE physical_id = ?`, [
+        generation.physical_id
+      ]);
+      this.collectionTableCache.delete(generation.physical_id);
+    }
+  }
+  getCacheGenerationNow() {
+    return this.now();
+  }
   runInHydrationScope(task) {
     const scheduler = this.resolveScheduler();
     if (scheduler) {
@@ -1151,14 +1407,63 @@ class SQLiteCorePersistenceAdapter {
       );
     }
   }
-  loadSubset(collectionId, options, ctx) {
+  async assertCacheGenerationReadClaim(driver, storageCollectionId, claimId) {
+    await this.ensureInitialized();
+    if (!claimId) {
+      if (!hasCacheGenerationIdPrefix(storageCollectionId)) return;
+      const generation = await driver.query(
+        `SELECT physical_id FROM cache_generation WHERE physical_id = ?`,
+        [storageCollectionId]
+      );
+      if (generation[0]) {
+        throw new InvalidPersistedCollectionConfigError(
+          `Persisted cache claim is required for collection "${storageCollectionId}"`
+        );
+      }
+      return;
+    }
+    const rows = await driver.query(
+      `SELECT claim.claim_id
+       FROM cache_generation_claim AS claim
+       JOIN cache_generation AS generation
+         ON generation.physical_id = claim.physical_id
+       WHERE claim.claim_id = ? AND claim.physical_id = ?
+         AND claim.expires_at_ms > ?`,
+      [claimId, storageCollectionId, this.now()]
+    );
+    if (!rows[0]) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Persisted cache claim is no longer active for collection "${storageCollectionId}"`
+      );
+    }
+  }
+  loadSubset(target, options, ctx) {
     return this.runRegular(
-      () => this.loadSubsetUnscheduled(collectionId, options, ctx)
+      () => this.loadSubsetUnscheduled(target, options, ctx)
     );
   }
-  async loadSubsetUnscheduled(collectionId, options, ctx) {
-    const tableMapping = await this.ensureCollectionReady(collectionId);
+  async loadSubsetUnscheduled(target, options, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    const tableMapping = await this.ensureCollectionReady(
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
     return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1217,15 +1522,34 @@ class SQLiteCorePersistenceAdapter {
       }));
     });
   }
-  loadResumeSnapshot(collectionId, ctx) {
+  loadResumeSnapshot(target, ctx) {
     return this.runRegular(
-      () => this.loadResumeSnapshotUnscheduled(collectionId, ctx)
+      () => this.loadResumeSnapshotUnscheduled(target, ctx)
     );
   }
-  async loadResumeSnapshotUnscheduled(collectionId, ctx) {
-    const tableMapping = await this.ensureCollectionReady(collectionId);
+  async loadResumeSnapshotUnscheduled(target, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    const tableMapping = await this.ensureCollectionReady(
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
     const includeRows = ctx?.includeRows !== false;
     return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1278,20 +1602,55 @@ class SQLiteCorePersistenceAdapter {
       };
     });
   }
-  applyCommittedTx(collectionId, tx) {
+  applyCommittedTx(target, tx) {
+    return this.runRegular(() => this.applyCommittedTxUnscheduled(target, tx));
+  }
+  reconcileCommittedTx(target, tx, anchor) {
     return this.runRegular(
-      () => this.applyCommittedTxUnscheduled(collectionId, tx)
+      () => this.reconcileCommittedTxUnscheduled(target, tx, anchor)
     );
   }
-  async applyCommittedTxUnscheduled(collectionId, tx) {
-    const tableMapping = await this.ensureCollectionReady(collectionId);
+  async applyCommittedTxUnscheduled(target, tx) {
+    await this.applyCommittedTxInternal(target, tx);
+  }
+  reconcileCommittedTxUnscheduled(target, tx, anchor) {
+    if (!isValidCommittedTxAnchor(anchor)) {
+      throw new Error(
+        `Cannot reconcile a committed transaction without a valid durable anchor`
+      );
+    }
+    return this.applyCommittedTxInternal(target, tx, anchor);
+  }
+  async applyCommittedTxInternal(target, tx, anchor) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      tx.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    tx = { ...tx, cacheGenerationClaimId: access.claimId };
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      tx.cacheGenerationClaimId
+    );
+    const tableMapping = await this.ensureCollectionReady(
+      collectionId,
+      tx.cacheGenerationClaimId
+    );
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const tombstoneTableSql = quoteIdentifier(tableMapping.tombstoneTableName);
-    await this.runInTransaction(async (transactionDriver) => {
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        tx.cacheGenerationClaimId
+      );
       const versionRows = await transactionDriver.query(
         `SELECT
            latest_row_version,
            key_set_evidence_available,
+           (SELECT reset_epoch FROM collection_reset_epoch
+            WHERE collection_id = ? LIMIT 1) AS reset_epoch,
            (
              SELECT schema_version
              FROM collection_registry
@@ -1306,7 +1665,14 @@ class SQLiteCorePersistenceAdapter {
          FROM collection_version
          WHERE collection_id = ?
          LIMIT 1`,
-        [collectionId, collectionId, tx.term, tx.seq, collectionId]
+        [
+          collectionId,
+          collectionId,
+          collectionId,
+          tx.term,
+          tx.seq,
+          collectionId
+        ]
       );
       const version = versionRows[0];
       if (!version) {
@@ -1319,8 +1685,34 @@ class SQLiteCorePersistenceAdapter {
           `Schema version mismatch for collection "${collectionId}": found ${version.schema_version}, expected ${this.schemaVersion}. Refusing to apply a committed transaction through a stale cached adapter.`
         );
       }
+      if (anchor) {
+        const sameResetEpoch = (version.reset_epoch ?? 0) === anchor.resetEpoch;
+        const matching = await transactionDriver.query(
+          `SELECT term, seq, row_version FROM applied_tx
+           WHERE collection_id = ? AND tx_id = ? LIMIT 2`,
+          [collectionId, tx.txId]
+        );
+        if (matching.length > 1) return { kind: `unknown` };
+        if (matching[0]) {
+          if (matching[0].row_version <= anchor.latestRowVersion || !sameResetEpoch) {
+            return { kind: `unknown` };
+          }
+          return {
+            kind: `already-applied`,
+            committed: {
+              term: matching[0].term,
+              seq: matching[0].seq,
+              rowVersion: matching[0].row_version
+            },
+            latestRowVersion: version.latest_row_version
+          };
+        }
+        if (version.latest_row_version !== anchor.latestRowVersion || !sameResetEpoch) {
+          return { kind: `unknown` };
+        }
+      }
       if (version.already_applied === 1) {
-        return;
+        return { kind: `unknown` };
       }
       const currentRowVersion = version.latest_row_version;
       const nextRowVersion = Math.max(currentRowVersion + 1, tx.rowVersion);
@@ -1568,16 +1960,41 @@ class SQLiteCorePersistenceAdapter {
         ]
       );
       await this.pruneAppliedTxRows(collectionId, transactionDriver);
+      return {
+        kind: `applied-now`,
+        committed: {
+          term: tx.term,
+          seq: tx.seq,
+          rowVersion: nextRowVersion
+        },
+        latestRowVersion: nextRowVersion
+      };
     });
   }
-  loadCollectionMetadata(collectionId) {
+  loadCollectionMetadata(target, ctx) {
     return this.runRegular(
-      () => this.loadCollectionMetadataUnscheduled(collectionId)
+      () => this.loadCollectionMetadataUnscheduled(target, ctx)
     );
   }
-  async loadCollectionMetadataUnscheduled(collectionId) {
-    await this.ensureCollectionReady(collectionId);
+  async loadCollectionMetadataUnscheduled(target, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    await this.ensureCollectionReady(collectionId, ctx?.cacheGenerationClaimId);
     return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1595,15 +2012,32 @@ class SQLiteCorePersistenceAdapter {
       }));
     });
   }
-  scanRows(collectionId, options) {
-    return this.runRegular(
-      () => this.scanRowsUnscheduled(collectionId, options)
-    );
+  scanRows(target, options, ctx) {
+    return this.runRegular(() => this.scanRowsUnscheduled(target, options, ctx));
   }
-  async scanRowsUnscheduled(collectionId, options) {
-    const tableMapping = await this.ensureCollectionReady(collectionId);
+  async scanRowsUnscheduled(target, options, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    const tableMapping = await this.ensureCollectionReady(
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1622,13 +2056,27 @@ class SQLiteCorePersistenceAdapter {
       }));
     });
   }
-  ensureIndex(collectionId, signature, spec) {
+  ensureIndex(target, signature, spec, ctx) {
     return this.runRegular(
-      () => this.ensureIndexUnscheduled(collectionId, signature, spec)
+      () => this.ensureIndexUnscheduled(target, signature, spec, ctx)
     );
   }
-  async ensureIndexUnscheduled(collectionId, signature, spec) {
-    const tableMapping = await this.ensureCollectionReady(collectionId);
+  async ensureIndexUnscheduled(target, signature, spec, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    const tableMapping = await this.ensureCollectionReady(
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const indexName = buildIndexName(collectionId, signature);
     const indexNameSql = quoteIdentifier(indexName);
@@ -1640,6 +2088,11 @@ class SQLiteCorePersistenceAdapter {
     const whereSql = spec.whereSql ? normalizeIndexSqlFragment(spec.whereSql) : void 0;
     const persistedWhereSql = whereSql ?? null;
     await this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1696,14 +2149,30 @@ class SQLiteCorePersistenceAdapter {
       await transactionDriver.exec(createIndexSql);
     });
   }
-  markIndexRemoved(collectionId, signature) {
+  markIndexRemoved(target, signature, ctx) {
     return this.runRegular(
-      () => this.markIndexRemovedUnscheduled(collectionId, signature)
+      () => this.markIndexRemovedUnscheduled(target, signature, ctx)
     );
   }
-  async markIndexRemovedUnscheduled(collectionId, signature) {
-    await this.ensureCollectionReady(collectionId);
+  async markIndexRemovedUnscheduled(target, signature, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    await this.ensureCollectionReady(collectionId, ctx?.cacheGenerationClaimId);
     await this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1732,12 +2201,69 @@ class SQLiteCorePersistenceAdapter {
       }
     });
   }
-  getStreamPosition(collectionId) {
-    return this.getStreamPositionUnscheduled(collectionId);
+  reserveLeadershipTerm(target, observedTerm, ctx) {
+    return this.reserveLeadershipTermUnscheduled(target, observedTerm, ctx);
   }
-  async getStreamPositionUnscheduled(collectionId) {
-    await this.ensureCollectionReady(collectionId);
+  async reserveLeadershipTermUnscheduled(target, observedTerm, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    await this.ensureCollectionReady(collectionId, ctx?.cacheGenerationClaimId);
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `reserve a leadership term`
+      );
+      await transactionDriver.run(
+        `INSERT INTO leader_term (collection_id, latest_term)
+         VALUES (?, ? + 1)
+         ON CONFLICT(collection_id) DO UPDATE SET
+           latest_term = MAX(leader_term.latest_term, ?) + 1`,
+        [collectionId, observedTerm, observedTerm]
+      );
+      const [position, latestRowVersion] = await Promise.all([
+        this.readStreamPosition(collectionId, transactionDriver),
+        this.readLatestRowVersion(collectionId, transactionDriver)
+      ]);
+      return { ...position, latestRowVersion };
+    });
+  }
+  getStreamPosition(target, ctx) {
+    return this.getStreamPositionUnscheduled(target, ctx);
+  }
+  async getStreamPositionUnscheduled(target, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    await this.ensureCollectionReady(collectionId, ctx?.cacheGenerationClaimId);
     return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -1805,16 +2331,35 @@ class SQLiteCorePersistenceAdapter {
       }
     };
   }
-  pullSince(collectionId, fromRowVersion) {
+  pullSince(target, fromRowVersion, ctx) {
     return this.runRegular(
-      () => this.pullSinceUnscheduled(collectionId, fromRowVersion)
+      () => this.pullSinceUnscheduled(target, fromRowVersion, ctx)
     );
   }
-  async pullSinceUnscheduled(collectionId, fromRowVersion) {
-    const tableMapping = await this.ensureCollectionReady(collectionId);
+  async pullSinceUnscheduled(target, fromRowVersion, ctx) {
+    const access = resolvePersistedStorageTarget(
+      target,
+      ctx?.cacheGenerationClaimId
+    );
+    const collectionId = access.collectionId;
+    ctx = access.claimId ? { ...ctx, cacheGenerationClaimId: access.claimId } : ctx;
+    await this.assertCacheGenerationReadClaim(
+      this.driver,
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
+    const tableMapping = await this.ensureCollectionReady(
+      collectionId,
+      ctx?.cacheGenerationClaimId
+    );
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const tombstoneTableSql = quoteIdentifier(tableMapping.tombstoneTableName);
     return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        ctx?.cacheGenerationClaimId
+      );
       await this.assertCurrentSchemaVersion(
         collectionId,
         transactionDriver,
@@ -2050,7 +2595,7 @@ class SQLiteCorePersistenceAdapter {
       [collectionId, excessRows]
     );
   }
-  async ensureCollectionReady(collectionId) {
+  async ensureCollectionReady(collectionId, cacheGenerationClaimId) {
     await this.ensureInitialized();
     const cached = this.collectionTableCache.get(collectionId);
     if (cached) {
@@ -2060,7 +2605,10 @@ class SQLiteCorePersistenceAdapter {
     if (inFlight) {
       return inFlight;
     }
-    const loadPromise = this.ensureCollectionReadyInternal(collectionId);
+    const loadPromise = this.ensureCollectionReadyInternal(
+      collectionId,
+      cacheGenerationClaimId
+    );
     this.collectionTableLoads.set(collectionId, loadPromise);
     try {
       return await loadPromise;
@@ -2078,23 +2626,34 @@ class SQLiteCorePersistenceAdapter {
     );
     return rows[0];
   }
-  async ensureCollectionReadyInternal(collectionId) {
+  async ensureCollectionReadyInternal(collectionId, cacheGenerationClaimId) {
+    const managedAtAdmission = cacheGenerationClaimId !== void 0 || hasCacheGenerationIdPrefix(collectionId) && (await this.driver.query(
+      `SELECT physical_id FROM cache_generation WHERE physical_id = ?`,
+      [collectionId]
+    ))[0] !== void 0;
     let registration = await this.loadCollectionRegistration(collectionId);
     if (!registration) {
       const tableName2 = createPersistedTableName(collectionId, `c`);
       const tombstoneTableName2 = createPersistedTableName(collectionId, `t`);
-      await this.driver.run(
-        `INSERT INTO collection_registry (
-           collection_id,
-           table_name,
-           tombstone_table_name,
-           schema_version,
-           updated_at
-         )
-         VALUES (?, ?, ?, ?, CAST(strftime('%s', 'now') AS INTEGER))
-         ON CONFLICT DO NOTHING`,
-        [collectionId, tableName2, tombstoneTableName2, this.schemaVersion]
-      );
+      await this.runInTransaction(async (transactionDriver) => {
+        await this.assertCacheGenerationReadClaim(
+          transactionDriver,
+          collectionId,
+          cacheGenerationClaimId
+        );
+        await transactionDriver.run(
+          `INSERT INTO collection_registry (
+             collection_id,
+             table_name,
+             tombstone_table_name,
+             schema_version,
+             updated_at
+           )
+           VALUES (?, ?, ?, ?, CAST(strftime('%s', 'now') AS INTEGER))
+           ON CONFLICT DO NOTHING`,
+          [collectionId, tableName2, tombstoneTableName2, this.schemaVersion]
+        );
+      });
       registration = await this.loadCollectionRegistration(collectionId);
       if (!registration) {
         throw new InvalidPersistedCollectionConfigError(
@@ -2110,7 +2669,8 @@ class SQLiteCorePersistenceAdapter {
         registration.schema_version,
         this.schemaVersion,
         tableName,
-        tombstoneTableName
+        tombstoneTableName,
+        cacheGenerationClaimId
       );
     }
     const collectionTableSql = quoteIdentifier(tableName);
@@ -2157,6 +2717,35 @@ class SQLiteCorePersistenceAdapter {
       [collectionId]
     );
     await this.ensureCollectionKeyEvidenceTriggers(collectionId, tableName);
+    if (managedAtAdmission) {
+      const generation = await this.driver.query(
+        `SELECT physical_id FROM cache_generation WHERE physical_id = ?`,
+        [collectionId]
+      );
+      if (!generation[0]) {
+        await this.driver.exec(
+          `DROP TABLE IF EXISTS ${quoteIdentifier(tableName)}`
+        );
+        await this.driver.exec(
+          `DROP TABLE IF EXISTS ${quoteIdentifier(tombstoneTableName)}`
+        );
+        await this.driver.run(
+          `DELETE FROM collection_registry WHERE collection_id = ?`,
+          [collectionId]
+        );
+        await this.driver.run(
+          `DELETE FROM collection_version WHERE collection_id = ?`,
+          [collectionId]
+        );
+        await this.driver.run(
+          `DELETE FROM collection_reset_epoch WHERE collection_id = ?`,
+          [collectionId]
+        );
+        throw new InvalidPersistedCollectionConfigError(
+          `Persisted cache generation was collected before registration finished`
+        );
+      }
+    }
     const mapping = {
       tableName,
       tombstoneTableName
@@ -2226,7 +2815,7 @@ class SQLiteCorePersistenceAdapter {
        END`
     );
   }
-  async handleSchemaMismatch(collectionId, previousSchemaVersion, nextSchemaVersion, tableName, tombstoneTableName) {
+  async handleSchemaMismatch(collectionId, previousSchemaVersion, nextSchemaVersion, tableName, tombstoneTableName, cacheGenerationClaimId) {
     if (this.schemaMismatchPolicy === `sync-absent-error`) {
       throw new InvalidPersistedCollectionConfigError(
         `Schema version mismatch for collection "${collectionId}": found ${previousSchemaVersion}, expected ${nextSchemaVersion}. Set schemaMismatchPolicy to "sync-present-reset" or "reset" to allow automatic reset.`
@@ -2235,6 +2824,11 @@ class SQLiteCorePersistenceAdapter {
     const collectionTableSql = quoteIdentifier(tableName);
     const tombstoneTableSql = quoteIdentifier(tombstoneTableName);
     await this.runInTransaction(async (transactionDriver) => {
+      await this.assertCacheGenerationReadClaim(
+        transactionDriver,
+        collectionId,
+        cacheGenerationClaimId
+      );
       const currentSchemaRows = await transactionDriver.query(
         `SELECT schema_version
          FROM collection_registry
@@ -2319,6 +2913,48 @@ class SQLiteCorePersistenceAdapter {
     if (this.initialized) {
       return;
     }
+    await this.driver.exec(
+      `CREATE TABLE IF NOT EXISTS cache_generation (
+         logical_id TEXT NOT NULL,
+         generation INTEGER NOT NULL,
+         physical_id TEXT NOT NULL UNIQUE,
+         retired INTEGER NOT NULL DEFAULT 0,
+         PRIMARY KEY (logical_id, generation)
+       )`
+    );
+    await this.driver.exec(
+      `CREATE UNIQUE INDEX IF NOT EXISTS cache_generation_head
+       ON cache_generation (logical_id) WHERE retired = 0`
+    );
+    await this.driver.exec(
+      `CREATE TABLE IF NOT EXISTS cache_generation_sequence (
+         logical_id TEXT PRIMARY KEY,
+         next_generation INTEGER NOT NULL
+       )`
+    );
+    await this.driver.exec(
+      `CREATE TABLE IF NOT EXISTS cache_generation_claim (
+         claim_id TEXT PRIMARY KEY,
+         logical_id TEXT NOT NULL,
+         physical_id TEXT NOT NULL,
+         expires_at_ms INTEGER NOT NULL
+       )`
+    );
+    const claimColumns = await this.driver.query(
+      `PRAGMA table_info(cache_generation_claim)`
+    );
+    if (!claimColumns.some(({ name }) => name === `logical_id`)) {
+      await this.driver.exec(
+        `ALTER TABLE cache_generation_claim
+         ADD COLUMN logical_id TEXT NOT NULL DEFAULT ''`
+      );
+    }
+    if (!claimColumns.some(({ name }) => name === `expires_at_ms`)) {
+      await this.driver.exec(
+        `ALTER TABLE cache_generation_claim
+         ADD COLUMN expires_at_ms INTEGER NOT NULL DEFAULT 0`
+      );
+    }
     await this.driver.exec(
       `CREATE TABLE IF NOT EXISTS collection_registry (
          collection_id TEXT PRIMARY KEY,
@@ -2355,6 +2991,10 @@ class SQLiteCorePersistenceAdapter {
          PRIMARY KEY (collection_id, term, seq)
        )`
     );
+    await this.driver.exec(
+      `CREATE INDEX IF NOT EXISTS idx_applied_tx_collection_tx_id
+       ON applied_tx (collection_id, tx_id)`
+    );
     try {
       await this.driver.exec(
         `ALTER TABLE applied_tx ADD COLUMN replay_json TEXT`
@@ -2455,6 +3095,7 @@ function createSQLiteCorePersistenceAdapter(options) {
 export {
   DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS,
   DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS,
+  DEFAULT_CACHE_GENERATION_CLAIM_TTL_MS,
   SQLiteCorePersistenceAdapter,
   createSQLiteCorePersistenceAdapter
 };