Public declaration syntax from forge-rs/crates/forge-contracts/src/flowers.rs
Original source SHA-256: e5196f463a87e82ce1b45d7a258dc27a41432995c8c11432ab7f1a4694d7c004
Function bodies and constant values are omitted. This is not the complete implementation.

Source line 60
pub const CONTRACT_VERSION: &str;

Source line 64
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FlowersExecutionHandle {
/// Unique execution identifier.

pub execution_id: String,
/// The workflow definition this execution instantiates.

pub workflow_id: String,
/// Current execution state.

pub state: FlowersExecutionState,
/// When the execution was created.

pub created_at: DateTime<Utc>,
/// When the execution last changed state.

pub updated_at: DateTime<Utc>
}

Source line 83
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum FlowersExecutionState {
    /// Execution is queued but not yet started.
    Queued,
    /// Execution is actively running.
    Running,
    /// Execution is paused (awaiting signal or timer).
    Suspended,
    /// Execution completed successfully.
    Completed,
    /// Execution failed with an error.
    Failed,
    /// Execution was cancelled.
    Cancelled,
    /// Execution is being compensated (saga rollback).
    Compensating,
}

Source line 105
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlowersJournalEntry {
/// Sequential event index within the execution.

pub index: u64,
/// The event type.

pub event_type: JournalEntryType,
/// The operation name (e.g., "agent.invoke", "tool.execute").

pub operation: String,
/// Input data for this operation (JSON-serialized).

pub input: serde_json::Value,
/// Output data from this operation (JSON-serialized), if completed.

pub output: Option<serde_json::Value>,
/// When this event was recorded.

pub timestamp: DateTime<Utc>,
/// Hash for integrity verification.

pub hash: String
}

Source line 130
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum JournalEntryType {
    /// A provider (LLM) call.
    ProviderCall,
    /// A tool execution.
    ToolExecution,
    /// A timer event.
    Timer,
    /// A signal received.
    Signal,
    /// A checkpoint created.
    Checkpoint,
    /// A compensation (rollback) action.
    Compensation,
    /// An arbitrary side effect.
    SideEffect,
}

Source line 149
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CheckpointData {
/// Unique checkpoint identifier.

pub checkpoint_id: String,
/// The execution this checkpoint belongs to.

pub execution_id: String,
/// The journal index at which this checkpoint was taken.

pub journal_index: u64,
/// Serialized execution state.

pub state: serde_json::Value,
/// When the checkpoint was created.

pub created_at: DateTime<Utc>
}

Source line 168
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlowersSignal {
/// Signal name.

pub name: String,
/// Signal payload.

pub payload: serde_json::Value
}

Source line 178
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FlowersSubmitRequest {
/// The agent to run (referenced by handle from S-01).

pub agent_id: String,
/// The input to pass to the agent.

pub input: String,
/// Optional workflow ID override (for resume scenarios).

pub workflow_id: Option<String>,
/// Optional checkpoint to resume from.

pub resume_from_checkpoint: Option<String>,
/// Maximum execution time in seconds.

pub timeout_seconds: Option<u64>,
/// Organization context.

pub org_id: Option<String>,
/// Department context.

pub department_id: Option<String>
}

Source line 224
#[async_trait]
pub trait FlowersBridgeContract: Send + Sync {
    /// Submits an agent for durable execution.
    ///
    /// The agent's LLM and tool calls will be journaled for crash
    /// recovery. On process restart, the execution resumes from the
    /// last committed journal entry.
    ///
    /// # Arguments
    ///
    /// * `request` - The submission parameters.
    ///
    /// # Returns
    ///
    /// A handle to the created execution.
    ///
    /// # Errors
    ///
    /// - `ContractError::FlowersError` if submission fails.
    /// - `ContractError::AgentNotFound` if the agent_id is invalid.
    async fn submit_agent(
        &self,
        request: FlowersSubmitRequest,
    ) -> ContractResult<FlowersExecutionHandle>;

    /// Sends a signal to a running or suspended execution.
    ///
    /// # Arguments
    ///
    /// * `execution_id` - The target execution.
    /// * `signal` - The signal to deliver.
    ///
    /// # Errors
    ///
    /// - `ContractError::FlowersError` if the execution does not exist
    ///   or cannot receive signals.
    async fn send_signal(&self, execution_id: &str, signal: FlowersSignal) -> ContractResult<()>;

    /// Cancels a running or suspended execution.
    ///
    /// Cancellation triggers compensation if a `CompensationStack` is
    /// registered for the execution.
    ///
    /// # Arguments
    ///
    /// * `execution_id` - The execution to cancel.
    /// * `reason` - Optional cancellation reason.
    async fn cancel_execution(
        &self,
        execution_id: &str,
        reason: Option<&str>,
    ) -> ContractResult<()>;

    /// Returns the journal entries for an execution.
    ///
    /// # Arguments
    ///
    /// * `execution_id` - The execution to query.
    /// * `from_index` - Start reading from this index.
    /// * `limit` - Maximum entries to return.
    ///
    /// # Returns
    ///
    /// Journal entries in sequential order.
    async fn get_journal(
        &self,
        execution_id: &str,
        from_index: u64,
        limit: u32,
    ) -> ContractResult<Vec<FlowersJournalEntry>>;

    /// Creates a checkpoint of the current execution state.
    ///
    /// # Arguments
    ///
    /// * `execution_id` - The execution to checkpoint.
    ///
    /// # Returns
    ///
    /// The checkpoint data.
    async fn create_checkpoint(&self, execution_id: &str) -> ContractResult<CheckpointData>;

    /// Returns the current status of an execution.
    ///
    /// # Arguments
    ///
    /// * `execution_id` - The execution to query.
    async fn get_execution_status(
        &self,
        execution_id: &str,
    ) -> ContractResult<FlowersExecutionHandle>;

    /// Lists all executions for an organization.
    ///
    /// # Arguments
    ///
    /// * `org_id` - The organization to query.
    /// * `state_filter` - Optional state filter.
    /// * `limit` - Maximum results.
    async fn list_executions(
        &self,
        org_id: &str,
        state_filter: Option<FlowersExecutionState>,
        limit: u32,
    ) -> ContractResult<Vec<FlowersExecutionHandle>>;
}