// file: kb_execution_api/src/executor.rs
// version: 3

//! Shared execution contract and neutral request models.

use ts_rs::TS; // rust-rules: derive-import

/// Support level returned by an executor for a requested operation.
#[derive(Clone, Copy, Debug, Eq, PartialEq, TS)]
#[ts(
    export,
    export_to = "../frontend/ts/bindings/kb_execution_api/executor/ExecutionSupport.ts"
)]
pub enum ExecutionSupport {
    /// The executor cannot handle the request.
    No,
    /// The executor may handle the request after account and payload validation.
    Maybe,
    /// The executor explicitly supports the request.
    Yes,
}

/// Generic request used before protocol-specific execution models are introduced.
#[derive(Clone, Debug, Eq, PartialEq, TS)]
#[ts(
    export,
    export_to = "../frontend/ts/bindings/kb_execution_api/executor/ExecutionRequest.ts"
)]
pub struct ExecutionRequest {
    /// Target program id.
    pub program_id: kb_model::ProgramId,
    /// Stable operation code such as buy, sell, transfer or route.
    pub operation_code: std::string::String,
    /// Serialized JSON payload reserved for protocol-specific arguments.
    pub payload_json: std::string::String,
}

/// Neutral execution plan placeholder produced by executor crates.
#[derive(Clone, Debug, Eq, PartialEq, TS)]
#[ts(
    export,
    export_to = "../frontend/ts/bindings/kb_execution_api/executor/ExecutionPlan.ts"
)]
pub struct ExecutionPlan {
    /// Stable executor crate name.
    pub executor_name: std::string::String,
    /// Number of instructions that would be produced by the final implementation.
    pub instruction_count: usize,
    /// Serialized JSON payload reserved for future instruction data and account metadata.
    pub payload_json: std::string::String,
}

/// Serializes a JSON payload to its compact string representation.
pub fn serialize_payload_json(value: &serde_json::Value) -> kb_core::Result<std::string::String> {
    return match serde_json::to_string(value) {
        std::result::Result::Ok(serialized) => std::result::Result::Ok(serialized),
        std::result::Result::Err(error) => std::result::Result::Err(kb_core::Error::new(
            "execution_payload_json_serialize_failed",
            error.to_string(),
        )),
    };
}

/// Serializes a JSON payload to its pretty string representation.
pub fn serialize_payload_json_pretty(
    value: &serde_json::Value,
) -> kb_core::Result<std::string::String> {
    return match serde_json::to_string_pretty(value) {
        std::result::Result::Ok(serialized) => std::result::Result::Ok(serialized),
        std::result::Result::Err(error) => std::result::Result::Err(kb_core::Error::new(
            "execution_payload_json_pretty_serialize_failed",
            error.to_string(),
        )),
    };
}

/// Common contract implemented by all execution crates.
pub trait InstructionExecutor {
    /// Returns the stable executor name.
    fn executor_name(&self) -> &'static str;

    /// Returns the executor version.
    fn executor_version(&self) -> &'static str;

    /// Returns the program ids handled by this executor.
    fn program_ids(&self) -> &'static [&'static str];

    /// Tests whether this executor owns a program id.
    fn handles_program_id(&self, program_id: &kb_model::ProgramId) -> bool {
        return self
            .program_ids()
            .iter()
            .any(|candidate| return *candidate == program_id.0.as_str());
    }

    /// Tests whether this executor supports a request.
    fn supports_request(&self, request: &crate::ExecutionRequest) -> crate::ExecutionSupport;

    /// Builds a neutral execution plan placeholder.
    fn build_plan(
        &self,
        request: &crate::ExecutionRequest,
    ) -> kb_core::Result<crate::ExecutionPlan>;
}