atelier/domains/edge/sync.md

Sync — Derived Rules

Derives from domains/edge/first-principles.md. Applies P4 (Sync Conflicts are Bounded, Not Infinite) primarily, with P5 (idempotent merge operations), P2 (offline as the precondition), and P10 (sync is observable). Cross-links domains/data/migrations for schema migration under sync and domains/concurrency/patterns for the immutability-aid-merge principle.

What the Sync Problem Is (P4 Sync Conflicts are Bounded, Not Infinite)

• Sync is the discipline of reconciling divergent state across partitioned nodes. While partitioned, each node accepts writes independently; on reconnect, the divergent state must converge. The correctness contract is that the merge terminates and converges — oscillation and infinite sync loops are correctness failures, not eventual consistency (P4).
• Sync is the edge domain's deepest problem: it is the reconciliation layer above P2 Offline is a First-Class State. Without offline operation there is nothing to sync; with it, the reconnect reconciliation is the correctness mechanism. See domains/edge/offline-first.md for the offline write-queue that produces the divergent state to be reconciled.
• The boundary is per D-061: edge owns the partitioned-reconcile angle; concurrency owns the in-process analog (concurrency/P1 Immutability by Default — immutability aids merge); data owns the generic migration discipline (data/migrations). Sync is an edge concern because its defining trait is partitioned divergence, a concern that only arises at the network edge.

Conflict Resolution Strategies (P4, C1 Correctness, C5 Reversibility)

• A conflict is when two nodes have divergent state for the same logical entity and no total order determines which is correct. Resolution strategies fall into two families:
  • Conflict-free: the data type guarantees convergence by construction (CRDTs). The merge is deterministic; no conflict surfaces to the user or the application.
  • Conflict-tolerant: the data type can conflict; the resolution policy (last-write-win, three-way merge, application-specific) arbitrates. Conflicts may surface to the user or be silently resolved per a documented policy.
• The choice is a P4 decision: conflict-free types guarantee the bound (convergence) but constrain the data model; conflict-tolerant types are flexible but require the resolution policy to be correct and bounded (no oscillation). See the decision matrix below.

CRDTs — Conflict-Free Replicated Data Types (P4, C5, C6)

• A CRDT is a data type whose merge operation is associative, commutative, and idempotent. Given any set of divergent replicas, merging them in any order converges to the same state — the merge is deterministic and terminating (P4 bound). CRDTs derive from C5 Reversibility (divergent state reverses to convergence) and C6 Composability (CRDTs compose: a CRDT map of CRDT registers is itself a CRDT).
• State-based (CvRDT — convergent): each replica carries its full state; merge is a least-upper-bound on a semi-lattice. The payload is larger (full state per merge); the merge is simple (one function). Fits small state and unreliable networks.
• Operation-based (CmRDT — commutative): each replica carries operations; merge is applying the operations in causal order. The payload is smaller (ops, not state); the delivery must be reliable and causally ordered. Fits large state and reliable transport.
• The tradeoff: state-based is simpler but heavier; operation-based is lighter but requires causal delivery. Both guarantee convergence (P4); the choice is a C8 Economy decision (bandwidth vs delivery complexity).

// CRDT register: LWW-element-set (state-based, CvRDT). The merge
// is deterministic — the register with the later timestamp wins.
// Convergence is guaranteed (P4); the merge is idempotent (P5).

interface LWWRegister<T> {
  value: T;
  timestamp: number;   // monotonic clock; ties broken by node id
  nodeId: string;
}

function mergeLWWRegister<T>(
  local: LWWRegister<T>,
  remote: LWWRegister<T>,
): LWWRegister<T> {
  // The merge is associative, commutative, idempotent (P4, P5).
  // (local.timestamp, local.nodeId) > (remote.timestamp, remote.nodeId)
  // is a total order — no oscillation, no infinite loop.
  if (local.timestamp > remote.timestamp) return local;
  if (local.timestamp < remote.timestamp) return remote;
  // Tie: break by node id for a deterministic total order.
  return local.nodeId > remote.nodeId ? local : remote;
}

