@delali/sirannon-db 0.3.4-next.62 → 0.3.4

package/dist/replication/index.mjs

@@ -1,16 +1,17 @@
 import { compatibilityAllowsPromotion } from '../chunk-ER7ODTDA.mjs';
-import { CoordinatorError, WriteConcernError, AuthorityError, SyncError, TopologyError, StalePrimaryError, NodeDrainingError, NodeNotInSyncError, ReadConcernError, ProtocolVersionMismatchError } from '../chunk-BTTFW4Z4.mjs';
-export { AuthorityError, ConflictError, CoordinatorError, FailoverError, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, ProtocolVersionMismatchError, ReadConcernError, StalePrimaryError, SyncError, TopologyError, TransportError, UnsafeRecoveryRequiredError, WriteConcernError } from '../chunk-BTTFW4Z4.mjs';
-import { LWWResolver, HLC, BatchReader, BatchApplier, StampOps, isWellFormedHlc, Transaction, loadPersistedHlc } from '../chunk-KXTYR2OQ.mjs';
-export { HLC, LWWResolver } from '../chunk-KXTYR2OQ.mjs';
-import '../chunk-MYNI2WFS.mjs';
-import { DumpOps, dumpSchema, tablesInFkOrder } from '../chunk-QP5L5DFJ.mjs';
-import { canonicaliseForChecksum, PkResolver, setForeignKeysEnabled, selectMaxChangeHlc, selectMaxColumnVersionHlc, selectMaxAppliedSourceSeq, upsertPeerAckedSeq, selectPeerAckedSeq, selectMaxChangeSeq, selectMinPeerAckedSeq, upsertSyncTableStatus, upsertSyncMeta, selectSyncMetaRow, selectCompletedSyncTableNames, ensureChangesTable, ensureReplicationStateTables, ensureMetaTable, IDENTIFIER_RE, deleteSyncTableStates, extractDroppedTable, insertDdlChange, validateDdlSafety, prepareInsertAppliedChange, selectMaxAppliedSourceSeqByNode } from '../chunk-45MKELYA.mjs';
-import { ReplicationError, BatchValidationError } from '../chunk-2QLXDHAP.mjs';
-export { BatchValidationError, ReplicationError } from '../chunk-2QLXDHAP.mjs';
-import { CHANGES_TABLE, INTERNAL_TABLE_PREFIX, isReservedIdentifier } from '../chunk-6CMCO7S4.mjs';
+import { CoordinatorError, WriteConcernError, AuthorityError, SyncError, TopologyError, StalePrimaryError, NodeDrainingError, NodeNotInSyncError, ReadConcernError, ProtocolVersionMismatchError } from '../chunk-KU32OT4H.mjs';
+export { AuthorityError, CoordinatorError, FailoverError, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, ProtocolVersionMismatchError, ReadConcernError, StalePrimaryError, SyncError, TopologyError, TransportError, UnsafeRecoveryRequiredError, WriteConcernError } from '../chunk-KU32OT4H.mjs';
+import { LWWResolver, BatchReader, BatchApplier, StampOps, isWellFormedHlc, Transaction, loadPersistedHlc } from '../chunk-A3PHCO6W.mjs';
+export { LWWResolver } from '../chunk-A3PHCO6W.mjs';
+import { runWriterTransaction, execute } from '../chunk-52XW3Z76.mjs';
+import { DumpOps, dumpSchema, tablesInFkOrder } from '../chunk-FJPR2CJX.mjs';
+import { canonicaliseForChecksum, HLC, PkResolver, selectMaxChangeHlc, selectMaxColumnVersionHlc, selectMaxAppliedSourceSeq, upsertPeerAckedSeq, selectPeerAckedSeq, selectMaxChangeSeq, selectMinPeerAckedSeq, upsertSyncTableStatus, upsertSyncMeta, selectSyncMetaRow, selectCompletedSyncTableNames, ensureChangesTable, ensureReplicationStateTables, ensureMetaTable, IDENTIFIER_RE, setForeignKeysEnabled, deleteSyncTableStates, extractDroppedTable, insertDdlChange, validateDdlSafety, prepareInsertAppliedChange, selectMaxAppliedSourceSeqByNode } from '../chunk-ESTZZPT5.mjs';
+export { HLC } from '../chunk-ESTZZPT5.mjs';
+import { ReplicationError, BatchValidationError } from '../chunk-BLMRNSUG.mjs';
+export { BatchValidationError, ConflictError, ReplicationError } from '../chunk-BLMRNSUG.mjs';
+import { CHANGES_TABLE, INTERNAL_TABLE_PREFIX, isReservedIdentifier } from '../chunk-2O3PP4CF.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-PBRXXISQ.mjs';
+import '../chunk-KINDFBQP.mjs';
 import { EventEmitter } from 'events';
 import { randomBytes, randomUUID, createHash } from 'crypto';
 
