Skip to main content

stateknot_runtime/
lifecycle_schema.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Versioned public-safe journal schema used by graph lifecycle commits.
5
6use serde_json::Value;
7use stateknot_core::{Digest, SchemaId, SchemaIdError, SchemaReference, Version};
8use thiserror::Error;
9
10use crate::{JsonSchemaRegistryBuilder, JsonSchemaRegistryError};
11
12/// Stable identity of the v1 graph lifecycle event-data schema.
13pub const STANDARD_GRAPH_LIFECYCLE_EVENT_SCHEMA_ID: &str =
14    "https://stknot.com/schemas/runtime/graph-lifecycle-event/1.0.0";
15
16const DOCUMENT: &str = include_str!("../schemas/graph-lifecycle-event-1.0.0.json");
17
18/// Returns the immutable reference and owned JSON Schema document shipped with
19/// this runtime release.
20///
21/// # Errors
22///
23/// Returns [`StandardGraphLifecycleSchemaError`] only when the embedded
24/// release artifact is internally malformed.
25pub fn standard_graph_lifecycle_event_schema()
26-> Result<(SchemaReference, Value), StandardGraphLifecycleSchemaError> {
27    let document = serde_json::from_str::<Value>(DOCUMENT)
28        .map_err(|_| StandardGraphLifecycleSchemaError::EmbeddedDocument)?;
29    let canonical = serde_json_canonicalizer::to_vec(&document)
30        .map_err(|_| StandardGraphLifecycleSchemaError::Canonicalization)?;
31    let id = STANDARD_GRAPH_LIFECYCLE_EVENT_SCHEMA_ID
32        .parse::<SchemaId>()
33        .map_err(StandardGraphLifecycleSchemaError::identifier)?;
34    let reference = SchemaReference::new(id, Version::new(1, 0, 0), Digest::sha256(canonical));
35    Ok((reference, document))
36}
37
38/// Registers the standard graph lifecycle event schema in a startup registry.
39///
40/// # Errors
41///
42/// Returns an embedded-definition error or the registry's duplicate, resource,
43/// dialect, digest, and reference-resolution failures.
44pub fn register_standard_graph_lifecycle_event_schema(
45    builder: &mut JsonSchemaRegistryBuilder,
46) -> Result<SchemaReference, StandardGraphLifecycleSchemaRegistrationError> {
47    let (reference, document) = standard_graph_lifecycle_event_schema()?;
48    builder.register(reference.clone(), document)?;
49    Ok(reference)
50}
51
52/// Internal release-artifact failure for the embedded standard schema.
53#[derive(Clone, Debug, Eq, Error, PartialEq)]
54#[non_exhaustive]
55pub enum StandardGraphLifecycleSchemaError {
56    /// The embedded JSON document cannot be parsed.
57    #[error("embedded graph lifecycle event schema is invalid JSON")]
58    EmbeddedDocument,
59    /// The embedded document cannot be represented as RFC 8785 bytes.
60    #[error("embedded graph lifecycle event schema cannot be canonicalized")]
61    Canonicalization,
62    /// The embedded stable HTTPS identifier is invalid.
63    #[error("embedded graph lifecycle event schema identifier is invalid: {source}")]
64    Identifier {
65        /// Exact identifier validation error.
66        #[source]
67        source: SchemaIdError,
68    },
69}
70
71impl StandardGraphLifecycleSchemaError {
72    const fn identifier(source: SchemaIdError) -> Self {
73        Self::Identifier { source }
74    }
75}
76
77/// Startup failure while adding the standard lifecycle schema to a registry.
78#[derive(Clone, Debug, Eq, Error, PartialEq)]
79#[non_exhaustive]
80pub enum StandardGraphLifecycleSchemaRegistrationError {
81    /// The embedded release artifact was malformed.
82    #[error(transparent)]
83    Definition(#[from] StandardGraphLifecycleSchemaError),
84    /// The target registry rejected the immutable resource.
85    #[error(transparent)]
86    Registry(#[from] JsonSchemaRegistryError),
87}
88
89#[cfg(test)]
90mod tests {
91    use super::*;
92    use crate::JsonSchemaRegistryLimits;
93    use serde_json::json;
94    use stateknot_core::BoundedJson;
95
96    #[test]
97    fn standard_schema_is_digest_pinned_and_registry_valid() {
98        let (reference, document) = standard_graph_lifecycle_event_schema().unwrap();
99        assert_eq!(
100            reference.id().as_str(),
101            STANDARD_GRAPH_LIFECYCLE_EVENT_SCHEMA_ID
102        );
103        assert_eq!(reference.version(), Version::new(1, 0, 0));
104
105        let mut builder = JsonSchemaRegistryBuilder::new(JsonSchemaRegistryLimits::default());
106        builder.register(reference.clone(), document).unwrap();
107        let registry = builder.build().unwrap();
108        assert!(registry.contains(&reference));
109    }
110
111    #[test]
112    fn standard_schema_accepts_only_the_three_closed_lifecycle_shapes() {
113        let (reference, document) = standard_graph_lifecycle_event_schema().unwrap();
114        let mut builder = JsonSchemaRegistryBuilder::new(JsonSchemaRegistryLimits::default());
115        builder.register(reference.clone(), document).unwrap();
116        let registry = builder.build().unwrap();
117        let base = json!({
118            "operation": "graph_barrier_waiting",
119            "graph_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
120            "checkpoint_id": "01912345-6789-7abc-8def-0123456789ab",
121            "superstep": "1",
122            "successor_checkpoint_id": "01912345-6789-7abc-8def-0123456789ac",
123            "successor_superstep": "2",
124            "disposition": "wait",
125            "wait_count": 1
126        });
127        registry
128            .validate_bounded(
129                &reference,
130                &BoundedJson::try_from_value(base.clone()).unwrap(),
131            )
132            .unwrap();
133
134        let success = json!({
135            "operation": "graph_barrier_succeeded",
136            "graph_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
137            "checkpoint_id": "01912345-6789-7abc-8def-0123456789ab",
138            "superstep": "1",
139            "successor_checkpoint_id": "01912345-6789-7abc-8def-0123456789ac",
140            "successor_superstep": "2",
141            "disposition": "succeeded",
142            "output_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
143        });
144        registry
145            .validate_bounded(&reference, &BoundedJson::try_from_value(success).unwrap())
146            .unwrap();
147
148        let failure = json!({
149            "operation": "graph_run_failed",
150            "graph_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
151            "checkpoint_id": "01912345-6789-7abc-8def-0123456789ab",
152            "superstep": "1",
153            "disposition": "failed",
154            "failure_id": "01912345-6789-7abc-8def-0123456789ad",
155            "in_flight": 0,
156            "failed": 1,
157            "exhausted": 0,
158            "unsupported": 0
159        });
160        registry
161            .validate_bounded(&reference, &BoundedJson::try_from_value(failure).unwrap())
162            .unwrap();
163
164        let mut crossed = base;
165        crossed["output_digest"] =
166            json!("bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb");
167        assert!(
168            registry
169                .validate_bounded(&reference, &BoundedJson::try_from_value(crossed).unwrap())
170                .is_err()
171        );
172    }
173}