adityamukho · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026
@@ -12,13 +12,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Bound-entity point queries no longer pay for other attributes' history (#323).** `[:e :attr ?v]` now range-scans only `(e, :attr)` in the EAVT index instead of every record the entity has ever written. Reading a rarely changed attribute of a heavily rewritten entity no longer slows down as that entity's history grows: with 2,000 retract/reassert cycles on another attribute of the same entity, it drops from 4.58 ms to 19.0 µs. Reading the heavily rewritten attribute itself, and attribute scans (`[?e :attr ?v]`), are about 1.35–1.4× faster (4.64 ms → 3.36 ms), from cheaper net-assert grouping and removing a redundant dedup pass. The file format is unchanged.
 - **Attribute scans are bounded to exactly the queried attribute (#381).** `[?e :attr ?v]` computed the end of its AEVT range by incrementing the attribute's last byte. For attributes whose last byte is `0x7F` or `0xBF` — including about 1 in 64 non-ASCII characters, such as `:丿` or `:ÿ` — the result was not valid UTF-8, so the scan ran to the end of the whole AEVT index and read every later fact before filtering. It also read facts for prefix siblings (`:ab`, `:a/b` when scanning `:a`). The range now ends at `attribute + "\0"`, which covers exactly one attribute. Scanning 100 `:丿` facts in a checkpointed file with 40,000 facts on neighbouring attributes drops from 45.4 ms to 251 µs. Results are unchanged.
 
+- **Checkpoints no longer re-encode the whole index (#315).** `checkpoint()` decoded and re-serialised every entry of all four covering indexes and re-read every page of the file for its checksum, so checkpointing after one new fact cost almost as much as after thousands. Index leaves that receive no new entries are now copied verbatim, only the leaves that do are decoded and re-split, and unchanged fact pages are no longer re-hashed. Leaves are still bounds-checked and the leaf chain is checked for cycles, so a damaged index fails the checkpoint instead of being copied forward. Checkpoint after one new fact drops from 246 ms to 26.3 ms on a 100k-fact file and from 23.9 ms to 4.0 ms at 10k. Cost still grows with graph size, because the index pages are copied on every checkpoint; the file format is unchanged. The `checkpoint()` and `wal_checkpoint_threshold` docs now state that a checkpoint is not a durability boundary: the WAL is already crash-durable.
+
 ### Fixed
 
 - **Bound-entity queries could drop rows when one `WriteTransaction` wrote the same attribute in several valid-time windows (#323).** Both facts share a `tx_count`, and the selective lookup path de-duplicated on `(entity, attribute, tx_count, asserted)`, so one window's value was silently lost, while the same query via a full scan returned both. That de-duplication has been removed, and bound-entity queries now always match a full scan.
 
 ### Notes
 
 - On v2.x, reading a heavily rewritten attribute still costs time proportional to its history, because v7 index keys carry neither the value nor the assert/retract flag; the structural fix needs the v8 keys and is tracked for v3.0.0 in #379.
+- Checkpoints on v2.x still copy every index page, so their cost grows with graph size. Copy-on-write index pages on the v3 branch, which also make `save()` crash-atomic, are needed for checkpoints proportional to the change alone (#374).
 
 ## v2.0.1 — 2026-09-25
 

@@ -108,7 +108,7 @@ cargo run < demos/demo_negation.txt
    - `backend/file.rs`: Single `.graph` file backend (4KB pages, cross-platform)
    - `backend/memory.rs`: In-memory backend for testing
    - `index.rs`: EAVT / AEVT / AVET / VAET key types, `FactRef`, `encode_value`
-   - `btree_v6.rs`: On-disk B+tree (`build_btree`, `OnDiskIndexReader`, `MutexStorageBackend`)
+   - `btree_v6.rs`: On-disk B+tree (`build_btree`, `rebuild_btree_incremental`, `OnDiskIndexReader`, `MutexStorageBackend`)
    - `btree.rs`: Legacy v5 B+tree (migration only)
    - `cache.rs`: LRU page cache (`PageCache`, default 256 pages)
    - `packed_pages.rs`: Packed fact pages (~25 facts/4KB page), `MAX_FACT_BYTES`
@@ -167,7 +167,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 → v7 on open/checkpoint.
 
 ## Test Coverage
 
-**1176 tests passing** (1168 passing, 8 ignored; unit + integration + doc).
+**1190 tests passing** (1182 passing, 8 ignored; unit + integration + doc).
 See `docs/TEST_COVERAGE.md` for the full per-file breakdown.
 
 **Testing conventions** — see the Testing Conventions section below before writing any tests.

@@ -92,7 +92,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit
 
 ```bash
 cargo run          # interactive Datalog REPL
-cargo test         # run 1176 tests
+cargo test         # run 1190 tests
 cargo run < demos/demo_recursive.txt   # recursive rules demo
 ```
 

@@ -415,6 +415,40 @@ fn bench_checkpoint(c: &mut Criterion) {
     group.finish();
 }
 
+// ── checkpoint/after_1_fact (#315) ────────────────────────────────────────────
+
+/// Checkpoint cost when only one fact is dirty, on an already-checkpointed graph.
+/// Before #315 this was flat in dirty bytes and proportional to graph size.
+fn bench_checkpoint_after_1_fact(c: &mut Criterion) {
+    use criterion::BatchSize;
+    use tempfile::NamedTempFile;
+
+    let mut group = c.benchmark_group("checkpoint/after_1_fact");
+    group.sample_size(20);
+    for &(label, n) in &[("10k", 10_000usize), ("100k", 100_000)] {
+        let tmp = NamedTempFile::new().unwrap();
+        let path = tmp.path().to_str().unwrap().to_string();
+        helpers::populate_file_no_checkpoint(n, &path);
+        let db = helpers::open_file_no_checkpoint(&path);
+        db.checkpoint().unwrap();
+        let mut i = 0u64;
+        group.bench_function(BenchmarkId::from_parameter(label), |b| {
+            b.iter_batched(
+                || {
+                    i += 1;
+                    db.execute(&format!("(transact [[:ck{i} :val {i}]])"))
+                        .unwrap();
+                },
+                // One dirty fact per checkpoint: batched setups would leave
+                // every checkpoint after the first with nothing to do.
+                |()| db.checkpoint().unwrap(),
+                BatchSize::PerIteration,
+            );
+        });
+    }
+    group.finish();
+}
+
 // ── Task 10: concurrent/ ─────────────────────────────────────────────────────
 
 fn bench_concurrent(c: &mut Criterion) {
@@ -1793,6 +1827,7 @@ criterion_group!(
     bench_query_extras,
     bench_open,
     bench_checkpoint,
+    bench_checkpoint_after_1_fact,
     bench_concurrent,
     bench_concurrent_file,
     bench_concurrent_btree_scan,

@@ -50,6 +50,19 @@ One entity's `:hash` is retracted and reasserted `depth` times (exactly one live
 
 The churned attribute still scales with its own history on v2.x; see #379 for the v3.0.0 fix.
 
+### Checkpoint After One Dirty Fact (#315)
+
+**Date**: 2026-09-26 · **Command**: `cargo bench --bench minigraf_bench -- checkpoint/after_1_fact` · same host as above; file on tmpfs, so fsync cost is excluded.
+
+An already-checkpointed file database of `n` facts receives one new fact, then `checkpoint()` runs; every iteration has exactly one dirty fact. "Before" is v2.0.1, which decoded and re-encoded every index entry. "After" copies index leaves that receive no new entries.
+
+| Facts | Before | After |
+|---:|---:|---:|
+| 10k | 23.9 ms | 4.01 ms |
+| 100k | 246 ms | 26.3 ms |
+
+Cost still grows with graph size, because index pages are copied on every checkpoint. Checkpoints proportional to the change alone need copy-on-write pages, tracked with #374 for v3.0.0.
+
 ## Measurement Method
 
 Criterion warms up each benchmark, collects ten samples for this query group, and estimates per-call latency from repeated iterations. The reported confidence intervals describe measurement uncertainty on this host; they are not cross-machine performance guarantees.

@@ -4,9 +4,9 @@
 
 **Verified**: 2026-09-26 with `cargo test`
 
-**Result**: 1,168 passing tests and 8 ignored tests (1,176 total)
+**Result**: 1,182 passing tests and 8 ignored tests (1,190 total)
 
-The v2.0.1 suite covers the public database API, the Datalog engine, storage and recovery paths, and the v2.0.0 locking and structured-error-code changes, plus v2.0.1's regression test for rebuilding indexes on open after several checkpoints (#370). Since v2.0.1, `tests/point_query_history_test.rs` and new storage unit tests check that attribute-narrowed bound-entity lookups return exactly what a full scan returns, and that `net_asserted_facts` matches its previous implementation on randomized histories (#323). Attribute-scan tests check that the AEVT range covers exactly the queried attribute, including non-ASCII names such as `:丿` and prefix siblings such as `:ab` for `:a` (#381).
+The v2.0.1 suite covers the public database API, the Datalog engine, storage and recovery paths, and the v2.0.0 locking and structured-error-code changes, plus v2.0.1's regression test for rebuilding indexes on open after several checkpoints (#370). Since v2.0.1, `tests/point_query_history_test.rs` and new storage unit tests check that attribute-narrowed bound-entity lookups return exactly what a full scan returns, and that `net_asserted_facts` matches its previous implementation on randomized histories (#323). Attribute-scan tests check that the AEVT range covers exactly the queried attribute, including non-ASCII names such as `:丿` and prefix siblings such as `:ab` for `:a` (#381). Incremental B+tree rebuild tests check that checkpoints which copy untouched index leaves produce exactly the entries and file checksum a full rebuild would, including over repeated checkpoints, that single-fact checkpoints do not fragment the index, and that a cyclic leaf chain or damaged slot directory is rejected rather than copied (#315).
 
 ### Covered Areas