aimx/aim/

workflow.rs

//! Workflow container and versioned persistence.
//!
//! Provides rule storage, lookup, and journaled version management for AIMX
//! workflows. Used as the concrete implementation behind [`WorkflowLike`].

use crate::{
    Aim, aim::{BasePath, Journal, Row, Rule, Typedef, Version, Writer, WriterLike, parse_rule, parse_version, read_latest, read_version, save_journal, version::now}, expressions::{Expression, Reference}, literals::parse_unsigned, values::{Errata, Instance, Node, Value}
};
use anyhow::{Result, anyhow};
use jiff::civil::DateTime;
use std::{
    any::Any,
    collections::HashMap,
    fmt::Debug, // Import Debug trait for the trait bound
    fs::OpenOptions,
    io::Write,
    path::{Path, PathBuf},
    sync::Arc,
    fmt,
};

/// Thread-safe abstraction over workflow rule storage and metadata.
///
/// Implemented by concrete workflow containers such as [`Workflow`].
pub trait WorkflowLike: Send + Sync + Debug + 'static {
    // --- Core Metadata ---

    /// Returns the global locator (Reference) for this workflow.
    ///
    /// The locator uniquely identifies the workflow within the workspace.
    fn locator(&self) -> Arc<Reference>;

    /// Returns the file system path to the workflow's AIM file.
    ///
    /// This path points to the `.aim` file that stores the workflow content.
    fn path(&self) -> Arc<PathBuf>;

    fn date(&self) -> DateTime;

    /// Returns the major version (epoch) of the workflow.
    ///
    /// The epoch represents major structural changes to the workflow.
    /// Increments when significant changes are made that require a new version.
    fn version(&self) -> u32;

    /// Returns the minor version (partial) of the workflow.
    ///
    /// The partial represents incremental updates within the same epoch.
    /// Increments for minor changes that don't require a new major version.
    fn minor_version(&self) -> u32;

    // --- Rule Access ---

    /// Gets the row index of a rule by identifier.
    ///
    /// # Parameters
    ///
    /// * `identifier` - The rule identifier
    ///
    /// # Returns
    ///
    /// `Some(usize)` if the rule exists, `None` otherwise.
    fn get_index(&self, identifier: &str) -> Option<usize>;

    /// Retrieves a rule by its row index.
    ///
    /// # Parameters
    /// - `index`: The zero-based row index
    ///
    /// # Returns
    /// `Some(Rule)` if the index is valid and contains a rule, `None` otherwise
    fn get_row(&self, index: usize) -> Row;

    /// Retrieves a rule by its identifier.
    ///
    /// # Parameters
    /// - `identifier`: The rule's unique identifier
    ///
    /// # Returns
    /// `Some(Rule)` if the identifier exists, `None` otherwise
    fn get_rule(&self, identifier: &str) -> Option<Arc<Rule>>;

    // --- Introspection & Bulk Access ---

    /// Checks if a rule with the given identifier exists.
    ///
    /// # Parameters
    /// - `identifier`: The identifier to check
    ///
    /// # Returns
    /// `true` if the rule exists, `false` otherwise
    fn contains(&self, identifier: &str) -> bool;

    /// Checks if a specific row index contains a rule.
    ///
    /// # Parameters
    /// - `index`: The row index to check
    ///
    /// # Returns
    /// `true` if the row contains a rule, `false` if empty or out of bounds
    fn has_rule(&self, index: usize) -> bool;

    /// Returns the number of rules in the workflow.
    ///
    /// This counts only the actual rules, excluding empty rows.
    fn rule_count(&self) -> usize;

    /// Returns the total number of rows in the workflow.
    ///
    /// This includes both rules and empty rows.
    fn row_count(&self) -> usize;

    /// Returns an iterator over all rows.
    ///
    /// The iterator yields `&Option<Rule>` items, including empty rows.
    /// Use this when you need to preserve the exact row structure.
    fn iter_rows<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Row> + 'a>;

    /// Returns an iterator over all rules.
    ///
    /// The iterator yields `&Rule` items, skipping empty rows.
    /// Use this when you only need the actual rules.
    fn iter_rules(&self) -> Box<dyn Iterator<Item = Arc<Rule>> + '_>;

    // --- Trait Object Helper ---

    /// Returns a reference to the workflow as a trait object.
    ///
    /// This method enables downcasting to the concrete workflow type
    /// when working with trait objects.
    fn as_any(&self) -> &dyn Any;
}

/// Workflow execution result used by orchestrators to understand whether
/// evaluation completed, suspended, or failed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum WorkflowStatus {
    /// Evaluation ran to completion.
    Completed,
    /// Evaluation suspended at a rule identifier; may be resumed.
    Suspended { state_id: Arc<str> },
    /// Evaluation failed at or near `state_id` with optional error detail.
    Failed {
        state_id: Option<Arc<str>>,
        errata: Option<Arc<Errata>>,
    },
}

impl WorkflowStatus {
    /// Returns true if the workflow completed successfully.
    pub fn is_completed(&self) -> bool {
        matches!(self, WorkflowStatus::Completed)
    }

    /// Returns the failure Errata when status is Failed.
    pub fn error(&self) -> Option<&Errata> {
        match self {
            WorkflowStatus::Failed {
                errata: Some(e), ..
            } => Some(e),
            _ => None,
        }
    }