// The register is a CRDT: merge(merge(a, b), c) === merge(a, merge(b, c))
// for any replicas a, b, c. Convergence is guaranteed (P4).

// CRDT set: add-wins last-write-wins element set (state-based).
// Each element carries a timestamp; remove only wins if the
// remove-timestamp is later than the add-timestamp. This avoids
// the remove-wins-vs-add race (P4) without surfacing a conflict.

interface AWLWWSet<T> {
  adds: Map<T, number>;     // element -> add-timestamp
  removes: Map<T, number>;  // element -> remove-timestamp
}

function mergeAWLWWSet<T>(a: AWLWWSet<T>, b: AWLWWSet<T>): AWLWWSet<T> {
  const adds = new Map<T, number>(a.adds);
  const removes = new Map<T, number>(a.removes);
  for (const [el, ts] of b.adds) {
    adds.set(el, Math.max(adds.get(el) ?? 0, ts));      // add-wins union
  }
  for (const [el, ts] of b.removes) {
    removes.set(el, Math.max(removes.get(el) ?? 0, ts));
  }
  return { adds, removes };
}

function contains<T>(set: AWLWWSet<T>, el: T): boolean {
  const addTs = set.adds.get(el) ?? 0;
  const rmTs = set.removes.get(el) ?? 0;
  return addTs > rmTs;   // add wins on equal timestamp (P4 bounded)
}

Last-Write-Win (LWW) with Vector Clocks (P4, C1, C5)

• LWW is the simplest conflict-tolerant strategy: the write with the latest timestamp wins. It is cheap, but it silently discards concurrent writes — the "lost update" is the correctness cost. LWW is correct only when the timestamp is a total order (a monotonic clock, not wall time), and when lost concurrent writes are acceptable (e.g., caching, presence, ephemeral state).
• Vector clocks are the timestamp that knows about concurrency. A vector clock records the logical time of each node; two writes are concurrent iff neither vector dominates the other. LWW with vector clocks: a write that is causally later wins; a write that is concurrent conflicts and is resolved by a tiebreak (node id, wall time, or application policy).
• The tiebreak is the P4 bound: the conflict must be resolved deterministically (no oscillation) and the resolution must be documented. A tiebreak by wall time alone (no vector clock) is a P4 violation waiting to happen — wall time skews across nodes, and a clock skew can flip the tiebreak, oscillating the merge.

// LWW with vector clocks (conflict-tolerant, P4 bounded). The
// vector clock records causal order; concurrent writes conflict;
// the conflict is tiebroken deterministically (no oscillation).

type VectorClock = Record<string, number>;  // nodeId -> counter

function compareClock(a: VectorClock, b: VectorClock): "before" | "after" | "equal" | "concurrent" {
  let aBefore = false, bBefore = false;
  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
  for (const k of keys) {
    const av = a[k] ?? 0;
    const bv = b[k] ?? 0;
    if (av < bv) aBefore = true;
    if (av > bv) bBefore = true;
  }
  if (aBefore && bBefore) return "concurrent";
  if (aBefore) return "before";
  if (bBefore) return "after";
  return "equal";
}

interface LWWVectorState<T> {
  value: T;
  clock: VectorClock;
  writerId: string;  // tiebreak: deterministic, no oscillation (P4)
}

function mergeLWWVector<T>(
  local: LWWVectorState<T>,
  remote: LWWVectorState<T>,
): LWWVectorState<T> {
  const order = compareClock(local.clock, remote.clock);
  if (order === "before") return remote;       // remote causally later
  if (order === "after" || order === "equal") return local;
  // Concurrent: tiebreak by writer id (deterministic, P4 bounded).
  return local.writerId > remote.writerId ? local : remote;
}

