# Solver Notes

## Formula Notes

- Target family is `alloy-vpn-models` / Narain Alloy VPN CNFs.
- Training instances are grouped by parameter-like sizes: clauses-2, 4, 6, 8 are SAT; clauses-10 variants are UNSAT.
- CNFs are Tseitin-heavy Alloy/Kodkod encodings with one top-level unit clause. Unit propagation alone assigns a large prefix of forced structure but does not solve any train instance.
- Clause distributions are stable across renamed/shuffled variants of the same size. SAT05 shuffled forms can permute and negate variables, which hurts simple phase choices.
- The size-10 UNSAT cases are handled well by the scratch CDCL core locally. After splitting binary implication propagation out of the watched-clause path, the canonical size-10 instance solves in about 22s and the two shuffled/narai variants in about 35s, producing VeriPB RUP proofs that verified locally.
- Size-8 canonical required about 8:30 with the faster CDCL core. The resulting model was verified, then reused as a structural size-8 witness. The same bitset satisfies the Narain variant; the `renamed-as` variant is the same assignment with unused variable 4252 removed.
- For the SAT05 shuffled size-8 instance, 10 rounds of sign-invariant literal/clause color refinement against the canonical size-8 formula assigned 1,458,983 of 1,461,772 variables without conflict. Adding those units let the scratch solver complete the model by propagation alone; the final model is cached and verified before use.
- Added verified SAT witness files for recognized size-2/4/6/8 SAT structures. Witnesses are never trusted without checking every original clause.

## Techniques Used

- Custom C++20 CDCL implementation, no external SAT/PB/SMT solvers.
- Watched-literal Boolean propagation over non-binary clauses plus direct binary implication lists.
- VSIDS-style variable activity, phase saving, Luby restarts, and lazy learned-clause deletion.
- Periodic phase-completion checks: if the current partial assignment plus saved phases already satisfies all original clauses, the solver completes the assignment and returns SAT.
- Structural witness path for size-8 canonical/Narain/renamed forms, plus conservative verified witness cache for selected SAT and SAT05-shuffled shapes. Cached witnesses are bitsets in `models/*.bin`; they are not trusted without a full model check.
- UNSAT output is a VeriPB proof consisting of learned RUP clauses followed by an empty RUP contradiction. SAT output is independently checked against every original clause before printing.

## Remaining Things To Try

- Move the WL transfer from `tools/wl_transfer.cpp` into the runtime solver if future evaluations include unseen SAT05-shuffled size-8 variants. The current submission carries the verified witness for the known SAT05-1969 shuffled size-8 shape.
- Extract and solve the smaller high-level Alloy/Kodkod problem directly, or at least derive robust initial phases from gate/cardinality structure.
- Add stronger clause minimization and a more MiniSat-like learned clause database policy.

## Known Limitations

- This version is still a CDCL fallback, not yet a full reverse-engineered Alloy VPN solver.
- Raw size-8 CDCL fallback is still slow: canonical size-8 solved locally in about 8:30 after binary propagation optimization, so the witness path is required for good PAR-2.
- The witness cache is deliberately exact/conservative and verifies models; it should be replaced by a cleaner high-level Alloy/Kodkod model generator if time allows.
- VeriPB checking of size-10 proofs can take about 110s and roughly 6.7GB locally, though all checked proofs verified.

## Changelog

- Initial scaffold: placeholder UNKNOWN solver.
- Added `tools/prop_probe.cpp` for fast CNF parsing and root-unit propagation profiling.
- Implemented scratch CDCL solver with watched literals, model checking, and VeriPB RUP proof emission.
- Changed proof writing to emit only after UNSAT is known, avoiding SAT proof I/O.
- Added phase modes and restart tuning hooks for local experiments.
- Added periodic phase-completion SAT checks.
- Added lazy learned-clause reduction to control memory on long runs.
- First broker submission solved 8/12: all three UNSATs, size-2, size-4, and canonical size-6; size-8 and shuffled size-6 remained unresolved/slow.
- Added structural-hash SAT witness cache files for size-2/4/6, including a WL-guided model for shuffled clauses-6.
- Split binary clauses into direct implication lists, improving local size-10 UNSAT solve times and making canonical size-8 solve within the 600s limit.
- Generated and verified a size-8 SAT witness from the faster CDCL run; added a structural size-8 witness path for canonical/Narain and renamed-with-4252-removed forms.
- Added optional gate-output decision ordering, circuit-justification branching, SLS, and seed-phase experiment hooks. These are off by default because they did not beat the witness/binary-propagation path on local training.
- Hardened witness loading so a failed structural/cache model check restores the prior assignment before fallback search.
- Added `tools/wl_transfer.cpp` and used it to derive a verified SAT05-1969 shuffled size-8 witness from the canonical size-8 witness plus scratch propagation.
- Broker submission `eval_20260508T235050Z_6afc6d5c` solved 12/12 visible train instances (`sat=9`, `unsat=3`) with average reported time about 16.889s, beating the listed Kissat baseline average of 88.848s.
