canic_host/fleet_ensure/model/

mod.rs

//! Module: fleet_ensure::model
//!
//! Responsibility: own current-generation Fleet reconciliation state and conservation records.
//! Does not own: transport parsing, policy decisions, persistence, or IC effects.
//! Boundary: workflow persists these records before and after every effect.

mod serialization;

use serde::{Deserialize, Serialize};
use std::collections::BTreeMap;

pub const FLEET_ENSURE_SCHEMA_VERSION: u16 = 1;
pub const MAX_FLEET_ENSURE_CANISTERS: usize = 4_096;
pub const MAX_FLEET_ENSURE_PROTOCOL_STEPS: usize = 4_096;

/// One exact observed canister state used by planning and effect reconciliation.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct LiveCanister {
    pub canister_version: Option<u64>,
    pub controllers: Vec<String>,
    #[serde(with = "u128_text")]
    pub cycles: u128,
    pub module_sha256: Option<String>,
    pub principal: String,
    pub reinstall_required: bool,
    pub root_owned_lifecycle: Option<RootOwnedCanisterLifecycle>,
    pub status: CanisterRuntimeStatus,
}

/// Root-owned lifecycle of one explicitly seeded paid canister.

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum RootOwnedCanisterLifecycle {
    Claimed,
    Idle,
    /// Live PendingReset/Failed asset; funding belongs to pool reconciliation.
    Reconciling,
    /// Last exact current-generation balance retained while Root status is fenced.
    Retained,
    Store,
    Workload,
}

impl RootOwnedCanisterLifecycle {
    #[must_use]
    pub const fn label(self) -> &'static str {
        match self {
            Self::Claimed => "claimed",
            Self::Idle => "idle",
            Self::Reconciling => "reconciling",
            Self::Retained => "retained",
            Self::Store => "store",
            Self::Workload => "workload",
        }
    }
}

/// Management status relevant to reconciliation.

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CanisterRuntimeStatus {
    Running,
    Stopped,
    Stopping,
}

/// Complete live snapshot of the explicitly controlled Fleet estate.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct FleetObservation {
    pub additional_controlled_cycles: BTreeMap<String, u128>,
    pub canisters: BTreeMap<String, Option<LiveCanister>>,
    pub estate_funding_domains: BTreeMap<String, EstateFundingDomainObservation>,
    #[serde(with = "u128_text")]
    pub ledger_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub operator_cycles: u128,
    pub protocol_ready: BTreeMap<String, bool>,
}

/// Exact read-only observation of one Root-owned Cycles Ledger account.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstateFundingDomainObservation {
    #[serde(with = "option_u128_text")]
    pub balance_cycles: Option<u128>,
    pub cycles_ledger: String,
    pub pool: Option<EstatePoolInventoryObservation>,
    pub root_principal: Option<String>,
}

/// Complete protected Root-pool observation used for capacity and conservation.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstatePoolInventoryObservation {
    pub assets: Vec<EstatePoolAssetObservation>,
    pub maximum_size: u32,
    pub minimum_size: u32,
    pub pending_creation: Option<EstatePoolPendingCreationObservation>,
    #[serde(with = "u128_text")]
    pub readiness_floor_cycles: u128,
    #[serde(with = "u128_text")]
    pub creation_execution_margin_cycles: u128,
}

/// One non-Store physical asset retained by a Root pool.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstatePoolAssetObservation {
    pub creation_receipt: Option<EstatePoolCreationReceiptObservation>,
    #[serde(with = "u128_text")]
    pub cycles: u128,
    pub lifecycle: EstatePoolAssetLifecycle,
    pub origin: EstatePoolAssetOrigin,
    pub principal: String,
}

/// Exact autonomous-creation receipt exposed by the protected Root inventory.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstatePoolCreationReceiptObservation {
    pub block_index: u64,
    pub operation_id: String,
    pub cycles_ledger: String,
    #[serde(with = "u128_text")]
    pub ledger_amount_cycles: u128,
    #[serde(with = "u128_text")]
    pub ledger_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub readiness_floor_cycles: u128,
    #[serde(with = "u128_text")]
    pub creation_execution_margin_cycles: u128,
    #[serde(with = "u128_text")]
    pub management_creation_fee_cycles: u128,
    #[serde(with = "option_u128_text")]
    pub first_observed_cycles: Option<u128>,
}

/// Protected provenance of one Root-owned pool asset.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum EstatePoolAssetOrigin {
    InfrastructureStore,
    Created,
    Imported,
    Recycled,
}

/// Reviewed Root authority and lifecycle of a native pool funding target.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PoolFundingAuthority {
    pub root: String,
    pub lifecycle: EstatePoolAssetLifecycle,
}

/// Capacity-relevant lifecycle of one Root-owned pool asset.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum EstatePoolAssetLifecycle {
    Claimed,
    Failed,
    HandingOff,
    PendingReset,
    Ready,
    Recycling,
    Workload,
}

/// Exact in-flight creation occupying one slot in the Root pool.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstatePoolPendingCreationObservation {
    pub attempt_count: u32,
    #[serde(with = "option_u128_text")]
    pub available_cycles: Option<u128>,
    #[serde(with = "u128_text")]
    pub creation_amount_cycles: u128,
    pub created_principal: Option<String>,
    pub diagnostic: Option<EstatePoolCreationDiagnostic>,
    pub last_attempt_at_ns: Option<u64>,
    pub operation_id: String,
    #[serde(with = "option_u128_text")]
    pub required_cycles: Option<u128>,
    pub retry_at_ns: Option<u64>,
    #[serde(with = "option_u128_text")]
    pub shortfall_cycles: Option<u128>,
    pub uncertain_result: bool,
}

/// Typed reason retained by an autonomous pool creation that cannot advance.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum EstatePoolCreationDiagnostic {
    FundingRequired,
    LedgerCreationFailed,
    LedgerRejected,
    UnresolvedAfterLedgerWindow,
}

/// Maintained disposition of one configured canister.

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum DesiredPresence {
    Absent,
    Present,
}

/// Exact method used by a controlled source to transfer its cycles before retirement.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DrainAuthority {
    pub candid: String,
    pub method: String,
    pub destination: String,
    pub maximum_execution_burn_cycles: String,
}

/// Current desired state for one controlled canister.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DesiredCanister {
    #[serde(default)]
    pub canic_init: Option<DesiredCanisterInit>,
    #[serde(default)]
    pub controller_canisters: Vec<String>,
    pub controllers: Vec<String>,
    pub drain: Option<DrainAuthority>,
    pub initial_cycles: String,
    pub init_arg: Option<String>,
    pub init_candid: Option<String>,
    pub kind: DesiredCanisterKind,
    pub minimum_cycles: String,
    pub name: String,
    pub parent: Option<String>,
    pub presence: DesiredPresence,
    pub principal: Option<String>,
    #[serde(skip)]
    pub(crate) protocol_binding: Option<crate::protocol_binding::RegistryProtocolBinding>,
    pub replace: bool,
    pub subnet: String,
    pub wasm: Option<String>,
}

