# Solver Notes

## Formula Notes

The target is the `minimum-disagreement-parity` family.  Training instances use
variables `1..N` as the primary parity assignment, variables `N+1..3N` as
disagreement/score bits, then XOR-tree auxiliaries and a cardinality suffix.

The formula starts with a long prefix of complete CNF encodings of XOR equations:

- 8 four-literal clauses encode one arity-4 XOR equation.
- 4 three-literal clauses encode one arity-3 XOR equation.
- 2 binary clauses encode one arity-2 XOR equation.

After the XOR prefix, the first suffix clauses have the shape
`-(N+2) -aux`, `-(N+1) -aux`, `(N+2) (N+1) aux`; this recovers `N` without
using the filename.  The suffix is a sequential/cardinality encoding over the
`2N` score bits.  Unit propagation on synthetic score vectors shows accepted
true-count thresholds of 7 for `N=28`, 8 for `N=32`, and 9 for `N=36` on the
SAT-side training encodings.

## Techniques Used

The solver is SAT-only and never claims UNSAT.

1. Parse the XOR prefix structurally and build GF(2) equations.
2. Eliminate while preferring non-primary pivots, so every score bit becomes an
   affine function of the primary variables.
3. Convert the score system into a nearest-codeword problem: find a score vector
   of weight at most the suffix threshold that lies in the affine image.
4. Use dependency rows of the score matrix as a parity-check system and solve
   the low-weight syndrome problem with meet-in-the-middle enumeration.  Several
   deterministic pseudo-random score permutations are tried to avoid unlucky
   unbalanced splits.
5. Solve for a primary assignment, evaluate XOR auxiliaries, complete remaining
   suffix variables with unit propagation/greedy choices, then validate every
   original CNF clause before printing `SATISFIABLE`.

## Local Results

After the 2026-05-07 implementation, local validation on `/data/train` solved
all 15 labeled SAT instances with valid models and returned `UNKNOWN` for the
remaining 13 instances.  No invalid models were observed.  Typical local times:

- `N=28` SAT: about 0.03 seconds.
- `N=32` SAT: about 0.3 to 0.75 seconds.
- `N=36` SAT: about 0.7 to 1.0 seconds.
- Standard unsupported UNSAT cases: usually below 5 seconds; malformed/simplified
  XOR-prefix cases return almost immediately.

This beats the supplied `kissat-sc2024` baseline of 3 solved training instances.

## Remaining Things To Try

- Add support for the simplified XOR clauses seen in a few UNSAT-side training
  formulas.  This may improve structural coverage, though it will not count
  without an UNSAT proof.
- Design a VeriPB proof for the low-weight syndrome nonexistence result.  A proof
  path would need to certify the parity-check derivation and all error-weight
  cases compactly enough for `veripb`.
- Replace the random-permutation meet-in-the-middle heuristic with a full bounded
  nearest-codeword search if larger hidden instances require complete SAT-side
  coverage.

## Known Limitations

- UNSAT is not certified; inconsistent or unsupported cases return `UNKNOWN`.
- The detector expects complete XOR CNF blocks in the prefix.  It conservatively
  rejects encodings with shortened/subsumed XOR clauses.
- The low-weight search is tuned for the observed `N <= 36`, `2N` score bits,
  and threshold near `N/4` regime.

## Changelog

- Initial scaffold: placeholder C++ solver returned `UNKNOWN`.
- 2026-05-07: Implemented structural XOR-prefix recovery, GF(2) affine score
  extraction, syndrome meet-in-the-middle SAT search, full model reconstruction,
  and original-clause validation.  Updated metadata and notes for broker
  submission.
