@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/replication/index.mjs

@@ -1,16 +1,16 @@
 import { compatibilityAllowsPromotion } from '../chunk-ER7ODTDA.mjs';
-import { WriteConcernError, AuthorityError, SyncError, TopologyError, CoordinatorError, StalePrimaryError, NodeDrainingError, NodeNotInSyncError, ReadConcernError, ProtocolVersionMismatchError } from '../chunk-O7SLN3GI.mjs';
-export { AuthorityError, ConflictError, CoordinatorError, FailoverError, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, ProtocolVersionMismatchError, ReadConcernError, StalePrimaryError, SyncError, TopologyError, TransportError, UnsafeRecoveryRequiredError, WriteConcernError } from '../chunk-O7SLN3GI.mjs';
-import { LWWResolver, HLC, BatchReader, BatchApplier, StampOps, isWellFormedHlc, Transaction, loadPersistedHlc } from '../chunk-HR5CWTLC.mjs';
-export { HLC, LWWResolver } from '../chunk-HR5CWTLC.mjs';
-import '../chunk-JZGINXTN.mjs';
-import { DumpOps, dumpSchema, tablesInFkOrder } from '../chunk-OQVZBEBY.mjs';
-import { canonicaliseForChecksum, PkResolver, setForeignKeysEnabled, selectMaxAppliedSourceSeqByNode, selectMaxChangeHlc, selectMaxColumnVersionHlc, selectMaxAppliedSourceSeq, upsertPeerAckedSeq, selectPeerAckedSeq, selectMaxChangeSeq, selectMinPeerAckedSeq, upsertSyncTableStatus, upsertSyncMeta, selectSyncMetaRow, selectCompletedSyncTableNames, ensureChangesTable, ensureReplicationStateTables, ensureMetaTable, IDENTIFIER_RE, deleteSyncTableStates, extractDroppedTable, insertDdlChange, prepareInsertAppliedChange } from '../chunk-NVQS53NT.mjs';
-import { ReplicationError, BatchValidationError } from '../chunk-5NOIGN5Y.mjs';
-export { BatchValidationError, ReplicationError } from '../chunk-5NOIGN5Y.mjs';
-import { CHANGES_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-D7LAYTKN.mjs';
+import { WriteConcernError, AuthorityError, SyncError, TopologyError, CoordinatorError, 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-P2VJYRVY.mjs';
+export { HLC, LWWResolver } from '../chunk-P2VJYRVY.mjs';
+import '../chunk-HCCGEIZ2.mjs';
+import { DumpOps, dumpSchema, tablesInFkOrder } from '../chunk-XF2HH5E6.mjs';
+import { canonicaliseForChecksum, PkResolver, setForeignKeysEnabled, selectMaxChangeHlc, selectMaxColumnVersionHlc, selectMaxAppliedSourceSeq, upsertPeerAckedSeq, selectPeerAckedSeq, selectMaxChangeSeq, selectMinPeerAckedSeq, upsertSyncTableStatus, upsertSyncMeta, selectSyncMetaRow, selectCompletedSyncTableNames, ensureChangesTable, ensureReplicationStateTables, ensureMetaTable, IDENTIFIER_RE, deleteSyncTableStates, extractDroppedTable, insertDdlChange, prepareInsertAppliedChange, selectMaxAppliedSourceSeqByNode } from '../chunk-7FQRQH5Z.mjs';
+import { ReplicationError, BatchValidationError } from '../chunk-2QLXDHAP.mjs';
+export { BatchValidationError, ReplicationError } from '../chunk-2QLXDHAP.mjs';
+import { CHANGES_TABLE, INTERNAL_TABLE_PREFIX } from '../chunk-7R4ER4FB.mjs';
 import '../chunk-GVCNMPOS.mjs';
-import '../chunk-UC3SCMIN.mjs';
+import '../chunk-PBRXXISQ.mjs';
 import { EventEmitter } from 'events';
 import { randomBytes, randomUUID, createHash } from 'crypto';
 
@@ -21,6 +21,12 @@ var FieldMergeResolver = class {
   constructor(getColumnVersions) {
     this.getColumnVersions = getColumnVersions;
   }
+  /**
+   * Merges columns only one side changed, and settles overlapping columns by their per-column stamps.
+   *
+   * @param ctx - The local and incoming versions of one row.
+   * @returns Which version to write, or the merged row.
+   */
   async resolve(ctx) {
     const columnVersions = await this.getColumnVersions(ctx.table, ctx.rowId);
     if (columnVersions.size === 0) {
@@ -95,6 +101,12 @@ var PrimaryWinsResolver = class {
   constructor(primaryNodeId) {
     this.primaryNodeId = primaryNodeId;
   }
+  /**
+   * Takes the version authored by the configured primary node, and falls back to last-writer-wins otherwise.
+   *
+   * @param ctx - The local and incoming versions of one row.
+   * @returns Which version to write.
+   */
   resolve(ctx) {
     if (ctx.remoteChange.nodeId === this.primaryNodeId) {
       return { action: "accept_remote" };
@@ -246,7 +258,7 @@ var ReplicationLog = class {
       changesTable
     );
     this.stampOps = new StampOps(localNodeId, hlc, changesTable);
-    this.dump = new DumpOps(conn, localNodeId, hlc, this.pkResolver);
+    this.dump = new DumpOps(conn, this.pkResolver);
   }
   pkResolver;
   state;
@@ -294,9 +306,6 @@ var ReplicationLog = class {
   unregisterActiveSyncSeq(seq) {
     this.state.unregisterActiveSyncSeq(seq);
   }
-  dumpTable(table, batchSize) {
-    return this.dump.dumpTable(table, batchSize);
-  }
   dumpTableOnConnection(conn, table, batchSize) {
     return this.dump.dumpTableOnConnection(conn, table, batchSize);
   }
@@ -657,6 +666,14 @@ async function refreshCoordinatorState(engine) {
     );
   }
 }
+function resolverFor(engine, table) {
+  const specific = table ? engine.config.conflictResolvers?.[table] : void 0;
+  return specific ?? engine.defaultResolver;
+}
+function resolveWriteConcern(engine, wc) {
+  if (wc) return wc;
+  return engine.isCoordinatorMode() ? { level: "majority" } : void 0;
+}
 function getCoordinatorMessageFields(engine) {
   const config = engine.config.coordinator;
   if (!config) return {};
@@ -1409,6 +1426,19 @@ async function forwardStatements(engine, statements, _options) {
   });
 }
 
+// src/replication/engine/internal-types.ts
+function initialSyncState() {
+  return {
+    phase: "ready",
+    sourcePeerId: null,
+    snapshotSeq: null,
+    completedTables: [],
+    totalTables: 0,
+    startedAt: null,
+    error: null
+  };
+}
+
 // src/replication/engine/replication-transaction.ts
 var ReplicationTransaction = class extends Transaction {
   constructor(txConn, hooks) {
@@ -1435,6 +1465,18 @@ var ReplicationTransaction = class extends Transaction {
   }
 };
 
+// src/replication/engine/trigger-refresh.ts
+async function refreshTriggersAfterDdl(engine) {
+  const tracker = engine.tracker;
+  if (!tracker) return;
+  for (const table of Array.from(tracker.watchedTables)) {
+    try {
+      await tracker.watch(engine.writerConn, table);
+    } catch {
+    }
+  }
+}
+
 // src/replication/engine/local-executor.ts
 var LocalExecutor = class {
   constructor(engine) {
@@ -1488,11 +1530,11 @@ var LocalExecutor = class {
       if (droppedTable !== null && engine.tracker) {
         await engine.tracker.pruneDroppedTables(engine.writerConn, [droppedTable]);
       }
-      await engine.refreshTriggersAfterDdl();
+      await refreshTriggersAfterDdl(engine);
     }
-    const writeConcern = engine.resolveWriteConcern(options?.writeConcern);
+    const writeConcern = resolveWriteConcern(engine, options?.writeConcern);
     if (writeConcern) {
-      await engine.waitForWriteConcern(newSeq, writeConcern);
+      await waitForWriteConcern(engine, newSeq, writeConcern);
     }
     return result;
   }
@@ -1556,7 +1598,7 @@ var LocalExecutor = class {
       if (droppedTables.length > 0 && engine.tracker) {
         await engine.tracker.pruneDroppedTables(engine.writerConn, droppedTables);
       }
-      await engine.refreshTriggersAfterDdl();
+      await refreshTriggersAfterDdl(engine);
     }
     return { results, requestId };
   }
@@ -1609,11 +1651,11 @@ var LocalExecutor = class {
       if (hooks.droppedTables.length > 0 && engine.tracker) {
         await engine.tracker.pruneDroppedTables(engine.writerConn, hooks.droppedTables);
       }
-      await engine.refreshTriggersAfterDdl();
+      await refreshTriggersAfterDdl(engine);
     }
-    const writeConcern = engine.resolveWriteConcern(options?.writeConcern);
+    const writeConcern = resolveWriteConcern(engine, options?.writeConcern);
     if (writeConcern) {
-      await engine.waitForWriteConcern(newSeq, writeConcern);
+      await waitForWriteConcern(engine, newSeq, writeConcern);
     }
     return userResult;
   }
@@ -1725,7 +1767,7 @@ var SenderLoop = class {
       const fromSeq = peerState?.lastSentSeq ?? engine.lastSentSeq;
       const rawBatch = await engine.log.readBatch(fromSeq, engine.batchSize);
       if (!rawBatch) continue;
-      const batch = engine.decorateBatch(rawBatch);
+      const batch = engine.decorate(rawBatch);
       const previousSeq = peerState?.lastSentSeq ?? 0n;
       if (peerState) {
         peerState.pendingBatches += 1;
@@ -1796,6 +1838,9 @@ async function delayAckIfConfigured(engine) {
 }
 
 // src/replication/engine/transport-wiring.ts
+function clockDriftMs(remoteHlc) {
+  return Math.abs(Date.now() - HLC.decode(remoteHlc).wallMs);
+}
 function replicatesFrom(engine, peer) {
   if (engine.isCoordinatorMode()) {
     return engine.coordinatorState?.currentPrimary?.nodeId === peer.id;
@@ -1811,11 +1856,11 @@ async function reportAppliedPosition(engine, peer, appliedSeq) {
   if (!servesItsData((await engine.log.getSyncState()).phase)) return;
   await engine.config.transport.sendAck(
     peer.id,
-    engine.decorateAck({ batchId: "", ackedSeq: appliedSeq, nodeId: engine.nodeId })
+    engine.decorate({ batchId: "", ackedSeq: appliedSeq, nodeId: engine.nodeId })
   );
 }
 function persistAckProgress(engine, nodeId, ackedSeq) {
-  engine.log.setLastAppliedSeq(nodeId, ackedSeq).then(() => engine.handleCoordinatorAckProgress(nodeId, ackedSeq)).catch((err) => {
+  engine.log.setLastAppliedSeq(nodeId, ackedSeq).then(() => handleCoordinatorAckProgress(engine, nodeId, ackedSeq)).catch((err) => {
     const wrappedErr = err instanceof Error ? err : new Error(String(err));
     engine.emitError({ error: wrappedErr, operation: "ack-state-persist", peerId: nodeId, recoverable: true });
   });
@@ -1840,23 +1885,23 @@ function wireTransportHandlers(engine) {
           throw new ReplicationError(`Rejected batch from unauthorized peer: ${fromPeerId}`);
         }
       }
-      await engine.assertInboundCoordinatorMessage(batch, fromPeerId, "batch");
+      await assertInboundCoordinatorMessage(engine, batch, fromPeerId, "batch");
       if (batch.changes.length > engine.maxBatchChanges) {
         throw new BatchValidationError(
           `Batch too large: ${batch.changes.length} changes exceeds max ${engine.maxBatchChanges}`
         );
       }
-      const drift = engine.checkClockDrift(batch.hlcRange.max);
+      const drift = clockDriftMs(batch.hlcRange.max);
       if (drift > engine.maxClockDriftMs) {
         throw new BatchValidationError(`Clock drift too high: ${drift}ms exceeds max ${engine.maxClockDriftMs}ms`);
       }
-      const applyResult = await engine.log.applyBatch(batch, (table) => engine.getResolver(table));
+      const applyResult = await engine.log.applyBatch(batch, (table) => resolverFor(engine, table));
       const batchContainedDdl = batch.changes.some((c) => c.operation === "ddl");
       if (batchContainedDdl) {
         if (applyResult.droppedTables.length > 0 && engine.tracker) {
           await engine.tracker.pruneDroppedTables(engine.writerConn, applyResult.droppedTables);
         }
-        await engine.refreshTriggersAfterDdl();
+        await refreshTriggersAfterDdl(engine);
       }
       await engine.log.setLastAppliedSeq(fromPeerId, batch.toSeq);
       const previousApplied = engine.appliedSeqByPeer.get(fromPeerId) ?? 0n;
@@ -1869,7 +1914,7 @@ function wireTransportHandlers(engine) {
       await delayAckIfConfigured(engine);
       await engine.config.transport.sendAck(
         fromPeerId,
-        engine.decorateAck({
+        engine.decorate({
           batchId: batch.batchId,
           ackedSeq: batch.toSeq,
           nodeId: engine.nodeId
@@ -1900,7 +1945,7 @@ function wireTransportHandlers(engine) {
       persistAckProgress(engine, ack.nodeId, ack.ackedSeq);
       return;
     }
-    engine.assertInboundCoordinatorMessage(ack, fromPeerId, "ack").then(() => {
+    assertInboundCoordinatorMessage(engine, ack, fromPeerId, "ack").then(() => {
       engine.peerTracker.onAckReceived(ack.nodeId, ack.ackedSeq);
       persistAckProgress(engine, ack.nodeId, ack.ackedSeq);
     }).catch((err) => {
@@ -1913,14 +1958,14 @@ function wireTransportHandlers(engine) {
       if (engine.syncState.phase !== "ready" && engine.syncState.phase !== "catching-up") {
         throw new ReplicationError("Node is not ready to handle forwarded requests");
       }
-      await engine.assertInboundCoordinatorMessage(request, fromPeerId, "forward");
+      await assertInboundCoordinatorMessage(engine, request, fromPeerId, "forward");
       const knownPeers = engine.config.transport.peers();
       if (!knownPeers.has(fromPeerId)) {
         throw new ReplicationError(`Rejected forward from unknown peer: ${fromPeerId}`);
       }
       try {
         const result = await engine.localExecutor.executeForwardedLocally(request.statements);
-        return engine.decorateForwardResult(result);
+        return engine.decorate(result);
       } catch (err) {
         const wrappedErr = err instanceof Error ? err : new Error(String(err));
         engine.emitError({ error: wrappedErr, operation: "forward-execution", peerId: fromPeerId, recoverable: true });
@@ -1934,7 +1979,7 @@ function wireTransportHandlers(engine) {
       if (!engine.running) return;
       engine.peerTracker.onAckReceived(peer.id, ackedSeq);
       await engine.log.setLastAppliedSeq(peer.id, ackedSeq);
-      await engine.handleCoordinatorAckProgress(peer.id, ackedSeq);
+      await handleCoordinatorAckProgress(engine, peer.id, ackedSeq);
       await reportAppliedPosition(engine, peer, ackedSeq);
     }).catch((err) => {
       const wrappedErr = err instanceof Error ? err : new Error(String(err));
@@ -1967,17 +2012,17 @@ function wireTransportHandlers(engine) {
   });
   engine.config.transport.onSyncRequested(async (request, fromPeerId) => {
     if (!engine.running) return;
-    await engine.assertInboundCoordinatorMessage(request, fromPeerId, "sync-request");
+    await assertInboundCoordinatorMessage(engine, request, fromPeerId, "sync-request");
     await engine.syncServer.handleSyncRequest(request, fromPeerId);
   });
   engine.config.transport.onSyncBatchReceived(async (batch, fromPeerId) => {
     if (!engine.running) return;
-    await engine.assertInboundCoordinatorMessage(batch, fromPeerId, "sync-data");
+    await assertInboundCoordinatorMessage(engine, batch, fromPeerId, "sync-data");
     await engine.syncJoiner.handleSyncBatchReceived(batch, fromPeerId);
   });
   engine.config.transport.onSyncCompleteReceived(async (complete, fromPeerId) => {
     if (!engine.running) return;
-    await engine.assertInboundCoordinatorMessage(complete, fromPeerId, "sync-data");
+    await assertInboundCoordinatorMessage(engine, complete, fromPeerId, "sync-data");
     await engine.syncJoiner.handleSyncCompleteReceived(complete, fromPeerId);
   });
   engine.config.transport.onSyncAckReceived((ack, fromPeerId) => {
@@ -2002,7 +2047,7 @@ function wireTransportHandlers(engine) {
       engine.syncServer.handleSyncAckReceived(ack);
       return;
     }
-    engine.assertInboundCoordinatorMessage(ack, fromPeerId, "ack").then(() => {
+    assertInboundCoordinatorMessage(engine, ack, fromPeerId, "ack").then(() => {
       engine.syncServer.handleSyncAckReceived(ack);
     }).catch((err) => {
       const wrappedErr = err instanceof Error ? err : new Error(String(err));
@@ -2012,6 +2057,11 @@ function wireTransportHandlers(engine) {
 }
 
 // src/replication/engine/startup.ts
+async function loadAppliedSeqs(engine) {
+  for (const [nodeId, seq] of await selectMaxAppliedSourceSeqByNode(engine.writerConn)) {
+    engine.appliedSeqByPeer.set(nodeId, seq);
+  }
+}
 async function recoverHlcFromDurableState(engine) {
   const persisted = await loadPersistedHlc(engine.writerConn);
   if (persisted !== null) {
@@ -2028,9 +2078,9 @@ async function startEngine(engine) {
   await recoverHlcFromDurableState(engine);
   engine.lastSentSeq = await engine.log.getLocalSeq();
   engine.lastLocalSeq = engine.lastSentSeq;
-  await engine.loadAppliedSeqs();
-  await engine.startCoordinatorMode();
-  await engine.prepareCoordinatorRejoinIfNeeded();
+  await loadAppliedSeqs(engine);
+  await startCoordinatorMode(engine);
+  await prepareCoordinatorRejoinIfNeeded(engine);
   wireTransportHandlers(engine);
   const transportConfig = {
     ...engine.config.transportConfig,
@@ -2040,10 +2090,10 @@ async function startEngine(engine) {
     protocolVersion: engine.config.coordinator?.compatibility?.protocolVersion ?? engine.config.transportConfig?.protocolVersion
   };
   await engine.config.transport.connect(engine.nodeId, transportConfig);
-  const isPrimary = engine.isCoordinatorMode() ? engine.hasCoordinatorWriteAuthority() : engine.config.topology.role === "primary";
+  const isPrimary = engine.isCoordinatorMode() ? engine.coordinatorAuthority : engine.config.topology.role === "primary";
   const syncCompleted = await engine.log.isSyncCompleted();
-  const requiresCoordinatorRejoinSync2 = engine.requiresCoordinatorRejoinSync();
-  if (engine.initialSync && !isPrimary && (!syncCompleted || requiresCoordinatorRejoinSync2)) {
+  const rejoinSyncRequired = requiresCoordinatorRejoinSync(engine, engine.coordinatorState);
+  if (engine.initialSync && !isPrimary && (!syncCompleted || rejoinSyncRequired)) {
     const savedState = await engine.log.getSyncState();
     if (savedState.phase === "syncing") {
       if (!engine.tracker) {
@@ -2080,7 +2130,7 @@ async function startEngine(engine) {
         startedAt: null,
         error: null
       };
-      engine.startSenderLoop();
+      engine.senderLoop.start();
       engine.syncJoiner.startCatchUpCheck();
       return;
     }
@@ -2099,7 +2149,7 @@ async function startEngine(engine) {
   } else {
     engine.syncState.phase = "ready";
   }
-  engine.startSenderLoop();
+  engine.senderLoop.start();
 }
 
 // src/replication/engine/sync-recovery.ts
@@ -2270,7 +2320,7 @@ var SyncJoiner = class {
       await engine.log.setSyncMeta("syncing", void 0, sourcePeerId, requestId);
       await engine.config.transport.requestSync(
         sourcePeerId,
-        engine.decorateSyncRequest({
+        engine.decorate({
           requestId,
           joinerNodeId: engine.nodeId,
           completedTables,
@@ -2463,7 +2513,7 @@ var SyncJoiner = class {
       engine.syncState.phase = "catching-up";
       engine.syncState.snapshotSeq = complete.snapshotSeq;
       await engine.log.setSyncMeta("catching-up", complete.snapshotSeq);
-      engine.startSenderLoop();
+      engine.senderLoop.start();
       this.startCatchUpCheck();
     } catch {
       try {
@@ -2539,7 +2589,7 @@ var SyncJoiner = class {
   }
   async sendSyncAck(peerId, ack) {
     await delayAckIfConfigured(this.engine);
-    await this.engine.config.transport.sendSyncAck(peerId, this.engine.decorateSyncAck(ack));
+    await this.engine.config.transport.sendSyncAck(peerId, this.engine.decorate(ack));
   }
   async finishCatchUpAsReady() {
     const engine = this.engine;
@@ -2559,7 +2609,7 @@ var SyncServer = class {
   async rejectSyncRequest(fromPeerId, request, error) {
     await this.engine.config.transport.sendSyncAck(
       fromPeerId,
-      this.engine.decorateSyncAck({
+      this.engine.decorate({
         requestId: request.requestId,
         joinerNodeId: request.joinerNodeId,
         table: "__schema__",
@@ -2729,7 +2779,7 @@ var SyncServer = class {
   async sendSyncBatchAndWaitForAck(peerId, batch) {
     const ackPromise = this.waitForSyncAck(batch.requestId, batch.table, batch.batchIndex);
     try {
-      await this.engine.config.transport.sendSyncBatch(peerId, this.engine.decorateSyncBatch(batch));
+      await this.engine.config.transport.sendSyncBatch(peerId, this.engine.decorate(batch));
     } catch (err) {
       const key = `${batch.requestId}:${batch.table}:${batch.batchIndex}`;
       const waiter = this.syncAckWaiters.get(key);
@@ -2837,7 +2887,7 @@ var SyncServer = class {
     }
     await engine.config.transport.sendSyncComplete(
       session.joinerNodeId,
-      engine.decorateSyncComplete({
+      engine.decorate({
         requestId: session.requestId,
         snapshotSeq: session.snapshotSeq,
         manifests
@@ -2873,62 +2923,105 @@ var SyncServer = class {
 
 // src/replication/engine/engine.ts
 var ReplicationEngine = class extends EventEmitter {
+  /** @internal */
   database;
+  /** @internal */
   writerConn;
+  /** @internal */
   config;
+  /**
+   * Identifier of this node, which every change it authors carries.
+   */
   nodeId;
+  /** @internal */
   hlc;
+  /** @internal */
   log;
+  /** @internal */
   peerTracker = new PeerTracker();
+  /** @internal */
   defaultResolver;
+  /** @internal */
   tracker;
+  /** @internal */
   snapshotConnectionFactory;
+  /** @internal */
   batchSize;
+  /** @internal */
   batchIntervalMs;
+  /** @internal */
   maxClockDriftMs;
+  /** @internal */
   maxPendingBatches;
+  /** @internal */
   maxBatchChanges;
+  /** @internal */
   ackTimeoutMs;
+  /** @internal */
   initialSync;
+  /** @internal */
   syncBatchSize;
+  /** @internal */
   maxConcurrentSyncs;
+  /** @internal */
   maxSyncDurationMs;
+  /** @internal */
   maxSyncLagBeforeReady;
+  /** @internal */
   syncAckTimeoutMs;
+  /** @internal */
   catchUpDeadlineMs;
+  /** @internal */
   resumeFromSeq;
+  /** @internal */
   running = false;
+  /** @internal */
   coordinatorState = null;
+  /** @internal */
   coordinatorAuthority = false;
+  /** @internal */
   controllerState = "disabled";
+  /** @internal */
   nodeSessionLeaseId = null;
+  /** @internal */
   controllerLeaseId = null;
+  /** @internal */
   coordinatorWatchDisposer = null;
+  /** @internal */
   coordinatorLeaseTimer = null;
+  /** @internal */
   controllerTimer = null;
+  /** @internal */
   coordinatorRejoinSyncStarting = false;
+  /** @internal */
   coordinatorSessionRestoring = false;
+  /** @internal */
   coordinatorLastContactMs = 0;
+  /** @internal */
   inSyncReconcileTimer = null;
+  /** @internal */
   inSyncReconciling = false;
+  /** @internal */
   lastSentSeq = 0n;
+  /** @internal */
   lastLocalSeq = 0n;
+  /** @internal */
   highestSourceSeqSeen = 0n;
+  /** @internal */
   appliedSeqByPeer = /* @__PURE__ */ new Map();
+  /** @internal */
   expectedBatchIndex = /* @__PURE__ */ new Map();
+  /** @internal */
   syncTableDigests = /* @__PURE__ */ new Map();
-  syncState = {
-    phase: "ready",
-    sourcePeerId: null,
-    snapshotSeq: null,
-    completedTables: [],
-    totalTables: 0,
-    startedAt: null,
-    error: null
-  };
+  /** @internal */
+  syncState = initialSyncState();
+  /** @internal */
   localExecutor;
+  /** @internal */
   syncServer;
+  /** @internal */
   syncJoiner;
+  /** @internal */
   senderLoop;
   constructor(database, writerConn, config) {
     super();
@@ -2964,9 +3057,15 @@ var ReplicationEngine = class extends EventEmitter {
     this.senderLoop = new SenderLoop(this);
     installTestHooks(this);
   }
+  /**
+   * Connects the transport, pulls a full copy when this node needs one, and starts replicating.
+   */
   start() {
     return startEngine(this);
   }
+  /**
+   * Stops replicating, abandons any sync in flight, and disconnects the transport.
+   */
   async stop() {
     if (!this.running) return;
     this.running = false;
@@ -2988,6 +3087,11 @@ var ReplicationEngine = class extends EventEmitter {
     await stopCoordinatorMode(this);
     await this.config.transport.disconnect();
   }
+  /**
+   * Reports where this node stands.
+   *
+   * @returns The node's role, its peers, its progress, its health, and its group state.
+   */
   status() {
     return {
       nodeId: this.nodeId,
@@ -3000,30 +3104,77 @@ var ReplicationEngine = class extends EventEmitter {
       coordinator: getCoordinatorRuntimeStatus(this)
     };
   }
+  /**
+   * Returns the highest change-log position this node has recorded locally.
+   *
+   * @returns That position, which a caller waits for a replica to reach.
+   */
   getCurrentSeq() {
     return this.lastLocalSeq;
   }
+  /**
+   * Returns how far this node has applied one peer's changes.
+   *
+   * @param peerId - Identifier of the peer.
+   * @returns The highest position from that peer this node has applied.
+   */
   getAppliedSeq(peerId) {
     return this.appliedSeqByPeer.get(peerId) ?? 0n;
   }
+  /**
+   * Runs a read, refusing it when the node 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.
+   */
   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.
+   *
+   * @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.
+   */
   execute(sql, params, options) {
     return execute(this, sql, params, options);
   }
+  /**
+   * Runs one statement over many parameter sets in a single transaction.
+   *
+   * @param sql - The statement to run for each parameter set.
+   * @param paramsBatch - One parameter set per run.
+   * @param options - Write concern for the transaction.
+   * @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.
+   *
+   * @param fn - Receives the transaction and runs statements on it.
+   * @param options - Write concern for the transaction.
+   * @returns Whatever the function returned.
+   */
   transaction(fn, options) {
     return transaction(this, fn, options);
   }
+  /**
+   * Sends a write to the primary and waits for its result.
+   *
+   * @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.
+   */
   forwardStatements(statements, options) {
     return forwardStatements(this, statements);
   }
-  startSenderLoop() {
-    this.senderLoop.start();
-  }
+  /** @internal */
   emitError(event) {
     if (this.listenerCount("replication-error") > 0) {
       try {
@@ -3032,110 +3183,74 @@ var ReplicationEngine = class extends EventEmitter {
       }
     }
   }
-  getResolver(table) {
-    if (table && this.config.conflictResolvers) {
-      const specific = this.config.conflictResolvers[table];
-      if (specific) return specific;
-    }
-    return this.defaultResolver;
-  }
-  checkClockDrift(remoteHlc) {
-    const decoded = HLC.decode(remoteHlc);
-    return Math.abs(Date.now() - decoded.wallMs);
-  }
-  async refreshTriggersAfterDdl() {
-    if (!this.tracker) return;
-    const tables = Array.from(this.tracker.watchedTables);
-    for (const table of tables) {
-      try {
-        await this.tracker.watch(this.writerConn, table);
-      } catch {
-      }
-    }
-  }
-  waitForWriteConcern(seq, wc) {
-    return waitForWriteConcern(this, seq, wc);
-  }
-  async loadAppliedSeqs() {
-    for (const [nodeId, seq] of await selectMaxAppliedSourceSeqByNode(this.writerConn)) {
-      this.appliedSeqByPeer.set(nodeId, seq);
-    }
-  }
+  /** @internal */
   isCoordinatorMode() {
     return this.config.coordinator !== void 0;
   }
-  startCoordinatorMode() {
-    return startCoordinatorMode(this);
-  }
-  prepareCoordinatorRejoinIfNeeded() {
-    return prepareCoordinatorRejoinIfNeeded(this);
-  }
-  hasCoordinatorWriteAuthority() {
-    return this.coordinatorAuthority;
-  }
-  requiresCoordinatorRejoinSync(state = this.coordinatorState) {
-    return requiresCoordinatorRejoinSync(this, state);
-  }
-  markCoordinatorSyncReady() {
-    return markCoordinatorSyncReady(this);
-  }
-  handleCoordinatorAckProgress(nodeId, ackedSeq) {
-    return handleCoordinatorAckProgress(this, nodeId, ackedSeq);
-  }
+  /** @internal */
   verifyPrimaryAuthority() {
     return verifyPrimaryAuthority(this);
   }
-  assertInboundCoordinatorMessage(message, fromPeerId, direction) {
-    return assertInboundCoordinatorMessage(this, message, fromPeerId, direction);
-  }
-  decorateBatch(batch) {
-    return { ...batch, ...getCoordinatorMessageFields(this) };
-  }
-  decorateAck(ack) {
-    return { ...ack, ...getCoordinatorMessageFields(this) };
-  }
-  decorateForwardResult(result) {
-    return { ...result, ...getCoordinatorMessageFields(this) };
-  }
-  decorateSyncRequest(request) {
-    return { ...request, ...getCoordinatorMessageFields(this) };
-  }
-  decorateSyncBatch(batch) {
-    return { ...batch, ...getCoordinatorMessageFields(this) };
-  }
-  decorateSyncComplete(complete) {
-    return { ...complete, ...getCoordinatorMessageFields(this) };
-  }
-  decorateSyncAck(ack) {
-    return { ...ack, ...getCoordinatorMessageFields(this) };
-  }
-  resolveWriteConcern(wc) {
-    if (wc) return wc;
-    if (this.isCoordinatorMode()) {
-      return { level: "majority" };
-    }
-    return void 0;
+  /** @internal */
+  markCoordinatorSyncReady() {
+    return markCoordinatorSyncReady(this);
   }
+  /** @internal */
   getCurrentPrimaryPeerId() {
     return getForwardingPrimaryPeerId(this);
   }
+  /**
+   * Stamps an outgoing replication message with this node's group and primary term.
+   *
+   * @internal
+   */
+  decorate(message) {
+    return { ...message, ...getCoordinatorMessageFields(this) };
+  }
 };
 
 // src/replication/topology/primary-replica.ts
 var PrimaryReplicaTopology = class {
+  /**
+   * Whether this node accepts writes or serves reads.
+   */
   role;
   constructor(role) {
     this.role = role;
   }
+  /**
+   * Reports whether this node accepts writes, which only the primary does.
+   *
+   * @returns True on the primary.
+   */
   canWrite() {
     return this.role === "primary";
   }
+  /**
+   * Reports whether this node sends its changes to a given peer.
+   *
+   * @param _peerId - Identifier of the peer, which this topology ignores.
+   * @param peerRole - Role of the peer.
+   * @returns True when this node is the primary and the peer is a replica.
+   */
   shouldReplicateTo(_peerId, peerRole) {
     return this.role === "primary" && peerRole === "replica";
   }
+  /**
+   * Reports whether this node applies changes arriving from a given peer.
+   *
+   * @param _peerId - Identifier of the peer, which this topology ignores.
+   * @param peerRole - Role of the peer.
+   * @returns True when this node is a replica and the peer is the primary.
+   */
   shouldAcceptFrom(_peerId, peerRole) {
     return this.role === "replica" && peerRole === "primary";
   }
+  /**
+   * Reports whether incoming changes need a resolver, which a single writer removes the need for.
+   *
+   * @returns False.
+   */
   requiresConflictResolution() {
     return false;
   }