aimx/

context.rs

//! Evaluation context for expression evaluation within AIM workflows.
//!
//! The context module provides the runtime environment for evaluating AIMX expressions
//! within the context of AIM workflows. It handles:
//!
//! - Variable resolution across multi-level workflow hierarchies
//! - Function and method dispatch through the global function registry
//! - Closure parameter management for functional programming constructs
//! - Caching of evaluation results within a single evaluation session
//! - Circular reference detection to prevent infinite loops
//! - Inference operations for agentic workflow execution
//!
//! # Context Architecture
//!
//! The module defines two primary components:
//!
//! 1. [`ContextLike`] - A trait that defines the interface for evaluation contexts
//! 2. [`Context`] - A complete implementation that integrates with AIM workflows
//!
//! The `Context` struct implements the `ContextLike` trait and provides a full
//! implementation for workflow-based expression evaluation with proper scoping,
//! caching, and inference capabilities.
//!
//! # Workflow Integration
//!
//! The context maintains references to workflows at different levels:
//! - `workflow`: The current read-only workflow context
//! - `workflow_mut`: A mutable workflow for making changes during inference
//! - `scope`: The current reference scope for resolving relative references
//!
//! When evaluating expressions within workflows, the context automatically handles:
//! - Multi-part reference resolution (e.g., `parent.child.value`)
//! - Type promotion and validation for assignments
//! - Caching of computed values within a session
//! - Circular reference detection to prevent stack overflows
//!
//! # Thread Safety
//!
//! Each thread should use its own context instance to evaluate a workflow .
//! Context instances are not thread-safe and should not be shared between threads.
//! 
use crate::{
    Expression, ExpressionLike, FunctionRegistry, Node, Reference, Rule, Typedef, Value, Workflow, WorkflowLike, aim::{get_config, get_lock_manager}, get_workspace, inference::{generate_prompt, parse_response, send_request, validate_responses},
};
use anyhow::{anyhow, Result};
use std::{
    collections::{HashMap, HashSet},
    mem::replace,
    sync::{Arc, Mutex},
};

/// Trait for evaluation contexts that provide runtime environment for expression evaluation.
///
/// This trait defines the interface that evaluation contexts must implement.
/// A context provides variable values, handles function calls, manages closure parameters,
/// and provides the runtime environment for expression evaluation.
///
/// The ContextLike trait is designed to be implemented by context types that need to:
/// - Resolve variable references during evaluation
/// - Handle function and method calls
/// - Manage closure parameters for functional programming constructs
/// - Support inference operations for agentic workflows
///
/// # Implementation Requirements
///
/// Implementors must manage:
/// - Variable resolution through [`get_referenced`](ContextLike::get_referenced) and [`set_referenced`](ContextLike::set_referenced)
/// - Function dispatch through [`function_call`](ContextLike::function_call) and [`method_call`](ContextLike::method_call)
/// - Closure parameter management through [`start_closure`](ContextLike::start_closure), [`set_key`](ContextLike::set_key), [`set_value`](ContextLike::set_value), and [`end_closure`](ContextLike::end_closure)
/// - Inference operations through [`inference_call`](ContextLike::inference_call)
///
/// See the [`Context`] struct for a complete implementation that supports
/// workflow-based evaluation with proper scoping and caching.
pub trait ContextLike {

    /// Start a new closure and save the current stack.
    fn start_closure(&mut self) -> [(String, Value); 2];

    /// Set the key of the indexed mapped variable used by element-wise functions like `map`.
    ///
    /// # Arguments
    ///
    /// * `index` - The index key to set (0 or 1)
    /// * `identifier` - The key to set
    fn set_key(&mut self, index: usize, identifier: &str);

    /// Set the value of the index mapped variable used by element-wise functions like `map`.
    ///
    /// # Arguments
    ///
    /// * `index` - The index value to set (0 or 1)
    /// * `value` - The value to set
    fn set_value(&mut self, index: usize, value: &Value);

    /// End the closure and restore the previous stack.
    fn end_closure(&mut self, stack: [(String, Value); 2]);

