44f7258b16
Stop wave/Third-Door physics from bypassing native dispatch: - Route geometric_product / versor_apply / versor_condition / cga_inner through algebra.backend in wave_manifold, goldtether, trajectory, dynamic_manifold, surprise, holographic_vault, atlas_packing, biography, self_authorship. - Backend: dtype-aware Rust use — f32 workloads use core_rs; f64 wave residual pins keep Python SOT until f64 GP parity exists. Coerce arrays for PyO3 bindings; fail soft to Python. - AST hygiene pin: tests/test_physics_backend_dispatch_hygiene.py - Docs: RUST.md, runtime_contracts, fidelity (ADR-0235 / UMA hygiene). Verified: wave + cohesion suites green default and CORE_BACKEND=rust (with core_rs built). MLX still exploratory off-serve.
131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
# Rust Extension (core-rs)
|
|
|
|
## Physics hot-path hygiene (P11a)
|
|
|
|
Third-Door / ADR-0241 physics modules must import Cl(4,1) multiplies and
|
|
closure residual helpers from **`algebra.backend`**, not directly from
|
|
`algebra.cl41` / `algebra.versor` / `algebra.cga` for:
|
|
|
|
- `geometric_product`
|
|
- `versor_apply`
|
|
- `versor_condition`
|
|
- `cga_inner`
|
|
|
|
Pinned by `tests/test_physics_backend_dispatch_hygiene.py`.
|
|
|
|
```bash
|
|
# Default: pure Python (semantic SOT)
|
|
uv run pytest tests/test_adr_0241_wave_manifold.py -q
|
|
|
|
# Apple Silicon / native acceleration (after maturin build)
|
|
export CORE_BACKEND=rust
|
|
uv run --with maturin maturin develop --release --manifest-path core-rs/Cargo.toml
|
|
uv run python -c "from algebra.backend import using_rust; assert using_rust()"
|
|
```
|
|
|
|
MLX remains an **exploratory** UMA lane (ADR-0235); not required for serving.
|
|
|
|
|
|
## Why Rust
|
|
|
|
The active Rust extension is an opt-in native substrate for parity-gated hot
|
|
paths, not a shadow cognition path. These operations currently justify Rust:
|
|
|
|
1. `geometric_product` — O(32^2) = 1024 multiply-adds per call, called 2-3x per `versor_apply`
|
|
2. `vault_recall` scan — O(N) CGA inner product calls, N = all stored versors, called during generation recall
|
|
3. `cga_inner` — called by vocabulary/proposition nearest selection and vault recall
|
|
4. `diffusion_step` — zero-copy graph diffusion over `(N, 32)` field buffers
|
|
|
|
None of the Python fallback paths release the Python GIL. Rayon gives
|
|
`vault_recall` true multithreaded parallelism across CPU cores. The geometric
|
|
product loop is cache-friendly and compiler-optimized in release mode.
|
|
|
|
## What is in Rust
|
|
|
|
| Module | Rust file | Why |
|
|
|---|---|---|
|
|
| Cl(4,1) product | `cl41.rs` | Hot inner loop, 1024 MADs |
|
|
| Versor ops | `versor.rs` | 3x geometric product per field step |
|
|
| CGA inner product | `cga.rs` | Called by nearest search and recall |
|
|
| Vault top-k scan | `vault.rs` | Rayon parallel scan |
|
|
| Graph diffusion | `diffusion.rs` | Zero-copy field graph step |
|
|
|
|
## What stays in Python
|
|
|
|
| Layer | Why |
|
|
|---|---|
|
|
| `VocabManifold` | Word/morphology/language metadata and exact candidate filtering |
|
|
| `SessionContext` | Orchestration, not arithmetic |
|
|
| `FieldState` | Plain dataclass |
|
|
| `PersonaMotor` | Motor construction is infrequent |
|
|
| `holonomy_encode` | Python-canonical until a native port proves byte-for-byte parity with position-rotor/f64 construction semantics |
|
|
| `propagate_batch` | Not an active runtime surface; future native propagation must use closure-preserving `versor_apply` semantics |
|
|
|
|
## Buffer Semantics
|
|
|
|
Scalar multivector bindings validate numpy-compatible arrays of length 32,
|
|
copy them into fixed stack arrays, execute the kernel, and return a new numpy
|
|
array. Bulk bindings (`vault_recall`, `diffusion_step`) consume contiguous
|
|
numpy buffers via `PyReadonlyArray` views so they avoid Python-list marshalling.
|
|
The Python fallback remains behaviorally available when `core_rs` is not
|
|
installed or `CORE_BACKEND=rust` is not explicit. A fresh root install is
|
|
therefore correct without the native extension, but not mechanically optimal.
|
|
|
|
## Build / Activate
|
|
|
|
Requires a Rust toolchain and maturin. Prefer the uv-native flow so the repo does not depend on `pip` being installed inside `.venv`:
|
|
|
|
```bash
|
|
core rust status
|
|
core rust test
|
|
core rust build
|
|
core rust status --require-active
|
|
```
|
|
|
|
`core rust build` and `core rust test` set
|
|
`PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1` for their subprocesses so PyO3 0.21 can
|
|
build from Python 3.13+ uv environments. Operators who need a specific Python
|
|
interpreter can still override with `PYO3_PYTHON`.
|
|
|
|
Equivalent explicit maturin command:
|
|
|
|
```bash
|
|
uv run --with maturin maturin develop --release --manifest-path core-rs/Cargo.toml
|
|
```
|
|
|
|
Verify Rust backend is active from Python:
|
|
|
|
```bash
|
|
uv run python -c "from algebra.backend import using_rust; print(using_rust())"
|
|
```
|
|
|
|
Expected:
|
|
|
|
```text
|
|
True
|
|
```
|
|
|
|
## Running Rust Tests
|
|
|
|
```bash
|
|
core rust test
|
|
# or
|
|
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 cargo test --release --manifest-path core-rs/Cargo.toml
|
|
```
|
|
|
|
## Type Safety Contract
|
|
|
|
All multivectors entering the Rust layer must be numpy-compatible `float32` arrays of length 32. Type errors surface as Python `ValueError` rather than silent memory corruption.
|
|
|
|
## Failure Mode
|
|
|
|
If `core_rs` is absent or fails to import, `algebra.backend` silently falls back to Python. This keeps the engine correct but not mechanically optimal. Use:
|
|
|
|
```bash
|
|
core doctor
|
|
core doctor --rust --require-rust
|
|
```
|
|
|
|
`core doctor` reports whether `core_rs` is importable without failing the Python
|
|
runtime. `core doctor --rust --require-rust` fails fast when benchmarking or
|
|
profiling requires the Rust backend.
|