1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
// Copyright 2026 StateKnot contributors
// SPDX-License-Identifier: Apache-2.0
//! Pure child ownership identities, not authority or committed admission proof.
use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize, de};
use thiserror::Error;
use crate::{Digest, NodeActivation, NodeId, NodeIdError, RunId, TenantId};
const KEY_DOMAIN: &[u8] = b"stateknot-child-run-key-v1\0";
/// A stable, case-sensitive child slot declared by an executable definition.
///
/// Reuses the bounded [`NodeId`] grammar, but is a distinct Rust type. A slot
/// is not a child Run ID, physical attempt, arbitrary model string, or path.
/// Construction validates syntax only; declaration membership is a separate
/// admission check.
#[derive(
Clone, Debug, Deserialize, Eq, Hash, JsonSchema, Ord, PartialEq, PartialOrd, Serialize,
)]
#[serde(transparent)]
pub struct ChildRunSlot(NodeId);
impl ChildRunSlot {
/// Maximum encoded slot length in bytes.
pub const MAX_LEN: usize = NodeId::MAX_LEN;
/// Constructs a bounded slot using the same validation on every wire path.
pub fn new(value: impl Into<String>) -> Result<Self, NodeIdError> {
NodeId::new(value).map(Self)
}
/// Returns the exact declared slot text.
#[must_use]
pub fn as_str(&self) -> &str {
self.0.as_str()
}
}
/// Integrity-bound logical ownership key for one isolated child Run.
///
/// The key binds the complete parent activation and slot. It intentionally
/// excludes physical attempts, fences, clocks, and candidate child Run IDs.
/// Its digest can index an ownership record but cannot authorize admission:
/// the store must prove the activation's committed readiness, current worker
/// authority, declaration membership, and atomic budget reservation.
///
/// Deserialization recomputes the digest. A matching checksum detects drift;
/// it is not a signature and does not authenticate caller-supplied data.
#[derive(Clone, Debug, Eq, JsonSchema, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct ChildRunKey {
parent: NodeActivation,
slot: ChildRunSlot,
digest: Digest,
}
impl ChildRunKey {
/// Computes a deterministic logical key from validated domain values.
pub fn new(parent: NodeActivation, slot: ChildRunSlot) -> Result<Self, ChildRunKeyError> {
#[derive(Serialize)]
struct Preimage<'a> {
tenant_id: &'a TenantId,
parent_run_id: RunId,
parent_activation_digest: Digest,
child_slot: &'a ChildRunSlot,
}
let activation_digest = crate::node_attempt::compute_activation_digest(&parent)
.map_err(|_| ChildRunKeyError::CanonicalSerialization)?;
let canonical = serde_json_canonicalizer::to_vec(&Preimage {
tenant_id: parent.tenant_id(),
parent_run_id: parent.run_id(),
parent_activation_digest: activation_digest,
child_slot: &slot,
})
.map_err(|_| ChildRunKeyError::CanonicalSerialization)?;
let mut preimage = Vec::with_capacity(KEY_DOMAIN.len() + canonical.len());
preimage.extend_from_slice(KEY_DOMAIN);
preimage.extend_from_slice(&canonical);
Ok(Self {
parent,
slot,
digest: Digest::sha256(preimage),
})
}
/// Returns the exact parent logical activation, without physical authority.
#[must_use]
pub const fn parent(&self) -> &NodeActivation {
&self.parent
}
/// Returns the declared child slot.
#[must_use]
pub const fn slot(&self) -> &ChildRunSlot {
&self.slot
}
/// Returns the tenant inherited from the parent activation.
#[must_use]
pub const fn tenant_id(&self) -> &TenantId {
self.parent.tenant_id()
}
/// Returns the parent Run ID, never a generated child ID.
#[must_use]
pub const fn parent_run_id(&self) -> RunId {
self.parent.run_id()
}
/// Returns the domain-separated SHA-256 ownership fingerprint.
#[must_use]
pub const fn digest(&self) -> Digest {
self.digest
}
}
impl<'de> Deserialize<'de> for ChildRunKey {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct Wire {
parent: NodeActivation,
slot: ChildRunSlot,
digest: Digest,
}
let wire = Wire::deserialize(deserializer)?;
let key = Self::new(wire.parent, wire.slot).map_err(de::Error::custom)?;
if key.digest != wire.digest {
return Err(de::Error::custom(ChildRunKeyError::DigestMismatch));
}
Ok(key)
}
}
/// Failure constructing or restoring a logical child ownership key.
#[derive(Clone, Debug, Eq, Error, PartialEq)]
#[non_exhaustive]
pub enum ChildRunKeyError {
/// The closed integrity preimage could not be encoded canonically.
#[error("child run key canonical serialization failed")]
CanonicalSerialization,
/// Stored identity fields no longer match their integrity fingerprint.
#[error("child run key digest mismatch")]
DigestMismatch,
}
#[cfg(test)]
#[path = "child_run_tests.rs"]
mod tests;