Skip to main content

Crate logit_loom_diffusion

Crate logit_loom_diffusion 

Source
Expand description

§logit-loom-diffusion

Backend-neutral mechanics for iterative image-generation state. This crate keeps diffusion tensors distinct from token IDs and logits.

It provides bounded, serializable tensor, schedule, plan, checkpoint, stage, and receipt contracts; ordered transactional intervention pipelines; and post-step observers. A pipeline copies one finite f32 state, applies stages in declared order, and commits to the caller’s slice only after every stage succeeds. Callback errors and panics are contained before commit.

The crate also defines compatible worker-local whole-image contract families:

  • ImageExecutionPlan and ImageExecutionReceipt preserve the version-one operation, buffer, placement, seed, schedule, LoRA, operator, observation, and terminal-position domains.
  • ImageExecutionPlanV2 and ImageExecutionReceiptV2 add transactional checkpoint restore/capture, an ordered deterministic compositing graph, explicit caller-owned output routes, and request-scope cleanup disposition under new identity domains.
  • ImageExecutionPlanV3 and ImageExecutionReceiptV3 preserve the current single-native-primary lowering under their own identity domains.
  • ImageProgramPlanV1 and ImageProgramReceiptV1 define a separate bounded resident program over typed single-assignment values and multiple ordered native, mask-blend, checkpoint-restore, and checkpoint-capture stages.
  • KreaActivationPlanV1, KreaActivationReceiptV1, and KreaActivationMeasurementsV1 define topology-bound activation capture, resident donor/vector inputs, ordered operations, exact application evidence, resource bounds, and cleanup without semantic labels.
  • ProjectedComponentPlanV1 defines a deterministic create-new projection transform for selected F32 SafeTensors matrices with exact source, basis, output, and per-tensor lineage.

The single-primary contracts define one bounded RGB8 diffusion primary followed by zero or more exact integer MaskBlend stages. The resident-program contract adds canonical value producers, earlier-stage-only references, operation-specific type and geometry checks, immutable branching, mutable checkpoint-state single consumption, liveness-derived release points, a 2 GiB arena ceiling, explicit value and receipt routes, completed-stage prefix receipts, cleanup uncertainty, and placement/transfer measurements outside deterministic identity. Stage-produced values use the image-program-value-content-v1 content domain so an executor can verify explicit materialization without reinterpreting the value.

Source images and masks are bound to the native stage canvas. Reference images instead retain their own bounded, tightly packed RGB8 or RGBA8 dimensions in the serialized value specification and plan identity; the contract performs no implicit resize, crop, or byte transformation.

Krea activation plans bind exact runtime-discovered sites, widths, token domains, CFG branches, and logical boundaries. They have no optional enablement field. Sealed donor tensors and vector banks may be imported once and reused in one resident session; a device-snapshot capture may be consumed as a same-run SSA donor without a host-to-device transfer. Public operations cover donor transplant, scaled vector add/subtract, orthogonal projection removal, and one-sided projection removal. Receipts establish what ran and measurements establish observed residency/copies; neither assigns a concept to an activation.

The projected-component reference transform never mutates its source. It preserves the SafeTensors header, metadata, offsets, length, and unselected bytes while creating a separately identified output for later ordinary artifact import.

mask_blend_rgb8 validates every length before its first write. These contracts contain no paths, transport, queue, native handles, or feature-gated availability. An adapter must reject plan mechanics it cannot implement exactly.

The crate owns no tensor runtime and performs no model inference. An adapter must prove that its native state has the reported shape, dtype, device, schedule step, plan identity, and contiguous dimension-zero-fastest layout before calling these mechanics.

use std::collections::BTreeMap;

use logit_loom_core::Digest;
use logit_loom_diffusion::{
    ChannelBias, DiffusionPlan, DiffusionSchedule, Pipeline, StepContext,
    TensorDType, TensorLayout, TensorSpec,
};

fn run() -> Result<(), Box<dyn std::error::Error>> {
    let tensor = TensorSpec::new(
        vec![2, 2, 3, 1],
        TensorDType::F32,
        TensorLayout::DimensionZeroFastest,
        "vulkan0",
    )?;
    let schedule = DiffusionSchedule::new(
        Digest::of_bytes("scheduler", b"linear-flow-v1"),
        vec![1.0, 0.5, 0.0],
    )?;
    let mut components = BTreeMap::new();
    components.insert("transformer".to_owned(), Digest::of_bytes("artifact", b"model"));
    let plan = DiffusionPlan::new(
        components,
        Digest::of_bytes("conditioning", b"exact-tokenization-output"),
        Digest::of_bytes("rng", b"cpu-rng-v1"),
        7,
        tensor.clone(),
        schedule,
    )?;
    let context = StepContext::for_plan(&plan, 0)?;
    let stage = ChannelBias::new(&tensor, 2, 0, 0.05, 0.1)?;
    let mut pipeline = Pipeline::new(plan.digest()?, tensor, vec![Box::new(stage)])?;
    pipeline.begin()?;

    let mut state = vec![0.0; 12];
    pipeline.apply(&context, &mut state)?;
    assert_eq!(pipeline.receipt().invocations, 1);
    Ok(())
}

