Harden and fully cover the C++ translation
Add an exhaustive readable-instance sweep and a coverage gate requiring 100% line coverage of the summarised implementation. Delete branches that are unreachable under `Readable`, centralise and assert the 32-bit offset contract at the public entry points, and stop materialising `n` zero bytes when deciding `keyAfterN n k < upper`. Also add the extreme-offset regression test, harden the corpus parsers, remove unused model helpers, document the literal-total / fast-readable split, and refresh the validation and benchmark numbers.
This commit is contained in:
1 parent
e32e42d933
commit
3bb5d062ff
15 files changed
+620
-196
No files matched your search
+118
-26
@@ -15,10 +15,15 @@ The Lean build is untouched.
|
||||
| `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/diff_corpus.cpp` | Compares literal and fast on the sorted subset of the golden corpus. |
|
||||
| `tests/readable_gen.h` | Readable-by-construction instance generator (owns the selector keys and reported keys, with borrowed views into them). |
|
||||
| `tests/extreme.cpp` | Regression test for offsets at the ends of the 32-bit input range. |
|
||||
| `tests/exhaustive.cpp` | Deterministic exhaustive sweep of small readable instances (also the coverage driver). |
|
||||
| `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. |
|
||||
| `run-fuzz.sh` | Rebuilds and runs both fuzzers for a fixed time. |
|
||||
| `run-coverage.sh` | Builds with Clang source-based coverage and requires 100% line coverage of `src/fast.cpp`. |
|
||||
| `third_party/nanobench.h` | Vendored nanobench (commit `7252da9d96bd0d71f508e9b2813ab1f57fdfaec1`). |
|
||||
|
||||
## Data model
|
||||
@@ -30,6 +35,26 @@ 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.
|
||||
|
||||
Caller-supplied selector offsets must fit in `std::int32_t`. Internally they are
|
||||
stored as `Int = std::int64_t`, because the closed form also builds derived
|
||||
selectors whose offsets (for example `end.offset - residualT`) need not fit in
|
||||
32 bits. All intermediate `Int` arithmetic assumes 64-bit signed integers do not
|
||||
overflow; with 32-bit input offsets and in-memory key counts that is far from
|
||||
the limit. The corpus parsers reject offsets outside the 32-bit input range, and
|
||||
both public `closedForm` entry points assert the same contract in debug builds.
|
||||
The assertion lives at the API boundary rather than in `Selector`, because
|
||||
derived selectors legitimately exceed the input range.
|
||||
|
||||
## Scope of the two implementations
|
||||
|
||||
`literal.cpp` is the total transliteration: it is defined on arbitrary inputs,
|
||||
and `golden_test` compares it with Lean over the whole generated corpus, most of
|
||||
which is not readable. `fast.cpp` is the readable-only implementation:
|
||||
`diff_corpus` filters the corpus to readable cases, and the fuzzers and the
|
||||
exhaustive sweep generate readable instances. The Lean anchor therefore covers
|
||||
`literal` on all inputs, while `fast` is anchored to `literal` on the readable
|
||||
subset.
|
||||
|
||||
## Build
|
||||
|
||||
```sh
|
||||
@@ -57,13 +82,70 @@ cases that satisfy the readable sorting invariant:
|
||||
./cpp/build/diff_corpus cpp/oracle/golden.txt
|
||||
```
|
||||
|
||||
`extreme_test` checks both implementations on offsets from `INT32_MIN` to
|
||||
`INT32_MAX`, which the fuzzers do not generate:
|
||||
|
||||
```sh
|
||||
./cpp/build/extreme_test
|
||||
# extreme: 7574 cases, 0 mismatches
|
||||
```
|
||||
|
||||
`exhaustive_test` enumerates small readable instances instead of sampling them:
|
||||
every sorted database of up to four keys over a fixed universe of boundary
|
||||
keys, every selector key (including `⊥` and `⊤`) with offsets in `[-3, 4]`, and
|
||||
every readable result (the complete traversal, each nonempty truncated prefix,
|
||||
or the empty result when the traversal is empty) in both directions:
|
||||
|
||||
```sh
|
||||
./cpp/build/exhaustive_test
|
||||
# exhaustive: 10562068 cases, 0 mismatches
|
||||
```
|
||||
|
||||
It runs in about a second and is also the coverage driver.
|
||||
|
||||
## Coverage
|
||||
|
||||
```sh
|
||||
./cpp/run-coverage.sh
|
||||
```
|
||||
|
||||
The script configures a Clang source-based-coverage build, runs
|
||||
`exhaustive_test`, and fails unless `src/fast.cpp` has 100% line coverage.
|
||||
`exhaustive_test` alone covers every line of the summarised implementation:
|
||||
|
||||
```text
|
||||
src/fast.cpp 836 regions (12 missed) 131 functions (0 missed) 773 lines (0 missed) 670 branches (125 missed)
|
||||
```
|
||||
|
||||
That is 100.00% line and function coverage, 98.56% region coverage, and 81.34%
|
||||
branch coverage. The missed branches are short-circuit operands: line coverage
|
||||
counts a condition as covered once any operand decides it, but branch coverage
|
||||
requires every operand to be the deciding one. Reaching 100% branch coverage
|
||||
would need inputs that force each redundant operand to disagree with the rest of
|
||||
its condition, which is not practical here.
|
||||
|
||||
Because equivalence is only promised on readable inputs, `src/fast.cpp` deletes
|
||||
*control-flow branches* that no readable input can take: the complete-closed
|
||||
family, the offset-one total/any wrappers and their `end.offset <= 1` shortcut,
|
||||
the `end.offset <= 1` shortcut in `completeForwardCrossedGeneral`, the
|
||||
`crossedCompleteEndLeOne` guard, and one `lastK < end.key` test that readability
|
||||
always satisfies.
|
||||
|
||||
The deletion criterion is deliberately limited to unreachable arms. An
|
||||
individual predicate operand that a dispatch invariant makes always true at one
|
||||
call site (for example `!c.r->reverse` inside a condition only reached after the
|
||||
forward branch was selected) is kept, because it is part of the Lean condition
|
||||
that the translation mirrors; re-proving the invariant at every site would make
|
||||
the tree harder to audit. Those operands are why every line is covered while branch coverage stays
|
||||
around 81%.
|
||||
|
||||
## 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
|
||||
mkdir -p /tmp/cr-corpus/readable /tmp/cr-corpus/raw
|
||||
./build/fuzz_readable -max_total_time=300 /tmp/cr-corpus/readable
|
||||
./build/fuzz_raw -max_total_time=300 /tmp/cr-corpus/raw
|
||||
```
|
||||
|
||||
or simply `./cpp/run-fuzz.sh` (optionally `./cpp/run-fuzz.sh build 600`).
|
||||
@@ -85,8 +167,16 @@ One representative validation run on this machine:
|
||||
| --- | ---: | --- |
|
||||
| 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 |
|
||||
| extreme-offset regression (`extreme_test`) | 7,574 | 0 mismatches |
|
||||
| exhaustive readable sweep (`exhaustive_test`) | 10,562,068 | 0 mismatches |
|
||||
| readable differential fuzzing (60 s) | 1,182,424 | 0 mismatches |
|
||||
| raw safety fuzzing (60 s) | 1,905,270 | no ASan/UBSan findings |
|
||||
|
||||
`extreme_test` covers offsets the fuzzers deliberately avoid (they draw offsets
|
||||
from `[-256, 255]`). Both implementations decide the closed form's
|
||||
`keyAfterN n k < upper` test from the key lengths (`keyAfterNLt`) rather than
|
||||
materialising `n` zero bytes, so an `end.offset` near `INT32_MAX` stays
|
||||
constant-time instead of attempting a 2 GiB allocation.
|
||||
|
||||
## Benchmark
|
||||
|
||||
@@ -94,37 +184,38 @@ One representative validation run on this machine:
|
||||
./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`).
|
||||
Representative results (Clang 21, default Release build: `-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 |
|
||||
| small complete (8 keys) | 41.6 ns | 16.2 ns | 0.39x |
|
||||
| small truncated forward | 16.9 ns | 22.9 ns | 1.35x |
|
||||
| crossed truncated forward | 56.0 ns | 46.6 ns | 0.83x |
|
||||
| crossed truncated reverse | 130.1 ns | 82.7 ns | 0.64x |
|
||||
| long complete forward (512 keys) | 2189 ns | 32.6 ns | 0.01x |
|
||||
| long truncated forward | 15.0 ns | 19.6 ns | 1.31x |
|
||||
| long truncated reverse | 9.5 ns | 12.8 ns | 1.35x |
|
||||
|
||||
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.
|
||||
Plain truncated 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. Crossed cases report 16 of a 33-key range, so the
|
||||
summary wins there too.
|
||||
|
||||
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):
|
||||
median). The crossed cases are absent from this table: their benchmark inputs
|
||||
were corrected to nonempty ranges after the owned-key measurements.
|
||||
|
||||
| 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% |
|
||||
@@ -133,15 +224,15 @@ 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
|
||||
reverse (`fast`) is the one small regression: it is a few 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:
|
||||
The fast implementation replays the same decision tree on readable inputs. 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
|
||||
@@ -153,6 +244,7 @@ changes are:
|
||||
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
|
||||
No branch condition or returned endpoint is otherwise changed on readable
|
||||
inputs; branches that `Readable` makes unreachable are omitted. Equivalence is
|
||||
therefore only claimed for readable inputs, and `fuzz_raw` deliberately does not
|
||||
compare outputs on arbitrary inputs.
|
||||
Reference in new issue
Block a user