    /// Returns the identifier of the rule where execution last stopped
    /// for both Suspended and Failed states.
    pub fn state_id(&self) -> Option<Arc<str>> {
        match self {
            WorkflowStatus::Suspended { state_id }
            | WorkflowStatus::Failed {
                state_id: Some(state_id),
                ..
            } => Some(state_id.clone()),
            _ => None,
        }
    }
}

/// Change classification used to decide how a workflow is persisted.
///
/// `None` → no-op, `Partial` → append partial update, `Version` → write full version.
#[derive(Debug, Clone, PartialEq)]
pub enum Changes {
    /// No changes have been made
    None,
    /// Changes that only require a partial save
    Partial,
    /// Changes that require a full version change
    Version,
}

/// In-memory workflow with journaled versioning for AIMX rules.
///
/// Maintains ordered rule rows plus identifier lookup, tracks changes as
/// [`Changes`], and persists via versioned AIM/journal files.
#[derive(Debug, Clone)]
pub struct Workflow {
    /// A global reference to this workflow's node.
    locator: Arc<Reference>,
    /// Path to the workflow `.aim` file.
    path: Arc<PathBuf>,
    /// Ordered storage of rules; `None` represents an empty row.
    rows: Vec<Row>,
    /// Hash map for identifier-based lookups to row indices.
    lookup: HashMap<Arc<str>, usize>,
    /// Current version
    version: Version,
    /// Version journal
    journals: Vec<Arc<Journal>>,
    /// Type of changes that have been made
    changes: Changes,

    /// This flag allows workflows to track changes for partial saves.
    /// This flag only affects `append_or_update`, `update_rule` and
    /// `set_rule` which are used by `Workflow::parse()`. Normally this
    /// flag should be set to `true` after parsing input, however it should
    /// be set to `true` before loading a previous versions it ensures all
    /// 'recovered' rules are saved.
    track_changes: bool,
}

impl PartialEq<Workflow> for Reference {
    fn eq(&self, other: &Workflow) -> bool {
        self == &*other.locator
    }
}

impl PartialEq<Reference> for Workflow {
    fn eq(&self, other: &Reference) -> bool {
        &*self.locator == other
    }
}

impl PartialEq<Workflow> for Workflow {
    fn eq(&self, other: &Workflow) -> bool {
        &self.locator == &other.locator
    }
}


impl WorkflowLike for Workflow {
    // --- Core Metadata ---

    fn locator(&self) -> Arc<Reference> {
        self.locator.clone()
    }

    fn path(&self) -> Arc<PathBuf> {
        self.path.clone()
    }

    fn date(&self) -> DateTime {
        self.version.date()
    }

    fn version(&self) -> u32 {
        self.version.epoch()
    }

    fn minor_version(&self) -> u32 {
        self.version.partial()
    }

    // --- Rule Access ---

    fn get_index(&self, identifier: &str) -> Option<usize> {
        self.lookup.get(identifier).copied()
    }

    fn has_rule(&self, index: usize) -> bool {
        if index < self.rows.len() {
            self.rows[index].is_rule()
        } else {
            false
        }
    }

    // --- Introspection & Bulk Access ---

    fn get_row(&self, index: usize) -> Row {
        if index < self.rows.len() {
            self.rows[index].clone()
        } else {
            Row::Empty
        }
    }

    fn contains(&self, identifier: &str) -> bool {
        self.lookup.contains_key(identifier)
    }

    fn get_rule(&self, identifier: &str) -> Option<Arc<Rule>> {
        self.lookup
            .get(identifier)
            .and_then(|&index| self.rows[index].rule())
    }

    fn rule_count(&self) -> usize {
        self.lookup.len()
    }

    fn row_count(&self) -> usize {
        self.rows.len()
    }

    fn iter_rows<'a>(&'a self) -> Box<dyn Iterator<Item = &'a Row> + 'a> {
        Box::new(self.rows.iter())
    }

    fn iter_rules(&self) -> Box<dyn Iterator<Item = Arc<Rule>> + '_> {
        Box::new(self.rows.iter().filter_map(|row| row.rule()))
    }

    // --- Trait Object Helper ---

    fn as_any(&self) -> &dyn Any {
        self
    }
}

impl Workflow {
    // -----------------------------------------------------------------------------
    // Test Methods
    // -----------------------------------------------------------------------------

    /// Creates a new empty workflow.
    ///
    /// The workflow starts with:
    /// - Empty rule storage
    /// - Version 0.0
    /// - Extract inference pattern
    /// - Empty path and reference
    /// - No changes pending
    /// - Change tracking disabled
    ///

    pub fn for_testing(locator: Arc<Reference>) -> Result<Self> {
        let path: Arc<PathBuf> = Arc::new(PathBuf::from("test.aim"));
        Ok(Self::new_from(locator, path))
    }

    /// Creates a new workflow by parsing AIM content.
    ///
    /// This constructor parses the provided AIM content and creates a workflow
    /// with the parsed rules. Change tracking is automatically enabled.
    ///

    pub fn parse_for_tests(input: &str) -> Result<Self> {
        let mut workflow = Self::for_testing(Reference::workspace())?;
        workflow.parse(input, None)?;
        Ok(workflow)
    }

