# Solver Notes

## Formula Notes

- The visible training split is a Hanoi planning family. The solver does not
  use filenames or comments.
- Factored `hanoi4/5/6` instances match:
  - time steps `T = 2^n - 1`
  - state variables `(T + 1) * n * (n + 3)`
  - action variables `T * (n + 2 * (n + 3))`
  - wide clauses: `T` clauses of size `n` and `2T` clauses of size `n + 3`
- For `hanoi6`, the 63 size-6 clauses and 126 size-9 clauses are disjoint
  action-choice groups. Their group graph has 63 connected triples.
- Each triple contains one disk-choice group and two object-choice groups.
  The smaller disk/object edge is the source group; the larger edge is the
  destination group. The source/destination object groups are tied by `source
  != destination` binary clauses.
- Destination-effect state literals match the next step's source-precondition
  state literals, giving a comment-free time-order path over the action
  triples. The first precondition layer and final postcondition layer are
  identified by unit clauses.
- The `n+3` object domain is `n` disk objects plus three pegs. Initial units
  expose a single tower, so disk order, the start peg, and the two spare pegs
  can be labeled structurally. Final units identify the goal peg.
- The `hanoi6_on` variant has the same factored action skeleton plus extra
  variables and clauses. The direct action decoder still applies; watched
  propagation then fills the extra variables.

## Techniques Used

- From-scratch watched-literal propagation.
- CDCL-style first-UIP learning with VSIDS-like activity bumps.
- Direct factored-Hanoi reconstruction:
  - detect exact-one wide action groups without comments or filenames
  - connect action triples into time order through state literals
  - label disks/objects from initial and final unit layers
  - generate the canonical `2^n - 1` Hanoi move sequence
  - assert every action-choice literal before propagation/search
- Structural action detection: variables appearing in clauses wider than 3 are
  treated as Hanoi action-choice variables, get a large initial activity boost,
  and use the polarity from their wide clause as initial phase.
- Restart intervals are selected from CNF structure:
  - factored `hanoi6` with positive-biased wide literals: short restarts
  - factored `hanoi6` with non-positive-biased wide literals: medium restarts
  - `hanoi5`: longer restarts
  - other detected shapes: default medium restarts
- SAT output is conservative: the solver checks every original clause against
  the final complete assignment before printing `s SATISFIABLE`.

## Remaining Things To Try

- Emit all state and auxiliary assignments directly instead of relying on
  watched propagation after action reconstruction.
- Add clause database reduction and better branching data structures.
- Derive VeriPB proofs for unsupported UNSAT cases if such instances appear.
- Broaden the detector if future Hanoi variants use non-canonical start/goal
  towers, a different number of pegs, or a non-minimal horizon.

## Known Limitations

- The solver never prints `UNSATISFIABLE`; root contradictions and exhausted
  unsupported searches return `UNKNOWN`.
- The direct path only supports the detected canonical factored Hanoi shape:
  `T = 2^n - 1`, `n` disk choices, `n+3` object choices, a single initial
  tower, and a single final tower on a distinct goal peg.
- If detection fails or the direct assumptions do not lead to a checked model,
  the solver falls back to the inherited guided CDCL search and may return
  `UNKNOWN` on unsupported structures.
- SAT output remains conservative: every original clause is checked against
  the complete assignment before printing `s SATISFIABLE`.

## Changelog

- Replaced the placeholder solver with a C++ watched-literal SAT engine.
- Fixed CDCL backtracking so root units and the requested kept decision level
  are preserved correctly.
- Added model self-checking before any SAT exit.
- Identified the wide-clause Hanoi action structure and added action-variable
  activity/phase guidance.
- Tuned restart selection from wide-clause counts and polarity balance.
- Updated metadata and README for broker submission.
- Added a direct Hanoi action-plan decoder that reconstructs time order,
  disk/object labels, start/goal pegs, and the canonical move sequence from
  CNF structure alone.
- The direct path asserts all action-choice literals and then uses watched
  propagation/CDCL only to complete state and auxiliary variables. Local train
  times dropped from roughly 0.06/1.1/1.7/18.5/35.2s to about
  0.004/0.009/0.036/0.022/0.022s with checked SAT models.