/// Canic-owned role class used to derive Fleet control-plane choreography.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum DesiredCanisterKind {
    Auxiliary,
    Component,
    Coordinator,
    Pool,
    Root,
    Store,
}

/// Canic-owned typed initialization role for one infrastructure canister.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case", tag = "role")]
pub enum DesiredCanisterInit {
    Coordinator,
    Root { root: String },
    Store { root: String },
}

/// One current-only idempotent protocol transition owned by the Fleet journal.
///
/// The three argument documents use Candid text. They may bind a dynamically
/// created canister with `{{principal:<logical-name>}}`, the retained operation
/// string with `{{operation_id}}`, or its 32-byte value with
/// `{{operation_id_blob}}`.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub(crate) struct DesiredProtocolStep {
    pub canister: String,
    pub candid: String,
    pub command_args: String,
    pub command_method: String,
    pub expected_status: String,
    pub maximum_execution_burn_cycles: String,
    pub name: String,
    pub status_args: String,
    pub status_method: String,
}

/// Current-only desired Fleet contract consumed by `canic fleet ensure`.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DesiredFleet {
    #[serde(default)]
    pub bootstrap: Option<DesiredFleetBootstrap>,
    pub canisters: Vec<DesiredCanister>,
    pub cycles_ledger: String,
    pub environment: String,
    pub fleet: String,
    pub ledger_fee_cycles: String,
    pub management_creation_fee_cycles: String,
    pub material_cycle_threshold: String,
    pub maximum_observation_burn_cycles: String,
    /// Observation stall bound and maximum paid attempts per fixture publication action.
    pub maximum_stalled_observations: u32,
    pub maximum_update_burn_cycles: String,
    pub operator: String,
    #[serde(default)]
    pub protocol: Option<DesiredFleetProtocol>,
    #[serde(skip)]
    pub(crate) protocol_steps: Vec<DesiredProtocolStep>,
    pub schema_version: u16,
    /// Logical name of the present controlled canister that owns retirement receipts.
    pub treasury: String,
}

/// Complete current-generation Canic initialization authority generated from App and Fleet input.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DesiredFleetBootstrap {
    /// Browser Principal namespace reviewed with this Fleet's admission input.
    #[serde(default)]
    pub admission_identity_origin: Option<String>,
    pub admission: canic_core::ids::FleetAdmissionPolicyTemplate,
    pub app: canic_core::ids::AppId,
    pub canonical_network_id: canic_core::ids::CanonicalNetworkId,
    pub component_deployment_configuration:
        canic_core::control_plane_support::config::ComponentDeploymentConfiguration,
    pub coordinator: String,
    pub coordinator_subnet: canic_core::ids::SubnetId,
    pub fleet_id: canic_core::ids::FleetId,
    pub fresh_estate: bool,
    pub release_build_id: canic_core::ids::ReleaseBuildId,
    pub root_funding: Option<canic_core::ids::FleetCoordinatorRootFundingPolicy>,
    pub roots: Vec<DesiredFleetBootstrapRoot>,
}

/// One Root/Store pair's generated immutable initialization authority.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DesiredFleetBootstrapRoot {
    pub canister_pool_imports: Vec<String>,
    pub component_admissions: Vec<canic_core::ids::ComponentSpecAdmission>,
    pub component_topology_digest: canic_core::ids::ComponentTopologyDigest,
    pub funding: canic_core::ids::FleetSubnetRootFundingAuthority,
    pub limits: canic_core::ids::FleetSubnetRootLimits,
    pub placement_subnet: canic_core::ids::SubnetId,
    pub root: String,
    pub store: String,
}

/// Current Canic-owned control-plane intent compiled from one App topology.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DesiredFleetProtocol {
    /// Canonical application `canic.toml` used to compile Component topology.
    pub app_config: String,
    /// Exact initial group placements assigned to declared Root roles.
    pub component_group_placements: Vec<DesiredComponentGroupPlacement>,
    /// Exact Coordinator Candid used only by Canic's typed protocol adapter.
    pub coordinator_candid: String,
    /// Exact Root Candid used only by Canic's typed protocol adapter.
    pub root_candid: String,
    /// Exact Store Candid used only by Canic's typed protocol adapter.
    pub store_candid: String,
}

/// One typed initial Component Group placement owned by Canic policy.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct DesiredComponentGroupPlacement {
    pub deployment: String,
    pub ordinal: u32,
    pub root: String,
}

/// Content identities resolved from current desired-state artifact paths by ops.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct DesiredFleetArtifacts {
    pub continuation: Option<FleetEnsureContinuationAuthority>,
    pub drain_candid_sha256_by_canister: BTreeMap<String, String>,
    pub init_arg_sha256_by_canister: BTreeMap<String, String>,
    pub init_candid_sha256_by_canister: BTreeMap<String, String>,
    pub wasm_sha256_by_canister: BTreeMap<String, String>,
    pub startup_funding_by_root: BTreeMap<String, StartupFundingRequirement>,
    pub(crate) protocol_by_step: BTreeMap<String, ProtocolArtifactDigests>,
}

/// Configuration-bound startup demand; live grant usage and execution are separate inputs.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct StartupFundingRequirement {
    /// Root-local upper bound from the selected continuation artifact catalogue.
    pub maximum_continuation_steps: u32,
    pub minimum_native_cycles: u128,
    pub unfunded_role: Option<StartupRoleShortfall>,
}

/// A role whose fresh lifetime allowance or disabled top-up cannot supply initial demand.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct StartupRoleShortfall {
    pub role: canic_core::ids::CanisterRole,
    #[serde(with = "u128_text")]
    pub cycles: u128,
}

/// Content identities for one declarative protocol transition.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub(crate) struct ProtocolArtifactDigests {
    pub candid_sha256: String,
    pub command_args_sha256: String,
    pub expected_status_sha256: String,
    pub status_args_sha256: String,
}

/// Validated numeric funding bounds for one desired canister.

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct CanisterCyclePolicy {
    #[serde(with = "u128_text")]
    pub initial_cycles: u128,
    #[serde(with = "u128_text")]
    pub minimum_cycles: u128,
}

/// Exact Root authority and Candid contract for replicated reinstall observations.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ReinstallHistoryWitness {
    /// Exact installed module retained before this reviewed reinstall.
    pub prior_module_sha256: String,
    pub authority: RootManagementBinding,
    pub candid: String,
    pub candid_sha256: String,
    /// Exact replacement Root admitted only while reconciling its own durable intent.
    #[serde(deserialize_with = "serialization::required_option")]
    pub replacement: Option<Box<ReinstallRootWitnessRecord>>,
}

