Skip to main content

stateknot_runtime/
invocation_schema.rs

1// Copyright 2026 StateKnot contributors
2// SPDX-License-Identifier: Apache-2.0
3
4//! Versioned public-safe journal schema for model/tool invocation execution.
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 invocation execution event-data schema.
13pub const STANDARD_INVOCATION_EXECUTION_EVENT_SCHEMA_ID: &str =
14    "https://stknot.com/schemas/runtime/invocation-execution-event/1.0.0";
15
16const DOCUMENT: &str = include_str!("../schemas/invocation-execution-event-1.0.0.json");
17
18/// Returns the immutable reference and embedded JSON Schema document.
19///
20/// # Errors
21///
22/// Returns an internal release-artifact failure only if embedded bytes are
23/// malformed, non-canonicalizable, or use an invalid stable identifier.
24pub fn standard_invocation_execution_event_schema()
25-> Result<(SchemaReference, Value), StandardInvocationExecutionSchemaError> {
26    let document = serde_json::from_str::<Value>(DOCUMENT)
27        .map_err(|_| StandardInvocationExecutionSchemaError::EmbeddedDocument)?;
28    let canonical = serde_json_canonicalizer::to_vec(&document)
29        .map_err(|_| StandardInvocationExecutionSchemaError::Canonicalization)?;
30    let id = STANDARD_INVOCATION_EXECUTION_EVENT_SCHEMA_ID
31        .parse::<SchemaId>()
32        .map_err(StandardInvocationExecutionSchemaError::identifier)?;
33    Ok((
34        SchemaReference::new(id, Version::new(1, 0, 0), Digest::sha256(canonical)),
35        document,
36    ))
37}
38
39/// Registers the standard invocation event schema in a startup registry.
40///
41/// # Errors
42///
43/// Returns an embedded-definition or frozen-registry validation failure.
44pub fn register_standard_invocation_execution_event_schema(
45    builder: &mut JsonSchemaRegistryBuilder,
46) -> Result<SchemaReference, StandardInvocationExecutionSchemaRegistrationError> {
47    let (reference, document) = standard_invocation_execution_event_schema()?;
48    builder.register(reference.clone(), document)?;
49    Ok(reference)
50}
51
52/// Internal embedded invocation-schema release-artifact failure.
53#[derive(Clone, Debug, Eq, Error, PartialEq)]
54#[non_exhaustive]
55pub enum StandardInvocationExecutionSchemaError {
56    /// Embedded schema is invalid JSON.
57    #[error("embedded invocation execution event schema is invalid JSON")]
58    EmbeddedDocument,
59    /// Embedded schema cannot be canonicalized.
60    #[error("embedded invocation execution event schema cannot be canonicalized")]
61    Canonicalization,
62    /// Stable HTTPS schema identifier is invalid.
63    #[error("embedded invocation execution event schema identifier is invalid: {source}")]
64    Identifier {
65        /// Exact identifier validation error.
66        #[source]
67        source: SchemaIdError,
68    },
69}
70
71impl StandardInvocationExecutionSchemaError {
72    const fn identifier(source: SchemaIdError) -> Self {
73        Self::Identifier { source }
74    }
75}
76
77/// Startup failure while adding the standard invocation schema.
78#[derive(Clone, Debug, Eq, Error, PartialEq)]
79#[non_exhaustive]
80pub enum StandardInvocationExecutionSchemaRegistrationError {
81    /// Embedded release artifact was malformed.
82    #[error(transparent)]
83    Definition(#[from] StandardInvocationExecutionSchemaError),
84    /// Target registry rejected the immutable resource.
85    #[error(transparent)]
86    Registry(#[from] JsonSchemaRegistryError),
87}
88
89#[cfg(test)]
90mod tests {
91    use serde_json::json;
92    use stateknot_core::BoundedJson;
93
94    use super::*;
95    use crate::JsonSchemaRegistryLimits;
96
97    #[test]
98    fn standard_schema_is_digest_pinned_and_closes_model_tool_shapes() {
99        let (reference, document) = standard_invocation_execution_event_schema().unwrap();
100        let mut builder = JsonSchemaRegistryBuilder::new(JsonSchemaRegistryLimits::default());
101        builder.register(reference.clone(), document).unwrap();
102        let registry = builder.build().unwrap();
103        let model = BoundedJson::try_from_value(json!({
104            "operation": "model_attempt_started",
105            "binding_kind": "model",
106            "invocation_id": "01912345-6789-7abc-8def-0123456789ab",
107            "attempt_id": "01912345-6789-7abc-8def-0123456789ac",
108            "intent_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
109        }))
110        .unwrap();
111        registry.validate_bounded(&reference, &model).unwrap();
112
113        let preparation = BoundedJson::try_from_value(json!({
114            "operation": "tool_invocation_prepared",
115            "binding_kind": "tool",
116            "invocation_id": "01912345-6789-7abc-8def-0123456789ad",
117            "attempt_id": "01912345-6789-7abc-8def-0123456789ae",
118            "intent_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
119        }))
120        .unwrap();
121        registry.validate_bounded(&reference, &preparation).unwrap();
122
123        let crossed = BoundedJson::try_from_value(json!({
124            "operation": "tool_result_committed",
125            "binding_kind": "model",
126            "invocation_id": "01912345-6789-7abc-8def-0123456789ab",
127            "attempt_id": "01912345-6789-7abc-8def-0123456789ac",
128            "intent_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
129        }))
130        .unwrap();
131        assert!(registry.validate_bounded(&reference, &crossed).is_err());
132    }
133}