1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
// Copyright 2026 StateKnot contributors
// SPDX-License-Identifier: Apache-2.0
//! Pure cumulative-capacity arithmetic, separate from durable reservation.
use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::{Deserialize, Deserializer, Serialize, de};
use thiserror::Error;
use crate::{
BudgetDimension, BudgetEvaluationError, BudgetRemaining, BudgetUsage, BudgetUsageError,
CostCollectionError, ExecutionCount, KnownCosts, ResolvedBudget, Timestamp,
};
/// An immutable ceiling reserved for cumulative work, not observed usage.
///
/// All cumulative dimensions, inclusive token/call subsets, and configured
/// currencies are reserved. High-water dimensions (`graph_depth`,
/// `concurrent_branches`, `fan_out`) are deliberately absent (zero in the
/// underlying amount); topology and live concurrency require their own
/// admission checks. Unknown price is never a zero-cost reservation.
///
/// This value does not reserve database capacity. A durable caller must bind
/// it to one ownership key and atomically check the complete set of current
/// reservations and accounted usage while serializing competing admissions
/// and direct-work budget consumption. Never persist the projected capacity
/// from [`Self::check_capacity`] as actual usage.
#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct CumulativeBudgetReservation {
#[schemars(schema_with = "amount_schema")]
amount: BudgetUsage,
}
fn amount_schema(generator: &mut SchemaGenerator) -> Schema {
json_schema!({
"allOf": [
generator.subschema_for::<BudgetUsage>(),
{"properties": {
"graph_depth": {"const": "0"},
"concurrent_branches": {"const": "0"},
"fan_out": {"const": "0"},
"unpriced_cost_events": {"const": "0"}
}}
]
})
}
impl CumulativeBudgetReservation {
/// Maximum reservation count accepted by one bounded capacity check.
///
/// This is an arithmetic work bound, not an implemented child fan-out limit.
pub const MAX_RESERVATIONS: usize = 256;
/// Constructs a reservation from explicit cumulative ceilings.
///
/// Rejects high-water dimensions and unpriced activity. Subset and integer
/// validation is inherited from [`BudgetUsage`]. Zero denies further
/// cumulative work; it does not mean unlimited capacity.
pub fn new(amount: BudgetUsage) -> Result<Self, CumulativeBudgetReservationError> {
for (dimension, count) in [
(BudgetDimension::GraphDepth, amount.graph_depth()),
(
BudgetDimension::ConcurrentBranches,
amount.concurrent_branches(),
),
(BudgetDimension::FanOut, amount.fan_out()),
] {
if count != ExecutionCount::ZERO {
return Err(CumulativeBudgetReservationError::HighWaterDimension { dimension });
}
}
if amount.unpriced_cost_events() != ExecutionCount::ZERO {
return Err(CumulativeBudgetReservationError::UnpricedCost);
}
Ok(Self { amount })
}
/// Reserves every cumulative ceiling from an already finite budget.
///
/// Does not copy the deadline or high-water limits. Child deadline,
/// authority, ancestry, and concurrency narrowing must be checked apart
/// from this arithmetic projection.
pub fn from_budget(budget: &ResolvedBudget) -> Result<Self, CumulativeBudgetReservationError> {
Self::new(
BudgetUsage::builder()
.graph_steps(budget.graph_steps())
.model_attempts(budget.model_attempts())
.model_turns(budget.model_turns())
.input_tokens(budget.input_tokens())
.cached_input_tokens(budget.cached_input_tokens())
.reasoning_tokens(budget.reasoning_tokens())
.output_tokens(budget.output_tokens())
.tool_calls(budget.tool_calls())
.write_calls(budget.write_calls())
.remote_agent_delegations(budget.remote_agent_delegations())
.retries(budget.retries())
.input_bytes(budget.input_bytes())
.output_bytes(budget.output_bytes())
.event_bytes(budget.event_bytes())
.checkpoint_bytes(budget.checkpoint_bytes())
.artifact_bytes(budget.artifact_bytes())
.known_costs(KnownCosts::try_new(budget.costs().iter().copied())?)
.build()?,
)
}
/// Returns reserved ceilings encoded using the validated usage dimensions.
///
/// These amounts are not evidence of spent tokens, calls, bytes, or money.
#[must_use]
pub const fn amount(&self) -> &BudgetUsage {
&self.amount
}
/// Checks accounted usage plus all outstanding reservations, including any
/// proposed new reservation, against the parent budget at a supplied clock.
///
/// `accounted` must include direct usage and settled child usage exactly
/// once, but exclude these outstanding reservations. Uses checked addition
/// and rejects unknown price, unsupported currencies, excess limits, and
/// expired deadlines. Existing high-water usage is checked, not decremented
/// per child. Duplicate entries are charged twice, never silently deduped.
///
/// This pure check neither owns a lock nor proves a durable snapshot is
/// complete. Commit-time atomicity is the storage adapter's responsibility.
pub fn check_capacity(
parent: &ResolvedBudget,
accounted: &BudgetUsage,
outstanding: &[Self],
observed_at: Timestamp,
) -> Result<BudgetRemaining, CumulativeBudgetReservationError> {
if outstanding.len() > Self::MAX_RESERVATIONS {
return Err(CumulativeBudgetReservationError::TooManyReservations);
}
let mut projected = accounted.clone();
for reservation in outstanding {
projected = projected.checked_accumulate(&reservation.amount)?;
}
Ok(parent.remaining(&projected, observed_at)?)
}
}
impl<'de> Deserialize<'de> for CumulativeBudgetReservation {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
amount: BudgetUsage,
}
Self::new(Wire::deserialize(deserializer)?.amount).map_err(de::Error::custom)
}
}
/// Invalid cumulative reservation or insufficient projected budget capacity.
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum CumulativeBudgetReservationError {
/// A peak topology count cannot be reserved as cumulative expenditure.
#[error("cannot cumulatively reserve high-water dimension {dimension:?}")]
HighWaterDimension {
/// The rejected non-cumulative dimension.
dimension: BudgetDimension,
},
/// Unknown external price cannot be treated as a finite known reservation.
#[error("cannot reserve unpriced activity as known cumulative cost")]
UnpricedCost,
/// One check exceeded its bounded amount of arithmetic work.
#[error("too many outstanding cumulative budget reservations")]
TooManyReservations,
/// Checked scalar addition, currency union, or subset validation failed.
#[error(transparent)]
Usage(#[from] BudgetUsageError),
/// A currency-specific reservation was invalid.
#[error(transparent)]
Costs(#[from] CostCollectionError),
/// The projected capacity exceeds a ceiling or cannot be evaluated safely.
#[error(transparent)]
Capacity(#[from] BudgetEvaluationError),
}
#[cfg(test)]
#[path = "budget_reservation_tests.rs"]
mod tests;