khora_core/control/
gorna.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//! Types and traits for the Goal-Oriented Resource Negotiation & Allocation (GORNA) protocol.
16
17use serde::{Deserialize, Serialize};
18use std::collections::HashMap;
19use std::time::Duration;
20
21/// Unique identifier for engine agents with implicit priority ordering.
22///
23/// The order of variants defines the default execution priority (first = highest).
24#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, PartialOrd, Ord)]
25pub enum AgentId {
26    /// The primary rendering agent (highest priority in Simulation).
27    Renderer,
28    /// The physics simulation agent.
29    Physics,
30    /// The ECS/Logic coordination agent.
31    Ecs,
32    /// The audio processing agent.
33    Audio,
34    /// The asset management agent (highest priority in Boot).
35    Asset,
36}
37
38impl std::fmt::Display for AgentId {
39    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
40        write!(f, "{:?}", self)
41    }
42}
43
44/// Generic strategy identifier for budget allocation.
45#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
46pub enum StrategyId {
47    /// Minimum resource usage, lowest quality/frequency.
48    LowPower,
49    /// Balanced resource usage.
50    Balanced,
51    /// High resource usage, maximum quality/performance.
52    HighPerformance,
53    /// Custom ID for agent-specific strategies.
54    /// Used when the predefined levels aren't sufficient.
55    Custom(u32),
56}
57
58/// Hard resource constraints the DCC imposes on an Agent during negotiation.
59///
60/// These represent non-negotiable limits that any proposed strategy must respect.
61#[derive(Debug, Clone, Default)]
62pub struct ResourceConstraints {
63    /// Maximum VRAM usage allowed, in bytes. `None` means unconstrained.
64    pub max_vram_bytes: Option<u64>,
65    /// Maximum system memory allowed, in bytes. `None` means unconstrained.
66    pub max_memory_bytes: Option<u64>,
67    /// If `true`, this agent is critical and must always execute (e.g. physics in Simulation).
68    pub must_run: bool,
69}
70
71/// A request sent by the DCC to an Agent to negotiate resources.
72#[derive(Debug, Clone)]
73pub struct NegotiationRequest {
74    /// The target latency for the frame or subsystem (e.g. 16.6ms).
75    pub target_latency: Duration,
76    /// Priority weight (0.0 to 1.0) assigned by the DCC.
77    pub priority_weight: f32,
78    /// Hard resource constraints that any proposed strategy must respect.
79    pub constraints: ResourceConstraints,
80}
81
82/// A response from an Agent offering various execution strategies.
83#[derive(Debug, Clone)]
84pub struct NegotiationResponse {
85    /// List of available strategies and their estimated costs.
86    pub strategies: Vec<StrategyOption>,
87}
88
89/// A specific execution strategy offered by an Agent.
90#[derive(Debug, Clone)]
91pub struct StrategyOption {
92    /// Unique identifier for the strategy.
93    pub id: StrategyId,
94    /// Expected cost in time.
95    pub estimated_time: Duration,
96    /// Expected cost in VRAM.
97    pub estimated_vram: u64,
98}
99
100/// An allocated resource budget issued by the DCC to an Agent.
101#[derive(Debug, Clone)]
102pub struct ResourceBudget {
103    /// The strategy ID to be applied.
104    pub strategy_id: StrategyId,
105    /// Maximum time allowed for execution.
106    pub time_limit: Duration,
107    /// Maximum VRAM budget in bytes, if constrained.
108    pub memory_limit: Option<u64>,
109    /// Additional ISA-specific parameters.
110    pub extra_params: HashMap<String, String>,
111}
112
113/// A snapshot of an Agent's current health and performance.
114#[derive(Debug, Clone)]
115pub struct AgentStatus {
116    /// The ID of the reporting agent.
117    pub agent_id: AgentId,
118    /// The strategy currently being executed.
119    pub current_strategy: StrategyId,
120    /// Health score (0.0 to 1.0). 1.0 means adhering perfectly to budget.
121    pub health_score: f32,
122    /// True if the agent is blocked or failed to execute.
123    pub is_stalled: bool,
124    /// Human-readable status message for telemetry.
125    pub message: String,
126}
khora_core/control/gorna.rs

khora_core/control/
gorna.rs