    // -----------------------------------------------------------------------------
    // Api Methods
    // -----------------------------------------------------------------------------

    // Called exclusively by Workspace::create
    pub fn new_from(locator: Arc<Reference>, path: Arc<PathBuf>) -> Self {
        Workflow {
            locator,
            path,
            rows: Vec::new(),
            lookup: HashMap::new(),
            version: Version::new(0, 0, now()),
            journals: Vec::new(),
            changes: Changes::None,
            track_changes: true,
        }
    }

    /// Creates a new workflow by loading from a global locator (Reference).
    ///
    /// This constructor loads a workflow from the file system based on the
    /// provided locator. If the file doesn't exist, an empty workflow
    /// is created with the locator set.
    ///

    pub fn open(locator: Arc<Reference>) -> Result<Self> {
        let path = BasePath::convert(&locator)?;
        let mut workflow = Self::new_from(locator, path);
        if workflow.path.exists() {
            workflow.load()?;
        }
        Ok(workflow)
    }

    /// Checks if the workflow has unsaved changes.
    ///
    /// # Returns
    ///
    /// `true` if the workflow has changes that need to be saved, `false` otherwise.
    pub fn is_touched(&self) -> bool {
        self.changes != Changes::None
    }

    /// Flags changes that only require a partial save.
    ///
    /// This method escalates the change status from `None` to `Partial`.
    /// If changes are already at `Partial` or `Version`, they remain unchanged.
    pub fn set_partial_change(&mut self) {
        // We only escalate partial changes from none
        if self.changes == Changes::None {
            self.changes = Changes::Partial;
        }
    }

    /// Flags changes that require a version change on save.
    ///
    /// This method sets the change status to `Version`, indicating that
    /// structural changes have been made that require a new version.
    pub fn set_version_change(&mut self) {
        self.changes = Changes::Version;
    }

    /// Clears the changes flag.
    ///
    /// This method is typically called after a successful save operation
    /// to reset the change tracking state.
    pub fn clear_changes(&mut self) {
        self.changes = Changes::None;
    }

    /// Gets the first version number from the journal.
    ///
    /// # Returns
    ///
    /// The epoch of the first version, or 0 if no versions exist.
    pub fn first_version(&self) -> u32 {
        if self.journals.is_empty() {
            0
        } else {
            // first() guaranteed to exist
            self.journals.first().unwrap().version()
        }
    }

    /// Gets the latest version number from the journal.
    ///
    /// # Returns
    ///
    /// The epoch of the latest version, or 0 if no versions exist.
    pub fn latest_version(&self) -> u32 {
        if self.journals.is_empty() {
            0
        } else {
            // last() guaranteed to exist
            self.journals.last().unwrap().version()
        }
    }

    /// Test-only: override the workflow file path.
    pub fn set_path(&mut self, path: &Path) {
        self.path = Arc::new(path.to_path_buf());
    }

    /// Loads a specific version of an AIM file.
    ///
    /// This method loads a particular version (and optionally a specific partial)
    /// from the AIM file. After loading, the workflow switches back to the latest
    /// version but flags that a version change is needed since the loaded version
    /// differs from the current one.
    ///
    /// # Parameters
    ///
    /// * `path` - The path to the AIM file
    /// * `version` - The epoch version to load
    /// * `partial` - Optional partial version within the epoch
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if the version cannot be loaded.
    pub fn load_version(&mut self, version: u32, partial: Option<u32>) -> Result<()> {
        // Read the contents of specific version section
        let contents = read_version(&mut self.journals, &self.path, version)?;
        self.version.set_epoch(version);
        // IMPORTANT! parser will throw an error if version is not found
        self.parse(&contents, partial)?;
        // Switch back to the latest version
        self.version.set_epoch(self.latest_version());
        // This is different to the latest version so flag a version change
        self.set_version_change();
        Ok(())
    }

    /// Loads the latest version of an AIM file.
    ///
    /// This method loads the most recent version from the AIM file and
    /// clears any pending changes. Change tracking is enabled after loading.
    ///
    /// # Parameters
    ///
    /// * `path` - The path to the AIM file
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if the file cannot be loaded.
    pub fn load(&mut self) -> Result<()> {
        // Read the latest section
        let contents = read_latest(&mut self.journals, &self.path)?;
        self.version.set_epoch(self.latest_version());
        self.track_changes = false;
        self.parse(&contents, None)?;
        self.clear_changes();
        self.track_changes = true;
        Ok(())
    }

