# Solver Notes

## Formula Notes

- The target is the `hypertree-decomposition` family. The CNFs match the
  pure-improved SAT encoding from the Schidler/Szeider hypertree ordering
  characterization.
- The first block detects `n`: it has `3 * C(n,2)` binary clauses tying compact
  order variables `o(i,j)` to an allocated `n x n` arc matrix `a(i,j)`.
- Variable layout is recovered structurally, without comments or filenames:
  `o`: `C(n,2)` variables; `a`: `n*n` variables; `w`: `n*m` edge-cover
  variables; `p`: `n*(n-1)` permission variables; remaining variables are
  per-row totalizer auxiliaries for `sum_e w(i,e) <= W`.
- `m` is detected from the first pure subset-clause stride
  `-a(i,j) -p(i,j) -w(i,e) w(j,e)`. `W` is detected from the header variable
  count using `aux_per_row = W*m - W*(W+1)/2`.
- Incidence is recoverable from binary clauses `p(v,r) OR -w(r,e)`, meaning a
  selected cover hyperedge forces permission for every vertex it contains.
- `p(v,r)` is a permission relation, not exact membership. The solver computes
  the least permission closure from order, selected covers, and arc-path
  propagation, then adds the extra permitted transitive arcs required by the
  improved pure encoding.
- Most Kakuro instances are 2-regular as hypergraphs: every encoded vertex is
  in exactly two original hyperedges. The dual graph has original hyperedges as
  vertices and original vertices as dual edges.
- The `2bitcomp_5.hg_20` training instance is not 2-regular; the current solver
  conservatively returns `UNKNOWN` for that regime.

## Techniques Used

- Conservative structural detector for the pure-improved hypertree-ordering CNF.
- For 2-regular instances, the solver builds the dual graph and runs a
  det-k-decomp-style recursive separator search. Boundary obligations are
  solved as small vertex-cover/set-cover subproblems over dual edges.
- The resulting hypertree decomposition is converted to the LEO assignment by
  ordering original vertices by the decomposition node where they are forgotten
  and assigning each row the cover of that node.
- The solver computes `o/a/w/p`, completes the truncated unary totalizers by
  prefix counts, then checks every original CNF clause before returning SAT.
- UNSAT is never claimed; unsupported structures, failed searches, and failed
  verification return `UNKNOWN`.

## Local Results

- On the available 42-file local train split, a 20-second per-instance sweep
  solved 31 SAT instances. A longer run solved `Kakuro-easy-148.hg_7` in about
  49 seconds, bringing the observed local solved count to 32/42.
- Known fast examples after decompression:
  `Kakuro-easy-048.hg_4` solves in about 0.1s, `Kakuro-easy-089.hg_4` in about
  0.5s, and most width >= 5 Kakuro instances in under 1s.
- Several width-4 instances exhaust the current separator search and return
  `UNKNOWN`. One sampled hard width-4 case returned `UNKNOWN` after about 76s.

## Remaining Things To Try

- Add alternative separator orderings for the hard width-4 Kakuro instances.
  Current ordering prefers balanced splits; some instances may need less
  balanced separators to expose the right normal-form decomposition.
- Generalize the recursive decomposition search beyond 2-regular hypergraphs
  or add a separate strategy for `2bitcomp_5.hg_20`.
- Design a compact VeriPB proof strategy before attempting any UNSAT claims.
- Reduce memory in failed deep searches; successful instances are fast, but
  exhaustive width-4 failures can exceed 1GB during local testing.

## Known Limitations

- The solver depends on structural encoding detection and 2-regularity, not on
  filenames or hashes. Non-matching formulas return `UNKNOWN`.
- The implementation prints SAT only after full CNF verification, including
  totalizer auxiliaries. Any model construction or verification failure falls
  back to `UNKNOWN`.
- No behavior depends on comments; the evaluator strips comments and the solver
  ignores them.

## Changelog

- 2026-05-08: Added CNF profilers and block detectors under `tools/`.
- 2026-05-08: Recovered variable layout and hypergraph incidence extraction.
- 2026-05-08: Documented why generalized cover-width witnesses are not enough
  for sound SAT output.
- 2026-05-08: Added decomposition-first prototypes
  `tools/test_td_order.py` and `tools/detk_proto.py` for semantic checking.
- 2026-05-08: Replaced the `UNKNOWN` seed with a C++ 2-regular Kakuro solver
  using recursive separators, LEO conversion, permission/arc closure,
  totalizer completion, and full-model verification.
