stateknot_core/
budget_reservation.rs1use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
7use serde::{Deserialize, Deserializer, Serialize, de};
8use thiserror::Error;
9
10use crate::{
11 BudgetDimension, BudgetEvaluationError, BudgetRemaining, BudgetUsage, BudgetUsageError,
12 CostCollectionError, ExecutionCount, KnownCosts, ResolvedBudget, Timestamp,
13};
14
15#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
29#[serde(deny_unknown_fields)]
30pub struct CumulativeBudgetReservation {
31 #[schemars(schema_with = "amount_schema")]
32 amount: BudgetUsage,
33}
34
35fn amount_schema(generator: &mut SchemaGenerator) -> Schema {
36 json_schema!({
37 "allOf": [
38 generator.subschema_for::<BudgetUsage>(),
39 {"properties": {
40 "graph_depth": {"const": "0"},
41 "concurrent_branches": {"const": "0"},
42 "fan_out": {"const": "0"},
43 "unpriced_cost_events": {"const": "0"}
44 }}
45 ]
46 })
47}
48
49impl CumulativeBudgetReservation {
50 pub const MAX_RESERVATIONS: usize = 256;
54
55 pub fn new(amount: BudgetUsage) -> Result<Self, CumulativeBudgetReservationError> {
61 for (dimension, count) in [
62 (BudgetDimension::GraphDepth, amount.graph_depth()),
63 (
64 BudgetDimension::ConcurrentBranches,
65 amount.concurrent_branches(),
66 ),
67 (BudgetDimension::FanOut, amount.fan_out()),
68 ] {
69 if count != ExecutionCount::ZERO {
70 return Err(CumulativeBudgetReservationError::HighWaterDimension { dimension });
71 }
72 }
73 if amount.unpriced_cost_events() != ExecutionCount::ZERO {
74 return Err(CumulativeBudgetReservationError::UnpricedCost);
75 }
76 Ok(Self { amount })
77 }
78
79 pub fn from_budget(budget: &ResolvedBudget) -> Result<Self, CumulativeBudgetReservationError> {
85 Self::new(
86 BudgetUsage::builder()
87 .graph_steps(budget.graph_steps())
88 .model_attempts(budget.model_attempts())
89 .model_turns(budget.model_turns())
90 .input_tokens(budget.input_tokens())
91 .cached_input_tokens(budget.cached_input_tokens())
92 .reasoning_tokens(budget.reasoning_tokens())
93 .output_tokens(budget.output_tokens())
94 .tool_calls(budget.tool_calls())
95 .write_calls(budget.write_calls())
96 .remote_agent_delegations(budget.remote_agent_delegations())
97 .retries(budget.retries())
98 .input_bytes(budget.input_bytes())
99 .output_bytes(budget.output_bytes())
100 .event_bytes(budget.event_bytes())
101 .checkpoint_bytes(budget.checkpoint_bytes())
102 .artifact_bytes(budget.artifact_bytes())
103 .known_costs(KnownCosts::try_new(budget.costs().iter().copied())?)
104 .build()?,
105 )
106 }
107
108 #[must_use]
112 pub const fn amount(&self) -> &BudgetUsage {
113 &self.amount
114 }
115
116 pub fn check_capacity(
128 parent: &ResolvedBudget,
129 accounted: &BudgetUsage,
130 outstanding: &[Self],
131 observed_at: Timestamp,
132 ) -> Result<BudgetRemaining, CumulativeBudgetReservationError> {
133 if outstanding.len() > Self::MAX_RESERVATIONS {
134 return Err(CumulativeBudgetReservationError::TooManyReservations);
135 }
136 let mut projected = accounted.clone();
137 for reservation in outstanding {
138 projected = projected.checked_accumulate(&reservation.amount)?;
139 }
140 Ok(parent.remaining(&projected, observed_at)?)
141 }
142}
143
144impl<'de> Deserialize<'de> for CumulativeBudgetReservation {
145 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
146 where
147 D: Deserializer<'de>,
148 {
149 #[derive(Deserialize)]
150 #[serde(deny_unknown_fields)]
151 struct Wire {
152 amount: BudgetUsage,
153 }
154 Self::new(Wire::deserialize(deserializer)?.amount).map_err(de::Error::custom)
155 }
156}
157
158#[derive(Clone, Debug, Eq, Error, PartialEq)]
160#[non_exhaustive]
161pub enum CumulativeBudgetReservationError {
162 #[error("cannot cumulatively reserve high-water dimension {dimension:?}")]
164 HighWaterDimension {
165 dimension: BudgetDimension,
167 },
168 #[error("cannot reserve unpriced activity as known cumulative cost")]
170 UnpricedCost,
171 #[error("too many outstanding cumulative budget reservations")]
173 TooManyReservations,
174 #[error(transparent)]
176 Usage(#[from] BudgetUsageError),
177 #[error(transparent)]
179 Costs(#[from] CostCollectionError),
180 #[error(transparent)]
182 Capacity(#[from] BudgetEvaluationError),
183}
184
185#[cfg(test)]
186#[path = "budget_reservation_tests.rs"]
187mod tests;