Receipts establish ordering, bounds, identities, and state lineage. They do not establish that an intervention improves an image or model behavior.

Structs§

ActivationStatisticsV1
Deterministic scalar statistics represented by exact f32 bits.
BufferSpec
Exact metadata for one borrowed or writable byte buffer.
ChannelBias
A bounded additive operation over one channel of a contiguous tensor.
DiffusionCheckpointReceipt
Conservative lineage for opaque adapter checkpoint bytes.
DiffusionPlan
Exact model, conditioning, random-state, tensor, and schedule contract.
DiffusionSchedule
Exact scheduler implementation and descending sigma sequence.
Digest
A domain-separated BLAKE3 digest encoded as 64 lowercase hexadecimal bytes.
ImageBufferBinding
One exact input-slot binding in an image execution plan.
ImageCheckpointPlan
Transactional checkpoint mechanics around the primary diffusion operation.
ImageCompositeReceipt
Deterministic composite lineage.
ImageCompositeStage
One ordered deterministic compositing stage.
ImageExecutionPlan
Complete exact image execution mechanics and input identities.
ImageExecutionPlanV2
Version-two whole-image execution contract.
ImageExecutionPlanV3
Version-three whole-image execution contract.
ImageExecutionReceipt
Deterministic mechanical receipt for one image execution.
ImageExecutionReceiptV2
Deterministic whole-plan receipt for ImageExecutionPlanV2.
ImageExecutionReceiptV3
Deterministic whole-plan receipt for ImageExecutionPlanV3.
ImageOutputReceiptV2
Exact output write accounting.
ImageOutputReceiptV3
Exact output write accounting.
ImageOutputRoute
One ordered output route.
ImageProgramInputBindingV1
One native-stage input role bound to an earlier logical value.
ImageProgramInputV1
One external value and its exact caller-owned input metadata.
ImageProgramLivenessV1
Conservative preflight value-arena accounting.
ImageProgramLoraV1
One scheduled adapter applied by a native stage.
ImageProgramMeasurementsV1
Deployment measurements excluded from deterministic plan and receipt identities.
ImageProgramNativeOutputV1
One typed value produced by a native image stage.
ImageProgramNativeStageV1
One exact diffusion or direct-VAE operation inside a resident program.
ImageProgramOutputReceiptV1
Exact initialized output accounting.
ImageProgramOutputRouteV1
One ordered caller-owned output route.
ImageProgramPlanV1
Complete bounded resident image program.
ImageProgramReceiptV1
Deterministic mechanical receipt for one resident image program.
ImageProgramReleaseV1
Release point derived for one logical program value.
ImageProgramStageReceiptV1
Deterministic receipt for one completed program stage.
ImageProgramStageV1
One ordered stage in a resident image program.
ImageProgramValueMeasurementV1
Non-deterministic placement and transfer measurements for one value.
ImageProgramValueReceiptV1
Exact content identity and initialized length of one produced value.
ImageProgramValueV1
One numbered logical value in a resident image program.
InterventionFailure
Complete callback error or contained panic.
InterventionSpec
Exact contract for one ordered state intervention.
KreaActivationApplicationV1
Deterministic application evidence for one installed operation.
KreaActivationCaptureReceiptV1
Deterministic capture evidence.
KreaActivationCaptureV1
One bounded capture request.
KreaActivationInputMeasurementV1
Observed placement and transfer accounting for one imported input.
KreaActivationInputV1
One topology-bound activation input retained by a resident session.
KreaActivationMeasurementsV1
Non-deterministic placement/transfer measurements excluded from semantic identities.
KreaActivationOperationV1
One ordered, site/token/transition/branch-scoped operation.
KreaActivationPlanV1
Complete always-on Krea activation request for one resident image stage.
KreaActivationReceiptV1
Complete deterministic Krea activation execution evidence.
KreaActivationSiteV1
One runtime-derived, topology-bound activation site.
KreaActivationTopologyV1
Exact topology discovered from one loaded Krea runtime.
KreaTokenDomainV1
Runtime bound for one token family at a site.
KreaTokenRangeV1
Half-open token interval.
LoraStackEntry
One entry in the exact ordered LoRA stack.
ObservationRequest
One exact batched observation request.
ObserverReceipt
Mechanical accounting for one post-step observer.
ObserverSet
Ordered post-step observer fan-out.
OperatorInvocation
One exact installed operator invocation.
Pipeline
An ordered transactional intervention pipeline.
PipelineReceipt
Aggregate transactional pipeline accounting.
PipelineSpec
Ordered diffusion intervention contracts.
ProjectedComponentBasisV1
Exact orthonormal basis declaration.
ProjectedComponentManifestV1
Complete create-new component mutation manifest.
ProjectedComponentOutputV1
Successful create-new transformation output.
ProjectedComponentPlanV1
Exact create-new component transform.
ProjectedComponentTensorReceiptV1
Before/after identity for one transformed tensor.
ScalePoint
One exact LoRA scale beginning at a completed-step boundary.
ScaleSchedule
Canonical piecewise-constant LoRA scale schedule.
StageReceipt
Mechanical accounting for one intervention stage.
StepContext
Exact post-step state boundary presented to Rust.
TensorSpec
Exact shape, scalar, layout, and device of one diffusion state.

