animsmith-engine 0.7.0

use animsmith_core::{InputIdentity, SourceFormatV1};
use std::collections::BTreeMap;

/// Exact four-field key selecting one revisioned engine profile.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct ProfileSelection {
    family: String,
    profile_revision: u32,
    engine_version: String,
    importer: String,
}

impl ProfileSelection {
    /// Construct an exact profile selection without aliases or version ranges.
    pub fn new(
        family: impl Into<String>,
        profile_revision: u32,
        engine_version: impl Into<String>,
        importer: impl Into<String>,
    ) -> Self {
        Self {
            family: family.into(),
            profile_revision,
            engine_version: engine_version.into(),
            importer: importer.into(),
        }
    }

    /// Stable profile family id.
    pub fn family(&self) -> &str {
        &self.family
    }

    /// Exact profile revision.
    pub const fn profile_revision(&self) -> u32 {
        self.profile_revision
    }

    /// Exact target engine version.
    pub fn engine_version(&self) -> &str {
        &self.engine_version
    }

    /// Exact importer id.
    pub fn importer(&self) -> &str {
        &self.importer
    }
}

/// Stable id for one immutable fact in every V1 profile record.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum FactId {
    /// Bounded AnimSmith input containers accepted by the profile.
    AcceptedInputs,
    /// How imported animation assets are addressed.
    AnimationAddressability,
    /// Target coordinate basis.
    TargetCoordinateBasis,
    /// Target linear unit.
    TargetLinearUnit,
    /// Importer's source-to-target unit-conversion control.
    UnitConversionControl,
    /// Importer's source-to-target axis-conversion control.
    AxisConversionControl,
    /// Exact axis-conversion transform.
    ExactAxisConversion,
    /// Resulting imported hierarchy scale.
    ResultingHierarchyScale,
    /// Whether a whole end frame is required at clip boundaries.
    WholeEndFrameRequired,
    /// Import handling of animation channels.
    AnimationChannelHandling,
    /// Import handling of source extensions.
    ExtensionHandling,
    /// Import handling of source constructs.
    ConstructHandling,
    /// How imported animation targets are addressed.
    AnimationTargetAddressability,
    /// How root-motion sources are addressed.
    RootMotionAddressability,
}

impl FactId {
    /// Stable digest/source-reference spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::AcceptedInputs => "accepted_inputs",
            Self::AnimationAddressability => "animation_addressability",
            Self::TargetCoordinateBasis => "target_coordinate_basis",
            Self::TargetLinearUnit => "target_linear_unit",
            Self::UnitConversionControl => "unit_conversion_control",
            Self::AxisConversionControl => "axis_conversion_control",
            Self::ExactAxisConversion => "exact_axis_conversion",
            Self::ResultingHierarchyScale => "resulting_hierarchy_scale",
            Self::WholeEndFrameRequired => "whole_end_frame_required",
            Self::AnimationChannelHandling => "animation_channel_handling",
            Self::ExtensionHandling => "extension_handling",
            Self::ConstructHandling => "construct_handling",
            Self::AnimationTargetAddressability => "animation_target_addressability",
            Self::RootMotionAddressability => "root_motion_addressability",
        }
    }
}

/// Coordinate-system handedness.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum Handedness {
    /// Left-handed coordinates.
    Left,
    /// Right-handed coordinates.
    Right,
}

/// Positive world axis used as up.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum UpAxis {
    /// Positive X is up.
    X,
    /// Positive Y is up.
    Y,
    /// Positive Z is up.
    Z,
}

/// Known target coordinate basis.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub struct CoordinateBasis {
    /// Coordinate-system handedness.
    pub handedness: Handedness,
    /// Positive world up axis.
    pub up_axis: UpAxis,
    /// Signed target forward axis.
    pub forward_axis: ForwardAxis,
}

/// Signed world axis used as forward.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ForwardAxis {
    /// Positive X is forward.
    PositiveX,
    /// Negative X is forward.
    NegativeX,
    /// Positive Y is forward.
    PositiveY,
    /// Negative Y is forward.
    NegativeY,
    /// Positive Z is forward.
    PositiveZ,
    /// Negative Z is forward.
    NegativeZ,
}

/// Known target linear unit.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum LinearUnit {
    /// Metre.
    Metre,
    /// Centimetre.
    Centimetre,
}

