Eventual consistency primer
Eventual consistency is the contract that, given enough time and no new writes, every replica of a piece of data will converge on the same value. Meridian relies on this model across its edge gateway, KV cache, and downstream model providers. This primer explains the trade-offs, the failure modes you must design around, and the patterns we recommend for building features on top of it.
1.Why we chose it
Strong consistency requires every read to block on a quorum write. At Meridian's scale that is a non-starter: a coordinator round-trip across regions burns more time than the actual model inference. We accept a small convergence window in exchange for sub-50ms reads from the nearest edge POP. The window is measured in milliseconds, not minutes, and the gateway exposes a freshness header so clients can opt into a stricter read when they need it.
2.The read-your-writes pattern
The classic footgun is updating a record and immediately reading it back from a different replica. To avoid the stale read, pin the follow-up read to the same session token returned by the write. The gateway routes pinned reads to the primary until the propagation deadline passes, then releases them back to the edge.
// Pin follow-up reads to the write session
const write = await meridian.kv.put("user:42", payload);
const fresh = await meridian.kv.get("user:42", {
consistency: "session",
sessionToken: write.sessionToken,
});3.Designing for convergence
Treat every cached value as a hint, not a source of truth. Use idempotent writes, version vectors on records that mutate often, and tombstones with a TTL longer than your worst-case propagation delay. When two writes race, prefer last-write-wins on UX state and CRDTs on counters. The gateway emits a x-meridian-stale header when it served a value past its freshness budget so you can degrade gracefully in the UI.