Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
269 changes: 163 additions & 106 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,127 +1,184 @@
# Lambda SAT Middleware
# λSAT · the moving frame

> *A solver that carries its own proof, and knows which shape of hardness it's looking at.*

[![tests](https://github.com/jesusvilela/lambda-sat-solver/actions/workflows/tests.yml/badge.svg)](https://github.com/jesusvilela/lambda-sat-solver/actions/workflows/tests.yml)

A headless, math-aligned λ-logic middleware for Boolean satisfiability: it
transforms formulas into CNF, solves with **Kissat**, and **independently
certifies** every result — SAT by model replay, UNSAT by DRAT/LRAT proof
checking. On top of the solver sits an honest research program on the
*intrinsic structure of SAT hardness* (`docs/ladder/`).

This repository is deliberately pure: a Python library + CLI + a verifiable
research ladder. There is no web UI. Every claim in the research half is bound
to a test; the discipline that keeps it that way is written down in
[`docs/CHARTER.md`](docs/CHARTER.md) — read it first.

## Two halves

**1. The solver middleware** (`backend/`)
- Typed lambda DSL for composable solve/verify pipelines (`lambda_dsl.py`, `middleware.py`)
- **Lambda ⊗ SAT fusion** (`lambda_sat.py`): a Boolean lambda term is β-reduced,
projected into CNF carrying a *remainder* (provenance from each clause back to
its lambda node), and decided with a re-verified witness — the lambda DSL
situated as an object the solver consumes, not just a pipeline language
- Kissat integration with version-probed heuristic flags (`kissat_wrapper.py`)
- Independent certification: model replay for SAT, DRAT/LRAT for UNSAT (`proof_checking.py`)
- Portfolio solving (`portfolio.py`), rule-based heuristic policy (`policy.py`), structural profiling (`cnf_profile.py`)
- Three sound, engine-independent frames (one per obstruction characteristic):
implication/2-SAT (`binary_clause_check.py`), parity/GF(2) (`xor_extraction.py`),
counting/cardinality (`cardinality_check.py`)

**2. The hardness-lower-bound ladder** (`backend/complexity/`, `docs/ladder/`)
- Intrinsic, solver-independent invariants with an enforced contract each
(`complexity/invariants.py`, `complexity/contracts.py`)
- Two theorem-backed carriers (resolution width; Nullstellensatz degree),
a clean negative (cheap graph invariants don't carry hardness), and the
algebra-relative "shallow-frame" corollary — benchmarked on Kissat + CaDiCaL
(`docs/ladder/FRAME_BENCHMARK_REPORT.md`)

Start at [`docs/ladder/README.md`](docs/ladder/README.md) for the research
index and [`docs/ladder/CONTRACTS.md`](docs/ladder/CONTRACTS.md) for the
per-invariant promises.

## Correctness — the Trusted Computing Base

**Kissat is NOT in the TCB.** Every result is independently verified:

1. CNF parser (DIMACS)
2. Tseitin transformation (formula → equisatisfiable CNF)
3. Model checker (verifies SAT assignments against the original formula)
4. DRAT/LRAT proof checkers (verify UNSAT proofs with an independent tool)

So a wrong answer from the solver is caught, not trusted.

> **Strict certification depends on external proof tools being installed.** The
> three sound frames (implication / parity / counting) are self-certifying with no
> external dependency, but the **CDCL fallback's UNSAT certificate requires
> `drat-trim`** (DRAT; LRAT optional). The middleware enforces the presence of
> Kissat + a DRAT checker at startup in strict mode; without them, frame verdicts
> stay sound but the fallback certification degrades to best-effort. See
> `PUBLIC_RESEARCH_CLAIMS.md` for the full proven / measured / speculative ledger
> and the exact TCB boundary.

## Quick start
Headless. No web UI. No *trust-me*.

```bash
cd backend
pip install -r requirements.txt # Python 3.11+ (CI-tested on 3.11 & 3.12), numpy
# install Kissat and drat-trim — see BACKEND_README.md
A λ-logic middleware for Boolean satisfiability that **verifies every verdict it emits** —
SAT by model replay, UNSAT by an independent DRAT proof. On top of the solver sits a
research program on the *intrinsic shape of SAT hardness*: three sound algebraic frames, a
hyperbolic map of instance-space, and a game-theoretic dispatcher that reads an instance
before it searches.

python -m backend.cli examples/simple_sat.cnf --heuristic aggressive
python -m pytest tests/ # the full suite
Kissat is a tool here, not an authority. A wrong answer is **caught**, not believed.

---

## 何 · what it is

Two halves, one discipline.

**The solver** — a typed λ-DSL over sound frames and certified CDCL. Every result carries a
checkable certificate.

**The ladder** — an honest study of where hardness *lives*, each claim bound to a test.
The stance is written down in [`docs/CHARTER.md`](docs/CHARTER.md). *A name is not a proof.*
Read it first.

---

## 道 · the path

An instance is **described** before it is solved. The description — laws (conserved
invariants), relations (frame couplings), motions (its place on the hyperbolic fabric) —
tells the actor which move to play.

```mermaid
flowchart TD
F([formula]) --> C{"critic — does frame<br/>+ geometry suffice?"}
C -->|"yes · structured island"| FR["<b>frame</b><br/>2-SAT · GF(2) · counting<br/>~0 ms · sound by construction"]
C -->|"no · tunnel"| H{"critic —<br/>heavy tail?"}
H -->|"light"| S["<b>single arm</b><br/>one engine · no swarm"]
H -->|"heavy"| P["<b>portfolio</b><br/>cores-sized · seed-diversified<br/>first certified arm wins"]
FR --> V([verdict])
S --> V
P --> V
V --> Z["<b>certified</b><br/>frame-sound · DRAT · model replay"]
```

Docker (backend only):
Structure is decided instantly and for free — the frame *is* the certificate. Only the
structureless tail reaches a solver, and even then the answer is re-checked.

---

## 三面 · three frames, one fold

Each obstruction has one sound, engine-independent frame. What escapes all three is not a
failure of the map — it is a different *region*, and the map says so.

```mermaid
flowchart LR
subgraph ISLAND["island · structured"]
direction TB
I1["a <b>dominant strategy</b> exists"]
I2["the owning frame wins ~0 ms<br/>2-SAT · parity · counting"]
end
subgraph TUNNEL["tunnel · unstructured"]
direction TB
T1["<b>no</b> strategy dominates"]
T2["heavy-tailed runtime"]
T3["→ a <b>mixed strategy</b> (portfolio)"]
end
ISLAND -. "the decidability fold<br/>(a measured catastrophe wall)" .-> TUNNEL
```

```bash
docker build -t lambda-sat .
The fold is not a metaphor — it is a Fisher–Rao metric singularity, measured in the natural
coordinate ([`docs/ladder/FABRIC_NOTE.md`](docs/ladder/FABRIC_NOTE.md)). It is also the line
where game theory flips: on the island a *pure* strategy dominates; on the tunnel you must
*mix*. Same boundary, two languages.

---

## 構造 · the stack

Every layer is the same operator seen at a different scale. Fractal, self-similar, and
each verdict certified all the way down.

```mermaid
flowchart TD
ACAF["<b>ACAF</b> · adaptive actor-critic-ambigator-fuzzer"] --> META["<b>metasolver</b> · description-driven dispatch"]
ACAF --> MM["<b>meta-metasolver</b> · fractal seed-portfolio"]
META --> FR["<b>frame router</b> · 3 sound frames + Nelson-Oppen coupling"]
MM --> FR
META --> K["certified CDCL · Kissat / CaDiCaL"]
MM --> K
FR --> OBS(["<b>observer</b> — certify every verdict"])
K --> OBS

DESC["<b>the view from outside</b><br/>dynamics · fabric · hyperbolic model"] -.reads.-> ACAF
```

## Lambda pipeline example
- **frame router** (`frame_solver.py`) — the three frames + their coupling, refute-first.
- **metasolver** (`metasolver.py`) — reverts the dynamical description into a dispatch;
beats every single solver, **CryptoMiniSat included**, on a competition mix (49× PAR-2).
- **meta-metasolver** (`metametasolver.py`) — the minimax mixed strategy; **out-searches CMS
on random-3SAT** by collapsing its heavy tail (no CMS in the pool).
- **ACAF** (`acaf.py`) — sizes the mixed strategy to the cores; wins the structured tier by
a constructive certificate, the hard tier by an adaptive portfolio.
- **the view from outside** — `dynamics.py` (laws/relations/motions), `fabric.py` +
`fabric_model.py` (the hyperbolic instance-manifold), `observer.py` (the adjudicator).

---

## 証 · certification — the TCB

**Kissat is not in the trusted base.** The trusted core is small and independent:

1. DIMACS parser · Tseitin transform
2. model checker — replays SAT assignments against the original formula
3. DRAT checker (`drat-trim`) — replays UNSAT proofs with an independent tool

The three frames are **sound by construction** — no external checker, the derivation *is*
the proof. Only the CDCL fallback's UNSAT certificate needs `drat-trim`. Full
proven / measured / speculative ledger in
[`PUBLIC_RESEARCH_CLAIMS.md`](PUBLIC_RESEARCH_CLAIMS.md).

---

## 始 · quick start

```bash
cd backend
pip install -r requirements.txt # Python 3.11+ · numpy · pycryptosat
# install Kissat + drat-trim — see BACKEND_README.md

python -m backend.cli examples/simple_sat.cnf --heuristic aggressive
python -m pytest tests/ # 650 tests
```

```python
# λ cnf. solve(cnf, heuristic, budget)
pipeline = abs_('cnf',
effect('solve', var('cnf'),
literal({'branching': 'vsids', 'restarts': 'geometric'}),
literal({'time_limit': 30, 'memory_limit': 256})))
middleware.type_checker.check(pipeline) # CNF -> Result
result = await middleware.execute_pipeline(pipeline, cnf) # executed + verified
from backend.acaf import acaf_solve # the adaptive game-player
r = acaf_solve(formula) # frame · single · or portfolio
assert r.certified # every verdict carries its proof
```

## Project structure
---

## structure

```
lambda-sat-solver/
├── backend/
│ ├── lambda_dsl.py # typed lambda DSL (pipelines)
│ ├── lambda_sat.py # Lambda ⊗ SAT fusion (β-reduce → CNF + remainder)
│ ├── cnf_utils.py # DIMACS parsing + model verification
│ ├── kissat_wrapper.py # Kissat integration (flag-probed)
│ ├── proof_checking.py # DRAT/LRAT verification
│ ├── middleware.py # pipeline kernel
│ ├── portfolio.py # parallel portfolio solving
│ ├── binary_clause_check.py # sound 2-SAT UNSAT fast-path (implication frame)
│ ├── xor_extraction.py # sound GF(2)/XOR fast-path (parity frame)
│ ├── cardinality_check.py # sound pigeonhole fast-path (counting frame)
│ ├── complexity/ # the intrinsic-invariant ladder + contracts
│ ├── vdis/ # experimental hypercomplex heuristic research
│ ├── eval/ # generators + evaluation
│ └── tests/ # the full test suite
├── docs/
│ ├── CHARTER.md # stance & claim discipline (read first)
│ └── ladder/ # the hardness research + benchmarks + scripts
├── examples/ # example CNF files
├── Dockerfile # backend container
└── BACKEND_README.md # backend detail
backend/
frame_solver.py three sound frames + coupling (the router)
metasolver.py description-driven dispatch (beats CMS on the mix)
metametasolver.py fractal portfolio (out-searches CMS on the tail)
acaf.py adaptive actor-critic policy (cores-sized mixed strategy)
dynamics.py laws · relations · motions (the view from outside)
fabric.py the instance as a woven tapestry
fabric_model.py the family distributions, hyperbolic (Poincaré ball)
observer.py the adjudicator — certify, don't trust
lambda_sat.py λ ⊗ SAT fusion (β-reduce → CNF + remainder → decide)
{binary_clause,xor_extraction,cardinality}_check.py the three frames
complexity/ intrinsic hardness invariants + contracts
tests/ the full suite
docs/
CHARTER.md stance & claim discipline (read first)
ladder/ the research index, notes, and benchmarks
```

## References
Research index: [`docs/ladder/README.md`](docs/ladder/README.md).
Per-invariant promises: [`docs/ladder/CONTRACTS.md`](docs/ladder/CONTRACTS.md).

---

## references

- **Kissat** — Armin Biere (SAT solver)
- **DRAT/LRAT** — certified UNSAT proof formats
- **Ben-Sasson–Wigderson** (resolution width ↔ size); **Clegg–Edmonds–Impagliazzo** (polynomial calculus) — the ladder's theorem anchors
- **Kissat** · **CaDiCaL** — Armin Biere · **CryptoMiniSat** — Mate Soos
- **DRAT / LRAT** — certified UNSAT proof formats
- **Gomes–Selman** — heavy-tailed runtime & portfolios · **von Neumann** — the minimax theorem
- **Ben-Sasson–Wigderson** (width ↔ size) · **Clegg–Edmonds–Impagliazzo** (polynomial calculus) — the ladder's anchors

## License
## license

MIT — see `LICENSE`.
See [`LICENSE`](LICENSE).
Loading
Loading