icydb-core 0.144.13

//! Module: diagnostics::execution_trace
//! Responsibility: execution trace contracts and mutation boundaries.
//! Does not own: execution routing policy or stream/materialization behavior.
//! Boundary: shared trace surface used by executor and response APIs.

use crate::db::query::plan::OrderDirection;

///
/// ExecutionOptimization
///
/// Load optimization label selected during execution and recorded in
/// diagnostics traces.
/// Diagnostics owns the DTO; executor code only chooses which label to attach.
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ExecutionOptimization {
    PrimaryKey,
    PrimaryKeyTopNSeek,
    SecondaryOrderPushdown,
    SecondaryOrderTopNSeek,
    IndexRangeLimitPushdown,
}

///
/// ExecutionStats
///
/// Diagnostics-owned operator stats snapshot for one traced query execution.
/// Executor profiling maps its internal counters into this DTO at the trace
/// boundary so diagnostics does not depend on executor-owned types.
///

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct ExecutionStats {
    rows_scanned_pre_filter: u64,
    rows_after_predicate: u64,
    rows_after_projection: u64,
    rows_after_distinct: u64,
    rows_sorted: u64,
    keys_streamed: u64,
    key_stream_micros: u64,
    ordering_micros: u64,
    projection_micros: u64,
    aggregation_micros: u64,
}

impl ExecutionStats {
    /// Build one diagnostics stats DTO from already-normalized counters.
    #[must_use]
    #[expect(
        clippy::too_many_arguments,
        reason = "diagnostics stats DTO exposes the exact flat trace counter surface"
    )]
    pub(in crate::db) const fn new(
        rows_scanned_pre_filter: u64,
        rows_after_predicate: u64,
        rows_after_projection: u64,
        rows_after_distinct: u64,
        rows_sorted: u64,
        keys_streamed: u64,
        key_stream_micros: u64,
        ordering_micros: u64,
        projection_micros: u64,
        aggregation_micros: u64,
    ) -> Self {
        Self {
            rows_scanned_pre_filter,
            rows_after_predicate,
            rows_after_projection,
            rows_after_distinct,
            rows_sorted,
            keys_streamed,
            key_stream_micros,
            ordering_micros,
            projection_micros,
            aggregation_micros,
        }
    }

    /// Return rows encountered before post-access predicate filtering.
    #[must_use]
    #[cfg_attr(
        not(test),
        expect(
            dead_code,
            reason = "execution profiling accessors are consumed by crate tests and diagnostics tooling"
        )
    )]
    pub(in crate::db) const fn rows_scanned_pre_filter(&self) -> u64 {
        self.rows_scanned_pre_filter
    }

    /// Return rows retained after predicate filtering.
    #[must_use]
    #[cfg_attr(
        not(test),
        expect(
            dead_code,
            reason = "execution profiling accessors are consumed by crate tests and diagnostics tooling"
        )
    )]
    pub(in crate::db) const fn rows_after_predicate(&self) -> u64 {
        self.rows_after_predicate
    }

    /// Return rows retained after final projection/materialization.
    #[must_use]
    #[cfg_attr(
        not(test),
        expect(
            dead_code,
            reason = "execution profiling accessors are consumed by crate tests and diagnostics tooling"
        )
    )]
    pub(in crate::db) const fn rows_after_projection(&self) -> u64 {
        self.rows_after_projection
    }

    /// Return rows retained after DISTINCT processing when applicable.
    #[must_use]
    #[expect(
        dead_code,
        reason = "execution profiling records this for diagnostics consumers before response exposure"
    )]
    pub(in crate::db) const fn rows_after_distinct(&self) -> u64 {
        self.rows_after_distinct
    }

    /// Return rows submitted to in-memory ordering.
    #[must_use]
    #[expect(
        dead_code,
        reason = "execution profiling records this for diagnostics consumers before response exposure"
    )]
    pub(in crate::db) const fn rows_sorted(&self) -> u64 {
        self.rows_sorted
    }

    /// Return number of physical keys yielded by ordered key streams.
    #[must_use]
    #[cfg_attr(
        not(test),
        expect(
            dead_code,
            reason = "execution profiling accessors are consumed by crate tests and diagnostics tooling"
        )
    )]
    pub(in crate::db) const fn keys_streamed(&self) -> u64 {
        self.keys_streamed
    }

    /// Return microseconds spent polling ordered key streams.
    #[must_use]
    #[expect(
        dead_code,
        reason = "execution profiling records this for diagnostics consumers before response exposure"
    )]
    pub(in crate::db) const fn key_stream_micros(&self) -> u64 {
        self.key_stream_micros
    }

    /// Return microseconds spent in in-memory ordering.
    #[must_use]
    #[expect(
        dead_code,
        reason = "execution profiling records this for diagnostics consumers before response exposure"
    )]
    pub(in crate::db) const fn ordering_micros(&self) -> u64 {
        self.ordering_micros
    }

    /// Return microseconds spent finalizing projection payloads.
    #[must_use]
    #[expect(
        dead_code,
        reason = "execution profiling records this for diagnostics consumers before response exposure"
    )]
    pub(in crate::db) const fn projection_micros(&self) -> u64 {
        self.projection_micros
    }

    /// Return microseconds spent in grouped aggregation fold work.
    #[must_use]
    #[expect(
        dead_code,
        reason = "execution profiling records this for diagnostics consumers before response exposure"
    )]
    pub(in crate::db) const fn aggregation_micros(&self) -> u64 {
        self.aggregation_micros
    }
}