/// Exact management identity and protocol for the selected replacement Root.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ReinstallRootWitnessRecord {
    pub authority: RootManagementBinding,
    pub candid: String,
    pub candid_sha256: String,
}

/// Exact effect kind retained before execution.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case", tag = "kind")]
pub enum EnsureAction {
    /// Seal one authority's mutation and timer owners before inventory capture.
    SealAuthority {
        candid: String,
        candid_sha256: String,
        authority_kind: DesiredCanisterKind,
        name: String,
        principal: String,
    },
    Create {
        controller_canisters: Vec<String>,
        controllers: Vec<String>,
        created_at_time: u64,
        ledger: String,
        name: String,
        #[serde(with = "u128_text")]
        requested_initial_cycles: u128,
        subnet: String,
    },
    Delete {
        #[serde(with = "u128_text")]
        maximum_remaining_cycles: u128,
        name: String,
        principal: String,
    },
    Fund {
        /// Exact Root and lifecycle for protected inspection of a pool funding target.
        #[serde(deserialize_with = "serialization::required_option")]
        pool_funding: Option<PoolFundingAuthority>,
        #[serde(with = "u128_text")]
        amount: u128,
        created_at_time: u64,
        #[serde(with = "u128_text")]
        expected_post_cycles: u128,
        #[serde(with = "u128_text")]
        funding_deficit_cycles: u128,
        #[serde(with = "u128_text")]
        funding_margin_cycles: u128,
        ledger: String,
        name: String,
        principal: String,
    },
    FundEstate {
        #[serde(with = "u128_text")]
        amount: u128,
        created_at_time: u64,
        #[serde(with = "u128_text")]
        expected_post_cycles: u128,
        ledger: String,
        #[serde(with = "u128_text")]
        ledger_fee_cycles: u128,
        name: String,
        principal: String,
    },
    Install {
        canic_init: Option<DesiredCanisterInit>,
        #[serde(deserialize_with = "serialization::required_option")]
        reinstall_witness: Option<Box<ReinstallHistoryWitness>>,
        init_arg: Option<String>,
        init_arg_sha256: Option<String>,
        init_candid: Option<String>,
        init_candid_sha256: Option<String>,
        mode: InstallMode,
        name: String,
        principal: String,
        wasm: String,
        wasm_sha256: String,
    },
    FleetProtocol {
        action: Box<CurrentFleetProtocolAction>,
        candid: String,
        candid_sha256: String,
        #[serde(with = "u128_text")]
        maximum_execution_burn_cycles: u128,
        name: String,
        principal: String,
    },
    Protocol {
        candid: String,
        candid_sha256: String,
        command_args: String,
        command_args_sha256: String,
        command_method: String,
        expected_status: String,
        expected_status_sha256: String,
        #[serde(with = "u128_text")]
        maximum_execution_burn_cycles: u128,
        name: String,
        principal: String,
        status_args: String,
        status_args_sha256: String,
        status_method: String,
    },
    SetControllers {
        controller_canisters: Vec<String>,
        controllers: Vec<String>,
        name: String,
        principal: String,
    },
    Start {
        name: String,
        principal: String,
    },
    Stop {
        name: String,
        principal: String,
    },
    Transfer {
        #[serde(with = "u128_text")]
        amount: u128,
        candid: String,
        candid_sha256: String,
        destination: String,
        #[serde(with = "u128_text")]
        maximum_execution_burn_cycles: u128,
        method: String,
        name: String,
        principal: String,
    },
}

impl EnsureAction {
    /// Paid publication attempts retained in the reviewed action, independent of observations.
    pub(crate) fn fixture_publication_attempt_limit(&self) -> Option<u32> {
        if let Self::FleetProtocol { action, .. } = self {
            match action.as_ref() {
                CurrentFleetProtocolAction::PrepareStoreFixture {
                    maximum_attempts, ..
                }
                | CurrentFleetProtocolAction::PublishStoreFixtureChunk {
                    maximum_attempts, ..
                } => {
                    return Some(*maximum_attempts);
                }
                _ => {}
            }
        }
        None
    }

    #[must_use]
    pub fn name(&self) -> &str {
        match self {
            Self::SealAuthority { name, .. }
            | Self::Create { name, .. }
            | Self::Delete { name, .. }
            | Self::FleetProtocol { name, .. }
            | Self::Fund { name, .. }
            | Self::FundEstate { name, .. }
            | Self::Install { name, .. }
            | Self::Protocol { name, .. }
            | Self::SetControllers { name, .. }
            | Self::Start { name, .. }
            | Self::Stop { name, .. }
            | Self::Transfer { name, .. } => name,
        }
    }
}

/// Closed current-only Canic choreography emitted from roles and topology.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case", tag = "kind")]
#[expect(
    clippy::large_enum_variant,
    reason = "each exact typed action is boxed by EnsureAction before durable retention"
)]
pub enum CurrentFleetProtocolAction {
    /// Verify host-created local supply without authorizing mainnet-only refill.
    ObservePoolReadiness {
        minimum_ready: u32,
        readiness_floor: canic_core::cdk::types::Cycles,
    },
    MaintainPoolReadiness {
        maximum_updates: u32,
        minimum_ready: u32,
        readiness_floor: canic_core::cdk::types::Cycles,
    },
    ReconcilePoolAsset {
        request: canic_core::dto::pool::PoolCanisterRequest,
        minimum_cycles: canic_core::cdk::types::Cycles,
    },
    ActivateRegistry {
        expected_registry: canic_core::dto::fleet_registry::FleetRegistry,
        expected_version: canic_core::dto::fleet_registry::FleetRegistryVersion,
        request: canic_core::dto::fleet_registry::FleetRegistryActivationRequest,
    },
    ActivateRegistryMirror {
        expected: canic_core::dto::fleet_registry::FleetSubnetRootRegistryMirrorActivationResponse,
        request: canic_core::dto::fleet_registry::FleetSubnetRootRegistrySyncRequest,
    },
    AdoptStore {
        request: canic_core::dto::fleet_subnet_root::FleetSubnetWasmStoreAdoptionRequest,
    },
    BootstrapStore {
        expected: canic_core::dto::root_store::RootStoreBootstrapResponse,
        request: canic_core::dto::root_store::RootStoreBootstrapRequest,
    },
    JoinRoot {
        expected_registry: canic_core::dto::fleet_registry::FleetRegistry,
        expected_version: canic_core::dto::fleet_registry::FleetRegistryVersion,
        request: canic_core::dto::fleet_registry::FleetSubnetRootJoinRequest,
    },
    PrepareStoreFixture {
        /// Total paid calls admitted by this exact reviewed action.
        maximum_attempts: u32,
        request: canic_core::dto::root_store::RootStoreFixturePrepareRequest,
        source: canic_core::dto::root_store::RootStoreFixture,
        store: candid::Principal,
    },
    PublishStoreFixtureChunk {
        /// Total paid calls admitted by this exact reviewed action.
        maximum_attempts: u32,
        request: canic_core::dto::fixture_provisioning::FixtureChunkUpload,
        expected: canic_core::dto::fixture_provisioning::FixtureSourceStatus,
        source_bytes: u64,
    },
    PrepareStoreChunkSet {
        request: canic_control_plane::dto::template::TemplateChunkSetPrepareInput,
    },
    PrepareComponentRegistry {
        expected: canic_core::dto::component_registry::RootComponentRegistryStatusResponse,
        request: canic_core::dto::component_registry::RootComponentRegistryPreparationRequest,
    },
    ProvisionComponents {
        plan_hash: [u8; 32],
        request: canic_core::dto::component_provisioning::FleetComponentProvisioningPrepareRequest,
    },
    PublishStoreChunk {
        request: canic_control_plane::dto::template::TemplateChunkInput,
    },
    StageStoreManifest {
        request: canic_control_plane::dto::template::TemplateManifestInput,
    },
    SynchronizeRegistry {
        expected: canic_core::dto::fleet_registry::FleetSubnetRootRegistrySyncResponse,
        request: canic_core::dto::fleet_registry::FleetSubnetRootRegistrySyncRequest,
    },
}

