rvf 0.1.0

//! Actions that define what a flow does
//!
//! Actions define what an economic flow (event, commitment, intent) does and how
//! it affects economic resources. This is a core part of the ValueFlows vocabulary.

use std::fmt;

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

/// The type of action being performed
///
/// Actions define what a flow does. They are used in Economic Events, Commitments,
/// Intents, and Recipe Flows to specify the behavior and resource effects.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum ActionType {
    // Production actions
    /// A new resource is created in the process
    Produce,
    /// A resource is consumed/used up in the process
    Consume,
    /// A resource is used but not consumed (e.g., equipment)
    Use,

    // Knowledge/design actions
    /// A resource is referenced without being consumed or used
    Cite,

    // Work actions
    /// Labor/work applied to a process
    Work,

    // Transportation actions
    /// A resource enters a transportation process
    Pickup,
    /// A resource exits a transportation process
    Dropoff,

    // Modification actions
    /// A resource enters a modification/repair process
    Accept,
    /// A resource exits a modification/repair process with changes
    Modify,

    // Container/combination actions
    /// A resource is combined into a package or container
    Combine,
    /// A resource is separated from a package or container
    Separate,

    // Service actions
    /// A service is delivered (created and consumed simultaneously)
    DeliverService,

    // Transfer actions
    /// Transfer full rights without physical transfer
    TransferAllRights,
    /// Transfer physical custody without rights
    TransferCustody,
    /// Transfer both rights and custody
    Transfer,

    // Movement actions
    /// Move a resource to a different location
    Move,

    // Digital actions
    /// Create a copy of a digital resource
    Copy,

    // Adjustment actions
    /// Adjust quantity upward (inventory correction)
    Raise,
    /// Adjust quantity downward (inventory correction)
    Lower,
}

impl ActionType {
    /// Get the string representation of the action
    pub fn as_str(&self) -> &'static str {
        match self {
            ActionType::Produce => "produce",
            ActionType::Consume => "consume",
            ActionType::Use => "use",
            ActionType::Cite => "cite",
            ActionType::Work => "work",
            ActionType::Pickup => "pickup",
            ActionType::Dropoff => "dropoff",
            ActionType::Accept => "accept",
            ActionType::Modify => "modify",
            ActionType::Combine => "combine",
            ActionType::Separate => "separate",
            ActionType::DeliverService => "deliverService",
            ActionType::TransferAllRights => "transferAllRights",
            ActionType::TransferCustody => "transferCustody",
            ActionType::Transfer => "transfer",
            ActionType::Move => "move",
            ActionType::Copy => "copy",
            ActionType::Raise => "raise",
            ActionType::Lower => "lower",
        }
    }

    /// Parse an action type from a string
    pub fn from_str(s: &str) -> Option<Self> {
        match s.to_lowercase().as_str() {
            "produce" => Some(ActionType::Produce),
            "consume" => Some(ActionType::Consume),
            "use" => Some(ActionType::Use),
            "cite" => Some(ActionType::Cite),
            "work" => Some(ActionType::Work),
            "pickup" => Some(ActionType::Pickup),
            "dropoff" => Some(ActionType::Dropoff),
            "accept" => Some(ActionType::Accept),
            "modify" => Some(ActionType::Modify),
            "combine" => Some(ActionType::Combine),
            "separate" => Some(ActionType::Separate),
            "deliverservice" | "deliver_service" => Some(ActionType::DeliverService),
            "transferallrights" | "transfer_all_rights" => Some(ActionType::TransferAllRights),
            "transfercustody" | "transfer_custody" => Some(ActionType::TransferCustody),
            "transfer" => Some(ActionType::Transfer),
            "move" => Some(ActionType::Move),
            "copy" => Some(ActionType::Copy),
            "raise" => Some(ActionType::Raise),
            "lower" => Some(ActionType::Lower),
            _ => None,
        }
    }

    /// Check if this action is a transfer action
    pub fn is_transfer(&self) -> bool {
        matches!(
            self,
            ActionType::Transfer | ActionType::TransferAllRights | ActionType::TransferCustody
        )
    }

    /// Check if this action is a production action
    pub fn is_production(&self) -> bool {
        matches!(
            self,
            ActionType::Produce | ActionType::Consume | ActionType::Use
        )
    }

    /// Check if this action is a transportation action
    pub fn is_transportation(&self) -> bool {
        matches!(self, ActionType::Pickup | ActionType::Dropoff)
    }

    /// Check if this action pairs with another (for same resource through process)
    pub fn pairs_with(&self) -> Option<ActionType> {
        match self {
            ActionType::Pickup => Some(ActionType::Dropoff),
            ActionType::Dropoff => Some(ActionType::Pickup),
            ActionType::Accept => Some(ActionType::Modify),
            ActionType::Modify => Some(ActionType::Accept),
            ActionType::Combine => Some(ActionType::Separate),
            ActionType::Separate => Some(ActionType::Combine),
            _ => None,
        }
    }
}

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