/// Stable setting id in the closed V1 vocabulary.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum SettingId {
    /// Unity document-level unit-conversion toggle.
    ConvertUnits,
    /// Unity document-level axis-baking toggle.
    BakeAxisConversion,
    /// Unity Generic document-level exact source-transform path.
    RootMotionSource,
    /// Unity per-clip root-rotation policy.
    RootRotation,
    /// Unity per-clip vertical root-position policy.
    RootPositionY,
    /// Unity per-clip horizontal root-position policy.
    RootPositionXz,
}

impl SettingId {
    /// Stable public configuration spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::ConvertUnits => "convert_units",
            Self::BakeAxisConversion => "bake_axis_conversion",
            Self::RootMotionSource => "root_motion_source",
            Self::RootRotation => "root_rotation",
            Self::RootPositionY => "root_position_y",
            Self::RootPositionXz => "root_position_xz",
        }
    }

    pub(crate) fn from_str(value: &str) -> Option<Self> {
        match value {
            "convert_units" => Some(Self::ConvertUnits),
            "bake_axis_conversion" => Some(Self::BakeAxisConversion),
            "root_motion_source" => Some(Self::RootMotionSource),
            "root_rotation" => Some(Self::RootRotation),
            "root_position_y" => Some(Self::RootPositionY),
            "root_position_xz" => Some(Self::RootPositionXz),
            _ => None,
        }
    }
}

impl std::fmt::Display for SettingId {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

/// A known importer control relevant to source-to-target conversion.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ConversionControl {
    /// Behavior is controlled by one declared profile setting.
    ProfileSetting(SettingId),
    /// Behavior is exposed by the importer but is not a V1 profile setting.
    ImporterOption,
}

/// Known importer treatment for a fact domain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ImportHandling {
    /// The importer retains the domain.
    Preserved,
    /// The importer converts the domain.
    Converted,
    /// The importer discards the domain.
    Discarded,
    /// The importer does not support the domain.
    Unsupported,
}

/// Known animation-target addressability behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum TargetAddressability {
    /// Targets are addressed by a stable id derived from their name path.
    NamePathDerivedId,
}

/// Known animation-asset addressability behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum AnimationAddressability {
    /// Bevy addresses each glTF animation by its source-array index through
    /// `GltfAssetLabel::Animation(index)`; animation names populate Bevy's
    /// separate named-animation map rather than this typed label.
    GltfAssetLabel,
}

/// Known root-motion addressability behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum RootMotionAddressability {
    /// A bounded exact source-transform path selects the motion node.
    ExactSourceTransformPath,
    /// Humanoid Avatar/body semantics determine root motion.
    HumanoidAvatarBody,
}

/// Typed value of a known immutable profile fact.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum FactValue {
    /// Exact accepted AnimSmith input formats.
    AcceptedFormats(Vec<SourceFormatV1>),
    /// Animation-asset addressability.
    AnimationAddressability(AnimationAddressability),
    /// Target coordinate basis.
    CoordinateBasis(CoordinateBasis),
    /// Target linear unit.
    LinearUnit(LinearUnit),
    /// Source-to-target conversion control.
    ConversionControl(ConversionControl),
    /// Boolean predicate.
    Boolean(bool),
    /// Import handling of a domain.
    ImportHandling(ImportHandling),
    /// Animation-target addressability.
    TargetAddressability(TargetAddressability),
    /// Root-motion addressability.
    RootMotionAddressability(RootMotionAddressability),
}

/// Evidence state of one profile fact.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum FactState {
    /// Supported known value.
    Known(FactValue),
    /// Primary evidence does not establish a value.
    Unknown,
    /// The fact domain genuinely does not apply.
    NotApplicable,
}

/// One stable fact and its explicit evidence state.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct ProfileFact {
    id: FactId,
    state: FactState,
}

impl ProfileFact {
    pub(crate) fn new(id: FactId, state: FactState) -> Self {
        Self { id, state }
    }

    /// Stable fact id.
    pub const fn id(&self) -> FactId {
        self.id
    }

    /// Explicit known, unknown, or not-applicable state.
    pub const fn state(&self) -> &FactState {
        &self.state
    }
}