impl CurrentFleetProtocolAction {
    /// Retained payload shared by publication reporting and the plan content store.
    pub(crate) fn publication_bytes(&self) -> Option<&[u8]> {
        match self {
            Self::PublishStoreChunk { request } => Some(&request.bytes),
            Self::PublishStoreFixtureChunk { request, .. } => Some(&request.bytes),
            _ => None,
        }
    }

    pub(crate) const fn publication_bytes_mut(&mut self) -> Option<&mut Vec<u8>> {
        match self {
            Self::PublishStoreChunk { request } => Some(&mut request.bytes),
            Self::PublishStoreFixtureChunk { request, .. } => Some(&mut request.bytes),
            _ => None,
        }
    }

    /// Role that exclusively owns this current control-plane transition.
    #[must_use]
    pub const fn target_kind(&self) -> DesiredCanisterKind {
        match self {
            Self::ActivateRegistry { .. }
            | Self::JoinRoot { .. }
            | Self::ProvisionComponents { .. } => DesiredCanisterKind::Coordinator,
            Self::ActivateRegistryMirror { .. }
            | Self::ReconcilePoolAsset { .. }
            | Self::MaintainPoolReadiness { .. }
            | Self::ObservePoolReadiness { .. }
            | Self::AdoptStore { .. }
            | Self::BootstrapStore { .. }
            | Self::PrepareStoreFixture { .. }
            | Self::PrepareComponentRegistry { .. }
            | Self::SynchronizeRegistry { .. } => DesiredCanisterKind::Root,
            Self::PrepareStoreChunkSet { .. }
            | Self::PublishStoreChunk { .. }
            | Self::PublishStoreFixtureChunk { .. }
            | Self::StageStoreManifest { .. } => DesiredCanisterKind::Store,
        }
    }

    /// Durable operation identity when this transition has a protocol-owned replay key.
    #[must_use]
    pub const fn operation_id(&self) -> Option<[u8; 32]> {
        match self {
            Self::ActivateRegistry { .. }
            | Self::ReconcilePoolAsset { .. }
            | Self::MaintainPoolReadiness { .. }
            | Self::ObservePoolReadiness { .. }
            | Self::JoinRoot { .. }
            | Self::PrepareComponentRegistry { .. }
            | Self::PrepareStoreFixture { .. }
            | Self::PrepareStoreChunkSet { .. }
            | Self::PublishStoreChunk { .. }
            | Self::PublishStoreFixtureChunk { .. }
            | Self::StageStoreManifest { .. } => None,
            Self::ActivateRegistryMirror { request, .. }
            | Self::SynchronizeRegistry { request, .. } => Some(request.operation_id),
            Self::AdoptStore { request } => Some(request.operation_id),
            Self::BootstrapStore { request, .. } => Some(request.operation_id),
            Self::ProvisionComponents { request, .. } => Some(request.operation_id),
        }
    }
}

/// Explicit Wasm installation mode selected from live state.

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum InstallMode {
    Install,
    Reinstall,
}

/// Planned disposition and effects for one controlled canister.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CanisterPlan {
    pub actions: Vec<EnsureAction>,
    pub disposition: CanisterDisposition,
    pub name: String,
    #[serde(with = "u128_text")]
    pub observed_cycles: u128,
    #[serde(deserialize_with = "serialization::required_option")]
    pub principal: Option<String>,
}

/// Operator-visible canister disposition.

#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum CanisterDisposition {
    Create,
    Delete,
    Replace,
    Reinstall,
    Reuse,
}

/// Exact cycle conservation proof reviewed before apply.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct CycleConservation {
    pub estate_funding_domains: Vec<EstateFundingDomainPlan>,
    #[serde(with = "u128_text")]
    pub expected_post_operation_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_execution_burn_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_new_funding_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_operator_debit_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_unavoidable_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub observed_controlled_cycles: u128,
    #[serde(with = "u128_text")]
    pub retained_in_reused_canisters_cycles: u128,
    #[serde(with = "u128_text")]
    pub scheduled_transfer_cycles: u128,
}

/// Reviewed autonomous-creation exposure for one Root-owned Cycles Ledger account.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstateFundingDomainPlan {
    pub allocated_workloads: u32,
    #[serde(with = "option_u128_text")]
    pub available_cycles: Option<u128>,
    pub available_pool_slots: u32,
    #[serde(with = "u128_text")]
    pub creation_amount_cycles: u128,
    pub cycles_ledger: String,
    #[serde(with = "u128_text")]
    pub creation_execution_margin_cycles: u128,
    #[serde(with = "u128_text")]
    pub readiness_floor_cycles: u128,
    pub eligible_ready_pool_assets: u32,
    pub initial_pool_assets: Vec<String>,
    #[serde(with = "u128_text")]
    pub ledger_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub management_creation_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_creation_debit_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_creation_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_funding_cycles: u128,
    pub occupied_pool_assets: u32,
    pub pending_creation_count: u32,
    pub pending_creation: Option<EstatePoolPendingCreationObservation>,
    pub pool_maximum_size: u32,
    pub planned_initial_workloads: u32,
    pub required_creation_count: u32,
    pub root: String,
    pub root_principal: Option<String>,
    #[serde(with = "u128_text")]
    pub shortfall_cycles: u128,
}

