katra_core/
subsystem.rs

1//! Subsystems and promotion states.
2//!
3//! Every Katra subsystem travels through the promotion pipeline
4//! (`OBSERVE → SHADOW → NATIVE_EXPERIMENTAL → NATIVE_DEFAULT`, with the
5//! `FALLBACK` state for mature C implementations retained as fallback).
6//! See `docs/standards/promotion-gates.md`.
7
8use serde::{Deserialize, Serialize};
9
10/// The named subsystems of Katra3D.
11#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
12#[serde(rename_all = "snake_case")]
13pub enum Subsystem {
14    /// Trace capture/writing.
15    Trace,
16    /// Report generation.
17    Report,
18    /// Trace replay.
19    Replay,
20    /// Semantic request graph.
21    Graph,
22    /// KatraFlow (inferred storage intent).
23    Flow,
24    /// Katra I/O (io_uring + backends).
25    Io,
26    /// Katra memory/residency.
27    Memory,
28    /// Katra synchronization.
29    Sync,
30    /// Unified scheduling.
31    Schedule,
32    /// DirectStorage frontend.
33    DStorage,
34    /// Shader service.
35    Shader,
36    /// Layered cache.
37    Cache,
38    /// D3D12 hot-path reconstruction.
39    D3d12,
40    /// Vulkan integration.
41    Vulkan,
42    /// Courts (falsifiable test corpus).
43    Courts,
44    /// C ABI (libkatra3d).
45    Abi,
46}
47
48impl Subsystem {
49    /// All subsystems in stable order.
50    pub const ALL: [Subsystem; 16] = [
51        Subsystem::Trace,
52        Subsystem::Report,
53        Subsystem::Replay,
54        Subsystem::Graph,
55        Subsystem::Flow,
56        Subsystem::Io,
57        Subsystem::Memory,
58        Subsystem::Sync,
59        Subsystem::Schedule,
60        Subsystem::DStorage,
61        Subsystem::Shader,
62        Subsystem::Cache,
63        Subsystem::D3d12,
64        Subsystem::Vulkan,
65        Subsystem::Courts,
66        Subsystem::Abi,
67    ];
68
69    /// Stable string name.
70    pub const fn as_str(self) -> &'static str {
71        match self {
72            Subsystem::Trace => "trace",
73            Subsystem::Report => "report",
74            Subsystem::Replay => "replay",
75            Subsystem::Graph => "graph",
76            Subsystem::Flow => "flow",
77            Subsystem::Io => "io",
78            Subsystem::Memory => "memory",
79            Subsystem::Sync => "sync",
80            Subsystem::Schedule => "schedule",
81            Subsystem::DStorage => "dstorage",
82            Subsystem::Shader => "shader",
83            Subsystem::Cache => "cache",
84            Subsystem::D3d12 => "d3d12",
85            Subsystem::Vulkan => "vulkan",
86            Subsystem::Courts => "courts",
87            Subsystem::Abi => "abi",
88        }
89    }
90}
91
92impl std::fmt::Display for Subsystem {
93    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
94        f.write_str(self.as_str())
95    }
96}
97
98/// The promotion state of a subsystem (§3.2, §20).
99#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
100#[serde(rename_all = "snake_case")]
101pub enum PromotionState {
102    /// Instrumented; observes and records only. Does not alter execution.
103    Observe,
104    /// Models behavior without changing the game's result.
105    Shadow,
106    /// Native implementation active behind a feature flag; parity corpus
107    /// required.
108    NativeExperimental,
109    /// Native implementation is the default path.
110    NativeDefault,
111    /// A mature C implementation (Wine/vkd3d-proton/DXVK) is retained.
112    Fallback,
113}
114
115impl PromotionState {
116    /// All states in stable order (index = serialized index).
117    pub const ALL: [PromotionState; 5] = [
118        PromotionState::Observe,
119        PromotionState::Shadow,
120        PromotionState::NativeExperimental,
121        PromotionState::NativeDefault,
122        PromotionState::Fallback,
123    ];
124
125    /// Stable string name.
126    pub const fn as_str(self) -> &'static str {
127        match self {
128            PromotionState::Observe => "observe",
129            PromotionState::Shadow => "shadow",
130            PromotionState::NativeExperimental => "native_experimental",
131            PromotionState::NativeDefault => "native_default",
132            PromotionState::Fallback => "fallback",
133        }
134    }
135
136    /// Whether this state counts as "Katra native" for coverage reporting.
137    pub const fn is_native(self) -> bool {
138        matches!(self, PromotionState::NativeExperimental | PromotionState::NativeDefault)
139    }
140
141    /// Whether this state counts as "legacy fallback" for coverage reporting.
142    pub const fn is_fallback(self) -> bool {
143        matches!(self, PromotionState::Fallback)
144    }
145
146    /// Whether this state alters execution (vs. pure observation).
147    pub const fn alters_execution(self) -> bool {
148        matches!(self, PromotionState::NativeExperimental | PromotionState::NativeDefault)
149    }
150}
151
152impl std::fmt::Display for PromotionState {
153    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
154        f.write_str(self.as_str())
155    }
156}
katra_core/subsystem.rs

katra_core/
subsystem.rs
