Skip to main content

Crate logit_loom_diffusion_sdcpp

Crate logit_loom_diffusion_sdcpp 

Source
Expand description

§logit-loom-diffusion-sdcpp

This crate is the safe adapter between logit-loom-diffusion and the versioned Logit Loom companion ABI for stable-diffusion.cpp.

It supports only the exact catalogued MiniT2I-B/16 and Krea 2 Turbo component sets. The caller supplies:

  • a companion shared-library path;
  • every model-component path;
  • explicit accelerator and parameter backends;
  • thread and flash-attention settings;
  • exact prompt, seed, shape, guidance, and sigma schedule; and
  • either an optional synchronous step program or an image-ABI-v3 whole-image request.

The adapter verifies artifact bytes, companion ABI and upstream commit, reported accelerator devices, conditioning tensors, and each post-Euler state boundary. It copies state transactionally before a step program runs. Callback errors, panics, wrong shapes, and non-finite values return to native code as an error without partial write-back or unwinding across the ABI.

Each successful generation also returns the native denoiser-plus-Euler-update latency for every completed step. These non-deterministic deployment measurements are separate from mechanical receipts and do not affect replay or content identities.

The safe Rust adapter contract is version 9. Its native-facing paths are intentionally explicit:

  • The full-state path copies each post-Euler host f32 tensor for transactional interventions, observations, and checkpoints.
  • The control-only image-v2 path validates boundary metadata without copying or hashing scheduler-state elements. It supports text-to-image, image-to-image, inpaint, outpaint, ordered reference images, negative conditioning, and fixed request-local LoRA stacks, then writes one RGB8 image directly to caller-owned storage or a synchronous sink.
  • generate_advanced_program_to combines the advanced image inputs and fixed request-local LoRA stack with the full-state step program in the same native generation call.
  • generate_from_checkpoint and generate_advanced_program_from_checkpoint_to authenticate a post-step checkpoint against the reconstructed plan and backend, initialize the native latent from its finite state, and begin at its exact next Euler transition. Completed denoise transitions are not replayed.
  • ImagePlanExecutor::execute_checkpointed applies direct continuation to a whole-image plan. Suspension returns opaque same-runtime state and writes no caller output; terminal completion binds every generation and observation segment into the normal whole-plan receipt.

ImagePlanExecutor implements the single-owner LocalExecutor<ImageExecutionPlanV3> boundary. It validates resident profile/load/RNG/placement identities and every borrowed buffer before native entry; restores or captures an authenticated checkpoint at the declared post-Euler boundary before installed scheduler-state operators; records digest/statistics observations after those operators; and observes cancellation after that same boundary. It then runs the ordered deterministic RGB8 mask-blend graph, preflights every route, performs the requested retain/clear cleanup, and only then initializes caller-owned outputs. A cleanup failure therefore cannot leave a partially initialized routed output.

ResidentImageProgramDriver is the default-built execution state machine for ImageProgramPlanV1. Its backend seam addresses only validated logical value numbers, so native arena handles remain private. The driver owns exact stage order, liveness-derived release calls, pre-start/between-stage/post-Euler cancellation terminals, clean rejected-stage receipts, direct materialization into caller-owned output allocations, fixed-point receipt serialization, atomic initialized-prefix publication, cleanup disposition, placement/transfer measurements, and poisoning on uncertainty. Model-free fake-arena tests exercise those mechanics without loading a companion library or model.

ResidentImageProgramDriver::execute_checkpointed separately accepts a checkpoint-suspension probe. At a between-stage or post-Euler safe boundary it copies only still-live bounded logical values to backend-private host representations, retains the exact in-stage scheduler checkpoint when needed, confirms request-arena teardown, and returns an opaque continuation without publishing output. Resume reconstructs a fresh arena, authenticates every value against the original plan and content identity, restores the exact stage cursor, and preserves one terminal receipt across the completed prefix. Cancellation never fabricates a continuation, and capture, reconstruction, or cleanup uncertainty poisons the backend.

SdcppResidentProgram implements that backend over the mandatory stable-diffusion.cpp program ABI v3, model-block ABI v4, and application ABI v5. Krea activation ABI v6 is also mandatory. One arena can execute multiple ordered diffusion and direct-VAE stages, scheduled request-local LoRA scales, authenticated checkpoint restore/capture, scheduler-state interventions and observations, exact-step Krea residual block scaling with transition bitmaps and graph-branch application receipts, exact snapshots, deterministic RGB8 joins, and typed RGB8/RGBA8/PNG/tensor/checkpoint outputs. Krea block indices are validated against the topology detected from the loaded weights; the adapter assigns no semantic role to a block. Native stages keep source images and masks canvas-bound while forwarding bounded reference images with their own exact RGB8/RGBA8 dimensions and bytes. PNG values bind decoded geometry, RGB or RGBA color, a deterministic encoder identity, and a bounded encoded length. During active execution every native intermediate remains behind a generation-checked handle. A suspended continuation contains bounded authenticated host copies, never native handles; cleanup uncertainty poisons the owner.

