From 0fd56910986be91dd57f75fc438479762bf179d5 Mon Sep 17 00:00:00 2001 From: matthew-pilot Date: Sat, 30 May 2026 08:04:15 +0000 Subject: [PATCH] docs(replication): document AP consistency model for Push/PushDelta (PILOT-280) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The replication Manager uses fire-and-forget broadcast: Push() and PushDelta() commit writes locally first, then send snapshots/deltas to all standbys without waiting for acknowledgment. If the primary crashes before a standby receives the latest deltas, mutations are lost. This is intentional AP design — the rendezvous stays available under partition at the cost of potential data loss on failover. This commit documents the tradeoff explicitly in the package doc comment. Sync-replication mode (primary waits for ≥1 standby ack) is not yet implemented — see PILOT-280 for discussion. Closes PILOT-280 --- replication/replication.go | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/replication/replication.go b/replication/replication.go index 755b190..e82327d 100644 --- a/replication/replication.go +++ b/replication/replication.go @@ -5,6 +5,24 @@ // set of standby subscriber connections and broadcasts snapshots/deltas to // all of them. Directory-sync types and helpers used by the server-side // handler are also defined here. +// +// ## Consistency model +// +// Replication uses an AP (Available / Partition-Tolerant) model: +// Push() and PushDelta() commit writes locally first, then broadcast +// snapshots/deltas to all connected standbys on a best-effort basis. +// The primary does NOT wait for standby acknowledgment — mutations +// are considered committed once they land in the local WAL. +// +// If the primary crashes before a standby has received the latest deltas +// (e.g. within the 1 s replicaPushInterval), those mutations are lost. +// This is an intentional design choice for the AP side of the CAP +// theorem: the rendezvous remains available under partition at the cost +// of potential data loss on failover. +// +// Sync-replication mode (where the primary waits for at least one +// standby ack before returning to the caller) is not yet implemented. +// See PILOT-280 for discussion. package replication import (