1use std::fmt;
7
8use schemars::JsonSchema;
9use serde::{Deserialize, Deserializer, Serialize, de};
10use thiserror::Error;
11
12use crate::{
13 AgentAdmission, AgentAdmissionIntent, AgentAdmissionIntentError, BudgetNarrowingError,
14 Checkpoint, CheckpointState, ChildRunKey, CompiledGraph, Digest, GraphSchemaValidationError,
15 GraphSchemaValidator, NodeActivation, Timestamp,
16};
17
18const SPAWN_DOMAIN: &[u8] = b"stateknot.child-run-admission-intent.v1\0";
19
20#[derive(Clone, Eq, JsonSchema, PartialEq, Serialize)]
35#[serde(deny_unknown_fields)]
36pub struct ChildRunAdmissionIntent {
37 key: ChildRunKey,
38 parent_admission_digest: Digest,
39 child: AgentAdmissionIntent,
40 child_graph: CompiledGraph,
41 initial_state: CheckpointState,
42 spawn_digest: Digest,
43}
44
45impl ChildRunAdmissionIntent {
46 pub const MAX_SNAPSHOT_BYTES: usize = 16 * 1024 * 1024;
48
49 pub fn new(
55 parent: &AgentAdmission,
56 key: ChildRunKey,
57 child: AgentAdmissionIntent,
58 child_graph: CompiledGraph,
59 initial_state: CheckpointState,
60 ) -> Result<Self, ChildRunAdmissionIntentError> {
61 let intent = Self::build(key, parent.digest(), child, child_graph, initial_state)?;
62 intent.validate_parent(parent)?;
63 Ok(intent)
64 }
65
66 fn build(
67 key: ChildRunKey,
68 parent_admission_digest: Digest,
69 child: AgentAdmissionIntent,
70 child_graph: CompiledGraph,
71 initial_state: CheckpointState,
72 ) -> Result<Self, ChildRunAdmissionIntentError> {
73 if key.tenant_id() != child.provenance().tenant_id()
74 || key.parent_run_id() == child.provenance().run_id()
75 {
76 return Err(ChildRunAdmissionIntentError::ChildScopeMismatch);
77 }
78 if !key.parent().graph_namespace().is_root() {
79 return Err(ChildRunAdmissionIntentError::UnsupportedParentNamespace);
80 }
81 if child.graph() != &child_graph.reference()
82 || child.descriptor().input_schema() != child_graph.input_schema()
83 || child.descriptor().output_schema() != child_graph.output_schema()
84 || initial_state.schema() != child_graph.state_schema()
85 {
86 return Err(ChildRunAdmissionIntentError::ChildGraphMismatch);
87 }
88 let mut intent = Self {
89 key,
90 parent_admission_digest,
91 child,
92 child_graph,
93 initial_state,
94 spawn_digest: Digest::sha256([]),
95 };
96 intent.spawn_digest = intent.compute_spawn_digest()?;
97 intent.canonical_bytes()?;
98 Ok(intent)
99 }
100
101 fn validate_parent(&self, parent: &AgentAdmission) -> Result<(), ChildRunAdmissionIntentError> {
102 let admitted = parent.intent();
103 if self.parent_admission_digest != parent.digest()
104 || self.key.tenant_id() != admitted.provenance().tenant_id()
105 || self.key.parent_run_id() != admitted.provenance().run_id()
106 || self.key.parent().base_checkpoint().graph() != admitted.graph()
107 || self
108 .key
109 .parent()
110 .base_checkpoint()
111 .journal_head()
112 .recorded_at()
113 < parent.admitted_at()
114 {
115 return Err(ChildRunAdmissionIntentError::ParentMismatch);
116 }
117 if self.child.authority().principal() != admitted.authority().principal() {
120 return Err(ChildRunAdmissionIntentError::PrincipalMismatch);
121 }
122 if !self
123 .child
124 .authority()
125 .granted_scopes()
126 .is_subset(admitted.authority().granted_scopes())
127 {
128 return Err(ChildRunAdmissionIntentError::ScopeWidening);
129 }
130 self.child.budget().validate_narrowing(admitted.budget())?;
131 Ok(())
132 }
133
134 pub fn validate_for<V: GraphSchemaValidator + ?Sized>(
145 &self,
146 parent: &AgentAdmission,
147 checkpoint: &Checkpoint,
148 schemas: &V,
149 observed_at: Timestamp,
150 ) -> Result<(), ChildRunAdmissionIntentError> {
151 self.validate_parent(parent)?;
152 if self.key.parent().base_checkpoint() != &checkpoint.head() {
153 return Err(ChildRunAdmissionIntentError::ParentCheckpointMismatch);
154 }
155 let activation =
156 NodeActivation::for_ready_root(checkpoint, self.key.parent().node_id().clone())
157 .map_err(|_| ChildRunAdmissionIntentError::ParentNotReady)?;
158 if &activation != self.key.parent() {
159 return Err(ChildRunAdmissionIntentError::ParentActivationMismatch);
160 }
161 if observed_at < checkpoint.journal_head().recorded_at() {
162 return Err(ChildRunAdmissionIntentError::ClockBeforeCheckpoint);
163 }
164 if observed_at >= self.child.budget().deadline()
165 || observed_at >= parent.intent().budget().deadline()
166 {
167 return Err(ChildRunAdmissionIntentError::DeadlineExpired);
168 }
169 for (schema, data) in [
170 (
171 self.child.request().input_schema(),
172 self.child.request().input(),
173 ),
174 (self.initial_state.schema(), self.initial_state.data()),
175 (
176 self.child.authority().evidence().schema(),
177 self.child.authority().evidence().data(),
178 ),
179 ] {
180 schemas.validate(schema, data)?;
181 }
182 Ok(())
183 }
184
185 fn compute_spawn_digest(&self) -> Result<Digest, ChildRunAdmissionIntentError> {
186 let wire = serde_json::json!({
189 "key": self.key.digest(),
190 "parent_admission_digest": self.parent_admission_digest,
191 "tenant_id": self.child.provenance().tenant_id(),
192 "descriptor": self.child.descriptor(),
193 "request": self.child.request(),
194 "budget_layers": self.child.budget_layers(),
195 "budget": self.child.budget(),
196 "graph": self.child.graph(),
197 "authority": self.child.authority(),
198 "initial_state": self.initial_state,
199 "initial_ready_nodes": self.child_graph.entry_nodes(),
200 "parent_close_policy": "cancel_and_join"
201 });
202 let canonical = canonical(&wire)?;
203 let mut bytes = Vec::with_capacity(SPAWN_DOMAIN.len() + canonical.len());
204 bytes.extend_from_slice(SPAWN_DOMAIN);
205 bytes.extend_from_slice(&canonical);
206 Ok(Digest::sha256(bytes))
207 }
208
209 pub fn canonical_bytes(&self) -> Result<Vec<u8>, ChildRunAdmissionIntentError> {
211 let bytes = canonical(self)?;
212 if bytes.len() > Self::MAX_SNAPSHOT_BYTES {
213 return Err(ChildRunAdmissionIntentError::SnapshotTooLarge);
214 }
215 Ok(bytes)
216 }
217
218 #[must_use]
220 pub const fn key(&self) -> &ChildRunKey {
221 &self.key
222 }
223 #[must_use]
225 pub const fn parent_admission_digest(&self) -> Digest {
226 self.parent_admission_digest
227 }
228 #[must_use]
230 pub const fn child(&self) -> &AgentAdmissionIntent {
231 &self.child
232 }
233 #[must_use]
235 pub const fn child_graph(&self) -> &CompiledGraph {
236 &self.child_graph
237 }
238 #[must_use]
240 pub const fn initial_state(&self) -> &CheckpointState {
241 &self.initial_state
242 }
243 #[must_use]
245 pub const fn spawn_digest(&self) -> Digest {
246 self.spawn_digest
247 }
248}
249
250fn canonical<T: Serialize>(value: &T) -> Result<Vec<u8>, ChildRunAdmissionIntentError> {
251 crate::agent_admission::canonical_bytes(value).map_err(|error| match error {
252 AgentAdmissionIntentError::NonInteroperableNumber => {
253 ChildRunAdmissionIntentError::NonInteroperableNumber
254 }
255 _ => ChildRunAdmissionIntentError::IntegritySerialization,
256 })
257}
258
259impl fmt::Debug for ChildRunAdmissionIntent {
260 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
261 formatter
262 .debug_struct("ChildRunAdmissionIntent")
263 .field("key_digest", &self.key.digest())
264 .field("parent_admission_digest", &self.parent_admission_digest)
265 .field("spawn_digest", &self.spawn_digest)
266 .finish_non_exhaustive()
267 }
268}
269
270impl<'de> Deserialize<'de> for ChildRunAdmissionIntent {
271 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
272 #[derive(Deserialize)]
273 #[serde(deny_unknown_fields)]
274 struct Wire {
275 key: ChildRunKey,
276 parent_admission_digest: Digest,
277 child: AgentAdmissionIntent,
278 child_graph: CompiledGraph,
279 initial_state: CheckpointState,
280 spawn_digest: Digest,
281 }
282 let wire = Wire::deserialize(deserializer)?;
283 let intent = Self::build(
284 wire.key,
285 wire.parent_admission_digest,
286 wire.child,
287 wire.child_graph,
288 wire.initial_state,
289 )
290 .map_err(de::Error::custom)?;
291 if intent.spawn_digest != wire.spawn_digest {
292 return Err(de::Error::custom(
293 ChildRunAdmissionIntentError::DigestMismatch,
294 ));
295 }
296 Ok(intent)
297 }
298}
299
300#[derive(Clone, Debug, Eq, Error, PartialEq)]
302#[non_exhaustive]
303pub enum ChildRunAdmissionIntentError {
304 #[error("child admission crosses scope or reuses its parent run")]
306 ChildScopeMismatch,
307 #[error("child admission requires a root-namespace parent activation")]
309 UnsupportedParentNamespace,
310 #[error("child admission graph or schema mismatch")]
312 ChildGraphMismatch,
313 #[error("child admission parent mismatch")]
315 ParentMismatch,
316 #[error("child admission principal differs from parent")]
318 PrincipalMismatch,
319 #[error("child admission widens granted scopes")]
321 ScopeWidening,
322 #[error(transparent)]
324 Budget(#[from] BudgetNarrowingError),
325 #[error("child admission parent checkpoint mismatch")]
327 ParentCheckpointMismatch,
328 #[error("child admission parent node is not ready")]
330 ParentNotReady,
331 #[error("child admission parent activation mismatch")]
333 ParentActivationMismatch,
334 #[error("child admission clock predates parent checkpoint")]
336 ClockBeforeCheckpoint,
337 #[error("child admission deadline expired")]
339 DeadlineExpired,
340 #[error(transparent)]
342 Schema(#[from] GraphSchemaValidationError),
343 #[error("child admission snapshot exceeds its byte limit")]
345 SnapshotTooLarge,
346 #[error("child admission canonical serialization failed")]
348 IntegritySerialization,
349 #[error("child admission contains a non-interoperable JSON integer")]
351 NonInteroperableNumber,
352 #[error("child admission spawn digest mismatch")]
354 DigestMismatch,
355}
356
357#[cfg(test)]
358#[path = "child_run_admission_tests.rs"]
359mod tests;