use std::collections::BTreeMap;
use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize, de};
use thiserror::Error;
use crate::{
AgentDescriptor, CapabilityIdentity, ChildRunAdmissionIntent, ChildRunSlot, CompiledGraph,
Digest, GraphReference, NodeId, SchemaReference,
};
#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ChildAgentReference {
identity: CapabilityIdentity,
definition_digest: Digest,
}
impl ChildAgentReference {
pub fn from_descriptor(descriptor: &AgentDescriptor) -> Result<Self, ChildRunPolicyError> {
let canonical = crate::agent_admission::canonical_bytes(descriptor)
.map_err(|_| ChildRunPolicyError::AgentEncoding)?;
let mut bytes = b"stateknot.child-agent-definition.v1\0".to_vec();
bytes.extend_from_slice(&canonical);
Ok(Self {
identity: descriptor.metadata().identity().clone(),
definition_digest: Digest::sha256(bytes),
})
}
#[must_use]
pub const fn identity(&self) -> &CapabilityIdentity {
&self.identity
}
#[must_use]
pub const fn definition_digest(&self) -> Digest {
self.definition_digest
}
}
#[derive(Clone, Debug, Deserialize, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ChildRunDeclaration {
node_id: NodeId,
slot: ChildRunSlot,
agent: ChildAgentReference,
graph: GraphReference,
input_schema: SchemaReference,
output_schema: SchemaReference,
}
impl ChildRunDeclaration {
pub fn new(
node_id: NodeId,
slot: ChildRunSlot,
agent: &AgentDescriptor,
graph: &CompiledGraph,
) -> Result<Self, ChildRunPolicyError> {
if agent.input_schema() != graph.input_schema()
|| agent.output_schema() != graph.output_schema()
{
return Err(ChildRunPolicyError::TargetSchemaMismatch);
}
Ok(Self {
node_id,
slot,
agent: ChildAgentReference::from_descriptor(agent)?,
graph: graph.reference(),
input_schema: agent.input_schema().clone(),
output_schema: agent.output_schema().clone(),
})
}
#[must_use]
pub const fn node_id(&self) -> &NodeId {
&self.node_id
}
#[must_use]
pub const fn slot(&self) -> &ChildRunSlot {
&self.slot
}
#[must_use]
pub const fn agent(&self) -> &ChildAgentReference {
&self.agent
}
#[must_use]
pub const fn graph(&self) -> &GraphReference {
&self.graph
}
#[must_use]
pub const fn input_schema(&self) -> &SchemaReference {
&self.input_schema
}
#[must_use]
pub const fn output_schema(&self) -> &SchemaReference {
&self.output_schema
}
pub fn validate_target(
&self,
target: &CompiledGraph,
limits: ChildRunTopologyLimits,
) -> Result<(), ChildRunPolicyError> {
if &target.reference() != self.graph() {
return Err(ChildRunPolicyError::TargetGraphMismatch);
}
if target.input_schema() != self.input_schema()
|| target.output_schema() != self.output_schema()
{
return Err(ChildRunPolicyError::TargetSchemaMismatch);
}
let child_depth = target
.child_runs()
.map_or(0, |policy| policy.limits().maximum_descendant_depth());
if child_depth >= limits.maximum_descendant_depth() {
return Err(ChildRunPolicyError::DepthNotNarrowed);
}
Ok(())
}
}
#[derive(Clone, Copy, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
#[allow(clippy::struct_field_names)]
pub struct ChildRunTopologyLimits {
#[schemars(range(min = 1, max = 32))]
maximum_descendant_depth: u16,
#[schemars(range(min = 1, max = 256))]
maximum_children_per_run: u16,
#[schemars(range(min = 1, max = 256))]
maximum_active_descendants: u16,
}
impl ChildRunTopologyLimits {
pub const MAX_DEPTH: u16 = 32;
pub const MAX_CHILDREN: u16 = 256;
pub fn new(depth: u16, children: u16, active: u16) -> Result<Self, ChildRunPolicyError> {
if !(1..=Self::MAX_DEPTH).contains(&depth)
|| !(1..=Self::MAX_CHILDREN).contains(&children)
|| !(1..=Self::MAX_CHILDREN).contains(&active)
{
return Err(ChildRunPolicyError::InvalidLimits);
}
Ok(Self {
maximum_descendant_depth: depth,
maximum_children_per_run: children,
maximum_active_descendants: active,
})
}
#[must_use]
pub const fn maximum_descendant_depth(self) -> u16 {
self.maximum_descendant_depth
}
#[must_use]
pub const fn maximum_children_per_run(self) -> u16 {
self.maximum_children_per_run
}
#[must_use]
pub const fn maximum_active_descendants(self) -> u16 {
self.maximum_active_descendants
}
}
impl<'de> Deserialize<'de> for ChildRunTopologyLimits {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
#[allow(clippy::struct_field_names)]
struct Wire {
maximum_descendant_depth: u16,
maximum_children_per_run: u16,
maximum_active_descendants: u16,
}
let wire = Wire::deserialize(deserializer)?;
Self::new(
wire.maximum_descendant_depth,
wire.maximum_children_per_run,
wire.maximum_active_descendants,
)
.map_err(de::Error::custom)
}
}
#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct GraphChildRunPolicy {
#[schemars(range(min = 1, max = 1))]
version: u8,
limits: ChildRunTopologyLimits,
#[schemars(length(min = 1, max = 256))]
declarations: Box<[ChildRunDeclaration]>,
}
impl GraphChildRunPolicy {
pub const MAX_DECLARATIONS: usize = 256;
pub const MAX_SLOTS_PER_NODE: usize = 64;
pub fn new<I>(
limits: ChildRunTopologyLimits,
declarations: I,
) -> Result<Self, ChildRunPolicyError>
where
I: IntoIterator<Item = ChildRunDeclaration>,
{
let mut ordered = BTreeMap::new();
let mut per_node = BTreeMap::new();
for declaration in declarations {
if ordered.len() == Self::MAX_DECLARATIONS {
return Err(ChildRunPolicyError::TooManyDeclarations);
}
let count = per_node.entry(declaration.node_id.clone()).or_insert(0);
*count += 1;
if *count > Self::MAX_SLOTS_PER_NODE {
return Err(ChildRunPolicyError::TooManyNodeSlots);
}
let key = (declaration.node_id.clone(), declaration.slot.clone());
if ordered.insert(key, declaration).is_some() {
return Err(ChildRunPolicyError::DuplicateSlot);
}
}
if ordered.is_empty() {
return Err(ChildRunPolicyError::EmptyDeclarations);
}
Ok(Self {
version: 1,
limits,
declarations: ordered.into_values().collect(),
})
}
#[must_use]
pub const fn limits(&self) -> ChildRunTopologyLimits {
self.limits
}
#[must_use]
pub const fn declarations(&self) -> &[ChildRunDeclaration] {
&self.declarations
}
#[must_use]
pub fn declaration(&self, node: &NodeId, slot: &ChildRunSlot) -> Option<&ChildRunDeclaration> {
self.declarations
.binary_search_by(|value| (&value.node_id, &value.slot).cmp(&(node, slot)))
.ok()
.map(|index| &self.declarations[index])
}
pub(crate) fn validate_nodes(&self, graph: &CompiledGraph) -> Result<(), ChildRunPolicyError> {
if self
.declarations
.iter()
.any(|item| graph.node(item.node_id()).is_none())
{
return Err(ChildRunPolicyError::UndeclaredParentNode);
}
Ok(())
}
}
impl<'de> Deserialize<'de> for GraphChildRunPolicy {
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
version: u8,
limits: ChildRunTopologyLimits,
#[serde(deserialize_with = "bounded_declarations")]
declarations: Vec<ChildRunDeclaration>,
}
let wire = Wire::deserialize(deserializer)?;
if wire.version != 1 {
return Err(de::Error::custom(ChildRunPolicyError::UnsupportedVersion));
}
Self::new(wire.limits, wire.declarations).map_err(de::Error::custom)
}
}
fn bounded_declarations<'de, D: Deserializer<'de>>(
deserializer: D,
) -> Result<Vec<ChildRunDeclaration>, D::Error> {
struct Visitor;
impl<'de> de::Visitor<'de> for Visitor {
type Value = Vec<ChildRunDeclaration>;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("at most 256 child declarations")
}
fn visit_seq<A: de::SeqAccess<'de>>(
self,
mut sequence: A,
) -> Result<Self::Value, A::Error> {
let maximum = GraphChildRunPolicy::MAX_DECLARATIONS;
if sequence.size_hint().is_some_and(|size| size > maximum) {
return Err(de::Error::custom(ChildRunPolicyError::TooManyDeclarations));
}
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(ChildRunPolicyError::TooManyDeclarations));
}
values.push(value);
}
Ok(values)
}
}
deserializer.deserialize_seq(Visitor)
}
impl ChildRunAdmissionIntent {
pub fn validate_declaration(&self, parent: &CompiledGraph) -> Result<(), ChildRunPolicyError> {
if self.key().parent().base_checkpoint().graph() != &parent.reference() {
return Err(ChildRunPolicyError::ParentGraphMismatch);
}
let policy = parent
.child_runs()
.ok_or(ChildRunPolicyError::DelegationNotDeclared)?;
let declaration = policy
.declaration(self.key().parent().node_id(), self.key().slot())
.ok_or(ChildRunPolicyError::DelegationNotDeclared)?;
declaration.validate_target(self.child_graph(), policy.limits())?;
if declaration.agent() != &ChildAgentReference::from_descriptor(self.child().descriptor())?
{
return Err(ChildRunPolicyError::TargetAgentMismatch);
}
Ok(())
}
}
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ChildRunPolicyError {
#[error("child Agent definition encoding failed")]
AgentEncoding,
#[error("invalid child topology limits")]
InvalidLimits,
#[error("child policy must declare at least one slot")]
EmptyDeclarations,
#[error("too many graph child declarations")]
TooManyDeclarations,
#[error("too many child slots on one node")]
TooManyNodeSlots,
#[error("duplicate child slot on one node")]
DuplicateSlot,
#[error("unsupported child policy version")]
UnsupportedVersion,
#[error("child declaration references an unknown parent node")]
UndeclaredParentNode,
#[error("child declaration parent graph mismatch")]
ParentGraphMismatch,
#[error("child delegation is not declared by the parent node")]
DelegationNotDeclared,
#[error("declared child graph mismatch")]
TargetGraphMismatch,
#[error("declared child input or output schema mismatch")]
TargetSchemaMismatch,
#[error("declared child Agent definition mismatch")]
TargetAgentMismatch,
#[error("declared child depth does not narrow the parent depth")]
DepthNotNarrowed,
}
#[cfg(test)]
#[path = "child_run_policy_tests.rs"]
mod tests;