#[cfg_attr(
    doc,
    doc = "ExecutionAccessPathVariant\n\nCoarse access path shape recorded in execution traces."
)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ExecutionAccessPathVariant {
    ByKey,
    ByKeys,
    KeyRange,
    IndexPrefix,
    IndexMultiLookup,
    IndexRange,
    FullScan,
    Union,
    Intersection,
}

#[cfg_attr(
    doc,
    doc = "ExecutionTrace\n\nStructured execution trace snapshot for one load path.\nCaptures plan shape and counters without affecting behavior."
)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ExecutionTrace {
    pub(crate) access_path_variant: ExecutionAccessPathVariant,
    pub(crate) direction: OrderDirection,
    pub(crate) optimization: Option<ExecutionOptimization>,
    pub(crate) keys_scanned: u64,
    pub(crate) rows_materialized: u64,
    pub(crate) rows_returned: u64,
    pub(crate) execution_time_micros: u64,
    pub(crate) index_only: bool,
    pub(crate) continuation_applied: bool,
    pub(crate) index_predicate_applied: bool,
    pub(crate) index_predicate_keys_rejected: u64,
    pub(crate) distinct_keys_deduped: u64,
    pub(crate) execution_stats: Option<ExecutionStats>,
}

#[cfg_attr(
    doc,
    doc = "ExecutionMetrics\n\nCompact metrics view derived from one `ExecutionTrace`.\nKept small for lightweight observability surfaces."
)]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ExecutionMetrics {
    pub(crate) rows_scanned: u64,
    pub(crate) rows_materialized: u64,
    pub(crate) execution_time_micros: u64,
    pub(crate) index_only: bool,
}

impl ExecutionTrace {
    /// Build one trace payload from an executor-projected access shape.
    #[must_use]
    pub(crate) const fn new_from_variant(
        access_path_variant: ExecutionAccessPathVariant,
        direction: OrderDirection,
        continuation_applied: bool,
    ) -> Self {
        Self {
            access_path_variant,
            direction,
            optimization: None,
            keys_scanned: 0,
            rows_materialized: 0,
            rows_returned: 0,
            execution_time_micros: 0,
            index_only: false,
            continuation_applied,
            index_predicate_applied: false,
            index_predicate_keys_rejected: 0,
            distinct_keys_deduped: 0,
            execution_stats: None,
        }
    }

