SilverSight/docs/ARCHITECTURE.md

# SilverSight Architecture

This is the living project plan. It replaces the Research Stack layer map with the actual SilverSight directory structure, and notes where the old map connects.

## Overview

SilverSight is a minimal invariant core plus independent libraries. The goal is to port the contracts and rituals from Research Stack, not the operational state (databases, RDS, Gremlin, ENE tables).

```
Layer 5: Infrastructure    <- CI, docs, repo hygiene
Layer 4: Shim / I-O        <- python/, qubo/ (I/O only, no admissibility logic)
Layer 3: RRC / AVM ISA     <- formal/SilverSight/ + formal/RRCLib/
Layer 2: Core Formalism    <- formal/CoreFormalism/ + PVGS_DQ_Bridge/ + ...
Layer 1: Core              <- Core/SilverSightCore.lean, Core/SilverSight/FixedPoint.lean
```

## Layer details

### Layer 1: Core (`Core/`)

- **`Core/SilverSightCore.lean`** — Hachimoji states, `Receipt`, abstract AVM transition `δ`, TIC axiom, library interface.
- **`Core/SilverSight/FixedPoint.lean`** — canonical `Q16_16` / `Q0_16` fixed-point arithmetic.
- **`Core/SilverSight/Semantics/`** — YaFF-inspired schema/layout/wireformat core:
  - `Schema.lean` — fixed-size schema contract (`byteSize`, `wellFormed`).
  - `Layout.lean` — physical layouts (`rowMajor`, `columnar`, `compact`, `mmapView`) and a Q0_16 cost model with an ε-suboptimal selector.
  - `WireFormat.lean` — certified encoder/decoder pairs (`encode`, `decode`, `roundTrip`, `encode_size`).
  - `View.lean` — zero-copy address-arithmetic views.
  - `LayoutBridge.lean` — certified conversions between layouts.
  - `CanalLayout.lean` — canal-regime override on top of the cost model.

**Status:** ✅ Active. `lake build SilverSightCore` is green (2987 jobs, 0 errors).

**Connection to old map:** This replaces Research Stack L1 `FixedPoint.lean` + `Basic.lean` + `SIConstants.lean`. SilverSight keeps only the fixed-point contract; constants and `Basic` are absorbed into CoreFormalism or omitted.

### Layer 2: Core Formalism (`formal/CoreFormalism/`, `formal/PVGS_DQ_Bridge/`, etc.)

- **`CoreFormalism/`** — Sidon sets, braid dynamics, eigensolid theory, SieveLemmas, InteractionGraphSidon.
- **`PVGS_DQ_Bridge/`** — photon-varied Gaussian state dual-quaternion bridge and receipts.
- **`UniversalEncoding/`** — universal math address space, chirality.
- **`BindingSite/`** — amino-acid / protein binding sketches.

**Status:** ✅ Active. `lake build SilverSightFormal` is green (3132 jobs, 0 errors).

**Connection to old map:** This absorbs Research Stack L2 (`Spectrum`, `GraphRank`, `BurgersPDE`, `S3C`, `SSMS`, `Bind`, `NonEuclidean`, `SpatialEvo`, `SidonSet`). Those named modules were not ported 1:1; their useful contents were folded into `CoreFormalism` modules.

### Layer 3: RRC / AVM ISA (`formal/SilverSight/` + `formal/RRCLib/`)

- **`RRCLogogramProjection.lean`** — RRC shapes, witness status, projection/merge gates.
- **`ReceiptCore.lean`** — internal validation receipt model and `toSilverSightReceipt` bridge.
- **`RRC/Emit.lean`** — alignment gate, 6 canonical fixture rows, JSON emitter.
- **`RRC/ReceiptDensity.lean`** — Q16_16 receipt-density scoring gate.
- **`RRC/PolyFactorIdentity.lean`** — divisor-sum signature gate.
- **`RRC/EntropyCandidates.lean`** — 10 certifiable braid-state fixtures.
- **`AVMIsa/{Types,Value,Instr,State,Step,Run}.lean`** — concrete typed AVM ISA.
- **`AVMIsa/Emit.lean`** — sole top-level JSON output boundary.
- **`formal/RRCLib/`** — user-facing symlinks into `formal/SilverSight/`.
- **`exe/RrcEmitFixture.lean`** — executable that emits the AVM-stamped fixture corpus JSON.

