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

Source line 69
#[async_trait::async_trait]
pub trait CoordinatorContract: Send + Sync {
    /// Decomposes a high-level task into smaller sub-tasks.
    ///
    /// The coordinator analyzes the input task and produces a list of
    /// sub-tasks that can be individually assigned to workers. The sub-tasks
    /// should collectively cover the scope of the original task.
    ///
    /// # Arguments
    ///
    /// * `task` - The task to decompose.
    ///
    /// # Returns
    ///
    /// A `Vec` of sub-tasks derived from the original task.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::DelegationFailed`] if the task cannot be
    /// decomposed (e.g., it is already atomic or invalid).
    // ANVIL Spec section 11.1 -- Coordinator: decompose_task
    async fn decompose_task(&self, task: &DelegatedTask)
        -> Result<Vec<DelegatedTask>, CollabError>;

    /// Assigns a task to a specific worker agent.
    ///
    /// The coordinator sends the task to the identified worker and receives
    /// an acknowledgment indicating acceptance or rejection.
    ///
    /// # Arguments
    ///
    /// * `task` - The task to assign.
    /// * `worker_did` - The OAS DID of the target worker.
    ///
    /// # Returns
    ///
    /// A [`TaskAcknowledgment`] from the worker.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::CapabilityMismatch`] if the worker cannot
    /// handle the task type, or [`CollabError::DelegationFailed`] if the
    /// assignment fails for other reasons.
    // ANVIL Spec section 11.1 -- Coordinator: assign_task
    async fn assign_task(
        &self,
        task: &DelegatedTask,
        worker_did: &str,
    ) -> Result<TaskAcknowledgment, CollabError>;

    /// Aggregates results from multiple worker tasks into a single result.
    ///
    /// After all sub-tasks have completed, the coordinator merges their
    /// results into a unified response for the original task.
    ///
    /// # Arguments
    ///
    /// * `results` - The results from all completed sub-tasks.
    ///
    /// # Returns
    ///
    /// A single aggregated [`TaskResult`].
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::DelegationFailed`] if the results cannot be
    /// meaningfully aggregated (e.g., no results, conflicting outputs).
    // ANVIL Spec section 11.1 -- Coordinator: aggregate_results
    async fn aggregate_results(&self, results: &[TaskResult]) -> Result<TaskResult, CollabError>;

    /// Handles a failure reported by a worker.
    ///
    /// When a worker fails to complete a task, the coordinator decides how
    /// to recover: reassign the task, mark it as failed, or abort the
    /// session.
    ///
    /// # Arguments
    ///
    /// * `task_id` - The ID of the failed task.
    /// * `worker_did` - The DID of the worker that failed.
    /// * `error` - A description of the failure.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::DelegationFailed`] if recovery is not possible.
    // ANVIL Spec section 11.1 -- Coordinator: handle_worker_failure
    async fn handle_worker_failure(
        &self,
        task_id: &str,
        worker_did: &str,
        error: &str,
    ) -> Result<(), CollabError>;
}

Source line 204
#[async_trait::async_trait]
pub trait WorkerContract: Send + Sync {
    /// Called when a task is delegated to this worker.
    ///
    /// The worker inspects the task and decides whether to accept or reject
    /// it based on its capabilities and current load.
    ///
    /// # Arguments
    ///
    /// * `task` - The delegated task to evaluate.
    ///
    /// # Returns
    ///
    /// A [`TaskAcknowledgment`] indicating acceptance or rejection.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError`] if the acknowledgment cannot be produced.
    // ANVIL Spec section 11.1 -- Worker: on_task_delegated
    async fn on_task_delegated(
        &self,
        task: &DelegatedTask,
    ) -> Result<TaskAcknowledgment, CollabError>;

    /// Reports progress on an in-flight task.
    ///
    /// Workers should report progress periodically so the coordinator can
    /// monitor execution and detect stalls.
    ///
    /// # Arguments
    ///
    /// * `progress` - The progress report.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::TaskNotFound`] if the task ID in the progress
    /// report does not match an active task.
    // ANVIL Spec section 11.1 -- Worker: report_progress
    async fn report_progress(&self, progress: &TaskProgress) -> Result<(), CollabError>;

    /// Submits the result of a completed task.
    ///
    /// Called when the worker has finished executing the task. The result
    /// includes the output data, status, and optional confidence score.
    ///
    /// # Arguments
    ///
    /// * `result` - The task result to submit.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::TaskNotFound`] if the task ID in the result
    /// does not match an active task.
    // ANVIL Spec section 11.1 -- Worker: submit_result
    async fn submit_result(&self, result: &TaskResult) -> Result<(), CollabError>;

    /// Called when a task is cancelled by the coordinator.
    ///
    /// The worker should clean up any in-progress work for the specified
    /// task and release resources.
    ///
    /// # Arguments
    ///
    /// * `task_id` - The ID of the cancelled task.
    /// * `reason` - A human-readable cancellation reason.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::TaskNotFound`] if the task is not known.
    // ANVIL Spec section 11.1 -- Worker: on_task_cancelled
    async fn on_task_cancelled(&self, task_id: &str, reason: &str) -> Result<(), CollabError>;
}

Source line 308
#[async_trait::async_trait]
pub trait PeerContract: Send + Sync {
    /// Submits a proposal for peer consensus.
    ///
    /// # Arguments
    ///
    /// * `proposal` - The proposal data to submit for voting.
    ///
    /// # Returns
    ///
    /// A unique proposal ID string.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::DelegationFailed`] if the proposal cannot be
    /// submitted (e.g., session is not in an active state).
    // ANVIL Spec section 11.1 -- Peer: propose
    async fn propose(&self, proposal: &serde_json::Value) -> Result<String, CollabError>;

    /// Votes on an existing proposal.
    ///
    /// # Arguments
    ///
    /// * `proposal_id` - The ID of the proposal to vote on.
    /// * `approve` - `true` to approve, `false` to reject.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError::DelegationFailed`] if the proposal is not
    /// found or voting has closed.
    // ANVIL Spec section 11.1 -- Peer: vote
    async fn vote(&self, proposal_id: &str, approve: bool) -> Result<(), CollabError>;

    /// Called when consensus is reached on a proposal.
    ///
    /// # Arguments
    ///
    /// * `proposal_id` - The ID of the proposal that reached consensus.
    /// * `result` - The consensus result data.
    ///
    /// # Errors
    ///
    /// Returns [`CollabError`] if the agent cannot act on the consensus.
    // ANVIL Spec section 11.1 -- Peer: on_consensus
    async fn on_consensus(
        &self,
        proposal_id: &str,
        result: &serde_json::Value,
    ) -> Result<(), CollabError>;
}