/// Configuration scope of a setting.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingScope {
    /// One value governs the imported document and all clips.
    Document,
    /// One materialized value is required for each real clip.
    Clip,
}

/// Closed value domain of a setting.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingDomain {
    /// Boolean value.
    Boolean,
    /// `bake` or `extract`.
    BakeOrExtract,
    /// Bounded exact source-transform path.
    SourceTransformPath,
}

/// Whether a descriptor applies to a profile revision.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingApplicability {
    /// The setting applies.
    Applicable,
    /// The setting genuinely does not apply.
    NotApplicable,
}

/// Verified default status of a setting.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum DefaultStatus {
    /// The caller must declare a value because no default is verified.
    RequiredWithoutDefault,
    /// Default behavior is irrelevant because the setting does not apply.
    NotApplicable,
}

/// Immutable descriptor for one stable setting id.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct SettingDescriptor {
    id: SettingId,
    scope: SettingScope,
    domain: SettingDomain,
    applicability: SettingApplicability,
    default_status: DefaultStatus,
}

impl SettingDescriptor {
    pub(crate) const fn new(
        id: SettingId,
        scope: SettingScope,
        domain: SettingDomain,
        applicability: SettingApplicability,
        default_status: DefaultStatus,
    ) -> Self {
        Self {
            id,
            scope,
            domain,
            applicability,
            default_status,
        }
    }

    /// Stable setting id.
    pub const fn id(&self) -> SettingId {
        self.id
    }

    /// Required declaration scope.
    pub const fn scope(&self) -> SettingScope {
        self.scope
    }

    /// Closed value domain.
    pub const fn domain(&self) -> SettingDomain {
        self.domain
    }

    /// Applicability to this exact profile revision.
    pub const fn applicability(&self) -> SettingApplicability {
        self.applicability
    }

    /// Verified default status.
    pub const fn default_status(&self) -> DefaultStatus {
        self.default_status
    }
}

/// Exact policy for a Unity root transform component.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum BakeOrExtract {
    /// Bake the component into the pose.
    Bake,
    /// Extract the component as root motion.
    Extract,
}

/// Closed public value vocabulary for engine settings.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingValue {
    /// Boolean setting value.
    Boolean(bool),
    /// Root-component bake/extract policy.
    BakeOrExtract(BakeOrExtract),
    /// Exact source-transform path, validated during static resolution.
    SourceTransformPath(String),
}

/// String-keyed setting declarations used at the TOML-free public boundary.
pub type SettingMap = BTreeMap<String, SettingValue>;

/// Full public input to phase-one static resolution.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EngineDeclaration {
    /// Exact profile selection, or none for engine-neutral behavior.
    pub selection: Option<ProfileSelection>,
    /// Declared document settings. `Some` retains an explicitly empty table.
    pub document_settings: Option<SettingMap>,
    /// Selector-keyed per-clip setting declarations.
    pub clip_settings: BTreeMap<String, SettingMap>,
}

/// One primary source retained by an immutable profile record.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct PrimarySource {
    id: &'static str,
    target_version: &'static str,
    url: &'static str,
    verified_on: &'static str,
    supported_facts: Vec<FactId>,
    supported_settings: Vec<SettingId>,
}

impl PrimarySource {
    pub(crate) fn new(
        id: &'static str,
        target_version: &'static str,
        url: &'static str,
        verified_on: &'static str,
        mut supported_facts: Vec<FactId>,
        mut supported_settings: Vec<SettingId>,
    ) -> Self {
        supported_facts.sort_by_key(|id| id.as_str());
        supported_settings.sort_by_key(|id| id.as_str());
        Self {
            id,
            target_version,
            url,
            verified_on,
            supported_facts,
            supported_settings,
        }
    }

    /// Stable source id.
    pub const fn id(&self) -> &'static str {
        self.id
    }

    /// Version of the source's target product/specification.
    pub const fn target_version(&self) -> &'static str {
        self.target_version
    }

    /// Primary-source URL.
    pub const fn url(&self) -> &'static str {
        self.url
    }

    /// ISO date on which this source was verified.
    pub const fn verified_on(&self) -> &'static str {
        self.verified_on
    }

    /// Stable fact ids supported by the source.
    pub fn supported_facts(&self) -> &[FactId] {
        &self.supported_facts
    }

    /// Stable setting ids supported by the source.
    pub fn supported_settings(&self) -> &[SettingId] {
        &self.supported_settings
    }

    #[cfg(test)]
    pub(crate) fn reverse_supported_ids_for_test(&mut self) {
        self.supported_facts.reverse();
        self.supported_settings.reverse();
    }
}

