{ "name": "forge-contracts", "language": "rust", "version": "0.2.0", "description": "Formal interface contracts between Forge (agent substrate) and Aut0 (organization platform)", "manifest": "forge-rs/crates/forge-contracts/Cargo.toml", "manifestSha256": "868abb63d997659c6e741835e2cca5a2b691582da86d3e47f0e0d7f15af0dad0", "status": "source-reference", "registryPublicationVerified": false, "route": "/libraries/rust/forge-contracts", "features": {}, "files": [ { "path": "forge-rs/crates/forge-contracts/src/auth.rs", "sha256": "98c9b6c97f10338f266df9de07417771d9ba69e3bcd6c52e87e56a4945e34106", "artifactSha256": "6fc991e73d0df3031a626b57e43502491f73e951ac6a1fec23218bc91b511375", "url": "/reference/source/forge-rs/crates/forge-contracts/src/auth.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 55, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-03." }, { "name": "::AuthDecision", "line": 71, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub enum AuthDecision {\n /// Authorization was granted.\n Allowed {\n /// The specific scope that was matched.\n scope: String,\n /// When this authorization expires, if applicable.\n expires_at: Option>,\n },\n /// Authorization was denied.\n Denied {\n /// The scope that was requested.\n requested_scope: String,\n /// The reason for denial.\n reason: String,\n },\n}", "documentation": "The result of an authorization check.\n\n# Examples\n\n```\nuse forge_contracts::auth::AuthDecision;\n\nlet decision = AuthDecision::Allowed {\n scope: \"tool:web_search\".to_string(),\n expires_at: None,\n};\nassert!(decision.is_allowed());\n```" }, { "name": "::AuthDecision::is_allowed", "line": 90, "signature": "pub fn is_allowed(&self) -> bool;", "documentation": "Returns `true` if authorization was granted." }, { "name": "::AuthDecision::is_denied", "line": 95, "signature": "pub fn is_denied(&self) -> bool;", "documentation": "Returns `true` if authorization was denied." }, { "name": "::CapabilityNarrowingRequest", "line": 123, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct CapabilityNarrowingRequest {\n/// The parent agent's DID (must have a valid ACT).\n\npub parent_did: String,\n/// The child agent's DID (will receive the narrowed ACT).\n\npub child_did: String,\n/// The scopes to grant to the child. Must be a subset of parent's scopes.\n\npub requested_scopes: Vec,\n/// Optional time-to-live in seconds for the child's token.\n\n/// If `None`, inherits the parent's expiration.\n\npub ttl_seconds: Option,\n/// Maximum delegation chain depth. If the parent is already at\n\n/// this depth, delegation fails.\n\npub max_delegation_depth: u32\n}", "documentation": "Request to narrow capabilities for a child agent.\n\nThe requested scopes must be a subset of the parent's scopes.\nIf any requested scope exceeds the parent's grant, the entire\nnarrowing operation fails.\n\n# Examples\n\n```\nuse forge_contracts::auth::CapabilityNarrowingRequest;\n\nlet req = CapabilityNarrowingRequest {\n parent_did: \"did:oas:l1fe:agent:eng-director\".to_string(),\n child_did: \"did:oas:l1fe:agent:code-reviewer\".to_string(),\n requested_scopes: vec![\n \"tool:code_search\".to_string(),\n \"tool:file_read\".to_string(),\n ],\n ttl_seconds: Some(3600),\n max_delegation_depth: 8,\n};\n```" }, { "name": "::DelegationChainEntry", "line": 146, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DelegationChainEntry {\n/// The delegator's DID.\n\npub delegator_did: String,\n/// The delegatee's DID.\n\npub delegatee_did: String,\n/// The scopes that were delegated.\n\npub scopes: Vec,\n/// When the delegation was created.\n\npub created_at: DateTime,\n/// When the delegation expires.\n\npub expires_at: Option>,\n/// Depth in the delegation chain (0 = root grant).\n\npub depth: u32\n}", "documentation": "A single entry in a delegation chain, showing who delegated what to whom.\n\nUsed for audit trail inspection and governance reviews." }, { "name": "::CapabilityTokenHandle", "line": 171, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct CapabilityTokenHandle {\n/// Unique identifier for this token.\n\npub token_id: String,\n/// The agent DID this token belongs to.\n\npub agent_did: String,\n/// The scopes granted by this token.\n\npub scopes: Vec,\n/// When this token expires, if applicable.\n\npub expires_at: Option>,\n/// Depth in the delegation chain.\n\npub delegation_depth: u32\n}", "documentation": "An opaque handle to a capability token.\n\nAut0 holds these and passes them to contract methods. The actual\ntoken contents (signatures, claims) are managed by Forge." }, { "name": "::AuthContract", "line": 210, "signature": "#[async_trait]\npub trait AuthContract: Send + Sync {\n /// Checks whether an agent is authorized for a specific scope.\n ///\n /// # Arguments\n ///\n /// * `agent_did` - The agent requesting authorization.\n /// * `scope` - The scope to check (e.g., \"tool:web_search\",\n /// \"memory:write:department:engineering\").\n ///\n /// # Returns\n ///\n /// An `AuthDecision` indicating whether access is granted or denied.\n ///\n /// # Errors\n ///\n /// - `ContractError::DidResolutionFailed` if the agent's DID cannot\n /// be resolved to find its ACT.\n async fn check_authorization(\n &self,\n agent_did: &str,\n scope: &str,\n ) -> ContractResult;\n\n /// Creates a narrowed capability token for a child agent.\n ///\n /// # Arguments\n ///\n /// * `request` - The narrowing parameters.\n ///\n /// # Returns\n ///\n /// A handle to the newly created child token.\n ///\n /// # Errors\n ///\n /// - `ContractError::CapabilityEscalation` if any requested scope\n /// exceeds the parent's grants.\n /// - `ContractError::TokenExpired` if the parent's token has expired.\n async fn delegate_capabilities(\n &self,\n request: CapabilityNarrowingRequest,\n ) -> ContractResult;\n\n /// Revokes a capability token, immediately invalidating it.\n ///\n /// Revocation cascades: revoking a parent token also revokes all\n /// tokens derived from it.\n ///\n /// # Arguments\n ///\n /// * `token_id` - The token to revoke.\n ///\n /// # Errors\n ///\n /// - `ContractError::AuthorizationDenied` if the caller does not\n /// have authority to revoke this token.\n async fn revoke_token(&self, token_id: &str) -> ContractResult<()>;\n\n /// Returns the full delegation chain for an agent's current token.\n ///\n /// # Arguments\n ///\n /// * `agent_did` - The agent whose delegation chain to retrieve.\n ///\n /// # Returns\n ///\n /// The chain of delegations from root to the agent, ordered by depth.\n ///\n /// # Errors\n ///\n /// - `ContractError::DidResolutionFailed` if the agent DID cannot\n /// be resolved.\n async fn get_delegation_chain(\n &self,\n agent_did: &str,\n ) -> ContractResult>;\n\n /// Lists all scopes currently granted to an agent.\n ///\n /// # Arguments\n ///\n /// * `agent_did` - The agent to query.\n ///\n /// # Returns\n ///\n /// The list of scope strings currently active for this agent.\n async fn list_scopes(&self, agent_did: &str) -> ContractResult>;\n}", "documentation": "The primary contract for authorization and delegation.\n\nForge implements this trait in `forge-auth`. Aut0 consumes it to\nenforce organizational access policies.\n\n# Implementor Notes (Forge)\n\n- `check_authorization` MUST be constant-time with respect to secret data.\n- `delegate_capabilities` MUST verify that requested scopes are a strict\n subset of the parent's scopes before creating the child token.\n- Expired tokens MUST always return `Denied`.\n- All decisions MUST be deterministic given the same inputs.\n\n# Consumer Notes (Aut0)\n\n- Call `check_authorization` before every privileged operation.\n- Use `delegate_capabilities` when creating sub-agents or assigning\n tasks to team members.\n- Periodically call `revoke_token` for agents that leave a department\n or have their role changed.\n- Use `get_delegation_chain` for governance audits." } ] }, { "path": "forge-rs/crates/forge-contracts/src/brew.rs", "sha256": "9ffac728e785247fa8415b577a2d9809b646d2d2d00d78d1e8fcd9157b521680", "artifactSha256": "db84410915d747839c79b0b30f53d4f07362c9fe698434c574434855e6923c6c", "url": "/reference/source/forge-rs/crates/forge-contracts/src/brew.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 41, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-05." }, { "name": "::PlanHandle", "line": 48, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct PlanHandle {\n/// Unique plan identifier.\n\npub plan_id: String,\n/// The Brew graph identifier this plan was frozen from.\n\npub brew_id: String,\n/// Number of nodes in the plan.\n\npub node_count: u32,\n/// Number of edges in the plan.\n\npub edge_count: u32,\n/// Whether this plan is currently executing.\n\npub executing: bool\n}", "documentation": "An opaque handle to a frozen, resolved Brew plan.\n\nThe plan has been validated and all symbols resolved. It is ready\nfor execution." }, { "name": "::BrewNodeSpec", "line": 69, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct BrewNodeSpec {\n/// Unique node identifier within the brew.\n\npub node_id: String,\n/// The type of node.\n\npub node_type: BrewNodeType,\n/// Input mapping: key is parameter name, value is source expression.\n\npub inputs: BTreeMap,\n/// Configuration specific to the node type.\n\npub config: serde_json::Value\n}", "documentation": "A node specification for building a Brew graph.\n\nAut0 uses these to construct the graph before freezing." }, { "name": "::BrewNodeType", "line": 85, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum BrewNodeType {\n /// An agent execution node (runs a tool loop).\n Agent,\n /// A tool invocation node (calls a single tool).\n Tool,\n /// A provider call node (single LLM inference).\n Inference,\n /// A conditional branch node.\n Condition,\n /// A data transformation node.\n Transform,\n /// A sub-brew reference node.\n SubBrew,\n}", "documentation": "The type of a node in a Brew graph." }, { "name": "::BrewEdgeSpec", "line": 102, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct BrewEdgeSpec {\n/// Source node ID.\n\npub from_node: String,\n/// Target node ID.\n\npub to_node: String,\n/// The type of edge.\n\npub edge_type: BrewEdgeType,\n/// Optional condition expression for conditional edges.\n\npub condition: Option\n}", "documentation": "An edge specification connecting two nodes in a Brew graph." }, { "name": "::BrewEdgeType", "line": 118, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum BrewEdgeType {\n /// Data flows from source output to target input.\n Data,\n /// Control flow: target executes after source completes.\n Control,\n /// Error flow: target executes if source fails.\n Error,\n}", "documentation": "The type of an edge in a Brew graph." }, { "name": "::PlanExecutionResult", "line": 129, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct PlanExecutionResult {\n/// The plan that was executed.\n\npub plan_id: String,\n/// Whether the plan completed successfully.\n\npub success: bool,\n/// Results from each node, keyed by node ID.\n\npub node_results: BTreeMap,\n/// Total execution time in milliseconds.\n\npub duration_ms: u64,\n/// Total tokens consumed across all nodes.\n\npub total_tokens: u64\n}", "documentation": "The result of executing a complete plan." }, { "name": "::NodeResult", "line": 148, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct NodeResult {\n/// The node identifier.\n\npub node_id: String,\n/// Whether this node succeeded.\n\npub success: bool,\n/// The node's output as JSON.\n\npub output: Option,\n/// Error message if the node failed.\n\npub error: Option,\n/// Execution time for this node in milliseconds.\n\npub duration_ms: u64\n}", "documentation": "The result of executing a single node." }, { "name": "::BrewContract", "line": 185, "signature": "#[async_trait]\npub trait BrewContract: Send + Sync {\n /// Creates a new empty Brew graph.\n ///\n /// # Arguments\n ///\n /// * `brew_id` - Unique identifier for this brew.\n /// * `description` - Human-readable description of the plan's purpose.\n ///\n /// # Returns\n ///\n /// A handle to the unfrozen plan.\n async fn create_plan(&self, brew_id: &str, description: &str) -> ContractResult;\n\n /// Adds a node to an unfrozen plan.\n ///\n /// # Arguments\n ///\n /// * `plan_id` - The plan to modify.\n /// * `node` - The node specification.\n ///\n /// # Errors\n ///\n /// - `ContractError::PlanResolutionFailed` if the plan is already frozen.\n async fn add_node(&self, plan_id: &str, node: BrewNodeSpec) -> ContractResult<()>;\n\n /// Adds an edge to an unfrozen plan.\n ///\n /// # Arguments\n ///\n /// * `plan_id` - The plan to modify.\n /// * `edge` - The edge specification.\n ///\n /// # Errors\n ///\n /// - `ContractError::PlanResolutionFailed` if the plan is already frozen\n /// or if referenced nodes do not exist.\n async fn add_edge(&self, plan_id: &str, edge: BrewEdgeSpec) -> ContractResult<()>;\n\n /// Freezes a plan, validating and resolving all symbols.\n ///\n /// After freezing, no modifications are allowed. The plan is ready\n /// for execution.\n ///\n /// # Arguments\n ///\n /// * `plan_id` - The plan to freeze.\n ///\n /// # Returns\n ///\n /// The updated plan handle with `executing: false`.\n ///\n /// # Errors\n ///\n /// - `ContractError::PlanResolutionFailed` if validation fails.\n async fn freeze_plan(&self, plan_id: &str) -> ContractResult;\n\n /// Executes a frozen plan.\n ///\n /// # Arguments\n ///\n /// * `plan_id` - The frozen plan to execute.\n /// * `inputs` - Input values keyed by parameter name.\n ///\n /// # Returns\n ///\n /// The execution result with outputs from all nodes.\n ///\n /// # Errors\n ///\n /// - `ContractError::PlanExecutionFailed` if execution fails.\n async fn execute_plan(\n &self,\n plan_id: &str,\n inputs: BTreeMap,\n ) -> ContractResult;\n\n /// Queries the current status of a plan.\n ///\n /// # Arguments\n ///\n /// * `plan_id` - The plan to query.\n async fn get_plan_status(&self, plan_id: &str) -> ContractResult;\n}", "documentation": "The primary contract for Brew plan operations.\n\nForge implements this trait. Aut0 consumes it to build, freeze,\nexecute, and inspect multi-agent execution plans.\n\n# Implementor Notes (Forge)\n\n- `freeze_plan` MUST validate the graph (no cycles in control edges,\n all referenced nodes exist, all provider refs resolvable).\n- `execute_plan` SHOULD use Flowers for crash-recoverable execution\n of frozen plans.\n- Node results MUST be collected even if the plan partially fails.\n\n# Consumer Notes (Aut0)\n\n- Build the Brew graph incrementally using `create_plan` + `add_node` +\n `add_edge`, then call `freeze_plan` to validate and lock.\n- Once frozen, a plan can be executed multiple times with different inputs.\n- Use `get_plan_status` to poll for completion on async executions." } ] }, { "path": "forge-rs/crates/forge-contracts/src/comm.rs", "sha256": "b2ca753341613777994e11f61a31dcf8444039ef1277e999d03da8ef7dd4219b", "artifactSha256": "b885b6503c710878669beae78d43e805304c122a9c55201150631e2c94540992", "url": "/reference/source/forge-rs/crates/forge-contracts/src/comm.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 45, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-06." }, { "name": "::ChannelConfig", "line": 71, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ChannelConfig {\n/// Human-readable channel name.\n\npub channel_name: String,\n/// The type of channel (maps to different session semantics).\n\npub channel_type: ChannelType,\n/// The organization this channel belongs to.\n\npub org_id: String,\n/// Optional department scope.\n\npub department_id: Option,\n/// DIDs of agents allowed in this channel.\n\npub participants: Vec,\n/// Maximum message payload size in bytes.\n\npub max_message_size_bytes: u32,\n/// How long to retain message history, in hours. `None` = forever.\n\npub history_retention_hours: Option\n}", "documentation": "Configuration for creating a communication channel.\n\nAut0 maps its organizational channel concepts (department channels,\nDMs, executive chat) to Forge's session-based communication model.\n\n# Examples\n\n```\nuse forge_contracts::comm::{ChannelConfig, ChannelType};\n\nlet config = ChannelConfig {\n channel_name: \"eng-general\".to_string(),\n channel_type: ChannelType::Department,\n org_id: \"l1fe-ai-inc\".to_string(),\n department_id: Some(\"engineering\".to_string()),\n participants: vec![\n \"did:oas:l1fe:agent:eng-director\".to_string(),\n \"did:oas:l1fe:agent:code-reviewer\".to_string(),\n ],\n max_message_size_bytes: 65536,\n history_retention_hours: Some(720),\n};\n```" }, { "name": "::ChannelType", "line": 96, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum ChannelType {\n /// Organization-wide broadcast channel.\n OrgWide,\n /// Department-scoped channel.\n Department,\n /// Direct message between two agents.\n DirectMessage,\n /// Executive channel (Company Director + root-holder).\n Executive,\n /// Root-holder secure channel.\n RootHolder,\n /// Custom channel type.\n Custom(String),\n}", "documentation": "The type of organizational channel." }, { "name": "::ChannelHandle", "line": 113, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct ChannelHandle {\n/// Unique channel identifier.\n\npub channel_id: String,\n/// The underlying Forge session identifier.\n\npub session_id: String,\n/// The channel name.\n\npub name: String,\n/// The channel type.\n\npub channel_type: ChannelType,\n/// Number of participants.\n\npub participant_count: u32\n}", "documentation": "An opaque handle to an active channel." }, { "name": "::SessionConfig", "line": 134, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct SessionConfig {\n/// Human-readable session name.\n\npub session_name: String,\n/// The coordinator agent's DID.\n\npub coordinator_did: String,\n/// Worker agent DIDs.\n\npub worker_dids: Vec,\n/// Optional timeout for the session in seconds.\n\npub timeout_seconds: Option,\n/// Whether to enable shared context for this session.\n\npub shared_context_enabled: bool\n}", "documentation": "Configuration for a collaboration session.\n\nSessions wrap Forge's `CollaborationSession` with org-level semantics." }, { "name": "::ChannelMessage", "line": 153, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ChannelMessage {\n/// The sender's DID.\n\npub sender_did: String,\n/// The message content type.\n\npub content_type: MessageContentType,\n/// The message payload as JSON.\n\npub payload: serde_json::Value,\n/// Optional correlation ID for threading.\n\npub correlation_id: Option,\n/// Optional reply-to message ID.\n\npub reply_to: Option\n}", "documentation": "A message to send through a channel." }, { "name": "::MessageContentType", "line": 172, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum MessageContentType {\n /// Plain text message.\n Text,\n /// Structured data message.\n Structured,\n /// Task delegation message.\n TaskDelegation,\n /// Task result message.\n TaskResult,\n /// Interrupt/signal message.\n Interrupt,\n /// Status update message.\n StatusUpdate,\n}", "documentation": "Content type for channel messages." }, { "name": "::ReceivedMessage", "line": 189, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ReceivedMessage {\n/// Unique message identifier.\n\npub message_id: String,\n/// The sender's DID.\n\npub sender_did: String,\n/// The message content type.\n\npub content_type: MessageContentType,\n/// The message payload.\n\npub payload: serde_json::Value,\n/// When the message was sent.\n\npub sent_at: DateTime,\n/// Ed25519 signature from the sender (base64-encoded).\n\npub signature: Option,\n/// Correlation ID for threading.\n\npub correlation_id: Option\n}", "documentation": "A received message from a channel." }, { "name": "::CommContract", "line": 231, "signature": "#[async_trait]\npub trait CommContract: Send + Sync {\n /// Creates a new communication channel.\n ///\n /// # Arguments\n ///\n /// * `config` - The channel configuration.\n ///\n /// # Returns\n ///\n /// A handle to the created channel.\n ///\n /// # Errors\n ///\n /// - `ContractError::ChannelError` if creation fails.\n /// - `ContractError::DidResolutionFailed` if any participant DID\n /// cannot be resolved.\n async fn create_channel(&self, config: ChannelConfig) -> ContractResult;\n\n /// Sends a message to a channel.\n ///\n /// The message is automatically wrapped in an `AgentMessage` envelope,\n /// signed by the sender, and delivered to all channel participants.\n ///\n /// # Arguments\n ///\n /// * `channel_id` - The target channel.\n /// * `message` - The message to send.\n ///\n /// # Returns\n ///\n /// The message ID assigned by the transport.\n ///\n /// # Errors\n ///\n /// - `ContractError::ChannelError` if the channel does not exist.\n /// - `ContractError::AuthorizationDenied` if the sender is not a\n /// participant.\n async fn send_message(\n &self,\n channel_id: &str,\n message: ChannelMessage,\n ) -> ContractResult;\n\n /// Receives the next message from a channel.\n ///\n /// This is a pull-based interface. For push-based delivery, use\n /// `subscribe`.\n ///\n /// # Arguments\n ///\n /// * `channel_id` - The channel to receive from.\n /// * `agent_did` - The receiving agent's DID.\n ///\n /// # Returns\n ///\n /// The next unread message, or `None` if no messages are pending.\n async fn receive_message(\n &self,\n channel_id: &str,\n agent_did: &str,\n ) -> ContractResult>;\n\n /// Closes a channel, cleaning up resources.\n ///\n /// # Arguments\n ///\n /// * `channel_id` - The channel to close.\n async fn close_channel(&self, channel_id: &str) -> ContractResult<()>;\n\n /// Lists all channels for an organization.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization to query.\n /// * `department_id` - Optional department filter.\n async fn list_channels(\n &self,\n org_id: &str,\n department_id: Option<&str>,\n ) -> ContractResult>;\n}", "documentation": "The primary contract for communication and collaboration.\n\nForge implements this trait in `forge-comm` and `forge-collab`. Aut0\nconsumes it to build organizational channels and collaboration sessions.\n\n# Implementor Notes (Forge)\n\n- `create_channel` MUST create an underlying Forge session with the\n appropriate transport (channel, network, etc.).\n- Messages MUST be signed by the sender's Ed25519 key if the sender\n has an identity.\n- `subscribe` MUST deliver messages in order within a channel.\n\n# Consumer Notes (Aut0)\n\n- Map organizational channel concepts to `ChannelConfig` entries.\n- Use `subscribe` for real-time message delivery to channel UIs.\n- Store `ChannelHandle` for channel lifetime management." } ] }, { "path": "forge-rs/crates/forge-contracts/src/error.rs", "sha256": "c1307a34bfd4e038c912a6bc4d7675b50595b2545f46ef4a243ba80c4f49b60e", "artifactSha256": "27cfd7aa75a589d9a84e40f585d47e4859da7490bc425a0d3a082e0fd46c892f", "url": "/reference/source/forge-rs/crates/forge-contracts/src/error.rs.txt", "declarations": [ { "name": "::ContractError", "line": 25, "signature": "#[derive(Debug, Error)]\npub enum ContractError {\n // -----------------------------------------------------------------------\n // S-01: Agent Runtime\n // -----------------------------------------------------------------------\n /// The requested agent does not exist or has been terminated.\n #[error(\"agent '{agent_id}' not found in runtime\")]\n AgentNotFound {\n /// The agent identifier that was not found.\n agent_id: String,\n },\n\n /// Agent creation failed due to invalid configuration.\n #[error(\"agent creation failed: {reason}\")]\n AgentCreationFailed {\n /// Human-readable explanation of why creation failed.\n reason: String,\n },\n\n /// An invalid lifecycle transition was attempted.\n #[error(\"invalid lifecycle transition from {from} to {to} for agent '{agent_id}'\")]\n InvalidLifecycleTransition {\n /// The agent that owns the lifecycle.\n agent_id: String,\n /// The current state name.\n from: String,\n /// The requested target state name.\n to: String,\n },\n\n // -----------------------------------------------------------------------\n // S-02: Identity & Lineage\n // -----------------------------------------------------------------------\n /// Identity derivation failed.\n #[error(\"identity derivation failed for path '{path}' from parent '{parent_did}': {reason}\")]\n IdentityDerivationFailed {\n /// The parent DID from which derivation was attempted.\n parent_did: String,\n /// The derivation path that failed.\n path: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n /// Lineage verification failed at the specified depth.\n #[error(\"lineage verification failed at depth {depth} for '{did}': {reason}\")]\n LineageVerificationFailed {\n /// The DID whose lineage failed verification.\n did: String,\n /// The depth at which verification failed.\n depth: u32,\n /// Explanation of the failure.\n reason: String,\n },\n\n /// DID resolution failed.\n #[error(\"DID resolution failed for '{did}': {reason}\")]\n DidResolutionFailed {\n /// The DID that could not be resolved.\n did: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-03: Auth & Delegation\n // -----------------------------------------------------------------------\n /// Capability escalation denied: child requested more than parent has.\n #[error(\"capability escalation denied: agent '{agent_did}' requested scope '{requested}' but parent ACT only grants {available:?}\")]\n CapabilityEscalation {\n /// The agent DID that attempted escalation.\n agent_did: String,\n /// The scope that was requested.\n requested: String,\n /// The scopes available to the parent.\n available: Vec,\n },\n\n /// A capability token has expired.\n #[error(\"capability token '{token_id}' for agent '{agent_did}' expired at {expired_at}\")]\n TokenExpired {\n /// The token identifier.\n token_id: String,\n /// The agent DID that owns the token.\n agent_did: String,\n /// ISO 8601 timestamp when the token expired.\n expired_at: String,\n },\n\n /// Authorization check failed.\n #[error(\"authorization denied for agent '{agent_did}' on scope '{scope}': {reason}\")]\n AuthorizationDenied {\n /// The agent DID that was denied.\n agent_did: String,\n /// The scope that was requested.\n scope: String,\n /// Explanation of why authorization was denied.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-04: Provider Routing\n // -----------------------------------------------------------------------\n /// No provider matched the routing policy.\n #[error(\"no provider matched routing policy for org '{org_id}': {reason}\")]\n NoProviderAvailable {\n /// The organization identifier.\n org_id: String,\n /// Explanation of why no provider matched.\n reason: String,\n },\n\n /// Provider session creation or management failed.\n #[error(\"provider session error for '{provider_ref}': {reason}\")]\n ProviderSessionError {\n /// The provider reference string.\n provider_ref: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-05: Brew Plans\n // -----------------------------------------------------------------------\n /// Plan resolution failed (unresolved symbols, cycles, etc.).\n #[error(\"brew plan '{plan_id}' resolution failed: {reason}\")]\n PlanResolutionFailed {\n /// The plan identifier.\n plan_id: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n /// Plan execution failed at a specific node.\n #[error(\"brew plan '{plan_id}' failed at node '{node_id}': {reason}\")]\n PlanExecutionFailed {\n /// The plan identifier.\n plan_id: String,\n /// The node that failed.\n node_id: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-06: Comm/Collab\n // -----------------------------------------------------------------------\n /// Channel creation or operation failed.\n #[error(\"channel '{channel_id}' error: {reason}\")]\n ChannelError {\n /// The channel identifier.\n channel_id: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-07: MCP\n // -----------------------------------------------------------------------\n /// MCP server connection or operation failed.\n #[error(\"MCP server '{server_name}' error: {reason}\")]\n McpError {\n /// The MCP server name.\n server_name: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-08: Telemetry & Health\n // -----------------------------------------------------------------------\n /// Telemetry collection or aggregation failed.\n #[error(\"telemetry error: {reason}\")]\n TelemetryError {\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-09: Flowers Bridge\n // -----------------------------------------------------------------------\n /// Durable execution checkpoint or resume failed.\n #[error(\"flowers execution '{execution_id}' error: {reason}\")]\n FlowersError {\n /// The Flowers execution identifier.\n execution_id: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // S-10: Memory\n // -----------------------------------------------------------------------\n /// Memory read or write operation failed.\n #[error(\"memory error in scope '{scope}': {reason}\")]\n MemoryError {\n /// The memory scope where the error occurred.\n scope: String,\n /// Explanation of the failure.\n reason: String,\n },\n\n /// Memory access denied by policy.\n #[error(\"memory access denied for agent '{agent_did}' in scope '{scope}': {reason}\")]\n MemoryAccessDenied {\n /// The agent DID that was denied.\n agent_did: String,\n /// The memory scope.\n scope: String,\n /// Explanation of the denial.\n reason: String,\n },\n\n // -----------------------------------------------------------------------\n // Cross-cutting\n // -----------------------------------------------------------------------\n /// Contract version mismatch between Forge and Aut0.\n #[error(\"contract version mismatch: Forge has {forge_version}, Aut0 expects {aut0_version}\")]\n VersionMismatch {\n /// The version Forge compiled against.\n forge_version: String,\n /// The version Aut0 compiled against.\n aut0_version: String,\n },\n\n /// A required configuration field was missing or invalid.\n #[error(\"configuration error: {reason}\")]\n ConfigurationError {\n /// Explanation of the configuration problem.\n reason: String,\n },\n\n /// An internal Forge error that Aut0 should not need to handle in detail.\n #[error(\"internal error: {reason}\")]\n Internal {\n /// Explanation for diagnostic purposes.\n reason: String,\n },\n}", "documentation": "The unified error type for all contract operations.\n\nEach variant includes enough context for Aut0 to take corrective action\nwithout inspecting Forge internals.\n\n# Examples\n\n```\nuse forge_contracts::error::ContractError;\n\nlet err = ContractError::AgentNotFound {\n agent_id: \"agent-42\".to_string(),\n};\nassert!(err.to_string().contains(\"agent-42\"));\n```" }, { "name": "::ContractResult", "line": 265, "signature": "pub type ContractResult = Result;", "documentation": "Convenience type alias for contract results." } ] }, { "path": "forge-rs/crates/forge-contracts/src/flowers.rs", "sha256": "e5196f463a87e82ce1b45d7a258dc27a41432995c8c11432ab7f1a4694d7c004", "artifactSha256": "c20b8ce302389748370f0e021098659d83fda175611488ac975a6270a1806f4e", "url": "/reference/source/forge-rs/crates/forge-contracts/src/flowers.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 60, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-09." }, { "name": "::FlowersExecutionHandle", "line": 64, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct FlowersExecutionHandle {\n/// Unique execution identifier.\n\npub execution_id: String,\n/// The workflow definition this execution instantiates.\n\npub workflow_id: String,\n/// Current execution state.\n\npub state: FlowersExecutionState,\n/// When the execution was created.\n\npub created_at: DateTime,\n/// When the execution last changed state.\n\npub updated_at: DateTime\n}", "documentation": "An opaque handle to a Flowers durable execution." }, { "name": "::FlowersExecutionState", "line": 83, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum FlowersExecutionState {\n /// Execution is queued but not yet started.\n Queued,\n /// Execution is actively running.\n Running,\n /// Execution is paused (awaiting signal or timer).\n Suspended,\n /// Execution completed successfully.\n Completed,\n /// Execution failed with an error.\n Failed,\n /// Execution was cancelled.\n Cancelled,\n /// Execution is being compensated (saga rollback).\n Compensating,\n}", "documentation": "State of a Flowers execution (maps to Flowers' 7-state model)." }, { "name": "::FlowersJournalEntry", "line": 105, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct FlowersJournalEntry {\n/// Sequential event index within the execution.\n\npub index: u64,\n/// The event type.\n\npub event_type: JournalEntryType,\n/// The operation name (e.g., \"agent.invoke\", \"tool.execute\").\n\npub operation: String,\n/// Input data for this operation (JSON-serialized).\n\npub input: serde_json::Value,\n/// Output data from this operation (JSON-serialized), if completed.\n\npub output: Option,\n/// When this event was recorded.\n\npub timestamp: DateTime,\n/// Hash for integrity verification.\n\npub hash: String\n}", "documentation": "A journal event from a Flowers execution.\n\nJournal events are the immutable record of all side effects during\ndurable execution. They enable crash recovery and deterministic replay." }, { "name": "::JournalEntryType", "line": 130, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum JournalEntryType {\n /// A provider (LLM) call.\n ProviderCall,\n /// A tool execution.\n ToolExecution,\n /// A timer event.\n Timer,\n /// A signal received.\n Signal,\n /// A checkpoint created.\n Checkpoint,\n /// A compensation (rollback) action.\n Compensation,\n /// An arbitrary side effect.\n SideEffect,\n}", "documentation": "The type of journal entry." }, { "name": "::CheckpointData", "line": 149, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct CheckpointData {\n/// Unique checkpoint identifier.\n\npub checkpoint_id: String,\n/// The execution this checkpoint belongs to.\n\npub execution_id: String,\n/// The journal index at which this checkpoint was taken.\n\npub journal_index: u64,\n/// Serialized execution state.\n\npub state: serde_json::Value,\n/// When the checkpoint was created.\n\npub created_at: DateTime\n}", "documentation": "Data for a checkpoint (snapshot of execution state)." }, { "name": "::FlowersSignal", "line": 168, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct FlowersSignal {\n/// Signal name.\n\npub name: String,\n/// Signal payload.\n\npub payload: serde_json::Value\n}", "documentation": "A signal to deliver to a Flowers execution." }, { "name": "::FlowersSubmitRequest", "line": 178, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct FlowersSubmitRequest {\n/// The agent to run (referenced by handle from S-01).\n\npub agent_id: String,\n/// The input to pass to the agent.\n\npub input: String,\n/// Optional workflow ID override (for resume scenarios).\n\npub workflow_id: Option,\n/// Optional checkpoint to resume from.\n\npub resume_from_checkpoint: Option,\n/// Maximum execution time in seconds.\n\npub timeout_seconds: Option,\n/// Organization context.\n\npub org_id: Option,\n/// Department context.\n\npub department_id: Option\n}", "documentation": "Request to submit an agent as a durable workflow." }, { "name": "::FlowersBridgeContract", "line": 224, "signature": "#[async_trait]\npub trait FlowersBridgeContract: Send + Sync {\n /// Submits an agent for durable execution.\n ///\n /// The agent's LLM and tool calls will be journaled for crash\n /// recovery. On process restart, the execution resumes from the\n /// last committed journal entry.\n ///\n /// # Arguments\n ///\n /// * `request` - The submission parameters.\n ///\n /// # Returns\n ///\n /// A handle to the created execution.\n ///\n /// # Errors\n ///\n /// - `ContractError::FlowersError` if submission fails.\n /// - `ContractError::AgentNotFound` if the agent_id is invalid.\n async fn submit_agent(\n &self,\n request: FlowersSubmitRequest,\n ) -> ContractResult;\n\n /// Sends a signal to a running or suspended execution.\n ///\n /// # Arguments\n ///\n /// * `execution_id` - The target execution.\n /// * `signal` - The signal to deliver.\n ///\n /// # Errors\n ///\n /// - `ContractError::FlowersError` if the execution does not exist\n /// or cannot receive signals.\n async fn send_signal(&self, execution_id: &str, signal: FlowersSignal) -> ContractResult<()>;\n\n /// Cancels a running or suspended execution.\n ///\n /// Cancellation triggers compensation if a `CompensationStack` is\n /// registered for the execution.\n ///\n /// # Arguments\n ///\n /// * `execution_id` - The execution to cancel.\n /// * `reason` - Optional cancellation reason.\n async fn cancel_execution(\n &self,\n execution_id: &str,\n reason: Option<&str>,\n ) -> ContractResult<()>;\n\n /// Returns the journal entries for an execution.\n ///\n /// # Arguments\n ///\n /// * `execution_id` - The execution to query.\n /// * `from_index` - Start reading from this index.\n /// * `limit` - Maximum entries to return.\n ///\n /// # Returns\n ///\n /// Journal entries in sequential order.\n async fn get_journal(\n &self,\n execution_id: &str,\n from_index: u64,\n limit: u32,\n ) -> ContractResult>;\n\n /// Creates a checkpoint of the current execution state.\n ///\n /// # Arguments\n ///\n /// * `execution_id` - The execution to checkpoint.\n ///\n /// # Returns\n ///\n /// The checkpoint data.\n async fn create_checkpoint(&self, execution_id: &str) -> ContractResult;\n\n /// Returns the current status of an execution.\n ///\n /// # Arguments\n ///\n /// * `execution_id` - The execution to query.\n async fn get_execution_status(\n &self,\n execution_id: &str,\n ) -> ContractResult;\n\n /// Lists all executions for an organization.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization to query.\n /// * `state_filter` - Optional state filter.\n /// * `limit` - Maximum results.\n async fn list_executions(\n &self,\n org_id: &str,\n state_filter: Option,\n limit: u32,\n ) -> ContractResult>;\n}", "documentation": "The primary contract for the Flowers durable execution bridge.\n\nForge implements this trait in `forge-flowers`. Aut0 consumes it to\nrun agents as crash-recoverable workflows.\n\n# Implementor Notes (Forge)\n\n- `submit_agent` MUST wrap the agent's provider calls and tool\n executions in journal entries via `JournaledProvider` and\n `JournaledToolExecutor`.\n- Journal events MUST be hash-chained for integrity verification.\n- Replay MUST be deterministic given the same journal.\n- Checkpoint data MUST be sufficient to resume execution.\n\n# Consumer Notes (Aut0)\n\n- Use `submit_agent` for any long-running or critical agent execution.\n- Use `send_signal` for external event delivery (human approval,\n timer expiration, cancellation).\n- Use `get_journal` for the Flowers Console execution inspector.\n- Use `create_checkpoint` + `submit_agent` with `resume_from_checkpoint`\n for manual recovery." } ] }, { "path": "forge-rs/crates/forge-contracts/src/identity.rs", "sha256": "58c5e34cd14b4451e3a60dead538762779e9dcee7117e3802069b64877fe620f", "artifactSha256": "c77d7c192e507feaf01f955bbcd58ad3fc2453abdd883da10571524c6eceefcf", "url": "/reference/source/forge-rs/crates/forge-contracts/src/identity.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 56, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-02." }, { "name": "::IdentityHandle", "line": 78, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct IdentityHandle {\n/// The OAS DID string (e.g., \"did:oas:l1fe:agent:code-reviewer\").\n\npub did: String,\n/// Depth in the lineage chain (0 = HMR root, 1 = direct child, etc.).\n\npub lineage_depth: u32,\n/// The OAS namespace (e.g., \"l1fe\").\n\npub namespace: String,\n/// The entity name within the DID (e.g., \"code-reviewer\").\n\npub entity_name: String\n}", "documentation": "An opaque handle to an agent's identity within the Forge runtime.\n\nAut0 holds `IdentityHandle` values and passes them to contract methods.\nThe handle exposes the agent's DID and lineage depth but not the private\nkey material.\n\n# Examples\n\n```\nuse forge_contracts::identity::IdentityHandle;\n\nlet handle = IdentityHandle {\n did: \"did:oas:l1fe:agent:code-reviewer\".to_string(),\n lineage_depth: 3,\n namespace: \"l1fe\".to_string(),\n entity_name: \"code-reviewer\".to_string(),\n};\nassert_eq!(handle.did, \"did:oas:l1fe:agent:code-reviewer\");\n```" }, { "name": "::DerivedIdentityRequest", "line": 111, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DerivedIdentityRequest {\n/// The parent agent's DID from which to derive.\n\npub parent_did: String,\n/// The name for the child agent identity.\n\npub child_name: String,\n/// The OAS namespace for the child DID.\n\npub namespace: String,\n/// Optional org ID for organizational context.\n\npub org_id: Option,\n/// Optional department ID for organizational context.\n\npub department_id: Option,\n/// Maximum allowed lineage depth. Derivation fails if this would\n\n/// be exceeded. Default: 16.\n\npub max_lineage_depth: u32\n}", "documentation": "Request to derive a new agent identity from an existing parent.\n\nAut0 uses this to create identity hierarchies that mirror org structure.\n\n# Examples\n\n```\nuse forge_contracts::identity::DerivedIdentityRequest;\n\nlet req = DerivedIdentityRequest {\n parent_did: \"did:oas:l1fe:agent:eng-director\".to_string(),\n child_name: \"code-reviewer\".to_string(),\n namespace: \"l1fe\".to_string(),\n org_id: Some(\"l1fe-ai-inc\".to_string()),\n department_id: Some(\"engineering\".to_string()),\n max_lineage_depth: 16,\n};\n```" }, { "name": "::LineageInfo", "line": 137, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct LineageInfo {\n/// The DID of the identity being verified.\n\npub did: String,\n/// Depth in the lineage chain (0 = root).\n\npub depth: u32,\n/// The root DID at the top of the chain (usually an HMR/MHR).\n\npub root_did: String,\n/// Whether the full chain from root to this identity verifies.\n\npub chain_valid: bool,\n/// Each hop in the chain from root to this identity.\n\npub chain: Vec\n}", "documentation": "Information about an identity's lineage chain.\n\nReturned by `verify_lineage` to give Aut0 visibility into the\ncryptographic proof chain without exposing key material." }, { "name": "::LineageHop", "line": 156, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct LineageHop {\n/// The parent DID at this hop.\n\npub parent_did: String,\n/// The child DID derived at this hop.\n\npub child_did: String,\n/// The derivation path used.\n\npub derivation_path: String,\n/// Whether this individual hop's signature verifies.\n\npub signature_valid: bool\n}", "documentation": "A single hop in a lineage chain." }, { "name": "::IdentityContract", "line": 189, "signature": "#[async_trait]\npub trait IdentityContract: Send + Sync {\n /// Creates a new root identity (HMR) for an organization.\n ///\n /// This is called once per organization founding. The HMR is the\n /// cryptographic root from which all agent identities are derived.\n ///\n /// # Arguments\n ///\n /// * `namespace` - The OAS namespace (e.g., \"l1fe\").\n /// * `root_name` - The root identity name (e.g., \"root-holder\").\n ///\n /// # Returns\n ///\n /// A handle to the created root identity.\n async fn create_root_identity(\n &self,\n namespace: &str,\n root_name: &str,\n ) -> ContractResult;\n\n /// Derives a child identity from an existing parent.\n ///\n /// The child's Ed25519 keypair is deterministically derived via\n /// HKDF-SHA256 from the parent's keypair and the derivation path.\n ///\n /// # Arguments\n ///\n /// * `request` - The derivation parameters.\n ///\n /// # Returns\n ///\n /// A handle to the derived child identity.\n ///\n /// # Errors\n ///\n /// - `ContractError::IdentityDerivationFailed` if derivation fails.\n /// - `ContractError::IdentityDerivationFailed` if max lineage depth\n /// would be exceeded.\n async fn derive_identity(\n &self,\n request: DerivedIdentityRequest,\n ) -> ContractResult;\n\n /// Verifies the lineage chain of an identity.\n ///\n /// Walks the chain from the given DID back to its root and verifies\n /// every hop's cryptographic proof.\n ///\n /// # Arguments\n ///\n /// * `did` - The DID to verify.\n ///\n /// # Returns\n ///\n /// Lineage information including chain validity.\n ///\n /// # Errors\n ///\n /// - `ContractError::DidResolutionFailed` if the DID cannot be resolved.\n /// - `ContractError::LineageVerificationFailed` if any hop fails.\n async fn verify_lineage(&self, did: &str) -> ContractResult;\n\n /// Resolves a DID to its public identity information.\n ///\n /// For local identities, this is immediate. For remote identities,\n /// this may involve network resolution.\n ///\n /// # Arguments\n ///\n /// * `did` - The DID string to resolve.\n ///\n /// # Returns\n ///\n /// The identity handle with public information.\n ///\n /// # Errors\n ///\n /// - `ContractError::DidResolutionFailed` if resolution fails.\n async fn resolve_did(&self, did: &str) -> ContractResult;\n\n /// Signs arbitrary data with the specified identity's private key.\n ///\n /// # Arguments\n ///\n /// * `did` - The DID of the signing identity.\n /// * `data` - The data to sign.\n ///\n /// # Returns\n ///\n /// The Ed25519 signature bytes.\n ///\n /// # Errors\n ///\n /// - `ContractError::DidResolutionFailed` if the DID is not local.\n async fn sign(&self, did: &str, data: &[u8]) -> ContractResult>;\n\n /// Verifies a signature against a DID's public key.\n ///\n /// # Arguments\n ///\n /// * `did` - The DID of the alleged signer.\n /// * `data` - The data that was signed.\n /// * `signature` - The signature to verify.\n ///\n /// # Returns\n ///\n /// `true` if the signature is valid.\n ///\n /// # Errors\n ///\n /// - `ContractError::DidResolutionFailed` if the DID cannot be resolved.\n async fn verify(&self, did: &str, data: &[u8], signature: &[u8]) -> ContractResult;\n}", "documentation": "The primary contract for identity and lineage operations.\n\nForge implements this trait in `forge-identity`. Aut0 consumes it to\nbuild organizational identity hierarchies.\n\n# Implementor Notes (Forge)\n\n- All derivation MUST use HKDF-SHA256 with Ed25519 keys.\n- Private key material MUST never appear in any return type.\n- Lineage verification MUST be possible without network access.\n- The `sign` method MUST use the identity's Ed25519 private key.\n\n# Consumer Notes (Aut0)\n\n- Cache `IdentityHandle` values; they are lightweight.\n- Use `verify_lineage` before trusting an identity from outside\n the local runtime (e.g., from a remote agent).\n- The `resolve_did` method may perform network I/O for remote DIDs." } ] }, { "path": "forge-rs/crates/forge-contracts/src/lib.rs", "sha256": "f2277b6f71636b7d41f4997ba32c39181493c2faa106c759c270ae76b1e62385", "artifactSha256": "762ca33ca91d0b3d047aa5abcfaafe761d63ca500f6b279e5b4b6d6517341dc7", "url": "/reference/source/forge-rs/crates/forge-contracts/src/lib.rs.txt", "declarations": [ { "name": "auth", "line": 69, "signature": "pub mod auth;", "documentation": "# forge-contracts\n\nFormal interface contracts between Forge (agent substrate) and Aut0\n(autonomous organization platform).\n\nThis crate defines the ten shared contracts (S-01 through S-10) from the\nAut0 + Forge Master Engineering Plan. Each contract is a Rust trait plus\nsupporting types that establish the **exact interface boundary** between\nForge and Aut0.\n\n# Design Principles\n\n1. **Forge owns the implementation.** Every contract trait is implemented\n by a Forge crate. Aut0 consumes these implementations but never\n reimplements the underlying logic.\n\n2. **Aut0 owns the policy.** Contracts accept policy parameters (org\n scopes, department constraints, routing rules) that Aut0 provides at\n the organization level.\n\n3. **No circular dependencies.** This crate depends only on `forge-core`,\n `forge-health`, `oas-did`, and `arsenal-core` for shared types. It\n does NOT depend on `forge-agent`, `forge-identity`, `forge-auth`, or\n any Aut0 crate.\n\n4. **Version compatibility.** Every contract carries a `CONTRACT_VERSION`\n constant. Breaking changes require a major version bump. Aut0 and Forge\n must agree on the contract version at startup.\n\n# Contract Index\n\n| Contract | Module | Priority | Phase |\n|----------|--------|----------|-------|\n| S-01 Agent Runtime | [`runtime`] | P1 Critical | 1 |\n| S-02 Identity & Lineage | [`identity`] | P1 Critical | 1 |\n| S-03 Auth & Delegation | [`auth`] | P1 Critical | 1 |\n| S-04 Provider Routing | [`provider`] | P1 High | 2 |\n| S-05 Brew Plans | [`brew`] | P2 High | 3 |\n| S-06 Comm/Collab Envelopes | [`comm`] | P2 High | 3 |\n| S-07 MCP Integration | [`mcp`] | P2 High | 3 |\n| S-08 Telemetry & Health | [`telemetry`] | P2 High | 3 |\n| S-09 Flowers Runtime Bridge | [`flowers`] | P1 High | 2 |\n| S-10 Memory Integration | [`memory`] | P2 High | 2 |\n\n# Usage\n\n```\nuse forge_contracts::runtime::{AgentRuntimeContract, AgentHandle};\nuse forge_contracts::identity::IdentityContract;\nuse forge_contracts::auth::AuthContract;\n```\n\n# Version Compatibility\n\nAll contracts in this crate share a single version. The version follows\nsemantic versioning:\n\n- **Patch**: Documentation, error message improvements, new optional fields\n with defaults.\n- **Minor**: New methods with default implementations, new non-breaking\n types.\n- **Major**: Changed method signatures, removed methods, changed semantics.\n\nBoth Forge and Aut0 must compile against the same major version of\n`forge-contracts`. The [`CONTRACTS_VERSION`] constant is checked at\nruntime initialization." }, { "name": "brew", "line": 70, "signature": "pub mod brew;", "documentation": "" }, { "name": "comm", "line": 71, "signature": "pub mod comm;", "documentation": "" }, { "name": "error", "line": 72, "signature": "pub mod error;", "documentation": "" }, { "name": "flowers", "line": 73, "signature": "pub mod flowers;", "documentation": "" }, { "name": "identity", "line": 74, "signature": "pub mod identity;", "documentation": "" }, { "name": "mcp", "line": 75, "signature": "pub mod mcp;", "documentation": "" }, { "name": "memory", "line": 76, "signature": "pub mod memory;", "documentation": "" }, { "name": "provider", "line": 77, "signature": "pub mod provider;", "documentation": "" }, { "name": "runtime", "line": 78, "signature": "pub mod runtime;", "documentation": "" }, { "name": "telemetry", "line": 79, "signature": "pub mod telemetry;", "documentation": "" }, { "name": "::CONTRACTS_VERSION", "line": 85, "signature": "pub const CONTRACTS_VERSION: &str;", "documentation": "The semantic version of all contracts in this crate.\n\nBoth Forge and Aut0 must agree on the major version at initialization.\nA mismatch in major version is a fatal startup error." }, { "name": "::contracts_major_version", "line": 95, "signature": "pub fn contracts_major_version() -> u32;", "documentation": "Returns the major version number for compatibility checking.\n\n# Examples\n\n```\nlet major = forge_contracts::contracts_major_version();\nassert_eq!(major, 0);\n```" }, { "name": "prelude", "line": 109, "signature": "pub mod prelude;", "documentation": "Prelude module for convenient imports.\n\n```\nuse forge_contracts::prelude::*;\n```" }, { "name": "pub use crate::auth::{\n AuthContract, AuthDecision, CapabilityNarrowingRequest, DelegationChainEntry,\n };", "line": 110, "signature": "pub use crate::auth::{\n AuthContract, AuthDecision, CapabilityNarrowingRequest, DelegationChainEntry,\n };", "documentation": "" }, { "name": "pub use crate::brew::{BrewContract, PlanExecutionResult, PlanHandle};", "line": 113, "signature": "pub use crate::brew::{BrewContract, PlanExecutionResult, PlanHandle};", "documentation": "" }, { "name": "pub use crate::comm::{ChannelConfig, ChannelHandle, CommContract, SessionConfig};", "line": 114, "signature": "pub use crate::comm::{ChannelConfig, ChannelHandle, CommContract, SessionConfig};", "documentation": "" }, { "name": "pub use crate::error::ContractError;", "line": 115, "signature": "pub use crate::error::ContractError;", "documentation": "" }, { "name": "pub use crate::flowers::{CheckpointData, FlowersBridgeContract, FlowersExecutionHandle};", "line": 116, "signature": "pub use crate::flowers::{CheckpointData, FlowersBridgeContract, FlowersExecutionHandle};", "documentation": "" }, { "name": "pub use crate::identity::{\n DerivedIdentityRequest, IdentityContract, IdentityHandle, LineageInfo,\n };", "line": 117, "signature": "pub use crate::identity::{\n DerivedIdentityRequest, IdentityContract, IdentityHandle, LineageInfo,\n };", "documentation": "" }, { "name": "pub use crate::mcp::{McpContract, McpServerHandle, McpToolDescriptor};", "line": 120, "signature": "pub use crate::mcp::{McpContract, McpServerHandle, McpToolDescriptor};", "documentation": "" }, { "name": "pub use crate::memory::{\n MemoryContract, MemoryQuery, MemoryRecord, MemoryScope, MemoryWritePolicy,\n };", "line": 121, "signature": "pub use crate::memory::{\n MemoryContract, MemoryQuery, MemoryRecord, MemoryScope, MemoryWritePolicy,\n };", "documentation": "" }, { "name": "pub use crate::provider::{\n OrgProviderPolicy, ProviderContract, ProviderFallbackStrategy, ProviderSessionHandle,\n };", "line": 124, "signature": "pub use crate::provider::{\n OrgProviderPolicy, ProviderContract, ProviderFallbackStrategy, ProviderSessionHandle,\n };", "documentation": "" }, { "name": "pub use crate::runtime::{\n AgentCreateRequest, AgentHandle, AgentLifecycleCommand, AgentRuntimeContract, AgentStatus,\n };", "line": 127, "signature": "pub use crate::runtime::{\n AgentCreateRequest, AgentHandle, AgentLifecycleCommand, AgentRuntimeContract, AgentStatus,\n };", "documentation": "" }, { "name": "pub use crate::telemetry::{\n HealthSummary, OrgHealthContract, OrgTelemetryContract, SpanFilter,\n };", "line": 130, "signature": "pub use crate::telemetry::{\n HealthSummary, OrgHealthContract, OrgTelemetryContract, SpanFilter,\n };", "documentation": "" } ] }, { "path": "forge-rs/crates/forge-contracts/src/mcp.rs", "sha256": "5dae19a0099171cb5a7b7817cb283b09820dc747ef813e373c21b34e9c83b62d", "artifactSha256": "c78761a32733e21db1fd62ce7070180285ab2936c850aad92b3138d4d8664d59", "url": "/reference/source/forge-rs/crates/forge-contracts/src/mcp.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 45, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-07." }, { "name": "::McpServerConfig", "line": 49, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct McpServerConfig {\n/// Unique name for this MCP server connection.\n\npub server_name: String,\n/// The transport type for connecting to the server.\n\npub transport: McpTransportType,\n/// Optional authentication configuration.\n\npub auth: Option,\n/// Organization that owns this connection.\n\npub org_id: String,\n/// Optional department scope (only agents in this department can use).\n\npub department_id: Option\n}", "documentation": "Configuration for connecting to an external MCP server." }, { "name": "::McpTransportType", "line": 68, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum McpTransportType {\n /// Standard I/O transport (subprocess).\n Stdio {\n /// Command to execute.\n command: String,\n /// Command arguments.\n args: Vec,\n },\n /// Server-Sent Events over HTTP.\n Sse {\n /// The SSE endpoint URL.\n url: String,\n },\n /// Streamable HTTP transport.\n Http {\n /// The HTTP endpoint URL.\n url: String,\n },\n}", "documentation": "The transport type for an MCP connection." }, { "name": "::McpAuthConfig", "line": 90, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct McpAuthConfig {\n/// The authentication method.\n\npub method: McpAuthMethod\n}", "documentation": "Authentication configuration for MCP connections." }, { "name": "::McpAuthMethod", "line": 97, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum McpAuthMethod {\n /// No authentication.\n None,\n /// API key authentication.\n ApiKey {\n /// Header name for the API key.\n header: String,\n },\n /// OAuth 2.0 with PKCE.\n OAuth {\n /// Authorization endpoint URL.\n auth_url: String,\n /// Token endpoint URL.\n token_url: String,\n /// Client ID.\n client_id: String,\n /// Scopes to request.\n scopes: Vec,\n },\n}", "documentation": "Authentication method for MCP connections." }, { "name": "::McpServerHandle", "line": 120, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub struct McpServerHandle {\n/// Unique connection identifier.\n\npub connection_id: String,\n/// The server name.\n\npub server_name: String,\n/// Whether the connection is currently alive.\n\npub connected: bool,\n/// Number of tools available from this server.\n\npub tool_count: u32,\n/// Number of resources available from this server.\n\npub resource_count: u32\n}", "documentation": "An opaque handle to a connected MCP server." }, { "name": "::McpToolDescriptor", "line": 139, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct McpToolDescriptor {\n/// The tool name.\n\npub name: String,\n/// Human-readable description.\n\npub description: String,\n/// JSON Schema for the tool's input parameters.\n\npub input_schema: serde_json::Value,\n/// The MCP server that provides this tool.\n\npub server_name: String\n}", "documentation": "A tool descriptor discovered from an MCP server." }, { "name": "::McpResourceDescriptor", "line": 155, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct McpResourceDescriptor {\n/// The resource URI.\n\npub uri: String,\n/// Human-readable name.\n\npub name: String,\n/// Resource description.\n\npub description: Option,\n/// MIME type of the resource.\n\npub mime_type: Option,\n/// The MCP server that provides this resource.\n\npub server_name: String\n}", "documentation": "A resource descriptor discovered from an MCP server." }, { "name": "::McpContract", "line": 190, "signature": "#[async_trait]\npub trait McpContract: Send + Sync {\n /// Connects to an external MCP server.\n ///\n /// # Arguments\n ///\n /// * `config` - The server connection configuration.\n ///\n /// # Returns\n ///\n /// A handle to the connected server.\n ///\n /// # Errors\n ///\n /// - `ContractError::McpError` if the connection or handshake fails.\n async fn connect_server(&self, config: McpServerConfig) -> ContractResult;\n\n /// Disconnects from an MCP server.\n ///\n /// # Arguments\n ///\n /// * `connection_id` - The connection to close.\n async fn disconnect_server(&self, connection_id: &str) -> ContractResult<()>;\n\n /// Discovers all tools available from a connected server.\n ///\n /// # Arguments\n ///\n /// * `connection_id` - The server to query.\n ///\n /// # Returns\n ///\n /// Tool descriptors from the server.\n async fn discover_tools(&self, connection_id: &str) -> ContractResult>;\n\n /// Discovers all resources available from a connected server.\n ///\n /// # Arguments\n ///\n /// * `connection_id` - The server to query.\n ///\n /// # Returns\n ///\n /// Resource descriptors from the server.\n async fn discover_resources(\n &self,\n connection_id: &str,\n ) -> ContractResult>;\n\n /// Invokes a tool on a connected MCP server.\n ///\n /// # Arguments\n ///\n /// * `connection_id` - The server hosting the tool.\n /// * `tool_name` - The tool to invoke.\n /// * `arguments` - The tool's input arguments as JSON.\n /// * `agent_did` - The agent invoking the tool (for ACT checks).\n ///\n /// # Returns\n ///\n /// The tool's output as JSON.\n ///\n /// # Errors\n ///\n /// - `ContractError::McpError` if the tool invocation fails.\n /// - `ContractError::AuthorizationDenied` if the agent lacks the\n /// required tool scope.\n async fn invoke_tool(\n &self,\n connection_id: &str,\n tool_name: &str,\n arguments: serde_json::Value,\n agent_did: &str,\n ) -> ContractResult;\n\n /// Reads a resource from a connected MCP server.\n ///\n /// # Arguments\n ///\n /// * `connection_id` - The server hosting the resource.\n /// * `uri` - The resource URI.\n ///\n /// # Returns\n ///\n /// The resource content as JSON.\n async fn read_resource(\n &self,\n connection_id: &str,\n uri: &str,\n ) -> ContractResult;\n\n /// Lists all connected MCP servers for an organization.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization to query.\n async fn list_servers(&self, org_id: &str) -> ContractResult>;\n}", "documentation": "The primary contract for MCP integration.\n\nForge implements this trait in `forge-mcp`. Aut0 consumes it to\nmanage MCP server connections and discover tools for agents.\n\n# Implementor Notes (Forge)\n\n- `connect_server` MUST perform the MCP initialization handshake.\n- Tool discovery MUST be cached after initial connection.\n- Tool invocations MUST go through the agent's ACT scope checks.\n\n# Consumer Notes (Aut0)\n\n- Connect MCP servers at org startup via `connect_server`.\n- Use `discover_tools` to populate agent toolbelts.\n- Use `invoke_tool` for direct tool calls (or let the agent\n runtime handle it through the tool loop)." } ] }, { "path": "forge-rs/crates/forge-contracts/src/memory.rs", "sha256": "16cfc8a37e876cfdc39b672a1fcbb1dbbbde1baa37890dd165f913e25782e530", "artifactSha256": "965509576adc705109585e82164160ce3ed357852234ff230a68baa8487563d2", "url": "/reference/source/forge-rs/crates/forge-contracts/src/memory.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 60, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-10." }, { "name": "::MemoryScope", "line": 79, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum MemoryScope {\n /// Organization-wide scope (all agents can read).\n Organization {\n /// The organization identifier.\n org_id: String,\n },\n /// Department-level scope.\n Department {\n /// The organization identifier.\n org_id: String,\n /// The department identifier.\n department_id: String,\n },\n /// Team-level scope.\n Team {\n /// The organization identifier.\n org_id: String,\n /// The department identifier.\n department_id: String,\n /// The team identifier.\n team_id: String,\n },\n /// Agent-private scope.\n Agent {\n /// The agent's DID.\n agent_did: String,\n },\n}", "documentation": "A memory scope within the organizational hierarchy.\n\nScopes form a tree: org -> department -> team -> agent. Read access\nflows upward (child can read parent). Write access flows downward\n(parent can write to child).\n\n# Examples\n\n```\nuse forge_contracts::memory::MemoryScope;\n\nlet scope = MemoryScope::Department {\n org_id: \"l1fe-ai-inc\".to_string(),\n department_id: \"engineering\".to_string(),\n};\n```" }, { "name": "::MemoryScope::org_id", "line": 110, "signature": "pub fn org_id(&self) -> Option<&str>;", "documentation": "Returns the org ID for this scope, if applicable." }, { "name": "::MemoryScope::display_scope", "line": 120, "signature": "pub fn display_scope(&self) -> String;", "documentation": "Returns a human-readable scope string for error messages." }, { "name": "::MemoryType", "line": 139, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum MemoryType {\n /// Temporal events and interaction histories.\n Episodic,\n /// Facts, relationships, and knowledge.\n Semantic,\n /// Workflows, runbooks, and procedures.\n Procedural,\n /// Documents, artifacts, and code snippets.\n Resource,\n}", "documentation": "The type of memory to store or retrieve." }, { "name": "::MemoryRecord", "line": 172, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct MemoryRecord {\n/// The scope where this record should be stored.\n\npub scope: MemoryScope,\n/// The type of memory.\n\npub memory_type: MemoryType,\n/// A unique key within the scope (for retrieval and updates).\n\npub key: String,\n/// The memory content as JSON.\n\npub content: serde_json::Value,\n/// Tags for discovery and filtering.\n\npub tags: Vec,\n/// The DID of the agent that authored this record.\n\npub author_did: String\n}", "documentation": "A memory record to store.\n\n# Examples\n\n```\nuse forge_contracts::memory::{MemoryRecord, MemoryScope, MemoryType};\n\nlet record = MemoryRecord {\n scope: MemoryScope::Department {\n org_id: \"l1fe-ai-inc\".to_string(),\n department_id: \"engineering\".to_string(),\n },\n memory_type: MemoryType::Procedural,\n key: \"code-review-checklist\".to_string(),\n content: serde_json::json!({\n \"steps\": [\"lint\", \"test\", \"security review\", \"approve\"]\n }),\n tags: vec![\"review\".to_string(), \"process\".to_string()],\n author_did: \"did:oas:l1fe:agent:eng-director\".to_string(),\n};\n```" }, { "name": "::MemoryQuery", "line": 194, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct MemoryQuery {\n/// The scope to query. The query also includes all parent scopes\n\n/// (unless `include_parents` is `false`).\n\npub scope: Option,\n/// Filter by memory type.\n\npub memory_type: Option,\n/// Filter by key prefix.\n\npub key_prefix: Option,\n/// Filter by tags (records must have ALL specified tags).\n\npub tags: Vec,\n/// Semantic search query (uses vector similarity).\n\npub semantic_query: Option,\n/// Maximum results to return.\n\npub limit: Option,\n/// Whether to include records from parent scopes. Default: true.\n\npub include_parents: bool\n}", "documentation": "A query for retrieving memory records." }, { "name": "::MemoryResult", "line": 220, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct MemoryResult {\n/// The record's unique key.\n\npub key: String,\n/// The scope this record belongs to.\n\npub scope: MemoryScope,\n/// The memory type.\n\npub memory_type: MemoryType,\n/// The record content.\n\npub content: serde_json::Value,\n/// Tags on this record.\n\npub tags: Vec,\n/// Who authored this record.\n\npub author_did: String,\n/// When this record was created.\n\npub created_at: DateTime,\n/// When this record was last updated.\n\npub updated_at: DateTime,\n/// Similarity score (0.0 to 1.0) when using semantic search.\n\npub similarity: Option\n}", "documentation": "A memory record returned from a query." }, { "name": "::MemoryWritePolicy", "line": 251, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct MemoryWritePolicy {\n/// The scope this policy applies to.\n\npub scope: MemoryScope,\n/// Whether writes are allowed to this scope.\n\npub writes_allowed: bool,\n/// DIDs allowed to write (empty = all agents in scope can write).\n\npub allowed_writers: Vec,\n/// Memory types that are writable (empty = all types).\n\npub writable_types: Vec,\n/// Whether writes require approval from a parent scope agent.\n\npub requires_approval: bool,\n/// Maximum record size in bytes.\n\npub max_record_size_bytes: Option\n}", "documentation": "Policy governing write access to a memory scope." }, { "name": "::MemoryContract", "line": 292, "signature": "#[async_trait]\npub trait MemoryContract: Send + Sync {\n /// Stores a memory record.\n ///\n /// # Arguments\n ///\n /// * `record` - The record to store.\n ///\n /// # Errors\n ///\n /// - `ContractError::MemoryAccessDenied` if the author lacks write\n /// access to the specified scope.\n /// - `ContractError::MemoryError` if storage fails.\n async fn store(&self, record: MemoryRecord) -> ContractResult<()>;\n\n /// Retrieves memory records matching a query.\n ///\n /// # Arguments\n ///\n /// * `query` - The query criteria.\n /// * `requester_did` - The agent requesting the records (for access\n /// control).\n ///\n /// # Returns\n ///\n /// Matching records ordered by relevance (semantic search) or\n /// recency (non-semantic queries).\n ///\n /// # Errors\n ///\n /// - `ContractError::MemoryAccessDenied` if the requester lacks\n /// read access.\n async fn retrieve(\n &self,\n query: MemoryQuery,\n requester_did: &str,\n ) -> ContractResult>;\n\n /// Deletes a memory record.\n ///\n /// # Arguments\n ///\n /// * `scope` - The scope containing the record.\n /// * `key` - The record key.\n /// * `requester_did` - The agent requesting deletion (for access\n /// control).\n ///\n /// # Errors\n ///\n /// - `ContractError::MemoryAccessDenied` if the requester lacks\n /// write access.\n async fn delete(\n &self,\n scope: &MemoryScope,\n key: &str,\n requester_did: &str,\n ) -> ContractResult<()>;\n\n /// Sets the write policy for a memory scope.\n ///\n /// # Arguments\n ///\n /// * `policy` - The write policy to set.\n ///\n /// # Errors\n ///\n /// - `ContractError::AuthorizationDenied` if the caller lacks\n /// authority to set policies for this scope.\n async fn set_write_policy(&self, policy: MemoryWritePolicy) -> ContractResult<()>;\n\n /// Returns the current write policy for a scope.\n ///\n /// # Arguments\n ///\n /// * `scope` - The scope to query.\n async fn get_write_policy(\n &self,\n scope: &MemoryScope,\n ) -> ContractResult>;\n}", "documentation": "The primary contract for memory integration.\n\nForge implements this trait with Akasha-backed storage. Aut0 consumes\nit to manage organizational knowledge hierarchies.\n\n# Implementor Notes (Forge)\n\n- `store` MUST enforce write policies before persisting.\n- `retrieve` MUST respect scope hierarchy (child can read parent).\n- `semantic_search` MUST use Akasha's vector operations.\n- `delete` MUST check that the requesting agent has write access.\n\n# Consumer Notes (Aut0)\n\n- Set write policies per scope at org startup.\n- Use `store` for organizational knowledge (policies, procedures,\n mission statements, runbooks).\n- Use `retrieve` with semantic search for context-aware agent memory.\n- Memory is the primary mechanism for org-level skill packs and\n crate-specific knowledge." } ] }, { "path": "forge-rs/crates/forge-contracts/src/provider.rs", "sha256": "355b623ad051e61df4fab522299d8eb79870ec62fbb3b2f02f709124f4ebe530", "artifactSha256": "965831d339d503adb72ef97ddd6201dc17576829d074ff4d6cede1c1d94c30d2", "url": "/reference/source/forge-rs/crates/forge-contracts/src/provider.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 51, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-04." }, { "name": "::OrgProviderPolicy", "line": 80, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct OrgProviderPolicy {\n/// The organization this policy applies to.\n\npub org_id: String,\n/// Ordered list of available providers. Lower priority number = preferred.\n\npub providers: Vec,\n/// Strategy for handling provider failures.\n\npub fallback_strategy: ProviderFallbackStrategy,\n/// Department-level overrides. Key is department ID.\n\n/// Overrides merge with (not replace) the org-level policy.\n\npub department_overrides: BTreeMap\n}", "documentation": "Organization-level provider policy set by Aut0.\n\nThis defines which providers are available to agents within an\norganization, with optional department-level overrides.\n\n# Examples\n\n```\nuse forge_contracts::provider::{OrgProviderPolicy, ProviderEntry, ProviderFallbackStrategy};\n\nlet policy = OrgProviderPolicy {\n org_id: \"l1fe-ai-inc\".to_string(),\n providers: vec![\n ProviderEntry {\n namespace: \"anthropic\".to_string(),\n enabled: true,\n priority: 1,\n max_tokens_per_minute: Some(100_000),\n max_cost_per_hour_usd: Some(10.0),\n allowed_models: vec![\"claude-sonnet-4-5-20250929\".to_string()],\n },\n ],\n fallback_strategy: ProviderFallbackStrategy::NextPriority,\n department_overrides: Default::default(),\n};\n```" }, { "name": "::ProviderEntry", "line": 97, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct ProviderEntry {\n/// Provider namespace (e.g., \"openai\", \"anthropic\", \"local\").\n\npub namespace: String,\n/// Whether this provider is currently enabled.\n\npub enabled: bool,\n/// Priority for routing (lower = preferred).\n\npub priority: u32,\n/// Optional rate limit: max tokens per minute across all agents.\n\npub max_tokens_per_minute: Option,\n/// Optional cost limit: max USD per hour.\n\npub max_cost_per_hour_usd: Option,\n/// Allowed model names within this provider. Empty = all models.\n\npub allowed_models: Vec\n}", "documentation": "A single provider entry in the policy." }, { "name": "::DepartmentProviderOverride", "line": 119, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct DepartmentProviderOverride {\n/// Department identifier.\n\npub department_id: String,\n/// Provider namespaces explicitly allowed for this department.\n\n/// Empty means \"inherit org policy.\"\n\npub allowed_providers: Vec,\n/// Provider namespaces explicitly blocked for this department.\n\npub blocked_providers: Vec,\n/// Optional department-level cost cap (USD per hour).\n\npub max_cost_per_hour_usd: Option\n}", "documentation": "Department-level override to the org provider policy." }, { "name": "::ProviderFallbackStrategy", "line": 136, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum ProviderFallbackStrategy {\n /// Try the next provider in priority order.\n NextPriority,\n /// Fail immediately without trying alternatives.\n FailFast,\n /// Retry the same provider up to N times, then fail.\n RetryThenFail {\n /// Maximum number of retries.\n max_retries: u32,\n },\n /// Retry the same provider, then fall back to next priority.\n RetryThenFallback {\n /// Maximum retries before fallback.\n max_retries: u32,\n },\n}", "documentation": "Strategy for handling provider failures." }, { "name": "::ProviderSessionHandle", "line": 158, "signature": "#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]\npub struct ProviderSessionHandle {\n/// Unique session identifier.\n\npub session_id: String,\n/// The provider namespace for this session.\n\npub provider_namespace: String,\n/// The specific model in use.\n\npub model: String,\n/// Tokens consumed in this session so far.\n\npub tokens_consumed: u64,\n/// Estimated cost in USD so far.\n\npub estimated_cost_usd: f64\n}", "documentation": "An opaque handle to an active provider session.\n\nProvider sessions track state across multiple LLM calls (e.g.,\nconversation history, rate limit windows, cost accumulation)." }, { "name": "::ProviderContract", "line": 196, "signature": "#[async_trait]\npub trait ProviderContract: Send + Sync {\n /// Sets or updates the organization-level provider policy.\n ///\n /// This replaces the entire policy for the given organization.\n ///\n /// # Arguments\n ///\n /// * `policy` - The complete provider policy.\n ///\n /// # Errors\n ///\n /// - `ContractError::ConfigurationError` if the policy is invalid.\n async fn set_org_policy(&self, policy: OrgProviderPolicy) -> ContractResult<()>;\n\n /// Resolves the best provider for a given request.\n ///\n /// Considers org policy, department overrides, agent capabilities,\n /// current rate limits, and cost budgets.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization making the request.\n /// * `department_id` - Optional department for override lookup.\n /// * `agent_did` - The requesting agent (for ACT scope checks).\n /// * `requested_provider` - Optional provider preference (e.g., \"anthropic:claude-sonnet-4-5-20250929\").\n ///\n /// # Returns\n ///\n /// A handle to the created provider session.\n ///\n /// # Errors\n ///\n /// - `ContractError::NoProviderAvailable` if no provider matches.\n /// - `ContractError::AuthorizationDenied` if the agent lacks provider scopes.\n async fn resolve_provider(\n &self,\n org_id: &str,\n department_id: Option<&str>,\n agent_did: &str,\n requested_provider: Option<&str>,\n ) -> ContractResult;\n\n /// Returns the current status of a provider session.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The session to query.\n ///\n /// # Returns\n ///\n /// The session handle with current usage statistics.\n async fn get_session(&self, session_id: &str) -> ContractResult;\n\n /// Closes a provider session, releasing resources.\n ///\n /// # Arguments\n ///\n /// * `session_id` - The session to close.\n async fn close_session(&self, session_id: &str) -> ContractResult<()>;\n\n /// Returns usage statistics for an organization.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization to query.\n ///\n /// # Returns\n ///\n /// Aggregate usage per provider namespace.\n async fn get_org_usage(\n &self,\n org_id: &str,\n ) -> ContractResult>;\n}", "documentation": "The primary contract for provider routing and session management.\n\nForge implements this trait. Aut0 consumes it to set organizational\nprovider policies and manage provider sessions for agents.\n\n# Implementor Notes (Forge)\n\n- `set_org_policy` MUST validate provider entries and reject invalid\n configurations immediately.\n- `resolve_provider` MUST check org policy, department overrides, and\n agent ACT scopes before selecting a provider.\n- Provider sessions MUST track token usage and cost for org-level billing.\n\n# Consumer Notes (Aut0)\n\n- Call `set_org_policy` at org startup and whenever provider\n configuration changes.\n- Use `get_session` to monitor active provider usage for cost tracking.\n- The `department_overrides` in `OrgProviderPolicy` allow fine-grained\n control per department without modifying the org-wide policy." }, { "name": "::ProviderUsageStats", "line": 273, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct ProviderUsageStats {\n/// Total tokens consumed.\n\npub total_tokens: u64,\n/// Total estimated cost in USD.\n\npub total_cost_usd: f64,\n/// Number of active sessions.\n\npub active_sessions: u32,\n/// Number of requests in the current rate limit window.\n\npub requests_this_window: u64,\n/// Number of requests that were rate-limited.\n\npub rate_limited_count: u64,\n/// Number of requests that failed.\n\npub failure_count: u64\n}", "documentation": "Aggregate usage statistics for a provider namespace within an org." } ] }, { "path": "forge-rs/crates/forge-contracts/src/runtime.rs", "sha256": "4dbb8f13325f3c7f0ba99318e6c9fef05643056919ee22fc53f011f00cc25230", "artifactSha256": "19f530b03860d54a92cc6666e7e691d20115dea465dc0c35ea6f982180c53ca8", "url": "/reference/source/forge-rs/crates/forge-contracts/src/runtime.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 60, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-01." }, { "name": "::AgentCreateRequest", "line": 88, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct AgentCreateRequest {\n/// Human-readable name for the agent (e.g., \"code-reviewer\").\n\npub agent_name: String,\n/// The provider:model reference (e.g., \"anthropic:claude-sonnet-4-5-20250929\").\n\npub provider_ref: String,\n/// Optional system prompt prepended to every LLM call.\n\npub system_prompt: Option,\n/// Tool definitions available to this agent.\n\npub tools: Vec,\n/// Maximum tool loop steps before forced termination.\n\npub max_steps: u32,\n/// Aut0 organization ID (org-level context).\n\npub org_id: Option,\n/// Aut0 department ID (department-level context).\n\npub department_id: Option,\n/// Role within the organization (e.g., \"senior-reviewer\", \"pm\").\n\npub role: Option,\n/// Parent agent DID for sub-agent derivation. When `None`, the agent\n\n/// is a root-level agent derived from an HMR/MHR.\n\npub parent_agent_did: Option,\n/// Arbitrary key-value metadata for Aut0-specific context.\n\npub metadata: std::collections::BTreeMap\n}", "documentation": "Request to create a new agent within the Forge runtime.\n\nAut0 populates this struct with organization-level context (department,\nrole, task assignment) plus the Forge-level agent configuration (model,\ntools, system prompt).\n\n# Examples\n\n```\nuse forge_contracts::runtime::AgentCreateRequest;\n\nlet req = AgentCreateRequest {\n agent_name: \"code-reviewer\".to_string(),\n provider_ref: \"anthropic:claude-sonnet-4-5-20250929\".to_string(),\n system_prompt: Some(\"You are a senior code reviewer.\".to_string()),\n tools: vec![],\n max_steps: 25,\n org_id: Some(\"l1fe-ai-inc\".to_string()),\n department_id: Some(\"engineering\".to_string()),\n role: Some(\"senior-reviewer\".to_string()),\n parent_agent_did: None,\n metadata: Default::default(),\n};\nassert_eq!(req.agent_name, \"code-reviewer\");\n```" }, { "name": "::AgentHandle", "line": 138, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Hash)]\npub struct AgentHandle {\n\n}", "documentation": "Opaque handle to a running agent within the Forge runtime.\n\nAut0 holds `AgentHandle` values and passes them back to the contract\nmethods to reference specific agents. The handle is not serializable\nacross process boundaries -- it is valid only within the creating\nruntime instance.\n\n# Examples\n\n```\nuse forge_contracts::runtime::AgentHandle;\n\nlet handle = AgentHandle::new(\"agent-001\", \"did:oas:l1fe:agent:code-reviewer\");\nassert_eq!(handle.id(), \"agent-001\");\nassert_eq!(handle.did(), \"did:oas:l1fe:agent:code-reviewer\");\n```" }, { "name": "::AgentHandle::new", "line": 147, "signature": "pub fn new(id: impl Into, did: impl Into) -> Self;", "documentation": "Creates a new agent handle." }, { "name": "::AgentHandle::id", "line": 155, "signature": "pub fn id(&self) -> &str;", "documentation": "Returns the internal runtime identifier." }, { "name": "::AgentHandle::did", "line": 160, "signature": "pub fn did(&self) -> &str;", "documentation": "Returns the agent's OAS DID." }, { "name": "::AgentLifecycleCommand", "line": 169, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum AgentLifecycleCommand {\n /// Transition from Initializing to Ready, then to Running.\n Start,\n /// Transition from Running to Paused.\n Pause,\n /// Transition from Paused to Running.\n Resume,\n /// Transition from any state to Terminated.\n Terminate {\n /// Optional reason for termination.\n reason: Option,\n },\n}", "documentation": "Commands that Aut0 can issue to manage an agent's lifecycle.\n\nThese map to the ANVIL 6-state lifecycle state machine transitions." }, { "name": "::AgentStatus", "line": 187, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct AgentStatus {\n/// The agent's OAS DID.\n\npub did: String,\n/// Current ANVIL lifecycle state.\n\npub lifecycle_state: LifecycleState,\n/// Current health profile snapshot.\n\npub health: HealthProfile,\n/// Number of tool loop steps completed.\n\npub steps_completed: u32,\n/// Number of tool loop steps remaining before max_steps.\n\npub steps_remaining: u32,\n/// Whether the agent is currently executing a tool call.\n\npub executing_tool: bool,\n/// The provider:model reference the agent is using.\n\npub provider_ref: String,\n/// Aut0 metadata passed at creation.\n\npub metadata: std::collections::BTreeMap\n}", "documentation": "Current status of an agent, returned by `get_status`.\n\nCombines lifecycle state with health profile for a complete snapshot." }, { "name": "::AgentRunResult", "line": 215, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct AgentRunResult {\n/// The final text output from the agent, if any.\n\npub output_text: Option,\n/// Structured output as JSON, if the agent produced structured output.\n\npub output_json: Option,\n/// Total tool invocations during the run.\n\npub tool_invocations: u32,\n/// Total LLM inference calls during the run.\n\npub inference_calls: u32,\n/// Total tokens consumed (input + output).\n\npub total_tokens: u64,\n/// Whether the agent terminated normally or was force-stopped.\n\npub terminated_normally: bool,\n/// The final lifecycle state.\n\npub final_state: LifecycleState\n}", "documentation": "The result of an agent's execution run." }, { "name": "::AgentRuntimeContract", "line": 262, "signature": "#[async_trait]\npub trait AgentRuntimeContract: Send + Sync {\n /// Creates a new agent in the Forge runtime.\n ///\n /// The agent starts in `Initializing` state. Call `lifecycle_command`\n /// with `Start` to advance it to `Running`.\n ///\n /// # Arguments\n ///\n /// * `request` - The agent creation parameters including identity,\n /// provider, tools, and Aut0-specific metadata.\n ///\n /// # Returns\n ///\n /// An opaque handle to the created agent.\n ///\n /// # Errors\n ///\n /// - `ContractError::AgentCreationFailed` if the configuration is invalid.\n /// - `ContractError::IdentityDerivationFailed` if identity cannot be derived.\n /// - `ContractError::NoProviderAvailable` if the provider ref cannot be resolved.\n async fn create_agent(&self, request: AgentCreateRequest) -> ContractResult;\n\n /// Issues a lifecycle command to an existing agent.\n ///\n /// # Arguments\n ///\n /// * `handle` - The agent to command.\n /// * `command` - The lifecycle transition to perform.\n ///\n /// # Returns\n ///\n /// The new status after the transition.\n ///\n /// # Errors\n ///\n /// - `ContractError::AgentNotFound` if the handle is invalid.\n /// - `ContractError::InvalidLifecycleTransition` if the transition\n /// violates the ANVIL state machine.\n async fn lifecycle_command(\n &self,\n handle: &AgentHandle,\n command: AgentLifecycleCommand,\n ) -> ContractResult;\n\n /// Queries the current status of an agent.\n ///\n /// # Arguments\n ///\n /// * `handle` - The agent to query.\n ///\n /// # Returns\n ///\n /// A snapshot of the agent's lifecycle, health, and execution state.\n ///\n /// # Errors\n ///\n /// - `ContractError::AgentNotFound` if the handle is invalid.\n async fn get_status(&self, handle: &AgentHandle) -> ContractResult;\n\n /// Runs an agent to completion with the given input.\n ///\n /// This is a convenience method that starts the agent (if not already\n /// running), sends the input through the tool loop, and blocks until\n /// termination or max_steps.\n ///\n /// # Arguments\n ///\n /// * `handle` - The agent to run.\n /// * `input` - The user/task input string.\n ///\n /// # Returns\n ///\n /// The execution result including output, tool counts, and token usage.\n ///\n /// # Errors\n ///\n /// - `ContractError::AgentNotFound` if the handle is invalid.\n /// - `ContractError::InvalidLifecycleTransition` if the agent is in\n /// a state that cannot transition to Running.\n async fn run_to_completion(\n &self,\n handle: &AgentHandle,\n input: &str,\n ) -> ContractResult;\n\n /// Lists all active agents matching an optional filter.\n ///\n /// # Arguments\n ///\n /// * `org_id` - Filter by organization. `None` returns all.\n /// * `department_id` - Filter by department. `None` returns all in org.\n ///\n /// # Returns\n ///\n /// Handles for all matching agents.\n async fn list_agents(\n &self,\n org_id: Option<&str>,\n department_id: Option<&str>,\n ) -> ContractResult>;\n}", "documentation": "The primary contract for agent lifecycle management.\n\nForge implements this trait. Aut0 consumes it to create and manage agents\nwithin organization departments, workflows, and tasks.\n\n# Implementor Notes (Forge)\n\n- `create_agent` MUST assign an OAS identity to the agent. If\n `parent_agent_did` is provided, derive identity via HKDF. Otherwise,\n derive from the organization's HMR/MHR root.\n- `lifecycle_command` MUST enforce the ANVIL 6-state transition table.\n Invalid transitions return `ContractError::InvalidLifecycleTransition`.\n- `run_to_completion` executes the agent's tool loop and blocks until\n the agent terminates or reaches max_steps.\n\n# Consumer Notes (Aut0)\n\n- Always check `get_status` before issuing lifecycle commands.\n- Store the `AgentHandle` for the lifetime of the agent. Dropping the\n handle does NOT terminate the agent -- call `lifecycle_command` with\n `Terminate` explicitly.\n- The `metadata` field on `AgentCreateRequest` is the place to attach\n Aut0-specific context (task ID, workflow run ID, department)." } ] }, { "path": "forge-rs/crates/forge-contracts/src/telemetry.rs", "sha256": "79c60c491d207d88c22a813f3472bd9ad5f4374cbbc3c4b833d3e6d1fcd82be3", "artifactSha256": "51b9e0cbbb5b555a87f495f8618a8bbe6af0929164de9ca6660f258be39a8a16", "url": "/reference/source/forge-rs/crates/forge-contracts/src/telemetry.rs.txt", "declarations": [ { "name": "::CONTRACT_VERSION", "line": 46, "signature": "pub const CONTRACT_VERSION: &str;", "documentation": "Contract version for S-08." }, { "name": "::SpanFilter", "line": 50, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct SpanFilter {\n/// Filter by agent DID.\n\npub agent_did: Option,\n/// Filter by span name prefix (e.g., \"anvil.tool.\").\n\npub name_prefix: Option,\n/// Filter by time range start (inclusive).\n\npub from: Option>,\n/// Filter by time range end (exclusive).\n\npub to: Option>,\n/// Filter by organization.\n\npub org_id: Option,\n/// Filter by department.\n\npub department_id: Option,\n/// Maximum number of spans to return.\n\npub limit: Option\n}", "documentation": "Filter criteria for querying spans." }, { "name": "::CollectedSpan", "line": 75, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct CollectedSpan {\n/// Unique span identifier.\n\npub span_id: String,\n/// Optional parent span ID.\n\npub parent_span_id: Option,\n/// The span name (e.g., \"anvil.generate\", \"anvil.tool.invoke\").\n\npub name: String,\n/// The agent DID that emitted this span.\n\npub agent_did: String,\n/// Start timestamp.\n\npub started_at: DateTime,\n/// End timestamp.\n\npub ended_at: Option>,\n/// Duration in microseconds.\n\npub duration_us: Option,\n/// Span attributes as key-value pairs.\n\npub attributes: BTreeMap\n}", "documentation": "A telemetry span collected from agent execution." }, { "name": "::AuditEntry", "line": 103, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct AuditEntry {\n/// Sequential entry index.\n\npub index: u64,\n/// The agent DID that created this entry.\n\npub agent_did: String,\n/// The event kind.\n\npub event_kind: String,\n/// The event payload as JSON.\n\npub payload: serde_json::Value,\n/// ISO 8601 timestamp.\n\npub timestamp: DateTime,\n/// Ed25519 signature (base64-encoded).\n\npub signature: String\n}", "documentation": "A signed audit trail entry." }, { "name": "::HealthSummary", "line": 125, "signature": "#[derive(Debug, Clone, Serialize, Deserialize)]\npub struct HealthSummary {\n/// The scope identifier (org ID, department ID, or team ID).\n\npub scope_id: String,\n/// The scope type.\n\npub scope_type: HealthScopeType,\n/// Overall health status for this scope.\n\npub overall_status: HealthStatus,\n/// Number of agents in each lifecycle state.\n\npub lifecycle_counts: BTreeMap,\n/// Number of agents at each health level.\n\npub health_counts: HealthCounts,\n/// Total active agents in this scope.\n\npub total_agents: u32,\n/// Total tool invocations across all agents.\n\npub total_tool_invocations: u64,\n/// Total inference calls across all agents.\n\npub total_inference_calls: u64,\n/// Total tokens consumed across all agents.\n\npub total_tokens: u64,\n/// Estimated total cost in USD.\n\npub estimated_cost_usd: f64,\n/// When this summary was last computed.\n\npub computed_at: DateTime\n}", "documentation": "Health summary for an organizational unit (org, department, or team)." }, { "name": "::HealthScopeType", "line": 162, "signature": "#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]\npub enum HealthScopeType {\n /// Organization-wide summary.\n Organization,\n /// Department-level summary.\n Department,\n /// Team-level summary.\n Team,\n}", "documentation": "The type of scope a health summary covers." }, { "name": "::HealthCounts", "line": 173, "signature": "#[derive(Debug, Clone, Default, Serialize, Deserialize)]\npub struct HealthCounts {\n/// Number of agents in Healthy state.\n\npub healthy: u32,\n/// Number of agents in Degraded state.\n\npub degraded: u32,\n/// Number of agents in Critical state.\n\npub critical: u32\n}", "documentation": "Counts of agents at each health level." }, { "name": "::OrgTelemetryContract", "line": 199, "signature": "#[async_trait]\npub trait OrgTelemetryContract: Send + Sync {\n /// Queries collected spans with filtering.\n ///\n /// # Arguments\n ///\n /// * `filter` - Criteria for filtering spans.\n ///\n /// # Returns\n ///\n /// Matching spans ordered by start time.\n async fn query_spans(&self, filter: SpanFilter) -> ContractResult>;\n\n /// Returns the audit trail for an agent.\n ///\n /// # Arguments\n ///\n /// * `agent_did` - The agent whose audit trail to retrieve.\n /// * `from_index` - Start reading from this entry index.\n /// * `limit` - Maximum entries to return.\n ///\n /// # Returns\n ///\n /// Audit entries in sequential order.\n async fn get_audit_trail(\n &self,\n agent_did: &str,\n from_index: u64,\n limit: u32,\n ) -> ContractResult>;\n\n /// Returns the audit trail for an entire organization.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization to query.\n /// * `from` - Start time (inclusive).\n /// * `to` - End time (exclusive).\n /// * `limit` - Maximum entries to return.\n async fn get_org_audit_trail(\n &self,\n org_id: &str,\n from: DateTime,\n to: DateTime,\n limit: u32,\n ) -> ContractResult>;\n}", "documentation": "The primary contract for telemetry aggregation.\n\nForge implements this trait. Aut0 consumes it to aggregate per-agent\ntelemetry into organizational views.\n\n# Implementor Notes (Forge)\n\n- `query_spans` MUST support all filter criteria.\n- Spans MUST include the agent's DID for org-level aggregation.\n- The implementation SHOULD use efficient indexing for time-range queries.\n\n# Consumer Notes (Aut0)\n\n- Use `query_spans` for debugging and performance analysis.\n- Use `get_audit_trail` for compliance and governance audits.\n- Cache span data in Aut0's own storage for long-term analytics." }, { "name": "::OrgHealthContract", "line": 261, "signature": "#[async_trait]\npub trait OrgHealthContract: Send + Sync {\n /// Returns a health summary for an organizational scope.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization.\n /// * `scope_type` - The scope level (org, department, or team).\n /// * `scope_id` - The scope identifier. For `Organization`, this\n /// is the org ID. For `Department`, the department ID, etc.\n ///\n /// # Returns\n ///\n /// Aggregated health summary for all agents in the scope.\n async fn get_health_summary(\n &self,\n org_id: &str,\n scope_type: HealthScopeType,\n scope_id: &str,\n ) -> ContractResult;\n\n /// Returns health summaries for all departments in an organization.\n ///\n /// # Arguments\n ///\n /// * `org_id` - The organization to query.\n ///\n /// # Returns\n ///\n /// One summary per department.\n async fn get_all_department_health(&self, org_id: &str) -> ContractResult>;\n\n /// Returns the health status of a specific agent.\n ///\n /// # Arguments\n ///\n /// * `agent_did` - The agent to query.\n async fn get_agent_health(&self, agent_did: &str) -> ContractResult;\n}", "documentation": "The primary contract for health aggregation.\n\nForge implements this trait. Aut0 consumes it for org-level health\ndashboards and incident detection.\n\n# Implementor Notes (Forge)\n\n- `get_health_summary` MUST aggregate across all agents in the scope.\n- The `overall_status` MUST be the worst status among all agents.\n\n# Consumer Notes (Aut0)\n\n- Poll `get_health_summary` periodically for dashboard updates.\n- Trigger incident flows when `overall_status` is Critical." } ] } ] }