1use 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
18pub const MAX_IMAGE_PROGRAM_STAGES: usize = 64;
20pub const MAX_IMAGE_PROGRAM_VALUES: usize = 128;
22pub const MAX_IMAGE_PROGRAM_INPUTS: usize = 32;
24pub const MAX_IMAGE_PROGRAM_OUTPUTS: usize = 32;
26pub const MAX_IMAGE_PROGRAM_VALUE_BYTES: u64 = 1024 * 1024 * 1024;
28pub const MAX_IMAGE_PROGRAM_ARENA_BYTES: u64 = 2 * 1024 * 1024 * 1024;
30
31pub fn image_program_value_content(bytes: &[u8]) -> Digest {
38 Digest::of_bytes("image-program-value-content-v1", bytes)
39}
40
41#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
43#[serde(rename_all = "kebab-case")]
44pub enum ImageOpaqueValueKindV1 {
45 Conditioning,
47 LoraArtifact,
49 CheckpointState,
51}
52
53#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
55#[serde(rename_all = "kebab-case")]
56pub enum ImagePngColorV1 {
57 Rgb8,
59 Rgba8,
61}
62
63impl ImagePngColorV1 {
64 pub const fn channels(self) -> u32 {
66 match self {
67 Self::Rgb8 => 3,
68 Self::Rgba8 => 4,
69 }
70 }
71}
72
73#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
75#[serde(rename_all = "kebab-case", tag = "kind")]
76pub enum ImageProgramValueSpecV1 {
77 Utf8 {
79 maximum_bytes: u64,
81 },
82 Rgb8 {
84 width: u32,
86 height: u32,
88 },
89 Rgba8 {
91 width: u32,
93 height: u32,
95 },
96 Png {
98 width: u32,
100 height: u32,
102 color: ImagePngColorV1,
104 encoding: Digest,
106 maximum_bytes: u64,
108 },
109 Gray8 {
111 width: u32,
113 height: u32,
115 },
116 Tensor {
118 tensor: TensorSpec,
120 representation: Digest,
122 },
123 Checkpoint {
125 compatibility: Digest,
127 maximum_bytes: u64,
129 },
130 Opaque {
132 opaque_kind: ImageOpaqueValueKindV1,
134 compatibility: Digest,
136 maximum_bytes: u64,
138 },
139}
140
141impl ImageProgramValueSpecV1 {
142 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 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
224#[serde(deny_unknown_fields)]
225pub struct ImageProgramValueV1 {
226 pub value: u16,
228 pub spec: ImageProgramValueSpecV1,
230}
231
232#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
234#[serde(deny_unknown_fields)]
235pub struct ImageProgramInputV1 {
236 pub value: u16,
238 pub buffer: BufferSpec,
240}
241
242#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
244#[serde(deny_unknown_fields)]
245pub struct ImageProgramInputBindingV1 {
246 pub role: ImageBufferRole,
248 pub value: u16,
250}
251
252#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
254#[serde(deny_unknown_fields)]
255pub struct ImageProgramLoraV1 {
256 pub value: u16,
258 pub target: Digest,
260 pub scales: ScaleSchedule,
262}
263
264#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
266#[serde(rename_all = "kebab-case", tag = "kind")]
267pub enum ImageProgramNativeOutputRoleV1 {
268 Primary,
270 CheckpointState,
272 Observation {
274 observation: u16,
276 },
277}
278
279#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
281#[serde(deny_unknown_fields)]
282pub struct ImageProgramNativeOutputV1 {
283 pub role: ImageProgramNativeOutputRoleV1,
285 pub value: u16,
287}
288
289#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
291#[serde(deny_unknown_fields)]
292pub struct ImageProgramNativeStageV1 {
293 pub profile: Digest,
295 pub load: Digest,
297 pub operation: ImageOperation,
299 pub width: u32,
301 pub height: u32,
303 pub output_format: ImageOutputFormat,
305 pub seed: SeedSelection,
307 pub rng: Digest,
309 pub placement: Digest,
311 pub schedule: Option<DiffusionSchedule>,
313 pub guidance_scale_bits: u32,
315 pub strength_bits: u32,
317 pub inputs: Vec<ImageProgramInputBindingV1>,
319 pub loras: Vec<ImageProgramLoraV1>,
321 pub operators: Vec<OperatorInvocation>,
323 pub observations: Vec<ObservationRequest>,
325 pub checkpoint_restore_at_step: Option<u32>,
328 pub checkpoint_after_step: Option<u32>,
330 pub outputs: Vec<ImageProgramNativeOutputV1>,
332}
333
334impl ImageProgramNativeStageV1 {
335 pub fn guidance_scale(&self) -> f32 {
337 f32::from_bits(self.guidance_scale_bits)
338 }
339
340 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#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
661#[serde(rename_all = "kebab-case", tag = "kind")]
662pub enum ImageProgramStageOperationV1 {
663 Native {
665 plan: Box<ImageProgramNativeStageV1>,
667 },
668 MaskBlend {
670 base: u16,
672 overlay: u16,
674 mask: u16,
676 output: u16,
678 },
679 RestoreCheckpoint {
681 checkpoint: u16,
683 state: u16,
685 implementation: Digest,
687 },
688 CaptureCheckpoint {
690 state: u16,
692 checkpoint: u16,
694 implementation: Digest,
696 },
697}
698
699impl ImageProgramStageOperationV1 {
700 pub fn referenced_values(&self) -> Vec<u16> {
702 self.references()
703 }
704
705 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 pub fn digest(&self) -> Result<Digest, CoreError> {
757 Digest::of_serializable("image-program-stage-operation-v1", self)
758 }
759}
760
761#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
763#[serde(deny_unknown_fields)]
764pub struct ImageProgramStageV1 {
765 pub stage: u16,
767 pub operation: ImageProgramStageOperationV1,
769}
770
771#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
773#[serde(rename_all = "kebab-case", tag = "kind")]
774pub enum ImageProgramOutputSourceV1 {
775 Value {
777 value: u16,
779 },
780 ProgramReceipt,
782}
783
784#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
786#[serde(deny_unknown_fields)]
787pub struct ImageProgramOutputRouteV1 {
788 pub route: u16,
790 pub source: ImageProgramOutputSourceV1,
792 pub buffer: BufferSpec,
794}
795
796#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
798#[serde(deny_unknown_fields)]
799pub struct ImageProgramReleaseV1 {
800 pub value: u16,
802 pub after_stage: Option<u16>,
804}
805
806#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
808#[serde(deny_unknown_fields)]
809pub struct ImageProgramLivenessV1 {
810 pub peak_bytes: u64,
812 pub releases: Vec<ImageProgramReleaseV1>,
814}
815
816#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
818#[serde(deny_unknown_fields)]
819pub struct ImageProgramPlanV1 {
820 pub values: Vec<ImageProgramValueV1>,
822 pub inputs: Vec<ImageProgramInputV1>,
824 pub stages: Vec<ImageProgramStageV1>,
826 pub outputs: Vec<ImageProgramOutputRouteV1>,
828 pub cleanup: ImageCleanupPolicy,
830}
831
832impl ImageProgramPlanV1 {
833 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 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 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1143#[serde(deny_unknown_fields)]
1144pub struct ImageProgramValueReceiptV1 {
1145 pub value: u16,
1147 pub content: Digest,
1149 pub bytes: u64,
1151}
1152
1153#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1155#[serde(deny_unknown_fields)]
1156pub struct ImageProgramStageReceiptV1 {
1157 pub stage: u16,
1159 pub operation: Digest,
1161 pub outputs: Vec<ImageProgramValueReceiptV1>,
1163 pub observations: Vec<Digest>,
1165}
1166
1167#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1169#[serde(deny_unknown_fields)]
1170pub struct ImageProgramOutputReceiptV1 {
1171 pub route: u16,
1173 pub allocation: Digest,
1175 pub content: Option<Digest>,
1177 pub bytes_written: u64,
1179}
1180
1181#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1183#[serde(rename_all = "kebab-case", tag = "kind")]
1184pub enum ImageProgramTerminalV1 {
1185 Completed,
1187 CancelledBeforeStart,
1189 CancelledAfterStage {
1191 stage: u16,
1193 },
1194 CancelledAfterStep {
1196 stage: u16,
1198 step: u32,
1200 },
1201 FailedAtStage {
1203 stage: u16,
1205 failure: String,
1207 },
1208 CleanupUncertain {
1210 after_stage: Option<u16>,
1212 failure: String,
1214 },
1215}
1216
1217#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1219#[serde(rename_all = "kebab-case", tag = "kind")]
1220pub enum ImageProgramCleanupDispositionV1 {
1221 Retained,
1223 Confirmed {
1225 cleared_epoch: u64,
1227 },
1228 NotRequired,
1230 Uncertain {
1232 failure: String,
1234 },
1235}
1236
1237#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1239#[serde(deny_unknown_fields)]
1240pub struct ImageProgramReceiptV1 {
1241 pub plan: Digest,
1243 pub backend: Digest,
1245 pub runtime_epoch: u64,
1247 pub completed_stages: u16,
1249 pub stages: Vec<ImageProgramStageReceiptV1>,
1251 pub outputs: Vec<ImageProgramOutputReceiptV1>,
1253 pub terminal: ImageProgramTerminalV1,
1255 pub cleanup: ImageProgramCleanupDispositionV1,
1257}
1258
1259impl ImageProgramReceiptV1 {
1260 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 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1484#[serde(rename_all = "kebab-case", tag = "kind")]
1485pub enum ImageProgramValuePlacementV1 {
1486 Host,
1488 Device {
1490 device: String,
1492 },
1493 Mixed {
1495 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#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1525#[serde(deny_unknown_fields)]
1526pub struct ImageProgramValueMeasurementV1 {
1527 pub value: u16,
1529 pub placement: ImageProgramValuePlacementV1,
1531 pub host_to_device_transfers: u64,
1533 pub host_to_device_bytes: u64,
1535 pub device_to_host_transfers: u64,
1537 pub device_to_host_bytes: u64,
1539}
1540
1541#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
1543#[serde(deny_unknown_fields)]
1544pub struct ImageProgramMeasurementsV1 {
1545 pub plan: Digest,
1547 pub backend: Digest,
1549 pub runtime_epoch: u64,
1551 pub stage_wall_time_ns: Vec<u64>,
1553 pub stage_native_time_ns: Vec<Option<u64>>,
1555 pub peak_arena_bytes: u64,
1557 pub values: Vec<ImageProgramValueMeasurementV1>,
1559}
1560
1561impl ImageProgramMeasurementsV1 {
1562 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}