SdcppResidentProgram::install_krea_activation installs one complete topology-bound activation plan on the loaded runtime for its diffusion stage. Temporary resident-program borrows do not release that installation. The adapter discovers exact conditioning, text-residual, and transformer-residual sites from the resident Krea runtime; imports sealed donors or vector banks once; retains and re-verifies their generation-checked native handles across same-session jobs; and lowers exact token, CFG-branch, and logical-boundary selections. Same-run device-snapshot captures can feed later donor operations without a host-to-device copy. Captures and operations return exact callback evidence, observed resource peaks, and placement/transfer accounting. Release and final clear are idempotent; any post-native mismatch or cleanup uncertainty poisons the owner. Supplying a plan enables all of its mechanics; there is no partial or optional activation mode.

Image-v3 success confirms that every requested LoRA participated in at least one native model tensor. The native stack is cleared before reusable returns; uncertain cleanup poisons the single-owner session. Direct bounded Krea VAE encode/decode exchanges finite native-layout tensors without making that layout portable to another profile or backend build.

The older ImagePlanExecutor whole-plan lowerer supports one native diffusion operation followed by bounded deterministic MaskBlend stages and explicit RGB8/checkpoint routes. Per-step LoRA schedules, arbitrary model-block or conditioning operators, snapshot observations, PNG/RGBA/tensor routes, multiple native inference operations, and version-two direct VAE execution are rejected before native entry instead of being approximated. The complete worker-local support matrix is in docs/image-execution.md.

All whole-plan tests in the ordinary repository gate are model-free. Live execution of either the version-two graph or resident program remains an opt-in acceptance lane over caller-supplied artifacts and an explicit non-CPU device.

No model is downloaded or executed by tests, CI, package builds, or documentation builds. Build the caller-selected native library with scripts/prepare-sdcpp.sh, then follow the opt-in MiniT2I or Krea 2 runbook. The probe_companion example verifies a library’s symbols, ABI, revision, bytes, and device report without loading a model.

The local unsafe boundary is documented in SAFETY.md.

Structs§

AdvancedGenerationOutput
Image ABI v2 generation written to caller-owned storage.
AdvancedGenerationReceipt
Mechanical receipt for one image ABI v2 generation.
AdvancedImageRequest
One image ABI v2 generation request.
AdvancedImageRequestReceipt
Path-free identity of one image ABI v2 request.
AdvancedProgramGenerationOutput
Image ABI v2 generation with a full scheduler-state program, written to caller-owned storage.
AdvancedProgramGenerationReceipt
Mechanical receipt for one image ABI v2 generation with full scheduler state accounting.
BoundaryReceipt
Accounting for one control-only post-Euler boundary.
ChannelBiasControlV1
Fixed binary controls for the installed scheduler-state channel-bias operator.
CompanionReceipt
Model-free evidence for one exact dynamically loaded companion library.
ContinueControl
Boundary controller that always continues.
ControlledGenerationOutput
Control-only generation written into caller-owned storage.
ControlledGenerationReceipt
Path-free mechanical record for control-only native generation.
DiffusionCheckpoint
Exact restorable post-step state plus conservative lineage.
ForkProgram
Captures or restores one exact deterministic-prefix branch boundary.
GenerationMeasurements
Non-deterministic deployment facts for one native generation.
GenerationOutput
One copied native image and its path-free receipt.
GenerationReceipt
Path-free mechanical record for one native generation.
ImageExecutionBindings
Exact identities required when constructing a backend-neutral logit_loom_diffusion::ImageExecutionPlanV3 and validating its backend receipt lineage.
ImagePixels
Tightly packed borrowed image bytes.
ImagePlanContinuation
Opaque same-runtime continuation for one interrupted whole-image plan.
ImagePlanExecutor
Single-owner whole-plan executor over one resident Sdcpp runtime.
ImageRequest
One exact image-generation request.
ImageRequestReceipt
Path-free, prompt-free identity of one exact image request.
KreaActivationExecutionV1
Exact deterministic and placement evidence for one native activation job.
KreaActivationInputBuffer
One caller-verified finite input mapped from a sealed descriptor.
LoraBinding
One caller-verified LoRA path and fixed request-local scale.
LoraBindingReceipt
Path-free identity of one request-local LoRA.
ModelBlockApplicationReceiptV1
Exact application evidence emitted beside one resident image-program receipt.
ModelBlockApplicationV1
Native graph-application accounting for one installed model-block operator.
ModelBlockResidualScaleControlV1
Fixed binary controls for the installed model-block residual-scale operator.
NativeRuntimeReceipt
Exact dynamically loaded runtime and placement evidence.
NoopProgram
A program that leaves state unchanged and continues every step.
PipelineProgram
Adapter glue for backend-neutral transactional pipelines and observers.
PixelReceipt
Path-free identity of tightly packed image bytes.
ProfileReceipt
Path-free receipt for the exact verified component set.
RejectArtifactPaths
Resolver that rejects every path-backed mechanic.
RejectResidentArtifactPaths
Resolver that rejects path-backed program values before native allocation.
ResidentImageProgramContinuation
Exact in-memory continuation for one resident image program.
ResidentImageProgramDriver
Single-owner execution driver over one resident image-program backend.
ResidentImageProgramExecution
Complete deterministic and deployment evidence for one execution attempt.
ResidentProgramCompletedStage
One completed native or deterministic program stage.
ResidentProgramFinish
Confirmed backend finalization for one request-scoped resident program.
ResidentProgramValueCheckpoint
One bounded logical value retained across request-arena reconstruction.
Sdcpp
One loaded exact diffusion profile and companion runtime.
SdcppOptions
Explicit native placement and loading options.
SdcppResidentProgram
Borrowed resident-program backend over one exclusively owned runtime.
SdcppResidentStageCheckpoint
Exact scheduler continuation for one interrupted resident diffusion stage.
SdcppResidentValueCheckpoint
Bounded host representation of one resident value across arena teardown.
StepReceipt
Accounting for one exact post-Euler callback.
VaeImageOutput
Direct VAE decode result.
VaeOperationReceipt
Mechanical direct-VAE operation receipt.
VaeTensor
Exact finite host tensor produced or consumed by direct VAE operations.
VaeTensorOutput
Direct VAE encode result.

