@tanstack/db-sqlite-persistence-core 0.2.23 → 0.4.1

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

@@ -1,6 +1,108 @@
 import { IR, toBooleanPredicate, compileSingleRowExpression } from "@tanstack/db";
 import { InvalidPersistedCollectionConfigError, InvalidPersistedStorageKeyEncodingError } from "./errors.js";
-import { encodePersistedStorageKey, createPersistedTableName, decodePersistedStorageKey } from "./persisted.js";
+import { encodePersistedStorageKey, createPersistedTableName, decodePersistedStorageKey, SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY } from "./persisted.js";
+import { PERSISTED_TYPE_TAG, PERSISTED_VALUE_TAG, serializeSQLiteBigInt, assertSQLiteBigIntInRange } from "./sqlite-value.js";
+const REPLACEMENT_BATCH_SIZE = 100;
+class SharedPersistenceScheduler {
+  constructor() {
+    this.regularQueue = [];
+    this.hydrateQueue = [];
+    this.running = false;
+  }
+  runRegular(task) {
+    return this.enqueue(`regular`, task);
+  }
+  runHydrate(task) {
+    return this.enqueue(`hydrate`, task);
+  }
+  adoptRunningHydrate(completion) {
+    if (this.running) return;
+    this.running = true;
+    const finish = () => {
+      this.lastCompletedKind = `hydrate`;
+      this.running = false;
+      this.drain();
+    };
+    void completion.then(finish, finish);
+  }
+  enqueue(kind, task) {
+    const result = new Promise((resolve, reject) => {
+      const operation = {
+        kind,
+        task,
+        resolve,
+        reject
+      };
+      const queue = kind === `hydrate` ? this.hydrateQueue : this.regularQueue;
+      queue.push(operation);
+    });
+    this.drain();
+    return result;
+  }
+  drain() {
+    if (this.running) return;
+    const operation = this.takeNext();
+    if (!operation) return;
+    this.running = true;
+    void this.execute(operation);
+  }
+  async execute(operation) {
+    try {
+      operation.resolve(await operation.task());
+    } catch (error) {
+      operation.reject(error);
+    } finally {
+      this.lastCompletedKind = operation.kind;
+      this.running = false;
+      this.drain();
+    }
+  }
+  takeNext() {
+    if (this.hydrateQueue.length > 0) {
+      if (this.regularQueue.length > 0 && this.lastCompletedKind === `hydrate`) {
+        return this.regularQueue.shift();
+      }
+      return this.hydrateQueue.shift();
+    }
+    return this.regularQueue.shift();
+  }
+}
+const sharedPersistenceSchedulers = /* @__PURE__ */ new WeakMap();
+const observedDriverSchedulingKeys = /* @__PURE__ */ new WeakMap();
+function getSharedPersistenceScheduler(key) {
+  let scheduler = sharedPersistenceSchedulers.get(key);
+  if (!scheduler) {
+    scheduler = new SharedPersistenceScheduler();
+    sharedPersistenceSchedulers.set(key, scheduler);
+  }
+  return scheduler;
+}
+function getSharedLogicalSchedulingKey(value) {
+  if (typeof value !== `object` && typeof value !== `function` || !value) {
+    return void 0;
+  }
+  const key = value[SQLITE_DRIVER_SHARED_LOGICAL_SCHEDULING_KEY];
+  return key !== null && (typeof key === `object` || typeof key === `function`) ? key : void 0;
+}
+function observeSharedLogicalSchedulingSupport(driver, onSupport) {
+  let observationPending = true;
+  const observe = (promise) => {
+    if (!observationPending) return promise;
+    observationPending = false;
+    const key = getSharedLogicalSchedulingKey(promise);
+    if (key) onSupport(key);
+    return promise;
+  };
+  return {
+    exec: (sql) => observe(driver.exec(sql)),
+    query: (sql, params = []) => observe(driver.query(sql, params)),
+    run: (sql, params = []) => observe(driver.run(sql, params)),
+    transaction: (fn) => observe(driver.transaction(fn)),
+    transactionWithDriver: (fn) => observe(
+      driver.transactionWithDriver ? driver.transactionWithDriver(fn) : driver.transaction(fn)
+    )
+  };
+}
 const DEFAULT_SCHEMA_VERSION = 1;
 const DEFAULT_PULL_SINCE_RELOAD_THRESHOLD = 128;
 const DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS = 1e3;
@@ -8,8 +110,6 @@ const DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS = 24 * 60 * 60;
 const SQLITE_MAX_IN_BATCH_SIZE = 900;
 const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 const FORBIDDEN_SQL_FRAGMENT_PATTERN = /(;|--|\/\*)/;
