wasm-capability-contract 0.4.0

//! [`CapabilityEngine`] — loads and invokes a validated Wasm component's handler export.

use futures::future::BoxFuture;

use crate::{
    CapabilityError, ComponentInvokeRequest, ComponentInvokeResponse, ComponentLoadRequest,
    ComponentLoadResponse,
};

/// Loads a validated component and invokes its handler export.
///
/// Implementations own instantiation, isolation, and resource-limit
/// enforcement — none of that is expressed in this trait, matching every
/// other port in this crate (the contract is the behavior, not the
/// mechanism). Callers must have already validated the same manifest/
/// bytes against ADR-001's own two-gate contract first — `load` is not
/// required to re-run the manifest-level grant check, only to fail if the
/// bytes cannot actually be instantiated. Zero implementation here.
pub trait CapabilityEngine: Send + Sync {
    /// Load a component artifact, returning a handle for subsequent
    /// [`CapabilityEngine::invoke`] calls.
    ///
    /// # Errors
    ///
    /// Returns [`CapabilityError`] if the bytes cannot be instantiated, or
    /// a declared-and-granted capability has no real dispatcher wired for
    /// it ([`CapabilityError::CapabilityUnavailable`]).
    fn load(
        &self,
        req: ComponentLoadRequest,
    ) -> BoxFuture<'_, Result<ComponentLoadResponse, CapabilityError>>;

    /// Invoke a previously loaded component's handler export once.
    ///
    /// # Errors
    ///
    /// Returns [`CapabilityError`] if the component traps, exceeds a
    /// configured resource limit, or exceeds `req.deadline`.
    fn invoke(
        &self,
        req: ComponentInvokeRequest,
    ) -> BoxFuture<'_, Result<ComponentInvokeResponse, CapabilityError>>;
}