KS78: Fix persistence format bug + CODEX.md

[Liorrr]

Summary

• Root cause of Issue Persistence format version mismatch: expected 1, got 25165826 #16: MCP binary at ~/.local/bin/shrimpk-mcp.exe was compiled from KS9 (Mar 20, FORMAT_VERSION=1 only). Data file is v2 (written by v0.7.0 daemon). Old binary reads bytes[4..8] as u32 LE → 25165826 (0x01800002) instead of single byte[4]=2.
• Improved error message to include supported versions (1, 2) and binary update hint
• Added CODEX.md for OpenAI Codex code reviewer + 2nd QA role
• Updated BACKLOG.md sprint roadmap to reflect shipped KS74-KS77b

Commits

1. KS78: Improve persistence version error diagnostic — Better error message + test coverage
2. KS78: Add CODEX.md + update BACKLOG.md sprint roadmap — Project infrastructure

Test plan

• cargo test -p shrimpk-memory — 391 passed, 0 failed, 21 ignored
• cargo clippy -p shrimpk-memory -- -D warnings — 0 warnings
• cargo check --workspace — clean
• Rebuild MCP binary and verify mcp__shrimpk__stats works (binary rebuild in progress)

Closes #16

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR tightens the persistence-layer diagnostic for Issue #16: when load_binary encounters an unknown format version byte (e.g. the old MCP binary reading a v2 data file and emitting the opaque version number 25165826), the error now names the offending version, lists the supported versions (1, 2), and tells the user to rebuild their binary. The test for header_validation_wrong_version is expanded to assert all three pieces of the new message rather than just a prefix match.

• persistence.rs — Error string updated at line 493–494; test at lines 1198–1210 now asserts three sub-strings (\"Unsupported format version: 99\", \"supported: 1, 2\", \"update your binary\") — logic and test are correct
• CODEX.md — New instruction file for the OpenAI Codex / AI secondary-QA role; documentation only
• BACKLOG.md — Marks KS74–KS77b as shipped, updates KS78–KS80 scope; documentation only
• One non-blocking style note: the supported-version list \"supported: 1, 2\" in the error message is a manual string that will need to be kept in sync when a future v3 arm is added — consider deriving it from FORMAT_VERSION and a named FORMAT_VERSION_LEGACY constant

Confidence Score: 5/5

Safe to merge — minimal, focused diagnostic improvement with no logic changes or new panic paths

The only Rust change is an error-message string and three additional test assertions. Version detection logic is untouched. No unsafe code, no new unwrap/expect calls, no async changes, and tests pass (391 pass, 0 fail per PR description). The single P2 note about the hardcoded version list is a future-proofing style suggestion, not a correctness issue.

No files require special attention

Important Files Changed

Filename	Overview
crates/shrimpk-memory/src/persistence.rs	Error message improved for unsupported format versions; test expanded to verify exact message content including version list and update hint — logic and test are correct
CODEX.md	New AI reviewer instruction file — documentation only, no code impact
BACKLOG.md	Sprint roadmap updated to mark KS74–KS77b as complete and KS78–KS80 revised — documentation only

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[load_binary called] --> B{file exists?}
    B -- no --> C[return empty EchoStore]
    B -- yes --> D[read bytes]
    D --> E{data.len >= 5?}
    E -- no --> F[Err: File too small]
    E -- yes --> G{magic bytes valid?}
    G -- no --> H[Err: Invalid magic bytes]
    G -- yes --> I[version_byte = data[4]]
    I --> J{version_byte == 1\nAND data[5..8] == 0,0,0?}
    J -- yes --> K[load_binary_v1]
    J -- no --> L{version_byte == 2?}
    L -- yes --> M[load_binary_v2]
    L -- no --> N["Err: Unsupported format version: X\n(supported: 1, 2).\nUpdate your binary. ← IMPROVED in this PR"]
    K --> O[Ok EchoStore]
    M --> O

Loading

_{Reviews (1): Last reviewed commit: "KS78: Add CODEX.md + update BACKLOG.md s..." | Re-trigger Greptile}