Skip to main content

oxide_batch_core/
scope.rs

1//! Shared scoped-component definition vocabulary.
2//!
3//! These types live in core because both the immutable plan and metadata
4//! repository need to name the same value-free scope identities without a
5//! dependency from the repository crate back to the plan crate.
6
7use crate::{
8    DefinitionError, DefinitionTokenKind, ParameterValueKind, definition_token, validate_token,
9};
10
11/// Maximum number of live scoped components one execution scope may own.
12pub const MAX_SCOPED_COMPONENTS: usize = 256;
13/// Maximum number of late-bound values one scoped component may declare.
14pub const MAX_LATE_BOUND_INPUTS: usize = 64;
15/// Maximum UTF-8 bytes across one structured selector path.
16pub const MAX_SELECTOR_PATH_BYTES: usize = 1_024;
17/// Maximum number of path segments in one structured selector.
18pub const MAX_SELECTOR_PATH_SEGMENTS: usize = 32;
19
20/// Returns whether `segments` satisfy the shared structured-selector path contract.
21///
22/// The byte bound counts segment bytes plus one separator byte between segments,
23/// matching the canonical plan representation without introducing an expression language.
24#[must_use]
25pub fn selector_path_is_valid(segments: &[String]) -> bool {
26    if segments.is_empty() || segments.len() > MAX_SELECTOR_PATH_SEGMENTS {
27        return false;
28    }
29    let bytes = segments
30        .iter()
31        .map(String::len)
32        .sum::<usize>()
33        .saturating_add(segments.len().saturating_sub(1));
34    bytes <= MAX_SELECTOR_PATH_BYTES
35        && segments.iter().all(|segment| {
36            !segment.is_empty()
37                && segment.trim() == segment
38                && !segment.chars().any(char::is_control)
39        })
40}
41
42definition_token!(
43    ScopedComponentId,
44    DefinitionTokenKind::Component,
45    "Stable logical identity of one job- or step-scoped component."
46);
47
48/// Runtime lifetime of one scoped component definition.
49#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
50#[non_exhaustive]
51pub enum ScopeKind {
52    /// One live instance for one job-execution attempt.
53    Job,
54    /// One live instance for one step-execution attempt.
55    Step,
56}
57
58impl ScopeKind {
59    /// Returns the stable manifest and durable code.
60    #[must_use]
61    pub const fn as_str(self) -> &'static str {
62        match self {
63            Self::Job => "job",
64            Self::Step => "step",
65        }
66    }
67}
68
69/// Closed framework-owned metadata that a scoped resolver may read.
70#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
71#[non_exhaustive]
72pub enum ScopeFrameworkSource {
73    /// Current logical job-instance identifier.
74    JobInstanceId,
75    /// Current job-execution attempt identifier.
76    JobExecutionId,
77    /// Current step-execution attempt identifier; step scope only.
78    StepExecutionId,
79    /// One-based current job execution attempt.
80    Attempt,
81    /// Current definition revision.
82    DefinitionRevision,
83    /// Current definition fingerprint encoded as lower-case hexadecimal.
84    DefinitionFingerprint,
85    /// Current logical flow-node identifier; step scope only.
86    LogicalNodeId,
87    /// Current durable step name; step scope only.
88    StepName,
89}
90
91impl ScopeFrameworkSource {
92    /// Returns the stable manifest and durable code.
93    #[must_use]
94    pub const fn as_str(self) -> &'static str {
95        match self {
96            Self::JobInstanceId => "job_instance_id",
97            Self::JobExecutionId => "job_execution_id",
98            Self::StepExecutionId => "step_execution_id",
99            Self::Attempt => "attempt",
100            Self::DefinitionRevision => "definition_revision",
101            Self::DefinitionFingerprint => "definition_fingerprint",
102            Self::LogicalNodeId => "logical_node_id",
103            Self::StepName => "step_name",
104        }
105    }
106
107    /// Returns the value kind produced before any declared coercion.
108    #[must_use]
109    pub const fn value_kind(self) -> ParameterValueKind {
110        match self {
111            Self::JobInstanceId | Self::JobExecutionId | Self::StepExecutionId | Self::Attempt => {
112                ParameterValueKind::U64
113            }
114            Self::DefinitionRevision
115            | Self::DefinitionFingerprint
116            | Self::LogicalNodeId
117            | Self::StepName => ParameterValueKind::String,
118        }
119    }
120}