Skip to main content

scientific_workflow/study/
error.rs

1//! Study composition and preflight failures.
2
3use std::path::{Path, PathBuf};
4
5use thiserror::Error;
6
7use crate::config::ConfigError;
8use crate::state::StateError;
9use crate::task::ExecutionUnitCatalogError;
10
11/// A failure while compiling complete declared intent into an immutable study.
12#[derive(Debug, Error)]
13#[non_exhaustive]
14pub enum StudyError {
15    /// Config could not load or validate project declarations.
16    #[error("failed to load project declarations")]
17    Config(#[from] ConfigError),
18
19    /// State rejected one centrally parsed named state-schema document.
20    #[error("failed to validate state schema `{state}` from `{path}`")]
21    State {
22        /// Semantic state key declared by the study manifest.
23        state: String,
24        /// Canonical source document path retained by Config.
25        path: PathBuf,
26        /// Original State semantic-validation failure.
27        #[source]
28        source: StateError,
29    },
30
31    /// State rejected a static schema document supplied by a linked provider.
32    #[error("failed to validate standard state-schema provider `{provider}`")]
33    ProvidedState {
34        /// Stable provider identity declared by the receiving execution unit.
35        provider: String,
36        /// Original State semantic-validation failure.
37        #[source]
38        source: StateError,
39    },
40
41    /// One standard provider declaration is invalid or conflicts with another.
42    #[error("invalid standard state-schema provider `{provider}`: {reason}")]
43    InvalidStateSchemaProvider {
44        /// Rejected stable provider identity.
45        provider: String,
46        /// Stable explanation of the rejected declaration.
47        reason: String,
48    },
49
50    /// Compiled execution-unit registrations are invalid or ambiguous.
51    #[error("invalid compiled execution-unit registration: {reason}")]
52    InvalidExecutionUnitRegistration {
53        /// Stable explanation of the invalid or duplicate registration.
54        reason: String,
55    },
56
57    /// A manifest task references no compiled execution unit.
58    #[error("phase `{phase}` references unregistered execution unit `{execution_unit}`")]
59    UnknownExecutionUnit {
60        /// Phase containing the unresolved reference.
61        phase: String,
62        /// Stable execution-unit key requested by the manifest.
63        execution_unit: String,
64    },
65
66    /// Automatic allocation selected an execution unit that does not permit
67    /// thread-count changes between steps.
68    #[error(
69        "execution unit `{execution_unit}` in phase `{phase}` does not declare thread-count-invariant execution required by automatic compute allocation"
70    )]
71    AutoComputeRequiresInvariantUnit {
72        /// Phase containing the incompatible unit.
73        phase: String,
74        /// Registered execution-unit key.
75        execution_unit: String,
76    },
77
78    /// A task omitted its state and its execution unit supplies no standard provider.
79    #[error(
80        "execution unit `{execution_unit}` in phase `{phase}` requires an explicit project state because it has no standard state-schema provider"
81    )]
82    MissingStateSchema {
83        /// Phase containing the unresolved invocation.
84        phase: String,
85        /// Registered execution-unit key with no schema source.
86        execution_unit: String,
87    },
88
89    /// Typed constants or observation-plan binding failed during execution-unit preflight.
90    #[error(
91        "execution unit `{execution_unit}` failed preflight for resolved parameters {ordinal} in phase `{phase}`"
92    )]
93    ExecutionUnitPreflight {
94        /// Phase containing the rejected invocation.
95        phase: String,
96        /// Stable compiled execution-unit key.
97        execution_unit: String,
98        /// Deterministic parameter expansion ordinal.
99        ordinal: u64,
100        /// Original config, observation, or execution-unit declaration error.
101        #[source]
102        source: Box<dyn std::error::Error + Send + Sync + 'static>,
103    },
104
105    /// The total expanded task count cannot be represented by stable ordinals.
106    #[error("the study contains more expanded task invocations than can be identified")]
107    TaskIdentityOverflow,
108}
109
110impl From<ExecutionUnitCatalogError> for StudyError {
111    fn from(source: ExecutionUnitCatalogError) -> Self {
112        Self::InvalidExecutionUnitRegistration {
113            reason: source.to_string(),
114        }
115    }
116}
117
118impl StudyError {
119    pub(crate) fn state_schema(state: &str, path: &Path, source: StateError) -> Self {
120        Self::State {
121            state: state.to_owned(),
122            path: path.to_path_buf(),
123            source,
124        }
125    }
126
127    pub(crate) fn execution_unit_preflight(
128        phase: &str,
129        execution_unit: &str,
130        ordinal: u64,
131        source: Box<dyn std::error::Error + Send + Sync + 'static>,
132    ) -> Self {
133        Self::ExecutionUnitPreflight {
134            phase: phase.to_owned(),
135            execution_unit: execution_unit.to_owned(),
136            ordinal,
137            source,
138        }
139    }
140}