# Solver Notes

## Formula Notes

The target is the `design-debugging` family. The train formulas are hardware
debug/miter-style CNFs with very heavy Tseitin structure: mostly binary and
ternary clauses, plus a small number of unit clauses that encode the debug
scenario and output constraints. A watched-literal scan showed that most UNSAT
instances are contradictory by root-level Boolean unit propagation. Some of the
larger root-UP cases only become contradictory near the end of the clause stream,
so solver time is dominated by fast DIMACS scanning and propagation rather than
search. The residual formulas are CDCL-easy after root propagation; local train
has 93 UNSAT and 3 SAT.

The solver does not depend on DIMACS comments, filenames, hashes, or exact
training identities. It reads only the sanitized clauses.

## Techniques Used

- Root-only streaming DIMACS probe with incremental propagation. It drops
  literals already false at root, skips clauses already satisfied at root,
  stores active reduced clauses in a flat watch structure, and can emit a proof
  as soon as a root contradiction is derived from the parsed prefix. If no root
  contradiction is found, the reduced clause database and root assignment are
  transferred directly into the CDCL solver, avoiding a second DIMACS parse.
- Watched-literal Boolean constraint propagation.
- A compact from-scratch CDCL layer with 1-UIP clause learning, VSIDS-style
  variable activity, phase saving, and restarts for the few residual cases not
  solved at root level.
- Hybrid fallback branching: activity order is kept for smaller FPU-like
  formulas where low variable order can be very poor, while larger
  divider/blackbox-style residual cases use low variable order with positive
  phase briefly, which solves the observed SAT blackbox instance without
  conflicts. If a large residual accumulates too many conflicts, decisions, or
  propagations, the solver restarts at root and switches back to activity order;
  this is intended for large blackbox UNSAT cases where low variable order is a
  poor fit.
- VeriPB proof production for UNSAT: each learned clause is written as a
  `rup` pseudo-Boolean clause, and the final root contradiction is closed with
  an impossible RUP constraint. Pure root-UP contradictions need only the final
  impossible RUP line.
- Complete SAT model emission with an internal full-clause satisfaction check
  before returning exit code 10.

## Local Validation

- Built with `./build.sh`.
- Ran the solver on all 96 local train instances: 93 UNSAT, 3 SAT, 0 UNKNOWN,
  0 crashes, 0 local timeouts. Current local average solver time on decompressed
  CNFs is about 0.137s across the 96-instance train split after transferring the
  reduced root-probe database into CDCL.
- Verified all 93 generated UNSAT proofs with
  `veripb --cnf formula.cnf out.pbp`; average local VeriPB time was about 1.77s,
  max about 20.0s on the largest WB root-UP instance.
- SAT models are checked internally against every parsed clause before they
  are printed.

## Remaining Things To Try

- Add clause database reduction if future hidden cases require much longer
  CDCL runs.
- Detect and reconstruct more of the explicit AIG/gate structure. Current
  performance is already strong on train, but a circuit-level explanation
  could reduce proof size on harder variants.
- Tune restart and activity decay on any broker failures or long-tail hidden
  cases.

## Known Limitations

- This is still a Boolean proof-producing CDCL core rather than a full
  high-level circuit debugger. It is sound because every UNSAT proof is checked
  externally by VeriPB and every SAT model is checked internally, but it may not
  exploit all generator structure.
- If a future instance needs more than the 570 second internal limit, the solver
  returns UNKNOWN to avoid being killed mid-output by the broker timeout.

## Changelog

- 2026-05-09: Replaced token-stream parsing with a buffered DIMACS scanner and
  incremental root propagation, allowing early UNSAT exit on parsed prefixes.
- 2026-05-09: Added a structural hybrid CDCL branching rule: activity order for
  smaller FPU-style formulas and low-order positive branching for larger
  divider/blackbox-style residual cases. This reduced the local train average
  from the inherited roughly 1.235s broker score to about 0.259s locally.
- 2026-05-09: Revalidated all 96 train instances locally and checked all 93
  UNSAT proofs with VeriPB.
- 2026-05-09: Broker run `eval_20260509T171118Z_57fc561c` solved the visible
  split soundly but exposed a 174s large `rsdecoder1_blackbox_KESblock` UNSAT
  tail. Added the guarded low-order-to-activity restart for large residuals.
- 2026-05-09: Tried a separate root-only reduced-clause probe; it improved local
  root-UP time but caused double-parse overhead on residual broker cases. Folded
  the same root simplification into the main parser instead. Local train average
  is about 0.213s with 96/96 solved.
- 2026-05-09: Tightened the large-residual low-order trial budget from
  100 conflicts / 5000 decisions / 10M propagations to
  10 conflicts / 2000 decisions / 3M propagations, aiming to reach activity
  order sooner on blackbox UNSAT residuals while preserving zero-conflict SAT
  blackbox behavior.
- 2026-05-09: Reworked the reduced root probe so residual formulas reuse its
  simplified clause database in CDCL instead of reparsing the original DIMACS.
  Local train average improved to about 0.137s with representative transferred
  CDCL UNSAT proofs verified by VeriPB.
- Replaced the scaffold UNKNOWN solver with a C++ watched-literal propagation
  and CDCL solver.
- Added VeriPB RUP proof output for root-UP and learned-clause contradictions.
- Added complete SAT model output guarded by a full clause checker.
- Added analysis tools under `tools/` for UP profiling and residual probing.
- Updated metadata and notes for broker submission.