Enums§

CheckpointedImageExecution
Result of one checkpoint-aware whole-image execution attempt.
CheckpointedResidentImageProgramExecution
Result of checkpoint-aware resident program execution.
Error
Safe adapter failure.
Profile
Exact catalogued image profile understood by the companion ABI.
ProfileArtifacts
Caller-selected paths for exact catalogued model components.
ResidentProgramStageTerminal
Exact result of attempting one resident program stage.

Constants§

ADAPTER_CONTRACT_VERSION
Version of the safe Rust execution contract layered over the companion.
COMPANION_ABI_VERSION
Companion ABI version implemented by this adapter.
IMAGE_ABI_VERSION
Version of the whole-image extension layered over companion ABI v2.
KREA_ACTIVATION_ABI_VERSION
Version of the native Krea activation topology, capture, resident-input, operator, and cleanup extension.
MAX_BACKEND_LABEL_BYTES
Maximum native backend label bytes.
MAX_CHECKPOINT_ENVELOPE_BYTES
Maximum complete version-one checkpoint envelope bytes.
MAX_CHECKPOINT_RECEIPT_BYTES
Maximum serialized checkpoint-lineage bytes accepted by the adapter.
MAX_CHECKPOINT_STATE_BYTES
Maximum exact f32 scheduler-state bytes in one checkpoint.
MAX_IMAGE_DIMENSION
Maximum output image dimension.
MAX_PROMPT_BYTES
Maximum UTF-8 bytes accepted before caller-owned token-context admission, without imposing the former hidden 64 KiB native-adapter cap.
MAX_REFERENCE_IMAGES
Maximum reference images in one native request.
MAX_REQUEST_LORAS
Maximum fixed-scale LoRA entries in one native request.
MAX_VAE_TENSOR_RANK
Maximum rank accepted for an explicit VAE tensor.
MODEL_BLOCK_ABI_VERSION
Version of the native model-block operator and application-attestation extension.
PROGRAM_ABI_VERSION
Version of the resident native value-arena extension.
UPSTREAM_COMMIT
Exact stable-diffusion.cpp revision required by this adapter.

Traits§

ArtifactPathResolver
Resolves an already verified opaque artifact to a caller-managed path that the pinned native ABI can reopen synchronously.
BoundaryControl
Lightweight synchronous control at exact post-Euler boundaries.
CheckpointSuspensionProbe
Worker-local signal that distinguishes checkpoint suspension from terminal cancellation.
ImageOutputSink
Caller-owned destination for one complete native image.
ResidentArtifactPathResolver
Resolves one verified program-local LoRA artifact to a synchronous, caller-retained descriptor path.
ResidentImageProgramBackend
Backend boundary used by ResidentImageProgramDriver.
StepProgram
Synchronous behavior at exact diffusion boundaries.

Functions§

channel_bias_schema_v1
Returns the public schema identity for ChannelBiasControlV1.
lora_target_v1
Returns the exact fixed-scale whole-request LoRA target identity.
model_block_residual_scale_schema_v1
Returns the public schema identity for ModelBlockResidualScaleControlV1.
probe_companion
Verifies and inspects one exact companion shared library without loading a model or requiring an accelerator.
resident_checkpoint_compatibility_v1
Exact checkpoint-state compatibility for one resident runtime binding.
resident_checkpoint_conversion_v1
Exact restore/capture conversion implementation for resident checkpoints.
resident_lora_target_v1
Exact scheduled request-local LoRA target installed by companion ABI v3.
resident_png_encoding_v1
Exact deterministic resident PNG encoder implementation.
resident_png_maximum_bytes_v1
Conservative encoded length required by the resident PNG implementation.

Type Aliases§

Result
Result returned by the stable-diffusion.cpp adapter.