    /// Saves the AIM structure to its associated file.
    ///
    /// This function saves changes to the AIM file based on the type of changes made:
    /// - `Changes::Version`: Creates a new version with incremented epoch
    /// - `Changes::Partial`: Creates a partial update with incremented partial counter
    /// - `Changes::None`: No changes to save, returns Ok(())
    ///
    /// The function also updates the journal file with position information for fast lookup.
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if the save operation fails.
    ///
    pub fn save(&mut self) -> Result<()> {
        let mut writer = Writer::formulizer();
        let mut new_version = self.version.clone();
        let mut update_journal = false;
        // Guarantee a version header on the first save
        if self.version.epoch() == 0 {
            self.set_version_change();
        }
        match self.changes {
            Changes::Version => {
                new_version.increment_epoch();
                new_version.print(&mut writer);
                // Collect touched rows first to avoid borrowing conflicts
                let mut touched_rows = Vec::new();
                for (index, row) in self.iter_with_rows() {
                    let untouched = row.save(&mut writer);
                    if let Some(row) = untouched {
                        touched_rows.push((index, row));
                    }
                }
                // Now update the rows after the iteration is complete
                for (index, row) in touched_rows {
                    self.rows[index] = row;
                }
                update_journal = true;
            }
            Changes::Partial => {
                new_version.increment_partial();
                new_version.print(&mut writer);
                // Collect touched rows first to avoid borrowing conflicts
                let mut touched_rows = Vec::new();
                for (index, row) in self.iter_with_rows() {
                    let untouched = row.partial_save(index, &mut writer);
                    if let Some(row) = untouched {
                        touched_rows.push((index, row));
                    }
                }
                // Now update the rows after the iteration is complete
                for (index, row) in touched_rows {
                    self.rows[index] = row;
                }
            }
            Changes::None => return Ok(()),
        }
        // Open file for appending
        let mut file = OpenOptions::new()
            .create(true)
            .append(true)
            .open(&*self.path)?;

        if update_journal {
            self.journals
                .push(Arc::new(Journal::new(new_version.epoch(), file.metadata()?.len(), now())));
            save_journal(&self.path, &self.journals)?;
        }
        file.write(writer.finish().as_bytes())?;
        self.version = new_version;
        self.clear_changes();
        Ok(())
    }

    pub fn save_all(&mut self) -> Result<()> {
        // Recursively save child nodes and instances
        for rule in self.iter_rules() {
            if let Some(node) = rule.get_node() {
                node.save_all()?;
            // Also handle instances within this workflow
            } else if let Some(instance) = rule.get_instance() {
                instance.save_all()?;
            }
        }
        self.save()
    }

    pub fn check_identifier_unique(&self, identifier: &str) -> Result<()> {
        Aim::check_identifier(identifier)?;
        if self.contains(&identifier) {
            return Err(anyhow!("Rule {} exists in {}", identifier, self.locator));
        }
        Ok(())
    }

    pub fn add_node(&mut self, identifier: Arc<str>, node: Node) -> Result<Arc<Reference>> {
        self.check_identifier_unique(&identifier)?;

        // If this is the workspace make a new top level reference
        let reference = if self.locator.contains_root() {
            Reference::new(identifier.clone())
        } else {
            Arc::new(self.locator.add_child(identifier.clone())?)
        };

        // Initialize as Unloaded
        node.init(reference.clone());

        let rule = Rule::new(
            identifier,
            Typedef::Node,
            Expression::Empty,
            Arc::new(Value::Node(node))
        );
        self.append_or_update(Row::Rule(Arc::new(rule)));
        Ok(reference)
    }

    pub fn copy_node(&mut self, from: &Node, to: Arc<str>) -> Result<()> {
        self.check_identifier_unique(&to)?;
        let from_workflow = from.get_workflow_like()?;
        let from_path = from_workflow.path();

        // Create and add new node reference
        let to_reference = if &*self.locator == "_" {
            Reference::new(to.clone())
        } else {
            Arc::new(self.locator.add_child(to.clone())?)
        };

        // Construct target path for the new node
        let base_path = self.path.with_extension("");
        if !base_path.exists() {
            std::fs::create_dir_all(&base_path)?;
        }
        let to_path = base_path.join(format!("{}.aim", to));

        // Copy AIM file if it exists
        if from_path.exists() {
            std::fs::copy(&*from_path, &*to_path)?;
        }
        
        // Copy JNL file if it exists
        let from_jnl_path = from_path.with_extension("jnl");
        let to_jnl_path = to_path.with_extension("jnl");
        if from_jnl_path.exists() {
            std::fs::copy(&from_jnl_path, &to_jnl_path)?;
        }
        
        // Copy directory contents recursively if it exists (for child nodes)
        let from_dir_path = from_path.with_extension("");
        let to_dir_path = to_path.with_extension("");
        if from_dir_path.exists() && from_dir_path.is_dir() {
            if to_dir_path.exists() {
                std::fs::remove_dir_all(&to_dir_path)?;
            }
            Self::copy_dir_all(&from_dir_path, &to_dir_path)?;
        }
        
        let node = Node::init_new(to_reference, from.inference());
        self.add_node(to.clone(), node)?;
        Ok(())
    }

    /// Recursively copy directory contents
    fn copy_dir_all(src: &Path, dst: &Path) -> Result<()> {
        std::fs::create_dir_all(dst)?;
        for entry in std::fs::read_dir(src)? {
            let entry = entry?;
            let file_type = entry.file_type()?;
            let dst_path = dst.join(entry.file_name());
            
            if file_type.is_dir() {
                Self::copy_dir_all(&entry.path(), &dst_path)?;
            } else {
                std::fs::copy(entry.path(), dst_path)?;
            }
        }
        Ok(())
    }

    pub fn get_node(&self, identifier: &str) -> Result<Node> {
        if let Some(rule) = self.get_rule(identifier) {
            if let Some(node) = rule.get_node() {
                return Ok(node);
            }
        }
        return Err(anyhow!("Node {} not found", identifier));
    }

