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

package/README.md

@@ -172,10 +172,23 @@ semantics.
 After a mutating RPC transport failure, replay is allowed only while the
 requester can prove the same non-null leader id and term still own the route.
 If either value was unknown for the first attempt, or either value changes,
-the request rejects with `IndeterminateCommitError` and requires application
-reconciliation. Coordinators never retry an indeterminate mutation against an
+the direct request rejects with `IndeterminateCommitError` and requires
+application reconciliation. Coordinators never retry that mutation against an
 unknown or replacement leader.
 
+A source sync transaction has a separate exact-ID reconciliation path. The
+persisted wrapper holds its applied receipt while an elected coordinator and
+SQLite adapter check the transaction under the writer lock. An existing ID
+acknowledges the original durable position. An absent ID permits one application
+only if the durable row version and reset epoch equal the wrapper's pre-send
+snapshot; another durable write may carry newer row values or an opaque source
+cursor and cannot be overwritten safely. On a certified result the wrapper
+fulfills the receipt in the same sync run and the coordinator invalidates peers,
+including a peer that missed the original notification. An uncertified result
+retains `IndeterminateCommitError` and terminal source failure. Custom adapters
+and coordinators without this optional operation keep that terminal behavior.
+One generated `txId` identifies one immutable source transaction payload.
+
 `SingleProcessCoordinator` also implements the complete route. It is always
 leader and has no cross-process transport, but it applies the transaction to
 the resolved adapter registered for the specific collection. The Browser and
@@ -294,6 +307,13 @@ row-bearing snapshot.
 - `unknown`: the adapter has no authoritative pre-migration key set and does
   not claim completeness.
 
+A no-write election can reserve a greater durable term and reset its sequence
+to zero without changing persisted rows or the source resume cursor. The
+persisted wrapper keeps an already certified resume baseline across that
+transition only when the atomic snapshot has the same row version and reset
+epoch. A committed write or schema reset requires fresh certification and
+cannot inherit the earlier baseline merely because the key set still matches.
+
 The method is required because the versioned `metadata.persistence` capability
 always carries hydration, durable row scanning, certification, evidence, and
 generation ownership as one complete bundle. Sync wrappers must forward the

package/dist/cjs/broadcast-coordinator.cjs

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const db = require("@tanstack/db");
+const committedTxAnchor = require("./committed-tx-anchor.cjs");
 const errors = require("./errors.cjs");
 const remoteSubsetWire = require("./remote-subset-wire.cjs");
 const remoteSubsetOwner = require("./remote-subset-owner.cjs");
@@ -13,6 +14,11 @@ const REMOTE_SUBSET_REPLAY_RETRY_ATTEMPTS = 2;
 const RPC_DEDUPE_RETENTION_MS = 6e4;
 const WRITER_LOCK_BUSY_RETRY_MS = 50;
 const WRITER_LOCK_MAX_RETRIES = 20;