impl Default for ActionType {
    fn default() -> Self {
        ActionType::Transfer
    }
}

/// How a flow affects resource quantities
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum ActionEffect {
    /// Increases the resource quantity
    Increment,
    /// Decreases the resource quantity
    Decrement,
    /// No effect on quantity
    NoEffect,
    /// Decrements one resource and increments another
    DecrementIncrement,
    /// Increments a "to" resource
    IncrementTo,
}

/// Input or output of a process
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum InputOutput {
    /// The flow is an input to a process
    Input,
    /// The flow is an output from a process
    Output,
    /// The flow is both input and output (for services)
    OutputInput,
    /// The flow is not applicable (transfers)
    NotApplicable,
}

/// Complete action definition with all behaviors
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct Action {
    /// The action type
    pub action_type: ActionType,
    /// The label for display
    pub label: String,
    /// Whether resource or effort quantity applies
    pub event_quantity: EventQuantityType,
    /// Input or output of a process
    pub input_output: InputOutput,
    /// If this action pairs with another
    pub pairs_with: Option<ActionType>,
    /// Whether this can create a new resource
    pub create_resource: CreateResource,
    /// Effect on accounting quantity
    pub accounting_effect: ActionEffect,
    /// Effect on onhand quantity
    pub onhand_effect: ActionEffect,
    /// Whether location is updated
    pub location_effect: LocationEffect,
    /// Effect on containment relationship
    pub contained_effect: ContainedEffect,
    /// Effect on primaryAccountable
    pub accountable_effect: AccountableEffect,
    /// Effect on stage
    pub stage_effect: StageEffect,
    /// Effect on state
    pub state_effect: StateEffect,
}

/// What type of quantity applies to an event
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum EventQuantityType {
    /// Only resource quantity applies
    ResourceQuantity,
    /// Only effort quantity applies
    EffortQuantity,
    /// Both resource and effort quantity can apply
    Both,
}

/// Whether a resource is created
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum CreateResource {
    /// No resource is created
    No,
    /// Resource creation is optional
    Optional,
    /// Resource creation to "to" resource is optional
    OptionalTo,
}

/// How location is affected
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum LocationEffect {
    /// No location effect
    NoEffect,
    /// Location is set for new resources
    New,
    /// Location is updated
    Update,
    /// Location is updated on "to" resource
    UpdateTo,
}

/// How containment is affected
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum ContainedEffect {
    /// No containment effect
    NoEffect,
    /// Containment is updated
    Update,
    /// Containment is removed
    Remove,
}

/// How primaryAccountable is affected
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum AccountableEffect {
    /// No accountable effect
    NoEffect,
    /// Accountable is set for new resources
    New,
    /// Accountable is updated on "to" resource
    UpdateTo,
}

/// How stage is affected
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum StageEffect {
    /// No stage effect
    NoEffect,
    /// Stage is set from process specification
    Stage,
}

/// How state is affected
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
pub enum StateEffect {
    /// No state effect
    NoEffect,
    /// State is updated
    Update,
    /// State is updated on "to" resource
    UpdateTo,
}

