Rust Core Handoff

This guide defines the boundary between the Rust core and the language bindings or adapters that sit on top of it.

Architecture decision

• Rust is the authoritative execution core for deterministic VOI kernels, shared result contracts, diagnostics, and reporting envelopes.
• Python remains the primary façade for orchestration, CLI entrypoints, plotting, and compatibility wrappers.
• Python/Mojo, R, Julia, and any future language packages are thin bindings or adapters over the Rust contract.

What stays in Rust core

• Numeric kernels and summary calculations for stable VOI methods
• Domain types (ValueArray, ParameterSet, TrialDesign, typed result envelopes)
• Diagnostics, method metadata, and CHEERS-style reporting payloads
• Serialization and cross-language contract behavior
• Validation for invalid shapes, non-finite values, and duplicate IDs

What stays in bindings

• Parsing native inputs and producing Rust-compatible shapes
• User-facing CLI or package-manager plumbing
• Light validation that improves error messages before the Rust call
• Language-native packaging, release, and registry integration

Current Python compatibility boundary

The stable Python façade delegates these operations to the private PyO3 bridge, with the Rust kernel as the authoritative implementation:

Operation	Native Rust route	Python compatibility path
EVPI	compute_evpi	retained only when the extension is unavailable
EVPPI	compute_evppi for the default full-sample linear contract	retained for custom models, subsampling, chunking, or no extension
EVSI	analytical normal–normal, seeded bootstrap, efficient-linear, and moment-based kernels	Python orchestrates the developing coherent-Gaussian two-loop model; regression, random-forest, adaptive, and NMA semantics remain method-specific
Dominance	compute_dominance	retained only when the extension is unavailable
CEAF	compute_ceaf	retained only when the extension is unavailable

Compatibility fallbacks are transitional and emit a deprecation warning where the fallback represents retired numerical policy. They are not a second authoritative implementation. New deterministic methods must define their Rust contract and parity evidence before being promoted to the stable façade.

Adding a new deterministic method

1. Define the method contract in Rust first.
2. Reuse existing domain types instead of inventing new wire shapes.
3. Return a typed summary or AnalysisEnvelope with diagnostics and reporting.
4. Keep the calculation deterministic and test it against fixed inputs.
5. Add only the smallest wrapper needed in Python or another binding.