**Status:** ✅ Bare-minimum refactor complete. `lake build SilverSightRRC` is green (3006 jobs, 0 errors).

**Connection to old map:** This maps to Research Stack L4 (`RRC/Corpus250.lean`, `RRC/RRCTypeWitness.lean`, `AVMIsa/*.lean`). SilverSight currently has the RRC surface and AVM ISA but **not** the full 250-equation corpus or `RRCTypeWitness`.

### Layer 4: Shim / I-O (`python/`, `qubo/`)

- **`python/`** — I/O and feature extraction: Q16_16 canonical reference, Sidon addressing, PIST matrix builder, RRC JSON validator, chaos game, spectral profile.
- **`qubo/`** — QUBO/QAOA/Finsler optimization shims.

**Status:** ✅ Active for I/O. Python shims pass `py_compile`; pytest is not installed in this environment.

**Connection to old map:** This maps to Research Stack L6 (`4-Infrastructure/shim/*.py`). SilverSight shims are intentionally smaller and contain **no** database or RDS logic.

### Layer 5: Infrastructure (`.github/`, `docs/`)

- **`.github/workflows/`** — `lean-check.yml`, `python-check.yml`, `doc-sync.yml`, `q16-roundtrip.yml`.
- **`.github/scripts/`** — `glossary_lint.py`, `check_doc_sync.py`.
- **`docs/`** — architecture, glossary, project map, build logs.

**Status:** ✅ Active.

**Connection to old map:** This is the Research Stack L6 hygiene layer, stripped of deployment-specific notes (RDS, Gremlin, Postgres, Caddy, Tailscale) that do not apply to SilverSight.

---

## What the old map got right

| Old-map item | SilverSight counterpart | Verdict |
|---|---|---|
| `Q16_16` as L1–L3 carrier | `Core/SilverSight/FixedPoint.lean` | ✅ Correct |
| `SidonSet` ancestry | `CoreFormalism.SidonSets` / `InteractionGraphSidon` | ✅ Correct |
| `BurgersPDE` → `NKHodgeFAMM` bridge | `CoreFormalism.Braid*` modules + `PVGS_DQ_Bridge` | ✅ Mostly accurate, names changed |
| AVM `Emit` as receipt boundary | `formal/SilverSight/AVMIsa/Emit.lean` | ✅ Correct |
| RDS dead / shim files still import `rds_connect.py` | `4-Infrastructure/shim/` still has 15 files | ✅ Correct |

## What the old map got wrong or left behind

| Old-map item | Reality | Verdict |
|---|---|---|
| L1 has `Basic.lean`, `SIConstants.lean`, `Toolkit.lean` | SilverSight L1 is only `SilverSightCore.lean` + `FixedPoint.lean` | ❌ Outdated |
| L2 modules (`Spectrum`, `GraphRank`, `S3C`, `SSMS`, etc.) exist as named files | Not ported 1:1; concepts absorbed into `CoreFormalism` | ❌ Outdated |
| L3 n-space variants (`SSMS_nD`, `NKHodgeFAMM`, etc.) are in scope | **Not ported** and not currently planned for SilverSight | ❌ Outdated |
| “147 n-space functions” / `extraction/math.json` as feed | `extraction/math.json` has 13 records, not 147 | ❌ Stale count |
| `scripts/infra_lint.py` flags RDS refs | It checks `INFRA:DEAD` markers and reports clean; it does **not** flag `import rds_connect` | ❌ Misleading |
| Gremlin / Postgres / ENE table completion gap | Irrelevant to SilverSight; SilverSight has no database surface | ❌ Wrong scope |

