From e92d4d73d96fc7b3aa79e94a63f12929482a5083 Mon Sep 17 00:00:00 2001 From: allaun Date: Sun, 21 Jun 2026 09:17:25 -0500 Subject: [PATCH] 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) --- docs/ARCHITECTURE.md | 230 +++++++++++++++++++++++-------------- docs/GLOSSARY_ALLOWLIST.md | 15 +++ docs/PROJECT_MAP.json | 12 +- docs/PROJECT_MAP.md | 2 +- 4 files changed, 166 insertions(+), 93 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e1cfa86c..8d5b732b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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. diff --git a/docs/GLOSSARY_ALLOWLIST.md b/docs/GLOSSARY_ALLOWLIST.md index 30638d85..26372dc6 100644 --- a/docs/GLOSSARY_ALLOWLIST.md +++ b/docs/GLOSSARY_ALLOWLIST.md @@ -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 diff --git a/docs/PROJECT_MAP.json b/docs/PROJECT_MAP.json index 09dddef0..06b84302 100644 --- a/docs/PROJECT_MAP.json +++ b/docs/PROJECT_MAP.json @@ -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", diff --git a/docs/PROJECT_MAP.md b/docs/PROJECT_MAP.md index b3d18861..923618e8 100644 --- a/docs/PROJECT_MAP.md +++ b/docs/PROJECT_MAP.md @@ -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