Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 23 additions & 32 deletions .github/workflows/coverage-gates.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@ name: Coverage Gates

on:
push:
branches: ["main"]
branches: [ "main", "v[0-9]*" ]
pull_request:
branches: ["main"]
branches: [ "main", "v[0-9]*" ]

permissions:
contents: read
Expand All @@ -17,41 +17,32 @@ jobs:
steps:
- uses: actions/checkout@v4

- name: Install Rust stable
uses: dtolnay/rust-toolchain@stable
# Branch coverage needs nightly. Pinned so a toolchain update cannot move
# the numbers under an unrelated PR; bump it on purpose and re-measure.
- name: Install Rust nightly
uses: dtolnay/rust-toolchain@master
with:
toolchain: nightly-2026-10-01
components: llvm-tools-preview

- name: Install cargo-llvm-cov
uses: taiki-e/install-action@cargo-llvm-cov

- name: Generate coverage (text)
run: cargo llvm-cov --text 2>&1 > cov_text.txt || true
- name: Build the pid_ns_helper example used by lock tests
# cargo-llvm-cov puts test binaries where the lock tests' lookup of
# examples/ next to the test binary fails; same workaround as
# llvm-cov.yml.
run: cargo build --examples --target-dir /tmp/minigraf-lock-test-examples

# A failing test fails the job: a partial report must never be gated.
- name: Run the tests with branch coverage
env:
MINIGRAF_PID_NS_HELPER: /tmp/minigraf-lock-test-examples/debug/examples/pid_ns_helper
run: cargo llvm-cov --branch --no-report

- name: Summarize coverage
run: cargo llvm-cov report --branch --json --summary-only --output-path coverage.json

# Thresholds come from coverage-thresholds.toml (#396).
- name: Check per-module thresholds
run: |
FAIL=0
check_module() {
local file=$1 threshold=$2
local pct
pct=$(grep "$file" cov_text.txt | grep -oP '\d+\.\d+(?=%)' | tail -1)
if [ -z "$pct" ]; then
echo "WARNING: $file not found in coverage report"
return 0
fi
if python3 -c "import sys; sys.exit(0 if float('$pct') >= $threshold else 1)"; then
echo "OK: $file: ${pct}% >= ${threshold}%"
else
echo "FAIL: $file: ${pct}% < ${threshold}%"
return 1
fi
}
# Thresholds from coverage-thresholds.toml
check_module "wal.rs" 75 || FAIL=1
check_module "db.rs" 70 || FAIL=1
check_module "persistent_facts" 70 || FAIL=1
check_module "btree_v6" 65 || FAIL=1
check_module "executor.rs" 75 || FAIL=1
check_module "evaluator.rs" 75 || FAIL=1
check_module "stratification" 75 || FAIL=1
exit $FAIL
run: python3 scripts/coverage_gates.py coverage-thresholds.toml coverage.json
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Tests