@@ -22,10 +23,10 @@ var FieldMergeResolver = class {
     this.getColumnVersions = getColumnVersions;
   }
   /**
-   * Merges columns only one side changed, and settles overlapping columns by their per-column stamps.
+   * Returns the resolution for one conflicting row, merging changes to different columns and settling each column that both sides changed by its per-column stamp.
    *
    * @param ctx - The local and incoming versions of one row.
-   * @returns Which version to write, or the merged row.
+   * @returns The version to keep, or the merged row.
    */
   async resolve(ctx) {
     const columnVersions = await this.getColumnVersions(ctx.table, ctx.rowId);
@@ -102,7 +103,7 @@ var PrimaryWinsResolver = class {
     this.primaryNodeId = primaryNodeId;
   }
   /**
-   * Takes the version authored by the configured primary node, and falls back to last-writer-wins otherwise.
+   * Returns the version that the primary node wrote, or the last-writer-wins result when neither version comes from the primary.
    *
    * @param ctx - The local and incoming versions of one row.
    * @returns Which version to write.
@@ -174,8 +175,9 @@ function toClusterStatusInfo(status, options) {
   };
 }
 function toClusterReadEndpoints(coordinator, endpoints) {
+  const live = coordinator.liveNodeIds;
   return coordinator.votingDataBearingNodeIds.filter(
-    (nodeId) => !coordinator.faultedNodeIds.includes(nodeId) && !coordinator.drainingNodeIds.includes(nodeId) && !coordinator.repairingNodeIds.includes(nodeId)
+    (nodeId) => !coordinator.faultedNodeIds.includes(nodeId) && !coordinator.drainingNodeIds.includes(nodeId) && !coordinator.repairingNodeIds.includes(nodeId) && (live === void 0 || live.includes(nodeId))
   ).map((nodeId) => ({
     nodeId,
     endpoint: endpoints[nodeId] ?? "",
@@ -451,6 +453,12 @@ var PeerTracker = class {
     }
     this.checkWaiters();
   }
+  onBatchApplied(nodeId, highestHlc) {
+    const peer = this.peers.get(nodeId);
+    if (peer && (peer.lastReceivedHlc === "" || HLC.compare(highestHlc, peer.lastReceivedHlc) > 0)) {
+      peer.lastReceivedHlc = highestHlc;
+    }
+  }
   recordInFlightBatch(nodeId, batch) {
     const peer = this.peers.get(nodeId);
     if (peer) {
@@ -927,7 +935,9 @@ function getCoordinatorRuntimeStatus(engine) {
   const config = engine.config.coordinator;
   const state = engine.coordinatorState;
   if (!config || !state) return void 0;
+  const connected = isCoordinatorConnected(engine);
   return {
+    ...connected && engine.liveNodeIds ? { liveNodeIds: [...engine.liveNodeIds] } : {},
     clusterId: config.clusterId,
     groupId: config.groupId,
     currentPrimary: state.currentPrimary ? { ...state.currentPrimary } : null,
@@ -938,7 +948,7 @@ function getCoordinatorRuntimeStatus(engine) {
     faultedNodeIds: [...state.faultedNodeIds],
     votingDataBearingNodeIds: [...state.votingDataBearingNodeIds],
     authority: engine.coordinatorAuthority,
-    connected: isCoordinatorConnected(engine),
+    connected,
     controllerState: engine.controllerState
   };
 }
@@ -1148,268 +1158,6 @@ async function evaluateFormerPrimaryHistory(engine, state) {
   });
   return nextState;
 }
-
-// src/replication/engine/coordinator-lifecycle.ts
-var DEFAULT_CONTROLLER_LEASE_TTL_MS = 1e4;
-var DEFAULT_CONTROLLER_TICK_INTERVAL_MS = 1e3;
-var IN_SYNC_RECONCILE_INTERVAL_MS = 1e3;
-function unrefTimer(timer) {
-  const unref = timer.unref;
-  unref?.call(timer);
-}
-function localCoordinatorPrimary(engine) {
-  const endpoint = engine.config.coordinator?.endpoint;
-  return endpoint ? { nodeId: engine.nodeId, endpoint } : { nodeId: engine.nodeId };
-}
-async function startCoordinatorMode(engine) {
-  const config = engine.config.coordinator;
-  if (!config) return;
-  const coordinator = config.coordinator;
-  let state = await coordinator.getReplicationGroupState(config.clusterId, config.groupId);
-  if (!state && config.votingDataBearingNodeIds) {
-    state = await coordinator.setReplicationGroupState({
-      clusterId: config.clusterId,
-      groupId: config.groupId,
-      votingDataBearingNodeIds: config.votingDataBearingNodeIds,
-      currentPrimary: engine.config.topology.role === "primary" ? localCoordinatorPrimary(engine) : null,
-      primaryTerm: 1n,
-      inSyncNodeIds: [engine.nodeId],
-      compatibility: config.compatibility
-    });
-  }
-  if (!state) {
-    throw new CoordinatorError(`Replication group '${config.groupId}' is not registered`);
-  }
-  noteCoordinatorContact(engine);
-  engine.coordinatorState = state;
-  engine.coordinatorAuthority = hasCurrentPrimaryAuthorityFor(engine, state);
-  const session = await coordinator.registerNodeSession({
-    clusterId: config.clusterId,
-    nodeId: engine.nodeId,
-    ttlMs: config.sessionTtlMs ?? DEFAULT_COORDINATOR_SESSION_TTL_MS,
-    endpoint: config.endpoint,
-    groupIds: [config.groupId],
-    dataBearing: true,
-    voting: state.votingDataBearingNodeIds.includes(engine.nodeId),
-    compatibility: config.compatibility
-  });
-  engine.nodeSessionLeaseId = session.lease.id;
-  noteCoordinatorContact(engine);
-  engine.coordinatorWatchDisposer = await coordinator.watchReplicationGroup(config.clusterId, config.groupId, (next) => {
-    handleCoordinatorStateUpdate(engine, next);
-  });
-  startCoordinatorLeaseRenewal(engine);
-  startInSyncReconcileLoop(engine);
-  startControllerLoop(engine);
-}
-function startInSyncReconcileLoop(engine) {
-  const timer = setInterval(() => {
-    reconcileInSyncSet(engine).catch((err) => {
-      const wrappedErr = err instanceof Error ? err : new Error(String(err));
-      engine.emitError({ error: wrappedErr, operation: "coordinator-in-sync-reconcile", recoverable: true });
-    });
-  }, IN_SYNC_RECONCILE_INTERVAL_MS);
-  unrefTimer(timer);
-  engine.inSyncReconcileTimer = timer;
-}
-function handleCoordinatorStateUpdate(engine, next) {
-  const previous = engine.coordinatorState;
-  const wasPrimary = previous ? hasCurrentPrimaryAuthorityFor(engine, previous) : engine.coordinatorAuthority;
-  noteCoordinatorContact(engine);
-  engine.coordinatorState = next;
-  engine.coordinatorAuthority = hasCurrentPrimaryAuthorityFor(engine, next);
-  if (wasPrimary && !engine.coordinatorAuthority && next.primaryTerm > (previous?.primaryTerm ?? 0n)) {
-    handleFormerPrimaryDemotion(engine, next).catch((err) => {
-      const wrappedErr = err instanceof Error ? err : new Error(String(err));
-      engine.emitError({ error: wrappedErr, operation: "coordinator-former-primary-demotion", recoverable: false });
-    });
-    return;
-  }
-  startCoordinatorRejoinSyncIfReady(engine, next);
-}
-function startCoordinatorLeaseRenewal(engine) {
-  const config = engine.config.coordinator;
-  if (!config || !engine.nodeSessionLeaseId) return;
-  const ttlMs = config.sessionTtlMs ?? DEFAULT_COORDINATOR_SESSION_TTL_MS;
-  const timer = setInterval(
-    () => {
-      void keepCoordinatorSessionAlive(engine, ttlMs);
-    },
-    Math.max(1e3, Math.floor(ttlMs / 3))
-  );
-  unrefTimer(timer);
-  engine.coordinatorLeaseTimer = timer;
-}
-function applyAuthorityFromKnownState(engine) {
-  const state = engine.coordinatorState;
-  engine.coordinatorAuthority = state ? hasCurrentPrimaryAuthorityFor(engine, state) : false;
-}
-async function keepCoordinatorSessionAlive(engine, ttlMs) {
-  const config = engine.config.coordinator;
-  if (!config || !engine.running || engine.coordinatorSessionRestoring) return;
-  const leaseId = engine.nodeSessionLeaseId;
-  if (leaseId) {
-    try {
-      if (await config.coordinator.renewLease(leaseId, ttlMs)) {
-        noteCoordinatorContact(engine);
-        applyAuthorityFromKnownState(engine);
-        return;
-      }
-    } catch (err) {
-      engine.coordinatorAuthority = false;
-      const wrappedErr = err instanceof Error ? err : new Error(String(err));
-      engine.emitError({ error: wrappedErr, operation: "coordinator-session-renew", recoverable: true });
-      return;
-    }
-  }
-  engine.coordinatorAuthority = false;
-  engine.nodeSessionLeaseId = null;
-  await restoreCoordinatorSession(engine, ttlMs);
-}
-async function restoreCoordinatorSession(engine, ttlMs) {
-  const config = engine.config.coordinator;
-  if (!config) return;
-  engine.coordinatorSessionRestoring = true;
-  try {
-    const state = await config.coordinator.getReplicationGroupState(config.clusterId, config.groupId);
-    if (!state) {
-      throw new CoordinatorError(`Replication group '${config.groupId}' is not registered`);
-    }
-    const session = await config.coordinator.registerNodeSession({
-      clusterId: config.clusterId,
-      nodeId: engine.nodeId,
-      ttlMs,
-      endpoint: config.endpoint,
-      groupIds: [config.groupId],
-      dataBearing: true,
-      voting: state.votingDataBearingNodeIds.includes(engine.nodeId),
-      compatibility: config.compatibility
-    });
-    if (!engine.running) {
-      await config.coordinator.releaseLease(session.lease.id).catch(() => void 0);
-      return;
-    }
-    engine.nodeSessionLeaseId = session.lease.id;
-    engine.coordinatorState = state;
-    noteCoordinatorContact(engine);
-    applyAuthorityFromKnownState(engine);
-  } catch (err) {
-    const wrappedErr = err instanceof Error ? err : new Error(String(err));
-    engine.emitError({ error: wrappedErr, operation: "coordinator-session-restore", recoverable: true });
-  } finally {
-    engine.coordinatorSessionRestoring = false;
-  }
-}
-function startControllerLoop(engine) {
-  const config = engine.config.coordinator;
-  if (!config) return;
-  const controllerConfig = typeof config.controller === "object" ? config.controller : {};
-  const enabled = typeof config.controller === "boolean" ? config.controller : controllerConfig.enabled ?? true;
-  if (!enabled) {
-    engine.controllerState = "disabled";
-    return;
-  }
-  engine.controllerState = "standby";
-  const ttlMs = controllerConfig.leaseTtlMs ?? DEFAULT_CONTROLLER_LEASE_TTL_MS;
-  const holderId = controllerConfig.holderId ?? engine.nodeId;
-  const tickMs = controllerConfig.tickIntervalMs ?? DEFAULT_CONTROLLER_TICK_INTERVAL_MS;
-  const timer = setInterval(() => {
-    controllerTick(engine, holderId, ttlMs).catch((err) => {
-      const wrappedErr = err instanceof Error ? err : new Error(String(err));
-      engine.controllerState = "lost";
-      engine.emitError({ error: wrappedErr, operation: "coordinator-controller", recoverable: true });
-    });
-  }, tickMs);
-  unrefTimer(timer);
-  engine.controllerTimer = timer;
-}
-async function controllerTick(engine, holderId, ttlMs) {
-  const config = engine.config.coordinator;
-  if (!config) return;
-  if (engine.controllerLeaseId) {
-    const renewed = await config.coordinator.renewLease(engine.controllerLeaseId, ttlMs);
-    if (!renewed) {
-      engine.controllerLeaseId = null;
-      engine.controllerState = "lost";
-      return;
-    }
-    noteCoordinatorContact(engine);
-    engine.controllerState = "active";
-    await runControllerPromotionCheck(engine);
-    return;
-  }
-  const acquired = await config.coordinator.tryAcquireControllerLease({
-    clusterId: config.clusterId,
-    holderId,
-    ttlMs
-  });
-  noteCoordinatorContact(engine);
-  if (acquired.acquired) {
-    engine.controllerLeaseId = acquired.lease.id;
-    engine.controllerState = "active";
-    await runControllerPromotionCheck(engine);
-  } else {
-    engine.controllerState = "standby";
-  }
-}
-async function runControllerPromotionCheck(engine) {
-  const config = engine.config.coordinator;
-  if (!config) return;
-  const state = await refreshCoordinatorState(engine);
-  if (!state) return;
-  const primaryNodeId = state.currentPrimary?.nodeId;
-  const primaryLive = primaryNodeId ? await config.coordinator.getLiveNodeSession(config.clusterId, primaryNodeId) : null;
-  const primaryCanKeepDuty = primaryNodeId && primaryLive && compatibilityAllowsPromotion(state.compatibility, primaryLive.compatibility) && !state.drainingNodeIds.includes(primaryNodeId) && !state.repairingNodeIds.includes(primaryNodeId) && !state.faultedNodeIds.includes(primaryNodeId);
-  if (primaryCanKeepDuty) {
-    return;
-  }
-  try {
-    const promoted = await config.coordinator.promoteEligibleReplica({
-      clusterId: config.clusterId,
-      groupId: config.groupId,
-      excludeNodeIds: primaryNodeId ? [primaryNodeId] : []
-    });
-    engine.coordinatorState = promoted;
-    engine.coordinatorAuthority = hasCurrentPrimaryAuthorityFor(engine, promoted);
-  } catch (err) {
-    const wrappedErr = err instanceof Error ? err : new Error(String(err));
-    engine.emitError({ error: wrappedErr, operation: "coordinator-promotion", recoverable: true });
-  }
-}
-function stopCoordinatorTimers(engine) {
-  if (engine.coordinatorLeaseTimer) {
-    clearInterval(engine.coordinatorLeaseTimer);
-    engine.coordinatorLeaseTimer = null;
-  }
-  if (engine.inSyncReconcileTimer) {
-    clearInterval(engine.inSyncReconcileTimer);
-    engine.inSyncReconcileTimer = null;
-  }
-  if (engine.controllerTimer) {
-    clearInterval(engine.controllerTimer);
-    engine.controllerTimer = null;
-  }
-}
-async function stopCoordinatorMode(engine) {
-  const config = engine.config.coordinator;
-  if (!config) return;
-  if (engine.coordinatorWatchDisposer) {
-    await engine.coordinatorWatchDisposer();
-    engine.coordinatorWatchDisposer = null;
-  }
-  if (engine.controllerLeaseId) {
-    const leaseId = engine.controllerLeaseId;
-    engine.controllerLeaseId = null;
-    await config.coordinator.releaseLease(leaseId).catch((err) => {
-      const wrappedErr = err instanceof Error ? err : new Error(String(err));
-      engine.emitError({ error: wrappedErr, operation: "coordinator-controller-release", recoverable: true });
-    });
-  }
-  await config.coordinator.deregisterNodeSession(config.clusterId, engine.nodeId).catch((err) => {
-    const wrappedErr = err instanceof Error ? err : new Error(String(err));
-    engine.emitError({ error: wrappedErr, operation: "coordinator-session-deregister", recoverable: true });
-  });
-}
 function assertReadyPhase(engine, activity) {
   if (engine.syncState.phase !== "ready") {
     throw new SyncError(`Node is in '${engine.syncState.phase}' phase and cannot ${activity}`);
@@ -1420,11 +1168,11 @@ async function query(engine, sql, params, options) {
   await assertReadConcern(engine, options?.readConcern?.level);
   return engine.database.query(sql, params, options);
 }
-async function execute(engine, sql, params, options) {
+async function execute2(engine, sql, params, options) {
   assertReadyPhase(engine, "accept operations");
   if (!await canAcceptLocalWrite(engine)) {
     if (engine.config.writeForwarding) {
-      const result = await forwardStatements(engine, [{ sql, params }]);
+      const result = await forwardStatements(engine, [{ sql, params }], options);
       const first = result.results[0];
       if (!first) {
         return { changes: 0, lastInsertRowId: 0 };
@@ -1443,7 +1191,7 @@ async function executeBatch(engine, sql, paramsBatch, options) {
   if (!await canAcceptLocalWrite(engine)) {
     if (engine.config.writeForwarding) {
       const statements = paramsBatch.map((p) => ({ sql, params: p }));
-      const result = await forwardStatements(engine, statements);
+      const result = await forwardStatements(engine, statements, options);
       return result.results.map((r) => ({
         changes: r.changes,
         lastInsertRowId: typeof r.lastInsertRowId === "string" ? BigInt(r.lastInsertRowId) : Number(r.lastInsertRowId)
@@ -1451,12 +1199,7 @@ async function executeBatch(engine, sql, paramsBatch, options) {
     }
     throwNotCurrentPrimary(engine);
   }
-  const results = [];
-  for (const params of paramsBatch) {
-    const r = await engine.localExecutor.executeLocally(sql, params, options);
-    results.push(r);
-  }
-  return results;
+  return engine.localExecutor.executeBatchLocally(sql, paramsBatch, options);
 }
 async function transaction(engine, fn, options) {
   assertReadyPhase(engine, "accept operations");
@@ -1465,9 +1208,10 @@ async function transaction(engine, fn, options) {
   }
   return engine.localExecutor.executeTransactionLocally(fn, options);
 }
-async function forwardStatements(engine, statements, _options) {
+async function forwardStatements(engine, statements, options) {
+  const writeConcern = options?.writeConcern;
   if (await canAcceptLocalWrite(engine)) {
-    return engine.localExecutor.executeForwardedLocally(statements);
+    return engine.localExecutor.executeForwardedLocally(statements, writeConcern);
   }
   const primaryPeerId = getForwardingPrimaryPeerId(engine);
   if (primaryPeerId === null) {
@@ -1476,7 +1220,8 @@ async function forwardStatements(engine, statements, _options) {
   return engine.config.transport.forward(primaryPeerId, {
     statements,
     requestId: randomUUID(),
-    ...getCoordinatorMessageFields(engine)
+    ...getCoordinatorMessageFields(engine),
+    ...writeConcern === void 0 ? {} : { writeConcern }
   });
 }
 
@@ -1537,17 +1282,15 @@ var LocalExecutor = class {
     this.engine = engine;
   }
   /**
-   * Serialises every `executeTransactionLocally` call against itself.
+   * Makes each `executeTransactionLocally` call wait until the previous one finishes.
    *
-   * Reason: SQLite only allows one active transaction per connection; the
-   * writer pool exposes a single writer connection (see `ConnectionPool`).
-   * Two parallel `engine.transaction(fn)` callers therefore both reach
-   * `await conn.exec('BEGIN')` on the same connection, and the second
-   * `BEGIN` errors with "cannot start a transaction within a transaction".
-   * Chaining onto this promise turns the second caller into a strict
-   * follow-on without changing the public API. A rejection is swallowed at
-   * the chain level so a failed transaction never poisons the queue; the
-   * original error still surfaces to the caller that initiated it.
+   * The engine writes through the single connection `engine.writerConn`,
+   * which SQLite limits to one open transaction. Without this queue, two
+   * concurrent `engine.transaction(fn)` calls would both send `BEGIN` on that
+   * connection, so SQLite would reject the second with 'cannot start a
+   * transaction within a transaction'. The queue catches each rejection so
+   * that a later transaction still starts after an earlier one fails, while
+   * the caller that started the failed transaction still receives its error.
    */
   transactionQueue = Promise.resolve();
   async executeLocally(sql, params, options) {
@@ -1558,11 +1301,9 @@ var LocalExecutor = class {
     }
     const txId = randomUUID();
     const droppedTable = isDdl ? extractDroppedTable(sql) : null;
-    const result = await engine.writerConn.transaction(async (tx) => {
+    const result = await runWriterTransaction(engine.writerConn, async (tx) => {
       const seqBefore = await engine.log.getLocalSeq();
-      const bindValues = params ? Array.isArray(params) ? params : [params] : [];
-      const stmt = await tx.prepare(sql);
-      const r = await stmt.run(...bindValues);
+      const r = await execute(tx, sql, params);
       if (isDdl) {
         await insertDdlChange(tx, CHANGES_TABLE, {
           ddlStatement: sql,
@@ -1592,12 +1333,13 @@ var LocalExecutor = class {
     }
     return result;
   }
-  async executeForwardedLocally(statements) {
-    const engine = this.engine;
-    const requestId = randomUUID();
-    const results = [];
-    const txId = randomUUID();
-    const hook = engine.config.onBeforeForwardedQuery;
+  async executeBatchLocally(sql, paramsBatch, options) {
+    const { results, newSeq } = await this.executeInOneTransaction(paramsBatch.map((params) => ({ sql, params })));
+    await this.waitForWriteConcernOf(newSeq, options?.writeConcern);
+    return results;
+  }
+  async executeForwardedLocally(statements, statedWriteConcern) {
+    const hook = this.engine.config.onBeforeForwardedQuery;
     for (const { sql } of statements) {
       if (!SAFE_SQL_PREFIX_RE.test(sql)) {
         throw new ReplicationError("Forwarded statement rejected: only DML and safe DDL are allowed");
@@ -1608,22 +1350,37 @@ var LocalExecutor = class {
         hook(sql, params);
       }
     }
+    const { results, newSeq } = await this.executeInOneTransaction(statements);
+    await this.waitForWriteConcernOf(newSeq, statedWriteConcern);
+    return {
+      results: results.map((r) => ({
+        changes: r.changes,
+        lastInsertRowId: typeof r.lastInsertRowId === "bigint" ? r.lastInsertRowId.toString() : r.lastInsertRowId
+      })),
+      requestId: randomUUID()
+    };
+  }
+  async waitForWriteConcernOf(seq, stated) {
+    const writeConcern = resolveWriteConcern(this.engine, stated);
+    if (writeConcern) {
+      await waitForWriteConcern(this.engine, seq, writeConcern);
+    }
+  }
+  async executeInOneTransaction(statements) {
+    const engine = this.engine;
+    const results = [];
+    const txId = randomUUID();
     let sawDdl = false;
     const droppedTables = [];
-    await engine.writerConn.transaction(async (tx) => {
+    await runWriterTransaction(engine.writerConn, async (tx) => {
       const seqBefore = await engine.log.getLocalSeq();
       for (const { sql, params } of statements) {
         const isDdl = DDL_PREFIX_RE.test(sql);
         if (isDdl && sql.includes(";")) {
           throw new ReplicationError("DDL statements containing semicolons are not allowed for replication safety");
         }
-        const bindValues = params ? Array.isArray(params) ? params : [params] : [];
-        const stmt = await tx.prepare(sql);
-        const r = await stmt.run(...bindValues);
-        results.push({
-          changes: r.changes,
-          lastInsertRowId: typeof r.lastInsertRowId === "bigint" ? r.lastInsertRowId.toString() : r.lastInsertRowId
-        });
+        const r = await execute(tx, sql, params);
+        results.push({ changes: r.changes, lastInsertRowId: r.lastInsertRowId });
         if (isDdl) {
           sawDdl = true;
           const droppedTable = extractDroppedTable(sql);
@@ -1654,7 +1411,7 @@ var LocalExecutor = class {
       }
       await refreshTriggersAfterDdl(engine);
     }
-    return { results, requestId };
+    return { results, newSeq };
   }
   async executeTransactionLocally(fn, options) {
     const ticket = this.transactionQueue.then(
@@ -1674,7 +1431,7 @@ var LocalExecutor = class {
         throw new ReplicationError("Internal error: DDL hook invoked outside an active transaction");
       }
     };
-    const userResult = await engine.writerConn.transaction(async (tx) => {
+    const userResult = await runWriterTransaction(engine.writerConn, async (tx) => {
       const seqBefore = await engine.log.getLocalSeq();
       hooks.onDdl = async (sql) => {
         const droppedTable = extractDroppedTable(sql);
@@ -1705,167 +1462,485 @@ var LocalExecutor = class {
       if (hooks.droppedTables.length > 0 && engine.tracker) {
         await engine.tracker.pruneDroppedTables(engine.writerConn, hooks.droppedTables);
       }
-      await refreshTriggersAfterDdl(engine);
-    }
-    const writeConcern = resolveWriteConcern(engine, options?.writeConcern);
-    if (writeConcern) {
-      await waitForWriteConcern(engine, newSeq, writeConcern);
+      await refreshTriggersAfterDdl(engine);
+    }
+    const writeConcern = resolveWriteConcern(engine, options?.writeConcern);
+    if (writeConcern) {
+      await waitForWriteConcern(engine, newSeq, writeConcern);
+    }
+    return userResult;
+  }
+};
+
+// src/replication/engine/node-health.ts
+function isSidelined(state, nodeId) {
+  return state.drainingNodeIds.includes(nodeId) || state.repairingNodeIds.includes(nodeId) || state.faultedNodeIds.includes(nodeId);
+}
+function excludingReason(state, nodeId) {
+  if (state.drainingNodeIds.includes(nodeId)) return "draining";
+  if (state.faultedNodeIds.includes(nodeId)) return "faulted";
+  return "sync-pending";
+}
+function staticHealth(engine, phase) {
+  if (phase !== "ready") {
+    return { state: "unavailable", reason: "sync-pending", canRead: false, canWrite: false };
+  }
+  return { state: "healthy", reason: "in-sync", canRead: true, canWrite: engine.config.topology.canWrite() };
+}
+function computeNodeHealth(engine) {
+  const phase = engine.syncState.phase;
+  if (phase === "syncing" || phase === "catching-up") {
+    return { state: "syncing", reason: "sync-pending", canRead: false, canWrite: false };
+  }
+  if (!engine.isCoordinatorMode()) {
+    return staticHealth(engine, phase);
+  }
+  const state = engine.coordinatorState;
+  if (!state) {
+    return { state: "unavailable", reason: "no-group-state", canRead: false, canWrite: false };
+  }
+  const nodeId = engine.nodeId;
+  const canRead = phase === "ready" && !isSidelined(state, nodeId);
+  const canWrite = canRead && engine.coordinatorAuthority;
+  if (state.repairingNodeIds.includes(nodeId)) {
+    return { state: "repairing", reason: "repairing", canRead, canWrite };
+  }
+  if (engine.coordinatorAuthority && !canWrite) {
+    return { state: "failing_over", reason: excludingReason(state, nodeId), canRead, canWrite };
+  }
+  if (!canRead) {
+    return { state: "unavailable", reason: excludingReason(state, nodeId), canRead, canWrite };
+  }
+  if (!isCoordinatorConnected(engine)) {
+    return { state: "degraded", reason: "coordinator-unreachable", canRead, canWrite };
+  }
+  if (!state.inSyncNodeIds.includes(nodeId)) {
+    return { state: "degraded", reason: "lagging", canRead, canWrite };
+  }
+  return { state: "healthy", reason: "in-sync", canRead, canWrite };
+}
+
+// src/replication/engine/sender-loop.ts
+var SenderLoop = class {
+  constructor(engine) {
+    this.engine = engine;
+  }
+  senderTimer = null;
+  start() {
+    const engine = this.engine;
+    if (!engine.running) return;
+    const timer = setTimeout(async () => {
+      if (!engine.running) return;
+      try {
+        engine.lastSentSeq = await engine.log.getLocalSeq();
+        await this.sendPendingBatches();
+        await this.updatePruneBoundary();
+      } catch (err) {
+        const wrappedErr = err instanceof Error ? err : new Error(String(err));
+        engine.emitError({ error: wrappedErr, operation: "sender-loop", recoverable: true });
+      }
+      this.start();
+    }, engine.batchIntervalMs);
+    timer.unref?.();
+    this.senderTimer = timer;
+  }
+  stop() {
+    if (this.senderTimer !== null) {
+      clearTimeout(this.senderTimer);
+      this.senderTimer = null;
+    }
+  }
+  async updatePruneBoundary() {
+    const engine = this.engine;
+    if (!engine.tracker) return;
+    const minAcked = await engine.log.getMinAckedSeq();
+    if (minAcked === null) {
+      engine.tracker.clearPruneBoundary("replication");
+    } else {
+      engine.tracker.setPruneBoundary("replication", minAcked);
+    }
+  }
+  async sendPendingBatches() {
+    const engine = this.engine;
+    const peers = engine.config.transport.peers();
+    const nowMs = Date.now();
+    for (const [peerId, peerInfo] of peers) {
+      if (!this.shouldReplicateTo(peerId, peerInfo.role)) {
+        continue;
+      }
+      const peerState = engine.peerTracker.getPeerState(peerId);
+      if (peerState) {
+        engine.peerTracker.expireTimedOutBatches(peerId, nowMs, engine.ackTimeoutMs);
+      }
+      if (peerState && peerState.pendingBatches >= engine.maxPendingBatches) {
+        continue;
+      }
+      const fromSeq = peerState?.lastSentSeq ?? engine.lastSentSeq;
+      const rawBatch = await engine.log.readBatch(fromSeq, engine.batchSize);
+      if (!rawBatch) continue;
+      const batch = engine.decorate(rawBatch);
+      const previousSeq = peerState?.lastSentSeq ?? 0n;
+      if (peerState) {
+        peerState.pendingBatches += 1;
+        peerState.lastSentSeq = batch.toSeq;
+        engine.peerTracker.recordInFlightBatch(peerId, {
+          batchId: batch.batchId,
+          fromSeq: batch.fromSeq,
+          toSeq: batch.toSeq,
+          sentAt: nowMs
+        });
+      }
+      engine.config.transport.send(peerId, batch).catch((err) => {
+        const wrappedErr = err instanceof Error ? err : new Error(String(err));
+        engine.emitError({ error: wrappedErr, operation: "transport-send", peerId, recoverable: true });
+        if (peerState) {
+          const idx = peerState.inFlightBatches.findIndex((b) => b.batchId === batch.batchId);
+          if (idx >= 0) {
+            peerState.inFlightBatches.splice(idx, 1);
+          }
+          if (peerState.pendingBatches > 0) {
+            peerState.pendingBatches -= 1;
+          }
+          if (previousSeq < peerState.lastSentSeq) {
+            peerState.lastSentSeq = previousSeq;
+          }
+        }
+      });
+      if (engine.config.flowControl?.maxLagSeconds && peerState) {
+        const lagMs = Number(batch.toSeq - peerState.lastAckedSeq) * engine.batchIntervalMs;
+        const maxLagMs = engine.config.flowControl.maxLagSeconds * 1e3;
+        if (lagMs > maxLagMs && engine.config.flowControl.onLagExceeded) {
+          engine.config.flowControl.onLagExceeded(peerId, lagMs);
+        }
+      }
+    }
+  }
+  shouldReplicateTo(peerId, peerRole) {
+    const engine = this.engine;
+    if (!engine.isCoordinatorMode()) {
+      return engine.config.topology.shouldReplicateTo(peerId, peerRole);
+    }
+    return engine.coordinatorAuthority && peerId !== engine.nodeId;
+  }
+};
+
+// src/replication/engine/timers.ts
+function unrefTimer(timer) {
+  const unref = timer.unref;
+  unref?.call(timer);
+}
+
+// src/replication/engine/controller-loop.ts
+var DEFAULT_CONTROLLER_LEASE_TTL_MS = 1e4;
+var DEFAULT_CONTROLLER_TICK_INTERVAL_MS = 1e3;
+async function startControllerLoop(engine) {
+  const config = engine.config.coordinator;
+  if (!config) return;
+  const controllerConfig = typeof config.controller === "object" ? config.controller : {};
+  const enabled = typeof config.controller === "boolean" ? config.controller : controllerConfig.enabled ?? true;
+  if (!enabled) {
+    engine.controllerState = "disabled";
+    return;
+  }
+  engine.controllerState = "standby";
+  const bid = {
+    holderId: controllerConfig.holderId ?? engine.nodeId,
+    ttlMs: controllerConfig.leaseTtlMs ?? DEFAULT_CONTROLLER_LEASE_TTL_MS
+  };
+  const coordinator = config.coordinator;
+  if (coordinator.watchControllerLease) {
+    engine.controllerLeaseWatchDisposer = await coordinator.watchControllerLease(config.clusterId, (lease) => {
+      engine.observedControllerLease = lease;
+      if (lease === null) {
+        bidForControllerLease(engine, bid).catch((err) => reportControllerFailure(engine, err));
+      }
+    });
+  }
+  const timer = setInterval(() => {
+    controllerTick(engine, bid).catch((err) => reportControllerFailure(engine, err));
+  }, controllerConfig.tickIntervalMs ?? DEFAULT_CONTROLLER_TICK_INTERVAL_MS);
+  unrefTimer(timer);
+  engine.controllerTimer = timer;
+}
+async function stopControllerLeaseWatch(engine) {
+  const dispose = engine.controllerLeaseWatchDisposer;
+  engine.controllerLeaseWatchDisposer = null;
+  engine.observedControllerLease = null;
+  if (dispose) {
+    await dispose();
+  }
+}
+async function controllerTick(engine, bid) {
+  const config = engine.config.coordinator;
+  if (!config) return;
+  if (engine.controllerLeaseId) {
+    const renewed = await config.coordinator.renewLease(engine.controllerLeaseId, bid.ttlMs);
+    if (!renewed) {
+      engine.controllerLeaseId = null;
+      engine.controllerState = "lost";
+      return;
+    }
+    noteCoordinatorContact(engine);
+    engine.controllerState = "active";
+    await runControllerPromotionCheck(engine);
+    return;
+  }
+  if (watchShowsLiveHolder(engine)) {
+    engine.controllerState = "standby";
+    return;
+  }
+  await bidForControllerLease(engine, bid);
+}
+function watchShowsLiveHolder(engine) {
+  const observed = engine.observedControllerLease;
+  return engine.controllerLeaseWatchDisposer !== null && observed !== null && observed.expiresAtMs > Date.now();
+}
+async function bidForControllerLease(engine, bid) {
+  const config = engine.config.coordinator;
+  if (!config || !engine.running || engine.controllerLeaseId || engine.controllerBidding) return;
+  engine.controllerBidding = true;
+  try {
+    const acquired = await config.coordinator.tryAcquireControllerLease({
+      clusterId: config.clusterId,
+      holderId: bid.holderId,
+      ttlMs: bid.ttlMs
+    });
+    noteCoordinatorContact(engine);
+    if (!acquired.acquired) {
+      engine.controllerState = "standby";
+      return;
+    }
+    if (!engine.running) {
+      await config.coordinator.releaseLease(acquired.lease.id);
+      return;
+    }
+    engine.controllerLeaseId = acquired.lease.id;
+    engine.controllerState = "active";
+  } finally {
+    engine.controllerBidding = false;
+  }
+  await runControllerPromotionCheck(engine);
+}
+function reportControllerFailure(engine, err) {
+  const wrappedErr = err instanceof Error ? err : new Error(String(err));
+  engine.controllerState = "lost";
+  engine.emitError({ error: wrappedErr, operation: "coordinator-controller", recoverable: true });
+}
+async function runControllerPromotionCheck(engine) {
+  const config = engine.config.coordinator;
+  if (!config) return;
+  const state = await refreshCoordinatorState(engine);
+  if (!state) return;
+  const primaryNodeId = state.currentPrimary?.nodeId;
+  const primaryLive = primaryNodeId ? await config.coordinator.getLiveNodeSession(config.clusterId, primaryNodeId) : null;
+  const primaryCanKeepDuty = primaryNodeId && primaryLive && compatibilityAllowsPromotion(state.compatibility, primaryLive.compatibility) && !state.drainingNodeIds.includes(primaryNodeId) && !state.repairingNodeIds.includes(primaryNodeId) && !state.faultedNodeIds.includes(primaryNodeId);
+  if (primaryCanKeepDuty) {
+    return;
+  }
+  try {
+    const promoted = await config.coordinator.promoteEligibleReplica({
+      clusterId: config.clusterId,
+      groupId: config.groupId,
+      excludeNodeIds: primaryNodeId ? [primaryNodeId] : []
+    });
+    engine.coordinatorState = promoted;
+    engine.coordinatorAuthority = hasCurrentPrimaryAuthorityFor(engine, promoted);
+  } catch (err) {
+    const wrappedErr = err instanceof Error ? err : new Error(String(err));
+    engine.emitError({ error: wrappedErr, operation: "coordinator-promotion", recoverable: true });
+  }
+}
+
+// src/replication/engine/coordinator-lifecycle.ts
+var IN_SYNC_RECONCILE_INTERVAL_MS = 1e3;
+function localCoordinatorPrimary(engine) {
+  const endpoint = engine.config.coordinator?.endpoint;
+  return endpoint ? { nodeId: engine.nodeId, endpoint } : { nodeId: engine.nodeId };
+}
+async function startCoordinatorMode(engine) {
+  const config = engine.config.coordinator;
+  if (!config) return;
+  const coordinator = config.coordinator;
+  let state = await coordinator.getReplicationGroupState(config.clusterId, config.groupId);
+  if (!state && config.votingDataBearingNodeIds) {
+    state = await coordinator.setReplicationGroupState({
+      clusterId: config.clusterId,
+      groupId: config.groupId,
+      votingDataBearingNodeIds: config.votingDataBearingNodeIds,
+      currentPrimary: engine.config.topology.role === "primary" ? localCoordinatorPrimary(engine) : null,
+      primaryTerm: 1n,
+      inSyncNodeIds: [engine.nodeId],
+      compatibility: config.compatibility
+    });
+  }
+  if (!state) {
+    throw new CoordinatorError(`Replication group '${config.groupId}' is not registered`);
+  }
+  noteCoordinatorContact(engine);
+  engine.coordinatorState = state;
+  engine.coordinatorAuthority = hasCurrentPrimaryAuthorityFor(engine, state);
+  const session = await coordinator.registerNodeSession({
+    clusterId: config.clusterId,
+    nodeId: engine.nodeId,
+    ttlMs: config.sessionTtlMs ?? DEFAULT_COORDINATOR_SESSION_TTL_MS,
+    endpoint: config.endpoint,
+    groupIds: [config.groupId],
+    dataBearing: true,
+    voting: state.votingDataBearingNodeIds.includes(engine.nodeId),
+    compatibility: config.compatibility
+  });
+  engine.nodeSessionLeaseId = session.lease.id;
+  noteCoordinatorContact(engine);
+  engine.coordinatorWatchDisposer = await coordinator.watchReplicationGroup(config.clusterId, config.groupId, (next) => {
+    handleCoordinatorStateUpdate(engine, next);
+  });
+  if (coordinator.watchNodeSessions) {
+    engine.nodeSessionWatchDisposer = await coordinator.watchNodeSessions(config.clusterId, (liveNodeIds) => {
+      engine.liveNodeIds = [...liveNodeIds];
+    });
+  }
+  startCoordinatorLeaseRenewal(engine);
+  startInSyncReconcileLoop(engine);
+  await startControllerLoop(engine);
+}
+function startInSyncReconcileLoop(engine) {
+  const timer = setInterval(() => {
+    reconcileInSyncSet(engine).catch((err) => {
+      const wrappedErr = err instanceof Error ? err : new Error(String(err));
+      engine.emitError({ error: wrappedErr, operation: "coordinator-in-sync-reconcile", recoverable: true });
+    });
+  }, IN_SYNC_RECONCILE_INTERVAL_MS);
+  unrefTimer(timer);
+  engine.inSyncReconcileTimer = timer;
+}
+function handleCoordinatorStateUpdate(engine, next) {
+  const previous = engine.coordinatorState;
+  const wasPrimary = previous ? hasCurrentPrimaryAuthorityFor(engine, previous) : engine.coordinatorAuthority;
+  noteCoordinatorContact(engine);
+  engine.coordinatorState = next;
+  engine.coordinatorAuthority = hasCurrentPrimaryAuthorityFor(engine, next);
+  if (wasPrimary && !engine.coordinatorAuthority && next.primaryTerm > (previous?.primaryTerm ?? 0n)) {
+    handleFormerPrimaryDemotion(engine, next).catch((err) => {
+      const wrappedErr = err instanceof Error ? err : new Error(String(err));
+      engine.emitError({ error: wrappedErr, operation: "coordinator-former-primary-demotion", recoverable: false });
+    });
+    return;
+  }
+  startCoordinatorRejoinSyncIfReady(engine, next);
+}
+function startCoordinatorLeaseRenewal(engine) {
+  const config = engine.config.coordinator;
+  if (!config || !engine.nodeSessionLeaseId) return;
+  const ttlMs = config.sessionTtlMs ?? DEFAULT_COORDINATOR_SESSION_TTL_MS;
+  const timer = setInterval(
+    () => {
+      void keepCoordinatorSessionAlive(engine, ttlMs);
+    },
+    Math.max(1e3, Math.floor(ttlMs / 3))
+  );
+  unrefTimer(timer);
+  engine.coordinatorLeaseTimer = timer;
+}
+function applyAuthorityFromKnownState(engine) {
+  const state = engine.coordinatorState;
+  engine.coordinatorAuthority = state ? hasCurrentPrimaryAuthorityFor(engine, state) : false;
+}
+async function keepCoordinatorSessionAlive(engine, ttlMs) {
+  const config = engine.config.coordinator;
+  if (!config || !engine.running || engine.coordinatorSessionRestoring) return;
+  const leaseId = engine.nodeSessionLeaseId;
+  if (leaseId) {
+    try {
+      if (await config.coordinator.renewLease(leaseId, ttlMs)) {
+        noteCoordinatorContact(engine);
+        applyAuthorityFromKnownState(engine);
+        return;
+      }
+    } catch (err) {
+      engine.coordinatorAuthority = false;
+      const wrappedErr = err instanceof Error ? err : new Error(String(err));
+      engine.emitError({ error: wrappedErr, operation: "coordinator-session-renew", recoverable: true });
+      return;
     }
-    return userResult;
   }
-};
-
-// src/replication/engine/node-health.ts
-function isSidelined(state, nodeId) {
-  return state.drainingNodeIds.includes(nodeId) || state.repairingNodeIds.includes(nodeId) || state.faultedNodeIds.includes(nodeId);
-}
-function excludingReason(state, nodeId) {
-  if (state.drainingNodeIds.includes(nodeId)) return "draining";
-  if (state.faultedNodeIds.includes(nodeId)) return "faulted";
-  return "sync-pending";
+  engine.coordinatorAuthority = false;
+  engine.nodeSessionLeaseId = null;
+  await restoreCoordinatorSession(engine, ttlMs);
 }
-function staticHealth(engine, phase) {
-  if (phase !== "ready") {
-    return { state: "unavailable", reason: "sync-pending", canRead: false, canWrite: false };
+async function restoreCoordinatorSession(engine, ttlMs) {
+  const config = engine.config.coordinator;
+  if (!config) return;
+  engine.coordinatorSessionRestoring = true;
+  try {
+    const state = await config.coordinator.getReplicationGroupState(config.clusterId, config.groupId);
+    if (!state) {
+      throw new CoordinatorError(`Replication group '${config.groupId}' is not registered`);
+    }
+    const session = await config.coordinator.registerNodeSession({
+      clusterId: config.clusterId,
+      nodeId: engine.nodeId,
+      ttlMs,
+      endpoint: config.endpoint,
+      groupIds: [config.groupId],
+      dataBearing: true,
+      voting: state.votingDataBearingNodeIds.includes(engine.nodeId),
+      compatibility: config.compatibility
+    });
+    if (!engine.running) {
+      await config.coordinator.releaseLease(session.lease.id).catch(() => void 0);
+      return;
+    }
+    engine.nodeSessionLeaseId = session.lease.id;
+    engine.coordinatorState = state;
+    noteCoordinatorContact(engine);
+    applyAuthorityFromKnownState(engine);
+  } catch (err) {
+    const wrappedErr = err instanceof Error ? err : new Error(String(err));
+    engine.emitError({ error: wrappedErr, operation: "coordinator-session-restore", recoverable: true });
+  } finally {
+    engine.coordinatorSessionRestoring = false;
   }
-  return { state: "healthy", reason: "in-sync", canRead: true, canWrite: engine.config.topology.canWrite() };
 }
-function computeNodeHealth(engine) {
-  const phase = engine.syncState.phase;
-  if (phase === "syncing" || phase === "catching-up") {
-    return { state: "syncing", reason: "sync-pending", canRead: false, canWrite: false };
-  }
-  if (!engine.isCoordinatorMode()) {
-    return staticHealth(engine, phase);
-  }
-  const state = engine.coordinatorState;
-  if (!state) {
-    return { state: "unavailable", reason: "no-group-state", canRead: false, canWrite: false };
-  }
-  const nodeId = engine.nodeId;
-  const canRead = phase === "ready" && !isSidelined(state, nodeId);
-  const canWrite = canRead && engine.coordinatorAuthority;
-  if (state.repairingNodeIds.includes(nodeId)) {
-    return { state: "repairing", reason: "repairing", canRead, canWrite };
-  }
-  if (engine.coordinatorAuthority && !canWrite) {
-    return { state: "failing_over", reason: excludingReason(state, nodeId), canRead, canWrite };
-  }
-  if (!canRead) {
-    return { state: "unavailable", reason: excludingReason(state, nodeId), canRead, canWrite };
+function stopCoordinatorTimers(engine) {
+  if (engine.coordinatorLeaseTimer) {
+    clearInterval(engine.coordinatorLeaseTimer);
+    engine.coordinatorLeaseTimer = null;
   }
-  if (!isCoordinatorConnected(engine)) {
-    return { state: "degraded", reason: "coordinator-unreachable", canRead, canWrite };
+  if (engine.inSyncReconcileTimer) {
+    clearInterval(engine.inSyncReconcileTimer);
+    engine.inSyncReconcileTimer = null;
   }
-  if (!state.inSyncNodeIds.includes(nodeId)) {
-    return { state: "degraded", reason: "lagging", canRead, canWrite };
+  if (engine.controllerTimer) {
+    clearInterval(engine.controllerTimer);
+    engine.controllerTimer = null;
   }
-  return { state: "healthy", reason: "in-sync", canRead, canWrite };
 }
-
-// src/replication/engine/sender-loop.ts
-var SenderLoop = class {
-  constructor(engine) {
-    this.engine = engine;
-  }
-  senderTimer = null;
-  start() {
-    const engine = this.engine;
-    if (!engine.running) return;
-    const timer = setTimeout(async () => {
-      if (!engine.running) return;
-      try {
-        engine.lastSentSeq = await engine.log.getLocalSeq();
-        await this.sendPendingBatches();
-        await this.updatePruneBoundary();
-      } catch (err) {
-        const wrappedErr = err instanceof Error ? err : new Error(String(err));
-        engine.emitError({ error: wrappedErr, operation: "sender-loop", recoverable: true });
-      }
-      this.start();
-    }, engine.batchIntervalMs);
-    timer.unref?.();
-    this.senderTimer = timer;
-  }
-  stop() {
-    if (this.senderTimer !== null) {
-      clearTimeout(this.senderTimer);
-      this.senderTimer = null;
-    }
-  }
-  async updatePruneBoundary() {
-    const engine = this.engine;
-    if (!engine.tracker) return;
-    const minAcked = await engine.log.getMinAckedSeq();
-    if (minAcked === null) {
-      engine.tracker.clearPruneBoundary();
-    } else {
-      engine.tracker.setPruneBoundary(minAcked);
-    }
+async function stopCoordinatorMode(engine) {
+  const config = engine.config.coordinator;
+  if (!config) return;
+  if (engine.coordinatorWatchDisposer) {
+    await engine.coordinatorWatchDisposer();
+    engine.coordinatorWatchDisposer = null;
   }
-  async sendPendingBatches() {
-    const engine = this.engine;
-    const peers = engine.config.transport.peers();
-    const nowMs = Date.now();
-    for (const [peerId, peerInfo] of peers) {
-      if (!this.shouldReplicateTo(peerId, peerInfo.role)) {
-        continue;
-      }
-      const peerState = engine.peerTracker.getPeerState(peerId);
-      if (peerState) {
-        engine.peerTracker.expireTimedOutBatches(peerId, nowMs, engine.ackTimeoutMs);
-      }
-      if (peerState && peerState.pendingBatches >= engine.maxPendingBatches) {
-        continue;
-      }
-      const fromSeq = peerState?.lastSentSeq ?? engine.lastSentSeq;
-      const rawBatch = await engine.log.readBatch(fromSeq, engine.batchSize);
-      if (!rawBatch) continue;
-      const batch = engine.decorate(rawBatch);
-      const previousSeq = peerState?.lastSentSeq ?? 0n;
-      if (peerState) {
-        peerState.pendingBatches += 1;
-        peerState.lastSentSeq = batch.toSeq;
-        engine.peerTracker.recordInFlightBatch(peerId, {
-          batchId: batch.batchId,
-          fromSeq: batch.fromSeq,
-          toSeq: batch.toSeq,
-          sentAt: nowMs
-        });
-      }
-      engine.config.transport.send(peerId, batch).catch((err) => {
-        const wrappedErr = err instanceof Error ? err : new Error(String(err));
-        engine.emitError({ error: wrappedErr, operation: "transport-send", peerId, recoverable: true });
-        if (peerState) {
-          const idx = peerState.inFlightBatches.findIndex((b) => b.batchId === batch.batchId);
-          if (idx >= 0) {
-            peerState.inFlightBatches.splice(idx, 1);
-          }
-          if (peerState.pendingBatches > 0) {
-            peerState.pendingBatches -= 1;
-          }
-          if (previousSeq < peerState.lastSentSeq) {
-            peerState.lastSentSeq = previousSeq;
-          }
-        }
-      });
-      if (engine.config.flowControl?.maxLagSeconds && peerState) {
-        const lagMs = Number(batch.toSeq - peerState.lastAckedSeq) * engine.batchIntervalMs;
-        const maxLagMs = engine.config.flowControl.maxLagSeconds * 1e3;
-        if (lagMs > maxLagMs && engine.config.flowControl.onLagExceeded) {
-          engine.config.flowControl.onLagExceeded(peerId, lagMs);
-        }
-      }
-    }
+  if (engine.nodeSessionWatchDisposer) {
+    await engine.nodeSessionWatchDisposer();
+    engine.nodeSessionWatchDisposer = null;
   }
-  shouldReplicateTo(peerId, peerRole) {
-    const engine = this.engine;
-    if (!engine.isCoordinatorMode()) {
-      return engine.config.topology.shouldReplicateTo(peerId, peerRole);
-    }
-    return engine.coordinatorAuthority && peerId !== engine.nodeId;
+  engine.liveNodeIds = null;
+  await stopControllerLeaseWatch(engine);
+  if (engine.controllerLeaseId) {
+    const leaseId = engine.controllerLeaseId;
+    engine.controllerLeaseId = null;
+    await config.coordinator.releaseLease(leaseId).catch((err) => {
+      const wrappedErr = err instanceof Error ? err : new Error(String(err));
+      engine.emitError({ error: wrappedErr, operation: "coordinator-controller-release", recoverable: true });
+    });
   }
-};
+  await config.coordinator.deregisterNodeSession(config.clusterId, engine.nodeId).catch((err) => {
+    const wrappedErr = err instanceof Error ? err : new Error(String(err));
+    engine.emitError({ error: wrappedErr, operation: "coordinator-session-deregister", recoverable: true });
+  });
+}
 
 // src/replication/engine/test-hooks.ts
 var ackDelayByEngine = /* @__PURE__ */ new WeakMap();
@@ -1958,6 +2033,7 @@ function wireTransportHandlers(engine) {
         await refreshTriggersAfterDdl(engine);
       }
       await engine.log.setLastAppliedSeq(fromPeerId, batch.toSeq);
+      engine.peerTracker.onBatchApplied(fromPeerId, batch.hlcRange.max);
       const previousApplied = engine.appliedSeqByPeer.get(fromPeerId) ?? 0n;
       if (batch.toSeq > previousApplied) {
         engine.appliedSeqByPeer.set(fromPeerId, batch.toSeq);
@@ -2018,7 +2094,7 @@ function wireTransportHandlers(engine) {
         throw new ReplicationError(`Rejected forward from unknown peer: ${fromPeerId}`);
       }
       try {
-        const result = await engine.localExecutor.executeForwardedLocally(request.statements);
+        const result = await engine.localExecutor.executeForwardedLocally(request.statements, request.writeConcern);
         return engine.decorate(result);
       } catch (err) {
         const wrappedErr = err instanceof Error ? err : new Error(String(err));
@@ -2205,6 +2281,27 @@ async function startEngine(engine) {
   }
   engine.senderLoop.start();
 }
+async function stopEngine(engine) {
+  if (!engine.running) return;
+  engine.running = false;
+  stopCoordinatorTimers(engine);
+  engine.syncJoiner.stopTimers();
+  engine.syncServer.abortAll();
+  if (engine.syncState.phase === "syncing") {
+    try {
+      await setForeignKeysEnabled(engine.writerConn, true);
+    } catch (err) {
+      const wrappedErr = err instanceof Error ? err : new Error(String(err));
+      engine.emitError({ error: wrappedErr, operation: "engine-stop-pragma-restore", recoverable: false });
+    }
+  }
+  engine.senderLoop.stop();
+  if (engine.tracker) {
+    engine.tracker.clearPruneBoundary("replication");
+  }
+  await stopCoordinatorMode(engine);
+  await engine.config.transport.disconnect();
+}
 
 // src/replication/engine/sync-recovery.ts
 var SYNC_RETRY_MIN_DELAY_MS = 1e3;
@@ -2984,7 +3081,7 @@ var ReplicationEngine = class extends EventEmitter {
   /** @internal */
   config;
   /**
-   * Identifier of this node, which every change it authors carries.
+   * Identifies this node, and the engine stamps it on every change that this node writes.
    */
   nodeId;
   /** @internal */
@@ -3042,6 +3139,16 @@ var ReplicationEngine = class extends EventEmitter {
   /** @internal */
   coordinatorWatchDisposer = null;
   /** @internal */
+  nodeSessionWatchDisposer = null;
+  /** @internal */
+  controllerLeaseWatchDisposer = null;
+  /** @internal */
+  observedControllerLease = null;
+  /** @internal */
+  controllerBidding = false;
+  /** @internal */
+  liveNodeIds = null;
+  /** @internal */
   coordinatorLeaseTimer = null;
   /** @internal */
   controllerTimer = null;
@@ -3112,39 +3219,28 @@ var ReplicationEngine = class extends EventEmitter {
     installTestHooks(this);
   }
   /**
-   * Connects the transport, pulls a full copy when this node needs one, and starts replicating.
+   * Connects the transport and starts replicating. When this node is a replica without a complete, current copy, it
+   * also requests a full copy from a source peer, and the returned promise resolves before that copy finishes.
    */
-  start() {
-    return startEngine(this);
+  async start() {
+    try {
+      await startEngine(this);
+    } catch (err) {
+      await this.stop().catch(() => {
+      });
+      throw err;
+    }
   }
   /**
-   * Stops replicating, abandons any sync in flight, and disconnects the transport.
+   * Stops replicating, aborts every first sync that this node serves, and disconnects the transport.
    */
   async stop() {
-    if (!this.running) return;
-    this.running = false;
-    stopCoordinatorTimers(this);
-    this.syncJoiner.stopTimers();
-    this.syncServer.abortAll();
-    if (this.syncState.phase === "syncing") {
-      try {
-        await setForeignKeysEnabled(this.writerConn, true);
-      } catch (err) {
-        const wrappedErr = err instanceof Error ? err : new Error(String(err));
-        this.emitError({ error: wrappedErr, operation: "engine-stop-pragma-restore", recoverable: false });
-      }
-    }
-    this.senderLoop.stop();
-    if (this.tracker) {
-      this.tracker.clearPruneBoundary();
-    }
-    await stopCoordinatorMode(this);
-    await this.config.transport.disconnect();
+    await stopEngine(this);
   }
   /**
-   * Reports where this node stands.
+   * Returns this node's replication status.
    *
-   * @returns The node's role, its peers, its progress, its health, and its group state.
+   * @returns The node's role, peers, sequence position, sync state, health, and coordinator group state.
    */
   status() {
     return {
@@ -3159,74 +3255,78 @@ var ReplicationEngine = class extends EventEmitter {
     };
   }
   /**
-   * Returns the highest change-log position this node has recorded locally.
+   * Returns the highest position in this node's local change log.
    *
-   * @returns That position, which a caller waits for a replica to reach.
+   * @returns That position, which a caller can wait for a replica to reach.
    */
   getCurrentSeq() {
     return this.lastLocalSeq;
   }
   /**
-   * Returns how far this node has applied one peer's changes.
+   * Returns the highest applied position from one peer's change log.
    *
-   * @param peerId - Identifier of the peer.
-   * @returns The highest position from that peer this node has applied.
+   * @param peerId - The peer's node ID.
+   * @returns That position, or `0n` before this node applies any change from that peer.
    */
   getAppliedSeq(peerId) {
     return this.appliedSeqByPeer.get(peerId) ?? 0n;
   }
   /**
-   * Runs a read, refusing it when the node cannot meet the read concern.
+   * Executes a read, and throws when this node is still syncing or cannot meet the read concern.
    *
-   * @param sql - The statement to run.
-   * @param params - Values bound to the statement, named or positional.
-   * @param options - Read concern for this statement.
-   * @returns The rows the statement produced.
+   * @param sql - The statement to execute.
+   * @param params - The values to bind to the statement, named or positional.
+   * @param options - The read concern for this statement.
+   * @returns The rows that the statement returns.
    */
   query(sql, params, options) {
     return query(this, sql, params, options);
   }
   /**
-   * Runs one write, forwarding it to the primary when this node accepts no writes and forwarding is on.
+   * Executes one write on this node, or forwards it to the primary when this node cannot accept writes and
+   * `writeForwarding` is on.
    *
-   * @param sql - The statement to run.
-   * @param params - Values bound to the statement, named or positional.
-   * @param options - Write concern for this statement.
-   * @returns How many rows changed, and the last inserted row id.
+   * @param sql - The statement to execute.
+   * @param params - The values to bind to the statement, named or positional.
+   * @param options - The write concern for this statement, which the primary also applies to a forwarded write before it answers.
+   * @returns The number of rows that changed and the ID of the last inserted row.
    */
   execute(sql, params, options) {
-    return execute(this, sql, params, options);
+    return execute2(this, sql, params, options);
   }
   /**
-   * Runs one statement over many parameter sets in a single transaction.
+   * Executes one statement once for each parameter set and commits every set in one transaction, on this node or, when
+   * this node forwards the batch, on the primary.
    *
-   * @param sql - The statement to run for each parameter set.
-   * @param paramsBatch - One parameter set per run.
-   * @param options - Write concern for the transaction.
+   * @param sql - The statement to execute for each parameter set.
+   * @param paramsBatch - One parameter set per execution.
+   * @param options - The write concern for the batch, which the primary also applies to a forwarded batch before it answers.
    * @returns One result per parameter set, in order.
    */
   executeBatch(sql, paramsBatch, options) {
     return executeBatch(this, sql, paramsBatch, options);
   }
   /**
-   * Runs a function inside one transaction on this node.
+   * Calls `fn` inside one transaction on this node. On a node that cannot accept writes, it throws a `TopologyError`,
+   * since the engine forwards only `execute` and `executeBatch` writes to the primary.
    *
-   * @param fn - Receives the transaction and runs statements on it.
-   * @param options - Write concern for the transaction.
-   * @returns Whatever the function returned.
+   * @param fn - The function that receives the transaction and executes statements on it.
+   * @param options - The write concern to wait for after the transaction commits.
+   * @returns The value that `fn` resolves to.
    */
   transaction(fn, options) {
     return transaction(this, fn, options);
   }
   /**
-   * Sends a write to the primary and waits for its result.
+   * Sends the statements to the primary, which executes them in one transaction, and returns the primary's result.
+   * When this node is the primary, it executes them here in the same way.
    *
-   * @param statements - The statements to run, in order, each with its own parameters.
-   * @param options - Write concern the primary applies.
-   * @returns What the primary reported for each statement.
+   * @param statements - The statements to execute, in order, each with its own parameters.
+   * @param options - The write concern that the primary applies to the statements before it answers.
+   * @returns The result of each statement, in order, and the request ID.
    */
   forwardStatements(statements, options) {
-    return forwardStatements(this, statements);
+    return forwardStatements(this, statements, options);
   }
   /** @internal */
   emitError(event) {
@@ -3254,7 +3354,7 @@ var ReplicationEngine = class extends EventEmitter {
     return getForwardingPrimaryPeerId(this);
   }
   /**
-   * Stamps an outgoing replication message with this node's group and primary term.
+   * Returns a copy of an outgoing replication message with this node's group ID and primary term added.
    *
    * @internal
    */
@@ -3266,7 +3366,7 @@ var ReplicationEngine = class extends EventEmitter {
 // src/replication/topology/primary-replica.ts
 var PrimaryReplicaTopology = class {
   /**
-   * Whether this node accepts writes or serves reads.
+   * Records whether this node is the primary, which accepts writes, or a replica, which serves reads.
    */
   role;
   constructor(role) {
@@ -3291,7 +3391,7 @@ var PrimaryReplicaTopology = class {
     return this.role === "primary" && peerRole === "replica";
   }
   /**
-   * Reports whether this node applies changes arriving from a given peer.
+   * Reports whether this node applies the changes that a given peer sends.
    *
    * @param _peerId - Identifier of the peer, which this topology ignores.
    * @param peerRole - Role of the peer.
@@ -3301,7 +3401,8 @@ var PrimaryReplicaTopology = class {
     return this.role === "replica" && peerRole === "primary";
   }
   /**
-   * Reports whether incoming changes need a resolver, which a single writer removes the need for.
+   * Reports whether the engine has to resolve conflicts for this topology. Only the primary writes, so the answer is
+   * always false.
    *
    * @returns False.
    */