# Solver Notes

## Formula Notes

The target is a SIMON-like cryptographic key-recovery family.  For `r` rounds
the CNF has `160*r + 128` variables and `544*r + 192` clauses, with exactly
128 units, `128*r + 64` binary clauses, and `416*r` ternary clauses.

Each round is a 32-bit Feistel step:

`L' = ((L <<< 1) & (L <<< 8)) ^ (L <<< 2) ^ R ^ round_key`, `R' = L`.

Variables `65..128` are the fixed initial state.  The final state is fixed by
unit clauses on the last 64 variables.  Variables `1..32` are the primary key
word.  Variables `33..64` are a second key word constrained by binary
equivalences to a permutation of `1..32`.  Early rounds use the primary key
word and later rounds use the permuted word; the solver recovers this from the
round clauses rather than from filenames or comments.

## Techniques Used

- Structural detector for the exact clause/variable shape and endpoint units.
- Recovery of the `33..64` to `1..32` key permutation from binary clauses.
- Recovery of which key half each round uses from the XOR output clauses.
- Exhaustive 32-bit key search using a direct word-level SIMON simulator.
- Complete CNF assignment reconstruction for all state, auxiliary, and key
  variables.
- Independent clause-by-clause model verification before printing
  `SATISFIABLE`.

## Remaining Things To Try

- Add a cryptanalytic or meet-in-the-middle search to reduce scan time on
  UNSAT/no-witness instances.
- Derive a VeriPB proof strategy for exhaustive misses.  The current solver
  returns `UNKNOWN` when no key is found because no checkable proof is emitted.
- Add AVX-512 or bitsliced candidate search if PAR-2 becomes more important
  than solved count.

## Known Limitations

- The solver is intentionally specialized to this recovered SIMON32 family.
  Shape mismatches return `UNKNOWN`.
- UNSAT is not claimed.  Exhaustive no-key cases return `UNKNOWN` after the
  full scan, preserving soundness but leaving possible solved count on the
  table if proof generation becomes feasible.
- Search order is numeric over the primary key, so high-valued keys take longer.

## Changelog

- Replaced scaffold with a C++ detector, SIMON recurrence simulator, exhaustive
  key search, assignment mapper, and internal CNF verifier.
- Added support for numeric hard instances by recovering the permuted second
  key word from binary equivalence clauses.
- Added local analysis scripts under `tools/` for CNF profiling, endpoint
  extraction, and local batch testing.
