# Solver Notes

## Formula Notes

- Target family is FPGA routing.
- A large subfamily is one-hot route choice under a hidden variable polarity:
  every non-binary clause is an at-least-one route group and every binary
  clause forbids a pair of selected routes. After recovering the polarity,
  each conflict edge is a perfect matching between group values, and the
  matchings are globally consistent with ordinary graph coloring on all
  checked `*_gr_rcs_*`, `homer*`, and `aloul*` samples.
- Another subfamily is bit-vector encoded route coloring. Clauses of size
  `2 * ceil(log2(width))` repeat on the same variable support; each support is
  the union of two recovered bit groups and each signed clause forbids one
  pair of group values. Some variants also contain binary side constraints.
- The `*_gr_2pin_*` / SAT04-style bit-vector formulas with cross-group binary
  side clauses encode color-permutation equality edges compactly. Contracting
  those equality components exposes the same overfull-clique conflict cores as
  the smaller `*_gr_2pinvar_*` encodings.
- `bart*` and several small `2pin` cases are currently handled mostly by the
  fallback CDCL engine, not by a complete high-level decoder.

## Techniques Used

- One-hot detector:
  - recovers the selected-literal polarity without comments or filenames;
  - partitions variables by non-binary route clauses;
  - verifies binary clauses are perfect matching conflicts;
  - maps matching permutations to global graph-color labels.
- One-hot SAT:
  - tries deterministic local graph coloring and bounded DSATUR;
  - for large recovered one-hot instances, skips the old exponential
    route-domain DFS after the graph-color heuristic fails and lets the CDCL
    fallback try the original CNF instead;
  - maps colors back to original literals;
  - checks every original CNF clause before printing SAT.
- One-hot UNSAT:
  - finds cliques larger than the recovered width;
  - emits a VeriPB proof: derive color-wise at-most-one constraints from
    binary conflicts by cutting planes, sum them with route at-least-one
    clauses, and conclude contradiction.
- Bit-vector UNSAT:
  - recovers bit groups from repeated support co-occurrence;
  - finds an overfull clique in the group conflict graph;
  - extracts only clauses over the clique variables;
  - runs the in-house CDCL solver on that core and logs RUP clauses. The proof
    is checked against the full formula because the core clauses are a subset
    of the original CNF.
- Contracted bit-vector UNSAT:
  - classifies binary side-pair constraints as permutation equalities when
    each row/column has exactly one allowed color;
  - contracts equality components with a union-find that carries color
    permutations;
  - finds overfull cliques in the quotient conflict graph;
  - extracts the original CNF clauses over all bit groups in the clique
    components and proves that core with the same CDCL/RUP logger.
- Bit-vector SAT:
  - a guarded permutation-coloring local search can map contracted equality
    components back to raw bit-vector assignments, then the residual DPLL fills
    unsupported variables and the full CNF model is checked before printing
    SAT.
- Fallback:
  - a small from-scratch CDCL solver with watched literals, 1-UIP learning,
    VSIDS-style activity, restarts, phase saving, and VeriPB RUP logging.
- Experimental gated path:
  - `ENABLE_BV_CSP=1` still enables the older uncontracted bit-vector CSP SAT
    local search after the new contracted path fails. It remains disabled by
    default because it is slower and has not solved additional visible cases.

## Current Local Results

- Parent provenance: seeded from `agent-fpga-routing-structural-guarded`
  (`d4b034ae34b894892e2b08a8bb84cb0a87d0a693a6341a3e16d79144b9f0fe9e`,
  parent eval `eval_20260508T205813Z_53e0736b`, parent val score 17/19).
- On the 66 visible training files, with a 45s local cap per instance after
  the contracted-clique update:
  - `sat`: 29
  - `unsat`: 37
  - local timeouts/unknown/crashes: 0
  - new contracted cores for `k2fix_gr_2pin_w9`, SAT04-351, and SAT04-352
    were checked locally with `veripb --cnf`.
- Prior broker run `eval_20260508T203615Z_e49d6f91` completed with no invalid,
  crash, OOM, or timeout statuses before this update. Visible status counts were:
  - `sat`: 30
  - `unsat`: 42
  - `unknown`: 6
