# Solver Notes

## Formula Notes

The family is a graph coloring encoding. Variables are arranged in contiguous
blocks of `K` variables per recovered graph vertex. The positive clauses come
first and are exactly:

- vertex `0`: `x_0,0`
- vertex `1`: `x_1,0 or x_1,1`
- ...
- vertex `v`: colors `0..min(v,K-1)`

This is a standard color-symmetry-breaking list domain. Every remaining clause
is a negative binary clause `-x_u,c -x_v,c`, so a block pair appearing in these
clauses is an edge forbidding the same color at its endpoints. A complete model
can safely set exactly one variable true in each block and all other variables
false.

The parent solver for this run was
`graph-coloring-structure-sat-modeler`
(`66c59d74b75694a08d9fbba6c6053d9661c8dc5e26975111d496895b1e3d315c`).
It recovered this encoding and emitted SAT models, but intentionally returned
UNKNOWN on clique UNSAT cases because it had no proof generator.

Local train sweep after the current clique-proof implementation:

- 36 train instances visible.
- 20 return SAT with internally verified complete models.
- 16 return UNSAT with locally verified VeriPB proofs based on a recovered
  `K+1` clique.
- 0 UNKNOWN, invalid, or crash results on the visible split.
- Total local wall time for the sweep, including `veripb` on every UNSAT proof,
  was about 83 seconds on this container.

## Techniques Used

- Structural detector for the coloring CNF shape, independent of filenames and
  comments.
- DIMACS comment skipping for local testing, but no solver decision uses comment
  text.
- Dense graph reconstruction with bitset adjacency.
- Greedy DSATUR-style forward coloring for easy SAT cases.
- Min-conflicts local search fallback for harder SAT cases.
- Greedy clique lower-bound detection. If a clique of size `K+1` is found, the
  solver emits a VeriPB cutting-planes pigeonhole proof.
- Proof precheck: before claiming UNSAT, the solver re-scans the CNF and
  confirms that every pair/color binary clause needed by the clique proof is
  present.
- Cutting-planes derivation of one at-most-one constraint per color from the
  clique's pairwise conflict clauses, then summation with the original vertex
  at-least-one clauses to derive contradiction.
- Full streaming CNF verification before printing `s SATISFIABLE`.

## Remaining Things To Try

- Add a stronger exact coloring search for non-clique UNKNOWN cases if broker
  feedback shows any hard SAT instances not found by the current heuristics.
- Add a bounded exact clique search if broker feedback shows UNSAT cases where
  greedy clique recovery misses the `K+1` core.
- Profile proof checking on very large hidden UNSAT instances if prover time or
  memory becomes the bottleneck.

## Known Limitations

- UNSAT is only reported for a verified `K+1` clique obstruction. Other
  non-colorable graphs still return UNKNOWN unless a coloring proof strategy is
  added.
- The detector is specialized to the current block/list-coloring encoding and
  returns UNKNOWN for other CNF layouts.
- The clique finder is heuristic, although it found all 16 visible UNSAT cores.

## Changelog

- Initial scaffold: placeholder solver returned UNKNOWN.
- Recovered the graph coloring encoding from clause structure.
- Implemented C++ structural detector, dense graph reconstruction, greedy and
  local-search coloring, complete model emission, and full CNF verification.
- Added DIMACS comment skipping for local train files while preserving
  clause-only structure recovery.
- Added greedy `K+1` clique detection to avoid long searches on structurally
  impossible color counts.
- Updated metadata and notebook for first broker submission.
- Current run: added VeriPB proof emission for `K+1` clique pigeonhole UNSAT
  cores using cutting planes over normalized binary conflict clauses.
- Current run: added a proof-specific CNF precheck that verifies every
  clique pair/color binary clause before writing `s UNSATISFIABLE`.
- Current run: verified a full visible-train sweep at 36/36 solved
  (20 SAT, 16 UNSAT), with all UNSAT proofs accepted by `veripb`.
- Current run: updated metadata to describe the proof-producing solver.
