Research-Stack/GEMINI.md

# Gemini CLI Instructions for Research Stack

You are working in the **Research Stack** project. This project is a formally verified, formally grounded, and hardware-native stack. You MUST adhere to the strict operating rules defined in the `AGENTS.md` files.

## Primary Mandate
**Lean is the source of truth.** All core logic belongs in `0-Core-Formalism/lean/Semantics/`. Python, Rust, and Verilog are shims/extraction targets only.

## Key Constraints (from AGENTS.md)
- **NO FLOATS:** Use `Q0_16` (pure fraction) or `Q16_16` (mixed) fixed-point. Floats are BANNED in core logic.
- **NO NEW DEPENDENCIES:** Do not add libraries without explicit human approval.
- **NO BROAD REFACTORING:** Only change code that is broken, violates invariants, or cannot be extracted.
- **STATISTICAL RIGOR:** All statistical claims must hit **6.5σ** (preferred) or **6σ** (acceptable). **5σ** is the absolute floor.
- **GIT HYGIENE:** Never use `git add .`. Always use explicit file lists.
- **RECOVER LEGACY INFORMATION:** Use this exact trigger to revive archived info from cornfield branches.
- **SI UNITS:** All physical and compression claims must use SI base units.
- **WOLFRAM ALPHA:** Verify all mathematical formulas with Wolfram Alpha when possible.

## Verification Workflow
1. **Plan:** Outline the Lean implementation and the required theorems/#eval witnesses.
2. **Act:** Implement in Lean first. Update shims only as extraction targets.
3. **Validate:** Run `lake build` in `0-Core-Formalism/lean/Semantics/`.
4. **Receipts:** All infrastructure or storage changes must produce a machine-readable receipt.

## Terminology
- Use **Sidon labels**, **BraidStorm**, **eigensolid**, **scar**, **receipt**.
- Refer to `AGENTS.md` for the full glossary.

## Sub-Agents & Tools
- Use `storage_agent.py` for restic/Garage/rclone operations.
- Use `gen_step_part` etc. for CAD work in `5-Applications/text-to-cad/`.
- Use `podman exec research-stack` for container-bound tasks (Lean builds, WGSL).

## References
- Root Contract: `AGENTS.md`
- Documentation/Lean Strict Rules: `6-Documentation/docs/AGENTS.md`
- Infrastructure: `4-Infrastructure/AGENTS.md`
- CAD: `5-Applications/text-to-cad/AGENTS.md`

<!-- BEGIN ContextStream -->
### When to Use ContextStream Search:
✅ Project is indexed and fresh
✅ Looking for code by meaning/concept
✅ Need semantic understanding

### Bosonic Tensor Network Simulator Scaling & Limits:
- **Theoretical Entropy Power Law**: Single-mode marginal entropy is \(H_K(N) \approx \log_2(N) - \frac{0.7213}{K}\) bits. Joint Fock-space capacity is \(H_{\text{joint}}(N, K) = \log_2 \binom{N+K-1}{K} \approx K \log_2(N) - \log_2(K!)\) bits.
- **Physical Target Scale**: The core system (Burgers representation graph in `burgers_chaos_game.py`) has exactly \(N = 22\) modes.
- **RTX 4070 SUPER Hardware Limits**:
  - **VRAM Ceiling (\(O(N^2)\))**: Usable limit of 10 GB VRAM is reached at \(N = 50000\) modes (\(\text{VRAM}(N) = N^2 \times 4\) bytes).
  - **Time Complexity (\(O(N^3)\))**: The dense graph (edge probability \(p=0.4\)) has a spectral radius scaling as \(\lambda_{\max} \approx 0.4 N\). Thus, RK4 step count scales as \(S \propto N\), making total duration cubic (\(T(N) = c \cdot N^3\) with \(c \approx 1.085 \times 10^{-10}\text{ s/mode}^3\)).
  - **Max Scale at 1-Hour Limit**: \(N \approx 32000\) modes (\(T \approx 55\) mins).
- **Comparison to Perceval SLOS**: Perceval compiles the full Fock-space and OOMs at \(N \ge 150\). Our GPU solver reaches \(N = 15000\) (verified) and \(N = 50000\) (limit) representing a \(>330\times\) increase.
- **Scaling Recommendation**: To scale beyond \(N = 50000\) or drop time complexity to \(O(N)\), transition the adjacency matrix to a sparse representation (keeps \(S\) constant and matrix mults \(O(N)\)).

---
<!-- END ContextStream -->