/// One immutable, revisioned registry profile.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EngineProfile {
    pub(crate) selection: ProfileSelection,
    pub(crate) fact_bundle_urn: &'static str,
    pub(crate) facts: Vec<ProfileFact>,
    pub(crate) settings: Vec<SettingDescriptor>,
    pub(crate) sources: Vec<PrimarySource>,
    pub(crate) facts_identity: InputIdentity,
}

impl EngineProfile {
    /// Full exact selection tuple retained by this profile.
    pub const fn selection(&self) -> &ProfileSelection {
        &self.selection
    }

    /// Revisioned fact-bundle URN.
    pub const fn fact_bundle_urn(&self) -> &'static str {
        self.fact_bundle_urn
    }

    /// Bounded AnimSmith V1 input formats accepted by the profile.
    pub fn accepted_inputs(&self) -> &[SourceFormatV1] {
        match self.fact(FactId::AcceptedInputs).map(ProfileFact::state) {
            Some(FactState::Known(FactValue::AcceptedFormats(formats))) => formats,
            _ => &[],
        }
    }

    /// Complete typed fact inventory in stable-id order.
    pub fn facts(&self) -> &[ProfileFact] {
        &self.facts
    }

    /// Complete descriptor inventory in stable-id order.
    pub fn setting_descriptors(&self) -> &[SettingDescriptor] {
        &self.settings
    }

    /// Primary sources in stable-id order.
    pub fn sources(&self) -> &[PrimarySource] {
        &self.sources
    }

    /// SHA-256 plus byte count of the canonical immutable record encoding.
    pub const fn facts_identity(&self) -> &InputIdentity {
        &self.facts_identity
    }

    /// Look up one fact by stable id.
    pub fn fact(&self, id: FactId) -> Option<&ProfileFact> {
        self.facts.iter().find(|fact| fact.id == id)
    }

    /// Look up one setting descriptor, including not-applicable descriptors.
    pub fn setting_descriptor(&self, id: SettingId) -> Option<&SettingDescriptor> {
        self.settings.iter().find(|descriptor| descriptor.id == id)
    }
}

/// Stable setting id in the revision-2 engine-profile vocabulary.
///
/// This is intentionally distinct from [`SettingId`]: the V1 ids and their
/// core wire projection are immutable and cannot represent verified defaults,
/// Unity's closed import modes, or Bevy's closed load-time environment.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum SettingIdV2 {
    /// Unity animation import mode.
    AnimationType,
    /// Unity avatar construction policy.
    AvatarSetup,
    /// Unity animation import toggle.
    ImportAnimation,
    /// Unity Generic exact source-transform path.
    RootMotionSource,
    /// Unity per-clip root-rotation policy.
    RootRotation,
    /// Unity per-clip vertical root-position policy.
    RootPositionY,
    /// Unity per-clip horizontal root-position policy.
    RootPositionXz,
    /// Per-load coordinate conversion of the loader-created scene entity.
    RotateSceneEntity,
    /// Per-load coordinate conversion of mesh assets and primitive entities.
    RotateMeshes,
    /// Per-load mesh usage flags, represented by their empty/nonempty state.
    LoadMeshes,
    /// Exact glTF extension-handler registry installed at load time.
    ExtensionHandlerEnvironment,
    /// Whether Bevy was compiled with its `bevy_animation` feature.
    BevyAnimationFeature,
    /// Per-load animation loading toggle.
    LoadAnimations,
    /// Godot scene-import animation bake frequency.
    AnimationFps,
    /// Godot scene-import animation trimming toggle.
    AnimationTrimming,
    /// Unreal FBX importer sample-rate policy.
    SampleRate,
}

