icydb 0.199.0

//! Module: db::session::load
//!
//! Responsibility: public session and fluent query facade.
//! Does not own: core execution, storage engines, or planner semantics.
//! Boundary: wraps core sessions with stable generated-code and application APIs.

use crate::{
    db::{
        AdminBatchRequest, ExplainAggregateTerminalPlan, ExplainExecutionNodeDescriptor,
        query::{
            AggregateExpr, CompareOp, CompiledQuery, ExplainPlan, FilterExpr, PlannedQuery, Query,
            QueryTracePlan,
        },
        response::{PagedResponse, QueryResponse, Response},
        session::macros::{impl_session_materialization_methods, impl_session_query_shape_methods},
    },
    error::Error,
    traits::{Entity, SingletonEntity},
    types::{Decimal, Id},
    value::InputValue,
};

use icydb_core as core;

///
/// FluentLoadQuery
///
/// Session-bound fluent wrapper for typed load queries.
/// This facade keeps query shaping and execution on the public `icydb`
/// surface while delegating planning and execution to `icydb-core`.
///

pub struct FluentLoadQuery<'a, E: Entity> {
    pub(crate) inner: core::db::FluentLoadQuery<'a, E>,
}

impl<'a, E: Entity> FluentLoadQuery<'a, E> {
    // ------------------------------------------------------------------
    // Intent inspection
    // ------------------------------------------------------------------

    #[doc(hidden)]
    #[must_use]
    pub const fn query(&self) -> &Query<E> {
        self.inner.query()
    }

    // ------------------------------------------------------------------
    // Primary-key access (semantic)
    // ------------------------------------------------------------------

    impl_session_query_shape_methods!();

    // ------------------------------------------------------------------
    // Query refinement
    // ------------------------------------------------------------------

