What it does
A GET to /v1 can carry an x-kynetra-consistency header: local, bounded(n) lag, exact(n) position, or an opaque token returned by an earlier call. A node that cannot meet the budget within the deadline refuses with a 412 and machine-readable detail. Successful reads report the assurance they achieved.
How it works
The header values are local, bounded(n), exact(n) and token(opaque). Bounded means the node's applied position must be within n records of the primary's last reported position. Exact means the node must have applied at least position n. A node waits up to a deadline, two seconds by default and at most ten, which a caller can set with x-kynetra-consistency-deadline-ms. If the budget cannot be met, nothing is served: the response is a 412 with a reason of unknown_primary, lag_exceeded, seq_not_applied or seq_too_far_ahead, and a retry hint. A replica whose primary position is unknown, for example just after a restart, cannot prove a bounded budget and refuses.
Successful reads carry x-kynetra-assurance, the level achieved, plus the applied position. Platform callers also see the primary position and the lag; project callers see a coarse lag class alone, because exact positions on a shared log would let a tenant infer other tenants' write activity.
For the same reason, a project-scoped caller cannot name a raw position. It can use local, or token(opaque). Every successful write and every successful declared-budget read on a project credential returns an x-kynetra-consistency-token, an encrypted token that binds one position to that project, and presenting it later gives read-your-writes at exactly that point. A token minted for one project cannot be redeemed by another.
Separately, a replica honours an x-kynetra-min-seq header from platform credentials: it waits up to two seconds for its applied position to reach the value, then answers 412 instead of serving stale data. Project credentials are refused this header and use tokens.
The gate applies to GET and HEAD requests. Writes are never delayed or refused by a staleness budget.
Where you reach it
- HTTP
Request headers x-kynetra-consistency: local | bounded(n) | exact(n) | token(opaque); x-kynetra-consistency-deadline-ms; x-kynetra-min-seq - HTTP
Response headers x-kynetra-assurance, x-kynetra-lag-class, x-kynetra-consistency-token
Limits
- The gate is mounted on the /v1 routes alone. It is not applied to /rest/v1, /v1/collections or the other mounts.
- It reports lag in log positions, not in time.
- Raw bounded and exact budgets are for platform credentials; project credentials use local or tokens.
Evidence
- On this siteReliability
- TestsCovered in the engine repository by 25 consistency-gate tests and 10 token tests in the server crate, and 4 HTTP tests for the minimum-position gate
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to talk through the limits above against your own workload.