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.
This commit is contained in:
1 parent
6559cc582b
commit
e32e42d933
17 files changed
+8871
No files matched your search
+158
@@ -0,0 +1,158 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user