    /// Return a deliberately partial row window.
    ///
    /// This is the hard-cut replacement for raw public read `.limit(...)` on
    /// load queries. Use it only when the endpoint contract is "the first N
    /// rows under this order." Use `page(...)` for public pages,
    /// `collect_complete()` for complete small sets, and exact aggregate
    /// helpers for semantic aggregates.
    #[must_use]
    pub fn partial_window(self, limit: u32) -> PartialWindowLoadQuery<'a, E> {
        PartialWindowLoadQuery {
            inner: self.inner.partial_window(limit),
        }
    }

    /// Mark this fluent read as trusted and bypass the default bounded read gate.
    ///
    /// Use this only for controller/admin maintenance code that has its own
    /// authorization and resource policy. Application-facing reads should stay
    /// on the normal bounded execution path through `execute`, `execute_rows`,
    /// `page(...)`, or terminal helpers.
    #[must_use]
    pub fn trusted_read_unchecked(mut self) -> Self {
        self.inner = self.inner.trusted_read_unchecked();
        self
    }

    /// Add one grouped key field.
    pub fn group_by(mut self, field: impl AsRef<str>) -> Result<Self, Error> {
        self.inner = self.inner.group_by(field)?;
        Ok(self)
    }

    /// Add one grouped aggregate terminal.
    #[must_use]
    pub fn aggregate(mut self, aggregate: AggregateExpr) -> Self {
        self.inner = self.inner.aggregate(aggregate);
        self
    }

    /// Override grouped hard limits for grouped execution budget enforcement.
    #[must_use]
    pub fn grouped_limits(mut self, max_groups: u64, max_group_bytes: u64) -> Self {
        self.inner = self.inner.grouped_limits(max_groups, max_group_bytes);
        self
    }

    /// Add one grouped HAVING compare clause over one grouped key field.
    pub fn having_group(
        mut self,
        field: impl AsRef<str>,
        op: CompareOp,
        value: InputValue,
    ) -> Result<Self, Error> {
        self.inner = self.inner.having_group(field, op, value)?;
        Ok(self)
    }

    /// Add one grouped HAVING compare clause over one grouped aggregate output.
    pub fn having_aggregate(
        mut self,
        aggregate_index: usize,
        op: CompareOp,
        value: InputValue,
    ) -> Result<Self, Error> {
        self.inner = self.inner.having_aggregate(aggregate_index, op, value)?;
        Ok(self)
    }

    // ------------------------------------------------------------------
    // Execution primitives
    // ------------------------------------------------------------------
    impl_session_materialization_methods!();

    /// Execute the first typed cursor page with the requested page size.
    ///
    /// Cursor pagination requires explicit ordering and disallows a prior
    /// `partial_window(...)`. IcyDB clamps the requested page size to the
    /// engine-owned public page cap.
    /// Cursor pagination runs through the default bounded read-admission lane.
    /// Continuation is best-effort and forward-only over live state:
    /// deterministic per request under canonical ordering, with no
    /// snapshot/version pinned across requests.
    pub fn page(self, limit: u32) -> Result<PagedResponse<E>, Error> {
        Ok(Self::paged_response_from_execution(self.inner.page(limit)?))
    }

    /// Execute the next typed cursor page from a previous continuation cursor.
    ///
    /// This is the continuation counterpart to `page(limit)`. The cursor is an
    /// opaque token returned by the previous page response.
    pub fn next_page(
        self,
        limit: u32,
        cursor: impl Into<String>,
    ) -> Result<PagedResponse<E>, Error> {
        Ok(Self::paged_response_from_execution(
            self.inner.next_page(limit, cursor)?,
        ))
    }

    /// Execute a trusted/admin cursor batch with an engine-owned batch size.
    ///
    /// This terminal is only for reads that have already opted into
    /// `trusted_read_unchecked()`. Application-facing list endpoints should
    /// use `page(limit)` / `next_page(limit, cursor)`.
    pub fn admin_batch(self, request: AdminBatchRequest) -> Result<PagedResponse<E>, Error>
    where
        E: Entity,
    {
        Ok(Self::paged_response_from_execution(
            self.inner.admin_batch(request)?,
        ))
    }

    fn paged_response_from_execution(execution: core::db::PagedLoadExecution<E>) -> PagedResponse<E>
    where
        E: Entity,
    {
        let read_intent = execution.read_intent();
        let (response, continuation_cursor) = execution.into_response_and_cursor();
        let next_cursor = continuation_cursor.as_deref().map(core::db::encode_cursor);

        PagedResponse::new(response.entities(), next_cursor, read_intent)
    }

    /// Execute as a scalar row load through the default bounded read-admission
    /// gate.
    ///
    /// Grouped queries return grouped rows through `execute().into_grouped()`;
    /// this method is for scalar entity-row reads.
    pub fn execute_rows(&self) -> Result<Response<E>, Error>
    where
        E: Entity,
    {
        Ok(Response::from_core(self.inner.execute_rows()?))
    }

    /// Return the stable plan hash for this query.
    pub fn plan_hash_hex(&self) -> Result<String, Error> {
        Ok(self.inner.plan_hash_hex()?)
    }

    /// Build one trace payload without executing the query.
    pub fn trace(&self) -> Result<QueryTracePlan, Error> {
        Ok(self.inner.trace()?)
    }

    /// Build the validated logical plan without compiling execution details.
    pub fn planned(&self) -> Result<PlannedQuery<E>, Error> {
        Ok(self.inner.planned()?)
    }

    /// Build the compiled executable plan for this query.
    pub fn plan(&self) -> Result<CompiledQuery<E>, Error> {
        Ok(self.inner.plan()?)
    }

    /// Build logical explain metadata for the current query.
    pub fn explain(&self) -> Result<ExplainPlan, Error> {
        Ok(self.inner.explain()?)
    }

    // ------------------------------------------------------------------
    // Aggregation helpers
    // ------------------------------------------------------------------

    /// Return whether at least one matching row exists.
    pub fn exists(&self) -> Result<bool, Error>
    where
        E: Entity,
    {
        Ok(self.inner.exists()?)
    }

    /// Return whether at least one matching row exists with terminal
    /// diagnostics attribution.
    #[cfg(feature = "diagnostics")]
    #[doc(hidden)]
    pub fn exists_with_attribution(
        &self,
    ) -> Result<(bool, crate::db::FluentTerminalExecutionAttribution), Error>
    where
        E: Entity,
    {
        Ok(self.inner.exists_with_attribution()?)
    }

    /// Explain scalar `exists()` routing without executing the terminal.
    pub fn explain_exists(&self) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_exists()?)
    }

    /// Return whether no matching row exists.
    pub fn not_exists(&self) -> Result<bool, Error>
    where
        E: Entity,
    {
        Ok(self.inner.not_exists()?)
    }

    /// Return all matching rows if the complete result fits in the default
    /// public-read small-set cap.
    ///
    /// This semantic terminal rejects a prior `partial_window(...)`; use
    /// `execute_rows()` when returning a partial row window is the endpoint
    /// contract.
    pub fn collect_complete(&self) -> Result<Vec<E>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.collect_complete()?)
    }

    /// Return all matching rows with query diagnostics attribution if the
    /// complete result fits in the default public-read small-set cap.
    #[cfg(feature = "diagnostics")]
    #[doc(hidden)]
    pub fn collect_complete_with_attribution(
        &self,
    ) -> Result<(Vec<E>, crate::db::QueryExecutionAttribution), Error>
    where
        E: Entity,
    {
        Ok(self.inner.collect_complete_with_attribution()?)
    }

    /// Return the exact number of matching rows.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact count must not mean "count the first N rows."
    pub fn count_exact(&self) -> Result<u32, Error>
    where
        E: Entity,
    {
        Ok(self.inner.count_exact()?)
    }

    /// Explain exact count routing without executing the terminal.
    pub fn explain_count_exact(&self) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_count_exact()?)
    }

    /// Return the exact row count with terminal diagnostics attribution.
    #[cfg(feature = "diagnostics")]
    #[doc(hidden)]
    pub fn count_exact_with_attribution(
        &self,
    ) -> Result<(u32, crate::db::FluentTerminalExecutionAttribution), Error>
    where
        E: Entity,
    {
        Ok(self.inner.count_exact_with_attribution()?)
    }

    /// Explain scalar `not_exists()` routing without executing the terminal.
    pub fn explain_not_exists(&self) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_not_exists()?)
    }

    /// Explain the execution shape without executing the query.
    pub fn explain_execution(&self) -> Result<ExplainExecutionNodeDescriptor, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution()?)
    }

    /// Render execution explain output as a compact text tree.
    pub fn explain_execution_text(&self) -> Result<String, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution_text()?)
    }

    /// Render execution explain output as canonical JSON.
    pub fn explain_execution_json(&self) -> Result<String, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution_json()?)
    }

    /// Render execution explain output as a verbose text tree.
    pub fn explain_execution_verbose(&self) -> Result<String, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution_verbose()?)
    }

    /// Return the exact minimum identifier under deterministic response ordering.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact minimum must not mean "minimum over the first N rows."
    pub fn min_id_exact(&self) -> Result<Option<Id<E>>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.min_id_exact()?)
    }

    /// Explain exact `min_id_exact()` routing without executing the terminal.
    pub fn explain_min_id_exact(&self) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_min_id_exact()?)
    }

    /// Return the identifier with the exact minimum `field` value.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact minimum must not mean "minimum over the first N rows."
    pub fn min_exact_by(&self, field: impl AsRef<str>) -> Result<Option<Id<E>>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.min_exact_by(field)?)
    }

    /// Explain exact `min_exact_by(field)` routing without executing the terminal.
    pub fn explain_min_exact_by(
        &self,
        field: impl AsRef<str>,
    ) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_min_exact_by(field)?)
    }

    /// Return the exact maximum identifier under deterministic response ordering.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact maximum must not mean "maximum over the first N rows."
    pub fn max_id_exact(&self) -> Result<Option<Id<E>>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.max_id_exact()?)
    }

    /// Explain exact `max_id_exact()` routing without executing the terminal.
    pub fn explain_max_id_exact(&self) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_max_id_exact()?)
    }

    /// Return the identifier with the exact maximum `field` value.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact maximum must not mean "maximum over the first N rows."
    pub fn max_exact_by(&self, field: impl AsRef<str>) -> Result<Option<Id<E>>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.max_exact_by(field)?)
    }

    /// Explain exact `max_exact_by(field)` routing without executing the terminal.
    pub fn explain_max_exact_by(
        &self,
        field: impl AsRef<str>,
    ) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_max_exact_by(field)?)
    }

    /// Return the exact sum of `field` over matching rows.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact sum must not mean "sum the first N rows."
    pub fn sum_exact(&self, field: impl AsRef<str>) -> Result<Option<Decimal>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.sum_exact(field)?)
    }

    /// Explain exact sum routing without executing the terminal.
    pub fn explain_sum_exact(
        &self,
        field: impl AsRef<str>,
    ) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_sum_exact(field)?)
    }

    /// Return the exact average of `field` over matching rows.
    ///
    /// This semantic aggregate rejects a prior partial row window because an
    /// exact average must not mean "average the first N rows."
    pub fn avg_exact(&self, field: impl AsRef<str>) -> Result<Option<Decimal>, Error>
    where
        E: Entity,
    {
        Ok(self.inner.avg_exact(field)?)
    }

    /// Explain exact `avg_exact(field)` routing without executing the terminal.
    pub fn explain_avg_exact(
        &self,
        field: impl AsRef<str>,
    ) -> Result<ExplainAggregateTerminalPlan, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_avg_exact(field)?)
    }

    /// Materialize zero or one entity, failing when more than one row matches.
    pub fn try_one(&self) -> Result<Option<E>, Error>
    where
        E: Entity,
    {
        icydb_core::db::ResponseCardinalityExt::try_entity(self.inner.execute_rows()?)
            .map_err(Into::into)
    }
}