impl SettingIdV2 {
    /// Stable public configuration spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::AnimationType => "animation_type",
            Self::AvatarSetup => "avatar_setup",
            Self::ImportAnimation => "import_animation",
            Self::RootMotionSource => "root_motion_source",
            Self::RootRotation => "root_rotation",
            Self::RootPositionY => "root_position_y",
            Self::RootPositionXz => "root_position_xz",
            Self::RotateSceneEntity => "rotate_scene_entity",
            Self::RotateMeshes => "rotate_meshes",
            Self::LoadMeshes => "load_meshes",
            Self::ExtensionHandlerEnvironment => "extension_handler_environment",
            Self::BevyAnimationFeature => "bevy_animation_feature",
            Self::LoadAnimations => "load_animations",
            Self::AnimationFps => "animation_fps",
            Self::AnimationTrimming => "animation_trimming",
            Self::SampleRate => "sample_rate",
        }
    }

    pub(crate) fn from_str_v2(value: &str) -> Option<Self> {
        match value {
            "animation_type" => Some(Self::AnimationType),
            "avatar_setup" => Some(Self::AvatarSetup),
            "import_animation" => Some(Self::ImportAnimation),
            "root_motion_source" => Some(Self::RootMotionSource),
            "root_rotation" => Some(Self::RootRotation),
            "root_position_y" => Some(Self::RootPositionY),
            "root_position_xz" => Some(Self::RootPositionXz),
            "rotate_scene_entity" => Some(Self::RotateSceneEntity),
            "rotate_meshes" => Some(Self::RotateMeshes),
            "load_meshes" => Some(Self::LoadMeshes),
            "extension_handler_environment" => Some(Self::ExtensionHandlerEnvironment),
            "bevy_animation_feature" => Some(Self::BevyAnimationFeature),
            "load_animations" => Some(Self::LoadAnimations),
            "animation_fps" => Some(Self::AnimationFps),
            "animation_trimming" => Some(Self::AnimationTrimming),
            "sample_rate" => Some(Self::SampleRate),
            _ => None,
        }
    }
}

/// Exact Unreal FBX animation sample-rate policy.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum UnrealSampleRateV2 {
    /// `bUseDefaultSampleRate=true` with no custom-rate value.
    Default30,
    /// `bUseDefaultSampleRate=false, CustomSampleRate=0`.
    SourceDetermined,
    /// `bUseDefaultSampleRate=false, CustomSampleRate=<hertz>`.
    CustomHz(u32),
}

/// Closed Unity animation-type values supported by the revision-2 profile.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum UnityAnimationTypeV2 {
    /// Unity's generic transform animation mode.
    Generic,
    /// Unity's humanoid avatar animation mode.
    Humanoid,
    /// Unity's legacy animation mode.
    Legacy,
}

impl UnityAnimationTypeV2 {
    /// Stable public value spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Generic => "generic",
            Self::Humanoid => "humanoid",
            Self::Legacy => "legacy",
        }
    }
}

/// Closed Unity avatar-setup values supported by the revision-2 profile.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum UnityAvatarSetupV2 {
    /// Build an avatar from the imported model.
    CreateFromThisModel,
    /// Reuse a separately supplied avatar.
    CopyFromOtherAvatar,
}

impl UnityAvatarSetupV2 {
    /// Stable public value spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::CreateFromThisModel => "create_from_this_model",
            Self::CopyFromOtherAvatar => "copy_from_other_avatar",
        }
    }
}

impl std::fmt::Display for SettingIdV2 {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(self.as_str())
    }
}

/// Exact state of Bevy's `RenderAssetUsages` mesh-loading flags.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum BevyLoadMeshesStateV2 {
    /// No usage flag is enabled, so mesh primitive child entities are skipped;
    /// the source-node entity is still created when its scene is loaded.
    Empty,
    /// At least one usage flag is enabled, so mesh primitive child entities
    /// are created beneath their source-node entity.
    Nonempty,
}

/// Supported version-pinned glTF extension-handler environment.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum BevyGltfHandlerEnvironmentV2 {
    /// `GltfExtensionHandlers` is empty.
    BareEmpty,
    /// The registry contains only Bevy 0.19's stock PBR handler.
    BevyPbrStock019,
}

impl BevyGltfHandlerEnvironmentV2 {
    /// Stable public value spelling.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::BareEmpty => "bare_empty",
            Self::BevyPbrStock019 => "bevy_pbr_stock_0_19",
        }
    }
}

