# Solver Notes

## Formula Notes

The training split is a random 4-ary linear system over GF(3), encoded as CNF.
All 16 train instances have 1200 Boolean variables and 21040 clauses:

- 400 ternary high-level variables, each represented by a one-hot Boolean
  triple.
- 1200 negative binary clauses plus 400 positive ternary clauses for the
  exactly-one constraints.
- 360 GF(3) equations.  Each equation touches four ternary variables and is
  encoded by the 54 forbidden assignments out of `3^4 = 81` possible tuples.

The solver does not use comments, names, hashes, or seed numbers.  It detects
the one-hot triples structurally and groups the remaining all-negative
4-clauses by their four high-level variable scopes.  A valid equation block
must contain exactly 54 distinct forbidden value tuples and fit a normalized
linear equation

```text
a0*x0 + a1*x1 + a2*x2 + a3*x3 = rhs mod 3
```

with `a0 = 1` and all other coefficients in `{1,2}`.

## Techniques Used

- Structural CNF detector for one-hot ternary domains and 54-clause GF(3)
  nogood blocks.
- Direct Gaussian elimination over GF(3), with free variables set to zero and
  back-substitution for a concrete high-level solution.
- Complete Boolean model reconstruction from the ternary values.
- Independent full CNF clause check before printing `SATISFIABLE`.

The current solver deliberately returns `UNKNOWN` for unsupported structures or
inconsistent GF(3) systems.  It does not emit VeriPB proofs yet, so it never
claims UNSAT.

## Remaining Things To Try

- Add a sparse/peeling GF(3) elimination path for much larger random instances.
  The dense byte matrix is trivial for the current 400-variable systems but
  would not be ideal for very large hidden deployments.
- Design a compact VeriPB proof strategy for inconsistent GF(3) systems, if the
  target later includes overconstrained UNSAT instances.
- Broaden value-label recovery if future encoders permute the three one-hot
  value literals per variable instead of using the natural sorted order.

## Known Limitations

- Supports the observed 4-variable GF(3) equation encoding only.
- Assumes DIMACS clauses are presented one clause per line, matching the
  training data and broker-generated sanitized files.
- UNSAT systems are classified as `UNKNOWN`, not solved.

## Local Validation

- `./build.sh` compiles with the required Ice Lake flags.
- All 16 training instances return exit code 10.
- An external Python checker parsed each emitted model and confirmed that all
  original CNF clauses are satisfied.

## Analysis Tools

- `tools/profile_gf3.py` summarizes the train split and checks the 54-clause
  equation-block signature.

## Changelog

- Replaced the placeholder solver with a structural GF(3)-SAT detector,
  Gaussian eliminator, model mapper, and full CNF model checker.
- Added `tools/profile_gf3.py` for repeatable CNF-family profiling.
- Updated metadata and notes for the first broker submission.