Enums§

ControlFlow
Cooperative action returned at a documented safe execution boundary.
Error
Failure before native state can be committed.
ImageBufferLayout
Exact interpretation of bytes at the public execution boundary.
ImageBufferRole
Logical role of an exact execution buffer.
ImageCleanupDisposition
Observed request-scope cleanup outcome.
ImageCleanupPolicy
Request-scope native cleanup behavior.
ImageCompositeOperation
One deterministic postprocess operation.
ImageOpaqueValueKindV1
Exact semantics of one backend-native opaque value.
ImageOperation
Whole-image operation selected by an exact execution plan.
ImageOutputFormat
Requested final image representation.
ImageOutputSource
Value routed into one caller-owned output allocation.
ImagePngColorV1
Exact decoded pixel representation carried by one PNG value.
ImageProgramCleanupDispositionV1
Observed cleanup outcome for one resident image program.
ImageProgramNativeOutputRoleV1
Mechanical role of one value produced by a native stage.
ImageProgramOutputSourceV1
Value selected for one caller-owned output allocation.
ImageProgramStageOperationV1
One ordered resident program operation.
ImageProgramTerminalV1
Terminal boundary reached by one resident image program.
ImageProgramValuePlacementV1
Observed native placement of one logical value.
ImageProgramValueSpecV1
Exact logical representation of one resident program value.
ImageTerminal
Terminal boundary reached by an image execution.
ImageValueSource
One image value available to a deterministic postprocess stage or output route.
KreaActivationBoundaryKindV1
Evaluation families available at one runtime-derived site.
KreaActivationBoundaryV1
Execution boundary selected by a capture or operator.
KreaActivationCaptureRetentionV1
Data retained for one activation capture.
KreaActivationCleanupDispositionV1
Request-local cleanup disposition.
KreaActivationElementTypeV1
Scalar representation at a Krea activation site.
KreaActivationInputKindV1
Mechanical role of one imported activation value.
KreaActivationInputSourceV1
Origin of one typed activation input.
KreaActivationLayoutV1
Canonical logical layout of a Krea activation tensor.
KreaActivationOperatorV1
Built-in Krea activation operation.
KreaActivationSiteKindV1
Runtime-derived Krea site family.
KreaActivationTerminalV1
Terminal boundary reached by an activation request.
KreaCfgBranchV1
Classifier-free-guidance branch selected by a mechanic.
KreaTokenDomainKindV1
Logical token family addressable at a site.
KreaTokenSelectionV1
Exact token rows selected at one site.
KreaVectorRepresentationV1
Exact representation of an imported Krea vector bank.
ObservationKind
Data retained at selected execution boundaries.
ProjectedComponentFormulaV1
Matrix side on which an orthogonal projection is applied.
ProjectedComponentReductionV1
Deterministic reduction and output-scalar policy.
SeedSelection
Resolution policy for the exact execution seed.
StepSelector
Exact schedule boundaries selected for one mechanic.
TensorDType
Tensor scalar representation at the intervention boundary.
TensorLayout
Contiguous element ordering at the intervention boundary.
TensorSelector
Exact tensor site selected by an installed mechanic.

Constants§

