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:
andrew committed 2026-11-17 18:46:24 -05:00
1 parent e32e42d933
commit 3bb5d062ff
15 files changed
+620 -196

No files matched your search

+118 -26
View File
@@ -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.