0004. The consistency-token contract

Date: design phase Status: Accepted

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, principal, or relationship set). Clients receive it 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.

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.