/// Durable no-effect pause for one underfunded Root-owned creation domain.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EstateFundingRequiredRecord {
    pub attempt_count: Option<u32>,
    #[serde(with = "u128_text")]
    pub available_cycles: u128,
    #[serde(with = "u128_text")]
    pub creation_amount_cycles: u128,
    pub cycles_ledger: String,
    #[serde(with = "u128_text")]
    pub creation_execution_margin_cycles: u128,
    #[serde(with = "u128_text")]
    pub readiness_floor_cycles: u128,
    #[serde(with = "u128_text")]
    pub ledger_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub management_creation_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_creation_debit_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_creation_fee_cycles: u128,
    pub operation_id: String,
    pub pending_creation_operation_id: Option<String>,
    pub plan_sha256: String,
    pub required_creation_count: u32,
    pub root: String,
    pub root_principal: String,
    pub last_attempt_at_ns: Option<u64>,
    pub retry_at_ns: Option<u64>,
    #[serde(with = "u128_text")]
    pub shortfall_cycles: u128,
}

/// Terminal measured conservation result from the exact applied operation.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
pub struct ActualCycleConservation {
    #[serde(with = "u128_text")]
    pub estate_funding_cycles: u128,
    #[serde(with = "u128_text")]
    pub exact_estate_creation_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub exact_unavoidable_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub final_controlled_cycles: u128,
    #[serde(with = "u128_text")]
    pub measured_execution_burn_cycles: u128,
    #[serde(with = "u128_text")]
    pub observed_starting_cycles: u128,
    /// Bounded net credits observed across exact activation-recovery Stop receipts.
    /// This observation does not classify their origin as refunds or funding.
    #[serde(with = "u128_text")]
    pub observed_settlement_credit_cycles: u128,
    #[serde(with = "u128_text")]
    pub operator_debit_cycles: u128,
    #[serde(with = "u128_text")]
    pub received_new_funding_cycles: u128,
}

/// Sum the separately reviewed Create execution and first-observation bounds.
/// Overflow cannot grant an unbounded allowance.
pub(crate) const fn creation_observation_burn(observation: u128, update: u128) -> Option<u128> {
    observation.checked_add(update)
}

/// Whether a newly created canister's first balance is covered by its reviewed
/// Create execution plus first-observation allowance. The Ledger receipt owns
/// the requested amount; live status owns the exact retained balance.
pub(crate) const fn create_balance_is_terminal(
    actual_cycles: Option<u128>,
    requested_initial_cycles: u128,
    maximum_observation_burn_cycles: u128,
) -> bool {
    let Some(actual_cycles) = actual_cycles else {
        return false;
    };
    if actual_cycles > requested_initial_cycles {
        return false;
    }
    requested_initial_cycles - actual_cycles <= maximum_observation_burn_cycles
}

/// Exact normalized desired input retained by one in-progress operation.
///
/// The public desired document cannot declare internal protocol steps. This
/// wrapper persists those Canic-owned steps without making them an input
/// surface and restores them before any resumed observation or effect.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ReviewedDesiredFleetRecord {
    desired: DesiredFleet,
}

impl ReviewedDesiredFleetRecord {
    pub(crate) fn capture(desired: &DesiredFleet) -> Self {
        Self {
            desired: desired.clone(),
        }
    }

    /// Borrow the complete normalized desired input, including internal steps.
    #[must_use]
    pub const fn desired(&self) -> &DesiredFleet {
        &self.desired
    }

    /// Consume the retained authority as the complete normalized desired input.
    #[must_use]
    pub fn into_desired(self) -> DesiredFleet {
        self.desired
    }
}

#[derive(Deserialize, Serialize)]
struct ReviewedDesiredFleetRecordProjection {
    desired: DesiredFleet,
    protocol_steps: Vec<DesiredProtocolStep>,
}

impl Serialize for ReviewedDesiredFleetRecord {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        ReviewedDesiredFleetRecordProjection {
            desired: self.desired.clone(),
            protocol_steps: self.desired.protocol_steps.clone(),
        }
        .serialize(serializer)
    }
}

impl<'de> Deserialize<'de> for ReviewedDesiredFleetRecord {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        let mut projection = ReviewedDesiredFleetRecordProjection::deserialize(deserializer)?;
        projection.desired.protocol_steps = projection.protocol_steps;
        Ok(Self {
            desired: projection.desired,
        })
    }
}

/// Immutable reviewed plan produced from desired state plus one live observation.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetEnsurePlan {
    /// Informational dependent work; grants no funding or effect authority.
    #[serde(deserialize_with = "serialization::required_option")]
    pub recovery_review: Option<Box<FleetRecoveryReview>>,
    /// One explicit selected-build wipe, retained through preparation and full convergence.
    #[serde(deserialize_with = "serialization::required_option")]
    pub reinstall: Option<Box<FleetReinstallRecord>>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub continuation: Option<FleetEnsureContinuationAuthority>,
    pub canisters: Vec<CanisterPlan>,
    pub conservation: CycleConservation,
    pub desired_sha256: String,
    pub environment: String,
    pub fleet: String,
    pub operation_id: String,
    pub plan_sha256: String,
    pub planned_at_time: u64,
    pub protocol_actions: Vec<EnsureAction>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub root_start_authority: Option<Box<RetainedRootStartAuthorityRecord>>,
    /// Exact installed Root authority approved for replacement by this plan.
    pub root_reinstall_bindings: Vec<RootManagementBinding>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub reviewed_desired: Option<Box<ReviewedDesiredFleetRecord>>,
    pub schema_version: u16,
    pub scope: FleetEnsurePlanScope,
    /// Exact terminal operation that owns the currently active Registry observation.
    #[serde(deserialize_with = "serialization::required_option")]
    pub terminal_inventory_operation_id: Option<String>,
}

/// Exact authority scope of one current Fleet Ensure plan.
#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FleetEnsurePlanScope {
    /// Complete desired-state convergence after all protected roles are observable.
    #[default]
    Full,
    /// Seal current allocation before reviewing the complete physical reset closure.
    ReinstallPreparation,
    /// Exact reviewed Root reset before current protected interfaces become available.
    RootReinstallPrerequisite,
    /// Exact management-authorized Root Start prerequisite.
    RootStartPrerequisite,
}

impl FleetEnsurePlanScope {
    /// Stable operator-facing name shared by text and JSON reports.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Full => "full",
            Self::ReinstallPreparation => "reinstall_preparation",
            Self::RootReinstallPrerequisite => "root_reinstall_prerequisite",
            Self::RootStartPrerequisite => "root_start_prerequisite",
        }
    }
}

/// Exact source estate and selected target authority for one requested database wipe.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetReinstallRecord {
    /// Selected build content identity bound before preparation effects.
    #[serde(deserialize_with = "serialization::required_option")]
    pub target_artifacts_sha256: Option<String>,
    /// Completed source authority; partial activation retains its separate evidence.
    #[serde(deserialize_with = "serialization::required_option")]
    pub source: Option<Box<FleetReinstallSourceRecord>>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub activation_reset: Option<Box<FleetActivationResetRecord>>,
    pub operation_id: String,
    pub source_operation_id: String,
    pub authorities: Vec<RootManagementBinding>,
    /// Empty during preparation; the full plan binds every sealed physical asset.
    pub assets: Vec<FleetReinstallAssetRecord>,
}

