Skip to main content

oxide_batch_core/
definition.rs

1//! Restart-relevant job-definition identity.
2
3use std::collections::{BTreeMap, BTreeSet};
4use std::error::Error;
5use std::fmt;
6
7use serde_json::json;
8use sha2::{Digest, Sha256};
9
10use crate::{ChunkSize, JobName, NodeId, StateSchemaId, StateSchemaVersion, StepName};
11
12const MAX_TOKEN_BYTES: usize = 128;
13/// The maximum number of nodes one plan may contain.
14///
15/// The bound is a framework capability rather than durable meaning: the
16/// manifest reader enforces the ceiling of the running build, and raising it
17/// in a later release must not change a fingerprint.
18pub const MAX_NODES: usize = 1_024;
19/// The maximum number of transitions one plan may contain.
20///
21/// The bound is a framework capability, on the same terms as [`MAX_NODES`].
22pub const MAX_TRANSITIONS: usize = 4_096;
23/// Maximum interceptors declared by one M7 repeat definition.
24///
25/// This capacity ceiling is not definition-fingerprint material.
26pub const MAX_REPEAT_INTERCEPTORS: usize = 32;
27/// Maximum nested M7 repeat-wrapper depth.
28///
29/// This capacity ceiling is not definition-fingerprint material.
30pub const MAX_REPEAT_NESTING_DEPTH: usize = 8;
31/// Maximum durable source nodes one compatible-upgrade edge may map.
32pub const MAX_DEFINITION_UPGRADE_NODES: usize = MAX_NODES;
33/// Maximum state-transform declarations one compatible-upgrade edge may carry.
34pub const MAX_DEFINITION_UPGRADE_TRANSFORMS: usize = MAX_TRANSITIONS;
35pub(crate) const MAX_MANIFEST_BYTES: usize = 64 * 1024;
36/// The canonical manifest format for a one-step tasklet or chunk definition.
37pub const MANIFEST_FORMAT_ONE_STEP: u16 = 1;
38/// The canonical manifest format that captures a compiled flow graph.
39pub const MANIFEST_FORMAT_FLOW: u16 = 2;
40/// The canonical manifest format for bounded M4 local-scale plans.
41pub const MANIFEST_FORMAT_LOCAL_SCALE: u16 = 3;
42/// The canonical manifest format for bounded M7 composed flows, including
43/// additive scoped-component definition identity.
44pub const MANIFEST_FORMAT_ADVANCED_FLOW: u16 = 4;
45/// The newest canonical manifest format this runtime can interpret.
46pub(crate) const SUPPORTED_MANIFEST_FORMAT: u16 = MANIFEST_FORMAT_ADVANCED_FLOW;
47const LEGACY_REVISION: &str = "__m1_repository_port_v1";
48const LEGACY_MANIFEST: &[u8] =
49    br#"{"format":1,"repository_port":"m1","revision":"__m1_repository_port_v1"}"#;
50
51/// Validates one application-owned definition token.
52///
53/// # Errors
54///
55/// Rejects empty values, values longer than 128 UTF-8 bytes, surrounding
56/// whitespace, and control characters.
57pub fn validate_token(value: &str, kind: DefinitionTokenKind) -> Result<(), DefinitionError> {
58    if value.is_empty() {
59        return Err(DefinitionError::EmptyToken { kind });
60    }
61    if value.len() > MAX_TOKEN_BYTES {
62        return Err(DefinitionError::TokenTooLong {
63            kind,
64            max_bytes: MAX_TOKEN_BYTES,
65        });
66    }
67    if value.trim() != value {
68        return Err(DefinitionError::SurroundingWhitespace { kind });
69    }
70    if value.chars().any(char::is_control) {
71        return Err(DefinitionError::ControlCharacter { kind });
72    }
73    Ok(())
74}
75
76/// Declares one validated, application-owned definition token type.
77///
78/// The generated constructor calls [`validate_token`] and returns
79/// [`DefinitionError`], both of which must be in scope where the macro is
80/// invoked.
81#[macro_export]
82macro_rules! definition_token {
83    ($name:ident, $kind:expr, $docs:literal) => {
84        #[doc = $docs]
85        #[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
86        pub struct $name(String);
87
88        impl $name {
89            /// Validates and constructs the token.
90            ///
91            /// # Errors
92            ///
93            /// Rejects empty values, values longer than 128 UTF-8 bytes,
94            /// surrounding whitespace, and control characters.
95            pub fn new(value: impl Into<String>) -> Result<Self, DefinitionError> {
96                let value = value.into();
97                validate_token(&value, $kind)?;
98                Ok(Self(value))
99            }
100
101            /// Borrows the validated token.
102            #[must_use]
103            pub fn as_str(&self) -> &str {
104                &self.0
105            }
106        }
107    };
108}
109
110definition_token!(
111    DefinitionRevision,
112    DefinitionTokenKind::Revision,
113    "An application-owned audit label for one restart-relevant definition."
114);
115
116/// Restart-relevant identity of one deterministic parameter incrementer.
117///
118/// The executable callback remains process-local. Only its reviewed kind and
119/// revision enter a format-4 definition fingerprint.
120#[derive(Clone, Debug, Eq, PartialEq)]
121pub struct ParameterIncrementerIdentity {
122    kind: DefinitionRevision,
123    revision: DefinitionRevision,
124}
125
126impl ParameterIncrementerIdentity {
127    /// Constructs an identity from already validated definition tokens.
128    #[must_use]
129    pub const fn new(kind: DefinitionRevision, revision: DefinitionRevision) -> Self {
130        Self { kind, revision }
131    }
132
133    /// Borrows the reviewed incrementer kind.
134    #[must_use]
135    pub const fn kind(&self) -> &DefinitionRevision {
136        &self.kind
137    }
138
139    /// Borrows the reviewed implementation revision.
140    #[must_use]
141    pub const fn revision(&self) -> &DefinitionRevision {
142        &self.revision
143    }
144}
145definition_token!(
146    DefinitionArtifactId,
147    DefinitionTokenKind::Artifact,
148    "A bounded application-owned identity for the executable artifact that assembles one definition."
149);
150definition_token!(
151    DefinitionUpgradeKey,
152    DefinitionTokenKind::Upgrade,
153    "An application-owned key for one directed definition compatibility edge."
154);
155definition_token!(
156    DefinitionUpgradeRevision,
157    DefinitionTokenKind::Upgrade,
158    "A bounded application-owned revision for one deterministic compatible-upgrade implementation."
159);
160definition_token!(
161    DefinitionStateTransformId,
162    DefinitionTokenKind::Upgrade,
163    "A stable bounded identity for one durable state family member transformed by a compatible upgrade."
164);
165definition_token!(
166    RepeatId,
167    DefinitionTokenKind::Repeat,
168    "A stable logical identifier for one repeat definition."
169);
170
171/// One source-to-target durable step mapping for a compatible restart.
172#[derive(Clone, Debug, Eq, PartialEq)]
173pub struct StepDefinitionUpgrade {
174    source: StepName,
175    target: StepName,
176}
177
178impl StepDefinitionUpgrade {
179    /// Constructs one directed step mapping.
180    #[must_use]
181    pub const fn new(source: StepName, target: StepName) -> Self {
182        Self { source, target }
183    }
184
185    /// Borrows the checkpoint-producing step name.
186    #[must_use]
187    pub const fn source(&self) -> &StepName {
188        &self.source
189    }
190
191    /// Borrows the step name in the proposed definition.
192    #[must_use]
193    pub const fn target(&self) -> &StepName {
194        &self.target
195    }
196}
197
198/// Durable state family covered by one compatible-upgrade transform.
199#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
200#[non_exhaustive]
201pub enum DefinitionStateKind {
202    /// A committed reader/checkpoint position.
203    Checkpoint,
204    /// Job- or step-owned execution context.
205    ExecutionContext,
206    /// Namespaced component-owned durable state.
207    ComponentState,
208    /// Value-free late-binding/source provenance.
209    ScopeResolution,
210    /// Current committed repeat state and decision.
211    Repeat,
212    /// Durable retry/skip/fault bookkeeping.
213    FaultState,
214}
215
216impl DefinitionStateKind {
217    /// Returns the stable durable encoding for this state family.
218    #[must_use]
219    pub const fn as_str(self) -> &'static str {
220        match self {
221            Self::Checkpoint => "checkpoint",
222            Self::ExecutionContext => "execution-context",
223            Self::ComponentState => "component-state",
224            Self::ScopeResolution => "scope-resolution",
225            Self::Repeat => "repeat",
226            Self::FaultState => "fault-state",
227        }
228    }
229}
230
231/// One durable source-to-target node mapping for a compatible restart.
232#[derive(Clone, Debug, Eq, PartialEq)]
233pub struct DefinitionNodeUpgrade {
234    source: NodeId,
235    target: NodeId,
236}
237
238impl DefinitionNodeUpgrade {
239    /// Constructs one explicit durable-node mapping.
240    #[must_use]
241    pub const fn new(source: NodeId, target: NodeId) -> Self {
242        Self { source, target }
243    }
244
245    /// Borrows the source durable node.
246    #[must_use]
247    pub const fn source(&self) -> &NodeId {
248        &self.source
249    }
250
251    /// Borrows the target durable node.
252    #[must_use]
253    pub const fn target(&self) -> &NodeId {
254        &self.target
255    }
256}
257
258/// Schema contract for one durable state transformation.
259///
260/// The actual pure transformer is runtime-owned and is deliberately absent
261/// from durable metadata.
262#[derive(Clone, Debug, Eq, PartialEq)]
263pub struct DefinitionStateTransform {
264    source_node: NodeId,
265    target_node: NodeId,
266    kind: DefinitionStateKind,
267    state_id: DefinitionStateTransformId,
268    source_schema: StateSchemaId,
269    source_version: StateSchemaVersion,
270    target_schema: StateSchemaId,
271    target_version: StateSchemaVersion,
272    revision: DefinitionUpgradeRevision,
273}
274
275impl DefinitionStateTransform {
276    /// Declares one explicit deterministic state transformation.
277    #[allow(clippy::too_many_arguments)]
278    #[must_use]
279    pub const fn new(
280        source_node: NodeId,
281        target_node: NodeId,
282        kind: DefinitionStateKind,
283        state_id: DefinitionStateTransformId,
284        source_schema: StateSchemaId,
285        source_version: StateSchemaVersion,
286        target_schema: StateSchemaId,
287        target_version: StateSchemaVersion,
288        revision: DefinitionUpgradeRevision,
289    ) -> Self {
290        Self {
291            source_node,
292            target_node,
293            kind,
294            state_id,
295            source_schema,
296            source_version,
297            target_schema,
298            target_version,
299            revision,
300        }
301    }
302
303    /// Borrows the source durable node.
304    #[must_use]
305    pub const fn source_node(&self) -> &NodeId {
306        &self.source_node
307    }
308
309    /// Borrows the target durable node.
310    #[must_use]
311    pub const fn target_node(&self) -> &NodeId {
312        &self.target_node
313    }
314
315    /// Returns the durable state family.
316    #[must_use]
317    pub const fn kind(&self) -> DefinitionStateKind {
318        self.kind
319    }
320
321    /// Borrows the stable identity of the state-family member.
322    #[must_use]
323    pub const fn state_id(&self) -> &DefinitionStateTransformId {
324        &self.state_id
325    }
326
327    /// Borrows the source schema identifier.
328    #[must_use]
329    pub const fn source_schema(&self) -> &StateSchemaId {
330        &self.source_schema
331    }
332
333    /// Returns the source schema version.
334    #[must_use]
335    pub const fn source_version(&self) -> StateSchemaVersion {
336        self.source_version
337    }
338
339    /// Borrows the target schema identifier.
340    #[must_use]
341    pub const fn target_schema(&self) -> &StateSchemaId {
342        &self.target_schema
343    }
344
345    /// Returns the target schema version.
346    #[must_use]
347    pub const fn target_version(&self) -> StateSchemaVersion {
348        self.target_version
349    }
350
351    /// Borrows the deterministic transformer revision.
352    #[must_use]
353    pub const fn revision(&self) -> &DefinitionUpgradeRevision {
354        &self.revision
355    }
356}
357
358/// Process-local implementation of one declared state-transform revision.
359///
360/// The function is deliberately not serializable or durable. Registration
361/// persists only the bounded revision/schema descriptor, while a compatible
362/// restart must supply the exact live implementation again.
363#[derive(Clone)]
364pub struct DefinitionStateTransformer {
365    revision: DefinitionUpgradeRevision,
366    apply: fn(&[u8]) -> Result<Vec<u8>, DefinitionStateTransformError>,
367}
368
369impl DefinitionStateTransformer {
370    /// Binds one deterministic payload transformer to its application revision.
371    #[must_use]
372    pub const fn new(
373        revision: DefinitionUpgradeRevision,
374        apply: fn(&[u8]) -> Result<Vec<u8>, DefinitionStateTransformError>,
375    ) -> Self {
376        Self { revision, apply }
377    }
378
379    /// Borrows the revision this implementation satisfies.
380    #[must_use]
381    pub const fn revision(&self) -> &DefinitionUpgradeRevision {
382        &self.revision
383    }
384
385    /// Applies the process-local pure transform.
386    ///
387    /// # Errors
388    ///
389    /// Returns the application-provided redacted transform failure.
390    pub fn apply(&self, payload: &[u8]) -> Result<Vec<u8>, DefinitionStateTransformError> {
391        (self.apply)(payload)
392    }
393}
394
395impl fmt::Debug for DefinitionStateTransformer {
396    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
397        formatter
398            .debug_struct("DefinitionStateTransformer")
399            .field("revision", &self.revision)
400            .finish_non_exhaustive()
401    }
402}
403
404/// Stable value-redacted failure from a compatible-upgrade transformer.
405#[derive(Clone, Copy, Debug, Eq, PartialEq)]
406#[non_exhaustive]
407pub enum DefinitionStateTransformError {
408    /// Source bytes do not satisfy the transformer's declared contract.
409    InvalidSource,
410    /// The transformer could not produce the declared target state.
411    TransformFailed,
412}
413
414impl fmt::Display for DefinitionStateTransformError {
415    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
416        formatter.write_str(match self {
417            Self::InvalidSource => "definition-upgrade source state is invalid",
418            Self::TransformFailed => "definition-upgrade state transform failed",
419        })
420    }
421}
422
423impl Error for DefinitionStateTransformError {}
424
425/// One explicitly selected compatible-upgrade edge plus its live pure code.
426///
427/// Construction proves that every transform revision declared by the durable
428/// edge has exactly one process-local implementation and that no undeclared
429/// implementation is smuggled into the restart.
430#[derive(Clone, Debug)]
431pub struct DefinitionUpgradeExecution {
432    upgrade: DefinitionUpgrade,
433    transformers: BTreeMap<DefinitionUpgradeRevision, DefinitionStateTransformer>,
434}
435
436impl DefinitionUpgradeExecution {
437    /// Validates one executable transformed edge.
438    ///
439    /// # Errors
440    ///
441    /// Rejects a legacy identity-only edge, duplicate implementations, a
442    /// missing declared transform implementation, or an unused implementation.
443    pub fn new(
444        upgrade: DefinitionUpgrade,
445        transformers: impl IntoIterator<Item = DefinitionStateTransformer>,
446    ) -> Result<Self, DefinitionError> {
447        if !upgrade.is_transformed() {
448            return Err(DefinitionError::LegacyUpgradeExecution);
449        }
450        let mut implementations = BTreeMap::new();
451        for transformer in transformers {
452            if implementations
453                .insert(transformer.revision().clone(), transformer)
454                .is_some()
455            {
456                return Err(DefinitionError::DuplicateStateTransformer);
457            }
458        }
459        let required = upgrade
460            .transforms()
461            .iter()
462            .map(|transform| transform.revision().clone())
463            .collect::<BTreeSet<_>>();
464        let supplied = implementations.keys().cloned().collect::<BTreeSet<_>>();
465        if required != supplied {
466            return Err(DefinitionError::StateTransformerSetMismatch);
467        }
468        Ok(Self {
469            upgrade,
470            transformers: implementations,
471        })
472    }
473
474    /// Borrows the exact durable edge selected by this execution.
475    #[must_use]
476    pub const fn upgrade(&self) -> &DefinitionUpgrade {
477        &self.upgrade
478    }
479
480    /// Resolves the exact implementation declared by one transform descriptor.
481    #[must_use]
482    pub fn transformer(
483        &self,
484        transform: &DefinitionStateTransform,
485    ) -> Option<&DefinitionStateTransformer> {
486        self.transformers.get(transform.revision())
487    }
488}
489
490/// One explicit, directed definition compatibility edge.
491#[derive(Clone, Debug, Eq, PartialEq)]
492pub struct DefinitionUpgrade {
493    key: DefinitionUpgradeKey,
494    revision: Option<DefinitionUpgradeRevision>,
495    from: DefinitionIdentity,
496    to: DefinitionIdentity,
497    step_mapping: BTreeMap<StepName, StepName>,
498    node_mapping: BTreeMap<NodeId, NodeId>,
499    transforms: Vec<DefinitionStateTransform>,
500}
501
502impl DefinitionUpgrade {
503    /// Validates a direct, non-transitive compatibility edge.
504    ///
505    /// The M2 edge preserves checkpoint and context bytes unchanged, so
506    /// applications may use it only when the mapped steps retain the same
507    /// state schemas and semantics.
508    ///
509    /// # Errors
510    ///
511    /// Rejects self-edges, empty mappings, and mappings that reuse a target.
512    pub fn new(
513        key: DefinitionUpgradeKey,
514        from: DefinitionIdentity,
515        to: DefinitionIdentity,
516        steps: impl IntoIterator<Item = StepDefinitionUpgrade>,
517    ) -> Result<Self, DefinitionError> {
518        if from.manifest_digest() == to.manifest_digest() {
519            return Err(DefinitionError::UpgradeSelfEdge);
520        }
521        let mut step_mapping = BTreeMap::new();
522        let mut targets = BTreeSet::new();
523        for step in steps {
524            if step_mapping
525                .insert(step.source().clone(), step.target().clone())
526                .is_some()
527            {
528                return Err(DefinitionError::DuplicateSourceStep);
529            }
530            if !targets.insert(step.target().clone()) {
531                return Err(DefinitionError::DuplicateTargetStep);
532            }
533        }
534        if step_mapping.is_empty() {
535            return Err(DefinitionError::EmptyStepMapping);
536        }
537        Ok(Self {
538            key,
539            revision: None,
540            from,
541            to,
542            step_mapping,
543            node_mapping: BTreeMap::new(),
544            transforms: Vec::new(),
545        })
546    }
547
548    /// Validates the full transformed compatible-upgrade descriptor.
549    ///
550    /// Completeness against the source definition and committed durable state
551    /// is checked by the restart path before lifecycle writes.
552    ///
553    /// # Errors
554    ///
555    /// Rejects self-edges, empty or non-injective node mappings, mappings or
556    /// transform sets beyond their public bounds, duplicate transform
557    /// identities, and transforms outside the declared node mapping.
558    pub fn transformed(
559        key: DefinitionUpgradeKey,
560        revision: DefinitionUpgradeRevision,
561        from: DefinitionIdentity,
562        to: DefinitionIdentity,
563        nodes: impl IntoIterator<Item = DefinitionNodeUpgrade>,
564        transforms: impl IntoIterator<Item = DefinitionStateTransform>,
565    ) -> Result<Self, DefinitionError> {
566        if from.manifest_digest() == to.manifest_digest() {
567            return Err(DefinitionError::UpgradeSelfEdge);
568        }
569
570        let mut node_mapping = BTreeMap::new();
571        let mut targets = BTreeSet::new();
572        for node in nodes {
573            if node_mapping.len() >= MAX_DEFINITION_UPGRADE_NODES {
574                return Err(DefinitionError::TooManyUpgradeNodes {
575                    max: MAX_DEFINITION_UPGRADE_NODES,
576                });
577            }
578            if node_mapping
579                .insert(node.source().clone(), node.target().clone())
580                .is_some()
581            {
582                return Err(DefinitionError::DuplicateSourceNode);
583            }
584            if !targets.insert(node.target().clone()) {
585                return Err(DefinitionError::DuplicateTargetNode);
586            }
587        }
588        if node_mapping.is_empty() {
589            return Err(DefinitionError::EmptyStepMapping);
590        }
591        let source_nodes = definition_upgrade_source_nodes(&from)?;
592        if node_mapping.keys().any(|node| !source_nodes.contains(node)) {
593            return Err(DefinitionError::UnknownUpgradeSourceNode);
594        }
595        if source_nodes
596            .iter()
597            .any(|node| !node_mapping.contains_key(node))
598        {
599            return Err(DefinitionError::MissingUpgradeSourceNode);
600        }
601        let target_nodes = definition_upgrade_source_nodes(&to)?;
602        if node_mapping
603            .values()
604            .any(|node| !target_nodes.contains(node))
605        {
606            return Err(DefinitionError::UnknownUpgradeTargetNode);
607        }
608
609        let transforms = transforms.into_iter().collect::<Vec<_>>();
610        if transforms.len() > MAX_DEFINITION_UPGRADE_TRANSFORMS {
611            return Err(DefinitionError::TooManyUpgradeTransforms {
612                max: MAX_DEFINITION_UPGRADE_TRANSFORMS,
613            });
614        }
615
616        let mut transform_keys = BTreeSet::new();
617        for transform in &transforms {
618            if node_mapping.get(transform.source_node()) != Some(transform.target_node()) {
619                return Err(DefinitionError::StateTransformOutsideNodeMapping);
620            }
621            if !transform_keys.insert((
622                transform.source_node().clone(),
623                transform.kind(),
624                transform.state_id().clone(),
625            )) {
626                return Err(DefinitionError::DuplicateStateTransform);
627            }
628        }
629        validate_required_definition_state_transforms(&from, &to, &node_mapping, &transforms)?;
630
631        Ok(Self {
632            key,
633            revision: Some(revision),
634            from,
635            to,
636            step_mapping: BTreeMap::new(),
637            node_mapping,
638            transforms,
639        })
640    }
641
642    /// Borrows the application-owned upgrade key.
643    #[must_use]
644    pub const fn key(&self) -> &DefinitionUpgradeKey {
645        &self.key
646    }
647
648    /// Borrows the deterministic transformed-edge revision.
649    ///
650    /// None identifies the legacy M2 identity-only edge shape.
651    #[must_use]
652    pub const fn revision(&self) -> Option<&DefinitionUpgradeRevision> {
653        self.revision.as_ref()
654    }
655
656    /// Borrows the checkpoint-producing definition.
657    #[must_use]
658    pub const fn from(&self) -> &DefinitionIdentity {
659        &self.from
660    }
661
662    /// Borrows the proposed definition.
663    #[must_use]
664    pub const fn to(&self) -> &DefinitionIdentity {
665        &self.to
666    }
667
668    /// Borrows the durable source-to-target step mapping.
669    ///
670    /// Durable adapters replay the mapping when they resolve a compatible
671    /// restart, so the order is the validated declaration order.
672    #[must_use]
673    pub fn step_mapping(&self) -> &BTreeMap<StepName, StepName> {
674        &self.step_mapping
675    }
676
677    /// Borrows the durable source-to-target node mapping.
678    #[must_use]
679    pub fn node_mapping(&self) -> &BTreeMap<NodeId, NodeId> {
680        &self.node_mapping
681    }
682
683    /// Borrows deterministic state-transform declarations.
684    #[must_use]
685    pub fn transforms(&self) -> &[DefinitionStateTransform] {
686        &self.transforms
687    }
688
689    /// Reports whether the edge carries the M7 transformed descriptor shape.
690    #[must_use]
691    pub const fn is_transformed(&self) -> bool {
692        self.revision.is_some()
693    }
694}
695
696#[derive(Clone, Debug, Eq, PartialEq)]
697struct DefinitionDurableStateContract {
698    kind: DefinitionStateKind,
699    state_id: Option<String>,
700    schema: StateSchemaId,
701    version: StateSchemaVersion,
702}
703
704fn validate_required_definition_state_transforms(
705    from: &DefinitionIdentity,
706    to: &DefinitionIdentity,
707    node_mapping: &BTreeMap<NodeId, NodeId>,
708    transforms: &[DefinitionStateTransform],
709) -> Result<(), DefinitionError> {
710    for (source_node, target_node) in node_mapping {
711        let source_contracts = definition_durable_state_contracts(from, source_node)?;
712        let target_contracts = definition_durable_state_contracts(to, target_node)?;
713        for source in source_contracts {
714            let target = target_contracts
715                .iter()
716                .find(|candidate| {
717                    candidate.kind == source.kind && candidate.state_id == source.state_id
718                })
719                .ok_or(DefinitionError::MissingTargetStateContract)?;
720            let matching = transforms
721                .iter()
722                .filter(|transform| {
723                    transform.source_node() == source_node
724                        && transform.target_node() == target_node
725                        && transform.kind() == source.kind
726                        && source
727                            .state_id
728                            .as_deref()
729                            .is_none_or(|state_id| transform.state_id().as_str() == state_id)
730                })
731                .collect::<Vec<_>>();
732            if matching.len() > 1 {
733                return Err(DefinitionError::DuplicateStateTransform);
734            }
735            let changed = source.schema != target.schema || source.version != target.version;
736            let Some(transform) = matching.first().copied() else {
737                if changed {
738                    return Err(DefinitionError::MissingRequiredStateTransform);
739                }
740                continue;
741            };
742            if transform.source_schema() != &source.schema
743                || transform.source_version() != source.version
744                || transform.target_schema() != &target.schema
745                || transform.target_version() != target.version
746            {
747                return Err(DefinitionError::StateTransformSchemaMismatch);
748            }
749        }
750    }
751    Ok(())
752}
753
754fn definition_durable_state_contracts(
755    definition: &DefinitionIdentity,
756    node_id: &NodeId,
757) -> Result<Vec<DefinitionDurableStateContract>, DefinitionError> {
758    let document: serde_json::Value = serde_json::from_slice(definition.canonical_manifest())
759        .map_err(|_| DefinitionError::ManifestEncoding)?;
760    if definition.manifest_format() == MANIFEST_FORMAT_ONE_STEP {
761        let object = document
762            .as_object()
763            .ok_or(DefinitionError::ManifestEncoding)?;
764        let step = object
765            .get("step")
766            .and_then(serde_json::Value::as_str)
767            .ok_or(DefinitionError::ManifestEncoding)?;
768        if step != node_id.as_str() {
769            return Err(DefinitionError::UnknownUpgradeSourceNode);
770        }
771        return one_step_durable_state_contracts(object);
772    }
773    let node = find_definition_node(&document, node_id).ok_or(DefinitionError::ManifestEncoding)?;
774    graph_node_durable_state_contracts(node)
775}
776
777fn one_step_durable_state_contracts(
778    object: &serde_json::Map<String, serde_json::Value>,
779) -> Result<Vec<DefinitionDurableStateContract>, DefinitionError> {
780    if object.get("kind").and_then(serde_json::Value::as_str) != Some("chunk") {
781        return Ok(Vec::new());
782    }
783    Ok(vec![
784        schema_contract(
785            DefinitionStateKind::Checkpoint,
786            None,
787            object
788                .get("checkpoint")
789                .ok_or(DefinitionError::ManifestEncoding)?,
790            "schema",
791        )?,
792        schema_contract(
793            DefinitionStateKind::ExecutionContext,
794            None,
795            object
796                .get("context")
797                .ok_or(DefinitionError::ManifestEncoding)?,
798            "schema",
799        )?,
800    ])
801}
802
803fn graph_node_durable_state_contracts(
804    node: &serde_json::Map<String, serde_json::Value>,
805) -> Result<Vec<DefinitionDurableStateContract>, DefinitionError> {
806    let mut contracts = Vec::new();
807    match node.get("kind").and_then(serde_json::Value::as_str) {
808        Some("step") => {
809            let step = node
810                .get("step")
811                .and_then(serde_json::Value::as_object)
812                .ok_or(DefinitionError::ManifestEncoding)?;
813            if step.get("kind").and_then(serde_json::Value::as_str) == Some("chunk") {
814                let declaration = step
815                    .get("declaration")
816                    .and_then(serde_json::Value::as_object)
817                    .ok_or(DefinitionError::ManifestEncoding)?;
818                contracts.push(schema_contract(
819                    DefinitionStateKind::Checkpoint,
820                    None,
821                    declaration
822                        .get("checkpoint")
823                        .ok_or(DefinitionError::ManifestEncoding)?,
824                    "schema",
825                )?);
826                contracts.push(schema_contract(
827                    DefinitionStateKind::ExecutionContext,
828                    None,
829                    declaration
830                        .get("context")
831                        .ok_or(DefinitionError::ManifestEncoding)?,
832                    "schema",
833                )?);
834            }
835            if let Some(repeat) = node.get("repeat") {
836                collect_repeat_state_contracts(repeat, &mut contracts)?;
837            }
838        }
839        Some("custom_leaf") => {
840            contracts.push(schema_contract(
841                DefinitionStateKind::ExecutionContext,
842                None,
843                node.get("state_schema")
844                    .ok_or(DefinitionError::ManifestEncoding)?,
845                "id",
846            )?);
847        }
848        _ => {}
849    }
850    Ok(contracts)
851}
852
853fn collect_repeat_state_contracts(
854    repeat: &serde_json::Value,
855    contracts: &mut Vec<DefinitionDurableStateContract>,
856) -> Result<(), DefinitionError> {
857    let object = repeat
858        .as_object()
859        .ok_or(DefinitionError::ManifestEncoding)?;
860    let id = object
861        .get("id")
862        .and_then(serde_json::Value::as_str)
863        .ok_or(DefinitionError::ManifestEncoding)?;
864    contracts.push(schema_contract(
865        DefinitionStateKind::Repeat,
866        Some(id.to_owned()),
867        object
868            .get("state")
869            .ok_or(DefinitionError::ManifestEncoding)?,
870        "schema",
871    )?);
872    if let Some(nested) = object.get("nested") {
873        collect_repeat_state_contracts(nested, contracts)?;
874    }
875    Ok(())
876}
877
878fn schema_contract(
879    kind: DefinitionStateKind,
880    state_id: Option<String>,
881    value: &serde_json::Value,
882    schema_key: &str,
883) -> Result<DefinitionDurableStateContract, DefinitionError> {
884    let object = value.as_object().ok_or(DefinitionError::ManifestEncoding)?;
885    let schema = object
886        .get(schema_key)
887        .and_then(serde_json::Value::as_str)
888        .ok_or(DefinitionError::ManifestEncoding)?;
889    let version = object
890        .get("version")
891        .and_then(serde_json::Value::as_u64)
892        .and_then(|value| u32::try_from(value).ok())
893        .and_then(|value| StateSchemaVersion::new(value).ok())
894        .ok_or(DefinitionError::ManifestEncoding)?;
895    Ok(DefinitionDurableStateContract {
896        kind,
897        state_id,
898        schema: StateSchemaId::new(schema).map_err(|_| DefinitionError::ManifestEncoding)?,
899        version,
900    })
901}
902
903fn find_definition_node<'a>(
904    value: &'a serde_json::Value,
905    node_id: &NodeId,
906) -> Option<&'a serde_json::Map<String, serde_json::Value>> {
907    match value {
908        serde_json::Value::Object(object) => {
909            let is_graph_node = matches!(
910                object.get("kind").and_then(serde_json::Value::as_str),
911                Some(
912                    "step"
913                        | "custom_leaf"
914                        | "decision"
915                        | "join"
916                        | "split"
917                        | "nested_flow"
918                        | "nested_job"
919                        | "partitioned_step"
920                )
921            );
922            if is_graph_node
923                && object.get("id").and_then(serde_json::Value::as_str) == Some(node_id.as_str())
924            {
925                return Some(object);
926            }
927            object
928                .values()
929                .find_map(|child| find_definition_node(child, node_id))
930        }
931        serde_json::Value::Array(values) => values
932            .iter()
933            .find_map(|child| find_definition_node(child, node_id)),
934        _ => None,
935    }
936}
937
938fn definition_upgrade_source_nodes(
939    definition: &DefinitionIdentity,
940) -> Result<BTreeSet<NodeId>, DefinitionError> {
941    let document: serde_json::Value = serde_json::from_slice(definition.canonical_manifest())
942        .map_err(|_| DefinitionError::ManifestEncoding)?;
943    let object = document
944        .as_object()
945        .ok_or(DefinitionError::ManifestEncoding)?;
946    if definition.manifest_format() == MANIFEST_FORMAT_ONE_STEP {
947        let step = object
948            .get("step")
949            .and_then(serde_json::Value::as_str)
950            .ok_or(DefinitionError::ManifestEncoding)?;
951        return Ok(BTreeSet::from([NodeId::new(step)?]));
952    }
953
954    let nodes = object
955        .get("nodes")
956        .and_then(serde_json::Value::as_array)
957        .ok_or(DefinitionError::ManifestEncoding)?;
958    let mut result = BTreeSet::new();
959    collect_upgrade_node_ids(nodes, &mut result)?;
960    Ok(result)
961}
962
963fn collect_upgrade_node_ids(
964    nodes: &[serde_json::Value],
965    result: &mut BTreeSet<NodeId>,
966) -> Result<(), DefinitionError> {
967    for node in nodes {
968        let object = node.as_object().ok_or(DefinitionError::ManifestEncoding)?;
969        if let Some(id) = object.get("id").and_then(serde_json::Value::as_str) {
970            result.insert(NodeId::new(id)?);
971        }
972        for key in ["members", "steps", "nodes"] {
973            if let Some(children) = object.get(key).and_then(serde_json::Value::as_array) {
974                collect_upgrade_node_ids(children, result)?;
975            }
976        }
977        if let Some(branches) = object.get("branches").and_then(serde_json::Value::as_array) {
978            for branch in branches {
979                let branch = branch
980                    .as_object()
981                    .ok_or(DefinitionError::ManifestEncoding)?;
982                for key in ["members", "steps", "nodes"] {
983                    if let Some(children) = branch.get(key).and_then(serde_json::Value::as_array) {
984                        collect_upgrade_node_ids(children, result)?;
985                    }
986                }
987            }
988        }
989    }
990    Ok(())
991}
992
993definition_token!(
994    ComponentRevision,
995    DefinitionTokenKind::Component,
996    "An application-owned revision token for one opaque executable component."
997);
998definition_token!(
999    ClassifierRevision,
1000    DefinitionTokenKind::Classifier,
1001    "An application-owned revision token for one bounded fault classifier."
1002);
1003definition_token!(
1004    ComponentStreamIdentity,
1005    DefinitionTokenKind::Component,
1006    "A stable, owner-scoped `ItemStream` namespace token.\n\nThis is the durable component-state namespace: it is never derived from a\ndisplay name, a memory address, or runtime object identity, and it\nparticipates in the restart-relevant chunk definition fingerprint alongside\nthe other component revisions."
1007);
1008
1009/// Component revisions for a one-step chunk definition.
1010#[derive(Clone, Debug, Eq, PartialEq)]
1011pub struct ChunkComponentRevisions {
1012    reader: ComponentRevision,
1013    processor: ComponentRevision,
1014    writer: ComponentRevision,
1015    checkpoint: ComponentRevision,
1016    restart: ChunkRestartContract,
1017    streams: BTreeMap<ComponentStreamIdentity, ComponentRevision>,
1018    completion_policy: Option<ComponentRevision>,
1019}
1020
1021impl ChunkComponentRevisions {
1022    /// Constructs the four restart-relevant chunk component revisions.
1023    ///
1024    /// Registers no `ItemStream` namespaces and no completion-policy
1025    /// revision; use [`with_stream_revision`](Self::with_stream_revision) and
1026    /// [`with_completion_policy_revision`](Self::with_completion_policy_revision)
1027    /// to add them.
1028    #[must_use]
1029    pub const fn new(
1030        reader: ComponentRevision,
1031        processor: ComponentRevision,
1032        writer: ComponentRevision,
1033        checkpoint: ComponentRevision,
1034        restart: ChunkRestartContract,
1035    ) -> Self {
1036        Self {
1037            reader,
1038            processor,
1039            writer,
1040            checkpoint,
1041            restart,
1042            streams: BTreeMap::new(),
1043            completion_policy: None,
1044        }
1045    }
1046
1047    /// Registers one `ItemStream` namespace's restart-relevant revision.
1048    ///
1049    /// Namespaces are kept in a deterministic (sorted, not insertion) order so
1050    /// the manifest and fingerprint never depend on registration order. A
1051    /// definition with no registered streams produces a manifest and
1052    /// fingerprint byte-for-byte identical to one built before this method
1053    /// existed.
1054    #[must_use]
1055    pub fn with_stream_revision(
1056        mut self,
1057        identity: ComponentStreamIdentity,
1058        revision: ComponentRevision,
1059    ) -> Self {
1060        self.streams.insert(identity, revision);
1061        self
1062    }
1063
1064    /// Iterates registered `ItemStream` namespace revisions in deterministic
1065    /// (sorted) order.
1066    pub fn stream_revisions(
1067        &self,
1068    ) -> impl Iterator<Item = (&ComponentStreamIdentity, &ComponentRevision)> {
1069        self.streams.iter()
1070    }
1071
1072    /// Records the restart-relevant revision of an installed
1073    /// [`crate::CompletionPolicy`](../../oxide_batch/trait.CompletionPolicy.html)
1074    /// (an early-completion policy supplementing the chunk's `ChunkSize`
1075    /// ceiling).
1076    ///
1077    /// A definition with no completion policy installed produces a manifest
1078    /// and fingerprint byte-for-byte identical to one built before this
1079    /// method existed.
1080    #[must_use]
1081    pub fn with_completion_policy_revision(mut self, revision: ComponentRevision) -> Self {
1082        self.completion_policy = Some(revision);
1083        self
1084    }
1085
1086    /// Borrows the completion policy's restart-relevant revision, if one was
1087    /// registered.
1088    #[must_use]
1089    pub const fn completion_policy_revision(&self) -> Option<&ComponentRevision> {
1090        self.completion_policy.as_ref()
1091    }
1092
1093    /// Returns the delivery mode declared by the restart contract.
1094    #[must_use]
1095    pub const fn delivery_mode(&self) -> ChunkDeliveryMode {
1096        self.restart.delivery_mode
1097    }
1098
1099    /// Returns the shutdown policy of an already-open chunk.
1100    #[must_use]
1101    pub const fn in_flight_policy(&self) -> InFlightPolicy {
1102        self.restart.in_flight_policy
1103    }
1104
1105    /// Borrows the revision of the component that reads items.
1106    #[must_use]
1107    pub const fn reader(&self) -> &ComponentRevision {
1108        &self.reader
1109    }
1110
1111    /// Borrows the revision of the component that processes items.
1112    #[must_use]
1113    pub const fn processor(&self) -> &ComponentRevision {
1114        &self.processor
1115    }
1116
1117    /// Borrows the revision of the component that writes items.
1118    #[must_use]
1119    pub const fn writer(&self) -> &ComponentRevision {
1120        &self.writer
1121    }
1122
1123    /// Borrows the revision of the component that produces checkpoints.
1124    #[must_use]
1125    pub const fn checkpoint(&self) -> &ComponentRevision {
1126        &self.checkpoint
1127    }
1128
1129    /// Borrows the declared checkpoint schema.
1130    #[must_use]
1131    pub const fn checkpoint_schema(&self) -> &StateSchemaId {
1132        &self.restart.checkpoint_schema
1133    }
1134
1135    /// Returns the declared checkpoint schema version.
1136    #[must_use]
1137    pub const fn checkpoint_schema_version(&self) -> StateSchemaVersion {
1138        self.restart.checkpoint_schema_version
1139    }
1140
1141    /// Borrows the declared execution-context schema.
1142    #[must_use]
1143    pub const fn context_schema(&self) -> &StateSchemaId {
1144        &self.restart.context_schema
1145    }
1146
1147    /// Returns the declared execution-context schema version.
1148    #[must_use]
1149    pub const fn context_schema_version(&self) -> StateSchemaVersion {
1150        self.restart.context_schema_version
1151    }
1152}
1153
1154/// The accepted shutdown behavior for an already-open chunk.
1155#[derive(Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
1156#[non_exhaustive]
1157pub enum InFlightPolicy {
1158    /// Complete and commit the open chunk, then stop at its boundary.
1159    #[default]
1160    FinishChunk,
1161    /// Roll back the open chunk and preserve the prior checkpoint.
1162    RollbackChunk,
1163}
1164
1165/// Declared delivery boundary included in a chunk definition fingerprint.
1166#[derive(Clone, Copy, Debug, Eq, PartialEq)]
1167#[non_exhaustive]
1168pub enum ChunkDeliveryMode {
1169    /// Business writes and progress share one `PostgreSQL` transaction.
1170    AtomicSameResource,
1171    /// The resource may observe a duplicate after restart.
1172    AtLeastOnce,
1173}
1174
1175impl ChunkDeliveryMode {
1176    /// Returns the stable name this mode is recorded under in a manifest.
1177    ///
1178    /// The name is durable: it is hashed into a definition fingerprint, so it
1179    /// is fixed for the life of the mode rather than a display string.
1180    #[must_use]
1181    pub const fn manifest_name(self) -> &'static str {
1182        match self {
1183            Self::AtomicSameResource => "atomic_same_resource",
1184            Self::AtLeastOnce => "at_least_once",
1185        }
1186    }
1187}
1188
1189/// Restart-state schemas and delivery mode for a chunk definition.
1190#[derive(Clone, Debug, Eq, PartialEq)]
1191pub struct ChunkRestartContract {
1192    checkpoint_schema: StateSchemaId,
1193    checkpoint_schema_version: StateSchemaVersion,
1194    context_schema: StateSchemaId,
1195    context_schema_version: StateSchemaVersion,
1196    delivery_mode: ChunkDeliveryMode,
1197    in_flight_policy: InFlightPolicy,
1198}
1199
1200impl ChunkRestartContract {
1201    /// Constructs the restart-relevant state and delivery declaration.
1202    #[must_use]
1203    pub const fn new(
1204        checkpoint_schema: StateSchemaId,
1205        checkpoint_schema_version: StateSchemaVersion,
1206        context_schema: StateSchemaId,
1207        context_schema_version: StateSchemaVersion,
1208        delivery_mode: ChunkDeliveryMode,
1209    ) -> Self {
1210        Self {
1211            checkpoint_schema,
1212            checkpoint_schema_version,
1213            context_schema,
1214            context_schema_version,
1215            delivery_mode,
1216            in_flight_policy: InFlightPolicy::FinishChunk,
1217        }
1218    }
1219
1220    /// Selects the restart-relevant open-chunk shutdown policy.
1221    #[must_use]
1222    pub const fn with_in_flight_policy(mut self, policy: InFlightPolicy) -> Self {
1223        self.in_flight_policy = policy;
1224        self
1225    }
1226}
1227
1228/// Canonical restart-relevant identity persisted with every execution.
1229#[derive(Clone, Eq, PartialEq)]
1230pub struct DefinitionIdentity {
1231    job_name: Option<JobName>,
1232    revision: DefinitionRevision,
1233    manifest_format: u16,
1234    manifest_digest: [u8; 32],
1235    canonical_manifest: Box<[u8]>,
1236}
1237
1238impl DefinitionIdentity {
1239    /// Builds the identity durable rows written before manifests carried one.
1240    ///
1241    /// The bytes are frozen: a durable row that predates manifest identity
1242    /// must keep resolving to exactly this value.
1243    #[must_use]
1244    pub fn legacy() -> Self {
1245        Self::from_canonical(
1246            None,
1247            DefinitionRevision(LEGACY_REVISION.to_owned()),
1248            LEGACY_MANIFEST.to_vec(),
1249            MANIFEST_FORMAT_ONE_STEP,
1250        )
1251    }
1252
1253    /// Builds the canonical identity for a one-step tasklet definition.
1254    ///
1255    /// # Errors
1256    ///
1257    /// Returns [`DefinitionError::ManifestEncoding`] if the bounded canonical
1258    /// manifest cannot be encoded.
1259    pub fn tasklet(
1260        job_name: &JobName,
1261        step_name: &StepName,
1262        revision: DefinitionRevision,
1263        component_revision: &ComponentRevision,
1264    ) -> Result<Self, DefinitionError> {
1265        let manifest = json!({
1266            "component": {
1267                "tasklet": component_revision.as_str()
1268            },
1269            "delivery_mode": "best_effort",
1270            "format": MANIFEST_FORMAT_ONE_STEP,
1271            "job": job_name.as_str(),
1272            "kind": "tasklet",
1273            "restart_state": "none",
1274            "step": step_name.as_str(),
1275            "transaction_boundary": "tasklet_completion"
1276        });
1277        Self::encode(job_name.clone(), revision, &manifest)
1278    }
1279
1280    /// Builds the canonical identity for a one-step chunk definition.
1281    ///
1282    /// # Errors
1283    ///
1284    /// Returns [`DefinitionError::ManifestEncoding`] if the bounded canonical
1285    /// manifest cannot be encoded.
1286    pub fn chunk(
1287        job_name: &JobName,
1288        step_name: &StepName,
1289        chunk_size: ChunkSize,
1290        revision: DefinitionRevision,
1291        components: &ChunkComponentRevisions,
1292    ) -> Result<Self, DefinitionError> {
1293        let mut manifest = json!({
1294            "chunk_size": chunk_size.get(),
1295            "components": {
1296                "checkpoint": components.checkpoint.as_str(),
1297                "processor": components.processor.as_str(),
1298                "reader": components.reader.as_str(),
1299                "writer": components.writer.as_str()
1300            },
1301            "context": {
1302                "schema": components.restart.context_schema.as_str(),
1303                "version": components.restart.context_schema_version.get()
1304            },
1305            "checkpoint": {
1306                "schema": components.restart.checkpoint_schema.as_str(),
1307                "version": components.restart.checkpoint_schema_version.get()
1308            },
1309            "delivery_mode": components.restart.delivery_mode.manifest_name(),
1310            "format": MANIFEST_FORMAT_ONE_STEP,
1311            "job": job_name.as_str(),
1312            "kind": "chunk",
1313            "step": step_name.as_str(),
1314            "transaction_boundary": "chunk"
1315        });
1316        if components.restart.in_flight_policy == InFlightPolicy::RollbackChunk
1317            && let Some(object) = manifest.as_object_mut()
1318        {
1319            object.insert(
1320                "in_flight_policy".to_owned(),
1321                serde_json::Value::String("rollback_chunk".to_owned()),
1322            );
1323        }
1324        if !components.streams.is_empty()
1325            && let Some(object) = manifest.as_object_mut()
1326        {
1327            let streams: Vec<serde_json::Value> = components
1328                .streams
1329                .iter()
1330                .map(|(identity, revision)| {
1331                    json!({
1332                        "identity": identity.as_str(),
1333                        "revision": revision.as_str(),
1334                    })
1335                })
1336                .collect();
1337            object.insert("streams".to_owned(), serde_json::Value::Array(streams));
1338        }
1339        if let Some(policy_revision) = &components.completion_policy
1340            && let Some(object) = manifest.as_object_mut()
1341        {
1342            object.insert(
1343                "completion_policy".to_owned(),
1344                serde_json::Value::String(policy_revision.as_str().to_owned()),
1345            );
1346        }
1347        Self::encode(job_name.clone(), revision, &manifest)
1348    }
1349
1350    /// Builds the canonical identity for a compiled flow graph.
1351    ///
1352    /// The bytes must already be the canonical manifest the plan compiler
1353    /// normalized and encoded; this constructor validates, bounds, and hashes
1354    /// them. Taking bytes rather than a parsed document keeps the serializer
1355    /// out of this contract and makes the encoding the caller is responsible
1356    /// for explicit rather than implied.
1357    ///
1358    /// # Errors
1359    ///
1360    /// Returns [`DefinitionError::ManifestEncoding`] when the bytes exceed the
1361    /// bounded encoding, are not a canonical JSON object, or do not declare a
1362    /// supported flow manifest format.
1363    pub fn from_flow_manifest(
1364        job_name: &JobName,
1365        revision: DefinitionRevision,
1366        canonical: &[u8],
1367    ) -> Result<Self, DefinitionError> {
1368        if canonical.len() > MAX_MANIFEST_BYTES {
1369            return Err(DefinitionError::ManifestTooLarge {
1370                max_bytes: MAX_MANIFEST_BYTES,
1371            });
1372        }
1373        let document: serde_json::Value =
1374            serde_json::from_slice(canonical).map_err(|_| DefinitionError::ManifestEncoding)?;
1375        let reencoded =
1376            serde_json::to_vec(&document).map_err(|_| DefinitionError::ManifestEncoding)?;
1377        if !document.is_object() || reencoded != canonical {
1378            return Err(DefinitionError::ManifestEncoding);
1379        }
1380        let format = document
1381            .get("format")
1382            .and_then(serde_json::Value::as_u64)
1383            .and_then(|value| u16::try_from(value).ok())
1384            .filter(|value| {
1385                matches!(
1386                    *value,
1387                    MANIFEST_FORMAT_FLOW
1388                        | MANIFEST_FORMAT_LOCAL_SCALE
1389                        | MANIFEST_FORMAT_ADVANCED_FLOW
1390                )
1391            })
1392            .ok_or(DefinitionError::ManifestEncoding)?;
1393
1394        Ok(Self::from_canonical(
1395            Some(job_name.clone()),
1396            revision,
1397            canonical.to_vec(),
1398            format,
1399        ))
1400    }
1401
1402    /// Encodes a one-step manifest this crate composed itself.
1403    fn encode(
1404        job_name: JobName,
1405        revision: DefinitionRevision,
1406        manifest: &serde_json::Value,
1407    ) -> Result<Self, DefinitionError> {
1408        let canonical =
1409            serde_json::to_vec(manifest).map_err(|_| DefinitionError::ManifestEncoding)?;
1410        if canonical.len() > MAX_MANIFEST_BYTES {
1411            return Err(DefinitionError::ManifestTooLarge {
1412                max_bytes: MAX_MANIFEST_BYTES,
1413            });
1414        }
1415        Ok(Self::from_canonical(
1416            Some(job_name),
1417            revision,
1418            canonical,
1419            MANIFEST_FORMAT_ONE_STEP,
1420        ))
1421    }
1422
1423    fn from_canonical(
1424        job_name: Option<JobName>,
1425        revision: DefinitionRevision,
1426        canonical: Vec<u8>,
1427        format: u16,
1428    ) -> Self {
1429        let digest: [u8; 32] = Sha256::digest(&canonical).into();
1430        Self {
1431            job_name,
1432            revision,
1433            manifest_format: format,
1434            manifest_digest: digest,
1435            canonical_manifest: canonical.into_boxed_slice(),
1436        }
1437    }
1438
1439    /// Reconstructs and validates one exact durable definition identity.
1440    ///
1441    /// # Errors
1442    ///
1443    /// Fails closed when the manifest is unsupported, non-canonical, too large,
1444    /// declares a different format, or does not reproduce the stored digest.
1445    #[doc(hidden)]
1446    pub fn from_durable(
1447        job_name: JobName,
1448        revision: DefinitionRevision,
1449        manifest_format: u16,
1450        canonical: &[u8],
1451        expected_digest: [u8; 32],
1452    ) -> Result<Self, DefinitionError> {
1453        if canonical.len() > MAX_MANIFEST_BYTES {
1454            return Err(DefinitionError::ManifestTooLarge {
1455                max_bytes: MAX_MANIFEST_BYTES,
1456            });
1457        }
1458        check_manifest_format(manifest_format).map_err(|_| DefinitionError::ManifestEncoding)?;
1459        let document: serde_json::Value =
1460            serde_json::from_slice(canonical).map_err(|_| DefinitionError::ManifestEncoding)?;
1461        let reencoded =
1462            serde_json::to_vec(&document).map_err(|_| DefinitionError::ManifestEncoding)?;
1463        if !document.is_object()
1464            || reencoded != canonical
1465            || document.get("format").and_then(serde_json::Value::as_u64)
1466                != Some(u64::from(manifest_format))
1467        {
1468            return Err(DefinitionError::ManifestEncoding);
1469        }
1470        let identity = Self::from_canonical(
1471            Some(job_name),
1472            revision,
1473            canonical.to_vec(),
1474            manifest_format,
1475        );
1476        if identity.manifest_digest != expected_digest {
1477            return Err(DefinitionError::ManifestEncoding);
1478        }
1479        Ok(identity)
1480    }
1481
1482    /// Borrows the application-owned definition revision.
1483    #[must_use]
1484    pub const fn revision(&self) -> &DefinitionRevision {
1485        &self.revision
1486    }
1487
1488    /// Borrows the job name bound into a framework-produced manifest.
1489    ///
1490    /// Legacy direct repository calls use an internal compatibility manifest
1491    /// without a bound name.
1492    #[must_use]
1493    pub const fn job_name(&self) -> Option<&JobName> {
1494        self.job_name.as_ref()
1495    }
1496
1497    /// Returns the canonical manifest format version.
1498    #[must_use]
1499    pub const fn manifest_format(&self) -> u16 {
1500        self.manifest_format
1501    }
1502
1503    /// Returns the framework-produced SHA-256 manifest digest.
1504    #[must_use]
1505    pub const fn manifest_digest(&self) -> &[u8; 32] {
1506        &self.manifest_digest
1507    }
1508
1509    /// Borrows the exact canonical manifest bytes that produced the digest.
1510    ///
1511    /// The manifest records names, logical identifiers, revisions, schema
1512    /// versions, and bounded policy values. Parameters, contexts, item values,
1513    /// credentials, endpoints, and component-private state are never encoded
1514    /// into it, so operators may inspect and archive these bytes.
1515    #[must_use]
1516    pub fn canonical_manifest(&self) -> &[u8] {
1517        &self.canonical_manifest
1518    }
1519}
1520
1521/// Returns whether this runtime can interpret `format`.
1522///
1523/// # Errors
1524///
1525/// Returns [`ManifestError::UnsupportedFormat`] for a newer format and
1526/// [`ManifestError::MissingFormat`] for zero.
1527pub const fn check_manifest_format(format: u16) -> Result<(), ManifestError> {
1528    if format == 0 {
1529        return Err(ManifestError::MissingFormat);
1530    }
1531    if format > SUPPORTED_MANIFEST_FORMAT {
1532        return Err(ManifestError::UnsupportedFormat {
1533            format,
1534            supported: SUPPORTED_MANIFEST_FORMAT,
1535        });
1536    }
1537    Ok(())
1538}
1539
1540impl fmt::Debug for DefinitionIdentity {
1541    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1542        formatter
1543            .debug_struct("DefinitionIdentity")
1544            .field("job_name", &self.job_name)
1545            .field("revision", &self.revision)
1546            .field("manifest_format", &self.manifest_format)
1547            .field(
1548                "digest_prefix",
1549                &DigestPrefix([
1550                    self.manifest_digest[0],
1551                    self.manifest_digest[1],
1552                    self.manifest_digest[2],
1553                    self.manifest_digest[3],
1554                ]),
1555            )
1556            .field("canonical_manifest", &"<redacted>")
1557            .finish()
1558    }
1559}
1560
1561struct DigestPrefix([u8; 4]);
1562
1563impl fmt::Debug for DigestPrefix {
1564    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1565        for byte in self.0 {
1566            write!(formatter, "{byte:02x}")?;
1567        }
1568        Ok(())
1569    }
1570}
1571
1572/// A validated, read-only view of one canonical definition manifest.
1573///
1574/// The reader accepts every manifest format this runtime understands, so a
1575/// deployment can inspect a definition persisted by an older release. It never
1576/// guesses: a newer format, a non-canonical encoding, a floating-point value,
1577/// an out-of-bound graph, or a digest that does not match the supplied bytes
1578/// fails closed.
1579///
1580/// The runnable example lives in the `oxide-batch` facade documentation,
1581/// because the supported import path is `oxide_batch`.
1582#[derive(Clone, Debug, Eq, PartialEq)]
1583pub struct DefinitionManifest {
1584    format: u16,
1585    digest: [u8; 32],
1586    job_name: Option<JobName>,
1587    node_count: Option<usize>,
1588    transition_count: Option<usize>,
1589}
1590
1591impl DefinitionManifest {
1592    /// Reads and validates canonical manifest bytes.
1593    ///
1594    /// # Errors
1595    ///
1596    /// Returns [`ManifestError`] when the bytes exceed the durable bound, are
1597    /// not a canonical JSON object, omit or overflow the format member, declare
1598    /// a format this runtime cannot interpret, contain a floating-point value,
1599    /// or describe a graph outside the accepted bounds.
1600    pub fn read(bytes: &[u8]) -> Result<Self, ManifestError> {
1601        if bytes.len() > MAX_MANIFEST_BYTES {
1602            return Err(ManifestError::TooLarge {
1603                max_bytes: MAX_MANIFEST_BYTES,
1604            });
1605        }
1606        let document: serde_json::Value =
1607            serde_json::from_slice(bytes).map_err(|_| ManifestError::MalformedJson)?;
1608        let members = document.as_object().ok_or(ManifestError::NotAnObject)?;
1609        if contains_float(&document) {
1610            return Err(ManifestError::FloatValue);
1611        }
1612        let reencoded = serde_json::to_vec(&document).map_err(|_| ManifestError::MalformedJson)?;
1613        if reencoded != bytes {
1614            return Err(ManifestError::NonCanonicalEncoding);
1615        }
1616        let format = members
1617            .get("format")
1618            .and_then(serde_json::Value::as_u64)
1619            .and_then(|format| u16::try_from(format).ok())
1620            .ok_or(ManifestError::MissingFormat)?;
1621        check_manifest_format(format)?;
1622        if format != MANIFEST_FORMAT_ADVANCED_FLOW
1623            && (members.contains_key("parameter_incrementer")
1624                || contains_object_key(&document, "restart_policy"))
1625        {
1626            return Err(ManifestError::MalformedGraph);
1627        }
1628        let job_name = members
1629            .get("job")
1630            .and_then(serde_json::Value::as_str)
1631            .map(JobName::new)
1632            .transpose()
1633            .map_err(|_| ManifestError::InvalidJobName)?;
1634        let (node_count, transition_count) = match format {
1635            MANIFEST_FORMAT_FLOW | MANIFEST_FORMAT_LOCAL_SCALE => {
1636                let nodes_value = members.get("nodes").ok_or(ManifestError::MalformedGraph)?;
1637                if contains_object_key(nodes_value, "repeat") {
1638                    return Err(ManifestError::MalformedGraph);
1639                }
1640                let nodes = array_len(Some(nodes_value))?;
1641                let transitions = array_len(members.get("transitions"))?;
1642                ensure_graph_bounds(nodes, transitions)?;
1643                (Some(nodes), Some(transitions))
1644            }
1645            MANIFEST_FORMAT_ADVANCED_FLOW => {
1646                validate_parameter_incrementer_manifest(members)?;
1647                validate_restart_policy_manifest(&document)?;
1648                let (nodes, transitions) = advanced_graph_counts(members)?;
1649                ensure_graph_bounds(nodes, transitions)?;
1650                if let Some(scoped) = members.get("scoped_components") {
1651                    let scoped = scoped.as_array().ok_or(ManifestError::MalformedGraph)?;
1652                    if scoped.is_empty() {
1653                        return Err(ManifestError::MalformedGraph);
1654                    }
1655                    let mut job_scoped = 0_usize;
1656                    let mut step_scoped = 0_usize;
1657                    for component in scoped {
1658                        let scope = component
1659                            .as_object()
1660                            .and_then(|object| object.get("scope"))
1661                            .and_then(serde_json::Value::as_str)
1662                            .ok_or(ManifestError::MalformedGraph)?;
1663                        let count = match scope {
1664                            "job" => &mut job_scoped,
1665                            "step" => &mut step_scoped,
1666                            _ => return Err(ManifestError::MalformedGraph),
1667                        };
1668                        *count += 1;
1669                        if *count > crate::MAX_SCOPED_COMPONENTS {
1670                            return Err(ManifestError::MalformedGraph);
1671                        }
1672                    }
1673                }
1674                validate_repeat_manifests(members)?;
1675                (Some(nodes), Some(transitions))
1676            }
1677            _ => (None, None),
1678        };
1679        Ok(Self {
1680            format,
1681            digest: Sha256::digest(bytes).into(),
1682            job_name,
1683            node_count,
1684            transition_count,
1685        })
1686    }
1687
1688    /// Reads canonical bytes and requires them to hash to `expected`.
1689    ///
1690    /// # Errors
1691    ///
1692    /// Returns every [`ManifestError`] [`read`](Self::read) returns, plus
1693    /// [`ManifestError::DigestMismatch`] when the bytes were altered.
1694    pub fn read_verified(bytes: &[u8], expected: &[u8; 32]) -> Result<Self, ManifestError> {
1695        let manifest = Self::read(bytes)?;
1696        if &manifest.digest != expected {
1697            return Err(ManifestError::DigestMismatch);
1698        }
1699        Ok(manifest)
1700    }
1701
1702    /// Returns the declared canonical manifest format.
1703    #[must_use]
1704    pub const fn format(&self) -> u16 {
1705        self.format
1706    }
1707
1708    /// Returns the SHA-256 digest of the exact bytes that were read.
1709    #[must_use]
1710    pub const fn digest(&self) -> &[u8; 32] {
1711        &self.digest
1712    }
1713
1714    /// Borrows the job name bound into the manifest, when present.
1715    #[must_use]
1716    pub const fn job_name(&self) -> Option<&JobName> {
1717        self.job_name.as_ref()
1718    }
1719
1720    /// Returns the compiled node count of a flow manifest.
1721    #[must_use]
1722    pub const fn node_count(&self) -> Option<usize> {
1723        self.node_count
1724    }
1725
1726    /// Returns the compiled transition count of a flow manifest.
1727    #[must_use]
1728    pub const fn transition_count(&self) -> Option<usize> {
1729        self.transition_count
1730    }
1731}
1732
1733fn contains_object_key(value: &serde_json::Value, key: &str) -> bool {
1734    match value {
1735        serde_json::Value::Object(object) => object
1736            .iter()
1737            .any(|(member, value)| member == key || contains_object_key(value, key)),
1738        serde_json::Value::Array(values) => {
1739            values.iter().any(|value| contains_object_key(value, key))
1740        }
1741        _ => false,
1742    }
1743}
1744
1745fn validate_parameter_incrementer_manifest(
1746    members: &serde_json::Map<String, serde_json::Value>,
1747) -> Result<(), ManifestError> {
1748    let Some(value) = members.get("parameter_incrementer") else {
1749        return Ok(());
1750    };
1751    let object = value.as_object().ok_or(ManifestError::MalformedGraph)?;
1752    let required = ["kind", "revision"];
1753    if object.len() != required.len() || object.keys().any(|key| !required.contains(&key.as_str()))
1754    {
1755        return Err(ManifestError::MalformedGraph);
1756    }
1757    let kind = object
1758        .get("kind")
1759        .and_then(serde_json::Value::as_str)
1760        .ok_or(ManifestError::MalformedGraph)?;
1761    let revision = object
1762        .get("revision")
1763        .and_then(serde_json::Value::as_str)
1764        .ok_or(ManifestError::MalformedGraph)?;
1765    DefinitionRevision::new(kind).map_err(|_| ManifestError::MalformedGraph)?;
1766    DefinitionRevision::new(revision).map_err(|_| ManifestError::MalformedGraph)?;
1767    Ok(())
1768}
1769
1770fn validate_restart_policy_manifest(document: &serde_json::Value) -> Result<(), ManifestError> {
1771    fn visit(value: &serde_json::Value, root: bool) -> Result<(), ManifestError> {
1772        match value {
1773            serde_json::Value::Object(object) => {
1774                if let Some(policy) = object.get("restart_policy") {
1775                    let is_start_controls = object.contains_key("start_limit")
1776                        && object.contains_key("allow_start_if_complete");
1777                    if (!root && !is_start_controls) || policy.as_str() != Some("not_restartable") {
1778                        return Err(ManifestError::MalformedGraph);
1779                    }
1780                }
1781                for child in object.values() {
1782                    visit(child, false)?;
1783                }
1784            }
1785            serde_json::Value::Array(values) => {
1786                for child in values {
1787                    visit(child, false)?;
1788                }
1789            }
1790            _ => {}
1791        }
1792        Ok(())
1793    }
1794
1795    visit(document, true)
1796}
1797
1798fn ensure_graph_bounds(nodes: usize, transitions: usize) -> Result<(), ManifestError> {
1799    if nodes > MAX_NODES || transitions > MAX_TRANSITIONS {
1800        return Err(ManifestError::GraphOutOfBounds {
1801            max_nodes: MAX_NODES,
1802            max_transitions: MAX_TRANSITIONS,
1803        });
1804    }
1805    Ok(())
1806}
1807
1808fn advanced_graph_counts(
1809    members: &serde_json::Map<String, serde_json::Value>,
1810) -> Result<(usize, usize), ManifestError> {
1811    let nodes = members
1812        .get("nodes")
1813        .and_then(serde_json::Value::as_array)
1814        .ok_or(ManifestError::MalformedGraph)?;
1815    let transitions = array_len(members.get("transitions"))?;
1816    let mut materialized_nodes = nodes.len();
1817    let mut materialized_transitions = transitions;
1818
1819    for node in nodes {
1820        let object = node.as_object().ok_or(ManifestError::MalformedGraph)?;
1821        match object.get("kind").and_then(serde_json::Value::as_str) {
1822            Some("step" | "decision" | "join") => {}
1823            Some("nested_job") => validate_nested_job_manifest(object)?,
1824            Some("partitioned_step") => {
1825                if !object
1826                    .get("worker")
1827                    .is_some_and(serde_json::Value::is_object)
1828                {
1829                    return Err(ManifestError::MalformedGraph);
1830                }
1831                materialized_nodes =
1832                    materialized_nodes
1833                        .checked_add(1)
1834                        .ok_or(ManifestError::GraphOutOfBounds {
1835                            max_nodes: MAX_NODES,
1836                            max_transitions: MAX_TRANSITIONS,
1837                        })?;
1838            }
1839            Some("split") => {
1840                let branches = object
1841                    .get("branches")
1842                    .and_then(serde_json::Value::as_array)
1843                    .ok_or(ManifestError::MalformedGraph)?;
1844                materialized_nodes = materialized_nodes.checked_add(branches.len()).ok_or(
1845                    ManifestError::GraphOutOfBounds {
1846                        max_nodes: MAX_NODES,
1847                        max_transitions: MAX_TRANSITIONS,
1848                    },
1849                )?;
1850                for branch in branches {
1851                    let branch = branch.as_object().ok_or(ManifestError::MalformedGraph)?;
1852                    match branch.get("kind").and_then(serde_json::Value::as_str) {
1853                        Some("linear") => {
1854                            materialized_nodes = materialized_nodes
1855                                .checked_add(array_len(branch.get("steps"))?)
1856                                .ok_or(ManifestError::GraphOutOfBounds {
1857                                    max_nodes: MAX_NODES,
1858                                    max_transitions: MAX_TRANSITIONS,
1859                                })?;
1860                        }
1861                        Some("flow") => {
1862                            if !branch
1863                                .get("members")
1864                                .is_some_and(serde_json::Value::is_array)
1865                                || branch
1866                                    .get("entry")
1867                                    .and_then(serde_json::Value::as_str)
1868                                    .is_none()
1869                            {
1870                                return Err(ManifestError::MalformedGraph);
1871                            }
1872                        }
1873                        _ => return Err(ManifestError::MalformedGraph),
1874                    }
1875                }
1876            }
1877            Some("nested_flow") => {
1878                let exits = array_len(object.get("exits"))?;
1879                if !object
1880                    .get("members")
1881                    .is_some_and(serde_json::Value::is_array)
1882                    || object
1883                        .get("entry")
1884                        .and_then(serde_json::Value::as_str)
1885                        .is_none()
1886                {
1887                    return Err(ManifestError::MalformedGraph);
1888                }
1889                materialized_transitions = materialized_transitions.checked_add(exits).ok_or(
1890                    ManifestError::GraphOutOfBounds {
1891                        max_nodes: MAX_NODES,
1892                        max_transitions: MAX_TRANSITIONS,
1893                    },
1894                )?;
1895            }
1896            _ => return Err(ManifestError::MalformedGraph),
1897        }
1898        ensure_graph_bounds(materialized_nodes, materialized_transitions)?;
1899    }
1900
1901    Ok((materialized_nodes, materialized_transitions))
1902}
1903
1904fn validate_repeat_manifests(
1905    members: &serde_json::Map<String, serde_json::Value>,
1906) -> Result<(), ManifestError> {
1907    let nodes = members
1908        .get("nodes")
1909        .and_then(serde_json::Value::as_array)
1910        .ok_or(ManifestError::MalformedGraph)?;
1911    let mut repeat_ids = BTreeSet::new();
1912    for node in nodes {
1913        validate_node_repeat(node, &mut repeat_ids)?;
1914    }
1915    Ok(())
1916}
1917
1918fn validate_node_repeat(
1919    node: &serde_json::Value,
1920    repeat_ids: &mut BTreeSet<String>,
1921) -> Result<(), ManifestError> {
1922    let object = node.as_object().ok_or(ManifestError::MalformedGraph)?;
1923    let kind = object.get("kind").and_then(serde_json::Value::as_str);
1924    if kind != Some("step") && object.contains_key("repeat") {
1925        return Err(ManifestError::MalformedGraph);
1926    }
1927    match kind {
1928        Some("step") => {
1929            if let Some(repeat) = object.get("repeat") {
1930                validate_repeat_definition(repeat, repeat_ids, 1)?;
1931            }
1932        }
1933        Some("partitioned_step") => {
1934            validate_node_repeat(
1935                object.get("worker").ok_or(ManifestError::MalformedGraph)?,
1936                repeat_ids,
1937            )?;
1938        }
1939        Some("split") => {
1940            let branches = object
1941                .get("branches")
1942                .and_then(serde_json::Value::as_array)
1943                .ok_or(ManifestError::MalformedGraph)?;
1944            for branch in branches {
1945                let branch = branch.as_object().ok_or(ManifestError::MalformedGraph)?;
1946                if branch.get("kind").and_then(serde_json::Value::as_str) == Some("linear") {
1947                    let steps = branch
1948                        .get("steps")
1949                        .and_then(serde_json::Value::as_array)
1950                        .ok_or(ManifestError::MalformedGraph)?;
1951                    for step in steps {
1952                        validate_node_repeat(step, repeat_ids)?;
1953                    }
1954                }
1955            }
1956        }
1957        _ => {}
1958    }
1959    Ok(())
1960}
1961
1962fn validate_repeat_definition(
1963    value: &serde_json::Value,
1964    repeat_ids: &mut BTreeSet<String>,
1965    depth: usize,
1966) -> Result<(), ManifestError> {
1967    if depth > MAX_REPEAT_NESTING_DEPTH {
1968        return Err(ManifestError::MalformedGraph);
1969    }
1970    let object = value.as_object().ok_or(ManifestError::MalformedGraph)?;
1971    let allowed = ["id", "interceptors", "nested", "policy", "state"];
1972    if object.keys().any(|key| !allowed.contains(&key.as_str())) {
1973        return Err(ManifestError::MalformedGraph);
1974    }
1975    let id = object
1976        .get("id")
1977        .and_then(serde_json::Value::as_str)
1978        .ok_or(ManifestError::MalformedGraph)?;
1979    validate_token(id, DefinitionTokenKind::Repeat).map_err(|_| ManifestError::MalformedGraph)?;
1980    if !repeat_ids.insert(id.to_owned()) {
1981        return Err(ManifestError::MalformedGraph);
1982    }
1983    validate_repeat_policy(object.get("policy").ok_or(ManifestError::MalformedGraph)?)?;
1984    validate_repeat_state(object.get("state").ok_or(ManifestError::MalformedGraph)?)?;
1985    let interceptors = object
1986        .get("interceptors")
1987        .and_then(serde_json::Value::as_array)
1988        .ok_or(ManifestError::MalformedGraph)?;
1989    if interceptors.len() > MAX_REPEAT_INTERCEPTORS {
1990        return Err(ManifestError::MalformedGraph);
1991    }
1992    let mut interceptor_ids = BTreeSet::new();
1993    for interceptor in interceptors {
1994        validate_repeat_interceptor(interceptor, &mut interceptor_ids)?;
1995    }
1996    if let Some(nested) = object.get("nested") {
1997        validate_repeat_definition(nested, repeat_ids, depth.saturating_add(1))?;
1998    }
1999    Ok(())
2000}
2001
2002fn validate_repeat_policy(value: &serde_json::Value) -> Result<(), ManifestError> {
2003    let object = value.as_object().ok_or(ManifestError::MalformedGraph)?;
2004    let required = ["configuration", "kind", "revision"];
2005    if object.len() != required.len() || object.keys().any(|key| !required.contains(&key.as_str()))
2006    {
2007        return Err(ManifestError::MalformedGraph);
2008    }
2009    let configuration = object
2010        .get("configuration")
2011        .and_then(serde_json::Value::as_str)
2012        .ok_or(ManifestError::MalformedGraph)?;
2013    validate_token(configuration, DefinitionTokenKind::RepeatPolicy)
2014        .map_err(|_| ManifestError::MalformedGraph)?;
2015    let kind = object
2016        .get("kind")
2017        .and_then(serde_json::Value::as_str)
2018        .ok_or(ManifestError::MalformedGraph)?;
2019    validate_token(kind, DefinitionTokenKind::RepeatPolicy)
2020        .map_err(|_| ManifestError::MalformedGraph)?;
2021    let revision = object
2022        .get("revision")
2023        .and_then(serde_json::Value::as_str)
2024        .ok_or(ManifestError::MalformedGraph)?;
2025    ComponentRevision::new(revision.to_owned()).map_err(|_| ManifestError::MalformedGraph)?;
2026    Ok(())
2027}
2028
2029fn validate_repeat_interceptor(
2030    value: &serde_json::Value,
2031    ids: &mut BTreeSet<String>,
2032) -> Result<(), ManifestError> {
2033    let object = value.as_object().ok_or(ManifestError::MalformedGraph)?;
2034    let required = ["id", "kind", "revision"];
2035    if object.len() != required.len() || object.keys().any(|key| !required.contains(&key.as_str()))
2036    {
2037        return Err(ManifestError::MalformedGraph);
2038    }
2039    let id = object
2040        .get("id")
2041        .and_then(serde_json::Value::as_str)
2042        .ok_or(ManifestError::MalformedGraph)?;
2043    validate_token(id, DefinitionTokenKind::RepeatInterceptor)
2044        .map_err(|_| ManifestError::MalformedGraph)?;
2045    if !ids.insert(id.to_owned()) {
2046        return Err(ManifestError::MalformedGraph);
2047    }
2048    let kind = object
2049        .get("kind")
2050        .and_then(serde_json::Value::as_str)
2051        .ok_or(ManifestError::MalformedGraph)?;
2052    validate_token(kind, DefinitionTokenKind::RepeatInterceptor)
2053        .map_err(|_| ManifestError::MalformedGraph)?;
2054    let revision = object
2055        .get("revision")
2056        .and_then(serde_json::Value::as_str)
2057        .ok_or(ManifestError::MalformedGraph)?;
2058    ComponentRevision::new(revision.to_owned()).map_err(|_| ManifestError::MalformedGraph)?;
2059    Ok(())
2060}
2061
2062fn validate_repeat_state(value: &serde_json::Value) -> Result<(), ManifestError> {
2063    let object = value.as_object().ok_or(ManifestError::MalformedGraph)?;
2064    let required = ["schema", "version"];
2065    if object.len() != required.len() || object.keys().any(|key| !required.contains(&key.as_str()))
2066    {
2067        return Err(ManifestError::MalformedGraph);
2068    }
2069    let schema = object
2070        .get("schema")
2071        .and_then(serde_json::Value::as_str)
2072        .ok_or(ManifestError::MalformedGraph)?;
2073    StateSchemaId::new(schema.to_owned()).map_err(|_| ManifestError::MalformedGraph)?;
2074    let version = object
2075        .get("version")
2076        .and_then(serde_json::Value::as_u64)
2077        .and_then(|value| u32::try_from(value).ok())
2078        .ok_or(ManifestError::MalformedGraph)?;
2079    StateSchemaVersion::new(version).map_err(|_| ManifestError::MalformedGraph)?;
2080    Ok(())
2081}
2082fn validate_nested_job_manifest(
2083    object: &serde_json::Map<String, serde_json::Value>,
2084) -> Result<(), ManifestError> {
2085    if !object
2086        .get("child")
2087        .is_some_and(serde_json::Value::is_object)
2088        || !object
2089            .get("parameters")
2090            .is_some_and(serde_json::Value::is_array)
2091        || object
2092            .get("mapping_revision")
2093            .and_then(serde_json::Value::as_str)
2094            .is_none()
2095    {
2096        return Err(ManifestError::MalformedGraph);
2097    }
2098    Ok(())
2099}
2100
2101fn array_len(value: Option<&serde_json::Value>) -> Result<usize, ManifestError> {
2102    value
2103        .and_then(serde_json::Value::as_array)
2104        .map(Vec::len)
2105        .ok_or(ManifestError::MalformedGraph)
2106}
2107
2108fn contains_float(value: &serde_json::Value) -> bool {
2109    match value {
2110        serde_json::Value::Number(number) => number.as_i64().is_none() && number.as_u64().is_none(),
2111        serde_json::Value::Array(values) => values.iter().any(contains_float),
2112        serde_json::Value::Object(members) => members.values().any(contains_float),
2113        _ => false,
2114    }
2115}
2116
2117/// A canonical definition manifest that cannot be interpreted.
2118#[derive(Clone, Copy, Debug, Eq, PartialEq)]
2119#[non_exhaustive]
2120pub enum ManifestError {
2121    /// The bytes exceeded the durable manifest bound.
2122    TooLarge {
2123        /// Maximum accepted byte length.
2124        max_bytes: usize,
2125    },
2126    /// The bytes are not valid JSON.
2127    MalformedJson,
2128    /// The document is not a JSON object.
2129    NotAnObject,
2130    /// Re-encoding the document did not reproduce the supplied bytes.
2131    NonCanonicalEncoding,
2132    /// The document contains a floating-point number.
2133    FloatValue,
2134    /// The format member is absent or not a `u16`.
2135    MissingFormat,
2136    /// The manifest is newer than this runtime understands.
2137    UnsupportedFormat {
2138        /// Format found in the manifest.
2139        format: u16,
2140        /// Newest format this runtime interprets.
2141        supported: u16,
2142    },
2143    /// A flow manifest omitted or malformed its graph members.
2144    MalformedGraph,
2145    /// A flow manifest declared a graph larger than this runtime accepts.
2146    GraphOutOfBounds {
2147        /// Maximum accepted node count.
2148        max_nodes: usize,
2149        /// Maximum accepted transition count.
2150        max_transitions: usize,
2151    },
2152    /// The bound job name is not a valid [`JobName`].
2153    InvalidJobName,
2154    /// The bytes do not hash to the expected fingerprint.
2155    DigestMismatch,
2156}
2157
2158impl fmt::Display for ManifestError {
2159    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2160        match self {
2161            Self::TooLarge { max_bytes } => {
2162                write!(formatter, "definition manifest exceeds {max_bytes} bytes")
2163            }
2164            Self::MalformedJson => formatter.write_str("definition manifest is not valid JSON"),
2165            Self::NotAnObject => formatter.write_str("definition manifest is not a JSON object"),
2166            Self::NonCanonicalEncoding => {
2167                formatter.write_str("definition manifest is not canonically encoded")
2168            }
2169            Self::FloatValue => {
2170                formatter.write_str("definition manifest contains a floating-point value")
2171            }
2172            Self::MissingFormat => {
2173                formatter.write_str("definition manifest has no usable format member")
2174            }
2175            Self::UnsupportedFormat { format, supported } => write!(
2176                formatter,
2177                "definition manifest format {format} is newer than the supported format {supported}"
2178            ),
2179            Self::MalformedGraph => {
2180                formatter.write_str("flow manifest has no readable node and transition members")
2181            }
2182            Self::GraphOutOfBounds {
2183                max_nodes,
2184                max_transitions,
2185            } => write!(
2186                formatter,
2187                "flow manifest exceeds {max_nodes} nodes or {max_transitions} transitions"
2188            ),
2189            Self::InvalidJobName => {
2190                formatter.write_str("definition manifest binds an invalid job name")
2191            }
2192            Self::DigestMismatch => {
2193                formatter.write_str("definition manifest does not match its fingerprint")
2194            }
2195        }
2196    }
2197}
2198
2199impl Error for ManifestError {}
2200
2201/// Definition token category used by validation diagnostics.
2202#[derive(Clone, Copy, Debug, Eq, PartialEq)]
2203#[non_exhaustive]
2204pub enum DefinitionTokenKind {
2205    /// Definition revision.
2206    Revision,
2207    /// Opaque component revision.
2208    Component,
2209    /// Executable artifact identity.
2210    Artifact,
2211    /// Directed compatibility edge key.
2212    Upgrade,
2213    /// Bounded fault-classifier revision.
2214    Classifier,
2215    /// Stable flow-graph node identifier.
2216    Node,
2217    /// Bounded decider revision.
2218    Decider,
2219    /// Stable repeat definition identity.
2220    Repeat,
2221    /// Repeat policy kind or configuration identity.
2222    RepeatPolicy,
2223    /// Repeat interceptor registration or kind identity.
2224    RepeatInterceptor,
2225}
2226
2227/// Failure to construct a bounded restart definition.
2228#[derive(Clone, Debug, Eq, PartialEq)]
2229#[non_exhaustive]
2230pub enum DefinitionError {
2231    /// A start limit of zero can never start its step.
2232    ZeroStartLimit,
2233    /// A required token was empty.
2234    EmptyToken {
2235        /// Rejected token category.
2236        kind: DefinitionTokenKind,
2237    },
2238    /// A token exceeded its UTF-8 byte bound.
2239    TokenTooLong {
2240        /// Rejected token category.
2241        kind: DefinitionTokenKind,
2242        /// Maximum accepted byte length.
2243        max_bytes: usize,
2244    },
2245    /// A token had leading or trailing whitespace.
2246    SurroundingWhitespace {
2247        /// Rejected token category.
2248        kind: DefinitionTokenKind,
2249    },
2250    /// A token contained a control character.
2251    ControlCharacter {
2252        /// Rejected token category.
2253        kind: DefinitionTokenKind,
2254    },
2255    /// The canonical manifest could not be encoded.
2256    ManifestEncoding,
2257    /// The canonical manifest exceeded its durable bound.
2258    ManifestTooLarge {
2259        /// Maximum accepted byte length.
2260        max_bytes: usize,
2261    },
2262    /// A directed edge pointed from a definition to itself.
2263    UpgradeSelfEdge,
2264    /// A directed edge omitted its durable step mapping.
2265    EmptyStepMapping,
2266    /// A source step appeared more than once.
2267    DuplicateSourceStep,
2268    /// Two source steps mapped to the same target step.
2269    DuplicateTargetStep,
2270    /// A transformed edge exceeded its durable source-node bound.
2271    TooManyUpgradeNodes {
2272        /// Maximum accepted mapped source nodes.
2273        max: usize,
2274    },
2275    /// A transformed edge exceeded its state-transform declaration bound.
2276    TooManyUpgradeTransforms {
2277        /// Maximum accepted state-transform declarations.
2278        max: usize,
2279    },
2280    /// A durable source node appeared more than once.
2281    DuplicateSourceNode,
2282    /// Two durable source nodes mapped to the same target node.
2283    DuplicateTargetNode,
2284    /// The same state-family member was declared more than once.
2285    DuplicateStateTransform,
2286    /// A state transform named a source/target pair outside the node mapping.
2287    StateTransformOutsideNodeMapping,
2288    /// A mapping named a source node absent from the source definition.
2289    UnknownUpgradeSourceNode,
2290    /// A durable source definition node had no explicit target mapping.
2291    MissingUpgradeSourceNode,
2292    /// A mapping named a target node absent from the target definition.
2293    UnknownUpgradeTargetNode,
2294    /// A durable source state family has no matching target contract.
2295    MissingTargetStateContract,
2296    /// A changed durable schema has no explicit transform declaration.
2297    MissingRequiredStateTransform,
2298    /// A declared transform disagrees with source/target manifest schemas.
2299    StateTransformSchemaMismatch,
2300    /// A legacy M2 identity-only edge cannot execute an M7 compatible restart.
2301    LegacyUpgradeExecution,
2302    /// Two live state transformer implementations reused one revision.
2303    DuplicateStateTransformer,
2304    /// Live transformer revisions did not exactly match the durable descriptor.
2305    StateTransformerSetMismatch,
2306    /// A step's fault runtime declared a different delivery mode than its
2307    /// restart contract.
2308    DeliveryModeMismatch,
2309    /// A one-step wrapper could not be lowered into its compatibility plan.
2310    ///
2311    /// The framework derives the compatibility graph from values it has
2312    /// already validated, so this variant reports a framework invariant rather
2313    /// than an application mistake.
2314    CompatibilityLowering,
2315    /// A runtime `ItemStream` was registered under a namespace this
2316    /// definition's [`ChunkComponentRevisions`] does not declare.
2317    RuntimeStreamNotDeclared {
2318        /// The undeclared runtime namespace.
2319        namespace: ComponentStreamIdentity,
2320    },
2321    /// A declared stream revision has no matching runtime `ItemStream`
2322    /// registration.
2323    DeclaredStreamMissingRuntime {
2324        /// The declared namespace with no runtime registration.
2325        namespace: ComponentStreamIdentity,
2326    },
2327    /// The same namespace was registered as a runtime `ItemStream` more than
2328    /// once.
2329    DuplicateRuntimeStream {
2330        /// The namespace registered more than once.
2331        namespace: ComponentStreamIdentity,
2332    },
2333    /// A registered `ItemStream` declares
2334    /// [`RestartabilityDeclaration::NotRestartable`](crate::RestartabilityDeclaration::NotRestartable),
2335    /// which prevents its owning chunk step from claiming restartability
2336    /// regardless of reader-checkpoint presence.
2337    NonRestartableStream {
2338        /// The namespace whose stream cannot honestly claim restartability.
2339        namespace: ComponentStreamIdentity,
2340    },
2341    /// An installed completion policy's `fingerprint()` panicked while its
2342    /// configuration was being folded into the chunk definition's
2343    /// restart-relevant revisions.
2344    ///
2345    /// `fingerprint()` is an application-supplied callback (every built-in
2346    /// policy's own implementation cannot panic), so a definition cannot be
2347    /// constructed from one that does -- this is reported the same way any
2348    /// other definition-construction failure is, rather than unwinding out
2349    /// of a constructor with a `Result` return type.
2350    CompletionPolicyFingerprintPanic,
2351    /// A custom completion policy did not provide restart-relevant identity.
2352    CompletionPolicyFingerprintMissing,
2353    /// A chunk step's live completion-policy fingerprint does not match the
2354    /// completion-policy revision already declared in the
2355    /// [`ChunkComponentRevisions`] a compiled flow node was bound against.
2356    ///
2357    /// Unlike a standalone chunk job (which builds its compiled plan and
2358    /// runtime step from the same call, so it can fold a completion
2359    /// policy's fingerprint in automatically), a flow node is bound to a
2360    /// plan that was already compiled from bare `ChunkComponentRevisions`
2361    /// -- before any concrete step, or its installed policy, existed. The
2362    /// caller must declare the matching revision up front (the same way a
2363    /// stream revision is declared up front and validated against its
2364    /// runtime registration) rather than relying on it being computed
2365    /// automatically.
2366    CompletionPolicyRevisionMismatch,
2367}
2368
2369impl fmt::Display for DefinitionError {
2370    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
2371        match self {
2372            Self::ZeroStartLimit => formatter.write_str("start limit must be nonzero"),
2373            Self::EmptyToken { kind } => write!(formatter, "{kind:?} token must not be empty"),
2374            Self::TokenTooLong { kind, max_bytes } => {
2375                write!(formatter, "{kind:?} token exceeds {max_bytes} bytes")
2376            }
2377            Self::SurroundingWhitespace { kind } => {
2378                write!(formatter, "{kind:?} token has surrounding whitespace")
2379            }
2380            Self::ControlCharacter { kind } => {
2381                write!(formatter, "{kind:?} token contains a control character")
2382            }
2383            Self::ManifestEncoding => formatter.write_str("definition manifest encoding failed"),
2384            Self::ManifestTooLarge { max_bytes } => {
2385                write!(formatter, "definition manifest exceeds {max_bytes} bytes")
2386            }
2387            Self::UpgradeSelfEdge => formatter.write_str("definition upgrade is a self-edge"),
2388            Self::EmptyStepMapping => formatter.write_str("definition upgrade has no step mapping"),
2389            Self::DuplicateSourceStep => {
2390                formatter.write_str("definition upgrade repeats a source step")
2391            }
2392            Self::DuplicateTargetStep => {
2393                formatter.write_str("definition upgrade reuses a target step")
2394            }
2395            Self::TooManyUpgradeNodes { max } => {
2396                write!(
2397                    formatter,
2398                    "definition upgrade exceeds {max} mapped source nodes"
2399                )
2400            }
2401            Self::TooManyUpgradeTransforms { max } => {
2402                write!(
2403                    formatter,
2404                    "definition upgrade exceeds {max} state transforms"
2405                )
2406            }
2407            Self::DuplicateSourceNode => {
2408                formatter.write_str("definition upgrade repeats a durable source node")
2409            }
2410            Self::DuplicateTargetNode => {
2411                formatter.write_str("definition upgrade reuses a durable target node")
2412            }
2413            Self::DuplicateStateTransform => {
2414                formatter.write_str("definition upgrade repeats a state transform")
2415            }
2416            Self::StateTransformOutsideNodeMapping => {
2417                formatter.write_str("definition state transform is outside the node mapping")
2418            }
2419            Self::UnknownUpgradeSourceNode => {
2420                formatter.write_str("definition upgrade maps an unknown source node")
2421            }
2422            Self::MissingUpgradeSourceNode => {
2423                formatter.write_str("definition upgrade omits a durable source node")
2424            }
2425            Self::UnknownUpgradeTargetNode => {
2426                formatter.write_str("definition upgrade maps to an unknown target node")
2427            }
2428            Self::MissingTargetStateContract => {
2429                formatter.write_str("definition upgrade drops a durable source state contract")
2430            }
2431            Self::MissingRequiredStateTransform => {
2432                formatter.write_str("definition upgrade omits a required state schema transform")
2433            }
2434            Self::StateTransformSchemaMismatch => {
2435                formatter.write_str("definition state transform disagrees with manifest schemas")
2436            }
2437            Self::LegacyUpgradeExecution => formatter
2438                .write_str("legacy definition upgrade has no transformed execution contract"),
2439            Self::DuplicateStateTransformer => {
2440                formatter.write_str("definition upgrade repeats a live state transformer revision")
2441            }
2442            Self::StateTransformerSetMismatch => formatter
2443                .write_str("definition upgrade live transformer set does not match metadata"),
2444            Self::DeliveryModeMismatch => formatter
2445                .write_str("fault runtime and restart contract declare different delivery modes"),
2446            Self::CompatibilityLowering => {
2447                formatter.write_str("one-step compatibility lowering produced an invalid plan")
2448            }
2449            Self::RuntimeStreamNotDeclared { namespace } => write!(
2450                formatter,
2451                "runtime ItemStream namespace {:?} is not declared in the chunk definition",
2452                namespace.as_str()
2453            ),
2454            Self::DeclaredStreamMissingRuntime { namespace } => write!(
2455                formatter,
2456                "declared stream namespace {:?} has no registered runtime ItemStream",
2457                namespace.as_str()
2458            ),
2459            Self::DuplicateRuntimeStream { namespace } => write!(
2460                formatter,
2461                "runtime ItemStream namespace {:?} was registered more than once",
2462                namespace.as_str()
2463            ),
2464            Self::NonRestartableStream { namespace } => write!(
2465                formatter,
2466                "ItemStream namespace {:?} declares NotRestartable, so this step cannot claim restartability",
2467                namespace.as_str()
2468            ),
2469            Self::CompletionPolicyFingerprintPanic => {
2470                formatter.write_str("completion policy fingerprint() panicked")
2471            }
2472            Self::CompletionPolicyFingerprintMissing => formatter
2473                .write_str("custom completion policy must provide a restart-relevant fingerprint"),
2474            Self::CompletionPolicyRevisionMismatch => formatter.write_str(
2475                "the step's live completion-policy fingerprint does not match the \
2476                 completion-policy revision declared in the bound component revisions",
2477            ),
2478        }
2479    }
2480}
2481
2482impl Error for DefinitionError {}