/// Closed value domain for revision-2 settings.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingDomainV2 {
    /// Boolean value.
    Boolean,
    /// Bake or extract value.
    BakeOrExtract,
    /// Exact source-transform path.
    SourceTransformPath,
    /// Unity animation type.
    AnimationType,
    /// Unity avatar setup policy.
    AvatarSetup,
    /// Empty/nonempty mesh usage state.
    LoadMeshesState,
    /// Exact supported glTF extension-handler environment.
    HandlerEnvironment,
    /// Positive bounded integer.
    PositiveInteger,
    /// Exact Unreal FBX sample-rate policy.
    SampleRate,
}

/// Closed public value vocabulary for revision-2 settings.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingValueV2 {
    /// Boolean setting value.
    Boolean(bool),
    /// Root-component bake/extract policy.
    BakeOrExtract(BakeOrExtract),
    /// Exact source-transform path.
    SourceTransformPath(String),
    /// Unity animation type.
    AnimationType(UnityAnimationTypeV2),
    /// Unity avatar setup policy.
    AvatarSetup(UnityAvatarSetupV2),
    /// Empty/nonempty mesh usage state.
    LoadMeshesState(BevyLoadMeshesStateV2),
    /// Exact supported extension-handler environment.
    HandlerEnvironment(BevyGltfHandlerEnvironmentV2),
    /// Positive bounded integer.
    PositiveInteger(u32),
    /// Exact Unreal FBX sample-rate policy.
    SampleRate(UnrealSampleRateV2),
}

impl SettingValueV2 {
    pub(crate) const fn matches_domain(&self, domain: SettingDomainV2) -> bool {
        matches!(
            (self, domain),
            (Self::Boolean(_), SettingDomainV2::Boolean)
                | (Self::BakeOrExtract(_), SettingDomainV2::BakeOrExtract)
                | (
                    Self::SourceTransformPath(_),
                    SettingDomainV2::SourceTransformPath
                )
                | (Self::AnimationType(_), SettingDomainV2::AnimationType)
                | (Self::AvatarSetup(_), SettingDomainV2::AvatarSetup)
                | (Self::LoadMeshesState(_), SettingDomainV2::LoadMeshesState)
                | (
                    Self::HandlerEnvironment(_),
                    SettingDomainV2::HandlerEnvironment
                )
                | (
                    Self::PositiveInteger(1..=120),
                    SettingDomainV2::PositiveInteger
                )
                | (
                    Self::SampleRate(
                        UnrealSampleRateV2::Default30 | UnrealSampleRateV2::SourceDetermined
                    ),
                    SettingDomainV2::SampleRate
                )
                | (
                    Self::SampleRate(UnrealSampleRateV2::CustomHz(1..=48_000)),
                    SettingDomainV2::SampleRate
                )
        )
    }
}

/// Declaration/default policy for one revision-2 setting.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub enum SettingDefaultV2 {
    /// The caller must declare a value; no default is claimed.
    RequiredExplicit,
    /// The exact profile has a version-pinned verified default.
    Verified(SettingValueV2),
}

/// Immutable descriptor for one revision-2 setting.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct SettingDescriptorV2 {
    pub(crate) id: SettingIdV2,
    pub(crate) scope: SettingScope,
    pub(crate) domain: SettingDomainV2,
    pub(crate) default: SettingDefaultV2,
}

impl SettingDescriptorV2 {
    pub(crate) const fn new(
        id: SettingIdV2,
        scope: SettingScope,
        domain: SettingDomainV2,
        default: SettingDefaultV2,
    ) -> Self {
        Self {
            id,
            scope,
            domain,
            default,
        }
    }

    /// Stable setting id.
    pub const fn id(&self) -> SettingIdV2 {
        self.id
    }

    /// Required declaration scope.
    pub const fn scope(&self) -> SettingScope {
        self.scope
    }

    /// Closed value domain.
    pub const fn domain(&self) -> SettingDomainV2 {
        self.domain
    }

    /// Exact required/default policy.
    pub const fn default(&self) -> &SettingDefaultV2 {
        &self.default
    }
}

/// Primary source retained by an immutable revision-2 profile record.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct PrimarySourceV2 {
    pub(crate) id: &'static str,
    pub(crate) target_version: &'static str,
    pub(crate) url: &'static str,
    pub(crate) verified_on: &'static str,
    pub(crate) supported_facts: Vec<animsmith_core::engine_contract::EngineFactIdV2>,
    pub(crate) supported_settings: Vec<SettingIdV2>,
}