+function requireDurableElection(adapter) {
+  if (typeof adapter.reserveLeadershipTerm !== `function`) {
+    throw new errors.InvalidPersistenceAdapterError(`reserveLeadershipTerm`);
+  }
+}
 class BroadcastCollectionCoordinator {
   constructor(options) {
     this.nodeId = db.safeRandomUUID();
@@ -29,6 +35,7 @@ class BroadcastCollectionCoordinator {
     this.appliedEnvelopePruneTimer = null;
     this.rejectDisposed = null;
     this.disposed = false;
+    if (options.adapter) requireDurableElection(options.adapter);
     this.dbName = options.dbName;
     this.coordinatorName = options.coordinatorName;
     this.defaultAdapter = options.adapter ?? null;
@@ -67,10 +74,12 @@ class BroadcastCollectionCoordinator {
    * Called by a host persistence factory to wire the internally-created adapter.
    */
   setAdapter(adapter) {
+    requireDurableElection(adapter);
     this.defaultAdapter = adapter;
   }
   /** Register the persistence adapter that owns one collection. */
   setAdapterForCollection(collectionId, adapter) {
+    requireDurableElection(adapter);
     this.collectionAdapters.set(collectionId, adapter);
   }
   registerRemoteSubsetOwner(collectionId, owner) {
@@ -349,6 +358,30 @@ class BroadcastCollectionCoordinator {
     }
     return this.sendRPC(collectionId, request);
   }
+  async reconcileCommittedTx(collectionId, tx, anchor, scopedAdapter) {
+    const initialRoute = this.waitForInitialRoute(collectionId);
+    if (initialRoute) await initialRoute;
+    let response;
+    for (let attempt = 0; attempt <= RPC_RETRY_ATTEMPTS; attempt++) {
+      if (attempt > 0) await sleep(RPC_RETRY_DELAY_MS * attempt);
+      const request = {
+        type: `rpc:reconcileCommittedTx:req`,
+        rpcId: db.safeRandomUUID(),
+        tx,
+        anchor
+      };
+      response = this.isLeader(collectionId) ? await this.handleReconcileCommittedTx(
+        collectionId,
+        request,
+        scopedAdapter
+      ) : await this.sendRPC(
+        collectionId,
+        request
+      );
+      if (response.ok || response.code !== `NOT_LEADER`) return response;
+    }
+    return response;
+  }
   async pullSince(collectionId, fromRowVersion, scopedAdapter) {
     if (this.isLeader(collectionId)) {
       return this.handlePullSince(
@@ -454,16 +487,18 @@ class BroadcastCollectionCoordinator {
           }
           try {
             const adapter = this.requireAdapter(collectionId);
-            if (adapter.getStreamPosition) {
-              const pos = await adapter.getStreamPosition(collectionId);
-              state.latestTerm = pos.latestTerm;
-              state.latestSeq = pos.latestSeq;
-              state.latestRowVersion = pos.latestRowVersion;
-            }
+            const reserveTerm = adapter.reserveLeadershipTerm;
+            if (!reserveTerm)
+              throw new errors.InvalidPersistenceAdapterError(`reserveLeadershipTerm`);
+            const pos = await this.withWriterLock(
+              () => reserveTerm.call(adapter, collectionId, state.latestTerm)
+            );
+            state.latestTerm = pos.latestTerm;
+            state.latestSeq = pos.latestSeq;
+            state.latestRowVersion = pos.latestRowVersion;
             if (this.isDisposed() || !this.participatesInLeadership(state) || this.collections.get(collectionId) !== state || abortController.signal.aborted || state.lockAbortController !== abortController) {
               return;
             }
-            state.latestTerm++;
             state.isLeader = true;
             state.leaderId = this.nodeId;
             this.notifyRouteWaiters(state);
@@ -720,6 +755,7 @@ class BroadcastCollectionCoordinator {
       const heartbeat = payload;
       if (typeof heartbeat.leaderId === `string` && typeof heartbeat.term === `number` && typeof heartbeat.latestSeq === `number` && typeof heartbeat.latestRowVersion === `number`) {
         const state2 = this.getOrCreateCollectionState(envelope.collectionId);
+        if (state2.isLeader) return;
         if (heartbeat.term < state2.latestTerm) return;
         const changedLeader = state2.leaderId !== heartbeat.leaderId;
         state2.leaderId = heartbeat.leaderId;
@@ -900,6 +936,8 @@ class BroadcastCollectionCoordinator {
         return this.handleApplyLocalMutations(collectionId, request);
       case `rpc:applyCommittedTx:req`:
         return this.handleApplyCommittedTx(collectionId, request);
+      case `rpc:reconcileCommittedTx:req`:
+        return this.handleReconcileCommittedTx(collectionId, request);
       case `rpc:pullSince:req`:
         return this.handlePullSince(collectionId, request);
     }
@@ -1393,6 +1431,10 @@ class BroadcastCollectionCoordinator {
       }
     );
     this.pruneAppliedEnvelopes();
+    this.publishCommittedTx(collectionId, state, tx);
+    return response;
+  }
+  publishCommittedTx(collectionId, state, tx, forceReload = false) {
     const committedBase = {
       type: `tx:committed`,
       term: tx.term,
@@ -1400,9 +1442,10 @@ class BroadcastCollectionCoordinator {
       txId: tx.txId,
       latestRowVersion: tx.rowVersion
     };
-    const committedPayload = tx.truncate ? {
+    const committedPayload = tx.truncate || forceReload ? {
       ...committedBase,
-      requiresFullReload: true
+      requiresFullReload: true,
+      ...forceReload ? { reconciliationReload: true } : {}
     } : {
       ...committedBase,
       requiresFullReload: false,
@@ -1426,22 +1469,115 @@ class BroadcastCollectionCoordinator {
     for (const subscriber of state.subscribers) {
       subscriber(committed);
     }
+  }
+  async handleReconcileCommittedTx(collectionId, request, scopedAdapter) {
+    const state = this.collections.get(collectionId);
+    const notLeader = () => ({
+      type: `rpc:reconcileCommittedTx:res`,
+      rpcId: request.rpcId,
+      ok: false,
+      code: `NOT_LEADER`,
+      error: `not the leader for ${collectionId}`
+    });
+    if (!state?.isLeader) return notLeader();
+    if (!committedTxAnchor.isValidCommittedTxAnchor(request.anchor) || !hasReconciliationTxPayload(request.tx)) {
+      return {
+        type: `rpc:reconcileCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `UNDETERMINED`,
+        error: `the source transaction has no valid durable proof`
+      };
+    }
+    const expectedTerm = state.latestTerm;
+    const result = await this.withScheduledWriterLock(
+      collectionId,
+      async (adapter) => {
+        const candidate = this.nextPersistedTxIfLeader(
+          collectionId,
+          state,
+          expectedTerm,
+          request.tx
+        );
+        if (candidate === null) return null;
+        if (!adapter.reconcileCommittedTx) return { kind: `unknown` };
+        try {
+          const reconciled = await adapter.reconcileCommittedTx(
+            collectionId,
+            candidate,
+            request.anchor
+          );
+          if (reconciled.kind !== `unknown`) {
+            state.latestRowVersion = Math.max(
+              state.latestRowVersion,
+              reconciled.latestRowVersion
+            );
+            if (reconciled.kind === `applied-now`) {
+              state.latestSeq = reconciled.committed.seq;
+            }
+          }
+          return reconciled;
+        } catch (error) {
+          throw errors.toPersistedCollectionDurabilityError(collectionId, error);
+        }
+      },
+      scopedAdapter
+    );
+    if (result === null) return notLeader();
+    if (result.kind === `unknown`) {
+      return {
+        type: `rpc:reconcileCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: `UNDETERMINED`,
+        error: `the durable outcome cannot be certified`
+      };
+    }
+    const current = {
+      term: state.latestTerm,
+      seq: state.latestSeq,
+      rowVersion: state.latestRowVersion
+    };
+    const response = {
+      type: `rpc:reconcileCommittedTx:res`,
+      rpcId: request.rpcId,
+      ok: true,
+      alreadyApplied: result.kind === `already-applied`,
+      committed: result.committed
+    };
+    if (!this.isDisposed() && this.collections.get(collectionId) === state) {
+      this.publishCommittedTx(
+        collectionId,
+        state,
+        result.kind === `already-applied` ? { ...request.tx, ...current } : { ...request.tx, ...result.committed },
+        result.kind === `already-applied`
+      );
+    }
     return response;
   }
+  nextPersistedTxIfLeader(collectionId, state, expectedTerm, pendingTx) {
+    if (this.isDisposed() || this.collections.get(collectionId) !== state || !state.isLeader || state.leaderId !== this.nodeId || state.latestTerm !== expectedTerm) {
+      return null;
+    }
+    return {
+      ...pendingTx,
+      term: state.latestTerm,
+      seq: state.latestSeq + 1,
+      rowVersion: state.latestRowVersion + 1
+    };
+  }
   async applyDurablyAtNextStreamPosition(collectionId, state, pendingTx, scopedAdapter) {
     const expectedTerm = state.latestTerm;
     return this.withScheduledWriterLock(
       collectionId,
       async (adapter) => {
-        if (this.isDisposed() || this.collections.get(collectionId) !== state || !state.isLeader || state.leaderId !== this.nodeId || state.latestTerm !== expectedTerm) {
-          return null;
-        }
-        const tx = {
-          ...pendingTx,
-          term: state.latestTerm,
-          seq: state.latestSeq + 1,
-          rowVersion: state.latestRowVersion + 1
-        };
+        const tx = this.nextPersistedTxIfLeader(
+          collectionId,
+          state,
+          expectedTerm,
+          pendingTx
+        );
+        if (tx === null) return null;
         try {
           await adapter.applyCommittedTx(collectionId, tx);
         } catch (error) {
@@ -1584,12 +1720,18 @@ function isRPCRequest(payload) {
     case `rpc:ensurePersistedIndex:req`:
     case `rpc:applyLocalMutations:req`:
     case `rpc:applyCommittedTx:req`:
+    case `rpc:reconcileCommittedTx:req`:
     case `rpc:pullSince:req`:
       return true;
     default:
       return false;
   }
 }
+function hasReconciliationTxPayload(value) {
+  if (!value || typeof value !== `object`) return false;
+  const tx = value;
+  return typeof tx.txId === `string` && Array.isArray(tx.mutations);
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1663,6 +1805,15 @@ function createRPCErrorResponse(request, cause) {
         code: `CONFLICT`,
         error
       };
+    case `rpc:reconcileCommittedTx:req`:
+      return {
+        type: `rpc:reconcileCommittedTx:res`,
+        rpcId: request.rpcId,
+        ok: false,
+        code: cause instanceof errors.PersistedCollectionDurabilityError ? `PERSISTENCE_ERROR` : `UNDETERMINED`,
+        error,
+        ...cause instanceof errors.PersistedCollectionDurabilityError ? toSafeDurabilityDetails(cause) : {}
+      };
     case `rpc:pullSince:req`:
       return {
         type: `rpc:pullSince:res`,