    /// Get the value of a referenced variable or expression.
    ///
    /// # Arguments
    ///
    /// * `reference` - The reference to resolve
    ///
    /// # Returns
    ///
    /// Returns the value of the referenced variable or an error if the reference
    /// cannot be resolved.
    fn get_referenced(&mut self, reference: &Reference) -> Result<Value>;

    /// Set the value of a referenced variable.
    ///
    /// # Arguments
    ///
    /// * `reference` - The reference to set
    /// * `value` - The value to assign
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on success or an error if the referenced variable cannot be set.
    fn set_referenced(&mut self, reference: &Reference, value: Value) -> Result<()>;

    /// Call a standalone function.
    ///
    /// # Arguments
    /// * `name` - The name of the function to call
    /// * `arg` - The argument(s) to pass to the function (Value can be Empty, Literal, or Array)
    ///
    /// # Returns
    ///
    /// Returns the result of the function call or an error if the function is not found
    /// or if there's an error during execution.
    fn function_call(&mut self, name: &str, arg: Value) -> Result<Value>;

    /// Call a method on a value.
    ///
    /// # Arguments
    /// * `name` - The name of the method to call
    /// * `value` - The value on which to call the method
    /// * `arg` - The argument(s) to pass to the method (Value can be Empty, Literal, or Array)
    ///
    /// # Returns
    ///
    /// Returns the result of the method call or an error if the method is not found
    /// or if there's an error during execution.
    fn method_call(&mut self, name: &str, value: Value, arg: Value) -> Result<Value>;

    /// Run inference on a referenced workflow.
    ///
    /// # Arguments
    /// * `reference` - The workflow reference
    /// * `arg` - The argument(s) to pass to the inference call (Value can be Empty, Literal, or Array)
    ///
    /// # Returns
    ///
    /// Returns the result of the inference call or an error if the workflow is not found
    /// or if there's an error during execution.
    fn inference_call(&mut self, reference: &Reference, arg: Value) -> Result<Value>;
}

enum Stack {
    Reader(Reference, Arc<Workflow>),
    Writer(Reference, Arc<Workflow>, Workflow),
}

/// A default context for evaluating expressions within AIM workflows.
///
/// The `Context` struct provides a complete implementation of the [`ContextLike`] trait
/// that integrates with the AIM workflow system. It supports:
///
/// - Variable resolution across multi-level workflow hierarchies
/// - Function and method dispatch through the global function registry
/// - Closure parameter management for functional programming constructs
/// - Caching of evaluation results within a single evaluation session
/// - Circular reference detection to prevent infinite loops
/// - Inference operations for agentic workflow execution
///
/// # Workflow Integration
///
/// The context maintains references to workflows at different levels:
/// - `workflow`: The current read-only workflow context
/// - `workflow_mut`: A mutable workflow for making changes during inference
/// - `scope`: The current reference scope for resolving relative references
///
/// When evaluating expressions within workflows, the context automatically handles:
/// - Multi-part reference resolution (e.g., `parent.child.value`)
/// - Type promotion and validation for assignments
/// - Caching of computed values within a session
/// - Circular reference detection to prevent stack overflows
///
/// # Thread Safety
///
/// Context instances are not thread-safe and should not be shared between threads.
/// Each evaluation session should use its own context instance.
///
/// # Examples
///
/// Basic usage with predefined values:
///
/// ```rust
/// use aimx::{Context, Literal, Value};
///
/// let context = Context::new()
///     .with_value("x", Value::Literal(Literal::Number(42.0)))
///     .with_value("name", Value::Literal(Literal::Text("Alice".to_string())));
/// ```
///
/// Evaluating expressions within workflows:
///
/// ```rust
/// use aimx::{Context, aimx_parse, ExpressionLike};
///
/// let mut context = Context::new();
/// // Expressions are evaluated within the context of the workspace workflows
/// let expression = aimx_parse("some_workflow_value + 10");
/// let result = expression.evaluate(&mut context);
/// ```
#[derive(Debug)]
pub struct Context {
    scope: Reference,
    workflow: Arc<Workflow>,
    workflow_mut: Option<Workflow>,
    lock_guard: Option<Arc<Mutex<()>>>,
    parameters: [(String, Value); 2],
    /// Rules that have already been entered on the current call‑stack.
    visited: HashSet<Reference>,
    /// Caches results for the current evaluation.
    cache: HashMap<Reference, Value>,
}