---

## Data flow (current SilverSight)

```
Raw equation / expression text
        |
        v
[python/ pist_matrix_builder.py]  ->  raw features + 8×8 strand matrix
        |
        v
[formal/SilverSight/RRC/Emit.lean]  ->  FixtureRow + alignment gate
        |
        v
[formal/SilverSight/AVMIsa/Emit.lean]  ->  AVM-stamped receipt JSON
        |
        v
Output: validated RRC fixture bundle (not promoted until a Lean gate passes)
```

The old Research Stack flow went through Gremlin/Postgres/ENE tables; SilverSight bypasses all of that.

---

## Build & verification commands

```bash
# Lean — narrow targets first, then full build
lake build SilverSightCore
lake build SilverSightFormal
lake build SilverSightRRC
lake build rrc-emit-fixture
lake build

# Emit and validate the fixture corpus JSON
.lake/build/bin/rrc-emit-fixture > /tmp/rrc_fixture_emitted.json
python3 python/validate_rrc_predictions.py /tmp/rrc_fixture_emitted.json

# Python hygiene
python3 -m py_compile python/*.py qubo/*.py tests/*.py .github/scripts/*.py
python3 .github/scripts/glossary_lint.py
python3 .github/scripts/check_doc_sync.py

# Regenerate project map after moving/adding files
python3 docs/generate_project_map.py
```

---

## Repository layout

```
/
├── Core/
│   ├── SilverSightCore.lean          ← Layer 1: invariant core
│   └── SilverSight/
│       ├── FixedPoint.lean           ← Layer 1: canonical Q16_16 / Q0_16
│       └── Semantics/                ← Layer 1: schema / layout / wireformat core
│           ├── Schema.lean
│           ├── Layout.lean
│           ├── WireFormat.lean
│           ├── View.lean
│           ├── LayoutBridge.lean
│           └── CanalLayout.lean
├── formal/
│   ├── CoreFormalism/                ← Layer 2: Sidon, braid, Hachimoji
│   ├── PVGS_DQ_Bridge/               ← Layer 2: photon-varied Gaussian bridge
│   ├── UniversalEncoding/            ← Layer 2: universal address space
│   ├── BindingSite/                  ← Layer 2: biological binding sketches
│   ├── SilverSight/                  ← Layer 3: RRC + AVM ISA (namespace roots)
│   └── RRCLib/                       ← Layer 3: user-facing symlinks
├── python/                           ← Layer 4: I/O shims
├── qubo/                             ← Layer 4: optimization shims
├── tests/                            ← Verification fixtures
├── exe/
│   ├── RrcEmitFixture.lean           ← JSON emitter executable
│   └── Q16_16Roundtrip.lean        ← Lean ↔ C Q16_16 roundtrip executable
├── .github/
│   ├── workflows/                    ← CI
│   └── scripts/                      ← repo hygiene scripts
├── docs/                             ← Layer 5: architecture, glossary, maps
├── lakefile.lean
└── README.md
```

---

## In-scope next steps

1. Port the full 250-equation `Corpus250` fixture corpus.
2. Add `PIST.Classify` / matrix builder so `pistProxyLabel` / `pistExactLabel` can be populated from real data.
3. Extend `Semantics.WireFormat` and `Semantics.LayoutBridge` with concrete columnar/compact encodings for product types (e.g., `BraidState`).
4. Promote `CanalRegime` into `CoreFormalism.DynamicCanal` so the library physics drives the Core layout override.
5. Keep promotion as `not_promoted` everywhere until a Lean gate explicitly passes.

## Explicitly out of scope for SilverSight

- Gremlin / Postgres / ENE database back-fill.
- RDS migration or any RDS references.
- N-space variants (`SSMS_nD`, `NKHodgeFAMM`, etc.) unless deliberately brought back in.
- Deployment infrastructure (Caddy, Tailscale, Hermes, Ollama) — these live in Research Stack `AGENTS.md` only as provenance.