db-11 — Verification

Prerequisites

  • macOS or Linux with Apple Clang / clang ≥ 14 / gcc ≥ 11.
  • cmake ≥ 3.20.
  • Rust toolchain ≥ 1.74.
  • Go ≥ 1.22.
  • shasum, xxd, awk (default on macOS; coreutils on Linux).

One command

cd db-11-pager-system
scripts/verify.sh        # unit tests, all three languages
scripts/cross_test.sh    # cross-language sha256 match

Both should print === OK === / === ALL OK === and exit 0.

Per-language drill-down

Rust

cd db-11-pager-system/src/rust
cargo test --quiet
cargo build --release

Expected: all 10 inline tests pass; target/release/pagerctl is built.

Go

cd db-11-pager-system/src/go
go test ./...
go build ./cmd/pagerctl

Expected: ok github.com/10xdev/dse/db11 <duration>. The TestWorkloadMatchesCanonicalHashes test is the most important; it fails loudly if Go disagrees with Rust on any of the three scenarios.

C++

cd db-11-pager-system/src/cpp
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
ctest --test-dir build --output-on-failure

Expected: 100% tests passed, 0 tests failed out of 1 and the test_pager11 target prints OK 11 tests.

What "green" means

A green run guarantees:

  • All inline unit tests pass in Rust, Go, and C++.

  • The cross-language test produces byte-identical files for all three canonical scenarios:

    scenariotypeseedpagescacheopspszsha256
    Asequential42328200256cbac0289ce1eb784e5bd80ab1298c3f9677f1aeb3cfdb09ce78d6796c43b9428
    Brandom76485002563405654fd750bffa933c2d1b590160fcbf8ec446f261cc25c5c04c8c0c3dd023
    Cmixed20241281610005125b10acb3e9cf57e3b314c17dc9fa122d79caac6a46501c71875374f9d6720460

    Matching sha256 across three independent implementations proves agreement on:

    • the file format (header magic, page_size, num_pages encoding),
    • the SplitMix64 PRNG (constants and bit-extraction layout),
    • the workload state machine (op/pid/byte selection),
    • the cache admission rule (write-on-miss admits without read),
    • the eviction rule (LRU tail, dirty pages written back),
    • the flush order (dirty pages sorted by pid before write),
    • and the final on-disk page layout.

  • The spot-check confirms the first 20 bytes of Scenario A's file are 4453452d50414745522d76310000000000010000 (magic + page_size = 256 LE), guarding against the regression where all three languages "successfully" agree on a wrong header.

When verification fails

  • Cross-language sha256 mismatch on Scenario A only — the sequential scenario exercises the simplest code path (no random pid selection, predictable evictions). A failure here is almost always either:
    • the magic / header encoding (check the spot-check first), or
    • the SplitMix64 PRNG (re-derive the first 5 outputs by hand and compare against 0xe220a8397b1dcdaf, …).
  • Scenario A matches, B fails — the random scenario stresses eviction. Look for off-by-one in LRU tail selection or for a language whose unordered_map iteration leaks into the flush order (it should not; flush sorts by pid).
  • A and B match, C fails — the mixed scenario uses a larger cache and a larger page size; suspect a page-size assumption baked into the implementation (e.g., a hard-coded 256 instead of reading from the header).
  • All three sha256s match each other but disagree with the table above — a legitimate algorithm change. Make sure it was intentional, then update cross_test.sh, the Go canonical-hashes test, the C++ canonical-hashes assertion, and the table above in the same commit.
  • One language's unit tests pass but cross_test fails — almost always a CLI bug, not a library bug. The unit tests drive the library directly; the cross_test drives the binary through the shell. Double-check argument parsing: in particular, that <path> may appear before the --flags (this is the bug the Go port hit during bring-up, fixed by the custom findFlag/firstPositional parser).