• The merge is idempotent (P5): merging the same two replicas twice yields the same result. The tiebreak by writerId is a total order, so the merge cannot oscillate (P4 bound).
• A vector-clock merge that surfaces the concurrent conflict to the application (instead of tiebreaking) is also valid — the application resolves per its own policy. The P4 bound is that the resolution terminates; the policy determines whether the user sees the conflict or the system silences it.

Merge Semantics (P4, P5, cross-link concurrency/patterns)

• The merge function is the heart of sync. Its properties (P4):
  • Associative: merge(merge(a, b), c) === merge(a, merge(b, c)).
  • Commutative: merge(a, b) === merge(b, a).
  • Idempotent: merge(a, a) === a (P5 — retried merges are safe).
• Immutability aids merge: an immutable state representation (the CRDT payload, the LWW register with a clock) makes the merge a pure function of two inputs, with no in-place mutation race. See domains/concurrency/patterns (concurrency/P1 Immutability by Default) for the in-process immutability principle; sync is the cross-partition instance of it.
• A merge that mutates in place is a P5 violation waiting to happen: a retried merge mutates the same state twice, and the result is not idempotent. Always merge into a new state; never mutate the inputs.

Conflict-Free vs Conflict-Tolerant Data Types (P4, C3 Simplicity)

• Conflict-free (CRDTs): the data type guarantees convergence. The application never sees a conflict; the merge is deterministic. The cost: the data model is constrained (counters, sets, registers, maps of these). A conflict-free type for arbitrary JSON is hard; a conflict-free type for a counter is a PN-counter.
• Conflict-tolerant (LWW, three-way merge, application policy): the data type can conflict; the resolution policy arbitrates. The cost: the policy must be correct and bounded (no oscillation), and the conflict may surface to the user. The benefit: any data model can be made conflict-tolerant (just pick a tiebreak).
• The choice is the decision matrix below. It is a P4 decision (which bound), a C1 decision (which correctness cost is acceptable), and a C3 decision (which simplicity is affordable). See also domains/data/migrations for the schema-evolution angle — a schema change under sync must be compatible with both replicas, or the merge fails on the new shape.

Schema Migration Under Sync (P4, cross-link data/migrations)

• A schema migration under sync is harder than a single-node migration: both replicas must understand the new shape, or the merge fails. The migration must be forward-and-backward compatible across all replicas that may still hold the old shape — see domains/data/migrations for the generic compatibility discipline.
• A breaking schema change under sync requires a staged migration: deploy the new-shape-aware merge first (it accepts both shapes), then deploy the new shape, then deploy the old-shape-removing merge. A big-bang schema change under sync is a P4 violation: the replicas that have not yet upgraded will fail the merge, and the sync will not converge.
• The merge function's version awareness is the P4 bound: the merge must handle every shape version that may exist in the fleet, or reject (and surface) the merge rather than silently corrupting.

CRDT vs Last-Write-Win — Decision Matrix (D-069)

Strategy	When	Correctness Guarantee	Operational Cost	Failure Mode
CRDT (state-based, CvRDT)	The data model fits a CRDT (counter, set, register, map of these); convergence must be guaranteed without surfacing conflicts; the network is unreliable (full-state merge tolerates dropped ops)	Strong eventual convergence — merge(a, b) === merge(b, a) for any replicas (P4 bound by construction)	Medium — full state per merge (bandwidth); semi-lattice merge function per type; CRDT library or hand-rolled	A bug in the merge function = silent divergence (C1); large state = bandwidth cost on constrained links (P3)
CRDT (operation-based, CmRDT)	The data model fits a CRDT; bandwidth is constrained (ops are smaller than state); the transport is reliable and causally ordered	Strong eventual convergence — same guarantee, smaller payload	High — requires causal delivery (vector clock or broker with ordering); op transform must be idempotent (P5)	Causal-delivery violation = lost ops = divergence; op-transform bug = silent divergence
Last-Write-Win (LWW) with vector clocks	The data model is arbitrary (any JSON, any record); concurrent writes are acceptable to discard or tiebreak; a total order tiebreak (node id) is acceptable	Bounded convergence — causally-later writes win; concurrent writes are tiebroken deterministically (P4 bound via tiebreak)	Low — simple merge (compare clocks, pick winner); no CRDT library; small payload	Concurrent writes are silently discarded (lost update); tiebreak by wall time = clock-skew oscillation (P4 violation); no vector clock = no concurrent-write detection = silent loss
LWW with wall-clock timestamp only	The data model is ephemeral (cache, presence); lost updates are acceptable; the clock is roughly synchronized (NTP)	Weak — convergence eventually, but concurrent writes may oscillate with clock skew; no concurrent-write detection	Lowest — one timestamp per write; no clock vector	Clock skew = oscillation (P4 violation); concurrent writes silently lost; not a correctness-safe strategy for durable state
Three-way merge (application-specific)	The data model is structured (documents, forms); conflicts should surface to the user or a domain-specific resolver; the merge is field-level	Bounded if the merge function is correct (associative, commutative, idempotent — P4, P5); conflicts surface per field	High — application-specific merge function per type; UI for conflict resolution; user-facing conflict surface	Merge-function bug = silent divergence or oscillation; unbounded conflict UI = user fatigue

