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
f32tensor 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
LoRAstacks, then writes one RGB8 image directly to caller-owned storage or a synchronous sink. generate_advanced_program_tocombines the advanced image inputs and fixed request-localLoRAstack with the full-state step program in the same native generation call.generate_from_checkpointandgenerate_advanced_program_from_checkpoint_toauthenticate 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_checkpointedapplies 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§
- Advanced
Generation Output - Image ABI v2 generation written to caller-owned storage.
- Advanced
Generation Receipt - Mechanical receipt for one image ABI v2 generation.
- Advanced
Image Request - One image ABI v2 generation request.
- Advanced
Image Request Receipt - Path-free identity of one image ABI v2 request.
- Advanced
Program Generation Output - Image ABI v2 generation with a full scheduler-state program, written to caller-owned storage.
- Advanced
Program Generation Receipt - Mechanical receipt for one image ABI v2 generation with full scheduler state accounting.
- Boundary
Receipt - Accounting for one control-only post-Euler boundary.
- Channel
Bias Control V1 - Fixed binary controls for the installed scheduler-state channel-bias operator.
- Companion
Receipt - Model-free evidence for one exact dynamically loaded companion library.
- Continue
Control - Boundary controller that always continues.
- Controlled
Generation Output - Control-only generation written into caller-owned storage.
- Controlled
Generation Receipt - Path-free mechanical record for control-only native generation.
- Diffusion
Checkpoint - Exact restorable post-step state plus conservative lineage.
- Fork
Program - Captures or restores one exact deterministic-prefix branch boundary.
- Generation
Measurements - Non-deterministic deployment facts for one native generation.
- Generation
Output - One copied native image and its path-free receipt.
- Generation
Receipt - Path-free mechanical record for one native generation.
- Image
Execution Bindings - Exact identities required when constructing a backend-neutral
logit_loom_diffusion::ImageExecutionPlanV3and validating its backend receipt lineage. - Image
Pixels - Tightly packed borrowed image bytes.
- Image
Plan Continuation - Opaque same-runtime continuation for one interrupted whole-image plan.
- Image
Plan Executor - Single-owner whole-plan executor over one resident
Sdcppruntime. - Image
Request - One exact image-generation request.
- Image
Request Receipt - Path-free, prompt-free identity of one exact image request.
- Krea
Activation Execution V1 - Exact deterministic and placement evidence for one native activation job.
- Krea
Activation Input Buffer - One caller-verified finite input mapped from a sealed descriptor.
- Lora
Binding - One caller-verified
LoRApath and fixed request-local scale. - Lora
Binding Receipt - Path-free identity of one request-local
LoRA. - Model
Block Application Receipt V1 - Exact application evidence emitted beside one resident image-program receipt.
- Model
Block Application V1 - Native graph-application accounting for one installed model-block operator.
- Model
Block Residual Scale Control V1 - Fixed binary controls for the installed model-block residual-scale operator.
- Native
Runtime Receipt - Exact dynamically loaded runtime and placement evidence.
- Noop
Program - A program that leaves state unchanged and continues every step.
- Pipeline
Program - Adapter glue for backend-neutral transactional pipelines and observers.
- Pixel
Receipt - Path-free identity of tightly packed image bytes.
- Profile
Receipt - Path-free receipt for the exact verified component set.
- Reject
Artifact Paths - Resolver that rejects every path-backed mechanic.
- Reject
Resident Artifact Paths - Resolver that rejects path-backed program values before native allocation.
- Resident
Image Program Continuation - Exact in-memory continuation for one resident image program.
- Resident
Image Program Driver - Single-owner execution driver over one resident image-program backend.
- Resident
Image Program Execution - Complete deterministic and deployment evidence for one execution attempt.
- Resident
Program Completed Stage - One completed native or deterministic program stage.
- Resident
Program Finish - Confirmed backend finalization for one request-scoped resident program.
- Resident
Program Value Checkpoint - One bounded logical value retained across request-arena reconstruction.
- Sdcpp
- One loaded exact diffusion profile and companion runtime.
- Sdcpp
Options - Explicit native placement and loading options.
- Sdcpp
Resident Program - Borrowed resident-program backend over one exclusively owned runtime.
- Sdcpp
Resident Stage Checkpoint - Exact scheduler continuation for one interrupted resident diffusion stage.
- Sdcpp
Resident Value Checkpoint - Bounded host representation of one resident value across arena teardown.
- Step
Receipt - Accounting for one exact post-Euler callback.
- VaeImage
Output - Direct VAE decode result.
- VaeOperation
Receipt - Mechanical direct-VAE operation receipt.
- VaeTensor
- Exact finite host tensor produced or consumed by direct VAE operations.
- VaeTensor
Output - Direct VAE encode result.
Enums§
- Checkpointed
Image Execution - Result of one checkpoint-aware whole-image execution attempt.
- Checkpointed
Resident Image Program Execution - Result of checkpoint-aware resident program execution.
- Error
- Safe adapter failure.
- Profile
- Exact catalogued image profile understood by the companion ABI.
- Profile
Artifacts - Caller-selected paths for exact catalogued model components.
- Resident
Program Stage Terminal - 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
f32scheduler-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
LoRAentries 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§
- Artifact
Path Resolver - Resolves an already verified opaque artifact to a caller-managed path that the pinned native ABI can reopen synchronously.
- Boundary
Control - Lightweight synchronous control at exact post-Euler boundaries.
- Checkpoint
Suspension Probe - Worker-local signal that distinguishes checkpoint suspension from terminal cancellation.
- Image
Output Sink - Caller-owned destination for one complete native image.
- Resident
Artifact Path Resolver - Resolves one verified program-local
LoRAartifact to a synchronous, caller-retained descriptor path. - Resident
Image Program Backend - Backend boundary used by
ResidentImageProgramDriver. - Step
Program - 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
LoRAtarget 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
LoRAtarget 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.