# Solver Notes

## Formula Notes

The `edit_distance` family encodes cluster editing. The first
`3 * C(M, 3)` clauses are the equality/transitivity constraints over the
`C(M, 2)` pair variables. The exact gate block is:

```text
-a -b  c
-a  b -c
 a -b -c
```

This lets the solver reconstruct the hidden vertex pair for every low
variable without using comments or filenames.

After the transitivity block, each pair variable appears with one consistent
polarity in the edit-literal leaves. A positive low literal means the original
graph has that edge and a deletion is counted when the pair variable is false.
A negative low literal means a non-edge and an insertion is counted when the
pair variable is true. The remaining variables are a unary cardinality
encoding using standard totalizer blocks and modulo-totalizer blocks.

The modulo-totalizer structure is parsed from clauses, not hard-coded by
variable numbers. Each parsed block is evaluated from the recovered partition
to produce a complete assignment for all auxiliary variables.

## Techniques Used

- Structural detector for the transitivity prefix and pair-variable map.
- Direct graph extraction and cluster-editing local search over vertex
  partitions.
- Clause-level parser for totalizer, modulo-remainder, quotient, and carry-only
  quotient merge blocks.
- Complete auxiliary model reconstruction from the parsed counter DAG.
- Final soundness gate: every CNF clause must be satisfied before printing
  `SATISFIABLE`; otherwise the solver returns `UNKNOWN`.

## Current Results

Local run on `/data/train` after model checking:

- SAT: 11 / 16
- UNKNOWN: 5 / 16
- SAT-invalid: 0 locally

The five UNKNOWN cases match the instances where local cluster search finds a
best partition just above the encoded edit bound. No UNSAT proof is emitted.

## Known Limitations

- UNSAT instances are not solved because the solver does not currently produce
  VeriPB proofs.
- The detector is intentionally conservative and expects the same ordered
  transitivity and totalizer clause families as the training generator.
- The cluster search is heuristic. It is very fast on the observed training
  split, but a harder SAT instance could require more restarts or stronger
  partition moves.

## Remaining Things To Try

- Derive a VeriPB proof strategy for cluster-editing lower bounds to solve the
  UNSAT side.
- Add stronger partition moves such as pair swaps or small cluster split/merge
  neighborhoods if future SAT instances are harder.
- Parse the encoded bound explicitly for diagnostics and targeted stopping,
  while still relying on final CNF verification for soundness.

## Changelog

- Recovered the high-level cluster-editing problem from the equivalence gate
  prefix and edit-literal leaves.
- Implemented direct graph extraction and local search over cluster
  partitions.
- Implemented totalizer/modulo-totalizer block parsing and deterministic
  auxiliary assignment reconstruction.
- Added complete CNF model verification before SAT output.
- Updated build metadata for the specialized C++ solver.