-const PERSISTED_TYPE_TAG = `__tanstack_db_persisted_type__`;
-const PERSISTED_VALUE_TAG = `value`;
 const persistedTaggedValueTypes = /* @__PURE__ */ new Set([
   `bigint`,
   `date`,
@@ -20,12 +120,11 @@ const persistedTaggedValueTypes = /* @__PURE__ */ new Set([
 const orderByObjectIds = /* @__PURE__ */ new WeakMap();
 let nextOrderByObjectId = 1;
 function isDuplicateColumnAddError(error, columnName) {
-  if (!(error instanceof Error)) {
+  if (typeof error !== `string` && !(error instanceof Error)) {
     return false;
   }
-  const message = error.message.toLowerCase();
-  const normalizedColumnName = columnName.toLowerCase();
-  return message.includes(`duplicate column name`) && message.includes(normalizedColumnName) || message.includes(`already exists`) && message.includes(normalizedColumnName);
+  const normalizedMessage = (typeof error === `string` ? error : error.message).toLowerCase();
+  return normalizedMessage.includes(columnName.toLowerCase()) && (normalizedMessage.includes(`duplicate column name`) || normalizedMessage.includes(`already exists`));
 }
 function quoteIdentifier(identifier) {
   if (!SAFE_IDENTIFIER_PATTERN.test(identifier)) {
@@ -52,10 +151,7 @@ function encodePersistedJsonValue(value) {
     return value;
   }
   if (typeof value === `bigint`) {
-    return {
-      [PERSISTED_TYPE_TAG]: `bigint`,
-      [PERSISTED_VALUE_TAG]: value.toString()
-    };
+    return serializeSQLiteBigInt(value);
   }
   if (value instanceof Date) {
     return {
@@ -153,6 +249,7 @@ function toSqliteParameterValue(value) {
     return value;
   }
   if (typeof value === `bigint`) {
+    assertSQLiteBigIntInRange(value);
     return value.toString();
   }
   if (typeof value === `boolean`) {
@@ -175,56 +272,11 @@ function toSqliteLiteral(value) {
   }
   return `'${value.replace(/'/g, `''`)}'`;
 }
-function inlineSqlParams(sql, params) {
-  let index = 0;
-  const inlinedSql = sql.replace(/\?/g, () => {
-    const paramValue = params[index];
-    index++;
-    return toSqliteLiteral(paramValue ?? null);
-  });
-  if (index !== params.length) {
-    throw new InvalidPersistedCollectionConfigError(
-      `Unable to inline SQL params; placeholder count did not match provided params`
-    );
-  }
-  return inlinedSql;
-}
-function collectAliasQualifiedRefSegments(expression, segments = /* @__PURE__ */ new Set()) {
-  if (expression.type === `ref`) {
-    if (expression.path.length > 1) {
-      const rootSegment = String(expression.path[0]);
-      if (rootSegment.length > 0) {
-        segments.add(rootSegment);
-      }
-    }
-    return segments;
-  }
-  if (expression.type === `func`) {
-    for (const arg of expression.args) {
-      collectAliasQualifiedRefSegments(arg, segments);
-    }
+function toSqliteExpressionLiteral(value) {
+  if (typeof value === `bigint`) {
+    return assertSQLiteBigIntInRange(value).toString();
   }
-  return segments;
-}
-function createAliasAwareRowProxy(row, aliasSegments) {
-  return new Proxy(row, {
-    get(target, prop, receiver) {
-      if (typeof prop !== `string`) {
-        return Reflect.get(target, prop, receiver);
-      }
-      if (Object.prototype.hasOwnProperty.call(target, prop)) {
-        const value = Reflect.get(target, prop, receiver);
-        if (value !== void 0 || !aliasSegments.has(prop)) {
-          return value;
-        }
-        return target;
-      }
-      if (aliasSegments.has(prop)) {
-        return target;
-      }
-      return void 0;
-    }
-  });
+  return toSqliteLiteral(toSqliteParameterValue(value));
 }
 function compileRowExpressionEvaluator(expression) {
   let baseEvaluator;
@@ -235,19 +287,7 @@ function compileRowExpressionEvaluator(expression) {
       `Unsupported expression for SQLite adapter fallback evaluator: ${error.message}`
     );
   }
-  const aliasSegments = collectAliasQualifiedRefSegments(expression);
-  if (aliasSegments.size === 0) {
-    return (row) => baseEvaluator(row);
-  }
-  const proxyCache = /* @__PURE__ */ new WeakMap();
-  return (row) => {
-    let proxy = proxyCache.get(row);
-    if (!proxy) {
-      proxy = createAliasAwareRowProxy(row, aliasSegments);
-      proxyCache.set(row, proxy);
-    }
-    return baseEvaluator(proxy);
-  };
+  return baseEvaluator;
 }
 function getOrderByObjectId(value) {
   const existing = orderByObjectIds.get(value);
@@ -270,6 +310,9 @@ function compareOrderByValues(left, right, compareOptions) {
     return compareOptions.nulls === `first` ? 1 : -1;
   }
   if (typeof left === `string` && typeof right === `string`) {
+    if (compareOptions.stringSort === `custom`) {
+      return compareOptions.compare(left, right);
+    }
     if (compareOptions.stringSort === `locale`) {
       return left.localeCompare(
         right,
@@ -364,32 +407,34 @@ function resolveComparisonValueKind(leftExpression, rightExpression, leftCompile
   }
   return `unknown`;
 }
-function compileComparisonSql(operator, leftSql, rightSql, valueKind) {
-  if (valueKind === `bigint`) {
-    return `(CAST(${leftSql} AS NUMERIC) ${operator} CAST(${rightSql} AS NUMERIC))`;
-  }
-  if (valueKind === `date`) {
-    return `(date(${leftSql}) ${operator} date(${rightSql}))`;
-  }
-  if (valueKind === `datetime`) {
-    return `(datetime(${leftSql}) ${operator} datetime(${rightSql}))`;
-  }
-  return `(${leftSql} ${operator} ${rightSql})`;
+function compileComparisonSql(operator, leftExpression, rightExpression, leftSql, rightSql, valueKind, leftKind, rightKind) {
+  const compileOperand = (expression, sql, otherKind) => {
+    if (expression.type !== `val`) return sql;
+    if (valueKind === `date` && otherKind === `date`) return `date(${sql})`;
+    if (valueKind === `datetime` && otherKind === `datetime`) {
+      return `datetime(${sql})`;
+    }
+    return sql;
+  };
+  return `(${compileOperand(leftExpression, leftSql, rightKind)} ${operator} ${compileOperand(rightExpression, rightSql, leftKind)})`;
 }
 function compileRefExpressionSql(jsonPath) {
   const typePath = `${jsonPath}.${PERSISTED_TYPE_TAG}`;
   const taggedValuePath = `${jsonPath}.${PERSISTED_VALUE_TAG}`;
+  const typePathSql = toSqliteLiteral(typePath);
+  const taggedValuePathSql = toSqliteLiteral(taggedValuePath);
+  const jsonPathSql = toSqliteLiteral(jsonPath);
   return {
     supported: true,
-    sql: `(CASE json_extract(value, ?)
-      WHEN 'bigint' THEN CAST(json_extract(value, ?) AS NUMERIC)
-      WHEN 'date' THEN json_extract(value, ?)
+    sql: `(CASE json_extract(value, ${typePathSql})
+      WHEN 'bigint' THEN CAST(json_extract(value, ${taggedValuePathSql}) AS NUMERIC)
+      WHEN 'date' THEN json_extract(value, ${taggedValuePathSql})
       WHEN 'nan' THEN NULL
       WHEN 'infinity' THEN NULL
       WHEN '-infinity' THEN NULL
-      ELSE json_extract(value, ?)
+      ELSE json_extract(value, ${jsonPathSql})
     END)`,
-    params: [typePath, taggedValuePath, taggedValuePath, jsonPath],
+    params: [],
     valueKind: `unknown`
   };
 }
@@ -416,18 +461,45 @@ function decodeStoredSqliteRows(storedRows) {
 function stableStringify(value) {
   return serializePersistedRowValue(value);
 }
-function compileSqlExpression(expression) {
+function argumentCompilationContext(parentName, argumentIndex, argument, parentContext) {
+  if (parentContext === `index-expression`) return `index-expression`;
+  switch (parentName) {
+    case `and`:
+    case `or`:
+    case `not`:
+      return `predicate`;
+    case `eq`:
+    case `gt`:
+    case `gte`:
+    case `lt`:
+    case `lte`:
+    case `like`:
+    case `ilike`:
+      if (argument.type !== `val`) return `index-expression`;
+      return typeof argument.value === `bigint` ? `index-expression` : `predicate`;
+    case `in`:
+      return argumentIndex === 0 ? `index-expression` : `predicate`;
+    case `isNull`:
+    case `isUndefined`:
+      return `index-expression`;
+    default:
+      return `index-expression`;
+  }
+}
+function compileSqlExpression(expression, context = `predicate`) {
   if (expression.type === `val`) {
     const valueKind = getLiteralValueKind(expression.value);
     return {
       supported: true,
-      sql: `?`,
-      params: [toSqliteParameterValue(expression.value)],
+      sql: context === `index-expression` ? toSqliteExpressionLiteral(expression.value) : `?`,
+      params: context === `predicate` ? [toSqliteParameterValue(expression.value)] : [],
       valueKind
     };
   }
   if (expression.type === `ref`) {
-    const jsonPath = createJsonPath(expression.path.map(String));
+    const jsonPath = createJsonPath(
+      IR.getPropRefPropertyPath(expression).map(String)
+    );
     if (!jsonPath) {
       return {
         supported: false,
@@ -437,7 +509,12 @@ function compileSqlExpression(expression) {
     }
     return compileRefExpressionSql(jsonPath);
   }
-  const compiledArgs = expression.args.map((arg) => compileSqlExpression(arg));
+  const compiledArgs = expression.args.map(
+    (arg, index) => compileSqlExpression(
+      arg,
+      argumentCompilationContext(expression.name, index, arg, context)
+    )
+  );
   if (compiledArgs.some((arg) => !arg.supported)) {
     return {
       supported: false,
@@ -473,9 +550,13 @@ function compileSqlExpression(expression) {
         supported: true,
         sql: compileComparisonSql(
           operatorByName[expression.name],
+          expression.args[0],
+          expression.args[1],
           argSql[0],
           argSql[1],
-          valueKind
+          valueKind,
+          getCompiledValueKind(compiledArgs[0]),
+          getCompiledValueKind(compiledArgs[1])
         ),
         params
       };
@@ -526,11 +607,14 @@ function compileSqlExpression(expression) {
       if (!leftSql) {
         return { supported: false, sql: ``, params: [] };
       }
+      if (context === `index-expression`) {
+        return {
+          supported: true,
+          sql: `(${leftSql} IN (${listValue.map((value) => toSqliteExpressionLiteral(value)).join(`, `)}))`,
+          params: leftParams
+        };
+      }
       if (listValue.length > SQLITE_MAX_IN_BATCH_SIZE) {
-        const hasBigIntValues2 = listValue.some(
-          (value) => typeof value === `bigint`
-        );
-        const inLeftSql2 = hasBigIntValues2 ? `CAST(${leftSql} AS NUMERIC)` : leftSql;
         const chunkClauses = [];
         const batchedParams = [];
         for (let startIndex = 0; startIndex < listValue.length; startIndex += SQLITE_MAX_IN_BATCH_SIZE) {
@@ -538,13 +622,13 @@ function compileSqlExpression(expression) {
             startIndex,
             startIndex + SQLITE_MAX_IN_BATCH_SIZE
           );
-          chunkClauses.push(
-            `(${inLeftSql2} IN (${chunkValues.map(() => `?`).join(`, `)}))`
-          );
-          batchedParams.push(...leftParams);
-          batchedParams.push(
-            ...chunkValues.map((value) => toSqliteParameterValue(value))
-          );
+          const chunkParams = [];
+          const chunkValueSql = chunkValues.map((value) => {
+            chunkParams.push(toSqliteParameterValue(value));
+            return typeof value === `bigint` ? `CAST(? AS NUMERIC)` : `?`;
+          });
+          chunkClauses.push(`(${leftSql} IN (${chunkValueSql.join(`, `)}))`);
+          batchedParams.push(...leftParams, ...chunkParams);
         }
         return {
           supported: true,
@@ -552,18 +636,15 @@ function compileSqlExpression(expression) {
           params: batchedParams
         };
       }
-      const hasBigIntValues = listValue.some(
-        (value) => typeof value === `bigint`
-      );
-      const inLeftSql = hasBigIntValues ? `CAST(${leftSql} AS NUMERIC)` : leftSql;
-      const listPlaceholders = listValue.map(() => `?`).join(`, `);
+      const listParams = [];
+      const listValueSql = listValue.map((value) => {
+        listParams.push(toSqliteParameterValue(value));
+        return typeof value === `bigint` ? `CAST(? AS NUMERIC)` : `?`;
+      });
       return {
         supported: true,
-        sql: `(${inLeftSql} IN (${listPlaceholders}))`,
-        params: [
-          ...leftParams,
-          ...listValue.map((value) => toSqliteParameterValue(value))
-        ]
+        sql: `(${leftSql} IN (${listValueSql.join(`, `)}))`,
+        params: [...leftParams, ...listParams]
       };
     }
     case `like`:
@@ -638,7 +719,10 @@ function compileOrderByClauses(orderBy) {
   const parts = [];
   const params = [];
   for (const clause of orderBy) {
-    const compiledExpression = compileSqlExpression(clause.expression);
+    const compiledExpression = compileSqlExpression(
+      clause.expression,
+      `index-expression`
+    );
     if (!compiledExpression.supported) {
       return {
         supported: false,
@@ -666,7 +750,7 @@ function isExpressionLikeShape(value) {
     return Object.prototype.hasOwnProperty.call(candidate, `value`);
   }
   if (candidate.type === `ref`) {
-    return Array.isArray(candidate.path);
+    return Array.isArray(candidate.path) && (candidate.sourceAlias === void 0 || typeof candidate.sourceAlias === `string` && candidate.path[0] === candidate.sourceAlias);
   }
   if (candidate.type === `func`) {
     if (typeof candidate.name !== `string` || !Array.isArray(candidate.args)) {
@@ -690,14 +774,20 @@ function normalizeIndexSqlFragment(fragment) {
     hasParsedJson = true;
   } catch {
   }
-  if (hasParsedJson && isExpressionLikeShape(parsedJson)) {
-    const compiled = compileSqlExpression(parsedJson);
+  const decodedJson = hasParsedJson ? decodePersistedJsonValue(parsedJson) : void 0;
+  if (hasParsedJson && isExpressionLikeShape(decodedJson)) {
+    const compiled = compileSqlExpression(decodedJson, `index-expression`);
     if (!compiled.supported) {
       throw new InvalidPersistedCollectionConfigError(
         `Persisted index expression is not supported by the SQLite compiler`
       );
     }
-    return inlineSqlParams(compiled.sql, compiled.params);
+    if (compiled.params.length !== 0) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Persisted index expression cannot contain bound parameters`
+      );
+    }
+    return compiled.sql;
   }
   return sanitizeExpressionSqlFragment(fragment);
 }
@@ -719,6 +809,13 @@ class SQLiteCorePersistenceAdapter {
     this.initialized = false;
     this.collectionTableCache = /* @__PURE__ */ new Map();
     this.collectionTableLoads = /* @__PURE__ */ new Map();
+    const maxBoundParameters = options.driver.maxBoundParameters;
+    if (maxBoundParameters !== void 0 && (!Number.isInteger(maxBoundParameters) || maxBoundParameters < 4)) {
+      throw new InvalidPersistedCollectionConfigError(
+        `SQLite driver maxBoundParameters must be an integer of at least 4`
+      );
+    }
+    this.replacementBatchSize = maxBoundParameters === void 0 ? REPLACEMENT_BATCH_SIZE : Math.min(REPLACEMENT_BATCH_SIZE, Math.floor(maxBoundParameters / 4));
     const schemaVersion = options.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
     if (!Number.isInteger(schemaVersion) || schemaVersion < 0) {
       throw new InvalidPersistedCollectionConfigError(
@@ -741,12 +838,67 @@ class SQLiteCorePersistenceAdapter {
         `SQLite adapter pullSinceReloadThreshold must be a non-negative integer`
       );
     }
-    this.driver = options.driver;
+    this.schedulingIdentitySource = options.driver;
+    const schedulingKey = getSharedLogicalSchedulingKey(options.driver) ?? observedDriverSchedulingKeys.get(options.driver);
+    this.scheduler = schedulingKey ? getSharedPersistenceScheduler(schedulingKey) : void 0;
+    this.driver = schedulingKey ? options.driver : observeSharedLogicalSchedulingSupport(options.driver, (key) => {
+      observedDriverSchedulingKeys.set(options.driver, key);
+      const scheduler = getSharedPersistenceScheduler(key);
+      this.scheduler ??= scheduler;
+      if (this.activeUnscheduledHydration) {
+        scheduler.adoptRunningHydrate(this.activeUnscheduledHydration);
+      }
+    });
     this.schemaVersion = schemaVersion;
     this.schemaMismatchPolicy = options.schemaMismatchPolicy ?? `sync-present-reset`;
     this.appliedTxPruneMaxRows = options.appliedTxPruneMaxRows;
     this.appliedTxPruneMaxAgeSeconds = options.appliedTxPruneMaxAgeSeconds;
     this.pullSinceReloadThreshold = pullSinceReloadThreshold;
+    this.hydrationAdapter = {
+      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),
+      runInHydrationScope: async (task) => task(this.hydrationAdapter)
+    };
+  }
+  runInHydrationScope(task) {
+    const scheduler = this.resolveScheduler();
+    if (scheduler) {
+      return scheduler.runHydrate(() => task(this.hydrationAdapter));
+    }
+    const hydration = Promise.resolve().then(() => task(this.hydrationAdapter));
+    this.activeUnscheduledHydration = hydration;
+    const clear = () => {
+      if (this.activeUnscheduledHydration === hydration) {
+        this.activeUnscheduledHydration = void 0;
+      }
+    };
+    void hydration.then(clear, clear);
+    return hydration;
+  }
+  runInRegularScope(task) {
+    return this.runRegular(() => task(this.hydrationAdapter));
+  }
+  isHydrationScopeScheduled() {
+    return this.resolveScheduler() !== void 0;
+  }
+  runRegular(task) {
+    const scheduler = this.resolveScheduler();
+    return scheduler ? scheduler.runRegular(task) : task();
+  }
+  resolveScheduler() {
+    if (this.scheduler) return this.scheduler;
+    const key = observedDriverSchedulingKeys.get(this.schedulingIdentitySource);
+    if (key) {
+      this.scheduler = getSharedPersistenceScheduler(key);
+    }
+    return this.scheduler;
   }
   runInTransaction(fn) {
     if (typeof this.driver.transactionWithDriver === `function`) {
@@ -754,69 +906,197 @@ class SQLiteCorePersistenceAdapter {
     }
     return this.driver.transaction(fn);
   }
-  async loadSubset(collectionId, options, ctx) {
+  async assertCurrentSchemaVersion(collectionId, driver, operation) {
+    const schemaRows = await driver.query(
+      `SELECT schema_version
+       FROM collection_registry
+       WHERE collection_id = ?
+       LIMIT 1`,
+      [collectionId]
+    );
+    const persistedSchemaVersion = schemaRows[0]?.schema_version;
+    if (persistedSchemaVersion !== this.schemaVersion) {
+      throw new InvalidPersistedCollectionConfigError(
+        `Schema version mismatch for collection "${collectionId}": found ${persistedSchemaVersion ?? `missing`}, expected ${this.schemaVersion}. Refusing to ${operation} through a stale cached adapter.`
+      );
+    }
+  }
+  loadSubset(collectionId, options, ctx) {
+    return this.runRegular(
+      () => this.loadSubsetUnscheduled(collectionId, options, ctx)
+    );
+  }
+  async loadSubsetUnscheduled(collectionId, options, ctx) {
     const tableMapping = await this.ensureCollectionReady(collectionId);
-    await this.touchRequiredIndexes(collectionId, ctx?.requiredIndexSignatures);
-    if (options.cursor) {
-      const whereCurrentOptions = {
-        where: options.where ? new IR.Func(`and`, [options.where, options.cursor.whereCurrent]) : options.cursor.whereCurrent,
-        orderBy: options.orderBy
-      };
-      const whereFromOptions = {
-        where: options.where ? new IR.Func(`and`, [options.where, options.cursor.whereFrom]) : options.cursor.whereFrom,
-        orderBy: options.orderBy,
-        limit: options.limit
-      };
-      const [whereCurrentRows, whereFromRows] = await Promise.all([
-        this.loadSubsetInternal(tableMapping, whereCurrentOptions),
-        this.loadSubsetInternal(tableMapping, whereFromOptions)
-      ]);
-      const mergedRows = /* @__PURE__ */ new Map();
-      for (const row of [...whereCurrentRows, ...whereFromRows]) {
-        mergedRows.set(encodePersistedStorageKey(row.key), row);
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `load persisted rows`
+      );
+      await this.touchRequiredIndexes(
+        collectionId,
+        ctx?.requiredIndexSignatures,
+        transactionDriver
+      );
+      if (options.cursor) {
+        const whereCurrentOptions = {
+          where: options.where ? new IR.Func(`and`, [options.where, options.cursor.whereCurrent]) : options.cursor.whereCurrent,
+          orderBy: options.orderBy
+        };
+        const whereFromOptions = {
+          where: options.where ? new IR.Func(`and`, [options.where, options.cursor.whereFrom]) : options.cursor.whereFrom,
+          orderBy: options.orderBy,
+          limit: options.limit
+        };
+        const [whereCurrentRows, whereFromRows] = await Promise.all([
+          this.loadSubsetInternal(
+            tableMapping,
+            whereCurrentOptions,
+            transactionDriver
+          ),
+          this.loadSubsetInternal(
+            tableMapping,
+            whereFromOptions,
+            transactionDriver
+          )
+        ]);
+        const mergedRows = /* @__PURE__ */ new Map();
+        for (const row of [...whereCurrentRows, ...whereFromRows]) {
+          mergedRows.set(encodePersistedStorageKey(row.key), row);
+        }
+        const orderedRows = this.applyInMemoryOrderBy(
+          Array.from(mergedRows.values()),
+          options.orderBy
+        );
+        return orderedRows.map((row) => ({
+          key: row.key,
+          value: row.value,
+          metadata: row.metadata
+        }));
       }
-      const orderedRows = this.applyInMemoryOrderBy(
-        Array.from(mergedRows.values()),
-        options.orderBy
+      const rows = await this.loadSubsetInternal(
+        tableMapping,
+        options,
+        transactionDriver
       );
-      return orderedRows.map((row) => ({
+      return rows.map((row) => ({
         key: row.key,
         value: row.value,
         metadata: row.metadata
       }));
-    }
-    const rows = await this.loadSubsetInternal(tableMapping, options);
-    return rows.map((row) => ({
-      key: row.key,
-      value: row.value,
-      metadata: row.metadata
-    }));
+    });
+  }
+  loadResumeSnapshot(collectionId, ctx) {
+    return this.runRegular(
+      () => this.loadResumeSnapshotUnscheduled(collectionId, ctx)
+    );
+  }
+  async loadResumeSnapshotUnscheduled(collectionId, ctx) {
+    const tableMapping = await this.ensureCollectionReady(collectionId);
+    const includeRows = ctx?.includeRows !== false;
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `load a resume snapshot`
+      );
+      if (includeRows) {
+        await this.touchRequiredIndexes(
+          collectionId,
+          ctx?.requiredIndexSignatures,
+          transactionDriver
+        );
+      }
+      const rows = includeRows ? await this.loadSubsetInternal(tableMapping, {}, transactionDriver) : [];
+      const { latestRowVersion, keySet } = await this.readKeySetEvidence(
+        collectionId,
+        transactionDriver
+      );
+      const collectionMetadataRows = await transactionDriver.query(
+        `SELECT key, value
+         FROM collection_metadata
+         WHERE collection_id = ?`,
+        [collectionId]
+      );
+      const { latestTerm, latestSeq } = await this.readStreamPosition(
+        collectionId,
+        transactionDriver
+      );
+      const resetRows = await transactionDriver.query(
+        `SELECT reset_epoch
+         FROM collection_reset_epoch
+         WHERE collection_id = ?
+         LIMIT 1`,
+        [collectionId]
+      );
+      return {
+        rows: rows.map((row) => ({
+          key: row.key,
+          value: row.value,
+          metadata: row.metadata
+        })),
+        keySet,
+        collectionMetadata: collectionMetadataRows.map((row) => ({
+          key: row.key,
+          value: deserializePersistedRowValue(row.value)
+        })),
+        latestTerm,
+        latestSeq,
+        latestRowVersion,
+        resetEpoch: resetRows[0]?.reset_epoch ?? 0
+      };
+    });
+  }
+  applyCommittedTx(collectionId, tx) {
+    return this.runRegular(
+      () => this.applyCommittedTxUnscheduled(collectionId, tx)
+    );
   }
-  async applyCommittedTx(collectionId, tx) {
+  async applyCommittedTxUnscheduled(collectionId, tx) {
     const tableMapping = await this.ensureCollectionReady(collectionId);
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const tombstoneTableSql = quoteIdentifier(tableMapping.tombstoneTableName);
     await this.runInTransaction(async (transactionDriver) => {
-      const alreadyApplied = await transactionDriver.query(
-        `SELECT 1 AS applied
-         FROM applied_tx
-         WHERE collection_id = ? AND term = ? AND seq = ?
-         LIMIT 1`,
-        [collectionId, tx.term, tx.seq]
-      );
-      if (alreadyApplied.length > 0) {
-        return;
-      }
       const versionRows = await transactionDriver.query(
-        `SELECT latest_row_version
+        `SELECT
+           latest_row_version,
+           key_set_evidence_available,
+           (
+             SELECT schema_version
+             FROM collection_registry
+             WHERE collection_id = ?
+             LIMIT 1
+           ) AS schema_version,
+           EXISTS (
+             SELECT 1
+             FROM applied_tx
+             WHERE collection_id = ? AND term = ? AND seq = ?
+           ) AS already_applied
          FROM collection_version
          WHERE collection_id = ?
          LIMIT 1`,
-        [collectionId]
+        [collectionId, collectionId, tx.term, tx.seq, collectionId]
       );
-      const currentRowVersion = versionRows[0]?.latest_row_version ?? 0;
+      const version = versionRows[0];
+      if (!version) {
+        throw new InvalidPersistedCollectionConfigError(
+          `Missing persisted version state for collection "${collectionId}"`
+        );
+      }
+      if (version.schema_version !== this.schemaVersion) {
+        throw new InvalidPersistedCollectionConfigError(
+          `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 (version.already_applied === 1) {
+        return;
+      }
+      const currentRowVersion = version.latest_row_version;
       const nextRowVersion = Math.max(currentRowVersion + 1, tx.rowVersion);
-      const replayDelta = tx.truncate ? null : {
+      const replacesPersistedBaseline = tx.truncate === true;
+      const tracksPersistedKeySet = version.key_set_evidence_available === 1 || replacesPersistedBaseline;
+      const replayDelta = replacesPersistedBaseline ? null : {
         txId: tx.txId,
         latestRowVersion: nextRowVersion,
         changedRows: tx.mutations.filter((mutation) => mutation.type !== `delete`).map((mutation) => ({
@@ -827,13 +1107,67 @@ class SQLiteCorePersistenceAdapter {
         rowMetadataMutations: tx.rowMetadataMutations ?? [],
         collectionMetadataMutations: tx.collectionMetadataMutations ?? []
       };
-      if (tx.truncate) {
+      if (replacesPersistedBaseline) {
+        await transactionDriver.run(
+          `DELETE FROM collection_expected_keys
+           WHERE collection_id = ?`,
+          [collectionId]
+        );
         await transactionDriver.run(`DELETE FROM ${collectionTableSql}`);
         await transactionDriver.run(`DELETE FROM ${tombstoneTableSql}`);
       }
-      for (const mutation of tx.mutations) {
+      const replacementKeys = replacesPersistedBaseline ? tx.mutations.map(
+        (mutation) => encodePersistedStorageKey(mutation.key)
+      ) : [];
+      const batchReplacement = replacesPersistedBaseline && tx.mutations.length > 0 && tx.mutations.every((mutation) => mutation.type !== `delete`) && new Set(replacementKeys).size === replacementKeys.length;
+      if (batchReplacement) {
+        const finalRowMetadata = /* @__PURE__ */ new Map();
+        for (const mutation of tx.rowMetadataMutations ?? []) {
+          finalRowMetadata.set(
+            encodePersistedStorageKey(mutation.key),
+            mutation.type === `delete` ? void 0 : mutation.value
+          );
+        }
+        for (let start = 0; start < tx.mutations.length; start += this.replacementBatchSize) {
+          const mutations = tx.mutations.slice(
+            start,
+            start + this.replacementBatchSize
+          );
+          const keys = replacementKeys.slice(
+            start,
+            start + this.replacementBatchSize
+          );
+          await transactionDriver.run(
+            `INSERT INTO collection_expected_keys (collection_id, key)
+             VALUES ${keys.map(() => `(?, ?)`).join(`, `)}`,
+            keys.flatMap((key) => [collectionId, key])
+          );
+          await transactionDriver.run(
+            `INSERT INTO ${collectionTableSql} (key, value, metadata, row_version)
+             VALUES ${keys.map(() => `(?, ?, ?, ?)`).join(`, `)}`,
+            mutations.flatMap((mutation, index) => {
+              const key = keys[index];
+              const metadata = finalRowMetadata.has(key) ? finalRowMetadata.get(key) : mutation.type !== `delete` && mutation.metadataChanged === true ? mutation.metadata : void 0;
+              return [
+                key,
+                serializePersistedRowValue(mutation.value),
+                metadata === void 0 ? null : serializePersistedRowValue(metadata),
+                nextRowVersion
+              ];
+            })
+          );
+        }
+      }
+      for (const mutation of batchReplacement ? [] : tx.mutations) {
         const encodedKey = encodePersistedStorageKey(mutation.key);
         if (mutation.type === `delete`) {
+          if (tracksPersistedKeySet) {
+            await transactionDriver.run(
+              `DELETE FROM collection_expected_keys
+               WHERE collection_id = ? AND key = ?`,
+              [collectionId, encodedKey]
+            );
+          }
           await transactionDriver.run(
             `DELETE FROM ${collectionTableSql}
              WHERE key = ?`,
@@ -866,6 +1200,14 @@ class SQLiteCorePersistenceAdapter {
         const existingMetadata = existingRows[0]?.metadata != null ? deserializePersistedRowValue(existingRows[0].metadata) : void 0;
         const mergedValue = mutation.type === `update` ? mergeObjectRows(existingValue, mutation.value) : mutation.value;
         const nextMetadata = mutation.metadataChanged === true ? mutation.metadata : existingMetadata;
+        if (tracksPersistedKeySet) {
+          await transactionDriver.run(
+            `INSERT INTO collection_expected_keys (collection_id, key)
+             VALUES (?, ?)
+             ON CONFLICT(collection_id, key) DO NOTHING`,
+            [collectionId, encodedKey]
+          );
+        }
         await transactionDriver.run(
           `INSERT INTO ${collectionTableSql} (key, value, metadata, row_version)
            VALUES (?, ?, ?, ?)
@@ -886,7 +1228,7 @@ class SQLiteCorePersistenceAdapter {
           [encodedKey]
         );
       }
-      for (const rowMetadataMutation of tx.rowMetadataMutations ?? []) {
+      for (const rowMetadataMutation of batchReplacement ? [] : tx.rowMetadataMutations ?? []) {
         const encodedKey = encodePersistedStorageKey(rowMetadataMutation.key);
         if (rowMetadataMutation.type === `delete`) {
           await transactionDriver.run(
@@ -930,11 +1272,23 @@ class SQLiteCorePersistenceAdapter {
         }
       }
       await transactionDriver.run(
-        `INSERT INTO collection_version (collection_id, latest_row_version)
-         VALUES (?, ?)
-         ON CONFLICT(collection_id) DO UPDATE SET
-           latest_row_version = excluded.latest_row_version`,
-        [collectionId, nextRowVersion]
+        `UPDATE collection_version
+         SET latest_row_version = ?,
+             key_set_evidence_available = CASE
+               WHEN ? = 1 THEN 1
+               ELSE key_set_evidence_available
+             END,
+             key_set_evidence_incompatible = CASE
+               WHEN ? = 1 THEN 0
+               ELSE key_set_evidence_incompatible
+             END
+         WHERE collection_id = ?`,
+        [
+          nextRowVersion,
+          replacesPersistedBaseline ? 1 : 0,
+          replacesPersistedBaseline ? 1 : 0,
+          collectionId
+        ]
       );
       await transactionDriver.run(
         `INSERT INTO leader_term (collection_id, latest_term)
@@ -966,40 +1320,70 @@ class SQLiteCorePersistenceAdapter {
           tx.txId,
           nextRowVersion,
           replayDelta ? stableStringify(replayDelta) : null,
-          tx.truncate ? 1 : 0
+          replacesPersistedBaseline ? 1 : 0
         ]
       );
       await this.pruneAppliedTxRows(collectionId, transactionDriver);
     });
   }
-  async loadCollectionMetadata(collectionId) {
-    const rows = await this.driver.query(
-      `SELECT key, value
-       FROM collection_metadata
-       WHERE collection_id = ?`,
-      [collectionId]
+  loadCollectionMetadata(collectionId) {
+    return this.runRegular(
+      () => this.loadCollectionMetadataUnscheduled(collectionId)
     );
-    return rows.map((row) => ({
-      key: row.key,
-      value: deserializePersistedRowValue(row.value)
-    }));
   }
-  async scanRows(collectionId, options) {
+  async loadCollectionMetadataUnscheduled(collectionId) {
+    await this.ensureCollectionReady(collectionId);
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `load collection metadata`
+      );
+      const rows = await transactionDriver.query(
+        `SELECT key, value
+         FROM collection_metadata
+         WHERE collection_id = ?`,
+        [collectionId]
+      );
+      return rows.map((row) => ({
+        key: row.key,
+        value: deserializePersistedRowValue(row.value)
+      }));
+    });
+  }
+  scanRows(collectionId, options) {
+    return this.runRegular(
+      () => this.scanRowsUnscheduled(collectionId, options)
+    );
+  }
+  async scanRowsUnscheduled(collectionId, options) {
     const tableMapping = await this.ensureCollectionReady(collectionId);
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
-    const storedRows = await this.driver.query(
-      options?.metadataOnly ? `SELECT key, value, metadata, row_version
-           FROM ${collectionTableSql}
-           WHERE metadata IS NOT NULL` : `SELECT key, value, metadata, row_version
-           FROM ${collectionTableSql}`
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `scan persisted rows`
+      );
+      const storedRows = await transactionDriver.query(
+        options?.metadataOnly ? `SELECT key, value, metadata, row_version
+             FROM ${collectionTableSql}
+             WHERE metadata IS NOT NULL` : `SELECT key, value, metadata, row_version
+             FROM ${collectionTableSql}`
+      );
+      return decodeStoredSqliteRows(storedRows).map((row) => ({
+        key: row.key,
+        value: row.value,
+        metadata: row.metadata
+      }));
+    });
+  }
+  ensureIndex(collectionId, signature, spec) {
+    return this.runRegular(
+      () => this.ensureIndexUnscheduled(collectionId, signature, spec)
     );
-    return decodeStoredSqliteRows(storedRows).map((row) => ({
-      key: row.key,
-      value: row.value,
-      metadata: row.metadata
-    }));
   }
-  async ensureIndex(collectionId, signature, spec) {
+  async ensureIndexUnscheduled(collectionId, signature, spec) {
     const tableMapping = await this.ensureCollectionReady(collectionId);
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const indexName = buildIndexName(collectionId, signature);
@@ -1008,8 +1392,28 @@ class SQLiteCorePersistenceAdapter {
       (fragment) => normalizeIndexSqlFragment(fragment)
     );
     const expressionSql = normalizedExpressionSql.join(`, `);
+    const persistedExpressionSql = JSON.stringify(normalizedExpressionSql);
     const whereSql = spec.whereSql ? normalizeIndexSqlFragment(spec.whereSql) : void 0;
+    const persistedWhereSql = whereSql ?? null;
     await this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `create a persisted index`
+      );
+      const existingRows = await transactionDriver.query(
+        `SELECT index_name, expression_sql, where_sql
+         FROM persisted_index_registry
+         WHERE collection_id = ? AND signature = ?
+         LIMIT 1`,
+        [collectionId, signature]
+      );
+      const existing = existingRows[0];
+      if (existing && (existing.index_name !== indexName || existing.expression_sql !== persistedExpressionSql || existing.where_sql !== persistedWhereSql)) {
+        await transactionDriver.exec(
+          `DROP INDEX IF EXISTS ${quoteIdentifier(existing.index_name)}`
+        );
+      }
       await transactionDriver.run(
         `INSERT INTO persisted_index_registry (
            collection_id,
@@ -1037,8 +1441,8 @@ class SQLiteCorePersistenceAdapter {
           collectionId,
           signature,
           indexName,
-          JSON.stringify(normalizedExpressionSql),
-          whereSql ?? null
+          persistedExpressionSql,
+          persistedWhereSql
         ]
       );
       const createIndexSql = whereSql ? `CREATE INDEX IF NOT EXISTS ${indexNameSql}
@@ -1048,48 +1452,83 @@ class SQLiteCorePersistenceAdapter {
       await transactionDriver.exec(createIndexSql);
     });
   }
-  async markIndexRemoved(collectionId, signature) {
-    await this.ensureCollectionReady(collectionId);
-    const rows = await this.driver.query(
-      `SELECT index_name
-       FROM persisted_index_registry
-       WHERE collection_id = ? AND signature = ?
-       LIMIT 1`,
-      [collectionId, signature]
-    );
-    const indexName = rows[0]?.index_name;
-    await this.driver.run(
-      `UPDATE persisted_index_registry
-       SET removed = 1,
-           updated_at = CAST(strftime('%s', 'now') AS INTEGER),
-           last_used_at = CAST(strftime('%s', 'now') AS INTEGER)
-       WHERE collection_id = ? AND signature = ?`,
-      [collectionId, signature]
+  markIndexRemoved(collectionId, signature) {
+    return this.runRegular(
+      () => this.markIndexRemovedUnscheduled(collectionId, signature)
     );
-    if (indexName) {
-      await this.driver.exec(
-        `DROP INDEX IF EXISTS ${quoteIdentifier(indexName)}`
+  }
+  async markIndexRemovedUnscheduled(collectionId, signature) {
+    await this.ensureCollectionReady(collectionId);
+    await this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `remove a persisted index`
       );
-    }
+      const rows = await transactionDriver.query(
+        `SELECT index_name
+         FROM persisted_index_registry
+         WHERE collection_id = ? AND signature = ?
+         LIMIT 1`,
+        [collectionId, signature]
+      );
+      const indexName = rows[0]?.index_name;
+      await transactionDriver.run(
+        `UPDATE persisted_index_registry
+         SET removed = 1,
+             updated_at = CAST(strftime('%s', 'now') AS INTEGER),
+             last_used_at = CAST(strftime('%s', 'now') AS INTEGER)
+         WHERE collection_id = ? AND signature = ?`,
+        [collectionId, signature]
+      );
+      if (indexName) {
+        await transactionDriver.exec(
+          `DROP INDEX IF EXISTS ${quoteIdentifier(indexName)}`
+        );
+      }
+    });
   }
-  async getStreamPosition(collectionId) {
+  getStreamPosition(collectionId) {
+    return this.getStreamPositionUnscheduled(collectionId);
+  }
+  async getStreamPositionUnscheduled(collectionId) {
     await this.ensureCollectionReady(collectionId);
-    const [termRows, versionRows, seqRows] = await Promise.all([
-      this.driver.query(
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `read the stream position`
+      );
+      const [position, latestRowVersion] = await Promise.all([
+        this.readStreamPosition(collectionId, transactionDriver),
+        this.readLatestRowVersion(collectionId, transactionDriver)
+      ]);
+      return {
+        ...position,
+        latestRowVersion
+      };
+    });
+  }
+  async readLatestRowVersion(collectionId, driver) {
+    const versionRows = await driver.query(
+      `SELECT latest_row_version
+       FROM collection_version
+       WHERE collection_id = ?
+       LIMIT 1`,
+      [collectionId]
+    );
+    return versionRows[0]?.latest_row_version ?? 0;
+  }
+  async readStreamPosition(collectionId, driver) {
+    const [termRows, seqRows] = await Promise.all([
+      driver.query(
         `SELECT latest_term
          FROM leader_term
          WHERE collection_id = ?
          LIMIT 1`,
         [collectionId]
       ),
-      this.driver.query(
-        `SELECT latest_row_version
-         FROM collection_version
-         WHERE collection_id = ?
-         LIMIT 1`,
-        [collectionId]
-      ),
-      this.driver.query(
+      driver.query(
         `SELECT MAX(seq) AS max_seq
          FROM applied_tx
          WHERE collection_id = ? AND term = (
@@ -1100,116 +1539,146 @@ class SQLiteCorePersistenceAdapter {
     ]);
     return {
       latestTerm: termRows[0]?.latest_term ?? 0,
-      latestSeq: seqRows[0]?.max_seq ?? 0,
-      latestRowVersion: versionRows[0]?.latest_row_version ?? 0
+      latestSeq: seqRows[0]?.max_seq ?? 0
+    };
+  }
+  async readKeySetEvidence(collectionId, driver) {
+    const versionRows = await driver.query(
+      `SELECT
+         latest_row_version,
+         key_set_evidence_available,
+         key_set_evidence_incompatible AS key_set_incompatible
+       FROM collection_version
+       WHERE collection_id = ?
+       LIMIT 1`,
+      [collectionId]
+    );
+    const version = versionRows[0];
+    return {
+      latestRowVersion: version?.latest_row_version ?? 0,
+      keySet: {
+        status: version?.key_set_evidence_available !== 1 ? `unknown` : version.key_set_incompatible === 1 ? `incompatible` : `consistent`
+      }
     };
   }
-  async pullSince(collectionId, fromRowVersion) {
+  pullSince(collectionId, fromRowVersion) {
+    return this.runRegular(
+      () => this.pullSinceUnscheduled(collectionId, fromRowVersion)
+    );
+  }
+  async pullSinceUnscheduled(collectionId, fromRowVersion) {
     const tableMapping = await this.ensureCollectionReady(collectionId);
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const tombstoneTableSql = quoteIdentifier(tableMapping.tombstoneTableName);
-    const [
-      changedRows,
-      deletedRows,
-      latestVersionRows,
-      replayRows,
-      replayAvailabilityRows
-    ] = await Promise.all([
-      this.driver.query(
-        `SELECT key
+    return this.runInTransaction(async (transactionDriver) => {
+      await this.assertCurrentSchemaVersion(
+        collectionId,
+        transactionDriver,
+        `read persisted transaction deltas`
+      );
+      const [
+        changedRows,
+        deletedRows,
+        latestVersionRows,
+        replayRows,
+        replayAvailabilityRows
+      ] = await Promise.all([
+        transactionDriver.query(
+          `SELECT key
          FROM ${collectionTableSql}
          WHERE row_version > ?`,
-        [fromRowVersion]
-      ),
-      this.driver.query(
-        `SELECT key
+          [fromRowVersion]
+        ),
+        transactionDriver.query(
+          `SELECT key
          FROM ${tombstoneTableSql}
          WHERE row_version > ?`,
-        [fromRowVersion]
-      ),
-      this.driver.query(
-        `SELECT latest_row_version
+          [fromRowVersion]
+        ),
+        transactionDriver.query(
+          `SELECT latest_row_version
          FROM collection_version
          WHERE collection_id = ?
          LIMIT 1`,
-        [collectionId]
-      ),
-      this.driver.query(
-        `SELECT tx_id, row_version, replay_json, replay_requires_full_reload
+          [collectionId]
+        ),
+        transactionDriver.query(
+          `SELECT tx_id, row_version, replay_json, replay_requires_full_reload
          FROM applied_tx
          WHERE collection_id = ? AND row_version > ?
          ORDER BY term ASC, seq ASC`,
-        [collectionId, fromRowVersion]
-      ),
-      this.driver.query(
-        `SELECT MIN(row_version) AS min_row_version
+          [collectionId, fromRowVersion]
+        ),
+        transactionDriver.query(
+          `SELECT MIN(row_version) AS min_row_version
          FROM applied_tx
          WHERE collection_id = ?`,
-        [collectionId]
-      )
-    ]);
-    const latestRowVersion = latestVersionRows[0]?.latest_row_version ?? 0;
-    const replayFloor = replayAvailabilityRows[0]?.min_row_version;
-    if (latestRowVersion > fromRowVersion && (replayFloor == null || replayFloor > fromRowVersion + 1)) {
-      return {
-        latestRowVersion,
-        requiresFullReload: true
-      };
-    }
-    const changedKeyCount = changedRows.length + deletedRows.length;
-    if (changedKeyCount > this.pullSinceReloadThreshold) {
-      return {
-        latestRowVersion,
-        requiresFullReload: true
-      };
-    }
-    if (replayRows.some(
-      (row) => row.replay_requires_full_reload !== 0 || row.replay_json == null
-    )) {
-      return {
-        latestRowVersion,
-        requiresFullReload: true
+          [collectionId]
+        )
+      ]);
+      const latestRowVersion = latestVersionRows[0]?.latest_row_version ?? 0;
+      const replayFloor = replayAvailabilityRows[0]?.min_row_version;
+      if (latestRowVersion > fromRowVersion && (replayFloor == null || replayFloor > fromRowVersion + 1)) {
+        return {
+          latestRowVersion,
+          requiresFullReload: true
+        };
+      }
+      const changedKeyCount = changedRows.length + deletedRows.length;
+      if (changedKeyCount > this.pullSinceReloadThreshold) {
+        return {
+          latestRowVersion,
+          requiresFullReload: true
+        };
+      }
+      if (replayRows.some(
+        (row) => row.replay_requires_full_reload !== 0 || row.replay_json == null
+      )) {
+        return {
+          latestRowVersion,
+          requiresFullReload: true
+        };
+      }
+      const decodeKey = (encodedKey) => {
+        try {
+          return decodePersistedStorageKey(encodedKey);
+        } catch (error) {
+          throw new InvalidPersistedStorageKeyEncodingError(
+            `${encodedKey}: ${error.message}`
+          );
+        }
       };
-    }
-    const decodeKey = (encodedKey) => {
-      try {
-        return decodePersistedStorageKey(encodedKey);
-      } catch (error) {
-        throw new InvalidPersistedStorageKeyEncodingError(
-          `${encodedKey}: ${error.message}`
+      const deltas = replayRows.map((row) => {
+        const parsed = deserializePersistedRowValue(
+          row.replay_json ?? `null`
         );
-      }
-    };
-    const deltas = replayRows.map((row) => {
-      const parsed = deserializePersistedRowValue(
-        row.replay_json ?? `null`
+        if (!parsed) {
+          throw new InvalidPersistedCollectionConfigError(
+            `missing replay payload for applied_tx row`
+          );
+        }
+        return parsed;
+      });
+      const replayChangeCount = deltas.reduce(
+        (count, delta) => count + delta.changedRows.length + delta.deletedKeys.length + delta.rowMetadataMutations.length + delta.collectionMetadataMutations.length,
+        0
       );
-      if (!parsed) {
-        throw new InvalidPersistedCollectionConfigError(
-          `missing replay payload for applied_tx row`
-        );
+      if (replayChangeCount > this.pullSinceReloadThreshold) {
+        return {
+          latestRowVersion,
+          requiresFullReload: true
+        };
       }
-      return parsed;
-    });
-    const replayChangeCount = deltas.reduce(
-      (count, delta) => count + delta.changedRows.length + delta.deletedKeys.length + delta.rowMetadataMutations.length + delta.collectionMetadataMutations.length,
-      0
-    );
-    if (replayChangeCount > this.pullSinceReloadThreshold) {
       return {
         latestRowVersion,
-        requiresFullReload: true
+        requiresFullReload: false,
+        changedKeys: changedRows.map((row) => decodeKey(row.key)),
+        deletedKeys: deletedRows.map((row) => decodeKey(row.key)),
+        deltas
       };
-    }
-    return {
-      latestRowVersion,
-      requiresFullReload: false,
-      changedKeys: changedRows.map((row) => decodeKey(row.key)),
-      deletedKeys: deletedRows.map((row) => decodeKey(row.key)),
-      deltas
-    };
+    });
   }
-  async loadSubsetInternal(tableMapping, options) {
+  async loadSubsetInternal(tableMapping, options, driver = this.driver) {
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const whereCompiled = options.where ? compileSqlExpression(options.where) : { supported: true, sql: ``, params: [] };
     const orderByCompiled = compileOrderByClauses(options.orderBy);
@@ -1223,10 +1692,7 @@ class SQLiteCorePersistenceAdapter {
       sql = `${sql} ORDER BY ${orderByCompiled.sql}, key ASC`;
       queryParams.push(...orderByCompiled.params);
     }
-    const storedRows = await this.driver.query(
-      sql,
-      queryParams
-    );
+    const storedRows = await driver.query(sql, queryParams);
     const parsedRows = decodeStoredSqliteRows(storedRows);
     const filteredRows = this.applyInMemoryWhere(parsedRows, options.where);
     const orderedRows = this.applyInMemoryOrderBy(filteredRows, options.orderBy);
@@ -1286,12 +1752,12 @@ class SQLiteCorePersistenceAdapter {
     }
     return rows.slice(start, start + limit);
   }
-  async touchRequiredIndexes(collectionId, requiredIndexSignatures) {
+  async touchRequiredIndexes(collectionId, requiredIndexSignatures, driver = this.driver) {
     if (!requiredIndexSignatures || requiredIndexSignatures.length === 0) {
       return;
     }
     for (const signature of requiredIndexSignatures) {
-      await this.driver.run(
+      await driver.run(
         `UPDATE persisted_index_registry
          SET last_used_at = CAST(strftime('%s', 'now') AS INTEGER),
              updated_at = CAST(strftime('%s', 'now') AS INTEGER)
@@ -1353,31 +1819,21 @@ class SQLiteCorePersistenceAdapter {
       this.collectionTableLoads.delete(collectionId);
     }
   }
-  async ensureCollectionReadyInternal(collectionId) {
-    const existingRows = await this.driver.query(
+  async loadCollectionRegistration(collectionId) {
+    const rows = await this.driver.query(
       `SELECT table_name, tombstone_table_name, schema_version
        FROM collection_registry
        WHERE collection_id = ?
        LIMIT 1`,
       [collectionId]
     );
-    let tableName;
-    let tombstoneTableName;
-    if (existingRows.length > 0) {
-      tableName = existingRows[0].table_name;
-      tombstoneTableName = existingRows[0].tombstone_table_name;
-      if (existingRows[0].schema_version !== this.schemaVersion) {
-        await this.handleSchemaMismatch(
-          collectionId,
-          existingRows[0].schema_version,
-          this.schemaVersion,
-          tableName,
-          tombstoneTableName
-        );
-      }
-    } else {
-      tableName = createPersistedTableName(collectionId, `c`);
-      tombstoneTableName = createPersistedTableName(collectionId, `t`);
+    return rows[0];
+  }
+  async ensureCollectionReadyInternal(collectionId) {
+    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,
@@ -1386,8 +1842,26 @@ class SQLiteCorePersistenceAdapter {
            schema_version,
            updated_at
          )
-         VALUES (?, ?, ?, ?, CAST(strftime('%s', 'now') AS INTEGER))`,
-        [collectionId, tableName, tombstoneTableName, this.schemaVersion]
+         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(
+          `Unable to register persistence tables for collection "${collectionId}"`
+        );
+      }
+    }
+    const tableName = registration.table_name;
+    const tombstoneTableName = registration.tombstone_table_name;
+    if (registration.schema_version !== this.schemaVersion) {
+      await this.handleSchemaMismatch(
+        collectionId,
+        registration.schema_version,
+        this.schemaVersion,
+        tableName,
+        tombstoneTableName
       );
     }
     const collectionTableSql = quoteIdentifier(tableName);
@@ -1417,8 +1891,13 @@ class SQLiteCorePersistenceAdapter {
        ON ${tombstoneTableSql} (row_version)`
     );
     await this.driver.run(
-      `INSERT INTO collection_version (collection_id, latest_row_version)
-       VALUES (?, 0)
+      `INSERT INTO collection_version (
+         collection_id,
+         latest_row_version,
+         key_set_evidence_available,
+         key_set_evidence_incompatible
+       )
+       VALUES (?, 0, 1, 0)
        ON CONFLICT(collection_id) DO NOTHING`,
       [collectionId]
     );
@@ -1428,6 +1907,7 @@ class SQLiteCorePersistenceAdapter {
        ON CONFLICT(collection_id) DO NOTHING`,
       [collectionId]
     );
+    await this.ensureCollectionKeyEvidenceTriggers(collectionId, tableName);
     const mapping = {
       tableName,
       tombstoneTableName
@@ -1435,6 +1915,68 @@ class SQLiteCorePersistenceAdapter {
     this.collectionTableCache.set(collectionId, mapping);
     return mapping;
   }
+  async ensureCollectionKeyEvidenceTriggers(collectionId, tableName) {
+    const collectionTableSql = quoteIdentifier(tableName);
+    const collectionIdLiteral = toSqliteLiteral(collectionId);
+    const insertTriggerSql = quoteIdentifier(`${tableName}_key_evidence_insert`);
+    const deleteTriggerSql = quoteIdentifier(`${tableName}_key_evidence_delete`);
+    const updateTriggerSql = quoteIdentifier(`${tableName}_key_evidence_update`);
+    await this.driver.exec(
+      `CREATE TRIGGER IF NOT EXISTS ${insertTriggerSql}
+       AFTER INSERT ON ${collectionTableSql}
+       WHEN EXISTS (
+         SELECT 1
+         FROM collection_version
+         WHERE collection_id = ${collectionIdLiteral}
+           AND key_set_evidence_available = 1
+       ) AND NOT EXISTS (
+         SELECT 1
+         FROM collection_expected_keys
+         WHERE collection_id = ${collectionIdLiteral}
+           AND key = NEW.key
+       )
+       BEGIN
+         UPDATE collection_version
+         SET key_set_evidence_incompatible = 1
+         WHERE collection_id = ${collectionIdLiteral};
+       END`
+    );
+    await this.driver.exec(
+      `CREATE TRIGGER IF NOT EXISTS ${deleteTriggerSql}
+       AFTER DELETE ON ${collectionTableSql}
+       WHEN EXISTS (
+         SELECT 1
+         FROM collection_version
+         WHERE collection_id = ${collectionIdLiteral}
+           AND key_set_evidence_available = 1
+       ) AND EXISTS (
+         SELECT 1
+         FROM collection_expected_keys
+         WHERE collection_id = ${collectionIdLiteral}
+           AND key = OLD.key
+       )
+       BEGIN
+         UPDATE collection_version
+         SET key_set_evidence_incompatible = 1
+         WHERE collection_id = ${collectionIdLiteral};
+       END`
+    );
+    await this.driver.exec(
+      `CREATE TRIGGER IF NOT EXISTS ${updateTriggerSql}
+       AFTER UPDATE OF key ON ${collectionTableSql}
+       WHEN OLD.key <> NEW.key AND EXISTS (
+         SELECT 1
+         FROM collection_version
+         WHERE collection_id = ${collectionIdLiteral}
+           AND key_set_evidence_available = 1
+       )
+       BEGIN
+         UPDATE collection_version
+         SET key_set_evidence_incompatible = 1
+         WHERE collection_id = ${collectionIdLiteral};
+       END`
+    );
+  }
   async handleSchemaMismatch(collectionId, previousSchemaVersion, nextSchemaVersion, tableName, tombstoneTableName) {
     if (this.schemaMismatchPolicy === `sync-absent-error`) {
       throw new InvalidPersistedCollectionConfigError(
@@ -1444,6 +1986,22 @@ class SQLiteCorePersistenceAdapter {
     const collectionTableSql = quoteIdentifier(tableName);
     const tombstoneTableSql = quoteIdentifier(tombstoneTableName);
     await this.runInTransaction(async (transactionDriver) => {
+      const currentSchemaRows = await transactionDriver.query(
+        `SELECT schema_version
+         FROM collection_registry
+         WHERE collection_id = ?
+         LIMIT 1`,
+        [collectionId]
+      );
+      const currentSchemaVersion = currentSchemaRows[0]?.schema_version;
+      if (currentSchemaVersion === nextSchemaVersion) {
+        return;
+      }
+      if (currentSchemaVersion !== previousSchemaVersion) {
+        throw new InvalidPersistedCollectionConfigError(
+          `Schema version changed concurrently for collection "${collectionId}": found ${currentSchemaVersion ?? `no registry entry`} after observing ${previousSchemaVersion}; refusing to reset it to ${nextSchemaVersion}.`
+        );
+      }
       const persistedIndexes = await transactionDriver.query(
         `SELECT index_name
          FROM persisted_index_registry
@@ -1455,6 +2013,11 @@ class SQLiteCorePersistenceAdapter {
           `DROP INDEX IF EXISTS ${quoteIdentifier(row.index_name)}`
         );
       }
+      await transactionDriver.run(
+        `DELETE FROM collection_expected_keys
+         WHERE collection_id = ?`,
+        [collectionId]
+      );
       await transactionDriver.run(`DELETE FROM ${collectionTableSql}`);
       await transactionDriver.run(`DELETE FROM ${tombstoneTableSql}`);
       await transactionDriver.run(
@@ -1467,6 +2030,11 @@ class SQLiteCorePersistenceAdapter {
          WHERE collection_id = ?`,
         [collectionId]
       );
+      await transactionDriver.run(
+        `DELETE FROM collection_metadata
+         WHERE collection_id = ?`,
+        [collectionId]
+      );
       await transactionDriver.run(
         `UPDATE collection_registry
          SET schema_version = ?,
@@ -1475,10 +2043,17 @@ class SQLiteCorePersistenceAdapter {
         [nextSchemaVersion, collectionId]
       );
       await transactionDriver.run(
-        `INSERT INTO collection_version (collection_id, latest_row_version)
-         VALUES (?, 0)
+        `INSERT INTO collection_version (
+           collection_id,
+           latest_row_version,
+           key_set_evidence_available,
+           key_set_evidence_incompatible
+         )
+         VALUES (?, 0, 1, 0)
          ON CONFLICT(collection_id) DO UPDATE SET
-           latest_row_version = 0`,
+           latest_row_version = 0,
+           key_set_evidence_available = 1,
+           key_set_evidence_incompatible = 0`,
         [collectionId]
       );
       await transactionDriver.run(
@@ -1552,7 +2127,37 @@ class SQLiteCorePersistenceAdapter {
     await this.driver.exec(
       `CREATE TABLE IF NOT EXISTS collection_version (
          collection_id TEXT PRIMARY KEY,
-         latest_row_version INTEGER NOT NULL
+         latest_row_version INTEGER NOT NULL,
+         key_set_evidence_available INTEGER NOT NULL DEFAULT 0,
+         key_set_evidence_incompatible INTEGER NOT NULL DEFAULT 0
+       )`
+    );
+    const collectionVersionColumns = await this.driver.query(
+      `PRAGMA table_info(collection_version)`
+    );
+    const keyEvidenceColumns = [
+      `key_set_evidence_available`,
+      `key_set_evidence_incompatible`
+    ];
+    for (const columnName of keyEvidenceColumns) {
+      if (collectionVersionColumns.some(({ name }) => name === columnName)) {
+        continue;
+      }
+      try {
+        await this.driver.exec(
+          `ALTER TABLE collection_version ADD COLUMN ${columnName} INTEGER NOT NULL DEFAULT 0`
+        );
+      } catch (error) {
+        if (!isDuplicateColumnAddError(error, columnName)) {
+          throw error;
+        }
+      }
+    }
+    await this.driver.exec(
+      `CREATE TABLE IF NOT EXISTS collection_expected_keys (
+         collection_id TEXT NOT NULL,
+         key TEXT NOT NULL,
+         PRIMARY KEY (collection_id, key)
        )`
     );
     await this.driver.exec(