    pub fn rename_node(&mut self, from: &str, to: Arc<str>) -> Result<()> {
        self.check_identifier_unique(&to)?;
        if let Some(from_rule) = self.get_rule(from) {
            // Save the 'from' workflow before renaming its node
            if let Some(from_node) = from_rule.get_node() {
                let from_workflow = from_node.get_workflow_like()?;
                let from_path = from_workflow.path();

                // Rename the workflow node
                if let Some(index) = self.get_index(from) {
                    match self.get_row(index) {
                        Row::Rule(from_rule) 
                        | Row::Touched(from_rule) => {
                            let to_rule = Arc::new(from_rule.clone().rename_node(to.clone())?);
                            // Clear the previous row
                            self.replace_row(index, Row::Touched(to_rule.clone()))?;

                            // Rename associated files if they exist
                            if from_path.exists() {
                                // Rename the .aim file
                                let to_path = from_path.with_file_name(format!("{}.aim", to));
                                std::fs::rename(&*from_path, &to_path)?;
                                
                                // Rename the .jnl file
                                let from_jnl_path = from_path.with_extension("jnl");
                                if from_jnl_path.exists() {
                                    let to_jnl_path = to_path.with_extension("jnl");
                                    std::fs::rename(from_jnl_path, to_jnl_path)?;
                                }
                                
                                // Rename the directory if it exists (for child nodes)
                                let from_dir_path = from_path.with_extension("");
                                if from_dir_path.exists() && from_dir_path.is_dir() {
                                    let to_dir_path = to_path.with_extension("");
                                    std::fs::rename(from_dir_path, to_dir_path)?;
                                }
                            }
                            return Ok(())
                        }
                        _ => unreachable!(),
                    }
                }
            }
        }
        Err(anyhow!("Node {} not found", from))
    }

    pub fn delete_node(&mut self, identifier: &str) -> Result<()> {
        if let Some(rule) = self.get_rule(identifier) {
            // Save the 'from' workflow before renaming its node
            if let Some(node) = rule.get_node() {
                let workflow = node.get_workflow_like()?;
                let node_path = workflow.path();
                
                self.delete_rule(identifier);
                // Remove associated files

                // Remove the .aim file
                if node_path.exists() {
                    std::fs::remove_file(&*node_path)?;
                }
                
                // Remove the .jnl file
                let jnl_path = node_path.with_extension("jnl");
                if jnl_path.exists() {
                    std::fs::remove_file(jnl_path)?;
                }
                
                // Remove the directory if it exists (for child nodes)
                let dir_path = node_path.with_extension("");
                if dir_path.exists() && dir_path.is_dir() {
                    std::fs::remove_dir_all(dir_path)?;
                }
                return Ok(())
            }
        }
        return Err(anyhow!("Node {} not found", identifier));
    }

    pub fn add_instance(&mut self, identifier: Arc<str>, source: Arc<Reference>, target: Arc<Reference>) -> Result<()> {
        self.check_identifier_unique(&identifier)?;
        let instance = Instance::new(source, target);
        let rule = Rule::new(
            identifier,
            Typedef::Instance,
            Expression::Empty,
            Arc::new(Value::Instance(instance))
        );
        Ok(self.append_or_update(Row::Rule(Arc::new(rule))))
    }

    /// Appends a row to the workflow or updates an existing rule.
    ///
    /// If a rule with the same identifier already exists, it is updated.
    /// Otherwise, the rule is appended to the end of the workflow.
    ///
    /// # Parameters
    ///
    /// * `row` - The rule to append or update
    pub fn append_or_update(&mut self, row: Row) {
        match row {
            Row::Rule(rule) | Row::Touched(rule) => {
                // Update if the rule already exists
                if self.lookup.contains_key(&rule.identifier()) {
                    // Rule update guaranteed because identifier exists
                    self.update_rule(rule).unwrap();
                    return;
                }
                if Aim::check_identifier(&rule.identifier()).is_ok() {
                    let index = self.rows.len();
                    self.lookup.insert(rule.identifier().clone(), index);
                    if self.track_changes {
                        self.set_partial_change();
                        self.rows.push(Row::Touched(rule));
                    } else {
                        self.rows.push(Row::Rule(rule));
                    }
                }
            }
            _ => {
                if self.track_changes {
                    self.set_version_change();
                }
                self.rows.push(row);
            }
        }
    }

    /// Updates an existing rule.
    ///
    /// # Parameters
    ///
    /// * `rule` - The updated rule
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if the rule doesn't exist.
    pub fn update_rule(&mut self, rule: Arc<Rule>) -> Result<()> {
        match self.lookup.get(&rule.identifier()) {
            Some(&index) => {
                if self.track_changes {
                    self.set_partial_change();
                    self.rows[index] = Row::Touched(rule);
                } else {
                    self.rows[index] = Row::Rule(rule);
                }
                Ok(())
            }
            None => Err(anyhow!("Rule {} not found in {}", rule.identifier(), self.locator())),
        }
    }

    /// Updates an existing rule value.
    ///
    /// # Parameters
    ///
    /// * `identifier` = The rule identifier
    /// * `value` - The new value
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if the rule doesn't exist.
    pub fn update_value(&mut self, identifier: &str, value: Arc<Value>) -> Result<()> {
        if let Some(&index) = self.lookup.get(identifier) {
            let arc_rule = self.rows[index].rule().unwrap();
            if arc_rule.value().as_ref() != &*value {
                let mut new_rule = (*arc_rule).clone();
                let _ = new_rule.set_value(value);
                if self.track_changes {
                    self.set_partial_change();
                    self.rows[index] = Row::Touched(Arc::new(new_rule));
                } else {
                    self.rows[index] = Row::Rule(Arc::new(new_rule));
                }
            }
            Ok(())
        } else {
            Err(anyhow!("Rule {} not found in {}", identifier, self.locator()))
        }
    }