impl Context {
    pub fn new() -> Self {
        // Convert WorkflowLike to Workflow
        let workflow = get_workspace()
                    .as_any()
                    .downcast_ref::<Workflow>()
                    .map(|workspace| Arc::new(workspace.clone())).unwrap();
        Self {
            scope: Reference::new("_"),
            workflow,
            workflow_mut: None,
            lock_guard: None,
            parameters: [
                (String::new(), Value::Empty),
                (String::new(), Value::Empty)
            ],
            visited: HashSet::new(),
            cache: HashMap::new(),
        }
    }

    /// Gets read-only access to the current workflow.
    ///
    /// Returns a clone of the Arc reference to the current workflow, allowing
    /// read-only access to workflow data without affecting the context's ownership.
    pub fn workflow(&self) -> Arc<Workflow> {
        self.workflow.clone()
    }

    /// Gets mutable access to the workflow if available.
    ///
    /// Returns a mutable reference to the workflow if one is currently being
    /// modified, or None if only read-only access is available.
    pub fn workflow_mut(&mut self) -> Option<&mut Workflow> {
        self.workflow_mut.as_mut()
    }

    /// Sets mutable access to a workflow.
    ///
    /// This method is used to provide a workflow that can be modified during
    /// evaluation, typically when performing inference operations that need
    /// to update workflow values. Note that this requires appropriate write
    /// permissions from the lock manager.
    ///
    /// # Arguments
    ///
    /// * `workflow` - The workflow to make mutable
    pub fn set_workflow_mut(&mut self, workflow: Workflow) {
        self.workflow_mut = Some(workflow);
    }

    /// Clears mutable workflow access.
    ///
    /// This method releases the mutable workflow reference, reverting to
    /// read-only access for subsequent operations.
    pub fn clear_workflow_mut(&mut self) {
        self.workflow_mut = None;
    }

    /// Begin a writable session on the current workflow.
    ///
    /// This method acquires a write lock on the current workflow scope and
    /// prepares the context for making modifications. It's typically used
    /// when an inference operation needs to update workflow values.
    pub fn writable_start(&mut self) {
        if self.workflow_mut.is_none() {
            let lock_manager = get_lock_manager();
            self.lock_guard = Some(lock_manager.acquire_workflow_lock(self.scope.clone()));
            let workflow = self.workflow.clone();
            self.workflow_mut = Some((*workflow).clone());
        }
    }

    /// End a writable session and commit changes.
    ///
    /// This method releases the write lock and commits any changes made to
    /// the workflow during the writable session. The modified workflow is
    /// atomically replaced with the new version.
    pub fn writable_end(&mut self) {
        // Atomically replace the old node workflow with the new workflow.
        if let Ok((_, node, _)) = self.dereference(&self.scope) {
            if let Some(workflow_mut) = self.workflow_mut.take() {
                node.set_workflow(workflow_mut);
            }            
        }
        // Release the lock by taking ownership and letting it drop
        let _ = self.lock_guard.take();
    }


    /// Start a new evaluation session.
    ///
    /// This method clears the visited set and cache, preparing the context
    /// for a new evaluation session. It's important to call this method
    /// when starting a new independent evaluation to avoid conflicts with
    /// cached values from previous evaluations.
    pub fn new_session(&mut self) {
        self.visited.clear();
        self.cache.clear();
    }

    fn inference_start(&mut self, scope: Reference) -> Stack {
        let old_scope = replace(&mut self.scope, scope);
        if let Some(workflow_mut) = self.workflow_mut.take() {
            Stack::Writer(old_scope, self.workflow.clone(), workflow_mut)
        }
        else {
            Stack::Reader(old_scope, self.workflow.clone())
        }
    }

