# Solver Notes

## Formula Notes

- The family is a GF(2) tensor-rank encoding. Rank terms contain three factor
  vectors. For each tensor cell and rank term, the CNF has a signed 3-input AND
  gate for `u_i & v_j & w_k`.
- Tensor cell constraints are XOR chains over the rank-term AND outputs, with
  one unit clause per tensor entry. Some instances apply signed variable
  permutations, so the solver reconstructs gates structurally and does not use
  comments, filenames, or contiguous variable ranges.
- Extra clauses encode rank-term ordering/symmetry comparators. A recovered
  decomposition must be placed into rank slots in an order accepted by those
  comparator clauses.
- Observed local groups:
  - `5x5x5, r=12`: SAT in the train split; now solved by this solver.
  - `4x5x5, r=9` and `4x4x4, r=8`: expected UNSAT in available labels. The
    solver currently returns UNKNOWN because no VeriPB proof generator is
    implemented.

## Techniques Used

- Signed AND-gate detection from one 4-clause plus three binary implications.
- XOR-chain detection by grouping four ternary clauses over the same variables
  and recovering the parity equation.
- Rank component recovery from the complete tripartite co-occurrence graph of
  AND-gate inputs.
- A matrix-slice-space algorithm for supported 5x5x5 instances. The five tensor
  slices span a subspace `W` of `GF(2)^25`; the solver searches for a subspace
  containing `W` whose internal rank-one matrices span `W` with dimension at
  most 12.
- A deterministic beam over quotient residues of all rank-one 5x5 matrices.
  Once a rank-one basis is found, Gaussian elimination gives each tensor term's
  first-mode coefficient vector.
- Comparator-aware term placement: adjacent slot/pair feasibility is checked by
  watched-literal propagation on the original CNF, then a small path search
  orders the recovered terms.
- Final SAT output is accepted only after the completed assignment satisfies
  every original clause.

## Remaining Things To Try

- Add a proof-producing UNSAT path for `4x4x4` and `4x5x5`. A CDCL fallback was
  tested on a representative `4x4x4` instance and reached the 590 second
  internal cutoff without a refutation, so substantial proof-oriented work is
  still needed.
- Convert the matrix-space UNSAT search into a checkable VeriPB certificate.
  This is the most promising way to beat baselines that solve UNSAT cases.
- Tune the beam search further if larger supported SAT instances appear. The
  current 5x5x5 train instances solve in about 5.4-6.8 seconds locally.

## Known Limitations

- The solver is intentionally SAT-only for supported `5x5x5, r=12` tensors.
  It returns UNKNOWN for unsupported structures and for UNSAT cases.
- The beam search is specialized to small GF(2) tensors with matrix slice size
  at most 6x6 and is only enabled for the observed 5x5x5 rank-12 regime.
- No behavior depends on comments, filenames, hashes, or memorized answers.

## Changelog

- Replaced the placeholder with a structural tensor-rank reconstructor.
- Added the matrix slice-space beam search for 5x5x5 rank-12 SAT instances.
- Added comparator-aware term ordering and CNF model completion/verification.
- Added `tools/prototype.py` with the Python reconstruction/search prototype
  used during reverse engineering.
- Updated metadata and build notes for broker submission.
