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/Q16_16Manifold.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

# 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 Q16_16Manifold 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.