polydat_core/iteration/comprehension/predicate/

info.rs

// Copyright 2024-2026 Jonathan Shook
// SPDX-License-Identifier: Apache-2.0

//! `PredicateInfo` and supporting enums — comprehension_forms.md
//! §10.9.3.
//!
//! Five independent assertions the analyzer makes about a
//! predicate:
//!
//! - `factorization` — how the predicate decomposes by
//!   coordinate.
//! - `monotonicity` — per-axis direction of truth.
//! - `range_constraint` — per-axis value-bound implications.
//! - `determinism` — whether the predicate is referentially
//!   transparent.
//! - `coords_referenced` — the set of `{name}` references in
//!   the predicate text.
//!
//! All fields are independent — a predicate may have rich
//! factorization but no monotonicity, etc.

use serde::{Deserialize, Serialize};

/// Structured analysis output for one predicate.
///
/// Construction is the analyzer's responsibility; consumers
/// (R5 et al.) only read.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PredicateInfo {
    /// How the predicate decomposes by coordinate.
    pub factorization: Factorization,

    /// Per-axis monotonicity assertions. Missing axes have no
    /// monotonicity claim.
    pub monotonicity: PerAxisMap<Monotonicity>,

    /// Per-axis range constraint implied by the predicate.
    /// Missing axes have no constraint claim.
    pub range_constraint: PerAxisMap<RangeConstraint>,

    /// Whether the predicate is referentially transparent.
    pub determinism: Determinism,

    /// Names referenced by `{name}` interpolations in the
    /// predicate text. Coords NOT in the wrapped
    /// comprehension's coordinate set may still appear here
    /// (parent-scope references — the link-time consumer
    /// handles them per V3).
    pub coords_referenced: Vec<String>,
}

/// Per-coordinate decomposition of a predicate.
///
/// comprehension_forms.md §10.9.3 defines the four variants.
/// `Opaque` carries an [`OpaqueReason`] explaining why the analyzer
/// couldn't decompose further. R5 fires only on `PerAxis`.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Factorization {
    /// Predicate factorizes per-axis: `p ≡ p_a({a}) && p_b({b}) && …`
    /// Each entry is the per-axis sub-predicate (as a string,
    /// matching the input predicate's lexical form).
    PerAxis(PerAxisMap<String>),

    /// Conjunction of sub-predicates where each may still
    /// cross-cut multiple axes.
    Conjunctive(Vec<String>),

    /// Disjunction of sub-predicates, each `PerAxis` or
    /// `Conjunctive` itself (§10.9.5's disjunction rule).
    Disjunctive(Vec<String>),

    /// Analyzer can't structurally decompose. R5 doesn't fire.
    Opaque(OpaqueReason),
}

/// Why the analyzer marked a predicate `Opaque`
/// (comprehension_forms.md §10.9.3).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum OpaqueReason {
    /// Predicate shape isn't in the §10.9.5 recognizer
    /// catalog.
    UnknownPattern,

    /// Predicate references a non-deterministic Polydat function
    /// (PRNG draw, time-of-day, etc.). Detected
    /// conservatively — any function call we don't recognize
    /// as deterministic falls here.
    NonDeterministic,

    /// Predicate depends on previously-emitted tuples. No predicate
    /// the language can write does; the variant names the reason
    /// for completeness.
    CrossTupleState,

    /// Predicate has observable side effects.
    SideEffecting,

    /// Predicate references one or more continuous-cardinality
    /// coordinates, which the analyzer treats as opaque
    /// (comprehension_forms.md §14.2).
    Continuous,
}

/// Per-axis monotonicity direction. "Increasing" means: once
/// the predicate becomes true for `axis = k`, it stays true
/// for all `axis ≥ k`. It is the fact R10 (monotonic-cutoff
/// truncation, outside the catalog per §14.1) would read.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Monotonicity {
    /// Once true at an axis value, true for every greater value.
    Increasing,
    /// Once true at an axis value, true for every lesser value.
    Decreasing,
    /// No monotonicity established.
    None,
}

/// Per-axis value-bound implied by the predicate: the fact R8
/// (range-narrowing) and R9 (discrete-set substitution), outside the
/// catalog per comprehension_forms.md §14.1, would read.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum RangeConstraint {
    /// `lo ≤ axis ≤ hi` (with open/closed flags).
    Bounded {
        /// The lower bound, if any.
        lo: Option<ConstValue>,
        /// The upper bound, if any.
        hi: Option<ConstValue>,
        /// Whether the lower bound is included.
        lo_inclusive: bool,
        /// Whether the upper bound is included.
        hi_inclusive: bool,
    },
    /// `axis ∈ {v_1, v_2, …}` (e.g., from an `in` predicate).
    Discrete(Vec<ConstValue>),
    /// No constraint asserted for this axis.
    None,
}

