# Solver Notes

## Formula Notes

- The target family is the SAT Competition 2020 `ncc` crafted benchmark set.
- The generator builds formulas from many all-sign-permutation UNSAT cores.
  A core with `m` variables contains one clause for every assignment. The
  clauses are split into shorter CNF chains and several cores share the same
  chain variables.
- In the 3-SAT transformed instances with many combined cores, the linking
  stage leaves a distinctive long clause per recovered core. Its length is
  `3*m + 1`: the first `3*m` literals are the payload assignment to block, and
  the final literal is the link/output literal.
- Assigning each long-clause payload literal false and the final link literal
  true produces a consistent partial model on the SAT members seen locally.
  Unit propagation fills many of the split-chain auxiliary variables. A short
  stochastic repair pass then completes the remaining auxiliaries.
- The `n=2` high-N instances have only two long clauses, but the same payload
  orientation is still useful. On the SAT members, BCP plus residual 2-SAT
  completes the model quickly; on the known UNSAT sparse members, the oriented
  payload hits a contradiction and the solver returns `UNKNOWN`.
- The first long clause index matches `core_count * (2^m - 1) * 3 * split_count`
  on sampled instances, confirming that each linked combined core has one
  deleted sign-pattern group and one long clause whose final variable is a
  link/output literal.

## Techniques Used

- Direct DIMACS parsing with no dependency on comments or filenames.
- Long-clause structural detector for the linked NCC core payload clauses.
- Deterministic partial assignment and unit propagation.
- Residual 2-SAT completion for cases where assigning the recovered original
  variables collapses the split chains to binary implications.
- From-scratch stochastic local search repair over the original CNF.
- Odd-degree variables are used only as a conservative runtime signal for
  extended SAT repair budgets on paired SAT gadgets; they do not affect
  correctness or model construction.
- Full independent clause verification before returning `SATISFIABLE`.
- No UNSAT answers are emitted; unsupported or unsolved instances return
  `UNKNOWN`.

## Remaining Things To Try

- Generate VeriPB proofs for UNSAT core families by replaying the known
  all-sign-permutation resolution proof through the split-chain variables.
  A prototype RUP proof for the `n=3, m=16` sparse UNSAT case derived the
  three link units with a row-by-row DPLL proof, but the resulting 413-432 MB
  proof timed out in local VeriPB checks at 900 seconds, both with and without
  immediate deletion of child learned clauses. A more compact CP or PB proof is
  needed before enabling UNSAT output.
- Replace stochastic repair with a deterministic chain-filling pass per
  recovered combined core.
- Recover and solve the link DAG explicitly instead of assuming the SAT
  long-clause orientation.

## Known Limitations

- The solver is SAT-only. It never prints `UNSATISFIABLE`.
- It uses the structural hint whenever at least two long clauses are recovered
  and the long-clause payload assignments are internally consistent.
- The repair phase is incomplete. If it does not find a verified full model
  within the time budget, the solver exits `UNKNOWN`.

## Changelog

- Initial scaffold replaced with a C++ solver and Ice Lake build path.
- Added metadata describing the NCC core reconstruction approach.
- Added direct DIMACS parser, occurrence lists, stochastic local search, and
  full model verification.
- Added long-clause payload detector and unit propagation to seed the model.
- Restricted sparse long-clause cases to `UNKNOWN` to avoid local-search
  overruns on high-N instances.
- Capped the repair budget and re-enabled sparse short-clause long-hint cases
  to target the small `n=2` SAT members without causing broker timeouts.
- Added a residual 2-SAT pass and fast sparse-hint contradiction handling, so
  unsupported `n=2` UNSAT cases no longer fall into slow repair search.
- Added profiling tools under `tools/` for clause-length, degree, long-clause,
  and residual-hint analysis.
- Loosened the long-clause detector to accept two-core high-N instances. This
  makes `n=2` SAT members solve through BCP plus residual 2-SAT while the known
  sparse UNSAT members still return `UNKNOWN` after a detected contradiction.
- Switched the repair budget to a structural policy: odd-degree SAT-gadget
  signals get a longer stochastic-repair window, while ordinary cases keep a
  shorter window. Every SAT output is still checked against the original CNF.
- Submitted `eval_20260509T051441Z_b42ba4f4`: visible train result was
  `sat=8`, `unknown=8`, no invalids. This matches the VBS solved count and is
  faster on solved instances.
- Prototyped sparse UNSAT link-unit RUP proofs for the `n=3, m=16` case.
  Generation was fast, but local VeriPB did not finish within 900 seconds, so
  the proof path was not added to the solver.
