mirror of
https://github.com/allaunthefox/SilverSight.git
synced 2026-07-30 17:16:16 +00:00
docs(architecture): rewrite project plan and map old Research Stack layers
- Rewrite docs/ARCHITECTURE.md as the living SilverSight project plan - Add old-map connection table: what transferred, what was left behind - Move Q16_16 canonical note to Core layer - Mark n-space variants, RDS/Gremlin/ENE as out of scope - Update GLOSSARY_ALLOWLIST.md with legacy module names and commands - Regenerate PROJECT_MAP.md/json Build: 2981 jobs, 0 errors (lake build)
This commit is contained in:
parent
4490dc28a7
commit
e92d4d73d9
4 changed files with 166 additions and 93 deletions
|
|
@ -1,129 +1,187 @@
|
|||
# Architecture
|
||||
# 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
|
||||
|
||||
Research-Stack v2 is organized into 6 layers, each with a single responsibility:
|
||||
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 6: Infrastructure <- CI/CD, docs, repo hygiene (this stage)
|
||||
Layer 5: Integrate <- Language bridges (C, Python, Lean FFI)
|
||||
Layer 4: Optimize <- QUBO/QAOA, Finsler annealing
|
||||
Layer 3: Search <- Chaos game, basin finding, equation candidates
|
||||
Layer 2: Codec <- Hachimoji encoding, Q16_16, Sidon addressing
|
||||
Layer 1: Core <- Chentsov theorem, statistical manifolds
|
||||
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 details
|
||||
|
||||
### Layer 1: Core (CoreFormalism/)
|
||||
### Layer 1: Core (`Core/`)
|
||||
|
||||
- **ChentsovTheorem.lean** — Proof that Fisher information metric is the unique (up to scaling) monotone Riemannian metric on the 8-state Hachimoji probability simplex. 883 lines, 0 sorry.
|
||||
- **StatisticalManifold.lean** — Definitions: ProbabilitySimplex, FisherInformationMetric, MarkovKernel, monotonicity.
|
||||
- **Q16_16.lean** — Canonical fixed-point type with round-half-up semantics. Proven equivalent across Lean, C, and Python.
|
||||
- **`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.
|
||||
|
||||
**Status**: PROVEN. No axioms beyond standard Lean/mathlib.
|
||||
**Status:** ✅ Active. `lake build SilverSightCore` is green (3132 jobs, 0 errors).
|
||||
|
||||
### Layer 2: Codec (Codec/)
|
||||
**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.
|
||||
|
||||
- **hachimoji_codec.py** — Deterministic codec: UTF-8 string -> Hachimoji DNA sequence. No ML. No randomness. Pure function.
|
||||
- **q16_roundtrip.py** — Cross-language roundtrip test: Lean <-> C <-> Python.
|
||||
- **sidon_address.py** — Sidon set generation for collision-free memory addressing.
|
||||
### Layer 2: Core Formalism (`formal/CoreFormalism/`, `formal/PVGS_DQ_Bridge/`, etc.)
|
||||
|
||||
**Key invariant**: `decode(encode(s)) == s` for all valid UTF-8 strings `s`.
|
||||
- **`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.
|
||||
|
||||
### Layer 3: Search (Search/)
|
||||
**Status:** ✅ Active. `lake build SilverSightFormal` is green (3132 jobs, 0 errors).
|
||||
|
||||
- **chaos_game.py** — Iterated function system for basin boundary sampling.
|
||||
- **basin_finder.py** — Classifies orbits into basins of attraction.
|
||||
- **equation_candidates.py** — Generates equation candidates from basin representatives.
|
||||
**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.
|
||||
|
||||
**Status**: PROTOTYPE. Chaos game converges; basin classification heuristic.
|
||||
### Layer 3: RRC / AVM ISA (`formal/SilverSight/` + `formal/RRCLib/`)
|
||||
|
||||
### Layer 4: Optimize (Optimize/)
|
||||
- **`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.
|
||||
- **`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.
|
||||
|
||||
- **finsler_qubo.py** — Finsler-anisotropic QUBO formulation.
|
||||
- **qaoa_pipeline.py** — Parameterized quantum circuit optimization (classical simulation).
|
||||
- **annealer.py** — Simulated annealing with Finsler metric temperature schedule.
|
||||
**Status:** ✅ Bare-minimum refactor complete. `lake build SilverSightRRC` is green (2992 jobs, 0 errors).
|
||||
|
||||
**Status**: IN DEVELOPMENT. QUBO formulation solid; QAOA classical simulation slow.
|
||||
**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 5: Integrate (CBridge/, PythonBridge/)
|
||||
### Layer 4: Shim / I-O (`python/`, `qubo/`)
|
||||
|
||||
- **CBridge/** — C shared library with Q16_16 operations, compiled to `.so`.
|
||||
- **PythonBridge/** — Python ctypes bindings to C library. `ctypes.CDLL("./libq16.so")`.
|
||||
- **FFI/** — Lean FFI stubs (future work: direct Lean <-> C calls).
|
||||
- **`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.
|
||||
|
||||
**Invariant**: All three languages produce identical Q16_16 results for the same inputs (verified by roundtrip test).
|
||||
**Status:** ✅ Active for I/O. Python shims pass `py_compile`; pytest is not installed in this environment.
|
||||
|
||||
### Layer 6: Infrastructure (.github/, docs, repo hygiene)
|
||||
**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.
|
||||
|
||||
- **4 CI workflows** — lean-check, python-check, q16-roundtrip, doc-sync.
|
||||
- **pre-commit hooks** — Same checks as CI, run locally before every commit.
|
||||
- **.gitignore** — Excludes all generated artifacts; large files tracked via LFS.
|
||||
### Layer 5: Infrastructure (`.github/`, `docs/`)
|
||||
|
||||
## Data Flow
|
||||
- **`.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)
|
||||
|
||||
```
|
||||
Input equation string
|
||||
|
|
||||
v
|
||||
[Codec] Hachimoji encode -> DNA sequence
|
||||
|
|
||||
v
|
||||
[Search] Chaos game -> basin representative
|
||||
|
|
||||
v
|
||||
[Optimize] QUBO/QAOA -> optimal parameters
|
||||
|
|
||||
v
|
||||
[Core] Chentsov metric -> classification score
|
||||
|
|
||||
v
|
||||
Output: classified equation with provenance
|
||||
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)
|
||||
```
|
||||
|
||||
## Cross-Language Contracts
|
||||
The old Research Stack flow went through Gremlin/Postgres/ENE tables; SilverSight bypasses all of that.
|
||||
|
||||
### Q16_16 Fixed-Point
|
||||
---
|
||||
|
||||
| Language | File | Semantics |
|
||||
|----------|------|-----------|
|
||||
| Lean | CoreFormalism/Q16_16.lean | Round-half-up, saturating |
|
||||
| C | CBridge/libq16.c | Round-half-up, saturating |
|
||||
| Python | PythonBridge/q16_binding.py | Round-half-up, saturating |
|
||||
|
||||
**Verification**: `Tests/q16_roundtrip_test.py` checks all triples (x, y) in [-1, 1] x [-1, 1] with step 1/256.
|
||||
|
||||
### Build Commands
|
||||
## Build & verification commands
|
||||
|
||||
```bash
|
||||
# Lean
|
||||
# Lean — narrow targets first, then full build
|
||||
lake build SilverSightCore
|
||||
lake build SilverSightFormal
|
||||
lake build SilverSightRRC
|
||||
lake build rrc-emit-fixture
|
||||
lake build
|
||||
|
||||
# C
|
||||
make -f CBridge/Makefile
|
||||
# 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
|
||||
pytest Tests/ -v
|
||||
# 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
|
||||
---
|
||||
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
/
|
||||
├── CoreFormalism/ <- Layer 1: Lean proofs
|
||||
├── Codec/ <- Layer 2: Encoding/decoding
|
||||
├── Search/ <- Layer 3: Chaos game, basins
|
||||
├── Optimize/ <- Layer 4: QUBO, QAOA
|
||||
├── CBridge/ <- Layer 5: C library
|
||||
├── PythonBridge/ <- Layer 5: Python bindings
|
||||
├── FFI/ <- Layer 5: Lean FFI (stub)
|
||||
├── Tests/ <- Cross-layer tests
|
||||
├── Core/
|
||||
│ ├── SilverSightCore.lean ← Layer 1: invariant core
|
||||
│ └── SilverSight/
|
||||
│ └── FixedPoint.lean ← Layer 1: canonical Q16_16
|
||||
├── 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
|
||||
├── .github/
|
||||
│ ├── workflows/ <- 4 CI workflows
|
||||
│ └── scripts/ <- doc-sync check
|
||||
├── .gitignore
|
||||
├── .pre-commit-config.yaml
|
||||
├── README.md
|
||||
└── ARCHITECTURE.md
|
||||
│ ├── 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. Add `RRC.ReceiptDensity`, `RRC.PolyFactorIdentity`, `RRC.EntropyCandidates` if needed.
|
||||
4. Add a C/Lean FFI or Python `ctypes` bridge for the canonical Q16_16 roundtrip test.
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -55,6 +55,7 @@ are comments.
|
|||
## Allowed commands and tool invocations
|
||||
|
||||
- lake build
|
||||
- lake build SilverSightCore
|
||||
- lake build SilverSightFormal
|
||||
- lake build SilverSightRRC
|
||||
- python3 -m py_compile
|
||||
|
|
@ -66,9 +67,23 @@ are comments.
|
|||
- Goal
|
||||
- Purpose
|
||||
- Decision needed
|
||||
- Connection to old map
|
||||
|
||||
## Allowed implementation-only identifiers
|
||||
|
||||
- expressionToReceipt
|
||||
- emitFixtureCorpus
|
||||
- toSilverSightReceipt
|
||||
- pistProxyLabel
|
||||
- pistExactLabel
|
||||
|
||||
## Allowed Research Stack module names (legacy references only)
|
||||
|
||||
- NKHodgeFAMM
|
||||
- BurgersPDE
|
||||
- GraphRank
|
||||
- S3C
|
||||
- SSMS
|
||||
- SSMS_nD
|
||||
- SidonSet
|
||||
- Spectrum
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
{
|
||||
"schema": "silversight_project_map_v1",
|
||||
"generated_at": "2026-06-21T14:04:19.314776+00:00",
|
||||
"generated_at": "2026-06-21T14:16:47.617133+00:00",
|
||||
"repo": "https://github.com/allaunthefox/SilverSight",
|
||||
"local_path": "/tmp/SilverSight",
|
||||
"summary": {
|
||||
|
|
@ -239,7 +239,7 @@
|
|||
"research_stack_source": null,
|
||||
"role": "",
|
||||
"receipt_boundary": false,
|
||||
"line_count": 341
|
||||
"line_count": 348
|
||||
},
|
||||
{
|
||||
"path": "CITATION.cff",
|
||||
|
|
@ -347,7 +347,7 @@
|
|||
"research_stack_source": null,
|
||||
"role": "",
|
||||
"receipt_boundary": false,
|
||||
"line_count": 129
|
||||
"line_count": 187
|
||||
},
|
||||
{
|
||||
"path": "docs/GLOSSARY.md",
|
||||
|
|
@ -361,7 +361,7 @@
|
|||
"research_stack_source": null,
|
||||
"role": "",
|
||||
"receipt_boundary": false,
|
||||
"line_count": 168
|
||||
"line_count": 172
|
||||
},
|
||||
{
|
||||
"path": "docs/GLOSSARY_ALLOWLIST.md",
|
||||
|
|
@ -445,7 +445,7 @@
|
|||
"research_stack_source": null,
|
||||
"role": "",
|
||||
"receipt_boundary": false,
|
||||
"line_count": 90
|
||||
"line_count": 95
|
||||
},
|
||||
{
|
||||
"path": "docs/TESTING.md",
|
||||
|
|
@ -473,7 +473,7 @@
|
|||
"research_stack_source": null,
|
||||
"role": "",
|
||||
"receipt_boundary": false,
|
||||
"line_count": 136
|
||||
"line_count": 151
|
||||
},
|
||||
{
|
||||
"path": "docs/generate_porting_candidates.py",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# SilverSight Project Map
|
||||
|
||||
**Generated:** 2026-06-21T14:04:19.314776+00:00
|
||||
**Generated:** 2026-06-21T14:16:47.617133+00:00
|
||||
|
||||
**Source repo:** https://github.com/allaunthefox/SilverSight
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue