constraint-theory-distributed 0.1.0__tar.gz

constraint_theory_distributed-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PurplePincher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

constraint_theory_distributed-0.1.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: constraint-theory-distributed
+Version: 0.1.0
+Summary: Unified geometric constraint theory — Eisenstein lattices, deadband funnels, Laman rigidity, holonomy consensus
+Author-email: Forgemaster <forgemaster@superinstance.ai>
+License-Expression: MIT
+Keywords: constraint-theory,eisenstein,laman,rigidity,deadband,holonomy,distributed-systems
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Dynamic: license-file
+
+# constraint-theory-distributed
+
+> Extracted from a stray `master` branch on
+> [`purplepincher/constraint-theory-core`](https://github.com/purplepincher/constraint-theory-core)
+> (a different, unrelated Rust crate) during an org-wide branch cleanup —
+> this is real, separately-authored work that doesn't belong mixed into
+> that repo's history. Full commit history preserved on extraction.
+
+Unified mathematical library for constraint theory — Eisenstein lattices, deadband funnels, Laman rigidity, distributed consensus, and holonomy verification. Five composable modules. 308 tests (83 core + property/edge-case/benchmark suites). Zero external dependencies.
+
+## What It Does
+
+Every distributed system has constraints: agents must agree on time, sensors must stay within tolerance, and the communication graph must carry enough information without waste. This package provides the mathematical primitives that make those constraints precise and provable.
+
+The five modules compose into a unified architecture:
+
+- **Lattice** quantizes continuous space onto the Eisenstein A₂ lattice — every point is within ρ = 1/√3 of a lattice point, guaranteed by geometry.
+- **Temporal** wraps that quantization in a narrowing deadband funnel — ε(t) = ε₀ · e^(−λt) — so drift converges to zero or triggers an anomaly.
+- **Rigidity** ensures the communication graph is minimally rigid (Laman) — exactly 2n−3 edges, every edge load-bearing, no waste.
+- **Metronome** drives distributed consensus across Laman-connected agents — tick, agree, correct with optimal coupling α* = 2/(λ₂ + λₙ).
+- **Holonomy** verifies cycle consistency in tiled constraint systems — detects and isolates faults in O(log N) via binary bisection.
+
+## Architecture
+
+```
+                    ┌─────────────┐
+                    │   Lattice   │
+                    │  (Eisenstein │
+                    │    A₂ snap)  │
+                    └──────┬──────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+       ┌──────▼──────┐    │    ┌───────▼───────┐
+       │   Temporal   │    │    │   Holonomy    │
+       │  (deadband   │    │    │  (cycle verify)│
+       │   funnel)    │    │    └───────┬───────┘
+       └──────┬──────┘    │            │
+              │           │            │
+       ┌──────▼───────────▼──┐  ┌─────▼─────────┐
+       │     Metronome       │  │   Rigidity    │
+       │  (distributed       │  │  (Laman graph) │
+       │   consensus)        │  └───────┬───────┘
+       └──────────┬──────────┘          │
+                  │                     │
+                  └──────┬──────────────┘
+                         │
+                  optimal coupling α*
+```
+
+**Compositions:**
+- **Lattice + Temporal = bounded drift** — snap to lattice, then narrow the deadband over time.
+- **Rigidity + Holonomy = zero-comm consensus** — Laman topology ensures minimal edges; holonomy verifies every cycle closes.
+- **All five = full metronome** — agents snap to lattice, narrow via temporal, couple via Laman rigidity, agree via metronome, verify via holonomy.
+
+## Installation
+
+Not yet published to PyPI. Install from source:
+
+```bash
+git clone https://github.com/purplepincher/constraint-theory-distributed.git
+cd constraint-theory-distributed
+pip install -e .
+```
+
+Requires Python ≥ 3.10. No external dependencies.
+
+## Quick Start
+
+### Lattice — Snap to Eisenstein Lattice
+
+```python
+from constraint_theory_core import snap, covering_radius, is_safe
+
+# Any point in the plane snaps to the nearest A₂ lattice point
+pt, error = snap(0.5, 0.3)
+print(f"Snapped to ({pt.a}, {pt.b}), error = {error:.4f}")
+
+# Error is always ≤ 1/√3 ≈ 0.577 (covering radius guarantee)
+assert error <= covering_radius()
+
+# If error < 1/2√3 ≈ 0.289, the snap is unambiguous
+print(f"Safe: {is_safe(error)}")
+```
+
+### Temporal — Deadband Funnel
+
+```python
+from constraint_theory_core.temporal import TemporalAgent, FunnelPhase
+
+agent = TemporalAgent(decay_rate=0.1)
+
+for t in range(1, 50):
+    result = agent.observe(0.01, 0.01, t=float(t))
+    print(f"t={t:2d}  phase={result.phase.value:10s}  ε={result.deadband:.4f}  err={result.error:.4f}")
+    if result.phase == FunnelPhase.ANOMALY:
+        print("  ⚠ Anomaly detected!")
+```
+
+### Rigidity — Laman Graphs
+
+```python
+from constraint_theory_core import henneberg_construct, is_laman, algebraic_connectivity, optimal_coupling
+
+# Build a minimally rigid graph for 9 agents
+edges = henneberg_construct(9)
+print(f"Edges: {len(edges)} (expected {2*9-3})")
+assert is_laman(9, edges)
+
+# Compute convergence properties
+lam2 = algebraic_connectivity(edges, 9)
+alpha = optimal_coupling(edges, 9)
+print(f"λ₂ = {lam2:.4f}, α* = {alpha:.4f}")
+```
+
+### Metronome — Distributed Consensus
+
+```python
+from constraint_theory_core import Metronome, henneberg_construct
+import math
+
+def neighbors_of(edges, i):
+    """Neighbor indices for vertex i in an undirected edge list."""
+    return [v if u == i else u for u, v in edges if u == i or v == i]
+
+# 9 agents on a Laman graph
+edges = henneberg_construct(9)
+agents = [
+    Metronome(T=1.0, phi0=math.pi * i / 9, epsilon=0.5, delta=0.6,
+              neighbors=neighbors_of(edges, i),
+              edges=edges, n_agents=9)
+    for i in range(9)
+]
+
+# Run consensus
+for tick in range(100):
+    for agent in agents:
+        agent.tick()
+    phases = [a.phase for a in agents]
+    for agent in agents:
+        neighbor_phases = [phases[j] for j in agent.neighbors]
+        agent.correct(neighbor_phases)
+
+# Check convergence
+print(f"All converged: {all(a.converged for a in agents)}")
+```
+
+### Holonomy — Cycle Verification
+
+```python
+from constraint_theory_core import verify_consistency, isolate_fault, fault_boundaries
+
+# Each tile = (edges, direction_indices)
+tiles = [
+    ([(0,1), (1,2), (2,0)], [16, 16, 16]),  # consistent: 48 ≡ 0 mod 48
+    ([(0,1), (1,3), (3,0)], [16, 16, 16]),  # consistent
+    ([(2,3), (3,4), (4,2)], [1, 2, 3]),      # INCONSISTENT: 6 ≠ 0
+]
+
+print(f"All consistent: {verify_consistency(tiles)}")   # False
+print(f"First fault at index: {isolate_fault(tiles)}")   # 2
+print(f"All faults: {fault_boundaries(tiles)}")          # [2]
+```
+
+## Modules
+
+| Module | What | Key Functions |
+|--------|------|---------------|
+| `lattice` | Eisenstein A₂ lattice | `snap`, `covering_radius`, `is_safe`, `A2Point`, `encode_dodecet`, `vector48_encode` |
+| `temporal` | Deadband funnel | `TemporalAgent`, `FunnelPhase`, `FunnelResult` |
+| `rigidity` | Laman graph topology | `is_laman`, `henneberg_construct`, `algebraic_connectivity`, `optimal_coupling` |
+| `metronome` | Distributed consensus | `Metronome`, `MetronomeState` |
+| `holonomy` | Cycle verification | `cycle_holonomy`, `verify_consistency`, `isolate_fault`, `fault_boundaries` |
+
+## Equations
+
+| Concept | Equation | Meaning |
+|---------|----------|---------|
+| A₂ covering radius | ρ = 1/√3 ≈ 0.577 | Max distance from any point to nearest lattice point |
+| Safe threshold | ρ/2 ≈ 0.289 | Below this, snap is unambiguous |
+| Eisenstein norm | ‖(a,b)‖² = a² − ab + b² | Squared norm on the lattice |
+| Deadband decay | ε(t) = ε₀ · e^(−λt) | Funnel narrows exponentially |
+| Laman condition | \|E\| = 2n − 3 | Exactly the right number of edges |
+| Algebraic connectivity | λ₂ (2nd Laplacian eigenvalue) | Convergence rate of consensus |
+| Optimal coupling | α* = 2/(λ₂ + λₙ) | Fastest convergence without oscillation |
+| Holonomy | Σ directions mod 48 | 0 means cycle closes exactly |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest                          # 308 tests (83 core + property/edge-case/benchmark suites)
+pytest -v --tb=short            # verbose
+```
+
+## Documentation
+
+- [User Guide](docs/USER-GUIDE.md) — Complete usage documentation
+- [Developer Guide](docs/DEVELOPER-GUIDE.md) — Contributing and internals
+- [Examples](examples/) — Working code examples
+
+## Related Projects
+
+- [flux-tensor-midi](https://github.com/SuperInstance/flux-tensor-midi) — Musical constraint theory
+- [plato](https://github.com/SuperInstance/plato) — PLATO tiling architecture
+- [forgemaster](https://github.com/SuperInstance/forgemaster) — Constraint-theory specialist agent
+
+## License
+
+MIT

constraint_theory_distributed-0.1.0/README.md

@@ -0,0 +1,210 @@
+# constraint-theory-distributed
+
+> Extracted from a stray `master` branch on
+> [`purplepincher/constraint-theory-core`](https://github.com/purplepincher/constraint-theory-core)
+> (a different, unrelated Rust crate) during an org-wide branch cleanup —
+> this is real, separately-authored work that doesn't belong mixed into
+> that repo's history. Full commit history preserved on extraction.
+
+Unified mathematical library for constraint theory — Eisenstein lattices, deadband funnels, Laman rigidity, distributed consensus, and holonomy verification. Five composable modules. 308 tests (83 core + property/edge-case/benchmark suites). Zero external dependencies.
+
+## What It Does
+
+Every distributed system has constraints: agents must agree on time, sensors must stay within tolerance, and the communication graph must carry enough information without waste. This package provides the mathematical primitives that make those constraints precise and provable.
+
+The five modules compose into a unified architecture:
+
+- **Lattice** quantizes continuous space onto the Eisenstein A₂ lattice — every point is within ρ = 1/√3 of a lattice point, guaranteed by geometry.
+- **Temporal** wraps that quantization in a narrowing deadband funnel — ε(t) = ε₀ · e^(−λt) — so drift converges to zero or triggers an anomaly.
+- **Rigidity** ensures the communication graph is minimally rigid (Laman) — exactly 2n−3 edges, every edge load-bearing, no waste.
+- **Metronome** drives distributed consensus across Laman-connected agents — tick, agree, correct with optimal coupling α* = 2/(λ₂ + λₙ).
+- **Holonomy** verifies cycle consistency in tiled constraint systems — detects and isolates faults in O(log N) via binary bisection.
+
+## Architecture
+
+```
+                    ┌─────────────┐
+                    │   Lattice   │
+                    │  (Eisenstein │
+                    │    A₂ snap)  │
+                    └──────┬──────┘
+                           │
+              ┌────────────┼────────────┐
+              │            │            │
+       ┌──────▼──────┐    │    ┌───────▼───────┐
+       │   Temporal   │    │    │   Holonomy    │
+       │  (deadband   │    │    │  (cycle verify)│
+       │   funnel)    │    │    └───────┬───────┘
+       └──────┬──────┘    │            │
+              │           │            │
+       ┌──────▼───────────▼──┐  ┌─────▼─────────┐
+       │     Metronome       │  │   Rigidity    │
+       │  (distributed       │  │  (Laman graph) │
+       │   consensus)        │  └───────┬───────┘
+       └──────────┬──────────┘          │
+                  │                     │
+                  └──────┬──────────────┘
+                         │
+                  optimal coupling α*
+```
+
+**Compositions:**
+- **Lattice + Temporal = bounded drift** — snap to lattice, then narrow the deadband over time.
+- **Rigidity + Holonomy = zero-comm consensus** — Laman topology ensures minimal edges; holonomy verifies every cycle closes.
+- **All five = full metronome** — agents snap to lattice, narrow via temporal, couple via Laman rigidity, agree via metronome, verify via holonomy.
+
+## Installation
+
+Not yet published to PyPI. Install from source:
+
+```bash
+git clone https://github.com/purplepincher/constraint-theory-distributed.git
+cd constraint-theory-distributed
+pip install -e .
+```
+
+Requires Python ≥ 3.10. No external dependencies.
+
+## Quick Start
+
+### Lattice — Snap to Eisenstein Lattice
+
+```python
+from constraint_theory_core import snap, covering_radius, is_safe
+
+# Any point in the plane snaps to the nearest A₂ lattice point
+pt, error = snap(0.5, 0.3)
+print(f"Snapped to ({pt.a}, {pt.b}), error = {error:.4f}")
+
+# Error is always ≤ 1/√3 ≈ 0.577 (covering radius guarantee)
+assert error <= covering_radius()
+
+# If error < 1/2√3 ≈ 0.289, the snap is unambiguous
+print(f"Safe: {is_safe(error)}")
+```
+
+### Temporal — Deadband Funnel
+
+```python
+from constraint_theory_core.temporal import TemporalAgent, FunnelPhase
+
+agent = TemporalAgent(decay_rate=0.1)
+
+for t in range(1, 50):
+    result = agent.observe(0.01, 0.01, t=float(t))
+    print(f"t={t:2d}  phase={result.phase.value:10s}  ε={result.deadband:.4f}  err={result.error:.4f}")
+    if result.phase == FunnelPhase.ANOMALY:
+        print("  ⚠ Anomaly detected!")
+```
+
+### Rigidity — Laman Graphs
+
+```python
+from constraint_theory_core import henneberg_construct, is_laman, algebraic_connectivity, optimal_coupling
+
+# Build a minimally rigid graph for 9 agents
+edges = henneberg_construct(9)
+print(f"Edges: {len(edges)} (expected {2*9-3})")
+assert is_laman(9, edges)
+
+# Compute convergence properties
+lam2 = algebraic_connectivity(edges, 9)
+alpha = optimal_coupling(edges, 9)
+print(f"λ₂ = {lam2:.4f}, α* = {alpha:.4f}")
+```
+
+### Metronome — Distributed Consensus
+
+```python
+from constraint_theory_core import Metronome, henneberg_construct
+import math
+
+def neighbors_of(edges, i):
+    """Neighbor indices for vertex i in an undirected edge list."""
+    return [v if u == i else u for u, v in edges if u == i or v == i]
+
+# 9 agents on a Laman graph
+edges = henneberg_construct(9)
+agents = [
+    Metronome(T=1.0, phi0=math.pi * i / 9, epsilon=0.5, delta=0.6,
+              neighbors=neighbors_of(edges, i),
+              edges=edges, n_agents=9)
+    for i in range(9)
+]
+
+# Run consensus
+for tick in range(100):
+    for agent in agents:
+        agent.tick()
+    phases = [a.phase for a in agents]
+    for agent in agents:
+        neighbor_phases = [phases[j] for j in agent.neighbors]
+        agent.correct(neighbor_phases)
+
+# Check convergence
+print(f"All converged: {all(a.converged for a in agents)}")
+```
+
+### Holonomy — Cycle Verification
+
+```python
+from constraint_theory_core import verify_consistency, isolate_fault, fault_boundaries
+
+# Each tile = (edges, direction_indices)
+tiles = [
+    ([(0,1), (1,2), (2,0)], [16, 16, 16]),  # consistent: 48 ≡ 0 mod 48
+    ([(0,1), (1,3), (3,0)], [16, 16, 16]),  # consistent
+    ([(2,3), (3,4), (4,2)], [1, 2, 3]),      # INCONSISTENT: 6 ≠ 0
+]
+
+print(f"All consistent: {verify_consistency(tiles)}")   # False
+print(f"First fault at index: {isolate_fault(tiles)}")   # 2
+print(f"All faults: {fault_boundaries(tiles)}")          # [2]
+```
+
+## Modules
+
+| Module | What | Key Functions |
+|--------|------|---------------|
+| `lattice` | Eisenstein A₂ lattice | `snap`, `covering_radius`, `is_safe`, `A2Point`, `encode_dodecet`, `vector48_encode` |
+| `temporal` | Deadband funnel | `TemporalAgent`, `FunnelPhase`, `FunnelResult` |
+| `rigidity` | Laman graph topology | `is_laman`, `henneberg_construct`, `algebraic_connectivity`, `optimal_coupling` |
+| `metronome` | Distributed consensus | `Metronome`, `MetronomeState` |
+| `holonomy` | Cycle verification | `cycle_holonomy`, `verify_consistency`, `isolate_fault`, `fault_boundaries` |
+
+## Equations
+
+| Concept | Equation | Meaning |
+|---------|----------|---------|
+| A₂ covering radius | ρ = 1/√3 ≈ 0.577 | Max distance from any point to nearest lattice point |
+| Safe threshold | ρ/2 ≈ 0.289 | Below this, snap is unambiguous |
+| Eisenstein norm | ‖(a,b)‖² = a² − ab + b² | Squared norm on the lattice |
+| Deadband decay | ε(t) = ε₀ · e^(−λt) | Funnel narrows exponentially |
+| Laman condition | \|E\| = 2n − 3 | Exactly the right number of edges |
+| Algebraic connectivity | λ₂ (2nd Laplacian eigenvalue) | Convergence rate of consensus |
+| Optimal coupling | α* = 2/(λ₂ + λₙ) | Fastest convergence without oscillation |
+| Holonomy | Σ directions mod 48 | 0 means cycle closes exactly |
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest                          # 308 tests (83 core + property/edge-case/benchmark suites)
+pytest -v --tb=short            # verbose
+```
+
+## Documentation
+
+- [User Guide](docs/USER-GUIDE.md) — Complete usage documentation
+- [Developer Guide](docs/DEVELOPER-GUIDE.md) — Contributing and internals
+- [Examples](examples/) — Working code examples
+
+## Related Projects
+
+- [flux-tensor-midi](https://github.com/SuperInstance/flux-tensor-midi) — Musical constraint theory
+- [plato](https://github.com/SuperInstance/plato) — PLATO tiling architecture
+- [forgemaster](https://github.com/SuperInstance/forgemaster) — Constraint-theory specialist agent
+
+## License
+
+MIT

constraint_theory_distributed-0.1.0/constraint_theory_core/__init__.py

@@ -0,0 +1,96 @@
+"""
+constraint_theory_core — unified geometric constraint theory.
+
+The one package that brings together:
+- Eisenstein A₂ lattice quantization
+- Deadband temporal funnels
+- Laman rigidity for topology
+- Metronome consensus
+- Holonomy consistency verification
+
+All constants derived from first principles. Zero external dependencies.
+
+Example
+-------
+>>> from constraint_theory_core import snap, covering_radius, is_safe
+>>> pt, err = snap(0.5, 0.3)
+>>> is_safe(err)
+True
+"""
+
+from .exercises import (
+    generate_exercise,
+)
+from .genre_brain import (
+    GenreEpsilons,
+    custom_genre,
+    get_genre,
+    list_genres,
+    sweep_genre,
+)
+from .holonomy import (
+    cycle_holonomy,
+    fault_boundaries,
+    isolate_fault,
+    soft_verify_consistency,
+    verify_consistency,
+)
+from .lattice import (
+    COVERING_RADIUS,
+    DIRECTION_COUNT,
+    DODECET_DIRECTIONS,  # noqa: F401 — re-exported for external use
+    SAFE_THRESHOLD,
+    SQRT_3,
+    A2Point,
+    covering_radius,
+    decode_dodecet,
+    encode_dodecet,
+    holonomy_product,
+    is_consistent,
+    is_safe,
+    norm_sq,
+    snap,
+    soft_snap,
+    vector48_decode,
+    vector48_encode,
+)
+from .metronome import (
+    Metronome,
+    MetronomeState,
+)
+from .rigidity import (
+    algebraic_connectivity,
+    henneberg_construct,
+    is_laman,
+    optimal_coupling,
+    soft_rigidity,
+)
+from .temporal import (
+    FunnelPhase,
+    FunnelResult,
+    TemporalAgent,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Lattice
+    "A2Point", "snap", "soft_snap", "covering_radius", "is_safe", "norm_sq",
+    "decode_dodecet", "encode_dodecet", "vector48_encode", "vector48_decode",
+    "holonomy_product", "is_consistent",
+    "COVERING_RADIUS", "SAFE_THRESHOLD", "SQRT_3", "DIRECTION_COUNT",
+    # Temporal
+    "TemporalAgent", "FunnelPhase", "FunnelResult",
+    # Rigidity
+    "is_laman", "henneberg_construct", "algebraic_connectivity", "optimal_coupling", "soft_rigidity",
+    # Metronome
+    "Metronome", "MetronomeState",
+    # Holonomy
+    "cycle_holonomy", "verify_consistency", "soft_verify_consistency", "isolate_fault", "fault_boundaries",
+    # Genre Brain
+    "GenreEpsilons", "get_genre", "list_genres", "custom_genre", "sweep_genre",
+    # Exercises
+    "generate_exercise",
+    # Meta
+    "__version__",
+]

constraint_theory_distributed-0.1.0/constraint_theory_core/__main__.py

@@ -0,0 +1,27 @@
+"""CLI entry-point: ``python -m constraint_theory_core <subcommand>``."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        print("Usage: python -m constraint_theory_core <subcommand> [options]")
+        print("Subcommands: exercise")
+        sys.exit(1)
+
+    subcommand = sys.argv[1]
+    rest = sys.argv[2:]
+
+    if subcommand == "exercise":
+        from .exercises import _cli_exercise
+        _cli_exercise(rest)
+    else:
+        print(f"Unknown subcommand: {subcommand!r}")
+        print("Available: exercise")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()