Skip to content

Session-Guarantee Token

Client-held token interface — instantiates Shared-State Consistency Contract Design

A token the client carries between requests, encoding what it has already observed, so the system can promise read-your-writes and monotonic reads within that one session even over inconsistent replicas.

Session-Guarantee Token provides a small marker that a client carries from one request to the next, recording the versions it has already seen or written. On each read, the system serves only a replica at least as fresh as the token — waiting, rerouting, or repairing if necessary — and advances the token forward. This delivers the four session guarantees (read-your-writes, monotonic reads, monotonic writes, writes-follow-reads) scoped to a single client's session, without making the whole system globally strongly consistent. That scoping is the defining idea: the token turns "what has this one client observed?" into a concrete, portable object, so the most user-visible anomalies vanish cheaply while the underlying store stays weakly consistent and available.

Example

A user posts a comment; the write lands on a replica in one region and returns a version watermark, which the client stores in its session token. Seconds later the user refreshes their timeline and the request is routed to a different, slightly-lagging replica that has not yet received the comment. Without a session guarantee, the timeline comes back without the comment the user just posted — the maddening "I just did that and it's gone" experience. With the token, the read carries the watermark; the lagging replica sees that it is behind the client's known version, so the system either waits for it to catch up, reroutes to a fresh replica, or triggers a repair — and the comment appears. The same token, never decreasing, also guarantees monotonic reads: a later refresh can never show older data than an earlier one.

How it works

The distinguishing mechanic is client-pinned freshness. Writes and reads return a version token (the minimum version the client is now entitled to see); the client replays it on subsequent requests; the read path enforces "serve only if this replica's version ≥ the token, else wait / reroute / repair," and the token advances monotonically. Because the guarantee is anchored to one client's history rather than to a global order, it is cheap: no cross-client coordination is required. It carries a version, but it does not define the versioning scheme — that substrate comes from a version artifact it consumes.

Tuning parameters

  • Guarantees included — which of read-your-writes / monotonic-reads / monotonic-writes / writes-follow-reads are enforced: more safety for more cost.
  • Token contents — a single high-water version, a per-key set, or a full vector: precision versus request-header/cookie bloat.
  • Enforcement on miss — wait for the replica, reroute to a fresh one, trigger repair, or fail: latency versus freshness.
  • Token scope & TTL — session, device, or user, and how long it lives: continuity versus staleness of the watermark.
  • Storage — client cookie/header vs. server-side session store: statelessness versus trust in the client.

When it helps, and when it misleads

Its strength is eliminating the anomalies users actually notice — reverted edits, data that appears then disappears — at very low cost and with no global coordination, letting a weakly-consistent, highly-available store feel personally consistent.[1]

It misleads when its scope is forgotten. The guarantee holds only within a session: two different users, or the same user on two devices without a shared token, get no cross-session promise, so it must not carry cross-client invariants. A lost or reset token silently drops the guarantee (the next read may regress), and full-vector tokens can bloat every request. The classic error is assuming session guarantees imply global consistency and building shared-state invariants on top of them. The discipline is to state the scope explicitly — one session — and route anything cross-client to a global protocol.

How it implements the components

  • session_guarantee_profile — selects and enforces which of the four session guarantees hold for a client across its requests.
  • client_observation_model — the token is the model of what this session has already observed, made concrete and portable so freshness can be pinned to it.

It does not define the underlying version scheme the token carries (version_token) — that is Version Vector — nor establish a cross-client global order (visibility_and_order_relation, Causal-Consistency Protocol) or the strong single-copy guarantee (Linearizable Read/Write Protocol).

References

[1] Session guarantees — read-your-writes, monotonic reads, monotonic writes, and writes-follow-reads — were introduced in the Bayou project (Terry et al.) as per-client properties achievable over weakly-consistent replicas without global coordination. ↩