# 1.0.0 Pre-Release Crate Audit
Tracking document for the per-crate audit effort (0.19.x series) leading to 1.0.0.
---
## amari-core (0.19.0)
**Status:** Complete — pending manual review
### Phase 1 — Critical Bugs (P0)
- **`rotor::power()`** — Was a stub returning identity for all exponents except 1.0 and 2.0. Now implements via `exp(t * log(R))` with edge-case handling for exponent=0 and near-identity rotors.
- **`rotor::logarithm()`** — Was incorrectly scaled ("simplified to match test expectations"). Now properly computes `(θ/2)B̂` by normalizing the bivector part.
- **`rotor::to_rotation_matrix()`** — Was reading wrong basis blade indices (e.g. index 4 for e13 instead of 5). Rewrote to use `apply()` directly on basis vectors, eliminating the error-prone manual index mapping.
- **`verified::compute_product_sign()`** — Was ignoring metric signature entirely. Now applies sign flip for Q-range basis vectors and returns 0 for R-range (null) basis vectors.
- **`verified.rs` — 3 `todo!()` panics in public code paths** (behind default `phantom-types` feature): KVector outer products (grade 1∧2, grade 2∧1) and `VerifiedRotor::apply()`. All implemented.
### Phase 2 — Math Correctness (P1)
- **Hodge dual** — Sign logic was incorrect for degenerate algebras (R-range basis vectors treated same as Q-range). Rewrote using `metric(A) * permutation_sign * e_complement` formula. Verified with double-dual identity tests.
- **Cayley table** — Added full 8×8 verification for Cl(3,0,0) against textbook values.
- **Inner product** — Added tests verifying Hestenes convention for vector-bivector and vector-vector contractions.
### Phase 3 — Unsafe Code (P1)
- **SIMD SSE2** — Removed incomplete `geometric_product_3d_sse2` implementation. AVX2 retained behind `pub(crate)` visibility.
- **`AlignedMemory<T>`** — Added `T: Copy` bound to prevent unsound use with types that have destructors (previously `Drop` impl didn't drop contained values).
- **Visibility** — Changed `pub mod simd` and `pub mod aligned_alloc` to `pub(crate)`.
### Phase 4 — API Surface (P2)
- **`geometric_product_scalar()`** — Changed from `pub` to `pub(crate)` (internal fallback, not part of public API).
- **`.mv` field visibility** — Deferred to 1.0.0. 168 occurrences across 25 downstream files; too widespread to change in this pass.
### Phase 5 — Tests (P2)
- **Test count:** 199 → 227 (+28 tests, 0 ignored, 0 failures)
- **New rotor tests (11):** power fractional/zero/negative/third, e13/e23 plane rotations, 180° rotation, small angle, matrix verification, diagonal axis-angle, slerp endpoints.
- **New audit tests (17):** Hodge dual (basis vectors, bivectors, scalar/pseudoscalar, double-dual, mixed grade), Cayley table, Minkowski Cl(1,3,0), Projective GA Cl(2,0,1), left contraction, inner product, numeric stability (zero normalize, zero inverse, large coefficients, near-zero, identity product, associativity).
- **0 regressions** across full workspace.
### Phase 6 — Cleanup (P3)
- **`verified_laws.rs`** — Implemented 4 `todo!()` helper functions (`scalar_product`, `scalar_product_reverse`, `grade_involution`, `reverse`). These were behind `formal-verification` feature gate.
- **Error handling** — Deferred panic→Result changes for `from_coefficients`/`basis_vector` (too many downstream call sites for 0.19.0).
- **SIMD TODO** — Removed TODO comment from `geometric_product` in lib.rs.
### Files Changed
| `amari-core/src/rotor.rs` | Fixed `power()`, `logarithm()`, rewrote `to_rotation_matrix()` |
| `amari-core/src/verified.rs` | Fixed `compute_product_sign`, implemented 3 `todo!()` methods |
| `amari-core/src/verified_laws.rs` | Implemented 4 `todo!()` helper functions |
| `amari-core/src/lib.rs` | Rewrote Hodge dual, visibility changes, removed SIMD TODO |
| `amari-core/src/simd.rs` | Removed incomplete SSE2 impl, un-ignored test |
| `amari-core/src/aligned_alloc.rs` | Added `T: Copy` bound |
| `amari-core/tests/rotors.rs` | Fixed existing tests, added 11 new tests |
| `amari-core/tests/audit_tests.rs` | **New file** — 17 audit tests |
### GF(2) Algebra Module (new feature)
New `gf2` submodule added to amari-core behind default-on `gf2` feature flag.
Provides the algebraic foundation for binary Grassmannians, binary matroid
representability, and binary-encoded geometric data. Downstream consumers:
amari-enumerative (binary matroid representability, binary Grassmannians).
| `amari-core/src/gf2/mod.rs` | Module root, re-exports |
| `amari-core/src/gf2/scalar.rs` | `GF2` field element — XOR/AND arithmetic, num_traits impls |
| `amari-core/src/gf2/vector.rs` | `GF2Vector` — bit-packed vectors (u64 words), dot product, Hamming weight/distance |
| `amari-core/src/gf2/matrix.rs` | `GF2Matrix` — Gaussian elimination, rank, null space, determinant, solve Ax=b |
| `amari-core/src/gf2/grassmannian.rs` | Gaussian binomial, `enumerate_subspaces` for Gr(k,n;F₂), Schubert cells |
| `amari-core/src/gf2/clifford.rs` | `BinaryMultivector<N,R>` — Cl(N,R;F₂) geometric/outer/inner products, `to_real`/`from_real` conversion bridge |
| `amari-core/tests/gf2_tests.rs` | Cross-module integration tests |
| `amari-core/src/error.rs` | Added `GF2DimensionMismatch`, `GF2NotSquare`, `GF2IndexOutOfBounds` error variants |
| `amari-core/Cargo.toml` | Added `gf2 = []` feature (default on), `rand` dev-dependency |
**Tests:** +49 new GF2 tests (227 → 276 total), 0 regressions.
### Deferred Items (for 1.0.0)
- `.mv` field visibility on Scalar/Vector/Bivector types
- `from_coefficients`/`basis_vector` panic → Result migration
- Full documentation pass
- Benchmarks
---
## amari-enumerative — GF(2) Extensions
**Status:** Complete — pending manual review (same PR #98)
### New Modules
| `finite_field.rs` | F_q point counting, Poincaré polynomials, Schubert varieties over finite fields |
| `representability.rs` | Matroid representability over GF(2)/GF(3)/GF(q), excluded minor checks, Fano/dual-Fano |
| `weight_enumerator.rs` | Binary linear codes, weight enumerators, MacWilliams duality, Hamming/Reed-Muller/Golay codes, coding bounds |
| `kazhdan_lusztig.rs` | KL polynomials, Z-polynomials, inverse KL polynomials for matroids |
### Extended Modules
| `matroid.rs` | `characteristic_polynomial`, lattice of flats, `closure`, `mobius_values`, Whitney numbers, `f_vector`/`h_vector`, `restrict`, `contraction_deletion`, `is_connected`, `connected_components`, `has_excluded_minor` |
| `localization.rs` | `fq_point_count`, `atiyah_bott_intersection`, `schubert_restriction` |
| `lib.rs` | 4 new error variants, module declarations, re-exports |
| `Cargo.toml` | `gf2 = ["amari-core/gf2"]` feature |
### Tests
- **Test count:** 345 → 388 (+43 new tests across lib + 4 new integration test files)
- **Integration tests:** `finite_field_tests.rs`, `representability_tests.rs`, `weight_enumerator_tests.rs`, `kazhdan_lusztig_tests.rs`
- **Bug fixed:** `is_self_dual()` was using `in_column_space` with dimension mismatch; rewrote to use `G·G^T = 0` check
- **0 regressions** across full workspace
---
## Remaining Crates
Audit sequence (bottom-up by dependency depth):
| 1 | amari-core | 276 | **Complete** (audit + GF(2) module) |
| 2 | amari-enumerative | 388 | **Complete** (GF(2) extensions) |
| 3 | amari-flynn-macros | 6 | Pending |
| 4 | amari-dual | 29 | Pending |
| 5 | amari-tropical | 28 | Pending |
| 6 | amari-holographic | 52 | Pending |
| 7 | amari-info-geom | 125 | Pending |
| 8 | amari-relativistic | 99 | Pending |
| 9 | amari-flynn | 27 | Pending |
| 10 | amari-measure | 84 | Pending |
| 11 | amari-network | 21 | Pending |
| 12 | amari-calculus | 160 | Pending |
| 13 | amari-automata | 69 | Pending |
| 14 | amari-fusion | 117 | Pending |
| 15 | amari-topology | 51 | Pending |
| 16 | amari-functional | 72 | Pending |
| 17 | amari-probabilistic | 102 | Pending |
| 18 | amari-optimization | 74 | Pending |
| 19 | amari-dynamics | 65 | Pending |
| 20 | amari-gpu | 88 | Pending — **needs GPU-equipped overhaul** |
| 21 | amari-wasm | 53 | Pending |
---
## amari-gpu — Known Limitations
**Status:** Requires extensive overhaul on an instance with a modern GPU
The GF(2) GPU bindings (and several pre-existing shaders) were developed and
tested without access to GPU hardware. All GPU-dependent tests are skipped in
the current environment (`BadDisplay` / no `wgpu` adapter). Consequences:
- **WGSL shader workarounds:** WGSL forbids dynamic indexing into local `var`
arrays and function parameter arrays. All GF(2) shaders (and the
representability shader in particular) had to be rewritten with named
variables (`m0..m7`) and if/else chains instead of natural array access.
This makes the shaders harder to read, maintain, and extend. Several
pre-existing shaders also have unresolved validation errors (recursive `gcd`
function, `partition` reserved keyword).
- **No runtime validation:** Shader correctness is verified only by
compilation, not by actual GPU execution. Numeric results have not been
validated against CPU reference implementations on real hardware.
- **Size limits baked in:** Fixed-size arrays (`[u32; 16]`, `[u32; 32]`) and
unrolled loops impose hard caps on problem dimensions that may be
unnecessarily restrictive or insufficiently large, but cannot be tuned
without hardware testing.
**Recommendation:** Before 1.0.0, the entire `amari-gpu` crate should be
audited and tested on an instance with a modern GPU (Vulkan/Metal-capable).
This includes fixing pre-existing shader validation errors, validating all
compute results against CPU baselines, profiling for actual speedups, and
potentially rewriting the WGSL workarounds if `naga` / `wgpu` have relaxed
their indexing restrictions by then.