# Solver Notes

## Formula Notes

- Target family is `testpattern-generation`; train instances are all UNSAT.
- Two structural regimes appear in training:
  - `bf1355`: about 2293-2298 variables, 7295-7307 clauses, usually 5 units,
    about 3926-3936 binaries, about 2857-2871 ternaries, and roughly 500
    longer clauses.
  - `ssa2670`: about 1327-1359 variables, 3201-3321 clauses, 4 units, about
    2406-2454 binaries, 603-659 ternaries, and 188-204 longer clauses.
- Plain unit propagation does not refute the formulas. The binary implication
  graph is also consistent for every training instance.
- Clause patterns show many Tseitin-style gates and XOR/equivalence signatures
  (roughly 870-880 XOR-like constraints in `ssa2670`, roughly 1190 in
  `bf1355`), but Gaussian elimination over those XOR signatures alone is not
  contradictory.

## Techniques Used

- The solver parses stripped DIMACS only; it does not read comments or file
  names.
- A root failed-literal probe is run before branching. Failed literals are
  logged as RUP unit clauses, so they are independently checkable by VeriPB.
- The main refutation engine is a small self-contained CDCL core with watched
  literals, first-UIP conflict analysis, VSIDS-style variable activity, and
  restarts.
- Every learned clause is written as a VeriPB `rup` constraint. The final empty
  clause is also emitted as `rup >= 1 ;`, followed by a VeriPB UNSAT
  conclusion.
- If a SAT assignment is ever found on a variant, the solver assigns remaining
  variables and checks every original clause before printing `SATISFIABLE`.

## Local Validation

- Built with `./build.sh` using the scaffold's Ice Lake clang++ flags.
- Local decompressed training run: 42/42 UNSAT.
- Local VeriPB check: 42/42 proofs verified.
- Local solver-time average in the validation script: about 0.013s, max about
  0.023s. VeriPB checking averaged about 0.006s for the tuned proof logs.

## Remaining Things To Try

- Recover the exact ATPG gate-level objects and generate an even more direct
  structural proof for the redundant fault cases.
- Add optional XOR-aware branching. Do not use XOR propagation as a proof
  reason unless its consequences are converted to VeriPB-checkable steps.
- Tune restart and phase heuristics on broker feedback if hidden instances have
  a wider parameter range.

## Known Limitations

- The solver is optimized for the observed test-pattern CNF shape. It is not a
  general SAT solver and may return `UNKNOWN` only on parse/write failures; on
  structurally different satisfiable formulas it relies on the internal model
  checker for soundness.
- UNSAT soundness depends on VeriPB accepting the emitted RUP proof. All local
  training proofs currently verify.

## Changelog

- Initial scaffold: placeholder solver returned `UNKNOWN`.
- Replaced placeholder with a self-contained C++ watched-literal CDCL solver
  and VeriPB RUP proof logging.
- Fixed root-level backtracking so restarts preserve level-0 implications.
- Fixed learned-clause insertion to preserve the asserting literal rather than
  sorting learned clauses; this was critical for `ssa2670` performance.
- Added root failed-literal probing with RUP unit logging.
- Tuned probing to avoid bulk binary implication logging; this reduced proof
  size and local runtime while keeping 42/42 local training proofs valid.
- Updated `meta.json` with solver description and techniques.
