db-17 — 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, cmp, awk (default on macOS; coreutils on Linux).

One command

cd db-17-raft
scripts/verify.sh        # builds + unit tests in all three langs
scripts/cross_test.sh    # cross-language sha256 match across six scenarios

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

Per-language drill-down

Rust

cd db-17-raft/src/rust
cargo test --release --quiet
cargo build --release

Expected: ~10 tests pass. The raftctl binary lands at target/release/raftctl. The release profile uses LTO.

Go

cd db-17-raft/src/go
go test ./...
go build -o /tmp/raftctl_go ./cmd/raftctl

Expected: ok github.com/10xdev/dse/db17 <duration> and a working binary. Tests include TestSha256HexKnownVectors (validates the SHA-256 wrapper against published vectors) and TestVotedForNegativeEncoding (validates the -1 sentinel byte layout).

C++

cd db-17-raft/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_db17 prints "db-17 C++ tests: 10 passed". The test source #undef NDEBUG before <cassert> so assert() fires in Release builds too.

What "green" means

A green run guarantees:

1. Per-language unit tests pass. Each implementation independently exercises splitmix64, election-timer reset, RequestVote granting, AppendEntries truncation, single-node commit, multi-node commit, canonical dump magic + node_count + log_len framing, and the SHA-256 implementation against a known test vector.

2. All six scenarios produce byte-identical canonical dumps across Rust, Go, and C++. cross_test.sh actually compares the raw dump bytes (cmp -s) before comparing the sha256 hex, so a divergence is caught with an exact byte offset rather than just "the hashes don't match".

3. The sha256s match the table in docs/observation.md. If you change the algorithm or the dump format, both the dumps and the table must change in the same commit. The mismatch between code and docs is itself a verification failure.

What "green" does NOT guarantee

• No production safety. There is no fsync; in-memory state is considered durable by construction.
• No coverage of snapshot / membership / pre-vote / lease code. Those features are deferred to db-21, db-23, and possibly never (this lab is a study lab, not a production engine).
• No client-facing API. Proposals are injected into the simulator via a fixed schedule; there is no Propose RPC for an external client.
• No performance characterization. The lab is sized to run in under a second per scenario; multi-thousand-round runs work but are not the goal.

Invariant assertions in code

The C++ test file in particular makes the invariants concrete:

The Rust and Go tests assert the same set in their respective testing idioms.