Module kv 

Server KV store (docs/design/kv.md): opcodes, record codecs, and the client-side mirror reducer. Server KV store wire protocol (docs/design/kv.md).

A host-local key→value store with CAS writes and prefix-watch subscriptions. Keys are raw UTF-8 (≤ [KV_MAX_KEY] bytes, no NUL, non-empty); values are opaque bytes, LZ4 on the wire. CAS is BLAKE3-128 over value bytes with the zero-hash absent sentinel, [docs/design/fs-write.md]’s conflict model verbatim.

All integers little-endian, tightly packed, as everywhere in the protocol.

Structs

KvEntry

One mirrored entry.

KvMirror

The complete watcher obligation: apply updates, read live.

KvPut

A CAS put or delete (C2S_KV_PUT).

KvRecordIter

Iterate records in an uncompressed KV_UPDATE payload. Unknown kinds are skipped via record_len; a malformed record ends iteration (forward-compatible with future record extensions, the fs rule).

Enums

KvRecord

One decoded record from a KV_UPDATE payload.

Constants

C2S_KV_ACK

Cumulative acknowledgement: [0x72][kv_id:2][update_id:4]

C2S_KV_FETCH

Fetch one value: [0x74][nonce:2][key_len:2][key:N]

C2S_KV_OPEN

Subscribe to a prefix: [0x70][nonce:2][flags:1][inline_max:4][prefix_len:2][prefix:N] The prefix is a literal byte prefix (no glob); empty = whole store.

C2S_KV_PUT

CAS put/delete: [0x73][nonce:2][flags:1][base:16][key_len:2][key:N][value:LZ4] base is the CAS precondition on the current value bytes: non-zero = match-or-CONFLICT, zero = create-exclusive, ignored under KV_PUT_NO_CAS.

C2S_KV_STOP

Close a subscription: [0x71][kv_id:2]

FEATURE_KV

S2C_HELLO feature bit: server supports the KV_* family (docs/design/kv.md). BLIT_KV=0 refuses every KV_* at dispatch with PERMISSION instead of un-advertising.

KV_CLOSED_RESOURCE_LIMIT

Queued-unacked bytes exceeded BLIT_KV_UNACKED_MAX (docs/design/kv.md § Budgets); the subscription was dropped.

KV_CONTENT_FULL

KV_CONTENT_NONE

KV_ID_INVALID

kv_id reported by a failed KV_OPENED.

KV_MAX_KEY

Maximum key length in bytes (fixed, not an env knob).

KV_PUT_DELETE

Remove the entry (value must be empty). A delete is a put of absence; base zero with DELETE is INVALID (delete-iff-absent is meaningless).

KV_PUT_DURABLE

fsync the store before replying; default trades durability for latency.

KV_PUT_NO_CAS

Ignore base; unconditional put/delete.

KV_RECORD_DELETE

KV_RECORD_UPSERT

KV_STATUS_BUDGET

KV_STATUS_CONFLICT

A CAS precondition failed (mismatch, or create-exclusive on an existing key). KV_DONE.hash carries the current value hash.

KV_STATUS_INVALID

KV_STATUS_NOT_FOUND

KV_STATUS_OK

KV_STATUS_OTHER

KV_STATUS_PERMISSION

KV_STATUS_TOO_LARGE

KV_UPDATE_SNAPSHOT_END

This batch completes the initial snapshot; subsequent updates are live.

S2C_KV_CLOSED

Subscription ended server-side: [0x74][kv_id:2][reason:1] After it the kv_id is dead; a client that still wants the prefix re-opens with KV_OPEN and receives a fresh snapshot — lossless, because updates carry state, not events (docs/design/kv.md § Watch).

S2C_KV_DONE

Put result: [0x72][nonce:2][status:1][hash:16][mtime_ns:8] — one per KV_PUT. On success hash is the new value hash (zero for a delete); on CONFLICT it carries the current hash so the client rebases without a round trip.

S2C_KV_OPENED

Subscription accepted or refused: [0x70][nonce:2][kv_id:2][status:1][detail_len:2][detail:N]

S2C_KV_UPDATE

Snapshot/live records: [0x71][kv_id:2][update_id:4][flags:1][records:LZ4]

S2C_KV_VALUE

Fetch result: [0x73][nonce:2][status:1][hash:16][data:LZ4]

Functions

append_kv_record

Append one record to an uncompressed KV_UPDATE records buffer.

kv_key_valid

Wire-key validity: non-empty UTF-8 (guaranteed by &str), ≤ KV_MAX_KEY bytes, no NUL.

kv_put_declared_value_len

Parse a C2S_KV_PUT. None = malformed, a non-UTF-8 key, or a value whose declared decompressed size exceeds the protocol cap. The decompressed size a C2S_KV_PUT claims for its value, read without inflating it.

kv_records

kv_status_text

Human-readable name for a KV_* status code.

msg_kv_ack

msg_kv_closed

msg_kv_done

Build an S2C_KV_DONE. On success hash is the new value hash (zero for a delete); on CONFLICT the current hash.

msg_kv_fetch

msg_kv_open

msg_kv_opened

msg_kv_put

msg_kv_stop

msg_kv_update

Build a KV_UPDATE from an uncompressed records buffer.

msg_kv_value

parse_kv_ack

Parse a C2S_KV_ACK → (kv_id, update_id).

parse_kv_closed

Parse an S2C_KV_CLOSED → (kv_id, reason).

parse_kv_done

Parse an S2C_KV_DONE → (nonce, status, hash, mtime_ns).

parse_kv_fetch

Parse a C2S_KV_FETCH → (nonce, key).

parse_kv_open

Parse a C2S_KV_OPEN → (nonce, flags, inline_max, prefix).

parse_kv_opened

Parse an S2C_KV_OPENED → (nonce, kv_id, status, detail).

parse_kv_put

parse_kv_stop

Parse a C2S_KV_STOP → kv_id.

parse_kv_value

Parse an S2C_KV_VALUE → (nonce, status, hash, data).