@delali/sirannon-db 0.2.0 → 0.2.1

package/dist/replication/index.d.ts

@@ -1,18 +1,19 @@
-export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-DPAm2AKG.js';
-import { H as HLCTimestamp, R as ReplicationBatch, C as ConflictResolver, A as ApplyResult, S as SyncTableManifest } from '../types-C_D8IhpO.js';
-export { a as ConflictContext, b as ConflictResolution, c as ReplicationChange } from '../types-C_D8IhpO.js';
-import { R as ReplicationGroupState, f as CoordinatorWatchDisposer } from '../types-BsVabqSI.js';
-export { A as AcquireControllerLeaseInput, b as AcquireControllerLeaseResult, i as AdmitNodeToInSyncSetInput, C as ClusterCoordinator, g as CompareAndAdvancePrimaryTermInput, h as CompareAndAdvancePrimaryTermResult, a as CoordinatorCompatibilityMetadata, k as CoordinatorLease, d as CoordinatorNodeSession, l as CoordinatorPrimary, P as PromoteEligibleReplicaInput, c as RegisterNodeSessionInput, e as ReplicationGroupWatcher, S as SetReplicationGroupStateInput, U as UpdateInSyncSetInput, j as UpdateNodeMaintenanceInput } from '../types-BsVabqSI.js';
+export { F as FieldMergeResolver, L as LWWResolver, P as PrimaryWinsResolver } from '../primary-wins-B0np8JS3.js';
+import { H as HLCTimestamp, R as ReplicationBatch, C as ConflictResolver, A as ApplyResult, S as SyncTableManifest } from '../types-CjhxcjhA.js';
+export { a as ConflictContext, b as ConflictResolution, c as ReplicationChange } from '../types-CjhxcjhA.js';
+import { c as ReplicationGroupState, e as CoordinatorWatchDisposer } from '../types-CMBcFPhb.js';
+export { A as AcquireControllerLeaseInput, a as AcquireControllerLeaseResult, h as AdmitNodeToInSyncSetInput, C as ClusterCoordinator, 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-CMBcFPhb.js';
 import { EventEmitter } from 'node:events';
-import { C as ChangeTracker } from '../change-tracker-DKRVUC3l.js';
-import { D as Database } from '../database-BY0L5Q2n.js';
-import { e as SQLiteConnection, P as Params, Q as QueryOptions, T as Transaction, E as ExecuteResult } from '../types-zhnRXrsb.js';
-import { g as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, h as ReplicationConfig, i as SyncState, j as ReplicationStatus, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-B7gmEsZW.js';
-export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-B7gmEsZW.js';
-import { S as SirannonError } from '../errors-Bw5MdNCu.js';
-import '../server-options-1JHu8pid.js';
-import '../operation-registry-9DcvxcE5.js';
-import '../types-CL6piSnD.js';
+import { C as ChangeTracker } from '../change-tracker-DDmXB754.js';
+import { D as Database } from '../database-B5Qv1-cU.js';
+import { e as SQLiteConnection, T as Transaction } from '../types-rVZKnKN-.js';
+import { P as Params, Q as QueryOptions, E as ExecuteResult } from '../query-types-DL3LtPvY.js';
+import { g as SyncPhase, I as InFlightBatch, P as PeerState, a as ForwardedTransactionResult, b as SyncBatch, c as SyncComplete, d as SyncAck, S as SyncRequest, h as ReplicationConfig, i as SyncState, j as ReplicationStatus, k as ReplicationErrorEvent, R as ReplicationAck, l as Topology, f as TopologyRole } from '../types-DyrCiWuc.js';
+export { F as ForwardedTransaction, N as NodeInfo, e as ReplicationTransport, T as TransportConfig } from '../types-DyrCiWuc.js';
+import { S as SirannonError } from '../errors-Dei4GdBb.js';
+import '../server-options-Dab_Jvd_.js';
+import '../operation-registry-hlbhqu7q.js';
+import '../types-BCejqzNA.js';
 
 /**
  * Hybrid Logical Clock (HLC) for causal ordering of events across nodes.
@@ -28,20 +29,38 @@ import '../types-CL6piSnD.js';
  * increasing timestamp. Call `receive(remote)` when processing a remote
  * change to merge the remote clock into the local state, ensuring the local
  * clock is never behind any observed timestamp.
+ *
+ * @public
  */
 declare class HLC {
     private wallMs;
     private logical;
     private readonly nodeId;
     constructor(nodeId: string);
-    /** Generate a new HLC timestamp, advancing the clock. */
+    /**
+     * Generate a new HLC timestamp, advancing the clock.
+     *
+     * @internal
+     */
     now(): string;
-    /** Merge a remote HLC timestamp into the local clock and return the updated value. */
+    /**
+     * Merge a remote HLC timestamp into the local clock and return the updated value.
+     *
+     * @internal
+     */
     receive(remote: string): string;
     /** Lexicographic comparison of two encoded HLC strings. Returns -1, 0, or 1. */
     static compare(a: string, b: string): number;
     /** Parse an encoded HLC string into its wall-clock, logical, and nodeId components. */
     static decode(hlc: string): HLCTimestamp;
+    /**
+     * Builds the string form of a clock reading, which sorts in the same order as the reading itself.
+     *
+     * @param wallMs - Wall-clock milliseconds since the Unix epoch.
+     * @param logical - Counter that orders events sharing one millisecond.
+     * @param nodeId - Identifier of the node taking the reading.
+     * @returns The encoded stamp.
+     */
     static encode(wallMs: number, logical: number, nodeId: string): string;
 }
 
@@ -53,6 +72,8 @@ declare class HLC {
  * manifests), SchemaOps (replication-table bootstrap, schema dump, wipe),
  * StateOps (sequence and sync metadata), and PkResolver (cached primary-key
  * lookups).
+ *
+ * @internal
  */
 declare class ReplicationLog {
     private readonly changesTable;
@@ -77,7 +98,6 @@ declare class ReplicationLog {
     getMinAckedSeq(): Promise<bigint | null>;
     registerActiveSyncSeq(seq: bigint): void;
     unregisterActiveSyncSeq(seq: bigint): void;
-    dumpTable(table: string, batchSize: number): AsyncGenerator<ReplicationBatch>;
     dumpTableOnConnection(conn: SQLiteConnection, table: string, batchSize: number): AsyncGenerator<{
         rows: Record<string, unknown>[];
         checksum: string;
@@ -113,6 +133,8 @@ declare class ReplicationLog {
  *   with a sequence number and timeout. These methods resolve once enough
  *   peers have acknowledged that sequence, or reject with a
  *   WriteConcernError on timeout.
+ *
+ * @internal
  */
 declare class PeerTracker {
     private readonly peers;
@@ -135,6 +157,11 @@ declare class PeerTracker {
     private checkWaiters;
 }
 
+/**
+ * Runs a statement on the local node and records the resulting changes in the replication log.
+ *
+ * @internal
+ */
 declare class LocalExecutor {
     private readonly engine;
     /**
@@ -164,6 +191,11 @@ declare class LocalExecutor {
     private runTransaction;
 }
 
+/**
+ * Batches locally recorded changes and pushes them to the peers the topology accepts.
+ *
+ * @internal
+ */
 declare class SenderLoop {
     private readonly engine;
     private senderTimer;
@@ -175,6 +207,11 @@ declare class SenderLoop {
     private shouldReplicateTo;
 }
 
+/**
+ * Drives a joining node through first sync and the catch-up that follows it.
+ *
+ * @internal
+ */
 declare class SyncJoiner {
     private readonly engine;
     private catchUpCheckTimer;
@@ -184,7 +221,7 @@ declare class SyncJoiner {
     handleSyncBatchReceived(batch: SyncBatch, fromPeerId: string): Promise<void>;
     handleSyncCompleteReceived(complete: SyncComplete, fromPeerId: string): Promise<void>;
     startCatchUpCheck(): void;
-    stopCatchUpCheck(): void;
+    private stopCatchUpCheck;
     stopTimers(): void;
     isSourceRejection(ack: SyncAck, fromPeerId: string): boolean;
     handleSourceRejection(ack: SyncAck, fromPeerId: string): void;
@@ -193,39 +230,20 @@ declare class SyncJoiner {
     private finishCatchUpAsReady;
 }
 
-interface TableStreamDigest {
-    rowCount: number;
-    digest: string;
-}
-
-interface ActiveSyncSession {
-    requestId: string;
-    joinerNodeId: string;
-    readConn: SQLiteConnection;
-    snapshotSeq: bigint;
-    tables: string[];
-    totalTables: number;
-    completedTables: Set<string>;
-    startedAt: number;
-    timeoutTimer: ReturnType<typeof setTimeout>;
-    aborted: boolean;
-    streamVerification: boolean;
-    tableDigests: Map<string, TableStreamDigest>;
-}
-interface SyncAckWaiter {
-    resolve: (ack: SyncAck) => void;
-    timer: ReturnType<typeof setTimeout>;
-}
-
+/**
+ * Serves first-sync requests from joining nodes by streaming schema, table pages, and a manifest.
+ *
+ * @internal
+ */
 declare class SyncServer {
     private readonly engine;
-    readonly activeSyncs: Map<string, ActiveSyncSession>;
-    readonly syncAckWaiters: Map<string, SyncAckWaiter>;
+    private readonly activeSyncs;
+    private readonly syncAckWaiters;
     constructor(engine: ReplicationEngine);
     private rejectSyncRequest;
     handleSyncRequest(request: SyncRequest, fromPeerId: string): Promise<void>;
     handleSyncAckReceived(ack: SyncAck): void;
-    abortSyncSession(requestId: string): void;
+    private abortSyncSession;
     abortAll(): void;
     abortSessionsForPeer(peerId: string): void;
     private waitForSyncAck;
@@ -234,185 +252,372 @@ declare class SyncServer {
     private serveSyncSession;
 }
 
+interface TableStreamDigest {
+    rowCount: number;
+    digest: string;
+}
+
+type CoordinatorStampedMessage = ReplicationBatch | ReplicationAck | ForwardedTransactionResult | SyncRequest | SyncBatch | SyncComplete | SyncAck;
 /**
  * Coordinates replication for a single database node.
  *
- * State and dependencies are exposed as readable properties so that the
- * collaborating modules in `./engine/` (LocalExecutor, SyncServer, SyncJoiner,
- * SenderLoop, transport wiring, coordinator lifecycle/authority/membership)
- * can operate against a shared, mutable engine instance without duplicating
- * constructor wiring.
+ * Its state and dependencies are readable properties so that the collaborating
+ * modules in `./engine/` share one mutable engine instance.
+ *
+ * @public
  */
 declare class ReplicationEngine extends EventEmitter {
+    /** @internal */
     readonly database: Database;
+    /** @internal */
     readonly writerConn: SQLiteConnection;
+    /** @internal */
     readonly config: ReplicationConfig;
+    /**
+     * Identifier of this node, which every change it authors carries.
+     */
     readonly nodeId: string;
+    /** @internal */
     readonly hlc: HLC;
+    /** @internal */
     readonly log: ReplicationLog;
+    /** @internal */
     readonly peerTracker: PeerTracker;
+    /** @internal */
     readonly defaultResolver: ConflictResolver;
+    /** @internal */
     readonly tracker: ChangeTracker | undefined;
+    /** @internal */
     readonly snapshotConnectionFactory: (() => Promise<SQLiteConnection>) | undefined;
+    /** @internal */
     readonly batchSize: number;
+    /** @internal */
     readonly batchIntervalMs: number;
+    /** @internal */
     readonly maxClockDriftMs: number;
+    /** @internal */
     readonly maxPendingBatches: number;
+    /** @internal */
     readonly maxBatchChanges: number;
+    /** @internal */
     readonly ackTimeoutMs: number;
+    /** @internal */
     readonly initialSync: boolean;
+    /** @internal */
     readonly syncBatchSize: number;
+    /** @internal */
     readonly maxConcurrentSyncs: number;
+    /** @internal */
     readonly maxSyncDurationMs: number;
+    /** @internal */
     readonly maxSyncLagBeforeReady: number;
+    /** @internal */
     readonly syncAckTimeoutMs: number;
+    /** @internal */
     readonly catchUpDeadlineMs: number;
+    /** @internal */
     readonly resumeFromSeq: bigint | undefined;
+    /** @internal */
     running: boolean;
+    /** @internal */
     coordinatorState: ReplicationGroupState | null;
+    /** @internal */
     coordinatorAuthority: boolean;
+    /** @internal */
     controllerState: 'disabled' | 'standby' | 'active' | 'lost';
+    /** @internal */
     nodeSessionLeaseId: string | null;
+    /** @internal */
     controllerLeaseId: string | null;
+    /** @internal */
     coordinatorWatchDisposer: CoordinatorWatchDisposer | null;
+    /** @internal */
     coordinatorLeaseTimer: ReturnType<typeof setInterval> | null;
+    /** @internal */
     controllerTimer: ReturnType<typeof setInterval> | null;
+    /** @internal */
     coordinatorRejoinSyncStarting: boolean;
+    /** @internal */
     coordinatorSessionRestoring: boolean;
+    /** @internal */
     coordinatorLastContactMs: number;
+    /** @internal */
     inSyncReconcileTimer: ReturnType<typeof setInterval> | null;
+    /** @internal */
     inSyncReconciling: boolean;
+    /** @internal */
     lastSentSeq: bigint;
+    /** @internal */
     lastLocalSeq: bigint;
+    /** @internal */
     highestSourceSeqSeen: bigint;
+    /** @internal */
     readonly appliedSeqByPeer: Map<string, bigint>;
+    /** @internal */
     readonly expectedBatchIndex: Map<string, number>;
+    /** @internal */
     readonly syncTableDigests: Map<string, TableStreamDigest>;
+    /** @internal */
     syncState: SyncState;
+    /** @internal */
     readonly localExecutor: LocalExecutor;
+    /** @internal */
     readonly syncServer: SyncServer;
+    /** @internal */
     readonly syncJoiner: SyncJoiner;
+    /** @internal */
     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.
+     */
     start(): Promise<void>;
+    /**
+     * Stops replicating, abandons any sync in flight, and disconnects the transport.
+     */
     stop(): Promise<void>;
+    /**
+     * Reports where this node stands.
+     *
+     * @returns The node's role, its peers, its progress, its health, and its group state.
+     */
     status(): ReplicationStatus;
+    /**
+     * Returns the highest change-log position this node has recorded locally.
+     *
+     * @returns That position, which a caller waits for a replica to reach.
+     */
     getCurrentSeq(): bigint;
+    /**
+     * 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: string): bigint;
+    /**
+     * 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<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.
+     *
+     * @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: string, params?: Params, options?: QueryOptions): Promise<ExecuteResult>;
+    /**
+     * 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: string, paramsBatch: Params[], options?: QueryOptions): Promise<ExecuteResult[]>;
+    /**
+     * 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<T>(fn: (tx: Transaction) => Promise<T>, options?: QueryOptions): Promise<T>;
+    /**
+     * 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: Array<{
         sql: string;
         params?: Params;
     }>, options?: QueryOptions): Promise<ForwardedTransactionResult>;
-    startSenderLoop(): void;
+    /** @internal */
     emitError(event: ReplicationErrorEvent): void;
-    getResolver(table?: string): ConflictResolver;
-    checkClockDrift(remoteHlc: string): number;
-    refreshTriggersAfterDdl(): Promise<void>;
-    waitForWriteConcern(seq: bigint, wc: {
-        level: string;
-        timeoutMs?: number;
-    }): Promise<void>;
-    loadAppliedSeqs(): Promise<void>;
+    /** @internal */
     isCoordinatorMode(): boolean;
-    startCoordinatorMode(): Promise<void>;
-    prepareCoordinatorRejoinIfNeeded(): Promise<void>;
-    hasCoordinatorWriteAuthority(): boolean;
-    requiresCoordinatorRejoinSync(state?: ReplicationGroupState | null): boolean;
-    markCoordinatorSyncReady(): Promise<void>;
-    handleCoordinatorAckProgress(nodeId: string, ackedSeq: bigint): Promise<void>;
+    /** @internal */
     verifyPrimaryAuthority(): Promise<ReplicationGroupState>;
-    assertInboundCoordinatorMessage(message: {
-        groupId?: string;
-        primaryTerm?: bigint;
-    }, fromPeerId: string, direction: 'batch' | 'ack' | 'forward' | 'sync-request' | 'sync-data'): Promise<void>;
-    decorateBatch(batch: ReplicationBatch): ReplicationBatch;
-    decorateAck(ack: ReplicationAck): ReplicationAck;
-    decorateForwardResult(result: ForwardedTransactionResult): ForwardedTransactionResult;
-    decorateSyncRequest(request: SyncRequest): SyncRequest;
-    decorateSyncBatch(batch: SyncBatch): SyncBatch;
-    decorateSyncComplete(complete: SyncComplete): SyncComplete;
-    decorateSyncAck(ack: SyncAck): SyncAck;
-    resolveWriteConcern(wc: {
-        level: string;
-        timeoutMs?: number;
-    } | undefined): {
-        level: string;
-        timeoutMs?: number;
-    } | undefined;
+    /** @internal */
+    markCoordinatorSyncReady(): Promise<void>;
+    /** @internal */
     getCurrentPrimaryPeerId(): string | null;
+    /**
+     * Stamps an outgoing replication message with this node's group and primary term.
+     *
+     * @internal
+     */
+    decorate<T extends CoordinatorStampedMessage>(message: T): T;
 }
 
-/** Base error for all replication-related failures. */
+/** Base error for all replication-related failures.
+ * @public
+ */
 declare class ReplicationError extends SirannonError {
+    /** Anything the failing operation attached, such as the peer or the batch involved. */
     readonly details?: Record<string, unknown> | undefined;
-    constructor(message: string, code?: string, details?: Record<string, unknown> | undefined);
+    constructor(message: string, code?: string, 
+    /** Anything the failing operation attached, 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). */
+/** 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. */
+/** Thrown when a write conflict cannot be resolved automatically.
+ * @public
+ */
 declare class ConflictError extends ReplicationError {
+    /**
+     * Table the conflicting row belongs to.
+     */
     readonly table: string;
+    /**
+     * Primary key of the conflicting row, encoded as a string.
+     */
     readonly rowId: string;
-    constructor(message: string, table: string, rowId: string);
+    constructor(message: string, 
+    /**
+     * Table the conflicting row belongs to.
+     */
+    table: string, 
+    /**
+     * Primary key of the conflicting row, encoded as a string.
+     */
+    rowId: string);
 }
-/** Thrown when inter-node communication fails. */
+/** Thrown when inter-node communication fails.
+ * @public
+ */
 declare class TransportError extends ReplicationError {
     constructor(message: string);
 }
-/** Thrown when a write-concern quorum is not met within the configured timeout. */
+/** Thrown when a write-concern quorum is not met within the configured timeout.
+ * @public
+ */
 declare class WriteConcernError extends ReplicationError {
     constructor(message: string);
 }
+/**
+ * @public
+ *
+ * Thrown when a node cannot prove a read is as current as the caller required.
+ */
 declare class ReadConcernError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
-/** Thrown when a write or routing operation violates the configured topology rules. */
+/** Thrown when a write or routing operation violates the configured topology rules.
+ * @public
+ */
 declare class TopologyError extends ReplicationError {
     constructor(message: string);
 }
+/**
+ * @public
+ *
+ * Thrown when a node cannot reach its cluster coordinator.
+ */
 declare class CoordinatorError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when a node cannot prove it holds write authority for the current term.
+ */
 declare class AuthorityError extends ReplicationError {
     constructor(message: string, code?: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when a node believing itself primary finds the group has moved to a later term.
+ */
 declare class StalePrimaryError extends AuthorityError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when failover cannot complete safely.
+ */
 declare class FailoverError extends ReplicationError {
     constructor(message: string, code?: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when no replica is in sync enough to take over as primary, so writes stay unavailable rather than risking loss.
+ */
 declare class NoSafePrimaryError extends FailoverError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when a node cannot meet a read concern because the group does not count it as in sync.
+ */
 declare class NodeNotInSyncError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when a node is being taken out of service and refuses new work.
+ */
 declare class NodeDrainingError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when a peer speaks a replication protocol version this node cannot work with.
+ */
 declare class ProtocolVersionMismatchError extends ReplicationError {
     constructor(message: string, details?: Record<string, unknown>);
 }
+/**
+ * @public
+ *
+ * Thrown when recovery would lose acknowledged writes, so an operator must rebuild or restore the node first.
+ */
 declare class UnsafeRecoveryRequiredError extends FailoverError {
     constructor(message: string, details?: Record<string, unknown>);
 }
-/** Thrown for initial sync failures. */
+/** Thrown for initial sync failures.
+ * @public
+ */
 declare class SyncError extends ReplicationError {
+    /**
+     * Identifier of the sync that failed.
+     */
     readonly requestId?: string | undefined;
-    constructor(message: string, requestId?: string | undefined);
+    constructor(message: string, 
+    /**
+     * Identifier of the sync that failed.
+     */
+    requestId?: string | undefined);
 }
 
-/** Generate a cryptographically random 32-hex-character node identifier. */
+/** Generate a cryptographically random 32-hex-character node identifier.
+ * @public
+ */
 declare function generateNodeId(): string;
-/** Throw a ReplicationError if the given string is not a valid 32-hex-character node ID. */
+/** Throw a ReplicationError if the given string is not a valid 32-hex-character node ID.
+ * @public
+ */
 declare function validateNodeId(id: string): void;
 
 /**
@@ -424,13 +629,42 @@ declare function validateNodeId(id: string): void;
  * 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.
+ *
+ * @public
  */
 declare class PrimaryReplicaTopology implements Topology {
+    /**
+     * Whether this node accepts writes or serves reads.
+     */
     readonly role: TopologyRole;
     constructor(role: 'primary' | 'replica');
+    /**
+     * Reports whether this node accepts writes, which only the primary does.
+     *
+     * @returns True on the primary.
+     */
     canWrite(): boolean;
+    /**
+     * 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: string, peerRole: TopologyRole): boolean;
+    /**
+     * 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: string, peerRole: TopologyRole): boolean;
+    /**
+     * Reports whether incoming changes need a resolver, which a single writer removes the need for.
+     *
+     * @returns False.
+     */
     requiresConflictResolution(): boolean;
 }