constraint-theory-core

Exact geometric computation on discrete constraint manifolds.

What is Constraint Theory?

Constraint theory replaces floating-point arithmetic with operations on discrete mathematical manifolds. Values are "snapped" to exact points (like Pythagorean triples) rather than approximated as floats. This provides:

Zero drift — snap operations are exact by construction
Provable correctness — snapped values satisfy algebraic identities (a²+b²=c²)
Deterministic — same input always produces same output, regardless of hardware

Features

Feature	Description
`PythagoreanManifold`	Generate and query primitive Pythagorean triples
`AdaptiveTolerance`	ε(c) = k/c — adaptive tolerance for sparse boundary regions
`FixedTolerance`	Constant tolerance for backward compatibility
`HolonomyMeter`	Closed-loop displacement measurement
`SnapReport`	Per-snap diagnostics (distance, time, resolution, tolerance)
`ConstraintSurface`	Object-safe trait for multi-manifold composition
`MultiManifold`	Compose multiple constraint surfaces with conflict resolution

Quick Start

use constraint_theory_core::{PythagoreanManifold, ResolutionConfig, AdaptiveTolerance};

let config = ResolutionConfig::medium();
let manifold = PythagoreanManifold::new(config, Box::new(AdaptiveTolerance { k: 1.0 }));

// Snap a value to the nearest Pythagorean triple
let report = manifold.snap(5.1)?;
println!("Snapped to: {:?}", report.nearest_triple);  // (3, 4, 5)
println!("Distance: {}", report.distance_to_manifold);

Holonomy Measurement

use constraint_theory_core::{HolonomyMeter, ResolutionConfig, AdaptiveTolerance, PythagoreanManifold};

let manifold = PythagoreanManifold::new(ResolutionConfig::medium(), Box::new(AdaptiveTolerance { k: 1.0 }));
let meter = HolonomyMeter::new(&manifold, 42);

let result = meter.holonomy_loop(100, 1.0, 0.1)?;
println!("Displacement: {}", result.final_displacement);
println!("Angle drift: {} rad", result.total_angle_drift);

Multi-Manifold

use constraint_theory_core::{MultiManifold, ConflictStrategy, PythagoreanSurface, PythagoreanManifold, ResolutionConfig, AdaptiveTolerance};

let surface = Box::new(PythagoreanSurface::new(
    PythagoreanManifold::new(ResolutionConfig::high(), Box::new(AdaptiveTolerance { k: 1.0 }))
));
let multi = MultiManifold::new(vec![surface], ConflictStrategy::Nearest);

Architecture

TolerancePolicy (trait)
  ├─ AdaptiveTolerance  (ε = k/c)
  └─ FixedTolerance     (ε = constant)

PythagoreanManifold
  ├─ snap() → Result<SnapReport, SnapError>
  └─ hint_region()

HolonomyMeter
  ├─ holonomy_loop() → HolonomyResult
  └─ survey()

ConstraintSurface (trait)
  ├─ PythagoreanSurface (adapter)
  └─ MultiManifold (composition)

License

MIT

constraint-theory-core 2.0.0