# Solver Notes

## Formula Notes

- The visible train split is the `genurq` family from the SAT 2003 handmade
  benchmarks. The files are shuffled, so variable numbers and clause order
  cannot be interpreted directly.
- Grouping clauses by their sorted absolute variable set reveals the encoding:
  almost all blocks contain exactly `2^(k-1)` clauses over `k` variables
  (`k` in 2..5), and the forbidden assignments in each block have the same
  parity. These are complete CNF encodings of XOR equations.
- Each visible satisfiable instance has exactly one anomalous five-variable
  half relation: it still has 16 clauses forbidding 16 of 32 assignments, but
  it differs from an XOR table by one swapped assignment. The solver treats
  this as a small explicit relation instead of forcing it into the linear
  system.
- Visible local results after implementation:
  - genurq4,5,6,7,8,15,25,30 all return verified SAT models.
  - Largest visible instance (`n=3622`, `m=17076`) solves locally in about
    0.03 seconds in this container.

## Techniques Used

- Parse sanitized DIMACS only; comments are ignored and not required.
- Recover structural blocks from sorted absolute literal sets.
- For each block with exactly half of all assignments forbidden:
  - classify as XOR if every forbidden assignment has the same parity;
  - otherwise keep a compact relation table of allowed assignments.
- Solve the XOR core with a from-scratch dense bitset Gaussian elimination over
  GF(2). Free variables are set to false.
- Enumerate variables appearing in non-XOR relation blocks when their union is
  at most 28 variables, add those choices as linear unit equations, solve the
  XOR system, then check the original CNF.
- Soundness gate: never exits 10 unless the complete model satisfies every
  parsed clause. No UNSAT claims are made.

## Remaining Things To Try

- Add a VeriPB proof path for inconsistent pure XOR systems. This would require
  a reliable proof translation, likely via parity or cutting-planes derivations.
- Investigate the hidden `*.mis-*.debugged.cnf.xz` variants from the baseline
  results. The current solver should return UNKNOWN if their block structure is
  not a small XOR-plus-relation instance.
- If hidden relation blocks are larger or more numerous, replace the current
  simple relation enumeration with backtracking plus incremental linear
  consistency checks.

## Known Limitations

- The solver is not a general SAT solver and intentionally rejects structures
  that are not complete half-table blocks of size at most 20 variables.
- UNSAT is never claimed because there is no checked VeriPB proof generator.
- Relation enumeration is capped at 28 distinct variables to avoid accidental
  exponential blowups on unsupported inputs.

## Changelog

- Initial scaffold: placeholder UNKNOWN solver.
- 2026-05-06: Recovered the block-level XOR structure from visible genurq
  instances.
- 2026-05-06: Implemented C++ structural detector, GF(2) elimination, bounded
  relation enumeration, complete model printing, and final CNF model checking.
- 2026-05-06: Updated metadata and README for first broker submission.
- 2026-05-06: First broker submission solved 8 train instances and returned
  UNKNOWN on the two hidden MIS/debugged instances, with no invalid results.
- 2026-05-06: Tried a deterministic local repair fallback for unsupported or
  structurally unresolved SAT cases. Broker run still solved 8 and returned
  UNKNOWN on both MIS/debugged cases, but spent 570 seconds on each, so the
  submitted solver behavior was reverted to the faster structural-only path.
