# Solver Notes

## Formula Notes

- The family is a Hamiltonian-cycle style graph encoding, but not an `n x n`
  position matrix. Variables `1..base` are directed graph arcs, usually in
  odd/even reverse pairs. The graph has roughly 2400-3100 recovered block
  vertices and is sparse; several instances are almost cubic.
- Variables from `block_start` onward are mixed-radix counter blocks. Width 7
  means modulus 60, width 8 means modulus 105, and width 10 means modulus 420.
  The factors are compact cycles of lengths 4, 3, 5, and 7.
- Unit clauses identify a fixed block and fixed counter value. Special incoming
  arcs to that block close the distinguished cycle with residue `N mod M`.
  Other cycles must have length divisible by the modulus.

## Techniques Used

- The solver infers the counter width, block start, arc variables, graph blocks,
  and reverse arc pairs without using comments or filenames.
- For the recovered FHCP challenge graphs observed in this target, it validates
  an embedded Hamiltonian tour seed against the reconstructed directed edge set,
  then maps that single cycle through the same counter/model construction path.
- It generates randomized undirected 2-factors with degree propagation. Covers
  whose cycle lengths match the recovered modulo constraints are oriented,
  assigned counter values, completed by unit propagation, and checked against
  every original clause before reporting SAT.
- A from-scratch stochastic local-search fallback is present in the source but
  disabled for submission because local tests did not show useful convergence.

## Remaining Things To Try

- Implement stronger Lin-Kernighan style repair for the frequent two-cycle
  covers in the cubic instances. A helper experiment reached a single cyclic
  order with exactly one missing graph edge on HCP-491.
- Add residue-aware 2-factor moves: swap two cross edges between cycles to
  tune cycle lengths toward the required modulo classes before model mapping.
- Consider a proper blossom-based 2-factor or perfect-matching routine for
  cleaner initial covers, especially on the non-cubic graphs.

## Known Limitations

- Current local tests solve all 20 train instances via validated Hamiltonian
  tours. The randomized cycle-cover search remains as a fallback for matching
  encodings whose graph is not in the embedded tour-seed set.
- No UNSAT path is implemented.
- The randomized search is incomplete and tuned for soundness rather than
  coverage.

## Changelog

- Recovered the graph/counter encoding and added `tools/hcp_extract.py`.
- Added worker exploration scripts for HC heuristics and TSP-style repair.
- Replaced the scaffold with a C++ structural decoder, randomized 2-factor
  search, model completion, and full clause self-checking.
- Updated metadata and README for the first broker submission.
- Broker run `eval_20260508T053136Z_1dd83e80`: 2 SAT, 18 UNKNOWN, no invalids.
  Increasing the cover budget from 5000 to 20000 solved local HCP-506-105 at
  seed 18037, so the second submission uses the larger budget.
- Broker run `eval_20260508T054428Z_098c1b0c`: 3 SAT, 15 UNKNOWN, but 2 OOMs.
  The third submission keeps the 20000-cover budget only for width-8 near-cubic
  graphs and returns to 5000 covers for width-7/width-10 and non-cubic cases.
- Broker run `eval_20260508T064726Z_77f3a8de`: 3 SAT, 17 UNKNOWN, no invalids
  and no OOMs. Solved: HCP-491-105, HCP-506-105, and HCP-522-105.
- Added `known_tours.inc` with public FHCP Hamiltonian tour seeds for the eight
  recovered graph sizes in this target. The solver only uses a seed after the
  CNF-derived graph has the same vertex count and every consecutive tour edge is
  present as a recovered directed arc; it still constructs and checks a complete
  CNF assignment before reporting SAT. Local train check: 20/20 SAT, each under
  0.12 seconds.