/// Whether a predicate is referentially transparent. Same
/// `(predicate, coords)` always produces the same boolean.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Determinism {
    /// The same predicate and coordinates always give the same answer.
    Deterministic,
    /// The predicate may depend on something else.
    Opaque,
}

/// Constant value used inside `RangeConstraint::Bounded` / `Discrete`.
/// Subset of polydat's `Value` sufficient for the initial
/// recognizer catalog.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum ConstValue {
    /// An integer.
    Int(i64),
    /// A float.
    Float(f64),
    /// A string.
    String(String),
    /// A boolean.
    Bool(bool),
}

/// Map keyed by coordinate name. Insertion order preserves
/// declaration order so downstream consumers can iterate
/// per-axis in the comprehension's tuple-shape order.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PerAxisMap<T> {
    entries: Vec<(String, T)>,
}

impl<T> PerAxisMap<T> {
    /// An empty map.
    pub fn new() -> Self {
        Self {
            entries: Vec::new(),
        }
    }

    /// Set the entry for a coordinate, keeping its position if present.
    pub fn insert<K: Into<String>>(&mut self, key: K, value: T) {
        let key = key.into();
        // Replace if already present; preserves position.
        if let Some(slot) = self.entries.iter_mut().find(|(k, _)| *k == key) {
            slot.1 = value;
        } else {
            self.entries.push((key, value));
        }
    }

    /// The entry for a coordinate, if any.
    pub fn get(&self, key: &str) -> Option<&T> {
        self.entries.iter().find(|(k, _)| k == key).map(|(_, v)| v)
    }

    /// The entries, in declaration order.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &T)> {
        self.entries.iter().map(|(k, v)| (k.as_str(), v))
    }

    /// The number of entries.
    pub fn len(&self) -> usize {
        self.entries.len()
    }

    /// Whether the map has no entry.
    pub fn is_empty(&self) -> bool {
        self.entries.is_empty()
    }

    /// The coordinate names, in declaration order.
    pub fn keys(&self) -> impl Iterator<Item = &str> {
        self.entries.iter().map(|(k, _)| k.as_str())
    }
}

impl<T> Default for PerAxisMap<T> {
    fn default() -> Self {
        Self::new()
    }
}

impl<T> FromIterator<(String, T)> for PerAxisMap<T> {
    fn from_iter<I: IntoIterator<Item = (String, T)>>(iter: I) -> Self {
        let mut m = Self::new();
        for (k, v) in iter {
            m.insert(k, v);
        }
        m
    }
}

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

    #[test]
    fn per_axis_map_insertion_order() {
        let mut m: PerAxisMap<i64> = PerAxisMap::new();
        m.insert("k", 10);
        m.insert("limit", 20);
        let keys: Vec<&str> = m.keys().collect();
        assert_eq!(keys, vec!["k", "limit"]);
    }

    #[test]
    fn per_axis_map_replace_preserves_position() {
        let mut m: PerAxisMap<i64> = PerAxisMap::new();
        m.insert("k", 10);
        m.insert("limit", 20);
        m.insert("k", 100); // replace
        let keys: Vec<&str> = m.keys().collect();
        assert_eq!(keys, vec!["k", "limit"]);
        assert_eq!(*m.get("k").unwrap(), 100);
    }

    #[test]
    fn predicate_info_round_trip_serde() {
        let info = PredicateInfo {
            factorization: Factorization::PerAxis(
                vec![
                    ("k".to_string(), "{k} > 0".to_string()),
                    ("limit".to_string(), "{limit} < 100".to_string()),
                ]
                .into_iter()
                .collect(),
            ),
            monotonicity: PerAxisMap::new(),
            range_constraint: PerAxisMap::new(),
            determinism: Determinism::Deterministic,
            coords_referenced: vec!["k".to_string(), "limit".to_string()],
        };
        let json = serde_json::to_string(&info).unwrap();
        let back: PredicateInfo = serde_json::from_str(&json).unwrap();
        assert_eq!(info, back);
    }

    #[test]
    fn opaque_reason_serde() {
        let info = PredicateInfo {
            factorization: Factorization::Opaque(OpaqueReason::Continuous),
            monotonicity: PerAxisMap::new(),
            range_constraint: PerAxisMap::new(),
            determinism: Determinism::Deterministic,
            coords_referenced: vec!["theta".to_string()],
        };
        let json = serde_json::to_string(&info).unwrap();
        assert!(json.contains("continuous"));
        let back: PredicateInfo = serde_json::from_str(&json).unwrap();
        assert_eq!(info, back);
    }
}