katra-core 0.1.0

//! Subsystems and promotion states.
//!
//! Every Katra subsystem travels through the promotion pipeline
//! (`OBSERVE → SHADOW → NATIVE_EXPERIMENTAL → NATIVE_DEFAULT`, with the
//! `FALLBACK` state for mature C implementations retained as fallback).
//! See `docs/standards/promotion-gates.md`.

use serde::{Deserialize, Serialize};

/// The named subsystems of Katra3D.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Subsystem {
    /// Trace capture/writing.
    Trace,
    /// Report generation.
    Report,
    /// Trace replay.
    Replay,
    /// Semantic request graph.
    Graph,
    /// KatraFlow (inferred storage intent).
    Flow,
    /// Katra I/O (io_uring + backends).
    Io,
    /// Katra memory/residency.
    Memory,
    /// Katra synchronization.
    Sync,
    /// Unified scheduling.
    Schedule,
    /// DirectStorage frontend.
    DStorage,
    /// Shader service.
    Shader,
    /// Layered cache.
    Cache,
    /// D3D12 hot-path reconstruction.
    D3d12,
    /// Vulkan integration.
    Vulkan,
    /// Courts (falsifiable test corpus).
    Courts,
    /// C ABI (libkatra3d).
    Abi,
}

impl Subsystem {
    /// All subsystems in stable order.
    pub const ALL: [Subsystem; 16] = [
        Subsystem::Trace,
        Subsystem::Report,
        Subsystem::Replay,
        Subsystem::Graph,
        Subsystem::Flow,
        Subsystem::Io,
        Subsystem::Memory,
        Subsystem::Sync,
        Subsystem::Schedule,
        Subsystem::DStorage,
        Subsystem::Shader,
        Subsystem::Cache,
        Subsystem::D3d12,
        Subsystem::Vulkan,
        Subsystem::Courts,
        Subsystem::Abi,
    ];

    /// Stable string name.
    pub const fn as_str(self) -> &'static str {
        match self {
            Subsystem::Trace => "trace",
            Subsystem::Report => "report",
            Subsystem::Replay => "replay",
            Subsystem::Graph => "graph",
            Subsystem::Flow => "flow",
            Subsystem::Io => "io",
            Subsystem::Memory => "memory",
            Subsystem::Sync => "sync",
            Subsystem::Schedule => "schedule",
            Subsystem::DStorage => "dstorage",
            Subsystem::Shader => "shader",
            Subsystem::Cache => "cache",
            Subsystem::D3d12 => "d3d12",
            Subsystem::Vulkan => "vulkan",
            Subsystem::Courts => "courts",
            Subsystem::Abi => "abi",
        }
    }
}

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

/// The promotion state of a subsystem (§3.2, §20).
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum PromotionState {
    /// Instrumented; observes and records only. Does not alter execution.
    Observe,
    /// Models behavior without changing the game's result.
    Shadow,
    /// Native implementation active behind a feature flag; parity corpus
    /// required.
    NativeExperimental,
    /// Native implementation is the default path.
    NativeDefault,
    /// A mature C implementation (Wine/vkd3d-proton/DXVK) is retained.
    Fallback,
}

impl PromotionState {
    /// All states in stable order (index = serialized index).
    pub const ALL: [PromotionState; 5] = [
        PromotionState::Observe,
        PromotionState::Shadow,
        PromotionState::NativeExperimental,
        PromotionState::NativeDefault,
        PromotionState::Fallback,
    ];

    /// Stable string name.
    pub const fn as_str(self) -> &'static str {
        match self {
            PromotionState::Observe => "observe",
            PromotionState::Shadow => "shadow",
            PromotionState::NativeExperimental => "native_experimental",
            PromotionState::NativeDefault => "native_default",
            PromotionState::Fallback => "fallback",
        }
    }

    /// Whether this state counts as "Katra native" for coverage reporting.
    pub const fn is_native(self) -> bool {
        matches!(self, PromotionState::NativeExperimental | PromotionState::NativeDefault)
    }

    /// Whether this state counts as "legacy fallback" for coverage reporting.
    pub const fn is_fallback(self) -> bool {
        matches!(self, PromotionState::Fallback)
    }

    /// Whether this state alters execution (vs. pure observation).
    pub const fn alters_execution(self) -> bool {
        matches!(self, PromotionState::NativeExperimental | PromotionState::NativeDefault)
    }
}

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