SilverSight/AGENTS.md

# 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:
     ```
     <type>(<scope>): <summary>

     <body — what changed and why>

     Build: <N> 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 <branch>
  git rev-list --left-right --count FETCH_HEAD...HEAD
  git push -u github <branch>
  git ls-remote --heads github <branch>
  ```

---

## 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: <path, commit, concept, or artifact>
Recover Legacy Information: <path, commit, concept, or artifact>
recover from cornfield: <path, commit, concept, or artifact>
```

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.