    /// Apply one finalized path outcome to this trace snapshot.
    #[expect(clippy::too_many_arguments)]
    pub(in crate::db) fn set_path_outcome(
        &mut self,
        optimization: Option<ExecutionOptimization>,
        keys_scanned: usize,
        rows_materialized: usize,
        rows_returned: usize,
        execution_time_micros: u64,
        index_only: bool,
        index_predicate_applied: bool,
        index_predicate_keys_rejected: u64,
        distinct_keys_deduped: u64,
    ) {
        self.optimization = optimization;
        self.keys_scanned = u64::try_from(keys_scanned).unwrap_or(u64::MAX);
        self.rows_materialized = u64::try_from(rows_materialized).unwrap_or(u64::MAX);
        self.rows_returned = u64::try_from(rows_returned).unwrap_or(u64::MAX);
        self.execution_time_micros = execution_time_micros;
        self.index_only = index_only;
        self.index_predicate_applied = index_predicate_applied;
        self.index_predicate_keys_rejected = index_predicate_keys_rejected;
        self.distinct_keys_deduped = distinct_keys_deduped;
        debug_assert_eq!(
            self.keys_scanned,
            u64::try_from(keys_scanned).unwrap_or(u64::MAX),
            "execution trace keys_scanned must match rows_scanned metrics input",
        );
    }

    /// Attach optional operator-level execution stats to this trace.
    pub(in crate::db) const fn set_execution_stats(&mut self, stats: Option<ExecutionStats>) {
        self.execution_stats = stats;
    }

    /// Return compact execution metrics for pre-EXPLAIN observability surfaces.
    #[must_use]
    pub const fn metrics(&self) -> ExecutionMetrics {
        ExecutionMetrics {
            rows_scanned: self.keys_scanned,
            rows_materialized: self.rows_materialized,
            execution_time_micros: self.execution_time_micros,
            index_only: self.index_only,
        }
    }

    /// Return the coarse executed access-path variant.
    #[must_use]
    pub const fn access_path_variant(&self) -> ExecutionAccessPathVariant {
        self.access_path_variant
    }

    /// Return executed order direction.
    #[must_use]
    pub const fn direction(&self) -> OrderDirection {
        self.direction
    }

    /// Return selected optimization, if any.
    #[must_use]
    pub const fn optimization(&self) -> Option<ExecutionOptimization> {
        self.optimization
    }

    /// Return number of keys scanned.
    #[must_use]
    pub const fn keys_scanned(&self) -> u64 {
        self.keys_scanned
    }

    /// Return number of rows materialized.
    #[must_use]
    pub const fn rows_materialized(&self) -> u64 {
        self.rows_materialized
    }

    /// Return number of rows returned.
    #[must_use]
    pub const fn rows_returned(&self) -> u64 {
        self.rows_returned
    }

    /// Return execution time in microseconds.
    #[must_use]
    pub const fn execution_time_micros(&self) -> u64 {
        self.execution_time_micros
    }

    /// Return whether execution remained index-only.
    #[must_use]
    pub const fn index_only(&self) -> bool {
        self.index_only
    }

    /// Return whether continuation was applied.
    #[must_use]
    pub const fn continuation_applied(&self) -> bool {
        self.continuation_applied
    }

    /// Return whether index predicate pushdown was applied.
    #[must_use]
    pub const fn index_predicate_applied(&self) -> bool {
        self.index_predicate_applied
    }

    /// Return number of keys rejected by index predicate pushdown.
    #[must_use]
    pub const fn index_predicate_keys_rejected(&self) -> u64 {
        self.index_predicate_keys_rejected
    }

    /// Return number of deduplicated keys under DISTINCT processing.
    #[must_use]
    pub const fn distinct_keys_deduped(&self) -> u64 {
        self.distinct_keys_deduped
    }

    /// Return optional operator-level execution stats for this trace.
    #[must_use]
    #[cfg_attr(
        not(test),
        expect(
            dead_code,
            reason = "execution stats are an internal diagnostics/testing surface"
        )
    )]
    pub(in crate::db) const fn execution_stats(&self) -> Option<ExecutionStats> {
        self.execution_stats
    }
}

impl ExecutionMetrics {
    /// Return number of rows scanned.
    #[must_use]
    pub const fn rows_scanned(&self) -> u64 {
        self.rows_scanned
    }

    /// Return number of rows materialized.
    #[must_use]
    pub const fn rows_materialized(&self) -> u64 {
        self.rows_materialized
    }

    /// Return execution time in microseconds.
    #[must_use]
    pub const fn execution_time_micros(&self) -> u64 {
        self.execution_time_micros
    }

    /// Return whether execution remained index-only.
    #[must_use]
    pub const fn index_only(&self) -> bool {
        self.index_only
    }
}