khora_core/agent/
execution_phase.rs

1// Copyright 2025 eraflo
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Execution phases for the frame pipeline.
16//!
17//! Each phase represents a stage in the frame execution order.
18//! Built-in phases have fixed IDs 0-5. Custom phases can be created
19//! with IDs 6-254 and inserted at any position via the Scheduler API.
20
21/// A phase in the frame execution pipeline.
22///
23/// Phases are executed in order. Built-in phases have fixed IDs 0-5.
24/// Custom phases can be inserted at any position via the Scheduler API.
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
26pub struct ExecutionPhase(u8);
27
28impl ExecutionPhase {
29    // Built-in phases — default order
30    /// Setup frame, reset state.
31    pub const INIT: Self = Self(0);
32    /// Read-only: extraction, analysis, observation.
33    pub const OBSERVE: Self = Self(1);
34    /// Simulation: physics, AI, logic transformations.
35    pub const TRANSFORM: Self = Self(2);
36    /// Write: sync results, update state, mutations.
37    pub const MUTATE: Self = Self(3);
38    /// External output: render, audio, UI.
39    pub const OUTPUT: Self = Self(4);
40    /// Cleanup, telemetry, end-of-frame tasks.
41    pub const FINALIZE: Self = Self(5);
42
43    /// Default phase order — used if no custom order is set.
44    pub const DEFAULT_ORDER: &'static [Self] = &[
45        Self::INIT,
46        Self::OBSERVE,
47        Self::TRANSFORM,
48        Self::MUTATE,
49        Self::OUTPUT,
50        Self::FINALIZE,
51    ];
52
53    /// Create a custom phase. IDs 6-254 are available for user phases.
54    /// ID 255 is reserved.
55    ///
56    /// # Panics
57    /// Panics if `id` is not in range 6..255.
58    #[must_use]
59    pub const fn custom(id: u8) -> Self {
60        assert!(
61            id > 5 && id < 255,
62            "Custom phase IDs must be in range 6..255"
63        );
64        Self(id)
65    }
66
67    /// Returns the raw ID of this phase.
68    #[must_use]
69    pub const fn id(&self) -> u8 {
70        self.0
71    }
72
73    /// Returns true if this is a built-in phase.
74    #[must_use]
75    pub const fn is_builtin(&self) -> bool {
76        self.0 <= 5
77    }
78}
79
80impl std::fmt::Display for ExecutionPhase {
81    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
82        match self.0 {
83            0 => write!(f, "Init"),
84            1 => write!(f, "Observe"),
85            2 => write!(f, "Transform"),
86            3 => write!(f, "Mutate"),
87            4 => write!(f, "Output"),
88            5 => write!(f, "Finalize"),
89            _ => write!(f, "Custom({})", self.0),
90        }
91    }
92}
khora_core/agent/execution_phase.rs

khora_core/agent/
execution_phase.rs