- **Weekly soak test at scale (#392).** `tests/soak_test.rs` grows a file-backed database to 10M live facts in batches of 1–2,000 facts, then churns it for the rest of a 5-hour budget at 50 transactions a second (retracts, re-asserts, long histories on 32 hot entities), with a checkpoint every 20–200 transactions and a reopen every 2–10 minutes. Samples are checked against a reference through EAVT, entity and attribute, AVET, AEVT, `:as-of` and the transaction counter, with a full scan in a child process at 2M facts. RSS after a reopen is bounded relative to the fact versions held. Metrics go to a JSON-lines file that `.github/workflows/soak.yml` uploads weekly, alternating `main` (Saturday) and `v3` (Sunday). On v2.x no transaction writes two values of one entity and attribute, because of the known issue #371; the v3 workload fails here. It also checkpoints every 100–1,000 transactions and samples `:as-of` less, since both cost time in the database size on v2.x. `soak_short` runs the driver at 20K facts in the normal suite.
- **Coverage gates that gate (#396).** The per-module gate in `coverage-gates.yml` had never checked anything: the instrumented test run failed (the lock tests could not find `pid_ns_helper`), the report it grepped was empty, and every module was skipped with a warning, so the job passed. It also read `cargo llvm-cov --text`, which has no per-file percentages. The job now runs the whole suite with branch coverage on a pinned nightly, fails if any test fails, and checks each file's line and branch percentage against `coverage-thresholds.toml` with `scripts/coverage_gates.py`; a file missing from the report, or without branch data, fails. The floors are the measured values less one point, for the WAL, `db.rs`, `graph/storage.rs`, the storage files (except the v5 B+tree kept for migration) and the evaluator, executor and stratification. New tests check that WAL replay stops at an entry whose first fact is over 10 MB (the old test changed bytes inside the fact and never reached the limit) or that claims more than 1M facts, that a WAL writer cannot be opened in a missing directory, and that two threads missing the same page in the page cache get the one cached copy (before, only a lucky race reached that path).

## v2.0.4 β€” 2026-10-08

Expand Down
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 β†’ v7 on open/checkpoint.

## Test Coverage

**1234 tests** (1225 passing, 9 ignored; unit + integration + doc).
**1237 tests** (1228 passing, 9 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.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ let r2 = pq.execute(&[("tx", BindValue::TxCount(2)), ("entity", BindValue::Entit

```bash
cargo run # interactive Datalog REPL
cargo test # run 1234 tests
cargo test # run 1237 tests
cargo run < demos/demo_recursive.txt # recursive rules demo
```

Expand Down
2 changes: 1 addition & 1 deletion ROADMAP.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ Scope β€” release-gate testing and documentation:
- Fault injection across save/WAL/recovery (#390)
- Long-running soak test at scale (#392; `tests/soak_test.rs`, 10M facts and a 5-hour churn weekly, alternating `main` and `v3`)
- Benchmarks at 100K–10M facts and a published performance envelope (#394)
- Higher storage/WAL coverage gates and branch-coverage gates (#396)
- Higher storage/WAL coverage gates and branch-coverage gates (#396; line and branch floors per file in `coverage-thresholds.toml`, checked on every PR)
- Durability, recovery and operations guide (#398)

---
Expand Down
76 changes: 76 additions & 0 deletions coverage-thresholds.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Per-file coverage floors, checked on every push and PR by
# .github/workflows/coverage-gates.yml (scripts/coverage_gates.py). The single
# source of truth for the gates (#396).
#
# Percentages of lines and branches covered by `cargo llvm-cov --branch` with
# the nightly pinned in that workflow, test modules included. Each floor is
# the measured value rounded down, minus one point of slack (none at 100%).
# A floor only goes up: raise it in the PR that adds the tests, and lower one
# only with the reason in the PR.
#
# v2.x (format v7) gets only data-integrity and security fixes, so these
# floors hold the line rather than climb; v3 raises its own. `btree.rs` (the
# v5 B+tree, read only for migration) is not gated.
#
# Known uncovered paths, left on purpose:
# - wal.rs `delete_file` retry sleep: Windows only (one attempt elsewhere).
# - wal.rs `scan_entries` read error other than EOF: needs a failing read on a
# regular file.

# WAL and the public API

[files."src/wal.rs"]
lines = 97
branches = 93

[files."src/db.rs"]
lines = 94
branches = 77

[files."src/graph/storage.rs"]
lines = 91
branches = 74 # random-input tests reach some branches only in some runs; lowest seen 75.7

# Storage engine

[files."src/storage/backend/file.rs"]
lines = 85
branches = 62

[files."src/storage/btree_v6.rs"]
lines = 82
branches = 81

[files."src/storage/cache.rs"]
lines = 85
branches = 75

[files."src/storage/index.rs"]
lines = 92
branches = 100

[files."src/storage/mod.rs"]
lines = 92
branches = 92

[files."src/storage/packed_pages.rs"]
lines = 73
branches = 71

[files."src/storage/persistent_facts.rs"]
lines = 88
branches = 66

# Query engine

[files."src/query/datalog/evaluator.rs"]
lines = 88
branches = 84

[files."src/query/datalog/executor.rs"]
lines = 93
branches = 75

[files."src/query/datalog/stratification.rs"]
lines = 100
branches = 100
13 changes: 9 additions & 4 deletions docs/TEST_COVERAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

**Verified**: 2026-10-10 with `cargo test`

**Result**: 1,225 passing tests and 9 ignored tests (1,234 total), including the golden-file corpus (#391)
**Result**: 1,228 passing tests and 9 ignored tests (1,237 total), including the golden-file corpus (#391)

Since v2.0.4, `tests/edge_cases_test.rs` checks that a file of 1 to 4,095 bytes is `STG-045`, unchanged and with no WAL, when it is a database cut below one page or foreign bytes, and opens as a new database that takes a write and reads it back after reopen when it is a prefix of the initial header or all zeros (#506).

Expand Down Expand Up @@ -44,8 +44,13 @@ cargo test --quiet
# Include the scheduled/ignored tests when the host supports them
cargo test -- --include-ignored

# Generate a local branch-coverage report (requires cargo-llvm-cov)
cargo llvm-cov --branch --html
# Generate a local branch-coverage report (requires cargo-llvm-cov and a nightly toolchain)
cargo +nightly llvm-cov --branch --html

# Check the per-file gates the way CI does
cargo +nightly llvm-cov --branch --no-report
cargo +nightly llvm-cov report --branch --json --summary-only --output-path coverage.json
python3 scripts/coverage_gates.py coverage-thresholds.toml coverage.json
```

Coverage percentages are intentionally not fixed in this document: they depend on the current toolchain and instrumentation. The CI coverage gates and the command above are the source of truth for the current measurement.
Coverage percentages are intentionally not fixed in this document: they depend on the toolchain and instrumentation. `coverage-thresholds.toml` holds the per-file line and branch floors, measured with the nightly pinned in `.github/workflows/coverage-gates.yml`, and lists the paths left uncovered on purpose (#396). Delete `target/llvm-cov-target` after changing the toolchain or cargo-llvm-cov version: stale binaries from an older build are merged into the report and skew it.
61 changes: 61 additions & 0 deletions scripts/coverage_gates.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
#!/usr/bin/env python3
"""Check per-file coverage floors from coverage-thresholds.toml (#396).

Usage: coverage_gates.py <thresholds.toml> <llvm-cov summary.json>

The JSON is `cargo llvm-cov report --branch --json --summary-only`. Every file
named in the thresholds must be in the report, with branch data when it has a
branch floor; a missing file or missing branch data fails the gate instead of
being skipped, so an empty or partial report can never pass.
"""

import json
import sys
import tomllib


def main() -> int:
thresholds_path, report_path = sys.argv[1], sys.argv[2]
with open(thresholds_path, "rb") as f:
floors = tomllib.load(f)["files"]
with open(report_path) as f:
report = json.load(f)

by_path = {}
for entry in report["data"][0]["files"]:
name = entry["filename"].replace("\\", "/")
for path in floors:
if name.endswith("/" + path):
by_path[path] = entry["summary"]

failures = 0
print(f"{'file':<40} {'metric':<9} {'covered':>8} {'floor':>6}")
for path, floor in floors.items():
summary = by_path.get(path)
if summary is None:
print(f"{path:<40} FAIL: not in the coverage report")
failures += 1
continue
for metric in ("lines", "branches"):
if metric not in floor:
continue
counts = summary.get(metric, {})
if not counts.get("count"):
print(f"{path:<40} {metric:<9} FAIL: no {metric} data")
failures += 1
continue
pct = counts["percent"]
ok = pct >= floor[metric]
failures += not ok
mark = "" if ok else " FAIL"
print(f"{path:<40} {metric:<9} {pct:>7.2f}% {floor[metric]:>5}%{mark}")

if failures:
print(f"\n{failures} coverage gate(s) failed. Add tests, or list a path "
"left uncovered, with its reason, in the thresholds file; lower a "
"floor only with the reason in the PR.")
return 1 if failures else 0


if __name__ == "__main__":
sys.exit(main())
55 changes: 55 additions & 0 deletions src/storage/cache.rs
Original file line number Diff line number Diff line change
Expand Up @@ -222,6 +222,61 @@ mod tests {
vec![byte; PAGE_SIZE]
}

/// Holds every `read_page` until two are in flight, so two threads miss
/// the same page before either caches it.
struct BarrierBackend {
inner: MemoryBackend,
barrier: std::sync::Barrier,
}

impl StorageBackend for BarrierBackend {
fn write_page(&mut self, page_id: u64, data: &[u8]) -> Result<()> {
self.inner.write_page(page_id, data)
}
fn read_page(&self, page_id: u64) -> Result<Vec<u8>> {
self.barrier.wait();
self.inner.read_page(page_id)
}
fn sync(&mut self) -> Result<()> {
Ok(())
}
fn page_count(&self) -> Result<u64> {
self.inner.page_count()
}
fn close(&mut self) -> Result<()> {
Ok(())
}
fn backend_name(&self) -> &'static str {
"barrier"
}
fn is_new(&self) -> bool {
false
}
}

/// Two threads that miss the same page both load it; the second to take
/// the write lock returns the first one's cached copy.
#[test]
#[cfg_attr(target_os = "wasi", ignore = "spawns threads; WASI has no threads")]
fn test_concurrent_misses_share_one_cached_copy() {
let mut inner = MemoryBackend::new();
inner.write_page(1, &make_page(0x5A)).unwrap();
let backend = BarrierBackend {
inner,
barrier: std::sync::Barrier::new(2),
};
let cache = PageCache::new(4);
let (a, b) = std::thread::scope(|s| {
let a = s.spawn(|| cache.get_or_load(1, &backend).unwrap());
let b = s.spawn(|| cache.get_or_load(1, &backend).unwrap());
(a.join().unwrap(), b.join().unwrap())
});
assert!(Arc::ptr_eq(&a, &b), "one copy cached and returned to both");
assert_eq!(a[0], 0x5A);
let cached = cache.get_or_load(1, &backend.inner).unwrap();
assert!(Arc::ptr_eq(&a, &cached));
}

#[test]
fn test_cache_miss_loads_from_backend() {
let mut backend = MemoryBackend::new();
Expand Down
42 changes: 32 additions & 10 deletions src/wal.rs
Original file line number Diff line number Diff line change
Expand Up @@ -842,22 +842,44 @@ mod tests {
writer.append_entry(1, &[fact]).unwrap();
writer.file.sync_all().unwrap();

// Manually corrupt the WAL to have a fact larger than MAX_FACT_SIZE
// Overwrite the first fact's length, after the entry's checksum,
// tx_count and num_facts, with one just over MAX_FACT_SIZE.
let mut file = std::fs::OpenOptions::new().write(true).open(&path).unwrap();
file.seek(std::io::SeekFrom::End(-20)).unwrap();
// Overwrite the fact length to be huge
let huge_len: u32 = (10 * 1024 * 1024 + 1) as u32; // Just over MAX_FACT_SIZE
file.seek(std::io::SeekFrom::Start(WAL_HEADER_SIZE as u64 + 20))
.unwrap();
let huge_len: u32 = (10 * 1024 * 1024 + 1) as u32;
file.write_all(&huge_len.to_le_bytes()).unwrap();

drop(file);

// Try to read - should fail gracefully
// Replay stops at the entry instead of allocating 10 MB.
let mut reader = WalReader::open(&path).unwrap();
let result = reader.read_entries();
assert!(
result.is_err() || result.unwrap().is_empty(),
"Should fail or return empty on corrupted large fact"
);
assert!(reader.read_entries().unwrap().is_empty());
}

#[test]
fn test_wal_entry_with_too_many_facts_ends_replay() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("test.wal");
wal_with_entries(&path, 2);
let one_len = {
let p = dir.path().join("one.wal");
wal_with_entries(&p, 1).len()
};
// Entry 2's num_facts, after its checksum and tx_count.
let mut file = std::fs::OpenOptions::new().write(true).open(&path).unwrap();
file.seek(std::io::SeekFrom::Start(one_len as u64 + 12))
.unwrap();
file.write_all(&1_000_001u64.to_le_bytes()).unwrap();
drop(file);
assert_eq!(tx_counts(&path), [1]);
}

#[test]
fn test_wal_writer_open_fails_in_a_missing_directory() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("missing").join("test.wal");
assert!(WalWriter::open_or_create(&path, SyncMode::Full).is_err());
}

// ── #360: WAL-0xx error code regression tests ──────────────────────────
Expand Down
Loading