GrainStore

GrainStore

std.db.lsm provides the native Janus Log-Structured Merge storage path. Cluster consumers normally import std.cluster.grainstore, which re-exports the same types and functions without exposing storage-internal module layout.

u32 Store

GrainStoreU32U32 is the scalar key/value store used by the bounded L0 compaction path.

use std.cluster.grainstore as grainstore

const WAL_PATH: [*:0]u8 = "/tmp/example-grainstore.wal"

var store = grainstore.open_u32(WAL_PATH, 42)
if not grainstore.put_u32(&store, 7, 99) do
    _ = grainstore.close_u32(&store)
    return 1
end

let hit = grainstore.get_u32(&store, 7)
if hit == null do
    _ = grainstore.close_u32(&store)
    return 2
end

if not grainstore.delete_u32(&store, 7) do
    _ = grainstore.close_u32(&store)
    return 3
end

if grainstore.get_u32(&store, 7) != null do
    _ = grainstore.close_u32(&store)
    return 4
end

_ = grainstore.close_u32(&store)

Tombstones

delete_u32 is a durable delete, not an in-memory remove. It appends a WAL frame with the normal 4-byte little-endian key and a zero-length value. The u32 MemTable stores ?u32: Some(value) is live, None is a tombstone.

Flush preserves the marker as a zero-length SSTable value. Reads treat that shape as a miss and stop the search, so an older L0 entry cannot resurrect a deleted key.

Compaction preserves tombstones across the bounded L0 helper:

• older value + newer tombstone -> tombstone
• older tombstone + newer value -> value
• tombstone without a newer value -> tombstone

Bottom-level tombstone elision is not implemented yet. Until the compactor can prove that no older records remain below an output file, it must keep the tombstone.

Bytes Store

GrainStoreBytes stores byte keys and byte values. It is the substrate for std.stl.lsm_store, including owned puts, WAL replay, flush/attach, prefix counting, and L0 manifest recovery.

The bytes store is append-oriented today. It does not expose delete_bytes or TTL metadata.

Verification

./scripts/zb test-lsm-tombstone-compaction
./scripts/zb test-cluster-grainstore
./scripts/zb test-lsm-grainstore-bytes-replay
./scripts/zb test-lsm-grainstore-manifest
./scripts/zb test-stl-lsm-store-v2

Current Limits

• Single writer per store.
• TTL metadata and TTL-aware compaction are not implemented.
• Group-fsync WAL batching is not implemented.
• Wider level metadata beyond the current L0 helper and bytes/STL manifest policy is future work.
• Bottom-level tombstone elision is future work.