ruka_types/

coercion.rs

use crate::{normalize_ty, normalize_ty_with_access, AccessMode, BaseTy, NormalizedTy, Ty};

/// Coercion decision returned by the normalized compatibility table.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CoercionDecision {
    /// Source and destination are incompatible.
    Denied,
    /// Source and destination are compatible.
    Allowed {
        /// Whether both normalized types are identical.
        exact: bool,
        /// Runtime check requirement for this coercion.
        check: CheckPolicy,
        /// Materialization requirement for this coercion.
        materialization: MaterializationPolicy,
    },
}

/// Runtime check requirement for one coercion.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CheckPolicy {
    /// No runtime check is required.
    None,
    /// Runtime check is required, identified by kind.
    Runtime(RuntimeCheckKind),
}

/// Runtime check category used by coercion planning.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RuntimeCheckKind {
    /// Requires `len == expected_len`.
    LenEquals {
        /// Required exact sequence length.
        expected_len: usize,
    },
    /// Requires `len >= min_len`.
    LenAtLeast {
        /// Required minimum sequence length.
        min_len: usize,
    },
}

/// Materialization requirement for one coercion.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MaterializationPolicy {
    /// No materialization is required.
    None,
    /// Materialization is required, identified by kind.
    Required(MaterializationKind),
}

/// Materialization category used by lowering.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum MaterializationKind {
    /// Coercion materializes a read-only view from an owned source value.
    ViewFromOwned,
    /// Coercion materializes a dynamic owned array from a static owned array.
    DynamicArrayFromStaticArray,
    /// Coercion materializes a static owned array from a dynamic owned array.
    StaticArrayFromDynamicArray,
}

impl CoercionDecision {
    /// Return whether this coercion is accepted.
    pub fn is_allowed(&self) -> bool {
        matches!(self, Self::Allowed { .. })
    }

    /// Return whether this coercion requires a runtime check.
    pub fn requires_runtime_check(&self) -> bool {
        matches!(
            self,
            Self::Allowed {
                check: CheckPolicy::Runtime(_),
                ..
            }
        )
    }

    /// Return whether this coercion requires representation materialization.
    pub fn requires_materialization(&self) -> bool {
        matches!(
            self,
            Self::Allowed {
                materialization: MaterializationPolicy::Required(_),
                ..
            }
        )
    }
}

/// Compute normalized coercion compatibility for two semantic types.
pub fn ty_coercion_decision(expected: &Ty, actual: &Ty) -> CoercionDecision {
    let Ok(expected_norm) = normalize_ty(expected) else {
        return CoercionDecision::Denied;
    };
    let Ok(actual_norm) = normalize_ty(actual) else {
        return CoercionDecision::Denied;
    };
    normalized_coercion_decision(&expected_norm, &actual_norm)
}

/// Compute coercion compatibility for one boundary where access mode is tracked separately.
pub fn boundary_coercion_decision(
    expected_access: AccessMode,
    expected_ty: &Ty,
    actual_access: AccessMode,
    actual_ty: &Ty,
) -> CoercionDecision {
    let Ok(expected_norm) = normalize_ty_with_access(expected_ty, expected_access) else {
        return CoercionDecision::Denied;
    };
    let Ok(actual_norm) = normalize_ty_with_access(actual_ty, actual_access) else {
        return CoercionDecision::Denied;
    };
    normalized_coercion_decision(&expected_norm, &actual_norm)
}

/// Compute coercion compatibility for two normalized types.
pub fn normalized_coercion_decision(
    expected: &NormalizedTy,
    actual: &NormalizedTy,
) -> CoercionDecision {
    if expected == actual {
        return CoercionDecision::Allowed {
            exact: true,
            check: CheckPolicy::None,
            materialization: MaterializationPolicy::None,
        };
    }

    match (expected.access, actual.access) {
        (AccessMode::Owned, AccessMode::Owned) => owned_coercion(&expected.base, &actual.base),
        (AccessMode::View, AccessMode::Owned) => {
            view_from_owned_coercion(&expected.base, &actual.base)
        }
        (AccessMode::View, AccessMode::View) | (AccessMode::MutBorrow, AccessMode::MutBorrow) => {
            borrow_like_coercion(&expected.base, &actual.base)
        }
        _ => CoercionDecision::Denied,
    }
}

/// Return one non-exact allowed coercion with provided policies.
fn allowed(check: CheckPolicy, materialization: MaterializationPolicy) -> CoercionDecision {
    CoercionDecision::Allowed {
        exact: false,
        check,
        materialization,
    }
}

