diffusers-workflow 0.4.0__py3-none-any.whl

dw/docs/QUANTIZATION.md

@@ -0,0 +1,230 @@
+# Quantization
+
+Quantization reduces model memory usage by storing weights at lower precision. diffusers-workflow ships examples for BitsAndBytes, TorchAO, GGUF, and SDNQ, applied per-component in the pipeline - and any other backend with a config class (optimum-quanto, for example) works through the same dynamic `config_type` import.
+
+## Per-Component Quantization
+
+Quantize individual components (transformer, text encoder, etc.) independently:
+
+```json
+{
+    "pipeline": {
+        "transformer": {
+            "configuration": { "component_type": "FluxTransformer2DModel" },
+            "quantization_config": {
+                "configuration": { "config_type": "..." },
+                "arguments": { ... }
+            },
+            "from_pretrained_arguments": {
+                "model_name": "...",
+                "subfolder": "transformer",
+                "torch_dtype": "torch.bfloat16"
+            }
+        },
+        "configuration": { "component_type": "FluxPipeline" },
+        "from_pretrained_arguments": {
+            "model_name": "...",
+            "torch_dtype": "torch.bfloat16"
+        }
+    }
+}
+```
+
+The component is loaded separately with quantization, then the rest of the pipeline loads around it.
+
+## BitsAndBytes (CUDA only)
+
+4-bit and 8-bit quantization via bitsandbytes:
+
+```json
+"quantization_config": {
+    "configuration": { "config_type": "BitsAndBytesConfig" },
+    "arguments": {
+        "load_in_4bit": true,
+        "bnb_4bit_quant_type": "{nf4}",
+        "bnb_4bit_compute_dtype": "torch.bfloat16"
+    }
+}
+```
+
+Note: `"{nf4}"` uses braces to keep the string literal. Without braces, the type system would try to load `nf4` as a Python class.
+
+For 8-bit:
+
+```json
+"arguments": { "load_in_8bit": true }
+```
+
+**Example:** [flux2-dev.json](../workflows/models/flux2-dev.json) (a pre-quantized 4-bit checkpoint)
+
+## TorchAO
+
+Quantization via TorchAO. `quant_type` must be an `AOBaseConfig` class (diffusers no
+longer accepts string shorthands like `"int4wo"`). Name the class as a dotted
+`quant_type` and it is instantiated automatically with no arguments before being passed
+to `TorchAoConfig`:
+
+```json
+"quantization_config": {
+    "configuration": { "config_type": "TorchAoConfig" },
+    "arguments": {
+        "quant_type": "torchao.quantization.Int8WeightOnlyConfig",
+        "modules_to_not_convert": ["proj_in", "proj_out"]
+    }
+}
+```
+
+Common choices: `Int8WeightOnlyConfig` (any CUDA card), `Int4WeightOnlyConfig` (smallest),
+`Float8DynamicActivationFloat8WeightConfig` (fastest, requires compute capability 8.9+ -
+RTX 40-series/Ada or newer).
+
+**Example:** [flux-torchao.json](../workflows/models/flux-torchao.json)
+
+**Pair TorchAO with `torch.compile`.** Int8 weight-only and float8 dynamic-activation
+quant types get their fused-kernel speedups only under compilation - uncompiled they are
+a memory win but often a speed *loss*. Compiled is not a guarantee either: int8 weight-only
+on an RTX 3090 measured over a minute per denoising step for Flux dev, compiled, against
+two seconds for bf16 (see [RECIPES_24GB.md](RECIPES_24GB.md#flux-dev-12b)). Measure on the
+card before recording a TorchAO recipe as fast. Add a `compile` block to the quantized component
+(see [ACCELERATION.md](ACCELERATION.md#torchcompile)):
+
+```json
+"configuration": {
+    "components": {
+        "transformer": {
+            "compile": { "repeated_blocks": true, "fullgraph": true }
+        }
+    }
+}
+```
+
+## GGUF
+
+Load GGUF-format checkpoint files:
+
+```json
+"quantization_config": {
+    "configuration": { "config_type": "GGUFQuantizationConfig" },
+    "arguments": {
+        "compute_dtype": "torch.bfloat16"
+    }
+}
+```
+
+GGUF models load from single files using `from_single_file`:
+
+```json
+"from_pretrained_arguments": {
+    "from_single_file": "https://huggingface.co/city96/FLUX.1-dev-gguf/blob/main/flux1-dev-Q2_K.gguf",
+    "torch_dtype": "torch.bfloat16"
+}
+```
+
+**Example:** [flux-gguf.json](../workflows/models/flux-gguf.json)
+
+## SDNQ (SD.Next Quantization)
+
+SDNQ works two ways: quantize a component on the fly at load time, or load a
+pre-quantized model as a complete pipeline.
+
+### On-the-fly (`sdnq.SDNQConfig`)
+
+Quantizes the component while it loads - the pattern the LTX-2 and MiniMax H3
+examples use for their large transformers and text encoders:
+
+```json
+"quantization_config": {
+    "configuration": { "config_type": "sdnq.SDNQConfig" },
+    "arguments": {
+        "weights_dtype": "{uint4}",
+        "quantization_device": "cuda",
+        "return_device": "cuda",
+        "use_quantized_matmul": true,
+        "dequantize_fp32": false
+    }
+}
+```
+
+- `weights_dtype` — the storage dtype (`uint4`, `int8`, ...; brace-escaped so it stays a string)
+- `quantization_device` / `return_device` — where the quantization pass runs and where the finished component lands; quantizing on `cuda` is much faster than on CPU
+- `use_quantized_matmul` — quantized matmul kernels (CUDA/XPU only)
+
+**Examples:** [text-to-video.json](../workflows/templates/ltx2/text-to-video.json), [video-with-audio.json](../workflows/templates/minimax/video-with-audio.json)
+
+### Pre-quantized models
+
+Pre-quantized SDNQ repos load as complete pipelines. The `sdnq` module must be imported before loading so it can register with diffusers:
+
+```json
+{
+    "pipeline": {
+        "configuration": {
+            "component_type": "ZImagePipeline",
+            "pre_load_modules": ["sdnq"],
+            "sdnq_optimize": ["transformer", "text_encoder"]
+        },
+        "from_pretrained_arguments": {
+            "model_name": "Disty0/Z-Image-Turbo-SDNQ-uint4-svd-r32",
+            "torch_dtype": "torch.bfloat16"
+        }
+    }
+}
+```
+
+- `pre_load_modules` — Imports sdnq before pipeline loading (registers quantization method)
+- `sdnq_optimize` — Applies quantized matmul to listed components (CUDA/XPU only, skipped on MPS/CPU)
+
+**Example:** [z-image-sdnq.json](../workflows/models/z-image-sdnq.json)
+
+## Modular Pipelines
+
+A modular pipeline pulls its component weights itself via `load_components()` rather than
+through `from_pretrained_arguments`, so quantization is keyed by component name under
+`load_components.quantization_config` instead of living on a separate component block:
+
+```json
+"configuration": {
+    "component_type": "MiniMaxMusic3ModularPipeline",
+    "load_components": {
+        "dtype": "torch.bfloat16",
+        "quantization_config": {
+            "transformer": {
+                "configuration": { "config_type": "TorchAoConfig" },
+                "arguments": { "quant_type": "torchao.quantization.Int8WeightOnlyConfig" }
+            },
+            "language_model": {
+                "configuration": { "config_type": "transformers.TorchAoConfig" },
+                "arguments": { "quant_type": "torchao.quantization.Int8WeightOnlyConfig" }
+            }
+        }
+    }
+}
+```
+
+A component the map does not name loads unquantized. Note that a transformers-based
+component (a text encoder, for example) takes the `transformers.TorchAoConfig` class,
+not the diffusers one - the `config_type` still resolves either via the dynamic import
+described below.
+
+## Custom Quantization
+
+Any quantization backend that provides a config class works via the `config_type` field with a dotted module path:
+
+```json
+"quantization_config": {
+    "configuration": { "config_type": "some_package.SomeQuantConfig" },
+    "arguments": { ... }
+}
+```
+
+The class is loaded dynamically via importlib.
+
+## Platform Notes
+
+| Framework | CUDA | MPS | CPU |
+| --------- | ---- | --- | --- |
+| BitsAndBytes | Yes | No | No |
+| TorchAO | Yes | Partial | No |
+| GGUF | Yes | Yes | Yes |
+| SDNQ (load) | Yes | Yes | Yes |
+| SDNQ (optimize) | Yes | No | No |

dw/docs/RECIPES_24GB.md

@@ -0,0 +1,201 @@
+# Fast on 24GB
+
+Recommended configurations per model family for a 24GB consumer GPU (RTX 3090/4090 class). Every knob here is documented individually in [ACCELERATION.md](ACCELERATION.md) and [QUANTIZATION.md](QUANTIZATION.md); this page is about the combinations that work.
+
+The general recipe, in order of impact:
+
+1. **Fit the transformer first.** If it fits in bf16 with room for activations, don't quantize. If it doesn't, prefer float8/int8 quantization (TorchAO, GGUF Q8) over offloading - quantization costs quality once, offloading costs speed every step.
+2. **Compile the transformer** (`"compile": {"repeated_blocks": true}`). 1.3-1.5x, stacks with everything below. The REPL worker keeps compiled pipelines loaded, so the compile cost is paid once per session. Add `fullgraph: true` only when no cache is configured - cache hooks need a graph break.
+3. **Cache** (`"cache": {"type": "first_block"}`). Another 1.5-2x at mild quality cost; raise `threshold` to taste.
+4. **Offload only what doesn't fit.** Text encoders and VAE tolerate `offload: "model"` cheaply - they run once per generation, not once per step. In a modular pipeline the same components take `"residency": "on_demand"`, which frees their VRAM for the denoise loop at the cost of one pair of transfers per call.
+5. **Pin the attention backend** on compiled components (`"attention_backend": "flash_hub"` or `"sage_hub"` - fetched from the Hub, no local build).
+
+## Flux dev (12B)
+
+The bf16 transformer is ~24GB - it does not fit alongside the T5 encoder, and it does
+not fit alongside the VAE either: a resident bf16 transformer runs the denoise and then
+fails at decode. `offload: "model"` is what makes bf16 work on 24GB, and on an RTX 3090
+it is also the fastest configuration measured (1024x1024, 28 steps, pipeline loaded):
+
+| Approach | Config | Measured on RTX 3090 |
+| -------- | ------ | -------------------- |
+| **bf16 + model offload** | [flux-dev.json](../workflows/models/flux-dev.json) | 55s per image (72s cold) |
+| **bf16 + model offload + compile** | [flux-dev-compile.json](../workflows/models/flux-dev-compile.json) - `compile: {repeated_blocks: true}` on the transformer | 52s per image (64s cold) |
+| **int8 TorchAO** | transformer `quant_type: "torchao.quantization.Int8WeightOnlyConfig"` + `compile`, with or without `cache: first_block` | over 60s per *denoising step* - do not use on Ampere |
+| **float8 TorchAO** (RTX 40-series+) | `Float8DynamicActivationFloat8WeightConfig` + `compile` | needs compute capability 8.9+ (Ada); unmeasured |
+| **GGUF Q8** | [flux-gguf.json](../workflows/models/flux-gguf.json) - `from_single_file` Q8_0 transformer + `offload: "model"` | unmeasured; smallest VRAM, best quality retention |
+
+Measured 2026-09-07. A number in this table came from a run on the named card; a row
+without one is a configuration that loads, not a speed claim.
+
+**Examples:** [flux-dev-compile.json](../workflows/models/flux-dev-compile.json), [flux-gguf.json](../workflows/models/flux-gguf.json), [step-caching.json](../workflows/templates/step-caching.json)
+
+## Qwen-Image (20B)
+
+Too large for bf16 on 24GB. Quantize the transformer (TorchAO int8/float8 or GGUF Q4/Q5) and model-offload the rest; add `compile` + `first_block` cache as for Flux. The Qwen2.5-VL text encoder is large - quantize it too, or group-offload it (`"text_encoder.model"` with `leaf_level`).
+
+The catalog no longer ships a Qwen-Image workflow - author one from [text-to-image.json](../workflows/templates/text-to-image.json) with the configuration above.
+
+## Wan 2.2
+
+- **TI2V-5B**: fits in bf16 on 24GB. No quantization needed - just `compile` + `cache` + VAE tiling for longer clips.
+- **T2V/I2V-A14B**: two 14B transformers (`transformer` + `transformer_2`). Quantize both (GGUF Q4/Q5 or TorchAO int8) and use `offload: "model"`; enable `vae.enable_tiling`.
+
+The catalog no longer ships Wan workflows - author one from [minimax/image-to-video.json](../workflows/templates/minimax/image-to-video.json) with the configuration above.
+
+## HunyuanVideo (13B)
+
+Same shape as Flux: quantize the transformer (GGUF Q6/Q8, or TorchAO int8/float8 per the Flux table) + `offload: "model"` + `vae.enable_tiling`. The Llama text encoder benefits from group offload. Use `first_block` cache - video steps are expensive, caching pays off more than on images.
+
+The catalog no longer ships a HunyuanVideo workflow - author one from [ltx2/text-to-video.json](../workflows/templates/ltx2/text-to-video.json) with the configuration above.
+
+## MiniMax-H3
+
+A modular pipeline, so everything is per component in `components` rather than a
+pipeline-level `offload`. The working 24GB configuration at 960x544:
+
+| Component | Config |
+| --------- | ------ |
+| `transformer` / `transformer_ref` | SDNQ int4 (`quantization_device: "cuda"`, `return_device: "cpu"`), `group_offload` `block_level` with `num_blocks_per_group: 1-2` and `use_stream: true` |
+| `text_encoder` | `remove_modules: ["lm_head"]` - the encoder path never calls it |
+| `text_encoder.model` | SDNQ int4, `truncate_layers: {"language_model.layers": 51}`, `group_offload` `leaf_level` |
+| `vae`, `audio_vae` | SDNQ int8, `device: "cuda"`, `residency: "on_demand"` |
+| pipeline | `cache: first_block` (`threshold: 0.1`) on the 20-step ref2va workflows only - measured on the 9-step turbo schedule it never skips (consecutive distilled steps differ too much for the threshold), so the turbo examples omit it rather than hold cache state for nothing |
+
+The VAEs are the piece worth calling out. They hold roughly 3GiB, are used only to
+encode references and decode the result, and group offloading them is worse than useless
+because tiled decode restreams the model once per tile. Every H3 workflow adds
+`"residency": "on_demand"` to both. The reference workflows, which carry the most
+conditioning, go from 23.2GiB peak reserved with 40 allocator retries to 18.9GiB with
+none; the frame-conditioned ones from 22.7GiB with 22 retries to 18.0GiB with none. Both
+for about 1% in wall time.
+Spend the headroom on length: carrying a frame between chained segments adds a reference
+and ~1.9GiB, which is what made the chained variants OOM on their second segment before.
+
+The text encoder pruning exists because H3 conditions on `hidden_states[50]` of its
+64-layer Qwen3-VL: layers 51-63 and the LM head run (and stream) for nothing on every
+encode. Keeping 51 layers is bit-identical - index 50 of the tuple is recorded before
+layer 50 runs; keeping only 50 would hand back the final-norm output, a different
+tensor - and it returns a few GiB of system RAM on a host that needs every one of them
+(a full t2va run peaks around 63GiB RSS on a 64GiB box). Note H3's VAE constructs with
+tiling already enabled, so a pipeline-level `vae.enable_tiling` adds nothing here.
+
+Two levers measured and *rejected* on a 3090 (A/B, t2va 960x544x124f, 2026-08):
+`low_cpu_mem_usage: false` on the transformer's group offload (pin host copies once
+instead of re-pinning per onload) left step time unchanged at ~15.4s - at int4 the
+step is compute-bound and the transfers already hide under it - while the ~27GiB of
+unswappable pinned memory pushed the host into an OOM kill. `use_stream` on the text
+encoder's leaf offload was backed out with it for the same host-memory reason. On a
+faster GPU (or a host with more RAM) both are worth re-testing; the step budget there
+may actually expose the transfer time.
+
+Length costs VRAM but the configuration holds to the model's full range: a single
+345-frame take (14.4s, the `17n+5` maximum) peaks at 23.6GiB reserved at 960x544 -
+inside 24GB with nothing to spare - and denoises in ~13 minutes on a 3090 with the
+9-step turbo schedule (~85-100s a step once warm, against ~15s at 124 frames).
+
+Host RAM is the tighter budget than VRAM on a 64GiB box. Loading H3 peaks around
+59GiB RSS and a running ref2va shot sits at 45-53GiB, so a workflow that ran another
+model first (Z-Image drawing a subject, Music3 writing a song) must free it with
+`release_pipeline` before H3 loads - with it, the multi-model digital-short
+workflows below fit; without it, the load is an OOM kill, not a slowdown.
+
+**Examples:** [reference-to-video.json](../workflows/templates/minimax/reference-to-video.json), [chain-matched-to-audio.json](../workflows/templates/minimax/chain-matched-to-audio.json), [image-to-video.json](../workflows/templates/minimax/image-to-video.json), [dialogue-short.json](../workflows/templates/minimax/dialogue-short.json) (five ref2va shots + two Z-Image portraits in ~35 minutes end to end)
+
+## MiniMax-Music3
+
+Music3 runs at about 22GiB in bfloat16 under the templates' `components_manager`
+auto CPU offload, which keeps only the running component resident; no quantization
+is needed on a 24GB card. The language model is the part worth offloading harder:
+a leaf-level `group_offload` of `language_model` brings it to about 8GiB (the model
+card's low-VRAM recipe). Two things the examples carry: `release_pipeline` on the
+music step in any workflow that loads H3 afterwards, since host RAM is the binding
+constraint (see Multi-model workflows below), and the run's time follows the length
+the model actually sings, not `audio_duration`, which is a ceiling of at most 9000
+frames at 25 frames per second (360 seconds). Output is 44.1 kHz stereo.
+
+**Examples:** [music.json](../workflows/templates/minimax/music.json), [music-video.json](../workflows/templates/minimax/music-video.json)
+
+## LTX-2.5 (22B, video + audio)
+
+A standard pipeline, but placed per component rather than with a pipeline-level
+`offload` - the transformer is the only thing that wants to be resident, and the text
+encoder is nearly as large as it is. The working 24GB configuration at 960x544:
+
+| Component | Config |
+| --------- | ------ |
+| `transformer` | SDNQ `uint4` (`quantization_device: "cuda"`, `return_device: "cuda"`, `use_quantized_matmul: true`), resident |
+| `text_encoder` (Gemma 4, 23GB) | SDNQ `int8`, `return_device: "cpu"`, `group_offload` `leaf_level` with `use_stream: true` |
+| `connectors` (12GB) | `group_offload` `leaf_level` with `use_stream: true` |
+| `vae`, `audio_vae`, `vocoder`, `duration_head` | `device: "cuda"` - small, and used once per generation |
+| pipeline | `vae.enable_tiling` for anything above the base resolution |
+
+Two things about the checkpoint are worth knowing before tuning anything:
+
+- **`transformer` is the distilled model.** It runs a fixed 8-step schedule at
+  `guidance_scale: 1.0`, with STG and modality guidance off, and the `sigmas` every
+  example passes are its trained schedule - not a knob. They are referenced from
+  diffusers (`constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES`) rather
+  than copied, so the schedule stays whatever the library says it is. `num_inference_steps`,
+  `guidance_scale`, `stg_scale` and the rest only mean anything against
+  `subfolder: "transformer_full"`, the dev model, which is not a 24GB configuration:
+  it is the same ~38GB in bf16, and the guidance those knobs turn on costs three
+  transformer passes per step against CFG-doubled batches. Nothing here ships it.
+- **The checkpoint ships a diffusion decoder that `LTX2Pipeline` ignores**, and on
+  24GB you are not missing much. It is listed in `model_index.json` but is not a
+  constructor argument, so diffusers logs "not expected ... will be ignored" and
+  decodes with the convolutional VAE. Reaching it means `LTX2VideoDiffusionDecodePipeline`
+  on a step run with `output_type: "{latent}"`, and two things get in the way. Its
+  neighborhood attention has two processors, and the one you get by default is the
+  portable FlexAttention fallback: it densifies a `seq_len x seq_len` block mask and then
+  runs uncompiled `flex_attention`, which falls to the eager reference path. Both
+  allocations are quadratic in the output grid, and neither is reduced by tiling (stages
+  1-3 always run on the full volume) or by shrinking the clip (the stage-4 grid is near
+  output resolution either way). Measured on an otherwise empty 3090 (#153): 10.05GiB
+  inside stages 1-3 at 960x544x121, 69.77GiB for one stage-4 attention at 512x288x25
+  (17.44GiB just to densify that stage's mask, whichever it reaches first), and ~25.5GiB
+  at 224x224x25, which is the smallest canvas its 7x7 kernel accepts at all. Nothing
+  fits - not base resolution, not the smallest clip the decoder will take. The path that does is NATTEN's `na3d` kernel, named per component as
+  `"attn_processor_type": "diffusers.models.autoencoders.ltx2_diffusion_decoder.LTX2VideoVaeNeighborhoodNattenProcessor"`,
+  which builds no mask at all - but it is fetched from the Hub by the `kernels` package
+  and needs a `shi-labs/natten` build matching the installed torch, which as of
+  torch 2.14 does not exist.
+  And a step that returns latents returns *audio* latents too, which nothing outside a
+  pipeline call can vocode - the two-stage template below feeds them back into one,
+  which is the only way they become sound. Nothing here ships the diffusion decoder.
+
+Spend headroom on the two-stage flow rather than on base resolution: render at 768x448
+on the eight distilled sigmas, double the video latents with the latent upsampler, then
+renoise them and run the three stage-two sigmas at 1536x896 through the same pipeline.
+That refine pass is what puts the detail back - the upsampler alone gives a soft 2x -
+and it is the flow the model card, Lightricks' pipeline notes and the diffusers docs all
+describe. The base pass keeps its pipeline loaded so the refine pass is served from the
+cache; the refine pass releases it. Since 2026-08 Lightricks route production quality
+through their DFR pipeline instead, which diffusers ships and nothing here uses yet.
+Measured on an RTX 3090 the refined clip is sharper than the 2x upsample alone at the
+same seed: fur, branches and snow texture resolve where the upsample-only frame is a
+soft blur. About eight warm minutes, three and a half of them writing the full-size clip.
+
+**Examples:** [text-to-video.json](../workflows/templates/ltx2/text-to-video.json) (t2v),
+[two-stage.json](../workflows/templates/ltx2/two-stage.json) (base -> latent upsample -> refine),
+[keyframes.json](../workflows/templates/ltx2/keyframes.json) (first and
+last frame), [extend-clip.json](../workflows/templates/ltx2/extend-clip.json) (continue a clip),
+[generative-upscale.json](../workflows/templates/ltx2/generative-upscale.json) (generative 2x upscale via IC-LoRA),
+[enhance-prompt.json](../workflows/templates/ltx2/enhance-prompt.json) (native prompt
+enhancer and duration head)
+
+## SDXL (2.6B UNet)
+
+Fits several times over in 24GB. Skip quantization and offloading entirely; `compile` the UNet if you generate many images per session. Use `num_images_per_prompt` batching with `vae.enable_slicing`.
+
+**Example:** [base-and-refiner.json](../workflows/templates/base-and-refiner.json)
+
+## Multi-model workflows
+
+When a workflow chains two large models (generate → upscale, generate → interpolate), release the first pipeline instead of offloading everything:
+
+```json
+{ "name": "generate", "release_pipeline": true, "pipeline": { ... } }
+```
+
+See [WORKFLOW_GUIDE.md](WORKFLOW_GUIDE.md#releasing-a-pipeline-mid-workflow).

dw/docs/RELEASING.md

@@ -0,0 +1,195 @@
+# Releasing
+
+## Unreleased
+
+This project has no standing release-notes file - GitHub auto-generates
+notes from commits at tag time (see below). This section is a scratch pad
+for items a branch's author wants the next release note to name; clear it
+when a release ships.
+
+### 0.4.0
+
+The auto-generated notes for this range are a single merge line, since the
+work landed on `develop` without PRs. Paste this section into the GitHub
+release body once the tag has published (`gh release edit v0.4.0
+--notes-file ...`).
+
+**Breaking and behaviour changes**
+
+- `download_output` over a `dw.serve --mcp` endpoint refuses a call with no
+  `destination`. It used to write into the server's own directory (#353).
+- Untrusted workflows are refused in more cases (#409-#413):
+  - a `*_type` that doesn't resolve to a class, or that isn't a kind a
+    workflow constructs: a diffusers or transformers model, pipeline,
+    scheduler, tokenizer or processor, a quantization config, an auto
+    factory, a diffusers reference/condition type or an attention processor.
+    A plain `torch` class such as `torch.nn.Linear` is now refused;
+  - `constant:` walks through `_` names or out of the allowed packages;
+  - URLs with backslashes;
+  - `text/html` and `text/xml` result types;
+  - media hosts that aren't globally routable, including 100.64/10 (CGNAT,
+    and so Tailscale);
+  - more than 5 redirects;
+  - images over 50M pixels.
+
+  Listings and export zips drop symlinks that escape their root.
+  `--trust-workflows` lifts all of these.
+- `run_workflow` validates the caller's `arguments` when it queues the job
+  (#414/#415). `validate_workflow(arguments={})` checks a run with no values
+  supplied, not just the document (#364).
+- A fractional value for an int variable is refused (#338), and so is a
+  still image passed as a video argument (#347).
+- `templates/minimax/music` normalizes to -3 dBFS instead of -1, so its output
+  is quieter (#362).
+- Every response carries `X-Content-Type-Options: nosniff` and
+  `X-Frame-Options: DENY`. Active document types under `/outputs` and
+  `/inputs` are served with `Content-Security-Policy: sandbox`.
+- A validate-time probe reads only a literal media path that the run itself
+  would be allowed to read.
+- A dict or list passed to a string-typed variable is refused (#433).
+  `templates/ltx2/keyframes` takes `first_image`/`last_image` as plain
+  strings, not `{"location": ...}` (#431/#433).
+- `loop_frames` returns float32 frames in [0, 1] instead of uint8, the shape
+  `LTX2ReferenceCondition` needs; a keyframe condition still wants
+  `frames_as_array`. `ltx2/reference-sheet`'s default asset is now
+  `asset:reference_sheet.jpg` (#444).
+- `validate_workflow` refuses a `components` name the pipeline doesn't
+  register; `duration_head` is gone from the in-context LTX-2 templates
+  (#442).
+- A `{"media_type": "image"}` reference on a video argument loads as a
+  one-frame still (#443).
+- `pair_audio fit: "video"` always fits, and warns on any nonzero gap
+  (#428/#429). `concat_videos` and `dissolve_videos` pad a short joined
+  track to the frame grid, warning (`joined_audio_padded_to_frames`) only
+  when the pad is a frame or more; a residual the AAC mux trims off is
+  logged, or warned as `joined_audio_short_after_mux` from a frame up.
+  `media.shots` is measured against the file as written (#426/#435/#454).
+  Neither warns about resampling inputs that agree to a pinned
+  `sample_rate` (#453).
+- New warnings: `match_levels_near_silent` (#434), and `shot_span_overrun`
+  from the probes plus a validate-time check (#425).
+- Error text changed: `delete_workspace` (#437/#438), the sub-workflow path
+  refusal names the places it looked (#422), and `/outputs/asset:...` misses
+  name the asset without server paths.
+
+**New**
+
+- The `assess_output` tool and `GET /api/gallery/{name}/assess`, plus the
+  probe tasks `analyze_shots`, `analyze_seams` and `analyze_sync_drift`
+  (#387/#388).
+- A joined video records its shot boundaries (`media.shots`).
+  `get_output_frames(seams=true)` uses them, so it no longer needs
+  `boundaries` (#385).
+- Run versions (`v<N>`):
+  - `list_gallery` returns `run_id`/`version` and filters by `folder` and
+    `version`;
+  - `output:<wf>/v<N>/<file>` references;
+  - `wait_for_job` returns `run_version`;
+  - export zips download as `<wf>-vN-<job>.zip`.
+- `list_gallery(media=true)` adds durations, and `output:` names work in
+  gallery reads (#356).
+- `DW_PUBLIC_URL` adds absolute URLs to gallery and export responses.
+  `export_job` also returns `auth_required` and `open_url` (#353).
+- A `grade` task for images and video: exposure, contrast, saturation and
+  temperature/tint (#349).
+- The `templates/minimax/shots-batch` H3 template (#352).
+- Every generative template takes a `seed` argument (#351).
+- `normalize_audio(target_lufs)`, and `integrated_lufs` plus true peak in
+  media metadata (#361).
+- `gain_audio` with no region gains the whole track (#395).
+- `world_fade_out_ms` on `assemble-and-score` (#339).
+- Download progress shows in `phase_detail` (#343). `phase_stall` events
+  now read as informational (#357).
+- `workflow`, `inline_workflow` and `prompt` also accept a JSON string. A
+  mistyped workflow name gets suggestions from the catalog (#397).
+- Host caches are released when each job ends (#368), and the skills point
+  at `clear_memory`.
+- `get_job_events(kinds=...)` and `?kinds=` on the event-log route; a kind
+  matches an event's `event` or its `kind`, so `["phase_stall"]` selects
+  one warning type (#436).
+- `get_memory` reports the step cache's `entries` and `retained_bytes`
+  (#418).
+- `get_output_image` and `/outputs` resolve `asset:` references (#445), and
+  `get_output_frames(seams=true)` works on linked assets (#430).
+- Compact `assess_output` lists each finding once (#427). Shots are named by
+  their source when joined inputs already carry shots (#432).
+- A task-only workflow's run history counts, so its estimate can quote
+  `basis: observed` (#439). The Music 3 hint no longer shows on video
+  (#441).
+
+**Fixes**
+
+- The step cache's retained-byte count no longer only grows (#418).
+- `templates/ltx2/keyframes` (#431), `restore-decompression` (#442) and
+  `reference-sheet` (#444) run with their own defaults again.
+- Joined audio and shot maps stay on the frame grid through repeated joins
+  (#423, #426, #428, #435).
+
+Releases are cut by pushing a `v<semver>` tag. CI does the rest.
+
+Before merging `develop` into `master`, run `scripts/preflight.sh` and get it
+passing. It covers more than CI: ruff over the whole repo rather than
+`dw dw_mcp tests`, and the UI's Playwright e2e tests, which CI doesn't run.
+
+```bash
+scripts/release.sh 0.38.0
+scripts/release.sh 0.38.0-alpha.1 "UI front end"   # optional tag message
+```
+
+The script bumps `pyproject.toml` (the single source of the version —
+`dw.__version__` reads it at runtime) and sets the same version in
+`plugins/dw/.claude-plugin/plugin.json`, so an installed plugin names the
+engine it was written against; it commits just those two files, pushes
+master, tags the bump commit `v0.38.0`, and pushes the tag. It refuses
+a malformed version, a branch other than master, an existing tag, or a
+dirty index (unstaged changes elsewhere are fine — the release commit
+is path-limited to those two files).
+
+By hand, the equivalent is:
+
+```bash
+# 1. Bump the version in pyproject.toml:
+#    version = "0.38.0"
+# 2. Set the same version in plugins/dw/.claude-plugin/plugin.json
+git commit -m "release 0.38.0" -- pyproject.toml plugins/dw/.claude-plugin/plugin.json
+
+# 3. Tag the bump commit and push
+git tag -a v0.38.0 -m "release 0.38.0"
+git push origin master v0.38.0
+```
+
+The tag must point at a commit whose pyproject already declares the
+same version — the release job checks and refuses a mismatch.
+
+The tag triggers the full CI chain: backend tests, UI lint/type-check/
+unit tests, then the wheel build (SPA compiled into the package via
+`scripts/build_dist.sh`). Only if all of that passes does the `release`
+job run — it verifies the tag matches the pyproject version, then
+creates a GitHub release named after the tag with auto-generated notes
+and the wheel + sdist attached.
+
+Note on pre-release numbering: Python packaging normalizes semver-style
+pre-releases, so a `0.38.0-alpha.1` version builds a wheel named
+`0.38.0a1`. The tag, pyproject, and release stay in the semver form;
+only the wheel filename and pip metadata show the normalized one.
+
+A pre-release tag like `v0.38.0-rc1` is marked as a pre-release on
+GitHub. Tags that aren't `v` + semver (or that don't match the declared
+versions) fail the release job before anything is published.
+
+After the GitHub release, the `pypi` job publishes the same artifacts to
+PyPI via [trusted publishing](https://docs.pypi.org/trusted-publishers/)
+(OIDC — no token stored anywhere). One-time setup on pypi.org under
+*Publishing*: add a trusted publisher for project `diffusers-workflow`
+with owner `dkackman`, repository `diffusers-workflow`, workflow
+`ci.yml`, environment `pypi` (use "add a pending publisher" before the
+first release, since the project won't exist yet). Pre-release versions
+are hidden from plain `pip install`; they need `pip install --pre`.
+
+Note: released `diffusers` from PyPI may lag the newest model pipelines
+this project targets — a PyPI install can need
+`pip install git+https://github.com/huggingface/diffusers` on top.
+
+To rebuild artifacts without releasing, run the CI workflow manually
+(`workflow_dispatch`) — the wheel job uploads `dist/*` as a workflow
+artifact.