fix(sqlite-native): keep truncate cache coherent

[NathanFlurry]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[NathanFlurry]

• chore(engine): publish engine bases in ci #4649 : 3 dependent PRs (#4650 , #4652 , #4666 )
• chore: lockfile lefthook #4647
• fix(rivetkit): surface native sqlite kv errors to callers #4645
• fix(rivetkit): prevent sleep races during disconnect and db work #4644
• fix(rivetkit): isolate engine envoys and propagate startup failures #4643
• test(rivetkit): remove wasm sqlite-only fixtures and coverage #4642
• chore(sqlite-vfs): remove wasm sqlite packages and workspace wiring #4641
• chore(rivetkit): remove wasm sqlite runtime #4614
• fix(sqlite-native): restore native startup kv preload #4639
• fix(sqlite-native): delete metadata before chunk range #4638
• fix(sqlite-native): keep truncate cache coherent #4637 👈 (View in Graphite)
• fix(sqlite-vfs): use delete range for truncate cleanup #4636
• fix(sqlite-native): restore kv error hook #4635
• perf(sqlite-native): avoid cloning cached read chunks #4634
• perf(sqlite-native): gate kv operation labels #4633
• perf(sqlite-native): reuse read cache for partial writes #4632
• perf(sqlite-native): remove delete file existence probe #4631
• fix(sqlite-native): gate native read cache behind env var #4630
• fix(pegboard): isolate runner config dc lookup failures #4625 : 1 other dependent PR (#4626 )
• docs(pegboard): note runner config upsert split write risk #4624
• fix(pegboard): unpack global runner config keys correctly #4623
• fix(pegboard-gateway): enforce tunnel message state #4622
• fix(pegboard-runner): clear terminal tunnel routes #4621
• fix(pegboard): skip protocol version keys in runner pool backfill #4620
• fix(pegboard): create missing normal runner configs #4619
• fix(epoxy): reuse cached optimistic value #4618
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR Review: fix(sqlite-native): keep truncate cache coherent

PR #4637 | rivetkit-typescript/packages/sqlite-native/src/vfs.rs | +17 / -18

---

Summary

This PR fixes two cache coherence bugs in kv_io_truncate in the native SQLite VFS:

1. Off-by-one in read_cache.retain boundary. The old truncate_from_chunk formula (size / CHUNK_SIZE) + 1 was one chunk too high for exact chunk-aligned sizes. For example, size = 4096 (exactly one 4096-byte chunk) gave 1 + 1 = 2, retaining chunks 0 and 1, but chunk 1 is entirely past the new file boundary. The new formula (size - 1) / CHUNK_SIZE correctly yields 0, keeping only chunk 0. This aligns with the WASM counterpart (Math.floor((size - 1) / CHUNK_SIZE)) and the existing KV deletion logic in the same function.

2. Missing cache update after last-chunk truncation. After writing the truncated last chunk to KV, the old code did not update read_cache. A subsequent xRead on the same connection would serve the stale full-length chunk from cache, silently returning garbage bytes beyond the truncation point. The fix inserts the truncated slice back into the cache immediately after the successful kv_put, symmetric with how kv_io_write populates the cache.

---

Code Quality and Correctness

Fix 1 is correct and complete. The reordering of last_chunk_to_keep / last_existing_chunk declarations above the read_cache.retain block is necessary since the closure now captures last_chunk_to_keep by reference. Edge cases:

• size == 0: last_chunk_to_keep = -1, so retain removes all chunks. Correct.
• size % CHUNK_SIZE == 0 (chunk-aligned): the last-chunk truncation block is guarded by size > 0 && size as usize % kv::CHUNK_SIZE != 0, so it is correctly skipped. The retain pass evicts the boundary chunk. Correct.
• size > file.size (extension): returns SQLITE_OK early without touching the cache. Correct.

Fix 2 is correct. The read_cache.insert call is placed after the kv_put success check, so the cache is never updated if the KV write fails. The old full-length chunk remains in cache, matching KV state (put failed, KV still has the original chunk).

WASM parity is maintained for the retain boundary. The WASM VFS has no in-process read cache (it is async and relies on the host KV layer), so Fix 2 has no TypeScript counterpart to update. This asymmetry is architectural, not a bug.

---

Style and Convention Compliance

• Hard tabs used correctly throughout.
• No eprintln!/println! logging introduced.
• read_cache: Option<HashMap<...>> is per-file and single-connection-scoped with no mutex; the CLAUDE.md prohibition against Mutex<HashMap> does not apply here.
• Commit title follows conventional commits format.
• Comments are complete sentences with no em dashes.

---

Test Coverage

No regression tests were added. Given the subtlety of both bugs (Fix 1 only triggers for exact-multiple sizes; Fix 2 only manifests when the same connection reads after a non-aligned truncation), a targeted regression test would be valuable. Suggested scenario:

1. Write data spanning multiple chunks with a partially-filled last chunk.
2. Truncate to a non-chunk-aligned size smaller than the written data using the same connection.
3. Read back bytes from the truncated last chunk and verify no stale bytes past the truncation point are returned.

The existing VFS test suite would be the appropriate place for this coverage.

---

Verdict

Both fixes are logically correct and well-targeted. The formula change aligns with the existing KV deletion logic in the same function and the WASM VFS counterpart. The cache update after last-chunk truncation closes a real stale-read window. Adding a regression test for the non-chunk-aligned truncate + cached-read path is recommended but not a blocker.