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

package/dist/cjs/persisted.d.cts

@@ -49,6 +49,7 @@ export type TxCommitted = {
     latestRowVersion: number;
 } & ({
     requiresFullReload: true;
+    reconciliationReload?: true;
 } | {
     requiresFullReload: false;
     changedRows: Array<{
@@ -149,6 +150,41 @@ export type ApplyCommittedTxResponse = {
     sourceCode?: string | number;
     path?: string | ReadonlyArray<string | number>;
 };
+/** The durable version read before a source transaction enters coordination. */
+export type CommittedTxAnchor = {
+    latestRowVersion: number;
+    resetEpoch: number;
+};
+export type ReconcileCommittedTxResponse = {
+    type: `rpc:reconcileCommittedTx:res`;
+    rpcId: string;
+    ok: true;
+    alreadyApplied: boolean;
+    committed: {
+        term: number;
+        seq: number;
+        rowVersion: number;
+    };
+} | {
+    type: `rpc:reconcileCommittedTx:res`;
+    rpcId: string;
+    ok: false;
+    code: `NOT_LEADER` | `UNDETERMINED` | `PERSISTENCE_ERROR`;
+    error: string;
+    sourceCode?: string | number;
+    path?: string | ReadonlyArray<string | number>;
+};
+export type ReconciledCommittedTx = {
+    kind: `already-applied` | `applied-now`;
+    committed: {
+        term: number;
+        seq: number;
+        rowVersion: number;
+    };
+    latestRowVersion: number;
+} | {
+    kind: `unknown`;
+};
 export type PullSinceRequest = {
     type: `rpc:pullSince:req`;
     rpcId: string;
@@ -299,6 +335,8 @@ export interface PersistenceAdapter {
         resetEpoch: number;
     }>;
     applyCommittedTx: (collectionId: string, tx: PersistedTx) => Promise<void>;
+    /** Atomically certify or apply one source transaction after a lost response. */
+    reconcileCommittedTx?: (collectionId: string, tx: PersistedTx, anchor: CommittedTxAnchor) => Promise<ReconciledCommittedTx>;
     loadCollectionMetadata?: (collectionId: string) => Promise<Array<{
         key: string;
         value: unknown;
@@ -311,6 +349,12 @@ export interface PersistenceAdapter {
         latestSeq: number;
         latestRowVersion: number;
     }>;
+    /** Reserve a new durable election term before announcing Browser leadership. */
+    reserveLeadershipTerm?: (collectionId: string, observedTerm: number) => Promise<{
+        latestTerm: number;
+        latestSeq: number;
+        latestRowVersion: number;
+    }>;
     /**
      * Runs one complete logical hydrate as a non-preemptible scheduler unit.
      * The callback must use the supplied unscheduled adapter for all nested
@@ -365,6 +409,8 @@ export interface PersistedCollectionCoordinator {
      * loan after the call; ordinary work uses the registered collection adapter.
      */
     requestApplyCommittedTx: (collectionId: string, tx: PersistedTx, scopedAdapter?: HydrationPersistenceAdapter) => Promise<ApplyCommittedTxResponse>;
+    /** Available only when the elected adapter can certify the durable outcome. */
+    reconcileCommittedTx?: (collectionId: string, tx: PersistedTx, anchor: CommittedTxAnchor, scopedAdapter?: HydrationPersistenceAdapter) => Promise<ReconcileCommittedTxResponse>;
     /** The scoped adapter is leader-local and is never serialized to a follower. */
     pullSince?: (collectionId: string, fromRowVersion: number, scopedAdapter?: HydrationPersistenceAdapter) => Promise<PullSinceResponse>;
 }

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const db = require("@tanstack/db");
 const errors = require("./errors.cjs");
+const committedTxAnchor = require("./committed-tx-anchor.cjs");
 const persisted = require("./persisted.cjs");
 const sqliteValue = require("./sqlite-value.cjs");
 const REPLACEMENT_BATCH_SIZE = 125;
@@ -1090,6 +1091,7 @@ 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),
+      reconcileCommittedTx: (collectionId, tx, anchor) => this.reconcileCommittedTxUnscheduled(collectionId, tx, anchor),
       loadCollectionMetadata: (collectionId) => this.loadCollectionMetadataUnscheduled(collectionId),
       scanRows: (collectionId, scanOptions) => this.scanRowsUnscheduled(collectionId, scanOptions),
       ensureIndex: (collectionId, signature, spec) => this.ensureIndexUnscheduled(collectionId, signature, spec),
@@ -1285,15 +1287,33 @@ class SQLiteCorePersistenceAdapter {
       () => this.applyCommittedTxUnscheduled(collectionId, tx)
     );
   }
+  reconcileCommittedTx(collectionId, tx, anchor) {
+    return this.runRegular(
+      () => this.reconcileCommittedTxUnscheduled(collectionId, tx, anchor)
+    );
+  }
   async applyCommittedTxUnscheduled(collectionId, tx) {
+    await this.applyCommittedTxInternal(collectionId, tx);
+  }
+  reconcileCommittedTxUnscheduled(collectionId, tx, anchor) {
+    if (!committedTxAnchor.isValidCommittedTxAnchor(anchor)) {
+      throw new Error(
+        `Cannot reconcile a committed transaction without a valid durable anchor`
+      );
+    }
+    return this.applyCommittedTxInternal(collectionId, tx, anchor);
+  }
+  async applyCommittedTxInternal(collectionId, tx, anchor) {
     const tableMapping = await this.ensureCollectionReady(collectionId);
     const collectionTableSql = quoteIdentifier(tableMapping.tableName);
     const tombstoneTableSql = quoteIdentifier(tableMapping.tombstoneTableName);
-    await this.runInTransaction(async (transactionDriver) => {
+    return this.runInTransaction(async (transactionDriver) => {
       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
@@ -1308,7 +1328,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) {
@@ -1321,8 +1348,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);
@@ -1570,6 +1623,15 @@ class SQLiteCorePersistenceAdapter {
         ]
       );
       await this.pruneAppliedTxRows(collectionId, transactionDriver);
+      return {
+        kind: `applied-now`,
+        committed: {
+          term: tx.term,
+          seq: tx.seq,
+          rowVersion: nextRowVersion
+        },
+        latestRowVersion: nextRowVersion
+      };
     });
   }
   loadCollectionMetadata(collectionId) {
@@ -1734,6 +1796,31 @@ class SQLiteCorePersistenceAdapter {
       }
     });
   }
+  reserveLeadershipTerm(collectionId, observedTerm) {
+    return this.reserveLeadershipTermUnscheduled(collectionId, observedTerm);
+  }
+  async reserveLeadershipTermUnscheduled(collectionId, observedTerm) {
+    await this.ensureCollectionReady(collectionId);
+    return this.runInTransaction(async (transactionDriver) => {
+      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(collectionId) {
     return this.getStreamPositionUnscheduled(collectionId);
   }
@@ -2357,6 +2444,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`