Skip to content

feat: persist native Arctic and Congee indexes - #39

Merged
pathscale merged 5 commits into
masterfrom
feat/art-native-persistence
Aug 3, 2026
Merged

feat: persist native Arctic and Congee indexes#39
pathscale merged 5 commits into
masterfrom
feat/art-native-persistence

Conversation

@pathscale

@pathscale pathscale commented Aug 3, 2026

Copy link
Copy Markdown
Owner

Summary

  • allow explicit persist: true with using arctic or using congee for primary and unique secondary indexes
  • persist a pointer-free, backend-native ART topology checkpoint plus a checksummed logical Set/Remove WAL
  • preserve Arctic node kinds/physical slots and Congee node kinds/prefixes/physical slots/Node48 free-list order
  • recover, mutate after recovery, and compact without retaining WorkTablesIndex or a second authoritative ART during normal operation
  • prepare WorkTable and worktable_codegen 1.0.0-beta.2

Fork boundary

WorkTable consumes the published arctic-wt 0.1.4 and congee-wt 0.4.1 crates. The forks expose typed topology import/export only; WorkTable owns byte framing, checksums, WAL semantics, table versions, recovery, and compaction.

Concurrency and hot paths

  • memory-only Congee and Arctic keep their native types and native point-operation paths
  • persisted point reads delegate directly to the native ART without a new lock or backend-selection branch
  • persisted mutations use 64 key-hashed stripes so same-key native mutations and logical events have the same order while different keys remain concurrent
  • failed checked inserts consume no event ID; rollback/acknowledgement remains compatible with the existing gapless analyzer
  • compaction reconstructs one temporary ART in the background persistence task and atomically replaces the native checkpoint

Format and recovery

  • fixed header: magic, format version, backend, key width, table version, snapshot length, checksum
  • native pointer-free topology snapshot
  • framed logical WAL with event ID, Set/Remove, key, link, and checksum
  • complete corruption is an error; an incomplete final frame is a torn tail and is truncated before later appends
  • ART and B-tree physical formats are intentionally different, so switching between them requires migration/rebuild

See docs/art-index-persistence-plan.md and docs/index-backend-dsl-proposal.md.

Validation

  • full cargo test --workspace --all-targets: pass
    • 135 library tests
    • 336 integration tests passed, 3 pre-existing ignored
    • 64 codegen tests
  • cargo fmt --all -- --check: pass
  • cargo clippy --workspace --all-targets -- -D warnings: pass
  • generated Arctic-primary/Congee-secondary and Congee-primary/Arctic-secondary reload/mutate/reload coverage
  • concurrent same-row update/reload test: 8 workers, 800 updates, no stale secondary keys
  • duplicate rollback, torn-tail/new-append, checksum/header mismatch, exact topology round trip, and compaction coverage

Preliminary local performance evidence

Two interleaved ten-trial ARM microprobe runs; these are engineering checks, not paper results:

  • fork-backed memory-only Congee vs crates.io baseline: point reads about 25% faster; insert/remove about 13.5% faster
  • fork-backed memory-only Arctic: insert/remove about 1% faster; point reads about 1.5% slower than the crates.io baseline
  • persisted wrapper point reads vs native: statistically indistinguishable in paired trials
  • persisted mutation frontend: Congee approximately +22 to +23 ns; Arctic approximately +21 to +22 ns
  • WTI control: structural CDC approximately +35 ns over direct WTI mutation

The Arctic 1.5% read shift is disclosed as a small measurable regression and should be repeated on the target deployment hardware before promotion. The persistence cost is feature-gated by explicit persist: true plus using arctic|congee; memory-only ART tables do not pay it.

Reproducible local probes are included under examples/*_probe.rs.

Deliberate beta boundaries

  • persisted ART remains experimental pending target-hardware and end-to-end WorkTable benchmarks
  • S3 upload/download and interrupted-sync validation remains required
  • WAL append durability currently follows WorkTable's existing flush contract; checkpoint replacement calls sync_data
  • a stable 1.0 disk migration policy is still required
  • ART range scans retain their current allocation/isolation limitations

The immediate WTI follow-up is documented in docs/wti-dirty-generation-persistence-plan.md: logical redo plus dirty-generation background checkpoints to reduce caller-side structural-CDC cost without affecting reads.

@pathscale
pathscale merged commit 97b7b08 into master Aug 3, 2026
3 of 5 checks passed
@pathscale
pathscale deleted the feat/art-native-persistence branch August 3, 2026 21:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant