db-16 — Verification

How to reproduce the green status on a clean machine.

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-16-distributed-fundamentals
scripts/verify.sh        # builds + unit tests in all three langs
scripts/cross_test.sh    # cross-language sha256 match

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

Per-language drill-down

Rust

cd db-16-distributed-fundamentals/src/rust
cargo test --quiet
cargo build --release

Expected: 7 passed; 0 failed. The simctl binary lands in target/release/simctl.

Go

cd db-16-distributed-fundamentals/src/go
go test ./...
go build ./cmd/simctl

Expected: ok github.com/10xdev/dse/db16 <duration>.

C++

cd db-16-distributed-fundamentals/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 test_db16 prints "db-16 C++ tests: 7 passed".

What "green" means

A green run guarantees:

• All 21 unit tests pass (7 each in Rust, Go, C++) covering Lamport monotonicity, vector-clock partial order including the Concurrent case, simulator determinism on a fixed seed, and causality of the generated event log.

• The cross-language test produces byte-identical event logs for both canonical scenarios:

  scenario	sha256	size
  A --seed 42 --nodes 3 --rounds 20	0d7e753cdc891e3a481977da372a4d97a6a0e0ab00b74f5a074dbc25791dc797	8 156 B
  B --seed 7 --nodes 5 --rounds 50	321221187709684afd59c55202f8d373dad33c8026e933b36740aeed23c8c2d4	45 592 B

  Matching sha256s prove that all three implementations agree on the PRNG, the scheduling rule, the Lamport / vector-clock update rules, the VC entry ordering on the wire, and the integer endianness.

• The spot-check in cross_test.sh confirms the magic header 44 53 45 36 and the expected u32 LE event count, guarding against the regression where all three implementations agree on producing empty output.

When verification fails

• Cross-language sha256 mismatch on the first 8 bytes — magic / count drift. Almost always a count formula bug (2 × nodes × rounds).
• Mismatch past byte 8 but matching on a smaller --rounds — the PRNG or the scheduler diverges as soon as a recv-in-flight overlaps with a send. Inspect splitmix64 and the heap tie-break.
• Causality test fails in one language only — that language's recv does not bump its own counter, or bumps before the merge. Read the Vector-clock rule in CONCEPTS again.
• One language passes locally but the cross-test diverges — most often: VC entries serialized in insertion order rather than sorted by node-id. Switch to BTreeMap / std::map / explicit sort.Slice.