# kevy

> Pure-Rust, zero-dependency, Redis-compatible serving engine: the primary
> store for applications (declared indexes, views, write-time aggregates,
> CJK full-text search, vector KNN, CDC feeds, replication) speaking RESP.

Machine notes: wire protocol is RESP2 (RESP3 via HELLO 3). Every verb below
is discoverable live via `COMMAND DOCS <verb>`, which answers with the same
`complexity` and `compat` fields printed here; errors are self-explaining and
their prefixes are a stable contract (docs/error-replies.md). This file is
GENERATED from the server's verb metadata table — do not edit by hand.
The full text of every document below is inlined at https://kevy.golia.jp/llms-full.txt,
which is one fetch and needs no crawling.

Read `compat` before you assume a verb behaves the way Redis's docs say. kevy
is wire-compatible, not behaviour-identical, and the differences that matter
are stated per verb rather than buried in a migration guide. Three that catch
people: SCAN is not a cursor iterator (one call sweeps the whole keyspace and
returns cursor 0); RANDOMKEY, SPOP and SRANDMEMBER are NOT random (they return
the same members every time); and multi-key writes are atomic only within one
shard — co-locate keys with a {hashtag} when you need them to move together.

Read `complexity` before you assume a cost. It was derived from THIS engine's
code, not copied from Redis: our sorted set is a hash plus a plain BTreeSet
with no rank augmentation, so ZRANK is O(N) here and score-range queries scan
rather than seek.

## Docs

- [Verb reference](https://kevy.golia.jp/docs/commands/): every verb, arity, flags, syntax
- [Designing on kevy](https://kevy.golia.jp/docs/designing-on-kevy/): the serving-engine model
- [Cookbook](https://kevy.golia.jp/docs/cookbook/): RDS-to-kevy modeling recipes
- [RDS workloads](https://kevy.golia.jp/docs/rds-workloads/): SQL-to-kevy reference matrix (types, SELECT, JOIN, transactions, DDL)
- [Indexes](https://kevy.golia.jp/docs/indexes/) · [Views](https://kevy.golia.jp/docs/views/) · [Text search](https://kevy.golia.jp/docs/text-search/) · [Vector search](https://kevy.golia.jp/docs/vector-search/)
- [CDC feeds](https://kevy.golia.jp/docs/cdc/) · [Replication](https://kevy.golia.jp/docs/replication/) · [Availability & failover](https://kevy.golia.jp/docs/availability/) · [Persistence](https://kevy.golia.jp/docs/persistence/)
- [Migration](https://kevy.golia.jp/docs/migration/) · [Upgrading between majors](https://kevy.golia.jp/docs/UPGRADING/)
- [WASM / browser](https://kevy.golia.jp/docs/wasm/) · [IoT / embedded tiers](https://kevy.golia.jp/docs/iot/)
- [Error contract](https://kevy.golia.jp/docs/error-replies/) · [Tuning](https://kevy.golia.jp/docs/tuning/)

## Verbs (184 total)

### scan

- `KEYS pattern` [readonly] — Return every key matching the glob pattern (cross-shard gather).
  - complexity: O(N) keys in the whole keyspace — every shard walks its entire map, plus an O(P*K) glob match per key
  - compat: full
- `RANDOMKEY` [readonly] — Return a random key from the keyspace.
  - complexity: O(1) expected
  - compat: differs: the result is NOT random — each shard returns the first live key in hash-bucket order and the reducer takes the first shard's, so a fixed keyspace returns the same key every time; do not use it for sampling
- `SCAN cursor [MATCH pattern] [COUNT count]` [readonly] — Sweep the keyspace and return every match at once; NOT a cursor iterator (COUNT and TYPE are accepted and ignored, and the cursor is always 0).
  - complexity: O(N) keys in the WHOLE keyspace, on every call — there is no incremental walk
  - compat: differs: SCAN is not a cursor iterator. Every call sweeps every shard's entire keyspace and replies with cursor 0 and all matches in one batch, so the standard SCAN loop terminates after one round trip. COUNT and TYPE are accepted and ignored; MATCH is honoured. Redis's incremental, bounded-work, rehash-tolerant guarantees do not exist here

### generic

- `DEL key [key ...]` [write] — Delete one or more keys.
  - complexity: O(N) keys, plus O(M) per key holding a collection of M elements (the drop walks the container)
  - compat: differs: the multi-key form is split by shard and summed with no barrier, so it is not atomic across shards; the single-key form is
- `EXISTS key [key ...]` [readonly] — Count how many of the given keys exist.
  - complexity: O(N) keys, one O(1) probe each
  - compat: differs: the multi-key form is gathered per shard, so the count is not a point-in-time snapshot across shards
- `EXPIRE key seconds` [write] — Set a key's TTL in seconds (non-positive TTL deletes the key).
  - complexity: O(1)
  - compat: differs: the NX / XX / GT / LT condition flags are not parsed — arity is fixed at 3, so EXPIRE key seconds NX is a wrong-arity error
- `EXPIREAT key unix-time-seconds` [write] — Set a key's expiry as an absolute Unix timestamp in seconds.
  - complexity: O(1)
  - compat: differs: the NX / XX / GT / LT condition flags are not parsed — arity is fixed at 3
- `PERSIST key` [write] — Remove a key's TTL.
  - complexity: O(1)
  - compat: full
- `PEXPIRE key milliseconds` [write] — Set a key's TTL in milliseconds.
  - complexity: O(1)
  - compat: differs: the NX / XX / GT / LT condition flags are not parsed — arity is fixed at 3
- `PEXPIREAT key unix-time-milliseconds` [write] — Set a key's expiry as an absolute Unix timestamp in milliseconds.
  - complexity: O(1)
  - compat: differs: the NX / XX / GT / LT condition flags are not parsed — arity is fixed at 3
- `PTTL key` [readonly] — Return a key's remaining TTL in milliseconds (-1 no TTL, -2 missing).
  - complexity: O(1)
  - compat: full
- `RENAME key newkey` [write] — Rename a key, overwriting the destination (write routed at the runtime Op level).
  - complexity: O(1) for a string value; O(M) for a collection of M elements (the entry's weight is re-derived by walking the value)
  - compat: differs: a cross-shard rename is a non-atomic Take then Put — there is a window in which neither key is visible; co-locate the two keys with a {hashtag} for the atomic path
- `RENAMENX key newkey` [write] — Rename a key only if the destination does not exist (write routed at the runtime Op level).
  - complexity: O(1) for a string value; O(M) for a collection of M elements
  - compat: differs: cross-shard RENAMENX is a non-atomic Take, Put, restore-on-refusal sequence — there is a window in which the source is absent from the keyspace
- `TTL key` [readonly] — Return a key's remaining TTL in seconds (-1 no TTL, -2 missing).
  - complexity: O(1)
  - compat: full
- `TYPE key` [readonly] — Return the type of the value stored at key.
  - complexity: O(1)
  - compat: full
- `UNLINK key [key ...]` [write] — Delete one or more keys (alias of DEL in kevy's shard model).
  - complexity: O(N) keys, plus O(M) per collection-typed key — identical to DEL
  - compat: differs: UNLINK is an alias of DEL — the value is freed inline on the owning shard's reactor thread, not by a background thread, so it gives no latency benefit

### string

- `APPEND key value` [write] — Append bytes to a string value; returns the new length.
  - complexity: O(1) amortised while the value is <= 64 B; O(N) per call once it exceeds that (the Arc payload is copied out and re-boxed on every append), so building a large string by repeated APPEND is O(N^2)
  - compat: full
- `DECR key` [write] — Decrement the integer value of a key by one.
  - complexity: O(1)
  - compat: full
- `DECRBY key decrement` [write] — Decrement the integer value of a key by the given amount.
  - complexity: O(1)
  - compat: full
- `GET key` [readonly] — Return the string value of a key.
  - complexity: O(1)
  - compat: full
- `GETDEL key` [write] — Return the string value of a key and delete it.
  - complexity: O(1)
  - compat: full
- `GETSET key value` [write] — Set a key's string value and return its previous value.
  - complexity: O(1)
  - compat: full
- `INCR key` [write] — Increment the integer value of a key by one.
  - complexity: O(1)
  - compat: full
- `INCRBY key increment` [write] — Increment the integer value of a key by the given amount.
  - complexity: O(1)
  - compat: full
- `INCRBYFLOAT key increment` [write] — Increment the float value of a key by the given amount.
  - complexity: O(1)
  - compat: differs: arithmetic is f64 and the reply uses Rust's shortest-round-trip float printer, not a long double accumulator, so trailing digits can diverge from Redis
- `MGET key [key ...]` [readonly] — Return the values of multiple keys (cross-shard gather).
  - complexity: O(N) keys, one O(1) probe each on the owning shard
  - compat: differs: keys are grouped by shard and each shard is probed independently, so the reply is not a point-in-time snapshot across shards
- `MSET key value [key value ...]` [write] — Set multiple key/value pairs atomically per shard.
  - complexity: O(N) pairs, one O(1) SET each
  - compat: differs: atomic only per shard — pairs are split by key and applied shard-by-shard with no cross-shard barrier, so a reader can observe some pairs written and others not; Redis MSET is globally atomic
- `PSETEX key milliseconds value` [write] — Set a key's value with a TTL in milliseconds.
  - complexity: O(1)
  - compat: full
- `SET key value [EX seconds|PX milliseconds] [NX|XX]` [write] — Set a key's string value with optional TTL and existence conditions.
  - complexity: O(1)
  - compat: differs: only NX / XX / EX / PX are parsed — KEEPTTL, EXAT, PXAT, GET and the IFEQ family are a syntax error; a repeated expire option is silently accepted last-one-wins instead of erroring
- `SETEX key seconds value` [write] — Set a key's value with a TTL in seconds.
  - complexity: O(1)
  - compat: full
- `SETNX key value` [write] — Set a key's value only if it does not exist.
  - complexity: O(1)
  - compat: full
- `STRLEN key` [readonly] — Return the length of a key's string value.
  - complexity: O(1)
  - compat: full

### hash

- `HDEL key field [field ...]` [write] — Delete one or more hash fields.
  - complexity: O(M) fields
  - compat: full
- `HEXISTS key field` [readonly] — Check whether a hash field exists.
  - complexity: O(1)
  - compat: full
- `HEXPIRE key seconds [NX|XX|GT|LT] FIELDS numfields field [field ...]` [write] — Set per-field TTLs on a hash, in seconds.
  - complexity: O(F) fields in the FIELDS clause
  - compat: differs: the FIELDS parse error reads 'Mandatory keyword FIELDS is missing' where Redis says 'Mandatory argument FIELDS'
- `HGET key field` [readonly] — Return the value of a hash field.
  - complexity: O(1)
  - compat: full
- `HGETALL key` [readonly] — Return all fields and values of a hash.
  - complexity: O(N) fields, with a full copy of every name and value
  - compat: full
- `HINCRBY key field increment` [write] — Increment the integer value of a hash field.
  - complexity: O(1)
  - compat: full
- `HKEYS key` [readonly] — Return all field names of a hash.
  - complexity: O(N) fields
  - compat: full
- `HLEN key` [readonly] — Return the number of fields in a hash.
  - complexity: O(1)
  - compat: full
- `HMGET key field [field ...]` [readonly] — Return the values of multiple hash fields.
  - complexity: O(M) fields requested
  - compat: full
- `HMSET key field value [field value ...]` [write] — Deprecated alias of HSET that replies OK.
  - complexity: O(M) pairs
  - compat: full
- `HPERSIST key FIELDS numfields field [field ...]` [write] — Remove per-field TTLs from a hash.
  - complexity: O(F) fields
  - compat: differs: silently accepts a stray NX|XX|GT|LT token before FIELDS (it shares HEXPIRE's parser) where Redis rejects it
- `HPEXPIRE key milliseconds [NX|XX|GT|LT] FIELDS numfields field [field ...]` [write] — Set per-field TTLs on a hash, in milliseconds.
  - complexity: O(F) fields
  - compat: differs: same FIELDS error-text deviation as HEXPIRE
- `HPEXPIREAT key unix-time-milliseconds [NX|XX|GT|LT] FIELDS numfields field [field ...]` [write] — Set per-field expiries as absolute Unix-millisecond deadlines.
  - complexity: O(F) fields
  - compat: differs: same FIELDS error-text deviation as HEXPIRE
- `HSCAN key cursor [MATCH pattern] [COUNT count]` [readonly] — Iterate a hash's fields and values (single-batch cursor).
  - complexity: O(N) — the whole hash is copied and returned in one batch
  - compat: differs: not a cursor iterator — the cursor is always 0 and the entire hash comes back in a single reply; NOVALUES is not parsed and COUNT is validated then ignored
- `HSET key field value [field value ...]` [write] — Set one or more hash fields; returns the number of new fields.
  - complexity: O(M) pairs
  - compat: full
- `HSETNX key field value` [write] — Set a hash field only if it does not exist.
  - complexity: O(1)
  - compat: full
- `HPTTL key FIELDS numfields field [field ...]` [readonly] — Return per-field remaining TTLs in milliseconds (-1 no TTL, -2 missing).
  - complexity: O(F) fields
  - compat: differs: silently accepts a stray NX|XX|GT|LT token before FIELDS where Redis rejects it
- `HTTL key FIELDS numfields field [field ...]` [readonly] — Return per-field remaining TTLs in seconds (-1 no TTL, -2 missing).
  - complexity: O(F) fields
  - compat: differs: silently accepts a stray NX|XX|GT|LT token before FIELDS where Redis rejects it
- `HVALS key` [readonly] — Return all values of a hash.
  - complexity: O(N) fields
  - compat: full

### list

- `BLPOP key [key ...] timeout` [write,blocking] — Blocking left pop across one or more lists (effect logged as LPOP).
  - complexity: O(1) to serve; the park is O(1) and waiters are woken FIFO per key
  - compat: differs: on a multi-shard server the multi-key form does not honour Redis's left-to-right key priority — keys on the connection's own shard are served before remote ones
- `BRPOP key [key ...] timeout` [write,blocking] — Blocking right pop across one or more lists (effect logged as RPOP).
  - complexity: O(1) to serve; FIFO park
  - compat: differs: same multi-key priority deviation as BLPOP
- `BRPOPLPUSH source destination timeout` [write,blocking] — Blocking RPOPLPUSH: pop the source tail and push it onto the destination head.
  - complexity: O(1) to serve
  - compat: differs: a cross-shard move is not atomic — the element is popped on the source's shard and pushed on the destination's, and between those two steps it is in neither list. Co-locate the keys with a {hashtag} to get Redis's atomic path
- `LINDEX key index` [readonly] — Return the element at the given list index.
  - complexity: O(1) — the list is a VecDeque, so an index is a direct offset (Redis's quicklist is O(N))
  - compat: full
- `LLEN key` [readonly] — Return the length of a list.
  - complexity: O(1)
  - compat: full
- `LMOVE source destination LEFT|RIGHT LEFT|RIGHT` [write] — Atomically move an element between two lists.
  - complexity: O(1)
  - compat: differs: a cross-shard move is not atomic — see BRPOPLPUSH
- `LPOP key [count]` [write] — Pop one or more elements from the head of a list.
  - complexity: O(C) elements popped
  - compat: differs: LPOP key 0 on an existing key replies a nil array where Redis replies an empty array
- `LPOS key element [RANK rank] [COUNT num-matches] [MAXLEN len]` [readonly] — Return the index of matching elements in a list.
  - complexity: O(N) always — the whole list is copied before RANK / COUNT / MAXLEN are applied, so MAXLEN bounds the comparisons but not the copy
  - compat: full
- `LPUSH key element [element ...]` [write] — Prepend one or more elements to a list.
  - complexity: O(M) values, O(1) amortised each
  - compat: full
- `LRANGE key start stop` [readonly] — Return a range of list elements.
  - complexity: O(M) elements returned — the start offset is skipped in O(1) (Redis is O(S+M))
  - compat: full
- `LREM key count element` [write] — Remove elements equal to the given value from a list.
  - complexity: O(N*R) worst case — the scan is O(N) but each removal shifts up to half the deque (Redis is O(N+R))
  - compat: full
- `LSET key index element` [write] — Set the list element at the given index.
  - complexity: O(1) — a direct index write (Redis is O(N) for a mid-list index)
  - compat: full
- `LTRIM key start stop` [write] — Trim a list to the given range.
  - complexity: O(R) elements removed
  - compat: full
- `RPOP key [count]` [write] — Pop one or more elements from the tail of a list.
  - complexity: O(C) elements popped
  - compat: differs: RPOP key 0 on an existing key replies a nil array where Redis replies an empty array
- `RPOPLPUSH source destination` [write] — Pop the source tail and push it onto the destination head.
  - complexity: O(1)
  - compat: differs: a cross-shard move is not atomic — see BRPOPLPUSH
- `RPUSH key element [element ...]` [write] — Append one or more elements to a list.
  - complexity: O(M) values, O(1) amortised each
  - compat: full

### set

- `SADD key member [member ...]` [write] — Add one or more members to a set.
  - complexity: O(M) members
  - compat: full
- `SCARD key` [readonly] — Return the number of members in a set.
  - complexity: O(1)
  - compat: full
- `SDIFF key [key ...]` [readonly] — Return the difference of the given sets (cross-shard gather).
  - complexity: O(sum of the source cardinalities)
  - compat: full
- `SDIFFSTORE destination key [key ...]` [write] — Store the difference of the given sets into destination.
  - complexity: O(sum of the source cardinalities) + O(result) to write the destination on its own shard
  - compat: full
- `SINTER key [key ...]` [readonly] — Return the intersection of the given sets (cross-shard gather).
  - complexity: O(sum of the source cardinalities) — there is NO smallest-set-first ordering, so SINTER huge tiny costs O(huge) where Redis costs O(tiny * k)
  - compat: full
- `SINTERSTORE destination key [key ...]` [write] — Store the intersection of the given sets into destination.
  - complexity: O(sum of the source cardinalities) + O(result); same no-smallest-first algorithm
  - compat: full
- `SISMEMBER key member` [readonly] — Check whether a value is a member of a set.
  - complexity: O(1)
  - compat: full
- `SMEMBERS key` [readonly] — Return all members of a set.
  - complexity: O(N) members
  - compat: full
- `SPOP key [count]` [write] — Remove and return one or more random members of a set.
  - complexity: O(count) expected; draining an N-member set with N calls is O(N^2) because the bucket scan restarts each time
  - compat: differs: members are NOT random — SPOP returns the first members in hash-bucket order and the seed is a fixed constant, so repeated SPOP on the same set is fully deterministic
- `SRANDMEMBER key [count]` [readonly] — Return one or more random members of a set without removing them.
  - complexity: O(count) expected
  - compat: differs: NOT random — it returns the same first-bucket member every time for a given set; a negative count is rejected instead of returning |count| members with repetitions
- `SREM key member [member ...]` [write] — Remove one or more members from a set.
  - complexity: O(M) members
  - compat: full
- `SSCAN key cursor [MATCH pattern] [COUNT count]` [readonly] — Iterate a set's members (single-batch cursor).
  - complexity: O(N) — the whole set is copied and returned in one batch
  - compat: differs: not a cursor iterator — the cursor is always 0 and the entire set comes back in one reply; COUNT is validated then ignored
- `SUNION key [key ...]` [readonly] — Return the union of the given sets (cross-shard gather).
  - complexity: O(sum of the source cardinalities)
  - compat: full
- `SUNIONSTORE destination key [key ...]` [write] — Store the union of the given sets into destination.
  - complexity: O(sum of the source cardinalities) + O(result)
  - compat: full

### zset

- `BZPOPMIN key [key ...] timeout` [write,blocking] — Blocking pop of the lowest-scored member across one or more sorted sets.
  - complexity: O(log N) per pop; the park is O(1)
  - compat: full
- `ZADD key [NX|XX] [GT|LT] [CH] [INCR] score member [score member ...]` [write] — Add members with scores to a sorted set, with conditional flags.
  - complexity: O(M log N) — O(1) hash insert plus O(log N) tree insert per member
  - compat: full
- `ZCARD key` [readonly] — Return the number of members in a sorted set.
  - complexity: O(1)
  - compat: full
- `ZCOUNT key min max` [readonly] — Count members with scores within the given bounds.
  - complexity: O(N) — a full scan and filter, NOT a range seek; Redis's O(log N) does not apply
  - compat: full
- `ZDIFFSTORE destination numkeys key [key ...]` [write] — Store the difference of the given sorted sets into destination.
  - complexity: O(sum of the source cardinalities + R log R); each source is extracted whole on its own shard
  - compat: full
- `ZINCRBY key increment member` [write] — Increment a member's score in a sorted set.
  - complexity: O(log N)
  - compat: full
- `ZINTERCARD numkeys key [key ...] [LIMIT limit]` [readonly] — Return the cardinality of the intersection of the given sorted sets.
  - complexity: O(sum of the source cardinalities) — LIMIT does not short-circuit the gather, only the combine
  - compat: full
- `ZINTERSTORE destination numkeys key [key ...] [WEIGHTS weight [weight ...]] [AGGREGATE SUM|MIN|MAX]` [write] — Store the intersection of the given sorted sets into destination.
  - complexity: O(sum of the source cardinalities + R log R)
  - compat: full
- `ZPOPMIN key [count]` [write] — Pop up to count members with the lowest scores.
  - complexity: O(M log N)
  - compat: full
- `ZPOPMIN.BELOW key below [count]` [write,extension] — kevy extension: pop up to count lowest members with score strictly below the threshold (delayed-job primitive).
  - complexity: O(M log N) — take_while stops at the first score at or above the threshold, so it never walks past the due prefix
  - compat: kevy-only: a delayed-job primitive (score = due time); no Redis analogue
- `ZRANGE key start stop [WITHSCORES]` [readonly] — Return members by rank range.
  - complexity: O(start + M) — the tree iterator advances one node at a time; there is no rank index to jump with
  - compat: differs: only the legacy 'key start stop [WITHSCORES]' form is accepted — the Redis 6.2 BYSCORE / BYLEX / REV / LIMIT arguments are a syntax error
- `ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count]` [readonly] — Return members with scores within the given bounds.
  - complexity: O(N + M) — a full scan and filter; LIMIT is applied after the whole match set is materialised, so it does not reduce the work
  - compat: full
- `ZRANK key member` [readonly] — Return a member's rank, ordered from the lowest score.
  - complexity: O(N) — a linear position scan. NOT O(log N): our zset has no rank-augmented structure
  - compat: differs: the Redis 7.2 WITHSCORE option is not supported
- `ZREM key member [member ...]` [write] — Remove one or more members from a sorted set.
  - complexity: O(M log N)
  - compat: full
- `ZREMRANGEBYRANK key start stop` [write] — Remove members within the given rank range.
  - complexity: O(start + M log N)
  - compat: full
- `ZREMRANGEBYSCORE key min max` [write] — Remove members with scores within the given bounds.
  - complexity: O(N + M log N) — a full scan to find the hit set, then M deletes
  - compat: full
- `ZREVRANGEBYSCORE key max min [WITHSCORES] [LIMIT offset count]` [readonly] — Return members with scores within the given bounds, highest first.
  - complexity: O(N + M) — a forward full scan and filter, then the result is reversed
  - compat: full
- `ZSCAN key cursor [MATCH pattern] [COUNT count]` [readonly] — Iterate a sorted set's members and scores (single-batch cursor).
  - complexity: O(N) — the whole set is materialised
  - compat: differs: not a cursor iterator — every call returns the whole set with cursor 0, and COUNT is parsed then ignored
- `ZSCORE key member` [readonly] — Return a member's score.
  - complexity: O(1) — a hash lookup
  - compat: full
- `ZUNIONSTORE destination numkeys key [key ...] [WEIGHTS weight [weight ...]] [AGGREGATE SUM|MIN|MAX]` [write] — Store the union of the given sorted sets into destination.
  - complexity: O(sum of the source cardinalities + R log R)
  - compat: full

### stream

- `XACK key group id [id ...]` [write] — Acknowledge pending entries for a consumer group.
  - complexity: O(A log P)
  - compat: full
- `XADD key [NOMKSTREAM] [MAXLEN [=|~] threshold | MINID [=|~] id] id|* field value [field value ...]` [write] — Append an entry to a stream, with optional trim.
  - complexity: O(log N) to insert; O(N*F) whenever a MAXLEN / MINID clause actually evicts, because the trim triggers a full weight recompute
  - compat: differs: the approximate-trim '~' is accepted for wire compatibility but always trims exactly, and the LIMIT clause is not parsed
- `XAUTOCLAIM key group consumer min-idle-time start [COUNT count] [JUSTID]` [write] — Scan and claim idle pending entries starting from a cursor.
  - complexity: O(log P + K + COUNT log N); the idle filter runs before the take, so a PEL of fresh entries is walked in full
  - compat: differs: the next-cursor is last-claimed+1 rather than 0-0 when the PEL scan completes, so a client looping until 0-0 needs one extra round trip
- `XCLAIM key group consumer min-idle-time id [id ...] [IDLE ms] [TIME unix-time-milliseconds] [RETRYCOUNT count] [FORCE] [JUSTID]` [write] — Claim specific idle pending entries for a consumer.
  - complexity: O(A * (log P + log N))
  - compat: differs: IDLE / TIME / RETRYCOUNT / FORCE / JUSTID are parsed but LASTID is not, and a missing key or group returns 'no such key' instead of NOGROUP
- `XDEL key id [id ...]` [write] — Delete entries from a stream by ID.
  - complexity: O(D log N + N*F) for D ids — NOT O(1): the trailing weight recompute is linear in the whole stream
  - compat: full
- `XGROUP CREATE key group id|$ [MKSTREAM] | DESTROY key group | SETID key group id|$ | CREATECONSUMER key group consumer | DELCONSUMER key group consumer` [write] — Manage stream consumer groups.
  - complexity: CREATE / DESTROY: O(1) plus an O(N*F) reweigh. SETID / CREATECONSUMER: O(1). DELCONSUMER: O(P)
  - compat: differs: CREATE / SETID / DESTROY / CREATECONSUMER / DELCONSUMER / MKSTREAM are supported, but on a missing key the non-CREATE subcommands return 0 or NOGROUP instead of Redis's error, and XGROUP HELP is absent
- `XINFO STREAM key | GROUPS key | CONSUMERS key group | HELP` [readonly] — Introspect a stream, its groups, or its consumers.
  - complexity: STREAM: O(1). GROUPS: O(G*N) — 'lag' is a linear walk of every entry, once per group. CONSUMERS: O(C)
  - compat: differs: STREAM / GROUPS / CONSUMERS / HELP only — XINFO STREAM FULL is absent; radix-tree-keys and nodes are synthetic (we have no radix tree), entries-read is approximated, and CONSUMERS omits 'inactive'
- `XLEN key` [readonly] — Return the number of entries in a stream.
  - complexity: O(1)
  - compat: full
- `XPENDING key group [[IDLE min-idle-time] start end count [consumer]]` [readonly] — Inspect pending entries of a consumer group (summary or extended form).
  - complexity: summary: O(P*C) — the per-consumer tally is a linear find per PEL row. extended: O(log P + K)
  - compat: full
- `XRANGE key start end [COUNT count]` [readonly] — Return stream entries within an ID range.
  - complexity: O(log N + M) — a B-tree range descent, COUNT applied lazily
  - compat: full
- `XREAD [COUNT count] [BLOCK milliseconds] STREAMS key [key ...] id [id ...]` [readonly,blocking] — Read new entries from one or more streams, optionally blocking.
  - complexity: O(S * (log N + M)) over S streams; '$' is O(1); the park is O(1)
  - compat: differs: the '+' last-id form is not parsed — only explicit IDs and '$' are accepted
- `XREADGROUP GROUP group consumer [COUNT count] [BLOCK milliseconds] [NOACK] STREAMS key [key ...] id [id ...]` [write,blocking] — Read stream entries as a consumer-group member, optionally blocking.
  - complexity: '>' form: O(log N + U + M) — COUNT does NOT bound the scan, the entire undelivered tail is materialised first. Replay form: O(log P + K)
  - compat: differs: COUNT is parsed but does not bound the '>' scan
- `XREVRANGE key end start [COUNT count]` [readonly] — Return stream entries within an ID range, in reverse order.
  - complexity: O(log N + M)
  - compat: full
- `XSETID key last-id [ENTRIESADDED entries-added] [MAXDELETEDID max-deleted-id]` [write] — Overwrite a stream's last-generated ID and bookkeeping counters.
  - complexity: O(log N)
  - compat: full
- `XTRIM key MAXLEN|MINID [=|~] threshold` [write] — Trim a stream by length or minimum ID.
  - complexity: O(R log N + N*F) for R evicted entries
  - compat: differs: '~' is accepted but trimming is always exact, LIMIT is not parsed, and trailing tokens after the threshold are silently ignored instead of erroring

### geo

- `GEOADD key [NX|XX] [CH] longitude latitude member [longitude latitude member ...]` [write] — Add geospatial members (longitude/latitude) to a geo set.
  - complexity: O(M log N); CH adds an O(M^2) term
  - compat: full
- `GEODIST key member1 member2 [m|km|mi|ft]` [readonly] — Return the distance between two geo members.
  - complexity: O(1)
  - compat: full
- `GEOHASH key member [member ...]` [readonly] — Return the base32 geohash string of each member.
  - complexity: O(M)
  - compat: full
- `GEOPOS key member [member ...]` [readonly] — Return the longitude/latitude of each member.
  - complexity: O(M)
  - compat: full
- `GEORADIUS key longitude latitude radius m|km|mi|ft [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC|DESC] [STORE key] [STOREDIST key]` [write] — Legacy radius search around a coordinate, with optional STORE writes.
  - complexity: O(N) per call; STORE / STOREDIST add O(K log K) to write plus O(D) to clear the destination
  - compat: differs: the destination is written on its own shard, so a STORE across shards is not atomic with the search
- `GEORADIUSBYMEMBER key member radius m|km|mi|ft [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC|DESC] [STORE key] [STOREDIST key]` [write] — Legacy radius search around an existing member, with optional STORE writes.
  - complexity: O(N) per call; the anchor lookup is O(1)
  - compat: differs: the destination is written on its own shard, so a STORE across shards is not atomic with the search
- `GEOSEARCH key FROMMEMBER member|FROMLONLAT longitude latitude BYRADIUS radius m|km|mi|ft|BYBOX width height m|km|mi|ft [ASC|DESC] [COUNT count [ANY]] [WITHCOORD] [WITHDIST] [WITHHASH]` [readonly] — Search members within a radius or box from a member or coordinate.
  - complexity: O(N) per call — up to nine neighbour ranges, each fetched with a full zset scan; the geohash block prunes distance maths, not iteration
  - compat: differs: STOREDIST is accepted and ignored on the read-only form; COUNT 0 is an error
- `GEOSEARCHSTORE destination source FROMMEMBER member|FROMLONLAT longitude latitude BYRADIUS radius m|km|mi|ft|BYBOX width height m|km|mi|ft [ASC|DESC] [COUNT count [ANY]] [STOREDIST]` [write] — Run GEOSEARCH on source and store the hits into destination.
  - complexity: O(N) to search, plus O(D + K log K) to rewrite the destination on its own shard
  - compat: differs: STOREDIST stores the distance in the unit the query asked for (Redis does the same); the destination is written on its own shard, so the source and destination may live on different cores and the write is not atomic with the read

### connection

- `ECHO message` [readonly] — Return the given message.
  - complexity: O(1)
  - compat: full
- `HELLO [protover]` [readonly] — Handshake: report server info and switch RESP protocol version (2 or 3).
  - complexity: O(1)
  - compat: differs: only HELLO [2|3] is honoured — the AUTH and SETNAME tails are parsed off and ignored, because kevy has no AUTH and this form does not set the connection name
- `PING [message]` [readonly] — Ping the server; returns PONG or echoes the optional message.
  - complexity: O(1)
  - compat: differs: kevy has no RESP2 subscriber mode, so PING while subscribed does not switch to the array form and non-pubsub commands stay legal on a subscribed connection
- `QUIT` [readonly] — Close the connection after replying OK.
  - complexity: O(1)
  - compat: full
- `SELECT index` [readonly] — Select the logical database; kevy is single-DB and only accepts index 0.
  - complexity: O(1)
  - compat: differs: kevy is single-DB — SELECT 0 replies OK and any other index is an error

### server

- `BGREWRITEAOF` [write,admin] — Start an append-only-file rewrite in the background.
  - complexity: O(S) fan-out; each shard freezes a copy-on-write view and hands serialise plus fsync to its own worker
  - compat: differs: replies +OK rather than Redis's status line, rewrites one AOF per shard, and replies +OK even when AOF is disabled
- `BGSAVE` [write,admin] — Start a snapshot save in the background.
  - complexity: O(S) fan-out; O(N/S) copy-on-write freeze per shard on the reactor, then serialise off-thread
  - compat: differs: replies +OK rather than Redis's status line, and writes one dump per shard
- `COMMAND [COUNT | LIST | INFO command [command ...] | DOCS [command [command ...]]]` [readonly] — Introspect the command table (COUNT, LIST, INFO, DOCS subcommands).
  - complexity: bare / LIST / DOCS: O(V) verbs. COUNT: O(1). INFO / DOCS with k names: O(k*V) — the lookup is a linear scan
  - compat: differs: COUNT / LIST / INFO / DOCS only — GETKEYS and GETKEYSANDFLAGS are absent, and the info rows hard-code first/last/step and leave ACL categories, tips and key-specs empty
- `CONFIG GET parameter | SET parameter value | REWRITE | RESETSTAT` [write,admin] — Read or change server configuration parameters.
  - complexity: GET: O(patterns * 16). SET: O(1) plus one config swap that shards pick up on their next tick. REWRITE: O(config file size)
  - compat: differs: 16 Redis-named parameters exist; only maxmemory, maxmemory-policy, appendfsync, the auto-rewrite pair, hz, maxmemory-samples, loglevel and logfile are hot-settable — bind, port, io-threads, dir and appendonly error at runtime; RESETSTAT is a no-op
- `CLIENT ID | GETNAME | SETNAME name | LIST | KILL filter | INFO | NO-EVICT ON|OFF` [readonly,admin] — Connection introspection and control subcommands.
  - complexity: ID / GETNAME / SETNAME / INFO: O(1). LIST: O(S) fan-out + O(C) rows. KILL: O(S) + O(C) scan
  - compat: differs: ID / GETNAME / SETNAME / INFO / LIST (bare) / KILL (ID, ADDR) / NO-EVICT only; CLIENT LIST with a filter is a syntax error and every other subcommand (PAUSE, REPLY, TRACKING, UNBLOCK, NO-TOUCH) is unknown
- `CLUSTER INFO | NODES | SLOTS | SHARDS | KEYSLOT key | COUNTKEYSINSLOT slot` [readonly,admin] — Cluster topology introspection (virtual-node model over shards).
  - complexity: INFO / NODES / SLOTS / SHARDS / MYID: O(S). KEYSLOT: O(len(key)). COUNTKEYSINSLOT: O(N/S)
  - compat: differs: a read-only virtual-node topology derived from config (one virtual master per shard) — no gossip, no MEET / FORGET / SETSLOT effect (they reply OK as no-ops), no MIGRATE / ASK, no failover; COUNTKEYSINSLOT counts only the answering shard's keys
- `DBSIZE` [readonly] — Return the number of keys across all shards.
  - complexity: O(S) — one message per shard, each answering O(1) from its map length; NOT O(N)
  - compat: full
- `DEBUG SLEEP seconds | subcommand [args ...]` [readonly,admin] — Debug subcommands; SLEEP blocks the shard, other subcommands are tolerated as OK.
  - complexity: SLEEP: parks the ANSWERING shard's reactor thread for the duration (other shards keep serving). Everything else: O(1)
  - compat: differs: SLEEP is the only subcommand with an effect and it blocks one shard, not the server; every other subcommand is accepted and answered OK without doing anything
- `FLUSHALL` [write] — Delete every key on every shard.
  - complexity: O(S) fan-out; per shard O(N/S) clear plus WATCH invalidation plus a feed-generation bump
  - compat: differs: ASYNC / SYNC are accepted and ignored (the flush is always synchronous per shard), and it bumps the CDC feed generation, so live FEED cursors get a resync error
- `FLUSHDB` [write] — Delete every key of the current database (kevy is single-DB: same as FLUSHALL).
  - complexity: O(N + S) — identical to FLUSHALL
  - compat: differs: kevy is single-DB, so FLUSHDB is an alias of FLUSHALL; ASYNC / SYNC are ignored
- `INFO [section]` [readonly] — Report server statistics and status sections as text.
  - complexity: O(1) in the keyspace — it never walks it; O(S) to sum the per-shard gauges
  - compat: differs: 8 sections only (server, clients, memory, persistence, stats, replication, cluster, keyspace) — no commandstats / latencystats / errorstats / cpu; reports redis_version 7.4.0 for client sniffing plus a kevy_version line, and the values are up to one tick stale
- `MEMORY USAGE key [SAMPLES count] | STATS | DOCTOR | PURGE | MALLOC-STATS` [readonly] — Memory introspection subcommands.
  - complexity: USAGE: O(1) — the accounting is exact, not sampled. STATS: O(1) from the instance-wide gauges
  - compat: differs: USAGE's SAMPLES count is parsed and ignored (our accounting is exact); PURGE is a no-op (system allocator, no arena); DOCTOR and MALLOC-STATS return canned strings; STATS is a trimmed 8-field set
- `SAVE` [write,admin] — Synchronously snapshot the dataset to disk.
  - complexity: O(S) fan-out; O(N/S) copy-on-write freeze per shard
  - compat: differs: SAVE is no longer synchronous-until-durable — it freezes a copy-on-write view and replies OK immediately, so 'SAVE returned, therefore the dump is safe to copy' no longer holds
- `SHUTDOWN [NOSAVE|SAVE]` [write,admin] — Stop the server process (connection drops without a reply).
  - complexity: O(1) to trip the stop flag; the drain that follows is O(N)
  - compat: differs: only SHUTDOWN [NOSAVE|SAVE] parses — NOW, FORCE and ABORT are a syntax error
- `SLOWLOG GET [count] | LEN | RESET | HELP` [readonly,admin] — Inspect or reset the slow-command log.
  - complexity: GET: O(S) fan-out plus O(L log L) to merge. LEN: O(S). RESET: O(S)
  - compat: differs: the log is per-shard and GET merges across shards by timestamp, so ids are not globally monotonic; every entry's client-addr and client-name are empty strings

### replication

- `FAILOVER host port [TIMEOUT ms] | ABORT` [write,admin] — Planned zero-loss handover: quiesce writes, wait for the target replica to drain, promote it, and follow it.
  - complexity: O(1) at the command — the handover runs in the background, polling the target until it is caught up
  - compat: differs: Redis's syntax is FAILOVER [TO host port [FORCE]] [ABORT] [TIMEOUT ms] with an optional target; kevy's is FAILOVER host port [TIMEOUT ms] | ABORT — the target is mandatory and positional, and the port given is the target's client port
- `REPL.TOKEN` [readonly,extension] — kevy extension: mint a read-your-writes token — per-shard [generation, offset] pairs (a primary reports its live feed tail; a replica its applied positions).
  - complexity: O(S) — one (generation, offset) pair per shard
  - compat: kevy-only: the read-your-writes token; the nearest Redis concept is master_repl_offset, which is not a resumable per-shard cursor
- `REPL.WAIT gen offset [gen offset ...] [TIMEOUT milliseconds]` [readonly,blocking,extension] — kevy extension: on a replica, block until every shard has applied the given REPL.TOKEN (then reads are read-your-writes); +OK on success, -MISDIRECTED writer is <primary> on timeout or generation mismatch. Default TIMEOUT 1000 ms, hard cap 60 s. On a primary: immediate +OK.
  - complexity: O(S) — a barrier, not a keyspace op; the wall-clock cost is the replication lag, bounded by TIMEOUT (default 1s, hard-capped at 60s)
  - compat: kevy-only: waits until a (generation, offset) token has been applied, which is what makes read-your-writes possible across a failover
- `REPLICAOF host port | NO ONE` [write,admin] — Make this server a replica of another, or promote it with NO ONE.
  - complexity: O(1) at the command; the full resync that follows is O(N) in the background
  - compat: differs: the port argument is the primary's REPLICATION port base, not its client port (the default base is client port + 10000); chain replication is rejected
- `ROLE` [readonly] — Report the replication role and state of this server.
  - complexity: O(1) on a replica; O(R) on a primary
  - compat: full
- `SLAVEOF host port | NO ONE` [write,admin] — Legacy alias of REPLICAOF.
  - complexity: O(1) plus a background resync
  - compat: differs: a deprecated alias of REPLICAOF, including the replication-port-base argument
- `WAIT numreplicas timeout` [readonly,blocking] — Block until every shard's master_repl_offset is acknowledged by at least numreplicas replicas (or timeout ms pass); returns the minimum acked-replica count across shards. timeout 0 = wait forever, hard-capped at 60 s. NOTE: a replica ACK is not fsync durability.
  - complexity: O(S) — an all-shard barrier returning the MINIMUM acked-replica count; the wall-clock cost is the replication round trip
  - compat: differs: it is an all-shard barrier returning the minimum across shards (Redis has one offset to wait on); timeout 0 is capped at 60s rather than blocking forever, and an ACK means the frame reached the replica's apply pipeline, not fsync durability

### tx

- `DISCARD` [readonly,transaction] — Abort the open MULTI transaction.
  - complexity: O(1) — drops the queued commands and the WATCH set
  - compat: full
- `EXEC` [readonly,transaction] — Execute every command queued since MULTI.
  - complexity: O(sum of the queued commands' costs); with W watched keys, one extra O(W) pre-check fanned into O(min(W,S)) messages
  - compat: differs: a MULTI batch spanning several shards is per-shard-atomic, not globally isolated (there is no cross-shard snapshot); a queue-time error aborts the whole batch with EXECABORT, but a runtime error inside EXEC leaves the other commands applied, as in Redis
- `MULTI` [readonly,transaction] — Start a transaction; subsequent commands are queued until EXEC.
  - complexity: O(1)
  - compat: full
- `UNWATCH` [readonly,transaction] — Forget all watched keys.
  - complexity: O(1)
  - compat: full
- `WATCH key [key ...]` [readonly,transaction] — Watch keys for optimistic locking of the next EXEC.
  - complexity: O(W) keys, grouped into O(min(W,S)) cross-shard messages
  - compat: full

### pubsub

- `PSUBSCRIBE pattern [pattern ...]` [readonly,pubsub] — Subscribe to channels matching the given glob patterns.
  - complexity: O(p * P) — each pattern costs a linear scan of the shared pattern registry
  - compat: full
- `PUBLISH channel message` [readonly,pubsub] — Post a message to a channel; returns the receiver count.
  - complexity: O(1) channel lookup + O(P) — a linear walk of the registered patterns with one glob match each, even when none match. Delivery fans out only to the shards holding a subscriber
  - compat: full
- `PUNSUBSCRIBE [pattern [pattern ...]]` [readonly,pubsub] — Unsubscribe from patterns (all patterns when none given).
  - complexity: O(p * P)
  - compat: full
- `SUBSCRIBE channel [channel ...]` [readonly,pubsub] — Subscribe to the given channels.
  - complexity: O(c) channels; never fans out to other shards
  - compat: differs: kevy has no RESP2 subscriber mode — after SUBSCRIBE the connection may still issue any command, where Redis restricts it to the pubsub verbs plus PING / QUIT / RESET
- `UNSUBSCRIBE [channel [channel ...]]` [readonly,pubsub] — Unsubscribe from channels (all channels when none given).
  - complexity: O(c) channels
  - compat: full

### script

- `EVAL script numkeys [key [key ...]] [arg [arg ...]]` [write] — Run a Lua script server-side; routed to KEYS[1]'s shard when numkeys >= 1.
  - complexity: O(compile + the script's own work). The whole script is one atomic unit on KEYS[1]'s shard and blocks that shard for its duration. The runaway guard is an INSTRUCTION budget (lua time_limit_ms x 40000 instructions), not a wall clock
  - compat: differs: there is no -BUSY state and no SCRIPT KILL — an over-budget script is aborted in place and answered with an ordinary error; nested EVAL is rejected, a redis.call touching another shard's key returns CROSSSLOT, and EVAL auto-caches its source by SHA1 so EVALSHA works without SCRIPT LOAD
- `EVALSHA sha1 numkeys [key [key ...]] [arg [arg ...]]` [write] — Run a cached Lua script by its SHA1 digest.
  - complexity: O(1) cache lookup, then identical to EVAL
  - compat: differs: same instruction-budget model as EVAL (no -BUSY, no SCRIPT KILL); the cache is process-wide and EVAL populates it
- `SCRIPT LOAD script | EXISTS sha1 [sha1 ...] | FLUSH [ASYNC|SYNC]` [readonly] — Manage the process-wide Lua script cache.
  - complexity: LOAD: O(len(script)). EXISTS: O(k). FLUSH: O(cached scripts)
  - compat: differs: LOAD / EXISTS / FLUSH only — SCRIPT KILL does not exist, by design: there is no -BUSY state to interrupt because an over-budget script self-aborts

### index

- `IDX.COUNT name RANGE min max | EQ value` [readonly,extension] — Count index entries matching a range or equality predicate.
  - complexity: O(log N + matched) per shard — NOT an O(1) counter and not a B-tree rank query; it counts the matched range
  - compat: kevy-only: nearest is FT.SEARCH with LIMIT 0 0
- `IDX.CREATE name ON PREFIX prefix FIELD field TYPE i64|f64|str|vector KIND range|unique|text|ann|agg [MAXMEM bytes] [DIM dim] [DISTANCE cosine|l2|ip] [M m] [EF ef] [GROUPBY field]` [write,extension] — Declare a secondary index over a key prefix (catalog mutation, sidecar-persisted).
  - complexity: O(1) at the call; the build is asynchronous — each shard snapshots its matching keys (O(keys on that shard)) then backfills 2048 rows per tick. Per-row build cost: range/unique O(log N), text O(tokens), vector O(ef_construction * M * dim)
  - compat: kevy-only: nearest is RediSearch FT.CREATE — comparable declarative index-on-prefix, but RediSearch is a separate module with its own index server; kevy's catalog is in-process and the index is maintained in the write hook
- `IDX.DROP name` [write,extension] — Drop a declared index (catalog mutation, sidecar-persisted).
  - complexity: O(catalog size)
  - compat: kevy-only: nearest is FT.DROPINDEX
- `IDX.LIST` [readonly,extension] — List declared indexes with per-index build state and stats.
  - complexity: Not O(1) — per shard, per index it computes live stats: range/unique O(1), text O(distinct tokens + docs), vector O(nodes + links), agg O(groups + rows)
  - compat: kevy-only: nearest is FT._LIST plus FT.INFO combined
- `IDX.EXPLAIN name RANGE min max|EQ value|MATCH text|KNN vector|GROUPS [args ...]` [readonly,extension] — The IDX.QUERY parse without the execution: kind, state, est_rows, and the plan line.
  - complexity: The plan is parse-only, but est_rows costs the same live stats walk as IDX.LIST
  - compat: kevy-only: nearest is FT.EXPLAIN, which returns a parsed query tree; ours returns kind, build state, estimated rows and a one-line plan
- `IDX.QUERY name RANGE min max [LIMIT n] [CURSOR c] [FIELDS field ...] | name EQ value [LIMIT n] [CURSOR c] [FIELDS field ...] | name MATCH text [LIMIT n] [FIELDS field ...] | name KNN vector [LIMIT k] [EF ef] [FIELDS field ...] | name GROUP group | name GROUPS [BY count|sum|min|max] [LIMIT n] | HYBRID text_idx MATCH text ann_idx KNN vector [LIMIT n] [RRFK k] [EF ef] [FIELDS field ...] | COMPOSE AND|OR nameA RANGE min max|EQ value nameB RANGE min max|EQ value [LIMIT n] [CURSOR c] [FIELDS field ...]` [readonly,extension] — Query an index: range/equality, text MATCH, vector KNN, aggregation groups, or a two-index COMPOSE.
  - complexity: Depends on the index kind. range: O(log N + limit). unique: O(log N + hits). full-text: O(sum of the posting lists), MaxScore-pruned. vector ANN: O(dim * (M log N + ef * M)) distance evaluations (HNSW). agg GROUPS: a bounded top-K with 1 to 3 fan-out rounds. HYBRID: both sub-queries at 4x depth, fused by RRF at the origin. COMPOSE: NOT limit-bounded — both leaves are materialised in full, because the result is key-ordered while a segment is value-ordered
  - compat: kevy-only: nearest is RediSearch FT.SEARCH — genuinely comparable on two axes (our text index is BM25 over inverted segments, our vector index is HNSW, and RediSearch offers both). Differences: no separate module or index server; our BM25 statistics are per-shard, not global; and our query surface is a fixed grammar, not a DSL — no field boosting, no phrase or proximity search, no stemming, no aggregation pipeline
- `IDX.REBUILD name` [write,extension] — Rebuild an ANN index (tombstone compaction).
  - complexity: Vector indexes only (tombstone compaction). O(V_live * ef_construction * M * dim) distance evaluations, on every shard, synchronously — the most expensive verb in the extension surface
  - compat: kevy-only: no Redis analogue — RediSearch handles HNSW deletes internally and exposes no rebuild verb
- `IDX.VERIFY name` [readonly,extension] — Verify an index: re-read every held entry against its row and report entries/bytes/coerce_failures/duplicates/drift/checked.
  - complexity: O(N) per shard — every held entry is re-read against its row and re-coerced, which is the point: it makes index drift falsifiable rather than merely asserted
  - compat: kevy-only: no Redis analogue — RediSearch's index is asynchronously maintained and offers no consistency-verify verb

### view

- `VIEW.CREATE name QUERY tree ORDER BY index [DESC] [MODE virtual|materialized] [TOPK k] [VIA template] (tree = '( AND|OR|DIFF sub sub )' | 'index RANGE min max' | 'index EQ value')` [write,extension] — Declare a composed view over indexes with an ORDER BY (catalog mutation, sidecar-persisted).
  - complexity: O(tree size) at the call. A materialized view builds lazily on the next tick (a full eval_tree plus an O(M log M) sort); a virtual view builds nothing, ever
  - compat: kevy-only: no Redis analogue. A view is neither a stored query nor a join — it is a named composition tree over declared indexes that stores membership and order only, never field values
- `VIEW.DROP name` [write,extension] — Drop a declared view (catalog mutation, sidecar-persisted).
  - complexity: O(catalog size)
  - compat: kevy-only
- `VIEW.EXPLAIN name` [readonly,extension] — Explain a view's composition tree with per-leaf cardinalities.
  - complexity: O(sum over leaves of (log N + matched)) — each leaf's cardinality is a real count, so EXPLAIN on a broad leaf costs as much as counting it
  - compat: kevy-only: nearest is FT.EXPLAIN, which returns a query tree rather than per-leaf cardinalities
- `VIEW.LIST` [readonly,extension] — List declared views with their mode and shape.
  - complexity: O(views) at the origin — the catalog is process-global
  - compat: kevy-only
- `VIEW.QUERY name [LIMIT n] [CURSOR c] [FIELDS field ...]` [readonly,extension] — Page through a view's ordered members, optionally hydrating fields via the VIA template.
  - complexity: virtual: O(log N_order + candidates * leaves) — it streams the ORDER index and probes membership per candidate, stopping at the limit, so it never materialises the member set. materialized: O(log M + limit). Adding FIELDS with VIA costs a SECOND fan-out to hydrate the rows
  - compat: kevy-only: no Redis analogue. Absent by construction: no joins, no predicates at the view layer, no projection from the view itself, no HAVING, no aggregation
- `VIEW.REBUILD name` [write,extension] — Force a rebuild of a materialized view.
  - complexity: Materialized only. A full eval_tree over the whole tree plus an O(M log M) sort and re-insert, on every shard, now (not deferred to a tick)
  - compat: kevy-only
- `VIEW.VERIFY name` [readonly,extension] — Verify a view and report member/byte statistics.
  - complexity: materialized: O(M). virtual: O(sum over leaves of (log N + leaf range) + M) — a full fresh evaluation just to report cardinality, which is the one place a virtual view is the expensive one
  - compat: kevy-only

### feed

- `FEED.READ shard generation offset [COUNT n] [PREFIX prefix ...]` [readonly,extension] — Read change-feed frames from one shard past a generation/offset cursor.
  - complexity: A single shard (the shard is an argument, not a fan-out). O(log B) to locate the start offset in the backlog plus O(count * frame size) to decode and re-encode. COUNT defaults to 256 and is hard-capped at 4096
  - compat: kevy-only: no clean Redis analogue. Keyspace notifications are fire-and-forget with no cursor and no replay; Redis Streams have cursors but are a stream you must dual-write to, not a feed over your existing keyspace; the replication backlog is what this is built on, but Redis exposes it only to replicas. kevy is deliberately not a broker: no consumer groups, no server-side positions, no global cross-shard order
- `FEED.SHARDS` [readonly,extension] — Return the number of change-feed shards.
  - complexity: O(1), answered locally
  - compat: kevy-only: Redis has no shard-partitioned change feed to enumerate
- `FEED.TAIL shard` [readonly,extension] — Return a shard's current feed generation and next offset.
  - complexity: O(1) on a single shard
  - compat: kevy-only: nearest is INFO replication's master_repl_offset, which is not a resumable per-shard CDC cursor

### migration

- `PREFIX.STATS prefix` [readonly,extension] — Report key-count and byte statistics for a key prefix.
  - complexity: O(keys on the shard) — a full keyspace walk on every shard; the prefix cannot be precomputed
  - compat: kevy-only: nearest is INFO keyspace's db0:keys=N,expires=M — the same two counters, but whole-DB and O(1) off a counter, where ours is per-prefix and therefore O(keyspace)
- `PREFIX.DIGEST prefix` [readonly,extension] — Order-insensitive checksum of a prefix's rows for migration verification.
  - complexity: O(keys on the shard) to walk plus O(sum of row sizes) to digest, on every shard. Per-row digests XOR together, so the result is order-insensitive and safe across shard counts
  - compat: kevy-only: nearest is DEBUG DIGEST — comparable in kind (Redis also XORs per-key digests), but Redis's is whole-DB and lives behind DEBUG, while ours is per-prefix (the unit a migration actually cares about) and is a supported verb


==============================================================================
# FULL DOCUMENTATION
==============================================================================

Everything below is the complete text of kevy's documentation, in the order
an assistant should read it. The first three documents matter most: they are
what stops you from writing Redis code that compiles here and then behaves
differently.


==============================================================================
# designing-on-kevy
==============================================================================

# Designing your application on kevy

kevy is a **serving engine**: the primary data store for
applications that would otherwise put their operational model on a
relational database and cache in front of it. This page is the map —
what the engine gives you, the laws that bound it, and where each
capability lives.

If you're migrating from an RDS, read this page first, then work
through [the cookbook](https://kevy.golia.jp/docs/cookbook/) recipe by recipe.

## The seven planes

| Plane | What it carries | Where |
|---|---|---|
| **P0 — Operations** | Every op on every surface: server (RESP), embedded (in-process), Lua, atomic blocks, pipelines. One OP_TABLE, CI-enforced parity. | docs/verb-reference.md |
| **P1 — Atomicity & durability** | Single-shard atomic blocks, deterministic-order all-shard blocks, appendfsync × atomic-commit matrix, per-block fsync barriers. | docs/persistence.md |
| **P2 — Indexes** | Declared secondary indexes, four kinds: `range`, `unique`, `text` (CJK bigram + BM25), `ann` (HNSW). Derived-by-construction (write-hook maintained, zero drift), one-hop hydration (`FIELDS`), backfill rebuild. | docs/indexes.md, docs/text-search.md, docs/vector-search.md |
| **P3 — Views & algebra** | Named compositions over indexes (virtual / materialized top-K), zset/set algebra with full Redis semantics. | docs/views.md |
| **P4 — Flow** | CDC feed with `(generation, offset)` cursors (the built-in outbox), blocking pops, hash-field TTLs, snapshot read views, the embedded read-only RESP listener. | docs/cdc.md, docs/embedded-listener.md |
| **P5 — Evidence** | Every declared line measured and reconciled; crash-consistency chaos gates; 30M-key mixed-stack soak. | bench/VALIDATION-LEDGER.md |
| **P6 — Availability** | Replication with acked-offset truth and heartbeats, planned handover (`FAILOVER`) and crash failover (quorum election, election-only write authority, fork discard), and the opt-in consistency ladder: `WAIT`, read-your-writes tokens (`REPL.TOKEN`/`REPL.WAIT`), bounded staleness (`-STALE`), quorum-lease write fencing. 13 executable clamps (availgate) run in CI. | docs/availability.md, docs/replication.md |

## The three laws

The constitution that kept — and keeps — kevy from sliding into
being a worse RDS:

**Law 1 — The Redis contract is inviolable.** Every Redis op kevy
implements behaves exactly like Redis. New-genre capability never
changes the semantics of an existing verb, never leaks internal
keyspace into `SCAN`/`KEYS`/`DBSIZE`, and lives in its own command
namespaces (`IDX.*`, `VIEW.*`, `FEED.*`, `PREFIX.*`).

**Law 2 — Superset only when it is engine-genre.** A capability gets
in only if it is derived data with a lifecycle the engine can own:
declare → maintain → verify → rebuild. Indexes, views, feeds and
digests all pass that test. Stored app logic doesn't.

**Law 3 — The RDS event horizon.** No query language, no planner, no
joins, no server-side validation, no triggers. The moment the engine
starts *deciding* how to answer a question instead of *executing a
declared access path*, it's an RDS — a worse one. kevy stays on this
side of the horizon permanently.

## Considered and refused

Each of these has a covered answer — the need is real, the feature
is the wrong shape:

| You might ask for | Use instead |
|---|---|
| SQL / query DSL | explicit index APIs + [cookbook](https://kevy.golia.jp/docs/cookbook/) |
| Query planner / auto index selection | `IDX.EXPLAIN` (diagnostic only) |
| Joins | one-hop hydration (`FIELDS`, `VIA`) + app-side assembly |
| Foreign keys / cascades | atomic blocks, prefix bulk ops, CDC consumers |
| CHECK constraints | reads inside atomic blocks (app evaluates, engine commits atomically) |
| Schema / typed columns | bytes are yours; types declared at index creation |
| JSON-path queries | hash fields ARE the column model |
| Triggers / write-path UDFs | CDC consumers — after commit, decoupled, replayable |
| GROUP BY / aggregation pipelines | maintain aggregates at write time in your model |
| Time travel | snapshots + CDC retention (recovery-point contract) |
| Transactional outbox | unnecessary — the feed IS the outbox |
| WHERE without an index | deliberately absent: model the access path or don't ship it |

## The serving charter (what's gated, forever)

Numbers are ratchets — floors only rise. The standing lines
(measured values in `bench/VALIDATION-LEDGER.md`):

- Redis-parity throughput: 12-angle perfgate, floor = baseline×0.92.
- Hydrated row-list page p99 < 1ms; view page < 1ms; write fan-out
  through index+view hooks p99 < 200µs — on one server carrying the
  full stack.
- IDX.QUERY p99 < 2ms @ 1M rows; MATCH p95 < 20ms @ 1M docs;
  KNN p95 < 30ms with recall@10 ≥ 0.90 @ 1M×128d.
- Crash honesty: kill -9 mid-write → replay → derived state identical
  to a fresh rebuild. Restore point = snapshot + `(gen, offset)`.
- Empty catalogs cost nothing: every subsystem gates a zero-tax line.

## Where to start

1. Model your prefixes and access paths ([cookbook §1-2](https://kevy.golia.jp/docs/cookbook/)).
2. Bulk load, then declare indexes ([migration guide](https://kevy.golia.jp/docs/migration/)).
3. Compose views for your hot lists ([views](https://kevy.golia.jp/docs/views/)).
4. Wire your event consumers to the feed ([CDC](https://kevy.golia.jp/docs/cdc/)).
5. Verify with digests, watch the gates.
6. When one node stops being enough, add replicas and pick your rung
   on the consistency ladder ([availability](https://kevy.golia.jp/docs/availability/)).

==============================================================================
# cookbook
==============================================================================

# The RDS→kevy modeling cookbook

You are moving a relational data model onto kevy. Every recipe below
uses shipped primitives — no roadmap features, no "coming soon". Each
one names the RDS concept it replaces and the kevy pattern that
carries it.

The design stance behind all of them: **model the access paths, not
the schema**. An RDS lets you defer that decision to a query planner;
kevy makes you state it — and pays you back with microsecond pages
at serving time (`bench/VALIDATION-LEDGER.md` has the measured
numbers).

Every command block runs as-is against a fresh local kevy
(`kevy --port 6004`; recipes 11–14, 16 and 20 additionally want
`[feed] enabled = true` in `kevy.toml` — see docs/cdc.md).
`bench/cookbook_smoke.sh` executes every `kevy-cli` line below
against a throwaway server, so the blocks stay honest.

## 1. Tables and rows

**SQL equivalent:** `CREATE TABLE` + `SELECT col FROM t WHERE id = ?`
— [matrix: tables, rows, columns](https://kevy.golia.jp/docs/rds-workloads/#tables-rows-columns).

A row is a hash under a typed prefix:

```console
kevy-cli -p 6004 HSET user:42 name ada email ada@example.com age 36
kevy-cli -p 6004 HGET user:42 name
kevy-cli -p 6004 HGET user:42 phone    # NULL = absent field: already answers (nil)
```

- Table → key prefix (`user:`). Column → hash field. Primary key →
  the key itself.
- **NULL = absent field.** Don't store sentinel strings; `HGET` of a
  missing field already answers nil, and index specs treat a missing
  field as "row excluded" (visible in `IDX.VERIFY` counts).
- Column types are yours: kevy stores bytes. Declare types where they
  matter — at index creation (`TYPE i64|f64|str|vector`); coercion
  failures are counted, never silently indexed.

## 2. One-to-many, many-to-many

**SQL equivalent:** foreign-key columns + junction tables;
`SELECT … FROM orders WHERE user_id = ?` —
[matrix: JOIN](https://kevy.golia.jp/docs/rds-workloads/#join).

Link keys carry the relation, one set per side:

```console
kevy-cli -p 6004 HSET order:1001 user_id 42 total 1999 status shipped
kevy-cli -p 6004 HSET order:1002 user_id 42 total 550 status pending
kevy-cli -p 6004 SADD user:42:orders 1001 1002       # 1-N: member = order id
kevy-cli -p 6004 RPUSH order:1001:items sku-7 sku-9
kevy-cli -p 6004 SADD tag:urgent:orders 1001         # N-M: one set per side
kevy-cli -p 6004 SADD order:1001:tags urgent
```

Or skip the link keys entirely: put the foreign key in the row
(`user_id` above) and declare an index — `IDX.QUERY … EQ 42` is the
`SELECT … WHERE user_id = 42` of this world, hydrated in one hop:

```console
kevy-cli -p 6004 IDX.CREATE order_user ON PREFIX order: FIELD user_id TYPE i64 KIND range
kevy-cli -p 6004 IDX.QUERY order_user EQ 42 FIELDS total status
```

## 3. Sequences

**SQL equivalent:** `AUTO_INCREMENT` / `CREATE SEQUENCE` + `nextval()`
— [matrix: primary key, unique, auto_increment](https://kevy.golia.jp/docs/rds-workloads/#primary-key-unique-auto_increment).

```console
kevy-cli -p 6004 INCR seq:order          # one id
kevy-cli -p 6004 INCRBY seq:order 100    # block allocation: hand out 100 ids
                                         # from app memory, refill when dry
```

Block allocation is the high-throughput form; gaps on crash are the
same contract PostgreSQL sequences give you.

## 4. Optimistic locking (row versions)

**SQL equivalent:** `UPDATE t SET …, version = v+1 WHERE id = ? AND
version = v` (the version-column CAS) —
[matrix: transactions](https://kevy.golia.jp/docs/rds-workloads/#transactions).

Server: WATCH/MULTI — the CAS loop. The transaction is
connection-scoped, so it runs in one REPL session (here fed by a
heredoc):

```bash
kevy-cli -p 6004 HSET user:42 balance 100 version 7
kevy-cli -p 6004 <<'TXN'
WATCH user:42
HGET user:42 version
MULTI
HSET user:42 balance 90 version 8
EXEC
TXN
```

`EXEC` answers nil when somebody else touched `user:42` after the
`WATCH` — somebody won the race; re-read and retry.

Embedded: run the read-decide-write inside one `atomic()` block —
the shard lock makes the branch race-free without a retry loop.

## 5. CHECK constraints and multi-key invariants

**SQL equivalent:** `CHECK (balance >= 0)` + a trigger-maintained
audit row — [matrix: constraints and triggers](https://kevy.golia.jp/docs/rds-workloads/#constraints-and-triggers).

The RDS runs `CHECK (balance >= 0)` in the engine. kevy's replacement
is **reads inside the atomic block**: the app evaluates the
invariant, the engine guarantees the decision and the write commit
together.

```rust
// embedded — debit that must not overdraw, plus an audit row:
store.atomic(b"acct:7", |ctx| {
    let bal: i64 = parse(ctx.hget(b"acct:7", b"balance")?);
    if bal < amount { return Err(Overdraw); }
    ctx.hset(b"acct:7", &[(b"balance", &(bal - amount))])?;
    ctx.rpush(b"acct:7:ledger", &[entry])?;
    Ok(())
})
```

Cross-shard invariants: `atomic_all_shards` (deterministic lock
order, documented deadlock exemption). Use sparingly — it is the
serializable-transaction hammer, and most invariants live under one
key prefix by design.

## 6. Idempotency keys

**SQL equivalent:** `UNIQUE INDEX` + `INSERT … ON CONFLICT DO NOTHING`
— [matrix: primary key, unique, auto_increment](https://kevy.golia.jp/docs/rds-workloads/#primary-key-unique-auto_increment).

```console
kevy-cli -p 6004 HSET req:9001 idem_key pay-2026-07-04-a77 amount 1999
kevy-cli -p 6004 IDX.CREATE req_idem ON PREFIX req: FIELD idem_key TYPE str KIND unique
kevy-cli -p 6004 IDX.QUERY req_idem EQ pay-2026-07-04-a77   # duplicates are visible as multi-hit reads
kevy-cli -p 6004 IDX.VERIFY req_idem                        # ...and counted here
kevy-cli -p 6004 SET idem:pay-2026-07-04-a77 1 NX PX 86400000
```

Write the row, then query — duplicates are *visible* (the unique
kind counts them in VERIFY rather than rejecting writes; declarative
fence, not a write gate). For a hard gate use the `SET … NX PX` form
before processing: NX is the atomic claim, the TTL is the retention
window.

## 7. Soft delete

**SQL equivalent:** a `deleted` flag column + a partial index / view
`WHERE deleted = 0` — [matrix: VIEW](https://kevy.golia.jp/docs/rds-workloads/#view).

Flag, don't remove:

```console
kevy-cli -p 6004 HSET user:42 deleted 0 age 36
kevy-cli -p 6004 HSET user:43 deleted 1 age 51
kevy-cli -p 6004 IDX.CREATE user_live ON PREFIX user: FIELD deleted TYPE i64 KIND range
kevy-cli -p 6004 IDX.QUERY user_live EQ 0 LIMIT 100    # live rows only
```

Views compose it away permanently — callers never re-state the
filter:

```console
kevy-cli -p 6004 IDX.CREATE user_age ON PREFIX user: FIELD age TYPE i64 KIND range
kevy-cli -p 6004 VIEW.CREATE live_users QUERY '(' AND user_live EQ 0 user_age RANGE 18 200 ')' ORDER BY user_age
kevy-cli -p 6004 VIEW.QUERY live_users LIMIT 10
```

## 8. Composite ordering (ORDER BY a, b)

**SQL equivalent:** `ORDER BY a, b` on a composite index —
[matrix: ORDER BY / LIMIT / OFFSET](https://kevy.golia.jp/docs/rds-workloads/#order-by--limit--offset).

Encode the composite into one indexed score field at write time:
`score = a * 1_000_000 + b` for bounded integer `b`, or a
zero-padded string field for lexicographic composites — one index,
one ORDER BY; the write hook maintains it like any field:

```console
kevy-cli -p 6004 HSET evt:1 ord '2026-07-04|000042'
kevy-cli -p 6004 HSET evt:2 ord '2026-07-04|000007'
kevy-cli -p 6004 HSET evt:3 ord '2026-07-05|000001'
kevy-cli -p 6004 IDX.CREATE evt_ord ON PREFIX evt: FIELD ord TYPE str KIND range
kevy-cli -p 6004 IDX.QUERY evt_ord RANGE '2026-07-04|000000' '2026-07-04|999999' LIMIT 100
```

## 9. JSONB

**SQL equivalent:** a JSON/JSONB column with generated-column indexes
— [matrix: type system](https://kevy.golia.jp/docs/rds-workloads/#type-system).

Flatten to hash fields: `profile.city` → field `profile.city`. You
keep per-field reads/writes, field TTLs (HEXPIRE), and indexability —
everything JSONB gave you except JSON-path queries, which are
**permanently out** (query-engine slope; see the REFUSED table in
docs/designing-on-kevy.md).

```console
kevy-cli -p 6004 HSET user:7 profile.city tokyo profile.plan pro
kevy-cli -p 6004 HGET user:7 profile.city
kevy-cli -p 6004 HEXPIRE user:7 3600 FIELDS 1 profile.plan   # per-field TTL survives the flattening
```

A deeply nested blob nobody indexes can stay one serialized field;
the moment a path matters, promote it to a field.

## 10. Cascade delete / foreign keys

**SQL equivalent:** `FOREIGN KEY … ON DELETE CASCADE` —
[matrix: constraints and triggers](https://kevy.golia.jp/docs/rds-workloads/#constraints-and-triggers).

Cascades are app patterns, never engine magic:

- Synchronous, small blast radius: delete inside one atomic block
  (`ctx.del(row)`, `ctx.srem(parent_link, id)`).
- Bulk / prefix-shaped: `delete-prefix` — rate-limited, resumable.
- Asynchronous: a CDC consumer (`FEED.READ` with `PREFIX`) reacts to
  parent deletes and cleans children — the trigger replacement, after
  commit, decoupled, replayable.

```console
kevy-cli -p 6004 HSET order:1001 user_id 42
kevy-cli -p 6004 RPUSH order:1001:items sku-7 sku-9
kevy-cli -p 6004 SADD order:1001:tags urgent
kevy-cli delete-prefix -p 6004 --rate 5000 order:1001:   # children gone, parent row stays
```

## 11. The outbox you don't need

**SQL equivalent:** the transactional-outbox table + relay worker —
[matrix: CDC](https://kevy.golia.jp/docs/rds-workloads/#cdc).

The transactional-outbox pattern exists because an RDS commit and a
message-bus publish can't be atomic. In kevy **the feed is the
outbox**: every committed write is already a change frame at a
`(generation, offset)` cursor, at-least-once, prefix-filterable
(docs/cdc.md). Consume `FEED.READ`; don't build a second journal.

```console
# needs [feed] enabled = true in kevy.toml (docs/cdc.md)
kevy-cli -p 6004 HSET order:9001 status paid
kevy-cli -p 6004 FEED.SHARDS
kevy-cli -p 6004 FEED.TAIL 0                             # a fresh consumer's starting cursor
kevy-cli -p 6004 FEED.READ 0 1 0 COUNT 10 PREFIX order:  # gen 1 = a fresh data dir's first generation
```

## 12. Audit history

**SQL equivalent:** a trigger-maintained audit/history table (or
binlog archaeology) — [matrix: CDC](https://kevy.golia.jp/docs/rds-workloads/#cdc).

CDC retention IS the audit log: frames carry the applied effect argv
in commit order. Size the feed backlog for the window you owe
compliance, export to cold storage with a cursor consumer. For
point-in-time reconstruction: restore snapshot + replay to the
`(gen, offset)` recovery point (docs/persistence.md).

```console
kevy-cli -p 6004 HSET acct:7 balance 100
kevy-cli -p 6004 HSET acct:7 balance 90
kevy-cli -p 6004 FEED.READ 0 1 0 COUNT 100 PREFIX acct:   # who set what, in commit order
```

## 13. The rollback window (reverse mirror)

**SQL equivalent:** reverse replication back to the old primary
during a cutover — [migration playbook, phase 5](https://kevy.golia.jp/docs/migration/#phase-5--write-cutover--the-rollback-window).

During cutover, run a CDC consumer that mirrors kevy writes BACK to
the old RDS (`FEED.READ` → UPDATE statements). Your rollback plan is
then "repoint the app", not "reverse-migrate data". Decommission the
mirror when confidence hardens; `kevy-cli diff` (per-prefix digests)
is the confidence meter.

```console
kevy-cli -p 6004 HSET user:42 name ada
kevy-cli -p 6004 FEED.READ 0 1 0 COUNT 10 PREFIX user:   # the mirror consumer's read loop
kevy-cli diff 127.0.0.1:6004 127.0.0.1:6004 user:        # digests match: safe form of the check
kevy-cli diff old-rds-mirror.internal:6379 127.0.0.1:6004 user:   # needs-external
```

## 14. Analytics export

**SQL equivalent:** the ETL job / binlog tap feeding the warehouse —
[matrix: CDC](https://kevy.golia.jp/docs/rds-workloads/#cdc).

Serving and analytics don't share an engine. Export patterns:

- `export` — logical, resumable, loadable anywhere RESP goes.
- CDC → warehouse: a cursor consumer streaming inserts to your OLAP
  store, exactly the CDC-to-Kafka shape.
- Read-only listener (`docs/embedded-listener.md`) for ad-hoc pulls
  from embedded apps.

```console
kevy-cli -p 6004 HSET order:1001 user_id 42 total 1999
kevy-cli export -p 6004 --prefix order: /tmp/orders.resp
kevy-cli -p 6004 FEED.READ 0 1 0 COUNT 100 PREFIX order:   # the CDC-to-warehouse read loop
```

## 15. Loading order (the deferred-index rule)

**SQL equivalent:** `LOAD DATA` first, `CREATE INDEX` after (the
bulk-load discipline) — [matrix: secondary index DDL](https://kevy.golia.jp/docs/rds-workloads/#secondary-index-ddl).

Bulk load FIRST, declare indexes/views AFTER: backfill builds from
existing rows at ~7s/million — orders of magnitude cheaper than
paying the write hook per imported row (docs/migration.md).

```console
kevy-cli -p 6004 HSET item:1 price 10
kevy-cli -p 6004 HSET item:2 price 25
kevy-cli -p 6004 HSET item:3 price 7
kevy-cli export -p 6004 --prefix item: /tmp/items.resp
kevy-cli import -p 6004 /tmp/items.resp   # bulk load FIRST: no index write hook to pay
kevy-cli -p 6004 IDX.CREATE item_price ON PREFIX item: FIELD price TYPE i64 KIND range   # declare AFTER: backfill
kevy-cli -p 6004 IDX.QUERY item_price RANGE 0 100 LIMIT 10
```

---

The last three recipes swap the workload: not an RDS being replaced
but an AI agent's memory stack. Nothing new is needed — session
state, episodic memory and RAG retrieval are the same access-path
patterns wearing different key prefixes.

## 16. Session context with TTL

**SQL equivalent:** a sessions table + the expiry cron job —
[matrix: operational deltas](https://kevy.golia.jp/docs/rds-workloads/#sizing-and-operational-deltas).

An agent's working context is a row with a lease: the compacted
conversation lives in a hash, `EXPIRE` is the idle-eviction policy
(renewed every turn — a sliding window), and the feed is the audit
trail you replay when someone asks what the agent knew at turn 7.

```console
# needs [feed] enabled = true in kevy.toml (docs/cdc.md)
kevy-cli -p 6004 HSET session:a7 user 42 turns 6 messages 'wants refund for order 1001; tone calm' last_tool order_lookup
kevy-cli -p 6004 EXPIRE session:a7 3600
kevy-cli -p 6004 HSET session:a7 turns 7 messages 'refund approved; awaiting confirmation'
kevy-cli -p 6004 EXPIRE session:a7 3600                       # renew the lease on every turn
kevy-cli -p 6004 FEED.TAIL 0                                  # audit cursor: where the log ends now
kevy-cli -p 6004 FEED.READ 0 1 0 COUNT 100 PREFIX session:    # gen 1 = a fresh data dir's first generation
```

The `messages` field holds whatever summary your compaction step
produces; rewriting it is one `HSET`, and every revision is already
a change frame in commit order — the "conversation history" table
most agent frameworks bolt on is recipe 12's audit log for free.

## 17. Episodic memory (time × semantic)

**SQL equivalent:** `WHERE ts BETWEEN …` + pgvector
`ORDER BY embedding <=> ? LIMIT k` — [matrix: SELECT](https://kevy.golia.jp/docs/rds-workloads/#select).

Episodic memory answers two questions about the same rows: *what
happened recently* (time) and *what resembles this* (meaning). One
prefix, one index per question — `DIM 8` keeps the demo readable;
real embeddings are 768+ dimensions shipped as f32-LE blobs, and the
`csv:` debug form below is accepted everywhere a vector is (stored
fields and query vectors go through the same parser —
docs/vector-search.md).

```console
kevy-cli -p 6004 HSET mem:1 ts 1783200000 kind obs what 'user prefers dark roast' v csv:0.9,0.1,0,0,0,0,0,0
kevy-cli -p 6004 HSET mem:2 ts 1783203600 kind obs what 'user asked about decaf' v csv:0.8,0.3,0.1,0,0,0,0,0
kevy-cli -p 6004 HSET mem:3 ts 1783207200 kind reflection what 'coffee questions cluster in the morning' v csv:0,0.2,0.9,0.1,0,0,0,0
kevy-cli -p 6004 IDX.CREATE mem_ts ON PREFIX mem: FIELD ts TYPE i64 KIND range
kevy-cli -p 6004 IDX.CREATE mem_kind ON PREFIX mem: FIELD kind TYPE str KIND range
kevy-cli -p 6004 IDX.CREATE mem_ann ON PREFIX mem: FIELD v TYPE vector KIND ann DIM 8
kevy-cli -p 6004 IDX.QUERY mem_ts RANGE 1783203000 1783210000 LIMIT 10 FIELDS what      # recent memories
kevy-cli -p 6004 IDX.QUERY mem_ann KNN csv:0.85,0.2,0,0,0,0,0,0 LIMIT 2 FIELDS what ts  # similar memories
kevy-cli -p 6004 IDX.QUERY COMPOSE AND mem_ts RANGE 1783203000 1783210000 mem_kind EQ reflection LIMIT 10 FIELDS what
```

`COMPOSE AND` conjoins scalar legs (`RANGE`/`EQ`) — here "in this
time window AND a reflection". For *similar within a window* there
is deliberately no KNN leg (filtering inside the graph walk is the
query-engine slope, REFUSED): run the KNN with headroom on `LIMIT`,
hydrate `ts` via `FIELDS` as above, and drop out-of-window hits
client-side.

## 18. RAG chunks with hybrid retrieval

**SQL equivalent:** tsvector full-text + pgvector KNN, fused
app-side — [matrix: SELECT](https://kevy.golia.jp/docs/rds-workloads/#select).

Chunks are rows carrying both retrieval surfaces — the text and its
embedding — so one write maintains both indexes:

```console
kevy-cli -p 6004 HSET chunk:1 doc kevy-guide seq 1 body 'rows are hashes under a typed key prefix' v csv:1,0,0,0,0,0,0,0
kevy-cli -p 6004 HSET chunk:2 doc kevy-guide seq 2 body 'indexes are declared once and maintained by the write hook' v csv:0,1,0,0,0,0,0,0
kevy-cli -p 6004 HSET chunk:3 doc kevy-guide seq 3 body 'the feed streams every committed write as a change frame' v csv:0,0,1,0,0,0,0,0
kevy-cli -p 6004 IDX.CREATE chunk_text ON PREFIX chunk: FIELD body TYPE str KIND text
kevy-cli -p 6004 IDX.CREATE chunk_ann ON PREFIX chunk: FIELD v TYPE vector KIND ann DIM 8
kevy-cli -p 6004 IDX.QUERY HYBRID chunk_text MATCH 'typed key prefix' chunk_ann KNN csv:0.9,0.1,0.1,0,0,0,0,0 LIMIT 2 FIELDS body
kevy-cli -p 6004 IDX.QUERY HYBRID chunk_text MATCH 'change frame' chunk_ann KNN csv:0,0.1,0.9,0,0,0,0,0 LIMIT 2 RRFK 20 FIELDS body
```

`HYBRID` runs both legs server-side and fuses by **reciprocal-rank
fusion**: each key scores `Σ 1/(k + rank)` across the BM25 list and
the KNN list — rank-only, so the two heterogeneous score scales
never need normalizing, and a chunk near the top of *both* legs
beats a chunk that tops only one. `RRFK` is the k (default 60):
lower it when you trust each leg's top hits and want agreement there
to dominate; raise it to flatten the fusion toward consensus deeper
in both lists.

---

The last two recipes leave the rack entirely: a kevy on an edge node
— the same server binary, or `kevy-embedded` compiled down to its
`core` tier at 655 KB ([docs/iot.md](https://kevy.golia.jp/docs/iot/)) — speaks the same
verbs, so the patterns transfer verbatim from datacenter to sensor
gateway.

## 19. Sensor cache (latest value + liveness lease)

**SQL equivalent:** the `readings_latest` upsert table plus the
staleness cron —
[matrix: operational deltas](https://kevy.golia.jp/docs/rds-workloads/#sizing-and-operational-deltas).

The current value of every sensor is a row; the TTL is the liveness
contract. A sensor that stops reporting expires out of the cache —
**absence IS the offline signal**, no reaper job to write:

```console
kevy-cli -p 6004 HSET sensor:t1 val 21.5 unit C ts 1783200000
kevy-cli -p 6004 EXPIRE sensor:t1 90
kevy-cli -p 6004 HSET sensor:t1 val 21.7 unit C ts 1783200030
kevy-cli -p 6004 EXPIRE sensor:t1 90      # every report renews the lease
kevy-cli -p 6004 EXISTS sensor:t1         # 1 = reporting, 0 = gone dark
```

Size the lease to your alarm tolerance (here 90 s = three missed
30-second reports). To *react* to a sensor going dark instead of
polling, enable keyspace notifications with the `x` (expired) class
and subscribe to the expiry events — the push form of the same
contract (docs/pubsub.md).

The recent window is a stream with a hard cap — `MAXLEN ~` keeps the
node's memory bounded no matter how long it runs, which on a
months-uptime edge box is the invariant that matters:

```console
kevy-cli -p 6004 XADD sensor:t1:log MAXLEN '~' 1000 '*' val 21.5
kevy-cli -p 6004 XADD sensor:t1:log MAXLEN '~' 1000 '*' val 21.7
kevy-cli -p 6004 XLEN sensor:t1:log
kevy-cli -p 6004 XRANGE sensor:t1:log - + COUNT 10
```

Embedded form: same verbs through the typed API inside your gateway
process — `store.hset(…)` / `store.expire(…)` / `store.xadd(…)` —
with no socket at all; the `core` feature tier carries everything
this recipe uses (docs/iot.md).

## 20. Edge aggregation (write-time GROUP BY + uplink)

**SQL equivalent:** `SELECT zone, COUNT(*), SUM(w) … GROUP BY zone`
re-run per dashboard refresh —
[matrix: GROUP BY and aggregates](https://kevy.golia.jp/docs/rds-workloads/#group-by-and-aggregates).

An edge node summarizes locally and ships summaries — raw readings
are too many to uplink. Declare the aggregate once; it is maintained
in the write path, so the "aggregation job" simply stops existing:

```console
kevy-cli -p 6004 HSET reading:1 zone floor1 w 120
kevy-cli -p 6004 HSET reading:2 zone floor1 w 180
kevy-cli -p 6004 HSET reading:3 zone floor2 w 95
kevy-cli -p 6004 IDX.CREATE zone_w ON PREFIX reading: FIELD w TYPE i64 KIND agg GROUPBY zone
kevy-cli -p 6004 IDX.QUERY zone_w GROUP floor1            # [count, sum, min, max, avg]
kevy-cli -p 6004 IDX.QUERY zone_w GROUPS BY sum LIMIT 10  # zones ranked by load
```

The uplink is recipe 11's outbox wearing overalls: the feed already
journals every committed write, so the cloud-sync consumer is a
cursor loop, resumable across links that drop for hours —
at-least-once, in commit order, prefix-filtered to just what the
cloud needs:

```console
# needs [feed] enabled = true in kevy.toml (docs/cdc.md)
kevy-cli -p 6004 FEED.TAIL 0
kevy-cli -p 6004 FEED.READ 0 1 0 COUNT 100 PREFIX reading:   # the uplink loop
```

Pair it with recipe 19's `MAXLEN` cap and TTLs: raw readings stay
bounded on the node, the aggregate rows stay tiny, and the feed
cursor survives reboots — the whole edge story with zero moving
parts beyond kevy itself.

## Recipe index

Recipe ↔ the SQL construct it replaces ↔ the
[rds-workloads.md](https://kevy.golia.jp/docs/rds-workloads/) matrix row that states the
semantics and limits.

| # | Recipe | SQL construct | Matrix row |
|---|---|---|---|
| 1 | Tables and rows | `CREATE TABLE`, point `SELECT` | [tables, rows, columns](https://kevy.golia.jp/docs/rds-workloads/#tables-rows-columns) |
| 2 | One-to-many, many-to-many | FK columns, junction tables, `WHERE fk = ?` | [JOIN](https://kevy.golia.jp/docs/rds-workloads/#join) |
| 3 | Sequences | `AUTO_INCREMENT` / `nextval()` | [PK, UNIQUE, AUTO_INCREMENT](https://kevy.golia.jp/docs/rds-workloads/#primary-key-unique-auto_increment) |
| 4 | Optimistic locking | version-column CAS `UPDATE` | [transactions](https://kevy.golia.jp/docs/rds-workloads/#transactions) |
| 5 | CHECK constraints | `CHECK (…)` + audit trigger | [constraints and triggers](https://kevy.golia.jp/docs/rds-workloads/#constraints-and-triggers) |
| 6 | Idempotency keys | `UNIQUE INDEX` + `ON CONFLICT DO NOTHING` | [PK, UNIQUE, AUTO_INCREMENT](https://kevy.golia.jp/docs/rds-workloads/#primary-key-unique-auto_increment) |
| 7 | Soft delete | flag column + filtered view | [VIEW](https://kevy.golia.jp/docs/rds-workloads/#view) |
| 8 | Composite ordering | `ORDER BY a, b` | [ORDER BY / LIMIT / OFFSET](https://kevy.golia.jp/docs/rds-workloads/#order-by--limit--offset) |
| 9 | JSONB | JSON column + generated-column indexes | [type system](https://kevy.golia.jp/docs/rds-workloads/#type-system) |
| 10 | Cascade delete / FKs | `ON DELETE CASCADE` | [constraints and triggers](https://kevy.golia.jp/docs/rds-workloads/#constraints-and-triggers) |
| 11 | The outbox you don't need | transactional-outbox table | [CDC](https://kevy.golia.jp/docs/rds-workloads/#cdc) |
| 12 | Audit history | audit table / binlog archaeology | [CDC](https://kevy.golia.jp/docs/rds-workloads/#cdc) |
| 13 | The rollback window | reverse replication at cutover | [migration playbook](https://kevy.golia.jp/docs/migration/#phase-5--write-cutover--the-rollback-window) |
| 14 | Analytics export | ETL / binlog tap to warehouse | [CDC](https://kevy.golia.jp/docs/rds-workloads/#cdc) |
| 15 | Loading order | bulk `LOAD DATA`, index after | [secondary index DDL](https://kevy.golia.jp/docs/rds-workloads/#secondary-index-ddl) |
| 16 | Session context with TTL | sessions table + expiry cron | [operational deltas](https://kevy.golia.jp/docs/rds-workloads/#sizing-and-operational-deltas) |
| 17 | Episodic memory | time `BETWEEN` + pgvector KNN | [SELECT](https://kevy.golia.jp/docs/rds-workloads/#select) |
| 18 | RAG hybrid retrieval | tsvector + pgvector, fused | [SELECT](https://kevy.golia.jp/docs/rds-workloads/#select) |
| 19 | Sensor cache | upsert table + staleness cron | [operational deltas](https://kevy.golia.jp/docs/rds-workloads/#sizing-and-operational-deltas) |
| 20 | Edge aggregation | `GROUP BY` per refresh + ETL uplink | [GROUP BY and aggregates](https://kevy.golia.jp/docs/rds-workloads/#group-by-and-aggregates) |

==============================================================================
# rds-workloads
==============================================================================

# RDS workloads on kevy

You run an operational workload on MySQL or PostgreSQL and are
considering moving it — wholly or partially — onto kevy. This page is
the **reference matrix**: every SQL-surface construct, what carries it
in kevy, the exact verbs, and the semantic deltas. Where kevy refuses a
construct, the refusal is stated plainly along with the covered
alternative. The companion [cookbook](https://kevy.golia.jp/docs/cookbook/) turns these rows
into runnable recipes; [designing-on-kevy](https://kevy.golia.jp/docs/designing-on-kevy/) is
the one-page map of the engine itself.

## The division of labor

An RDS lets you write data first and decide the access paths later —
the query planner turns any `WHERE` clause into *some* plan at query
time. kevy inverts that: **you declare the access paths at write time**
(indexes, aggregates, views), the engine maintains them synchronously
with every write (derived-by-construction, zero drift), and serving is
a microsecond-scale lookup, never a plan search. The trade is
explicit:

- What you give up: ad-hoc queries over undeclared paths. A `WHERE`
  with no matching index is not slow on kevy — it is *absent by
  design* (model the access path or don't ship the query).
- What you get: predictable serving latency (hydrated page p99 < 1ms,
  write fan-out through index+view hooks p99 < 200µs on one server
  carrying the full stack — the gated lines in
  [designing-on-kevy](https://kevy.golia.jp/docs/designing-on-kevy/)), and raw Redis-parity
  throughput far above what a B-tree-on-disk engine serves
  (see [Sizing](#sizing-and-operational-deltas)).

The boundary is a charter, not a backlog: no query language, no
planner, no joins, no server-side validation DSL, no triggers
("Law 3", [designing-on-kevy](https://kevy.golia.jp/docs/designing-on-kevy/)). Everything below
maps SQL constructs onto that fixed surface.

## Tables, rows, columns

| RDS | kevy |
|---|---|
| table | key prefix (`user:`) |
| row | hash under the prefix (`user:42`) |
| column | hash field |
| PRIMARY KEY | the key itself |
| NULL | absent field (never a sentinel string) |

```
HSET user:42 name ada email ada@example.com age 36
HGETALL user:42                # SELECT * WHERE id = 42
HGET user:42 email             # SELECT email WHERE id = 42
HMGET user:42 name age         # SELECT name, age WHERE id = 42
```

`HGET` of a missing field answers nil — that IS the NULL semantics,
and index specs treat a missing field as "row excluded" (counted,
visible in `IDX.VERIFY`).

### Type system

kevy stores bytes; types are declared **where they matter — at index
creation** (`TYPE i64|f64|str|vector`). A row whose field fails the
declared coercion is excluded from that index and counted
(`coerce_failures` in `IDX.VERIFY` / `IDX.LIST`) — a declarative
fence, never a write error.

| RDS type | kevy form | notes |
|---|---|---|
| INT / BIGINT / SERIAL | field bytes, index `TYPE i64` | full i64 range |
| DECIMAL / NUMERIC | **integer minor units** as `i64` (cents, micros) | kevy has no decimal type; `f64` is binary floating point — never store money in it. Sums in `KIND agg` accumulate in f64 (documented precision bound), so pick units that keep totals well under 2^53 |
| FLOAT / DOUBLE | field bytes, index `TYPE f64` | IEEE 754 semantics |
| VARCHAR / CHAR / TEXT | field bytes, index `TYPE str` | binary-safe; lexicographic byte order |
| BLOB / BYTEA | field bytes (no index) or a dedicated string key | values are arbitrary bytes everywhere |
| DATETIME / TIMESTAMP | Unix epoch (secs or millis) as `i64` | range index gives you `BETWEEN`; kevy has no date arithmetic — the app does calendar math |
| BOOL | `0` / `1` as `i64` | indexable, composable (`EQ 0`) |
| JSON / JSONB | flattened hash fields (`profile.city`) | per-field reads, TTLs (`HEXPIRE`), indexability; JSON-path queries are permanently out — cookbook recipe 9 |
| embedding (pgvector) | `dim × 4` bytes f32-LE, index `TYPE vector` | [vector-search](https://kevy.golia.jp/docs/vector-search/) |

## PRIMARY KEY, UNIQUE, AUTO_INCREMENT

**Primary key** — the key itself. Point lookups (`WHERE pk = ?`) are
`GET`/`HGETALL`/`HMGET`: one shard, one hash probe, no index needed.

**AUTO_INCREMENT / sequences** — `INCR seq:order` mints one id;
`INCRBY seq:order 100` allocates a block to hand out from app memory
(the high-throughput form). Gaps on crash are the same contract
PostgreSQL sequences give you (cookbook recipe 3).

**UNIQUE** — `KIND unique` is a **fence, not a lock**: it does not
block writes (blocking would serialize cross-shard writes); duplicates
are counted (`duplicates` in `IDX.VERIFY`) and visible as multi-hit
`EQ` reads. For a hard uniqueness gate use one of:

```
SET uniq:email:ada@example.com 42 NX          # atomic claim, NX = the gate
WATCH + MULTI/EXEC check-then-write           # CAS loop (cookbook recipe 4)
{hashtag} prefix + single-shard domain        # cluster mode
```

## SELECT

| SQL | kevy | verbs |
|---|---|---|
| `WHERE pk = ?` | direct key read | `GET` / `HGETALL` / `HMGET` |
| `WHERE col = ?` | equality on a declared index | `IDX.QUERY idx EQ v [FIELDS f…]` |
| `WHERE col BETWEEN a AND b` | range scan on a declared index | `IDX.QUERY idx RANGE a b` |
| `WHERE col > a` | half-open range | `RANGE a <max-sentinel>` |
| `WHERE a = ? AND b BETWEEN …` | two-index composition | `IDX.QUERY COMPOSE AND idxA EQ v idxB RANGE a b` |
| `WHERE col IN (v1, v2)` | two-leg OR, or N app-side EQ queries | `IDX.QUERY COMPOSE OR idx EQ v1 idx EQ v2` |
| `LIKE 'abc%'` (prefix) | str range index, prefix bounds | `IDX.QUERY idx RANGE 'abc' 'abc\xff'` |
| `LIKE '%abc%'` (infix) | **not supported as such** | full-text `MATCH` if token-shaped; else redesign the field |
| full-text search | `KIND text`, BM25 | `IDX.QUERY idx MATCH "…"` |
| `SELECT col1, col2` (projection) | field hydration | `… FIELDS col1 col2` |
| `COUNT(*) WHERE …` | count without materializing | `IDX.COUNT idx RANGE a b` |
| `EXPLAIN` | parse + plan line, zero execution | `IDX.EXPLAIN idx RANGE a b` |

Semantics and limits, honestly:

- **One field per index.** An index covers one declared field of one
  prefix. Multi-column predicates are `COMPOSE AND|OR` of exactly
  **two** indexes (key-ordered — the two value domains differ, so key
  order is the only shared order), or a [view](#view) for a named,
  reusable composition of up to 4 leaves. Wider ad-hoc conjunctions
  are the query-planner slope — refused. Filter residual predicates
  app-side after hydration.
- **`RANGE`/`EQ`/`COMPOSE`**: default `LIMIT 100`, max `10000`, cursor
  pagination (`[next-cursor, rows]`, `"0"` = start/exhausted).
  Cursor contract is SCAN-class: rows stable across the traversal are
  seen exactly once; concurrent writes may or may not appear. No
  global snapshot — same envelope as `SCAN`/`DBSIZE`.
- **Prefix `LIKE`**: a `TYPE str KIND range` index is ordered by
  lexicographic byte order, so `LIKE 'abc%'` is
  `RANGE 'abc' 'abc<0xff>'` — an index scan, not a keyspace walk.
  (Key-name prefix matching via `SCAN 0 MATCH 'user:*'` also exists
  but walks the whole keyspace incrementally — use it for ops chores,
  never as a serving path.)
- **`MATCH`** is OR-semantics over query tokens, BM25-ranked, CJK
  bigrams built in; `LIMIT` caps at 1000, no cursor; no phrase
  queries, no boolean syntax, no highlighting
  ([text-search](https://kevy.golia.jp/docs/text-search/)).
- **`FIELDS`** hydrates named hash fields on each row's owning shard
  in the same call — the one-hop replacement for the "index scan +
  primary lookup" double hop. This is also the JOIN-shaped hydration
  primitive (below).
- **`IDX.EXPLAIN` is diagnostic only.** It reports kind, state,
  `est_rows`, and the plan line for the query you already wrote —
  there is no optimizer choosing among plans.

## ORDER BY / LIMIT / OFFSET

- A `range` index **is** the order: `IDX.QUERY … RANGE` returns rows
  ascending by indexed value. `ORDER BY col ASC LIMIT n` = declare a
  range index on `col`, query with `LIMIT n`.
- **Descending order** on the bare index surface: not an `IDX.QUERY`
  option. Either declare a view (`VIEW.CREATE … ORDER BY idx DESC`) or
  store a negated/complemented sort field at write time.
- **`ORDER BY a, b`** (composite): encode the composite into one
  indexed field at write time — `a * 1_000_000 + b` for bounded
  integers, zero-padded strings for lexicographic composites
  (cookbook recipe 8).
- **`OFFSET` does not exist.** There is deliberately no "skip N rows"
  — it is O(N) waste in any engine and an anti-pattern at depth.
  Paginate with the returned cursor (constant cost per page,
  position-stable under the SCAN-class contract). If your product
  needs "jump to page 47", precompute page anchors or rethink the UX;
  kevy will not hide the cost.

## GROUP BY and aggregates

`KIND agg` maintains aggregates **in the write path** — the inversion
of `GROUP BY`: an RDS scans rows at query time, kevy folds each write
into its group as it lands, and reading a group is O(1).

```
IDX.CREATE ord_amt ON PREFIX ord: FIELD amount TYPE i64 KIND agg GROUPBY status
IDX.QUERY ord_amt GROUP paid                  → [count, sum, min, max, avg]
IDX.QUERY ord_amt GROUPS BY sum LIMIT 100     → ranked [group, count, sum, min, max]
```

- `GROUP g` = `SELECT COUNT(*), SUM(v), MIN(v), MAX(v), AVG(v) WHERE
  group = g`; `GROUPS BY count|sum|min|max` = the ranked
  `GROUP BY … ORDER BY agg LIMIT n` (LIMIT ≤ 1000).
- min/max stay exact under deletion (per-group value multiset); sums
  accumulate in f64 — mind the precision bound for money (use minor
  units sized so totals stay well under 2^53).
- **No `HAVING`, no aggregate expressions, no `GROUP BY` over
  arbitrary predicates** — filter the (bounded) `GROUPS` result in
  the app. One group-by field per index; declare several agg indexes
  for several groupings.

## JOIN

**kevy does not join.** No verb joins two prefixes server-side, and
none ever will (Law 3). The three replacements, in order of
preference:

1. **Denormalize at write time.** The serving-model answer: if the
   page shows `order.total` next to `user.name`, write `user_name`
   into the order row when it's created. Storage is cheap; the write
   hook keeps any indexes on the copy fresh. Update fan-out on the
   parent (rare for display fields) is a CDC consumer.
2. **Application-side hydration (the two-hop).** Foreign key lives in
   the row; an index makes the reverse direction one hop:
   `IDX.QUERY order_user EQ 42 FIELDS total status` is
   `SELECT total, status FROM orders WHERE user_id = 42` — the index
   finds the keys and hydrates fields in the same call (cookbook
   recipe 2). The forward direction is `HMGET` per parent — batch the
   ids and pipeline.
3. **A view with `VIA` hydration.** `VIEW.QUERY v FIELDS name VIA
   user:{key.1}` dereferences each member key to a *target* key via a
   template and reads fields there — a declared, reusable
   member→parent dereference (one internal fan-out, no client round
   trips). Dereference, not query: targets take no predicates.

What you lose vs SQL: arbitrary N-way joins, join-time filtering on
the far table, planner-chosen join order. What you gain: no join ever
shows up in a latency histogram.

## VIEW

`VIEW.*` is a named AND/OR/DIFF composition over declared indexes with
an ordering index — closer to a *materialized* view with an index than
to a SQL view:

| SQL view property | kevy view |
|---|---|
| arbitrary SELECT body | **no** — tree of index shapes only (depth ≤ 3, ≤ 4 leaves, shapes fixed at CREATE) |
| always-fresh (virtual) | `MODE virtual` — evaluated per query, zero write cost |
| materialized + REFRESH | `MODE materialized` — incrementally maintained in the write hook, **never stale**, no refresh job; optional `TOPK k` bound |
| ORDER BY in the view | `ORDER BY <index> [DESC]` — a declared range index supplies the order |
| view over a view | no — one level, over indexes |

```
VIEW.CREATE live_adults QUERY '( AND user_live EQ 0 user_age RANGE 18 200 )'
    ORDER BY user_age MODE materialized TOPK 100
VIEW.QUERY live_adults LIMIT 10 [FIELDS name] [VIA …]
```

The killer app is the **hot list**: "top 100 ready jobs by priority"
as a `TOPK` materialized view costs ~2% write tax and answers in
microseconds, permanently fresh — the thing an RDS needs a covering
index + a disciplined query + luck to approximate
([views](https://kevy.golia.jp/docs/views/)).

## Transactions

kevy's transaction story is Redis's (Law 1), which maps to SQL like
this:

| SQL | kevy | delta |
|---|---|---|
| `BEGIN … COMMIT` (batch) | `MULTI` … `EXEC` | commands queue and apply as one unit; **no interactive reads inside** — reads you branch on happen before `MULTI` |
| `SELECT … FOR UPDATE` | `WATCH key` + `MULTI`/`EXEC` | optimistic CAS, not a lock: `EXEC` answers nil if a watched key changed — re-read and retry (cookbook recipe 4) |
| `ROLLBACK` | none | a queue-time error aborts the whole batch (`-EXECABORT`, nothing ran); a runtime error inside `EXEC` does **not** undo the other commands — Redis semantics |
| stored procedure / one atomic RMW | `EVAL` (Lua) | the whole script is one atomic unit on `KEYS[1]`'s shard; read-decide-write with real branching ([lua](https://kevy.golia.jp/docs/lua/)) |
| serializable single-entity txn | embedded `store.atomic(key, …)` | shard-locked closure: reads see your own writes, commit is atomic + one fsync (cookbook recipe 5) |
| cross-entity serializable | embedded `atomic_all_shards` | deterministic lock order; the hammer — use sparingly |

Isolation, honestly: kevy has no MVCC and no isolation-level knob.
Within one shard, every command (and every `EVAL`, `MULTI` batch, or
embedded atomic block) is serialized — you get *serializable* behavior
for anything that fits one shard / one script. Across shards there is
no global snapshot: multi-key reads (`MGET`, `IDX.QUERY` merges) are
per-shard-atomic, SCAN-class overall. There is no read that observes a
torn single command, and no dirty read of an uncommitted `MULTI`
batch; there IS no repeatable-read across two separate commands —
use `WATCH` (CAS) or Lua (one unit) where that matters.

Durability of a "commit": see [persistence](https://kevy.golia.jp/docs/persistence/) — with
`appendfsync always` an acknowledged write is on disk before the
reply; the default `everysec` windows up to 1s (the Redis trade).
`Store::fsync_aof()` (embedded) is the per-transaction
`synchronous_commit` escape hatch.

## Constraints and triggers

| SQL | kevy answer |
|---|---|
| `NOT NULL` / type checks | the **coercion fence**: rows failing an index's declared TYPE are excluded and counted (`coerce_failures`); the app watches `IDX.VERIFY` — declarative visibility, not write rejection |
| `CHECK (expr)` | evaluate the invariant inside the atomic unit: Lua script (server) or `atomic` block (embedded) reads, decides, writes — the engine guarantees decision + commit are one unit (cookbook recipe 5) |
| `UNIQUE` | fence + counted duplicates, or a hard `SET … NX` gate (above) |
| `FOREIGN KEY` (existence) | not enforced; write parent-then-child inside one atomic unit if you need the invariant |
| `ON DELETE CASCADE` | app pattern: atomic block (small), `kevy-cli delete-prefix` (bulk), or a CDC consumer reacting to parent deletes (async — cookbook recipe 10) |
| triggers | **CDC consumers**: `FEED.READ` delivers every committed write as a change frame — after commit, decoupled, replayable, and it can't corrupt the write path (cookbook recipes 10–12) |

There is deliberately no server-side constraint or trigger DSL: Lua
scripts are the only server-side logic, and they run *as the write*,
not attached to it.

## Secondary index DDL

| SQL | kevy |
|---|---|
| `CREATE INDEX idx ON t (col)` | `IDX.CREATE idx ON PREFIX t: FIELD col TYPE i64\|f64\|str KIND range` |
| `CREATE UNIQUE INDEX` | `KIND unique` (fence semantics, above) |
| `CREATE INDEX … USING gin (tsvector)` | `KIND text` ([text-search](https://kevy.golia.jp/docs/text-search/)) |
| pgvector `USING hnsw` | `KIND ann DIM d [DISTANCE cosine\|l2\|ip] [M m] [EF ef]` ([vector-search](https://kevy.golia.jp/docs/vector-search/)) |
| `DROP INDEX` | `IDX.DROP idx` |
| `\d` / information_schema | `IDX.LIST` / `VIEW.LIST` (state, entries, bytes) |

- **Online build**: `IDX.CREATE` returns immediately and backfills in
  the background (~7s per million small rows; multi-KB text bodies
  ~85s/M). Queries answer `-INDEXBUILDING` until ready — poll
  `IDX.LIST` for `state=ready` ([migration](https://kevy.golia.jp/docs/migration/)). Data
  availability never waits on an index build.
- Index content is **derived state**: never snapshotted or AOF-logged,
  rebuilt in the background after restart. The catalog (the
  declarations) persists in a data-dir sidecar.
- Up to 64 indexes; `MAXMEM` caps a build declaratively
  (`-INDEXOVERBUDGET`) instead of growing unbounded.
- **Bulk-load rule**: import first, declare indexes after — backfill
  at bulk speed beats paying the write hook per imported row
  (cookbook recipe 15).

## Pagination and optimistic locking patterns

- **Keyset/cursor pagination** (the good kind of `OFFSET`): every
  paged surface (`IDX.QUERY RANGE/EQ/COMPOSE`, `VIEW.QUERY`, `SCAN`)
  returns `[next-cursor, rows]`; feed the cursor back until `"0"`.
  Treat cursors as opaque and single-traversal.
- **Version-column optimistic locking**: keep a `version` field,
  `WATCH` the row, read, `MULTI` + `HSET … version n+1` + `EXEC`; nil
  reply = lost the race, retry (cookbook recipe 4).

## Backup and PITR

| RDS | kevy |
|---|---|
| `mysqldump` / `pg_dump` | `kevy-cli export` (logical RESP stream, `redis-cli --pipe`-compatible) |
| binary backup | snapshot files (`SAVE`/`BGSAVE` → `dump-<id>.rdb`) |
| WAL / binlog | the AOF (append-only command log, per shard) |
| `synchronous_commit` | `appendfsync always` (or `everysec` + `fsync_aof` barriers) |
| PITR (base + WAL replay) | **recovery-point contract**: snapshot + CDC frames from the snapshot's recorded cursor = exact state at any later cursor ([persistence](https://kevy.golia.jp/docs/persistence/)) |

Scope note on PITR: the feed window is an in-memory backlog
(`feed_buffer_size`, caps 1 GiB/shard) — take snapshots at least as
often as the window turns over if you rely on exact-point recovery.
Verification is first-class: `PREFIX.DIGEST` / `kevy-cli diff` prove
two keyspaces equal, order- and topology-insensitively.

## Replication and read scaling

Primary + N replicas, asynchronous by default — the read-replica
shape. The differences from an RDS are all in the **consistency
ladder** ([availability](https://kevy.golia.jp/docs/availability/)), which prices each
guarantee per call instead of per instance:

| RDS notion | kevy rung |
|---|---|
| async replica (MySQL default) | rung 0: primary acks after local apply, replicas trail |
| session read-your-writes | rung 1: `REPL.TOKEN` on the primary → `REPL.WAIT token` on the replica → your next read observes your write |
| semi-sync replication | rung 2: `WAIT n timeout` per write — on the primary **and** acked by ≥ n replicas (ACK ≠ fsync) |
| max replica lag guard | rung 3: `replica_max_staleness_ms` — a stale replica answers `-STALE` instead of serving old reads |
| refuse writes without standbys | rung 4: `min_replicas_to_write` (`-NOREPLICAS`) |
| fencing / split-brain guard | rung 5: quorum lease — a partitioned primary fences its own writes |

Failover: planned handover is the `FAILOVER` verb (quiesce → drain →
promote — zero-loss); crash failover is the 3-node elect quorum
(MTTR ≈ 5–8s, offset-best candidate wins so `WAIT`-acked writes
survive). A rejoining ex-primary's un-replicated tail is **discarded**
(the forked suffix was never acked by definition) — the same
data-loss shape as losing un-shipped binlog in MySQL semi-sync, made
explicit. Every degraded state is a named error (`-READONLY`,
`-STALE`, `-NOREPLICAS`, `-QUIESCED`, `-MISDIRECTED`) that a routing
client self-heals from ([error-replies](https://kevy.golia.jp/docs/error-replies/)).

## CDC

The feed is kevy's binlog-as-API — what Debezium extracts from an RDS,
served natively ([cdc](https://kevy.golia.jp/docs/cdc/)):

| Debezium/binlog notion | kevy |
|---|---|
| binlog position / LSN | `(generation, offset)` cursor, per shard |
| connector snapshot + stream | rebuild (SCAN your prefix) + resume from `FEED.TAIL` |
| topic-per-table filtering | `PREFIX` filter on `FEED.READ` (fail-open for multi-key frames) |
| at-least-once delivery | same — consumers must be idempotent |
| transactional outbox pattern | **unnecessary**: every committed write already IS a change frame (cookbook recipe 11) |

Not provided, deliberately: global cross-shard order (per-key order is
guaranteed within a shard stream), server-side consumer positions,
consumer groups. Retention is the in-memory backlog; falling behind
answers `-FEEDRESYNC` with the cursor to rebuild from.

## What kevy will NOT do

The refusals, in one place. Each is a charter decision
([designing-on-kevy](https://kevy.golia.jp/docs/designing-on-kevy/), the project's scope log) —
not a roadmap gap:

| Refused | Because | Use instead |
|---|---|---|
| SQL parser / query DSL | the planner slope starts here | explicit `IDX.*`/`VIEW.*` + this matrix |
| query planner / auto index selection | engine must execute declared paths, not decide | `IDX.EXPLAIN` (diagnostic only) |
| JOINs | no server-side plan search | denormalize / hydrate (`FIELDS`, `VIA`) / view |
| `WHERE` without an index | accidental O(n) is a lie waiting to page you | declare the path or don't ship the query |
| server-side constraint DSL / triggers | stored app logic isn't engine-genre | Lua `EVAL` (atomic unit) + CDC consumers |
| DECIMAL type | no server-side arithmetic beyond i64/f64 | integer minor units |
| JSON-path queries | hash fields ARE the column model | flatten to fields (cookbook recipe 9) |
| `HAVING` / aggregate expressions | query-language slope | filter `GROUPS` output app-side |
| `OFFSET` pagination | O(N) skip is an anti-pattern | cursors |
| multi-database `SELECT n` | one keyspace per server | prefixes or separate instances |
| AUTH / TLS | trust boundary is the network perimeter | loopback bind (default), sidecar proxy |
| cross-DC active-active, CRDTs | single-DC charter | app-level federation |
| dynamic membership / auto-replace / resharding | topology is operator-declared | config + rolling restart |
| HTTP/REST API | RESP + MCP are the two access planes | any Redis client |

## Sizing and operational deltas

**Everything is RAM-resident.** The working set that an RDS pages from
disk lives in memory here; disk is the durability log + snapshot, not
the serving tier. Capacity planning in one line:

> RAM ≈ rows × (avg key len + avg row bytes + per-key overhead)
> + Σ per-index formula + view members × entry size — then verify
> against `MEMORY USAGE` / `IDX.LIST` bytes on a loaded sample.

The per-subsystem formulas (each gated against measured RSS in CI):
range index ≈ `rows × (value_width + avg_key_len + 48)`; text and ANN
formulas in [text-search](https://kevy.golia.jp/docs/text-search/) /
[vector-search](https://kevy.golia.jp/docs/vector-search/) (1M × 1024d vectors ≈ 4.1 GiB);
agg ≈ groups-dominated ([indexes](https://kevy.golia.jp/docs/indexes/)); view members ≈
`order_value_width + key_len + 48` ([views](https://kevy.golia.jp/docs/views/)). Set
`maxmemory` + an eviction policy or accept `-OOM` refusals (writes are
rejected at admission — existing data is never corrupted).

**Serving headroom.** The v3.18.0 release arena (kevy vs valkey 9.1,
fair-fight protocol, median-of-5 — `bench/PERF-LEDGER.md`): GET 3.00×,
SET 3.99×, INCR 3.00×, SADD 2.50×, HSET 2.25×, ZADD 1.73×,
LPUSH 1.64× — 7/7 wins with the full replication/heartbeat pipeline
landed. Against
a disk-first RDS on point reads the gap is larger still; the honest
comparison there is "kevy replaces the cache tier AND the operational
queries", not a per-query benchmark.

**Operational deltas vs an RDS**, in brief: single keyspace (no
schemas/databases — prefixes are the namespace); TTLs are first-class
(`EXPIRE`, per-field `HEXPIRE` — the cron-delete job disappears);
`FLUSHALL` is one command away (perimeter-protect it); derived state
(indexes, views, feeds) rebuilds after restart rather than loading
(seconds per million rows — budget it into restart time); and the
error surface is part of the contract — clients should match error
prefixes, not parse messages ([error-replies](https://kevy.golia.jp/docs/error-replies/)).

## This page vs the cookbook

This page is the **reference matrix** — SQL construct in, kevy shape
out, deltas stated. The [cookbook](https://kevy.golia.jp/docs/cookbook/) is the **recipe book**
— 20 runnable patterns (every command block CI-smoked), each tagged
with the SQL construct it replaces and cross-linked back to the matrix
rows above. Migrating for real? The phased playbook is in
[migration](https://kevy.golia.jp/docs/migration/).

==============================================================================
# persistence
==============================================================================

# Persistence

How kevy keeps data across restarts — the AOF, snapshots, fsync policies, rewrite/compaction, crash recovery, and the introspection that lets you watch all of it.

## When you need this

Reach for this doc when you are:

- Choosing a durability policy (zero-loss vs throughput) for a production deployment.
- Sizing disk usage and replay-time budgets for a write-heavy workload.
- Debugging an unexpected on-disk artifact — a quarantine file, a stale `.rewrite` temp, a `.premigration.*` backup.
- Wiring an embedded `kevy_embedded::Store` into a host application and want to know what survives a process crash, what doesn't, and how to observe it from inside the host.
- Looking at a key whose TTL behaves oddly across restarts.

If you only want a quick "does it survive `kill -9`?" answer: yes, with at most one second of writes lost under the default policy.

## Core idea

Every shard owns two files in the persistence directory: an append-only log of mutating commands (`aof-<id>.aof`) and an optional binary snapshot (`dump-<id>.rdb`). The AOF alone is a complete durable record; the snapshot exists only to bound replay time. On boot kevy loads the snapshot if present, then replays the AOF; on a successful snapshot the AOF is reset so the two files together cover the full history exactly once.

The directory itself is created at boot if missing (v3.17); a path that cannot be created is one named startup error, not a bare ENOENT from whichever subsystem touches it first.

## Worked examples

### Server mode

Drop this into `kevy.toml` and launch with `kevy --config kevy.toml`:

```toml
# kevy.toml
[server]
data_dir = "/var/lib/kevy"
port     = 6379
threads  = 4

[persistence]
aof = true
# AOF durability — see the knobs table below for the full set.
appendfsync                 = "everysec"   # always | everysec | no
auto_aof_rewrite_percentage = 100          # rewrite when the AOF doubles since the last rewrite
auto_aof_rewrite_min_size   = "64mb"       # …and is at least this big
```

Operate it with standard Redis-style commands over RESP:

```text
$ redis-cli -p 6379 BGSAVE
Background saving started

$ redis-cli -p 6379 BGREWRITEAOF
Background append only file rewriting started

$ redis-cli -p 6379 INFO persistence
aof_enabled:1
appendfsync:everysec
aof_rewrite_in_progress:0
aof_rewrites_total:3
```

`CONFIG SET appendfsync always` retunes the policy live without a restart.

### Embedded mode

Add the crate to `Cargo.toml`:

```toml
[dependencies]
kevy-embedded = "*"
```

Then in `main.rs`:

```rust
use std::time::Duration;
use kevy_embedded::{AppendFsync, Config, KevyMetric, Store};

fn main() -> kevy_embedded::KevyResult<()> {
    let cfg = Config::default()
        .with_persist("/var/lib/myapp/kevy")
        .with_appendfsync(AppendFsync::EverySec)
        .with_auto_aof_rewrite(100, 64 * 1024 * 1024)
        .with_metric_sink(|m| match m {
            KevyMetric::Replay { commands, bytes, elapsed_ms } => {
                eprintln!("kevy replay: {commands} cmds / {bytes} B in {elapsed_ms} ms");
            }
            KevyMetric::Rewrite { keys, before_bytes, after_bytes, elapsed_ms } => {
                eprintln!(
                    "kevy rewrite: {keys} keys, {before_bytes} -> {after_bytes} B in {elapsed_ms} ms"
                );
            }
            _ => {}
        });

    let store = Store::open(cfg)?;

    store.set(b"hello", b"world")?;
    store.expire(b"hello", Duration::from_secs(300))?;

    // Point-in-time snapshot. Returns after the file is on disk; per-shard
    // locks are held only for the view freeze and the final rename.
    store.save_snapshot()?;

    // On-demand AOF compaction. Same lock discipline as save_snapshot.
    let _stats = store.rewrite_aof()?;

    // Live introspection.
    let info = store.info();
    println!("{} keys, {} bytes AOF", info.keys, info.aof_bytes);

    Ok(())
}
```

A fresh embedded store with the default config writes only the AOF — no snapshot file appears until `save_snapshot` runs. That is expected; the AOF on its own is enough to rebuild the keyspace.

## Configuration knobs

### Durability and AOF growth

| Knob | Server (TOML / `CONFIG SET`) | Embedded (`Config::…`) | Default | Notes |
|---|---|---|---|---|
| AOF fsync policy | `appendfsync` (`always` / `everysec` / `no`) | `with_appendfsync(AppendFsync::…)` | `EverySec` | Live-tunable on the server. |
| AOF enabled | `aof` (`true` / `false`) | implied by `with_persist(...)` | `true` (server), off until `with_persist` | Disabling skips all on-disk persistence. |
| Auto-rewrite percentage | `auto_aof_rewrite_percentage` | first arg of `with_auto_aof_rewrite(pct, min)` | `100` | `0` disables auto-rewrite. |
| Auto-rewrite minimum size | `auto_aof_rewrite_min_size` | second arg of `with_auto_aof_rewrite(pct, min)` | `67108864` (64 MiB) | Auto-rewrite fires only when both thresholds are met. |
| Persistence directory | `data_dir` / env `KEVY_DIR` | `with_persist(path)` | `./data` (server); none (embedded) | One directory per kevy instance. |
| Reactor / reaper cadence | reactor tick, ~100 ms | background reaper, or your `Store::tick` calls | ~100 ms | Drives `EverySec` flush, auto-rewrite checks, TTL eviction. |

### Trigger surface

| Action | Server | Embedded | Blocking shape |
|---|---|---|---|
| Synchronous snapshot | `SAVE` | `Store::save_snapshot()` | Returns after the file is on disk; locks held only for freeze + rename. |
| Background snapshot | `BGSAVE` | call `save_snapshot` from a worker thread | Returns immediately; commit lands within one reactor tick of the disk write finishing. |
| AOF rewrite | `BGREWRITEAOF` | `Store::rewrite_aof()` | Returns after the atomic rename; serialization runs with the keyspace live. |
| Live-tune fsync | `CONFIG SET appendfsync everysec` | rebuild `Config` | n/a |
| Graceful shutdown | `SHUTDOWN [SAVE\|NOSAVE]` (or SIGTERM) | drop the last `Store` clone | Drains every shard: in-flight persist jobs land, the AOF tail is force-fsynced, then the process exits. `SAVE` additionally takes one final snapshot per shard. No reply is sent — the client observes the connection closing (Redis behavior). |

### fsync policy semantics

| Policy | Durability | Cost |
|---|---|---|
| `Always` | Zero-loss — every write fsynced before its reply | ~50% throughput |
| `EverySec` (default) | At most ~1 second of writes lost on a crash | Cheap |
| `No` | Defers to the OS pagecache flush | Cheapest |

## Trade-offs and limits

**Per-policy throughput vs data loss.** `Always` blocks each reply on `fsync`; it is the only policy that survives `kill -9` with zero command loss, and it cuts SET-heavy throughput roughly in half on typical NVMe. `EverySec` runs a background flush every second and loses up to that window on a crash — the default precisely because it matches the Redis trade and the lost window is usually tolerable. `No` lets the kernel decide; throughput is highest but a crash can lose anything still in pagecache, potentially many seconds.

**AOF replay cost vs snapshot load cost.** Without a snapshot, boot time grows linearly with the AOF byte count: a 4 GiB AOF replays in a few seconds on local NVMe, a 40 GiB one in a minute or more. A snapshot caps that — load is one streaming read plus a short tail of post-snapshot AOF — but costs a transient view freeze (O(keys), nanoseconds per key, because collection values are refcount-shared) plus a one-time copy of any collection first mutated while the snapshot is in flight. For write-heavy workloads, prefer leaning on auto-rewrite to keep the AOF bounded rather than running periodic `BGSAVE`s: rewrite gives you the same boot-time bound with no second file to manage.

**Background-job concurrency.** Each shard runs at most one background save or rewrite at a time. A duplicate request that arrives mid-job is skipped with a log line, never queued.

**TTL persistence.** TTLs are written as absolute Unix-millisecond deadlines (`PEXPIREAT` in the AOF, an absolute field in the snapshot format), so a key keeps its original expiry instant across any number of restarts and the time the process spent down is subtracted correctly. Older AOFs that recorded relative remaining time still load (treated as relative on entry); new writes are always absolute. `EXPIREAT` and `PEXPIREAT` are exposed as client commands.

**Shard-layout changes are crash-idempotent.** Changing `--threads` / `shards` writes new snapshots under `.reshard` temp names, commits via a durable `reshard.journal`, and rolls an interrupted migration forward on the next start. Source files survive as `.premigration.<unix_ts>` backups; the journal is the commit point and must never be deleted by hand.

**What is not persisted.** Pub/sub channels, subscriptions, and undelivered messages live only in memory. Blocking-command waiters such as `BLPOP` and blocking `XREAD` are connection state, not data. Neither is written to the AOF or snapshot, and neither is replayed.

## FAQ

### My AOF file is growing — how do I compact it?

Run `BGREWRITEAOF` on the server or `Store::rewrite_aof()` in embedded mode. Rewrite rebuilds the log as the minimal command set that reconstructs the current keyspace — one `SET` / `HSET` / etc. per key, plus a `PEXPIREAT` for TTL'd keys — and atomically swaps the new file in. Ten thousand overwrites of `hot` collapse to a single `SET hot <latest>`.

For unattended ops, leave auto-rewrite at its defaults — 100% growth over the previous rewrite size, with a 64 MiB floor — and the reactor will fire compaction on its own. Set `auto_aof_rewrite_percentage = 0` to disable it and drive rewrite entirely by hand.

Rewrite is non-blocking for the keyspace: serialization and `fsync` run with reads and writes flowing, and any writes that land during the rewrite are tee'd into a diff buffer that gets appended to the compacted image. If a rewrite crashes midway the original AOF is untouched (the swap is an atomic `rename`) and the leftover `aof-<id>.aof.rewrite` temp is safe to delete.

### Can I disable persistence entirely?

Yes, in two ways:

- **Server:** set `appendonly = false` in `kevy.toml` (or omit `--dir`). The server runs as a pure in-memory cache; no `aof-*` or `dump-*` files are created.
- **Embedded:** build a `Config` without calling `with_persist(...)`. `Store::open` runs the keyspace entirely in memory; `save_snapshot` and `rewrite_aof` become no-ops at the API surface (or surface an error indicating no persistence directory is configured).

If you want persistence but no AOF growth at all between snapshots, that combination is not supported — kevy's durability model is AOF-first, and the snapshot exists to bound AOF replay, not to replace the AOF.

### What is the cost of a snapshot during high write load?

The blocking portion is tiny. A per-shard freeze of the keyspace is O(keys), not O(bytes), because collection values are reference-counted and shared with the live store; on a million-key shard the freeze takes single-digit milliseconds. Serialization itself runs with the keyspace live — writes are not paused.

The transient cost you pay is memory. Any collection (list, hash, set, sorted-set) that gets mutated while the snapshot is being written gets cloned once, so the live store can move on without disturbing the frozen view. For workloads dominated by `SET` on plain string keys the extra memory is negligible; for workloads dominated by `HSET` / `LPUSH` on a small number of huge collections it can briefly double the resident size of those specific collections.

A successful snapshot also resets the AOF — the snapshot now carries everything the log used to, and the log restarts with only writes that landed after the freeze. A restart then loads snapshot + log without ever double-applying history.

### How is recovery sequenced on the next boot?

For each shard, in order:

1. **Load the snapshot.** If `dump-<id>.rdb` exists, stream it into the keyspace. Expired TTLs are dropped during load.
2. **Replay the AOF.** Read `aof-<id>.aof` from the front and apply each frame.
3. **Handle the tail.** A clean file applies in full. A truncated tail (crash mid-append) drops the partial trailing frame and applies the prefix. A corrupt frame moves the bad bytes aside to `aof-<id>.aof.panic-quarantine.<unix_ts>` so they don't block future starts, then applies the prefix. The quarantined tail is never re-applied; inspect it by hand if you need to recover anything from it.
4. **Log a one-line summary** including wall-clock time:

   ```text
   kevy: AOF /data/kevy/aof-0.aof replayed 145313 commands from 418261733 bytes in 247 ms (clean)
   ```

5. **Roll forward any interrupted shard-layout migration** by replaying `reshard.journal`.

Watch the replay-time line and use auto-rewrite to keep it bounded — replay time grows linearly with the unrewritten AOF size.

### How do I monitor persistence from inside an embedded host process?

Two surfaces.

**Polling.** `store.info()` returns a `KevyInfo` struct with `keys`, `used_memory`, `aof_bytes`, `expire_pending`, `evictions`, `expired_keys`. Finer-grained helpers cover the same ground:

```rust
store.dbsize();                 // live key count
store.ttl(key);                 // Option<Duration> (None = no key / no TTL)
store.ttl_ms(key);              // Redis PTTL semantics: -2 no key, -1 no TTL, else ms
store.expire_pending_count();   // live keys carrying a TTL
store.used_memory();            // resident-bytes estimate
store.expired_keys_total();     // total expired (lazy + reaper)
store.evictions_total();        // total evicted by maxmemory
```

`expire_pending_count() == 0` when you expected TTLs is the classic tell that the TTL subsystem didn't register your keys.

**Push.** Register `Config::with_metric_sink(...)` and receive `KevyMetric` events on AOF replay (startup) and each AOF rewrite (compaction). The sink runs synchronously on the emitting thread (the reaper for background rewrites), so keep the callback fast. `KevyMetric` is `#[non_exhaustive]` — always match a `_` arm to stay forward-compatible.

### What is every file in the persistence directory?

| Pattern | Meaning |
|---|---|
| `aof-<id>.aof` | Live AOF for shard `<id>`. |
| `dump-<id>.rdb` | Binary snapshot for shard `<id>`. |
| `shards.meta` | Recorded shard count and routing scheme. |
| `dump-<id>.rdb.tmp` | In-progress snapshot write. Safe to delete if stale. |
| `aof-<id>.aof.rewrite` | In-progress AOF rewrite/reset. Safe to delete if stale. |
| `dump-<id>.rdb.reshard` + `reshard.journal` | In-progress shard-layout migration. Rolled forward on next start; never delete the journal by hand. |
| `*.premigration.<unix_ts>` | Pre-migration source backups, kept for rollback. |
| `aof-<id>.aof.panic-quarantine.<unix_ts>` | Corrupt AOF tail set aside during recovery. Inspect by hand if you need to salvage anything; kevy will not re-apply it. |
| `elect.meta` (+ transient `elect.meta.tmp`) | Election durability (v3.15): the elector's `(epoch, votedFor)` pair, persisted *before* any vote answer leaves the node so a crash-restart can never double-vote. Written tmp + fsync + rename — a crash mid-save leaves the old pair or the new pair, never a torn file. Only present with a `[cluster]` quorum configured. |

## Durability contract (v2.1)

What "the call returned OK" guarantees, per `appendfsync` × write path.
"Durable" = on stable storage (`fdatasync` completed); "windowed" = in
the OS page cache, lost only if the *machine* (not just the process)
dies inside the window.

| Write path | `always` | `everysec` | `no` |
|---|---|---|---|
| Server command reply | durable before the reply leaves the shard (group-committed per batch) | windowed ≤ 1 s | OS-paced |
| Embedded facade op (`set`, `zadd`, …) | durable on return | windowed ≤ 1 s | OS-paced |
| Embedded `atomic` / `atomic_all_shards` block | durable on commit (one fsync per touched shard) | windowed ≤ 1 s | OS-paced |
| Embedded `Pipeline::commit` | durable on return, fsyncs batched per shard | windowed ≤ 1 s | OS-paced |
| …any of the above + **`Store::fsync_aof()`** | no-op | **durable at the barrier** | **durable at the barrier** |

`Store::fsync_aof()` is the per-write durability escape hatch
(Postgres `synchronous_commit`-per-transaction genre): run a
deployment on `everysec` for throughput, and place the barrier after
the few writes that must survive a machine crash the moment they are
acknowledged. Cost: one `fdatasync` per dirty shard.

Process crash (SIGKILL) never loses acknowledged writes under `always`
and loses at most the fsync window otherwise; the AOF tail is
replayed on the next open, and a torn final frame is quarantined
(`panic-quarantine`), never silently applied.

An **orderly stop** (`SHUTDOWN` or SIGTERM) loses nothing under any
policy: the drain force-fsyncs the AOF tail before exit, so the
`everysec` window that a crash can lose does not apply to a clean
shutdown.

## Atomicity charter (embedded serving-store, v2.1)

- **`Store::atomic(body)`** — single-shard transaction: takes that
  shard's write lock for the closure, reads inside see the closure's
  own writes, AOF appends are deferred and committed with **one fsync
  at commit** (under `always`). Every key touched must hash to the
  same shard — the blessed serving-store config is therefore
  **1 shard** when your write patterns span arbitrary keys: you keep
  full atomicity and pay no cross-shard coordination. The ceiling of
  the 1-shard config is single-core write throughput; measured
  numbers live in `bench/REPORT.md`.
- **`Store::atomic_all_shards(body)`** — multi-shard transaction:
  acquires **every** shard's write lock in shard-index order
  (deterministic order = no deadlock), commits per-shard AOF batches
  on return. Cost: blocks all other readers + writers for the
  closure's duration — use it for cross-shard invariants, not as the
  default write path.
- **`Store::pipeline()`** — NOT atomic: each op takes its own lock;
  other writers interleave. It batches fsyncs (N ops → ≤ shard-count
  fsyncs), nothing more.
- Both atomic forms log the **effect** of conditional ops (`ZADD GT`,
  `SPOP`) as unconditional verbs, so replay and replica-apply are
  deterministic by construction.

## Recovery points (v2.3)

With the change feed enabled (`[feed] enabled = true`, see
[cdc.md](https://kevy.golia.jp/docs/cdc/)), every snapshot records the feed cursor it was taken
at — frozen in the same no-append window as the snapshot data itself.
That yields the recovery-point contract:

> **snapshot S + the feed frames from S's recorded cursor = the exact
> state at any later cursor.**

`kevy_persist::read_snapshot_cursor(path)` reads the cursor back
(`None` for pre-v2.3 snapshots — format v4 and older carry no cursor
and remain fully loadable). The executable form of the contract is
`bench/restore-drill.sh`, run as a `diskgate` line: write → SAVE →
write more → kill → restore the dumps alone → replay the captured
feed frames → byte-exact key-by-key verification.

Scope note: the feed window is the in-memory backlog. Frames older
than the window are gone — a snapshot older than the window's reach
is a plain snapshot restore (state at S), not a PITR base. Take
snapshots at least as often as the window turns over if you rely on
exact-point recovery.

## The snapshot on the replication wire (v3.15)

The same snapshot format is what a primary in-line-ships to a replica
that has fallen past the backlog window (see
[replication.md](https://kevy.golia.jp/docs/replication/)). One semantic worth knowing: a
shipped snapshot **replaces** the replica's local state, it does not
merge — the replica flushes its keyspace before loading. That is
deliberate: when a rejoining ex-primary carries a forked suffix
(writes that were never replicated), the resync must genuinely
discard the fork rather than leave it as residue under an upsert-only
load.

==============================================================================
# tuning
==============================================================================

# Tuning kevy

A reference for the runtime knobs that change kevy's per-op cost — CPU layout, reactor choice, persistence, memory limits, network transport, and a few Linux-side levers.

## When you need this

Reach for this doc when:

- A benchmark is showing kevy under your throughput or latency target and you want to know which knob to turn next.
- You are deploying kevy on a host where the defaults (TCP loopback, io_uring auto-detect, `appendfsync everysec`, no `maxmemory`) do not match the workload — e.g. sparse-conn services, NVMe-backed durability requirements, or memory-capped cache tiers.
- You are profiling kevy with `perf` and need the build profile that keeps debug line tables on.

If you are just starting kevy on a laptop and the numbers look fine, you do not need this page. Defaults are tuned to be reasonable across workloads.

## Core idea

kevy is a thread-per-core server: one shard per OS thread, shared-nothing keyspace partitioned by CRC16 hashtag, busy-poll reactor on each shard. The defaults aim at "decent on every workload"; tuning means matching the shard count, the reactor, and the persistence policy to **what your perf data actually shows is the bottleneck**. Do not pre-emptively flip knobs. Measure, identify the cost, then change one variable at a time.

## Tuning playbook

### CPU and shards

| Knob | Where | Default | Effect |
|------|-------|---------|--------|
| `--threads N` / `KEVY_THREADS` | CLI / env | number of online cores | shard count; one OS thread per shard |
| `--accept-shards K` | CLI | all shards accept | only the first K shards bind a listener; the rest are compute-only |
| CPU pinning | `taskset` / `numactl` | none | locks shards to a fixed core set |

**Picking `--threads`.** Set this to the parallelism actually present in the workload. A single-client pipelined benchmark (`-c 1 -P 16`) saturates one shard; setting `--threads 10` here makes nine shards busy-poll for no work and steal cache lines from shard 0. For real multi-client workloads, start at `min(cores, expected concurrent clients / 4)` and measure.

**Picking `--accept-shards`.** When the connection-to-shard ratio is low (sparse-conn workloads — say, 50 clients across 10 shards = 5 conns/shard), the per-iteration busy-poll overhead stops amortizing and throughput drops. The rule of thumb is `ceil(conns / 20)` — for 50 conns, set `--accept-shards 3` and let three listening shards each take roughly 17 connections while the remaining shards stay compute-only and still receive cross-shard work via the internal dispatcher. The empirical sweet spot is broader than the point estimate; see [docs/accept-shards.md](https://github.com/goliajp/kevy/blob/develop/docs/accept-shards.md) for the full sweep and a discussion of when the cross-shard hop tax outweighs the accept-concentration win.

**CPU pinning.** On a benchmark or single-tenant host, pinning kevy to a fixed core set keeps the NIC IRQ → softirq → user-thread path on the same L1/L2:

```sh
taskset -c 0-9 kevy --port 6004 --threads 10
```

If the client runs on the same machine, pin server and client to **disjoint** core ranges (server `0-9`, client `10-15`). Shared cores reintroduce scheduler ping-pong that swamps any reactor gain.

### Reactor choice

| Platform | Default | Override |
|----------|---------|----------|
| Linux ≥ 5.19 | io_uring (auto-detected) | `KEVY_IO_URING=0` forces epoll; `KEVY_IO_URING=1` requires io_uring and exits loudly if `io_uring_setup` is blocked by seccomp |
| macOS / *BSD | kqueue | not configurable |
| Older Linux | epoll | n/a |

The Linux auto-detect runs `io_uring_setup` at startup; if the syscall is blocked (seccomp profile, locked-down container) kevy silently falls back to epoll. In a hardened deployment that you *want* to fail loudly rather than silently degrade, set `KEVY_IO_URING=1` so the server refuses to start unless io_uring is actually available. Conversely, when you need to take io_uring out of the picture for a reproducible epoll-vs-io_uring benchmark or to work around a kernel regression, set `KEVY_IO_URING=0`.

```sh
KEVY_IO_URING=1 kevy --port 6004   # require io_uring, exit if blocked
KEVY_IO_URING=0 kevy --port 6004   # force epoll
```

### Persistence

AOF policy is controlled by `appendfsync` (config file or `CONFIG SET`). The three values match Redis semantics:

| `appendfsync` | Durability | Cost |
|---------------|------------|------|
| `always` | every write `fsync`-ed before reply | highest latency; bounded by NVMe sync latency |
| `everysec` (default) | `fsync` once per second on a background thread | bounded data loss window of 1 s; near-zero hot-path cost |
| `no` | never `fsync`; kernel flushes on its own schedule | fastest; data loss window = page-cache flush interval |

The background `fsync` for `everysec` runs on a dedicated bio thread off the shard hot path, so shard tail latency is not coupled to disk latency. For a pure cache or a read-replica, also consider disabling AOF entirely with `--no-aof` (no AOF file is written at all, not even buffered).

### Memory

| Knob | Default | What it does |
|------|---------|--------------|
| `maxmemory` | unlimited | hard memory cap in bytes; once reached, the eviction policy kicks in |
| `maxmemory-policy` | `noeviction` | which keys to drop when the cap is hit |
| `maxmemory-samples` | 5 | sample size for the approximate-LRU/LFU policies |

Eviction policies mirror Redis: `noeviction`, `allkeys-lru`, `allkeys-lfu`, `allkeys-random`, `volatile-lru`, `volatile-lfu`, `volatile-random`, `volatile-ttl`. `noeviction` makes writes fail with OOM once the cap is hit and is the safe default for a primary store; the `allkeys-*` policies are correct for a cache tier where any key is disposable.

`maxmemory-samples` is a quality-vs-cost dial for the approximate policies — sampling more keys produces a closer approximation to true LRU/LFU at a per-eviction CPU cost. The default of 5 is sufficient for most cache workloads; raise to 10 if you can see eviction picking poor victims in your access pattern, lower to 3 only if eviction itself is showing up in profiles.

### Network

The default transport is TCP. When the client lives on the same host, switch to a Unix-domain socket and skip the loopback TCP stack entirely:

```sh
KEVY_UNIX_SOCKET=/tmp/kevy.sock kevy --port 6004
redis-cli -s /tmp/kevy.sock SET foo bar
```

The server dual-binds: TCP stays available for remote clients, UDS handles local ones. Same RESP semantics, same shard runtime. The gain on local-client workloads is large (the loopback TCP path is the dominant cost at small payload sizes); see [docs/uds.md](https://github.com/goliajp/kevy/blob/develop/docs/uds.md) for the full numbers, the permissions model, and the cases where UDS does not apply.

**Bind address warning.** kevy has no AUTH and no TLS today. Binding to a non-loopback address (`--bind 0.0.0.0` or any public interface) prints a startup warning, because anything on the network can then issue commands. Run kevy behind a private network boundary or behind a proxy that terminates auth.

**Connection introspection.** `INFO clients` reports a live `connected_clients` gauge summed across all shards. `CLIENT LIST` / `CLIENT INFO` render one Redis-7.x-shaped row per real client connection — peer address, a globally unique `id`, `name`, subscription counts, MULTI queue depth, input/output buffer sizes (`cmd=NULL`: the last-command name is not tracked). `CLIENT SETNAME` labels the connection for LIST; `CLIENT KILL ID <id> | ADDR <ip:port> | LADDR <ip:port>` (or the legacy positional `CLIENT KILL <ip:port>`) closes every matching connection, including ones parked in blocking commands. Teardown waits for the victim's pending output to drain, so a connection that kills itself still receives its own reply.

### Replication and availability

Only relevant when running a primary/replica topology ([docs/replication.md](https://github.com/goliajp/kevy/blob/develop/docs/replication.md), [docs/availability.md](https://github.com/goliajp/kevy/blob/develop/docs/availability.md)).

**Port layout.** Each node uses three planes, all derived from the client port by default:

| Plane | Port | Notes |
|-------|------|-------|
| client RESP | `port` (e.g. 6004) | what clients and `peers` client-ports refer to |
| replication | `listen_port_base + shard_i`; default base = `port` + 10000 | `nshards` consecutive ports; replicas bind this range too (v3.15) |
| election | `elect_port_base`; default = `port` + 200 | one control-plane listener per node |

Co-hosting several instances on one machine: keep client ports at least `nshards` apart, or the default replication ranges collide. `FAILOVER` and automatic retarget assume the `port + 10000` convention — leave `listen_port_base` at its default in failover-enabled deployments.

**Consistency knobs.** Two `[replication]` keys trade availability for stronger guarantees (the full ladder is [docs/availability.md](https://github.com/goliajp/kevy/blob/develop/docs/availability.md)):

| Knob | Default | What it does |
|------|---------|--------------|
| `replica_max_staleness_ms` | `0` (off) | a replica whose last primary heartbeat is older than the bound refuses reads with `-STALE`; heartbeats ride the stream at 1 Hz, so bounds below ~2 s trip on healthy links |
| `min_replicas_to_write` | `0` (off) | the primary refuses writes with `-NOREPLICAS` when fewer than N replicas are healthy |

Per-call barriers cost one blocked call instead of a standing config: `WAIT n timeout` on the primary, `REPL.TOKEN` + `REPL.WAIT` for read-your-writes on a replica. Both interpret `timeout 0` as "wait forever", hard-capped at 60 s.

### Linux kernel knobs

Two host-level levers move the kernel floor that sits underneath kevy. Both are benchmark / single-tenant-only — read the trade-offs before applying.

**Spectre / BHB mitigations.** On Linux 6.x kernels with mitigations enabled (the default), every syscall pays for `clear_bhb_loop` and friends. On a small-payload `-c 1` workload this is the single largest CPU consumer in a kevy run. Disabling mitigations at the kernel cmdline:

```sh
# Add `mitigations=off` to GRUB_CMDLINE_LINUX_DEFAULT, then:
sudo update-grub && sudo reboot
cat /proc/cmdline | grep mitigations
```

is only acceptable on single-tenant boxes where no untrusted code runs (no Lua-from-the-wire, no third-party plugins, no multi-tenant containers). Do not apply to multi-tenant hosts, shared CI runners, or anything processing untrusted user code. The gain is in the +10–15% range on `-c 1`, smaller as the workload pipelines more.

**Hugepages for the `.text` segment.** kevy can call `madvise(MADV_HUGEPAGE)` on its own code segment, which lets the kernel back the kevy binary's instructions with 2 MiB pages instead of 4 KiB. The win is a smaller iTLB footprint on the hot dispatch loop. This costs effectively nothing at runtime and is worth enabling on Linux hosts where `/sys/kernel/mm/transparent_hugepage/enabled` is `always` or `madvise`. The trade-off is purely the small one-time cost of the `madvise` call at startup; there is no security trade-off, unlike `mitigations=off`.

## Profiling

For a `perf record` flamegraph that resolves to actual symbols, build with the `release-perf` profile — same optimization level as `release` but with debug line tables retained:

```sh
cargo build --profile release-perf
./target/release-perf/kevy --port 6004 --threads 1 &
KEVY_PID=$!

perf record -F 999 -p $KEVY_PID -g --call-graph=fp -- sleep 30
perf report --stdio | head -60

# Resolve raw addresses for inlined symbols:
addr2line -e ./target/release-perf/kevy -f -i 0x<addr>
```

The standard `release` profile strips line tables, so `perf` reports raw addresses with no symbols and `addr2line` returns `??`. Don't profile a `release` binary; rebuild with `release-perf` first.

For symbol-level attribution of `clear_bhb_loop` and other kernel-side cost, capture with `--call-graph=dwarf` instead of `fp` and use the same `addr2line` flow. The dwarf unwinder is slower but unwinds across the syscall boundary correctly.

## Trade-offs

| Knob | Costs | Buys |
|------|-------|------|
| `--threads N` (raise) | wasted CPU on idle busy-poll shards if N > workload parallelism | more concurrent client capacity |
| `--threads N` (lower) | one shard's worth of cross-shard hop tax avoided | less wasted CPU on sparse-conn workloads |
| `--accept-shards K` | listener concentration; fewer entry points if clients connect via raw `connect` | per-iter overhead amortizes across more conns on each accepting shard |
| `KEVY_IO_URING=1` (force) | server refuses to start when seccomp blocks io_uring | no silent degradation to epoll on hardened hosts |
| `KEVY_IO_URING=0` (force epoll) | gives up io_uring's per-op saving | reproducible epoll baseline; works around kernel regressions |
| `appendfsync always` | every write blocks on `fsync` | zero-data-loss durability |
| `appendfsync no` | data loss window = page-cache flush interval | fastest write path |
| `--no-aof` | no persistence at all | minimum disk I/O; useful for replicas / caches |
| `maxmemory` set | writes can fail (`noeviction`) or evict (`allkeys-*`) | bounded memory footprint |
| `maxmemory-samples` raise | per-eviction CPU cost | better approximate-LRU/LFU victim choice |
| Unix-domain socket | local-only; filesystem-permission security model | skips the TCP loopback stack |
| `replica_max_staleness_ms` set | reads on a lagging replica fail (`-STALE`) until it catches up | bounded read staleness |
| `min_replicas_to_write` set | write availability coupled to replica health (`-NOREPLICAS`) | no writing into the void |
| `mitigations=off` | Spectre / Meltdown / MDS / etc. mitigations all off | reclaims the syscall-path tax |
| `MADV_HUGEPAGE` on `.text` | none meaningful | smaller iTLB footprint on the dispatch loop |
| `release-perf` build | larger binary (debug line tables) | `perf` resolves to symbols |

## FAQ

**Should I always set `--accept-shards`?**

No. The knob exists for sparse-conn workloads where conns/shards is low and the busy-poll body fails to amortize. For dense-conn workloads (say, 1000 clients on 10 shards = 100 conns/shard), the default — every shard accepts — is correct, because spreading the listener evenly reduces accept-side contention. Apply `ceil(conns / 20)` only when you actually have a sparse-conn case.

**Is io_uring always faster than epoll?**

On Linux ≥ 5.19 with a workload that batches submissions, yes, materially. On older kernels, on kernels with seccomp filters that block `io_uring_setup`, or on workloads dominated by a single syscall per op with no batching opportunity, the difference shrinks. Auto-detect is the right default; override only when you have a measured reason or a hardened deployment that should fail loudly rather than silently fall back.

**What's the production sweet spot for `appendfsync`?**

`everysec` for almost everyone. It bounds data loss to one second, runs the `fsync` off the hot path, and has near-zero impact on tail latency. Use `always` only when your durability story actually requires zero data loss (and accept that NVMe `fsync` latency now bounds your tail latency). Use `no` only for pure caches where the AOF exists just for warm-restart speed.

**When do I need `MADV_HUGEPAGE`?**

When `perf` shows iTLB misses on the hot dispatch loop, or when the host's `/sys/kernel/mm/transparent_hugepage/enabled` is set to `madvise` (in which case nothing else opts kevy in). It's a no-cost knob on Linux hosts where THP is enabled at all, so the default position is "leave it on." There is no equivalent on macOS / BSD.

**My `perf` report is full of raw addresses. What did I do wrong?**

You profiled a `cargo build --release` binary. The standard release profile strips debug line tables, so `perf` and `addr2line` have nothing to resolve against. Rebuild with `cargo build --profile release-perf` and re-record.

==============================================================================
# error-replies
==============================================================================

# Error reply catalog

A lookup table of every wire-level error reply kevy emits, what triggers it, and what the client should do next.

## How to read this

kevy errors travel over RESP as a simple-error string: `-<PREFIX> <message>\r\n`. The first whitespace-separated token is the **prefix** (`ERR`, `WRONGTYPE`, `MOVED`, `CROSSSLOT`, ...). Client libraries typically surface this as an error variant or exception whose `.kind` / `.code` / class name matches the prefix; the rest of the line is a human-readable message.

This catalog is grouped by prefix. If you handle errors structurally (recommended), match on the prefix; the trailing message is intended for logs and operators, not for parsing.

Errors are part of kevy's user-facing contract. Adding, renaming, or repurposing a prefix is a breaking change for clients that pattern-match.

## Core reference

| Prefix | Triggers when | Recovery / next step |
|--------|---------------|----------------------|
| `-ERR unknown command '<cmd>'` | Command name is not implemented or not recognized. | Check README command coverage; verify spelling. |
| `-ERR wrong number of arguments for '<cmd>' command` | argc doesn't match the command's accepted shapes. | Re-issue with the documented argument count. |
| `-ERR value is not an integer or out of range` | INCR/DECR-class command on a value that isn't a parsable i64, or numeric arg out of range. | Use `SET` to overwrite with a parsable integer; clamp the input. |
| `-ERR no such key` | RENAME / RENAMENX / COPY / GETEX targets a key that does not exist. | Treat the key as absent (use `EXISTS` to pre-check if needed). |
| `-ERR kevy only supports DB 0` | `SELECT N` issued with N ≠ 0. | kevy has no multi-DB; use separate instances or namespaced keys. |
| `-ERR MULTI calls can not be nested` | `MULTI` sent while already inside a MULTI block. | Wait for `EXEC` / `DISCARD` before opening another transaction. |
| `-ERR EXEC without MULTI` | `EXEC` sent with no open transaction. | Pair with `MULTI`, or drop the command. |
| `-ERR DISCARD without MULTI` | `DISCARD` sent with no open transaction. | Pair with `MULTI`, or drop the command. |
| `-ERR WATCH inside MULTI is not allowed` | `WATCH` sent inside a MULTI block. | Issue `WATCH` before `MULTI`. |
| `-ERR <cmd> not allowed inside MULTI` | A command that isn't queue-safe (pub/sub, `WATCH`, `HELLO`, `RENAME`) was queued inside MULTI. | Issue these outside the transaction. |
| `-ERR Protocol error` | Inbound bytes are not valid RESP. | Reconnect and retry; if persistent, audit the client serializer. |
| `-ERR CONFIG SET failed for '<key>': <reason>` | Unknown CONFIG field or value out of range. | `CONFIG GET *` to see supported fields and current values. |
| `-ERR CONFIG REWRITE could not write <path>: <io-error>` | Config TOML path is missing or not writable. | Check `--config` path and filesystem permissions. |
| `-WRONGTYPE Operation against a key holding the wrong kind of value` | Command run against an existing key of a different Redis type. | See [Wrong-type rules](#wrong-type-rules). |
| `-EXECABORT Transaction discarded because of previous errors.` | A command queued during MULTI was an unknown verb or had too few arguments; EXEC refuses the batch and runs nothing. | Fix the offending queued command, then `MULTI` / queue / `EXEC` again. |
| `-MOVED <slot> <host:port>` | Key's hash slot is not owned by this node. | See [Cluster-routing replies](#cluster-routing-replies). |
| `-CROSSSLOT Keys in request don't hash to the same slot` | Multi-key command spans more than one hash slot. | See [Cluster-routing replies](#cluster-routing-replies). |
| `-MISDIRECTED writer is <host:port>` | Write landed on a node that doesn't own this key's scope, or `REPL.WAIT` could not serve read-your-writes on this replica (timeout or generation mismatch). | See [Cluster-routing replies](#cluster-routing-replies); for `REPL.WAIT`, read the primary at `<host:port>`. |
| `-QUIESCED migrating to <host:port>` | The slot or scope is mid-migration and frozen on this node, or the node is mid-`FAILOVER` handover to `<host:port>`. | See [Cluster-routing replies](#cluster-routing-replies). |
| `-OOM command not allowed when used memory > 'maxmemory'` | Write-class command with policy `noeviction` after the limit is exceeded. | Raise `maxmemory`, set an eviction policy (e.g. `allkeys-lru`), or `DEL` to free room. Existing data is intact. |
| `-READONLY You can't write against a read only replica.` | Write command sent to a replica node. | Send to the primary, or use a routing client. |
| `-NOREPLICAS Not enough good replicas to write.` | Primary with `min_replicas_to_write = N` sees fewer than N healthy replicas. | Back off and retry; restore the replicas (see [docs/availability.md](https://github.com/goliajp/kevy/blob/develop/docs/availability.md)). |
| `-NOREPLICAS primary lost quorum; writes fenced` | An elect-quorum primary cannot reach a strict majority of its peers (partition minority side); writes self-fence for the lease window. | Back off and retry — the fence lifts when the partition heals, or the majority elects a new primary your routing client will find. |
| `-STALE replica is stale; read the primary or raise replica_max_staleness_ms` | Read sent to a replica whose last primary heartbeat is older than its `replica_max_staleness_ms` bound. | Read the primary until the replica catches up, or raise/disable the bound. |
| `-READONLY can't write against a read-only script` | Script was evaluated via `EVAL_RO` / `EVALSHA_RO` and attempted a write. | Use the writable `EVAL` / `EVALSHA` variant. |
| `-NOSCRIPT No matching script. Please use EVAL.` | `EVALSHA <sha>` requested a script not in the cache. | Call `EVAL` directly (kevy auto-caches) or `SCRIPT LOAD` first. |
| `-LOADING kevy is loading the dataset in memory` | Read sent to a replica while it is receiving a full-resync snapshot from its primary. | Wait and retry (the window is bounded by the snapshot ship); `PING`, `INFO`, and `HELLO` are answered during loading, so health checks and monitoring keep working. |
| `-ERR No such client address in the list` | Legacy-form `CLIENT KILL <addr:port>` matched no connection. | List live connections with `CLIENT LIST` and re-issue with an existing `addr`; the filtered form (`CLIENT KILL ID\|ADDR\|LADDR …`) returns a count of 0 instead of erroring. |

### Prefixes kevy never emits

By design, kevy does not authenticate or authorize at the protocol layer; these Redis-compatible prefixes are deliberately absent:

- `-NOAUTH` — no `AUTH` command surface.
- `-WRONGPASS` — no password check.
- `-NOPERM` — no ACL system.
- `-MISCONF` — a persistence failure (AOF append or background save) is logged to stderr and the node keeps serving from its consistent in-memory state; kevy does not turn a durability error into a client-visible reply. On restart it replays whatever reached disk.
- `-BUSY` — kevy has no interactive `SCRIPT KILL`. A script is instead bounded by an instruction budget (`[lua] time_limit_ms`, `0` = unlimited); an over-budget script is aborted in place and its `EVAL` returns an ordinary `-ERR` Lua error, so a runaway script never wedges the shard for another client to interrupt.

If your client expects these to be possible, treat them as unreachable on kevy. Access control is delegated to the deployment perimeter (kevy binds `127.0.0.1` by default).

## Wrong-type rules

A `WRONGTYPE` reply means the key already exists with a different Redis data type than the command expects. The rules:

- Type is decided at key creation and persists until the key is deleted (or expires).
- `DEL <key>` followed by the original command will succeed (you've reset the type).
- `EXPIRE` / `PERSIST` / `TYPE` / `OBJECT ENCODING` / `EXISTS` / `DEL` / `UNLINK` are type-agnostic and never raise `WRONGTYPE`.
- `WRONGTYPE` is never returned for a missing key; missing-key semantics follow each command's documented behavior (`GET` returns nil, `LPUSH` creates the list, and so on).

Recovery is always one of: pick a different key, or `DEL` the existing one and re-create with the intended type.

## Cluster-routing replies

These prefixes only appear when kevy is running in a routed mode (cluster or scoped). A non-cluster client may never see them.

- **`-MOVED <slot> <host:port>`** — Fires when a key's hash slot is permanently owned by another node. The client should reconnect to `<host:port>` and re-issue. Cluster-aware clients (e.g., `redis-cli -c`, `ioredis` in cluster mode) follow the redirect transparently and update their slot map.
- **`-CROSSSLOT Keys in request don't hash to the same slot`** — Fires on multi-key commands (`MGET`, `MSET`, `DEL` with multiple keys, `EVAL` with multiple `KEYS`, `SUNIONSTORE`, etc.) when the keys do not all hash to the same slot. Co-locate the keys with a shared `{hashtag}` segment, or split the command into per-slot batches client-side.
- **`-MISDIRECTED writer is <host:port>`** — Fires on a write that landed on a node that does not own the key's scope. Routing clients follow the redirect; manual clients should reconnect to `<host:port>`.
- **`-QUIESCED migrating to <host:port>`** — Fires while a slot or scope is being migrated and is frozen on this node. The client should treat it like `MOVED` and retry against `<host:port>`. Once migration completes, that node will respond authoritatively.

See the protocol notes in [docs/](https://github.com/goliajp/kevy/tree/develop/docs) for the full routing model.

## FAQ

**My client treats `-MOVED` as a fatal error — how do I fix it?**
The client isn't cluster-aware. Either switch to a cluster-aware client (e.g., `redis-cli -c`, `ioredis` with `Cluster`, `redis-py` with `RedisCluster`, the kevy routing client), or wrap your driver to catch `MOVED`, reconnect to the host in the message, and re-issue.

**Single-key command came back with `-CROSSSLOT` — is that a bug?**
No. `CROSSSLOT` only fires for multi-key commands. If you see it on what looks like a single-key call, the command is actually multi-key (e.g., `EVAL` with two `KEYS`, `SUNIONSTORE` with source + destination). Use `{tag}` notation to force shared slot placement, or split the call.

**I got `-OOM` — is my data corrupt?**
No. `-OOM` is rejected at command-admission time; the write never landed. The keyspace is in exactly the state it was before the command. Free room (`DEL` / set an eviction policy / raise `maxmemory`) and retry.

**`-LOADING` keeps coming back — how long should I wait?**
For as long as the full-resync snapshot ship takes (proportional to dataset size and link speed). `PING`, `INFO`, and `HELLO` are answered during loading (`INFO replication` reports `loading:1`), so health checks still work. A replica only enters this state when it reconnects too far behind the primary's backlog; if `-LOADING` recurs constantly, raise `[replication] replication_buffer_size` or investigate the link.

**A queued MULTI command returned `-EXECABORT` — were any writes applied?**
No. `EXECABORT` means the transaction was rejected as a batch; nothing in the queued sequence was executed. Fix the offending command and reopen with `MULTI`.

## Extension surfaces (IDX. / VIEW. / FEED.)

The extension verbs follow the same prefix contract. Every error is
self-explaining: it names the verb and the object and points at the
discovery surface (an agent that hits one can recover in-band).

| Prefix | Emitted when | Recovery |
|---|---|---|
| `ERR <VERB> '<name>': bad arguments — run COMMAND DOCS <VERB> for the syntax` | argument parse failed on an IDX./VIEW. verb | `COMMAND DOCS <verb>` returns the full syntax string |
| `ERR no such index '<name>' (IDX.LIST enumerates them)` | query names an index that doesn't exist | `IDX.LIST` / `VIEW.LIST` enumerate the catalog |
| `INDEXBUILDING index '<name>' is still building (poll IDX.LIST until state=ready)` | query raced the post-create backfill | poll `IDX.LIST` `state`; see docs/migration.md |
| `INDEXOVERBUDGET index '<name>' build exceeded MAXMEM (raise maxmemory or DROP the index)` | build hit the memory budget | raise `maxmemory` or `IDX.DROP` |
| `FEEDRESYNC <gen> <tail>` | a FEED cursor is no longer servable (generation bump or past-backlog) | restart consumption from a fresh snapshot + the returned cursor; see docs/cdc.md |

## Updating this catalog

If you add or modify a code path that emits a `-<PREFIX> ...` reply:

1. Update the row in [Core reference](#core-reference) (or add a new one).
2. Extend the wire-level chaos test at [crates/kevy/tests/wire_torture_chaos.rs](https://github.com/goliajp/kevy/blob/develop/crates/kevy/tests/wire_torture_chaos.rs) if a new prefix is introduced.
3. Note the change in [CHANGELOG.md](https://github.com/goliajp/kevy/blob/develop/CHANGELOG.md) for the release that ships it.

Errors are part of the client contract. Silent message changes can break ecosystem libraries that pattern-match on them.

==============================================================================
# indexes
==============================================================================

# Secondary indexes (`IDX.*` / `idx_*`)

kevy can maintain declarative secondary indexes over a **prefix
domain** of the keyspace: every hash key under a prefix is a "row",
one declared hash field is the indexed value. Indexes are maintained
**synchronously with every write** (derived-by-construction — the
index can never drift from the data, and `IDX.VERIFY` makes that
falsifiable), and queried with cursor pagination, two-index
composition, and optional field hydration.

```
IDX.CREATE idx_age ON PREFIX user: FIELD age TYPE i64 KIND range
HSET user:42 age 31 name "……"
IDX.QUERY idx_age RANGE 18 30 LIMIT 100 FIELDS name
```

## Declaring

`IDX.CREATE <name> ON PREFIX <p> FIELD <f> TYPE i64|f64|str KIND
range|unique [MAXMEM <bytes>]`

- **TYPE** is a scalar coercion: a row whose field is missing or fails
  to parse is **excluded** (counted per index — `IDX.VERIFY` /
  `IDX.LIST` report `coerce_failures`; this is the declarative fence,
  not a runtime error).
- **KIND range** serves `RANGE min max` scans; **unique** serves the
  same plus the duplicate fence (below).
- **MAXMEM** caps the index's memory: a build that crosses the budget
  fails declaratively (`-INDEXOVERBUDGET` on queries) instead of
  growing unbounded.
- Up to 64 indexes. The catalog persists in a data-dir sidecar;
  the index CONTENT is derived state — it is never snapshotted or
  AOF-logged, and rebuilds in the background after a restart
  (`-INDEXBUILDING` until ready; data availability never waits).

## Querying

- `IDX.QUERY <name> RANGE <min> <max> | EQ <v> [LIMIT n] [CURSOR c]
  [FIELDS f…]` → `[next-cursor, rows]`. Rows are `(value, key)`
  ordered across all shards; `FIELDS` hydrates the named hash fields
  on each row's owning shard (no second round-trip) and switches the
  rows to nested `[key, value, fname, fval…]` form.
- `IDX.QUERY COMPOSE AND|OR <n1> <spec1> <n2> <spec2> …` — two-index
  composition, **key-ordered** (the two value domains differ), same
  LIMIT/CURSOR/FIELDS tail. AND/OR run per shard (a key lives on
  exactly one shard, so per-shard set algebra composes globally).
- `IDX.COUNT <name> RANGE|EQ …` — count without materializing keys.
- `IDX.VERIFY <name>` — summed stats: entries, bytes,
  coerce_failures, duplicates.
- `IDX.LIST` — catalog + per-index state/entries/bytes.
- Cursor contract is SCAN-class: rows stable across the whole
  traversal are seen exactly once; concurrent insertions/deletions
  may or may not appear. `"0"` = start / exhausted.

## Uniqueness is a fence, not a lock

A `unique` index **does not block writes** — enforcing global
uniqueness at write time would serialize cross-shard writes. Instead:
duplicates are counted (`duplicates` in
VERIFY/LIST) and visible as multi-hit `EQ` reads. If you need hard
uniqueness, pin the domain to one shard with a `{hashtag}` prefix in
cluster mode, or check-then-write under `MULTI`/`WATCH`.

## Embedded

Same engine, typed API: `idx_create / idx_drop / idx_query /
idx_count / idx_stats / idx_list` (values as `IndexValue`, cursors as
`IndexCursor`). No `FIELDS` hydration — you're in-process; read
fields with `hget`. `idx_create` builds synchronously and returns
when the index serves.

## Consistency + cost model

- A write and its index update are atomic within the owning shard
  (single reactor thread / shard lock). Cross-shard queries are
  merged per shard with no global snapshot (SCAN-class, same as
  DBSIZE).
- An **empty catalog costs one untaken branch per write** (a Relaxed
  atomic load). With indexes declared, a write in an indexed domain
  pays one hash-field read + one B-tree update per matching index.
- Memory per index ≈ `rows × (value_width + avg_key_len + 48)` bytes
  (the constant is per-entry structure overhead). `IDX.LIST` reports
  measured bytes; `bench/idxgate.sh` gates the formula.

## Aggregate kind (`KIND agg`) — write-time GROUP BY

```
IDX.CREATE ord_amt ON PREFIX ord: FIELD amount TYPE i64 KIND agg GROUPBY status
IDX.QUERY ord_amt GROUP paid                      → [count, sum, min, max, avg]
IDX.QUERY ord_amt GROUPS BY sum LIMIT 100         → ranked [group, count, sum, min, max]
```

The engine answer to `SELECT g, COUNT(*), SUM(v) … GROUP BY g`:
aggregates are maintained IN THE WRITE PATH (a declared access path —
never a query-time row scan). min/max stay exact under deletion via a
per-group value multiset; sums accumulate in f64 (documented
precision bound); a row whose value fails coercion or whose group
field is missing is excluded and counted (VERIFY). Cross-shard
merging is exact: counts/sums add, extremes take. `GROUPS` ranks by
count/sum/max descending or min ascending, LIMIT ≤ 1000.

No HAVING, no aggregate expressions, no approximate sketches — the
query-language slope. Filter GROUPS results in the app.

Embedded: `idx_create_agg(name, prefix, field, ty, group_by)` /
`idx_group(name, g)` / `idx_groups(name, by, limit)`.

Memory ≈ `groups × (gkey+64) + distinct_values × 18 + rows ×
(key+10)` (constants calibrated against measured RSS); gated vs real RSS by `bench/agggate.sh` along with GROUP
p99 < 1ms @ 1M×10k groups, GROUPS top-100 < 5ms, and write tax < 10%.

==============================================================================
# vector-search
==============================================================================

# Vector search (`KIND ann`)

ANN is the index engine's fourth kind: declare it like any index and
the field's raw bytes parse as an f32 vector indexed in a per-shard
HNSW graph, maintained synchronously with every write. There is no
sidecar vector database and no ingestion job: embeddings live in the
same hash rows as the rest of the record, and the graph can never
drift from the data.

```
IDX.CREATE embs ON PREFIX doc: FIELD v TYPE vector KIND ann DIM 768
    [DISTANCE cosine|l2|ip] [M 16] [EF 200]
IDX.QUERY embs KNN <f32-le-blob> LIMIT 10 [EF 400] [FIELDS title]
IDX.REBUILD embs
```

## Quick start (server)

Rows are hash keys under the declared prefix; the indexed value is
one declared field holding the raw vector bytes:

```console
kevy-cli -p 6004 IDX.CREATE embs ON PREFIX doc: FIELD v TYPE vector KIND ann DIM 4
kevy-cli -p 6004 HSET doc:1 title "intro" v "csv:0.1,0.2,0.3,0.4"
kevy-cli -p 6004 HSET doc:2 title "search" v "csv:0.4,0.3,0.2,0.1"
kevy-cli -p 6004 IDX.QUERY embs KNN "csv:0.1,0.2,0.3,0.4" LIMIT 2 FIELDS title
```

The reply is `key, distance` pairs ascending (closest first);
`FIELDS` hydrates hash fields on each hit's owning shard in the same
call. In production the vector value is the binary blob (`dim × 4`
bytes of little-endian f32) written by your client library; the
`csv:` form above is the debugging convenience.

Supporting verbs work like on every kind: `IDX.EXPLAIN embs KNN …`
(parse + plan without execution), `IDX.VERIFY` / `IDX.LIST` (live
stats), `IDX.DROP`. `IDX.REBUILD` is specific to ANN — see
"Deletes and rebuild".

## Quick start (embedded)

The ANN kind is behind the `vector` cargo feature (on by default;
compiled out it answers `KevyError::Unsupported`):

```rust
use kevy_embedded::{AnnSpec, Config, Store};

fn main() -> kevy_embedded::KevyResult<()> {
    let store = Store::open(Config::default())?;

    // m / ef of 0 select the defaults (16 / 200);
    // distance: 0 = cosine, 1 = l2, 2 = ip.
    store.idx_create_ann(b"embs", b"doc:", b"v", AnnSpec {
        dim: 4, distance: 0, m: 0, ef: 0,
    })?;

    let v1: Vec<u8> = [0.1f32, 0.2, 0.3, 0.4]
        .iter().flat_map(|f| f.to_le_bytes()).collect();
    store.hset(b"doc:1", &[
        (b"title".as_slice(), b"intro".as_slice()),
        (b"v".as_slice(), v1.as_slice()),
    ])?;

    // Nearest neighbors ascending: Vec<(key, distance)>.
    // ef = 0 takes the engine default beam width.
    let hits = store.idx_knn(b"embs", &[0.1, 0.2, 0.3, 0.4], 10, 0)?;
    for (key, dist) in &hits {
        println!("{} {dist}", String::from_utf8_lossy(key));
    }
    Ok(())
}
```

`idx_knn` returns `KevyResult<Vec<(Vec<u8>, f32)>>` (`k` clamps to
1..=1000); `KevyError::NotFound` names a missing index,
`KevyError::InvalidInput` a bad `AnnSpec` (zero dim, unknown
distance tag). Embedded builds are synchronous — `idx_create_ann`
returns when the index serves. No `FIELDS` hydration in-process:
read fields with `hget`.

## Wire format

A vector field holds `dim × 4` bytes of little-endian f32 (the
RediSearch convention). Wrong length or non-finite values exclude the
row (counted, visible in VERIFY) — same discipline as scalar coercion
failures. Query vectors use the same format; `csv:1.0,2.5,…` is
accepted for debugging.

## Distances and results

`cosine` (default; vectors are normalized at insert — the stored copy
is unit length), `l2` (squared euclidean), `ip` (negative inner
product). Every metric is oriented "smaller = closer", so cross-shard
results merge with one ascending sort. `LIMIT` caps at 1000; no
cursor (deep ANN pagination is an anti-pattern).

Per-shard graphs are independent (index-follows-key, zero cross-shard
write coordination); a query fans out, takes each shard's top-k, and
merges.

## Recall: the EF knob

`EF` (16-4096, default max(4·LIMIT, 100)) is the query beam width —
the canonical HNSW recall/latency knob. Dense near-duplicate regions
need wider beams (measured on a 20k cluster @128d: EF 64 → 0.67
recall@10, 100 → 0.77, 400 → the ≥ 0.90 gate line). Embedded:
`idx_knn(…, ef)` (0 = default).

Recall is gated ≥ 0.90 at EF 400 against exact brute-force ground
truth by [`bench/vectorgate.sh`](https://github.com/goliajp/kevy/blob/main/bench/vectorgate.sh) — on a
realistic corpus geometry (an intrinsic-dimension-20 manifold in
128d; ambient-uniform random vectors suffer distance concentration
and represent nothing). If your recall matters, measure it on YOUR
corpus with a brute-force sample exactly the way the gate does, and
tune EF per query, not per index.

## Parameters, deletes, rebuild

`M` (links per node per layer, 4-64) and `EF` (construction beam,
16-1024) are **immutable once created** — changing them means DROP +
re-CREATE. Neighbor selection uses the diversity heuristic (Malkov
Alg. 4), which preserves bridge links to outlying regions.

Deletes tombstone the graph node (it keeps routing, stops matching);
updates tombstone + reinsert. `IDX.VERIFY` reports vectors / bytes /
tombstones and flags `rebuild_recommended` past 30% dead;
`IDX.REBUILD` re-inserts the living per shard (bounded O(n · ef_construction · M · dim) work — every living key goes back through the full HNSW insert, so the neighbour cap M and the dimensionality both multiply in,
answer-preserving — asserted in e2e). Graphs are derived state: never
persisted, rebuilt from data after restart. On the server that
restart rebuild is a background backfill — queries answer
`-INDEXBUILDING` until it completes ([indexes.md](https://kevy.golia.jp/docs/indexes/));
embedded rebuilds are synchronous.

## Filtering, and hybrid retrieval

No filter-during-search (partition predicates inside the graph walk
are the query-engine slope): KNN first, then hydrate with `FIELDS`
and filter client-side.

The one server-side composition that IS built in: an ANN index and a
text index over the same corpus fuse with reciprocal-rank fusion —

```
IDX.QUERY HYBRID posts MATCH "rust storage" embs KNN <f32-le-blob>
    [LIMIT n] [RRFK k] [EF ef] [FIELDS f…]
```

— rank-based (`Σ 1/(k + rank_i)`, `RRFK` default 60), so BM25 scores
and vector distances need no calibration against each other. See
[text-search.md](https://kevy.golia.jp/docs/text-search/) for the MATCH half. Embedded
callers run `idx_knn` + `idx_match` and fuse in-process.

**Multi-modal caveat**: navigation graphs degrade on corpora made of
far-separated modes (inter-mode gaps ≫ intra-mode distances, e.g.
two disjoint tenants' embeddings in one index) — late inserts in one
mode can't discover the other, starving the graph of bridges. Real
embedding corpora are continuous manifolds and don't trigger this;
if your data is strongly multi-modal, index the modes separately
(one index per prefix — they're cheap and independent).

## Consistency

Same envelope as every index kind ([indexes.md](https://kevy.golia.jp/docs/indexes/)): a
write and its graph update are atomic within the owning shard;
cross-shard queries merge per-shard top-k without a global snapshot
(SCAN-class). The catalog persists in a data-dir sidecar; graph
CONTENT is derived state, rebuilt after restart.

## Performance

Measured envelope (receipts in the bench tree):

- [`bench/vectorgate.sh`](https://github.com/goliajp/kevy/blob/main/bench/vectorgate.sh) gates KNN LIMIT 10
  p95 < 30ms at 1M × 128d against a real server, with recall ≥ 0.90
  at EF 400 holding simultaneously (both clamps at once — a fast
  wrong answer doesn't pass), plus the memory formula against real
  RSS growth (0.5-1.5×).
- [`bench/PERF-LEDGER.md`](https://github.com/goliajp/kevy/blob/main/bench/PERF-LEDGER.md) records the
  comparative shootout: recall-aligned at 1.000, KNN answers in
  0.48 ms vs 0.79 ms — **1.64× ahead** of the RediSearch HNSW on
  the same corpus.

Write-side cost is the standard index tax (one field parse + one
graph insert per matching index per write); construction cost scales
with `EF` (construction beam), which is why it is a declaration-time
parameter.

## Sizing

`bytes ≈ vectors × (dim×4 + 40) + links × 8 + vectors × 32`, reported
live by `IDX.VERIFY`/`IDX.LIST`. Cosine keeps only the normalized
copy (single copy — the raw field bytes stay in the row itself).
1M × 1024d ≈ 4.1 GiB plus links. The gate checks the formula against
real RSS growth (0.5-1.5×).

## See also

- [indexes.md](https://kevy.golia.jp/docs/indexes/) — the index engine this kind plugs into
  (declaration grammar, backfill contract, consistency envelope).
- [text-search.md](https://kevy.golia.jp/docs/text-search/) — the BM25 kind and the other
  half of `HYBRID`.
- [verb-reference.md](https://kevy.golia.jp/docs/verb-reference/) — generated grammar for
  every `IDX.*` form.
- [cookbook.md](https://kevy.golia.jp/docs/cookbook/) — retrieval recipes in context.

==============================================================================
# text-search
==============================================================================

# Full-text search (`KIND text`)

Text is the index engine's third kind: declare it like any index and
the field's raw bytes tokenize into a per-shard inverted segment,
maintained synchronously with every write (zero drift, same
derived-by-construction discipline as `range`/`unique`). There is no
separate search server, no ingestion pipeline, and no analyzer
configuration — one verb declares the index, and every subsequent
write keeps it exact.

```
IDX.CREATE posts ON PREFIX post: FIELD body TYPE str KIND text
IDX.QUERY posts MATCH "rust 全文检索" LIMIT 10 [FIELDS title body]
```

## Quick start (server)

Rows are hash keys under the declared prefix; the indexed value is
one declared field, exactly as with `range` indexes
([indexes.md](https://kevy.golia.jp/docs/indexes/)):

```console
kevy-cli -p 6004 IDX.CREATE posts ON PREFIX post: FIELD body TYPE str KIND text
kevy-cli -p 6004 HSET post:1 title "intro" body "kevy is a pure-Rust key-value store"
kevy-cli -p 6004 HSET post:2 title "search" body "dictionary-free CJK full-text search"
kevy-cli -p 6004 IDX.QUERY posts MATCH "full-text rust" LIMIT 10
```

The reply is a flat array of `key, score` pairs, best first. Add
`FIELDS` to hydrate named hash fields on each hit's owning shard in
the same call (no second round-trip):

```console
kevy-cli -p 6004 IDX.QUERY posts MATCH "search" LIMIT 10 FIELDS title
```

Supporting verbs work on text indexes like on every other kind:

- `IDX.EXPLAIN posts MATCH "full-text rust"` — the parse without the
  execution: kind, build state, estimated rows, and the plan line.
- `IDX.VERIFY posts` / `IDX.LIST` — entries / bytes / postings /
  token statistics, live.
- `IDX.DROP posts` — drop the declaration (catalog mutation,
  sidecar-persisted).

`MATCH` accepts `LIMIT` (≤ 1000) and `FIELDS`; there is no `CURSOR`
form (see "Matching and ranking" for why).

## Quick start (embedded)

Same engine in-process. The text kind is behind the `text` cargo
feature (on by default; `idx_create` with `IndexKind::Text` answers
`KevyError::Unsupported` when compiled out):

```rust
use kevy_embedded::{Config, IndexKind, IndexValType, Store};

fn main() -> kevy_embedded::KevyResult<()> {
    let store = Store::open(Config::default())?;

    store.idx_create(b"posts", b"post:", b"body", IndexValType::Str,
                     IndexKind::Text)?;   // builds synchronously
    store.hset(b"post:1", &[
        (b"title".as_slice(), b"intro".as_slice()),
        (b"body".as_slice(),
         b"kevy is a pure-Rust key-value store".as_slice()),
    ])?;

    // BM25-ranked hits, best first: Vec<(key, score)>.
    let hits = store.idx_match(b"posts", b"rust store", 10)?;
    for (key, score) in &hits {
        println!("{} {score}", String::from_utf8_lossy(key));
    }
    Ok(())
}
```

`idx_match` returns `KevyResult<Vec<(Vec<u8>, f64)>>`;
`KevyError::NotFound` names a missing index. There is no `FIELDS`
hydration embedded — you are in-process, read fields with `hget`.
Embedded builds are synchronous: `idx_create` returns when the index
serves (no `-INDEXBUILDING` phase to poll).

## Tokenization (dictionary-free)

- Latin/alphanumeric runs → lowercased word tokens (length ≥ 2).
- CJK (unified ideographs, kana, hangul) → **adjacent bigrams** —
  「全文检索」 indexes as 全文/文检/检索, so any two-character
  substring query matches without a dictionary. A lone CJK character
  emits itself.
- Tokens never cross a script boundary; queries tokenize with the
  same rules.

The bigram scheme is the whole CJK story: no dictionary to ship, no
dictionary to go stale, and mixed-script documents (`"Rust 入门"`)
index both halves under their own rules. The cost is recall noise on
one-character CJK queries (they match only lone-character emissions)
— query with two or more characters.

## Matching and ranking

`MATCH` is **OR semantics over query tokens, BM25-ranked** (k1=1.2,
b=0.75, non-negative idf variant). Documents matching more (and
rarer) query terms rank higher; term frequency saturates; long
documents are normalized down.

Two declared approximations:

- **Scores are shard-local.** df/avgdl come from each shard's own
  corpus (global statistics would require cross-shard write
  coordination). With hash-sharded keys the statistics converge
  across shards and the merged ranking is stable; scores from
  different shards are comparable, not identical to a single-corpus
  run.
- **No cursor.** BM25 deep pagination is an anti-pattern (page N
  requires re-scoring everything above it); `LIMIT` caps at 1000.

No phrase queries, no boolean syntax, no highlighting — that's the
query-engine slope (deliberately out of scope). If you need those,
you are describing a search engine; kevy's text kind stops at
"ranked lookup over declared fields".

## Hybrid retrieval (BM25 + KNN)

A text index and an ANN index over the same corpus fuse server-side
with reciprocal-rank fusion:

```
IDX.QUERY HYBRID posts MATCH "rust storage" embs KNN <f32-le-blob>
    [LIMIT n] [RRFK k] [EF ef] [FIELDS f…]
```

Each hit's fused score is `Σ 1/(k + rank_i)` over the two result
lists (`RRFK` default 60 — the standard fusion constant; rank
positions, not raw scores, so BM25 and distance need no calibration
against each other). See [vector-search.md](https://kevy.golia.jp/docs/vector-search/) for
the KNN half. Hybrid is a server verb; embedded callers run
`idx_match` + `idx_knn` and fuse in-process.

## Lifecycle and consistency

Same envelope as every index kind ([indexes.md](https://kevy.golia.jp/docs/indexes/)):

- A write and its segment update are **atomic within the owning
  shard** (single reactor thread / shard lock). An update removes
  exactly the old document's tokens and inserts the new ones —
  documents keep their original text for this, so there is no
  tombstone drift.
- A row whose declared field is missing simply contributes no
  tokens; there is no coercion failure for `TYPE str` text fields.
- Cross-shard queries merge per-shard top-K without a global
  snapshot (SCAN-class, same as `DBSIZE`).
- **Server backfill is asynchronous**: after `IDX.CREATE` on a live
  keyspace, or after a restart, queries answer `-INDEXBUILDING`
  until the rebuild completes (data availability never waits for
  index builds; poll or retry — see [indexes.md](https://kevy.golia.jp/docs/indexes/)).
  Embedded builds are synchronous.
- Inverted segments are **derived state** — never snapshotted or
  AOF-logged, rebuilt from data after restart.
- `MAXMEM` (on `IDX.CREATE`) caps the segment's memory; a build that
  crosses the budget fails declaratively (`-INDEXOVERBUDGET` on
  queries) instead of growing unbounded.

## Performance

Top-K evaluation uses MaxScore pruning (rarest terms first; commoner
lists are probed per candidate once they can't lift new documents
into the top K). Postings are doc-id inverted lists impact-ordered
two ways: tf buckets descending, sparse log2 dl bands ascending
inside each bucket — a single-term query (no second list to prune
against) stops exactly at the first band whose lower edge can't beat
the kth floor, so even the most common term answers in ~0.1ms at
200k docs (was ~6ms as a full postings scan). One-posting tokens
(the Zipf long tail) stay inline and cost no heap.

Measured envelope (receipts in the bench tree):

- [`bench/textgate.sh`](https://github.com/goliajp/kevy/blob/main/bench/textgate.sh) gates `MATCH` p95
  < 20ms at 1M mixed-script documents (~100 bytes each) against a
  real server, plus the memory formula against real RSS growth.
  It runs in CI-adjacent release checks — the numbers are clamps,
  not aspirations.
- [`bench/PERF-LEDGER.md`](https://github.com/goliajp/kevy/blob/main/bench/PERF-LEDGER.md) records the
  comparative shootout: BM25 top-10 at +21% qps with a p95 tie
  against RediSearch's `FT.SEARCH` on the same corpus.

The write side is the standard index tax: one hash-field read plus
one segment update per matching index per write; an empty catalog
costs one untaken branch per write.

## Sizing

`bytes ≈ Σ_token (token_len + 48) + postings × 64 + Σ_doc (key_len +
text_len + 72)` (docs keep their original text so updates remove
exactly their own tokens), reported live by `IDX.VERIFY` /
`IDX.LIST` (entries/bytes/postings/tokens for text kinds).
`bench/textgate.sh` gates the formula against real RSS growth.

Rebuild rides the standard backfill skeleton (tick-incremental on
the server, synchronous embedded).

## See also

- [indexes.md](https://kevy.golia.jp/docs/indexes/) — the index engine this kind plugs into
  (declaration grammar, cursor contract, consistency envelope).
- [vector-search.md](https://kevy.golia.jp/docs/vector-search/) — the ANN kind and the other
  half of `HYBRID`.
- [verb-reference.md](https://kevy.golia.jp/docs/verb-reference/) — generated grammar for
  every `IDX.*` form.
- [cookbook.md](https://kevy.golia.jp/docs/cookbook/) — full-text recipes in context.

==============================================================================
# views
==============================================================================

# Views (`VIEW.*` / `view_*`)

A view is a **named composition of declared indexes** — an AND/OR/DIFF
tree of index shapes with an ordering index — queryable as one unit,
either evaluated per query (**virtual**) or maintained incrementally
on every write (**materialized**, optionally top-K bounded). Views
are the engine's answer to the "hot list" query — `WHERE state =
'ready' AND pri BETWEEN 0 AND 100 ORDER BY pri DESC LIMIT 10` — as a
declared access path instead of a query-time scan.

```
IDX.CREATE j_pri  ON PREFIX job: FIELD pri  TYPE i64 KIND range
IDX.CREATE j_state ON PREFIX job: FIELD state TYPE str KIND range

VIEW.CREATE ready_jobs
    QUERY ( AND j_pri RANGE 0 100 j_state EQ ready )
    ORDER BY j_pri DESC
    MODE materialized TOPK 100
VIEW.QUERY ready_jobs LIMIT 10
```

## Quick start (server)

Everything a view composes must exist first — leaves and the ORDER
BY index are declared `IDX.*` indexes over the same prefix domain
([indexes.md](https://kevy.golia.jp/docs/indexes/)):

```console
kevy-cli -p 6004 IDX.CREATE j_pri ON PREFIX job: FIELD pri TYPE i64 KIND range
kevy-cli -p 6004 IDX.CREATE j_state ON PREFIX job: FIELD state TYPE str KIND range
kevy-cli -p 6004 VIEW.CREATE ready_jobs QUERY ( AND j_pri RANGE 0 100 j_state EQ ready ) ORDER BY j_pri DESC MODE materialized TOPK 100
kevy-cli -p 6004 HSET job:1 pri 10 state ready
kevy-cli -p 6004 HSET job:2 pri 99 state blocked
kevy-cli -p 6004 VIEW.QUERY ready_jobs LIMIT 10
```

The reply pages `key, order-value` pairs in view order with a resume
`CURSOR`. The tree grammar (one line, parenthesized):

```
tree     = '(' AND|OR|DIFF sub sub ')' | leaf
leaf     = <index> RANGE <min> <max> | <index> EQ <value>
```

Supporting verbs: `VIEW.LIST` (catalog + mode + shape),
`VIEW.EXPLAIN name` (the tree with per-leaf cardinalities),
`VIEW.VERIFY name` (members / bytes / order-exclusions — **bytes and
order-exclusions are materialized-only**; a virtual view stores nothing and
reports both as 0, and verifying one costs a full fresh `eval_tree`, which is
the one place a virtual view is the expensive one),
`VIEW.REBUILD name` (force a materialized rebuild — answer-
preserving), `VIEW.DROP name`.

## The three structural rules

1. **Components are named indexes.** Leaves carry a shape (`RANGE min
   max` | `EQ v`, coerced to the referenced index's type at CREATE);
   the view layer holds no predicates of its own. Trees are depth ≤ 3,
   ≤ 4 leaves; `AND`/`OR` may be re-ordered by the engine, `DIFF` is
   fixed left-minus-right.
2. **A view stores membership + order only** — never field values.
   `ORDER BY <index>` supplies the sort key; rows absent from the
   order index are excluded (counted, visible in `VIEW.VERIFY`).
3. **Hydration is dereference, not query.** `VIA <template>` (e.g.
   `user:{key.1}`; `{key}` = member key, `{key.N}` = its N-th
   `:`-segment) maps each member to a target key; `VIEW.QUERY …
   FIELDS f…` reads those fields on the targets' owning shards in a
   second internal fan-out. Missing target = nil row fields. Targets
   take no predicates.

## Modes and cost model

- **Virtual** — evaluated at query time by streaming the ORDER index
  in order and probing tree membership per candidate: a LIMIT-100
  page costs O(limit / selectivity) probes, not O(members). Always
  fresh; zero write cost. The failure mode is a highly selective
  tree under a large ORDER domain (many candidates probed per
  emitted row) — that shape wants materialization.
- **Materialized** — an ordered member set per shard, updated in the
  same write hook that maintains indexes (one probe per referenced
  index per write, shared across all views). `TOPK k` bounds it to
  `k + k/4`, evicting from the view's worst end; a non-member worse
  than the current worst is rejected with a single comparison — the
  steady-state write tax measured by
  [`bench/viewgate.sh`](https://github.com/goliajp/kevy/blob/main/bench/viewgate.sh) is ~2% for 3 indexes +
  4 top-K views (the gate clamps it < 15%). Shrinking below `k`
  schedules a local per-shard rebuild (next tick). Unbounded
  materialized views pay O(log members) per affected write.
  - Right after `VIEW.CREATE`, expect a brief settling window (the
    first write burst over a fresh top-K set runs slower while the
    eviction threshold stabilizes).

Choosing: a dashboard top-100 over a high-write domain wants
`MODE materialized TOPK 100` (bounded memory, O(1) rejection of
non-contenders); an occasionally-paged report over a moderate domain
wants `MODE virtual` (zero write tax, always fresh). `VIEW.EXPLAIN`
shows per-leaf cardinalities — the selectivity data for the call.

### DIFF: the declared anti-join

`DIFF` is left-minus-right and NOT commutative — the one tree node
whose children the engine never re-orders. The canonical use is
"eligible but not excluded":

```
VIEW.CREATE assignable
    QUERY ( DIFF j_pri RANGE 0 100 j_state EQ quarantined )
    ORDER BY j_pri DESC
    MODE virtual
```

— every job in the working priority band, minus the quarantined
ones.

In SQL terms this is the `WHERE … AND NOT EXISTS (…)` shape — as a
declared access path instead of a per-query subquery
([rds-workloads.md](https://kevy.golia.jp/docs/rds-workloads/) maps the rest of that
vocabulary).

## Consistency

Same envelope as indexes ([indexes.md](https://kevy.golia.jp/docs/indexes/)): per-shard
atomic with the triggering write, cross-shard merged without a
global snapshot (SCAN-class).

- Queries answer `-INDEXBUILDING` while any referenced index is
  still backfilling (a partial index would silently misreport
  membership) — same retry discipline as index queries.
- `VIEW.REBUILD` is answer-preserving (asserted in the e2e suite);
  `VIEW.VERIFY` makes drift falsifiable (members / bytes /
  order-exclusions).
- The view catalog persists in a data-dir sidecar; materialized
  CONTENT is derived state — rebuilt after restart, never
  snapshotted.

## Embedded

Typed API behind the `index` cargo feature (on by default) — the
tree is passed as a value, no text grammar in-process, and every
call returns `KevyResult` (4.0's single error currency):

```rust
use kevy_embedded::{
    Config, IndexKind, IndexValType, IndexValue, Store, ViewLeaf,
    ViewMode, ViewTree,
};

fn main() -> kevy_embedded::KevyResult<()> {
    let store = Store::open(Config::default())?;
    store.idx_create(b"j_pri", b"job:", b"pri", IndexValType::I64,
                     IndexKind::Range)?;
    store.idx_create(b"j_state", b"job:", b"state", IndexValType::Str,
                     IndexKind::Range)?;

    let tree = ViewTree::And(
        Box::new(ViewTree::Leaf(ViewLeaf {
            index: b"j_pri".to_vec(),
            min: IndexValue::I64(0),
            max: IndexValue::I64(100),
        })),
        Box::new(ViewTree::Leaf(ViewLeaf {
            index: b"j_state".to_vec(),
            min: IndexValue::Str(b"ready".to_vec()),
            max: IndexValue::Str(b"ready".to_vec()),   // EQ = same min/max
        })),
    );
    store.view_create(b"ready_jobs", tree, b"j_pri", /*desc*/ true,
                      ViewMode::Materialized { top_k: 100 })?;

    store.hset(b"job:1", &[
        (b"pri".as_slice(), b"10".as_slice()),
        (b"state".as_slice(), b"ready".as_slice()),
    ])?;

    // One page: (Vec<(key, order_value)>, Option<resume_cursor>).
    let (rows, _next) = store.view_query(b"ready_jobs", None, 10)?;
    for (key, val) in &rows {
        println!("{} {val:?}", String::from_utf8_lossy(key));
    }
    Ok(())
}
```

- `view_create(name, tree, order_by, desc, mode)` builds
  synchronously; every referenced index (leaves + ORDER BY) must
  already be declared (`KevyError::InvalidInput` otherwise).
- `view_query(name, after, limit)` pages `(key, order_value)` rows;
  the returned cursor resumes exclusively (DESC views page from the
  large end). `view_count` / `view_list` / `view_drop` complete the
  face.
- No `VIA`/`FIELDS` — in-process callers dereference and read fields
  directly with `hget`.

## Performance

Measured envelope — the clamps live in
[`bench/viewgate.sh`](https://github.com/goliajp/kevy/blob/main/bench/viewgate.sh), run against a real
server at 1M rows:

- Virtual `VIEW.QUERY` p99 < 3ms (two-component tree).
- Materialized `VIEW.QUERY` p99 < 2ms (the index-read line — a
  materialized page IS an ordered-set read).
- Write tax with 3 indexes + 4 materialized top-K views < 15% vs the
  same workload with indexes only (measured steady-state ~2%).
- Memory per member within ±20% of the formula below.

Memory per member ≈ `order_value_width + key_len + 48` bytes,
reported live by `VIEW.VERIFY`.

## See also

- [indexes.md](https://kevy.golia.jp/docs/indexes/) — the indexes views compose (declaration,
  backfill, the consistency envelope views inherit).
- [rds-workloads.md](https://kevy.golia.jp/docs/rds-workloads/) — where views sit in the
  SQL-to-kevy mapping.
- [verb-reference.md](https://kevy.golia.jp/docs/verb-reference/) — generated grammar for
  every `VIEW.*` form.
- [cookbook.md](https://kevy.golia.jp/docs/cookbook/) — view recipes in context.

==============================================================================
# cdc
==============================================================================

# CDC — the change feed (`FEED.*` / `changes_since`)

kevy exposes every applied write as a consumable change stream — the
same effect frames the AOF logs and replicas apply. Typical consumers:
cache invalidators, search-index updaters, downstream mirrors — the
jobs an "outbox table" does in an RDS stack, without the table.

Enable it in config:

```toml
[feed]
enabled = true
# feed_buffer_size = "64mb"   # per shard, caps at 1gb
```

or embedded: `Config::default().with_feed(0)`.

## The cursor: `(generation, offset)`

Every stream position is a `(generation, offset)` pair:

- `offset` increases by one per applied write within a generation.
- `generation` identifies one unbroken offset history. A given
  `(generation, offset)` refers to the same stream prefix **forever**.
- A **clean shutdown + restart preserves both** — consumers resume
  where they left off.
- Continuity breaks bump the generation and restart offsets at 0:
  `FLUSHALL`, restoring from a snapshot, or an **unclean shutdown**
  (crash). A bumped generation tells consumers their view may be
  stale: rebuild, then resume.

## Server surface

- `FEED.SHARDS` → `:N` — number of independent streams (one per
  shard; keys map to shards, so **per-key order is guaranteed** within
  a stream; there is no cross-shard order).
- `FEED.TAIL <shard>` → `*2 [:generation, :next_offset]` — the cursor
  a fresh consumer starts from.
- `FEED.READ <shard> <gen> <offset> [COUNT n] [PREFIX p ...]` →
  `*3 [:generation, :next_cursor, *frames]`, each frame
  `*2 [:offset, *argv]`. Poll it; an empty frame list means caught up.
  - `COUNT` caps frames per call (default 256, max 4096).
  - `PREFIX` (repeatable, OR) filters frames by key prefix
    **fail-open**: frames whose key layout isn't the plain
    single-key shape (multi-key `DEL`, `MSET`, `FLUSHALL`, …) are
    always delivered. Filtering never changes the cursor — you can
    change filters without resyncing.

### Errors

- `-FEEDRESYNC <gen> <tail>` — your cursor is unservable (older
  generation, or the offsets were evicted from the backlog). Rebuild
  your derived state (e.g. `SCAN` your prefix), then resume from the
  carried `(gen, tail)`.
- `-ERR feed cursor ahead of stream` — a cursor from the future;
  caller bug.

## Embedded surface

```rust
let store = kevy_embedded::Store::open(Config::default().with_feed(0))?;
let (gen, off) = store.changes_tail()?;             // start cursor
let batch = store.changes_since(gen, off, 256, &[b"user:"])?;
for change in &batch.changes { /* change.offset, change.argv */ }
let (gen, off) = batch.next;                        // resume here
```

`feed_shards()` reports 1 — the embedded write path serializes all
shards into one stream, so the same consumer loop works against both
surfaces. `FeedError::Resync { generation, tail }` mirrors
`-FEEDRESYNC`.

## Delivery semantics

**At-least-once.** After a resync-rebuild (and in some failover
shapes) you may see frames you already applied — consumers must be
idempotent (cache invalidation naturally is). Frames carry the applied
**effect** (e.g. a `ZINTERSTORE` appears as `DEL` + plain `ZADD`), so
applying them is deterministic regardless of source state.

**Retention** is the in-memory backlog (`feed_buffer_size` per shard):
fall behind further than the window and you get `-FEEDRESYNC`. There
is no on-disk archive — see the recovery-point contract below for the
durable story.

## Recovery-point contract (PITR)

Snapshots taken with the feed enabled record the stream cursor in
their header, frozen in the same no-append window as the snapshot
data:

> **snapshot S + the feed frames from S's cursor = the exact state at
> any later cursor.**

`kevy_persist::read_snapshot_cursor(path)` reads it back (`None` for
pre-v2.3 snapshots). A restore drill: load the snapshot into a fresh
data dir, then replay `FEED.READ` frames from the recorded cursor —
byte-exact state, verifiable with `PREFIX.STATS` / key dumps. The
drill script lives at `bench/diskgate.sh`'s restore line.

## Per-prefix stats

`PREFIX.STATS <prefix>` (server) / `Store::info_prefix` (embedded)
report live key + TTL'd key counts under a byte prefix — O(keyspace)
walk, meant for ops dashboards, not hot paths.

## What this is not

No global cross-shard order, no server-side consumer positions, no
consumer groups, no query predicates (a prefix is a byte filter). If
you need those, you are describing a message broker or an RDS — kevy's
feed stops at the event-horizon deliberately (see the three-laws
design note in the repository docs).

==============================================================================
# pubsub
==============================================================================

# Pub/sub

How publishers fan messages out to many subscribers in kevy — over the
wire with `PUBLISH` / `SUBSCRIBE`, in-process via the embedded `Store`,
and through the same URL facade that the rest of `kevy-client` uses.

## When you need this

Reach for pub/sub when one writer needs to notify zero-or-more readers
*right now*, and you do not care about messages that arrive while a
reader is offline:

- "Tell every web worker to refresh its config cache."
- "Stream just-written rows from one shard to whoever is tailing."
- "Wake a worker pool when a job lands; the job itself is in a list."
- "Dev loop: a producer thread and a consumer thread in the same
  binary, no Redis box required."

If you need durable hand-off (job queue with retries, fan-out over
restarts, message replay), use a list or stream instead — see
[`docs/persistence.md`](https://github.com/goliajp/kevy/blob/develop/docs/persistence.md)
for what gets written to disk.

## Core idea

A pub/sub channel is a name. Subscribers register interest in that
name (or a glob pattern); a publish on the same name walks the
subscriber index and enqueues one copy of the body per matching
subscriber. There is no broker queue, no offline buffer, no ack — if
nobody is listening the moment you publish, the message is gone.

```
                   publish("news", body)
                          |
                          v
             +-----------------------+
             |  channel "news"       |   <- per-channel subscriber index
             |  subscribers: [A,B,C] |
             +-----------------------+
                  |       |       |
                  v       v       v
               sub A   sub B   sub C    <- each gets its own copy
```

Internally each publish builds the wire frame once, wraps the body in
an `Arc`, and uses `writev` to scatter-gather it to every matching
TCP subscriber — so the body bytes are copied **zero** extra times
no matter how wide the fan-out. The same per-channel index handles
both server connections and in-process `Subscription` handles.

## Worked examples

### Smoke-test with `redis-cli`

Open two shells against a running kevy server:

```sh
# shell 1 — subscriber
$ redis-cli -p 6379 SUBSCRIBE news
Reading messages... (press Ctrl-C to quit)
1) "subscribe"
2) "news"
3) (integer) 1
```

```sh
# shell 2 — publisher
$ redis-cli -p 6379 PUBLISH news "hello"
(integer) 1   # one subscriber received it
```

Back in shell 1:

```
1) "message"
2) "news"
3) "hello"
```

A `PUBLISH` to a channel with no subscribers returns `(integer) 0`
and the message is dropped on the floor. That is the contract — you
do not get a "we tried to deliver this" signal.

### Rust over the URL facade — `kevy-client`

The same call shape targets a TCP server, a named in-process bus, or
a persistent in-process store; flip the URL and recompile, no
`match scheme { … }` at call sites.

```rust
use kevy_client::{Connection, Subscriber, PubsubEvent};

fn run(url: &str) -> kevy_client::KevyResult<()> {
    // Open a subscriber against `news`. The first frame the bus
    // hands back is the subscribe ack; drain it before asserting
    // on bodies.
    let mut sub = Subscriber::connect_channels(url, &[b"news"])?;
    let _ack = sub.recv()?;

    let mut conn = Connection::connect(url)?;
    let received = conn.publish(b"news", b"hello")?;
    assert_eq!(received, 1);

    match sub.recv()? {
        PubsubEvent::Message { channel, payload } => {
            assert_eq!(channel, b"news");
            assert_eq!(payload, b"hello");
        }
        other => panic!("unexpected frame: {other:?}"),
    }
    Ok(())
}

// Dev:  in-process shared bus by name.
run("mem://app")?;
// Prod: real TCP server.
run("kevy://prod-cache:6379")?;
# Ok::<(), kevy_client::KevyError>(())
```

Cross-thread is the same code with one `Subscriber` and one
`Connection` opened against the same URL from different threads —
the `mem://<name>` registry hands both ends the same backing bus, so
the producer thread can `Connection::publish` and the consumer
thread blocks in `sub.recv()`.

### In-process via `kevy-embedded`

When the embedding code already has a `Store`, skip the URL
indirection and talk to the bus directly:

```rust
use kevy_embedded::{Config, PubsubFrame, Store};

let store = Store::open(Config::default().with_ttl_reaper_manual())?;

// Subscriber owns the receive queue.
let sub = store.subscribe(&[b"jobs"]);
let _ack = sub.recv()?; // PubsubFrame::Subscribe

// Any clone of `store` reaches the same bus.
let writer = store.clone();
assert_eq!(writer.publish(b"jobs", b"compute-pi"), 1);

match sub.recv()? {
    PubsubFrame::Message { channel, payload } => {
        assert_eq!(channel, b"jobs");
        assert_eq!(payload, b"compute-pi");
    }
    other => panic!("unexpected frame: {other:?}"),
}
# Ok::<(), kevy_embedded::KevyError>(())
```

`Store::clone` is cheap (it's an `Arc` bump), so the common shape is
"hand each thread a `store.clone()` and let it `publish` or
`subscribe` whenever it needs to." Subscribers drop unregisters
atomically; a panicking consumer thread does not leave a zombie
entry in the index.

### Pattern subscriptions

`PSUBSCRIBE` registers a glob and receives messages on every channel
that matches it. The glob syntax — `*`, `?`, `[abc]` — is the same
matcher `KEYS` and `SCAN` use.

```rust
use kevy_client::{Connection, Subscriber, PubsubEvent};

let mut sub = Subscriber::connect("mem://signals")?;
sub.psubscribe(&[b"news.*"])?;
let _ack = sub.recv()?;            // PubsubEvent::Psubscribe

let mut conn = Connection::connect("mem://signals")?;
conn.publish(b"news.tech", b"breaking")?; // matches
conn.publish(b"weather",   b"sunny")?;    // does NOT match

match sub.recv()? {
    PubsubEvent::Pmessage { pattern, channel, payload } => {
        assert_eq!(pattern, b"news.*");
        assert_eq!(channel, b"news.tech");
        assert_eq!(payload, b"breaking");
    }
    other => panic!("unexpected frame: {other:?}"),
}
# Ok::<(), kevy_client::KevyError>(())
```

A subscriber that holds both a channel subscription **and** a
matching pattern subscription receives **two** copies — one
`Message`, one `Pmessage`. Per-publish dedup only suppresses the
"same `Subscription` listed twice in the same channel index"
duplicate, not channel-vs-pattern overlap.

## Keyspace notifications

kevy can announce keyspace changes over pub/sub, Redis-style: a write
to `user:42` fires `__keyspace@0__:user:42` (payload = the event
name, e.g. `set`) and/or `__keyevent@0__:set` (payload = the key).
kevy serves DB 0 only, so the channel names always carry `@0`.

Off by default — with the flag string empty, every write pays one
atomic load and skips. Enable it in the config file:

```toml
[notification]
notify_keyspace_events = "KEA"   # everything, both channels
```

The flag string follows the Redis convention — channels first, then
event classes:

| flag | meaning |
|---|---|
| `K` | publish on the `__keyspace@0__:<key>` channel |
| `E` | publish on the `__keyevent@0__:<event>` channel |
| `g` | generic commands — `DEL`, `EXPIRE`, `PERSIST`, `RENAME`, … |
| `$` | string commands — `SET`, `INCR`, `APPEND`, `MSET`, … |
| `l` | list commands |
| `s` | set commands |
| `h` | hash commands |
| `z` | sorted-set commands |
| `t` | stream commands — `XADD`, `XTRIM`, `XGROUP`, … |
| `x` | `expired` events — a TTL'd key removed (lazily on access or by the reaper) |
| `e` | `evicted` events — a key removed by `maxmemory` pressure |
| `n` | `new` events — a key added to the keyspace |
| `A` | alias for `g$lshztxe` (every class except `n`, matching Redis) |

At least one of `K`/`E` plus at least one event class must be set for
anything to fire. An unknown character in the string is a **config
error at startup** — a typo'd flag string refuses admission instead
of silently dropping events. Subscribe with an ordinary pattern
subscription:

```sh
redis-cli -p 6379 PSUBSCRIBE '__keyevent@0__:*'
```

Notification delivery rides the same at-most-once pub/sub bus as
everything else on this page: no subscriber at publish time means the
event is gone. Consumers that must not miss changes belong on the CDC
feed ([`docs/cdc.md`](https://github.com/goliajp/kevy/blob/develop/docs/cdc.md)),
which is cursored and replayable — keyspace notifications are the
"wake up" signal, not the ledger.

## URL backend table

| URL                                | Backing store              | Shared across opens?                              | Cross-process visible? |
|------------------------------------|----------------------------|---------------------------------------------------|-----------------------|
| `mem://`                           | in-process, anonymous      | **No** — each open gets a fresh `Store`           | No                    |
| `mem://<name>`                     | in-process, named registry | **Yes** — same `<name>` ⇒ same `Store`            | No                    |
| `file:///abs/path`                 | in-process + AOF/snapshot  | **Yes** — same path ⇒ same `Store`, persists      | No                    |
| `kevy://host[:port][/db]`          | TCP kevy server            | One socket per open; server-side fan-out          | **Yes**               |
| `redis://host[:port][/db]`         | TCP — alias of `kevy://`   | same                                              | **Yes**               |
| `tcp://host[:port]`                | TCP — raw, no leading `SELECT` | same                                          | **Yes**               |

Anonymous `mem://` cannot receive published messages — nothing else
can reach the same backing `Store`, so `Subscriber::connect_channels` rejects
it with `KevyError::Unsupported`. Use `mem://<some-name>` whenever
you intend to publish.

`rediss://`, `kevys://`, and `redis://user:pass@…` are rejected for
the same reason: kevy ships without TLS or `AUTH`. Front the socket
with stunnel + IP allowlist at the network boundary if you need
either.

The `mem://<name>` and `file:///` registries are **per-process**:
two unrelated OS processes that open the same name see two
independent buses. Cross-process delivery means running a kevy
server and opening `kevy://host:port` from both sides.

## Trade-offs and limits

- **At-most-once delivery.** A subscriber that disconnects mid-frame
  loses that frame. There is no per-subscriber durable cursor and no
  redelivery. If a frame matters, persist it in a list or stream and
  use pub/sub only as the "wake up" signal.
- **No offline backlog.** A publish that finds zero subscribers
  returns `0` and the body is discarded. There is no buffer that
  catches a subscriber up on what it missed while disconnected.
- **Subscriber back-pressure is per-subscriber, not global.** Each
  subscriber owns its own bounded queue. A slow consumer fills its
  own queue and then drops frames or, on TCP, gets closed by the
  server's client-output-buffer policy. The publish path drops the
  bus mutex before sending, so one slow listener cannot stall
  publishes on unrelated channels — but it also cannot exert
  back-pressure on the publisher.
- **Linux `writev` cap.** On Linux, `writev` hands the kernel at most
  `IOV_MAX = 1024` iovec entries per call. The server batches the
  per-subscriber frame headers and the shared body Arc into iovecs;
  for fan-outs wider than ~340 subscribers per channel (each takes
  three iovec slots) the server splits into multiple `writev` calls
  automatically. The cap shows up only as a soft performance
  ceiling, never as a delivery failure.
- **Subscribed clients are restricted.** A `Subscriber` connection
  rejects non-pub/sub commands; that is why `kevy-client` exposes
  publisher and subscriber as **two separate types** sharing the
  same URL.

## Operational introspection

The standard `PUBSUB` admin subcommand works on both the TCP server
and the URL facade — open a normal `Connection`, not a `Subscriber`,
to call them.

| Subcommand              | Returns                                                                        |
|-------------------------|--------------------------------------------------------------------------------|
| `PUBSUB CHANNELS [pat]` | Array of channels with at least one subscriber, optionally glob-filtered.      |
| `PUBSUB NUMSUB [ch …]`  | Interleaved `channel, count` pairs for each named channel (0 if absent).       |
| `PUBSUB NUMPAT`         | Integer: number of distinct `PSUBSCRIBE` patterns registered, across clients.  |

```sh
$ redis-cli -p 6379 PUBSUB CHANNELS '*'
1) "news"
2) "jobs"
$ redis-cli -p 6379 PUBSUB NUMSUB news jobs missing
1) "news"
2) (integer) 3
3) "jobs"
4) (integer) 1
5) "missing"
6) (integer) 0
$ redis-cli -p 6379 PUBSUB NUMPAT
(integer) 2
```

All three are O(channels) or O(args) point lookups against the
per-shard pub/sub registry; safe to poll from monitoring agents.

## FAQ

**Will a message arrive if the subscriber connected after the
publish?**  No. Pub/sub has no replay. The subscriber index is
consulted at publish time; later subscribers see only frames
published *after* their subscribe ack lands.

**Does `PUBLISH` block the publisher until subscribers drain?**  No.
The publisher's `publish` call returns once the body has been
queued onto every matching subscriber's per-subscriber queue (and,
for TCP subscribers, scheduled onto their socket's write queue). A
slow subscriber holds up its own queue, not yours.

**Can I share one `Subscriber` between async tasks?**  Yes — wrap it
in an `Arc` and `spawn_blocking` the `recv` call. The receive mutex
serialises blocking waits, so each frame is delivered to **exactly
one** task. For real broadcast fan-out (every task sees every
frame), open one `Subscriber` per task — they are cheap. See
[`docs/async.md`](https://github.com/goliajp/kevy/blob/develop/docs/async.md)
for the full async pattern.

**Why does my test see the subscribe ack before any messages?**  The
bus is ordered, but every `SUBSCRIBE` / `PSUBSCRIBE` enqueues an ack
frame *before* the first body frame for that channel arrives. Drain
the ack with one `sub.recv()?` before asserting on payloads — this
matches the redis-cli wire shape.

**Do I need cluster routing for pub/sub?**  No. Pub/sub fan-out is
process-level, not slot-routed: publishing on any shard's port
reaches every subscriber on every shard's port in the same process.
A plain `Connection::connect("kevy://host:port")` against any shard
port works. See
[`docs/cluster.md`](https://github.com/goliajp/kevy/blob/develop/docs/cluster.md)
for the slot routing that *keyspace* commands use.

==============================================================================
# lua
==============================================================================

# Lua scripting

Server-side Lua scripting in kevy: how to run atomic scripts with `EVAL` / `EVALSHA`, what bindings exist, and how to opt into Lua dialects newer than 5.1.

## When you need this

Reach for Lua scripting when you want to:

- Execute a small multi-command sequence atomically against one key (check-then-set, conditional counters, distributed locks).
- Push read-modify-write logic that a single command can't express into the server, eliminating round trips.
- Run a script published by an ecosystem library (BullMQ, Sidekiq, Bee Queue, Redlock, sliding-window rate limiters) unchanged.

For ordinary single-command access or for transactions across many keys with explicit optimistic locking, use plain commands or `MULTI` / `EXEC` instead.

## Core idea

`EVAL` ships a Lua source string to the server, compiles it, and runs it on the shard that owns `KEYS[1]`. While the script runs, no other command on that shard interleaves with it — the whole script is one atomic unit. Inside the script, `redis.call("CMD", ...)` dispatches back through the normal command path, `KEYS` and `ARGV` give 1-indexed binary-safe access to the inputs, and the script's return value is marshaled to RESP. Loaded scripts are cached by SHA1, so `SCRIPT LOAD` + `EVALSHA` lets clients send the hash instead of the body on every call. The Lua runtime is [luna](https://github.com/goliajp/luna), a pure-Rust 5.1 – 5.5 interpreter. Default dialect is Lua 5.1 (matching what every Redis-ecosystem script expects); a one-line shebang opts a single script into 5.2, 5.3, 5.4, or 5.5.

## Worked example: capped counter

The script bumps a counter by 1, but only if the new value would stay at or below a cap. Returns the new value, or `nil` if the cap would be exceeded.

```lua
-- KEYS[1] = counter key
-- ARGV[1] = cap (integer)
local cur = tonumber(redis.call("GET", KEYS[1]) or "0")
local cap = tonumber(ARGV[1])
if cur + 1 > cap then
  return nil
end
return redis.call("INCR", KEYS[1])
```

### Inline via `EVAL`

```sh
redis-cli -p 6004 EVAL \
  "local cur = tonumber(redis.call('GET', KEYS[1]) or '0')
   local cap = tonumber(ARGV[1])
   if cur + 1 > cap then return nil end
   return redis.call('INCR', KEYS[1])" \
  1 quota:user:42 5
# (integer) 1
# … four more calls …
# (integer) 5
# next call:
# (nil)
```

### Cached via `SCRIPT LOAD` + `EVALSHA`

```sh
SHA=$(redis-cli -p 6004 SCRIPT LOAD \
  "local cur = tonumber(redis.call('GET', KEYS[1]) or '0')
   local cap = tonumber(ARGV[1])
   if cur + 1 > cap then return nil end
   return redis.call('INCR', KEYS[1])")
echo "$SHA"
# e.g. 7c3e0a9b1d4f...

redis-cli -p 6004 EVALSHA "$SHA" 1 quota:user:42 5
# (integer) 1

redis-cli -p 6004 SCRIPT EXISTS "$SHA"
# 1) (integer) 1
```

If a client sends `EVALSHA` for a hash the server has never seen (cold start, `SCRIPT FLUSH`), kevy returns `-NOSCRIPT` and the client should fall back to `EVAL`. The script body cached by SHA1 includes any shebang line, so a 5.1 and a 5.4 copy of the same source are distinct cache entries.

### Lua 5.4 dialect via shebang

```lua
#!lua version=5.4
-- ARGV[1] = max retries before giving up
local tries = tonumber(ARGV[1])
local i = 0
::again::
i = i + 1
local ok = redis.call("SET", KEYS[1], "owned", "NX", "PX", 3000)
if type(ok) == "table" and ok.ok == "OK" then
  return i
end
if i < tries then goto again end
return redis.error_reply("LOCK_FAILED")
```

`goto` / labels and integer-typed arithmetic are 5.3+ features; the shebang routes this one script to the 5.4 VM pool while other scripts keep running on 5.1.

## Bindings

| Symbol | Behaviour |
|---|---|
| `redis.call(cmd, ...)` | Dispatch a kevy command. RESP errors raise a Lua error and abort the script unless caught with `pcall`. |
| `redis.pcall(cmd, ...)` | Same dispatch, but RESP errors return as `{err = "msg"}` instead of raising. |
| `redis.error_reply(msg)` | Build `{err = msg}`; when returned from the script it marshals to `-msg\r\n`. |
| `redis.status_reply(msg)` | Build `{ok = msg}`; marshals to `+msg\r\n` (simple string). |
| `redis.sha1hex(s)` | 40-char lowercase hex SHA-1 of the input bytes. |
| `redis.replicate_commands()` | No-op. Every script already replicates atomically as a unit. |
| `KEYS` | 1-indexed table of `numkeys` byte strings declared in the `EVAL` call. Binary-safe. |
| `ARGV` | 1-indexed table of the remaining arguments. Binary-safe. |
| `cjson.encode(v)` / `cjson.decode(s)` | Pure-Rust JSON codec. Same surface as the Redis `cjson` library. |
| `cmsgpack.pack(v)` / `cmsgpack.unpack(s)` | Pure-Rust MessagePack codec. Same surface as the Redis `cmsgpack` library. |

Lua return values marshal to RESP using the standard Redis rules: `nil` and `false` become nil-bulk, `true` becomes `:1`, integers and lossless-integer floats become integer replies, other floats and strings become bulk strings, `{ok=...}` becomes a simple string, `{err=...}` becomes an error reply, and a plain array becomes a multi-bulk reply (with the first-nil truncation rule).

## Dialect selection

| First line of script | Dialect used |
|---|---|
| (no shebang) | Lua 5.1 (default; what BullMQ, Sidekiq, Redlock, and most published Redis-Lua snippets assume) |
| `#!lua version=5.1` (or `51`) | Lua 5.1, explicit |
| `#!lua version=5.2` (or `52`) | Lua 5.2 — `goto`, `_ENV`, ephemeron tables |
| `#!lua version=5.3` (or `53`) | Lua 5.3 — integer subtype, bitwise operators, `//`, `string.pack` / `string.unpack` |
| `#!lua version=5.4` (or `54`) | Lua 5.4 — to-be-closed variables, integer `for` semantics, new bitwise corners |
| `#!lua version=5.5` (or `55`) | Lua 5.5 — latest published dialect |
| `#!lua version=<other>` | `-ERR unknown lua version: <X>` |

Redis 7.0 Functions metadata (`flags=`, `name=`) on the shebang line is parsed and ignored, so scripts written for the Functions surface load cleanly under `EVAL`.

Deployments that want pure Redis-ecosystem compatibility can pin the accepted dialects in config: `[lua] allow_dialects = ["5.1"]` rejects any script whose shebang asks for a newer VM. The default (empty list) accepts all five.

## Trade-offs and limits

- **No filesystem, network, or OS access.** `io`, `os`, `package`, `debug`, and `coroutine` are not loaded. Scripts cannot open files, make sockets, spawn processes, or read environment variables.
- **No bytecode loading.** `load(bytecode)` and `string.dump` are blocked. Only Lua source can enter the VM, which closes the bytecode-verifier escape route that has historically broken Lua sandboxes.
- **Whitelisted standard library.** `base`, `math`, `string`, `table`, `cjson`, and `cmsgpack` are available. Other standard modules are absent.
- **Per-script time budget.** Each `EVAL` runs under an instruction budget derived from `[lua] time_limit_ms` (default 5000 ms ≈ 200 M instructions — the same ceiling as Redis's default `lua-time-limit`; `0` disables the cap). Exceeding it returns a catchable Lua error and aborts the script.
- **Per-script memory budget.** Each script runs in a fresh interpreter state seeded from a per-dialect VM pool; tables and strings created during the call are reclaimed when it returns. There is no shared mutable Lua state between calls — use kevy keys to persist anything.
- **No nested `EVAL`.** A script calling `redis.call("EVAL", ...)` returns an error, matching Redis behaviour.
- **One shard per script.** All `KEYS` must hash to the same slot. Scripts that touch multiple keys across shards get `-CROSSSLOT` at dispatch.
- **JIT off by design.** The interpreter is used directly; the Cranelift JIT in luna is not linked into the kevy server, keeping the dependency surface minimal and avoiding JIT-time pauses.

## FAQ

**Will my existing Redis Lua script run unmodified?**
If it targets Lua 5.1 (the Redis default) and only uses `redis.call` / `redis.pcall` / `redis.error_reply` / `redis.status_reply` / `KEYS` / `ARGV` / `cjson` / `cmsgpack`, yes. If it relies on the debug library, the OS library, or loading precompiled bytecode, no — those are sandboxed out.

**How do I run a script across keys on different shards?**
You can't — atomicity is the whole point. Split the work into per-shard scripts and coordinate at the client, or design the key layout so the relevant keys share a hash tag (`{user:42}:quota` and `{user:42}:counter` route to the same shard).

**`EVALSHA` returns `-NOSCRIPT`. What do I do?**
Re-send the same body via `EVAL`. The server caches it again and answers the call. Most client libraries handle this fallback automatically. `SCRIPT FLUSH` and process restarts both reset the cache.

**Can a script call `BLPOP` or other blocking commands?**
No. Blocking commands inside `EVAL` would defeat the atomicity contract — the shard would either freeze waiting for itself or have to interleave other work. Blocking commands return an error when dispatched from a script.

**Why Lua 5.1 by default when newer versions exist?**
Every script published in the Redis ecosystem assumes 5.1. Defaulting to 5.1 means those scripts copy-paste in without surprises around integer subtypes, bitwise operators, or `goto`. Opting individual scripts into a newer dialect via the shebang is a one-line change when you actively want the newer features.

==============================================================================
# replication
==============================================================================

# Replication

How kevy streams writes from a primary to one or more replicas, how to fail over by hand or by quorum, and how an embedded process can subscribe to the same stream as a read replica.

## When you need this

Reach for replication when one of these is true:

- **Read fan-out.** A single primary takes every write; one or more replicas absorb the read load and round-robin behind the [`kevy-cluster-rw`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-cluster-rw) client.
- **HA failover.** You want the surviving replicas to elect a new primary automatically when the current one goes away. Add [`kevy-elect`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-elect) for quorum-based promotion; use the `FAILOVER` verb for a planned zero-loss handover; or promote by hand with `REPLICAOF NO ONE`.
- **Embed-as-replica.** An application uses [`kevy-embedded`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-embedded) as an in-process keyspace but wants the source of truth to live on a `kevy` server. The embed mirrors the primary in-memory and serves reads with zero network round-trip; writes are rejected locally and must be sent to the primary.

If you only run one `kevy` node, you do not need this doc. If you need cross-DC active-active, gossip discovery, online resharding, Raft, AUTH, or TLS, kevy will never give them to you — pick a different system.

## Core idea

A primary `kevy` opens a dedicated replication listener per shard. Every applied mutation is encoded as a RESP envelope (`*2\r\n:<offset>\r\n<argv>`) with a monotonically increasing 64-bit offset and pushed into a per-shard bounded ring backlog. Each connected replica streams from its last-acked offset; if the requested offset has aged out of the backlog, the primary in-line-ships a snapshot of that shard's keyspace, then resumes live streaming with no gap. A replica may retarget at runtime with `REPLICAOF host port`, and demote itself with `REPLICAOF NO ONE`. Chain replication (replica-of-replica) is not supported on the wire and is rejected defensively in the apply path.

Since v3.14 the connection is two-way. The replica writes `REPLCONF ACK <offset>` back on the same replication connection as frames are applied, so the primary holds a per-replica **acked** position (not just "sent") — this is what `INFO replication`'s `slave0` lines and the `WAIT` barrier read. In the other direction the primary appends an out-of-band heartbeat `+PING <generation> <next_offset>` at 1 Hz — it occupies no offset space, and gives the replica self-measured lag (`slave_lag_frames`) and link liveness (`master_link_status`). The `generation` field (v3.16) identifies one unbroken offset history; failover bumps it. The pre-v3.16 one-number `+PING <next_offset>` form still decodes.

Since v3.15 the topology is **symmetric**: a node started with `role = "replica"` binds the full replication listener + source too, so a promoted replica serves downstream replicas immediately — no config edit, no restart.

```
                  +-----------------+
   writes ──────► |    primary      |
                  |  shard 0..N-1   |
                  |  port_base + i  |
                  +--------+--------+
                           │ per-shard RESP stream (offset, argv)
            ┌──────────────┼──────────────┐
            ▼              ▼              ▼
       +---------+    +---------+    +---------+
       | replica |    | replica |    | embed   |
       |   A     |    |   B     |    | (in-proc|
       |  reads  |    |  reads  |    |  reader)|
       +---------+    +---------+    +---------+
```

The same replication stream feeds three kinds of subscribers: a full `kevy` server running as a replica, an embedded `kevy-embedded` `Store` opened in replica mode, and (transitively) the quorum elector that watches everyone's `repl_offset` for failover decisions.

## Worked example

The example below brings up one primary, one replica, retargets the replica at runtime, probes role, and attaches an in-process embedded reader to the same primary.

### 1. Primary `kevy.toml`

```toml
[replication]
role             = "primary"
listen_port_base = 16004        # shard i binds replication on listen_port_base + i
replication_buffer_size = 268435456   # 256 MiB ring backlog per shard
reconnect_window_ms     = 60000       # how long to hold a slot for a reconnecting replica
```

Start it:

```sh
kevy --config /etc/kevy/primary.toml --port 6004
```

Shard 0 of the primary now accepts RESP client traffic on `:6004` and replication connections on `:16004`.

### 2. Replica `kevy.toml`

```toml
[replication]
role     = "replica"
upstream = "primary.internal:16004"   # the primary's listen_port_base
```

Start it on a second host:

```sh
kevy --config /etc/kevy/replica.toml --port 6004
```

Each local shard opens a runner thread, connects to `(upstream_host, upstream_port_base + shard_index)`, handshakes with `REPLICATE FROM <offset> ID <replica_id>`, reads `+ACK <offset>`, then streams frames into the shard's apply path inside a guard that suppresses local re-emission.

### 3. Retarget the replica at runtime

```sh
redis-cli -p 6004 REPLICAOF new-primary.internal 16004
# +OK
```

The replica stops its runner fleet (sockets are shut down so blocked reads unblock), parses the new upstream, and spawns new runners. The local store is **not** wiped — frames from the new primary land on top of the existing data. Call `FLUSHALL` first if you want a clean replay.

### 4. Promote a replica by hand

```sh
redis-cli -p 6004 REPLICAOF NO ONE
# +OK
```

All runner threads stop and the effective role flips to `master`. Local data stays exactly where the last applied frame left it. A node started with `role = "replica"` already binds the full replication listener (topology symmetry, v3.15), so it serves downstream replicas the moment it is promoted — no config edit, no restart. Only a node started `standalone` and retargeted at runtime lacks the downstream listener.

For a coordinated, zero-loss handover (quiesce writes, wait for the target to drain, promote, follow), use the `FAILOVER` verb instead — see *Planned failover* below.

### 5. Probe the role

```sh
redis-cli -p 6004 ROLE
# 1) "master"
# 2) (integer) 12345678
# 3) 1) 1) "10.0.0.21"
#       2) (integer) 6004
#       3) (integer) 12345670

redis-cli -p 6004 INFO replication          # on the primary
# role:master
# connected_slaves:1
# slave0:ip=10.0.0.21,port=6004,state=online,offset=12345670,sent=12345678,lag=8
# master_repl_offset:12345678

redis-cli -p 6004 INFO replication          # on the replica
# role:slave
# master_host:primary.internal
# master_port:16004
# master_link_status:up
# master_last_io_seconds_ago:0
# slave_read_only:1
# slave_repl_offset:12345670
# slave_lag_frames:0
```

Both sides report heartbeat/ACK truth (v3.14): on the primary, a `slave0` line's `state` flips `syncing → online` once every shard stream has a real `REPLCONF ACK`, `offset` is its **acked** position, and `lag` is in frames; on the replica, `master_link_status` is `up` while a heartbeat landed within 3 s, and `slave_lag_frames:0` means caught up. `ROLE` and `INFO replication` aggregate across shards: offsets are summed over the shard streams, and each replica process appears as exactly one `slaveN` entry regardless of shard count. Field-by-field semantics are in the *Observability* section of [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md).

Live runtime state from `REPLICAOF` always wins over the static config in the reply — and with an elect quorum configured, the live election role wins over both.

### 6. Embed-as-replica (one-liner)

An application can join the same replication stream in-process via [`kevy-embedded`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-embedded):

```rust
use kevy_embedded::Store;

let store = Store::open_replica("primary.internal:16004")?;
assert!(store.is_replica());

// Local writes are rejected with READONLY.
assert!(store.set(b"local", b"nope").is_err());

// Reads pay zero network round-trip — the keyspace lives in this process.
if let Some(v) = store.get(b"hello")? {
    println!("{:?}", v);
}
```

The embed connects to the same `listen_port_base` shard, applies frames as they arrive, and serves reads directly from its local arena. A runnable copy lives at [`crates/kevy-embedded/examples/replica.rs`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-embedded/examples/replica.rs).

## Knobs

Server-side TOML keys under `[replication]`:

| key | default | meaning |
|---|---|---|
| `role` | `"standalone"` | `"standalone"` = subsystem dormant; `"primary"` opens the replication listener; `"replica"` spawns runners that pull from `upstream`. |
| `listen_port_base` | `0` (= client port + 10000) | Shard `i` binds replication on `listen_port_base + i`. Since v3.15 **replicas bind this listener too** (promotion symmetry). |
| `upstream` | unset | Replica-only. `host:port` of the primary's replication port base. Each local shard targets `(host, port + shard_index)`. |
| `replication_buffer_size` | `268435456` (256 MiB) | Per-shard ring backlog in bytes. Reconnects within this window stay on the live path; older offsets trigger snapshot ship. |
| `reconnect_window_ms` | `60000` | How long the primary keeps a slot reserved for a disconnected replica's offset before reclaiming it. |
| `replica_read_only` | `true` | Reject client writes on a replica with `-READONLY`; the replication apply path and admin verbs bypass the gate. |
| `replica_max_staleness_ms` | `0` (off) | Bounded staleness: a replica whose last primary heartbeat is older than the bound refuses reads with `-STALE`. Ladder rung 3 in [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md). |
| `min_replicas_to_write` | `0` (off) | The primary refuses writes with `-NOREPLICAS` when fewer than N replicas are healthy (live connection that has ACKed). Ladder rung 4. |
| `min_replicas_max_lag_ms` | `10000` | Freshness window for `min_replicas_to_write`: a replica counts as healthy only if its latest ACK is younger than this bound, so a stalled replica ages out of the count even while its connection stays up. |
| `single_source` | `false` | The upstream is ONE stream on one port (an embedded writer) instead of the per-shard fleet — see *Embedded-as-primary* below. |

Because both roles bind the replication range, co-hosting several instances on one machine requires client ports at least `nshards` apart — otherwise their default replication ranges (`client port + 10000 … + 10000 + nshards − 1`) collide.

When [`kevy-elect`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-elect) is configured, the `[cluster]` block adds quorum knobs:

| key | default | meaning |
|---|---|---|
| `node_id` | unset | Stable id of this node (≤ 32 B ASCII). Used as the tie-breaker in elections. |
| `elect_port_base` | `0` (= client port + 200) | Control-plane TCP port for heartbeats and ballots — one listener per node. |
| `peers` | empty | `id@host:elect_port:client_port,…` for every node in the cluster including self. Empty means the elector is dormant. |

Use the extended three-field peer syntax: election traffic rides the elect port, while retargeting and `-MISDIRECTED` replies use the client port. The legacy `id@host:port` form assumes both are equal, which is almost never what you want.

Election timing is FIXED CONSTANTS, not config keys: heartbeats every
200 ms, a peer is DOWN after 5 s of silence, a candidate waits 3 s
for quorum ACCEPTs. (Earlier revisions of this page listed them as
`[cluster]` keys — the config parser rejects those.)

Quorum is `N/2 + 1`. N=2 needs both nodes alive (either down locks the survivor read-only); the linter warns and any deployment that needs failover should use N ≥ 3.

One consequence to plan for: in an elect quorum, `[replication] role = "primary"` is only an initial *preference*. Write authority comes from winning an election — every quorum member boots read-only and holds writes until it wins (including a cold start, which pays one election round before the first write). This clamp is what prevents a restarted empty primary from erasing the cluster; the full story is the *Election-only write authority* section of [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md).

## Failover

Two paths move the primary role, both built on the stream mechanics above; the operational detail (steps, timings, error contract) lives in [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md).

**Planned: `FAILOVER host port [TIMEOUT ms] | ABORT`** (v3.15). Run on the primary with the target replica's *client* address; it answers `+OK` and hands over on a background thread: quiesce writes (`-QUIESCED`), poll the target's `INFO replication` until drained (`slave_lag_frames:0`), promote it (`REPLICAOF NO ONE`), then follow it as a replica. The handover retargets to `client port + 10000`, so the target must run with the default `listen_port_base`. Timeout (default 10 000 ms) rolls the quiesce back.

**Crash: quorum election** (v3.15). With the `[cluster]` block on every node, peers detect a dead primary and elect the replica with the highest applied replication offset (lowest `node_id` breaks ties); the winner opens writes and bumps its feed generation, losers retarget automatically. A rejoining ex-primary whose stream is *ahead* of the new primary (a forked suffix of never-replicated writes) gets a **replacing** snapshot resync — `FLUSHALL` before load — instead of a corrupt-close: the fork is discarded and the node converges on the majority's history.

## Trade-offs and limits

Replication is **asynchronous by default**. The primary commits and replies before it knows any replica has applied the frame; replicas trail by the time it takes a frame to ride the wire and drain the per-shard channel into the apply path. When a given write or read needs more, buy it per call: `WAIT n timeout` blocks until ≥ n replicas have acknowledged, `REPL.TOKEN` + `REPL.WAIT` gives read-your-writes on a chosen replica, and two config keys add bounded staleness (`-STALE`) and a min-replicas write gate (`-NOREPLICAS`). The whole ladder, rung by rung, is [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md).

| concern | answer |
|---|---|
| Write durability | Acknowledged by the primary as soon as it lands in the local store and the backlog ring. Replicas catch up afterwards; `WAIT n timeout` blocks until ≥ n have acknowledged (a replica ack is not an fsync — see availability.md). |
| Read consistency | Replicas may lag. Send `request_read(…, consistent = true)` through `kevy-cluster-rw` to force a read at the primary, or use `REPL.TOKEN` + `REPL.WAIT` for read-your-writes on the replica itself. |
| Replica falls behind | If the reconnect needs an offset that has aged out of the ring, the primary in-line-ships a snapshot of that shard and resumes live frames at the snapshot's end offset — no gap, no operator action. While the ship is replacing the replica's keyspace, client reads on the replica answer `-LOADING` (`PING` / `INFO` / `HELLO` stay answerable, so health checks keep passing). |
| Sizing the backlog | `replication_buffer_size ≈ peak_writes_per_sec × avg_argv_bytes × reconnect_window_seconds`. Oversize is harmless; undersize falls back to snapshot ship. |
| What fails over | Writes to the new primary, automatically when `kevy-elect` is configured, by hand otherwise. Existing `kevy-cluster-rw` clients re-route writes once they learn the new primary; in-flight writes during the gap fail loudly. |
| What does not fail over | Cross-DC traffic, gossip-discovered peers, online resharding, AUTH/TLS — kevy does not ship any of these. Single-DC only. |
| Chain replication | Not on the wire. A replica's apply path will not re-emit downstream; a misconfiguration is rejected defensively. |
| Minority writes during partition | Bounded, then lost. A quorum primary that cannot see a strict majority fences its own writes (`-NOREPLICAS primary lost quorum; writes fenced`) within one lease window, so the silent-absorption window is ~5 s, and every write inside it fails loudly. A partitioned minority cannot promote; when the partition heals it demotes, its un-replicated forked suffix is discarded, and it resyncs to the majority's history via snapshot. |

The wire format (live frame envelope, snapshot ship, handshake) is documented in [`crates/kevy-replicate/docs/wire.md`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-replicate/docs/wire.md) and [`crates/kevy-replicate/docs/snapshot.md`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-replicate/docs/snapshot.md). The elector's protocol is in [`crates/kevy-elect/docs/protocol.md`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-elect/docs/protocol.md).

## FAQ

**How do I promote a replica?**
Planned and zero-loss: run `FAILOVER host port` on the current primary (see *Failover* above). By hand: connect to the replica and run `REPLICAOF NO ONE` — the effective role flips to `master` immediately, the local store is preserved, writes are accepted, and (since v3.15) the already-bound replication listener starts serving downstream replicas at once. Automatically: configure `[cluster]` with `node_id`, `elect_port_base`, and a `peers` list on every node; the alive replica with the highest applied offset wins on quorum.

**Can a replica become a primary, and then back to a replica?**
Yes. `REPLICAOF NO ONE` demotes the upstream link without touching data; a subsequent `REPLICAOF host port` re-attaches to a new primary. The local store is kept across both transitions. Call `FLUSHALL` first if you want a clean replay from the new upstream.

**What's the data loss window?**
The interval between "primary acks the client" and "every replica has applied the frame." Replication is asynchronous by default, so a primary that crashes after acking a write but before any replica has the frame loses that write. Sizing the gap is workload-dependent — on a single-DC LAN it is typically sub-millisecond. For writes that must survive a single-node loss, follow them with `WAIT 1 <timeout>`: a `WAIT`-acked write exists on two nodes, and crash elections pick the most-advanced replica, so it survives (see [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md)). A replica ack is still not an fsync; for durability across a power-off, pair replication with [`docs/persistence.md`](https://github.com/goliajp/kevy/blob/develop/docs/persistence.md) (AOF + RDB) on the primary.

**Can I read from a replica?**
Yes — that is the main reason to add one. Use [`kevy-cluster-rw::ReadWriteClient`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-cluster-rw) and it will send writes to the primary and round-robin reads across the replica seeds you pass in. When a read must observe the latest write, use the consistent-read path on the same client to force that read through the primary.

**A replica fell too far behind — how do I recover it?**
Do nothing. The primary detects that the replica's requested offset is no longer in the backlog ring, returns `TooOld`, in-line-ships a snapshot of the shard's keyspace via the same RESP wire connection, then resumes live frames at the snapshot's end offset. The replica swaps in the snapshot, applies the live tail, and is caught up. During the ship window the replica refuses client reads with `-LOADING` (the visible keyspace is about to be replaced wholesale); `PING`, `INFO`, and `HELLO` are exempt, and `INFO replication` reports `loading:1` so monitoring can watch the window close. If you would rather rebuild from empty, stop the replica, delete its data directory, and restart — the runner will connect with `from_offset = 0` and snapshot-ship the whole keyspace.

## See also

- [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md) — the operational half: topologies, the consistency ladder, planned + crash failover, the error contract. This page is the mechanics (wire, frames, snapshot ship); that one is what to run and what clients see.
- [`docs/cluster.md`](https://github.com/goliajp/kevy/blob/develop/docs/cluster.md) — multi-shard exposure and the slot-routing `ClusterClient`; orthogonal to replication and composable with it.
- [`docs/persistence.md`](https://github.com/goliajp/kevy/blob/develop/docs/persistence.md) — RDB and AOF; the snapshot ship path reuses the same on-disk format on the wire.
- [`crates/kevy-cluster-rw`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-cluster-rw) — the read/write-split client.
- [`crates/kevy-elect`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-elect) — quorum failover.
- [`crates/kevy-embedded`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-embedded) — embed-as-replica `Store::open_replica`.

## Embedded-as-primary (v3.2)

An embedded application can be the PRIMARY, with a kevy server as its
replica — read scaling and a full query surface (the replica declares
its own indexes/views/aggregates over the replicated data) for an
in-process store:

```rust
// the application (primary)
let store = Store::open(
    Config::default().with_shards(4).with_embed_writer("127.0.0.1:7101"),
)?;
```

```toml
# the server replica (replica.toml)
[replication]
role = "replica"
upstream = "127.0.0.1:7101"
single_source = true          # ONE upstream stream, hash-routed locally
```

`single_source = true` tells the server the upstream is a single
stream (an embed writer source) rather than the per-shard port fleet
of server↔server replication: one runner connects, keyed frames route
to local shards by key hash, FLUSHALL/FLUSHDB broadcast, and a
snapshot ship broadcasts the whole payload with each shard loading
only its own hash slice.

A replica handshaking from offset 0 (fresh) or from past the backlog
window receives a full snapshot ship from the embed source (the
v1.21 anti-scope, closed in v3.2): a point-in-time freeze of every
shard plus the as-of offset, then live frames.

Relationship to the CDC feed (docs/cdc.md): they coexist by design.
The replication source serves REPLICA CONSISTENCY (infra plane,
per-source offsets); the feed serves APPLICATION CDC ((generation,
offset) cursors, prefix filters, at-least-once). Unifying them would
tie app-facing CDC semantics to the replica protocol.

Gate: `bench/repligate.sh` — true two-process: snapshot ship to a
fresh replica, quiesced digest stability, restart re-sync, and
replica-local `IDX.CREATE`/`IDX.QUERY` over replicated data.

==============================================================================
# availability
==============================================================================

# Availability

How a kevy deployment stays writable and readable through node failures: the topologies, the consistency ladder from "fastest, asynchronous" up to "quorum-fenced", planned and crash failover, and the exact error contract clients see at every step.

This doc builds on [`docs/replication.md`](https://github.com/goliajp/kevy/blob/develop/docs/replication.md) (the streaming mechanics) — read that first if you have never brought up a primary/replica pair. If you only run one kevy node, the only section that applies to you is the ladder's first rung.

## Topologies

### Single node

No replication config (`role = "standalone"`, the default). Every write is acknowledged as soon as it lands in the local store; durability is [`docs/persistence.md`](https://github.com/goliajp/kevy/blob/develop/docs/persistence.md) (AOF + RDB). There is no failover — availability equals the lifetime of the process.

### Primary + replicas

```toml,fragment
# primary                          # each replica
[replication]                      [replication]
role = "primary"                   role = "replica"
                                   upstream = "primary.internal:16004"
```

The primary streams every applied mutation per shard; replicas apply and serve reads (client writes get `-READONLY`). Two wiring shapes:

- **Fleet** (default): the upstream is a full kevy server — each local shard connects to `(host, port_base + shard_index)`, one stream per shard.
- **`single_source = true`**: the upstream is ONE stream on one port (an embedded writer via `with_embed_writer`) — a single routing runner fans frames into local shards by key hash. See the *Embedded-as-primary* section of [`docs/replication.md`](https://github.com/goliajp/kevy/blob/develop/docs/replication.md).

Failover in this topology is **manual**: `REPLICAOF NO ONE` on the survivor, retarget the rest.

### Three-node elect quorum

```toml
# every node adds the same [cluster] block
[cluster]
node_id         = "n1"                  # unique per node
elect_port_base = 6204
peers           = "n1@10.0.0.1:6204:6004,n2@10.0.0.2:6204:6004,n3@10.0.0.3:6204:6004"
```

Membership is **static** (the operator-declared `peers` table); roles are **dynamic** (elections move the primary around inside that table). Quorum is `N/2 + 1` — N=2 cannot survive any failure (either node down locks the survivor read-only), so a deployment that needs failover uses N ≥ 3.

Use the extended peer syntax `id@host:elect_port:client_port`: election traffic rides the elect port, while retargeting and `-MISDIRECTED` replies use the client port. With the legacy two-field form the client port is assumed equal to the elect port, which is almost never what you want.

**Election-only write authority.** In an elect quorum, `[replication] role = "primary"` is only an initial *preference*. Every quorum member configured as primary starts **read-only** and holds writes until it wins an election — including on a cold start, where the cluster pays one election round (a few seconds) before the first write is accepted. This unconditional clamp is what prevents the classic "restarted empty primary erases the cluster" accident: a node that crashed and lost its disk can never come back writable on config alone.

## The consistency ladder

Replication is asynchronous by default. Each rung below buys a stronger guarantee for one verb or one config key — pay for exactly what a given read or write needs.

| rung | mechanism | guarantee | cost |
|---|---|---|---|
| 0 | (default) | primary acks after local apply; replicas trail | none |
| 1 | `REPL.TOKEN` + `REPL.WAIT` | read-your-writes on a chosen replica | one blocked call on the replica |
| 2 | `WAIT n timeout` | write is on the primary **and** acked by ≥ n replicas | one blocked call on the primary |
| 3 | `replica_max_staleness_ms` | a replica never serves reads older than the bound (`-STALE`) | reads fail over to the primary during lag spikes |
| 4 | `min_replicas_to_write` | primary refuses writes without n fresh replicas (`-NOREPLICAS`) | write availability coupled to replica health |
| 5 | quorum lease (automatic with elect) | a partitioned primary fences its own writes (`-NOREPLICAS`) | writes pause for the lease window during partitions |

### Read-your-writes: `REPL.TOKEN` / `REPL.WAIT`

```
REPL.TOKEN
REPL.WAIT gen offset [gen offset ...] [TIMEOUT milliseconds]
```

Write to the primary, then `REPL.TOKEN` there: it returns one `(generation, offset)` pair per shard — the live feed tail, which by construction covers your write. Hand the whole token to `REPL.WAIT` on the replica you are about to read: it blocks until every shard has **applied** at least that far, answers `+OK`, and your next read on that connection observes your write. Default `TIMEOUT` is 1000 ms; `0` and anything larger are capped at 60 s.

The `generation` half is the anti-footgun: it identifies one unbroken offset history (the same generation the CDC feed uses — see [`docs/cdc.md`](https://github.com/goliajp/kevy/blob/develop/docs/cdc.md)). A failover, `FLUSHALL`, or crash restart bumps it, so a token minted against the old primary's offset space can never falsely satisfy against the new one — `REPL.WAIT` answers `-MISDIRECTED writer is <primary>` immediately on a generation mismatch, and the client falls back to reading the primary. Timeout gives the same reply: either way, "go read the writer" is the one recovery path.

On a primary, `REPL.WAIT` returns `+OK` immediately (you are already talking to the writer), so the call is safe to issue unconditionally through a routing client.

### `WAIT` — replica acknowledgment, not durability

```
WAIT numreplicas timeout
```

Blocks until **every shard's** `master_repl_offset` (frozen when the barrier arms) has been acknowledged by at least `numreplicas` replicas, or the timeout passes; returns the minimum acked-replica count across shards. The all-shard barrier is deliberate — a kevy write may land on any shard, so per-shard counting is the only answer that is never wrong. `timeout 0` is Redis's "wait forever", hard-capped at 60 s. Issued on a replica, `WAIT` answers `-ERR WAIT cannot be used with replica instances`.

**`WAIT` is not durability.** A replica ACK means the frame reached the replica's apply pipeline, not that any fsync happened anywhere. What `WAIT 1` does buy: the write exists on two nodes, so it survives any single-node loss *provided the subsequent election picks the most-advanced candidate* — which it does (see crash failover below). For power-loss durability, pair replication with AOF on the primary.

### Bounded staleness: `-STALE`

```toml
[replication]
replica_max_staleness_ms = 2500     # 0 = off (default)
```

A replica whose last primary heartbeat is older than the bound refuses reads with `-STALE replica is stale; read the primary or raise replica_max_staleness_ms`. Heartbeats ride the replication stream at 1 Hz, so bounds below ~2 s will trip on healthy links; the gate uses 2500 ms. The replica recovers the moment heartbeats resume — no operator action.

### Write gates: `min_replicas_to_write` and the quorum lease

```toml
[replication]
min_replicas_to_write = 1           # 0 = off (default)
```

A heuristic modeled on Redis: the primary refuses writes with `-NOREPLICAS Not enough good replicas to write.` when fewer than N replicas are healthy. Healthy means a live replication connection that has ACKed **and** whose latest ACK is younger than `min_replicas_max_lag_ms` (default 10 000 ms) — a stalled replica that stops ACKing ages out of the count even while its TCP connection stays up. This closes the "primary writing into the void" window but is **not** a split-brain guarantee — both sides of a partition can each see their own replicas.

The real fence is the **quorum lease**, automatic in an elect quorum: a primary whose election heartbeats cannot reach a strict majority of peers within the lease window (= `down_after`, 5 s) fences its own writes with `-NOREPLICAS primary lost quorum; writes fenced`, and unfences when the partition heals. Combined with `WAIT` or tokens this squeezes "the minority side silently absorbed writes" down to at most one lease window, and every write inside that window fails *loudly* rather than silently diverging.

## Failover

### Planned: the `FAILOVER` verb

```
FAILOVER host port [TIMEOUT ms]      # host:port = the target replica's CLIENT address
FAILOVER ABORT
```

Run on the primary; answers `+OK` at once and runs the handover on a background thread (asynchronous, like Redis's `FAILOVER`):

1. **Quiesce** — every new client write answers `-QUIESCED migrating to <host:port>`; the [`kevy-cluster-rw`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-cluster-rw) client already retries these with backoff, so writers stall rather than fail.
2. **Drain** — the old primary polls the target's `INFO replication` until `master_link_status:up` and `slave_lag_frames:0`. With writes quiesced, converged gauges are exact — this is the zero-loss step.
3. **Promote + follow** — `REPLICAOF NO ONE` is sent to the target (its feed generation bumps, fencing stale tokens), then the old primary retargets itself at the target's replication port and becomes the read-only replica.
4. Un-quiesce. Stray writes still aimed at the old node now get `-READONLY` and reroute.

`FAILOVER ABORT` clears the quiesce at any point before promotion; the background thread notices and stands down. If the target never drains within `TIMEOUT` (default 10 000 ms), the quiesce rolls back and the node resumes primary duty — the failed attempt costs one write-availability blip and nothing else.

One addressing constraint: the handover retargets to `client port + 10000`, so the target must be running with the default `listen_port_base` (see port conventions below).

### Crash: quorum election

With the `[cluster]` block configured on every node, a dead primary is detected and replaced without an operator:

1. Peers miss its election heartbeats for `down_after` (5 s) and flag it DOWN.
2. An eligible replica starts a candidacy: it must hold the **highest replication offset** (sum of applied stream positions across shards) among alive peers, with lowest `node_id` as the tie-breaker. Offset-best ordering is what turns `WAIT`-acked writes into survivors — the replica that has your acked write outranks the ones that don't.
3. The candidate needs quorum `ACCEPT`s within `election_timeout` (3 s); the epoch and vote are persisted to `<data_dir>/elect.meta` *before* they leave the node, so a crash-restart can never double-vote.
4. The winner broadcasts `ANNOUNCE`, stops its runner fleet (writes open), and bumps its feed generation. Losers retarget their replication upstream at the winner automatically.

**MTTR ≈ `down_after` + one election round** — about 5–8 s with the shipped timings; the gate bounds it at 30 s end-to-end including write reopening. The election timings (`hb_interval` 200 ms, `down_after` 5 s, `election_timeout` 3 s) are fixed constants in this release, not config keys.

**The old primary comes back.** The restart-role clamp starts it read-only (election-only write authority, above). The election tells it who the current primary is; it retargets and handshakes. Any writes it absorbed after the partition but before dying form a *forked suffix* — its stream position is ahead of the new primary's, and the new primary answers the only safe way: **discard the fork**, ship a full snapshot, resume live frames. The rejoined node converges on the majority's history; the forked writes are gone (they were never `WAIT`-acked by definition — the fork is exactly the un-replicated tail).

Failed nodes are **not** auto-replaced and membership never changes at runtime — replacing hardware means updating `peers` on every node and restarting them. Dynamic membership, multi-primary, and cross-DC are out of charter.

## Error contract for writers and readers

The full catalog lives in [`docs/error-replies.md`](https://github.com/goliajp/kevy/blob/develop/docs/error-replies.md); this table is the availability slice — what a client sees at each point of the topology's lifecycle, and what it should do. `kevy-cluster-rw::ReadWriteClient` implements all of these behaviors already (writes to the primary, reads round-robined across replicas, redirect-following on `MISDIRECTED`/`QUIESCED`, a consistent-read path that forces the primary).

| reply | you are talking to | when | client action |
|---|---|---|---|
| `-READONLY You can't write against a read only replica.` | a replica (incl. a demoted or clamped ex-primary) | any client write while `replica_read_only = true` (default) | send writes to the primary; a routing client re-resolves it |
| `-QUIESCED migrating to <host:port>` | a primary mid-`FAILOVER` | the quiesce window (handover step 1–3) | retry with backoff; follow `<host:port>` once the handover lands |
| `-MISDIRECTED writer is <host:port>` | a replica (`REPL.WAIT`), or a non-owner node (scoped writes) | read-your-writes not servable (timeout / generation mismatch), or a scope-routed write | read (or write) at `<host:port>` — the current writer |
| `-NOREPLICAS Not enough good replicas to write.` | a primary with `min_replicas_to_write` | fewer than N healthy replicas | back off and retry; page whoever runs the replicas |
| `-NOREPLICAS primary lost quorum; writes fenced` | a quorum primary on a partition's minority side | quorum lease lost | back off and retry — either the partition heals or the majority elects a new primary your routing client will find |
| `-STALE replica is stale; read the primary or raise replica_max_staleness_ms` | a replica with a staleness bound | primary heartbeat older than the bound | read the primary until the replica catches up |
| `-LOADING kevy is loading the dataset in memory` | a replica mid-full-resync | a snapshot ship is replacing the replica's keyspace wholesale | wait and retry — the window is bounded by the ship; `PING` / `INFO` / `HELLO` still answer, so health checks keep passing |

Two rules of thumb: every one of these is **retryable by design** (nothing was applied), and every one names the topology truth a routing client needs to self-heal — none requires a human in the loop.

## Operations

### Port conventions

| plane | port | notes |
|---|---|---|
| client RESP | `server.port` (e.g. 6004) | the address clients and `peers` client-ports refer to |
| replication | `listen_port_base + shard_i`; default base = client port + 10000 | `nshards` consecutive ports; since v3.15 **replicas bind this listener too** (promotion symmetry) |
| election | `elect_port_base`; default = client port + 200 | one control-plane listener per node |

Both automatic retarget (election) and `FAILOVER` assume the `client port + 10000` replication convention — leave `listen_port_base` at its default in any failover-enabled deployment. Running several instances on one host: keep client ports at least `nshards` apart, or the instances' replication port ranges collide.

### Config keys

`[replication]` (see [`crates/kevy-config/src/replication.rs`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-config/src/replication.rs)):

| key | default | meaning |
|---|---|---|
| `role` | `"standalone"` | `"primary"` streams to replicas; `"replica"` pulls from `upstream`; standalone = subsystem dormant |
| `upstream` | unset | replica-only: `host:port` of the primary's replication port base |
| `listen_port_base` | `0` (= client port + 10000) | shard `i` binds replication at base + `i` |
| `replication_buffer_size` | `256mb` | per-shard ring backlog; reconnects inside it skip the snapshot |
| `reconnect_window_ms` | `60000` | how long a disconnected replica's slot is held |
| `replica_read_only` | `true` | reject client writes on a replica (`-READONLY`); `CONFIG SET` is the escape hatch |
| `replica_max_staleness_ms` | `0` (off) | ladder rung 3: `-STALE` reads past the bound |
| `min_replicas_to_write` | `0` (off) | ladder rung 4: `-NOREPLICAS` under N healthy replicas |
| `min_replicas_max_lag_ms` | `10000` | rung 4's freshness window: a replica counts as healthy only if its latest ACK is younger than this bound — a stalled replica no longer satisfies `min_replicas_to_write` |
| `single_source` | `false` | one-stream upstream (embedded writer) instead of the per-shard fleet |

`[cluster]` election keys (see [`crates/kevy-config/src/cluster.rs`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-config/src/cluster.rs)): `node_id` (≤ 32 B ASCII, unique), `elect_port_base`, and `peers` (`id@host:elect_port[:client_port],...`). The elector stays dormant unless both `node_id` and `peers` are set.

### Observability

`INFO replication` on a **replica**:

| field | truth source |
|---|---|
| `role:slave` + `master_host` / `master_port` | the live upstream (a runtime `REPLICAOF` wins over config) |
| `master_link_status` | `up` if a stream heartbeat landed within 3 s, else `down` |
| `master_last_io_seconds_ago` | age of the last heartbeat |
| `slave_read_only` | the `-READONLY` gate |
| `slave_repl_offset` | applied stream position |
| `slave_lag_frames` | primary's announced tail minus applied — **0 means caught up** |

`INFO replication` on a **primary**:

| field | truth source |
|---|---|
| `role:master`, `master_repl_offset` | stream tails **summed across all shards** (the same convention the election's offset-best ordering uses) |
| `connected_slaves` | distinct replica processes with live connections (a replica's per-shard streams fold into one entry) |
| `slaveN:ip=…,port=…,state=…,offset=…,sent=…,lag=…` | per replica process, identified by its peer address: `state` is `online` once **every** shard stream has ACKed (`syncing` while any hasn't), `offset` is its acked position summed across shards, `lag` in frames |

The cross-process comparables are the replica's own `slave_lag_frames` gauge and the data itself — offset arithmetic between two different processes' INFO outputs is only meaningful within one generation.

`ROLE` gives the same truths in Redis's array shape (`master` + offset + per-replica `[ip, port, acked-offset]`, or `slave` + upstream); with an elect quorum configured, the live election role wins over both `REPLICAOF` state and config. Watching lag in practice: poll `slave_lag_frames` on replicas (alert on non-zero sustained past your staleness budget), and `WAIT 1 <small-timeout>` on the primary as a cheap end-to-end "is at least one replica keeping up" probe.

### The gate

Everything this doc promises is executable: [`bench/availgate.sh`](https://github.com/goliajp/kevy/blob/develop/bench/availgate.sh) runs 13 clamps against real processes — phase 1 (READONLY-while-applying, offset/lag truth, link-down/up detection, per-replica ack truth, min-replicas), phase 2 (3-node crash failover with MTTR bound, restart-role clamp + fork-discard rejoin), phase 3 (WAIT truth, 20/20 read-your-writes rounds + future-token MISDIRECT, `-STALE` on a SIGSTOP'd primary, quorum-lease fence and reopen), phase 4 (the `-LOADING` contract across a full-resync ship window, `PING` exempt). If a claim here and the gate ever disagree, the gate wins — file the doc bug.

## See also

- [`docs/replication.md`](https://github.com/goliajp/kevy/blob/develop/docs/replication.md) — stream mechanics, snapshot ship, embed-as-replica, sizing the backlog.
- [`docs/cdc.md`](https://github.com/goliajp/kevy/blob/develop/docs/cdc.md) — the `(generation, offset)` cursor model that `REPL.TOKEN` shares.
- [`docs/error-replies.md`](https://github.com/goliajp/kevy/blob/develop/docs/error-replies.md) — the full error catalog.
- [`docs/persistence.md`](https://github.com/goliajp/kevy/blob/develop/docs/persistence.md) — the durability half of the story (`WAIT` is not it).
- [`crates/kevy-elect/docs/protocol.md`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-elect/docs/protocol.md) — the election wire protocol.
- [`crates/kevy-cluster-rw`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-cluster-rw) — the client that implements the whole error contract.

==============================================================================
# cluster
==============================================================================

# Cluster

kevy's cluster surface has two independent layers — **single-node multi-shard exposure** (one process, every shard speaks Redis Cluster) and **multi-node replication + scoped multi-writer** (primaries, replicas, embeds, quorum failover) — and you can run either, both, or neither.

## The two layers at a glance

**Single-node cluster mode.** One kevy process partitions its keyspace across N shards and exposes each shard as a virtual cluster node on a deterministic per-shard port. `CLUSTER SLOTS / SHARDS / NODES` report the real CRC16 partition; key-aware clients (`redis-cli -c`, `redis-benchmark --cluster`, stock cluster-aware libraries, and the bundled [`ClusterClient`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-client/examples/cluster.rs)) hash each key and connect straight to the owning shard. The win is mechanical — removing the server-side cross-shard hop translates directly into higher throughput and lower tail latency.

**Multi-node cluster.** A kevy server can act as a **primary** streaming a write log to one or more **replicas** (either kevy servers or in-process [`kevy-embedded`](https://github.com/goliajp/kevy/tree/develop/crates/kevy-embedded) stores). A primary can also delegate **scoped writes** by prefix: `[cluster] scopes` declares which node owns writes for `app:billing:*`, which owns `app:auth:*`, etc.; writes that land on the wrong node receive `-MISDIRECTED writer is <host:port>` so the client follows. [`kevy-elect`](https://github.com/goliajp/kevy/tree/develop/crates/kevy-elect) provides the quorum control plane: it flags a dead node DOWN, elects a replacement primary for the replication topology (v3.15), and promotes a scope's declared fallback. Operator-issued `MOVE-SCOPE` migrates a prefix under a quiesce window.

## When you need this

| Situation | Reach for |
|-----------|-----------|
| One process, key-aware client, want the cross-shard hop gone | Single-node cluster mode + `ClusterClient` |
| Compatibility with stock Redis Cluster tooling on a single host | Single-node cluster mode |
| Hot reads served from another machine or in-process | Multi-node: primary + replicas (or embed-as-replica) |
| Multiple writers, partitioned by key prefix, on different hosts | Multi-node: scoped multi-writer |
| Surviving a writer crash without a human in the loop | Multi-node: `kevy-elect` quorum elections (primary) / scope fallback (scoped writers) |
| One process, low load, ordinary clients | Neither — the default proxy port is enough |

The two layers compose: a primary in cluster mode advertises N shards, each replica also runs N shards, and a routing client wires them together.

---

# Layer 1 — Single-node cluster mode

## Core idea

A normal kevy process accepts every command on a single port and internally forwards mis-routed keys to the shard that owns them. That forward is correct, but on a hot path it dominates p99 latency and caps throughput. Cluster mode exposes each shard at its own port; a key-aware client hashes the key with CRC16-XMODEM, looks up the owner shard from `CLUSTER SLOTS`, and connects straight there — no forward, no `-MOVED`.

```
                  ┌─────────────────────────────────────────┐
                  │            kevy process (1 host)        │
                  │                                         │
  main port  ───▶ │  6004  ── proxy: forwards or -MOVED ──▶ │
                  │                                         │
  shard ports ──▶ │  6005  ── shard 0   (slots     0– 4095) │
                  │  6006  ── shard 1   (slots  4096– 8191) │
                  │  6007  ── shard 2   (slots  8192–12287) │
                  │  6008  ── shard 3   (slots 12288–16383) │
                  └─────────────────────────────────────────┘
```

Shard `i` always binds `port_base + 1 + i` (override `port_base` via TOML). The main port keeps the proxy behaviour for clients that don't speak cluster; per-shard ports answer `-MOVED <slot> <host:port>` when a key arrives at the wrong owner.

Whole-keyspace commands (`KEYS`, `SCAN`, `DBSIZE`, `FLUSHALL`) stay whole-keyspace on every port — kevy fans them out internally so a client doesn't have to.

## Enabling it

```toml
# kevy.toml
[server]
port = 6004

[cluster]
enabled   = true
# port_base = 6004   # defaults to `port`; shards live at port_base + 1 + i
```

Equivalent CLI / env:

```sh
kevy --port 6004 --threads 8 --cluster      # shard ports 6005..6012
KEVY_CLUSTER=1 kevy --port 6004 --threads 8
```

Switching a data directory in or out of cluster mode re-homes the keys once at startup; the prior files are backed up as `*.premigration.<ts>`.

## Using `ClusterClient` from Rust

```toml
[dependencies]
kevy-client = "*"
```

```rust
use kevy_client::ClusterClient;

// Seed against any cluster port; topology is discovered via CLUSTER SLOTS
// and one connection is opened per shard.
let mut cc = ClusterClient::connect("127.0.0.1", 6005)?;

cc.set(b"user:42", b"alice")?;
let v = cc.get(b"user:42")?;            // routed to user:42's owner shard
let n = cc.incr(b"counter")?;

// Multi-key DEL/EXISTS — routed per key and summed.
let removed = cc.del(&[b"a", b"b", b"c"])?;
# Ok::<(), kevy_client::KevyError>(())
```

A runnable seed example lives at [`crates/kevy-client/examples/cluster.rs`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-client/examples/cluster.rs); a benchmark at [`crates/kevy-client/examples/cluster_bench.rs`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-client/examples/cluster_bench.rs).

### How routing removes the cross-shard hop

1. **Discover.** `connect` sends `CLUSTER SLOTS` to the seed, reads each shard's `[start, end, host, port]`, and builds a 16384-entry `slot → shard-index` table. The table comes from the server's advertised ranges, so the client never reimplements the partitioning arithmetic.
2. **Route.** Every single-key command computes `key_hash_slot(key)` (CRC16-XMODEM over the `{hashtag}` if present, else the whole key) and sends straight to that slot's owner connection.
3. **Fan-out where needed.** `dbsize`, `flushall`, and other whole-cluster commands are handled server-side; the client issues one call.

On a 16-core Linux box with GET at concurrency 64, removing the cross-shard hop lifts measured throughput from 333 k ops/s to 533 k ops/s (1.6×) and drops p99 from 3858 µs to 260 µs (~15× lower tail). Reproduce with `cargo run -p kevy-client --release --example cluster_bench`.

> The hop's cost only shows up under load on a clean machine. On a small co-located cloud VM the difference is buried in scheduling noise.

### Cross-slot multi-key commands

Unlike Redis Cluster, kevy does **not** return `-CROSSSLOT` when a multi-key command (`MGET`, `MSET`, `SUNION`, transactions, blocking fan-outs) spans shards on a single-node cluster: the server fulfils the request across shards. kevy is a superset of Redis Cluster on a single machine — every Redis Cluster client works, plus the surface you would have hit `-CROSSSLOT` on still works. A shared `{hashtag}` is still the right tool when you need data co-located for atomicity, but it is no longer required for correctness.

### `CLUSTER` commands supported on a cluster port

| Command | Behaviour |
|---------|-----------|
| `CLUSTER SLOTS` | Real partition: one `[start, end, host, port]` row per shard. |
| `CLUSTER SHARDS` | Newer shape of the same data, primary nodes only. |
| `CLUSTER NODES` | Flat text manifest, one row per shard, IDs derived from shard index. |
| `CLUSTER MYID` | Deterministic ID for the shard answering the call. |
| `CLUSTER KEYSLOT <key>` | CRC16-XMODEM over the `{hashtag}` or whole key. |
| `CLUSTER COUNTKEYSINSLOT <slot>` | Live count by walking the owning shard's index. |
| `CLUSTER COUNT-FAILURE-REPORTS <id>` | Always 0 — there is no failure detector on this layer. |
| `CLUSTER INFO` | Reports `cluster_enabled:1`, `cluster_state:ok`, slot coverage. |
| `CLUSTER RESET`, `CLUSTER FORGET`, `CLUSTER MEET`, `CLUSTER FAILOVER`, `MIGRATE`, `ASK` | Not implemented — see *Out of scope*. |

### Falling back to raw routed helpers

```rust
// Route an arbitrary single-key command to its owner shard.
let reply = cc.request_keyed(b"mykey", &[b"STRLEN".to_vec(), b"mykey".to_vec()])?;
// Keyless commands go to any shard.
let reply = cc.request_unkeyed(&[b"PING".to_vec()])?;
# Ok::<(), kevy_client::KevyError>(())
```

`ClusterClient` wraps the common verbs across strings, hashes, lists, sets, sorted sets, pub/sub, and the multi-key `DEL` / `EXISTS`. Pub/sub is process-global: a `Subscriber` on any port sees every published message regardless of which shard accepted the `PUBLISH`.

---

# Layer 2 — Multi-node cluster

## Primary and replicas

A kevy server can be a primary streaming its write log, or a replica that mirrors one (the default role is `standalone` — replication dormant). The primary binds a dedicated replication listener per shard; replicas connect, hand over their last-applied offset, and apply the streamed frames onto local shards. Chain replication (replica-of-replica) is not supported.

```toml
# primary.toml
[server]
port = 6004

[replication]
role             = "primary"
listen_port_base = 16004    # optional; defaults to port + 10000
```

```toml
# replica.toml
[server]
port = 6004

[replication]
role     = "replica"
upstream = "primary.local:16004"
```

Full server-side semantics — backlog sizing, snapshot ingest, heartbeats and ACKs — live in [`docs/replication.md`](https://github.com/goliajp/kevy/blob/develop/docs/replication.md); failover (planned `FAILOVER` and crash elections) and the consistency ladder are [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md). The relevant fact for this document is that the same wire protocol carries cluster-mode replication: a primary running with `[cluster] enabled = true` streams N shards' worth of writes, and a replica running with the same shard count applies them shard-for-shard.

## Embed as read-replica

A [`kevy-embedded`](https://github.com/goliajp/kevy/tree/develop/crates/kevy-embedded) store can subscribe to a primary directly and serve in-process reads with zero network hop. Writes are refused locally with `READONLY`.

```rust
use kevy_embedded::Store;

// In-memory replica, AOF off, default reconnect (100 ms → 5 s).
let replica = Store::open_replica("primary.local:16004")?;

let v = replica.get(b"hello")?;
assert!(replica.set(b"k", b"v").is_err());      // KevyError::ReadOnly
# Ok::<(), kevy_embedded::KevyError>(())
```

For tuning:

```rust
use std::time::Duration;
use kevy_embedded::{Config, Store};

let cfg = Config::default()
    .with_replica_upstream("primary.local:16004")
    .with_replica_id("backup-svc-region-a")
    .with_replica_reconnect(Duration::from_millis(50), Duration::from_secs(10));
let replica = Store::open(cfg)?;
# Ok::<(), kevy_embedded::KevyError>(())
```

The handshake sends `REPLICATE FROM <last-applied-offset> ID <replica_id>`; the primary acks the offset and streams frames. The runner thread is joined when the last `Store` clone drops, so the primary observes a clean FIN and frees the slot. `PUBLISH` is allowed locally on the embed (pub/sub is process-local), but the keyspace itself remains read-only.

## Scoped multi-writer

Scoped multi-writer splits writes by key prefix across nodes. Every node knows the full ownership table from static config; writes that land on a non-owner answer `-MISDIRECTED writer is <host:port>` so the client retries against the right node.

```toml
# Same config block on every member.
[cluster]
node_id = "embed-billing-1"
peers   = "embed-billing-1@10.0.0.1:6004,server-eu-1@10.0.0.2:6004,reader-1@10.0.0.3:6004"

# prefix=writer[|fallback], comma-separated.
# The first `=` splits prefix from owner spec, so `app:billing:` (with `:`) is fine.
scopes  = "app:billing:=embed-billing-1|server-eu-1, app:auth:=embed-auth-1"

elect_port_base = 16100    # kevy-elect listens here
```

`peers` is a flat string of `<node_id>@<host>:<port>` entries — no nested structure, easy to template. `scopes` is parsed `prefix=writer[|fallback]`, comma-separated. A node with no scope ownership simply forwards writes; a node that does own a scope accepts writes for it and rejects others.

Reads are independent of scope ownership — any node holding the data (typically a read-replica) can serve them. The scope mechanism is for write attribution only.

### Embed as scoped writer

```rust
use kevy_embedded::{Config, Store};

let writer = Store::open(
    Config::default().with_embed_writer("0.0.0.0:6105")
)?;

// Local writes feed the embed's replication source backlog;
// readers connect to 0.0.0.0:6105 via kevy_replicate::ReplicaClient.
writer.set(b"app:billing:invoice:42", b"...")?;
# Ok::<(), kevy_embedded::KevyError>(())
```

The embed exposes a replication listener on the address passed to `with_embed_writer`. Other nodes pull the log from there exactly as they would from a server primary.

## `kevy-elect` quorum failover

`kevy-elect` is the in-process quorum control plane every cluster member runs when `[cluster] node_id` and `peers` are both set. Each node binds one TCP control listener at `elect_port_base` (default: client port + 200) and heartbeats every peer; a peer silent past `down_after` (5 s) is flagged DOWN. Membership is **static** (the operator-declared `peers` table); roles are **dynamic** — elections move the primary around inside that table. The election timings (`hb_interval` 200 ms, `down_after` 5 s, `election_timeout` 3 s) are fixed constants in this release, not config keys.

It drives two failover surfaces:

**Replication primary election (v3.15).** When the current primary is DOWN, an eligible replica — the one holding the highest applied replication offset among alive peers, lowest `node_id` breaking ties — starts a candidacy and needs quorum (`N/2 + 1`) ACCEPTs within `election_timeout`. Epoch and vote are persisted to `<data_dir>/elect.meta` *before* any answer leaves the node, so a crash-restart can never double-vote. The winner opens writes; losers retarget their replication upstream automatically. Three clamps back this up: a **cold start** with no known primary elects after one `down_after` grace window; a **restarted** quorum member holds writes until an election settles (config `role = "primary"` is only a preference); and a primary that cannot see a strict majority **fences its own writes** within one lease window (`-NOREPLICAS primary lost quorum; writes fenced`). The operational walkthrough is [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md).

**Scope fallback.** A scope's declared fallback consults the DOWN set on every accepted write: if its writer is DOWN, the fallback treats itself as the active owner and accepts the write; the next write on every other node now MISDIRECTs to the fallback. When the original writer's HBs resume, it leaves the DOWN set and the fallback steps down implicitly on the next decision.

| Knob | Meaning | Default |
|------|---------|---------|
| `node_id` | This node's stable identifier (≤ 32 B ASCII; scope owners and elections reference it) | required |
| `peers` | `<node_id>@<host>:<elect_port>:<client_port>` list of every cluster member | required |
| `elect_port_base` | TCP port the election control plane binds (one listener per node) | `0` = client port + 200 |

### Manual rejoin recovery

If the original writer was DOWN long enough that the fallback accepted writes, those writes only live on the fallback. Before re-enabling the original writer for the scope: stop the writer, copy the fallback's data directory into the writer's, then restart. This stays inside the no-consensus contract — no shadow-writes, no double-acceptance.

---

# `MOVE-SCOPE`

`MOVE-SCOPE` migrates a prefix from one writer to another under a bounded quiesce window. It is operator-issued and runs on the current writer.

```
MOVE-SCOPE <prefix> from <from-node-id> to <to-node-id>
```

Step by step:

1. The current writer flips local state for `<prefix>` to MIGRATING. Subsequent writes to keys under the prefix return `-QUIESCED migrating to <to-host:port>`. Clients back off briefly and retry.
2. The writer serialises the prefix's keyspace slice and ships it via `MOVE-SCOPE-INGEST <prefix> <bulk>` to the target's data port. Every value type moves with full fidelity — including streams, which carry their entries, `last_id` bookkeeping, consumer groups, consumers, and live pending (PEL) rows across the move (only tombstone PEL rows for already-deleted entries are dropped; no RESP verb can recreate those).
3. On `+OK` from the target, the writer commits the migration locally. Future writes for the prefix on the source now return `-MISDIRECTED writer is <to-host:port>`.
4. Other cluster members continue routing per their static `scopes` config until the operator pushes new config and restarts.

The two wire replies you will see during a move:

| Reply | Meaning |
|-------|---------|
| `-MISDIRECTED writer is <host:port>` | Write landed on a non-owner. Retry against the named host. |
| `-QUIESCED migrating to <host:port>` | Transient during a MOVE-SCOPE window. Back off and retry. |

A cluster-aware client caches the per-key target on `-MISDIRECTED` and retries transparently; on `-QUIESCED` it should sleep briefly (single-digit hundreds of milliseconds) before retrying.

Aborting mid-ship reverts to the source writer; no partial-apply state is left on the target.

---

# Configuration reference

## Single-node cluster mode

| TOML | CLI | Env | Default | Meaning |
|------|-----|-----|---------|---------|
| `[cluster] enabled` | `--cluster` | `KEVY_CLUSTER=1` | `false` | Expose each shard at a per-shard port. |
| `[cluster] port_base` | — | — | value of `port` | Shard `i` binds `port_base + 1 + i`. TOML-only. |

## Replication

TOML-only — there are no replication CLI flags or env vars:

| TOML | Default | Meaning |
|------|---------|---------|
| `[replication] role` | `"standalone"` | `"primary"` streams to replicas; `"replica"` pulls from `upstream`; `"standalone"` = subsystem dormant. |
| `[replication] listen_port_base` | `0` (= `port` + 10000) | Shard `i` binds replication at base + `i`; replicas bind it too (v3.15 promotion symmetry). |
| `[replication] upstream` | unset | Replica-only: `host:port` of the primary's replication port base. |

The full key list (backlog sizing, `replica_read_only`, `replica_max_staleness_ms`, `min_replicas_to_write`, `single_source`) is in [`docs/replication.md`](https://github.com/goliajp/kevy/blob/develop/docs/replication.md).

## Scoped multi-writer + elect

| TOML | Meaning |
|------|---------|
| `[cluster] node_id` | This node's stable identifier (≤ 32 B ASCII). |
| `[cluster] peers` | `<node_id>@<host>:<elect_port>:<client_port>` list of every cluster member (legacy two-field form: both ports equal). |
| `[cluster] scopes` | `prefix=writer[\|fallback]` entries, comma-separated. |
| `[cluster] elect_port_base` | TCP port the election control plane binds; `0` (default) = `port` + 200. |

Election timings (heartbeat 200 ms, DOWN after 5 s, election timeout 3 s) are fixed constants, not config keys.

---

# Trade-offs and limits

- **Single-node cluster mode is a single process.** It buys client-side key routing, not host-level fault tolerance. Add replicas for that.
- **The proxy port stays available.** It will keep working for non-cluster clients and remains correct, just with the cross-shard hop.
- **Membership is static; roles are dynamic.** `peers` and `scopes` are read from config at startup — a membership change is "push new config, restart", and there is no gossip, by design. Within that static table, elections move the primary role around at runtime (v3.15); failed nodes are never auto-replaced.
- **`MOVE-SCOPE` quiesces writes for the prefix.** The window is bounded by slice-ship time, which is single-digit seconds for GB-class scopes over LAN. For prefixes much larger than that, schedule during a maintenance window.
- **Embed as scoped writer is sized for service-shape workloads** (a billing service, an auth service), not multi-TB datasets.
- **Manual rejoin recovery after fallback acceptance.** Copy the fallback's data dir into the writer's before re-enabling; no automatic consensus catch-up.

---

# Out of scope by design

- Mutating `CLUSTER` subcommands (`RESET`, `SETSLOT`, `FORGET`, `MEET`, …) are accepted as no-op `+OK`: kevy has no dynamic membership to mutate (membership is "push new config, restart"), and defensively-probing clients should proceed rather than error. The read-only subcommands always report the true static topology.
- AUTH and TLS — handled by the deployment edge (sidecar, mesh, LB), not by kevy.
- Multi-DC active-active and CRDTs.
- Raft, Paxos, or any consensus log under the keyspace.
- Gossip-based discovery — `peers` is static.
- Online resharding, `MIGRATE`, `ASK` redirection.
- Multi-master with overlapping ownership — every prefix has exactly one writer at a time.

These will not be added. The simplicity is the feature.

---

# FAQ

**Do I need cluster mode to use replication?**
No. Single-node cluster mode and the replication / multi-node layer are independent. A non-cluster primary can have non-cluster replicas; a cluster primary can have cluster replicas. They compose but neither requires the other.

**Can I run a standard cluster-aware client (Lettuce, ioredis, redis-py-cluster) against a kevy in cluster mode?**
Yes. `CLUSTER SLOTS / SHARDS / NODES` advertise a real partition and `-MOVED` fires on a wrong-shard hit, which is the entire surface those libraries depend on. Stick to the per-shard ports (not the main proxy port) so the client's routing is what reaches the shards.

**What happens to a multi-key command across shards in single-node cluster mode?**
It succeeds. kevy executes cross-slot `MGET`, `MSET`, `SUNION`, transactions, and blocking fan-outs server-side rather than returning `-CROSSSLOT`. `{hashtag}` co-location is still useful for atomicity-sensitive cases but is no longer a correctness requirement.

**How do I survive a writer crash without an operator?**
For the replication primary: configure the `[cluster]` block (`node_id`, `elect_port_base`, `peers`) on every node — a dead primary is detected after `down_after` (5 s) and the most-advanced replica is elected in its place; a rejoining ex-primary demotes and resyncs automatically (see [`docs/availability.md`](https://github.com/goliajp/kevy/blob/develop/docs/availability.md)). For a scoped writer: declare a fallback (`prefix=writer|fallback`) — when the writer misses heartbeats past `down_after`, the fallback starts accepting that prefix's writes, clients receive `-MISDIRECTED writer is <fallback>` and follow, and when the original writer comes back you run the manual rejoin recovery.

**Why is gossip / Raft permanently out of scope?**
The cost of a consensus log under every write would erase the throughput and tail-latency advantages that make kevy worth choosing. The static-config + quorum-heartbeat design gives you the failover branch without paying for state-machine replication on the hot path. If your workload genuinely needs a consensus-backed key-value store, kevy is the wrong tool.

==============================================================================
# accept-shards
==============================================================================

# `--accept-shards N` — fold sparse connections onto a subset of shards

`--accept-shards N` tells kevy to bind its listeners and arm `accept` only on shards `0..N`, leaving the rest as compute-only workers that still serve cross-shard reads and writes.

## When you need this

Each kevy shard runs its own reactor with a busy-poll body. That body amortizes its per-iteration overhead (waker drain, inbox check, accept arm) only when each iteration sees enough productive events. If `concurrent_conns / threads` drops below roughly one, every shard spends most of its iterations idle, and aggregate throughput falls below what a 1- or 2-thread server would achieve on the same machine.

Reach for `--accept-shards N` when:

- The client count is small and known (typical app servers, replication followers, internal services).
- You still want `--threads` to match the core count for keyspace parallelism on cross-shard hops.
- Benchmarks show that adding shards makes throughput worse, not better.

Leave it unset when the conn count is high (≥ 1 conn per shard on average), unpredictable, or driven by a thundering-herd client pool — the default of "every shard accepts" is the right answer there.

## Core idea

A static accept-set is declared at boot. Shards inside the set bind the listener fd and arm an `accept` SQE; shards outside the set do neither, so the kernel's `SO_REUSEPORT` group never routes a SYN to them. Off-accept-set shards still own their keyspace slice and still drain the cross-shard inbox, so writes that hash to their slice are dispatched to them, executed, and the reply travels back through the owning conn's shard. The stateless-shard model is intact — every shard runs the same code path; some just happen to own zero connections.

```
                      clients (SO_REUSEPORT group)
                                 |
                  +--------------+--------------+
                  |              |              |
              shard 0        shard 1        shard 2          <-- accept-set (--accept-shards 3)
              listen + accept + own conns + own keyspace slice
                  |              |              |
                  +------ cross-shard dispatch -------+
                  |       |       |       |       |       |
              shard 3  shard 4  shard 5  shard 6  shard 7  shard 8  shard 9   <-- compute-only
              no listener, no accept; execute dispatched cmds, own keyspace slice
```

## Worked example

Ten threads, three accept shards, listening on the standard Redis port:

```sh
kevy --threads 10 --accept-shards 3 --port 6379
```

Equivalent environment-variable form:

```sh
KEVY_THREADS=10 KEVY_ACCEPT_SHARDS=3 kevy --port 6379
```

Equivalent TOML (`kevy.toml`):

```toml
[server]
threads = 10
accept_shards = 3
port = 6379
```

Precedence is CLI > env > TOML > default. `accept_shards` must satisfy `1 <= accept_shards <= threads`; anything outside that range fails fast at startup with exit code 2. The default is unset, which means every shard accepts and the binary behaves byte-identically to a build without the flag.

## Sizing heuristic

Rule of thumb: `accept_shards ≈ ceil(conns / 20)`. The empirical sweet spot is the plateau where each accept shard owns roughly 15–25 connections — dense enough for the busy-poll body to amortize, sparse enough to keep cross-shard dispatch from saturating the inbox channel.

| concurrent conns | threads | recommended `--accept-shards` | conns / accept shard |
|-----------------:|--------:|------------------------------:|---------------------:|
| 10               | 10      | 1                             | 10                   |
| 20               | 10      | 1                             | 20                   |
| 50               | 10      | 2 or 3                        | 25 or 17             |
| 100              | 10      | 5                             | 20                   |
| 200              | 10      | 10 (default, unset)           | 20                   |
| 50               | 16      | 2 or 3                        | 25 or 17             |
| 100              | 16      | 5 or 6                        | 20 or 17             |
| 500              | 16      | 16 (default, unset)           | 31                   |

For the canonical `--threads 10 -c 50 -d 65536 SET` workload, `--accept-shards 3` lifts throughput +10.6% over the default by collapsing 50 conns from ~5/shard onto ~17/shard. The same plateau holds at `--accept-shards 2` (25 conns/shard).

## Trade-offs

| dimension                       | accept-set shard                          | compute-only shard                                  |
|---------------------------------|-------------------------------------------|-----------------------------------------------------|
| busy-poll amortization          | high (own conn fan-in drives per-iter work) | depends on cross-shard inbox rate                  |
| per-conn read / write cost      | local, no hop                             | n/a (no owned conns)                                |
| cross-shard dispatch cost       | one channel send per hop                  | one channel recv + execute + reply send             |
| keyspace ownership              | own slice                                 | own slice                                           |
| CPU floor at idle               | accept-armed, blocks in `io_uring_enter`  | spins to `URING_SPIN_LIMIT` then blocks             |
| effect on tail latency          | accept SQE adds work to hot loop          | cleaner hot loop; cross-shard hop adds one channel  |

Concretely, the smaller `N` you pick, the more each conn benefits from a hot accept-set shard, but the higher the fraction of writes that take a cross-shard hop (`(threads - N) / threads` of all keys). The plateau at conns/shard ≈ 15–25 is where the busy-poll win pays for the extra hops; well below it the dispatch cost dominates, well above it you're back to the unset default.

## FAQ

**Should I always set `--accept-shards`?**
No. If `concurrent_conns / threads >= 1` on average, the default (every shard accepts) is already optimal — the busy-poll body amortizes without help. `--accept-shards` is for the sparse-conn regime where adding shards hurts throughput.

**How do I pick `N` for my workload?**
Start from the rule of thumb `ceil(conns / 20)`. Sweep `N` in a perfgate across `{ceil(conns/25), ceil(conns/20), ceil(conns/15)}` and pick the one that maximises throughput at your target tail-latency budget. Anywhere on the 15–25 conns/shard plateau is a safe production setting.

**Does it break replication, AOF, or persistence?**
No. Off-accept-set shards run the same reactor loop, the same TTL reaper, the same AOF writer, and the same replication ticks as accept-set shards. The only thing they skip is binding the listener and arming `accept`. Replication followers and snapshot/AOF restore behave identically regardless of `N`.

**How do off-accept-set shards still serve writes?**
They own their slice of the keyspace. When a client connection on an accept-set shard issues a write whose key hashes to a compute-only shard, the accept-set shard pushes an `Inbound::RequestBatch` onto the owning shard's inbox; the owning shard executes the command against its own keyspace slice and sends the reply back through the originating shard's reply channel. From the client's perspective the hop is invisible — it sees one reply on one connection, in order.

**What if I get the number wrong?**
The cost of a too-small `N` is a saturated cross-shard inbox and worse tail latency; the cost of a too-large `N` is the original sparse-conn inversion. Both are recoverable by restart with a new value — there's no on-disk state tied to the choice.

==============================================================================
# uds
==============================================================================

# Unix-domain socket (UDS) transport

kevy exposes an optional Unix-domain stream listener that speaks identical RESP semantics to the TCP port, letting same-host clients skip the loopback stack entirely.

## When you need this

UDS is the right transport when the client and server share a host:

- **Same-host clients** — application and kevy on one box, or in containers sharing a tmpfs / mounted socket directory.
- **Latency-sensitive workloads** — low connection counts, small payloads, or high-fanout pipelining where the TCP loopback round-trip floor is the binding constraint.
- **Container sidecars** — sidecar + main container sharing a `/run` or `/tmp` volume; the socket file is the IPC handle, no port allocation needed.

Cross-host clients still need TCP — UDS is filesystem-scoped and never leaves the kernel.

## Core idea

Set `KEVY_UNIX_SOCKET` to a filesystem path and kevy dual-binds: the TCP listener stays up exactly as before, and a UDS listener accepts on the same shard runtime with the same RESP2/3 parser. Any RESP client that takes a `unix://` URL or `-s <path>` flag switches over with one line of config. UDS eliminates loopback `rep_movs`, `nft_do_chain`, and the TCP syscall path, so the per-op floor drops materially on every workload.

## Worked example

Start kevy with both transports enabled:

```sh
KEVY_UNIX_SOCKET=/tmp/kevy.sock kevy --port 6379
```

Connect via UDS with `redis-cli`:

```sh
redis-cli -s /tmp/kevy.sock SET foo bar
# OK
redis-cli -s /tmp/kevy.sock GET foo
# "bar"
```

TCP on `:6379` is still live in parallel — same data, same shards:

```sh
redis-cli -p 6379 GET foo
# "bar"
```

The in-tree Rust clients (`kevy-client` / `kevy-client-async`) speak
`tcp://` / `kevy://` / `redis://` plus the in-process `mem://` and
`file:///` schemes — they do not take a `unix://` URL. From Rust, a
same-host client either connects over TCP loopback or, when it lives
in the same *process*, skips sockets entirely with the embedded
backend (`file:///` / `mem://`), which is faster than UDS could be.
UDS is for out-of-process, same-host clients in other languages or
ecosystem drivers.

## Permissions and security

The trust boundary for UDS is the **filesystem** — there is no RESP-level AUTH or TLS on the Unix socket. Whoever can `open(2)` the socket file can issue any command, including `FLUSHALL`.

- **Socket file ownership.** kevy creates the socket as the user the server runs as. Use `chown` / `chgrp` after start, or run kevy under the identity you want to own the socket.
- **Permission bits.** The socket is created with permissive bits by default so a co-located client process can connect. Tighten by placing the socket inside a directory with restrictive permissions — e.g. `/run/kevy/` owned by a `kevy` group with `0750`, so only group members can `connect(2)`. Directory permissions gate access to the socket inode itself.
- **tmpfs vs disk.** `/tmp` and `/run` on most Linux distros are tmpfs and ideal for sockets (no disk I/O on connect). A persistent path on a real filesystem works too — the inode is just a rendezvous point, no data ever touches the disk.
- **Trust domain.** Treat any account with read+write on the socket path as fully authenticated. If you need per-client identity, that has to live above kevy (a sidecar proxy, a kernel LSM, namespace isolation).

## Server config knobs

| Env var | CLI flag | Default | Effect |
|---|---|---|---|
| `KEVY_UNIX_SOCKET` | (env-only for now) | unset | Filesystem path to bind. Unset = TCP-only. |
| `KEVY_BIND` | `--bind` | `127.0.0.1` | TCP bind address; UDS bind is independent. |
| `--port` | `--port` | `6379` | TCP port; UDS still binds when set. |

Notes:

- **Path must not pre-exist.** kevy refuses to start if `KEVY_UNIX_SOCKET` already points at a file — it will not clobber a path it didn't create. Clean it up on restart (`rm -f /tmp/kevy.sock`) or use a per-run path (`/run/kevy/$(date +%s).sock`). This is intentional: silently unlinking would let a misconfigured kevy steal another service's socket.
- **Dual-bind is always on when the env var is set.** There is no UDS-only mode — the TCP listener stays up too. If you want to forbid TCP, bind it to a loopback-only address you control and firewall it off.
- **Shard 0 owns the accept loop.** Accepted connections are dispatched onto the existing per-shard runtime, so `--threads` still controls parallelism for the workload behind the socket.
- **io_uring path.** On Linux with `KEVY_IO_URING=1`, the UDS accept runs as a multishot accept SQE through the same io_uring instance as TCP — no extra reactor cost. `TCP_NODELAY` is not set on UDS (it isn't an IP socket).

## Trade-offs

UDS vs TCP loopback on the same kevy binary:

| Aspect | UDS | TCP loopback |
|---|---|---|
| Per-op floor | lower (no IP/checksum/port/NAGLE) | higher |
| Reach | same host only | any host |
| Identity | filesystem permissions | port + bind address + AUTH |
| Lifecycle | socket file on disk; must be cleaned on restart | port lifecycle is kernel-managed |
| Observability | `lsof` / `ss -xl` | `ss -tln`, `netstat`, `tcpdump` |
| Client config | `unix:///path` or `-s /path` | `host:port` |

The throughput gain is workload-shape dependent — small-payload low-connection cells gain the most (the loopback per-op tax dominated them); CPU-saturated cells gain less (the transport wasn't the floor). See [bench/REPORT.md](https://github.com/goliajp/kevy/blob/develop/bench/REPORT.md) for measured numbers.

## FAQ

### Can I bind UDS and TCP at the same time?

Yes — that's the only mode. Setting `KEVY_UNIX_SOCKET` adds a UDS listener; the TCP listener stays up exactly as it was. Use whichever per-client makes sense.

### Server refuses to start — "socket exists"?

Intentional. kevy will not `unlink` a path it didn't create, because that lets a misconfigured run silently steal another service's socket. Either remove the stale file (`rm -f /tmp/kevy.sock`) before restart, or use a per-run path like `/run/kevy/$(uuidgen).sock`. If kevy crashed and left the file behind, removing it manually is safe.

### How fast is UDS vs TCP loopback?

Materially faster on every workload, because UDS skips the entire IP path: no checksum, no netfilter chain (`nft_do_chain`), no `rep_movs` through loopback, no per-packet ACK round-trip. The exact ratio depends on what fraction of the per-op budget was loopback overhead — single-connection small-payload workloads see the biggest jump; CPU-bound pipelined cells see less. Measure on your workload with `redis-benchmark -s /tmp/kevy.sock` vs `-h 127.0.0.1`.

### Can my client library use UDS?

Most ecosystem drivers do. `redis-cli` and `redis-benchmark` take `-s <path>`. ioredis, node-redis, redis-py, redis-rb, go-redis, lettuce, and jedis all accept `unix:///path` URLs or an explicit socket-path option — check your driver's connection-options docs for the exact key name. The in-tree [kevy-client](https://github.com/goliajp/kevy/tree/develop/crates/kevy-client) / [kevy-client-async](https://github.com/goliajp/kevy/tree/develop/crates/kevy-client-async) do **not** speak UDS: for a Rust client in the same process the embedded `file:///` / `mem://` backends beat any socket, and across processes they use TCP.

### Should I drop TCP entirely if all my clients are on the same host?

You can, but you don't have to. Leaving TCP bound to `127.0.0.1` costs nothing if no one connects, and it leaves a fallback if a client's UDS path gets misconfigured. The usual deployment is "UDS for the hot client, TCP for `redis-cli` debugging."

==============================================================================
# async
==============================================================================

# Async client

`kevy-client-async` is the async mirror of the blocking [`kevy-client`](https://github.com/goliajp/kevy/tree/develop/crates/kevy-client) — same surface, same URL facade, with `.await` on every call.

## When you need this

Reach for the async client when your app already runs on a `tokio`, `smol`, or `async-std` runtime and you want `await`-flow end-to-end: no blocking threadpool hops, no `spawn_blocking` wrapping, no thread-per-connection. If your code path is request-response on a regular thread, the blocking client is simpler and lower-latency — there is no async tax to pay for being synchronous.

## Core idea

Pick exactly one runtime via a Cargo feature (`tokio`, `smol`, or `async-std`); the crate compiles down to that runtime's `TcpStream` adapter and nothing else. The public surface mirrors the blocking client 1:1 — `AsyncConnection::connect(url).await?`, `conn.set(k, v).await?`, `conn.get(k).await?` — so porting from blocking is `Connection` → `AsyncConnection` plus an `.await` per call. A pipeline builder collapses N commands into one TCP round-trip when latency matters.

## Worked examples

### Tokio

```toml
[dependencies]
kevy-client-async = { version = "1", features = ["tokio"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread", "net"] }
```

```rust
use kevy_client_async::AsyncConnection;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let mut conn = AsyncConnection::connect("tcp://127.0.0.1:6004").await?;
    conn.set(b"k", b"v").await?;
    let v = conn.get(b"k").await?;
    assert_eq!(v.as_deref(), Some(&b"v"[..]));
    Ok(())
}
```

### Smol

Same code; swap the runtime feature.

```toml
[dependencies]
kevy-client-async = { version = "1", features = ["smol"] }
smol = "2"
```

```rust
use kevy_client_async::AsyncConnection;

fn main() -> std::io::Result<()> {
    smol::block_on(async {
        let mut conn = AsyncConnection::connect("tcp://127.0.0.1:6004").await?;
        conn.set(b"k", b"v").await?;
        let v = conn.get(b"k").await?;
        assert_eq!(v.as_deref(), Some(&b"v"[..]));
        Ok(())
    })
}
```

### Pipeline builder

One round-trip for the whole batch. Replies come back in queue order; per-command failures land as `Reply::Error(_)` inside the `Vec` rather than tearing down the batch.

```rust
use kevy_client_async::AsyncConnection;

let mut conn = AsyncConnection::connect("tcp://127.0.0.1:6004").await?;
let replies = conn
    .pipeline()
    .set(b"a", b"1")
    .get(b"a")
    .incr(b"hits")
    .run(&mut conn)
    .await?;
// replies.len() == 3; one Reply per queued command, in order.
```

## Runtime features

Exactly one of these must be enabled. Zero features, or two-plus features at once, is a compile-time error — there is no implicit default.

| feature      | transport adapter                  | runtime crate pulled |
|--------------|------------------------------------|----------------------|
| `tokio`      | `tokio::net::TcpStream`            | `tokio`              |
| `smol`       | `smol::net::TcpStream`             | `smol`               |
| `async-std`  | `async_std::net::TcpStream`        | `async-std`          |

Each runtime crate is pulled with `default-features = false` plus the minimum surface the adapter needs. These are the only crates.io dependencies in the kevy workspace — a deliberate carved exemption to the pure-Rust, zero-dependency rule, because the Rust async ecosystem has no std-only viable substrate.

## URL backends

`AsyncConnection::connect` takes the same URL facade as the blocking client. The TCP-shaped schemes go over the runtime's async socket; the in-process schemes are rejected (the blocking client is strictly faster for them — no point routing through an executor).

| scheme       | target                          | supported by async client |
|--------------|---------------------------------|---------------------------|
| `tcp://`     | kevy or Redis-compat server     | yes                       |
| `kevy://`    | kevy server (alias of `tcp://`) | yes                       |
| `redis://`   | Redis or Redis-compat server    | yes                       |
| `mem://`     | in-process embedded store       | no — use blocking client  |
| `file:///`   | on-disk embedded store          | no — use blocking client  |

Opening a `mem://` or `file:///` URL with `AsyncConnection::connect` returns `ErrorKind::Unsupported`.

## Trade-offs

The blocking client is the default and stays the default for a reason:

- **Sync code paths**: if you do not already have a runtime, do not stand one up for the client. `kevy-client` is pure-Rust, zero-dep, and avoids the executor's scheduling overhead on every command.
- **Embedded backends**: `mem://` and `file:///` are synchronous in-process stores. The blocking client talks to them directly; the async client cannot.
- **Single-shot commands**: one `.await` per command on a stock multi-threaded executor is measurable overhead vs. a direct syscall. The async win shows up under concurrency (many in-flight commands across tasks) or batching (pipeline collapsing round-trips).

Use async when the surrounding app is already async. Use the pipeline builder when you have a batch of independent commands and the round-trip is the bottleneck. Stay on blocking otherwise.

## FAQ

**Why must I pick exactly one runtime?**
The crate compiles a single `TcpStream` adapter. Two adapters in one binary would mean either runtime-agnostic indirection on every I/O (overhead) or a giant cfg matrix nobody can maintain. Zero adapters would leave the public types unimplemented. A compile-time check on feature count keeps the misconfiguration loud and early.

**Can I mix sync and async kevy clients in one process?**
Yes. `kevy-client` (blocking) and `kevy-client-async` are independent crates and coexist freely — use blocking for an embedded `file:///` store and async for a network shard from the same binary, for instance. They do not share connections.

**What about pub/sub?**
`AsyncSubscriber` mirrors the blocking `Subscriber`. A subscribed RESP connection cannot send normal commands, so it is a separate type from `AsyncConnection`. Per-message timeouts use your runtime's own primitive (`tokio::time::timeout`, `async_io::Timer`, etc.) rather than a socket-level read timeout.

**Does the pipeline builder force buffering on the send side?**
Yes — that is the point. `pipeline().…run(&mut conn).await` serializes the whole batch into one write and reads N replies in order. If you need command-by-command back-pressure, call `set` / `get` directly instead of building a pipeline.

## Examples in the repo

- [`tokio_hello`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-client-async/examples/tokio_hello.rs) — open, ping, set/get, del.
- [`pipeline`](https://github.com/goliajp/kevy/blob/develop/crates/kevy-client-async/examples/pipeline.rs) — mixed batch in one round-trip.

==============================================================================
# wasm
==============================================================================

# kevy on WebAssembly

kevy runs in the browser as a real store, not a compile-time curiosity:
the npm package [`@goliajp/kevy`](https://www.npmjs.com/package/@goliajp/kevy)
ships the engine (KV + TTL + counters + scans + pub/sub) compiled to
`wasm32-unknown-unknown` behind a hand-written ES-module loader, with
durable persistence over OPFS (IndexedDB fallback) and pub/sub that
crosses tabs. The same crates also build for `wasm32-wasip1`, so the
Rust API works under `wasmtime` / `wasmer` and in edge runtimes.

Try it live: the [kevy.golia.jp demo](https://kevy.golia.jp/demo/) is a
browser REPL over exactly this module — commands, OPFS persistence that
survives reloads, and pub/sub across tabs, with no backend.

## Quick start (browser)

```sh
npm install @goliajp/kevy
```

```js
import { open } from "@goliajp/kevy";

const db = await open({ persist: { name: "app" } });

db.set("greeting", "hello");
db.set("session", "abc123", { ttlMs: 60_000 });
db.getText("greeting");            // "hello"
db.incrby("visits");               // 1, 2, 3, ...
db.keys("user:*");

// Pub/sub — including other tabs of the same origin:
const off = db.subscribe("events", (payload, channel) => {
  console.log(channel, new TextDecoder().decode(payload));
});
db.publish("events", "hi from this or any other tab");

await db.flush();                  // durability barrier
```

Writes stream to storage as a kevy append-only log and replay on the
next `open()` with the same `persist.name`. The package is six files
(~165 KB packed): the wasm module, the loader, the OPFS worker,
hand-written TypeScript typings, and the usual README + manifest.
Zero dependencies on both sides of the boundary.

## The loader API

`open(options)` instantiates the module, replays the stored log (when
persistence is on), and starts the tick timer and the cross-tab
bridge. Options:

| Option | Default | Meaning |
|---|---|---|
| `wasm` | `kevy.wasm` next to the loader | Module source: URL, `ArrayBuffer`, `Uint8Array`, `Response`, or a compiled `WebAssembly.Module` |
| `persist` | `false` (in-memory) | `{ name, backend }`: one log per `name`; `backend` = `"auto"` (OPFS, IndexedDB fallback), `"opfs"`, or `"idb"` |
| `broadcast` | `true` | Cross-tab pub/sub bridge over `BroadcastChannel` |
| `name` | `persist.name` or `"kevy"` | Instance name; scopes both the storage file and the broadcast channel |
| `tickMs` | `100` | TTL sweep + event poll cadence; `0` disables the timer — call `tick()` yourself |

The returned `Kevy` handle (full signatures in `kevy.d.ts`):

| Method | Semantics |
|---|---|
| `set(key, value, { ttlMs? })` | SET, optionally with an expiry |
| `get(key)` / `getText(key)` | GET as `Uint8Array` / as UTF-8 text; `undefined` when absent or expired |
| `del(key)` / `exists(key)` | DEL / EXISTS |
| `expire(key, ttlMs)` / `persist(key)` / `pttl(key)` | PEXPIRE / PERSIST / PTTL (`-1` no TTL, `-2` no key) |
| `incrby(key, delta?)` | INCRBY, returns the new value |
| `dbsize()` / `flushall()` | DBSIZE / FLUSHALL |
| `keys(pattern?, limit?)` | KEYS with a Redis glob, optionally capped |
| `tick()` | One manual TTL sweep + event poll; returns the expired-key count |
| `subscribe(channel, cb)` / `psubscribe(pattern, cb)` | SUBSCRIBE / PSUBSCRIBE; both return an unsubscribe function |
| `publish(channel, payload)` | PUBLISH to local subscribers and (bridge on) other same-origin tabs; returns the local receiver count |
| `flush()` | Durability barrier: pending write frames are flushed to storage |
| `compact()` | Rewrite storage as a compacted image of the live keyspace |
| `close()` | Flush, tear down bridge/timer/storage, free the instance |

Keys and values are `string | Uint8Array | ArrayBuffer` everywhere:
strings are UTF-8 encoded at the boundary, byte views pass through —
values are genuinely binary, not strings.

## How the binding works (no wasm-bindgen)

kevy's zero-dependency law extends to the toolchain: there is no
binding generator on either side. The [`kevy-wasm`](https://docs.rs/kevy-wasm)
crate exports a flat, hand-written C ABI — 30 `extern "C"` symbols —
and `pkg/kevy.js` is a hand-written loader that owns the TypedArray
boundary, the UTF-8 codecs, the persistence pump, and the cross-tab
bridge. The conventions:

- **Instances** are `u32` handles from `kevy_open`; every other call
  takes the handle first. `0` is never a valid handle.
- **Bytes in** cross as `(ptr, len)` pairs pointing into linear memory
  obtained from `kevy_alloc` / returned with `kevy_free`.
- **Bytes out** land in a per-instance result buffer read via
  `kevy_out_ptr` / `kevy_out_len`, valid until the next call on the
  same handle — callers copy out immediately.
- **Status codes**: `>= 0` is success, `-1` an operation error (UTF-8
  message in the result buffer), `-2` an invalid handle.
- **Numbers** cross as `f64` (clocks, TTLs, counts — all inside the
  2^53 exact-integer range).
- `kevy_abi_version()` reports the ABI contract version, so a loader
  can refuse a mismatched module.

The export surface groups into core (open/close/alloc/free/clock/
tick/result buffer), KV (`kevy_set`, `kevy_get`, `kevy_del`,
`kevy_exists`, `kevy_expire`, `kevy_persist`, `kevy_pttl`,
`kevy_incrby`, `kevy_dbsize`, `kevy_flushall`, `kevy_keys`, …),
pub/sub (`kevy_subscribe`, `kevy_psubscribe`, `kevy_unsubscribe`,
`kevy_publish`, `kevy_poll_events`), and the AOF pump
(`kevy_aof_frames_out`, `kevy_aof_frame_in`, `kevy_aof_dump`). If the
shipped loader doesn't fit your host, the ABI is the supported
integration point — the crate docs specify every symbol and packed
byte format.

## Persistence: a real log, byte-compatible with native kevy

The browser has no filesystem, so durability is host-mediated: with
persistence on, every write also encodes the same RESP multi-bulk
frame a kevy AOF stores on disk (the `kevy-persist` format —
[docs/persistence.md](https://kevy.golia.jp/docs/persistence/)). The loader pumps pending
frames to storage once per microtask, so a synchronous burst of
writes costs one storage append. `await db.flush()` is the durability
barrier; a resolved `flush()` means the backend has flushed to disk.

**The log a browser tab writes replays in a native kevy unchanged** —
same magic header, same frames. Copy the `.aof` out of OPFS and point
a native embedded store (or the server) at it, and the keyspace comes
back. The reverse holds too: the inbound pump accepts a native-written
log. Corrupt tails follow the native replay contract — the intact
prefix is applied, the tail is dropped, and the next compaction
rewrites storage from live state.

Two backends, picked automatically under `backend: "auto"`:

- **OPFS** (primary): a `FileSystemSyncAccessHandle` owned by a small
  dedicated worker — sync handles are worker-only. Every append
  flushes before acknowledging.
- **IndexedDB** (fallback): the same pump against an object store, for
  contexts without OPFS sync handles (notably older Safari).

Compaction is automatic: once the appended log outgrows
`max(512 KB, 4× the last image)`, the loader rewrites storage as a
compacted image of the live keyspace (the browser-side equivalent of
an AOF rewrite). `compact()` forces one before a snapshot or export.

**localStorage is deliberately not a backend**: a ~5 MB quota, a
synchronous API that blocks the main thread on every write, and
UTF-16 string-only storage disqualify it as a write log.

## Cross-tab pub/sub

`publish()` delivers to subscribers in the same tab through the
engine, and (bridge on) broadcasts the frame over a per-instance
`BroadcastChannel` to every other same-origin tab, where each tab's
local subscribers receive it. Delivery is **at-most-once with no
backlog** — only currently-open tabs receive a message, and nothing
is replayed to a tab that opens later. That is the same contract as
kevy server pub/sub ([docs/pubsub.md](https://kevy.golia.jp/docs/pubsub/)), so code written
against one face behaves on the other.

## Clocks, ticks, and TTLs

`wasm32-unknown-unknown` has no threads and no OS clock, so the
engine runs with the manual TTL reaper and a host-fed clock: the
loader feeds `Date.now()` through the ABI before each entry point and
runs `tick()` on a timer (default 100 ms). Consequences:

- TTL precision tracks the tick cadence: a key with a 500 ms TTL
  expires on the first tick after its deadline. Set `tickMs` tighter
  if it matters, or `tickMs: 0` to own the cadence entirely.
- No background work happens between your calls — no hidden costs,
  but a forgotten `tick()` (with `tickMs: 0`) leaves expired keys
  live and event queues undrained.

## Performance

Full methodology, environment, and raw numbers:
[bench/WASM-BENCH.md](https://github.com/goliajp/kevy/blob/main/bench/WASM-BENCH.md) (headless-Chrome
harness, median of 3 runs, 16-byte values at 1k and 100k keys).
Against the storage a web app actually has:

| Axis (n=100k) | kevy-wasm | vs IndexedDB | vs localStorage |
|---|---:|---:|---:|
| point read (ops/s) | 1.67 M | **77×** | 0.48× |
| point write (ops/s) | 1.79 M | **189×** | 4.9× |
| batch load (ms) | 60.8 | **36× faster** | 4.5× faster |
| scan, ~10% match (ms) | 5.6 | **46× faster** | 5.7× faster |
| durable write (ops/s) | 785 k (OPFS) | **12.6–17.4×** | ~2× |
| restart to usable (ms) | 129 | **2.7× faster** | slower (see below) |

Headlines and the honest caveats:

- **Order of magnitude over IndexedDB on every axis** — 77–86× point
  read, 166–189× point write across dataset sizes.
- **Durable writes 12.6–17.4× raw IndexedDB**: the pump batches write
  frames per microtask, so a write burst costs one storage append.
  It also beats localStorage's fire-and-forget `setItem` ~2× while
  being an actual append log.
- **localStorage point reads are the one column kevy does not win**
  (0.42–0.48×), and the bench documents why no wasm-hosted store can:
  Chrome's localStorage read is a renderer-memory hash lookup (its
  measured 3.5–5 M ops/s is in bare-`Map` class, not storage class),
  while every wasm store pays a UTF-8 encode + boundary crossing +
  copy out of linear memory per call — a ~2–3 M ops/s ceiling that
  kevy sits near (1.7–2.1 M) after the loader's staging
  optimizations (persistent scratch buffer, `encodeInto`, cached
  memory view — a 2.2× gain over the naive loader). What kevy wins is
  everything localStorage cannot do at any speed: binary values,
  TTLs, counters, scans, >5 MB datasets, pub/sub, and non-blocking
  persistence.
- **Cross-tab RTT** beats the storage-event hack at 64 KB payloads
  (p50 0.295 ms vs 0.335 ms) and ties on the ~0.105 ms task-hop floor
  below 1 KB — while the storage-event hack drops frames under a slow
  consumer, is string-only, and writes every ping to disk quota.

## The Rust face: WASI, edge runtimes, direct embedding

The engine itself — `kevy-embedded` and its dependency closure
(`kevy-store`, `kevy-persist`, `kevy-hash`, `kevy-bytes`, `kevy-map`,
`kevy-resp`) — builds for both wasm targets; CI gates the whole list
plus `kevy-wasm` on every push. The network reactor crates
(`kevy-rt`, `kevy-sys`, `kevy-uring`) are deliberately outside the
closure, so the wasm build stays clean.

| Target | Command | Notes |
|---|---|---|
| `wasm32-unknown-unknown` | `cargo build -p kevy-wasm --target wasm32-unknown-unknown --release` | The browser artifact (`kevy_wasm.wasm`); the npm loader instantiates it. For your own host, drive the C ABI directly. |
| `wasm32-unknown-unknown` (Rust API) | `cargo build -p kevy-embedded --target wasm32-unknown-unknown` | No threads, no OS clock: open with `Config::with_ttl_reaper_manual()`, feed `set_clock_ns` / `set_wall_clock_ms`, call `Store::tick()` from the host loop. |
| `wasm32-wasip1` | `cargo build -p kevy-embedded --target wasm32-wasip1` | `Instant` / `SystemTime` work — no clock feeding. `std::fs` works against preopened dirs, so `Config::with_persist("/data")` + `wasmtime --dir=/data` gives real AOF durability. Threads still absent: keep the manual reaper. |

Direct embedding on `wasm32-unknown-unknown` in Rust:

```rust
use kevy_embedded::{Config, Store, set_clock_ns, set_wall_clock_ms};

let store = Store::open(Config::default().with_ttl_reaper_manual())?;

// Host feeds the clock before time-sensitive work…
set_clock_ns(now_ms_from_host().saturating_mul(1_000_000));
set_wall_clock_ms(now_ms_from_host());

store.set(b"hello", b"world")?;
let v = store.get(b"hello")?;   // Some(b"world".to_vec())

// …and drives expiry at its own cadence:
let _stats = store.tick();
```

Errors are `KevyResult` / `KevyError` and argv-style write methods
take borrowed slices, exactly as on native — see the
[`kevy-embedded`](https://docs.rs/kevy-embedded) docs.

Cloudflare Workers and similar edge isolates follow the browser
recipe: one instance per isolate, `Date.now()` as the clock source,
`tick()` lazily or from a scheduled handler. For durability across
isolate restarts, mirror writes to the platform's durable store from
your handler (the AOF pump gives you the frames); inside the isolate
kevy is the hot in-memory tier.

## FAQ

**Does the full command surface work in the browser?** The npm
package exposes the KV + TTL + counter + scan + pub/sub cut — the
surface a browser store needs, kept small on purpose (the wasm module
is 416 KB uncompressed). The Rust API on wasm targets exposes the
full `kevy-embedded` feature set of whichever features you compile
in.

**Is the persisted data portable?** Yes — it is a standard kevy AOF.
Browser → native and native → browser both replay. See
[docs/persistence.md](https://kevy.golia.jp/docs/persistence/) for the format contract.

**What about shared-memory threads (`+atomics`)?** The shipped module
is single-threaded, which matches every browser-style target. The
engine is thread-safe where the host provides threads, but the manual
`tick()` model remains the supported path.

**SharedWorker instead of BroadcastChannel?** A single-owner
SharedWorker topology is cleaner in theory but its availability is
narrower (notably absent on Android Chrome); the BroadcastChannel
bridge won on compatibility with the same measured latency class.

**Why not wasm-bindgen?** kevy ships zero third-party dependencies —
server, embedded, and browser alike. A binding generator would be a
build-time dependency and would own the boundary layout; the
hand-written ABI keeps the contract explicit, versioned, and
auditable.

==============================================================================
# embedded-listener
==============================================================================

# Embedded read-only RESP listener

An embedded (in-process) kevy store can expose itself to external
RESP clients — redis-cli, ops tooling, dashboards — over a read-only
listener. The store stays a library inside your process; the
listener is a window into it, not a second server: writes stay the
exclusive right of the owning process.

```rust
use kevy_embedded::{Config, Store};

fn main() -> kevy_embedded::KevyResult<()> {
    let store = Store::open(
        Config::default()
            .with_shards(4)
            .with_resp_listener("127.0.0.1:6009".parse().unwrap()),
    )?;
    store.hset(b"row:42", &[
        (b"state".as_slice(), b"live".as_slice()),
    ])?;
    // ... the application keeps running; clients can peek:
    Ok(())
}
```

```
$ redis-cli -p 6009 hgetall row:42
1) "state"
2) "live"
$ redis-cli -p 6009 scan 0 match 'row:*' count 100
$ kevy-cli -p 6009 DBSIZE
```

Any RESP client works — the listener speaks the same protocol as
the kevy server, both framed requests and inline commands (the
`redis-cli` PING style).

## Turning it on

- `Config::with_resp_listener(addr)` — one `SocketAddr`. **Off by
  default**; when off there is **no thread and no socket — zero
  tax** (gated: idle-listener write throughput within 10% of off,
  [`bench/topogate.sh`](https://github.com/goliajp/kevy/blob/main/bench/topogate.sh)).
- The code is behind the `listener` cargo feature (on by default;
  not available on wasm32 targets).
- The listener holds only a weak handle: it never keeps the store
  alive, and connections end when the store drops.
- There is no authentication (deliberate: kevy has no AUTH plane).
  Bind loopback or a private interface; anything reachable can read
  everything the whitelist serves.

## Surface

Whitelist only — anything else answers `-ERR READONLY embedded
listener`:

```
PING ECHO GET MGET EXISTS TYPE TTL PTTL DBSIZE KEYS SCAN
HGET HMGET HGETALL HLEN LRANGE LLEN SMEMBERS SCARD SISMEMBER
ZSCORE ZCARD ZRANGE FEED.READ FEED.TAIL FEED.SHARDS INFO
```

That includes every write verb, `MULTI`, blocking pops, pub/sub,
and the extension planes (`IDX.*` / `VIEW.*` — query those
in-process through the typed API). The `FEED.*` trio needs the
`replicate` cargo feature (on by default).

`INFO` answers a small embedded-shaped report — crate version,
shard count, key count, and `listener:readonly` — enough for a
dashboard to identify what it is talking to.

The rejection text is a contract: tooling can probe "is this a real
server or an embedded window?" by attempting a write and matching
`READONLY embedded listener`.

### Verb semantics

The whitelisted verbs behave like their server counterparts:

- `SCAN <cursor> [MATCH pattern] [COUNT n]` pages with a numeric
  cursor (`COUNT` clamps to 1..=10000, default 100) and the usual
  SCAN guarantee: keys stable across the traversal are seen exactly
  once; concurrent inserts/deletes may or may not appear.
- `KEYS <pattern>` walks the whole keyspace in one reply (`*`
  matches everything) — spot checks only, prefer `SCAN` on large
  stores.
- Type mismatches answer `-WRONGTYPE …` exactly as the server does;
  malformed integers answer `-ERR value is not an integer`.

## Consistency

Reads run under the store's own shard locks — every reply is a
committed point-in-time answer, live with the writing process (no
replication, no lag, no snapshot staleness). Multi-key reads
(`MGET`, `SCAN`, `KEYS`, `DBSIZE`) merge per shard without a global
snapshot — the same SCAN-class envelope as the server.

One thread per connection: this is an ops-tooling surface, not a
serving path (the kevy *server* is the serving path). Keep the
connection count to tooling scale; a dashboard polling every few
seconds is the intended shape.

## Feeds and read-your-writes

`FEED.TAIL` returns the current `(generation, offset)`; `FEED.READ
<gen> <offset> <limit> [PREFIX p…]` delivers change frames — the same
at-least-once contract as the embedded `changes_since` API (a stale
generation answers `Resync`; restart from `FEED.TAIL`). The embedded
write path serializes all shards into one stream, so `FEED.SHARDS`
reports 1 and the feed verbs take no shard argument — the same
consumer loop written against the server surface
([cdc.md](https://kevy.golia.jp/docs/cdc/)) works here.

Cross-process read-your-writes over the feed is a cursor pattern, not
a blocking primitive: the writing process notes `changes_tail()`
after its write; the reading process first drains `FEED.READ` past
that cursor, then reads. In-process reads are always read-your-writes
(writes commit synchronously). (Server-to-replica replication *does*
have a blocking primitive — `REPL.TOKEN` / `REPL.WAIT`, see
[availability.md](https://kevy.golia.jp/docs/availability/) — but that is the replication
plane, not this feed listener.)

## Inspection without a socket

The listener's verb table is also a public method:

```rust
let mut out = Vec::new();
store.dispatch_readonly(
    &[b"HGETALL".to_vec(), b"row:42".to_vec()], &mut out);
// `out` holds raw RESP bytes — the exact reply the listener
// would have written to a socket.
```

`Store::dispatch_readonly(argv, out)` answers one request against
the same whitelist (write verbs get the same `-ERR`) — the
programmatic face of the listener, for tooling embedded in the
owning process.

And for a store you do NOT own: `kevy-cli --embed <dir>` opens a
read-only point-in-time view of an embedded store's data directory —
the dump/aof/shards.meta files are **copied** to a scratch dir and
replayed, so the owning process keeps running untouched. REPL and
one-shot both work; write verbs answer the listener's `-ERR
READONLY`. That is the offline complement to this listener's live
window.

## When you want more than a window

Escalation path, in order of machinery:

1. **This listener** — live reads, zero write cost, one process.
2. **The CDC feed** ([cdc.md](https://kevy.golia.jp/docs/cdc/)) — push changes to another
   process instead of having it poll reads.
3. **Embedded-as-primary replication** — `with_embed_writer` exposes
   a replication source, and a kevy server with `[replication]
   single_source = true` follows the embedded store as a replica:
   full read fan-out on server hardware, fed by your process. See
   the *Embedded-as-primary* section of
   [replication.md](https://kevy.golia.jp/docs/replication/).

## Performance

[`bench/topogate.sh`](https://github.com/goliajp/kevy/blob/main/bench/topogate.sh) is the clamp, and it is
a TRUE two-process test — a writer binary under continuous HSET
load, a separate reader process asserting live data:

- Reader `GET` p99 < 1ms (median of 6 connections) while the owner
  writes continuously.
- READONLY enforcement (write verbs rejected with the contract
  text).
- Zero-tax: the owner's write throughput with the listener enabled
  but idle within 10% of listener-off.

The reads-under-shard-locks design means heavy listener traffic
CAN contend with the owner's writes on the same shards — that is
the trade for zero-lag truth. Tooling-scale read rates (dashboards,
spot checks) are unmeasurable in the owner's write throughput; if
you need serving-scale reads, use replication (above), not this
listener.

## See also

- [cdc.md](https://kevy.golia.jp/docs/cdc/) — the change feed this listener also serves.
- [replication.md](https://kevy.golia.jp/docs/replication/) — embedded-as-primary, when a
  window stops being enough.
- [availability.md](https://kevy.golia.jp/docs/availability/) — the consistency ladder on
  the replication plane.
- [uds.md](https://kevy.golia.jp/docs/uds/) — local-socket transport for the kevy server
  (the listener itself is TCP-only).

==============================================================================
# iot
==============================================================================

# kevy on IoT devices

`kevy-embedded` scales down as deliberately as the server scales up:
a feature-tiered build that goes from a ~411 KB in-memory KV core to
the full index/replication surface, musl cross-builds for Linux-class
IoT boards (Pi Zero 2, OpenWrt routers, industrial ARM), and a
`no_std` core that has been booted and exercised on a bare-metal
Cortex-M target, not merely compile-checked. Resource
budgets are enforced by a gate, not promised by a README.

## The feature tiers

`kevy-embedded` exposes one Cargo feature per subsystem. The default
is everything; IoT builds start from `core` and add only what the
device actually does:

| Feature | Adds | Pulls in |
|---|---|---|
| `core` | KV + TTL + counters + pub/sub + atomic/pipeline facades | (the base surface — always on in practice; named so the minimal archetype is spellable) |
| `persist` | Snapshot + AOF durability: `Config::with_persist`, `save_snapshot`, `rewrite_aof`, AOF replay on open | `kevy-persist` |
| `index` | Declared secondary indexes + materialized views | `kevy-index` |
| `text` | Full-text (BM25) index segments | `index` + `kevy-text` |
| `vector` | ANN / HNSW vector index segments | `index` + `kevy-vector` |
| `replicate` | Embed-as-replica, embed-as-writer, and the CDC feed | `persist` + `kevy-replicate` + `kevy-resp` |
| `listener` | The read-only RESP listener ([docs/embedded-listener.md](https://kevy.golia.jp/docs/embedded-listener/)) | — |

Dependencies between tiers are encoded in the features themselves:
`text` and `vector` imply `index`; `replicate` implies `persist`
(replicated frames replay through the AOF verb table). Whatever you
leave out is not just dead code that the linker drops — the crates
behind it never enter the build graph at all.

Six archetypes are compile-gated in CI on every push, so each
combination keeps building as the workspace moves:

```text
core                        # sensor cache: RAM-only KV + TTL
core,persist                # + survives power cycles
core,index                  # + declared indexes / views
core,index,text,vector      # + search (BM25, HNSW)
core,persist,replicate      # + edge node feeding a hub
core,listener               # + redis-cli-able diagnostics port
```

In `Cargo.toml`:

```toml
[dependencies]
kevy-embedded = { version = "4", default-features = false, features = ["core"] }
```

The API face is the same at every tier: `Store::open(Config)`,
`KevyResult` / `KevyError` errors, borrowed-slice argv on the write
methods. Code written against `core` recompiles unchanged when the
device later grows `persist`.

## Resource budgets (gated, not aspirational)

Two budget lines, enforced by
[`bench/iotgate.sh`](https://github.com/goliajp/kevy/blob/main/bench/iotgate.sh) as a ratchet — raising
either number requires a written verdict:

| Budget | Line | Measured |
|---|---|---|
| Binary size (`core` consumer, static musl) | ≤ 600 KB | **454 KB** (x86_64) · **411 KB** (aarch64) · **383 KB** (armv7) |
| Empty-store RSS right after `open` (Linux) | ≤ 2 MB | **336 KB** (aarch64) |

> These are measured on `bench/iot-consumer` — a crate deliberately kept
> **outside** the workspace whose only dependency is `kevy-embedded`. That
> is the shape you ship. An earlier version of this gate sized a workspace
> `--example` instead; building an example pulls dev-dependencies (the
> `kevy` server crate), which inflated the reported size by ~60%.

The `iot` cargo profile is defined in the workspace root — `release`
codegen with size the priority:

```toml
[profile.iot]
inherits = "release"
opt-level = "z"     # size over speed
lto = true          # fat LTO: the linker drops unused subsystems
codegen-units = 1
strip = true
```

Reproduce the size number:

```sh
cargo build --profile iot -p kevy-embedded --example iot_core \
  --no-default-features --features core
ls -l target/iot/examples/iot_core
```

## A sensor-cache in full

The `iot_core` example is the shape most devices need — an in-memory
KV with TTLs and a manually driven expiry sweep (no background
threads unless you ask for them):

```rust
use kevy_embedded::{Config, Store};

fn main() -> kevy_embedded::KevyResult<()> {
    // Manual reaper: no thread is spawned; the device's own loop
    // drives expiry at whatever cadence it already runs.
    let s = Store::open(Config::default().with_ttl_reaper_manual())?;

    s.set(b"sensor:1", b"22.5")?;
    s.set(b"sensor:2", b"3.3")?;
    s.expire(b"sensor:2", core::time::Duration::from_secs(60))?;

    // Call from the main loop / timer ISR bottom half:
    let _expired = s.tick();
    Ok(())
}
```

Leave the reaper on its default (a background thread) on boards where
a thread is cheap; take `with_ttl_reaper_manual()` + `tick()` where
you own the loop. TTL precision tracks the tick cadence.

## Cross-compiling: musl and the CI matrix

Static musl binaries are the deployment currency of Linux-class IoT —
one file, no glibc coupling, `scp` and run.

### Platform coverage — what has actually been run

Every row below was built AND executed, not merely compile-checked. The
`core`-tier consumer was run on a real kernel for that architecture; the
sizes are the static-musl artifact.

| Target | Board class | Size | Status |
|---|---|---|---|
| `x86_64-unknown-linux-musl` | industrial x86, gateways | 454 KB | **run** |
| `aarch64-unknown-linux-musl` | Pi Zero 2 / Pi 4-5 / most ARM64 SBC | 411 KB | **run — natively**, 336 KB empty-store RSS, 2.86M store-ops/s |
| `armv7-unknown-linux-musleabihf` | Pi 2-3, older 32-bit ARM | 383 KB | **run** (emulated) |
| `arm-unknown-linux-musleabihf` | Pi Zero / Pi 1 (ARMv6) | 411 KB | **run** (emulated) |
| `riscv64gc-unknown-linux-musl` | RISC-V SBC | 420 KB | **run** (emulated) — needs a RISC-V cross-gcc as the linker (its target spec wants `libgcc_s`, which `rust-lld` cannot supply) plus `crt-static` |
| `thumbv7em-none-eabihf` | Cortex-M4/M7 MCU | 145 KB firmware | **run on bare metal** — `kevy-store` only, not the full `kevy-embedded` surface (that needs `std`). See below. |

The aarch64 numbers are the trustworthy performance ones: that row ran
natively on ARM64. The armv7/ARMv6 rows prove the code is correct on
32-bit ARM, but their timing and RSS carry emulator overhead and should
not be read as device figures.

All shipped targets are compile-gated in CI (the standalone consumer is
built for each on every push), with the **full** default surface checked
on the Tier A targets:

```sh
rustup target add aarch64-unknown-linux-musl
cargo build --profile iot --target aarch64-unknown-linux-musl -p kevy-embedded

rustup target add armv7-unknown-linux-musleabihf
cargo build --profile iot --target armv7-unknown-linux-musleabihf -p kevy-embedded
```

kevy's zero-dependency law pays off here: there is no C library to
cross-compile and no `-sys` crate zoo — the only OS boundary is
kevy's own `kevy-sys`, and the embedded closure below `core` doesn't
even include that.

Running the test suite under emulation is a one-liner when you want
more than a compile proof:

```sh
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_RUNNER=qemu-aarch64 \
  cargo test -p kevy-embedded --target aarch64-unknown-linux-musl
```

## The `no_std` core

Below Linux entirely, the storage stones build without `std`. Five
crates carry `#![no_std]` cores behind their `std` default feature —
`kevy-store`, `kevy-hash`, `kevy-bytes`, `kevy-map`, `kevy-madvise`.

CI does not merely compile them for a Cortex-M: it **boots them on
one**. `bench/mcu-probe` is a bare-metal firmware — hand-written vector
table, bump allocator, panic handler, semihosting I/O, because kevy
takes no dependencies and so cannot reach for `cortex-m-rt` or
`embedded-alloc` — that stands up a real `Store` under QEMU
(`mps2-an386`, Cortex-M4) and exercises the KV and TTL surface. It runs
on every push; if the store misbehaves on an MCU, the build fails.

```sh
cd bench/mcu-probe && cargo run --release
```

Measured on that MCU, with a 64 KiB heap:

| | |
|---|---|
| Firmware image | 145 KB |
| Heap for an empty `Store` | **0 B** — the store allocates nothing until you write |
| Heap for 64 sensor keys | 17.8 KB |
| TTL | expires correctly when the firmware advances its own clock |

**What runs on an MCU is `kevy-store`, not `kevy-embedded`.** The
embedded façade (`Config`, background reapers, persistence, the
listener) needs `std`; the MCU gets the storage engine underneath it,
driven directly.

What the `no_std` cut means in practice:

- **`alloc` is required** — the store is a heap data structure; you
  provide a `#[global_allocator]`. There is no `alloc`-free tier.
- **`external-clock` replaces the OS clock**: the host feeds time
  through `set_clock_ns` (monotonic) and `set_wall_clock_ms` (wall),
  the same host-fed clock contract the browser build uses
  ([docs/wasm.md](https://kevy.golia.jp/docs/wasm/)).
- **No threads, no files, no sockets** — persistence, replication,
  and the listener are `std`-tier features by nature; the `no_std`
  core is the in-memory engine.

One detail is worth knowing because it is the kind that silently
breaks elsewhere: the host-fed clock is a single 64-bit cell that
must read atomically. On ISAs with 64-bit atomics it is a plain
`AtomicU64`; on 32-bit-only MCUs (ARMv7E-M has no 64-bit atomics) it
degrades to a **single-writer seqlock over two `AtomicU32` halves** —
readers retry on a torn read, and since the host feeds the clock from
one context, the retry loop settles immediately. Feeding the clock
from multiple contexts concurrently is outside the contract.

## Sizing guidance

- The numbers above are the `core` tier — the floor, not the typical.
  What each capability actually costs, measured on aarch64-musl with the
  `iot` profile (a consumer that genuinely *calls* the tier's API — a
  feature flag you never use is eliminated by LTO and costs nothing):

  | You use | Binary | Delta |
  |---|---|---|
  | KV + TTL (`core`) | 392 KB | — |
  | + durability (snapshot + AOF) | 601 KB | **+209 KB** |
  | + RESP listener | 629 KB | +28 KB |
  | + secondary index | 667 KB | +66 KB |
  | + full-text (BM25) | 691 KB | +24 KB |
  | + vector ANN (HNSW) | 696 KB | +29 KB |

  Durability is by far the largest single line — everything else is a
  small increment on top of it. Empty-store RSS moves the same way:
  336 KB at `core`, 656 KB with every feature compiled in, so the tier
  you pick shows up in resident memory even more than in bytes on disk.
- Memory scales with the keyspace: the empty-store RSS budget exists
  precisely so the baseline cost of *having* kevy stays trivial next
  to your data.
- If the device needs a diagnostics port, `listener` gives you a
  read-only RESP endpoint that `redis-cli` can talk to — see
  [docs/embedded-listener.md](https://kevy.golia.jp/docs/embedded-listener/) — for the cost of
  one thread and one socket, with writes structurally refused.
- Durability on flash: `persist` writes the same AOF/snapshot formats
  as the server ([docs/persistence.md](https://kevy.golia.jp/docs/persistence/)), so data
  written on the device reads back anywhere in the fleet. AOF fsync
  on SD-card-class storage wants `EverySec` (the default), not
  `Always`.

## What this is not

There is no attempt to make the *server* small: `kevy` (the binary),
`kevy-rt`, `kevy-uring` and friends assume a real kernel and are out
of scope for the IoT cut. The embedded library is the product here —
your firmware is the server.

==============================================================================
# migration
==============================================================================

# Migration — the playbook and the toolchain

Two halves. The **playbook**: how to move a live RDS workload onto
kevy in phases, each with its own verification clamp and rollback
point. The **toolchain** (`kevy-cli`): the commands that move data
into, out of, and between kevy servers — and prove the move was
faithful. Modeling questions ("what does my `JOIN` become?") live in
[rds-workloads.md](https://kevy.golia.jp/docs/rds-workloads/); runnable patterns in the
[cookbook](https://kevy.golia.jp/docs/cookbook/).

## The phased playbook

Seven phases. The load-bearing property: **at every phase up to write
cutover, the RDS is still the source of truth and rollback is
"repoint the app"** — never "reverse-migrate data". Don't skip
phases; each one's verification clamp is what makes the next one
boring.

### Phase 0 — Inventory

List every table and every query shape the workload actually runs
(your ORM's query log or `pg_stat_statements` is the ground truth,
not the schema). Classify each against the
[rds-workloads matrix](https://kevy.golia.jp/docs/rds-workloads/): most rows map mechanically;
flag the ones that hit a refused construct (N-way joins in a hot
path, `HAVING`, deep `OFFSET` pagination, ad-hoc reporting SQL).

- **Action:** a written access-path table: query → matrix row → kevy
  shape (index / view / agg / verb).
- **Clamp:** every hot-path query has a mapped shape **before any
  data moves**. Refused constructs get an app-side redesign decision
  now, not at cutover. Ad-hoc analytics stays off kevy — plan the
  warehouse export (cookbook recipe 14) instead.
- **Rollback:** nothing has moved.

### Phase 1 — Schema mapping

Turn the inventory into a declaration script: prefixes, field
layouts, types, then every `IDX.CREATE` / `VIEW.CREATE` line. Apply
the type rules from the matrix now — DECIMAL to integer minor units,
DATETIME to epoch i64, NULL to absent-field — because they are
write-format decisions you cannot cheaply revisit after backfill.

- **Action:** the declaration script, checked into the repo next to
  your DDL history.
- **Clamp:** run it against a throwaway kevy with a few hundred
  representative rows; `IDX.VERIFY` must show `coerce_failures = 0`
  and expected `duplicates`; `VIEW.VERIFY` no order-exclusions;
  paged queries return what the SQL returned.
- **Rollback:** nothing has moved.

### Phase 2 — Change capture (dual-write window opens)

Start capturing RDS writes **before** the backfill snapshot, so
nothing falls in the gap. Two routes:

- **App dual-write** — the app writes to the RDS (still the truth)
  and mirrors each write to kevy. Simple, no new infra; but the
  mirror rides your write path (make it fire-and-forget with a
  failure counter — a lost mirror write is repaired by re-backfill,
  never by blocking the RDS commit).
- **CDC pull** — a binlog/logical-replication consumer (Debezium or
  hand-rolled) translates row events into kevy writes. Decoupled from
  the app, ordered per row, replayable from a binlog position; costs
  connector infrastructure. Prefer it when you can't touch every
  writer, or when writers are many.

Either way the kevy writes must be **idempotent rebuild shapes**
(`HSET` full row, `DEL` + re-add for collections) so overlap with
the backfill is harmless.

- **Clamp:** freshness lag metric on the capture path (event
  timestamp → kevy apply), plus a row-count drift check per prefix
  (`PREFIX.STATS` vs `SELECT COUNT(*)`) that trends to a constant.
- **Rollback:** stop the capture. The RDS never noticed.

### Phase 3 — Backfill

Snapshot the RDS at a known capture position, export to a RESP
command file, and bulk load:

```
# generate rebuild frames from your RDS export (one HSET per row):
#   HSET user:42 name ada email ada@example.com …
kevy-cli import -p 6004 --strict rows.resp        # ≥200k cmd/s
```

**Import first, declare indexes after** (the deferred-index rule):
backfill builds each index from existing rows at bulk speed —
orders of magnitude cheaper than paying the write hook per imported
row. Then run the phase-1 declaration script and wait for
`IDX.LIST` to report `state=ready` (details under
[Loading into an indexed keyspace](#loading-into-an-indexed-keyspace)).

- **Clamp:** `PREFIX.STATS` counts match `SELECT COUNT(*)` per table;
  `IDX.VERIFY` coercion/duplicate counts are the expected zeros; a
  sampled digest check — recompute a few hundred rows from the RDS
  and byte-compare against `HGETALL` — passes. If you stage through
  an intermediate kevy, `kevy-cli diff` proves the hop.
- **Rollback:** `kevy-cli delete-prefix` (or `FLUSHALL`) and redo.
  The RDS is still the truth.

### Phase 4 — Read cutover (canary, per endpoint)

Flip reads endpoint by endpoint, not big-bang. For each endpoint,
pick the consistency rung it needs
([availability.md](https://kevy.golia.jp/docs/availability/)): browse/list endpoints ride
rung 0 (async replica reads); "I just wrote this, show it back"
flows use `REPL.TOKEN`/`REPL.WAIT` (rung 1) or read the primary. A
single-node kevy has no ladder to think about — every read is
primary.

- **Action:** shadow-read first (serve from the RDS, also read kevy,
  compare and count mismatches), then shift traffic percentage.
- **Clamp:** mismatch counter at zero over a full traffic cycle
  (24h+); serving latency inside your SLO.
- **Rollback:** repoint reads at the RDS — instant, data untouched.

### Phase 5 — Write cutover + the rollback window

Flip writers to kevy, and **in the same deploy** start the reverse
mirror: a CDC consumer replaying kevy's feed back to the RDS as SQL
(`FEED.READ` → `UPDATE`/`INSERT`, cookbook recipe 13). The RDS is
now a warm standby that trails kevy by seconds; your rollback plan
is "repoint the app back", not "reverse-migrate".

Before the flip, seed sequence keys **above** the RDS high-water
mark (`INCRBY seq:order <rds_max_id>` on a fresh key) — the classic
auto-increment collision is phase 5's sharpest edge.

- **Clamp:** `kevy-cli diff`-style sampling between kevy and the
  mirrored RDS (digest a prefix, compare row samples); the business
  metrics you already alert on.
- **Rollback:** within the mirror window, repoint the app at the RDS
  (accepting the mirror lag, which you are measuring). The mirror
  consumer must handle `-FEEDRESYNC` (a kevy crash-restart bumps the
  feed generation): rebuild the affected prefix into the RDS, then
  resume — at-least-once + idempotent SQL makes this safe.

### Phase 6 — Decommission

When confidence hardens (weeks of clean diffs, one exercised
failover), stop the reverse mirror, take a final RDS dump for the
archive, and move the operational story fully onto kevy: snapshots +
AOF (+ feed-cursor recovery points) per
[persistence.md](https://kevy.golia.jp/docs/persistence/), replica/failover posture per
[availability.md](https://kevy.golia.jp/docs/availability/).

- **Clamp:** a restore drill from kevy's own artifacts (snapshot +
  feed replay) before the RDS is turned off — never after.

## Common pitfalls

- **DECIMAL through two write paths.** If the dual-write path stores
  `"10.00"` and the backfill stores `"1000"` (minor units), every
  digest check fails and — worse — reads disagree. Fix the format in
  phase 1 and make both paths share one serializer.
- **Auto-increment collision.** Forgetting to seed `seq:*` keys above
  the RDS max id hands out ids that already exist. Seed in phase 5,
  verify with one `GET seq:order` before opening writes.
- **Hot keys.** A kevy key lives on exactly one shard; the RDS row
  every request touched becomes a single-shard serialization point.
  Shard hot counters (per-user keys, block-allocated sequences) and
  let `KIND agg` do the read-side summing.
- **Large values.** Multi-hundred-KB rows work but make every hop
  heavier (export frames, replication, feed frames) and shift
  serving cost to the network path. Keep hot rows lean; store cold
  blobs in object storage with a pointer field, or split
  rarely-read columns into a sibling key.
- **TTL semantics.** `EXPIRE` with a non-positive TTL deletes the key
  immediately (Redis contract). Exported TTLs travel as absolute
  `PEXPIREAT` deadlines, so a slow migration doesn't extend
  lifetimes. Digests ignore TTLs (values only) — TTL correctness is
  checked by sampling `PTTL`, not by `diff`.
- **`KEYS`/`SCAN` habits.** Ops one-liners that did `SELECT COUNT(*)`
  should use `PREFIX.STATS` or `IDX.COUNT` — `KEYS pattern` is a
  full-keyspace gather and `SCAN MATCH` a full NON-incremental sweep — every SCAN call walks the entire keyspace on every shard and returns all matches with cursor 0, so the usual SCAN loop terminates after one round trip;
  neither is a serving path (and on a big keyspace, barely an ops
  path).
- **Index build racing reads.** Right after declarations, queries
  answer `-INDEXBUILDING`. Clients in the cutover window need the
  poll-and-retry loop (below), or declare in phase 3 where no reader
  is looking yet.

---

# The toolchain (`kevy-cli`)

```
kevy-cli export  -p 6379 --prefix user: dump.resp
kevy-cli import  -p 6004 --strict dump.resp        # ≥200k cmd/s
kevy-cli import  -p 6004 --resume dump.resp        # after interruption
kevy-cli digest  -p 6004 user:
kevy-cli diff    hostA:6379 hostB:6004 user: order:
kevy-cli copy-prefix   -p 6004 --rate 5000 user: staging:user:
kevy-cli delete-prefix -p 6004 --rate 5000 --dry-run tmp:
kevy-cli inspect -p 6004 user:
```

## Wire format

`export` writes a plain **RESP command stream** of rebuild frames —
`DEL` + `SET`/`HSET`/`RPUSH`/`SADD`/`ZADD`, plus absolute `PEXPIREAT`
for TTLs. That makes the file bidirectionally compatible with
`redis-cli --pipe`: kevy exports feed a Redis, and any RESP command
file feeds `kevy-cli import` — including one you generate yourself
from an RDS dump (the playbook's phase 3).

The leading `DEL` per key makes replay **rebuild from scratch** —
genuinely idempotent for every type (an append verb like RPUSH would
otherwise double list content on re-import).

## Consistency and resumability

- Export is per-key point-in-time under a SCAN walk (SCAN-class
  guarantees; keys written during export may appear in either state,
  vanished keys are skipped). No global snapshot — by design.
- Import pipelines 512 commands per batch and fsyncs a byte offset to
  `<file>.progress` after every batch. `--resume` restarts there;
  because frames rebuild, overlap is harmless. `--strict` aborts on
  the first server error; otherwise errors are counted and reported.
- `kill -9` mid-import is a gated scenario: resume converges to the
  same `PREFIX.DIGEST`.

## Verification

`PREFIX.DIGEST <prefix>` (server + embedded `prefix_digest`) returns
`[count, hex64]` — an order-insensitive checksum over canonical row
bytes (hash fields and set members sorted, zset by score bits then
member, list in order — list order IS identity). It is insensitive to
shard count and insert order, so it compares across topologies.
`kevy-cli diff A:port B:port prefix…` exits non-zero on any mismatch.

TTLs do not participate in the digest (they decay); values do.

## Bulk operations

`copy-prefix` re-keys every row under a new prefix via read + rebuild
frames (the server intentionally has no COPY verb; TTLs carried as
absolute deadlines). `delete-prefix` SCANs + UNLINKs. Both take
`--rate N` (token bucket, strict pacing from the first op) and
delete supports `--dry-run`.

## Loading into an indexed keyspace

### Waiting for index readiness

`IDX.CREATE` returns immediately and backfills in the background;
queries answer `-INDEXBUILDING` until done. The standard wait is
polling `IDX.LIST` — its `state` column flips from `building` to
`ready`:

```
until kevy-cli -p 6004 IDX.LIST | grep -A1 my_index | grep -q ready; do sleep 1; done
```

Backfill speed scales with DOCUMENT SIZE for text indexes: ~7s per
million small rows, but multi-KB bodies index at roughly 85s per
million (measured: 200k mail-sized bodies in 17s).

### Verifying a whole migration in one command

`kevy-cli diff` compares any number of prefixes across two live
servers in one call — prefer it over per-prefix digest pairs:

```
kevy-cli diff 127.0.0.1:6004 127.0.0.1:6005 msg: mbox: usr: tag: session:
```

### Large exports

The dump is uncompressed RESP text (fast, greppable). For 10GB+
keyspaces pipe through gzip — the format is stream-friendly:

```
kevy-cli export -p 6004 /dev/stdout | gzip > dump.kevy.gz
gunzip -c dump.kevy.gz | kevy-cli import -p 6005 --strict /dev/stdin
```

(`--resume` needs a real file for its .progress sidecar — decompress
to disk first if you want resumability.)

Create indexes **after** the bulk load: the index engine's backfill
builds from existing data at bulk speed (~7s per million rows
measured), which beats paying per-write hook maintenance a million
times. Order of operations, not a switch:

```
kevy-cli import -p 6004 dump.resp
kevy-cli -p 6004 IDX.CREATE users ON PREFIX user: FIELD age TYPE i64 KIND range
```

Gate: `bench/onrampgate.sh` (1M-row round trip, ≥200k cmd/s import,
kill -9 resume convergence, ±20% rate accuracy).

==============================================================================
# UPGRADING
==============================================================================

# Upgrading kevy

Two chapters, newest first: **3.x → 4.0** (an API-definition major:
the wire and the disk carry over, the Rust faces changed once and are
now frozen) and **2.x → 3.x** (a capability major: everything carried
over). Each chapter is explicit about what upgrades automatically,
what needs a code change, and how to go back.

---

# 3.x → 4.0

4.0 is the industrial-production declaration. The semver major was
spent deliberately — one break window in which every long-standing
public-API debt was paid, and after which the surfaces are **frozen**:
later 4.x releases are additive only. If you talk to kevy over the
wire, 4.0 is a binary swap. If you link a kevy crate, expect a short,
mechanical migration — every change below has a one-line rule.

## TL;DR — versions at a glance

| Component | 3.x era | 4.0 | Action |
|---|---|---|---|
| `kevy` (server) | 3.18.x | 4.0.0 | swap the binary, restart on the same data dir |
| `kevy-embedded` | 3.18.x | 4.0.0 | bump + apply the API table below |
| `kevy-client` | **1.14.x** | **4.0.0** | bump — version-line unification (same move `kevy-embedded` made at 3.0.0) + the API table |
| `kevy-client-async` | **1.1.x** | **4.0.0** | same |
| `kevy-wasm` / `@goliajp/kevy` (npm) | — | 4.0.0 | new in 4.0 — [docs/wasm.md](https://kevy.golia.jp/docs/wasm/) |
| Infra crates (`kevy-store`, `kevy-rt`, …) | 3.18.x | 4.0.0 | follow the workspace version |

## What is compatible automatically

**Wire protocol.** RESP is unchanged, and every verb alias (`SLAVEOF`,
`HMSET`, …) is kept. Redis clients, scripts, and `redis-cli` sessions
work as before; the reply-parity suite against valkey 9.1 still gates
CI.

**Snapshots and AOF.** A 4.0 binary reads every 3.x (and 2.x)
snapshot format and replays 3.x AOFs unchanged. Formats did not
change in 4.0 — downgrade to 3.18 is equally a binary swap (unlike
the 3.x → 2.x direction, which has a format edge; see the 2.x → 3.x
chapter).

**Config.** Every 3.x config key is accepted and means the same
thing. Two keys got *stricter or truer* semantics — see "Behavior
changes" below (`notify_keyspace_events` unknown-flag rejection,
`min_replicas_max_lag_ms` enforcement).

**One removed knob.** Custom snapshot/AOF *filenames* are gone (the
`kevy-embedded` `Config::with_snapshot_filename` /
`with_aof_filename` builders). The on-disk layout is now fixed at
`dump-{i}.rdb` / `aof-{i}.aof` per shard. Directories that used the
default names — including every legacy single-file dir — load
unchanged; only dirs written under a *custom* name need a one-time
`mv` to the fixed names before the first 4.0 open.

## The API break table

Everything in this section is a compile-time break with a mechanical
fix. Nothing here changes runtime semantics except where called out.

### 1. `flush()` shims removed

The deprecated aliases are gone; the surviving name says what it does
(it WIPES the store):

| Crate | Removed | Call instead |
|---|---|---|
| `kevy-embedded` | `Store::flush()` | `Store::flushall()` |
| `kevy-client` | `Connection::flush()` | `Connection::flushall()` |
| `kevy-store` | `Store::flush()` | `Store::flushall()` |

### 2. One error currency: `KevyError`

Every public fallible face of `kevy-embedded` and `kevy-client` now
returns `KevyResult<T>` (`Result<T, KevyError>`) instead of
`io::Result<T>`. The type lives in `kevy-store` and is re-exported
by both crates:

**One deliberate exception.** The change feed keeps its own error type:
`changes_since` and `changes_tail` return `Result<_, FeedError>`, and there is
no `From<FeedError> for KevyError`. `FeedError::Resync` and `FeedError::Future`
are not failures — they are stream control signals telling the reader where it
is relative to the log, and folding them into a general-purpose error enum would
invite callers to `?` past the one thing they must handle. See
[CDC feeds](https://kevy.golia.jp/docs/cdc/).

```rust
pub enum KevyError {
    Store(StoreError),      // structured engine errors, no longer
                            // flattened into io::Error strings
    Io(std::io::Error),     // real I/O, preserved via From
    Protocol(String),       // server error replies, wire text intact
    ReadOnly,               // replica write rejection
    InvalidInput(String),   // e.g. URL parse errors
    NotFound(String),
    Unsupported(String),    // e.g. remote-only calls on embedded
    TimedOut,               // e.g. Subscription::recv_timeout
    Closed,                 // stream/bus gone; also terminates
                            // subscriber iterators
}
```

Migration is usually just the return-type annotation — `?` keeps
working because `From<io::Error>` and `From<StoreError>` exist:

```rust
// 3.x
fn warm(conn: &mut Connection) -> std::io::Result<()> {
    conn.set(b"greeting", b"hello")?;
    Ok(())
}

// 4.0
use kevy_client::{Connection, KevyResult};

fn warm(conn: &mut Connection) -> KevyResult<()> {
    conn.set(b"greeting", b"hello")?;
    Ok(())
}
```

Code that *inspected* errors gets strictly better off — match the
variant instead of parsing strings:

| 3.x signal | 4.0 |
|---|---|
| `io::Error::other("kevy-store: …")` wrapper text | `KevyError::Store(e)` — the structured `StoreError` |
| replica write rejection: `io::Error::other("READONLY …")` | `KevyError::ReadOnly` (its `Display` still starts with `READONLY`) |
| server `-ERR …` replies as opaque `io::Error` | `KevyError::Protocol(text)` — wire text preserved |
| `ErrorKind::TimedOut` from `Subscription::recv_timeout` | `KevyError::TimedOut` |
| `ErrorKind::UnexpectedEof` as the subscriber-stream-gone signal | `KevyError::Closed`; `SubscriberEvents` / `SubscriberMessages` iterators yield `KevyResult<_>` and end on it |
| `ErrorKind::Unsupported` for remote-only features | `KevyError::Unsupported(msg)` |

There is deliberately **no** `From<KevyError> for io::Error`: that
back-edge would reinstate the lossy downgrade this change removes. At
a boundary that truly needs `io::Error`, convert explicitly and own
the loss.

(`kevy-resp-client` keeps its `io::Result` face on purpose — it is a
pure transport stone and `io::Error` is its honest currency.)

### 3. Constructor naming: resources `open`, network `connect`

One verb per kind, everywhere. Local, file-backed things `open`;
things with a peer `connect`; pure in-memory values `new`. The
renames:

| Crate | 3.x | 4.0 |
|---|---|---|
| `kevy-client` | `Connection::open(url)` | `Connection::connect(url)` |
| `kevy-client` | `Subscriber::open(url, channels)` | `Subscriber::connect_channels(url, channels)` |
| `kevy-client-async` | `AsyncConnection::open(url)` | `AsyncConnection::connect(url)` |
| `kevy-client-async` | `AsyncSubscriber::open(url, channels)` | `AsyncSubscriber::connect_channels(url, channels)` |
| `kevy-resp-client` | `RespClient::from_url(url)` | `RespClient::connect_url(url)` |

Already conforming, unchanged: `kevy_embedded::Store::open`,
`kevy_persist::Aof::open`, `kevy_store::Store::new`,
`ClusterClient::connect`, `RwClient::connect`,
`Subscriber::connect(url)`, `RespClient::connect(host, port)`.

### 4. `kevy_rt::Runtime` is built, not positioned

The positional constructor is gone; `Runtime` is its own builder:

```rust
// 3.x
let rt = Runtime::new([127, 0, 0, 1], 6004, 4, commands);

// 4.0
let rt = Runtime::builder(commands)
    .bind([127, 0, 0, 1], 6004)
    .shards(4);
```

`builder(commands)` defaults: bind `127.0.0.1:6004`, 1 shard, AOF on
(`EverySec`), data dir `"."`. `bind` / `shards` are `#[must_use]`
setters like the existing `with_*` chain. This is also the visible
face of the 4.0 instance work: a `Runtime` no longer touches global
state, so one process can run several independent kevy instances.

### 5. `kevy-store` writes take borrowed argv

The owned-argument forms are removed; the borrowed forms (previously
the `_borrowed` twins) now own the canonical names:

| 3.x (owned) | 4.0 (borrowed, same name) |
|---|---|
| `del(&[Vec<u8>])` / `exists(&[Vec<u8>])` | `del(&[&[u8]])` / `exists(&[&[u8]])` |
| `hset(&[(Vec<u8>, Vec<u8>)])` / `hdel(&[Vec<u8>])` / `hmget(&[Vec<u8>])` | `hset(&[(&[u8], &[u8])])` / `hdel(&[&[u8]])` / `hmget(&[&[u8]])` |
| `sadd` / `srem` / `lpush` / `rpush` / `zrem` `(&[Vec<u8>])` | same names, `(&[&[u8]])` |
| `zadd(&[(f64, Vec<u8>)])` | `zadd(&[(f64, &[u8])])` |
| `zadd_flags_borrowed(…)` | renamed `zadd_flags(…)` |

```rust
// 3.x
store.del(&[b"k1".to_vec(), b"k2".to_vec()]);

// 4.0 — pass slices; no allocation
store.del(&[b"k1".as_slice(), b"k2".as_slice()]);
```

This is a performance fix wearing an API change: `kevy-embedded`'s
facades now hand borrowed argv straight through, and the per-call
`to_vec()` copies on every embedded write path are gone.

### 6. `Commands` trait + `Route` (embedders with a custom command set)

Only relevant if you `impl kevy_rt::Commands` yourself:

- `dispatch_resp3` (Vec-returning form) removed — override
  `dispatch_into_resp3`.
- `wake_idx` method removed — populate `ResolvedCmd::wake_idx` in
  your `resolve()`; the field is unchanged.
- `extension_reduce_v3` and the old two-arg `extension_reduce` merged
  into `extension_reduce(argv, chunks, proto) -> ExtensionReduced`;
  return `ExtensionReduced::Reply(bytes)`, or
  `ExtensionReduced::Continue(argv2)` instead of the old
  NUL-prefixed in-band continuation frame.
- `Route::{MGet, SInter, SUnion, SDiff, ZInterCard}` collapsed into
  `Route::Gather(MultiOp)`; `Route::{Keys, Scan, RandomKey}` into
  `Route::Keyspace(KeyShape, Option<Vec<u8>>)`. `MultiOp` and
  `KeyShape` are newly public.
- `Commands::on_replication_view` replicas entry is now
  `(String, Ipv4Addr, u16, u64, Option<ReplicaAck>)` — a leading
  replica-id `String`, then the peer `(Ipv4Addr, u16)`, the sent
  offset, and `ReplicaAck { acked_offset, ack_age_ms }` (which
  replaces the bare acked offset); destructure it.

## Behavior changes (no code change, ops-visible)

- **`-LOADING` is real.** While a replica swallows a full-resync
  snapshot, reads answer `-LOADING` instead of serving the
  half-replaced dataset. `PING`, `INFO`, and `HELLO` stay answerable
  (health checks keep working), matching the verbs Redis exempts.
  Retry-on-`-LOADING` loops written for Redis behave correctly as-is.
- **`notify_keyspace_events` rejects unknown flag characters** at
  config parse instead of silently ignoring them — and the flag set
  grew real `x` (expired), `e` (evicted), and `n` (new-key) events.
  A config that previously smuggled a typo through will now fail
  loudly; fix the flag string.
- **`min-replicas-to-write` counts only live ACKs.** The
  `min_replicas_max_lag_ms` key existed in 3.x and is now enforced: a
  replica whose last ACK is older than the window no longer satisfies
  the write gate. Deployments relying on a *stalled* replica to keep
  writes flowing will see `-NOREPLICAS` — which is the semantics the
  key always promised.
- **The `CLIENT` face tells the truth**: `CLIENT LIST` is the real
  connection table (getpeername-backed addresses, globally unique
  ids), `CLIENT KILL` really kills (including blocked connections),
  `CLIENT SETNAME` sticks, and `connected_clients` in `INFO` is a
  live gauge.
- **`SHUTDOWN` drains gracefully**: in-flight replies finish and the
  AOF gets a final fsync before exit, closing the everysec tail
  window that a bare SIGTERM used to leave unsynced.
- **`ROLE` / `INFO replication` aggregate across shards** with
  per-replica identity (`ip:port` and true per-replica offsets).
  Parsers that assumed one summary line per server keep working; the
  per-replica lines are richer.

## The feature system (new in 4.0)

`kevy-embedded` is now feature-tiered so small targets pay only for
what they use. The default remains everything-on:

| Feature | Adds | Pulls in |
|---|---|---|
| `core` | KV + TTL + pubsub + atomic/pipeline | (nothing) |
| `persist` | snapshots + AOF | `kevy-persist` |
| `index` | declared indexes + views | `kevy-index` |
| `text` | full-text (BM25) segments | `index`, `kevy-text` |
| `vector` | HNSW ANN segments | `index`, `kevy-vector` |
| `replicate` | replication + CDC feed | `persist`, `kevy-replicate` |
| `listener` | read-only RESP listener | (nothing) |

The `core` tier cross-compiles for musl targets and holds an
enforced budget (≤ 700 KB binary, ≤ 2 MB empty-store RSS); five
foundation crates additionally build `no_std`. See
[docs/iot.md](https://kevy.golia.jp/docs/iot/). At the other end of the size spectrum, the
same embedded core now runs in the browser as `@goliajp/kevy` —
see [docs/wasm.md](https://kevy.golia.jp/docs/wasm/).

## Downgrading 4.0 → 3.18

Binary swap back; snapshot and AOF formats are shared. The only edge:
a config file using the new notify flags (`x`/`e`/`n`) parses on 3.18
but the events never fire there.

---

# 2.x → 3.x

kevy 3.x is a superset of 2.x: every 2.x workload runs unchanged, and
the upgrade is a binary swap for the server and a dependency bump for
embedded users. This chapter is explicit about what carries over
automatically, what changed names or numbers, and the one direction
that needs care (downgrading back to 2.x).

## TL;DR — versions at a glance

| Component | 2.x era | 3.x (final: 3.18.x) | Action |
|---|---|---|---|
| `kevy` (server) | 2.0.x | 3.18.x | swap the binary, restart on the same data dir |
| `kevy-embedded` | **1.x** (1.4–1.16) | **3.x** | bump the dep — the 1.x line ended at v3.0.0 when the whole workspace unified on one version |
| `kevy-client` | 1.12.x | 1.13–1.14 | bump; API unchanged |
| `kevy-client-async` | 1.0.x | 1.1.x | bump; API unchanged |
| `kevy-cli` | unpublished | 3.x | `cargo install kevy-cli` — now carries the whole migration toolchain |
| Infra crates (`kevy-store`, `kevy-rt`, …) | 2.0.x | 3.x | follow the workspace version |

The `kevy-embedded` jump from 1.x to 3.x is a **version-line
unification, not an API rewrite**: the 1.16 surface is contained in
3.x. If your `Cargo.toml` says `kevy-embedded = "1"`, change it to
`"3"` and rebuild — or go straight to `"4"` with the chapter above.

## What is compatible automatically

**Wire protocol.** RESP is unchanged. 3.x remains reply-checked
byte-for-byte against valkey 9.1 in CI (98 commands). Existing Redis
clients, scripts, and `redis-cli` sessions work as before.

**Snapshots.** The 3.x loader reads every 2.x snapshot format
(`KEVYSNAP` versions 2–5): relative-TTL v2 files, absolute-TTL v3,
stream-group v4, and feed-cursor v5. Point a 3.x server at a 2.x data
directory and it loads.

**AOF.** The AOF is a verb log and 3.x's verb set is a superset of
2.x's — replay works unchanged. `appendfsync` semantics are
unchanged.

**Config.** Every 2.x config key is accepted. New sections
(`[replication] single_source`, `--accept-shards`, …) are additive
with defaults that reproduce 2.x behavior.

## Upgrade steps

### Server deployment

1. Take a snapshot on the running 2.x server (`SAVE` or your normal
   backup), and keep a copy — see “Downgrading” below for why.
2. Stop 2.x, start the 3.x binary with the same flags and data dir.
3. Verify: `DBSIZE` matches, and if you want cryptographic-grade
   assurance run `kevy-cli digest -p <port> <prefix>` before and
   after — equal digests mean an identical keyspace.

Rolling a replica pair: upgrade the replica first, let it re-sync,
then fail traffic over and upgrade the former primary. (2.x has no
managed failover, so from 2.x this is the usual manual swap. Once
you are on 3.15+, the fail-over step itself becomes one verb —
`FAILOVER host port` — see
[docs/availability.md](https://kevy.golia.jp/docs/availability/).)

### Embedded applications

1. `kevy-embedded = "3"` in `Cargo.toml`.
2. Rebuild. The 1.16 API is present unchanged; new capability
   surfaces (index/view/text/vector/feed/replication) are additive
   methods and `Config` options.
3. One trait note: if (and only if) you wrote a custom
   `impl kevy_rt::Commands` and construct `ResolvedCmd` literals,
   two fields were added during the v2 arc (`block_hint`,
   `wake_idx`). The default `resolve()` fills them; literal
   constructors add the two fields.
4. On-disk data from an embedded 1.x app loads as-is (same snapshot
   formats as the server).

### Clients

`kevy-client 1.13+` / `kevy-client-async 1.1` are drop-in: the minor
bump only re-pins internal crates to the 3.x workspace. Generic Redis
client libraries are unaffected either way.

## What 3.x adds (why you upgrade)

Declared indexes with hydration (`IDX.*`), named views (`VIEW.*`),
write-time aggregates (GROUP BY / distributed top-K), dictionary-free
CJK full-text search with BM25, HNSW vector KNN (plus hybrid BM25+KNN
fusion), CDC feeds with the recovery-point contract (`FEED.*`),
embedded-as-primary replication, the machine-readable contract
(`COMMAND DOCS`, generated references, the `kevy-mcp` MCP server),
the availability arc (replication lag truth, `FAILOVER`, quorum crash
elections, the `WAIT` / `REPL.TOKEN` / `REPL.WAIT` consistency
ladder — [docs/availability.md](https://kevy.golia.jp/docs/availability/)), and the migration
toolchain (`kevy-cli import/export/--verify/diff/
inspect/digest`). Start at [docs/designing-on-kevy.md](https://kevy.golia.jp/docs/designing-on-kevy/)
and [docs/cookbook.md](https://kevy.golia.jp/docs/cookbook/); performance receipts live in
[bench/PERF-LEDGER.md](https://github.com/goliajp/kevy/blob/main/bench/PERF-LEDGER.md).

None of these activate implicitly: a 3.x server with a 2.x workload
has an empty catalog, and the index hook on an empty catalog is on
the perfgate ratchet (no regression vs 2.x).

## Downgrading (the one direction that needs care)

A 3.x server **writes** snapshot format v4, or v5 once a CDC feed
cursor exists. A 2.x binary reads at most v4:

- If you never enabled feeds, a 3.x snapshot loads on 2.x.
- If feeds were active (v5), 2.x refuses the file. Downgrade path:
  `kevy-cli export` on 3.x → `kevy-cli import` into a fresh 2.x —
  or restore the pre-upgrade backup from step 1 and accept the gap.

Verbs introduced in 3.x (`IDX.*`, `VIEW.*`, `FEED.*`, …) naturally
don't replay on a 2.x binary — if you used them, the export/import
path is the correct downgrade, not AOF replay.

## Version history in one line each

- **3.0.0** — the serving-engine declaration (indexes, views, FTS,
  ANN, CDC, on-ramp; eleven gated trains).
- **3.8.0** — the perf arc (measured vs valkey 9.1 and RediSearch;
  bare face 1.6–3.3×, ANN 1.64× ahead at recall 1.000, FTS single
  common term 93×; embedded-as-primary replication). No releases
  were cut between 3.0.0 and 3.8.0; 3.8.0 contains trains v3.1–v3.8.
- **3.17.0** — the availability release: the AI-native serving faces
  (machine-readable verb contract, generated docs, `kevy-mcp`, hybrid
  retrieval) and the availability arc (replication heartbeat/ACK
  truth, `FAILOVER` + quorum crash elections, the consistency
  ladder, contract gates in CI). Contains trains v3.9–v3.17; no
  releases were cut in between.
- **3.17.1–3.17.4** — maintenance: the `luna-core` Lua runtime bump,
  the docs/migration wave, first-adopter feedback (`kevy-cli
  --embed`), and the docs/i18n polish wave.
- **3.18.0** — the structure release: LOC debt to zero with the
  limits enforced in CI, six more stones fuzzed (day-one harvest:
  four real bugs fixed), miri/pedantic/missing-docs sweeps, Rust
  1.97.0.