    /// Deletes a rule by identifier.
    ///
    /// # Parameters
    ///
    /// * `identifier` - The rule identifier to delete
    ///
    /// # Returns
    ///
    /// `Some(Rule)` if the rule was deleted, `None` if it didn't exist.
    pub fn delete_rule(&mut self, identifier: &str) -> Row {
        match self.lookup.remove(identifier) {
            Some(index) => {
                self.set_version_change();
                let row = self.rows.remove(index);
                self.reindex();
                row
            }
            None => Row::Empty,
        }
    }

    // --- Indexed Rule Access --

    /// Sets a rule at a specific row index.
    ///
    /// If a rule already exists at the specified index with a different identifier,
    /// this method will return an error. If the index is beyond the current size
    /// of the workflow, the rows vector will be expanded to accommodate it.
    ///
    /// # Parameters
    ///
    /// * `index` - The zero-based row index where to place the rule
    /// * `row` - The rule to set, or None to create an empty row
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if there's a conflict with an existing rule
    pub fn set_row(&mut self, index: usize, row: Row) -> Result<()> {
        if let Row::Rule(rule) | Row::Touched(rule) = row {
            Aim::check_identifier(&rule.identifier())?;
            // Check if the rule identifier already exists
            if self.lookup.contains_key(&rule.identifier()) {
                if index < self.rows.len() {
                    // Get the rule at the specified index
                    match &self.rows[index] {
                        Row::Rule(old_rule) | Row::Touched(old_rule) => {
                            // Ensure the new rule and old rule identifiers match
                            if rule.identifier() != old_rule.identifier() {
                                return Err(anyhow!("Rule mismatch {} at {}[{}], found {}", rule.identifier(), self.locator(), index, old_rule.identifier()));
                            }
                            // Manage this special case
                            if self.track_changes {
                                self.set_partial_change();
                                self.rows[index] = Row::Touched(rule);
                            } else {
                                self.rows[index] = Row::Rule(rule);
                            }
                            return Ok(());
                        }
                        _ => {
                            return Err(anyhow!("No Rule {} at {}[{}]", rule.identifier(), self.locator(), index));
                        }
                    }
                } else {
                    return Err(anyhow!("Rule {} is missing at {}[{}]", rule.identifier(), self.locator(), index));
                }
            }
            // Expand vector if needed
            if index >= self.rows.len() {
                self.rows.resize_with(index + 1, || Row::Empty);
            }
            // Insert at specified position
            self.lookup.insert(rule.identifier().clone(), index);
            if self.track_changes {
                self.set_partial_change();
                self.rows[index] = Row::Touched(rule);
            } else {
                self.rows[index] = Row::Rule(rule);
            }
        } else {
            // Expand vector if needed
            if index >= self.rows.len() {
                self.rows.resize_with(index + 1, || Row::Empty);
            }
            if self.track_changes {
                self.set_partial_change();
            }
            self.rows[index] = row;
        }
        Ok(())
    }

    /// Inserts a rule at a specific row index.
    ///
    /// This method inserts a rule at the specified index, shifting existing rules
    /// to higher indices. If the index is beyond the current size of the workflow,
    /// empty rows will be created as needed. If a rule with the same identifier
    /// already exists in the workflow, this method returns an error.
    ///
    /// # Parameters
    ///
    /// * `index` - The zero-based row index where to insert the rule
    /// * `row` - The rule to insert, or None to create an empty row
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if a rule with the same identifier already exists
    pub fn insert_row(&mut self, index: usize, row: Row) -> Result<()> {
        if let Row::Rule(rule) | Row::Touched(rule) = &row {
            Aim::check_identifier(&rule.identifier())?;
            if self.lookup.contains_key(&rule.identifier()) {
                return Err(anyhow!("Rule {} exists in {}", rule.identifier(), self.locator));
            }
            if index >= self.rows.len() {
                // Expand vector if needed
                if index > self.rows.len() {
                    self.rows.resize_with(index, || Row::Empty);
                }
                // and append
                self.lookup.insert(rule.identifier().clone(), index);
                self.rows.push(row);
            } else {
                // Insert at specified position
                self.lookup.insert(rule.identifier().clone(), index);
                self.rows.insert(index, row);
            }
        } else if index >= self.rows.len() {
            // Expand vector if needed
            if index > self.rows.len() {
                self.rows.resize_with(index, || Row::Empty);
            }
            // and append
            self.rows.push(row);
        } else {
            self.rows.insert(index, row);
        }

        // Update indices of all rows
        self.reindex();
        self.set_version_change();
        Ok(())
    }