/// Immutable completed-source input and artifact identities retained before sealing.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetReinstallSourceRecord {
    pub reviewed_desired: ReviewedDesiredFleetRecord,
    pub wasm_sha256_by_canister: BTreeMap<String, String>,
    pub candid_sha256_by_path: BTreeMap<String, String>,
}

/// Exact retained source bytes and issued protocol effects inspected for activation recovery.
/// The source plan label is a journal reference, not executable replacement authority.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetActivationSourceRecord {
    pub infrastructure: Vec<RootManagementBinding>,
    pub operator: String,
    pub cycles_ledger: String,
    #[serde(with = "u128_text")]
    pub initial_controlled_cycles: u128,
    #[serde(with = "u128_text")]
    pub maximum_execution_burn_cycles: u128,
    #[serde(with = "u128_text_map")]
    pub initial_estate_funding_cycles_by_root: BTreeMap<String, u128>,
    pub operation_id: String,
    pub plan_sha256: String,
    pub plan_document_sha256: String,
    pub journal_document_sha256: String,
    pub state_document_sha256: String,
    pub provisioning: EnsureAction,
    pub registry_preparations: Vec<EnsureAction>,
    pub stores: Vec<FleetProtocolReadRecord>,
}

/// Reviewed inactive activation evidence retained through preparation and reset.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetActivationResetRecord {
    #[serde(deserialize_with = "serialization::required_option")]
    pub preparation: Option<ActivationPreparationEvidenceRecord>,
    pub source: FleetActivationSourceRecord,
    pub roots: Vec<RootActivationResetRecord>,
}

/// Exact completed preparation documents retained before the separate Root-reset review.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ActivationPreparationEvidenceRecord {
    pub plan_document_sha256: String,
    pub journal_document_sha256: String,
}

/// Durable local handoff intent; completion is recorded before remote effects can run.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ActivationResetAdoptionRecord {
    pub source_plan_sha256: String,
    pub source_journal_sha256: String,
    pub source_state_sha256: String,
    pub replacement_plan_sha256: String,
    pub replacement_journal_sha256: String,
    pub complete: bool,
}

/// Exact retained Candid and target used only to observe a source protocol owner.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetProtocolReadRecord {
    pub candid: String,
    pub candid_sha256: String,
    pub principal: String,
}

/// Inactive Root identity and sealed initial membership observed before a reset.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RootActivationResetRecord {
    pub root: String,
    pub activation_operation_id: [u8; 32],
    pub inventory_hash: [u8; 32],
    pub provisioning_receipt_hash: [u8; 32],
    pub component_count: u32,
    pub managed_descendants: u32,
}

/// One controlled physical asset in the sealed reset closure.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetReinstallAssetRecord {
    pub controllers: Vec<String>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub module_sha256: Option<String>,
    pub principal: String,
    pub root: String,
    pub subnet: String,
}

/// Exact management-canister observation of one configured Fleet Subnet Root.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RootManagementCanisterObservation {
    pub live: LiveCanister,
    pub name: String,
    pub subnet: String,
}

/// Read-only management evidence available before protected Root ingress can run.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct RootManagementObservation {
    pub operator_cycles: u128,
    pub roots: BTreeMap<String, RootManagementCanisterObservation>,
}

/// Exact installed Root identity, module and controller authority observed through management.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RootManagementBinding {
    pub controllers: Vec<String>,
    pub name: String,
    pub module_sha256: String,
    pub principal: String,
    pub subnet: String,
}

/// Generator-owned authority for management-bound Root prerequisites before protected observation.
///
/// The separately reviewed plan permits only Start for the exact observed module.
/// It cannot authorize replacement, installation or reuse across releases.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RetainedRootStartAuthorityRecord {
    pub authority_sha256: String,
    pub environment: String,
    pub fleet: String,
    pub fleet_id: canic_core::ids::FleetId,
    pub roots: Vec<RootManagementBinding>,
    pub schema_version: u16,
}

impl RetainedRootStartAuthorityRecord {
    pub(crate) fn seal(&mut self) {
        self.authority_sha256 = self.expected_sha256();
    }

    pub(crate) fn has_valid_digest(&self) -> bool {
        self.authority_sha256 == self.expected_sha256()
    }

    fn expected_sha256(&self) -> String {
        let mut canonical = self.clone();
        canonical.authority_sha256.clear();
        let bytes = serde_json::to_vec(&canonical)
            .expect("retained Root-start authority is JSON serializable");
        let mut framed = b"canic:fleet-ensure:root-start-authority:v1".to_vec();
        framed.extend_from_slice(&u64::try_from(bytes.len()).unwrap_or(u64::MAX).to_be_bytes());
        framed.extend_from_slice(&bytes);
        canic_core::cdk::utils::hash::sha256_hex(&framed)
    }
}

/// Durable state of one planned effect.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum EffectState {
    Applied,
    Intent,
    Issued,
}

/// Durable outcome of one reviewed Fleet ensure operation.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FleetEnsureCompletion {
    Converged,
    /// Authorities are sealed; the full reset still requires review and execution.
    Prepared,
    InProgress,
    ReplanRequired,
}

/// Durable intent/result record for one action.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct EffectRecord {
    /// Root maintenance calls whose intent was persisted, including lost responses.
    pub maintenance_attempts: u32,
    /// Fixture publication calls reserved before issue, including failed or lost replies.
    pub publication_attempts: u32,
    pub action_sha256: String,
    #[serde(deserialize_with = "serialization::required_option")]
    pub created_principal: Option<String>,
    #[serde(with = "option_u128_text")]
    pub destination_post_cycles: Option<u128>,
    #[serde(with = "option_u128_text")]
    pub destination_pre_cycles: Option<u128>,
    #[serde(with = "option_u128_text")]
    pub post_cycles: Option<u128>,
    #[serde(with = "option_u128_text")]
    pub pre_cycles: Option<u128>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub pre_canister_version: Option<u64>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub progress_identity: Option<String>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub receipt: Option<String>,
    pub state: EffectState,
}

/// Complete retained/live balance tuple for one exact retirement transfer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct RetirementTransferBalances {
    pub destination_after: u128,
    pub destination_before: u128,
    pub maximum_execution_burn: u128,
    pub source_after: u128,
    pub source_before: u128,
    pub transfer_amount: u128,
}

/// Model-owned result of reconciling both controlled sides of a retirement transfer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RetirementTransferReconciliation {
    Conserved {
        destination_credit: u128,
        source_debit: u128,
    },
    Pending,
}