MAX_COMPONENTS
Maximum identified model components in one plan.
MAX_DEVICE_LABEL_BYTES
Maximum UTF-8 bytes in one device label.
MAX_DIFFUSION_STEPS
Maximum scheduler steps in one plan.
MAX_IMAGE_BUFFERS
Maximum input or output buffer bindings in one image execution.
MAX_IMAGE_COMPOSITE_STAGES
Maximum deterministic compositing stages in one image plan.
MAX_IMAGE_DIMENSION
Maximum image dimension accepted by the generic execution contract.
MAX_IMAGE_GRAPH_SCRATCH_BYTES
Maximum aggregate primary-plus-composite scratch bytes in one image graph.
MAX_IMAGE_LORAS
Maximum ordered LoRA entries in one image execution.
MAX_IMAGE_OBSERVATIONS
Maximum observation requests in one image execution.
MAX_IMAGE_OPERATORS
Maximum installed operator invocations in one image execution.
MAX_IMAGE_PROGRAM_ARENA_BYTES
Maximum liveness-derived resident value-arena size.
MAX_IMAGE_PROGRAM_INPUTS
Maximum external inputs in one resident image program.
MAX_IMAGE_PROGRAM_OUTPUTS
Maximum caller-owned output routes in one resident image program.
MAX_IMAGE_PROGRAM_STAGES
Maximum ordered stages in one resident image program.
MAX_IMAGE_PROGRAM_VALUES
Maximum typed values in one resident image program.
MAX_IMAGE_PROGRAM_VALUE_BYTES
Maximum declared size of one logical program value.
MAX_INTERVENTION_STAGES
Maximum stages in one intervention pipeline.
MAX_KREA_ACTIVATION_APPLICATIONS
Maximum aggregate applications retained in one receipt.
MAX_KREA_ACTIVATION_CAPTURES
Maximum captures in one resident request.
MAX_KREA_ACTIVATION_ELEMENTS
Maximum finite f32 elements in one Krea activation value.
MAX_KREA_ACTIVATION_INPUTS
Maximum activation inputs retained by one resident session.
MAX_KREA_ACTIVATION_OPERATIONS
Maximum ordered Krea activation operations in one request.
MAX_KREA_ACTIVATION_SITES
Maximum Krea activation sites reported by one loaded topology.
MAX_KREA_ACTIVATION_VALUE_BYTES
Maximum bytes retained for one activation input or capture.
MAX_KREA_TOKEN_RANGES
Maximum token-domain ranges in one selection.
MAX_KREA_VECTOR_RANK
Maximum vector rank accepted by one activation input.
MAX_OPERATOR_CONTROL_BYTES
Maximum schema-specific bytes in one installed operator invocation.
MAX_PROJECTED_COMPONENT_BASIS_ELEMENTS
Maximum finite basis elements accepted by the reference transform.
MAX_PROJECTED_COMPONENT_BASIS_RANK
Maximum basis rank accepted by the reference transform.
MAX_PROJECTED_COMPONENT_HEADER_BYTES
Maximum SafeTensors JSON header accepted by the transform.
MAX_PROJECTED_COMPONENT_TENSORS
Maximum selected tensors in one derived-component transform.
MAX_PROJECTED_COMPONENT_TENSOR_NAME_BYTES
Maximum UTF-8 bytes in one selected tensor name.
MAX_SELECTOR_LABEL_BYTES
Maximum bytes in one selector label.
MAX_TENSOR_DIMENSIONS
Maximum tensor rank accepted at the public boundary.
MAX_TENSOR_ELEMENTS
Maximum contiguous f32 elements copied transactionally.

Traits§

Intervention
One synchronous state intervention.
StepObserver
One synchronous observer at an exact post-step committed-state boundary.

Functions§

apply_krea_activation_operation_v1
Applies one built-in operation to a single finite activation row.
image_program_value_content
Returns the canonical content identity for one produced program value.
krea_activation_input_content_v1
Returns the canonical content identity for imported finite f32 bytes.
mask_blend_rgb8
Applies the version-two RGB8 mask-blend contract into caller-owned output.
project_safetensors_component_v1
Creates a new projected SafeTensors component without changing the source.
projected_component_basis_v1
Returns the exact canonical little-endian basis identity.
projected_component_implementation_v1
Returns the exact reference-transform implementation identity.
projected_component_output_v1
Returns the exact derived-component identity.
projected_component_source_v1
Returns the exact source-component identity.
verify_projected_component_v1
Recomputes and verifies one complete create-new transform.

Type Aliases§

Result
Result returned by backend-neutral diffusion mechanics.