1#[allow(clippy::wildcard_imports)]
8use super::*;
9use stateknot_core::{
10 ChildRunAdmissionIntent, ChildRunBudgetAccount, ChildRunBudgetSettlement, ChildRunKey,
11};
12
13const OWNER_COLUMNS: &str = "tenant_id, parent_run_id, key_digest, key_bytes, child_slot, activation_digest, parent_node_attempt_id, spawn_digest, child_run_id, root_run_id, ancestors, intent_bytes, child_admission_digest, parent_checkpoint_id, parent_checkpoint_superstep, parent_checkpoint_digest, journal_sequence, journal_event_id, journal_recorded_at, journal_digest, settled, terminal_pending_at";
14
15#[derive(Clone, Debug)]
17pub struct ChildRunRecord {
18 intent: ChildRunAdmissionIntent,
19 child: StoredAgentAdmission,
20 spawn: JournalEvent,
21 ancestors: Vec<RunId>,
22 settlement: Option<ChildRunBudgetSettlement>,
23}
24
25impl ChildRunRecord {
26 #[must_use]
28 pub const fn intent(&self) -> &ChildRunAdmissionIntent {
29 &self.intent
30 }
31 #[must_use]
33 pub const fn child(&self) -> &StoredAgentAdmission {
34 &self.child
35 }
36 #[must_use]
38 pub const fn spawn(&self) -> &JournalEvent {
39 &self.spawn
40 }
41 #[must_use]
43 pub fn ancestors(&self) -> &[RunId] {
44 &self.ancestors
45 }
46 #[must_use]
48 pub const fn settlement(&self) -> Option<&ChildRunBudgetSettlement> {
49 self.settlement.as_ref()
50 }
51}
52
53#[derive(Clone, Debug)]
55#[non_exhaustive]
56pub enum ChildRunCommitOutcome {
57 Committed(ChildRunRecord),
59 Idempotent(ChildRunRecord),
61}
62impl ChildRunCommitOutcome {
63 #[must_use]
65 pub const fn record(&self) -> &ChildRunRecord {
66 match self {
67 Self::Committed(record) | Self::Idempotent(record) => record,
68 }
69 }
70}
71
72#[derive(Clone, Debug)]
74#[non_exhaustive]
75pub enum ChildRunSettlementOutcome {
76 Committed {
78 event: JournalEvent,
80 record: ChildRunRecord,
82 },
83 Idempotent {
85 event: JournalEvent,
87 record: ChildRunRecord,
89 },
90}
91
92impl PostgresStore {
93 #[allow(clippy::too_many_arguments, clippy::too_many_lines)]
107 pub async fn admit_child_run<V: GraphSchemaValidator + ?Sized>(
108 &self,
109 intent: ChildRunAdmissionIntent,
110 node: &NodeAttemptStartHead,
111 parent_append: JournalAppend,
112 child_append: JournalAppend,
113 child_checkpoint: CheckpointWrite,
114 direct_usage: BudgetUsage,
115 schemas: &V,
116 ) -> Result<ChildRunCommitOutcome, StoreError> {
117 let key = intent.key();
118 validate_agent_admission_commit_input(intent.child(), &child_append, &child_checkpoint)?;
119 if parent_append.intent().tenant_id() != key.tenant_id()
120 || parent_append.intent().run_id() != key.parent_run_id()
121 || parent_append.intent().payload().kind().as_str() != "child-run-admitted"
122 || child_checkpoint.state() != intent.initial_state()
123 || child_checkpoint.ready_nodes() != intent.child_graph().entry_nodes()
124 {
125 return Err(StoreError::ChildRunRejected);
126 }
127 if let Some(record) = self.load_child_run_optional(key).await? {
128 if record.intent.spawn_digest() != intent.spawn_digest() {
129 return Err(StoreError::ChildRunConflict);
130 }
131 return Ok(ChildRunCommitOutcome::Idempotent(record));
132 }
133 let parent = self
134 .load_agent_admission(key.tenant_id(), key.parent_run_id())
135 .await?;
136 let checkpoint = self
137 .load_current_checkpoint(key.tenant_id(), key.parent_run_id())
138 .await?
139 .ok_or(StoreError::StaleCheckpointHead)?;
140 let parent_graph = self
141 .load_graph_definition(key.tenant_id(), parent.admission().intent().graph())
142 .await?;
143 let child_graph = self
144 .load_graph_definition(key.tenant_id(), intent.child().graph())
145 .await?;
146 if child_graph.graph() != intent.child_graph() {
147 return Err(StoreError::ChildRunRejected);
148 }
149 intent
150 .validate_declaration(parent_graph.graph())
151 .map_err(|_| StoreError::ChildRunRejected)?;
152 let schema_clock = self.observe_database_clock().await?;
153 catch_unwind(AssertUnwindSafe(|| {
154 intent.validate_for(parent.admission(), &checkpoint, schemas, schema_clock)
155 }))
156 .map_err(|_| StoreError::AgentAdmissionSchemaUnavailable)?
157 .map_err(|_| StoreError::ChildRunRejected)?;
158 validate_agent_initial_checkpoint(child_graph.graph(), &child_checkpoint, schemas)?;
159
160 let mut tx = self.begin_mutation("atomic child admission").await?;
161 let ancestors = ancestry(&mut tx, key.tenant_id(), key.parent_run_id()).await?;
162 lock_tree(&mut tx, key.tenant_id(), ancestors[0]).await?;
163 if ancestry(&mut tx, key.tenant_id(), key.parent_run_id()).await? != ancestors {
164 return Err(StoreError::corrupt("child ancestry changed"));
165 }
166 for ancestor in &ancestors {
168 fetch_locked_run_row(&mut tx, key.tenant_id(), *ancestor).await?;
169 }
170 if let Some(record) = load_record(&mut tx, key).await? {
171 load_account(&mut tx, key.tenant_id(), key.parent_run_id()).await?;
172 if record.intent.spawn_digest() != intent.spawn_digest() {
173 return Err(StoreError::ChildRunConflict);
174 }
175 tx.commit()
176 .await
177 .map_err(|source| StoreError::database("child admission retry", source))?;
178 return Ok(ChildRunCommitOutcome::Idempotent(record));
179 }
180 let stored =
181 decode_run(fetch_locked_run_row(&mut tx, key.tenant_id(), key.parent_run_id()).await?)?;
182 let parent_row = load_agent_admission_row(&mut tx, key.tenant_id(), key.parent_run_id())
183 .await?
184 .ok_or(StoreError::AgentAdmissionNotFound)?;
185 let parent = verify_stored_agent_admission(&mut tx, stored, parent_row).await?;
186 if parent.admission().digest() != intent.parent_admission_digest() {
187 return Err(StoreError::ChildRunConflict);
188 }
189 let current = load_locked_current_checkpoint(
190 &mut tx,
191 parent.run(),
192 key.tenant_id(),
193 key.parent_run_id(),
194 )
195 .await?
196 .ok_or(StoreError::StaleCheckpointHead)?;
197 if current.head() != *key.parent().base_checkpoint()
198 || !node_attempt_activation_is_ready(¤t, key.parent())
199 {
200 return Err(StoreError::StaleCheckpointHead);
201 }
202 let observed_at =
203 authorize_parent_append(&mut tx, parent.run(), &parent_append, true).await?;
204 let fence = parent_append
205 .worker_fence()
206 .ok_or(StoreError::WrongAppendAuthority)?;
207 if node.activation() != key.parent() || node.fence() != fence {
208 return Err(StoreError::ChildRunRejected);
209 }
210 let attempt = load_node_attempt_record(
211 &mut tx,
212 key.tenant_id(),
213 &key.parent_run_id(),
214 node.attempt_id(),
215 )
216 .await?
217 .ok_or(StoreError::ChildRunRejected)?;
218 verify_node_attempt(&mut tx, &attempt).await?;
219 if attempt.start().head() != *node || attempt.completion().is_some() {
220 return Err(StoreError::ChildRunRejected);
221 }
222 ensure_no_unsettled_tool_invocations(&mut tx, ¤t).await?;
223 ensure_no_unsettled_model_invocations(&mut tx, ¤t).await?;
224 check_topology(&mut tx, key.tenant_id(), &ancestors).await?;
225 let mut account = match load_account(&mut tx, key.tenant_id(), key.parent_run_id()).await? {
226 Some(account) => account
227 .observe_direct(
228 parent_append
229 .expectation()
230 .head()
231 .ok_or(StoreError::StaleJournalHead)?
232 .clone(),
233 direct_usage,
234 )
235 .map_err(|_| StoreError::ChildRunRejected)?,
236 None => ChildRunBudgetAccount::new(
237 parent.admission(),
238 parent_graph.graph(),
239 parent_append
240 .expectation()
241 .head()
242 .ok_or(StoreError::StaleJournalHead)?
243 .clone(),
244 direct_usage,
245 )
246 .map_err(|_| StoreError::ChildRunRejected)?,
247 };
248 account = account
249 .reserve(&intent, parent_graph.graph(), observed_at)
250 .map_err(|_| StoreError::ChildRunRejected)?;
251 let child_id = intent.child().provenance().run_id();
252 let exists = query_scalar::<_, bool>(
254 "SELECT EXISTS (SELECT 1 FROM stateknot.runs WHERE tenant_id=$1 AND run_id=$2)",
255 )
256 .bind(key.tenant_id().as_str())
257 .bind(*child_id.as_uuid())
258 .fetch_one(&mut *tx)
259 .await
260 .map_err(|source| StoreError::database("child fresh identity check", source))?;
261 if exists {
262 return Err(StoreError::ChildRunConflict);
263 }
264 if load_locked_agent_admission(&mut tx, key.tenant_id(), child_id)
265 .await?
266 .is_some()
267 {
268 return Err(StoreError::ChildRunConflict);
269 }
270 let child = match Box::pin(commit_new_agent_admission(
271 &mut tx,
272 intent.child().clone(),
273 child_append,
274 child_checkpoint,
275 ))
276 .await?
277 {
278 NewAgentAdmissionOutcome::Committed(child) => child,
279 NewAgentAdmissionOutcome::Idempotent(_) => return Err(StoreError::ChildRunConflict),
280 };
281 let at = database_now(&mut tx, "child spawn clock")
282 .await?
283 .max(observed_at)
284 .max(child.admission().admitted_at());
285 account
286 .remaining(at)
287 .map_err(|_| StoreError::ChildRunRejected)?;
288 let event = JournalEvent::commit(parent_append, at)
289 .map_err(|error| map_event_commit_error(&error))?;
290 insert_event(
291 &mut tx,
292 &event,
293 spawn_projection(&intent, child.admission(), child.checkpoint(), &event)?,
294 )
295 .await?;
296 insert_owner(
297 &mut tx,
298 &intent,
299 attempt.start(),
300 &ancestors,
301 &child,
302 &event,
303 )
304 .await?;
305 save_account(&mut tx, &account, &event.head()).await?;
306 mark_child_capability(&mut tx, key.tenant_id(), key.parent_run_id()).await?;
307 mark_child_capability(&mut tx, key.tenant_id(), child_id).await?;
308 update_run_head(&mut tx, &event, None).await?; let record = load_record(&mut tx, key)
310 .await?
311 .ok_or_else(|| StoreError::corrupt("new child ownership"))?;
312 tx.commit()
313 .await
314 .map_err(|source| StoreError::database("atomic child admission commit", source))?;
315 Ok(ChildRunCommitOutcome::Committed(record))
316 }
317
318 pub async fn load_child_run(&self, key: &ChildRunKey) -> Result<ChildRunRecord, StoreError> {
321 self.load_child_run_optional(key)
322 .await?
323 .ok_or(StoreError::ChildRunNotFound)
324 }
325
326 async fn load_child_run_optional(
327 &self,
328 key: &ChildRunKey,
329 ) -> Result<Option<ChildRunRecord>, StoreError> {
330 let mut tx = self.begin_repeatable_read("child ownership read").await?;
331 let result = Box::pin(load_record_inner(&mut tx, key, false)).await?;
332 if result.is_some() {
333 Box::pin(load_account_inner(
334 &mut tx,
335 key.tenant_id(),
336 key.parent_run_id(),
337 false,
338 ))
339 .await?;
340 }
341 tx.commit()
342 .await
343 .map_err(|source| StoreError::database("child ownership read commit", source))?;
344 Ok(result)
345 }
346
347 pub async fn load_child_budget_account(
350 &self,
351 tenant: &TenantId,
352 parent: RunId,
353 ) -> Result<Option<ChildRunBudgetAccount>, StoreError> {
354 let mut tx = self.begin_repeatable_read("child budget read").await?;
355 let account = Box::pin(load_account_inner(&mut tx, tenant, parent, false)).await?;
356 tx.commit()
357 .await
358 .map_err(|source| StoreError::database("child budget read commit", source))?;
359 Ok(account)
360 }
361
362 pub async fn include_child_usage(
366 &self,
367 tenant: &TenantId,
368 parent: RunId,
369 direct: BudgetUsage,
370 ) -> Result<BudgetUsage, StoreError> {
371 let Some(account) = self.load_child_budget_account(tenant, parent).await? else {
372 return Ok(direct);
373 };
374 ensure_settled(&account)?;
375 direct
376 .validate_monotonic_after(account.direct_usage())
377 .map_err(|_| StoreError::IncompleteChildAccounting)?;
378 direct
379 .checked_accumulate(
380 &account
381 .delegated_usage()
382 .map_err(|_| StoreError::IncompleteChildAccounting)?,
383 )
384 .map_err(|_| StoreError::IncompleteChildAccounting)
385 }
386
387 pub async fn list_child_run_identities(
390 &self,
391 tenant: &TenantId,
392 parent: RunId,
393 ) -> Result<Vec<(Digest, RunId)>, StoreError> {
394 let rows = query_as::<_, (Vec<u8>, Uuid)>("SELECT key_digest, child_run_id FROM stateknot.child_run_ownership WHERE tenant_id = $1 AND parent_run_id = $2 ORDER BY key_digest LIMIT 257")
395 .bind(tenant.as_str()).bind(*parent.as_uuid()).fetch_all(&self.pool).await
396 .map_err(|source| StoreError::database("child identity list", source))?;
397 if rows.len() > 256 {
398 return Err(StoreError::corrupt("child lifetime count"));
399 }
400 rows.into_iter()
401 .map(|(digest, run)| {
402 Ok((
403 decode_digest(&digest, "child key")?,
404 RunId::from_uuid(run).map_err(|_| StoreError::corrupt("child identity"))?,
405 ))
406 })
407 .collect()
408 }
409
410 pub async fn pending_child_settlements(
414 &self,
415 tenant: &TenantId,
416 ) -> Result<Vec<ChildRunKey>, StoreError> {
417 self.pending_child_settlements_after(tenant, None).await
418 }
419
420 pub async fn pending_child_settlements_after(
426 &self,
427 tenant: &TenantId,
428 after: Option<&ChildRunKey>,
429 ) -> Result<Vec<ChildRunKey>, StoreError> {
430 let cursor = if let Some(key) = after {
431 if key.tenant_id() != tenant {
432 return Err(StoreError::ChildRunRejected);
433 }
434 Some(query_as::<_, (DateTime<Utc>, Uuid)>("SELECT terminal.journal_recorded_at, terminal.child_run_id FROM stateknot.child_run_ownership AS owner JOIN stateknot.child_run_terminals AS terminal ON terminal.tenant_id=owner.tenant_id AND terminal.child_run_id=owner.child_run_id WHERE owner.tenant_id=$1 AND owner.parent_run_id=$2 AND owner.key_digest=$3")
435 .bind(tenant.as_str()).bind(*key.parent_run_id().as_uuid()).bind(key.digest().as_bytes())
436 .fetch_optional(&self.pool).await.map_err(|source| StoreError::database("child notification cursor", source))?
437 .ok_or(StoreError::ChildRunNotFound)?)
438 } else {
439 None
440 };
441 let sql = if cursor.is_some() {
445 "SELECT key_bytes, key_digest, parent_run_id FROM stateknot.child_run_ownership WHERE tenant_id = $1 AND terminal_pending_at IS NOT NULL AND NOT settled AND (terminal_pending_at, child_run_id) > ($2,$3) ORDER BY terminal_pending_at, child_run_id LIMIT 16"
446 } else {
447 "SELECT key_bytes, key_digest, parent_run_id FROM stateknot.child_run_ownership WHERE tenant_id = $1 AND terminal_pending_at IS NOT NULL AND NOT settled ORDER BY terminal_pending_at, child_run_id LIMIT 16"
448 };
449 let mut listing = query_as::<_, (Vec<u8>, Vec<u8>, Uuid)>(sql).bind(tenant.as_str());
450 if let Some((at, child)) = cursor {
451 listing = listing.bind(at).bind(child);
452 }
453 let rows = listing
454 .fetch_all(&self.pool)
455 .await
456 .map_err(|source| StoreError::database("child settlement discovery", source))?;
457 rows.into_iter()
458 .map(|(bytes, digest, parent)| {
459 let key: ChildRunKey = serde_json::from_slice(&bytes)
460 .map_err(|_| StoreError::corrupt("pending child key"))?;
461 if key.tenant_id() != tenant
462 || bytes.len() > 65_536
463 || key.digest() != decode_digest(&digest, "pending child key digest")?
464 || *key.parent_run_id().as_uuid() != parent
465 {
466 return Err(StoreError::corrupt("pending child key scope"));
467 }
468 Ok(key)
469 })
470 .collect()
471 }
472
473 #[allow(clippy::too_many_lines)]
480 pub async fn settle_child_run(
481 &self,
482 key: &ChildRunKey,
483 append: JournalAppend,
484 ) -> Result<ChildRunSettlementOutcome, StoreError> {
485 if append.intent().tenant_id() != key.tenant_id()
486 || append.intent().run_id() != key.parent_run_id()
487 || append.intent().payload().kind().as_str() != "child-run-settled"
488 {
489 return Err(StoreError::ChildRunRejected);
490 }
491 let mut tx = self.begin_mutation("child settlement").await?;
492 let ancestors = ancestry(&mut tx, key.tenant_id(), key.parent_run_id()).await?;
493 lock_tree(&mut tx, key.tenant_id(), ancestors[0]).await?;
494 let parent =
495 decode_run(fetch_locked_run_row(&mut tx, key.tenant_id(), key.parent_run_id()).await?)?;
496 let record = load_record(&mut tx, key)
497 .await?
498 .ok_or(StoreError::ChildRunNotFound)?;
499 if record.settlement.is_some() {
500 load_account(&mut tx, key.tenant_id(), key.parent_run_id()).await?;
501 let event = load_settlement_event(&mut tx, key).await?;
502 tx.commit()
503 .await
504 .map_err(|source| StoreError::database("child settlement retry", source))?;
505 return Ok(ChildRunSettlementOutcome::Idempotent { event, record });
506 }
507 let at = authorize_parent_append(&mut tx, &parent, &append, false).await?;
508 if record.child.run().is_quarantined() {
509 return Err(StoreError::RunQuarantined);
510 }
511 let child_id = record.child.admission().intent().provenance().run_id();
512 let evidence = terminal_evidence(&mut tx, &record.child).await?;
515 let account = load_account(&mut tx, key.tenant_id(), key.parent_run_id())
516 .await?
517 .ok_or_else(|| StoreError::corrupt("owned child account"))?;
518 let account = account
519 .settle(key, evidence.clone())
520 .map_err(|_| StoreError::ChildRunSettlementUnavailable)?;
521 let at = at.max(evidence.terminal().recorded_at());
522 let event =
523 JournalEvent::commit(append, at).map_err(|error| map_event_commit_error(&error))?;
524 let bytes = serde_json_canonicalizer::to_vec(&evidence)
525 .map_err(|_| StoreError::encoding("child settlement"))?;
526 let digest = Digest::sha256(&bytes);
527 insert_event(
528 &mut tx,
529 &event,
530 settlement_projection(key.digest(), digest, &event)?,
531 )
532 .await?;
533 query("INSERT INTO stateknot.child_run_settlements (tenant_id, parent_run_id, key_digest, child_run_id, settlement_bytes, settlement_digest, journal_sequence, journal_event_id, journal_recorded_at, journal_digest) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)")
534 .bind(key.tenant_id().as_str()).bind(*key.parent_run_id().as_uuid()).bind(key.digest().as_bytes())
535 .bind(*child_id.as_uuid()).bind(bytes).bind(digest.as_bytes())
536 .bind(i64::try_from(event.sequence().get()).map_err(|_| StoreError::JournalSequenceExhausted)?)
537 .bind(*event.event_id().as_uuid()).bind(to_database_time(event.recorded_at())?).bind(event.digest().as_bytes())
538 .execute(&mut *tx).await.map_err(|source| StoreError::database("child settlement insert", source))?;
539 query("UPDATE stateknot.child_run_ownership SET settled = true, terminal_pending_at = NULL WHERE tenant_id = $1 AND parent_run_id = $2 AND key_digest = $3 AND NOT settled")
540 .bind(key.tenant_id().as_str()).bind(*key.parent_run_id().as_uuid()).bind(key.digest().as_bytes())
541 .execute(&mut *tx).await.map_err(|source| StoreError::database("child settlement projection", source))?;
542 save_account(&mut tx, &account, &event.head()).await?;
543 update_run_head(&mut tx, &event, None).await?;
544 let record = load_record(&mut tx, key)
545 .await?
546 .ok_or_else(|| StoreError::corrupt("settled child ownership"))?;
547 tx.commit()
548 .await
549 .map_err(|source| StoreError::database("child settlement commit", source))?;
550 Ok(ChildRunSettlementOutcome::Committed { event, record })
551 }
552}
553
554fn decode_intent(bytes: &[u8]) -> Result<ChildRunAdmissionIntent, StoreError> {
555 if bytes.is_empty() || bytes.len() > ChildRunAdmissionIntent::MAX_SNAPSHOT_BYTES {
556 return Err(StoreError::corrupt("child intent size"));
557 }
558 let intent: ChildRunAdmissionIntent =
559 serde_json::from_slice(bytes).map_err(|_| StoreError::corrupt("child intent"))?;
560 if intent
561 .canonical_bytes()
562 .map_err(|_| StoreError::corrupt("child canonical intent"))?
563 != bytes
564 {
565 return Err(StoreError::corrupt("child canonical intent"));
566 }
567 Ok(intent)
568}
569
570pub(super) fn ensure_settled(account: &ChildRunBudgetAccount) -> Result<(), StoreError> {
571 if account
572 .children()
573 .iter()
574 .any(|entry| entry.settlement().is_none())
575 {
576 return Err(StoreError::UnsettledChildRuns);
577 }
578 Ok(())
579}
580
581pub(super) async fn authorize_invocation_budget(
583 tx: &mut Transaction<'_, Postgres>,
584 tenant: &TenantId,
585 run: RunId,
586 observed: Option<Digest>,
587) -> Result<(), StoreError> {
588 let account = load_account(tx, tenant, run).await?;
589 if let Some(account) = &account {
590 ensure_settled(account)?;
591 }
592 if account.as_ref().map(ChildRunBudgetAccount::digest) != observed {
593 return Err(StoreError::ChildBudgetObservationRequired);
594 }
595 if let Some(digest) = observed {
596 query("SELECT set_config('stateknot.child_budget_digest', encode($1::bytea, 'hex'), true)")
597 .bind(digest.as_bytes())
598 .execute(&mut **tx)
599 .await
600 .map_err(|source| StoreError::database("child invocation budget fence", source))?;
601 }
602 Ok(())
603}
604
605pub(super) async fn validate_terminal_accounting(
607 tx: &mut Transaction<'_, Postgres>,
608 event: &JournalEvent,
609 projection: &PreparedProjection,
610) -> Result<(), StoreError> {
611 if !matches!(projection.status, "succeeded" | "failed" | "cancelled") {
612 return Ok(());
613 }
614 let lifecycle: RunLifecycle = serde_json::from_slice(&projection.lifecycle_bytes)
615 .map_err(|_| StoreError::corrupt("child terminal accounting lifecycle"))?;
616 let total = lifecycle
617 .terminal_usage()
618 .ok_or(StoreError::IncompleteChildAccounting)?;
619 let Some(account) = load_account(tx, event.tenant_id(), event.run_id()).await? else {
620 return failure_closes::validate_direct_usage(tx, event, total).await;
621 };
622 ensure_settled(&account)?;
623 let direct = total
624 .checked_subtract_cumulative(
625 &account
626 .delegated_usage()
627 .map_err(|_| StoreError::IncompleteChildAccounting)?,
628 )
629 .map_err(|_| StoreError::IncompleteChildAccounting)?;
630 failure_closes::validate_direct_usage(tx, event, &direct).await?;
631 let account = account
632 .observe_direct(event.head(), direct)
633 .map_err(|_| StoreError::IncompleteChildAccounting)?;
634 save_account(tx, &account, &event.head()).await?;
635 query("SELECT set_config('stateknot.child_terminal_digest', encode($1::bytea, 'hex'), true)")
636 .bind(Digest::sha256(&projection.lifecycle_bytes).as_bytes())
637 .execute(&mut **tx)
638 .await
639 .map_err(|source| StoreError::database("child terminal accounting fence", source))?;
640 Ok(())
641}
642
643pub(super) async fn lock_tree(
644 tx: &mut Transaction<'_, Postgres>,
645 tenant: &TenantId,
646 root: RunId,
647) -> Result<(), StoreError> {
648 query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))")
649 .bind(format!("stateknot:child-tree:{}:{root}", tenant.as_str()))
650 .execute(&mut **tx)
651 .await
652 .map_err(|source| StoreError::database("child tree lock", source))?;
653 Ok(())
654}
655
656pub(super) async fn ancestry(
657 tx: &mut Transaction<'_, Postgres>,
658 tenant: &TenantId,
659 parent: RunId,
660) -> Result<Vec<RunId>, StoreError> {
661 let row = query_as::<_, (Vec<Uuid>, Uuid)>("SELECT ancestors, root_run_id FROM stateknot.child_run_ownership WHERE tenant_id = $1 AND child_run_id = $2")
662 .bind(tenant.as_str()).bind(*parent.as_uuid()).fetch_optional(&mut **tx).await
663 .map_err(|source| StoreError::database("child ancestry", source))?;
664 let mut values = Vec::new();
665 if let Some((path, root)) = row {
666 if path.is_empty() || path.len() >= 32 || path[0] != root || path.contains(parent.as_uuid())
667 {
668 return Err(StoreError::ChildRunTopologyExceeded);
669 }
670 for id in path {
671 values
672 .push(RunId::from_uuid(id).map_err(|_| StoreError::corrupt("child ancestor id"))?);
673 }
674 }
675 values.push(parent);
676 if values
677 .iter()
678 .collect::<std::collections::BTreeSet<_>>()
679 .len()
680 != values.len()
681 {
682 return Err(StoreError::corrupt("child ancestry cycle"));
683 }
684 for (position, ancestor) in values.iter().enumerate().take(values.len() - 1) {
687 let stored = query_scalar::<_, Vec<Uuid>>("SELECT ancestors FROM stateknot.child_run_ownership WHERE tenant_id=$1 AND child_run_id=$2")
688 .bind(tenant.as_str()).bind(*ancestor.as_uuid()).fetch_optional(&mut **tx).await
689 .map_err(|source| StoreError::database("child ancestry prefix", source))?;
690 let expected = values[..position]
691 .iter()
692 .map(|id| *id.as_uuid())
693 .collect::<Vec<_>>();
694 if (position == 0 && stored.is_some())
695 || (position > 0 && stored.as_ref() != Some(&expected))
696 {
697 return Err(StoreError::corrupt("child ancestry prefix"));
698 }
699 }
700 Ok(values)
701}
702
703async fn load_graph(
704 tx: &mut Transaction<'_, Postgres>,
705 tenant: &TenantId,
706 reference: &GraphReference,
707) -> Result<CompiledGraph, StoreError> {
708 let row = load_graph_definition_row(tx, tenant, reference)
709 .await?
710 .ok_or(StoreError::GraphDefinitionNotFound)?;
711 let graph = decode_graph_definition(row)?.graph().clone();
712 if graph.reference() != *reference {
713 return Err(StoreError::corrupt("child graph reference"));
714 }
715 Ok(graph)
716}
717
718async fn check_topology(
719 tx: &mut Transaction<'_, Postgres>,
720 tenant: &TenantId,
721 ancestors: &[RunId],
722) -> Result<(), StoreError> {
723 let active = query_scalar::<_, Vec<Uuid>>("SELECT ancestors FROM stateknot.child_run_ownership WHERE tenant_id = $1 AND root_run_id = $2 AND NOT settled LIMIT 257")
724 .bind(tenant.as_str()).bind(*ancestors[0].as_uuid()).fetch_all(&mut **tx).await
725 .map_err(|source| StoreError::database("child active tree", source))?;
726 if active.len() > 256 {
727 return Err(StoreError::corrupt("child active tree bound"));
728 }
729 for (position, ancestor) in ancestors.iter().enumerate() {
730 let run = decode_run(fetch_locked_run_row(tx, tenant, *ancestor).await?)?;
731 if run.is_quarantined() || run.lifecycle().status() != RunStatus::Active {
732 return Err(StoreError::ChildRunRejected);
733 }
734 let row = load_agent_admission_row(tx, tenant, *ancestor)
735 .await?
736 .ok_or(StoreError::AgentAdmissionNotFound)?;
737 let admission = verify_stored_agent_admission(tx, run, row).await?;
738 let graph = load_graph(tx, tenant, admission.admission().intent().graph()).await?;
739 let limits = graph
740 .child_runs()
741 .ok_or(StoreError::ChildRunRejected)?
742 .limits();
743 let count = active
744 .iter()
745 .filter(|path| path.contains(ancestor.as_uuid()))
746 .count();
747 if ancestors.len() - position > usize::from(limits.maximum_descendant_depth())
748 || count >= usize::from(limits.maximum_active_descendants())
749 {
750 return Err(StoreError::ChildRunTopologyExceeded);
751 }
752 }
753 Ok(())
754}
755
756pub(super) async fn authorize_parent_append(
757 tx: &mut Transaction<'_, Postgres>,
758 parent: &StoredRun,
759 append: &JournalAppend,
760 fresh: bool,
761) -> Result<Timestamp, StoreError> {
762 if parent.is_quarantined() {
763 return Err(StoreError::RunQuarantined);
764 }
765 if parent.lifecycle().status().is_terminal()
766 || (fresh && parent.lifecycle().status() != RunStatus::Active)
767 {
768 return Err(StoreError::RunNotRunnable);
769 }
770 if append.expectation().head() != parent.journal_head() {
771 return Err(StoreError::StaleJournalHead);
772 }
773 let now = database_now(tx, "child parent authority clock").await?;
774 if let Some(fence) = append.worker_fence() {
775 authorize_worker(parent, fence, now)?;
776 } else if fresh {
777 return Err(StoreError::WrongAppendAuthority);
778 }
779 Ok(now.max(
780 parent
781 .journal_head()
782 .ok_or(StoreError::StaleJournalHead)?
783 .recorded_at(),
784 ))
785}
786
787pub(super) async fn mark_child_capability(
788 tx: &mut Transaction<'_, Postgres>,
789 tenant: &TenantId,
790 run: RunId,
791) -> Result<(), StoreError> {
792 query(
793 "UPDATE stateknot.runs SET child_runtime_version = 1 WHERE tenant_id = $1 AND run_id = $2",
794 )
795 .bind(tenant.as_str())
796 .bind(*run.as_uuid())
797 .execute(&mut **tx)
798 .await
799 .map_err(|source| StoreError::database("child capability fence", source))?;
800 Ok(())
801}
802
803fn spawn_projection(
804 intent: &ChildRunAdmissionIntent,
805 admission: &AgentAdmission,
806 checkpoint: &Checkpoint,
807 event: &JournalEvent,
808) -> Result<Digest, StoreError> {
809 let bytes = serde_json_canonicalizer::to_vec(&(
810 "stateknot.child-spawn.v1",
811 intent.spawn_digest(),
812 admission.digest(),
813 checkpoint.digest(),
814 event.intent_digest(),
815 ))
816 .map_err(|_| StoreError::encoding("child spawn projection"))?;
817 Ok(Digest::sha256(bytes))
818}
819
820fn settlement_projection(
821 key: Digest,
822 digest: Digest,
823 event: &JournalEvent,
824) -> Result<Digest, StoreError> {
825 Ok(Digest::sha256(
826 serde_json_canonicalizer::to_vec(&(
827 "stateknot.child-settlement.v1",
828 key,
829 digest,
830 event.intent_digest(),
831 ))
832 .map_err(|_| StoreError::encoding("child settlement projection"))?,
833 ))
834}
835
836#[allow(clippy::too_many_arguments)]
837async fn insert_owner(
838 tx: &mut Transaction<'_, Postgres>,
839 intent: &ChildRunAdmissionIntent,
840 node: &NodeAttemptStart,
841 ancestors: &[RunId],
842 child: &StoredAgentAdmission,
843 event: &JournalEvent,
844) -> Result<(), StoreError> {
845 let key = intent.key();
846 let base = key.parent().base_checkpoint();
847 let bytes = intent
848 .canonical_bytes()
849 .map_err(|_| StoreError::encoding("child intent"))?;
850 query("INSERT INTO stateknot.child_run_ownership (tenant_id,parent_run_id,key_digest,child_slot,activation_digest,spawn_digest,child_run_id,root_run_id,ancestors,intent_bytes,child_admission_digest,parent_checkpoint_id,parent_checkpoint_superstep,parent_checkpoint_digest,journal_sequence,journal_event_id,journal_recorded_at,journal_digest,key_bytes,parent_node_attempt_id) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16,$17,$18,$19,$20)")
851 .bind(key.tenant_id().as_str()).bind(*key.parent_run_id().as_uuid()).bind(key.digest().as_bytes())
852 .bind(key.slot().as_str()).bind(node.activation_digest().as_bytes()).bind(intent.spawn_digest().as_bytes())
853 .bind(*intent.child().provenance().run_id().as_uuid()).bind(*ancestors[0].as_uuid())
854 .bind(ancestors.iter().map(|run| *run.as_uuid()).collect::<Vec<_>>()).bind(bytes).bind(child.admission().digest().as_bytes())
855 .bind(*base.checkpoint_id().as_uuid()).bind(i64::try_from(base.superstep().get()).map_err(|_| StoreError::ChildRunRejected)?)
856 .bind(base.digest().as_bytes()).bind(i64::try_from(event.sequence().get()).map_err(|_| StoreError::JournalSequenceExhausted)?)
857 .bind(*event.event_id().as_uuid()).bind(to_database_time(event.recorded_at())?).bind(event.digest().as_bytes())
858 .bind(serde_json_canonicalizer::to_vec(key).map_err(|_| StoreError::encoding("child key"))?)
859 .bind(*node.attempt_id().as_uuid())
860 .execute(&mut **tx).await.map_err(|source| StoreError::database("child ownership insert", source))?;
861 Ok(())
862}
863
864async fn save_account(
865 tx: &mut Transaction<'_, Postgres>,
866 account: &ChildRunBudgetAccount,
867 head: &JournalHead,
868) -> Result<(), StoreError> {
869 let bytes = account
870 .canonical_bytes()
871 .map_err(|_| StoreError::encoding("child budget account"))?;
872 query("INSERT INTO stateknot.child_run_budget_accounts (tenant_id,parent_run_id,account_digest,account_bytes,journal_sequence,journal_event_id,journal_recorded_at,journal_digest) VALUES ($1,$2,$3,$4,$5,$6,$7,$8) ON CONFLICT (tenant_id,parent_run_id) DO UPDATE SET account_digest=EXCLUDED.account_digest,account_bytes=EXCLUDED.account_bytes,journal_sequence=EXCLUDED.journal_sequence,journal_event_id=EXCLUDED.journal_event_id,journal_recorded_at=EXCLUDED.journal_recorded_at,journal_digest=EXCLUDED.journal_digest")
873 .bind(head.tenant_id().as_str()).bind(*head.run_id().as_uuid()).bind(account.digest().as_bytes()).bind(bytes)
874 .bind(i64::try_from(head.sequence().get()).map_err(|_| StoreError::JournalSequenceExhausted)?)
875 .bind(*head.event_id().as_uuid()).bind(to_database_time(head.recorded_at())?).bind(head.digest().as_bytes())
876 .execute(&mut **tx).await.map_err(|source| StoreError::database("child budget save", source))?;
877 Ok(())
878}
879
880pub(super) async fn anchored_event(
881 tx: &mut Transaction<'_, Postgres>,
882 tenant: &TenantId,
883 run: RunId,
884 sequence: i64,
885) -> Result<(JournalEvent, Option<Digest>), StoreError> {
886 let row = query_as::<_, EventRow>(SELECT_EVENT_BY_SEQUENCE)
887 .bind(tenant.as_str())
888 .bind(*run.as_uuid())
889 .bind(sequence)
890 .fetch_optional(&mut **tx)
891 .await
892 .map_err(|source| StoreError::database("child audit anchor", source))?
893 .ok_or_else(|| StoreError::corrupt("child audit event"))?;
894 let projection = row
895 .projection_digest
896 .as_deref()
897 .map(|bytes| decode_digest(bytes, "child audit projection"))
898 .transpose()?;
899 Ok((decode_event(row)?, projection))
900}
901
902pub(super) fn row_head(
903 row: &PgRow,
904 tenant: &TenantId,
905 run: RunId,
906) -> Result<JournalHead, StoreError> {
907 let get_error = |source| StoreError::database("child head decode", source);
908 Ok(JournalHead::new(
909 tenant.clone(),
910 run,
911 positive_sequence(row.try_get("journal_sequence").map_err(get_error)?)?,
912 EventId::from_uuid(row.try_get("journal_event_id").map_err(get_error)?)
913 .map_err(|_| StoreError::corrupt("child event id"))?,
914 from_database_time(row.try_get("journal_recorded_at").map_err(get_error)?)?,
915 decode_digest(
916 &row.try_get::<Vec<u8>, _>("journal_digest")
917 .map_err(get_error)?,
918 "child event digest",
919 )?,
920 ))
921}
922
923async fn terminal_evidence(
924 tx: &mut Transaction<'_, Postgres>,
925 child: &StoredAgentAdmission,
926) -> Result<ChildRunBudgetSettlement, StoreError> {
927 let provenance = child.admission().intent().provenance();
928 let row =
929 query("SELECT * FROM stateknot.child_run_terminals WHERE tenant_id=$1 AND child_run_id=$2")
930 .bind(provenance.tenant_id().as_str())
931 .bind(*provenance.run_id().as_uuid())
932 .fetch_optional(&mut **tx)
933 .await
934 .map_err(|source| StoreError::database("child terminal load", source))?
935 .ok_or(StoreError::ChildRunSettlementUnavailable)?;
936 let head = row_head(&row, provenance.tenant_id(), provenance.run_id())?;
937 let (event, _) = anchored_event(
938 tx,
939 provenance.tenant_id(),
940 provenance.run_id(),
941 i64::try_from(head.sequence().get())
942 .map_err(|_| StoreError::corrupt("child terminal sequence"))?,
943 )
944 .await?;
945 let bytes: Vec<u8> = row
946 .try_get("lifecycle_bytes")
947 .map_err(|source| StoreError::database("child terminal bytes", source))?;
948 let digest: Vec<u8> = row
949 .try_get("lifecycle_digest")
950 .map_err(|source| StoreError::database("child terminal digest", source))?;
951 let lifecycle: RunLifecycle = serde_json::from_slice(&bytes)
952 .map_err(|_| StoreError::corrupt("child terminal lifecycle"))?;
953 if bytes != encode_lifecycle(&lifecycle)?
954 || Digest::sha256(&bytes) != decode_digest(&digest, "child terminal checksum")?
955 || event.head() != head
956 || encode_lifecycle(child.run().lifecycle())? != bytes
957 {
958 return Err(StoreError::corrupt("child terminal binding"));
959 }
960 ChildRunBudgetSettlement::new(child.admission(), &lifecycle, head)
961 .map_err(|_| StoreError::ChildRunSettlementUnavailable)
962}
963
964async fn load_settlement_event(
965 tx: &mut Transaction<'_, Postgres>,
966 key: &ChildRunKey,
967) -> Result<JournalEvent, StoreError> {
968 let row = query("SELECT * FROM stateknot.child_run_settlements WHERE tenant_id=$1 AND parent_run_id=$2 AND key_digest=$3")
969 .bind(key.tenant_id().as_str()).bind(*key.parent_run_id().as_uuid()).bind(key.digest().as_bytes()).fetch_one(&mut **tx).await
970 .map_err(|source| StoreError::database("child settlement event", source))?;
971 let head = row_head(&row, key.tenant_id(), key.parent_run_id())?;
972 let (event, _) = anchored_event(
973 tx,
974 key.tenant_id(),
975 key.parent_run_id(),
976 i64::try_from(head.sequence().get())
977 .map_err(|_| StoreError::corrupt("child settlement sequence"))?,
978 )
979 .await?;
980 if event.head() != head {
981 return Err(StoreError::corrupt("child settlement head"));
982 }
983 Ok(event)
984}
985
986#[allow(clippy::too_many_lines)]
987async fn load_record(
988 tx: &mut Transaction<'_, Postgres>,
989 key: &ChildRunKey,
990) -> Result<Option<ChildRunRecord>, StoreError> {
991 Box::pin(load_record_inner(tx, key, true)).await
992}
993
994#[allow(clippy::too_many_lines)]
995pub(super) async fn load_record_inner(
996 tx: &mut Transaction<'_, Postgres>,
997 key: &ChildRunKey,
998 lock_child: bool,
999) -> Result<Option<ChildRunRecord>, StoreError> {
1000 let sql = format!(
1001 "SELECT {OWNER_COLUMNS} FROM stateknot.child_run_ownership WHERE tenant_id=$1 AND parent_run_id=$2 AND key_digest=$3"
1002 );
1003 let Some(row) = query(&sql)
1004 .bind(key.tenant_id().as_str())
1005 .bind(*key.parent_run_id().as_uuid())
1006 .bind(key.digest().as_bytes())
1007 .fetch_optional(&mut **tx)
1008 .await
1009 .map_err(|source| StoreError::database("child owner load", source))?
1010 else {
1011 return Ok(None);
1012 };
1013 let get_error = |source| StoreError::database("child owner decode", source);
1014 let intent = decode_intent(
1015 &row.try_get::<Vec<u8>, _>("intent_bytes")
1016 .map_err(get_error)?,
1017 )?;
1018 let child_id = RunId::from_uuid(row.try_get("child_run_id").map_err(get_error)?)
1019 .map_err(|_| StoreError::corrupt("child run id"))?;
1020 let locked_child = if lock_child {
1021 Some(fetch_locked_run_row(tx, key.tenant_id(), child_id).await?)
1022 } else {
1023 None
1024 };
1025 let row = if lock_child {
1028 query(&sql)
1029 .bind(key.tenant_id().as_str())
1030 .bind(*key.parent_run_id().as_uuid())
1031 .bind(key.digest().as_bytes())
1032 .fetch_one(&mut **tx)
1033 .await
1034 .map_err(|source| StoreError::database("locked child owner projection", source))?
1035 } else {
1036 row
1037 };
1038 let parent_row = load_agent_admission_row(tx, key.tenant_id(), key.parent_run_id())
1039 .await?
1040 .ok_or_else(|| StoreError::corrupt("child parent admission"))?;
1041 let parent = decode_agent_admission(&parent_row)?;
1042 let node_id = AttemptId::from_uuid(row.try_get("parent_node_attempt_id").map_err(get_error)?)
1043 .map_err(|_| StoreError::corrupt("child node attempt id"))?;
1044 let node = load_node_attempt_record(tx, key.tenant_id(), &key.parent_run_id(), node_id)
1045 .await?
1046 .ok_or_else(|| StoreError::corrupt("child node attempt"))?;
1047 verify_node_attempt_start(tx, node.start()).await?;
1048 if node.start().activation() != key.parent()
1049 || node.start().activation_digest()
1050 != decode_digest(
1051 &row.try_get::<Vec<u8>, _>("activation_digest")
1052 .map_err(get_error)?,
1053 "child activation",
1054 )?
1055 || row.try_get::<Vec<u8>, _>("key_bytes").map_err(get_error)?
1056 != serde_json_canonicalizer::to_vec(key)
1057 .map_err(|_| StoreError::corrupt("child key bytes"))?
1058 {
1059 return Err(StoreError::corrupt("child node activation"));
1060 }
1061 let checkpoint_row = query_as::<_, CheckpointRow>(SELECT_CHECKPOINT_BY_ID)
1062 .bind(key.tenant_id().as_str())
1063 .bind(*key.parent_run_id().as_uuid())
1064 .bind(*key.parent().base_checkpoint().checkpoint_id().as_uuid())
1065 .fetch_one(&mut **tx)
1066 .await
1067 .map_err(|source| StoreError::database("child base checkpoint", source))?;
1068 let checkpoint = decode_checkpoint(checkpoint_row)?;
1069 verify_checkpoint_anchor(tx, &checkpoint).await?;
1070 if checkpoint.head() != *key.parent().base_checkpoint()
1071 || !node_attempt_activation_is_ready(&checkpoint, key.parent())
1072 {
1073 return Err(StoreError::corrupt("child checkpoint activation"));
1074 }
1075 let graph = load_graph(tx, key.tenant_id(), parent.intent().graph()).await?;
1076 if load_graph(tx, key.tenant_id(), intent.child().graph()).await? != *intent.child_graph() {
1077 return Err(StoreError::corrupt("owned child graph"));
1078 }
1079 intent
1080 .validate_declaration(&graph)
1081 .map_err(|_| StoreError::corrupt("child declaration"))?;
1082 if intent.key() != key
1083 || intent.parent_admission_digest() != parent.digest()
1084 || intent.child().provenance().run_id() != child_id
1085 || row.try_get::<String, _>("child_slot").map_err(get_error)? != key.slot().as_str()
1086 || decode_digest(
1087 &row.try_get::<Vec<u8>, _>("spawn_digest")
1088 .map_err(get_error)?,
1089 "child spawn digest",
1090 )? != intent.spawn_digest()
1091 || row
1092 .try_get::<Uuid, _>("parent_checkpoint_id")
1093 .map_err(get_error)?
1094 != *key.parent().base_checkpoint().checkpoint_id().as_uuid()
1095 || row
1096 .try_get::<i64, _>("parent_checkpoint_superstep")
1097 .map_err(get_error)?
1098 != i64::try_from(key.parent().base_checkpoint().superstep().get())
1099 .map_err(|_| StoreError::corrupt("child base step"))?
1100 || decode_digest(
1101 &row.try_get::<Vec<u8>, _>("parent_checkpoint_digest")
1102 .map_err(get_error)?,
1103 "child base digest",
1104 )? != key.parent().base_checkpoint().digest()
1105 {
1106 return Err(StoreError::corrupt("child ownership projection"));
1107 }
1108 let head = row_head(&row, key.tenant_id(), key.parent_run_id())?;
1109 let (spawn, projection) = anchored_event(
1110 tx,
1111 key.tenant_id(),
1112 key.parent_run_id(),
1113 i64::try_from(head.sequence().get())
1114 .map_err(|_| StoreError::corrupt("child spawn sequence"))?,
1115 )
1116 .await?;
1117 let child_run = if let Some(row) = locked_child {
1121 decode_run(row)?
1122 } else {
1123 decode_run(
1124 query_as::<_, RunRow>(SELECT_RUN)
1125 .bind(key.tenant_id().as_str())
1126 .bind(*child_id.as_uuid())
1127 .fetch_one(&mut **tx)
1128 .await
1129 .map_err(|source| StoreError::database("owned child run", source))?,
1130 )?
1131 };
1132 let child_row = load_agent_admission_row(tx, key.tenant_id(), child_id)
1133 .await?
1134 .ok_or_else(|| StoreError::corrupt("owned child admission"))?;
1135 let child = verify_stored_agent_admission(tx, child_run, child_row).await?;
1136 if child.admission().intent() != intent.child()
1137 || child.checkpoint().state() != intent.initial_state()
1138 || child.admission().digest()
1139 != decode_digest(
1140 &row.try_get::<Vec<u8>, _>("child_admission_digest")
1141 .map_err(get_error)?,
1142 "owned admission digest",
1143 )?
1144 || spawn.head() != head
1145 || spawn.source().worker_fence() != Some(node.start().fence())
1146 || spawn.sequence() <= node.start().journal_head().sequence()
1147 || spawn.payload().kind().as_str() != "child-run-admitted"
1148 || projection
1149 != Some(spawn_projection(
1150 &intent,
1151 child.admission(),
1152 child.checkpoint(),
1153 &spawn,
1154 )?)
1155 {
1156 return Err(StoreError::corrupt("child atomic anchors"));
1157 }
1158 let expected_path = ancestry(tx, key.tenant_id(), key.parent_run_id()).await?;
1159 let path: Vec<Uuid> = row.try_get("ancestors").map_err(get_error)?;
1160 if path
1161 != expected_path
1162 .iter()
1163 .map(|id| *id.as_uuid())
1164 .collect::<Vec<_>>()
1165 || row.try_get::<Uuid, _>("root_run_id").map_err(get_error)? != *expected_path[0].as_uuid()
1166 {
1167 return Err(StoreError::corrupt("child ancestry projection"));
1168 }
1169 let settled: bool = row.try_get("settled").map_err(get_error)?;
1170 let pending: Option<DateTime<Utc>> = row.try_get("terminal_pending_at").map_err(get_error)?;
1171 let terminal_at = query_scalar::<_, DateTime<Utc>>("SELECT journal_recorded_at FROM stateknot.child_run_terminals WHERE tenant_id=$1 AND child_run_id=$2")
1172 .bind(key.tenant_id().as_str()).bind(*child_id.as_uuid()).fetch_optional(&mut **tx).await
1173 .map_err(|source| StoreError::database("child notification evidence", source))?;
1174 if terminal_at.is_some() != child.run().lifecycle().status().is_terminal()
1175 || pending != if settled { None } else { terminal_at }
1176 {
1177 return Err(StoreError::corrupt("child terminal notification"));
1178 }
1179 let settlement_row = query("SELECT * FROM stateknot.child_run_settlements WHERE tenant_id=$1 AND parent_run_id=$2 AND key_digest=$3")
1180 .bind(key.tenant_id().as_str()).bind(*key.parent_run_id().as_uuid()).bind(key.digest().as_bytes()).fetch_optional(&mut **tx).await
1181 .map_err(|source| StoreError::database("child settlement load", source))?;
1182 if settled != settlement_row.is_some() {
1183 return Err(StoreError::corrupt("child settlement projection"));
1184 }
1185 let settlement = if let Some(row) = settlement_row {
1186 let bytes: Vec<u8> = row.try_get("settlement_bytes").map_err(get_error)?;
1187 let evidence: ChildRunBudgetSettlement = serde_json::from_slice(&bytes)
1188 .map_err(|_| StoreError::corrupt("child settlement bytes"))?;
1189 let digest = Digest::sha256(&bytes);
1190 let expected = terminal_evidence(tx, &child).await?;
1191 let head = row_head(&row, key.tenant_id(), key.parent_run_id())?;
1192 let (event, projection) = anchored_event(
1193 tx,
1194 key.tenant_id(),
1195 key.parent_run_id(),
1196 i64::try_from(head.sequence().get())
1197 .map_err(|_| StoreError::corrupt("settlement sequence"))?,
1198 )
1199 .await?;
1200 if evidence != expected
1201 || serde_json_canonicalizer::to_vec(&evidence)
1202 .map_err(|_| StoreError::corrupt("settlement encoding"))?
1203 != bytes
1204 || decode_digest(
1205 &row.try_get::<Vec<u8>, _>("settlement_digest")
1206 .map_err(get_error)?,
1207 "child settlement checksum",
1208 )? != digest
1209 || row.try_get::<Uuid, _>("child_run_id").map_err(get_error)? != *child_id.as_uuid()
1210 || head != event.head()
1211 || projection != Some(settlement_projection(key.digest(), digest, &event)?)
1212 || event.payload().kind().as_str() != "child-run-settled"
1213 {
1214 return Err(StoreError::corrupt("child settlement anchors"));
1215 }
1216 Some(evidence)
1217 } else {
1218 None
1219 };
1220 Ok(Some(ChildRunRecord {
1221 intent,
1222 child,
1223 spawn,
1224 ancestors: expected_path,
1225 settlement,
1226 }))
1227}
1228
1229async fn load_account(
1230 tx: &mut Transaction<'_, Postgres>,
1231 tenant: &TenantId,
1232 parent_id: RunId,
1233) -> Result<Option<ChildRunBudgetAccount>, StoreError> {
1234 Box::pin(load_account_inner(tx, tenant, parent_id, true)).await
1235}
1236
1237pub(super) async fn load_account_inner(
1238 tx: &mut Transaction<'_, Postgres>,
1239 tenant: &TenantId,
1240 parent_id: RunId,
1241 lock_children: bool,
1242) -> Result<Option<ChildRunBudgetAccount>, StoreError> {
1243 let row = query(
1244 "SELECT * FROM stateknot.child_run_budget_accounts WHERE tenant_id=$1 AND parent_run_id=$2",
1245 )
1246 .bind(tenant.as_str())
1247 .bind(*parent_id.as_uuid())
1248 .fetch_optional(&mut **tx)
1249 .await
1250 .map_err(|source| StoreError::database("child budget load", source))?;
1251 let Some(row) = row else {
1252 let exists = query_scalar::<_, bool>("SELECT EXISTS (SELECT 1 FROM stateknot.child_run_ownership WHERE tenant_id=$1 AND parent_run_id=$2)")
1253 .bind(tenant.as_str()).bind(*parent_id.as_uuid()).fetch_one(&mut **tx).await.map_err(|source| StoreError::database("child budget completeness", source))?;
1254 if exists {
1255 return Err(StoreError::corrupt("child budget missing"));
1256 }
1257 return Ok(None);
1258 };
1259 let get_error = |source| StoreError::database("child budget decode", source);
1260 let bytes: Vec<u8> = row.try_get("account_bytes").map_err(get_error)?;
1261 if bytes.len() > ChildRunBudgetAccount::MAX_SNAPSHOT_BYTES {
1262 return Err(StoreError::corrupt("child budget size"));
1263 }
1264 let account: ChildRunBudgetAccount =
1265 serde_json::from_slice(&bytes).map_err(|_| StoreError::corrupt("child budget account"))?;
1266 let head = row_head(&row, tenant, parent_id)?;
1267 let (event, _) = anchored_event(
1268 tx,
1269 tenant,
1270 parent_id,
1271 i64::try_from(head.sequence().get())
1272 .map_err(|_| StoreError::corrupt("child budget sequence"))?,
1273 )
1274 .await?;
1275 let (direct_event, _) = anchored_event(
1276 tx,
1277 tenant,
1278 parent_id,
1279 i64::try_from(account.direct_head().sequence().get())
1280 .map_err(|_| StoreError::corrupt("child direct head"))?,
1281 )
1282 .await?;
1283 if direct_event.head() != *account.direct_head() {
1284 return Err(StoreError::corrupt("child direct anchor"));
1285 }
1286 let admission_row = load_agent_admission_row(tx, tenant, parent_id)
1287 .await?
1288 .ok_or_else(|| StoreError::corrupt("child budget parent"))?;
1289 let admission = decode_agent_admission(&admission_row)?;
1290 let graph = load_graph(tx, tenant, admission.intent().graph()).await?;
1291 account
1292 .validate_for(&admission, &graph)
1293 .map_err(|_| StoreError::corrupt("child budget parent binding"))?;
1294 if account
1295 .canonical_bytes()
1296 .map_err(|_| StoreError::corrupt("child budget encoding"))?
1297 != bytes
1298 || account.digest()
1299 != decode_digest(
1300 &row.try_get::<Vec<u8>, _>("account_digest")
1301 .map_err(get_error)?,
1302 "child budget checksum",
1303 )?
1304 || head != event.head()
1305 || account.direct_head().sequence() > head.sequence()
1306 {
1307 return Err(StoreError::corrupt("child budget anchor"));
1308 }
1309 let count = query_scalar::<_, i64>("SELECT count(*) FROM stateknot.child_run_ownership WHERE tenant_id=$1 AND parent_run_id=$2")
1310 .bind(tenant.as_str()).bind(*parent_id.as_uuid()).fetch_one(&mut **tx).await.map_err(|source| StoreError::database("child budget entry count", source))?;
1311 if usize::try_from(count).ok() != Some(account.children().len()) {
1312 return Err(StoreError::corrupt("child budget completeness"));
1313 }
1314 for entry in account.children() {
1315 let record = Box::pin(load_record_inner(tx, entry.key(), lock_children))
1316 .await?
1317 .ok_or_else(|| StoreError::corrupt("child budget ownership"))?;
1318 if entry.spawn_digest() != record.intent.spawn_digest()
1319 || entry.child() != record.child.admission().intent().provenance()
1320 || entry.intent_digest() != record.child.admission().intent().intent_digest()
1321 || entry.settlement() != record.settlement.as_ref()
1322 || entry.reservation()
1323 != &stateknot_core::CumulativeBudgetReservation::from_budget(
1324 record.intent.child().budget(),
1325 )
1326 .map_err(|_| StoreError::corrupt("child reservation"))?
1327 {
1328 return Err(StoreError::corrupt("child budget entry binding"));
1329 }
1330 }
1331 Ok(Some(account))
1332}
1333
1334pub(super) async fn verify_schema(pool: &PgPool) -> Result<(), StoreError> {
1335 let complete = query_scalar::<_, bool>(r"SELECT
1336 NOT EXISTS (
1337 SELECT 1 FROM (VALUES
1338 ('runs_child_mutation_guard', 'stateknot.runs', 'stateknot.guard_child_run_mutation()', 19),
1339 ('runs_child_terminal_capture', 'stateknot.runs', 'stateknot.capture_child_run_terminal()', 17),
1340 ('admissions_child_capability', 'stateknot.agent_admissions', 'stateknot.mark_child_graph_admission()', 5),
1341 ('tool_revisions_child_budget_guard', 'stateknot.tool_invocation_revisions', 'stateknot.guard_child_direct_invocation()', 7),
1342 ('model_revisions_child_budget_guard', 'stateknot.model_invocation_revisions', 'stateknot.guard_child_direct_invocation()', 7),
1343 ('ownership_child_immutable', 'stateknot.child_run_ownership', 'stateknot.guard_child_evidence()', 27),
1344 ('terminals_child_immutable', 'stateknot.child_run_terminals', 'stateknot.guard_child_evidence()', 27),
1345 ('settlements_child_immutable', 'stateknot.child_run_settlements', 'stateknot.guard_child_evidence()', 27)
1346 ) AS expected(name, relation, function, mask)
1347 WHERE NOT EXISTS (SELECT 1 FROM pg_trigger WHERE tgname = expected.name
1348 AND tgrelid = to_regclass(expected.relation) AND tgfoid = to_regprocedure(expected.function)
1349 AND tgenabled = 'O' AND NOT tgisinternal AND tgtype = expected.mask)
1350 )
1351 AND NOT EXISTS (
1352 SELECT 1 FROM (VALUES
1353 ('child_run_budget_accounts_admission_fk', 'stateknot.child_run_budget_accounts', 'stateknot.agent_admissions'),
1354 ('child_run_budget_accounts_event_fk', 'stateknot.child_run_budget_accounts', 'stateknot.run_events'),
1355 ('child_run_ownership_parent_fk', 'stateknot.child_run_ownership', 'stateknot.agent_admissions'),
1356 ('child_run_ownership_child_fk', 'stateknot.child_run_ownership', 'stateknot.agent_admissions'),
1357 ('child_run_ownership_root_fk', 'stateknot.child_run_ownership', 'stateknot.agent_admissions'),
1358 ('child_run_ownership_node_fk', 'stateknot.child_run_ownership', 'stateknot.node_attempts'),
1359 ('child_run_ownership_budget_fk', 'stateknot.child_run_ownership', 'stateknot.child_run_budget_accounts'),
1360 ('child_run_ownership_checkpoint_fk', 'stateknot.child_run_ownership', 'stateknot.run_checkpoints'),
1361 ('child_run_ownership_event_fk', 'stateknot.child_run_ownership', 'stateknot.run_events'),
1362 ('child_run_terminals_owner_fk', 'stateknot.child_run_terminals', 'stateknot.child_run_ownership'),
1363 ('child_run_terminals_event_fk', 'stateknot.child_run_terminals', 'stateknot.run_events'),
1364 ('child_run_settlements_owner_fk', 'stateknot.child_run_settlements', 'stateknot.child_run_ownership'),
1365 ('child_run_settlements_terminal_fk', 'stateknot.child_run_settlements', 'stateknot.child_run_terminals'),
1366 ('child_run_settlements_event_fk', 'stateknot.child_run_settlements', 'stateknot.run_events')
1367 ) AS expected(name, relation, target)
1368 WHERE NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = expected.name
1369 AND conrelid = to_regclass(expected.relation) AND confrelid = to_regclass(expected.target)
1370 AND contype = 'f' AND convalidated AND confdeltype = 'r')
1371 )
1372 AND (SELECT count(*) = 4 FROM pg_constraint WHERE convalidated AND conname IN
1373 ('child_run_ownership_child_unique','child_run_ownership_exact_unique','child_run_ownership_ancestry_valid','runs_child_runtime_version_valid')
1374 AND connamespace = to_regnamespace('stateknot'))
1375 AND (SELECT count(*) = 2 FROM pg_index WHERE indisvalid AND indisready AND indislive
1376 AND indrelid = to_regclass('stateknot.child_run_ownership') AND indpred IS NOT NULL
1377 AND indexrelid IN (to_regclass('stateknot.child_run_ownership_active_tree'),to_regclass('stateknot.child_run_ownership_terminal_pending')))
1378 AND EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = to_regclass('stateknot.runs')
1379 AND attname = 'child_runtime_version' AND atttypid = 'int2'::regtype AND attnotnull AND NOT attisdropped)")
1380 .fetch_one(pool).await.map_err(|source| StoreError::database("child schema verification", source))?;
1381 if !complete {
1382 return Err(StoreError::IncompleteSchema);
1383 }
1384 for function in include_str!("../migrations/0020_child_run_ownership.sql")
1386 .split("CREATE FUNCTION stateknot.")
1387 .skip(1)
1388 {
1389 let (name, _) = function
1390 .split_once("() RETURNS trigger")
1391 .ok_or(StoreError::IncompleteSchema)?;
1392 let body = function
1393 .split("$$")
1394 .nth(1)
1395 .ok_or(StoreError::IncompleteSchema)?;
1396 let installed = query_scalar::<_, String>("SELECT prosrc FROM pg_proc JOIN pg_language ON pg_language.oid=prolang WHERE pg_proc.oid=to_regprocedure($1) AND NOT prosecdef AND lanname='plpgsql'")
1397 .bind(format!("stateknot.{name}()")).fetch_optional(pool).await
1398 .map_err(|source| StoreError::database("child guard definition verification", source))?;
1399 if installed.as_deref() != Some(body) {
1400 return Err(StoreError::IncompleteSchema);
1401 }
1402 }
1403 Ok(())
1404}