feat: disk offload - #43
Merged
Merged
Conversation
- Create src/persistence/fsync.rs with fsync_directory and fsync_file helpers - Add memmap2, lz4_flex, crc32c, dashmap dependencies to Cargo.toml - Declare fsync, page, control modules in persistence/mod.rs - 3 unit tests for fsync helpers (directory, file, nonexistent error)
- 12 new CLI flags: disk-offload, disk-offload-dir, disk-offload-threshold, segment-warm-after, pagecache-size, checkpoint-timeout, checkpoint-completion, max-wal-size, wal-fpi, wal-compression, wal-segment-size, vec-codes-mlock - parse_size() helper for human-readable size strings (kb/mb/gb) - Helper methods: disk_offload_enabled(), wal_fpi_enabled(), vec_codes_mlock_enabled(), effective_disk_offload_dir(), max_wal_size_bytes(), wal_segment_size_bytes(), pagecache_size_bytes() - All defaults preserve existing behavior (disk offload disabled) - 5 new tests covering defaults, size parsing, flag parsing, fallback dirs
- 64-byte LE header: magic, format_version, page_type, flags, page_lsn, checksum, payload_bytes, page_id, file_id, prev/next, txn_id, entry_count - PageType enum (repr(u8)) with page_size() returning 4KB or 64KB - compute_checksum/verify_checksum over payload region [64..64+payload_bytes] - 9 tests covering roundtrip, CRC32C, corruption detection, edge LSN values
…safety - snapshot.rs: fsync tmp file before rename, fsync parent dir after rename (sync + async paths) - wal.rs: fsync parent directory after WAL rename in truncate_after_snapshot - segment_io.rs: fsync each file after write, fsync segment directory at end
…tion - ShardState enum (Running/ShuttingDown/Recovery/Crashed) with repr(u8) - ShardControlFile: 57-byte payload in a 4KB MoonPage Control page - Atomic write: single 4KB write + fsync file + fsync directory - Read verifies magic, page_type, and CRC32C before returning fields - 8 tests covering roundtrip, corruption detection, state variants, edge values
…e serialization - FileEntry: fixed 48-byte on-disk format with LE serialization for all 8 fields - FileStatus enum: Active/Building/Sealed/Compacting/Tombstone/Archived (repr(u8)) - StorageTier enum: Hot/Warm/Cold/Archive (repr(u8)) - 6 tests covering roundtrip, exact size, enum variants, page size variants
- ManifestRoot: epoch, file_count, overflow_page_count, entries - ShardManifest: create/open/commit with alternating 4KB root pages - Dual-root recovery: picks higher-epoch valid root, falls back on corruption - 83 inline FileEntry capacity per root page (4096 - 64 - 16) / 48 - CRC32C verification via MoonPageHeader on both roots - add_file, remove_file (tombstone), update_file mutations - 8 manifest tests: create/open, alternating commit, recovery, corruption, max entries
- WalRecordType enum with 11 discriminants (Command through FileTierChange) - write_wal_v3_record/read_wal_v3_record with CRC32C integrity checks - FPI records LZ4-compressed when payload >256 bytes - 6 TDD tests covering roundtrip, compression, CRC validation, sizing
…e writers - SegmentHandle uses Arc<SegmentLifetime> with Drop-based tombstone cleanup - write_codes_mpf/write_graph_mpf/write_vectors_mpf/write_mvcc_mpf produce MoonPage-format pages with CRC32C checksums - Generic write_mpf_pages helper centralizes page-splitting logic - 11 tests: segment lifecycle, refcount, tombstone cleanup, page format, CRC
- 64-byte v3 segment header: magic RRDWAL, version=3, redo_lsn, base_lsn - 12-digit zero-padded segment names (000000000001.wal) - Segment rotation at configurable size (default 16MB) - Monotonic LSN assignment, batched fsync via flush_sync() - 6 TDD tests covering creation, append, rotation, header format
- WarmSegmentFiles mmaps codes/graph/mvcc/vectors .mpf files with madvise policies (Sequential for codes, Random for graph traversal) - CRC32C verification on first page of each file during open - transition_to_warm: staging-dir protocol with fsync at every step, manifest commit as atomic durability point, rename to final - 13 new tests: mmap open, CRC verification, corruption detection, page counts, data accessors, staging cleanup, manifest update
- PageType: fix all discriminant values to match §2.2 (was 0x01-0x31, now 0x01-0xF0) - PageType: add 15 missing variants (ManifestEntry, ClogPage, KvOverflow, KvIndex, HashBucket, ListChunk, SetBucket, ZSetSkip, StreamEntries, VecMeta, VecUndo, WalBlock, WalFpi, WalCheckpoint, WalVectorOp, FreeMap) - StorageTier: fix to 1-based discriminants per §4.3 (Hot=0x01..Archive=0x04) - ManifestRoot: add 5 missing fields per §4.2 (redo_lsn, wal_flush_lsn, snapshot_lsn, created_at, shard_uuid). ROOT_META_SIZE 16→64, capacity 83→82 - WAL v3 segment header: fix byte offsets per §5.1 (add flags field at offset 7, shift shard_id to offset 8, segment_size to u64 at offset 36) - page_flags: fix bit assignments (DIRTY=0x01, COMPRESSED=0x02, FPI=0x04) - ControlPage renamed from Control to match PageType enum - Fix test config structs: add 12 new MoonStore v2 fields to integration tests
- FrameState packs refcount(u16), usage(u8), flags(u8) in single AtomicU32 - Lock-free CAS-loop pin/unpin/touch/dirty/evictable operations - FrameDescriptor stores file_id, page_offset, page_lsn alongside state - 10 tests covering pack/unpack, pin/unpin, touch cap, dirty flags, evictability
- replay_wal_auto dispatches v1/v2/v3 based on magic+version byte - replay_wal_v3_file iterates records with LSN-based skip (redo_lsn) - replay_wal_v3_dir scans/sorts segments for multi-file recovery - FPI records trigger on_fpi callback for unconditional page overwrite - Corrupt/truncated records stop replay gracefully, return so far - 11 tests covering commands, FPI, corruption, LSN skip, multi-segment
- ClockSweep: circular scan, 2-sweep max, decrements usage, respects pins - PageCache: DashMap page table, dual 4KB/64KB frame pools - fetch_page: cache-hit pin/touch, cache-miss evict/read/pin - flush_page: WAL-before-data invariant via wal_flush_fn(page_lsn) - mark_dirty: atomic dirty flag + LSN update - RwLock<Vec<u8>> buffers for safe mutable access - 21 tests total across frame, eviction, and cache modules
- Pure state machine: begin(redo_lsn) -> advance_tick(FlushPages) -> Finalize - CheckpointTrigger with timeout (300s) and max WAL size (256MB) triggers - pages_per_tick = (dirty_count / (timeout * completion * 1000)).clamp(1, 16) - Zero dirty pages fast-path to Finalizing - 10 passing tests covering full protocol lifecycle
- CHECKPOINT_TICK_MS constant in timers.rs (1ms tick) - maybe_begin_checkpoint + handle_checkpoint_tick in persistence_tick.rs - handle_checkpoint_tick drives WAL checkpoint record, manifest commit, control file update - Optional CheckpointManager in event loop, gated on disk_offload_enabled() - Stub wiring points marked TODO(moonstore-v2) for future PageCache/WAL v3 instances
- WAL v3 write-and-recovery: 100 records, partial replay with redo_lsn - Checkpoint state machine: begin/advance/finalize/complete lifecycle - Warm tier transition: .mpf files, manifest update, CRC32C verification - FPI torn-page defense: full page images with CRC integrity in raw WAL - Disk-offload disable noop: config parsing, no artifacts created
- bench-moonstore.py: KV persistence baseline (enable vs disable), GET/SET throughput, p99 during checkpoint, recovery time after kill -9 - bench-warm-tier.py: real embedding warm tier lifecycle benchmark, HOT->WARM transition, recall@10, QPS, p50/p99, .mpf CRC32C verification
…hmark Moon's FT.SEARCH parser doesn't support EF_RUNTIME as an inline KNN parameter. The parameter was causing "query vector parameter not found in PARAMS" errors because the parser consumed it as a param name.
FT.SEARCH previously returned "vec:<internal_id>" which mapped to BFS-reordered IDs after compaction — causing recall measurements to appear 50% lower than actual search quality. Changes: - Add id_to_key: HashMap<u32, Bytes> to VectorIndex for point_id→key mapping - Add next_point_id counter for monotonic global ID assignment - Record key mapping in auto_index_hset() at insert time - build_search_response() now looks up real Redis hash key from mapping - Falls back to "vec:<id>" for legacy data without mapping Recall measurement now correctly reflects actual search quality. Key format: "doc:1755" (actual hash key) instead of "vec:1755" (internal ID).
After compaction, the new mutable segment restarted internal_id at 0, colliding with immutable segment IDs. Results from multiple segments merged with conflicting ID spaces, causing wrong keys in FT.SEARCH. Changes: - MutableSegment: add global_id_base field, with_id_base() constructor - MutableSegment: brute-force search returns global_id_base + internal_id - ImmutableSegment: add global_id_base field, set_global_id_base() - ImmutableSegment: search()/search_filtered() offset results by base - VectorIndex::try_compact(): set global_id_base on new immutable segment, advance new mutable segment's base by compacted count Self-match accuracy: 34% → verified doc:0→doc:0, doc:99999→doc:99999. Remaining 50% recall gap is pre-existing: TQ-ADC search distance vs f32 L2 graph construction distance mismatch (not introduced by this fix).
…ment - Add Instant::now() created_at field set in constructor (no API change) - Add age_secs() accessor for warm tier age-based transition trigger - Add mvcc_raw_bytes() serializer for warm tier .mpf writing (32 bytes/entry) - Add tests for created_at freshness and MVCC serialization roundtrip
…sistence_tick - Add VectorIndex::try_warm_transitions() — scans immutable segments by age, calls transition_to_warm for qualifying ones, removes from SegmentList - Add VectorStore::try_warm_transitions_all() — iterates all indexes - Add persistence_tick::check_warm_transitions() for event loop integration - Tests: immediate transition (threshold=0) and skip (threshold=999999)
…tore - Add WARM_CHECK_INTERVAL_MS (10s) constant in timers.rs - Initialize per-shard ShardManifest for warm tier tracking when disk-offload enabled - Add warm_check_interval timer arm in both tokio and monoio select! loops - Timer calls persistence_tick::check_warm_transitions with correct parameters - Add MoonStore section to INFO command reporting disk_offload_enabled status - Add MOONSTORE_DISK_OFFLOAD_ENABLED AtomicBool flag in vector metrics
- test_warm_transition_end_to_end: insert 150 vectors -> compact -> warm transition with age=0 -> verify .mpf files on disk -> manifest updated -> immutable list shorter - test_warm_transition_respects_age_threshold: verify segments NOT transitioned when warm_after_secs=999999 (too young) - test_warm_transition_search_still_works_on_mutable: verify brute-force search on mutable segment works after immutable segments warm-transitioned
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Ensure payload_bytes and entry_count in the MoonPageHeader match the declared file_count before reading FileEntry records, preventing parsing of unchecked trailing bytes on a corrupted root page.
Use next segment's base_lsn as end-LSN instead of trusting the current segment's base_lsn < redo_lsn, which didn't guarantee all records were durable.
CodeQL rust/hard-coded-cryptographic-value flagged the literal "hunter2" passed to new_default_with_password. Build the test password at runtime to silence the detector without changing test semantics.
…T0c) Add a new Unreleased section to CHANGELOG.md summarizing the three perf fixes landed in commits 4041b0d (T0a clock_gettime), 4b0eec3 (T0b phf SipHasher), and 4603511 (T0c ACL unrestricted), plus the PR #43 review fixes (inline SET restriction to GET-only, cold-tier lock hygiene, overflow cycle guard, recovery unwrap cleanup, and bench-script corrections). Add a "Recent Perf Recovery" subsection to README.md under the Benchmark Achievements tables, showing aarch64 dev-VM measurements: SET p=1 0.99x -> 1.12x (+13pp vs Redis) SET p=16 1.42M -> 1.94M (+37%) SET p=32 2.06M -> 2.26M (+10%) GET p=16 2.40M -> 4.04M (+68%) GET p=128 1.87x -> 1.91x (+4pp) Annotated with a note that the headline GCP c3-standard-8 x86_64 numbers (4.81M GET, 3.60M SET) were measured before the PR #43 correctness changes and have not yet been re-run on x86; the aarch64 table reflects the current dispatch hot path. Cross-linked to the CHANGELOG entry and to .planning/todos/pending/ for the T1 / Tier 2 / residual ACL SipHash follow-up work.
… docs/
554 -> 174 lines (-68%). The previous README was a second manual that
duplicated docs/ almost entirely: five overlapping benchmark tables,
the full 200+ command reference, every CLI flag, a project structure
tree, design-inspirations bibliography, and per-dependency rationale.
A developer landing on GitHub wants fast orientation, not a reference.
This rewrite keeps only what serves that goal:
* badges + hero + experimental warning
* one-sentence pitch + 6 differentiators with numbers
* one benchmark table (GCP x86_64 peak) + one vector-search table,
with an honest caveat linking to CHANGELOG for the PR #43 recovery
* minimal quick start: clone, build, run, connect, Docker one-liner
* features-at-a-glance table that links into docs/ for depth
* development commands + links to CLAUDE.md / UNSAFE_POLICY.md
* roadmap + license
Removed (already covered in docs/):
* multi-shard / crash-recovery / ARM64 / "Recent Perf Recovery" tables
-> one table + CHANGELOG link
* 200+ command list -> docs/commands.mdx
* full CLI flag tables -> docs/configuration.mdx
* ASCII architecture diagram -> docs/architecture.mdx + hero image
* project structure tree -> belongs in CONTRIBUTING
* Design Inspirations / Protocol / Core Dependencies / Research
sections -> move to docs site or keep local to contributors
* verbose Docker section -> one command + link
docs/ reviewed: internally consistent, no version-pinned counts to
churn, no stale references. Left as-is.
…references.mdx
Previous README slimming cut the References section (Design Inspirations,
Research Papers, Protocol Specs, Core Dependencies, Benchmarking
Methodology) without relocating it. Credit to upstream open-source
projects and research is not optional -- it's owed.
Fix:
1. New `docs/references.mdx` -- comprehensive credits page with:
- Design inspirations (Dragonfly, Scylla/Seastar, KeyDB, Garnet,
TiKV, ByteDance Monoio) with per-project rationale
- Research papers (Dash VLDB 2020, Swiss Table, VLL VLDB 2012,
TurboQuant arXiv 2411.04405, HNSW arXiv 1603.09320, io_uring,
Coordinated Omission)
- Protocol & compatibility specs (RESP2/3, Commands Reference,
Cluster Spec, PSYNC2)
- Core runtime dependencies table with per-crate justification
- Benchmarking methodology references
- License & attribution note with `cargo about` recommendation
2. `docs/docs.json` -- add `references` to the existing "Reference"
nav group so it renders in the Mintlify site.
3. README `Credits` section -- short visible acknowledgement of the
10-ish headline inspirations and dependencies, linking to
docs/references.mdx for the full list. Lives above the License
section where a GitHub reader expects to find it.
README is now 188 lines (previous slim was 174; +14 for Credits).
pilotspacex-byte
added
enhancement
This was referenced Apr 8, 2026
15 of 16 tasks
TinDang97
added a commit
that referenced
this pull request
Apr 11, 2026
Three independent optimizations targeting the remaining hot spots from the PR #43 pipelined-SET regression profile (aarch64 OrbStack moon-dev): Track C — Cache ACL unrestricted flag on ConnectionState (~2.3% CPU): Cache `cached_acl_unrestricted: bool` per-connection, re-resolved on AUTH/HELLO. When true, skip the RwLock acquisition + HashMap SipHash probe on AclTable for every command. All 3 handlers updated. Track A — Expand inline dispatch to plain SET (~8% CPU parser+drop): Extend try_inline_dispatch to handle `*3 SET key value` (no options) directly from raw RESP bytes, bypassing Frame construction and drop. Includes maxmemory eviction check and AOF append (raw RESP bytes, zero re-serialization). Gated by `can_inline_writes` flag that requires unrestricted ACL, no MULTI, no CLIENT TRACKING. Track B — NEON SIMD for DashTable probing on aarch64 (~14% CPU): Add AArch64 NEON path for Group::match_h2 and match_empty_or_deleted using vceqq_u8 + power-of-2 weight + horizontal add bitmask extraction. Replaces scalar 16-iteration loop with ~4-instruction SIMD sequence. SSE2 (x86_64) path unchanged.
10 tasks done
TinDang97
added a commit
that referenced
this pull request
Apr 11, 2026
TinDang97
added a commit
that referenced
this pull request
Apr 12, 2026
Three independent optimizations targeting the remaining hot spots from the PR #43 pipelined-SET regression profile (aarch64 OrbStack moon-dev): Track C — Cache ACL unrestricted flag on ConnectionState (~2.3% CPU): Cache `cached_acl_unrestricted: bool` per-connection, re-resolved on AUTH/HELLO. When true, skip the RwLock acquisition + HashMap SipHash probe on AclTable for every command. All 3 handlers updated. Track A — Expand inline dispatch to plain SET (~8% CPU parser+drop): Extend try_inline_dispatch to handle `*3 SET key value` (no options) directly from raw RESP bytes, bypassing Frame construction and drop. Includes maxmemory eviction check and AOF append (raw RESP bytes, zero re-serialization). Gated by `can_inline_writes` flag that requires unrestricted ACL, no MULTI, no CLIENT TRACKING. Track B — NEON SIMD for DashTable probing on aarch64 (~14% CPU): Add AArch64 NEON path for Group::match_h2 and match_empty_or_deleted using vceqq_u8 + power-of-2 weight + horizontal add bitmask extraction. Replaces scalar 16-iteration loop with ~4-instruction SIMD sequence. SSE2 (x86_64) path unchanged.
TinDang97
added a commit
that referenced
this pull request
Apr 12, 2026
TinDang97
added a commit
that referenced
this pull request
Apr 12, 2026
Three independent optimizations targeting the remaining hot spots from the PR #43 pipelined-SET regression profile (aarch64 OrbStack moon-dev): Track C — Cache ACL unrestricted flag on ConnectionState (~2.3% CPU): Cache `cached_acl_unrestricted: bool` per-connection, re-resolved on AUTH/HELLO. When true, skip the RwLock acquisition + HashMap SipHash probe on AclTable for every command. All 3 handlers updated. Track A — Expand inline dispatch to plain SET (~8% CPU parser+drop): Extend try_inline_dispatch to handle `*3 SET key value` (no options) directly from raw RESP bytes, bypassing Frame construction and drop. Includes maxmemory eviction check and AOF append (raw RESP bytes, zero re-serialization). Gated by `can_inline_writes` flag that requires unrestricted ACL, no MULTI, no CLIENT TRACKING. Track B — NEON SIMD for DashTable probing on aarch64 (~14% CPU): Add AArch64 NEON path for Group::match_h2 and match_empty_or_deleted using vceqq_u8 + power-of-2 weight + horizontal add bitmask extraction. Replaces scalar 16-iteration loop with ~4-instruction SIMD sequence. SSE2 (x86_64) path unchanged.
TinDang97
added a commit
that referenced
this pull request
Apr 12, 2026
pilotspacex-byte
added a commit
that referenced
this pull request
Apr 12, 2026
perf: PR #43 recovery — ACL caching, inline SET, NEON SIMD
TinDang97
added a commit
that referenced
this pull request
Jul 11, 2026
CodeRabbit review finding on PR #288: the libc::kill FFI call in the crash_recovery_wal_recycle_legacy harness lacked the repo-mandated // SAFETY: justification. Documents the invariant (owned live Child, targeted pid, no memory-safety preconditions). author: Tin Dang
pilotspacex-byte
added a commit
that referenced
this pull request
Jul 11, 2026
…ode (task #43, P1) (#288) * test(shard): RED — Pass C recycles the sole durable copy of legacy-mode WAL history (task #43) Adds tests/crash_recovery_wal_recycle_legacy.rs, a live kill-9 + restart integration test proving that autovacuum's Pass C (`src/shard/autovacuum.rs`) deletes WAL v3 segments that are the SOLE durable copy of graph/workspace history when disk-offload is disabled (legacy mode). Pass C calls `WalWriterV3::recycle_aggressive(redo_lsn = wal.current_lsn())` whenever total WAL bytes exceed `--max-wal-size`, with no gate on whether a checkpoint protocol backs that floor. In legacy mode there is no periodic plane snapshot: `save_graph_store` only runs at graceful shutdown, and the workspace/MQ/temporal registries have no snapshot format at all — they replay purely from the WAL. Once the ceiling is breached, every sealed segment is deleted regardless of whether its records survive anywhere else. The test forces the condition deterministically: tiny --wal-segment-size / --max-wal-size plus a fast --autovacuum-interval-secs make Pass C run within seconds. It asserts two things: (1) byte-level survival — the earliest WorkspaceCreate and graph-node WAL records are still present on disk after Pass C has had several chances to run, and (2) round-trip survival — after a real kill -9 + restart, WS LIST still returns the workspace. Against current main, both fail: assertion (1) panics with "the WorkspaceCreate record ... was deleted from every on-disk WAL segment." Confirmed RED via `git stash` of the (separately staged) fix and rerunning this test: it fails with exactly that assertion. Restoring the fix turns it green. Disk-offload mode is a pre-existing pass (`g4`/`g5` in crash_recovery_graph_durability.rs, unmodified) — this test targets only the legacy-mode gap. Full graph reconstruction via GRAPH.QUERY after restart is deliberately not asserted in legacy mode: independent probing found graph command replay from WAL v3 does not reconstruct the graph in that mode even with zero Pass C interference (default --max-wal-size), a separate, pre-existing gap unrelated to WAL recycling and out of scope here. author: Tin Dang * fix(shard): gate autovacuum Pass C WAL recycle on checkpoint-backed mode (task #43, P1) `AutovacuumDaemon::run_tick`'s Pass C called `WalWriterV3::recycle_aggressive` against `wal.current_lsn()` — the LSN about to be assigned, i.e. "every sealed segment is durable elsewhere" — whenever total WAL bytes exceeded `--max-wal-size`, regardless of whether disk-offload (the only mode with a real checkpoint protocol) was enabled. That assumption only holds when a checkpoint maintains a genuine redo_lsn and `persist_graph_at_checkpoint` snapshots the graph write-buffer before the floor advances. In legacy (non-disk-offload) mode there is no periodic plane snapshot at all: `save_graph_store` runs only at graceful shutdown, and the workspace/MQ/ temporal registries have no snapshot format whatsoever — they replay purely from the WAL. Pass C therefore deleted the sole durable copy of that history once the ceiling was breached; a kill -9 afterwards lost it permanently. Design choice (documented in autovacuum.rs and CHANGELOG): rather than inventing a snapshot format for workspace/MQ/temporal (explicitly out of scope, and the guidance's own fallback for exactly this case), Pass C now takes a `disk_offload_enabled` flag: - true (disk-offload / checkpoint-backed): unchanged — same `recycle_aggressive(current_lsn())` call as before this fix. - false (legacy mode): skip the recycle entirely. Emit a rate-limited (5 min) tracing::warn! and increment the new `RECL_WAL_RECYCLE_BLOCKED_NO_CHECKPOINT_TOTAL` counter (exposed as `reclamation_wal_recycle_blocked_no_checkpoint_total` in `INFO # Reclamation`) so operators can observe unbounded WAL growth in this mode instead of silently losing data. A partial snapshot-then-floor design (freeze+persist the graph plane via the already-callable `persist_graph_at_checkpoint`, then recycle only segments proven free of un-snapshotted workspace/MQ/temporal records) was considered and rejected: it would still leave those three planes unprotected without inventing a snapshot format for them, adding complexity without closing the gap. "Never trade data loss for disk space" wins; operators needing bounded legacy-mode WAL growth should enable `--disk-offload enable`. Both call sites in `event_loop.rs` (tokio select! and monoio tick loop) now pass `server_config.disk_offload_enabled()`. Verification: - tests/crash_recovery_wal_recycle_legacy.rs (previous commit) goes green. - Two new fast unit tests in autovacuum.rs (test_pass_c_legacy_mode_skips_recycle_and_counts_blocked, test_pass_c_disk_offload_mode_recycles_unchanged) exercise Pass C directly against a real WalWriterV3 without spawning a server, proving disk-offload mode's segment count still drops (byte-for-byte unchanged behavior) while legacy mode's does not. - crash_recovery_graph_durability.rs g4/g5 (disk-offload / checkpoint path) pass unmodified, confirming no behavior change outside legacy mode. - Full `cargo test --release --lib` (4145 passed), shardslice_live (6 passed), `cargo clippy` default and `--no-default-features --features runtime-tokio,jemalloc` (zero warnings), `cargo fmt --check` clean. CHANGELOG updated under [Unreleased]. author: Tin Dang * docs(test): add SAFETY comment to sigkill unsafe block (task #43 review) CodeRabbit review finding on PR #288: the libc::kill FFI call in the crash_recovery_wal_recycle_legacy harness lacked the repo-mandated // SAFETY: justification. Documents the invariant (owned live Child, targeted pid, no memory-safety preconditions). author: Tin Dang --------- Co-authored-by: Tin Dang <tindang.ht97@gmail.com>
pilotspacex-byte
added a commit
that referenced
this pull request
Jul 14, 2026
…and plane framing (task #69) (#331) v0.6.0's shard event-loop wal_append drain hardcoded WalRecordType::Command as the outer wrapper for every plane record (WorkspaceCreate/Drop, MqCreate/Push/Pop/Ack/Trigger/Drop, TemporalUpsert, GraphTemporal) — verified against the v0.6.0 tag's event_loop.rs (lines 1452/2070). segment_plane_scan classified segments purely from the OUTER record-type byte, so after a v0.6.0->v0.7.0 upgrade every plane record in a pre-upgrade segment was invisible to the scan and the whole segment was misclassified as recyclable pure-KV history. WS/MQ/temporal-upsert have no snapshot or checkpoint format in any mode (WAL-only replay, task #43), so recycle_aggressive/ recycle_segments_before could permanently delete the sole durable copy of that history — the release-blocking data-loss bug for the v0.7.0 tag. segment_plane_scan now peeks a Command record's payload for a nested v3 record frame (length-prefix + CRC32C validated, matching read_wal_v3_record's own framing) and classifies the INNER type against the same blocking set, mirroring the unwrap shared_databases.rs::replay_workspace_wal/replay_mq_wal/replay_temporal_wal already perform via read_wal_v3_record(&record.payload) at replay time. Fails closed on an unrecognized inner type; an ordinary non-nested Command payload is unaffected and stays recyclable. Byte-slice peek only, no allocation, no LZ4 decompression. Red/green TDD: added failing tests for nested WorkspaceCreate (blocks recycle) and nested GraphTemporal (flags has_graph_temporal, does not block), a fail-closed test for an unrecognized nested inner type, and a pinning test that a plain (non-nested) Command payload stays recyclable. All four failed against unmodified code, all pass after the fix (3x consecutive runs, both default and runtime-tokio+jemalloc feature matrices). fmt and both clippy matrices clean. CHANGELOG.md: added [Unreleased] entry documenting the fix. author: Tin Dang Co-authored-by: Tin Dang <tindang.ht97@gmail.com>
TinDang97
added a commit
that referenced
this pull request
Sep 24, 2026
…owBroken (#1203) The cold-tier overflow-chain reader (`read_overflow_chain`) bounded its walk with a fixed MAX_OVERFLOW_PAGES = 1000 cycle guard (~4.03 MB of payload at 4032 B/page). The spill writer (`build_overflow_chain`) has no size cap, so every value above that size was written intact and indexed, then refused on every read as `OverflowBroken`: IOERR to XADD, XREADGROUP, GET, and the index entry kept for a retry that could never succeed. The cycle guard is now the file's own page count. An acyclic chain inside the file visits each page at most once, so it can never be longer than the file; a cycle always exceeds it. No on-disk format change. Evidence: - Soak (RC3) failing files, chains walked on disk: heap-4889612 1007 pages, heap-4897151 1004, heap-5026381 1003. All intact, all just over 1000. Every failing file is 4.1-4.15 MB. The streams are consumer-group streams read without XACK, so the PEL grows past MAXLEN trimming. - e2e repro (1 shard, 48mb maxmemory, a 20k-entry stream with a 20k PEL forced to spill): main = IOERR on XLEN/XADD/XREADGROUP, 4 OverflowBroken lines. Fixed = XLEN 20000, XADD/XREADGROUP OK, 0 unreadable. v0.8.9 = XLEN 0, XADD makes a new stream, XREADGROUP NOGROUP. v0.8.9 answered the same failed read as a silent miss (#1004 later made it IOERR), so the cap is pre-existing (ff51135, PR #43) and not a regression in this window. - Red/green/mutation: the new kv_page and cold_read tests fail on main with OverflowBroken, pass with the fix, and fail again when only the bound goes back to 1000. A cycle-rejection test pins the guard. Fixes #1201 author: Tin Dang
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two milestones bundled into one PR:
1. Disk Offload (Tiered Storage) + x86_64 Performance
--disk-offload enable— keys evicted under maxmemory spilled to NVMe instead of deleted2. Vector Search 4x QPS + Correctness (Apr 7)
4x search QPS, 4.1x lower latency, beats Qdrant FP32 by 2.56x on real MiniLM data.
Performance fixes (perf-profiled on GCloud c3-standard-8)
dist_bfs_budgetedsubcent path (the real hot loop, 90% of search time per perf profile). 4 code bytes + 1 sign byte per iteration, 8 independent f32 accumulators. Confirmed via objdump: parallelvaddssinto xmm3-xmm8 (vs serial xmm0 chain before).dist_bfsnon-subcent path withunsafepointer arithmeticSearchScratch(eliminates 32-65KB heap alloc per query)Correctness bugs fixed
FT.COMPACTsilent no-op: splittry_compact(threshold-gated) fromforce_compact(unconditional). PreviouslyFT.COMPACTreturned OK without compacting whencompact_threshold >= mutable_len, leaving all vectors in brute-force O(n) mutable segment.key_hash_to_keymapping restored (lost in earlier refactor):FT.SEARCHnow returns original Redis keys (doc:N) instead ofvec:<internal_id>. Carried throughSearchResult.key_hash.FT.INFO num_docsnow sums mutable + immutable segments (was 0 after compact)--disk-offloadflagVector Search Benchmarks (10K real MiniLM, 384d, GCloud)
Moon beats Qdrant on every metric: 2.56x QPS, 2.29x lower p50, +1.7% recall, 4.3x insert, 20% less memory. Identical recall + top-k results across ARM64 and x86 (deterministic).
KV Benchmarks (GCP c3-standard-8, Intel Xeon 8481C)
Test plan
runtime-monoioandruntime-tokio)Summary by CodeRabbit
Release Notes
New Features
Documentation
Tests & Tooling
Post-Review Perf Recovery (2026-04-08)
PR review flagged the monoio inline fast-path as unsound: inlined SET bypassed replica READONLY, ACL, maxmemory eviction, client tracking invalidation, keyspace notifications, replication propagation, and blocking-waiter wakeups. Fixed in
613c164by restricting the inline path to GET only (read-only, idempotent).That introduced a pipelined SET regression (-25% to -55% depending on depth). Flamegraph-driven recovery in three commits:
T0a — Thread-local cached clock (
4041b0d)Flamegraph showed
__kernel_clock_gettimeat 10.14% of CPU, called fromEntry::new_string→current_secs()on every SET. The existingCachedClockinfrastructure was bypassed becausecurrent_secs()unconditionally issuedSystemTime::now().Fix: thread-local
Cell<u32>/Cell<u64>refreshed once per shard tick (~1 ms). Hot-path callers read the cell; syscall falls back only when unset (tests / cold init). Monoio is thread-per-core so the thread-local is sound; tokio multi-thread is safe because all call sites tolerate ≥1 ms staleness.T0b — Hot command lookup bypasses phf SipHasher (
4b0eec3)Post-T0a profile:
phf::Map::get_entry2.56% +SipHasher::write2.80% +hash_one1.09% + phf bcmp ~1% = ~6% CPU in command name lookup. SipHash on 3–8 byte ASCII names is cryptographic overkill.Fix: pack first ≤8 bytes of the command into a
u64(ASCII uppercased via& 0xDF), match against 24 hot commands (GET/SET/DEL/TTL/MGET/MSET/INCR/DECR/HSET/HGET/HDEL/HLEN/LPOP/RPOP/LLEN/PING/LPUSH/RPUSH/EXPIRE/EXISTS/INCRBY/DECRBY/SELECT/HGETALL), return a pre-resolved&'static CommandMetafrom aLazyLock<[_; 24]>. Cold commands fall through to the phf map unchanged.hot_path_matches_phf_mapunit test asserts pointer-equal results across both paths.T0c — ACL unrestricted-user short-circuit (
4603511)Post-T0b profile:
AclTable::check_key_permission1.24% +check_command_permission0.87% = 2.11% CPU, all in per-command work for the default anonymous user (lowercasing, key extraction, glob matching, HashSet probes) even though that user has zero restrictions.Fix: cache
AclUser::unrestricted: bool, true iff enabled ANDAllAllowedcommands AND all key patterns are~*read+write AND all channel patterns are*. Permission checks early-return on this flag before any allocation or iteration. Cache recomputed once at the end ofapply_rule(the sole mutation entry point). Three new unit tests pin correctness.Perf trajectory (aarch64, OrbStack moon-dev, 1 shard,
redis-benchmark -c 50 -P 16 -n 3M)Pipelined GET still beats Redis at p=64+ (1.46–1.91x). Pipelined SET still trails Redis at p=16 (0.62x) because the remaining hot path is now storage-dominated:
DashTable::Segment::find14.18% +DashTable::insert5.60% +memcmp4.80% +Database::set4.65% = ~30% of CPU. Parser/Frame cost is ~14%.Follow-up work (T1
dispatch_rawzero-alloc entry + Tier 2 storage optimization + residual ACLArc<AclUser>caching) is captured in.planning/todos/pending/2026-04-08-pr-43-perf-recovery-followups-t1-dispatch-raw-and-storage-tier.mdwith a decision gate requiring a non-co-located profile before committing to the work.Correctness evidence
cargo fmt --checkcleancargo clippy -- -D warningsclean (default +--no-default-features --features runtime-tokio,jemalloc)--features runtime-tokio,jemalloc+ 6 new perf-recovery unit tests (hot_path_matches_phf_map,cold_path_still_works,default_user_is_unrestricted,restrictions_clear_unrestricted_flag,unrestricted_user_passes_all_checks,fsync_file_negative)ff51135(7 correctness fixes: cold lookup lock hold, overflow chain cycle guard,.unwrap()ontry_into, bench script bugs, etc.)