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

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)).

---