Skip to main content

stateknot_store_postgres/
child_runs.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Transactional local ownership. High-level child joins are a separate runtime boundary.
5
6// This private module shares the store's transaction and integrity helpers.
7#[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/// Fully verified ownership, the original child identities and committed spawn event.
16#[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    /// Returns the original immutable spawn intent, not replacement retry IDs.
27    #[must_use]
28    pub const fn intent(&self) -> &ChildRunAdmissionIntent {
29        &self.intent
30    }
31    /// Returns the isolated child admission and current child run projection.
32    #[must_use]
33    pub const fn child(&self) -> &StoredAgentAdmission {
34        &self.child
35    }
36    /// Returns the exact parent journal event committed with ownership/admission.
37    #[must_use]
38    pub const fn spawn(&self) -> &JournalEvent {
39        &self.spawn
40    }
41    /// Returns root-to-parent ancestry, with at most 32 distinct identities.
42    #[must_use]
43    pub fn ancestors(&self) -> &[RunId] {
44        &self.ancestors
45    }
46    /// Returns verified once-only accounting settlement, not a runtime Join.
47    #[must_use]
48    pub const fn settlement(&self) -> Option<&ChildRunBudgetSettlement> {
49        self.settlement.as_ref()
50    }
51}
52
53/// Result of atomic child ownership/admission/account reservation.
54#[derive(Clone, Debug)]
55#[non_exhaustive]
56pub enum ChildRunCommitOutcome {
57    /// All ownership, admission, checkpoint, budget and audit facts committed together.
58    Committed(ChildRunRecord),
59    /// The original logical key/intent already committed, including after lease expiry.
60    Idempotent(ChildRunRecord),
61}
62impl ChildRunCommitOutcome {
63    /// Returns the original durable child record for either outcome.
64    #[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/// Result of replacing one reservation with immutable child terminal usage.
73#[derive(Clone, Debug)]
74#[non_exhaustive]
75pub enum ChildRunSettlementOutcome {
76    /// Exact terminal evidence and the new parent account committed atomically.
77    Committed {
78        /// Parent accounting audit event.
79        event: JournalEvent,
80        /// Original owned-child record with terminal settlement.
81        record: ChildRunRecord,
82    },
83    /// The ownership already had this exact terminal settlement.
84    Idempotent {
85        /// Original accounting audit event.
86        event: JournalEvent,
87        /// Original owned-child record with terminal settlement.
88        record: ChildRunRecord,
89    },
90}
91
92impl PostgresStore {
93    /// Atomically creates one fresh isolated child and reserves its complete budget.
94    ///
95    /// `direct_usage` is a trusted, complete DIRECT-only parent observation at the
96    /// exact journal head in `parent_append`; it must exclude child subtree usage.
97    /// Schema callbacks run before the mutation transaction. The transaction locks
98    /// the tree coordinator, then ancestors root-to-parent, and rechecks readiness,
99    /// a live node start/fence, immutable admission, all ancestor limits and budget.
100    /// Parent model/tool invocations may not overlap outstanding child work.
101    ///
102    /// Same logical key and spawn digest recover the original child BEFORE fresh
103    /// lease/deadline/readiness checks. Candidate audit/checkpoint/Run IDs cannot
104    /// replace it. Existing arbitrary root runs cannot be attached as children.
105    /// Trusted caller authentication/delegation policy remains a server boundary.
106    #[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        // All ancestors are locked before checking cancellation and live counts.
167        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(&current, 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, &current).await?;
223        ensure_no_unsettled_model_invocations(&mut tx, &current).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        // Reject existing identities without inverting admission-key/run lock order.
253        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?; // final live database-time fence
309        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    /// Loads fully verified ownership and original child identities within one
319    /// repeatable-read snapshot. Callers authenticate read access before lookup.
320    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    /// Returns a verified accounting projection, not a fresh direct-usage report.
348    /// Invocation providers must add/subtract delegated charges exactly once.
349    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    /// Adds settled immediate-child subtree charges to complete DIRECT-only usage.
363    /// Outstanding children fail closed. The eventual journal CAS and terminal
364    /// mutation revalidate the account; this read alone never authorizes closure.
365    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    /// Lists at most 256 retained key/child identity pairs without materializing
388    /// private input snapshots. The next exact record load verifies all evidence.
389    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    /// Discovers at most sixteen durable terminal notifications for reconciliation.
411    /// Records remain discoverable until a successful settlement transaction;
412    /// there is no cursor/notification race or destructive dequeue before commit.
413    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    /// Continues a bounded notification sweep after its last returned key.
421    /// The immutable terminal anchor retains the cursor after settlement. Skip
422    /// unpriced/quarantined items and continue so they cannot block later work.
423    /// Restart from None after each complete sweep: commit order need not equal
424    /// timestamp order. This is discovery, never a permanent delivery watermark.
425    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        // Separate query shapes keep the cursor in the btree range condition,
442        // including PostgreSQL generic plans; an optional-parameter OR can scan
443        // an arbitrarily long earlier prefix of unresolved notifications.
444        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    /// Settles one child's complete immutable terminal evidence exactly once.
474    ///
475    /// No external code runs under the transaction. It locks the tree, parent,
476    /// then child; child terminal commits never lock parents. Control-plane or
477    /// currently fenced worker audit writes are accepted. Unpriced outcomes stay
478    /// outstanding and discoverable. This accounting operation is not a Join.
479    #[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        // load_record already locks this existing child's Run. Taking the root
513        // admission-key lock here would invert that API's key -> Run lock order.
514        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
581/// Called with the parent row locked, after idempotency recovery and before dispatch.
582pub(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
605/// All terminal writers share this check, including generic control-plane appends.
606pub(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    // Every prefix must be the immutable ownership path of that ancestor;
685    // checking only the immediate parent's cached array could hide a broken tree.
686    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    // Terminal capture can update the ownership notification while acquiring
1026    // that child lock. Refresh its mutable projection AFTER the lock, too.
1027    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    // Read-only callers use one repeatable-read snapshot. Mutation callers
1118    // already hold the parent lock and lock the child before reading its
1119    // lifecycle/terminal notification, avoiding READ COMMITTED torn evidence.
1120    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    // Verify actual installed guard code, not only names/checksummed migration history.
1385    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}