Files
conflict-range/README.md
T
andrew a0b68d148b Simplify crossed dispatch and add SMT-derived cases
Drop the redundant begin.offset split in crossedCompleteOvershoot and
the rE > 0 guard in closedFormForwardSaturated; both are implied by
the call-site invariants.

Add an SMT-derived empty-interval case as the smt_cases CTest and as a
committed fuzz_readable seed.  run-fuzz.sh now loads the read-only seed
corpus alongside the writable one.

Rename exhaustive to sweep and document that it is exhaustive only
over its bounded family of instances.
2026-11-18 13:03:55 -05:00

90 lines
4.7 KiB
Markdown

# conflict-range
A closed-form algorithm that computes the minimal conflict range for an observed
range read and result, based on the semantics used by FoundationDB.
See `Statement.lean` for definitions and the headline claim that the algorithm's
output is minimal. Intuitively, the minimal range is the smallest range that
preserves serializability (i.e. pinning this range pins the validity of any
inference you can make from the observed range read and result), and the key set
is unique: any two minimal ranges denote the same set of keys, though their
endpoints may differ.
See `cpp/src/fast.cpp` for the C++20 implementation.
The rest of this README documents the Lean proof and the C++/test support for
these claims.
## Layout
| Path | Purpose |
| --- | --- |
| `Statement.lean` | The statement: keys, selectors, reads, results, conflict ranges, soundness, minimality, and the closed form itself. It imports only Mathlib and states the definitions and headlines without using `theorem`, `axiom`, or `sorry`. |
| `FormalConflictRange/` | The reference development that proves the closed form minimal. |
| `Bridge.lean` | Definitional bridge from `Statement`'s types to the reference development, plus the transport lemmas. |
| `Proof.lean` | Proves `Statement.ClosedFormMinimal` and `Statement.MinimalUnique` by transporting the reference theorems across the bridge. |
| `Challenge.lean` | The same two headline statements with placeholder proofs (`sorry`). This is the trusted statement side of the comparator check. |
| `Solution.lean` | The solution side of the comparator check; it imports `Proof`. |
| `comparator.json` | Comparator configuration: challenge/solution modules, theorem names, and permitted axioms. |
| `cpp/` | A C++20 translation of `closedForm`, an equivalent summarised implementation, golden-vector and fuzz tests, and a benchmark. See `cpp/README.md`. |
## Build and check
```sh
lake exe cache get # clean checkout: download Mathlib's prebuilt oleans
lake build
./scripts/check-axioms.sh
lake comparator
```
This repository pins Lean `v4.35.0` and Mathlib `v4.35.0`
(`lean-toolchain`, `lakefile.toml`). `lake exe cache get` downloads Mathlib's
prebuilt `.olean` files; without it a fresh clone compiles Mathlib from source.
`lake build` then compiles the default targets (`Statement` and `Proof`, which
pull in the reference development); run it before the checks so that a manifest
is present and dependencies are resolved.
`./scripts/check-axioms.sh` prints the axiom dependencies of
`Statement.closedFormMinimal` and `Statement.minimalUnique` and fails unless
both are exactly `[propext, Classical.choice, Quot.sound]`. This catches `sorry`
(`sorryAx`) and newly introduced axioms without needing the comparator sandbox.
`lake comparator` then builds `Challenge` and `Solution` independently and
checks that the solution proves the challenge's statements and uses only
`propext`, `Quot.sound`, and `Classical.choice`. It requires `bubblewrap` and
either unprivileged user namespaces or a setuid-root `bwrap`; on systems where
user namespaces are restricted, `lake comparator` will fail before checking the
proof.
## Status and scope
* `Statement.ClosedFormMinimal` and `Statement.MinimalUnique` are proved, and no
proof in `Proof.lean`, `Bridge.lean`, or `FormalConflictRange/` uses `sorry`.
* `Challenge.lean` deliberately contains `sorry`: it is the statement side of
the comparator check, not part of the proof.
* The headline argument is the closed-form development under `FormalConflictRange/`.
`FormalConflictRange/Algorithm.lean` and `FormalConflictRange/Prototype.lean`
also supply shared ingredients used by that development: the empty-result
theory (`emptyValue`, `EmptyInferenceWitness`,
`minimal_emptyValue_of_emptyInference`) and the ascending-key list and
constraint collectors (`ascendingKeys`, `emptyConstraints`), respectively.
Their partial-algorithm and prototype sections are earlier case-analysis and
search material; those sections are not the route taken by the final
closed-form proof.
* The C++ tree is validated against Lean-generated golden vectors, by
differential fuzzing, and by a deterministic finite sweep of small
readable instances; `cpp/README.md` describes the model, the tests, the
coverage check, and the benchmark. The summarised implementation has 100%
line and branch coverage via `cpp/run-coverage.sh`.
## Continuous integration
`.gitea/workflows/ci.yml` runs the Lean build, the axiom audit, and the C++ test
suite (including the coverage gate) on pushes to `main` and on pull requests. It
is written for Gitea Actions; a GitHub mirror would need an equivalent workflow
under `.github/workflows/`.
## License
Apache License 2.0; see `LICENSE`.