wombatkv-core

Foundational types and traits shared across the WombatKV stack. The deepest crate in the dep tree, no wombatkv-* dependencies of its own, so changes here ripple everywhere. Touch with care.

What lives here

metadata, block-metadata types that the radix index and the on-disk block format both refer to:
- BlockMeta, per-block payload size + parent chain + format family marker
- LayoutTag (16 bytes), per-block layout family (ds4-v1, sglang-page-v1, future engines). Designed for multi-engine differentiation; production callers currently pass [0u8; 16].
- ModelDigest (24 bytes), truncated model fingerprint (sha256) used as the second factor in S3 key derivation alongside the block hash.
reuse, cross-cutting reuse-policy primitives: when can a block be reused, when does a fingerprint apply across model variants, what's a safe canonical-block boundary.

The crate is #![forbid(unsafe_code)]. Pure Rust, no I/O, no allocation beyond what the caller provides, it can compile into constrained reader environments.

Stack position

wombatkv-core      ← you are here (leaf, no internal deps)
      ↓ depended on by
wombatkv-format        wombatkv-radix        wombatkv-store        wombatkv-node        wombatkv-cabi

Minimal usage

use wombatkv_core::metadata::{BlockMeta, LayoutTag, ModelDigest};

// Construct a root block (no parent) of 128 KiB with a zero layout tag.
let model_digest: ModelDigest = [0u8; 24];
let layout: LayoutTag = [0u8; 16];
let meta = BlockMeta::new_root(128 * 1024, model_digest, layout);

assert_eq!(meta.payload_bytes, 128 * 1024);
assert!(meta.parent_hash.is_none());

Test

cargo test -p wombatkv-core --release

RFCs