# Solver Notes

## Formula Notes

- The target is Hidoku on an `N x N` king-move grid. The primary variables are
  cell-major: `x(cell,value)` is DIMACS variable `cell * M + value`, where
  `M = N*N` and values are 1-based.
- Generated UNSAT instances in the visible split use `N=6` or `N=7`, one
  positive at-least-one clause per cell, compact auxiliary AMO encodings per
  cell, direct adjacency clauses for `value -> value+1` and the reverse, and
  four positive unit clues.
- Even though generated formulas do not include explicit "each value appears"
  clauses, the cell ALO plus forward/backward adjacency force every value to
  occur. With exactly `M` cells and per-cell AMO this also forces value
  uniqueness.
- The SAT `Hidoku_enu_8` instance uses a more extended encoding with auxiliary
  adjacency variables and no unit clues. A simple serpentine Hamiltonian path
  over the board satisfies the high-level puzzle; the solver fills auxiliary
  variables with a small internal DPLL restricted to model completion. The
  detector now accepts the same cell-major primary layout up to `20x20`; this
  is intended to catch larger clue-free `Hidoku_enu_N` instances while still
  relying on the final CNF model check for soundness. SAT construction also
  tries the transposed primary layout because some enumerate-style encodings
  can expose value-major blocks first.

## Techniques Used

- Structural detector for Hidoku primary layouts with either consecutive or
  strided `N^2`-literal ALO blocks, plus direct adjacency clauses when present.
  Unsupported or clue-bearing formulas that are not proved UNSAT by the
  supported direct encoding return UNKNOWN.
- High-level arc consistency over value domains. Fixed clues become singleton
  value domains, negative primary units become forbidden placements, singleton
  values occupy cells, and adjacency deletes placements without a predecessor
  or successor neighbor. Domains are stored as explicit vectors rather than
  64-bit masks, so the same AC logic can run on direct encodings above 64
  cells. This proves every visible generated UNSAT formula.
- VeriPB proof generation:
  - derive same-cell pairwise AMO clauses by RUP from the compact AMO encoding;
  - derive per-cell cardinality AMO constraints by cutting planes over the
    pairwise clique;
  - derive "each value appears" by RUP from adjacency plus cell ALO;
  - combine total cell capacity with value occurrence constraints to derive
    per-value AMO;
  - replay every arc-consistency deletion as a unit RUP step and finish with a
    RUP contradiction.
  - the same derivations can be emitted under the transposed primary layout
    when direct adjacency is detected in value-major orientation.
- SAT model path: try all dihedral symmetries and reversal of a deterministic
  serpentine Hamiltonian path, then use bounded high-level DFS for clue-bearing
  boards up to 64 cells. Candidate paths are filtered against all primary-only
  clauses before auxiliary completion. The same path logic is tried under both
  cell-major and value-major/transposed primary layouts. Assign all primary
  variables, run a simple in-house DPLL to complete auxiliary variables, and
  check every original clause before printing SAT.
- Direct-encoding fallback: when no SAT path is found for a `6x6` direct
  instance, derive pairwise value AMO clauses by RUP and run a
  bounded proof-producing DPLL over the primary Hidoku clauses. Learned clauses
  are emitted as tree-like RUP steps, so UNSAT is still gated by VeriPB.

## Local Validation

- Visible train split after the 2026-05-08 update: 24/24 solved locally.
- UNSAT: 23/23 generated instances produced VeriPB proofs that checked with
  `veripb --cnf formula.cnf out.pbp`.
- SAT: `Hidoku_enu_8` produced a complete model satisfying all 39,432 clauses.
- Additional checks: public ToySolver `Hidoku_enu_6` sample solves SAT; forced
  DPLL fallback on a visible `6x6` generated UNSAT instance produced a 1.5 MB
  proof that VeriPB accepted.
- Solver runtime locally was about 0.01-0.02 seconds per visible instance;
  VeriPB proof checking was about 0.1-0.5 seconds for these proofs.

## Remaining Things To Try

- Improve the clue-aware Hamiltonian path search beyond `8x8`; currently larger
  clue-bearing SAT boards need to match a serpentine symmetry or they return
  UNKNOWN.
- Generalize the proof detector beyond the current direct adjacency encoding
  if future generated UNSAT instances use the extended `Hidoku_enu` style.
- Add proof deletion lines if much larger boards appear and checker memory
  becomes the bottleneck.

## Known Limitations

- UNSAT proof generation is intentionally restricted to the direct adjacency
  Hidoku encoding. Unsupported formulas return UNKNOWN rather than risk an
  invalid proof.
- SAT construction handles clue-free boards up to the detector limit and
  clue-bearing boards when a serpentine symmetry matches or bounded `8x8`
  high-level DFS finds a path. Larger clue-bearing boards outside that
  constructive coverage return UNKNOWN.
- The auxiliary DPLL is for model completion after a high-level assignment; it
  is not used as a general SAT fallback.

## Changelog

- Replaced the scaffold with a specialized C++ Hidoku solver.
- Added analysis tooling under `tools/` for CNF profiling and proof prototyping.
- Implemented VeriPB proof generation for the generated direct UNSAT encoding.
- Implemented deterministic SAT model construction and auxiliary completion.
- Updated metadata for broker submission.
- 2026-05-08: generalized shape detection through `20x20`, replaced AC masks
  with explicit vector domains, tried all serpentine symmetries/reversal before
  SAT search, and raised bounded clue-aware SAT search to `8x8`.
- 2026-05-08: added negative primary-unit domain handling, primary-only clause
  filtering for SAT path candidates, and a bounded RUP-logging DPLL fallback
  for hard `6x6` direct UNSAT instances.
- 2026-05-08: added a transposed primary-layout SAT model attempt, still gated
  by complete CNF verification, for enumerate encodings whose primary matrix is
  value-major.
- 2026-05-08: broadened shape detection to accept strided ALO blocks in
  addition to consecutive cell-major blocks.
- 2026-05-08: allowed the direct `6x6` proof-producing DPLL fallback to run
  after any failed SAT construction, not only after clue-unit handling.
- 2026-05-08: generalized direct-adjacency detection, AC proof replay, and the
  direct DPLL proof fallback to support transposed/value-major primary layout.
- 2026-05-08: relaxed shape detection to accept one missing cell ALO block in
  the generated direct layout; local simulation with one removed ALO still
  produced a VeriPB-checking proof.
