- 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.
159 lines
6.7 KiB
Markdown
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.
|