Files
conflict-range/cpp/README.md
T
andrew e32e42d933 Add a C++ translation of the closed form
- Literal transliteration of `Statement.closedForm` plus an equivalent
  summarised implementation
- Borrowed input keys (`std::string_view` / `std::span`) and owned result
  keys (`std::string`)
- Golden-vector test, differential/safety fuzzers, and a nanobench
  comparison

The literal and summarised implementations agree on 40,000 Lean golden
vectors, 18,971 sorted corpus cases, and the readable fuzzer; the raw fuzzer
runs both implementations under ASan/UBSan.  `build/` and the generated
`oracle/golden.txt` are ignored.
2026-11-17 16:08:07 -05:00

6.7 KiB

C++ translation of Statement.closedForm

This directory contains a C++20 translation of Statement.closedForm from Statement.lean, an equivalent summarised implementation, a libFuzzer differential harness, and a nanobench comparison.

The Lean build is untouched.

Layout

Path Purpose
src/model.h Data model: borrowed input keys (std::string_view), owned result keys (std::string), WithTop Key = std::optional, ℕ∞ = NatInf.
src/literal.cpp Line-by-line transliteration of Statement.closedForm, including its repeated scans.
src/fast.cpp The same decision tree, but with a summary of the reported keys and lazily cached cardinalities.
oracle/gen.lean Deterministic generator of golden vectors by evaluating the real Lean closedForm.
tests/golden.cpp Checks the literal translation against the Lean golden vectors.
tests/readable_gen.h Readable-by-construction instance generator (owned database and selectors, with borrowed views into them).
tests/fuzz_readable.cpp libFuzzer differential test: literal vs. fast on readable instances.
tests/fuzz_raw.cpp libFuzzer safety test on arbitrary instances under ASan/UBSan.
tests/bench.cpp nanobench literal-vs-fast benchmark.
third_party/nanobench.h Vendored nanobench (commit 7252da9d96bd0d71f508e9b2813ab1f57fdfaec1).

Data model

Inputs borrow and results own. RangeRead selectors and the reported keys in Result are std::string_views (the reported keys via a std::span), so a caller can point them straight at existing storage and the implementation reads them in place. ConflictRange returns owned std::strings because the decision procedure can synthesise endpoints (keyAfter, clamp bounds) that are not present in the input.

Build

cd cpp
cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=clang++-21
cmake --build build

Golden vectors from Lean

cd ..
lake env lean --run cpp/oracle/gen.lean > cpp/oracle/golden.txt
./cpp/build/golden_test cpp/oracle/golden.txt
# golden: 40000 cases, 0 mismatches

The golden test compares exact endpoints, because the literal translation reproduces Lean's interval encoding exactly (including empty intervals).

diff_corpus compares the literal and fast implementations on the generated cases that satisfy the readable sorting invariant:

./cpp/build/diff_corpus cpp/oracle/golden.txt

Fuzzing

cd cpp
mkdir -p /tmp/cr-corpus
./build/fuzz_readable -max_total_time=300 /tmp/cr-corpus
./build/fuzz_raw      -max_total_time=300 /tmp/cr-corpus-raw

or simply ./cpp/run-fuzz.sh (optionally ./cpp/run-fuzz.sh build 600). The CMake fuzz targets compile the implementation sources directly so that the decoder code, not just the harness, is covered by ASan/UBSan.

fuzz_readable builds a sorted, duplicate-free database, resolves both selectors against it, and reports either the complete traversal or a nonempty prefix. This makes every generated pair genuinely Readable. The differential check treats all encodings of the empty interval as equivalent and otherwise requires exact endpoints.

fuzz_raw only checks memory safety and undefined behaviour for arbitrary (possibly unreadable) inputs.

One representative validation run on this machine:

check cases / runs result
literal vs. Lean golden vectors 40,000 0 mismatches (exact endpoints)
fast vs. literal on sorted corpus 18,971 0 mismatches
readable differential fuzzing 2,310,641 0 mismatches
raw safety fuzzing 1,936,245 no ASan/UBSan findings

Benchmark

./cpp/build/cr_bench

Representative results (Clang 21, -O3 -DNDEBUG, medians of nine runs pinned to one core; relative to the literal translation, lower is better for fast). CPU frequency scaling makes the absolute numbers noisy, but the shape is stable:

case literal fast fast/literal
small complete (8 keys) 41.1 ns 16.6 ns 0.40x
small truncated forward 16.9 ns 23.1 ns 1.37x
crossed truncated forward 23.9 ns 24.4 ns 1.02x
crossed truncated reverse 24.0 ns 24.4 ns 1.02x
long complete forward (512 keys) 2093 ns 31.9 ns 0.02x
long truncated forward 14.8 ns 19.8 ns 1.34x
long truncated reverse 10.4 ns 14.2 ns 1.36x

The large win is on complete reads: the literal translation rescans the reported keys many times (residualT, reportedBelowBegin, allBelowEnd, ...), while the summary answers those questions in O(log n) or from a cached count. Truncated and crossed cases are dominated by the shared decision tree, so the two implementations are close; the literal path is slightly cheaper there because it performs no summary setup.

Against the same implementation with owned input keys (the previous model), the borrowed-key model changes the costs as follows (nine interleaved runs each, median):

case literal (borrow vs own) fast (borrow vs own)
small complete -64% -17%
small truncated forward -33% -19%
crossed truncated forward +4% +2%
crossed truncated reverse +4% +2%
long complete forward -69% -15%
long truncated forward -29% -6%
long truncated reverse -16% +16%

The complete-read gains come from not copying the reported keys just to normalise the result: a forward result is now the caller's span, and a reverse result is a reversed view rather than an owned copy. The fast path also benefits because it previously normalised complete results the same way. Truncated reverse (fast) is the one small regression: it is two nanoseconds and a few dozen instructions, and the other paths move in the opposite direction, so it reads as code-layout/code-generation noise rather than extra algorithmic work.

Why the fast implementation is equivalent

The fast implementation replays exactly the same decision tree. The only changes are:

  • reportedBelowBegin and residualT are summarised once. On readable inputs the reported keys are sorted in traversal order, so both counts are binary searches. The summaries depend only on the read and on the multiset of reported keys, so they survive the reversed-view normalisation.
  • Interval cardinalities (intervalCard) are cached lazily.
  • Complete observations are not copied: a forward result borrows the caller's span, and a reversed result is viewed backwards in place. (The previous owned-key model copied and reversed the reported keys here.)
  • allBelowEnd is residualT == 0 and anyAtOrAboveEnd is residualT != 0.

No branch condition or returned endpoint is otherwise changed. Equivalence is therefore only claimed for readable inputs; fuzz_raw deliberately does not compare outputs on arbitrary inputs.