Module kv_shard_store 

KvShardStore — a ShardStore implementation backed by Go’s Cosmos KV store via C function pointer callbacks.

Design

Instead of maintaining an in-process copy of all shard data, KvShardStore forwards every ShardStore read and write directly to the Cosmos KV store through a set of C callbacks registered at creation time. Go registers //export functions that dispatch to the current block’s store.KVStore through a stable proxy pointer.

This gives ShardTree true lazy loading: on a cold start only the data that is actually accessed (the frontier shard + cap + checkpoints) is read. No explicit restore loop, no O(n) blob loading, no shard geometry in Go.

KV key schema (matches keys.go)

Prefix	Key	Value
0x0F	0x0F || u64 BE shard_index	shard blob
0x10	0x10	cap blob
0x11	0x11 || u32 BE checkpoint_id	checkpoint blob

Buffer ownership

get returns a C-malloc’d buffer that Rust frees with the provided free_buf callback after copying the value. All write callbacks receive a Rust-owned slice (pointer + length); they must copy the data if they need it to outlive the call.

Iterator protocol

iter_create(ctx, prefix, prefix_len, reverse) returns an opaque handle (a cgo.Handle on the Go side). iter_next advances and writes C-malloc’d key + value; Rust frees each pair with free_buf before the next call. iter_free closes and drops the iterator. iter_next returns 0 on a valid entry, 1 when exhausted, -1 on error.

Structs

KvCallbacks

Bundle of C function pointers + context passed to KvShardStore.

KvShardStore

A ShardStore that stores all state in the Cosmos KV store via Go callbacks. Gives ShardTree true lazy loading: only the data it actually accesses is read from KV.

Enums

KvError

Error type for KvShardStore operations.

Type Aliases

KvDeleteFn

Delete a key. Returns 0 on success, -1 on error.

KvFreeBufFn

Free a C-malloc’d buffer returned by a KV callback.

KvGetFn

Retrieve a value from the KV store.

KvIterCreateFn

Create an iterator over the given prefix.

KvIterFreeFn

Close and free an iterator handle.

KvIterNextFn

Advance the iterator and return the next key-value pair as C-malloc’d buffers. Caller frees with free_buf.

KvSetFn

Write a key-value pair. Returns 0 on success, -1 on error.