# AGENTS.md — SilverSight Operating Contract **Principle:** *Port the contracts and the rituals, not the state.* This file distills the surviving rules from Research Stack and rebases them onto SilverSight's library-method architecture. Legacy deployment details, stale benchmark tables, and repo-specific paths have been stripped. The conceptual bindings — Lean authority, no-Float compute, receipt boundaries, and the post-interaction ritual — remain in force. --- ## 1. Project Architecture SilverSight is organized as a minimal invariant core plus independent libraries. ``` Core/ SilverSightCore.lean ← no imports, no Float, no library code formal/ CoreFormalism/ ← Q16_16, Hachimoji, Chentsov, Sidon PVGS_DQ_Bridge/ ← quantum bridge UniversalEncoding/ ← math address space BindingSite/ ← biological binding sketches python/ ← I/O, feature extraction, orchestration qubo/ ← optimization libraries tests/ ← verification fixtures docs/ ← architecture and placement docs ``` ### Library method - **Core defines the contract.** Libraries implement it. - `Core/SilverSightCore.lean` imports nothing and depends on nothing. - Every library may import `Core/` but may **not** import another library. - The `Receipt` is the only interface between Core and libraries. --- ## 2. The No-Float Law **No `Float` in Lean compute paths.** This is non-negotiable. - Use `Q16_16.ofNat`, `Q16_16.ofRatio`, or `Q16_16.ofRawInt` for all core arithmetic. - `ofFloat` is permitted **only** at external boundaries (JSON parsing, sensor input) and must be immediately bracketed/converted. - `Float` is forbidden in `Core/` entirely. `Receipt.pathCost` is an `Option Nat` (raw fixed-point integer), not `Option Float`. - The canonical fixed-point implementation is `formal/CoreFormalism/FixedPoint.lean`, ported from Research Stack `Semantics.FixedPoint.lean` with boundary conversions removed from compute paths. --- ## 3. Programming Choice Flow Before writing or placing any new logic, run through this decision tree in order. Stop at the first rule that applies. ``` New logic needed? │ ├── Does it make an admissibility, routing, alignment, or gating decision? │ └── YES → Write it in Lean. No Python equivalent allowed. │ File: formal/CoreFormalism/*.lean or a new formal/*.lean module. │ ├── Does it mint, stamp, or emit a top-level receipt or JSON bundle? │ └── YES → It belongs in Core receipt validators or the designated emitter. │ Python may format/store, but Lean stamps the decision. │ ├── Does it classify rows, run an alignment gate, or compute scores? │ └── YES → Lean. Python may call it via #eval / lake exe but may not │ replicate the logic. │ ├── Does it supply raw input features (expression text, route_hint, domain_type, │ equation_id hashing, weak_axes count)? │ └── YES → Python shim is acceptable. The shim must: │ (a) produce only a raw data structure │ (b) carry no admissibility logic │ (c) be regenerable from source │ (d) live in python/ or qubo/ with a TODO(lean-port) if the logic │ could eventually move to Lean │ ├── Does it use floating-point arithmetic in a compute path? │ └── YES → STOP. Use Q16_16.ofNat / Q16_16.ofRatio / Q16_16.ofRawInt. │ ├── Does it advance promotion status (e.g. set promotion = "promoted")? │ └── YES → STOP. Promotion is always not_promoted until a Lean gate │ explicitly passes. Never advance it in shim space or by hand. │ └── Is it pure I/O (read JSON, write JSONL, call subprocess, format output)? └── YES → Python shim is fine. Keep it in python/ or qubo/. ``` **Summary:** Lean owns all decisions. Python owns all I/O. --- ## 4. Receipt Contract The `Receipt` is the compressed interface record. It is not metadata around a result; it **is** the result. ```lean structure Receipt where receiptID : String expression : String finalState : HachimojiState ticCount : Nat fuelUsed : Nat pathCost : Option Nat -- raw integer cost; never Float libraryRefs : List String verified : Bool ``` - Libraries produce receipts. The core consumes them. - A receipt proves only the gate it actually checks. - Receipt validation lives in `Core/SilverSightCore.lean`. --- ## 5. AVM and TIC Axiom The Abstract Virtual Machine (AVM) is a stack machine defined in Core. - `δ : AVMState × Instruction → AVMState` is the sole transition function. - **TIC axiom:** TIC is derived from events, never the driver. - `T_{n+1} = T_n + E(S_n)` where `E ≥ 0` - `δ` never decreases TIC. - Meaningful computation (`finalState ≠ Ζ`) implies `ticCount > 0`. --- ## 6. Verification Expectations - For Lean changes, run the narrow target first, then `lake build` when feasible. - For Python shims, run `python3 -m py_compile` on touched files. - For JSON receipts, run `python3 -m json.tool`. - Before committing, run `git diff --cached --check` and scan touched files for secrets. --- ## 7. Post-Interaction Workflow (mandatory) After any code, Lean, shim, receipt, or architecture change: 1. **Update the nearest scoped AGENTS.md.** - Root or multi-subtree changes → this file. - `Core/` changes → `Core/AGENTS.md` if one exists, otherwise this file. - `formal/` changes → `formal/AGENTS.md` if one exists, otherwise this file. 2. **Verify the build.** - Lean: `lake build` from the appropriate `lakefile.lean` root. - Python: `python3 -m py_compile` on touched files. 3. **Commit.** - Stage only explicitly touched files. **Never `git add .`.** - Commit format: ``` (): Build: jobs, 0 errors (lake build) ``` - Types: `feat`, `fix`, `chore`, `docs`, `refactor`. - Scopes: `core`, `formal`, `python`, `qubo`, `docs`, `infra`. 4. **Check tree cleanliness.** ```bash git status --branch --short --untracked-files=all ``` Untracked files that are not generated artifacts must be staged or noted as intentionally dirty. --- ## 8. Do Not Sweep Never run broad cleanup commands: ```bash git add . git checkout -- . git clean -fdx ``` Use explicit file lists. Generated artifacts and research scratch should stay out of Git unless they are themselves the evidence under review. --- ## 9. Git Remote Hygiene - The active branch may not have an upstream. Inspect with `git rev-parse --abbrev-ref --symbolic-full-name @{u}` before assuming push state. - Prefer the `github` remote and verify the remote head after push: ```bash git fetch github git rev-list --left-right --count FETCH_HEAD...HEAD git push -u github git ls-remote --heads github ``` --- ## 10. Secrets Secrets are runtime-only. Use environment variables (`OLLAMA_API_KEY`, `DEEPSEEK_API_KEY`, etc.). Never paste, print, or commit literal provider keys. --- ## 11. Legacy Recovery Trigger The phrase **`RECOVER LEGACY INFORMATION`** is the explicit retrieval trigger for archived or quarantined concepts. Accepted forms: ```text RECOVER LEGACY INFORMATION: Recover Legacy Information: recover from cornfield: ``` Rules: - Inspect the requested legacy source with read-only commands first. - Recover only the named file, concept, commit slice, or receipt. - Modernize the recovered material onto the current clean branch. - Never merge, reset to, or base new work on a legacy branch unless explicitly asked. - Preserve the legacy branch as retrievable archive state. Current Research Stack cornfield ref (for cross-repo lookup only): `backup/distilled-with-vcd-history-2026-05-11`. --- ## 12. Glossary - **Hachimoji state** — one of Φ, Λ, Ρ, Κ, Ω, Σ, Π, Ζ. The 8-state output alphabet of the core classifier. - **Receipt** — the machine-readable attestation record that crosses the Core/library boundary. - **AVM** — Abstract Virtual Machine. The stack-machine semantics defined in `Core/SilverSightCore.lean`. - **TIC** — Temporal Index of Computation. A monotone event counter derived from state transitions. - **Q16_16** — Canonical 32-bit fixed-point type (`formal/CoreFormalism/FixedPoint.lean`). - **Library method** — Core defines contracts; libraries implement them; no library imports another library. - **Sidon label** — an address from a set with unique pairwise sums. Powers of 2 are canonical for 8 strands. - **BraidStorm** — the 8-strand braid topology used in eigensolid compression. - **eigensolid** — converged stable state of a braid crossing loop; detected when `crossStep(s) = s`. - **promotion** — status advance from `not_promoted` to `promoted` only after a Lean gate passes. --- ## 13. SilverSight-Specific Boundaries - `Core/SilverSightCore.lean` is the root authority. It contains no sorries in the active surface. - `formal/CoreFormalism/FixedPoint.lean` is the canonical Q16_16 source of truth. - The `python/` and `qubo/` directories are I/O and optimization shims only; they may not contain admissibility logic. - Research artifacts and scratch output should live outside the git tree unless promoted as durable receipts.