icydb_core/db/query/plan/validate/
mod.rs

1//! Query-plan validation at logical and executor boundaries.
2//!
3//! Validation ownership contract:
4//! - `validate_logical_plan_model` owns user-facing query semantics and emits `PlanError`.
5//! - `validate_executor_plan` is defensive: it re-checks owned semantics/invariants before
6//!   execution and must not introduce new user-visible semantics.
7//!
8//! Future rule changes must declare a semantic owner. Defensive re-check layers may mirror
9//! rules, but must not reinterpret semantics or error class intent.
10
11mod access;
12mod order;
13mod pushdown;
14mod semantics;
15
16#[cfg(test)]
17mod tests;
18
19use crate::{
20    db::query::{
21        plan::{AccessPlannedQuery, cursor::CursorPlanError},
22        policy::PlanPolicyError,
23        predicate::{self, SchemaInfo},
24    },
25    error::InternalError,
26    model::{entity::EntityModel, index::IndexModel},
27    traits::EntityKind,
28    value::Value,
29};
30use thiserror::Error as ThisError;
31
32// re-exports
33pub(crate) use access::{validate_access_plan, validate_access_plan_model};
34pub(crate) use order::{
35    validate_no_duplicate_non_pk_order_fields, validate_order, validate_primary_key_tie_break,
36};
37#[cfg(test)]
38pub(crate) use pushdown::assess_secondary_order_pushdown_if_applicable;
39#[cfg(test)]
40pub(crate) use pushdown::{
41    PushdownApplicability, assess_secondary_order_pushdown_if_applicable_validated,
42};
43pub(crate) use pushdown::{
44    PushdownSurfaceEligibility, SecondaryOrderPushdownEligibility, SecondaryOrderPushdownRejection,
45    assess_secondary_order_pushdown,
46};
47
48///
49/// PlanError
50///
51/// Executor-visible validation failures for logical plans.
52///
53/// These errors indicate that a plan cannot be safely executed against the
54/// current schema or entity definition. They are *not* planner bugs.
55///
56
57#[derive(Debug, ThisError)]
58pub enum PlanError {
59    #[error("predicate validation failed: {0}")]
60    PredicateInvalid(Box<predicate::ValidateError>),
61
62    #[error("{0}")]
63    Order(Box<OrderPlanError>),
64
65    #[error("{0}")]
66    Access(Box<AccessPlanError>),
67
68    #[error("{0}")]
69    Policy(Box<PolicyPlanError>),
70
71    #[error("{0}")]
72    Cursor(Box<CursorPlanError>),
73}
74
75///
76/// OrderPlanError
77///
78/// ORDER BY-specific validation failures.
79///
80#[derive(Debug, ThisError)]
81pub enum OrderPlanError {
82    /// ORDER BY references an unknown field.
83    #[error("unknown order field '{field}'")]
84    UnknownField { field: String },
85
86    /// ORDER BY references a field that cannot be ordered.
87    #[error("order field '{field}' is not orderable")]
88    UnorderableField { field: String },
89
90    /// ORDER BY references the same non-primary-key field multiple times.
91    #[error("order field '{field}' appears multiple times")]
92    DuplicateOrderField { field: String },
93
94    /// Ordered plans must terminate with the primary-key tie-break.
95    #[error("order specification must end with primary key '{field}' as deterministic tie-break")]
96    MissingPrimaryKeyTieBreak { field: String },
97}
98
99///
100/// AccessPlanError
101///
102/// Access-path and key-shape validation failures.
103///
104#[derive(Debug, ThisError)]
105pub enum AccessPlanError {
106    /// Access plan references an index not declared on the entity.
107    #[error("index '{index}' not found on entity")]
108    IndexNotFound { index: IndexModel },
109
110    /// Index prefix exceeds the number of indexed fields.
111    #[error("index prefix length {prefix_len} exceeds index field count {field_len}")]
112    IndexPrefixTooLong { prefix_len: usize, field_len: usize },
113
114    /// Index prefix must include at least one value.
115    #[error("index prefix must include at least one value")]
116    IndexPrefixEmpty,
117
118    /// Index prefix literal does not match indexed field type.
119    #[error("index prefix value for field '{field}' is incompatible")]
120    IndexPrefixValueMismatch { field: String },
121
122    /// Primary key field exists but is not key-compatible.
123    #[error("primary key field '{field}' is not key-compatible")]
124    PrimaryKeyNotKeyable { field: String },
125
126    /// Supplied key does not match the primary key type.
127    #[error("key '{key:?}' is incompatible with primary key '{field}'")]
128    PrimaryKeyMismatch { field: String, key: Value },
129
130    /// Key range has invalid ordering.
131    #[error("key range start is greater than end")]
132    InvalidKeyRange,
133}
134
135///
136/// PolicyPlanError
137///
138/// Plan-shape policy failures.
139///
140#[derive(Clone, Debug, Eq, PartialEq, ThisError)]
141pub enum PolicyPlanError {
142    /// ORDER BY must specify at least one field.
143    #[error("order specification must include at least one field")]
144    EmptyOrderSpec,
145
146    /// Delete plans must not carry pagination.
147    #[error("delete plans must not include pagination")]
148    DeletePlanWithPagination,
149
150    /// Load plans must not carry delete limits.
151    #[error("load plans must not include delete limits")]
152    LoadPlanWithDeleteLimit,
153
154    /// Delete limits require an explicit ordering.
155    #[error("delete limit requires an explicit ordering")]
156    DeleteLimitRequiresOrder,
157
158    /// Pagination requires an explicit ordering.
159    #[error(
160        "Unordered pagination is not allowed.\nThis query uses LIMIT or OFFSET without an ORDER BY clause.\nPagination without a total ordering is non-deterministic.\nAdd an explicit order_by(...) to make the query stable."
161    )]
162    UnorderedPagination,
163}
164
165impl From<PlanPolicyError> for PolicyPlanError {
166    fn from(err: PlanPolicyError) -> Self {
167        match err {
168            PlanPolicyError::EmptyOrderSpec => Self::EmptyOrderSpec,
169            PlanPolicyError::DeletePlanWithPagination => Self::DeletePlanWithPagination,
170            PlanPolicyError::LoadPlanWithDeleteLimit => Self::LoadPlanWithDeleteLimit,
171            PlanPolicyError::DeleteLimitRequiresOrder => Self::DeleteLimitRequiresOrder,
172            PlanPolicyError::UnorderedPagination => Self::UnorderedPagination,
173        }
174    }
175}
176
177impl From<predicate::ValidateError> for PlanError {
178    fn from(err: predicate::ValidateError) -> Self {
179        Self::PredicateInvalid(Box::new(err))
180    }
181}
182
183impl From<OrderPlanError> for PlanError {
184    fn from(err: OrderPlanError) -> Self {
185        Self::Order(Box::new(err))
186    }
187}
188
189impl From<AccessPlanError> for PlanError {
190    fn from(err: AccessPlanError) -> Self {
191        Self::Access(Box::new(err))
192    }
193}
194
195impl From<PolicyPlanError> for PlanError {
196    fn from(err: PolicyPlanError) -> Self {
197        Self::Policy(Box::new(err))
198    }
199}
200
201impl From<CursorPlanError> for PlanError {
202    fn from(err: CursorPlanError) -> Self {
203        Self::Cursor(Box::new(err))
204    }
205}
206
207impl From<PlanPolicyError> for PlanError {
208    fn from(err: PlanPolicyError) -> Self {
209        Self::from(PolicyPlanError::from(err))
210    }
211}
212
213/// Validate a logical plan with model-level key values.
214///
215/// Ownership:
216/// - semantic owner for user-facing query validity at planning boundaries
217/// - failures here are user-visible planning failures (`PlanError`)
218///
219/// New user-facing validation rules must be introduced here first, then mirrored
220/// defensively in downstream layers without changing semantics.
221pub(crate) fn validate_logical_plan_model(
222    schema: &SchemaInfo,
223    model: &EntityModel,
224    plan: &AccessPlannedQuery<Value>,
225) -> Result<(), PlanError> {
226    validate_plan_core(
227        schema,
228        model,
229        plan,
230        validate_order,
231        |schema, model, plan| validate_access_plan_model(schema, model, &plan.access),
232    )?;
233
234    Ok(())
235}
236
237/// Validate plans at executor boundaries and surface invariant violations.
238///
239/// Ownership:
240/// - defensive execution-boundary guardrail, not a semantic owner
241/// - must enforce structural integrity only, never user-shape semantics
242///
243/// Any disagreement with logical validation indicates an internal bug and is not
244/// a recoverable user-input condition.
245pub(crate) fn validate_executor_plan<E: EntityKind>(
246    plan: &AccessPlannedQuery<E::Key>,
247) -> Result<(), InternalError> {
248    let schema = SchemaInfo::from_entity_model(E::MODEL).map_err(|err| {
249        InternalError::query_invariant(format!("entity schema invalid for {}: {err}", E::PATH))
250    })?;
251
252    validate_access_plan(&schema, E::MODEL, &plan.access)
253        .map_err(InternalError::from_executor_plan_error)?;
254
255    Ok(())
256}
257
258// Shared logical plan validation core owned by planner semantics.
259fn validate_plan_core<K, FOrder, FAccess>(
260    schema: &SchemaInfo,
261    model: &EntityModel,
262    plan: &AccessPlannedQuery<K>,
263    validate_order_fn: FOrder,
264    validate_access_fn: FAccess,
265) -> Result<(), PlanError>
266where
267    FOrder: Fn(&SchemaInfo, &crate::db::query::plan::OrderSpec) -> Result<(), PlanError>,
268    FAccess: Fn(&SchemaInfo, &EntityModel, &AccessPlannedQuery<K>) -> Result<(), PlanError>,
269{
270    if let Some(predicate) = &plan.predicate {
271        predicate::validate(schema, predicate)?;
272    }
273
274    if let Some(order) = &plan.order {
275        validate_order_fn(schema, order)?;
276        validate_no_duplicate_non_pk_order_fields(model, order)?;
277        validate_primary_key_tie_break(model, order)?;
278    }
279
280    validate_access_fn(schema, model, plan)?;
281    semantics::validate_plan_semantics(plan)?;
282
283    Ok(())
284}
icydb_core/db/query/plan/validate/mod.rs

icydb_core/db/query/plan/validate/
mod.rs
