Vord

Architecture Decision Record

0004. The consistency-token contract

Context

Vord is read-dominated and globally distributed: the overwhelming majority of its operations are verification and authorization reads, served best from the nearest replica. The constitution (ADR-0001 rule 1) keeps those reads off the strongly-consistent core. But a minority of decisions genuinely need read-your-writes or monotonicity — "did the permission I just granted take effect?", "is the credential I just revoked actually gone?" — and serving those from a lagging replica would be wrong.

Wyrd ADR-0018 reserved its version-fence (meta:version, Wyrd ADR-0015's Option C) as an externally-carryable token precisely so a consumer could express that distinction. Vord is that consumer. This ADR pins what the token carries and how a read chooses between the fast path and the fenced path. It is the consumer-side definition of a hook Wyrd already reserved.

Decision

  1. The consistency token is opaque. It encodes Wyrd's meta:version high-water mark for the relevant aggregate (tenant or principal). Relationship state is not fenced here: it lives in the Forseti relation store, a separate consistency domain with its own version space, and is carried by the composite token's Forseti component (ADR-0026). Clients receive the token from an authoritative operation and present it later; they never interpret it. Opacity lets Vord change the encoding without breaking callers.

  2. Default reads are bounded-staleness, edge-local. The common path — token verification, ordinary authorization — is served from the nearest replica and may lag by up to the replication bound. This is what makes the system scale, and it is the default precisely so the fast path is the path of least resistance.

  3. Read-your-writes-sensitive decisions present a token. A replica serves such a read only if it is caught up to the token's version; otherwise the read routes to the home zone (or waits). This is the Zanzibar "zookie" semantics, and it is opt-in per decision, mirroring Wyrd ADR-0015's contract (home-zone authority in v1, version-fenced replica reads reserved).

  4. Authoritative operations issue tokens. Issuance, permission grant, and revocation return a token; the caller propagates it across services on subsequent reads. This is an SDK responsibility — the thick-client parallel to Wyrd's embedded library. When a caller holds several tokens (or the composite of ADR-0026), the SDK merges them component-wise by domain: each component is tagged with the domain it fences, comparison is per-component, and a merge takes the maximum of each — versions are never compared across domains, whose version spaces are unrelated.

Consequences

  • The common path stays edge-fast and core-independent, satisfying constitution rule 1; the strong path exists exactly where correctness demands it and nowhere else.
  • The token is the single seam between Vord and Wyrd's fence. Until Wyrd's Option C (fenced replica reads) is built, the strong path routes to the home zone — Wyrd's v1 home-zone authority — which is correct but WAN-latent, and improves transparently when Option C lands. Vord, being read-dominated and global, is the concrete consumer that may pull Option C forward (already noted in Wyrd ADR-0018).
  • Callers must carry the token; an SDK concern, not an application one.
  • Because the token is opaque, the encoding and even the underlying fence mechanism can evolve without a client-visible break.
  • A production decision can span more than one strongly-consistent domain — Vord's identity core (this ADR's meta:version fence) and the Forseti relation store (its own zookie), which keep separate version spaces. How the token becomes composite and fences both is settled in ADR-0026; the opacity here is what lets it carry one fence or two without a contract change.