impl Action {
    /// Get the default action definition for an action type
    pub fn from_type(action_type: ActionType) -> Self {
        match action_type {
            ActionType::Produce => Action {
                action_type,
                label: "Produce".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Output,
                pairs_with: None,
                create_resource: CreateResource::Optional,
                accounting_effect: ActionEffect::Increment,
                onhand_effect: ActionEffect::Increment,
                location_effect: LocationEffect::New,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::New,
                stage_effect: StageEffect::Stage,
                state_effect: StateEffect::Update,
            },
            ActionType::Consume => Action {
                action_type,
                label: "Consume".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Input,
                pairs_with: None,
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::Decrement,
                onhand_effect: ActionEffect::Decrement,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Use => Action {
                action_type,
                label: "Use".to_string(),
                event_quantity: EventQuantityType::Both,
                input_output: InputOutput::Input,
                pairs_with: None,
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Work => Action {
                action_type,
                label: "Work".to_string(),
                event_quantity: EventQuantityType::Both,
                input_output: InputOutput::Input,
                pairs_with: None,
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Cite => Action {
                action_type,
                label: "Cite".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Input,
                pairs_with: None,
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Transfer => Action {
                action_type,
                label: "Transfer".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::OptionalTo,
                accounting_effect: ActionEffect::DecrementIncrement,
                onhand_effect: ActionEffect::DecrementIncrement,
                location_effect: LocationEffect::UpdateTo,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::UpdateTo,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::TransferAllRights => Action {
                action_type,
                label: "Transfer All Rights".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::OptionalTo,
                accounting_effect: ActionEffect::DecrementIncrement,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::UpdateTo,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::TransferCustody => Action {
                action_type,
                label: "Transfer Custody".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::OptionalTo,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::DecrementIncrement,
                location_effect: LocationEffect::UpdateTo,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Move => Action {
                action_type,
                label: "Move".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::OptionalTo,
                accounting_effect: ActionEffect::DecrementIncrement,
                onhand_effect: ActionEffect::DecrementIncrement,
                location_effect: LocationEffect::UpdateTo,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Pickup => Action {
                action_type,
                label: "Pickup".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Input,
                pairs_with: Some(ActionType::Dropoff),
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Dropoff => Action {
                action_type,
                label: "Dropoff".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Output,
                pairs_with: Some(ActionType::Pickup),
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::Update,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Accept => Action {
                action_type,
                label: "Accept".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Input,
                pairs_with: Some(ActionType::Modify),
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Modify => Action {
                action_type,
                label: "Modify".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Output,
                pairs_with: Some(ActionType::Accept),
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::Stage,
                state_effect: StateEffect::Update,
            },
            ActionType::Combine => Action {
                action_type,
                label: "Combine".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Input,
                pairs_with: Some(ActionType::Separate),
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::Update,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Separate => Action {
                action_type,
                label: "Separate".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::Output,
                pairs_with: Some(ActionType::Combine),
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::Remove,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::DeliverService => Action {
                action_type,
                label: "Deliver Service".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::OutputInput,
                pairs_with: None,
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::NoEffect,
                onhand_effect: ActionEffect::NoEffect,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Copy => Action {
                action_type,
                label: "Copy".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::OptionalTo,
                accounting_effect: ActionEffect::IncrementTo,
                onhand_effect: ActionEffect::IncrementTo,
                location_effect: LocationEffect::New,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::UpdateTo,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Raise => Action {
                action_type,
                label: "Raise".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::Optional,
                accounting_effect: ActionEffect::Increment,
                onhand_effect: ActionEffect::Increment,
                location_effect: LocationEffect::New,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::New,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
            ActionType::Lower => Action {
                action_type,
                label: "Lower".to_string(),
                event_quantity: EventQuantityType::ResourceQuantity,
                input_output: InputOutput::NotApplicable,
                pairs_with: None,
                create_resource: CreateResource::No,
                accounting_effect: ActionEffect::Decrement,
                onhand_effect: ActionEffect::Decrement,
                location_effect: LocationEffect::NoEffect,
                contained_effect: ContainedEffect::NoEffect,
                accountable_effect: AccountableEffect::NoEffect,
                stage_effect: StageEffect::NoEffect,
                state_effect: StateEffect::NoEffect,
            },
        }
    }
}

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

    #[test]
    fn test_action_type_string_conversion() {
        assert_eq!(ActionType::Produce.as_str(), "produce");
        assert_eq!(ActionType::from_str("produce"), Some(ActionType::Produce));
        assert_eq!(ActionType::from_str("PRODUCE"), Some(ActionType::Produce));
    }

    #[test]
    fn test_action_pairs() {
        assert_eq!(ActionType::Pickup.pairs_with(), Some(ActionType::Dropoff));
        assert_eq!(ActionType::Accept.pairs_with(), Some(ActionType::Modify));
        assert_eq!(ActionType::Produce.pairs_with(), None);
    }

    #[test]
    fn test_action_classification() {
        assert!(ActionType::Transfer.is_transfer());
        assert!(ActionType::TransferAllRights.is_transfer());
        assert!(!ActionType::Produce.is_transfer());

        assert!(ActionType::Produce.is_production());
        assert!(!ActionType::Transfer.is_production());

        assert!(ActionType::Pickup.is_transportation());
        assert!(!ActionType::Produce.is_transportation());
    }
}