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:
ImageExecutionPlanandImageExecutionReceiptpreserve the version-one operation, buffer, placement, seed, schedule,LoRA, operator, observation, and terminal-position domains.ImageExecutionPlanV2andImageExecutionReceiptV2add transactional checkpoint restore/capture, an ordered deterministic compositing graph, explicit caller-owned output routes, and request-scope cleanup disposition under new identity domains.ImageExecutionPlanV3andImageExecutionReceiptV3preserve the current single-native-primary lowering under their own identity domains.ImageProgramPlanV1andImageProgramReceiptV1define a separate bounded resident program over typed single-assignment values and multiple ordered native, mask-blend, checkpoint-restore, and checkpoint-capture stages.KreaActivationPlanV1,KreaActivationReceiptV1, andKreaActivationMeasurementsV1define topology-bound activation capture, resident donor/vector inputs, ordered operations, exact application evidence, resource bounds, and cleanup without semantic labels.ProjectedComponentPlanV1defines a deterministic create-new projection transform for selectedF32SafeTensorsmatrices 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§
- Activation
Statistics V1 - Deterministic scalar statistics represented by exact
f32bits. - Buffer
Spec - Exact metadata for one borrowed or writable byte buffer.
- Channel
Bias - A bounded additive operation over one channel of a contiguous tensor.
- Diffusion
Checkpoint Receipt - Conservative lineage for opaque adapter checkpoint bytes.
- Diffusion
Plan - Exact model, conditioning, random-state, tensor, and schedule contract.
- Diffusion
Schedule - Exact scheduler implementation and descending sigma sequence.
- Digest
- A domain-separated BLAKE3 digest encoded as 64 lowercase hexadecimal bytes.
- Image
Buffer Binding - One exact input-slot binding in an image execution plan.
- Image
Checkpoint Plan - Transactional checkpoint mechanics around the primary diffusion operation.
- Image
Composite Receipt - Deterministic composite lineage.
- Image
Composite Stage - One ordered deterministic compositing stage.
- Image
Execution Plan - Complete exact image execution mechanics and input identities.
- Image
Execution Plan V2 - Version-two whole-image execution contract.
- Image
Execution Plan V3 - Version-three whole-image execution contract.
- Image
Execution Receipt - Deterministic mechanical receipt for one image execution.
- Image
Execution Receipt V2 - Deterministic whole-plan receipt for
ImageExecutionPlanV2. - Image
Execution Receipt V3 - Deterministic whole-plan receipt for
ImageExecutionPlanV3. - Image
Output Receipt V2 - Exact output write accounting.
- Image
Output Receipt V3 - Exact output write accounting.
- Image
Output Route - One ordered output route.
- Image
Program Input Binding V1 - One native-stage input role bound to an earlier logical value.
- Image
Program Input V1 - One external value and its exact caller-owned input metadata.
- Image
Program Liveness V1 - Conservative preflight value-arena accounting.
- Image
Program Lora V1 - One scheduled adapter applied by a native stage.
- Image
Program Measurements V1 - Deployment measurements excluded from deterministic plan and receipt identities.
- Image
Program Native Output V1 - One typed value produced by a native image stage.
- Image
Program Native Stage V1 - One exact diffusion or direct-VAE operation inside a resident program.
- Image
Program Output Receipt V1 - Exact initialized output accounting.
- Image
Program Output Route V1 - One ordered caller-owned output route.
- Image
Program Plan V1 - Complete bounded resident image program.
- Image
Program Receipt V1 - Deterministic mechanical receipt for one resident image program.
- Image
Program Release V1 - Release point derived for one logical program value.
- Image
Program Stage Receipt V1 - Deterministic receipt for one completed program stage.
- Image
Program Stage V1 - One ordered stage in a resident image program.
- Image
Program Value Measurement V1 - Non-deterministic placement and transfer measurements for one value.
- Image
Program Value Receipt V1 - Exact content identity and initialized length of one produced value.
- Image
Program Value V1 - One numbered logical value in a resident image program.
- Intervention
Failure - Complete callback error or contained panic.
- Intervention
Spec - Exact contract for one ordered state intervention.
- Krea
Activation Application V1 - Deterministic application evidence for one installed operation.
- Krea
Activation Capture Receipt V1 - Deterministic capture evidence.
- Krea
Activation Capture V1 - One bounded capture request.
- Krea
Activation Input Measurement V1 - Observed placement and transfer accounting for one imported input.
- Krea
Activation Input V1 - One topology-bound activation input retained by a resident session.
- Krea
Activation Measurements V1 - Non-deterministic placement/transfer measurements excluded from semantic identities.
- Krea
Activation Operation V1 - One ordered, site/token/transition/branch-scoped operation.
- Krea
Activation Plan V1 - Complete always-on Krea activation request for one resident image stage.
- Krea
Activation Receipt V1 - Complete deterministic Krea activation execution evidence.
- Krea
Activation Site V1 - One runtime-derived, topology-bound activation site.
- Krea
Activation Topology V1 - Exact topology discovered from one loaded Krea runtime.
- Krea
Token Domain V1 - Runtime bound for one token family at a site.
- Krea
Token Range V1 - Half-open token interval.
- Lora
Stack Entry - One entry in the exact ordered
LoRAstack. - Observation
Request - One exact batched observation request.
- Observer
Receipt - Mechanical accounting for one post-step observer.
- Observer
Set - Ordered post-step observer fan-out.
- Operator
Invocation - One exact installed operator invocation.
- Pipeline
- An ordered transactional intervention pipeline.
- Pipeline
Receipt - Aggregate transactional pipeline accounting.
- Pipeline
Spec - Ordered diffusion intervention contracts.
- Projected
Component Basis V1 - Exact orthonormal basis declaration.
- Projected
Component Manifest V1 - Complete create-new component mutation manifest.
- Projected
Component Output V1 - Successful create-new transformation output.
- Projected
Component Plan V1 - Exact create-new component transform.
- Projected
Component Tensor Receipt V1 - Before/after identity for one transformed tensor.
- Scale
Point - One exact
LoRAscale beginning at a completed-step boundary. - Scale
Schedule - Canonical piecewise-constant
LoRAscale schedule. - Stage
Receipt - Mechanical accounting for one intervention stage.
- Step
Context - Exact post-step state boundary presented to Rust.
- Tensor
Spec - Exact shape, scalar, layout, and device of one diffusion state.
Enums§
- Control
Flow - Cooperative action returned at a documented safe execution boundary.
- Error
- Failure before native state can be committed.
- Image
Buffer Layout - Exact interpretation of bytes at the public execution boundary.
- Image
Buffer Role - Logical role of an exact execution buffer.
- Image
Cleanup Disposition - Observed request-scope cleanup outcome.
- Image
Cleanup Policy - Request-scope native cleanup behavior.
- Image
Composite Operation - One deterministic postprocess operation.
- Image
Opaque Value Kind V1 - Exact semantics of one backend-native opaque value.
- Image
Operation - Whole-image operation selected by an exact execution plan.
- Image
Output Format - Requested final image representation.
- Image
Output Source - Value routed into one caller-owned output allocation.
- Image
PngColor V1 - Exact decoded pixel representation carried by one PNG value.
- Image
Program Cleanup Disposition V1 - Observed cleanup outcome for one resident image program.
- Image
Program Native Output Role V1 - Mechanical role of one value produced by a native stage.
- Image
Program Output Source V1 - Value selected for one caller-owned output allocation.
- Image
Program Stage Operation V1 - One ordered resident program operation.
- Image
Program Terminal V1 - Terminal boundary reached by one resident image program.
- Image
Program Value Placement V1 - Observed native placement of one logical value.
- Image
Program Value Spec V1 - Exact logical representation of one resident program value.
- Image
Terminal - Terminal boundary reached by an image execution.
- Image
Value Source - One image value available to a deterministic postprocess stage or output route.
- Krea
Activation Boundary Kind V1 - Evaluation families available at one runtime-derived site.
- Krea
Activation Boundary V1 - Execution boundary selected by a capture or operator.
- Krea
Activation Capture Retention V1 - Data retained for one activation capture.
- Krea
Activation Cleanup Disposition V1 - Request-local cleanup disposition.
- Krea
Activation Element Type V1 - Scalar representation at a Krea activation site.
- Krea
Activation Input Kind V1 - Mechanical role of one imported activation value.
- Krea
Activation Input Source V1 - Origin of one typed activation input.
- Krea
Activation Layout V1 - Canonical logical layout of a Krea activation tensor.
- Krea
Activation Operator V1 - Built-in Krea activation operation.
- Krea
Activation Site Kind V1 - Runtime-derived Krea site family.
- Krea
Activation Terminal V1 - Terminal boundary reached by an activation request.
- Krea
CfgBranch V1 - Classifier-free-guidance branch selected by a mechanic.
- Krea
Token Domain Kind V1 - Logical token family addressable at a site.
- Krea
Token Selection V1 - Exact token rows selected at one site.
- Krea
Vector Representation V1 - Exact representation of an imported Krea vector bank.
- Observation
Kind - Data retained at selected execution boundaries.
- Projected
Component Formula V1 - Matrix side on which an orthogonal projection is applied.
- Projected
Component Reduction V1 - Deterministic reduction and output-scalar policy.
- Seed
Selection - Resolution policy for the exact execution seed.
- Step
Selector - Exact schedule boundaries selected for one mechanic.
- TensorD
Type - Tensor scalar representation at the intervention boundary.
- Tensor
Layout - Contiguous element ordering at the intervention boundary.
- Tensor
Selector - 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
LoRAentries 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
f32elements 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
SafeTensorsJSON 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
f32elements copied transactionally.
Traits§
- Intervention
- One synchronous state intervention.
- Step
Observer - 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
f32bytes. - mask_
blend_ rgb8 - Applies the version-two RGB8 mask-blend contract into caller-owned output.
- project_
safetensors_ component_ v1 - Creates a new projected
SafeTensorscomponent 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.