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

package/dist/replication/index.d.ts

@@ -1,48 +1,51 @@
-export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-B0np8JS3.js';
-import { m as HLC, D as Database } from '../database-BLQvqjsw.js';
-import { r as BackupGroupSource, a2 as ClusterReadEndpointInfo, H as ClusterStatusInfo, I as SQLiteConnection, T as Transaction } from '../types-DPSmjU54.js';
-import { C as ClusterCoordinator, c as ReplicationGroupState, e as CoordinatorWatchDisposer } from '../types-B0EhgDbr.js';
-export { A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, h as AdmitNodeToInSyncSetInput, f as CompareAndAdvancePrimaryTermInput, g as CompareAndAdvancePrimaryTermResult, j as CoordinatorCompatibilityMetadata, k as CoordinatorLease, b as CoordinatorNodeSession, l as CoordinatorPrimary, P as PromoteEligibleReplicaInput, R as RegisterNodeSessionInput, d as ReplicationGroupWatcher, S as SetReplicationGroupStateInput, U as UpdateInSyncSetInput, i as UpdateNodeMaintenanceInput } from '../types-B0EhgDbr.js';
-import { f as ReplicationStatusInfo } from '../server-options-Bj5iJnjx.js';
-import { C as CoordinatorRuntimeStatus, g as ReplicationStatus, h as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, i as ReplicationConfig, j as SyncState, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-CbjfRwrK.js';
-export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-CbjfRwrK.js';
+export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-CHNOYuN7.js';
+import { m as HLC, D as Database } from '../database-CGDsXW1K.js';
+import { r as BackupGroupSource, a3 as ClusterReadEndpointInfo, H as ClusterStatusInfo, I as SQLiteConnection, T as Transaction } from '../types-Dc8oWlxj.js';
+import { C as ClusterCoordinator, e as ReplicationGroupState, c as CoordinatorWatchDisposer, l as CoordinatorLease } from '../types-guEKSzMr.js';
+export { A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, i as AdmitNodeToInSyncSetInput, g as CompareAndAdvancePrimaryTermInput, h as CompareAndAdvancePrimaryTermResult, b as ControllerLeaseWatcher, k as CoordinatorCompatibilityMetadata, d as CoordinatorNodeSession, m as CoordinatorPrimary, N as NodeSessionWatcher, P as PromoteEligibleReplicaInput, R as RegisterNodeSessionInput, f as ReplicationGroupWatcher, S as SetReplicationGroupStateInput, U as UpdateInSyncSetInput, j as UpdateNodeMaintenanceInput } from '../types-guEKSzMr.js';
+import { f as ReplicationStatusInfo } from '../server-options-aYtCkefX.js';
+import { C as CoordinatorRuntimeStatus, g as ReplicationStatus, h as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, i as ReplicationConfig, j as SyncState, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-BrAiDGOb.js';
+export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-BrAiDGOb.js';
 import { EventEmitter } from 'node:events';
-import { C as ChangeTracker } from '../change-tracker-CjRFuZdB.js';
-import { P as Params, Q as QueryOptions, E as ExecuteResult } from '../query-types-p1liOP-b.js';
-import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult, S as SyncTableManifest } from '../types-CjhxcjhA.js';
-export { a as ConflictContext, b as ConflictResolution, H as HLCTimestamp, c as ReplicationChange } from '../types-CjhxcjhA.js';
-import { S as SirannonError } from '../errors-Dei4GdBb.js';
-import '../database-backup-B7oszQ2n.js';
-import '../types-DTO4CYhW.js';
-import '../operation-registry-oiPuSYI6.js';
+import { C as ChangeTracker } from '../change-tracker-DqCdeEyx.js';
+import { P as Params, Q as QueryOptions, E as ExecuteResult, W as WriteConcern } from '../query-types-5B02ixH0.js';
+import { R as ReplicationBatch, C as ConflictResolver, A as ApplyResult, S as SyncTableManifest } from '../types-DqODKeOq.js';
+export { a as ConflictContext, b as ConflictResolution, H as HLCTimestamp, c as ReplicationChange } from '../types-DqODKeOq.js';
+import { S as SirannonError } from '../errors-CJUkQ-KL.js';
+import '../database-backup-DcLhxoa1.js';
+import '../types-CEJG0eFS.js';
+import '../operation-registry-CGhNT-Sn.js';
 
 /**
- * Which group a node reads its backup membership from, and where that group's
- * state is kept.
+ * Configures {@link coordinatorBackupGroup} with the coordinator that stores the
+ * group's state, the replication group to read backup membership from, and this
+ * node's ID.
  *
  * @public
  */
 interface CoordinatorBackupGroupOptions {
-    /** Where primary authority, node sessions, and group state are stored. */
+    /** Holds the coordinator that stores primary authority, node sessions, and the group state. */
     coordinator: ClusterCoordinator;
-    /** Identifier of the cluster the group belongs to. */
+    /** Identifies the cluster that contains the group. */
     clusterId: string;
-    /** Identifier of the replication group. */
+    /** Identifies the replication group. */
     groupId: string;
-    /** Identifier of this node, which must match the one it replicates under. */
+    /** Identifies this node. Pass the same node ID that this node's replication engine uses. */
     nodeId: string;
 }
 /**
- * Builds the group source a backup cycle asks before it copies anything, over
- * the coordinator the group already uses for failover.
+ * Returns a backup group source that reads the group's membership from the
+ * coordinator that the group already uses for failover. The backup cycle calls
+ * `readMembership` on the source before the cycle copies anything.
  *
- * Every node of the group passes one of these to its `backups` option, and each
- * scheduled turn reads the same membership from it. One node finds itself named
- * and takes the backup; the others stand down. A failover changes which node is
- * named, but it changes no schedule.
+ * Every node of the group passes one of these sources to its `backups` option.
+ * On each scheduled turn, every node reads the same membership and picks the
+ * same node to take the backup, while the other nodes skip that turn. A
+ * failover can change which node takes the backups, but you keep the same
+ * schedule on every node.
  *
- * This offers the nodes the group counts as in sync, less any node being
- * drained, rebuilt, or held out as faulted.
+ * The membership lists the nodes in the group's in-sync set, minus any node
+ * that the group state marks as draining, repairing, or faulted.
  *
  * @param options - The coordinator, the cluster, the group, and this node's identifier.
  * @returns The source, ready to pass as `replicationGroup`.
@@ -52,60 +55,64 @@ interface CoordinatorBackupGroupOptions {
 declare function coordinatorBackupGroup(options: CoordinatorBackupGroupOptions): BackupGroupSource;
 
 /**
- * What a node needs to know beyond its own engine state to describe its group.
+ * Holds the database ID and the node addresses that {@link toClusterStatusInfo} takes in addition to the engine
+ * status.
  *
  * @public
  */
 interface ClusterStatusOptions {
-    /** Identifier of the database the reported status describes. */
+    /** Identifies the database that the status reports on. */
     databaseId: string;
-    /** Address a client reaches each node on, keyed by node id. */
+    /** Maps each node ID to the address that a client uses to reach that node. */
     endpoints: Readonly<Record<string, string>>;
 }
 /**
- * Turns one node's engine status into the figures its readiness endpoint reports.
+ * Converts one node's engine status into the replication figures that the node's readiness endpoint reports.
  *
- * @param status - Status the replication engine reports for this node.
+ * @param status - The status that the replication engine reports for this node.
  * @returns The replication figures, ready to return from `getReplicationStatus`.
  *
  * @public
  */
 declare function toReplicationStatusInfo(status: ReplicationStatus): ReplicationStatusInfo;
 /**
- * Turns one node's engine status into what `GET /db/{id}/cluster` reports about its group.
+ * Converts one node's engine status into the group status that `GET /db/{id}/cluster` returns.
  *
- * @param status - Status the replication engine reports for this node.
- * @param options - The database this status describes and the address of each node.
+ * @param status - The status that the replication engine reports for this node.
+ * @param options - The database that this status reports on and the address of each node.
  * @returns The group status, ready to return from `getClusterStatus`.
  *
  * @public
  */
 declare function toClusterStatusInfo(status: ReplicationStatus, options: ClusterStatusOptions): ClusterStatusInfo;
 /**
- * Lists every node a client can read from, with the read concerns each one serves.
+ * Returns every node that a client can read from, with the read concerns that each node serves.
  *
- * A node counts towards majority and is neither quarantined, being taken out of
- * service, nor being rebuilt to appear at all. A node the group counts as in
- * sync serves both `local` and `majority`; one that has fallen behind serves
- * `local` alone, because the engine answers a `local` read without any in-sync
- * check.
+ * The list holds the group's voting data-bearing nodes, minus any node that the
+ * group state marks as faulted, draining, or repairing. When the coordinator
+ * status includes the IDs of the nodes with a live session, the list keeps only
+ * those nodes. A node in the in-sync set serves both `local` and `majority`
+ * reads, while any other node serves `local` reads alone, because the engine
+ * answers a `local` read without checking the in-sync set.
  *
- * @param coordinator - Group state this node last read from the coordinator.
- * @param endpoints - Address a client reaches each node on, keyed by node id.
- * @returns One entry per node a client can read from.
+ * @param coordinator - The group state that this node last read from the coordinator.
+ * @param endpoints - Maps each node ID to the address that a client uses to reach that node.
+ * @returns One entry per node that a client can read from.
  *
  * @public
  */
 declare function toClusterReadEndpoints(coordinator: CoordinatorRuntimeStatus, endpoints: Readonly<Record<string, string>>): ClusterReadEndpointInfo[];
 
 /**
- * Persistent change log that bridges CDC events and the replication protocol.
+ * Gives the replication engine one object for every read and write that it
+ * makes against the change log and the sync state that this node stores in
+ * SQLite.
  *
- * Composes specialised helpers: BatchReader (outbound batches), BatchApplier
- * (inbound batches and conflict resolution), DumpOps (table dumps and
- * manifests), SchemaOps (replication-table bootstrap, schema dump, wipe),
- * StateOps (sequence and sync metadata), and PkResolver (cached primary-key
- * lookups).
+ * Each method passes the call to one helper: BatchReader for outbound batches,
+ * BatchApplier for inbound batches and conflict resolution, StampOps for
+ * stamping local changes, DumpOps for table dumps and manifests, SchemaOps for
+ * the replication tables, the schema dump, and table wipes, StateOps for
+ * sequence and sync metadata, and PkResolver for cached primary-key lookups.
  *
  * @internal
  */
@@ -154,19 +161,21 @@ declare class ReplicationLog {
 }
 
 /**
- * Maintains in-memory state for every peer the local node communicates with.
- *
- * For each peer, PeerTracker records the last acknowledged sequence number,
- * the last sent sequence number, pending batch count, and connection status.
- * This state drives two key mechanisms:
- *
- * - **Back-pressure**: the sender loop in ReplicationEngine checks
- *   `pendingBatches` against the configured max before queuing more work
- *   for a given peer.
- * - **Write concern**: callers can await `waitForMajority` or `waitForAll`
- *   with a sequence number and timeout. These methods resolve once enough
- *   peers have acknowledged that sequence, or reject with a
- *   WriteConcernError on timeout.
+ * Keeps in memory the replication state of every peer that this node connects to.
+ *
+ * For each peer, the tracker records the last sequence number that the peer
+ * acknowledged, the last sequence number that this node sent, the number of
+ * pending batches, the batches in flight, and whether the peer is connected.
+ * The engine uses that state in two places.
+ *
+ * - Back-pressure: the sender loop skips a peer whose `pendingBatches` has
+ *   reached the configured maximum.
+ * - Write concern: a caller awaits `waitForMajority`, `waitForAll`,
+ *   `waitForConfiguredMajority`, or `waitForConfiguredAll` with a sequence
+ *   number and a timeout, and the promise resolves once enough peers
+ *   acknowledge that sequence. It rejects with a `WriteConcernError` when the
+ *   timeout expires, and a `waitForMajority` or `waitForAll` promise also
+ *   rejects early when too few peers are connected to reach the count.
  *
  * @internal
  */
@@ -176,6 +185,7 @@ declare class PeerTracker {
     addPeer(nodeId: string): void;
     removePeer(nodeId: string): void;
     onAckReceived(nodeId: string, ackedSeq: bigint): void;
+    onBatchApplied(nodeId: string, highestHlc: string): void;
     recordInFlightBatch(nodeId: string, batch: InFlightBatch): void;
     expireTimedOutBatches(nodeId: string, nowMs: number, timeoutMs: number): boolean;
     getPeerState(nodeId: string): PeerState | undefined;
@@ -192,24 +202,23 @@ declare class PeerTracker {
 }
 
 /**
- * Runs a statement on the local node and records the resulting changes in the replication log.
+ * Executes a write on this node and stamps the changes that it makes into the replication log inside the same SQLite
+ * transaction.
  *
  * @internal
  */
 declare class LocalExecutor {
     private readonly 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.
      */
     private transactionQueue;
     constructor(engine: ReplicationEngine);
@@ -217,16 +226,20 @@ declare class LocalExecutor {
         changes: number;
         lastInsertRowId: number | bigint;
     }>;
+    executeBatchLocally(sql: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
     executeForwardedLocally(statements: Array<{
         sql: string;
         params?: Params;
-    }>): Promise<ForwardedTransactionResult>;
+    }>, statedWriteConcern?: WriteConcern): Promise<ForwardedTransactionResult>;
+    private waitForWriteConcernOf;
+    private executeInOneTransaction;
     executeTransactionLocally<T>(fn: (tx: Transaction) => Promise<T>, options?: QueryOptions): Promise<T>;
     private runTransaction;
 }
 
 /**
- * Batches locally recorded changes and pushes them to the peers the topology accepts.
+ * Sends the changes in this node's replication log to its peers in batches, on a timer. In coordinator mode, the
+ * loop sends only while this node holds primary authority; otherwise, the topology's `shouldReplicateTo` picks the peers.
  *
  * @internal
  */
@@ -242,7 +255,8 @@ declare class SenderLoop {
 }
 
 /**
- * Drives a joining node through first sync and the catch-up that follows it.
+ * Copies a source node's tables onto a joining node through a first sync, then marks the node ready once its catch-up
+ * lag falls within the configured limit or the catch-up deadline passes.
  *
  * @internal
  */
@@ -265,7 +279,8 @@ declare class SyncJoiner {
 }
 
 /**
- * Serves first-sync requests from joining nodes by streaming schema, table pages, and a manifest.
+ * Answers a joining node's first-sync request by streaming the schema, then each table's rows in batches, and last a
+ * manifest for every table that it streamed.
  *
  * @internal
  */
@@ -295,8 +310,8 @@ type CoordinatorStampedMessage = ReplicationBatch | ReplicationAck | ForwardedTr
 /**
  * Coordinates replication for a single database node.
  *
- * Its state and dependencies are readable properties so that the collaborating
- * modules in `./engine/` share one mutable engine instance.
+ * The engine exposes its state and dependencies as properties, so that the
+ * helper modules that implement it can share one mutable instance.
  *
  * @public
  */
@@ -308,7 +323,7 @@ declare class ReplicationEngine extends EventEmitter {
     /** @internal */
     readonly config: ReplicationConfig;
     /**
-     * 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.
      */
     readonly nodeId: string;
     /** @internal */
@@ -366,6 +381,16 @@ declare class ReplicationEngine extends EventEmitter {
     /** @internal */
     coordinatorWatchDisposer: CoordinatorWatchDisposer | null;
     /** @internal */
+    nodeSessionWatchDisposer: CoordinatorWatchDisposer | null;
+    /** @internal */
+    controllerLeaseWatchDisposer: CoordinatorWatchDisposer | null;
+    /** @internal */
+    observedControllerLease: CoordinatorLease | null;
+    /** @internal */
+    controllerBidding: boolean;
+    /** @internal */
+    liveNodeIds: string[] | null;
+    /** @internal */
     coordinatorLeaseTimer: ReturnType<typeof setInterval> | null;
     /** @internal */
     controllerTimer: ReturnType<typeof setInterval> | null;
@@ -403,73 +428,78 @@ declare class ReplicationEngine extends EventEmitter {
     readonly senderLoop: SenderLoop;
     constructor(database: Database, writerConn: SQLiteConnection, config: ReplicationConfig);
     /**
-     * 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(): Promise<void>;
     /**
-     * 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.
      */
     stop(): Promise<void>;
     /**
-     * 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(): ReplicationStatus;
     /**
-     * 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(): bigint;
     /**
-     * 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: string): bigint;
     /**
-     * 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<T>(sql: string, params?: Params, options?: QueryOptions): Promise<T[]>;
     /**
-     * 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: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
     /**
-     * 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: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
     /**
-     * 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<T>(fn: (tx: Transaction) => Promise<T>, options?: QueryOptions): Promise<T>;
     /**
-     * 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: Array<{
         sql: string;
@@ -486,80 +516,82 @@ declare class ReplicationEngine extends EventEmitter {
     /** @internal */
     getCurrentPrimaryPeerId(): string | null;
     /**
-     * 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
      */
     decorate<T extends CoordinatorStampedMessage>(message: T): T;
 }
 
-/** Base error for all replication-related failures.
+/** Reports a replication failure, and more specific replication errors such as {@link BatchValidationError} extend it.
  * @public
  */
 declare class ReplicationError extends SirannonError {
-    /** Anything the failing operation attached, such as the peer or the batch involved. */
+    /** Extra context from the code that throws the error, such as the peer or the batch involved. */
     readonly details?: Record<string, unknown> | undefined;
     constructor(message: string, code?: string, 
-    /** Anything the failing operation attached, such as the peer or the batch involved. */
+    /** Extra context from the code that throws the error, such as the peer or the batch involved. */
     details?: Record<string, unknown> | undefined);
 }
-/** Thrown when an incoming replication batch fails integrity checks (checksum, schema, clock drift).
- * @public
- */
-declare class BatchValidationError extends ReplicationError {
-    constructor(message: string);
-}
-
-/** Thrown when a write conflict cannot be resolved automatically.
+/** Sirannon throws this error when a conflict resolver fails on a replicated change, and it names the table and row; `cause` holds the resolver's own error.
  * @public
  */
 declare class ConflictError extends ReplicationError {
     /**
-     * Table the conflicting row belongs to.
+     * Names the table that contains the conflicting row.
      */
     readonly table: string;
     /**
-     * Primary key of the conflicting row, encoded as a string.
+     * Holds the primary key of the conflicting row, encoded as a string.
      */
     readonly rowId: string;
     constructor(message: string, 
     /**
-     * Table the conflicting row belongs to.
+     * Names the table that contains the conflicting row.
      */
     table: string, 
     /**
-     * Primary key of the conflicting row, encoded as a string.
+     * Holds the primary key of the conflicting row, encoded as a string.
      */
-    rowId: string);
+    rowId: string, cause?: unknown);
 }
-/** Thrown when inter-node communication fails.
+/** Sirannon throws this error when an incoming replication batch fails a validation check, such as a checksum mismatch, an invalid table name, an unsafe DDL statement, or too much clock drift.
+ * @public
+ */
+declare class BatchValidationError extends ReplicationError {
+    constructor(message: string);
+}
+
+/** Sirannon throws this error when a transport call fails, such as a send to a disconnected peer or a send of a malformed message.
  * @public
  */
 declare class TransportError extends ReplicationError {
     constructor(message: string);
 }
-/** Thrown when a write-concern quorum is not met within the configured timeout.
+/** Sirannon throws this error when too few peers acknowledge a write before the write-concern timeout expires, or when too few peers are connected to reach the required count.
  * @public
  */
 declare class WriteConcernError extends ReplicationError {
     constructor(message: string);
 }
 /**
- * Thrown when a node cannot prove a read is as current as the caller required.
+ * Sirannon throws this error when a node cannot serve a read at the requested read concern, such as a `majority` read
+ * on a draining or repairing node, or a read at an unsupported level.
  *
  * @public
  */
 declare class ReadConcernError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
-/** Thrown when a write or routing operation violates the configured topology rules.
+/** Sirannon throws this error when a node that cannot accept writes receives a write that it cannot forward to a primary.
  * @public
  */
 declare class TopologyError extends ReplicationError {
     constructor(message: string);
 }
 /**
- * Thrown when a node cannot reach its cluster coordinator.
+ * Sirannon throws this error when a coordinator call fails, such as when the coordinator is unreachable, holds no state
+ * for the group, or refuses an update after concurrent writes.
  *
  * @public
  */
@@ -567,7 +599,8 @@ declare class CoordinatorError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when a node cannot prove it holds write authority for the current term.
+ * Sirannon throws this error when a node cannot prove that it holds write authority for the current term, such as
+ * while the node is repairing or faulted.
  *
  * @public
  */
@@ -575,7 +608,8 @@ declare class AuthorityError extends ReplicationError {
     constructor(message: string, code?: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when a node believing itself primary finds the group has moved to a later term.
+ * Sirannon throws this error when a node other than the group's current primary receives a write or another request
+ * that only the primary serves, or when a replication message has an old term or the wrong group.
  *
  * @public
  */
@@ -583,7 +617,8 @@ declare class StalePrimaryError extends AuthorityError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when failover cannot complete safely.
+ * Reports a failover that cannot complete safely, and {@link NoSafePrimaryError} and
+ * {@link UnsafeRecoveryRequiredError} extend it.
  *
  * @public
  */
@@ -591,7 +626,9 @@ declare class FailoverError extends ReplicationError {
     constructor(message: string, code?: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when no replica is in sync enough to take over as primary, so writes stay unavailable rather than risking loss.
+ * Sirannon throws this error when no in-sync replica is eligible for promotion, or when the group has fewer than three
+ * voting nodes. In that case the coordinator promotes no node, since promoting a replica outside the in-sync set could
+ * lose acknowledged writes.
  *
  * @public
  */
@@ -599,7 +636,7 @@ declare class NoSafePrimaryError extends FailoverError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when a node cannot meet a read concern because the group does not count it as in sync.
+ * Sirannon throws this error for a `majority` read on a node outside the group's in-sync set.
  *
  * @public
  */
@@ -607,7 +644,7 @@ declare class NodeNotInSyncError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when a node is being taken out of service and refuses new work.
+ * Sirannon throws this error when a draining node receives a write.
  *
  * @public
  */
@@ -615,7 +652,8 @@ declare class NodeDrainingError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when a peer speaks a replication protocol version this node cannot work with.
+ * Sirannon throws this error when this node's package, specification, or protocol major version differs from a version
+ * that the replication group requires.
  *
  * @public
  */
@@ -623,52 +661,53 @@ declare class ProtocolVersionMismatchError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 /**
- * Thrown when recovery would lose acknowledged writes, so an operator must rebuild or restore the node first.
+ * Signals that recovery would lose acknowledged writes, so an operator has to rebuild or restore the node first.
  *
  * @public
  */
 declare class UnsafeRecoveryRequiredError extends FailoverError {
     constructor(message: string, details?: Record<string, unknown>);
 }
-/** Thrown for initial sync failures.
+/** Sirannon throws this error when a first sync fails, or when a node that is still syncing receives a read or a write.
  * @public
  */
 declare class SyncError extends ReplicationError {
     /**
-     * Identifier of the sync that failed.
+     * Identifies the sync request that failed, when the error concerns one.
      */
     readonly requestId?: string | undefined;
     constructor(message: string, 
     /**
-     * Identifier of the sync that failed.
+     * Identifies the sync request that failed, when the error concerns one.
      */
     requestId?: string | undefined);
 }
 
-/** Generate a cryptographically random 32-hex-character node identifier.
+/** Returns a new node ID of 32 lowercase hex characters, drawn from a cryptographically secure random source.
  * @public
  */
 declare function generateNodeId(): string;
-/** Throw a ReplicationError if the given string is not a valid 32-hex-character node ID.
+/** Returns when `id` is exactly 32 lowercase hex characters, and throws a {@link ReplicationError} for any other string.
  * @public
  */
 declare function validateNodeId(id: string): void;
 
 /**
- * Single-writer topology with one primary and one or more read-only replicas.
+ * Sets the replication rules for a group with one writable primary and one or more read-only replicas.
  *
- * Only the primary node accepts writes; replicas reject writes with a
- * TopologyError (or forward them when writeForwarding is enabled on the
- * engine). The primary replicates outbound batches only to peers whose role
- * is 'replica', and replicas only accept inbound batches from a peer whose
- * role is 'primary'. Conflict resolution is not required because a single
- * writer eliminates concurrent write conflicts by design.
+ * Only the primary accepts writes. A replica rejects a write with a
+ * `TopologyError`, or forwards it to the primary when you turn on
+ * `writeForwarding` in the engine's config. The primary sends batches only to
+ * peers whose role is 'replica', and a replica applies batches only from a peer
+ * whose role is 'primary'. Since only one node writes, no two nodes can change
+ * the same row at once, so {@link PrimaryReplicaTopology.requiresConflictResolution}
+ * returns false.
  *
  * @public
  */
 declare class PrimaryReplicaTopology implements Topology {
     /**
-     * Whether this node accepts writes or serves reads.
+     * Records whether this node is the primary, which accepts writes, or a replica, which serves reads.
      */
     readonly role: TopologyRole;
     constructor(role: 'primary' | 'replica');
@@ -687,7 +726,7 @@ declare class PrimaryReplicaTopology implements Topology {
      */
     shouldReplicateTo(_peerId: string, peerRole: TopologyRole): boolean;
     /**
-     * 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.
@@ -695,11 +734,12 @@ declare class PrimaryReplicaTopology implements Topology {
      */
     shouldAcceptFrom(_peerId: string, peerRole: TopologyRole): boolean;
     /**
-     * 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.
      */
     requiresConflictResolution(): boolean;
 }
 
-export { ApplyResult, AuthorityError, BatchValidationError, ClusterCoordinator, type ClusterStatusOptions, ConflictError, ConflictResolver, type CoordinatorBackupGroupOptions, CoordinatorError, CoordinatorWatchDisposer, FailoverError, ForwardedTransactionResult, HLC, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, PeerState, PeerTracker, PrimaryReplicaTopology, ProtocolVersionMismatchError, ReadConcernError, ReplicationAck, ReplicationBatch, ReplicationConfig, ReplicationEngine, ReplicationError, ReplicationErrorEvent, ReplicationGroupState, ReplicationLog, ReplicationStatus, StalePrimaryError, SyncAck, SyncBatch, SyncComplete, SyncError, SyncPhase, SyncRequest, SyncState, SyncTableManifest, Topology, TopologyError, TopologyRole, TransportError, UnsafeRecoveryRequiredError, WriteConcernError, coordinatorBackupGroup, generateNodeId, toClusterReadEndpoints, toClusterStatusInfo, toReplicationStatusInfo, validateNodeId };
+export { ApplyResult, AuthorityError, BatchValidationError, ClusterCoordinator, type ClusterStatusOptions, ConflictError, ConflictResolver, type CoordinatorBackupGroupOptions, CoordinatorError, CoordinatorLease, CoordinatorWatchDisposer, FailoverError, ForwardedTransactionResult, HLC, NoSafePrimaryError, NodeDrainingError, NodeNotInSyncError, PeerState, PeerTracker, PrimaryReplicaTopology, ProtocolVersionMismatchError, ReadConcernError, ReplicationAck, ReplicationBatch, ReplicationConfig, ReplicationEngine, ReplicationError, ReplicationErrorEvent, ReplicationGroupState, ReplicationLog, ReplicationStatus, StalePrimaryError, SyncAck, SyncBatch, SyncComplete, SyncError, SyncPhase, SyncRequest, SyncState, SyncTableManifest, Topology, TopologyError, TopologyRole, TransportError, UnsafeRecoveryRequiredError, WriteConcernError, coordinatorBackupGroup, generateNodeId, toClusterReadEndpoints, toClusterStatusInfo, toReplicationStatusInfo, validateNodeId };