use std::collections::BTreeSet;
use schemars::{JsonSchema, Schema, SchemaGenerator, json_schema};
use serde::{Deserialize, Deserializer, Serialize, de};
use thiserror::Error;
use crate::{
AgentAdmission, AgentResultProvenance, BudgetNarrowingError, BudgetRemaining, BudgetUsage,
BudgetUsageError, ChildRunAdmissionIntent, ChildRunKey, ChildRunPolicyError, CompiledGraph,
CumulativeBudgetReservation, CumulativeBudgetReservationError, Digest, ExecutionCount,
GraphReference, JournalHead, ResolvedBudget, RunLifecycle, RunStatus, Timestamp,
};
const DOMAIN: &[u8] = b"stateknot.child-run-budget-account.v1\0";
#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ChildRunBudgetSettlement {
child: AgentResultProvenance,
intent_digest: Digest,
admission_digest: Digest,
admitted_at: Timestamp,
terminal: JournalHead,
#[schemars(schema_with = "terminal_status_schema")]
status: RunStatus,
outcome_digest: Digest,
#[schemars(schema_with = "priced_usage_schema")]
usage: BudgetUsage,
}
fn terminal_status_schema(_: &mut SchemaGenerator) -> Schema {
json_schema!({"type":"string","enum":["succeeded","failed","cancelled"]})
}
fn priced_usage_schema(generator: &mut SchemaGenerator) -> Schema {
json_schema!({"allOf":[generator.subschema_for::<BudgetUsage>(),
{"properties":{"unpriced_cost_events":{"const":"0"}}}]})
}
impl ChildRunBudgetSettlement {
pub fn new(
admission: &AgentAdmission,
lifecycle: &RunLifecycle,
terminal: JournalHead,
) -> Result<Self, ChildRunBudgetError> {
if lifecycle.provenance() != admission.intent().provenance()
|| lifecycle.admitted_at() != admission.admitted_at()
|| lifecycle.changed_at() > terminal.recorded_at()
{
return Err(ChildRunBudgetError::TerminalMismatch);
}
let usage = lifecycle
.terminal_usage()
.ok_or(ChildRunBudgetError::NotTerminal)?;
let mut preimage = b"stateknot.child-run-budget-terminal.v1\0".to_vec();
preimage.extend(
crate::agent_admission::canonical_bytes(lifecycle)
.map_err(|_| ChildRunBudgetError::Encoding)?,
);
let outcome_digest = Digest::sha256(preimage);
let value = Self {
child: admission.intent().provenance().clone(),
intent_digest: admission.intent().intent_digest(),
admission_digest: admission.digest(),
admitted_at: admission.admitted_at(),
terminal,
status: lifecycle.status(),
outcome_digest,
usage: usage.clone(),
};
value.validate()?;
Ok(value)
}
fn validate(&self) -> Result<(), ChildRunBudgetError> {
if !self.status.is_terminal() {
return Err(ChildRunBudgetError::NotTerminal);
}
if self.child.tenant_id() != self.terminal.tenant_id()
|| self.child.run_id() != self.terminal.run_id()
|| self.terminal.recorded_at() < self.admitted_at
|| self.terminal.sequence().get() <= 1
{
return Err(ChildRunBudgetError::TerminalMismatch);
}
if self.usage.unpriced_cost_events() != ExecutionCount::ZERO {
return Err(ChildRunBudgetError::UnpricedSettlement);
}
Ok(())
}
#[must_use]
pub const fn terminal(&self) -> &JournalHead {
&self.terminal
}
#[must_use]
pub const fn usage(&self) -> &BudgetUsage {
&self.usage
}
#[must_use]
pub const fn outcome_digest(&self) -> Digest {
self.outcome_digest
}
#[must_use]
pub const fn admission_digest(&self) -> Digest {
self.admission_digest
}
}
impl<'de> Deserialize<'de> for ChildRunBudgetSettlement {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
child: AgentResultProvenance,
intent_digest: Digest,
admission_digest: Digest,
admitted_at: Timestamp,
terminal: JournalHead,
status: RunStatus,
outcome_digest: Digest,
usage: BudgetUsage,
}
let wire = Wire::deserialize(deserializer)?;
let value = Self {
child: wire.child,
intent_digest: wire.intent_digest,
admission_digest: wire.admission_digest,
admitted_at: wire.admitted_at,
terminal: wire.terminal,
status: wire.status,
outcome_digest: wire.outcome_digest,
usage: wire.usage,
};
value.validate().map_err(de::Error::custom)?;
Ok(value)
}
}
#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ChildRunBudgetEntry {
key: ChildRunKey,
spawn_digest: Digest,
child: AgentResultProvenance,
intent_digest: Digest,
reservation: CumulativeBudgetReservation,
settlement: Option<ChildRunBudgetSettlement>,
}
impl ChildRunBudgetEntry {
fn validate(&self) -> Result<(), ChildRunBudgetError> {
if self.key.tenant_id() != self.child.tenant_id()
|| self.key.parent_run_id() == self.child.run_id()
{
return Err(ChildRunBudgetError::ParentMismatch);
}
if let Some(settlement) = &self.settlement {
settlement.validate()?;
if settlement.child != self.child || settlement.intent_digest != self.intent_digest {
return Err(ChildRunBudgetError::TerminalMismatch);
}
}
Ok(())
}
#[must_use]
pub const fn key(&self) -> &ChildRunKey {
&self.key
}
#[must_use]
pub const fn child(&self) -> &AgentResultProvenance {
&self.child
}
#[must_use]
pub const fn spawn_digest(&self) -> Digest {
self.spawn_digest
}
#[must_use]
pub const fn intent_digest(&self) -> Digest {
self.intent_digest
}
#[must_use]
pub const fn reservation(&self) -> &CumulativeBudgetReservation {
&self.reservation
}
#[must_use]
pub const fn settlement(&self) -> Option<&ChildRunBudgetSettlement> {
self.settlement.as_ref()
}
}
impl<'de> Deserialize<'de> for ChildRunBudgetEntry {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
key: ChildRunKey,
spawn_digest: Digest,
child: AgentResultProvenance,
intent_digest: Digest,
reservation: CumulativeBudgetReservation,
settlement: Option<ChildRunBudgetSettlement>,
}
let wire = Wire::deserialize(deserializer)?;
let value = Self {
key: wire.key,
spawn_digest: wire.spawn_digest,
child: wire.child,
intent_digest: wire.intent_digest,
reservation: wire.reservation,
settlement: wire.settlement,
};
value.validate().map_err(de::Error::custom)?;
Ok(value)
}
}
#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ChildRunBudgetAccount {
#[schemars(range(min = 1, max = 1))]
version: u8,
parent: AgentResultProvenance,
parent_admission_digest: Digest,
parent_admitted_at: Timestamp,
graph: GraphReference,
budget: ResolvedBudget,
#[schemars(range(min = 1, max = 256))]
maximum_children: u16,
direct_head: JournalHead,
direct_usage: BudgetUsage,
#[schemars(length(max = 256))]
children: Vec<ChildRunBudgetEntry>,
digest: Digest,
}
impl ChildRunBudgetAccount {
pub const MAX_CHILDREN: usize = 256;
pub const MAX_SNAPSHOT_BYTES: usize = 8 * 1024 * 1024;
pub fn new(
parent: &AgentAdmission,
graph: &CompiledGraph,
direct_head: JournalHead,
direct_usage: BudgetUsage,
) -> Result<Self, ChildRunBudgetError> {
let policy = graph
.child_runs()
.ok_or(ChildRunBudgetError::ParentMismatch)?;
if direct_head.recorded_at() < parent.admitted_at() {
return Err(ChildRunBudgetError::DirectObservationMismatch);
}
let value = Self {
version: 1,
parent: parent.intent().provenance().clone(),
parent_admission_digest: parent.digest(),
parent_admitted_at: parent.admitted_at(),
graph: graph.reference(),
budget: parent.intent().budget().clone(),
maximum_children: policy.limits().maximum_children_per_run(),
direct_head,
direct_usage,
children: Vec::new(),
digest: Digest::sha256([]),
}
.seal()?;
value.validate_for(parent, graph)?;
Ok(value)
}
pub fn validate_for(
&self,
parent: &AgentAdmission,
graph: &CompiledGraph,
) -> Result<(), ChildRunBudgetError> {
if self.parent != *parent.intent().provenance()
|| self.parent_admission_digest != parent.digest()
|| self.parent_admitted_at != parent.admitted_at()
|| self.graph != *parent.intent().graph()
|| self.graph != graph.reference()
|| self.budget != *parent.intent().budget()
|| graph
.child_runs()
.map(|policy| policy.limits().maximum_children_per_run())
!= Some(self.maximum_children)
|| self.direct_head.recorded_at() < parent.admitted_at()
{
return Err(ChildRunBudgetError::ParentMismatch);
}
Ok(())
}
pub fn reserve(
&self,
intent: &ChildRunAdmissionIntent,
parent_graph: &CompiledGraph,
observed_at: Timestamp,
) -> Result<Self, ChildRunBudgetError> {
if intent.parent_admission_digest() != self.parent_admission_digest
|| intent.key().tenant_id() != self.parent.tenant_id()
|| intent.key().parent_run_id() != self.parent.run_id()
|| intent.key().parent().base_checkpoint().graph() != &self.graph
|| parent_graph.reference() != self.graph
{
return Err(ChildRunBudgetError::ParentMismatch);
}
intent.validate_declaration(parent_graph)?;
intent.child().budget().validate_narrowing(&self.budget)?;
if let Some(existing) = self.entry(intent.key()) {
return if existing.spawn_digest == intent.spawn_digest() {
Ok(self.clone())
} else {
Err(ChildRunBudgetError::SpawnConflict)
};
}
if self.children.len() >= usize::from(self.maximum_children) {
return Err(ChildRunBudgetError::TooManyChildren);
}
let mut next = self.clone();
next.children.push(ChildRunBudgetEntry {
key: intent.key().clone(),
spawn_digest: intent.spawn_digest(),
child: intent.child().provenance().clone(),
intent_digest: intent.child().intent_digest(),
reservation: CumulativeBudgetReservation::from_budget(intent.child().budget())?,
settlement: None,
});
next.remaining(observed_at)?;
next.seal()
}
pub fn settle(
&self,
key: &ChildRunKey,
settlement: ChildRunBudgetSettlement,
) -> Result<Self, ChildRunBudgetError> {
settlement.validate()?;
let index = self
.children
.iter()
.position(|entry| &entry.key == key)
.ok_or(ChildRunBudgetError::ChildNotFound)?;
let entry = &self.children[index];
if entry.child != settlement.child || entry.intent_digest != settlement.intent_digest {
return Err(ChildRunBudgetError::TerminalMismatch);
}
if settlement.admitted_at < self.parent_admitted_at {
return Err(ChildRunBudgetError::TerminalMismatch);
}
if let Some(existing) = &entry.settlement {
return if existing == &settlement {
Ok(self.clone())
} else {
Err(ChildRunBudgetError::SettlementConflict)
};
}
let mut next = self.clone();
next.children[index].settlement = Some(settlement);
next.seal()
}
pub fn observe_direct(
&self,
head: JournalHead,
usage: BudgetUsage,
) -> Result<Self, ChildRunBudgetError> {
if head == self.direct_head && usage == self.direct_usage {
return Ok(self.clone());
}
if head.tenant_id() != self.parent.tenant_id()
|| head.run_id() != self.parent.run_id()
|| head.sequence() <= self.direct_head.sequence()
|| head.recorded_at() < self.direct_head.recorded_at()
{
return Err(ChildRunBudgetError::DirectObservationMismatch);
}
usage.validate_monotonic_after(&self.direct_usage)?;
let mut next = self.clone();
next.direct_head = head;
next.direct_usage = usage;
next.seal()
}
pub fn delegated_usage(&self) -> Result<BudgetUsage, ChildRunBudgetError> {
let mut total = BudgetUsage::zero();
for entry in &self.children {
if let Some(settlement) = &entry.settlement {
total = total.checked_accumulate(&settlement.usage.cumulative_only())?;
}
}
Ok(total)
}
pub fn accounted_usage(&self) -> Result<BudgetUsage, ChildRunBudgetError> {
Ok(self
.direct_usage
.checked_accumulate(&self.delegated_usage()?)?)
}
pub fn remaining(
&self,
observed_at: Timestamp,
) -> Result<BudgetRemaining, ChildRunBudgetError> {
if observed_at < self.direct_head.recorded_at()
|| self
.children
.iter()
.filter_map(|entry| entry.settlement.as_ref())
.any(|settlement| observed_at < settlement.terminal.recorded_at())
{
return Err(ChildRunBudgetError::ClockBeforeEvidence);
}
let outstanding: Vec<_> = self
.children
.iter()
.filter(|entry| entry.settlement.is_none())
.map(|entry| entry.reservation.clone())
.collect();
Ok(CumulativeBudgetReservation::check_capacity(
&self.budget,
&self.accounted_usage()?,
&outstanding,
observed_at,
)?)
}
#[must_use]
pub fn entry(&self, key: &ChildRunKey) -> Option<&ChildRunBudgetEntry> {
self.children.iter().find(|entry| &entry.key == key)
}
#[must_use]
pub fn children(&self) -> &[ChildRunBudgetEntry] {
&self.children
}
#[must_use]
pub const fn direct_usage(&self) -> &BudgetUsage {
&self.direct_usage
}
#[must_use]
pub const fn direct_head(&self) -> &JournalHead {
&self.direct_head
}
#[must_use]
pub const fn digest(&self) -> Digest {
self.digest
}
pub fn canonical_bytes(&self) -> Result<Vec<u8>, ChildRunBudgetError> {
let bytes = crate::agent_admission::canonical_bytes(self)
.map_err(|_| ChildRunBudgetError::Encoding)?;
if bytes.len() > Self::MAX_SNAPSHOT_BYTES {
return Err(ChildRunBudgetError::Encoding);
}
Ok(bytes)
}
fn seal(mut self) -> Result<Self, ChildRunBudgetError> {
if self.version != 1 {
return Err(ChildRunBudgetError::UnsupportedVersion);
}
if self.maximum_children == 0
|| usize::from(self.maximum_children) > Self::MAX_CHILDREN
|| self.children.len() > usize::from(self.maximum_children)
{
return Err(ChildRunBudgetError::TooManyChildren);
}
if self.direct_head.tenant_id() != self.parent.tenant_id()
|| self.direct_head.run_id() != self.parent.run_id()
|| self.direct_head.recorded_at() < self.parent_admitted_at
{
return Err(ChildRunBudgetError::DirectObservationMismatch);
}
self.children.sort_by_key(|entry| entry.key.digest());
let mut keys = BTreeSet::new();
let mut runs = BTreeSet::new();
for entry in &self.children {
entry.validate()?;
if entry.key.tenant_id() != self.parent.tenant_id()
|| entry.key.parent_run_id() != self.parent.run_id()
|| entry.key.parent().base_checkpoint().graph() != &self.graph
|| entry.child.tenant_id() != self.parent.tenant_id()
|| entry.child.run_id() == self.parent.run_id()
{
return Err(ChildRunBudgetError::ParentMismatch);
}
if !keys.insert(entry.key.digest()) || !runs.insert(entry.child.run_id()) {
return Err(ChildRunBudgetError::DuplicateChild);
}
if let Some(settlement) = &entry.settlement {
if settlement.admitted_at < self.parent_admitted_at {
return Err(ChildRunBudgetError::TerminalMismatch);
}
}
}
self.accounted_usage()?;
self.digest = Digest::sha256([]);
let mut preimage = DOMAIN.to_vec();
preimage.extend(self.canonical_bytes()?);
self.digest = Digest::sha256(preimage);
Ok(self)
}
}
impl<'de> Deserialize<'de> for ChildRunBudgetAccount {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
version: u8,
parent: AgentResultProvenance,
parent_admission_digest: Digest,
parent_admitted_at: Timestamp,
graph: GraphReference,
budget: ResolvedBudget,
maximum_children: u16,
direct_head: JournalHead,
direct_usage: BudgetUsage,
#[serde(deserialize_with = "bounded_children")]
children: Vec<ChildRunBudgetEntry>,
digest: Digest,
}
let wire = Wire::deserialize(deserializer)?;
let expected = wire.digest;
let value = Self {
version: wire.version,
parent: wire.parent,
parent_admission_digest: wire.parent_admission_digest,
parent_admitted_at: wire.parent_admitted_at,
graph: wire.graph,
budget: wire.budget,
maximum_children: wire.maximum_children,
direct_head: wire.direct_head,
direct_usage: wire.direct_usage,
children: wire.children,
digest: expected,
}
.seal()
.map_err(de::Error::custom)?;
if value.digest != expected {
return Err(de::Error::custom(ChildRunBudgetError::DigestMismatch));
}
Ok(value)
}
}
fn bounded_children<'de, D: Deserializer<'de>>(
deserializer: D,
) -> Result<Vec<ChildRunBudgetEntry>, D::Error> {
struct Visitor;
impl<'de> de::Visitor<'de> for Visitor {
type Value = Vec<ChildRunBudgetEntry>;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("at most 256 lifetime child budget entries")
}
fn visit_seq<A: de::SeqAccess<'de>>(
self,
mut sequence: A,
) -> Result<Self::Value, A::Error> {
let maximum = ChildRunBudgetAccount::MAX_CHILDREN;
if sequence.size_hint().is_some_and(|size| size > maximum) {
return Err(de::Error::custom(ChildRunBudgetError::TooManyChildren));
}
let mut values = Vec::with_capacity(sequence.size_hint().unwrap_or(0).min(maximum));
while let Some(value) = sequence.next_element()? {
if values.len() == maximum {
return Err(de::Error::custom(ChildRunBudgetError::TooManyChildren));
}
values.push(value);
}
Ok(values)
}
}
deserializer.deserialize_seq(Visitor)
}
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ChildRunBudgetError {
#[error("child budget parent mismatch")]
ParentMismatch,
#[error("unsupported child budget account version")]
UnsupportedVersion,
#[error("child budget lifetime bound exceeded")]
TooManyChildren,
#[error("duplicate child budget identity")]
DuplicateChild,
#[error("child budget spawn conflict")]
SpawnConflict,
#[error("child budget settlement conflict")]
SettlementConflict,
#[error("child budget reservation not found")]
ChildNotFound,
#[error("child budget requires terminal evidence")]
NotTerminal,
#[error("child budget terminal evidence mismatch")]
TerminalMismatch,
#[error("child budget cannot settle unpriced usage")]
UnpricedSettlement,
#[error("child budget direct observation mismatch")]
DirectObservationMismatch,
#[error("child budget clock predates accounting evidence")]
ClockBeforeEvidence,
#[error("child budget account encoding failed")]
Encoding,
#[error("child budget account digest mismatch")]
DigestMismatch,
#[error(transparent)]
Usage(#[from] BudgetUsageError),
#[error(transparent)]
Reservation(#[from] CumulativeBudgetReservationError),
#[error(transparent)]
Declaration(#[from] ChildRunPolicyError),
#[error(transparent)]
Narrowing(#[from] BudgetNarrowingError),
}