- Newly solved relative to the baseline-visible hard cases include:
  - `homer17.shuffled.cnf.xz` via one-hot clique PB proof;
  - `k2fix_gr_2pinvar_w8` / shuffled SAT04 w8 bit-vector clique cores;
  - `k2fix_gr_2pinvar_w9` and one shuffled w8/w9 mixed bit-vector core.
  - `vda_gr_rcs_w8.shuffled.cnf.xz`: after the large one-hot DFS guard, the
    fallback CDCL finds and internally verifies a SAT model quickly;
  - `c880_gr_rcs_w6.shuffled.cnf.xz`: after the same guard, fallback CDCL
    derives an UNSAT proof that was verified locally with VeriPB.

## Remaining Things To Try

- A structural SAT coloring path for `vda_gr_rcs_w8` would still be cleaner
  than relying on fallback CDCL.
- Add direct PB proof generation for one-hot graph-coloring UNSAT cases
  without a clique larger than the width; `c880_gr_rcs_w6` is now solved by
  CDCL/RUP, but a structural proof would likely be smaller.
- Make the bit-vector group recovery faster for very large mixed encodings and
  extract multiple clique candidates when the first core is not enough.
- Generate a direct VeriPB cutting-planes proof for contracted bit-vector
  cliques instead of using CDCL/RUP on the extracted core; this could reduce
  proof checking time on larger hidden instances.
- Improve the contracted permutation-coloring SAT local search. It is sound
  because every candidate model is CNF-checked, but it is still heuristic and
  slower than the proof path on visible side-equality UNSAT cases.
- Decode `bart*` structurally instead of relying on CDCL.

## Known Limitations

- UNSAT is only claimed when a VeriPB proof is produced. If high-level
  detection or proof construction is uncertain, the solver falls back or
  returns UNKNOWN.
- The bit-vector clique path is conservative and currently targets repeated
  largest-support binary table constraints plus clean permutation-equality
  side constraints; it does not claim arbitrary bit-vector CSP
  unsatisfiability.
- The fallback CDCL engine is intentionally simple compared with modern SAT
  solvers and is mainly a proof-producing safety net.

## Changelog

- Replaced the scaffold with a C++20 solver built by the provided Ice Lake
  compile flags.
- Added analysis tools:
  - `tools/profile.py` for clause/polarity/exact-one summaries;
  - `tools/recover_bit_groups.py` for bit-vector group recovery experiments.
- Implemented one-hot polarity recovery, graph-color mapping, SAT model
  construction, and verified clique UNSAT VeriPB proofs.
- Implemented a from-scratch watched-literal CDCL fallback with RUP proof
  logging.
- Added bit-vector repeated-support recovery and clique-core CDCL proof
  generation for compact 2-pin encodings.
- Generalized bit-vector clique recovery to allow binary side constraints.
- Added a stricter CDCL wall-clock guard so unsupported hard cases return
  UNKNOWN before the broker timeout instead of being killed.
- Added a large-one-hot DFS guard. If graph-color reconstruction fails on a
  large one-hot instance, the solver now falls through to the verified CDCL
  fallback instead of spending the whole run in exponential domain search.
  This locally solves `vda_gr_rcs_w8` as SAT and `c880_gr_rcs_w6` as UNSAT
  with a VeriPB-checked proof.
- Added an experimental bit-vector CSP SAT decoder, gated behind
  `ENABLE_BV_CSP`, and left it disabled for submission after local tests
  showed it slowed easy 2-pin cases without solving the large no-clique
  SAT04-style cases.
- Submitted broker job `eval_20260508T203615Z_e49d6f91`; it completed cleanly
  with 30 SAT, 42 UNSAT, and 6 UNKNOWN visible statuses.
- Added `tools/analyze_bv_csp.py` to inspect recovered bit groups, table
  matching constraints, binary side-pair density, and permutation signatures.
- Added contracted bit-vector clique UNSAT proofs. Binary side constraints
  with one allowed color per row/column are treated as color-permutation
  equalities, contracted, and overfull quotient cliques are proved by running
  the in-house RUP logger on the corresponding original CNF core. This locally
  solves the three previously timed-out visible bit-vector cases:
  `k2fix_gr_2pin_w9`, SAT04-351, and SAT04-352.
- Enabled the guarded contracted bit-vector SAT decoder by default while
  leaving the older uncontracted CSP search behind `ENABLE_BV_CSP`.
