[exKAZUu]

Why

Applying commitkv to the LLM response cache of an application (201,238 keys, 1.17 GB of values, 75 MB stored) showed two problems.

1. Reading every value was slow. keys() returned the keys in the order of a hash map, so reading the values in that order decoded a 1 MiB group again for most of them: 64.5 s for the whole store. Nothing else lists the records, so a dump or a migration had no faster way.
2. Nothing warned against opening a store per use. The application opens one cache object per LLM client, three or more per run on one directory. Stores that write at the same time each append to a segment of their own, and the next run continues at most one of them: three stores per run left 11 segments after 5 runs, where one store per run left 1. Small segments also compress worse: the same 12,000 records took 4.7 MB in one segment and 11.4 MB in segments of 10 records.

Requirements

• required: when applying commitkv to an application reveals a shortcoming, improve commitkv first and apply it afterwards.
• required: stores keep reading the segments that released versions wrote (docs/format.md).
• chosen: keys() returns the keys in the order of their current records in the segments instead of adding an iteration API, because the existing API then reads a whole store fast and the order was unspecified before.
• chosen: several stores on one directory stay independent and the README tells callers to share one, because the store's contract (another store's records stay invisible until refresh) and the tests that stand in for separate checkouts depend on that independence.

Customer Summary

• keys() lists the keys in the order their current values lie in the segments, oldest segment first, in Rust, Python, Node.js, and Bun. This is the order one store wrote them; the order across several stores does not tell which write came first. Reading every value in that order took 0.5 s on the store above instead of 64.5 s.
• The README says to open one store per directory in a process and why.

Technical Summary

Store::keys sorts the index by the position that already decides which record of a key is current (segment name, then end offset); State::position now holds that ordering for both uses. The segment format and the files a store writes are unchanged.

Testing

• cargo test --release --manifest-path rust/Cargo.toml (adds keys_are_listed_in_the_order_a_store_wrote_their_current_values, which covers several segments and a replaced key), cargo clippy, cargo fmt --check
• bun run verify, bun wb test
• Measured with the Python binding on the converted cache: all values in keys() order 64.5 s → 0.48 s; 2,000 values in random order unchanged at about 0.65 s.