icydb-core 0.257.18

//! Module: db::query::plan::access_planner
//! Responsibility: derive the canonical access plan from normalized query
//! intent, predicate, ordering, and planner-visible index metadata.
//! Does not own: executor runtime behavior or final access-choice scoring policy outside planning.
//! Boundary: turns validated logical query intent into planner-owned access plans.

use crate::{
    db::{
        QueryError,
        access::AccessPlan,
        predicate::{Predicate, normalize, normalize_enum_literals},
        query::plan::{
            OrderSpec, PlannedAccessSelection, VisibleIndexes,
            canonicalize_order_spec_for_grouping,
            plan_access_selection_with_order_and_semantic_indexes,
        },
        query::preparation::PreparationWork,
        schema::SchemaInfo,
    },
    value::Value,
};

///
/// AccessPlanningInputs
///
/// Access-planning input contract projected from query intent.
/// Carries the optional predicate and raw order shape.
/// Access planning consumes this contract before logical plan assembly and
/// normalizes order independently of the later logical-plan pass.
///

#[derive(Debug)]
pub(in crate::db::query) struct AccessPlanningInputs<'a> {
    predicate: Option<&'a Predicate>,
    order: Option<&'a OrderSpec>,
}

impl<'a> AccessPlanningInputs<'a> {
    /// Build access-planning inputs from intent-projected values.
    #[must_use]
    pub(in crate::db::query) const fn new(
        predicate: Option<&'a Predicate>,
        order: Option<&'a OrderSpec>,
    ) -> Self {
        Self { predicate, order }
    }

    /// Borrow predicate input for normalization and planner analysis.
    #[must_use]
    pub(in crate::db::query) const fn predicate(&self) -> Option<&'a Predicate> {
        self.predicate
    }

    /// Borrow raw ORDER BY input for planner-side canonicalization.
    #[must_use]
    pub(in crate::db::query) const fn order(&self) -> Option<&'a OrderSpec> {
        self.order
    }
}

// Normalize one optional predicate into canonical planner form.
pub(in crate::db::query) fn normalize_query_predicate(
    schema_info: &SchemaInfo,
    predicate: Option<&Predicate>,
    work: &PreparationWork<'_>,
) -> Result<Option<Predicate>, QueryError> {
    predicate
        .map(|predicate| {
            let predicate = normalize_enum_literals(schema_info, predicate, work)?;

            Ok::<Predicate, QueryError>(normalize(predicate))
        })
        .transpose()
}

/// Select one access plan from accepted schema and accepted semantic indexes.
///
/// Standalone SQL and dynamic reads enter here after accepted catalog
/// selection; generated model metadata is neither required nor consulted.
pub(in crate::db::query) fn plan_query_access_with_accepted_schema(
    visible_indexes: &VisibleIndexes,
    schema_info: &SchemaInfo,
    normalized_predicate: Option<&Predicate>,
    order: Option<&OrderSpec>,
    grouped: bool,
    key_access_override: Option<AccessPlan<Value>>,
    work: &PreparationWork<'_>,
) -> Result<PlannedAccessSelection, QueryError> {
    if let Some(plan) = key_access_override {
        return Ok(PlannedAccessSelection::new(
            plan,
            Some(crate::db::query::plan::PlannedNonIndexAccessReason::IntentKeyAccessOverride),
        ));
    }

    let canonical_order = canonicalize_order_spec_for_grouping(
        schema_info.primary_key_names(),
        order.map(|order| work.copy_order_spec(order)).transpose()?,
        grouped,
        work,
    )?;
    plan_access_selection_with_order_and_semantic_indexes(
        visible_indexes.accepted_semantic_index_contracts(),
        schema_info,
        normalized_predicate,
        canonical_order.as_ref(),
        grouped,
        work,
    )
    .map_err(QueryError::from)
}