use std::collections::{BTreeMap, HashSet};
use logit_loom_core::{CoreError, Digest};
use serde::{Deserialize, Serialize};
pub const MAX_TENSOR_DIMENSIONS: usize = 8;
pub const MAX_TENSOR_ELEMENTS: u64 = 16 * 1024 * 1024;
pub const MAX_DIFFUSION_STEPS: usize = 4_096;
pub const MAX_COMPONENTS: usize = 32;
pub const MAX_DEVICE_LABEL_BYTES: usize = 256;
pub const MAX_INTERVENTION_STAGES: usize = 32;
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TensorDType {
F32,
F16,
Bf16,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum TensorLayout {
DimensionZeroFastest,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TensorSpec {
pub shape: Vec<u64>,
pub dtype: TensorDType,
pub layout: TensorLayout,
pub device: String,
}
impl TensorSpec {
pub fn new(
shape: Vec<u64>,
dtype: TensorDType,
layout: TensorLayout,
device: impl Into<String>,
) -> Result<Self, CoreError> {
let specification = Self {
shape,
dtype,
layout,
device: device.into(),
};
specification.validate()?;
Ok(specification)
}
pub fn validate(&self) -> Result<(), CoreError> {
if !(1..=MAX_TENSOR_DIMENSIONS).contains(&self.shape.len()) {
return Err(CoreError::invalid(
"diffusion tensor shape",
format!("requires 1..={MAX_TENSOR_DIMENSIONS} dimensions"),
));
}
if self.shape.contains(&0) {
return Err(CoreError::invalid(
"diffusion tensor shape",
"dimensions must be positive",
));
}
let elements = self.elements()?;
if elements > MAX_TENSOR_ELEMENTS {
return Err(CoreError::invalid(
"diffusion tensor shape",
format!("exceeds the {MAX_TENSOR_ELEMENTS}-element bound"),
));
}
if self.device.is_empty()
|| self.device.len() > MAX_DEVICE_LABEL_BYTES
|| self.device.contains('\0')
{
return Err(CoreError::invalid(
"diffusion tensor device",
"must be a nonempty bounded label without NUL",
));
}
Ok(())
}
pub fn elements(&self) -> Result<u64, CoreError> {
if self.shape.is_empty() {
return Err(CoreError::Empty {
field: "diffusion tensor shape",
});
}
self.shape.iter().try_fold(1_u64, |product, dimension| {
product.checked_mul(*dimension).ok_or_else(|| {
CoreError::invalid("diffusion tensor shape", "element count overflowed")
})
})
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("diffusion-tensor-spec-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DiffusionSchedule {
pub implementation: Digest,
pub sigmas: Vec<f32>,
}
impl DiffusionSchedule {
pub fn new(implementation: Digest, sigmas: Vec<f32>) -> Result<Self, CoreError> {
let schedule = Self {
implementation,
sigmas,
};
schedule.validate()?;
Ok(schedule)
}
pub fn validate(&self) -> Result<(), CoreError> {
if !(2..=MAX_DIFFUSION_STEPS + 1).contains(&self.sigmas.len()) {
return Err(CoreError::invalid(
"diffusion schedule",
format!("requires 1..={MAX_DIFFUSION_STEPS} steps"),
));
}
if self
.sigmas
.iter()
.any(|sigma| !sigma.is_finite() || *sigma < 0.0)
{
return Err(CoreError::invalid(
"diffusion schedule",
"sigmas must be finite and non-negative",
));
}
if self.sigmas.windows(2).any(|pair| pair[0] < pair[1]) {
return Err(CoreError::invalid(
"diffusion schedule",
"sigmas must be non-increasing",
));
}
Ok(())
}
pub fn steps(&self) -> usize {
self.sigmas.len().saturating_sub(1)
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("diffusion-schedule-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DiffusionPlan {
pub components: BTreeMap<String, Digest>,
pub conditioning: Digest,
pub rng: Digest,
pub seed: u64,
pub tensor: TensorSpec,
pub schedule: DiffusionSchedule,
}
impl DiffusionPlan {
pub fn new(
components: BTreeMap<String, Digest>,
conditioning: Digest,
rng: Digest,
seed: u64,
tensor: TensorSpec,
schedule: DiffusionSchedule,
) -> Result<Self, CoreError> {
let plan = Self {
components,
conditioning,
rng,
seed,
tensor,
schedule,
};
plan.validate()?;
Ok(plan)
}
pub fn validate(&self) -> Result<(), CoreError> {
if self.components.is_empty() || self.components.len() > MAX_COMPONENTS {
return Err(CoreError::invalid(
"diffusion components",
format!("requires 1..={MAX_COMPONENTS} entries"),
));
}
for name in self.components.keys() {
if name.is_empty()
|| name.len() > 64
|| !name.bytes().all(|byte| {
byte.is_ascii_lowercase()
|| byte.is_ascii_digit()
|| matches!(byte, b'-' | b'_' | b'.')
})
{
return Err(CoreError::invalid(
"diffusion component name",
"must be a bounded lowercase identifier",
));
}
}
self.tensor.validate()?;
self.schedule.validate()
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("diffusion-plan-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StepContext {
pub plan: Digest,
pub step_index: u32,
pub sigma_from: f32,
pub sigma_to: f32,
pub tensor: TensorSpec,
}
impl StepContext {
pub fn for_plan(plan: &DiffusionPlan, step_index: usize) -> Result<Self, CoreError> {
plan.validate()?;
if step_index >= plan.schedule.steps() {
return Err(CoreError::invalid(
"diffusion step",
"index is outside the schedule",
));
}
let step_index_u32 = u32::try_from(step_index)
.map_err(|_| CoreError::invalid("diffusion step", "index exceeds u32"))?;
Ok(Self {
plan: plan.digest()?,
step_index: step_index_u32,
sigma_from: plan.schedule.sigmas[step_index],
sigma_to: plan.schedule.sigmas[step_index + 1],
tensor: plan.tensor.clone(),
})
}
pub fn validate_for(&self, plan: &DiffusionPlan) -> Result<(), CoreError> {
let expected = Self::for_plan(
plan,
usize::try_from(self.step_index)
.map_err(|_| CoreError::invalid("diffusion step", "index exceeds usize"))?,
)?;
if *self != expected {
return Err(CoreError::invalid(
"diffusion step",
"context does not match the execution plan",
));
}
Ok(())
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InterventionSpec {
pub implementation: Digest,
pub tensor: Digest,
pub max_invocations: u32,
}
impl InterventionSpec {
pub fn validate(&self) -> Result<(), CoreError> {
if self.max_invocations == 0 {
return Err(CoreError::invalid(
"diffusion intervention",
"maximum invocations must be positive",
));
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("diffusion-intervention-spec-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PipelineSpec {
pub stages: Vec<InterventionSpec>,
}
impl PipelineSpec {
pub fn validate(&self) -> Result<(), CoreError> {
if !(1..=MAX_INTERVENTION_STAGES).contains(&self.stages.len()) {
return Err(CoreError::invalid(
"diffusion pipeline stages",
format!("requires 1..={MAX_INTERVENTION_STAGES} entries"),
));
}
let tensor = &self.stages[0].tensor;
for stage in &self.stages {
stage.validate()?;
if &stage.tensor != tensor {
return Err(CoreError::invalid(
"diffusion pipeline stages",
"all stages must accept the same tensor contract",
));
}
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("diffusion-pipeline-spec-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InterventionFailure {
pub panicked: bool,
pub message: String,
}
impl InterventionFailure {
pub fn new(panicked: bool, message: impl Into<String>) -> Self {
Self {
panicked,
message: message.into(),
}
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct StageReceipt {
pub specification: InterventionSpec,
pub resets: u32,
pub invocations: u32,
pub elements_seen: u64,
pub elements_changed: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub failure: Option<InterventionFailure>,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PipelineReceipt {
pub specification: PipelineSpec,
pub pipeline: Digest,
pub begins: u32,
pub invocations: u32,
pub elements_copied: u64,
pub elements_committed: u64,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub failed_stage: Option<u32>,
pub stages: Vec<StageReceipt>,
}
impl PipelineReceipt {
pub fn validate(&self) -> Result<(), CoreError> {
self.specification.validate()?;
if self.pipeline != self.specification.digest()?
|| self.begins > 1
|| self.elements_committed > self.elements_copied
|| self.stages.len() != self.specification.stages.len()
{
return Err(CoreError::invalid(
"diffusion pipeline receipt",
"aggregate accounting is inconsistent",
));
}
let failed = self
.failed_stage
.map(usize::try_from)
.transpose()
.map_err(|_| {
CoreError::invalid("diffusion pipeline receipt", "failed stage exceeds usize")
})?;
if failed.is_some_and(|index| index >= self.stages.len()) {
return Err(CoreError::invalid(
"diffusion pipeline receipt",
"failed stage is outside the pipeline",
));
}
let mut failures = HashSet::new();
for (index, (stage, specification)) in self
.stages
.iter()
.zip(&self.specification.stages)
.enumerate()
{
if stage.specification != *specification
|| stage.resets > self.begins
|| stage.invocations > stage.specification.max_invocations
|| stage.elements_changed > stage.elements_seen
{
return Err(CoreError::invalid(
"diffusion pipeline receipt",
"stage accounting is inconsistent",
));
}
if stage.failure.is_some() {
failures.insert(index);
}
}
if failures.len() > 1 || failures.iter().next().copied() != failed {
return Err(CoreError::invalid(
"diffusion pipeline receipt",
"failure attribution is inconsistent",
));
}
Ok(())
}
pub fn digest(&self) -> Result<Digest, CoreError> {
self.validate()?;
Digest::of_serializable("diffusion-pipeline-receipt-v1", self)
}
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct DiffusionCheckpointReceipt {
pub plan: Digest,
pub backend: Digest,
pub next_step: u32,
pub state: Digest,
pub continuation: Digest,
}
impl DiffusionCheckpointReceipt {
pub fn validate_for(&self, plan: &DiffusionPlan) -> Result<(), CoreError> {
plan.validate()?;
if self.plan != plan.digest()?
|| usize::try_from(self.next_step).map_or(true, |step| step > plan.schedule.steps())
{
return Err(CoreError::invalid(
"diffusion checkpoint",
"plan identity or step position is incompatible",
));
}
Ok(())
}
pub fn digest_for(&self, plan: &DiffusionPlan) -> Result<Digest, CoreError> {
self.validate_for(plan)?;
Digest::of_serializable("diffusion-checkpoint-receipt-v1", self)
}
}
#[cfg(test)]
mod tests {
use super::*;
fn tensor() -> TensorSpec {
TensorSpec::new(
vec![8, 8, 3, 1],
TensorDType::F32,
TensorLayout::DimensionZeroFastest,
"test0",
)
.unwrap()
}
#[test]
fn tensor_bounds_reject_zero_and_overflow() {
assert!(
TensorSpec::new(
vec![1, 0],
TensorDType::F32,
TensorLayout::DimensionZeroFastest,
"test0"
)
.is_err()
);
assert!(
TensorSpec::new(
vec![u64::MAX, 2],
TensorDType::F32,
TensorLayout::DimensionZeroFastest,
"test0"
)
.is_err()
);
}
#[test]
fn schedules_reject_nonfinite_and_increasing_values() {
let implementation = Digest::of_bytes("test-scheduler", b"v1");
assert!(DiffusionSchedule::new(implementation.clone(), vec![1.0, f32::NAN]).is_err());
assert!(DiffusionSchedule::new(implementation, vec![0.0, 1.0]).is_err());
}
#[test]
fn component_names_accept_catalog_periods_but_reject_uppercase() {
let schedule =
DiffusionSchedule::new(Digest::of_bytes("scheduler", b"v1"), vec![1.0, 0.0]).unwrap();
let mut components = BTreeMap::new();
components.insert(
"wan-2.1-vae".to_owned(),
Digest::of_bytes("artifact", b"vae"),
);
assert!(
DiffusionPlan::new(
components.clone(),
Digest::of_bytes("conditioning", b"input"),
Digest::of_bytes("rng", b"v1"),
7,
tensor(),
schedule.clone(),
)
.is_ok()
);
components.insert(
"Invalid".to_owned(),
Digest::of_bytes("artifact", b"invalid"),
);
assert!(
DiffusionPlan::new(
components,
Digest::of_bytes("conditioning", b"input"),
Digest::of_bytes("rng", b"v1"),
7,
tensor(),
schedule,
)
.is_err()
);
}
#[test]
fn step_context_binds_exact_tensor_and_sigmas() {
let schedule =
DiffusionSchedule::new(Digest::of_bytes("scheduler", b"v1"), vec![1.0, 0.0]).unwrap();
let mut components = BTreeMap::new();
components.insert("model".to_owned(), Digest::of_bytes("artifact", b"model"));
let plan = DiffusionPlan::new(
components,
Digest::of_bytes("conditioning", b"input"),
Digest::of_bytes("rng", b"v1"),
7,
tensor(),
schedule,
)
.unwrap();
let mut context = StepContext::for_plan(&plan, 0).unwrap();
context.tensor.device = "other0".to_owned();
assert!(context.validate_for(&plan).is_err());
}
}