impl PrimarySourceV2 {
    /// Stable source id.
    pub const fn id(&self) -> &'static str {
        self.id
    }

    /// Version of the source's target product/specification.
    pub const fn target_version(&self) -> &'static str {
        self.target_version
    }

    /// Version-pinned primary-source URL.
    pub const fn url(&self) -> &'static str {
        self.url
    }

    /// ISO date on which the source was verified.
    pub const fn verified_on(&self) -> &'static str {
        self.verified_on
    }

    /// Whether this source establishes the accepted input containers.
    pub fn supports_accepted_inputs(&self) -> bool {
        self.supported_facts
            .contains(&animsmith_core::engine_contract::EngineFactIdV2::AcceptedInputs)
    }

    /// Stable fact ids supported by this source.
    pub fn supported_facts(&self) -> &[animsmith_core::engine_contract::EngineFactIdV2] {
        &self.supported_facts
    }

    /// Stable setting ids supported by this source.
    pub fn supported_settings(&self) -> &[SettingIdV2] {
        &self.supported_settings
    }
}

/// One immutable revision-2 engine-profile registry record.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EngineProfileV2 {
    pub(crate) selection: ProfileSelection,
    pub(crate) profile_urn: &'static str,
    pub(crate) accepted_inputs: Vec<SourceFormatV1>,
    pub(crate) facts: Vec<animsmith_core::engine_contract::EngineProfileFactV2>,
    pub(crate) settings: Vec<SettingDescriptorV2>,
    pub(crate) sources: Vec<PrimarySourceV2>,
}

impl EngineProfileV2 {
    /// Full exact selection tuple retained by this record.
    pub const fn selection(&self) -> &ProfileSelection {
        &self.selection
    }

    /// Stable revisioned profile-record URN.
    pub const fn profile_urn(&self) -> &'static str {
        self.profile_urn
    }

    /// Exact accepted input containers.
    pub fn accepted_inputs(&self) -> &[SourceFormatV1] {
        &self.accepted_inputs
    }

    /// Complete profile-facts V2 inventory in stable-id order.
    pub fn facts(&self) -> &[animsmith_core::engine_contract::EngineProfileFactV2] {
        &self.facts
    }

    /// Complete descriptor inventory in stable-id order.
    pub fn setting_descriptors(&self) -> &[SettingDescriptorV2] {
        &self.settings
    }

    /// Version-pinned primary sources in stable-id order.
    pub fn sources(&self) -> &[PrimarySourceV2] {
        &self.sources
    }

    /// Look up one setting descriptor.
    pub fn setting_descriptor(&self, id: SettingIdV2) -> Option<&SettingDescriptorV2> {
        self.settings.iter().find(|descriptor| descriptor.id == id)
    }
}

/// String-keyed setting declarations for revision-2 profiles.
pub type SettingMapV2 = BTreeMap<String, SettingValueV2>;

/// Public input to revision-2 static settings resolution.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EngineDeclarationV2 {
    /// Exact profile selection, or none for engine-neutral behavior.
    pub selection: Option<ProfileSelection>,
    /// Declared document settings. `Some` retains an explicitly empty table.
    pub document_settings: Option<SettingMapV2>,
    /// Selector-keyed clip settings reserved for descriptors that use clip scope.
    pub clip_settings: BTreeMap<String, SettingMapV2>,
}

/// Origin of one fully materialized revision-2 setting value.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum ResolvedSettingOriginV2 {
    /// Supplied explicitly by the caller.
    ExplicitConfig,
    /// Materialized from a version-pinned profile default.
    ProfileDefault,
}

/// One fully materialized revision-2 setting and its value origin.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
pub struct ResolvedSettingV2 {
    pub(crate) value: SettingValueV2,
    pub(crate) origin: ResolvedSettingOriginV2,
}

impl ResolvedSettingV2 {
    /// Closed resolved value.
    pub const fn value(&self) -> &SettingValueV2 {
        &self.value
    }

    /// Explicit/default value origin.
    pub const fn origin(&self) -> ResolvedSettingOriginV2 {
        self.origin
    }
}