Skip to main content

logit_loom_diffusion/
image_program.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Bounded resident image-program contracts, receipts, and measurements.
4
5use std::collections::{HashMap, HashSet};
6
7use logit_loom_core::{CoreError, Digest};
8use logit_loom_executor::BufferSpec;
9use serde::{Deserialize, Serialize};
10
11use crate::{
12    DiffusionSchedule, ImageBufferRole, ImageCleanupPolicy, ImageOperation, ImageOutputFormat,
13    MAX_DEVICE_LABEL_BYTES, MAX_IMAGE_DIMENSION, MAX_IMAGE_LORAS, MAX_IMAGE_OBSERVATIONS,
14    MAX_IMAGE_OPERATORS, ObservationKind, ObservationRequest, OperatorInvocation, ScaleSchedule,
15    SeedSelection, StepSelector, TensorDType, TensorSpec,
16};
17
18/// Maximum ordered stages in one resident image program.
19pub const MAX_IMAGE_PROGRAM_STAGES: usize = 64;
20/// Maximum typed values in one resident image program.
21pub const MAX_IMAGE_PROGRAM_VALUES: usize = 128;
22/// Maximum external inputs in one resident image program.
23pub const MAX_IMAGE_PROGRAM_INPUTS: usize = 32;
24/// Maximum caller-owned output routes in one resident image program.
25pub const MAX_IMAGE_PROGRAM_OUTPUTS: usize = 32;
26/// Maximum declared size of one logical program value.
27pub const MAX_IMAGE_PROGRAM_VALUE_BYTES: u64 = 1024 * 1024 * 1024;
28/// Maximum liveness-derived resident value-arena size.
29pub const MAX_IMAGE_PROGRAM_ARENA_BYTES: u64 = 2 * 1024 * 1024 * 1024;
30
31/// Returns the canonical content identity for one produced program value.
32///
33/// External input identities remain caller-supplied [`BufferSpec`] identities.
34/// Every stage-produced serializable value and the native representation of an
35/// opaque stage-produced value use this domain so materialization can be
36/// checked without interpreting the value.
37pub fn image_program_value_content(bytes: &[u8]) -> Digest {
38    Digest::of_bytes("image-program-value-content-v1", bytes)
39}
40
41/// Exact semantics of one backend-native opaque value.
42#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
43#[serde(rename_all = "kebab-case")]
44pub enum ImageOpaqueValueKindV1 {
45    /// Backend-native prompt conditioning.
46    Conditioning,
47    /// Verified adapter artifact retained for native application.
48    LoraArtifact,
49    /// Request-local post-Euler state that has not been serialized.
50    CheckpointState,
51}
52
53/// Exact decoded pixel representation carried by one PNG value.
54#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
55#[serde(rename_all = "kebab-case")]
56pub enum ImagePngColorV1 {
57    /// Eight-bit red, green, and blue samples.
58    Rgb8,
59    /// Eight-bit red, green, blue, and alpha samples.
60    Rgba8,
61}
62
63impl ImagePngColorV1 {
64    /// Returns the exact decoded channel count.
65    pub const fn channels(self) -> u32 {
66        match self {
67            Self::Rgb8 => 3,
68            Self::Rgba8 => 4,
69        }
70    }
71}
72
73/// Exact logical representation of one resident program value.
74#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
75#[serde(rename_all = "kebab-case", tag = "kind")]
76pub enum ImageProgramValueSpecV1 {
77    /// Valid UTF-8 bytes with a public maximum length.
78    Utf8 {
79        /// Maximum accepted byte length.
80        maximum_bytes: u64,
81    },
82    /// Tightly packed interleaved RGB bytes.
83    Rgb8 {
84        /// Pixel width.
85        width: u32,
86        /// Pixel height.
87        height: u32,
88    },
89    /// Tightly packed interleaved RGBA bytes.
90    Rgba8 {
91        /// Pixel width.
92        width: u32,
93        /// Pixel height.
94        height: u32,
95    },
96    /// Lossless PNG bytes with exact decoded geometry and encoder identity.
97    Png {
98        /// Decoded pixel width.
99        width: u32,
100        /// Decoded pixel height.
101        height: u32,
102        /// Decoded sample representation.
103        color: ImagePngColorV1,
104        /// Exact deterministic encoder implementation.
105        encoding: Digest,
106        /// Maximum accepted encoded byte length.
107        maximum_bytes: u64,
108    },
109    /// Tightly packed single-channel bytes.
110    Gray8 {
111        /// Pixel width.
112        width: u32,
113        /// Pixel height.
114        height: u32,
115    },
116    /// Exact typed tensor bytes under one representation identity.
117    Tensor {
118        /// Tensor shape, scalar type, layout, and placement contract.
119        tensor: TensorSpec,
120        /// Exact native representation and conversion identity.
121        representation: Digest,
122    },
123    /// Authenticated serialized checkpoint envelope.
124    Checkpoint {
125        /// Exact checkpoint compatibility and lineage domain.
126        compatibility: Digest,
127        /// Maximum serialized byte length.
128        maximum_bytes: u64,
129    },
130    /// Backend-native bytes or state unavailable to public interpretation.
131    Opaque {
132        /// Mechanical role of the opaque value.
133        opaque_kind: ImageOpaqueValueKindV1,
134        /// Exact producer/consumer compatibility domain.
135        compatibility: Digest,
136        /// Maximum resident byte length.
137        maximum_bytes: u64,
138    },
139}
140
141impl ImageProgramValueSpecV1 {
142    /// Validates dimensions, tensor metadata, and public byte bounds.
143    ///
144    /// # Errors
145    ///
146    /// Returns the first invalid dimension, tensor, or byte bound.
147    pub fn validate(&self) -> Result<(), CoreError> {
148        let bytes = match self {
149            Self::Utf8 { maximum_bytes }
150            | Self::Checkpoint { maximum_bytes, .. }
151            | Self::Opaque { maximum_bytes, .. } => {
152                validate_variable_bytes(*maximum_bytes)?;
153                *maximum_bytes
154            }
155            Self::Png {
156                width,
157                height,
158                maximum_bytes,
159                ..
160            } => {
161                validate_dimensions(*width, *height)?;
162                validate_variable_bytes(*maximum_bytes)?;
163                *maximum_bytes
164            }
165            Self::Rgb8 { width, height } => image_bytes(*width, *height, 3)?,
166            Self::Rgba8 { width, height } => image_bytes(*width, *height, 4)?,
167            Self::Gray8 { width, height } => image_bytes(*width, *height, 1)?,
168            Self::Tensor { tensor, .. } => {
169                tensor.validate()?;
170                tensor_bytes(tensor)?
171            }
172        };
173        if bytes > MAX_IMAGE_PROGRAM_VALUE_BYTES {
174            return Err(CoreError::invalid(
175                "image program value",
176                format!("exceeds {MAX_IMAGE_PROGRAM_VALUE_BYTES} bytes"),
177            ));
178        }
179        Ok(())
180    }
181
182    /// Returns the maximum resident bytes represented by this value.
183    ///
184    /// # Errors
185    ///
186    /// Returns an error when the value specification is invalid.
187    pub fn maximum_bytes(&self) -> Result<u64, CoreError> {
188        self.validate()?;
189        match self {
190            Self::Utf8 { maximum_bytes }
191            | Self::Checkpoint { maximum_bytes, .. }
192            | Self::Opaque { maximum_bytes, .. }
193            | Self::Png { maximum_bytes, .. } => Ok(*maximum_bytes),
194            Self::Rgb8 { width, height } => image_bytes(*width, *height, 3),
195            Self::Rgba8 { width, height } => image_bytes(*width, *height, 4),
196            Self::Gray8 { width, height } => image_bytes(*width, *height, 1),
197            Self::Tensor { tensor, .. } => tensor_bytes(tensor),
198        }
199    }
200
201    fn validate_buffer_length(&self, bytes: u64) -> Result<(), CoreError> {
202        self.validate()?;
203        let valid = match self {
204            Self::Utf8 { maximum_bytes }
205            | Self::Checkpoint { maximum_bytes, .. }
206            | Self::Opaque { maximum_bytes, .. }
207            | Self::Png { maximum_bytes, .. } => bytes > 0 && bytes <= *maximum_bytes,
208            Self::Rgb8 { .. } | Self::Rgba8 { .. } | Self::Gray8 { .. } | Self::Tensor { .. } => {
209                bytes == self.maximum_bytes()?
210            }
211        };
212        if !valid {
213            return Err(CoreError::invalid(
214                "image program buffer",
215                "length is incompatible with its value specification",
216            ));
217        }
218        Ok(())
219    }
220}
221
222/// One numbered logical value in a resident image program.
223#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
224#[serde(deny_unknown_fields)]
225pub struct ImageProgramValueV1 {
226    /// Zero-based value identifier.
227    pub value: u16,
228    /// Exact logical representation.
229    pub spec: ImageProgramValueSpecV1,
230}
231
232/// One external value and its exact caller-owned input metadata.
233#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
234#[serde(deny_unknown_fields)]
235pub struct ImageProgramInputV1 {
236    /// Logical value initialized by this input.
237    pub value: u16,
238    /// Exact readable input metadata.
239    pub buffer: BufferSpec,
240}
241
242/// One native-stage input role bound to an earlier logical value.
243#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
244#[serde(deny_unknown_fields)]
245pub struct ImageProgramInputBindingV1 {
246    /// Mechanical input role.
247    pub role: ImageBufferRole,
248    /// Earlier logical value supplying the role.
249    pub value: u16,
250}
251
252/// One scheduled adapter applied by a native stage.
253#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
254#[serde(deny_unknown_fields)]
255pub struct ImageProgramLoraV1 {
256    /// Earlier opaque `LoRA` artifact value.
257    pub value: u16,
258    /// Exact native target-resolution implementation.
259    pub target: Digest,
260    /// Exact pre-denoiser scale schedule.
261    pub scales: ScaleSchedule,
262}
263
264/// Mechanical role of one value produced by a native stage.
265#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
266#[serde(rename_all = "kebab-case", tag = "kind")]
267pub enum ImageProgramNativeOutputRoleV1 {
268    /// Primary image or tensor result.
269    Primary,
270    /// Post-Euler checkpoint state captured at the declared boundary.
271    CheckpointState,
272    /// Tensor snapshot for one zero-based observation request.
273    Observation {
274        /// Observation request index.
275        observation: u16,
276    },
277}
278
279/// One typed value produced by a native image stage.
280#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
281#[serde(deny_unknown_fields)]
282pub struct ImageProgramNativeOutputV1 {
283    /// Mechanical output role.
284    pub role: ImageProgramNativeOutputRoleV1,
285    /// New logical value receiving the result.
286    pub value: u16,
287}
288
289/// One exact diffusion or direct-VAE operation inside a resident program.
290#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
291#[serde(deny_unknown_fields)]
292pub struct ImageProgramNativeStageV1 {
293    /// Exact compatible profile descriptor.
294    pub profile: Digest,
295    /// Exact resident load identity.
296    pub load: Digest,
297    /// Native image operation.
298    pub operation: ImageOperation,
299    /// Output width.
300    pub width: u32,
301    /// Output height.
302    pub height: u32,
303    /// Requested primary representation.
304    pub output_format: ImageOutputFormat,
305    /// Exact seed policy.
306    pub seed: SeedSelection,
307    /// Exact RNG implementation.
308    pub rng: Digest,
309    /// Exact placement selected at load.
310    pub placement: Digest,
311    /// Diffusion schedule, present exactly for diffusion operations.
312    pub schedule: Option<DiffusionSchedule>,
313    /// Exact IEEE-754 guidance scale bits.
314    pub guidance_scale_bits: u32,
315    /// Exact IEEE-754 source-image strength bits.
316    pub strength_bits: u32,
317    /// Earlier values bound to native input roles.
318    pub inputs: Vec<ImageProgramInputBindingV1>,
319    /// Ordered scheduled adapter stack.
320    pub loras: Vec<ImageProgramLoraV1>,
321    /// Ordered installed tensor operators.
322    pub operators: Vec<OperatorInvocation>,
323    /// Ordered tensor observations.
324    pub observations: Vec<ObservationRequest>,
325    /// Optional zero-based post-Euler boundary at which an input checkpoint
326    /// state replaces the recomputed prefix.
327    pub checkpoint_restore_at_step: Option<u32>,
328    /// Optional zero-based post-Euler boundary captured as checkpoint state.
329    pub checkpoint_after_step: Option<u32>,
330    /// Canonically ordered primary, checkpoint, and snapshot outputs.
331    pub outputs: Vec<ImageProgramNativeOutputV1>,
332}
333
334impl ImageProgramNativeStageV1 {
335    /// Returns the exact guidance scale.
336    pub fn guidance_scale(&self) -> f32 {
337        f32::from_bits(self.guidance_scale_bits)
338    }
339
340    /// Returns the exact source-image strength.
341    pub fn strength(&self) -> f32 {
342        f32::from_bits(self.strength_bits)
343    }
344
345    fn references(&self) -> impl Iterator<Item = u16> + '_ {
346        self.inputs
347            .iter()
348            .map(|input| input.value)
349            .chain(self.loras.iter().map(|lora| lora.value))
350    }
351
352    fn output_values(&self) -> impl Iterator<Item = u16> + '_ {
353        self.outputs.iter().map(|output| output.value)
354    }
355
356    fn validate_for(&self, values: &[ImageProgramValueV1]) -> Result<(), CoreError> {
357        self.validate_scalars()?;
358        if self.inputs.len() > crate::MAX_IMAGE_BUFFERS
359            || self.loras.len() > MAX_IMAGE_LORAS
360            || self.operators.len() > MAX_IMAGE_OPERATORS
361            || self.observations.len() > MAX_IMAGE_OBSERVATIONS
362        {
363            return Err(CoreError::invalid(
364                "image program native stage",
365                "a public collection bound was exceeded",
366            ));
367        }
368        let mut roles = Vec::new();
369        for input in &self.inputs {
370            if roles.contains(&input.role) && is_singleton_role(input.role) {
371                return Err(CoreError::invalid(
372                    "image program native inputs",
373                    "a singleton role was repeated",
374                ));
375            }
376            roles.push(input.role);
377            let spec = value_spec(values, input.value)?;
378            validate_role_spec(input.role, spec, self.width, self.height)?;
379        }
380        self.validate_required_inputs()?;
381        let step_count = self.schedule.as_ref().map_or(0, DiffusionSchedule::steps);
382        if self.operation.uses_diffusion() != self.schedule.is_some() {
383            return Err(CoreError::invalid(
384                "image program native schedule",
385                "must be present exactly for diffusion operations",
386            ));
387        }
388        if let Some(schedule) = &self.schedule {
389            schedule.validate()?;
390        }
391        for lora in &self.loras {
392            if !matches!(
393                value_spec(values, lora.value)?,
394                ImageProgramValueSpecV1::Opaque {
395                    opaque_kind: ImageOpaqueValueKindV1::LoraArtifact,
396                    ..
397                }
398            ) {
399                return Err(CoreError::invalid(
400                    "image program LoRA",
401                    "must reference an opaque LoRA artifact value",
402                ));
403            }
404            lora.scales.validate_for(step_count)?;
405        }
406        self.validate_checkpoint_restore_binding()?;
407        if !self.operation.uses_diffusion()
408            && (!self.loras.is_empty()
409                || !self.operators.is_empty()
410                || !self.observations.is_empty()
411                || self.checkpoint_restore_at_step.is_some()
412                || self.checkpoint_after_step.is_some()
413                || self
414                    .inputs
415                    .iter()
416                    .any(|input| input.role == ImageBufferRole::Checkpoint))
417        {
418            return Err(CoreError::invalid(
419                "image program VAE stage",
420                "cannot carry diffusion-scoped mechanics",
421            ));
422        }
423        for operator in &self.operators {
424            operator.validate_for(step_count)?;
425        }
426        for observation in &self.observations {
427            observation.validate_for(step_count)?;
428        }
429        self.validate_snapshot_order()?;
430        if [self.checkpoint_restore_at_step, self.checkpoint_after_step]
431            .into_iter()
432            .flatten()
433            .any(|step| usize::try_from(step).map_or(true, |step| step >= step_count))
434        {
435            return Err(CoreError::invalid(
436                "image program checkpoint boundary",
437                "must name an in-range post-Euler step",
438            ));
439        }
440        self.validate_outputs(values)?;
441        self.validate_checkpoint_compatibility(values)
442    }
443
444    fn validate_snapshot_order(&self) -> Result<(), CoreError> {
445        let snapshot_steps = self.observations.iter().filter_map(|observation| {
446            if observation.kind != ObservationKind::Snapshot {
447                return None;
448            }
449            match &observation.steps {
450                StepSelector::Exact { steps } => steps.first().copied(),
451                StepSelector::All => None,
452            }
453        });
454        if snapshot_steps
455            .scan(None, |previous, step| {
456                let ordered = previous.is_none_or(|previous| previous < step);
457                *previous = Some(step);
458                Some(ordered)
459            })
460            .all(|ordered| ordered)
461        {
462            return Ok(());
463        }
464        Err(CoreError::invalid(
465            "image snapshot observations",
466            "must name strictly increasing distinct boundaries",
467        ))
468    }
469
470    fn validate_required_inputs(&self) -> Result<(), CoreError> {
471        let has = |role| self.inputs.iter().any(|input| input.role == role);
472        let needs_source = matches!(
473            self.operation,
474            ImageOperation::ImageToImage
475                | ImageOperation::Inpaint
476                | ImageOperation::Outpaint
477                | ImageOperation::VaeEncode
478        );
479        let needs_mask = matches!(
480            self.operation,
481            ImageOperation::Inpaint | ImageOperation::Outpaint
482        );
483        if (self.operation.uses_diffusion() && !has(ImageBufferRole::PositiveConditioning))
484            || (needs_source && !has(ImageBufferRole::SourceImage))
485            || (needs_mask && !has(ImageBufferRole::Mask))
486            || (self.operation == ImageOperation::VaeDecode
487                && !has(ImageBufferRole::TensorSnapshot))
488        {
489            return Err(CoreError::invalid(
490                "image program native inputs",
491                "a required operation input is missing",
492            ));
493        }
494        Ok(())
495    }
496
497    fn validate_checkpoint_restore_binding(&self) -> Result<(), CoreError> {
498        let checkpoint_inputs = self
499            .inputs
500            .iter()
501            .filter(|input| input.role == ImageBufferRole::Checkpoint)
502            .count();
503        if checkpoint_inputs != usize::from(self.checkpoint_restore_at_step.is_some()) {
504            return Err(CoreError::invalid(
505                "image program checkpoint restore",
506                "must bind exactly one state value when a restore boundary is declared",
507            ));
508        }
509        Ok(())
510    }
511
512    fn validate_scalars(&self) -> Result<(), CoreError> {
513        validate_dimensions(self.width, self.height)?;
514        if !self.guidance_scale().is_finite()
515            || !self.strength().is_finite()
516            || !(0.0..=1.0).contains(&self.strength())
517        {
518            return Err(CoreError::invalid(
519                "image program native scalar",
520                "guidance must be finite and strength must be finite within 0..=1",
521            ));
522        }
523        let output_compatible = match self.operation {
524            ImageOperation::VaeEncode => self.output_format == ImageOutputFormat::Tensor,
525            _ => matches!(
526                self.output_format,
527                ImageOutputFormat::Rgb8 | ImageOutputFormat::Rgba8 | ImageOutputFormat::Png
528            ),
529        };
530        if !output_compatible {
531            return Err(CoreError::invalid(
532                "image program native output",
533                "format is unsupported or incompatible with the operation",
534            ));
535        }
536        let strength_compatible = match self.operation {
537            ImageOperation::TextToImage | ImageOperation::VaeEncode | ImageOperation::VaeDecode => {
538                self.strength_bits == 1.0_f32.to_bits()
539            }
540            ImageOperation::ImageToImage | ImageOperation::Inpaint | ImageOperation::Outpaint => {
541                self.strength() > 0.0
542            }
543        };
544        if !strength_compatible {
545            return Err(CoreError::invalid(
546                "image program native strength",
547                "is not canonical for the selected operation",
548            ));
549        }
550        Ok(())
551    }
552
553    fn validate_outputs(&self, values: &[ImageProgramValueV1]) -> Result<(), CoreError> {
554        let expected_count = 1
555            + usize::from(self.checkpoint_after_step.is_some())
556            + self
557                .observations
558                .iter()
559                .filter(|request| request.kind == ObservationKind::Snapshot)
560                .count();
561        if self.outputs.len() != expected_count
562            || self.outputs.first().map(|output| output.role)
563                != Some(ImageProgramNativeOutputRoleV1::Primary)
564        {
565            return Err(CoreError::invalid(
566                "image program native outputs",
567                "must contain one primary followed by every declared state or snapshot",
568            ));
569        }
570        let primary = value_spec(values, self.outputs[0].value)?;
571        validate_primary_output(
572            self.operation,
573            self.output_format,
574            self.width,
575            self.height,
576            primary,
577        )?;
578        let mut cursor = 1;
579        if self.checkpoint_after_step.is_some() {
580            let Some(output) = self.outputs.get(cursor) else {
581                return Err(CoreError::invalid(
582                    "image program checkpoint output",
583                    "is missing",
584                ));
585            };
586            if output.role != ImageProgramNativeOutputRoleV1::CheckpointState
587                || !matches!(
588                    value_spec(values, output.value)?,
589                    ImageProgramValueSpecV1::Opaque {
590                        opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
591                        ..
592                    }
593                )
594            {
595                return Err(CoreError::invalid(
596                    "image program checkpoint output",
597                    "must be a checkpoint-state value in canonical position",
598                ));
599            }
600            cursor += 1;
601        }
602        for (index, observation) in self.observations.iter().enumerate() {
603            if observation.kind != ObservationKind::Snapshot {
604                continue;
605            }
606            let observation = u16::try_from(index).map_err(|_| {
607                CoreError::invalid("image program observation output", "index exceeds u16")
608            })?;
609            let Some(output) = self.outputs.get(cursor) else {
610                return Err(CoreError::invalid(
611                    "image program observation output",
612                    "is missing",
613                ));
614            };
615            if output.role != (ImageProgramNativeOutputRoleV1::Observation { observation })
616                || !matches!(
617                    value_spec(values, output.value)?,
618                    ImageProgramValueSpecV1::Tensor { .. }
619                )
620            {
621                return Err(CoreError::invalid(
622                    "image program observation output",
623                    "must be a tensor in request order",
624                ));
625            }
626            cursor += 1;
627        }
628        Ok(())
629    }
630
631    fn validate_checkpoint_compatibility(
632        &self,
633        values: &[ImageProgramValueV1],
634    ) -> Result<(), CoreError> {
635        let restored = self
636            .inputs
637            .iter()
638            .find(|input| input.role == ImageBufferRole::Checkpoint)
639            .map(|input| checkpoint_state_compatibility(values, input.value))
640            .transpose()?;
641        let captured = self
642            .outputs
643            .iter()
644            .find(|output| output.role == ImageProgramNativeOutputRoleV1::CheckpointState)
645            .map(|output| checkpoint_state_compatibility(values, output.value))
646            .transpose()?;
647        if let (Some(restored), Some(captured)) = (restored, captured)
648            && restored != captured
649        {
650            return Err(CoreError::invalid(
651                "image program checkpoint state",
652                "restored and captured compatibility domains differ",
653            ));
654        }
655        Ok(())
656    }
657}
658
659/// One ordered resident program operation.
660#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
661#[serde(rename_all = "kebab-case", tag = "kind")]
662pub enum ImageProgramStageOperationV1 {
663    /// Diffusion or direct-VAE work performed by the resident native runtime.
664    Native {
665        /// Exact native-stage mechanics.
666        plan: Box<ImageProgramNativeStageV1>,
667    },
668    /// Exact deterministic RGB8 mask blend.
669    MaskBlend {
670        /// Earlier RGB8 base value.
671        base: u16,
672        /// Earlier RGB8 overlay value.
673        overlay: u16,
674        /// Earlier Gray8 mask value.
675        mask: u16,
676        /// New RGB8 output value.
677        output: u16,
678    },
679    /// Deserialize an authenticated checkpoint into request-local native state.
680    RestoreCheckpoint {
681        /// Earlier serialized checkpoint value.
682        checkpoint: u16,
683        /// New opaque checkpoint-state value.
684        state: u16,
685        /// Exact restore implementation identity.
686        implementation: Digest,
687    },
688    /// Serialize request-local native state into an authenticated checkpoint.
689    CaptureCheckpoint {
690        /// Earlier opaque checkpoint-state value.
691        state: u16,
692        /// New serialized checkpoint value.
693        checkpoint: u16,
694        /// Exact capture implementation identity.
695        implementation: Digest,
696    },
697}
698
699impl ImageProgramStageOperationV1 {
700    /// Returns logical values consumed by this operation in canonical order.
701    pub fn referenced_values(&self) -> Vec<u16> {
702        self.references()
703    }
704
705    /// Returns logical values produced by this operation in canonical order.
706    pub fn produced_values(&self) -> Vec<u16> {
707        self.outputs()
708    }
709
710    fn references(&self) -> Vec<u16> {
711        match self {
712            Self::Native { plan } => plan.references().collect(),
713            Self::MaskBlend {
714                base,
715                overlay,
716                mask,
717                ..
718            } => vec![*base, *overlay, *mask],
719            Self::RestoreCheckpoint { checkpoint, .. } => vec![*checkpoint],
720            Self::CaptureCheckpoint { state, .. } => vec![*state],
721        }
722    }
723
724    fn outputs(&self) -> Vec<u16> {
725        match self {
726            Self::Native { plan } => plan.output_values().collect(),
727            Self::MaskBlend { output, .. } => vec![*output],
728            Self::RestoreCheckpoint { state, .. } => vec![*state],
729            Self::CaptureCheckpoint { checkpoint, .. } => vec![*checkpoint],
730        }
731    }
732
733    fn validate_types(&self, values: &[ImageProgramValueV1]) -> Result<(), CoreError> {
734        match self {
735            Self::Native { plan } => plan.validate_for(values),
736            Self::MaskBlend {
737                base,
738                overlay,
739                mask,
740                output,
741            } => validate_mask_blend(values, *base, *overlay, *mask, *output),
742            Self::RestoreCheckpoint {
743                checkpoint, state, ..
744            } => validate_checkpoint_conversion(values, *checkpoint, *state, true),
745            Self::CaptureCheckpoint {
746                state, checkpoint, ..
747            } => validate_checkpoint_conversion(values, *checkpoint, *state, false),
748        }
749    }
750
751    /// Returns the identity of this exact stage operation.
752    ///
753    /// # Errors
754    ///
755    /// Returns an error when deterministic serialization fails.
756    pub fn digest(&self) -> Result<Digest, CoreError> {
757        Digest::of_serializable("image-program-stage-operation-v1", self)
758    }
759}
760
761/// One ordered stage in a resident image program.
762#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
763#[serde(deny_unknown_fields)]
764pub struct ImageProgramStageV1 {
765    /// Zero-based stage index.
766    pub stage: u16,
767    /// Exact stage mechanics.
768    pub operation: ImageProgramStageOperationV1,
769}
770
771/// Value selected for one caller-owned output allocation.
772#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
773#[serde(rename_all = "kebab-case", tag = "kind")]
774pub enum ImageProgramOutputSourceV1 {
775    /// One typed logical value.
776    Value {
777        /// Value to materialize.
778        value: u16,
779    },
780    /// Deterministic program receipt serialized after execution.
781    ProgramReceipt,
782}
783
784/// One ordered caller-owned output route.
785#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
786#[serde(deny_unknown_fields)]
787pub struct ImageProgramOutputRouteV1 {
788    /// Zero-based route index.
789    pub route: u16,
790    /// Exact source written to the route.
791    pub source: ImageProgramOutputSourceV1,
792    /// Exact writable output allocation.
793    pub buffer: BufferSpec,
794}
795
796/// Release point derived for one logical program value.
797#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
798#[serde(deny_unknown_fields)]
799pub struct ImageProgramReleaseV1 {
800    /// Value released after its final consumer.
801    pub value: u16,
802    /// Stage after which release occurs, or `None` after output materialization.
803    pub after_stage: Option<u16>,
804}
805
806/// Conservative preflight value-arena accounting.
807#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
808#[serde(deny_unknown_fields)]
809pub struct ImageProgramLivenessV1 {
810    /// Maximum sum of declared live-value byte bounds.
811    pub peak_bytes: u64,
812    /// Canonical value-release order.
813    pub releases: Vec<ImageProgramReleaseV1>,
814}
815
816/// Complete bounded resident image program.
817#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
818#[serde(deny_unknown_fields)]
819pub struct ImageProgramPlanV1 {
820    /// Canonically numbered logical values.
821    pub values: Vec<ImageProgramValueV1>,
822    /// External value producers.
823    pub inputs: Vec<ImageProgramInputV1>,
824    /// Ordered native and deterministic stages.
825    pub stages: Vec<ImageProgramStageV1>,
826    /// Ordered caller-owned output routes.
827    pub outputs: Vec<ImageProgramOutputRouteV1>,
828    /// Request-scope resident-session cleanup policy.
829    pub cleanup: ImageCleanupPolicy,
830}
831
832impl ImageProgramPlanV1 {
833    /// Validates the complete typed graph and its conservative arena bound.
834    ///
835    /// # Errors
836    ///
837    /// Returns the first collection, type, producer, ordering, routing, or
838    /// liveness defect.
839    pub fn validate(&self) -> Result<(), CoreError> {
840        self.validate_collections_and_values()?;
841        let producers = self.validate_producers_and_stages()?;
842        let consumers = self.validate_outputs_and_consumers(&producers)?;
843        let liveness = self.compute_liveness(&consumers)?;
844        if liveness.peak_bytes > MAX_IMAGE_PROGRAM_ARENA_BYTES {
845            return Err(CoreError::invalid(
846                "image program arena",
847                format!("exceeds {MAX_IMAGE_PROGRAM_ARENA_BYTES} live bytes"),
848            ));
849        }
850        Ok(())
851    }
852
853    /// Computes canonical value release points and peak declared live bytes.
854    ///
855    /// # Errors
856    ///
857    /// Returns an error when the complete program is invalid.
858    pub fn liveness(&self) -> Result<ImageProgramLivenessV1, CoreError> {
859        self.validate_collections_and_values()?;
860        let producers = self.validate_producers_and_stages()?;
861        let consumers = self.validate_outputs_and_consumers(&producers)?;
862        let liveness = self.compute_liveness(&consumers)?;
863        if liveness.peak_bytes > MAX_IMAGE_PROGRAM_ARENA_BYTES {
864            return Err(CoreError::invalid(
865                "image program arena",
866                format!("exceeds {MAX_IMAGE_PROGRAM_ARENA_BYTES} live bytes"),
867            ));
868        }
869        Ok(liveness)
870    }
871
872    /// Returns the identity of this exact resident program.
873    ///
874    /// # Errors
875    ///
876    /// Returns a validation or deterministic serialization error.
877    pub fn digest(&self) -> Result<Digest, CoreError> {
878        self.validate()?;
879        Digest::of_serializable("image-program-plan-v1", self)
880    }
881
882    fn validate_collections_and_values(&self) -> Result<(), CoreError> {
883        if self.values.is_empty()
884            || self.values.len() > MAX_IMAGE_PROGRAM_VALUES
885            || self.inputs.is_empty()
886            || self.inputs.len() > MAX_IMAGE_PROGRAM_INPUTS
887            || self.stages.is_empty()
888            || self.stages.len() > MAX_IMAGE_PROGRAM_STAGES
889            || self.outputs.is_empty()
890            || self.outputs.len() > MAX_IMAGE_PROGRAM_OUTPUTS
891        {
892            return Err(CoreError::invalid(
893                "image program collections",
894                "a required collection is empty or exceeds its public bound",
895            ));
896        }
897        for (index, value) in self.values.iter().enumerate() {
898            if usize::from(value.value) != index {
899                return Err(CoreError::invalid(
900                    "image program values",
901                    "identifiers must be contiguous and declared in order",
902                ));
903            }
904            value.spec.validate()?;
905        }
906        Ok(())
907    }
908
909    fn validate_producers_and_stages(&self) -> Result<Vec<Option<Producer>>, CoreError> {
910        let mut producers = vec![None; self.values.len()];
911        let mut input_allocations = HashSet::new();
912        for input in &self.inputs {
913            input.buffer.validate()?;
914            value_spec(&self.values, input.value)?
915                .validate_buffer_length(input.buffer.byte_length)?;
916            if !input_allocations.insert(input.buffer.identity.clone()) {
917                return Err(CoreError::invalid(
918                    "image program inputs",
919                    "allocation identities must be unique",
920                ));
921            }
922            assign_producer(&mut producers, input.value, Producer::Input)?;
923        }
924        for (index, stage) in self.stages.iter().enumerate() {
925            if usize::from(stage.stage) != index {
926                return Err(CoreError::invalid(
927                    "image program stages",
928                    "indices must be contiguous and declared in execution order",
929                ));
930            }
931            for reference in stage.operation.references() {
932                let Some(producer) = producer_at(&producers, reference)? else {
933                    return Err(CoreError::invalid(
934                        "image program stage reference",
935                        "must name an external input or an earlier stage output",
936                    ));
937                };
938                if matches!(producer, Producer::Stage(producer) if producer >= index) {
939                    return Err(CoreError::invalid(
940                        "image program stage reference",
941                        "must name a value produced by an earlier stage",
942                    ));
943                }
944            }
945            stage.operation.validate_types(&self.values)?;
946            let mut stage_outputs = HashSet::new();
947            for output in stage.operation.outputs() {
948                if !stage_outputs.insert(output) {
949                    return Err(CoreError::invalid(
950                        "image program stage outputs",
951                        "a stage cannot produce one value more than once",
952                    ));
953                }
954                assign_producer(&mut producers, output, Producer::Stage(index))?;
955            }
956        }
957        if producers.iter().any(Option::is_none) {
958            return Err(CoreError::invalid(
959                "image program values",
960                "every declared value must have exactly one producer",
961            ));
962        }
963        Ok(producers)
964    }
965
966    fn validate_outputs_and_consumers(
967        &self,
968        producers: &[Option<Producer>],
969    ) -> Result<Vec<Vec<usize>>, CoreError> {
970        let mut consumers = vec![Vec::new(); self.values.len()];
971        for (stage_index, stage) in self.stages.iter().enumerate() {
972            for reference in stage.operation.references() {
973                consumers
974                    .get_mut(usize::from(reference))
975                    .ok_or_else(|| {
976                        CoreError::invalid("image program consumer", "value is outside the plan")
977                    })?
978                    .push(stage_index);
979            }
980        }
981        self.validate_output_routes(&mut consumers)?;
982        for (index, value_consumers) in consumers.iter().enumerate() {
983            if value_consumers.is_empty() {
984                return Err(CoreError::invalid(
985                    "image program value",
986                    "every input and stage output must have a consumer",
987                ));
988            }
989            if matches!(
990                self.values[index].spec,
991                ImageProgramValueSpecV1::Opaque {
992                    opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
993                    ..
994                }
995            ) && value_consumers.len() != 1
996            {
997                return Err(CoreError::invalid(
998                    "image program checkpoint state",
999                    "must have exactly one mutable consumer",
1000                ));
1001            }
1002            let producer = producers[index]
1003                .ok_or_else(|| CoreError::invalid("image program value", "producer is missing"))?;
1004            if let Producer::Stage(stage) = producer
1005                && value_consumers.iter().any(|consumer| *consumer <= stage)
1006            {
1007                return Err(CoreError::invalid(
1008                    "image program value",
1009                    "cannot be consumed before it is produced",
1010                ));
1011            }
1012        }
1013        Ok(consumers)
1014    }
1015
1016    fn validate_output_routes(&self, consumers: &mut [Vec<usize>]) -> Result<(), CoreError> {
1017        let output_boundary = self.stages.len();
1018        let mut allocations = self
1019            .inputs
1020            .iter()
1021            .map(|input| input.buffer.identity.clone())
1022            .collect::<HashSet<_>>();
1023        let mut routed_values = HashSet::new();
1024        let mut receipt_routes = 0;
1025        for (index, route) in self.outputs.iter().enumerate() {
1026            if usize::from(route.route) != index {
1027                return Err(CoreError::invalid(
1028                    "image program outputs",
1029                    "route indices must be contiguous and declared in order",
1030                ));
1031            }
1032            route.buffer.validate()?;
1033            if !allocations.insert(route.buffer.identity.clone()) {
1034                return Err(CoreError::invalid(
1035                    "image program outputs",
1036                    "output allocations must not alias an input or another output",
1037                ));
1038            }
1039            match route.source {
1040                ImageProgramOutputSourceV1::Value { value } => {
1041                    let spec = value_spec(&self.values, value)?;
1042                    if matches!(
1043                        spec,
1044                        ImageProgramValueSpecV1::Opaque {
1045                            opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
1046                            ..
1047                        }
1048                    ) || !routed_values.insert(value)
1049                    {
1050                        return Err(CoreError::invalid(
1051                            "image program output value",
1052                            "must be a uniquely routed serializable value",
1053                        ));
1054                    }
1055                    spec.validate_buffer_length(route.buffer.byte_length)?;
1056                    consumers[usize::from(value)].push(output_boundary);
1057                }
1058                ImageProgramOutputSourceV1::ProgramReceipt => {
1059                    receipt_routes += 1;
1060                    if index + 1 != self.outputs.len()
1061                        || route.buffer.byte_length > MAX_IMAGE_PROGRAM_VALUE_BYTES
1062                    {
1063                        return Err(CoreError::invalid(
1064                            "image program receipt output",
1065                            "must be the single final bounded route",
1066                        ));
1067                    }
1068                }
1069            }
1070        }
1071        if receipt_routes != 1 {
1072            return Err(CoreError::invalid(
1073                "image program receipt output",
1074                "must be routed exactly once",
1075            ));
1076        }
1077        Ok(())
1078    }
1079
1080    fn compute_liveness(
1081        &self,
1082        consumers: &[Vec<usize>],
1083    ) -> Result<ImageProgramLivenessV1, CoreError> {
1084        let mut live = vec![false; self.values.len()];
1085        let mut bytes = 0_u64;
1086        for input in &self.inputs {
1087            add_live_value(&self.values, &mut live, &mut bytes, input.value)?;
1088        }
1089        let mut peak_bytes = bytes;
1090        let mut releases = Vec::with_capacity(self.values.len());
1091        for (stage_index, stage) in self.stages.iter().enumerate() {
1092            for output in stage.operation.outputs() {
1093                add_live_value(&self.values, &mut live, &mut bytes, output)?;
1094            }
1095            peak_bytes = peak_bytes.max(bytes);
1096            for (value, value_consumers) in consumers.iter().enumerate() {
1097                if live[value] && value_consumers.iter().max() == Some(&stage_index) {
1098                    release_live_value(
1099                        &self.values,
1100                        &mut live,
1101                        &mut bytes,
1102                        value,
1103                        Some(stage_index),
1104                        &mut releases,
1105                    )?;
1106                }
1107            }
1108        }
1109        let output_boundary = self.stages.len();
1110        for (value, value_consumers) in consumers.iter().enumerate() {
1111            if live[value] && value_consumers.iter().max() == Some(&output_boundary) {
1112                release_live_value(
1113                    &self.values,
1114                    &mut live,
1115                    &mut bytes,
1116                    value,
1117                    None,
1118                    &mut releases,
1119                )?;
1120            }
1121        }
1122        if bytes != 0 || live.iter().any(|is_live| *is_live) {
1123            return Err(CoreError::invalid(
1124                "image program liveness",
1125                "not every produced value reached its final consumer",
1126            ));
1127        }
1128        Ok(ImageProgramLivenessV1 {
1129            peak_bytes,
1130            releases,
1131        })
1132    }
1133}
1134
1135#[derive(Clone, Copy, Debug, PartialEq, Eq)]
1136enum Producer {
1137    Input,
1138    Stage(usize),
1139}
1140
1141/// Exact content identity and initialized length of one produced value.
1142#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1143#[serde(deny_unknown_fields)]
1144pub struct ImageProgramValueReceiptV1 {
1145    /// Produced logical value.
1146    pub value: u16,
1147    /// Exact initialized content identity.
1148    pub content: Digest,
1149    /// Exact initialized byte length.
1150    pub bytes: u64,
1151}
1152
1153/// Deterministic receipt for one completed program stage.
1154#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1155#[serde(deny_unknown_fields)]
1156pub struct ImageProgramStageReceiptV1 {
1157    /// Zero-based completed stage index.
1158    pub stage: u16,
1159    /// Exact stage-operation identity.
1160    pub operation: Digest,
1161    /// Produced values in the operation's canonical output order.
1162    pub outputs: Vec<ImageProgramValueReceiptV1>,
1163    /// Observation result identities in request order.
1164    pub observations: Vec<Digest>,
1165}
1166
1167/// Exact initialized output accounting.
1168#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1169#[serde(deny_unknown_fields)]
1170pub struct ImageProgramOutputReceiptV1 {
1171    /// Zero-based output route.
1172    pub route: u16,
1173    /// Caller-owned allocation identity.
1174    pub allocation: Digest,
1175    /// Exact content identity, absent only for the self-containing receipt route.
1176    pub content: Option<Digest>,
1177    /// Exact initialized prefix length.
1178    pub bytes_written: u64,
1179}
1180
1181/// Terminal boundary reached by one resident image program.
1182#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1183#[serde(rename_all = "kebab-case", tag = "kind")]
1184pub enum ImageProgramTerminalV1 {
1185    /// Every stage and output route completed.
1186    Completed,
1187    /// Cancellation was observed before request-local state existed.
1188    CancelledBeforeStart,
1189    /// Cancellation was observed after one completed stage.
1190    CancelledAfterStage {
1191        /// Last completed stage.
1192        stage: u16,
1193    },
1194    /// Cancellation was observed inside a native stage at a post-Euler boundary.
1195    CancelledAfterStep {
1196        /// Native stage that did not complete.
1197        stage: u16,
1198        /// Zero-based completed Euler transition.
1199        step: u32,
1200    },
1201    /// One stage failed before publishing its outputs.
1202    FailedAtStage {
1203        /// Stage that did not complete.
1204        stage: u16,
1205        /// Complete stage failure detail.
1206        failure: String,
1207    },
1208    /// Cleanup or resident-state certainty was lost.
1209    CleanupUncertain {
1210        /// Last completed stage, or `None` when no stage completed.
1211        after_stage: Option<u16>,
1212        /// Complete cleanup failure detail.
1213        failure: String,
1214    },
1215}
1216
1217/// Observed cleanup outcome for one resident image program.
1218#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1219#[serde(rename_all = "kebab-case", tag = "kind")]
1220pub enum ImageProgramCleanupDispositionV1 {
1221    /// The plan retained a known resident session.
1222    Retained,
1223    /// Cleanup was confirmed for one prior runtime epoch.
1224    Confirmed {
1225        /// Runtime epoch invalidated by cleanup.
1226        cleared_epoch: u64,
1227    },
1228    /// Cancellation preceded request-local state.
1229    NotRequired,
1230    /// Cleanup or state release could not be verified.
1231    Uncertain {
1232        /// Complete cleanup failure detail.
1233        failure: String,
1234    },
1235}
1236
1237/// Deterministic mechanical receipt for one resident image program.
1238#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1239#[serde(deny_unknown_fields)]
1240pub struct ImageProgramReceiptV1 {
1241    /// Exact program-plan identity.
1242    pub plan: Digest,
1243    /// Exact backend build/runtime identity.
1244    pub backend: Digest,
1245    /// Runtime epoch used by native handles.
1246    pub runtime_epoch: u64,
1247    /// Number of completely published stages.
1248    pub completed_stages: u16,
1249    /// Completed stage receipts as an ordered prefix.
1250    pub stages: Vec<ImageProgramStageReceiptV1>,
1251    /// Completed output writes in route order.
1252    pub outputs: Vec<ImageProgramOutputReceiptV1>,
1253    /// Terminal program boundary.
1254    pub terminal: ImageProgramTerminalV1,
1255    /// Observed cleanup outcome.
1256    pub cleanup: ImageProgramCleanupDispositionV1,
1257}
1258
1259impl ImageProgramReceiptV1 {
1260    /// Validates plan lineage, stage prefix, output writes, terminal position,
1261    /// and cleanup disposition.
1262    ///
1263    /// # Errors
1264    ///
1265    /// Returns the first inconsistency with the exact program.
1266    pub fn validate_for(&self, plan: &ImageProgramPlanV1) -> Result<(), CoreError> {
1267        plan.validate()?;
1268        if self.plan != plan.digest()? || usize::from(self.completed_stages) != self.stages.len() {
1269            return Err(CoreError::invalid(
1270                "image program receipt",
1271                "plan identity or completed-stage count differs",
1272            ));
1273        }
1274        let mut contents = plan
1275            .inputs
1276            .iter()
1277            .map(|input| {
1278                (
1279                    input.value,
1280                    (input.buffer.identity.clone(), input.buffer.byte_length),
1281                )
1282            })
1283            .collect::<HashMap<_, _>>();
1284        for (index, receipt) in self.stages.iter().enumerate() {
1285            let stage = plan.stages.get(index).ok_or_else(|| {
1286                CoreError::invalid("image program stage receipt", "exceeds the plan")
1287            })?;
1288            let expected_outputs = stage.operation.outputs();
1289            let expected_observations = match &stage.operation {
1290                ImageProgramStageOperationV1::Native { plan } => plan.observations.len(),
1291                _ => 0,
1292            };
1293            if usize::from(receipt.stage) != index
1294                || receipt.operation != stage.operation.digest()?
1295                || receipt.outputs.len() != expected_outputs.len()
1296                || receipt.observations.len() != expected_observations
1297            {
1298                return Err(CoreError::invalid(
1299                    "image program stage receipt",
1300                    "is not the exact completed operation prefix",
1301                ));
1302            }
1303            for (output, expected) in receipt.outputs.iter().zip(expected_outputs) {
1304                if output.value != expected {
1305                    return Err(CoreError::invalid(
1306                        "image program value receipt",
1307                        "value order differs from the stage operation",
1308                    ));
1309                }
1310                value_spec(&plan.values, output.value)?.validate_buffer_length(output.bytes)?;
1311                if contents
1312                    .insert(output.value, (output.content.clone(), output.bytes))
1313                    .is_some()
1314                {
1315                    return Err(CoreError::invalid(
1316                        "image program value receipt",
1317                        "published a value more than once",
1318                    ));
1319                }
1320            }
1321        }
1322        self.validate_terminal(plan)?;
1323        self.validate_outputs(plan, &contents)?;
1324        self.validate_cleanup(plan)
1325    }
1326
1327    /// Returns the identity of this exact deterministic receipt.
1328    ///
1329    /// # Errors
1330    ///
1331    /// Returns a validation or deterministic serialization error.
1332    pub fn digest_for(&self, plan: &ImageProgramPlanV1) -> Result<Digest, CoreError> {
1333        self.validate_for(plan)?;
1334        Digest::of_serializable("image-program-receipt-v1", self)
1335    }
1336
1337    fn validate_terminal(&self, plan: &ImageProgramPlanV1) -> Result<(), CoreError> {
1338        let completed = usize::from(self.completed_stages);
1339        let valid = match self.terminal {
1340            ImageProgramTerminalV1::Completed => completed == plan.stages.len(),
1341            ImageProgramTerminalV1::CancelledBeforeStart => completed == 0,
1342            ImageProgramTerminalV1::CancelledAfterStage { stage } => {
1343                usize::from(stage).checked_add(1) == Some(completed)
1344            }
1345            ImageProgramTerminalV1::CancelledAfterStep { stage, step } => {
1346                usize::from(stage) == completed
1347                    && plan.stages.get(usize::from(stage)).is_some_and(|stage| {
1348                        match &stage.operation {
1349                            ImageProgramStageOperationV1::Native { plan } => {
1350                                plan.schedule.as_ref().is_some_and(|schedule| {
1351                                    usize::try_from(step).is_ok_and(|step| step < schedule.steps())
1352                                })
1353                            }
1354                            _ => false,
1355                        }
1356                    })
1357            }
1358            ImageProgramTerminalV1::FailedAtStage { stage, .. } => {
1359                usize::from(stage) == completed && completed < plan.stages.len()
1360            }
1361            ImageProgramTerminalV1::CleanupUncertain { after_stage, .. } => after_stage
1362                .map_or(completed == 0, |stage| {
1363                    usize::from(stage).checked_add(1) == Some(completed)
1364                }),
1365        };
1366        if !valid {
1367            return Err(CoreError::invalid(
1368                "image program terminal",
1369                "does not match the completed-stage prefix",
1370            ));
1371        }
1372        match &self.terminal {
1373            ImageProgramTerminalV1::FailedAtStage { failure, .. }
1374            | ImageProgramTerminalV1::CleanupUncertain { failure, .. }
1375                if failure.is_empty() =>
1376            {
1377                return Err(CoreError::invalid(
1378                    "image program terminal",
1379                    "failure detail is empty",
1380                ));
1381            }
1382            _ => {}
1383        }
1384        if self.terminal == ImageProgramTerminalV1::Completed {
1385            if self.outputs.len() != plan.outputs.len() {
1386                return Err(CoreError::invalid(
1387                    "image program receipt",
1388                    "completed terminal requires every output route",
1389                ));
1390            }
1391        } else if !self.outputs.is_empty() {
1392            return Err(CoreError::invalid(
1393                "image program receipt",
1394                "non-completed terminals cannot publish output routes",
1395            ));
1396        }
1397        Ok(())
1398    }
1399
1400    fn validate_outputs(
1401        &self,
1402        plan: &ImageProgramPlanV1,
1403        contents: &HashMap<u16, (Digest, u64)>,
1404    ) -> Result<(), CoreError> {
1405        for (index, output) in self.outputs.iter().enumerate() {
1406            let route = plan.outputs.get(index).ok_or_else(|| {
1407                CoreError::invalid("image program output receipt", "route exceeds the plan")
1408            })?;
1409            if usize::from(output.route) != index
1410                || output.allocation != route.buffer.identity
1411                || output.bytes_written == 0
1412                || output.bytes_written > route.buffer.byte_length
1413            {
1414                return Err(CoreError::invalid(
1415                    "image program output receipt",
1416                    "route, allocation, or initialized length differs",
1417                ));
1418            }
1419            match route.source {
1420                ImageProgramOutputSourceV1::Value { value } => {
1421                    let Some((content, bytes)) = contents.get(&value) else {
1422                        return Err(CoreError::invalid(
1423                            "image program output receipt",
1424                            "source value was not produced",
1425                        ));
1426                    };
1427                    if output.content.as_ref() != Some(content) || output.bytes_written != *bytes {
1428                        return Err(CoreError::invalid(
1429                            "image program output receipt",
1430                            "content or initialized length differs from its value",
1431                        ));
1432                    }
1433                }
1434                ImageProgramOutputSourceV1::ProgramReceipt if output.content.is_none() => {}
1435                ImageProgramOutputSourceV1::ProgramReceipt => {
1436                    return Err(CoreError::invalid(
1437                        "image program output receipt",
1438                        "self-containing receipt route cannot claim its own content digest",
1439                    ));
1440                }
1441            }
1442        }
1443        Ok(())
1444    }
1445
1446    fn validate_cleanup(&self, plan: &ImageProgramPlanV1) -> Result<(), CoreError> {
1447        let valid = match &self.terminal {
1448            ImageProgramTerminalV1::CancelledBeforeStart => {
1449                self.cleanup == ImageProgramCleanupDispositionV1::NotRequired
1450            }
1451            ImageProgramTerminalV1::CleanupUncertain { failure, .. } => matches!(
1452                &self.cleanup,
1453                ImageProgramCleanupDispositionV1::Uncertain {
1454                    failure: cleanup_failure
1455                } if cleanup_failure == failure
1456            ),
1457            ImageProgramTerminalV1::Completed
1458            | ImageProgramTerminalV1::CancelledAfterStage { .. }
1459            | ImageProgramTerminalV1::CancelledAfterStep { .. }
1460            | ImageProgramTerminalV1::FailedAtStage { .. } => matches!(
1461                (plan.cleanup, &self.cleanup),
1462                (
1463                    ImageCleanupPolicy::RetainSession,
1464                    ImageProgramCleanupDispositionV1::Retained
1465                ) | (
1466                    ImageCleanupPolicy::ClearSession,
1467                    ImageProgramCleanupDispositionV1::Confirmed { .. }
1468                )
1469            ),
1470        };
1471        if valid {
1472            Ok(())
1473        } else {
1474            Err(CoreError::invalid(
1475                "image program cleanup",
1476                "disposition differs from the plan or terminal state",
1477            ))
1478        }
1479    }
1480}
1481
1482/// Observed native placement of one logical value.
1483#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1484#[serde(rename_all = "kebab-case", tag = "kind")]
1485pub enum ImageProgramValuePlacementV1 {
1486    /// Value remained in host memory.
1487    Host,
1488    /// Value remained on one exact device.
1489    Device {
1490        /// Adapter-reported device identity.
1491        device: String,
1492    },
1493    /// Value occupied host memory and/or more than one device.
1494    Mixed {
1495        /// Canonical sorted unique device identities.
1496        devices: Vec<String>,
1497    },
1498}
1499
1500impl ImageProgramValuePlacementV1 {
1501    fn validate(&self) -> Result<(), CoreError> {
1502        let valid_device = |device: &str| {
1503            !device.is_empty() && device.len() <= MAX_DEVICE_LABEL_BYTES && !device.contains('\0')
1504        };
1505        match self {
1506            Self::Host => Ok(()),
1507            Self::Device { device } if valid_device(device) => Ok(()),
1508            Self::Mixed { devices }
1509                if !devices.is_empty()
1510                    && devices.iter().all(|device| valid_device(device))
1511                    && devices.windows(2).all(|pair| pair[0] < pair[1]) =>
1512            {
1513                Ok(())
1514            }
1515            _ => Err(CoreError::invalid(
1516                "image program value placement",
1517                "device labels must be bounded, NUL-free, sorted, and unique",
1518            )),
1519        }
1520    }
1521}
1522
1523/// Non-deterministic placement and transfer measurements for one value.
1524#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1525#[serde(deny_unknown_fields)]
1526pub struct ImageProgramValueMeasurementV1 {
1527    /// Logical value.
1528    pub value: u16,
1529    /// Observed native placement.
1530    pub placement: ImageProgramValuePlacementV1,
1531    /// Count of host-to-device transfers.
1532    pub host_to_device_transfers: u64,
1533    /// Host-to-device bytes.
1534    pub host_to_device_bytes: u64,
1535    /// Count of device-to-host transfers.
1536    pub device_to_host_transfers: u64,
1537    /// Device-to-host bytes.
1538    pub device_to_host_bytes: u64,
1539}
1540
1541/// Deployment measurements excluded from deterministic plan and receipt identities.
1542#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1543#[serde(deny_unknown_fields)]
1544pub struct ImageProgramMeasurementsV1 {
1545    /// Exact program-plan identity.
1546    pub plan: Digest,
1547    /// Exact backend build/runtime identity.
1548    pub backend: Digest,
1549    /// Runtime epoch used by native handles.
1550    pub runtime_epoch: u64,
1551    /// Wall time for each completed stage, in nanoseconds.
1552    pub stage_wall_time_ns: Vec<u64>,
1553    /// Native compute time for each completed stage, when available.
1554    pub stage_native_time_ns: Vec<Option<u64>>,
1555    /// Observed peak native value-arena bytes.
1556    pub peak_arena_bytes: u64,
1557    /// Placement and transfer accounting for every value that existed.
1558    pub values: Vec<ImageProgramValueMeasurementV1>,
1559}
1560
1561impl ImageProgramMeasurementsV1 {
1562    /// Validates measurements against one exact receipt without incorporating
1563    /// them into deterministic identity.
1564    ///
1565    /// # Errors
1566    ///
1567    /// Returns the first lineage, count, placement, or byte-bound defect.
1568    pub fn validate_for(
1569        &self,
1570        plan: &ImageProgramPlanV1,
1571        receipt: &ImageProgramReceiptV1,
1572    ) -> Result<(), CoreError> {
1573        receipt.validate_for(plan)?;
1574        if self.plan != plan.digest()?
1575            || self.backend != receipt.backend
1576            || self.runtime_epoch != receipt.runtime_epoch
1577            || self.stage_wall_time_ns.len() != receipt.stages.len()
1578            || self.stage_native_time_ns.len() != receipt.stages.len()
1579            || self.peak_arena_bytes > plan.liveness()?.peak_bytes
1580        {
1581            return Err(CoreError::invalid(
1582                "image program measurements",
1583                "lineage, stage count, or peak bytes differ from execution",
1584            ));
1585        }
1586        let mut expected = plan
1587            .inputs
1588            .iter()
1589            .map(|input| input.value)
1590            .collect::<HashSet<_>>();
1591        for stage in plan.stages.iter().take(receipt.stages.len()) {
1592            expected.extend(stage.operation.outputs());
1593        }
1594        let mut measured = HashSet::new();
1595        for value in &self.values {
1596            value.placement.validate()?;
1597            value_spec(&plan.values, value.value)?;
1598            if !measured.insert(value.value) {
1599                return Err(CoreError::invalid(
1600                    "image program measurements",
1601                    "a value was measured more than once",
1602                ));
1603            }
1604        }
1605        if measured != expected {
1606            return Err(CoreError::invalid(
1607                "image program measurements",
1608                "must describe exactly the values that existed",
1609            ));
1610        }
1611        Ok(())
1612    }
1613}
1614
1615fn value_spec(
1616    values: &[ImageProgramValueV1],
1617    value: u16,
1618) -> Result<&ImageProgramValueSpecV1, CoreError> {
1619    values
1620        .get(usize::from(value))
1621        .map(|value| &value.spec)
1622        .ok_or_else(|| CoreError::invalid("image program value", "identifier is outside the plan"))
1623}
1624
1625fn assign_producer(
1626    producers: &mut [Option<Producer>],
1627    value: u16,
1628    producer: Producer,
1629) -> Result<(), CoreError> {
1630    let entry = producers
1631        .get_mut(usize::from(value))
1632        .ok_or_else(|| CoreError::invalid("image program producer", "value is outside the plan"))?;
1633    if entry.replace(producer).is_some() {
1634        return Err(CoreError::invalid(
1635            "image program producer",
1636            "a value has more than one producer",
1637        ));
1638    }
1639    Ok(())
1640}
1641
1642fn producer_at(producers: &[Option<Producer>], value: u16) -> Result<Option<Producer>, CoreError> {
1643    producers
1644        .get(usize::from(value))
1645        .copied()
1646        .ok_or_else(|| CoreError::invalid("image program reference", "value is outside the plan"))
1647}
1648
1649fn add_live_value(
1650    values: &[ImageProgramValueV1],
1651    live: &mut [bool],
1652    bytes: &mut u64,
1653    value: u16,
1654) -> Result<(), CoreError> {
1655    let index = usize::from(value);
1656    let is_live = live
1657        .get_mut(index)
1658        .ok_or_else(|| CoreError::invalid("image program liveness", "value is outside the plan"))?;
1659    if *is_live {
1660        return Err(CoreError::invalid(
1661            "image program liveness",
1662            "value became live more than once",
1663        ));
1664    }
1665    *bytes = bytes
1666        .checked_add(value_spec(values, value)?.maximum_bytes()?)
1667        .ok_or_else(|| CoreError::invalid("image program liveness", "byte count overflowed"))?;
1668    *is_live = true;
1669    Ok(())
1670}
1671
1672fn release_live_value(
1673    values: &[ImageProgramValueV1],
1674    live: &mut [bool],
1675    bytes: &mut u64,
1676    value: usize,
1677    after_stage: Option<usize>,
1678    releases: &mut Vec<ImageProgramReleaseV1>,
1679) -> Result<(), CoreError> {
1680    *bytes = bytes
1681        .checked_sub(values[value].spec.maximum_bytes()?)
1682        .ok_or_else(|| CoreError::invalid("image program liveness", "byte count underflowed"))?;
1683    live[value] = false;
1684    releases.push(ImageProgramReleaseV1 {
1685        value: u16::try_from(value)
1686            .map_err(|_| CoreError::invalid("image program liveness", "value exceeds u16"))?,
1687        after_stage: after_stage
1688            .map(u16::try_from)
1689            .transpose()
1690            .map_err(|_| CoreError::invalid("image program liveness", "stage exceeds u16"))?,
1691    });
1692    Ok(())
1693}
1694
1695fn validate_variable_bytes(bytes: u64) -> Result<(), CoreError> {
1696    if bytes == 0 || bytes > MAX_IMAGE_PROGRAM_VALUE_BYTES {
1697        return Err(CoreError::invalid(
1698            "image program value bytes",
1699            format!("must be within 1..={MAX_IMAGE_PROGRAM_VALUE_BYTES}"),
1700        ));
1701    }
1702    Ok(())
1703}
1704
1705fn validate_dimensions(width: u32, height: u32) -> Result<(), CoreError> {
1706    if width == 0 || height == 0 || width > MAX_IMAGE_DIMENSION || height > MAX_IMAGE_DIMENSION {
1707        return Err(CoreError::invalid(
1708            "image program dimensions",
1709            format!("must be within 1..={MAX_IMAGE_DIMENSION}"),
1710        ));
1711    }
1712    Ok(())
1713}
1714
1715fn image_bytes(width: u32, height: u32, channels: u64) -> Result<u64, CoreError> {
1716    validate_dimensions(width, height)?;
1717    u64::from(width)
1718        .checked_mul(u64::from(height))
1719        .and_then(|pixels| pixels.checked_mul(channels))
1720        .ok_or_else(|| CoreError::invalid("image program image bytes", "length overflowed"))
1721}
1722
1723fn tensor_bytes(tensor: &TensorSpec) -> Result<u64, CoreError> {
1724    let scalar_bytes = match tensor.dtype {
1725        TensorDType::F32 => 4,
1726        TensorDType::F16 | TensorDType::Bf16 => 2,
1727    };
1728    tensor
1729        .elements()?
1730        .checked_mul(scalar_bytes)
1731        .ok_or_else(|| CoreError::invalid("image program tensor bytes", "length overflowed"))
1732}
1733
1734const fn is_singleton_role(role: ImageBufferRole) -> bool {
1735    !matches!(
1736        role,
1737        ImageBufferRole::ReferenceImage | ImageBufferRole::Lora
1738    )
1739}
1740
1741fn validate_role_spec(
1742    role: ImageBufferRole,
1743    spec: &ImageProgramValueSpecV1,
1744    width: u32,
1745    height: u32,
1746) -> Result<(), CoreError> {
1747    let compatible = match role {
1748        ImageBufferRole::PositiveConditioning | ImageBufferRole::NegativeConditioning => matches!(
1749            spec,
1750            ImageProgramValueSpecV1::Utf8 { .. }
1751                | ImageProgramValueSpecV1::Tensor { .. }
1752                | ImageProgramValueSpecV1::Opaque {
1753                    opaque_kind: ImageOpaqueValueKindV1::Conditioning,
1754                    ..
1755                }
1756        ),
1757        ImageBufferRole::SourceImage => matches!(
1758            spec,
1759            ImageProgramValueSpecV1::Rgb8 {
1760                width: value_width,
1761                height: value_height
1762            } | ImageProgramValueSpecV1::Rgba8 {
1763                width: value_width,
1764                height: value_height
1765            } if (*value_width, *value_height) == (width, height)
1766        ),
1767        ImageBufferRole::ReferenceImage => matches!(
1768            spec,
1769            ImageProgramValueSpecV1::Rgb8 { .. } | ImageProgramValueSpecV1::Rgba8 { .. }
1770        ),
1771        ImageBufferRole::Mask => matches!(
1772            spec,
1773            ImageProgramValueSpecV1::Gray8 {
1774                width: value_width,
1775                height: value_height
1776            } if (*value_width, *value_height) == (width, height)
1777        ),
1778        ImageBufferRole::Lora => false,
1779        ImageBufferRole::Checkpoint => matches!(
1780            spec,
1781            ImageProgramValueSpecV1::Opaque {
1782                opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
1783                ..
1784            }
1785        ),
1786        ImageBufferRole::TensorSnapshot => {
1787            matches!(spec, ImageProgramValueSpecV1::Tensor { .. })
1788        }
1789    };
1790    if compatible {
1791        Ok(())
1792    } else {
1793        Err(CoreError::invalid(
1794            "image program native input",
1795            "role is incompatible with the typed value",
1796        ))
1797    }
1798}
1799
1800fn validate_primary_output(
1801    operation: ImageOperation,
1802    format: ImageOutputFormat,
1803    width: u32,
1804    height: u32,
1805    spec: &ImageProgramValueSpecV1,
1806) -> Result<(), CoreError> {
1807    let compatible = match (operation, format, spec) {
1808        (
1809            ImageOperation::VaeEncode,
1810            ImageOutputFormat::Tensor,
1811            ImageProgramValueSpecV1::Tensor { .. },
1812        ) => true,
1813        (
1814            _,
1815            ImageOutputFormat::Rgb8,
1816            ImageProgramValueSpecV1::Rgb8 {
1817                width: value_width,
1818                height: value_height,
1819            },
1820        )
1821        | (
1822            _,
1823            ImageOutputFormat::Rgba8,
1824            ImageProgramValueSpecV1::Rgba8 {
1825                width: value_width,
1826                height: value_height,
1827            },
1828        )
1829        | (
1830            _,
1831            ImageOutputFormat::Png,
1832            ImageProgramValueSpecV1::Png {
1833                width: value_width,
1834                height: value_height,
1835                ..
1836            },
1837        ) => (*value_width, *value_height) == (width, height),
1838        _ => false,
1839    };
1840    if compatible {
1841        Ok(())
1842    } else {
1843        Err(CoreError::invalid(
1844            "image program primary output",
1845            "typed value differs from operation, format, or canvas",
1846        ))
1847    }
1848}
1849
1850fn validate_mask_blend(
1851    values: &[ImageProgramValueV1],
1852    base: u16,
1853    overlay: u16,
1854    mask: u16,
1855    output: u16,
1856) -> Result<(), CoreError> {
1857    let ImageProgramValueSpecV1::Rgb8 { width, height } = value_spec(values, base)? else {
1858        return Err(CoreError::invalid(
1859            "image program mask blend",
1860            "base must be RGB8",
1861        ));
1862    };
1863    if value_spec(values, overlay)?
1864        != &(ImageProgramValueSpecV1::Rgb8 {
1865            width: *width,
1866            height: *height,
1867        })
1868        || value_spec(values, mask)?
1869            != &(ImageProgramValueSpecV1::Gray8 {
1870                width: *width,
1871                height: *height,
1872            })
1873        || value_spec(values, output)?
1874            != &(ImageProgramValueSpecV1::Rgb8 {
1875                width: *width,
1876                height: *height,
1877            })
1878    {
1879        return Err(CoreError::invalid(
1880            "image program mask blend",
1881            "overlay, mask, and output must match the RGB8 base canvas",
1882        ));
1883    }
1884    Ok(())
1885}
1886
1887fn validate_checkpoint_conversion(
1888    values: &[ImageProgramValueV1],
1889    checkpoint: u16,
1890    state: u16,
1891    restoring: bool,
1892) -> Result<(), CoreError> {
1893    let ImageProgramValueSpecV1::Checkpoint {
1894        compatibility: checkpoint_compatibility,
1895        ..
1896    } = value_spec(values, checkpoint)?
1897    else {
1898        return Err(CoreError::invalid(
1899            "image program checkpoint",
1900            "serialized value has the wrong type",
1901        ));
1902    };
1903    let ImageProgramValueSpecV1::Opaque {
1904        opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
1905        compatibility: state_compatibility,
1906        ..
1907    } = value_spec(values, state)?
1908    else {
1909        return Err(CoreError::invalid(
1910            "image program checkpoint",
1911            "native state value has the wrong type",
1912        ));
1913    };
1914    if checkpoint_compatibility != state_compatibility {
1915        return Err(CoreError::invalid(
1916            "image program checkpoint",
1917            if restoring {
1918                "restore compatibility differs"
1919            } else {
1920                "capture compatibility differs"
1921            },
1922        ));
1923    }
1924    Ok(())
1925}
1926
1927fn checkpoint_state_compatibility(
1928    values: &[ImageProgramValueV1],
1929    state: u16,
1930) -> Result<&Digest, CoreError> {
1931    let ImageProgramValueSpecV1::Opaque {
1932        opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
1933        compatibility,
1934        ..
1935    } = value_spec(values, state)?
1936    else {
1937        return Err(CoreError::invalid(
1938            "image program checkpoint state",
1939            "value has the wrong type",
1940        ));
1941    };
1942    Ok(compatibility)
1943}
1944
1945#[cfg(test)]
1946mod tests {
1947    use super::*;
1948    use crate::{ImageCleanupPolicy, TensorLayout};
1949
1950    fn digest(domain: &str) -> Digest {
1951        Digest::of_bytes(domain, domain.as_bytes())
1952    }
1953
1954    fn buffer(domain: &str, bytes: u64) -> BufferSpec {
1955        BufferSpec::new(digest(domain), bytes, "application/octet-stream").unwrap()
1956    }
1957
1958    fn value(value: u16, spec: ImageProgramValueSpecV1) -> ImageProgramValueV1 {
1959        ImageProgramValueV1 { value, spec }
1960    }
1961
1962    fn schedule() -> DiffusionSchedule {
1963        DiffusionSchedule::new(digest("schedule"), vec![1.0, 0.5, 0.0]).unwrap()
1964    }
1965
1966    fn native(
1967        operation: ImageOperation,
1968        inputs: Vec<ImageProgramInputBindingV1>,
1969        output: u16,
1970        output_format: ImageOutputFormat,
1971    ) -> ImageProgramStageOperationV1 {
1972        let diffusion = operation.uses_diffusion();
1973        ImageProgramStageOperationV1::Native {
1974            plan: Box::new(ImageProgramNativeStageV1 {
1975                profile: digest("profile"),
1976                load: digest("load"),
1977                operation,
1978                width: 2,
1979                height: 1,
1980                output_format,
1981                seed: SeedSelection::Fixed { seed: 7 },
1982                rng: digest("rng"),
1983                placement: digest("placement"),
1984                schedule: diffusion.then(schedule),
1985                guidance_scale_bits: 1.0_f32.to_bits(),
1986                strength_bits: if matches!(
1987                    operation,
1988                    ImageOperation::ImageToImage
1989                        | ImageOperation::Inpaint
1990                        | ImageOperation::Outpaint
1991                ) {
1992                    0.75_f32.to_bits()
1993                } else {
1994                    1.0_f32.to_bits()
1995                },
1996                inputs,
1997                loras: Vec::new(),
1998                operators: Vec::new(),
1999                observations: Vec::new(),
2000                checkpoint_restore_at_step: None,
2001                checkpoint_after_step: None,
2002                outputs: vec![ImageProgramNativeOutputV1 {
2003                    role: ImageProgramNativeOutputRoleV1::Primary,
2004                    value: output,
2005                }],
2006            }),
2007        }
2008    }
2009
2010    fn binding(role: ImageBufferRole, value: u16) -> ImageProgramInputBindingV1 {
2011        ImageProgramInputBindingV1 { role, value }
2012    }
2013
2014    fn graph_values() -> Vec<ImageProgramValueV1> {
2015        let tensor = TensorSpec::new(
2016            vec![1, 2],
2017            TensorDType::F32,
2018            TensorLayout::DimensionZeroFastest,
2019            "host",
2020        )
2021        .unwrap();
2022        vec![
2023            value(0, ImageProgramValueSpecV1::Utf8 { maximum_bytes: 16 }),
2024            value(
2025                1,
2026                ImageProgramValueSpecV1::Gray8 {
2027                    width: 2,
2028                    height: 1,
2029                },
2030            ),
2031            value(
2032                2,
2033                ImageProgramValueSpecV1::Rgb8 {
2034                    width: 2,
2035                    height: 1,
2036                },
2037            ),
2038            value(
2039                3,
2040                ImageProgramValueSpecV1::Rgb8 {
2041                    width: 2,
2042                    height: 1,
2043                },
2044            ),
2045            value(
2046                4,
2047                ImageProgramValueSpecV1::Rgb8 {
2048                    width: 2,
2049                    height: 1,
2050                },
2051            ),
2052            value(
2053                5,
2054                ImageProgramValueSpecV1::Rgb8 {
2055                    width: 2,
2056                    height: 1,
2057                },
2058            ),
2059            value(
2060                6,
2061                ImageProgramValueSpecV1::Tensor {
2062                    tensor,
2063                    representation: digest("tensor-representation"),
2064                },
2065            ),
2066            value(
2067                7,
2068                ImageProgramValueSpecV1::Rgb8 {
2069                    width: 2,
2070                    height: 1,
2071                },
2072            ),
2073        ]
2074    }
2075
2076    fn graph_stages() -> Vec<ImageProgramStageV1> {
2077        vec![
2078            ImageProgramStageV1 {
2079                stage: 0,
2080                operation: native(
2081                    ImageOperation::TextToImage,
2082                    vec![binding(ImageBufferRole::PositiveConditioning, 0)],
2083                    2,
2084                    ImageOutputFormat::Rgb8,
2085                ),
2086            },
2087            ImageProgramStageV1 {
2088                stage: 1,
2089                operation: native(
2090                    ImageOperation::Inpaint,
2091                    vec![
2092                        binding(ImageBufferRole::PositiveConditioning, 0),
2093                        binding(ImageBufferRole::SourceImage, 2),
2094                        binding(ImageBufferRole::Mask, 1),
2095                    ],
2096                    3,
2097                    ImageOutputFormat::Rgb8,
2098                ),
2099            },
2100            ImageProgramStageV1 {
2101                stage: 2,
2102                operation: native(
2103                    ImageOperation::Inpaint,
2104                    vec![
2105                        binding(ImageBufferRole::PositiveConditioning, 0),
2106                        binding(ImageBufferRole::SourceImage, 2),
2107                        binding(ImageBufferRole::Mask, 1),
2108                    ],
2109                    4,
2110                    ImageOutputFormat::Rgb8,
2111                ),
2112            },
2113            ImageProgramStageV1 {
2114                stage: 3,
2115                operation: ImageProgramStageOperationV1::MaskBlend {
2116                    base: 3,
2117                    overlay: 4,
2118                    mask: 1,
2119                    output: 5,
2120                },
2121            },
2122            ImageProgramStageV1 {
2123                stage: 4,
2124                operation: native(
2125                    ImageOperation::VaeEncode,
2126                    vec![binding(ImageBufferRole::SourceImage, 5)],
2127                    6,
2128                    ImageOutputFormat::Tensor,
2129                ),
2130            },
2131            ImageProgramStageV1 {
2132                stage: 5,
2133                operation: native(
2134                    ImageOperation::VaeDecode,
2135                    vec![binding(ImageBufferRole::TensorSnapshot, 6)],
2136                    7,
2137                    ImageOutputFormat::Rgb8,
2138                ),
2139            },
2140        ]
2141    }
2142
2143    fn graph() -> ImageProgramPlanV1 {
2144        ImageProgramPlanV1 {
2145            values: graph_values(),
2146            inputs: vec![
2147                ImageProgramInputV1 {
2148                    value: 0,
2149                    buffer: buffer("prompt-input", 6),
2150                },
2151                ImageProgramInputV1 {
2152                    value: 1,
2153                    buffer: buffer("mask-input", 2),
2154                },
2155            ],
2156            stages: graph_stages(),
2157            outputs: vec![
2158                ImageProgramOutputRouteV1 {
2159                    route: 0,
2160                    source: ImageProgramOutputSourceV1::Value { value: 7 },
2161                    buffer: buffer("image-output", 6),
2162                },
2163                ImageProgramOutputRouteV1 {
2164                    route: 1,
2165                    source: ImageProgramOutputSourceV1::ProgramReceipt,
2166                    buffer: buffer("receipt-output", 16_384),
2167                },
2168            ],
2169            cleanup: ImageCleanupPolicy::ClearSession,
2170        }
2171    }
2172
2173    fn completed_receipt(plan: &ImageProgramPlanV1) -> ImageProgramReceiptV1 {
2174        let mut contents = plan
2175            .inputs
2176            .iter()
2177            .map(|input| (input.value, input.buffer.identity.clone()))
2178            .collect::<HashMap<_, _>>();
2179        let stages = plan
2180            .stages
2181            .iter()
2182            .map(|stage| {
2183                let outputs = stage
2184                    .operation
2185                    .outputs()
2186                    .into_iter()
2187                    .map(|value| {
2188                        let content =
2189                            Digest::of_bytes("synthetic-program-value", &value.to_le_bytes());
2190                        contents.insert(value, content.clone());
2191                        ImageProgramValueReceiptV1 {
2192                            value,
2193                            content,
2194                            bytes: plan.values[usize::from(value)]
2195                                .spec
2196                                .maximum_bytes()
2197                                .unwrap(),
2198                        }
2199                    })
2200                    .collect();
2201                ImageProgramStageReceiptV1 {
2202                    stage: stage.stage,
2203                    operation: stage.operation.digest().unwrap(),
2204                    outputs,
2205                    observations: Vec::new(),
2206                }
2207            })
2208            .collect::<Vec<_>>();
2209        let final_content = contents[&7].clone();
2210        ImageProgramReceiptV1 {
2211            plan: plan.digest().unwrap(),
2212            backend: digest("backend"),
2213            runtime_epoch: 9,
2214            completed_stages: u16::try_from(plan.stages.len()).unwrap(),
2215            stages,
2216            outputs: vec![
2217                ImageProgramOutputReceiptV1 {
2218                    route: 0,
2219                    allocation: plan.outputs[0].buffer.identity.clone(),
2220                    content: Some(final_content),
2221                    bytes_written: 6,
2222                },
2223                ImageProgramOutputReceiptV1 {
2224                    route: 1,
2225                    allocation: plan.outputs[1].buffer.identity.clone(),
2226                    content: None,
2227                    bytes_written: 1_024,
2228                },
2229            ],
2230            terminal: ImageProgramTerminalV1::Completed,
2231            cleanup: ImageProgramCleanupDispositionV1::Confirmed { cleared_epoch: 9 },
2232        }
2233    }
2234
2235    #[test]
2236    fn branching_native_graph_round_trips_and_has_a_new_identity() {
2237        let plan = graph();
2238        plan.validate().unwrap();
2239        let encoded = serde_json::to_vec(&plan).unwrap();
2240        assert_eq!(
2241            serde_json::from_slice::<ImageProgramPlanV1>(&encoded).unwrap(),
2242            plan
2243        );
2244        assert_eq!(plan.digest().unwrap(), plan.digest().unwrap());
2245        assert_ne!(
2246            plan.digest().unwrap(),
2247            Digest::of_serializable("image-execution-plan-v3", &plan).unwrap()
2248        );
2249    }
2250
2251    #[test]
2252    fn png_primary_binds_decoded_type_encoder_and_encoded_bound() {
2253        let mut plan = graph();
2254        plan.values[7].spec = ImageProgramValueSpecV1::Png {
2255            width: 2,
2256            height: 1,
2257            color: ImagePngColorV1::Rgba8,
2258            encoding: digest("png-encoding"),
2259            maximum_bytes: 1_024,
2260        };
2261        let ImageProgramStageOperationV1::Native { plan: native } = &mut plan.stages[5].operation
2262        else {
2263            panic!("fixture stage must be native");
2264        };
2265        native.output_format = ImageOutputFormat::Png;
2266        plan.outputs[0].buffer = buffer("png-output", 1_024);
2267        plan.validate().unwrap();
2268
2269        plan.outputs[0].buffer = buffer("oversized-png-output", 1_025);
2270        assert!(plan.validate().is_err());
2271    }
2272
2273    #[test]
2274    fn graph_rejects_forward_references_and_duplicate_producers() {
2275        let mut forward = graph();
2276        if let ImageProgramStageOperationV1::Native { plan } = &mut forward.stages[0].operation {
2277            plan.inputs[0].value = 2;
2278        }
2279        assert!(forward.validate().is_err());
2280
2281        let mut duplicate = graph();
2282        duplicate.inputs.push(ImageProgramInputV1 {
2283            value: 2,
2284            buffer: buffer("duplicate-producer", 6),
2285        });
2286        assert!(duplicate.validate().is_err());
2287    }
2288
2289    #[test]
2290    fn graph_rejects_type_invalid_masks_and_unused_inputs() {
2291        let mut wrong_mask = graph();
2292        wrong_mask.values[1].spec = ImageProgramValueSpecV1::Rgb8 {
2293            width: 2,
2294            height: 1,
2295        };
2296        assert!(wrong_mask.validate().is_err());
2297
2298        let mut unused = graph();
2299        unused
2300            .values
2301            .push(value(8, ImageProgramValueSpecV1::Utf8 { maximum_bytes: 8 }));
2302        unused.inputs.push(ImageProgramInputV1 {
2303            value: 8,
2304            buffer: buffer("unused", 4),
2305        });
2306        assert!(unused.validate().is_err());
2307    }
2308
2309    #[test]
2310    fn reference_images_preserve_independent_geometry_and_identity() {
2311        let mut plan = graph();
2312        plan.values.push(value(
2313            8,
2314            ImageProgramValueSpecV1::Rgb8 {
2315                width: 1,
2316                height: 2,
2317            },
2318        ));
2319        plan.inputs.push(ImageProgramInputV1 {
2320            value: 8,
2321            buffer: buffer("reference-input", 6),
2322        });
2323        let ImageProgramStageOperationV1::Native { plan: native } = &mut plan.stages[0].operation
2324        else {
2325            panic!("fixture stage must be native");
2326        };
2327        native
2328            .inputs
2329            .push(binding(ImageBufferRole::ReferenceImage, 8));
2330
2331        plan.validate().unwrap();
2332        let independent_digest = plan.digest().unwrap();
2333        let encoded = serde_json::to_vec(&plan).unwrap();
2334        let decoded: ImageProgramPlanV1 = serde_json::from_slice(&encoded).unwrap();
2335        assert_eq!(decoded, plan);
2336        assert_eq!(
2337            decoded.values[8].spec,
2338            ImageProgramValueSpecV1::Rgb8 {
2339                width: 1,
2340                height: 2,
2341            }
2342        );
2343
2344        plan.values[8].spec = ImageProgramValueSpecV1::Rgb8 {
2345            width: 2,
2346            height: 1,
2347        };
2348        plan.validate().unwrap();
2349        assert_ne!(plan.digest().unwrap(), independent_digest);
2350
2351        plan.values[8].spec = ImageProgramValueSpecV1::Rgba8 {
2352            width: 1,
2353            height: 2,
2354        };
2355        plan.inputs[2].buffer = buffer("rgba-reference-input", 8);
2356        plan.validate().unwrap();
2357    }
2358
2359    #[test]
2360    fn reference_images_reject_invalid_specs_and_lengths() {
2361        let independent_rgb = ImageProgramValueSpecV1::Rgb8 {
2362            width: 1,
2363            height: 2,
2364        };
2365        assert!(
2366            validate_role_spec(ImageBufferRole::ReferenceImage, &independent_rgb, 2, 1).is_ok()
2367        );
2368        assert!(validate_role_spec(ImageBufferRole::SourceImage, &independent_rgb, 2, 1).is_err());
2369        assert!(
2370            validate_role_spec(
2371                ImageBufferRole::Mask,
2372                &ImageProgramValueSpecV1::Gray8 {
2373                    width: 1,
2374                    height: 2,
2375                },
2376                2,
2377                1
2378            )
2379            .is_err()
2380        );
2381        assert!(
2382            validate_role_spec(
2383                ImageBufferRole::ReferenceImage,
2384                &ImageProgramValueSpecV1::Gray8 {
2385                    width: 1,
2386                    height: 2,
2387                },
2388                2,
2389                1
2390            )
2391            .is_err()
2392        );
2393        assert!(
2394            ImageProgramValueSpecV1::Rgb8 {
2395                width: 0,
2396                height: 1,
2397            }
2398            .validate()
2399            .is_err()
2400        );
2401        assert!(
2402            ImageProgramValueSpecV1::Rgba8 {
2403                width: MAX_IMAGE_DIMENSION + 1,
2404                height: 1,
2405            }
2406            .validate()
2407            .is_err()
2408        );
2409        assert!(independent_rgb.validate_buffer_length(5).is_err());
2410    }
2411
2412    #[test]
2413    fn liveness_releases_branch_values_after_their_last_consumers() {
2414        let plan = graph();
2415        let liveness = plan.liveness().unwrap();
2416        assert!(liveness.peak_bytes > 0);
2417        assert_eq!(liveness.releases.len(), plan.values.len());
2418        assert_eq!(
2419            liveness
2420                .releases
2421                .iter()
2422                .find(|release| release.value == 2)
2423                .unwrap()
2424                .after_stage,
2425            Some(2)
2426        );
2427        assert_eq!(
2428            liveness.releases.last().unwrap(),
2429            &ImageProgramReleaseV1 {
2430                value: 7,
2431                after_stage: None
2432            }
2433        );
2434    }
2435
2436    #[test]
2437    fn arena_overflow_is_rejected_before_execution() {
2438        let mut plan = graph();
2439        plan.values[0].spec = ImageProgramValueSpecV1::Utf8 {
2440            maximum_bytes: MAX_IMAGE_PROGRAM_VALUE_BYTES,
2441        };
2442        plan.inputs[0].buffer.byte_length = 6;
2443        plan.values[1].spec = ImageProgramValueSpecV1::Opaque {
2444            opaque_kind: ImageOpaqueValueKindV1::Conditioning,
2445            compatibility: digest("large-one"),
2446            maximum_bytes: MAX_IMAGE_PROGRAM_VALUE_BYTES,
2447        };
2448        plan.inputs[1].buffer.byte_length = 2;
2449        plan.values.push(value(
2450            8,
2451            ImageProgramValueSpecV1::Opaque {
2452                opaque_kind: ImageOpaqueValueKindV1::Conditioning,
2453                compatibility: digest("large-two"),
2454                maximum_bytes: MAX_IMAGE_PROGRAM_VALUE_BYTES,
2455            },
2456        ));
2457        plan.inputs.push(ImageProgramInputV1 {
2458            value: 8,
2459            buffer: buffer("large-input", 1),
2460        });
2461        if let ImageProgramStageOperationV1::Native { plan: native } = &mut plan.stages[0].operation
2462        {
2463            native
2464                .inputs
2465                .push(binding(ImageBufferRole::NegativeConditioning, 8));
2466        }
2467        assert!(plan.validate().is_err());
2468    }
2469
2470    #[test]
2471    fn checkpoint_compatibility_and_mutable_fanout_are_rejected() {
2472        let mut plan = graph();
2473        plan.values.push(value(
2474            8,
2475            ImageProgramValueSpecV1::Checkpoint {
2476                compatibility: digest("checkpoint-a"),
2477                maximum_bytes: 128,
2478            },
2479        ));
2480        plan.values.push(value(
2481            9,
2482            ImageProgramValueSpecV1::Opaque {
2483                opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
2484                compatibility: digest("checkpoint-b"),
2485                maximum_bytes: 128,
2486            },
2487        ));
2488        plan.inputs.push(ImageProgramInputV1 {
2489            value: 8,
2490            buffer: buffer("checkpoint-input", 64),
2491        });
2492        plan.stages.insert(
2493            0,
2494            ImageProgramStageV1 {
2495                stage: 0,
2496                operation: ImageProgramStageOperationV1::RestoreCheckpoint {
2497                    checkpoint: 8,
2498                    state: 9,
2499                    implementation: digest("restore"),
2500                },
2501            },
2502        );
2503        for (index, stage) in plan.stages.iter_mut().enumerate() {
2504            stage.stage = u16::try_from(index).unwrap();
2505        }
2506        assert!(plan.validate().is_err());
2507
2508        plan.values[9].spec = ImageProgramValueSpecV1::Opaque {
2509            opaque_kind: ImageOpaqueValueKindV1::CheckpointState,
2510            compatibility: digest("checkpoint-a"),
2511            maximum_bytes: 128,
2512        };
2513        if let ImageProgramStageOperationV1::Native { plan: native } = &mut plan.stages[1].operation
2514        {
2515            native.inputs.push(binding(ImageBufferRole::Checkpoint, 9));
2516            native.checkpoint_restore_at_step = Some(0);
2517        }
2518        if let ImageProgramStageOperationV1::Native { plan: native } = &mut plan.stages[2].operation
2519        {
2520            native.inputs.push(binding(ImageBufferRole::Checkpoint, 9));
2521            native.checkpoint_restore_at_step = Some(0);
2522        }
2523        assert!(plan.validate().is_err());
2524    }
2525
2526    #[test]
2527    fn completed_receipt_and_measurements_validate_separately() {
2528        let plan = graph();
2529        let receipt = completed_receipt(&plan);
2530        assert!(receipt.digest_for(&plan).is_ok());
2531        let measurements = ImageProgramMeasurementsV1 {
2532            plan: plan.digest().unwrap(),
2533            backend: receipt.backend.clone(),
2534            runtime_epoch: receipt.runtime_epoch,
2535            stage_wall_time_ns: vec![10; plan.stages.len()],
2536            stage_native_time_ns: vec![Some(8); plan.stages.len()],
2537            peak_arena_bytes: plan.liveness().unwrap().peak_bytes,
2538            values: plan
2539                .values
2540                .iter()
2541                .map(|value| ImageProgramValueMeasurementV1 {
2542                    value: value.value,
2543                    placement: ImageProgramValuePlacementV1::Host,
2544                    host_to_device_transfers: 0,
2545                    host_to_device_bytes: 0,
2546                    device_to_host_transfers: 0,
2547                    device_to_host_bytes: 0,
2548                })
2549                .collect(),
2550        };
2551        assert!(measurements.validate_for(&plan, &receipt).is_ok());
2552
2553        let mut tampered = receipt;
2554        tampered.stages[2].stage = 7;
2555        assert!(tampered.digest_for(&plan).is_err());
2556    }
2557
2558    #[test]
2559    fn cleanup_uncertainty_must_poison_the_terminal_contract() {
2560        let plan = graph();
2561        let failure = "cleanup failed because the native arena remained live".to_owned();
2562        let receipt = ImageProgramReceiptV1 {
2563            plan: plan.digest().unwrap(),
2564            backend: digest("backend"),
2565            runtime_epoch: 9,
2566            completed_stages: 0,
2567            stages: Vec::new(),
2568            outputs: Vec::new(),
2569            terminal: ImageProgramTerminalV1::CleanupUncertain {
2570                after_stage: None,
2571                failure: failure.clone(),
2572            },
2573            cleanup: ImageProgramCleanupDispositionV1::Uncertain { failure },
2574        };
2575        assert!(receipt.digest_for(&plan).is_ok());
2576    }
2577}