gollum-ir 0.4.0

//! IR representation of planning actions.
//!
//! [`IrAction`] captures the STRIPS-style structure of a planning action:
//! a name, typed parameters, preconditions that gate applicability, and
//! effects that describe world changes after execution.  Optional
//! [`IrMetadata`] allows attaching probabilistic weights or costs for
//! probabilistic and neurosymbolic planning.
//!
//! Call [`IrAction::validate`] after construction to check structural
//! consistency before the action enters the planning pipeline.

use std::collections::HashSet;

use serde::{Deserialize, Serialize};

use crate::metadata::IrMetadata;
use crate::term::IrTerm;

// ── Validation error ──────────────────────────────────────────────────────────

/// Errors produced by [`IrAction::validate`].
#[derive(Debug, Clone, PartialEq, thiserror::Error)]
pub enum ActionValidationError {
    /// The action name is empty.
    #[error("action name must not be empty")]
    EmptyName,

    /// A parameter name is used more than once.
    #[error("duplicate parameter name: {0:?}")]
    DuplicateParameter(String),

    /// A variable appearing in the preconditions or effects is not declared as
    /// a parameter.  The contained string is the variable name, and the second
    /// field indicates where it was found.
    #[error("undeclared variable {0:?} in {1}")]
    UndeclaredVariable(String, &'static str),
}

/// IR-level representation of a planning action.
///
/// Follows the classical STRIPS action schema (Fikes & Nilsson, 1971):
/// an action is applicable in a state when all its `preconditions` hold,
/// and executing it produces the `effects`.
///
/// # Example
///
/// ```rust
/// use gollum_ir::{IrAction, IrTerm};
///
/// let move_action = IrAction {
///     name: "move".into(),
///     parameters: vec!["X".into(), "Y".into()],
///     preconditions: vec![
///         IrTerm::Structure {
///             name: "at".into(),
///             args: vec![IrTerm::Var("X".into())],
///         },
///         IrTerm::Structure {
///             name: "connected".into(),
///             args: vec![IrTerm::Var("X".into()), IrTerm::Var("Y".into())],
///         },
///     ],
///     effects: vec![
///         IrTerm::Structure {
///             name: "at".into(),
///             args: vec![IrTerm::Var("Y".into())],
///         },
///         IrTerm::Structure {
///             name: "not".into(),
///             args: vec![IrTerm::Structure {
///                 name: "at".into(),
///                 args: vec![IrTerm::Var("X".into())],
///             }],
///         },
///     ],
///     metadata: None,
/// };
/// assert_eq!(move_action.name, "move");
/// assert_eq!(move_action.parameters.len(), 2);
/// ```
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct IrAction {
    /// Name of the action, e.g. `"move"` or `"pickup"`.
    pub name: String,
    /// Parameter names (variables) shared across preconditions and effects.
    pub parameters: Vec<String>,
    /// Conditions that must hold in the current state for this action to be
    /// applicable.
    pub preconditions: Vec<IrTerm>,
    /// Terms describing world changes after the action executes.  Positive
    /// terms are added; terms wrapped in `not(…)` represent deletions.
    pub effects: Vec<IrTerm>,
    /// Optional reasoning metadata (probability, cost, temporal bounds, …).
    pub metadata: Option<IrMetadata>,
}

// ── impl IrAction ─────────────────────────────────────────────────────────────

impl IrAction {
    /// Validate the structural consistency of this action.
    ///
    /// Checks performed:
    ///
    /// 1. `name` is non-empty.
    /// 2. `parameters` contains no duplicates.
    /// 3. Every `Var` node inside `preconditions` names a declared parameter.
    /// 4. Every `Var` node inside `effects` names a declared parameter.
    ///
    /// Anonymous variables (names starting with `_`) are allowed anywhere
    /// without being declared as parameters.
    ///
    /// Returns `Ok(())` on success or the first [`ActionValidationError`]
    /// encountered.
    pub fn validate(&self) -> Result<(), ActionValidationError> {
        // 1. Non-empty name.
        if self.name.is_empty() {
            return Err(ActionValidationError::EmptyName);
        }

        // 2. No duplicate parameter names.
        let mut seen: HashSet<&str> = HashSet::new();
        for p in &self.parameters {
            if !seen.insert(p.as_str()) {
                return Err(ActionValidationError::DuplicateParameter(p.clone()));
            }
        }
        let declared: HashSet<&str> = self.parameters.iter().map(String::as_str).collect();

        // 3. Variables in preconditions must be declared.
        for term in &self.preconditions {
            if let Some(v) = find_undeclared_var(term, &declared) {
                return Err(ActionValidationError::UndeclaredVariable(v, "preconditions"));
            }
        }

        // 4. Variables in effects must be declared.
        for term in &self.effects {
            if let Some(v) = find_undeclared_var(term, &declared) {
                return Err(ActionValidationError::UndeclaredVariable(v, "effects"));
            }
        }

        Ok(())
    }
}

/// Walk `term` recursively and return the first `Var` whose name is not in
/// `declared` and does not start with `_` (anonymous variables are exempt).
fn find_undeclared_var(term: &IrTerm, declared: &HashSet<&str>) -> Option<String> {
    match term {
        IrTerm::Var(name) => {
            if !name.starts_with('_') && !declared.contains(name.as_str()) {
                Some(name.clone())
            } else {
                None
            }
        }
        IrTerm::Structure { args, .. } => {
            args.iter().find_map(|a| find_undeclared_var(a, declared))
        }
        IrTerm::Typed { term: inner, .. }
        | IrTerm::Neural { term: inner, .. }
        | IrTerm::Differentiable { term: inner, .. } => find_undeclared_var(inner, declared),
        IrTerm::DiffNeural { term: inner, .. } => find_undeclared_var(inner, declared),
        _ => None,
    }
}

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

