canic-core 0.110.2

//! Module: role_contract::model
//!
//! Responsibility: define passive typed role-contract inputs, outputs, and findings.
//! Does not own: Cargo evidence collection, state descriptors, or report rendering.
//! Boundary: host/build consumers provide typed feature evidence to pure core policy.

use crate::{config::schema::ConfigModel, ids::CanisterRole};
use serde::{Deserialize, Serialize};
use std::collections::BTreeSet;

///
/// CanicFeatureKey
///
/// Maintained public feature of the `canic` facade crate.
///

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub enum CanicFeatureKey {
    AuthChainKeyEcdsa,
    AuthChainKeyRootSign,
    AuthDelegatedTokenVerify,
    AuthIssuerCanisterSigCreate,
    AuthIssuerCanisterSigVerify,
    AuthRootCanisterSigCreate,
    AuthRootCanisterSigVerify,
    BlobStorage,
    BlobStorageBilling,
    ControlPlane,
    FleetCoordinatorCanister,
    InternalTestFixtures,
    Sharding,
    WasmStoreCanister,
}

///
/// CanicFeatureEffect
///
/// Whether enabling one public Canic feature selects stable state.
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum CanicFeatureEffect {
    NoState,
    StateBearing,
}

///
/// RoleCapabilityKey
///
/// Typed behavior derived from validated role configuration or built-in identity.
///

#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
pub enum RoleCapabilityKey {
    AutomaticTopup,
    ChildProvisioning,
    DelegatedTokenIssuer,
    DelegatedTokenVerifier,
    FleetAdmissionProjection,
    FleetCoordinator,
    Icrc21,
    Index,
    LocalApplicationAuthorization,
    RoleAttestationSigner,
    RoleAttestationVerifier,
    Root,
    RootControlPlane,
    Runtime,
    Scaling,
    Sharding,
    WasmStore,
}

impl RoleCapabilityKey {
    /// Stable manifest spelling used by protocol-profile identity encoding.
    #[must_use]
    pub const fn manifest_name(self) -> &'static str {
        match self {
            Self::AutomaticTopup => "AutomaticTopup",
            Self::ChildProvisioning => "ChildProvisioning",
            Self::DelegatedTokenIssuer => "DelegatedTokenIssuer",
            Self::DelegatedTokenVerifier => "DelegatedTokenVerifier",
            Self::FleetAdmissionProjection => "FleetAdmissionProjection",
            Self::FleetCoordinator => "FleetCoordinator",
            Self::Icrc21 => "Icrc21",
            Self::Index => "Index",
            Self::LocalApplicationAuthorization => "LocalApplicationAuthorization",
            Self::RoleAttestationSigner => "RoleAttestationSigner",
            Self::RoleAttestationVerifier => "RoleAttestationVerifier",
            Self::Root => "Root",
            Self::RootControlPlane => "RootControlPlane",
            Self::Runtime => "Runtime",
            Self::Scaling => "Scaling",
            Self::Sharding => "Sharding",
            Self::WasmStore => "WasmStore",
        }
    }
}

///
/// StateAllocationKey
///
/// Typed identity of one active Canic-managed stable-memory allocation group.
///

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub enum StateAllocationKey {
    TemplateManifests,
    TemplateChunkSets,
    TemplateChunkRefs,
    TemplateChunkPayloads,
    WasmStoreGcState,
    FleetCoordinatorAdmission,
    FleetCoordinatorFunding,
    FleetCoordinatorRegistry,
    RootAdmission,
    RootFunding,
    RootWasmStoreState,
    RootFleetRegistryMirror,
    RootComponentRegistry,
    RootCanisterPool,
    RootComponentProvisioning,
    CoreRuntimeChildren,
    CoreRuntimeBindings,
    CoreFleetState,
    CoreFleetActivation,
    CoreAuthState,
    CoreReplayReceipts,
    CoreCycles,
    CoreCyclesIcpRefillRecords,
    CoreRuntimeLog,
    CoreIntent,
    CoreApplicationReceipts,
    CorePlacementAcknowledgement,
    PlacementScalingRegistry,
    PlacementIndexRegistry,
    ShardingRegistry,
    ShardingAssignments,
    ShardingActiveSet,
    BlobStorageRoots,
    BlobStoragePendingDeletions,
    BlobStorageGatewayPrincipals,
    BlobStorageBilling,
    CoreAuthorityRestoreFence,
    CoreAsyncJobRecovery,
    CoreFleetAdmissionProjection,
}

///
/// AllocationOwner
///
/// Crate that owns the records and storage implementation for an allocation.
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum AllocationOwner {
    CanicControlPlane,
    CanicCore,
}

impl AllocationOwner {
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::CanicControlPlane => "canic-control-plane",
            Self::CanicCore => "canic-core",
        }
    }
}

///
/// MemoryId
///
/// Typed stable-memory manager ID owned by the allocation registry.
///

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub struct MemoryId(u8);

impl MemoryId {
    #[must_use]
    pub const fn new(value: u8) -> Self {
        Self(value)
    }

    #[must_use]
    pub const fn get(self) -> u8 {
        self.0
    }
}

///
/// AllocationDefinition
///
/// Canonical assignment of one or more stable-memory IDs to an active allocation.
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct AllocationDefinition {
    pub key: StateAllocationKey,
    pub owner: AllocationOwner,
    pub memory_ids: &'static [MemoryId],
}

///
/// BuiltInRoleKind
///
/// Canic-managed role that is not resolved from an App role declaration.
///

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub enum BuiltInRoleKind {
    FleetCoordinator,
    WasmStore,
}

///
/// RoleContractSource
///
/// Validated configuration source used by pure role-contract resolution.
///