    /// Repositions a rule from one row index to another.
    ///
    /// This method moves a rule from the `from` index to the `to` index,
    /// shifting other rules as needed. If either index is beyond the current
    /// size of the workflow, the rows vector will be expanded to accommodate them.
    ///
    /// # Parameters
    ///
    /// * `from` - The current zero-based row index of the rule to move
    /// * `to` - The target zero-based row index where to place the rule
    ///
    /// # Returns
    ///
    /// `Ok(())` if successful, or an error if the operation fails
    pub fn reposition_row(&mut self, from: usize, to: usize) -> Result<()> {
        if from != to {
            // Expand vectors if needed
            let max_row = from.max(to);
            if max_row >= self.rows.len() {
                self.rows.resize_with(max_row + 1, || Row::Empty);
            }
            self.set_partial_change();

            // Check if there's actually a rules to move
            if self.rows[from].is_empty() && self.rows[to].is_empty() {
                return Ok(());
            }

            let row = self.rows.remove(from);
            self.rows.insert(to, row);

            // Rebuild index mappings due to reordering
            self.reindex();
        }
        Ok(())
    }

    pub fn replace_row(&mut self, index: usize, row: Row) -> Result<()> {
        if let Row::Rule(new_rule) | Row::Touched(new_rule) = row {
            Aim::check_identifier(&new_rule.identifier())?;
            // Check if the rule identifier already exists
            if self.lookup.contains_key(&new_rule.identifier()) {
                if index < self.rows.len() {
                    // Get the rule at the specified index
                    match &self.rows[index] {
                        // Check if the old row is a rule
                        Row::Rule(old_rule) | Row::Touched(old_rule) => {
                            // Ensure the new rule and old rule identifiers match
                            if new_rule.identifier() != old_rule.identifier() {
                                return Err(anyhow!("Rule {} already exists in {}", new_rule.identifier(), self.locator()));
                            }
                            // Manage changes
                            if self.track_changes {
                                self.set_partial_change();
                                self.rows[index] = Row::Touched(new_rule);
                            } else {
                                self.rows[index] = Row::Rule(new_rule);
                            }
                            return Ok(());
                        }
                        _ => {}
                    }
                } else {
                    return Err(anyhow!("Rule {} is missing at {}[{}]", new_rule.identifier(), self.locator(), index));
                }
            }
            // Expand vector if needed
            if index >= self.rows.len() {
                self.rows.resize_with(index + 1, || Row::Empty);
            }
            // Insert at specified position
            self.lookup.insert(new_rule.identifier().clone(), index);
            if self.track_changes {
                self.set_partial_change();
                self.rows[index] = Row::Touched(new_rule);
            } else {
                self.rows[index] = Row::Rule(new_rule);
            }
        } else {
            // Expand vector if needed
            if index >= self.rows.len() {
                self.rows.resize_with(index + 1, || Row::Empty);
            }
            if self.track_changes {
                self.set_partial_change();
            }
            self.rows[index] = row;
        }
        self.reindex();
        Ok(())
    }


    /// Clears a row at a specific index, removing the rule if present.
    ///
    /// This method removes the rule at the specified index but keeps the row
    /// structure intact. The row will become empty but still exist in the workflow.
    /// If the index is out of bounds, this method returns None.
    ///
    /// # Parameters
    ///
    /// * `index` - The zero-based row index to clear
    ///
    /// # Returns
    ///
    /// `Some(Rule)` if a rule was present and removed, `None` if the row was already empty or index was out of bounds
    pub fn clear_row(&mut self, index: usize) -> Row {
        // Check bounds
        if index >= self.rows.len() {
            return Row::Empty;
        }
        self.set_version_change();
        let row = self.rows[index].clone();
        self.rows[index] = Row::Empty;
        if let Row::Rule(rule) | Row::Touched(rule) = &row {
            self.lookup.remove(&rule.identifier());
        }
        row
    }

    /// Removes a row at a specific index, removing the rule and shrinking the workflow.
    ///
    /// This method removes the rule at the specified index and removes the row
    /// entirely from the workflow, shifting subsequent rows to lower indices.
    /// If the index is out of bounds, this method returns None.
    ///
    /// # Parameters
    ///
    /// * `index` - The zero-based row index to remove
    ///
    /// # Returns
    ///
    /// `Some(Rule)` if a rule was present and removed, `None` if the index was out of bounds
    pub fn remove_row(&mut self, index: usize) -> Row {
        if index >= self.rows.len() {
            return Row::Empty;
        }
        self.set_version_change();
        let row = self.rows.remove(index);
        self.reindex();
        row
    }

    /// Create an iterator over the rules with their indices.
    ///
    /// This iterator yields tuples of `(index, &Option<Rule>)`, providing
    /// both the position and content of each row including empty ones.
    pub fn iter_with_rows(&self) -> impl Iterator<Item = (usize, &Row)> {
        self.rows
            .iter()
            .enumerate()
            .map(|(index, row)| (index, row))
    }

    /// Rebuilds the lookup mapping index.
    ///
    /// This helper function rebuilds the internal hash map that maps rule identifiers
    /// to their row indices. It's called automatically after operations that change
    /// the position of rules within the workflow.
    pub fn reindex(&mut self) {
        self.lookup.clear();
        for (index, row) in self.rows.iter().enumerate() {
            if let Row::Rule(rule) | Row::Touched(rule) = row {
                self.lookup.insert(rule.identifier().clone(), index);
            }
        }
    }

