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}