# Solver Notes

## Formula Notes

- The family is a signed/permuted relativized pigeonhole encoding. Variables
  split structurally into:
  - `P_i,j`: primary pigeons choose a domain element.
  - `R_j`: a selected domain predicate.
  - `Q_j,c`: selected domains choose one of `p-1` secondary colors.
- Core clauses:
  - `p` long clauses require every primary pigeon to choose a domain.
  - binary `P` clauses make each domain accept at most one primary pigeon.
  - binary implication clauses enforce `P_i,j -> R_j`.
  - `R_j -> OR_c Q_j,c` clauses require a secondary color for selected domains.
  - four-literal clauses forbid two selected domains from using the same
    secondary color.
- Shuffled instances complement and permute variables, so the solver infers
  each atom's canonical literal from occurrence patterns. It does not use
  filenames or comments.
- SAT instances in the observed split are exact RPHP formulas with one
  secondary collision clause deleted. Choosing the two domains and color from
  the missing clause gives a direct model.

## Techniques Used

- Structural detector:
  - `P` variables are exactly the variables absent from four-literal clauses.
  - Long all-`P` clauses define primary rows and canonical `P` literals.
  - Binary `P` cliques recover domains; the non-`P` binary neighbor recovers
    the canonical `R_j` literal for each domain.
  - `R -> Q` clauses assign `Q` variables to domains, and four-literal
    injection clauses connect same-color `Q` variables across domains.
- SAT path:
  - If at least one expected secondary collision clause is missing, select that
    collision, assign the two domains to the same color, assign the remaining
    selected domains injectively to other colors, then verify every original
    clause before printing `SATISFIABLE`.
- UNSAT path:
  - For every exact formula, output a VeriPB proof.
  - The proof derives clique cardinalities from pairwise clauses using
    cutting-planes proof-by-contradiction.
  - It introduces extension atoms `X_j,c = R_j & Q_j,c` with redundance rules,
    derives pairwise `~X_j,c v ~X_k,c` clauses by RUP, derives secondary color
    clique bounds, and combines them with `R -> X` constraints.
  - The final proof adds `sum R_j >= p` and `sum ~R_j >= r-p+1` to obtain the
    contradiction `r >= r+1`.

## Remaining Things To Try

- Stream more detector data instead of keeping all clauses if future instances
  are much larger than the train split.
- Add support for very small degenerate `r <= 2` cases where a single missing
  secondary edge could disconnect a color component.
- Add optional proof deletions if proof-checker memory becomes a bottleneck on
  much larger deployments. Current local checks fit comfortably.

## Known Limitations

- The detector is intentionally conservative. If the `P/R/Q` counts, signs,
  components, or color classes do not match the RPHP skeleton, the solver
  returns `UNKNOWN`.
- SAT is only claimed after the constructed model satisfies the original CNF.
- UNSAT is only claimed for formulas with no missing secondary collision
  clauses; the proof is generated from recovered structure and is expected to
  be checked by VeriPB.
- The current proof does not include deletion commands, so proof size grows
  with the number of secondary collision clauses.

## Changelog

- Replaced the scaffold with a Python structural RPHP solver.
- Added a prototype analysis/proof script under `tools/rphp_proto.py`.
- Implemented SAT model construction for deleted-collision formulas.
- Implemented VeriPB UNSAT proofs using extension atoms, RUP, and
  cutting-planes cardinality derivations.
- Local verification: all 32 available train instances solved; 3 SAT models
  self-checked and 29 UNSAT proofs accepted by `veripb --cnf`.
