Add README.md

README.md

@@ -0,0 +1,109 @@
+# SnapKitty — Integrity DAG + Sovereign Computation Research
+
+**One sentence:** A formally specified integrity DAG that gates every claim, proof, decision, and execution in an AI pipeline — plus experimental SUBLEQ-based attention routing and formally verified entropy bounds.
+
+---
+
+## What This Is
+
+This repository is the research synthesis of the SnapKitty project. It contains:
+
+1. **The ICP-DAG** — a working governance DAG enforced by both Answer Set Programming and MUMPS, with 10 integrity invariants. Nothing executes without passing the graph.
+
+2. **SUBLEQ Attention** — an experimental replacement of softmax attention where activation vectors become SUBLEQ programs, integer routing replaces probability distributions.
+
+3. **Formally proved results** — Jordan fixed-point commutativity (0 sorry), entropy bound H < 0.20 nats (0 sorry), Fibonacci dimension recurrence.
+
+4. **Quantum swarm** — classical multi-agent inference system with real quantum entropy from ANU QRNG. Not a quantum computer. Precisely defined in `docs/QUANTUM_SWARM.md`.
+
+5. **Topological quantum computing** — Lean 4 formalizations of Fibonacci anyons, braid group, and classical simulations. Pentagon/hexagon axioms are incomplete. See `docs/TOPOLOGICAL_QUANTUM.md`.
+
+---
+
+## Quick Start
+
+```bash
+# Verify the entropy bound (Python stdlib only)
+cd sovereign-entropy-theorem
+python python/verify_entropy.py
+
+# Install the EntropyGovernor LogitsProcessor
+pip install snapkitty-entropy[hf]
+
+# Run the ICP governance DAG tests
+# (requires GT.M or Caché MUMPS installation)
+mumps -run TEST^ICP-DAG
+
+# Run the SUBLEQ VM tests
+cd DEVFLOW-FINANCE/snapkitty-wasm
+cargo test
+
+# Run the Resonance ISA VM tests
+cd snapkitty-resonance-isa
+cargo test
+```
+
+---
+
+## What Actually Works
+
+| Component | Status | Tests |
+|-----------|--------|-------|
+| SUBLEQ VM (Rust/WASM) | ✓ Working | 4 passing |
+| Resonance ISA VM (Rust) | ✓ Working | 3 passing |
+| ICP-DAG MUMPS | ✓ Working | TEST entry |
+| ICP-DAG ASP | ✓ Spec | Requires Clingo |
+| ERE quality filter (JS) | ✓ Working | — |
+| EntropyGovernor (Python) | ✓ Working | — |
+| Jordan proof (Lean 4) | ✓ 0 sorry | `lake build` |
+| Entropy bound (Lean 4) | ✓ 0 sorry | `lake build` |
+| Fibonacci anyon sim (Rust) | ✓ Working | Passing |
+| Quantum WASM (44KB binary) | ✓ Working | — |
+| Braid B₃ access control (Rust) | ✓ Working | 4 passing |
+| SUBLEQ attention (J) | ✓ Runs | — |
+| Braid synthesis (Lean 4) | ✗ All sorry | — |
+| HybridQuantumSAT | ✗ Stub | — |
+
+---
+
+## What Has Not Been Benchmarked
+
+- SUBLEQ attention vs. softmax: **no benchmark**
+- Latency comparison: **no benchmark**
+- Hallucination rate improvement: **no benchmark**
+- FLOPs comparison: **no benchmark**
+
+Do not cite this repository as evidence of performance improvements without running these benchmarks first.
+
+---
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| `docs/REPOSITORY_INVENTORY.md` | Complete evidence map — every algorithm, DAG, and quantum component |
+| `docs/ARCHITECTURE.md` | Architectural synthesis — what the common structure is |
+| `docs/QUANTUM_SWARM.md` | Precise definition of the quantum swarm (for researchers) |
+| `docs/TOPOLOGICAL_QUANTUM.md` | What is established vs. experimental in the TQC work |
+| `docs/RESEARCHER_EXPLANATION.md` | Q&A for a quantum computing or AI researcher |
+
+---
+
+## License
+
+Apache-2.0 (harness code and documentation)
+BSL-1.1 / AGPL-3.0 / MPL-2.0 (research core)
+Patent Pending — Bel Esprit D'Accord Irrevocable Trust EIN 42-697643
+
+---
+
+## Citation
+
+```bibtex
+@software{snapkitty2026,
+  author = {Ali Parr, Ahmad and Westerhoff, Jessica},
+  title = {SnapKitty: Integrity DAG and Sovereign Computation Research},
+  year = {2026},
+  url = {https://github.com/SNAPKITTYWEST/snapkitty-open-source}
+}
+```