Add docs/QUANTUM_SWARM.md

docs/QUANTUM_SWARM.md

@@ -0,0 +1,172 @@
+# Quantum Swarm — Precise Definition
+
+**For researchers.** No metaphors.
+
+---
+
+## What A Swarm Element Is
+
+A swarm element in SnapKitty is **a classical inference agent whose temperature parameter is seeded by real quantum entropy.**
+
+It is not:
+- A quantum particle
+- A quantum state in superposition
+- A topological charge
+- An anyon
+
+It is:
+- An HTTP call to an LLM inference backend (Ollama local or OpenRouter cloud)
+- Carrying a Born-collapsed temperature value derived from ANU QRNG entropy
+- Running concurrently with other elements (bounded by `VRAM_SLOTS = 6`)
+- Returning a quality-scored text response
+
+**Evidence:** `bob-orchestrator/bridges/quantum-swarm.mjs`
+
+---
+
+## Complete Definition
+
+```
+Swarm element:
+  id:           string (HKDF-derived from quantum seed slice)
+  model:        string (Ollama model identifier)
+  temperature:  float ∈ (0,1) (Born-collapsed from quantum entropy)
+  prompt:       string (the query)
+  result:       string | null (inference response)
+  quality:      float ∈ [0,1] (scored after completion)
+  seal:         hex string (SHA-256 WORM receipt)
+```
+
+**State transitions:**
+```
+PENDING → RUNNING (HTTP call dispatched)
+RUNNING → COMPLETE (response received)
+RUNNING → FAILED (timeout / error)
+COMPLETE → SEALED (WORM receipt written)
+```
+
+**Allowed transitions:** strictly forward — no back-edges, no loops.
+
+---
+
+## The Quantum Component
+
+The only genuinely quantum component is the entropy source.
+
+**Source:** Australian National University Quantum Random Number Generator API (ANU QRNG)  
+**Type:** Real vacuum fluctuations — physical quantum randomness, not pseudo-random  
+**Usage:** 512 bytes fetched once per swarm invocation  
+**Processing:**
+```
+ANU QRNG batch (512 bytes)
+  ↓
+HKDF-SHA256 key derivation (one derived key per agent)
+  → keys are orthogonal (non-correlated per HKDF construction)
+  ↓
+Normalize uint16 → [0, 1]
+Filter to thermal window [0.2, 0.8]
+  ↓
+Born collapse: uniform weights within window, select dominant
+  ↓
+Temperature parameter T ∈ (0.2, 0.8) for this agent
+```
+
+**What is quantum:** the 512-byte entropy batch (physical quantum measurement)  
+**What is classical:** everything after — HKDF, normalization, window filter, Born collapse, LLM inference  
+**What is classical metaphor:** "Born collapse" is an analogy to quantum measurement. It is implemented as a weighted average, not a quantum operation.
+
+---
+
+## What Connects Two Elements
+
+Nothing directly. The swarm topology is a **star** (not a mesh or lattice):
+```
+         ┌─ agent-0 ─┐
+         ├─ agent-1 ─┤
+Coordinator ─ agent-2 ─┤ → aggregated result → WORM seal
+         ├─ agent-3 ─┤
+         └─ agent-N ─┘
+```
+
+Elements do not communicate with each other. All communication passes through the coordinator. There are no entanglement-like correlations between agents beyond the shared HKDF key derivation from the same quantum seed.
+
+The HKDF derivation does mean all agents' temperatures are derived from the same physical quantum event. This is the only "connection" — shared quantum ancestry, not peer communication.
+
+---
+
+## What Is Measured
+
+The swarm measures:
+1. **Quality score** per agent response (evaluated by coordinator)
+2. **Consensus** by quality-weighted aggregation
+3. **WORM chain integrity** (every event sealed and verifiable)
+
+There is no quantum measurement in the physical sense. The word "measurement" in this codebase means scoring a classical text response.
+
+---
+
+## The 5-Role Variant
+
+`sov-kernel-monster/quantum-piper/swarm/swarm_coordinator.mjs`
+
+Five named agents:
+| Role | Model | Purpose |
+|------|-------|---------|
+| architect | Nemotron Ultra 550B (OpenRouter) | High-level reasoning |
+| delegate | Nemotron Super 49B | Coordination |
+| engineer | Qwen3-Coder 480B | Implementation |
+| witness | Gemma-3-27B | Independent review |
+| worker | Gemma3:12b (local Ollama) | Execution |
+
+Each role's temperature is derived from `qnu_temperature.mjs` (ANU QRNG source). Each role is a distinct classical inference process — the "roles" are prompt engineering, not quantum states.
+
+---
+
+## What Remains Invariant
+
+The WORM chain is invariant: SHA-256 append-only audit log. No event can be removed or modified after sealing. The quantum genesis seal (SHA-256 of the ANU entropy batch) anchors the entire chain to a physical quantum event.
+
+---
+
+## What The Swarm Visualization Represents
+
+The swarm visualization (if built) would show:
+- **Nodes:** individual inference agents (classical processes)
+- **Edges:** data flow from coordinator to agents and back
+- **Node color:** quality score (0=red, 1=green)
+- **Edge labels:** temperature value (quantum-derived)
+- **Root node:** quantum entropy source (ANU QRNG)
+
+Every visible node corresponds to an actual inference call. Every edge corresponds to an actual data transfer. No decorative quantum effects.
+
+---
+
+## Relationship To Topological Quantum Computing
+
+The swarm uses:
+- No braids
+- No anyons
+- No fusion rules
+- No topological protection
+
+The braid group work in SnapKitty (`BraidCompilation.lean`, `carry-agent/braid.rs`) is a **separate research track** — formal verification of Fibonacci anyon gate synthesis. It is not connected to the swarm at runtime.
+
+The word "quantum" in "quantum swarm" refers to the entropy source only.
+
+---
+
+## Summary: Classical vs. Quantum
+
+| Component | Classical | Quantum |
+|-----------|:---------:|:-------:|
+| Entropy source (ANU QRNG) | | ✓ (physical) |
+| HKDF key derivation | ✓ | |
+| Temperature assignment | ✓ | |
+| LLM inference | ✓ | |
+| Quality scoring | ✓ | |
+| WORM chain | ✓ | |
+| "Born collapse" aggregation | ✓ (metaphor) | |
+| Braid compilation (Lean) | ✓ (formal spec) | ✓ (theory) |
+| Fibonacci anyon sim | ✓ (classical) | |
+
+**One line:** The quantum swarm is a classical multi-agent system where temperature scheduling uses real quantum entropy from ANU vacuum fluctuations, and results are sealed in a quantum-genesis-anchored WORM chain.