/// Exact invariant failure while reconciling a retirement transfer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RetirementTransferInvariantError {
    ArithmeticOverflow,
    BalanceMovedInInvalidDirection,
    Unbalanced {
        destination_credit: u128,
        maximum_source_debit: u128,
        source_debit: u128,
    },
}

/// Require a matching source debit and treasury credit before retirement may continue.
pub fn reconcile_retirement_transfer(
    balances: RetirementTransferBalances,
) -> Result<RetirementTransferReconciliation, RetirementTransferInvariantError> {
    let source_debit = balances
        .source_before
        .checked_sub(balances.source_after)
        .ok_or(RetirementTransferInvariantError::BalanceMovedInInvalidDirection)?;
    let destination_credit = balances
        .destination_after
        .checked_sub(balances.destination_before)
        .ok_or(RetirementTransferInvariantError::BalanceMovedInInvalidDirection)?;
    let maximum_source_debit = balances
        .transfer_amount
        .checked_add(balances.maximum_execution_burn)
        .ok_or(RetirementTransferInvariantError::ArithmeticOverflow)?;
    if source_debit == 0 && destination_credit == 0 {
        return Ok(RetirementTransferReconciliation::Pending);
    }
    if source_debit >= balances.transfer_amount
        && source_debit <= maximum_source_debit
        && destination_credit == balances.transfer_amount
    {
        return Ok(RetirementTransferReconciliation::Conserved {
            destination_credit,
            source_debit,
        });
    }
    Err(RetirementTransferInvariantError::Unbalanced {
        destination_credit,
        maximum_source_debit,
        source_debit,
    })
}

/// Current discovered identities retained only to seed live observation.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetEnsureStateRecord {
    #[serde(deserialize_with = "serialization::required_option")]
    pub active_registry: Option<canic_core::dto::fleet_registry::FleetRegistry>,
    /// Exact applied action identities for the adjacent completed reinstalls.
    pub completed_reinstall_action_sha256: BTreeMap<String, String>,
    /// Exact operation owning the adjacent completed-reinstall thresholds.
    #[serde(deserialize_with = "serialization::required_option")]
    pub completed_reinstall_operation_id: Option<String>,
    /// Pre-effect version thresholds for exact journal-proved reinstalls in the
    /// immediately preceding nonterminal operation.
    pub completed_reinstalls: BTreeMap<String, u64>,
    pub fleet: String,
    pub pending_principals: BTreeMap<String, String>,
    pub principals: BTreeMap<String, String>,
    pub retained_cycles_by_principal: BTreeMap<String, u128>,
    pub schema_version: u16,
    pub topology: BTreeMap<String, FleetEnsureTopologyRecord>,
}

/// Current typed topology retained independently from any historical install evidence.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetEnsureTopologyRecord {
    pub kind: DesiredCanisterKind,
    #[serde(deserialize_with = "serialization::required_option")]
    pub module_hash: Option<String>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub parent: Option<String>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub protocol_binding: Option<crate::protocol_binding::RegistryProtocolBinding>,
    #[serde(deserialize_with = "serialization::required_option")]
    pub role: Option<String>,
}

/// Sole current-generation host journal for one Fleet ensure operation.

#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetEnsureJournalRecord {
    pub funding_reviews: Vec<FundingReviewRecord>,
    pub successor_phases: Vec<FleetEnsureSuccessorPhaseRecord>,
    pub completion: FleetEnsureCompletion,
    #[serde(deserialize_with = "serialization::required_option")]
    pub estate_funding_required: Option<EstateFundingRequiredRecord>,
    pub effects: Vec<EffectRecord>,
    pub fleet: String,
    #[serde(with = "u128_text")]
    pub initial_controlled_cycles: u128,
    #[serde(with = "u128_text_map")]
    pub initial_estate_funding_cycles_by_root: BTreeMap<String, u128>,
    #[serde(with = "u128_text")]
    pub initial_operator_cycles: u128,
    pub operation_id: String,
    pub plan_sha256: String,
    pub schema_version: u16,
    pub stalled_observations: u32,
}

/// Reviewed input identities and finite protocol expansion for a fresh Fleet.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetEnsureContinuationAuthority {
    /// Additional paid fixture attempts, beyond each publication action's first call.
    pub fixture_publication_retry_attempts: u32,
    pub app_config_sha256: String,
    pub application_artifact_union_sha256: String,
    pub coordinator_candid_sha256: String,
    pub maximum_successor_actions: u32,
    pub root_candid_sha256: String,
    pub store_candid_sha256: String,
}

/// One immutable successor plan retained before its first effect intent.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetEnsureSuccessorPhaseRecord {
    #[serde(with = "u128_text")]
    pub execution_burn_before_phase: u128,
    pub plan_sha256: String,
    /// Hydrated by the owning file reader; durable JSON contains only the digest.
    #[serde(skip)]
    pub plan: Option<Box<FleetEnsurePlan>>,
}

/// Typed boundary requiring a new review instead of automatic protocol continuation.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum FleetEnsureSuccessorReviewReason {
    AdditionalEffect,
    BudgetExceeded,
    ChangedInputs,
    PhaseBound,
    ProtocolAuthority,
}

/// Result returned by one plan-only or apply invocation.

#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct FleetEnsureReport {
    pub funding_review: Option<FundingReviewRecord>,
    pub actual_conservation: Option<ActualCycleConservation>,
    pub effects_applied: u32,
    pub plan: FleetEnsurePlan,
    pub terminal: bool,
}

/// Exact additional transfer reviewed within an existing Fleet operation.
/// The nullable effect is the durable approval boundary; planning never sets it.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FundingReviewRecord {
    pub action: EnsureAction,
    #[serde(deserialize_with = "serialization::required_option")]
    pub effect: Option<EffectRecord>,
    pub pause: FundingPauseRecord,
    pub review_sha256: String,
}

/// Funding destination and retained-operation reason for an additional reviewed credit.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(
    tag = "kind",
    content = "evidence",
    rename_all = "snake_case",
    deny_unknown_fields
)]
pub enum FundingPauseRecord {
    Estate(EstateFundingRequiredRecord),
    Native(NativeFundingRequiredRecord),
}

impl FundingPauseRecord {
    /// Root name retained by the original operation.
    #[must_use]
    pub fn root(&self) -> &str {
        match self {
            Self::Estate(p) => &p.root,
            Self::Native(p) => &p.root,
        }
    }

    /// Exact receiver Principal on the reviewed Ledger.
    #[must_use]
    pub fn root_principal(&self) -> &str {
        match self {
            Self::Estate(p) => &p.root_principal,
            Self::Native(p) => &p.root_principal,
        }
    }

    /// Ledger that owns the operator's source account.
    #[must_use]
    pub fn cycles_ledger(&self) -> &str {
        match self {
            Self::Estate(p) => &p.cycles_ledger,
            Self::Native(p) => &p.cycles_ledger,
        }
    }

