# Solver Notes

## Formula Notes

- The family is `or_randxor`: DIMACS variables occur in pairs `(2i-1, 2i)`.
- Each pair represents one high-level Boolean `y_i = x_{2i-1} OR x_{2i}`.
- Each contiguous clause block mentions exactly three pairs and encodes one
  3-XOR equation over those high-level OR values.
- Block size identifies the RHS without comments:
  - 13 clauses: odd parity, `y_a xor y_b xor y_c = 1`
  - 14 clauses: even parity, `y_a xor y_b xor y_c = 0`
- Visible training files have 510-600 high-level variables/equations and are
  inconsistent over GF(2).

## Techniques Used

- Structural detector groups contiguous clauses by their three OR-pair indices.
- GF(2) Gaussian elimination solves the recovered linear system and tracks a
  row dependency for UNSAT certificates.
- SAT case: choose the second variable in every pair false and realize the
  high-level solution on the first variable; the solver checks every original
  CNF clause before printing `SATISFIABLE`.
- UNSAT case:
  - Add `~x_{2i}` for every pair with VeriPB `red`, witness
    `x_{2i}->0, x_{2i-1}->1`.
  - For each equation in the inconsistent dependency, derive the direct
    3-XOR clauses on odd representatives by RUP.
  - Introduce fresh carry/parity variables with `red` templates and derive two
    PB inequalities encoding `sum literals = 2*c + rhs`.
  - Sum all lower and upper inequalities in the dependency. All original
    variable and carry coefficients are even, while the RHS is odd; dividing
    and rounding the lower sum, multiplying back by two, and adding the upper
    sum derives `>= 1`.

## Remaining Things To Try

- Add support for non-contiguous blocks if future instances shuffle clauses.
- Reduce proof size by only adding OR-pair symmetry units touched by the
  inconsistent dependency.
- Add annotated RUP hints if proof checking becomes a bottleneck on larger
  hidden instances.

## Known Limitations

- The detector intentionally returns `UNKNOWN` if the OR-pair block structure,
  variable pairing, or 13/14-clause XOR block shape is not present.
- UNSAT proof generation assumes the target's three-pair blocks are contiguous,
  as in all visible training instances.
- The solver does not implement a fallback SAT solver for unrelated CNFs.

## Changelog

- Initial scaffold: placeholder solver returned `UNKNOWN`.
- Added `tools/profile_or_randxor.py` to summarize block counts and clause
  distributions for training instances.
- Replaced the placeholder with a C++ specialized solver:
  structural OR-pair XOR recovery, GF(2) Gaussian elimination, SAT model
  self-checking, and VeriPB UNSAT proof generation using redundance and
  cutting-planes parity reasoning.
- Filled in metadata for broker submission.
