# Solver Notes

## Formula Notes

The family is made of SAT encodings for closed knight tours / Hamiltonian cycles
on `n x n` knight graphs. The useful structural signatures are:

- Sparse `hcp_d*` formulas expose two exact-one support families over legal
  directed knight arcs. After collapsing complementary size-2 exact-one clauses,
  the support hypergraph has `2*n^2` nodes and `8*(n-1)*(n-2)` directed arc
  variables.
- `hcp_CP*` formulas expose one support family plus `n^2` dense length-`n^2`
  clauses. Some sizes include additional CP symmetry/order constraints over
  auxiliary variables. Unit-propagation conflicts on rejected tours often reduce
  to small no-goods over selected corner or near-corner arcs, but the accepted
  canonical-tour condition is not fully decoded yet.
- `hcp_bij16` has `2*n^2` dense length-`n^2` clauses. Primary variables form a
  complete bipartite position-square matrix, and heavy binary blocks recover the
  position cycle.
- `knight_*` formulas are distance-pruned position-square encodings. The large
  clauses expose all square constraints and all nontrivial position constraints;
  the missing first/last two position domains appear as two positive binary
  clauses and two positive 11-clauses. Ternary transition clauses recover the
  directed position path and the knight graph with the fixed corner removed.
- `hcp_r*` is a huge reachability/transitive-closure encoding. The visible
  `r26` file has 919562 variables and 103690720 clauses; its exact-one knight
  support can be recovered from all length 4/6/8 clauses, the 16 length-3
  clauses whose variables occur in that support, and 8 of 9 positive binary
  support candidates. The remaining order/reachability layer is not assigned.
  The current solver deliberately returns `UNKNOWN` for very large clause
  counts instead of risking a slow or memory-heavy reconstruction.

## Techniques Used

The solver does not use a SAT solver. It recovers the high-level graph from
support clauses, labels the unlabeled graph with Weisfeiler-Lehman color
refinement plus a bounded backtracking isomorphism search, then maps a
precomputed constructive closed knight tour for the board size to CNF variables.
For `knight_*`, it reconstructs the pruned position-square matrix, orders the
position groups from transition clauses, labels the square groups as the knight
board minus the fixed corner, and assigns the recovered matrix directly.

For supported encodings it assigns all primary successor or position variables,
runs deterministic unit propagation to fill auxiliary variables, sets remaining
irrelevant variables false, and checks every original clause before printing
`SATISFIABLE`.

## Remaining Things To Try

- Decode CP symmetry/order units for the CP sizes currently returning
  `UNKNOWN`. For `CP20`, the corner orientation assumptions alone still
  propagate consistently, but full tours hit no-goods involving distant corner
  arcs and then larger order constraints.
- Add direct reachability-variable assignment for `hcp_r*` instead of skipping
  very large formulas. A naive all-false or all-true fill of non-primary
  variables leaves roughly 1.65M or 0.99M clauses unsatisfied respectively on
  visible `r26`, mostly binary clauses in the reachability/order layer.
- Replace precomputed tour data with an in-code constructive generator if
  future targets include board sizes above the current table.

## Known Limitations

- No UNSAT proof path is implemented; unsupported structures return `UNKNOWN`.
- Tour data is included for even board sizes 12 through 30.
- The solver is intentionally conservative: if unit propagation conflicts or
  the final full assignment does not satisfy the CNF, it exits `UNKNOWN`.

## Changelog

- Implemented structural support extraction for sparse directed-edge HCP
  encodings and model construction from a closed knight tour.
- Added dense `bij` reconstruction using long-clause incidence, heavy binary
  position-cycle detection, square graph isomorphism, and unit alignment.
- Added partial CP support for instances whose auxiliary constraints accept the
  generated tour.
- Added sparse-HCP retries over board dihedral symmetries and tour reversal so
  symmetry/order units are less likely to reject an otherwise valid tour.
- Added an early `UNKNOWN` cutoff for very large non-`bij16` formulas to avoid
  spending time parsing unsupported reachability encodings.
- Added full assignment self-checking before SAT output.
- Updated build metadata and added generated closed-tour data include.
- Added a structural decoder for distance-pruned `knight_*` position-square
  encodings, including recovery of the omitted small position domains, directed
  position path, fixed-corner square graph, and a small auxiliary repair search.
- Local 2026-05-09 pass after the `knight_*` decoder solves 9/15 visible train
  instances: all `hcp_d*`, all `knight_*`, `hcp_CP18`, and `hcp_bij16`; the
  unsupported CP variants and huge reachability instance return `UNKNOWN`.
- Extended the small residual auxiliary search to sparse HCP models as well as
  CP/knight position models, while still requiring a full original-CNF model
  check before SAT output.
- Added deterministic 2-opt mutations of the constructive closed tour for
  sparse directed-edge HCP instances, giving the model builder many alternate
  Hamiltonian cycles when a size-specific symmetry/order layer rejects the
  first tour.
- 2026-05-09: Broker feedback exposed held-out sparse misses on `hcp_d16` and
  `hcp_d24`; added a deterministic multi-step 2-opt walk for sparse HCP
  instances after the single-mutation neighborhood is exhausted, bounded by a
  540 second per-instance guard.
- 2026-05-09: Added the same deterministic 2-opt tour-neighborhood retry to
  `hcp_CP*` model construction. This remains conservative because every
  candidate is completed by propagation/search and checked against the original
  CNF before SAT output; visible CP14/16/20/22/26 still return `UNKNOWN`.
- 2026-05-09: Analyzed visible `hcp_r26`: recovered the 1352 support groups
  structurally, confirmed they bipartition into two 676-node knight copies, and
  documented that the unsolved part is the large auxiliary order/reachability
  assignment rather than the primary tour support.