impl<E: Entity + SingletonEntity> FluentLoadQuery<'_, E> {
    /// Load the singleton entity.
    #[must_use]
    pub fn singleton(mut self) -> Self
    where
        E::Key: Default,
    {
        self.inner = self.inner.singleton();
        self
    }
}

///
/// PartialWindowLoadQuery
///
/// Facade wrapper for deliberately partial row-window reads.
/// It exposes materialization and diagnostics, but not semantic terminals such
/// as paging, complete collection, existence, or exact aggregates.
///

pub struct PartialWindowLoadQuery<'a, E: Entity> {
    inner: core::db::PartialWindowLoadQuery<'a, E>,
}

impl<E: Entity> PartialWindowLoadQuery<'_, E> {
    #[doc(hidden)]
    #[must_use]
    pub const fn query(&self) -> &Query<E> {
        self.inner.query()
    }

    /// Mark this partial window as trusted and bypass the default bounded read
    /// gate.
    ///
    /// Use this only for controller/admin maintenance code that owns its
    /// authorization and resource policy. Caller-facing list endpoints should
    /// use `page(limit)` / `next_page(limit, cursor)` instead of trusted
    /// partial windows.
    #[must_use]
    pub fn trusted_read_unchecked(mut self) -> Self {
        self.inner = self.inner.trusted_read_unchecked();
        self
    }

    /// Execute this deliberately partial row window.
    ///
    /// Scalar queries return `QueryResponse::Rows`; grouped queries return
    /// `QueryResponse::Grouped`. Use `into_rows()` or `into_grouped()` when
    /// the endpoint expects one concrete shape.
    pub fn execute(&self) -> Result<QueryResponse<E>, Error>
    where
        E: Entity,
    {
        Ok(QueryResponse::from_core(self.inner.execute()?))
    }

    /// Execute this deliberately partial row window as scalar entity rows.
    pub fn execute_rows(&self) -> Result<Response<E>, Error>
    where
        E: Entity,
    {
        Ok(Response::from_core(self.inner.execute_rows()?))
    }

    /// Return the stable plan hash for this partial-window query.
    pub fn plan_hash_hex(&self) -> Result<String, Error> {
        Ok(self.inner.plan_hash_hex()?)
    }

    /// Build one trace payload without executing the partial-window query.
    pub fn trace(&self) -> Result<QueryTracePlan, Error> {
        Ok(self.inner.trace()?)
    }

    /// Build the validated logical plan without compiling execution details.
    pub fn planned(&self) -> Result<PlannedQuery<E>, Error> {
        Ok(self.inner.planned()?)
    }

    /// Build the compiled executable plan for this partial-window query.
    pub fn plan(&self) -> Result<CompiledQuery<E>, Error> {
        Ok(self.inner.plan()?)
    }

    /// Build logical explain metadata for the current partial-window query.
    pub fn explain(&self) -> Result<ExplainPlan, Error> {
        Ok(self.inner.explain()?)
    }

    /// Explain the execution shape without executing the partial-window query.
    pub fn explain_execution(&self) -> Result<ExplainExecutionNodeDescriptor, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution()?)
    }

    /// Render execution explain output as a compact text tree.
    pub fn explain_execution_text(&self) -> Result<String, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution_text()?)
    }

    /// Render execution explain output as canonical JSON.
    pub fn explain_execution_json(&self) -> Result<String, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution_json()?)
    }

    /// Render execution explain output as a verbose text tree.
    pub fn explain_execution_verbose(&self) -> Result<String, Error>
    where
        E: Entity,
    {
        Ok(self.inner.explain_execution_verbose()?)
    }
}