Skip to main content

oxide_batch_plan/
lib.rs

1//! Internal implementation crate for `OxideBatch`.
2//!
3//! **This crate is implementation detail. Use
4//! [`oxide-batch`](https://crates.io/crates/oxide-batch) instead.**
5//!
6//! It exists on crates.io only because the published `oxide-batch` facade
7//! depends on it. Its API carries no stability promise: items may be added,
8//! changed, or removed in any release, without a deprecation period. It has no
9//! supported-configuration matrix, no compatibility ledger row, and no
10//! independent release cadence.
11//!
12//! Everything here that `OxideBatch` supports is re-exported from `oxide-batch`
13//! under a stable path.
14//!
15//! The crate holds immutable flow graphs and the compiled execution plans they
16//! lower into. An application declares a [`FlowGraph`] of step and decision
17//! nodes joined by exit-pattern transitions, then compiles it into an immutable
18//! [`CompiledExecutionPlan`]. Compilation normalizes the graph, rejects every
19//! structural error the accepted basic-flow contract names, and produces the
20//! canonical manifest whose SHA-256 digest is the definition fingerprint.
21//!
22//! The graph remains finite and acyclic. M4 adds bounded local split and
23//! partition forms. M7 adds bounded nested-flow composition and split-branch
24//! subgraphs while retaining one compiled-plan authority; nested jobs and
25//! remote execution remain separate lifecycle boundaries.
26//! Existing one-step `TaskletJob` and `ChunkJob` definitions lower into a
27//! compatibility plan that retains their original format-1 manifest bytes and
28//! fingerprint.
29//!
30//! The crate depends on no async runtime, database driver, command-line
31//! framework, telemetry SDK, broker client, or web framework, and on no
32//! `OxideBatch` crate other than `oxide-batch-core`. The flow engine that
33//! executes a compiled plan, the metadata ports that persist its decisions,
34//! and the runtime live above this crate.
35//!
36//! # Items marked `#[doc(hidden)]`
37//!
38//! Some items exist as `#[doc(hidden)] pub` only because the facade's own code
39//! was split from these types by the extraction boundary: private access that
40//! one crate resolved by module privacy now crosses a crate boundary. They are
41//! not part of any surface, supported or otherwise, and the facade never
42//! re-exports one under its own name. The staged crate-extraction contract
43//! records each one.
44
45#![forbid(unsafe_code)]
46
47mod advanced;
48mod custom_leaf;
49mod late_binding;
50mod nested_job;
51mod repeat;
52
53pub use custom_leaf::{CustomLeafKind, CustomLeafNode};
54
55pub use late_binding::{
56    LateBindingDefinitionError, LateBoundInput, LateBoundSource, MAX_LATE_BOUND_INPUTS,
57    MAX_SCOPED_COMPONENTS, ScopeFactoryKind, ScopeFrameworkSource, ScopeKind, ScopeResolverKind,
58    ScopedComponentDefinition, ScopedComponentId,
59};
60
61pub use nested_job::{
62    FrameworkParameterSource, MAX_NESTED_JOB_PARAMETERS, MAX_SELECTOR_PATH_BYTES,
63    MAX_SELECTOR_PATH_SEGMENTS, MissingParameterPolicy, NestedJobNode, NestedJobParameterMapping,
64    NestedJobParameterSource, ParameterCoercion, SelectorPath,
65};
66pub use oxide_batch_core::RepeatId;
67pub use repeat::{
68    RepeatDefinition, RepeatDefinitionError, RepeatInterceptorDefinition, RepeatInterceptorId,
69    RepeatInterceptorKind, RepeatPolicyConfiguration, RepeatPolicyDefinition, RepeatPolicyKind,
70    RepeatStateSchema,
71};
72
73use std::collections::{BTreeMap, BTreeSet};
74use std::error::Error;
75use std::fmt;
76use std::num::NonZeroU32;
77
78use serde_json::{Value, json};
79
80use oxide_batch_core::{
81    ChunkComponentRevisions, ChunkSize, ComponentRevision, DefinitionError, DefinitionIdentity,
82    DefinitionRevision, DefinitionTokenKind, ExitCode, FaultPolicy, FlowTarget, InFlightPolicy,
83    JobName, MAX_NODES, MAX_PARTITIONS, MAX_TRANSITIONS, NodeId, ParameterIncrementerIdentity,
84    ParameterName, RestartPolicy, StartControls, StepName, TerminalKind, definition_token,
85    validate_token,
86};
87
88/// The maximum number of transitions leaving one node.
89pub const MAX_OUTGOING_TRANSITIONS: usize = 64;
90/// The maximum length of one exit pattern in UTF-8 bytes.
91pub const MAX_PATTERN_BYTES: usize = 64;
92/// The maximum number of branches in one M4 split.
93pub const MAX_SPLIT_BRANCHES: usize = 8;
94/// The maximum number of linear steps in one split branch.
95pub const MAX_BRANCH_STEPS: usize = 8;
96/// The maximum number of concurrent local partition workers.
97pub const MAX_PARTITION_WORKERS: u8 = 64;
98/// The maximum structural nesting depth of an M7 composed flow.
99pub const MAX_FLOW_COMPOSITION_DEPTH: usize = 8;
100
101/// The sibling behavior selected after one local child fails.
102#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
103#[non_exhaustive]
104pub enum LocalFailurePolicy {
105    /// Request cooperative cancellation of siblings, then join all children.
106    #[default]
107    CancelSiblings,
108    /// Allow siblings to reach their next boundary, then join all children.
109    DrainSiblings,
110}
111
112impl LocalFailurePolicy {
113    const fn as_str(self) -> &'static str {
114        match self {
115            Self::CancelSiblings => "cancel_siblings",
116            Self::DrainSiblings => "drain_siblings",
117        }
118    }
119}
120
121/// The finite concurrency and connection budget for one M4 split.
122#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
123pub struct SplitBudget {
124    max_parallel_branches: u8,
125    repository_pool_size: u32,
126}
127
128impl SplitBudget {
129    /// Constructs validated branch-concurrency and connection bounds.
130    ///
131    /// # Errors
132    ///
133    /// Rejects zero/over-limit concurrency or a pool that cannot supply every
134    /// active branch plus the owning parent connection.
135    pub fn new(max_parallel_branches: u8, repository_pool_size: u32) -> Result<Self, PlanError> {
136        if max_parallel_branches == 0 || usize::from(max_parallel_branches) > MAX_SPLIT_BRANCHES {
137            return Err(PlanError::InvalidParallelBranchBudget {
138                max: MAX_SPLIT_BRANCHES,
139            });
140        }
141        let required = u32::from(max_parallel_branches).saturating_add(1);
142        if repository_pool_size < required {
143            return Err(PlanError::InsufficientPoolCapacity {
144                required,
145                configured: repository_pool_size,
146            });
147        }
148        Ok(Self {
149            max_parallel_branches,
150            repository_pool_size,
151        })
152    }
153
154    /// Returns the maximum concurrent split branches.
155    #[must_use]
156    pub const fn max_parallel_branches(self) -> u8 {
157        self.max_parallel_branches
158    }
159
160    /// Returns the validated repository pool size.
161    #[must_use]
162    pub const fn repository_pool_size(self) -> u32 {
163        self.repository_pool_size
164    }
165}
166
167impl Default for SplitBudget {
168    fn default() -> Self {
169        Self {
170            max_parallel_branches: 1,
171            repository_pool_size: 2,
172        }
173    }
174}
175
176/// The finite worker and connection budget for one M4 partition manager.
177#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
178pub struct PartitionBudget {
179    max_partition_workers: u8,
180    repository_pool_size: u32,
181}
182
183impl PartitionBudget {
184    /// Constructs validated worker-concurrency and connection bounds.
185    ///
186    /// # Errors
187    ///
188    /// Rejects zero/over-limit concurrency or a pool that cannot supply every
189    /// active worker plus the owning parent connection.
190    pub fn new(max_partition_workers: u8, repository_pool_size: u32) -> Result<Self, PlanError> {
191        if !(1..=MAX_PARTITION_WORKERS).contains(&max_partition_workers) {
192            return Err(PlanError::InvalidPartitionWorkerBudget {
193                max: MAX_PARTITION_WORKERS,
194            });
195        }
196        let required = u32::from(max_partition_workers).saturating_add(1);
197        if repository_pool_size < required {
198            return Err(PlanError::InsufficientPoolCapacity {
199                required,
200                configured: repository_pool_size,
201            });
202        }
203        Ok(Self {
204            max_partition_workers,
205            repository_pool_size,
206        })
207    }
208
209    /// Returns the maximum concurrent partition workers.
210    #[must_use]
211    pub const fn max_partition_workers(self) -> u8 {
212        self.max_partition_workers
213    }
214
215    /// Returns the validated repository pool size.
216    #[must_use]
217    pub const fn repository_pool_size(self) -> u32 {
218        self.repository_pool_size
219    }
220}
221
222impl Default for PartitionBudget {
223    fn default() -> Self {
224        Self {
225            max_partition_workers: 4,
226            repository_pool_size: 5,
227        }
228    }
229}
230
231definition_token!(
232    DeciderRevision,
233    DefinitionTokenKind::Decider,
234    "An application-owned revision token for one deterministic decider."
235);
236
237/// The version of the durable input contract one decider reads.
238#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
239pub struct DecisionInputVersion(NonZeroU32);
240
241impl DecisionInputVersion {
242    /// Constructs a nonzero durable input-contract version.
243    ///
244    /// # Errors
245    ///
246    /// Returns [`PlanError::ZeroDecisionInputVersion`] for zero.
247    pub fn new(value: u32) -> Result<Self, PlanError> {
248        NonZeroU32::new(value)
249            .map(Self)
250            .ok_or(PlanError::ZeroDecisionInputVersion)
251    }
252
253    /// Returns the version.
254    #[must_use]
255    pub const fn get(self) -> u32 {
256        self.0.get()
257    }
258}
259
260/// A bounded exit-outcome pattern used to select one transition.
261///
262/// A pattern contains literal characters plus `*` for zero or more characters
263/// and `?` for exactly one character. It matches the bounded
264/// [`ExitCode`], never [`BatchStatus`](oxide_batch_core::BatchStatus).
265///
266/// The worked example lives in the `oxide-batch` crate documentation, so that
267/// it keeps demonstrating the supported import path.
268#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
269pub struct ExitPattern(String);
270
271impl ExitPattern {
272    /// Validates and constructs an exit pattern.
273    ///
274    /// # Errors
275    ///
276    /// Returns [`PlanError::InvalidPattern`] for an empty pattern, a pattern
277    /// longer than 64 UTF-8 bytes, surrounding whitespace, or a control
278    /// character.
279    pub fn new(value: impl Into<String>) -> Result<Self, PlanError> {
280        let value = value.into();
281        if value.is_empty()
282            || value.len() > MAX_PATTERN_BYTES
283            || value.trim() != value
284            || value.chars().any(char::is_control)
285        {
286            return Err(PlanError::InvalidPattern {
287                max_bytes: MAX_PATTERN_BYTES,
288            });
289        }
290        Ok(Self(value))
291    }
292
293    /// Borrows the validated pattern.
294    #[must_use]
295    pub fn as_str(&self) -> &str {
296        &self.0
297    }
298
299    /// Returns whether this pattern matches one exit code.
300    #[must_use]
301    pub fn matches(&self, code: &ExitCode) -> bool {
302        let pattern: Vec<char> = self.0.chars().collect();
303        let value: Vec<char> = code.as_str().chars().collect();
304        matches_from(&pattern, &value)
305    }
306
307    /// Returns the computed specificity used to order transitions.
308    ///
309    /// A greater specificity is evaluated first.
310    #[must_use]
311    pub fn specificity(&self) -> PatternSpecificity {
312        let wildcards = self
313            .0
314            .chars()
315            .filter(|character| matches!(character, '*' | '?'))
316            .count();
317        let literals = self.0.chars().count() - wildcards;
318        PatternSpecificity {
319            literals,
320            wildcards,
321            bytes: self.0.len(),
322        }
323    }
324
325    /// Returns whether some exit code exists that both patterns match.
326    #[must_use]
327    pub fn intersects(&self, other: &Self) -> bool {
328        let left: Vec<char> = self.0.chars().collect();
329        let right: Vec<char> = other.0.chars().collect();
330        let mut memo = vec![None; (left.len() + 1) * (right.len() + 1)];
331        intersects_from(&left, &right, 0, 0, &mut memo)
332    }
333}
334
335impl fmt::Display for ExitPattern {
336    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
337        formatter.write_str(&self.0)
338    }
339}
340
341fn matches_from(pattern: &[char], value: &[char]) -> bool {
342    let mut pattern_index = 0_usize;
343    let mut value_index = 0_usize;
344    let mut star: Option<(usize, usize)> = None;
345    while value_index < value.len() {
346        match pattern.get(pattern_index) {
347            Some('*') => {
348                star = Some((pattern_index, value_index));
349                pattern_index += 1;
350            }
351            Some('?') => {
352                pattern_index += 1;
353                value_index += 1;
354            }
355            Some(literal) if *literal == value[value_index] => {
356                pattern_index += 1;
357                value_index += 1;
358            }
359            _ => match star {
360                Some((star_index, resume)) => {
361                    pattern_index = star_index + 1;
362                    value_index = resume + 1;
363                    star = Some((star_index, resume + 1));
364                }
365                None => return false,
366            },
367        }
368    }
369    pattern[pattern_index..]
370        .iter()
371        .all(|character| *character == '*')
372}
373
374fn intersects_from(
375    left: &[char],
376    right: &[char],
377    left_index: usize,
378    right_index: usize,
379    memo: &mut [Option<bool>],
380) -> bool {
381    let key = left_index * (right.len() + 1) + right_index;
382    if let Some(cached) = memo[key] {
383        return cached;
384    }
385    let answer = match (left.get(left_index), right.get(right_index)) {
386        (None, None) => true,
387        (None, Some(_)) => right[right_index..].iter().all(|value| *value == '*'),
388        (Some(_), None) => left[left_index..].iter().all(|value| *value == '*'),
389        (Some('*'), _) => {
390            intersects_from(left, right, left_index + 1, right_index, memo)
391                || intersects_from(left, right, left_index, right_index + 1, memo)
392        }
393        (_, Some('*')) => {
394            intersects_from(left, right, left_index, right_index + 1, memo)
395                || intersects_from(left, right, left_index + 1, right_index, memo)
396        }
397        (Some(left_character), Some(right_character)) => {
398            (*left_character == '?' || *right_character == '?' || left_character == right_character)
399                && intersects_from(left, right, left_index + 1, right_index + 1, memo)
400        }
401    };
402    memo[key] = Some(answer);
403    answer
404}
405
406/// The computed specificity of one exit pattern.
407///
408/// Ordering compares more literal characters first, then fewer wildcards, then
409/// a longer UTF-8 byte length. A greater value is evaluated first.
410#[derive(Clone, Copy, Debug, Eq, PartialEq)]
411pub struct PatternSpecificity {
412    literals: usize,
413    wildcards: usize,
414    bytes: usize,
415}
416
417impl PatternSpecificity {
418    /// Returns the number of literal characters.
419    #[must_use]
420    pub const fn literals(self) -> usize {
421        self.literals
422    }
423
424    /// Returns the number of `*` and `?` characters.
425    #[must_use]
426    pub const fn wildcards(self) -> usize {
427        self.wildcards
428    }
429
430    /// Returns the pattern length in UTF-8 bytes.
431    #[must_use]
432    pub const fn bytes(self) -> usize {
433        self.bytes
434    }
435}
436
437impl Ord for PatternSpecificity {
438    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
439        self.literals
440            .cmp(&other.literals)
441            .then_with(|| other.wildcards.cmp(&self.wildcards))
442            .then_with(|| self.bytes.cmp(&other.bytes))
443    }
444}
445
446impl PartialOrd for PatternSpecificity {
447    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
448        Some(self.cmp(other))
449    }
450}
451
452/// The executable kind and restart-relevant declaration of one step node.
453#[derive(Clone, Debug, Eq, PartialEq)]
454#[non_exhaustive]
455pub enum StepComponents {
456    /// A single-invocation tasklet body.
457    Tasklet(ComponentRevision),
458    /// A restartable reader, processor, and writer pipeline.
459    Chunk {
460        /// The committed chunk size.
461        size: ChunkSize,
462        /// The restart-relevant component revisions and state schemas.
463        revisions: Box<ChunkComponentRevisions>,
464    },
465}
466
467impl StepComponents {
468    fn kind_name(&self) -> &'static str {
469        match self {
470            Self::Tasklet(_) => "tasklet",
471            Self::Chunk { .. } => "chunk",
472        }
473    }
474
475    fn manifest_value(&self) -> Value {
476        match self {
477            Self::Tasklet(revision) => json!({
478                "component": revision.as_str(),
479                "delivery_mode": "best_effort",
480                "transaction_boundary": "tasklet_completion"
481            }),
482            Self::Chunk { size, revisions } => {
483                let mut chunk = chunk_declaration_manifest(revisions);
484                if let Some(members) = chunk.as_object_mut() {
485                    members.insert("size".to_owned(), json!(size.get()));
486                    members.insert(
487                        "transaction_boundary".to_owned(),
488                        Value::String("chunk".to_owned()),
489                    );
490                }
491                chunk
492            }
493        }
494    }
495}
496
497/// One executable node of a compiled plan.
498#[derive(Clone, Debug, Eq, PartialEq)]
499pub struct StepNode {
500    id: NodeId,
501    step_name: StepName,
502    components: StepComponents,
503    start: StartControls,
504    fault: Option<FaultPolicy>,
505    listeners: Vec<ComponentRevision>,
506    repeat: Option<RepeatDefinition>,
507}
508
509impl StepNode {
510    /// Declares one step node.
511    #[must_use]
512    pub fn new(id: NodeId, step_name: StepName, components: StepComponents) -> Self {
513        Self {
514            id,
515            step_name,
516            components,
517            start: StartControls::default(),
518            fault: None,
519            listeners: Vec::new(),
520            repeat: None,
521        }
522    }
523
524    /// Declares explicit start controls.
525    #[must_use]
526    pub const fn with_start_controls(mut self, start: StartControls) -> Self {
527        self.start = start;
528        self
529    }
530
531    /// Declares the fault policy this step's fingerprint captures.
532    #[must_use]
533    pub fn with_fault_policy(mut self, policy: FaultPolicy) -> Self {
534        self.fault = Some(policy);
535        self
536    }
537
538    /// Declares one authoritative listener revision in registration order.
539    #[must_use]
540    pub fn with_listener_revision(mut self, revision: ComponentRevision) -> Self {
541        self.listeners.push(revision);
542        self
543    }
544
545    /// Declares restart-relevant Gate-C repeat metadata around this step.
546    #[must_use]
547    pub fn with_repeat_definition(mut self, repeat: RepeatDefinition) -> Self {
548        self.repeat = Some(repeat);
549        self
550    }
551
552    /// Borrows the repeat definition attached to this step, when present.
553    #[must_use]
554    pub const fn repeat_definition(&self) -> Option<&RepeatDefinition> {
555        self.repeat.as_ref()
556    }
557
558    /// Borrows the stable node identifier.
559    #[must_use]
560    pub const fn id(&self) -> &NodeId {
561        &self.id
562    }
563
564    /// Borrows the durable step name.
565    #[must_use]
566    pub const fn step_name(&self) -> &StepName {
567        &self.step_name
568    }
569
570    /// Borrows the executable component declaration.
571    #[must_use]
572    pub const fn components(&self) -> &StepComponents {
573        &self.components
574    }
575
576    /// Returns the restart-relevant start controls.
577    #[must_use]
578    pub const fn start_controls(&self) -> StartControls {
579        self.start
580    }
581
582    /// Borrows the declared fault policy.
583    #[must_use]
584    pub const fn fault_policy(&self) -> Option<&FaultPolicy> {
585        self.fault.as_ref()
586    }
587
588    /// Borrows the authoritative listener revisions in registration order.
589    #[must_use]
590    pub fn listener_revisions(&self) -> &[ComponentRevision] {
591        &self.listeners
592    }
593
594    fn manifest_value(&self) -> Value {
595        let mut value = json!({
596            "id": self.id.as_str(),
597            "kind": "step",
598            "listeners": self
599                .listeners
600                .iter()
601                .map(|revision| Value::String(revision.as_str().to_owned()))
602                .collect::<Vec<_>>(),
603            "policy": self.fault.as_ref().map_or(Value::Null, fault_manifest_value),
604            "start": start_controls_manifest(self.start),
605            "step": {
606                "declaration": self.components.manifest_value(),
607                "kind": self.components.kind_name(),
608                "name": self.step_name.as_str()
609            }
610        });
611        if let Some(repeat) = &self.repeat
612            && let Some(object) = value.as_object_mut()
613        {
614            object.insert("repeat".to_owned(), repeat.manifest_value());
615        }
616        value
617    }
618}
619
620/// One deterministic decision node of a compiled plan.
621///
622/// M3 compiles and fingerprints decision nodes; executing them is owned by the
623/// durable-flow workstream.
624#[derive(Clone, Debug, Eq, PartialEq)]
625pub struct DecisionNode {
626    id: NodeId,
627    revision: DeciderRevision,
628    input_version: DecisionInputVersion,
629}
630
631impl DecisionNode {
632    /// Declares one decision node.
633    #[must_use]
634    pub const fn new(
635        id: NodeId,
636        revision: DeciderRevision,
637        input_version: DecisionInputVersion,
638    ) -> Self {
639        Self {
640            id,
641            revision,
642            input_version,
643        }
644    }
645
646    /// Borrows the stable node identifier.
647    #[must_use]
648    pub const fn id(&self) -> &NodeId {
649        &self.id
650    }
651
652    /// Borrows the application-owned decider revision.
653    #[must_use]
654    pub const fn revision(&self) -> &DeciderRevision {
655        &self.revision
656    }
657
658    /// Returns the durable input-contract version.
659    #[must_use]
660    pub const fn input_version(&self) -> DecisionInputVersion {
661        self.input_version
662    }
663
664    fn manifest_value(&self) -> Value {
665        json!({
666            "decision": {
667                "input_version": self.input_version.get(),
668                "revision": self.revision.as_str()
669            },
670            "id": self.id.as_str(),
671            "kind": "decision"
672        })
673    }
674}
675
676/// One validated execution scope inside an M7 composed plan.
677#[derive(Clone, Debug, Eq, PartialEq)]
678pub struct CompiledFlowScope {
679    entry: NodeId,
680    members: BTreeSet<NodeId>,
681}
682
683impl CompiledFlowScope {
684    pub(crate) fn new(entry: NodeId, members: BTreeSet<NodeId>) -> Self {
685        Self { entry, members }
686    }
687
688    /// Borrows the first executable node in this scope.
689    #[must_use]
690    pub const fn entry(&self) -> &NodeId {
691        &self.entry
692    }
693
694    /// Returns whether an executable node belongs to this scope.
695    #[must_use]
696    pub fn contains(&self, node: &NodeId) -> bool {
697        self.members.contains(node)
698    }
699
700    /// Iterates executable members in canonical logical-ID order.
701    #[must_use]
702    pub fn members(&self) -> impl ExactSizeIterator<Item = &NodeId> {
703        self.members.iter()
704    }
705}
706
707/// One reusable M7 flow embedded under a stable structural owner.
708#[derive(Clone, Debug, Eq, PartialEq)]
709pub struct NestedFlow {
710    id: NodeId,
711    graph: Box<FlowGraph>,
712}
713
714impl NestedFlow {
715    /// Declares one nested-flow boundary.
716    #[must_use]
717    pub fn new(id: NodeId, graph: FlowGraph) -> Self {
718        Self {
719            id,
720            graph: Box::new(graph),
721        }
722    }
723
724    /// Borrows the stable structural owner ID.
725    #[must_use]
726    pub const fn id(&self) -> &NodeId {
727        &self.id
728    }
729
730    /// Borrows the nested graph declaration.
731    #[must_use]
732    pub const fn graph(&self) -> &FlowGraph {
733        &self.graph
734    }
735}
736
737/// One split branch. M4 branches are linear; M7 may embed a bounded flow.
738#[derive(Clone, Debug, Eq, PartialEq)]
739pub struct SplitBranch {
740    steps: Vec<StepNode>,
741    flow: Option<Box<FlowGraph>>,
742}
743
744impl SplitBranch {
745    /// Declares the byte-compatible M4 linear branch form.
746    ///
747    /// Cardinality and identifier uniqueness are checked by
748    /// [`FlowGraph::compile`], so builders can assemble a complete diagnostic
749    /// instead of panicking while under construction.
750    #[must_use]
751    pub fn new(steps: Vec<StepNode>) -> Self {
752        Self { steps, flow: None }
753    }
754
755    /// Declares an M7 branch as a bounded acyclic subgraph.
756    #[must_use]
757    pub fn flow(graph: FlowGraph) -> Self {
758        Self {
759            steps: Vec::new(),
760            flow: Some(Box::new(graph)),
761        }
762    }
763
764    /// Borrows the legacy linear branch steps.
765    ///
766    /// An M7 flow branch returns an empty slice; use [`flow_graph`](Self::flow_graph)
767    /// to inspect its declaration.
768    #[must_use]
769    pub fn steps(&self) -> &[StepNode] {
770        &self.steps
771    }
772
773    /// Borrows the M7 branch graph when this is a flow branch.
774    #[must_use]
775    pub fn flow_graph(&self) -> Option<&FlowGraph> {
776        self.flow.as_deref()
777    }
778
779    /// Borrows the legacy branch identity, which is its first logical step ID.
780    ///
781    /// Flow branches have a separate compiled scope and therefore no synthetic
782    /// branch `NodeId`.
783    #[must_use]
784    pub fn id(&self) -> Option<&NodeId> {
785        self.steps.first().map(StepNode::id)
786    }
787
788    fn manifest_value(&self) -> Value {
789        Value::Array(self.steps.iter().map(StepNode::manifest_value).collect())
790    }
791}
792
793/// A bounded M4 split whose branches converge at exactly one join node.
794#[derive(Clone, Debug, Eq, PartialEq)]
795pub struct SplitNode {
796    id: NodeId,
797    branches: Vec<SplitBranch>,
798    join: NodeId,
799    budget: SplitBudget,
800    failure_policy: LocalFailurePolicy,
801}
802
803impl SplitNode {
804    /// Declares a split, its ordered branches, and its unique join.
805    #[must_use]
806    pub fn new(id: NodeId, branches: Vec<SplitBranch>, join: NodeId, budget: SplitBudget) -> Self {
807        Self {
808            id,
809            branches,
810            join,
811            budget,
812            failure_policy: LocalFailurePolicy::default(),
813        }
814    }
815
816    /// Selects sibling failure behavior.
817    #[must_use]
818    pub const fn with_failure_policy(mut self, failure_policy: LocalFailurePolicy) -> Self {
819        self.failure_policy = failure_policy;
820        self
821    }
822
823    /// Borrows the stable split identifier.
824    #[must_use]
825    pub const fn id(&self) -> &NodeId {
826        &self.id
827    }
828
829    /// Borrows branches in deterministic aggregation order.
830    #[must_use]
831    pub fn branches(&self) -> &[SplitBranch] {
832        &self.branches
833    }
834
835    /// Borrows the split's unique join identifier.
836    #[must_use]
837    pub const fn join(&self) -> &NodeId {
838        &self.join
839    }
840
841    /// Returns the finite local resource budget.
842    #[must_use]
843    pub const fn budget(&self) -> SplitBudget {
844        self.budget
845    }
846
847    /// Returns sibling failure behavior.
848    #[must_use]
849    pub const fn failure_policy(&self) -> LocalFailurePolicy {
850        self.failure_policy
851    }
852
853    /// Projects the restart-relevant split declaration.
854    ///
855    /// The budget is a throughput bound rather than a durable-meaning value, so
856    /// [ADR-0009](https://github.com/luceat-lux-vestra/oxide-batch/blob/main/docs/architecture/decisions/0009-definition-fingerprint-input-set.md)
857    /// excludes it. Branch membership and order select assignment and remain.
858    fn manifest_value(&self) -> Value {
859        json!({
860            "branches": self.branches.iter().map(SplitBranch::manifest_value).collect::<Vec<_>>(),
861            "failure_policy": self.failure_policy.as_str(),
862            "id": self.id.as_str(),
863            "join": self.join.as_str(),
864            "kind": "split"
865        })
866    }
867}
868
869/// The structural join owned by one M4 split.
870#[derive(Clone, Debug, Eq, PartialEq)]
871pub struct JoinNode {
872    id: NodeId,
873}
874
875impl JoinNode {
876    /// Declares a structural join.
877    #[must_use]
878    pub const fn new(id: NodeId) -> Self {
879        Self { id }
880    }
881
882    /// Borrows the stable join identifier.
883    #[must_use]
884    pub const fn id(&self) -> &NodeId {
885        &self.id
886    }
887
888    fn manifest_value(&self) -> Value {
889        json!({
890            "id": self.id.as_str(),
891            "kind": "join"
892        })
893    }
894}
895
896/// A finite durable partition count for one M4 partitioned step.
897#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
898pub struct PartitionCount(u16);
899
900impl PartitionCount {
901    /// Constructs a count in the accepted `1..=1024` range.
902    ///
903    /// # Errors
904    ///
905    /// Returns [`PlanError::InvalidPartitionCount`] outside that range.
906    pub fn new(value: u16) -> Result<Self, PlanError> {
907        if value == 0 || value > MAX_PARTITIONS {
908            return Err(PlanError::InvalidPartitionCount {
909                max: MAX_PARTITIONS,
910            });
911        }
912        Ok(Self(value))
913    }
914
915    /// Returns the declared partition count.
916    #[must_use]
917    pub const fn get(self) -> u16 {
918        self.0
919    }
920}
921
922/// A bounded local partition manager and its ordinary worker-step definition.
923#[derive(Clone, Debug, Eq, PartialEq)]
924pub struct PartitionedStepNode {
925    id: NodeId,
926    step_name: StepName,
927    worker: StepNode,
928    partitioner: ComponentRevision,
929    aggregation: ComponentRevision,
930    partitions: PartitionCount,
931    budget: PartitionBudget,
932    failure_policy: LocalFailurePolicy,
933    start: StartControls,
934}
935
936impl PartitionedStepNode {
937    /// Declares the complete restart-relevant local partition shape.
938    #[allow(clippy::too_many_arguments)]
939    #[must_use]
940    pub fn new(
941        id: NodeId,
942        step_name: StepName,
943        worker: StepNode,
944        partitioner: ComponentRevision,
945        aggregation: ComponentRevision,
946        partitions: PartitionCount,
947        budget: PartitionBudget,
948    ) -> Self {
949        Self {
950            id,
951            step_name,
952            worker,
953            partitioner,
954            aggregation,
955            partitions,
956            budget,
957            failure_policy: LocalFailurePolicy::default(),
958            start: StartControls::default(),
959        }
960    }
961
962    /// Selects sibling failure behavior.
963    #[must_use]
964    pub const fn with_failure_policy(mut self, failure_policy: LocalFailurePolicy) -> Self {
965        self.failure_policy = failure_policy;
966        self
967    }
968
969    /// Declares the partition manager's start controls.
970    #[must_use]
971    pub const fn with_start_controls(mut self, start: StartControls) -> Self {
972        self.start = start;
973        self
974    }
975
976    /// Borrows the stable manager node identifier.
977    #[must_use]
978    pub const fn id(&self) -> &NodeId {
979        &self.id
980    }
981
982    /// Borrows the manager's durable step name.
983    #[must_use]
984    pub const fn step_name(&self) -> &StepName {
985        &self.step_name
986    }
987
988    /// Borrows the ordinary tasklet or chunk worker declaration.
989    #[must_use]
990    pub const fn worker(&self) -> &StepNode {
991        &self.worker
992    }
993
994    /// Borrows the deterministic partitioner revision.
995    #[must_use]
996    pub const fn partitioner(&self) -> &ComponentRevision {
997        &self.partitioner
998    }
999
1000    /// Borrows the deterministic aggregation revision.
1001    #[must_use]
1002    pub const fn aggregation(&self) -> &ComponentRevision {
1003        &self.aggregation
1004    }
1005
1006    /// Returns the finite partition count.
1007    #[must_use]
1008    pub const fn partition_count(&self) -> PartitionCount {
1009        self.partitions
1010    }
1011
1012    /// Returns the finite local resource budget.
1013    #[must_use]
1014    pub const fn budget(&self) -> PartitionBudget {
1015        self.budget
1016    }
1017
1018    /// Returns sibling failure behavior.
1019    #[must_use]
1020    pub const fn failure_policy(&self) -> LocalFailurePolicy {
1021        self.failure_policy
1022    }
1023
1024    /// Returns the partition manager's start controls.
1025    #[must_use]
1026    pub const fn start_controls(&self) -> StartControls {
1027        self.start
1028    }
1029
1030    /// Projects the restart-relevant partition declaration.
1031    ///
1032    /// The partition count selects durable assignment and the partitioner and
1033    /// aggregation revisions decide how that assignment and its results are
1034    /// interpreted, so all three remain. The worker and connection budget is a
1035    /// throughput bound that [ADR-0009](https://github.com/luceat-lux-vestra/oxide-batch/blob/main/docs/architecture/decisions/0009-definition-fingerprint-input-set.md)
1036    /// excludes.
1037    fn manifest_value(&self) -> Value {
1038        json!({
1039            "aggregation": self.aggregation.as_str(),
1040            "failure_policy": self.failure_policy.as_str(),
1041            "id": self.id.as_str(),
1042            "kind": "partitioned_step",
1043            "partition_count": self.partitions.get(),
1044            "partitioner": self.partitioner.as_str(),
1045            "start": start_controls_manifest(self.start),
1046            "step_name": self.step_name.as_str(),
1047            "worker": self.worker.manifest_value()
1048        })
1049    }
1050}
1051
1052/// One node of a declared flow graph.
1053#[derive(Clone, Debug, Eq, PartialEq)]
1054#[non_exhaustive]
1055pub enum FlowNode {
1056    /// A tasklet or chunk step.
1057    Step(Box<StepNode>),
1058    /// A deterministic decision.
1059    Decision(DecisionNode),
1060    /// A separately durable child-job lifecycle boundary.
1061    NestedJob(Box<NestedJobNode>),
1062    /// A registered framework-owned custom leaf.
1063    CustomLeaf(Box<CustomLeafNode>),
1064    /// A bounded set of linear branches and its structural join.
1065    Split(Box<SplitNode>),
1066    /// A structural join owned by exactly one split.
1067    Join(JoinNode),
1068    /// A bounded durable local-partition manager.
1069    PartitionedStep(Box<PartitionedStepNode>),
1070}
1071
1072impl FlowNode {
1073    fn has_nonrestartable_step(&self) -> bool {
1074        match self {
1075            Self::Step(step) => {
1076                step.start_controls().restart_policy() == RestartPolicy::NotRestartable
1077            }
1078            Self::CustomLeaf(custom) => {
1079                custom.start_controls().restart_policy() == RestartPolicy::NotRestartable
1080            }
1081            Self::PartitionedStep(partitioned) => {
1082                partitioned.start_controls().restart_policy() == RestartPolicy::NotRestartable
1083                    || partitioned.worker().start_controls().restart_policy()
1084                        == RestartPolicy::NotRestartable
1085            }
1086            Self::Split(split) => {
1087                split
1088                    .branches()
1089                    .iter()
1090                    .flat_map(SplitBranch::steps)
1091                    .any(|step| {
1092                        step.start_controls().restart_policy() == RestartPolicy::NotRestartable
1093                    })
1094            }
1095            _ => false,
1096        }
1097    }
1098
1099    fn has_repeat_definition(&self) -> bool {
1100        match self {
1101            Self::Step(step) => step.repeat_definition().is_some(),
1102            Self::PartitionedStep(partitioned) => {
1103                partitioned.worker().repeat_definition().is_some()
1104            }
1105            Self::Split(split) => split
1106                .branches()
1107                .iter()
1108                .flat_map(SplitBranch::steps)
1109                .any(|step| step.repeat_definition().is_some()),
1110            _ => false,
1111        }
1112    }
1113
1114    /// Declares a step node.
1115    #[must_use]
1116    pub fn step(node: StepNode) -> Self {
1117        Self::Step(Box::new(node))
1118    }
1119
1120    /// Declares a decision node.
1121    #[must_use]
1122    pub const fn decision(node: DecisionNode) -> Self {
1123        Self::Decision(node)
1124    }
1125
1126    /// Declares a separately durable nested-job node.
1127    #[must_use]
1128    pub fn nested_job(node: NestedJobNode) -> Self {
1129        Self::NestedJob(Box::new(node))
1130    }
1131
1132    /// Declares a registered framework-owned custom leaf.
1133    #[must_use]
1134    pub fn custom_leaf(node: CustomLeafNode) -> Self {
1135        Self::CustomLeaf(Box::new(node))
1136    }
1137
1138    /// Declares a bounded split node.
1139    #[must_use]
1140    pub fn split(node: SplitNode) -> Self {
1141        Self::Split(Box::new(node))
1142    }
1143
1144    /// Declares a structural join node.
1145    #[must_use]
1146    pub const fn join(node: JoinNode) -> Self {
1147        Self::Join(node)
1148    }
1149
1150    /// Declares a bounded local partitioned-step node.
1151    #[must_use]
1152    pub fn partitioned_step(node: PartitionedStepNode) -> Self {
1153        Self::PartitionedStep(Box::new(node))
1154    }
1155
1156    /// Borrows the node's stable identifier.
1157    #[must_use]
1158    pub const fn id(&self) -> &NodeId {
1159        match self {
1160            Self::Step(node) => node.id(),
1161            Self::Decision(node) => node.id(),
1162            Self::NestedJob(node) => node.id(),
1163            Self::CustomLeaf(node) => node.id(),
1164            Self::Split(node) => node.id(),
1165            Self::Join(node) => node.id(),
1166            Self::PartitionedStep(node) => node.id(),
1167        }
1168    }
1169
1170    fn manifest_value(&self) -> Value {
1171        match self {
1172            Self::Step(node) => node.manifest_value(),
1173            Self::Decision(node) => node.manifest_value(),
1174            Self::NestedJob(node) => node.manifest_value(),
1175            Self::CustomLeaf(node) => node.manifest_value(),
1176            Self::Split(node) => node.manifest_value(),
1177            Self::Join(node) => node.manifest_value(),
1178            Self::PartitionedStep(node) => node.manifest_value(),
1179        }
1180    }
1181}
1182
1183/// One declared transition edge.
1184#[derive(Clone, Debug, Eq, PartialEq)]
1185pub struct FlowTransition {
1186    source: NodeId,
1187    pattern: ExitPattern,
1188    target: FlowTarget,
1189}
1190
1191impl FlowTransition {
1192    /// Declares one directed transition selected by an exit pattern.
1193    #[must_use]
1194    pub const fn new(source: NodeId, pattern: ExitPattern, target: FlowTarget) -> Self {
1195        Self {
1196            source,
1197            pattern,
1198            target,
1199        }
1200    }
1201
1202    /// Borrows the source node identifier.
1203    #[must_use]
1204    pub const fn source(&self) -> &NodeId {
1205        &self.source
1206    }
1207
1208    /// Borrows the selecting pattern.
1209    #[must_use]
1210    pub const fn pattern(&self) -> &ExitPattern {
1211        &self.pattern
1212    }
1213
1214    /// Borrows the selected target.
1215    #[must_use]
1216    pub const fn target(&self) -> &FlowTarget {
1217        &self.target
1218    }
1219
1220    fn manifest_value(&self) -> Value {
1221        json!({
1222            "pattern": self.pattern.as_str(),
1223            "source": self.source.as_str(),
1224            "target": flow_target_manifest(&self.target)
1225        })
1226    }
1227}
1228
1229/// An immutable declaration of the M3 flow subset.
1230///
1231/// The worked example lives in the `oxide-batch` crate documentation, so that
1232/// it keeps demonstrating the supported import path.
1233#[derive(Clone, Debug, Default, Eq, PartialEq)]
1234pub struct FlowGraph {
1235    entry: Option<NodeId>,
1236    nodes: Vec<FlowNode>,
1237    transitions: Vec<FlowTransition>,
1238    nested_flows: Vec<NestedFlow>,
1239    scoped_components: Vec<ScopedComponentDefinition>,
1240    parameter_incrementer: Option<ParameterIncrementerIdentity>,
1241    job_restart_policy: RestartPolicy,
1242}
1243
1244impl FlowGraph {
1245    /// Starts a graph at its entry node.
1246    #[must_use]
1247    pub fn new(entry: NodeId) -> Self {
1248        Self {
1249            entry: Some(entry),
1250            nodes: Vec::new(),
1251            transitions: Vec::new(),
1252            nested_flows: Vec::new(),
1253            scoped_components: Vec::new(),
1254            parameter_incrementer: None,
1255            job_restart_policy: RestartPolicy::Restartable,
1256        }
1257    }
1258
1259    /// Declares one node.
1260    #[must_use]
1261    pub fn with_node(mut self, node: FlowNode) -> Self {
1262        self.nodes.push(node);
1263        self
1264    }
1265
1266    /// Embeds one reusable flow under a stable structural owner.
1267    #[must_use]
1268    pub fn with_nested_flow(mut self, flow: NestedFlow) -> Self {
1269        self.nested_flows.push(flow);
1270        self
1271    }
1272
1273    /// Declares one restart-relevant job- or step-scoped component.
1274    ///
1275    /// Components are canonicalized by scope and logical component ID during
1276    /// compilation. Duplicate identities fail closed.
1277    #[must_use]
1278    pub fn with_scoped_component(mut self, component: ScopedComponentDefinition) -> Self {
1279        self.scoped_components.push(component);
1280        self
1281    }
1282
1283    /// Declares the restart-relevant identity of the parameter incrementer
1284    /// authorized for this definition.
1285    ///
1286    /// Declaring an incrementer identity opts the graph into manifest format 4.
1287    #[must_use]
1288    pub fn with_parameter_incrementer_identity(
1289        mut self,
1290        identity: ParameterIncrementerIdentity,
1291    ) -> Self {
1292        self.parameter_incrementer = Some(identity);
1293        self
1294    }
1295
1296    /// Applies the execution-definition restart policy for this job.
1297    ///
1298    /// A non-restartable declaration opts the definition into manifest format 4.
1299    /// Nested flow declarations may only narrow the enclosing job to
1300    /// non-restartable; they can never reset a non-restartable parent.
1301    #[must_use]
1302    pub const fn with_job_restart_policy(mut self, policy: RestartPolicy) -> Self {
1303        self.job_restart_policy = policy;
1304        self
1305    }
1306
1307    /// Returns the declared job restart policy.
1308    #[must_use]
1309    pub const fn job_restart_policy(&self) -> RestartPolicy {
1310        self.job_restart_policy
1311    }
1312
1313    /// Borrows the declared entry reference.
1314    #[must_use]
1315    pub const fn entry(&self) -> Option<&NodeId> {
1316        self.entry.as_ref()
1317    }
1318
1319    fn requires_advanced_format(&self) -> bool {
1320        self.job_restart_policy == RestartPolicy::NotRestartable
1321            || self.parameter_incrementer.is_some()
1322            || !self.scoped_components.is_empty()
1323            || !self.nested_flows.is_empty()
1324            || self.nodes.iter().any(|node| {
1325                node.has_nonrestartable_step()
1326                    || node.has_repeat_definition()
1327                    || match node {
1328                        FlowNode::NestedJob(_) | FlowNode::CustomLeaf(_) => true,
1329                        FlowNode::Split(split) => {
1330                            split.branches().iter().any(|branch| branch.flow.is_some())
1331                        }
1332                        _ => false,
1333                    }
1334            })
1335    }
1336
1337    /// Declares one explicit transition.
1338    #[must_use]
1339    pub fn with_transition(mut self, transition: FlowTransition) -> Self {
1340        self.transitions.push(transition);
1341        self
1342    }
1343
1344    /// Declares the convenience sequential edge.
1345    ///
1346    /// A sequential edge compiles to an exact `FAILED` transition leading to
1347    /// [`TerminalKind::Fail`] and a less specific `*` transition leading to
1348    /// `next`. Custom successful exit codes therefore continue, while a failed
1349    /// step ends the job.
1350    ///
1351    /// # Errors
1352    ///
1353    /// Returns [`PlanError::InvalidPattern`] only if the framework-owned
1354    /// patterns cannot be constructed.
1355    pub fn with_sequence(self, source: NodeId, next: FlowTarget) -> Result<Self, PlanError> {
1356        Ok(self
1357            .with_transition(FlowTransition::new(
1358                source.clone(),
1359                ExitPattern::new("FAILED")?,
1360                FlowTarget::Terminal(TerminalKind::Fail),
1361            ))
1362            .with_transition(FlowTransition::new(source, ExitPattern::new("*")?, next)))
1363    }
1364
1365    /// Validates and normalizes the graph into an immutable plan.
1366    ///
1367    /// # Errors
1368    ///
1369    /// Returns [`PlanError`] for a missing entry node, a duplicate logical
1370    /// identifier, an undefined source or target, a node without outgoing
1371    /// transitions, two equally specific patterns that can match one value, an
1372    /// unreachable node, a cycle, an exceeded bound, or a manifest that cannot
1373    /// be encoded within the durable limit.
1374    pub fn compile(
1375        self,
1376        job_name: &JobName,
1377        revision: DefinitionRevision,
1378    ) -> Result<CompiledExecutionPlan, PlanError> {
1379        if self.requires_advanced_format() {
1380            return advanced::compile(self, job_name, revision);
1381        }
1382        let entry = self.entry.ok_or(PlanError::MissingEntryNode)?;
1383        if self.nodes.len() > MAX_NODES {
1384            return Err(PlanError::TooManyNodes { max: MAX_NODES });
1385        }
1386        if self.transitions.len() > MAX_TRANSITIONS {
1387            return Err(PlanError::TooManyTransitions {
1388                max: MAX_TRANSITIONS,
1389            });
1390        }
1391
1392        let mut nodes = BTreeMap::new();
1393        for node in self.nodes {
1394            if nodes.insert(node.id().clone(), node.clone()).is_some() {
1395                return Err(PlanError::DuplicateNodeId {
1396                    node: node.id().clone(),
1397                });
1398            }
1399        }
1400        if !nodes.contains_key(&entry) {
1401            return Err(PlanError::UndefinedNode {
1402                node: entry.clone(),
1403            });
1404        }
1405        let local_scale = check_local_scale_subset(&entry, &nodes)?;
1406
1407        let mut outgoing: BTreeMap<NodeId, Vec<FlowTransition>> = BTreeMap::new();
1408        for transition in self.transitions {
1409            if !nodes.contains_key(transition.source()) {
1410                return Err(PlanError::UndefinedNode {
1411                    node: transition.source().clone(),
1412                });
1413            }
1414            if let FlowTarget::Node(target) = transition.target()
1415                && !nodes.contains_key(target)
1416            {
1417                return Err(PlanError::UndefinedNode {
1418                    node: target.clone(),
1419                });
1420            }
1421            if let FlowTarget::Node(target) = transition.target()
1422                && matches!(nodes.get(target), Some(FlowNode::Join(_)))
1423            {
1424                return Err(PlanError::JoinHasExternalEntry {
1425                    join: target.clone(),
1426                });
1427            }
1428            if matches!(nodes.get(transition.source()), Some(FlowNode::Split(_))) {
1429                return Err(PlanError::SplitHasExplicitTransition {
1430                    split: transition.source().clone(),
1431                });
1432            }
1433            let edges = outgoing.entry(transition.source().clone()).or_default();
1434            if edges.len() == MAX_OUTGOING_TRANSITIONS {
1435                return Err(PlanError::TooManyOutgoingTransitions {
1436                    node: transition.source().clone(),
1437                    max: MAX_OUTGOING_TRANSITIONS,
1438                });
1439            }
1440            edges.push(transition);
1441        }
1442
1443        for (id, node) in &nodes {
1444            if matches!(node, FlowNode::Split(_)) {
1445                continue;
1446            }
1447            let edges = outgoing
1448                .get(id)
1449                .filter(|edges| !edges.is_empty())
1450                .ok_or_else(|| PlanError::MissingTransition { node: id.clone() })?;
1451            check_unambiguous(id, edges)?;
1452        }
1453
1454        let mut compiled: BTreeMap<NodeId, Vec<FlowTransition>> = outgoing;
1455        for edges in compiled.values_mut() {
1456            edges.sort_by(|left, right| {
1457                right
1458                    .pattern()
1459                    .specificity()
1460                    .cmp(&left.pattern().specificity())
1461                    .then_with(|| left.pattern().cmp(right.pattern()))
1462                    .then_with(|| left.target().sort_key().cmp(&right.target().sort_key()))
1463            });
1464        }
1465
1466        check_reachable_and_acyclic(&entry, &nodes, &compiled)?;
1467
1468        let manifest = flow_manifest(job_name, &entry, &nodes, &compiled, local_scale);
1469        let canonical = serde_json::to_vec(&manifest)
1470            .map_err(|_| PlanError::Manifest(DefinitionError::ManifestEncoding))?;
1471        let definition = DefinitionIdentity::from_flow_manifest(job_name, revision, &canonical)
1472            .map_err(PlanError::Manifest)?;
1473        Ok(CompiledExecutionPlan {
1474            definition,
1475            job_restart_policy: RestartPolicy::Restartable,
1476            parameter_incrementer: None,
1477            scoped_components: BTreeMap::new(),
1478            root_scope: CompiledFlowScope::new(entry.clone(), nodes.keys().cloned().collect()),
1479            entry,
1480            nodes,
1481            transitions: compiled,
1482            split_branch_scopes: BTreeMap::new(),
1483            nested_scopes: BTreeMap::new(),
1484            decision_sequences: BTreeMap::new(),
1485        })
1486    }
1487}
1488
1489fn check_local_scale_subset(
1490    entry: &NodeId,
1491    nodes: &BTreeMap<NodeId, FlowNode>,
1492) -> Result<bool, PlanError> {
1493    let mut embedded_ids = BTreeSet::new();
1494    let mut join_owners: BTreeMap<NodeId, NodeId> = BTreeMap::new();
1495    let mut local_scale = false;
1496    for (id, node) in nodes {
1497        match node {
1498            FlowNode::Split(split) => {
1499                local_scale = true;
1500                if id == entry {
1501                    return Err(PlanError::SplitIsEntry { split: id.clone() });
1502                }
1503                if !(2..=MAX_SPLIT_BRANCHES).contains(&split.branches().len()) {
1504                    return Err(PlanError::InvalidSplitBranchCount {
1505                        split: id.clone(),
1506                        min: 2,
1507                        max: MAX_SPLIT_BRANCHES,
1508                    });
1509                }
1510                if usize::from(split.budget().max_parallel_branches()) > split.branches().len() {
1511                    return Err(PlanError::ParallelBudgetExceedsBranches {
1512                        split: id.clone(),
1513                        branches: split.branches().len(),
1514                    });
1515                }
1516                if !matches!(nodes.get(split.join()), Some(FlowNode::Join(_))) {
1517                    return Err(PlanError::InvalidSplitJoin {
1518                        split: id.clone(),
1519                        join: split.join().clone(),
1520                    });
1521                }
1522                if let Some(first) = join_owners.insert(split.join().clone(), id.clone()) {
1523                    return Err(PlanError::JoinHasMultipleOwners {
1524                        join: split.join().clone(),
1525                        first,
1526                        second: id.clone(),
1527                    });
1528                }
1529                for branch in split.branches() {
1530                    if !(1..=MAX_BRANCH_STEPS).contains(&branch.steps().len()) {
1531                        return Err(PlanError::InvalidBranchLength {
1532                            split: id.clone(),
1533                            max: MAX_BRANCH_STEPS,
1534                        });
1535                    }
1536                    for step in branch.steps() {
1537                        if nodes.contains_key(step.id()) || !embedded_ids.insert(step.id().clone())
1538                        {
1539                            return Err(PlanError::DuplicateNodeId {
1540                                node: step.id().clone(),
1541                            });
1542                        }
1543                    }
1544                }
1545            }
1546            FlowNode::Join(_) => {
1547                local_scale = true;
1548            }
1549            FlowNode::PartitionedStep(partitioned) => {
1550                local_scale = true;
1551                let worker = partitioned.worker().id();
1552                if nodes.contains_key(worker) || !embedded_ids.insert(worker.clone()) {
1553                    return Err(PlanError::DuplicateNodeId {
1554                        node: worker.clone(),
1555                    });
1556                }
1557            }
1558            FlowNode::Step(_)
1559            | FlowNode::Decision(_)
1560            | FlowNode::NestedJob(_)
1561            | FlowNode::CustomLeaf(_) => {}
1562        }
1563    }
1564    if nodes.len().saturating_add(embedded_ids.len()) > MAX_NODES {
1565        return Err(PlanError::TooManyNodes { max: MAX_NODES });
1566    }
1567    for (id, node) in nodes {
1568        if matches!(node, FlowNode::Join(_)) && !join_owners.contains_key(id) {
1569            return Err(PlanError::OrphanJoin { join: id.clone() });
1570        }
1571    }
1572    Ok(local_scale)
1573}
1574
1575fn check_unambiguous(node: &NodeId, edges: &[FlowTransition]) -> Result<(), PlanError> {
1576    for (index, left) in edges.iter().enumerate() {
1577        for right in &edges[index + 1..] {
1578            if left.pattern().specificity() == right.pattern().specificity()
1579                && left.pattern().intersects(right.pattern())
1580            {
1581                return Err(PlanError::AmbiguousTransition {
1582                    node: node.clone(),
1583                    first: left.pattern().clone(),
1584                    second: right.pattern().clone(),
1585                });
1586            }
1587        }
1588    }
1589    Ok(())
1590}
1591
1592fn check_reachable_and_acyclic(
1593    entry: &NodeId,
1594    nodes: &BTreeMap<NodeId, FlowNode>,
1595    transitions: &BTreeMap<NodeId, Vec<FlowTransition>>,
1596) -> Result<(), PlanError> {
1597    let mut visited = BTreeSet::new();
1598    let mut on_path = BTreeSet::new();
1599    visit(entry, nodes, transitions, &mut visited, &mut on_path)?;
1600    for id in nodes.keys() {
1601        if !visited.contains(id) {
1602            return Err(PlanError::UnreachableNode { node: id.clone() });
1603        }
1604    }
1605    Ok(())
1606}
1607
1608fn visit(
1609    node: &NodeId,
1610    nodes: &BTreeMap<NodeId, FlowNode>,
1611    transitions: &BTreeMap<NodeId, Vec<FlowTransition>>,
1612    visited: &mut BTreeSet<NodeId>,
1613    on_path: &mut BTreeSet<NodeId>,
1614) -> Result<(), PlanError> {
1615    if on_path.contains(node) {
1616        return Err(PlanError::CyclicGraph { node: node.clone() });
1617    }
1618    if !visited.insert(node.clone()) {
1619        return Ok(());
1620    }
1621    on_path.insert(node.clone());
1622    if let Some(FlowNode::Split(split)) = nodes.get(node) {
1623        visit(split.join(), nodes, transitions, visited, on_path)?;
1624    }
1625    if let Some(edges) = transitions.get(node) {
1626        for edge in edges {
1627            if let FlowTarget::Node(target) = edge.target() {
1628                visit(target, nodes, transitions, visited, on_path)?;
1629            }
1630        }
1631    }
1632    on_path.remove(node);
1633    Ok(())
1634}
1635
1636/// Projects restart-relevant start controls into their manifest member.
1637///
1638/// The projection lives here rather than on the value because the canonical
1639/// manifest is this crate's contract. Keeping it here is also what keeps the
1640/// serializer out of the core's public signatures, and out of the facade that
1641/// re-exports them.
1642fn start_controls_manifest(controls: StartControls) -> Value {
1643    let mut value = json!({
1644        "allow_start_if_complete": controls.allow_start_if_complete(),
1645        "start_limit": controls.start_limit().get()
1646    });
1647    if controls.restart_policy() == RestartPolicy::NotRestartable
1648        && let Some(object) = value.as_object_mut()
1649    {
1650        object.insert(
1651            "restart_policy".to_owned(),
1652            Value::String("not_restartable".to_owned()),
1653        );
1654    }
1655    value
1656}
1657
1658/// Projects one transition target into its manifest member.
1659fn flow_target_manifest(target: &FlowTarget) -> Value {
1660    match target {
1661        FlowTarget::Node(id) => json!({ "node": id.as_str() }),
1662        FlowTarget::Terminal(kind) => json!({ "terminal": kind.as_str() }),
1663    }
1664}
1665
1666/// Projects the restart-relevant chunk declaration into manifest members.
1667///
1668/// `in_flight_policy` is present only when it is the non-default rollback
1669/// policy, because format 1 recorded nothing for the default and the two
1670/// formats must agree on what a chunk declaration means.
1671fn chunk_declaration_manifest(revisions: &ChunkComponentRevisions) -> Value {
1672    let mut value = json!({
1673        "checkpoint": {
1674            "schema": revisions.checkpoint_schema().as_str(),
1675            "version": revisions.checkpoint_schema_version().get()
1676        },
1677        "components": {
1678            "checkpoint": revisions.checkpoint().as_str(),
1679            "processor": revisions.processor().as_str(),
1680            "reader": revisions.reader().as_str(),
1681            "writer": revisions.writer().as_str()
1682        },
1683        "context": {
1684            "schema": revisions.context_schema().as_str(),
1685            "version": revisions.context_schema_version().get()
1686        },
1687        "delivery_mode": revisions.delivery_mode().manifest_name()
1688    });
1689    if revisions.in_flight_policy() == InFlightPolicy::RollbackChunk
1690        && let Some(object) = value.as_object_mut()
1691    {
1692        object.insert(
1693            "in_flight_policy".to_owned(),
1694            Value::String("rollback_chunk".to_owned()),
1695        );
1696    }
1697    value
1698}
1699
1700fn fault_manifest_value(policy: &FaultPolicy) -> Value {
1701    let backoff = policy.backoff();
1702    let rules: Vec<Value> = policy
1703        .classifier()
1704        .rules()
1705        .iter()
1706        .map(|rule| {
1707            json!({
1708                "category": rule.category().as_str(),
1709                "phase": rule.phase().as_str(),
1710                "retryable": rule.action().is_retryable(),
1711                "skip": rule
1712                    .action()
1713                    .skip_disposition()
1714                    .map_or(Value::Null, |skip| Value::String(skip.as_str().to_owned()))
1715            })
1716        })
1717        .collect();
1718    json!({
1719        "backoff": {
1720            "initial_ms": u64::try_from(backoff.initial().as_millis()).unwrap_or(u64::MAX),
1721            "kind": backoff.kind().as_str(),
1722            "maximum_ms": u64::try_from(backoff.maximum().as_millis()).unwrap_or(u64::MAX),
1723            "multiplier": backoff.multiplier()
1724        },
1725        "classifier": {
1726            "revision": policy.classifier().revision().as_str(),
1727            "rules": rules
1728        },
1729        "retry_limit": policy.retry_limit().get(),
1730        "retry_state_limit": policy.retry_state_limit().get(),
1731        "skip_limit": policy.skip_limit().get()
1732    })
1733}
1734
1735/// Projects the compiled graph into its canonical restart-relevant manifest.
1736///
1737/// The projection carries exactly the values that select or reinterpret durable
1738/// state. Framework capacity bounds are deliberately absent: they belong to the
1739/// runtime that reads a manifest, not to the definition it identifies, so
1740/// raising one in a later release must not change a fingerprint. `MAX_NODES`
1741/// and `MAX_TRANSITIONS` are enforced against the graph a manifest declares by
1742/// [`DefinitionManifest::read`](oxide_batch_core::DefinitionManifest::read).
1743fn flow_manifest(
1744    job_name: &JobName,
1745    entry: &NodeId,
1746    nodes: &BTreeMap<NodeId, FlowNode>,
1747    transitions: &BTreeMap<NodeId, Vec<FlowTransition>>,
1748    local_scale: bool,
1749) -> Value {
1750    let node_values: Vec<Value> = nodes.values().map(FlowNode::manifest_value).collect();
1751    let transition_values: Vec<Value> = transitions
1752        .values()
1753        .flat_map(|edges| edges.iter().map(FlowTransition::manifest_value))
1754        .collect();
1755    json!({
1756        "entry": entry.as_str(),
1757        "format": if local_scale {
1758            oxide_batch_core::MANIFEST_FORMAT_LOCAL_SCALE
1759        } else {
1760            oxide_batch_core::MANIFEST_FORMAT_FLOW
1761        },
1762        "job": job_name.as_str(),
1763        "nodes": node_values,
1764        "transitions": transition_values
1765    })
1766}
1767
1768/// A validated, immutable execution plan.
1769///
1770/// A plan owns the exact canonical manifest and fingerprint that identify the
1771/// definition across restart. A plan lowered from a one-step wrapper retains
1772/// that wrapper's original format-1 manifest bytes instead of emitting new
1773/// ones, so lowering never changes a persisted identity.
1774#[derive(Clone, Debug, Eq, PartialEq)]
1775pub struct CompiledExecutionPlan {
1776    definition: DefinitionIdentity,
1777    job_restart_policy: RestartPolicy,
1778    parameter_incrementer: Option<ParameterIncrementerIdentity>,
1779    scoped_components: BTreeMap<(ScopeKind, ScopedComponentId), ScopedComponentDefinition>,
1780    entry: NodeId,
1781    root_scope: CompiledFlowScope,
1782    nodes: BTreeMap<NodeId, FlowNode>,
1783    transitions: BTreeMap<NodeId, Vec<FlowTransition>>,
1784    split_branch_scopes: BTreeMap<(NodeId, usize), CompiledFlowScope>,
1785    nested_scopes: BTreeMap<NodeId, CompiledFlowScope>,
1786    decision_sequences: BTreeMap<NodeId, u64>,
1787}
1788
1789impl CompiledExecutionPlan {
1790    /// Lowers one validated wrapper step into an in-memory compatibility plan.
1791    ///
1792    /// The plan reuses `definition` unchanged, so its manifest bytes, format,
1793    /// and fingerprint stay exactly what the wrapper persisted. The synthetic
1794    /// graph maps the framework's own exit codes onto terminals and adds no
1795    /// node an application could observe as a new durable decision.
1796    #[doc(hidden)]
1797    pub fn compatibility_one_step(
1798        definition: DefinitionIdentity,
1799        step: StepNode,
1800    ) -> Result<Self, PlanError> {
1801        let entry = step.id().clone();
1802        let mut nodes = BTreeMap::new();
1803        nodes.insert(entry.clone(), FlowNode::step(step));
1804        let mut edges = Vec::with_capacity(3);
1805        for (code, terminal) in [
1806            ("COMPLETED", TerminalKind::Complete),
1807            ("FAILED", TerminalKind::Fail),
1808            ("STOPPED", TerminalKind::Stop),
1809        ] {
1810            edges.push(FlowTransition::new(
1811                entry.clone(),
1812                ExitPattern::new(code)?,
1813                FlowTarget::Terminal(terminal),
1814            ));
1815        }
1816        check_unambiguous(&entry, &edges)?;
1817        let mut transitions = BTreeMap::new();
1818        transitions.insert(entry.clone(), edges);
1819        Ok(Self {
1820            definition,
1821            job_restart_policy: RestartPolicy::Restartable,
1822            parameter_incrementer: None,
1823            scoped_components: BTreeMap::new(),
1824            root_scope: CompiledFlowScope::new(entry.clone(), nodes.keys().cloned().collect()),
1825            entry,
1826            nodes,
1827            transitions,
1828            split_branch_scopes: BTreeMap::new(),
1829            nested_scopes: BTreeMap::new(),
1830            decision_sequences: BTreeMap::new(),
1831        })
1832    }
1833
1834    /// Borrows the restart-relevant definition identity.
1835    #[must_use]
1836    pub const fn definition_identity(&self) -> &DefinitionIdentity {
1837        &self.definition
1838    }
1839
1840    /// Returns the execution-definition restart policy for this job.
1841    #[must_use]
1842    pub const fn job_restart_policy(&self) -> RestartPolicy {
1843        self.job_restart_policy
1844    }
1845
1846    /// Borrows the restart-relevant parameter-incrementer identity, when declared.
1847    #[must_use]
1848    pub const fn parameter_incrementer_identity(&self) -> Option<&ParameterIncrementerIdentity> {
1849        self.parameter_incrementer.as_ref()
1850    }
1851
1852    /// Iterates scoped component definitions in canonical scope/ID order.
1853    #[must_use]
1854    pub fn scoped_components(&self) -> impl ExactSizeIterator<Item = &ScopedComponentDefinition> {
1855        self.scoped_components.values()
1856    }
1857
1858    /// Borrows one scoped component definition by scope and logical ID.
1859    #[must_use]
1860    pub fn scoped_component(
1861        &self,
1862        scope: ScopeKind,
1863        id: &ScopedComponentId,
1864    ) -> Option<&ScopedComponentDefinition> {
1865        self.scoped_components.get(&(scope, id.clone()))
1866    }
1867
1868    /// Returns the canonical manifest format this plan is identified by.
1869    #[must_use]
1870    pub const fn manifest_format(&self) -> u16 {
1871        self.definition.manifest_format()
1872    }
1873
1874    /// Returns the SHA-256 definition fingerprint.
1875    #[must_use]
1876    pub const fn fingerprint(&self) -> &[u8; 32] {
1877        self.definition.manifest_digest()
1878    }
1879
1880    /// Borrows the entry node identifier.
1881    #[must_use]
1882    pub const fn entry(&self) -> &NodeId {
1883        &self.entry
1884    }
1885
1886    /// Borrows the root execution scope.
1887    #[must_use]
1888    pub const fn root_scope(&self) -> &CompiledFlowScope {
1889        &self.root_scope
1890    }
1891
1892    /// Borrows one M7 split-branch execution scope by zero-based branch ordinal.
1893    #[must_use]
1894    pub fn split_branch_scope(&self, split: &NodeId, ordinal: usize) -> Option<&CompiledFlowScope> {
1895        self.split_branch_scopes.get(&(split.clone(), ordinal))
1896    }
1897
1898    /// Borrows one flattened nested-flow scope by structural owner ID.
1899    #[must_use]
1900    pub fn nested_scope(&self, owner: &NodeId) -> Option<&CompiledFlowScope> {
1901        self.nested_scopes.get(owner)
1902    }
1903
1904    /// Returns the canonical format-4 decision sequence for one transition source.
1905    ///
1906    /// Formats 1-3 return `None` and retain their historical append sequence.
1907    #[must_use]
1908    pub fn decision_sequence(&self, source: &NodeId) -> Option<u64> {
1909        self.decision_sequences.get(source).copied()
1910    }
1911
1912    /// Returns the compiled node count.
1913    #[must_use]
1914    pub fn node_count(&self) -> usize {
1915        self.nodes.len()
1916    }
1917
1918    /// Returns the compiled transition count.
1919    #[must_use]
1920    pub fn transition_count(&self) -> usize {
1921        self.transitions.values().map(Vec::len).sum()
1922    }
1923
1924    /// Borrows one compiled node.
1925    #[must_use]
1926    pub fn node(&self, id: &NodeId) -> Option<&FlowNode> {
1927        self.nodes.get(id)
1928    }
1929
1930    /// Iterates over compiled nodes in stable logical-identifier order.
1931    ///
1932    /// The returned order is canonical and independent of builder declaration
1933    /// order. It is useful when binding executable components to an immutable
1934    /// plan before launch.
1935    #[must_use]
1936    pub fn nodes(&self) -> impl ExactSizeIterator<Item = (&NodeId, &FlowNode)> {
1937        self.nodes.iter()
1938    }
1939
1940    /// Borrows one node's transitions in evaluation order.
1941    ///
1942    /// The first matching transition wins, so the slice is ordered from the
1943    /// most specific pattern to the least specific one.
1944    #[must_use]
1945    pub fn transitions(&self, id: &NodeId) -> &[FlowTransition] {
1946        self.transitions.get(id).map_or(&[], Vec::as_slice)
1947    }
1948
1949    /// Selects the target one node's exit outcome reaches.
1950    ///
1951    /// # Errors
1952    ///
1953    /// Returns [`FlowSelectionError::UnknownNode`] when `id` is not compiled
1954    /// into this plan and [`FlowSelectionError::UnmappedExitOutcome`] when no
1955    /// declared pattern matches `code`. The plan never selects an arbitrary
1956    /// default.
1957    pub fn select_target(
1958        &self,
1959        id: &NodeId,
1960        code: &ExitCode,
1961    ) -> Result<&FlowTarget, FlowSelectionError> {
1962        let edges = self
1963            .transitions
1964            .get(id)
1965            .ok_or_else(|| FlowSelectionError::UnknownNode { node: id.clone() })?;
1966        edges
1967            .iter()
1968            .find(|edge| edge.pattern().matches(code))
1969            .map(FlowTransition::target)
1970            .ok_or_else(|| FlowSelectionError::UnmappedExitOutcome {
1971                node: id.clone(),
1972                code: code.clone(),
1973            })
1974    }
1975}
1976
1977/// A flow graph that cannot be compiled into an executable plan.
1978#[derive(Clone, Debug, Eq, PartialEq)]
1979#[non_exhaustive]
1980pub enum PlanError {
1981    /// No entry node was declared.
1982    MissingEntryNode,
1983    /// Two nodes declared the same logical identifier.
1984    DuplicateNodeId {
1985        /// Repeated identifier.
1986        node: NodeId,
1987    },
1988    /// A transition referenced a node the graph does not declare.
1989    UndefinedNode {
1990        /// Missing identifier.
1991        node: NodeId,
1992    },
1993    /// A node declared no outgoing transition.
1994    MissingTransition {
1995        /// Identifier of the node without a transition.
1996        node: NodeId,
1997    },
1998    /// Two equally specific patterns can match one exit outcome.
1999    AmbiguousTransition {
2000        /// Identifier of the node with the ambiguity.
2001        node: NodeId,
2002        /// First conflicting pattern.
2003        first: ExitPattern,
2004        /// Second conflicting pattern.
2005        second: ExitPattern,
2006    },
2007    /// A node cannot be reached from the entry node.
2008    UnreachableNode {
2009        /// Unreachable identifier.
2010        node: NodeId,
2011    },
2012    /// The graph contains a cycle.
2013    CyclicGraph {
2014        /// Identifier revisited on one path.
2015        node: NodeId,
2016    },
2017    /// The graph declared more nodes than M3 accepts.
2018    TooManyNodes {
2019        /// Maximum accepted node count.
2020        max: usize,
2021    },
2022    /// The graph declared more transitions than M3 accepts.
2023    TooManyTransitions {
2024        /// Maximum accepted transition count.
2025        max: usize,
2026    },
2027    /// One node declared more outgoing transitions than M3 accepts.
2028    TooManyOutgoingTransitions {
2029        /// Identifier of the node with too many transitions.
2030        node: NodeId,
2031        /// Maximum accepted outgoing transition count.
2032        max: usize,
2033    },
2034    /// An exit pattern violated its bounded format.
2035    InvalidPattern {
2036        /// Maximum accepted pattern length in UTF-8 bytes.
2037        max_bytes: usize,
2038    },
2039    /// A decision input-contract version of zero is not a version.
2040    ZeroDecisionInputVersion,
2041    /// A split declared fewer than two or more than eight branches.
2042    InvalidSplitBranchCount {
2043        /// Split whose branch count was invalid.
2044        split: NodeId,
2045        /// Minimum accepted branch count.
2046        min: usize,
2047        /// Maximum accepted branch count.
2048        max: usize,
2049    },
2050    /// A split branch was empty or longer than the accepted bound.
2051    InvalidBranchLength {
2052        /// Owning split.
2053        split: NodeId,
2054        /// Maximum accepted branch length.
2055        max: usize,
2056    },
2057    /// A split was declared as the graph entry.
2058    SplitIsEntry {
2059        /// Rejected split.
2060        split: NodeId,
2061    },
2062    /// A split did not reference a declared structural join.
2063    InvalidSplitJoin {
2064        /// Owning split.
2065        split: NodeId,
2066        /// Missing or wrongly typed join.
2067        join: NodeId,
2068    },
2069    /// More than one split tried to own the same join.
2070    JoinHasMultipleOwners {
2071        /// Multiply owned join.
2072        join: NodeId,
2073        /// First owning split.
2074        first: NodeId,
2075        /// Second owning split.
2076        second: NodeId,
2077    },
2078    /// A join was not owned by any split.
2079    OrphanJoin {
2080        /// Unowned join.
2081        join: NodeId,
2082    },
2083    /// A normal transition attempted to enter a structural join.
2084    JoinHasExternalEntry {
2085        /// Join with an external incoming edge.
2086        join: NodeId,
2087    },
2088    /// A split tried to bypass its implicit join edge.
2089    SplitHasExplicitTransition {
2090        /// Split with the explicit edge.
2091        split: NodeId,
2092    },
2093    /// The branch concurrency budget exceeded the declared branch count.
2094    ParallelBudgetExceedsBranches {
2095        /// Split with the contradictory budget.
2096        split: NodeId,
2097        /// Declared branch count.
2098        branches: usize,
2099    },
2100    /// A branch concurrency budget was zero or above the M4 ceiling.
2101    InvalidParallelBranchBudget {
2102        /// Maximum accepted branch concurrency.
2103        max: usize,
2104    },
2105    /// A partition-worker budget was zero or above the M4 ceiling.
2106    InvalidPartitionWorkerBudget {
2107        /// Maximum accepted worker concurrency.
2108        max: u8,
2109    },
2110    /// The declared pool cannot supply active children plus their parent.
2111    InsufficientPoolCapacity {
2112        /// Minimum required connection count.
2113        required: u32,
2114        /// Declared connection count.
2115        configured: u32,
2116    },
2117    /// A durable partition count was zero or above the M4 ceiling.
2118    InvalidPartitionCount {
2119        /// Maximum accepted partition count.
2120        max: u16,
2121    },
2122    /// M7 composition exceeded the bounded structural nesting depth.
2123    CompositionDepthExceeded {
2124        /// Maximum accepted composition depth.
2125        max: usize,
2126    },
2127    /// A nested-flow terminal class had no owner transition.
2128    UnmappedNestedFlowExit {
2129        /// Structural nested-flow owner.
2130        flow: NodeId,
2131        /// Normalized terminal outcome that could not be routed.
2132        code: ExitCode,
2133    },
2134    /// A structured selector path exceeded its closed bounded shape.
2135    InvalidSelectorPath {
2136        /// Maximum accepted encoded path bytes.
2137        max_bytes: usize,
2138        /// Maximum accepted segment count.
2139        max_segments: usize,
2140    },
2141    /// A nested-job child definition had no bound job identity.
2142    NestedJobMissingChildIdentity {
2143        /// Nested-job node with the unbound child.
2144        node: NodeId,
2145    },
2146    /// A graph declared more scoped components than the M7 ceiling.
2147    TooManyScopedComponents {
2148        /// Maximum accepted scoped component count.
2149        max: usize,
2150    },
2151    /// Two declarations reused one scope/component logical identity.
2152    DuplicateScopedComponent {
2153        /// Repeated scope.
2154        scope: ScopeKind,
2155        /// Repeated logical component identifier.
2156        component: ScopedComponentId,
2157    },
2158    /// Two repeat declarations reused one logical repeat identity.
2159    DuplicateRepeatId {
2160        /// Repeated repeat identity.
2161        repeat: RepeatId,
2162    },
2163    /// A nested job declared more child parameters than the M7 ceiling.
2164    TooManyNestedJobParameters {
2165        /// Nested-job node over the limit.
2166        node: NodeId,
2167        /// Maximum accepted mapping count.
2168        max: usize,
2169    },
2170    /// Two mappings targeted the same child parameter.
2171    DuplicateNestedJobParameter {
2172        /// Nested-job node with the duplicate target.
2173        node: NodeId,
2174        /// Repeated child parameter name.
2175        parameter: ParameterName,
2176    },
2177    /// A logical identifier or revision token was invalid.
2178    Token(DefinitionError),
2179    /// The canonical manifest could not be encoded within its bound.
2180    Manifest(DefinitionError),
2181}
2182
2183impl fmt::Display for PlanError {
2184    #[allow(
2185        clippy::too_many_lines,
2186        reason = "each typed plan rejection retains one stable redacted diagnostic"
2187    )]
2188    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2189        match self {
2190            Self::MissingEntryNode => formatter.write_str("flow graph has no entry node"),
2191            Self::DuplicateNodeId { node } => {
2192                write!(
2193                    formatter,
2194                    "node {} is declared more than once",
2195                    node.as_str()
2196                )
2197            }
2198            Self::UndefinedNode { node } => {
2199                write!(formatter, "node {} is not declared", node.as_str())
2200            }
2201            Self::MissingTransition { node } => {
2202                write!(
2203                    formatter,
2204                    "node {} has no outgoing transition",
2205                    node.as_str()
2206                )
2207            }
2208            Self::AmbiguousTransition {
2209                node,
2210                first,
2211                second,
2212            } => write!(
2213                formatter,
2214                "node {} patterns {first} and {second} are equally specific and overlap",
2215                node.as_str()
2216            ),
2217            Self::UnreachableNode { node } => {
2218                write!(
2219                    formatter,
2220                    "node {} is unreachable from the entry node",
2221                    node.as_str()
2222                )
2223            }
2224            Self::CyclicGraph { node } => {
2225                write!(formatter, "node {} closes a cycle", node.as_str())
2226            }
2227            Self::TooManyNodes { max } => write!(formatter, "flow graph exceeds {max} nodes"),
2228            Self::TooManyTransitions { max } => {
2229                write!(formatter, "flow graph exceeds {max} transitions")
2230            }
2231            Self::TooManyOutgoingTransitions { node, max } => write!(
2232                formatter,
2233                "node {} exceeds {max} outgoing transitions",
2234                node.as_str()
2235            ),
2236            Self::InvalidPattern { max_bytes } => write!(
2237                formatter,
2238                "exit pattern must be 1 to {max_bytes} bytes without control characters"
2239            ),
2240            Self::ZeroDecisionInputVersion => {
2241                formatter.write_str("decision input version must be nonzero")
2242            }
2243            Self::InvalidSplitBranchCount { split, min, max } => write!(
2244                formatter,
2245                "split {} must declare {min} to {max} branches",
2246                split.as_str()
2247            ),
2248            Self::InvalidBranchLength { split, max } => write!(
2249                formatter,
2250                "split {} branches must declare 1 to {max} steps",
2251                split.as_str()
2252            ),
2253            Self::SplitIsEntry { split } => {
2254                write!(
2255                    formatter,
2256                    "split {} cannot be the entry node",
2257                    split.as_str()
2258                )
2259            }
2260            Self::InvalidSplitJoin { split, join } => write!(
2261                formatter,
2262                "split {} does not own declared join {}",
2263                split.as_str(),
2264                join.as_str()
2265            ),
2266            Self::JoinHasMultipleOwners {
2267                join,
2268                first,
2269                second,
2270            } => write!(
2271                formatter,
2272                "join {} is owned by both splits {} and {}",
2273                join.as_str(),
2274                first.as_str(),
2275                second.as_str()
2276            ),
2277            Self::OrphanJoin { join } => {
2278                write!(formatter, "join {} has no owning split", join.as_str())
2279            }
2280            Self::JoinHasExternalEntry { join } => write!(
2281                formatter,
2282                "join {} can be entered only by its owning split",
2283                join.as_str()
2284            ),
2285            Self::SplitHasExplicitTransition { split } => write!(
2286                formatter,
2287                "split {} reaches only its declared join",
2288                split.as_str()
2289            ),
2290            Self::ParallelBudgetExceedsBranches { split, branches } => write!(
2291                formatter,
2292                "split {} parallel budget exceeds its {branches} branches",
2293                split.as_str()
2294            ),
2295            Self::InvalidParallelBranchBudget { max } => {
2296                write!(formatter, "parallel branch budget must be 1 to {max}")
2297            }
2298            Self::InvalidPartitionWorkerBudget { max } => {
2299                write!(formatter, "partition worker budget must be 1 to {max}")
2300            }
2301            Self::InsufficientPoolCapacity {
2302                required,
2303                configured,
2304            } => write!(
2305                formatter,
2306                "repository pool size {configured} cannot supply required capacity {required}"
2307            ),
2308            Self::InvalidPartitionCount { max } => {
2309                write!(formatter, "partition count must be 1 to {max}")
2310            }
2311            Self::CompositionDepthExceeded { max } => {
2312                write!(formatter, "flow composition exceeds depth {max}")
2313            }
2314            Self::InvalidSelectorPath {
2315                max_bytes,
2316                max_segments,
2317            } => write!(
2318                formatter,
2319                "selector path must contain 1 to {max_segments} bounded segments within {max_bytes} bytes"
2320            ),
2321            Self::NestedJobMissingChildIdentity { node } => write!(
2322                formatter,
2323                "nested job {} requires a bound child definition identity",
2324                node.as_str()
2325            ),
2326            Self::TooManyScopedComponents { max } => {
2327                write!(formatter, "flow graph exceeds {max} scoped components")
2328            }
2329            Self::DuplicateScopedComponent { scope, component } => write!(
2330                formatter,
2331                "{} scope component {} is declared more than once",
2332                scope.as_str(),
2333                component.as_str()
2334            ),
2335            Self::DuplicateRepeatId { repeat } => write!(
2336                formatter,
2337                "repeat {} is declared more than once in the compiled plan",
2338                repeat.as_str()
2339            ),
2340            Self::TooManyNestedJobParameters { node, max } => write!(
2341                formatter,
2342                "nested job {} exceeds {max} child parameters",
2343                node.as_str()
2344            ),
2345            Self::DuplicateNestedJobParameter { node, parameter } => write!(
2346                formatter,
2347                "nested job {} maps child parameter {} more than once",
2348                node.as_str(),
2349                parameter.as_str()
2350            ),
2351            Self::UnmappedNestedFlowExit { flow, code } => write!(
2352                formatter,
2353                "nested flow {} declares no transition for terminal outcome {code}",
2354                flow.as_str()
2355            ),
2356            Self::Token(error) => write!(formatter, "flow graph token is invalid: {error}"),
2357            Self::Manifest(error) => {
2358                write!(formatter, "flow manifest could not be encoded: {error}")
2359            }
2360        }
2361    }
2362}
2363
2364impl Error for PlanError {
2365    fn source(&self) -> Option<&(dyn Error + 'static)> {
2366        match self {
2367            Self::Token(error) | Self::Manifest(error) => Some(error),
2368            _ => None,
2369        }
2370    }
2371}
2372
2373impl From<DefinitionError> for PlanError {
2374    fn from(error: DefinitionError) -> Self {
2375        Self::Token(error)
2376    }
2377}
2378
2379/// A compiled plan that cannot route one observed exit outcome.
2380#[derive(Clone, Debug, Eq, PartialEq)]
2381#[non_exhaustive]
2382pub enum FlowSelectionError {
2383    /// The requested node is not part of this plan.
2384    UnknownNode {
2385        /// Requested identifier.
2386        node: NodeId,
2387    },
2388    /// No declared pattern matches the produced exit outcome.
2389    UnmappedExitOutcome {
2390        /// Node whose outcome could not be routed.
2391        node: NodeId,
2392        /// Produced exit code.
2393        code: ExitCode,
2394    },
2395}
2396
2397impl fmt::Display for FlowSelectionError {
2398    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2399        match self {
2400            Self::UnknownNode { node } => {
2401                write!(
2402                    formatter,
2403                    "node {} is not part of the compiled plan",
2404                    node.as_str()
2405                )
2406            }
2407            Self::UnmappedExitOutcome { node, code } => write!(
2408                formatter,
2409                "node {} declares no transition for exit outcome {code}",
2410                node.as_str()
2411            ),
2412        }
2413    }
2414}
2415
2416impl Error for FlowSelectionError {}