    fn inference_end(&mut self, stack: Stack) {
        match stack {
            Stack::Reader(scope, workflow) => {
                self.scope = scope;
                self.workflow = workflow
            }
            Stack::Writer(scope, workflow, workflow_mut) => {
                self.scope = scope;
                self.workflow = workflow;
                self.workflow_mut = Some(workflow_mut)
            }
        }
    }

    /// Add a predefined value to the context for testing purposes.
    ///
    /// This method creates a rule with the given identifier and value and adds it
    /// to the workspace. This is primarily used for testing expressions that reference
    /// predefined variables.
    ///
    /// # Arguments
    ///
    /// * `identifier` - The identifier name for the value
    /// * `value` - The value to associate with the identifier
    ///
    /// # Returns
    ///
    /// Returns the modified context for method chaining.
    pub fn with_value(mut self, identifier: &str, value: Value) -> Self {
        let typedef = value.get_type().unwrap_or(Typedef::Any);
        let rule = Rule::new(identifier.to_string(), typedef, Expression::Empty, value);
        
        // Try mutable workflow first
        if let Some(ref mut workflow) = self.workflow_mut {
            workflow.append_or_update(Some(rule));
        }
        // Otherwise try read-only workflow
        else {
            // Clone the workflow for modification
            let mut workflow_clone = (*self.workflow).clone();
            workflow_clone.append_or_update(Some(rule));
            self.workflow = Arc::new(workflow_clone);
        }
        self
    }

