{"id":50446703,"url":"https://github.com/jasonshroyer/sgc-lean","last_synced_at":"2026-05-31T22:00:46.219Z","repository":{"id":331655698,"uuid":"1102662087","full_name":"JasonShroyer/sgc-lean","owner":"JasonShroyer","description":"Lean 4 library characterizing the algebraic structure of metastability and consolidation in stochastic systems","archived":false,"fork":false,"pushed_at":"2026-05-26T18:31:34.000Z","size":82763,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T20:17:49.206Z","etag":null,"topics":["assembly-theory","complex-systems","formal-verification","free-energy-principle","information-geometry","lean4","markov-chains","mechanistic-interpretability","quantum-information","spectral-geometry","stochastic-thermodynamics","topological-data-analysis"],"latest_commit_sha":null,"homepage":"","language":"Lean","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JasonShroyer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-23T21:18:32.000Z","updated_at":"2026-01-28T18:46:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JasonShroyer/sgc-lean","commit_stats":null,"previous_names":["jasonshroyer/sgc-lean"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/JasonShroyer/sgc-lean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonShroyer%2Fsgc-lean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonShroyer%2Fsgc-lean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonShroyer%2Fsgc-lean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonShroyer%2Fsgc-lean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JasonShroyer","download_url":"https://codeload.github.com/JasonShroyer/sgc-lean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JasonShroyer%2Fsgc-lean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33750474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly-theory","complex-systems","formal-verification","free-energy-principle","information-geometry","lean4","markov-chains","mechanistic-interpretability","quantum-information","spectral-geometry","stochastic-thermodynamics","topological-data-analysis"],"created_at":"2026-05-31T22:00:30.720Z","updated_at":"2026-05-31T22:00:46.207Z","avatar_url":"https://github.com/JasonShroyer.png","language":"Lean","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SGC: The Spectral Geometry of Consolidation\n\n[![Build](https://github.com/JasonShroyer/sgc-lean/actions/workflows/build.yml/badge.svg)](https://github.com/JasonShroyer/sgc-lean/actions/workflows/build.yml)\n[![Lean 4](https://img.shields.io/badge/Lean-4-blue.svg)](https://lean-lang.org/)\n[![Verified Core](https://img.shields.io/badge/core-verified-brightgreen.svg)](VERIFIED_CORE_MANIFEST.md)\n\nAn experimental formalization of the algebraic structure of metastability in discrete stochastic systems. This library integrates spectral geometry, stochastic thermodynamics, and variational methods to derive bounds on the stability of partitions in finite-state Markov chains.\n\n**Note:** This project was developed by a non-academic enthusiast (music background, self-taught programmer) using AI to explore formal verification. I treat Lean 4 as a \"falsification engine\" to test physical intuitions against rigorous logic, in an attempt to prevent self-delusion. I am essentially steering the AI to build the mathematical objects I intuit. Feedback on these definitions is very welcome.\n\n**Scope:** The verified core establishes results for **finite state spaces** (`[Fintype V]`). This is a deliberate design choice—see [`ARCHITECTURE.md`](ARCHITECTURE.md) for rationale. Continuum limits are axiomatized via `SGC.Bridge.Discretization`, providing an explicit interface for future formalization of analytic convergence results.\n\n**New in v2:** Approximate lumpability is now a *derived theorem*, not an axiom. We prove that small kinematic defects (leakage between blocks) lead to bounded trajectory errors. The core result `trajectory_closure_bound` establishes that **prediction is possible in a coarse-grained world**—the mathematical foundation for emergent agency.\n\n**New in v3 (Audit Refinement):** Following rigorous mathematical review, we clarified the scope of spectral vs. dynamical results. The **trajectory bounds** (`trajectory_closure_bound`, `NCD_uniform_error_bound`) are valid for ALL generators, including non-reversible systems. Spectral eigenvalue matching (`spectral_stability_reversible`) requires reversibility. The trajectory-based results are the foundation for a physics of emergence.\n\n---\n\n## The Four Pillars of Formalization\n\nThe library is organized into four logical modules (`src/SGC/`):\n\n### 1. Spectral Geometry (The Foundation)\n- **Module:** `SGC.Spectral` \n- **Physics:** Establishes that non-reversible Markov chains converge to equilibrium exponentially fast via spectral gap bounds.\n- **Key Theorem:** `spectral_stability_bound` (Exponential decay bound derived from the Sector Envelope).\n\n### 2. Renormalization (Scale Invariance)\n- **Module:** `SGC.Renormalization.Lumpability` \n- **Physics:** Proves that coarse-graining preserves predictive validity (trajectory closure).\n- **Key Theorem:** `dirichlet_gap_non_decrease` (The Dirichlet form infimum is preserved under coarse-graining).\n\n#### Verified Approximate Lumpability (100% Complete)\n\nWe have replaced the `approximate_gap_leakage` axiom with a **fully verified theorem stack**. See [`src/SGC/Renormalization/Approximate.lean`](src/SGC/Renormalization/Approximate.lean).\n\n| Component | Status | Scope | Description |\n|-----------|--------|-------|-------------|\n| `IsApproxLumpable` | ✅ Definition | All L | ‖(I-Π)LΠ‖_op ≤ ε (leakage defect) |\n| `trajectory_closure_bound` | ✅ Verified | **All L** | Trajectory error O(ε·t) — **THE CORE VICTORY** |\n| `NCD_uniform_error_bound` | ✅ Verified | **All L** | Uniform-in-time O(ε/γ) for NCD systems |\n| `propagator_approximation_bound` | ✅ Verified | All L | Operator norm bound on propagator difference |\n| `spectral_stability_reversible` | ⚠️ Reversible | L = L* | Eigenvalue tracking via Weyl (requires self-adjoint L) |\n| `dirichlet_gap_non_decrease` | ✅ Verified | All L | Algebraic (spectral interpretation requires reversibility) |\n\n**The Physics of Emergence:** The trajectory-based results prove that **prediction is possible** using a coarse-grained model. This is the mathematical foundation for:\n- **Effective Field Theory**: A reduced model validly predicts the future\n- **Markov Blankets**: Minimizing leakage defect ε mechanically carves out predictive boundaries\n- **Emergent Agency**: Systems that persist must minimize prediction error, hence minimize ε\n\nThe chain of inference for non-reversible systems:\n```\nIsApproxLumpable → trajectory_closure_bound → NCD_uniform_error_bound\n                                           ↓\n                              PREDICTIVE EMERGENCE (valid for all generators)\n```\n\nFor reversible systems only:\n```\ntrajectory_closure_bound → propagator_approximation_bound → spectral_stability_reversible\n```\n\n#### NCD Validity Horizon (A Physical Insight)\n\nFor NCD (Near-Completely Decomposable) systems, the formalization successfully distinguished between:\n\n- **Vertical Stability** (✅ Verified): States rapidly collapse to the slow manifold with uniform-in-time error O(ε/γ).\n- **Horizontal Drift** (🚫 Disproved): Phase along the slow manifold drifts as O(ε·t).\n\nThe proof assistant correctly rejected `NCD_spectral_stability` as false. Effective theories for NCD systems have a **validity horizon** of t ≪ 1/ε. Beyond this timescale, higher-order corrections are required.\n\n### 3. Thermodynamics (Stochastic Heat)\n- **Module:** `SGC.Thermodynamics.DoobMeyer` \n- **Physics:** The stochastic thermodynamics of surprise. Decomposes self-information into predictable work and martingale heat.\n- **Key Theorem:** `doob_decomposition` ($S_n = M_n + A_n$).\n\n### 4. Variational Mechanics (The \"Why\")\n- **Module:** `SGC.Variational.LeastAction` \n- **Physics:** Derives drift maximization from the Principle of Least Action.\n- **Key Theorem:** `variational_drift_optimality` (Action minimization implies drift maximization).\n\n---\n\n## Bridges \u0026 Axioms\n\n- **`SGC.Axioms.Geometry`**: Defines the explicit $L^2(\\pi)$ metric space structures without heavy typeclass overhead.\n- **`SGC.Topology.Blanket`**: Formalizes Markov Blankets via geometric orthogonality rather than information theory.\n- **`SGC.Bridge.Discretization`**: Defines the **Gap Consistency** interface for the continuum limit. Proves that any discretization satisfying this interface inherits thermodynamic stability.\n- **`SGC.Geometry.Manifold.Convergence`**: Contains the **Axiomatic Interface** (`manifold_hypothesis`, `spectral_convergence_axiom`) encoding the Belkin-Niyogi convergence theorem. This separates the thermodynamic logic from the geometric implementation.\n\n---\n\n## Extensions\n\n### Information Geometry\n- **Module:** `SGC.Information`\n- **Physics:** Proves that geometric orthogonality is equivalent to conditional independence (vanishing Conditional Mutual Information) in the Gaussian limit.\n- **Key Theorem:** `information_geometry_equivalence` — For reversible systems, `RespectsBlank` (geometric) ⟺ `IsInformationBlanketV` (information-theoretic).\n\n### Continuum Limits\n- **Module:** `SGC.Geometry.Manifold`\n- **Physics:** Scaffolding for the Belkin-Niyogi convergence theorem (graph Laplacians → Laplace-Beltrami operators).\n- **Goal:** Constructive validation of the `ContinuumTarget` axiom.\n\n### Topological Evolution (Phase 5 - NEW)\n- **Module:** `SGC.Evolution`\n- **Physics:** Ricci Flow with Surgery—structural emergence via bond breaking/forming.\n- **Key Components:**\n\n| Module | Purpose | Key Definition |\n|--------|---------|----------------|\n| `FormanRicci` | Stress signal | `FormanRicci G u v` — combinatorial edge curvature |\n| `Surgery` | Operators | `SurgeryCut`, `SurgerySew` — topology-changing maps |\n| `Conservation` | Constraints | `IsSafeSurgery`, `BettiNumber` — topological invariants |\n\n**The Three-Layer Architecture:**\n```\nSignal:     FormanRicci(e) \u003c 0  →  Edge under stress (bottleneck)\nAction:     SurgeryCut(G, θ)   →  Remove stressed edges\nConstraint: IsSafeSurgery      →  Preserve b₀=1, b₁≥1 (connectedness + blanket)\n```\n\n**Physical Applications:**\n- **Origin of Life**: Chemical bond formation/breaking\n- **Neural Networks**: Synaptic pruning/growth  \n- **Emergent Identity**: Markov blanket (b₁ ≥ 1) as topological \"self\"\n\n---\n\n## Theorem Index\n\n| Theorem | Module | Tier | Description |\n|---------|--------|------|-------------|\n| `spectral_stability_bound` | `SGC.Spectral.Defs` | **Core** | Spectral stability of non-reversible chains |\n| `gap_non_decrease` | `SGC.Renormalization.Lumpability` | **Core** | Spectral gap preservation under coarse-graining |\n| `trajectory_closure_bound` | `SGC.Renormalization.Approximate` | **Core** | Trajectory error O(ε·t) for approx-lumpable systems |\n| `spectral_stability` | `SGC.Renormalization.Approximate` | **Core** | Eigenvalue tracking (verified via Weyl) |\n| `NCD_uniform_error_bound` | `SGC.Renormalization.Approximate` | **Core** | Uniform-in-time O(ε/γ) bound for NCD systems |\n| `doob_decomposition` | `SGC.Thermodynamics.DoobMeyer` | **Core** | Stochastic thermodynamic decomposition of surprise |\n| `variational_drift_optimality` | `SGC.Variational.LeastAction` | **Core** | Variational derivation of drift maximization |\n| `blanket_orthogonality` | `SGC.Topology.Blanket` | **Core** | Internal-external orthogonality for Markov blankets |\n| `information_geometry_equivalence` | `SGC.Information.Equivalence` | **Extension** | Geometry ⟺ Information equivalence |\n| `forman_ricci_symm` | `SGC.Evolution.FormanRicci` | **Evolution** | F(u,v) = F(v,u) — curvature symmetry |\n| `forman_ricci_bottleneck` | `SGC.Evolution.FormanRicci` | **Evolution** | High-degree endpoints → negative curvature |\n| `safe_surgery_preserves_blanket` | `SGC.Evolution.Conservation` | **Evolution** | Safe surgery maintains b₁ ≥ 1 |\n| `self_preservation` | `SGC.Evolution.Conservation` | **Evolution** | Constrained surgery preserves Markov blanket |\n\n---\n\n## Getting Started\n\n### System Requirements\n\n- **Disk Space:** ~1 GB (includes Mathlib cache and build artifacts)\n- **Network:** Requires downloading Mathlib dependencies (approx. 10 mins on standard connections)\n\n### Prerequisites\n\nThis project uses [Lean 4](https://lean-lang.org/) with Mathlib. You'll need `elan` (the Lean version manager) installed.\n\n**macOS / Linux:**\n```bash\ncurl https://raw.githubusercontent.com/leanprover/elan/master/elan-init.sh -sSf | sh\n```\n\n**Windows:**\nDownload the installer from [github.com/leanprover/elan](https://github.com/leanprover/elan/releases)\n\n### Build Instructions\n\n**Step 1: Clone the repository**\n```bash\ngit clone https://github.com/JasonShroyer/sgc-lean.git\ncd sgc-lean\n```\n\n**Step 2: Troubleshooting — Clean Artifacts**\n\nIf you encounter path conflicts or build errors, remove the local Lake cache:\n```bash\nrm -rf .lake\n```\n\n**Step 3: Build**\n```bash\n# Fetch pre-compiled Mathlib binaries (could save an hour or more of compilation time)\nlake exe cache get\n\n# Build the project\nlake build\n```\n\nThe library root is located at `src/SGC.lean`.\n\n### Running Tests\n\nTo run the sanity checks and see output (axiom transparency, concrete examples):\n\n```bash\nlake env lean test/Main.lean\n```\n\nThis uses the Lean interpreter and runs instantly with cached bytecode.\n\n### Reading Guide\n\n**For Physicists/Mathematicians:**\n1. Start with this README for the high-level architecture\n2. Read [VERIFIED_CORE_MANIFEST.md](VERIFIED_CORE_MANIFEST.md) for verification status\n3. Inspect [`src/SGC/Renormalization/Lumpability.lean`](src/SGC/Renormalization/Lumpability.lean) for the `gap_non_decrease` proof\n4. See [`test/Main.lean`](test/Main.lean) for concrete examples and axiom audits\n\n**For Lean Developers:**\n1. Read [ARCHITECTURE.md](ARCHITECTURE.md) for design rationale (why explicit weights, why finite state spaces)\n2. Read [CONTRIBUTING.md](CONTRIBUTING.md) for build instructions and safeguards\n3. Run `lake build` and `lake env lean test/Main.lean` to verify\n4. Inspect `#print axioms` output to understand dependency chains\n\n**For Peer Reviewers:**\n1. Start with [VERIFIED_CORE_MANIFEST.md](VERIFIED_CORE_MANIFEST.md) for the verification statement\n2. Check [`src/SGC/Renormalization/Approximate.lean`](src/SGC/Renormalization/Approximate.lean) for the axiomatized effective theory\n3. Review axiom docstrings (search for `axiom` keyword) to understand modeling assumptions\n4. Verify CI build status and `Verify no sorries` step in [`.github/workflows/build.yml`](.github/workflows/build.yml)\n\n---\n\n## Verification Status (v0.6.0)\n\n**Build Status: ✅ Zero Sorries** — All modules compile without `sorry` placeholders.\n\n### Two-Tier Architecture\n\n| Tier | Description | Verification Level |\n|------|-------------|-------------------|\n| **Verified Core** | Algebraic theorems proved from Mathlib primitives | ✅ Machine-checked proofs |\n| **Axiomatized Effective Theory** | Physical axioms with explicit assumptions | ✅ Conditional on declared axioms |\n\n### Verified Core (No Additional Axioms)\n\nThese theorems are proved from first principles using only standard Lean/Mathlib axioms:\n\n| Module | Key Theorem | Status |\n|--------|-------------|--------|\n| `Renormalization.Lumpability` | `dirichlet_gap_non_decrease` | ✅ Verified |\n| `Renormalization.Approximate` | `trajectory_closure_bound` | ✅ Verified |\n| `Thermodynamics.DoobMeyer` | `doob_decomposition` | ✅ Verified |\n| `Variational.LeastAction` | `variational_drift_optimality` | ✅ Verified |\n| `Topology.Blanket` | `blanket_orthogonality` | ✅ Verified |\n| `Geometry.CurvatureBridge` | `assembly_index_zero_iff_constant` | ✅ Verified |\n| `Geometry.Yamabe` | `YamabeFlowStep.radius_pos` (CFL) | ✅ Verified |\n\n### Axiomatized Effective Theory\n\nThese modules use explicitly declared axioms for standard mathematical results:\n\n| Category | Axioms | Purpose |\n|----------|--------|---------|\n| **Functional Analysis** | `Duhamel_integral_bound`, `Weyl_inequality_pi`, `HeatKernel_opNorm_bound` | Spectral perturbation theory |\n| **Stochastic Processes** | `diffusionStep_nonneg`, `diffusionStep_sum` | Markov semigroup properties |\n| **Thermodynamics** | `stationary_strictly_positive`, `hidden_entropy_bounded_by_defect` | Perron-Frobenius, entropy bounds |\n| **Geometry** | `YamabeFlow`, `eulerCharacteristic` | Discrete flow dynamics |\n\nThese axioms represent standard results in analysis that we chose not to formalize from scratch. Each axiom is documented with its mathematical justification. Future contributors can discharge these by proving them from Mathlib primitives.\n\n### Axiom Audit\n\n**Run `lake env lean test/Main.lean`** to see exactly which axioms each theorem depends on.\n\nThe only \"non-standard\" axioms are those explicitly declared in our codebase—all others (`propext`, `Classical.choice`, `Quot.sound`) are standard Lean/Mathlib foundations.\n\n---\n\n## Build Status\n\n| Component | Status | Notes |\n|-----------|--------|-------|\n| Full Build | ✅ Passing | Zero sorries in all modules |\n| Approximate Lumpability | ✅ Complete | All core theorems verified (conditional on analysis axioms) |\n| NCD Extension | ✅ Verified | `NCD_spectral_stability` correctly identified as **false** (secular growth) |\n\n**Documentation:**\n- [`VERIFIED_CORE_MANIFEST.md`](VERIFIED_CORE_MANIFEST.md) — Formal verification statement\n- [`ARCHITECTURE.md`](ARCHITECTURE.md) — Design decisions and rationale for reviewers\n- [`CONTRIBUTING.md`](CONTRIBUTING.md) — How to verify and extend the library\n- [`CHANGELOG.md`](CHANGELOG.md) — Project history\n\n---\n\n## Future Roadmap\n\n### Current Scope: Metric Consolidation (Level 1)\n\n**What we have formalized (Phase 1-4):**\n- **Fixed Topology**: The graph structure (which states connect to which) is static\n- **Yamabe Flow**: Curvature smoothing via gradient descent on conformal factors\n- **Assembly Index**: Measures deviation from uniform predictability\n- **Ollivier-Ricci Curvature**: Grounds geometric curvature in transition probabilities\n\nThis corresponds to **learning/annealing** on a fixed architecture—optimizing edge weights without changing which edges exist.\n\n### Future Scope: Topological Evolution (Level 2)\n\n**The next frontier (Phase 5+):**\n\n| Concept | Tool | Application |\n|---------|------|-------------|\n| **Forman-Ricci Curvature** | Combinatorial edge curvature | Identifies \"stress points\" (likely to break/form) |\n| **Ricci Flow with Surgery** | Topology-changing operator | Models bond breaking/forming |\n| **Discrete Morse Theory** | Persistent homology (Betti numbers) | Tracks topological invariants through surgery |\n\n**Why This Matters:**\n- **Origin of Life**: Chemical bond formation/breaking\n- **Neural Architecture Search**: Synaptic pruning/growth\n- **Social Network Evolution**: Relationship formation/dissolution\n- **Emergent Identity**: Creation of stable Markov blankets (Betti₁ = \"self\")\n\n**Reserved Interfaces:**\n```\nTopologicalSurgery : Graph → Graph  -- Discontinuous topology change\nFormanRicci : Edge → ℝ              -- Combinatorial stress indicator\nBettiNumber : Graph → ℕ → ℕ         -- Topological invariant tracker\n```\n\nThe current Yamabe flow framework provides the foundation: surgery occurs when weights vanish (w_{ij} → 0) or curvature diverges (κ → -∞).\n\n### Executable Semantics (SciLean Target)\nWhile the verified core utilizes `Real` for analytic precision (marking definitions `noncomputable`), the algebraic structure over `Fintype` is inherently algorithmic.\n* **Goal:** Instantiate the topological definitions with `Float` using [SciLean](https://github.com/lecopivo/SciLean).\n* **Application:** This will allow the exact same theorem-checked code to compile into high-performance C simulators, effectively creating a \"verified physics engine\" for computing validity horizons.\n\n### Browser-Based Verification (Planned)\n\nUpcoming integration with [Gitpod](https://gitpod.io/) to allow one-click review and verification of proofs directly in the browser—no local installation required.\n\n---\n\n## Architecture Note\n\nThis library provides the **mathematical foundation**—spectral theory, thermodynamics, and geometry—as a formally verified standard. Runtime implementations, measurement harnesses, and experimental control modules are maintained in a separate repository to ensure this library remains a focused, academically accessible artifact.\n\nIf you are interested in applying these formalizations to executable simulations or control systems, please reach out via the channels below.\n\n---\n\n## Community \u0026 Feedback\n\nI am looking for collaborators to help refute or refine these definitions.\n\n* **Discussion:** Open a [GitHub Issue](https://github.com/JasonShroyer/sgc-lean/issues)\n* **Contact:** Find me on the [Lean Zulip](https://leanprover.zulipchat.com/) as **Jason Shroyer**.\n\n---\n\n## License\n\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonshroyer%2Fsgc-lean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjasonshroyer%2Fsgc-lean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjasonshroyer%2Fsgc-lean/lists"}