/// Compute one owned-to-owned base coercion decision.
fn owned_coercion(expected: &BaseTy, actual: &BaseTy) -> CoercionDecision {
    match (expected, actual) {
        (
            BaseTy::DynamicArray(expected_item),
            BaseTy::StaticArray {
                item: actual_item, ..
            },
        ) if expected_item == actual_item => allowed(
            CheckPolicy::None,
            MaterializationPolicy::Required(MaterializationKind::DynamicArrayFromStaticArray),
        ),
        (
            BaseTy::StaticArray {
                item: expected_item,
                len,
            },
            BaseTy::DynamicArray(actual_item),
        ) if expected_item == actual_item => allowed(
            CheckPolicy::Runtime(RuntimeCheckKind::LenEquals { expected_len: *len }),
            MaterializationPolicy::Required(MaterializationKind::StaticArrayFromDynamicArray),
        ),
        (BaseTy::Option(expected_item), BaseTy::Option(actual_item)) => {
            nested_owned_compatible(expected_item, actual_item)
        }
        (BaseTy::Tuple(expected_items), BaseTy::Tuple(actual_items)) => {
            nested_tuple_owned_compatible(expected_items, actual_items)
        }
        _ if expected == actual => allowed(CheckPolicy::None, MaterializationPolicy::None),
        _ => CoercionDecision::Denied,
    }
}

