Cross-shard consistency.

When two related keys A and B live on different shards, the pair of writes is not one atomic step. The client writes A to shard 1 and it succeeds; it writes B to shard 2 and it fails on a network error or a timeout. A now holds new data, B holds old data, and there is no transaction to roll back. A read that fetches both returns inconsistent state.

With a single primary a multi-key transaction or a Lua script would make the pair atomic; across shards that guarantee is gone, so the application has to detect the tear after the fact. These patterns work with any multi-primary Valkey setup — cluster shards, client-side sharding across independent primaries, or even separate deployments — because detection runs at the application layer through shared tokens embedded in the values themselves, with no coordination between instances required.

Pattern 1 — transaction stamp (shared token). Generate one unique token per logical transaction and include it in every related write. A read parses both tokens and compares; equal proves the pair is whole, unequal flags a tear:

Pattern 2 — version-stamped values. A bare token catches a tear but cannot order the sides. A version field both detects and orders: stamp each value {version}:{token}:{payload} and on a mismatch accept the higher version. A wall-clock timestamp orders cheaply but breaks under clock skew; a monotonic INCR user:123:version orders by one source and resolves correctly always.

Pattern 3 — commit marker. Write the data first, then one final SET txn:id:committed 1 EX 3600; a reader accepts the data only when EXISTS txn:id:committed returns the marker. A crash before the marker leaves the data present but invisible — a two-phase-commit shape with the marker as the decision record.

Pattern 4 — append-only logs with shared tokens. For event-sourced state, RPUSH per-key logs stamped with one token, then find the newest token present in both logs — that token names the latest complete transaction. A sorted-set variant scores by timestamp.

Detection is half the policy; the other half is the recovery rule. When a tear is detected, the response depends on what guarantees the values carry:

• Re-read with backoff — the write may still be in progress; retry a few times with increasing delays before declaring a tear.
• Accept newest — if values carry versions, regenerate the older side from the newer.
• Consult the source of truth — re-fetch from the authoritative database, mint a fresh token, and rewrite both values together.
• Serve stale with background repair — return the most recent data immediately and queue an async repair job.

Use transaction stamps when keys must live on different shards and detection plus repair is an acceptable substitute for prevention. Use commit markers when incomplete transactions must be invisible to readers. Use version stamps when you need to determine which write is newest and last-write-wins is acceptable — and all three only when the keys genuinely cannot share a slot.

Detection has a real cost, and a prevention option usually beats it when the keys can be made to share a slot. The five approaches side by side — the top row wins on every column:

When the keys can share a slot, a hash tag co-locates them and a multi-key Lua script stays atomic, so there is no tear to detect. The hero figure above is that choice made concrete — the real EchoMQ keyspace, the braced form versus the flat form, and the slot each lands on.

EchoMQ does not run any of these detectors on its own queue keys, because it removes the tear before it can happen. Every per-queue key is built by EchoMQ.Keyspace.queue_key(q, type), which is literally "emq:{" <> q <> "}:" <> type — the queue name always lands inside the braces. So emq:{orders}:pending and emq:{orders}:active (and the row key emq:{orders}:job:<id>) all hash to one slot. The client computes the slot itself: Keyspace.slot/1 runs CRC16-XMODEM over Keyspace.hashtag/1 modulo 16384, the cluster specification's own algorithm, so the connector can route without a server round trip.

Because the keys co-locate, the whole transition is one inline Lua script. EchoMQ.Jobs.claim/3 (jobs.ex:283) calls Connector.eval/5 with two declared keys, and the @claim script (jobs.ex:126) touches the row key built from ARGV[1] — all three on the {orders} slot, so the move applies in full or not at all:

The v2 law that makes this safe is in Connector.eval/5 (echo_wire/connector.ex:63): parts = ["EVALSHA", s.sha, Integer.to_string(length(keys))] ++ keys ++ argv — every key a script touches is declared in KEYS; ARGV carries values only. Hand that script a key on a different slot and the engine raises CROSSSLOT. The braced keyspace is precisely what keeps it from happening.

Each dive takes one detection pattern in the source's order: the problem and the base token detector, then the version that also orders, then the commit marker that hides an incomplete write — and each closes on the real EchoMQ surface that makes the detector unnecessary on a co-located queue. Read them in order.