    fn at(loc: &str) -> IrTerm {
        IrTerm::Structure { name: "at".into(), args: vec![IrTerm::Atom(loc.into())] }
    }

    fn at_var(v: &str) -> IrTerm {
        IrTerm::Structure { name: "at".into(), args: vec![IrTerm::Var(v.into())] }
    }

    fn connected(x: &str, y: &str) -> IrTerm {
        IrTerm::Structure {
            name: "connected".into(),
            args: vec![IrTerm::Var(x.into()), IrTerm::Var(y.into())],
        }
    }

    fn not_term(inner: IrTerm) -> IrTerm {
        IrTerm::Structure { name: "not".into(), args: vec![inner] }
    }

    #[test]
    fn test_move_action_fields() {
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into(), "Y".into()],
            preconditions: vec![at_var("X"), connected("X", "Y")],
            effects: vec![at_var("Y"), not_term(at_var("X"))],
            metadata: None,
        };
        assert_eq!(action.name, "move");
        assert_eq!(action.parameters, vec!["X", "Y"]);
        assert_eq!(action.preconditions.len(), 2);
        assert_eq!(action.effects.len(), 2);
        assert!(action.metadata.is_none());
    }

    #[test]
    fn test_ground_action_no_parameters() {
        let action = IrAction {
            name: "open_door".into(),
            parameters: vec![],
            preconditions: vec![at("locked")],
            effects: vec![at("unlocked"), not_term(at("locked"))],
            metadata: None,
        };
        assert!(action.parameters.is_empty());
        assert_eq!(action.preconditions.len(), 1);
        assert_eq!(action.effects.len(), 2);
    }

    #[test]
    fn test_action_with_metadata() {
        let action = IrAction {
            name: "risky_move".into(),
            parameters: vec!["X".into()],
            preconditions: vec![at_var("X")],
            effects: vec![],
            metadata: Some(IrMetadata { probability: Some(0.8), ..IrMetadata::default() }),
        };
        assert_eq!(
            action.metadata.as_ref().and_then(|m| m.probability),
            Some(0.8)
        );
    }

    #[test]
    fn test_serde_roundtrip() {
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into(), "Y".into()],
            preconditions: vec![at_var("X"), connected("X", "Y")],
            effects: vec![at_var("Y"), not_term(at_var("X"))],
            metadata: None,
        };
        let s = ron::to_string(&action).expect("serialize failed");
        let back: IrAction = ron::from_str(&s).expect("deserialize failed");
        assert_eq!(action, back);
    }

    #[test]
    fn test_serde_roundtrip_with_metadata() {
        let action = IrAction {
            name: "probabilistic_move".into(),
            parameters: vec!["X".into()],
            preconditions: vec![],
            effects: vec![at_var("X")],
            metadata: Some(IrMetadata { probability: Some(0.5), ..IrMetadata::default() }),
        };
        let s = ron::to_string(&action).expect("serialize failed");
        let back: IrAction = ron::from_str(&s).expect("deserialize failed");
        assert_eq!(action, back);
    }

    #[test]
    fn test_clone_and_eq() {
        let a = IrAction {
            name: "jump".into(),
            parameters: vec!["X".into()],
            preconditions: vec![at_var("X")],
            effects: vec![],
            metadata: None,
        };
        let b = a.clone();
        assert_eq!(a, b);
    }

    // ── validate() tests ──────────────────────────────────────────────────────

    #[test]
    fn test_validate_well_formed_parametric_action() {
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into(), "Y".into()],
            preconditions: vec![at_var("X"), connected("X", "Y")],
            effects: vec![at_var("Y"), not_term(at_var("X"))],
            metadata: None,
        };
        assert!(action.validate().is_ok());
    }

    #[test]
    fn test_validate_well_formed_ground_action() {
        let action = IrAction {
            name: "open_door".into(),
            parameters: vec![],
            preconditions: vec![at("locked")],
            effects: vec![at("unlocked"), not_term(at("locked"))],
            metadata: None,
        };
        assert!(action.validate().is_ok());
    }

    #[test]
    fn test_validate_empty_name_is_error() {
        let action = IrAction {
            name: "".into(),
            parameters: vec![],
            preconditions: vec![],
            effects: vec![],
            metadata: None,
        };
        assert_eq!(action.validate(), Err(ActionValidationError::EmptyName));
    }

    #[test]
    fn test_validate_duplicate_parameter_is_error() {
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into(), "X".into()],
            preconditions: vec![at_var("X")],
            effects: vec![],
            metadata: None,
        };
        assert_eq!(
            action.validate(),
            Err(ActionValidationError::DuplicateParameter("X".into()))
        );
    }

    #[test]
    fn test_validate_undeclared_variable_in_preconditions() {
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into()],
            // Y is not declared as a parameter
            preconditions: vec![connected("X", "Y")],
            effects: vec![],
            metadata: None,
        };
        assert_eq!(
            action.validate(),
            Err(ActionValidationError::UndeclaredVariable("Y".into(), "preconditions"))
        );
    }

    #[test]
    fn test_validate_undeclared_variable_in_effects() {
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into()],
            preconditions: vec![at_var("X")],
            // Z is not declared as a parameter
            effects: vec![IrTerm::Structure {
                name: "at".into(),
                args: vec![IrTerm::Var("Z".into())],
            }],
            metadata: None,
        };
        assert_eq!(
            action.validate(),
            Err(ActionValidationError::UndeclaredVariable("Z".into(), "effects"))
        );
    }

    #[test]
    fn test_validate_anonymous_variable_is_allowed() {
        // Anonymous variables (starting with _) need not be declared.
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into()],
            preconditions: vec![IrTerm::Structure {
                name: "edge".into(),
                args: vec![IrTerm::Var("X".into()), IrTerm::Var("_".into())],
            }],
            effects: vec![],
            metadata: None,
        };
        assert!(action.validate().is_ok());
    }

    #[test]
    fn test_validate_nested_undeclared_variable_is_detected() {
        // Z is nested inside not(at(Z)) in effects.
        let action = IrAction {
            name: "move".into(),
            parameters: vec!["X".into()],
            preconditions: vec![],
            effects: vec![not_term(IrTerm::Structure {
                name: "at".into(),
                args: vec![IrTerm::Var("Z".into())],
            })],
            metadata: None,
        };
        assert_eq!(
            action.validate(),
            Err(ActionValidationError::UndeclaredVariable("Z".into(), "effects"))
        );
    }

    #[test]
    fn test_validate_empty_preconditions_and_effects_is_ok() {
        let action = IrAction {
            name: "noop".into(),
            parameters: vec![],
            preconditions: vec![],
            effects: vec![],
            metadata: None,
        };
        assert!(action.validate().is_ok());
    }
}