Module replica 

Replica-side client — connect to a primary’s replication listener, perform the handshake, then yield decoded mutation frames in order.

The client is synchronous + blocking by design: it slots into a dedicated thread on the replica node alongside (but separate from) the regular kevy reactor. An async surface is a Phase 4 deliverable (kevy-client-async, the only crate carved out of the 0-dep rule).

Hot loop usage:

use kevy_replicate::replica::ReplicaClient;

let mut client = ReplicaClient::connect("127.0.0.1:16004", "replica-a", 0)
    .expect("connect ok");
while let Some(result) = client.next() {
    let frame = result.expect("decode ok");
    // apply frame.argv at frame.offset — caller's responsibility (T1.19)
    drop(frame);
}

Errors map to actionable next steps for the caller:

• ReplicaError::HandshakeRejected / ReplicaError::AckMalformed — primary refused or replied with garbage; drop the link, log, maybe back off and retry.
• ReplicaError::Truncated — peer EOF mid-frame; treat as a disconnect, reconnect later.
• [ReplicaError::OffsetGap { expected, got }] — frames arrived out of order or with a skip; per plan T1.20 the caller should trigger a full snapshot resync. v1.18.0 surfaces the gap; the snapshot ship machinery itself lands at T1.22.
• ReplicaError::Frame — wire-level decode error; same action as Truncated (drop + reconnect).

Structs

DecodedFrame

A decoded mutation frame the replica should apply to its local store. Ownership of the Argv passes to the caller.

ReplicaClient

One blocking TCP connection to a primary’s per-shard replication listener. After Self::connect completes the handshake, the client behaves as an Iterator<Item = Result<DecodedFrame, ReplicaError>> yielding frames in offset order until the peer disconnects or a hard error surfaces.

Enums

ReplicaError

Errors a replica client can surface to its driver loop.

ReplicaEvent

Event yielded by ReplicaClient::next_event. A driver loop pattern-matches and applies each: