geoit 0.0.0

# geoit — Exact Geometric Algebra for Rust

A governed geometric algebra engine with exact arithmetic.

**Zero floating-point operations. Zero dependencies. Every answer is exact.**

## What is geoit?

`geoit` is a Clifford algebra computation library that enforces mathematical
correctness through a governance system. You declare what geometric objects look
like (grade constraints, polynomial equations, inequalities), and geoit verifies
every multivector against those declarations before allowing parameter extraction.

The pipeline: **Construct → Govern → Read**

```
Parameters → Construction → Mv → Governance → Geoit → ReadingRules → Parameters
     (x, y)     formula      ↓      verify        ↓     extract        (x, y)
                              └── exact Mv ───────└── proof + phase
```

The circuit must close: what you put in is what you get out.

## Scalar Tower

All arithmetic is exact. No floats anywhere.

| Type | Range | When |
|------|-------|------|
| `Rat` | i128/u128 rational | Default. Fastest. |
| `BigRat` | Arbitrary precision | Automatic on i128 overflow |
| `QuadraticSurd` | a + b√d, a,b ∈ ℚ | Square roots of rationals |
| `AlgebraicNumber` | Root of polynomial over ℚ | Resultant-based arithmetic |

Promotion is automatic. Demotion is attempted after every operation.

## Quick Start

```rust
use geoit::*;
use geoit::scalar::{Scalar, Rat};
use geoit::algebra::signature::Signature;
use geoit::governance::Expr;

// 1. Define the algebra
let alg = Algebra::new(Signature::new(0, 0, 3)); // VGA3

// 2. Build governance
let class = GeomClassBuilder::new(&alg).grades(&[1]).build();
let body = Expr::Add(
    Expr::add(
        Expr::mul(Expr::param(0), Expr::gen(0)),
        Expr::mul(Expr::param(1), Expr::gen(1)),
    ),
    Expr::mul(Expr::param(2), Expr::gen(2)),
);
let gov = GovernanceBuilder::new(alg)
    .class("Vector", class)
    .construction("Vector", "Vector", 3, body)
    .build();

// 3. Use it
let params = vec![Scalar::from(3), Scalar::from(4), Scalar::from(5)];
let mv = gov.construct("Vector", &params).unwrap();
let geoit = gov.govern(&mv, "Vector").unwrap();
assert!(geoit.predicate.is_satisfied());
let extracted = geoit.read_all().unwrap();
assert_eq!(extracted, params); // circuit closes
```

## The `mv!` Macro

```rust
use geoit::mv;

let v = mv![0b001 => 3, 0b010 => 4, 0b100 => 5];  // 3e₀ + 4e₁ + 5e₂
let p = mv![0b01 => 1/2, 0b10 => 1/2];              // ½e₀ + ½e₁
```

## Supported Algebras

Tested across 10 algebra families:

| Algebra | Signature | Generators | Use |
|---------|-----------|------------|-----|
| VGA(2) | Cl(0,0,2) | 2 | 2D Euclidean |
| VGA(3) | Cl(0,0,3) | 3 | 3D Euclidean |
| PGA(2) | Cl(0,1,2) | 3 | 2D projective |
| PGA(3) | Cl(0,1,3) | 4 | 3D projective |
| CGA(2) | Cl(1,0,3) | 4 | 2D conformal |
| CGA(3) | Cl(1,0,4) | 5 | 3D conformal |
| STA-WC | Cl(3,0,1) | 4 | Spacetime (west coast) |
| STA-EC | Cl(1,0,3) | 4 | Spacetime (east coast) |
| QGA(3) | Cl(3,0,6) | 9 | Quadric |
| VGA(5) | Cl(0,0,5) | 5 | 5D Euclidean |

Any signature up to 64 generators is supported.

## Operations

**Products**: geometric, outer (wedge), inner (Hestenes), left/right contraction,
scalar product, commutator, regressive (meet).

**Unary**: reverse, grade involution, Clifford conjugate, dual, undual, grade projection.

**Derived**: sandwich product, norm², inverse (blade/versor/general), normalized sandwich.

**Field ops**: scalar product (IPNS), outer product (OPNS), left contraction,
inner product, geometric product, grade-k projection — all returning full Mv results.

## Known Limitations

- **Surd radicand mismatch**: Adding √2 + √3 panics at the QuadraticSurd level.
  Promote both to AlgebraicNumber first. (Will be addressed when Compass Ruler
  Algebra work lands.)

- **Algebraic degree cap**: AlgebraicNumber operations cap result polynomial degree
  at 32. Operations exceeding this return `AlgebraicError::DegreeCap`. The cap is
  a runtime policy — honest precision loss, not silent truncation.

## License

[Your license here]