• The default for structured state that must converge silently is a CRDT (state-based for unreliable networks, operation-based for bandwidth-constrained reliable transport). The default for arbitrary JSON where lost concurrent updates are acceptable is LWW with vector clocks (never wall-clock-only for durable state). The default for user-facing documents where conflicts should surface is three-way merge with a documented resolution policy.
• The failure-mode column is the P4 check: every row except wall-clock-only LWW carries a bounded failure mode (the bug is in the implementation, not the strategy). Wall-clock-only LWW carries an unbounded failure mode (clock skew = oscillation) and is a P4 violation for durable state. Use it only for ephemeral state where lost updates are acceptable.
• The choice is a P4 decision (which bound) and a C1 decision (which correctness cost). A CRDT guarantees convergence but constrains the data model; LWW is flexible but discards concurrent writes. Neither is universally correct; the matrix is the decision tool.

Observability of Sync (P10 Edge Observability Survives Partition)

• Sync is itself an observable operation: the merge count, the conflict count, the convergence lag (time from reconnect to convergence), and the divergent-replica count are first-class signals. A sync that runs forever without converging is the edge-sync-loop chaos anti-pattern (P4 breach); without observability it is invisible until the user notices the stale state.
• A conflict that is silently resolved should be logged (the resolution policy applied, the discarded write's idempotency key, the winning write's clock). A conflict that surfaces to the user should be metricated (the conflict rate, the resolution time). See domains/observability/metrics for the generic discipline.
• A divergent replica that has not converged after the expected window is an incident; without a metric it is invisible (P10 breach). Wire sync convergence to an alert — the divergent-replica-count is the sync analog of the messaging consumer-lag metric.

What Violates Sync Discipline

Violation	Principle
Sync loop that oscillates forever (CRDT without merge-semantics, LWW without monotonic clock)	P4 Sync Conflicts are Bounded, Not Infinite
LWW with wall-clock timestamp only on durable state (clock skew = oscillation)	P4, C1 (no concurrent-write detection)
Merge function that mutates inputs in place (retried merge is not idempotent)	P5 Edge Operations are Idempotent, domains/concurrency/patterns
Big-bang schema change under sync (replicas fail the merge)	P4, domains/data/migrations
Conflict silently resolved with no log (the policy is invisible)	P10 Edge Observability Survives Partition
Divergent replica with no convergence-lag metric (invisible stale state)	P10, domains/observability/metrics
Three-way merge with an unbounded conflict UI (user fatigue, no termination)	P4 (the merge must terminate)
Operation-based CRDT without causal delivery (lost ops = divergence)	P4, C1 (the delivery contract is the bound)
Merge that surfaces every concurrent conflict to the user (no default policy)	P4, C3 (the default policy is the simplicity bound)
Sync with no convergence test (the merge is untested under partition)	P4, domains/testing/pyramid