    /// Cycles observed at the destination before review.
    #[must_use]
    pub const fn available_cycles(&self) -> u128 {
        match self {
            Self::Estate(p) => p.available_cycles,
            Self::Native(p) => p.available_cycles,
        }
    }

    /// Exact additional amount requiring approval.
    #[must_use]
    pub const fn shortfall_cycles(&self) -> u128 {
        match self {
            Self::Estate(p) => p.shortfall_cycles,
            Self::Native(p) => p.shortfall_cycles,
        }
    }

    /// Exact operator Ledger fee, separately accounted from the credit.
    #[must_use]
    pub const fn ledger_fee_cycles(&self) -> u128 {
        match self {
            Self::Estate(p) => p.ledger_fee_cycles,
            Self::Native(p) => p.ledger_fee_cycles,
        }
    }
}

/// Native reserve review bound to one already-issued provisioning effect and Root.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct NativeFundingRequiredRecord {
    #[serde(with = "u128_text")]
    pub available_cycles: u128,
    pub cycles_ledger: String,
    #[serde(with = "u128_text")]
    pub funding_margin_cycles: u128,
    #[serde(with = "u128_text")]
    pub ledger_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub minimum_cycles: u128,
    pub operation_id: String,
    pub plan_sha256: String,
    pub provisioning_action_sha256: String,
    pub root: String,
    pub root_principal: String,
    #[serde(with = "u128_text")]
    pub shortfall_cycles: u128,
}

/// Management/Ledger evidence available even while runtime activation is incomplete.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct NativeFundingObservation {
    pub cycles_ledger: String,
    pub ledger_fee_cycles: u128,
    pub live: LiveCanister,
    pub operator_cycles: u128,
}

mod u128_text {
    use serde::{Deserialize, Deserializer, Serializer};

    pub fn serialize<S>(value: &u128, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&value.to_string())
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<u128, D::Error>
    where
        D: Deserializer<'de>,
    {
        String::deserialize(deserializer)?
            .parse()
            .map_err(serde::de::Error::custom)
    }
}

mod option_u128_text {
    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    #[expect(
        clippy::ref_option,
        reason = "serde(with) requires the serializer to accept the field by reference"
    )]
    pub fn serialize<S>(value: &Option<u128>, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        value.map(|cycles| cycles.to_string()).serialize(serializer)
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<Option<u128>, D::Error>
    where
        D: Deserializer<'de>,
    {
        Option::<String>::deserialize(deserializer)?
            .map(|value| value.parse().map_err(serde::de::Error::custom))
            .transpose()
    }
}

mod u128_text_map {
    use std::collections::BTreeMap;

    use serde::{Deserialize, Deserializer, Serialize, Serializer};

    pub fn serialize<S>(values: &BTreeMap<String, u128>, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        values
            .iter()
            .map(|(key, value)| (key, value.to_string()))
            .collect::<BTreeMap<_, _>>()
            .serialize(serializer)
    }

    pub fn deserialize<'de, D>(deserializer: D) -> Result<BTreeMap<String, u128>, D::Error>
    where
        D: Deserializer<'de>,
    {
        BTreeMap::<String, String>::deserialize(deserializer)?
            .into_iter()
            .map(|(key, value)| {
                value
                    .parse()
                    .map(|value| (key, value))
                    .map_err(serde::de::Error::custom)
            })
            .collect()
    }
}

/// Conservative base and continuation allowances, with separately reviewed dependent funding.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct FleetRecoveryReview {
    #[serde(with = "u128_text")]
    pub base_execution_burn_cycles: u128,
    #[serde(with = "u128_text")]
    pub continuation_reserve_cycles: u128,
    #[serde(with = "u128_text")]
    pub whole_continuation_ceiling_cycles: u128,
    pub maximum_successor_actions: u32,
    pub fixture_publication_retry_attempts: u32,
    #[serde(with = "u128_text")]
    pub per_step_burn_cycles: u128,
    pub startup_funding: Vec<RootStartupFundingForecast>,
    pub known_pool_funding: Vec<PoolRecoveryFunding>,
    /// Current protocol installation and fresh inventory may reveal more work or debit.
    pub discovery: RecoveryDiscovery,
}

/// Configuration-bound native demand, excluding installation margins and dependent pool funding.
///
/// This projection grants no funding authority and credits no observed reuse.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct RootStartupFundingForecast {
    pub root: String,
    #[serde(with = "u128_text")]
    pub startup_minimum_cycles: u128,
    pub maximum_continuation_steps: u32,
    #[serde(with = "u128_text")]
    pub continuation_allowance_cycles: u128,
    #[serde(with = "u128_text")]
    pub configured_minimum_cycles: u128,
    #[serde(with = "u128_text")]
    pub required_native_cycles: u128,
    pub reuse_assumption: StartupFundingReuseAssumption,
    #[serde(deserialize_with = "serialization::required_option")]
    pub unfunded_role: Option<StartupRoleShortfall>,
}

/// Conservative scenario used before current installation and pool reuse are established.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum StartupFundingReuseAssumption {
    FreshChildrenAndFullPublication,
}

/// Availability of authoritative dependent-work observations at review time.
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum RecoveryDiscovery {
    PendingCurrentProtocol,
}

/// Exact current pool reset top-up estimate; execution requires its own reviewed Fund action.
#[derive(Clone, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct PoolRecoveryFunding {
    pub principal: String,
    pub root: String,
    #[serde(with = "u128_text")]
    pub amount_cycles: u128,
    #[serde(with = "u128_text")]
    pub ledger_fee_cycles: u128,
    #[serde(with = "u128_text")]
    pub funding_deficit_cycles: u128,
    #[serde(with = "u128_text")]
    pub funding_margin_cycles: u128,
    #[serde(with = "u128_text")]
    pub expected_post_cycles: u128,
}

/// Informational difference requiring another plan review; never grants effect authority.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct FleetSuccessorReview {
    pub actions: Vec<FleetReviewAction>,
    #[serde(with = "u128_text")]
    pub maximum_additional_debit_cycles: u128,
    pub next_review_command: String,
}

/// Exact target and current action kind in a newly observed phase.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
pub struct FleetReviewAction {
    pub name: String,
    pub principal: Option<String>,
    pub kind: String,
}

impl std::fmt::Display for FleetSuccessorReview {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "remaining actions: ")?;
        for (index, action) in self.actions.iter().enumerate() {
            if index > 0 {
                write!(f, ", ")?;
            }
            write!(
                f,
                "{} {} ({})",
                action.kind,
                action.name,
                action.principal.as_deref().unwrap_or("not yet created")
            )?;
        }
        write!(
            f,
            "; maximum additional debit including fees: {} cycles; next review: {}",
            self.maximum_additional_debit_cycles, self.next_review_command
        )
    }
}