//! Wire types for self-dispatch outcome callbacks.

//!

//! `DispatchOutcome` is an Agent SDK concept: an instance fn classifies one external

//! action attempt, then certifies this payload back into a network callback. The SDK

//! callback routing lives in `workflow_helpers::apply_dispatch_outcome`.

//!

//! ## Variant guide

//!

//! Five variants matching the five non-trivial `AgentEvent` transitions on the execution

//! side. No new event types - `DispatchOutcome` is just the classification payload the

//! instance fn produces; the SDK callback routes by variant.

//!

//! ## Wire shape

//!

//! `DispatchOutcome` crosses the certified-callback boundary on the in-Lyquid

//! self-dispatch path: `Succeeded { receipt_output_json: String }` carries the

//! audit-anchor payload as opaque JSON (the SDK doesn't unpack typed adapter output),

//! and the four non-Succeeded variants carry only `reason: String`. The actual cert

//! payload also embeds `op_id_hex` and `observed_retry_count` for the stale-callback

//! fingerprint (see `apply_dispatch_outcome` in `workflow_helpers`).

use serde::{Deserialize, Serialize};

/// SDK-enforced cap on automatic retries triggered by `DispatchOutcome::RetryablePrePayment`.

/// Service code that legitimately needs different bounds should re-litigate in design

/// review; until then, every self-dispatch service shares this cap.

pub const MAX_PREPAYMENT_RETRY_ATTEMPTS: u32 = 3;

/// Classification of a single self-dispatch attempt's outcome, produced by the instance

/// function and routed by the SDK to the matching `AgentEvent` writer.

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]

#[serde(tag = "kind")]

pub enum DispatchOutcome {

    /// Adapter ran to completion. `receipt_output_json` is the audit-anchor payload that

    /// becomes `Receipt.output` after the service's domain-side schema check. Maps to

    /// `AgentEvent::OperationSucceeded` -> `Finished(Succeeded)`.

    Succeeded { receipt_output_json: String },

    /// Pre-payment / pre-side-effect transient failure (5xx, transport, etc.). Safe to

    /// re-attempt with the SAME idempotency_key. Maps to `AgentEvent::OperationRetried` ->

    /// `Running { op_id: Some(_) }`. A service callback that receives

    /// `DispatchAction::Retried` can re-fire `dispatch_pending_*` with

    /// `TriggerMode::Commit`.

    ///

    /// **`attempt` is intentionally NOT in the variant.** Instance-fn-supplied attempt

    /// counts can't be trusted (a buggy adapter could loop past the cap). The SDK callback

    /// derives `prev_attempt + 1` from the workflow's event history (count of prior

    /// `OperationRetried` events for the current `op_id`) and enforces

    /// [`MAX_PREPAYMENT_RETRY_ATTEMPTS`] there.

    RetryablePrePayment { reason: String },

    /// Side effect MAY have happened; settlement state is uncertain (post-payment

    /// transport failure, missing or undecodable confirmation, etc.). Maps to

    /// `AgentEvent::OperationAmbiguous` -> `Blocked(OperationAmbiguous)`. Workflow requires

    /// an explicit `retry_*_dispatch` ABI call to re-attempt - the service does not

    /// auto-retry because the counterparty may have already settled.

    Ambiguous { reason: String },

    /// Permanent rejection; no side effect occurred. Caller bug (validation failure,

    /// policy violation). Maps to `AgentEvent::OperationFailed` -> `Finished(Failed)`.

    /// Workflow is terminal.

    Failed { reason: String },

    /// Side effect happened in a way that needs human disambiguation. Rare. Maps to

    /// `AgentEvent::OperationRequiresHuman` -> `Blocked(HumanInputRequired)`.

    RequiresHuman { reason: String },

}

impl DispatchOutcome {

    /// Stable variant tag for logging / diagnostics. Mirrors the serde `kind` discriminant.

    pub fn variant_name(&self) -> &'static str {

        match self {

            Self::Succeeded { .. } => "Succeeded",

            Self::RetryablePrePayment { .. } => "RetryablePrePayment",

            Self::Ambiguous { .. } => "Ambiguous",

            Self::Failed { .. } => "Failed",

            Self::RequiresHuman { .. } => "RequiresHuman",

        }

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn round_trip_succeeded() {

        let out = DispatchOutcome::Succeeded {

            receipt_output_json: r#"{"tx_hash":"0xabc"}"#.into(),

        };

        let s = serde_json::to_string(&out).unwrap();

        assert!(s.contains(r#""kind":"Succeeded""#));

        let decoded: DispatchOutcome = serde_json::from_str(&s).unwrap();

        assert_eq!(decoded, out);

    }

    #[test]

    fn round_trip_retryable() {

        let out = DispatchOutcome::RetryablePrePayment {

            reason: "5xx from gateway".into(),

        };

        let s = serde_json::to_string(&out).unwrap();

        assert!(s.contains(r#""kind":"RetryablePrePayment""#));

        let decoded: DispatchOutcome = serde_json::from_str(&s).unwrap();

        assert_eq!(decoded, out);

    }

    #[test]

    fn round_trip_ambiguous() {

        let out = DispatchOutcome::Ambiguous {

            reason: "missing PAYMENT-RESPONSE".into(),

        };

        let decoded: DispatchOutcome = serde_json::from_str(&serde_json::to_string(&out).unwrap()).unwrap();

        assert_eq!(decoded, out);

    }

    #[test]

    fn round_trip_failed() {

        let out = DispatchOutcome::Failed {

            reason: "amount exceeds policy cap".into(),

        };

        let decoded: DispatchOutcome = serde_json::from_str(&serde_json::to_string(&out).unwrap()).unwrap();

        assert_eq!(decoded, out);

    }

    #[test]

    fn round_trip_requires_human() {

        let out = DispatchOutcome::RequiresHuman {

            reason: "double-debit detected".into(),

        };

        let decoded: DispatchOutcome = serde_json::from_str(&serde_json::to_string(&out).unwrap()).unwrap();

        assert_eq!(decoded, out);

    }

    #[test]

    fn variant_names_are_stable() {

        assert_eq!(

            DispatchOutcome::Succeeded {

                receipt_output_json: "{}".into()

            }

            .variant_name(),

            "Succeeded"

        );

        assert_eq!(

            DispatchOutcome::RetryablePrePayment { reason: "".into() }.variant_name(),

            "RetryablePrePayment"

        );

        assert_eq!(

            DispatchOutcome::Ambiguous { reason: "".into() }.variant_name(),

            "Ambiguous"

        );

        assert_eq!(DispatchOutcome::Failed { reason: "".into() }.variant_name(), "Failed");

        assert_eq!(

            DispatchOutcome::RequiresHuman { reason: "".into() }.variant_name(),

            "RequiresHuman"

        );

    }

}