docs: rewrite README — sync model, version-vector design, and tradeoffs

[benitogf]

Summary

The README explained pivot in a few lines and carried a stale route table. This rewrite turns it into a document someone can actually decide to adopt (or not) from — it exposes how synchronization works internally and justifies the design.

What the new README covers:

• What pivot is — AP state-sync for ooo servers, an embedded Go library, leader/follower — and its CAP positioning (availability + partition tolerance, at the cost of immediate consistency).
• The full data flow — a node's write pushed to the leader (with the version-vector idempotency guard, VV merge, and originator-skip fan-out); the leader's write fanned out to nodes; catch-up via sync-on-read / on-start / re-trigger; and delete tombstones.
• Version vectors — what and why — causal ordering that survives clock drift, and the conflict policy: VV dominance decides; on genuine concurrency the leader's value wins the round (last-sync-wins, leader-convergent), with wall-clock timestamps used only as a no-VV fallback and a glob-push tiebreak.
• Strengths and pitfalls — including the leader-dials-nodes reachability constraint and that concurrency is resolved leader-convergent (not merged).
• Comparison — a researched table positioning pivot against rqlite/dqlite, Litestream, CouchDB/PouchDB, ElectricSQL/PowerSync, CRDT libraries (Automerge/Yjs), and etcd, with sources.

Also corrects the stale HTTP route table to the routes actually registered under /_pivot.

Docs-only change; no code touched. Every technical claim was fact-checked against the source (roles, push/pull/trigger flow, the VV idempotency guard and merge, last-sync-wins concurrency resolution, tombstone ordering, the route set, and the protocol header constants).

---

🤖 Generated with Claude Code

[CBosch101]

Docs-only rewrite of the README into an adopt-or-not explainer of the sync model, VV design, and tradeoffs. Verdict: APPROVE — I independently fact-checked the technical claims against the source and they hold.

Verified against source:

• Idempotency guard — handlers.go: skips on VVGreater/VVEqual (returns 200, writes nothing), proceeds on VVLess/VVConcurrent, with bump + merge-on-receive after the write. Matches the README's step-by-step exactly.
• Roles — LeaderID = "leader", role decided by ClusterURL == ""; tombstone-first-then-Del ordering and StoragePrefix = "pivot/" are as described.
• The load-bearing claim that wall-clock Updated is not the primary resolver: confirmed. The single-key timestamp comparison only fires in the no-VV cold-start fallback, and the glob per-element timestamp compare only fires on the non-authoritative branch — whenever both sides carry a VV, direction is derived from VV alone.
• Routes table, the X-Pivot-VV / X-Pivot-Originator headers, the unauthenticated /version probe, Port <= 0 ⇒ data-not-node, and the sync-tuned default client (short dial timeout + pooling) all match the code.

No blockers. The comparison table's external positioning claims are properly sourced; reasonable for a docs PR.

---

🤖 Generated with Claude Code