pub enum RoleContractSource<'a> {
    BuiltIn(BuiltInRoleKind),
    Declared {
        config: &'a ConfigModel,
        role: &'a CanisterRole,
    },
}

///
/// RoleContractInput
///
/// Typed feature evidence for one pure role-contract resolution.
///

pub struct RoleContractInput<'a> {
    pub source: RoleContractSource<'a>,
    pub declared_features: BTreeSet<CanicFeatureKey>,
    pub default_features_enabled: bool,
}

///
/// RoleFeatureRequirement
///
/// Public Canic feature required by one derived role capability.
///

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct RoleFeatureRequirement {
    pub capability: RoleCapabilityKey,
    pub config_key: &'static str,
    pub feature: CanicFeatureKey,
    pub reason: &'static str,
}

///
/// SelectionProvenance
///
/// Typed reason one active allocation was selected for a role contract.
///

#[derive(Clone, Copy, Debug, Eq, Ord, PartialEq, PartialOrd)]
pub enum SelectionProvenance {
    BuiltInRole(BuiltInRoleKind),
    Capability(RoleCapabilityKey),
    EffectiveFeature(CanicFeatureKey),
}

///
/// ResolvedStateAllocation
///
/// Active allocation selected for one resolved role contract.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ResolvedStateAllocation {
    pub key: StateAllocationKey,
    pub owner: AllocationOwner,
    pub memory_ids: Vec<MemoryId>,
    pub selected_by: BTreeSet<SelectionProvenance>,
}

///
/// ResolvedRoleContract
///
/// Consumable role contract returned only when all blocking checks pass.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ResolvedRoleContract {
    pub role: CanisterRole,
    pub built_in: Option<BuiltInRoleKind>,
    pub capabilities: BTreeSet<RoleCapabilityKey>,
    pub required_features: BTreeSet<CanicFeatureKey>,
    pub effective_features: BTreeSet<CanicFeatureKey>,
    pub allocations: Vec<ResolvedStateAllocation>,
}

///
/// RoleContractFinding
///
/// Blocking failure produced by pure role-contract validation.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub enum RoleContractFinding {
    AllocationDescriptorDuplicate {
        key: StateAllocationKey,
    },
    AllocationDescriptorIdMismatch {
        key: StateAllocationKey,
        expected: Vec<MemoryId>,
        actual: Vec<MemoryId>,
    },
    AllocationDescriptorMissing {
        key: StateAllocationKey,
    },
    CatalogInvalid {
        reason: String,
    },
    BuiltInPackageUnavailable {
        role: BuiltInRoleKind,
    },
    CanicVersionMismatch {
        expected: String,
        actual: String,
    },
    CargoCatalogDrift {
        reason: String,
    },
    CargoEvidenceUnavailable {
        phase: String,
        cause: String,
    },
    DependencyShapeUnsupported {
        reason: String,
    },
    MemoryIdCollision {
        memory_id: MemoryId,
        first: StateAllocationKey,
        second: StateAllocationKey,
    },
    MultipleCanicPackages {
        packages: Vec<String>,
    },
    PackageAmbiguous {
        role: CanisterRole,
    },
    PackageMetadataMismatch {
        expected_app: String,
        expected_role: CanisterRole,
        actual_app: Option<String>,
        actual_role: Option<String>,
    },
    PackageMissing {
        role: CanisterRole,
    },
    RequiredFeatureMissing {
        capability: RoleCapabilityKey,
        feature: CanicFeatureKey,
    },
    RoleUnknown {
        role: CanisterRole,
    },
    RuntimeCanicDependencyMissing {
        role: CanisterRole,
    },
}

impl RoleContractFinding {
    #[must_use]
    pub const fn code(&self) -> &'static str {
        match self {
            Self::AllocationDescriptorDuplicate { .. } => {
                "role_contract_allocation_descriptor_duplicate"
            }
            Self::AllocationDescriptorIdMismatch { .. } => "role_contract_allocation_id_mismatch",
            Self::AllocationDescriptorMissing { .. } => {
                "role_contract_allocation_descriptor_missing"
            }
            Self::BuiltInPackageUnavailable { .. } => "role_contract_builtin_package_unavailable",
            Self::CanicVersionMismatch { .. } => "role_contract_canic_version_mismatch",
            Self::CargoCatalogDrift { .. } => "role_contract_cargo_catalog_drift",
            Self::CargoEvidenceUnavailable { .. } => "role_contract_cargo_evidence_unavailable",
            Self::CatalogInvalid { .. } => "role_contract_catalog_invalid",
            Self::DependencyShapeUnsupported { .. } => "role_contract_dependency_shape_unsupported",
            Self::MemoryIdCollision { .. } => "role_contract_memory_id_collision",
            Self::MultipleCanicPackages { .. } => "role_contract_multiple_canic_packages",
            Self::PackageAmbiguous { .. } => "role_contract_package_ambiguous",
            Self::PackageMetadataMismatch { .. } => "role_contract_package_metadata_mismatch",
            Self::PackageMissing { .. } => "role_contract_package_missing",
            Self::RequiredFeatureMissing { .. } => "role_contract_required_feature_missing",
            Self::RoleUnknown { .. } => "role_contract_role_unknown",
            Self::RuntimeCanicDependencyMissing { .. } => {
                "role_contract_runtime_canic_dependency_missing"
            }
        }
    }
}

///
/// RoleContractResolution
///
/// Resolved contract or blocking findings; rejected results never carry a contract.
///

#[derive(Clone, Debug, Eq, PartialEq)]
pub enum RoleContractResolution {
    Rejected { errors: Vec<RoleContractFinding> },
    Resolved { contract: ResolvedRoleContract },
}