/// Compute one view-from-owned coercion decision.
fn view_from_owned_coercion(expected: &BaseTy, actual: &BaseTy) -> CoercionDecision {
    match (expected, actual) {
        (BaseTy::Slice(expected_item), BaseTy::StaticArray { item, .. })
            if expected_item == item =>
        {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (BaseTy::Slice(expected_item), BaseTy::DynamicArray(actual_item))
            if expected_item == actual_item =>
        {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (
            BaseTy::StaticSlice {
                item: expected_item,
                len: expected_len,
            },
            BaseTy::StaticArray {
                item: actual_item,
                len: actual_len,
            },
        ) if expected_item == actual_item && actual_len >= expected_len => {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (
            BaseTy::StaticSlice {
                item: expected_item,
                len,
            },
            BaseTy::DynamicArray(actual_item),
        ) if expected_item == actual_item => allowed(
            CheckPolicy::Runtime(RuntimeCheckKind::LenAtLeast { min_len: *len }),
            MaterializationPolicy::None,
        ),
        _ if expected == actual => allowed(
            CheckPolicy::None,
            MaterializationPolicy::Required(MaterializationKind::ViewFromOwned),
        ),
        _ => CoercionDecision::Denied,
    }
}

/// Compute one borrow/view coercion decision where destination expects a view-like access mode.
fn borrow_like_coercion(expected: &BaseTy, actual: &BaseTy) -> CoercionDecision {
    match (expected, actual) {
        (BaseTy::Slice(expected_item), BaseTy::StaticArray { item, .. })
            if expected_item == item =>
        {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (BaseTy::Slice(expected_item), BaseTy::StaticSlice { item, .. })
            if expected_item == item =>
        {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (
            BaseTy::StaticSlice {
                item: expected_item,
                len: expected_len,
            },
            BaseTy::StaticArray {
                item: actual_item,
                len: actual_len,
            },
        ) if expected_item == actual_item && actual_len >= expected_len => {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (
            BaseTy::StaticSlice {
                item: expected_item,
                len: expected_len,
            },
            BaseTy::StaticSlice {
                item: actual_item,
                len: actual_len,
            },
        ) if expected_item == actual_item && actual_len >= expected_len => {
            allowed(CheckPolicy::None, MaterializationPolicy::None)
        }
        (
            BaseTy::StaticSlice {
                item: expected_item,
                len,
            },
            BaseTy::Slice(actual_item),
        ) if expected_item == actual_item => allowed(
            CheckPolicy::Runtime(RuntimeCheckKind::LenAtLeast { min_len: *len }),
            MaterializationPolicy::None,
        ),
        _ if expected == actual => allowed(CheckPolicy::None, MaterializationPolicy::None),
        _ => CoercionDecision::Denied,
    }
}

/// Return one nested owned compatibility decision for one option payload.
fn nested_owned_compatible(expected: &BaseTy, actual: &BaseTy) -> CoercionDecision {
    let decision = owned_coercion(expected, actual);
    if matches!(
        decision,
        CoercionDecision::Allowed {
            check: CheckPolicy::None,
            materialization: MaterializationPolicy::None,
            ..
        }
    ) {
        decision
    } else {
        CoercionDecision::Denied
    }
}

/// Return one nested owned compatibility decision for one tuple payload.
fn nested_tuple_owned_compatible(
    expected_items: &[BaseTy],
    actual_items: &[BaseTy],
) -> CoercionDecision {
    if expected_items.len() != actual_items.len() {
        return CoercionDecision::Denied;
    }
    for (expected_item, actual_item) in expected_items.iter().zip(actual_items.iter()) {
        if !matches!(
            nested_owned_compatible(expected_item, actual_item),
            CoercionDecision::Allowed { .. }
        ) {
            return CoercionDecision::Denied;
        }
    }
    allowed(CheckPolicy::None, MaterializationPolicy::None)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn accepts_exact_types() {
        let decision = ty_coercion_decision(&Ty::I64, &Ty::I64);
        assert_eq!(
            decision,
            CoercionDecision::Allowed {
                exact: true,
                check: CheckPolicy::None,
                materialization: MaterializationPolicy::None,
            }
        );
    }

    #[test]
    fn accepts_slice_from_array() {
        let decision = ty_coercion_decision(
            &Ty::Slice(Box::new(Ty::I64)),
            &Ty::Array {
                item: Box::new(Ty::I64),
                len: 4,
            },
        );
        assert_eq!(
            decision,
            CoercionDecision::Allowed {
                exact: false,
                check: CheckPolicy::None,
                materialization: MaterializationPolicy::Required(
                    MaterializationKind::DynamicArrayFromStaticArray
                ),
            }
        );
    }

    #[test]
    fn rejects_access_mismatch() {
        let decision = normalized_coercion_decision(
            &NormalizedTy {
                base: BaseTy::I64,
                access: AccessMode::MutBorrow,
            },
            &NormalizedTy {
                base: BaseTy::I64,
                access: AccessMode::Owned,
            },
        );
        assert_eq!(decision, CoercionDecision::Denied);
    }

    #[test]
    fn marks_view_from_owned_as_materialization_required() {
        let decision = normalized_coercion_decision(
            &NormalizedTy {
                base: BaseTy::I64,
                access: AccessMode::View,
            },
            &NormalizedTy {
                base: BaseTy::I64,
                access: AccessMode::Owned,
            },
        );
        assert_eq!(
            decision,
            CoercionDecision::Allowed {
                exact: false,
                check: CheckPolicy::None,
                materialization: MaterializationPolicy::Required(
                    MaterializationKind::ViewFromOwned
                ),
            }
        );
    }

    #[test]
    fn boundary_decision_tracks_view_from_owned_policy() {
        let decision =
            boundary_coercion_decision(AccessMode::View, &Ty::I64, AccessMode::Owned, &Ty::I64);
        assert_eq!(
            decision,
            CoercionDecision::Allowed {
                exact: false,
                check: CheckPolicy::None,
                materialization: MaterializationPolicy::Required(
                    MaterializationKind::ViewFromOwned
                ),
            }
        );
    }

    #[test]
    fn accepts_nested_option_element_compatibility() {
        let decision = ty_coercion_decision(
            &Ty::Option(Box::new(Ty::Slice(Box::new(Ty::I32)))),
            &Ty::Option(Box::new(Ty::Array {
                item: Box::new(Ty::I32),
                len: 8,
            })),
        );
        assert_eq!(decision, CoercionDecision::Denied);
    }

    #[test]
    fn rejects_tuple_arity_mismatch() {
        let decision = ty_coercion_decision(
            &Ty::Tuple(vec![Ty::I32, Ty::Bool]),
            &Ty::Tuple(vec![Ty::I32]),
        );
        assert_eq!(decision, CoercionDecision::Denied);
    }

    #[test]
    fn rejects_slice_item_type_mismatch() {
        let decision =
            ty_coercion_decision(&Ty::Slice(Box::new(Ty::I64)), &Ty::Slice(Box::new(Ty::U64)));
        assert_eq!(decision, CoercionDecision::Denied);
    }

    #[test]
    fn requires_runtime_check_for_dynamic_to_static_array() {
        let decision = ty_coercion_decision(
            &Ty::Array {
                item: Box::new(Ty::I64),
                len: 4,
            },
            &Ty::Slice(Box::new(Ty::I64)),
        );
        assert!(decision.is_allowed());
        assert!(decision.requires_runtime_check());
        assert!(decision.requires_materialization());
    }

    #[test]
    fn accepts_static_slice_from_slice_with_runtime_len_check() {
        let decision = boundary_coercion_decision(
            AccessMode::View,
            &Ty::Array {
                item: Box::new(Ty::I64),
                len: 4,
            },
            AccessMode::Owned,
            &Ty::Slice(Box::new(Ty::I64)),
        );
        assert_eq!(
            decision,
            CoercionDecision::Allowed {
                exact: false,
                check: CheckPolicy::Runtime(RuntimeCheckKind::LenAtLeast { min_len: 4 }),
                materialization: MaterializationPolicy::None,
            }
        );
    }
}