# Native Validation Alignment Checklist
This checklist translates the proposed design into concrete file-by-file work items.
Target design:
1. Native `f64` / `Complex<f64>` trait implementations are fast backend adapters.
2. Target: release-mode validation remains mandatory at fallible entry points.
3. Validated wrappers preserve invariants themselves and do not rely on native raw behavior.
## Priority Order
1. Lock down release-validating boundaries.
2. Fix wrapper methods that mutate raw state without revalidation.
3. Align documentation so that native and validated behavior are described separately.
## File-By-File Checklist
## `src/core/types.rs`
Status: highest priority.
Required changes:
- Review `RealValidated<K>::try_from_f64` at [src/core/types.rs](../../src/core/types.rs#L1285).
- Decide one of two contracts:
- either `K::RawReal::try_new_raw_real_from_f64::<K::RealPolicy>` is guaranteed to validate in release
- or `RealValidated<K>::try_from_f64` must revalidate with `Self::try_new_with_policy(...)` before returning
- Revalidate after `RealValidated<K>::kernel_mul_add_mul_mut` at [src/core/types.rs](../../src/core/types.rs#L1255).
- Revalidate after `RealValidated<K>::kernel_mul_sub_mul_mut` at [src/core/types.rs](../../src/core/types.rs#L1263).
- Keep `kernel_copysign` and `kernel_signum` as direct constructors only if the closure argument remains explicit and documented.
Why:
- This is the main wrapper-invariant enforcement layer.
- These are the methods most exposed if native `f64` impls become debug-only.
## `src/backends/native/raw.rs`
Status: policy-definition layer for native behavior.
Required changes:
- Keep non-fallible native delegates as fast paths with no release validation.
- Use `debug_assert!` only where the method contract wants development-time checks.
- Make the contract of `RawRealTrait::try_new_raw_real_from_f64` explicit and consistent.
- Ensure `try_new_raw_real_from_f64` is always-validating in release if wrapper `try_from_f64` continues to trust it.
- Keep mutating methods on raw native complex types (`set_*`, `add_to_*`, `multiply_*`) as debug-only checked if the design goal is backend speed, but document that clearly.
Why:
- This file should define native backend performance behavior, not silently carry validated-wrapper invariants.
## `src/functions/pow.rs`
Status: already close to the target model.
Required changes:
- Use this file as the reference pattern for native raw APIs:
- `try_*` validates in release
- panicking `*` may be debug-checked and release-fast
- Verify the same policy is applied consistently to other native fallible function families if desired.
Why:
- `Pow<&f64> for f64` and `Pow<&f64> for Complex<f64>` already encode the cleanest version of the split.
## `src/functions/complex.rs`
Status: documentation alignment needed.
Required changes:
- Clarify that `ComplexScalarConstructors::try_new_complex` is a validated boundary.
- Clarify that native mutators may only have debug-time finiteness checks unless wrapped by validated types.
- Separate documentation for:
- raw/native complex behavior
- validated wrapper behavior
Why:
- Current docs are semantically too close to “always validated” for operations whose native impls are only debug-checked.
## `src/lib.rs`
Status: high-level contract clarification.
Required changes:
- Keep the “direct delegation / maximum performance” description for native `f64`.
- Add one short sentence making the split explicit:
- native scalar impls are performance-oriented
- validated wrappers are invariant-preserving
- Cross-link to the fallible APIs where release validation is guaranteed.
Why:
- This is the first place contributors and users read when trying to infer semantics.
## `src/macros.rs`
Status: preserve as invariant anchor.
Required changes:
- No semantic weakening to `validated construction`.
- Keep `new_unchecked` explicitly unsafe and debug-only validated.
- If any wrapper constructors are refactored, keep `try_new_with_policy(...)` as the canonical validation path.
Why:
- This file is the stable center of the wrapper validation model.
## `src/core/traits/validation.rs`
Status: keep boundary traits explicit.
Required changes:
- Preserve `ValidateNativeReal` and `ValidateNativeComplex` as release-validating helper traits if wrappers depend on them as boundaries.
- Document clearly that these traits are validation boundaries, not mere debug helpers.
Why:
- If these helpers become debug-only, wrapper constructors and fallible native APIs lose their strongest guarantees.
## `docs/native-validation-matrix.md`
Status: already created, use as behavioral baseline.
Required changes:
- Update after any semantic code change.
- Keep the distinction between native raw behavior and validated wrapper behavior prominent.
## `docs/validated-wrapper-impact-matrix.md`
Status: already created, use as wrapper-risk baseline.
Required changes:
- Update if additional wrapper methods are found to bypass release validation.
- Keep the “methods that especially matter” section synchronized with code.
## Exact `RealValidated` Methods To Revisit
These are the concrete methods to inspect first if you adopt debug-only validation in native `f64` impls.
### Must be corrected or contractually locked down
1. `RealValidated<K>::try_from_f64` in [src/core/types.rs](../../src/core/types.rs#L1285)
2. `RealValidated<K>::kernel_mul_add_mul_mut` in [src/core/types.rs](../../src/core/types.rs#L1255)
3. `RealValidated<K>::kernel_mul_sub_mul_mut` in [src/core/types.rs](../../src/core/types.rs#L1263)
### Likely acceptable as-is, but should be documented as closure-based
1. `RealValidated<K>::kernel_copysign` in [src/core/types.rs](../../src/core/types.rs#L167)
2. `RealValidated<K>::kernel_signum` in [src/core/types.rs](../../src/core/types.rs#L176)
Reason:
- These methods construct `Self` directly without `try_new_with_policy(...)`, but for already-validated finite inputs their outputs remain within the finite native domain.
## Acceptance Criteria
The design is internally coherent when all of the following are true:
1. Every fallible constructor validates in release.
2. Every wrapper mutation that can create invalid raw state revalidates in release.
3. Native non-fallible delegates are allowed to remain release-fast.
4. Documentation distinguishes native fast-path semantics from validated-wrapper semantics.
Current gap note:
- Native `f64::try_from_f64` currently validates only in debug and returns `Ok(value)` in release; treat this as a temporary divergence from the target model until code or contract is finalized.