Skip to main content

stateknot_store_postgres/
child_joins.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Dedicated, sealed child Join storage. No user code runs in a transaction.
5
6#[allow(clippy::wildcard_imports)]
7use super::*;
8use stateknot_core::{ChildRunJoinBinding, ChildRunJoinHead, ChildRunJoinRequest};
9
10/// Verified registration and optional publication/consumption, without copying
11/// child output payloads. Publication is not parent result consumption.
12#[derive(Clone, Debug)]
13pub struct ChildJoinRecord {
14    request: ChildRunJoinRequest,
15    registration: JournalEvent,
16    binding: Option<ChildRunJoinBinding>,
17    head: Option<ChildRunJoinHead>,
18    consumed: Option<JournalHead>,
19}
20impl ChildJoinRecord {
21    /// Returns the complete sealed set in canonical slot order.
22    #[must_use]
23    pub const fn request(&self) -> &ChildRunJoinRequest {
24        &self.request
25    }
26    /// Returns the event committed atomically with parent lease release.
27    #[must_use]
28    pub const fn registration(&self) -> &JournalEvent {
29        &self.registration
30    }
31    /// Returns immutable complete terminal evidence, if published.
32    #[must_use]
33    pub const fn binding(&self) -> Option<&ChildRunJoinBinding> {
34        self.binding.as_ref()
35    }
36    /// Bind this exact head to the pending parent result; reading is not consumption.
37    #[must_use]
38    pub const fn head(&self) -> Option<&ChildRunJoinHead> {
39        self.head.as_ref()
40    }
41    /// Returns the exact pending-result event that consumed publication once.
42    #[must_use]
43    pub const fn consumed(&self) -> Option<&JournalHead> {
44        self.consumed.as_ref()
45    }
46}
47
48/// Both outcomes return original identities; retry candidates cannot replace evidence.
49#[derive(Clone, Debug)]
50#[non_exhaustive]
51pub enum ChildJoinCommitOutcome {
52    /// Fresh atomic registration or publication.
53    Committed(ChildJoinRecord),
54    /// Original fact recovered before fresh fence/head/lifecycle checks.
55    Idempotent(ChildJoinRecord),
56}
57impl ChildJoinCommitOutcome {
58    /// Returns verified original evidence for either outcome.
59    #[must_use]
60    pub const fn record(&self) -> &ChildJoinRecord {
61        match self {
62            Self::Committed(record) | Self::Idempotent(record) => record,
63        }
64    }
65}
66
67impl PostgresStore {
68    /// Seals ALL children owned by one exact current activation, journals the
69    /// registration, and releases the parent lease in the SAME transaction.
70    ///
71    /// Requires an unfinished live physical start and exclusive ownership of the
72    /// Run execution boundary: no other unfinished physical node in the current
73    /// fence may exist. The original attempt remains executing, not a fabricated
74    /// failure/completion. Higher-fence recovery may re-enter the logical node.
75    /// No new child slot can be added after registration. The caller must stop
76    /// dispatching on the released fence and arrange bounded publication scans.
77    /// Cancellation bypasses this successful-wait gate, retaining all evidence.
78    #[allow(clippy::too_many_lines)]
79    pub async fn register_child_join(
80        &self,
81        request: ChildRunJoinRequest,
82        node: &NodeAttemptStartHead,
83        append: JournalAppend,
84    ) -> Result<ChildJoinCommitOutcome, StoreError> {
85        validate_append(&request, &append, "child-join-registered")?;
86        let activation = request.activation();
87        let mut tx = self.begin_mutation("child Join registration").await?;
88        lock_parent(&mut tx, activation).await?;
89        if let Some(record) = load(&mut tx, activation, true).await? {
90            if record.request() != &request {
91                return Err(StoreError::ChildJoinRejected);
92            }
93            tx.commit()
94                .await
95                .map_err(|source| StoreError::database("child Join retry", source))?;
96            return Ok(ChildJoinCommitOutcome::Idempotent(record));
97        }
98        let parent = decode_run(
99            fetch_locked_run_row(&mut tx, activation.tenant_id(), activation.run_id()).await?,
100        )?;
101        let at = child_runs::authorize_parent_append(&mut tx, &parent, &append, true).await?;
102        if node.activation() != activation || append.worker_fence() != Some(node.fence()) {
103            return Err(StoreError::ChildJoinRejected);
104        }
105        let checkpoint = load_locked_current_checkpoint(
106            &mut tx,
107            &parent,
108            activation.tenant_id(),
109            activation.run_id(),
110        )
111        .await?
112        .ok_or(StoreError::StaleCheckpointHead)?;
113        if checkpoint.head() != *activation.base_checkpoint()
114            || !node_attempt_activation_is_ready(&checkpoint, activation)
115        {
116            return Err(StoreError::StaleCheckpointHead);
117        }
118        let attempt = load_locked_node_attempt(&mut tx, node).await?;
119        verify_node_attempt_start(&mut tx, attempt.start()).await?;
120        if attempt.start().head() != *node
121            || attempt.completion().is_some()
122            || load_pending_node_result_row(&mut tx, activation)
123                .await?
124                .is_some()
125        {
126            return Err(StoreError::ChildJoinRejected);
127        }
128        let overlapping = query_scalar::<_, bool>("SELECT EXISTS (SELECT 1 FROM stateknot.node_attempts n WHERE n.tenant_id=$1 AND n.run_id=$2 AND n.fence_attempt_id=$3 AND n.attempt_id<>$4 AND NOT EXISTS (SELECT 1 FROM stateknot.node_attempt_completions c WHERE c.tenant_id=n.tenant_id AND c.run_id=n.run_id AND c.attempt_id=n.attempt_id))")
129            .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid())
130            .bind(*node.fence().attempt_id().as_uuid()).bind(*node.attempt_id().as_uuid())
131            .fetch_one(&mut *tx).await.map_err(|source| StoreError::database("child Join exclusive boundary", source))?;
132        if overlapping {
133            return Err(StoreError::ChildJoinRejected);
134        }
135        ensure_no_unsettled_tool_invocations(&mut tx, &checkpoint).await?;
136        ensure_no_unsettled_model_invocations(&mut tx, &checkpoint).await?;
137        verify_members(&mut tx, &request, true).await?;
138        let event =
139            JournalEvent::commit(append, at).map_err(|error| map_event_commit_error(&error))?;
140        insert_event(
141            &mut tx,
142            &event,
143            projection("registration", request.digest(), node.digest(), &event)?,
144        )
145        .await?;
146        // The worker append checks the live fence before the same transaction
147        // installs the wait gate and clears that lease.
148        update_run_head(&mut tx, &event, None).await?;
149        let bytes = request
150            .canonical_bytes()
151            .map_err(|_| StoreError::ChildJoinRejected)?;
152        query("INSERT INTO stateknot.child_run_joins (tenant_id,parent_run_id,activation_digest,request_digest,request_bytes,request_checksum,base_checkpoint_id,graph_namespace,node_id,node_attempt_id,journal_sequence,journal_event_id,journal_recorded_at,journal_digest) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)")
153            .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid())
154            .bind(request.activation_digest().as_bytes()).bind(request.digest().as_bytes())
155            .bind(&bytes).bind(Digest::sha256(&bytes).as_bytes())
156            .bind(*activation.base_checkpoint().checkpoint_id().as_uuid()).bind(activation.graph_namespace().as_str()).bind(activation.node_id().as_str())
157            .bind(*node.attempt_id().as_uuid()).bind(sequence(&event.head())?).bind(*event.event_id().as_uuid())
158            .bind(to_database_time(at)?).bind(event.digest().as_bytes())
159            .execute(&mut *tx).await.map_err(|source| StoreError::database("child Join insert", source))?;
160        // Check lease expiry again at the write, not only before evidence reads.
161        let released = query("UPDATE stateknot.runs SET lease_attempt_id=NULL,lease_acquired_at=NULL,lease_renewed_at=NULL,lease_expires_at=NULL,scheduler_not_before=NULL,updated_at=$5 WHERE tenant_id=$1 AND run_id=$2 AND lease_attempt_id=$3 AND fencing_epoch=$4 AND lease_expires_at>clock_timestamp()")
162            .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid())
163            .bind(*node.fence().attempt_id().as_uuid()).bind(i64::try_from(node.fence().epoch().get()).map_err(|_| StoreError::StaleFence)?)
164            .bind(to_database_time(at)?).execute(&mut *tx).await.map_err(|source| StoreError::database("child Join lease release", source))?.rows_affected();
165        if released != 1 {
166            return Err(StoreError::LeaseExpired);
167        }
168        let record = load(&mut tx, activation, true)
169            .await?
170            .ok_or(StoreError::ChildJoinRejected)?;
171        tx.commit()
172            .await
173            .map_err(|source| StoreError::database("child Join register commit", source))?;
174        Ok(ChildJoinCommitOutcome::Committed(record))
175    }
176
177    /// Publishes one immutable complete terminal binding and makes an Active
178    /// parent claimable. Requires every sealed child's verified priced settlement.
179    /// No child outputs are merged, no budgets are charged, and no result is
180    /// consumed here. Registration before/after completion uses the same durable
181    /// discovery predicate: there is no destructive notification dequeue.
182    pub async fn publish_child_join(
183        &self,
184        request: &ChildRunJoinRequest,
185        append: JournalAppend,
186    ) -> Result<ChildJoinCommitOutcome, StoreError> {
187        validate_append(request, &append, "child-join-published")?;
188        if append.worker_fence().is_some() {
189            return Err(StoreError::WrongAppendAuthority);
190        }
191        let activation = request.activation();
192        let mut tx = self.begin_mutation("child Join publication").await?;
193        lock_parent(&mut tx, activation).await?;
194        let record = load(&mut tx, activation, true)
195            .await?
196            .ok_or(StoreError::ChildJoinRejected)?;
197        if record.request() != request {
198            return Err(StoreError::ChildJoinRejected);
199        }
200        if record.binding().is_some() {
201            tx.commit()
202                .await
203                .map_err(|source| StoreError::database("child Join publish retry", source))?;
204            return Ok(ChildJoinCommitOutcome::Idempotent(record));
205        }
206        let parent = decode_run(
207            fetch_locked_run_row(&mut tx, activation.tenant_id(), activation.run_id()).await?,
208        )?;
209        if parent.lifecycle().status() != RunStatus::Active {
210            return Err(StoreError::RunNotRunnable);
211        }
212        if failure_closes::exists(&mut tx, activation.tenant_id(), activation.run_id()).await? {
213            return Err(StoreError::RunFailureClosing);
214        }
215        let at = child_runs::authorize_parent_append(&mut tx, &parent, &append, false).await?;
216        let terminals = verify_members(&mut tx, request, true)
217            .await?
218            .ok_or(StoreError::ChildRunSettlementUnavailable)?;
219        let binding = ChildRunJoinBinding::new(request.clone(), terminals)
220            .map_err(|_| StoreError::ChildJoinRejected)?;
221        let at = binding
222            .terminals()
223            .iter()
224            .fold(at, |clock, value| clock.max(value.terminal().recorded_at()));
225        let event =
226            JournalEvent::commit(append, at).map_err(|error| map_event_commit_error(&error))?;
227        let head = binding
228            .head(event.head())
229            .map_err(|_| StoreError::ChildJoinRejected)?;
230        insert_event(
231            &mut tx,
232            &event,
233            projection("publication", request.digest(), binding.digest(), &event)?,
234        )
235        .await?;
236        let bytes = binding
237            .canonical_bytes()
238            .map_err(|_| StoreError::ChildJoinRejected)?;
239        query("INSERT INTO stateknot.child_run_join_bindings (tenant_id,parent_run_id,activation_digest,binding_bytes,binding_checksum,head_bytes,journal_sequence,journal_event_id,journal_recorded_at,journal_digest,ready_at) SELECT $1,$2,$3,$4,$5,$6,$7,$8,$9,$10,GREATEST(clock_timestamp(),queued_at) FROM stateknot.child_run_joins WHERE tenant_id=$1 AND parent_run_id=$2 AND activation_digest=$3")
240            .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid()).bind(request.activation_digest().as_bytes())
241            .bind(&bytes).bind(Digest::sha256(&bytes).as_bytes()).bind(canonical(&head)?)
242            .bind(sequence(&event.head())?).bind(*event.event_id().as_uuid()).bind(to_database_time(at)?).bind(event.digest().as_bytes())
243            .execute(&mut *tx).await.map_err(|source| StoreError::database("child Join binding insert", source))?;
244        query("UPDATE stateknot.child_run_joins j SET ready_at=b.ready_at FROM stateknot.child_run_join_bindings b WHERE j.tenant_id=$1 AND j.parent_run_id=$2 AND j.activation_digest=$3 AND b.tenant_id=j.tenant_id AND b.parent_run_id=j.parent_run_id AND b.activation_digest=j.activation_digest")
245            .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid()).bind(request.activation_digest().as_bytes())
246            .execute(&mut *tx).await.map_err(|source| StoreError::database("child Join ready projection", source))?;
247        update_run_head(&mut tx, &event, None).await?;
248        query("UPDATE stateknot.runs SET scheduler_ready_at=GREATEST(clock_timestamp(),$3),scheduler_not_before=NULL WHERE tenant_id=$1 AND run_id=$2")
249            .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid()).bind(to_database_time(at)?)
250            .execute(&mut *tx).await.map_err(|source| StoreError::database("child Join scheduler wakeup", source))?;
251        let record = load(&mut tx, activation, true)
252            .await?
253            .ok_or(StoreError::ChildJoinRejected)?;
254        tx.commit()
255            .await
256            .map_err(|source| StoreError::database("child Join publication commit", source))?;
257        Ok(ChildJoinCommitOutcome::Committed(record))
258    }
259
260    /// Authenticated caller scope is required. Reads a consistent snapshot and
261    /// verifies canonical identity, physical start, membership, terminal evidence,
262    /// publication and optional result consumption. Returns no child outputs.
263    pub async fn load_child_join(
264        &self,
265        activation: &NodeActivation,
266    ) -> Result<Option<ChildJoinRecord>, StoreError> {
267        let mut tx = self.begin_repeatable_read("child Join read").await?;
268        let record = load(&mut tx, activation, false).await?;
269        tx.commit()
270            .await
271            .map_err(|source| StoreError::database("child Join read commit", source))?;
272        Ok(record)
273    }
274
275    /// At most 16 registered, unquarantined Active parent joins whose children
276    /// are all settled. Retain the last request as an in-process continuation;
277    /// after a full sweep or restart begin with `None`. Continue past item errors.
278    /// Completed cursor rows are retained; a cursor is not a permanent watermark.
279    pub async fn pending_child_joins_after(
280        &self,
281        tenant: &TenantId,
282        after: Option<&ChildRunJoinRequest>,
283    ) -> Result<Vec<ChildRunJoinRequest>, StoreError> {
284        let mut tx = self.begin_repeatable_read("child Join discovery").await?;
285        let mut cursor = None;
286        if let Some(after) = after {
287            if after.activation().tenant_id() != tenant {
288                return Err(StoreError::ChildJoinRejected);
289            }
290            cursor = query_as::<_, (DateTime<Utc>, Uuid, Vec<u8>)>("SELECT queued_at,parent_run_id,activation_digest FROM stateknot.child_run_joins WHERE tenant_id=$1 AND parent_run_id=$2 AND request_digest=$3")
291                .bind(tenant.as_str()).bind(*after.activation().run_id().as_uuid()).bind(after.digest().as_bytes())
292                .fetch_optional(&mut *tx).await.map_err(|source| StoreError::database("child Join cursor", source))?;
293            if cursor.is_none() {
294                return Err(StoreError::ChildJoinRejected);
295            }
296        }
297        let rows = query_scalar::<_, Vec<u8>>("SELECT j.request_bytes FROM stateknot.child_run_joins j JOIN stateknot.runs r ON r.tenant_id=j.tenant_id AND r.run_id=j.parent_run_id WHERE j.tenant_id=$1 AND j.ready_at IS NULL AND r.lifecycle_status='active' AND r.quarantined_at IS NULL AND ($2::timestamptz IS NULL OR (j.queued_at,j.parent_run_id,j.activation_digest)>($2,$3,$4)) AND NOT EXISTS (SELECT 1 FROM stateknot.child_run_ownership o WHERE o.tenant_id=j.tenant_id AND o.parent_run_id=j.parent_run_id AND o.activation_digest=j.activation_digest AND NOT o.settled) ORDER BY j.queued_at,j.parent_run_id,j.activation_digest LIMIT 16")
298            .bind(tenant.as_str()).bind(cursor.as_ref().map(|value| value.0)).bind(cursor.as_ref().map(|value| value.1)).bind(cursor.as_ref().map(|value| &value.2))
299            .fetch_all(&mut *tx).await.map_err(|source| StoreError::database("child Join discovery", source))?;
300        let requests = rows
301            .iter()
302            .map(|bytes| decode::<ChildRunJoinRequest>(bytes))
303            .collect::<Result<Vec<_>, _>>()?;
304        tx.commit()
305            .await
306            .map_err(|source| StoreError::database("child Join discovery commit", source))?;
307        Ok(requests)
308    }
309}
310
311fn validate_append(
312    request: &ChildRunJoinRequest,
313    append: &JournalAppend,
314    kind: &str,
315) -> Result<(), StoreError> {
316    if append.intent().tenant_id() != request.activation().tenant_id()
317        || append.intent().run_id() != request.activation().run_id()
318        || append.intent().payload().kind().as_str() != kind
319    {
320        return Err(StoreError::ChildJoinRejected);
321    }
322    Ok(())
323}
324async fn lock_parent(
325    tx: &mut Transaction<'_, Postgres>,
326    activation: &NodeActivation,
327) -> Result<(), StoreError> {
328    let ancestors = child_runs::ancestry(tx, activation.tenant_id(), activation.run_id()).await?;
329    child_runs::lock_tree(tx, activation.tenant_id(), ancestors[0]).await?;
330    fetch_locked_run_row(tx, activation.tenant_id(), activation.run_id()).await?;
331    Ok(())
332}
333fn canonical<T: Serialize>(value: &T) -> Result<Vec<u8>, StoreError> {
334    serde_json_canonicalizer::to_vec(value).map_err(|_| StoreError::encoding("child Join bytes"))
335}
336fn decode<T: serde::de::DeserializeOwned + Serialize>(bytes: &[u8]) -> Result<T, StoreError> {
337    if bytes.is_empty() || bytes.len() > ChildRunJoinRequest::MAX_BYTES {
338        return Err(StoreError::corrupt("child Join size"));
339    }
340    let value: T =
341        serde_json::from_slice(bytes).map_err(|_| StoreError::corrupt("child Join value"))?;
342    if canonical(&value)? != bytes {
343        return Err(StoreError::corrupt("child Join canonical bytes"));
344    }
345    Ok(value)
346}
347fn sequence(head: &JournalHead) -> Result<i64, StoreError> {
348    i64::try_from(head.sequence().get()).map_err(|_| StoreError::JournalSequenceExhausted)
349}
350fn projection(
351    domain: &str,
352    request: Digest,
353    evidence: Digest,
354    event: &JournalEvent,
355) -> Result<Digest, StoreError> {
356    Ok(Digest::sha256(canonical(&(
357        "stateknot.child-join.v1",
358        domain,
359        request,
360        evidence,
361        event.intent_digest(),
362    ))?))
363}
364
365/// Verifies the COMPLETE admitted membership, not just the supplied subset.
366/// Child rows are read one at a time; outputs are not retained in the result.
367async fn verify_members(
368    tx: &mut Transaction<'_, Postgres>,
369    request: &ChildRunJoinRequest,
370    lock: bool,
371) -> Result<Option<Vec<stateknot_core::ChildRunBudgetSettlement>>, StoreError> {
372    Box::pin(verify_members_inner(tx, request, lock)).await
373}
374
375async fn verify_members_inner(
376    tx: &mut Transaction<'_, Postgres>,
377    request: &ChildRunJoinRequest,
378    lock: bool,
379) -> Result<Option<Vec<stateknot_core::ChildRunBudgetSettlement>>, StoreError> {
380    let a = request.activation();
381    let keys = query_scalar::<_, Vec<u8>>("SELECT key_bytes FROM stateknot.child_run_ownership WHERE tenant_id=$1 AND parent_run_id=$2 AND activation_digest=$3 ORDER BY child_slot COLLATE \"C\" LIMIT 65")
382        .bind(a.tenant_id().as_str()).bind(*a.run_id().as_uuid()).bind(request.activation_digest().as_bytes())
383        .fetch_all(&mut **tx).await.map_err(|source| StoreError::database("child Join membership", source))?;
384    if keys.len() != request.keys().len() {
385        return Err(StoreError::ChildJoinRejected);
386    }
387    let mut terminals = Vec::new();
388    for (bytes, key) in keys.iter().zip(request.keys()) {
389        if *bytes != canonical(key)? {
390            return Err(StoreError::ChildJoinRejected);
391        }
392        let child = Box::pin(child_runs::load_record_inner(tx, key, lock))
393            .await?
394            .ok_or(StoreError::ChildRunNotFound)?;
395        if lock && child.child().run().is_quarantined() {
396            return Err(StoreError::RunQuarantined);
397        }
398        if let Some(terminal) = child.settlement() {
399            terminals.push(terminal.clone());
400        }
401    }
402    Ok((terminals.len() == keys.len()).then_some(terminals))
403}
404
405async fn load(
406    tx: &mut Transaction<'_, Postgres>,
407    activation: &NodeActivation,
408    lock_children: bool,
409) -> Result<Option<ChildJoinRecord>, StoreError> {
410    Box::pin(load_inner(tx, activation, lock_children)).await
411}
412
413#[allow(clippy::too_many_lines)]
414async fn load_inner(
415    tx: &mut Transaction<'_, Postgres>,
416    activation: &NodeActivation,
417    lock_children: bool,
418) -> Result<Option<ChildJoinRecord>, StoreError> {
419    let row = query("SELECT * FROM stateknot.child_run_joins WHERE tenant_id=$1 AND parent_run_id=$2 AND base_checkpoint_id=$3 AND graph_namespace=$4 AND node_id=$5")
420        .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid()).bind(*activation.base_checkpoint().checkpoint_id().as_uuid())
421        .bind(activation.graph_namespace().as_str()).bind(activation.node_id().as_str())
422        .fetch_optional(&mut **tx).await.map_err(|source| StoreError::database("child Join load", source))?;
423    let Some(row) = row else {
424        return Ok(None);
425    };
426    let err = |source| StoreError::database("child Join projection", source);
427    let bytes: Vec<u8> = row.try_get("request_bytes").map_err(err)?;
428    let request: ChildRunJoinRequest = decode(&bytes)?;
429    if request.activation() != activation {
430        return Err(StoreError::ChildJoinRejected);
431    }
432    if request.activation_digest()
433        != decode_digest(
434            &row.try_get::<Vec<u8>, _>("activation_digest")
435                .map_err(err)?,
436            "child Join activation",
437        )?
438        || request.digest()
439            != decode_digest(
440                &row.try_get::<Vec<u8>, _>("request_digest").map_err(err)?,
441                "child Join request",
442            )?
443        || Digest::sha256(&bytes)
444            != decode_digest(
445                &row.try_get::<Vec<u8>, _>("request_checksum").map_err(err)?,
446                "child Join checksum",
447            )?
448    {
449        return Err(StoreError::corrupt("child Join identity"));
450    }
451    let id = AttemptId::from_uuid(row.try_get("node_attempt_id").map_err(err)?)
452        .map_err(|_| StoreError::corrupt("child Join node"))?;
453    let node = load_node_attempt_record(tx, activation.tenant_id(), &activation.run_id(), id)
454        .await?
455        .ok_or_else(|| StoreError::corrupt("child Join node"))?;
456    verify_node_attempt_start(tx, node.start()).await?;
457    let registration_head =
458        child_runs::row_head(&row, activation.tenant_id(), activation.run_id())?;
459    let (registration, registration_projection) = anchored_event(tx, &registration_head).await?;
460    if node.start().activation() != activation
461        || registration.source().worker_fence() != Some(node.start().fence())
462        || registration.sequence() <= node.start().journal_head().sequence()
463        || registration.recorded_at() < node.start().journal_head().recorded_at()
464        || registration.payload().kind().as_str() != "child-join-registered"
465        || registration_projection
466            != Some(projection(
467                "registration",
468                request.digest(),
469                node.start().digest(),
470                &registration,
471            )?)
472    {
473        return Err(StoreError::corrupt("child Join registration"));
474    }
475    let terminals =
476        verify_members(tx, &request, lock_children)
477            .await
478            .map_err(|error| match error {
479                StoreError::ChildJoinRejected | StoreError::ChildRunNotFound => {
480                    StoreError::corrupt("child Join membership")
481                }
482                other => other,
483            })?;
484    let publication = query("SELECT * FROM stateknot.child_run_join_bindings WHERE tenant_id=$1 AND parent_run_id=$2 AND activation_digest=$3")
485        .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid()).bind(request.activation_digest().as_bytes())
486        .fetch_optional(&mut **tx).await.map_err(|source| StoreError::database("child Join binding load", source))?;
487    let mut record = ChildJoinRecord {
488        request,
489        registration,
490        binding: None,
491        head: None,
492        consumed: None,
493    };
494    let ready_at: Option<DateTime<Utc>> = row.try_get("ready_at").map_err(err)?;
495    if let Some(publication) = publication {
496        let bytes: Vec<u8> = publication.try_get("binding_bytes").map_err(err)?;
497        let binding: ChildRunJoinBinding = decode(&bytes)?;
498        let expected = ChildRunJoinBinding::new(
499            record.request.clone(),
500            terminals.ok_or_else(|| StoreError::corrupt("child Join terminals missing"))?,
501        )
502        .map_err(|_| StoreError::corrupt("child Join terminals"))?;
503        let head = child_runs::row_head(&publication, activation.tenant_id(), activation.run_id())?;
504        let (event, digest) = anchored_event(tx, &head).await?;
505        let join_head = binding
506            .head(head.clone())
507            .map_err(|_| StoreError::corrupt("child Join head"))?;
508        if binding != expected
509            || Digest::sha256(&bytes)
510                != decode_digest(
511                    &publication
512                        .try_get::<Vec<u8>, _>("binding_checksum")
513                        .map_err(err)?,
514                    "child Join binding checksum",
515                )?
516            || publication
517                .try_get::<Vec<u8>, _>("head_bytes")
518                .map_err(err)?
519                != canonical(&join_head)?
520            || ready_at != Some(publication.try_get("ready_at").map_err(err)?)
521            || event.source().worker_fence().is_some()
522            || event.payload().kind().as_str() != "child-join-published"
523            || event.sequence() <= record.registration.sequence()
524            || event.recorded_at() < record.registration.recorded_at()
525            || digest
526                != Some(projection(
527                    "publication",
528                    record.request.digest(),
529                    binding.digest(),
530                    &event,
531                )?)
532        {
533            return Err(StoreError::corrupt("child Join publication"));
534        }
535        record.binding = Some(binding);
536        record.head = Some(join_head);
537    } else if ready_at.is_some() {
538        return Err(StoreError::corrupt("child Join ready projection"));
539    }
540    let consumption = query_as::<_, (i64,DateTime<Utc>)>("SELECT journal_sequence,consumed_at FROM stateknot.child_run_join_consumptions WHERE tenant_id=$1 AND parent_run_id=$2 AND activation_digest=$3")
541        .bind(activation.tenant_id().as_str()).bind(*activation.run_id().as_uuid()).bind(record.request.activation_digest().as_bytes())
542        .fetch_optional(&mut **tx).await.map_err(|source| StoreError::database("child Join consumption load", source))?;
543    if let Some((seq, at)) = consumption {
544        let result_row = load_pending_node_result_row(tx, activation)
545            .await?
546            .ok_or_else(|| StoreError::corrupt("child Join consumed result"))?;
547        let result = decode_pending_node_result(&result_row)?;
548        if record.head.is_none()
549            || result.intent().child_join() != record.head.as_ref()
550            || sequence(result.journal_head())? != seq
551            || row
552                .try_get::<Option<DateTime<Utc>>, _>("consumed_at")
553                .map_err(err)?
554                != Some(at)
555        {
556            return Err(StoreError::corrupt("child Join consumed result"));
557        }
558        // Authenticate start and completion without recursing result -> Join.
559        let attempt_id = AttemptId::from_uuid(
560            result_row
561                .node_attempt_id
562                .ok_or_else(|| StoreError::corrupt("child Join result physical start"))?,
563        )
564        .map_err(|_| StoreError::corrupt("child Join result physical start"))?;
565        let attempt =
566            load_node_attempt_record(tx, activation.tenant_id(), &activation.run_id(), attempt_id)
567                .await?
568                .ok_or_else(|| StoreError::corrupt("child Join result physical start"))?;
569        verify_node_attempt_start(tx, attempt.start()).await?;
570        let completion = attempt
571            .completion()
572            .ok_or_else(|| StoreError::corrupt("child Join result completion"))?;
573        if !matches!(completion.outcome(), NodeAttemptOutcome::Succeeded { result: completed } if **completed == result.head())
574        {
575            return Err(StoreError::corrupt("child Join result completion"));
576        }
577        verify_node_attempt_anchor(
578            tx,
579            result.journal_head(),
580            result.fence(),
581            completion.digest(),
582            "child Join result completion anchor",
583        )
584        .await?;
585        record.consumed = Some(result.journal_head().clone());
586    } else if row
587        .try_get::<Option<DateTime<Utc>>, _>("consumed_at")
588        .map_err(err)?
589        .is_some()
590    {
591        return Err(StoreError::corrupt("child Join consumption projection"));
592    }
593    Ok(Some(record))
594}
595
596async fn anchored_event(
597    tx: &mut Transaction<'_, Postgres>,
598    head: &JournalHead,
599) -> Result<(JournalEvent, Option<Digest>), StoreError> {
600    let (event, projection) =
601        child_runs::anchored_event(tx, head.tenant_id(), head.run_id(), sequence(head)?).await?;
602    if event.head() != *head {
603        return Err(StoreError::corrupt("child Join journal anchor"));
604    }
605    Ok((event, projection))
606}
607
608pub(super) async fn verify_result(
609    tx: &mut Transaction<'_, Postgres>,
610    result: &PendingNodeResult,
611    committed: bool,
612) -> Result<(), StoreError> {
613    let a = result.intent().activation();
614    // Fresh writes hold the parent row, not the tree. Refuse unpublished joins
615    // without reading mutable child terminals under READ COMMITTED.
616    let ready = query_scalar::<_, bool>("SELECT ready_at IS NOT NULL FROM stateknot.child_run_joins WHERE tenant_id=$1 AND parent_run_id=$2 AND base_checkpoint_id=$3 AND graph_namespace=$4 AND node_id=$5")
617        .bind(a.tenant_id().as_str()).bind(*a.run_id().as_uuid()).bind(*a.base_checkpoint().checkpoint_id().as_uuid())
618        .bind(a.graph_namespace().as_str()).bind(a.node_id().as_str()).fetch_optional(&mut **tx).await.map_err(|source| StoreError::database("child Join result readiness", source))?;
619    if ready.is_none() && result.intent().child_join().is_none() {
620        return Ok(());
621    }
622    if ready != Some(true) {
623        return Err(if committed {
624            StoreError::corrupt("missing or unpublished result child Join")
625        } else {
626            StoreError::ChildJoinRejected
627        });
628    }
629    // Publication sealed membership and proved every child terminal. Fresh
630    // consumption already holds the parent row; lock these terminal children
631    // in canonical slot order so operator quarantine cannot race consumption.
632    // Never acquire the tree lock after the parent. Terminal children cannot
633    // spawn or settle outstanding descendants; their audit/quarantine writers
634    // do not lock ancestors. Historical replay remains a nonlocking proof read.
635    let record = load(tx, a, !committed).await?;
636    match record {
637        None if result.intent().child_join().is_none() => Ok(()),
638        Some(record)
639            if record.head().is_some()
640                && result.intent().child_join() == record.head()
641                && if committed {
642                    record.consumed() == Some(result.journal_head())
643                } else {
644                    record.consumed().is_none()
645                } =>
646        {
647            Ok(())
648        }
649        _ if committed => Err(StoreError::corrupt("pending result child Join")),
650        _ => Err(StoreError::ChildJoinRejected),
651    }
652}
653
654pub(super) async fn verify_schema(pool: &PgPool) -> Result<(), StoreError> {
655    let installed = query_scalar::<_, String>(CATALOG_QUERY)
656        .fetch_one(pool)
657        .await
658        .map_err(|source| StoreError::database("child Join catalog", source))?;
659    let expected: serde_json::Value = serde_json::from_str(include_str!("child_join_catalog.json"))
660        .map_err(|_| StoreError::IncompleteSchema)?;
661    if serde_json::from_str::<serde_json::Value>(&installed)
662        .map_err(|_| StoreError::IncompleteSchema)?
663        != expected
664    {
665        return Err(StoreError::IncompleteSchema);
666    }
667    for function in include_str!("../migrations/0022_child_run_joins.sql")
668        .split("CREATE FUNCTION stateknot.")
669        .skip(1)
670    {
671        let (name, _) = function
672            .split_once("() RETURNS trigger")
673            .ok_or(StoreError::IncompleteSchema)?;
674        let body = function
675            .split("$$")
676            .nth(1)
677            .ok_or(StoreError::IncompleteSchema)?;
678        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'")
679            .bind(format!("stateknot.{name}()")).fetch_optional(pool).await.map_err(|source| StoreError::database("child Join guard",source))?;
680        if installed.as_deref() != Some(body) {
681            return Err(StoreError::IncompleteSchema);
682        }
683    }
684    Ok(())
685}
686
687// Full additive catalog, including nullability, exact checks/FKs/keys, live
688// indexes and enabled trigger definitions. Function bodies are checked above.
689const CATALOG_QUERY: &str = r"
690WITH relations AS (SELECT oid,relname FROM pg_class WHERE relnamespace='stateknot'::regnamespace AND relname IN ('child_run_joins','child_run_join_bindings','child_run_join_consumptions'))
691SELECT jsonb_build_object(
692 'columns',(SELECT jsonb_agg(jsonb_build_array(r.relname,a.attname,format_type(a.atttypid,a.atttypmod),a.attnotnull) ORDER BY r.relname,a.attnum) FROM relations r JOIN pg_attribute a ON a.attrelid=r.oid WHERE a.attnum>0 AND NOT a.attisdropped),
693 'constraints',(SELECT jsonb_agg(jsonb_build_array(r.relname,c.conname,pg_get_constraintdef(c.oid),c.convalidated,c.condeferrable) ORDER BY r.relname,c.conname) FROM relations r JOIN pg_constraint c ON c.conrelid=r.oid),
694 'indexes',(SELECT jsonb_agg(jsonb_build_array(r.relname,pg_get_indexdef(i.indexrelid),i.indisvalid,i.indisready,i.indislive) ORDER BY r.relname,pg_get_indexdef(i.indexrelid)) FROM relations r JOIN pg_index i ON i.indrelid=r.oid),
695 'triggers',(SELECT jsonb_agg(jsonb_build_array(t.tgname,pg_get_triggerdef(t.oid),t.tgenabled) ORDER BY t.tgname) FROM pg_trigger t WHERE NOT t.tgisinternal AND (t.tgrelid IN (SELECT oid FROM relations) OR (t.tgrelid='stateknot.runs'::regclass AND t.tgname='runs_child_join_guard') OR (t.tgrelid='stateknot.child_run_ownership'::regclass AND t.tgname='child_join_spawn_guard') OR (t.tgrelid='stateknot.pending_node_results'::regclass AND t.tgname='pending_results_child_join_consume')))
696)::text
697";