    // Dereference the Rule and return a normalized reference to it.
    fn normalize(&mut self, reference: &Reference) -> Result<Reference> {
        match reference {
            Reference::One(one) => {
                // Try writable workflow
                if let Some(workflow_mut) = &self.workflow_mut {
                    if workflow_mut.get_rule(one).is_some() {
                        return self.scope.normalize(reference)
                    }
                }
                // Try read-only workflow
                if self.workflow.get_rule(one).is_some() {
                    return self.scope.normalize(reference)
                }
                // Try workspace
                if get_workspace().get_rule(one).is_some() {
                    return Ok(reference.clone())
                }
            }
            Reference::Two(one, two) => {
                // Try writable workflow
                if let Some(workflow_mut) = &self.workflow_mut {
                    if let Some(rule) = &workflow_mut.get_rule(one) {
                        if let Some(node) = rule.get_node() {
                            if node.get_workflow_like().get_rule(two).is_some() {
                                return self.scope.normalize(reference)
                            }
                        }
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if node.get_workflow_like().get_rule(two).is_some() {
                            return self.scope.normalize(reference)
                        }
                    }
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if node.get_workflow_like().get_rule(two).is_some() {
                            return Ok(reference.clone())
                        }
                    }
                }
            }
            Reference::Three(one, two, three) => {
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            if let Some(node) = rule.get_node() {
                                if node.get_workflow_like().get_rule(three).is_some() {
                                    return Ok(reference.clone())
                                }
                            }
                        }
                    }
                }
            }
        }
        Err(anyhow!("Undefined locator ~{}", reference))
    }

    fn dereference_and_evaluate(&mut self, reference: &Reference) -> Result<Value> {
        match reference {
            Reference::One(one) => {
                // Try writable workflow
                if let Some(workflow) = &self.workflow_mut {
                    if let Some(rule) = &workflow.get_rule(one) {
                        return rule.evaluate(self);
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    return rule.evaluate(self);
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    return rule.evaluate(self);
                }
            }
            Reference::Two(one, two) => {
                // Try writable workflow
                if let Some(workflow) = &self.workflow_mut {
                    if let Some(rule) = &workflow.get_rule(one) {
                        if let Some(node) = rule.get_node() {
                            if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                                return rule.evaluate(self);
                            }
                        }
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            return rule.evaluate(self);
                        }
                    }
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            return rule.evaluate(self);
                        }
                    }
                }
            }
            Reference::Three(one, two, three) => {
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            if let Some(node) = rule.get_node() {
                                if let Some(rule) = &node.get_workflow_like().get_rule(three) {
                                    return rule.evaluate(self);
                                }
                            }
                        }
                    }
                }
            }
        }
        Err(anyhow!("Undefined locator ~{}", reference))
    }

    fn dereference_typedef(&mut self, reference: &Reference) -> Result<(Reference, Typedef)> {
        match reference {
            Reference::One(one) => {
                // Try writable workflow
                if let Some(workflow) = &self.workflow_mut {
                    if let Some(rule) = &workflow.get_rule(one) {
                        let normalized = self.scope.normalize(reference)?;
                        return Ok((normalized, rule.typedef().clone()));
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    let normalized = self.scope.normalize(reference)?;
                    return Ok((normalized, rule.typedef().clone()));
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    return Ok((reference.clone(), rule.typedef().clone()));
                }
            }
            Reference::Two(one, two) => {
                // Try writable workflow
                if let Some(workflow) = &self.workflow_mut {
                    if let Some(rule) = &workflow.get_rule(one) {
                        if let Some(node) = rule.get_node() {
                            if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                                let normalized = self.scope.normalize(reference)?;
                                return Ok((normalized, rule.typedef().clone()));
                            }
                        }
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            let normalized = self.scope.normalize(reference)?;
                            return Ok((normalized, rule.typedef().clone()));
                        }
                    }
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            return Ok((reference.clone(), rule.typedef().clone()));
                        }
                    }
                }
            }
            Reference::Three(one, two, three) => {
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            if let Some(node) = rule.get_node() {
                                if let Some(rule) = &node.get_workflow_like().get_rule(three) {
                                    return Ok((reference.clone(), rule.typedef().clone()));
                                }
                            }
                        }
                    }
                }
            }
        }
        Err(anyhow!("Undefined locator ~{}", reference))
    }

    // Dereference the Node and return a normalized reference to it.
    fn dereference(&self, reference: &Reference) -> Result<(Reference, Node, bool)> {
        match reference {
            Reference::One(one) => {
                // Try writable workflow
                if let Some(workflow) = &self.workflow_mut {
                    if let Some(rule) = &workflow.get_rule(one) {
                        if let Some(node) = rule.get_node() {
                            let normalized = self.scope.normalize(reference)?;
                            return Ok((normalized, node, true));
                        }
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        let normalized = self.scope.normalize(reference)?;
                        return Ok((normalized, node, true));
                    }
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        return Ok((reference.clone(), node, false));
                    }
                }
            }
            Reference::Two(one, two) => {
                // Try writable workflow
                if let Some(workflow) = &self.workflow_mut {
                    if let Some(rule) = &workflow.get_rule(one) {
                        if let Some(node) = rule.get_node() {
                            if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                                if let Some(node) = rule.get_node() {
                                    let normalized = self.scope.normalize(reference)?;
                                    return Ok((normalized, node, true));
                                }
                            }
                        }
                    }
                }
                // Try read-only workflow
                if let Some(rule) = self.workflow.get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            if let Some(node) = rule.get_node() {
                                let normalized = self.scope.normalize(reference)?;
                                return Ok((normalized, node, true));
                            }
                        }
                    }
                }
                // Try workspace
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            if let Some(node) = rule.get_node() {
                                return Ok((reference.clone(), node, false));
                            }
                        }
                    }
                }
            }
            Reference::Three(one, two, three) => {
                if let Some(rule) = &get_workspace().get_rule(one) {
                    if let Some(node) = rule.get_node() {
                        if let Some(rule) = &node.get_workflow_like().get_rule(two) {
                            if let Some(node) = rule.get_node() {
                                if let Some(rule) = &node.get_workflow_like().get_rule(three) {
                                    if let Some(node) = rule.get_node() {
                                        return Ok((reference.clone(), node, false));
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
        Err(anyhow!("Undefined locator {} within {} scope~{}", reference, &self.scope, reference))
    }
}

impl ContextLike for Context {

    /// Start a new closure and save the current parameter stack.
    fn start_closure(&mut self) -> [(String, Value); 2] {
        replace(&mut self.parameters, [
                (String::new(), Value::Empty),
                (String::new(), Value::Empty)
            ])
    }

    /// Set the key of the indexed mapped variable used by element-wise functions like `map`.
    ///
    /// # Arguments
    ///
    /// * `index` - The index key to set (0 or 1)
    /// * `identifier` - The key to set
    fn set_key(&mut self, index: usize, identifier: &str) {
        if self.parameters[index].0 != *identifier {
            self.parameters[index].0 = identifier.to_string();
        }
    }

    /// Set the value of the index mapped variable used by element-wise functions like `map`.
    ///
    /// # Arguments
    ///
    /// * `index` - The index value to set (0 or 1)
    /// * `value` - The value to set
    fn set_value(&mut self, index: usize, value: &Value) {
        self.parameters[index].1 = value.clone();
    }

    /// End the closure and restore the previous parameter stack.
    fn end_closure(&mut self, stack: [(String, Value); 2]) {
        self.parameters = stack;
    }
    /// Get the value of a referenced variable.
    ///
    /// This implementation only supports single-part references (default identifiers).
    /// Multi-part references (e.g., `object.property`) are not supported in this
    /// simplified context.
    ///
    /// # Arguments
    ///
    /// * `reference` - The reference to resolve
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the referenced value or an error
    /// if the reference cannot be resolved.
    fn get_referenced(&mut self, reference: &Reference) -> Result<Value> {
        // Check closure parameters first
        if *reference == self.parameters[0].0 {
            Ok(self.parameters[0].1.clone())
        } else if *reference == self.parameters[1].0 {
            Ok(self.parameters[1].1.clone())
        } else {
            // Get a normalized reference for the cache key
            let normalized = self.normalize(reference)?;
            // 1️⃣ Cycle detection
            if !self.visited.insert(normalized.clone()) {
                // The key was already present → we are revisiting this rule on the stack.
                return Err(anyhow!("Circular reference detected ~{}", normalized));
            }
            // 2️⃣ Cache lookup – if the value has already been computed in this run,
            //    just return the cached copy.
            if let Some(cached) = self.cache.get(&normalized) {
                // Pop the visited entry before returning.
                self.visited.remove(&normalized);
                return Ok(cached.clone());
            }
            // 3️⃣ Dereference and evaluate the rule
            match self.dereference_and_evaluate(reference) {
                Ok(value) => {
                    // 4️⃣ Clean up the visited reference (pop stack frame)
                    self.visited.remove(&normalized);
                    // 5️⃣ Cache value for the rest of this evaluation.
                    self.cache.insert(normalized, value.clone());
                    Ok(value)
                }
                Err(e) => {
                    self.visited.remove(&normalized);
                    Err(e)
                }
            }
        }
    }

    /// Set the value of a referenced variable.
    ///
    /// # Arguments
    ///
    /// * `reference` - The reference to set
    /// * `literal` - The value to assign
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` if the referenced value was set or an error if the 
    /// reference cannot be resolved.
    fn set_referenced(&mut self, reference: &Reference, value: Value) -> Result<()> {
        // Check closure parameters first
        if *reference == self.parameters[0].0 {
            self.parameters[0].1 = value;
            Ok(())
        } else if *reference == self.parameters[1].0 {
            self.parameters[1].1 = value;
            Ok(())
        } else {
             // Find the referenced rule's typedef
            match self.dereference_typedef(reference) {
                Ok((normalized, typedef)) => {
                    // Promote type
                    let value = match value.to_type(&typedef) {
                        Ok(v) => v,
                        Err(e) => return Err(anyhow!("{}~{}", e, reference))
                    };
                    match reference {
                        Reference::One(one) => {
                            // Try mutable workflow first
                            if let Some(workflow_mut) = self.workflow_mut() {
                                if let Some(rule) = workflow_mut.get_rule_mut(one) {
                                    return rule.set_value(value);
                                }
                            }
                            /* NOTE: I don't think we want to modify other workflows here
                            Try read-only workflow (clone and modify)
                            else if let Some(workflow) = self.workflow.as_ref() {
                                let mut workflow_clone = (**workflow).clone();
                                if let Some(rule) = workflow_clone.get_rule_mut(one) {
                                    rule.set_value(value)?;
                                    // Update the workflow in context
                                    self.workflow = Some(Arc::new(workflow_clone));
                                    return Ok(());
                                }
                            } */
                        }
                        _ => {}
                    }
                    // Cache the referenced assignment instead
                    self.cache.insert(normalized, value);
                    Ok(())
                }
                Err(e) => Err(e),
            }
        }
    }

    /// Call a standalone function.
    ///
    /// Delegates function calls to the singleton function registry.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the function to call
    /// * `arg` - The argument(s) to pass to the function
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the function result or an error
    /// if the function is not found or execution fails.
    fn function_call(&mut self, name: &str, arg: Value) -> Result<Value> {
        let registry = FunctionRegistry::read_lock()?;
        registry.function_call(self, name, arg)
    }

    /// Call a method on a value.
    ///
    /// Delegates method calls to the singleton function registry.
    ///
    /// # Arguments
    ///
    /// * `name` - The name of the method to call
    /// * `value` - The value on which to call the method
    /// * `arg` - The argument(s) to pass to the method
    ///
    /// # Returns
    ///
    /// Returns a `Result<Value>` containing the method result or an error
    /// if the method is not found or execution fails.
    fn method_call(&mut self, name: &str, value: Value, arg: Value) -> Result<Value> {
        let registry = FunctionRegistry::read_lock()?;
        registry.method_call(self, name, value, arg)
    }

    fn inference_call(&mut self, reference: &Reference, _arg: Value) -> Result<Value> {
        let (scope, node, is_descendent) = self.dereference(reference)?;
        if &self.scope == &scope {
            return Err(anyhow!("Circular inference detected ~{}", scope));
        }
        
        // 1️⃣ Acquire file-specific write lock ONLY when this is a descendant workflow
        let lock_manager = get_lock_manager();
        let _lock_guard = if is_descendent {
            Some(lock_manager.acquire_workflow_lock(scope.clone()))
        } else {
            None
        };
  
        // 2️⃣ Push current state onto stack and switch to the new node workflow
        let stack = self.inference_start(scope);
        // If this is a descendant workflow we will write to it
        self.workflow_mut = if is_descendent {
            // Clone a writable workflow.
            Some(node.get_workflow_mut())
        } else {
            None
        };
        // Get a reference to the read-only workflow.
        self.workflow = node.get_workflow().clone();
    
        // 3️⃣ Assign arguments
        // TODO add argument list to node?

        // Create a provider for Ollama
        let config = get_config().read().unwrap();
        let provider = config.get_provider();

        // 4️⃣ Generate prompt
        if let Ok((system_prompt, user_prompt))
            = generate_prompt(self.workflow.clone(), &provider.capability) {

            // 5️⃣ Send inference request
            match send_request(&provider, &system_prompt, &user_prompt) {
                Ok(inference) => {
                    if let Some(responses) = parse_response(inference.text()) {
                        // 6️⃣ Validate response
                        let _ = validate_responses(self.workflow.clone(), self, responses);
                    }
                    //let input = inference.finish();
                }
                _ => {}
            }
        }

        // 7️⃣ Evaluate workflow expressions
        node.get_workflow().evaluate(self);
        
        // 8️⃣ Save changes
        if is_descendent {
            if let Some(workflow_mut) = &mut self.workflow_mut {
                let _ = workflow_mut.save();
            }
            // Atomically replace the old node workflow with the new workflow.
            if let Some(workflow_mut) = self.workflow_mut.take() {
                node.set_workflow(workflow_mut);
            }
        }

        // 9️⃣ Pop previous state from stack
        self.inference_end(stack);

        // Return results
        Ok(Value::Empty)
        // _lock_guard is dropped here, releasing the lock if it was acquired.
    }
}