    /// Parses AIM content and populates the workflow.
    ///
    /// This method parses AIM format content and creates rules based on the parsed data.
    /// It can optionally parse only up to a specific partial version. The method clears
    /// the current workflow contents before parsing.
    /// 
    /// # Special tokens and their meanings
    /// 
    /// - `[` .. `]` HEADER: Used to signify a version header.
    /// - `:` PARTIAL: Used inside a workflow header to signify a minor version number.
    /// - `@` DATETIME: Used inside a workflow header to signify the snapshot date and time.
    /// - `#` COMMENT: Used to signify a comment.
    /// - `$` CONSTANT: Used inside rule a definitions to signify a constant variable.
    /// - `(` .. `)` Delimits expression parenthesis
    /// - `{` .. `}` Delimits and expression collection
    /// - `"` | `'` Delimits strings
    /// - `^`, `!`, `&`, `%`, `*` Potentially available
    ///
    /// # Parameters
    ///
    /// * `input` - The AIM content to parse
    /// * `partial` - Optional partial version to parse up to
    ///
    /// # Returns
    ///
    /// `Ok(())` if parsing was successful, or an error if parsing failed
    pub fn parse(&mut self, input: &str, partial: Option<u32>) -> Result<()> {
        // Clear contents
        self.rows.clear();
        self.lookup.clear();
        self.clear_changes();

        let lines: Vec<&str> = input.lines().collect();
        let mut is_version = false;
        let mut is_partial = false;

        for line in lines {
            let mut opt_index: Option<u32> = None;
            let mut line = line.trim();
            // Append empty lines to maintain row spacing in first (non-partial) section
            if line.is_empty() {
                if is_version && self.version.partial() == 0 {
                    self.append_or_update(Row::Empty);
                }
                continue;
            }

            // Try to parse comment (lines starting with #)
            if line.starts_with('#') {
                if is_version && self.version.partial() == 0 {
                    self.append_or_update(Row::Comment(Arc::from(line)));
                }
                continue;
            }

            // Try to parse version headers (lines starting with [)
            if line.starts_with('[') {
                match parse_version(line) {
                    Ok((_, current)) => {
                        // When version/epoch is 0, assign the first version header encountered
                        if self.version.epoch() == 0 {
                            is_version = true;
                            self.version = current;
                        }
                        // When epoch is known, merge partials
                        else if self.version.epoch() == current.epoch() {
                            is_version = true;
                            // We've moved past the target partial, stop parsing
                            if is_partial {
                                break;
                            }
                            self.version.set_partial(current.partial());
                            self.version.set_date(current.date());
                            if let Some(opt_partial) = partial {
                                if opt_partial == current.partial() {
                                    is_partial = true;
                                }
                            }
                        } else if is_version {
                            // We've moved past the target version, stop parsing
                            break;
                        }
                    }
                    // Skip lines with syntax errors
                    Err(_e) => {}
                }
                continue;
            }

            // If we haven't found the target version yet, skip this line
            if !is_version {
                continue;
            }

            // Try to parse leading number (rule index used by partial saves)
            if line.chars().next().map_or(false, |c| c.is_ascii_digit()) {
                match parse_unsigned(line) {
                    Ok((remainder, index)) => {
                        opt_index = Some(index);
                        line = remainder;
                    }
                    Err(_) => {}
                }
            }

            // Try to parse rule
            match parse_rule(line) {
                Ok(rule) => {
                    // If this is a node-typed rule, synthesize a lazy Node value now that
                    // we know the workflow locator. This keeps parsing simple while
                    // ensuring node rules always carry a concrete Node reference.
                    if rule.typedef().is_node() {
                        if let Some(node) = rule.get_node() {
                            // Derive a child reference from the workflow locator + rule identifier.
                            // Reference::new uses the identifier as a segment; append composes
                            // a hierarchical locator like `parent.child`.
                            let reference = self.locator.add_child(rule.identifier())?;
                            // Initialize the node as Unloaded
                            node.init(Arc::new(reference));
                        }
                    }

                    match opt_index {
                        Some(index) => {
                            // Set rule at index
                            if self.contains(&rule.identifier()) {
                                let _ = self.update_rule(Arc::new(rule));
                            } else {
                                let _ = self.set_row(index as usize, Row::Rule(Arc::new(rule)));
                            }
                        }
                        None => {
                            // Append or overwrite existing rule
                            self.append_or_update(Row::Rule(Arc::new(rule)));
                        }
                    }
                }
                Err(_) => {
                    // Ignore syntax errors, but maintain row spacing in (non-partial) sections
                    if self.version.partial() == 0 {
                        self.append_or_update(Row::Empty);
                    }
                }
            }
        }

        if !is_version && self.version.epoch() > 0 {
            return Err(anyhow!("Version {} not found", self.version.epoch()));
        }

        Ok(())
    }

    pub fn print(&self, writer: &mut Writer) {
        if writer.is_formulizer() {
            self.version.print(writer);
        }
        for row in self.iter_rows() {
            row.print(writer);
        }
    }

    /// Return the formula-string representation (round-trippable by the parser).
    pub fn to_formula(&self) -> String {
        let mut writer = Writer::formulizer();
        self.print(&mut writer);
        writer.finish()
    }
}

impl WriterLike for Workflow {
    fn write(&self, writer: &mut Writer) {
        self.print(writer);
    }
}

impl fmt::Display for Workflow {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.to_stringized())
    }
}