Skip to main content

scientific_workflow/state/
schema.rs

1//! Immutable state schemas loaded from JSON templates.
2//!
3//! A scientific program establishes its SystemState layout before constructing
4//! states. This module loads that layout, validates field declarations, assigns
5//! compact deterministic field indices, and shares the resulting metadata
6//! among all derived states.
7//!
8//! # Template format
9//!
10//! The accepted JSON document has one ordered `fields` array:
11//!
12//! ```json
13//! {
14//!   "fields": [
15//!     {
16//!       "name": "population",
17//!       "description": "Population count for each simulated region"
18//!     },
19//!     {"name": "space"}
20//!   ]
21//! }
22//! ```
23//!
24//! Array order is significant. It assigns each field a zero-based index used
25//! by the compact payload-slot vector in `SystemState`. Names and present
26//! descriptions are trimmed. Missing, null, empty, and whitespace-only
27//! descriptions all normalize to no description. Unknown JSON properties are
28//! rejected so misspelled template configuration cannot be silently ignored.
29//! Payload types and storage encodings deliberately do not belong here.
30//!
31//! # Sharing and performance
32//!
33//! `SystemStateSchema` is a small cloneable handle around an immutable, reference-
34//! counted layout. Cloning it never duplicates field names or lookup tables.
35//! Field lookup uses a hash map, while iteration preserves JSON declaration
36//! order through the field slice.
37//!
38//! # Construction boundary
39//!
40//! Public callers load the first specification from a JSON template path using
41//! [`SystemStateSchema::load_json_template`]. Crate-private peer functions apply
42//! the same semantic validation to Config's already-parsed JSON values and to
43//! Persistence's already-decoded ordered field metadata. Those peers never
44//! reread a project document or serialize metadata merely to parse it again.
45
46use std::collections::HashMap;
47use std::fs;
48use std::path::{Path, PathBuf};
49use std::sync::Arc;
50
51use serde::{Deserialize, Serialize};
52
53use super::error::StateError;
54use super::state::SystemState;
55use super::time::StateTime;
56
57/// One validated field in a state template.
58///
59/// A field description is immutable after template loading. Its position is
60/// the corresponding payload slot in every state sharing the schema.
61#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
62pub struct StateFieldSchema {
63    #[serde(skip)]
64    index: usize,
65    name: Box<str>,
66    #[serde(skip_serializing_if = "Option::is_none")]
67    description: Option<Box<str>>,
68}
69
70impl StateFieldSchema {
71    fn new(index: usize, name: &str, description: Option<&str>) -> Self {
72        Self {
73            index,
74            name: name.trim().into(),
75            description: description
76                .map(str::trim)
77                .filter(|description| !description.is_empty())
78                .map(Into::into),
79        }
80    }
81
82    /// Returns the zero-based payload-slot position assigned by template order.
83    pub fn position(&self) -> usize {
84        self.index
85    }
86
87    /// Returns the field name used by typed state accessors.
88    pub fn name(&self) -> &str {
89        &self.name
90    }
91
92    /// Returns the optional natural-language payload description.
93    pub fn description(&self) -> Option<&str> {
94        self.description.as_deref()
95    }
96
97    fn owned_name(&self) -> Box<str> {
98        self.name.clone()
99    }
100}
101
102/// A validated, shareable SystemState layout.
103///
104/// `SystemStateSchema` owns an [`Arc`] to immutable metadata, making `Clone` a cheap
105/// reference-count increment. Every state derived from a specification shares
106/// the exact field order and name lookup table.
107#[derive(Clone, Debug)]
108pub struct SystemStateSchema {
109    inner: Arc<StateLayout>,
110}
111
112/// One reusable static state-schema document supplied by an upstream crate.
113///
114/// An execution unit may return this descriptor from
115/// [`ExecutionUnit::standard_state_schema`](crate::task::ExecutionUnit::standard_state_schema)
116/// when its ordinary state layout is fixed by a linked dependency. Study
117/// validates and caches the borrowed document during preflight. The provider
118/// performs no filesystem IO and retains no project or runtime state.
119#[derive(Clone, Copy, Debug)]
120pub struct StateSchemaProvider {
121    id: &'static str,
122    document: &'static [u8],
123}
124
125impl StateSchemaProvider {
126    /// Declares one stable provider identity and its complete JSON template.
127    ///
128    /// Validation is intentionally deferred to Study or [`Self::resolve`] so
129    /// this constructor can remain `const` and providers can expose ordinary
130    /// static descriptors.
131    pub const fn new(id: &'static str, document: &'static [u8]) -> Self {
132        Self { id, document }
133    }
134
135    /// Returns the stable, versionable provider identity retained as provenance.
136    pub const fn id(self) -> &'static str {
137        self.id
138    }
139
140    /// Returns the borrowed static JSON schema document.
141    pub const fn document(self) -> &'static [u8] {
142        self.document
143    }
144
145    /// Validates this embedded document and returns its immutable state schema.
146    ///
147    /// This is the direct-integration counterpart to Study's automatic
148    /// provider resolution. It performs no filesystem IO. Each call creates a
149    /// new schema allocation; composed Workflow studies resolve and cache one
150    /// allocation per provider identity during preflight.
151    pub fn resolve(self) -> Result<SystemStateSchema, StateError> {
152        let source = PathBuf::from(format!("<state-schema-provider:{}>", self.id));
153        SystemStateSchema::parse(source, self.document)
154    }
155}
156
157impl SystemStateSchema {
158    /// Loads and validates a state specification from a JSON template.
159    ///
160    /// The file is read as bytes and parsed directly, avoiding an intermediate
161    /// UTF-8 `String` allocation. The returned specification retains the input
162    /// path for diagnostics and provenance but does not canonicalize it or keep
163    /// the file open.
164    ///
165    /// # Errors
166    ///
167    /// Returns:
168    ///
169    /// - [`StateError::TemplateRead`] when the file cannot be read;
170    /// - [`StateError::TemplateParse`] when JSON syntax or structure is invalid;
171    /// - [`StateError::EmptyFieldName`] for an empty normalized field name;
172    /// - [`StateError::DuplicateField`] for repeated normalized names.
173    pub fn load_json_template(path: &Path) -> Result<Self, StateError> {
174        let source = path.to_path_buf();
175        let bytes = fs::read(&source).map_err(|error| StateError::TemplateRead {
176            path: source.clone(),
177            source: error,
178        })?;
179
180        Self::parse(source, &bytes)
181    }
182
183    /// Parses the standalone public template loaded from disk.
184    ///
185    /// # Errors
186    ///
187    /// Returns [`StateError::TemplateParse`] for invalid JSON structure or
188    /// syntax and the same semantic template variants documented by
189    /// [`SystemStateSchema::load_json_template`]. The input bytes are borrowed
190    /// only for this call.
191    fn parse(source: PathBuf, bytes: &[u8]) -> Result<Self, StateError> {
192        let template: StateTemplate =
193            serde_json::from_slice(bytes).map_err(|error| StateError::TemplateParse {
194                path: source.clone(),
195                source: error,
196            })?;
197
198        Self::from_template(source, template)
199    }
200
201    /// Validates a centrally parsed JSON value without a second file read.
202    fn from_json_template_value(
203        source_path: &Path,
204        document: &serde_json::Value,
205    ) -> Result<Self, StateError> {
206        let template =
207            StateTemplate::deserialize(document).map_err(|source| StateError::TemplateParse {
208                path: source_path.to_path_buf(),
209                source,
210            })?;
211        Self::from_template(source_path.to_path_buf(), template)
212    }
213
214    /// Creates an empty SystemState that shares this specification.
215    ///
216    /// Every declared field exists in the returned state's layout, while every
217    /// payload slot starts empty. Cloning the specification is constant-time
218    /// and does not duplicate layout data.
219    pub fn create_empty_state(&self, time: StateTime) -> SystemState {
220        SystemState::new(self.clone(), time)
221    }
222
223    /// Resolves a declared field name to its payload-slot index.
224    ///
225    /// This is crate-private because compact indices are an implementation
226    /// detail. Public callers address fields by name or inspect [`StateFieldSchema`].
227    pub(crate) fn index_of(&self, name: &str) -> Result<usize, StateError> {
228        self.inner
229            .by_name
230            .get(name)
231            .copied()
232            .ok_or_else(|| StateError::UnknownField {
233                field: name.to_owned(),
234            })
235    }
236
237    /// Validates a parsed template and constructs its shared lookup layout.
238    fn from_template(source: PathBuf, template: StateTemplate) -> Result<Self, StateError> {
239        let mut fields = Vec::with_capacity(template.fields.len());
240        let mut by_name = HashMap::with_capacity(template.fields.len());
241
242        for (index, declaration) in template.fields.into_iter().enumerate() {
243            let name = declaration.name.trim();
244            if name.is_empty() {
245                return Err(StateError::EmptyFieldName { index });
246            }
247
248            if by_name.contains_key(name) {
249                return Err(StateError::DuplicateField {
250                    field: name.to_owned(),
251                });
252            }
253
254            let field = StateFieldSchema::new(index, name, declaration.description.as_deref());
255            by_name.insert(field.owned_name(), index);
256            fields.push(field);
257        }
258
259        Ok(Self {
260            inner: Arc::new(StateLayout {
261                source,
262                fields,
263                by_name,
264            }),
265        })
266    }
267}
268
269/// Validates one centrally parsed state-schema value without reading a file.
270pub(crate) fn schema_from_json_value(
271    source_path: &Path,
272    document: &serde_json::Value,
273) -> Result<SystemStateSchema, StateError> {
274    SystemStateSchema::from_json_template_value(source_path, document)
275}
276
277/// Reconstructs a schema directly from already-decoded ordered field metadata.
278pub(crate) fn schema_from_fields<'a>(
279    source_path: &Path,
280    fields: impl IntoIterator<Item = (&'a str, Option<&'a str>)>,
281) -> Result<SystemStateSchema, StateError> {
282    let template = StateTemplate {
283        fields: fields
284            .into_iter()
285            .map(|(name, description)| FieldDeclaration {
286                name: name.to_owned(),
287                description: description.map(str::to_owned),
288            })
289            .collect(),
290    };
291    SystemStateSchema::from_template(source_path.to_path_buf(), template)
292}
293
294impl SystemStateSchema {
295    /// Reports whether two schema handles share one immutable allocation.
296    ///
297    /// This is an identity comparison, not structural equality. Independently
298    /// loaded but textually identical schemas do not share an instance.
299    pub fn shares_schema_instance(&self, other: &SystemStateSchema) -> bool {
300        Arc::ptr_eq(&self.inner, &other.inner)
301    }
302
303    /// Returns the path from which this schema was loaded.
304    pub fn template_path(&self) -> &Path {
305        &self.inner.source
306    }
307
308    /// Returns field descriptions in deterministic template order.
309    pub fn field_schemas(&self) -> &[StateFieldSchema] {
310        &self.inner.fields
311    }
312
313    /// Looks up one field description by normalized name.
314    pub fn field_schema(&self, name: &str) -> Option<&StateFieldSchema> {
315        let index = self.inner.by_name.get(name)?;
316        self.inner.fields.get(*index)
317    }
318
319    /// Reports whether the schema declares `name`.
320    pub fn contains_field(&self, name: &str) -> bool {
321        self.inner.by_name.contains_key(name)
322    }
323
324    /// Returns the number of declared fields.
325    pub fn len(&self) -> usize {
326        self.inner.fields.len()
327    }
328
329    /// Reports whether the schema declares no fields.
330    pub fn is_empty(&self) -> bool {
331        self.inner.fields.is_empty()
332    }
333
334    /// Converts this schema to the strict, pretty-printed JSON template format.
335    pub fn to_json_template(&self) -> Result<String, serde_json::Error> {
336        serde_json::to_string_pretty(&StateTemplateRef {
337            fields: self.field_schemas(),
338        })
339    }
340}
341
342/// Immutable metadata shared by every clone of a [`SystemStateSchema`].
343#[derive(Debug)]
344struct StateLayout {
345    /// Original template path retained for provenance and diagnostics.
346    source: PathBuf,
347    /// Validated fields in deterministic template order.
348    fields: Vec<StateFieldSchema>,
349    /// Normalized field name to compact payload-slot index.
350    by_name: HashMap<Box<str>, usize>,
351}
352
353/// Serde-only representation of the top-level JSON template.
354#[derive(Debug, Deserialize)]
355#[serde(deny_unknown_fields)]
356struct StateTemplate {
357    /// Ordered field declarations.
358    fields: Vec<FieldDeclaration>,
359}
360
361/// Serde-only representation of one JSON field declaration.
362#[derive(Debug, Deserialize)]
363#[serde(deny_unknown_fields)]
364struct FieldDeclaration {
365    /// Human-facing dictionary key.
366    name: String,
367    /// Optional human-facing payload documentation.
368    #[serde(default)]
369    description: Option<String>,
370}
371
372/// Borrowed serialization view of a validated state specification.
373///
374/// Keeping this separate from [`StateTemplate`] prevents deserialization-only
375/// owned strings from being allocated when converting an existing
376/// specification back to JSON.
377#[derive(Serialize)]
378struct StateTemplateRef<'a> {
379    /// Fields borrowed in deterministic template order.
380    fields: &'a [StateFieldSchema],
381}