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

159 lines
6.7 KiB
Markdown

# 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_view`s (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::string`s because the decision
procedure can synthesise endpoints (`keyAfter`, clamp bounds) that are not
present in the input.
## Build
```sh
cd cpp
cmake -S . -B build -G Ninja -DCMAKE_CXX_COMPILER=clang++-21
cmake --build build
```
## Golden vectors from Lean
```sh
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:
```sh
./cpp/build/diff_corpus cpp/oracle/golden.txt
```
## Fuzzing
```sh
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
```sh
./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.