From 0cbd0de14c70b58c1af028fc09cd0d5d3d2efa5c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Tue, 27 Oct 2026 20:18:07 -0500
Subject: [PATCH 001/125] chore: open 0.17.0-alpha.1 on develop

---
 plugins/dw/.claude-plugin/plugin.json | 2 +-
 pyproject.toml                        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/plugins/dw/.claude-plugin/plugin.json b/plugins/dw/.claude-plugin/plugin.json
index c1a6e533..b222535f 100644
--- a/plugins/dw/.claude-plugin/plugin.json
+++ b/plugins/dw/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
     "name": "dw",
     "description": "Compose MiniMax H3 video, MiniMax Music 3, LTX-2.5 and Kandinsky 6.0 workflows over a dw MCP server, and cut a multi-episode series from them: which template fits which shape, the hard rules, cost, and how to judge the output. Prompt format comes from the vendors' own guides.",
-    "version": "0.16.0",
+    "version": "0.17.0-alpha.1",
     "author": {
         "name": "Don Kackman"
     },
diff --git a/pyproject.toml b/pyproject.toml
index 868017bd..bc55cba5 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -8,7 +8,7 @@ name = "diffusers-workflow"
 # runtime (static in TOML because importing dw at build time would drag
 # torch into the build environment). Release tags must match it - see
 # docs/RELEASING.md
-version = "0.16.0"
+version = "0.17.0-alpha.1"
 description = "Declarative workflow engine and web UI for Hugging Face Diffusers"
 readme = "README.md"
 requires-python = ">=3.10"

From 3bf128b02d06349c9b8b90a523c6cfdba3549e1d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 18:59:05 -0500
Subject: [PATCH 002/125] docs: add an attributions page, linked from the
 README

Credits the code included from other projects (RIFE, the H3 latent
upscaler, the RF-Inversion community pipeline, sd_embed) and the
projects whose ideas dw reimplemented: comfyui-vrgamedevgirl,
Kablex/ComfyUI-Ref2VA-VSA (and FastVideo's VSA-H3 work),
mo-akkakk's TemporalWindow-SpatialTiles, and Kinoloom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md            |  1 +
 docs/ATTRIBUTIONS.md | 80 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 81 insertions(+)
 create mode 100644 docs/ATTRIBUTIONS.md

diff --git a/README.md b/README.md
index e8d01692..86f77da2 100644
--- a/README.md
+++ b/README.md
@@ -245,3 +245,4 @@ frame interpolation and more.
 - [Testing](docs/TESTING.md) — Running the test suite
 - [Releasing](docs/RELEASING.md) — Cutting a release from a version tag
 - [Agent Loop](docs/AGENT_LOOP.md) — What the automated implementer/tester ticket labels mean, for anyone joining an Issue
+- [Attributions](docs/ATTRIBUTIONS.md) — Code included from other projects, and the projects whose ideas dw reimplemented
diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
new file mode 100644
index 00000000..1adb6efc
--- /dev/null
+++ b/docs/ATTRIBUTIONS.md
@@ -0,0 +1,80 @@
+# Attributions
+
+diffusers-workflow is Apache-2.0. This page credits the work it builds on that
+a dependency list does not show: code that was copied in, and other projects
+whose ideas were reimplemented here. Python dependencies are in
+[requirements.txt](../requirements.txt) and [pyproject.toml](../pyproject.toml).
+Model and LoRA weights keep their own licences, and each catalog entry
+([workflows/models/](../workflows/models/), [loras/](../loras/)) names the
+repository it downloads from.
+
+## Code included in this repository
+
+Each file keeps its upstream licence notice in its header.
+
+| File | Source | Licence |
+|---|---|---|
+| [dw/tasks/rife_model.py](../dw/tasks/rife_model.py) | The RIFE interpolation network from [hzwer/Practical-RIFE](https://github.com/hzwer/Practical-RIFE) | MIT, Copyright (c) Megvii Inc. |
+| [dw/tasks/h3_latent_upscaler_model.py](../dw/tasks/h3_latent_upscaler_model.py) | The MiniMax H3 3D-convolution latent upscaler from [LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler](https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler) | MIT, Copyright (c) LBH-123-AI |
+| [dw/community_pipelines/pipeline_flux_rf_inversion.py](../dw/community_pipelines/pipeline_flux_rf_inversion.py) | The diffusers community RF-Inversion pipeline, after [RF Inversion](https://rf-inversion.github.io/) by Litu Rout, Yujia Chen, Nataniel Ruiz, Constantine Caramanis, Sanjay Shakkottai and Wen-Sheng Chu | Apache-2.0, Copyright 2024 Black Forest Labs and The HuggingFace Team |
+| [dw/prompt_weighting.py](../dw/prompt_weighting.py) | Based on [sd_embed](https://github.com/xhinker/sd_embed) by Andrew Zhu | Apache-2.0 |
+
+## Ideas reimplemented here
+
+These projects showed an approach that dw rebuilt in its own code for
+diffusers. No code, prompt text or data was copied from them; where a licence
+does not allow reuse, only the concept was taken. The issue numbers link to the
+design discussion, which names the source files consulted.
+
+### [vrgamegirl19/comfyui-vrgamedevgirl](https://github.com/vrgamegirl19/comfyui-vrgamedevgirl)
+
+A ComfyUI node pack and set of workflows for MiniMax H3 and LTX-2 film making,
+assessed in October 2026. It is source-available under a licence that does not
+allow reuse here, so only concepts were taken. It inspired:
+
+- holding the reference audio during H3 denoising, and a refine pass after the
+  latent upscale ([#598](https://github.com/dkackman/diffusers-workflow/issues/598))
+- tracked, distance-gated face repair with LTX on face crops ([#599](https://github.com/dkackman/diffusers-workflow/issues/599))
+- the music-video timing stack: beat analysis, a lyric- and beat-aware cut
+  planner, pad-then-trim shots ([#600](https://github.com/dkackman/diffusers-workflow/issues/600))
+- overlapping windows for long video sources, joined with a cosine blend
+  (`window_video`, `join_windows`; [#601](https://github.com/dkackman/diffusers-workflow/issues/601))
+- the exact size and frame-count round trip for video-to-video templates
+  (`fit_to_model`, `restore_to_source`; [#602](https://github.com/dkackman/diffusers-workflow/issues/602))
+- the finishing tasks: LUT apply and make, film grain, sharpen, tonal controls
+  in `grade` ([#603](https://github.com/dkackman/diffusers-workflow/issues/603))
+- stem separation as its own task (`separate_stems`; [#604](https://github.com/dkackman/diffusers-workflow/issues/604))
+- strength-selectable same-size LTX refine and per-segment strength decay in
+  chains ([#606](https://github.com/dkackman/diffusers-workflow/issues/606))
+- laying out a reference sheet from individual images (`ingredients_grid`; [#607](https://github.com/dkackman/diffusers-workflow/issues/607))
+- the H3 dialogue-budget warnings ([#608](https://github.com/dkackman/diffusers-workflow/issues/608))
+- checking a take's transcript against the expected lines (`check_script`; [#609](https://github.com/dkackman/diffusers-workflow/issues/609))
+- the script-to-video shot-list contract and voice bible ([#610](https://github.com/dkackman/diffusers-workflow/issues/610))
+- H3 chunk continuation in latent space ([#611](https://github.com/dkackman/diffusers-workflow/issues/611))
+- trying the Alissonerdx H3 LoRAs, which its workflows use ([#612](https://github.com/dkackman/diffusers-workflow/issues/612))
+
+### [Kablex/ComfyUI-Ref2VA-VSA](https://github.com/Kablex/ComfyUI-Ref2VA-VSA)
+
+Apache-2.0. Showed that MiniMax H3's Ref2VA attention could run block-sparse,
+building on the [FastVideo](https://github.com/hao-ai-lab/FastVideo) team's
+VSA-H3 sparse-attention work. dw's `sparse` attention backend
+([dw/sparse_attention.py](../dw/sparse_attention.py),
+[#931](https://github.com/dkackman/diffusers-workflow/issues/931)) runs on
+[comfy-kitchen](https://pypi.org/project/comfy-kitchen/)'s Sol-Attn kernel, a
+dependency.
+
+### [mo-akkakk/ComfyUI-MiniMaxH3-TemporalWindow-SpatialTiles](https://github.com/mo-akkakk/ComfyUI-MiniMaxH3-TemporalWindow-SpatialTiles)
+
+MIT. The tiled low-sigma refine after an H3 upscale (`refine_tiles`,
+[#1043](https://github.com/dkackman/diffusers-workflow/issues/1043)), and the
+approach of the test that checks a one-segment H3 chain is bit-identical to a
+native run on a tiny random-weight model on CPU
+([#1046](https://github.com/dkackman/diffusers-workflow/issues/1046)).
+
+### [harlixay7/Kinoloom](https://github.com/harlixay7/Kinoloom)
+
+MIT. Its seamless-chain research gave `analyze_seams` its saturation,
+lightness, contrast and detail measures
+([#1031](https://github.com/dkackman/diffusers-workflow/issues/1031)), and the
+`script-to-video` skill its guidance on re-rolling a chained segment whose seam
+fails ([#1034](https://github.com/dkackman/diffusers-workflow/issues/1034)).

From e745bca9cc12fc070c8b72aff63b2e231e32c6b7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 21:33:05 -0500
Subject: [PATCH 003/125] feat(plugin): #1070 - minimax-h3 style-skills pointer
 (references/style.md)

Lists MiniMax's eight H3 style packs by name with a per-pack install
line, adds the medium line attributed to the packs and marked unprobed,
and points SKILL.md and the plugin README at it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/README.md                          |  3 +-
 plugins/dw/skills/minimax-h3/SKILL.md         |  6 +--
 .../dw/skills/minimax-h3/references/style.md  | 43 +++++++++++++++++++
 3 files changed, 48 insertions(+), 4 deletions(-)
 create mode 100644 plugins/dw/skills/minimax-h3/references/style.md

diff --git a/plugins/dw/README.md b/plugins/dw/README.md
index 8b0b4685..b6a4bb24 100644
--- a/plugins/dw/README.md
+++ b/plugins/dw/README.md
@@ -35,7 +35,8 @@ npx skills add MiniMax-AI/MiniMax-Music3 --skill music-caption-rewriter
 
 Name the skill: the H3 repo also ships eight style packs
 (`brand-promo-video-generator` and the like) that `--skill '*'` would install
-alongside it.
+alongside it. When a request wants one of those looks, install that pack the
+same way, by name; the `minimax-h3` skill's `references/style.md` lists them.
 
 Each skill quotes catalog names and numeric rules that `tests/test_plugin_skills.py`
 holds to the catalog and to the diffusers module that enforces them. A
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 8a9db008..26a8623e 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -150,6 +150,7 @@ the rules are MiniMax's:
 Either way: write the whole script before the first shot. Repeat a speaker's voice description verbatim across shots.
 Several characters: one cropped reference each, never a group picture, which imposes its framing on every shot (`references/per-character.md`).
 Before writing lines, read `references/dialogue.md`: how long a line fits a clip, and what not to name.
+A wanted look (clay, paper): `references/style.md`.
 
 ## Run and judge
 
@@ -191,6 +192,5 @@ Before writing lines, read `references/dialogue.md`: how long a line fits a clip
 
 ## Sources
 
-MiniMax-H3 model card and prompt guides, `h3-prompt-writing`, diffusers'
-MiniMax-H3 modular pipeline, `lightx2v/Minimax-h3-Turbo` LoRA notes; read
-2026-09-07; audit `docs/proposals/audits/2026-09-07-minimax-h3-audit.md`.
+Model card, prompt guides, `h3-prompt-writing`, diffusers' pipeline,
+`lightx2v/Minimax-h3-Turbo` notes; read 2026-09-07; audit `docs/proposals/audits/2026-09-07-minimax-h3-audit.md`.
diff --git a/plugins/dw/skills/minimax-h3/references/style.md b/plugins/dw/skills/minimax-h3/references/style.md
new file mode 100644
index 00000000..5cd187c9
--- /dev/null
+++ b/plugins/dw/skills/minimax-h3/references/style.md
@@ -0,0 +1,43 @@
+# MiniMax H3: a request that wants a look
+
+Part of the `minimax-h3` skill; its *Prompts* section says when to read this.
+
+MiniMax's H3 repo ships eight style packs next to `h3-prompt-writing`. Each
+plans a whole piece in one look - style rules, shots, and the prompts for
+them. When a request asks for one of these looks, install that pack by name
+and let it write the prompts; the templates and hard rules in `SKILL.md`
+still pick what runs.
+
+```bash
+npx skills add MiniMax-AI/MiniMax-H3 --skill <name>
+```
+
+Name the pack. `--skill '*'` installs all eight plus `h3-prompt-writing`.
+
+| Pack | Suits a request for |
+|---|---|
+| papercraft-stop-motion-explainer | an explainer built from folded, cut paper, animated frame by frame |
+| paper-collage-explainer-generator | an editorial explainer of torn-paper and halftone cut-outs |
+| 3d-animation-short-generator | a 3D animated short |
+| handdrawn-live-video-generator | hand-drawn animation over a live-action scene |
+| minimalist-product-ad-generator | a clean, minimal product ad |
+| music-video-subtitle-generator | a music video with on-screen lyrics or subtitles |
+| brand-promo-video-generator | a brand promo |
+| co-op-game-intro-generator | an intro for a co-op game |
+
+The names are MiniMax's and nothing here checks them; if one fails to
+install, the pack was renamed, so look in the repo's `skills/` folder.
+
+## Without a pack: name the medium, then what it looks like
+
+A medium named alone tends to render as its smooth CG version. Name it, then
+the physical traits that make it that medium: for claymation, fingerprints,
+tool marks and stepped, frame-by-frame motion; for paper, fibres, folds and
+cut edges; for crayon, wobbling lines and uneven fill.
+
+This is MiniMax's practice, not ours: the papercraft, paper-collage and
+hand-drawn packs each prompt this way (read 2026-10-30). It is **unprobed on
+dw** - no job here has compared a bare medium with a described one.
+
+It doesn't override `SKILL.md`'s guide rule: a guide clip holds its look as
+well as its motion, and no style prompt restyles it.

From 7495862f8eca746e89e74e6cb1d2d7c4cd9bafca Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 22:37:08 -0500
Subject: [PATCH 004/125] feat(audit): #1071 - H3 AISkills probes 2, 3 and 5 on
 lem (all refuted)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-10-h3-aiskills-probes.md      | 184 ++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 docs/proposals/audits/2026-10-h3-aiskills-probes.md

diff --git a/docs/proposals/audits/2026-10-h3-aiskills-probes.md b/docs/proposals/audits/2026-10-h3-aiskills-probes.md
new file mode 100644
index 00000000..190ce5bf
--- /dev/null
+++ b/docs/proposals/audits/2026-10-h3-aiskills-probes.md
@@ -0,0 +1,184 @@
+# MiniMax-H3 AISkills claims: record-only probes (#1059 stage 2, #1071)
+
+Probe date: 2026-10-30 (lem's clock reads 2026-10-31 in the run ids). Server `lem`, develop @ 7735379d,
+dw 0.17.0-alpha.1, diffusers 0.42.0.dev0, torch 2.14.1+cu130, two RTX 3090s.
+Agent: claude-opus-5-5 (anthropic). Workspace `qa-h3-aiskills-probes`.
+No engine, skill or template file was changed. This document only records results.
+
+The claims come from einhorn13/AISkills, as listed on #1059. Plan v1 there keeps three of them
+(2, 3 and 5). Probes 1 and 4 are deferred, and 6 and 7 are dropped. Neither the plan nor this
+document copies anything from that repository.
+
+## Configuration
+
+Every probe ran at 960x544 and 124 frames, int4 sdnq (VAE int8), 24 fps.
+
+| Probe | Workflow | Pipeline | LoRA (`lightx2v/Minimax-h3-Turbo`) | Steps | Shift (video/audio) |
+| --- | --- | --- | --- | --- | --- |
+| P2 | `templates/minimax/voice-timbre-reference`, as shipped | Ref2VA, one audio reference | `minimax_h3_ref2v_turbo_8step_v1.0_768p_bf16.safetensors`, pinned by the template (plan: runs as shipped, despite the `<d>` line) | 9 | 12 / 3 |
+| P3 | `p3-style-reference`, hand-authored and saved in the workspace | Ref2VA, one image reference | `minimax_h3_ref2v_turbo_8step_v1.0_768p_bf16.safetensors` | 9 | 12 / 3 |
+| P5 | `templates/minimax/video-with-audio`, template defaults | T2VA | `minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors` (the template's default) | 5 | 6 / 3 |
+
+P3's workflow copies the `reference-to-video` step's loading (sparse attention, tau 0.5, top-k
+0.15, block-level group offload) and drops the audio reference. It has one
+`MiniMaxH3ImageReference` from the variable `subject`.
+
+Each arm ran on seeds 1001 and 2002. A claim is **held** only when both seeds of the broken arm
+show the effect and neither seed of the followed arm does. It is **refuted** when the broken arm
+doesn't show the effect, and **not settled** when the seeds disagree. A job that failed would be
+**not run**. None did: all 12 probe jobs and 4 check-script jobs succeeded.
+
+## Verdicts
+
+| # | Claim | Verdict | Jobs | Observation |
+| --- | --- | --- | --- | --- |
+| P2 | A timbre-only audio reference replays its source words. | **refuted** | clip A: 679d1647474e (s1001), 23951087cc0e (s2002). Clip B: 1ae32a340b81 (s1001), 8b5321bf4db3 (s2002). check-script: 558af206ad68, e247ffc86d1b, 58d17f8beea2, 94115820bfa5 | On all four, Whisper heard only the new line: "Bring the copper kettle inside before the storm reaches the harbor." `findings` was empty (no `line_mismatch`), the similarity was 0.9091 (only the harbour/harbor spelling differed), and nothing landed in `unmatched`. No source word from either clip was transcribed. See *Probe 2*. |
+| P3 | A style image pulls in its person and composition. | **refuted**, but the reference also carried no style, so the probe says little about style references in general | arm a (old man at window): f90a041af26a (s1001), 1b751acfc1d4 (s2002). Arm b (still life): b1469a34cea9 (s1001), db3b5b47095b (s2002) | On no seed of either arm did the old man, his cap or beard, a seated pose, the window, its curtains or the reference's framing appear. Frames 0–5 show the beach shot, so the reference didn't leak into frame 0. All four clips are photographic, not watercolour. Same-seed clips of the two arms are near-identical, so the reference had no visible effect under this phrasing. See *Probe 3*. |
+| P5 | "Screen right" plus the anatomical side holds handedness; the anatomical side alone misses. | **refuted** | arm a ("in her left hand"): a6c07856c701 (s1001), cb19f9007653 (s2002). Arm b ("in her left hand, on screen right"): e96170407504 (s1001), 7ce8ed6f90ab (s2002) | All four clips are right on both counts. She lifts the mug with her left hand, which shows on screen right because she faces the camera, and holds it at chest height there to the end. Her right hand stays flat on the counter, on screen left. See *Probe 5*. |
+
+## Probe 2: timbre-only audio reference
+
+The template's `voice` step makes the reference clip with Bark (`v2/en_speaker_6`) from
+`voice_line`. Its Ref2VA step is prompted to take only the timbre of `<Audio 1>`. The prompt was
+the template's default, with only the `<d>` line replaced:
+
+```
+<d>[English] Bring the copper kettle inside before the storm reaches the harbour.</d>
+```
+
+It shares no content word with either source:
+
+| Clip | `voice_line` (the source speech) |
+| --- | --- |
+| A | the template's default, "The way ahead is longer still, and we are going anyway." |
+| B | "Seven green apples rolled under the kitchen table." |
+
+`templates/check-script` ran on each output, with `lines` set to the new line. Every run used
+`openai/whisper-large-v3-turbo` with a `whole_cut` pass.
+
+| Job | Clip, seed | check-script | Transcript | Line span | Findings |
+| --- | --- | --- | --- | --- | --- |
+| 679d1647474e | A, 1001 | 558af206ad68 | "bring the copper kettle inside before the storm reaches the harbor." | 0.66–4.82 s | none |
+| 23951087cc0e | A, 2002 | e247ffc86d1b | "Bring the copper kettle inside before the storm reaches the harbor." | 0.78–4.68 s | none |
+| 1ae32a340b81 | B, 1001 | 58d17f8beea2 | "Bring the copper kettle inside before the storm reaches the harbor." | 0.12–4.92 s | none |
+| 8b5321bf4db3 | B, 2002 | 94115820bfa5 | "Bring the copper kettle inside before the storm reaches the harbor." | 0.64–4.82 s | none |
+
+The rules applied were `line_mismatch`, `transcript_loop`, `tag_spoken`, `line_clipped_at_end`
+and `speech_not_transcribed`. None fired. The transcript holds no word from either source line
+("way", "ahead", "longer", "going", "seven", "apples", "kitchen", "table"). The effect, source
+words spoken or the new line not spoken, appears on neither clip and neither seed.
+
+Not measured: whether the timbre itself matched the reference. That needs a listener or a speaker
+embedding, and the claim under test was about words.
+
+## Probe 3: a style image and its person
+
+The reference images were made once each with `templates/text-to-image` at 512x512, as
+watercolours:
+
+| Asset | Job | Content |
+| --- | --- | --- |
+| `asset:p3-style-person.jpg` | a120cca0fdbc | An old bearded man in a flat cap, seated in profile at a curtained window, with a misty landscape outside. Brown and grey wash on visible paper. |
+| `asset:p3-style-stilllife.jpg` | e941f3bb3d9c | Three pears, a reddish vase and a sheet of paper on a table, against a blue wash. No person. |
+
+A first person image (5f7d24bb04d7) lost the window and was not used.
+
+The prompt is the same for both arms; only `subject` changes. Here it is exactly:
+
+```
+subject_definitions:
+<Picture 1> is a style reference only. <Picture 1> sets only the medium and palette. Its subject and framing are not used.
+<Subject 1> is a young woman cyclist in a yellow jersey and black shorts on a red road bicycle.
+
+summary:
+[reference generation] The target video shows <Subject 1> riding a bicycle along a sunny beach at the waterline, rendered in the medium and palette of <Picture 1>.
+
+retention_analysis:
+<Picture 1>: reference - only the medium (watercolour on paper, paper grain, wet-on-wet blooms, soft pigment edges) and the palette are taken. Its subject and framing are not used; nothing it depicts appears in the video.
+
+detailed_description:
+The target video is in the watercolour medium and palette of <Picture 1>. [Shot 1] A wide side-on tracking shot follows <Subject 1> as she rides from left to right along the wet sand at the edge of the sea, pedalling steadily, her jersey bright against the pale sand. Small waves wash in behind her and slide back, leaving a glossy sheen on the sand that reflects the bicycle. The horizon sits in the upper third, a flat band of sea under an open sky with a few soft clouds. The camera tracks alongside her at a matching medium speed across the whole shot.
+
+overall_soundscape:
+Open beach ambience: waves breaking softly and hissing back over the sand, a steady sea breeze across the microphone, the tyres' wet crackle on packed sand and the light tick of the freewheel, a gull calling once in the distance.
+
+non_diegetic_music:
+A light, bright acoustic guitar figure, mixed well beneath the ambience, steady through the whole clip.
+```
+
+Each output was read with `get_output_frames(count=12)` and frames 0–5.
+
+| Job | Arm, seed | Person, pose or window? | Style carried? | Frame-0 leak? |
+| --- | --- | --- | --- | --- |
+| f90a041af26a | a, 1001 | no. One cyclist in yellow and black on a red bike, side-on, riding left to right along the waterline, with no window and no frame | no. Photographic, saturated blue sky and sea | no. Frames 0–5 are the beach shot |
+| 1b751acfc1d4 | a, 2002 | no. Same subject and framing, with puffy clouds | no. Photographic | no |
+| b1469a34cea9 | b, 1001 | no person beyond the cyclist, no pears or vase | no. Photographic | no |
+| db3b5b47095b | b, 2002 | no | no. Photographic | no |
+
+Arm a shows no sign of the claim: neither seed brings in the old man, his pose or the window
+framing. Under the verdict rule that is **refuted**. But the followed arm didn't carry the medium
+either, and the clips with the same seed are near-identical across arms. The image reference was
+effectively ignored, which is the risk the plan names: "a role phrasing that H3 ignores entirely
+would test the phrasing, not the claim." So this result says that a reference prompted
+style-only, in these words, didn't leak its person on dw. It doesn't say that a style
+reference H3 does follow keeps its person out. A second probe would need a phrasing that
+carries the medium (for instance, a reference that isn't marked "not used" for everything except
+medium) before the leak question can be asked of it.
+
+## Probe 5: handedness
+
+The `video-with-audio` defaults ran with this prompt (arm a):
+
+```
+summary:
+[text generation] The target video shows a woman facing the camera in a kitchen who picks up a red mug and raises it.
+
+detailed_description:
+The target video is in realistic photographic style. [Shot 1] A static medium shot frames a woman in her thirties with short dark hair and a plain grey sweater, standing centred behind a white kitchen counter and facing the camera squarely. A single red mug sits on the counter directly in front of her, centred. Soft daylight falls from a window out of frame. She looks at the lens, then picks up the red mug in her left hand and raises it to chest height, holding it there steadily and smiling for the rest of the shot. The camera does not move.
+
+overall_soundscape:
+A quiet kitchen room tone, a soft ceramic clink as the mug leaves the counter, a faint fridge hum.
+
+non_diegetic_music:
+None.
+```
+
+Arm b changes only "in her left hand and raises" to "in her left hand, on screen right, and
+raises". She faces the camera, so her left hand is on screen right, and the two arms ask for the
+same picture.
+
+Each clip was read with `get_output_frames(count=8)`, and then frames 35/53, 70/88 and 123,
+around and after the raise.
+
+| Job | Arm, seed | Screen side of the mug | Hand holding it | Other hand |
+| --- | --- | --- | --- | --- |
+| a6c07856c701 | a, 1001 | right (from about 2.9 s to the end) | her left | right hand flat on the counter, screen left |
+| cb19f9007653 | a, 2002 | right (from about 3.7 s to the end) | her left | right hand flat on the counter, screen left |
+| e96170407504 | b, 1001 | right | her left | right hand flat on the counter, screen left |
+| 7ce8ed6f90ab | b, 2002 | right | her left | right hand flat on the counter, screen left |
+
+The mug starts centred and moves to screen right as it is raised on every seed of both arms, so
+the anatomical side alone was enough here. Treat this as one easy case: a single person facing
+the camera, one prop, a static shot. It doesn't cover a person in profile, two people, or a
+moving camera.
+
+Side finding: the four P5 clips decode at -71 to -80 dBFS mean, near-silent. The engine flagged
+each one, so the quiet soundscape was barely rendered. This doesn't bear on the claim.
+
+## Method notes and deviations
+
+- **Reference images from `templates/text-to-image`, not FLUX.** The FLUX 3 text-to-image
+  template needed a 40.3 GB download on lem. `templates/text-to-image` was cached and makes a
+  512px SD-class image, which was enough for a stylised picture. Both images are watercolour
+  and carry the distinguishing content each arm needs.
+- **`<Picture 1>`, not `<Image 1>`.** The plan's wording, "<Image 1> sets only the medium and
+  palette. Its subject and framing are not used", was written with H3's image-reference token,
+  `<Picture 1>`. The sentence is otherwise as the plan states it.
+- **P2's second clip came from the template's own `voice` step.** That step is a
+  `generate_speech` step, the plan's "or similar". `voice_line` was overridden with new words
+  and kept the same Bark preset, so the second clip differs in words and not in voice.
+- **P5 ran `video-with-audio`'s defaults:** the 4-step v1.2 fl2v turbo LoRA, 5 steps and shift
+  6. The plan says "templates run their defaults". This differs from the 2026-10 dialogue
+  probes' 8-step LoRA, 9 steps and shift 12.
+- **Measures that read no audio.** No agent can listen. P2 is judged by Whisper transcripts
+  through `check-script`, and P3 and P5 by frames only.

From 0c112449ecc94465826d56b8dbe4881ff52ada44 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 22:46:46 -0500
Subject: [PATCH 005/125] docs: #1085 - reframe a clip to another aspect (crop
 or native re-render)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md   | 32 ++++++++++++++++++++++++++++++++
 dw/tasks/fit.py |  7 ++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 7372bfbd..4c823416 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1049,6 +1049,38 @@ and exactly `num_frames`, the pipeline runs on the fitted video, and
 ]
 ```
 
+#### Reframe to another aspect
+
+To turn a 16:9 clip into 9:16, 4:5 or 1:1 there are two ways today:
+
+- **Crop.** `fit_to_model` with `mode: "crop"` and the target `width`/`height`
+  scales each frame to fill and centre-crops it. It works at full resolution
+  with no model, and it loses the sides. `num_frames` is required: set it to
+  the clip's own length to keep every frame. `restore_to_source` is the wrong
+  follow-up for a reframe, because it undoes the fit.
+
+  ```json
+  {
+      "name": "reframe",
+      "task": {
+          "command": "fit_to_model",
+          "arguments": {
+              "video": "asset:clip.mp4",
+              "width": 432,
+              "height": 768,
+              "num_frames": 121,
+              "mode": "crop"
+          }
+      }
+  }
+  ```
+
+- **Re-render natively.** A generated clip is usually better re-made at the
+  portrait size. Any H3 template takes any 32-multiple `width`/`height` (for
+  example 544x960), and that keeps the audio.
+
+Generative outpaint of video (filling the new sides) is not supported; see #1066.
+
 `mode` is `letterbox` (default: scale to fit, centred on black), `stretch`
 (resize to fill exactly) or `crop` (scale to fill, centre-crop). The frame
 count is exact: a longer source is cut to its first `num_frames` frames and a
diff --git a/dw/tasks/fit.py b/dw/tasks/fit.py
index e27e5311..a464d75f 100644
--- a/dw/tasks/fit.py
+++ b/dw/tasks/fit.py
@@ -15,6 +15,9 @@
 whatever the model did to the fitted frame (2x for the upscalers), inferred
 from the output's size, so no `scale` argument is needed.
 
+`mode: "crop"` also reframes a clip to another aspect (16:9 to 9:16); see
+"Reframe to another aspect" in docs/TASKS.md.
+
 Neither task touches a soundtrack. The fitted video has none (its length is
 the model's), and the restored one has none either - a template pairs the
 source's track with `pair_audio` after the restore.
@@ -98,7 +101,9 @@ def fit_to_model(video, width, height, num_frames, mode="letterbox", downscale=1
     frame count set to exactly `num_frames`: a longer source is cut to its
     first `num_frames` frames, a shorter one holds its last frame. Hand the
     `fit` record to restore_to_source with the model's output to get the
-    source's own size and length back.
+    source's own size and length back. To reframe a clip to another aspect
+    (16:9 to 9:16), use `mode: "crop"`; see "Reframe to another aspect" in
+    docs/TASKS.md.
 
     `downscale` fits into `width`/downscale x `height`/downscale instead, so
     a template can keep `width`/`height` as a 2x model's output size and

From cc046a1b6fbc506b629e7c7cf2f9569606bc6e62 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 22:59:13 -0500
Subject: [PATCH 006/125] fix(install): #1084 - require Python >=3.12
 (pyproject, classifiers, install scripts, docs)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 README.md            |  2 +-
 docs/DEPENDENCIES.md |  2 +-
 install.ps1          |  6 +++---
 install.sh           | 11 ++++++-----
 pyproject.toml       |  6 ++----
 5 files changed, 13 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 86f77da2..5b7e950e 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,7 @@ two front ends on it: an **MCP server**, so Claude Code (or any MCP client)
 can author, run and inspect generations; and a **web UI** for doing the same
 by hand. A CLI sits underneath for when you want neither.
 
-**Python 3.10-3.14 | CUDA (NVIDIA) | MPS (Apple Silicon) | CPU**
+**Python 3.12-3.14 | CUDA (NVIDIA) | MPS (Apple Silicon) | CPU**
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/img/ui-workflows-dark.png">
diff --git a/docs/DEPENDENCIES.md b/docs/DEPENDENCIES.md
index 088443bc..27152ad8 100644
--- a/docs/DEPENDENCIES.md
+++ b/docs/DEPENDENCIES.md
@@ -16,7 +16,7 @@ source ./activate
 .\venv\scripts\activate
 ```
 
-The install scripts handle everything: Python version detection (3.10-3.14), virtual environment creation, PyTorch, diffusers, and all dependencies.
+The install scripts handle everything: Python version detection (3.12-3.14), virtual environment creation, PyTorch, diffusers, and all dependencies.
 
 ### Manual Installation
 
diff --git a/install.ps1 b/install.ps1
index 0803c794..5fd5b2d1 100644
--- a/install.ps1
+++ b/install.ps1
@@ -27,8 +27,8 @@ catch {
     Exit 1
 }
 
-# Check for supported Python version (3.10 - 3.14)
-$supportedPythonVersions = "3.14", "3.13", "3.12", "3.11", "3.10"
+# Check for supported Python version (3.12 - 3.14)
+$supportedPythonVersions = "3.14", "3.13", "3.12"
 if ($env:INSTALL_PYTHON_VERSION) {
     $pythonVersion = $env:INSTALL_PYTHON_VERSION
 }
@@ -52,7 +52,7 @@ else {
 if (-not $pythonVersion) {
     $supportedPythonVersions = ($supportedPythonVersions | ForEach-Object { "Python $_" }) -join ", "
     Write-Error "No usable Python version found, supported versions are: $supportedPythonVersions"
-    Write-Output "diffusers-workflow requires Python version >= 3.10 and <= 3.14"
+    Write-Output "diffusers-workflow requires Python version >= 3.12 and <= 3.14"
     Exit 1
 }
 
diff --git a/install.sh b/install.sh
index 4f98b519..9c826e12 100644
--- a/install.sh
+++ b/install.sh
@@ -59,7 +59,7 @@ if $UBUNTU; then
 fi
 
 # You can specify preferred python version by exporting `INSTALL_PYTHON_VERSION`
-# e.g. `export INSTALL_PYTHON_VERSION=3.8`
+# e.g. `export INSTALL_PYTHON_VERSION=3.12`
 INSTALL_PYTHON_PATH=
 PYTHON_MAJOR_VER=
 PYTHON_MINOR_VER=
@@ -67,7 +67,7 @@ PYTHON_MINOR_VER=
 find_python() {
   set +e
   unset BEST_VERSION
-  for V in 314 3.14 313 3.13 312 3.12 311 3.11 310 3.10; do
+  for V in 314 3.14 313 3.13 312 3.12; do
     if command -v python$V >/dev/null; then
       if [ "$BEST_VERSION" = "" ]; then
         BEST_VERSION=$V
@@ -97,12 +97,13 @@ else
 fi
 
 if ! command -v "$INSTALL_PYTHON_PATH" >/dev/null; then
-  echo "${INSTALL_PYTHON_PATH} was not found"
+  echo "${INSTALL_PYTHON_PATH:-python3.12 to python3.14} was not found" >&2
+  echo "diffusers-workflow requires Python version >= 3.12 and <= 3.14 (3.10 and 3.11 are not supported)" >&2
   exit 1
 fi
 
-if [ "$PYTHON_MAJOR_VER" -ne "3" ] || [ "$PYTHON_MINOR_VER" -lt "10" ] || [ "$PYTHON_MINOR_VER" -ge "15" ]; then
-  echo "diffusers-workflow requires Python version >= 3.10 and <= 3.14" >&2
+if [ "$PYTHON_MAJOR_VER" -ne "3" ] || [ "$PYTHON_MINOR_VER" -lt "12" ] || [ "$PYTHON_MINOR_VER" -ge "15" ]; then
+  echo "diffusers-workflow requires Python version >= 3.12 and <= 3.14" >&2
   echo "Current Python version = $INSTALL_PYTHON_VERSION" >&2
   # If Arch, direct to Arch Wiki
   if type pacman >/dev/null 2>&1 && [ -f "/etc/arch-release" ]; then
diff --git a/pyproject.toml b/pyproject.toml
index bc55cba5..ff19b9df 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -11,15 +11,13 @@ name = "diffusers-workflow"
 version = "0.17.0-alpha.1"
 description = "Declarative workflow engine and web UI for Hugging Face Diffusers"
 readme = "README.md"
-requires-python = ">=3.10"
+requires-python = ">=3.12"
 license = { text = "Apache-2.0" }
 authors = [{ name = "dkackman" }]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
@@ -155,7 +153,7 @@ dw-test = "dw.test:main"
 dw-mcp = "dw_mcp.__main__:main"
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py312"
 
 [tool.ruff.lint]
 # Start conservative: pyflakes + pycodestyle only. Widen (e.g. add "I" for

From a5d22ebf80d2ef757e46fedbd7334018eab195e6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 23:01:23 -0500
Subject: [PATCH 007/125] fix(tasks): #1085 - reframe pointer in fit_to_model
 mode param doc (served by get_task)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/fit.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/dw/tasks/fit.py b/dw/tasks/fit.py
index a464d75f..80cf6db4 100644
--- a/dw/tasks/fit.py
+++ b/dw/tasks/fit.py
@@ -117,7 +117,9 @@ def fit_to_model(video, width, height, num_frames, mode="letterbox", downscale=1
         height: The model's working height in pixels
         num_frames: The model's frame count, e.g. an 8n+1 LTX length
         mode: "letterbox" (scale to fit, centred on black), "stretch" (resize
-            to fill exactly) or "crop" (scale to fill, centre-crop)
+            to fill exactly) or "crop" (scale to fill, centre-crop; also the
+            way to reframe a clip to another aspect - see TASKS.md "Reframe
+            to another aspect")
         downscale: Divides `width` and `height` before fitting - 2 for a 2x
             model whose output size they are. Both must be divisible by it
 

From 49b1373f4356a8e90019dbf3cbb011e63bc7e718 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 23:10:56 -0500
Subject: [PATCH 008/125] fix(install): #1084 - ps1 range-checks an explicit
 INSTALL_PYTHON_VERSION; drop stale 3.10 comment

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/__init__.py |  6 +++---
 install.ps1    | 31 ++++++++++++++-----------------
 2 files changed, 17 insertions(+), 20 deletions(-)

diff --git a/dw/__init__.py b/dw/__init__.py
index 3337b5ac..89ee2063 100644
--- a/dw/__init__.py
+++ b/dw/__init__.py
@@ -110,9 +110,9 @@ def _inductor_cache_dir_default(environ):
 
 
 def _read_version():
-    # Single-sourced from pyproject.toml. Read as text rather than TOML:
-    # tomllib is 3.11+ and this project supports 3.10. In a wheel install
-    # there is no pyproject on disk - the package metadata carries it.
+    # Single-sourced from pyproject.toml. A regex on the text is enough for
+    # one line, without parsing the whole file. In a wheel install there is
+    # no pyproject on disk - the package metadata carries it.
     try:
         pyproject = os.path.join(os.path.dirname(__file__), "..", "pyproject.toml")
         with open(pyproject, encoding="utf-8") as f:
diff --git a/install.ps1 b/install.ps1
index 5fd5b2d1..4bdc12b3 100644
--- a/install.ps1
+++ b/install.ps1
@@ -29,23 +29,20 @@ catch {
 
 # Check for supported Python version (3.12 - 3.14)
 $supportedPythonVersions = "3.14", "3.13", "3.12"
-if ($env:INSTALL_PYTHON_VERSION) {
-    $pythonVersion = $env:INSTALL_PYTHON_VERSION
-}
-else {
-    $pythonVersion = $null
-    foreach ($version in $supportedPythonVersions) {
-        try {
-            $pver = (python --version).split(" ")[1]
-            $result = $pver.StartsWith($version)
-        }
-        catch {
-            $result = $false
-        }
-        if ($result) {
-            $pythonVersion = $version
-            break
-        }
+# The script always runs plain `python`, so check that interpreter's version;
+# an explicit INSTALL_PYTHON_VERSION must also be one of the supported ones.
+$pythonVersion = $null
+foreach ($version in $supportedPythonVersions) {
+    try {
+        $pver = (python --version).split(" ")[1]
+        $result = $pver.StartsWith("$version.")
+    }
+    catch {
+        $result = $false
+    }
+    if ($result -and ((-not $env:INSTALL_PYTHON_VERSION) -or ($env:INSTALL_PYTHON_VERSION.StartsWith($version)))) {
+        $pythonVersion = $version
+        break
     }
 }
 

From 00e89a94c456c22c65aa7264ef4881a5da790ae6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 23:17:05 -0500
Subject: [PATCH 009/125] fix(tasks): #1085 - put the reframe pointer in the
 served fit_to_model mode description

get_task serves mode from the register_command parameter_descriptions
override, not the fit.py Args docstring a5d22ebf edited.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/tasks/video_handlers.py   | 4 +++-
 tests/test_task_discovery.py | 8 ++++++++
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/dw/tasks/video_handlers.py b/dw/tasks/video_handlers.py
index 814fd5e9..f82ca06b 100644
--- a/dw/tasks/video_handlers.py
+++ b/dw/tasks/video_handlers.py
@@ -161,7 +161,9 @@ def _handle_window_video(task, arguments, previous_pipelines):
         ),
         "mode": (
             "letterbox (scale to fit, centred on black), stretch (resize to "
-            "fill exactly) or crop (scale to fill, centre-crop)."
+            "fill exactly) or crop (scale to fill, centre-crop). crop is also "
+            "how to reframe a clip to another aspect (16:9 to 9:16) - see "
+            'TASKS.md "Reframe to another aspect".'
         ),
         "downscale": (
             "Fit into width/downscale x height/downscale instead, default 1 - "
diff --git a/tests/test_task_discovery.py b/tests/test_task_discovery.py
index 6698d41f..11308ba0 100644
--- a/tests/test_task_discovery.py
+++ b/tests/test_task_discovery.py
@@ -63,6 +63,14 @@ def test_fit_to_model_lists_its_arguments_and_the_mode_choices(self):
         assert by_name["mode"]["choices"] == ["letterbox", "stretch", "crop"]
         assert by_name["mode"]["default"] == "letterbox"
 
+    def test_fit_to_model_mode_names_crop_as_the_reframe(self):
+        # #1085: the served mode text, not the fit.py docstring, is what
+        # get_task shows, so the reframe pointer must live there.
+        description = describe_task("fit_to_model")
+        mode = {p["name"]: p for p in description["parameters"]}["mode"]
+        assert "reframe a clip to another aspect" in mode["description"]
+        assert "Reframe to another aspect" in mode["description"]
+
     def test_restore_to_source_lists_video_and_fit(self):
         names = self.names(describe_task("restore_to_source"))
         assert "video" in names

From 69d187607310adb24f065698336536e2ee1c7312 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Fri, 30 Oct 2026 23:21:10 -0500
Subject: [PATCH 010/125] feat(plugin): #1072 - record the AISkills probes
 P2/P3/P5 (all refuted) as probed-and-not-a-rule

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/minimax-h3/references/dialogue.md |  4 ++++
 .../skills/minimax-h3/references/per-character.md   | 13 +++++++++++++
 plugins/dw/skills/minimax-h3/references/staging.md  | 13 +++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/plugins/dw/skills/minimax-h3/references/dialogue.md b/plugins/dw/skills/minimax-h3/references/dialogue.md
index 62c472dc..42c4d0c7 100644
--- a/plugins/dw/skills/minimax-h3/references/dialogue.md
+++ b/plugins/dw/skills/minimax-h3/references/dialogue.md
@@ -70,6 +70,10 @@ rule and none is worth prompt words yet:
     (WanGP's claim) is not needed: one person in frame, Ref2VA with the
     track held, sung and spoken, moved the mouth at the same instants with
     the words in `<d>` or not (`2026-10-h3-wangp-probes.md`, #985).
+  - a timbre-only audio reference didn't replay its source words: with
+    `templates/minimax/voice-timbre-reference` as shipped, two Bark source
+    clips and two seeds each, `check-script` heard only the new `<d>` line
+    and no source word (`2026-10-h3-aiskills-probes.md` row P2, #1059).
 - Not settled:
   - whether `<breath>` adds a beat: it may lengthen a pause H3 already takes
     at a sentence break, but it doesn't create one (row 6b);
diff --git a/plugins/dw/skills/minimax-h3/references/per-character.md b/plugins/dw/skills/minimax-h3/references/per-character.md
index 93be17d6..ddbf08bb 100644
--- a/plugins/dw/skills/minimax-h3/references/per-character.md
+++ b/plugins/dw/skills/minimax-h3/references/per-character.md
@@ -11,3 +11,16 @@ that. Give each character their own reference instead.
 3. Reference the crops, one per character, in the shot's reference list
    (`keep_output` makes each an `asset:`), never the group picture.
 4. Judge the first frames (`get_output_frames`) for the old composition.
+
+## Probed and not a rule
+
+Tested on our server (Ref2VA turbo, 960x544, two seeds per arm,
+October 2026; the record is `docs/proposals/audits/2026-10-h3-aiskills-probes.md` in the
+diffusers-workflow repo, #1059), and not a rule:
+
+- Refuted, but weakly: a style-only image reference didn't pull its person
+  or composition into the shot. A watercolour of an old man at a window,
+  prompted as "a style reference only", left no man, pose or window on
+  either seed (row P3). The medium didn't carry over either, so H3 ignored
+  the reference under that phrasing; this says nothing about a style
+  reference H3 does follow.
diff --git a/plugins/dw/skills/minimax-h3/references/staging.md b/plugins/dw/skills/minimax-h3/references/staging.md
index 93a79d9c..915a2165 100644
--- a/plugins/dw/skills/minimax-h3/references/staging.md
+++ b/plugins/dw/skills/minimax-h3/references/staging.md
@@ -15,3 +15,16 @@ rule came from a render that went wrong on our server (#484).
   for ~1.5s (about 1 in 25): check a shot's first frames and say in
   `subject_definitions` that the portrait's backdrop, pose and framing are
   not reused.
+
+## Probed and not a rule
+
+Tested on our server (T2VA turbo, 960x544, two seeds per arm, October 2026;
+the record is `docs/proposals/audits/2026-10-h3-aiskills-probes.md` in the
+diffusers-workflow repo, #1059), and not a rule:
+
+- Refuted: adding "on screen right" to an anatomical side isn't needed for
+  handedness. A woman facing the camera asked to raise a mug "in her left
+  hand" used her left hand, on screen right, on both seeds, as did the arm
+  that added "on screen right" (row P5). That is one easy case: one person
+  facing the camera, one prop, a static shot. A person in profile, two
+  people and a moving camera weren't tested.

From ec039e49cd699fc0fb8fd783b650b9127d00d3a7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 00:14:26 -0500
Subject: [PATCH 011/125] docs(proposals): #1059 - close-out record for the H3
 AISkills probes and style pointer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/h3-aiskills-probes-complete.md   | 121 ++++++++++++++++++
 docs/proposals/todo.md                        |   8 ++
 2 files changed, 129 insertions(+)
 create mode 100644 docs/proposals/complete/h3-aiskills-probes-complete.md

diff --git a/docs/proposals/complete/h3-aiskills-probes-complete.md b/docs/proposals/complete/h3-aiskills-probes-complete.md
new file mode 100644
index 00000000..96874bf7
--- /dev/null
+++ b/docs/proposals/complete/h3-aiskills-probes-complete.md
@@ -0,0 +1,121 @@
+# H3 AISkills claims: style-skills pointer and three probes on lem (#1059)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 approved by Don on 2026-10-30 ("approve with
+defaults", Q1–Q4) as "build smaller"; three stages, #1070 (style pointer),
+#1071 (probes), #1072 (rules), all verified. The probe record is
+`docs/proposals/audits/2026-10-h3-aiskills-probes.md`; this doc is the
+design record around it.
+
+## The idea
+
+einhorn13/AISkills publishes two H3 prompting guides (`MiniMax_H3_prompting_v20.md`,
+`MiniMax_H3_prompting_deep_v3.md`). The repo has no license, so nothing was
+copied; only its claims were tested. Most of v20 repeats MiniMax's own
+`h3-prompt-writing` skill, which `minimax-h3` already points at. The issue
+proposed two things:
+
+- **Part 1:** point the skill at MiniMax's eight style packs in
+  `MiniMax-AI/MiniMax-H3/skills/`, with the deep guide's "name the medium,
+  then its physical traits" line.
+- **Part 2:** probe seven claims on lem before any became a rule.
+
+## Decisions
+
+- **Plan v1 verdict: build smaller.** Probe 3 of the 7 claims: P2 (a
+  timbre-only audio reference replays its source words), P3 (a style image
+  pulls in its person and composition), P5 (screen side plus anatomical side
+  holds handedness). These touch a shipped template (`voice-timbre-reference`)
+  or #484's field-report classes.
+- **Deferred (Q2 default):** P1 (FL2VA anime at ~12 unique fps), *comes back
+  on* a cel/anime request or choppy motion in a field report; P4 (POV breaks
+  on an outside description), *comes back on* a POV request or field report.
+- **Dropped:** P6 (ongoing motion vs settle with a new last frame per
+  segment), because dw chains carry the last frame forward as the next first
+  frame and pin no end image (#985 claim 2), *comes back on* keyframed chains
+  or a seam snap in a field report. P7 (positive targets beat negations) was
+  already settled by the 2026-10 dialogue probes, rows 10b and 12.
+- **Q1:** a new `references/style.md`, with `SKILL.md`'s Sources wording
+  trimmed to pay for the link. **Q3:** the medium line ships unprobed,
+  attributed to MiniMax's packs. **Q4:** ~60 GPU minutes, both P2 clips.
+
+## What the probes found
+
+From the audit doc (2 seeds per arm, 1001 and 2002; held only when both
+broken seeds show the effect and neither followed seed does). Configuration:
+960x544, 124 frames, int4 sdnq (VAE int8), 24 fps, turbo LoRAs per template.
+
+| # | Claim | Verdict |
+| --- | --- | --- |
+| P2 | timbre-only audio reference replays its source words | **refuted**: on all four takes `check-script` heard only the new line, no `line_mismatch`, no source word from either clip |
+| P3 | a style image pulls in its person and composition | **refuted, weakly**: no person, pose or window on any seed, but no watercolour carried over either; H3 ignored the reference under this phrasing |
+| P5 | bare anatomical side misses; "on screen right" holds it | **refuted**: all four clips put the left hand on screen right |
+
+## What was built
+
+**Stage 1, #1070** (plugin only): `e745bca9`, develop `7735379d`.
+- New `plugins/dw/skills/minimax-h3/references/style.md`: the eight packs
+  by bare name, one line each on the request it suits; the per-pack install
+  `npx skills add MiniMax-AI/MiniMax-H3 --skill <name>`, the wildcard
+  described and never advised.
+- The medium line was kept: the build read three upstream packs
+  (`papercraft-stop-motion-explainer`, `paper-collage-explainer-generator`,
+  `handdrawn-live-video-generator`) and each prompts that way. It is
+  attributed to them, marked unprobed on dw, and stated not to override
+  the guide-clip rule (a style prompt does not restyle a guide).
+- `SKILL.md` links it from *Prompts* (12,286 bytes, under the 12,288 cap);
+  `plugins/dw/README.md` agrees on the install form and pack count.
+
+**Stage 2, #1071** (docs only): `7495862f`, develop `e7cc1545`. The audit doc;
+12 probe jobs, 2 reference images and 4 `check-script` runs in workspace
+`qa-h3-aiskills-probes` on lem. All succeeded; nothing is marked not run.
+
+**Stage 3, #1072** (plugin only): `69d18760`, develop `24eb678d`. All three
+verdicts were refuted, so no rule landed and `voice-timbre-reference` is
+unchanged:
+- P2: a bullet in `references/dialogue.md`'s *Refuted on both seeds* list.
+- P3: a new *Probed and not a rule* section in `references/per-character.md`,
+  keeping the "H3 ignored the reference" caveat.
+- P5: the same section in `references/staging.md`, after #484's rules,
+  with the probe's scope limit (one person facing camera, one prop, static).
+- `SKILL.md` got no new bytes.
+
+## Method deviations (from the audit doc)
+
+- Reference images came from `templates/text-to-image` (cached, 512px), not
+  FLUX 3, which needed a 40.3 GB download on lem.
+- P3's prompt used H3's image token `<Picture 1>` where the plan wrote
+  `<Image 1>`.
+- P2's second clip came from the template's own Bark `voice` step with new
+  words, so the clips differ in words, not voice.
+- P5 ran `video-with-audio`'s defaults (4-step v1.2 fl2v turbo, 5 steps,
+  shift 6), unlike the 2026-10 dialogue probes' 8-step settings.
+
+## Bounces per stage
+
+| Stage | Bounces | Cause |
+| --- | --- | --- |
+| 1, #1070 | 0 | The tester passed M-F189–M-F192 and sent the byte cap and test run to docs review, which closed it. The 7 local test failures are `TestKandinsky6Skill`/`TestFlux3KleinSkill` needing a newer diffusers than the agents' Mac has, unrelated. |
+| 2, #1071 | 1 | M-F193: the ticket carried a summary of the audit doc, not its configuration. Cleared by posting the doc's header, configuration and verdict rows verbatim; nothing re-run. |
+| 3, #1072 | 0 | |
+
+No stage comment names `usage:` figures, so per-stage session cost is not
+recorded. The plan estimated ~$10 (stage 1 ~$2, stage 2 ~$5, stage 3 ~$3)
+and ~60 lem GPU minutes; the audit doc records no GPU total.
+
+## Not built, and why
+
+- **Any rule from P2, P3 or P5:** all refuted. P3's refutation is weak (the
+  reference had no visible effect at all); *comes back if* a field report
+  shows a style reference's subject leaking, or a phrasing that makes H3
+  take a style reference's medium.
+- **A `voice-timbre-reference` prompt change:** gated on P2 holding.
+- **P1, P4 (deferred) and P6, P7 (dropped):** triggers above.
+- **The guide's style recipes, A/B/C ratings and ComfyUI embeddings:**
+  unlicensed and untested by us, or not applicable to diffusers.
+- **A frame-cadence check** (what P1 would need): not built; P1 is deferred.
+
+## Standing cost
+
+The style-pack names are bare and untested; a MiniMax rename shows up only
+when someone installs one.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index f2de5926..36577a54 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -367,6 +367,14 @@ remaining deferred fix is recorded in
   copy during the one decode. Measures only, no rules. Record, including
   what was deferred (rules until #1033 measures real chains, take drift,
   apparent age): `complete/seam-look-measures-complete.md`.
+- **H3 AISkills claims: style-skills pointer and three probes** (#1059,
+  stages #1070-#1072), shipped 2026-10-30. `minimax-h3/references/style.md`
+  points a style-heavy request at MiniMax's eight style packs, by name. On
+  lem, P2 (timbre reference replays source words), P3 (style image pulls in
+  its person) and P5 (screen side holds handedness) were all refuted
+  (`audits/2026-10-h3-aiskills-probes.md`) and listed as probed-and-not-a-rule.
+  Record, including what was deferred (P1 anime cadence, P4 POV) and dropped
+  (P6, P7): `complete/h3-aiskills-probes-complete.md`.
 
 ## Declined
 

From 7525c41a707abecf8d6bf720aeb80d4bde292e08 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 01:27:00 -0500
Subject: [PATCH 012/125] docs(proposals): #1061 - close-out record for the
 follow-timeline probe (gate failed, B/C not built)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/chain-follow-video-complete.md   | 127 ++++++++++++++++++
 docs/proposals/todo.md                        |   8 ++
 2 files changed, 135 insertions(+)
 create mode 100644 docs/proposals/complete/chain-follow-video-complete.md

diff --git a/docs/proposals/complete/chain-follow-video-complete.md b/docs/proposals/complete/chain-follow-video-complete.md
new file mode 100644
index 00000000..b6459840
--- /dev/null
+++ b/docs/proposals/complete/chain-follow-video-complete.md
@@ -0,0 +1,127 @@
+# Chain that follows consecutive windows of one long source video (#1061)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 approved by Don on 2026-10-31 ("approve defaults",
+Q1–Q3) as "build smaller and gated": a probe first, the engine change only
+if the probe passed. Three stages: #1074 (probe, verified), #1075
+(`match_video` chain key) and #1076 (template and skill line), both closed
+not planned when the probe's gate failed. **Nothing was built**: no code,
+no template, no deploy. This doc is the record of the probe and of the
+design, so a revival starts from both.
+
+## The idea
+
+Let a chain reference consecutive windows of one long source video, so a
+long output (past H3's 345-frame cap) follows a driving clip's motion and
+camera window by window, not only its own previous tail. Prior art:
+einhorn13/mmh3_media's "follow timeline" (MIT, ComfyUI), where each
+continuation segment's `<Video 1>` is the next window of the source on the
+generation clock, a reroll reads the same window, the paired soundtrack is
+sliced with it, and a source that runs out is an error, not padding.
+
+## Decisions
+
+- **No-code composition doesn't work.** A `for_each` over `window_video`
+  entries can't do it: those windows start `overlap` frames early (the
+  wrong clock), a `for_each` member can take only the whole previous
+  render, not its tail, and a `chain` can't vary its reference per segment.
+  The smallest working form was a chain key, `match_video: true`, slicing
+  one source video reference per segment the way `match_audio` slices
+  audio.
+- **Correction to the issue's clock:** in dw the carry is a separate
+  reference video, not frames inside the clip, so the stride would be
+  `num_frames - trim_frames`, not `num_frames - context`.
+- **Gate:** build B and C only if a probe showed (a) H3 ref2va's motion and
+  camera follow a driving window and (b) a 124-frame shot with two video
+  references fits a 24 GB card. Otherwise the verdict is don't build.
+- **Q1:** #1045 (long H3 video-to-video via per-window source slicing,
+  guides on ref2va) stays parked as the full version, cross-linked; it is
+  now parked on this probe's result. **Q2:** segment count derived from the
+  source and tail-trimmed, like `match_audio`. **Q3:** run the probe now.
+- **Demand:** prospective. None of Don's workspaces restyles or
+  motion-transfers a driving clip, and no field report asks for it.
+
+## What the probe found (#1074)
+
+Record: the #1061 comment "Stage A (#1074) probe record". Two ref2va runs on
+lem (RTX 3090, 24,124 MB), develop @ b7fbc8e4: int4 sdnq, 768p turbo LoRA,
+9 steps, sparse attention, seed 12345, 960x544, 124 frames, two
+`MiniMaxH3VideoReference`s (`<Video 1>` the driving window, `<Video 2>` a
+48-frame carry). Source `asset:qa-cast/ep49-episode.mp4`, which has a hard
+cut at source frame 124.
+
+| | Shot 1 (job `8bd76a6d24f2`) | Shot 2 (job `e0180de3a644`) |
+| --- | --- | --- |
+| window | `[0,124)`, no cut | `[85,209)`, cut at window frame 39 |
+| carry | stand-in, unrelated `ep252` `[200,248)` | shot 1's own tail `[76,124)` |
+| time | 1677 s | 1297 s (model cached) |
+
+- **(a) Motion follows: no.** Shot 1, with no cut in its window, followed
+  timing, position and framing. Shot 2 dropped the window's first shot
+  entirely, rendered only the second from frame 0, ran about 40 frames
+  ahead, and invented its last ~20 frames. It ignored the carry too. A
+  fixed-stride window over an edited source routinely holds a cut.
+- **(b) Fits: pass, thin.** Shot 1's highest sample was 23,364 MB reserved,
+  111 MB free; shot 2 showed no OOM (its denoise wasn't sampled). Any
+  heavier reference is past the edge, as #479 classifies.
+- **(c) Seam: broken.** `get_output_frames(seams=true)` on the joined
+  `[0,85)` + shot 2: difference 75.81 at frame 85; `assess_output` warned
+  `seam_level_step` 6.08 dB and `shot_level_spread` 6.08 dB.
+- **The restyle didn't take** in either run: both came out photoreal
+  near-copies of the source, so "follows" meant near-reproduction, not a
+  re-render.
+
+The tester verified the record against the jobs (M-F202, M-F203 pass).
+
+## What was not built, and what would reopen it
+
+- **#1075 `match_video` chain key** and **#1076 `chain-follow-video`
+  template + minimax-h3 skill line**: closed not planned on the gate.
+- **Reopen on either of:**
+  - a lighter H3 build with VRAM headroom to test a third reference, a
+    longer carry or a stronger `<Video 1>` weighting, shown to follow a cut
+    inside a window;
+  - #1045's guide path (driving the shot from a guide rather than a ref2va
+    video reference).
+- **Untested observation, not a reopener:** shot 1, with no cut in its
+  window, followed. Windows cut on the source's shot boundaries might
+  sidestep the cut failure, but not the dropped carry continuity or the
+  restyle not taking.
+
+### The design, kept for a revival
+
+- *Source:* the step's references hold exactly one video reference besides
+  the carry; zero or two-plus refused before the first segment, naming the
+  count (mirrors `_single_audio_reference` in
+  `dw/pipeline_processors/chain.py`).
+- *Timeline:* segment i reads source `[start_i, start_i + num_frames)`,
+  `start_i` from `plan_segments`; a pure function of the index, so a reroll
+  reads the same slice. The slice is a copy of the reference with `frames`
+  and its paired `audio` cut to the window, never mutating the shared
+  reference, decoded lazily one window at a time.
+- *Length:* segment count derived from the source; `segments` and
+  `match_audio` are each exclusive with `match_video`; the last segment
+  overshoots and the output is tail-trimmed; a source shorter than one
+  window is refused.
+- *Continuity:* `last_segment` only (`guide` is refused on ref2va anyway).
+- *Validation:* the same checks in `validate_workflow`, before GPU time.
+
+Open points the tester raised on the spec, unanswered because B never
+started: the shape (`sequence` vs `shot`, where chained H3 templates list
+today), what the last short slice gets, whether the output muxes the
+source's track or the generated audio, and whether omitted continuity
+implies `last_segment`.
+
+## Cost and bounces
+
+| Stage | Outcome | Bounces |
+| --- | --- | --- |
+| #1074 probe | verified | 0 |
+| #1075 `match_video` | not planned (gate) | — |
+| #1076 template + skill | not planned (gate) | — |
+
+The probe used about 50 minutes of lem GPU (1677 s + 1297 s). No stage
+comment names a `usage:` figure, so session cost is left out.
+
+The acceptance cases written for #1075 and #1076 (M-F204 to M-F213,
+`pending:`) have nothing to test and are retired with those stages.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 36577a54..9c41d527 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -375,6 +375,14 @@ remaining deferred fix is recorded in
   (`audits/2026-10-h3-aiskills-probes.md`) and listed as probed-and-not-a-rule.
   Record, including what was deferred (P1 anime cadence, P4 POV) and dropped
   (P6, P7): `complete/h3-aiskills-probes-complete.md`.
+- **Chain following consecutive windows of a long source video** (#1061,
+  stages #1074-#1076), closed 2026-10-31 after its probe only. On lem, H3
+  ref2va followed a driving window with no cut in it, but a window holding
+  a source cut dropped the first shot and the carry broke the seam, so the
+  gate failed and the `match_video` chain key and `chain-follow-video`
+  template were not built. Record, with the design and what would reopen it
+  (a lighter H3 build, or #1045's guide path):
+  `complete/chain-follow-video-complete.md`.
 
 ## Declined
 

From 64b7997933b21611a78a7806a658cfcf17dabfea Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 01:39:20 -0500
Subject: [PATCH 013/125] feat(h3): #1077 - regional edit blocks: source
 latents and mask blend

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/components.py    |   3 +
 dw/pipeline_processors/h3_hold_steps.py |   4 +
 dw/pipeline_processors/h3_mask.py       | 185 ++++++++++++++++++++
 dw/pipeline_processors/h3_mask_steps.py | 217 ++++++++++++++++++++++++
 dw/pipeline_processors/h3_rules.py      | 110 +++++++++++-
 dw/pipeline_processors/pipeline.py      |  86 +++++++++-
 6 files changed, 602 insertions(+), 3 deletions(-)
 create mode 100644 dw/pipeline_processors/h3_mask.py
 create mode 100644 dw/pipeline_processors/h3_mask_steps.py

diff --git a/dw/pipeline_processors/components.py b/dw/pipeline_processors/components.py
index 46aa59db..f8b67880 100644
--- a/dw/pipeline_processors/components.py
+++ b/dw/pipeline_processors/components.py
@@ -29,6 +29,7 @@
 )
 from .h3_guides import insert_guides
 from .h3_hold import core_denoise_sequences, insert_audio_hold
+from .h3_mask import insert_mask_blocks
 from .placement import (
     apply_on_demand_placement,
     create_components_manager,
@@ -718,6 +719,8 @@ def from_pretrained():
             insert_audio_hold(component)
             # ...and `guides` on t2va and fl2va
             insert_guides(component)
+            # ...and `source_video` with a mask, a regional edit (h3_mask.py)
+            insert_mask_blocks(component)
             # ...and the decode-free graph a `refine_tiles` step runs per tile
             from .h3_tiles import attach_tile_blocks
 
diff --git a/dw/pipeline_processors/h3_hold_steps.py b/dw/pipeline_processors/h3_hold_steps.py
index 74d91229..08b67ced 100644
--- a/dw/pipeline_processors/h3_hold_steps.py
+++ b/dw/pipeline_processors/h3_hold_steps.py
@@ -48,6 +48,7 @@
     HELD_ROWS,
     HOLD_AUDIO_INPUT,
     REFINE_NOISE,
+    REFINE_ROW_NOISE,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
 )
@@ -345,6 +346,8 @@ def intermediate_outputs(self):
             OutputParam("timesteps", type_hint=torch.Tensor),
             OutputParam("audio_timesteps", type_hint=torch.Tensor),
             OutputParam("row_timestep_plan", type_hint=list),
+            # The packed re-noise, for a regional edit's kept rows (h3_mask.py)
+            OutputParam(REFINE_ROW_NOISE, type_hint=torch.Tensor),
         ]
 
     @torch.no_grad()
@@ -424,6 +427,7 @@ def __call__(self, components, state):
                 components.scheduler.scale_noise(clean, 1 - strength, noise),
             ]
         )
+        setattr(block_state, REFINE_ROW_NOISE, noise)
 
         logger.info(
             f"Refining from sigma {strength} over {len(block_state.timesteps)} steps"
diff --git a/dw/pipeline_processors/h3_mask.py b/dw/pipeline_processors/h3_mask.py
new file mode 100644
index 00000000..e1b6471d
--- /dev/null
+++ b/dw/pipeline_processors/h3_mask.py
@@ -0,0 +1,185 @@
+"""MiniMax-H3 regional edit: re-denoising a `source_video` inside a mask while
+everything outside it stays the source (#1062).
+
+The refine schedule (dw/pipeline_processors/h3_hold.py) re-denoises a whole
+canvas from `refine_strength`. A regional edit is that refine with most rows
+held: a `mask_video` or `mask_image` - white regenerates - is binarized at
+`MASK_THRESHOLD`, max-pooled onto the transformer's patch-row grid (a cell any
+white pixel touches regenerates) and dilated by `mask_grow` cells. Every other
+generated row is a kept row, written back after each denoise step to the source
+noised to that step's sigma, with the noise the refine block re-noised the
+canvas with. At the last step the sigma is 0 and a kept row is the source
+latent exactly; the decode still round-trips it through the VAE.
+
+Two blocks go into each of H3's core-denoise sequences, always, as no-ops when
+`source_video` is not passed:
+
+- `DwH3SourceLatentsStep`, before `set_timesteps` (after the hold block) - VAE-
+  encodes `source_video` over the generated video rows of `latents`, and keeps
+  the clean rows (`SOURCE_ROWS`) and which ones the mask keeps (`KEEP_ROWS`);
+- `DwH3MaskBlendStep`, a sub-block of the `denoise` loop after `update` -
+  writes the kept rows back after every step. Conditioning rows are never
+  touched.
+
+The refine block (unchanged otherwise) hands its re-noise on as
+`REFINE_ROW_NOISE`. This module puts the blocks in and holds the mask-to-rows
+arithmetic, numpy only; the blocks are dw/pipeline_processors/h3_mask_steps.py,
+imported in `blocks()` only, since it imports diffusers when it loads (#790).
+The argument rules shared with validation are
+dw/pipeline_processors/h3_rules.py (`mask_problems`, `media_problems`).
+"""
+
+import logging
+
+import numpy as np
+
+from .h3_hold import core_denoise_sequences
+from .h3_rules import (
+    BLEND_AFTER,
+    BLEND_BLOCK,
+    MASK_THRESHOLD,
+    REFINE_BEFORE,
+    SOURCE_BEFORE,
+    SOURCE_BLOCK,
+)
+
+logger = logging.getLogger("dw")
+
+
+def blocks():
+    """(DwH3SourceLatentsStep, DwH3MaskBlendStep) - the classes in
+    dw/pipeline_processors/h3_mask_steps.py, imported here on first use because
+    that module imports diffusers when it loads (#790)."""
+    from . import h3_mask_steps
+
+    return h3_mask_steps.DwH3SourceLatentsStep, h3_mask_steps.DwH3MaskBlendStep
+
+
+def _loop(sequence, prefix):
+    """The sequence's denoise loop, or None - the step `refine` anchors to."""
+    loop = sequence.sub_blocks.get(prefix + REFINE_BEFORE)
+    return loop if hasattr(loop, "sub_blocks") else None
+
+
+def insert_mask_blocks(pipeline):
+    """Put the source and blend blocks into every H3 core-denoise sequence.
+
+    Idempotent - a block already in place is left alone. Returns whether the
+    pipeline now takes a regional edit. The two go in as a pair: a sequence
+    missing either anchor (a diffusers that renamed `set_timesteps`, the
+    `denoise` loop or its `update`) gets neither, with a warning, and a
+    pipeline left with none refuses `source_video` at the call.
+    """
+    source_block, blend_block = blocks()
+    inserted = False
+    for prefix, sequence in core_denoise_sequences(pipeline):
+        sub_blocks = sequence.sub_blocks
+        source_name, source_before = prefix + SOURCE_BLOCK, prefix + SOURCE_BEFORE
+        loop = _loop(sequence, prefix)
+        loop_names = list(loop.sub_blocks) if loop is not None else []
+        if source_name in sub_blocks and BLEND_BLOCK in loop_names:
+            inserted = True
+            continue
+        if source_before not in sub_blocks or BLEND_AFTER not in loop_names:
+            logger.warning(
+                f"MiniMax-H3 has a denoise sequence with no '{source_before}' step "
+                f"or '{prefix}{REFINE_BEFORE}' loop with an '{BLEND_AFTER}' to "
+                f"anchor the regional edit to, so it cannot take a source_video"
+            )
+            continue
+        if source_name not in sub_blocks:
+            names = list(sub_blocks)
+            sub_blocks.insert(source_name, source_block(), names.index(source_before))
+        if BLEND_BLOCK not in loop_names:
+            loop.sub_blocks.insert(
+                BLEND_BLOCK, blend_block(), loop_names.index(BLEND_AFTER) + 1
+            )
+        inserted = True
+    return inserted
+
+
+def edits_regions(pipeline):
+    """Whether a pipeline's block graph carries the regional edit."""
+    for prefix, sequence in core_denoise_sequences(pipeline):
+        loop = _loop(sequence, prefix)
+        if (
+            prefix + SOURCE_BLOCK in sequence.sub_blocks
+            and loop is not None
+            and BLEND_BLOCK in loop.sub_blocks
+        ):
+            return True
+    return False
+
+
+def binarized(frames):
+    """`(n, h, w)` bool - True to regenerate - from `(n, h, w, 3|4)` or
+    `(n, h, w)` uint8 mask frames: luma at or above `MASK_THRESHOLD`, the
+    threshold remove_object binarizes its mask at."""
+    frames = np.asarray(frames)
+    if frames.ndim == 4:
+        rgb = frames[..., :3].astype(np.float32)
+        # PIL's L conversion: ITU-R 601-2 luma
+        frames = rgb @ np.array([0.299, 0.587, 0.114], dtype=np.float32)
+    return frames >= MASK_THRESHOLD
+
+
+def _pool(mask, cells, axis):
+    """Max-pool `mask` along `axis` into `cells` cells, cell i covering pixels
+    floor(i * n / cells) up to ceil((i + 1) * n / cells) - so a pixel on a
+    boundary counts toward both cells it touches."""
+    n = mask.shape[axis]
+    pooled = []
+    for i in range(cells):
+        start = i * n // cells
+        end = max(-(-(i + 1) * n // cells), start + 1)
+        pooled.append(
+            np.take(mask, range(start, end), axis=axis).any(axis=axis, keepdims=True)
+        )
+    return np.concatenate(pooled, axis=axis)
+
+
+def _dilate(grid, grow):
+    """`grid` widened by `grow` cells along every axis, diagonals included (a
+    cube structuring element), clipped at the edges."""
+    for _ in range(grow):
+        for axis in range(grid.ndim):
+            cells = np.swapaxes(grid, 0, axis)
+            grown = cells.copy()
+            grown[1:] |= cells[:-1]
+            grown[:-1] |= cells[1:]
+            grid = np.swapaxes(grown, 0, axis)
+    return grid
+
+
+def regenerate_cells(
+    mask, latent_frames, latent_height, latent_width, patch_size, grow
+):
+    """`(t, h, w)` bool over the patch-row grid - True where a row regenerates -
+    from an `(n, height, width)` bool pixel mask (n = 1 for a `mask_image`,
+    which covers every frame).
+
+    A latent frame covers the pixel frames proportional to it, a patch cell
+    `16 * patch` pixels; a cell regenerates if any pixel it covers is white,
+    then the grid is dilated by `grow` cells. The grid flattens frame-major then
+    row-major, the order `patchify_video_latents` packs rows in.
+    """
+    patch_t, patch_h, patch_w = patch_size
+    cells = (
+        latent_frames // patch_t,
+        latent_height // patch_h,
+        latent_width // patch_w,
+    )
+    grid = np.asarray(mask, dtype=bool)
+    if grid.shape[0] == 1:
+        grid = np.repeat(grid, cells[0], axis=0)
+    for axis, count in enumerate(cells):
+        grid = _pool(grid, count, axis)
+    return _dilate(grid, grow)
+
+
+def keep_rows(mask, latent_frames, latent_height, latent_width, patch_size, grow):
+    """The generated video rows a regional edit keeps, as a flat bool array in
+    packed order - the complement of `regenerate_cells`."""
+    return ~regenerate_cells(
+        mask, latent_frames, latent_height, latent_width, patch_size, grow
+    ).reshape(-1)
diff --git a/dw/pipeline_processors/h3_mask_steps.py b/dw/pipeline_processors/h3_mask_steps.py
new file mode 100644
index 00000000..ae234039
--- /dev/null
+++ b/dw/pipeline_processors/h3_mask_steps.py
@@ -0,0 +1,217 @@
+"""The MiniMax-H3 regional-edit blocks (#1062) - what
+dw/pipeline_processors/h3_mask.py inserts and describes.
+
+This module imports diffusers when it loads, so nothing imports it at module
+level - `h3_mask.blocks()` imports it on first use (#790).
+"""
+
+import logging
+
+import numpy as np
+import torch
+from diffusers.models import AutoencoderKLMiniMaxH3
+from diffusers.modular_pipelines.minimax_h3 import encoders
+from diffusers.modular_pipelines.minimax_h3.before_denoise import (
+    patchify_video_latents,
+)
+from diffusers.modular_pipelines.modular_pipeline import ModularPipelineBlocks
+from diffusers.modular_pipelines.modular_pipeline_utils import (
+    ComponentSpec,
+    InputParam,
+    OutputParam,
+)
+
+from .h3_mask import keep_rows
+from .h3_rules import (
+    KEEP_ROWS,
+    MASK_GROW_DEFAULT,
+    MASK_GROW_INPUT,
+    REFINE_ROW_NOISE,
+    REFINE_STRENGTH_INPUT,
+    REGENERATE_MASK,
+    SOURCE_ROWS,
+    SOURCE_VIDEO_INPUT,
+    media_problems,
+)
+
+logger = logging.getLogger("dw")
+
+
+def fit_source_frames(frames, num_frames):
+    """`frames` padded to the `num_frames` H3 aligned the render to, by
+    repeating the last frame - the frames past the source's own are never
+    regenerated from anything but it."""
+    if frames.shape[0] >= num_frames:
+        return frames[:num_frames]
+    pad = np.repeat(frames[-1:], num_frames - frames.shape[0], axis=0)
+    return np.concatenate([frames, pad])
+
+
+class DwH3SourceLatentsStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self):
+        return (
+            "dw: with `source_video`, VAE-encodes it over the generated video rows of `latents` for the refine "
+            "schedule to re-denoise, and keeps the clean rows and which of them the mask leaves alone for the "
+            "loop's blend. Does nothing without `source_video`."
+        )
+
+    @property
+    def expected_components(self):
+        return [ComponentSpec("vae", AutoencoderKLMiniMaxH3)]
+
+    @property
+    def inputs(self):
+        return [
+            InputParam(
+                name=SOURCE_VIDEO_INPUT,
+                default=None,
+                description=(
+                    "The video to edit, as (frames, height, width, 3) uint8 at the render's size and frame "
+                    "count. Needs `refine_strength`."
+                ),
+            ),
+            InputParam(
+                name=REGENERATE_MASK,
+                default=None,
+                description=(
+                    "Internal: the mask as (frames, height, width) bool, True to regenerate; one frame covers "
+                    "every frame. Without it the whole source is re-denoised."
+                ),
+            ),
+            InputParam(
+                name=MASK_GROW_INPUT,
+                type_hint=int,
+                default=MASK_GROW_DEFAULT,
+                description="Patch cells the mask is widened by.",
+            ),
+            InputParam(name="latents", type_hint=torch.Tensor, required=True),
+            InputParam(name="num_condition_video_rows", type_hint=int, default=0),
+            InputParam(name="height", type_hint=int, required=True),
+            InputParam(name="width", type_hint=int, required=True),
+            InputParam(name="num_frames", type_hint=int, required=True),
+            InputParam(name="num_latent_frames", type_hint=int, required=True),
+            InputParam(name="latent_height", type_hint=int, required=True),
+            InputParam(name="latent_width", type_hint=int, required=True),
+        ]
+
+    @property
+    def intermediate_outputs(self):
+        return [
+            OutputParam("latents", type_hint=torch.Tensor),
+            OutputParam(SOURCE_ROWS, type_hint=torch.Tensor),
+            OutputParam(KEEP_ROWS, type_hint=torch.Tensor),
+        ]
+
+    @torch.no_grad()
+    def __call__(self, components, state):
+        block_state = self.get_block_state(state)
+        frames = getattr(block_state, SOURCE_VIDEO_INPUT)
+        if frames is None:
+            return components, state
+
+        height, width = block_state.height, block_state.width
+        # The canvas H3 resolved - the step's own width and height were
+        # checked against the source before the call
+        problems = media_problems(SOURCE_VIDEO_INPUT, frames.shape[:3], width, height)
+        if problems:
+            raise ValueError(problems[0])
+        pixels = fit_source_frames(frames, block_state.num_frames)
+        device = components._execution_device
+        encoded = encoders.encode_vae_condition(
+            components.vae,
+            torch.from_numpy(np.ascontiguousarray(pixels))
+            .to(device)
+            .permute(3, 0, 1, 2)[None],
+            components.pixel_mean,
+            components.pixel_std,
+            components.keyframe_encode_seed,
+        )
+        latents = block_state.latents
+        start = block_state.num_condition_video_rows or 0
+        rows = patchify_video_latents(
+            encoded.to(latents.device, torch.float32), components.patch_size
+        ).to(latents.dtype)
+        if rows.shape != latents[start:].shape:
+            raise ValueError(
+                f"source_video encodes to {tuple(rows.shape)} rows, and the step "
+                f"generates {tuple(latents[start:].shape)}"
+            )
+        block_state.latents = torch.cat([latents[:start], rows])
+        setattr(block_state, SOURCE_ROWS, rows.clone())
+
+        mask = getattr(block_state, REGENERATE_MASK)
+        keep = None
+        if mask is not None:
+            grow = getattr(block_state, MASK_GROW_INPUT)
+            keep = keep_rows(
+                mask,
+                block_state.num_latent_frames,
+                block_state.latent_height,
+                block_state.latent_width,
+                components.patch_size,
+                MASK_GROW_DEFAULT if grow is None else grow,
+            )
+            if keep.shape[0] != rows.shape[0]:
+                raise ValueError(
+                    f"the mask maps to {keep.shape[0]} rows, and the step "
+                    f"generates {rows.shape[0]}"
+                )
+            logger.info(
+                f"Regional edit: regenerating {int((~keep).sum())} of "
+                f"{keep.shape[0]} video rows"
+            )
+            keep = torch.from_numpy(keep).to(latents.device)
+        setattr(block_state, KEEP_ROWS, keep)
+        self.set_block_state(state, block_state)
+        return components, state
+
+
+class DwH3MaskBlendStep(ModularPipelineBlocks):
+    model_name = "minimax-h3"
+
+    @property
+    def description(self):
+        return (
+            "dw: after each denoise step, writes the rows a regional edit keeps back to the source noised to "
+            "the step's sigma, with the refine schedule's own noise. Does nothing without a mask."
+        )
+
+    @property
+    def inputs(self):
+        return [
+            InputParam(name="latents", type_hint=torch.Tensor, required=True),
+            InputParam(name="num_condition_video_rows", type_hint=int, default=0),
+            InputParam(name=SOURCE_ROWS, type_hint=torch.Tensor, default=None),
+            InputParam(name=KEEP_ROWS, type_hint=torch.Tensor, default=None),
+            InputParam(name=REFINE_ROW_NOISE, type_hint=torch.Tensor, default=None),
+        ]
+
+    @property
+    def intermediate_outputs(self):
+        return [OutputParam("latents", type_hint=torch.Tensor)]
+
+    @torch.no_grad()
+    def __call__(self, components, block_state, i, t):
+        keep = getattr(block_state, KEEP_ROWS, None)
+        if keep is None:
+            return components, block_state
+        noise = getattr(block_state, REFINE_ROW_NOISE, None)
+        if noise is None:
+            raise ValueError(
+                f"a regional edit re-denoises from {REFINE_STRENGTH_INPUT}, and "
+                f"the refine schedule left no noise to hold the kept rows with"
+            )
+        scheduler = components.scheduler
+        # After update stepped to the next point of the schedule
+        index = scheduler.step_index if scheduler.step_index is not None else i + 1
+        sigma = scheduler.sigmas[index]
+        source = getattr(block_state, SOURCE_ROWS)
+        rows = block_state.latents[block_state.num_condition_video_rows or 0 :]
+        # In H3's t = 1 - σ convention, as the refine block re-noised them
+        rows[keep] = scheduler.scale_noise(source[keep], 1 - sigma, noise[keep]).to(
+            rows.dtype
+        )
+        return components, block_state
diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index 2ae21d20..da4f0382 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -64,7 +64,7 @@ def refine_problems(arguments, canvas=None):
             f"refine_strength is a sigma in (0, 1) - about 0.2 refines an "
             f"upscaled take - and {strength} is outside it"
         )
-    if arguments.get("latents") is None:
+    if arguments.get("latents") is None and arguments.get(SOURCE_VIDEO_INPUT) is None:
         problems.append(
             "refine_strength re-denoises the 'latents' it is passed - pass the "
             "upscaled latents, e.g. 'previous_result:up'"
@@ -101,7 +101,15 @@ def refine_problems(arguments, canvas=None):
 
 # The arguments that condition a step on a reference, a keyframe or a guide: the
 # tile plan has no place to put one, and each tile would need its own crop
-TILE_CONFLICTS = ("image", "last_image", "references", "guides")
+TILE_CONFLICTS = (
+    "image",
+    "last_image",
+    "references",
+    "guides",
+    "source_video",
+    "mask_video",
+    "mask_image",
+)
 
 
 def _is_int(value):
@@ -436,3 +444,101 @@ def guide_end_problem(frame, length, num_frames):
             f"{frame + length}, past the end of the {num_frames}-frame render"
         )
     return None
+
+
+# Regional edit (#1062): re-denoise a `source_video` from `refine_strength`,
+# holding every row outside a mask to the source at each step's sigma
+# (dw/pipeline_processors/h3_mask.py)
+SOURCE_VIDEO_INPUT = "source_video"
+MASK_VIDEO_INPUT = "mask_video"
+MASK_IMAGE_INPUT = "mask_image"
+MASK_GROW_INPUT = "mask_grow"
+MASK_INPUTS = (MASK_VIDEO_INPUT, MASK_IMAGE_INPUT)
+REGIONAL_EDIT_INPUTS = (SOURCE_VIDEO_INPUT, *MASK_INPUTS, MASK_GROW_INPUT)
+# Patch cells a mask is widened by past what it covers, so the edit's seam
+# lands in regenerated rows rather than against a kept one
+MASK_GROW_DEFAULT = 1
+# A mask pixel at or above this reads as white - regenerate (remove_object's)
+MASK_THRESHOLD = 128
+# The mask as the source block takes it: (frames, height, width) bool, True to
+# regenerate - what Pipeline._with_mask turns either mask argument into
+REGENERATE_MASK = "dw_regenerate_mask"
+SOURCE_BLOCK = "dw_source_latents"
+SOURCE_BEFORE = HOLD_BEFORE
+BLEND_BLOCK = "dw_mask_blend"
+# The loop sub-block the blend follows, inside the core sequence's `denoise`
+BLEND_AFTER = "update"
+SOURCE_ROWS = "dw_source_rows"
+KEEP_ROWS = "dw_keep_rows"
+# The refine block's re-noise of the generated rows, packed - the noise the
+# blend re-noises the kept rows with, so they ride the same trajectory
+REFINE_ROW_NOISE = "dw_refine_row_noise"
+
+
+def _given(arguments, name):
+    return arguments.get(name) is not None
+
+
+def mask_problems(arguments, chained=False):
+    """Why this step's regional edit - `source_video`, `mask_video` or
+    `mask_image`, `mask_grow` - cannot run, as a list; empty when it can or
+    cannot be told yet. The one owner of the argument rules: the static check
+    (dw/hold_audio.py `mask_errors`) and the run-time check before the call
+    (`Pipeline._with_mask`) both ask it. What needs the media itself - its size
+    and frame count against the canvas, an empty mask - is `media_problems`
+    and `Pipeline._with_mask`. `chained` is whether the step is a chain."""
+    masks = [name for name in MASK_INPUTS if _given(arguments, name)]
+    source = _given(arguments, SOURCE_VIDEO_INPUT)
+    grow = arguments.get(MASK_GROW_INPUT)
+    if not masks and not source and grow is None:
+        return []
+    problems = []
+    if len(masks) > 1:
+        problems.append(
+            "pass mask_video or mask_image, not both - mask_image holds one mask "
+            "for every frame"
+        )
+    if masks and not source:
+        problems.append(
+            f"{masks[0]} marks what to regenerate in a 'source_video' - pass the "
+            f"video to edit"
+        )
+    if grow is not None and not masks:
+        problems.append(
+            "mask_grow widens a mask_video or mask_image, and this step passes neither"
+        )
+    elif grow is not None and not _deferred(grow) and (not _is_int(grow) or grow < 0):
+        problems.append(
+            f"mask_grow is a whole number of patch cells, 0 or more, not {grow!r}"
+        )
+    if source and arguments.get(REFINE_STRENGTH_INPUT) is None:
+        problems.append(
+            "source_video is re-denoised from 'refine_strength' - pass one, near "
+            "1.0 to replace what the mask covers, lower to keep its layout"
+        )
+    if source and _given(arguments, "latents"):
+        problems.append("source_video stands in for 'latents' - pass one or the other")
+    if source and chained:
+        problems.append(
+            "a regional edit re-denoises one source_video, and a chained step "
+            "renders several segments - use an unchained step"
+        )
+    return problems
+
+
+def media_problems(name, shape, width, height, num_frames=None):
+    """Why a `source_video` or mask of `shape` - (frames, height, width) -
+    does not fit a `width` x `height` canvas, as a list. `num_frames` is the
+    step's frame count, when it is known; a `mask_image` (one frame) fits any."""
+    problems = []
+    if (width, height) != (shape[2], shape[1]):
+        problems.append(
+            f"{name} is {shape[2]}x{shape[1]}, and the step renders "
+            f"{width}x{height} - they must match"
+        )
+    if num_frames is not None and name != MASK_IMAGE_INPUT and shape[0] != num_frames:
+        problems.append(
+            f"{name} has {shape[0]} frames, and the step renders num_frames="
+            f"{num_frames} - they must match"
+        )
+    return problems
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index a83e6e49..6ca17a1d 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -32,16 +32,24 @@
     attention_slicing_requested,
     place_component,
 )
-from .h3_guides import guides_refusal, prepared_guide
+from .h3_guides import guide_frames_array, guides_refusal, prepared_guide
 from .h3_hold import hold_audio_reference, holds_audio, refines
+from .h3_mask import binarized, edits_regions
 from .h3_rules import (
     GUIDES_INPUT,
     GUIDE_LIMIT,
     HELD_AUDIO_OUTPUT,
     HELD_AUDIO_RATE_OUTPUT,
     HOLD_AUDIO_INPUT,
+    MASK_IMAGE_INPUT,
+    MASK_INPUTS,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
+    REGENERATE_MASK,
+    REGIONAL_EDIT_INPUTS,
+    SOURCE_VIDEO_INPUT,
+    mask_problems,
+    media_problems,
     refine_problems,
 )
 from .h3_tiles import run_tiled_refine
@@ -644,6 +652,7 @@ def _call_pipeline(self, arguments, attn_backend):
         """Call the pipeline with optional attention backend and cache contexts."""
         arguments = self._with_step_callback(arguments)
         self._check_refine(arguments)
+        arguments = self._with_mask(arguments)
         arguments = self._with_held_audio(arguments)
         arguments = self._with_guides(arguments)
         # The load is over and the denoise loop is starting. Pipelines whose
@@ -785,6 +794,81 @@ def _with_guides(self, arguments):
         arguments[GUIDES_INPUT] = prepared
         return arguments
 
+    def _with_mask(self, arguments):
+        """A regional edit's `source_video` as uint8 frames and its mask as the
+        bool frames the H3 source block maps to rows, under `REGENERATE_MASK`
+        (dw/pipeline_processors/h3_mask.py).
+
+        A step without `width`, `height` or `num_frames` renders the source's.
+
+        Raises:
+            ValueError: If this pipeline cannot take a regional edit, the
+                arguments break `mask_problems`, the mask is all black, or the
+                source or mask does not fit the canvas
+        """
+        if all(arguments.get(name) is None for name in REGIONAL_EDIT_INPUTS):
+            return arguments
+        where = f"Step '{self.name}'"
+        if not edits_regions(self.pipeline):
+            raise ValueError(
+                f"{where}: {SOURCE_VIDEO_INPUT} is a MiniMax-H3 argument (t2va, "
+                f"fl2va or ref2va), and {type(self.pipeline).__name__} cannot "
+                f"edit a region"
+            )
+        problems = mask_problems(arguments, chained=self.segment_label is not None)
+        if problems:
+            raise ValueError(f"{where}: {problems[0]}")
+        arguments = dict(arguments)
+        try:
+            source = guide_frames_array(arguments[SOURCE_VIDEO_INPUT])
+        except ValueError as e:
+            raise ValueError(f"{where}: {SOURCE_VIDEO_INPUT} is not a video: {e}")
+        arguments[SOURCE_VIDEO_INPUT] = source
+        frames, height, width = source.shape[:3]
+        for key, value in (
+            ("width", width),
+            ("height", height),
+            ("num_frames", frames),
+        ):
+            if arguments.get(key) is None:
+                arguments[key] = value
+        problems = media_problems(
+            SOURCE_VIDEO_INPUT,
+            source.shape[:3],
+            arguments["width"],
+            arguments["height"],
+            arguments["num_frames"],
+        )
+        name = next((n for n in MASK_INPUTS if arguments.get(n) is not None), None)
+        if name is not None:
+            value = arguments.pop(name)
+            try:
+                if name == MASK_IMAGE_INPUT:
+                    import numpy as np
+
+                    mask = binarized(np.asarray(value.convert("RGB"))[None])
+                else:
+                    mask = binarized(guide_frames_array(value))
+            except (AttributeError, ValueError) as e:
+                kind = "an image" if name == MASK_IMAGE_INPUT else "a video"
+                raise ValueError(f"{where}: {name} is not {kind}: {e}")
+            if not mask.any():
+                raise ValueError(
+                    f"{where}: {name} is all black, so nothing would regenerate "
+                    f"- white marks the region to regenerate"
+                )
+            problems += media_problems(
+                name,
+                mask.shape,
+                arguments["width"],
+                arguments["height"],
+                arguments["num_frames"],
+            )
+            arguments[REGENERATE_MASK] = mask
+        if problems:
+            raise ValueError(f"{where}: {problems[0]}")
+        return arguments
+
     def _check_refine(self, arguments):
         """Refuse a `refine_strength` the H3 refine block cannot run, before the
         call (dw/pipeline_processors/h3_hold.py).

From 218ce7929f765dc9f7b256c847687a815e973221 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 01:44:10 -0500
Subject: [PATCH 014/125] feat(h3): #1077 - regional edit argument rules at
 validate and call

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/hold_audio.py                   | 36 +++++++++++++++++++++++++++++-
 dw/pipeline_processors/h3_rules.py | 19 ++++++++++++++++
 dw/pipeline_processors/pipeline.py |  8 ++++---
 dw/validation.py                   |  5 ++++-
 tests/test_validation.py           |  1 +
 5 files changed, 64 insertions(+), 5 deletions(-)

diff --git a/dw/hold_audio.py b/dw/hold_audio.py
index f9b28fc8..5f97e582 100644
--- a/dw/hold_audio.py
+++ b/dw/hold_audio.py
@@ -25,6 +25,10 @@
 below 2 - the refine schedule is that many points, so one point is no step.
 Those per-argument rules are `h3_rules.refine_problems`, which the run-time
 check calls too; only the H3 test is here.
+
+A regional edit - `source_video` with a `mask_video` or `mask_image` - rides on
+them as well (dw/pipeline_processors/h3_mask.py): its rules are
+`h3_rules.mask_problems`, called here and at the call alike.
 """
 
 from . import references
@@ -34,6 +38,10 @@
     HOLD_AUDIO_INPUT,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
+    REGIONAL_EDIT_INPUTS,
+    edits_region,
+    is_h3_step,
+    mask_problems,
     not_h3,
     refine_problems,
 )
@@ -159,4 +167,30 @@ def refine_strength_errors(workflow_definition, source_indices=None):
     return errors
 
 
-__all__ = ["hold_audio_errors", "refine_strength_errors"]
+def mask_errors(workflow_definition, source_indices=None):
+    """Every regional-edit argument (`source_video`, `mask_video`,
+    `mask_image`, `mask_grow`) refused before the run, as [{path, message}] -
+    each at the path of the first of them the step passes. A step not known
+    to be H3 is a regional edit only with `source_video`: an inpaint
+    pipeline's `mask_image` is its own."""
+    errors = []
+    steps = workflow_definition.get("steps")
+    for _, _, pipeline, source, where in references.iter_steps(
+        steps, source_indices, "pipeline"
+    ):
+        arguments = pipeline.get("arguments")
+        if not isinstance(arguments, dict) or not edits_region(
+            arguments, is_h3_step(pipeline)
+        ):
+            continue
+        given = [n for n in REGIONAL_EDIT_INPUTS if arguments.get(n) is not None]
+        path = render_path(("steps", source, "pipeline", "arguments", given[0]))
+        problems = [not_h3(pipeline, given[0])]
+        problems += mask_problems(arguments, chained=pipeline.get("chain") is not None)
+        for problem in problems:
+            if problem is not None:
+                errors.append({"path": path, "message": f"{problem}{where}"})
+    return errors
+
+
+__all__ = ["hold_audio_errors", "mask_errors", "refine_strength_errors"]
diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index da4f0382..3f01bc4b 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -475,6 +475,25 @@ def guide_end_problem(frame, length, num_frames):
 REFINE_ROW_NOISE = "dw_refine_row_noise"
 
 
+def is_h3_step(pipeline):
+    """Whether a step's pipeline is known to be H3 before the load - its
+    `from_pretrained` `workflow` is one of H3's three."""
+    from_pretrained = pipeline.get(FROM_PRETRAINED_KEY)
+    workflow = (
+        from_pretrained.get(WORKFLOW_KEY) if isinstance(from_pretrained, dict) else None
+    )
+    return isinstance(workflow, str) and workflow in H3_WORKFLOWS
+
+
+def edits_region(arguments, h3):
+    """Whether a step's arguments ask for a regional edit. `mask_image` and
+    `mask_video` are diffusers inpaint arguments too, so on a pipeline not
+    known to be H3 (`h3` false) only `source_video` does."""
+    if _given(arguments, SOURCE_VIDEO_INPUT):
+        return True
+    return h3 and any(_given(arguments, name) for name in REGIONAL_EDIT_INPUTS)
+
+
 def _given(arguments, name):
     return arguments.get(name) is not None
 
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index 6ca17a1d..238dc962 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -46,8 +46,8 @@
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
     REGENERATE_MASK,
-    REGIONAL_EDIT_INPUTS,
     SOURCE_VIDEO_INPUT,
+    edits_region,
     mask_problems,
     media_problems,
     refine_problems,
@@ -806,10 +806,12 @@ def _with_mask(self, arguments):
                 arguments break `mask_problems`, the mask is all black, or the
                 source or mask does not fit the canvas
         """
-        if all(arguments.get(name) is None for name in REGIONAL_EDIT_INPUTS):
+        takes = edits_regions(self.pipeline)
+        # An inpaint pipeline's own mask_image is no regional edit
+        if not edits_region(arguments, takes):
             return arguments
         where = f"Step '{self.name}'"
-        if not edits_regions(self.pipeline):
+        if not takes:
             raise ValueError(
                 f"{where}: {SOURCE_VIDEO_INPUT} is a MiniMax-H3 argument (t2va, "
                 f"fl2va or ref2va), and {type(self.pipeline).__name__} cannot "
diff --git a/dw/validation.py b/dw/validation.py
index bf081258..0fc883a8 100644
--- a/dw/validation.py
+++ b/dw/validation.py
@@ -41,7 +41,7 @@
 from .dissolve_frame_errors import dissolve_frame_errors
 from .for_each import ForEachError, entry_field_warnings
 from .guides import guide_chain_errors, guides_errors
-from .hold_audio import hold_audio_errors, refine_strength_errors
+from .hold_audio import hold_audio_errors, mask_errors, refine_strength_errors
 from .introspection import task_signature_errors
 from .kernel_availability import kernel_availability_errors
 from .library import SubWorkflowNotFound
@@ -350,6 +350,9 @@ def _task_errors(context):
         "refine_strength",
         lambda c: refine_strength_errors(c.expanded, c.source_indices),
     ),
+    # A regional edit on a pipeline that is not H3, a mask with no source, or a
+    # source with no refine_strength, with latents or on a chained step
+    Check("regional_edit", lambda c: mask_errors(c.expanded, c.source_indices)),
     # guides on a pipeline that cannot take them, with references, malformed,
     # or a clip that is no video or runs past the render (dw/guides.py)
     Check(
diff --git a/tests/test_validation.py b/tests/test_validation.py
index 9a344000..0353cdfa 100644
--- a/tests/test_validation.py
+++ b/tests/test_validation.py
@@ -183,6 +183,7 @@ def test_validation_does_not_import_the_workflow_module():
     "video_extensions",
     "hold_audio",
     "refine_strength",
+    "regional_edit",
     "guides",
     "content_types",
     "scalar_results",

From b3563b728567a5d96253c6f335402084e74ecd3a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 01:48:40 -0500
Subject: [PATCH 015/125] feat(h3): #1077 - regional edit tests, guide section
 and architecture row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md   |   2 +-
 docs/WORKFLOW_GUIDE.md |  46 +++
 tests/test_h3_mask.py  | 801 +++++++++++++++++++++++++++++++++++++++++
 tests/test_h3_rules.py |   2 +-
 4 files changed, 849 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_h3_mask.py

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index ab1063ff..75738673 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -112,7 +112,7 @@ one to open.
 | Acceleration warnings | `dw/acceleration_warnings.py`: `acceleration_warnings`, `CACHE_MIN_USEFUL_STEPS`, `CUDA_ONLY_ATTENTION_BACKENDS` (the last entry of `WARNING_CHECKS`) | An acceleration setting that can't pay off (a `first_block`/`mag` cache under `CACHE_MIN_USEFUL_STEPS`, any `taylorseer` cache, `compile.fullgraph` with a cache, a cache on a pipeline class with no transformer or whose transformer lacks `enable_cache()`, a CUDA-only `attention_backend` on a non-CUDA device) is a warning and never a refusal, and an unresolvable value (steps, backend, device) leaves it silent. | `tests/test_validation.py::TestAccelerationWarnings::test_warnings_never_refuse`, `tests/test_validation.py::TestAccelerationWarnings::test_steps_that_resolve_to_nothing_are_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unknown_device_is_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unresolvable_backend_is_silent_on_mps` |
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
-| H3 audio hold, refine, tiled refine and guide layout | Six modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) and `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`), which import diffusers when they load, so the two owners import them only inside `blocks()` and `guide_blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors`, `refine_strength_errors` | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and they are no-ops without `hold_audio` / `refine_strength`. The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
+| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `regenerate_cells` and `keep_rows`, numpy only), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors`, `refine_strength_errors`, `mask_errors` (Check `regional_edit`) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
 | IC-LoRA reference scale | `workflows/templates/ltx2/` | The three conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 7cb3b0e0..d9a3e4a0 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2495,6 +2495,52 @@ refine with no `latents` or no `hold_audio`, a step that is not H3, and a
 To refine a canvas above 1344x768, such as a 1920x1088 plate, see [Refining above 768p in
 tiles](#refining-above-768p-in-tiles).
 
+### H3: regional edit with source_video and a mask
+
+To change part of a take and keep the rest, pass a video as `source_video` on an H3
+`t2va`, `fl2va` or `ref2va` step. It is a path, `asset:`, `output:` or `previous_result:`
+reference to a video, and it stands in for the `latents` of a refine: the step VAE-encodes
+it over the generated rows and re-denoises from `refine_strength`, which is required and
+between 0 and 1 (exclusive). With no mask the whole source is refined.
+
+```json
+{
+    "source_video": "asset:fox_dawn.mp4",
+    "mask_image": "asset:fox_mask.png",
+    "mask_grow": 1,
+    "refine_strength": 0.6,
+    "hold_audio": "asset:fox_dawn.wav",
+    "prompt": "the fox wears a red scarf, same light and motion"
+}
+```
+
+A `mask_video` (one frame per frame) or a `mask_image` (one mask for every frame) limits
+what is regenerated. Pass one, not both. White regenerates and black is kept, binarized
+at luma 128. The mask is max-pooled onto the transformer's patch grid, 16 px times the
+patch size per cell, so any white pixel marks its whole cell, and `mask_grow` widens it by
+that many cells (a whole number, 0 or more, default 1). After every denoise step each
+other row is written back as the source noised to that step's sigma, with the refine's own
+noise, so at the end it is the source latent. The decode still round-trips it through the
+VAE, so kept pixels are near-identical to the source, not bit-identical. A higher
+`refine_strength` replaces what the mask covers, a lower one keeps its layout.
+
+The source and the mask must match the step's `width` x `height`, and a `source_video` or
+`mask_video` its `num_frames`. A step that leaves width, height or `num_frames` out renders
+the source's. An all-black mask is refused, as it would regenerate nothing.
+
+`hold_audio` is still required with `refine_strength`, since the refine holds the
+soundtrack: an audio file (`.wav`, `.mp3`, `.flac`, `.ogg`) or an earlier step's
+audio-carrying result. An `.mp4` path is not accepted, so extract the track first.
+
+Validation and the call both refuse:
+
+- `source_video` with `latents`, or on a chained step;
+- a mask with no `source_video`, or `mask_grow` with no mask;
+- `source_video` with no `refine_strength`;
+- `source_video` on a pipeline that is not H3 (`mask_image` there is left alone, since
+  inpaint pipelines own that name);
+- any of it with `refine_tiles`, which does not combine with a regional edit.
+
 ### Refining above 768p in tiles
 
 H3's refine runs at 1344x768 at most, and `upscale_h3_latents` now reaches 1920x1088 (or
diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
new file mode 100644
index 00000000..ef6b9782
--- /dev/null
+++ b/tests/test_h3_mask.py
@@ -0,0 +1,801 @@
+"""MiniMax-H3 regional edit (#1062/#1077): the mask-to-rows arithmetic, the block
+insertion, the blend, and the argument rules."""
+
+import copy
+import json
+import os
+import tempfile
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+from dw.hold_audio import mask_errors
+from dw.pipeline_processors import h3_mask
+from dw.pipeline_processors.h3_hold import core_denoise_sequences
+from dw.pipeline_processors.h3_mask import (
+    _dilate,
+    _pool,
+    binarized,
+    edits_regions,
+    insert_mask_blocks,
+    keep_rows,
+    regenerate_cells,
+)
+from dw.pipeline_processors.h3_rules import (
+    REGENERATE_MASK,
+    BLEND_BLOCK,
+    KEEP_ROWS,
+    REFINE_ROW_NOISE,
+    SOURCE_BLOCK,
+    SOURCE_ROWS,
+    edits_region,
+    is_h3_step,
+    mask_problems,
+    media_problems,
+    refine_problems,
+)
+from dw.workflow import workflow_from_definition
+
+torch = pytest.importorskip("torch")
+minimax = pytest.importorskip("diffusers.modular_pipelines.minimax_h3")
+from diffusers.modular_pipelines.modular_pipeline import PipelineState  # noqa: E402
+from diffusers.schedulers import MiniMaxH3Scheduler  # noqa: E402
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+WORKFLOWS = ("t2va", "fl2va", "ref2va")
+PATCH = (1, 2, 2)
+
+# A 128x128 pixel canvas is an 8x8 latent, a 4x4 grid of 2x2 patches (32 px a cell)
+SIDE = 128
+LATENT_SIDE = SIDE // 16
+
+
+def pixel_mask(frames, *white):
+    """(frames, SIDE, SIDE) uint8 with each `(frame, y, x)` in `white` set to 255."""
+    mask = np.zeros((frames, SIDE, SIDE), dtype=np.uint8)
+    for frame, y, x in white:
+        mask[frame, y, x] = 255
+    return mask
+
+
+def cells(mask, latent_frames=3, grow=0):
+    return regenerate_cells(
+        binarized(mask), latent_frames, LATENT_SIDE, LATENT_SIDE, PATCH, grow
+    )
+
+
+# 1. Arithmetic
+
+
+class TestBinarized:
+    def test_rgb_thresholds_luma_at_128(self):
+        frame = np.zeros((1, 1, 4, 3), dtype=np.uint8)
+        frame[0, 0, 0] = (255, 255, 255)
+        frame[0, 0, 1] = (128, 128, 128)
+        frame[0, 0, 2] = (127, 127, 127)
+        frame[0, 0, 3] = (0, 0, 0)
+        assert binarized(frame).tolist() == [[[True, True, False, False]]]
+
+    def test_rgb_uses_luma_not_a_channel(self):
+        frame = np.zeros((1, 1, 2, 3), dtype=np.uint8)
+        frame[0, 0, 0] = (255, 0, 0)  # luma 76: below
+        frame[0, 0, 1] = (0, 255, 0)  # luma 150: above
+        assert binarized(frame).tolist() == [[[False, True]]]
+
+    def test_rgba_ignores_alpha(self):
+        frame = np.zeros((1, 1, 1, 4), dtype=np.uint8)
+        frame[0, 0, 0] = (0, 0, 0, 255)
+        assert not binarized(frame).any()
+
+    def test_a_2d_frame_stack_thresholds_directly(self):
+        frames = np.array([[[0, 127, 128, 255]]], dtype=np.uint8)
+        assert binarized(frames).tolist() == [[[False, False, True, True]]]
+
+
+class TestRegenerateCells:
+    def test_the_grid_is_the_patch_row_grid(self):
+        grid = cells(pixel_mask(6))
+        assert grid.shape == (3, 4, 4)
+        assert grid.dtype == bool
+
+    def test_a_corner_pixel_without_grow_marks_one_cell(self):
+        grid = cells(pixel_mask(6, (0, 0, 0)), grow=0)
+        assert grid.sum() == 1
+        assert grid[0, 0, 0]
+
+    def test_the_opposite_corner_lands_in_the_last_cell(self):
+        grid = cells(pixel_mask(6, (5, SIDE - 1, SIDE - 1)), grow=0)
+        assert grid.sum() == 1
+        assert grid[2, 3, 3]
+
+    def test_grow_one_makes_a_clipped_cube_at_a_corner(self):
+        grid = cells(pixel_mask(6, (0, 0, 0)), grow=1)
+        assert grid.sum() == 8
+        assert grid[:2, :2, :2].all()
+
+    def test_grow_in_the_interior_makes_a_full_3x3x3_cube(self):
+        # latent frames 5, pixel frame 2 of 5 -> cell 2; pixel (64, 64) -> cell (2, 2)
+        grid = cells(pixel_mask(5, (2, 64, 64)), latent_frames=5, grow=1)
+        assert grid.shape == (5, 4, 4)
+        assert grid[1:4, 1:4, 1:4].all()
+        assert grid.sum() == 27
+
+    def test_grow_two_widens_further(self):
+        one = cells(pixel_mask(6, (0, 0, 0)), grow=1).sum()
+        two = cells(pixel_mask(6, (0, 0, 0)), grow=2).sum()
+        assert two == 27 and two > one
+
+    def test_a_single_frame_mask_covers_every_latent_frame(self):
+        mask = pixel_mask(1, (0, 0, 0))
+        grid = cells(mask, latent_frames=3, grow=0)
+        assert grid[:, 0, 0].all()
+        assert grid.sum() == 3
+
+    def test_a_single_frame_mask_matches_the_same_mask_repeated(self):
+        one = pixel_mask(1, (0, 70, 100))
+        many = np.repeat(one, 6, axis=0)
+        assert (cells(one, grow=1) == cells(many, grow=1)).all()
+
+    def test_an_empty_mask_regenerates_nothing(self):
+        assert not cells(pixel_mask(6), grow=1).any()
+
+    def test_a_full_mask_regenerates_everything(self):
+        assert cells(np.full((6, SIDE, SIDE), 255, np.uint8), grow=0).all()
+
+    def test_the_flattened_order_is_frame_major_then_row_major(self):
+        # cell (frame 1, row 2, column 3)
+        mask = pixel_mask(6, (2, 2 * 32, 3 * 32))
+        flat = cells(mask, grow=0).reshape(-1)
+        assert flat.sum() == 1
+        assert np.flatnonzero(flat).tolist() == [1 * 16 + 2 * 4 + 3]
+
+    def test_a_patch_time_stride_pools_latent_frames(self):
+        grid = regenerate_cells(
+            binarized(pixel_mask(8, (0, 0, 0))), 4, 8, 8, (2, 2, 2), 0
+        )
+        assert grid.shape == (2, 4, 4)
+        assert grid.sum() == 1
+
+    def test_pool_counts_a_boundary_pixel_toward_both_cells(self):
+        # 5 pixels into 2 cells: cell 0 covers [0, 3), cell 1 covers [2, 5)
+        mask = np.zeros(5, dtype=bool)
+        mask[2] = True
+        assert _pool(mask, 2, 0).tolist() == [True, True]
+
+    def test_pool_to_more_cells_than_pixels_still_covers_each(self):
+        mask = np.array([True, False])
+        assert _pool(mask, 4, 0).tolist() == [True, True, False, False]
+
+    def test_dilate_is_clipped_and_diagonal(self):
+        grid = np.zeros((3, 3), dtype=bool)
+        grid[0, 0] = True
+        assert _dilate(grid, 1).tolist() == [
+            [True, True, False],
+            [True, True, False],
+            [False, False, False],
+        ]
+
+    def test_dilate_zero_is_a_no_op(self):
+        grid = np.zeros((2, 2, 2), dtype=bool)
+        grid[0, 0, 0] = True
+        assert (_dilate(grid, 0) == grid).all()
+
+
+class TestKeepRows:
+    def keep(self, mask, grow=0):
+        return keep_rows(binarized(mask), 3, LATENT_SIDE, LATENT_SIDE, PATCH, grow)
+
+    def test_it_is_the_complement_of_the_regenerated_cells(self):
+        mask = pixel_mask(6, (0, 0, 0), (3, 70, 70))
+        for grow in (0, 1, 2):
+            regenerate = cells(mask, grow=grow).reshape(-1)
+            keep = self.keep(mask, grow)
+            assert keep.shape == (3 * 4 * 4,)
+            assert (keep == ~regenerate).all()
+
+    def test_an_empty_mask_keeps_every_row(self):
+        assert self.keep(pixel_mask(6)).all()
+
+    def test_a_corner_pixel_keeps_all_but_one_row(self):
+        keep = self.keep(pixel_mask(6, (0, 0, 0)))
+        assert (~keep).sum() == 1
+        assert not keep[0]
+
+
+def test_fit_source_frames_pads_with_the_last_frame():
+    from dw.pipeline_processors.h3_mask_steps import fit_source_frames
+
+    frames = np.arange(3, dtype=np.uint8).reshape(3, 1, 1, 1) * np.ones(
+        (3, 2, 2, 3), np.uint8
+    )
+    fitted = fit_source_frames(frames, 5)
+    assert fitted.shape == (5, 2, 2, 3)
+    assert (fitted[:3] == frames).all()
+    assert (fitted[3] == frames[2]).all() and (fitted[4] == frames[2]).all()
+
+
+def test_fit_source_frames_truncates_and_passes_an_exact_fit():
+    from dw.pipeline_processors.h3_mask_steps import fit_source_frames
+
+    frames = np.arange(4, dtype=np.uint8).reshape(4, 1, 1, 1)
+    assert fit_source_frames(frames, 2).reshape(-1).tolist() == [0, 1]
+    assert fit_source_frames(frames, 4).reshape(-1).tolist() == [0, 1, 2, 3]
+
+
+# 2. Insertion
+
+
+@pytest.fixture
+def built():
+    blocks_ = minimax.MiniMaxH3Blocks()
+    result = [("whole", blocks_.init_pipeline())]
+    for name in WORKFLOWS:
+        result.append((name, blocks_.get_workflow(name).init_pipeline()))
+    return result
+
+
+class TestInsertion:
+    def test_blocks_land_before_set_timesteps_and_after_update(self, built):
+        for label, pipeline in built:
+            assert not edits_regions(pipeline), label
+            assert insert_mask_blocks(pipeline) is True, label
+            assert edits_regions(pipeline), label
+            sequences = core_denoise_sequences(pipeline)
+            assert sequences, label
+            for prefix, sequence in sequences:
+                names = list(sequence.sub_blocks)
+                source = names.index(prefix + SOURCE_BLOCK)
+                assert source < names.index(prefix + "set_timesteps"), label
+                loop = list(sequence.sub_blocks[prefix + "denoise"].sub_blocks)
+                assert loop[loop.index("update") + 1] == BLEND_BLOCK, label
+
+    def test_the_source_block_sits_right_before_set_timesteps(self, built):
+        for label, pipeline in built:
+            insert_mask_blocks(pipeline)
+            for prefix, sequence in core_denoise_sequences(pipeline):
+                names = list(sequence.sub_blocks)
+                assert names.index(prefix + SOURCE_BLOCK) + 1 == names.index(
+                    prefix + "set_timesteps"
+                ), label
+
+    def test_the_flat_shape_prefixes_the_source_block(self):
+        pipeline = minimax.MiniMaxH3Blocks().get_workflow("t2va").init_pipeline()
+        insert_mask_blocks(pipeline)
+        assert "denoise." + SOURCE_BLOCK in pipeline._blocks.sub_blocks
+
+    def test_the_nested_shape_does_not_prefix_it(self):
+        pipeline = minimax.MiniMaxH3Blocks().init_pipeline()
+        insert_mask_blocks(pipeline)
+        prefixes = {p for p, _ in core_denoise_sequences(pipeline)}
+        assert prefixes == {""}
+        for _, sequence in core_denoise_sequences(pipeline):
+            assert SOURCE_BLOCK in sequence.sub_blocks
+
+    def test_a_second_call_adds_nothing(self, built):
+        for label, pipeline in built:
+            insert_mask_blocks(pipeline)
+
+            def shape():
+                return [
+                    (list(s.sub_blocks), list(s.sub_blocks[p + "denoise"].sub_blocks))
+                    for p, s in core_denoise_sequences(pipeline)
+                ]
+
+            before = shape()
+            assert insert_mask_blocks(pipeline) is True
+            assert shape() == before, label
+            for names, loop in before:
+                assert sum(SOURCE_BLOCK in n for n in names) == 1
+                assert loop.count(BLEND_BLOCK) == 1
+
+    def test_the_inserted_blocks_are_the_step_classes(self, built):
+        from dw.pipeline_processors.h3_mask_steps import (
+            DwH3MaskBlendStep,
+            DwH3SourceLatentsStep,
+        )
+
+        assert h3_mask.blocks() == (DwH3SourceLatentsStep, DwH3MaskBlendStep)
+        _, pipeline = built[1]
+        insert_mask_blocks(pipeline)
+        for prefix, sequence in core_denoise_sequences(pipeline):
+            assert isinstance(
+                sequence.sub_blocks[prefix + SOURCE_BLOCK], DwH3SourceLatentsStep
+            )
+            loop = sequence.sub_blocks[prefix + "denoise"]
+            assert isinstance(loop.sub_blocks[BLEND_BLOCK], DwH3MaskBlendStep)
+
+    def test_source_video_and_mask_are_pipeline_inputs(self, built):
+        for label, pipeline in built:
+            insert_mask_blocks(pipeline)
+            names = [param.name for param in pipeline._blocks.inputs]
+            assert "source_video" in names, label
+            assert "mask_grow" in names, label
+
+    def test_a_pipeline_without_the_blocks_does_not_edit(self):
+        assert not edits_regions(minimax.MiniMaxH3Blocks().init_pipeline())
+        assert edits_regions(object()) is False
+        assert insert_mask_blocks(object()) is False
+
+    def test_a_sequence_without_update_gets_neither_block(self):
+        pipeline = minimax.MiniMaxH3Blocks().get_workflow("t2va").init_pipeline()
+        loop = pipeline._blocks.sub_blocks["denoise.denoise"]
+        loop.sub_blocks.pop("update")
+        assert insert_mask_blocks(pipeline) is False
+        assert "denoise." + SOURCE_BLOCK not in pipeline._blocks.sub_blocks
+        assert not edits_regions(pipeline)
+
+    def test_every_anchor_is_in_the_installed_diffusers(self):
+        pipeline = minimax.MiniMaxH3Blocks().get_workflow("t2va").init_pipeline()
+        sequence = pipeline._blocks
+        assert "denoise.set_timesteps" in sequence.sub_blocks
+        assert "update" in sequence.sub_blocks["denoise.denoise"].sub_blocks
+
+    def test_components_load_inserts_the_mask_blocks(self):
+        # components.py inserts them where it inserts the hold and the guides
+        import inspect
+
+        from dw.pipeline_processors import components
+
+        source = inspect.getsource(components)
+        assert "insert_mask_blocks(component)" in source
+        assert components.insert_mask_blocks is insert_mask_blocks
+
+
+# 3. The blend
+
+
+ROWS, WIDTH = 6, 4
+
+
+def comps(sigmas):
+    scheduler = MiniMaxH3Scheduler(shift=6.0)
+    scheduler.set_timesteps(sigmas=sigmas)
+    return SimpleNamespace(scheduler=scheduler)
+
+
+def block_state(keep, condition=0, seed=0):
+    generator = torch.Generator().manual_seed(seed)
+    total = condition + ROWS
+    return SimpleNamespace(
+        latents=torch.randn(total, WIDTH, generator=generator),
+        num_condition_video_rows=condition,
+        dw_source_rows=torch.randn(ROWS, WIDTH, generator=generator),
+        dw_keep_rows=keep,
+        dw_refine_row_noise=torch.randn(ROWS, WIDTH, generator=generator),
+    )
+
+
+def blend():
+    from dw.pipeline_processors.h3_mask_steps import DwH3MaskBlendStep
+
+    return DwH3MaskBlendStep()
+
+
+KEEP = torch.tensor([True, False, True, True, False, True])
+
+
+def at_last_step(condition=0):
+    components = comps([0.4, 0.2, 0.0])
+    state = block_state(KEEP, condition)
+    # as `update` leaves it after the final step
+    components.scheduler._step_index = 2
+    return components, state
+
+
+class TestBlend:
+    def test_names_match_the_rules(self):
+        state = block_state(KEEP)
+        assert hasattr(state, SOURCE_ROWS)
+        assert hasattr(state, KEEP_ROWS)
+        assert hasattr(state, REFINE_ROW_NOISE)
+
+    def test_at_sigma_zero_kept_rows_are_the_source_exactly(self):
+        components, state = at_last_step()
+        before = state.latents.clone()
+        blend()(components, state, 1, components.scheduler.timesteps[-1])
+        assert torch.equal(state.latents[KEEP], state.dw_source_rows[KEEP])
+        assert torch.equal(state.latents[~KEEP], before[~KEEP])
+
+    def test_before_the_last_step_kept_rows_are_the_source_noised_to_sigma(self):
+        components = comps([0.4, 0.2, 0.0])
+        components.scheduler._step_index = 1
+        state = block_state(KEEP)
+        blend()(components, state, 0, components.scheduler.timesteps[0])
+        sigma = components.scheduler.sigmas[1]
+        expected = (
+            1 - sigma
+        ) * state.dw_source_rows + sigma * state.dw_refine_row_noise
+        assert torch.allclose(state.latents[KEEP], expected[KEEP], atol=1e-6)
+
+    def test_the_step_index_is_i_plus_one_when_the_scheduler_has_none(self):
+        components = comps([0.4, 0.2, 0.0])
+        assert components.scheduler.step_index is None
+        state = block_state(KEEP)
+        blend()(components, state, 1, components.scheduler.timesteps[1])
+        assert torch.equal(state.latents[KEEP], state.dw_source_rows[KEEP])
+
+    def test_conditioning_rows_are_never_touched(self):
+        components, state = at_last_step(condition=3)
+        before = state.latents.clone()
+        blend()(components, state, 1, components.scheduler.timesteps[-1])
+        assert torch.equal(state.latents[:3], before[:3])
+        assert torch.equal(state.latents[3:][KEEP], state.dw_source_rows[KEEP])
+        assert torch.equal(state.latents[3:][~KEEP], before[3:][~KEEP])
+
+    def test_the_latents_are_written_in_place(self):
+        components, state = at_last_step()
+        tensor = state.latents
+        blend()(components, state, 1, components.scheduler.timesteps[-1])
+        assert state.latents is tensor
+
+    def test_no_keep_is_a_no_op(self):
+        components, state = at_last_step()
+        state.dw_keep_rows = None
+        before = state.latents.clone()
+        out_components, out_state = blend()(
+            components, state, 1, components.scheduler.timesteps[-1]
+        )
+        assert out_components is components and out_state is state
+        assert torch.equal(state.latents, before)
+
+    def test_no_keep_attribute_is_a_no_op(self):
+        components = comps([0.4, 0.0])
+        state = SimpleNamespace(latents=torch.zeros(2, 2))
+        blend()(components, state, 0, components.scheduler.timesteps[0])
+        assert torch.equal(state.latents, torch.zeros(2, 2))
+
+    def test_keep_without_noise_raises(self):
+        components, state = at_last_step()
+        state.dw_refine_row_noise = None
+        with pytest.raises(ValueError, match="refine"):
+            blend()(components, state, 1, components.scheduler.timesteps[-1])
+
+    def test_a_mini_loop_ends_on_the_source_in_kept_rows(self):
+        sigmas = [0.5, 0.35, 0.2, 0.08, 0.0]
+        components = comps(sigmas)
+        scheduler = components.scheduler
+        state = block_state(KEEP, condition=2, seed=3)
+        source, noise = state.dw_source_rows, state.dw_refine_row_noise
+        # what the refine block does: re-noise the generated rows from the source
+        state.latents[2:] = scheduler.scale_noise(source, 1 - sigmas[0], noise)
+        generator = torch.Generator().manual_seed(11)
+
+        for i, t in enumerate(scheduler.timesteps):
+            output = torch.randn(state.latents.shape, generator=generator)
+            state.latents = scheduler.step(output, t, state.latents).prev_sample
+            before_regenerated = state.latents[2:][~KEEP].clone()
+            blend()(components, state, i, t)
+            sigma = scheduler.sigmas[i + 1]
+            kept = state.latents[2:][KEEP]
+            expected = (1 - sigma) * source[KEEP] + sigma * noise[KEEP]
+            assert torch.allclose(kept, expected, atol=1e-6), i
+            assert torch.equal(state.latents[2:][~KEEP], before_regenerated), i
+
+        assert float(scheduler.sigmas[-1]) == 0.0
+        assert torch.equal(state.latents[2:][KEEP], source[KEEP])
+
+
+# 4. The source block
+
+
+class TestSourceBlock:
+    def test_no_source_video_returns_the_state_untouched(self):
+        from dw.pipeline_processors.h3_mask_steps import DwH3SourceLatentsStep
+
+        state = PipelineState()
+        latents = torch.randn(ROWS, WIDTH)
+        state.set("latents", latents)
+        for name in ("height", "width", "num_frames", "num_latent_frames"):
+            state.set(name, 16)
+        state.set("latent_height", 1)
+        state.set("latent_width", 1)
+        components = SimpleNamespace()
+
+        out_components, out_state = DwH3SourceLatentsStep()(components, state)
+
+        assert out_components is components and out_state is state
+        assert state.get("latents") is latents
+        assert state.get(SOURCE_ROWS) is None
+        assert state.get(KEEP_ROWS) is None
+
+
+# 5. Rule refusals
+
+
+def args(**overrides):
+    arguments = {
+        "source_video": "asset:clip",
+        "mask_video": "asset:mask",
+        "mask_grow": 1,
+        "refine_strength": 0.9,
+    }
+    arguments.update(overrides)
+    return {k: v for k, v in arguments.items() if v is not None}
+
+
+def one(problems, name):
+    assert len(problems) == 1, problems
+    assert name in problems[0]
+    return problems[0]
+
+
+class TestMaskProblems:
+    def test_a_valid_set_is_clean(self):
+        assert mask_problems(args()) == []
+        assert mask_problems(args(mask_video=None, mask_image="asset:m")) == []
+        assert mask_problems(args(mask_grow=None)) == []
+        assert mask_problems(args(mask_grow=0)) == []
+
+    def test_a_source_alone_is_clean(self):
+        assert mask_problems(args(mask_video=None, mask_grow=None)) == []
+
+    def test_no_regional_edit_argument_says_nothing(self):
+        assert mask_problems({"prompt": "x"}) == []
+
+    def test_both_masks_are_refused(self):
+        problems = mask_problems(args(mask_image="asset:m"))
+        one(problems, "mask_video")
+        assert "mask_image" in problems[0]
+
+    def test_a_mask_without_source_video_is_refused(self):
+        one(
+            mask_problems(args(source_video=None, refine_strength=None)), "source_video"
+        )
+        one(
+            mask_problems(
+                args(source_video=None, mask_video=None, mask_image="a", mask_grow=None)
+            ),
+            "mask_image",
+        )
+
+    def test_mask_grow_without_a_mask_is_refused(self):
+        one(mask_problems(args(mask_video=None)), "mask_grow")
+
+    @pytest.mark.parametrize("grow", [-1, 1.5, "2", True, 2.0])
+    def test_a_bad_mask_grow_is_refused(self, grow):
+        one(mask_problems(args(mask_grow=grow)), "mask_grow")
+
+    def test_a_deferred_mask_grow_is_not_refused(self):
+        assert mask_problems(args(mask_grow="variable:grow")) == []
+
+    def test_source_video_without_refine_strength_is_refused(self):
+        one(mask_problems(args(refine_strength=None)), "refine_strength")
+
+    def test_source_video_with_latents_is_refused(self):
+        one(mask_problems(args(latents="previous_result:up")), "latents")
+
+    def test_a_chained_step_is_refused(self):
+        problems = mask_problems(args(), chained=True)
+        assert len(problems) == 1
+        assert "chained" in problems[0] or "chain" in problems[0]
+
+    def test_a_chained_step_without_an_edit_says_nothing(self):
+        assert mask_problems({"prompt": "x"}, chained=True) == []
+
+
+class TestOtherRules:
+    def test_refine_no_longer_demands_latents_with_a_source_video(self):
+        arguments = {
+            "refine_strength": 0.9,
+            "hold_audio": "previous_result:base.audio",
+            "num_inference_steps": 5,
+        }
+        assert any("latents" in p for p in refine_problems(arguments))
+        arguments["source_video"] = "asset:clip"
+        assert refine_problems(arguments) == []
+
+    def test_a_size_mismatch_is_reported(self):
+        problems = media_problems("source_video", (9, 64, 96), 128, 128)
+        assert len(problems) == 1
+        assert "96x64" in problems[0] and "128x128" in problems[0]
+
+    def test_a_frame_mismatch_is_reported(self):
+        problems = media_problems("mask_video", (5, 128, 128), 128, 128, 9)
+        assert len(problems) == 1
+        assert "5 frames" in problems[0] and "num_frames=9" in problems[0]
+
+    def test_a_match_is_clean(self):
+        assert media_problems("source_video", (9, 128, 128), 128, 128, 9) == []
+
+    def test_a_mask_image_ignores_frames(self):
+        assert media_problems("mask_image", (1, 128, 128), 128, 128, 9) == []
+
+    def test_a_mask_image_still_checks_size(self):
+        assert len(media_problems("mask_image", (1, 64, 64), 128, 128, 9)) == 1
+
+    def test_no_frame_count_skips_the_frame_check(self):
+        assert media_problems("source_video", (3, 128, 128), 128, 128) == []
+
+    def test_an_inpaint_mask_image_on_a_non_h3_step_is_not_a_regional_edit(self):
+        assert edits_region({"mask_image": "x"}, False) is False
+        assert edits_region({"mask_image": "x"}, True) is True
+        assert edits_region({"mask_video": "x"}, False) is False
+        assert edits_region({"mask_grow": 1}, False) is False
+
+    def test_source_video_always_is(self):
+        assert edits_region({"source_video": "x"}, False) is True
+        assert edits_region({"source_video": "x"}, True) is True
+
+    def test_nothing_given_is_not(self):
+        assert edits_region({"source_video": None, "mask_image": None}, True) is False
+
+    def test_is_h3_step_reads_the_workflow(self):
+        for workflow in WORKFLOWS:
+            assert is_h3_step({"from_pretrained_arguments": {"workflow": workflow}})
+        assert not is_h3_step({"from_pretrained_arguments": {"workflow": "i2v"}})
+        assert not is_h3_step({"from_pretrained_arguments": {}})
+        assert not is_h3_step({})
+
+
+# 5b. Validation end to end
+
+
+def h3_step(workflow="t2va", chain=None, **arguments):
+    pipeline = {
+        "configuration": {"component_type": "ModularPipeline"},
+        "from_pretrained_arguments": {"workflow": workflow},
+        "arguments": arguments,
+    }
+    if chain is not None:
+        pipeline["chain"] = chain
+    return {"name": "video", "pipeline": pipeline}
+
+
+def template(name):
+    with open(os.path.join(ROOT, "workflows", "templates", name)) as f:
+        return json.load(f)
+
+
+def edit_errors(definition):
+    workflow = workflow_from_definition(definition, tempfile.mkdtemp())
+    return [
+        problem
+        for problem in workflow.validation_errors()
+        if any(n in problem["path"] for n in ("source_video", "mask_"))
+    ]
+
+
+def h3_definition(**arguments):
+    definition = copy.deepcopy(template("text-to-image.json"))
+    pipeline = definition["steps"][0]["pipeline"]
+    pipeline["configuration"]["component_type"] = "ModularPipeline"
+    pipeline["from_pretrained_arguments"] = {
+        "model_name": "MiniMaxAI/MiniMax-H3",
+        "workflow": "t2va",
+    }
+    pipeline["arguments"].update(arguments)
+    return definition
+
+
+class TestStaticEdit:
+    def test_a_valid_step_is_clean(self):
+        assert mask_errors({"steps": [h3_step(**args())]}) == []
+
+    def test_a_mask_without_source_is_refused_at_the_mask_path(self):
+        errors = mask_errors(
+            {"steps": [h3_step(mask_video="asset:m", refine_strength=0.9)]}
+        )
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("mask_video")
+        assert "source_video" in errors[0]["message"]
+
+    def test_the_path_is_the_first_argument_the_step_passes(self):
+        errors = mask_errors({"steps": [h3_step(**args(mask_grow=-1))]})
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("source_video")
+        assert "mask_grow" in errors[0]["message"]
+
+    def test_a_chained_step_is_refused(self):
+        errors = mask_errors({"steps": [h3_step(chain={"segments": 2}, **args())]})
+        assert len(errors) == 1
+
+    def test_a_non_h3_workflow_is_refused(self):
+        errors = mask_errors({"steps": [h3_step("i2v", **args())]})
+        assert errors and "i2v" in errors[0]["message"]
+
+    def test_an_h3_step_without_edit_arguments_is_clean(self):
+        assert mask_errors({"steps": [h3_step(prompt="x")]}) == []
+
+    def test_a_non_h3_inpaint_mask_image_is_not_flagged(self):
+        definition = copy.deepcopy(template("inpaint.json"))
+        arguments = definition["steps"][0]["pipeline"]["arguments"]
+        assert "mask_image" in arguments
+        assert mask_errors(definition) == []
+        assert edit_errors(definition) == []
+
+    def test_a_mask_without_source_surfaces_through_the_workflow(self):
+        definition = h3_definition(mask_image="asset:m", refine_strength=0.9)
+        errors = edit_errors(definition)
+        assert errors
+        assert any(e["path"].endswith("mask_image") for e in errors)
+        assert any("source_video" in e["message"] for e in errors)
+
+    def test_the_check_is_registered(self):
+        from dw import validation
+
+        source = open(validation.__file__).read()
+        assert 'Check("regional_edit"' in source
+
+
+# The call: Pipeline._with_mask
+
+
+def editing_step(pipeline, chained=False):
+    return SimpleNamespace(
+        name="video",
+        pipeline=pipeline,
+        base_dir=None,
+        segment_label="segment 1" if chained else None,
+    )
+
+
+@pytest.fixture
+def editing():
+    pipeline = minimax.MiniMaxH3Blocks().get_workflow("t2va").init_pipeline()
+    h3_mask.insert_mask_blocks(pipeline)
+    return pipeline
+
+
+def call_arguments(**overrides):
+    from PIL import Image
+
+    mask = np.zeros((32, 48, 3), dtype=np.uint8)
+    mask[:8, :8] = 255
+    arguments = {
+        "source_video": [Image.new("RGB", (48, 32)) for _ in range(5)],
+        "mask_image": Image.fromarray(mask),
+        "refine_strength": 0.5,
+        "hold_audio": object(),
+    }
+    arguments.update(overrides)
+    return {k: v for k, v in arguments.items() if v is not None}
+
+
+class TestTheCall:
+    def call(self, pipeline, chained=False, **overrides):
+        from dw.pipeline_processors.pipeline import Pipeline
+
+        step = editing_step(pipeline, chained)
+        return Pipeline._with_mask(step, call_arguments(**overrides))
+
+    def test_the_mask_becomes_the_internal_bool_frames(self, editing):
+        arguments = self.call(editing)
+        assert "mask_image" not in arguments
+        mask = arguments[REGENERATE_MASK]
+        assert mask.shape == (1, 32, 48) and mask.dtype == bool
+        assert mask[0, :8, :8].all() and not mask[0, 8:, 8:].any()
+        assert arguments["source_video"].shape == (5, 32, 48, 3)
+
+    def test_an_unsized_step_renders_the_sources_canvas(self, editing):
+        arguments = self.call(editing)
+        assert (arguments["width"], arguments["height"], arguments["num_frames"]) == (
+            48,
+            32,
+            5,
+        )
+
+    def test_a_canvas_mismatch_is_refused(self, editing):
+        with pytest.raises(ValueError, match="must match"):
+            self.call(editing, width=64)
+
+    def test_an_all_black_mask_is_refused(self, editing):
+        from PIL import Image
+
+        with pytest.raises(ValueError, match="all black"):
+            self.call(editing, mask_image=Image.new("RGB", (48, 32)))
+
+    def test_a_chained_step_is_refused(self, editing):
+        with pytest.raises(ValueError, match="chain"):
+            self.call(editing, chained=True)
+
+    def test_a_pipeline_without_the_blocks_refuses_source_video(self):
+        with pytest.raises(ValueError, match="MiniMax-H3"):
+            self.call(object())
+
+    def test_an_inpaint_mask_image_passes_through(self):
+        from dw.pipeline_processors.pipeline import Pipeline
+
+        arguments = {"mask_image": object(), "prompt": "x"}
+        step = editing_step(object())
+        assert Pipeline._with_mask(step, arguments) is arguments
diff --git a/tests/test_h3_rules.py b/tests/test_h3_rules.py
index e272f3fc..d5e547a1 100644
--- a/tests/test_h3_rules.py
+++ b/tests/test_h3_rules.py
@@ -50,7 +50,7 @@ def test_h3_rules_imports_neither_torch_nor_diffusers():
     assert _imported_heavy_modules() == ""
 
 
-@pytest.mark.parametrize("module", ["h3_hold", "h3_guides"])
+@pytest.mark.parametrize("module", ["h3_hold", "h3_guides", "h3_mask"])
 def test_the_block_owners_import_no_diffusers(module):
     # Their blocks are h3_hold_steps and h3_guide_steps, which import diffusers
     # when they load: validation imports h3_guides, so those wait for a block

From a1402074080fa19c0c1ca6461e9b7eb33a45cbe9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 01:58:56 -0500
Subject: [PATCH 016/125] feat(h3): #1077 - mask arithmetic on Pillow, torch
 and scipy

Binarize both masks through Pillow's L conversion, pool with torch's
adaptive_max_pool3d and dilate with scipy's binary_dilation, per the
architecture review's build-vs-buy findings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md               |  2 +-
 dw/pipeline_processors/h3_mask.py  | 77 +++++++++++++++---------------
 dw/pipeline_processors/pipeline.py |  4 +-
 tests/test_h3_mask.py              | 21 ++++++--
 4 files changed, 57 insertions(+), 47 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 75738673..ce306e27 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -112,7 +112,7 @@ one to open.
 | Acceleration warnings | `dw/acceleration_warnings.py`: `acceleration_warnings`, `CACHE_MIN_USEFUL_STEPS`, `CUDA_ONLY_ATTENTION_BACKENDS` (the last entry of `WARNING_CHECKS`) | An acceleration setting that can't pay off (a `first_block`/`mag` cache under `CACHE_MIN_USEFUL_STEPS`, any `taylorseer` cache, `compile.fullgraph` with a cache, a cache on a pipeline class with no transformer or whose transformer lacks `enable_cache()`, a CUDA-only `attention_backend` on a non-CUDA device) is a warning and never a refusal, and an unresolvable value (steps, backend, device) leaves it silent. | `tests/test_validation.py::TestAccelerationWarnings::test_warnings_never_refuse`, `tests/test_validation.py::TestAccelerationWarnings::test_steps_that_resolve_to_nothing_are_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unknown_device_is_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unresolvable_backend_is_silent_on_mps` |
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
-| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `regenerate_cells` and `keep_rows`, numpy only), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors`, `refine_strength_errors`, `mask_errors` (Check `regional_edit`) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
+| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors`, `refine_strength_errors`, `mask_errors` (Check `regional_edit`) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
 | IC-LoRA reference scale | `workflows/templates/ltx2/` | The three conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
diff --git a/dw/pipeline_processors/h3_mask.py b/dw/pipeline_processors/h3_mask.py
index e1b6471d..e602dc36 100644
--- a/dw/pipeline_processors/h3_mask.py
+++ b/dw/pipeline_processors/h3_mask.py
@@ -23,7 +23,8 @@
 
 The refine block (unchanged otherwise) hands its re-noise on as
 `REFINE_ROW_NOISE`. This module puts the blocks in and holds the mask-to-rows
-arithmetic, numpy only; the blocks are dw/pipeline_processors/h3_mask_steps.py,
+arithmetic (numpy, with Pillow's luma conversion, torch's adaptive max pool and
+scipy's dilation imported where they run); the blocks are dw/pipeline_processors/h3_mask_steps.py,
 imported in `blocks()` only, since it imports diffusers when it loads (#790).
 The argument rules shared with validation are
 dw/pipeline_processors/h3_rules.py (`mask_problems`, `media_problems`).
@@ -111,44 +112,46 @@ def edits_regions(pipeline):
     return False
 
 
-def binarized(frames):
-    """`(n, h, w)` bool - True to regenerate - from `(n, h, w, 3|4)` or
-    `(n, h, w)` uint8 mask frames: luma at or above `MASK_THRESHOLD`, the
-    threshold remove_object binarizes its mask at."""
-    frames = np.asarray(frames)
-    if frames.ndim == 4:
-        rgb = frames[..., :3].astype(np.float32)
-        # PIL's L conversion: ITU-R 601-2 luma
-        frames = rgb @ np.array([0.299, 0.587, 0.114], dtype=np.float32)
-    return frames >= MASK_THRESHOLD
-
-
-def _pool(mask, cells, axis):
-    """Max-pool `mask` along `axis` into `cells` cells, cell i covering pixels
-    floor(i * n / cells) up to ceil((i + 1) * n / cells) - so a pixel on a
-    boundary counts toward both cells it touches."""
-    n = mask.shape[axis]
-    pooled = []
-    for i in range(cells):
-        start = i * n // cells
-        end = max(-(-(i + 1) * n // cells), start + 1)
-        pooled.append(
-            np.take(mask, range(start, end), axis=axis).any(axis=axis, keepdims=True)
-        )
-    return np.concatenate(pooled, axis=axis)
+def binarized(mask):
+    """`(n, h, w)` bool - True to regenerate - from a `mask_image` (a PIL image,
+    n = 1) or `(n, h, w, 3|4)` / `(n, h, w)` uint8 `mask_video` frames. Every
+    frame goes through Pillow's L conversion, the one remove_object's
+    `binarize_mask` uses, and is white at or above `MASK_THRESHOLD`, so both
+    masks binarize by one rule."""
+    from PIL import Image
+
+    if isinstance(mask, Image.Image):
+        images = [mask]
+    else:
+        images = [Image.fromarray(frame) for frame in np.asarray(mask)]
+    luma = np.stack([np.asarray(image.convert("L")) for image in images])
+    return luma >= MASK_THRESHOLD
+
+
+def _pool(mask, cells):
+    """`mask` max-pooled onto `cells` (t, h, w) cells by torch's adaptive max
+    pool, cell i of an axis covering pixels floor(i * n / cells) up to
+    ceil((i + 1) * n / cells) - so a pixel on a boundary counts toward both
+    cells it touches. torch is imported here, on first use, so that loading
+    this module (at pipeline load, and by validation) does not."""
+    import torch
+    import torch.nn.functional as F
+
+    grid = torch.from_numpy(np.ascontiguousarray(mask, dtype=np.float32))
+    pooled = F.adaptive_max_pool3d(grid[None, None], cells)[0, 0]
+    return pooled.numpy() > 0
 
 
 def _dilate(grid, grow):
     """`grid` widened by `grow` cells along every axis, diagonals included (a
-    cube structuring element), clipped at the edges."""
-    for _ in range(grow):
-        for axis in range(grid.ndim):
-            cells = np.swapaxes(grid, 0, axis)
-            grown = cells.copy()
-            grown[1:] |= cells[:-1]
-            grown[:-1] |= cells[1:]
-            grid = np.swapaxes(grown, 0, axis)
-    return grid
+    cube structuring element), clipped at the edges. scipy reads 0 iterations
+    as "until nothing changes", so `grow == 0` returns the grid as it is."""
+    if grow == 0:
+        return grid
+    from scipy.ndimage import binary_dilation
+
+    structure = np.ones((3,) * grid.ndim, dtype=bool)
+    return binary_dilation(grid, structure=structure, iterations=grow)
 
 
 def regenerate_cells(
@@ -172,9 +175,7 @@ def regenerate_cells(
     grid = np.asarray(mask, dtype=bool)
     if grid.shape[0] == 1:
         grid = np.repeat(grid, cells[0], axis=0)
-    for axis, count in enumerate(cells):
-        grid = _pool(grid, count, axis)
-    return _dilate(grid, grow)
+    return _dilate(_pool(grid, cells), grow)
 
 
 def keep_rows(mask, latent_frames, latent_height, latent_width, patch_size, grow):
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index 238dc962..fa949924 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -846,9 +846,7 @@ def _with_mask(self, arguments):
             value = arguments.pop(name)
             try:
                 if name == MASK_IMAGE_INPUT:
-                    import numpy as np
-
-                    mask = binarized(np.asarray(value.convert("RGB"))[None])
+                    mask = binarized(value)
                 else:
                     mask = binarized(guide_frames_array(value))
             except (AttributeError, ValueError) as e:
diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
index ef6b9782..0e3dc8db 100644
--- a/tests/test_h3_mask.py
+++ b/tests/test_h3_mask.py
@@ -88,6 +88,17 @@ def test_rgba_ignores_alpha(self):
         frame[0, 0, 0] = (0, 0, 0, 255)
         assert not binarized(frame).any()
 
+    def test_a_mask_image_binarizes_as_its_frame_does(self):
+        from PIL import Image
+
+        frame = np.zeros((1, 2, 8, 3), dtype=np.uint8)
+        frame[0, :, :4] = (255, 255, 255)
+        frame[0, :, 4] = (128, 128, 128)
+        frame[0, :, 5] = (0, 255, 0)
+        image = Image.fromarray(frame[0])
+        assert binarized(image).tolist() == binarized(frame).tolist()
+        assert binarized(image)[0, 0].tolist() == [True] * 6 + [False] * 2
+
     def test_a_2d_frame_stack_thresholds_directly(self):
         frames = np.array([[[0, 127, 128, 255]]], dtype=np.uint8)
         assert binarized(frames).tolist() == [[[False, False, True, True]]]
@@ -159,13 +170,13 @@ def test_a_patch_time_stride_pools_latent_frames(self):
 
     def test_pool_counts_a_boundary_pixel_toward_both_cells(self):
         # 5 pixels into 2 cells: cell 0 covers [0, 3), cell 1 covers [2, 5)
-        mask = np.zeros(5, dtype=bool)
-        mask[2] = True
-        assert _pool(mask, 2, 0).tolist() == [True, True]
+        mask = np.zeros((1, 1, 5), dtype=bool)
+        mask[0, 0, 2] = True
+        assert _pool(mask, (1, 1, 2)).tolist() == [[[True, True]]]
 
     def test_pool_to_more_cells_than_pixels_still_covers_each(self):
-        mask = np.array([True, False])
-        assert _pool(mask, 4, 0).tolist() == [True, True, False, False]
+        mask = np.array([[[True, False]]])
+        assert _pool(mask, (1, 1, 4)).tolist() == [[[True, True, False, False]]]
 
     def test_dilate_is_clipped_and_diagonal(self):
         grid = np.zeros((3, 3), dtype=bool)

From 0b1787a4fdd710830b96063d5a51d2fca52d0fd6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 02:17:56 -0500
Subject: [PATCH 017/125] feat(h3): #1077 - hold the source mp4's track,
 strength 1.0 with a source, media checks at validate

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                    |   2 +-
 docs/WORKFLOW_GUIDE.md                  |  27 +++-
 dw/hold_audio.py                        | 200 ++++++++++++++++++++---
 dw/media.py                             |   8 +
 dw/pipeline_processors/h3_hold.py       |  29 +++-
 dw/pipeline_processors/h3_hold_steps.py |  12 +-
 dw/pipeline_processors/h3_rules.py      |  15 +-
 dw/validation.py                        |  12 +-
 tests/test_h3_hold_audio.py             |  57 ++++++-
 tests/test_h3_mask.py                   | 205 +++++++++++++++++++++++-
 10 files changed, 519 insertions(+), 48 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index ce306e27..eb666821 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -112,7 +112,7 @@ one to open.
 | Acceleration warnings | `dw/acceleration_warnings.py`: `acceleration_warnings`, `CACHE_MIN_USEFUL_STEPS`, `CUDA_ONLY_ATTENTION_BACKENDS` (the last entry of `WARNING_CHECKS`) | An acceleration setting that can't pay off (a `first_block`/`mag` cache under `CACHE_MIN_USEFUL_STEPS`, any `taylorseer` cache, `compile.fullgraph` with a cache, a cache on a pipeline class with no transformer or whose transformer lacks `enable_cache()`, a CUDA-only `attention_backend` on a non-CUDA device) is a warning and never a refusal, and an unresolvable value (steps, backend, device) leaves it silent. | `tests/test_validation.py::TestAccelerationWarnings::test_warnings_never_refuse`, `tests/test_validation.py::TestAccelerationWarnings::test_steps_that_resolve_to_nothing_are_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unknown_device_is_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unresolvable_backend_is_silent_on_mps` |
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
-| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors`, `refine_strength_errors`, `mask_errors` (Check `regional_edit`) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
+| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
 | IC-LoRA reference scale | `workflows/templates/ltx2/` | The three conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index d9a3e4a0..a4d7d099 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2488,7 +2488,8 @@ scheduler's `shift`, so a refine runs `num_inference_steps - 1` denoise evaluati
 sets where it starts, not how many steps run: a higher strength moves the picture further
 from the upscaled take, a lower one stays closer to it.
 
-Validation refuses a `refine_strength` that is not a number between 0 and 1 (exclusive), a
+Validation refuses a `refine_strength` that is not a number between 0 and 1 (exclusive;
+a [regional edit](#h3-regional-edit-with-source_video-and-a-mask) also takes 1.0), a
 refine with no `latents` or no `hold_audio`, a step that is not H3, and a
 `num_inference_steps` below 2.
 
@@ -2501,7 +2502,9 @@ To change part of a take and keep the rest, pass a video as `source_video` on an
 `t2va`, `fl2va` or `ref2va` step. It is a path, `asset:`, `output:` or `previous_result:`
 reference to a video, and it stands in for the `latents` of a refine: the step VAE-encodes
 it over the generated rows and re-denoises from `refine_strength`, which is required and
-between 0 and 1 (exclusive). With no mask the whole source is refined.
+in (0, 1]: 1.0 regenerates the masked region from pure noise, about 0.4 reworks it lightly
+and keeps its layout. (Without a `source_video` the refine's range stays (0, 1).) With no
+mask the whole source is refined.
 
 ```json
 {
@@ -2509,7 +2512,7 @@ between 0 and 1 (exclusive). With no mask the whole source is refined.
     "mask_image": "asset:fox_mask.png",
     "mask_grow": 1,
     "refine_strength": 0.6,
-    "hold_audio": "asset:fox_dawn.wav",
+    "hold_audio": "asset:fox_dawn.mp4",
     "prompt": "the fox wears a red scarf, same light and motion"
 }
 ```
@@ -2518,7 +2521,9 @@ A `mask_video` (one frame per frame) or a `mask_image` (one mask for every frame
 what is regenerated. Pass one, not both. White regenerates and black is kept, binarized
 at luma 128. The mask is max-pooled onto the transformer's patch grid, 16 px times the
 patch size per cell, so any white pixel marks its whole cell, and `mask_grow` widens it by
-that many cells (a whole number, 0 or more, default 1). After every denoise step each
+that many cells (a whole number, 0 or more, default 1). In time the grain is the latent
+frame: about 4 pixel frames each (3.4 - every 17 frames encode to 5 latent frames), times
+the patch's time size, so a `mask_video` switching on or off mid-cell marks the whole cell. After every denoise step each
 other row is written back as the source noised to that step's sigma, with the refine's own
 noise, so at the end it is the source latent. The decode still round-trips it through the
 VAE, so kept pixels are near-identical to the source, not bit-identical. A higher
@@ -2526,17 +2531,23 @@ VAE, so kept pixels are near-identical to the source, not bit-identical. A highe
 
 The source and the mask must match the step's `width` x `height`, and a `source_video` or
 `mask_video` its `num_frames`. A step that leaves width, height or `num_frames` out renders
-the source's. An all-black mask is refused, as it would regenerate nothing.
+the source's. An all-black mask is refused, as it would regenerate nothing. Validation reads
+a source or mask that resolves already (a path, `asset:` or `output:`) and refuses a size,
+frame count or empty mask there, the way it reads guide videos; a `previous_result:` is
+checked at the call.
 
 `hold_audio` is still required with `refine_strength`, since the refine holds the
-soundtrack: an audio file (`.wav`, `.mp3`, `.flac`, `.ogg`) or an earlier step's
-audio-carrying result. An `.mp4` path is not accepted, so extract the track first.
+soundtrack. It is normally the `source_video` itself: a video path (`.mp4`, `.mov`, `.mkv`,
+`.webm`, `.avi`) is held by its own soundtrack, so the edit keeps the take's audio. A video
+with no audio stream is refused. An audio file (`.wav`, `.mp3`, `.flac`, `.ogg`) or an
+earlier step's audio-carrying result works too.
 
 Validation and the call both refuse:
 
 - `source_video` with `latents`, or on a chained step;
+- both mask kinds, `mask_video` and `mask_image`, on one step;
 - a mask with no `source_video`, or `mask_grow` with no mask;
-- `source_video` with no `refine_strength`;
+- `source_video` with no `refine_strength`, or one outside (0, 1];
 - `source_video` on a pipeline that is not H3 (`mask_image` there is left alone, since
   inpaint pipelines own that name);
 - any of it with `refine_tiles`, which does not combine with a regional edit.
diff --git a/dw/hold_audio.py b/dw/hold_audio.py
index 5f97e582..313c13b9 100644
--- a/dw/hold_audio.py
+++ b/dw/hold_audio.py
@@ -10,17 +10,21 @@
   `from_pretrained` `workflow` is not one of H3's three (`t2va`, `fl2va`,
   `ref2va`). A modular pipeline loaded with no `workflow` is left to the
   run-time check, which asks the loaded block graph itself;
-- a literal path, or an `asset:`/`output:` reference, whose name carries no
-  audio extension (a bare word like `hello` among them), any value that is not
-  a string or a mapping (a number), and any `{"media_type": ...}` reference -
-  those load an image or a video.
+- a literal path, or an `asset:`/`output:` reference, whose name carries
+  neither an audio nor a video extension (a bare word like `hello` among them),
+  any value that is not a string or a mapping (a number), and any
+  `{"media_type": ...}` reference - those load an image or video frames. A
+  video file is held by its own soundtrack (a regional edit's `source_video`
+  is the usual one), so one that resolves now and has no audio stream is
+  refused too.
 
 A `previous_result:` names no file yet and is left to the run-time check, the
 same as `dw/video_extensions.py` leaves it.
 
 `refine_strength`, the refine that re-denoises an upscaled take from a low sigma,
 rides on the same blocks and is checked beside it: refused on a step that is not
-H3, when it is not a number in (0, 1), when the step passes no `latents` to refine
+H3, when it is not a number in (0, 1) - (0, 1] with a `source_video` - when the
+step passes no `latents` to refine
 or no `hold_audio` to keep its soundtrack, and when `num_inference_steps` is
 below 2 - the refine schedule is that many points, so one point is no step.
 Those per-argument rules are `h3_rules.refine_problems`, which the run-time
@@ -28,7 +32,11 @@
 
 A regional edit - `source_video` with a `mask_video` or `mask_image` - rides on
 them as well (dw/pipeline_processors/h3_mask.py): its rules are
-`h3_rules.mask_problems`, called here and at the call alike.
+`h3_rules.mask_problems`, called here and at the call alike. Where the files
+resolve now, they are read here too, the way the guide-frame check reads its
+videos (`dw/guides.py`): the source's and the mask's size and frame count
+against the canvas (`h3_rules.media_problems`, which `Pipeline._with_mask` asks
+again at the call), and a mask with no white pixel in it.
 """
 
 from . import references
@@ -36,16 +44,24 @@
 from .for_each import render_path
 from .pipeline_processors.h3_rules import (
     HOLD_AUDIO_INPUT,
+    MASK_IMAGE_INPUT,
+    MASK_INPUTS,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
     REGIONAL_EDIT_INPUTS,
+    SOURCE_VIDEO_INPUT,
     edits_region,
     is_h3_step,
     mask_problems,
+    media_problems,
     not_h3,
     refine_problems,
 )
-from .security import ALLOWED_AUDIO_EXTENSIONS
+from .probe_paths import resolve_probe_path
+from .security import ALLOWED_AUDIO_EXTENSIONS, ALLOWED_VIDEO_EXTENSIONS
+
+# A video is held by its own soundtrack - a regional edit's source_video
+HOLDABLE_EXTENSIONS = ALLOWED_AUDIO_EXTENSIONS | ALLOWED_VIDEO_EXTENSIONS
 
 UPSCALE_COMMAND = "upscale_h3_latents"
 
@@ -78,21 +94,44 @@ def _not_audio(value):
     # A name with no extension - a bare word like 'hello' - is refused at the
     # call too, which checks the extension before it opens anything
     _, dot, ext = value.rpartition(".")
-    if dot and ext and "/" not in ext and f".{ext.lower()}" in ALLOWED_AUDIO_EXTENSIONS:
+    if dot and ext and "/" not in ext and f".{ext.lower()}" in HOLDABLE_EXTENSIONS:
         return None
     return (
         f"hold_audio holds a soundtrack, and '{value}' is not an audio file "
-        f"({', '.join(sorted(ALLOWED_AUDIO_EXTENSIONS))})"
+        f"({', '.join(sorted(ALLOWED_AUDIO_EXTENSIONS))}) or a video whose "
+        f"track it takes ({', '.join(sorted(ALLOWED_VIDEO_EXTENSIONS))})"
     )
 
 
-def hold_audio_errors(workflow_definition, source_indices=None):
+def _silent_video(value, base_dir, probe):
+    """Why this `hold_audio` video holds nothing - it resolves now and has no
+    audio stream - or None, including when it cannot be told yet."""
+    if probe is None or not isinstance(value, str):
+        return None
+    _, dot, ext = value.rpartition(".")
+    if f".{ext.lower()}" not in ALLOWED_VIDEO_EXTENSIONS:
+        return None
+    path = resolve_probe_path(value, base_dir, HOLD_AUDIO_INPUT)
+    info = probe(path) if path is not None else None
+    if isinstance(info, dict) and not info.get("sample_rate"):
+        return (
+            f"hold_audio takes the soundtrack of '{value}', and it has no audio "
+            f"stream - pass a video with a soundtrack, or the audio file itself"
+        )
+    return None
+
+
+def hold_audio_errors(
+    workflow_definition, source_indices=None, base_dir=None, probe=None
+):
     """Every `hold_audio` argument refused before the run, as [{path, message}].
 
     Walks the substituted, expanded definition, the convention
     `video_extension_errors` follows: `source_indices` maps an expanded step
     back to the one the author wrote, and a path inside a `for_each` member
-    names the member.
+    names the member. `probe` (`ValidationContext.probe`) reads a video that
+    resolves against `base_dir` for its audio stream; without it a video is
+    left to the run.
     """
     errors = []
     for _, _, pipeline, source, where in references.iter_steps(
@@ -102,7 +141,9 @@ def hold_audio_errors(workflow_definition, source_indices=None):
         if not isinstance(arguments, dict) or arguments.get(HOLD_AUDIO_INPUT) is None:
             continue
         path = render_path(("steps", source, "pipeline", "arguments", HOLD_AUDIO_INPUT))
-        for problem in (not_h3(pipeline), _not_audio(arguments[HOLD_AUDIO_INPUT])):
+        value = arguments[HOLD_AUDIO_INPUT]
+        problem = _not_audio(value) or _silent_video(value, base_dir, probe)
+        for problem in (not_h3(pipeline), problem):
             if problem is not None:
                 errors.append({"path": path, "message": f"{problem}{where}"})
     return errors
@@ -167,12 +208,126 @@ def refine_strength_errors(workflow_definition, source_indices=None):
     return errors
 
 
-def mask_errors(workflow_definition, source_indices=None):
+def _static(value):
+    """`value` when it is a literal whole number, else None."""
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _mask_image_shape(path):
+    """(1, height, width) and whether any pixel is white, for the mask image
+    at `path` (already confined by `resolve_probe_path`), or None when it is
+    no image."""
+    from PIL import Image, UnidentifiedImageError
+
+    from .pipeline_processors.h3_mask import binarized
+
+    try:
+        with Image.open(path) as image:
+            mask = binarized(image)
+    except (OSError, UnidentifiedImageError, ValueError):
+        return None
+    return mask.shape, bool(mask.any())
+
+
+def _mask_video_white(path):
+    """Whether any frame of the mask video at `path` has a white pixel,
+    decoded until the first one does; None when it cannot be decoded."""
+    import av
+
+    from .media import iter_rgb_frames
+    from .pipeline_processors.h3_mask import binarized
+
+    try:
+        for frame in iter_rgb_frames(path):
+            if binarized(frame[None]).any():
+                return True
+    except (av.error.FFmpegError, OSError, ValueError, IndexError):
+        return None
+    return False
+
+
+def _video_shape(name, value, base_dir, probe):
+    """(problem, (frames, height, width), path) for a regional edit's video
+    argument: why it is no video, its shape when the probe reads one, and the
+    confined path it resolved to; Nones for what cannot be told yet."""
+    path = resolve_probe_path(value, base_dir, name)
+    info = probe(path) if path is not None else None
+    if not isinstance(info, dict):
+        return None, None, None
+    if info.get("kind") != "video":
+        return (
+            f"{name} must be a video, and this is {info.get('kind') or 'unreadable'}",
+            None,
+            path,
+        )
+    frames, height, width = (info.get(k) for k in ("frame_count", "height", "width"))
+    if not all(isinstance(v, int) and v > 0 for v in (frames, height, width)):
+        return None, None, path
+    return None, (frames, height, width), path
+
+
+def _media_problems(arguments, base_dir, probe):
+    """[(argument, problem)] for the regional edit's files that resolve now:
+    the source's and the mask's size and frame count against the canvas - a
+    canvas key the step leaves out is the source's, as at the call - and a
+    mask with no white pixel."""
+    if probe is None:
+        return []
+    problems = []
+    width, height, num_frames = (
+        arguments.get(k) for k in ("width", "height", "num_frames")
+    )
+    problem, shape, _ = _video_shape(
+        SOURCE_VIDEO_INPUT, arguments.get(SOURCE_VIDEO_INPUT), base_dir, probe
+    )
+    if problem:
+        problems.append((SOURCE_VIDEO_INPUT, problem))
+    if shape is not None:
+        width = shape[2] if width is None else width
+        height = shape[1] if height is None else height
+        num_frames = shape[0] if num_frames is None else num_frames
+    canvas = (_static(width), _static(height), _static(num_frames))
+    if shape is not None and None not in canvas[:2]:
+        problems += [
+            (SOURCE_VIDEO_INPUT, p)
+            for p in media_problems(SOURCE_VIDEO_INPUT, shape, *canvas)
+        ]
+    name = next((n for n in MASK_INPUTS if arguments.get(n) is not None), None)
+    if name is None:
+        return problems
+    white = None
+    if name == MASK_IMAGE_INPUT:
+        path = resolve_probe_path(arguments[name], base_dir, name)
+        read = _mask_image_shape(path) if path is not None else None
+        mask_shape, white = read if read is not None else (None, None)
+    else:
+        problem, mask_shape, path = _video_shape(name, arguments[name], base_dir, probe)
+        if problem:
+            problems.append((name, problem))
+        elif path is not None:
+            white = _mask_video_white(path)
+    if white is False:
+        problems.append(
+            (
+                name,
+                f"{name} is all black, so nothing would regenerate - white marks "
+                f"the region to regenerate",
+            )
+        )
+    if mask_shape is not None and None not in canvas[:2]:
+        problems += [(name, p) for p in media_problems(name, mask_shape, *canvas)]
+    return problems
+
+
+def mask_errors(workflow_definition, source_indices=None, base_dir=None, probe=None):
     """Every regional-edit argument (`source_video`, `mask_video`,
-    `mask_image`, `mask_grow`) refused before the run, as [{path, message}] -
-    each at the path of the first of them the step passes. A step not known
-    to be H3 is a regional edit only with `source_video`: an inpaint
-    pipeline's `mask_image` is its own."""
+    `mask_image`, `mask_grow`) refused before the run, as [{path, message}].
+    An argument rule is at the path of the first of them the step passes; a
+    problem with a file - its size, frame count, or a mask with no white - is
+    at that file's argument. A step not known to be H3 is a regional edit
+    only with `source_video`: an inpaint pipeline's `mask_image` is its own.
+    `probe` (`ValidationContext.probe`) reads the files that resolve against
+    `base_dir`; without it only the argument rules are checked."""
     errors = []
     steps = workflow_definition.get("steps")
     for _, _, pipeline, source, where in references.iter_steps(
@@ -184,11 +339,14 @@ def mask_errors(workflow_definition, source_indices=None):
         ):
             continue
         given = [n for n in REGIONAL_EDIT_INPUTS if arguments.get(n) is not None]
-        path = render_path(("steps", source, "pipeline", "arguments", given[0]))
-        problems = [not_h3(pipeline, given[0])]
-        problems += mask_problems(arguments, chained=pipeline.get("chain") is not None)
-        for problem in problems:
+        problems = [(given[0], not_h3(pipeline, given[0]))]
+        rules = mask_problems(arguments, chained=pipeline.get("chain") is not None)
+        problems += [(given[0], problem) for problem in rules]
+        if not rules:
+            problems += _media_problems(arguments, base_dir, probe)
+        for name, problem in problems:
             if problem is not None:
+                path = render_path(("steps", source, "pipeline", "arguments", name))
                 errors.append({"path": path, "message": f"{problem}{where}"})
     return errors
 
diff --git a/dw/media.py b/dw/media.py
index a5d90c4d..a622f2cf 100644
--- a/dw/media.py
+++ b/dw/media.py
@@ -614,6 +614,14 @@ def decode_rgb_frames(path):
         ]
 
 
+def iter_rgb_frames(path):
+    """The picture frames of `path` as (height, width, 3) uint8 arrays, one at
+    a time, so a caller can stop at the frame it is looking for."""
+    with av.open(path) as container:
+        for frame in container.decode(_threaded(container.streams.video[0])):
+            yield frame.to_ndarray(format="rgb24")
+
+
 def read_thumbnails_and_track(
     path, thumb_width, thumb_height, look=None, look_width=128, look_height=72
 ):
diff --git a/dw/pipeline_processors/h3_hold.py b/dw/pipeline_processors/h3_hold.py
index 3bd8374f..eb275b27 100644
--- a/dw/pipeline_processors/h3_hold.py
+++ b/dw/pipeline_processors/h3_hold.py
@@ -188,7 +188,9 @@ def hold_audio_reference(value, base_dir=None):
     """A `hold_audio` argument as the MiniMaxH3AudioReference the hold block takes.
 
     Whatever an argument can hold audio as: a file path (an `asset:` or `output:`
-    reference arrives resolved to one), a step's artifact - an AudioTrack, an
+    reference arrives resolved to one) - an audio file, or a video whose
+    soundtrack is held, a regional edit's `source_video` the usual one - a
+    step's artifact - an AudioTrack, an
     AudioVideo, a bare waveform - or a reference already built. A path or URL goes
     through the location owner (dw/locations.py) before anything opens it, the
     run-time half of the check validation makes on the same argument.
@@ -199,7 +201,7 @@ def hold_audio_reference(value, base_dir=None):
             file's directory
 
     Raises:
-        ValueError: If the value is not audio
+        ValueError: If the value is not audio, or a video with no audio stream
         SecurityError: If the path or URL is outside what the workflow may read
     """
     from ..argument_media import local_media_file
@@ -207,10 +209,14 @@ def hold_audio_reference(value, base_dir=None):
     from ..locations import is_http_url, validate_media_path, validate_media_url
     from ..security import (
         ALLOWED_AUDIO_EXTENSIONS,
+        ALLOWED_VIDEO_EXTENSIONS,
         InvalidInputError,
         validate_file_extension,
     )
 
+    # A video is held by its own soundtrack
+    holdable = ALLOWED_AUDIO_EXTENSIONS | ALLOWED_VIDEO_EXTENSIONS
+
     from diffusers.modular_pipelines.minimax_h3.references import (
         MiniMaxH3AudioReference,
     )
@@ -219,11 +225,12 @@ def hold_audio_reference(value, base_dir=None):
         return value
     if isinstance(value, str):
         try:
-            validate_file_extension(value, ALLOWED_AUDIO_EXTENSIONS)
+            validate_file_extension(value, holdable)
         except InvalidInputError as error:
             raise ValueError(
-                f"hold_audio holds a soundtrack, and '{value}' is not an audio file "
-                f"({', '.join(sorted(ALLOWED_AUDIO_EXTENSIONS))})"
+                f"hold_audio holds a soundtrack, and '{value}' is not an audio "
+                f"file ({', '.join(sorted(ALLOWED_AUDIO_EXTENSIONS))}) or a video "
+                f"whose track it takes ({', '.join(sorted(ALLOWED_VIDEO_EXTENSIONS))})"
             ) from error
         if is_http_url(value):
             # Checked again, hop by hop, by the fetch below
@@ -231,12 +238,18 @@ def hold_audio_reference(value, base_dir=None):
         else:
             location = validate_file_extension(
                 validate_media_path(value, base_dir, "hold_audio"),
-                ALLOWED_AUDIO_EXTENSIONS,
+                holdable,
             )
         # from_file given a URL downloads it with requests itself, outside
-        # the host policy; given a path it only decodes
+        # the host policy; given a path it only decodes - a video's soundtrack
         with local_media_file(location, "hold_audio") as path:
-            return MiniMaxH3AudioReference.from_file(path)
+            try:
+                return MiniMaxH3AudioReference.from_file(path)
+            except ValueError as error:
+                raise ValueError(
+                    f"hold_audio takes the soundtrack of '{value}', and it has none "
+                    f"to take: {error}"
+                ) from error
     try:
         return MiniMaxH3AudioReference(
             **media_arguments(MiniMaxH3AudioReference, value)
diff --git a/dw/pipeline_processors/h3_hold_steps.py b/dw/pipeline_processors/h3_hold_steps.py
index 08b67ced..83ac93b7 100644
--- a/dw/pipeline_processors/h3_hold_steps.py
+++ b/dw/pipeline_processors/h3_hold_steps.py
@@ -67,12 +67,15 @@ def refine_sigmas(strength, num_points, shift):
     full grid, which `set_timesteps(sigmas=...)` does not apply itself.
 
     Raises:
-        ValueError: If `strength` is not in (0, 1) or `num_points` is below 2
+        ValueError: If `strength` is not in (0, 1] or `num_points` is below 2.
+            At 1 the schedule is the stock full grid - a regional edit that
+            regenerates its region from noise; which callers may pass 1 is
+            `h3_rules.refine_problems`'s rule
     """
     if isinstance(strength, bool) or not isinstance(strength, (int, float)):
         raise ValueError(f"refine_strength must be a number, got {strength!r}")
-    if not 0 < strength < 1:
-        raise ValueError(f"refine_strength must be in (0, 1), got {strength}")
+    if not 0 < strength <= 1:
+        raise ValueError(f"refine_strength must be in (0, 1], got {strength}")
     if num_points is None or num_points < 2:
         raise ValueError(
             f"refine_strength needs num_inference_steps of 2 or more, got {num_points}"
@@ -306,7 +309,8 @@ def inputs(self):
                 default=None,
                 description=(
                     "The sigma in (0, 1) to re-denoise a passed `latents` from - an upscaled take refined at "
-                    "about 0.2. Runs num_inference_steps - 1 evaluations."
+                    "about 0.2 - or in (0, 1] for a `source_video` regional edit, where 1.0 regenerates the "
+                    "masked region from noise. Runs num_inference_steps - 1 evaluations."
                 ),
             ),
             InputParam(
diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index 3f01bc4b..dfcf7004 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -42,7 +42,9 @@ def refine_problems(arguments, canvas=None):
     """Why this step's `refine_strength` and `refine_tiles` cannot run, as a
     list - empty when they can, or cannot be told yet. The one owner of the
     per-argument rules: the static check (dw/hold_audio.py) and the run-time
-    check before the call (`Pipeline._check_refine`) both ask it. A tile
+    check before the call (`Pipeline._check_refine`) both ask it. The sigma
+    is in (0, 1), or (0, 1] with a `source_video`: a regional edit at 1.0
+    regenerates its region from pure noise. A tile
     problem's message starts with `refine_tiles`. `canvas` is the (width,
     height) the static check read from the upscale step `latents` names, when
     it could; at run time the `latents` tensor gives it."""
@@ -59,10 +61,19 @@ def refine_problems(arguments, canvas=None):
         problems.append(
             f"refine_strength is a number in (0, 1), and {strength!r} is not a number"
         )
+    elif arguments.get(SOURCE_VIDEO_INPUT) is not None:
+        # A regional edit may start from pure noise: 1.0 regenerates the region
+        if not 0 < strength <= 1:
+            problems.append(
+                f"refine_strength is a sigma in (0, 1] with a source_video - 1.0 "
+                f"regenerates the masked region from noise, about 0.4 reworks it "
+                f"lightly - and {strength} is outside it"
+            )
     elif not 0 < strength < 1:
         problems.append(
             f"refine_strength is a sigma in (0, 1) - about 0.2 refines an "
-            f"upscaled take - and {strength} is outside it"
+            f"upscaled take, and 1.0 is allowed only with a source_video - and "
+            f"{strength} is outside it"
         )
     if arguments.get("latents") is None and arguments.get(SOURCE_VIDEO_INPUT) is None:
         problems.append(
diff --git a/dw/validation.py b/dw/validation.py
index 0fc883a8..9f3846d5 100644
--- a/dw/validation.py
+++ b/dw/validation.py
@@ -343,7 +343,12 @@ def _task_errors(context):
     ),
     # hold_audio on a pipeline with no H3 hold blocks, or holding something
     # that is not audio, costs a checkpoint load otherwise (dw/hold_audio.py)
-    Check("hold_audio", lambda c: hold_audio_errors(c.expanded, c.source_indices)),
+    Check(
+        "hold_audio",
+        lambda c: hold_audio_errors(
+            c.expanded, c.source_indices, c.base_dir, probe=c.probe
+        ),
+    ),
     # refine_strength with nothing to refine, no held soundtrack or a one-point
     # schedule fails after the checkpoint load just the same
     Check(
@@ -352,7 +357,10 @@ def _task_errors(context):
     ),
     # A regional edit on a pipeline that is not H3, a mask with no source, or a
     # source with no refine_strength, with latents or on a chained step
-    Check("regional_edit", lambda c: mask_errors(c.expanded, c.source_indices)),
+    Check(
+        "regional_edit",
+        lambda c: mask_errors(c.expanded, c.source_indices, c.base_dir, probe=c.probe),
+    ),
     # guides on a pipeline that cannot take them, with references, malformed,
     # or a clip that is no video or runs past the render (dw/guides.py)
     Check(
diff --git a/tests/test_h3_hold_audio.py b/tests/test_h3_hold_audio.py
index d6d4c071..8e02fb88 100644
--- a/tests/test_h3_hold_audio.py
+++ b/tests/test_h3_hold_audio.py
@@ -427,12 +427,45 @@ def test_a_workflow_that_is_not_an_h3_one_is_refused(self, workflow):
     def test_the_h3_workflows_are_accepted(self, workflow):
         assert errors_for(h3_step(workflow, hold_audio="asset:track.wav")) == []
 
-    @pytest.mark.parametrize("value", ["asset:frame.png", "clip.mp4", "x.png"])
+    @pytest.mark.parametrize("value", ["asset:frame.png", "clip.gif", "x.png"])
     def test_a_non_audio_path_is_refused(self, value):
         errors = errors_for(h3_step(hold_audio=value))
         assert len(errors) == 1
         assert "not an audio file" in errors[0]["message"]
 
+    @pytest.mark.parametrize(
+        "value", ["asset:clip.mp4", "output:a/latest/final/take.mov", "clip.mkv"]
+    )
+    def test_a_video_is_held_by_its_soundtrack(self, value):
+        assert errors_for(h3_step(hold_audio=value)) == []
+
+    def test_a_silent_video_is_refused_when_it_resolves(self, tmp_path):
+        from tests.test_h3_mask import write_video
+
+        from dw.media import probe_metadata
+
+        name = write_video(tmp_path / "silent.mp4")
+        step = h3_step(hold_audio=name)
+        errors = hold_audio_errors(
+            {"steps": [step]}, None, str(tmp_path), probe=probe_metadata
+        )
+        assert len(errors) == 1
+        assert "no audio stream" in errors[0]["message"]
+
+    def test_a_video_with_a_soundtrack_is_clean_when_it_resolves(self, tmp_path):
+        from tests.test_h3_mask import write_video
+
+        from dw.media import probe_metadata
+
+        name = write_video(tmp_path / "take.mp4", sample_rate=16000)
+        step = h3_step(hold_audio=name)
+        assert (
+            hold_audio_errors(
+                {"steps": [step]}, None, str(tmp_path), probe=probe_metadata
+            )
+            == []
+        )
+
     @pytest.mark.parametrize("value", ["hello", "asset:track", "clip"])
     def test_a_name_with_no_audio_extension_is_refused(self, value):
         errors = errors_for(h3_step(hold_audio=value))
@@ -666,6 +699,28 @@ def from_file(cls, location):
         )
         return opened
 
+    def test_a_video_path_is_opened_for_its_soundtrack(self, tmp_path, opened):
+        (tmp_path / "take.mp4").write_bytes(b"")
+
+        hold_audio_reference("take.mp4", str(tmp_path))
+
+        assert opened == [os.path.realpath(tmp_path / "take.mp4")]
+
+    def test_a_video_with_no_soundtrack_is_refused_at_the_call(self, tmp_path):
+        from tests.test_h3_mask import write_video
+
+        name = write_video(tmp_path / "silent.mp4")
+        with pytest.raises(ValueError, match="soundtrack of 'silent.mp4'"):
+            hold_audio_reference(name, str(tmp_path))
+
+    def test_a_video_soundtrack_is_decoded_for_real(self, tmp_path):
+        from tests.test_h3_mask import write_video
+
+        name = write_video(tmp_path / "take.mp4", sample_rate=16000)
+        reference = hold_audio_reference(name, str(tmp_path))
+        assert reference.sample_rate == 16000
+        assert reference.audio.shape[-1] > 0
+
     def test_a_relative_path_resolves_against_the_workflow_directory(
         self, tmp_path, opened
     ):
diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
index 0e3dc8db..b51f40a0 100644
--- a/tests/test_h3_mask.py
+++ b/tests/test_h3_mask.py
@@ -726,7 +726,210 @@ def test_the_check_is_registered(self):
         from dw import validation
 
         source = open(validation.__file__).read()
-        assert 'Check("regional_edit"' in source
+        assert '"regional_edit",' in source
+        assert (
+            "mask_errors(c.expanded, c.source_indices, c.base_dir, probe=c.probe)"
+            in (source)
+        )
+
+
+# 5c. Validation reads the files: size, frame count and an empty mask (#1077)
+
+
+def write_video(path, frames=9, size=(64, 48), value=0, sample_rate=None):
+    """A real h264 mp4 of `frames` flat frames at `value`, `size` (w, h), with a
+    soundtrack when `sample_rate` is given."""
+    import av
+
+    container = av.open(str(path), "w")
+    video = container.add_stream("libx264", rate=8)
+    video.width, video.height, video.pix_fmt = size[0], size[1], "yuv420p"
+    audio = container.add_stream("aac", rate=sample_rate) if sample_rate else None
+    pixels = np.full((size[1], size[0], 3), value, dtype=np.uint8)
+    for _ in range(frames):
+        frame = av.VideoFrame.from_ndarray(pixels, format="rgb24")
+        container.mux(video.encode(frame))
+    container.mux(video.encode())
+    if audio is not None:
+        samples = np.zeros((1, sample_rate * frames // 8), dtype=np.float32)
+        frame = av.AudioFrame.from_ndarray(samples, format="flt", layout="mono")
+        frame.sample_rate = sample_rate
+        container.mux(audio.encode(frame))
+        container.mux(audio.encode())
+    container.close()
+    return path.name
+
+
+def write_mask(path, size=(64, 48), value=255):
+    from PIL import Image
+
+    Image.new("L", size, value).save(path)
+    return path.name
+
+
+def probed_errors(tmp_path, **arguments):
+    from dw.media import probe_metadata
+
+    arguments.setdefault("refine_strength", 0.9)
+    return mask_errors(
+        {"steps": [h3_step(**arguments)]}, None, str(tmp_path), probe=probe_metadata
+    )
+
+
+class TestStaticMedia:
+    def test_a_fitting_edit_is_clean(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_mask(tmp_path / "m.png")
+        assert probed_errors(tmp_path, source_video=source, mask_image=mask) == []
+
+    def test_the_canvas_defaults_to_the_source(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        assert probed_errors(tmp_path, source_video=source) == []
+
+    def test_a_source_off_the_canvas_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        errors = probed_errors(tmp_path, source_video=source, width=128, height=48)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("source_video")
+        assert "64x48" in errors[0]["message"] and "128x48" in errors[0]["message"]
+
+    def test_a_source_frame_mismatch_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4", frames=9)
+        errors = probed_errors(tmp_path, source_video=source, num_frames=17)
+        assert len(errors) == 1
+        assert "num_frames=17" in errors[0]["message"]
+
+    def test_a_mask_image_of_another_size_is_refused_at_its_path(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_mask(tmp_path / "m.png", size=(32, 32))
+        errors = probed_errors(tmp_path, source_video=source, mask_image=mask)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("mask_image")
+        assert "32x32" in errors[0]["message"]
+
+    def test_an_all_black_mask_image_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_mask(tmp_path / "m.png", value=0)
+        errors = probed_errors(tmp_path, source_video=source, mask_image=mask)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("mask_image")
+        assert "all black" in errors[0]["message"]
+
+    def test_an_all_black_mask_video_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_video(tmp_path / "m.mp4", value=0)
+        errors = probed_errors(tmp_path, source_video=source, mask_video=mask)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("mask_video")
+        assert "all black" in errors[0]["message"]
+
+    def test_a_white_mask_video_that_fits_is_clean(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_video(tmp_path / "m.mp4", value=255)
+        assert probed_errors(tmp_path, source_video=source, mask_video=mask) == []
+
+    def test_a_mask_video_frame_mismatch_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4", frames=9)
+        mask = write_video(tmp_path / "m.mp4", frames=5, value=255)
+        errors = probed_errors(tmp_path, source_video=source, mask_video=mask)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("mask_video")
+        assert "5 frames" in errors[0]["message"]
+
+    def test_a_mask_video_that_is_an_image_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_mask(tmp_path / "m.png")
+        errors = probed_errors(tmp_path, source_video=source, mask_video=mask)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("mask_video")
+        assert "1 frames" in errors[0]["message"]
+
+    def test_without_a_probe_only_the_rules_are_checked(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_mask(tmp_path / "m.png", value=0)
+        step = h3_step(source_video=source, mask_image=mask, refine_strength=0.9)
+        assert mask_errors({"steps": [step]}, None, str(tmp_path)) == []
+
+    def test_a_previous_result_is_left_to_the_call(self, tmp_path):
+        errors = probed_errors(
+            tmp_path,
+            source_video="previous_result:base.video",
+            mask_video="previous_result:mask",
+        )
+        assert errors == []
+
+    def test_the_size_refusal_surfaces_through_the_workflow(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4")
+        mask = write_mask(tmp_path / "m.png", value=0)
+        definition = h3_definition(
+            source_video=source,
+            mask_image=mask,
+            refine_strength=0.9,
+            hold_audio=source,
+            width=64,
+            height=48,
+            num_frames=9,
+        )
+        workflow = workflow_from_definition(
+            definition, str(tmp_path), base_dir=str(tmp_path)
+        )
+        errors = [
+            e
+            for e in workflow.validation_errors()
+            if any(n in e["path"] for n in ("source_video", "mask_"))
+        ]
+        assert any("all black" in e["message"] for e in errors), errors
+
+
+class TestStrengthOne:
+    def test_one_is_accepted_with_a_source_video(self):
+        arguments = {
+            "refine_strength": 1.0,
+            "source_video": "asset:clip.mp4",
+            "hold_audio": "asset:clip.mp4",
+            "num_inference_steps": 5,
+        }
+        assert refine_problems(arguments) == []
+
+    def test_one_is_refused_without_a_source_video(self):
+        arguments = {
+            "refine_strength": 1.0,
+            "latents": "previous_result:up",
+            "hold_audio": "previous_result:base.audio",
+            "num_inference_steps": 5,
+        }
+        problems = refine_problems(arguments)
+        assert len(problems) == 1 and "source_video" in problems[0]
+
+    def test_above_one_is_refused_with_a_source_video(self):
+        arguments = {
+            "refine_strength": 1.5,
+            "source_video": "asset:clip.mp4",
+            "hold_audio": "asset:clip.mp4",
+        }
+        problems = refine_problems(arguments)
+        assert len(problems) == 1 and "(0, 1]" in problems[0]
+
+    def test_the_schedule_at_one_is_the_stock_grid(self):
+        from dw.pipeline_processors.h3_hold_steps import (
+            refine_sigmas,
+            shifted_sigma_grid,
+        )
+
+        sigmas = refine_sigmas(1.0, 5, 12)
+        stock = shifted_sigma_grid(5, 12.0).float()
+        stock[-1] = 0.0
+        assert sigmas[0] == 1.0
+        assert np.allclose(sigmas.numpy(), stock.numpy())
+
+    def test_a_validated_step_at_one_is_clean(self):
+        step = h3_step(
+            **args(refine_strength=1.0, hold_audio="asset:clip.mp4"),
+            num_inference_steps=5,
+        )
+        from dw.hold_audio import refine_strength_errors
+
+        assert refine_strength_errors({"steps": [step]}) == []
 
 
 # The call: Pipeline._with_mask

From 71304eb8a13545e6ea6cfe493afa6e26b818ad09 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 03:04:33 -0500
Subject: [PATCH 018/125] feat(ltx2): #1079 - alpha-matte template on the
 Alpha-Gen IC-LoRA

fit -> LTX2InContextPipeline with Alpha-Gen 0.9 at 1.0, empty prompt,
reference at factor 1 -> restore_to_source. num_frames 8n+1, 9-145.
Alpha-Gen promoted to proven (lem job 7219cf6b4cf5, 3.9 min cold);
Clean-Plate and Day-To-Night carry the not-shipped finding and its
reopening trigger. Skill route row, README, ARCHITECTURE count, budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                      |   2 +-
 loras/ltx-2.5/ic-alpha-gen.json           |   9 +-
 loras/ltx-2.5/ic-clean-plate.json         |   6 +
 loras/ltx-2.5/ic-day-to-night.json        |   6 +
 plugins/dw/skills/ltx-2.5/SKILL.md        |  11 +-
 tests/test_catalog_structure.py           |   5 +-
 tests/test_ltx2_ic_loras.py               |  15 +-
 tests/test_step_cache.py                  |   3 +
 workflows/templates/ltx2/README.md        |  10 +-
 workflows/templates/ltx2/alpha-matte.json | 222 ++++++++++++++++++++++
 10 files changed, 277 insertions(+), 12 deletions(-)
 create mode 100644 workflows/templates/ltx2/alpha-matte.json

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index eb666821..df2fc0f7 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -113,7 +113,7 @@ one to open.
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
 | H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
-| IC-LoRA reference scale | `workflows/templates/ltx2/` | The three conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
+| IC-LoRA reference scale | `workflows/templates/ltx2/` | The four conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
 
diff --git a/loras/ltx-2.5/ic-alpha-gen.json b/loras/ltx-2.5/ic-alpha-gen.json
index 13b39df5..16ec7735 100644
--- a/loras/ltx-2.5/ic-alpha-gen.json
+++ b/loras/ltx-2.5/ic-alpha-gen.json
@@ -11,7 +11,14 @@
   "scale": {
     "default": 1.0
   },
-  "status": "trial",
+  "status": "proven",
+  "evidence": [
+    {
+      "job": "7219cf6b4cf5",
+      "issue": 1079,
+      "note": "templates/ltx2/alpha-matte on lem (RTX 3090, uint4 SDNQ) at 960x544x121: a clean white walking figure, background black, birds and debris as soft partial values; 3.9 min including a cold load"
+    }
+  ],
   "license": "other",
   "tags": [
     "matte",
diff --git a/loras/ltx-2.5/ic-clean-plate.json b/loras/ltx-2.5/ic-clean-plate.json
index dc253c45..793b01c6 100644
--- a/loras/ltx-2.5/ic-clean-plate.json
+++ b/loras/ltx-2.5/ic-clean-plate.json
@@ -12,6 +12,12 @@
     "default": 1.0
   },
   "status": "trial",
+  "evidence": [
+    {
+      "issue": 1064,
+      "note": "Not shipped as a template (#1064): the card is for the dev/full guided route - it describes the empty scene through a prompt with a negative prompt, which dw's distilled IC route runs at guidance 1.0 and ignores, and trains at 25 fps with an audio track on the reference. Reopen when dw has a guided (dev/full) IC route, or a field report needs subject removal across a whole clip"
+    }
+  ],
   "license": "other",
   "tags": [
     "remove",
diff --git a/loras/ltx-2.5/ic-day-to-night.json b/loras/ltx-2.5/ic-day-to-night.json
index f3c5b65f..98113758 100644
--- a/loras/ltx-2.5/ic-day-to-night.json
+++ b/loras/ltx-2.5/ic-day-to-night.json
@@ -12,6 +12,12 @@
     "default": 1.0
   },
   "status": "trial",
+  "evidence": [
+    {
+      "issue": 1064,
+      "note": "Not shipped as a template (#1064): the night look is steered by the prompt under the card's guided (dev/full) route, which dw's distilled IC route does not run, and the reference must be re-encoded to 24 fps first, which fit_to_model does not do. Reopen when dw has a guided IC route plus fps resampling in fit_to_model, or a field report asks for it"
+    }
+  ],
   "license": "other",
   "tags": [
     "relight",
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 03662614..171d6c6b 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ltx-2.5
-description: Use when a dw MCP server is connected and the user wants LTX-2.5 video - a short clip with its own soundtrack, a clip from one picture or between two, a sharper full-size render, a 2x upscale of its own or the user's clip, a subject held across a clip from a reference sheet, a blurry or compressed clip restored, or a clip extended or chained longer. Picks the template, states schedule and size rules, quotes cost, and carries the trained caption spec the prompt must follow.
+description: Use when a dw MCP server is connected and the user wants LTX-2.5 video - a short clip with its own soundtrack, a clip from one picture or between two, a sharper full-size render, a 2x upscale of its own or the user's clip, a subject held across a clip from a reference sheet, a blurry or compressed clip restored, an alpha matte pulled from a clip, or a clip extended or chained longer. Picks the template, states schedule and size rules, quotes cost, and carries the trained caption spec the prompt must follow.
 ---
 
 # LTX-2.5 on a dw server
@@ -46,6 +46,10 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   - one composite image, a clean panel per character, prop and location, no
   text, bigger panels for what matters. What isn't on the sheet won't
   appear. `reference_frames` must stay at or above 121.
+- **A matte of the user's clip**: `templates/ltx2/alpha-matte` - a soft
+  grey per-frame alpha, white = foreground, at the source's size, for the
+  user's editor to composite. No prompt: the model picks the foreground and
+  a prompt doesn't steer it. `num_frames` caps at 145 (RGB leaks past it).
 - **Repairing the user's footage**: `templates/ltx2/restore-deblur` for
   spatial defocus, `templates/ltx2/restore-decompression` for low-bitrate
   artefacts. Each inverts one defect and no other - neither upscales or
@@ -126,9 +130,8 @@ caption spec, verbatim from the pipeline, which the caption must follow.
 1. `validate_workflow` first - free, and catches bad arguments.
 2. Quote `plan.estimate` from the validate answer (wall clock, loading
    included) and name any `downloads_required` - an IC-LoRA template pulls a
-   gated weight the box may not have. Only `text-to-video`, `two-stage`,
-   `refine-clip` and `refine-in-place` (~1.5 min, RTX 3090) carry a `cost`;
-   for the rest give the shape - a 121-frame clip at 960x544 is under two
+   gated weight the box may not have. A template whose catalog entry has
+   no `cost` prices from the shape - a 121-frame clip at 960x544 is under two
    minutes cold on a 24 GB card, a minute loading; extend and chain
    multiply by their passes.
    Get the go-ahead, then `run_workflow` with `acknowledged_cost` set to the
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index c38c3beb..cf4d113d 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -497,7 +497,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Then to 11_650 for the `remove-object` and `segment-and-remove` templates
 # (#956, stage #974, 2026-10-22), measured at 11_592: two new entries, the
 # catalog's only prompt-free removal route, each with a cost block.
-COMPACT_BUDGET = 11_650
+# Then to 11_850 for the `alpha-matte` template (#1064, stage #1079,
+# 2026-10-31), measured at 11_788: one new entry, the catalog's only matte
+# route, with its cost block.
+COMPACT_BUDGET = 11_850
 FILTERED_BUDGET = 1_500
 
 
diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index ba0da3dd..3f051e31 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -28,6 +28,15 @@
 # repo -> (weight file, reference downscale factor, trained width, height,
 #          trained frames, lora strength)
 CARDS = {
+    "alpha-matte": (
+        "Lightricks/LTX-2.5-22b-IC-LoRA-Alpha-Gen",
+        "ltx-2.5-22b-ic-lora-alpha-gen-0.9.safetensors",
+        1,
+        960,
+        544,
+        121,
+        1.0,
+    ),
     "reference-sheet": (
         "Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients",
         "ltx-2.5-22b-ic-lora-ingredients-0.9.safetensors",
@@ -91,8 +100,12 @@ def test_the_strength_is_the_cards_default(self, name):
         *_, strength = CARDS[name]
         (lora,) = conditioned_step(name)["pipeline"]["loras"]
         variables = definition(name)["variables"]
+        # Alpha-Gen's card fixes the strength, so its template writes it inline
+        scale = lora["scale"]
+        if isinstance(scale, str):
+            scale = variables[scale.removeprefix("variable:")]
 
-        assert variables[lora["scale"].removeprefix("variable:")] == strength
+        assert scale == strength
 
     def test_the_reference_is_encoded_at_the_output_resolution(self, name):
         """The conditioning LoRAs state downscale factor 1; the spatial
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 57b47366..0c3d4f13 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -727,6 +727,9 @@ def test_normalized_downstream_false_when_nothing_references_it():
     "lora.json": {
         "txt2img": "04031c5e01597b46f9ceb50f717e036013d5f6e6a497ae3aaef585f7121bcf4e"
     },
+    "ltx2/alpha-matte.json": {
+        "matte": "1ee2f5927bde21fca0096fe39db8632238b1031e483d3a780695290b10b713cd"
+    },
     "ltx2/chained-segments.json": {
         "chained_image_to_video": "3a36def4e09fe10832bc1821c7cb6fd82d9e050ba149e5b6e7afa6ec66f60f68"
     },
diff --git a/workflows/templates/ltx2/README.md b/workflows/templates/ltx2/README.md
index 75b145ae..074973da 100644
--- a/workflows/templates/ltx2/README.md
+++ b/workflows/templates/ltx2/README.md
@@ -56,17 +56,19 @@ Read them in this order and each introduces one new idea on top of the last.
 
 ## Restoring footage you did not generate
 
-Both of these (and `upscale-clip` above) read a clip the workflow did not make, with the source attached
+These (and `upscale-clip` above) read a clip the workflow did not make, with the source attached
 as an in-context reference for the whole denoise - so identity, framing and
-background geometry are the source's and only the defect changes. A different
+background geometry are the source's and only the defect changes (or, for
+`alpha-matte`, the source is read and a matte drawn from it). A different
 trade from `two-stage`, which invents a sharper version of a scene it
-generated. Both are 0.9 preview weights trained at 960x544x121 @ 24fps;
-generating far above that bucket weakens the effect.
+generated. Deblur and decompression are 0.9 preview weights trained at
+960x544x121 @ 24fps; generating far above that bucket weakens the effect.
 
 | Example | What it introduces |
 | ------- | ------------------ |
 | [restore-deblur.json](restore-deblur.json) | Spatial defocus only - not motion blur, not noise, not low resolution. Lower `lora_scale` toward 0.8 if it over-sharpens into haloing (#152) |
 | [restore-decompression.json](restore-decompression.json) | Macroblocking, chroma bleed, ringing and banding from a low bit-rate source. Not a deblur and not an upscale (#152) |
+| [alpha-matte.json](alpha-matte.json) | A soft per-frame alpha matte of the source - grey h264, white = foreground, at the source's size - for compositing in an editor. No prompt: the Alpha-Gen card's model picks the foreground itself. `num_frames` caps at 145, past which RGB leaks into the matte; the card's 1920x1088 ceiling is not a 24 GB size (#1064) |
 | [restore-long.json](restore-long.json) | `restore-deblur` over a source longer than one bucket: `window_video` slices it, a `for_each` restores each window, `join_windows` cross-fades them back to the source's length. `windows` is `ceil(source_frames / (num_frames - overlap))` entries, checked by `validate_workflow` (#601) |
 
 ## Going long
diff --git a/workflows/templates/ltx2/alpha-matte.json b/workflows/templates/ltx2/alpha-matte.json
new file mode 100644
index 00000000..fd7e0524
--- /dev/null
+++ b/workflows/templates/ltx2/alpha-matte.json
@@ -0,0 +1,222 @@
+{
+    "id": "LTX2AlphaMatte",
+    "description": "Pulls a soft per-frame alpha matte from the user's clip with the Alpha-Gen in-context LoRA - no green screen, mask or prompt; hair, smoke, motion blur and glass come back as partial values, not a hard cutout. The output is a grey-scale h264 MP4 at the source's own size and frame-aligned with it: white is foreground, black background. dw does not composite it: use it as the source's alpha (a luma matte) in an editor. The model picks the foreground itself and the prompt does not steer it, so the prompt is fixed empty and there is no prompt variable. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing (the black padding reads as background) and a last step crops the padding back off, so any aspect ratio comes back at its own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. 'num_frames' is 8n+1 from 9 to 145 and refused above: past 145 the card says RGB content leaks into the matte. Defaults 960x544 at 121 frames, 24 fps - set 'frame_rate' to the source's. The card's ceiling is 1920x1088, which is not a 24 GB size. The LoRA strength is the card's fixed 1.0. A 0.9 preview weight, run here under uint4 SDNQ.",
+    "summary": "Soft per-frame alpha matte of your clip: grey MP4, white = foreground, at the source's size. No prompt.",
+    "traits": [
+        "needs-input-media"
+    ],
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 3.9
+        }
+    ],
+    "cost_drivers": [
+        "num_frames",
+        "width",
+        "height"
+    ],
+    "variables": {
+        "transformer_weights_dtype": "{uint4}",
+        "text_encoder_weights_dtype": "{int8}",
+        "source_video": "asset:clip.mp4",
+        "width": 960,
+        "height": 544,
+        "num_frames": 121,
+        "frame_rate": 24.0,
+        "seed": 42
+    },
+    "variable_constraints": {
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "LTX-2.5's pipelines refuse a width not divisible by 32 outright (ValueError, not a silent floor), so it is checked here before the pipeline load rather than after it"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "LTX-2.5's pipelines refuse a height not divisible by 32 outright (ValueError, not a silent floor), so it is checked here before the pipeline load rather than after it"
+        },
+        "num_frames": {
+            "modulus": 8,
+            "remainder": 1,
+            "min_frames": 9,
+            "reason": "LTX-2.5's video VAE encodes 8 * n + 1 frames, so an off-grid count is not refused by the pipeline but floored to the grid below - refused here instead, with no 'snap'. 145 is the Alpha-Gen card's ceiling: past it the source's RGB content leaks into the matte, so a longer request is refused rather than run into that failure",
+            "max_frames": 145
+        }
+    },
+    "seed": "variable:seed",
+    "steps": [
+        {
+            "name": "fit",
+            "task": {
+                "command": "fit_to_model",
+                "arguments": {
+                    "video": "variable:source_video",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_frames": "variable:num_frames",
+                    "mode": "letterbox",
+                    "downscale": 1
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "save": false
+            }
+        },
+        {
+            "name": "matte",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "LTX2InContextPipeline",
+                    "pre_load_modules": [
+                        "sdnq"
+                    ],
+                    "components": {
+                        "transformer": {
+                            "device": "cuda"
+                        },
+                        "text_encoder": {
+                            "group_offload": {
+                                "offload_type": "leaf_level",
+                                "use_stream": true
+                            }
+                        },
+                        "connectors": {
+                            "group_offload": {
+                                "offload_type": "leaf_level",
+                                "use_stream": true
+                            }
+                        },
+                        "vae": {
+                            "device": "cuda"
+                        },
+                        "audio_vae": {
+                            "device": "cuda"
+                        },
+                        "vocoder": {
+                            "device": "cuda"
+                        }
+                    },
+                    "vae": {
+                        "enable_tiling": true
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "Lightricks/LTX-2.5-Diffusers",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "transformer": {
+                    "configuration": {
+                        "component_type": "LTX2VideoTransformer3DModel",
+                        "preserve_device_placement": true
+                    },
+                    "quantization_config": {
+                        "configuration": {
+                            "config_type": "sdnq.SDNQConfig"
+                        },
+                        "arguments": {
+                            "weights_dtype": "variable:transformer_weights_dtype",
+                            "quantization_device": "cuda",
+                            "return_device": "cuda",
+                            "use_quantized_matmul": true,
+                            "dequantize_fp32": false
+                        }
+                    },
+                    "from_pretrained_arguments": {
+                        "model_name": "Lightricks/LTX-2.5-Diffusers",
+                        "subfolder": "transformer",
+                        "torch_dtype": "torch.bfloat16"
+                    }
+                },
+                "text_encoder": {
+                    "configuration": {
+                        "component_type": "transformers.Gemma4UnifiedForConditionalGeneration",
+                        "preserve_device_placement": true
+                    },
+                    "quantization_config": {
+                        "configuration": {
+                            "config_type": "sdnq.SDNQConfig"
+                        },
+                        "arguments": {
+                            "weights_dtype": "variable:text_encoder_weights_dtype",
+                            "quantization_device": "cuda",
+                            "return_device": "cpu",
+                            "dequantize_fp32": false,
+                            "modules_to_not_convert": [
+                                "embed_vision",
+                                "embed_audio",
+                                "lm_head"
+                            ]
+                        }
+                    },
+                    "from_pretrained_arguments": {
+                        "model_name": "Lightricks/LTX-2.5-Diffusers",
+                        "subfolder": "text_encoder",
+                        "torch_dtype": "torch.bfloat16"
+                    }
+                },
+                "arguments": {
+                    "prompt": "",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_frames": "variable:num_frames",
+                    "frame_rate": "variable:frame_rate",
+                    "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
+                    "guidance_scale": 1.0,
+                    "audio_guidance_scale": 1.0,
+                    "stg_scale": 0.0,
+                    "audio_stg_scale": 0.0,
+                    "modality_scale": 1.0,
+                    "audio_modality_scale": 1.0,
+                    "output_type": "{np}",
+                    "reference_conditions": [
+                        {
+                            "reference_type": "diffusers.pipelines.ltx2.pipeline_ltx2_ic_lora.LTX2ReferenceCondition",
+                            "from_arguments": {
+                                "frames": {
+                                    "media_type": "video",
+                                    "location": "previous_result:fit.video"
+                                },
+                                "strength": 1.0
+                            }
+                        }
+                    ],
+                    "reference_downscale_factor": 1,
+                    "conditioning_attention_strength": 1.0
+                },
+                "loras": [
+                    {
+                        "model_name": "Lightricks/LTX-2.5-22b-IC-LoRA-Alpha-Gen",
+                        "weight_name": "ltx-2.5-22b-ic-lora-alpha-gen-0.9.safetensors",
+                        "adapter_name": "ic_lora",
+                        "scale": 1.0
+                    }
+                ]
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": "variable:frame_rate",
+                "save": false
+            }
+        },
+        {
+            "name": "final",
+            "task": {
+                "command": "restore_to_source",
+                "arguments": {
+                    "video": "previous_result:matte",
+                    "fit": "previous_result:fit.fit"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": "variable:frame_rate",
+                "subfolder": "final"
+            }
+        }
+    ]
+}

From b34b46757c6497cc90093c2ea934d90a4c9c6d31 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 03:20:48 -0500
Subject: [PATCH 019/125] feat(loras): #1081 - Open-H3 refiner trial entry,
 regenerate-2k and tiled-refine doc corrections

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/WORKFLOW_GUIDE.md                        |  4 +--
 .../audits/2026-09-07-minimax-h3-audit.md     |  4 +--
 .../plans/2026-09-07-ltx-h3-catalog-repair.md |  3 ++-
 loras/minimax-h3/open-h3-regenerate-2k.json   | 27 +++++++++++++++++++
 4 files changed, 33 insertions(+), 5 deletions(-)
 create mode 100644 loras/minimax-h3/open-h3-regenerate-2k.json

diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index a4d7d099..74911581 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2577,8 +2577,8 @@ audio, once. Its `videos` carry H3's 24 fps, so the `pair_audio` below writes th
 that rate without being told. The job's events show one log line per tile and one decoding phase.
 
 It is slow. A 1920x1088 refine is roughly 4 tiles, each a 768p refine, plus a 1080p decode:
-about 25-30 minutes, against about 9.6 minutes for a native 768p take (an estimate, not
-measured). The validate projection prices the denoise at the tile's size and the decode at the
+about 12 minutes measured on an RTX 3090 for 124 frames (the recipe below, with its 544p
+base), against about 9.6 minutes for a native 768p take. The validate projection prices the denoise at the tile's size and the decode at the
 canvas's, so a tiled refine does not warn as if it denoised 1080p at once.
 
 ```json
diff --git a/docs/proposals/audits/2026-09-07-minimax-h3-audit.md b/docs/proposals/audits/2026-09-07-minimax-h3-audit.md
index 2625ec5a..c8a71b55 100644
--- a/docs/proposals/audits/2026-09-07-minimax-h3-audit.md
+++ b/docs/proposals/audits/2026-09-07-minimax-h3-audit.md
@@ -281,8 +281,8 @@ Ordered by how much it would change what the repository does.
     768-pixel short edge (max 768×1344), dimensions must be multiples of 32,
     aspect ratios from 1:4 to 4:1, 32 kHz stereo output, 11 stable dialogue
     languages, Ref2VA limits (≤9 images, ≤3 videos, ≤3 audio, ≤12 total; audio
-    references can never be the only references), and that H3-Regenerate-2K
-    (2K output) is API-only and not open-sourced.
+    references can never be the only references). (This audit said H3-Regenerate-2K
+    was API-only; NVlabs has since published Open-H3-Regenerate-2K, see #1065.)
 
 11. **Step-count guidance**: ComfyUI documents 20 steps as the non-turbo default
     and ~25 for better motion quality. The repository's 20 matches the default
diff --git a/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md b/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md
index 3a0859c9..7229f670 100644
--- a/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md
+++ b/docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md
@@ -1080,7 +1080,8 @@ MiniMax H3 ([audit](audits/2026-09-07-minimax-h3-audit.md)):
 - Cut-verb and audio-continuity vocabularies (base guide §4.2, §4.4).
 - Step-count note: 20 default, ~25 for motion (ComfyUI).
 - Ref2VA input limits (≤9 images, ≤3 videos, ≤3 audio, ≤12) and that audio can never
-  be the only reference; H3-Regenerate-2K is API-only.
+  be the only reference. (H3-Regenerate-2K was API-only when this was written; NVlabs
+  has since published Open-H3-Regenerate-2K, see #1065.)
 - Music3 `audio_duration` cap: 9000 frames, six minutes.
 ```
 
diff --git a/loras/minimax-h3/open-h3-regenerate-2k.json b/loras/minimax-h3/open-h3-regenerate-2k.json
new file mode 100644
index 00000000..51e5ea4a
--- /dev/null
+++ b/loras/minimax-h3/open-h3-regenerate-2k.json
@@ -0,0 +1,27 @@
+{
+  "model_name": "Kijai/MiniMax-H3-experimental",
+  "weight_name": "loras/minimax_h3_open_regenerate_2k_refiner_rank_384_bf16.safetensors",
+  "revision": "f5c3b1d5a63e008a691fca1b6096fd57a5307536",
+  "base_models": [
+    "MiniMaxAI/MiniMax-H3"
+  ],
+  "workflow": [
+    "t2va",
+    "fl2va"
+  ],
+  "description": "Kijai's refiner-only rank-384 extraction (5.9 GB, bf16) of NVlabs' Open-H3-Regenerate-2K (Efficient-Large-Model/Open-H3-Regenerate-2K): a high-sigma regenerate pass over an upscaled 768p draft. Linears only - NVlabs' sharp_curve_branches.safetensors (AdaLN branches on a timestep curve) is not a LoRA and is not loaded, nor is the merge's LMS half. Leave lora_alpha unset: the file's own alphas scale it (see the mixed-rank note in instantx-turbo-4step). Trained on the keyframe partition",
+  "use_when": "Probe only (#1065): on the refine step of the guide's H3LatentUpscaleRefine recipe, stacked with turbo-4step-keyframe, refine_strength 0.909375, num_inference_steps 4, shift about 2 (the recipe's exact sigmas need refine_sigmas, #1065 stage B)",
+  "scale": {
+    "default": 1.0
+  },
+  "stacks_with": [
+    "minimax-h3/turbo-4step-keyframe"
+  ],
+  "status": "trial",
+  "license": "minimax-h3-community",
+  "tags": [
+    "refine",
+    "upscale",
+    "second-pass"
+  ]
+}

From 4fc4fb6d0b677dd6a643f0215fc959c61dae1090 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 05:22:08 -0500
Subject: [PATCH 020/125] fix(server): #1086 - list_jobs refuses a workspace
 that doesn't exist

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/server/routes/jobs.py   |  3 +++
 tests/test_jobs_listing.py | 13 +++++++++++++
 2 files changed, 16 insertions(+)

diff --git a/dw/server/routes/jobs.py b/dw/server/routes/jobs.py
index d66edee3..5f7dc0ec 100644
--- a/dw/server/routes/jobs.py
+++ b/dw/server/routes/jobs.py
@@ -236,6 +236,9 @@ def list_jobs(
     complete one. The default is still every matching job, oldest first -
     what the web UI polls."""
     manager = request.app.state.job_manager
+    if workspace:
+        # A name that was never a workspace is a typo, not "no jobs here"
+        workspace_for(request.app.state, workspace)
     statuses = [part.strip() for part in status.split(",")] if status else None
     statuses = [part for part in statuses if part] if statuses else None
     if statuses:
diff --git a/tests/test_jobs_listing.py b/tests/test_jobs_listing.py
index 36ff5f5c..26fe9cc9 100644
--- a/tests/test_jobs_listing.py
+++ b/tests/test_jobs_listing.py
@@ -121,6 +121,19 @@ def test_unknown_status_is_a_bad_request(server):
         assert "finished" in response.json()["detail"]
 
 
+def test_unknown_workspace_is_not_found_not_an_empty_listing(server, tmp_path):
+    from dw.workspace import Workspace
+
+    with server(success_script) as client:
+        (tmp_path / "ws").mkdir()
+        client.app.state.workspace_root = Workspace(str(tmp_path / "ws"), "flag")
+        response = client.get("/api/jobs", params={"workspace": "qa-typo"})
+
+        assert response.status_code == 404
+        assert "No such workspace: qa-typo" in response.json()["detail"]
+        assert client.get("/api/jobs", params={"workspace": "default"}).status_code == 200
+
+
 def mcp_client(body):
     seen = {}
 

From d9f3056b8857a47bc47b8a52944cd78d4f60dc9b Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 05:22:32 -0500
Subject: [PATCH 021/125] style: #1086 - ruff format

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 tests/test_jobs_listing.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tests/test_jobs_listing.py b/tests/test_jobs_listing.py
index 26fe9cc9..df078ebf 100644
--- a/tests/test_jobs_listing.py
+++ b/tests/test_jobs_listing.py
@@ -131,7 +131,9 @@ def test_unknown_workspace_is_not_found_not_an_empty_listing(server, tmp_path):
 
         assert response.status_code == 404
         assert "No such workspace: qa-typo" in response.json()["detail"]
-        assert client.get("/api/jobs", params={"workspace": "default"}).status_code == 200
+        assert (
+            client.get("/api/jobs", params={"workspace": "default"}).status_code == 200
+        )
 
 
 def mcp_client(body):

From bac5823abb7725ca5f61c16044cf7f6b7980a47e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 06:45:03 -0500
Subject: [PATCH 022/125] fix(validate): #1087 - refuse a full-frame H3 refine
 whose size disagrees with the upscaled latents

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/h3_rules.py | 27 ++++++++++++++++++++++++
 tests/test_h3_refine.py            | 33 ++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+)

diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index dfcf7004..8aa89908 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -93,6 +93,33 @@ def refine_problems(arguments, canvas=None):
         )
     if arguments.get(REFINE_TILES_INPUT) is not None:
         problems.extend(_tile_problems(arguments, canvas))
+    elif canvas is not None:
+        problems.extend(_full_frame_problems(arguments, canvas))
+    return problems
+
+
+def _full_frame_problems(arguments, canvas):
+    """A full-frame refine's own width and height against the `latents` canvas
+    the static check read: an omitted size falls to the layout default
+    (TILE_LIMIT), and any size but the canvas's fails at the denoise."""
+    problems = []
+    for key, size, default in zip(("width", "height"), canvas, TILE_LIMIT):
+        value = arguments.get(key)
+        if value is None:
+            if size != default:
+                problems.append(
+                    f"refine_strength re-denoises the 'latents' canvas, "
+                    f"{canvas[0]}x{canvas[1]}, and this step sets no {key}, so its "
+                    f"layout falls to {TILE_LIMIT[0]}x{TILE_LIMIT[1]} - set width "
+                    f"{canvas[0]} and height {canvas[1]}"
+                )
+                break
+        elif _is_int(value) and value != size:
+            problems.append(
+                f"refine_strength re-denoises the 'latents' canvas, "
+                f"{canvas[0]}x{canvas[1]}, and the step's {key} {value} disagrees "
+                f"- set it to {size}"
+            )
     return problems
 
 
diff --git a/tests/test_h3_refine.py b/tests/test_h3_refine.py
index 587e8a92..f26b5903 100644
--- a/tests/test_h3_refine.py
+++ b/tests/test_h3_refine.py
@@ -808,3 +808,36 @@ def test_a_size_disagreeing_with_the_tensor_raises(self, run):
     def test_a_guide_raises(self, run):
         with pytest.raises(ValueError, match="refine_tiles.*guides"):
             run(guides=[{"video": "a.mp4"}])
+
+
+def full_frame_workflow(up_width=1920, up_height=1088, **sizes):
+    workflow = upscale_workflow(up_width, up_height)
+    arguments = workflow["steps"][2]["pipeline"]["arguments"]
+    del arguments["refine_tiles"]
+    arguments.update(sizes)
+    return workflow
+
+
+class TestFullFrameStatic:
+    def test_an_omitted_size_over_larger_latents_is_refused(self):
+        problems = refine_strength_errors(full_frame_workflow())
+        assert len(problems) == 1
+        assert problems[0]["path"].endswith("refine_strength")
+        assert "1920x1088" in problems[0]["message"]
+        assert "no width" in problems[0]["message"]
+
+    def test_a_disagreeing_height_is_refused(self):
+        problems = refine_strength_errors(full_frame_workflow(width=1920, height=768))
+        assert len(problems) == 1
+        assert "height 768" in problems[0]["message"]
+
+    def test_a_matching_size_is_clean(self):
+        assert (
+            refine_strength_errors(full_frame_workflow(width=1920, height=1088)) == []
+        )
+
+    def test_latents_at_the_layout_default_need_no_size(self):
+        assert refine_strength_errors(full_frame_workflow(1344, 768)) == []
+
+    def test_an_unknown_canvas_is_not_checked(self):
+        assert errors_for(step_with()) == []

From ef73cf08d686dfc466ac863c502a08eff0180550 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 06:49:21 -0500
Subject: [PATCH 023/125] fix(plan): #1088 - price a single-file LoRA as its
 file, not its whole repo

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/plan_downloads.py | 33 +++++++++++++++++++++++------
 tests/test_plan.py   | 50 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 76 insertions(+), 7 deletions(-)

diff --git a/dw/plan_downloads.py b/dw/plan_downloads.py
index 4153384a..094fb3f1 100644
--- a/dw/plan_downloads.py
+++ b/dw/plan_downloads.py
@@ -35,6 +35,8 @@
 MODEL_NAME_KEY = "model_name"
 # An adapter names its repo directly, not through from_pretrained_arguments
 LORAS_KEY = "loras"
+WEIGHT_NAME_KEY = "weight_name"
+SUBFOLDER_KEY = "subfolder"
 SINGLE_FILE_KEY = "from_single_file"
 VARIANT_KEY = "variant"
 LOAD_COMPONENTS_KEY = "load_components"
@@ -63,7 +65,7 @@ def downloads_required(expanded, base_dir, workflow_dir, cache_dir, lookup_sizes
     variants = {}
     urls = []
     files = []
-    _collect_sources(expanded, names, variants, urls)
+    _collect_sources(expanded, names, variants, urls, files)
     _collect_task_weights(expanded, names, files, urls)
     for path, _arguments in _sub_workflow_paths(expanded):
         raw = read_sub_workflow(path, base_dir, workflow_dir)
@@ -73,7 +75,7 @@ def downloads_required(expanded, base_dir, workflow_dir, cache_dir, lookup_sizes
             child = json.loads(raw)
         except ValueError:
             continue
-        _collect_sources(child, names, variants, urls)
+        _collect_sources(child, names, variants, urls, files)
         _collect_task_weights(child, names, files, urls)
     present = {repo.get("repo_id") for repo in scan_models(cache_dir).get("repos", [])}
     required = []
@@ -121,7 +123,7 @@ def downloads_required(expanded, base_dir, workflow_dir, cache_dir, lookup_sizes
     return required
 
 
-def _collect_sources(tree, names, variants, urls):
+def _collect_sources(tree, names, variants, urls, files=None):
     """Every from_pretrained source in a tree, first-seen order, deduplicated.
     `variants` collects each name's requested `variant` (first-seen), used to
     tell a repo that is merely missing its fp16 files from one that is fully
@@ -133,11 +135,30 @@ def _collect_sources(tree, names, variants, urls):
     every base weight but not the IC-LoRA answered `downloads_required:
     []` and then pulled it mid-run, which is the one question the field
     exists to answer (found verifying #151).
+
+    A `loras` entry that names its `weight_name` loads that one file, so with
+    `files` given it is keyed there as `(repo, [subfolder/]weight_name, None)`
+    and sized as the file, not as the repo it sits in (#1088). A weight name
+    still holding a reference is no file yet: the repo stands for it.
     """
     if isinstance(tree, dict):
         for lora in tree.get(LORAS_KEY) or []:
             name = lora.get(MODEL_NAME_KEY) if isinstance(lora, dict) else None
-            if isinstance(name, str) and name not in names:
+            if not isinstance(name, str):
+                continue
+            weight = lora.get(WEIGHT_NAME_KEY)
+            if (
+                files is not None
+                and isinstance(weight, str)
+                and not references.is_ref(references.DEFERRED, weight)
+            ):
+                subfolder = lora.get(SUBFOLDER_KEY)
+                if isinstance(subfolder, str) and subfolder:
+                    weight = f"{subfolder.strip('/')}/{weight}"
+                key = (name, weight, None)
+                if key not in files:
+                    files.append(key)
+            elif name not in names:
                 names.append(name)
         source = tree.get(FROM_PRETRAINED_KEY)
         if isinstance(source, dict):
@@ -152,10 +173,10 @@ def _collect_sources(tree, names, variants, urls):
                 urls.append(single)
         _collect_component_overrides(tree.get(LOAD_COMPONENTS_KEY), names)
         for value in tree.values():
-            _collect_sources(value, names, variants, urls)
+            _collect_sources(value, names, variants, urls, files)
     elif isinstance(tree, list):
         for value in tree:
-            _collect_sources(value, names, variants, urls)
+            _collect_sources(value, names, variants, urls, files)
 
 
 def _collect_component_overrides(arguments, names):
diff --git a/tests/test_plan.py b/tests/test_plan.py
index c39929c7..bd2ff203 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -2306,6 +2306,12 @@ def repos(self, present, monkeypatch):
         monkeypatch.setattr(
             dw.plan_downloads, "repo_download_incomplete", lambda *a, **k: False
         )
+        # The adapter names a file, so it is checked file by file
+        monkeypatch.setattr(
+            dw.plan_downloads,
+            "_cached_file",
+            lambda repo, *a, **k: "cached" if repo in present else None,
+        )
         return [
             entry["repo"]
             for entry in dw.plan_downloads.downloads_required(
@@ -2313,6 +2319,48 @@ def repos(self, present, monkeypatch):
             )
         ]
 
+    def test_a_single_file_adapter_is_sized_as_the_file_not_the_repo(self, monkeypatch):
+        """#1088: priced as its whole repo (104.7 GB for a 5.9 GB file)."""
+        import dw.plan_downloads
+
+        monkeypatch.setattr(dw.plan_downloads, "scan_models", lambda *a: {})
+        monkeypatch.setattr(dw.plan_downloads, "_cached_file", lambda *a: None)
+        monkeypatch.setattr(
+            dw.plan_downloads,
+            "_model_info",
+            lambda name: (104.7, False, None),
+        )
+        monkeypatch.setattr(
+            dw.plan_downloads,
+            "_file_info",
+            lambda repo, filename, revision: (5.9, None),
+        )
+        definition = self.definition()
+        definition["steps"][0]["pipeline"]["loras"][0]["subfolder"] = "loras"
+        entries = dw.plan_downloads.downloads_required(
+            definition, None, None, None, True
+        )
+        adapter = [e for e in entries if "IC-LoRA" in e["repo"]]
+        assert [(e["gb"], e["filename"]) for e in adapter] == [
+            (5.9, "loras/ic-lora.safetensors")
+        ]
+
+    def test_an_adapter_without_a_weight_name_is_still_the_whole_repo(
+        self, monkeypatch
+    ):
+        import dw.plan_downloads
+
+        monkeypatch.setattr(dw.plan_downloads, "scan_models", lambda *a: {})
+        definition = self.definition()
+        del definition["steps"][0]["pipeline"]["loras"][0]["weight_name"]
+        entries = dw.plan_downloads.downloads_required(
+            definition, None, None, None, False
+        )
+        assert [(e["repo"], "filename" in e) for e in entries] == [
+            ("Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients", False),
+            ("Lightricks/LTX-2.5-Diffusers", False),
+        ]
+
     def test_the_adapter_is_named_when_it_is_absent(self, monkeypatch):
         assert self.repos(["Lightricks/LTX-2.5-Diffusers"], monkeypatch) == [
             "Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients"
@@ -2332,8 +2380,8 @@ def test_nothing_is_named_when_both_are_present(self, monkeypatch):
 
     def test_both_are_named_on_an_empty_cache(self, monkeypatch):
         assert self.repos([], monkeypatch) == [
-            "Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients",
             "Lightricks/LTX-2.5-Diffusers",
+            "Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients",
         ]
 
 

From 908fbbaf8bd10dd91cf432fb4a9369a183dd5896 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 06:55:23 -0500
Subject: [PATCH 024/125] feat(h3): #1077 - a regional edit's job events name
 its cells, mask_grow and refine_strength

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/h3_mask_steps.py | 44 ++++++++++++++----
 tests/test_h3_mask.py                   | 59 +++++++++++++++++++++++++
 2 files changed, 94 insertions(+), 9 deletions(-)

diff --git a/dw/pipeline_processors/h3_mask_steps.py b/dw/pipeline_processors/h3_mask_steps.py
index ae234039..39c635f1 100644
--- a/dw/pipeline_processors/h3_mask_steps.py
+++ b/dw/pipeline_processors/h3_mask_steps.py
@@ -5,8 +5,6 @@
 level - `h3_mask.blocks()` imports it on first use (#790).
 """
 
-import logging
-
 import numpy as np
 import torch
 from diffusers.models import AutoencoderKLMiniMaxH3
@@ -21,6 +19,8 @@
     OutputParam,
 )
 
+from ..events import emit_log
+
 from .h3_mask import keep_rows
 from .h3_rules import (
     KEEP_ROWS,
@@ -34,7 +34,20 @@
     media_problems,
 )
 
-logger = logging.getLogger("dw")
+
+def edit_summary(keep, grow, strength):
+    """The log line naming what a `source_video` edit regenerates and how
+    hard - `keep` is the per-row bool the mask maps to, None for no mask."""
+    if keep is None:
+        return (
+            f"Regional edit: no mask, re-denoising the whole source_video at "
+            f"refine_strength {strength}"
+        )
+    kept = int(keep.sum())
+    return (
+        f"Regional edit: regenerating {keep.shape[0] - kept} of {keep.shape[0]} "
+        f"patch cells ({kept} kept), mask_grow {grow}, refine_strength {strength}"
+    )
 
 
 def fit_source_frames(frames, num_frames):
@@ -87,6 +100,11 @@ def inputs(self):
                 default=MASK_GROW_DEFAULT,
                 description="Patch cells the mask is widened by.",
             ),
+            InputParam(
+                name=REFINE_STRENGTH_INPUT,
+                default=None,
+                description="Read here only to name it in the regional edit's log line.",
+            ),
             InputParam(name="latents", type_hint=torch.Tensor, required=True),
             InputParam(name="num_condition_video_rows", type_hint=int, default=0),
             InputParam(name="height", type_hint=int, required=True),
@@ -143,26 +161,34 @@ def __call__(self, components, state):
         setattr(block_state, SOURCE_ROWS, rows.clone())
 
         mask = getattr(block_state, REGENERATE_MASK)
+        grow = getattr(block_state, MASK_GROW_INPUT)
+        grow = MASK_GROW_DEFAULT if grow is None else grow
         keep = None
         if mask is not None:
-            grow = getattr(block_state, MASK_GROW_INPUT)
             keep = keep_rows(
                 mask,
                 block_state.num_latent_frames,
                 block_state.latent_height,
                 block_state.latent_width,
                 components.patch_size,
-                MASK_GROW_DEFAULT if grow is None else grow,
+                grow,
             )
             if keep.shape[0] != rows.shape[0]:
                 raise ValueError(
                     f"the mask maps to {keep.shape[0]} rows, and the step "
                     f"generates {rows.shape[0]}"
                 )
-            logger.info(
-                f"Regional edit: regenerating {int((~keep).sum())} of "
-                f"{keep.shape[0]} video rows"
-            )
+        # An event, not just the log, so a job's events say a regional edit
+        # ran, over how much of the take, and how hard (#1077)
+        strength = getattr(block_state, REFINE_STRENGTH_INPUT)
+        emit_log(
+            edit_summary(keep, grow, strength),
+            regenerated_cells=None if keep is None else int((~keep).sum()),
+            kept_cells=None if keep is None else int(keep.sum()),
+            mask_grow=grow,
+            refine_strength=strength,
+        )
+        if keep is not None:
             keep = torch.from_numpy(keep).to(latents.device)
         setattr(block_state, KEEP_ROWS, keep)
         self.set_block_state(state, block_state)
diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
index b51f40a0..7b9fb761 100644
--- a/tests/test_h3_mask.py
+++ b/tests/test_h3_mask.py
@@ -510,6 +510,65 @@ def test_no_source_video_returns_the_state_untouched(self):
         assert state.get(SOURCE_ROWS) is None
         assert state.get(KEEP_ROWS) is None
 
+    def run_block(self, monkeypatch, mask, strength):
+        """The block over a 3-latent-frame SIDE canvas with the VAE encode
+        stubbed, and the events it emitted."""
+        from dw.events import RunContext, activate_context, deactivate_context
+        from dw.pipeline_processors import h3_mask_steps
+
+        monkeypatch.setattr(
+            h3_mask_steps.encoders,
+            "encode_vae_condition",
+            lambda *a: torch.zeros(1, 1, 3, LATENT_SIDE, LATENT_SIDE),
+        )
+        state = PipelineState()
+        state.set("latents", torch.randn(3 * 4 * 4, 4))
+        state.set("source_video", np.zeros((9, SIDE, SIDE, 3), dtype=np.uint8))
+        state.set(REGENERATE_MASK, mask)
+        state.set("mask_grow", 0)
+        state.set("refine_strength", strength)
+        for name, value in (("height", SIDE), ("width", SIDE), ("num_frames", 9)):
+            state.set(name, value)
+        state.set("num_latent_frames", 3)
+        state.set("latent_height", LATENT_SIDE)
+        state.set("latent_width", LATENT_SIDE)
+        components = SimpleNamespace(
+            vae=None,
+            pixel_mean=None,
+            pixel_std=None,
+            keyframe_encode_seed=0,
+            patch_size=PATCH,
+            _execution_device="cpu",
+        )
+        events = []
+        token = activate_context(RunContext(on_event=events.append))
+        try:
+            h3_mask_steps.DwH3SourceLatentsStep()(components, state)
+        finally:
+            deactivate_context(token)
+        return state, [e for e in events if e.get("event") == "log"]
+
+    def test_a_masked_edit_emits_its_cells_grow_and_strength(self, monkeypatch):
+        # #1077: a job's events show the regional edit ran and how hard
+        mask = binarized(pixel_mask(1, (0, 0, 0)))
+        state, logs = self.run_block(monkeypatch, mask, 0.9)
+
+        assert len(logs) == 1
+        log = logs[0]
+        assert log["regenerated_cells"] == 3 and log["kept_cells"] == 45
+        assert log["mask_grow"] == 0 and log["refine_strength"] == 0.9
+        assert "3 of 48 patch cells" in log["message"]
+        assert "refine_strength 0.9" in log["message"]
+        assert int((~state.get(KEEP_ROWS)).sum()) == 3
+
+    def test_an_unmasked_edit_says_it_re_denoises_the_whole_take(self, monkeypatch):
+        state, logs = self.run_block(monkeypatch, None, 0.5)
+
+        assert len(logs) == 1
+        assert logs[0]["regenerated_cells"] is None
+        assert "whole source_video at refine_strength 0.5" in logs[0]["message"]
+        assert state.get(KEEP_ROWS) is None
+
 
 # 5. Rule refusals
 

From 9ae694b4920ab5ca444949b654440d3e4b642ae5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:13:25 -0500
Subject: [PATCH 025/125] fix(plan): #1088 - build a LoRA's file entry through
 file_entries

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md |  2 +-
 dw/plan_downloads.py | 12 +++++++++---
 tests/test_plan.py   | 21 +++++++++++++++++++++
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index df2fc0f7..bdced1da 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -98,7 +98,7 @@ one to open.
 | Variable constraints | `dw/variable_constraints.py`: `apply_constraints`; the grid arithmetic `aligned` / `aligned_down` | A model's rule about a value is declared in the workflow's `variable_constraints`, and it is checked at validation and again before anything loads. `plan_cuts` (and its static check) rounds render lengths through `aligned` / `aligned_down`, never its own copy, so a planned `num_frames` is one the template's constraint accepts; `crop_face_track` pads its crops to the step's `modulus`/`remainder` grid through `aligned` too (`padding_to_grid`). | `tests/test_variable_constraints.py::TestTheGrid::test_without_snap_an_off_grid_value_is_refused_not_rounded`, `tests/test_variable_constraints.py::TestTheGrid::test_plan_cuts_rounds_through_the_constraint_owner`, `tests/test_face_track.py::TestPadding::test_padding_to_grid_rounds_through_the_constraint_owner`, `tests/test_variable_constraints.py::TestTheRunTimePass::test_an_illegal_value_is_refused_before_anything_loads` |
 | Bound acknowledgement | `dw/plan.py`: `fingerprint`, `dw/server/admission.py`: `check_bound_acknowledgement` | A bound `acknowledged_cost` is refused with 409 when the plan's fingerprint or its required downloads changed. The fingerprint is keyed only by what can change the output: `DOCUMENTATION_KEYS` (`cost`, `cost_drivers`, `vram_estimate`, descriptions, catalog shape/traits), a constraint's `reason` and a result's role, subfolder and file name are left out, of the workflow and of each composed child; every schema key is sorted into left out or kept. A number digests by value, not spelling (`12.0` as `12`), and the seed stays out (#85). | `tests/test_plan.py::TestFingerprintKeys::test_the_exclusion_lists_are_pinned`, `tests/test_plan.py::TestTheCatalogH3Template::test_a_client_round_trip_keeps_it`, `tests/test_plan.py::TestFingerprintKeys::test_every_top_level_schema_key_is_sorted`, `tests/test_server.py::TestBoundRerun::test_a_rerun_bound_to_a_stale_plan_is_refused`, `tests/test_server.py::TestBoundAcknowledgement::test_a_matching_fingerprint_queues` |
 | Per-repo gating | `dw/plan_downloads.py`: `_model_info`, `_probe_gate_blocked`, assembled by `dw/plan.py`: `build_plan` | Each gated repo, including a `loras` entry's repo, is probed and reported on its own. | `tests/test_plan.py::TestDownloadsRequired::test_a_gated_repo_this_token_lacks_access_to_is_blocked` |
-| Download sources | `dw/plan_downloads.py`: `downloads_required`, `_collect_sources`, `_collect_component_overrides`, `_sub_workflow_paths` (which `plan.estimate` walks children by too; the module never imports `dw/plan.py` back, and `plan.py` re-exports `downloads_required` and `gate_warnings`) | `downloads_required` lists every `model_name`, `loras` repo, single-file URL and `load_components.pretrained_model_name_or_path` override (string, per-component dict, `default`), once each. The base repo stays listed whole: an override's replaced subfolder is not subtracted, so the list is a floor. | `tests/test_plan.py::TestDownloadsRequired::test_a_load_components_repo_override_is_listed` |
+| Download sources | `dw/plan_downloads.py`: `downloads_required`, `_collect_sources`, `_collect_component_overrides`, `_sub_workflow_paths` (which `plan.estimate` walks children by too; the module never imports `dw/plan.py` back, and `plan.py` re-exports `downloads_required` and `gate_warnings`) | `downloads_required` lists every `model_name`, `loras` repo (a `loras` entry naming a resolved `weight_name` is listed instead as a `{repo, filename, revision}` file entry built by `file_entries`, sized as that file), single-file URL and `load_components.pretrained_model_name_or_path` override (string, per-component dict, `default`), once each. The base repo stays listed whole: an override's replaced subfolder is not subtracted, so the list is a floor. | `tests/test_plan.py::TestDownloadsRequired::test_a_load_components_repo_override_is_listed` |
 | Task weights | each fetching task's `*_source(arguments)` (e.g. `dw/tasks/remove_object.py`: `remover_source`); `dw/tasks/weights.py`: `argument_or_default`, `file_entries`, `package_dir`; `dw/tasks/registry.py`: `required_weights_hook`, `register_weights_fallback`; `dw/tasks/image_utils.py`: `processor_weights_hook`; `dw/security.py`: `validate_weight_name`; `dw/plan_downloads.py`: `_collect_task_weights`, `_file_info` | A model-backed task declares `required_weights(arguments)` on its `register_command`, and `downloads_required` lists those repos beside the pipeline `model_name`s (a shared repo once; a reference or local-path argument none). A single-file task lists `{repo, filename, revision}` entries, checked per file against the cache; `restore_faces` also lists facexlib's weights as URL entries. A task's declaration and its loader read the same resolution of which argument wins (a single-file task's `*_source(arguments)`, an overridable whole-repo task's `argument_or_default` call, a fixed repo's module constant), so they cannot differ; `argument_or_default` is the shared helper only where `None` means the default (`remover_source` and `upscaler_source` treat any falsy value as absent; `spandrel_source` has no default). `file_entries` builds a file entry (its name checked by `validate_weight_name`), `package_dir` finds facexlib's weights dir without importing it, and `_file_info` sizes one file. The lookup path is acyclic: `dw/locations.py` reads the registry's tables and the task modules import the location policy and `weights.py`, so the registry imports no task module (an image processor's hook reaches it through `register_weights_fallback`, which `image_utils` calls at import) and `weights.py` imports only `dw/security.py`, where `validate_weight_name` lives for that reason. A task module the hook lookup imports keeps `transformers` out of its module top (`hf_pipeline` is a lazy wrapper, patched by name in the tests), so a validate never pays for it. | `tests/test_task_weights.py`, `tests/test_task_weights.py::TestTheHookPathStaysAcyclic::test_weights_imports_only_the_security_leaf_from_dw`, `tests/test_task_weights.py::TestTheHookPathStaysAcyclic::test_the_registry_imports_nothing_from_dw` |
 | Observed cost | `dw/server/observed_cost.py`: `declared_drivers`, `ObservedCosts._on_this_card`, `ObservedCosts.card` | `observed` comes only from this box's finished jobs on the named card (the one `route` names, for `plan.estimate`), else the server's own card; `ObservedCosts.card` owns a card's (kind, name, default). Rows are matched by card name whatever index they ran on (a job from before jobs carried a `device` counts only while the server is on the default card), and never writes `cost`. Cold and warm runs are reported separately. | `tests/test_observed_cost.py::TestColdIsNotWarm::test_the_two_are_reported_separately_each_with_its_runs`, `tests/test_observed_cost.py::TestByCard::test_only_rows_from_this_card_count_whichever_index_they_had`, `tests/test_observed_cost.py::TestByCard::test_rows_from_before_jobs_carried_a_device_do_not_count_off_the_default_card` |
 | The estimate | `dw/plan.py`: `estimate`, `_tempered`; the driver scaling is `dw/cost_scaling.py`: `scale_curated`, `_driver_scaling` | `plan.estimate` quotes the observed figure ahead of the curated one, and blends it toward the curated figure below three runs. A `cost` entry is measured at the workflow's variable defaults; a run moving `num_inference_steps`, `width`/`height` or `num_frames` (per list entry, summed) scales it in proportion (`scale_curated`, which `dw/server/deps.py` reuses for an inherited figure), basis `derived` with `scaled` naming each axis, times the list-length re-price, and that scaled figure is what a thin observed one blends toward (#866). | `tests/test_plan.py::TestObservedEstimate::test_history_beats_a_curated_figure`, `tests/test_plan.py::TestLowConfidenceObservedEstimate::test_a_single_run_blends_toward_the_curated_figure`, `tests/test_plan.py::TestDriverScaling::test_steps_canvas_and_frames_multiply`, `tests/test_plan.py::TestScalingAccuracy::test_within_thirty_percent` |
diff --git a/dw/plan_downloads.py b/dw/plan_downloads.py
index 094fb3f1..ca04fb75 100644
--- a/dw/plan_downloads.py
+++ b/dw/plan_downloads.py
@@ -139,7 +139,8 @@ def _collect_sources(tree, names, variants, urls, files=None):
     A `loras` entry that names its `weight_name` loads that one file, so with
     `files` given it is keyed there as `(repo, [subfolder/]weight_name, None)`
     and sized as the file, not as the repo it sits in (#1088). A weight name
-    still holding a reference is no file yet: the repo stands for it.
+    still holding a reference is no file yet, and a name `file_entries`
+    refuses is none either: the repo stands for it.
     """
     if isinstance(tree, dict):
         for lora in tree.get(LORAS_KEY) or []:
@@ -147,6 +148,7 @@ def _collect_sources(tree, names, variants, urls, files=None):
             if not isinstance(name, str):
                 continue
             weight = lora.get(WEIGHT_NAME_KEY)
+            entries = []
             if (
                 files is not None
                 and isinstance(weight, str)
@@ -155,10 +157,14 @@ def _collect_sources(tree, names, variants, urls, files=None):
                 subfolder = lora.get(SUBFOLDER_KEY)
                 if isinstance(subfolder, str) and subfolder:
                     weight = f"{subfolder.strip('/')}/{weight}"
-                key = (name, weight, None)
+                from .tasks.weights import file_entries
+
+                entries = file_entries(name, weight, None)
+            for entry in entries:
+                key = (entry["repo"], entry["filename"], entry["revision"])
                 if key not in files:
                     files.append(key)
-            elif name not in names:
+            if not entries and name not in names:
                 names.append(name)
         source = tree.get(FROM_PRETRAINED_KEY)
         if isinstance(source, dict):
diff --git a/tests/test_plan.py b/tests/test_plan.py
index bd2ff203..5f78b8f4 100644
--- a/tests/test_plan.py
+++ b/tests/test_plan.py
@@ -2361,6 +2361,27 @@ def test_an_adapter_without_a_weight_name_is_still_the_whole_repo(
             ("Lightricks/LTX-2.5-Diffusers", False),
         ]
 
+    def test_an_adapter_file_climbing_out_is_priced_as_the_repo(self, monkeypatch):
+        """file_entries refuses a name that is not plain and relative, so the
+        cache lookup never joins it onto the disk; the repo stands for it."""
+        import dw.plan_downloads
+
+        monkeypatch.setattr(dw.plan_downloads, "scan_models", lambda *a: {})
+        looked_up = []
+        monkeypatch.setattr(
+            dw.plan_downloads, "_cached_file", lambda *a: looked_up.append(a)
+        )
+        definition = self.definition()
+        definition["steps"][0]["pipeline"]["loras"][0]["subfolder"] = ".."
+        entries = dw.plan_downloads.downloads_required(
+            definition, None, None, None, False
+        )
+        assert [(e["repo"], "filename" in e) for e in entries] == [
+            ("Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients", False),
+            ("Lightricks/LTX-2.5-Diffusers", False),
+        ]
+        assert looked_up == []
+
     def test_the_adapter_is_named_when_it_is_absent(self, monkeypatch):
         assert self.repos(["Lightricks/LTX-2.5-Diffusers"], monkeypatch) == [
             "Lightricks/LTX-2.5-22b-IC-LoRA-Ingredients"

From 3b8a4dafc3356afcfaba2f5fca3b185d2f22788f Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:16:21 -0500
Subject: [PATCH 026/125] docs(mcp): #1089 - H3 lead-in is mostly the first
 denoise pass, not the reference encode

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/MCP.md                           | 16 +++++++++++-----
 plugins/dw/skills/minimax-h3/SKILL.md |  6 ++++--
 2 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index cbda3203..0bdbb050 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -424,11 +424,17 @@ one phase, so two polls otherwise come back identical: read `denoise_step`
 moving (slow but healthy) against a `denoise_step` that is a number and
 stays put while `seconds_since_event` climbs (nothing is happening). A null
 `denoise_step` under `generating` is neither - it is the lead-in the
-pipeline runs before the loop, encoding the prompt and every reference, with
-nothing emitted, so silence there is expected. Its length follows what it
-encodes: ~90 s on MiniMax H3 for a prompt with an image or audio reference,
-~10 min once a *video* reference is among them (measured: 629 s for one 5 s
-960x544 clip on an RTX 3090). `get_job_events` names the block it is in
+pipeline runs before the loop, encoding the prompt and every reference and
+then the first denoise pass, with nothing emitted, so silence there is
+expected. On MiniMax H3 the first pass dominates the lead-in, not the encode,
+and it varies by card. The reference encode (`vae_encoder`) is about 6 s for
+an image reference and about 50-53 s for a 5 s 960x544 video reference;
+reference tokens make the first pass slower. Measured on lem: an image
+reference's lead-in was 187 s (job `f90a041af26a`: encode 26 s, first pass
+161 s); the same image + video job took 508 s on cuda:1 (`f5aefcdd5e26`:
+`vae_encoder` 59 s, first pass 422 s) and 165 s on cuda:0 (`6961876f11d3`:
+`vae_encoder` 56 s, first pass 86 s). Plan for several minutes, up to ~10,
+with a video reference. `get_job_events` names the block it is in
 while that runs - a `log` line per top-level block of a modular pipeline
 (`MiniMaxAI/MiniMax-H3: vae_encoder`), which is the difference between
 silence and knowing it is encoding the reference. And once the counter is a number the gaps
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 26a8623e..8a909552 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -166,8 +166,10 @@ A wanted look (clay, paper): `references/style.md`.
    (`timeout_capped` says the server's cap cut it; call again while
    `still_running`; on a client "timed out", retry at `timeout_seconds` 60), then `get_job`. A cancelled H3 job runs
    to its next step boundary. Silence is no hang: `denoise_step` is null
-   through the reference encode (~90 s; 629 s for a video reference on a
-   3090) and the block cache makes later steps uneven -
+   through the lead-in, the reference encode plus the first denoise pass
+   (the first pass dominates and varies by card: 165-508 s with a video
+   reference, jobs `6961876f11d3`/`f5aefcdd5e26`; the encode alone is ~6 s
+   for an image reference, ~50 s for a 5 s video) and the block cache makes later steps uneven -
    two-minute gaps are healthy; so is a slow first step at a new size (autotune, once a box). `phase_stall` in `get_job_events` narrates
    it, not a fault; judge by `denoise_step`. Each entry carries `subfolder`:
    `final` is the deliverable (`episode`, `music_video`, `voyage`),

From 7b104ebddb77d7aeaa71a932f584e99c1daa47c7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:17:47 -0500
Subject: [PATCH 027/125] fix(plugin): #1089 - keep minimax-h3 SKILL.md under
 its size cap

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/minimax-h3/SKILL.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 8a909552..3e8826c6 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -166,10 +166,8 @@ A wanted look (clay, paper): `references/style.md`.
    (`timeout_capped` says the server's cap cut it; call again while
    `still_running`; on a client "timed out", retry at `timeout_seconds` 60), then `get_job`. A cancelled H3 job runs
    to its next step boundary. Silence is no hang: `denoise_step` is null
-   through the lead-in, the reference encode plus the first denoise pass
-   (the first pass dominates and varies by card: 165-508 s with a video
-   reference, jobs `6961876f11d3`/`f5aefcdd5e26`; the encode alone is ~6 s
-   for an image reference, ~50 s for a 5 s video) and the block cache makes later steps uneven -
+   in the lead-in (encode ~6 s img, ~50 s video; 1st pass
+   dominates: 165-508 s) and the block cache makes later steps uneven -
    two-minute gaps are healthy; so is a slow first step at a new size (autotune, once a box). `phase_stall` in `get_job_events` narrates
    it, not a fault; judge by `denoise_step`. Each entry carries `subfolder`:
    `final` is the deliverable (`episode`, `music_video`, `voyage`),

From c5ed8bd771e5ecd41d87ca1adbabd5af52349eea Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:20:09 -0500
Subject: [PATCH 028/125] test(mcp): #1089 - the H3 skill carries the
 re-measured lead-in

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 tests/test_mcp_server.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index 8f496520..2d837148 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -1126,7 +1126,7 @@ async def test_wait_for_job_says_silence_is_not_a_hang():
 
 def test_the_h3_skill_carries_the_measured_lead_in():
     """The other half of that move: the numbers are not lost, they are in
-    the skill that loads when H3 is in play (#101)."""
+    the skill that loads when H3 is in play (#101; re-measured in #1089)."""
     import os
 
     path = os.path.join(
@@ -1140,7 +1140,8 @@ def test_the_h3_skill_carries_the_measured_lead_in():
     with open(path) as handle:
         text = handle.read()
 
-    assert "629 s" in text and "90 s" in text
+    assert "629 s" not in text
+    assert "165-508 s" in text and "~50 s video" in text
 
 
 @pytest.mark.asyncio

From eed146271a61e2a68603fc949fb2f27be61d5de1 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:29:41 -0500
Subject: [PATCH 029/125] fix(security): GHSA-75fh-g499-53cf,
 GHSA-9597-5qpq-55x6 - videos list and active result types gated at validate

SE-F045: join_windows, concat_videos and dissolve_videos register `videos`
as a media argument, so a bare path, a '..' path or an internal URL in the
list is refused at validation at its own index. The loader already refused
them at run time.

SE-F035: ACTIVE_DOCUMENT_TYPES moves to dw/content_types.py and the server
imports it, so result.content_type refuses all five types /outputs
sandboxes (application/xhtml+xml, application/xml and image/svg+xml were
stopped only by a result-type mismatch).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/SECURITY.md                   |  5 +--
 docs/SERVER.md                     |  4 +--
 dw/content_types.py                | 34 ++++++++++++------
 dw/locations.py                    |  5 +--
 dw/server/http_security.py         | 13 ++-----
 dw/tasks/video_handlers.py         |  4 ++-
 tests/test_locations.py            | 56 ++++++++++++++++++++++++++++++
 tests/test_security_web_headers.py | 28 +++++++++++----
 8 files changed, 114 insertions(+), 35 deletions(-)

diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index dd576e77..c3d68e96 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -325,8 +325,9 @@ SecurityError
 - **Arbitrary file read through a media argument** — a location a workflow
   supplies is confined to the roots it may read (`dw/locations.py`)
 - **Script on the UI's origin through an output** — a step's
-  `result.content_type` may not be `text/html` or `text/xml` (compared
-  without case or parameters): validation refuses it at
+  `result.content_type` may not be an active document type - `text/html`,
+  `application/xhtml+xml`, `text/xml`, `application/xml` or `image/svg+xml`
+  (compared without case or parameters): validation refuses it at
   `steps[i].result.content_type` and the writer refuses it again
   (`dw/content_types.py`). A file of an active type that reaches `/outputs`
   or `/inputs` anyway is served with `Content-Security-Policy: sandbox`
diff --git a/docs/SERVER.md b/docs/SERVER.md
index 9c636d98..2884a1f7 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -937,8 +937,8 @@ network:
   (`text/html`, `application/xhtml+xml`, `text/xml`, `application/xml`,
   `image/svg+xml`) carries `Content-Security-Policy: sandbox`: it opens
   under an opaque origin with no script. Range and ETag answers are
-  unchanged. The engine does not write `text/html` or `text/xml` results
-  at all (below), so such a file is one planted on disk.
+  unchanged. The engine does not write a result of any of those types
+  (below), so such a file is one planted on disk.
 - Requests carrying a `Host` header that names neither a loopback address
   nor the configured `--host` are rejected (400). A wildcard bind
   (`--host 0.0.0.0` or `::`) skips this check - clients reach such a
diff --git a/dw/content_types.py b/dw/content_types.py
index aa53ed1d..b01f425a 100644
--- a/dw/content_types.py
+++ b/dw/content_types.py
@@ -16,13 +16,15 @@
 prefix/suffix match (PIL's own format inference, a literal text or JSON
 write) with no narrower container to enforce a whitelist against.
 
-The one text/* exception is active content. `/outputs` serves a written
-file on the UI's own origin, without a token, so an .html or .xml output is
-a page whose script reads the API token the UI keeps in localStorage (#407).
-`text/html` and `text/xml` are the two active types the text writer can
-produce, so they are refused outright; the server also serves every active
-type it finds on disk under a `Content-Security-Policy: sandbox`, since a
-planted file never passes through here.
+The one exception is active content. `/outputs` serves a written file on
+the UI's own origin, without a token, so an .html, .xml or .svg output is a
+page whose script reads the API token the UI keeps in localStorage (#407).
+Every type in `ACTIVE_DOCUMENT_TYPES` is refused outright, whichever writer
+would take it - refusing only the two the text writer produces left
+`application/xml`, `application/xhtml+xml` and `image/svg+xml` stopped by
+nothing but a result-type mismatch (SE-F035). The same set is what the
+server serves under a `Content-Security-Policy: sandbox` when it finds one on
+disk, since a planted file never passes through here.
 """
 
 import logging
@@ -67,8 +69,18 @@
 # The only container encode_video writes - it always encodes h264 video
 MUXED_VIDEO_CONTENT_TYPE = "video/mp4"
 
-# Result types a browser would run as a document on the UI origin
-REFUSED_ACTIVE_CONTENT_TYPES = frozenset({"text/html", "text/xml"})
+# Types a browser renders as a document, where script runs: refused as a
+# result type here, and served under a CSP sandbox by /outputs and /inputs
+# (dw/server/routes/files.py)
+ACTIVE_DOCUMENT_TYPES = frozenset(
+    {
+        "text/html",
+        "application/xhtml+xml",
+        "text/xml",
+        "application/xml",
+        "image/svg+xml",
+    }
+)
 
 
 def _active_content_fault(value):
@@ -76,7 +88,7 @@ def _active_content_fault(value):
     # the same document type
     if (
         isinstance(value, str)
-        and value.split(";", 1)[0].strip().lower() in REFUSED_ACTIVE_CONTENT_TYPES
+        and value.split(";", 1)[0].strip().lower() in ACTIVE_DOCUMENT_TYPES
     ):
         return (
             f"Invalid content_type: {value!r} - active content is not written: "
@@ -160,7 +172,7 @@ def refuse_active_content_type(value):
 
 
 __all__ = [
-    "REFUSED_ACTIVE_CONTENT_TYPES",
+    "ACTIVE_DOCUMENT_TYPES",
     "content_type_errors",
     "content_type_fault",
     "guess_extension",
diff --git a/dw/locations.py b/dw/locations.py
index 30c38d7c..7090c90a 100644
--- a/dw/locations.py
+++ b/dw/locations.py
@@ -70,8 +70,9 @@
 # dw/tasks/registry.py) and this is a view of them. Each gets the same
 # validate-time refusal as a media key, rather than only the loader's one at
 # run time (#630) - join_windows' `source`, the finishing commands' `media`
-# and apply_lut's `lut` (#635, SE-F044), and the face-track and fit commands'
-# `clip`, `repaired`, `track` and `fit` (#773, SE-F045)
+# and apply_lut's `lut` (#635, SE-F044), the face-track and fit commands'
+# `clip`, `repaired`, `track` and `fit` (#773, SE-F045), and the joining
+# commands' `videos` list (SE-F045, GHSA-75fh-g499-53cf)
 TASK_MEDIA_ARGUMENTS = RegistryTable("media_arguments")
 
 # Of those, the arguments read from a local file only: no loader fetches
diff --git a/dw/server/http_security.py b/dw/server/http_security.py
index f169e0a4..47d6d8db 100644
--- a/dw/server/http_security.py
+++ b/dw/server/http_security.py
@@ -13,16 +13,9 @@
 from starlette.routing import Match, Route
 
 # Types a browser renders as a document, where script runs: /outputs and
-# /inputs serve these under a CSP sandbox (_sandbox_active_content)
-ACTIVE_DOCUMENT_TYPES = frozenset(
-    {
-        "text/html",
-        "application/xhtml+xml",
-        "text/xml",
-        "application/xml",
-        "image/svg+xml",
-    }
-)
+# /inputs serve these under a CSP sandbox (_sandbox_active_content). Owned by
+# the engine, which refuses the same set as a result type
+from ..content_types import ACTIVE_DOCUMENT_TYPES  # noqa: F401
 
 
 def query_token_ok(fn):
diff --git a/dw/tasks/video_handlers.py b/dw/tasks/video_handlers.py
index f82ca06b..93e9c032 100644
--- a/dw/tasks/video_handlers.py
+++ b/dw/tasks/video_handlers.py
@@ -50,6 +50,7 @@
         "fps": POSITIVE,
         "sample_rate": POSITIVE,
     },
+    media_arguments=("videos",),
 )
 def _handle_concat_videos(task, arguments, previous_pipelines):
     """Concatenate videos - and the audio generated with them - into one"""
@@ -69,6 +70,7 @@ def _handle_concat_videos(task, arguments, previous_pipelines):
         "match_levels_dbfs": FINITE,
         "fps": POSITIVE,
     },
+    media_arguments=("videos",),
 )
 def _handle_dissolve_videos(task, arguments, previous_pipelines):
     """Join videos with cross-dissolves, fading the whole from and to a colour"""
@@ -224,7 +226,7 @@ def _handle_restore_to_source(task, arguments, previous_pipelines):
     whole_numbers=("num_frames", "overlap"),
     choices={"curve": JOIN_WINDOWS_CURVES},
     static_check=join_windows_errors,
-    media_arguments=("source",),
+    media_arguments=("source", "videos"),
 )
 def _handle_join_windows(task, arguments, previous_pipelines):
     """Blend processed overlapping windows back into one video the source's length"""
diff --git a/tests/test_locations.py b/tests/test_locations.py
index 36f80093..f25fd511 100644
--- a/tests/test_locations.py
+++ b/tests/test_locations.py
@@ -867,6 +867,62 @@ def test_a_record_handed_on_as_a_dict_is_left_alone(
         assert location_errors(definition, base_dir=workflow_dir) == []
 
 
+class TestVideosArgument:
+    """The joining commands' `videos` list - a plural no media key matches -
+    is refused at validation, entry by entry, rather than only by the loader
+    once the job is queued (SE-F045)."""
+
+    COMMANDS = ["join_windows", "concat_videos", "dissolve_videos"]
+
+    @staticmethod
+    def _step(command, videos):
+        return {
+            "steps": [
+                {
+                    "name": "probe",
+                    "task": {"command": command, "arguments": {"videos": videos}},
+                }
+            ]
+        }
+
+    @pytest.mark.parametrize("command", COMMANDS)
+    @pytest.mark.parametrize(
+        "value",
+        [
+            "/etc/hostname",
+            "../../../../etc/hostname",
+            "http://127.0.0.1:8765/x.mp4",
+            "file:///etc/hostname",
+        ],
+    )
+    def test_an_unreadable_entry_is_an_error_at_its_index(
+        self, untrusted, workflow_dir, command, value
+    ):
+        definition = self._step(command, ["asset:a.mp4", value])
+
+        errors = location_errors(definition, base_dir=workflow_dir)
+
+        assert [error["path"] for error in errors] == [
+            "steps[0].task.arguments.videos[1]"
+        ]
+        assert "'videos'" in errors[0]["message"]
+
+    @pytest.mark.parametrize("command", COMMANDS)
+    def test_a_scalar_is_checked_too(self, untrusted, workflow_dir, command):
+        errors = location_errors(
+            self._step(command, "/etc/hostname"), base_dir=workflow_dir
+        )
+
+        assert [error["path"] for error in errors] == ["steps[0].task.arguments.videos"]
+
+    @pytest.mark.parametrize("command", COMMANDS)
+    def test_references_are_left_alone(self, untrusted, workflow_dir, command):
+        definition = self._step(
+            command, ["asset:a.mp4", "output:wf/run/b.mp4", "previous_result:c"]
+        )
+        assert location_errors(definition, base_dir=workflow_dir) == []
+
+
 class TestOwnOutputHint:
     """#951: a bare manifest file name is refused with `output:` as the fix."""
 
diff --git a/tests/test_security_web_headers.py b/tests/test_security_web_headers.py
index 91fba01a..d06b8c1a 100644
--- a/tests/test_security_web_headers.py
+++ b/tests/test_security_web_headers.py
@@ -13,6 +13,7 @@
 """
 
 import json
+import re
 
 import pytest
 from fastapi.testclient import TestClient
@@ -99,14 +100,15 @@ def _document_is_inert(response):
 
 
 class TestActiveOutputs:
-    """A workflow - which an MCP agent may author - could write an .html or
-    .xml output, and /outputs needs no token and shares the UI's origin.
-    Validation and the writer refuse those two result types (dw/
+    """A workflow - which an MCP agent may author - could write an .html,
+    .xml or .svg output, and /outputs needs no token and shares the UI's
+    origin. Validation and the writer refuse every active result type (dw/
     content_types.py); a planted file still reaches /outputs, so it is
     served sandboxed."""
 
     @pytest.mark.parametrize(
-        "content_type", ["text/html", "text/xml", "Text/HTML; charset=utf-8"]
+        "content_type",
+        [*ACTIVE_TYPES, "Text/HTML; charset=utf-8", " Image/SVG+XML"],
     )
     def test_validation_refuses_it_at_its_path(self, monkeypatch, content_type):
         from dw.workflow import Workflow
@@ -123,7 +125,7 @@ def test_an_inert_text_type_still_validates(self, monkeypatch, content_type):
         monkeypatch.setenv(TRUST_WORKFLOWS_ENV_VAR, "0")
         assert Workflow(_page(content_type), "", "").validation_errors() == []
 
-    @pytest.mark.parametrize("content_type", ["text/html", "text/xml"])
+    @pytest.mark.parametrize("content_type", ACTIVE_TYPES)
     def test_the_writer_refuses_it_without_validation(
         self, tmp_path, monkeypatch, content_type
     ):
@@ -133,12 +135,24 @@ def test_the_writer_refuses_it_without_validation(
 
         monkeypatch.setenv(TRUST_WORKFLOWS_ENV_VAR, "0")
         workflow = Workflow(_page(content_type), str(tmp_path / "out"), "")
-        with pytest.raises(InvalidInputError, match=content_type):
+        with pytest.raises(InvalidInputError, match=re.escape(content_type)):
             workflow.run({})
         assert not [
-            p for p in (tmp_path / "out").rglob("*") if p.suffix in (".html", ".xml")
+            p
+            for p in (tmp_path / "out").rglob("*")
+            if p.suffix in (".html", ".xhtml", ".xml", ".svg")
         ]
 
+    def test_validation_and_serving_name_the_same_types(self):
+        """One set decides both what is refused as a result and what /outputs
+        sandboxes - three of the five got through validation while the two
+        lists were kept apart (SE-F035)."""
+        from dw.content_types import ACTIVE_DOCUMENT_TYPES
+        from dw.server import http_security
+
+        assert ACTIVE_DOCUMENT_TYPES == frozenset(ACTIVE_TYPES)
+        assert http_security.ACTIVE_DOCUMENT_TYPES is ACTIVE_DOCUMENT_TYPES
+
     def test_the_api_refuses_to_queue_it(self, client):
         response = client.post("/api/jobs", json={"workflow": _page("text/html")})
         assert response.status_code == 400, response.text

From 3b714b2c884476d884f8cf66a9803a66b6dcf06d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:44:48 -0500
Subject: [PATCH 030/125] docs: #1089 - one encode metric in the lead-in
 breakdown, SERVER.md matches MCP.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/MCP.md                        | 11 ++++++-----
 docs/SERVER.md                     | 11 +++++++----
 dw/pipeline_processors/pipeline.py |  2 +-
 3 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/docs/MCP.md b/docs/MCP.md
index 0bdbb050..2466bca7 100644
--- a/docs/MCP.md
+++ b/docs/MCP.md
@@ -430,11 +430,12 @@ expected. On MiniMax H3 the first pass dominates the lead-in, not the encode,
 and it varies by card. The reference encode (`vae_encoder`) is about 6 s for
 an image reference and about 50-53 s for a 5 s 960x544 video reference;
 reference tokens make the first pass slower. Measured on lem: an image
-reference's lead-in was 187 s (job `f90a041af26a`: encode 26 s, first pass
-161 s); the same image + video job took 508 s on cuda:1 (`f5aefcdd5e26`:
-`vae_encoder` 59 s, first pass 422 s) and 165 s on cuda:0 (`6961876f11d3`:
-`vae_encoder` 56 s, first pass 86 s). Plan for several minutes, up to ~10,
-with a video reference. `get_job_events` names the block it is in
+reference's lead-in was 187 s (job `f90a041af26a`: `timing.encode_s` 26 s,
+first pass 161 s; of the encode, `vae_encoder` was 6 s); the same image +
+video job took 508 s on cuda:1 (`f5aefcdd5e26`: `encode_s` 86 s, first pass
+422 s; `vae_encoder` 59 s) and 165 s on cuda:0 (`6961876f11d3`: `encode_s`
+79 s, first pass 86 s; `vae_encoder` 56 s). Plan for several minutes, up to
+~8.5 min measured (508 s, `f5aefcdd5e26`), with a video reference. `get_job_events` names the block it is in
 while that runs - a `log` line per top-level block of a modular pipeline
 (`MiniMaxAI/MiniMax-H3: vae_encoder`), which is the difference between
 silence and knowing it is encoding the reference. And once the counter is a number the gaps
diff --git a/docs/SERVER.md b/docs/SERVER.md
index 9c636d98..0243049b 100644
--- a/docs/SERVER.md
+++ b/docs/SERVER.md
@@ -327,10 +327,13 @@ to learn where a long render is:
 
 A null `denoise_step` under `generating` is the pipeline's lead-in - encoding
 the prompt and every reference - which emits nothing and runs well over a
-minute on a large video model. How long it runs follows what it has to
-encode: on MiniMax H3, ~90 s for a prompt with an image or audio reference,
-but ~10 min once a *video* reference is among them - a measured run encoding
-one 5 s 960x544 clip on an RTX 3090 sat silent from 94 s to 723 s. The keys
+minute on a large video model. It is the encode plus the first denoise
+pass, and on MiniMax H3 the first pass dominates and varies by card. The
+reference encode (`vae_encoder`) is about 6 s for an image reference and
+about 50-53 s for a 5 s 960x544 video reference. Measured on lem: 187 s for
+an image reference (job `f90a041af26a`), and 508 s on cuda:1
+(`f5aefcdd5e26`, first pass 422 s) against 165 s on cuda:0
+(`6961876f11d3`, first pass 86 s) for the same image + video job. The keys
 are always present so that lead-in can be told from a loop that has stopped
 advancing: `seconds_since_event` is a stall signal once `denoise_step` is a
 number, or in any phase other than `generating`.
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index fa949924..2fe8ffab 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -691,7 +691,7 @@ def _call_pipeline(self, arguments, attn_backend):
                 # the difference between a slow run and a hung one
                 stack.enter_context(reported_progress_bars(self.pipeline))
                 # The bar only covers the denoise loop; the blocks around it
-                # are where a reference encode's minutes go (#95)
+                # are where the lead-in's minutes go (#95)
                 stack.enter_context(
                     reported_blocks(self.pipeline, self.segment_label or self.name)
                 )

From 677c04f3cdeb25a5bcc62a9e07797e39452047f0 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:52:52 -0500
Subject: [PATCH 031/125] docs: credit Longshot Studio for the #1091-#1095
 ideas

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ATTRIBUTIONS.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
index 1adb6efc..e42a5441 100644
--- a/docs/ATTRIBUTIONS.md
+++ b/docs/ATTRIBUTIONS.md
@@ -78,3 +78,17 @@ lightness, contrast and detail measures
 ([#1031](https://github.com/dkackman/diffusers-workflow/issues/1031)), and the
 `script-to-video` skill its guidance on re-rolling a chained segment whose seam
 fails ([#1034](https://github.com/dkackman/diffusers-workflow/issues/1034)).
+
+### [r34vtraining/Longshot_Studio](https://github.com/r34vtraining/Longshot_Studio)
+
+A ComfyUI studio for making long MiniMax H3 films shot by shot, assessed in
+October 2026. It has no licence, so only concepts are taken. Its ideas are
+filed as dialogue/effects stem separation
+([#1091](https://github.com/dkackman/diffusers-workflow/issues/1091)), an H3
+face refine with the audio held
+([#1092](https://github.com/dkackman/diffusers-workflow/issues/1092)), cutaway
+and lead-in joins ([#1093](https://github.com/dkackman/diffusers-workflow/issues/1093)),
+rendering the odd shots of a long take first and bridging the gaps
+([#1094](https://github.com/dkackman/diffusers-workflow/issues/1094)), and
+finding phrase starts from the centre of the stereo mix
+([#1095](https://github.com/dkackman/diffusers-workflow/issues/1095)).

From 73ceb378df55e85ca422f257e1f4ad07ed45306c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 07:54:56 -0500
Subject: [PATCH 032/125] feat(h3): #1082 - refine_sigmas, an explicit refine
 schedule

An H3 refine step takes an optional refine_sigmas list, run verbatim in
place of the shift-spaced grid for both the video and audio schedulers,
with row_timestep_plan rebuilt from it. h3_rules.refine_problems owns its
rules - at least 2 points, strictly decreasing, from refine_strength
(within 1e-6) to 0, one point per num_inference_steps, which is required
beside it - and both the static check and _check_refine ask it. Refused
without refine_strength; allowed with refine_tiles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                    |   2 +-
 docs/WORKFLOW_GUIDE.md                  |  33 ++++
 dw/hold_audio.py                        |  30 ++--
 dw/pipeline_processors/h3_hold.py       |   3 +-
 dw/pipeline_processors/h3_hold_steps.py |  45 ++++-
 dw/pipeline_processors/h3_rules.py      |  88 +++++++--
 dw/pipeline_processors/pipeline.py      |  19 +-
 tests/test_h3_refine.py                 | 226 ++++++++++++++++++++++++
 8 files changed, 405 insertions(+), 41 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index bdced1da..59501a5a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -112,7 +112,7 @@ one to open.
 | Acceleration warnings | `dw/acceleration_warnings.py`: `acceleration_warnings`, `CACHE_MIN_USEFUL_STEPS`, `CUDA_ONLY_ATTENTION_BACKENDS` (the last entry of `WARNING_CHECKS`) | An acceleration setting that can't pay off (a `first_block`/`mag` cache under `CACHE_MIN_USEFUL_STEPS`, any `taylorseer` cache, `compile.fullgraph` with a cache, a cache on a pipeline class with no transformer or whose transformer lacks `enable_cache()`, a CUDA-only `attention_backend` on a non-CUDA device) is a warning and never a refusal, and an unresolvable value (steps, backend, device) leaves it silent. | `tests/test_validation.py::TestAccelerationWarnings::test_warnings_never_refuse`, `tests/test_validation.py::TestAccelerationWarnings::test_steps_that_resolve_to_nothing_are_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unknown_device_is_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unresolvable_backend_is_silent_on_mps` |
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
-| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
+| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` and the explicit `refine_sigmas` schedule among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`, and `explicit_sigmas`, a step's `refine_sigmas` list run verbatim in place of the shift grid) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_refine.py::TestSigmaListOneOwner::test_the_runtime_message_is_the_owners`, `tests/test_h3_refine.py::TestSigmaListSchedule::test_the_block_runs_the_list_unshifted`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
 | IC-LoRA reference scale | `workflows/templates/ltx2/` | The four conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 74911581..0f8829d3 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2496,6 +2496,39 @@ refine with no `latents` or no `hold_audio`, a step that is not H3, and a
 To refine a canvas above 1344x768, such as a 1920x1088 plate, see [Refining above 768p in
 tiles](#refining-above-768p-in-tiles).
 
+#### Explicit refine sigmas
+
+A recipe published with its own schedule cannot be reached by spacing points with
+`shift`. `refine_sigmas` gives the schedule itself: the sigma points, from
+`refine_strength` down to 0, used verbatim for both the video and audio schedules, with no
+shift applied. NVlabs' Open-H3-Regenerate-2K recipe starts from
+`(1 - 0.909375)·up + 0.909375·noise` and runs 3 Euler steps on four points:
+
+```json
+"arguments": {
+    "latents": "previous_result:up",
+    "hold_audio": "previous_result:base.audio",
+    "refine_strength": 0.909375,
+    "num_inference_steps": 4,
+    "refine_sigmas": [0.909375, 0.857143, 0.666667, 0]
+}
+```
+
+`refine_strength` still sets the re-noise, and the list replaces only the spacing. The
+step count is the number of points, so `num_inference_steps` is required beside the list
+and must equal its length: four points are 3 denoise evaluations. Validation, and the
+check before the call, refuse a `refine_sigmas` that:
+
+- is not a list of numbers, or has fewer than 2 points;
+- is not strictly decreasing;
+- does not start at `refine_strength` (within 1e-6);
+- does not end at exactly 0;
+- has a length other than `num_inference_steps`, or comes with no `num_inference_steps`;
+- comes with no `refine_strength`.
+
+A step without `refine_sigmas` runs the shift-spaced schedule as before. It works with
+`refine_tiles` too: every tile runs the same list.
+
 ### H3: regional edit with source_video and a mask
 
 To change part of a take and keep the rest, pass a video as `source_video` on an H3
diff --git a/dw/hold_audio.py b/dw/hold_audio.py
index 313c13b9..69488ad0 100644
--- a/dw/hold_audio.py
+++ b/dw/hold_audio.py
@@ -27,6 +27,8 @@
 step passes no `latents` to refine
 or no `hold_audio` to keep its soundtrack, and when `num_inference_steps` is
 below 2 - the refine schedule is that many points, so one point is no step.
+An explicit `refine_sigmas` schedule is checked with it: a strictly decreasing
+list from `refine_strength` to 0 with one point per `num_inference_steps`.
 Those per-argument rules are `h3_rules.refine_problems`, which the run-time
 check calls too; only the H3 test is here.
 
@@ -46,6 +48,7 @@
     HOLD_AUDIO_INPUT,
     MASK_IMAGE_INPUT,
     MASK_INPUTS,
+    REFINE_SIGMAS_INPUT,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
     REGIONAL_EDIT_INPUTS,
@@ -170,36 +173,37 @@ def _upscaled_canvas(steps, latents):
     return None
 
 
+_REFINE_INPUTS = (REFINE_STRENGTH_INPUT, REFINE_SIGMAS_INPUT, REFINE_TILES_INPUT)
+
+
 def refine_strength_errors(workflow_definition, source_indices=None):
-    """Every `refine_strength` or `refine_tiles` argument refused before the
-    run, as [{path, message}] - walked the way `hold_audio_errors` walks. A
-    problem about `refine_tiles` is at its path; the rest are at
-    `refine_strength`'s."""
+    """Every `refine_strength`, `refine_sigmas` or `refine_tiles` argument
+    refused before the run, as [{path, message}] - walked the way
+    `hold_audio_errors` walks. A problem about `refine_sigmas` or
+    `refine_tiles` is at its path; the rest are at `refine_strength`'s."""
     errors = []
     steps = workflow_definition.get("steps")
     for _, _, pipeline, source, where in references.iter_steps(
         steps, source_indices, "pipeline"
     ):
         arguments = pipeline.get("arguments")
-        if not isinstance(arguments, dict) or (
-            arguments.get(REFINE_STRENGTH_INPUT) is None
-            and arguments.get(REFINE_TILES_INPUT) is None
+        if not isinstance(arguments, dict) or all(
+            arguments.get(name) is None for name in _REFINE_INPUTS
         ):
             continue
         paths = {
             name: render_path(("steps", source, "pipeline", "arguments", name))
-            for name in (REFINE_STRENGTH_INPUT, REFINE_TILES_INPUT)
+            for name in _REFINE_INPUTS
         }
         problems = []
-        for name in (REFINE_STRENGTH_INPUT, REFINE_TILES_INPUT):
+        for name in _REFINE_INPUTS:
             if arguments.get(name) is not None:
                 problems.append((name, not_h3(pipeline, name)))
         canvas = _upscaled_canvas(steps, arguments.get("latents"))
         for problem in refine_problems(arguments, canvas):
-            name = (
-                REFINE_TILES_INPUT
-                if problem.startswith(REFINE_TILES_INPUT)
-                else REFINE_STRENGTH_INPUT
+            name = next(
+                (n for n in _REFINE_INPUTS[1:] if problem.startswith(n)),
+                REFINE_STRENGTH_INPUT,
             )
             problems.append((name, problem))
         for name, problem in problems:
diff --git a/dw/pipeline_processors/h3_hold.py b/dw/pipeline_processors/h3_hold.py
index eb275b27..33943ef7 100644
--- a/dw/pipeline_processors/h3_hold.py
+++ b/dw/pipeline_processors/h3_hold.py
@@ -20,7 +20,8 @@
 - `DwH3RefineScheduleStep`, before `denoise` - after `set_timesteps`, whose
   schedule it replaces when `refine_strength` is passed: σ₀ = `refine_strength`,
   then `num_inference_steps` points down to 0 spaced by the scheduler's shift
-  (`refine_sigmas`), so `num_inference_steps - 1` evaluations. It re-noises the
+  (`refine_sigmas`), so `num_inference_steps - 1` evaluations - or, with a
+  `refine_sigmas` argument, that list verbatim (`explicit_sigmas`). It re-noises the
   generated video rows of a passed `latents` to σ₀. Every audio row has to be a
   held one (`hold_audio`): the audio scheduler gets the same list only so the
   loop's audio step finds its timesteps, and steps no row;
diff --git a/dw/pipeline_processors/h3_hold_steps.py b/dw/pipeline_processors/h3_hold_steps.py
index 83ac93b7..17159945 100644
--- a/dw/pipeline_processors/h3_hold_steps.py
+++ b/dw/pipeline_processors/h3_hold_steps.py
@@ -49,6 +49,7 @@
     HOLD_AUDIO_INPUT,
     REFINE_NOISE,
     REFINE_ROW_NOISE,
+    REFINE_SIGMAS_INPUT,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
 )
@@ -87,6 +88,23 @@ def refine_sigmas(strength, num_points, shift):
     return sigmas.float()
 
 
+def explicit_sigmas(points, strength):
+    """A caller's own `refine_sigmas` schedule as the float32 tensor
+    `set_timesteps(sigmas=...)` takes, used verbatim - no shift is applied.
+    Its first point is pinned to `strength` and its last to 0, the values
+    `h3_rules.refine_problems` already held them to within SIGMA_TOLERANCE,
+    so the re-noise and the schedule start from the same sigma.
+
+    Raises:
+        ValueError: If `points` has fewer than 2 points
+    """
+    sigmas = torch.tensor([float(point) for point in points], dtype=torch.float64)
+    if sigmas.numel() < 2:
+        raise ValueError(f"refine_sigmas needs at least 2 points, got {sigmas.numel()}")
+    sigmas[0], sigmas[-1] = float(strength), 0.0
+    return sigmas.float()
+
+
 def shifted_sigma_grid(num_points, shift, start=1.0):
     """`num_points` sigmas, float64, linear in the unshifted coordinate u from
     `start` down to 0 and mapped through σ = shift·u / (1 + (shift−1)·u). At
@@ -295,9 +313,9 @@ class DwH3RefineScheduleStep(ModularPipelineBlocks):
     def description(self):
         return (
             "dw: with `refine_strength`, re-denoises the passed `latents` from that sigma - replaces both "
-            "schedules with `num_inference_steps` shift-spaced points from it down to 0 and re-noises the "
-            "generated video rows to it. Needs every audio row held (`hold_audio`). Does nothing without "
-            "`refine_strength`."
+            "schedules with `num_inference_steps` shift-spaced points from it down to 0, or with "
+            "`refine_sigmas` when passed, and re-noises the generated video rows to it. Needs every audio "
+            "row held (`hold_audio`). Does nothing without `refine_strength`."
         )
 
     @property
@@ -313,6 +331,16 @@ def inputs(self):
                     "masked region from noise. Runs num_inference_steps - 1 evaluations."
                 ),
             ),
+            InputParam(
+                name=REFINE_SIGMAS_INPUT,
+                type_hint=list,
+                default=None,
+                description=(
+                    "An explicit refine schedule in place of the shift-spaced one: strictly decreasing sigma "
+                    "points from `refine_strength` down to 0, one per `num_inference_steps`, used verbatim "
+                    "for the video and audio schedules. Needs `refine_strength`."
+                ),
+            ),
             InputParam(
                 name=REFINE_TILES_INPUT,
                 type_hint=dict,
@@ -372,9 +400,13 @@ def __call__(self, components, state):
             )
 
         device = components._execution_device
-        sigmas = refine_sigmas(
-            strength, block_state.num_inference_steps, components.scheduler.shift
-        )
+        explicit = getattr(block_state, REFINE_SIGMAS_INPUT, None)
+        if explicit is not None:
+            sigmas = explicit_sigmas(explicit, strength)
+        else:
+            sigmas = refine_sigmas(
+                strength, block_state.num_inference_steps, components.scheduler.shift
+            )
         # Verbatim: set_timesteps(sigmas=...) applies no shift. The audio
         # schedule only has to match the video's for the loop's audio step,
         # which steps no row when every one is held
@@ -435,6 +467,7 @@ def __call__(self, components, state):
 
         logger.info(
             f"Refining from sigma {strength} over {len(block_state.timesteps)} steps"
+            + (f" on refine_sigmas {list(explicit)}" if explicit is not None else "")
         )
         self.set_block_state(state, block_state)
         return components, state
diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index 8aa89908..7d2a6908 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -21,8 +21,12 @@
 HELD_AUDIO_RATE_OUTPUT = "dw_held_audio_sampling_rate"
 HELD_LATENTS_OUTPUT = "dw_held_audio_latents"
 
-# The refine call argument
+# The refine call arguments: the sigma to start from, and an explicit schedule
+# from it down to 0 in place of the shift-spaced one (#1082)
 REFINE_STRENGTH_INPUT = "refine_strength"
+REFINE_SIGMAS_INPUT = "refine_sigmas"
+# How far a `refine_sigmas` first point may sit from `refine_strength`
+SIGMA_TOLERANCE = 1e-6
 
 # The block names dw inserts, and the diffusers block each goes in front of
 HOLD_BLOCK = "dw_hold_audio"
@@ -39,19 +43,25 @@
 
 
 def refine_problems(arguments, canvas=None):
-    """Why this step's `refine_strength` and `refine_tiles` cannot run, as a
-    list - empty when they can, or cannot be told yet. The one owner of the
-    per-argument rules: the static check (dw/hold_audio.py) and the run-time
-    check before the call (`Pipeline._check_refine`) both ask it. The sigma
-    is in (0, 1), or (0, 1] with a `source_video`: a regional edit at 1.0
-    regenerates its region from pure noise. A tile
-    problem's message starts with `refine_tiles`. `canvas` is the (width,
-    height) the static check read from the upscale step `latents` names, when
-    it could; at run time the `latents` tensor gives it."""
+    """Why this step's `refine_strength`, `refine_sigmas` and `refine_tiles`
+    cannot run, as a list - empty when they can, or cannot be told yet. The
+    one owner of the per-argument rules: the static check (dw/hold_audio.py)
+    and the run-time check before the call (`Pipeline._check_refine`) both ask
+    it. The sigma is in (0, 1), or (0, 1] with a `source_video`: a regional
+    edit at 1.0 regenerates its region from pure noise. A tile problem's
+    message starts with `refine_tiles`, a schedule problem's with
+    `refine_sigmas`. `canvas` is the (width, height) the static check read
+    from the upscale step `latents` names, when it could; at run time the
+    `latents` tensor gives it."""
     if arguments.get(REFINE_STRENGTH_INPUT) is None:
         return [
-            "refine_tiles tiles a refine_strength pass, and this step passes no "
-            "refine_strength - add one, about 0.2"
+            f"{name} {does} a refine_strength pass, and this step passes no "
+            f"refine_strength - add one, about 0.2"
+            for name, does in (
+                (REFINE_SIGMAS_INPUT, "schedules"),
+                (REFINE_TILES_INPUT, "tiles"),
+            )
+            if arguments.get(name) is not None
         ]
     problems = []
     strength = arguments[REFINE_STRENGTH_INPUT]
@@ -91,6 +101,8 @@ def refine_problems(arguments, canvas=None):
             f"refine_strength runs num_inference_steps - 1 denoise steps, so "
             f"num_inference_steps must be 2 or more, not {steps}"
         )
+    if arguments.get(REFINE_SIGMAS_INPUT) is not None:
+        problems.extend(_sigma_problems(arguments))
     if arguments.get(REFINE_TILES_INPUT) is not None:
         problems.extend(_tile_problems(arguments, canvas))
     elif canvas is not None:
@@ -98,6 +110,58 @@ def refine_problems(arguments, canvas=None):
     return problems
 
 
+def _number(value):
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _sigma_problems(arguments):
+    """Why this step's `refine_sigmas` cannot run - a list, empty when it can.
+    The list is the whole schedule, sigma points down to 0, standing in for
+    the shift-spaced one: at least 2 points, strictly decreasing, from
+    `refine_strength` (within SIGMA_TOLERANCE) to 0, one point per
+    `num_inference_steps` - which is required beside it and must agree."""
+    sigmas = arguments[REFINE_SIGMAS_INPUT]
+    if _deferred(sigmas):
+        return []
+    if not isinstance(sigmas, (list, tuple)) or not all(map(_number, sigmas)):
+        return [
+            f"refine_sigmas is a list of sigma points from refine_strength down "
+            f"to 0, and {sigmas!r} is not a list of numbers"
+        ]
+    problems = []
+    if len(sigmas) < 2:
+        problems.append(
+            f"refine_sigmas needs at least 2 points, refine_strength and 0, and "
+            f"has {len(sigmas)}"
+        )
+    elif any(later >= earlier for earlier, later in zip(sigmas, sigmas[1:])):
+        problems.append(
+            f"refine_sigmas must be strictly decreasing, and {list(sigmas)} is not"
+        )
+    strength = arguments[REFINE_STRENGTH_INPUT]
+    if sigmas and _number(strength) and abs(sigmas[0] - strength) > SIGMA_TOLERANCE:
+        problems.append(
+            f"refine_sigmas starts at refine_strength, {strength}, and its first "
+            f"point is {sigmas[0]}"
+        )
+    if sigmas and sigmas[-1] != 0:
+        problems.append(f"refine_sigmas ends at 0, and its last point is {sigmas[-1]}")
+    steps = arguments.get("num_inference_steps")
+    if steps is None:
+        problems.append(
+            f"refine_sigmas has {len(sigmas)} points, and this step sets no "
+            f"num_inference_steps - set it to {len(sigmas)}, one per point "
+            f"({len(sigmas) - 1} evaluations)"
+        )
+    elif _number(steps) and steps != len(sigmas):
+        problems.append(
+            f"refine_sigmas has {len(sigmas)} points, {len(sigmas) - 1} "
+            f"evaluations, and num_inference_steps {steps} runs {steps - 1} - "
+            f"set num_inference_steps to {len(sigmas)}"
+        )
+    return problems
+
+
 def _full_frame_problems(arguments, canvas):
     """A full-frame refine's own width and height against the `latents` canvas
     the static check read: an omitted size falls to the layout default
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index 2fe8ffab..03a6bac2 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -43,6 +43,7 @@
     HOLD_AUDIO_INPUT,
     MASK_IMAGE_INPUT,
     MASK_INPUTS,
+    REFINE_SIGMAS_INPUT,
     REFINE_STRENGTH_INPUT,
     REFINE_TILES_INPUT,
     REGENERATE_MASK,
@@ -874,16 +875,18 @@ def _check_refine(self, arguments):
         call (dw/pipeline_processors/h3_hold.py).
 
         Raises:
-            ValueError: If this pipeline cannot refine, the strength or step count
-                is out of range, or the step passes no `latents` or `hold_audio`
+            ValueError: If this pipeline cannot refine, the strength, the
+                `refine_sigmas` schedule or the step count is out of range, or the
+                step passes no `latents` or `hold_audio`
         """
-        strength = arguments.get(REFINE_STRENGTH_INPUT)
-        if strength is None and arguments.get(REFINE_TILES_INPUT) is None:
+        given = [
+            name
+            for name in (REFINE_STRENGTH_INPUT, REFINE_SIGMAS_INPUT, REFINE_TILES_INPUT)
+            if arguments.get(name) is not None
+        ]
+        if not given:
             return
-        where = (
-            f"Step '{self.name}': "
-            f"{REFINE_STRENGTH_INPUT if strength is not None else REFINE_TILES_INPUT}"
-        )
+        where = f"Step '{self.name}': {given[0]}"
         if not refines(self.pipeline):
             raise ValueError(
                 f"{where} is a MiniMax-H3 argument (t2va, fl2va or ref2va), and "
diff --git a/tests/test_h3_refine.py b/tests/test_h3_refine.py
index f26b5903..a8275364 100644
--- a/tests/test_h3_refine.py
+++ b/tests/test_h3_refine.py
@@ -21,6 +21,7 @@
 from dw.pipeline_processors.h3_rules import (
     HOLD_BLOCK,
     REFINE_BLOCK,
+    REFINE_SIGMAS_INPUT,
     REFINE_STRENGTH_INPUT,
     refine_problems,
 )
@@ -35,6 +36,7 @@
 from diffusers.schedulers import MiniMaxH3Scheduler  # noqa: E402
 from diffusers.utils.torch_utils import randn_tensor  # noqa: E402
 from dw.pipeline_processors.h3_hold_steps import (  # noqa: E402
+    explicit_sigmas,
     refine_sigmas,
     shifted_sigma_grid,
 )
@@ -841,3 +843,227 @@ def test_latents_at_the_layout_default_need_no_size(self):
 
     def test_an_unknown_canvas_is_not_checked(self):
         assert errors_for(step_with()) == []
+
+
+# 12. refine_sigmas - an explicit schedule (#1082)
+
+# The regenerate recipe: H3's stock 4-step grid from 0.909375
+RECIPE = [0.909375, 0.857143, 0.666667, 0]
+RECIPE_STRENGTH = 0.909375
+
+
+def explicit(**overrides):
+    arguments = {
+        "refine_strength": RECIPE_STRENGTH,
+        "num_inference_steps": len(RECIPE),
+        "refine_sigmas": list(RECIPE),
+    }
+    arguments.update(overrides)
+    return arguments
+
+
+BROKEN = [
+    pytest.param({"refine_sigmas": [0.909375]}, "at least 2 points", id="one-point"),
+    pytest.param(
+        {"refine_sigmas": [0.909375, 0.857143, 0.857143, 0]},
+        "strictly decreasing",
+        id="repeated-point",
+    ),
+    pytest.param(
+        {"refine_sigmas": [0.909375, 0.666667, 0.857143, 0]},
+        "strictly decreasing",
+        id="rising",
+    ),
+    pytest.param(
+        {"refine_sigmas": [0.9, 0.857143, 0.666667, 0]},
+        "starts at refine_strength",
+        id="off-strength",
+    ),
+    pytest.param(
+        {"refine_sigmas": [0.909375, 0.857143, 0.666667, 0.01]},
+        "ends at 0",
+        id="not-to-zero",
+    ),
+    pytest.param(
+        {"num_inference_steps": 5}, "set num_inference_steps to 4", id="count"
+    ),
+    pytest.param(
+        {"num_inference_steps": None}, "sets no num_inference_steps", id="no-steps"
+    ),
+    pytest.param(
+        {"refine_sigmas": "0.9,0.5,0"}, "not a list of numbers", id="not-a-list"
+    ),
+    pytest.param(
+        {"refine_sigmas": [0.909375, "half", 0]},
+        "not a list of numbers",
+        id="not-numbers",
+    ),
+    pytest.param(
+        {"refine_sigmas": [0.909375, True, 0]},
+        "not a list of numbers",
+        id="a-bool",
+    ),
+]
+
+
+class TestSigmaListStatic:
+    def test_the_regenerate_recipe_is_clean(self):
+        assert errors_for(step_with(**explicit())) == []
+
+    @pytest.mark.parametrize("overrides, fragment", BROKEN)
+    def test_a_broken_rule_is_refused_at_the_sigmas_path(self, overrides, fragment):
+        errors = errors_for(step_with(**explicit(**overrides)))
+        assert errors, overrides
+        assert all(e["path"].endswith("arguments.refine_sigmas") for e in errors)
+        assert any(fragment in e["message"] for e in errors), errors
+
+    def test_the_first_point_may_differ_within_the_tolerance(self):
+        sigmas = [RECIPE_STRENGTH + 5e-7, 0.857143, 0.666667, 0]
+        assert errors_for(step_with(**explicit(refine_sigmas=sigmas))) == []
+
+    def test_an_integer_zero_and_a_float_zero_both_end_it(self):
+        for zero in (0, 0.0):
+            sigmas = [0.909375, 0.5, zero]
+            assert (
+                errors_for(
+                    step_with(**explicit(refine_sigmas=sigmas, num_inference_steps=3))
+                )
+                == []
+            )
+
+    def test_sigmas_without_a_strength_are_refused(self):
+        errors = errors_for(step_with(**explicit(refine_strength=None)))
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("arguments.refine_sigmas")
+        assert errors[0]["message"].startswith(
+            "refine_sigmas schedules a refine_strength pass"
+        )
+
+    def test_a_deferred_list_is_not_checked(self):
+        step = step_with(**explicit(refine_sigmas="variable:sigmas"))
+        assert errors_for(step) == []
+
+    def test_sigmas_with_tiles_are_clean(self):
+        assert errors_for(tiled(**explicit())) == []
+
+    def test_sigmas_on_a_non_h3_step_are_refused(self):
+        step = step_with(**explicit())
+        step["pipeline"]["configuration"]["component_type"] = "StableDiffusionPipeline"
+        errors = errors_for(step)
+        assert any(e["path"].endswith("arguments.refine_sigmas") for e in errors)
+
+    def test_the_strength_rules_still_hold_beside_sigmas(self):
+        errors = errors_for(step_with(**explicit(hold_audio=None)))
+        assert any(
+            e["path"].endswith("refine_strength") and "hold_audio" in e["message"]
+            for e in errors
+        )
+
+    def test_no_sigmas_keeps_the_old_rules(self):
+        assert refine_problems(valid()) == []
+
+
+class TestSigmaListRuntime:
+    def test_the_regenerate_recipe_passes(self, refining):
+        assert Pipeline._check_refine(refining, runtime_arguments(**explicit())) is None
+
+    @pytest.mark.parametrize("overrides, fragment", BROKEN)
+    def test_a_broken_rule_raises(self, refining, overrides, fragment):
+        with pytest.raises(ValueError, match="refine_sigmas") as raised:
+            Pipeline._check_refine(refining, runtime_arguments(**explicit(**overrides)))
+        assert str(raised.value).startswith("Step 'video': ")
+
+    def test_sigmas_without_a_strength_raise(self, refining):
+        with pytest.raises(ValueError, match="refine_sigmas schedules"):
+            Pipeline._check_refine(
+                refining, runtime_arguments(**explicit(refine_strength=None))
+            )
+
+    def test_a_non_h3_pipeline_names_refine_sigmas(self):
+        with pytest.raises(ValueError, match="refine_sigmas is a MiniMax-H3"):
+            Pipeline._check_refine(
+                ns(object()), runtime_arguments(**explicit(refine_strength=None))
+            )
+
+
+class TestSigmaListOneOwner:
+    @pytest.mark.parametrize("overrides, fragment", BROKEN)
+    def test_the_runtime_message_is_the_owners(self, refining, overrides, fragment):
+        arguments = runtime_arguments(**explicit(**overrides))
+        problems = refine_problems(arguments)
+        assert any(fragment in problem for problem in problems)
+        with pytest.raises(ValueError) as raised:
+            Pipeline._check_refine(refining, arguments)
+        assert str(raised.value) == f"Step 'video': {problems[0]}"
+
+    @pytest.mark.parametrize("overrides, fragment", BROKEN)
+    def test_the_static_messages_are_the_owners(self, overrides, fragment):
+        arguments = valid(**explicit(**overrides))
+        statics = [e["message"] for e in errors_for(h3_step(**arguments))]
+        assert statics == refine_problems(arguments)
+
+
+def explicit_state(sigmas=RECIPE, strength=RECIPE_STRENGTH, seed=4, **kwargs):
+    state = make_state(steps=len(sigmas), strength=strength, seed=seed, **kwargs)
+    state.set(REFINE_SIGMAS_INPUT, list(sigmas))
+    return state
+
+
+class TestSigmaListSchedule:
+    def test_explicit_sigmas_are_the_list_verbatim(self):
+        assert explicit_sigmas(RECIPE, RECIPE_STRENGTH).tolist() == pytest.approx(
+            RECIPE
+        )
+
+    def test_the_ends_are_pinned_to_strength_and_zero(self):
+        sigmas = explicit_sigmas([0.9093755, 0.5, 0.0], 0.909375)
+        assert sigmas[0].item() == pytest.approx(0.909375, abs=1e-7)
+        assert sigmas[-1].item() == 0.0
+
+    def test_fewer_than_two_points_raise(self):
+        with pytest.raises(ValueError, match="at least 2 points"):
+            explicit_sigmas([0.9], 0.9)
+
+    @pytest.mark.parametrize("shift", [1.0, 6.0])
+    def test_the_block_runs_the_list_unshifted(self, shift):
+        comps = components(shift)
+        state = run(comps, explicit_state())
+        for scheduler in (comps.scheduler, comps.audio_scheduler):
+            assert scheduler.sigmas.tolist() == pytest.approx(RECIPE, abs=1e-6)
+        assert len(state.get("timesteps")) == len(RECIPE) - 1
+        assert torch.equal(state.get("timesteps"), state.get("audio_timesteps"))
+
+    def test_the_plan_is_rebuilt_one_entry_per_denoise_step(self):
+        state = run(components(), explicit_state())
+        assert len(state.get("row_timestep_plan")) == len(RECIPE) - 1
+
+    def test_the_renoise_is_at_the_strength(self):
+        comps = components()
+        state = make_state(steps=4, strength=RECIPE_STRENGTH, seed=4)
+        clean = state.get("latents").clone()
+        state.set(REFINE_SIGMAS_INPUT, list(RECIPE))
+        run(comps, state)
+        noise = randn_tensor(
+            clean.shape,
+            generator=torch.Generator().manual_seed(4),
+            device=torch.device("cpu"),
+            dtype=clean.dtype,
+        )
+        expected = (1 - RECIPE_STRENGTH) * clean + RECIPE_STRENGTH * noise
+        assert torch.allclose(state.get("latents"), expected, atol=1e-5)
+
+    def test_a_shorter_list_is_not_the_shift_grid(self):
+        comps = components()
+        sigmas = [0.5, 0.25, 0]
+        run(comps, explicit_state(sigmas=sigmas, strength=0.5))
+        assert comps.scheduler.sigmas.tolist() == pytest.approx(sigmas, abs=1e-6)
+        assert comps.scheduler.sigmas.tolist() != pytest.approx(
+            refine_sigmas(0.5, 3, 6.0).tolist(), abs=1e-6
+        )
+
+    def test_without_the_list_the_shift_grid_runs(self):
+        comps = components()
+        run(comps, make_state(steps=5, strength=0.2))
+        assert comps.scheduler.sigmas.tolist() == pytest.approx(
+            refine_sigmas(0.2, 5, 6.0).tolist(), abs=1e-6
+        )

From f47ff1617e53a3dfbab66dd7836ad93b6c044b3e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 09:20:56 -0500
Subject: [PATCH 033/125] docs(h3): #1077 - measured refine_strength bands for
 a regional edit

The regional-edit section of WORKFLOW_GUIDE.md carries plan v2's sweep
(seed 1062, 5 turbo steps, video_shift 6): <=0.85 a light rework, 0.9
replaces an object, 0.95 reworks clothing, 1.0 a fresh generation; a big
recolour needs 1.0. It explains refine_strength as sigma on the shifted
grid, u = s / (shift - (shift - 1) * s), and its example runs at 0.9.
The out-of-range refusal no longer suggests 0.4.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/WORKFLOW_GUIDE.md             | 37 ++++++++++++++++++++++++++----
 dw/pipeline_processors/h3_rules.py |  4 ++--
 2 files changed, 35 insertions(+), 6 deletions(-)

diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 0f8829d3..d6989684 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2535,8 +2535,9 @@ To change part of a take and keep the rest, pass a video as `source_video` on an
 `t2va`, `fl2va` or `ref2va` step. It is a path, `asset:`, `output:` or `previous_result:`
 reference to a video, and it stands in for the `latents` of a refine: the step VAE-encodes
 it over the generated rows and re-denoises from `refine_strength`, which is required and
-in (0, 1]: 1.0 regenerates the masked region from pure noise, about 0.4 reworks it lightly
-and keeps its layout. (Without a `source_video` the refine's range stays (0, 1).) With no
+in (0, 1]: 1.0 regenerates the masked region from pure noise, and about 0.9 replaces an
+object in it (see [Choosing refine_strength for a regional
+edit](#choosing-refine_strength-for-a-regional-edit)). (Without a `source_video` the refine's range stays (0, 1).) With no
 mask the whole source is refined.
 
 ```json
@@ -2544,9 +2545,9 @@ mask the whole source is refined.
     "source_video": "asset:fox_dawn.mp4",
     "mask_image": "asset:fox_mask.png",
     "mask_grow": 1,
-    "refine_strength": 0.6,
+    "refine_strength": 0.9,
     "hold_audio": "asset:fox_dawn.mp4",
-    "prompt": "the fox wears a red scarf, same light and motion"
+    "prompt": "the fox holds a pine cone in its mouth, same light and motion"
 }
 ```
 
@@ -2562,6 +2563,34 @@ noise, so at the end it is the source latent. The decode still round-trips it th
 VAE, so kept pixels are near-identical to the source, not bit-identical. A higher
 `refine_strength` replaces what the mask covers, a lower one keeps its layout.
 
+#### Choosing refine_strength for a regional edit
+
+The useful range sits high. Measured on one take (a 960x544, 124-frame H3 shot of a woman
+holding a cup, the mask over the middle of the frame around her and the cup, `mask_grow` 1), seed 1062, 5 turbo steps,
+`video_shift` 6, with a prompt asking for a bright red raincoat:
+
+| `refine_strength` | Inside the mask | Inside-mask SSIM vs the source |
+|---|---|---|
+| 0.85 or less | A light rework: re-detailed, the source's objects and colours stay | 0.86 at 0.8, 0.83 at 0.85 |
+| 0.9 | A held object is replaced (the cup became a domed sundae cup); the same person, pose and clothing | 0.78 |
+| 0.95 | Clothing is reworked too (a hooded navy jacket) and the object replaced; face, hair and pose mostly hold | 0.65 |
+| 1.0 | A fresh generation: the prompt lands in full, but a different person and composition | 0.44 |
+
+Outside the mask held at every strength (SSIM about 0.98 on a crop outside it). So:
+0.9 to replace an object, 0.95 to rework clothing, 0.85 or less for a light rework. A large
+recolour of a big region, such as a dark top to a bright red coat, did not land below 1.0,
+and 1.0 gives up the region's identity: that is a fresh generation, not a regional edit.
+
+Why the numbers sit high: `refine_strength` is the starting sigma σ₀ on the **shifted**
+grid, the same as for any refine (and `refine_tiles`). The scheduler's shift maps the
+unshifted position u to σ = shift·u / (1 + (shift − 1)·u), so the start point on the
+unshifted schedule is u = s / (shift − (shift − 1)·s). At `video_shift` 6 that is
+0.8 → 0.40, 0.85 → 0.49, 0.9 → 0.60 and 0.95 → 0.76: a strength of 0.8 re-noises less than
+its number suggests. The bands above hold for those conditions only. Another
+`video_shift` or step count moves them, the way the formula says: a lower shift brings u
+closer to s, so the same change comes at a lower strength. A [`refine_sigmas`](#explicit-refine-sigmas)
+list is run as given, with no shift, so its points are the schedule itself.
+
 The source and the mask must match the step's `width` x `height`, and a `source_video` or
 `mask_video` its `num_frames`. A step that leaves width, height or `num_frames` out renders
 the source's. An all-black mask is refused, as it would regenerate nothing. Validation reads
diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index 7d2a6908..0d054d67 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -76,8 +76,8 @@ def refine_problems(arguments, canvas=None):
         if not 0 < strength <= 1:
             problems.append(
                 f"refine_strength is a sigma in (0, 1] with a source_video - 1.0 "
-                f"regenerates the masked region from noise, about 0.4 reworks it "
-                f"lightly - and {strength} is outside it"
+                f"regenerates the masked region from noise, about 0.9 replaces an "
+                f"object in it - and {strength} is outside it"
             )
     elif not 0 < strength < 1:
         problems.append(

From a3672fd735b21488d6edfe8c4a3c83412b836920 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 09:48:36 -0500
Subject: [PATCH 034/125] test(h3): #1077 - a string refine_strength is refused
 where it reaches the rule

A caller's argument to a variable is converted to the type of the
variable's default before validation, so "0.8" to a variable declared
0.9 is the number 0.8. Pins that, and the refusal of a literal string
and of a string to a null-declared variable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_h3_mask.py | 50 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
index 7b9fb761..0a2320f8 100644
--- a/tests/test_h3_mask.py
+++ b/tests/test_h3_mask.py
@@ -991,6 +991,56 @@ def test_a_validated_step_at_one_is_clean(self):
         assert refine_strength_errors({"steps": [step]}) == []
 
 
+class TestStringStrength:
+    """#1077 bounce: a string `refine_strength` is refused where it reaches
+    the rule. A caller's argument to a variable is first converted to the
+    type of the variable's default (dw/variables.py `set_variables`), so
+    "0.8" to a variable declared 0.9 is the number 0.8, as a command-line
+    `refine_strength=0.8` must be. Only a variable declared null keeps it a
+    string."""
+
+    def realized(self, default, value):
+        from dw.variables import replace_variables, set_variables
+
+        variables = {"refine_strength": default}
+        set_variables({"refine_strength": value}, variables)
+        step = h3_step(
+            **args(refine_strength="variable:refine_strength"),
+            hold_audio="asset:clip.mp4",
+            num_inference_steps=5,
+        )
+        return replace_variables(step, variables)
+
+    def errors(self, step):
+        from dw.hold_audio import refine_strength_errors
+
+        return refine_strength_errors({"steps": [step]})
+
+    def test_a_literal_string_is_refused_at_its_path(self):
+        step = h3_step(
+            **args(refine_strength="0.8"),
+            hold_audio="asset:clip.mp4",
+            num_inference_steps=5,
+        )
+        errors = self.errors(step)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("refine_strength")
+        assert "'0.8' is not a number" in errors[0]["message"]
+
+    def test_a_string_to_a_number_variable_is_the_number(self):
+        step = self.realized(0.9, "0.8")
+        assert step["pipeline"]["arguments"]["refine_strength"] == 0.8
+        assert self.errors(step) == []
+
+    def test_a_string_to_a_null_variable_is_refused(self):
+        errors = self.errors(self.realized(None, "0.8"))
+        assert len(errors) == 1 and "'0.8' is not a number" in errors[0]["message"]
+
+    def test_a_non_numeric_string_to_a_number_variable_is_refused(self):
+        with pytest.raises(ValueError, match="refine_strength"):
+            self.realized(0.9, "high")
+
+
 # The call: Pipeline._with_mask
 
 

From 64722a0a61143f9c497fe852be5373ab41e622ff Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 10:18:46 -0500
Subject: [PATCH 035/125] fix(h3): #1077 - a latent refine keeps its verbatim
 range message

The no-source_video range refusal had gained 'and 1.0 is allowed only with
a source_video', breaking M-F115's verbatim contract (M-F217). The
regional-edit path keeps its own (0, 1] message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/h3_rules.py |  3 +--
 tests/test_h3_mask.py              | 21 +++++++++++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index 0d054d67..21e9b39f 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -82,8 +82,7 @@ def refine_problems(arguments, canvas=None):
     elif not 0 < strength < 1:
         problems.append(
             f"refine_strength is a sigma in (0, 1) - about 0.2 refines an "
-            f"upscaled take, and 1.0 is allowed only with a source_video - and "
-            f"{strength} is outside it"
+            f"upscaled take - and {strength} is outside it"
         )
     if arguments.get("latents") is None and arguments.get(SOURCE_VIDEO_INPUT) is None:
         problems.append(
diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
index 0a2320f8..a0d83741 100644
--- a/tests/test_h3_mask.py
+++ b/tests/test_h3_mask.py
@@ -957,8 +957,25 @@ def test_one_is_refused_without_a_source_video(self):
             "hold_audio": "previous_result:base.audio",
             "num_inference_steps": 5,
         }
-        problems = refine_problems(arguments)
-        assert len(problems) == 1 and "source_video" in problems[0]
+        assert refine_problems(arguments) == [
+            "refine_strength is a sigma in (0, 1) - about 0.2 refines an "
+            "upscaled take - and 1.0 is outside it"
+        ]
+
+    @pytest.mark.parametrize("strength", [0, 1.5])
+    def test_a_latent_refine_keeps_its_range_message(self, strength):
+        """A refine without a source_video says what it said before the
+        regional edit: its range sentence is a pinned contract."""
+        arguments = {
+            "refine_strength": strength,
+            "latents": "previous_result:up",
+            "hold_audio": "previous_result:base.audio",
+            "num_inference_steps": 5,
+        }
+        assert refine_problems(arguments) == [
+            f"refine_strength is a sigma in (0, 1) - about 0.2 refines an "
+            f"upscaled take - and {strength} is outside it"
+        ]
 
     def test_above_one_is_refused_with_a_source_video(self):
         arguments = {

From 0a962401a4656097ccf65d45179bd989a161d016 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 10:53:22 -0500
Subject: [PATCH 036/125] feat(h3): #1078 - regional-edit template and
 minimax-h3 skill branch

templates/minimax/regional-edit: one t2va edit step taking the take as
source_video, a mask_image, hold_audio on the take, refine_strength 0.9 at
the 4-step turbo file's 5 steps. The minimax-h3 skill gains "fix one region
of a good take" with references/regional-edit.md (mask by segment on a frame
or upload, the measured strength bands, the patch-cell grain), pinned by
test_plugin_skills against the guide and the engine's validators.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/README.md                          |   2 +-
 plugins/dw/skills/minimax-h3/SKILL.md         |  21 +-
 .../minimax-h3/references/regional-edit.md    |  62 +++++
 tests/test_catalog_structure.py               |  10 +-
 tests/test_h3_sparse_defaults.py              |   5 +-
 tests/test_plugin_skills.py                   |  67 ++++++
 tests/test_step_cache.py                      |   3 +
 workflows/templates/minimax/README.md         |   6 +
 .../templates/minimax/regional-edit.json      | 223 ++++++++++++++++++
 9 files changed, 385 insertions(+), 14 deletions(-)
 create mode 100644 plugins/dw/skills/minimax-h3/references/regional-edit.md
 create mode 100644 workflows/templates/minimax/regional-edit.json

diff --git a/plugins/dw/README.md b/plugins/dw/README.md
index b6a4bb24..98b3f853 100644
--- a/plugins/dw/README.md
+++ b/plugins/dw/README.md
@@ -15,7 +15,7 @@ Install once, from Claude Code:
 
 | Skill | Teaches |
 | ----- | ------- |
-| `minimax-h3` | MiniMax H3 video with audio: one take, a longer take by chain, a piece with cuts, identity and voice references, music; the frame and canvas rules; what a run costs. Prompts come from MiniMax's own `h3-prompt-writing` skill or the guides on the model card. |
+| `minimax-h3` | MiniMax H3 video with audio: one take, a fix to one region of a take, a longer take by chain, a piece with cuts, identity and voice references, music; the frame and canvas rules; what a run costs. Prompts come from MiniMax's own `h3-prompt-writing` skill or the guides on the model card. |
 | `minimax-music3` | MiniMax Music 3: a song, an instrumental, a score under a film, the soundtrack a music video is cut to; the ceiling semantics, the tag vocabulary, the caps and the 44.1 kHz output. Captions come from MiniMax's own `music-caption-rewriter` skill. |
 | `ltx-2.5` | LTX-2.5 video with a soundtrack: a single clip, first-frame and keyframe conditioning, the three-move two-stage flow, the IC-LoRA upscale, extend and chain; the distilled schedule and the frame and size rules. Prompts follow the trained-caption spec that ships inside diffusers. |
 | `kandinsky-6` | Kandinsky 6.0 video with a soundtrack: a five-second clip from text or from a picture on the 3B Lite-distill checkpoint; the distilled schedule, the size and frame rules the pipeline's own defaults get wrong, and why Apple Silicon is parked. Prompts follow Kandinsky Lab's own beautifier system prompts. |
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index 3e8826c6..e7b4bb1f 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -14,7 +14,7 @@ This skill picks the template and arguments; prompt format is MiniMax's.
    run on mps) and the session's workspace.
 2. `list_workflows(shape="shot")`, `list_workflows(shape="sequence")` and
    `list_workflows(shape="audio")`: the family's templates by name,
-   `summary`, `traits`, `cost`. Trust the listing over names below.
+   `summary`, `traits`, `cost`; it outranks names below.
 3. `get_workflow` on the one chosen: its variables and defaults.
 
 ## Which shape is the request
@@ -40,6 +40,8 @@ This skill picks the template and arguments; prompt format is MiniMax's.
   copies the take, and a style prompt does not restyle it. `"audio": true`
   on a guide holds its soundtrack too. Rules and example: `get_guide("workflows",
   section="H3: holding a clip with `guides`")`.
+- **Fix one region of a good take** (the rest and audio stay):
+  `templates/minimax/regional-edit`; first `references/regional-edit.md`.
 - **A consistent subject**: `templates/minimax/reference-to-video`
   (an image fixes appearance, an audio clip voice);
   `templates/minimax/composable-references` adds a video reference for
@@ -49,7 +51,7 @@ This skill picks the template and arguments; prompt format is MiniMax's.
   `templates/minimax/voice-timbre-reference` fixes a voice from a Bark line.
 - **Several boards, one generation, unbroken score**:
   `templates/minimax/storyboard`, cuts no concat matches. One beat only;
-  past that, the cuts pattern.
+  past that, cuts.
 - **Longer than 14.4 seconds**: chain when one action or line of speech
   crosses the seam, cut when the scene changes.
 - **As one take (a chain)**: `templates/minimax/chained-segments`
@@ -58,8 +60,7 @@ This skill picks the template and arguments; prompt format is MiniMax's.
   The guide prefix is trimmed off the deliverable (`trim_frames` and the
   crossfade do not apply). `carry_audio` (default true, a chain-block setting)
   holds the previous tail's audio. Guide only here: the reference chains
-  (`chain-video-continuity`, `chain-matched-and-aligned`, `music-video`) are
-  ref2va, and guides stay off ref2va),
+  are ref2va, and guides stay off ref2va),
   `templates/minimax/chain-video-continuity`
   (previous segment's tail rides as a video reference - motion, camera,
   voice carry the seam), `templates/minimax/chain-matched-to-audio` (a track
@@ -123,12 +124,12 @@ section).
   `match_audio` chains pass it, can sing shifted beats off the track; `music-video`
   holds each slice as well by default, and the chains' `hold_audio` variable adds a
   hold (`references/cuts.md`, #795, #808).
-- H3 is guidance-distilled: no `guidance_scale` or negative prompt.
+- Guidance-distilled: no `guidance_scale` or negative prompt.
 - Keep `release_pipeline` where the template puts it (frees Z-Image before
   H3 loads, H3 before a concat), or a warm worker may SIGKILL near the end.
 - Ref2VA limits: at most 9 images, 3 videos, 3 audio clips, 12 files; audio can
   never be the only reference. References are labelled in order.
-- Timestamps in the prompt span the generated length.
+- Prompt timestamps span the generated length.
 
 ## Prompts
 
@@ -154,7 +155,7 @@ A wanted look (clay, paper): `references/style.md`.
 
 ## Run and judge
 
-1. `validate_workflow` first - free, catches rejected arguments.
+1. `validate_workflow` first: free, catches rejected arguments.
 2. Quote `plan.estimate` from the validate answer (warm minutes; a first
    load or `downloads_required` is longer). When `basis` is `unknown`,
    say so and give the shape: a 124-frame turbo clip is a few minutes
@@ -166,7 +167,7 @@ A wanted look (clay, paper): `references/style.md`.
    (`timeout_capped` says the server's cap cut it; call again while
    `still_running`; on a client "timed out", retry at `timeout_seconds` 60), then `get_job`. A cancelled H3 job runs
    to its next step boundary. Silence is no hang: `denoise_step` is null
-   in the lead-in (encode ~6 s img, ~50 s video; 1st pass
+   at first (encode ~6 s img, ~50 s video; 1st pass
    dominates: 165-508 s) and the block cache makes later steps uneven -
    two-minute gaps are healthy; so is a slow first step at a new size (autotune, once a box). `phase_stall` in `get_job_events` narrates
    it, not a fault; judge by `denoise_step`. Each entry carries `subfolder`:
@@ -182,8 +183,8 @@ A wanted look (clay, paper): `references/style.md`.
    and all) and read its `findings` with `get_output_text`. Dialogue gaps (`shot_dead_air`) need room tone:
    `find_loop_bed` the `output:` cut, then `slice_audio`->`loop_audio`->`mix_audio`
    its pick at its `gain`.
-   Then `get_gallery_metadata` for duration/audio presence and hand the
-   user the gallery `url` (`list_gallery`). `get_output_image` is for image
+   Then `get_gallery_metadata` for duration/audio and hand the
+   user the gallery `url`. `get_output_image` is for image
    steps only.
 5. After a run worth keeping, `get_job_workflow` and `save_workflow` it;
    `export_job` bundles it on the server. `auth_required: false` - fetch
diff --git a/plugins/dw/skills/minimax-h3/references/regional-edit.md b/plugins/dw/skills/minimax-h3/references/regional-edit.md
new file mode 100644
index 00000000..7662cf5d
--- /dev/null
+++ b/plugins/dw/skills/minimax-h3/references/regional-edit.md
@@ -0,0 +1,62 @@
+# Fixing one region of a good take
+
+A take that is right except for one thing - the cup, the jacket, a sign - is fixed
+in place with `templates/minimax/regional-edit`: the mask's region is regenerated
+from the prompt, the rest of the picture is the take's, and the whole soundtrack
+is the take's (`hold_audio` is the `source_video`). Engine rules, refusals and the
+measurements behind the bands: `get_guide("workflows", section="H3: regional edit
+with source_video and a mask")`.
+
+## The take
+
+`source_video` is the take: an `output:` reference to the earlier run's file, or
+an `asset:` after `upload_asset`. The step renders at its `width`, `height` and
+`num_frames` (960x544, 124 frames by default), and the take and the mask must
+match them: read the take's with `get_gallery_metadata` and pass all three when
+it differs. Validation names both sizes on a mismatch. The take must carry audio.
+
+## The mask
+
+One `mask_image`, the take's size, used on every frame. White regenerates, black
+is kept, binarized at luma 128; an all-black mask is refused. Either:
+
+- the user's own mask, sent with `upload_asset`;
+- or `segment` with a text prompt ("the cup") on one frame of the take: a small
+  workflow of `get_frame` (`video` the take's `output:` or `asset:`,
+  `frame_index` where the object sits) then `segment` (`image` that frame), as
+  in `templates/segment`; `keep_output` the mask and pass it as `asset:`.
+  The object must stay inside the mask for the whole clip - a moving one needs a
+  mask covering everywhere it goes, or a `mask_video` (one mask per frame, see
+  the guide) on the step in place of `mask_image`.
+
+Grain: the mask is max-pooled to the patch grid, 16 px times the patch size per
+cell, so any white pixel marks its whole cell, and `mask_grow` (default 1) widens
+it by that many cells. In time a cell is a latent frame, about 3.4 pixel frames.
+Leave a margin; a tight mask shows its seam.
+
+## refine_strength
+
+The template defaults to 0.9, at its 5 steps. Measured on one 960x544 take at 5 turbo steps,
+`video_shift` 6, seed 1062:
+
+| `refine_strength` | Inside the mask |
+|---|---|
+| 0.85 or less | a light rework: re-detailed, objects and colours stay |
+| 0.9 | replaces an object; same person, pose, clothing |
+| 0.95 | reworks clothing too; face, hair, pose mostly hold |
+| 1.0 | a fresh generation: the prompt lands, identity is lost |
+
+Outside the mask held at every strength. A large recolour (a dark top to a
+bright red coat) did not land below 1.0, and 1.0 is a fresh generation: that is
+not a regional edit's job - regenerate the take instead. Another `video_shift`
+or step count moves the bands (lower shift, lower strength for the same change).
+
+Write the prompt for the whole shot as it should look after the edit, the same
+Context-IR as the take's with the changed thing described, not an instruction.
+
+## Judge
+
+`compare_outputs` the edit against the take (what changed, what held),
+`get_output_frames(count=12)` for the region across the clip, `get_output_audio`
+to confirm the soundtrack is the take's. Not with `refine_tiles` or on a chain
+step: validation refuses both.
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index cf4d113d..0972eb2c 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -71,6 +71,11 @@ def load(path):
         "shot",
         ["has-audio", "identity-referenced"],
     ),
+    # #1078: the take it edits is input media, and its soundtrack is held
+    "workflows/templates/minimax/regional-edit.json": (
+        "shot",
+        ["has-audio", "needs-input-media"],
+    ),
     "workflows/templates/minimax/dialogue-short.json": (
         "sequence",
         ["has-audio", "identity-referenced"],
@@ -500,7 +505,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Then to 11_850 for the `alpha-matte` template (#1064, stage #1079,
 # 2026-10-31), measured at 11_788: one new entry, the catalog's only matte
 # route, with its cost block.
-COMPACT_BUDGET = 11_850
+# Then to 12_050 for the `minimax/regional-edit` template (#1062, stage #1078,
+# 2026-10-31), measured at 11_983: one new entry, the catalog's only regional
+# edit of a take, with its cost block.
+COMPACT_BUDGET = 12_050
 FILTERED_BUDGET = 1_500
 
 
diff --git a/tests/test_h3_sparse_defaults.py b/tests/test_h3_sparse_defaults.py
index d646e483..8aa89ce1 100644
--- a/tests/test_h3_sparse_defaults.py
+++ b/tests/test_h3_sparse_defaults.py
@@ -27,8 +27,9 @@ def _read(path):
 )
 
 
-def test_nineteen_h3_templates():
-    assert len(H3) == 19
+def test_twenty_h3_templates():
+    # 20 since minimax/regional-edit (#1078)
+    assert len(H3) == 20
 
 
 @pytest.mark.parametrize("path", H3)
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index f649a1bd..f9d7a76e 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -7,6 +7,7 @@
 matched to the server it was written against by that number.
 """
 
+import copy
 import glob
 import inspect
 import json
@@ -547,6 +548,72 @@ def max_frames_for(references):
         for frames in ceilings.values():
             assert str(frames) in text
 
+    def test_the_regional_edit_branch_is_the_template_s_and_the_guide_s(self):
+        """#1078: "fix one region of a good take" sends an agent to a template
+        whose edit step the engine's own checks pass, at the strength and grain
+        the guide measured."""
+        from dw.hold_audio import (
+            hold_audio_errors,
+            mask_errors,
+            refine_strength_errors,
+        )
+        from dw.pipeline_processors import h3_mask
+
+        text = skill_text(H3_SKILL)
+        assert "`templates/minimax/regional-edit`" in text
+        assert "`references/regional-edit.md`" in text
+        with open(
+            os.path.join(os.path.dirname(H3_SKILL), "references", "regional-edit.md")
+        ) as f:
+            reference = f.read()
+
+        path = os.path.join(
+            REPO_ROOT, "workflows", "templates", "minimax", "regional-edit.json"
+        )
+        with open(path) as f:
+            template = json.load(f)
+        variables = template["variables"]
+        assert variables["refine_strength"] == 0.9
+        # 5: the 4-step turbo file plus the terminal zero, the bands' step count
+        assert variables["num_inference_steps"] == 5
+        (step,) = template["steps"]
+        pipeline = step["pipeline"]
+        assert pipeline["from_pretrained_arguments"]["workflow"] == "t2va"
+        arguments = pipeline["arguments"]
+        assert arguments["source_video"] == "variable:source_video"
+        assert arguments["mask_image"] == "variable:mask_image"
+        assert arguments["hold_audio"] == "variable:source_video"
+        assert arguments["refine_strength"] == "variable:refine_strength"
+
+        # The engine's static checks on the substituted step: the arguments
+        # rules pass (the placeholder assets are not on disk, so no probe)
+        substituted = copy.deepcopy(template)
+        for name, value in substituted["steps"][0]["pipeline"]["arguments"].items():
+            if isinstance(value, str) and value.startswith("variable:"):
+                substituted["steps"][0]["pipeline"]["arguments"][name] = variables[
+                    value.removeprefix("variable:")
+                ]
+        assert mask_errors(substituted) == []
+        assert refine_strength_errors(substituted) == []
+        assert hold_audio_errors(substituted) == []
+
+        # The bands and the grain are the guide's section, word for word
+        guide = open(os.path.join(REPO_ROOT, "docs", "WORKFLOW_GUIDE.md")).read()
+        section = guide.split("#### Choosing refine_strength for a regional edit")[1]
+        section = section.split("\n#")[0]
+        assert "seed 1062, 5 turbo steps" in section and "seed 1062" in reference
+        assert "`video_shift` 6" in section and "`video_shift` 6" in reference
+        for strength in ("0.85 or less", "| 0.9 |", "| 0.95 |", "| 1.0 |"):
+            assert strength in section and strength in reference
+        assert (
+            "did not land below 1.0" in section
+            and "did not land below 1.0" in reference
+        )
+        # Both wrap their prose, so the grain is matched with the lines joined
+        assert "16 px times the patch size" in " ".join(guide.split())
+        assert "16 px times the patch size" in " ".join(reference.split())
+        assert "`16 * patch`" in inspect.getsource(h3_mask)
+
 
 LTX_SKILL = os.path.join(PLUGIN_DIR, "skills", "ltx-2.5", "SKILL.md")
 
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 0c3d4f13..b896b788 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -847,6 +847,9 @@ def test_normalized_downstream_false_when_nothing_references_it():
     "minimax/reference-to-video.json": {
         "reference_to_video_audio": "ba9915580e6a8017d8c68efbddea776985d107222546f84cca18e319298243bf"
     },
+    "minimax/regional-edit.json": {
+        "edit": "2a7fdf989a40500620fb03212502bbda8f52827f5fcd872b8fda182fab2fac77"
+    },
     "minimax/shots-batch.json": {
         "shot@shot_1": "2a7fdf989a40500620fb03212502bbda8f52827f5fcd872b8fda182fab2fac77",
         "shot@shot_2": "2a7fdf989a40500620fb03212502bbda8f52827f5fcd872b8fda182fab2fac77",
diff --git a/workflows/templates/minimax/README.md b/workflows/templates/minimax/README.md
index dc492033..b9d2b19f 100644
--- a/workflows/templates/minimax/README.md
+++ b/workflows/templates/minimax/README.md
@@ -117,6 +117,12 @@ the hosted API accept 4. Output audio is 32 kHz stereo.
 | [first-and-last-frame.json](first-and-last-frame.json) | Pinning both ends - `image` and `last_image` - so the model interpolates between two fixed states |
 | [last-frame-only.json](last-frame-only.json) | Pinning the end alone - the model invents the approach to a picture you already have |
 
+## Editing a take
+
+| Example | What it introduces |
+| ------- | ------------------ |
+| [regional-edit.json](regional-edit.json) | Fixing one region of a good take: `source_video` is the take, a `mask_image` marks what to regenerate (white) and keep (black), `refine_strength` 0.9 replaces an object there, and `hold_audio` is the take itself, so the rest of the picture and the whole soundtrack stay the take's |
+
 ## Writing the prompt with a model
 
 | Example | What it introduces |
diff --git a/workflows/templates/minimax/regional-edit.json b/workflows/templates/minimax/regional-edit.json
new file mode 100644
index 00000000..283b30b1
--- /dev/null
+++ b/workflows/templates/minimax/regional-edit.json
@@ -0,0 +1,223 @@
+{
+    "id": "MiniMaxH3RegionalEdit",
+    "description": "Fixes one region of a good take and keeps the rest: the take's motion, timing and soundtrack stay, and only what the mask covers is regenerated. 'source_video' is the take (an 'asset:' or 'output:' video) and 'mask_image' a picture the take's size, white where to regenerate and black where to keep; one mask covers every frame. The one 'edit' step is the baseline t2va pipeline given the take as 'source_video': it VAE-encodes the take, re-noises the masked patch cells to 'refine_strength' and writes the kept cells back to the source after every step, while its hold_audio argument holds the take's own soundtrack. 'prompt' is the take's own prompt with the fix written in; the default is the baseline's fox prompt, so the default take is a run of video-with-audio. 'refine_strength' is measured high (one 960x544 take, 5 turbo steps, 'video_shift' 6): 0.85 or less re-details the region, 0.9 replaces an object in it while the person and pose hold, 0.95 reworks clothing too, and 1.0 is a fresh generation that loses the region's identity; a large recolour of a big region does not land below 1.0. The mask's grain is one patch cell, 16 px times the patch size, and the edit grows it by one cell so the boundary blends. 'width', 'height' and 'num_frames' must be the take's, and the mask the same size: validation refuses a mismatch and names both sizes. Kept pixels round-trip the VAE, so they are near-identical to the take, not bit-identical.",
+    "summary": "One masked region of an H3 take regenerated, the rest and its soundtrack kept.",
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 3.0
+        }
+    ],
+    "cost_drivers": [
+        "num_frames",
+        "num_inference_steps",
+        "width",
+        "height",
+        "weights_dtype",
+        "lora_model_name",
+        "attention_backend",
+        "cache"
+    ],
+    "vram_estimate": {
+        "base_gb": 16.3,
+        "bytes_per_voxel": 28.71,
+        "bytes_per_guide_voxel": 28.71,
+        "voxel_variables": [
+            "width",
+            "height",
+            "num_frames"
+        ],
+        "reason": "VAE decode's conv3d activation scales with the voxel count width * height * num_frames; base_gb and bytes_per_voxel are calibrated from two real runs: image-to-video's family baseline at 960x544x124 (on-demand VAE) succeeded at 18.03 GiB peak reserved (docs/WORKFLOW_GUIDE.md), and video-with-audio-768p at 1344x768x345 (the family's own num_frames ceiling) OOM'd mid-denoise needing >=25.82 GiB - 20.25 GiB already allocated plus a refused 5.57 GiB allocation, on a 23.56 GiB card (job 282172105da1, 2026-09-22) - closing the gap #265/#266 left the H3 family with nothing declared to check the engine's vram_estimate machinery against (#324)"
+    },
+    "variables": {
+        "source_video": "asset:take.mp4",
+        "mask_image": "asset:take_mask.png",
+        "prompt": "prompt:minimax/fox_dawn_context_ir",
+        "refine_strength": 0.9,
+        "num_inference_steps": 5,
+        "num_frames": 124,
+        "width": 960,
+        "height": 544,
+        "video_shift": 6.0,
+        "audio_shift": 3.0,
+        "weights_dtype": "{int4}",
+        "lora_scale": 1.0,
+        "lora_alpha": null,
+        "lora_model_name": "lightx2v/Minimax-h3-Turbo",
+        "lora_weight_name": "minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors",
+        "lora_adapter_name": "turbo",
+        "seed": 42,
+        "attention_backend": "sparse",
+        "sparse_tau": 0.5,
+        "sparse_topk": 0.15,
+        "cache": null
+    },
+    "variable_constraints": {
+        "num_frames": {
+            "modulus": 17,
+            "remainder": 5,
+            "min_frames": 124,
+            "max_frames": 345,
+            "snap": "up",
+            "reason": "the video VAE encodes 17 * n + 5 frames, and MiniMax-H3 generates between 5 and 15 seconds at 24 fps"
+        },
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "MiniMax-H3's pipeline refuses a `width` or `height` that is not a multiple of 32, and only after the weights have loaded; refused here instead, with no 'snap', since rounding would be a silent change to the size asked for"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "MiniMax-H3's pipeline refuses a `width` or `height` that is not a multiple of 32, and only after the weights have loaded; refused here instead, with no 'snap', since rounding would be a silent change to the size asked for"
+        }
+    },
+    "seed": "variable:seed",
+    "steps": [
+        {
+            "name": "edit",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "ModularPipeline",
+                    "pre_load_modules": [
+                        "sdnq"
+                    ],
+                    "load_components": {
+                        "dtype": "torch.bfloat16",
+                        "quantization_config": {
+                            "transformer": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "variable:weights_dtype",
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "use_quantized_matmul": true,
+                                    "dequantize_fp32": false,
+                                    "modules_to_not_convert": [
+                                        "proj_in",
+                                        "audio_proj_in",
+                                        "context_embedder",
+                                        "time_embedder",
+                                        "time_proj",
+                                        "token_refiner",
+                                        "norm_out",
+                                        "proj_out",
+                                        "audio_proj_out"
+                                    ]
+                                }
+                            },
+                            "text_encoder": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "variable:weights_dtype",
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "dequantize_fp32": false,
+                                    "modules_to_not_convert": [
+                                        ".model.visual",
+                                        "lm_head"
+                                    ]
+                                }
+                            },
+                            "vae": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "{int8}",
+                                    "quant_conv": true,
+                                    "use_quantized_matmul_conv": true,
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "dequantize_fp32": false
+                                }
+                            }
+                        }
+                    },
+                    "components": {
+                        "transformer": {
+                            "attention_backend": "variable:attention_backend",
+                            "sparse_tau": "variable:sparse_tau",
+                            "sparse_topk": "variable:sparse_topk",
+                            "group_offload": {
+                                "offload_type": "block_level",
+                                "num_blocks_per_group": 2,
+                                "use_stream": true,
+                                "record_stream": true,
+                                "low_cpu_mem_usage": true
+                            }
+                        },
+                        "text_encoder": {
+                            "remove_modules": [
+                                "lm_head"
+                            ]
+                        },
+                        "text_encoder.model": {
+                            "truncate_layers": {
+                                "language_model.layers": 51
+                            },
+                            "group_offload": {
+                                "offload_type": "leaf_level"
+                            }
+                        },
+                        "vae": {
+                            "device": "cuda",
+                            "residency": "on_demand"
+                        },
+                        "audio_vae": {
+                            "device": "cuda",
+                            "residency": "on_demand"
+                        }
+                    },
+                    "cache": "variable:cache"
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "MiniMaxAI/MiniMax-H3",
+                    "workflow": "t2va"
+                },
+                "loras": [
+                    {
+                        "model_name": "variable:lora_model_name",
+                        "weight_name": "variable:lora_weight_name",
+                        "adapter_name": "variable:lora_adapter_name",
+                        "scale": "variable:lora_scale",
+                        "alpha": "variable:lora_alpha"
+                    }
+                ],
+                "scheduler": {
+                    "shift": "variable:video_shift"
+                },
+                "audio_scheduler": {
+                    "shift": "variable:audio_shift"
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "source_video": "variable:source_video",
+                    "mask_image": "variable:mask_image",
+                    "hold_audio": "variable:source_video",
+                    "refine_strength": "variable:refine_strength",
+                    "num_frames": "variable:num_frames",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_inference_steps": "variable:num_inference_steps",
+                    "output": [
+                        "videos",
+                        "audio",
+                        "sampling_rate"
+                    ]
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24,
+                "subfolder": "final"
+            }
+        }
+    ]
+}

From 3b0707cf55ecf13e1135b28e6d207b53c38e1f71 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 11:06:52 -0500
Subject: [PATCH 037/125] feat(h3): #1078 - regional-edit cost recalibrated to
 the measured 2.1 min on a 3090

Job d1ad99c8b396 (cold load, 5 turbo steps, 960x544x124) took 122.7 s;
the listed 3.0 min was scaled from another run and sat 32% over.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 workflows/templates/minimax/regional-edit.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/workflows/templates/minimax/regional-edit.json b/workflows/templates/minimax/regional-edit.json
index 283b30b1..d712e041 100644
--- a/workflows/templates/minimax/regional-edit.json
+++ b/workflows/templates/minimax/regional-edit.json
@@ -7,7 +7,7 @@
             "device": "cuda",
             "name": "RTX 3090",
             "vram_gb": 24,
-            "minutes": 3.0
+            "minutes": 2.1
         }
     ],
     "cost_drivers": [

From 9ec2df8a9d5fd66ac1ed5e99c1f42cf70fa6aa15 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 11:19:47 -0500
Subject: [PATCH 038/125] feat(ltx2): #1079 - alpha-matte written at the
 source's frame rate

fit_to_model records source_fps (null when the source carries none);
restore_to_source takes an optional fps: omitted keeps the input's rate,
"source" the record's (falling back to the input's), a positive number
that rate. A bad literal fps is refused at validation. alpha-matte runs
the model at a fixed 24 fps and its final step restores at
variable:frame_rate, default "source". TASKS.md, the task's parameter
description and the ltx-2.5 skill row say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                             |  19 +++-
 dw/task_domains.py                        |  27 +++++
 dw/tasks/fit.py                           |  43 ++++++--
 dw/tasks/video_handlers.py                |  13 ++-
 plugins/dw/skills/ltx-2.5/SKILL.md        |   3 +-
 tests/test_fit_templates.py               |  70 +++++++++++++
 tests/test_fit_to_model.py                | 118 ++++++++++++++++++++++
 tests/test_ltx2_ic_loras.py               |   9 +-
 workflows/templates/ltx2/alpha-matte.json |  12 +--
 9 files changed, 296 insertions(+), 18 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 4c823416..b2d016ae 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -529,7 +529,7 @@ add grain last so it is not itself sharpened:
 | `window_video` | One overlapping, fixed-length window of a long video, with its audio | `index`, `num_frames`, `overlap`, `fps` - see [window_video](#window_video) |
 | `join_windows` | Blend processed windows back into one video the source's length, with the source's audio | `videos`, `source`, `num_frames`, `overlap`, `curve`, `fps` - see [join_windows](#join_windows) |
 | `fit_to_model` | Fit a video into a model's working size and exact frame count; returns `{video, fit}` | `width`, `height`, `num_frames`, `mode` (`letterbox`, `stretch`, `crop`), `downscale` - see [fit_to_model and restore_to_source](#fit_to_model-and-restore_to_source) |
-| `restore_to_source` | Put a model's output back at its source's size and length, from the `fit` record | `fit` - see [fit_to_model and restore_to_source](#fit_to_model-and-restore_to_source) |
+| `restore_to_source` | Put a model's output back at its source's size and length, from the `fit` record | `fit`, `fps` (omitted: the input's rate; `"source"`: the source's; or a number) - see [fit_to_model and restore_to_source](#fit_to_model-and-restore_to_source) |
 
 The frame commands accept videos in any shape a result carries them: PIL frame
 lists, numpy or torch frame arrays, and audio+video pairs (LTX-2, MiniMax H3).
@@ -1095,8 +1095,10 @@ it goes straight to a pipeline's `video` or a reference condition's `frames`;
 saved, it is written as an mp4 at that rate. The `fit`
 record holds `mode`, `source_width`, `source_height`, `source_frames`,
 `model_width`, `model_height`, `model_frames`, `content_box` (where the source
-sits in the model frame) and `source_box` (the part of the source kept - all
-of it unless `mode` is `crop`), each box `{x, y, w, h}`.
+sits in the model frame), `source_box` (the part of the source kept - all
+of it unless `mode` is `crop`), each box `{x, y, w, h}`, and `source_fps`
+(the source's frame rate, `null` when it carries none). A record written
+before `source_fps` existed still restores.
 
 `restore_to_source` takes the pipeline's output and that record; it has no
 `scale` argument. The scale is the output's size over the fitted size and must
@@ -1108,6 +1110,17 @@ the source's pixel density times the scale: 640x480 fitted into 512x288
 restores to 640x360. A saved video keeps its exact size; only an odd side
 grows by one pixel, since the encoder needs even sides.
 
+`fps` sets the restored clip's frame rate; it never adds or drops a frame.
+Omitted, the clip keeps the rate it came in at - the pipeline's, which for a
+model that runs at a fixed rate is not the source's. `"source"` takes the
+record's `source_fps`, falling back to the input's rate when the record has
+none. A positive number sets that rate. Anything else is refused, at
+validation for a literal. A model that runs at 24 fps on an 8 fps clip
+returns one frame per source frame, so `"fps": "source"` writes it back at 8
+and it stays frame-aligned with the source in time as well as in count
+(`templates/ltx2/alpha-matte`, whose `frame_rate` variable defaults to
+`"source"` and passes through to this argument).
+
 Neither task carries a soundtrack. Pair the source's with `pair_audio` after
 the restore.
 
diff --git a/dw/task_domains.py b/dw/task_domains.py
index d5af355d..bfa6833c 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -675,6 +675,33 @@ def fit_to_model_errors(arguments):
     return errors
 
 
+# restore_to_source's `fps` value for "the rate the source carried", read
+# from the fit record's `source_fps` (#1079)
+SOURCE_FPS = "source"
+
+
+def restore_fps_problem(fps):
+    """The refusal sentence for a restore_to_source `fps` that is neither
+    "source" nor a positive number, or None. Omitted (None) and a reference
+    still to resolve are not this check's to refuse."""
+    if fps is None or fps == SOURCE_FPS or is_ref(DEFERRED, fps):
+        return None
+    if _is_literal_text(fps) and not _is_non_finite_text(fps):
+        return (
+            f"restore_to_source needs 'fps' as {SOURCE_FPS!r} or a number "
+            f"({_DOMAIN_TEXT[POSITIVE]}), got {fps!r}"
+        )
+    return domain_error("restore_to_source", "fps", fps, POSITIVE)
+
+
+def restore_to_source_errors(arguments):
+    """[(argument, message)] for the restore_to_source rule a literal
+    workflow can break before it runs: an `fps` that is neither "source" nor
+    a positive number."""
+    problem = restore_fps_problem(arguments.get("fps"))
+    return [] if problem is None else [("fps", problem.rstrip("."))]
+
+
 def dissolve_shortfalls(frame_counts, dissolve_frames):
     """One sentence per video too short for its share of the overlaps.
 
diff --git a/dw/tasks/fit.py b/dw/tasks/fit.py
index 80cf6db4..d42563c1 100644
--- a/dw/tasks/fit.py
+++ b/dw/tasks/fit.py
@@ -34,9 +34,13 @@
 
 from ..media_types import AudioVideo, FittedVideo, JsonRecord
 from ..task_domains import (
+    SOURCE_FPS,
+    as_number,
     check_arguments,
     fit_downscale_problem,
     fit_mode_problem,
+    real_number,
+    restore_fps_problem,
     whole_number,
 )
 from .video_utils import frames_of, frames_as_array, load_audio_video
@@ -130,7 +134,8 @@ def fit_to_model(video, width, height, num_frames, mode="letterbox", downscale=1
         source_width/height/frames, model_width/height/frames, content_box
         (where the source sits in the model frame) and source_box (the part
         of the source kept; all of it unless mode is "crop"), each box
-        {x, y, w, h}}
+        {x, y, w, h}, and source_fps (the source's frame rate, null when it
+        carries none)}
     """
     command = "fit_to_model"
     width = whole_number(width, "width", command, required=True)
@@ -193,6 +198,8 @@ def fit_to_model(video, width, height, num_frames, mode="letterbox", downscale=1
             "model_frames": num_frames,
             "content_box": content_box,
             "source_box": source_box,
+            # restore_to_source's fps: "source" reads it back (#1079)
+            "source_fps": float(fps) if fps else None,
         }
     )
     logger.info(
@@ -244,10 +251,16 @@ def refuse(detail):
         raise refuse(
             f"its '{box_name}' {box} runs outside the {bound_w}x{bound_h} frame"
         )
+    # Absent from a record saved before #1079, which still restores
+    source_fps = fit.get("source_fps")
+    if source_fps is not None:
+        number = as_number(source_fps)
+        if isinstance(source_fps, str) or number is None or number <= 0:
+            raise refuse(f"its 'source_fps' is {source_fps!r}, not a rate above zero")
     return fit
 
 
-def restore_to_source(video, fit):
+def restore_to_source(video, fit, fps=None):
     """Task command: put a model's output back at its source's size and length.
 
     The scale is the model output's size over the fitted size, and must be
@@ -260,21 +273,39 @@ def restore_to_source(video, fit):
     are trimmed to the source's count, removing fit_to_model's held frames;
     an output shorter than that is returned as it is.
 
+    `fps` sets the rate the restored video carries. Omitted, it is the input
+    video's. "source" is the rate the fit record says the source carried
+    (`source_fps`), for a fixed-edit route whose output has to line up frame
+    for frame with its source (#1079); a source that carried none, or a
+    record saved without it, falls back to the input video's. A number is
+    that rate. No frames are added or dropped for it.
+
     Args:
         video: The model's output for the fitted video - an earlier step's
             video, or an `asset:`/`output:` reference
         fit: The record fit_to_model returned - previous_result:<step>.fit,
             or its saved .json
+        fps: The restored video's frame rate - omitted for the input video's,
+            "source" for the source's, or a number above zero
 
     Returns:
-        The restored video, float [0, 1], at the input video's fps and with
-        no soundtrack - pair the source's with pair_audio
+        The restored video, float [0, 1], at that fps and with no
+        soundtrack - pair the source's with pair_audio
     """
     command = "restore_to_source"
+    problem = restore_fps_problem(fps)
+    if problem is not None:
+        raise ValueError(problem)
     fit = _read_fit(fit)
     if isinstance(video, str):
         video = load_audio_video(video)
-    fps = getattr(video, "fps", None)
+    carried = getattr(video, "fps", None)
+    if fps is None:
+        fps = carried
+    elif fps == SOURCE_FPS:
+        fps = fit.get("source_fps") or carried
+    else:
+        fps = real_number(fps, "fps", command)
     frames = _float_frames(video, command)
     count, video_height, video_width = frames.shape[:3]
 
@@ -312,6 +343,6 @@ def scaled(value):
 
     logger.info(
         f"restore_to_source: {video_width}x{video_height}x{count} -> "
-        f"{out_w}x{out_h}x{len(restored)} ({mode}, {scale:g}x)"
+        f"{out_w}x{out_h}x{len(restored)} ({mode}, {scale:g}x, {fps} fps)"
     )
     return AudioVideo(restored.astype(numpy.float32), None, None, fps=fps)
diff --git a/dw/tasks/video_handlers.py b/dw/tasks/video_handlers.py
index f82ca06b..293ef86d 100644
--- a/dw/tasks/video_handlers.py
+++ b/dw/tasks/video_handlers.py
@@ -24,6 +24,7 @@
     POSITIVE,
     fit_to_model_errors,
     join_windows_errors,
+    restore_to_source_errors,
     window_video_errors,
 )
 from ..task_problems import (
@@ -194,7 +195,8 @@ def _handle_fit_to_model(task, arguments, previous_pipelines):
     implementation="dw.tasks.fit.restore_to_source",
     summary=(
         "Put a model's output for a fit_to_model video back at the source's "
-        "size (times the model's scale, inferred) and frame count."
+        "size (times the model's scale, inferred) and frame count, and with "
+        'fps: "source" at its frame rate.'
     ),
     parameter_descriptions={
         "video": (
@@ -206,8 +208,17 @@ def _handle_fit_to_model(task, arguments, previous_pipelines):
             "its saved .json. A crop fit restores only the part it kept, at "
             "the source's pixel density."
         ),
+        "fps": (
+            "The restored video's frame rate. Omitted, the input video's. "
+            '"source" is the rate the source had when it was fitted (the fit '
+            "record's source_fps), for a fixed edit whose output has to line "
+            "up frame for frame with its source; a source with no rate, or a "
+            "record saved without one, falls back to the input video's. A "
+            "number above zero is that rate. No frames are added or dropped."
+        ),
     },
     media_arguments=("fit",),
+    static_check=restore_to_source_errors,
 )
 def _handle_restore_to_source(task, arguments, previous_pipelines):
     """Put a fitted video back at its source's size and length"""
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 171d6c6b..2e6ac96d 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -47,7 +47,8 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   text, bigger panels for what matters. What isn't on the sheet won't
   appear. `reference_frames` must stay at or above 121.
 - **A matte of the user's clip**: `templates/ltx2/alpha-matte` - a soft
-  grey per-frame alpha, white = foreground, at the source's size, for the
+  grey per-frame alpha, white = foreground, at the source's size and frame
+  rate (`frame_rate` overrides the rate, never the frame count), for the
   user's editor to composite. No prompt: the model picks the foreground and
   a prompt doesn't steer it. `num_frames` caps at 145 (RGB leaks past it).
 - **Repairing the user's footage**: `templates/ltx2/restore-deblur` for
diff --git a/tests/test_fit_templates.py b/tests/test_fit_templates.py
index bbe62fa7..9a29ee0b 100644
--- a/tests/test_fit_templates.py
+++ b/tests/test_fit_templates.py
@@ -135,3 +135,73 @@ def test_restore_takes_the_pipeline_output_and_the_record(self, name, pipeline):
         assert steps["with_source_audio"]["task"]["arguments"]["video"] == (
             "previous_result:restore"
         )
+
+
+@pytest.fixture
+def eight_fps_clip(tmp_path, monkeypatch):
+    library = tmp_path / "assets"
+    library.mkdir()
+    ramp = numpy.linspace(0.1, 0.9, SRC_FRAMES, dtype=numpy.float32)
+    frames = [numpy.full((SRC_H, SRC_W, 3), value) for value in ramp]
+    export_to_video(frames, str(library / "clip.mp4"), fps=8)
+    monkeypatch.setenv(ASSET_DIR_ENV_VAR, str(library))
+    return library
+
+
+class TestTheAlphaMatteKeepsTheSourcesRate:
+    """#1079: the model runs at its 24 fps, but the matte is written at the
+    source's own rate unless 'frame_rate' says otherwise. The real path:
+    the template expanded against an 8 fps asset, `fit` through the task
+    dispatch, the matte step's 24 fps output standing in for the pipeline,
+    and `final` run and saved through its own result definition."""
+
+    # A small working size keeps the stand-in matte cheap
+    SMALL = {"width": 256, "height": 192, "num_frames": 25}
+
+    def written(self, tmp_path, **arguments):
+        from dw.media import video_shape
+        from dw.media_types import AudioVideo
+
+        workflow = workflow_from_file(
+            os.path.join(TEMPLATES, "alpha-matte.json"), str(tmp_path / "out")
+        )
+        steps = workflow.expanded_definition(arguments=dict(self.SMALL, **arguments))
+        steps = steps["steps"]
+        realize_args(steps, run_base_dir(workflow))
+        steps = {step["name"]: step for step in steps}
+        _, fit = run_fit(steps)
+
+        matte = Result(steps["matte"]["result"])
+        matte.add_result(
+            AudioVideo(numpy.zeros((25, 192, 256, 3), numpy.float32), None, None, 24)
+        )
+        final = steps["final"]
+        (task_arguments,) = get_iterations(
+            final["task"]["arguments"], {"fit": fit, "matte": matte}
+        )
+        output = Task(final["task"], "cpu").run(task_arguments)
+        result = Result(final["result"])
+        result.add_result(output)
+        saved = tmp_path / "saved"
+        saved.mkdir()
+        result.save(str(saved), "alpha-final.0")
+        (name,) = [n for n in os.listdir(saved) if n.endswith(".mp4")]
+        return video_shape(str(saved / name))
+
+    def test_the_default_writes_the_sources_rate(self, eight_fps_clip, tmp_path):
+        shape = self.written(tmp_path)
+
+        assert shape["fps"] == pytest.approx(8.0)
+        assert (shape["width"], shape["height"], shape["frame_count"]) == (
+            SRC_W,
+            SRC_H,
+            SRC_FRAMES,
+        )
+
+    def test_frame_rate_overrides_the_rate_not_the_frames(
+        self, eight_fps_clip, tmp_path
+    ):
+        shape = self.written(tmp_path, frame_rate=24)
+
+        assert shape["fps"] == pytest.approx(24.0)
+        assert shape["frame_count"] == SRC_FRAMES
diff --git a/tests/test_fit_to_model.py b/tests/test_fit_to_model.py
index ca4d50e5..17d4cd8e 100644
--- a/tests/test_fit_to_model.py
+++ b/tests/test_fit_to_model.py
@@ -483,3 +483,121 @@ def test_a_crop_restore_is_saved_at_its_own_size(self, tmp_path):
             360,
             12,
         )
+
+
+def _validate_restore(arguments):
+    workflow = {
+        "steps": [
+            {
+                "name": "r",
+                "task": {
+                    "command": "restore_to_source",
+                    "arguments": dict(
+                        {"video": "variable:v", "fit": "variable:f"}, **arguments
+                    ),
+                },
+            }
+        ]
+    }
+    errors = task_argument_errors(workflow)
+    return [(error["path"].rsplit(".", 1)[-1], error["message"]) for error in errors]
+
+
+def model_output(fps=24, count=57):
+    """What a model hands back: the fitted size, at the model's own rate."""
+    return AudioVideo(
+        numpy.zeros((count, 288, 512, 3), numpy.float32), None, None, fps=fps
+    )
+
+
+class TestRestoreFrameRate:
+    """#1079: the record carries the source's rate, and `fps` chooses the
+    restored clip's rate - omitted, the input's; "source", the record's; a
+    number, that one. Frames are never added or dropped."""
+
+    def test_the_record_carries_the_source_rate(self):
+        assert fit(clip(fps=8))["fit"]["source_fps"] == 8.0
+
+    def test_a_source_without_a_rate_records_none(self):
+        images = [Image.new("RGB", (SRC_W, SRC_H)) for _ in range(5)]
+        record = fit(images, num_frames=9)["fit"]
+        assert "source_fps" in record and record["source_fps"] is None
+        json.dumps(record)
+
+    def test_source_carries_the_recorded_rate(self):
+        record = fit(clip(fps=8))["fit"]
+        restored = restore_to_source(model_output(24), record, fps="source")
+        assert restored.fps == 8.0
+        assert frames_of(restored).shape == (50, 480, 640, 3)
+
+    def test_omitted_carries_the_inputs_rate(self):
+        record = fit(clip(fps=8))["fit"]
+        assert restore_to_source(model_output(24), record).fps == 24
+
+    @pytest.mark.parametrize("fps", [12, 12.0, "12"])
+    def test_a_number_carries_that_rate(self, fps):
+        record = fit(clip(fps=8))["fit"]
+        restored = restore_to_source(model_output(24), record, fps=fps)
+        assert restored.fps == 12.0
+        assert frames_of(restored).shape[0] == 50
+
+    def test_an_old_record_without_the_field_restores(self):
+        record = dict(fit(clip(fps=8))["fit"])
+        del record["source_fps"]
+        assert restore_to_source(model_output(24), record).fps == 24
+        # "source" with nothing recorded falls back to the input's rate
+        assert restore_to_source(model_output(24), record, fps="source").fps == 24
+
+    def test_a_record_with_no_rate_falls_back_to_the_input(self):
+        record = dict(fit(clip(fps=8))["fit"], source_fps=None)
+        assert restore_to_source(model_output(24), record, fps="source").fps == 24
+
+    @pytest.mark.parametrize("bad", [0, -1, "sorce", "inf", "nan", True])
+    def test_a_bad_fps_is_refused_at_run_time(self, bad):
+        record = fit(clip(fps=8))["fit"]
+        with pytest.raises(ValueError, match="fps"):
+            restore_to_source(model_output(24), record, fps=bad)
+
+    @pytest.mark.parametrize("bad", ["8", 0, -8, True])
+    def test_a_bad_recorded_rate_is_refused(self, bad):
+        record = dict(fit(clip(fps=8))["fit"], source_fps=bad)
+        with pytest.raises(ValueError, match="source_fps"):
+            restore_to_source(model_output(24), record, fps="source")
+
+    @pytest.mark.parametrize("bad", [0, -1, "sorce", "inf"])
+    def test_a_bad_fps_is_refused_statically(self, bad):
+        errors = _validate_restore({"fps": bad})
+        assert [name for name, _ in errors] == ["fps"], errors
+
+    @pytest.mark.parametrize(
+        "fps", ["source", 12, 23.976, "variable:frame_rate", "previous_result:s.fps"]
+    )
+    def test_a_good_or_deferred_fps_is_silent(self, fps):
+        assert not _validate_restore({"fps": fps})
+
+    def test_no_fps_is_silent(self):
+        assert not _validate_restore({})
+
+    def test_an_eight_fps_source_is_saved_at_eight(self, tmp_path):
+        """The real path: both commands through the task dispatch, the
+        model's 24 fps output restored under "source", written and probed."""
+        from dw.media import video_shape
+        from dw.tasks.task import Task
+
+        fitted = Task({"command": "fit_to_model", "arguments": {}}, "cpu").run(
+            dict(video=clip(12, fps=8), width=512, height=288, num_frames=17)
+        )
+        restored = Task({"command": "restore_to_source", "arguments": {}}, "cpu").run(
+            dict(video=model_output(24, 17), fit=fitted["fit"], fps="source")
+        )
+        result = Result({"content_type": "video/mp4", "save": True})
+        result.add_result(restored)
+        result.save(str(tmp_path), "wf-restore.0")
+        (name,) = os.listdir(tmp_path)
+        shape = video_shape(str(tmp_path / name))
+        assert shape["fps"] == pytest.approx(8.0)
+        assert (shape["width"], shape["height"], shape["frame_count"]) == (
+            640,
+            480,
+            12,
+        )
diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index 3f051e31..09c10773 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -121,7 +121,14 @@ def test_the_defaults_are_the_trained_bucket(self, name):
 
         assert (variables["width"], variables["height"]) == (width, height)
         assert variables["num_frames"] == frames
-        assert variables["frame_rate"] == 24.0
+        if name == "alpha-matte":
+            # #1079: the matte is written at the source's rate; the model
+            # itself still runs at its trained 24 fps
+            pipeline = conditioned_step(name)["pipeline"]
+            assert variables["frame_rate"] == "source"
+            assert pipeline["arguments"]["frame_rate"] == 24.0
+        else:
+            assert variables["frame_rate"] == 24.0
 
     def test_it_conditions_through_the_in_context_pipeline(self, name):
         pipeline = conditioned_step(name)["pipeline"]
diff --git a/workflows/templates/ltx2/alpha-matte.json b/workflows/templates/ltx2/alpha-matte.json
index fd7e0524..931360ec 100644
--- a/workflows/templates/ltx2/alpha-matte.json
+++ b/workflows/templates/ltx2/alpha-matte.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2AlphaMatte",
-    "description": "Pulls a soft per-frame alpha matte from the user's clip with the Alpha-Gen in-context LoRA - no green screen, mask or prompt; hair, smoke, motion blur and glass come back as partial values, not a hard cutout. The output is a grey-scale h264 MP4 at the source's own size and frame-aligned with it: white is foreground, black background. dw does not composite it: use it as the source's alpha (a luma matte) in an editor. The model picks the foreground itself and the prompt does not steer it, so the prompt is fixed empty and there is no prompt variable. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing (the black padding reads as background) and a last step crops the padding back off, so any aspect ratio comes back at its own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. 'num_frames' is 8n+1 from 9 to 145 and refused above: past 145 the card says RGB content leaks into the matte. Defaults 960x544 at 121 frames, 24 fps - set 'frame_rate' to the source's. The card's ceiling is 1920x1088, which is not a 24 GB size. The LoRA strength is the card's fixed 1.0. A 0.9 preview weight, run here under uint4 SDNQ.",
+    "description": "Pulls a soft per-frame alpha matte from the user's clip with the Alpha-Gen in-context LoRA - no green screen, mask or prompt; hair, smoke, motion blur and glass come back as partial values, not a hard cutout. The output is a grey-scale h264 MP4 at the source's own size and frame-aligned with it: white is foreground, black background. dw does not composite it: use it as the source's alpha (a luma matte) in an editor. The model picks the foreground itself and the prompt does not steer it, so the prompt is fixed empty and there is no prompt variable. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing (the black padding reads as background) and a last step crops the padding back off, so any aspect ratio comes back at its own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. 'num_frames' is 8n+1 from 9 to 145 and refused above: past 145 the card says RGB content leaks into the matte. The matte has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Defaults 960x544 at 121 frames. The card's ceiling is 1920x1088, which is not a 24 GB size. The LoRA strength is the card's fixed 1.0. A 0.9 preview weight, run here under uint4 SDNQ.",
     "summary": "Soft per-frame alpha matte of your clip: grey MP4, white = foreground, at the source's size. No prompt.",
     "traits": [
         "needs-input-media"
@@ -25,7 +25,7 @@
         "width": 960,
         "height": 544,
         "num_frames": 121,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "seed": 42
     },
     "variable_constraints": {
@@ -164,7 +164,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
@@ -199,7 +199,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
                 "save": false
             }
         },
@@ -209,12 +209,12 @@
                 "command": "restore_to_source",
                 "arguments": {
                     "video": "previous_result:matte",
-                    "fit": "previous_result:fit.fit"
+                    "fit": "previous_result:fit.fit",
+                    "fps": "variable:frame_rate"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "final"
             }
         }

From 56d1819a0b3d09c1a7692dd8ee3bdd0b58107d34 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 11:24:03 -0500
Subject: [PATCH 039/125] docs: #1062 close-out - H3 regional edit design
 record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/h3-regional-edit-complete.md     | 187 ++++++++++++++++++
 docs/proposals/todo.md                        |  10 +
 2 files changed, 197 insertions(+)
 create mode 100644 docs/proposals/complete/h3-regional-edit-complete.md

diff --git a/docs/proposals/complete/h3-regional-edit-complete.md b/docs/proposals/complete/h3-regional-edit-complete.md
new file mode 100644
index 00000000..afe40d88
--- /dev/null
+++ b/docs/proposals/complete/h3-regional-edit-complete.md
@@ -0,0 +1,187 @@
+# H3 regional edit: source_video and a mask (#1062)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 approved by Don with its defaults (Q1 per-step blend,
+Q2 build smaller, Q3 no paste-back, Q4 names as proposed). Plan v2, written
+after Don's ruling on #1077's M-F218 bounce, approved 2026-10-31 with its
+defaults (Q5 keep the feature, Q6 document the shifted-σ meaning rather
+than re-scale). Two stages, #1077 and #1078, both verified 2026-10-31.
+
+Prior art: einhorn13/mmh3_media (MIT, ComfyUI): `av_edit.py`'s per-stream
+masks, `inpaint_prepare.py`, and `h3_tile_refine.py`. The concept was
+re-implemented on the diffusers modular pipeline. No code was taken.
+
+## The question
+
+Does the diffusers MiniMax-H3 modular pipeline let the noise or latents be
+masked, per stream, during the denoise? The audio half existed already
+(`hold_audio`); the video half was the unknown.
+
+## The answer: feasible as dw blocks, no upstream needed
+
+The modular pipeline has no mask input, but it has what a mask needs:
+- **per-row noise levels are native** (`row_timestep_plan`): conditioning
+  and held audio rows already ride clean beside noisy rows;
+- **one block writes rows** (`MiniMaxH3LoopSchedulerStep`), so a dw loop
+  sub-block after `update` can put the kept rows back after every step,
+  which is ComfyUI's per-stream `noise_mask`;
+- **the audio-locked tile refine had already shipped** (#1043 / #1048,
+  `refine_tiles`).
+
+A `denoise_mask` input on `MiniMaxH3LoopSchedulerStep` would be a clean
+upstream PR later, and the dw block would shrink to a pass-through. Not
+pursued here.
+
+## Verdict
+
+**Build smaller.** A (engine) and B (template and skill). Audio intervals,
+masked tiled refine and masked chained steps were cut, each with a
+trigger (below).
+
+## What was built
+
+### Stage A, #1077: engine regional edit
+
+Arguments on an H3 `t2va`, `fl2va` or `ref2va` step:
+- `source_video`: the take to edit. It must match the step's `width`,
+  `height` and `num_frames`. It stands in for a refine's `latents`.
+- `mask_video` **or** `mask_image`: white regenerates, binarized at luma
+  128 through Pillow's `L` conversion (the same rule as
+  `remove_object.binarize_mask`), max-pooled onto the patch grid (16 px ×
+  patch size; one latent frame, about 3.4 pixel frames, × patch time
+  size), then dilated by `mask_grow` cells (a whole number, 0 or more,
+  default 1). With no mask the whole source is re-denoised.
+- `refine_strength`: required, in (0, 1] with a `source_video` (1.0
+  regenerates the region from noise). Without a source the refine's range
+  stays (0, 1), with its message unchanged.
+- `hold_audio`: normally `source_video` itself; the source mp4's own track
+  is held.
+
+Code:
+- `dw/pipeline_processors/h3_mask.py`: `insert_mask_blocks`, and the
+  mask-to-rows arithmetic (`binarized`, `regenerate_cells`, `keep_rows`).
+- `dw/pipeline_processors/h3_mask_steps.py`:
+  - the source-latents block before `set_timesteps`, which VAE-encodes the
+    source on the canvas;
+  - the mask-blend block in the `denoise` loop after `update`. It writes
+    each kept row back as the source noised to the next sigma, with the
+    refine's own noise, so the kept rows end as the source latent;
+  - `edit_summary`, the regional-edit `log` job event (regenerated/kept
+    cells, `mask_grow`, `refine_strength`), added after Don's ruling.
+- `dw/pipeline_processors/h3_rules.py`: `mask_problems`, `media_problems`
+  and `edits_region`, shared by validate and `_with_mask` in
+  `pipeline.py`.
+- `dw/hold_audio.py`: `mask_errors`, Check `regional_edit`. It probes the
+  source and mask through `ValidationContext.probe`, so every refusal
+  fires at `validate_workflow` and nothing is queued.
+- Docs: `WORKFLOW_GUIDE.md` › *H3: regional edit with source_video and a
+  mask* and *Choosing refine_strength for a regional edit* (the measured
+  bands and the shifted-σ note). Also the `ARCHITECTURE.md` H3 row.
+- Tests: `tests/test_h3_mask.py` (arithmetic, insertion, the blend ending
+  at the source, rules, static media, strength 1.0, the job event) and
+  additions to `tests/test_h3_hold_audio.py`.
+
+The output is the decode as-is (Q3: no pixel paste-back), so kept pixels
+are near-identical to the source, not bit-identical. Outside-mask SSIM
+measured about 0.98 at every strength.
+
+### Plan v2: the measured strength bands
+
+v1 promised that `refine_strength: 0.8` changes the masked region "per the
+prompt". On the M-F218 take (`ep6-cold-open.mp4` + `h3-mask/region.png`,
+`mask_grow` 1, 5 turbo steps, `video_shift` 6, seed 1062; prompt asking for
+a bright red raincoat) it didn't. Don ruled for a sweep:
+
+| strength | inside SSIM | outside SSIM | inside the mask |
+|---|---|---|---|
+| 0.80 / 0.85 | 0.86 / 0.83 | 0.978 | re-detail only: the source wins |
+| 0.90 | 0.78 | 0.977 | a held object is replaced; same person, pose, clothing |
+| 0.95 | 0.65 | 0.978 | garments reworked too; face, hair and pose mostly hold |
+| 1.00 | 0.44 | 0.975 | the prompt lands, but a fresh generation (identity lost) |
+
+The numbers sit high because `refine_strength` is σ₀ on the shifted grid.
+At shift 6 the unshifted start is u = s / (6 − 5s): 0.8 → 0.40,
+0.9 → 0.60, 0.95 → 0.76. Q6 kept the semantics (re-scaling would move
+`refine_tiles` too). A big recolour of a large region needs 1.0, which is
+a documented limit, not a promise.
+
+### Stage B, #1078: template and skill branch
+
+- `workflows/templates/minimax/regional-edit.json`: shape `shot`, traits
+  `needs-input-media` and `has-audio`. Defaults are 960×544×124,
+  `refine_strength` 0.9, 5 turbo steps, shift 6, and
+  `hold_audio: variable:source_video`. Cost **2.1 min on an RTX 3090**,
+  measured: a cold run took 120-123 s (encode 45 s, denoise 45-47 s,
+  decode 19 s).
+- `minimax-h3` skill: the "fix one region of a good take" branch in
+  `SKILL.md`, with `references/regional-edit.md`. It covers making the
+  mask (segment on a frame, or upload), choosing the strength from the
+  bands, the recolour limit, and the patch-cell grain.
+
+## Deviations from the plan
+
+- **Every refusal is at validate.** The first build checked media only at
+  the call, so an all-black mask queued a job (the first tester bounce).
+  `media_problems` now runs at validate on the files that resolve.
+- **Strength 1.0 is accepted with a `source_video`**, following "1.0
+  regenerates from noise". It stays refused without one.
+- **The template runs 5 steps, not the sketch's 8**, matching the turbo
+  LoRA and the measured bands.
+- **The acceptance strength moved from 0.8 to 0.9** (plan v2). The red
+  raincoat is no longer required inside the mask.
+
+## Bounces per stage
+
+- **#1077: one architecture bounce, four tester bounces, then a park.**
+  - architecture: the mask arithmetic was hand-written instead of on
+    Pillow, torch and scipy, and `mask_image` took an RGB round trip that
+    could binarize differently from `mask_video`;
+  - tester: refusals fired at the run rather than at validate (M-F216), and
+    M-F214/M-F215 (a)(d) were short. Fixed by validate-time media checks,
+    holding the source mp4's own track, and strength 1.0 with a source;
+  - tester: M-F218, the region changed but not per the prompt at 0.8, and
+    no job event named the edit. The driver parked the stage after four
+    hand-offs. Don ruled: add the event, and re-plan (v2) on a measured
+    sweep;
+  - tester: M-F216 (k), a string `"0.8"` validated clean. Not a code
+    defect: the carrier's variable default was a number, so the argument
+    was converted before the rule saw it. Tests were added that pin where
+    a string reaches the rule;
+  - tester: M-F217, the latent-refine range message had changed wording
+    for the no-source case. Restored verbatim, and the exact sentence is
+    pinned.
+
+  Twice an architecture review sent the stage back with no findings and no
+  record, which looked like a failed reviewer session. Nothing was changed
+  for either. It verified at `a34b4d15`.
+- **#1078: one.** M-F249: the listed cost of 3.0 min was 32% over the
+  measured 2.05 min. It was recalibrated to 2.1, and the stage verified at
+  `5e04cab0`.
+
+No `usage:` figures were recorded on the stages, so cost is left out. The
+plan's estimate was $6-9.
+
+## Deferred and left open
+
+- **Audio intervals and "audio follows video mask".** Cut until a field
+  report wants a line re-sung or re-spoken inside a kept take. The
+  mechanism is the same blend on audio rows, with `refine_problems`'
+  "every audio row held" rule relaxed.
+- **Mask + `refine_tiles`.** Refused (`TILE_CONFLICTS`). It comes back when
+  a 1080p regional fix is asked for, by cropping the mask per tile the way
+  `latents` already is.
+- **Mask on a chained step.** Refused, until a chained regional-edit
+  request comes in.
+- **The big-recolour case**, where identity holds at strength 1.0. Revisit
+  with an H3 refiner LoRA (#1065) or an upstream mask input.
+- **Strength generality.** The bands come from one take, one seed and 5
+  turbo steps at shift 6. The guide states those conditions, and the u
+  formula says which way another shift moves them.
+- **Upstream `denoise_mask`** on `MiniMaxH3LoopSchedulerStep`: an
+  optional diffusers PR. It would reduce the blend block to a
+  pass-through.
+- **Q1's alternative** (pin kept rows clean at t = 1.0) was not tried.
+- **Stale v1 cases.** M-F218, M-F222 and the v1 lines of M-F220/M-F221
+  expect v1's 0.8 / 0.7 / "0.5 / 1.0". The tester asked the curator to
+  retire or amend them in dkackman/harnest#158. M-F244 to M-F249 are
+  authoritative.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 9c41d527..12d35ac1 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -383,6 +383,16 @@ remaining deferred fix is recorded in
   template were not built. Record, with the design and what would reopen it
   (a lighter H3 build, or #1045's guide path):
   `complete/chain-follow-video-complete.md`.
+- **H3 regional edit** (#1062, stages #1077-#1078), shipped 2026-10-31. An
+  H3 step takes a `source_video` and a `mask_image` or `mask_video`, with
+  `mask_grow`. Two dw blocks (a source encode, and a mask blend inside the
+  denoise loop) regenerate the masked patch cells and keep the rest of the
+  take and its soundtrack. Strength bands are measured: 0.9 replaces an
+  object, 0.95 reworks clothing, and 1.0 is a fresh generation. Ships the
+  `templates/minimax/regional-edit` template and a `minimax-h3` skill
+  branch. Record, including what was deferred (audio intervals, masked
+  tiles, chains, upstream `denoise_mask`):
+  `complete/h3-regional-edit-complete.md`.
 
 ## Declined
 

From 02ebe65de905b96a9dfceff31eac082d3dca04da Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 12:09:08 -0500
Subject: [PATCH 040/125] docs(h3): #1082 - Explicit refine sigmas reachable
 through get_guide

The subsection was a #### heading, which get_guide's section lookup
doesn't resolve. It is now a ### subsection, with a pointer from the
refine_strength subsection it used to sit in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/WORKFLOW_GUIDE.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index d6989684..6176e00c 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2494,9 +2494,10 @@ refine with no `latents` or no `hold_audio`, a step that is not H3, and a
 `num_inference_steps` below 2.
 
 To refine a canvas above 1344x768, such as a 1920x1088 plate, see [Refining above 768p in
-tiles](#refining-above-768p-in-tiles).
+tiles](#refining-above-768p-in-tiles). To give the schedule's sigma points yourself rather
+than spacing them by `shift`, see [Explicit refine sigmas](#explicit-refine-sigmas).
 
-#### Explicit refine sigmas
+### Explicit refine sigmas
 
 A recipe published with its own schedule cannot be reached by spacing points with
 `shift`. `refine_sigmas` gives the schedule itself: the sigma points, from

From 92d09b51ac7f74b6c4d9234f8574e5cd0d9f6f23 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 12:31:31 -0500
Subject: [PATCH 041/125] docs(stems): #1096 - htdemucs as a dialogue/rest
 splitter, A/B record

Three H3 dialogue shots mixed under a Music 3 score and split with
separate_stems: vocals matches the dry shot within 0.1 dB rms, score
leak into vocals sits ~30 dB under the bed, and the rest carries the
shot's own SFX. TASKS.md names the dialogue/rest use and corrects
where htdemucs weights come from (demucs' downloader, not Hugging Face).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                                 |  20 +-
 .../audits/2026-11-dialogue-stems.md          | 256 ++++++++++++++++++
 2 files changed, 273 insertions(+), 3 deletions(-)
 create mode 100644 docs/proposals/audits/2026-11-dialogue-stems.md

diff --git a/docs/TASKS.md b/docs/TASKS.md
index b2d016ae..b4036017 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -2329,6 +2329,19 @@ The model is fixed (`htdemucs`, run in fp32), its weights download on first
 use, and it needs the `demucs` package. On MPS a failed separation falls back
 to the CPU and warns (`separation_cpu_fallback`).
 
+**Dialogue and the rest.** The same split takes a dialogue shot apart from a
+score mixed under it: `vocals` is the dialogue and `drums` + `bass` + `other`,
+summed with `mix_audio`, is the rest. Measured on H3 shots under a Music 3
+score, the `vocals` stem matched the dry shot within 0.1 dB rms, and the
+score's leak into it sat about 30 dB under the bed
+([record](proposals/audits/2026-11-dialogue-stems.md)). The rest is not a
+clean score, though: htdemucs puts a shot's own SFX and foley in `drums` and
+`other`, so they come out with the music. Keep the score file when the goal is
+to replace the music. Transcribing the `vocals` stem also gives the line where
+transcribing the dry shot can loop on a hallucination; a speechless shot gives
+a near-silent `vocals` stem and an invented transcript, so judge "no dialogue"
+by the stem's level. Single-speaker dialogue doesn't raise `stacked_vocals`.
+
 **Stacked vocals.** A chorus is often recorded as layered stereo doubles - every
 Music 3 chorus is - and htdemucs returns all of them in the one `vocals` stem.
 When the stem's left and right channels sing different lines over a sung span,
@@ -2441,9 +2454,10 @@ picking better-separated reference spans is the fix, not reading past it.
 
 Both models are fixed - there is no model-name argument - and both run in
 fp32 (their STFT front ends are fp32-only in practice, and both are small
-enough that it costs nothing). Weights download on first use - htdemucs from
-Hugging Face (`adefossez/HTDemucs` via demucs 4.1), ECAPA from speechbrain -
-and are cached between calls like any other model. On MPS a `separate: true`
+enough that it costs nothing). Weights download on first use - htdemucs
+through demucs' own downloader (from `dl.fbaipublicfiles.com` into the torch
+hub cache, outside the Hugging Face cache), ECAPA from speechbrain - and are
+cached between calls like any other model. On MPS a `separate: true`
 run that fails in htdemucs falls back to the CPU and warns
 (`separation_cpu_fallback`) rather than failing the step.
 
diff --git a/docs/proposals/audits/2026-11-dialogue-stems.md b/docs/proposals/audits/2026-11-dialogue-stems.md
new file mode 100644
index 00000000..ac4b2cf7
--- /dev/null
+++ b/docs/proposals/audits/2026-11-dialogue-stems.md
@@ -0,0 +1,256 @@
+# htdemucs as a dialogue/rest splitter: A/B record (#1091 stage A, #1096)
+
+Probe date: 2026-10-31 (server clock). Server `lem`, develop @ 1cc889fa.
+Agent: claude-opus-5-5 (anthropic). Workspace `dialogue-stems-1096`.
+No engine or skill file was changed. This document only records results.
+The listening verdict ("good enough" or not) is Don's: the agent could not
+listen to the stems. The leak notes below are read from level measurements
+and control separations, and each one says so.
+
+## The question
+
+An H3 shot comes with its dialogue, room tone and foley baked into one track.
+Once a score goes under it, there is no clean dialogue left to retime, duck or
+re-mix. Can `separate_stems` (htdemucs) take a shot + score mix apart again,
+into dialogue (`vocals`) and everything else (`drums` + `bass` + `other`, the
+"rest")? The bar is that the `vocals` stem matches the dry shot and that
+transcribing it gives the shot's line.
+
+## The recipe
+
+This is a mix, then `separate_stems`, then `mix_audio` over the three non-vocal
+stems to make the rest. Only these four steps are the recipe. The measurement
+workflow that ran it (below) adds levels, transcripts and controls around them.
+
+```json
+{
+    "id": "DialogueStems",
+    "variables": {
+        "shot": "output:KnownIssuesRestorePointA/20261013-013302-bdc190ac/intermediate/KnownIssuesRestorePointA-shot@deflect.1-0.0.mp4",
+        "score": "output:templates/minimax/music/20260922-134436-b40b67b6/final/MiniMaxMusic-balanced.1-0.0.mp3",
+        "score_start": 8,
+        "shot_seconds": 5.17,
+        "score_gain": 0.5
+    },
+    "steps": [
+        {
+            "name": "bed",
+            "task": {
+                "command": "slice_audio",
+                "arguments": {
+                    "audio": "variable:score",
+                    "start_seconds": "variable:score_start",
+                    "duration_seconds": "variable:shot_seconds"
+                }
+            }
+        },
+        {
+            "name": "mix",
+            "task": {
+                "command": "mix_audio",
+                "arguments": {
+                    "audios": ["variable:shot", "previous_result:bed"],
+                    "gains": [1, "variable:score_gain"]
+                }
+            },
+            "result": { "content_type": "audio/wav", "subfolder": "intermediate", "file_base_name": "mix" }
+        },
+        {
+            "name": "stems",
+            "task": {
+                "command": "separate_stems",
+                "arguments": { "audio": "previous_result:mix" }
+            },
+            "result": { "content_type": "audio/wav", "subfolder": "final", "file_base_name": "stems" }
+        },
+        {
+            "name": "rest",
+            "task": {
+                "command": "mix_audio",
+                "arguments": {
+                    "audios": ["previous_result:stems.drums", "previous_result:stems.bass", "previous_result:stems.other"]
+                }
+            },
+            "result": { "content_type": "audio/wav", "subfolder": "final", "file_base_name": "rest" }
+        }
+    ]
+}
+```
+
+Each run returned `stems-0.0-{vocals,drums,bass,other}.wav` (44.1 kHz stereo)
+and `rest-0.0.wav`. `mix_audio` warns that it resampled, because the H3 shots
+are 32 kHz and the score is 44.1 kHz. That warning is expected. **No run raised
+`stacked_vocals`**: these are single-speaker dialogue shots.
+
+The measurement runs added the following steps:
+- `analyze_audio` on the dry shot, the `vocals` stem, the rest, the bed, and
+  the bed at its mix gain (`bed_scaled`);
+- `transcribe_audio` (whisper-base) on the dry shot, the `vocals` stem and
+  the bed;
+- two controls, each separating one input on its own:
+  - `ctl_bed` separates the gain-scaled bed alone, and its `vocals` stem is
+    the score's leak into dialogue;
+  - `ctl_dry` separates the dry shot alone, and its drums + bass + other is
+    the shot's own non-speech content, which lands in the rest.
+
+The controls stand in for a subtraction: `mix_audio` refuses negative gains, so
+"vocals − dry" can't be rendered directly.
+
+Score: Music 3 `MiniMaxMusic-balanced.1` (42.25 s), from `acorn-wars`. Score
+gain was 0.5 in every mix. Levels are dBFS (`analyze_audio`, mean over channels
+where it reports per channel).
+
+## Mix 1: deflect
+
+The shot is `KnownIssuesRestorePointA-shot@deflect.1` (5.17 s), with the score
+from 8 s. Job `98c9dea3612f`, run `DialogueStems/20261031-172140-2a115543`.
+
+| Signal | peak | rms | low | mid | high |
+| --- | --- | --- | --- | --- | --- |
+| dry shot | -1.29 | -21.72 | -31.40 | -22.67 | -43.03 |
+| `vocals` stem | -1.24 | -21.71 | -31.19 | -22.67 | -43.01 |
+| rest | -20.10 | -34.20 | | | |
+| bed at mix gain | -18.68 | -32.81 | | | |
+| control: bed-alone `vocals` | -60.77 | -62.79 | | | |
+| control: dry-alone rest | -22.40 | -60.43 | | | |
+
+The vocals are within 0.05 dB of the dry shot in peak, 0.01 dB in rms, and 0.2
+dB in every band.
+
+| Transcript of | Text |
+| --- | --- |
+| dry shot | "Of course, we have backups every night since 1994." then an "AHHHH…" loop (1824 chars) |
+| `vocals` stem | "Of course, we have backups every night since 1994. Yeah!" |
+| bed alone | "Thank you very much for watching." (Whisper's hallucination on music) |
+
+The `drums` and `bass` stems are near-silent and warn so: this section of the
+score has no drums or bass.
+
+## Mix 2: button
+
+The shot is `KnownIssuesRestorePointB-shot@button.0` (5.17 s), with the score
+from 20 s. Job `af3f52108e3b`, run `DialogueStems/20261031-172221-2a0e0902`.
+
+| Signal | peak | rms | low | mid | high |
+| --- | --- | --- | --- | --- | --- |
+| dry shot | -0.80 | -23.01 | -31.44 | -24.56 | -40.52 |
+| `vocals` stem | -0.94 | -23.06 | -31.41 | -24.61 | -40.70 |
+| rest | -12.55 | -28.05 | | | |
+| bed at mix gain | -12.60 | -27.52 | | | |
+| control: bed-alone `vocals` | -58.91 | -63.69 | | | |
+| control: dry-alone rest | -12.95 | -46.49 | | | |
+
+In the dry-alone control, the shot's own non-speech audio lands in `drums`
+(mean -46.75, peak -12.85). It is transient SFX or foley, not speech.
+
+| Transcript of | Text |
+| --- | --- |
+| dry shot | "We don't test them. That's how you lose them." |
+| `vocals` stem | "We don't test them. That's how you lose them." |
+| bed alone | "Thank you very much." (hallucination) |
+
+## Mix 3: tag
+
+The shot is `KnownIssuesRestorePointB-shot@tag.1` (5.875 s), with the score
+from 30 s. Job `0e7e6bb039ef`, run `DialogueStems/20261031-172507-2722c9f3`.
+
+| Signal | peak | rms | low | mid | high |
+| --- | --- | --- | --- | --- | --- |
+| dry shot | -1.38 | -23.26 | -33.63 | -23.93 | -47.44 |
+| `vocals` stem | -1.21 | -23.35 | -33.56 | -24.01 | -48.25 |
+| rest | -11.05 | -31.28 | | | |
+| bed at mix gain | -10.93 | -31.48 | | | |
+| control: bed-alone `vocals` | -55.42 | -62.34 | | | |
+| control: dry-alone rest | -12.43 | -42.06 | | | |
+
+In the dry-alone control, the shot's non-speech audio again goes to the rest:
+`drums` has mean -47.16 and peak -12.68, and `other` has mean -44.22. The `bass`
+stem of the mix is near-silent and warns.
+
+| Transcript of | Text |
+| --- | --- |
+| dry shot | "So we have no idea if they work. We have hope." then a "Thank you very much." loop (2728 chars) |
+| `vocals` stem | "So we have no idea if they work. We have hope." |
+| bed alone | "Thank you so much for watching!" (hallucination) |
+
+## A non-dialogue negative: s04
+
+`acorn-wars` `H3ShotsBatch-shot@s04-the-call-r4.3` was the first pick. It turned
+out to hold no speech (run `DialogueStems/20261031-172300-7bc2933b`):
+- the dry-shot transcript was "Thank you very much for watching.", which is
+  Whisper's hallucination;
+- the `vocals` stem averaged -53.65 dBFS, and its transcript was a string of
+  garbage glyphs.
+
+It was replaced by `tag`. It is recorded here because it shows what the recipe
+does on a speechless shot. The `vocals` stem comes back near-silent, and Whisper
+then invents a line, so an empty transcript can't be relied on to say "no
+dialogue". Check the stem's level instead.
+
+## Leak notes (from measurements; listening is Don's)
+
+| Mix | `vocals` stem: score leak | rest: dialogue leak | rest: what else is in it |
+| --- | --- | --- | --- |
+| deflect | Bed-alone `vocals` is about 30 dB under the bed (rms -62.8 vs. -32.8). Expect it to be inaudible under speech. | Dry-alone rest is at rms -60.4. Expect no audible speech in the rest. | Score only. Rest ≈ bed (-34.2 vs. -32.8 rms). |
+| button | About 36 dB under the bed (-63.7 vs. -27.5). | Dry-alone rest is at rms -46.5, peak -13. That is the shot's SFX/foley, routed to `drums`, not speech. | Score plus the shot's own SFX. |
+| tag | About 31 dB under the bed (-62.3 vs. -31.5). | Dry-alone rest is at rms -42.1, peak -12.4, the shot's SFX in `drums`/`other`. | Score plus the shot's own SFX. |
+
+What to listen for in the kept stems:
+- whether music bleeds into `vocals` between words (the controls put it at
+  -55 to -61 dBFS peak);
+- whether consonants (s, t) bleed into the rest;
+- whether the SFX that went to the rest belongs with the dialogue for the
+  scene's purpose.
+
+## Findings
+
+1. **The `vocals` stem is the dry dialogue.** On all three shots it matches
+   the dry shot within 0.1 dB rms and 0.2 dB peak, and within 0.8 dB in every
+   band (the largest gap is tag's high band).
+2. **The score barely reaches `vocals`.** Separating the bed alone puts
+   -62 to -64 dBFS rms into `vocals`, about 30–36 dB under the bed's level in
+   the mix.
+3. **The rest is the score plus the shot's own non-speech audio.** The rest's
+   rms tracks the bed's within 1.4 dB. htdemucs sends an H3 shot's SFX and
+   foley to `drums`/`other`, not `vocals`, so the rest isn't a clean score: it
+   carries the shot's room and foley too. When the goal is to re-mix or replace
+   the score, keep the original score file. The rest is for when the score file
+   is lost or the score is to be ducked as a unit with the effects.
+4. **Transcribing `vocals` beats transcribing the dry shot.** All three
+   `vocals` transcripts gave the shot's line. On two of three shots the dry
+   audio sent whisper-base into a hallucination loop that the stem didn't. The
+   one extra word ("Yeah!" on deflect) is a vocalization in the shot.
+5. **No `stacked_vocals` on single-speaker dialogue.** The check didn't fire
+   on any shot.
+6. **A speechless shot gives a near-silent `vocals` stem and an invented
+   transcript** (s04). Check the stem's level, not the transcript.
+
+## Kept stems
+
+Each stem is kept in workspace `dialogue-stems-1096` as an `asset:` and is still
+readable as an `output:`.
+
+| Mix | `output:` | `asset:` |
+| --- | --- | --- |
+| deflect | `DialogueStems/20261031-172140-2a115543/final/stems-0.0-vocals.wav` | `dialogue-stems-deflect-vocals.wav` |
+| deflect | `DialogueStems/20261031-172140-2a115543/final/stems-0.0-drums.wav` | `dialogue-stems-deflect-drums.wav` |
+| deflect | `DialogueStems/20261031-172140-2a115543/final/stems-0.0-bass.wav` | `dialogue-stems-deflect-bass.wav` |
+| deflect | `DialogueStems/20261031-172140-2a115543/final/stems-0.0-other.wav` | `dialogue-stems-deflect-other.wav` |
+| deflect | `DialogueStems/20261031-172140-2a115543/final/rest-0.0.wav` | `dialogue-stems-deflect-rest.wav` |
+| button | `DialogueStems/20261031-172221-2a0e0902/final/stems-0.0-vocals.wav` | `dialogue-stems-button-vocals.wav` |
+| button | `DialogueStems/20261031-172221-2a0e0902/final/stems-0.0-drums.wav` | `dialogue-stems-button-drums.wav` |
+| button | `DialogueStems/20261031-172221-2a0e0902/final/stems-0.0-bass.wav` | `dialogue-stems-button-bass.wav` |
+| button | `DialogueStems/20261031-172221-2a0e0902/final/stems-0.0-other.wav` | `dialogue-stems-button-other.wav` |
+| button | `DialogueStems/20261031-172221-2a0e0902/final/rest-0.0.wav` | `dialogue-stems-button-rest.wav` |
+| tag | `DialogueStems/20261031-172507-2722c9f3/final/stems-0.0-vocals.wav` | `dialogue-stems-tag-vocals.wav` |
+| tag | `DialogueStems/20261031-172507-2722c9f3/final/stems-0.0-drums.wav` | `dialogue-stems-tag-drums.wav` |
+| tag | `DialogueStems/20261031-172507-2722c9f3/final/stems-0.0-bass.wav` | `dialogue-stems-tag-bass.wav` |
+| tag | `DialogueStems/20261031-172507-2722c9f3/final/stems-0.0-other.wav` | `dialogue-stems-tag-other.wav` |
+| tag | `DialogueStems/20261031-172507-2722c9f3/final/rest-0.0.wav` | `dialogue-stems-tag-rest.wav` |
+
+The mixes the stems came from are each run's `intermediate/mix-0.0.wav`.
+
+## Verdict
+
+Pending Don's listening. A `series-episodes` paragraph is written only if the
+verdict is "good enough" (plan v2, stage A).

From 5080a5d7a4f593ec16b14b884e02405ffacd52f6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 12:33:29 -0500
Subject: [PATCH 042/125] docs(proposals): #1065 - Open-Regenerate-2K refiner
 design record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../h3-open-regenerate-2k-complete.md         | 164 ++++++++++++++++++
 docs/proposals/todo.md                        |   8 +
 2 files changed, 172 insertions(+)
 create mode 100644 docs/proposals/complete/h3-open-regenerate-2k-complete.md

diff --git a/docs/proposals/complete/h3-open-regenerate-2k-complete.md b/docs/proposals/complete/h3-open-regenerate-2k-complete.md
new file mode 100644
index 00000000..7a530ea5
--- /dev/null
+++ b/docs/proposals/complete/h3-open-regenerate-2k-complete.md
@@ -0,0 +1,164 @@
+# H3 Open-Regenerate-2K refiner LoRA and `refine_sigmas` (#1065)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 approved by Don with "approve defaults" (Q1 Kijai's
+refiner-only rank-384 extraction stacked with `turbo-4step-keyframe`, Q2
+Don's read of the crop as the pass line with PSNR/SSIM as a drift guard,
+Q3 `refine_sigmas` and `num_inference_steps` both required and agreeing).
+Two stages, #1081 and #1082, both verified 2026-10-31.
+
+Prior art: HomoLapis/justae-flow (GPL-3.0, ideas only): its "Open-H3 2K"
+preset pairs the regenerate LoRA with the H3 latent upscaler and runs 3
+steps on a 768p draft. No code was taken.
+
+## The question
+
+Does a LoRA trained for the regenerate step beat dw's low-sigma refine
+(#471 latent upscaler, #1043/#1048 `refine_tiles`) on the #1049 arms, and
+does it load and fit on lem's 24 GB cards?
+
+## What the design sweep found
+
+- **Source and licence.** NVlabs, `Efficient-Large-Model/Open-H3-Regenerate-2K`
+  (code in `NVlabs/Sana`, branch `sol-engine`), under the MiniMax H3
+  Community License. The issue's `..._r128_comfyui_bf16` file is a
+  community re-extraction with no stated provenance or licence: not used.
+  `Kijai/MiniMax-H3-experimental` holds refiner-only extractions at rank 16
+  and 384.
+- **NVlabs ships a merge plus a non-LoRA part.** One FP32 adapter (~12.45
+  GB, rank 576 on 312 linears) merging the refiner (r384), LightX2V FL2VA
+  Turbo and LMS Sharp r64, plus `sharp_curve_branches.safetensors`: 50
+  AdaLN branches on an 8-D timestep curve, which `load_lora_weights` can't
+  carry (the same wall that made `loras/minimax-h3/lms.json` `rejected`).
+- **The recipe.** 768p draft → 3D-conv latent upscaler → start at
+  `(1-0.909375)·up + 0.909375·noise` → 3 Euler steps on
+  `[0.909375, 0.857143, 0.666667, 0]` at CFG 1 → 2560x1440.
+- **Corrections to the proposal.** Tiled refine at σ 0.91 keeps only 9% of
+  the plate, so tiles would each re-render the whole prompt: full-frame
+  1920x1088 was tried first. #1049's crop PSNR/SSIM measures drift, which a
+  regenerate causes by design, so it could not be the pass line. The
+  recipe's sigma points could not be written in dw (the refine schedule
+  was always shift-spaced), hence stage B.
+
+## Verdict
+
+**Build smaller**, as a probe with a gate: A (catalog, docs, probe jobs),
+then Don's gate, then B (`refine_sigmas` and the faithful arm).
+
+## What was built
+
+### Stage A, #1081: catalog entry, doc corrections, probes
+
+- `loras/minimax-h3/open-h3-regenerate-2k.json`, `status: trial`: Kijai's
+  `loras/minimax_h3_open_regenerate_2k_refiner_rank_384_bf16.safetensors`
+  (5.9 GB) at revision `f5c3b1d5…`, `workflow: [t2va, fl2va]`,
+  `stacks_with: [minimax-h3/turbo-4step-keyframe]`, no `lora_alpha`, the
+  sharp-branch note, licence `minimax-h3-community`.
+- The "API-only and not open-sourced" lines in
+  `audits/2026-09-07-minimax-h3-audit.md` and
+  `docs/superpowers/plans/2026-09-07-ltx-h3-catalog-repair.md` now point at
+  Open-H3-Regenerate-2K. `WORKFLOW_GUIDE.md`'s "25-30 min, not measured"
+  tiled-refine figure is now the measured ~12 min (RTX 3090, 124 frames).
+- Probes on lem, workspace `qa-h3-regen-2k`, on #1049 arm (d)'s realized
+  workflow (#500 crowd-gate draft, seed 42, 124 frames):
+  - **P1, load:** clean on the default unpruned `transformer`; no
+    unmatched-key or skipped-module warning. The only warning was the
+    `adapter_unrecognized` filename heuristic, which the catalog entry
+    clears.
+  - **P2, fit:** full-frame 1920x1088 refine, strength 0.909375, 4 steps,
+    shift 2: succeeded (`33feb79dab33`), **21.5 GB** reserved, 13.4 min
+    (refine only; base/up cached).
+  - **P3, tiles:** not run, since P2 fit.
+
+### Stage B, #1082: `refine_sigmas`
+
+- An optional `refine_sigmas` list on an H3 refine step.
+  `DwH3RefineScheduleStep` runs it as given through `explicit_sigmas()` in
+  `dw/pipeline_processors/h3_hold_steps.py`, unshifted, for both the video
+  and audio schedulers, and rebuilds `row_timestep_plan` from it. Without
+  it the shift grid is unchanged.
+- Rules in one owner, `h3_rules.refine_problems`, called by the static
+  check (`hold_audio.refine_strength_errors`) and the run-time check
+  (`Pipeline._check_refine`): at least 2 points, strictly decreasing,
+  first point equal to `refine_strength` within 1e-6, last point 0, length
+  equal to `num_inference_steps`. Refused without `refine_strength`;
+  allowed with `refine_tiles`.
+- Tests: `TestSigmaListStatic`, `TestSigmaListRuntime`,
+  `TestSigmaListOneOwner`, `TestSigmaListSchedule` in
+  `tests/test_h3_refine.py`.
+- Docs: `WORKFLOW_GUIDE.md` › *Pipeline Configuration* › *Explicit refine
+  sigmas*, with the recipe as its example; the `ARCHITECTURE.md` H3 row.
+
+## The measurements
+
+Crop `[1200,700,600,388]` at 2.0 s and 4.5 s, against #1049 arm (a)
+(`PreGateFitF-a_1080.2-0.0-video.mp4`):
+
+| arm | job | peak reserved | wall | PSNR / SSIM vs (a) |
+|---|---|---|---|---|
+| #1049 (d) tiled refine, no LoRA | `0be863816672` | - | 14.8 min | 26.40 dB / 0.773 |
+| #1049 (e) spandrel 2x | - | - | 7.05 min | 34.4 / 0.94 |
+| #1049 (f) LTX upscale | - | - | ≈9.3 min | 18.7 / 0.50 |
+| P2, regen LoRA, shift-2 grid | `33feb79dab33` | 21.5 GB | 13.4 min | 18.58 / 0.458 |
+| faithful, regen LoRA, recipe sigmas | `51e1c17b4022` | 23.5 GB | 10.2 min | 18.63 / 0.451 |
+
+The regenerate is far sharper (pores, stubble, coat weave, crisp flames
+and cobbles; no seams or duplicated subjects), but at strength 0.909 it
+redraws identity: it scores at (f)'s level, not (d)'s. The recipe's exact
+sigma points are visually near-identical to the shift-2 grid and agree
+within noise (+0.05 dB, -0.007 SSIM): at this strength they buy nothing
+measurable.
+
+## Deviations from the plan
+
+1. **The gate added a step that was not recorded.** Don's ruling on the
+   stage A record (2026-10-31) was "proceed, with a cheap lower-strength
+   arm before stage B": run one or two arms at `refine_strength` about 0.6
+   and 0.7, and plan stage B only if one kept (d)'s fidelity (about 26 dB /
+   0.77) with visibly sharper detail; otherwise close the idea. **No
+   lower-strength arm appears on #1065, #1081 or #1082.** Stage B was built
+   and the faithful arm run without that record. The question Don asked,
+   whether the detail survives once identity drift is gone, is still open
+   (see Deferred).
+2. **The refine step needs explicit `width`/`height` at 1920x1088.**
+   Without them the layout defaults to 1344x768 and the transformer fails
+   (`fc673788417c`, `index_copy_` size mismatch). Validate didn't catch it.
+   Filed with the other side finding as #1087 and #1088.
+3. **The guide subsection moved.** It was written as a `####` under the
+   *refine_strength* subsection, which `get_guide` can't resolve; it is now
+   a `###` under *Pipeline Configuration* (the stage B bounce).
+
+## Bounces per stage
+
+- **#1081 (A):** none. The tester counted one clause of M-F231 (d)
+  (warnings beside a refusal) as the case's own error and filed a suite
+  amendment on dkackman/harnest; validate drops warnings on any invalid
+  result, for every model.
+- **#1082 (B):** one. M-F233 step 1, `get_guide("workflows",
+  section="Explicit refine sigmas")`, didn't resolve because of the
+  heading level. Fixed docs-only (`02ebe65d`, merged as `1cc889fa`) and
+  verified.
+
+Cost: the stage comments name no `usage:` figures, so none is recorded.
+The plan's estimates were $2-3 plus ~45 min GPU for A and $3-5 for B.
+
+## Deferred and left open
+
+- **The lower-strength arms (0.6, 0.7).** Don's gate question. They need
+  no new code: the P2 workflow with a lower `refine_strength`, reusing the
+  cached base/up, scored on the same crop. Their result decides whether
+  the entry goes toward `proven` (and a template) or `rejected`.
+- **The catalog entry stays `trial`.** Its `use_when` still says the exact
+  sigmas "need refine_sigmas, #1065 stage B"; that input now exists, so
+  the line should name it as available (a catalog change, left to the
+  next build that touches the entry).
+- **Sharp curve branches.** Need a new AdaLN module fed by the step
+  timestep. Reopen if a lower-strength arm is close but soft and NVlabs'
+  ablation shows the branches carry the sharpness.
+- **2560x1440 output.** Needs the upscaler and tile caps raised and new
+  VRAM pricing; the faithful arm already reserved 23.5 GB at 1920x1088, so
+  it won't fit full-frame on 24 GB.
+- **A template and a `minimax-h3` skill row.** Their own issue, after a
+  passing gate.
+- **The NVlabs merged FP32 file and the community r128 file.** Not used
+  (Q1 default; unknown provenance).
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 12d35ac1..b1c6a165 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -393,6 +393,14 @@ remaining deferred fix is recorded in
   branch. Record, including what was deferred (audio intervals, masked
   tiles, chains, upstream `denoise_mask`):
   `complete/h3-regional-edit-complete.md`.
+- **H3 Open-Regenerate-2K refiner** (#1065, stages #1081-#1082), shipped
+  2026-10-31. A `trial` catalog entry for Kijai's rank-384 extraction of
+  NVlabs' regenerate refiner: it loads and fits a full-frame 1920x1088
+  refine on 24 GB, and is far sharper, but at strength 0.909 it redraws
+  identity (18.6 dB vs #1049 (d)'s 26.4). Adds `refine_sigmas`, an explicit
+  H3 refine schedule; the recipe's exact points measured the same as the
+  shift-2 grid. Don's lower-strength arms (0.6, 0.7) are still owed.
+  Record: `complete/h3-open-regenerate-2k-complete.md`.
 
 ## Declined
 

From 0e265cb18157fe6a0b76adb607f445ab1e916ceb Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 13:07:46 -0500
Subject: [PATCH 043/125] fix(video): #1109 - write fractional frame rates
 exactly

encode_video floored the rate with int(fps); a carried 29.97 was written at 29.
dw.writers.encode_video opens the video stream at the exact rational
(30000/1001). fps_errors no longer refuses a fractional result.fps.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/chain.py |  4 +-
 dw/result.py                    |  2 +-
 dw/step_value_checks.py         | 14 ++-----
 dw/workflow_schema.json         |  2 +-
 dw/writers.py                   | 71 +++++++++++++++++++++++++++++++++
 tests/test_fractional_fps.py    | 61 ++++++++++++++++++++++++++++
 tests/test_result_fps.py        | 13 ++----
 7 files changed, 143 insertions(+), 24 deletions(-)
 create mode 100644 tests/test_fractional_fps.py

diff --git a/dw/pipeline_processors/chain.py b/dw/pipeline_processors/chain.py
index 87801a8a..33a6a94c 100644
--- a/dw/pipeline_processors/chain.py
+++ b/dw/pipeline_processors/chain.py
@@ -40,12 +40,12 @@
 import numpy
 import torch
 from PIL import Image
-from diffusers.utils import encode_video, is_av_available
+from diffusers.utils import is_av_available
 
 from .. import empty_device_cache
 from ..media_types import AudioVideo, fit_codec_padding
 from ..output_extraction import get_artifact_list
-from ..writers import frames_for_encoding, output_file_path
+from ..writers import encode_video, frames_for_encoding, output_file_path
 from ..events import emit_log
 from ..shots import shot_record, without_samples
 from ..dsp import as_channels_samples, slice_samples
diff --git a/dw/result.py b/dw/result.py
index f46ff1bf..94fdd0e9 100644
--- a/dw/result.py
+++ b/dw/result.py
@@ -7,7 +7,6 @@
 from diffusers.utils import (
     export_to_video,
     export_to_gif,
-    encode_video,
     is_av_available,
 )
 from collections.abc import Mapping
@@ -31,6 +30,7 @@
 )
 from .output_extraction import get_artifact_list
 from .writers import (
+    encode_video,
     _artifact_size,
     _file_size_mb,
     as_audio_track,
diff --git a/dw/step_value_checks.py b/dw/step_value_checks.py
index bedc81b9..03c3d806 100644
--- a/dw/step_value_checks.py
+++ b/dw/step_value_checks.py
@@ -37,12 +37,9 @@
 # one frame-rate variable rather than a literal duplicated between the step
 # that generates and the step that writes (#363). This owns the resolved-value
 # check: once substitution has run, `result.fps` has to be a real, positive
-# frame rate, and it must be a whole number - `encode_video` (dw/result.py,
-# the writer used whenever a step's result carries audio) hands the value
-# straight to PyAV as `rate=int(fps)`, so a fractional rate like 23.976 would
-# be silently floored to 23 rather than written as asked. A frame_rate
-# variable declared as a float (24.0) still passes, since it carries no
-# fractional part; only a genuine fraction is refused.
+# frame rate. A fractional rate (23.976, 29.97) is allowed: `dw.writers`
+# writes it as the exact rational (24000/1001, 30000/1001) on both video
+# writers; it used to be refused because `encode_video` floored it to 23 (#1109).
 #
 # Containment doesn't apply here - there's no path to join - so unlike
 # subfolder_errors this only ever checks value shape.
@@ -77,11 +74,6 @@ def fps_errors(workflow_definition, source_indices=None):
             message = f"Invalid fps: {value!r} - fps is a number of frames per second"
         elif value <= 0:
             message = f"Invalid fps: {value!r} - fps must be greater than zero"
-        elif float(value) != int(value):
-            message = (
-                f"Invalid fps: {value!r} - fps must be a whole number; the video "
-                f"writer truncates a fractional rate rather than honoring it"
-            )
         if message is not None:
             errors.append(
                 {
diff --git a/dw/workflow_schema.json b/dw/workflow_schema.json
index 866f622e..c6a08fdc 100644
--- a/dw/workflow_schema.json
+++ b/dw/workflow_schema.json
@@ -1282,7 +1282,7 @@
                     ]
                 },
                 "fps": {
-                    "description": "Frames per second - only used when output is video. Defaults to the rate the frames themselves carry (a chain's 'fps', a join's own rate, the rate of the file a task read) and to 8 only when nothing knows better. Set it to write at a rate other than the source's - a deliberate slow motion - which the run then warns about. May be a 'variable:' or, inside a for_each step, an 'item:' reference, resolved the same way 'subfolder' is - the resolved value must be a positive whole number; a fractional rate is refused, since the video writer would silently truncate rather than honor it.",
+                    "description": "Frames per second - only used when output is video. Defaults to the rate the frames themselves carry (a chain's 'fps', a join's own rate, the rate of the file a task read) and to 8 only when nothing knows better. Set it to write at a rate other than the source's - a deliberate slow motion - which the run then warns about. May be a 'variable:' or, inside a for_each step, an 'item:' reference, resolved the same way 'subfolder' is - the resolved value must be a positive number; a fractional rate (23.976, 29.97) is written as the exact rational (24000/1001, 30000/1001).",
                     "type": ["integer", "number", "string"],
                     "default": 8
                 },
diff --git a/dw/writers.py b/dw/writers.py
index 52d8df2c..68991f3f 100644
--- a/dw/writers.py
+++ b/dw/writers.py
@@ -11,6 +11,7 @@
 import logging
 import os
 from collections.abc import Sequence
+from fractions import Fraction
 
 import numpy
 import soundfile
@@ -22,6 +23,76 @@
 logger = logging.getLogger("dw")
 
 
+def exact_frame_rate(fps):
+    """`fps` as the exact rational a container stores.
+
+    A float read back from a 29.97 file (29.97002997...), or a typed 29.97,
+    snaps to 30000/1001; 23.976 to 24000/1001; a whole rate stays whole. Any
+    other fraction is the nearest one with a denominator up to 1001.
+    """
+    if isinstance(fps, Fraction):
+        return fps
+    if float(fps) == int(fps):
+        return Fraction(int(fps))
+    # The NTSC family (24000/1001, 30000/1001, 60000/1001): a rounded 29.97
+    # is within a hair of one, and 2997/100 would drift against its audio
+    numerator = round(fps * 1001)
+    if numerator % 1000 == 0 and abs(numerator / 1001 - fps) < 0.005:
+        return Fraction(numerator, 1001)
+    rate = Fraction(fps).limit_denominator(1001)
+    return rate if rate > 0 else Fraction(fps)
+
+
+class _ExactRateContainer:
+    """An output container whose video stream is opened at the exact rate -
+    diffusers' `encode_video` passes `rate=int(fps)`, which floors 29.97 to 29."""
+
+    def __init__(self, container, rate):
+        self._container = container
+        self._rate = rate
+
+    def add_stream(self, codec, rate=None, **kwargs):
+        if codec == "libx264" and rate is not None:
+            rate = self._rate
+        return self._container.add_stream(codec, rate=rate, **kwargs)
+
+    def __getattr__(self, name):
+        return getattr(self._container, name)
+
+
+class _ExactRateAv:
+    def __init__(self, av, rate):
+        self._av = av
+        self._rate = rate
+
+    def open(self, *args, **kwargs):
+        container = self._av.open(*args, **kwargs)
+        if kwargs.get("mode", args[1] if len(args) > 1 else "r") != "w":
+            return container
+        return _ExactRateContainer(container, self._rate)
+
+    def __getattr__(self, name):
+        return getattr(self._av, name)
+
+
+def encode_video(video, fps, *args, **kwargs):
+    """diffusers' `encode_video`, writing a fractional `fps` exactly.
+
+    The stream gets 30000/1001 for a 29.97 source rather than 29, so a
+    carried phone-clip rate keeps picture and audio in step. The audio path
+    is untouched: only the video stream's `rate` is replaced.
+    """
+    from diffusers.utils import export_utils
+
+    rate = exact_frame_rate(fps)
+    original = export_utils._import_av
+    export_utils._import_av = lambda: _ExactRateAv(original(), rate)
+    try:
+        return export_utils.encode_video(video, int(fps), *args, **kwargs)
+    finally:
+        export_utils._import_av = original
+
+
 def _artifact_size(artifact):
     """How much there is to write, said the way the thing itself counts -
     frames for a video, samples for a waveform. Best effort: it is narration
diff --git a/tests/test_fractional_fps.py b/tests/test_fractional_fps.py
new file mode 100644
index 00000000..6c63a441
--- /dev/null
+++ b/tests/test_fractional_fps.py
@@ -0,0 +1,61 @@
+"""Fractional frame rates are written exactly, not floored (#1109)."""
+
+from fractions import Fraction
+
+import av
+import numpy
+import pytest
+import torch
+from diffusers.utils import export_to_video
+
+from dw.writers import encode_video, exact_frame_rate
+
+
+def _frames(count=30):
+    return numpy.zeros((count, 32, 32, 3), dtype=numpy.uint8)
+
+
+def _rate(path):
+    with av.open(str(path)) as container:
+        return container.streams.video[0].average_rate
+
+
+@pytest.mark.parametrize(
+    "fps, expected",
+    [
+        (29.97, Fraction(30000, 1001)),
+        (30000 / 1001, Fraction(30000, 1001)),
+        (23.976, Fraction(24000, 1001)),
+        (59.94, Fraction(60000, 1001)),
+        (24, Fraction(24)),
+        (24.0, Fraction(24)),
+    ],
+)
+def test_exact_frame_rate(fps, expected):
+    assert exact_frame_rate(fps) == expected
+
+
+def test_encode_video_with_audio_keeps_fractional_rate(tmp_path):
+    path = tmp_path / "out.mp4"
+    encode_video(
+        torch.from_numpy(_frames()),
+        fps=30000 / 1001,
+        output_path=str(path),
+        audio=torch.zeros(2, 48000),
+        audio_sample_rate=48000,
+    )
+    assert _rate(path) == Fraction(30000, 1001)
+    with av.open(str(path)) as container:
+        assert len(container.streams.audio) == 1
+
+
+def test_encode_video_whole_rate_unchanged(tmp_path):
+    path = tmp_path / "out.mp4"
+    encode_video(torch.from_numpy(_frames()), fps=24, output_path=str(path))
+    assert _rate(path) == 24
+
+
+def test_export_to_video_keeps_fractional_rate(tmp_path):
+    path = tmp_path / "out.mp4"
+    export_to_video(list(_frames()), str(path), fps=30000 / 1001, macro_block_size=16)
+    assert abs(float(_rate(path)) - 29.97) < 0.01
diff --git a/tests/test_result_fps.py b/tests/test_result_fps.py
index 2e0a62a2..4c69ff20 100644
--- a/tests/test_result_fps.py
+++ b/tests/test_result_fps.py
@@ -32,12 +32,10 @@ def test_a_whole_number_float_is_fine(self):
         definition = {"steps": [_step("a", {"fps": 24.0})]}
         assert fps_errors(definition) == []
 
-    def test_a_fractional_fps_is_reported_at_its_path(self):
+    def test_a_fractional_fps_is_fine(self):
+        # written as the exact rational (#1109)
         definition = {"steps": [_step("a", {"fps": 23.976})]}
-        errors = fps_errors(definition)
-        assert len(errors) == 1
-        assert errors[0]["path"] == "steps[0].result.fps"
-        assert "whole number" in errors[0]["message"]
+        assert fps_errors(definition) == []
 
     def test_a_non_positive_fps_is_reported(self):
         definition = {"steps": [_step("a", {"fps": 0})]}
@@ -110,9 +108,6 @@ def test_a_variable_driven_fps_resolves(self, tmp_path):
     def test_a_bad_resolved_fps_is_refused_at_validate_time(self, tmp_path):
         definition = {
             "id": "fps_test",
-            # float-typed, like the ltx2 templates' own frame_rate default -
-            # an integer-typed variable would itself truncate 23.976 to 23
-            # before fps_errors ever saw a fractional value
             "variables": {"frame_rate": 24.0},
             "steps": [
                 {
@@ -126,7 +121,7 @@ def test_a_bad_resolved_fps_is_refused_at_validate_time(self, tmp_path):
             ],
         }
         workflow = self._workflow(definition, tmp_path)
-        errors = workflow.validation_errors(arguments={"frame_rate": 23.976})
+        errors = workflow.validation_errors(arguments={"frame_rate": 0})
         assert [e["path"] for e in errors] == ["steps[0].result.fps"]
 
     def test_an_item_driven_fps_is_checked_per_member(self, tmp_path):

From 1d2d29a24bad26c26b709daf88f38ccfa2690214 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 13:51:48 -0500
Subject: [PATCH 044/125] docs(arch): #1109 - map row for writing a video at
 its rate, plus guard tests

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md         |  1 +
 tests/test_fractional_fps.py | 26 ++++++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 59501a5a..da2b6240 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -75,6 +75,7 @@ one to open.
 | Result subfolders | `dw/subfolders.py`: `subfolder_errors`, `dw/security.py`: `SUBFOLDER_PATTERN` | A step's `result.subfolder` is checked for shape at validation. | `tests/test_subfolders.py::TestValidationErrorsIntegration::test_validation_errors_reports_a_bad_subfolder` |
 | Template subfolder roles | `workflows/templates/`, `dw/workflows/` | Every saving step of a template is marked `final` or `intermediate`, with at least one `final`, and packaged builtins stay unmarked. | `tests/test_template_subfolders.py::test_every_saving_step_of_a_template_names_its_role`, `tests/test_template_subfolders.py::test_the_packaged_builtins_stay_unmarked` |
 | Frames carrying their rate | `dw/media_types.py`: `FrameList` (re-exported by `dw/tasks/video_utils.py`), `rated_videos` | The one list of frames (or of videos) that carries `.fps` and `.shots`: a video loaded from a file (`dw/argument_media.py`) and a step that knows its rate but would return bare frame lists both answer it - `h3_tiles`' tiled refine `videos`, and every pipeline step whose pipeline reports its own `fps` (MiniMax-H3's property; `dw/output_extraction.py`: `attach_video_frame_rate`, called by `pipeline.py`'s `_run_once` beside `attach_audio_sample_rate`, #1056) - through `rated_videos`, the batch and each video in it, so `pair_audio` and the result writer read `getattr(video, "fps", None)` instead of fitting and playing at the default 8 fps. A pipeline that reports no rate leaves its lists bare. No second class of that name. | `tests/test_h3_tiles.py::TestTileLoopReporting::test_the_videos_are_dws_one_frame_list`, `tests/test_pipeline_components.py::TestVideoFrameRate::test_a_dict_outputs_videos_carry_the_pipelines_rate`, `tests/test_pipeline_components.py::TestVideoFrameRate::test_a_pipeline_with_no_rate_leaves_the_lists_bare`, `tests/test_modular_output_properties.py::TestTheBasesOwnTakeSavesBesideIt::test_the_base_take_pairs_at_its_own_rate_with_no_padding`, `tests/test_video_utils.py` (the `FrameList` cases) |
+| Writing a video at its rate | `dw/writers.py`: `encode_video`, `exact_frame_rate` | A fractional rate is written as the exact rational (30000/1001, 24000/1001, 60000/1001), never truncated to a whole rate, and no `dw/` or `dw_mcp/` module imports `encode_video` from `diffusers.utils` - every audio-carrying video write goes through `dw.writers.encode_video` (`dw/result.py`, `dw/pipeline_processors/chain.py`). A declared fractional `result.fps` is therefore accepted by `fps_errors`. | `tests/test_fractional_fps.py::test_encode_video_with_audio_keeps_fractional_rate`, `tests/test_fractional_fps.py::test_no_dw_module_calls_the_diffusers_encode_video_directly`, `tests/test_fractional_fps.py::test_the_diffusers_hook_the_wrapper_swaps_still_exists` |
 | JSON records beside media | `dw/media_types.py`: `JsonRecord`, `dw/result.py`: `Result.save_artifact` | A dict marked `JsonRecord` is saved whole as one `.json`, whatever content type the step declares, and is never split into one file per key. | `tests/test_face_track.py::test_json_record_is_saved_whole_under_a_video_content_type`, `tests/test_face_track.py::test_the_task_result_saves_crops_as_video_and_track_as_one_json` |
 | Reading a JSON record back | `dw/locations.py`: `load_json_record` | A task reads a saved JSON record (`fit_to_model`'s, `crop_face_track`'s) only through `load_json_record`: the path is confined like any media path, then the extension must be `.json`, then the size is checked against `MAX_JSON_SIZE`, and only then is it parsed. `fit._read_fit` and `face_track._read_track` call it, never `open`. | `tests/test_locations.py::TestLoadJsonRecord::test_traversal_out_of_the_roots_is_refused`, `tests/test_locations.py::TestLoadJsonRecord::test_a_non_json_extension_is_refused`, `tests/test_locations.py::TestLoadJsonRecord::test_an_oversized_file_is_refused_before_it_is_read`, `tests/test_fit_to_model.py::TestRestore::test_fit_path_with_traversal_is_refused` |
 | Shots in a joined video | `dw/shots.py` | Every `AudioVideo` constructor decides what to do with `shots`, and the sample spans are measured from the joined waveform. | `tests/test_shots.py::test_every_audio_video_constructor_site_is_decided`, `tests/test_shots.py::TestConcatVideosShots::test_an_overrun_track_is_measured_not_derived` |
diff --git a/tests/test_fractional_fps.py b/tests/test_fractional_fps.py
index 6c63a441..1536229a 100644
--- a/tests/test_fractional_fps.py
+++ b/tests/test_fractional_fps.py
@@ -59,3 +59,29 @@ def test_export_to_video_keeps_fractional_rate(tmp_path):
     path = tmp_path / "out.mp4"
     export_to_video(list(_frames()), str(path), fps=30000 / 1001, macro_block_size=16)
     assert abs(float(_rate(path)) - 29.97) < 0.01
+
+
+def test_no_dw_module_calls_the_diffusers_encode_video_directly():
+    import re
+    from pathlib import Path
+
+    root = Path(__file__).resolve().parent.parent
+    pattern = re.compile(
+        r"diffusers\.utils(\.export_utils)?\s+import[^\n]*\bencode_video\b"
+    )
+    offenders = [
+        str(p.relative_to(root))
+        for folder in ("dw", "dw_mcp")
+        for p in (root / folder).rglob("*.py")
+        if p.name != "writers.py" and pattern.search(p.read_text())
+    ]
+    assert offenders == []
+
+
+def test_the_diffusers_hook_the_wrapper_swaps_still_exists():
+    import inspect
+
+    from diffusers.utils import export_utils
+
+    assert callable(export_utils._import_av)
+    assert 'add_stream("libx264"' in inspect.getsource(export_utils.encode_video)

From da0fd435a4de18d09112c4d8284f663ca9d7e56c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 13:56:45 -0500
Subject: [PATCH 045/125] feat(ltx2): #1079 - alpha-matte keeps vae, audio_vae
 and vocoder off the card

Plan v6, Q8 (a): the 145-frame cap ran out of memory on a warm 24 GB card.
The three decoders rest in system memory and visit the card only for their
own calls. The step-cache key moves with the placement; the VRAM estimate's
(pipeline, model, workflow) identity does not, so the template still
inherits restore-deblur's estimate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_ltx2_ic_loras.py               | 25 +++++++++++++++++++++++
 tests/test_step_cache.py                  |  2 +-
 workflows/templates/ltx2/alpha-matte.json |  9 +++++---
 3 files changed, 32 insertions(+), 4 deletions(-)

diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index 09c10773..c9fdd76c 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -277,3 +277,28 @@ def test_the_default_prompt_is_a_literal_the_caller_replaces(self):
 
         assert not workflow["variables"]["prompt"].startswith("prompt:")
         assert "Replace the default prompt" in workflow["description"]
+
+
+class TestTheAlphaMatteKeepsItsDecodersOffTheCard:
+    """#1079 (plan v6, Q8 (a)): the 145-frame cap ran out of memory on a warm
+    24 GB card. The VAE is only used to encode the reference and decode the
+    matte, and the matte never reads the audio, so all three rest in system
+    memory and visit the card only for their own calls."""
+
+    @pytest.mark.parametrize("component", ["vae", "audio_vae", "vocoder"])
+    def test_it_is_on_demand(self, component):
+        components = conditioned_step("alpha-matte")["pipeline"]["configuration"][
+            "components"
+        ]
+
+        assert components[component] == {"device": "cuda", "residency": "on_demand"}
+
+    def test_it_keeps_deblurs_pipeline_identity(self):
+        """The placement is not part of the (pipeline, model, workflow)
+        identity the VRAM estimate is matched on, so the matte still
+        inherits restore-deblur's estimate."""
+        from dw.vram_estimate import pipeline_identity
+
+        assert pipeline_identity(conditioned_step("alpha-matte")) == (
+            pipeline_identity(conditioned_step("restore-deblur"))
+        )
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index b896b788..6daff016 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -728,7 +728,7 @@ def test_normalized_downstream_false_when_nothing_references_it():
         "txt2img": "04031c5e01597b46f9ceb50f717e036013d5f6e6a497ae3aaef585f7121bcf4e"
     },
     "ltx2/alpha-matte.json": {
-        "matte": "1ee2f5927bde21fca0096fe39db8632238b1031e483d3a780695290b10b713cd"
+        "matte": "5a04e525d8c8e42ca75d84515b9318c09cfd1f4e55b1dce8f5e7dcd4ae685357"
     },
     "ltx2/chained-segments.json": {
         "chained_image_to_video": "3a36def4e09fe10832bc1821c7cb6fd82d9e050ba149e5b6e7afa6ec66f60f68"
diff --git a/workflows/templates/ltx2/alpha-matte.json b/workflows/templates/ltx2/alpha-matte.json
index 931360ec..6eb6d36a 100644
--- a/workflows/templates/ltx2/alpha-matte.json
+++ b/workflows/templates/ltx2/alpha-matte.json
@@ -92,13 +92,16 @@
                             }
                         },
                         "vae": {
-                            "device": "cuda"
+                            "device": "cuda",
+                            "residency": "on_demand"
                         },
                         "audio_vae": {
-                            "device": "cuda"
+                            "device": "cuda",
+                            "residency": "on_demand"
                         },
                         "vocoder": {
-                            "device": "cuda"
+                            "device": "cuda",
+                            "residency": "on_demand"
                         }
                     },
                     "vae": {

From d52f1aed9aab0eb11b7adf4ea3312f856f92d857 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 14:17:19 -0500
Subject: [PATCH 046/125] feat(plugin): #1100 - cutaway and lead-in joins in
 the script-to-video skill

references/joins.md: the cutaway (C continues from A's last frame, not B)
and the lead-in (render the target first, pin B's last_image to C's first
frame), story-order concat, and re-roll invalidation. SKILL.md step 2 gains
the per-shot join and the source rewrite of opening_state; step 5 one line
on render order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/script-to-video/SKILL.md    | 12 ++-
 .../script-to-video/references/joins.md       | 93 +++++++++++++++++++
 tests/test_plugin_skills.py                   | 49 +++++++++-
 3 files changed, 150 insertions(+), 4 deletions(-)
 create mode 100644 plugins/dw/skills/script-to-video/references/joins.md

diff --git a/plugins/dw/skills/script-to-video/SKILL.md b/plugins/dw/skills/script-to-video/SKILL.md
index dbb35384..3633938e 100644
--- a/plugins/dw/skills/script-to-video/SKILL.md
+++ b/plugins/dw/skills/script-to-video/SKILL.md
@@ -33,8 +33,13 @@ Fill in this shape before writing any prompt:
 - **Locations**: each place a shot happens, named once and reused.
 - **Per shot**: the above, plus `opening_state` (what is on screen, who
   stands where, what is held, at frame one) and `ending_state` (the same at
-  the last frame). A shot's `opening_state` is the previous shot's
-  `ending_state`, so the cut between them is written down rather than hoped for.
+  the last frame). A shot's `opening_state` is the `ending_state` of its
+  **source**, so the cut between them is written down rather than hoped for.
+- **Per shot, optional `join`**: `continue` (the default; its source is the
+  shot before), `cut` (opens fresh), `cutaway` (an insert: the shot after it
+  takes the shot before it as source) or `lead_in` (its last frame is the
+  next shot's first). Read `references/joins.md` before rendering a
+  `cutaway` or `lead_in`.
 
 Whatever the user supplied is locked; copy it, don't improve it. A field
 they left blank stays blank - ask, or mark it unspecified - and you invent
@@ -87,6 +92,9 @@ human (or an explicit pre-authorization) has signed off - this is a real
 gate, not a formality, and skipping it here is the one thing this skill
 must not do even when running unattended.
 
+Render in source order, not story order: a `lead_in`'s target first, and a
+re-roll quotes every shot taken off it (`references/joins.md`).
+
 Pass `note` on each `run_workflow` naming the shot and what the run tests,
 and `set_note` the take you keep: the note shows on every file it made.
 
diff --git a/plugins/dw/skills/script-to-video/references/joins.md b/plugins/dw/skills/script-to-video/references/joins.md
new file mode 100644
index 00000000..d4003baa
--- /dev/null
+++ b/plugins/dw/skills/script-to-video/references/joins.md
@@ -0,0 +1,93 @@
+# Script to video: cutaway and lead-in joins
+
+Part of the `script-to-video` skill; step 2's per-shot `join` says when to
+read this. Both joins are composed from separate runs of existing templates,
+joined in the cut by `concat_videos`. Nothing in a template reads `join`: it
+tells you which shot is a shot's **source**, and what to render first.
+
+The recipes are written for `dw:minimax-h3`. An LTX-2.5 re-entry works the
+same way, through `templates/ltx2/image-to-video` from the same still.
+
+## Taking a frame off a finished shot
+
+Both joins start from a still off a shot that already rendered. That is a
+one-step run of the `get_last_frame` (or `get_first_frame`) task, reading the
+shot's file by reference:
+
+```json
+{
+    "id": "shot-frame",
+    "steps": [
+        {
+            "name": "frame",
+            "task": {
+                "command": "get_last_frame",
+                "arguments": { "video": "output:<shot file>" }
+            },
+            "result": { "content_type": "image/png", "role": "intermediate" }
+        }
+    ]
+}
+```
+
+Pass the still on as `{"location": "output:<frame file>"}` (or `keep_output`
+it and use `asset:`). It cannot be a step inside the shot's own run: there is
+no step between two entries of one `for_each` list (`workflows` guide,
+`for_each`).
+
+## Cutaway: A, B, C
+
+A is the scene, B the insert (B-roll, a reaction, a detail), C the return.
+C's source is **A**, not B.
+
+1. Render A.
+2. Render B as its own shot: a `continue` off A (A's last frame into
+   `templates/minimax/image-to-video`) or a fresh `cut`, whichever the script
+   asks. Real B-roll is usually a cut.
+3. Render C from A: `get_last_frame` of `output:<A>`.
+   - A silent or action C: that still as `image` into
+     `templates/minimax/image-to-video`.
+   - A talking C: `templates/minimax/dialogue-short` with the same cast
+     references (portraits and voices) as A, so the voice carries; one
+     frame alone does not carry a voice.
+   - C's prompt opens on A's `ending_state`, never on B's.
+   - For a C that has to pick up motion mid-action, A's tail can go in as a
+     video reference instead (`templates/minimax/chain-video-continuity`'s
+     pattern): it keeps motion and audio context, at the cost of a
+     reference slot and the VRAM that clip takes. It is an option, not the
+     recipe.
+4. `concat_videos` A, B, C in **story order**. Both seams are real picture
+   cuts, so their `hard_cut` record is honest.
+5. Check the re-entry by comparing A's last frame with C's first
+   (`get_output_frames` on each), not seam 2: seam 2 is B into C, a cut that
+   is meant to jump.
+
+## Lead-in: B into C
+
+B's last frame is C's first frame. **Render the target first**: C before B.
+
+1. Render C.
+2. `get_first_frame` of `output:<C>`.
+3. Render B with `templates/minimax/first-and-last-frame`: `image` is B's
+   own opening (the source shot's last frame, or a still), `last_image` is
+   C's first frame. When B has no fixed opening, use
+   `templates/minimax/last-frame-only` (`last_image` alone).
+4. `concat_videos` B, C in story order. The seam is pinned by construction,
+   so its `hard_cut` skipping `seam_frame_jump` costs nothing; look at B's
+   last frame and C's first with `get_output_frames` anyway.
+
+Keep a lead-in short (the 124-frame floor or near it): the interpolation
+between two pinned frames drifts mid-shot over a long B.
+
+## Render order and re-rolls
+
+- Render order follows the sources, not the story: a lead-in's target goes
+  before the lead-in, and a cutaway's return waits only on A.
+- **Re-rolling C invalidates B** when B leads into C: B is re-rendered off
+  the new C's first frame, and the quote names both.
+- Re-rolling A invalidates any C that continues from it and any cutaway
+  taken off it; quote them with A.
+- A forced re-render counts as an attempt against the dependent shot's
+  three-attempt budget.
+- These are separate shots, so `concat_videos` is the assembly, not a splice:
+  "never splice a re-rolled segment into a chain" still holds for chains.
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index f9d7a76e..41b1ac4f 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -152,7 +152,7 @@ def test_every_catalog_name_a_skill_quotes_resolves(path):
 SKILL_TASKS = {
     "minimax-music3": ["attribute_voices"],
     "minimax-h3": ["join_into_song", "slice_audio", "normalize_audio", "pair_audio"],
-    "script-to-video": ["concat_videos"],
+    "script-to-video": ["concat_videos", "get_first_frame", "get_last_frame"],
     "series-episodes": ["apply_lut", "film_grain", "concat_videos", "loop_audio"],
 }
 
@@ -167,7 +167,9 @@ def test_every_task_a_skill_names_is_in_list_tasks(skill, task):
 
     path = os.path.join(PLUGIN_DIR, "skills", skill, "SKILL.md")
     assert f"`{task}`" in skill_text(path)
-    assert task in list_tasks()["commands"]
+    tasks = list_tasks()
+    # get_first_frame and its kin are listed as video processors, not commands
+    assert task in tasks["commands"] + tasks["video_processors"]
 
 
 H3_SKILL = os.path.join(PLUGIN_DIR, "skills", "minimax-h3", "SKILL.md")
@@ -845,6 +847,49 @@ def test_the_skill_starts_with_the_server(self):
         assert text.index("get_server_info") < text.index("templates/flux3/")
 
 
+SCRIPT_SKILL = os.path.join(PLUGIN_DIR, "skills", "script-to-video", "SKILL.md")
+SCRIPT_JOINS = os.path.join(os.path.dirname(SCRIPT_SKILL), "references", "joins.md")
+
+
+class TestScriptToVideoJoins:
+    """The cutaway and lead-in joins (#1093): composed from separate runs,
+    with the order the lead-in needs stated, since nothing enforces it."""
+
+    def test_the_shot_list_names_every_join_and_links_the_recipes(self):
+        body = skill_body(SCRIPT_SKILL)
+        for join in ("`continue`", "`cut`", "`cutaway`", "`lead_in`"):
+            assert join in body
+        assert "`ending_state` of its\n  **source**" in body
+        assert "`references/joins.md`" in body
+
+    def test_the_recipes_name_both_joins_and_render_the_target_first(self):
+        text = open(SCRIPT_JOINS, encoding="utf-8").read()
+        assert "## Cutaway" in text and "## Lead-in" in text
+        assert "Render the target first" in text
+        assert "Re-rolling C invalidates B" in text
+        # the cutaway's return continues from A, the lead-in pins C's opening
+        assert "`get_last_frame` of `output:<A>`" in text
+        assert "`get_first_frame` of `output:<C>`" in text
+
+    def test_the_frame_step_is_a_real_task_step(self, tmp_path):
+        from dw.workflow import workflow_from_file
+
+        workflow = json.loads(
+            _fenced_block_after(
+                open(SCRIPT_JOINS, encoding="utf-8").read(),
+                "## Taking a frame off a finished shot",
+            )
+        )
+        step = workflow["steps"][0]
+        assert step["task"]["command"] == "get_last_frame"
+        step["task"]["arguments"]["video"] = "variable:video"
+        workflow["variables"] = {"video": "shot.mp4"}
+        (tmp_path / "shot.mp4").write_bytes(b"")
+        path = tmp_path / "shot-frame.json"
+        path.write_text(json.dumps(workflow), encoding="utf-8")
+        workflow_from_file(str(path), str(tmp_path)).validate()
+
+
 SERIES_SKILL = os.path.join(PLUGIN_DIR, "skills", "series-episodes", "SKILL.md")
 SERIES_LOOK = os.path.join(os.path.dirname(SERIES_SKILL), "references", "look.md")
 

From e73d53d62640997d2c3ddcb0a9bb8e03779ff5c3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 14:42:59 -0500
Subject: [PATCH 047/125] fix(templates): #1110 - price last-frame-only and
 first-and-last-frame at the family canvas

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 tests/test_cost_scaling_h3_frames.py          | 23 +++++++++++++++++++
 .../minimax/first-and-last-frame.json         |  8 +++++++
 .../templates/minimax/last-frame-only.json    |  8 +++++++
 3 files changed, 39 insertions(+)
 create mode 100644 tests/test_cost_scaling_h3_frames.py

diff --git a/tests/test_cost_scaling_h3_frames.py b/tests/test_cost_scaling_h3_frames.py
new file mode 100644
index 00000000..abc62bdd
--- /dev/null
+++ b/tests/test_cost_scaling_h3_frames.py
@@ -0,0 +1,23 @@
+"""The H3 frame-anchored templates quote a price at the family canvas (#1110)."""
+
+import json
+from pathlib import Path
+
+import pytest
+
+from dw.cost_scaling import scale_curated
+
+ROOT = Path(__file__).resolve().parent.parent / "workflows/templates/minimax"
+
+
+@pytest.mark.parametrize("name", ["last-frame-only", "first-and-last-frame"])
+def test_960x544_is_priced_near_the_measured_run(name):
+    definition = json.loads((ROOT / f"{name}.json").read_text())
+    minutes = definition["cost"][0]["minutes"]
+    defaults = definition["variables"]
+    scaled, axes = scale_curated(
+        minutes,
+        {k: defaults[k] for k in ("width", "height")},
+        {"width": 960, "height": 544},
+    )
+    assert axes and scaled == pytest.approx(3.5, abs=0.1)
diff --git a/workflows/templates/minimax/first-and-last-frame.json b/workflows/templates/minimax/first-and-last-frame.json
index 16853e4b..c046ba32 100644
--- a/workflows/templates/minimax/first-and-last-frame.json
+++ b/workflows/templates/minimax/first-and-last-frame.json
@@ -2,6 +2,14 @@
     "id": "MiniMaxH3FL2VA",
     "description": "Conditioning on both ends of the clip at once. The 'fl2va' workflow is given an 'image' and a 'last_image', pinning the first and final frames so the model interpolates the motion between two fixed states rather than inventing an ending. Pointing both at the same picture is what makes a clip that returns to where it started, the building block for a seamless loop.",
     "summary": "H3 video with audio between two supplied stills pinned as first and last frames; the same still at both ends loops.",
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 2.0
+        }
+    ],
     "cost_drivers": [
         "num_frames",
         "num_inference_steps",
diff --git a/workflows/templates/minimax/last-frame-only.json b/workflows/templates/minimax/last-frame-only.json
index 936da62d..22efc45c 100644
--- a/workflows/templates/minimax/last-frame-only.json
+++ b/workflows/templates/minimax/last-frame-only.json
@@ -2,6 +2,14 @@
     "id": "MiniMaxH3L2V",
     "description": "Conditioning on the end of the clip alone. The 'fl2va' workflow takes a 'last_image' without an 'image', which pins the final frame and leaves the model to invent everything that leads up to it - the reverse of a keyframe start, and the way to generate the approach to a picture you already have. The prompt uses the L2VA alignment line, which states which second of the target video the picture lands on.",
     "summary": "H3 video with audio that ends on a supplied still, inventing the approach to it.",
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 2.0
+        }
+    ],
     "cost_drivers": [
         "num_frames",
         "num_inference_steps",

From db71fc1ad30a6eacaef3cffe89bd2d165d5e2bad Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 14:53:25 -0500
Subject: [PATCH 048/125] feat(face-track): #1098 - crops carry the padded
 soundtrack; min_frames, max_frames and fps refusals

crop_face_track hands the clip's soundtrack on under the crops, with
pad_before / pad_after frames of silence, so a hold of the crops' audio
lines up frame for frame; a silent clip gives silent crops. Optional
min_frames / max_frames refuse a padded crop count outside the model's
window, and fps refuses a clip not at that rate (within 0.01), before the
detector loads. min > max is a validate error. TASKS.md documents both and
H3's 17/5/32 grid. The LTX template is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md       |   2 +-
 docs/TASKS.md              |  29 ++++-
 dw/task_problems.py        |  17 ++-
 dw/tasks/face_track.py     | 161 ++++++++++++++++++++++++++--
 dw/tasks/video_handlers.py |  17 ++-
 tests/test_face_track.py   | 209 +++++++++++++++++++++++++++++++++++++
 6 files changed, 420 insertions(+), 15 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index da2b6240..430df69c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -35,7 +35,7 @@ one to open.
 | Step-cache skip counts | `dw/pipeline_processors/timing.py`: `CacheCounter`, `counting_forwards`, `report_cache_stats`, `StepTimer.cache_counted`; `dw/pipeline_processors/components.py`: `stateful_cache_context`; `dw/pipeline_processors/mag_calibration.py`: `get_cache_transformer`, `captured_mag_calibration` | For `first_block` and `mag`, a forward hook on the cache transformer counts computed or skipped once per forward, reading the leader hook's `should_compute` inside the cond/uncond `cache_context` the pipeline opened, so classifier-free guidance counts both forwards. `stateful_cache_context` registers the hook for one pipeline call; its `finally` emits `cache_stats` before `_reset_stateful_cache()` and removes the hook after the event. Private diffusers state that has moved gives null counts and one `cache_stats_unavailable` warning, and never fails the run; `taylorseer`, `faster` and `text_kv` report type and config only, with no warning. The denoiser a cache attaches to (`get_cache_transformer`) and the MagCache calibration capture (`captured_mag_calibration`, the end-of-run log record turned into `cache_stats`-side job events, #891/#927) live in `mag_calibration.py`, which `components.py` imports and re-exports for `pipeline.py`, never the reverse. The counts reach the step's `timing.cache` only through `StepTimer.cache_counted`; a chain sums its calls' counts, and a null in any call nulls the sum. A step with no `cache` has no `cache` key and no event (`docs/ACCELERATION.md` *Reading the skip counts*). | `tests/test_cache_stats.py::test_cfg_counts_two_forwards_per_step_and_they_add_up`, `tests/test_cache_stats.py::test_the_event_names_the_step_and_segment_and_goes_out_before_the_reset`, `tests/test_cache_stats.py::test_moved_hook_state_nulls_the_counts_warns_once_and_the_run_finishes`, `tests/test_cache_stats.py::test_the_private_diffusers_names_are_where_the_counter_reads_them`, `tests/test_cache_stats.py::test_the_timer_sums_counts_and_nulls_on_any_null`, `tests/test_cache_stats.py::test_types_without_a_decision_report_type_only_and_no_warning` |
 | Community pipelines | `dw/community_pipelines/` (e.g. `pipeline_ltx2_refine.py`: `LTX2RefinePipeline`), `dw/introspection.py`: `community_pipelines`, `load_allowed_class` | A pipeline dw ships is named by its dotted path (`dw.community_pipelines.<module>.<Class>`), loads untrusted because it is under `dw`, and is listed by `list_pipelines` and resolved by `get_pipeline_signature` - only the modules in that directory, never a caller-chosen import. `LTX2RefinePipeline` VAE-encodes `video` at `width` x `height` and passes it unnormalized as `latents`, because `LTX2Pipeline.prepare_latents` normalizes 5-D latents itself. | `tests/test_ltx2_refine_pipeline.py::TestIntrospection::test_only_the_shipped_modules_resolve`, `tests/test_ltx2_refine_pipeline.py::TestEncode::test_the_latents_are_left_unnormalized_for_the_parent` |
 | Adding a task | `dw/tasks/registry.py`: `register_command`, `RegistryTable` | A task is a function registered with `@register_command`, and the signature of its implementation is its argument schema. Its validate-time rules are declared on the same decorator - `domains`, `choices`, `static_check`, `whole_numbers` and `media_arguments` - and `TASK_ARGUMENT_DOMAINS`, `TASK_ARGUMENT_CHOICES`, `TASK_STATIC_CHECKS`, `TASK_WHOLE_NUMBER_ARGUMENTS` and `TASK_MEDIA_ARGUMENTS` are read-only views derived from them, so there is no second table to forget (#692). The registry lives in `dw/tasks/registry.py`; `dw/tasks/task.py` re-exports it, and a task module may register its own handler, as `dw/tasks/beats.py` does, provided `dw/tasks/task.py` imports it (`docs/TASKS.md` *Adding a task*). The built-in handlers are grouped by family the same way - `dw/tasks/audio_handlers.py`, `dw/tasks/video_handlers.py`, `dw/tasks/finish_handlers.py` and `dw/tasks/model_handlers.py` (#790) - and `dw/tasks/task.py` keeps the general-purpose commands, the processor dispatch and `Task`. | `tests/test_task_discovery.py::TestDescribeTask::test_signature_becomes_the_schema`, `tests/test_task_registry_rules.py::test_every_derived_table_is_the_registrys_view`, `tests/test_task_registry_rules.py::test_every_static_check_is_registered_to_exactly_one_command`, `tests/test_task_registry_rules.py::test_every_media_argument_is_a_parameter_of_its_command` |
-| Task argument domains | `dw/task_domains.py`: `check_arguments`, `task_argument_errors`; `dw/task_problems.py`: `face_track_errors`, `beats_errors`, `cuts_errors`, `lut_errors` | A numeric domain that a signature cannot express is declared on the command's `@register_command(domains=...)`, and it is checked at validation and again at run time. A numeric argument is read by `whole_number` or `real_number`, the only numeric coercion in `dw/tasks/`, and validation applies the same rule (`number_problem`), so a value is refused at both or at neither: `"3.0"` is a whole number, `"3.5"` for one of `whole_numbers` is not, and `true` is no number (#774). `Task.run` coerces every declared argument through `coerce_arguments` before dispatch, so a handler sees a number, and an argument that has no range besides being a number declares `finite`. A command's cross-argument rules are its registered `static_check`, which `task_argument_errors` runs at validation (`attribute_voices`' `voices_argument_errors`, kept in `dw/tasks/voice_attribution.py`, among them). A literal enum choice (`choice_errors`) is refused at validation by the same module. The per-family rules past a single domain live in `dw/task_problems.py`, which reads `task_domains`' helpers and is never imported by it (`task_argument_errors` reaches them only through the registered `static_check`, so `import_cycles` stays 0; #790): the `ingredients_grid` image count against `max_images` (`ingredients_grid_errors`), and `crop_face_track`'s cross-argument rules (`face_track_problems`, `face_track_errors`: crop size a multiple of the step's `multiple` (32 by default), `remainder` below `modulus`, `gate_zero` above `gate_full`, padding and confidence limits), which the task checks again at run time, as `analyze_beats`' are too (`beats_problems`, `beats_errors`: `min_bpm` below `max_bpm`, and anchors that are one kind per list, ascending, with whole beat indexes; `tests/test_analyze_beats.py`), and `plan_cuts`' (`cuts_problems`, `cuts_errors`: a bare-string transcript (`transcript_problem`, which `plan_cuts` also calls at run time), `min_scene_s` above `max_scene_s`, `segment_by: "beat"` without beats), and `apply_lut`'s (`lut_source_problem`, `palette_problem`, `lut_errors`: exactly one of `lut` or `palette`, and a palette of 2..16 `#rrggbb` colours, re-checked at run time by `check_lut_source`), and `check_face_detector_source` vets its Hub repo and `.onnx` file before any download. `select`'s index stays in `task_domains` with the other media-timing rules (`select_index_problem`, `select_rule_problems`: a whole number, at least 0, and below the candidate count when the count is known, i.e. at run time or when `candidates` is a written list). | `tests/test_task_domains.py::TestTheStaticPass::test_a_negative_frame_count_is_refused_at_its_path`, `tests/test_numeric_coercion.py::TestGradeExposure::test_a_string_number_grades_like_the_number`, `tests/test_task_domains.py::TestAtRunTime::test_slice_audio_refuses_a_negative_count`, `tests/test_ingredients_grid.py::TestStaticValidation::test_bad_layout_and_fit`, `tests/test_face_track.py::TestStaticValidation::test_bad_literal_is_an_error_at_its_argument`, `tests/test_face_track.py::TestCropFaceTrack::test_bad_arguments_are_refused_at_run_time`, `tests/test_face_track.py::TestStaticValidation::test_a_declared_grid_is_accepted`, `tests/test_face_track.py::TestDetectorSource::test_traversing_repo_is_refused`, `tests/test_select_validation.py::TestSelectErrors::test_an_out_of_range_literal_index_names_both_ends`, `tests/test_lut.py::TestPaletteAtValidate::test_both_refuse_naming_the_two`, `tests/test_lut.py::TestPalette::test_a_bad_palette_refuses_naming_the_entry` |
+| Task argument domains | `dw/task_domains.py`: `check_arguments`, `task_argument_errors`; `dw/task_problems.py`: `face_track_errors`, `beats_errors`, `cuts_errors`, `lut_errors` | A numeric domain that a signature cannot express is declared on the command's `@register_command(domains=...)`, and it is checked at validation and again at run time. A numeric argument is read by `whole_number` or `real_number`, the only numeric coercion in `dw/tasks/`, and validation applies the same rule (`number_problem`), so a value is refused at both or at neither: `"3.0"` is a whole number, `"3.5"` for one of `whole_numbers` is not, and `true` is no number (#774). `Task.run` coerces every declared argument through `coerce_arguments` before dispatch, so a handler sees a number, and an argument that has no range besides being a number declares `finite`. A command's cross-argument rules are its registered `static_check`, which `task_argument_errors` runs at validation (`attribute_voices`' `voices_argument_errors`, kept in `dw/tasks/voice_attribution.py`, among them). A literal enum choice (`choice_errors`) is refused at validation by the same module. The per-family rules past a single domain live in `dw/task_problems.py`, which reads `task_domains`' helpers and is never imported by it (`task_argument_errors` reaches them only through the registered `static_check`, so `import_cycles` stays 0; #790): the `ingredients_grid` image count against `max_images` (`ingredients_grid_errors`), and `crop_face_track`'s cross-argument rules (`face_track_problems`, `face_track_errors`: crop size a multiple of the step's `multiple` (32 by default), `remainder` below `modulus`, `gate_zero` above `gate_full`, `max_frames` at or above `min_frames`, padding and confidence limits), which the task checks again at run time, as `analyze_beats`' are too (`beats_problems`, `beats_errors`: `min_bpm` below `max_bpm`, and anchors that are one kind per list, ascending, with whole beat indexes; `tests/test_analyze_beats.py`), and `plan_cuts`' (`cuts_problems`, `cuts_errors`: a bare-string transcript (`transcript_problem`, which `plan_cuts` also calls at run time), `min_scene_s` above `max_scene_s`, `segment_by: "beat"` without beats), and `apply_lut`'s (`lut_source_problem`, `palette_problem`, `lut_errors`: exactly one of `lut` or `palette`, and a palette of 2..16 `#rrggbb` colours, re-checked at run time by `check_lut_source`), and `check_face_detector_source` vets its Hub repo and `.onnx` file before any download. `select`'s index stays in `task_domains` with the other media-timing rules (`select_index_problem`, `select_rule_problems`: a whole number, at least 0, and below the candidate count when the count is known, i.e. at run time or when `candidates` is a written list). | `tests/test_task_domains.py::TestTheStaticPass::test_a_negative_frame_count_is_refused_at_its_path`, `tests/test_numeric_coercion.py::TestGradeExposure::test_a_string_number_grades_like_the_number`, `tests/test_task_domains.py::TestAtRunTime::test_slice_audio_refuses_a_negative_count`, `tests/test_ingredients_grid.py::TestStaticValidation::test_bad_layout_and_fit`, `tests/test_face_track.py::TestStaticValidation::test_bad_literal_is_an_error_at_its_argument`, `tests/test_face_track.py::TestCropFaceTrack::test_bad_arguments_are_refused_at_run_time`, `tests/test_face_track.py::TestStaticValidation::test_a_declared_grid_is_accepted`, `tests/test_face_track.py::TestDetectorSource::test_traversing_repo_is_refused`, `tests/test_select_validation.py::TestSelectErrors::test_an_out_of_range_literal_index_names_both_ends`, `tests/test_lut.py::TestPaletteAtValidate::test_both_refuse_naming_the_two`, `tests/test_lut.py::TestPalette::test_a_bad_palette_refuses_naming_the_entry` |
 | Variables | `dw/variables.py`: `set_variables`, `argument_errors`, `resolve_variable_values` | `argument_errors` folds a caller's arguments in exactly as `set_variables` does when a run starts, so a bad name or value is refused before anything is queued. | `tests/test_variables.py::test_argument_errors_reports_a_dict_passed_for_a_string_variable` |
 | List variables from the CLI | `dw/run.py`, `dw/variables.py`: `get_value` | A `name=value` string given for a list variable is split on commas, so a list of objects can only be passed as JSON over the API or MCP. | `tests/test_variables.py::test_set_variables_list_default_splits_on_comma` |
 | `for_each` expansion | `dw/for_each.py`: `expand_for_each`, `group_of` | Each entry becomes an ordinary step named `<step>@<entry>`, after substitution and before the reference check. | `tests/test_for_each.py::TestNaming::test_member_name_joins_with_at` |
diff --git a/docs/TASKS.md b/docs/TASKS.md
index b4036017..f37a6147 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1153,6 +1153,9 @@ face-detail pass that needs the face large and still:
 | `modulus` | No | The crop count is padded to `modulus * n + remainder` frames - the frame grid of the model the crops feed. At least `1`. Default `8` |
 | `remainder` | No | The padded count's remainder, `0` up to `modulus - 1`. Default `1` |
 | `multiple` | No | `crop_size` must be a multiple of this - the model's frame-size step. At least `1`. Default `32` |
+| `min_frames` | No | Refuse the clip when its padded crop count is below this - the shortest clip the model the crops feed takes. A whole number, at least `1`. No check when unset |
+| `max_frames` | No | Refuse the clip when its padded crop count is above this - the longest the model takes. A whole number, at least `min_frames`. No check when unset |
+| `fps` | No | Refuse the clip unless its frame rate is this, within `0.01` (23.976 passes for `23.98`, not for `24`). Above `0`. No check when unset |
 | `detector_repo` | No | Hub repo holding the YuNet weights. Default `opencv/face_detection_yunet`, read at a pinned revision; any other must be a Hub repo id |
 | `detector_file` | No | The detector file in that repo, a bare `.onnx` name. Default `face_detection_yunet_2023mar.onnx` |
 | `device` | No | Where detection runs |
@@ -1163,7 +1166,8 @@ A validate's `downloads_required` lists the detector file as a file entry when i
 the workflow's to declare. The defaults (8, 1, 32) are LTX's 8n+1 frames and
 32-pixel steps, so a workflow that names none gets the output it always did;
 the `face-repair` template passes `modulus: 8, remainder: 1, multiple: 32`
-explicitly. A `modulus` below 1, a `remainder` below 0 or not below `modulus`,
+explicitly. A model on another grid names its own: MiniMax H3's is `modulus:
+17, remainder: 5, multiple: 32` (17n+5 frames, 32-pixel steps). A `modulus` below 1, a `remainder` below 0 or not below `modulus`,
 and a `crop_size` that is not a multiple of `multiple` are refused at
 validation.
 
@@ -1190,8 +1194,21 @@ change it. It is 1 when face width over frame width is at or below `gate_full`,
 0 at or above `gate_zero`, linear between, and multiplied by the hold decay on
 frames the detector missed.
 
-It returns `{crops, track}`. `crops` is a video (no audio) at the clip's frame
-rate. `track` is a JSON record saved as its own `.json` file, readable by
+`min_frames`, `max_frames` and `fps` refuse a clip the model the crops feed
+cannot take, before the detector loads: the window is checked against the
+padded crop count, and the message names both the clip's frame count and the
+count it pads to (`the clip's 346 frames pad to 362 crops on the 17n+5 grid,
+above max_frames 345`). A clip that records no frame rate is refused when
+`fps` is set.
+
+It returns `{crops, track}`. `crops` is a video at the clip's frame rate. When
+the clip has a soundtrack, `crops` carries it padded to match: `pad_before`
+frames of silence, the clip's own sound, then `pad_after` frames of silence, so
+the track is exactly `crop_frames / fps` seconds long and a step holding the
+crops' audio (`hold_audio: previous_result:<step>.crops`) lines up with them
+frame for frame. A silent clip gives crops with no audio; a soundtrack on a
+clip with no frame rate to place it by is dropped, with a `crop_audio_dropped`
+warning. `track` is a JSON record saved as its own `.json` file, readable by
 `previous_result:<step>.track`:
 
 | Field | Description |
@@ -1209,8 +1226,10 @@ rate. `track` is a JSON record saved as its own `.json` file, readable by
 A clip with no face still succeeds: every strength is 0, the crops are the
 centre square, and a `no_face_found` warning is raised. `validate_workflow`
 refuses a `crop_size` that is not a multiple of 32, a `gate_zero` at or below
-`gate_full`, a `padding` out of range, a `detector_repo` that is not a repo id
-and a `detector_file` that is not a `.onnx` name, before anything downloads.
+`gate_full`, a `padding` out of range, a `detector_repo` that is not a repo id,
+a `detector_file` that is not a `.onnx` name, a `min_frames`, `max_frames` or
+`fps` at or below 0, and a `max_frames` below `min_frames`, before anything
+downloads.
 
 ### paste_face_track
 
diff --git a/dw/task_problems.py b/dw/task_problems.py
index 08564117..47371865 100644
--- a/dw/task_problems.py
+++ b/dw/task_problems.py
@@ -79,7 +79,8 @@ def ingredients_grid_errors(arguments):
 # whose frame size and count move on a grid the workflow declares (modulus,
 # remainder and multiple; the defaults are LTX's 8n+1 and 32 pixels), the
 # padding is a multiple of the face's own size added on each side, and the gate
-# is a ramp from gate_full to gate_zero, so the two must be in that order.
+# is a ramp from gate_full to gate_zero, so the two must be in that order, as
+# must the min_frames/max_frames window the padded crop count must fall in.
 # Owned here so the static pass and the command's run-time refusal read one rule
 FACE_CROP_MODULUS = 8
 FACE_CROP_REMAINDER = 1
@@ -97,6 +98,8 @@ def face_track_problems(
     modulus=FACE_CROP_MODULUS,
     remainder=FACE_CROP_REMAINDER,
     multiple=FACE_CROP_MULTIPLE,
+    min_frames=None,
+    max_frames=None,
 ):
     """[(argument, message)] for each crop_face_track rule these values break.
 
@@ -175,6 +178,16 @@ def face_track_problems(
                 f"{min_confidence!r}",
             )
         )
+    low, high = as_number(min_frames), as_number(max_frames)
+    if low is not None and high is not None and low > high:
+        problems.append(
+            (
+                "max_frames",
+                f"crop_face_track needs 'max_frames' at or above 'min_frames' "
+                f"- the window the crop count must fall in - got min_frames "
+                f"{min_frames!r} and max_frames {max_frames!r}",
+            )
+        )
     return problems
 
 
@@ -231,6 +244,8 @@ def face_track_errors(arguments):
             "modulus",
             "remainder",
             "multiple",
+            "min_frames",
+            "max_frames",
         )
         if name in arguments
     }
diff --git a/dw/tasks/face_track.py b/dw/tasks/face_track.py
index 654986cb..a0ef28d0 100644
--- a/dw/tasks/face_track.py
+++ b/dw/tasks/face_track.py
@@ -24,6 +24,12 @@
 so strength falls from 1 at `gate_full` (face width over frame width) to 0 at
 `gate_zero`.
 
+The crops are padded, by reflection, to the frame grid of the model they feed
+(`modulus` * n + `remainder`), and a clip with a soundtrack hands it on under
+them, with the same padding laid in as silence, so a step holding the crops'
+audio lines up with them frame for frame. `min_frames`, `max_frames` and `fps`
+refuse a clip the model cannot take before the detector loads.
+
 `paste_face_track` is the other half: given the clip, the crops after a
 face-detail pass, and the track, it puts each repaired crop back over its
 square with a feathered round mask scaled by that frame's strength, so the
@@ -35,6 +41,7 @@
 import numpy as np
 from PIL import Image
 
+from ..dsp import as_channels_samples
 from ..events import emit_log, emit_warning
 from ..media_types import AudioVideo, JsonRecord
 from ..shots import carried_shots
@@ -46,6 +53,7 @@
     face_track_problems,
     paste_feather_problems,
 )
+from ..task_domains import check_arguments
 from ..variable_constraints import aligned
 from .video_utils import frames_as_pil_list, load_audio_video
 from .weights import argument_or_default, file_entries
@@ -78,6 +86,10 @@
 CUT_SPIKE = 4.0
 CUT_WINDOW = 8  # frames each side whose differences form that median
 
+# How far a clip's frame rate may sit from a requested `fps`: 23.976 passes
+# for 23.98 but not for 24
+FPS_TOLERANCE = 0.01
+
 
 def _iou(a, b):
     """Overlap of two [x, y, w, h] boxes, as intersection over union."""
@@ -346,6 +358,76 @@ def pad_frames(crops, before, after):
     return [crops[i] for i in indices]
 
 
+def padded_audio(audio, sample_rate, fps, frames, before, after):
+    """The source track laid under the padded crops: `before` frames of
+    silence, the source's own `frames` frames of sound (cut or silence-padded
+    to that length), then `after` frames of silence - so sample 0 of the
+    result is crop 0 and a hold of it lines up with the crops frame for frame.
+
+    Every boundary is rounded from frame times, so the track is exactly
+    `(before + frames + after) / fps` long and its head is exactly `before`
+    frames.
+    """
+    waveform = as_channels_samples(audio)
+    per_frame = float(sample_rate) / float(fps)
+    head = int(round(before * per_frame))
+    body = int(round((before + frames) * per_frame)) - head
+    total = int(round((before + frames + after) * per_frame))
+    out = np.zeros((waveform.shape[0], total), dtype=np.float32)
+    kept = min(body, waveform.shape[1])
+    out[:, head : head + kept] = waveform[:, :kept]
+    return out
+
+
+def _rate_text(rate):
+    """A frame rate as a person writes it: 30, 23.976."""
+    return f"{float(rate):.3f}".rstrip("0").rstrip(".")
+
+
+def window_problems(frames, crop_frames, grid, min_frames, max_frames):
+    """Messages for a padded crop count outside [min_frames, max_frames]."""
+    problems = []
+    for name, bound, outside, side in (
+        ("min_frames", min_frames, lambda b: crop_frames < b, "below"),
+        ("max_frames", max_frames, lambda b: crop_frames > b, "above"),
+    ):
+        if bound is not None and outside(bound):
+            problems.append(
+                f"crop_face_track: the clip's {frames} frames pad to "
+                f"{crop_frames} crops on the {grid} grid, {side} {name} "
+                f"{int(bound)} - the model the crops feed takes "
+                f"{_window_text(min_frames, max_frames)}"
+            )
+    return problems
+
+
+def _window_text(min_frames, max_frames):
+    if min_frames is not None and max_frames is not None:
+        return f"{int(min_frames)} to {int(max_frames)} frames"
+    if min_frames is not None:
+        return f"at least {int(min_frames)} frames"
+    return f"at most {int(max_frames)} frames"
+
+
+def rate_problem(clip_fps, fps):
+    """The message for a clip not at `fps` (within FPS_TOLERANCE), or None."""
+    if fps is None:
+        return None
+    if clip_fps is None:
+        return (
+            f"crop_face_track needs a clip at {_rate_text(fps)} fps, and this "
+            f"one carries no frame rate - pass a video file, or a step's "
+            f"video that records its rate"
+        )
+    if abs(float(clip_fps) - float(fps)) > FPS_TOLERANCE:
+        return (
+            f"crop_face_track needs a clip at {_rate_text(fps)} fps, and this "
+            f"one is {_rate_text(clip_fps)} fps - re-render or convert it to "
+            f"that rate first, or drop the 'fps' argument"
+        )
+    return None
+
+
 def detector_source(arguments):
     """The (repo, file, revision) a crop_face_track step loads YuNet from -
     `detector_repo` and `detector_file` over the defaults, the default repo
@@ -414,6 +496,9 @@ def crop_face_track(
     modulus=FACE_CROP_MODULUS,
     remainder=FACE_CROP_REMAINDER,
     multiple=FACE_CROP_MULTIPLE,
+    min_frames=None,
+    max_frames=None,
+    fps=None,
     detector_repo=DEFAULT_DETECTOR_REPO,
     detector_file=DEFAULT_DETECTOR_FILE,
     device=None,
@@ -437,12 +522,19 @@ def crop_face_track(
             to modulus - 1
         multiple: crop_size must be a multiple of this, the model's frame-size
             step (32 for LTX)
+        min_frames: Refuse the clip when its padded crop count is below this
+            (unset: no check)
+        max_frames: Refuse the clip when its padded crop count is above this
+            (unset: no check)
+        fps: Refuse the clip unless its frame rate is this, within
+            FPS_TOLERANCE (unset: no check)
         detector_repo: Hugging Face repo holding the YuNet weights
         detector_file: The .onnx file in that repo
         device: Where detection runs; CUDA only when OpenCV was built with it
     Returns:
         {"crops": AudioVideo of crop_size squares, padded to modulus * n + remainder
-         frames (8n+1 by default),
+         frames (8n+1 by default), carrying the clip's soundtrack padded with
+         silence to match (no audio for a silent clip),
          "track": the record of every frame's box, crop and strength}
     """
     problems = face_track_problems(
@@ -454,20 +546,46 @@ def crop_face_track(
         modulus=modulus,
         remainder=remainder,
         multiple=multiple,
+        min_frames=min_frames,
+        max_frames=max_frames,
     )
     if problems:
         raise ValueError("; ".join(message for _, message in problems))
+    check_arguments(
+        "crop_face_track",
+        **{
+            name: value
+            for name, value in (
+                ("min_frames", min_frames),
+                ("max_frames", max_frames),
+                ("fps", fps),
+            )
+            if value is not None
+        },
+    )
     crop_size = int(crop_size)
     modulus, remainder = int(modulus), int(remainder)
 
-    detector = _detector(detector_repo, detector_file, min_confidence, device)
-
     if isinstance(clip, str):
         clip = load_audio_video(clip)
     frames = frames_as_pil_list(clip)
     if not frames:
         raise ValueError("crop_face_track needs a clip with at least one frame")
-    fps = getattr(clip, "fps", None)
+    clip_fps = getattr(clip, "fps", None)
+
+    # The window and the rate are the clip's to meet before the detector loads
+    before, after = padding_to_grid(len(frames), modulus, remainder)
+    crop_frames = before + len(frames) + after
+    refusals = window_problems(
+        len(frames), crop_frames, f"{modulus}n+{remainder}", min_frames, max_frames
+    )
+    rate = rate_problem(clip_fps, fps)
+    if rate is not None:
+        refusals.append(rate)
+    if refusals:
+        raise ValueError("; ".join(refusals))
+
+    detector = _detector(detector_repo, detector_file, min_confidence, device)
     rgb = [np.asarray(frame.convert("RGB")) for frame in frames]
     height, width = rgb[0].shape[:2]
 
@@ -498,8 +616,10 @@ def crop_face_track(
         entry["crop"] = square
         crops.append(_cut(rgb[index], square, crop_size))
 
-    before, after = padding_to_grid(len(crops), modulus, remainder)
     crops = pad_frames(crops, before, after)
+    track_audio, sample_rate = crop_soundtrack(
+        clip, clip_fps, len(frames), before, after
+    )
 
     record = JsonRecord(
         {
@@ -507,7 +627,7 @@ def crop_face_track(
                 "width": width,
                 "height": height,
                 "frames": len(frames),
-                "fps": fps,
+                "fps": clip_fps,
             },
             "crop_size": crop_size,
             "padding": padding,
@@ -540,8 +660,35 @@ def crop_face_track(
         f"crop_face_track: face in {tracked} of {len(frames)} frames, "
         f"{len(resets)} reset(s), {len(crops)} crops of {crop_size}px "
         f"({before} before, {after} after for {modulus}n+{remainder})"
+        + (", with the clip's soundtrack" if track_audio is not None else "")
     )
-    return {"crops": AudioVideo(crops, None, None, fps=fps), "track": record}
+    return {
+        "crops": AudioVideo(crops, track_audio, sample_rate, fps=clip_fps),
+        "track": record,
+    }
+
+
+def crop_soundtrack(clip, clip_fps, frames, before, after):
+    """(audio, sample_rate) for the crops: the clip's track padded to them, or
+    (None, None) for a silent clip. A track without a frame rate or sample
+    rate to place it by is dropped, with a warning."""
+    audio = getattr(clip, "audio", None)
+    if audio is None:
+        return None, None
+    sample_rate = getattr(clip, "sample_rate", None)
+    if not sample_rate or not clip_fps:
+        emit_warning(
+            "crop_face_track: the clip's soundtrack is dropped from the crops - "
+            "the clip carries no "
+            + ("frame rate" if not clip_fps else "sample rate")
+            + " to line it up with the padded crops by",
+            kind="crop_audio_dropped",
+            command="crop_face_track",
+        )
+        return None, None
+    return padded_audio(
+        audio, sample_rate, clip_fps, frames, before, after
+    ), sample_rate
 
 
 def feather_mask(side, feather):
diff --git a/dw/tasks/video_handlers.py b/dw/tasks/video_handlers.py
index 293ef86d..e699e33c 100644
--- a/dw/tasks/video_handlers.py
+++ b/dw/tasks/video_handlers.py
@@ -333,6 +333,18 @@ def _handle_stabilize_video(task, arguments, previous_pipelines):
             "crop_size must be a multiple of this - the model's frame-size "
             "step (32 for LTX)."
         ),
+        "min_frames": (
+            "Refuse the clip when its padded crop count is below this - the "
+            "fewest frames the model the crops feed takes. No check when unset."
+        ),
+        "max_frames": (
+            "Refuse the clip when its padded crop count is above this - the "
+            "most frames the model the crops feed takes. No check when unset."
+        ),
+        "fps": (
+            "Refuse the clip unless its frame rate is this, within 0.01 - the "
+            "rate the model the crops feed generates at. No check when unset."
+        ),
         "detector_repo": "Hugging Face repo holding the YuNet face detector.",
         "detector_file": "The .onnx file in detector_repo.",
     },
@@ -345,8 +357,11 @@ def _handle_stabilize_video(task, arguments, previous_pipelines):
         "modulus": POSITIVE,
         "remainder": NON_NEGATIVE,
         "multiple": POSITIVE,
+        "min_frames": POSITIVE,
+        "max_frames": POSITIVE,
+        "fps": POSITIVE,
     },
-    whole_numbers=("modulus", "remainder", "multiple"),
+    whole_numbers=("modulus", "remainder", "multiple", "min_frames", "max_frames"),
     static_check=face_track_errors,
     media_arguments=("clip",),
 )
diff --git a/tests/test_face_track.py b/tests/test_face_track.py
index 8b376444..8ab14227 100644
--- a/tests/test_face_track.py
+++ b/tests/test_face_track.py
@@ -808,3 +808,212 @@ def test_paste_command_is_registered():
     from dw.tasks.task import _COMMAND_REGISTRY
 
     assert "paste_face_track" in _COMMAND_REGISTRY
+
+
+SR = 48000
+
+
+def tone(frames, fps=24, sample_rate=SR, channels=2):
+    """A (channels, samples) track of `frames` frames, never zero."""
+    samples = round(frames * sample_rate / fps)
+    t = np.arange(samples, dtype=np.float32)
+    return np.stack([0.5 + 0.1 * np.sin(t / (7 + c)) for c in range(channels)])
+
+
+def tiny_clip(frames, fps=24, audio=None, sample_rate=None):
+    """A clip of `frames` small blank frames - for refusals, which never
+    look at the pixels."""
+    still = Image.new("RGB", (8, 8))
+    return AudioVideo([still] * frames, audio, sample_rate, fps=fps)
+
+
+@pytest.fixture
+def no_detector(monkeypatch):
+    def fail(*a, **k):
+        pytest.fail("the detector loaded before the clip was refused")
+
+    monkeypatch.setattr(ft, "_detector", fail)
+
+
+class TestPaddedAudio:
+    def test_200_frames_on_17_5_is_209_frames_of_sound(self):
+        before, after = ft.padding_to_grid(200, 17, 5)
+        assert before + 200 + after == 209
+        out = ft.padded_audio(tone(200), SR, 24, 200, before, after)
+        assert out.shape == (2, 209 * SR // 24)
+
+    def test_the_head_is_pad_before_frames_of_silence(self):
+        before, after = ft.padding_to_grid(200, 17, 5)
+        source = tone(200)
+        out = ft.padded_audio(source, SR, 24, 200, before, after)
+        head = before * SR // 24
+        assert not out[:, :head].any()
+        assert np.array_equal(out[:, head : head + source.shape[1]], source)
+        assert not out[:, head + source.shape[1] :].any()
+
+    def test_a_fractional_rate_still_sums_to_the_padded_length(self):
+        fps = 24000 / 1001
+        out = ft.padded_audio(tone(10, fps=fps), SR, fps, 10, 3, 4)
+        assert out.shape[1] == round(17 * SR / fps)
+
+    def test_a_long_track_is_cut_and_a_short_one_padded_to_the_clip(self):
+        long = ft.padded_audio(tone(30), SR, 24, 20, 2, 3)
+        short = ft.padded_audio(tone(10), SR, 24, 20, 2, 3)
+        assert long.shape == short.shape == (2, 25 * SR // 24)
+        assert not long[:, 22 * SR // 24 :].any()
+        assert not short[:, 12 * SR // 24 :].any()
+
+    def test_mono_samples_first_is_read_as_one_channel(self):
+        out = ft.padded_audio(tone(4, channels=1)[0], SR, 24, 4, 1, 0)
+        assert out.shape == (1, 5 * SR // 24)
+
+
+class TestCropSoundtrack:
+    def test_the_crops_carry_the_padded_track(self, stub_detector):
+        frames = [make_frame((100, 80, 16))] * 10
+        clip = AudioVideo([Image.fromarray(a) for a in frames], tone(10), SR, fps=24)
+        result = ft.crop_face_track(clip, crop_size=64)
+        crops, track = result["crops"], result["track"]
+        assert len(crops.frames) == track["crop_frames"] == 17
+        assert crops.sample_rate == SR
+        assert crops.fps == 24
+        assert crops.audio.shape[1] == 17 * SR // 24
+        head = track["pad_before"] * SR // 24
+        assert not crops.audio[:, :head].any()
+        assert crops.audio[:, head].all()
+
+    def test_a_silent_clip_gives_silent_crops(self, stub_detector, warnings_seen):
+        result = ft.crop_face_track(clip_of([make_frame((100, 80, 16))] * 5))
+        assert result["crops"].audio is None
+        assert result["crops"].sample_rate is None
+        assert warnings_seen == []
+
+    def test_a_silent_clip_on_the_h3_grid_gives_silent_crops(self, stub_detector):
+        result = ft.crop_face_track(
+            clip_of([make_frame((100, 80, 16))] * 5), modulus=17, remainder=5
+        )
+        assert len(result["crops"].frames) == 5
+        assert result["crops"].audio is None
+
+    def test_a_track_with_no_rate_to_place_it_is_dropped_with_a_warning(
+        self, stub_detector, warnings_seen
+    ):
+        frames = [Image.fromarray(make_frame((100, 80, 16)))] * 3
+        clip = AudioVideo(frames, tone(3), SR, fps=None)
+        result = ft.crop_face_track(clip, crop_size=64)
+        assert result["crops"].audio is None
+        assert [d["kind"] for _, d in warnings_seen] == ["crop_audio_dropped"]
+
+
+class TestWindowAndRate:
+    def test_too_many_crops_name_the_bound_and_the_count(self, no_detector):
+        with pytest.raises(ValueError) as refused:
+            ft.crop_face_track(tiny_clip(200), modulus=17, remainder=5, max_frames=124)
+        message = str(refused.value)
+        assert "200 frames" in message and "209 crops" in message
+        assert "max_frames 124" in message
+
+    def test_padding_past_the_top_is_refused(self, no_detector):
+        with pytest.raises(ValueError, match="346 frames pad to 362 crops"):
+            ft.crop_face_track(tiny_clip(346), modulus=17, remainder=5, max_frames=345)
+
+    def test_padding_short_of_the_bottom_is_refused(self, no_detector):
+        with pytest.raises(ValueError, match="96 frames pad to 107 crops.*min_frames"):
+            ft.crop_face_track(tiny_clip(96), modulus=17, remainder=5, min_frames=124)
+
+    @pytest.mark.parametrize("frames", [124, 345])
+    def test_the_window_bounds_are_accepted(self, stub_detector, frames):
+        result = ft.crop_face_track(
+            tiny_clip(frames),
+            crop_size=64,
+            modulus=17,
+            remainder=5,
+            min_frames=124,
+            max_frames=345,
+        )
+        assert len(result["crops"].frames) == frames
+
+    @pytest.mark.parametrize("clip_fps,fps", [(30, 24), (24000 / 1001, 24)])
+    def test_a_clip_at_another_rate_is_refused(self, no_detector, clip_fps, fps):
+        with pytest.raises(ValueError) as refused:
+            ft.crop_face_track(tiny_clip(5, fps=clip_fps), fps=fps)
+        message = str(refused.value)
+        assert f"{ft._rate_text(clip_fps)} fps" in message
+        assert "needs a clip at 24 fps" in message
+
+    def test_a_rate_within_the_tolerance_is_accepted(self, stub_detector):
+        result = ft.crop_face_track(
+            tiny_clip(5, fps=24000 / 1001), crop_size=64, fps=23.98
+        )
+        assert len(result["crops"].frames) == 9
+
+    def test_no_fps_means_no_rate_check(self, stub_detector):
+        result = ft.crop_face_track(tiny_clip(5, fps=30), crop_size=64)
+        assert result["crops"].fps == 30
+
+    def test_a_clip_with_no_rate_is_refused_when_one_is_asked(self, no_detector):
+        with pytest.raises(ValueError, match="carries no frame rate"):
+            ft.crop_face_track(tiny_clip(5, fps=None), fps=24)
+
+    @pytest.mark.parametrize(
+        "arguments,name",
+        [
+            ({"min_frames": 0}, "min_frames"),
+            ({"max_frames": -5}, "max_frames"),
+            ({"fps": 0}, "fps"),
+            ({"min_frames": 200, "max_frames": 100}, "max_frames"),
+        ],
+    )
+    def test_bad_window_or_rate_is_refused_at_run_time(
+        self, no_detector, arguments, name
+    ):
+        with pytest.raises(ValueError, match=name):
+            ft.crop_face_track(tiny_clip(5), **arguments)
+
+    @pytest.mark.parametrize(
+        "arguments,name",
+        [
+            ({"min_frames": 0}, "min_frames"),
+            ({"min_frames": -1}, "min_frames"),
+            ({"max_frames": 0}, "max_frames"),
+            ({"max_frames": 12.5}, "max_frames"),
+            ({"fps": 0}, "fps"),
+            ({"fps": -24}, "fps"),
+            ({"min_frames": 200, "max_frames": 100}, "max_frames"),
+        ],
+    )
+    def test_bad_window_or_rate_is_an_error_at_validate(self, arguments, name):
+        errors = task_argument_errors(workflow({"clip": "v.mp4", **arguments}))
+        path = f"steps[0].task.arguments.{name}"
+        assert [e for e in errors if e["path"] == path], errors
+
+    def test_a_good_window_and_rate_validate_clean(self):
+        args = {"clip": "v.mp4", "min_frames": 124, "max_frames": 345, "fps": 24}
+        assert task_argument_errors(workflow(args)) == []
+        deferred = {"clip": "v.mp4", "min_frames": "variable:a", "max_frames": 100}
+        assert task_argument_errors(workflow(deferred)) == []
+
+    def test_the_task_describes_the_window_and_rate(self):
+        from dw.introspection import describe_task
+
+        found = {p["name"]: p for p in describe_task("crop_face_track")["parameters"]}
+        for name in ("min_frames", "max_frames", "fps"):
+            assert found[name]["default"] is None
+            assert found[name]["description"]
+
+
+def test_the_ltx_template_crop_step_passes_no_window_or_rate():
+    path = os.path.join(
+        os.path.dirname(__file__),
+        "..",
+        "workflows",
+        "templates",
+        "ltx2",
+        "face-repair.json",
+    )
+    with open(path) as f:
+        steps = json.load(f)["steps"]
+    crop = next(
+        s for s in steps if s.get("task", {}).get("command") == "crop_face_track"
+    )
+    assert not {"min_frames", "max_frames", "fps"} & set(crop["task"]["arguments"])

From 76d10b4470d61bb66cbbeca9f7031375eb4231d1 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 14:57:56 -0500
Subject: [PATCH 049/125] docs(proposals): #1093 - design record for cutaway
 and lead-in joins

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../script-to-video-joins-complete.md         | 141 ++++++++++++++++++
 docs/proposals/todo.md                        |   8 +
 2 files changed, 149 insertions(+)
 create mode 100644 docs/proposals/complete/script-to-video-joins-complete.md

diff --git a/docs/proposals/complete/script-to-video-joins-complete.md b/docs/proposals/complete/script-to-video-joins-complete.md
new file mode 100644
index 00000000..7fdd486a
--- /dev/null
+++ b/docs/proposals/complete/script-to-video-joins-complete.md
@@ -0,0 +1,141 @@
+# Cutaway and lead-in joins in `script-to-video` (#1093)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v2 approved under Don's delegation on 2026-10-31 (Q1
+composition-only, Q2 the default re-entry plus one line on the A-tail video
+reference, Q3 the tester runs both paid cases). One stage, #1100, verified
+2026-10-31.
+
+Source of the idea: r34vtraining/Longshot_Studio (a ComfyUI studio for long
+MiniMax H3 films, assessed 2026-10-31). The repo has no licence, so only the
+concept was taken. Its join chip has Cut, Context, Bridge, Continuous,
+Lead In and Cutaway.
+
+## The question
+
+How can a shot list say "skip over this one" (a B-roll insert that the shot
+after it doesn't continue from) and "land on the next shot" (a shot whose
+last frame is pinned to its successor's first)? Today an insert in the
+middle of a dialogue run breaks continuity. The shot after it either
+continues from the insert or starts cold.
+
+## What the design sweep found
+
+- **The chain block can't say it.** `dw/workflow_schema.json`'s chain
+  `$def` has one uniform `continuity` and a string `prompts` array.
+  `run_chain` (`dw/chain.py`) overwrites one `carry` per segment and renders
+  strictly in order. A cutaway needs a non-adjacent carry. A lead-in needs
+  a forward dependency.
+- **`for_each` can't say it either.** There is no relative indexing, and
+  groups expand whole, so no per-entry frame grab can sit between entries.
+  A literal `from_previous_result: "shot@<key>"` cross-entry reference
+  slips through today but no test pins it. It was filed as #1101
+  (`owner:don`) rather than relied on.
+- **Separate runs can say it.** `get_first_frame` / `get_last_frame` read
+  `output:` files. The renderers both joins need already exist:
+  `templates/minimax/image-to-video`, `first-and-last-frame`,
+  `last-frame-only` and `dialogue-short`.
+- **Seam bookkeeping needs no change.** For a cutaway, both seams in the
+  cut (A→B, B→C) are real picture cuts, so `concat_videos`' `hard_cut` is
+  honest. The A→C continuity is checked by comparing frames, not as a seam.
+  For a lead-in, the B→C join is pinned by construction.
+- **Corrections to the issue.** "Context (`h3_context_ir`)" is a prompt
+  convention plus `last_segment`/`guide` continuity, not an engine join.
+  "Bridge" exists only as a Music3 lyric tag, and the two-keyframe pin is
+  `first-and-last-frame`. The `shots-batch` / `storyboard` entries render
+  independently, so the join belongs in the skill's shot list, not in a
+  template field.
+
+## Verdict
+
+**Build smaller**: composition layer only (skill text). No engine, schema,
+template or task change. The evidence was thin: no field report asked for
+either join, and Don's film workspaces already build episodes as separate
+shots joined by `concat_videos`, which is where both joins work as separate
+runs.
+
+## What was built
+
+### Stage A, #1100: the joins in the `script-to-video` skill
+
+- **`plugins/dw/skills/script-to-video/references/joins.md`** (new):
+  - **Cutaway A, B, C.** C's source is A. `get_last_frame` of `output:<A>`
+    goes into `image-to-video` for a silent C, or `dialogue-short` with the
+    same cast references for a talking C. One line names A's tail as a
+    video reference (`chain-video-continuity`'s pattern) for a C that picks
+    up motion mid-action, with its slot and VRAM cost. Concat is in story
+    order. The re-entry check compares A's last frame with C's first.
+  - **Lead-in B → C.** Render the target first. `get_first_frame` of
+    `output:<C>` becomes `last_image` in `first-and-last-frame`, or
+    `last-frame-only` is used when B has no fixed opening. Keep lead-ins
+    short.
+  - **Render order and re-rolls.** Order follows sources, not story.
+    Re-rolling C invalidates B, and both are quoted. Re-rolling A
+    invalidates any C or cutaway taken off it. A forced re-render counts
+    against the dependent shot's three-attempt budget.
+  - One line says an LTX-2.5 re-entry works the same way through
+    `templates/ltx2/image-to-video`.
+  - **Taking a frame off a finished shot** (not in the plan): a one-step
+    `get_last_frame` / `get_first_frame` workflow reading
+    `video: "output:<shot file>"`. Its still is passed on as
+    `{"location": "output:<frame file>"}` or kept as an `asset:`. The plan
+    assumed this step without writing it down.
+- **SKILL.md step 2.** A shot's `opening_state` is now the `ending_state`
+  of its **source**. A per-shot `join` field (`continue` (the default),
+  `cut`, `cutaway`, `lead_in`) links `references/joins.md`. Step 5 gets one
+  line on source order and re-roll quoting. SKILL.md is 10,115 bytes, under
+  the 12 KiB cap.
+- **Tests** (`tests/test_plugin_skills.py`): `get_first_frame` and
+  `get_last_frame` are in `SKILL_TASKS["script-to-video"]`. The task check
+  also accepts `list_tasks()["video_processors"]`, which is the only list
+  that holds the frame commands. `TestScriptToVideoJoins` pins the four
+  joins, the source rule, "Render the target first", "Re-rolling C
+  invalidates B", and that the frame-grab step validates.
+- **No README change and no version bump.** `plugins/dw/README.md` lists
+  skills, not their references. The plugin's version is the engine's, set
+  by the release script.
+
+### Verification (lem, H3 draft tier)
+
+- **Cutaway (M-F261).** A café two-shot, then a rainy-street B-roll cut,
+  then C from A's last frame. A's last frame and C's first are the same
+  picture, and C is visibly not B's scene. The concat has two `hard_cut`
+  seams. `assess_output` raised only audio level steps between unrelated
+  shots, which `match_levels` handles.
+- **Lead-in (M-F262).** C was rendered before B. B's last frame equals C's
+  first, and concat frames 121–126 show no jump. Mid-B the subject drifts
+  and turns back, which is the long-FL2VA drift the plan's risks name. It
+  happens even at the 124-frame floor, and the shot stays usable.
+- **Refusal (M-F263).** A frame grab or a `first-and-last-frame` request
+  against a nonexistent `output:` is refused at validate and at
+  `run_workflow`, naming the reference, and nothing is queued. A re-roll
+  quote of C lists C and B with a sum. `first-and-last-frame` at 960×544 and
+  `last-frame-only` are both unpriced (`basis: unknown`). The tester filed
+  the missing prices as a server issue and the case's estimate clause as a
+  suite amendment on harnest.
+
+## Cost and bounces
+
+| Stage | Bounces | Cost |
+|---|---|---|
+| A, #1100 | 0 | not recorded on the stage |
+
+## What was deferred, and what would reopen it
+
+- **Engine chain joins** (a per-segment `joins` array in the chain `$def`,
+  carries kept by index, dependency render order in `run_chain`, a
+  `last_image` continuity class in lockstep with `CHAIN_CONTINUITY_MODES`,
+  and a cut-vs-continuation seam attribute through `shots.py`,
+  `concat_videos` and `analyze_seams`). Estimated at 4-5 stages, $15-25.
+  **Reopen when** a field report shows a chained take (not a shot list)
+  broken by an insert, or a session builds the triple by hand across jobs
+  more than once and the multi-job quote and re-roll become the complaint.
+  Don't start it while #1030 (latent carry) and #1033 (colour-match chained
+  segments) are parked undecided: they touch the same loop.
+- **A non-adjacent continuity probe.** The A→C match is judged by eye, and
+  the engine route would add one.
+- **The `shot@<key>` cross-entry reference**: #1101, Don's call to pin or
+  refuse it.
+- **Related improvements:** #1032 (sharpest-of-N last frame) would improve a
+  cutaway's re-entry frame. #1067 (colour-match a region to its source)
+  could match C's colour to A's tail.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index b1c6a165..b00e214f 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -401,6 +401,14 @@ remaining deferred fix is recorded in
   H3 refine schedule; the recipe's exact points measured the same as the
   shift-2 grid. Don's lower-strength arms (0.6, 0.7) are still owed.
   Record: `complete/h3-open-regenerate-2k-complete.md`.
+- **Cutaway and lead-in joins in `script-to-video`** (#1093, stage #1100),
+  shipped 2026-10-31 as skill text only. A shot list's `join` field
+  (`continue`, `cut`, `cutaway`, `lead_in`) and
+  `script-to-video/references/joins.md`: a cutaway's successor re-enters
+  from the shot before it, and a lead-in is rendered after its target and
+  pinned to it with `first-and-last-frame`. Record, including the deferred
+  engine chain joins and their reopen trigger:
+  `complete/script-to-video-joins-complete.md`.
 
 ## Declined
 

From a99b08868e0d05c57c3c10b1a3ba36b4b1e9a1a7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 15:37:06 -0500
Subject: [PATCH 050/125] feat(templates): #1079 - alpha-matte says a hard cut
 leaks; matte one shot at a time

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/ltx-2.5/SKILL.md        |  2 ++
 tests/test_ltx2_ic_loras.py               | 21 +++++++++++++++++++++
 workflows/templates/ltx2/alpha-matte.json |  2 +-
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 2e6ac96d..b29f4873 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -51,6 +51,8 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   rate (`frame_rate` overrides the rate, never the frame count), for the
   user's editor to composite. No prompt: the model picks the foreground and
   a prompt doesn't steer it. `num_frames` caps at 145 (RGB leaks past it).
+  A hard cut leaks source texture into the frames after it: matte one shot
+  at a time.
 - **Repairing the user's footage**: `templates/ltx2/restore-deblur` for
   spatial defocus, `templates/ltx2/restore-decompression` for low-bitrate
   artefacts. Each inverts one defect and no other - neither upscales or
diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index c9fdd76c..ad9ebb7e 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -302,3 +302,24 @@ def test_it_keeps_deblurs_pipeline_identity(self):
         assert pipeline_identity(conditioned_step("alpha-matte")) == (
             pipeline_identity(conditioned_step("restore-deblur"))
         )
+
+
+class TestTheAlphaMatteSaysAShotCutLeaks:
+    """#1079 (plan v8, Q9 (a)): at the 145-frame cap the matte leaked source
+    texture on the frame just after a hard cut, so the description and the
+    skill row tell the caller to matte one shot at a time."""
+
+    def test_the_description_says_it(self):
+        with open(os.path.join(TEMPLATES, "alpha-matte.json")) as f:
+            description = json.load(f)["description"]
+
+        assert "hard cut" in description
+        assert "one shot at a time" in description
+
+    def test_the_skill_row_says_it(self):
+        path = os.path.join(REPO_ROOT, "plugins", "dw", "skills", "ltx-2.5", "SKILL.md")
+        with open(path) as f:
+            row = f.read().split("templates/ltx2/alpha-matte")[1].split("\n- ")[0]
+
+        assert "hard cut" in row
+        assert "one shot" in row
diff --git a/workflows/templates/ltx2/alpha-matte.json b/workflows/templates/ltx2/alpha-matte.json
index 6eb6d36a..c0684249 100644
--- a/workflows/templates/ltx2/alpha-matte.json
+++ b/workflows/templates/ltx2/alpha-matte.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2AlphaMatte",
-    "description": "Pulls a soft per-frame alpha matte from the user's clip with the Alpha-Gen in-context LoRA - no green screen, mask or prompt; hair, smoke, motion blur and glass come back as partial values, not a hard cutout. The output is a grey-scale h264 MP4 at the source's own size and frame-aligned with it: white is foreground, black background. dw does not composite it: use it as the source's alpha (a luma matte) in an editor. The model picks the foreground itself and the prompt does not steer it, so the prompt is fixed empty and there is no prompt variable. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing (the black padding reads as background) and a last step crops the padding back off, so any aspect ratio comes back at its own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. 'num_frames' is 8n+1 from 9 to 145 and refused above: past 145 the card says RGB content leaks into the matte. The matte has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Defaults 960x544 at 121 frames. The card's ceiling is 1920x1088, which is not a 24 GB size. The LoRA strength is the card's fixed 1.0. A 0.9 preview weight, run here under uint4 SDNQ.",
+    "description": "Pulls a soft per-frame alpha matte from the user's clip with the Alpha-Gen in-context LoRA - no green screen, mask or prompt; hair, smoke, motion blur and glass come back as partial values, not a hard cutout. The output is a grey-scale h264 MP4 at the source's own size and frame-aligned with it: white is foreground, black background. dw does not composite it: use it as the source's alpha (a luma matte) in an editor. The model picks the foreground itself and the prompt does not steer it, so the prompt is fixed empty and there is no prompt variable. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing (the black padding reads as background) and a last step crops the padding back off, so any aspect ratio comes back at its own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. 'num_frames' is 8n+1 from 9 to 145 and refused above: past 145 the card says RGB content leaks into the matte. A hard cut inside the clip can leak source texture into the matte on the frames just after it, so matte a multi-shot clip one shot at a time. The matte has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Defaults 960x544 at 121 frames. The card's ceiling is 1920x1088, which is not a 24 GB size. The LoRA strength is the card's fixed 1.0. A 0.9 preview weight, run here under uint4 SDNQ.",
     "summary": "Soft per-frame alpha matte of your clip: grey MP4, white = foreground, at the source's size. No prompt.",
     "traits": [
         "needs-input-media"

From 416c4068c90bb3cb146dce9ad159292d6c116d71 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:09:19 -0500
Subject: [PATCH 051/125] feat(templates): #1080 - restore-colorize template
 and dual-panel prompt

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 prompts/ltx2/colorize_dual_panel.json         |  10 +
 .../templates/ltx2/restore-colorize.json      | 217 ++++++++++++++++++
 2 files changed, 227 insertions(+)
 create mode 100644 prompts/ltx2/colorize_dual_panel.json
 create mode 100644 workflows/templates/ltx2/restore-colorize.json

diff --git a/prompts/ltx2/colorize_dual_panel.json b/prompts/ltx2/colorize_dual_panel.json
new file mode 100644
index 00000000..7ca710c3
--- /dev/null
+++ b/prompts/ltx2/colorize_dual_panel.json
@@ -0,0 +1,10 @@
+{
+  "text": "Reference shows a woman in a long coat walking a small dog along a cobbled street lined with shop fronts and parked cars under overcast daylight, in black and white with no colour information. Edited shows the same scene with natural colors restored. COLORIZE a woman in a camel coat and a red scarf walking a small brown dog along a grey cobbled street lined with shop fronts with green and cream awnings and parked cars under overcast daylight. Subject identity, framing, motion, and background geometry are identical to the reference; only color information differs between reference and edited.",
+  "description": "The Colorization IC-LoRA's trained dual-panel form - replace both descriptions of the scene with your own clip's, keeping the structure, and name the colours you expect where they matter",
+  "intended_model": "ltx-2.5",
+  "tags": [
+    "ic-lora",
+    "restoration",
+    "v2v"
+  ]
+}
diff --git a/workflows/templates/ltx2/restore-colorize.json b/workflows/templates/ltx2/restore-colorize.json
new file mode 100644
index 00000000..f25a8370
--- /dev/null
+++ b/workflows/templates/ltx2/restore-colorize.json
@@ -0,0 +1,217 @@
+{
+    "id": "LTX2Colorize",
+    "description": "Restores natural colour to black-and-white or washed-out source footage with the Colorization in-context LoRA, the monochrome clip attached as a reference for the whole denoise - so the subject, the framing and the motion are the ones that were shot and only the colour changes. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so any aspect ratio comes back at the source's own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket weakens the effect. 'lora_scale' is 1.0 - lower it toward 0.8 if the colour oversaturates or bleeds across edges. The prompt follows the trained dual-panel convention ('Reference shows ... COLORIZE ... only color information differs'): replace both descriptions of the scene with your own clip's, naming the colours you expect where they matter. A 0.9 preview weight, run here under uint4 SDNQ.",
+    "summary": "Colourises black-and-white or washed-out footage, keeping the source's size, frame rate and motion.",
+    "traits": [
+        "needs-input-media"
+    ],
+    "cost_drivers": [
+        "num_frames",
+        "width",
+        "height"
+    ],
+    "variables": {
+        "transformer_weights_dtype": "{uint4}",
+        "text_encoder_weights_dtype": "{int8}",
+        "source_video": "asset:clip.mp4",
+        "prompt": "prompt:ltx2/colorize_dual_panel",
+        "negative_prompt": "constant:diffusers.pipelines.ltx2.utils.DEFAULT_NEGATIVE_PROMPT",
+        "width": 960,
+        "height": 544,
+        "num_frames": 121,
+        "frame_rate": "source",
+        "lora_scale": 1.0,
+        "seed": 42
+    },
+    "variable_constraints": {
+        "width": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "LTX-2.5's pipelines refuse a width not divisible by 32 outright (ValueError, not a silent floor), so it is checked here before the pipeline load rather than after it"
+        },
+        "height": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "LTX-2.5's pipelines refuse a height not divisible by 32 outright (ValueError, not a silent floor), so it is checked here before the pipeline load rather than after it"
+        },
+        "num_frames": {
+            "modulus": 8,
+            "remainder": 1,
+            "min_frames": 9,
+            "reason": "LTX-2.5's video VAE encodes 8 * n + 1 frames, so an off-grid count is not refused by the pipeline but floored to the grid below - a shorter clip than the one asked for. Refused here instead: no 'snap', because rounding a length the other way from the pipeline's own would be a second silent change"
+        }
+    },
+    "seed": "variable:seed",
+    "steps": [
+        {
+            "name": "fit",
+            "task": {
+                "command": "fit_to_model",
+                "arguments": {
+                    "video": "variable:source_video",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_frames": "variable:num_frames",
+                    "mode": "letterbox",
+                    "downscale": 1
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "save": false
+            }
+        },
+        {
+            "name": "colorized",
+            "pipeline": {
+                "configuration": {
+                    "component_type": "LTX2InContextPipeline",
+                    "pre_load_modules": [
+                        "sdnq"
+                    ],
+                    "components": {
+                        "transformer": {
+                            "device": "cuda"
+                        },
+                        "text_encoder": {
+                            "group_offload": {
+                                "offload_type": "leaf_level",
+                                "use_stream": true
+                            }
+                        },
+                        "connectors": {
+                            "group_offload": {
+                                "offload_type": "leaf_level",
+                                "use_stream": true
+                            }
+                        },
+                        "vae": {
+                            "device": "cuda"
+                        },
+                        "audio_vae": {
+                            "device": "cuda"
+                        },
+                        "vocoder": {
+                            "device": "cuda"
+                        }
+                    },
+                    "vae": {
+                        "enable_tiling": true
+                    }
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "Lightricks/LTX-2.5-Diffusers",
+                    "torch_dtype": "torch.bfloat16"
+                },
+                "transformer": {
+                    "configuration": {
+                        "component_type": "LTX2VideoTransformer3DModel",
+                        "preserve_device_placement": true
+                    },
+                    "quantization_config": {
+                        "configuration": {
+                            "config_type": "sdnq.SDNQConfig"
+                        },
+                        "arguments": {
+                            "weights_dtype": "variable:transformer_weights_dtype",
+                            "quantization_device": "cuda",
+                            "return_device": "cuda",
+                            "use_quantized_matmul": true,
+                            "dequantize_fp32": false
+                        }
+                    },
+                    "from_pretrained_arguments": {
+                        "model_name": "Lightricks/LTX-2.5-Diffusers",
+                        "subfolder": "transformer",
+                        "torch_dtype": "torch.bfloat16"
+                    }
+                },
+                "text_encoder": {
+                    "configuration": {
+                        "component_type": "transformers.Gemma4UnifiedForConditionalGeneration",
+                        "preserve_device_placement": true
+                    },
+                    "quantization_config": {
+                        "configuration": {
+                            "config_type": "sdnq.SDNQConfig"
+                        },
+                        "arguments": {
+                            "weights_dtype": "variable:text_encoder_weights_dtype",
+                            "quantization_device": "cuda",
+                            "return_device": "cpu",
+                            "dequantize_fp32": false,
+                            "modules_to_not_convert": [
+                                "embed_vision",
+                                "embed_audio",
+                                "lm_head"
+                            ]
+                        }
+                    },
+                    "from_pretrained_arguments": {
+                        "model_name": "Lightricks/LTX-2.5-Diffusers",
+                        "subfolder": "text_encoder",
+                        "torch_dtype": "torch.bfloat16"
+                    }
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "negative_prompt": "variable:negative_prompt",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_frames": "variable:num_frames",
+                    "frame_rate": 24.0,
+                    "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
+                    "guidance_scale": 1.0,
+                    "audio_guidance_scale": 1.0,
+                    "stg_scale": 0.0,
+                    "audio_stg_scale": 0.0,
+                    "modality_scale": 1.0,
+                    "audio_modality_scale": 1.0,
+                    "output_type": "{np}",
+                    "reference_conditions": [
+                        {
+                            "reference_type": "diffusers.pipelines.ltx2.pipeline_ltx2_ic_lora.LTX2ReferenceCondition",
+                            "from_arguments": {
+                                "frames": {
+                                    "media_type": "video",
+                                    "location": "previous_result:fit.video"
+                                },
+                                "strength": 1.0
+                            }
+                        }
+                    ],
+                    "reference_downscale_factor": 1,
+                    "conditioning_attention_strength": 1.0
+                },
+                "loras": [
+                    {
+                        "model_name": "Lightricks/LTX-2.5-22b-IC-LoRA-Colorization",
+                        "weight_name": "ltx-2.5-22b-ic-lora-colorization-0.9.safetensors",
+                        "adapter_name": "ic_lora",
+                        "scale": "variable:lora_scale"
+                    }
+                ]
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24.0,
+                "save": false
+            }
+        },
+        {
+            "name": "final",
+            "task": {
+                "command": "restore_to_source",
+                "arguments": {
+                    "video": "previous_result:colorized",
+                    "fit": "previous_result:fit.fit",
+                    "fps": "variable:frame_rate"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "subfolder": "final"
+            }
+        }
+    ]
+}

From 60aef905a152596f4e71e366b7d16ebb24ecde2a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:13:15 -0500
Subject: [PATCH 052/125] feat(templates): #1080 - restore-colorize route, docs
 and tests

Skill route row and description, family README row, ARCHITECTURE count
(five conditioning templates), CARDS / prompt-convention / step-cache rows,
the source-rate real-path test parametrized over colorize, and the
compact-listing budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md               |  2 +-
 plugins/dw/skills/ltx-2.5/SKILL.md |  6 ++--
 tests/test_catalog_structure.py    |  5 ++-
 tests/test_fit_templates.py        | 38 ++++++++++++----------
 tests/test_ltx2_ic_loras.py        | 51 ++++++++++++++++++++++++++++--
 tests/test_ltx_prompt_library.py   |  5 +++
 tests/test_step_cache.py           |  3 ++
 workflows/templates/ltx2/README.md |  3 +-
 8 files changed, 90 insertions(+), 23 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 430df69c..4ea794ab 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -114,7 +114,7 @@ one to open.
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
 | H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` and the explicit `refine_sigmas` schedule among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`, and `explicit_sigmas`, a step's `refine_sigmas` list run verbatim in place of the shift grid) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_refine.py::TestSigmaListOneOwner::test_the_runtime_message_is_the_owners`, `tests/test_h3_refine.py::TestSigmaListSchedule::test_the_block_runs_the_list_unshifted`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
-| IC-LoRA reference scale | `workflows/templates/ltx2/` | The four conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
+| IC-LoRA reference scale | `workflows/templates/ltx2/` | The five conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
 
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index b29f4873..8fc5c13f 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: ltx-2.5
-description: Use when a dw MCP server is connected and the user wants LTX-2.5 video - a short clip with its own soundtrack, a clip from one picture or between two, a sharper full-size render, a 2x upscale of its own or the user's clip, a subject held across a clip from a reference sheet, a blurry or compressed clip restored, an alpha matte pulled from a clip, or a clip extended or chained longer. Picks the template, states schedule and size rules, quotes cost, and carries the trained caption spec the prompt must follow.
+description: Use when a dw MCP server is connected and the user wants LTX-2.5 video - a short clip with its own soundtrack, a clip from one picture or between two, a sharper full-size render, a 2x upscale of its own or the user's clip, a subject held across a clip from a reference sheet, a blurry or compressed clip restored, a black-and-white clip colourised, an alpha matte pulled from a clip, or a clip extended or chained longer. Picks the template, states schedule and size rules, quotes cost, and carries the trained caption spec the prompt must follow.
 ---
 
 # LTX-2.5 on a dw server
@@ -55,7 +55,9 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   at a time.
 - **Repairing the user's footage**: `templates/ltx2/restore-deblur` for
   spatial defocus, `templates/ltx2/restore-decompression` for low-bitrate
-  artefacts. Each inverts one defect and no other - neither upscales or
+  artefacts, `templates/ltx2/restore-colorize` for black-and-white or
+  washed-out footage (keeps the source's size and rate; prompt names the
+  colours). Each inverts one defect and no other - neither upscales or
   removes motion blur or grain - so name the defect and let the user
   correct you. To upscale or sharpen: `templates/ltx2/upscale-clip`
   (IC-LoRA re-render), `width`/`height` the render size, or `refine-clip`
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 0972eb2c..4cc0ed77 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -508,7 +508,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Then to 12_050 for the `minimax/regional-edit` template (#1062, stage #1078,
 # 2026-10-31), measured at 11_983: one new entry, the catalog's only regional
 # edit of a take, with its cost block.
-COMPACT_BUDGET = 12_050
+# Then to 12_250 for the `restore-colorize` template (#1064, stage #1080,
+# 2026-10-31), measured at 12_156 before its cost block: one new entry, the
+# catalog's only colourise route; the cost block it still owes fits the rest.
+COMPACT_BUDGET = 12_250
 FILTERED_BUDGET = 1_500
 
 
diff --git a/tests/test_fit_templates.py b/tests/test_fit_templates.py
index 9a29ee0b..971b3705 100644
--- a/tests/test_fit_templates.py
+++ b/tests/test_fit_templates.py
@@ -148,22 +148,26 @@ def eight_fps_clip(tmp_path, monkeypatch):
     return library
 
 
-class TestTheAlphaMatteKeepsTheSourcesRate:
-    """#1079: the model runs at its 24 fps, but the matte is written at the
-    source's own rate unless 'frame_rate' says otherwise. The real path:
-    the template expanded against an 8 fps asset, `fit` through the task
-    dispatch, the matte step's 24 fps output standing in for the pipeline,
-    and `final` run and saved through its own result definition."""
+@pytest.mark.parametrize(
+    "template,model_step",
+    [("alpha-matte", "matte"), ("restore-colorize", "colorized")],
+)
+class TestTheModelPassKeepsTheSourcesRate:
+    """#1079, #1080: the model runs at its 24 fps, but the output is written
+    at the source's own rate unless 'frame_rate' says otherwise. The real
+    path: the template expanded against an 8 fps asset, `fit` through the
+    task dispatch, the model step's 24 fps output standing in for the
+    pipeline, and `final` run and saved through its own result definition."""
 
     # A small working size keeps the stand-in matte cheap
     SMALL = {"width": 256, "height": 192, "num_frames": 25}
 
-    def written(self, tmp_path, **arguments):
+    def written(self, template, model_step, tmp_path, **arguments):
         from dw.media import video_shape
         from dw.media_types import AudioVideo
 
         workflow = workflow_from_file(
-            os.path.join(TEMPLATES, "alpha-matte.json"), str(tmp_path / "out")
+            os.path.join(TEMPLATES, f"{template}.json"), str(tmp_path / "out")
         )
         steps = workflow.expanded_definition(arguments=dict(self.SMALL, **arguments))
         steps = steps["steps"]
@@ -171,25 +175,27 @@ def written(self, tmp_path, **arguments):
         steps = {step["name"]: step for step in steps}
         _, fit = run_fit(steps)
 
-        matte = Result(steps["matte"]["result"])
-        matte.add_result(
+        model = Result(steps[model_step]["result"])
+        model.add_result(
             AudioVideo(numpy.zeros((25, 192, 256, 3), numpy.float32), None, None, 24)
         )
         final = steps["final"]
         (task_arguments,) = get_iterations(
-            final["task"]["arguments"], {"fit": fit, "matte": matte}
+            final["task"]["arguments"], {"fit": fit, model_step: model}
         )
         output = Task(final["task"], "cpu").run(task_arguments)
         result = Result(final["result"])
         result.add_result(output)
         saved = tmp_path / "saved"
         saved.mkdir()
-        result.save(str(saved), "alpha-final.0")
+        result.save(str(saved), f"{template}-final.0")
         (name,) = [n for n in os.listdir(saved) if n.endswith(".mp4")]
         return video_shape(str(saved / name))
 
-    def test_the_default_writes_the_sources_rate(self, eight_fps_clip, tmp_path):
-        shape = self.written(tmp_path)
+    def test_the_default_writes_the_sources_rate(
+        self, template, model_step, eight_fps_clip, tmp_path
+    ):
+        shape = self.written(template, model_step, tmp_path)
 
         assert shape["fps"] == pytest.approx(8.0)
         assert (shape["width"], shape["height"], shape["frame_count"]) == (
@@ -199,9 +205,9 @@ def test_the_default_writes_the_sources_rate(self, eight_fps_clip, tmp_path):
         )
 
     def test_frame_rate_overrides_the_rate_not_the_frames(
-        self, eight_fps_clip, tmp_path
+        self, template, model_step, eight_fps_clip, tmp_path
     ):
-        shape = self.written(tmp_path, frame_rate=24)
+        shape = self.written(template, model_step, tmp_path, frame_rate=24)
 
         assert shape["fps"] == pytest.approx(24.0)
         assert shape["frame_count"] == SRC_FRAMES
diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index ad9ebb7e..e8e01dea 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -46,6 +46,15 @@
         121,
         1.0,
     ),
+    "restore-colorize": (
+        "Lightricks/LTX-2.5-22b-IC-LoRA-Colorization",
+        "ltx-2.5-22b-ic-lora-colorization-0.9.safetensors",
+        1,
+        960,
+        544,
+        121,
+        1.0,
+    ),
     "restore-deblur": (
         "Lightricks/LTX-2.5-22b-IC-LoRA-Deblur",
         "ltx-2.5-22b-ic-lora-deblur-0.9.safetensors",
@@ -121,8 +130,8 @@ def test_the_defaults_are_the_trained_bucket(self, name):
 
         assert (variables["width"], variables["height"]) == (width, height)
         assert variables["num_frames"] == frames
-        if name == "alpha-matte":
-            # #1079: the matte is written at the source's rate; the model
+        if name in ("alpha-matte", "restore-colorize"):
+            # #1079, #1080: the output is written at the source's rate; the model
             # itself still runs at its trained 24 fps
             pipeline = conditioned_step(name)["pipeline"]
             assert variables["frame_rate"] == "source"
@@ -233,6 +242,7 @@ def test_the_upscaler_references_the_callers_clip_fitted_to_half_size(self):
         [
             ("restore-deblur", "DEBLUR"),
             ("restore-decompression", "ENHANCE QUALITY"),
+            ("restore-colorize", "COLORIZE"),
         ],
     )
     def test_the_default_prompt_is_in_the_trained_form(self, name, marker):
@@ -323,3 +333,40 @@ def test_the_skill_row_says_it(self):
 
         assert "hard cut" in row
         assert "one shot" in row
+
+
+class TestTheColorizeTemplateIsDeblursShape:
+    """#1080: deblur's pipeline with the Colorization LoRA, between
+    alpha-matte's fit and restore, so it inherits deblur's VRAM estimate
+    and keeps the source's size and rate."""
+
+    def test_it_keeps_deblurs_pipeline_identity(self):
+        from dw.vram_estimate import pipeline_identity
+
+        assert pipeline_identity(conditioned_step("restore-colorize")) == (
+            pipeline_identity(conditioned_step("restore-deblur"))
+        )
+
+    def test_the_reference_is_the_fitted_source(self):
+        (reference,) = conditioned_step("restore-colorize")["pipeline"]["arguments"][
+            "reference_conditions"
+        ]
+
+        assert reference["from_arguments"]["frames"]["location"] == (
+            "previous_result:fit.video"
+        )
+
+    def test_it_fits_by_letterbox_and_restores_at_the_frame_rate(self):
+        fit, colorized, final = definition("restore-colorize")["steps"]
+
+        assert fit["task"]["command"] == "fit_to_model"
+        assert fit["task"]["arguments"]["mode"] == "letterbox"
+        assert fit["task"]["arguments"]["downscale"] == 1
+        assert colorized["result"] == {
+            "content_type": "video/mp4",
+            "fps": 24.0,
+            "save": False,
+        }
+        assert final["task"]["command"] == "restore_to_source"
+        assert final["task"]["arguments"]["fps"] == "variable:frame_rate"
+        assert "fps" not in final["result"]
diff --git a/tests/test_ltx_prompt_library.py b/tests/test_ltx_prompt_library.py
index bcc0a8c7..4d4103de 100644
--- a/tests/test_ltx_prompt_library.py
+++ b/tests/test_ltx_prompt_library.py
@@ -73,6 +73,11 @@ def test_a_prompt_is_one_paragraph_of_caption_length(path):
 
 # The phrase each IC-LoRA card states as the form it was trained to read
 _IC_LORA_CONVENTION = {
+    "colorize_dual_panel.json": (
+        "Reference shows",
+        "COLORIZE",
+        "only color information differs",
+    ),
     "deblur_dual_panel.json": (
         "Reference shows",
         "DEBLUR",
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 6daff016..13408857 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -767,6 +767,9 @@ def test_normalized_downstream_false_when_nothing_references_it():
     "ltx2/refine-in-place.json": {
         "refine": "4b54a53f5c05de50d0b3094addf68b2d843135fdc02518b0ab02fb7e225b2552"
     },
+    "ltx2/restore-colorize.json": {
+        "colorized": "e804709bcac668776c00b3ac58e13ae4024c67116c94e29c0a543005370277fb"
+    },
     "ltx2/restore-deblur.json": {
         "restored": "676c6d3535647dca49d39838de6cf5962c1c817eefb4c750f73be169fd60aa78"
     },
diff --git a/workflows/templates/ltx2/README.md b/workflows/templates/ltx2/README.md
index 074973da..6088443b 100644
--- a/workflows/templates/ltx2/README.md
+++ b/workflows/templates/ltx2/README.md
@@ -61,13 +61,14 @@ as an in-context reference for the whole denoise - so identity, framing and
 background geometry are the source's and only the defect changes (or, for
 `alpha-matte`, the source is read and a matte drawn from it). A different
 trade from `two-stage`, which invents a sharper version of a scene it
-generated. Deblur and decompression are 0.9 preview weights trained at
+generated. Deblur, decompression and colorization are 0.9 preview weights trained at
 960x544x121 @ 24fps; generating far above that bucket weakens the effect.
 
 | Example | What it introduces |
 | ------- | ------------------ |
 | [restore-deblur.json](restore-deblur.json) | Spatial defocus only - not motion blur, not noise, not low resolution. Lower `lora_scale` toward 0.8 if it over-sharpens into haloing (#152) |
 | [restore-decompression.json](restore-decompression.json) | Macroblocking, chroma bleed, ringing and banding from a low bit-rate source. Not a deblur and not an upscale (#152) |
+| [restore-colorize.json](restore-colorize.json) | Natural colour for black-and-white or washed-out footage, at the source's size and frame rate; only the colour changes. The prompt keeps the dual-panel convention and names the colours you expect. Lower `lora_scale` toward 0.8 if colour oversaturates or bleeds (#1064) |
 | [alpha-matte.json](alpha-matte.json) | A soft per-frame alpha matte of the source - grey h264, white = foreground, at the source's size - for compositing in an editor. No prompt: the Alpha-Gen card's model picks the foreground itself. `num_frames` caps at 145, past which RGB leaks into the matte; the card's 1920x1088 ceiling is not a 24 GB size (#1064) |
 | [restore-long.json](restore-long.json) | `restore-deblur` over a source longer than one bucket: `window_video` slices it, a `for_each` restores each window, `join_windows` cross-fades them back to the source's length. `windows` is `ceil(source_frames / (num_frames - overlap))` entries, checked by `validate_workflow` (#601) |
 

From f5f792c2ff3cbb206b871151c2f6af7c690c4846 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:20:02 -0500
Subject: [PATCH 053/125] feat(templates): #1099 - minimax/face-repair: H3 t2va
 face refine with the take's soundtrack held

crop_face_track on H3's 17n+5 grid (24 fps, 124-345 padded frames, refused
before H3 loads) -> t2va refine at 0.6 with hold_audio on the crops ->
paste_face_track. Gate 0.2/0.3 (Don's ruling), README row, TASKS example,
minimax-h3 skill line, step-cache key, compact budget 12_250.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                                |   1 +
 plugins/dw/skills/minimax-h3/SKILL.md        |   2 +-
 tests/test_catalog_structure.py              |   5 +-
 tests/test_h3_sparse_defaults.py             |   6 +-
 tests/test_step_cache.py                     |   3 +
 workflows/templates/minimax/README.md        |   1 +
 workflows/templates/minimax/face-repair.json | 232 +++++++++++++++++++
 7 files changed, 245 insertions(+), 5 deletions(-)
 create mode 100644 workflows/templates/minimax/face-repair.json

diff --git a/docs/TASKS.md b/docs/TASKS.md
index f37a6147..4cb0d261 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3487,3 +3487,4 @@ Canny edge detection followed by ControlNet generation:
 - [voice-timbre-reference.json](../workflows/templates/minimax/voice-timbre-reference.json) — Generate a voice and condition H3's `<Audio 1>` on it
 - [dissolve-between-shots.json](../workflows/templates/dissolve-between-shots.json) — Dissolve between supplied shots and mix a score under their own audio
 - [face-repair.json](../workflows/templates/ltx2/face-repair.json) — Track, refine and paste back a wide shot's small face
+- [minimax/face-repair.json](../workflows/templates/minimax/face-repair.json) — The same on an H3 take, its soundtrack held so the mouth stays on the speech
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index e7b4bb1f..d7b943d0 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -6,7 +6,6 @@ description: Use when a dw MCP server is connected and the user wants MiniMax H3
 # MiniMax H3 on a dw server
 
 H3 generates video and audio together. Every template fits a 24 GB card.
-This skill picks the template and arguments; prompt format is MiniMax's.
 
 ## Before anything
 
@@ -42,6 +41,7 @@ This skill picks the template and arguments; prompt format is MiniMax's.
   section="H3: holding a clip with `guides`")`.
 - **Fix one region of a good take** (the rest and audio stay):
   `templates/minimax/regional-edit`; first `references/regional-edit.md`.
+- **A good take with a soft small face**: `templates/minimax/face-repair`.
 - **A consistent subject**: `templates/minimax/reference-to-video`
   (an image fixes appearance, an audio clip voice);
   `templates/minimax/composable-references` adds a video reference for
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 0972eb2c..eee0c09a 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -508,7 +508,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Then to 12_050 for the `minimax/regional-edit` template (#1062, stage #1078,
 # 2026-10-31), measured at 11_983: one new entry, the catalog's only regional
 # edit of a take, with its cost block.
-COMPACT_BUDGET = 12_050
+# Then to 12_250 for the `minimax/face-repair` template (#1092, stage #1099,
+# 2026-10-31), measured at 12_171: one new entry, the catalog's only face
+# repair that holds an H3 take's soundtrack, with its cost block.
+COMPACT_BUDGET = 12_250
 FILTERED_BUDGET = 1_500
 
 
diff --git a/tests/test_h3_sparse_defaults.py b/tests/test_h3_sparse_defaults.py
index 8aa89ce1..3b2afd2d 100644
--- a/tests/test_h3_sparse_defaults.py
+++ b/tests/test_h3_sparse_defaults.py
@@ -27,9 +27,9 @@ def _read(path):
 )
 
 
-def test_twenty_h3_templates():
-    # 20 since minimax/regional-edit (#1078)
-    assert len(H3) == 20
+def test_twenty_one_h3_templates():
+    # 20 since minimax/regional-edit (#1078), 21 since minimax/face-repair (#1099)
+    assert len(H3) == 21
 
 
 @pytest.mark.parametrize("path", H3)
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 6daff016..b9c81840 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -847,6 +847,9 @@ def test_normalized_downstream_false_when_nothing_references_it():
     "minimax/reference-to-video.json": {
         "reference_to_video_audio": "ba9915580e6a8017d8c68efbddea776985d107222546f84cca18e319298243bf"
     },
+    "minimax/face-repair.json": {
+        "refine": "2a7fdf989a40500620fb03212502bbda8f52827f5fcd872b8fda182fab2fac77"
+    },
     "minimax/regional-edit.json": {
         "edit": "2a7fdf989a40500620fb03212502bbda8f52827f5fcd872b8fda182fab2fac77"
     },
diff --git a/workflows/templates/minimax/README.md b/workflows/templates/minimax/README.md
index b9d2b19f..881221c1 100644
--- a/workflows/templates/minimax/README.md
+++ b/workflows/templates/minimax/README.md
@@ -122,6 +122,7 @@ the hosted API accept 4. Output audio is 32 kHz stereo.
 | Example | What it introduces |
 | ------- | ------------------ |
 | [regional-edit.json](regional-edit.json) | Fixing one region of a good take: `source_video` is the take, a `mask_image` marks what to regenerate (white) and keep (black), `refine_strength` 0.9 replaces an object there, and `hold_audio` is the take itself, so the rest of the picture and the whole soundtrack stay the take's |
+| [face-repair.json](face-repair.json) | Repairing a good take's small, soft face: `crop_face_track` cuts the face out on H3's `17n + 5` grid (24 fps, 124 to 345 padded frames, refused before H3 loads), a t2va refine at `refine_strength` 0.6 redraws it with `hold_audio` holding the take's own soundtrack so the mouth stays on the speech, and `paste_face_track` puts it back. The gate is 0.2/0.3 of the frame width, for H3's smaller faces. A ref2va refine with the cast picture holds identity slightly better, at about 4x the denoise time |
 
 ## Writing the prompt with a model
 
diff --git a/workflows/templates/minimax/face-repair.json b/workflows/templates/minimax/face-repair.json
new file mode 100644
index 00000000..37e4e297
--- /dev/null
+++ b/workflows/templates/minimax/face-repair.json
@@ -0,0 +1,232 @@
+{
+    "id": "MiniMaxH3FaceRepair",
+    "description": "Gives a good H3 take's small, soft face more detail without losing its lip sync. 'crop' (crop_face_track) tracks the take's main face and cuts a 'crop_size' square around it on every frame, padded to H3's 17n+5 frame grid with reflected frames, and carries the take's own soundtrack padded with silence to match; 'refine' re-denoises those crops with MiniMax-H3 t2va from 'refine_strength' while its hold_audio holds that soundtrack, so the mouth is redrawn against the speech it says; 'pasted' (paste_face_track) feathers each refined crop back into the take at the track's box, colour-matched to it, and drops the padded frames. The take must be 24 fps and, padded, 124 to 345 frames (about 5.2 to 14.4 s): the crop step refuses anything else, naming the clip's frame count or rate, before H3 loads; a shorter take uses templates/ltx2/face-repair. How much each frame is repaired comes from the face's size: full strength while it is at most 'gate_full' of the frame's width, fading to none at 'gate_zero', so a large face comes back as the source. 'refine_strength' 0.6 (measured on two dialogue takes, #1092) keeps the person; 0.72 drifts identity and 0.8 distorts frames. Replace the default prompt with a description of the person (hair, clothing, lighting) to hold identity closer. A ref2va refine with the cast picture as <Picture 1> held identity slightly better at about 4x the denoise time; this template is t2va. The final picture keeps the take's frame count, frame rate and soundtrack; the crops and refined crops are saved to intermediate/.",
+    "summary": "An H3 take's small, soft face redrawn by H3 with its soundtrack held; lip sync kept.",
+    "cost": [
+        {
+            "device": "cuda",
+            "name": "RTX 3090",
+            "vram_gb": 24,
+            "minutes": 3.0
+        }
+    ],
+    "cost_drivers": [
+        "crop_size",
+        "num_inference_steps",
+        "weights_dtype",
+        "lora_model_name",
+        "attention_backend",
+        "cache"
+    ],
+    "variables": {
+        "source_video": "asset:take.mp4",
+        "prompt": "A detailed close-up of the same person's face: the same expression, the same head, eye and mouth movement in time with the speech, the same lighting and hair, a still camera.",
+        "refine_strength": 0.6,
+        "num_inference_steps": 5,
+        "crop_size": 512,
+        "padding": 1.5,
+        "gate_full": 0.2,
+        "gate_zero": 0.3,
+        "feather": 0.3,
+        "weights_dtype": "{int4}",
+        "lora_model_name": "lightx2v/Minimax-h3-Turbo",
+        "seed": 1092,
+        "attention_backend": "sparse",
+        "sparse_tau": 0.5,
+        "sparse_topk": 0.15,
+        "cache": null
+    },
+    "variable_constraints": {
+        "crop_size": {
+            "modulus": 32,
+            "remainder": 0,
+            "reason": "the crops are H3's frame size, and its pipeline refuses a width or height that is not a multiple of 32 only after the weights have loaded; the crop step declares H3's grid (modulus 17, remainder 5, multiple 32), so the crop count is padded to 17 * n + 5 frames"
+        }
+    },
+    "seed": "variable:seed",
+    "steps": [
+        {
+            "name": "crop",
+            "task": {
+                "command": "crop_face_track",
+                "arguments": {
+                    "clip": "variable:source_video",
+                    "crop_size": "variable:crop_size",
+                    "padding": "variable:padding",
+                    "gate_full": "variable:gate_full",
+                    "gate_zero": "variable:gate_zero",
+                    "modulus": 17,
+                    "remainder": 5,
+                    "multiple": 32,
+                    "min_frames": 124,
+                    "max_frames": 345,
+                    "fps": 24
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24,
+                "subfolder": "intermediate"
+            }
+        },
+        {
+            "name": "refine",
+            "release_pipeline": true,
+            "pipeline": {
+                "configuration": {
+                    "component_type": "ModularPipeline",
+                    "pre_load_modules": [
+                        "sdnq"
+                    ],
+                    "load_components": {
+                        "dtype": "torch.bfloat16",
+                        "quantization_config": {
+                            "transformer": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "variable:weights_dtype",
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "use_quantized_matmul": true,
+                                    "dequantize_fp32": false,
+                                    "modules_to_not_convert": [
+                                        "proj_in",
+                                        "audio_proj_in",
+                                        "context_embedder",
+                                        "time_embedder",
+                                        "time_proj",
+                                        "token_refiner",
+                                        "norm_out",
+                                        "proj_out",
+                                        "audio_proj_out"
+                                    ]
+                                }
+                            },
+                            "text_encoder": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "variable:weights_dtype",
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "dequantize_fp32": false,
+                                    "modules_to_not_convert": [
+                                        ".model.visual",
+                                        "lm_head"
+                                    ]
+                                }
+                            },
+                            "vae": {
+                                "configuration": {
+                                    "config_type": "sdnq.SDNQConfig"
+                                },
+                                "arguments": {
+                                    "weights_dtype": "{int8}",
+                                    "quant_conv": true,
+                                    "use_quantized_matmul_conv": true,
+                                    "quantization_device": "cuda",
+                                    "return_device": "cpu",
+                                    "dequantize_fp32": false
+                                }
+                            }
+                        }
+                    },
+                    "components": {
+                        "transformer": {
+                            "attention_backend": "variable:attention_backend",
+                            "sparse_tau": "variable:sparse_tau",
+                            "sparse_topk": "variable:sparse_topk",
+                            "group_offload": {
+                                "offload_type": "block_level",
+                                "num_blocks_per_group": 2,
+                                "use_stream": true,
+                                "record_stream": true,
+                                "low_cpu_mem_usage": true
+                            }
+                        },
+                        "text_encoder": {
+                            "remove_modules": [
+                                "lm_head"
+                            ]
+                        },
+                        "text_encoder.model": {
+                            "truncate_layers": {
+                                "language_model.layers": 51
+                            },
+                            "group_offload": {
+                                "offload_type": "leaf_level"
+                            }
+                        },
+                        "vae": {
+                            "device": "cuda",
+                            "residency": "on_demand"
+                        },
+                        "audio_vae": {
+                            "device": "cuda",
+                            "residency": "on_demand"
+                        }
+                    },
+                    "cache": "variable:cache"
+                },
+                "from_pretrained_arguments": {
+                    "model_name": "MiniMaxAI/MiniMax-H3",
+                    "workflow": "t2va"
+                },
+                "loras": [
+                    {
+                        "model_name": "variable:lora_model_name",
+                        "weight_name": "minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors",
+                        "adapter_name": "turbo",
+                        "scale": 1.0
+                    }
+                ],
+                "scheduler": {
+                    "shift": 6.0
+                },
+                "audio_scheduler": {
+                    "shift": 3.0
+                },
+                "arguments": {
+                    "prompt": "variable:prompt",
+                    "source_video": "previous_result:crop.crops",
+                    "hold_audio": "previous_result:crop.crops",
+                    "refine_strength": "variable:refine_strength",
+                    "num_frames": null,
+                    "width": null,
+                    "height": null,
+                    "num_inference_steps": "variable:num_inference_steps",
+                    "output": [
+                        "videos",
+                        "audio",
+                        "sampling_rate"
+                    ]
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24,
+                "subfolder": "intermediate"
+            }
+        },
+        {
+            "name": "pasted",
+            "task": {
+                "command": "paste_face_track",
+                "arguments": {
+                    "clip": "variable:source_video",
+                    "repaired": "previous_result:refine",
+                    "track": "previous_result:crop.track",
+                    "feather": "variable:feather"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "fps": 24,
+                "subfolder": "final"
+            }
+        }
+    ]
+}

From 3cc3805aec44c89b48aeb038bc394888a2ef20d4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:23:37 -0500
Subject: [PATCH 054/125] feat(templates): #1099 - face-repair cost measured on
 lem: 2.2 min (job 38da34a526e1, 127 s)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 workflows/templates/minimax/face-repair.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/workflows/templates/minimax/face-repair.json b/workflows/templates/minimax/face-repair.json
index 37e4e297..457ec994 100644
--- a/workflows/templates/minimax/face-repair.json
+++ b/workflows/templates/minimax/face-repair.json
@@ -7,7 +7,7 @@
             "device": "cuda",
             "name": "RTX 3090",
             "vram_gb": 24,
-            "minutes": 3.0
+            "minutes": 2.2
         }
     ],
     "cost_drivers": [

From 416ed9350c2a2a6d81ea340a33651d69df2527f6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:27:32 -0500
Subject: [PATCH 055/125] feat(templates): #1099 - face-repair declares the
 LoRA and shift variables H3 templates must expose

test_h3_schedule requires variable:video_shift/audio_shift and variable:lora_alpha
on every H3 step; the pins are gone. Compact listing re-measured at 12_201.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_catalog_structure.py              |  2 +-
 workflows/templates/minimax/face-repair.json | 17 ++++++++++++-----
 2 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index eee0c09a..88376880 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -509,7 +509,7 @@ def test_no_stale_entry_in_the_allowlist():
 # 2026-10-31), measured at 11_983: one new entry, the catalog's only regional
 # edit of a take, with its cost block.
 # Then to 12_250 for the `minimax/face-repair` template (#1092, stage #1099,
-# 2026-10-31), measured at 12_171: one new entry, the catalog's only face
+# 2026-10-31), measured at 12_201: one new entry, the catalog's only face
 # repair that holds an H3 take's soundtrack, with its cost block.
 COMPACT_BUDGET = 12_250
 FILTERED_BUDGET = 1_500
diff --git a/workflows/templates/minimax/face-repair.json b/workflows/templates/minimax/face-repair.json
index 457ec994..1a135f28 100644
--- a/workflows/templates/minimax/face-repair.json
+++ b/workflows/templates/minimax/face-repair.json
@@ -30,6 +30,12 @@
         "feather": 0.3,
         "weights_dtype": "{int4}",
         "lora_model_name": "lightx2v/Minimax-h3-Turbo",
+        "lora_weight_name": "minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors",
+        "lora_adapter_name": "turbo",
+        "lora_scale": 1.0,
+        "lora_alpha": null,
+        "video_shift": 6.0,
+        "audio_shift": 3.0,
         "seed": 1092,
         "attention_backend": "sparse",
         "sparse_tau": 0.5,
@@ -178,16 +184,17 @@
                 "loras": [
                     {
                         "model_name": "variable:lora_model_name",
-                        "weight_name": "minimax_h3_fl2v_turbo_4step_v1.2_768p_bf16.safetensors",
-                        "adapter_name": "turbo",
-                        "scale": 1.0
+                        "weight_name": "variable:lora_weight_name",
+                        "adapter_name": "variable:lora_adapter_name",
+                        "scale": "variable:lora_scale",
+                        "alpha": "variable:lora_alpha"
                     }
                 ],
                 "scheduler": {
-                    "shift": 6.0
+                    "shift": "variable:video_shift"
                 },
                 "audio_scheduler": {
-                    "shift": 3.0
+                    "shift": "variable:audio_shift"
                 },
                 "arguments": {
                     "prompt": "variable:prompt",

From cef4041d8d16ab31858ada068fac2bf2e9a8edb4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:37:20 -0500
Subject: [PATCH 056/125] feat(plugin): #1096 - series-episodes dialogue/rest
 recipe via separate_stems

Don's verdict on #1096: htdemucs is good enough as a dialogue/rest
splitter. Replace the world_gain dead end with the three-track recipe and
the caveat that a scored mix's rest carries the shots' foley.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/series-episodes/SKILL.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 72989120..534c9bb5 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -112,9 +112,17 @@ composes into, not something to re-derive:
   before the cut; leaving it null only warns on a wide spread instead of
   fixing it. A shot whose voice-over the score buries is a different
   problem, not fixed by `match_levels` or `world_gain` (which lifts the
-  whole world track, action sound included) - see `minimax-h3`'s ducking
-  recipe: `gain_audio` regions on the score, one per voice-over shot,
-  applied before the score is passed in.
+  whole world track, action sound included). Either duck the score -
+  `minimax-h3`'s ducking recipe: `gain_audio` regions on the score, one per
+  voice-over shot, applied before the score is passed in - or give dialogue
+  its own gain. For that, in a saved copy of `assemble-and-score`, add a
+  `separate_stems` step on `world_faded`; `previous_result:<step>.vocals` is
+  the dialogue, and a `mix_audio` of its `drums`, `bass` and `other` is the
+  rest (room tone, foley, action sound). Then have `mixed` layer
+  `[soundtrack_resampled, dialogue, rest]`, one gain each. htdemucs keeps H3
+  speech intact this way (#1091). Separating an already-scored mix works
+  too, but its rest is the score plus the shots' foley, not a clean score:
+  keep the original score file to re-mix or replace it.
 - **normalize**: the mixed world sound and score are normalized together
   (`assemble-and-score`'s `balanced` step, -3 dBFS peak ceiling, always
   enforced), but a shared peak is not a shared loudness. Pass one series

From f0fb02d4282abf46ae3dd9a51da0a7315d90a2df Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:45:53 -0500
Subject: [PATCH 057/125] fix(security): GHSA-w9qv-2pg5-j79m,
 GHSA-75cg-7964-pjwx - reference errors no longer name server paths

An 'output:' reference that names nothing raised "Output '...' not found
under <root>", handing any MCP client the absolute output root (host
username, workspace layout) from validate_workflow or run_workflow. Both
raises now name the reference only. A missing relative media path had
the same leak through "Path does not exist: <resolved>"; it now names
the location as written.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/locations.py         |  3 ++-
 dw/runs.py              |  6 ++++--
 tests/test_locations.py |  9 +++++++++
 tests/test_runs.py      | 21 +++++++++++++++++++++
 4 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/dw/locations.py b/dw/locations.py
index 7090c90a..aa0cf2b5 100644
--- a/dw/locations.py
+++ b/dw/locations.py
@@ -222,7 +222,8 @@ def validate_media_path(
             )
 
     if require_exists and not os.path.exists(resolved):
-        raise InvalidInputError(f"Path does not exist: {resolved}")
+        # Named as written: the resolved path is the server's own layout
+        raise InvalidInputError(f"Path does not exist: '{location}'")
     return resolved
 
 
diff --git a/dw/runs.py b/dw/runs.py
index 75a1ed61..86cb7e0b 100644
--- a/dw/runs.py
+++ b/dw/runs.py
@@ -251,10 +251,12 @@ def resolve_output_reference(reference, root=None, before=None):
     name = validate_output_reference(name.strip())
     root = root or output_root()
 
+    # The errors below reach the client, so they name the reference and
+    # never the root: that is the server's own filesystem layout
     resolved = _resolve_segments(root, name.split("/"), reference, root, before)
     if resolved is None:
         raise ValueError(
-            f"Output '{name}' not found under {root} - no run of that workflow "
+            f"Output '{name}' not found - no run of that workflow "
             f"holds the file. A run that failed, or reused every step from the "
             f"cache, leaves only its manifest behind"
         )
@@ -265,7 +267,7 @@ def resolve_output_reference(reference, root=None, before=None):
 
     if not os.path.isfile(resolved):
         raise ValueError(
-            f"Output '{name}' not found under {root} - an 'output:' reference "
+            f"Output '{name}' not found - an 'output:' reference "
             f"names a file an earlier run wrote, like "
             f"'output:ltx2/Gyre/latest/Gyre-still.0-0.0.png'"
         )
diff --git a/tests/test_locations.py b/tests/test_locations.py
index f25fd511..95665e1a 100644
--- a/tests/test_locations.py
+++ b/tests/test_locations.py
@@ -106,6 +106,15 @@ def test_a_relative_path_still_resolves_against_the_workflow(
             os.path.join(workflow_dir, "subject.png")
         )
 
+    def test_a_missing_relative_path_does_not_name_the_directory(
+        self, untrusted, workflow_dir
+    ):
+        # The error reaches the client: it names the location as written,
+        # not where the server resolved it (GHSA-w9qv-2pg5-j79m's sibling)
+        with pytest.raises(InvalidInputError, match="missing.png") as raised:
+            validate_media_path("missing.png", workflow_dir)
+        assert os.path.realpath(workflow_dir) not in str(raised.value)
+
     def test_trust_lifts_containment(self, trusted, workflow_dir):
         with tempfile.TemporaryDirectory() as elsewhere:
             outside = _image(os.path.join(elsewhere, "scratch.png"))
diff --git a/tests/test_runs.py b/tests/test_runs.py
index 380e49a0..3e60741d 100644
--- a/tests/test_runs.py
+++ b/tests/test_runs.py
@@ -1249,3 +1249,24 @@ def sweep_then_claim(path, *args, **kwargs):
         assert swept
         assert os.path.isdir(run_dir)
         assert version == 1
+
+
+class TestOutputReferenceErrors:
+    # GHSA-75cg-7964-pjwx / GHSA-w9qv-2pg5-j79m: the error goes back to the
+    # client, so it names the reference, never the server's output root
+
+    def test_a_run_that_does_not_exist_does_not_name_the_root(self, tmp_path):
+        (tmp_path / "shot-frame").mkdir()
+        with pytest.raises(ValueError, match="not found") as raised:
+            resolve_output_reference(
+                "output:shot-frame/20991231-000000-nosuchrun/frame.png",
+                str(tmp_path),
+            )
+        assert str(tmp_path) not in str(raised.value)
+        assert "shot-frame/20991231-000000-nosuchrun/frame.png" in str(raised.value)
+
+    def test_a_name_that_is_not_a_file_does_not_name_the_root(self, tmp_path):
+        (tmp_path / "shot-frame" / "run").mkdir(parents=True)
+        with pytest.raises(ValueError, match="not found") as raised:
+            resolve_output_reference("output:shot-frame/run", str(tmp_path))
+        assert str(tmp_path) not in str(raised.value)

From 61a1b4a93711b790fd77311a0ed3b0dbe6227f9d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 16:59:47 -0500
Subject: [PATCH 058/125] feat(plugin): #1096 - dialogue recipe keeps balanced
 for headroom, notes quiet beds land in vocals

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/series-episodes/SKILL.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 534c9bb5..2d336403 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -119,8 +119,12 @@ composes into, not something to re-derive:
   `separate_stems` step on `world_faded`; `previous_result:<step>.vocals` is
   the dialogue, and a `mix_audio` of its `drums`, `bass` and `other` is the
   rest (room tone, foley, action sound). Then have `mixed` layer
-  `[soundtrack_resampled, dialogue, rest]`, one gain each. htdemucs keeps H3
-  speech intact this way (#1091). Separating an already-scored mix works
+  `[soundtrack_resampled, dialogue, rest]`, one gain each, and keep
+  `balanced` after it: a dialogue gain above 1 on a stem peaking near full
+  scale sums past 0 dBFS, which `balanced` pulls back to -3. htdemucs keeps
+  H3 speech intact this way (#1091). A shot with little foley leaves a
+  near-silent rest, and a quiet unpitched bed (room tone, ambience) lands
+  mostly in `vocals`, not the rest. Separating an already-scored mix works
   too, but its rest is the score plus the shots' foley, not a clean score:
   keep the original score file to re-mix or replace it.
 - **normalize**: the mixed world sound and score are normalized together

From a7e267c491c42efc169e14a0e53b4306bfea3cbc Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 17:12:14 -0500
Subject: [PATCH 059/125] feat(tasks): #1104 - analyze_phrases task: sung
 phrases from centre-weighted voiced energy

New JSON task dw/tasks/phrases.py: mid/side band power (250-3500 Hz) on
stereo, band energy on mono / centre=false / identical channels, voiced
floor from voice_attribution, gap bridging and short-run dropping.
Warnings for mono, no phrases (with the centre:false hint) and one fused
phrase (pointing at separate_stems vocals), all through emit_warning.
Domains and a static check on 'centre'; registry pins, TASKS.md entry and
an ARCHITECTURE.md row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md              |   1 +
 docs/TASKS.md                     |  57 ++++++
 dw/task_problems.py               |  29 +++-
 dw/tasks/phrases.py               | 277 ++++++++++++++++++++++++++++++
 dw/tasks/task.py                  |   1 +
 tests/test_analyze_phrases.py     | 227 ++++++++++++++++++++++++
 tests/test_task_discovery.py      |  26 +++
 tests/test_task_domains.py        |  18 ++
 tests/test_task_registry_rules.py |   1 +
 9 files changed, 636 insertions(+), 1 deletion(-)
 create mode 100644 dw/tasks/phrases.py
 create mode 100644 tests/test_analyze_phrases.py

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 430df69c..a22898fd 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -143,6 +143,7 @@ one to open.
 | Assessment probes | `dw/tasks/assess.py`, `dw/assessment_rules.py` | Exactly three registered commands are assessment probes. Each measures a finished file, and every rule names a real probe field. | `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_assessment_is_exactly_the_three_probes`, `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_every_rule_names_a_registered_json_command` |
 | Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` (`script_take.word_level` wraps it; the guard, the transcription levelling and the shot placement are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
 | Audio sync against a source slice | `dw/tasks/measure_sync.py`: `measure_sync`; `dw/dsp.py`: `envelope_lag` | `measure_sync` cross-correlates the onset envelopes of a shot's audio and its source slice and answers the lag and a 0-1 confidence. A positive lag means the audio is LATE (its events fall after the reference's), negative early; `lag_seconds` is None for a silent or flat track. It builds its findings (`sync_unmeasurable`, `sync_low_confidence`, `audio_out_of_sync`) with `assessment_rules.finding()` over module-local rule dicts and adds nothing to `RULES`; it reads the silence floor from `beats.SILENT_DBFS`. `envelope_lag` imports nothing from `dw`. | `tests/test_measure_sync.py::TestLag::test_late_audio_is_a_positive_lag`, `tests/test_measure_sync.py::TestLag::test_early_audio_is_a_negative_lag`, `tests/test_measure_sync.py::TestUnmeasurable::test_a_silent_reference_has_no_lag` |
+| Sung phrases from voiced energy | `dw/tasks/phrases.py`: `analyze_phrases`, `voiced_power`, `voiced_runs`; `dw/task_problems.py`: `phrases_problems`, `phrases_errors` | `analyze_phrases` times a song's sung phrases with no model: a stereo file's centre-weighted band power (max(0, P_mid - P_side), 250-3500 Hz, 20 ms frames) or, for mono, `centre: false` or identical channels, the downmix's band power (`method` `band`). The voiced floor is `voice_attribution.voiced_floor_dbfs`, the rule `attribute_voices` uses, unless `floor_db` is given. It answers a dict - `{phrases, duration_seconds, method, warnings}` - so a step saves one JSON artifact. Its ranges are the registration's domains; `phrases_problems` (a real boolean `centre`) runs at validate and at run time. | `tests/test_analyze_phrases.py::TestCentre::test_centred_bursts_under_hard_panned_noise_are_found`, `tests/test_analyze_phrases.py::TestCentre::test_bursts_panned_hard_to_one_side_are_not_centre`, `tests/test_analyze_phrases.py::TestRefusals::test_validate_refuses_a_missing_audio_and_a_negative_gap` |
 
 ## Security and architecture guardrails
 
diff --git a/docs/TASKS.md b/docs/TASKS.md
index 4cb0d261..3a42393c 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -2043,6 +2043,63 @@ out of order, a non-whole `beat_index`), at `validate_workflow`; an anchor past
 the song's end, or a `beat_index` past the detected count, at run start.
 It returns JSON, so `result` may only be `application/json`.
 
+### analyze_phrases
+
+Find when a song's sung phrases start and stop, from voiced energy alone - no
+Whisper, no model download, seconds of runtime. Where Whisper cannot hear the
+words (a non-English verse, a hallucinated transcript, wordless vocals) this
+still says when the lines are sung. Feed it the vocal stem where there is one;
+the result is JSON and nothing is built:
+
+```json
+{
+    "name": "phrases",
+    "task": {
+        "command": "analyze_phrases",
+        "arguments": {
+            "audio": "previous_result:stems.vocals"
+        }
+    },
+    "result": { "content_type": "application/json" }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `audio` | Yes | The song or its vocal stem: a path, `asset:`/`output:` reference of an audio or video file, a waveform, or an earlier step's generated audio (`previous_result:<separate_stems step>.vocals`) |
+| `min_gap_seconds` | No | A silence shorter than this between voiced runs is bridged into one phrase (default `0.35`). Raise it to merge phrases split by breaths, lower it to split lines sung close together. At least 0 |
+| `min_phrase_seconds` | No | A phrase shorter than this, after bridging, is dropped as a click or breath (default `0.3`). Above 0 |
+| `floor_db` | No | The level, in dBFS of a 20 ms frame, a frame must reach to count as voiced. Unset, it is the track's 95th-percentile frame less 35 dB, never below -60 dBFS (the floor `attribute_voices` uses). At or below 0 |
+| `centre` | No | `true` (the default) weights a stereo file to its centre, where a lead vocal is mixed; `false` uses the band energy of the downmix. A real boolean - `"false"` is refused |
+| `sample_rate` | With a waveform | Rate of a directly passed waveform (files carry their own) |
+
+Returns `{phrases: [{start, end}], duration_seconds, method, warnings}`, in
+seconds rounded to 0.01; the phrases ascend and do not overlap.
+
+- **`method: "centre"`** (stereo, `centre: true`): mid = (L+R)/2 and side =
+  (L-R)/2 are both bandpassed to 250-3500 Hz, and a 20 ms frame's power is
+  max(0, P_mid - P_side), smoothed over three frames. What is panned away from
+  the centre cancels, so a hard-panned guitar or noise bed does not read as
+  singing - and a vocal panned hard to one side does not either: use
+  `centre: false` for it.
+- **`method: "band"`**: the band energy of the downmix, for a mono file (which
+  also warns), for `centre: false`, and for a stereo file whose channels are
+  the same (it has no side to cancel, so no warning).
+
+A frame is voiced at or above the floor; gaps shorter than `min_gap_seconds`
+are bridged, then runs shorter than `min_phrase_seconds` are dropped.
+
+Warnings: no phrases found (a silent track, or one whose loudest frame is
+under -50 dBFS in the voice band - room tone, hiss - unless `floor_db` is
+given); and one phrase covering more than 90% of the track, which is usually
+a dense mix whose centred bass and kick fill the voice band: feed it
+`separate_stems`' `vocals` instead. `warnings` repeats what was emitted.
+
+Refused at `validate_workflow`: a missing `audio`, a negative
+`min_gap_seconds`, a `min_phrase_seconds` at or below 0, a `floor_db` above 0,
+and a `centre` that is not `true` or `false`; the run refuses the same.
+It returns JSON, so `result` may only be `application/json`.
+
 ### plan_cuts
 
 Plan a music video's cuts from a song's lyrics and beats. `transcribe_audio`
diff --git a/dw/task_problems.py b/dw/task_problems.py
index 47371865..7e64c9a7 100644
--- a/dw/task_problems.py
+++ b/dw/task_problems.py
@@ -4,7 +4,7 @@
 is everything a single range cannot say: crop_face_track's crop size on the
 video model's frame grid, gate_zero above gate_full; analyze_beats' tempo range
 and anchors that are one kind and in time order; plan_cuts' transcript shape
-and render grid; apply_lut's one-of-two source and its palette; check_script's
+and render grid; analyze_phrases' `centre` as a real boolean; apply_lut's one-of-two source and its palette; check_script's
 `lines` and `shots`; ingredients_grid's choices and image count. Each family's
 `*_problems` function is the rule, and both sides call it - its `*_errors`
 static check (registered as the command's `static_check`, run by
@@ -544,6 +544,33 @@ def cuts_errors(arguments):
     return choice_errors("plan_cuts", arguments) + cuts_problems(**literal)
 
 
+def phrases_problems(centre=None):
+    """[(argument, message)] for each analyze_phrases rule these values break
+    past a domain: `centre` given as anything but true or false. A string
+    "false" would read as on; it is refused rather than guessed at."""
+    if centre is None or isinstance(centre, bool):
+        return []
+    return [
+        (
+            "centre",
+            "analyze_phrases needs 'centre' as true or false - true weights a "
+            "stereo file to its centre, false uses the band energy of the "
+            f"downmix - not {centre!r}",
+        )
+    ]
+
+
+def phrases_errors(arguments):
+    """[(argument, message)] for the analyze_phrases rules a literal workflow
+    can break before it runs (`phrases_problems`). Its numeric ranges - a
+    non-negative gap, a positive phrase length, a floor at or under 0 dBFS -
+    are the registration's domains."""
+    centre = arguments.get("centre")
+    if is_ref(DEFERRED, centre):
+        return []
+    return phrases_problems(centre=centre)
+
+
 # apply_lut's palette: 2..16 colours, each #rrggbb (#603 stage D)
 MIN_PALETTE_COLOURS = 2
 MAX_PALETTE_COLOURS = 16
diff --git a/dw/tasks/phrases.py b/dw/tasks/phrases.py
new file mode 100644
index 00000000..3bed922f
--- /dev/null
+++ b/dw/tasks/phrases.py
@@ -0,0 +1,277 @@
+"""analyze_phrases: when a song's sung lines start and stop, without Whisper (#1095).
+
+`plan_cuts` takes all of its line timing from a transcript, and when Whisper
+cannot hear the words - a non-English verse, a hallucination, wordless
+vocals - there is nothing else to time the lines by. This finds the phrases
+from voiced energy alone: no model, no download, seconds of runtime.
+
+On a stereo file it weights the centre, where a lead vocal is mixed: mid =
+(L+R)/2 and side = (L-R)/2, both bandpassed to the voice band, and a frame's
+power is max(0, P_mid - P_side), so what is panned away from the centre
+cancels. A mono file, a stereo file whose channels are the same, or
+`centre=false` uses the band energy of the downmix instead (`method:
+"band"`). A frame is voiced above a floor relative to the track - the rule
+`voice_attribution.voiced_floor_dbfs` applies to a stem - and the voiced runs
+become phrases once short gaps are bridged and short runs dropped.
+
+On a dense mix the centred bass and kick sit partly in the band too, and the
+phrases fuse; the task warns, and the documented path feeds it
+`separate_stems`' `vocals` stem. The result is a dict, so a step saves it as
+one JSON artifact.
+"""
+
+import logging
+
+import numpy
+
+from .registry import register_command
+from ..task_domains import NON_NEGATIVE, NON_POSITIVE, POSITIVE
+from ..task_problems import phrases_errors, phrases_problems
+
+logger = logging.getLogger("dw")
+
+COMMAND = "analyze_phrases"
+
+# The voice band both channels are filtered to, in Hz
+BAND_LOW_HZ = 250.0
+BAND_HIGH_HZ = 3500.0
+# A Butterworth biquad's Q, run twice at each edge for a steeper skirt
+BAND_Q = 0.7071
+# The analysis frame, and the centred moving average that smooths its power
+FRAME_SECONDS = 0.02
+SMOOTH_FRAMES = 3
+# A side channel this far under the mid (in power) is no side at all: the
+# channels are the same, and the centre weighting has nothing to cancel
+ALL_CENTRE_DB = -60.0
+# A track whose loudest frame is under this, in the band, is near-silence -
+# room tone or hiss that a relative floor would still call voiced. A given
+# `floor_db` is the caller's own floor, and skips this
+NEAR_SILENT_DBFS = -50.0
+# One phrase covering more than this share of the track is a dense mix, fused
+ONE_PHRASE_SHARE = 0.9
+# Seconds as reported
+TIME_PLACES = 2
+
+
+def _band(channel, rate):
+    """The channel bandpassed to BAND_LOW_HZ..BAND_HIGH_HZ: a highpass and a
+    lowpass biquad, each run twice. The lowpass edge is held under Nyquist."""
+    from .. import dsp
+
+    high_b, high_a = dsp.biquad_coefficients("highpass", BAND_LOW_HZ, BAND_Q, rate)
+    low_edge = min(BAND_HIGH_HZ, 0.45 * rate)
+    low_b, low_a = dsp.biquad_coefficients("lowpass", low_edge, BAND_Q, rate)
+    for b, a in ((high_b, high_a), (high_b, high_a), (low_b, low_a), (low_b, low_a)):
+        channel = dsp.apply_biquad(channel, b, a)
+    return channel
+
+
+def _frame_power(channel, frame):
+    """The mean power of each whole `frame`-sample frame of a channel."""
+    count = len(channel) // frame
+    frames = channel[: count * frame].reshape(count, frame)
+    return numpy.mean(frames * frames, axis=1)
+
+
+def _smooth(power):
+    """A centred SMOOTH_FRAMES moving average, the same length as `power`."""
+    if len(power) < SMOOTH_FRAMES:
+        return power
+    kernel = numpy.ones(SMOOTH_FRAMES) / SMOOTH_FRAMES
+    return numpy.convolve(power, kernel, mode="same")
+
+
+def voiced_power(wave, rate, centre=True):
+    """(per-frame power, frame length in samples, method, side_free) for a
+    (channels, samples) waveform: the centre-weighted power of a stereo
+    file, or the band power of the downmix when the file is mono, when
+    `centre` is off, or when its side channel is silent. `side_free` says the
+    centre weighting was asked for on stereo but had no side to cancel."""
+    from .. import dsp
+
+    frame = max(1, int(round(FRAME_SECONDS * rate)))
+    wave = numpy.asarray(wave, dtype=numpy.float64)
+    if centre and wave.shape[0] >= 2:
+        left, right = wave[0], wave[1]
+        mid = _frame_power(_band((left + right) / 2.0, rate), frame)
+        side = _frame_power(_band((left - right) / 2.0, rate), frame)
+        mid_total, side_total = float(mid.sum()), float(side.sum())
+        if mid_total > 0 and side_total > mid_total * 10 ** (ALL_CENTRE_DB / 10):
+            power = numpy.maximum(0.0, mid - side)
+            return _smooth(power), frame, "centre", False
+        # the channels are the same: the mid is the band energy already
+        return _smooth(mid), frame, "band", True
+    power = _frame_power(_band(dsp.mono_float64(wave), rate), frame)
+    return _smooth(power), frame, "band", False
+
+
+def voiced_runs(voiced, min_gap_frames, min_phrase_frames):
+    """[(first frame, end frame)] of the voiced runs in a boolean array, with
+    each gap shorter than `min_gap_frames` bridged and each run then shorter
+    than `min_phrase_frames` dropped. The end frame is exclusive."""
+    runs = []
+    index, count = 0, len(voiced)
+    while index < count:
+        if not voiced[index]:
+            index += 1
+            continue
+        start = index
+        while index < count and voiced[index]:
+            index += 1
+        if runs and start - runs[-1][1] < min_gap_frames:
+            runs[-1] = (runs[-1][0], index)
+        else:
+            runs.append((start, index))
+    return [(start, end) for start, end in runs if end - start >= min_phrase_frames]
+
+
+def analyze_phrases(
+    audio,
+    min_gap_seconds=0.35,
+    min_phrase_seconds=0.3,
+    floor_db=None,
+    centre=True,
+    sample_rate=None,
+):
+    """Find when a song's sung phrases start and stop, from voiced energy.
+
+    Args:
+        audio: The song or its vocal stem - a file, a generated audio result
+            (`previous_result:<separate_stems step>.vocals`), or a video
+            carrying a soundtrack. A vocal stem gives the cleanest phrases;
+            a dense mix can fuse into one
+        min_gap_seconds: A silence shorter than this between two voiced runs
+            is bridged, so they are one phrase. Raise it to merge phrases
+            split by breaths, lower it to split lines sung close together
+        min_phrase_seconds: A phrase shorter than this, after bridging, is
+            dropped as a click or breath
+        floor_db: The level, in dBFS of a 20 ms frame, a frame must reach to
+            count as voiced. Unset, it is the track's 95th-percentile frame
+            less 35 dB, never below -60 dBFS
+        centre: Weight a stereo file to its centre, where a lead vocal is
+            mixed, cancelling what is panned to the sides. False uses the
+            band energy of the downmix
+        sample_rate: The rate of a raw waveform; a file or result carries
+            its own
+
+    Returns:
+        {phrases: [{start, end}], duration_seconds, method, warnings}: the
+        phrases in time order, in seconds rounded to 0.01. `method` is
+        "centre" for the centre-weighted power of a stereo file, "band" for
+        the band energy of a mono one, of `centre=false`, or of stereo
+        channels that are the same
+    """
+    from .. import dsp
+    from ..events import emit_warning
+    from ..task_domains import check_arguments, real_number
+    from .audio_utils import waveform_and_rate
+    from .voice_attribution import voiced_floor_dbfs
+
+    if audio is None:
+        raise ValueError(f"{COMMAND} needs 'audio' - the song or its vocal stem")
+    problems = phrases_problems(centre=centre)
+    if problems:
+        raise ValueError(problems[0][1])
+    values = {
+        name: real_number(value, name, COMMAND, required=required)
+        for name, value, required in (
+            ("min_gap_seconds", min_gap_seconds, True),
+            ("min_phrase_seconds", min_phrase_seconds, True),
+            ("floor_db", floor_db, False),
+            ("sample_rate", sample_rate, False),
+        )
+    }
+    # the registration's domains, again for a direct call
+    check_arguments(COMMAND, **values)
+
+    wave, rate = waveform_and_rate(audio, values["sample_rate"], COMMAND)
+    wave = numpy.atleast_2d(numpy.asarray(wave))
+    duration = wave.shape[-1] / rate
+    warnings = []
+    if wave.shape[0] == 1:
+        warnings.append(
+            f"{COMMAND}: the audio is mono, so there is no centre to weight - "
+            'the phrases come from its band energy (method "band")'
+        )
+
+    power, frame, method, _ = voiced_power(wave, rate, centre=bool(centre))
+    level = numpy.sqrt(power)
+    loudest = dsp.dbfs(float(level.max()), floor=-numpy.inf) if len(level) else None
+    near_silent = values["floor_db"] is None and (
+        loudest is None or loudest < NEAR_SILENT_DBFS
+    )
+    phrases = []
+    if not near_silent:
+        floor = values["floor_db"]
+        if floor is None:
+            floor = voiced_floor_dbfs(level)
+        voiced = level >= 10 ** (floor / 20)
+        frame_seconds = frame / rate
+        runs = voiced_runs(
+            voiced,
+            int(numpy.ceil(values["min_gap_seconds"] / frame_seconds - 1e-9)),
+            int(numpy.ceil(values["min_phrase_seconds"] / frame_seconds - 1e-9)),
+        )
+        phrases = [
+            {
+                "start": round(start * frame_seconds, TIME_PLACES),
+                "end": round(min(end * frame_seconds, duration), TIME_PLACES),
+            }
+            for start, end in runs
+        ]
+
+    if not phrases:
+        reason = (
+            f"the audio is near-silent (its loudest frame is under "
+            f"{NEAR_SILENT_DBFS:g} dBFS in the voice band)"
+            if near_silent
+            else "no frame rose above the voiced floor for long enough"
+        )
+        if method == "centre":
+            reason += (
+                ", or all of it is panned away from the centre - "
+                "'centre': false listens to the whole downmix"
+            )
+        warnings.append(
+            f"{COMMAND}: no phrases found - {reason}. Check the audio, or set "
+            "'floor_db' lower"
+        )
+    elif (
+        len(phrases) == 1
+        and duration > 0
+        and phrases[0]["end"] - phrases[0]["start"] > ONE_PHRASE_SHARE * duration
+    ):
+        warnings.append(
+            f"{COMMAND}: one phrase covers more than {ONE_PHRASE_SHARE:.0%} of "
+            "the track - probably a dense mix whose instruments fill the voice "
+            "band. Feed it the vocal stem (separate_stems, then "
+            "previous_result:<step>.vocals)"
+        )
+
+    for message in warnings:
+        emit_warning(message, kind=COMMAND, command=COMMAND)
+    return {
+        "phrases": phrases,
+        "duration_seconds": round(duration, TIME_PLACES),
+        "method": method,
+        "warnings": warnings,
+    }
+
+
+@register_command(
+    COMMAND,
+    implementation="dw.tasks.phrases.analyze_phrases",
+    returns="json",
+    domains={
+        "min_gap_seconds": NON_NEGATIVE,
+        "min_phrase_seconds": POSITIVE,
+        "floor_db": NON_POSITIVE,
+        "sample_rate": POSITIVE,
+    },
+    whole_numbers=("sample_rate",),
+    static_check=phrases_errors,
+)
+def _handle_analyze_phrases(task, arguments, previous_pipelines):
+    """Find when a song's sung phrases start and stop, from voiced energy"""
+    logger.debug("Analyzing phrases")
+    return analyze_phrases(**arguments)
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index f2d4edad..d635c11b 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -19,6 +19,7 @@
 from ..task_domains import FINITE, coerce_arguments
 from . import beats  # noqa: F401 - registers analyze_beats
 from . import measure_sync  # noqa: F401 - registers measure_sync
+from . import phrases  # noqa: F401 - registers analyze_phrases
 from . import cuts  # noqa: F401 - registers plan_cuts
 from . import trim  # noqa: F401 - registers trim_video
 
diff --git a/tests/test_analyze_phrases.py b/tests/test_analyze_phrases.py
new file mode 100644
index 00000000..84e03f71
--- /dev/null
+++ b/tests/test_analyze_phrases.py
@@ -0,0 +1,227 @@
+"""analyze_phrases: sung phrases from voiced energy, centre-weighted (#1095)."""
+
+import numpy
+import pytest
+import soundfile
+
+import dw.tasks.task  # noqa: F401 - registers every command, as validation does
+from dw.task_domains import task_argument_errors
+from dw.task_problems import phrases_errors
+from dw.tasks.phrases import analyze_phrases, voiced_runs
+from dw.workflow import Workflow
+
+SR = 22050
+BURSTS = [(0.5, 1.5), (2.0, 3.2), (4.0, 5.5)]
+SECONDS = 6.0
+
+
+def tone_bursts(bursts=BURSTS, seconds=SECONDS, level=0.3):
+    """A 440 Hz tone, on during each (start, end) and silent between."""
+    t = numpy.arange(int(seconds * SR)) / SR
+    tone = numpy.zeros_like(t)
+    for start, end in bursts:
+        on = (t >= start) & (t < end)
+        tone[on] = level * numpy.sin(2 * numpy.pi * 440 * t[on])
+    return tone
+
+
+def noise(seconds=SECONDS, level=0.3, seed=0):
+    return level * numpy.random.default_rng(seed).standard_normal(int(seconds * SR))
+
+
+def run(wave, **kwargs):
+    return analyze_phrases(
+        numpy.asarray(wave, dtype=numpy.float32), sample_rate=SR, **kwargs
+    )
+
+
+def spans(result):
+    return [(p["start"], p["end"]) for p in result["phrases"]]
+
+
+def assert_found(result, bursts=BURSTS):
+    found = spans(result)
+    assert len(found) == len(bursts), found
+    for (start, end), (want_start, want_end) in zip(found, bursts):
+        assert start == pytest.approx(want_start, abs=0.05)
+        assert end == pytest.approx(want_end, abs=0.05)
+
+
+class TestCentre:
+    def test_centred_bursts_under_hard_panned_noise_are_found(self):
+        tone = tone_bursts()
+        result = run(numpy.stack([tone + noise(), tone]))
+        assert result["method"] == "centre"
+        assert_found(result)
+        assert result["warnings"] == []
+        assert result["duration_seconds"] == SECONDS
+
+    def test_noise_panned_to_either_side_cancels(self):
+        tone = tone_bursts()
+        result = run(numpy.stack([tone, tone + noise(seed=3)]))
+        assert_found(result)
+
+    def test_bursts_panned_hard_to_one_side_are_not_centre(self):
+        tone = tone_bursts()
+        hard_left = numpy.stack([tone, numpy.zeros_like(tone)])
+        result = run(hard_left)
+        assert result["method"] == "centre"
+        assert result["phrases"] == []
+        assert any("no phrases" in w for w in result["warnings"])
+        assert any("'centre': false" in w for w in result["warnings"])
+
+    def test_bursts_panned_hard_to_one_side_are_found_without_centre(self):
+        tone = tone_bursts()
+        result = run(numpy.stack([tone, numpy.zeros_like(tone)]), centre=False)
+        assert result["method"] == "band"
+        assert_found(result)
+        assert result["warnings"] == []
+
+    def test_identical_channels_fall_back_to_band_without_a_warning(self):
+        tone = tone_bursts()
+        result = run(numpy.stack([tone, tone]))
+        assert result["method"] == "band"
+        assert_found(result)
+        assert result["warnings"] == []
+
+
+class TestBand:
+    def test_mono_input_is_band_with_a_warning(self):
+        result = run(tone_bursts()[None, :])
+        assert result["method"] == "band"
+        assert_found(result)
+        (warning,) = result["warnings"]
+        assert "mono" in warning
+
+    def test_a_one_dimensional_waveform_is_mono(self):
+        result = run(tone_bursts())
+        assert result["method"] == "band"
+        assert any("mono" in w for w in result["warnings"])
+
+    def test_a_dense_track_is_one_phrase_with_a_warning(self):
+        wave = noise()
+        result = run(numpy.stack([wave, wave]))
+        assert len(result["phrases"]) == 1
+        assert any("stems" in w and "90%" in w for w in result["warnings"])
+
+
+class TestSilence:
+    def test_silence_gives_no_phrases_and_a_warning(self):
+        result = run(numpy.zeros((2, int(3 * SR))))
+        assert result["phrases"] == []
+        assert result["duration_seconds"] == 3.0
+        assert any("no phrases" in w for w in result["warnings"])
+
+    def test_near_silent_hiss_gives_no_phrases(self):
+        hiss = noise(level=1e-4)
+        result = run(numpy.stack([hiss, noise(level=1e-4, seed=1)]))
+        assert result["phrases"] == []
+        assert any("near-silent" in w for w in result["warnings"])
+
+    def test_a_given_floor_skips_the_near_silence_gate(self):
+        quiet = tone_bursts(level=1e-3)
+        result = run(quiet[None, :], floor_db=-75)
+        assert_found(result)
+
+
+class TestPhraseRules:
+    def test_a_short_gap_is_bridged(self):
+        result = run(tone_bursts([(0.5, 1.5), (1.7, 2.5)], seconds=3.0)[None, :])
+        assert spans(result) == [pytest.approx((0.5, 2.5), abs=0.05)]
+
+    def test_a_gap_at_min_gap_splits(self):
+        result = run(
+            tone_bursts([(0.5, 1.5), (1.7, 2.5)], seconds=3.0)[None, :],
+            min_gap_seconds=0.1,
+        )
+        assert len(result["phrases"]) == 2
+
+    def test_a_short_run_is_dropped(self):
+        result = run(tone_bursts([(0.5, 1.5), (2.2, 2.35)], seconds=3.0)[None, :])
+        assert spans(result) == [pytest.approx((0.5, 1.5), abs=0.05)]
+
+    def test_phrases_are_ordered_and_inside_the_track(self):
+        result = run(tone_bursts([(0.0, 0.8), (1.5, 3.0)], seconds=3.0)[None, :])
+        found = spans(result)
+        assert found == sorted(found)
+        assert all(0 <= s < e <= result["duration_seconds"] for s, e in found)
+        assert all(a[1] <= b[0] for a, b in zip(found, found[1:]))
+
+    def test_voiced_runs_bridges_then_drops(self):
+        voiced = numpy.array([1, 1, 0, 1, 1, 0, 0, 0, 1, 0, 0, 0, 1, 1, 1], dtype=bool)
+        assert voiced_runs(voiced, min_gap_frames=2, min_phrase_frames=2) == [
+            (0, 5),
+            (12, 15),
+        ]
+
+
+class TestFromAFile:
+    def test_a_stereo_wav_keeps_its_channels(self, tmp_path):
+        tone = tone_bursts()
+        path = tmp_path / "song.wav"
+        soundfile.write(path, numpy.stack([tone + noise(), tone]).T, SR)
+        result = analyze_phrases(str(path))
+        assert result["method"] == "centre"
+        assert_found(result)
+
+
+class TestRefusals:
+    def errors(self, arguments):
+        step = {
+            "name": "phrases",
+            "task": {"command": "analyze_phrases", "arguments": arguments},
+        }
+        return task_argument_errors({"id": "p", "steps": [step]})
+
+    @pytest.mark.parametrize(
+        "name, value",
+        [
+            ("min_gap_seconds", -1),
+            ("min_phrase_seconds", 0),
+            ("min_phrase_seconds", -0.5),
+            ("floor_db", 6),
+        ],
+    )
+    def test_an_out_of_range_value_is_refused_at_its_path(self, name, value):
+        errors = self.errors({"audio": "asset:song.wav", name: value})
+        assert [e["path"] for e in errors] == [f"steps[0].task.arguments.{name}"]
+
+    def test_a_zero_gap_is_allowed(self):
+        assert self.errors({"audio": "asset:song.wav", "min_gap_seconds": 0}) == []
+
+    def test_a_string_centre_is_refused(self):
+        assert phrases_errors({"centre": "false"})[0][0] == "centre"
+        errors = self.errors({"audio": "asset:song.wav", "centre": "false"})
+        assert [e["path"] for e in errors] == ["steps[0].task.arguments.centre"]
+
+    def test_a_referenced_centre_is_left_to_the_run(self):
+        assert phrases_errors({"centre": "variable:centre"}) == []
+
+    def test_the_run_refuses_a_string_centre(self):
+        with pytest.raises(ValueError, match="centre"):
+            run(tone_bursts()[None, :], centre="false")
+
+    def test_the_run_refuses_a_negative_gap(self):
+        with pytest.raises(ValueError, match="min_gap_seconds"):
+            run(tone_bursts()[None, :], min_gap_seconds=-1)
+
+    def test_validate_refuses_a_missing_audio_and_a_negative_gap(self):
+        workflow = Workflow(
+            {
+                "id": "p",
+                "steps": [
+                    {
+                        "name": "phrases",
+                        "task": {
+                            "command": "analyze_phrases",
+                            "arguments": {"min_gap_seconds": -1},
+                        },
+                    }
+                ],
+            },
+            "outputs",
+            None,
+        )
+        messages = " ".join(e["message"] for e in workflow.validation_errors())
+        assert "audio" in messages
+        assert "min_gap_seconds" in messages
diff --git a/tests/test_task_discovery.py b/tests/test_task_discovery.py
index 11308ba0..7fb15b11 100644
--- a/tests/test_task_discovery.py
+++ b/tests/test_task_discovery.py
@@ -203,3 +203,29 @@ def test_analyze_beats_is_registered_as_a_json_answer(self):
         assert info["implementation"] == "dw.tasks.beats.analyze_beats"
         assert info["returns"] == "json"
         assert "assessment" not in info
+
+
+class TestAnalyzePhrasesRegistration:
+    def test_analyze_phrases_is_registered_as_a_json_answer(self):
+        from dw.tasks.task import task_command_info
+
+        info = task_command_info("analyze_phrases")
+        assert info["implementation"] == "dw.tasks.phrases.analyze_phrases"
+        assert info["returns"] == "json"
+        assert "assessment" not in info
+
+    def test_its_arguments_are_described(self):
+        by_name = {p["name"]: p for p in describe_task("analyze_phrases")["parameters"]}
+        assert set(by_name) >= {
+            "audio",
+            "min_gap_seconds",
+            "min_phrase_seconds",
+            "floor_db",
+            "centre",
+        }
+        assert by_name["audio"]["required"]
+        assert by_name["min_gap_seconds"]["default"] == 0.35
+        assert by_name["min_phrase_seconds"]["default"] == 0.3
+        assert by_name["floor_db"]["default"] is None
+        assert by_name["centre"]["default"] is True
+        assert "bridged" in by_name["min_gap_seconds"]["description"]
diff --git a/tests/test_task_domains.py b/tests/test_task_domains.py
index bbd5249e..a9c68acc 100644
--- a/tests/test_task_domains.py
+++ b/tests/test_task_domains.py
@@ -206,6 +206,24 @@ def test_a_referenced_value_is_not_this_passs_business(self):
             == []
         )
 
+    def test_analyze_phrases_declares_its_ranges(self):
+        from dw.task_domains import TASK_ARGUMENT_DOMAINS
+
+        assert dict(TASK_ARGUMENT_DOMAINS["analyze_phrases"]) == {
+            "min_gap_seconds": "non_negative",
+            "min_phrase_seconds": "positive",
+            "floor_db": "non_positive",
+            "sample_rate": "positive",
+        }
+        errors = errors_for(
+            "analyze_phrases",
+            {"audio": "a.wav", "min_gap_seconds": -1, "min_phrase_seconds": 0},
+        )
+        assert {e["path"].rsplit(".", 1)[-1] for e in errors} == {
+            "min_gap_seconds",
+            "min_phrase_seconds",
+        }
+
     def test_an_untouched_command_is_left_alone(self):
         assert errors_for("compose_text", {"parts": ["a"]}) == []
 
diff --git a/tests/test_task_registry_rules.py b/tests/test_task_registry_rules.py
index 5396c853..7052f5e1 100644
--- a/tests/test_task_registry_rules.py
+++ b/tests/test_task_registry_rules.py
@@ -71,6 +71,7 @@ def test_a_table_read_first_holds_the_self_registering_commands():
         "from dw.task_domains import TASK_ARGUMENT_DOMAINS, TASK_STATIC_CHECKS\n"
         "assert 'analyze_beats' in TASK_STATIC_CHECKS\n"
         "assert 'plan_cuts' in TASK_STATIC_CHECKS\n"
+        "assert 'analyze_phrases' in TASK_STATIC_CHECKS\n"
         "assert 'trim_video' in TASK_ARGUMENT_DOMAINS\n"
     )
     subprocess.run([sys.executable, "-c", script], check=True)

From 9c49e16aac2bddb49f928e1e07cc0ae9735e4f2d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 17:14:34 -0500
Subject: [PATCH 060/125] feat(templates): #1080 - restore-colorize cost from a
 lem run; ic-colorization proven

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 loras/ltx-2.5/ic-colorization.json             | 9 ++++++++-
 tests/test_catalog_structure.py                | 5 ++++-
 workflows/templates/ltx2/restore-colorize.json | 3 +++
 3 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/loras/ltx-2.5/ic-colorization.json b/loras/ltx-2.5/ic-colorization.json
index 87f29a1f..779b15db 100644
--- a/loras/ltx-2.5/ic-colorization.json
+++ b/loras/ltx-2.5/ic-colorization.json
@@ -16,7 +16,14 @@
       1.0
     ]
   },
-  "status": "trial",
+  "status": "proven",
+  "evidence": [
+    {
+      "job": "b70c30a5e8e4",
+      "issue": 1064,
+      "note": "templates/ltx2/restore-colorize on lem (RTX 3090, uint4 SDNQ) at 960x544x121: natural colour on a greyscale street clip, subject, framing and motion kept, 121 frames at the source's 24 fps; a portrait 384x544x97 run (c01a0fc6df48) came back at source size with no band or colour from the letterbox padding; 2.5 min including a cold load"
+    }
+  ],
   "license": "other",
   "tags": [
     "restore",
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 88376880..2e67478d 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -511,7 +511,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Then to 12_250 for the `minimax/face-repair` template (#1092, stage #1099,
 # 2026-10-31), measured at 12_201: one new entry, the catalog's only face
 # repair that holds an H3 take's soundtrack, with its cost block.
-COMPACT_BUDGET = 12_250
+# Then to 12_400 for the `ltx2/restore-colorize` template (#1064, stage #1080,
+# 2026-10-31), measured at 12_357: one new entry, the catalog's only
+# colourisation of existing footage, with its cost block.
+COMPACT_BUDGET = 12_400
 FILTERED_BUDGET = 1_500
 
 
diff --git a/workflows/templates/ltx2/restore-colorize.json b/workflows/templates/ltx2/restore-colorize.json
index f25a8370..02d4f848 100644
--- a/workflows/templates/ltx2/restore-colorize.json
+++ b/workflows/templates/ltx2/restore-colorize.json
@@ -5,6 +5,9 @@
     "traits": [
         "needs-input-media"
     ],
+    "cost": [
+        {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 2.5}
+    ],
     "cost_drivers": [
         "num_frames",
         "width",

From 4f9b3a1903564de0afd7ed3e6ec8ebab32ff490c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 17:19:20 -0500
Subject: [PATCH 061/125] docs(proposals): #1092 - H3 face repair close-out
 record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/h3-face-repair-complete.md       | 142 ++++++++++++++++++
 docs/proposals/todo.md                        |  10 ++
 2 files changed, 152 insertions(+)
 create mode 100644 docs/proposals/complete/h3-face-repair-complete.md

diff --git a/docs/proposals/complete/h3-face-repair-complete.md b/docs/proposals/complete/h3-face-repair-complete.md
new file mode 100644
index 00000000..0d0297d3
--- /dev/null
+++ b/docs/proposals/complete/h3-face-repair-complete.md
@@ -0,0 +1,142 @@
+# `minimax/face-repair`: low-strength H3 redraw of the tracked face crop, audio held (#1092)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 approved 2026-10-31 under Don's delegation, with Q1–Q4
+at the plan's defaults; plan v2 folded those answers in with no scope
+change. Three stages, #1097, #1098 and #1099, all verified 2026-10-31. It
+is the H3 sibling of `face-repair-complete.md` (#599), whose
+`crop_face_track` and `paste_face_track` tasks it reuses, and its middle
+step is the H3 video-to-video with the audio held from
+`h3-audio-hold-refine-complete.md` / `h3-regional-edit-complete.md` (#1062).
+
+The concept came from r34vtraining/Longshot_Studio (its Face refine,
+assessed 2026-10-31). That repo has **no license**, so nothing was copied:
+the close-up prompt, the gate and the strength are ours, tuned on lem.
+
+## The report
+
+The only face pass was LTX (`templates/ltx2/face-repair`). An LTX redraw of
+an H3 talking face can't see the H3 audio, so it could soften the lip sync
+that made the take worth keeping. H3 with the shot's own track held is
+conditioned on the sound that drove the mouth.
+
+## Verdict
+
+**Build, probe first.** Most of the mechanism existed already, so the open
+question was whether H3 beats LTX at this job. Stage A answered it on GPU
+with no code before anything was built (the #664 lesson: an H3 refine
+template that failed its quality gate and was reverted).
+
+## What the plan found against the issue
+
+- **Audio alignment.** `crop_face_track` pads the crops to the grid with
+  reflected frames at both ends, and `hold_audio` starts at sample 0, so
+  reusing the task unchanged would have the sound lead the mouth by up to
+  8 frames. Fix: `crops` carries the source track, silence-padded by
+  `pad_before` / `pad_after` frames, so `hold_audio:
+  previous_result:crop.crops` lines up frame for frame.
+- **Length and rate.** H3 takes 124–345 frames at 24 fps. The crop step
+  refuses anything else before a pipeline loads.
+- **Strength scale.** The issue's ComfyUI "denoise 0.2/0.3/0.4" is
+  unshifted. At `video_shift` 6 it is about `refine_strength`
+  0.6 / 0.72 / 0.8 in dw (s = 6u / (1 + 5u)).
+- **Sync metric.** `measure_sync` compares two audio tracks, and the
+  pasted result's audio *is* the source's, so it always reads 0. Mouth sync
+  is judged on frames (`compare_outputs` face grids, `get_output_frames`).
+- **Template shape.** A separate template, not a `model` switch on the LTX
+  one: the pipeline block differs wholesale, and the LTX template has 10+
+  consumers.
+
+## Decisions
+
+- **Q1–Q4 (approval, 2026-10-31):** silence-padded track at both ends (tail
+  only as a fallback); the probe picks one mode; the stage A session picks
+  the takes; Don owns the gate.
+- **Gate ruling on the probe (Don, 2026-10-31):** build, **t2va at
+  `refine_strength` 0.6**.
+  - ref2va with a cast picture was only marginally better (face SSIM 0.732
+    vs 0.708) at about 4x the denoise time, so it doesn't ship. The
+    template description says it is a slightly better, slower option.
+  - 0.72 drifts identity; 0.8 distorts frames.
+  - **Face gate 0.2 / 0.3** in the H3 template only. The task defaults and
+    the LTX template's 0.03 / 0.06 are unchanged.
+
+## What was built
+
+**Stage A, #1097: the probe (GPU, no code).** Workspace `probe-1092` on
+lem, seed 1092, two small-face takes from `KnownIssuesRestorePointHD`
+(`tag`, the man says "We have hope."; `cold_open`, the same man silent).
+Arms: LTX `ltx2/face-repair` at strength 2; H3 t2va refine at 0.6 / 0.72 /
+0.8; ref2va at 0.6 with `asset:cast/pat.jpg` as `<Picture 1>`; the #1062
+regional edit with a static face-box mask at 0.85. Result:
+- H3 (both modes) keeps the man's face; LTX at strength 2 replaces him with
+  a younger, rounder man with a smaller moustache, on both takes.
+- H3 mouth sync is as good as LTX's.
+- The masked full-frame regional edit was the worst arm (too few patch
+  cells on a small face, as the plan expected).
+
+**Stage B, #1098: `crop_face_track` audio and window** (`db71fc1a`, merged
+as `3d8bc206`).
+- When the clip has sound, `crops` carries it: `pad_before` frames of
+  silence, the clip's sound, `pad_after` frames of silence, with each
+  boundary rounded from frame times so the track is exactly
+  `crop_frames / fps` long (`padded_audio`, `crop_soundtrack` in
+  `dw/tasks/face_track.py`). A silent clip gives `crops` with no audio and
+  no warning.
+- Optional `min_frames`, `max_frames` and `fps` (±0.01). The window is
+  checked against the **padded** crop count, and the message names both
+  counts. `min_frames` ≤ `max_frames` is a validate-time problem in
+  `dw/task_problems.py`.
+- `docs/TASKS.md` documents the three arguments, the padded soundtrack, and
+  that the grid defaults are LTX's, with H3's 17/5/32.
+- The LTX template's `crops` intermediate now also carries sound; its
+  final output and step-cache keys are unchanged.
+
+**Stage C, #1099: template and skill** (`develop` @ `b110e7cd`).
+- `workflows/templates/minimax/face-repair.json`, shape `shot`, traits
+  `needs-input-media`, `has-audio`: `crop` (17/5/32, window 124–345,
+  fps 24, gate 0.2/0.3) → `refine` (H3 t2va, `refine_strength` 0.6,
+  `source_video` and `hold_audio` both `previous_result:crop.crops`, our
+  own close-up prompt) → `pasted` (`paste_face_track`, final).
+- Cost measured on lem: 2.2 min (job 38da34a526e1, 127 s from a fresh
+  load).
+- A minimax README row, a `TEMPLATE_PIPELINE_KEYS` row, `COMPACT_BUDGET`
+  raised to 12_250 with a dated line, and one `minimax-h3` skill line
+  within its byte cap.
+
+## Deviations from the plan
+
+- **The probe had to open the face gate.** These faces are about 0.087 of
+  the frame, so at the LTX gate (0.03/0.06) every arm's paste was a no-op
+  (PSNR 37.5 vs the source). That became Don's 0.2/0.3 ruling.
+- **The probe's takes were 124 frames**, not trimmed to 17n+5 by hand;
+  124 is already on the grid.
+- **The padded-head risk (Q1) was checked on a built clip.** Every
+  small-face take on lem is exactly 124 frames, so the tester appended one
+  frame to make 125 (padded to 141 crops, job a4ad2c6752a7). The mouth on
+  frames 0–6 matched the source and the unpadded arm frame for frame, so
+  tail-only padding was **not** needed. Not a pass condition, but seen in
+  both arms: the head frames' brow reads slightly more furrowed and the
+  skin slightly redder than the source's. Identity holds.
+
+## Bounces per stage
+
+None. Each of #1097, #1098 and #1099 passed its first verify, and both
+code stages passed architecture review.
+
+## Cost
+
+The stage comments name no `usage:` figures, so per-stage spend isn't
+recorded here. The one figure on file: the probe spent about $6 against its
+$1.5–2.5 estimate, mostly on reruns after the gated no-ops.
+
+## Deferred and left open
+
+- **ref2va mode** (cast picture as `<Picture 1>`). Back if a take loses
+  identity under t2va at 0.6.
+- **Tail-only padding.** Back if a padded run shows the head silence
+  closing the mouth on the first real frames.
+- **Takes under 124 frames** can't use this template; they use
+  `ltx2/face-repair`.
+- **Multi-face shots**, as in #599: `crop_face_track` tracks one face.
+- **Composition with #1065** (the H3 refiner LoRA) was not tried.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index b00e214f..a34f39f8 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -409,6 +409,16 @@ remaining deferred fix is recorded in
   pinned to it with `first-and-last-frame`. Record, including the deferred
   engine chain joins and their reopen trigger:
   `complete/script-to-video-joins-complete.md`.
+- **H3 face repair, `templates/minimax/face-repair`** (#1092, stages
+  #1097-#1099), shipped 2026-10-31. A GPU probe found H3 t2va at
+  `refine_strength` 0.6 keeps a small face's identity where LTX
+  `ltx2/face-repair` replaces it, with mouth sync as good. `crop_face_track`
+  now carries the clip's soundtrack on `crops`, silence-padded to the grid,
+  and takes optional `min_frames` / `max_frames` / `fps` refusals; the
+  template crops at 17/5/32 with a 0.2/0.3 gate and refines with the
+  crops' own audio held. Record, including what was deferred (ref2va,
+  tail-only padding, with their triggers):
+  `complete/h3-face-repair-complete.md`.
 
 ## Declined
 

From bda5d3ae7c685b13991e9994d4ceb6fd3ca14c47 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 17:27:56 -0500
Subject: [PATCH 062/125] feat(tasks): #1105 - plan_cuts takes analyze_phrases'
 result

A {phrases} transcript is timing with no text: without lyrics a line per
phrase with lyric null; with lyrics of the same count, one to one in
order; otherwise a warning naming both counts and which way to move
analyze_phrases' min_gap_seconds, then the even spread. No suspect
filtering or word splitting on phrases. The song length falls back to
the phrase result's duration_seconds. Docs: TASKS.md, minimax README,
music-video-cuts description, minimax-h3 cuts reference (chain fixed).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                                 |   8 +-
 dw/task_problems.py                           |   8 +
 dw/tasks/cuts.py                              | 136 ++++++++++--
 .../dw/skills/minimax-h3/references/cuts.md   |  22 +-
 tests/test_plan_cuts_phrases.py               | 193 ++++++++++++++++++
 workflows/templates/minimax/README.md         |  20 ++
 .../templates/minimax/music-video-cuts.json   |   2 +-
 7 files changed, 369 insertions(+), 20 deletions(-)
 create mode 100644 tests/test_plan_cuts_phrases.py

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 3a42393c..5bde7ff0 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -2132,12 +2132,12 @@ the list rendered. A transcript chunk `transcribe_audio` marked `suspect` `no_wo
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-| `transcript` | Yes | `transcribe_audio`'s result with `timestamps` set (`"segment"` or `"word"`): a `{text, chunks}` dict of `{start, end, text}` chunks in seconds. A null `end` runs to the next chunk's start, or the song's end. Its `result` must be `application/json` |
-| `lyrics` | No | The song's own lyrics, one line per line with a blank line or a lone section tag (`[Chorus]`) between stanzas, or a list of lines. The shots carry these lines verbatim and in order; the transcript only times them. `null` or `""` means none: the transcript's text is used |
+| `transcript` | Yes | `transcribe_audio`'s result with `timestamps` set (`"segment"` or `"word"`): a `{text, chunks}` dict of `{start, end, text}` chunks in seconds. A null `end` runs to the next chunk's start, or the song's end. Its `result` must be `application/json`. Or an [`analyze_phrases`](#analyze_phrases) result (recognised by its `phrases` key), for a song Whisper can't time: each phrase is one line, and suspect filtering and word alignment don't apply. Without `lyrics` a phrase is a line with no lyric (shot `lyric: null`, kind vocal), and `segment_by` `line`, `stanza` (phrases a silence of at least `min_gap_seconds` apart are grouped) and `beat` all work. With `lyrics` of as many lines as phrases they map one to one, in order. With a different count a warning names both counts and the knob: raise `analyze_phrases`' `min_gap_seconds` when there are more phrases than lyric lines (it bridges more pauses), lower it when fewer; the lines are then spread evenly from the first phrase's start to the last phrase's end, never paired silently. A long phrase split into pieces gives every piece its whole lyric |
+| `lyrics` | No | The song's own lyrics, one line per line with a blank line or a lone section tag (`[Chorus]`) between stanzas, or a list of lines. The shots carry these lines verbatim and in order; the transcript only times them (an `analyze_phrases` transcript: one line per phrase, see `transcript`). `null` or `""` means none: the transcript's text is used (a phrase result has none: `lyric` is `null`) |
 | `beats` | For `segment_by: "beat"` | `analyze_beats`' result, or a list of beat times in seconds |
 | `segment_by` | No | `line` (default), `stanza` or `beat` |
 | `fps` | No | Frames per second the shots are counted in (default `24`) |
-| `duration_s` | No | The song's length; `analyze_beats`' `duration_seconds` when `beats` is that whole dict, else the transcript's last end (with a warning). `"beats": "previous_result:beats"` passes only the result's `beats` list - the engine takes the key an argument is named for - so name the length too: `"duration_s": "previous_result:beats.duration_seconds"` |
+| `duration_s` | No | The song's length; `analyze_beats`' `duration_seconds` when `beats` is that whole dict, else a phrase result's `duration_seconds`, else the transcript's last end (with a warning). `"beats": "previous_result:beats"` passes only the result's `beats` list - the engine takes the key an argument is named for - so name the length too: `"duration_s": "previous_result:beats.duration_seconds"` |
 | `min_scene_s` | No | The shortest a shot may be (default `1.0`) |
 | `max_scene_s` | No | The longest a shot may be (default none) |
 | `vocal_tail_s` | No | Seconds a sung shot holds past its last word (default `0`) |
@@ -2207,7 +2207,7 @@ on) and `lyrics` with no sung lines.
 [music-video-cuts.json](../workflows/templates/minimax/music-video-cuts.json)
 chains `separate_stems`, `transcribe_audio` (of the vocal stem, so an instrumental intro is not folded into the first word), `analyze_beats` (of the full mix) and `plan_cuts`, passing H3's
 grid (`17`, `5`, `124`, `345`) and a `lead_s` variable (default `0.5`, 12
-frames at 24 fps). Its shots are what
+frames at 24 fps). When Whisper can't time the words (a non-English verse, a hallucinated transcript, wordless vocals), swap the `transcribe` step for an `analyze_phrases` step on `previous_result:stems.vocals`, keep `plan_cuts`' `transcript` on that step and pass `lyrics`, one line per sung phrase; the default chain is unchanged. Its shots are what
 [music-video.json](../workflows/templates/minimax/music-video.json) renders:
 the agent writes a prompt per shot, drops `lyric` and `kind`, and passes the
 list as `shots`.
diff --git a/dw/task_problems.py b/dw/task_problems.py
index 7e64c9a7..1025b07e 100644
--- a/dw/task_problems.py
+++ b/dw/task_problems.py
@@ -397,6 +397,14 @@ def transcript_problem(transcript):
             "result's content_type application/json"
         )
     if isinstance(transcript, dict):
+        if "phrases" in transcript and "chunks" not in transcript:
+            # analyze_phrases' result: timing only, no text (#1095)
+            if not isinstance(transcript["phrases"], list):
+                return (
+                    "plan_cuts's 'transcript' has a 'phrases' key that is not a "
+                    "list - pass analyze_phrases' result as it is"
+                )
+            return None
         chunks = transcript.get("chunks")
         if not isinstance(chunks, list):
             return (
diff --git a/dw/tasks/cuts.py b/dw/tasks/cuts.py
index 9f70c857..a361f290 100644
--- a/dw/tasks/cuts.py
+++ b/dw/tasks/cuts.py
@@ -383,21 +383,98 @@ def _transcript_lines(chunks, stanza_gap):
     return lines
 
 
+def _is_phrases(transcript):
+    """Whether this is analyze_phrases' result (#1095): timing with no text,
+    told from a transcript by its 'phrases' key."""
+    return (
+        isinstance(transcript, dict)
+        and "phrases" in transcript
+        and "chunks" not in transcript
+    )
+
+
+def _phrases(transcript):
+    """[{start, end, text}] in seconds, ascending - an analyze_phrases
+    result's phrases, each with no text. A phrase is never suspect."""
+    problem = transcript_problem(transcript)
+    if problem:
+        raise ValueError(problem)
+    parsed = []
+    for index, phrase in enumerate(transcript["phrases"]):
+        if not isinstance(phrase, dict):
+            raise ValueError(
+                f"{COMMAND}: phrase {index} is not a {{start, end}} object"
+            )
+        start = _number(phrase.get("start"), f"phrases[{index}].start", required=True)
+        end = _number(phrase.get("end"), f"phrases[{index}].end", required=True)
+        parsed.append({"start": start, "end": max(end, start), "text": ""})
+    parsed.sort(key=lambda phrase: phrase["start"])
+    return parsed
+
+
+def _phrase_lines(phrases, lyrics, duration, stanza_gap, warnings):
+    """[{start, end, text, stanza, tokens}] from analyze_phrases' phrases.
+    Without lyrics a line per phrase, with no text, and a silence of at least
+    stanza_gap starts a stanza. With lyrics whose lines are as many as the
+    phrases, line n is phrase n; otherwise the counts are warned about, with
+    the analyze_phrases knob to turn, and the lines spread evenly from the
+    first phrase to the last - never paired. A phrase has no word times, so
+    a split piece of one keeps its whole lyric."""
+    if lyrics is None:
+        lines, stanza = [], 0
+        for phrase in phrases:
+            if lines and phrase["start"] - lines[-1]["end"] >= stanza_gap:
+                stanza += 1
+            lines.append(dict(phrase, stanza=stanza, tokens=None))
+        return lines
+    if len(lyrics) == len(phrases):
+        return [
+            dict(phrase, text=text, stanza=stanza, tokens=None)
+            for phrase, (text, stanza) in zip(phrases, lyrics)
+        ]
+    if len(phrases) > len(lyrics):
+        knob = "raise analyze_phrases' 'min_gap_seconds' to bridge more pauses"
+    else:
+        knob = "lower analyze_phrases' 'min_gap_seconds' to split at shorter pauses"
+    low = phrases[0]["start"] if phrases else 0.0
+    high = phrases[-1]["end"] if phrases else duration
+    warnings.append(
+        f"{COMMAND}: the lyrics have {len(lyrics)} line(s) and analyze_phrases "
+        f"found {len(phrases)} phrase(s) - the lines are spread evenly over "
+        f"{low:.2f}-{high:.2f} s, not paired with the phrases; {knob}, so the "
+        "counts match"
+    )
+    step = (high - low) / len(lyrics)
+    return [
+        {
+            "start": low + index * step,
+            "end": low + (index + 1) * step,
+            "text": text,
+            "stanza": stanza,
+            "tokens": None,
+        }
+        for index, (text, stanza) in enumerate(lyrics)
+    ]
+
+
 def _units(lines, segment_by):
     """The vocal spans scenes are cut around: a line each, or a stanza."""
     units = []
     for line in lines:
         if segment_by == "stanza" and units and units[-1]["stanza"] == line["stanza"]:
             units[-1]["end"] = max(units[-1]["end"], line["end"])
-            units[-1]["lyrics"].append(line["text"])
-            units[-1]["tokens"].append(line.get("tokens"))
+            if line["text"]:
+                units[-1]["lyrics"].append(line["text"])
+                units[-1]["tokens"].append(line.get("tokens"))
         else:
+            # A phrase with no lyric is sung, with no line to carry
+            sung = [line["text"]] if line["text"] else []
             units.append(
                 {
                     "start": line["start"],
                     "end": line["end"],
-                    "lyrics": [line["text"]],
-                    "tokens": [line.get("tokens")],
+                    "lyrics": sung,
+                    "tokens": [line.get("tokens")] if sung else [],
                     "stanza": line["stanza"],
                 }
             )
@@ -480,6 +557,8 @@ def _scenes_by_beats(lines, beats, duration, args):
             continue
         scenes.append(_scene(start, end, "instrumental", []))
     for line in lines:
+        if not line["text"]:
+            continue
         for scene in scenes:
             if scene["start"] <= line["start"] < scene["end"] or (
                 scene is scenes[-1] and line["start"] >= scene["end"]
@@ -833,11 +912,17 @@ def _parsed_arguments(transcript, beats, segment_by, **raw):
 
 def _song_length(args, transcript, beats, beats_duration, warnings):
     """(duration, chunks) - the song's length in seconds and the
-    transcript's chunks. duration_s says how long, else the analyze_beats
-    result; failing both the transcript's last end does, and is warned
-    about."""
+    transcript's chunks (or analyze_phrases' phrases). duration_s says how
+    long, else the analyze_beats result, else the phrases' duration_seconds;
+    failing those the transcript's last end does, and is warned about."""
     duration = args.duration_s or beats_duration
-    chunks = _chunks(transcript, duration)
+    if _is_phrases(transcript):
+        chunks = _phrases(transcript)
+        duration = duration or _number(
+            transcript.get("duration_seconds"), "transcript.duration_seconds"
+        )
+    else:
+        chunks = _chunks(transcript, duration)
     if duration is None:
         # Only the transcript says how long: to the last word it kept (a
         # hallucination over the fade-out is left out), if that word has an end
@@ -948,7 +1033,15 @@ def plan_cuts(
             {text, chunks} dict of {start, end, text} chunks in seconds. A
             null 'end' runs to the next chunk's start, or the song's end. A
             chunk marked `suspect` no_words, repetition or silent is left
-            out of the lines; every suspect run is warned about
+            out of the lines; every suspect run is warned about. Or
+            analyze_phrases' result, {phrases: [{start, end}],
+            duration_seconds}, told by its 'phrases' key (#1095): timing
+            with no text. Without lyrics each phrase is a line with no
+            lyric; with lyrics as many lines as phrases, line n is phrase n,
+            and otherwise the counts are warned about (naming which way to
+            move analyze_phrases' min_gap_seconds) and the lines spread
+            evenly from the first phrase to the last. A phrase is never
+            suspect, and a split piece of one keeps its whole lyric
         lyrics: The song's own lyrics - one line per line, a blank line or a
             lone section tag ("[Chorus]") between stanzas - or a list of
             lines. The shots carry these lines verbatim and in order; the
@@ -1024,10 +1117,29 @@ def plan_cuts(
     warnings = []
     duration, chunks = _song_length(args, transcript, beats, beats_duration, warnings)
     beat_times = [beat for beat in beat_times if 0.0 < beat < duration]
-    warnings.extend(_suspect_warnings(chunks))
-    chunks = [chunk for chunk in chunks if chunk.get("suspect") not in SUSPECT_LEFT_OUT]
+    phrases = _is_phrases(transcript)
+    if not phrases:
+        # Phrases have no text, so none is ever suspect (#1095)
+        warnings.extend(_suspect_warnings(chunks))
+        chunks = [c for c in chunks if c.get("suspect") not in SUSPECT_LEFT_OUT]
+    given_lyrics = lyrics is not None and not (
+        isinstance(lyrics, str) and not lyrics.strip()
+    )
 
-    if lyrics is not None and not (isinstance(lyrics, str) and not lyrics.strip()):
+    if phrases:
+        lines = _phrase_lines(
+            chunks,
+            _lyric_lines(lyrics) if given_lyrics else None,
+            duration,
+            args.min_gap_seconds,
+            warnings,
+        )
+        if not lines:
+            warnings.append(
+                f"{COMMAND}: analyze_phrases found no sung phrases - the song is "
+                "planned as instrumental"
+            )
+    elif given_lyrics:
         lines = _align_lyrics(
             _lyric_lines(lyrics), chunks, duration, warnings, max(args.min_scene_s, 0.5)
         )
diff --git a/plugins/dw/skills/minimax-h3/references/cuts.md b/plugins/dw/skills/minimax-h3/references/cuts.md
index f413d2cc..590d2544 100644
--- a/plugins/dw/skills/minimax-h3/references/cuts.md
+++ b/plugins/dw/skills/minimax-h3/references/cuts.md
@@ -30,11 +30,27 @@ enters that long before the cut), each next where the last ended; then
 ## Planning a music video's cuts
 
 Plan, read, prompt, render. Run `templates/minimax/music-video-cuts`
-on the song with its `lyrics` (it chains `transcribe_audio`, `analyze_beats`
-and the `plan_cuts` task, on H3's grid with a `lead_s` run-up, default 0.5 s);
+on the song with its `lyrics` (it chains `separate_stems`, `transcribe_audio` of the
+vocal stem, `analyze_beats` of the full mix and the `plan_cuts` task, on H3's grid with a `lead_s` run-up, default 0.5 s);
 read the plan's `shots` (`lyric`, `kind`, `start_frame`, `num_frames`,
 `lead_frames`, `cut_frames`) and quote its `render_frames` for the cost: it is
-what renders, more than the song's length. Write one prompt per shot, a vocal
+what renders, more than the song's length. When Whisper can't time the words (a non-English verse, a hallucinated
+transcript, wordless vocals), replace the `transcribe` step with an
+`analyze_phrases` step on `previous_result:stems.vocals` (sung phrase timing
+from voiced energy, no Whisper), keep `plan_cuts`' `transcript` on that step
+and pass `lyrics`, one line per sung phrase; the default chain is unchanged.
+`plan_cuts` recognises the result by its `phrases` key. Without `lyrics` each
+phrase is a line with `lyric: null` (kind vocal), and `segment_by` `line`,
+`stanza` (a silence of at least `min_gap_seconds` between phrases) and `beat`
+all work. With as many lyric lines as phrases they map one to one, in order.
+With a different count it warns with both counts and spreads the lines evenly
+from the first phrase's start to the last's end, never pairing silently: raise
+`analyze_phrases`' `min_gap_seconds` when there are more phrases than lines,
+lower it when fewer. Suspect filtering and word alignment don't apply; a long
+phrase split into pieces gives every piece its whole lyric. The song length
+falls back to the phrase result's `duration_seconds`.
+
+Write one prompt per shot, a vocal
 shot to its `lyric`, an instrumental one to the mood. Render with
 `music-video`: each entry is the plan's shot with `prompt` added and `lyric`
 and `kind` dropped (unread, they only warn). Each shot renders `num_frames`
diff --git a/tests/test_plan_cuts_phrases.py b/tests/test_plan_cuts_phrases.py
new file mode 100644
index 00000000..ce066da0
--- /dev/null
+++ b/tests/test_plan_cuts_phrases.py
@@ -0,0 +1,193 @@
+"""plan_cuts on analyze_phrases' result: timing with no text (#1095)."""
+
+import numpy
+import pytest
+
+from dw.task_problems import cuts_errors
+from dw.tasks.cuts import plan_cuts
+from dw.tasks.phrases import analyze_phrases
+
+FPS = 24
+DURATION = 30.0
+SPANS = [(4.0, 7.0), (7.5, 10.0), (18.0, 21.0), (21.5, 24.0)]
+PHRASES = {
+    "phrases": [{"start": a, "end": b} for a, b in SPANS],
+    "duration_seconds": DURATION,
+    "method": "centre",
+    "warnings": [],
+}
+LYRICS = """[Verse]
+Rise up the morning
+Over the river
+
+[Chorus]
+Sing it out loud
+Never let go
+"""
+LINES = ["Rise up the morning", "Over the river", "Sing it out loud", "Never let go"]
+
+
+def beat_list(step=0.5, duration=DURATION):
+    return [round(i * step, 4) for i in range(1, int(duration / step))]
+
+
+def plan(**kwargs):
+    kwargs.setdefault("transcript", PHRASES)
+    return plan_cuts(**kwargs)
+
+
+def vocal(result):
+    return [s for s in result["shots"] if s["kind"] == "vocal"]
+
+
+def assert_tiles(result):
+    shots = result["shots"]
+    assert shots[0]["start_frame"] == 0
+    for before, after in zip(shots, shots[1:]):
+        assert after["start_frame"] == before["start_frame"] + before["cut_frames"]
+    assert sum(s["cut_frames"] for s in shots) == result["total_frames"]
+
+
+class TestWithoutLyrics:
+    def test_a_line_per_phrase_with_no_lyric(self):
+        result = plan()
+        shots = vocal(result)
+        assert len(shots) == len(SPANS)
+        assert all(s["lyric"] is None for s in shots)
+        assert [s["start_frame"] for s in shots] == [round(a * FPS) for a, _ in SPANS]
+        assert_tiles(result)
+
+    def test_the_length_comes_from_the_phrase_result(self):
+        result = plan()
+        assert result["duration_s"] == DURATION
+        assert not any(
+            "can't tell" in w or "last line" in w for w in result["warnings"]
+        )
+
+    def test_no_transcript_warnings(self):
+        warnings = plan()["warnings"]
+        assert not any("suspect" in w or "heard" in w for w in warnings)
+
+    def test_stanza_groups_phrases_by_silence(self):
+        shots = vocal(plan(segment_by="stanza"))
+        # The 8 s silence after 10.0 s is the only gap of min_gap_seconds (2.0)
+        assert [s["start_frame"] for s in shots] == [
+            round(4.0 * FPS),
+            round(18.0 * FPS),
+        ]
+        assert all(s["lyric"] is None for s in shots)
+
+    def test_beat_cuts_mark_the_sung_scenes(self):
+        result = plan(segment_by="beat", beats=beat_list(2.0), min_scene_s=2.0)
+        assert_tiles(result)
+        assert vocal(result) and all(s["lyric"] is None for s in result["shots"])
+        assert result["shots"][0]["kind"] == "instrumental"  # 0-2 s, nothing sung
+
+    def test_no_phrases_is_one_instrumental_shot(self):
+        result = plan(transcript=dict(PHRASES, phrases=[]))
+        assert [s["kind"] for s in result["shots"]] == ["instrumental"]
+        assert any("no sung phrases" in w for w in result["warnings"])
+
+
+class TestMatchingLyrics:
+    def test_lines_map_onto_phrases_in_order(self):
+        result = plan(lyrics=LYRICS)
+        shots = vocal(result)
+        assert [s["lyric"] for s in shots] == LINES
+        assert [s["start_frame"] for s in shots] == [round(a * FPS) for a, _ in SPANS]
+        assert result["warnings"] == []
+
+    def test_stanza_takes_the_lyrics_stanzas(self):
+        shots = vocal(plan(lyrics=LYRICS, segment_by="stanza"))
+        assert [s["lyric"] for s in shots] == [
+            "\n".join(LINES[:2]),
+            "\n".join(LINES[2:]),
+        ]
+
+    def test_beat_cuts_carry_the_lines(self):
+        result = plan(
+            lyrics=LYRICS, segment_by="beat", beats=beat_list(2.0), min_scene_s=2.0
+        )
+        assert_tiles(result)
+        sung = [s["lyric"] for s in result["shots"] if s["lyric"]]
+        assert "\n".join(sung).split("\n") == LINES
+
+    def test_a_split_phrase_keeps_its_whole_lyric(self):
+        long = dict(PHRASES, phrases=[{"start": 2.0, "end": 14.0}])
+        result = plan(transcript=long, lyrics="One long held line", max_scene_s=5.0)
+        sung = vocal(result)
+        assert len(sung) > 1
+        assert all(s["lyric"] == "One long held line" for s in sung)
+
+
+class TestMismatchedLyrics:
+    def mismatch(self, result):
+        return [w for w in result["warnings"] if "spread evenly" in w]
+
+    def test_more_phrases_than_lines_says_raise(self):
+        result = plan(lyrics="\n".join(LINES[:3]))
+        (warning,) = self.mismatch(result)
+        assert "3 line(s)" in warning and "4 phrase(s)" in warning
+        assert "raise analyze_phrases' 'min_gap_seconds'" in warning
+
+    def test_fewer_phrases_than_lines_says_lower(self):
+        result = plan(lyrics="\n".join(LINES + ["One more line", "And another"]))
+        (warning,) = self.mismatch(result)
+        assert "6 line(s)" in warning and "4 phrase(s)" in warning
+        assert "lower analyze_phrases' 'min_gap_seconds'" in warning
+
+    def test_the_lines_spread_evenly_from_first_phrase_to_last(self):
+        result = plan(lyrics="\n".join(LINES[:2]), include_instrumental_gaps=False)
+        shots = vocal(result)
+        assert [s["lyric"] for s in shots] == LINES[:2]
+        # 4.0-24.0 s halved: the second line starts at 14.0 s, not at a phrase
+        assert shots[1]["start_frame"] == round(14.0 * FPS)
+        assert_tiles(result)
+
+
+class TestUnchanged:
+    def test_the_render_grid_holds(self):
+        result = plan(
+            lyrics=LYRICS, modulus=8, remainder=1, min_frames=25, max_frames=121
+        )
+        assert_tiles(result)
+        for shot in result["shots"]:
+            assert shot["num_frames"] % 8 == 1
+            assert 25 <= shot["num_frames"] <= 121
+
+    def test_cuts_snap_to_beats(self):
+        beats = beat_list(0.7)
+        result = plan(lyrics=LYRICS, beats=beats, snap_to_beats=True)
+        beat_frames = {round(b * FPS) for b in beats}
+        for shot in result["shots"][1:]:
+            assert shot["start_frame"] in beat_frames
+
+    def test_a_static_check_accepts_the_phrase_result(self):
+        assert cuts_errors({"transcript": PHRASES}) == []
+
+    def test_a_phrases_key_that_is_no_list_is_refused(self):
+        errors = cuts_errors({"transcript": {"phrases": "4.0-7.0"}})
+        assert errors and errors[0][0] == "transcript"
+        with pytest.raises(ValueError, match="'phrases' key that is not a list"):
+            plan(transcript={"phrases": "4.0-7.0"}, duration_s=DURATION)
+
+
+def test_analyze_phrases_result_plans_with_lyrics():
+    # The real chain: analyze_phrases' own result straight into plan_cuts
+    rate, seconds = 22050, 8.0
+    t = numpy.arange(int(seconds * rate)) / rate
+    wave = numpy.zeros_like(t)
+    bursts = [(1.0, 2.5), (3.5, 5.0), (6.0, 7.5)]
+    for start, end in bursts:
+        on = (t >= start) & (t < end)
+        wave[on] = 0.3 * numpy.sin(2 * numpy.pi * 440 * t[on])
+    phrases = analyze_phrases(wave.astype(numpy.float32), sample_rate=rate)
+    assert len(phrases["phrases"]) == 3
+    result = plan_cuts(
+        phrases, lyrics="one\ntwo\nthree", min_scene_s=0.5, min_gap_seconds=0.5
+    )
+    shots = vocal(result)
+    assert [s["lyric"] for s in shots] == ["one", "two", "three"]
+    for shot, (start, _) in zip(shots, bursts):
+        assert shot["start_frame"] == pytest.approx(start * FPS, abs=0.05 * FPS + 1)
+    assert not any("spread evenly" in w for w in result["warnings"])
diff --git a/workflows/templates/minimax/README.md b/workflows/templates/minimax/README.md
index 881221c1..79785e2c 100644
--- a/workflows/templates/minimax/README.md
+++ b/workflows/templates/minimax/README.md
@@ -184,6 +184,26 @@ same clip as an audio reference in each shot, as
 | [music-video.json](music-video.json) | A music video cut to a generated song, one `shots` list driving both `for_each` groups: `slice_audio` deals each entry its frame-exact piece, the shot lip-syncs to it, and `pair_audio` lays the unbroken track over the finished edit, cut to the length of the edit by `fit: "video"` so the soundtrack follows the list rather than a constant. An entry is `name`, `prompt`, `start_frame`, `num_frames` (on H3's `17n + 5` grid, 124 to 345, never snapped), `lead_frames` and `cut_frames`: the shot renders `num_frames` from the song sliced `lead_frames` early, and a `trim` step (`trim_video`) keeps `cut_frames` after the lead, so the video is the sum of the `cut_frames`. `song` defaults to the song written; `asset:...` uses an existing one |
 | [music-video-cuts.json](music-video-cuts.json) | Plans a music video's cuts without generating anything: `transcribe_audio` times the song's lines, `analyze_beats` finds its beats, and `plan_cuts` aligns the song's own `lyrics` to them and answers a `shots` list of `start_frame`, `num_frames`, `lead_frames`, `cut_frames`, lyric and kind (on H3's grid, with a `lead_s` run-up, default 0.5 s) and `render_frames` to quote the cost from. Write a prompt per shot, drop `lyric` and `kind`, and render the list with `music-video.json` |
 
+**music-video-cuts without Whisper.** When Whisper can't time the words (a non-English verse, a hallucinated transcript, wordless vocals or a vocalise), replace the `transcribe` step with an `analyze_phrases` step on the vocal stem, which times sung phrases from voiced energy alone. `plan` keeps `"transcript": "previous_result:transcribe"`; pass `lyrics` with one line per sung phrase (left null, each shot has `lyric: null`):
+
+```json
+{
+    "name": "transcribe",
+    "task": {
+        "command": "analyze_phrases",
+        "arguments": {
+            "audio": "previous_result:stems.vocals"
+        }
+    },
+    "result": {
+        "content_type": "application/json",
+        "subfolder": "intermediate"
+    }
+}
+```
+
+Lyric lines map onto phrases one to one when the counts match. When they differ, `plan_cuts` warns with both counts and spreads the lines evenly across the phrases: raise `analyze_phrases`' `min_gap_seconds` when there are more phrases than lines, lower it when fewer. The template's default chain is unchanged (Whisper first).
+
 ## Field notes from a 24-shot musical
 
 A 24-shot Ref2VA short with a Music3 song surfaced six prompting habits, each
diff --git a/workflows/templates/minimax/music-video-cuts.json b/workflows/templates/minimax/music-video-cuts.json
index 85606d47..030e97f3 100644
--- a/workflows/templates/minimax/music-video-cuts.json
+++ b/workflows/templates/minimax/music-video-cuts.json
@@ -1,6 +1,6 @@
 {
     "id": "MiniMaxMusicVideoCuts",
-    "description": "Plans a music video's cuts from a song and its lyrics. It separates the vocal stem ('stems', htdemucs) so the transcript is of the voice alone - transcribing the full mix folds an instrumental intro into the first word and lets Whisper invent text over a fade-out - then transcribes that stem with timestamps ('transcribe', a Whisper-class model) and finds the beats of the full mix ('beats'), then 'plan_cuts' turns the two into a shot list ('plan') covering the whole song, to the length 'beats' measured. Nothing is generated: the result is one JSON document of shots, each {name, start_frame, num_frames, lead_frames, cut_frames, lyric, kind}, tiling the song exactly at 'fps', so the agent writes one prompt per shot and renders the list with music-video.json, whose entries are {name, prompt, start_frame, num_frames, lead_frames, cut_frames}: add a 'prompt' to each entry and drop 'lyric' and 'kind' to render the plan as it stands. The shots are sized for H3 - 'num_frames' on its 17n+5 grid between 124 and 345 frames, with 'lead_s' seconds of run-up before each cut that music-video trims off - and the result's 'render_frames' is the total frames that will be generated, lead included, for quoting the cost. 'lyrics' is the song's own words, one line per line with a blank line or a lone section tag such as [Chorus] between stanzas: the shots carry those lines verbatim and the transcript only times them, since Whisper mishears sung words. Left null, the shots carry the transcript's text. 'segment_by' is 'line' (a shot per sung line), 'stanza' or 'beat' (a cut every few beats). 'min_scene_s' merges a shot that is too short into its neighbour and 'max_scene_s' splits one that is too long, on a beat. 'vocal_tail_s' holds a sung shot past its last word, 'include_instrumental_gaps' gives a long silence its own instrumental shot, and 'snap_to_beats' moves every cut to its nearest beat. 'timestamps' must stay 'segment' (a Whisper segment per line) or be 'word'; plan_cuts refuses a transcript without timings.",
+    "description": "Plans a music video's cuts from a song and its lyrics. It separates the vocal stem ('stems', htdemucs) so the transcript is of the voice alone - transcribing the full mix folds an instrumental intro into the first word and lets Whisper invent text over a fade-out - then transcribes that stem with timestamps ('transcribe', a Whisper-class model) and finds the beats of the full mix ('beats'), then 'plan_cuts' turns the two into a shot list ('plan') covering the whole song, to the length 'beats' measured. Nothing is generated: the result is one JSON document of shots, each {name, start_frame, num_frames, lead_frames, cut_frames, lyric, kind}, tiling the song exactly at 'fps', so the agent writes one prompt per shot and renders the list with music-video.json, whose entries are {name, prompt, start_frame, num_frames, lead_frames, cut_frames}: add a 'prompt' to each entry and drop 'lyric' and 'kind' to render the plan as it stands. The shots are sized for H3 - 'num_frames' on its 17n+5 grid between 124 and 345 frames, with 'lead_s' seconds of run-up before each cut that music-video trims off - and the result's 'render_frames' is the total frames that will be generated, lead included, for quoting the cost. 'lyrics' is the song's own words, one line per line with a blank line or a lone section tag such as [Chorus] between stanzas: the shots carry those lines verbatim and the transcript only times them, since Whisper mishears sung words. Left null, the shots carry the transcript's text. 'segment_by' is 'line' (a shot per sung line), 'stanza' or 'beat' (a cut every few beats). 'min_scene_s' merges a shot that is too short into its neighbour and 'max_scene_s' splits one that is too long, on a beat. 'vocal_tail_s' holds a sung shot past its last word, 'include_instrumental_gaps' gives a long silence its own instrumental shot, and 'snap_to_beats' moves every cut to its nearest beat. 'timestamps' must stay 'segment' (a Whisper segment per line) or be 'word'; plan_cuts refuses a transcript without timings. Swap 'transcribe' for an analyze_phrases step on the vocal stem when Whisper cannot time the words (non-English, wordless).",
     "cost_drivers": [
         "fps"
     ],

From ec2d3c309a119560b77c552319aaf8b4623dade2 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 17:42:08 -0500
Subject: [PATCH 063/125] docs(proposals): #1091 - dialogue/rest stems
 close-out record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-11-dialogue-stems.md          |   6 +-
 .../complete/dialogue-stems-complete.md       | 127 ++++++++++++++++++
 docs/proposals/todo.md                        |   9 ++
 3 files changed, 140 insertions(+), 2 deletions(-)
 create mode 100644 docs/proposals/complete/dialogue-stems-complete.md

diff --git a/docs/proposals/audits/2026-11-dialogue-stems.md b/docs/proposals/audits/2026-11-dialogue-stems.md
index ac4b2cf7..7e21ba89 100644
--- a/docs/proposals/audits/2026-11-dialogue-stems.md
+++ b/docs/proposals/audits/2026-11-dialogue-stems.md
@@ -252,5 +252,7 @@ The mixes the stems came from are each run's `intermediate/mix-0.0.wav`.
 
 ## Verdict
 
-Pending Don's listening. A `series-episodes` paragraph is written only if the
-verdict is "good enough" (plan v2, stage A).
+**Good enough** (Don, by ear, 2026-10-31, on the mix, `vocals` and rest of
+button, tag and deflect). htdemucs stands as the dialogue/rest splitter; the
+recipe is in the `series-episodes` skill's *match_levels* bullet, and no
+dedicated separator was built (`../complete/dialogue-stems-complete.md`).
diff --git a/docs/proposals/complete/dialogue-stems-complete.md b/docs/proposals/complete/dialogue-stems-complete.md
new file mode 100644
index 00000000..ee1a9908
--- /dev/null
+++ b/docs/proposals/complete/dialogue-stems-complete.md
@@ -0,0 +1,127 @@
+# Dialogue/rest stems: htdemucs `vocals` plus a three-track re-mix (#1091)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 approved 2026-10-31 under Don's delegation, with Q1–Q4
+at the plan's defaults; plan v2 folded those answers in with no scope
+change. One stage, #1096, verified 2026-10-31 (mini-ai, then lem for the
+kept stems). Stages B–C (a dedicated separator) were conditional and were
+not built.
+
+The concept came from r34vtraining/Longshot_Studio (its `build_stems`,
+MelBand RoFormer dialogue/sfx stems, assessed 2026-10-31). That repo has
+**no license**, so nothing was copied.
+
+## The report
+
+A short film's dialogue can't be levelled, cleaned or replaced separately
+from its sound bed, because the world track is one stem. The issue asked for
+a speech-vs-rest separator (MelBand RoFormer or a DnR-trained model) in place
+of htdemucs, which was trained on songs.
+
+## Verdict
+
+**Build smaller: measure first.** The evidence for a new model was thin (no
+field report, no film workspace using `separate_stems`, the nearest past
+problem #340 solved by ducking), and a new separator brings a dependency
+outside diffusers, a pickle boundary (most RoFormer checkpoints are `.ckpt`)
+and unverified weight licences. So stage A measured htdemucs as a
+dialogue/rest splitter with tasks that already exist, and a new separator was
+gated on Don hearing it fail.
+
+## What the plan found against the issue
+
+- **A `model` argument on `separate_stems` is the wrong shape.** Result keys
+  are never checked statically (`previous_result:step.key` resolves at run
+  time), so `stems.vocals` on a dialogue model would validate clean and fail
+  mid-run; and the `stacked_vocals` check indexes `stems["vocals"]`. Had a
+  separator been built, it would have been its own command,
+  `separate_dialogue`, with fixed `dialogue` / `rest` results.
+- **`match_levels` is a concat/dissolve argument, not a task**, so the
+  issue's "recut-bed-match_levels pass" is the skill's ducking/bed advice.
+- **`dialogue-short` has no audio pass**: it gains nothing until a scoring
+  step follows it. The split point is `assemble-and-score`'s world track.
+- **A doc inconsistency:** `docs/TASKS.md` said htdemucs came from HF
+  `adefossez/HTDemucs` in one place and from outside the HF cache in another.
+
+## Decisions
+
+- **Q1–Q4 (approval, 2026-10-31):** Don judges stage A by listening, with
+  the numbers beside the verdict; no `dialogue_gain` template variable;
+  pickles refused; vendor the minimal module, licence permitting (the last
+  two applied only to stage B).
+- **Listening verdict (Don, 2026-10-31): good enough.** Don listened to the
+  mix, `vocals` and rest for button, tag and deflect. htdemucs stands; B–C
+  are not built, and #1091 ends with stage A.
+
+## What was built
+
+**Stage A, #1096: the A/B record and the recipe** (plugin and docs only).
+- The record, `audits/2026-11-dialogue-stems.md` (lem, workspace
+  `dialogue-stems-1096`): three H3 dialogue shots from `known-issues`, each
+  mixed with a Music 3 score at gain 0.5, then `separate_stems`, with
+  bed-alone and dry-alone control separations. Findings:
+  - `vocals` matches the dry shot within 0.1 dB rms and 0.2 dB peak;
+  - the score puts -62 to -64 dBFS rms into `vocals`, 30–36 dB under the
+    bed;
+  - the rest is the score **plus the shot's own SFX and foley**, which
+    htdemucs routes to `drums` / `other`;
+  - transcribing `vocals` gave the line on 3/3 shots, where whisper-base
+    looped on the dry audio on 2/3;
+  - no `stacked_vocals` on single-speaker dialogue;
+  - a speechless shot gives a near-silent `vocals` stem and an invented
+    transcript, so check the stem's level, not the transcript.
+  The 15 stems are kept as `asset:dialogue-stems-<mix>-<stem>.wav` there.
+- `plugins/dw/skills/series-episodes/SKILL.md`, the *match_levels* bullet:
+  besides ducking, give dialogue its own gain in a saved copy of
+  `assemble-and-score` — `separate_stems` on `world_faded`,
+  `previous_result:<step>.vocals` as the dialogue, a `mix_audio` of
+  `drums`/`bass`/`other` as the rest, `mixed` layering
+  `[soundtrack_resampled, dialogue, rest]` with one gain each, and
+  `balanced` kept after it. It carries finding 3's caveat (keep the original
+  score file to re-mix or replace the score) and the ambience caveat below.
+- `docs/TASKS.md`: the *Stem separation* section names the dialogue/rest
+  use, and *Voice attribution* now gives demucs' own downloader
+  (`dl.fbaipublicfiles.com`, torch hub cache) as the weights' source.
+
+## Deviations from the plan
+
+- **Control separations instead of a difference.** `mix_audio` refuses
+  negative gains, so "vocals − dry" can't be rendered; the bed and the dry
+  shot were separated alone to measure leak each way.
+- **`acorn-wars` s04 replaced by `tag`.** s04 held no speech; it is kept in
+  the record as the speechless negative.
+- **The split point is `world_faded`**, not `world`: it is the step that
+  feeds `mixed`, and splitting after the fade keeps the fade on every stem.
+
+## Bounces per stage
+
+**#1096: one.** The first mini-ai verify failed C-F557 and C-F559:
+- The tester's chain stopped at `mix_audio`, and a 1.4× dialogue gain on a
+  stem peaking at -1.5 dBFS clipped to +1.4. Fix: the bullet says to keep
+  `balanced` (`normalize_audio`, -3 dBFS peak) after `mixed`; re-run, it
+  lands at -3.00.
+- The fixture `asset:qa-cast/ep20-score.wav` is a near-silent ambience bed,
+  not a music score, and htdemucs sends it almost whole to `vocals`, leaving
+  a near-silent rest. That is the fixture, not the recipe: the bullet gained
+  a caveat (a quiet, unpitched bed lands mostly in `vocals`; a shot with
+  little foley leaves a near-silent rest), and the tester filed the suite
+  amendment as dkackman/harnest#163. C-F557 and C-F559 stay `pending:
+  #1096` until it is ruled on.
+
+C-F562 (the kept stems) ran on lem, where the workspace lives.
+
+## Cost
+
+The stage comments name no `usage:` figures, so per-stage spend isn't
+recorded here.
+
+## Deferred and left open
+
+- **A dedicated dialogue separator (`separate_dialogue`, stages B–C).**
+  Back if a film session hears foley or score leak in `vocals` that matters,
+  or needs a clean score from an already-scored mix. The re-plan must first
+  find a checkpoint with a licence that permits Don's use and safetensors
+  weights at a pinned revision.
+- **A three-way dialogue/music/effects split** (BandIt-style). Back if the
+  foley-in-the-rest caveat becomes the problem.
+- **C-F557 / C-F559's fixture**: harnest#163.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index a34f39f8..27aeea5e 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -419,6 +419,15 @@ remaining deferred fix is recorded in
   crops' own audio held. Record, including what was deferred (ref2va,
   tail-only padding, with their triggers):
   `complete/h3-face-repair-complete.md`.
+- **Dialogue/rest stems from htdemucs, in `series-episodes`** (#1091,
+  stage #1096), shipped 2026-10-31. An A/B on three H3 dialogue shots over a
+  Music 3 score (`audits/2026-11-dialogue-stems.md`) found `separate_stems`'
+  `vocals` within 0.1 dB of the dry shot; Don judged it good enough by ear,
+  so no new separator was built. The skill's *match_levels* bullet gives
+  dialogue its own gain: `vocals` as dialogue, `mix_audio` of the other three
+  stems as the rest, a three-track `mixed`, then `balanced`. Record,
+  including the deferred `separate_dialogue` task and its reopen trigger:
+  `complete/dialogue-stems-complete.md`.
 
 ## Declined
 

From 9aff5c7df43207912c1eb2c2f85cd1ac68f74466 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 19:16:46 -0500
Subject: [PATCH 064/125] feat(templates): #1080 - restore-colorize prompt must
 describe the clip (plan v10)

The Colorization IC-LoRA colours only what the prompt names. The template
description, the stored prompt's description, the ltx-2.5 skill row and the
family README now say the caller writes both panels for their own clip and
names its colours; the default is a worked example. The registry evidence
note names the clip-matched screen f80056a98e62. COMPACT_BUDGET re-measured
(unchanged at 12_357).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 loras/ltx-2.5/ic-colorization.json             | 2 +-
 plugins/dw/skills/ltx-2.5/SKILL.md             | 6 ++++--
 prompts/ltx2/colorize_dual_panel.json          | 2 +-
 tests/test_catalog_structure.py                | 4 +++-
 workflows/templates/ltx2/README.md             | 2 +-
 workflows/templates/ltx2/restore-colorize.json | 2 +-
 6 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/loras/ltx-2.5/ic-colorization.json b/loras/ltx-2.5/ic-colorization.json
index 779b15db..4defa78d 100644
--- a/loras/ltx-2.5/ic-colorization.json
+++ b/loras/ltx-2.5/ic-colorization.json
@@ -21,7 +21,7 @@
     {
       "job": "b70c30a5e8e4",
       "issue": 1064,
-      "note": "templates/ltx2/restore-colorize on lem (RTX 3090, uint4 SDNQ) at 960x544x121: natural colour on a greyscale street clip, subject, framing and motion kept, 121 frames at the source's 24 fps; a portrait 384x544x97 run (c01a0fc6df48) came back at source size with no band or colour from the letterbox padding; 2.5 min including a cold load"
+      "note": "templates/ltx2/restore-colorize on lem (RTX 3090, uint4 SDNQ) at 960x544x121: natural colour on a greyscale street clip that the stored default prompt happens to describe, subject, framing and motion kept, 121 frames at the source's 24 fps; the colour holds only with a prompt matched to the clip - on an office-interview fixture the default and two generic prompts left it grey (1521f00bcf5a, 69e6bb12d56b, PSNR 36.7 dB to the source) and a prompt describing that clip and naming its colours coloured it (f80056a98e62, 49 frames, PSNR 30.2 dB); a portrait 384x544x97 run (c01a0fc6df48) came back at source size with no band or colour from the letterbox padding; 2.5 min including a cold load"
     }
   ],
   "license": "other",
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 8fc5c13f..10f6f694 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -56,8 +56,10 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
 - **Repairing the user's footage**: `templates/ltx2/restore-deblur` for
   spatial defocus, `templates/ltx2/restore-decompression` for low-bitrate
   artefacts, `templates/ltx2/restore-colorize` for black-and-white or
-  washed-out footage (keeps the source's size and rate; prompt names the
-  colours). Each inverts one defect and no other - neither upscales or
+  washed-out footage (keeps the source's size and rate, no soundtrack). It
+  colours only what the prompt names: look at a source frame
+  (`get_output_frames`) and write both prompt panels for that clip, naming
+  its colours - the default is an example and leaves an unlike clip grey. Each inverts one defect and no other - neither upscales or
   removes motion blur or grain - so name the defect and let the user
   correct you. To upscale or sharpen: `templates/ltx2/upscale-clip`
   (IC-LoRA re-render), `width`/`height` the render size, or `refine-clip`
diff --git a/prompts/ltx2/colorize_dual_panel.json b/prompts/ltx2/colorize_dual_panel.json
index 7ca710c3..82b890b7 100644
--- a/prompts/ltx2/colorize_dual_panel.json
+++ b/prompts/ltx2/colorize_dual_panel.json
@@ -1,6 +1,6 @@
 {
   "text": "Reference shows a woman in a long coat walking a small dog along a cobbled street lined with shop fronts and parked cars under overcast daylight, in black and white with no colour information. Edited shows the same scene with natural colors restored. COLORIZE a woman in a camel coat and a red scarf walking a small brown dog along a grey cobbled street lined with shop fronts with green and cream awnings and parked cars under overcast daylight. Subject identity, framing, motion, and background geometry are identical to the reference; only color information differs between reference and edited.",
-  "description": "The Colorization IC-LoRA's trained dual-panel form - replace both descriptions of the scene with your own clip's, keeping the structure, and name the colours you expect where they matter",
+  "description": "The Colorization IC-LoRA's trained dual-panel form, a worked example for a street scene - the LoRA colours only what the prompt names, so replace both descriptions with your own clip's, keeping the structure, and name its colours; run as-is on an unlike clip it leaves the clip grey",
   "intended_model": "ltx-2.5",
   "tags": [
     "ic-lora",
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 2e67478d..9f6b1205 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -513,7 +513,9 @@ def test_no_stale_entry_in_the_allowlist():
 # repair that holds an H3 take's soundtrack, with its cost block.
 # Then to 12_400 for the `ltx2/restore-colorize` template (#1064, stage #1080,
 # 2026-10-31), measured at 12_357: one new entry, the catalog's only
-# colourisation of existing footage, with its cost block.
+# colourisation of existing footage, with its cost block. Re-measured at
+# 12_357 after its description grew (plan v10): the compact view carries the
+# summary, not the description, so the budget stands.
 COMPACT_BUDGET = 12_400
 FILTERED_BUDGET = 1_500
 
diff --git a/workflows/templates/ltx2/README.md b/workflows/templates/ltx2/README.md
index 6088443b..56423643 100644
--- a/workflows/templates/ltx2/README.md
+++ b/workflows/templates/ltx2/README.md
@@ -68,7 +68,7 @@ generated. Deblur, decompression and colorization are 0.9 preview weights traine
 | ------- | ------------------ |
 | [restore-deblur.json](restore-deblur.json) | Spatial defocus only - not motion blur, not noise, not low resolution. Lower `lora_scale` toward 0.8 if it over-sharpens into haloing (#152) |
 | [restore-decompression.json](restore-decompression.json) | Macroblocking, chroma bleed, ringing and banding from a low bit-rate source. Not a deblur and not an upscale (#152) |
-| [restore-colorize.json](restore-colorize.json) | Natural colour for black-and-white or washed-out footage, at the source's size and frame rate; only the colour changes. The prompt keeps the dual-panel convention and names the colours you expect. Lower `lora_scale` toward 0.8 if colour oversaturates or bleeds (#1064) |
+| [restore-colorize.json](restore-colorize.json) | Natural colour for black-and-white or washed-out footage, at the source's size and frame rate; only the colour changes. The prompt keeps the dual-panel convention and must describe your clip and name its colours: the LoRA colours only what the prompt names, and the default prompt (a street scene) leaves an unlike clip grey. Lower `lora_scale` toward 0.8 if colour oversaturates or bleeds (#1064) |
 | [alpha-matte.json](alpha-matte.json) | A soft per-frame alpha matte of the source - grey h264, white = foreground, at the source's size - for compositing in an editor. No prompt: the Alpha-Gen card's model picks the foreground itself. `num_frames` caps at 145, past which RGB leaks into the matte; the card's 1920x1088 ceiling is not a 24 GB size (#1064) |
 | [restore-long.json](restore-long.json) | `restore-deblur` over a source longer than one bucket: `window_video` slices it, a `for_each` restores each window, `join_windows` cross-fades them back to the source's length. `windows` is `ceil(source_frames / (num_frames - overlap))` entries, checked by `validate_workflow` (#601) |
 
diff --git a/workflows/templates/ltx2/restore-colorize.json b/workflows/templates/ltx2/restore-colorize.json
index 02d4f848..b42edb40 100644
--- a/workflows/templates/ltx2/restore-colorize.json
+++ b/workflows/templates/ltx2/restore-colorize.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2Colorize",
-    "description": "Restores natural colour to black-and-white or washed-out source footage with the Colorization in-context LoRA, the monochrome clip attached as a reference for the whole denoise - so the subject, the framing and the motion are the ones that were shot and only the colour changes. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so any aspect ratio comes back at the source's own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket weakens the effect. 'lora_scale' is 1.0 - lower it toward 0.8 if the colour oversaturates or bleeds across edges. The prompt follows the trained dual-panel convention ('Reference shows ... COLORIZE ... only color information differs'): replace both descriptions of the scene with your own clip's, naming the colours you expect where they matter. A 0.9 preview weight, run here under uint4 SDNQ.",
+    "description": "Restores natural colour to black-and-white or washed-out source footage with the Colorization in-context LoRA, the monochrome clip attached as a reference for the whole denoise - so the subject, the framing and the motion are the ones that were shot and only the colour changes. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so any aspect ratio comes back at the source's own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket weakens the effect. 'lora_scale' is 1.0 - lower it toward 0.8 if the colour oversaturates or bleeds across edges. The prompt follows the trained dual-panel convention ('Reference shows ... COLORIZE ... only color information differs') and must describe this clip and name its colours: the LoRA colours only what the prompt names, so the default - a worked example describing a street scene - leaves an unlike clip grey. Look at a frame of the source and write both panels for it. A 0.9 preview weight, run here under uint4 SDNQ.",
     "summary": "Colourises black-and-white or washed-out footage, keeping the source's size, frame rate and motion.",
     "traits": [
         "needs-input-media"

From 4256fddc3cd9e1242b6c5498de8c385281ba8914 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 19:24:55 -0500
Subject: [PATCH 065/125] feat(tasks): #1106 - source fps for paste_face_track,
 join_windows and the ltx2 face-repair/restore-long templates

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                              | 13 ++++---
 dw/task_domains.py                         | 40 ++++++++++++++--------
 dw/task_problems.py                        | 10 +++---
 dw/tasks/face_track.py                     | 19 +++++++---
 dw/tasks/fit.py                            |  4 +--
 dw/tasks/video_handlers.py                 | 19 ++++++++--
 dw/tasks/windows.py                        | 15 +++++---
 plugins/dw/skills/ltx-2.5/SKILL.md         |  6 ++--
 workflows/templates/ltx2/face-repair.json  | 13 ++++---
 workflows/templates/ltx2/restore-long.json | 15 ++++----
 10 files changed, 99 insertions(+), 55 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 5bde7ff0..1eb6a49a 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -973,7 +973,7 @@ that step instead.
 | `num_frames` | Yes | Frames per window, as given to `window_video` |
 | `overlap` | Yes | Frames each window shares with the one before, as given to `window_video` |
 | `curve` | No | The blend's shape across a seam: `cosine` (the default, `(1 - cos πt) / 2`), `smoothstep` (`3t² - 2t³`) or `linear` (`t`) |
-| `fps` | No | The source's frame rate. Defaults to the rate its file was read at; needed only to put its audio back |
+| `fps` | No | The joined video's frame rate: omitted or `"source"` for the rate the source's file was read at, or a number above zero for that rate. No frames are added or dropped; the source's audio is put back over the frames at this rate |
 
 The result has exactly the source's frame count, each source frame once:
 window 0's real frames, then each later window's first `overlap` frames
@@ -1002,7 +1002,8 @@ check is the task's (`dw/window_count_errors.py`), so any `join_windows`
 step gets it, and it applies the same `window_count_problem` the task does. It also refuses a window whose frame count is not `num_frames`
 (named by position) and windows of different sizes. An unknown `curve` and an
 `overlap` that is not below `num_frames` are refused by `validate_workflow`
-on literal values as well.
+on literal values as well, and so is an `fps` that is neither `"source"`
+nor a number above zero.
 
 The output's audio is the source's own track over exactly
 `frames_to_samples(source_frames)`, and none when the source has none; the
@@ -1257,6 +1258,7 @@ using the `track` record `crop_face_track` returned:
 | `track` | Yes | The `track` record `crop_face_track` returned (`previous_result:<step>.track`), or the path of its saved `.json`, such as an `output:` reference |
 | `feather` | No | Fraction of the paste's radius that fades out, `0` to `1`. Default `0.3` |
 | `color_match` | No | Shift each crop's mean colour onto the source's inside the mask before blending. Default `true` |
+| `fps` | No | The output's frame rate: omitted or `"source"` for the clip's own, or a number above zero for that rate. No frames are added or dropped |
 
 The pad frames are dropped: the crop at `pad_before + i` goes back on source
 frame `i`. Each crop is resized to the square it was cut from, then blended
@@ -1271,11 +1273,12 @@ through exactly. With `color_match`, the crop's mean colour is shifted onto the
 source's inside the mask, so a repair pass that drifted in tone does not show
 as a patch.
 
-It returns the source clip with its audio, frame rate and shots carried, the
-same frames one for one. It refuses a track whose frame count or frame size
+It returns the source clip with its audio and shots carried, the same frames
+one for one, at the clip's frame rate unless `fps` sets another. It refuses a track whose frame count or frame size
 does not match the clip, a `repaired` with fewer frames than the track's
 `crop_frames`, and a `track` that is not a `crop_face_track` record.
-`validate_workflow` refuses a `feather` past `1` before the job runs.
+`validate_workflow` refuses a `feather` past `1`, and an `fps` that is
+neither `"source"` nor a number above zero, before the job runs.
 
 **Example:** [face-repair.json](../workflows/templates/ltx2/face-repair.json) — the repaired crops pasted back over the source, its soundtrack kept.
 
diff --git a/dw/task_domains.py b/dw/task_domains.py
index bfa6833c..a9179cf8 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -588,11 +588,14 @@ def window_video_errors(arguments, command="window_video"):
 
 def join_windows_errors(arguments):
     """[(argument, message)] for the join_windows rules a literal workflow
-    can break before it runs: an unknown `curve`, and the overlap rule it
-    shares with window_video. The window count needs the source's frame
-    count, which the run measures."""
-    return choice_errors("join_windows", arguments) + window_video_errors(
-        arguments, "join_windows"
+    can break before it runs: an unknown `curve`, the overlap rule it shares
+    with window_video, and an `fps` that is neither "source" nor a positive
+    number. The window count needs the source's frame count, which the run
+    measures."""
+    return (
+        choice_errors("join_windows", arguments)
+        + window_video_errors(arguments, "join_windows")
+        + source_fps_errors(arguments, "join_windows")
     )
 
 
@@ -675,31 +678,38 @@ def fit_to_model_errors(arguments):
     return errors
 
 
-# restore_to_source's `fps` value for "the rate the source carried", read
-# from the fit record's `source_fps` (#1079)
+# The `fps` value for "the rate the source carried" - restore_to_source's,
+# read from the fit record's `source_fps` (#1079), and paste_face_track's
+# and join_windows', read from the source clip itself (#1090)
 SOURCE_FPS = "source"
 
 
-def restore_fps_problem(fps):
-    """The refusal sentence for a restore_to_source `fps` that is neither
-    "source" nor a positive number, or None. Omitted (None) and a reference
-    still to resolve are not this check's to refuse."""
+def source_fps_problem(fps, command="restore_to_source"):
+    """The refusal sentence for a `command` `fps` that is neither "source"
+    nor a positive number, or None. Omitted (None) and a reference still to
+    resolve are not this check's to refuse."""
     if fps is None or fps == SOURCE_FPS or is_ref(DEFERRED, fps):
         return None
     if _is_literal_text(fps) and not _is_non_finite_text(fps):
         return (
-            f"restore_to_source needs 'fps' as {SOURCE_FPS!r} or a number "
+            f"{command} needs 'fps' as {SOURCE_FPS!r} or a number "
             f"({_DOMAIN_TEXT[POSITIVE]}), got {fps!r}"
         )
-    return domain_error("restore_to_source", "fps", fps, POSITIVE)
+    return domain_error(command, "fps", fps, POSITIVE)
+
+
+def source_fps_errors(arguments, command):
+    """[(argument, message)] for the rule a literal `fps` breaks before the
+    run: neither "source" nor a positive number."""
+    problem = source_fps_problem(arguments.get("fps"), command)
+    return [] if problem is None else [("fps", problem.rstrip("."))]
 
 
 def restore_to_source_errors(arguments):
     """[(argument, message)] for the restore_to_source rule a literal
     workflow can break before it runs: an `fps` that is neither "source" nor
     a positive number."""
-    problem = restore_fps_problem(arguments.get("fps"))
-    return [] if problem is None else [("fps", problem.rstrip("."))]
+    return source_fps_errors(arguments, "restore_to_source")
 
 
 def dissolve_shortfalls(frame_counts, dissolve_frames):
diff --git a/dw/task_problems.py b/dw/task_problems.py
index 1025b07e..5e42c2b2 100644
--- a/dw/task_problems.py
+++ b/dw/task_problems.py
@@ -25,7 +25,7 @@
 
 from .references import DEFERRED, GATHER, is_ref
 from .script_lines import parse_lines, parse_shots, shot_names_error
-from .task_domains import as_number, choice_errors
+from .task_domains import as_number, choice_errors, source_fps_errors
 
 # ingredients_grid's literal choices, read by its registration and by
 # ingredients_grid_errors below, and its default image cap
@@ -208,11 +208,13 @@ def paste_feather_problems(feather=None):
 
 def paste_face_track_errors(arguments):
     """[(argument, message)] for the paste_face_track rules a literal
-    workflow can break before it runs."""
+    workflow can break before it runs: a feather past 1, and an `fps` that
+    is neither "source" nor a positive number."""
+    problems = source_fps_errors(arguments, "paste_face_track")
     feather = arguments.get("feather")
     if is_ref(DEFERRED, feather):
-        return []
-    return paste_feather_problems(feather)
+        return problems
+    return paste_feather_problems(feather) + problems
 
 
 def check_face_detector_source(repo, filename):
diff --git a/dw/tasks/face_track.py b/dw/tasks/face_track.py
index a0ef28d0..11fc78ed 100644
--- a/dw/tasks/face_track.py
+++ b/dw/tasks/face_track.py
@@ -53,7 +53,7 @@
     face_track_problems,
     paste_feather_problems,
 )
-from ..task_domains import check_arguments
+from ..task_domains import SOURCE_FPS, check_arguments, real_number, source_fps_problem
 from ..variable_constraints import aligned
 from .video_utils import frames_as_pil_list, load_audio_video
 from .weights import argument_or_default, file_entries
@@ -768,19 +768,22 @@ def _read_track(track):
     return track
 
 
-def paste_face_track(clip, repaired, track, feather=0.3, color_match=True):
+def paste_face_track(clip, repaired, track, feather=0.3, color_match=True, fps=None):
     """Task command: put repaired face crops back into the clip they came from.
 
     Args:
         clip: The source video crop_face_track read - frames, an AudioVideo,
-            or the path or URL of a video file. Its audio, frame rate and
-            shots come through unchanged
+            or the path or URL of a video file. Its audio and shots come
+            through unchanged, and its frame rate unless `fps` sets one
         repaired: The crops after a face-detail pass, still padded to the
             padded count crop_face_track produced; any frame size
         track: The `track` record crop_face_track returned, or its .json file
         feather: Fraction of the paste's radius that fades out, 0 to 1
         color_match: Match each crop's mean colour to the source's inside the
             mask before blending
+        fps: The output's frame rate - omitted or "source" for the clip's
+            own, or a number above zero for that rate (#1090). No frames are
+            added or dropped for it
     Returns:
         An AudioVideo: the source frames with the face pasted back where the
         strength is above 0, and the source frame itself where it is 0
@@ -789,6 +792,12 @@ def paste_face_track(clip, repaired, track, feather=0.3, color_match=True):
     if problems:
         raise ValueError("; ".join(message for _, message in problems))
     feather = float(feather)
+    problem = source_fps_problem(fps, "paste_face_track")
+    if problem is not None:
+        raise ValueError(problem)
+    if fps == SOURCE_FPS:
+        fps = None
+    fps = real_number(fps, "fps", "paste_face_track")
     track = _read_track(track)
 
     if isinstance(clip, str):
@@ -855,6 +864,6 @@ def paste_face_track(clip, repaired, track, feather=0.3, color_match=True):
         out,
         getattr(clip, "audio", None),
         getattr(clip, "sample_rate", None),
-        fps=getattr(clip, "fps", None),
+        fps=fps or getattr(clip, "fps", None),
         shots=carried_shots(clip),
     )
diff --git a/dw/tasks/fit.py b/dw/tasks/fit.py
index d42563c1..63513479 100644
--- a/dw/tasks/fit.py
+++ b/dw/tasks/fit.py
@@ -40,7 +40,7 @@
     fit_downscale_problem,
     fit_mode_problem,
     real_number,
-    restore_fps_problem,
+    source_fps_problem,
     whole_number,
 )
 from .video_utils import frames_of, frames_as_array, load_audio_video
@@ -293,7 +293,7 @@ def restore_to_source(video, fit, fps=None):
         soundtrack - pair the source's with pair_audio
     """
     command = "restore_to_source"
-    problem = restore_fps_problem(fps)
+    problem = source_fps_problem(fps)
     if problem is not None:
         raise ValueError(problem)
     fit = _read_fit(fit)
diff --git a/dw/tasks/video_handlers.py b/dw/tasks/video_handlers.py
index 57dfe0a5..dabfe64a 100644
--- a/dw/tasks/video_handlers.py
+++ b/dw/tasks/video_handlers.py
@@ -233,7 +233,15 @@ def _handle_restore_to_source(task, arguments, previous_pipelines):
 @register_command(
     "join_windows",
     implementation="dw.tasks.windows.join_windows",
-    domains={"num_frames": POSITIVE, "overlap": NON_NEGATIVE, "fps": POSITIVE},
+    parameter_descriptions={
+        "fps": (
+            'The joined video\'s frame rate. Omitted or "source", the rate '
+            "the source's file was read at; a number above zero is that rate. "
+            "No frames are added or dropped, and the source's audio is put "
+            "back over the frames at this rate."
+        ),
+    },
+    domains={"num_frames": POSITIVE, "overlap": NON_NEGATIVE},
     whole_numbers=("num_frames", "overlap"),
     choices={"curve": JOIN_WINDOWS_CURVES},
     static_check=join_windows_errors,
@@ -385,8 +393,8 @@ def _handle_crop_face_track(task, arguments, previous_pipelines):
     parameter_descriptions={
         "clip": (
             "The source video crop_face_track tracked - a file path, an "
-            "asset:/output: reference, or an earlier step's video. Its audio, "
-            "frame rate and shots are kept."
+            "asset:/output: reference, or an earlier step's video. Its audio "
+            "and shots are kept, and its frame rate unless 'fps' sets one."
         ),
         "repaired": (
             "The crops after a face-detail pass, still padded to the count "
@@ -401,6 +409,11 @@ def _handle_crop_face_track(task, arguments, previous_pipelines):
             "Match each crop's mean colour to the source inside the mask "
             "before blending."
         ),
+        "fps": (
+            'The repaired video\'s frame rate. Omitted or "source", the '
+            "clip's own; a number above zero is that rate. No frames are "
+            "added or dropped."
+        ),
     },
     domains={"feather": NON_NEGATIVE},
     static_check=paste_face_track_errors,
diff --git a/dw/tasks/windows.py b/dw/tasks/windows.py
index 29be15f2..803c225d 100644
--- a/dw/tasks/windows.py
+++ b/dw/tasks/windows.py
@@ -55,11 +55,13 @@
 from ..shots import remeasured_shots, shot_record
 from ..task_domains import (
     JOIN_WINDOWS_CURVES,
+    SOURCE_FPS,
     check_arguments,
     frames_to_samples,
     window_count,
     window_count_problem,
     real_number,
+    source_fps_problem,
     whole_number,
     window_overlap_problem,
 )
@@ -318,8 +320,10 @@ def join_windows(videos, source, num_frames, overlap, curve="cosine", fps=None):
             window_video
         curve: The blend's shape across a seam - "cosine"
             `(1 - cos(pi t)) / 2`, "smoothstep" `3t^2 - 2t^3`, or "linear" `t`
-        fps: Frame rate of the source. Defaults to the rate its file was read
-            at; needed only to put its audio back
+        fps: The joined video's frame rate - omitted or "source" for the
+            rate the source's file was read at, or a number above zero for
+            that rate. No frames are added or dropped for it; the source's
+            audio is put back over the frames at this rate
 
     Returns:
         One AudioVideo of exactly the source's frame count, at the windows'
@@ -332,14 +336,17 @@ def join_windows(videos, source, num_frames, overlap, curve="cosine", fps=None):
     """
     num_frames = whole_number(num_frames, "num_frames", "join_windows")
     overlap = whole_number(overlap, "overlap", "join_windows")
-    fps = real_number(fps, "fps", "join_windows")
+    problem = source_fps_problem(fps, "join_windows")
+    if problem is not None:
+        raise ValueError(problem)
+    fps = None if fps == SOURCE_FPS else real_number(fps, "fps", "join_windows")
     for name, value in (("num_frames", num_frames), ("overlap", overlap)):
         if not isinstance(value, numbers.Integral) or isinstance(value, bool):
             raise ValueError(
                 f"join_windows needs '{name}' as a whole number, got {value!r}"
             )
     num_frames, overlap = int(num_frames), int(overlap)
-    check_arguments("join_windows", num_frames=num_frames, overlap=overlap, fps=fps)
+    check_arguments("join_windows", num_frames=num_frames, overlap=overlap)
     if curve not in JOIN_WINDOWS_CURVES:
         raise ValueError(
             f"join_windows needs 'curve' as one of {list(JOIN_WINDOWS_CURVES)}, "
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 10f6f694..9a6e1d76 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -71,13 +71,15 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   smeared face in a wide shot, the rest left alone:
   `templates/ltx2/face-repair` (`strength` 0-4, default 2; describe the
   person in `prompt` to hold identity at 3-4). A near face comes back
-  untouched. Footage
+  untouched; the source's soundtrack, size and frame rate are kept
+  (`frame_rate` overrides the rate, never the frame count). Footage
   longer than `num_frames`: `templates/ltx2/restore-long` restores it window
   by window. Its `windows` list needs `ceil(source_frames / (num_frames -
   overlap))` entries, `index` 0 up - read `source_frames` from
   `get_gallery_metadata`, keep `num_frames` 121 and `overlap` 16 (105 new
   frames per window), and let `validate_workflow` name any entry to add or
-  drop. At most 32 windows.
+  drop. At most 32 windows. Written at the source's frame rate with its
+  soundtrack (`frame_rate` overrides the rate, never the frame count).
 - **Longer**: `templates/ltx2/extend-clip` continues an opening conditioned
   on all of it, not one frame; `clip` extends an existing clip (`width`/
   `height` matched, shorter than `num_frames`; clip_frames unused) instead
diff --git a/workflows/templates/ltx2/face-repair.json b/workflows/templates/ltx2/face-repair.json
index 949ac97a..9c8b57a7 100644
--- a/workflows/templates/ltx2/face-repair.json
+++ b/workflows/templates/ltx2/face-repair.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2FaceRepair",
-    "description": "Repairs small, broken faces in a clip from the asset library - the far faces of a wide shot that the model rendered as a smear - and leaves everything else alone. 'crop' (crop_face_track) finds and tracks the clip's main face, smooths the track, and cuts a 'crop_size' square around it on every frame, 'padding' face-widths of context on each side; 'refine' (LTX2RefinePipeline) re-renders those crops at the same size over a three-sigma schedule; 'pasted' (paste_face_track) feathers each repaired crop back into the source at the track's box, colour-matched to it. How much each frame is repaired comes from the face's size: full strength while the face is at most 'gate_full' of the frame's width, fading to none at 'gate_zero', so a near or medium face (and a clip with no face) comes back as the source. 'strength' is the refine's one knob: an integer 0-4 that picks one of five schedules lem-tuned on face crops, from 0 (lightest - the face stays close to the smear) to 4 (re-invented - sharp, but hair and clothing can drift); default 2, a defined face that keeps the person's colouring and dress. An out-of-range 'strength' is refused by the first step, before any pipeline loads. Replace the default prompt with a description of the person (hair, clothing, lighting) to hold identity at the higher strengths. The soundtrack, frame rate and shots are the source's own: the repaired picture is paired with them in final/, and the crops and refined crops are saved to intermediate/.",
+    "description": "Repairs small, broken faces in a clip from the asset library - the far faces of a wide shot that the model rendered as a smear - and leaves everything else alone. 'crop' (crop_face_track) finds and tracks the clip's main face, smooths the track, and cuts a 'crop_size' square around it on every frame, 'padding' face-widths of context on each side; 'refine' (LTX2RefinePipeline) re-renders those crops at the same size over a three-sigma schedule; 'pasted' (paste_face_track) feathers each repaired crop back into the source at the track's box, colour-matched to it. How much each frame is repaired comes from the face's size: full strength while the face is at most 'gate_full' of the frame's width, fading to none at 'gate_zero', so a near or medium face (and a clip with no face) comes back as the source. 'strength' is the refine's one knob: an integer 0-4 that picks one of five schedules lem-tuned on face crops, from 0 (lightest - the face stays close to the smear) to 4 (re-invented - sharp, but hair and clothing can drift); default 2, a defined face that keeps the person's colouring and dress. An out-of-range 'strength' is refused by the first step, before any pipeline loads. Replace the default prompt with a description of the person (hair, clothing, lighting) to hold identity at the higher strengths. The soundtrack and shots are the source's own, and the output has one frame per source frame, written at the source's frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. The repaired picture is saved to final/ with the source's soundtrack, and the crops and refined crops are saved to intermediate/.",
     "summary": "Repairs a wide shot's small, smeared face in place at strength 0-4; the rest and the soundtrack kept.",
     "cost": [
         {
@@ -25,7 +25,7 @@
         "gate_full": 0.03,
         "gate_zero": 0.06,
         "feather": 0.3,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "seed": 42
     },
     "variable_constraints": {
@@ -117,7 +117,6 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "intermediate"
             }
         },
@@ -226,7 +225,7 @@
                     "width": "variable:crop_size",
                     "height": "variable:crop_size",
                     "num_frames": null,
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
                     "stg_scale": 0.0,
@@ -238,7 +237,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
                 "subfolder": "intermediate"
             }
         },
@@ -250,12 +249,12 @@
                     "clip": "variable:source_video",
                     "repaired": "previous_result:refine",
                     "track": "previous_result:crop.track",
-                    "feather": "variable:feather"
+                    "feather": "variable:feather",
+                    "fps": "variable:frame_rate"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "final"
             }
         }
diff --git a/workflows/templates/ltx2/restore-long.json b/workflows/templates/ltx2/restore-long.json
index 0dbd93b9..a319b55b 100644
--- a/workflows/templates/ltx2/restore-long.json
+++ b/workflows/templates/ltx2/restore-long.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2DeblurLong",
-    "description": "Restores sharpness to an out-of-focus source longer than one LTX-2.5 bucket by cutting it into overlapping windows, running restore-deblur's in-context pass on each, and blending them back into one video of exactly the source's length. 'window' (window_video) cuts window i of 'num_frames' frames, sharing 'overlap' frames with the one before; 'restore' regenerates each window in focus with the window attached as the IC-LoRA reference; 'join' (join_windows) blends each seam's 'overlap' frames on the 'curve' ramp and puts the source's own soundtrack back over the whole result, so the model's generated audio is discarded. 'windows' is a list of {name, index} entries, one per window, and must be exactly ceil(source_frames / (num_frames - overlap)) long, indexes 0 upward: read the source's frame count first with get_gallery_metadata('asset:...'). The defaults (121-frame windows, overlap 16, stride 105) take 3 windows for a source of 211 to 315 frames - about 9 to 13 s at 24 fps; 2 windows cover up to 210 frames, 4 up to 420. validate_workflow refuses a list of the wrong length when the source is an asset: or output: reference, naming the count it needs, before any GPU time. At most 32 windows (for_each's limit), about 140 s at these defaults. 'num_frames' is LTX's 8 * n + 1 bucket and is the window length, not the output's: the output is the source's frame count. A larger 'overlap' hides per-window drift in colour or detail better and costs more windows. Everything else - the trained 960x544 / 24 fps bucket, 'lora_scale', the dual-panel prompt, spatial defocus only - is restore-deblur's; set 'width'/'height' to the source's own size.",
+    "description": "Restores sharpness to an out-of-focus source longer than one LTX-2.5 bucket by cutting it into overlapping windows, running restore-deblur's in-context pass on each, and blending them back into one video of exactly the source's length. 'window' (window_video) cuts window i of 'num_frames' frames, sharing 'overlap' frames with the one before; 'restore' regenerates each window in focus with the window attached as the IC-LoRA reference; 'join' (join_windows) blends each seam's 'overlap' frames on the 'curve' ramp and puts the source's own soundtrack back over the whole result, so the model's generated audio is discarded. The output is written at the source's frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. 'windows' is a list of {name, index} entries, one per window, and must be exactly ceil(source_frames / (num_frames - overlap)) long, indexes 0 upward: read the source's frame count first with get_gallery_metadata('asset:...'). The defaults (121-frame windows, overlap 16, stride 105) take 3 windows for a source of 211 to 315 frames - about 9 to 13 s at 24 fps; 2 windows cover up to 210 frames, 4 up to 420. validate_workflow refuses a list of the wrong length when the source is an asset: or output: reference, naming the count it needs, before any GPU time. At most 32 windows (for_each's limit), about 140 s at these defaults. 'num_frames' is LTX's 8 * n + 1 bucket and is the window length, not the output's: the output is the source's frame count. A larger 'overlap' hides per-window drift in colour or detail better and costs more windows. Everything else - the trained 960x544 / 24 fps bucket, 'lora_scale', the dual-panel prompt, spatial defocus only - is restore-deblur's; set 'width'/'height' to the source's own size.",
     "summary": "Sharpens out-of-focus footage longer than one bucket, a window at a time, joined back to the source's length.",
     "cost": [
         {
@@ -46,7 +46,7 @@
         "num_frames": 121,
         "overlap": 16,
         "curve": "cosine",
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "lora_scale": 1.0,
         "seed": 42
     },
@@ -84,8 +84,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "save": false,
-                "fps": "variable:frame_rate"
+                "save": false
             }
         },
         {
@@ -187,7 +186,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
@@ -219,7 +218,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
                 "subfolder": "intermediate"
             }
         },
@@ -232,12 +231,12 @@
                     "source": "variable:source_video",
                     "num_frames": "variable:num_frames",
                     "overlap": "variable:overlap",
-                    "curve": "variable:curve"
+                    "curve": "variable:curve",
+                    "fps": "variable:frame_rate"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "final"
             }
         }

From 200a338bac288e9ccb1d906efa5e215944c5ebd3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 19:29:03 -0500
Subject: [PATCH 066/125] test(tasks): #1106 - source fps tests for
 paste_face_track, join_windows and the ltx2 templates

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/task_domains.py              |  6 +--
 dw/task_problems.py             |  4 +-
 tests/test_catalog_structure.py |  3 ++
 tests/test_face_track.py        | 69 ++++++++++++++++++++++++++++++++-
 tests/test_join_windows.py      | 26 +++++++++++++
 5 files changed, 102 insertions(+), 6 deletions(-)

diff --git a/dw/task_domains.py b/dw/task_domains.py
index a9179cf8..23eedf9f 100644
--- a/dw/task_domains.py
+++ b/dw/task_domains.py
@@ -595,7 +595,7 @@ def join_windows_errors(arguments):
     return (
         choice_errors("join_windows", arguments)
         + window_video_errors(arguments, "join_windows")
-        + source_fps_errors(arguments, "join_windows")
+        + source_fps_problems(arguments, "join_windows")
     )
 
 
@@ -698,7 +698,7 @@ def source_fps_problem(fps, command="restore_to_source"):
     return domain_error(command, "fps", fps, POSITIVE)
 
 
-def source_fps_errors(arguments, command):
+def source_fps_problems(arguments, command):
     """[(argument, message)] for the rule a literal `fps` breaks before the
     run: neither "source" nor a positive number."""
     problem = source_fps_problem(arguments.get("fps"), command)
@@ -709,7 +709,7 @@ def restore_to_source_errors(arguments):
     """[(argument, message)] for the restore_to_source rule a literal
     workflow can break before it runs: an `fps` that is neither "source" nor
     a positive number."""
-    return source_fps_errors(arguments, "restore_to_source")
+    return source_fps_problems(arguments, "restore_to_source")
 
 
 def dissolve_shortfalls(frame_counts, dissolve_frames):
diff --git a/dw/task_problems.py b/dw/task_problems.py
index 5e42c2b2..3b273591 100644
--- a/dw/task_problems.py
+++ b/dw/task_problems.py
@@ -25,7 +25,7 @@
 
 from .references import DEFERRED, GATHER, is_ref
 from .script_lines import parse_lines, parse_shots, shot_names_error
-from .task_domains import as_number, choice_errors, source_fps_errors
+from .task_domains import as_number, choice_errors, source_fps_problems
 
 # ingredients_grid's literal choices, read by its registration and by
 # ingredients_grid_errors below, and its default image cap
@@ -210,7 +210,7 @@ def paste_face_track_errors(arguments):
     """[(argument, message)] for the paste_face_track rules a literal
     workflow can break before it runs: a feather past 1, and an `fps` that
     is neither "source" nor a positive number."""
-    problems = source_fps_errors(arguments, "paste_face_track")
+    problems = source_fps_problems(arguments, "paste_face_track")
     feather = arguments.get("feather")
     if is_ref(DEFERRED, feather):
         return problems
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 9f6b1205..7e228084 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -516,6 +516,9 @@ def test_no_stale_entry_in_the_allowlist():
 # colourisation of existing footage, with its cost block. Re-measured at
 # 12_357 after its description grew (plan v10): the compact view carries the
 # summary, not the description, so the budget stands.
+# Re-measured at 12_357 after `ltx2/face-repair` and `ltx2/restore-long` took
+# the source's frame rate (#1090, stage #1106, 2026-10-31): their summaries
+# did not change, so the budget stands.
 COMPACT_BUDGET = 12_400
 FILTERED_BUDGET = 1_500
 
diff --git a/tests/test_face_track.py b/tests/test_face_track.py
index 8ab14227..2b73979d 100644
--- a/tests/test_face_track.py
+++ b/tests/test_face_track.py
@@ -690,6 +690,28 @@ def test_identity_round_trip(self, stub_detector):
         assert max(x.mean() for x in d) < 0.1
         assert max(x.max() for x in d) <= 32
 
+    @pytest.mark.parametrize(
+        "fps, expected",
+        [(None, 8), ("source", 8), (12, 12), ("12", 12), (12.5, 12.5)],
+    )
+    def test_the_output_rate_is_the_clips_unless_fps_sets_one(
+        self, stub_detector, fps, expected
+    ):
+        """#1106: omitted or "source" keeps the 8 fps clip's rate; a number
+        sets it. The frame count never changes."""
+        arrays = self.frames()
+        clip, crops, track = tracked(arrays, fps=8)
+        kwargs = {} if fps is None else {"fps": fps}
+        out = ft.paste_face_track(clip, crops, track, **kwargs)
+        assert out.fps == expected
+        assert len(out.frames) == len(arrays)
+
+    @pytest.mark.parametrize("fps", [0, -1, "x"])
+    def test_a_bad_fps_is_refused_at_run_time(self, stub_detector, fps):
+        clip, crops, track = tracked(self.frames(), fps=8)
+        with pytest.raises(ValueError, match="fps"):
+            ft.paste_face_track(clip, crops, track, fps=fps)
+
     def test_strength_zero_is_an_exact_passthrough(self, stub_detector):
         arrays = self.frames()
         clip, crops, track = tracked(arrays)
@@ -776,7 +798,7 @@ def test_refusals(self, stub_detector):
 
 class TestPasteValidation:
     @staticmethod
-    def paste_workflow(feather):
+    def paste_workflow(feather, **extra):
         return {
             "id": "x",
             "steps": [
@@ -789,6 +811,7 @@ def paste_workflow(feather):
                             "repaired": "r.mp4",
                             "track": "t.json",
                             "feather": feather,
+                            **extra,
                         },
                     },
                 }
@@ -803,6 +826,22 @@ def test_bad_feather_is_refused(self, feather):
     def test_good_feather_is_accepted(self):
         assert task_argument_errors(self.paste_workflow(0.3)) == []
 
+    @pytest.mark.parametrize("fps", [0, -2, "x", True])
+    def test_a_bad_fps_is_refused(self, fps):
+        errors = task_argument_errors(self.paste_workflow(0.3, fps=fps))
+        assert [e["path"] for e in errors] == ["steps[0].task.arguments.fps"]
+
+    @pytest.mark.parametrize("fps", ["source", 12, "12", 23.976, "variable:rate"])
+    def test_source_a_number_or_a_deferred_fps_is_accepted(self, fps):
+        assert task_argument_errors(self.paste_workflow(0.3, fps=fps)) == []
+
+    def test_the_task_describes_fps(self):
+        from dw.introspection import describe_task
+
+        found = {p["name"]: p for p in describe_task("paste_face_track")["parameters"]}
+        assert found["fps"]["default"] is None
+        assert "source" in found["fps"]["description"]
+
 
 def test_paste_command_is_registered():
     from dw.tasks.task import _COMMAND_REGISTRY
@@ -1017,3 +1056,31 @@ def test_the_ltx_template_crop_step_passes_no_window_or_rate():
         s for s in steps if s.get("task", {}).get("command") == "crop_face_track"
     )
     assert not {"min_frames", "max_frames", "fps"} & set(crop["task"]["arguments"])
+
+
+def _template_steps(name):
+    path = os.path.join(
+        os.path.dirname(__file__), "..", "workflows", "templates", "ltx2", name
+    )
+    with open(path) as f:
+        workflow = json.load(f)
+    return workflow, {s["name"]: s for s in workflow["steps"]}
+
+
+@pytest.mark.parametrize(
+    "name, model, carrier, rateless",
+    [
+        ("face-repair.json", "refine", "pasted", ["crop", "pasted"]),
+        ("restore-long.json", "restore", "join", ["window", "join"]),
+    ],
+)
+def test_the_ltx_template_writes_at_the_source_rate(name, model, carrier, rateless):
+    """#1106: the model runs at a literal 24 fps; the step that writes the
+    output carries frame_rate, which defaults to the source's own."""
+    workflow, steps = _template_steps(name)
+    assert workflow["variables"]["frame_rate"] == "source"
+    assert steps[model]["pipeline"]["arguments"]["frame_rate"] == 24.0
+    assert steps[model]["result"]["fps"] == 24.0
+    assert steps[carrier]["task"]["arguments"]["fps"] == "variable:frame_rate"
+    for step in rateless:
+        assert "fps" not in steps[step].get("result", {})
diff --git a/tests/test_join_windows.py b/tests/test_join_windows.py
index 4efdf1b8..d9dbb496 100644
--- a/tests/test_join_windows.py
+++ b/tests/test_join_windows.py
@@ -87,6 +87,24 @@ def test_overlap_wider_than_the_stride_still_rejoins(self):
 
         assert numpy.array_equal(frames_as_array(joined), frames_as_array(clip))
 
+    @pytest.mark.parametrize(
+        "fps, expected", [("source", 25.0), (30, 30.0), ("12", 12.0)]
+    )
+    def test_fps_source_keeps_the_sources_rate_and_a_number_sets_one(
+        self, fps, expected
+    ):
+        """#1106: "source" is the source file's own rate."""
+        clip = _ramp_clip(50, fps=25.0)
+        joined = join_windows(_cut(clip, 17, 4), clip, 17, 4, fps=fps)
+        assert joined.fps == expected
+        assert len(joined.frames) == 50
+
+    @pytest.mark.parametrize("fps", [0, "x"])
+    def test_a_bad_fps_is_refused_at_run_time(self, fps):
+        clip = _ramp_clip(50, fps=25.0)
+        with pytest.raises(ValueError, match="fps"):
+            join_windows(_cut(clip, 17, 4), clip, 17, 4, fps=fps)
+
     def test_the_output_keeps_the_sources_fps(self):
         clip = _ramp_clip(50, fps=25.0)
         joined = join_windows(_cut(clip, 17, 4), clip, 17, 4)
@@ -288,6 +306,14 @@ class TestValidate:
     def test_a_good_literal_step_has_no_errors(self):
         assert not _validate(self.GOOD)
 
+    @pytest.mark.parametrize("fps", ["source", 24, "23.976", "variable:rate"])
+    def test_source_a_number_or_a_deferred_fps_is_fine(self, fps):
+        assert _validate(self.GOOD | {"fps": fps}) == []
+
+    @pytest.mark.parametrize("fps", [0, -1, "x"])
+    def test_a_bad_fps_is_reported_on_fps(self, fps):
+        assert [name for name, _ in _validate(self.GOOD | {"fps": fps})] == ["fps"]
+
     def test_the_default_curve_is_fine(self):
         good = {k: v for k, v in self.GOOD.items() if k != "curve"}
         assert not _validate(good)

From e748fc2f95734f66a53fda801ffb1b9612962cd3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 19:58:03 -0500
Subject: [PATCH 067/125] feat(templates): #1107 - upscale-clip, refine-clip
 and refine-in-place write at the source's frame rate

frame_rate defaults to "source" and is the output rate; the pipeline runs at
a literal 24.0 and stamps 24 on its own output; restore_to_source takes
fps: variable:frame_rate, and no step downstream declares a result.fps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/ltx-2.5/SKILL.md            |   4 +-
 tests/test_catalog_structure.py               |   3 +
 tests/test_fit_templates.py                   | 161 ++++++++++++++++++
 tests/test_ltx2_ic_loras.py                   |  11 +-
 workflows/templates/ltx2/refine-clip.json     |  18 +-
 workflows/templates/ltx2/refine-in-place.json |  15 +-
 workflows/templates/ltx2/upscale-clip.json    |  15 +-
 7 files changed, 197 insertions(+), 30 deletions(-)

diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 9a6e1d76..07040a87 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -67,7 +67,9 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   the source first and restore after: output exactly 2x the source (2x the kept region under crop) at its
   length, any aspect ratio letterboxed and cut back (`fit`), a short source
   held and trimmed. Soundtrack kept, silent source refused. Same size and length, no 2x:
-  `templates/ltx2/refine-in-place` (`strength` 0-4, default 2). A small,
+  `templates/ltx2/refine-in-place` (`strength` 0-4, default 2). All three
+  write at the source's frame rate (`frame_rate` overrides the rate, never
+  the frame count). A small,
   smeared face in a wide shot, the rest left alone:
   `templates/ltx2/face-repair` (`strength` 0-4, default 2; describe the
   person in `prompt` to hold identity at 3-4). A near face comes back
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 7e228084..43ec059b 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -519,6 +519,9 @@ def test_no_stale_entry_in_the_allowlist():
 # Re-measured at 12_357 after `ltx2/face-repair` and `ltx2/restore-long` took
 # the source's frame rate (#1090, stage #1106, 2026-10-31): their summaries
 # did not change, so the budget stands.
+# Re-measured at 12_357 after `ltx2/upscale-clip`, `refine-clip` and
+# `refine-in-place` took the source's frame rate (#1090, stage #1107,
+# 2026-10-31): their summaries did not change, so the budget stands.
 COMPACT_BUDGET = 12_400
 FILTERED_BUDGET = 1_500
 
diff --git a/tests/test_fit_templates.py b/tests/test_fit_templates.py
index 971b3705..1253aba4 100644
--- a/tests/test_fit_templates.py
+++ b/tests/test_fit_templates.py
@@ -10,6 +10,7 @@
 resolves them. Only the pipeline itself is not run.
 """
 
+import json
 import os
 
 import numpy
@@ -131,12 +132,42 @@ def test_restore_takes_the_pipeline_output_and_the_record(self, name, pipeline):
         assert steps["restore"]["task"]["arguments"] == {
             "video": f"previous_result:{pipeline}",
             "fit": "previous_result:fit.fit",
+            "fps": "variable:frame_rate",
         }
         assert steps["with_source_audio"]["task"]["arguments"]["video"] == (
             "previous_result:restore"
         )
 
 
+@pytest.mark.parametrize(
+    "name,fit,pipeline,restore",
+    [
+        ("upscale-clip", "fit", "upscaled", "restore"),
+        ("refine-clip", "fit", "refine", "restore"),
+        ("refine-in-place", "fitted", "refine", "restored"),
+    ],
+)
+def test_the_output_is_written_at_the_sources_frame_rate(name, fit, pipeline, restore):
+    """#1107 (#1090 plan v1): 'frame_rate' defaults to "source" and is the
+    output rate. The model runs at its 24 fps and stamps 24 on its own output;
+    restore_to_source sets the rate, and nothing downstream declares one."""
+    with open(os.path.join(TEMPLATES, f"{name}.json"), encoding="utf-8") as handle:
+        definition = json.load(handle)
+    steps = {s["name"]: s for s in definition["steps"]}
+
+    assert definition["variables"]["frame_rate"] == "source"
+    assert steps[pipeline]["pipeline"]["arguments"]["frame_rate"] == 24.0
+    assert steps[pipeline]["result"]["fps"] == 24.0
+    assert steps[restore]["task"]["arguments"]["fps"] == "variable:frame_rate"
+    assert steps[restore]["task"]["arguments"]["fit"] == f"previous_result:{fit}.fit"
+    names = list(steps)
+    for step in [steps[n] for n in names[names.index(restore) :]]:
+        assert "fps" not in step.get("result", {}), step
+    # no declared result.fps anywhere names the "source" sentinel
+    for step in definition["steps"]:
+        assert step.get("result", {}).get("fps") != "variable:frame_rate", step["name"]
+
+
 @pytest.fixture
 def eight_fps_clip(tmp_path, monkeypatch):
     library = tmp_path / "assets"
@@ -211,3 +242,133 @@ def test_frame_rate_overrides_the_rate_not_the_frames(
 
         assert shape["fps"] == pytest.approx(24.0)
         assert shape["frame_count"] == SRC_FRAMES
+
+
+@pytest.fixture
+def eight_fps_clip_with_audio(tmp_path, monkeypatch):
+    from tests.test_media_info import write_mp4
+
+    library = tmp_path / "assets"
+    library.mkdir()
+    write_mp4(library / "clip.mp4", frames=SRC_FRAMES, fps=8, width=SRC_W, height=SRC_H)
+    monkeypatch.setenv(ASSET_DIR_ENV_VAR, str(library))
+    return library
+
+
+@pytest.mark.parametrize(
+    "template,final_step",
+    [
+        ("refine-in-place", "with_source_audio"),
+        ("upscale-clip", "with_source_audio"),
+        ("refine-clip", "with_source_audio"),
+    ],
+)
+class TestTheFitShapedRoutesKeepTheSourcesRate:
+    """#1107 (#1090 plan v1, stage A): the real path. The template expanded
+    against an 8 fps asset with a soundtrack; every task step run through the
+    task dispatch in order, each pipeline step stood in for by a 24 fps clip
+    at its own size; the deliverable saved through its own result definition.
+    It comes back at the source's rate and frame count, with the source's
+    track paired to frames / rate, and no fps warning on the way."""
+
+    SMALL = {"width": 256, "height": 192, "num_frames": 25}
+
+    def written(self, template, final_step, tmp_path, warnings, **arguments):
+        import av
+
+        from dw.events import RunContext, activate_context, deactivate_context
+        from dw.media import stream_seconds, video_shape
+        from dw.media_types import AudioVideo
+
+        workflow = workflow_from_file(
+            os.path.join(TEMPLATES, f"{template}.json"), str(tmp_path / "out")
+        )
+        assert workflow.validation_errors(arguments=dict(self.SMALL, **arguments)) == []
+        steps = workflow.expanded_definition(arguments=dict(self.SMALL, **arguments))
+        steps = steps["steps"]
+        realize_args(steps, run_base_dir(workflow))
+
+        def record(event):
+            if event["event"] == "warning":
+                warnings.append(event.get("code") or event["message"])
+
+        token = activate_context(RunContext(on_event=record))
+        try:
+            results = {}
+            for step in steps:
+                result = Result(step.get("result", {}))
+                if "pipeline" in step:
+                    args = step["pipeline"]["arguments"]
+                    # refine-clip's latent upsampler doubles; its refine
+                    # renders at twice the working size
+                    scale = (
+                        2
+                        if template == "refine-clip" and step["name"] == "refine"
+                        else 1
+                    )
+                    frames = numpy.zeros(
+                        (
+                            self.SMALL["num_frames"],
+                            args.get("height", self.SMALL["height"]) * scale,
+                            args.get("width", self.SMALL["width"]) * scale,
+                            3,
+                        ),
+                        numpy.float32,
+                    )
+                    result.add_result(AudioVideo(frames, None, None, 24))
+                else:
+                    (task_arguments,) = get_iterations(
+                        step["task"]["arguments"], results
+                    )
+                    result.add_result(Task(step["task"], "cpu").run(task_arguments))
+                results[step["name"]] = result
+                if step["name"] == final_step:
+                    saved = tmp_path / "saved"
+                    saved.mkdir()
+                    result.save(str(saved), f"{template}-final.0")
+                    break
+        finally:
+            deactivate_context(token)
+
+        (name,) = [n for n in os.listdir(saved) if n.endswith(".mp4")]
+        path = str(saved / name)
+        with av.open(path) as container:
+            audio_seconds = stream_seconds(container.streams.audio[0])
+        return video_shape(path), audio_seconds
+
+    def test_the_default_writes_the_sources_rate(
+        self, template, final_step, eight_fps_clip_with_audio, tmp_path
+    ):
+        warnings = []
+        shape, audio_seconds = self.written(template, final_step, tmp_path, warnings)
+
+        assert shape["fps"] == pytest.approx(8.0)
+        assert shape["frame_count"] == SRC_FRAMES
+        assert audio_seconds == pytest.approx(SRC_FRAMES / 8, abs=0.1)
+        assert not any(
+            "video_fps_defaulted" in w or "fps_mismatch" in w for w in warnings
+        ), warnings
+
+    def test_frame_rate_overrides_the_rate_not_the_frames(
+        self, template, final_step, eight_fps_clip_with_audio, tmp_path
+    ):
+        warnings = []
+        shape, audio_seconds = self.written(
+            template, final_step, tmp_path, warnings, frame_rate=24
+        )
+
+        assert shape["fps"] == pytest.approx(24.0)
+        assert shape["frame_count"] == SRC_FRAMES
+        assert audio_seconds == pytest.approx(SRC_FRAMES / 24, abs=0.1)
+
+    @pytest.mark.parametrize("bad", ["fast", 0])
+    def test_a_bad_frame_rate_is_refused_at_validate(
+        self, template, final_step, bad, eight_fps_clip_with_audio, tmp_path
+    ):
+        workflow = workflow_from_file(
+            os.path.join(TEMPLATES, f"{template}.json"), str(tmp_path / "out")
+        )
+        errors = workflow.validation_errors(arguments={"frame_rate": bad})
+
+        assert errors
+        assert any("fps" in str(error) for error in errors), errors
diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index e8e01dea..838d00e0 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -130,9 +130,9 @@ def test_the_defaults_are_the_trained_bucket(self, name):
 
         assert (variables["width"], variables["height"]) == (width, height)
         assert variables["num_frames"] == frames
-        if name in ("alpha-matte", "restore-colorize"):
-            # #1079, #1080: the output is written at the source's rate; the model
-            # itself still runs at its trained 24 fps
+        if name in ("alpha-matte", "restore-colorize", "upscale-clip"):
+            # #1079, #1080, #1107: the output is written at the source's rate;
+            # the model itself still runs at its trained 24 fps
             pipeline = conditioned_step(name)["pipeline"]
             assert variables["frame_rate"] == "source"
             assert pipeline["arguments"]["frame_rate"] == 24.0
@@ -271,7 +271,12 @@ def test_the_deliverable_pairs_the_upscale_with_the_source(self):
         assert restore["task"]["arguments"] == {
             "video": "previous_result:upscaled",
             "fit": "previous_result:fit.fit",
+            "fps": "variable:frame_rate",
         }
+        # #1107: written at the rate restore carries, never a declared one
+        assert "fps" not in restore["result"]
+        assert "fps" not in paired["result"]
+        assert upscaled["result"]["fps"] == 24.0
         assert paired["task"]["command"] == "pair_audio"
         assert paired["task"]["arguments"] == {
             "video": "previous_result:restore",
diff --git a/workflows/templates/ltx2/refine-clip.json b/workflows/templates/ltx2/refine-clip.json
index 77fac271..006bb4a5 100644
--- a/workflows/templates/ltx2/refine-clip.json
+++ b/workflows/templates/ltx2/refine-clip.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2RefineClip",
-    "description": "Refines a clip from the asset library at exactly twice its size through LTX-2.5's stage-two path, starting from the clip's own latents rather than a reference: the latent upsampler VAE-encodes the source, doubles the latents, and 'refine' renoises them at 0.909375 and runs the three stage-two distilled sigmas - two-stage's refine pass, fed a clip dw did not make. Composition and motion are the source's; fine texture is regenerated at that noise level, so it is not a faithful resize. 'width'/'height' are the working size the source is fitted to (each divisible by 32), and 'num_frames' (8 * n + 1) its working length; the model renders at twice that, and a last step restores the result to twice the source's size at the source's own length - so the output is exactly 2x the source whatever its size (under crop, 2x the kept region, since crop cuts the edges off for good). A different aspect ratio is handled by 'fit': letterbox (default) pads it and the padding is cut back off, stretch resizes it, crop cuts it to fill. A source shorter than 'num_frames' is held on its last frame and trimmed back after; a longer one is cut to its opening 'num_frames' frames. Defaults work at 512x288, 121 frames, 24 fps - set 'frame_rate' to the source's (get_gallery_metadata('asset:...') reads it). Replace the default prompt with a description of the source's subject, setting, motion and lighting. The soundtrack is the source's own, not generated: its track is read and normalized to -3 dBFS as the first step, so a source with no soundtrack is refused there, before any pipeline loads, and the refined picture (saved to intermediate/) is paired with it, cut to the output length, in final/. Versus upscale-clip: that template re-renders with the source as an IC-LoRA reference (invented detail, gated LoRA download); this one keeps the source's own latents, needs no LoRA and denoises three sigmas rather than eight.",
+    "description": "Refines a clip from the asset library at exactly twice its size through LTX-2.5's stage-two path, starting from the clip's own latents rather than a reference: the latent upsampler VAE-encodes the source, doubles the latents, and 'refine' renoises them at 0.909375 and runs the three stage-two distilled sigmas - two-stage's refine pass, fed a clip dw did not make. Composition and motion are the source's; fine texture is regenerated at that noise level, so it is not a faithful resize. 'width'/'height' are the working size the source is fitted to (each divisible by 32), and 'num_frames' (8 * n + 1) its working length; the model renders at twice that, and a last step restores the result to twice the source's size at the source's own length - so the output is exactly 2x the source whatever its size (under crop, 2x the kept region, since crop cuts the edges off for good). A different aspect ratio is handled by 'fit': letterbox (default) pads it and the padding is cut back off, stretch resizes it, crop cuts it to fill. A source shorter than 'num_frames' is held on its last frame and trimmed back after; a longer one is cut to its opening 'num_frames' frames. Defaults work at 512x288, 121 frames; the model runs at its 24 fps, and the output is written at the source's frame rate, one frame per source frame - 'frame_rate' overrides that rate, never the frame count. Replace the default prompt with a description of the source's subject, setting, motion and lighting. The soundtrack is the source's own, not generated: its track is read and normalized to -3 dBFS as the first step, so a source with no soundtrack is refused there, before any pipeline loads, and the refined picture (saved to intermediate/) is paired with it, cut to the output length, in final/. Versus upscale-clip: that template re-renders with the source as an IC-LoRA reference (invented detail, gated LoRA download); this one keeps the source's own latents, needs no LoRA and denoises three sigmas rather than eight.",
     "summary": "2x latent refine of your own clip, any aspect or length, soundtrack kept. width/height = the working size.",
     "cost": [
         {
@@ -30,7 +30,7 @@
         "width": 512,
         "height": 288,
         "num_frames": 121,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "fit": "letterbox",
         "seed": 42
     },
@@ -126,8 +126,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "save": false,
-                "fps": "variable:frame_rate"
+                "save": false
             }
         },
         {
@@ -235,7 +234,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
                     "stg_scale": 0.0,
@@ -247,7 +246,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
                 "subfolder": "intermediate"
             }
         },
@@ -257,13 +256,13 @@
                 "command": "restore_to_source",
                 "arguments": {
                     "video": "previous_result:refine",
-                    "fit": "previous_result:fit.fit"
+                    "fit": "previous_result:fit.fit",
+                    "fps": "variable:frame_rate"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "save": false,
-                "fps": "variable:frame_rate"
+                "save": false
             }
         },
         {
@@ -278,7 +277,6 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "final"
             }
         }
diff --git a/workflows/templates/ltx2/refine-in-place.json b/workflows/templates/ltx2/refine-in-place.json
index 8f42a81c..6036e0fd 100644
--- a/workflows/templates/ltx2/refine-in-place.json
+++ b/workflows/templates/ltx2/refine-in-place.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2RefineInPlace",
-    "description": "Refines a clip from the asset library at its own size and length: 'fitted' fits the source into the model's working 'width' x 'height' x 'num_frames' (letterboxed by default; 'fit_mode' stretch or crop), 'refine' (LTX2RefinePipeline) VAE-encodes those frames and renoises them over a three-sigma schedule, and 'restored' puts the result back at the source's own size and frame count. 'strength' is the one knob: an integer 0-4 that picks one of five schedules lem-tuned for this route, from 0 (preserve - close to the source, light retexture) to 4 (reinterpret - framing and identity hold, skin texture, tone and expression are re-rendered); default 2, a subtle retexture. Each schedule's noise_scale is its first sigma, and all five denoise three sigmas, so run time is the same at every strength; an out-of-range 'strength' is refused by the first step, before any pipeline loads. This route is not a vendor recipe: Lightricks' own route for sharpening a clip is the Refine-Details IC-LoRA - use this to restyle detail at a chosen strength, not as a faithful sharpen. 'width'/'height' (each divisible by 32) and 'num_frames' (8 * n + 1) are the model's working size, not the source's: a longer source is cut to 'num_frames' and the restore keeps that cut length; a shorter one is held on its last frame and trimmed back. Replace the default prompt with a description of the source's subject, setting, motion and lighting. The soundtrack is the source's own, not generated: it is read and normalized to -3 dBFS first, so a source with no soundtrack is refused before any pipeline loads; the refined picture at the model's size is saved to intermediate/, and the restored picture paired with the source's track to final/. Versus refine-clip: that template always doubles the size at refine-clip's one fixed strength (0.909375); this one keeps the size and lets you choose the strength.",
+    "description": "Refines a clip from the asset library at its own size and length: 'fitted' fits the source into the model's working 'width' x 'height' x 'num_frames' (letterboxed by default; 'fit_mode' stretch or crop), 'refine' (LTX2RefinePipeline) VAE-encodes those frames and renoises them over a three-sigma schedule, and 'restored' puts the result back at the source's own size and frame count. 'strength' is the one knob: an integer 0-4 that picks one of five schedules lem-tuned for this route, from 0 (preserve - close to the source, light retexture) to 4 (reinterpret - framing and identity hold, skin texture, tone and expression are re-rendered); default 2, a subtle retexture. Each schedule's noise_scale is its first sigma, and all five denoise three sigmas, so run time is the same at every strength; an out-of-range 'strength' is refused by the first step, before any pipeline loads. This route is not a vendor recipe: Lightricks' own route for sharpening a clip is the Refine-Details IC-LoRA - use this to restyle detail at a chosen strength, not as a faithful sharpen. 'width'/'height' (each divisible by 32) and 'num_frames' (8 * n + 1) are the model's working size, not the source's: a longer source is cut to 'num_frames' and the restore keeps that cut length; a shorter one is held on its last frame and trimmed back. The model runs at its 24 fps, and the output is written at the source's frame rate - 'frame_rate' overrides that rate, never the frame count. Replace the default prompt with a description of the source's subject, setting, motion and lighting. The soundtrack is the source's own, not generated: it is read and normalized to -3 dBFS first, so a source with no soundtrack is refused before any pipeline loads; the refined picture at the model's size is saved to intermediate/, and the restored picture paired with the source's track to final/. Versus refine-clip: that template always doubles the size at refine-clip's one fixed strength (0.909375); this one keeps the size and lets you choose the strength.",
     "summary": "Same-size refine of your own clip at strength 0-4 (preserve to reinterpret), soundtrack kept.",
     "cost": [
         {
@@ -25,7 +25,7 @@
         "width": 960,
         "height": 544,
         "num_frames": 121,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "fit_mode": "letterbox",
         "seed": 42
     },
@@ -244,7 +244,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
                     "stg_scale": 0.0,
@@ -256,7 +256,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
                 "subfolder": "intermediate"
             }
         },
@@ -266,13 +266,13 @@
                 "command": "restore_to_source",
                 "arguments": {
                     "video": "previous_result:refine",
-                    "fit": "previous_result:fitted.fit"
+                    "fit": "previous_result:fitted.fit",
+                    "fps": "variable:frame_rate"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "save": false,
-                "fps": "variable:frame_rate"
+                "save": false
             }
         },
         {
@@ -287,7 +287,6 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "final"
             }
         }
diff --git a/workflows/templates/ltx2/upscale-clip.json b/workflows/templates/ltx2/upscale-clip.json
index ae570aff..106fdc67 100644
--- a/workflows/templates/ltx2/upscale-clip.json
+++ b/workflows/templates/ltx2/upscale-clip.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2UpscaleClip",
-    "description": "Re-renders a clip from the asset library at exactly twice its size with the spatial-upscaler in-context LoRA, the clip attached as the reference for the whole denoise - so composition, motion and subject carry over while fine detail (texture, edges, micro-contrast) is invented, not interpolated. It is a generative re-render, not a faithful resize: the vendor scopes it as a creative step, not for live-action footage where factual fidelity matters, and a heavily compressed source is 'restore-decompression''s job first. 'width'/'height' are the output size the model renders (each divisible by 32); a first step fits the source to half of it and 'num_frames', and a last step restores the result to twice the source's size at the source's own length - so the output is exactly 2x the source whatever its size (under crop, 2x the kept region, since crop cuts the edges off for good). A different aspect ratio is handled by 'fit': letterbox (default) pads it and the padding is cut back off, stretch resizes it, crop cuts it to fill. A source shorter than 'num_frames' is held on its last frame and trimmed back after; a longer one is cut to its opening 'num_frames' frames. Defaults render 960x544 at 121 frames, 24 fps - set 'frame_rate' to the source's (get_gallery_metadata('asset:...') reads it). Replace the default prompt with a description of the source's subject, setting, motion and lighting - the vendor card states no caption convention, and the prompt is what anchors the re-render to the scene. 'lora_scale' is 1.0 because the weights ship pre-scaled. The upscale is saved to intermediate/; the deliverable in final/ carries the source's own soundtrack cut to the output length, so a source with no audio fails at that step, after the upscale is saved.",
+    "description": "Re-renders a clip from the asset library at exactly twice its size with the spatial-upscaler in-context LoRA, the clip attached as the reference for the whole denoise - so composition, motion and subject carry over while fine detail (texture, edges, micro-contrast) is invented, not interpolated. It is a generative re-render, not a faithful resize: the vendor scopes it as a creative step, not for live-action footage where factual fidelity matters, and a heavily compressed source is 'restore-decompression''s job first. 'width'/'height' are the output size the model renders (each divisible by 32); a first step fits the source to half of it and 'num_frames', and a last step restores the result to twice the source's size at the source's own length - so the output is exactly 2x the source whatever its size (under crop, 2x the kept region, since crop cuts the edges off for good). A different aspect ratio is handled by 'fit': letterbox (default) pads it and the padding is cut back off, stretch resizes it, crop cuts it to fill. A source shorter than 'num_frames' is held on its last frame and trimmed back after; a longer one is cut to its opening 'num_frames' frames. Defaults render 960x544 at 121 frames; the model runs at its 24 fps, and the output is written at the source's frame rate, one frame per source frame - 'frame_rate' overrides that rate, never the frame count. Replace the default prompt with a description of the source's subject, setting, motion and lighting - the vendor card states no caption convention, and the prompt is what anchors the re-render to the scene. 'lora_scale' is 1.0 because the weights ship pre-scaled. The upscale is saved to intermediate/; the deliverable in final/ carries the source's own soundtrack cut to the output length, so a source with no audio fails at that step, after the upscale is saved.",
     "summary": "2x generative re-render of your own clip, any aspect or length, soundtrack kept. width/height = the render size.",
     "cost": [
         {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 3.4}
@@ -25,7 +25,7 @@
         "width": 960,
         "height": 544,
         "num_frames": 121,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "fit": "letterbox",
         "lora_scale": 1.0,
         "seed": 42
@@ -166,7 +166,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
@@ -198,7 +198,7 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
                 "subfolder": "intermediate"
             }
         },
@@ -208,13 +208,13 @@
                 "command": "restore_to_source",
                 "arguments": {
                     "video": "previous_result:upscaled",
-                    "fit": "previous_result:fit.fit"
+                    "fit": "previous_result:fit.fit",
+                    "fps": "variable:frame_rate"
                 }
             },
             "result": {
                 "content_type": "video/mp4",
-                "save": false,
-                "fps": "variable:frame_rate"
+                "save": false
             }
         },
         {
@@ -229,7 +229,6 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
                 "subfolder": "final"
             }
         }

From b375e3bb5be77177cea4ac766e046dfcac290688 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 20:02:17 -0500
Subject: [PATCH 068/125] docs(proposals): #1064 - design record for the
 remaining LTX-2.5 IC-LoRAs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/ltx2-ic-loras-complete.md        | 180 ++++++++++++++++++
 docs/proposals/todo.md                        |   9 +
 2 files changed, 189 insertions(+)
 create mode 100644 docs/proposals/complete/ltx2-ic-loras-complete.md

diff --git a/docs/proposals/complete/ltx2-ic-loras-complete.md b/docs/proposals/complete/ltx2-ic-loras-complete.md
new file mode 100644
index 00000000..327124b5
--- /dev/null
+++ b/docs/proposals/complete/ltx2-ic-loras-complete.md
@@ -0,0 +1,180 @@
+# `ltx2/alpha-matte` and `ltx2/restore-colorize`: the remaining LTX-2.5 IC-LoRAs (#1064)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). The plan went through ten versions on #1064; v10 was approved
+by Don on 2026-10-31 ("approve with defaults"). It was built as two stages:
+#1079 (stage A, Alpha-Gen) and #1080 (stage B, Colorization). Stage A was
+verified 2026-10-31 on develop @ 6b1dcfcb, stage B 2026-11-01 on develop
+@ fc0a40d9, both on lem over MCP.
+
+## The report
+
+The 2026-10-02 LTX-2.5 audit (`audits/2026-10-02-ltx-2.5-audit.md`,
+finding 5) listed four IC-LoRAs dw had not onboarded: Alpha-Gen 0.9,
+Clean-Plate 1.0, Colorization 0.9 and Day-To-Night 0.9. #1064 asked for at
+least Alpha-Gen as a template, with each of the others either onboarded or
+recorded as not loadable. SDR-To-HDR was out of scope (engine work).
+
+## Verdict
+
+**Build smaller.** Alpha-Gen ships as one template that writes a grey matte
+MP4. Colorization ships as `restore-deblur`'s pipeline wrapped in a fit and
+a restore. Clean-Plate and Day-To-Night are recorded as not onboarded.
+Demand evidence was thin (no field report asked for a matte or colourising,
+and the comparable `restore-*` templates had one run apiece). Alpha-Gen was
+worth it because nothing else in dw makes a per-frame soft matte; Don chose
+to include Colorization (Q1) since it fits the existing pattern.
+
+## What the plan found against the issue
+
+1. **Alpha-Gen is a plain IC-LoRA.** No `alpha_gen` pipeline is needed: the
+   card's recipe is the standard IC command with `--skip-stage-2`, an empty
+   prompt, strength 1.0 and `reference_downscale_factor` 1. Card limits:
+   up to 1920x1088, 8n+1 frames up to 145. Pad, don't stretch.
+2. **dw can't write video with alpha** (`dw/result.py` writes h264/yuv420p
+   only). The matte ships as a grey h264 MP4, white = foreground (Q2).
+3. **Clean-Plate and Day-To-Night don't fit the distilled IC template**
+   (distilled sigmas, guidance 1.0). Day-To-Night wants the dev recipe (30
+   steps, CFG 3-4, STG, a negative prompt) and a 24 fps re-encode;
+   Clean-Plate steers through the negative prompt, which guidance 1.0
+   ignores. Colorization fits (960x544x121 at 24 fps).
+4. **The registry's `workflow` field names an H3 transformer partition, not
+   a template** (Q5). LTX entries keep `workflow: null`; promotion links to
+   the template through an `evidence` item `{issue, note}`.
+5. **Nothing carried a source's frame rate past a pipeline step.**
+   `fit_to_model` kept the rate on the fitted video but not in its record,
+   so a template could not say "the source's rate" in JSON (Q6, Q7).
+6. **`restore-deblur` has no fit or restore step**, so following the
+   source's rate in Colorization meant `alpha-matte`'s fit → model → final
+   shape, not a one-line change.
+7. **The Colorization IC-LoRA colours only what the prompt names** (found
+   on stage B's first bounce). A generic prompt, or one naming only colour
+   categories, left the tester's clip grey (`1521f00bcf5a`,
+   `69e6bb12d56b`, both 36.7 dB PSNR against the source); a prompt that
+   described the clip and named its colours coloured it (`f80056a98e62`).
+   The stored default had coloured the build's own evidence clip only
+   because both were street scenes.
+
+## What was built
+
+### Engine: the source's frame rate through a fit (stage A)
+
+- `fit_to_model`'s record gains `source_fps` (the rate the source carries,
+  or `null`). Additive: an older record without it still restores.
+- `restore_to_source` gains an optional `fps`: omitted keeps today's
+  behaviour (the input video's rate); `"source"` uses the record's
+  `source_fps`, falling back to the input's rate; a positive number sets
+  it. Non-positive or other strings are refused at validate.
+- Documented in `docs/TASKS.md` and the task's parameter description. No
+  existing template changed in this feature; #1090 later moved
+  `upscale-clip`, `refine-clip`, `refine-in-place` and others onto it.
+
+### Stage A (#1079): `ltx2/alpha-matte`
+
+Commits: `71304eb8` (merged `ddb18608`), `9ec2df8a` (`c6a5878e`),
+`da0fd435` (`99af9674`), `a99b0886` (`6b1dcfcb`).
+
+- `workflows/templates/ltx2/alpha-matte.json`: `fit` (`fit_to_model`,
+  letterbox, downscale 1) → `matte` (`LTX2InContextPipeline` with
+  `restore-deblur`'s components and quantization, Alpha-Gen 0.9 at 1.0,
+  empty prompt, model and step rate fixed at the card's 24) → `final`
+  (`restore_to_source`, `fps: variable:frame_rate`).
+- Variables: `frame_rate` defaults to `"source"`; `width`/`height` 32n,
+  default 960x544 (Q4); `num_frames` 8n+1, 9-145; `seed`.
+- `vae`, `audio_vae` and `vocoder` are `residency: on_demand` (Q8 (a)), so
+  the 145-frame cap fits on a warm 24 GB card.
+- The description and skill row say a hard cut inside the clip can leak
+  source texture into the frames just after it, so matte one shot at a
+  time (Q9 (a)).
+- No own `vram_estimate`: it inherits deblur's through the same pipeline
+  identity. Catalog cost 3.9 on the RTX 3090.
+- `loras/ltx-2.5/ic-alpha-gen.json` promoted to `proven`, `workflow: null`,
+  evidence job `7219cf6b4cf5`.
+- Clean-Plate and Day-To-Night records (below), the `ltx-2.5` skill row,
+  family README, `docs/ARCHITECTURE.md` IC count, and test rows
+  (`TEMPLATE_PIPELINE_KEYS`, `CARDS`, `COMPACT_BUDGET`).
+
+Verified: 960x544x121 default matte with soft hair edges; 384x544 and
+544x544 sources come back at their own size; an 8 fps source gives an 8 fps
+matte with the same frame count, `frame_rate=24` overrides it; 145 frames
+on a warm card with no OOM (about 11.95 GB allocated after both arms); a
+cut-free 145-frame source (`ic-alpha/priya-cutfree-145f.mp4`) is clean on
+every checked frame, so the leak on `ep13-episode.mp4` comes from its cut
+at frame 141, not the length.
+
+### Stage B (#1080): `ltx2/restore-colorize`
+
+Commits: `416c4068`, `60aef905`, `9c49e16a` (merged `65f26281`);
+`9aff5c7d` (merged `3d211b35`).
+
+- `workflows/templates/ltx2/restore-colorize.json`: `fit` → `colorized`
+  (deblur's pipeline with `ltx-2.5-22b-ic-lora-colorization-0.9`,
+  `lora_scale` default 1.0, model and step rate fixed at 24) → `final`
+  (`restore_to_source`, `fps: variable:frame_rate`). The output keeps the
+  source's size and frame rate and has no soundtrack (Q11 (i)).
+- Stored prompt `ltx2/colorize_dual_panel`, in the card's dual-panel form.
+  It is a worked example: the caller writes a prompt that describes their
+  own clip and names its colours (Q10 (a)). The template description, the
+  prompt's description and the skill row say so, and the skill tells the
+  composing agent to look at a frame (`get_output_frames`) first.
+- `loras/ltx-2.5/ic-colorization.json` promoted to `proven`, `workflow:
+  null`, evidence naming the template and `f80056a98e62`.
+- Skill row, README, ARCHITECTURE count, `TEMPLATE_PIPELINE_KEYS`, `CARDS`,
+  `_IC_LORA_CONVENTION` and `COMPACT_BUDGET`.
+
+Verified with clip-matched prompts: the black-and-white office fixture at
+121 frames comes back in the named colours, same scene, no audio stream
+(job `4e475c7b92cb`); an 8 fps source follows its rate and `frame_rate=24`
+overrides it with near-identical frames (41.0 dB, SSIM 0.982); a 384x544
+portrait comes back at its own size with no letterbox band or edge bleed.
+
+### Records for the two not onboarded
+
+`ic-clean-plate` and `ic-day-to-night` stay `trial`, `workflow: null`, each
+with an `evidence` item `{issue: 1064, note}`:
+- **Clean-Plate** reopens with a guided (dev/full transformer) IC route in
+  dw, or a field report needing subject removal across a clip.
+- **Day-To-Night** reopens with the same guided route plus fps resampling
+  in `fit_to_model`, or a field report.
+
+## Deferred, and why
+
+- **RGBA / ProRes 4444 / PNG-sequence output and a composite task** (Q2):
+  a grey matte is enough for an editor; dw has no alpha writer.
+- **Mattes past 145 frames:** the card's limit.
+- **Shot-cut detection in `fit_to_model`** (Q9 (d)): the description's
+  one-shot-at-a-time rule covers it; a feature of its own if wanted.
+- **An engine policy for releasing warm-worker GPU state** (Q8 (c)):
+  `on_demand` residency cured the warm OOM without it.
+- **An auto-caption step in `restore-colorize`** (Q10 (b)): the composing
+  agent can see the frame and write the prompt.
+- **The source's soundtrack through `restore-colorize`** (Q11 (ii)).
+- **Clean-Plate, Day-To-Night, SDR-To-HDR:** recorded above / out of scope.
+- **Moving other templates to the source's rate:** Don's Q7 audit, filed
+  separately as #1090.
+
+## Cost and bounces
+
+No stage comment names a `usage:` figure, so cost is left out. The plan
+estimated stage B's first build at about $3.5.
+
+- **Stage A (#1079): 3 bounces, 4 builds.**
+  1. M-F223: the registry `workflow` field was set to a template name; it
+     names an H3 partition (Q5). Re-planned with the frame-rate change (Q6).
+  2. M-F225's 145-frame cap OOMed on a warm card (job `376a537cc3e6`).
+     Fixed by on-demand decoders (Q8 (a)).
+  3. M-F272: a source-texture leak on frame 144, just after a shot cut.
+     Fixed by the description (Q9 (a)); the cut-free arm confirmed the
+     cause.
+- **Stage B (#1080): 1 bounce, 2 builds.** The colour clause failed on all
+  three fixtures with the default prompt (finding 7). Re-planned (v9/v10)
+  to put the per-clip prompt on the caller. One verify session in between
+  did not run (incomplete MCP surface) and is not counted.
+- A licence gate on the Colorization LoRA parked stage B once until Don
+  accepted it on Hugging Face (2026-10-31).
+
+## Overlap left open
+
+- **#597** (parked): the Restore 1.0 IC-LoRA "includes colourisation". If it
+  is onboarded, its description should say when to pick it over
+  `restore-colorize`.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 27aeea5e..d4c18880 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -37,6 +37,15 @@ remaining deferred fix is recorded in
 
 ## Shipped since the ranking
 
+- **The remaining LTX-2.5 IC-LoRAs: `ltx2/alpha-matte` and
+  `ltx2/restore-colorize`** (#1064, stages #1079-#1080), shipped
+  2026-11-01. A grey soft-matte MP4 at the source's size and frame rate
+  (Alpha-Gen), and black-and-white colourising with a caller-written,
+  clip-matched prompt (Colorization), plus `source_fps` on the fit record
+  and `fps` on `restore_to_source`. Clean-Plate and Day-To-Night are
+  recorded in their registry entries as not onboarded. Record, including
+  what was deferred (alpha output, cut detection, auto-captioning, the
+  colourised clip's soundtrack): `complete/ltx2-ic-loras-complete.md`.
 - **H3 quality ramp: draft -> final tiers** (#862, stage #882), shipped
   2026-10-15. A `## Ramp` section in the `minimax-h3` skill's
   `references/quality-and-speed.md`, not a new skill: TV L1 -> L7, cinema

From 1d1a4eebacc42a554bd19379ac1922d9fc47ee59 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 20:45:22 -0500
Subject: [PATCH 069/125] feat(templates): #1108 - restore-deblur and
 restore-decompression fit, then restore to the source

Both now take restore-colorize's shape: fit (letterbox, downscale 1) ->
the IC pass at 24 fps -> restore_to_source at 'frame_rate' (default
"source"), so the output comes back at the source's size and rate.
Declared traits [needs-input-media]: restore_to_source drops audio.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/ltx-2.5/SKILL.md            |  3 +-
 tests/test_catalog_structure.py               |  3 +
 tests/test_fit_templates.py                   | 34 +++++++-
 tests/test_ltx2_ic_loras.py                   | 81 ++++++++++++++++++-
 workflows/templates/ltx2/README.md            |  4 +-
 workflows/templates/ltx2/restore-deblur.json  | 48 +++++++++--
 .../templates/ltx2/restore-decompression.json | 48 +++++++++--
 7 files changed, 198 insertions(+), 23 deletions(-)

diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 07040a87..229ce46a 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -56,7 +56,8 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
 - **Repairing the user's footage**: `templates/ltx2/restore-deblur` for
   spatial defocus, `templates/ltx2/restore-decompression` for low-bitrate
   artefacts, `templates/ltx2/restore-colorize` for black-and-white or
-  washed-out footage (keeps the source's size and rate, no soundtrack). It
+  washed-out footage. All three come back at the source's size and frame
+  rate (`frame_rate` overrides the rate), with no soundtrack. Colorize
   colours only what the prompt names: look at a source frame
   (`get_output_frames`) and write both prompt panels for that clip, naming
   its colours - the default is an example and leaves an unlike clip grey. Each inverts one defect and no other - neither upscales or
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 43ec059b..67c5226c 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -522,6 +522,9 @@ def test_no_stale_entry_in_the_allowlist():
 # Re-measured at 12_357 after `ltx2/upscale-clip`, `refine-clip` and
 # `refine-in-place` took the source's frame rate (#1090, stage #1107,
 # 2026-10-31): their summaries did not change, so the budget stands.
+# Re-measured at 12_344 after `ltx2/restore-deblur` and `restore-decompression`
+# took restore-colorize's fit shape (#1090, stage #1108, 2026-10-31): both
+# summaries got shorter, so the budget stands.
 COMPACT_BUDGET = 12_400
 FILTERED_BUDGET = 1_500
 
diff --git a/tests/test_fit_templates.py b/tests/test_fit_templates.py
index 1253aba4..a1bbdfee 100644
--- a/tests/test_fit_templates.py
+++ b/tests/test_fit_templates.py
@@ -145,6 +145,8 @@ def test_restore_takes_the_pipeline_output_and_the_record(self, name, pipeline):
         ("upscale-clip", "fit", "upscaled", "restore"),
         ("refine-clip", "fit", "refine", "restore"),
         ("refine-in-place", "fitted", "refine", "restored"),
+        ("restore-deblur", "fit", "restored", "final"),
+        ("restore-decompression", "fit", "restored", "final"),
     ],
 )
 def test_the_output_is_written_at_the_sources_frame_rate(name, fit, pipeline, restore):
@@ -181,17 +183,28 @@ def eight_fps_clip(tmp_path, monkeypatch):
 
 @pytest.mark.parametrize(
     "template,model_step",
-    [("alpha-matte", "matte"), ("restore-colorize", "colorized")],
+    [
+        ("alpha-matte", "matte"),
+        ("restore-colorize", "colorized"),
+        ("restore-deblur", "restored"),
+        ("restore-decompression", "restored"),
+    ],
 )
 class TestTheModelPassKeepsTheSourcesRate:
-    """#1079, #1080: the model runs at its 24 fps, but the output is written
+    """#1079, #1080, #1108: the model runs at its 24 fps, but the output is written
     at the source's own rate unless 'frame_rate' says otherwise. The real
     path: the template expanded against an 8 fps asset, `fit` through the
     task dispatch, the model step's 24 fps output standing in for the
     pipeline, and `final` run and saved through its own result definition."""
 
-    # A small working size keeps the stand-in matte cheap
-    SMALL = {"width": 256, "height": 192, "num_frames": 25}
+    # A small working size keeps the stand-in matte cheap; the fixture's
+    # asset is named, since deblur and decompression default to other names
+    SMALL = {
+        "width": 256,
+        "height": 192,
+        "num_frames": 25,
+        "source_video": "asset:clip.mp4",
+    }
 
     def written(self, template, model_step, tmp_path, **arguments):
         from dw.media import video_shape
@@ -372,3 +385,16 @@ def test_a_bad_frame_rate_is_refused_at_validate(
 
         assert errors
         assert any("fps" in str(error) for error in errors), errors
+
+
+@pytest.mark.parametrize("template", ["restore-deblur", "restore-decompression"])
+@pytest.mark.parametrize("bad", ["fast", 0])
+def test_a_bad_restore_frame_rate_is_refused_at_validate(template, bad, tmp_path):
+    """#1108: 'frame_rate' reaches restore_to_source's `fps`, whose static
+    check refuses anything but "source" or a positive number."""
+    workflow = workflow_from_file(
+        os.path.join(TEMPLATES, f"{template}.json"), str(tmp_path / "out")
+    )
+    errors = workflow.validation_errors(arguments={"frame_rate": bad})
+
+    assert any("fps" in str(error) for error in errors), errors
diff --git a/tests/test_ltx2_ic_loras.py b/tests/test_ltx2_ic_loras.py
index 838d00e0..49c99243 100644
--- a/tests/test_ltx2_ic_loras.py
+++ b/tests/test_ltx2_ic_loras.py
@@ -130,8 +130,14 @@ def test_the_defaults_are_the_trained_bucket(self, name):
 
         assert (variables["width"], variables["height"]) == (width, height)
         assert variables["num_frames"] == frames
-        if name in ("alpha-matte", "restore-colorize", "upscale-clip"):
-            # #1079, #1080, #1107: the output is written at the source's rate;
+        if name in (
+            "alpha-matte",
+            "restore-colorize",
+            "restore-deblur",
+            "restore-decompression",
+            "upscale-clip",
+        ):
+            # #1079, #1080, #1107, #1108: the output is written at the source's rate;
             # the model itself still runs at its trained 24 fps
             pipeline = conditioned_step(name)["pipeline"]
             assert variables["frame_rate"] == "source"
@@ -201,14 +207,20 @@ class TestTheTemplatesThatReadFootageTheyDidNotGenerate:
     on an earlier step's output instead."""
 
     @pytest.mark.parametrize("name", ["restore-deblur", "restore-decompression"])
-    def test_the_reference_is_the_callers_own_clip(self, name):
+    def test_the_reference_is_the_callers_own_clip_fitted(self, name):
+        """#1108: the caller's clip reaches the model through `fit`, so a
+        different aspect ratio is letterboxed rather than cropped by the
+        pipeline's own preprocess."""
         (reference,) = conditioned_step(name)["pipeline"]["arguments"][
             "reference_conditions"
         ]
         frames = reference["from_arguments"]["frames"]
+        fit = definition(name)["steps"][0]
 
         assert frames["media_type"] == "video"
-        assert frames["location"] == "variable:source_video"
+        assert frames["location"] == "previous_result:fit.video"
+        assert fit["name"] == "fit"
+        assert fit["task"]["arguments"]["video"] == "variable:source_video"
         assert definition(name)["variables"]["source_video"].startswith("asset:")
 
     def test_the_upscaler_references_the_callers_clip_fitted_to_half_size(self):
@@ -375,3 +387,64 @@ def test_it_fits_by_letterbox_and_restores_at_the_frame_rate(self):
         assert final["task"]["command"] == "restore_to_source"
         assert final["task"]["arguments"]["fps"] == "variable:frame_rate"
         assert "fps" not in final["result"]
+
+
+@pytest.mark.parametrize("name", ["restore-deblur", "restore-decompression"])
+class TestTheDeblurAndDecompressionTemplatesAreColorizesShape:
+    """#1108 (#1090 plan v1, stage C): fit -> the IC step held at 24 -> final,
+    as restore-colorize (#1080), so the output comes back at the source's size
+    and frame rate. `restore_to_source` drops audio, so the output is silent
+    and the declared traits say so."""
+
+    def test_the_steps_are_fit_restored_final(self, name):
+        fit, restored, final = definition(name)["steps"]
+
+        assert fit["task"] == {
+            "command": "fit_to_model",
+            "arguments": {
+                "video": "variable:source_video",
+                "width": "variable:width",
+                "height": "variable:height",
+                "num_frames": "variable:num_frames",
+                "mode": "letterbox",
+                "downscale": 1,
+            },
+        }
+        assert fit["result"]["save"] is False
+        assert restored["name"] == "restored"
+        assert restored["result"] == {
+            "content_type": "video/mp4",
+            "fps": 24.0,
+            "save": False,
+        }
+        assert final["task"] == {
+            "command": "restore_to_source",
+            "arguments": {
+                "video": "previous_result:restored",
+                "fit": "previous_result:fit.fit",
+                "fps": "variable:frame_rate",
+            },
+        }
+        assert "fps" not in final["result"]
+        assert final["result"]["subfolder"] == "final"
+
+    def test_it_keeps_colorizes_pipeline_identity(self, name):
+        from dw.vram_estimate import pipeline_identity
+
+        assert pipeline_identity(conditioned_step(name)) == (
+            pipeline_identity(conditioned_step("restore-colorize"))
+        )
+
+    def test_the_declared_traits_carry_no_audio(self, name):
+        assert definition(name)["traits"] == ["needs-input-media"]
+
+    def test_the_description_says_size_and_rate(self, name):
+        workflow = definition(name)
+
+        assert (
+            "comes back at the source's size and frame rate"
+            in (workflow["description"])
+        )
+        assert "'frame_rate' overrides the rate" in workflow["description"]
+        assert "no soundtrack" in workflow["description"]
+        assert "source's size and frame rate" in workflow["summary"]
diff --git a/workflows/templates/ltx2/README.md b/workflows/templates/ltx2/README.md
index 56423643..052f89f0 100644
--- a/workflows/templates/ltx2/README.md
+++ b/workflows/templates/ltx2/README.md
@@ -66,8 +66,8 @@ generated. Deblur, decompression and colorization are 0.9 preview weights traine
 
 | Example | What it introduces |
 | ------- | ------------------ |
-| [restore-deblur.json](restore-deblur.json) | Spatial defocus only - not motion blur, not noise, not low resolution. Lower `lora_scale` toward 0.8 if it over-sharpens into haloing (#152) |
-| [restore-decompression.json](restore-decompression.json) | Macroblocking, chroma bleed, ringing and banding from a low bit-rate source. Not a deblur and not an upscale (#152) |
+| [restore-deblur.json](restore-deblur.json) | Spatial defocus only - not motion blur, not noise, not low resolution. Fitted by letterbox and cropped back, so it comes back at the source's size and frame rate, with no soundtrack. Lower `lora_scale` toward 0.8 if it over-sharpens into haloing (#152, #1090) |
+| [restore-decompression.json](restore-decompression.json) | Macroblocking, chroma bleed, ringing and banding from a low bit-rate source, at the source's size and frame rate, with no soundtrack. Not a deblur and not an upscale (#152, #1090) |
 | [restore-colorize.json](restore-colorize.json) | Natural colour for black-and-white or washed-out footage, at the source's size and frame rate; only the colour changes. The prompt keeps the dual-panel convention and must describe your clip and name its colours: the LoRA colours only what the prompt names, and the default prompt (a street scene) leaves an unlike clip grey. Lower `lora_scale` toward 0.8 if colour oversaturates or bleeds (#1064) |
 | [alpha-matte.json](alpha-matte.json) | A soft per-frame alpha matte of the source - grey h264, white = foreground, at the source's size - for compositing in an editor. No prompt: the Alpha-Gen card's model picks the foreground itself. `num_frames` caps at 145, past which RGB leaks into the matte; the card's 1920x1088 ceiling is not a 24 GB size (#1064) |
 | [restore-long.json](restore-long.json) | `restore-deblur` over a source longer than one bucket: `window_video` slices it, a `for_each` restores each window, `join_windows` cross-fades them back to the source's length. `windows` is `ceil(source_frames / (num_frames - overlap))` entries, checked by `validate_workflow` (#601) |
diff --git a/workflows/templates/ltx2/restore-deblur.json b/workflows/templates/ltx2/restore-deblur.json
index 09c465f3..6a9f56d1 100644
--- a/workflows/templates/ltx2/restore-deblur.json
+++ b/workflows/templates/ltx2/restore-deblur.json
@@ -1,7 +1,10 @@
 {
     "id": "LTX2Deblur",
-    "description": "Restores sharpness to out-of-focus footage by regenerating it in focus, with the blurry clip attached as an in-context reference for the whole denoise - so the subject, the framing and the background geometry are the ones that were shot and only the focus changes. A different trade from re-rendering: 'two-stage' invents a sharper version of a scene it generated, this one reads a scene it did not. The LoRA is a 0.9 preview weight trained on spatial defocus only - motion blur, noise, compression artefacts and low resolution are not what it inverts, and 'restore-decompression' is the sibling for the third of those. Trained at 960x544, 121 frames, 24 fps, which is what the defaults are; generating far above that bucket weakens the effect, so raise the size only with a measurement in hand. 'lora_scale' is 1.0 because the weights ship pre-scaled - lower it toward 0.8 if the result over-sharpens into haloing or ringing. The prompt follows the trained dual-panel convention ('Reference shows ... DEBLUR ... only focus and sharpness differ'), because the reference does most of the work and the prompt is what anchors the scene and the intent.",
-    "summary": "Sharpens out-of-focus footage by regenerating it in focus, the blurry clip attached as an in-context reference.",
+    "description": "Restores sharpness to out-of-focus footage by regenerating it in focus, with the blurry clip attached as an in-context reference for the whole denoise - so the subject, the framing and the background geometry are the ones that were shot and only the focus changes. A different trade from re-rendering: 'two-stage' invents a sharper version of a scene it generated, this one reads a scene it did not. The LoRA is a 0.9 preview weight trained on spatial defocus only - motion blur, noise, compression artefacts and low resolution are not what it inverts, and 'restore-decompression' is the sibling for the third of those. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so it comes back at the source's size and frame rate; 'frame_rate' overrides the rate, never the frame count (the model itself runs at its 24 fps). A longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has no soundtrack. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket weakens the effect, so raise the size only with a measurement in hand. 'lora_scale' is 1.0 because the weights ship pre-scaled - lower it toward 0.8 if the result over-sharpens into haloing or ringing. The prompt follows the trained dual-panel convention ('Reference shows ... DEBLUR ... only focus and sharpness differ'), because the reference does most of the work and the prompt is what anchors the scene and the intent.",
+    "summary": "Sharpens out-of-focus footage by regenerating it in focus, keeping the source's size and frame rate.",
+    "traits": [
+        "needs-input-media"
+    ],
     "cost": [
         {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 3.4}
     ],
@@ -25,7 +28,7 @@
         "width": 960,
         "height": 544,
         "num_frames": 121,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "lora_scale": 1.0,
         "seed": 42
     },
@@ -49,6 +52,24 @@
     },
     "seed": "variable:seed",
     "steps": [
+        {
+            "name": "fit",
+            "task": {
+                "command": "fit_to_model",
+                "arguments": {
+                    "video": "variable:source_video",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_frames": "variable:num_frames",
+                    "mode": "letterbox",
+                    "downscale": 1
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "save": false
+            }
+        },
         {
             "name": "restored",
             "pipeline": {
@@ -147,7 +168,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
@@ -162,7 +183,7 @@
                             "from_arguments": {
                                 "frames": {
                                     "media_type": "video",
-                                    "location": "variable:source_video"
+                                    "location": "previous_result:fit.video"
                                 },
                                 "strength": 1.0
                             }
@@ -182,7 +203,22 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
+                "save": false
+            }
+        },
+        {
+            "name": "final",
+            "task": {
+                "command": "restore_to_source",
+                "arguments": {
+                    "video": "previous_result:restored",
+                    "fit": "previous_result:fit.fit",
+                    "fps": "variable:frame_rate"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
                 "subfolder": "final"
             }
         }
diff --git a/workflows/templates/ltx2/restore-decompression.json b/workflows/templates/ltx2/restore-decompression.json
index 21f2b699..6ebb89a7 100644
--- a/workflows/templates/ltx2/restore-decompression.json
+++ b/workflows/templates/ltx2/restore-decompression.json
@@ -1,7 +1,10 @@
 {
     "id": "LTX2Decompression",
-    "description": "Removes compression artefacts - macroblocking, chroma bleed, ringing, banding - from a low bit-rate clip by regenerating it clean, with the compressed clip attached as an in-context reference for the whole denoise, so identity, framing and geometry are the source's and only the artefacts go. A different trade from re-rendering: it reads footage it did not generate. The LoRA is a 0.9 preview weight and targets compression only - defocus blur is 'restore-deblur', and motion blur, grain and low resolution are outside what it was trained to invert. Trained at 960x544, 121 frames, 24 fps, which is what the defaults are; generating far above that bucket leaves artefacts in the high-frequency detail. The prompt follows the trained convention ('Reference shows ... heavily compressed ... ENHANCE QUALITY ... only compression artifacts and image quality differ'), describing the same scene in both halves.",
-    "summary": "Strips macroblocking and ringing from a low bit-rate clip, the compressed clip attached as an in-context reference.",
+    "description": "Removes compression artefacts - macroblocking, chroma bleed, ringing, banding - from a low bit-rate clip by regenerating it clean, with the compressed clip attached as an in-context reference for the whole denoise, so identity, framing and geometry are the source's and only the artefacts go. A different trade from re-rendering: it reads footage it did not generate. The LoRA is a 0.9 preview weight and targets compression only - defocus blur is 'restore-deblur', and motion blur, grain and low resolution are outside what it was trained to invert. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so it comes back at the source's size and frame rate; 'frame_rate' overrides the rate, never the frame count (the model itself runs at its 24 fps). A longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has no soundtrack. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket leaves artefacts in the high-frequency detail. The prompt follows the trained convention ('Reference shows ... heavily compressed ... ENHANCE QUALITY ... only compression artifacts and image quality differ'), describing the same scene in both halves.",
+    "summary": "Strips macroblocking and ringing from a low bit-rate clip, keeping the source's size and frame rate.",
+    "traits": [
+        "needs-input-media"
+    ],
     "cost": [
         {"device": "cuda", "name": "RTX 3090", "vram_gb": 24, "minutes": 3.4}
     ],
@@ -25,7 +28,7 @@
         "width": 960,
         "height": 544,
         "num_frames": 121,
-        "frame_rate": 24.0,
+        "frame_rate": "source",
         "lora_scale": 1.0,
         "seed": 42
     },
@@ -49,6 +52,24 @@
     },
     "seed": "variable:seed",
     "steps": [
+        {
+            "name": "fit",
+            "task": {
+                "command": "fit_to_model",
+                "arguments": {
+                    "video": "variable:source_video",
+                    "width": "variable:width",
+                    "height": "variable:height",
+                    "num_frames": "variable:num_frames",
+                    "mode": "letterbox",
+                    "downscale": 1
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
+                "save": false
+            }
+        },
         {
             "name": "restored",
             "pipeline": {
@@ -147,7 +168,7 @@
                     "width": "variable:width",
                     "height": "variable:height",
                     "num_frames": "variable:num_frames",
-                    "frame_rate": "variable:frame_rate",
+                    "frame_rate": 24.0,
                     "sigmas": "constant:diffusers.pipelines.ltx2.utils.DISTILLED_SIGMA_VALUES",
                     "guidance_scale": 1.0,
                     "audio_guidance_scale": 1.0,
@@ -162,7 +183,7 @@
                             "from_arguments": {
                                 "frames": {
                                     "media_type": "video",
-                                    "location": "variable:source_video"
+                                    "location": "previous_result:fit.video"
                                 },
                                 "strength": 1.0
                             }
@@ -182,7 +203,22 @@
             },
             "result": {
                 "content_type": "video/mp4",
-                "fps": "variable:frame_rate",
+                "fps": 24.0,
+                "save": false
+            }
+        },
+        {
+            "name": "final",
+            "task": {
+                "command": "restore_to_source",
+                "arguments": {
+                    "video": "previous_result:restored",
+                    "fit": "previous_result:fit.fit",
+                    "fps": "variable:frame_rate"
+                }
+            },
+            "result": {
+                "content_type": "video/mp4",
                 "subfolder": "final"
             }
         }

From af5a38dd5d2737270294202445242c60dbe56f72 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 21:11:15 -0500
Subject: [PATCH 070/125] docs(proposals): #1090 - design record for
 one-for-one templates following the source's frame rate

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../source-fps-one-for-one-complete.md        | 140 ++++++++++++++++++
 docs/proposals/todo.md                        |   9 ++
 2 files changed, 149 insertions(+)
 create mode 100644 docs/proposals/complete/source-fps-one-for-one-complete.md

diff --git a/docs/proposals/complete/source-fps-one-for-one-complete.md b/docs/proposals/complete/source-fps-one-for-one-complete.md
new file mode 100644
index 00000000..8a02015a
--- /dev/null
+++ b/docs/proposals/complete/source-fps-one-for-one-complete.md
@@ -0,0 +1,140 @@
+# One-for-one templates follow the source's frame rate (#1090)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). Plan v1 on #1090 was approved by Don on 2026-10-31 with every
+default (Q1-Q4). It was built as three stages, in the order B, A, C:
+#1106 (stage B), #1107 (stage A) and #1108 (stage C). All three were
+verified on the first attempt on lem over MCP: B on develop @ fc0a40d9,
+A @ c69a6cbf, C @ f47d2adb.
+
+## The report
+
+Split out of #1064 by Don's Q7 ruling there: **a template whose output has
+one frame per source frame keeps the source's rate unless the caller asks
+for another.** Seven LTX-2.5 templates broke it. Each took a clip's frames
+one for one and wrote them at a fixed 24 fps, so a 30 fps phone clip came
+back 0.8x slow and, in the `pair_audio` routes, its audio was cut to the
+wrong length. No field report named it, because most of Don's footage is
+generated at 24. The evidence was the class: fps defaults had been fixed
+one at a time six times before (#84, #104, #363, #561, #673, #1056).
+
+## Verdict
+
+**Build**, in three stages. Retiming (resampling fps in `fit_to_model`) is
+a non-goal: it changes frame counts and breaks the one-for-one rule.
+
+## What the plan found against the issue
+
+1. **`face-repair` already had a carrier.** `paste_face_track` returns the
+   clip's own fps, audio and shots. Only the declared `fps` on `pasted`
+   made it 24.
+2. **`restore-long` already had a carrier.** `window_video` and
+   `join_windows` both fall back to the file's rate. Only the declared
+   `fps` on the join made it 24. The issue was wrong that this route
+   "needs another carrier". `join_windows`' `fps` refused `"source"`.
+3. **Every template fed `variable:frame_rate` into the LTX pipeline**, so a
+   `"source"` default needed the pipeline's own `frame_rate` made a literal
+   `24.0`.
+4. **`restore-deblur` and `restore-decompression` read nothing of the
+   source's rate**: one pipeline step, the source as a reference only,
+   960x544 out. They needed `restore-colorize`'s fit → model → restore
+   shape (#1080).
+5. **A declared `result.fps` on a `save: false` step does nothing**, and
+   `result.fps` refuses a non-number, so `"source"` must never go there.
+6. **The writer truncates fractional rates** (`int(fps)`), so a 29.97
+   source wrote at 29. Filed and fixed separately as #1109 (Q4).
+
+## The rule, as built
+
+On all seven templates:
+- `frame_rate` defaults to `"source"` and sets the **output** rate. A
+  number overrides the rate, never the frame count. (On the generating
+  templates `frame_rate` still means the model's rate; the descriptions
+  say which.)
+- The pipeline's `frame_rate` is a literal `24.0` and the model step's
+  `result.fps` stays `24.0` (LTX output carries no rate).
+- No `result.fps` downstream of the carrier.
+
+## What was built
+
+### Stage B (#1106): `face-repair`, `restore-long`, two task arguments
+
+Commits `4256fddc`, `200a338b` (merged `fc0a40d9`).
+- `paste_face_track` gains an optional `fps`: omitted or `"source"` keeps
+  the clip's rate; a number above zero (numeric strings parse) sets it.
+- `join_windows`' `fps` also accepts `"source"`; its `POSITIVE` domain is
+  replaced by the same source-or-positive check.
+- One owner for that check: `task_domains.source_fps_problem(fps,
+  command)` (renamed from `restore_fps_problem`), called by
+  `restore_to_source`, `paste_face_track` and `join_windows` at validate
+  and at run time.
+- `face-repair`: `pasted` takes `fps: variable:frame_rate`; `fps` dropped
+  from `crop` and `pasted`. `restore-long`: `join` takes
+  `fps: variable:frame_rate`; `fps` dropped from `join` and `window`.
+- `docs/TASKS.md`, both task parameter descriptions, both template
+  descriptions and the ltx-2.5 skill rows.
+
+Verified (M-F278 to M-F284): on a 30 fps source, `face-repair` writes 124
+frames @30 fps with the source's audio in sync, `frame_rate=24` writes at
+24; `restore-long` joins three windows to 282 frames @30 fps with the
+source's audio; the 24 fps control is unchanged.
+
+### Stage A (#1107): `upscale-clip`, `refine-clip`, `refine-in-place`
+
+Commit `e748fc2f` (merged `c41fb9f0`).
+- `restore_to_source` takes `fps: variable:frame_rate` (#1079's argument).
+- `with_source_audio` declares no `result.fps`; the dead `fps` on the
+  `save: false` restore and on `refine-clip`'s latent-upsampler step were
+  removed (the latter would have resolved to `"source"`).
+- Descriptions: "the model runs at 24 and the output is written at the
+  source's frame rate; 'frame_rate' overrides that rate, never the frame
+  count", replacing "set 'frame_rate' to the source's".
+- Tests include a real-path class: an 8 fps source through each
+  template's own task steps, pipelines stood in for at 24 fps.
+
+Verified (M-F273 to M-F277): `refine-in-place` and `upscale-clip` on a 30
+fps source give 121 frames @30 fps with the audio paired to 4.033 s and no
+fps warnings; `frame_rate=24` gives 121 frames @24. `refine-clip` was
+checked statically only (same restore-and-pair path).
+
+### Stage C (#1108): `restore-deblur`, `restore-decompression`
+
+Commit `1d1a4eeb` (merged `f47d2adb`). Labelled `breaking-change`.
+- Both take `restore-colorize`'s shape: `fit` (`fit_to_model`,
+  letterbox, `downscale: 1`) → `restored` (the IC pass on the fitted clip
+  at 24) → `final` (`restore_to_source`, `fps: variable:frame_rate`).
+- **The output now comes back at the source's size**, not 960x544.
+- **The output is silent.** The plan said the model's generated audio
+  stays, but `restore_to_source` drops audio and shots, as in colorize
+  (#1064 Q11 (i)). The build followed that precedent: both declare
+  `"traits": ["needs-input-media"]` (so the catalog no longer derives
+  `has-audio`) and the descriptions say "The output has no soundtrack".
+- Skill row, `workflows/templates/ltx2/README.md`, test pins.
+- One lem run (job `66d0ac46f4e3`, deblur, cold): 111 s wall. The curated
+  `cost` stays at 3.4 min.
+
+Verified (M-F285 to M-F288): on a 384x544 30 fps portrait, 97 frames,
+both templates come back 384x544, 97 frames @30 fps with no letterbox band
+or edge bleed; `frame_rate=24` gives 24 fps with the frame count kept.
+
+## Deferred, and why
+
+- **Retiming in `fit_to_model`**: a non-goal; it returns with Day-To-Night
+  or a field report asking for a rate change.
+- **`extend-clip`, `dissolve-between-shots`, `assemble-and-score`** (Q1):
+  out of scope. `extend-clip` is a generator; the other two join
+  generated 24 fps shots and take an explicit `fps`.
+- **The source's soundtrack through `restore-deblur` /
+  `restore-decompression`** (Q3): no `pair_audio`. The outputs are silent
+  (above); a `pair_audio` step is the change if a caller wants the sound.
+
+## Cost and bounces
+
+No stage comment names a `usage:` figure, so cost is left out. The plan
+estimated about $9.5 in all ($3 A, $3 B, $3.5 C).
+
+- **Stage B (#1106): 0 bounces, 1 build.**
+- **Stage A (#1107): 0 bounces, 1 build.**
+- **Stage C (#1108): 0 bounces, 1 build.** The portrait fixture
+  `fps-1090/priya-30fps-384x544-97f.mp4` was missing at verify and was
+  rebuilt from the suite's recipe.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index d4c18880..208a82e9 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -37,6 +37,15 @@ remaining deferred fix is recorded in
 
 ## Shipped since the ranking
 
+- **One-for-one templates follow the source's frame rate** (#1090,
+  stages #1106-#1108), shipped 2026-11-01. `face-repair`, `restore-long`,
+  `upscale-clip`, `refine-clip`, `refine-in-place`, `restore-deblur` and
+  `restore-decompression` default `frame_rate` to `"source"` (the output
+  rate; the model still runs at 24). `paste_face_track` gains `fps` and
+  `join_windows`' `fps` accepts `"source"`. Deblur and decompression now
+  return the source's size, silent. Record, including what was deferred
+  (retiming, `extend-clip`, the restores' soundtrack):
+  `complete/source-fps-one-for-one-complete.md`.
 - **The remaining LTX-2.5 IC-LoRAs: `ltx2/alpha-matte` and
   `ltx2/restore-colorize`** (#1064, stages #1079-#1080), shipped
   2026-11-01. A grey soft-matte MP4 at the source's size and frame rate

From 5880731e628bd996c120a6e843a46ac2cdb5def5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 22:03:50 -0500
Subject: [PATCH 071/125] feat(plugin): #1103 - record the odd-then-bridge
 probe as "probed, not a rule" in minimax-h3 cuts.md

Stage B of #1094, "doesn't win" branch (Don's ruling): the claim, the
per-arm numbers, the deviations and the job ids from stage A (#1102),
plus a one-line cross-link from script-to-video's joins.md lead-in.
No SKILL.md bytes change; script-to-video/SKILL.md untouched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../dw/skills/minimax-h3/references/cuts.md   | 49 +++++++++++++++++++
 .../script-to-video/references/joins.md       |  3 ++
 2 files changed, 52 insertions(+)

diff --git a/plugins/dw/skills/minimax-h3/references/cuts.md b/plugins/dw/skills/minimax-h3/references/cuts.md
index 590d2544..108628a5 100644
--- a/plugins/dw/skills/minimax-h3/references/cuts.md
+++ b/plugins/dw/skills/minimax-h3/references/cuts.md
@@ -71,3 +71,52 @@ the same rule.
 `asset:...` to cut to an existing one and skip writing.
 
 Mouths and the pasted-over song (#795): `pair_audio` lays the original song over shots whose mouths follow H3's own audio. With the slice as a reference alone, H3 was seen re-singing it shifted by whole beats (up to 1.8 s), so the mouth lands off the song. The `hold_audio` variable holds the slice as well, keeping the reference: it defaults to `previous_result:slice` on `music-video` (null for the reference alone) and to null on the `match_audio` chains, where an audio file sets it. Measured on lem (#808, 4 shots, two seeds), the reference alone put shots up to 1.37 s late (0.18 s early on another), while reference plus hold measured 0.00 s on all eight, correlation 0.95 to 1.00. That is the audio against its slice, not the mouth: #619 measured hold with image-only references at 3 of 6 sung onsets, against 6 of 6 reference-only, and mouth onsets with hold plus reference were not counted. Check a cut with `measure_sync`.
+
+## Probed, not a rule: odd shots, then bridges
+
+Tested on our server (lem, draft tier: 1344x768, 124 frames, 5 steps, int4,
+sparse, seed 12345; October 2026; one take, so one sample; #1094, record on
+the issue). The claim (from an outside repo): for a long continuous take,
+render the odd shots independently from the same references, then fill each
+even shot with a `templates/minimax/first-and-last-frame` bridge pinned to
+its neighbours (`get_last_frame` of the shot before as `image`,
+`get_first_frame` of the shot after as `last_image`), and the take holds its
+look better than a chain. A take needs an odd shot count for this: the last
+shot of an even count has one neighbour.
+
+Five shots, one astronaut at a marker post, no dialogue. Arm A was a
+`last_segment`-style Ref2VA chain; arm B rendered shots 3 and 5 as separate
+Ref2VA jobs and shots 2 and 4 as 124-frame bridges. Both shared shot 1 and
+one reference image. Both were joined with `concat_videos` `trim_frames: 1`
+and measured with `analyze_seams` given `shots=` (concat's `hard_cut` record
+would skip `seam_frame_jump`).
+
+- **Refuted on this take, so not a rule: it doesn't win, on identity.** Arm
+  B's independent shot 3 rendered two astronauts for its whole length, and
+  both bridges interpolated faithfully into and out of the duplicate. Arm A
+  kept one subject (its prop doubled and its framing wandered).
+- Everything else went to arm B:
+  - take drift, shot 1 head vs shot 5 tail (4 frames each): lightness
+    -14.09 (A) vs +0.16 (B), saturation +5.09 vs +1.05, contrast -9.86 vs
+    -7.51;
+  - worst seam: `frame_delta` 19.57 / `jump_ratio` 7.29 (A) vs 1.85 / 0.81
+    (B); every arm B seam was under the clip's own motion (`jump_ratio`
+    below 1), every arm A seam a visible jump (3.08-7.29);
+  - no bridge tail snap: the largest per-frame step over a bridge's last 12
+    frames was 0.92 and 1.03, against a body typical of 2.33 and 6.72. So
+    WanGP's "discard ~5 tail frames" was not reproduced for a bridge (#985).
+- Audio: each bridge makes its own, a different soundscape from the Ref2VA
+  shots around it: level steps of 3.60-6.72 dB at all four arm B seams
+  (0.35-2.39 dB in the chain), and bridge 2 near-silent at -46.1 dBFS.
+  Never for dialogue; an ambient take would need `match_levels` or one bed
+  under the whole take.
+- So an independent odd shot is a fresh render with no carry: one wrong
+  subject count breaks two bridges with it. A cut still erases drift
+  (above); a take that must stay continuous stays a chain.
+- Deviations: the reference was a shared HF URL, not an `asset:` upload;
+  arm A was hand-built as 48-frame carries of the segment before (what
+  `last_segment` injects), not one `chain` job; drift used 4 frames a side;
+  shots 3 and 5 ran one after the other on one card (host RAM).
+- Jobs: shot 1 `71a3c4ee9eba`; arm A `e1d37983f04a`; arm B shot 3
+  `d4be72601012`, shot 5 `1ae6a04cb793`, bridge 2 `932c2add5238`, bridge 4
+  `305f70b310b9`; joins and measurements `8a8adfbf3c30`.
diff --git a/plugins/dw/skills/script-to-video/references/joins.md b/plugins/dw/skills/script-to-video/references/joins.md
index d4003baa..bea33f8b 100644
--- a/plugins/dw/skills/script-to-video/references/joins.md
+++ b/plugins/dw/skills/script-to-video/references/joins.md
@@ -78,6 +78,9 @@ B's last frame is C's first frame. **Render the target first**: C before B.
 
 Keep a lead-in short (the 124-frame floor or near it): the interpolation
 between two pinned frames drifts mid-shot over a long B.
+Bridging every other shot of a continuous take this way was probed and
+is not a rule: `dw:minimax-h3`'s `references/cuts.md`, *Probed, not a rule:
+odd shots, then bridges*.
 
 ## Render order and re-rolls
 

From c439731c516b9ef6d15a90fb432598fcb0324f4a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 22:18:43 -0500
Subject: [PATCH 072/125] feat(validation): #1111 - refuse a literal
 cross-entry reference inside one for_each group

A member G@k holding a literal previous-result reference to G@j (j != k),
either spelling, with or without a .property, is a validation error
(cross_entry_reference_errors, after previous_result_references).
#813's video-into-image check and the "no earlier step" check skip it, so
the author sees one error. The UI's flow.ts gives the same verdict, pinned
by a shared reference_cases.json case. Guide and architecture map updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                |   2 +-
 docs/WORKFLOW_GUIDE.md              |  33 +++---
 dw/previous_results.py              |  51 +++++++++
 dw/references.py                    |  23 ++++
 dw/validation.py                    |  10 +-
 dw/video_extensions.py              |   5 +
 tests/fixtures/reference_cases.json |  77 +++++++++++++
 tests/test_previous_results.py      | 163 ++++++++++++++++++++++++++++
 tests/test_validation.py            |   1 +
 tests/test_video_extensions.py      |  47 ++++++--
 ui/src/lib/flow.ts                  |  21 +++-
 11 files changed, 406 insertions(+), 27 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index f2520221..74123bdd 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -41,7 +41,7 @@ one to open.
 | `for_each` expansion | `dw/for_each.py`: `expand_for_each`, `group_of` | Each entry becomes an ordinary step named `<step>@<entry>`, after substitution and before the reference check. | `tests/test_for_each.py::TestNaming::test_member_name_joins_with_at` |
 | Optional entry field | `dw/for_each.py`: `_optional_item`, `_item_fields` | `{"item": "field", "default": X}` reads an entry field with a fallback; without `default` it is the plain required read, and `list_fields` / `entry_field_warnings` count the field as one entries take. The editor's string scan needs no twin code, only the shared case file. | `tests/test_for_each.py::TestOptionalItem::test_a_present_field_wins_and_an_absent_one_takes_the_default`, `tests/test_ui_twins.py::test_the_engine_decides_each_shared_reference_case` |
 | Previous results | `dw/previous_results.py`: `get_iterations`, `previous_result_reference_errors` | Several `previous_result:` references in one step multiply into a cartesian product. | `tests/test_previous_results.py::TestGetIterations::test_multiple_references_create_cartesian_product` |
-| Previous-result check | `dw/previous_results.py`: `previous_result_reference_errors` | A literal reference to a step that is not earlier in the workflow is a validation error. | `tests/test_previous_results.py::TestStaticReferenceChecking::test_a_step_cannot_reference_itself_or_a_later_one` |
+| Previous-result check | `dw/previous_results.py`: `previous_result_reference_errors`, `cross_entry_reference_errors` | A literal reference to a step that is not earlier in the workflow is a validation error. A for_each member reading another entry of its own list (`shot@a` inside `shot@b`, either spelling, any `.property`) is a validation error too, `cross_entry_reference_errors` (#1101); same-key pairing, other groups and `gather:` stay legal. | `tests/test_previous_results.py::TestStaticReferenceChecking::test_a_step_cannot_reference_itself_or_a_later_one`, `tests/test_previous_results.py::TestCrossEntryReferences::test_the_prefix_spelled_in_an_entry_is_refused` |
 | Type conversion | `dw/arguments.py`: `realize_args`, `dw/type_helpers.py`: `get_type` | A key ending `_type` or `_dtype` loads a Python object at realize time. The other spellings, and `{}` escaping, are in `docs/WORKFLOW_GUIDE.md`. | `tests/test_type_helpers.py::TestGetType::test_get_type_from_diffusers`, `tests/test_arguments.py::TestRealizeArgs::test_realize_escaped_type_reference` |
 
 ## References and libraries
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index 6176e00c..b331b79b 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -621,7 +621,9 @@ reference to another `for_each` step `slice` over the same `shots` list
 resolves to `slice@closeup`. That is how a shot reads the audio
 slice cut for it when slicing and generating are two steps. It is the one
 pairing the engine has; `for_each` runs over exactly one list, and there is
-no zip and no loop index.
+no zip and no loop index. Same-key pairing is the only way one member reads another
+member of the same list's expansion: a member never reads a sibling entry of
+its own list (below).
 
 That auto-pairing is at the *step* level only, where `from_previous_result`
 (or `previous_result:`) sits directly in the `for_each` step's own
@@ -633,22 +635,19 @@ came from. Spell the member out: `{"reference_type": "…",
 fails the run with a precise error naming the members that do exist, but the
 guide says it here first.
 
-A member may reference an *earlier* member of its own list directly
-(`"image": "previous_result:shot@accuse"` inside `shot@deflect`), but it
-cannot interpose a derivation on that reference — "shot 2 starts where shot
-1 ended," a still pulled from shot 1's last frame with `get_last_frame`.
-There is no step between two members of the same `for_each` list: a step
-meant to derive that still (say, named `last`) would itself have to sit
-after `shot` in the file to read `shot@accuse`'s result, which makes it a
-step *after* the whole list, and referencing it from inside the list is a
-`previous_result:` naming no earlier step — refused at validate. Split the
-list at the dependency instead: run the members up to and including the one
-being derived from as their own `for_each` (or, for a single entry, an
-ordinary step), add an ordinary `get_last_frame` step after it reading
-`previous_result:shot@accuse`, and run the remaining members as a second
-`for_each` whose dependent entry takes that derived still — as a variable
-value or, over the API/MCP, folded into the entry itself — rather than a
-bare `previous_result:` reference to the video.
+Members of one list can't read each other. A literal reference to another
+entry of the member's own list (`"image": "previous_result:shot@accuse"`
+inside `shot@deflect`, spelled in the template or carried in an entry, with
+either spelling and with or without a `.property`) is refused at validate:
+it would make the list's order part of its meaning, and no derivation — "shot
+2 starts where shot 1 ended," a still pulled from shot 1's last frame with
+`get_last_frame` — can sit between two members of one list. When one entry
+depends on another, use separate runs: generate the one being derived from
+in its own run (with the derivation, such as a `get_last_frame` step, after
+it), then pass that run's file to the next run as an `output:` reference in
+the dependent entry. Another `for_each` step over the same list reading a
+different key (`trim@deflect` reading `shot@accuse`) stays legal: every member
+of `shot` has finished before `trim` starts.
 
 Limits: a list has at most 32 entries, and an empty list is a validation
 error — the step would run nothing. Validation realizes a `constant:`
diff --git a/dw/previous_results.py b/dw/previous_results.py
index 6f4cbc79..256dc6a6 100644
--- a/dw/previous_results.py
+++ b/dw/previous_results.py
@@ -393,6 +393,10 @@ def previous_result_reference_errors(workflow_definition, source_indices=None):
         for path, reference in sorted(found.items(), key=lambda item: str(item[0])):
             if any(reference_resolves_to(reference, name) for name in seen):
                 continue
+            # A sibling entry later in the list is cross_entry_reference_errors'
+            # to report, with the fix that applies (#1101)
+            if references.cross_entry_key(reference, name) is not None:
+                continue
             location = render_path(("steps", source) + path)
             errors.append(
                 {
@@ -408,6 +412,53 @@ def previous_result_reference_errors(workflow_definition, source_indices=None):
     return errors
 
 
+def cross_entry_reference_errors(workflow_definition, source_indices=None):
+    """Every for_each member that reads another entry of its own list (#1101).
+
+    `expand_for_each` rewrites a bare reference to the member's own group
+    (`shot` inside `shot@b`) to the same key, but a literal
+    `previous_result:shot@a` inside `shot@b` - spliced in through `item:` or
+    written out - passed validation and made the list's order part of its
+    meaning (#509, #813). Entries of one list can't read each other: the only
+    member-to-member read is same-key pairing (`refine@a` reading `shot@a`).
+    Another group over the same list reading another key (`trim@b` reading
+    `shot@a`) is a read from outside the group - every `shot@*` has run
+    before any `trim@*` - and stays legal, as do steps after the group and
+    `gather:`.
+
+    Both spellings, the 'previous_result:' prefix and 'from_previous_result',
+    with or without a '.property'. Membership is read off the member names
+    (`references.cross_entry_key`), so nothing else from the expansion is
+    needed beyond the source indices the paths use.
+    """
+    errors = []
+    for _, step, _, source, _ in references.iter_steps(
+        workflow_definition.get("steps"), source_indices
+    ):
+        name = step.get("name")
+        if not isinstance(name, str):
+            continue
+        found = {}
+        _collect_reference_paths(step, (), found)
+        for path, reference in sorted(found.items(), key=lambda item: str(item[0])):
+            key = references.cross_entry_key(reference, name)
+            if key is None:
+                continue
+            errors.append(
+                {
+                    "path": render_path(("steps", source) + path),
+                    "message": (
+                        f"previous_result '{reference}' in member '{name}' reads "
+                        f"another entry ('{key}') of the same for_each list. "
+                        f"Entries of one list can't read each other. Generate "
+                        f"'{key}' in its own run and pass its file to this one "
+                        f"as an output: reference (guide: for_each)."
+                    ),
+                }
+            )
+    return errors
+
+
 def _collect_reference_paths(value, path, found):
     """Every literal previous-result reference under `value`, by JSON path.
 
diff --git a/dw/references.py b/dw/references.py
index 7e647c94..fc421c61 100644
--- a/dw/references.py
+++ b/dw/references.py
@@ -131,6 +131,29 @@ def member_keys(name):
     return keys
 
 
+def cross_entry_key(reference, step_name):
+    """The key of the sibling entry a member's previous-result reference
+    reads, or None (#1101).
+
+    `reference` is a literal previous-result name (no prefix, any
+    `.property` kept); `step_name` is the step holding it. A sibling is a
+    member of the same group under a different key: `shot@a` or
+    `shot@a.frames` read from `shot@b`. Entries of one list can't read each
+    other, so validation refuses that. The same key, another group (`trim@b`
+    reading `shot@a`) or a step outside every group is None."""
+    if not isinstance(step_name, str) or not isinstance(reference, str):
+        return None
+    if MEMBER_SEPARATOR not in step_name or MEMBER_SEPARATOR not in reference:
+        return None
+    group = step_name.split(MEMBER_SEPARATOR)[0]
+    if reference.split(MEMBER_SEPARATOR)[0] != group:
+        return None
+    own, read = member_keys(step_name), member_keys(reference)
+    if not own or not read or own[0] == read[0]:
+        return None
+    return read[0]
+
+
 def member_suffix(name):
     """The `" in member '<name>'"` a message ends with when its step is a
     for_each member, else "".
diff --git a/dw/validation.py b/dw/validation.py
index 9f3846d5..df826b41 100644
--- a/dw/validation.py
+++ b/dw/validation.py
@@ -47,7 +47,10 @@
 from .library import SubWorkflowNotFound
 from .locations import location_errors
 from .media import probe_metadata
-from .previous_results import previous_result_reference_errors
+from .previous_results import (
+    cross_entry_reference_errors,
+    previous_result_reference_errors,
+)
 from .reference_limits import reference_limit_errors
 from .reference_names import reference_name_errors
 from .scalar_result_validation import scalar_result_errors
@@ -319,6 +322,11 @@ def _task_errors(context):
         "previous_result_references",
         lambda c: previous_result_reference_errors(c.expanded, c.source_indices),
     ),
+    # A for_each member reading another entry of its own list (#1101)
+    Check(
+        "cross_entry_references",
+        lambda c: cross_entry_reference_errors(c.expanded, c.source_indices),
+    ),
     Check("subfolders", lambda c: subfolder_errors(c.expanded, c.source_indices)),
     Check("fps", lambda c: fps_errors(c.expanded, c.source_indices)),
     # A `cache: "variable:cache"` the raw schema let through, holding an
diff --git a/dw/video_extensions.py b/dw/video_extensions.py
index 46fc8073..1489a5a1 100644
--- a/dw/video_extensions.py
+++ b/dw/video_extensions.py
@@ -150,6 +150,11 @@ def video_into_image_errors(workflow_definition, source_indices=None):
                 name = references.ref_name(references.PREVIOUS_RESULT, value)
                 if name not in video_steps:
                     continue
+                # Another entry of the member's own list: refused outright by
+                # cross_entry_reference_errors (#1101), whose fix is the one
+                # that applies - no still can be taken inside one list
+                if references.cross_entry_key(name, step.get("name")) is not None:
+                    continue
                 errors.append(
                     {
                         "path": render_path(
diff --git a/tests/fixtures/reference_cases.json b/tests/fixtures/reference_cases.json
index 21678297..e094e698 100644
--- a/tests/fixtures/reference_cases.json
+++ b/tests/fixtures/reference_cases.json
@@ -547,5 +547,82 @@
     "flagged": [
       "variable:nope"
     ]
+  },
+  {
+    "name": "cross_entry_same_group",
+    "workflow": {
+      "id": "cross_entry_same_group",
+      "steps": [
+        {
+          "name": "g",
+          "task": {
+            "command": "compose_text",
+            "arguments": {
+              "parts": [
+                "item:name",
+                "previous_result:g@open"
+              ]
+            }
+          },
+          "for_each": "variable:shots"
+        }
+      ],
+      "variables": {
+        "shots": [
+          {
+            "name": "open"
+          },
+          {
+            "name": "close"
+          }
+        ]
+      }
+    },
+    "flagged": [
+      "reads another entry ('open') of the same for_each list"
+    ]
+  },
+  {
+    "name": "other_group_other_key",
+    "workflow": {
+      "id": "other_group_other_key",
+      "steps": [
+        {
+          "name": "g",
+          "task": {
+            "command": "compose_text",
+            "arguments": {
+              "parts": [
+                "item:name"
+              ]
+            }
+          },
+          "for_each": "variable:shots"
+        },
+        {
+          "name": "h",
+          "task": {
+            "command": "compose_text",
+            "arguments": {
+              "parts": [
+                "previous_result:g@open"
+              ]
+            }
+          },
+          "for_each": "variable:shots"
+        }
+      ],
+      "variables": {
+        "shots": [
+          {
+            "name": "open"
+          },
+          {
+            "name": "close"
+          }
+        ]
+      }
+    },
+    "flagged": []
   }
 ]
diff --git a/tests/test_previous_results.py b/tests/test_previous_results.py
index 9031df98..87e86872 100644
--- a/tests/test_previous_results.py
+++ b/tests/test_previous_results.py
@@ -3,6 +3,8 @@
 Tests cartesian product generation and result reference handling
 """
 
+import tempfile
+
 import pytest
 from dw.previous_results import (
     StepResults,
@@ -11,6 +13,7 @@
     find_previous_result_refs,
     previous_result_reference_errors,
 )
+from dw.workflow import workflow_from_definition
 from dw.workflow_run import release_unreferenced_results
 from dw.result import Result
 from PIL import Image
@@ -634,3 +637,163 @@ def test_a_variable_spelled_reference_is_left_alone(self):
 
     def test_a_definition_with_no_steps_is_not_an_error(self):
         assert previous_result_reference_errors({"id": "test"}) == []
+
+
+class TestCrossEntryReferences:
+    """#1101: entries of one for_each list can't read each other. A literal
+    `shot@a` inside `shot@b` is refused at validation; same-key pairing,
+    reads from outside the group and `gather:` stay legal. Every case goes
+    through the real validate path."""
+
+    CROSS = "of the same for_each list"
+
+    def errors(self, steps, shots=None):
+        definition = {
+            "id": "cross_entry",
+            "variables": {
+                "shots": shots
+                if shots is not None
+                else [{"name": "a", "text": "one"}, {"name": "b", "text": "two"}]
+            },
+            "steps": steps,
+        }
+        return workflow_from_definition(
+            definition, tempfile.mkdtemp()
+        ).validation_errors()
+
+    def group(self, name, parts, over="variable:shots"):
+        return {
+            "name": name,
+            "for_each": over,
+            "task": {"command": "compose_text", "arguments": {"parts": parts}},
+        }
+
+    def cross(self, errors):
+        return [e for e in errors if self.CROSS in e["message"]]
+
+    def test_the_prefix_spelled_in_an_entry_is_refused(self):
+        shots = [
+            {"name": "a", "text": "one"},
+            {"name": "b", "text": "previous_result:shot@a"},
+        ]
+        errors = self.errors([self.group("shot", ["item:text"])], shots)
+        cross = self.cross(errors)
+        assert len(cross) == 1, errors
+        assert cross[0]["path"] == "steps[0].task.arguments.parts[0]"
+        message = cross[0]["message"]
+        assert "'shot@a'" in message and "member 'shot@b'" in message
+        assert "reads another entry ('a')" in message
+        assert "output:" in message and "own run" in message
+        # One error, not also "names no earlier step"
+        assert len(errors) == 1, errors
+
+    def test_from_previous_result_in_a_spliced_entry_is_refused(self):
+        shots = [
+            {"name": "a", "ref": "x"},
+            {"name": "b", "ref": {"from_previous_result": "shot@a"}},
+        ]
+        errors = self.errors([self.group("shot", ["item:ref"])], shots)
+        cross = self.cross(errors)
+        assert len(cross) == 1, errors
+        assert "member 'shot@b'" in cross[0]["message"]
+        assert cross[0]["path"].endswith("from_previous_result")
+
+    def test_a_property_suffix_is_refused(self):
+        shots = [
+            {"name": "a", "text": "one"},
+            {"name": "b", "text": "previous_result:shot@a.frames"},
+        ]
+        cross = self.cross(self.errors([self.group("shot", ["item:text"])], shots))
+        assert len(cross) == 1
+        assert "reads another entry ('a')" in cross[0]["message"]
+
+    def test_index_keys_are_refused(self):
+        shots = [{"text": "one"}, {"text": "previous_result:shot@0"}]
+        cross = self.cross(self.errors([self.group("shot", ["item:text"])], shots))
+        assert len(cross) == 1
+        assert "member 'shot@1'" in cross[0]["message"]
+        assert "reads another entry ('0')" in cross[0]["message"]
+
+    def test_a_forward_sibling_gets_only_the_cross_entry_error(self):
+        shots = [
+            {"name": "a", "text": "previous_result:shot@b"},
+            {"name": "b", "text": "two"},
+        ]
+        errors = self.errors([self.group("shot", ["item:text"])], shots)
+        assert len(errors) == 1, errors
+        assert "reads another entry ('b')" in errors[0]["message"]
+
+    def test_same_key_bare_and_literal_is_legal(self):
+        shots = [
+            {"name": "a", "text": "one", "own": "previous_result:shot@a"},
+            {"name": "b", "text": "two", "own": "previous_result:shot@b"},
+        ]
+        assert (
+            self.errors(
+                [
+                    self.group("shot", ["item:text"]),
+                    self.group("trim", ["previous_result:shot"]),
+                    self.group("tail", ["item:own"]),
+                ],
+                shots,
+            )
+            == []
+        )
+
+    def test_a_later_ordinary_step_and_gather_are_legal(self):
+        assert (
+            self.errors(
+                [
+                    self.group("shot", ["item:text"]),
+                    {
+                        "name": "after",
+                        "task": {
+                            "command": "compose_text",
+                            "arguments": {"parts": ["previous_result:shot@a"]},
+                        },
+                    },
+                    {
+                        "name": "all",
+                        "task": {
+                            "command": "compose_text",
+                            "arguments": {"parts": "gather:shot"},
+                        },
+                    },
+                ]
+            )
+            == []
+        )
+
+    def test_another_group_over_the_same_list_reading_another_key_is_legal(self):
+        shots = [
+            {"name": "a", "text": "one", "other": "previous_result:shot@b"},
+            {"name": "b", "text": "two", "other": "previous_result:shot@a"},
+        ]
+        assert (
+            self.errors(
+                [
+                    self.group("shot", ["item:text"]),
+                    self.group("trim", ["item:other"]),
+                ],
+                shots,
+            )
+            == []
+        )
+
+    def test_a_group_over_a_different_list_is_legal(self):
+        definition_steps = [
+            self.group("shot", ["item:text"]),
+            self.group("trim", ["previous_result:shot@a"], over="variable:takes"),
+        ]
+        definition = {
+            "id": "cross_entry",
+            "variables": {
+                "shots": [{"name": "a", "text": "one"}, {"name": "b", "text": "2"}],
+                "takes": [{"name": "x"}, {"name": "y"}],
+            },
+            "steps": definition_steps,
+        }
+        assert (
+            workflow_from_definition(definition, tempfile.mkdtemp()).validation_errors()
+            == []
+        )
diff --git a/tests/test_validation.py b/tests/test_validation.py
index 0353cdfa..0fef4841 100644
--- a/tests/test_validation.py
+++ b/tests/test_validation.py
@@ -176,6 +176,7 @@ def test_validation_does_not_import_the_workflow_module():
 
 ERROR_ORDER = [
     "previous_result_references",
+    "cross_entry_references",
     "subfolders",
     "fps",
     "cache",
diff --git a/tests/test_video_extensions.py b/tests/test_video_extensions.py
index 228f1b54..3b6b4ef0 100644
--- a/tests/test_video_extensions.py
+++ b/tests/test_video_extensions.py
@@ -128,6 +128,8 @@ def _definition(self, shots):
         }
 
     def test_a_member_fed_an_earlier_video_is_refused_before_the_run(self):
+        # Another group's member (`refine@b` reading `shot@a`) is a read from
+        # outside `shot`, legal under #1101, so #813's advice still applies
         from dw.video_extensions import video_into_image_errors
 
         expanded = {
@@ -138,7 +140,7 @@ def test_a_member_fed_an_earlier_video_is_refused_before_the_run(self):
                     "result": {"content_type": "video/mp4"},
                 },
                 {
-                    "name": "shot@b",
+                    "name": "refine@b",
                     "workflow": {
                         "path": "t",
                         "arguments": {"image": "previous_result:shot@a"},
@@ -147,13 +149,37 @@ def test_a_member_fed_an_earlier_video_is_refused_before_the_run(self):
                 },
             ]
         }
-        errors = video_into_image_errors(expanded, [0, 0])
-        assert [e["path"] for e in errors] == ["steps[0].workflow.arguments.image"]
+        errors = video_into_image_errors(expanded, [0, 1])
+        assert [e["path"] for e in errors] == ["steps[1].workflow.arguments.image"]
         assert (
             "shot@a" in errors[0]["message"]
             and "get_last_frame" in errors[0]["message"]
         )
-        assert "in member 'shot@b'" in errors[0]["message"]
+        assert "in member 'refine@b'" in errors[0]["message"]
+
+    def test_a_sibling_entry_is_left_to_the_cross_entry_check(self):
+        # #1101: `shot@b` reading `shot@a` is refused as a cross-entry read;
+        # #813's get_last_frame advice can't be followed inside one list
+        from dw.video_extensions import video_into_image_errors
+
+        expanded = {
+            "steps": [
+                {
+                    "name": "shot@a",
+                    "workflow": {"path": "t", "arguments": {"image": "asset:x.png"}},
+                    "result": {"content_type": "video/mp4"},
+                },
+                {
+                    "name": "shot@b",
+                    "workflow": {
+                        "path": "t",
+                        "arguments": {"image": "previous_result:shot@a"},
+                    },
+                    "result": {"content_type": "video/mp4"},
+                },
+            ]
+        }
+        assert video_into_image_errors(expanded, [0, 0]) == []
 
     def test_an_image_producer_is_fine(self):
         from dw.video_extensions import video_into_image_errors
@@ -175,12 +201,19 @@ def test_an_image_producer_is_fine(self):
         assert video_into_image_errors(expanded) == []
 
     def test_the_real_validate_path_reports_it(self):
+        # #1101: a member chained to an earlier entry of its own list is
+        # refused as a cross-entry read - one error, not also #813's
         shots = [
             {"name": "a", "image": "asset:a.png"},
             {"name": "b", "image": "previous_result:shot@a"},
         ]
         workflow = workflow_from_definition(self._definition(shots), tempfile.mkdtemp())
         problems = workflow.validation_errors()
-        assert any("declares a video result" in p["message"] for p in problems), (
-            problems
-        )
+        messages = [p["message"] for p in problems]
+        assert any(
+            "reads another entry ('a') of the same for_each list" in m
+            and "in member 'shot@b'" in m
+            for m in messages
+        ), problems
+        assert not any("declares a video result" in m for m in messages), problems
+        assert not any("get_last_frame" in m for m in messages), problems
diff --git a/ui/src/lib/flow.ts b/ui/src/lib/flow.ts
index 60e81f64..67804d8c 100644
--- a/ui/src/lib/flow.ts
+++ b/ui/src/lib/flow.ts
@@ -372,15 +372,30 @@ interface ReferenceScope {
   earlier: EarlierStep[]
   variables: Set<string>
   prompts: Set<string> | null
-  /** The step holding the reference */
+  /** The step holding the reference, when it is a for_each group */
+  consumerGroup: string | undefined
   /** The entries the referencing step's own for_each iterates, if any */
   consumerEntries: unknown
 }
 
 const UNNAMED = 'no earlier step has that name'
 
+/** Why a for_each group's own member reference is refused, or null. A
+ * literal `<group>@<key>` inside the group is read by every other member,
+ * and entries of one list can't read each other (#1101) - the engine's
+ * cross_entry_reference_errors says the same. */
+function crossEntryRefusal(reference: string, scope: ReferenceScope) {
+  if (scope.consumerGroup === undefined) return null
+  const prefix = scope.consumerGroup + MEMBER_SEPARATOR
+  if (!reference.startsWith(prefix)) return null
+  const entry = reference.slice(prefix.length).split('.')[0]
+  return `reads another entry ('${entry}') of the same for_each list. Entries of one list can't read each other. Generate '${entry}' in its own run and pass its file to this one as an output: reference`
+}
+
 /** What is wrong with a reference to an earlier step's result, or null. */
 function resultRefusal(reference: string, scope: ReferenceScope) {
+  const crossEntry = crossEntryRefusal(reference, scope)
+  if (crossEntry !== null) return crossEntry
   const producer = resolveName(scope.earlier, reference)
   return producer === null
     ? UNNAMED
@@ -458,6 +473,10 @@ export function danglingReferenceDetails(
       earlier,
       variables,
       prompts,
+      consumerGroup:
+        FOR_EACH_KEY in step && typeof step.name === 'string'
+          ? step.name
+          : undefined,
       consumerEntries:
         FOR_EACH_KEY in step
           ? forEachEntries(workflow, step[FOR_EACH_KEY])

From 5da0f56e68ce92407e4f7988cc47c200ac256715 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 22:22:51 -0500
Subject: [PATCH 073/125] docs: #1094 close-out - odd-then-bridge design record
 (doesn't win)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/h3-odd-then-bridge-complete.md   | 140 ++++++++++++++++++
 docs/proposals/todo.md                        |   7 +
 2 files changed, 147 insertions(+)
 create mode 100644 docs/proposals/complete/h3-odd-then-bridge-complete.md

diff --git a/docs/proposals/complete/h3-odd-then-bridge-complete.md b/docs/proposals/complete/h3-odd-then-bridge-complete.md
new file mode 100644
index 00000000..436cdb49
--- /dev/null
+++ b/docs/proposals/complete/h3-odd-then-bridge-complete.md
@@ -0,0 +1,140 @@
+# H3 long takes: odd shots, then bridges, A/B against a chain (#1094)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v2 approved by Don on 2026-10-31 as "build smaller": a
+no-code probe on lem, then one skill reference edit either way, no template.
+Two stages, #1102 (probe) and #1103 (skill text), both verified. The probe
+record is the stage A results comment on #1094; this doc is the design
+record around it.
+
+## The idea
+
+From assessing r34vtraining/Longshot_Studio (a ComfyUI studio for long
+MiniMax H3 films; no license, so only the concept was taken). Its tip: to
+stop drift building over a long continuous take, render the odd shots on
+their own, then fill each even shot as an FL2VA bridge pinned to its
+rendered neighbours (first frame = shot i-1's last, last frame = shot i+1's
+first). No shot is more than one hop from a fresh render, and the odd shots
+can run in parallel across cards.
+
+## Decisions
+
+- **Plan v2 verdict: build smaller.** Probe first, then land only what the
+  probe confirms (the repo's practice since #985, #1059, #1031). The issue's
+  order (skill text first) was reversed.
+- **Corrections to the issue** (accepted by Don):
+  - The take needs an odd shot count; a 6-shot take's shot 6 has one
+    neighbour. The probe used 5 shots (odd 1, 3, 5; bridges 2, 4).
+  - A fair A/B needs a shared identity anchor: both arms used the same
+    reference, and shot 1 was one render shared by both arms.
+  - The "at least 5 s" bridge is already `first-and-last-frame`'s floor:
+    124 frames (5.17 s). Validate refuses 107 and below; 108-123 is
+    rounded up to 124 with a warning (tester's note on the spec).
+- **Q1: probe at all?** Yes: it settles #1031's take-drift reopen and
+  #985's end-frame snap claim on its own.
+- **Q2: arm A's baseline.** The `last_segment` Ref2VA chain, the strongest
+  one the skill prefers.
+- **Q3: where the result lands.** `minimax-h3/references/cuts.md`, plus
+  one `script-to-video` sentence on a win; a one-line cross-link with
+  #1093's `joins.md` from whichever landed second.
+- **Win rule** (fixed before the run): arm B wins only if its take drift is
+  smaller on lightness and saturation, it holds identity at least as well,
+  its worst seam is no worse, and no bridge shows a tail snap.
+
+## What the probe found
+
+lem, develop cb49329c, workspace `qa-1094-bridge`, draft tier (1344x768,
+124 frames, 5 steps, int4, sparse, seed 12345). 9 renders, no re-rolls.
+
+| Win-rule condition | Arm A (chain) | Arm B (odd-then-bridge) | Holds for B? |
+|---|---|---|---|
+| Take drift, lightness / saturation | -14.09 / +5.09 | +0.16 / +1.05 | yes |
+| Identity | one subject; prop doubled, framing wanders | subject duplicated in shot 3 and both bridges | **no** |
+| Worst seam (`frame_delta` / `jump_ratio`) | 19.57 / 7.29 | 1.85 / 0.81 | yes |
+| Visible bridge tail snap | n/a | none | yes |
+
+**Verdict: doesn't win, on identity.** Arm B's independent shot 3 rendered
+two astronauts against a one-subject prompt, and both bridges faithfully
+interpolated into and out of it. Every other condition went to arm B by a
+wide margin: every arm B seam was under the clip's own frame-to-frame
+motion, every arm A seam a visible jump.
+
+Also measured:
+- **Bridge audio:** FL2VA bridges carry a different soundscape from the
+  Ref2VA shots around them (3.6-6.7 dB level steps, a `seam_level_step`
+  warning on all four arm B seams; bridge 2 near-silent). A bridged take
+  would need `match_levels` or a bed under the whole take.
+- **#1031 take-drift reopen: not met.** Arm A's end differs, but its seams
+  don't score low; arm B's seams score low, but its end holds.
+- **#985 end-frame snap: not reproduced.** Neither bridge jumps onto its
+  pinned last frame (last-12-frame per-frame delta at most 1.03 against a
+  body typical of 2.3-6.7), so no tail discard is needed at this tier.
+
+Jobs: `71a3c4ee9eba` (shared shot 1), `e1d37983f04a` (arm A chain, shots
+2-5), `d4be72601012` / `1ae6a04cb793` (arm B shots 3, 5), `932c2add5238` /
+`305f70b310b9` (bridges 2, 4), `8a8adfbf3c30` (joins and measurements).
+
+### Deviations from the protocol (accepted by Don, Q4)
+
+- The reference was a shared HF-hosted URL, not an `upload_asset` asset
+  (the upload was refused; later traced to TokenEconomizer deny rules).
+- Arm A's chain was hand-built: a 48-frame carry of each previous segment
+  passed as a video reference, which is what `LastSegmentContinuity`
+  injects. A real `chain` block can't continue from a separately rendered
+  shot 1.
+- Take drift used 4 vs 4 frames, not 8: `look_stats` is not an MCP task and
+  `analyze_seams`' look window is fixed at 4.
+- Ref2VA jobs serialized on cuda:0 because of host RAM (~121 GB each); only
+  the bridges ran on both cards at once.
+
+The tester bounced stage A on these (see below). Plan v3, which would have
+re-run the probe to a protocol the code can express, was written but never
+posted: Don ruled (Q4) to accept the first run, since none of the
+deviations touches the identity failure that decides the verdict, and no
+re-probe with a clean shot 3 (it would make the verdict post hoc).
+
+## What was built
+
+**Stage A, #1102** (no code): the probe above. No commit or deploy; the
+jobs (each with a `set_note`) and the results comment on #1094 are the
+record.
+
+**Stage B, #1103** (plugin only): `5880731e`, develop `7dd927b1`. The
+"doesn't win" branch: a *Probed, not a rule: odd shots, then bridges*
+section at the end of `plugins/dw/skills/minimax-h3/references/cuts.md`, in
+`dialogue.md`'s format, with the claim, the numbers, the job ids, the
+deviations and #1094. `script-to-video/SKILL.md` and `minimax-h3/SKILL.md`
+are unchanged. #1093 had landed, so `script-to-video/references/joins.md`
+cross-links the section. No version bump (the plugin's version is the
+engine's).
+
+## Bounces
+
+- **#1102:** one bounce. The tester failed M-F264 (carry, drift window) and
+  M-F265 (`asset:`) against the recorded deviations; resolved by Don's Q4
+  ruling and amended cases, then verified against the existing jobs with no
+  new renders. Before that, two verify sessions ran with only
+  `get_server_info` exposed (TokenEconomizer's tool pruning had denied the
+  rest), and the driver parked it once; not a fault of the stage.
+- **#1103:** none.
+
+Cost: the stage comments name no `usage:` figures, so none are recorded.
+GPU time was about 9 renders: ~5 min per Ref2VA shot, ~6.5 min per bridge.
+
+## Deferred, and what brings it back
+
+- **A template** (two `for_each` passes, odd then bridges). `for_each` can't
+  express "bridge k reads odd shots k and k+1" (a group reference resolves
+  to the same-key member only, a cross-list one raises `ForEachError`), and
+  one template runs serially on one card. *Comes back if* a re-probe wins
+  **and** sessions hand-build odd-then-bridge more than once.
+- **A re-probe with a clean shot 3.** The seam and drift numbers suggest it
+  might flip the verdict. Don declined it for #1094. *Comes back on* a
+  request for a long continuous take that a cut can't serve, or a field
+  report of drift over a chained take. Run it to plan v3's protocol: arm A
+  as one real `chain` job with shot 1 as its segment 1 (arm B takes it with
+  `trim_video`), references via `upload_asset`, drift as the mean of two
+  4-vs-4 `analyze_seams` steps, and re-rolls (up to 2) for a wrong subject
+  count on either arm, fixed before the run.
+- **A take-drift field in `analyze_seams`.** #1031's reopen condition was
+  not met.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 208a82e9..deae408f 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -446,6 +446,13 @@ remaining deferred fix is recorded in
   stems as the rest, a three-track `mixed`, then `balanced`. Record,
   including the deferred `separate_dialogue` task and its reopen trigger:
   `complete/dialogue-stems-complete.md`.
+- **Odd shots, then bridges, for long H3 takes** (#1094, stages #1102,
+  #1103), probed 2026-10-31. A/B on lem against a `last_segment` chain:
+  bridges held seams and take look far better, but an independent odd shot
+  duplicated the subject and the bridges carried it, so it **doesn't win**.
+  Landed as a "Probed, not a rule" entry in `minimax-h3/references/cuts.md`;
+  no template. Record, including the re-probe protocol and the template's
+  reopen trigger: `complete/h3-odd-then-bridge-complete.md`.
 
 ## Declined
 

From 7502e4780965d24337d9c730b5e159fc369cbd78 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 22:34:12 -0500
Subject: [PATCH 074/125] refactor(validation): #1111 - move cross_entry_key
 into for_each beside group_of

Architecture review: the sibling test re-derived a member's group with its
own split. It now lives in dw/for_each.py and calls group_of and
member_keys; the map's previous-result row names it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md   |  2 +-
 dw/for_each.py         | 21 +++++++++++++++++++++
 dw/previous_results.py |  8 ++++----
 dw/references.py       | 23 -----------------------
 dw/video_extensions.py |  4 ++--
 5 files changed, 28 insertions(+), 30 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 74123bdd..2c89c5ee 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -41,7 +41,7 @@ one to open.
 | `for_each` expansion | `dw/for_each.py`: `expand_for_each`, `group_of` | Each entry becomes an ordinary step named `<step>@<entry>`, after substitution and before the reference check. | `tests/test_for_each.py::TestNaming::test_member_name_joins_with_at` |
 | Optional entry field | `dw/for_each.py`: `_optional_item`, `_item_fields` | `{"item": "field", "default": X}` reads an entry field with a fallback; without `default` it is the plain required read, and `list_fields` / `entry_field_warnings` count the field as one entries take. The editor's string scan needs no twin code, only the shared case file. | `tests/test_for_each.py::TestOptionalItem::test_a_present_field_wins_and_an_absent_one_takes_the_default`, `tests/test_ui_twins.py::test_the_engine_decides_each_shared_reference_case` |
 | Previous results | `dw/previous_results.py`: `get_iterations`, `previous_result_reference_errors` | Several `previous_result:` references in one step multiply into a cartesian product. | `tests/test_previous_results.py::TestGetIterations::test_multiple_references_create_cartesian_product` |
-| Previous-result check | `dw/previous_results.py`: `previous_result_reference_errors`, `cross_entry_reference_errors` | A literal reference to a step that is not earlier in the workflow is a validation error. A for_each member reading another entry of its own list (`shot@a` inside `shot@b`, either spelling, any `.property`) is a validation error too, `cross_entry_reference_errors` (#1101); same-key pairing, other groups and `gather:` stay legal. | `tests/test_previous_results.py::TestStaticReferenceChecking::test_a_step_cannot_reference_itself_or_a_later_one`, `tests/test_previous_results.py::TestCrossEntryReferences::test_the_prefix_spelled_in_an_entry_is_refused` |
+| Previous-result check | `dw/previous_results.py`: `previous_result_reference_errors`, `cross_entry_reference_errors`; the sibling rule is `dw/for_each.py`: `cross_entry_key` (beside `group_of`, which it calls), which the cross-entry check, the earlier-step check and `dw/video_extensions.py`: `video_into_image_errors` all ask | A literal reference to a step that is not earlier in the workflow is a validation error. A for_each member reading another entry of its own list (`shot@a` inside `shot@b`, either spelling, any `.property`) is a validation error too, `cross_entry_reference_errors` (#1101); same-key pairing, other groups and `gather:` stay legal. | `tests/test_previous_results.py::TestStaticReferenceChecking::test_a_step_cannot_reference_itself_or_a_later_one`, `tests/test_previous_results.py::TestCrossEntryReferences::test_the_prefix_spelled_in_an_entry_is_refused` |
 | Type conversion | `dw/arguments.py`: `realize_args`, `dw/type_helpers.py`: `get_type` | A key ending `_type` or `_dtype` loads a Python object at realize time. The other spellings, and `{}` escaping, are in `docs/WORKFLOW_GUIDE.md`. | `tests/test_type_helpers.py::TestGetType::test_get_type_from_diffusers`, `tests/test_arguments.py::TestRealizeArgs::test_realize_escaped_type_reference` |
 
 ## References and libraries
diff --git a/dw/for_each.py b/dw/for_each.py
index 161aad76..cbd942f4 100644
--- a/dw/for_each.py
+++ b/dw/for_each.py
@@ -77,6 +77,27 @@ def group_of(name):
     return name.split(MEMBER_SEPARATOR)[0] if is_member_name(name) else name
 
 
+def cross_entry_key(reference, step_name):
+    """The key of the sibling entry a member's previous-result reference
+    reads, or None (#1101).
+
+    `reference` is a literal previous-result name (no prefix, any
+    `.property` kept); `step_name` is the step holding it. A sibling is a
+    member of the same group (`group_of`) under a different key
+    (`member_keys`): `shot@a` or `shot@a.frames` read from `shot@b`. Entries
+    of one list can't read each other, so validation refuses that. The same
+    key, another group (`trim@b` reading `shot@a`) or a step outside every
+    group is None."""
+    if not isinstance(reference, str) or not is_member_name(step_name):
+        return None
+    if not is_member_name(reference) or group_of(reference) != group_of(step_name):
+        return None
+    own, read = references.member_keys(step_name), references.member_keys(reference)
+    if not own or not read or own[0] == read[0]:
+        return None
+    return read[0]
+
+
 def expand_for_each(definition, source_indices=None):
     """The definition with every 'for_each' step replaced by its members.
 
diff --git a/dw/previous_results.py b/dw/previous_results.py
index 256dc6a6..4dd00952 100644
--- a/dw/previous_results.py
+++ b/dw/previous_results.py
@@ -6,7 +6,7 @@
 from .arguments import (
     build_objects,
 )
-from .for_each import render_path
+from .for_each import cross_entry_key, render_path
 from .step_cache import reference_resolves_to
 
 logger = logging.getLogger("dw")
@@ -395,7 +395,7 @@ def previous_result_reference_errors(workflow_definition, source_indices=None):
                 continue
             # A sibling entry later in the list is cross_entry_reference_errors'
             # to report, with the fix that applies (#1101)
-            if references.cross_entry_key(reference, name) is not None:
+            if cross_entry_key(reference, name) is not None:
                 continue
             location = render_path(("steps", source) + path)
             errors.append(
@@ -428,7 +428,7 @@ def cross_entry_reference_errors(workflow_definition, source_indices=None):
 
     Both spellings, the 'previous_result:' prefix and 'from_previous_result',
     with or without a '.property'. Membership is read off the member names
-    (`references.cross_entry_key`), so nothing else from the expansion is
+    (`for_each.cross_entry_key`), so nothing else from the expansion is
     needed beyond the source indices the paths use.
     """
     errors = []
@@ -441,7 +441,7 @@ def cross_entry_reference_errors(workflow_definition, source_indices=None):
         found = {}
         _collect_reference_paths(step, (), found)
         for path, reference in sorted(found.items(), key=lambda item: str(item[0])):
-            key = references.cross_entry_key(reference, name)
+            key = cross_entry_key(reference, name)
             if key is None:
                 continue
             errors.append(
diff --git a/dw/references.py b/dw/references.py
index fc421c61..7e647c94 100644
--- a/dw/references.py
+++ b/dw/references.py
@@ -131,29 +131,6 @@ def member_keys(name):
     return keys
 
 
-def cross_entry_key(reference, step_name):
-    """The key of the sibling entry a member's previous-result reference
-    reads, or None (#1101).
-
-    `reference` is a literal previous-result name (no prefix, any
-    `.property` kept); `step_name` is the step holding it. A sibling is a
-    member of the same group under a different key: `shot@a` or
-    `shot@a.frames` read from `shot@b`. Entries of one list can't read each
-    other, so validation refuses that. The same key, another group (`trim@b`
-    reading `shot@a`) or a step outside every group is None."""
-    if not isinstance(step_name, str) or not isinstance(reference, str):
-        return None
-    if MEMBER_SEPARATOR not in step_name or MEMBER_SEPARATOR not in reference:
-        return None
-    group = step_name.split(MEMBER_SEPARATOR)[0]
-    if reference.split(MEMBER_SEPARATOR)[0] != group:
-        return None
-    own, read = member_keys(step_name), member_keys(reference)
-    if not own or not read or own[0] == read[0]:
-        return None
-    return read[0]
-
-
 def member_suffix(name):
     """The `" in member '<name>'"` a message ends with when its step is a
     for_each member, else "".
diff --git a/dw/video_extensions.py b/dw/video_extensions.py
index 1489a5a1..b03867b5 100644
--- a/dw/video_extensions.py
+++ b/dw/video_extensions.py
@@ -29,7 +29,7 @@
 
 from . import references
 from .argument_media import is_media_reference
-from .for_each import render_path
+from .for_each import cross_entry_key, render_path
 from .security import ALLOWED_IMAGE_EXTENSIONS, ALLOWED_VIDEO_EXTENSIONS
 
 
@@ -153,7 +153,7 @@ def video_into_image_errors(workflow_definition, source_indices=None):
                 # Another entry of the member's own list: refused outright by
                 # cross_entry_reference_errors (#1101), whose fix is the one
                 # that applies - no still can be taken inside one list
-                if references.cross_entry_key(name, step.get("name")) is not None:
+                if cross_entry_key(name, step.get("name")) is not None:
                     continue
                 errors.append(
                     {

From aa49e2d480c0427587df36d72307f39d703c38a8 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 22:52:41 -0500
Subject: [PATCH 075/125] fix(check-script): #1115 - speech_not_transcribed
 reports each audible block of a stretched word/gap in its own shot

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/script_check.py   | 101 ++++++++++++++++++++++++-------------
 tests/test_script_check.py |  25 +++++++++
 2 files changed, 92 insertions(+), 34 deletions(-)

diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index e05eef3f..e6329404 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -516,7 +516,11 @@ def _line_pass(
         heard_end = max(heard_end or 0.0, end)
         tails = ([(shot, span["end"])] if span else []) + [(None, duration)]
         findings.extend(_clipped_findings(mono, sample_rate, tails, index, own, shot))
-        findings.extend(_untranscribed_findings(mono, sample_rate, index, own, shot))
+        findings.extend(
+            _untranscribed_findings(
+                mono, sample_rate, index, own, shot, spans, parsed_lines
+            )
+        )
         previous_end = end
 
     if heard_end is not None:
@@ -669,7 +673,9 @@ def _silent_take(heard, discarded, spans, shots_source):
     }
 
 
-def _untranscribed_findings(mono, sample_rate, index, own, shot):
+def _untranscribed_findings(
+    mono, sample_rate, index, own, shot, spans=None, parsed_lines=()
+):
     """speech_not_transcribed: audible sound in a gap the line's words leave
     - between two of them - or inside one word stretched over
     UNHEARD_MIN_SECONDS (#923). The gap before a line's first word is
@@ -678,19 +684,30 @@ def _untranscribed_findings(mono, sample_rate, index, own, shot):
     findings = []
     for start, end in intervals:
         if end - start >= UNHEARD_MIN_SECONDS:
-            findings.append(_untranscribed(mono, sample_rate, index, start, end, shot))
+            findings.extend(
+                _audible_findings(
+                    mono, sample_rate, index, start, end, shot, spans, parsed_lines
+                )
+            )
     for word in own:
         # A word is sound itself: only its interior past the margins is a gap
         if (
             word["end"] - word["start"]
             >= UNHEARD_MIN_SECONDS + 2 * UNHEARD_MARGIN_SECONDS
         ):
-            findings.append(
-                _untranscribed(
-                    mono, sample_rate, index, word["start"], word["end"], shot
+            findings.extend(
+                _audible_findings(
+                    mono,
+                    sample_rate,
+                    index,
+                    word["start"],
+                    word["end"],
+                    shot,
+                    spans,
+                    parsed_lines,
                 )
             )
-    return [found for found in findings if found is not None]
+    return findings
 
 
 def _between_lines_findings(
@@ -719,47 +736,63 @@ def _between_lines_findings(
     for lo, hi in stretches:
         if hi - lo < UNHEARD_MIN_SECONDS:
             continue
-        audible = _audible_extent(mono, sample_rate, lo, hi)
-        if audible is None:
-            continue
-        lo, hi = audible
-        where_line, where_shot = index, shot
-        holder = None if spans is None else overlapping_shot(spans, lo, hi)
-        if holder is not None and holder != shot:
-            where_shot = holder
-            where_line = next(
-                (i for i, line in enumerate(parsed_lines) if line["shot"] == holder),
-                None,
+        found.extend(
+            _audible_findings(
+                mono, sample_rate, index, lo, hi, shot, spans, parsed_lines
             )
-        found.append(_untranscribed(mono, sample_rate, where_line, lo, hi, where_shot))
+        )
     return [f for f in found if f is not None]
 
 
-def _audible_extent(mono, sample_rate, start, end):
-    """The span of the stretch [start, end] from its first to its last window
-    above UNHEARD_FLOOR_DBFS, or None when that is shorter than
-    UNHEARD_MIN_SECONDS (#967): sub-floor time at either edge is not "audible
-    sound", and must not size or place the finding. An edge that is itself
-    audible stays the stretch's own edge."""
+def _audible_runs(mono, sample_rate, start, end):
+    """The audible blocks of the stretch [start, end] (#967, #1115): each run
+    of windows above UNHEARD_FLOOR_DBFS, runs a sub-floor gap shorter than
+    UNHEARD_MIN_SECONDS apart joined, and only those lasting UNHEARD_MIN_SECONDS
+    kept. Sub-floor time is never counted or placed in a block, and a quiet
+    stretch of UNHEARD_MIN_SECONDS or more splits the stretch in two. A block
+    edge at the stretch's own (margin-trimmed) edge stays that edge."""
     inner_start, inner_end = (
         start + UNHEARD_MARGIN_SECONDS,
         end - UNHEARD_MARGIN_SECONDS,
     )
-    first = last = None
+    runs = []
     cursor = inner_start
     while cursor < inner_end:
         stop = min(cursor + GUARD_WINDOW_SECONDS, inner_end)
         level = word_level(mono, sample_rate, cursor, stop)
         if level is not None and level > UNHEARD_FLOOR_DBFS:
-            if first is None:
-                first = cursor
-            last = stop
+            if runs and cursor - runs[-1][1] < UNHEARD_MIN_SECONDS:
+                runs[-1][1] = stop
+            else:
+                runs.append([cursor, stop])
         cursor = stop
-    if first is None:
-        return None
-    first = start if first <= inner_start else first
-    last = end if last >= inner_end else last
-    return (first, last) if last - first >= UNHEARD_MIN_SECONDS else None
+    found = []
+    for first, last in runs:
+        first = start if first <= inner_start else first
+        last = end if last >= inner_end else last
+        if last - first >= UNHEARD_MIN_SECONDS:
+            found.append((first, last))
+    return found
+
+
+def _audible_findings(
+    mono, sample_rate, index, start, end, shot, spans=None, parsed_lines=()
+):
+    """speech_not_transcribed for each audible block of [start, end], each
+    attributed to the shot holding most of it - and to the line naming that
+    shot, null when none does - not to the stretch's own line by default."""
+    found = []
+    for lo, hi in _audible_runs(mono, sample_rate, start, end):
+        where_line, where_shot = index, shot
+        holder = None if spans is None else overlapping_shot(spans, lo, hi)
+        if holder is not None and holder != shot:
+            where_shot = holder
+            where_line = next(
+                (i for i, line in enumerate(parsed_lines) if line["shot"] == holder),
+                None,
+            )
+        found.append(_untranscribed(mono, sample_rate, where_line, lo, hi, where_shot))
+    return [f for f in found if f is not None]
 
 
 def _untranscribed(mono, sample_rate, index, start, end, shot):
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index 517f45fd..1e4cf969 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -855,6 +855,31 @@ def test_only_the_audible_part_of_a_gap_sizes_and_places_the_finding(self):
         self.assertLess(found["at"]["end"], 2.5)
         self.assertLess(found["value"], 1.6)
 
+    def test_a_stretched_word_reports_each_audible_block_in_its_own_shot(self):
+        # #1115: one word timed 0.9-10.6 over two blocks of sound with 3 s of
+        # silence between: two findings, none counting the silence, each in
+        # the shot holding it - not one span credited to the word's shot
+        spans = [
+            {"name": "A", "start": 0.0, "end": 5.0},
+            {"name": "B", "start": 5.0, "end": 11.0},
+        ]
+        chunks = [
+            {"start": 0.9, "end": 10.6, "text": " alpha"},
+            {"start": 10.6, "end": 11.0, "text": " bravo"},
+        ]
+        mono = numpy.concatenate([voiced(5.5), silent(3.0), voiced(2.5)])
+        answer = shot_run(
+            [{"text": "alpha bravo", "shot": "B"}], chunks, mono=mono, spans=spans
+        )
+        found = rules(answer, "speech_not_transcribed")
+        self.assertEqual(len(found), 2)
+        first, second = found
+        self.assertEqual(first["at"]["shot"], "A")
+        self.assertLessEqual(first["at"]["end"], 5.6)
+        self.assertEqual(second["at"]["shot"], "B")
+        self.assertGreaterEqual(second["at"]["seconds"], 8.0)
+        self.assertLess(sum(f["value"] for f in found), 8.0)
+
     def test_under_a_second_of_audible_sound_in_a_long_gap_is_not(self):
         chunks = words("alpha bravo", 0.0) + words("charlie delta", 5.0)
         mono = numpy.concatenate([voiced(1.5), silent(3.5), voiced(1.0)])

From 3a3b3a1de4b95013c386e82b306674078080694b Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 23:00:00 -0500
Subject: [PATCH 076/125] feat(ltx2): #1114 - document restore-colorize's
 colour limit on low-rate/portrait sources

Template description and ltx-2.5 skill row say colour is reliable on a
24 fps 16:9 source and a low-rate or portrait one may stay grey even with
a matched prompt; the skill says to check a frame of the result. The
ic-colorization registry entry gains the B8/BP evidence (763968953985,
3579d7d376b2, cf3ad9b05f4f; 718e232f76b0 for contrast). COMPACT_BUDGET
re-measured at 12_344: unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 loras/ltx-2.5/ic-colorization.json             | 5 +++++
 plugins/dw/skills/ltx-2.5/SKILL.md             | 5 ++++-
 tests/test_catalog_structure.py                | 3 +++
 workflows/templates/ltx2/restore-colorize.json | 2 +-
 4 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/loras/ltx-2.5/ic-colorization.json b/loras/ltx-2.5/ic-colorization.json
index 4defa78d..54fca93f 100644
--- a/loras/ltx-2.5/ic-colorization.json
+++ b/loras/ltx-2.5/ic-colorization.json
@@ -22,6 +22,11 @@
       "job": "b70c30a5e8e4",
       "issue": 1064,
       "note": "templates/ltx2/restore-colorize on lem (RTX 3090, uint4 SDNQ) at 960x544x121: natural colour on a greyscale street clip that the stored default prompt happens to describe, subject, framing and motion kept, 121 frames at the source's 24 fps; the colour holds only with a prompt matched to the clip - on an office-interview fixture the default and two generic prompts left it grey (1521f00bcf5a, 69e6bb12d56b, PSNR 36.7 dB to the source) and a prompt describing that clip and naming its colours coloured it (f80056a98e62, 49 frames, PSNR 30.2 dB); a portrait 384x544x97 run (c01a0fc6df48) came back at source size with no band or colour from the letterbox padding; 2.5 min including a cold load"
+    },
+    {
+      "job": "763968953985",
+      "issue": 1064,
+      "note": "Colour is reliable on a 24 fps 16:9 source and not on a low-frame-rate or portrait one, even with a clip-matched prompt (feature check, develop @ c69a6cbf, seed 1080): the 960x544 24 fps 121-frame office fixture coloured (718e232f76b0: warm skin, brown hair, blue lanyard); the same subject at 8 fps, 97 frames, stayed grey with frame_rate omitted (763968953985) and with frame_rate 24 (3579d7d376b2), and a 384x544 portrait crop, 97 frames, stayed grey (cf3ad9b05f4f) - each with only a faint blue lanyard, at the right rate, size and frame count, with no band or bleed. Cause not established (3x motion per frame at 8 fps; about 60% letterbox padding in the portrait's reference); check a frame of the result"
     }
   ],
   "license": "other",
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index 229ce46a..e9a2abc3 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -60,7 +60,10 @@ schedule that is not a knob (except refine-in-place's `strength`, 0 preserve
   rate (`frame_rate` overrides the rate), with no soundtrack. Colorize
   colours only what the prompt names: look at a source frame
   (`get_output_frames`) and write both prompt panels for that clip, naming
-  its colours - the default is an example and leaves an unlike clip grey. Each inverts one defect and no other - neither upscales or
+  its colours - the default is an example and leaves an unlike clip grey.
+  Reliable on 24 fps 16:9; a low-rate or portrait source may stay grey even
+  so: check a frame of the result; if it is grey, this route doesn't take
+  that source. Each inverts one defect and no other - neither upscales or
   removes motion blur or grain - so name the defect and let the user
   correct you. To upscale or sharpen: `templates/ltx2/upscale-clip`
   (IC-LoRA re-render), `width`/`height` the render size, or `refine-clip`
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index 67c5226c..e0606f18 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -525,6 +525,9 @@ def test_no_stale_entry_in_the_allowlist():
 # Re-measured at 12_344 after `ltx2/restore-deblur` and `restore-decompression`
 # took restore-colorize's fit shape (#1090, stage #1108, 2026-10-31): both
 # summaries got shorter, so the budget stands.
+# Re-measured at 12_344 after `ltx2/restore-colorize`'s description gained its
+# low-rate/portrait colour limit (#1064, stage #1114, 2026-10-31): its summary
+# did not change, so the budget stands.
 COMPACT_BUDGET = 12_400
 FILTERED_BUDGET = 1_500
 
diff --git a/workflows/templates/ltx2/restore-colorize.json b/workflows/templates/ltx2/restore-colorize.json
index b42edb40..6ac031ea 100644
--- a/workflows/templates/ltx2/restore-colorize.json
+++ b/workflows/templates/ltx2/restore-colorize.json
@@ -1,6 +1,6 @@
 {
     "id": "LTX2Colorize",
-    "description": "Restores natural colour to black-and-white or washed-out source footage with the Colorization in-context LoRA, the monochrome clip attached as a reference for the whole denoise - so the subject, the framing and the motion are the ones that were shot and only the colour changes. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so any aspect ratio comes back at the source's own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket weakens the effect. 'lora_scale' is 1.0 - lower it toward 0.8 if the colour oversaturates or bleeds across edges. The prompt follows the trained dual-panel convention ('Reference shows ... COLORIZE ... only color information differs') and must describe this clip and name its colours: the LoRA colours only what the prompt names, so the default - a worked example describing a street scene - leaves an unlike clip grey. Look at a frame of the source and write both panels for it. A 0.9 preview weight, run here under uint4 SDNQ.",
+    "description": "Restores natural colour to black-and-white or washed-out source footage with the Colorization in-context LoRA, the monochrome clip attached as a reference for the whole denoise - so the subject, the framing and the motion are the ones that were shot and only the colour changes. A first step fits the source to 'width'/'height' and 'num_frames' by letterboxing and a last step crops the padding back off, so any aspect ratio comes back at the source's own size; a longer source is cut to its opening 'num_frames' frames, a shorter one held on its last frame and trimmed back. The output has one frame per source frame and is written at the source's own frame rate (the model itself runs at its 24 fps); 'frame_rate' overrides that rate, never the frame count. Trained at 960x544, 121 frames, which is what the defaults are; generating far above that bucket weakens the effect. 'lora_scale' is 1.0 - lower it toward 0.8 if the colour oversaturates or bleeds across edges. The prompt follows the trained dual-panel convention ('Reference shows ... COLORIZE ... only color information differs') and must describe this clip and name its colours: the LoRA colours only what the prompt names, so the default - a worked example describing a street scene - leaves an unlike clip grey. Look at a frame of the source and write both panels for it. Colour is reliable on a 24 fps 16:9 source; a low-frame-rate or portrait source may stay grey even with a matched prompt, so check a frame of the result. A 0.9 preview weight, run here under uint4 SDNQ.",
     "summary": "Colourises black-and-white or washed-out footage, keeping the source's size, frame rate and motion.",
     "traits": [
         "needs-input-media"

From 6b1afbf65263be4f3b8711bb268e8b137c21db6b Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 23:03:50 -0500
Subject: [PATCH 077/125] docs(proposals): #1101 - close-out record for
 refusing for_each cross-entry references

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/for-each-cross-entry-complete.md | 133 ++++++++++++++++++
 .../script-to-video-joins-complete.md         |   8 +-
 docs/proposals/todo.md                        |  10 ++
 3 files changed, 147 insertions(+), 4 deletions(-)
 create mode 100644 docs/proposals/complete/for-each-cross-entry-complete.md

diff --git a/docs/proposals/complete/for-each-cross-entry-complete.md b/docs/proposals/complete/for-each-cross-entry-complete.md
new file mode 100644
index 00000000..3b1d9dea
--- /dev/null
+++ b/docs/proposals/complete/for-each-cross-entry-complete.md
@@ -0,0 +1,133 @@
+# Refuse a literal cross-entry reference inside one `for_each` group (#1101)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-10-31). Plan v1 was approved by Don on 2026-10-31 with every question
+at its default. Its only stage, A (#1111), shipped the same day at
+`develop` @ `9b65ba80`, and an architecture-review fix followed at
+`168a61ce`. It was verified on lem.
+
+## The idea
+
+Inside a `for_each` expansion, a member could read another entry of the same
+list with a literal reference, such as `previous_result:shot@a` inside
+`shot@b`. Validation let it through. `_rewrite_reference` only refuses a
+*bare* reference to the member's own group, and
+`previous_result_reference_errors` only checks that the name belongs to an
+earlier step. It then resolved at run time, backward only. No test pinned
+it, but `docs/WORKFLOW_GUIDE.md` promised it ("A member may reference an
+*earlier* member of its own list directly"). #1101 was filed as a follow-up
+to #1093, so Don could decide whether to pin it or refuse it.
+
+Demand: #509, #511 and #813 show driving sessions chaining shots inside one
+list this way. Each run failed after GPU time had been spent, because the
+earlier member's result was a video. #813 patched only the video case.
+
+## Verdict and scope (Don, 2026-10-31)
+
+**Refuse it.** Validation rejects a literal reference from one entry of a
+`for_each` into another entry of the same expansion. The error names both
+entries and points at separate runs plus `output:` references (#1093's
+recipe). A cutaway inside one workflow would be a new feature with its own
+design.
+
+Don required a check, before any change, that nothing used the form. It came
+back clean: catalog `workflows/`, packaged `dw/workflows/`, `plugins/dw/`
+and `tests/fixtures` were checked at design time. Every lem workspace was
+checked at the start of the build (Q4), with `use_workspace`,
+`list_workflows` and `get_workflow` on each list-driven workflow.
+
+## Decisions (Don's review of plan v1, 2026-10-31)
+
+- **Q1:** the ruling stands even though the guide promised the form. The
+  guide paragraph is replaced by separate runs plus `output:` references.
+- **Q2:** a *different* group over the same list (`trim@b` reading
+  `shot@a`) stays legal. Every `shot@*` has run before any `trim@*`, so
+  entry order carries no meaning there.
+- **Q3:** one error, not two. The new check wins, and #813's
+  `video_into_image_errors` skips a reference the new check refuses, since
+  its `get_last_frame` advice can't be followed inside one list.
+- **Q4:** the lem workspace check ran at the start of the build (clean).
+
+## What was built
+
+### Stage A, #1111: refuse the reference
+
+- **The check.** `cross_entry_reference_errors` in `dw/previous_results.py`,
+  registered as `cross_entry_references` in `dw/validation.py`'s
+  `ERROR_CHECKS`, right after `previous_result_references`. Every path runs
+  it: `/api/validate`, job submission, library save, MCP
+  `validate_workflow`, the CLI and composed children.
+  - **Refuses:** a member `G@k` holding a literal reference to `G@j`
+    (j ≠ k). That covers the `previous_result:` prefix, `from_previous_result`
+    (including inside an `item:`-spliced `references` entry), with or
+    without a `.property` suffix, and index keys (`shot@1` → `shot@0`).
+  - **Error:** `{path, message}`. The path points at the authored step. The
+    message names both members and the sibling key, and gives the fix:
+    "Generate 'a' in its own run and pass its file to this one as an
+    output: reference (guide: for_each)."
+- **The sibling rule's owner.** `cross_entry_key` in `dw/for_each.py`, next
+  to `group_of`. Its three callers are the new check, the earlier-step skip
+  in `previous_result_reference_errors`, and the skip in
+  `video_into_image_errors`. `docs/ARCHITECTURE.md`'s previous-result check
+  row names it.
+- **One error per reference.** `video_into_image_errors` skips a refused
+  reference (Q3). A *forward* sibling reference (`shot@a` reading `shot@b`)
+  also gets only the cross-entry error, not also "names no earlier step".
+  That second skip was a build deviation in the same spirit as Q3.
+- **UI.** `memberRefusal` in `ui/src/lib/flow.ts` refuses the same form,
+  with a reason naming the sibling. The shared case table
+  `tests/fixtures/reference_cases.json` gains `cross_entry_same_group`
+  (refused) and `other_group_other_key` (legal, Q2), so the engine and the
+  UI are held to one verdict.
+
+### Tests and docs
+
+- `tests/test_previous_results.py::TestCrossEntryReferences`, every case
+  through the real validate path. Refused: the prefix, `from_previous_result`
+  in a spliced entry, `.property`, index keys and a forward sibling. Legal:
+  same key (bare and literal), a later step, `gather:`, a different group
+  over the same list, and a group over a different list.
+- `tests/test_video_extensions.py::TestVideoIntoImage` is reframed. The real
+  validate path asserts the cross-entry refusal and the absence of #813's
+  message. The unit case moved to `refine@b` → `shot@a`, plus a sibling-skip
+  case.
+- `tests/test_validation.py`'s pinned `ERROR_ORDER` gains
+  `cross_entry_references`.
+- `docs/WORKFLOW_GUIDE.md`: entries of one list can't read each other (use
+  separate runs plus `output:`), and same-key pairing is the only
+  member-to-member read.
+- `docs/ARCHITECTURE.md`: the previous-result check row gains the rule,
+  `cross_entry_key` and its test.
+
+## Verified
+
+On lem, over MCP only, against `develop` @ `168a61ce`: C-F590 to C-F593.
+These cover the refusal at `validate_workflow` and at `run_workflow`
+submission (no job queued), the `references`/`.property`/index-key forms,
+the forms that must stay legal (with one real CPU run of a cross-group read),
+the catalog templates `templates/minimax/music-video` and
+`templates/ltx2/restore-long` still validating clean, and one error, not
+two, on a video read as `image`. The UI twin can't be checked over MCP. The
+shared fixture case and `npm test` cover it.
+
+## Bounces per stage
+
+- **Stage A, #1111: 1.**
+  - **Architecture review (1):** `cross_entry_key` first lived in
+    `dw/references.py` and split member names itself, which made it a second
+    owner of `for_each.group_of`'s rule. The map also didn't name it. Fixed
+    by moving it into `dw/for_each.py` on top of `group_of` and adding it to
+    the map row. Behaviour didn't change.
+  - **Tester: 0.**
+
+Cost per stage isn't recorded: the stage comments name no `usage:` figures.
+The plan estimated about $3.
+
+## Deferred
+
+- **Chaining or cutaways inside one list.** Out of scope by Don's ruling. It
+  would be a new feature with its own design. Until then, a cutaway's A→C
+  source uses separate runs and `output:` references (#1093's recipe).
+- **A direct Python `Workflow.run` that skips validation** would still
+  resolve the reference. Every server, MCP and CLI path validates first, so
+  the plan accepted this.
diff --git a/docs/proposals/complete/script-to-video-joins-complete.md b/docs/proposals/complete/script-to-video-joins-complete.md
index 7fdd486a..ab18baf3 100644
--- a/docs/proposals/complete/script-to-video-joins-complete.md
+++ b/docs/proposals/complete/script-to-video-joins-complete.md
@@ -29,8 +29,8 @@ continues from the insert or starts cold.
 - **`for_each` can't say it either.** There is no relative indexing, and
   groups expand whole, so no per-entry frame grab can sit between entries.
   A literal `from_previous_result: "shot@<key>"` cross-entry reference
-  slips through today but no test pins it. It was filed as #1101
-  (`owner:don`) rather than relied on.
+  slipped through then, with no test pinning it. It was filed as #1101,
+  and validation now refuses it (`complete/for-each-cross-entry-complete.md`).
 - **Separate runs can say it.** `get_first_frame` / `get_last_frame` read
   `output:` files. The renderers both joins need already exist:
   `templates/minimax/image-to-video`, `first-and-last-frame`,
@@ -134,8 +134,8 @@ runs.
   segments) are parked undecided: they touch the same loop.
 - **A non-adjacent continuity probe.** The A→C match is judged by eye, and
   the engine route would add one.
-- **The `shot@<key>` cross-entry reference**: #1101, Don's call to pin or
-  refuse it.
+- **The `shot@<key>` cross-entry reference**: #1101. Don ruled to refuse
+  it, and it shipped 2026-10-31 (`complete/for-each-cross-entry-complete.md`).
 - **Related improvements:** #1032 (sharpest-of-N last frame) would improve a
   cutaway's re-entry frame. #1067 (colour-match a region to its source)
   could match C's colour to A's tail.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index deae408f..165272ec 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -453,6 +453,16 @@ remaining deferred fix is recorded in
   Landed as a "Probed, not a rule" entry in `minimax-h3/references/cuts.md`;
   no template. Record, including the re-probe protocol and the template's
   reopen trigger: `complete/h3-odd-then-bridge-complete.md`.
+- **Refuse a literal cross-entry reference inside one `for_each` group**
+  (#1101, stage #1111), shipped 2026-10-31. Don ruled to refuse it rather
+  than pin it. A member `G@k` reading `G@j` (j ≠ k) with a literal
+  `previous_result:`/`from_previous_result` reference is now a validation
+  error that names both members and points at separate runs plus `output:`.
+  It applies on every path, and the UI gives the same verdict. A different
+  group over the same list stays legal, and #813's video-into-image advice
+  is skipped for a refused reference. The guide no longer promises the form.
+  Record, including the deferred in-list cutaway:
+  `complete/for-each-cross-entry-complete.md`.
 
 ## Declined
 

From 635d46c5637a9f2bde09d817be486ed59bbc3711 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 23:14:40 -0500
Subject: [PATCH 078/125] fix(check-script): #1115 - split an untranscribed
 block at the shot seam so each shot is credited

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/script_check.py   | 20 ++++++++++++++++++++
 tests/test_script_check.py | 18 ++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index e6329404..bfadc493 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -782,7 +782,27 @@ def _audible_findings(
     attributed to the shot holding most of it - and to the line naming that
     shot, null when none does - not to the stretch's own line by default."""
     found = []
+    pieces = []
     for lo, hi in _audible_runs(mono, sample_rate, start, end):
+        # A block crossing a shot seam is one finding per shot (#1115), so the
+        # shot that holds the untranscribed speech is named even if the other
+        # holds more of the block.
+        cuts = [lo]
+        if spans is not None:
+            cuts += sorted(
+                {s["start"] for s in spans if lo < s["start"] < hi}
+                | {s["end"] for s in spans if lo < s["end"] < hi}
+            )
+        cuts.append(hi)
+        parts = [
+            (a, b)
+            for a, b in zip(cuts, cuts[1:])
+            if b - a >= UNHEARD_MIN_SECONDS + 2 * UNHEARD_MARGIN_SECONDS
+        ]
+        # Split only when each side is substantial; else one finding, placed
+        # by majority as before (#964)
+        pieces.extend(parts if len(parts) > 1 else [(lo, hi)])
+    for lo, hi in pieces:
         where_line, where_shot = index, shot
         holder = None if spans is None else overlapping_shot(spans, lo, hi)
         if holder is not None and holder != shot:
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index 1e4cf969..b0216aee 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -880,6 +880,24 @@ def test_a_stretched_word_reports_each_audible_block_in_its_own_shot(self):
         self.assertGreaterEqual(second["at"]["seconds"], 8.0)
         self.assertLess(sum(f["value"] for f in found), 8.0)
 
+    def test_a_block_crossing_a_shot_seam_is_credited_to_both_shots(self):
+        # #1115: sound 3-8 s, seam at 5: the larger half is in B, but the
+        # first half in A must be reported against A, not swallowed
+        spans = [
+            {"name": "A", "start": 0.0, "end": 5.0},
+            {"name": "B", "start": 5.0, "end": 11.0},
+        ]
+        chunks = [
+            {"start": 0.9, "end": 10.6, "text": " alpha"},
+            {"start": 10.6, "end": 11.0, "text": " bravo"},
+        ]
+        mono = numpy.concatenate([silent(3.0), voiced(5.0), silent(3.0)])
+        answer = shot_run(
+            [{"text": "alpha bravo", "shot": "B"}], chunks, mono=mono, spans=spans
+        )
+        found = rules(answer, "speech_not_transcribed")
+        self.assertEqual({f["at"]["shot"] for f in found}, {"A", "B"})
+
     def test_under_a_second_of_audible_sound_in_a_long_gap_is_not(self):
         chunks = words("alpha bravo", 0.0) + words("charlie delta", 5.0)
         mono = numpy.concatenate([voiced(1.5), silent(3.5), voiced(1.0)])

From 7f5a64610619b6a0642f9a5d1d1b698b9c9e5fa3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 23:18:03 -0500
Subject: [PATCH 079/125] docs(proposals): #1064 - close-out record adds
 fix-forward stage C (#1114), the colour limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/ltx2-ic-loras-complete.md        | 41 ++++++++++++++++++-
 docs/proposals/todo.md                        |  5 ++-
 2 files changed, 43 insertions(+), 3 deletions(-)

diff --git a/docs/proposals/complete/ltx2-ic-loras-complete.md b/docs/proposals/complete/ltx2-ic-loras-complete.md
index 327124b5..56f4635c 100644
--- a/docs/proposals/complete/ltx2-ic-loras-complete.md
+++ b/docs/proposals/complete/ltx2-ic-loras-complete.md
@@ -5,7 +5,9 @@ Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
 by Don on 2026-10-31 ("approve with defaults"). It was built as two stages:
 #1079 (stage A, Alpha-Gen) and #1080 (stage B, Colorization). Stage A was
 verified 2026-10-31 on develop @ 6b1dcfcb, stage B 2026-11-01 on develop
-@ fc0a40d9, both on lem over MCP.
+@ fc0a40d9, both on lem over MCP. The feature's final check then bounced on
+M-F293 (below); plans v11-v12 added a text-only fix-forward stage, #1114
+(stage C), verified 2026-11-01 on develop @ 96dbdd91.
 
 ## The report
 
@@ -128,6 +130,36 @@ Verified with clip-matched prompts: the black-and-white office fixture at
 overrides it with near-identical frames (41.0 dB, SSIM 0.982); a 384x544
 portrait comes back at its own size with no letterbox band or edge bleed.
 
+### Stage C (#1114): `restore-colorize`'s colour limit, documented (fix-forward)
+
+Commit: `3a3b3a1d` (merged `f3fdb6cf`).
+
+**Why.** The feature's final check bounced on M-F293: with a clip-matched
+prompt, `restore-colorize` coloured the 24 fps 16:9 fixture (`718e232f76b0`)
+but left the same subject grey at 8 fps, 97 frames (`763968953985`, and
+`3579d7d376b2` with `frame_rate: 24`) and as a 384x544 portrait
+(`cf3ad9b05f4f`), with only a faint blue lanyard. Rate, size, frame count
+and no-band all held. No template change was known to fix it, so this was a
+plan gap, not a build miss. The likely suspects are the 8 fps motion per
+frame (the LoRA is trained at 24) and the portrait's letterbox padding
+(about 60% of the reference is black); the cause was not screened. Don
+ruled Q12 (a): document the limit and close, no GPU screen (Q12 (b)) and no
+withdrawal (Q12 (c)).
+
+- Template description: "Colour is reliable on a 24 fps 16:9 source; a
+  low-frame-rate or portrait source may stay grey even with a matched
+  prompt, so check a frame of the result." `COMPACT_BUDGET` re-measured.
+- `ltx-2.5` skill row: the same limit, plus "check a frame of the result;
+  if it is grey, this route doesn't take that source".
+- `ic-colorization` evidence note: the B8/BP result with the three grey
+  jobs, and `718e232f76b0` for contrast.
+- No engine, step or variable change; the output still follows the
+  source's frame rate (Q7).
+
+Verified by M-F294 (M-F293 with colour as a record: all three arms grey,
+every rate/geometry/no-band point held; jobs `5fb3d6a80467`,
+`7c885d73df4a`, `23b79bb81090`) and M-F295 (the wording, free).
+
 ### Records for the two not onboarded
 
 `ic-clean-plate` and `ic-day-to-night` stay `trial`, `workflow: null`, each
@@ -152,6 +184,10 @@ with an `evidence` item `{issue: 1064, note}`:
 - **Clean-Plate, Day-To-Night, SDR-To-HDR:** recorded above / out of scope.
 - **Moving other templates to the source's rate:** Don's Q7 audit, filed
   separately as #1090.
+- **Why `restore-colorize` stays grey on a low-rate or portrait source**
+  (Q12 (b)): documented, not explained. A field report that hits it starts
+  from Q12 (b)'s bounded screen (8 fps motion, letterbox padding, length)
+  as a feature of its own.
 
 ## Cost and bounces
 
@@ -170,6 +206,9 @@ estimated stage B's first build at about $3.5.
   three fixtures with the default prompt (finding 7). Re-planned (v9/v10)
   to put the per-clip prompt on the caller. One verify session in between
   did not run (incomplete MCP surface) and is not counted.
+- **Stage C (#1114): 0 bounces, 1 build.** Estimated at about $0.5.
+- **Feature final check: 1 bounce** (M-F293, the B8/BP colour limit),
+  answered by stage C.
 - A licence gate on the Colorization LoRA parked stage B once until Don
   accepted it on Hugging Face (2026-10-31).
 
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 165272ec..54115552 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -47,10 +47,11 @@ remaining deferred fix is recorded in
   (retiming, `extend-clip`, the restores' soundtrack):
   `complete/source-fps-one-for-one-complete.md`.
 - **The remaining LTX-2.5 IC-LoRAs: `ltx2/alpha-matte` and
-  `ltx2/restore-colorize`** (#1064, stages #1079-#1080), shipped
+  `ltx2/restore-colorize`** (#1064, stages #1079-#1080, #1114), shipped
   2026-11-01. A grey soft-matte MP4 at the source's size and frame rate
   (Alpha-Gen), and black-and-white colourising with a caller-written,
-  clip-matched prompt (Colorization), plus `source_fps` on the fit record
+  clip-matched prompt (Colorization; reliable on 24 fps 16:9, a low-rate or
+  portrait source may stay grey, documented), plus `source_fps` on the fit record
   and `fps` on `restore_to_source`. Clean-Plate and Day-To-Night are
   recorded in their registry entries as not onboarded. Record, including
   what was deferred (alpha output, cut detection, auto-captioning, the

From 1bb6b87aab997626a5c194a2aa320d5125ccfe36 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sat, 31 Oct 2026 23:53:36 -0500
Subject: [PATCH 080/125] fix(check-script): #1115 - keep a line's timing
 inside its shot; check an unheard line's clip

A line's lines[] start/end are clamped to the shot it belongs to, the ASR's
own times kept as asr_start/asr_end. A line nothing was heard for gets
line_clipped_at_end through the untranscribed speech credited to it, or a
per-line rules_skipped entry when that cannot be judged. Shot helpers and
audible_runs move to script_take to hold script_check under the size ceiling.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md       |   2 +-
 docs/TASKS.md              |   4 +-
 dw/tasks/script_check.py   | 130 +++++++++++++++++++------------------
 dw/tasks/script_take.py    |  79 +++++++++++++++++++++-
 tests/test_script_check.py |  77 ++++++++++++++++++++++
 5 files changed, 225 insertions(+), 67 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 2c89c5ee..0b3a6964 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -141,7 +141,7 @@ one to open.
 | Output comparison | `dw/media_compare.py`: `compare`, `psnr`, `ssim`, `mean_abs_diff`, `check_request`, `crop_box` | Metrics always compare the same pixels: one shared crop is the measured region, and per-output crops are display only, leaving metrics on the full frame. An output whose size differs from the baseline's, or a moment past its end, gets null metrics with a reason; nothing is resized to force a number. SSIM is on Rec. 601 luma (SSIM's convention, not `image_ops.luma`). It runs in the server process and decodes through `dw/media.py` and `open_bounded`. | `tests/test_compare_route.py::test_a_shared_crop_is_the_region_measured`, `tests/test_compare_route.py::test_per_output_crops_are_display_only`, `tests/test_compare_route.py::test_a_size_mismatch_gets_no_numbers_and_says_why`, `tests/test_compare_route.py::test_a_moment_past_the_shorter_clip_is_a_blank_cell` |
 | Signal processing | `dw/dsp.py` | It measures and transforms waveforms, decides nothing, and imports nothing from `dw`. | `tests/test_media_layering.py::test_dsp_imports_nothing_from_dw` |
 | Assessment probes | `dw/tasks/assess.py`, `dw/assessment_rules.py` | Exactly three registered commands are assessment probes. Each measures a finished file, and every rule names a real probe field. | `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_assessment_is_exactly_the_three_probes`, `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_every_rule_names_a_registered_json_command` |
-| Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` (`script_take.word_level` wraps it; the guard, the transcription levelling and the shot placement are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
+| Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` (`script_take.word_level` wraps it; the guard, the transcription levelling, the floor-gated `audible_runs` and the shot placement (with `clamp_to_shot`, a line's timing kept inside its shot) are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
 | Audio sync against a source slice | `dw/tasks/measure_sync.py`: `measure_sync`; `dw/dsp.py`: `envelope_lag` | `measure_sync` cross-correlates the onset envelopes of a shot's audio and its source slice and answers the lag and a 0-1 confidence. A positive lag means the audio is LATE (its events fall after the reference's), negative early; `lag_seconds` is None for a silent or flat track. It builds its findings (`sync_unmeasurable`, `sync_low_confidence`, `audio_out_of_sync`) with `assessment_rules.finding()` over module-local rule dicts and adds nothing to `RULES`; it reads the silence floor from `beats.SILENT_DBFS`. `envelope_lag` imports nothing from `dw`. | `tests/test_measure_sync.py::TestLag::test_late_audio_is_a_positive_lag`, `tests/test_measure_sync.py::TestLag::test_early_audio_is_a_negative_lag`, `tests/test_measure_sync.py::TestUnmeasurable::test_a_silent_reference_has_no_lag` |
 | Sung phrases from voiced energy | `dw/tasks/phrases.py`: `analyze_phrases`, `voiced_power`, `voiced_runs`; `dw/task_problems.py`: `phrases_problems`, `phrases_errors` | `analyze_phrases` times a song's sung phrases with no model: a stereo file's centre-weighted band power (max(0, P_mid - P_side), 250-3500 Hz, 20 ms frames) or, for mono, `centre: false` or identical channels, the downmix's band power (`method` `band`). The voiced floor is `voice_attribution.voiced_floor_dbfs`, the rule `attribute_voices` uses, unless `floor_db` is given. It answers a dict - `{phrases, duration_seconds, method, warnings}` - so a step saves one JSON artifact. Its ranges are the registration's domains; `phrases_problems` (a real boolean `centre`) runs at validate and at run time. | `tests/test_analyze_phrases.py::TestCentre::test_centred_bursts_under_hard_panned_noise_are_found`, `tests/test_analyze_phrases.py::TestCentre::test_bursts_panned_hard_to_one_side_are_not_centre`, `tests/test_analyze_phrases.py::TestRefusals::test_validate_refuses_a_missing_audio_and_a_negative_gap` |
 
diff --git a/docs/TASKS.md b/docs/TASKS.md
index 1eb6a49a..bc501c28 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3296,7 +3296,7 @@ Markup stripped from an expected line: `<d>[Language] ...</d>`, `<scenetrans>`,
 | `line_mismatch` | A line's similarity is below `similarity`; a dropped line comes back with `heard: ""` | The line's similarity / `similarity` | `{line, seconds, word}` - the line's first heard word, or where it should have been |
 | `tag_spoken` | A word from the line's stripped markup was heard, and is not also a word of the line's dialogue | The word heard / none | `{line, seconds, word}` |
 | `transcript_loop` | A repetition loop (`REPEAT_RUN_MIN` periods of up to `REPEAT_MAX_PERIOD` words) made only of words the script holds - Whisper stuck on a line it heard, so speech after it can be missing from `heard` and lines read 0.0 without being wrong (#961). The loop's first occurrence is kept as heard when it has real duration and speech level; the rest is under `discarded`, one entry per loop (`count`, `start`..`end`). A line heard nowhere, at or after the loop, reads `heard: null`, `similarity: null`, `not_transcribed: "transcript_loop"` and raises no `line_mismatch`. When the shots are known the cut is then transcribed again one shot at a time and the findings and `lines` come from that pass (`transcription_pass: "per_shot"`, each line `pass: "per_shot"`, #963) | Chunks in the loop / `REPEAT_RUN_MIN` | `{line: null, seconds, end}` |
-| `line_clipped_at_end` | A line's last heard word ends inside the final `CLIP_TAIL_SECONDS` of its shot (when the line has one) or of the file, and that tail is still above `GUARD_FLOOR_DBFS` and within `CLIP_TAIL_BELOW_WORD_DB` of the last word's own loudest window (a quieter tail is a score bed or room tone, not the word - #953) | The tail's level in dBFS / `GUARD_FLOOR_DBFS` | `{line, seconds, word, shot}` - `shot` when the line has one |
+| `line_clipped_at_end` | A line's last heard word ends inside the final `CLIP_TAIL_SECONDS` of its shot (when the line has one) or of the file, and that tail is still above `GUARD_FLOOR_DBFS` and within `CLIP_TAIL_BELOW_WORD_DB` of the last word's own loudest window (a quieter tail is a score bed or room tone, not the word - #953) | The tail's level in dBFS / `GUARD_FLOOR_DBFS` | `{line, seconds, word, shot}` - `shot` when the line has one. A line nothing was heard for has no last word: when a `speech_not_transcribed` block credited to it runs to its shot's end and that tail is voiced, it fires at the block's end with no `word` (#1115); otherwise the line is listed in `rules_skipped` with its `line` index |
 | `speech_where_silent` | `lines` is `[]` and words were heard above the floor and outside a repetition loop | Number of words heard / 0 | `{line: null, seconds, word}` - the first; `shot` when shots are known |
 | `speech_in_silent_shot` | Shots are known, at least one line names a shot, and words were heard above the floor and outside a repetition loop in a shot no line names. A word is in the shot its midpoint falls in; one a line in another shot matched (a word straddling the cut) is that line's, not counted | Number of words heard in the shot / 0 | `{line: null, seconds, word, shot}` - the shot's first counted word, `seconds` no earlier than the shot's start |
 | `unscripted_speech` | Shots are known and a line names the shot; words were heard inside it that align to no line (a line spoken twice, an ad-lib) | Number of unmatched words in the shot / 0 | `{line: null, seconds, end, word, shot, repeats_line}` - the first such word; `repeats_line` is true when those words repeat or contain one of the shot's lines |
@@ -3317,7 +3317,7 @@ The thresholds are module constants in `dw/tasks/script_check.py` (the guard's `
 | `REPEAT_RUN_MIN` | 6 | Heard words repeating the same unit this many times over, back to back, are a repetition loop: every chunk holding one is discarded (`reason: "repetition"`), however loud |
 | `REPEAT_MAX_PERIOD` | 4 words | The longest repeating unit a loop is looked for in - `pre pre pre` has period 1, `thank you thank you` period 2 |
 
-The result: `findings`, `lines[]` (`expected`, `heard`, `similarity`, `start`, `end`, `shot`), `discarded[]` (`text`, `start`, `end`, `level_dbfs`, `reason` - `below_floor`, `repeated_span` (a chunk repeating the previous one's exact span) or `repetition`, `count` - a repetition loop is one entry spanning its chunks), `unmatched[]` (heard words aligned to no line), `transcript`, `model_name`, `rules_applied`, `rules_skipped[]` (`rule`, `reason`) and `thresholds`. A line's `shot` is the shot it names, else the shot its heard words overlap most (null when none is known). `shots` is the map as placed - `[{name, start, end}]` in seconds on the take, or null when none is known - and `shots_source` says where it came from: `argument`, `artifact`, `manifest` or `none`.
+The result: `findings`, `lines[]` (`expected`, `heard`, `similarity`, `start`, `end`, `shot`; with the shot known, `start` and `end` are kept inside it, and the ASR's own times, when they fall outside - a word stretched across the seam over speech Whisper dropped - are kept as `asr_start` / `asr_end`, #1115), `discarded[]` (`text`, `start`, `end`, `level_dbfs`, `reason` - `below_floor`, `repeated_span` (a chunk repeating the previous one's exact span) or `repetition`, `count` - a repetition loop is one entry spanning its chunks), `unmatched[]` (heard words aligned to no line), `transcript`, `model_name`, `rules_applied`, `rules_skipped[]` (`rule`, `reason`, and `line` for a per-line skip) and `thresholds`. A line's `shot` is the shot it names, else the shot its heard words overlap most (null when none is known). `shots` is the map as placed - `[{name, start, end}]` in seconds on the take, or null when none is known - and `shots_source` says where it came from: `argument`, `artifact`, `manifest` or `none`.
 
 How the alignment reads a take:
 
diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index bfadc493..55a29056 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -31,7 +31,8 @@
    shot no line names is meant to be silent (`speech_in_silent_shot`), and a
    line's last word is checked against the end of its shot as well as the
    end of the file (`line_clipped_at_end`). With no shots known those are
-   listed under `rules_skipped` with the reason, never reported clean.
+   listed under `rules_skipped` with the reason, never reported clean (an
+   unheard line's clip: `_unheard_line_clips`, #1115).
 
 It decides nothing. Like the probes, its findings are places to look and are
 built with `assessment_rules.finding()`; unlike them it is not
@@ -68,13 +69,16 @@
 from .script_take import (
     GUARD_FLOOR_DBFS,
     GUARD_WINDOW_SECONDS,
+    audible_runs,
+    clamp_to_shot,
+    heard_shot,
     round_seconds,
     guard_words,
     level_for_transcription,
     overlapping_shot,
     per_shot_chunks,
-    shot_at,
     shot_spans,
+    shots_entry,
     word_level,
 )
 
@@ -348,19 +352,6 @@ def _no_shot_reason(shots_source, spans, parsed_lines):
     return None
 
 
-def _shots_entry(spans):
-    if spans is None:
-        return None
-    return [
-        {
-            "name": span["name"],
-            "start": round_seconds(span["start"]),
-            "end": round_seconds(span["end"]),
-        }
-        for span in spans
-    ]
-
-
 def check(
     parsed_lines,
     chunks,
@@ -422,13 +413,16 @@ def check(
         similarity_threshold,
     )
     findings.extend(found)
+    found, unchecked = _unheard_line_clips(mono, sample_rate, lines, findings, spans)
+    findings.extend(found)
+    rules_skipped.extend(unchecked)
     findings.sort(key=lambda found: found["at"].get("seconds") or 0.0)
     return {
         "findings": findings,
         "lines": lines,
         "discarded": discarded,
         "unmatched": [_heard_entry(heard[j]) for j, _ in unassigned],
-        "shots": _shots_entry(spans),
+        "shots": shots_entry(spans),
         "shots_source": shots_source,
         "rules_applied": rules_applied,
         "rules_skipped": rules_skipped,
@@ -492,6 +486,7 @@ def _line_pass(
             mismatch=mismatch,
             similarity_threshold=similarity_threshold,
         )
+        clamp_to_shot(entry, span)
         lines.append(entry)
         findings.extend(found)
         if not own:
@@ -543,6 +538,46 @@ def _line_pass(
     return lines, claimed, findings
 
 
+def _unheard_line_clips(mono, sample_rate, lines, findings, spans):
+    """line_clipped_at_end for a line nothing was heard for (#1115): it has no
+    last word, so the speech_not_transcribed blocks credited to it stand in -
+    one running to its shot's voiced end is a shot stopping mid-speech. An
+    unheard line no block of reaches its shot's end is listed in
+    `rules_skipped` with its index, never reported clean. Returns (findings,
+    skipped)."""
+    by_name = {span["name"]: span for span in spans or ()}
+    found, skipped = [], []
+    for index, entry in enumerate(lines):
+        span = by_name.get(entry["shot"])
+        if entry["start"] is not None:
+            continue
+        key = (index, span and span["name"])
+        ends = [
+            f["at"]
+            for f in findings
+            if span
+            and f["rule"] == SPEECH_NOT_TRANSCRIBED["name"]
+            and (f["at"].get("line"), f["at"].get("shot")) == key
+            and abs(f["at"]["end"] - span["end"]) <= CLIP_TAIL_SECONDS
+        ]
+        for at in ends:
+            tail = [(span["name"], span["end"])]
+            clipped = _clipped_tail(
+                mono, sample_rate, at["end"], tail, (at["seconds"], at["end"])
+            )
+            if clipped is not None:
+                at = {"line": index, "seconds": at["end"], "shot": span["name"]}
+                found.append(finding(CLIPPED_AT_END, round_seconds(clipped[1], 2), at))
+                break
+        if not ends:
+            reason = "nothing heard for the line reaches its shot's end, so where"
+            reason += " the line ends is unknown - check the shot on its own"
+            skipped.append(
+                {"rule": CLIPPED_AT_END["name"], "line": index, "reason": reason}
+            )
+    return found, skipped
+
+
 def _line_entry(
     index, line, words, own, shot, position, looped, mismatch, similarity_threshold
 ):
@@ -639,13 +674,6 @@ def _loop_findings(chunks, script_words):
     return found
 
 
-def _heard_shot(spans, word):
-    """The shot a heard word's midpoint falls in, None when no shots are known."""
-    if spans is None:
-        return None
-    return shot_at(spans, (word["start"] + word["end"]) / 2)
-
-
 def _silent_take(heard, discarded, spans, shots_source):
     """check's result for `lines: []`: any speech at all is the finding, and
     the line and shot rules have nothing to compare against."""
@@ -655,7 +683,7 @@ def _silent_take(heard, discarded, spans, shots_source):
             finding(
                 SPEECH_WHERE_SILENT,
                 len(heard),
-                _at(None, heard[0], shot=_heard_shot(spans, heard[0])),
+                _at(None, heard[0], shot=heard_shot(spans, heard[0])),
             )
         )
     return {
@@ -663,7 +691,7 @@ def _silent_take(heard, discarded, spans, shots_source):
         "lines": [],
         "discarded": discarded,
         "unmatched": [_heard_entry(word) for word in heard],
-        "shots": _shots_entry(spans),
+        "shots": shots_entry(spans),
         "shots_source": shots_source,
         "rules_applied": list(SILENT_RULES),
         "rules_skipped": [
@@ -744,37 +772,6 @@ def _between_lines_findings(
     return [f for f in found if f is not None]
 
 
-def _audible_runs(mono, sample_rate, start, end):
-    """The audible blocks of the stretch [start, end] (#967, #1115): each run
-    of windows above UNHEARD_FLOOR_DBFS, runs a sub-floor gap shorter than
-    UNHEARD_MIN_SECONDS apart joined, and only those lasting UNHEARD_MIN_SECONDS
-    kept. Sub-floor time is never counted or placed in a block, and a quiet
-    stretch of UNHEARD_MIN_SECONDS or more splits the stretch in two. A block
-    edge at the stretch's own (margin-trimmed) edge stays that edge."""
-    inner_start, inner_end = (
-        start + UNHEARD_MARGIN_SECONDS,
-        end - UNHEARD_MARGIN_SECONDS,
-    )
-    runs = []
-    cursor = inner_start
-    while cursor < inner_end:
-        stop = min(cursor + GUARD_WINDOW_SECONDS, inner_end)
-        level = word_level(mono, sample_rate, cursor, stop)
-        if level is not None and level > UNHEARD_FLOOR_DBFS:
-            if runs and cursor - runs[-1][1] < UNHEARD_MIN_SECONDS:
-                runs[-1][1] = stop
-            else:
-                runs.append([cursor, stop])
-        cursor = stop
-    found = []
-    for first, last in runs:
-        first = start if first <= inner_start else first
-        last = end if last >= inner_end else last
-        if last - first >= UNHEARD_MIN_SECONDS:
-            found.append((first, last))
-    return found
-
-
 def _audible_findings(
     mono, sample_rate, index, start, end, shot, spans=None, parsed_lines=()
 ):
@@ -783,7 +780,15 @@ def _audible_findings(
     shot, null when none does - not to the stretch's own line by default."""
     found = []
     pieces = []
-    for lo, hi in _audible_runs(mono, sample_rate, start, end):
+    for lo, hi in audible_runs(
+        mono,
+        sample_rate,
+        start,
+        end,
+        UNHEARD_FLOOR_DBFS,
+        UNHEARD_MIN_SECONDS,
+        UNHEARD_MARGIN_SECONDS,
+    ):
         # A block crossing a shot seam is one finding per shot (#1115), so the
         # shot that holds the untranscribed speech is named even if the other
         # holds more of the block.
@@ -857,7 +862,7 @@ def _unassigned_tags(heard, unassigned, parsed_lines, expected, spans):
                     finding(
                         TAG_SPOKEN,
                         word["word"],
-                        _at(index, word, shot=_heard_shot(spans, word)),
+                        _at(index, word, shot=heard_shot(spans, word)),
                     )
                 )
                 break
@@ -875,7 +880,7 @@ def _silent_shot_findings(spans, parsed_lines, heard, claimed):
         inside = [
             word
             for j, word in enumerate(heard)
-            if _heard_shot(spans, word) == span["name"]
+            if heard_shot(spans, word) == span["name"]
             and claimed.get(j) in (None, span["name"])
         ]
         if inside:
@@ -905,7 +910,7 @@ def _unscripted_findings(
         inside = [
             heard[j]
             for j, _ in unassigned
-            if _heard_shot(spans, heard[j]) == span["name"]
+            if heard_shot(spans, heard[j]) == span["name"]
         ]
         if not inside:
             continue
@@ -996,8 +1001,9 @@ def check_script(
         A JSON document: 'findings' (line_mismatch, tag_spoken,
         line_clipped_at_end, speech_not_transcribed, speech_where_silent, speech_in_silent_shot,
         unscripted_speech),
-        'lines' (expected, heard, similarity, start, end, shot), 'shots'
-        (name, start, end in seconds, or null), 'shots_source', 'discarded' (guarded words with their
+        'lines' (expected, heard, similarity, start, end, shot; start and
+        end kept inside the line's shot, the ASR's own times then in
+        asr_start / asr_end), 'shots' (name, start, end in seconds, or null), 'shots_source', 'discarded' (guarded words with their
         level and reason), 'unmatched' (heard words aligned to no line), 'transcript',
         'model_name', 'rules_applied', 'rules_skipped' and the 'thresholds'
         used.
diff --git a/dw/tasks/script_take.py b/dw/tasks/script_take.py
index 0f94a5bc..be4d5ad8 100644
--- a/dw/tasks/script_take.py
+++ b/dw/tasks/script_take.py
@@ -7,14 +7,16 @@
 - the levelling the transcriber hears the take at (`level_for_transcription`,
   `per_shot_chunks`) - the level checks keep reading the original waveform;
 - the shot placement the probes' rule gives (`shot_spans` via
-  `assess.sample_span`, `overlapping_shot`, `shot_at`);
+  `assess.sample_span`, `overlapping_shot`, `shot_at`, `heard_shot`,
+  `clamp_to_shot`, `shots_entry`);
 - the guard (`guard_words`): a heard word at or below the dead-air floor
   (`GUARD_FLOOR_DBFS`, the probes' `DEAD_AIR_FLOOR_DBFS`), one repeating the
   previous chunk's exact span, or one inside a repetition loop
   (`script_lines.looped_texts_firsts`) is discarded, never raised as a
   finding. `word_level` is the measure the guard and the level checks share
   (`dsp.loudest_window_dbfs` over `GUARD_WINDOW_SECONDS`, the window
-  `shot_dead_air` measures in).
+  `shot_dead_air` measures in), and `audible_runs` the floor-gated blocks
+  of a stretch built from it.
 """
 
 from types import SimpleNamespace
@@ -101,12 +103,85 @@ def shot_at(spans, seconds):
     return None
 
 
+def heard_shot(spans, word):
+    """The shot a heard word's midpoint falls in, None when no shots are known."""
+    if spans is None:
+        return None
+    return shot_at(spans, (word["start"] + word["end"]) / 2)
+
+
+def shots_entry(spans):
+    if spans is None:
+        return None
+    return [
+        {
+            "name": span["name"],
+            "start": round_seconds(span["start"]),
+            "end": round_seconds(span["end"]),
+        }
+        for span in spans
+    ]
+
+
+def clamp_to_shot(entry, span):
+    """Keep a line's `start`/`end` inside its shot (#1115). Whisper drops a
+    passage on a longer input and the word alignment hands that time to a
+    neighbouring word, so the first word of the next shot's line can begin
+    seconds before the seam. The line belongs to `span`, so its timing is
+    reported inside it; the ASR's own times, when they differ, are kept as
+    `asr_start` / `asr_end`."""
+    if span is None or entry["start"] is None:
+        return
+    lo, hi = round_seconds(span["start"]), round_seconds(span["end"])
+    start, end = entry["start"], entry["end"]
+    clamped_start = min(max(start, lo), hi)
+    clamped_end = max(min(end, hi), clamped_start)
+    if clamped_start != start:
+        entry["asr_start"], entry["start"] = start, clamped_start
+    if clamped_end != end:
+        entry["asr_end"], entry["end"] = end, clamped_end
+
+
 def word_level(mono, sample_rate, start, end):
     """The loudest GUARD_WINDOW_SECONDS window's rms over [start, end], in
     dBFS, or None for silence (`dsp.loudest_window_dbfs`)."""
     return dsp.loudest_window_dbfs(mono, sample_rate, start, end, GUARD_WINDOW_SECONDS)
 
 
+def audible_runs(
+    mono, sample_rate, start, end, floor_dbfs, min_seconds, margin_seconds
+):
+    """The audible blocks of the stretch [start, end] (#967, #1115): each run
+    of GUARD_WINDOW_SECONDS windows above `floor_dbfs`, runs a sub-floor gap
+    shorter than `min_seconds` apart joined, and only those lasting
+    `min_seconds` kept, inside [start, end] trimmed by `margin_seconds`
+    (script_check's UNHEARD_* thresholds). Sub-floor time is never counted or placed in a block, and a quiet
+    stretch of min_seconds or more splits the stretch in two. A block
+    edge at the stretch's own (margin-trimmed) edge stays that edge."""
+    inner_start, inner_end = (
+        start + margin_seconds,
+        end - margin_seconds,
+    )
+    runs = []
+    cursor = inner_start
+    while cursor < inner_end:
+        stop = min(cursor + GUARD_WINDOW_SECONDS, inner_end)
+        level = word_level(mono, sample_rate, cursor, stop)
+        if level is not None and level > floor_dbfs:
+            if runs and cursor - runs[-1][1] < min_seconds:
+                runs[-1][1] = stop
+            else:
+                runs.append([cursor, stop])
+        cursor = stop
+    found = []
+    for first, last in runs:
+        first = start if first <= inner_start else first
+        last = end if last >= inner_end else last
+        if last - first >= min_seconds:
+            found.append((first, last))
+    return found
+
+
 def round_seconds(value, places=3):
     return None if value is None else round(float(value), places)
 
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index b0216aee..de8c25ef 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -898,6 +898,83 @@ def test_a_block_crossing_a_shot_seam_is_credited_to_both_shots(self):
         found = rules(answer, "speech_not_transcribed")
         self.assertEqual({f["at"]["shot"] for f in found}, {"A", "B"})
 
+    # #1115, the ep318 cut: A's line dropped by the ASR, B's first word
+    # stretched back across the seam over it
+    EP318_SPANS = [
+        {"name": "A", "start": 0.0, "end": 5.167},
+        {"name": "B", "start": 5.167, "end": 11.042},
+    ]
+    EP318_LINES = [
+        {"text": "Pistachio in the colander.", "shot": "A"},
+        {"text": "The stapler did it.", "shot": "B"},
+    ]
+
+    def ep318(self):
+        chunks = [{"start": 0.88, "end": 9.82, "text": " The"}] + words(
+            "stapler did it.", 9.82, step=0.28, length=0.26
+        )
+        mono = numpy.concatenate(
+            [
+                silent(0.5),
+                voiced(1.0),
+                silent(1.5),
+                voiced(5.0),  # 3.0-8.0: A's speech runs over the seam at 5.167
+                silent(1.5),
+                voiced(1.0),
+                silent(0.542),
+            ]
+        )
+        return shot_run(self.EP318_LINES, chunks, mono=mono, spans=self.EP318_SPANS)
+
+    def test_a_line_timed_across_the_seam_is_kept_inside_its_shot(self):
+        line = self.ep318()["lines"][1]
+        self.assertEqual(line["shot"], "B")
+        self.assertGreaterEqual(line["start"], 5.167)
+        self.assertLessEqual(line["end"], 11.042)
+        # the ASR's own time is not hidden
+        self.assertEqual(line["asr_start"], 0.88)
+
+    def test_a_line_inside_its_shot_carries_no_asr_times(self):
+        chunks = words("alpha bravo", 0.5) + words("charlie delta", 6.0)
+        answer = shot_run(
+            [
+                {"text": "alpha bravo", "shot": "A"},
+                {"text": "charlie delta", "shot": "B"},
+            ],
+            chunks,
+            spans=self.EP318_SPANS,
+        )
+        for line in answer["lines"]:
+            self.assertNotIn("asr_start", line)
+            self.assertNotIn("asr_end", line)
+
+    def test_an_unheard_line_cut_off_by_its_shot_is_clipped(self):
+        # A's untranscribed speech runs to A's end and the tail is voiced
+        answer = self.ep318()
+        (clip,) = rules(answer, "line_clipped_at_end")
+        self.assertEqual(clip["at"]["line"], 0)
+        self.assertEqual(clip["at"]["shot"], "A")
+        self.assertEqual(clip["at"]["seconds"], 5.167)
+        self.assertEqual(
+            [s for s in skipped(answer, "line_clipped_at_end") if "line" in s], []
+        )
+
+    def test_an_unheard_line_with_nothing_to_check_is_listed_skipped(self):
+        chunks = words("charlie delta", 6.0)
+        mono = numpy.concatenate([silent(6.0), voiced(5.042)])
+        answer = shot_run(
+            [
+                {"text": "alpha bravo", "shot": "A"},
+                {"text": "charlie delta", "shot": "B"},
+            ],
+            chunks,
+            mono=mono,
+            spans=self.EP318_SPANS,
+        )
+        self.assertEqual(rules(answer, "line_clipped_at_end"), [])
+        (skip,) = skipped(answer, "line_clipped_at_end")
+        self.assertEqual(skip["line"], 0)
+
     def test_under_a_second_of_audible_sound_in_a_long_gap_is_not(self):
         chunks = words("alpha bravo", 0.0) + words("charlie delta", 5.0)
         mono = numpy.concatenate([voiced(1.5), silent(3.5), voiced(1.0)])

From 93ff0610104c5791153cb6ec995f0ba3a78cfc17 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 01:39:33 -0600
Subject: [PATCH 081/125] fix(timing): #1116 - warn when a cached pipeline's
 decode runs for minutes

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/timing.py | 31 +++++++++++++++++++++++++++
 tests/test_step_timing.py        | 36 ++++++++++++++++++++++++++++++++
 2 files changed, 67 insertions(+)

diff --git a/dw/pipeline_processors/timing.py b/dw/pipeline_processors/timing.py
index 4993c81b..7b72b6b7 100644
--- a/dw/pipeline_processors/timing.py
+++ b/dw/pipeline_processors/timing.py
@@ -43,6 +43,11 @@
 # worth a warning (#924)
 _SLOW_FIRST_PASS_EXTRA_S = 30.0
 
+# A decode this long on a pipeline served from cache is worth a warning (#1116):
+# the same decode ran in ~19 s on a first entry, and 100-255 s on a later entry
+# of a different frame count with nothing in the job saying why
+_SLOW_DECODE_S = 60.0
+
 
 def _synced_clock():
     """The monotonic clock, read after the device has finished its queued work.
@@ -180,6 +185,32 @@ def call_ended(self):
         segment = self._current_segment()
         if segment is not None:
             segment.ended = self._clock()
+            self._warn_on_slow_decode(segment)
+
+    def _warn_on_slow_decode(self, segment):
+        """Say so once per call when a cached pipeline's decode runs for minutes.
+
+        The decode is the tail of the call, after the last denoise pass. On a
+        pipeline already loaded, a decode this long is not weights loading: it
+        is a one-off cost of meeting a new shape (a different frame count gives
+        the video decoder a chunk shape it has not run: kernel selection,
+        allocator re-growth) or a memory-pressure slow path. Without a word the
+        consumer sees only `phase_stall` notices (#1116)."""
+        if self._load_cached is not True:
+            return
+        decode = segment.spans()[3]
+        if decode is None or decode < _SLOW_DECODE_S:
+            return
+        emit_warning(
+            f"Decode took {decode:.0f}s with the pipeline already loaded. That "
+            "is far past a steady decode and is not proportional to frame "
+            "count: a one-off cost of a cached pipeline meeting a shape it has "
+            "not run (a different number of frames), or memory pressure on the "
+            "decode device.",
+            kind="decode_slow",
+            decode_s=round(decode, 1),
+            step=self.step,
+        )
 
     def cache_counted(self, stats):
         """One call's step-cache counts (report_cache_stats, below). A chain's calls sum
diff --git a/tests/test_step_timing.py b/tests/test_step_timing.py
index 3884ca3c..460adcae 100644
--- a/tests/test_step_timing.py
+++ b/tests/test_step_timing.py
@@ -635,3 +635,39 @@ def test_no_warning_for_a_normal_first_pass_or_a_fresh_load(
     clock, timer = new_timer()
     _passes(clock, timer, cached, first, steady)
     assert warnings == []
+
+
+def _decode(clock, timer, cached, decode_s):
+    timer.load_cached(cached)
+    marked(
+        clock,
+        timer,
+        (0.0, "call_started"),
+        (1.0, "denoise_started"),
+        (2.0, "pass_ended"),
+        (2.0 + decode_s, "call_ended"),
+    )
+
+
+def test_a_cached_pipeline_with_a_minutes_long_decode_warns(monkeypatch):
+    """#1116: a 255 s decode on a loaded pipeline is said, not silent."""
+    warnings = []
+    monkeypatch.setattr(
+        timing_module, "emit_warning", lambda message, **data: warnings.append(data)
+    )
+    clock, timer = new_timer()
+    _decode(clock, timer, True, 254.8)
+    assert len(warnings) == 1
+    assert warnings[0]["kind"] == "decode_slow"
+    assert warnings[0]["decode_s"] == 254.8
+
+
+@pytest.mark.parametrize("cached, decode_s", [(True, 19.0), (False, 254.8)])
+def test_a_normal_or_uncached_decode_does_not_warn(monkeypatch, cached, decode_s):
+    warnings = []
+    monkeypatch.setattr(
+        timing_module, "emit_warning", lambda message, **data: warnings.append(data)
+    )
+    clock, timer = new_timer()
+    _decode(clock, timer, cached, decode_s)
+    assert warnings == []

From 671ed7cd99086746d2d42b8b90eb27424e7a109f Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 05:36:34 -0600
Subject: [PATCH 082/125] fix(check-script): #1117 - a take with no shots is
 one implicit shot for unscripted_speech

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md              |  2 +-
 dw/tasks/script_check.py   | 23 +++++++++++++++++++++++
 tests/test_script_check.py | 22 ++++++++++++++++++++--
 3 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index bc501c28..1344851e 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3302,7 +3302,7 @@ Markup stripped from an expected line: `<d>[Language] ...</d>`, `<scenetrans>`,
 | `unscripted_speech` | Shots are known and a line names the shot; words were heard inside it that align to no line (a line spoken twice, an ad-lib) | Number of unmatched words in the shot / 0 | `{line: null, seconds, end, word, shot, repeats_line}` - the first such word; `repeats_line` is true when those words repeat or contain one of the shot's lines |
 | `speech_not_transcribed` | Between two words of one matched line, or between one line's last word and the next line's first (#960; the finding sits on the next line, and a gap holding heard-but-unmatched words is `unscripted_speech`'s), there is a gap of `UNHEARD_MIN_SECONDS` or more, or one of its words lasts `UNHEARD_MIN_SECONDS` + 2 `UNHEARD_MARGIN_SECONDS` or more, and the interior (trimmed by `UNHEARD_MARGIN_SECONDS` each side) holds a window above `UNHEARD_FLOOR_DBFS`: audible speech the ASR left out of its text, which the line's timing absorbed (#923) | The gap's length in seconds / `UNHEARD_FLOOR_DBFS` | `{line, seconds, end, shot}` - `shot` when the line has one |
 
-Every finding is severity `warn`; `at.shot` is set whenever the shot is known. A rule that does not apply to the call is listed in `rules_skipped` with its reason: `speech_in_silent_shot` and `unscripted_speech` are skipped when no shots are known (`line_clipped_at_end` then looks at the file's end only), when the shots carry neither a sample span nor a frame span the take's frame rate can place, or when no line names a shot (no shot is known to be meant silent). A take checked alone, with no shot map (an `asset:` file with no manifest beside it), therefore never raises `unscripted_speech`, however many words are `unmatched`: read `unmatched` there, or pass `shots`. With shots known there is no minimum word count - one unmatched word inside a named shot fires it.
+Every finding is severity `warn`; `at.shot` is set whenever the shot is known. A rule that does not apply to the call is listed in `rules_skipped` with its reason: `speech_in_silent_shot` and `unscripted_speech` are skipped when the shots carry neither a sample span nor a frame span the take's frame rate can place, or when no line names a shot (no shot is known to be meant silent). When no shots are known at all (no `shots`, none carried by the take, no manifest beside the file) and the lines name at most one shot, the whole file is checked as one implicit shot: `unscripted_speech` runs (a line spoken twice, an ad-lib) and `speech_in_silent_shot` is skipped; `line_clipped_at_end` looks at the file's end only. Lines naming two or more shots with none placed skip both. With shots known there is no minimum word count - one unmatched word inside a named shot fires it.
 
 The thresholds are module constants in `dw/tasks/script_check.py` (the guard's `GUARD_FLOOR_DBFS` and `GUARD_WINDOW_SECONDS` in its sibling `dw/tasks/script_take.py`, beside `guard_words`), deliberately not in `RULES` (`dw/assessment_rules.py`): every rule there must fire on a synthetic file that holds no script. The answer echoes them under `thresholds`.
 
diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index 55a29056..1cbe98f2 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -411,6 +411,7 @@ def check(
         unassigned,
         claimed,
         similarity_threshold,
+        duration,
     )
     findings.extend(found)
     found, unchecked = _unheard_line_clips(mono, sample_rate, lines, findings, spans)
@@ -626,6 +627,7 @@ def _shot_rules(
     unassigned,
     claimed,
     similarity_threshold,
+    duration=0.0,
 ):
     """The shot rules (`SHOT_RULES`) when the shots are known and a line
     names one (`_no_shot_reason`), else their skip entries. Returns
@@ -648,6 +650,27 @@ def _shot_rules(
         )
     else:
         rules_skipped.extend({"rule": rule, "reason": no_shot} for rule in SHOT_RULES)
+        named = list(
+            dict.fromkeys(line["shot"] for line in parsed_lines if line["shot"])
+        )
+        if shots_source == "none" and len(named) <= 1 and duration > 0:
+            # A lone take (#1117): no shots known means the file is one shot,
+            # so a repeated or ad-libbed line is still unscripted speech.
+            implicit = [
+                {"name": named[0] if named else None, "start": 0.0, "end": duration}
+            ]
+            rules_skipped.pop()  # unscripted_speech: run on the implicit shot
+            rules_applied.append("unscripted_speech")
+            findings.extend(
+                _unscripted_findings(
+                    implicit,
+                    parsed_lines,
+                    expected,
+                    heard,
+                    unassigned,
+                    similarity_threshold,
+                )
+            )
     return rules_applied, rules_skipped, findings
 
 
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index de8c25ef..1094d3d1 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -418,10 +418,12 @@ def test_exact_lines_have_no_findings(self):
         self.assertEqual(answer["findings"], [])
         self.assertEqual([x["similarity"] for x in answer["lines"]], [1.0] * 3)
         self.assertEqual(answer["unmatched"], [])
-        self.assertEqual(answer["rules_applied"], list(script_check.LINE_RULES))
+        self.assertEqual(
+            answer["rules_applied"], [*script_check.LINE_RULES, "unscripted_speech"]
+        )
         self.assertEqual(
             [s["rule"] for s in answer["rules_skipped"]],
-            ["speech_where_silent", "speech_in_silent_shot", "unscripted_speech"],
+            ["speech_where_silent", "speech_in_silent_shot"],
         )
         self.assertTrue(all(s["reason"] for s in answer["rules_skipped"]))
 
@@ -737,6 +739,22 @@ def test_an_ad_lib_in_a_scripted_shot_is_not_a_repeat(self):
         (found,) = rules(answer, "unscripted_speech")
         self.assertFalse(found["at"]["repeats_line"])
 
+    def test_a_lone_take_without_shots_is_one_implicit_shot(self):
+        # #1117: no shots known, a line spoken twice is still a finding
+        chunks = words("alpha bravo charlie", 0.0) + words("alpha bravo charlie", 1.0)
+        answer = run(["alpha bravo charlie"], chunks)
+        (found,) = rules(answer, "unscripted_speech")
+        self.assertEqual(found["value"], 3)
+        self.assertTrue(found["at"]["repeats_line"])
+        self.assertIn("unscripted_speech", answer["rules_applied"])
+        self.assertEqual(
+            [s["rule"] for s in answer["rules_skipped"] if "shot" in s["rule"]],
+            ["speech_in_silent_shot"],
+        )
+        self.assertEqual(
+            rules(run(["alpha bravo"], words("alpha bravo")), "unscripted_speech"), []
+        )
+
     def test_clean_take_has_none(self):
         answer = shot_run([{"text": "alpha bravo", "shot": "A"}], words("alpha bravo"))
         self.assertEqual(rules(answer, "unscripted_speech"), [])

From f3bbd9e51be51599d3e20cab11d5ec8e1b9cb698 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 05:54:08 -0600
Subject: [PATCH 083/125] fix(check-script): #1118 - a looped bed in a line gap
 is not untranscribed speech

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md              |  3 ++-
 dw/tasks/script_check.py   | 39 ++++++++++++++++++++++++++++++++++++++
 tests/test_script_check.py | 22 ++++++++++++++++++++-
 3 files changed, 62 insertions(+), 2 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 1344851e..bcf3dca2 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3300,7 +3300,7 @@ Markup stripped from an expected line: `<d>[Language] ...</d>`, `<scenetrans>`,
 | `speech_where_silent` | `lines` is `[]` and words were heard above the floor and outside a repetition loop | Number of words heard / 0 | `{line: null, seconds, word}` - the first; `shot` when shots are known |
 | `speech_in_silent_shot` | Shots are known, at least one line names a shot, and words were heard above the floor and outside a repetition loop in a shot no line names. A word is in the shot its midpoint falls in; one a line in another shot matched (a word straddling the cut) is that line's, not counted | Number of words heard in the shot / 0 | `{line: null, seconds, word, shot}` - the shot's first counted word, `seconds` no earlier than the shot's start |
 | `unscripted_speech` | Shots are known and a line names the shot; words were heard inside it that align to no line (a line spoken twice, an ad-lib) | Number of unmatched words in the shot / 0 | `{line: null, seconds, end, word, shot, repeats_line}` - the first such word; `repeats_line` is true when those words repeat or contain one of the shot's lines |
-| `speech_not_transcribed` | Between two words of one matched line, or between one line's last word and the next line's first (#960; the finding sits on the next line, and a gap holding heard-but-unmatched words is `unscripted_speech`'s), there is a gap of `UNHEARD_MIN_SECONDS` or more, or one of its words lasts `UNHEARD_MIN_SECONDS` + 2 `UNHEARD_MARGIN_SECONDS` or more, and the interior (trimmed by `UNHEARD_MARGIN_SECONDS` each side) holds a window above `UNHEARD_FLOOR_DBFS`: audible speech the ASR left out of its text, which the line's timing absorbed (#923) | The gap's length in seconds / `UNHEARD_FLOOR_DBFS` | `{line, seconds, end, shot}` - `shot` when the line has one |
+| `speech_not_transcribed` | Between two words of one matched line, or between one line's last word and the next line's first (#960; the finding sits on the next line, and a gap holding heard-but-unmatched words is `unscripted_speech`'s), there is a gap of `UNHEARD_MIN_SECONDS` or more, or one of its words lasts `UNHEARD_MIN_SECONDS` + 2 `UNHEARD_MARGIN_SECONDS` or more, and the interior (trimmed by `UNHEARD_MARGIN_SECONDS` each side) holds a window above `UNHEARD_FLOOR_DBFS`: audible speech the ASR left out of its text, which the line's timing absorbed (#923). A block that repeats itself sample for sample (`BED_CORRELATION` 0.98 at a lag of 0.3 s or more, 0.5 s compared) is a looped bed from `loop_audio`, not speech, and is no finding (#1118) | The gap's length in seconds / `UNHEARD_FLOOR_DBFS` | `{line, seconds, end, shot}` - `shot` when the line has one |
 
 Every finding is severity `warn`; `at.shot` is set whenever the shot is known. A rule that does not apply to the call is listed in `rules_skipped` with its reason: `speech_in_silent_shot` and `unscripted_speech` are skipped when the shots carry neither a sample span nor a frame span the take's frame rate can place, or when no line names a shot (no shot is known to be meant silent). When no shots are known at all (no `shots`, none carried by the take, no manifest beside the file) and the lines name at most one shot, the whole file is checked as one implicit shot: `unscripted_speech` runs (a line spoken twice, an ad-lib) and `speech_in_silent_shot` is skipped; `line_clipped_at_end` looks at the file's end only. Lines naming two or more shots with none placed skip both. With shots known there is no minimum word count - one unmatched word inside a named shot fires it.
 
@@ -3311,6 +3311,7 @@ The thresholds are module constants in `dw/tasks/script_check.py` (the guard's `
 | `DEFAULT_SIMILARITY` | 0.85 | A line below this similarity is a `line_mismatch` (the `similarity` argument overrides it) |
 | `GUARD_FLOOR_DBFS` | -65 dBFS (= `DEAD_AIR_FLOOR_DBFS`, `shot_dead_air`'s floor) | A heard word whose loudest window is at or below it is discarded as unheard; also the level a clipped tail must exceed |
 | `UNHEARD_MIN_SECONDS` / `UNHEARD_MARGIN_SECONDS` / `UNHEARD_FLOOR_DBFS` | 1.0 s / 0.25 s / -40 dBFS | A gap in a line's words or between two lines (or a stretched word) this long, with a window above the floor in its margin-trimmed interior, is a `speech_not_transcribed` |
+| `BED_CORRELATION` | 0.98 | An audible block matching itself this closely at a lag of 0.3 s or more is a looped bed, not untranscribed speech |
 | `GUARD_WINDOW_SECONDS` | 0.05 s (= `DEAD_AIR_WINDOW`, `shot_dead_air`'s window) | The window a heard word is measured in - its loudest one, so a span overhanging a pause does not average a real word away |
 | `CLIP_TAIL_SECONDS` | 0.25 s | The final stretch of the file a line's last word must end in to be `line_clipped_at_end` |
 | `CLIP_TAIL_BELOW_WORD_DB` | 15 dB | A tail more than this far under the last word's loudest window is not the word still sounding (a bed under a finished line), so not `line_clipped_at_end` |
diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index 1cbe98f2..9c55dfb8 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -44,6 +44,8 @@
 import difflib
 import logging
 import math
+
+import numpy
 from types import SimpleNamespace
 
 from .. import dsp
@@ -110,6 +112,14 @@
 UNHEARD_MIN_SECONDS = 1.0
 UNHEARD_MARGIN_SECONDS = 0.25
 UNHEARD_FLOOR_DBFS = -40.0
+# A block whose samples repeat themselves - one stretch of it matching the
+# same stretch BED_MIN_PERIOD_SECONDS or more later at BED_CORRELATION or
+# better, over at least BED_MIN_OVERLAP_SECONDS - is a looped bed (loop_audio
+# of a room tone), not speech: the same sound does not recur to the sample
+# in a voice (#1118)
+BED_MIN_PERIOD_SECONDS = 0.3
+BED_MIN_OVERLAP_SECONDS = 0.5
+BED_CORRELATION = 0.98
 # REPEAT_RUN_MIN and REPEAT_MAX_PERIOD, the repetition-loop guard, live in
 # dw/script_lines.py beside the detector, which transcribe_audio shares
 
@@ -122,6 +132,7 @@
     "unheard_min_seconds": UNHEARD_MIN_SECONDS,
     "unheard_margin_seconds": UNHEARD_MARGIN_SECONDS,
     "unheard_floor_dbfs": UNHEARD_FLOOR_DBFS,
+    "bed_correlation": BED_CORRELATION,
     "repeat_run_min": REPEAT_RUN_MIN,
     "repeat_max_period": REPEAT_MAX_PERIOD,
 }
@@ -843,11 +854,39 @@ def _audible_findings(
     return [f for f in found if f is not None]
 
 
+def is_looped_bed(mono, sample_rate, start, end):
+    """True when [start, end] repeats itself sample for sample at some lag of
+    BED_MIN_PERIOD_SECONDS or more, leaving BED_MIN_OVERLAP_SECONDS to compare
+    (#1118): a looped room-tone or score bed, which a voice never does."""
+    first, last = int(round(start * sample_rate)), int(round(end * sample_rate))
+    block = numpy.asarray(mono[max(0, first) : last], dtype=numpy.float64)
+    block = block - block.mean() if block.size else block
+    shortest = int(BED_MIN_PERIOD_SECONDS * sample_rate)
+    overlap = int(BED_MIN_OVERLAP_SECONDS * sample_rate)
+    longest = block.size - overlap
+    if longest < shortest:
+        return False
+    size = 1 << int(block.size * 2 - 1).bit_length()
+    spectrum = numpy.fft.rfft(block, size)
+    auto = numpy.fft.irfft(spectrum * numpy.conj(spectrum), size)
+    # Prefix energies give each lag's two overlapping stretches' energy
+    energy = numpy.concatenate([[0.0], numpy.cumsum(block * block)])
+    for lag in range(shortest, longest + 1):
+        head = energy[block.size - lag]
+        tail = energy[block.size] - energy[lag]
+        denominator = math.sqrt(head * tail)
+        if denominator > 0 and auto[lag] / denominator >= BED_CORRELATION:
+            return True
+    return False
+
+
 def _untranscribed(mono, sample_rate, index, start, end, shot):
     lo, hi = start + UNHEARD_MARGIN_SECONDS, end - UNHEARD_MARGIN_SECONDS
     level = word_level(mono, sample_rate, lo, hi)
     if level is None or level <= UNHEARD_FLOOR_DBFS:
         return None
+    if is_looped_bed(mono, sample_rate, start, end):
+        return None
     at = _at(index, seconds=start, shot=shot)
     at["end"] = round_seconds(end)
     return finding(SPEECH_NOT_TRANSCRIBED, round_seconds(end - start, 2), at)
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index 1094d3d1..388c3b51 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -42,7 +42,20 @@
 
 def voiced(seconds, amplitude=0.1):
     t = numpy.arange(int(round(seconds * RATE)), dtype=numpy.float32) / RATE
-    return (amplitude * numpy.sin(2 * numpy.pi * 220 * t)).astype(numpy.float32)
+    # Noise keeps it from repeating to the sample, as a voice never does
+    noise = numpy.random.default_rng(7).standard_normal(t.size) * 0.3
+    return (amplitude * (numpy.sin(2 * numpy.pi * 220 * t) + noise)).astype(
+        numpy.float32
+    )
+
+
+def looped_bed(seconds, period=0.75, amplitude=0.1):
+    """A short noise burst repeated sample for sample: loop_audio of a room tone."""
+    cycle = numpy.random.default_rng(3).standard_normal(int(period * RATE))
+    reps = int(numpy.ceil(seconds / period))
+    return (amplitude * numpy.tile(cycle, reps)[: int(seconds * RATE)]).astype(
+        numpy.float32
+    )
 
 
 def silent(seconds):
@@ -784,6 +797,13 @@ def test_a_stretched_word_over_sound_is_a_finding(self):
         (found,) = rules(answer, "speech_not_transcribed")
         self.assertEqual(found["at"]["seconds"], 0.5)
 
+    def test_a_looped_bed_in_the_gap_is_not(self):
+        # loop_audio of a room tone under the cut: same samples every period (#1118)
+        chunks = words("alpha bravo", 0.0) + words("charlie delta", 4.0)
+        mono = numpy.concatenate([voiced(0.9), looped_bed(3.1), voiced(1.0)])
+        answer = shot_run(self.LINES, chunks, mono=mono)
+        self.assertEqual(rules(answer, "speech_not_transcribed"), [])
+
     def test_a_quiet_gap_is_not(self):
         chunks = words("alpha bravo", 0.0) + words("charlie delta", 4.0)
         mono = numpy.concatenate([voiced(0.9), silent(3.1), voiced(1.0)])

From 955cd88fa04c19e2bcce2b3dae1d0edee9a3f752 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 05:59:10 -0600
Subject: [PATCH 084/125] refactor(dsp): #1118 - looped-bed self-correlation
 measured in dsp via scipy, vectorized

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md     |  2 +-
 dw/dsp.py                | 27 +++++++++++++++++++++++++++
 dw/tasks/script_check.py | 34 ++++++++++------------------------
 3 files changed, 38 insertions(+), 25 deletions(-)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 0b3a6964..fe14df8a 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -141,7 +141,7 @@ one to open.
 | Output comparison | `dw/media_compare.py`: `compare`, `psnr`, `ssim`, `mean_abs_diff`, `check_request`, `crop_box` | Metrics always compare the same pixels: one shared crop is the measured region, and per-output crops are display only, leaving metrics on the full frame. An output whose size differs from the baseline's, or a moment past its end, gets null metrics with a reason; nothing is resized to force a number. SSIM is on Rec. 601 luma (SSIM's convention, not `image_ops.luma`). It runs in the server process and decodes through `dw/media.py` and `open_bounded`. | `tests/test_compare_route.py::test_a_shared_crop_is_the_region_measured`, `tests/test_compare_route.py::test_per_output_crops_are_display_only`, `tests/test_compare_route.py::test_a_size_mismatch_gets_no_numbers_and_says_why`, `tests/test_compare_route.py::test_a_moment_past_the_shorter_clip_is_a_blank_cell` |
 | Signal processing | `dw/dsp.py` | It measures and transforms waveforms, decides nothing, and imports nothing from `dw`. | `tests/test_media_layering.py::test_dsp_imports_nothing_from_dw` |
 | Assessment probes | `dw/tasks/assess.py`, `dw/assessment_rules.py` | Exactly three registered commands are assessment probes. Each measures a finished file, and every rule names a real probe field. | `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_assessment_is_exactly_the_three_probes`, `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_every_rule_names_a_registered_json_command` |
-| Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` (`script_take.word_level` wraps it; the guard, the transcription levelling, the floor-gated `audible_runs` and the shot placement (with `clamp_to_shot`, a line's timing kept inside its shot) are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
+| Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` and the looped-bed self-correlation `dsp.repeat_correlation` (`script_check.is_looped_bed` only decides on it) (`script_take.word_level` wraps it; the guard, the transcription levelling, the floor-gated `audible_runs` and the shot placement (with `clamp_to_shot`, a line's timing kept inside its shot) are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
 | Audio sync against a source slice | `dw/tasks/measure_sync.py`: `measure_sync`; `dw/dsp.py`: `envelope_lag` | `measure_sync` cross-correlates the onset envelopes of a shot's audio and its source slice and answers the lag and a 0-1 confidence. A positive lag means the audio is LATE (its events fall after the reference's), negative early; `lag_seconds` is None for a silent or flat track. It builds its findings (`sync_unmeasurable`, `sync_low_confidence`, `audio_out_of_sync`) with `assessment_rules.finding()` over module-local rule dicts and adds nothing to `RULES`; it reads the silence floor from `beats.SILENT_DBFS`. `envelope_lag` imports nothing from `dw`. | `tests/test_measure_sync.py::TestLag::test_late_audio_is_a_positive_lag`, `tests/test_measure_sync.py::TestLag::test_early_audio_is_a_negative_lag`, `tests/test_measure_sync.py::TestUnmeasurable::test_a_silent_reference_has_no_lag` |
 | Sung phrases from voiced energy | `dw/tasks/phrases.py`: `analyze_phrases`, `voiced_power`, `voiced_runs`; `dw/task_problems.py`: `phrases_problems`, `phrases_errors` | `analyze_phrases` times a song's sung phrases with no model: a stereo file's centre-weighted band power (max(0, P_mid - P_side), 250-3500 Hz, 20 ms frames) or, for mono, `centre: false` or identical channels, the downmix's band power (`method` `band`). The voiced floor is `voice_attribution.voiced_floor_dbfs`, the rule `attribute_voices` uses, unless `floor_db` is given. It answers a dict - `{phrases, duration_seconds, method, warnings}` - so a step saves one JSON artifact. Its ranges are the registration's domains; `phrases_problems` (a real boolean `centre`) runs at validate and at run time. | `tests/test_analyze_phrases.py::TestCentre::test_centred_bursts_under_hard_panned_noise_are_found`, `tests/test_analyze_phrases.py::TestCentre::test_bursts_panned_hard_to_one_side_are_not_centre`, `tests/test_analyze_phrases.py::TestRefusals::test_validate_refuses_a_missing_audio_and_a_negative_gap` |
 
diff --git a/dw/dsp.py b/dw/dsp.py
index b7e77f7d..eeb90ae0 100644
--- a/dw/dsp.py
+++ b/dw/dsp.py
@@ -416,6 +416,33 @@ def harmonicity(waveform, sample_rate):
     return max(scores) if scores else 0.0
 
 
+def repeat_correlation(mono, sample_rate, min_lag_seconds, min_overlap_seconds):
+    """The best overlap-normalized self-correlation of a block with itself at
+    any lag of min_lag_seconds or more that leaves min_overlap_seconds to
+    compare, 0.0 when the block is too short or silent. 1.0 means the block
+    repeats sample for sample, as a looped bed does (#1118)."""
+    block = numpy.asarray(mono, dtype=numpy.float64)
+    if block.size == 0:
+        return 0.0
+    block = block - block.mean()
+    shortest = int(min_lag_seconds * sample_rate)
+    longest = block.size - int(min_overlap_seconds * sample_rate)
+    if longest < shortest or shortest < 1:
+        return 0.0
+    full = scipy.signal.correlate(block, block, mode="full", method="fft")
+    auto = full[block.size - 1 :]
+    # Prefix energies give each lag's two overlapping stretches' energy
+    energy = numpy.concatenate([[0.0], numpy.cumsum(block * block)])
+    lags = numpy.arange(shortest, longest + 1)
+    denominator = numpy.sqrt(
+        energy[block.size - lags] * (energy[block.size] - energy[lags])
+    )
+    valid = denominator > 0
+    if not valid.any():
+        return 0.0
+    return float(numpy.max(auto[lags][valid] / denominator[valid]))
+
+
 def spectral_balance(waveform, sample_rate):
     """A rough low/mid/high energy reading in dBFS, from one FFT of the
     channel-averaged track - not a spectrogram, just enough to say whether
diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index 9c55dfb8..b578a41a 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -44,8 +44,6 @@
 import difflib
 import logging
 import math
-
-import numpy
 from types import SimpleNamespace
 
 from .. import dsp
@@ -855,29 +853,17 @@ def _audible_findings(
 
 
 def is_looped_bed(mono, sample_rate, start, end):
-    """True when [start, end] repeats itself sample for sample at some lag of
-    BED_MIN_PERIOD_SECONDS or more, leaving BED_MIN_OVERLAP_SECONDS to compare
-    (#1118): a looped room-tone or score bed, which a voice never does."""
+    """True when [start, end] repeats itself sample for sample (#1118): a
+    looped room-tone or score bed, which a voice never does. The measurement
+    is `dsp.repeat_correlation`; this is the decision."""
     first, last = int(round(start * sample_rate)), int(round(end * sample_rate))
-    block = numpy.asarray(mono[max(0, first) : last], dtype=numpy.float64)
-    block = block - block.mean() if block.size else block
-    shortest = int(BED_MIN_PERIOD_SECONDS * sample_rate)
-    overlap = int(BED_MIN_OVERLAP_SECONDS * sample_rate)
-    longest = block.size - overlap
-    if longest < shortest:
-        return False
-    size = 1 << int(block.size * 2 - 1).bit_length()
-    spectrum = numpy.fft.rfft(block, size)
-    auto = numpy.fft.irfft(spectrum * numpy.conj(spectrum), size)
-    # Prefix energies give each lag's two overlapping stretches' energy
-    energy = numpy.concatenate([[0.0], numpy.cumsum(block * block)])
-    for lag in range(shortest, longest + 1):
-        head = energy[block.size - lag]
-        tail = energy[block.size] - energy[lag]
-        denominator = math.sqrt(head * tail)
-        if denominator > 0 and auto[lag] / denominator >= BED_CORRELATION:
-            return True
-    return False
+    block = mono[max(0, first) : last]
+    return (
+        dsp.repeat_correlation(
+            block, sample_rate, BED_MIN_PERIOD_SECONDS, BED_MIN_OVERLAP_SECONDS
+        )
+        >= BED_CORRELATION
+    )
 
 
 def _untranscribed(mono, sample_rate, index, start, end, shot):

From 96bfd47cd6256144e6d1c1937f2479b5c82e6059 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 06:24:32 -0600
Subject: [PATCH 085/125] fix(timing): #1119 - first_pass_slow no longer claims
 a shape cause it cannot see

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/timing.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/dw/pipeline_processors/timing.py b/dw/pipeline_processors/timing.py
index 7b72b6b7..af437a8f 100644
--- a/dw/pipeline_processors/timing.py
+++ b/dw/pipeline_processors/timing.py
@@ -152,6 +152,9 @@ def pass_ended(self):
     def _warn_on_slow_first_pass(self, segment):
         """Say so once when a cached pipeline's first pass dwarfs the steady one.
 
+        The cause is unknown (#1119: it fired on an equal-shape second entry, and
+        #924's rerun did not reproduce it), so the message states none.
+
         The pipeline is loaded, so the minutes are not a load. A later entry
         that runs the cached pipeline at a larger shape (more frames) pays a
         one-off warm-up on its first pass - re-allocation, offload buffers,
@@ -172,9 +175,10 @@ def _warn_on_slow_first_pass(self, segment):
         emit_warning(
             f"First denoise pass took {first:.0f}s against {steady:.0f}s for "
             "the passes after it, with the pipeline already loaded: a one-off "
-            "warm-up (typically a cached pipeline meeting a larger shape than "
-            "it last ran, such as more frames). Later passes run at the "
-            "steady rate.",
+            "warm-up whose cause is not identified. It has followed a larger "
+            "shape (more frames) and also an entry of the same shape, so "
+            "reordering entries by size is not a known remedy. Later passes "
+            "run at the steady rate.",
             kind="first_pass_slow",
             first_pass_s=round(first, 1),
             pass_s=round(steady, 1),

From c4867c2f99e2f0820c6475fffe0e145a0aff5a1d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:05:35 -0600
Subject: [PATCH 086/125] feat(tasks): #1120 - vendored, ported Audio8-TTS
 model module

dw/tasks/audio8_tts_model.py: the Audio8-TTS (ArkTTS) config, dual-AR
model, codec and processor from Edge0/Audio8-TTS-Realistic-0.6b @
1e857568, merged into one file and ported to transformers >= 5.19.
Loads only from caller-given local paths (safetensors, codec.pth with
weights_only=True, tokenizer.json); no torchaudio or soundfile; legacy
weight_norm folded at load; eager snake. Unreferenced until stage C.

Upstream read before porting: no subprocess or os.system, no eval/exec
(only nn.Module.eval()), network only via cached_file and
AutoTokenizer.from_pretrained (with trust_remote_code passed through),
np.load of reference codes, shutil.copy2 in save_pretrained, and
torch.jit.script on local snake code - none carried.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ATTRIBUTIONS.md           |    1 +
 dw/tasks/audio8_tts_model.py   | 2033 ++++++++++++++++++++++++++++++++
 tests/test_audio8_tts_model.py |  362 ++++++
 3 files changed, 2396 insertions(+)
 create mode 100644 dw/tasks/audio8_tts_model.py
 create mode 100644 tests/test_audio8_tts_model.py

diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
index e42a5441..2559fdcd 100644
--- a/docs/ATTRIBUTIONS.md
+++ b/docs/ATTRIBUTIONS.md
@@ -16,6 +16,7 @@ Each file keeps its upstream licence notice in its header.
 |---|---|---|
 | [dw/tasks/rife_model.py](../dw/tasks/rife_model.py) | The RIFE interpolation network from [hzwer/Practical-RIFE](https://github.com/hzwer/Practical-RIFE) | MIT, Copyright (c) Megvii Inc. |
 | [dw/tasks/h3_latent_upscaler_model.py](../dw/tasks/h3_latent_upscaler_model.py) | The MiniMax H3 3D-convolution latent upscaler from [LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler](https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler) | MIT, Copyright (c) LBH-123-AI |
+| [dw/tasks/audio8_tts_model.py](../dw/tasks/audio8_tts_model.py) | The Audio8-TTS (ArkTTS) dual-AR speech model, codec and processor from [Edge0/Audio8-TTS-Realistic-0.6b](https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b/tree/1e857568bfd4f02931aca3988ee773a44d2d26d3), ported (upstream NOTICE kept in the file header) | Apache-2.0 |
 | [dw/community_pipelines/pipeline_flux_rf_inversion.py](../dw/community_pipelines/pipeline_flux_rf_inversion.py) | The diffusers community RF-Inversion pipeline, after [RF Inversion](https://rf-inversion.github.io/) by Litu Rout, Yujia Chen, Nataniel Ruiz, Constantine Caramanis, Sanjay Shakkottai and Wen-Sheng Chu | Apache-2.0, Copyright 2024 Black Forest Labs and The HuggingFace Team |
 | [dw/prompt_weighting.py](../dw/prompt_weighting.py) | Based on [sd_embed](https://github.com/xhinker/sd_embed) by Andrew Zhu | Apache-2.0 |
 
diff --git a/dw/tasks/audio8_tts_model.py b/dw/tasks/audio8_tts_model.py
new file mode 100644
index 00000000..e28daff5
--- /dev/null
+++ b/dw/tasks/audio8_tts_model.py
@@ -0,0 +1,2033 @@
+"""
+Audio8-TTS (ArkTTS) - the dual-AR text-to-speech model, its audio codec and
+its prompt processor, v1.
+
+Vendored from https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b at
+revision 1e857568bfd4f02931aca3988ee773a44d2d26d3 (configuration_arktts.py,
+modeling_arktts.py, modeling_arktts_codec.py, processing_arktts.py, merged
+into this one file). The weights are that repository's model.safetensors and
+codec.pth at the same revision (REPO_ID / REVISION below).
+
+Carried over as written: the slow and fast transformers, the hand-written
+generate() loop with its own KV cache, top-k/top-p and RAS sampling and the
+fast-AR codebook loop, the codec's encoder, residual quantizers and decoder,
+and the processor's prompt layout.
+
+Changed in the port, so nothing here touches the Hub, a network, torchaudio
+or soundfile, and nothing depends on transformers' model-loading machinery:
+- The config, model and processor are plain classes, not PretrainedConfig,
+  PreTrainedModel or ProcessorMixin subclasses. load_model() builds the model
+  from the local config.json, model.safetensors, generation_config.json and
+  codec.pth paths its caller gives; load_tokenizer() reads a local
+  tokenizer.json. Upstream's Hub loading and saving entry points (and the
+  saver's copy of the codec) are not carried. The transformers logits/stopping
+  list classes become plain lists of callables, ModelOutput/BatchFeature plain
+  dataclasses and dicts.
+- codec.pth loads with torch.load(weights_only=True); the deprecated legacy
+  weight_norm on the quantizer projections is folded into plain weights at
+  load, and the TorchScript snake activation is plain eager code.
+- Reference audio given as a path is read with audio_utils.load_audio and
+  resampled with dw.dsp.resample_waveform. The processor's precomputed
+  reference-codes input (np.load of a file) is not carried.
+- The codec's layer widths are config fields whose defaults are the released
+  checkpoint's, so a test can build a tiny one; codec.pth loads strictly, so
+  any other size fails to load.
+
+Apache License 2.0 - upstream NOTICE:
+
+    audio8_tts
+
+    The model architecture is inspired by the DualAR design used in Fish
+    Audio S2 Pro.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this file except in compliance with the License. You may obtain a copy of
+the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+License for the specific language governing permissions and limitations under
+the License.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torch import Tensor
+from torch.nn.attention import SDPBackend, sdpa_kernel
+from torch.nn.utils.parametrizations import weight_norm
+
+REPO_ID = "Edge0/Audio8-TTS-Realistic-0.6b"
+REVISION = "1e857568bfd4f02931aca3988ee773a44d2d26d3"
+CONFIG_FILE = "config.json"
+GENERATION_CONFIG_FILE = "generation_config.json"
+WEIGHTS_FILE = "model.safetensors"
+TOKENIZER_FILE = "tokenizer.json"
+CODEC_FILE = "codec.pth"
+MODEL_FILES = (
+    CONFIG_FILE,
+    GENERATION_CONFIG_FILE,
+    WEIGHTS_FILE,
+    TOKENIZER_FILE,
+    CODEC_FILE,
+)
+
+
+# --- configuration (upstream configuration_arktts.py) -----------------------
+
+
+class ArkttsConfig:
+    model_type = "arktts"
+
+    def __init__(
+        self,
+        vocab_size: int = 155776,
+        dim: int = 896,
+        n_layer: int = 24,
+        n_head: int = 14,
+        n_local_heads: int = 2,
+        head_dim: int = 64,
+        intermediate_size: int = 4864,
+        max_seq_len: int = 2048,
+        rope_base: float = 1_000_000,
+        norm_eps: float = 1e-6,
+        dropout: float = 0.0,
+        attention_qkv_bias: bool = True,
+        attention_qk_norm: bool = False,
+        attention_o_bias: bool = False,
+        tie_word_embeddings: bool = True,
+        codebook_size: int = 4096,
+        num_codebooks: int = 10,
+        semantic_begin_id: int = 151678,
+        semantic_end_id: int = 155773,
+        n_fast_layer: int = 4,
+        fast_dim: int = 896,
+        fast_n_head: int = 14,
+        fast_n_local_heads: int = 2,
+        fast_head_dim: int = 64,
+        fast_intermediate_size: int = 4864,
+        fast_attention_qkv_bias: bool = False,
+        fast_attention_qk_norm: bool = False,
+        fast_attention_o_bias: bool = False,
+        norm_fastlayer_input: bool = True,
+        initializer_range: float = 0.02,
+        use_gradient_checkpointing: bool = False,
+        codec_filename: str = CODEC_FILE,
+        codec_sample_rate: int = 44100,
+        codec_frame_size: int = 2048,
+        codec_post_n_layer: int = 8,
+        codec_post_n_head: int = 16,
+        codec_post_n_local_heads: int = 8,
+        codec_post_intermediate_size: int = 1216,
+        codec_encoder_dim: int = 64,
+        codec_encoder_transformer_layers: int = 4,
+        codec_latent_dim: int = 1024,
+        codec_decoder_dim: int = 1536,
+        codec_pre_n_layer: int = 8,
+        codec_pre_n_head: int = 16,
+        codec_pre_intermediate_size: int = 3072,
+        codec_residual_codebook_size: int = 1024,
+        codec_codebook_dim: int = 8,
+        ras_window_size: int = 10,
+        ras_temperature: float = 1.0,
+        ras_top_p: float = 0.9,
+        eos_token_id: int = 151645,
+        pad_token_id: int = 151643,
+        **kwargs,
+    ):
+        # config.json also carries transformers bookkeeping (architectures,
+        # auto_map, dtype, the hidden_size-style aliases set below) - none of
+        # it configures the network
+        del kwargs
+        self.vocab_size = int(vocab_size)
+        self.dim = int(dim)
+        self.hidden_size = self.dim
+        self.n_layer = int(n_layer)
+        self.num_hidden_layers = self.n_layer
+        self.n_head = int(n_head)
+        self.num_attention_heads = self.n_head
+        self.n_local_heads = int(n_local_heads)
+        self.num_key_value_heads = self.n_local_heads
+        self.head_dim = int(head_dim)
+        self.intermediate_size = int(intermediate_size)
+        self.max_seq_len = int(max_seq_len)
+        self.max_position_embeddings = self.max_seq_len
+        self.rope_base = float(rope_base)
+        self.rope_theta = self.rope_base
+        self.norm_eps = float(norm_eps)
+        self.rms_norm_eps = self.norm_eps
+        self.dropout = float(dropout)
+        self.attention_qkv_bias = bool(attention_qkv_bias)
+        self.attention_qk_norm = bool(attention_qk_norm)
+        self.attention_o_bias = bool(attention_o_bias)
+        self.tie_word_embeddings = bool(tie_word_embeddings)
+        self.codebook_size = int(codebook_size)
+        self.num_codebooks = int(num_codebooks)
+        self.semantic_begin_id = int(semantic_begin_id)
+        self.semantic_end_id = int(semantic_end_id)
+        self.n_fast_layer = int(n_fast_layer)
+        self.fast_dim = int(fast_dim)
+        self.fast_n_head = int(fast_n_head)
+        self.fast_n_local_heads = int(fast_n_local_heads)
+        self.fast_head_dim = int(fast_head_dim)
+        self.fast_intermediate_size = int(fast_intermediate_size)
+        self.fast_attention_qkv_bias = bool(fast_attention_qkv_bias)
+        self.fast_attention_qk_norm = bool(fast_attention_qk_norm)
+        self.fast_attention_o_bias = bool(fast_attention_o_bias)
+        self.norm_fastlayer_input = bool(norm_fastlayer_input)
+        self.initializer_range = float(initializer_range)
+        self.use_gradient_checkpointing = bool(use_gradient_checkpointing)
+        self.codec_filename = str(codec_filename)
+        self.codec_sample_rate = int(codec_sample_rate)
+        self.codec_frame_size = int(codec_frame_size)
+        self.codec_post_n_layer = int(codec_post_n_layer)
+        self.codec_post_n_head = int(codec_post_n_head)
+        self.codec_post_n_local_heads = int(codec_post_n_local_heads)
+        self.codec_post_intermediate_size = int(codec_post_intermediate_size)
+        self.codec_encoder_dim = int(codec_encoder_dim)
+        self.codec_encoder_transformer_layers = int(codec_encoder_transformer_layers)
+        self.codec_latent_dim = int(codec_latent_dim)
+        self.codec_decoder_dim = int(codec_decoder_dim)
+        self.codec_pre_n_layer = int(codec_pre_n_layer)
+        self.codec_pre_n_head = int(codec_pre_n_head)
+        self.codec_pre_intermediate_size = int(codec_pre_intermediate_size)
+        self.codec_residual_codebook_size = int(codec_residual_codebook_size)
+        self.codec_codebook_dim = int(codec_codebook_dim)
+        self.ras_window_size = int(ras_window_size)
+        self.ras_temperature = float(ras_temperature)
+        self.ras_top_p = float(ras_top_p)
+        self.eos_token_id = int(eos_token_id)
+        self.pad_token_id = int(pad_token_id)
+
+    @classmethod
+    def from_json_file(cls, path) -> "ArkttsConfig":
+        with open(path, "r", encoding="utf-8") as handle:
+            return cls(**json.load(handle))
+
+
+# --- model (upstream modeling_arktts.py) ------------------------------------
+
+
+@dataclass
+class ArkttsModelOutput:
+    logits: Optional[Tensor] = None
+    hidden_states: Optional[Tensor] = None
+    codebook_logits: Optional[Tensor] = None
+
+
+@dataclass
+class ArkttsGenerateOutput:
+    codes: Optional[Tensor] = None
+    code_lengths: Optional[Tensor] = None
+    finished: Optional[Tensor] = None
+
+
+class ArkttsSemanticLogitsProcessor:
+    def __init__(self, semantic_begin_id: int, semantic_end_id: int, eos_token_id: int):
+        self.semantic_begin_id = int(semantic_begin_id)
+        self.semantic_end_id = int(semantic_end_id)
+        self.eos_token_id = int(eos_token_id)
+
+    def __call__(self, input_ids: Tensor, scores: Tensor) -> Tensor:
+        filtered = torch.full_like(scores, float("-inf"))
+        filtered[:, self.semantic_begin_id : self.semantic_end_id + 1] = scores[
+            :, self.semantic_begin_id : self.semantic_end_id + 1
+        ]
+        filtered[:, self.eos_token_id] = scores[:, self.eos_token_id]
+        return filtered
+
+
+class ArkttsLegacyTopKTopPLogitsProcessor:
+    """Matches the candidate filtering order used by the original inference code."""
+
+    def __init__(self, top_k: int, top_p: float):
+        if top_k <= 0:
+            raise ValueError("top_k must be positive")
+        if not 0.0 < top_p <= 1.0:
+            raise ValueError("top_p must be in (0, 1]")
+        self.top_k = int(top_k)
+        self.top_p = float(top_p)
+
+    def __call__(self, input_ids: Tensor, scores: Tensor) -> Tensor:
+        sorted_scores, sorted_indices = torch.sort(scores, descending=True, dim=-1)
+        cumulative = torch.cumsum(torch.softmax(sorted_scores, dim=-1), dim=-1)
+        positions = torch.arange(sorted_scores.shape[-1], device=scores.device)
+        threshold = torch.tensor(
+            self.top_p, dtype=cumulative.dtype, device=cumulative.device
+        )
+        remove_sorted = (cumulative > threshold) | (positions >= self.top_k)
+        remove_sorted[..., 0] = False
+        remove = torch.zeros_like(remove_sorted).scatter(
+            1, sorted_indices, remove_sorted
+        )
+        return scores.masked_fill(remove, float("-inf"))
+
+
+def _apply_processors(processors, input_ids: Tensor, scores: Tensor) -> Tensor:
+    for processor in processors:
+        scores = processor(input_ids, scores)
+    return scores
+
+
+class ArkttsKVCache(nn.Module):
+    def __init__(
+        self,
+        batch_size: int,
+        max_length: int,
+        heads: int,
+        head_dim: int,
+        dtype,
+        return_full: bool = False,
+    ):
+        super().__init__()
+        shape = (batch_size, heads, max_length, head_dim)
+        self.register_buffer("keys", torch.zeros(shape, dtype=dtype), persistent=False)
+        self.register_buffer(
+            "values", torch.zeros(shape, dtype=dtype), persistent=False
+        )
+        self.return_full = bool(return_full)
+
+    def update(self, cache_position: Tensor, keys: Tensor, values: Tensor):
+        self.keys[:, :, cache_position] = keys
+        self.values[:, :, cache_position] = values
+        end = (
+            self.keys.shape[2]
+            if self.return_full
+            else int(cache_position[-1].item()) + 1
+        )
+        return self.keys[:, :, :end], self.values[:, :, :end]
+
+
+class ArkttsRMSNorm(nn.Module):
+    def __init__(self, dim: int, eps: float):
+        super().__init__()
+        self.eps = float(eps)
+        self.weight = nn.Parameter(torch.ones(dim))
+
+    def forward(self, x: Tensor) -> Tensor:
+        normalized = x.float() * torch.rsqrt(
+            x.float().pow(2).mean(-1, keepdim=True) + self.eps
+        )
+        return normalized.to(x.dtype) * self.weight
+
+
+def _precompute_rope(length: int, head_dim: int, base: float, device=None) -> Tensor:
+    frequencies = 1.0 / (
+        base
+        ** (
+            torch.arange(0, head_dim, 2, device=device).float()[: head_dim // 2]
+            / head_dim
+        )
+    )
+    phases = torch.outer(torch.arange(length, device=device), frequencies)
+    values = torch.polar(torch.ones_like(phases), phases)
+    return torch.stack((values.real, values.imag), dim=-1).to(torch.bfloat16)
+
+
+def _apply_rope(x: Tensor, rope: Tensor) -> Tensor:
+    shaped = x.float().reshape(*x.shape[:-1], -1, 2)
+    if rope.ndim == 3:
+        rope = rope[None, :, None]
+    elif rope.ndim == 4:
+        rope = rope[:, :, None]
+    else:
+        raise ValueError(f"Unexpected RoPE shape: {tuple(rope.shape)}")
+    output = torch.stack(
+        (
+            shaped[..., 0] * rope[..., 0] - shaped[..., 1] * rope[..., 1],
+            shaped[..., 1] * rope[..., 0] + shaped[..., 0] * rope[..., 1],
+        ),
+        dim=-1,
+    )
+    return output.flatten(3).to(x.dtype)
+
+
+class ArkttsAttention(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        n_head: int,
+        n_local_heads: int,
+        head_dim: int,
+        qkv_bias: bool,
+        output_bias: bool,
+        qk_norm: bool,
+        norm_eps: float,
+        dropout: float,
+        use_sdpa: bool,
+    ):
+        super().__init__()
+        total = (n_head + 2 * n_local_heads) * head_dim
+        self.wqkv = nn.Linear(dim, total, bias=qkv_bias)
+        self.wo = nn.Linear(n_head * head_dim, dim, bias=output_bias)
+        self.n_head = int(n_head)
+        self.n_local_heads = int(n_local_heads)
+        self.head_dim = int(head_dim)
+        self.dropout = float(dropout)
+        self.use_sdpa = bool(use_sdpa)
+        self.qk_norm = bool(qk_norm)
+        if self.qk_norm:
+            self.q_norm = ArkttsRMSNorm(head_dim, norm_eps)
+            self.k_norm = ArkttsRMSNorm(head_dim, norm_eps)
+        self.kv_cache: Optional[ArkttsKVCache] = None
+
+    def forward(
+        self,
+        x: Tensor,
+        rope: Tensor,
+        attention_mask: Optional[Tensor],
+        cache_position: Optional[Tensor] = None,
+    ) -> Tensor:
+        batch, length, _ = x.shape
+        query_size = self.n_head * self.head_dim
+        kv_size = self.n_local_heads * self.head_dim
+        query, key, value = self.wqkv(x).split((query_size, kv_size, kv_size), dim=-1)
+        query = query.view(batch, length, self.n_head, self.head_dim)
+        key = key.view(batch, length, self.n_local_heads, self.head_dim)
+        value = value.view(batch, length, self.n_local_heads, self.head_dim)
+        if self.qk_norm:
+            query = self.q_norm(query)
+            key = self.k_norm(key)
+        query = _apply_rope(query, rope).transpose(1, 2)
+        key = _apply_rope(key, rope).transpose(1, 2)
+        value = value.transpose(1, 2)
+        if self.kv_cache is not None:
+            if cache_position is None:
+                raise ValueError("cache_position is required when KV cache is enabled")
+            key, value = self.kv_cache.update(cache_position, key, value)
+        repeats = self.n_head // self.n_local_heads
+        key = key.repeat_interleave(repeats, dim=1)
+        value = value.repeat_interleave(repeats, dim=1)
+        if self.use_sdpa:
+            output = F.scaled_dot_product_attention(
+                query,
+                key,
+                value,
+                attn_mask=attention_mask,
+                dropout_p=self.dropout if self.training else 0.0,
+            )
+        else:
+            scores = query @ key.transpose(-2, -1) / math.sqrt(self.head_dim)
+            if attention_mask is not None:
+                scores = scores.masked_fill(~attention_mask, float("-inf"))
+            probabilities = torch.softmax(scores, dim=-1)
+            if self.training and self.dropout:
+                probabilities = F.dropout(probabilities, p=self.dropout)
+            output = probabilities @ value
+        output = output.transpose(1, 2).contiguous().view(batch, length, query_size)
+        return self.wo(output)
+
+
+class ArkttsFeedForward(nn.Module):
+    def __init__(self, dim: int, intermediate_size: int):
+        super().__init__()
+        self.w1 = nn.Linear(dim, intermediate_size, bias=False)
+        self.w2 = nn.Linear(intermediate_size, dim, bias=False)
+        self.w3 = nn.Linear(dim, intermediate_size, bias=False)
+
+    def forward(self, x: Tensor) -> Tensor:
+        return self.w2(F.silu(self.w1(x)) * self.w3(x))
+
+
+class ArkttsTransformerBlock(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        intermediate_size: int,
+        n_head: int,
+        n_local_heads: int,
+        head_dim: int,
+        qkv_bias: bool,
+        output_bias: bool,
+        qk_norm: bool,
+        norm_eps: float,
+        dropout: float,
+        use_sdpa: bool,
+    ):
+        super().__init__()
+        self.attention = ArkttsAttention(
+            dim,
+            n_head,
+            n_local_heads,
+            head_dim,
+            qkv_bias,
+            output_bias,
+            qk_norm,
+            norm_eps,
+            dropout,
+            use_sdpa,
+        )
+        self.feed_forward = ArkttsFeedForward(dim, intermediate_size)
+        self.ffn_norm = ArkttsRMSNorm(dim, norm_eps)
+        self.attention_norm = ArkttsRMSNorm(dim, norm_eps)
+
+    def forward(self, x, rope, attention_mask, cache_position=None):
+        hidden = x + self.attention(
+            self.attention_norm(x), rope, attention_mask, cache_position
+        )
+        return hidden + self.feed_forward(self.ffn_norm(hidden))
+
+
+class ArkttsModel(nn.Module):
+    def __init__(self, config: ArkttsConfig, codec_path=None):
+        super().__init__()
+        self.config = config
+        self.codec_path = str(codec_path) if codec_path is not None else None
+        self.generation_config: dict = {}
+        self.embeddings = nn.Embedding(config.vocab_size, config.dim)
+        self.codebook_embeddings = nn.Embedding(
+            config.codebook_size * config.num_codebooks, config.dim
+        )
+        self.layers = nn.ModuleList(
+            [
+                ArkttsTransformerBlock(
+                    config.dim,
+                    config.intermediate_size,
+                    config.n_head,
+                    config.n_local_heads,
+                    config.head_dim,
+                    config.attention_qkv_bias,
+                    config.attention_o_bias,
+                    config.attention_qk_norm,
+                    config.norm_eps,
+                    config.dropout,
+                    True,
+                )
+                for _ in range(config.n_layer)
+            ]
+        )
+        self.norm = ArkttsRMSNorm(config.dim, config.norm_eps)
+        self.fast_project_in = (
+            nn.Linear(config.dim, config.fast_dim)
+            if config.fast_dim != config.dim
+            else nn.Identity()
+        )
+        self.fast_embeddings = nn.Embedding(config.codebook_size, config.fast_dim)
+        self.fast_layers = nn.ModuleList(
+            [
+                ArkttsTransformerBlock(
+                    config.fast_dim,
+                    config.fast_intermediate_size,
+                    config.fast_n_head,
+                    config.fast_n_local_heads,
+                    config.fast_head_dim,
+                    config.fast_attention_qkv_bias,
+                    config.fast_attention_o_bias,
+                    config.fast_attention_qk_norm,
+                    config.norm_eps,
+                    config.dropout,
+                    False,
+                )
+                for _ in range(config.n_fast_layer)
+            ]
+        )
+        self.fast_norm = ArkttsRMSNorm(config.fast_dim, config.norm_eps)
+        self.fast_output = nn.Linear(config.fast_dim, config.codebook_size, bias=False)
+        self.register_buffer(
+            "freqs_cis",
+            _precompute_rope(config.max_seq_len, config.head_dim, config.rope_base),
+            persistent=False,
+        )
+        self.register_buffer(
+            "fast_freqs_cis",
+            _precompute_rope(
+                config.num_codebooks, config.fast_head_dim, config.rope_base
+            ),
+            persistent=False,
+        )
+        # kept out of the module tree: the codec loads lazily from its own
+        # file and is not part of model.safetensors
+        self.__dict__["_arktts_codec"] = None
+
+    def reset_rope_buffers(self, device=None):
+        """Recompute the RoPE tables - after load_model built the model on meta."""
+        config = self.config
+        self.freqs_cis = _precompute_rope(
+            config.max_seq_len, config.head_dim, config.rope_base, device=device
+        )
+        self.fast_freqs_cis = _precompute_rope(
+            config.num_codebooks, config.fast_head_dim, config.rope_base, device=device
+        )
+
+    @property
+    def device(self) -> torch.device:
+        return next(self.parameters()).device
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return next(self.parameters()).dtype
+
+    def get_input_embeddings(self):
+        return self.embeddings
+
+    def _embed(self, input_ids: Tensor) -> Tensor:
+        codebook_embeds = []
+        for index in range(self.config.num_codebooks):
+            codebook_embeds.append(
+                self.codebook_embeddings(
+                    input_ids[:, index + 1] + index * self.config.codebook_size
+                )
+            )
+        codebook_sum = torch.stack(codebook_embeds, dim=1).sum(dim=1)
+        semantic = (input_ids[:, 0] >= self.config.semantic_begin_id) & (
+            input_ids[:, 0] <= self.config.semantic_end_id
+        )
+        codebook_sum = torch.where(semantic.unsqueeze(-1), codebook_sum, 0.0)
+        return self.embeddings(input_ids[:, 0]) + codebook_sum
+
+    @staticmethod
+    def _causal_mask(
+        attention_mask: Tensor, query_positions: Tensor, key_length: int
+    ) -> Tensor:
+        if attention_mask.shape[1] < key_length:
+            attention_mask = F.pad(
+                attention_mask,
+                (0, key_length - attention_mask.shape[1]),
+                value=0,
+            )
+        key_positions = torch.arange(key_length, device=attention_mask.device)
+        causal = key_positions[None, :] <= query_positions[:, None]
+        return causal[None, None] & attention_mask[:, None, None, :key_length].bool()
+
+    def forward(
+        self,
+        input_ids: Tensor,
+        attention_mask: Optional[Tensor] = None,
+    ) -> ArkttsModelOutput:
+        if input_ids.ndim != 3 or input_ids.shape[1] != self.config.num_codebooks + 1:
+            raise ValueError(
+                f"input_ids must have shape [B, {self.config.num_codebooks + 1}, T]"
+            )
+        batch, _, length = input_ids.shape
+        if attention_mask is None:
+            attention_mask = torch.ones(
+                (batch, length), dtype=torch.long, device=input_ids.device
+            )
+        position_ids = attention_mask.long().cumsum(-1).sub(1).clamp_min(0)
+        rope = self.freqs_cis[position_ids]
+        mask = self._causal_mask(
+            attention_mask,
+            torch.arange(length, device=input_ids.device),
+            length,
+        )
+        hidden = self._embed(input_ids)
+        for layer in self.layers:
+            hidden = layer(hidden, rope, mask)
+        normalized = self.norm(hidden)
+        logits = F.linear(normalized, self.embeddings.weight)
+        return ArkttsModelOutput(logits=logits, hidden_states=hidden)
+
+    def _setup_generation_caches(self, batch_size: int, dtype):
+        for layer in self.layers:
+            layer.attention.kv_cache = ArkttsKVCache(
+                batch_size,
+                self.config.max_seq_len,
+                self.config.n_local_heads,
+                self.config.head_dim,
+                dtype,
+                return_full=True,
+            ).to(self.device)
+        for layer in self.fast_layers:
+            layer.attention.kv_cache = ArkttsKVCache(
+                batch_size,
+                self.config.num_codebooks,
+                self.config.fast_n_local_heads,
+                self.config.fast_head_dim,
+                dtype,
+                return_full=True,
+            ).to(self.device)
+
+    def _clear_generation_caches(self):
+        # the slow cache is max_seq_len long per layer; a cached model keeps
+        # no buffers from its last run between jobs
+        for layer in (*self.layers, *self.fast_layers):
+            layer.attention.kv_cache = None
+
+    def _slow_step(
+        self,
+        input_ids: Tensor,
+        cache_position: Tensor,
+        position_ids: Tensor,
+        attention_mask: Tensor,
+    ) -> tuple[Tensor, Tensor]:
+        hidden = self._embed(input_ids)
+        rope = self.freqs_cis[position_ids]
+        mask = self._causal_mask(
+            attention_mask,
+            cache_position,
+            self.config.max_seq_len,
+        )
+        for layer in self.layers:
+            hidden = layer(hidden, rope, mask, cache_position)
+        hidden = hidden[:, -1:]
+        normalized = self.norm(hidden)
+        logits = F.linear(normalized, self.embeddings.weight)[:, -1]
+        fast_hidden = normalized if self.config.norm_fastlayer_input else hidden
+        return logits, fast_hidden
+
+    def _fast_step(self, hidden: Tensor, position: int) -> Tensor:
+        cache_position = torch.tensor(
+            [position], device=hidden.device, dtype=torch.long
+        )
+        rope = self.fast_freqs_cis[cache_position]
+        key_mask = torch.ones(
+            (hidden.shape[0], self.config.num_codebooks),
+            device=hidden.device,
+            dtype=torch.bool,
+        )
+        mask = self._causal_mask(key_mask, cache_position, self.config.num_codebooks)
+        for layer in self.fast_layers:
+            hidden = layer(hidden, rope, mask, cache_position)
+        return self.fast_output(self.fast_norm(hidden))[:, -1]
+
+    @staticmethod
+    def _sample(scores: Tensor, generator=None) -> Tensor:
+        probabilities = torch.softmax(scores, dim=-1)
+        random = torch.rand(
+            probabilities.shape,
+            dtype=probabilities.dtype,
+            device=probabilities.device,
+            generator=generator,
+        )
+        noise = -torch.log(random)
+        return torch.argmax(probabilities / noise, dim=-1)
+
+    def _processed_scores(
+        self,
+        input_ids: Tensor,
+        scores: Tensor,
+        processors: list,
+        top_k: int,
+        top_p: float,
+        temperature: float,
+    ) -> Tensor:
+        scores = _apply_processors(processors, input_ids, scores)
+        scores = ArkttsLegacyTopKTopPLogitsProcessor(top_k, top_p)(input_ids, scores)
+        temperature_value = torch.tensor(
+            temperature, dtype=scores.dtype, device=scores.device
+        ).clamp_min(1e-5)
+        return scores / temperature_value
+
+    def _sample_semantic(
+        self,
+        history: Tensor,
+        logits: Tensor,
+        custom_processors: list,
+        top_k: int,
+        top_p: float,
+        temperature: float,
+        previous: Optional[Tensor],
+        do_sample: bool,
+        generator=None,
+    ) -> Tensor:
+        processors = [
+            ArkttsSemanticLogitsProcessor(
+                self.config.semantic_begin_id,
+                self.config.semantic_end_id,
+                self.config.eos_token_id,
+            ),
+            *custom_processors,
+        ]
+        regular_scores = self._processed_scores(
+            history, logits, processors, top_k, top_p, temperature
+        )
+        if not do_sample:
+            return regular_scores.argmax(dim=-1)
+        normal = self._sample(regular_scores, generator=generator)
+        high_scores = self._processed_scores(
+            history,
+            logits,
+            processors,
+            top_k,
+            self.config.ras_top_p,
+            self.config.ras_temperature,
+        )
+        high = self._sample(high_scores, generator=generator)
+        if previous is None:
+            return normal
+        repeated = (previous == normal[:, None]).any(dim=1)
+        semantic = (normal >= self.config.semantic_begin_id) & (
+            normal <= self.config.semantic_end_id
+        )
+        return torch.where(repeated & semantic, high, normal)
+
+    def _generate_codebooks(
+        self,
+        slow_hidden: Tensor,
+        semantic: Tensor,
+        processors: list,
+        top_k: int,
+        top_p: float,
+        temperature: float,
+        do_sample: bool,
+        generator=None,
+    ) -> Tensor:
+        hidden = self.fast_project_in(slow_hidden)
+        self._fast_step(hidden, 0)
+        current = (semantic - self.config.semantic_begin_id).clamp(
+            0, self.config.codebook_size - 1
+        )
+        codebooks = [current]
+        fast_history = current[:, None]
+        hidden = self.fast_embeddings(current)[:, None]
+        for position in range(1, self.config.num_codebooks):
+            scores = self._fast_step(hidden, position)
+            scores = self._processed_scores(
+                fast_history, scores, processors, top_k, top_p, temperature
+            )
+            current = (
+                self._sample(scores, generator=generator)
+                if do_sample
+                else scores.argmax(dim=-1)
+            )
+            codebooks.append(current)
+            fast_history = torch.cat((fast_history, current[:, None]), dim=1)
+            hidden = self.fast_embeddings(current)[:, None]
+        return torch.stack(codebooks, dim=1)
+
+    def _prepare_prompt(
+        self,
+        input_ids=None,
+        attention_mask=None,
+        prefix_input_ids=None,
+        prefix_attention_mask=None,
+        suffix_input_ids=None,
+        suffix_attention_mask=None,
+        reference_codes=None,
+        reference_code_lengths=None,
+        reference_audio_values=None,
+        reference_audio_lengths=None,
+    ):
+        if input_ids is not None:
+            if (
+                input_ids.ndim != 3
+                or input_ids.shape[1] != self.config.num_codebooks + 1
+            ):
+                raise ValueError(
+                    "Direct input_ids must have shape [B, num_codebooks + 1, T]"
+                )
+            if attention_mask is None:
+                attention_mask = torch.ones(
+                    input_ids.shape[0],
+                    input_ids.shape[-1],
+                    dtype=torch.long,
+                    device=input_ids.device,
+                )
+            return input_ids.to(self.device), attention_mask.to(self.device)
+        if prefix_input_ids is None or suffix_input_ids is None:
+            raise ValueError("Processor output or direct input_ids is required")
+        prefix_input_ids = prefix_input_ids.to(self.device)
+        suffix_input_ids = suffix_input_ids.to(self.device)
+        prefix_attention_mask = prefix_attention_mask.to(self.device)
+        suffix_attention_mask = suffix_attention_mask.to(self.device)
+        if reference_audio_values is not None:
+            if reference_codes is not None:
+                raise ValueError("Provide reference audio or reference codes, not both")
+            reference_codes, reference_code_lengths = self.encode_audio(
+                reference_audio_values.to(self.device),
+                reference_audio_lengths.to(self.device),
+            )
+        if reference_codes is not None:
+            reference_codes = reference_codes.to(self.device)
+            reference_code_lengths = reference_code_lengths.to(self.device)
+        batch_size = prefix_input_ids.shape[0]
+        rows = []
+        for batch_index in range(batch_size):
+            prefix = prefix_input_ids[
+                batch_index, prefix_attention_mask[batch_index].bool()
+            ]
+            suffix = suffix_input_ids[
+                batch_index, suffix_attention_mask[batch_index].bool()
+            ]
+            if reference_codes is None:
+                semantic_row = torch.cat((prefix, suffix))
+                values = torch.zeros(
+                    (self.config.num_codebooks + 1, semantic_row.numel()),
+                    dtype=torch.long,
+                    device=self.device,
+                )
+                values[0] = semantic_row
+            else:
+                length = int(reference_code_lengths[batch_index])
+                codes = reference_codes[batch_index, :, :length].long()
+                semantic_codes = codes[0] + self.config.semantic_begin_id
+                semantic_row = torch.cat((prefix, semantic_codes, suffix))
+                values = torch.zeros(
+                    (self.config.num_codebooks + 1, semantic_row.numel()),
+                    dtype=torch.long,
+                    device=self.device,
+                )
+                values[0] = semantic_row
+                values[1:, prefix.numel() : prefix.numel() + length] = codes
+            rows.append(values)
+        max_length = max(row.shape[1] for row in rows)
+        prompt = torch.zeros(
+            (batch_size, self.config.num_codebooks + 1, max_length),
+            dtype=torch.long,
+            device=self.device,
+        )
+        prompt[:, 0] = self.config.pad_token_id
+        prompt_mask = torch.zeros(
+            (batch_size, max_length), dtype=torch.long, device=self.device
+        )
+        for batch_index, row in enumerate(rows):
+            start = max_length - row.shape[1]
+            prompt[batch_index, :, start:] = row
+            prompt_mask[batch_index, start:] = 1
+        return prompt, prompt_mask
+
+    @torch.inference_mode()
+    def generate(
+        self,
+        input_ids: Optional[Tensor] = None,
+        attention_mask: Optional[Tensor] = None,
+        prefix_input_ids: Optional[Tensor] = None,
+        prefix_attention_mask: Optional[Tensor] = None,
+        suffix_input_ids: Optional[Tensor] = None,
+        suffix_attention_mask: Optional[Tensor] = None,
+        reference_codes: Optional[Tensor] = None,
+        reference_code_lengths: Optional[Tensor] = None,
+        reference_audio_values: Optional[Tensor] = None,
+        reference_audio_lengths: Optional[Tensor] = None,
+        generation_config: Optional[dict] = None,
+        logits_processor=None,
+        codebook_logits_processor=None,
+        stopping_criteria=None,
+        max_new_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+        top_p: Optional[float] = None,
+        top_k: Optional[int] = None,
+        do_sample: Optional[bool] = None,
+        return_dict_in_generate: bool = False,
+        generator=None,
+        **kwargs,
+    ):
+        """Codes [B, num_codebooks, T] for the prompt; -1 marks frames past a row's end.
+
+        generation_config is a mapping (generation_config.json's keys); the
+        model's own, loaded by load_model, is used when none is given.
+        logits_processor, codebook_logits_processor and stopping_criteria are
+        lists of callables taking (history, scores).
+        """
+        if kwargs:
+            raise TypeError(f"Unexpected generation arguments: {sorted(kwargs)}")
+        config = (
+            generation_config
+            if generation_config is not None
+            else self.generation_config
+        ) or {}
+        config_max_new = config.get("max_new_tokens")
+        config_temperature = config.get("temperature")
+        config_top_p = config.get("top_p")
+        config_top_k = config.get("top_k")
+        max_new_tokens = int(
+            max_new_tokens if max_new_tokens is not None else (config_max_new or 512)
+        )
+        temperature = float(
+            temperature if temperature is not None else (config_temperature or 0.7)
+        )
+        top_p = float(top_p if top_p is not None else (config_top_p or 0.9))
+        top_k = int(top_k if top_k is not None else (config_top_k or 50))
+        do_sample = bool(
+            do_sample if do_sample is not None else config.get("do_sample", True)
+        )
+        if max_new_tokens <= 0:
+            raise ValueError("max_new_tokens must be positive")
+        if temperature <= 0:
+            raise ValueError("temperature must be positive")
+        prompt, prompt_mask = self._prepare_prompt(
+            input_ids,
+            attention_mask,
+            prefix_input_ids,
+            prefix_attention_mask,
+            suffix_input_ids,
+            suffix_attention_mask,
+            reference_codes,
+            reference_code_lengths,
+            reference_audio_values,
+            reference_audio_lengths,
+        )
+        batch_size, _, prompt_width = prompt.shape
+        if prompt_width >= self.config.max_seq_len:
+            raise ValueError(
+                f"Prompt length {prompt_width} must be smaller than "
+                f"{self.config.max_seq_len}"
+            )
+        max_new_tokens = min(max_new_tokens, self.config.max_seq_len - prompt_width)
+        self._setup_generation_caches(batch_size, self.dtype)
+        try:
+            return self._generate_loop(
+                prompt,
+                prompt_mask,
+                list(logits_processor or []),
+                list(codebook_logits_processor or []),
+                list(stopping_criteria or []),
+                max_new_tokens,
+                temperature,
+                top_p,
+                top_k,
+                do_sample,
+                return_dict_in_generate,
+                generator,
+            )
+        finally:
+            self._clear_generation_caches()
+
+    def _generate_loop(
+        self,
+        prompt,
+        prompt_mask,
+        semantic_processors,
+        codebook_processors,
+        criteria,
+        max_new_tokens,
+        temperature,
+        top_p,
+        top_k,
+        do_sample,
+        return_dict_in_generate,
+        generator,
+    ):
+        batch_size, _, prompt_width = prompt.shape
+        cache_position = torch.arange(
+            prompt_width, device=self.device, dtype=torch.long
+        )
+        position_ids = prompt_mask.cumsum(-1).sub(1).clamp_min(0)
+        logits, slow_hidden = self._slow_step(
+            prompt, cache_position, position_ids, prompt_mask
+        )
+        semantic_history = prompt[:, 0]
+        prompt_lengths = prompt_mask.sum(-1)
+        previous = None
+        finished = torch.zeros(batch_size, dtype=torch.bool, device=self.device)
+        code_lengths = torch.zeros(batch_size, dtype=torch.long, device=self.device)
+        generated_frames = []
+
+        for step in range(max_new_tokens):
+            active_before = ~finished
+            semantic = self._sample_semantic(
+                semantic_history,
+                logits,
+                semantic_processors,
+                top_k,
+                top_p,
+                temperature,
+                previous,
+                do_sample,
+                generator,
+            )
+            codebooks = self._generate_codebooks(
+                slow_hidden,
+                semantic,
+                codebook_processors,
+                top_k,
+                top_p,
+                temperature,
+                do_sample,
+                generator,
+            )
+            emitted = active_before & (semantic != self.config.eos_token_id)
+            frame = torch.where(emitted[:, None], codebooks, -1)
+            generated_frames.append(frame)
+            code_lengths += emitted.long()
+            semantic_history = torch.cat((semantic_history, semantic[:, None]), dim=1)
+
+            if previous is None:
+                previous = torch.zeros(
+                    (batch_size, self.config.ras_window_size),
+                    dtype=torch.long,
+                    device=self.device,
+                )
+            else:
+                previous = previous.roll(-1, dims=1)
+                previous[:, -1] = semantic
+            finished |= semantic.eq(self.config.eos_token_id)
+            for criterion in criteria:
+                stopped = criterion(semantic_history, logits)
+                if not isinstance(stopped, Tensor):
+                    stopped = torch.full_like(finished, bool(stopped))
+                finished |= stopped.to(device=self.device, dtype=torch.bool)
+            if finished.all():
+                break
+
+            next_column = torch.cat((semantic[:, None], codebooks), dim=1).unsqueeze(-1)
+            new_valid = active_before.long()[:, None]
+            prompt_mask = torch.cat((prompt_mask, new_valid), dim=1)
+            physical_position = torch.tensor([prompt_width + step], device=self.device)
+            token_position = (prompt_lengths + step)[:, None]
+            with sdpa_kernel(SDPBackend.MATH):
+                logits, slow_hidden = self._slow_step(
+                    next_column, physical_position, token_position, prompt_mask
+                )
+
+        if generated_frames:
+            codes = torch.stack(generated_frames, dim=2)
+            max_valid = int(code_lengths.max().item()) if code_lengths.numel() else 0
+            codes = codes[:, :, :max_valid]
+        else:
+            codes = torch.empty(
+                (batch_size, self.config.num_codebooks, 0),
+                dtype=torch.long,
+                device=self.device,
+            )
+        if return_dict_in_generate:
+            return ArkttsGenerateOutput(
+                codes=codes, code_lengths=code_lengths, finished=finished
+            )
+        return codes
+
+    def load_codec(self, device=None, dtype=None):
+        codec = self.__dict__.get("_arktts_codec")
+        target_device = torch.device(device) if device is not None else self.device
+        target_dtype = dtype or self.dtype
+        if target_device.type == "cpu":
+            target_dtype = torch.float32
+        if codec is None:
+            if self.codec_path is None:
+                raise FileNotFoundError(
+                    f"No {self.config.codec_filename} path was given for this model"
+                )
+            codec = ArkttsCodec(self.config)
+            codec.load_state_dict(load_codec_state(self.codec_path), strict=True)
+            codec.eval()
+            self.__dict__["_arktts_codec"] = codec
+        codec.to(device=target_device, dtype=target_dtype)
+        return codec
+
+    @torch.inference_mode()
+    def encode_audio(
+        self, audio_values: Tensor, audio_lengths: Optional[Tensor] = None
+    ):
+        codec = self.load_codec(device=audio_values.device)
+        audio_values = audio_values.to(dtype=next(codec.parameters()).dtype)
+        return codec.encode(audio_values, audio_lengths)
+
+    @torch.inference_mode()
+    def decode_audio(self, codes: Tensor):
+        """(waveforms [B, samples] float32, lengths [B]) at config.codec_sample_rate."""
+        if codes.ndim == 2:
+            codes = codes.unsqueeze(0)
+        if codes.ndim != 3 or codes.shape[1] != self.config.num_codebooks:
+            raise ValueError(
+                f"codes must have shape [B, {self.config.num_codebooks}, T]"
+            )
+        codec = self.load_codec(device=codes.device)
+        waveforms = []
+        lengths = []
+        for item in codes:
+            valid = (item >= 0).all(dim=0)
+            length = int(valid.sum().item())
+            if length == 0:
+                waveform = torch.empty(0, device=codes.device, dtype=torch.float32)
+            else:
+                waveform = codec.decode(item[:, :length].unsqueeze(0))[0, 0].float()
+            waveforms.append(waveform)
+            lengths.append(waveform.numel())
+        max_length = max(lengths, default=0)
+        padded = torch.zeros(
+            (len(waveforms), max_length), dtype=torch.float32, device=codes.device
+        )
+        for index, waveform in enumerate(waveforms):
+            padded[index, : waveform.numel()] = waveform
+        return padded, torch.tensor(lengths, dtype=torch.long, device=codes.device)
+
+    @torch.inference_mode()
+    def generate_audio(self, **kwargs):
+        codes = self.generate(**kwargs)
+        waveforms, lengths = self.decode_audio(codes)
+        return waveforms, lengths, codes
+
+
+def _fold_legacy_weight_norm(state: dict) -> dict:
+    """Plain '.weight' tensors for the checkpoint's legacy weight_g/weight_v pairs.
+
+    The quantizer projections were saved through torch.nn.utils.weight_norm,
+    which is deprecated; at inference the norm is a constant, so it is folded
+    into the weight once here (w = g * v / ||v||, norm over every dim but 0).
+    """
+    folded = {}
+    for key, value in state.items():
+        if key.endswith(".weight_v"):
+            continue
+        if key.endswith(".weight_g"):
+            stem = key[: -len("_g")]
+            direction = state[f"{stem}_v"]
+            folded[stem] = torch._weight_norm(direction, value, 0)
+            continue
+        folded[key] = value
+    return folded
+
+
+def load_codec_state(path) -> dict:
+    """The codec state dict from a local codec.pth, read with weights_only=True."""
+    state = torch.load(str(path), map_location="cpu", weights_only=True)
+    if "state_dict" in state:
+        state = state["state_dict"]
+    if any("generator." in key for key in state):
+        state = {
+            key.replace("generator.", ""): value
+            for key, value in state.items()
+            if "generator." in key
+        }
+    state = {
+        key: value
+        for key, value in state.items()
+        if not key.endswith(("freqs_cis", "causal_mask"))
+    }
+    return _fold_legacy_weight_norm(state)
+
+
+def load_model(
+    config_path,
+    weights_path,
+    codec_path,
+    generation_config_path=None,
+    device="cpu",
+    dtype=torch.bfloat16,
+) -> ArkttsModel:
+    """An ArkttsModel from local files; the codec loads on first encode/decode."""
+    from safetensors.torch import load_file
+
+    config = ArkttsConfig.from_json_file(config_path)
+    # built on meta so the 0.6B parameters are not randomly initialised only
+    # to be overwritten; assign=True takes the loaded tensors as they are
+    with torch.device("meta"):
+        model = ArkttsModel(config, codec_path=codec_path)
+    model.load_state_dict(load_file(str(weights_path)), strict=True, assign=True)
+    model.reset_rope_buffers(device="cpu")
+    if generation_config_path is not None:
+        with open(generation_config_path, "r", encoding="utf-8") as handle:
+            model.generation_config = json.load(handle)
+    model.to(device=device, dtype=dtype)
+    model.eval()
+    return model
+
+
+# --- codec (upstream modeling_arktts_codec.py) ------------------------------
+
+
+def _rope(length: int, head_dim: int, base: float, device=None) -> Tensor:
+    frequencies = 1.0 / (
+        base ** (torch.arange(0, head_dim, 2, device=device).float() / head_dim)
+    )
+    phases = torch.outer(torch.arange(length, device=device), frequencies)
+    values = torch.polar(torch.ones_like(phases), phases)
+    return torch.stack((values.real, values.imag), dim=-1).to(torch.bfloat16)
+
+
+def _apply_codec_rope(x: Tensor, values: Tensor) -> Tensor:
+    shaped = x.float().reshape(*x.shape[:-1], -1, 2)
+    values = values.view(1, shaped.shape[1], 1, shaped.shape[3], 2)
+    output = torch.stack(
+        (
+            shaped[..., 0] * values[..., 0] - shaped[..., 1] * values[..., 1],
+            shaped[..., 1] * values[..., 0] + shaped[..., 0] * values[..., 1],
+        ),
+        dim=-1,
+    )
+    return output.flatten(3).to(x.dtype)
+
+
+class ArkttsCodecRMSNorm(nn.Module):
+    def __init__(self, dim: int, eps: float = 1e-5):
+        super().__init__()
+        self.eps = float(eps)
+        self.weight = nn.Parameter(torch.ones(dim))
+
+    def forward(self, x):
+        output = x.float() * torch.rsqrt(
+            x.float().pow(2).mean(-1, keepdim=True) + self.eps
+        )
+        return output.to(x.dtype) * self.weight
+
+
+class ArkttsCodecLayerScale(nn.Module):
+    def __init__(self, dim: int, init_values: float = 1e-2, inplace: bool = False):
+        super().__init__()
+        self.inplace = bool(inplace)
+        self.gamma = nn.Parameter(init_values * torch.ones(dim))
+
+    def forward(self, x):
+        return x.mul_(self.gamma) if self.inplace else x * self.gamma
+
+
+@dataclass
+class ArkttsCodecTransformerConfig:
+    n_layer: int
+    n_head: int
+    dim: int
+    intermediate_size: int
+    n_local_heads: int = -1
+    head_dim: int = 64
+    rope_base: float = 10000
+    norm_eps: float = 1e-5
+    dropout_rate: float = 0.1
+    attn_dropout_rate: float = 0.1
+    channels_first: bool = True
+
+    def __post_init__(self):
+        if self.n_local_heads == -1:
+            self.n_local_heads = self.n_head
+
+
+class ArkttsCodecAttention(nn.Module):
+    def __init__(self, config: ArkttsCodecTransformerConfig):
+        super().__init__()
+        total = (config.n_head + 2 * config.n_local_heads) * config.head_dim
+        self.wqkv = nn.Linear(config.dim, total, bias=False)
+        self.wo = nn.Linear(config.head_dim * config.n_head, config.dim, bias=False)
+        self.n_head = config.n_head
+        self.n_local_heads = config.n_local_heads
+        self.head_dim = config.head_dim
+        self.attn_dropout_rate = config.attn_dropout_rate
+
+    def forward(self, x, rope_values, mask):
+        batch, length, _ = x.shape
+        query_size = self.n_head * self.head_dim
+        kv_size = self.n_local_heads * self.head_dim
+        query, key, value = self.wqkv(x).split((query_size, kv_size, kv_size), dim=-1)
+        query = query.view(batch, length, self.n_head, self.head_dim)
+        key = key.view(batch, length, self.n_local_heads, self.head_dim)
+        value = value.view(batch, length, self.n_local_heads, self.head_dim)
+        query = _apply_codec_rope(query, rope_values).transpose(1, 2)
+        key = _apply_codec_rope(key, rope_values).transpose(1, 2)
+        value = value.transpose(1, 2)
+        repeat = self.n_head // self.n_local_heads
+        key = key.repeat_interleave(repeat, dim=1)
+        value = value.repeat_interleave(repeat, dim=1)
+        output = F.scaled_dot_product_attention(
+            query,
+            key,
+            value,
+            attn_mask=mask,
+            dropout_p=self.attn_dropout_rate if self.training else 0.0,
+        )
+        output = output.transpose(1, 2).contiguous().view(batch, length, query_size)
+        return self.wo(output)
+
+
+class ArkttsCodecFeedForward(nn.Module):
+    def __init__(self, config: ArkttsCodecTransformerConfig):
+        super().__init__()
+        self.w1 = nn.Linear(config.dim, config.intermediate_size, bias=False)
+        self.w3 = nn.Linear(config.dim, config.intermediate_size, bias=False)
+        self.w2 = nn.Linear(config.intermediate_size, config.dim, bias=False)
+        self.dropout = nn.Dropout(config.dropout_rate)
+
+    def forward(self, x):
+        return self.w2(self.dropout(F.silu(self.w1(x)) * self.w3(x)))
+
+
+class ArkttsCodecTransformerBlock(nn.Module):
+    def __init__(self, config):
+        super().__init__()
+        self.attention = ArkttsCodecAttention(config)
+        self.feed_forward = ArkttsCodecFeedForward(config)
+        self.ffn_norm = ArkttsCodecRMSNorm(config.dim, config.norm_eps)
+        self.attention_norm = ArkttsCodecRMSNorm(config.dim, config.norm_eps)
+        self.attention_layer_scale = ArkttsCodecLayerScale(config.dim, inplace=True)
+        self.ffn_layer_scale = ArkttsCodecLayerScale(config.dim, inplace=True)
+
+    def forward(self, x, rope_values, mask):
+        hidden = x + self.attention_layer_scale(
+            self.attention(self.attention_norm(x), rope_values, mask)
+        )
+        return hidden + self.ffn_layer_scale(self.feed_forward(self.ffn_norm(hidden)))
+
+
+class ArkttsCodecWindowTransformer(nn.Module):
+    def __init__(
+        self, config, input_dim: int, window_size: int | None, causal: bool = True
+    ):
+        super().__init__()
+        self.layers = nn.ModuleList(
+            [ArkttsCodecTransformerBlock(config) for _ in range(config.n_layer)]
+        )
+        self.norm = ArkttsCodecRMSNorm(config.dim, config.norm_eps)
+        self.window_size = window_size
+        self.causal = causal
+        self.channels_first = config.channels_first
+        self.input_proj = (
+            nn.Linear(input_dim, config.dim)
+            if input_dim != config.dim
+            else nn.Identity()
+        )
+        self.output_proj = (
+            nn.Linear(config.dim, input_dim)
+            if input_dim != config.dim
+            else nn.Identity()
+        )
+        self.look_ahead_conv = nn.Identity()
+        self.head_dim = config.head_dim
+        self.rope_base = config.rope_base
+
+    def forward(self, x, x_lens=None):
+        del x_lens
+        if self.channels_first:
+            x = x.transpose(1, 2)
+        x = self.look_ahead_conv(self.input_proj(x))
+        length = x.shape[1]
+        row = torch.arange(length, device=x.device)[:, None]
+        column = torch.arange(length, device=x.device)[None, :]
+        mask = column <= row
+        if self.window_size is not None:
+            mask &= column >= (row - self.window_size + 1).clamp_min(0)
+        mask = mask[None, None]
+        rope_values = _rope(length, self.head_dim, self.rope_base, x.device)
+        for layer in self.layers:
+            x = layer(x, rope_values, mask)
+        x = self.output_proj(self.norm(x))
+        return x.transpose(1, 2) if self.channels_first else x
+
+
+def _extra_padding(x, kernel_size: int, stride: int, padding_total: int = 0) -> int:
+    length = x.shape[-1]
+    frames = (length - kernel_size + padding_total) / stride + 1
+    ideal = (math.ceil(frames) - 1) * stride + kernel_size - padding_total
+    return ideal - length
+
+
+class ArkttsCausalConv1d(nn.Module):
+    def __init__(
+        self, in_channels, out_channels, kernel_size, dilation=1, stride=1, groups=1
+    ):
+        super().__init__()
+        self.conv = nn.Conv1d(
+            in_channels,
+            out_channels,
+            kernel_size,
+            stride=stride,
+            dilation=dilation,
+            groups=groups,
+        )
+        self.stride = stride
+        self.kernel_size = (kernel_size - 1) * dilation + 1
+        self.padding = self.kernel_size - self.stride
+
+    def forward(self, x):
+        right = _extra_padding(x, self.kernel_size, self.stride, self.padding)
+        return self.conv(F.pad(x, (self.padding, right))).contiguous()
+
+    def apply_weight_norm(self):
+        self.conv = weight_norm(self.conv)
+        return self
+
+
+class ArkttsCausalConvTranspose1d(nn.Module):
+    def __init__(self, in_channels, out_channels, kernel_size, stride=1, dilation=1):
+        super().__init__()
+        self.conv = nn.ConvTranspose1d(
+            in_channels, out_channels, kernel_size, stride=stride, dilation=dilation
+        )
+        self.stride = stride
+        self.kernel_size = kernel_size
+
+    def forward(self, x):
+        x = self.conv(x)
+        crop = self.kernel_size - self.stride
+        return x[..., : x.shape[-1] - crop].contiguous() if crop else x.contiguous()
+
+    def apply_weight_norm(self):
+        self.conv = weight_norm(self.conv)
+        return self
+
+
+def _causal_wn_conv(*args, **kwargs):
+    return ArkttsCausalConv1d(*args, **kwargs).apply_weight_norm()
+
+
+def _causal_wn_transpose(*args, **kwargs):
+    return ArkttsCausalConvTranspose1d(*args, **kwargs).apply_weight_norm()
+
+
+def _arktts_snake(x: Tensor, alpha: Tensor) -> Tensor:
+    shape = x.shape
+    x = x.reshape(shape[0], shape[1], -1)
+    x = x + (alpha + 1e-9).reciprocal() * torch.sin(alpha * x).pow(2)
+    return x.reshape(shape)
+
+
+class ArkttsSnake1d(nn.Module):
+    def __init__(self, channels):
+        super().__init__()
+        self.alpha = nn.Parameter(torch.ones(1, channels, 1))
+
+    def forward(self, x):
+        return _arktts_snake(x, self.alpha)
+
+
+class ArkttsResidualUnit(nn.Module):
+    def __init__(self, dim: int, dilation: int):
+        super().__init__()
+        self.block = nn.Sequential(
+            ArkttsSnake1d(dim),
+            _causal_wn_conv(dim, dim, kernel_size=7, dilation=dilation),
+            ArkttsSnake1d(dim),
+            _causal_wn_conv(dim, dim, kernel_size=1),
+        )
+
+    def forward(self, x):
+        output = self.block(x)
+        difference = x.shape[-1] - output.shape[-1]
+        if difference > 0:
+            x = x[..., :-difference]
+        return x + output
+
+
+class ArkttsEncoderBlock(nn.Module):
+    def __init__(self, dim: int, stride: int, transformer_layers: int):
+        super().__init__()
+        modules = [
+            ArkttsResidualUnit(dim // 2, 1),
+            ArkttsResidualUnit(dim // 2, 3),
+            ArkttsResidualUnit(dim // 2, 9),
+            ArkttsSnake1d(dim // 2),
+            _causal_wn_conv(dim // 2, dim, kernel_size=2 * stride, stride=stride),
+        ]
+        if transformer_layers:
+            config = ArkttsCodecTransformerConfig(
+                n_layer=transformer_layers,
+                n_head=max(dim // 64, 1),
+                dim=dim,
+                intermediate_size=dim * 3,
+            )
+            modules.append(ArkttsCodecWindowTransformer(config, dim, window_size=512))
+        else:
+            modules.append(nn.Identity())
+        self.block = nn.Sequential(*modules)
+
+    def forward(self, x):
+        return self.block(x)
+
+
+class ArkttsEncoder(nn.Module):
+    def __init__(
+        self, base_dim: int = 64, transformer_layers: int = 4, latent_dim: int = 1024
+    ):
+        super().__init__()
+        dim = base_dim
+        modules = [_causal_wn_conv(1, dim, kernel_size=7)]
+        for stride, layers in zip((2, 4, 8, 8), (0, 0, 0, transformer_layers)):
+            dim *= 2
+            modules.append(ArkttsEncoderBlock(dim, stride, layers))
+        modules.extend(
+            (ArkttsSnake1d(dim), _causal_wn_conv(dim, latent_dim, kernel_size=3))
+        )
+        self.block = nn.Sequential(*modules)
+
+    def forward(self, x):
+        return self.block(x)
+
+
+class ArkttsDecoderBlock(nn.Module):
+    def __init__(self, input_dim: int, output_dim: int, stride: int):
+        super().__init__()
+        self.block = nn.Sequential(
+            ArkttsSnake1d(input_dim),
+            _causal_wn_transpose(
+                input_dim, output_dim, kernel_size=2 * stride, stride=stride
+            ),
+            ArkttsResidualUnit(output_dim, 1),
+            ArkttsResidualUnit(output_dim, 3),
+            ArkttsResidualUnit(output_dim, 9),
+        )
+
+    def forward(self, x):
+        return self.block(x)
+
+
+class ArkttsDecoder(nn.Module):
+    def __init__(self, channels: int = 1536, latent_dim: int = 1024):
+        super().__init__()
+        modules = [_causal_wn_conv(latent_dim, channels, kernel_size=7)]
+        for index, stride in enumerate((8, 8, 4, 2)):
+            input_dim = channels // (2**index)
+            output_dim = channels // (2 ** (index + 1))
+            modules.append(ArkttsDecoderBlock(input_dim, output_dim, stride))
+        modules.extend(
+            (
+                ArkttsSnake1d(output_dim),
+                _causal_wn_conv(output_dim, 1, kernel_size=7),
+                nn.Tanh(),
+            )
+        )
+        self.model = nn.Sequential(*modules)
+
+    def forward(self, x):
+        return self.model(x)
+
+
+class ArkttsVectorQuantizer(nn.Module):
+    def __init__(self, input_dim: int, codebook_size: int, codebook_dim: int):
+        super().__init__()
+        self.codebook_size = int(codebook_size)
+        self.codebook_dim = int(codebook_dim)
+        # upstream wraps both projections in the deprecated legacy
+        # weight_norm; load_codec_state folds the checkpoint's g/v pairs
+        self.in_proj = nn.Conv1d(input_dim, codebook_dim, kernel_size=1)
+        self.out_proj = nn.Conv1d(codebook_dim, input_dim, kernel_size=1)
+        self.codebook = nn.Embedding(codebook_size, codebook_dim)
+
+    def decode_code(self, indices):
+        return F.embedding(indices, self.codebook.weight).transpose(1, 2)
+
+    def decode_latents(self, latents):
+        batch, _, length = latents.shape
+        flattened = latents.transpose(1, 2).reshape(batch * length, -1)
+        flattened = F.normalize(flattened)
+        codebook = F.normalize(self.codebook.weight)
+        distances = (
+            flattened.pow(2).sum(1, keepdim=True)
+            - 2 * flattened @ codebook.t()
+            + codebook.pow(2).sum(1, keepdim=True).t()
+        )
+        indices = (-distances).argmax(1).view(batch, length)
+        return self.decode_code(indices), indices
+
+    def forward(self, z):
+        projected = self.in_proj(z)
+        quantized, indices = self.decode_latents(projected)
+        quantized_st = projected + (quantized - projected).detach()
+        return self.out_proj(quantized_st), indices, projected
+
+
+class ArkttsResidualQuantizer(nn.Module):
+    def __init__(
+        self, input_dim: int, n_codebooks: int, codebook_size: int, codebook_dim: int
+    ):
+        super().__init__()
+        self.n_codebooks = int(n_codebooks)
+        self.codebook_size = int(codebook_size)
+        self.quantizers = nn.ModuleList(
+            [
+                ArkttsVectorQuantizer(input_dim, codebook_size, codebook_dim)
+                for _ in range(n_codebooks)
+            ]
+        )
+
+    def forward(self, z):
+        quantized_sum = 0.0
+        residual = z
+        codes = []
+        for quantizer in self.quantizers:
+            quantized, indices, _ = quantizer(residual)
+            quantized_sum = quantized_sum + quantized
+            residual = residual - quantized
+            codes.append(indices)
+        return quantized_sum, torch.stack(codes, dim=1)
+
+    def from_codes(self, codes):
+        output = 0.0
+        for index in range(codes.shape[1]):
+            projected = self.quantizers[index].decode_code(codes[:, index])
+            output = output + self.quantizers[index].out_proj(projected)
+        return output
+
+
+class ArkttsConvNeXtBlock(nn.Module):
+    def __init__(self, dim: int):
+        super().__init__()
+        self.dwconv = ArkttsCausalConv1d(dim, dim, kernel_size=7, groups=dim)
+        self.norm = nn.LayerNorm(dim, eps=1e-6)
+        self.pwconv1 = nn.Linear(dim, 4 * dim)
+        self.act = nn.GELU()
+        self.pwconv2 = nn.Linear(4 * dim, dim)
+        self.gamma = nn.Parameter(1e-6 * torch.ones(dim))
+
+    def forward(self, x):
+        residual = x
+        x = self.dwconv(x).permute(0, 2, 1)
+        x = self.pwconv2(self.act(self.pwconv1(self.norm(x))))
+        x = (self.gamma * x).permute(0, 2, 1)
+        return residual + x
+
+
+class ArkttsDownsampleQuantizer(nn.Module):
+    def __init__(self, config: ArkttsConfig):
+        super().__init__()
+        latent = config.codec_latent_dim
+        self.semantic_quantizer = ArkttsResidualQuantizer(
+            latent, 1, config.codebook_size, config.codec_codebook_dim
+        )
+        self.quantizer = ArkttsResidualQuantizer(
+            latent,
+            config.num_codebooks - 1,
+            config.codec_residual_codebook_size,
+            config.codec_codebook_dim,
+        )
+        self.downsample = nn.Sequential(
+            nn.Sequential(
+                ArkttsCausalConv1d(latent, latent, kernel_size=2, stride=2),
+                ArkttsConvNeXtBlock(latent),
+            ),
+            nn.Sequential(
+                ArkttsCausalConv1d(latent, latent, kernel_size=2, stride=2),
+                ArkttsConvNeXtBlock(latent),
+            ),
+        )
+        self.upsample = nn.Sequential(
+            nn.Sequential(
+                ArkttsCausalConvTranspose1d(latent, latent, kernel_size=2, stride=2),
+                ArkttsConvNeXtBlock(latent),
+            ),
+            nn.Sequential(
+                ArkttsCausalConvTranspose1d(latent, latent, kernel_size=2, stride=2),
+                ArkttsConvNeXtBlock(latent),
+            ),
+        )
+        pre_transformer_config = ArkttsCodecTransformerConfig(
+            n_layer=config.codec_pre_n_layer,
+            n_head=config.codec_pre_n_head,
+            dim=latent,
+            intermediate_size=config.codec_pre_intermediate_size,
+        )
+        post_transformer_config = ArkttsCodecTransformerConfig(
+            n_layer=config.codec_post_n_layer,
+            n_head=config.codec_post_n_head,
+            n_local_heads=config.codec_post_n_local_heads,
+            dim=latent,
+            intermediate_size=config.codec_post_intermediate_size,
+        )
+        self.pre_module = ArkttsCodecWindowTransformer(
+            pre_transformer_config, latent, window_size=128
+        )
+        self.post_module = ArkttsCodecWindowTransformer(
+            post_transformer_config, latent, window_size=128
+        )
+        self.semantic_predictor_module = nn.Identity()
+
+    def forward(self, z):
+        original_length = z.shape[-1]
+        z = self.pre_module(self.downsample(z))
+        semantic, semantic_codes = self.semantic_quantizer(z)
+        residual, residual_codes = self.quantizer(z - semantic)
+        z = self.upsample(self.post_module(semantic + residual))
+        difference = original_length - z.shape[-1]
+        if difference > 0:
+            z = F.pad(z, (difference, 0))
+        elif difference < 0:
+            z = z[..., -difference:]
+        return z, torch.cat((semantic_codes, residual_codes), dim=1)
+
+    def decode(self, indices):
+        indices = indices.clone()
+        indices[:, 0].clamp_(0, self.semantic_quantizer.codebook_size - 1)
+        indices[:, 1:].clamp_(0, self.quantizer.codebook_size - 1)
+        semantic = self.semantic_quantizer.from_codes(indices[:, :1])
+        residual = self.quantizer.from_codes(indices[:, 1:])
+        return self.upsample(self.post_module(semantic + residual))
+
+
+class ArkttsCodec(nn.Module):
+    sample_rate = 44100
+    hop_length = 512
+    frame_length = 2048
+
+    def __init__(self, config: ArkttsConfig | None = None):
+        super().__init__()
+        config = config or ArkttsConfig()
+        self.encoder = ArkttsEncoder(
+            config.codec_encoder_dim,
+            config.codec_encoder_transformer_layers,
+            config.codec_latent_dim,
+        )
+        self.quantizer = ArkttsDownsampleQuantizer(config)
+        self.decoder = ArkttsDecoder(config.codec_decoder_dim, config.codec_latent_dim)
+
+    @torch.inference_mode()
+    def encode(self, audio, audio_lengths=None):
+        if audio.ndim == 2:
+            audio = audio[:, None]
+        if audio.ndim != 3 or audio.shape[1] != 1:
+            raise ValueError("audio must have shape [B, 1, samples]")
+        original_length = audio.shape[-1]
+        right = (
+            math.ceil(original_length / self.frame_length) * self.frame_length
+            - original_length
+        )
+        if right:
+            audio = F.pad(audio, (0, right))
+        if audio_lengths is None:
+            audio_lengths = torch.full(
+                (audio.shape[0],),
+                original_length,
+                device=audio.device,
+                dtype=torch.long,
+            )
+        encoded = self.encoder(audio)
+        _, codes = self.quantizer(encoded)
+        code_lengths = torch.ceil(audio_lengths.float() / self.frame_length).long()
+        max_codes = codes.shape[-1]
+        padded = torch.full_like(codes, -1)
+        for index, length in enumerate(code_lengths.tolist()):
+            padded[index, :, : min(length, max_codes)] = codes[
+                index, :, : min(length, max_codes)
+            ]
+        return padded, code_lengths.clamp_max(max_codes)
+
+    @torch.inference_mode()
+    def decode(self, codes):
+        return self.decoder(self.quantizer.decode(codes.long()))
+
+
+# --- processor (upstream processing_arktts.py) ------------------------------
+
+
+def load_tokenizer(path):
+    """The model's stock fast tokenizer, from a local tokenizer.json."""
+    from transformers import PreTrainedTokenizerFast
+
+    return PreTrainedTokenizerFast(tokenizer_file=str(path))
+
+
+def _clean_text(text: str) -> str:
+    return " ".join(str(text).strip().split())
+
+
+def _as_list(value: Any, batch_size: int, name: str) -> list[Any]:
+    if isinstance(value, (str, Path)) or value is None or np.isscalar(value):
+        return [value] * batch_size
+    if isinstance(value, torch.Tensor) and value.ndim <= 2:
+        return [value] if batch_size == 1 else list(value)
+    if isinstance(value, np.ndarray) and value.ndim <= 2:
+        return [value] if batch_size == 1 else list(value)
+    values = list(value)
+    if len(values) != batch_size:
+        raise ValueError(f"{name} must contain {batch_size} items, got {len(values)}")
+    return values
+
+
+def _pad_1d(rows: list[Tensor], pad_value: int) -> tuple[Tensor, Tensor]:
+    max_len = max((row.numel() for row in rows), default=0)
+    values = torch.full((len(rows), max_len), pad_value, dtype=torch.long)
+    mask = torch.zeros((len(rows), max_len), dtype=torch.long)
+    for idx, row in enumerate(rows):
+        length = row.numel()
+        values[idx, :length] = row
+        mask[idx, :length] = 1
+    return values, mask
+
+
+class ArkttsProcessor:
+    """Builds generate()'s prompt inputs from text and an optional reference voice.
+
+    The tokenizer is anything with encode(text, add_special_tokens=False)
+    returning token ids - load_tokenizer() gives the model's own.
+    """
+
+    def __init__(
+        self,
+        tokenizer,
+        pad_token_id: int = 151643,
+        num_codebooks: int = 10,
+        semantic_begin_id: int = 151678,
+        audio_sampling_rate: int = 44100,
+    ):
+        self.tokenizer = tokenizer
+        self.pad_token_id = int(pad_token_id)
+        self.num_codebooks = int(num_codebooks)
+        self.semantic_begin_id = int(semantic_begin_id)
+        self.audio_sampling_rate = int(audio_sampling_rate)
+
+    @classmethod
+    def for_model(cls, tokenizer, config: ArkttsConfig) -> "ArkttsProcessor":
+        return cls(
+            tokenizer,
+            pad_token_id=config.pad_token_id,
+            num_codebooks=config.num_codebooks,
+            semantic_begin_id=config.semantic_begin_id,
+            audio_sampling_rate=config.codec_sample_rate,
+        )
+
+    def _encode(self, text: str) -> Tensor:
+        ids = self.tokenizer.encode(text, add_special_tokens=False)
+        return torch.tensor(ids, dtype=torch.long)
+
+    @staticmethod
+    def _format_reference_text(text: str) -> str:
+        cleaned = _clean_text(text)
+        if re.search(r"<\|speaker:\d+\|>", cleaned):
+            return cleaned
+        return f"<|speaker:0|>{cleaned}"
+
+    def _prompt_segments(
+        self, text: str, reference_text: str | None, has_reference: bool
+    ):
+        target = _clean_text(text)
+        if not target:
+            raise ValueError("text must not be empty")
+
+        def encode_parts(parts: list[str]) -> Tensor:
+            return torch.cat([self._encode(part) for part in parts])
+
+        if not has_reference:
+            full = encode_parts(
+                [
+                    "<|im_start|>system\n",
+                    "convert the provided text to speech",
+                    "<|im_end|>\n",
+                    "<|im_start|>user\n",
+                    target,
+                    "<|im_end|>\n",
+                    "<|im_start|>assistant\n<|voice|>",
+                ]
+            )
+            return full, self._encode("")
+        if not reference_text:
+            raise ValueError(
+                "reference_text is required when a reference voice is provided"
+            )
+        prefix = encode_parts(
+            [
+                "<|im_start|>system\n",
+                "convert the provided text to speech reference to the following:"
+                "\n\nText:\n",
+                self._format_reference_text(reference_text),
+                "\n\nSpeech:\n",
+            ]
+        )
+        suffix = encode_parts(
+            [
+                "<|im_end|>\n",
+                "<|im_start|>user\n",
+                target,
+                "<|im_end|>\n",
+                "<|im_start|>assistant\n<|voice|>",
+            ]
+        )
+        return prefix, suffix
+
+    def _load_audio(
+        self, value: Any, sampling_rate: int | None, base_dir=None
+    ) -> Tensor:
+        source_rate = sampling_rate
+        if isinstance(value, (str, Path)):
+            from .audio_utils import load_audio
+
+            if str(value).lower().startswith(("http://", "https://")):
+                # load_audio would fetch it; this module reads local files only
+                raise ValueError("reference audio must be a local file, not a URL")
+
+            array, source_rate = load_audio(str(value), base_dir=base_dir)
+            audio = torch.from_numpy(np.asarray(array, dtype=np.float32).mean(axis=0))
+        else:
+            if isinstance(value, dict):
+                source_rate = value.get("sampling_rate", source_rate)
+                value = value.get("array")
+            if (
+                isinstance(value, (tuple, list))
+                and len(value) == 2
+                and np.isscalar(value[1])
+            ):
+                value, source_rate = value
+            audio = torch.as_tensor(np.asarray(value), dtype=torch.float32)
+            if audio.ndim == 2:
+                audio = audio.mean(dim=0)
+            if audio.ndim != 1:
+                raise ValueError(
+                    "reference audio must be mono or channels-first, got "
+                    f"{tuple(audio.shape)}"
+                )
+        if audio.numel() == 0:
+            raise ValueError("reference audio must not be empty")
+        if source_rate is None:
+            raise ValueError("sampling_rate is required for reference audio arrays")
+        if int(source_rate) != self.audio_sampling_rate:
+            from ..dsp import resample_waveform
+
+            resampled = resample_waveform(
+                audio.numpy()[None, :], int(source_rate), self.audio_sampling_rate
+            )
+            audio = torch.from_numpy(np.asarray(resampled, dtype=np.float32)[0])
+        return audio.contiguous()
+
+    def __call__(
+        self,
+        text: str | Sequence[str],
+        reference_text: str | Sequence[str] | None = None,
+        reference_audio: Any = None,
+        sampling_rate: int | Sequence[int] | None = None,
+        base_dir=None,
+    ) -> dict[str, Tensor]:
+        """generate()'s keyword inputs, as tensors.
+
+        reference_audio is a path (read with audio_utils.load_audio, checked
+        against base_dir), a (samples,) or (channels, samples) array with
+        sampling_rate, an (array, rate) pair or a {"array", "sampling_rate"}
+        dict; it is mixed to mono and resampled to the codec's rate.
+        """
+        texts = [text] if isinstance(text, str) else list(text)
+        if not texts:
+            raise ValueError("text batch must not be empty")
+        batch_size = len(texts)
+        ref_texts = _as_list(reference_text, batch_size, "reference_text")
+        has_reference = reference_audio is not None
+
+        prefix_rows, suffix_rows = zip(
+            *[
+                self._prompt_segments(item, ref_texts[idx], has_reference)
+                for idx, item in enumerate(texts)
+            ]
+        )
+        prefix_ids, prefix_mask = _pad_1d(list(prefix_rows), self.pad_token_id)
+        suffix_ids, suffix_mask = _pad_1d(list(suffix_rows), self.pad_token_id)
+        data: dict[str, Tensor] = {
+            "prefix_input_ids": prefix_ids,
+            "prefix_attention_mask": prefix_mask,
+            "suffix_input_ids": suffix_ids,
+            "suffix_attention_mask": suffix_mask,
+        }
+
+        if reference_audio is not None:
+            audio_items = _as_list(reference_audio, batch_size, "reference_audio")
+            rate_items = _as_list(sampling_rate, batch_size, "sampling_rate")
+            loaded_audio = [
+                self._load_audio(item, rate_items[idx], base_dir)
+                for idx, item in enumerate(audio_items)
+            ]
+            max_samples = max(item.numel() for item in loaded_audio)
+            padded_audio = torch.zeros(
+                (batch_size, 1, max_samples), dtype=torch.float32
+            )
+            lengths = torch.empty(batch_size, dtype=torch.long)
+            for idx, audio in enumerate(loaded_audio):
+                lengths[idx] = audio.numel()
+                padded_audio[idx, 0, : audio.numel()] = audio
+            data["reference_audio_values"] = padded_audio
+            data["reference_audio_lengths"] = lengths
+
+        return data
+
+
+__all__ = [
+    "CODEC_FILE",
+    "CONFIG_FILE",
+    "GENERATION_CONFIG_FILE",
+    "MODEL_FILES",
+    "REPO_ID",
+    "REVISION",
+    "TOKENIZER_FILE",
+    "WEIGHTS_FILE",
+    "ArkttsCodec",
+    "ArkttsConfig",
+    "ArkttsGenerateOutput",
+    "ArkttsModel",
+    "ArkttsModelOutput",
+    "ArkttsProcessor",
+    "load_codec_state",
+    "load_model",
+    "load_tokenizer",
+]
diff --git a/tests/test_audio8_tts_model.py b/tests/test_audio8_tts_model.py
new file mode 100644
index 00000000..7e6480da
--- /dev/null
+++ b/tests/test_audio8_tts_model.py
@@ -0,0 +1,362 @@
+"""The vendored Audio8-TTS model module (#1120): a tiny random-config model
+runs end to end on CPU, the processor builds its prompt inputs, and the
+module loads only from local files - codec.pth with weights_only=True."""
+
+import json
+import re
+import wave
+from pathlib import Path
+
+import numpy as np
+import pytest
+import torch
+
+from dw.tasks import audio8_tts_model as a8
+
+MODULE_PATH = Path(a8.__file__)
+
+# semantic ids sit at the top of the vocabulary like the real model's;
+# eos and pad are ordinary text ids below them
+TINY = dict(
+    vocab_size=64,
+    dim=32,
+    n_layer=2,
+    n_head=4,
+    n_local_heads=2,
+    head_dim=8,
+    intermediate_size=64,
+    max_seq_len=128,
+    codebook_size=16,
+    num_codebooks=10,
+    semantic_begin_id=40,
+    semantic_end_id=55,
+    n_fast_layer=1,
+    fast_dim=32,
+    fast_n_head=4,
+    fast_n_local_heads=2,
+    fast_head_dim=8,
+    fast_intermediate_size=64,
+    eos_token_id=2,
+    pad_token_id=0,
+    codec_encoder_dim=4,
+    codec_encoder_transformer_layers=1,
+    codec_latent_dim=64,
+    codec_decoder_dim=32,
+    codec_pre_n_layer=1,
+    codec_pre_n_head=1,
+    codec_pre_intermediate_size=64,
+    codec_post_n_layer=1,
+    codec_post_n_head=1,
+    codec_post_n_local_heads=1,
+    codec_post_intermediate_size=64,
+    codec_residual_codebook_size=8,
+    codec_codebook_dim=4,
+)
+
+LEGACY_PROJECTION = re.compile(r"quantizers\.\d+\.(in_proj|out_proj)\.weight$")
+
+
+def tiny_config(**overrides):
+    return a8.ArkttsConfig(**{**TINY, **overrides})
+
+
+def legacy_codec_state(codec):
+    """The codec's state as the checkpoint stores it: quantizer projections as
+    legacy weight_norm g/v pairs, so loading goes through the fold."""
+    state = {}
+    for key, value in codec.state_dict().items():
+        if LEGACY_PROJECTION.search(key):
+            norm = value.norm(dim=(1, 2), keepdim=True)
+            state[f"{key}_g"] = norm.clone()
+            state[f"{key}_v"] = value.clone()
+        else:
+            state[key] = value.clone()
+    return state
+
+
+@pytest.fixture
+def tiny_files(tmp_path):
+    torch.manual_seed(0)
+    config = tiny_config()
+    model = a8.ArkttsModel(config)
+    codec = a8.ArkttsCodec(config)
+    from safetensors.torch import save_file
+
+    weights = tmp_path / a8.WEIGHTS_FILE
+    save_file({k: v.contiguous() for k, v in model.state_dict().items()}, weights)
+    codec_path = tmp_path / a8.CODEC_FILE
+    torch.save(legacy_codec_state(codec), codec_path)
+    config_path = tmp_path / a8.CONFIG_FILE
+    config_path.write_text(
+        json.dumps({**TINY, "architectures": ["ArkttsModel"], "dtype": "bfloat16"})
+    )
+    generation_path = tmp_path / a8.GENERATION_CONFIG_FILE
+    generation_path.write_text(json.dumps({"max_new_tokens": 4, "do_sample": False}))
+    return {
+        "model": model,
+        "codec": codec,
+        "config": config_path,
+        "weights": weights,
+        "codec_path": codec_path,
+        "generation": generation_path,
+    }
+
+
+class NoEos:
+    """A logits processor that keeps a random model from stopping at once."""
+
+    def __init__(self, eos):
+        self.eos = eos
+
+    def __call__(self, input_ids, scores):
+        scores = scores.clone()
+        scores[:, self.eos] = float("-inf")
+        return scores
+
+
+def text_prompt(config, length=6, batch=1):
+    ids = torch.zeros((batch, config.num_codebooks + 1, length), dtype=torch.long)
+    ids[:, 0] = torch.arange(3, 3 + length)
+    return ids
+
+
+def test_tiny_model_generates_and_decodes_on_cpu(tiny_files):
+    model = a8.load_model(
+        tiny_files["config"],
+        tiny_files["weights"],
+        tiny_files["codec_path"],
+        tiny_files["generation"],
+        device="cpu",
+        dtype=torch.float32,
+    )
+    config = model.config
+    generator = torch.Generator().manual_seed(1)
+    codes = model.generate(
+        input_ids=text_prompt(config),
+        max_new_tokens=5,
+        do_sample=True,
+        logits_processor=[NoEos(config.eos_token_id)],
+        generator=generator,
+    )
+    assert codes.shape == (1, config.num_codebooks, 5)
+    assert int(codes.min()) >= 0
+    assert int(codes[:, 0].max()) < config.codebook_size
+    assert int(codes[:, 1:].max()) < config.codebook_size
+
+    waveforms, lengths = model.decode_audio(codes)
+    assert waveforms.dtype == torch.float32
+    assert waveforms.shape == (1, 5 * a8.ArkttsCodec.frame_length)
+    assert lengths.tolist() == [5 * a8.ArkttsCodec.frame_length]
+    assert config.codec_sample_rate == 44100
+    assert torch.isfinite(waveforms).all()
+    # the KV caches do not outlive the call on a model kept between jobs
+    assert all(layer.attention.kv_cache is None for layer in model.layers)
+
+
+def test_generation_config_file_sets_the_defaults(tiny_files):
+    model = a8.load_model(
+        tiny_files["config"],
+        tiny_files["weights"],
+        tiny_files["codec_path"],
+        tiny_files["generation"],
+        dtype=torch.float32,
+    )
+    output = model.generate(
+        input_ids=text_prompt(model.config),
+        logits_processor=[NoEos(model.config.eos_token_id)],
+        return_dict_in_generate=True,
+    )
+    # generation_config.json's max_new_tokens=4, greedy
+    assert output.codes.shape[-1] == 4
+    assert output.code_lengths.tolist() == [4]
+
+
+def test_stopping_criteria_end_generation(tiny_files):
+    model = a8.load_model(
+        tiny_files["config"],
+        tiny_files["weights"],
+        tiny_files["codec_path"],
+        dtype=torch.float32,
+    )
+    calls = []
+
+    def stop_after_two(history, scores):
+        calls.append(history.shape[-1])
+        return len(calls) >= 2
+
+    codes = model.generate(
+        input_ids=text_prompt(model.config),
+        max_new_tokens=8,
+        do_sample=False,
+        logits_processor=[NoEos(model.config.eos_token_id)],
+        stopping_criteria=[stop_after_two],
+    )
+    assert codes.shape[-1] == 2
+
+
+def test_load_model_matches_the_saved_weights(tiny_files):
+    source = tiny_files["model"].eval()
+    loaded = a8.load_model(
+        tiny_files["config"],
+        tiny_files["weights"],
+        tiny_files["codec_path"],
+        dtype=torch.float32,
+    )
+    ids = text_prompt(source.config)
+    with torch.no_grad():
+        expected = source(ids).logits
+        actual = loaded(ids).logits
+    assert torch.allclose(expected, actual, atol=1e-5)
+    assert loaded.freqs_cis.device.type == "cpu"
+    assert loaded.freqs_cis.shape[0] == source.config.max_seq_len
+
+
+def test_codec_loads_with_weights_only(tiny_files, monkeypatch):
+    seen = []
+    real_load = torch.load
+
+    def spy(*args, **kwargs):
+        seen.append(kwargs)
+        return real_load(*args, **kwargs)
+
+    monkeypatch.setattr(a8.torch, "load", spy)
+    model = a8.ArkttsModel(tiny_config(), codec_path=tiny_files["codec_path"])
+    model.load_codec()
+    assert seen and all(call.get("weights_only") is True for call in seen)
+
+
+def test_legacy_weight_norm_folds_to_the_same_projection():
+    torch.manual_seed(0)
+    legacy = torch.nn.utils.weight_norm(torch.nn.Conv1d(16, 4, kernel_size=1))
+    with torch.no_grad():
+        legacy.weight_g.mul_(torch.rand_like(legacy.weight_g) + 0.5)
+    state = {f"in_proj.{k}": v for k, v in legacy.state_dict().items()}
+    folded = a8._fold_legacy_weight_norm(state)
+    assert set(folded) == {"in_proj.weight", "in_proj.bias"}
+    plain = torch.nn.Conv1d(16, 4, kernel_size=1)
+    plain.load_state_dict(
+        {k.removeprefix("in_proj."): v for k, v in folded.items()}, strict=True
+    )
+    x = torch.randn(2, 16, 7)
+    with torch.no_grad():
+        assert torch.allclose(legacy(x), plain(x), atol=1e-6)
+
+
+def test_codec_round_trip_keeps_the_frame_grid(tiny_files):
+    model = a8.ArkttsModel(tiny_config(), codec_path=tiny_files["codec_path"])
+    audio = torch.randn(1, 1, 3 * a8.ArkttsCodec.frame_length - 100) * 0.1
+    codes, lengths = model.encode_audio(audio)
+    assert codes.shape == (1, 10, 3)
+    assert lengths.tolist() == [3]
+    waveforms, _ = model.decode_audio(codes)
+    assert waveforms.shape[-1] == 3 * a8.ArkttsCodec.frame_length
+
+
+def test_default_config_is_the_released_checkpoint():
+    config = a8.ArkttsConfig()
+    with torch.device("meta"):
+        codec = a8.ArkttsCodec(config)
+    assert config.dim == 896 and config.n_layer == 24 and config.num_codebooks == 10
+    assert codec.quantizer.semantic_quantizer.codebook_size == 4096
+    assert codec.quantizer.quantizer.n_codebooks == 9
+    assert codec.quantizer.quantizer.codebook_size == 1024
+    assert codec.decoder.model[0].conv.in_channels == 1024
+
+
+def test_module_has_no_hub_io():
+    source = MODULE_PATH.read_text(encoding="utf-8")
+    for name in ("from_pretrained", "hf_hub_download", "cached_file"):
+        assert name not in source, name
+    assert not re.search(r"^\s*(import|from)\s+(torchaudio|soundfile)\b", source, re.M)
+    assert "weights_only=True" in source
+    assert a8.REVISION == "1e857568bfd4f02931aca3988ee773a44d2d26d3"
+
+
+# --- processor ---------------------------------------------------------------
+
+
+class CharTokenizer:
+    """One id per character - enough to see the prompt's layout."""
+
+    def encode(self, text, add_special_tokens=True):
+        assert add_special_tokens is False
+        return [ord(ch) % 1000 + 1 for ch in text]
+
+
+def decode(ids):
+    return "".join(chr(i - 1) for i in ids.tolist())
+
+
+def make_processor():
+    return a8.ArkttsProcessor.for_model(CharTokenizer(), a8.ArkttsConfig())
+
+
+def test_processor_builds_a_text_only_prompt():
+    data = make_processor()("  hello   world ")
+    assert set(data) == {
+        "prefix_input_ids",
+        "prefix_attention_mask",
+        "suffix_input_ids",
+        "suffix_attention_mask",
+    }
+    prompt = decode(data["prefix_input_ids"][0])
+    assert prompt == (
+        "<|im_start|>system\nconvert the provided text to speech<|im_end|>\n"
+        "<|im_start|>user\nhello world<|im_end|>\n<|im_start|>assistant\n<|voice|>"
+    )
+    assert data["suffix_input_ids"].shape == (1, 0)
+    assert data["prefix_attention_mask"].all()
+
+
+def test_processor_builds_a_reference_prompt_and_resamples():
+    processor = make_processor()
+    audio = np.sin(np.linspace(0, 200, 22050)).astype(np.float32)
+    data = processor(
+        "say this",
+        reference_text="the reference",
+        reference_audio=np.stack([audio, audio]),
+        sampling_rate=22050,
+    )
+    prefix = decode(data["prefix_input_ids"][0])
+    assert prefix.endswith("<|speaker:0|>the reference\n\nSpeech:\n")
+    assert decode(data["suffix_input_ids"][0]).startswith("<|im_end|>\n")
+    values = data["reference_audio_values"]
+    assert values.shape[:2] == (1, 1)
+    assert abs(values.shape[-1] - 44100) <= 64
+    assert data["reference_audio_lengths"].tolist() == [values.shape[-1]]
+
+
+def test_processor_requires_reference_text_with_audio():
+    with pytest.raises(ValueError, match="reference_text"):
+        make_processor()("hi", reference_audio=np.ones(100), sampling_rate=44100)
+
+
+def test_processor_reads_a_local_path_and_refuses_a_url(tmp_path):
+    path = tmp_path / "voice.wav"
+    with wave.open(str(path), "w") as handle:
+        handle.setnchannels(1)
+        handle.setsampwidth(2)
+        handle.setframerate(44100)
+        handle.writeframes(b"\x10\x00" * 4410)
+    data = make_processor()(
+        "hi", reference_text="ref", reference_audio=str(path), base_dir=str(tmp_path)
+    )
+    assert data["reference_audio_lengths"].tolist() == [4410]
+    with pytest.raises(ValueError, match="local file"):
+        make_processor()(
+            "hi", reference_text="ref", reference_audio="https://example.com/a.wav"
+        )
+
+
+def test_load_tokenizer_reads_a_local_tokenizer_json(tmp_path):
+    from tokenizers import Tokenizer, models, pre_tokenizers
+
+    vocab = {"[UNK]": 0, "hello": 1, "world": 2}
+    tokenizer = Tokenizer(models.WordLevel(vocab, unk_token="[UNK]"))
+    tokenizer.pre_tokenizer = pre_tokenizers.Whitespace()
+    path = tmp_path / a8.TOKENIZER_FILE
+    tokenizer.save(str(path))
+    loaded = a8.load_tokenizer(path)
+    assert loaded.encode("hello world", add_special_tokens=False) == [1, 2]
+    data = a8.ArkttsProcessor.for_model(loaded, a8.ArkttsConfig())("hello")
+    assert data["prefix_input_ids"].dtype == torch.long

From 5748f4d2f9a4e3da152d81f526e8c607b2f0bc2d Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:12:36 -0600
Subject: [PATCH 087/125] fix(timing): #1119 - pin the first_pass_slow wording;
 docstring drops the withdrawn shape cause

The message rewording in 96bfd47c had no test: the existing one discards the
message. The docstring still explained the warm-up as a larger shape.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/pipeline_processors/timing.py | 11 +++++------
 tests/test_step_timing.py        | 15 +++++++++++++++
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/dw/pipeline_processors/timing.py b/dw/pipeline_processors/timing.py
index af437a8f..75fc6b36 100644
--- a/dw/pipeline_processors/timing.py
+++ b/dw/pipeline_processors/timing.py
@@ -155,12 +155,11 @@ def _warn_on_slow_first_pass(self, segment):
         The cause is unknown (#1119: it fired on an equal-shape second entry, and
         #924's rerun did not reproduce it), so the message states none.
 
-        The pipeline is loaded, so the minutes are not a load. A later entry
-        that runs the cached pipeline at a larger shape (more frames) pays a
-        one-off warm-up on its first pass - re-allocation, offload buffers,
-        kernels meeting a new shape - and without a word the consumer sees only
-        a `phase_stall` (#924). Judged at the second pass interval, when a
-        steady pass is known."""
+        The pipeline is loaded, so the minutes are not a load. The stall has
+        followed a later entry at a larger shape (#924) and one at the same
+        shape (#1119), and the exact rerun of each ran at the steady rate.
+        Without a word the consumer sees only a `phase_stall`. Judged at the
+        second pass interval, when a steady pass is known."""
         passes = segment.pass_ends
         if (
             len(passes) != 3
diff --git a/tests/test_step_timing.py b/tests/test_step_timing.py
index 460adcae..e74fc596 100644
--- a/tests/test_step_timing.py
+++ b/tests/test_step_timing.py
@@ -621,6 +621,21 @@ def test_a_cached_pipeline_whose_first_pass_dwarfs_the_rest_warns_once(monkeypat
     assert warnings[0]["pass_s"] == 37.0
 
 
+def test_the_slow_first_pass_warning_names_no_cause(monkeypatch):
+    """#1119: it fired on an equal-shape entry, so the message must not
+    claim a larger shape as the cause."""
+    messages = []
+    monkeypatch.setattr(
+        timing_module, "emit_warning", lambda message, **data: messages.append(message)
+    )
+    clock, timer = new_timer()
+    _passes(clock, timer, True, 164.0, 22.0)
+    assert len(messages) == 1
+    assert "cause is not identified" in messages[0]
+    assert "typically" not in messages[0]
+    assert "reordering entries by size is not a known remedy" in messages[0]
+
+
 @pytest.mark.parametrize(
     "cached, first, steady",
     [(True, 29.0, 28.4), (True, 60.0, 37.0), (False, 202.0, 37.0)],

From e8782f13a14ad92de7957cf8c04d42ef589cb9ec Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:15:51 -0600
Subject: [PATCH 088/125] fix(ui): minimatch 11.0.3 for eslint and
 typescript-eslint (GHSA-g3hv-75wg-m249)

Dependabot alert #103: minimatch < 11.0.1, globparts amplification DoS.
There is no patched 10.x, and eslint, @eslint/config-array and
@typescript-eslint/typescript-estree all declare ^10, so the fix is an
override on those three. None use the APIs 11.0 removed (makeRe, regexp,
AST, matchOne). redocly's minimatch 5.1.9 stays: it predates the vulnerable
firstPhasePreProcess path.

lint (226 files, same as before), check, 700 vitest tests and build pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 ui/package-lock.json | 16 ++++++++++++----
 ui/package.json      |  9 +++++++++
 2 files changed, 21 insertions(+), 4 deletions(-)

diff --git a/ui/package-lock.json b/ui/package-lock.json
index 020afbdc..9db3db95 100644
--- a/ui/package-lock.json
+++ b/ui/package-lock.json
@@ -539,6 +539,13 @@
         "@swc/helpers": "^0.5.0"
       }
     },
+    "node_modules/@isaacs/nonrecursive-glob-match": {
+      "version": "1.0.3",
+      "resolved": "https://registry.npmjs.org/@isaacs/nonrecursive-glob-match/-/nonrecursive-glob-match-1.0.3.tgz",
+      "integrity": "sha512-SI7kyKHq4XXDRozw+r9GlRZkia1ZkFrpLW98r2IC2Bpr8YkFGE3fvjzmxCG0x78A++69HmDNrDvSMYBZmHGpKA==",
+      "dev": true,
+      "license": "BlueOak-1.0.0"
+    },
     "node_modules/@jridgewell/gen-mapping": {
       "version": "0.3.13",
       "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz",
@@ -2923,13 +2930,14 @@
       }
     },
     "node_modules/minimatch": {
-      "version": "10.2.6",
-      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz",
-      "integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==",
+      "version": "11.0.3",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-11.0.3.tgz",
+      "integrity": "sha512-iny/40PEGkNJQ5/Pv6z3nm6FbRAby32GeZRjCUJk2WnNDbgPSTcdI+DDvLqsgBdD4cD5sMtMheqPPnehCCa8Nw==",
       "dev": true,
       "license": "BlueOak-1.0.0",
       "dependencies": {
-        "brace-expansion": "^5.0.8"
+        "@isaacs/nonrecursive-glob-match": "^1.0.3",
+        "brace-expansion": "^5.0.12"
       },
       "engines": {
         "node": "18 || 20 || >=22"
diff --git a/ui/package.json b/ui/package.json
index 256d261c..76338f5b 100644
--- a/ui/package.json
+++ b/ui/package.json
@@ -58,6 +58,15 @@
     },
     "openapi-typescript": {
       "typescript": "$typescript"
+    },
+    "eslint": {
+      "minimatch": "^11.0.3"
+    },
+    "@eslint/config-array": {
+      "minimatch": "^11.0.3"
+    },
+    "@typescript-eslint/typescript-estree": {
+      "minimatch": "^11.0.3"
     }
   }
 }

From 957a7c539e2e1fc485af7d5e48b370105b27ae62 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:28:12 -0600
Subject: [PATCH 089/125] feat(plugin): #1125 - beat authoring and the beat
 review in script-to-video and series-episodes

Shot sheet gains `beat` and `must_not`; "Run and judge" points to the new
references/beat-review.md before the keep; series-episodes points to it.
Pins in tests/test_plugin_skills.py, including a 1 KB size margin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 plugins/dw/skills/script-to-video/SKILL.md    |  6 ++
 .../script-to-video/references/beat-review.md | 80 +++++++++++++++++++
 plugins/dw/skills/series-episodes/SKILL.md    |  3 +
 tests/test_plugin_skills.py                   | 64 +++++++++++++++
 4 files changed, 153 insertions(+)
 create mode 100644 plugins/dw/skills/script-to-video/references/beat-review.md

diff --git a/plugins/dw/skills/script-to-video/SKILL.md b/plugins/dw/skills/script-to-video/SKILL.md
index 3633938e..b3f1c9fb 100644
--- a/plugins/dw/skills/script-to-video/SKILL.md
+++ b/plugins/dw/skills/script-to-video/SKILL.md
@@ -35,6 +35,10 @@ Fill in this shape before writing any prompt:
   stands where, what is held, at frame one) and `ending_state` (the same at
   the last frame). A shot's `opening_state` is the `ending_state` of its
   **source**, so the cut between them is written down rather than hoped for.
+- **Per shot, `beat`** (one visible state a single frame can show) and
+  **`must_not`** (a short list of physically or story-impossible things to
+  rule out: extra limbs, text in frame, the reference portrait itself).
+  `references/beat-review.md` has the rules for writing one.
 - **Per shot, optional `join`**: `continue` (the default; its source is the
   shot before), `cut` (opens fresh), `cutaway` (an insert: the shot after it
   takes the shot before it as source) or `lead_in` (its last frame is the
@@ -126,6 +130,8 @@ joined by `templates/assemble-and-score`). Never splice a re-rolled segment
 in with `concat_videos`: that join is recorded `hard_cut`, so
 `seam_frame_jump` stops checking it. A seam re-roll counts against the
 shot's budget below.
+Before the keep, run the beat review in `references/beat-review.md` on
+the shot's `get_output_frames` frames.
 Give each shot a budget of three failed attempts, then stop and ask the user
 rather than spending more. Each shot's files are organized by `subfolder` - typically `final`
 for the deliverable video or `intermediate` for test frames; read the
diff --git a/plugins/dw/skills/script-to-video/references/beat-review.md b/plugins/dw/skills/script-to-video/references/beat-review.md
new file mode 100644
index 00000000..ff458595
--- /dev/null
+++ b/plugins/dw/skills/script-to-video/references/beat-review.md
@@ -0,0 +1,80 @@
+# Beats and the beat review
+
+A shot can pass every automated check and still not show what the story
+needs: the bear poking the wall instead of shouldering the door. `check-script`
+confirms each line is *heard*; this review is how you confirm each beat is
+*seen*. It runs on the tools you already have (`get_output_frames`,
+`get_output_image`) and adds no engine mechanism.
+
+## Writing a beat
+
+A shot sheet's `beat` names **who, doing what, to what, and where, in a state
+one frame proves**. Someone shown a single still, with no script, could say
+yes or no to it. `must_not` lists the few things that would make the take
+wrong however good it looks: a horse behind the wagon it pulls, extra limbs
+or heads, text in frame, the reference portrait itself pasted in.
+
+Four kinds of wording are banned in a beat. They are fine in the generation
+prompt, which describes motion and mood; the beat is what you judge against,
+and a frame cannot show any of these:
+
+- **Motion over time** ("steadily widening", "rushes toward", "keeps
+  rising"). Rewrite: "the bear rushes the door" -> "the door half open, the
+  bear's shoulder against it".
+- **Intent** ("trying to"). Rewrite: "the girl tries to reach the shelf" ->
+  "the girl on tiptoe, one hand on the top shelf's edge".
+- **Off-screen facts** (what happened before, who is behind the door,
+  what the character knows). Rewrite: "the captain, having heard the news,
+  in the cabin" -> "the captain seated at the cabin table, a letter open in
+  his hand".
+- **Emotion words** ("celebrating", "alarmed"). Rewrite: "the crew
+  celebrating" -> "the crew on deck, arms raised, hats in the air".
+
+Most false fails come from a beat a frame could never satisfy, not from a
+bad take: in story-forge, 34 of 44 false fails traced back to how the beat
+was worded.
+
+## Before anything renders
+
+Cross-check the shot sheet: every shot id in the edit list has a `beat`, and
+every `beat` belongs to a shot in the edit list. Do not render while an
+edit-list shot has no beat; write it first, or ask.
+
+## The review, before the keep
+
+1. **Pull frames** with `get_output_frames`: **3 evenly spaced** across a
+   clip by default; **5 only when the first verdict is split**. For a still,
+   the image itself (`get_output_image`).
+2. **Describe blind, before the verdict.** Write a plain description of each
+   frame (who is there, where, what they hold, what is touching what) before
+   re-reading the beat. Where the client can start a fresh subagent, hand it
+   the frames without the beat and take its descriptions instead: you wrote
+   the beat, so you will see it if you look for it.
+3. **A verdict per frame** against `beat` and `must_not`, from the
+   description. The shot passes on a **majority** of frames (2 of 3, 3 of 5),
+   not unanimity, so one frame mid-motion does not fail a good take.
+4. **Exactly one reason per rejected frame**, from this list:
+   - `beat_not_shown`: the visible state the beat names is not in frame;
+   - `must_not_present`: something on the `must_not` list is;
+   - `identity_drift`: a cast member no longer reads as their reference;
+   - `text_in_frame`: legible or pseudo text the shot did not ask for;
+   - `reference_leak`: the reference portrait (its framing, pose or
+     backdrop) shows through.
+
+   A wrong reason teaches the wrong correction, so pick the one that, fixed,
+   would have passed the frame.
+5. **One concrete correction.** A failing shot yields one change to the next
+   attempt's prompt that answers its reason ("the bear's shoulder pressed
+   flat against the door, the door half open"), not a list. The rerun counts
+   against the shot's three-attempt budget in `SKILL.md`'s "Run and judge";
+   after three, stop and ask.
+
+## Audit the auditor
+
+When a human overrules a beat verdict (keeps a take the review failed, or
+rejects one it passed), record it in the workspace note
+(`set_note("workspace:<name>", ...)`, appending to the note already there
+rather than replacing it): the shot, the beat, the verdict, the reason
+given, and why it was wrong. The
+rule that misfired is then visible the next time the series or script is
+picked up, rather than repeated.
diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 2d336403..7c3b68c5 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -165,6 +165,9 @@ template's own name - read off the run's manifest (`get_job`) rather than
 guessed. Or, if the shot should outlive its run directory the way the cast
 does, `keep_output` it and reference the resulting `asset:` instead.
 
+Before keeping each episode shot, run `dw:script-to-video`'s beat review
+(`script-to-video/references/beat-review.md`) on it.
+
 Beyond `minimax-h3`'s own judging checklist (a character that changes
 between shots, a portrait imposing its framing, a voice without affect):
 watch two episodes back to back and check the cast reads as the same
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 41b1ac4f..6f9a2fdc 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -890,6 +890,70 @@ def test_the_frame_step_is_a_real_task_step(self, tmp_path):
         workflow_from_file(str(path), str(tmp_path)).validate()
 
 
+SCRIPT_BEATS = os.path.join(
+    os.path.dirname(SCRIPT_SKILL), "references", "beat-review.md"
+)
+# What SKILL.md keeps free under SKILL_SIZE_LIMIT after the beat review moved
+# to a reference (#1125): an addition that eats it belongs in `references/`.
+SCRIPT_SKILL_MARGIN = 1024
+
+
+class TestScriptToVideoBeatReview:
+    """Beat authoring and the beat review (#1122 stage A): a beat a frame can
+    prove, judged blind on a majority of frames, one reason per rejection."""
+
+    def test_the_shot_sheet_names_beat_and_must_not(self):
+        body = skill_body(SCRIPT_SKILL)
+        assert "`beat`" in body and "`must_not`" in body
+        assert body.index("`ending_state`") < body.index("`beat`")
+        assert body.index("`beat`") < body.index("## 3.")
+
+    def test_run_and_judge_keeps_its_tools_and_points_to_the_review(self):
+        body = skill_body(SCRIPT_SKILL)
+        judge = body[body.index("## Run and judge") : body.index("## 6.")]
+        assert "get_output_frames" in judge
+        assert "`references/beat-review.md`" in judge
+        assert "adds no new mechanism" in body
+
+    def test_the_review_names_its_rules(self):
+        text = open(SCRIPT_BEATS, encoding="utf-8").read()
+        assert "**majority**" in text
+        for reason in (
+            "`beat_not_shown`",
+            "`must_not_present`",
+            "`identity_drift`",
+            "`text_in_frame`",
+            "`reference_leak`",
+        ):
+            assert reason in text
+        for banned in (
+            "Motion over time",
+            "Intent",
+            "Off-screen facts",
+            "Emotion words",
+        ):
+            assert f"**{banned}**" in text
+        assert "**3 evenly spaced**" in text and "**5 only when" in text
+        assert text.index("Describe blind, before the verdict") < text.index(
+            "A verdict per frame"
+        )
+        assert "three-attempt budget" in text
+        assert "Do not render while an\nedit-list shot has no beat" in text
+        assert "## Audit the auditor" in text and "workspace note" in text
+
+    def test_series_episodes_points_to_the_review(self):
+        body = skill_body(SERIES_SKILL)
+        assert "`script-to-video/references/beat-review.md`" in body
+        assert "beat_not_shown" not in body  # a pointer, not a restatement
+
+    def test_script_to_video_keeps_headroom_under_the_cap(self):
+        size = len(skill_body(SCRIPT_SKILL).encode("utf-8"))
+        assert size <= SKILL_SIZE_LIMIT - SCRIPT_SKILL_MARGIN, (
+            f"{SCRIPT_SKILL} is {size} bytes, within {SCRIPT_SKILL_MARGIN} of "
+            f"the {SKILL_SIZE_LIMIT}-byte cap: move detail to references/"
+        )
+
+
 SERIES_SKILL = os.path.join(PLUGIN_DIR, "skills", "series-episodes", "SKILL.md")
 SERIES_LOOK = os.path.join(os.path.dirname(SERIES_SKILL), "references", "look.md")
 

From 2c86a230aff52a53a8bb8c516fbfa1871ce40dd3 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:47:17 -0600
Subject: [PATCH 090/125] feat(tasks): #1121 - Audio8-TTS branch in
 generate_speech, voice-clone template

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/server/catalog_shape.py               |  11 +-
 dw/tasks/speech_generation.py            | 256 +++++++++++++++++++-
 tests/test_catalog_shape.py              |  32 +++
 tests/test_catalog_structure.py          |   6 +-
 tests/test_security_trust_gate.py        |  20 ++
 tests/test_speech_generation.py          | 296 +++++++++++++++++++++++
 tests/test_task_weights.py               |  28 +++
 workflows/templates/generate-speech.json |   2 +-
 workflows/templates/voice-clone.json     |  29 +++
 9 files changed, 671 insertions(+), 9 deletions(-)
 create mode 100644 workflows/templates/voice-clone.json

diff --git a/dw/server/catalog_shape.py b/dw/server/catalog_shape.py
index 6e78474e..7511da82 100644
--- a/dw/server/catalog_shape.py
+++ b/dw/server/catalog_shape.py
@@ -56,7 +56,16 @@
     {"last_frame", "last_segment", "last_image", "match_audio"}
 )
 _MEDIA_ARGUMENTS = frozenset(
-    {"image", "video", "audio", "mask_image", "urls", "videos", "clip"}
+    {
+        "image",
+        "video",
+        "audio",
+        "mask_image",
+        "urls",
+        "videos",
+        "clip",
+        "reference_audio",
+    }
 )
 _CUT_TASKS = frozenset({"concat_videos", "dissolve_videos", "join_windows"})
 # Components that exist only to synthesise a waveform. A video pipeline
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index 6cd5c5f8..a8c6c11b 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -17,18 +17,20 @@
 """
 
 import logging
+import math
 
 import torch
 from transformers import pipeline as hf_pipeline
 
-from .. import preferred_task_dtype
+from .. import get_device_type, preferred_task_dtype
 from ..dsp import as_channels_samples
 from ..media_types import AudioTrack
 from ..dsp import resample_waveform
 from .audio_utils import load_audio
 from ..trust import require_trusted_generate_arguments
+from . import audio8_tts_model as audio8
 from .model_cache import cached_model, hf_pipeline_placement
-from .weights import argument_or_default, repo_entries
+from .weights import argument_or_default, file_entries, repo_entries
 
 logger = logging.getLogger("dw")
 
@@ -47,6 +49,31 @@
 # part of extracting a voiceprint, not an approximation of one
 _SPEAKER_ENCODER_SAMPLE_RATE = 16000
 
+# Audio8-TTS (#1112) is a vendored architecture (audio8_tts_model), not a
+# transformers pipeline, so it gets its own branch; its identity is the
+# vendored module's constant. Its 2,048-position context holds the prompt
+# text, the reference's codec frames and the speech it generates, at the
+# codec's 44100 / 2048 = ~21.5 frames a second
+_AUDIO8_REFERENCE_ARGUMENTS = ("reference_audio", "reference_text")
+_AUDIO8_REFUSED_ARGUMENTS = ("speaker_embedding", "voice_preset", "messages")
+# A longer reference leaves too little of the context for the line (#1112 Q2)
+_AUDIO8_MAX_REFERENCE_SECONDS = 20.0
+# The estimate a line is refused on before anything loads: speech at ~14
+# characters a second, ~2.5 characters a prompt token (Cyrillic tokenizes
+# denser than English, so this leans long), and the prompt's fixed chat
+# scaffolding. A line that still runs out of context is refused after
+# generation rather than returned cut off
+_AUDIO8_CHARS_PER_SECOND = 14.0
+_AUDIO8_CHARS_PER_TOKEN = 2.5
+_AUDIO8_PROMPT_OVERHEAD = 48
+# What the vendored generate() takes from generate_kwargs / forward_params
+_AUDIO8_GENERATION_KEYS = frozenset(
+    {"temperature", "top_p", "top_k", "do_sample", "max_new_tokens"}
+)
+# The architecture's defaults, which the pinned config.json matches - the fit
+# estimate runs before that file is fetched
+_AUDIO8_CONFIG = audio8.ArkttsConfig()
+
 
 def model_source(arguments):
     """The text-to-speech repo a generate_speech step loads."""
@@ -57,6 +84,14 @@ def required_weights(arguments):
     """The speech model's repo, plus speechbrain's speaker encoder when the
     step clones a voice from a `speaker_embedding` clip, for the plan
     (dw/tasks/weights.py)."""
+    if model_source(arguments) == audio8.REPO_ID:
+        # Every file at the pinned commit the vendored module was reviewed
+        # at - a repo entry cannot pin, and codec.pth is a pickle-format file
+        return [
+            entry
+            for filename in audio8.MODEL_FILES
+            for entry in file_entries(audio8.REPO_ID, filename, audio8.REVISION)
+        ]
     encoder = (
         _SPEAKER_ENCODER_MODEL if (arguments or {}).get("speaker_embedding") else None
     )
@@ -135,6 +170,188 @@ def _generation_settings(value, name):
     return value
 
 
+def _audio8_dtype(device):
+    # The checkpoint is bf16, which a 0.6B Qwen-style decoder keeps finite
+    # where fp16 may not; MPS and CPU run it in fp32 (fp16/bf16 NaN or crawl)
+    return torch.bfloat16 if get_device_type(device) == "cuda" else torch.float32
+
+
+def _check_audio8_arguments(model_name, kwargs):
+    """The argument refusals around the Audio8 branch, all raised before
+    anything loads - a kwargs task silently drops an argument it does not
+    read, so a misplaced one would otherwise run in the wrong voice."""
+    given = {name for name, value in kwargs.items() if value is not None}
+    if model_name != audio8.REPO_ID:
+        misplaced = [name for name in _AUDIO8_REFERENCE_ARGUMENTS if name in given]
+        if misplaced:
+            raise ValueError(
+                f"{model_name} takes no {' or '.join(map(repr, misplaced))} - "
+                f"only {audio8.REPO_ID} clones a voice from a reference clip "
+                "and its transcript. Drop it, or set model_name to that model"
+            )
+        return
+    refused = [name for name in _AUDIO8_REFUSED_ARGUMENTS if name in given]
+    if refused:
+        raise ValueError(
+            f"{audio8.REPO_ID} takes no {' or '.join(map(repr, refused))} - its "
+            "voice comes from 'reference_audio' with 'reference_text' (or its "
+            "default voice when neither is given), and it speaks plain 'text'"
+        )
+    has_audio = "reference_audio" in given
+    has_text = bool(kwargs.get("reference_text"))
+    if has_audio != has_text:
+        missing, present = (
+            ("reference_text", "reference_audio")
+            if has_audio
+            else ("reference_audio", "reference_text")
+        )
+        raise ValueError(
+            f"generate_speech: '{present}' needs '{missing}' - {audio8.REPO_ID} "
+            "clones a voice from a reference clip together with the words "
+            "spoken in it. Give both, or neither for the default voice"
+        )
+    if has_text and not isinstance(kwargs["reference_text"], str):
+        raise ValueError(
+            "generate_speech: 'reference_text' must be the transcript of the "
+            f"reference clip as a string, got {type(kwargs['reference_text']).__name__}"
+        )
+
+
+def _audio8_generation_kwargs(forward_params, generate_kwargs):
+    """The sampling settings the vendored generate() takes, merged; anything
+    else is refused by name rather than raised from inside a loaded model."""
+    settings = {**forward_params, **generate_kwargs}
+    unknown = sorted(set(settings) - _AUDIO8_GENERATION_KEYS)
+    if unknown:
+        raise ValueError(
+            f"{audio8.REPO_ID} takes no generation setting(s) {unknown} - it "
+            f"takes {sorted(_AUDIO8_GENERATION_KEYS)} in generate_kwargs"
+        )
+    return settings
+
+
+def _audio8_estimated_positions(text, reference_text, reference_seconds):
+    """How many of the context's positions a line is expected to take: the
+    prompt (scaffolding, both texts, the reference's frames) plus the frames
+    of the speech it generates."""
+    frame_rate = _AUDIO8_CONFIG.codec_sample_rate / _AUDIO8_CONFIG.codec_frame_size
+    text_chars = len(" ".join(text.split()))
+    reference_chars = len(" ".join((reference_text or "").split()))
+    prompt = (
+        _AUDIO8_PROMPT_OVERHEAD
+        + (text_chars + reference_chars) / _AUDIO8_CHARS_PER_TOKEN
+        + reference_seconds * frame_rate
+    )
+    speech = text_chars / _AUDIO8_CHARS_PER_SECOND * frame_rate
+    return int(math.ceil(prompt + speech))
+
+
+def _load_audio8(device, dtype):
+    """(model, processor) from the pinned files, fetched to the Hugging Face
+    cache here - the vendored module reads local paths only."""
+    from huggingface_hub import hf_hub_download
+
+    def load():
+        logger.info(f"Loading {audio8.REPO_ID} at {audio8.REVISION[:8]} on {device}")
+        paths = {
+            filename: hf_hub_download(
+                repo_id=audio8.REPO_ID, filename=filename, revision=audio8.REVISION
+            )
+            for filename in audio8.MODEL_FILES
+        }
+        model = audio8.load_model(
+            paths[audio8.CONFIG_FILE],
+            paths[audio8.WEIGHTS_FILE],
+            paths[audio8.CODEC_FILE],
+            generation_config_path=paths[audio8.GENERATION_CONFIG_FILE],
+            device=device,
+            dtype=dtype,
+        )
+        tokenizer = audio8.load_tokenizer(paths[audio8.TOKENIZER_FILE])
+        return model, audio8.ArkttsProcessor.for_model(tokenizer, model.config)
+
+    return cached_model(
+        ("speech_generation", audio8.REPO_ID, str(device), str(dtype), audio8.REVISION),
+        load,
+    )
+
+
+def _generate_audio8(text, device, seed, kwargs, settings):
+    """Speak `text` with Audio8-TTS, in the voice of reference_audio when one
+    is given; every refusal has been raised by the time this loads."""
+    if text is None:
+        raise ValueError(f"generate_speech: {audio8.REPO_ID} needs 'text'")
+    if not isinstance(text, str) or not text.strip():
+        raise ValueError("generate_speech: 'text' must be a non-empty string")
+    reference_audio = kwargs.get("reference_audio")
+    reference_text = kwargs.get("reference_text")
+
+    reference = None
+    reference_seconds = 0.0
+    if reference_audio is not None:
+        waveform, sample_rate = load_audio(reference_audio)
+        reference_seconds = waveform.shape[-1] / float(sample_rate)
+        if reference_seconds > _AUDIO8_MAX_REFERENCE_SECONDS:
+            raise ValueError(
+                f"generate_speech: 'reference_audio' is {reference_seconds:.1f} s; "
+                f"{audio8.REPO_ID} takes a reference of at most "
+                f"{_AUDIO8_MAX_REFERENCE_SECONDS:.0f} s (its context holds the "
+                "reference and the line together). Trim it with slice_audio - "
+                "5 to 10 s of clean speech is plenty"
+            )
+        reference = (waveform.mean(axis=0), int(sample_rate))
+
+    context = _AUDIO8_CONFIG.max_seq_len
+    estimated = _audio8_estimated_positions(text, reference_text, reference_seconds)
+    if estimated > context:
+        raise ValueError(
+            f"generate_speech: 'text' is too long for {audio8.REPO_ID} - it is "
+            f"estimated to need {estimated} of the model's {context} context "
+            "positions (prompt, reference and speech together, about 95 s in "
+            "all). Split the line into shorter generate_speech steps"
+            + (" or use a shorter reference" if reference is not None else "")
+        )
+
+    dtype = _audio8_dtype(device)
+    model, processor = _load_audio8(device, dtype)
+    if reference is None:
+        inputs = processor(text)
+    else:
+        inputs = processor(
+            text,
+            reference_text=reference_text,
+            reference_audio=reference[0],
+            sampling_rate=reference[1],
+        )
+    # Fill the context by default - the checkpoint's own 512-frame cap would
+    # end a line at ~24 s without saying so
+    settings = {"max_new_tokens": context, **settings}
+    logger.info(f"Speaking: {text[:100]}{'...' if len(text) > 100 else ''}")
+    # An explicit generator, not the global seed the pipelines here use: the
+    # codec builds lazily inside the first generate() that encodes a
+    # reference, and its init draws from the global RNG, so a globally seeded
+    # first take would differ from every later one
+    generator = (
+        torch.Generator(device=model.device).manual_seed(int(seed))
+        if seed is not None
+        else None
+    )
+    output = model.generate(
+        **inputs, return_dict_in_generate=True, generator=generator, **settings
+    )
+    if not bool(output.finished.all()):
+        raise ValueError(
+            f"generate_speech: {audio8.REPO_ID} ran out of room before the line "
+            "ended, so it is refused rather than returned cut off. Split the "
+            "line into shorter generate_speech steps"
+            + (" or use a shorter reference" if reference is not None else "")
+            + " (or raise generate_kwargs.max_new_tokens if you lowered it)"
+        )
+    waveforms, lengths = model.decode_audio(output.codes)
+    samples = waveforms[0, : int(lengths[0])].cpu().numpy()
+    return AudioTrack(as_channels_samples(samples), int(model.config.codec_sample_rate))
+
+
 def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     """Speak a line of text with a local text-to-speech model - any
     transformers text-to-speech checkpoint named by model_name. Three
@@ -143,7 +360,12 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     (facebook/mms-tts-eng and the other per-language mms-tts-* checkpoints;
     one voice, small and fast; a multi-speaker VITS takes speaker_id through
     forward_params) and SpeechT5 (microsoft/speecht5_tts; speaks in the
-    voice of a reference clip given as speaker_embedding).
+    voice of a reference clip given as speaker_embedding). Audio8-TTS
+    (Edge0/Audio8-TTS-Realistic-0.6b, pinned to one revision) is not a
+    transformers pipeline and runs through its own vendored loader: it speaks
+    44.1 kHz mono in the voice of a short reference clip given as
+    reference_audio with its transcript as reference_text, or in its default
+    voice when neither is given.
 
     Args:
         text: The line to speak. Mutually exclusive with messages - exactly
@@ -154,7 +376,8 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
             takes no such argument, so reproducing Bark (and any other
             sampling model here) means seeding the global RNG immediately
             before the call - unseeded when None, matching every other
-            unseeded task (#261).
+            unseeded task (#261). Audio8 takes it as an explicit
+            torch.Generator instead, so the same seed repeats the same take.
         **kwargs:
             messages: Chat-templated input for a model such as VibeVoice that
                 takes a conversation rather than a bare string - a list of
@@ -179,9 +402,24 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
                 VITS model's speaker instead takes a plain 'speaker_id' int,
                 which already reaches the model unchanged through
                 forward_params and needs no argument of its own.
+            reference_audio: Edge0/Audio8-TTS-Realistic-0.6b only - a clip of
+                the voice to clone (typically an 'asset:' reference), at most
+                20 s; 5-10 s of clean speech is plenty. Requires
+                reference_text. Refused on any other model, and refused
+                together with speaker_embedding, voice_preset or messages,
+                which Audio8 does not take. Clone only a voice you have
+                permission to use.
+            reference_text: Edge0/Audio8-TTS-Realistic-0.6b only - the exact
+                words spoken in reference_audio. Requires reference_audio
+                and is refused on any other model. Text plus reference must
+                fit the model's 2,048-position context (about 95 s of
+                prompt, reference and speech together); a line estimated not
+                to fit is refused before generation, never truncated.
             forward_params: Passed to the model's forward/generate call.
             generate_kwargs: Ad-hoc generation settings for a generative model -
-                temperature, do_sample and so on.
+                temperature, do_sample and so on. Audio8 takes temperature,
+                top_p, top_k, do_sample and max_new_tokens only (here or in
+                forward_params); anything else is refused by name.
 
     Returns:
         An AudioTrack holding the waveform, shaped (channels, samples), and the
@@ -189,7 +427,8 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
 
     Raises:
         ValueError: If the model reports no sample rate for what it generated,
-            or if text/messages are both given or neither is.
+            or if text/messages are both given or neither is, or for any of
+            the Audio8 refusals above - each raised before a model loads.
     """
     messages = kwargs.get("messages", None)
     if (text is None) == (messages is None):
@@ -212,6 +451,11 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     )
 
     model_name = model_source(kwargs)
+    _check_audio8_arguments(model_name, kwargs)
+    if model_name == audio8.REPO_ID:
+        settings = _audio8_generation_kwargs(forward_params, generate_kwargs)
+        return _generate_audio8(text, device, seed, kwargs, settings)
+
     voice_preset = kwargs.get("voice_preset", None)
     speaker_embedding = kwargs.get("speaker_embedding", None)
     dtype = preferred_task_dtype(device)
diff --git a/tests/test_catalog_shape.py b/tests/test_catalog_shape.py
index 65c80fcd..76053a2b 100644
--- a/tests/test_catalog_shape.py
+++ b/tests/test_catalog_shape.py
@@ -249,6 +249,38 @@ def test_text_only_is_text():
     assert derive_catalog_metadata(definition(step))["shape"] == "text"
 
 
+def test_a_voice_clone_reference_is_input_media():
+    # #1121: the voice-clone template's reference clip is a variable the
+    # caller must fill, so the listing says it needs input media
+    step = task_step(
+        "speak",
+        "generate_speech",
+        {
+            "text": "variable:text",
+            "model_name": "Edge0/Audio8-TTS-Realistic-0.6b",
+            "reference_audio": "variable:reference_audio",
+            "reference_text": "variable:reference_text",
+        },
+        "audio/wav",
+    )
+    meta = derive_catalog_metadata(definition(step))
+    assert meta["shape"] == "audio"
+    assert "needs-input-media" in meta["traits"]
+
+
+def test_the_voice_clone_template_needs_input_media():
+    import json
+    import os
+
+    path = os.path.join(
+        os.path.dirname(__file__), "..", "workflows", "templates", "voice-clone.json"
+    )
+    with open(path, encoding="utf-8") as handle:
+        meta = derive_catalog_metadata(json.load(handle))
+    assert meta["shape"] == "audio"
+    assert "needs-input-media" in meta["traits"]
+
+
 def test_processing_tasks_alone_are_utility():
     step = task_step("crop", "crop_square", {"image": "asset:a.png"}, "image/jpeg")
     meta = derive_catalog_metadata(definition(step))
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index e0606f18..decdf56b 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -117,6 +117,7 @@ def load(path):
         ["composes-workflows", "image-conditioned"],
     ),
     "workflows/templates/generate-speech.json": ("audio", ["has-audio"]),
+    "workflows/templates/voice-clone.json": ("audio", ["has-audio", "needs-input-media"]),
     "workflows/templates/assemble-and-score.json": ("sequence", ["needs-input-media"]),
     "workflows/templates/image-processors.json": ("utility", []),
 }
@@ -528,7 +529,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Re-measured at 12_344 after `ltx2/restore-colorize`'s description gained its
 # low-rate/portrait colour limit (#1064, stage #1114, 2026-10-31): its summary
 # did not change, so the budget stands.
-COMPACT_BUDGET = 12_400
+# Then to 12_480 for the `voice-clone` template (#1112, stage #1121,
+# 2026-11-01), measured at 12_436: one new entry, the catalog's only voice
+# clone from a reference clip and its transcript, with no cost block yet.
+COMPACT_BUDGET = 12_480
 FILTERED_BUDGET = 1_500
 
 
diff --git a/tests/test_security_trust_gate.py b/tests/test_security_trust_gate.py
index 3f25468e..72def866 100644
--- a/tests/test_security_trust_gate.py
+++ b/tests/test_security_trust_gate.py
@@ -878,6 +878,26 @@ def test_a_non_object_is_refused(self, monkeypatch, where):
         with pytest.raises(ValueError, match=f"{where} must be an object"):
             speech_generation.generate_speech("hello", device="cpu", **{where: "x"})
 
+    @pytest.mark.parametrize("where", ["generate_kwargs", "forward_params"])
+    def test_refused_before_audio8_loads(self, untrusted, no_network, monkeypatch, where):
+        """The Audio8 branch (#1121) sits behind the same gate: a workflow
+        naming the vendored model is refused 'trust_remote_code' before any
+        file is fetched, not handed to the branch's own key allowlist."""
+        from dw.tasks import speech_generation
+
+        loader = MagicMock()
+        monkeypatch.setattr(speech_generation, "_load_audio8", loader)
+        monkeypatch.setattr(speech_generation, "hf_pipeline", loader)
+        with pytest.raises(UntrustedWorkflowError, match="'trust_remote_code'.*trusted"):
+            speech_generation.generate_speech(
+                "hello",
+                device="cpu",
+                model_name=speech_generation.audio8.REPO_ID,
+                **{where: {"trust_remote_code": True}},
+            )
+        loader.assert_not_called()
+        assert list(no_network) == []
+
 
 def _probe_recorder(info):
     """A `probe=` callable that records every path it is asked about.
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 00b3e72e..3eefe078 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -462,3 +462,299 @@ def seed_for(self, arguments):
             handler(FakeTask(), {"text": "hi"}, {})
 
         mock_seed.assert_called_once_with(7)
+
+
+# --- Audio8-TTS (#1121) -------------------------------------------------------
+
+import json  # noqa: E402
+import wave  # noqa: E402
+from pathlib import Path  # noqa: E402
+
+import pytest  # noqa: E402
+
+from dw.tasks import audio8_tts_model as a8  # noqa: E402
+from dw.tasks import speech_generation as sg  # noqa: E402
+from dw.tasks.model_cache import clear_model_cache  # noqa: E402
+from tests.test_audio8_tts_model import TINY, legacy_codec_state  # noqa: E402
+
+AUDIO8 = a8.REPO_ID
+
+
+def write_wav(path, seconds, rate=22050):
+    with wave.open(str(path), "w") as handle:
+        handle.setnchannels(1)
+        handle.setsampwidth(2)
+        handle.setframerate(rate)
+        tone = (numpy.sin(numpy.linspace(0, 400 * seconds, int(rate * seconds))) * 8000)
+        handle.writeframes(tone.astype("<i2").tobytes())
+    return str(path)
+
+
+@pytest.fixture
+def never_loads(monkeypatch):
+    """Every way the task could load a model, each failing the test if hit."""
+    loaders = {
+        "_load_audio8": MagicMock(side_effect=AssertionError("Audio8 loaded")),
+        "hf_pipeline": MagicMock(side_effect=AssertionError("pipeline loaded")),
+    }
+    for name, mock in loaders.items():
+        monkeypatch.setattr(sg, name, mock)
+    yield loaders
+    for mock in loaders.values():
+        mock.assert_not_called()
+
+
+class TestAudio8Refusals:
+    """Each refusal is the task's own, raised before anything loads."""
+
+    @pytest.mark.parametrize("argument", ["reference_audio", "reference_text"])
+    def test_reference_arguments_are_refused_on_another_model(
+        self, never_loads, argument
+    ):
+        with pytest.raises(ValueError, match=f"takes no '{argument}'.*{AUDIO8}"):
+            generate_speech(
+                "hello", model_name="facebook/mms-tts-eng", **{argument: "x"}
+            )
+
+    def test_reference_arguments_are_refused_on_the_default_model(self, never_loads):
+        with pytest.raises(ValueError, match="takes no 'reference_audio'"):
+            generate_speech("hello", reference_audio="voice.wav", reference_text="hi")
+
+    @pytest.mark.parametrize("argument", ["speaker_embedding", "voice_preset"])
+    def test_other_voice_controls_are_refused_on_audio8(self, never_loads, argument):
+        with pytest.raises(ValueError, match=f"{AUDIO8} takes no '{argument}'"):
+            generate_speech("hello", model_name=AUDIO8, **{argument: "x"})
+
+    def test_messages_are_refused_on_audio8(self, never_loads):
+        with pytest.raises(ValueError, match=f"{AUDIO8} takes no 'messages'"):
+            generate_speech(
+                model_name=AUDIO8, messages=[{"role": "user", "content": "hi"}]
+            )
+
+    def test_reference_audio_needs_reference_text(self, never_loads):
+        with pytest.raises(ValueError, match="'reference_audio' needs 'reference_text'"):
+            generate_speech("hello", model_name=AUDIO8, reference_audio="voice.wav")
+
+    def test_an_empty_reference_text_counts_as_missing(self, never_loads):
+        with pytest.raises(ValueError, match="'reference_audio' needs 'reference_text'"):
+            generate_speech(
+                "hello", model_name=AUDIO8, reference_audio="v.wav", reference_text=""
+            )
+
+    def test_reference_text_needs_reference_audio(self, never_loads):
+        with pytest.raises(ValueError, match="'reference_text' needs 'reference_audio'"):
+            generate_speech("hello", model_name=AUDIO8, reference_text="hi there")
+
+    def test_a_reference_over_twenty_seconds_is_refused(self, never_loads, tmp_path):
+        clip = write_wav(tmp_path / "long.wav", 21.0)
+        with pytest.raises(ValueError, match=r"21\.0 s.*at most 20 s"):
+            generate_speech(
+                "hello", model_name=AUDIO8, reference_audio=clip, reference_text="hi"
+            )
+
+    def test_text_that_cannot_fit_the_context_is_refused(self, never_loads):
+        line = "This sentence is spoken at a steady pace. " * 40
+        with pytest.raises(ValueError, match="too long.*2048 context positions"):
+            generate_speech(line, model_name=AUDIO8)
+
+    def test_a_long_reference_shrinks_what_fits(self, never_loads, tmp_path):
+        # A line that fits alone is refused beside a long reference: the clip's
+        # frames come out of the same 2,048 positions
+        line = "This sentence is spoken at a steady pace. " * 24
+        assert sg._audio8_estimated_positions(line, "", 0.0) <= 2048
+        clip = write_wav(tmp_path / "ref.wav", 19.0)
+        with pytest.raises(ValueError, match="too long.*shorter reference"):
+            generate_speech(
+                line, model_name=AUDIO8, reference_audio=clip, reference_text="hi"
+            )
+
+    @pytest.mark.parametrize("where", ["generate_kwargs", "forward_params"])
+    def test_an_unknown_generation_setting_is_refused_by_name(self, never_loads, where):
+        with pytest.raises(ValueError, match=r"generation setting\(s\) \['speaker_id'\]"):
+            generate_speech("hello", model_name=AUDIO8, **{where: {"speaker_id": 1}})
+
+    def test_audio8_needs_text(self, never_loads):
+        with pytest.raises(ValueError, match="generate_speech needs exactly one of"):
+            generate_speech(model_name=AUDIO8)
+
+
+class FakeOutput:
+    def __init__(self, finished=True):
+        self.codes = torch.zeros((1, 10, 3), dtype=torch.long)
+        self.finished = torch.tensor([finished])
+
+
+class TestAudio8Dispatch:
+    """The branch around a stand-in model: what reaches it, what comes back."""
+
+    @pytest.fixture
+    def fake_model(self, monkeypatch):
+        model = MagicMock()
+        model.config.codec_sample_rate = 44100
+        model.device = torch.device("cpu")
+        model.generate.return_value = FakeOutput()
+        model.decode_audio.return_value = (torch.ones((1, 900)), torch.tensor([700]))
+        processor = MagicMock(return_value={"prefix_input_ids": torch.zeros(1)})
+        loader = MagicMock(return_value=(model, processor))
+        monkeypatch.setattr(sg, "_load_audio8", loader)
+        monkeypatch.setattr(
+            sg, "hf_pipeline", MagicMock(side_effect=AssertionError("pipeline"))
+        )
+        return model, processor, loader
+
+    def test_returns_44k_mono_trimmed_to_its_length(self, fake_model):
+        track = generate_speech("hello", model_name=AUDIO8)
+        assert track.sample_rate == 44100
+        assert track.audio.shape == (1, 700)
+
+    def test_no_reference_speaks_in_the_default_voice(self, fake_model):
+        _, processor, _ = fake_model
+        generate_speech("hello", model_name=AUDIO8)
+        processor.assert_called_once_with("hello")
+
+    def test_the_reference_reaches_the_processor_as_mono(self, fake_model, tmp_path):
+        _, processor, _ = fake_model
+        clip = write_wav(tmp_path / "ref.wav", 2.0, rate=22050)
+        generate_speech(
+            "hello", model_name=AUDIO8, reference_audio=clip, reference_text="hi"
+        )
+        kwargs = processor.call_args.kwargs
+        assert kwargs["reference_text"] == "hi"
+        assert kwargs["sampling_rate"] == 22050
+        assert kwargs["reference_audio"].shape == (44100,)
+
+    def test_the_context_is_filled_by_default(self, fake_model):
+        model, _, _ = fake_model
+        generate_speech("hello", model_name=AUDIO8, generate_kwargs={"top_k": 20})
+        kwargs = model.generate.call_args.kwargs
+        assert kwargs["max_new_tokens"] == 2048
+        assert kwargs["top_k"] == 20
+        assert kwargs["return_dict_in_generate"] is True
+
+    def test_a_caller_max_new_tokens_wins(self, fake_model):
+        model, _, _ = fake_model
+        generate_speech("hello", model_name=AUDIO8, forward_params={"max_new_tokens": 9})
+        assert model.generate.call_args.kwargs["max_new_tokens"] == 9
+
+    def test_an_unfinished_line_is_refused_not_truncated(self, fake_model):
+        model, _, _ = fake_model
+        model.generate.return_value = FakeOutput(finished=False)
+        with pytest.raises(ValueError, match="ran out of room"):
+            generate_speech("hello", model_name=AUDIO8)
+        model.decode_audio.assert_not_called()
+
+    def test_the_seed_becomes_the_generator(self, fake_model):
+        model, _, _ = fake_model
+        generate_speech("hello", model_name=AUDIO8, seed=7)
+        generator = model.generate.call_args.kwargs["generator"]
+        assert generator.initial_seed() == 7
+
+    def test_no_seed_samples_unseeded(self, fake_model):
+        model, _, _ = fake_model
+        generate_speech("hello", model_name=AUDIO8)
+        assert model.generate.call_args.kwargs["generator"] is None
+
+    @pytest.mark.parametrize(
+        "device, dtype",
+        [("cpu", torch.float32), ("mps", torch.float32), ("cuda:1", torch.bfloat16)],
+    )
+    def test_dtype_by_backend(self, fake_model, device, dtype):
+        _, _, loader = fake_model
+        generate_speech("hello", model_name=AUDIO8, device=device)
+        assert loader.call_args.args == (device, dtype)
+
+
+class TestAudio8Loader:
+    def test_fetches_each_file_at_the_pinned_revision(self, monkeypatch, tmp_path):
+        clear_model_cache()
+        fetched = []
+
+        def fake_download(repo_id, filename, revision):
+            fetched.append((repo_id, filename, revision))
+            return str(tmp_path / filename)
+
+        monkeypatch.setattr("huggingface_hub.hf_hub_download", fake_download)
+        monkeypatch.setattr(a8, "load_model", MagicMock(return_value=MagicMock()))
+        monkeypatch.setattr(a8, "load_tokenizer", MagicMock())
+        monkeypatch.setattr(a8.ArkttsProcessor, "for_model", MagicMock())
+        try:
+            sg._load_audio8("cpu", torch.float32)
+        finally:
+            clear_model_cache()
+        assert fetched == [(AUDIO8, f, a8.REVISION) for f in a8.MODEL_FILES]
+        args, kwargs = a8.load_model.call_args
+        assert args == tuple(
+            str(tmp_path / f) for f in (a8.CONFIG_FILE, a8.WEIGHTS_FILE, a8.CODEC_FILE)
+        )
+        assert kwargs["generation_config_path"] == str(
+            tmp_path / a8.GENERATION_CONFIG_FILE
+        )
+
+    def test_the_codec_is_read_with_weights_only(self):
+        # what the branch relies on to load codec.pth from a Hub repo
+        assert "weights_only=True" in Path(a8.__file__).read_text()
+
+
+class SmallTokenizer:
+    """Characters into the tiny model's text range, below its semantic ids."""
+
+    def encode(self, text, add_special_tokens=True):
+        return [3 + ord(ch) % 30 for ch in text]
+
+
+@pytest.fixture
+def tiny_hub(tmp_path, monkeypatch):
+    """The real branch over a tiny random checkpoint: the files a hub fetch
+    would return, written locally. The slow transformer's output norm is
+    zeroed so every allowed token is equally likely - a random model then
+    reaches eos within a short line rather than never."""
+    from safetensors.torch import save_file
+
+    torch.manual_seed(0)
+    overrides = {**TINY, "max_seq_len": 512}
+    config = a8.ArkttsConfig(**overrides)
+    model = a8.ArkttsModel(config)
+    state = {k: v.contiguous() for k, v in model.state_dict().items()}
+    state["norm.weight"] = torch.zeros_like(state["norm.weight"])
+    files = tmp_path / "hub"
+    files.mkdir()
+    save_file(state, files / a8.WEIGHTS_FILE)
+    torch.save(legacy_codec_state(a8.ArkttsCodec(config)), files / a8.CODEC_FILE)
+    (files / a8.CONFIG_FILE).write_text(json.dumps(overrides))
+    (files / a8.GENERATION_CONFIG_FILE).write_text(json.dumps({"top_p": 1.0}))
+    (files / a8.TOKENIZER_FILE).write_text("{}")
+
+    def fake_download(repo_id, filename, revision):
+        assert (repo_id, revision) == (AUDIO8, a8.REVISION)
+        return str(files / filename)
+
+    monkeypatch.setattr("huggingface_hub.hf_hub_download", fake_download)
+    monkeypatch.setattr(a8, "load_tokenizer", lambda path: SmallTokenizer())
+    clear_model_cache()
+    yield tmp_path
+    clear_model_cache()
+
+
+class TestAudio8RealPath:
+    """generate_speech through the vendored model, processor and codec - no
+    stand-in between the task and the architecture."""
+
+    def test_default_voice_speaks_44k_mono(self, tiny_hub):
+        track = generate_speech("hello there", model_name=AUDIO8, seed=3)
+        assert track.sample_rate == 44100
+        assert track.audio.ndim == 2 and track.audio.shape[0] == 1
+        assert track.audio.shape[1] > 0
+        assert track.audio.shape[1] % a8.ArkttsCodec.frame_length == 0
+        assert numpy.isfinite(track.audio).all()
+
+    def test_a_reference_clone_runs_and_the_seed_repeats_it(self, tiny_hub):
+        clip = write_wav(tiny_hub / "voice.wav", 1.0)
+        arguments = dict(
+            model_name=AUDIO8, reference_audio=clip, reference_text="hi", seed=5
+        )
+        first = generate_speech("hello there", **arguments)
+        second = generate_speech("hello there", **arguments)
+        assert first.sample_rate == 44100
+        assert first.audio.shape[1] > 0
+        assert first.audio.shape == second.audio.shape
+        numpy.testing.assert_array_equal(first.audio, second.audio)
diff --git a/tests/test_task_weights.py b/tests/test_task_weights.py
index 084c6f0c..a87f281a 100644
--- a/tests/test_task_weights.py
+++ b/tests/test_task_weights.py
@@ -132,6 +132,20 @@ def test_a_local_model_still_lists_the_speaker_encoder(self):
             {"model_name": "/models/tts", "speaker_embedding": "me.wav"},
         ) == ["speechbrain/spkrec-xvect-voxceleb"]
 
+    def test_audio8_lists_its_pinned_files_and_the_codec(self):
+        # #1121: a vendored model fetched file by file at one revision, so
+        # the plan names each file - codec.pth among them - not the repo
+        from dw.tasks import audio8_tts_model as a8
+
+        hook = required_weights_hook("generate_speech")
+        entries = hook({"model_name": a8.REPO_ID})
+        assert entries == [
+            {"repo": a8.REPO_ID, "filename": f, "revision": a8.REVISION}
+            for f in a8.MODEL_FILES
+        ]
+        assert "codec.pth" in [entry["filename"] for entry in entries]
+        assert a8.REVISION == "1e857568bfd4f02931aca3988ee773a44d2d26d3"
+
 
 class TestVoiceAttribution:
     def test_is_only_the_speaker_embedder(self):
@@ -338,6 +352,20 @@ def test_generate_speech_loads_the_repo_it_declares(self, monkeypatch, arguments
 
         assert [key[1] for key in keys] == declared("generate_speech", arguments)
 
+    def test_generate_speech_loads_the_audio8_repo_it_declares(self, monkeypatch):
+        from dw.tasks import audio8_tts_model as a8
+        from dw.tasks import speech_generation
+
+        keys = recording_cache(monkeypatch, speech_generation)
+        with pytest.raises(Reached):
+            speech_generation.generate_speech("hello", model_name=a8.REPO_ID)
+
+        assert [key[1] for key in keys] == sorted(
+            set(declared("generate_speech", {"model_name": a8.REPO_ID}))
+        )
+        assert keys[0][0] == "speech_generation"
+        assert keys[0][-1] == a8.REVISION
+
     @pytest.mark.parametrize(
         "arguments",
         [
diff --git a/workflows/templates/generate-speech.json b/workflows/templates/generate-speech.json
index b4f35a22..57206139 100644
--- a/workflows/templates/generate-speech.json
+++ b/workflows/templates/generate-speech.json
@@ -1,6 +1,6 @@
 {
   "id": "GenerateSpeech",
-  "description": "Speaks a line of text with a local text-to-speech model and saves it as a wav. model_name picks the voice: facebook/mms-tts-eng (the default, one voice; other languages are mms-tts-<code>), suno/bark-small (distinct speakers via a voice_preset task argument) or microsoft/speecht5_tts (the voice of a reference clip via speaker_embedding). The result declares no 'sample_rate': a generated track carries the rate its model produced it at, so saying nothing is what saves it correctly.",
+  "description": "Speaks a line of text with a local text-to-speech model and saves it as a wav. model_name picks the voice: facebook/mms-tts-eng (the default, one voice; other languages are mms-tts-<code>), suno/bark-small (distinct speakers via a voice_preset task argument) or microsoft/speecht5_tts (the voice of a reference clip via speaker_embedding). To clone a voice from a short clip and its transcript, use the voice-clone template (Edge0/Audio8-TTS-Realistic-0.6b, reference_audio with reference_text task arguments). The result declares no 'sample_rate': a generated track carries the rate its model produced it at, so saying nothing is what saves it correctly.",
   "variables": {
     "text": "Somebody finished the pistachio and nobody is saying anything.",
     "model_name": "facebook/mms-tts-eng"
diff --git a/workflows/templates/voice-clone.json b/workflows/templates/voice-clone.json
new file mode 100644
index 00000000..5601d181
--- /dev/null
+++ b/workflows/templates/voice-clone.json
@@ -0,0 +1,29 @@
+{
+  "id": "VoiceClone",
+  "description": "Speaks a line in the voice of a short reference clip with Audio8-TTS and saves it as a 44.1 kHz mono wav. 'reference_audio' is the clip (an asset: reference, at most 20 s; 5-10 s of clean speech is plenty) and 'reference_text' is exactly what is said in it - both are required together. The line can be in another language than the clip: English and Russian are the model's strongest. Text and reference share a 2,048-position context, about 95 s of prompt, reference and speech together, so a line too long to fit is refused before anything runs rather than cut off; split it into shorter takes. The same 'seed' gives the same take. Consent: clone only a voice you have the right to use - your own, or one whose owner has agreed - and never to impersonate or deceive. As the model card asks, do not use it to make speech a person did not say pass as theirs.",
+  "variables": {
+    "text": "Somebody finished the pistachio and nobody is saying anything.",
+    "reference_audio": "asset:voice.wav",
+    "reference_text": "The words spoken in the reference clip, exactly as said.",
+    "seed": null
+  },
+  "seed": "variable:seed",
+  "steps": [
+    {
+      "name": "speak",
+      "task": {
+        "command": "generate_speech",
+        "arguments": {
+          "text": "variable:text",
+          "model_name": "Edge0/Audio8-TTS-Realistic-0.6b",
+          "reference_audio": "variable:reference_audio",
+          "reference_text": "variable:reference_text"
+        }
+      },
+      "result": {
+        "content_type": "audio/wav",
+        "subfolder": "final"
+      }
+    }
+  ]
+}

From 37f457f255d6f5b0dc9bcfb7e37f0ba22d34a4da Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:52:17 -0600
Subject: [PATCH 091/125] feat(speech): #1121 - Audio8 docs, voice-clone plugin
 line, step-cache row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/SECURITY.md                              | 11 ++++++++++
 docs/TASKS.md                                 | 21 ++++++++++++++++++
 .../skills/minimax-h3/references/dialogue.md  |  2 ++
 tests/test_catalog_structure.py               |  5 ++++-
 tests/test_security_trust_gate.py             |  8 +++++--
 tests/test_speech_generation.py               | 22 ++++++++++++++-----
 tests/test_step_cache.py                      |  1 +
 7 files changed, 61 insertions(+), 9 deletions(-)

diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index c3d68e96..50d5659c 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -136,6 +136,17 @@ generative model (Bark, VibeVoice). Each must be an object, and
 `custom_generate` / `trust_remote_code` in either are refused untrusted, before
 the model loads (released versions through 0.14.0 passed them through).
 
+`speech_generation`'s Audio8-TTS branch (`Edge0/Audio8-TTS-Realistic-0.6b`,
+`dw/tasks/audio8_tts_model.py`) runs no code from its repo: the model is
+vendored, so there is no `trust_remote_code` load. Its five files are fetched
+with `hf_hub_download` at one pinned 40-hex revision, never a branch, and the
+weights are safetensors. The audio codec, `codec.pth`, is a pickle checkpoint;
+it is read with `torch.load(weights_only=True)`, which refuses any object that
+isn't a tensor or a plain container, and only at that pinned revision. Its
+`generate_kwargs` / `forward_params` pass the same trust gate as above, then an
+allowlist (`temperature`, `top_p`, `top_k`, `do_sample`, `max_new_tokens`):
+any other key is refused by name before the model loads.
+
 `text_generation`'s `system_prompt` may be read from a Hub repo file
 (`{"from_hub": {...}}`). That fetch is anonymous only: the Hub is asked
 without credentials (`token=False`) whether it serves the file publicly at the
diff --git a/docs/TASKS.md b/docs/TASKS.md
index bcf3dca2..99fd73c2 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3167,6 +3167,7 @@ Speak a line of text with a local text-to-speech model. A validate's `downloads_
 | Bark | `suno/bark-small` (the command's default) | Distinct speakers by `voice_preset` |
 | MMS / VITS | `facebook/mms-tts-eng`, and `mms-tts-<code>` per language (the template's default) | One voice, a quarter Bark's size; a multi-speaker VITS takes `speaker_id` in `forward_params` |
 | SpeechT5 | `microsoft/speecht5_tts` | The voice of a reference clip, given as `speaker_embedding` |
+| Audio8-TTS | `Edge0/Audio8-TTS-Realistic-0.6b` | A cloned voice from `reference_audio` + `reference_text`, or its default voice; 44.1 kHz mono, many languages from one checkpoint |
 
 The result is a waveform carrying the rate its model generated at, so it composes with [`slice_audio`](#slice_audio), [`fade_audio`](#fade_audio) and [`pair_audio`](#pair_audio) directly ([`concat_videos`](#concat_videos) and `dissolve_videos` join videos — pair the track onto a video first).
 
@@ -3190,6 +3191,8 @@ The result is a waveform carrying the rate its model generated at, so it compose
 | `model_name` | No | HuggingFace model ID (default: `suno/bark-small`) |
 | `voice_preset` | No | The speaker, for a model with presets — `v2/en_speaker_0` through `v2/en_speaker_9` for Bark. A model with no processor (a single-voice model such as `facebook/mms-tts-eng`) refuses a `voice_preset` with an error rather than ignoring it |
 | `speaker_embedding` | No | A reference audio file (typically an `asset:` reference) whose voice a SpeechT5 model should speak in. Reduced to an x-vector with speechbrain's `spkrec-xvect-voxceleb` and injected into `forward_params` as `speaker_embeddings`. A model that isn't SpeechT5 refuses it the same way a single-voice model refuses `voice_preset` |
+| `reference_audio` | No | Audio8-TTS only: a clip of the voice to clone (typically an `asset:` reference), up to 20 s; 5-10 s of clean speech is plenty. Needs `reference_text` |
+| `reference_text` | No | Audio8-TTS only: the words spoken in `reference_audio`, verbatim. Needs `reference_audio` |
 | `forward_params` | No | Passed to the model's forward/generate call |
 | `generate_kwargs` | No | Ad-hoc generation settings for a generative model — `temperature`, `do_sample` |
 
@@ -3199,6 +3202,23 @@ The command's own default is Bark because its voice presets give distinct speake
 
 The result needs no `sample_rate`. A generated track carries the rate its model produced it at, and that beats the 44100 default; declaring one still wins over both, for a track whose rate was reported wrong. Every TTS model runs at a different rate, so a declared rate that does not match plays the speech at the wrong speed and pitch without ever failing.
 
+### Cloning a voice (Audio8-TTS)
+
+`model_name: "Edge0/Audio8-TTS-Realistic-0.6b"` takes its own branch. The model is vendored (`dw/tasks/audio8_tts_model.py`), so it loads no code from its repo, and its files - `config.json`, `generation_config.json`, `model.safetensors`, `tokenizer.json` and the codec `codec.pth` - are fetched at one pinned revision; a validate's `downloads_required` lists all five. The result is a 44.1 kHz mono track.
+
+Give `reference_audio` and `reference_text` together and it speaks `text` in the reference's voice; leave both out and it speaks in its default voice. The language follows `text` - there is no `language` argument. Every refusal fires before the model loads:
+
+- `reference_audio` without `reference_text` (an empty one counts as missing), or the reverse;
+- either one on any other model;
+- `speaker_embedding`, `voice_preset` or `messages` on Audio8;
+- a reference longer than 20 s;
+- text that, with the reference, won't fit the model's 2,048-position context. It is refused, never truncated: split the line;
+- a `generate_kwargs` / `forward_params` key outside `temperature`, `top_p`, `top_k`, `do_sample`, `max_new_tokens`. `max_new_tokens` defaults to the room left in the context.
+
+The fit check is an estimate from the text's length; a line that passes it but still runs out of room before the model finishes is refused after generation rather than returned cut off. The workflow's `seed` fixes the take: the same seed, text and reference give the same audio.
+
+[`voice-clone.json`](../workflows/templates/voice-clone.json) is the template. **Clone only a voice you have the speaker's consent to use.**
+
 ### Generating a voice to condition on
 
 The role this earns its place in is voice *timbre reference*, not the track a mouth follows. A `MiniMaxH3AudioReference` is audio H3 reads, not audio it plays: it takes a few seconds of a voice to fix timbre, pitch and delivery while H3 still generates the line, and a mouth asked to follow a whole track through a reference follows it loosely. `music-video` and the `match_audio` chain templates pass each shot's slice as one, and a reference alone can re-sing the track shifted by whole beats (#795). Holding the track with `hold_audio` (the `workflows` guide, "H3: generating to a held soundtrack") keeps it exact: `music-video` holds each slice by default, the chains leave it null. #619 found hold with image-only references worse than the reference alone on a sung track; #808 measured hold plus the reference at 0.00 s offset on every shot against up to 1.37 s for the reference alone, audio only, mouth onsets not counted. Build the reference with `from_previous_result` and the clip's own sample rate comes across with it:
@@ -3219,6 +3239,7 @@ A speech model is worth releasing before a video model loads — set `release_mo
 **Examples:**
 
 - [generate-speech.json](../workflows/templates/generate-speech.json) — Speak a line and save it as a `.wav`
+- [voice-clone.json](../workflows/templates/voice-clone.json) — Speak a line in the voice of a reference clip (Audio8-TTS)
 - [voice-timbre-reference.json](../workflows/templates/minimax/voice-timbre-reference.json) — Generate a voice, then condition H3's `<Audio 1>` on it
 
 ## Speech Transcription
diff --git a/plugins/dw/skills/minimax-h3/references/dialogue.md b/plugins/dw/skills/minimax-h3/references/dialogue.md
index 42c4d0c7..36222344 100644
--- a/plugins/dw/skills/minimax-h3/references/dialogue.md
+++ b/plugins/dw/skills/minimax-h3/references/dialogue.md
@@ -74,6 +74,8 @@ rule and none is worth prompt words yet:
     `templates/minimax/voice-timbre-reference` as shipped, two Bark source
     clips and two seeds each, `check-script` heard only the new `<d>` line
     and no source word (`2026-10-h3-aiskills-probes.md` row P2, #1059).
+    `templates/voice-clone` (Audio8-TTS, #1121) is another source for that
+    reference: it speaks a new line in a real speaker's cloned voice, with consent.
 - Not settled:
   - whether `<breath>` adds a beat: it may lengthen a pause H3 already takes
     at a sentence break, but it doesn't create one (row 6b);
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index decdf56b..ce2f65d6 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -117,7 +117,10 @@ def load(path):
         ["composes-workflows", "image-conditioned"],
     ),
     "workflows/templates/generate-speech.json": ("audio", ["has-audio"]),
-    "workflows/templates/voice-clone.json": ("audio", ["has-audio", "needs-input-media"]),
+    "workflows/templates/voice-clone.json": (
+        "audio",
+        ["has-audio", "needs-input-media"],
+    ),
     "workflows/templates/assemble-and-score.json": ("sequence", ["needs-input-media"]),
     "workflows/templates/image-processors.json": ("utility", []),
 }
diff --git a/tests/test_security_trust_gate.py b/tests/test_security_trust_gate.py
index 72def866..c1f96e29 100644
--- a/tests/test_security_trust_gate.py
+++ b/tests/test_security_trust_gate.py
@@ -879,7 +879,9 @@ def test_a_non_object_is_refused(self, monkeypatch, where):
             speech_generation.generate_speech("hello", device="cpu", **{where: "x"})
 
     @pytest.mark.parametrize("where", ["generate_kwargs", "forward_params"])
-    def test_refused_before_audio8_loads(self, untrusted, no_network, monkeypatch, where):
+    def test_refused_before_audio8_loads(
+        self, untrusted, no_network, monkeypatch, where
+    ):
         """The Audio8 branch (#1121) sits behind the same gate: a workflow
         naming the vendored model is refused 'trust_remote_code' before any
         file is fetched, not handed to the branch's own key allowlist."""
@@ -888,7 +890,9 @@ def test_refused_before_audio8_loads(self, untrusted, no_network, monkeypatch, w
         loader = MagicMock()
         monkeypatch.setattr(speech_generation, "_load_audio8", loader)
         monkeypatch.setattr(speech_generation, "hf_pipeline", loader)
-        with pytest.raises(UntrustedWorkflowError, match="'trust_remote_code'.*trusted"):
+        with pytest.raises(
+            UntrustedWorkflowError, match="'trust_remote_code'.*trusted"
+        ):
             speech_generation.generate_speech(
                 "hello",
                 device="cpu",
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 3eefe078..60ebe01c 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -485,7 +485,7 @@ def write_wav(path, seconds, rate=22050):
         handle.setnchannels(1)
         handle.setsampwidth(2)
         handle.setframerate(rate)
-        tone = (numpy.sin(numpy.linspace(0, 400 * seconds, int(rate * seconds))) * 8000)
+        tone = numpy.sin(numpy.linspace(0, 400 * seconds, int(rate * seconds))) * 8000
         handle.writeframes(tone.astype("<i2").tobytes())
     return str(path)
 
@@ -532,17 +532,23 @@ def test_messages_are_refused_on_audio8(self, never_loads):
             )
 
     def test_reference_audio_needs_reference_text(self, never_loads):
-        with pytest.raises(ValueError, match="'reference_audio' needs 'reference_text'"):
+        with pytest.raises(
+            ValueError, match="'reference_audio' needs 'reference_text'"
+        ):
             generate_speech("hello", model_name=AUDIO8, reference_audio="voice.wav")
 
     def test_an_empty_reference_text_counts_as_missing(self, never_loads):
-        with pytest.raises(ValueError, match="'reference_audio' needs 'reference_text'"):
+        with pytest.raises(
+            ValueError, match="'reference_audio' needs 'reference_text'"
+        ):
             generate_speech(
                 "hello", model_name=AUDIO8, reference_audio="v.wav", reference_text=""
             )
 
     def test_reference_text_needs_reference_audio(self, never_loads):
-        with pytest.raises(ValueError, match="'reference_text' needs 'reference_audio'"):
+        with pytest.raises(
+            ValueError, match="'reference_text' needs 'reference_audio'"
+        ):
             generate_speech("hello", model_name=AUDIO8, reference_text="hi there")
 
     def test_a_reference_over_twenty_seconds_is_refused(self, never_loads, tmp_path):
@@ -570,7 +576,9 @@ def test_a_long_reference_shrinks_what_fits(self, never_loads, tmp_path):
 
     @pytest.mark.parametrize("where", ["generate_kwargs", "forward_params"])
     def test_an_unknown_generation_setting_is_refused_by_name(self, never_loads, where):
-        with pytest.raises(ValueError, match=r"generation setting\(s\) \['speaker_id'\]"):
+        with pytest.raises(
+            ValueError, match=r"generation setting\(s\) \['speaker_id'\]"
+        ):
             generate_speech("hello", model_name=AUDIO8, **{where: {"speaker_id": 1}})
 
     def test_audio8_needs_text(self, never_loads):
@@ -633,7 +641,9 @@ def test_the_context_is_filled_by_default(self, fake_model):
 
     def test_a_caller_max_new_tokens_wins(self, fake_model):
         model, _, _ = fake_model
-        generate_speech("hello", model_name=AUDIO8, forward_params={"max_new_tokens": 9})
+        generate_speech(
+            "hello", model_name=AUDIO8, forward_params={"max_new_tokens": 9}
+        )
         assert model.generate.call_args.kwargs["max_new_tokens"] == 9
 
     def test_an_unfinished_line_is_refused_not_truncated(self, fake_model):
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 62f7c60e..3bbfdac2 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -914,6 +914,7 @@ def test_normalized_downstream_false_when_nothing_references_it():
     "transcribe-audio.json": {},
     "upscale-diffusion.json": {},
     "upscale-spandrel.json": {},
+    "voice-clone.json": {},
 }
 
 TEMPLATES_DIR = pathlib.Path(__file__).resolve().parents[1] / "workflows" / "templates"

From 8ad64d25d302addae066822c2296ae9b8cb11e9f Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 07:56:22 -0600
Subject: [PATCH 092/125] docs(proposals): #1122 - beat review design record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/beat-review-complete.md          | 143 ++++++++++++++++++
 docs/proposals/todo.md                        |   7 +
 2 files changed, 150 insertions(+)
 create mode 100644 docs/proposals/complete/beat-review-complete.md

diff --git a/docs/proposals/complete/beat-review-complete.md b/docs/proposals/complete/beat-review-complete.md
new file mode 100644
index 00000000..af520126
--- /dev/null
+++ b/docs/proposals/complete/beat-review-complete.md
@@ -0,0 +1,143 @@
+# Beat review: beat authoring and the beat review in the story skills (#1122)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). Plan v2 approved by Don on 2026-11-01 as "build smaller"; one
+stage, #1125 (A), verified. The plan comment on #1122 is the full design;
+this doc records what shipped against it, and keeps the deferred stage B
+design so it can be approved later without a new sweep.
+
+## The idea
+
+A clip-level beat gate, from story-forge (MIT,
+`nicedreamzapp/story-forge`: `pipeline-tools/beat_gate.py`, `LESSONS.json`;
+assessed 2026-11-01). A vision-language judge describes a shot's frames
+blind, then gives a verdict against the shot's script beat, with a majority
+over sampled frames, a distinct rejection reason and a correction for the
+next attempt. dw confirmed each line is *heard* (`check_script`); nothing
+confirmed each beat is *seen*. story-forge's founding failure: an episode
+that passed 86 of 91 automated checks while the bear poked a wall with a
+stick instead of shouldering the door open.
+
+## Decisions
+
+- **Plan verdict: build smaller.** In story-forge a script reviewed its own
+  output, so a local VLM was the only eye. In dw the driving agent is
+  already a strong vision model reading frames with `get_output_frames` in
+  "Run and judge". What carries over is **how** to judge and **how to write
+  a beat that can be judged**, which is skill text. The engine task (stage
+  B) was deferred until evidence shows the agent's own review misses beats.
+- **Q1:** build smaller, stage A now, stage B deferred with its return
+  triggers. **Q2:** the shot-sheet fields are `beat` and `must_not`.
+  **Q3:** a pointer only in `series-episodes`, no restatement.
+- **Size-cap amendment (Don):** `script-to-video/SKILL.md` was at 10,115 of
+  its 12,288-byte `SKILL_SIZE_LIMIT`, so the rules, the protocol and the
+  audit paragraph went in a new `references/beat-review.md`; `SKILL.md`
+  carries only the two fields and a pointer, plus a size-margin pin.
+- **Correction to the proposal:** the issue proposed a VLM task first; the
+  plan made skill guidance first. SmolVLM-256M, dw's default vision model,
+  is too weak for the verdict in any case.
+
+## What was built
+
+**A, #1125: beat authoring and the beat review (plugin-only).** Develop
+957a7c53, merged 84e8edde (branch `feat/1122-A-beat-review`). No engine,
+MCP, REST or syntax surface changed; no `lem` deploy.
+
+- `plugins/dw/skills/script-to-video/SKILL.md` §2: shot-sheet fields
+  `beat` (one visible state a single frame can show) and `must_not`
+  (physically or story-impossible things to rule out), after
+  `opening_state` / `ending_state`. "Run and judge" points to
+  `references/beat-review.md` before the keep and still names
+  `get_output_frames`. 10,504 of 12,288 bytes after the change.
+- `plugins/dw/skills/script-to-video/references/beat-review.md` (new,
+  4,147 bytes):
+  - *Writing a beat:* who, doing what, to what, where, in a state one frame
+    proves. Four banned kinds, each with a rewrite: motion over time,
+    intent, off-screen facts, emotion words.
+  - *Before anything renders:* every edit-list shot has a beat and every
+    beat a shot; nothing renders while one is missing.
+  - *The review:* 3 evenly spaced frames per clip, 5 only on a split
+    verdict, the image itself for a still; describe blind before the
+    verdict (a fresh subagent without the beat where the client has one);
+    one verdict per frame against `beat` and `must_not`; pass on a
+    majority; exactly one reason per rejected frame from `beat_not_shown`,
+    `must_not_present`, `identity_drift`, `text_in_frame`,
+    `reference_leak`; one concrete correction into the next prompt, within
+    the three-attempt budget.
+  - *Audit the auditor:* a human overrule is appended to the workspace note
+    with `set_note("workspace:<name>", ...)`.
+- `plugins/dw/skills/series-episodes/SKILL.md` "Run and judge": a pointer
+  to `dw:script-to-video`'s beat review per episode shot.
+- Pins: `tests/test_plugin_skills.py::TestScriptToVideoBeatReview` (fields,
+  pointer, majority, the five reasons, the four banned kinds, 3/5 frames,
+  describe-before-verdict, budget, no-render-without-a-beat, audit
+  paragraph, the series pointer with no restated reasons) and
+  `SCRIPT_SKILL_MARGIN = 1024` (SKILL.md stays at least 1 KB under the cap).
+
+Deviations from plan v2, accepted at verify:
+- **No plugin version bump.** `plugin.json`'s version is pinned to
+  `pyproject.toml`'s and only the release script moves both.
+- **The series pointer is written `script-to-video/references/beat-review.md`**,
+  since the link test resolves a bare `references/...` against the
+  linking skill's own directory.
+
+## Bounces per stage
+
+| Stage | Bounces | Cause |
+|---|---|---|
+| A, #1125 | 0 | Verified by reading the served plugin text against the acceptance list (no GPU run, as the plan approved). |
+
+No stage comment names `usage:` figures, so per-stage session cost is not
+recorded. The plan estimated about $2-3 for stage A.
+
+## Not built, and why
+
+### Stage B: a `beat_gate` task (deferred, Q1)
+
+Designed so it can be approved as is:
+- A new command, `returns="json"`:
+  `{verdict, pass_fraction, votes[{frame, description, pass, reason}], correction}`.
+- Two `generate_text` calls on one cached load: describe with no beat, then
+  a verdict from the description plus the beat.
+- Frames from `evenly_spaced_indices`, shot windows from
+  `assess.resolve_shots` / `sample_span`.
+- Beats from a new `beats: [{shot, text, must_not?}]` argument, not `lines`
+  (`dw/script_lines.py` refuses unknown keys there).
+- Default model `Qwen/Qwen3-VL-4B-Instruct` (templates already load it),
+  declared via `required_weights`, `release_models` before the generator.
+- `pass_fraction` feeds `select first_above 0.5` in a beat-gated variant of
+  `best-of-n-to-video`.
+- Opens with a no-code lem probe: score a calibration set of Don's kept and
+  rejected shots with Qwen3-VL-4B through `text_generation`; if 4B can't
+  match the human verdicts, the task isn't worth building at that size.
+- Its cost: a task and docs, a `beats` argument shape, a template against
+  the compact catalog budget, VLM memory no task-level VRAM mechanism can
+  declare (`dw/vram_inheritance.py` projects pipeline steps only), and a
+  calibration set to keep true. Estimated $8-12.
+
+*Comes back if:* a field report shows the agent's own beat review passed a
+shot that missed its beat; or Don asks for unattended best-of-n judged on
+beats; or a run is long enough that frame review by the agent costs more
+context than a local judge would.
+
+### Also out of scope
+
+- A beat linter in code: the skill states the rules and the agent applies
+  them.
+- In-workflow branching or retry (no `when`/`retry`, by design), a new MCP
+  tool (surface at 15,052 of 16,000 tokens), and any change to `judge`'s
+  scalar contract.
+
+## Known edges
+
+- The review relies on the agent's discipline; nothing enforces it, as with
+  the rest of "Run and judge".
+- "Blind" isn't truly blind without a subagent: the agent wrote the beat.
+- Frames add context cost over a long episode, hence 3 by default.
+
+## Overlap left as it was
+
+#1123 (LTX-2.5 and prompt lessons, same source, open) owns model-specific
+prompt wording. This feature owns the beat-as-visible-state rule and the
+review protocol; #1123 should point to `references/beat-review.md` rather
+than restate them.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 54115552..734f3b2c 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -37,6 +37,13 @@ remaining deferred fix is recorded in
 
 ## Shipped since the ranking
 
+- **Beat authoring and the beat review in the story skills** (#1122, stage
+  #1125), shipped 2026-11-01. `script-to-video`'s shot sheet gains `beat`
+  and `must_not`; a new `references/beat-review.md` holds the beat-writing
+  rules and the review (3 frames, blind describe, majority verdict, one
+  reason from five, a correction into the rerun); `series-episodes` points
+  to it. Plugin-only. Record, including the deferred `beat_gate` task and
+  what brings it back: `complete/beat-review-complete.md`.
 - **One-for-one templates follow the source's frame rate** (#1090,
   stages #1106-#1108), shipped 2026-11-01. `face-repair`, `restore-long`,
   `upscale-clip`, `refine-clip`, `refine-in-place`, `restore-deblur` and

From 5546c17ce5e960392527b79329066397dde5d0c5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 08:13:39 -0600
Subject: [PATCH 093/125] fix(check-script): #1129 - name speech outside a
 partial shot map in rules_skipped

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/script_check.py   | 31 +++++++++++++++++++++++++++++++
 tests/test_script_check.py | 27 +++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index b578a41a..02ad0e31 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -423,6 +423,7 @@ def check(
         duration,
     )
     findings.extend(found)
+    rules_skipped.extend(_uncovered_speech(spans, heard, duration))
     found, unchecked = _unheard_line_clips(mono, sample_rate, lines, findings, spans)
     findings.extend(found)
     rules_skipped.extend(unchecked)
@@ -683,6 +684,34 @@ def _shot_rules(
     return rules_applied, rules_skipped, findings
 
 
+def _uncovered_speech(spans, heard, duration):
+    """A `shot_coverage` skip entry (#1129) naming each stretch of the take
+    outside every supplied shot where words were heard: no shot rule looks
+    there, so a clean result must not read as checked."""
+    if not spans:
+        return []
+    gaps, cursor = [], 0.0
+    for span in sorted(spans, key=lambda s: s["start"]):
+        if span["start"] > cursor:
+            gaps.append((cursor, span["start"]))
+        cursor = max(cursor, span["end"])
+    if duration > cursor:
+        gaps.append((cursor, duration))
+    named = []
+    for start, end in gaps:
+        if any(start <= (w["start"] + w["end"]) / 2 < end for w in heard):
+            named.append(f"{round_seconds(start)}-{round_seconds(end)} s")
+    if not named:
+        return []
+    return [
+        {
+            "rule": "shot_coverage",
+            "reason": "speech was heard outside the supplied shot map and "
+            "not checked against any shot: " + ", ".join(named),
+        }
+    ]
+
+
 def _loop_findings(chunks, script_words):
     """A `transcript_loop` finding for each repetition loop over the script's
     own words: Whisper stuck on a line it heard, so what follows the loop was
@@ -1044,6 +1073,8 @@ def check_script(
             start_sample, num_samples}]) - default: the take's own (an earlier
             step's video), else the run manifest or keep_output sidecar
             beside its file. A line naming a shot the map lacks is refused.
+            Speech outside every shot of a partial map is not checked by
+            the shot rules; 'rules_skipped' names those spans (shot_coverage).
 
     Returns:
         A JSON document: 'findings' (line_mismatch, tag_spoken,
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index 388c3b51..510c072f 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -695,6 +695,33 @@ def test_dropped_line_in_a_known_shot_is_at_the_shots_start(self):
         self.assertEqual(found[0]["at"]["shot"], "B")
 
 
+class TestUncoveredSpeech(unittest.TestCase):
+    def test_speech_before_a_partial_map_is_named_as_unchecked(self):
+        chunks = words("ladle soup grudges", 0.0) + words("alpha bravo", 5.0)
+        spans = [{"name": "A", "start": 4.0, "end": 8.0}]
+        answer = run(
+            [{"text": "alpha bravo", "shot": "A"}],
+            chunks,
+            spans=spans,
+            shots_source="explicit",
+        )
+        (skip,) = [s for s in answer["rules_skipped"] if s["rule"] == "shot_coverage"]
+        self.assertIn("0.0-4.0 s", skip["reason"])
+
+    def test_full_coverage_has_no_entry(self):
+        chunks = words("alpha bravo", 5.0)
+        spans = [{"name": "A", "start": 4.0, "end": 8.0}]
+        answer = run(
+            [{"text": "alpha bravo", "shot": "A"}],
+            chunks,
+            spans=spans,
+            shots_source="explicit",
+        )
+        self.assertFalse(
+            [s for s in answer["rules_skipped"] if s["rule"] == "shot_coverage"]
+        )
+
+
 class TestUnscriptedSpeech(unittest.TestCase):
     def test_a_line_spoken_twice_in_its_shot_is_a_finding(self):
         chunks = words("alpha bravo charlie", 0.0) + words("alpha bravo charlie", 1.0)

From b0ac9b4989f4763707e47404a1089f07a922e35c Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 08:18:50 -0600
Subject: [PATCH 094/125] feat(speech): #1121 - refuse top-level Hub-code
 arguments in generate_speech

trust_remote_code, custom_pipeline and custom_generate given as step
arguments (outside forward_params/generate_kwargs) were dropped silently
and the step ran, for every model. They are now refused before anything
loads: by the trust gate when untrusted, as an unused argument when
trusted. Fixes the SE-F057 bounce (probes a and d).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/SECURITY.md                  |  5 +++
 dw/tasks/speech_generation.py     | 44 +++++++++++++++++++++-
 tests/test_security_trust_gate.py | 62 +++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+), 1 deletion(-)

diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 50d5659c..91c7c4fb 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -135,6 +135,11 @@ both its `generate_kwargs` and its `forward_params` to `generate()` for a
 generative model (Bark, VibeVoice). Each must be an object, and
 `custom_generate` / `trust_remote_code` in either are refused untrusted, before
 the model loads (released versions through 0.14.0 passed them through).
+`trust_remote_code`, `custom_pipeline` or `custom_generate` given as a step
+argument of their own, outside those two objects, is refused too, for every
+model: untrusted by the trust gate, trusted as an argument the task doesn't
+take. The task never read them there, but it used to drop them silently, so a
+step setting one ran as if it had taken effect.
 
 `speech_generation`'s Audio8-TTS branch (`Edge0/Audio8-TTS-Realistic-0.6b`,
 `dw/tasks/audio8_tts_model.py`) runs no code from its repo: the model is
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index a8c6c11b..951567b6 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -27,7 +27,13 @@
 from ..media_types import AudioTrack
 from ..dsp import resample_waveform
 from .audio_utils import load_audio
-from ..trust import require_trusted_generate_arguments
+from ..security import UntrustedWorkflowError
+from ..trust import (
+    GENERATE_REMOTE_CODE_ARGUMENTS,
+    REMOTE_CODE_ARGUMENTS,
+    require_trusted_generate_arguments,
+    workflows_are_trusted,
+)
 from . import audio8_tts_model as audio8
 from .model_cache import cached_model, hf_pipeline_placement
 from .weights import argument_or_default, file_entries, repo_entries
@@ -170,6 +176,36 @@ def _generation_settings(value, name):
     return value
 
 
+# The Hub-code switches as top-level task arguments. generate_speech reads
+# none of them there, and a kwargs task drops what it does not read, so one
+# would otherwise pass silently - looking as if it took effect (#1121 bounce)
+_TOP_LEVEL_REMOTE_CODE_ARGUMENTS = tuple(
+    dict.fromkeys(REMOTE_CODE_ARGUMENTS + GENERATE_REMOTE_CODE_ARGUMENTS)
+)
+
+
+def _refuse_top_level_remote_code(kwargs):
+    """Refuse trust_remote_code / custom_pipeline / custom_generate given as
+    step arguments, for every model, before anything loads: the trust gate's
+    refusal for an untrusted workflow, and a plain error for a trusted one
+    (the task still would not use it)."""
+    given = [name for name in _TOP_LEVEL_REMOTE_CODE_ARGUMENTS if kwargs.get(name)]
+    if not given:
+        return
+    names = " or ".join(map(repr, given))
+    if not workflows_are_trusted():
+        raise UntrustedWorkflowError(
+            f"Refusing to run speech_generation: its arguments set {names}, "
+            "which downloads and executes Python from a Hub repository, so it "
+            "needs trusted workflows - see docs/SECURITY.md. generate_speech "
+            "loads no Hub code from its arguments in any case; drop it"
+        )
+    raise ValueError(
+        f"generate_speech takes no {names} argument - it loads no Hub code "
+        "from its arguments, so the setting would have no effect. Drop it"
+    )
+
+
 def _audio8_dtype(device):
     # The checkpoint is bf16, which a 0.6B Qwen-style decoder keeps finite
     # where fp16 may not; MPS and CPU run it in fp32 (fp16/bf16 NaN or crawl)
@@ -429,6 +465,11 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
         ValueError: If the model reports no sample rate for what it generated,
             or if text/messages are both given or neither is, or for any of
             the Audio8 refusals above - each raised before a model loads.
+        UntrustedWorkflowError: If an untrusted workflow sets
+            trust_remote_code, custom_pipeline or custom_generate as a step
+            argument (a trusted one gets a ValueError: the task never reads
+            them there), or Hub-code settings in forward_params or
+            generate_kwargs.
     """
     messages = kwargs.get("messages", None)
     if (text is None) == (messages is None):
@@ -440,6 +481,7 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     if messages is not None:
         _check_messages(messages)
     text_inputs = messages if messages is not None else text
+    _refuse_top_level_remote_code(kwargs)
     # Both reach model.generate() for a generative model, where
     # custom_generate / trust_remote_code download and run Hub code: refused
     # for an untrusted workflow before anything loads, as text_generation does
diff --git a/tests/test_security_trust_gate.py b/tests/test_security_trust_gate.py
index c1f96e29..be8916ca 100644
--- a/tests/test_security_trust_gate.py
+++ b/tests/test_security_trust_gate.py
@@ -902,6 +902,68 @@ def test_refused_before_audio8_loads(
         loader.assert_not_called()
         assert list(no_network) == []
 
+    @pytest.mark.parametrize(
+        "model", [None, "suno/bark-small", "Edge0/Audio8-TTS-Realistic-0.6b"]
+    )
+    @pytest.mark.parametrize(
+        "setting",
+        [
+            pytest.param({"trust_remote_code": True}, id="trust_remote_code"),
+            pytest.param(
+                {"custom_pipeline": "lpw_stable_diffusion"}, id="custom_pipeline"
+            ),
+            pytest.param({"custom_generate": "attacker/repo"}, id="custom_generate"),
+        ],
+    )
+    def test_a_top_level_remote_code_argument_is_refused(
+        self, untrusted, no_network, monkeypatch, model, setting
+    ):
+        """#1121 bounce: a Hub-code switch given as a step argument, not
+        inside forward_params/generate_kwargs, was dropped silently and the
+        step ran. It is refused for every model before anything loads."""
+        from dw.tasks import speech_generation
+
+        loader = MagicMock()
+        monkeypatch.setattr(speech_generation, "_load_audio8", loader)
+        monkeypatch.setattr(speech_generation, "hf_pipeline", loader)
+        key = next(iter(setting))
+        extra = {"model_name": model} if model else {}
+        with pytest.raises(UntrustedWorkflowError, match=f"'{key}'.*trusted"):
+            speech_generation.generate_speech("hello", device="cpu", **extra, **setting)
+        loader.assert_not_called()
+        assert list(no_network) == []
+
+    def test_a_top_level_remote_code_argument_is_refused_when_trusted(
+        self, monkeypatch
+    ):
+        """Trusted, it is still refused: the task never reads it there, so
+        letting it pass would look as if it took effect."""
+        from dw import trust
+        from dw.tasks import speech_generation
+
+        loader = MagicMock()
+        monkeypatch.setattr(speech_generation, "hf_pipeline", loader)
+        monkeypatch.setattr(trust, "workflows_are_trusted", lambda: True)
+        monkeypatch.setattr(speech_generation, "workflows_are_trusted", lambda: True)
+        with pytest.raises(ValueError, match="takes no 'trust_remote_code'"):
+            speech_generation.generate_speech(
+                "hello", device="cpu", trust_remote_code=True
+            )
+        loader.assert_not_called()
+
+    def test_a_false_trust_remote_code_is_not_refused(self, untrusted, monkeypatch):
+        from dw.tasks import speech_generation
+
+        pipe = MagicMock(
+            return_value={"audio": __import__("numpy").zeros(8), "sampling_rate": 16000}
+        )
+        monkeypatch.setattr(
+            speech_generation, "hf_pipeline", MagicMock(return_value=pipe)
+        )
+        speech_generation.generate_speech(
+            "hello", device="cpu", trust_remote_code=False
+        )
+
 
 def _probe_recorder(info):
     """A `probe=` callable that records every path it is asked about.

From 2ca6ece8f56aa425c3250fa7b0aa3e3119d0253b Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 08:43:27 -0600
Subject: [PATCH 095/125] fix(stems): #1130 - no random-shift averaging on a
 clip shorter than the htdemucs segment

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/voice_attribution.py | 13 ++++++++++++-
 tests/test_separate_stems.py  | 22 +++++++++++++++++++---
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/dw/tasks/voice_attribution.py b/dw/tasks/voice_attribution.py
index d976e3ab..1de66b3c 100644
--- a/dw/tasks/voice_attribution.py
+++ b/dw/tasks/voice_attribution.py
@@ -581,9 +581,20 @@ def _run_separator_stems(waveform, sample_rate, device, dtype):
     reference = mix.mean(0)
     mean, std = reference.mean(), reference.std()
     std = std if float(std) > 0 else torch.tensor(1.0)
+    # apply_model's default random-shift averaging (shifts=1) pads and
+    # re-aligns the mix; on a clip shorter than the model's own segment that
+    # returned stems up to 17 dB louder than the mix, and different on every
+    # run (#1130). Such a clip is separated as it is, once, which is exact
+    # and repeatable.
+    segment = float(getattr(model, "segment", 0) or 0)
+    shifts = 0 if mix.shape[-1] < segment * rate else 1
     with torch.no_grad():
         stems = apply_model(
-            model, ((mix - mean) / std)[None], device=device, split=True
+            model,
+            ((mix - mean) / std)[None],
+            device=device,
+            split=True,
+            shifts=shifts,
         )[0]
     return {
         name: (stems[index] * std + mean).float().cpu().numpy()
diff --git a/tests/test_separate_stems.py b/tests/test_separate_stems.py
index a36ab81c..98dcb9ec 100644
--- a/tests/test_separate_stems.py
+++ b/tests/test_separate_stems.py
@@ -47,7 +47,7 @@ def fake_demucs(apply_model):
     }
 
 
-def quarter_split(model, mix, device=None, split=True):
+def quarter_split(model, mix, device=None, split=True, shifts=1):
     """Each stem is a distinct share of the (normalized) mix; they sum to it."""
     shares = torch.tensor([0.1, 0.2, 0.3, 0.4]).view(1, 4, 1, 1)
     return mix[:, None] * shares
@@ -81,10 +81,26 @@ def test_stems_sum_back_to_the_mix(self):
         numpy.testing.assert_allclose(total, source, atol=1e-4)
         numpy.testing.assert_allclose(stems["vocals"].audio, source * 0.4, atol=1e-4)
 
+    def test_clip_shorter_than_the_segment_is_not_shift_averaged(self):
+        # #1130: htdemucs' random-shift averaging blew up short clips
+        seen = []
+
+        def spy(model, mixture, device=None, split=True, shifts=1):
+            seen.append(shifts)
+            return quarter_split(model, mixture)
+
+        with (
+            patch.dict(sys.modules, fake_demucs(spy)),
+            patch.object(FakeModel, "segment", 7.8, create=True),
+        ):
+            separate_stems(AudioTrack(mix(1.0), RATE), device="cpu")
+            separate_stems(AudioTrack(mix(9.0), RATE), device="cpu")
+        self.assertEqual(seen, [0, 1])
+
     def test_mps_failure_retries_on_cpu_with_a_warning(self):
         devices = []
 
-        def flaky(model, mixture, device=None, split=True):
+        def flaky(model, mixture, device=None, split=True, shifts=1):
             devices.append(device)
             if len(devices) == 1:
                 raise RuntimeError("boom")
@@ -106,7 +122,7 @@ def test_task_is_registered_and_described(self):
         self.assertIn("audio", names)
 
 
-def vocals_only(model, mix, device=None, split=True):
+def vocals_only(model, mix, device=None, split=True, shifts=1):
     """The whole (normalized) mix comes back as the vocal stem."""
     shares = torch.tensor([0.0, 0.0, 0.0, 1.0]).view(1, 4, 1, 1)
     return mix[:, None] * shares

From e45b22846a935e51d6b8f145ba7b9a5911e9b924 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 09:26:16 -0600
Subject: [PATCH 096/125] fix(trust): GHSA-hhfj-p9xj-xjmr - refuse Hub-code
 task arguments at validate

trust_remote_code, custom_pipeline and custom_generate in a task step's
arguments validated clean wherever they sat: top level (dropped at run,
refused at run since b0ac9b49 for generate_speech only) or nested in
forward_params/generate_kwargs (refused only at run). A new validate pass,
task_remote_code_errors, refuses each untrusted, naming the key and its
path, so the run is refused before it queues. Task.run repeats the check
for every command before its handler, so no task can grow a path that
forwards one ungated. generate_speech's own top-level gate now reads the
shared TASK_REMOTE_CODE_ARGUMENTS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/SECURITY.md                  |  6 ++
 dw/tasks/speech_generation.py     | 17 ++----
 dw/tasks/task.py                  |  5 ++
 dw/trust.py                       | 77 +++++++++++++++++++++++++
 dw/validation.py                  |  8 +++
 tests/test_security_trust_gate.py | 95 +++++++++++++++++++++++++++++++
 tests/test_validation.py          |  1 +
 7 files changed, 197 insertions(+), 12 deletions(-)

diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 91c7c4fb..ff848587 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -141,6 +141,12 @@ model: untrusted by the trust gate, trusted as an argument the task doesn't
 take. The task never read them there, but it used to drop them silently, so a
 step setting one ran as if it had taken effect.
 
+Untrusted, every task step is checked the same way at validate:
+`trust_remote_code`, `custom_pipeline` or `custom_generate` set anywhere in its
+`arguments`, top level or nested, is an error naming the key and its path, so
+the run is refused before it queues. `Task.run` repeats the check for every
+command before its handler runs (GHSA-hhfj-p9xj-xjmr).
+
 `speech_generation`'s Audio8-TTS branch (`Edge0/Audio8-TTS-Realistic-0.6b`,
 `dw/tasks/audio8_tts_model.py`) runs no code from its repo: the model is
 vendored, so there is no `trust_remote_code` load. Its five files are fetched
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index 951567b6..c12dd5e1 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -29,8 +29,7 @@
 from .audio_utils import load_audio
 from ..security import UntrustedWorkflowError
 from ..trust import (
-    GENERATE_REMOTE_CODE_ARGUMENTS,
-    REMOTE_CODE_ARGUMENTS,
+    TASK_REMOTE_CODE_ARGUMENTS,
     require_trusted_generate_arguments,
     workflows_are_trusted,
 )
@@ -176,20 +175,14 @@ def _generation_settings(value, name):
     return value
 
 
-# The Hub-code switches as top-level task arguments. generate_speech reads
-# none of them there, and a kwargs task drops what it does not read, so one
-# would otherwise pass silently - looking as if it took effect (#1121 bounce)
-_TOP_LEVEL_REMOTE_CODE_ARGUMENTS = tuple(
-    dict.fromkeys(REMOTE_CODE_ARGUMENTS + GENERATE_REMOTE_CODE_ARGUMENTS)
-)
-
-
 def _refuse_top_level_remote_code(kwargs):
     """Refuse trust_remote_code / custom_pipeline / custom_generate given as
     step arguments, for every model, before anything loads: the trust gate's
     refusal for an untrusted workflow, and a plain error for a trusted one
-    (the task still would not use it)."""
-    given = [name for name in _TOP_LEVEL_REMOTE_CODE_ARGUMENTS if kwargs.get(name)]
+    (the task still would not use it). generate_speech reads none of them
+    there, and a kwargs task drops what it does not read, so one would
+    otherwise pass silently - looking as if it took effect (#1121 bounce)."""
+    given = [name for name in TASK_REMOTE_CODE_ARGUMENTS if kwargs.get(name)]
     if not given:
         return
     names = " or ".join(map(repr, given))
diff --git a/dw/tasks/task.py b/dw/tasks/task.py
index d635c11b..972bf2ca 100644
--- a/dw/tasks/task.py
+++ b/dw/tasks/task.py
@@ -17,6 +17,7 @@
 # the names the rest of dw and the tests read
 from .registry import _COMMAND_INFO, _COMMAND_REGISTRY, register_command  # noqa: F401
 from ..task_domains import FINITE, coerce_arguments
+from ..trust import require_trusted_task_arguments
 from . import beats  # noqa: F401 - registers analyze_beats
 from . import measure_sync  # noqa: F401 - registers measure_sync
 from . import phrases  # noqa: F401 - registers analyze_phrases
@@ -312,6 +313,10 @@ def run(self, arguments, previous_pipelines={}):
             # and decoding is otherwise indistinguishable from a hang
             emit_phase("task", detail=self.command)
 
+            # Before any handler: one that drops a remote-code key today is
+            # one refactor away from forwarding it (GHSA-hhfj-p9xj-xjmr)
+            require_trusted_task_arguments(self.command, arguments)
+
             # Look up command in registry
             if self.command in _COMMAND_REGISTRY:
                 handler = _COMMAND_REGISTRY[self.command]
diff --git a/dw/trust.py b/dw/trust.py
index 9e9dcd63..1c80ba66 100644
--- a/dw/trust.py
+++ b/dw/trust.py
@@ -308,3 +308,80 @@ def require_trusted_generate_arguments(arguments, what: str) -> None:
                 f"needs trusted workflows - see docs/SECURITY.md. Pass "
                 f"--trust-workflows if you trust this workflow's source."
             )
+
+
+# Every argument name above, wherever in a task step's arguments it sits. A
+# task hands only the arguments it names to a load or a generate() call, so a
+# top-level `trust_remote_code` on generate_speech was dropped rather than
+# obeyed - but it validated clean, as did the nested forms the task refused
+# only at run (GHSA-hhfj-p9xj-xjmr). Refused at validate and in Task.run for
+# every command, so no task can grow a path that forwards one ungated
+TASK_REMOTE_CODE_ARGUMENTS = tuple(
+    dict.fromkeys(REMOTE_CODE_ARGUMENTS + GENERATE_REMOTE_CODE_ARGUMENTS)
+)
+
+
+def remote_code_arguments(value, path=()):
+    """Every (path, key) under `value` - a task's arguments, walked through
+    nested objects and lists - where a TASK_REMOTE_CODE_ARGUMENTS key is set.
+    `path` ends with the key itself."""
+    found = []
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if key in TASK_REMOTE_CODE_ARGUMENTS and item:
+                found.append((path + (key,), key))
+            else:
+                found.extend(remote_code_arguments(item, path + (key,)))
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            found.extend(remote_code_arguments(item, path + (index,)))
+    return found
+
+
+def _remote_code_task_message(command, path, key):
+    where = ".".join(str(part) for part in path)
+    return (
+        f"Refusing to run task '{command}': its arguments set '{key}' (at "
+        f"'{where}'), which downloads and executes Python from a Hub "
+        f"repository, so it needs trusted workflows - see docs/SECURITY.md. "
+        f"Pass --trust-workflows if you trust this workflow's source"
+    )
+
+
+def require_trusted_task_arguments(command, arguments) -> None:
+    """Refuse a task step whose arguments set a TASK_REMOTE_CODE_ARGUMENTS key
+    anywhere, unless the workflow is trusted.
+
+    Raises:
+        UntrustedWorkflowError: If untrusted and any such key is set
+    """
+    if workflows_are_trusted():
+        return
+    found = remote_code_arguments(arguments)
+    if found:
+        path, key = found[0]
+        raise UntrustedWorkflowError(_remote_code_task_message(command, path, key))
+
+
+def task_remote_code_errors(workflow_definition, source_indices=None):
+    """require_trusted_task_arguments as a validate pass, over the
+    substituted, expanded definition: every remote-code key in a task step's
+    arguments, as [{path, message}], so the run is refused before it queues."""
+    from .references import iter_steps, render_path
+
+    if workflows_are_trusted():
+        return []
+    errors = []
+    for _, _, task, source, where in iter_steps(
+        workflow_definition.get("steps"), source_indices, "task"
+    ):
+        command = task.get("command")
+        for path, key in remote_code_arguments(task.get("arguments"), ("arguments",)):
+            errors.append(
+                {
+                    "path": render_path(("steps", source, "task") + path),
+                    "message": f"{_remote_code_task_message(command, path[1:], key)}"
+                    f"{where}.",
+                }
+            )
+    return errors
diff --git a/dw/validation.py b/dw/validation.py
index df826b41..93abd77b 100644
--- a/dw/validation.py
+++ b/dw/validation.py
@@ -67,6 +67,7 @@
     select_errors,
 )
 from .task_domains import task_argument_errors
+from .trust import task_remote_code_errors
 from .type_references import (
     component_name_errors,
     component_type_errors,
@@ -490,6 +491,13 @@ def _task_errors(context):
         lambda c: guide_chain_errors(c.expanded, c.source_indices),
     ),
     Check("task_signatures", _task_errors),
+    # A task argument that runs Hub code, anywhere in the step - the run
+    # refuses it too (Task.run), but before it queues costs nothing
+    # (GHSA-hhfj-p9xj-xjmr)
+    Check(
+        "task_remote_code",
+        lambda c: task_remote_code_errors(c.expanded, c.source_indices),
+    ),
     # A component_type/scheduler_type/config_type that does not exist, or is
     # outside the trusted ecosystem (dw/type_references.py, #345)
     Check(
diff --git a/tests/test_security_trust_gate.py b/tests/test_security_trust_gate.py
index be8916ca..b25acc68 100644
--- a/tests/test_security_trust_gate.py
+++ b/tests/test_security_trust_gate.py
@@ -1176,3 +1176,98 @@ def test_shot_span_trusted_lifts_containment_for_the_probe(
         )
         assert warnings
         assert calls == [str(outside / "clip.mp4")]
+
+
+class TestTaskRemoteCodeArguments:
+    """GHSA-hhfj-p9xj-xjmr: a Hub-code switch in a task step's arguments -
+    top level, or nested in forward_params/generate_kwargs - validated clean
+    and was refused (or dropped) only at run. It is refused at validate,
+    naming the key, wherever in the arguments it sits, and Task.run refuses
+    it for every command, not only generate_speech."""
+
+    KEYS = [
+        pytest.param("trust_remote_code", True, id="trust_remote_code"),
+        pytest.param("custom_pipeline", "lpw_stable_diffusion", id="custom_pipeline"),
+        pytest.param("custom_generate", "attacker/repo", id="custom_generate"),
+    ]
+
+    @staticmethod
+    def _workflow(arguments, command="generate_speech"):
+        from dw.workflow import Workflow
+
+        return Workflow(
+            {
+                "id": "remote-code",
+                "steps": [
+                    {
+                        "name": "speak",
+                        "task": {"command": command, "arguments": arguments},
+                        "result": {"content_type": "audio/wav"},
+                    }
+                ],
+            },
+            "outputs",
+            None,
+        )
+
+    @pytest.mark.parametrize("key, value", KEYS)
+    @pytest.mark.parametrize(
+        "nest, path",
+        [
+            (lambda kv: kv, "steps[0].task.arguments.{key}"),
+            (
+                lambda kv: {"forward_params": kv},
+                "steps[0].task.arguments.forward_params.{key}",
+            ),
+            (
+                lambda kv: {"generate_kwargs": {"inner": [kv]}},
+                "steps[0].task.arguments.generate_kwargs.inner[0].{key}",
+            ),
+        ],
+        ids=["top_level", "forward_params", "nested_list"],
+    )
+    def test_validate_refuses_it_wherever_it_sits(
+        self, untrusted, key, value, nest, path
+    ):
+        arguments = {"text": "A short line.", **nest({key: value})}
+        errors = self._workflow(arguments).validation_errors()
+        refused = [e for e in errors if "needs trusted workflows" in e["message"]]
+        assert [e["path"] for e in refused] == [path.format(key=key)]
+        assert f"'{key}'" in refused[0]["message"]
+
+    def test_validate_lets_a_false_value_through(self, untrusted):
+        errors = self._workflow(
+            {"text": "A short line.", "trust_remote_code": False}
+        ).validation_errors()
+        assert not [e for e in errors if "trusted workflows" in e["message"]]
+
+    def test_validate_lets_it_through_when_trusted(self, trusted):
+        from dw.trust import task_remote_code_errors
+
+        definition = self._workflow(
+            {"text": "A short line.", "trust_remote_code": True}
+        ).workflow_definition
+        assert task_remote_code_errors(definition) == []
+
+    @pytest.mark.parametrize("key, value", KEYS)
+    def test_task_run_refuses_it_for_any_command(
+        self, untrusted, monkeypatch, key, value
+    ):
+        from dw.tasks import task as task_module
+        from dw.tasks.task import Task
+
+        handler = MagicMock()
+        monkeypatch.setitem(task_module._COMMAND_REGISTRY, "grade", handler)
+        step = Task({"command": "grade", "arguments": {}}, "cpu")
+        with pytest.raises(UntrustedWorkflowError, match=f"'{key}'.*trusted"):
+            step.run({"media": "x", "options": {key: value}})
+        handler.assert_not_called()
+
+    def test_task_run_lets_it_through_when_trusted(self, trusted, monkeypatch):
+        from dw.tasks import task as task_module
+        from dw.tasks.task import Task
+
+        handler = MagicMock(return_value="ran")
+        monkeypatch.setitem(task_module._COMMAND_REGISTRY, "grade", handler)
+        step = Task({"command": "grade", "arguments": {}}, "cpu")
+        assert step.run({"trust_remote_code": True}) == "ran"
diff --git a/tests/test_validation.py b/tests/test_validation.py
index 0fef4841..83ddd45c 100644
--- a/tests/test_validation.py
+++ b/tests/test_validation.py
@@ -202,6 +202,7 @@ def test_validation_does_not_import_the_workflow_module():
     "chain_prompts",
     "guide_chain",
     "task_signatures",
+    "task_remote_code",
     "component_types",
     "component_names",
     "constraints",

From 6d72885ff63161f9aa533ebdcee6bb6e5e05e0e7 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 09:38:26 -0600
Subject: [PATCH 097/125] feat(docs): #1126 - story-forge lessons 1-2 probes

Record-only A/B renders on lem (workspace probe-1123, N=2 seeds):
L1 (haze after 2-3.5 s) and L2 (invented i2v camera moves) are both
not reproduced on our pipeline at this N.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-11-story-forge-lessons.md     | 142 ++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 docs/proposals/audits/2026-11-story-forge-lessons.md

diff --git a/docs/proposals/audits/2026-11-story-forge-lessons.md b/docs/proposals/audits/2026-11-story-forge-lessons.md
new file mode 100644
index 00000000..8198f4e6
--- /dev/null
+++ b/docs/proposals/audits/2026-11-story-forge-lessons.md
@@ -0,0 +1,142 @@
+# Story-forge lessons: record-only probes (#1123 stage A, #1126)
+
+Probe date: 2026-11-01. Server `lem` (2x RTX 3090), develop @ 2ca6ece8.
+Agent: claude-opus-5-5 (anthropic). Workspace `probe-1123`.
+No engine or skill file was changed. This document only records results.
+Stage B (#1123) adds the sections for lessons 3, 4 and 6.
+
+Every render ran on the LTX-2.5 catalog templates as they stand on develop:
+`templates/ltx2/text-to-video` for t2v and `templates/ltx2/image-to-video` for
+i2v, at 24 fps and the templates' default size, steps and offload. Each run's
+`note` names its lesson, cell, seed and arm (`naive`, `control` or `remedy`),
+for example `#1126 L1 cell t2v-day-241 seed 1 (naive: 241 frames)`.
+
+**N = 2.** Each cell ran on seeds 1 and 2, and nothing else varied within a
+cell. Verdicts hold at that N only.
+
+**Verdict rule** (plan v2): a lesson **holds** when its failure shows in at
+least half of the naive renders and its remedy removes it in at least half of
+the remedy renders. Otherwise it is **not reproduced (on our pipeline at this
+N)**.
+
+**How it was judged.** `assess_output` measures audio, seams and A/V sync; it
+has no probe for haze, contrast loss or camera motion. Every verdict below is
+by eye, from `get_output_frames` stills at the times each row lists
+(`fN` is frame N; the last frame of a 121-frame clip is f120). Haze was judged
+as loss of contrast, saturation or black level against the same render's 1 s
+frame. Camera motion was judged by registration of fixed background
+features (horizon, window frame, shelving, bench) across the inspected frames.
+
+## Verdicts
+
+| # | Lesson | Verdict | Naive renders failing | Remedy renders clean |
+| --- | --- | --- | --- | --- |
+| L1 | LTX-2.5 renders haze over after 2–3.5 s; keep clips short (89 frames). | **not reproduced (on our pipeline at this N)** | 0 of 10 (6 t2v at 241, 2 i2v at 241, 2 i2v at 401) | 8 of 8 at 89 frames, but there was nothing to remove |
+| L2 | i2v invents camera moves unless the prompt pins the camera; "camera remains static" alone is not enough, add "locked-off on a tripod, no pan, no zoom". | **not reproduced (on our pipeline at this N)** | 0 of 6 clear moves; 2 of 6 ambiguous (S3, see below) | 6 of 6 "static", 6 of 6 "locked-off" show no move |
+
+L1's two questions:
+- **(i) Does haze set in at a fixed time from the start?** No. No render, at
+  89, 121, 241 or 401 frames, lost contrast or saturation at 2, 3 or 3.5 s,
+  or at any later time inspected (5, 8, 12 s). Compare the 89-frame remedies
+  (07cb2f669c68, be9d8afa66fa, a7775b2ff01a, bd676e2b1ccc, f39f603399a3,
+  4e587078c06e, 40b83c33b23a, 5413b87108de at 2, 3, 3.5 s) with the 241-frame
+  renders at the same times (a843d44d7963, 5eed612e3cb0, 22da8679d29b,
+  1bdae5a5ab37, 3d897e7528ed, 7922a2310b26, 390102b12db4, 1f042b8c8b31) and
+  the 401-frame renders (62d74005a35c, c6d94bb1edac at 3, 3.5 s): the same
+  look at the same time, whatever the length.
+- **(ii) Does the tail of any render degrade, whatever its length?** No. The
+  last frame of every render (f88, f120, f240, f400) is as sharp and
+  saturated as its 1 s frame, including both 401-frame i2v renders (f400 at
+  16.7 s).
+
+Incidental, for L2's reading: one naive L1 render moved its camera despite
+"camera remains static" in the prompt (1f042b8c8b31, i2v-241 seed 2: a slow
+push/arc from about 5 s), and 62d74005a35c (i2v-401 seed 1) drifts left by
+12–16.7 s. Both are past the 5 s of an L2 cell. At 121 frames no render moved.
+
+## L1: haze after 2–3.5 s
+
+Prompts (prompt library, `probe-1123/`): `l1-day` (daylit street market),
+`l1-dim` (low-key reading lamp interior), `l1-action` (boxing gym, dusty light
+shafts), `l1-i2v-bench` (the S1 still's man on a park bench). All four say
+"the camera remains static", so camera motion is not L1's variable.
+
+The i2v still S1 is `asset:probe-1123-s1-bench.jpg` (z-image, seed 1, job
+836e69c60940).
+
+### t2v
+
+| Cell | Arm | Frames | Seed 1 | Seed 2 | Frame times inspected | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| t2v-day-241 | naive | 241 | a843d44d7963 | 5eed612e3cb0 | 1, 2, 3, 3.5, 5, 8 s, f240 | no haze | Contrast and colour steady to f240 on both. Seed 1's woman walks off left late; a slight reframe at 8–10 s. |
+| t2v-dim-241 | naive | 241 | 22da8679d29b | 1bdae5a5ab37 | 1, 2, 3, 3.5, 5, 8 s, f240 | no haze | Blacks stay deep and the lamp highlight crisp to f240. |
+| t2v-action-241 | naive | 241 | 3d897e7528ed | 7922a2310b26 | 1, 2, 3, 3.5, 5, 8 s, f240 | no haze | The dust shafts are prompted atmosphere and hold the same density at 1 s and f240. The blur on punches is per-frame motion blur, not a fade. |
+| t2v-day-121 | control | 121 | d0b681f6d0a1 | 4ff547d7b280 | 1, 2, 3, 3.5 s, f120 | no haze | Steady to f120. |
+| t2v-dim-121 | control | 121 | 9e47ba3de55f | 8e548bf95e8e | 1, 3 s, f120 | no haze | Low-key exposure constant. |
+| t2v-action-121 | control | 121 | 92f361532f52 | d3a51b66db99 | 1, 3 s, f120 | no haze | Dust density constant; punch motion blur only. |
+| t2v-day-89 | remedy | 89 | 07cb2f669c68 | be9d8afa66fa | 1, 2, 3, 3.5 s, f88 | no haze | Steady to f88. |
+| t2v-dim-89 | remedy | 89 | a7775b2ff01a | bd676e2b1ccc | 1, 2, 3, 3.5 s, f88 | no haze | Steady to f88. |
+| t2v-action-89 | remedy | 89 | f39f603399a3 | 4e587078c06e | 1, 2, 3, 3.5 s, f88 | no haze | Motion blur on punches at 1–2 s (seed 1). |
+
+### i2v (still S1)
+
+| Cell | Arm | Frames | Seed 1 | Seed 2 | Frame times inspected | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| i2v-bench-241 | naive | 241 | 390102b12db4 | 1f042b8c8b31 | 1, 2, 3, 3.5, 5, 8 s, f240 | no haze | Colour and foliage contrast steady to f240. Seed 1's camera is static; seed 2 pushes/arcs from about 5 s. |
+| i2v-bench-401 | naive | 401 | 62d74005a35c | c6d94bb1edac | 1, 3, 3.5, 5, 8, 12 s, f400 | no haze | f400 as sharp and saturated as 1 s on both. Seed 1 drifts left by 12–16.7 s; seed 2 near-static. |
+| i2v-bench-89 | remedy | 89 | 40b83c33b23a | 5413b87108de | 1, 2, 3, 3.5 s, f88 | no haze | Static. |
+| (control) L2 s1-static | control | 121 | 8625f73f4beb | 31d1f51392c8 | 0 s, f120 | no haze | Borrowed from L2: the same still and a static-camera prompt at 121 frames. |
+
+## L2: invented camera moves
+
+Stills (z-image, seed 1): S1 `asset:probe-1123-s1-bench.jpg` (job
+836e69c60940), S2 `asset:probe-1123-s2-kitchen.jpg` (bd8d69807e4c), S3
+`asset:probe-1123-s3-lighthouse.jpg` (f3044c7d87ab). Every L2 render is i2v at
+121 frames. Prompts `prompt:probe-1123/l2-s{1,2,3}-{none,static,locked}`: the
+same scene sentence per still, then no camera sentence (`none`), "the camera
+remains static" (`static`), or that plus "locked-off on a tripod, no pan, no
+zoom" (`locked`).
+
+| Cell | Arm | Seed 1 | Seed 2 | Frame times inspected | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- | --- |
+| s1-none | naive | b37a61236086 | 303bc7dcdb40 | 0, 2.5 s, f120 | static | Bench and background registered; the man turns his head. |
+| s1-static | remedy | 8625f73f4beb | 31d1f51392c8 | 0 s, f120 | static | Registered. |
+| s1-locked | remedy | ba03832525f9 | 43ec4a08bc2d | 0 s, f120 | static | Registered. |
+| s2-none | naive | 9650219d85a9 | 8e1147a306a7 | 0, 2.5 s, f120 | static | Window, shelves and plants registered; the woman pours or steps left inside a fixed frame. |
+| s2-static | remedy | 807397eaacf3 | 696a1b7dbe65 | 0 s, f120 | static | Registered. |
+| s2-locked | remedy | 2a62f1d3e46e | 6e7901458b80 | 0 s, f120 | static | Registered. |
+| s3-none | naive | d3baf1e6ac33 | c07fa80ef144 | 0, 2.5 s, f120 | ambiguous | Horizon and lighthouse fixed, but the foreground grass recedes and (seed 2) the left rocks look larger by f120: wind sway or a very slight forward drift. Not a clear move. |
+| s3-static | remedy | 96ca8ebd9196 | b56afa6a2875 | 0 s, f120 | static | Horizon and lighthouse fixed. The foreground grass changes the same way as in s3-none. |
+| s3-locked | remedy | 2fb65dba5d13 | 1a89971de09e | 0 s, f120 | static | As s3-static, grass change included. |
+
+The S3 grass change appears in all six S3 renders, with and without a camera
+sentence. That points to the prompted wind in the grass rather than a camera
+move, which is why s3-none is counted ambiguous and not as a failure. Even
+counting both as failures, the naive arm fails 2 of 6, under half, and the
+verdict stands.
+
+## Deviations from plan v2
+
+- **More L1 renders than the plan's minimum.** Each t2v prompt ran at 241
+  (naive), 121 (control) and 89 (remedy) frames, and the i2v still at 241,
+  401 and 89: 24 L1 renders in all.
+- **The i2v 121-frame control is borrowed** from L2 s1-static (same still,
+  static prompt, 121 frames) rather than run as a separate L1 cell; its note
+  names the L2 cell.
+- **Stills from z-image, not Klein.** The Klein route needed a 40 GB model
+  download; `models/z-image` was already on lem.
+- **Asset names are flat** (`probe-1123-s1-bench.jpg`), not in a folder.
+- **The L1 prompts all say "the camera remains static"**, to keep camera
+  motion out of the haze read.
+- **Fewer frames on some cells**: the dim and action 121-frame controls at
+  three times (1, 3 s, f120); the L2 remedy cells at two (0 s, f120), at
+  160 px. The 401-frame renders added a 12 s frame.
+- **Judged by eye**, since `assess_output` has no image or motion probe.
+
+## Infrastructure notes (not lesson findings)
+
+- The first denoise pass of a job on a cold worker takes about 50–64 s and
+  emits a warm-up warning.
+- A 401-frame i2v job spent about 330 s in decode and save.
+- The quiet-audio warnings on these jobs are irrelevant to L1 and L2: the
+  probes judge the picture only.

From a49d1987eae448969270e4cd94abfb9ac580d262 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 09:55:42 -0600
Subject: [PATCH 098/125] fix(stems): #1130 - read the BagOfModels
 max_allowed_segment so the short-clip no-shift branch is taken

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/voice_attribution.py | 5 ++++-
 tests/test_separate_stems.py  | 5 +++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/dw/tasks/voice_attribution.py b/dw/tasks/voice_attribution.py
index 1de66b3c..129ef610 100644
--- a/dw/tasks/voice_attribution.py
+++ b/dw/tasks/voice_attribution.py
@@ -586,7 +586,10 @@ def _run_separator_stems(waveform, sample_rate, device, dtype):
     # returned stems up to 17 dB louder than the mix, and different on every
     # run (#1130). Such a clip is separated as it is, once, which is exact
     # and repeatable.
-    segment = float(getattr(model, "segment", 0) or 0)
+    # (a BagOfModels has no `segment`; its `max_allowed_segment` is the one)
+    segment = float(getattr(model, "max_allowed_segment", 0) or 0)
+    if segment == float("inf"):
+        segment = 0.0
     shifts = 0 if mix.shape[-1] < segment * rate else 1
     with torch.no_grad():
         stems = apply_model(
diff --git a/tests/test_separate_stems.py b/tests/test_separate_stems.py
index 98dcb9ec..214f2be8 100644
--- a/tests/test_separate_stems.py
+++ b/tests/test_separate_stems.py
@@ -82,7 +82,8 @@ def test_stems_sum_back_to_the_mix(self):
         numpy.testing.assert_allclose(stems["vocals"].audio, source * 0.4, atol=1e-4)
 
     def test_clip_shorter_than_the_segment_is_not_shift_averaged(self):
-        # #1130: htdemucs' random-shift averaging blew up short clips
+        # #1130: random-shift averaging blew up short clips. The real model
+        # is a BagOfModels: max_allowed_segment, no `segment` attribute.
         seen = []
 
         def spy(model, mixture, device=None, split=True, shifts=1):
@@ -91,7 +92,7 @@ def spy(model, mixture, device=None, split=True, shifts=1):
 
         with (
             patch.dict(sys.modules, fake_demucs(spy)),
-            patch.object(FakeModel, "segment", 7.8, create=True),
+            patch.object(FakeModel, "max_allowed_segment", 7.8, create=True),
         ):
             separate_stems(AudioTrack(mix(1.0), RATE), device="cpu")
             separate_stems(AudioTrack(mix(9.0), RATE), device="cpu")

From 097e63340597ee7e08ce71bd7e362955c4048dd6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 10:38:02 -0600
Subject: [PATCH 099/125] feat(docs): #1127 - story-forge lessons 3, 4, 6
 probes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-11-story-forge-lessons.md     | 121 +++++++++++++++++-
 1 file changed, 119 insertions(+), 2 deletions(-)

diff --git a/docs/proposals/audits/2026-11-story-forge-lessons.md b/docs/proposals/audits/2026-11-story-forge-lessons.md
index 8198f4e6..25e6bde3 100644
--- a/docs/proposals/audits/2026-11-story-forge-lessons.md
+++ b/docs/proposals/audits/2026-11-story-forge-lessons.md
@@ -1,9 +1,10 @@
-# Story-forge lessons: record-only probes (#1123 stage A, #1126)
+# Story-forge lessons: record-only probes (#1123 stages A and B, #1126, #1127)
 
 Probe date: 2026-11-01. Server `lem` (2x RTX 3090), develop @ 2ca6ece8.
 Agent: claude-opus-5-5 (anthropic). Workspace `probe-1123`.
 No engine or skill file was changed. This document only records results.
-Stage B (#1123) adds the sections for lessons 3, 4 and 6.
+Stage B (#1127) added the sections for lessons 3, 4 and 6, probed the same
+day on develop @ f1020d8f by the same agent in the same workspace.
 
 Every render ran on the LTX-2.5 catalog templates as they stand on develop:
 `templates/ltx2/text-to-video` for t2v and `templates/ltx2/image-to-video` for
@@ -27,12 +28,23 @@ as loss of contrast, saturation or black level against the same render's 1 s
 frame. Camera motion was judged by registration of fixed background
 features (horizon, window frame, shelving, bench) across the inspected frames.
 
+Stage B (L3, L4, L6) judged the same way. L3 and L6 are LTX
+`templates/ltx2/text-to-video` at 121 frames, plus an H3
+`templates/minimax/dialogue-short` cell for L3. Contact was judged on frames at
+1, 2, 3, 4 s and f120 (f123 on H3's 124 frames), with hand crops where hands
+met. Impacts were judged at 1, 2, 3, 4 s and f120, plus 2.5, 3, 3.5 and 4.5 s
+around the strike. L4 is stills: each render's whole frame at 384 px, read for
+any legible text.
+
 ## Verdicts
 
 | # | Lesson | Verdict | Naive renders failing | Remedy renders clean |
 | --- | --- | --- | --- | --- |
 | L1 | LTX-2.5 renders haze over after 2–3.5 s; keep clips short (89 frames). | **not reproduced (on our pipeline at this N)** | 0 of 10 (6 t2v at 241, 2 i2v at 241, 2 i2v at 401) | 8 of 8 at 89 frames, but there was nothing to remove |
 | L2 | i2v invents camera moves unless the prompt pins the camera; "camera remains static" alone is not enough, add "locked-off on a tripod, no pan, no zoom". | **not reproduced (on our pipeline at this N)** | 0 of 6 clear moves; 2 of 6 ambiguous (S3, see below) | 6 of 6 "static", 6 of 6 "locked-off" show no move |
+| L3 | Bodies in contact (hugs, handshakes, a hand on a shoulder) fuse or grow limbs; stage the moment just before contact. | **not reproduced (on our pipeline at this N)** | LTX 2 of 6 (both handshakes, mild); H3 0 of 2 (1 brief ambiguous) | 6 of 6 clean, but 0 of 6 followed the restaging: every remedy render went on into contact |
+| L4 | An ALL-CAPS word in an image prompt renders as written text; write it in lowercase. | **not reproduced (on our pipeline at this N)** | 0 of 6 (z-image only; Klein not run) | 6 of 6, but there was nothing to remove |
+| L6 | Impacts (a strike, a slam) break physics; show the effort, not the impact. | **not reproduced (on our pipeline at this N)** | 1 of 4 (axe seed 1); both door renders never showed the slam | 3 of 4 clean, 1 ambiguous (door seed 2 closes softly) |
 
 L1's two questions:
 - **(i) Does haze set in at a fixed time from the start?** No. No render, at
@@ -115,6 +127,82 @@ move, which is why s3-none is counted ambiguous and not as a failure. Even
 counting both as failures, the naive arm fails 2 of 6, under half, and the
 verdict stands.
 
+## L3: bodies in contact
+
+Prompts `probe-1123/l3-{hug,handshake,shoulder}` (naive: the contact shown)
+and `probe-1123/l3-{hug,handshake,shoulder}-before` (remedy: the same two
+people staged in the moment just before contact). All say "the camera remains
+static". LTX t2v, 121 frames.
+
+| Cell | Arm | Seed 1 | Seed 2 | Frame times inspected | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- | --- |
+| hug | naive | 2c8e2fd11a64 | a0bf15587a17 | 1, 2, 3, 4 s, f120; hand crop at 1, 3 s | clean | Clean hugs. Hands on backs are plausible, five fingers, no fusion. |
+| hug-before | remedy | 2b5294666c7b | 8b1b00b412b0 | 1, 2, 3, 4 s, f120 | clean, restaging not followed | Both go on into a full hug by 4 s and hold it to f120. Clean, but in contact. |
+| handshake | naive | 1e54ba7c709e | 33537ba0f0b5 | 1, 2, 3, 4 s, f120; hand crop at 1, 3 s | **fail (mild)** | Seed 1: the clasp at 3 s is a smeared, fused blob with no finger separation. Seed 2: fused or fanned fingers (an apparent extra) at first contact at 1 s, a plausible clasp by 3 s. Motion blur may contribute to both. |
+| handshake-before | remedy | 35efb75713d0 | 030338233ca5 | 1, 2, 3, 4 s, f120; hand crop at 3 s, f120 (seed 1) | clean, restaging not followed | Both shake hands by about 2–3 s and hold to f120. Seed 1's clasp is plausible in the crop. |
+| shoulder | naive | 486626742b05 | b50872edf631 | 1, 2, 3, 4 s, f120 | clean | Workshop, an old man and a girl. The hand settles on the shoulder by 3 s; an exchange of looks by f120. |
+| shoulder-before | remedy | 66934ce13ed3 | 376441d1abca | 1, 2, 3, 4 s, f120 | clean, restaging not followed | Both rest the hand on the shoulder by 3 s. |
+
+H3 cell, `templates/minimax/dialogue-short` with one shot (`hug`, 124
+frames), the template's own drawn portraits, and the hug prompt stored as
+`probe-1123/l3-h3-hug`. Naive arm only.
+
+| Cell | Arm | Seed 1 | Seed 2 | Frame times inspected | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- | --- |
+| h3-hug | naive | a793f12f9d8c | 134084669ce8 | 1, 2, 3, 4, 5 s; hug crop at 3, 5 s (seed 1), 2, 4 s (seed 2) | clean (seed 2 ambiguous at 2 s) | A station platform: the two step together and embrace by 2–3 s and hold to the end. Seed 1: hands on backs clean, rings and watch intact. Seed 2: at 2 s, as the arms close, four hands show at once with one motion-blurred over his shoulder, which is hard to assign to an arm. By 4 s it resolves into a clean embrace. Counted ambiguous, not a failure. |
+
+Tally: the naive arm fails 2 of 6 on LTX (both handshakes, mild) and 0 of 2
+on H3. That is under half, so the lesson is not reproduced. The remedy
+cannot be credited either way: LTX did not follow "just before contact" in
+any of 6 renders, and every remedy clip reached the contact it was staged to
+avoid, cleanly. On this pipeline, if contact is to be avoided, the prompt
+has to do more than stage the moment before it.
+
+## L6: impacts
+
+Prompts `probe-1123/l6-{axe,door}` (naive: the strike or slam) and
+`probe-1123/l6-{axe,door}-effort` (remedy: the effort before the impact, for
+example the axe raised overhead, or her gripping a door that stands wide open,
+"shot holds before the door moves"). LTX t2v, 121 frames, "the camera remains
+static".
+
+| Cell | Arm | Seed 1 | Seed 2 | Frame times inspected | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- | --- |
+| axe | naive | 6be90fe35d6b | 176f482ff752 | 1, 2, 3, 4 s, f120; crop at 2.5, 3, 3.5, 4.5 s | **fail (seed 1)** | Seed 1: a clean strike at 3 s and a half flying off right at 3.5 s, but by 4.5 s a whole log is back on the block with the axe in it, and pieces lie on the ground. The log re-forms or duplicates. Seed 2: the impact at 3 s is motion blur; by 4 s the block is empty with pieces on the ground. Plausible. |
+| axe-effort | remedy | 90e028d7e9a4 | 1088ba878fa5 | 1, 3 s, f120 | clean | Axe raised overhead to f120, no strike, no artifacts. In seed 2 the axe head comes to rest on the top of the log at the end. |
+| door | naive | 004112bab9e8 | 8d9afda0c95e | 1, 2, 3, 4 s, f120 | impact not depicted | The slam is never rendered. Seed 1: she presses on an already-closed door, with a reframe between 1 and 2 s. Seed 2: the door is near-shut at 1 s and she reaches for the handle at 3 s. No pass-through and no morph. The coat rack and picture are in the prompt, so they are not inventions. |
+| door-effort | remedy | b658f4bd3d82 | f87c4fe72657 | 1, 3 s, f120 | seed 1 clean, seed 2 ambiguous | Seed 1: she holds the open door, with the street visible through it, to f120. Seed 2: the door is open at 1 s, but closed or near-closed by f120 with her gripping it. It moved against the prompt, but with no artifact. |
+
+Tally: the naive arm fails 1 of 4 (axe seed 1), under half, so the lesson is
+not reproduced. The door renders are not counted as failures: LTX never
+showed the slam at all, so there was no impact to break. The remedy arm is
+clean in 3 or 4 of 4.
+
+## L4: ALL-CAPS words render as text
+
+Prompts `probe-1123/l4-{proud,alone,hurry}-{caps,lower}`: a baker holding a
+tray of croissants, "PROUD"/"proud" of them; a man alone in the rain at night,
+"ALONE"/"alone"; a girl in a yellow raincoat running to a red door in a
+"HURRY"/"hurry". The caps and lowercase prompts differ only in that one word's
+case. Stills from `models/z-image` at its defaults (960x544). Klein was not
+run (see Deviations).
+
+| Cell | Arm | Seed 1 | Seed 2 | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- |
+| proud | naive (caps) | b8f4028b4aca (run 20261101-162016-d3bd254a) | effa9b4d219c (20261101-162040-2ce53f0c) | no text | Baker smiling over a tray of croissants. No lettering anywhere: no sign, apron print or tray label. |
+| proud | remedy (lower) | run 20261101-162055-a3f9299d | run 20261101-162104-4e593ae9 | no text | Near-identical compositions to the caps renders, seed for seed. |
+| alone | naive (caps) | run 20261101-162112-831cc4c7 | run 20261101-162126-4574d07c | no text | Hooded man on a wet street at night. Shop fronts and signs stay blurred and illegible; "ALONE" appears nowhere. |
+| alone | remedy (lower) | run 20261101-162126-39518976 | run 20261101-162140-82c30056 | no text | Near-identical to the caps renders, seed for seed. |
+| hurry | naive (caps) | run 20261101-162147-4e6336c8 | run 20261101-162155-50cd07ed | no text | Girl running to a red door. No lettering on the door, wall or coat. |
+| hurry | remedy (lower) | f47fcbf043b0 (run 20261101-162207-258573e2) | 855955966ac3 (20261101-162209-dc42ad71) | no text | Near-identical to the caps renders, seed for seed. |
+
+Tally: the caps word appears as legible text in 0 of 6 caps renders and 0 of
+6 lowercase ones, so the plan's "holds" test (at least half of the caps
+renders, none of the lowercase) fails. Not reproduced on z-image. The case of
+the word changed nearly nothing: each caps/lowercase pair at the same seed is
+close to the same picture. Whether Klein, the family the lesson was written
+against, behaves differently is untested here.
+
 ## Deviations from plan v2
 
 - **More L1 renders than the plan's minimum.** Each t2v prompt ran at 241
@@ -133,6 +221,26 @@ verdict stands.
   160 px. The 401-frame renders added a 12 s frame.
 - **Judged by eye**, since `assess_output` has no image or motion probe.
 
+Stage B (#1127):
+- **More L3 LTX renders than the plan's 8**: three contact cells (hug,
+  handshake, hand on shoulder), each in both arms × 2 seeds, 12 in all.
+- **The H3 cell has no remedy arm**: one `hug` shot of 124 frames per seed,
+  with the template's own drawn portraits. The shot prompt was written inline
+  in the shots item; the same text is stored as `probe-1123/l3-h3-hug`.
+- **L4 rests on z-image only.** The Klein half (`templates/flux3/text-to-image`)
+  was not run: Klein is not on lem, and the download is 40.3 GB, a `spend`
+  decision this stage does not hold. The L4 verdict therefore says nothing
+  about Klein.
+- **The remedy restagings were not followed by LTX** in L3 (0 of 6) and only
+  partly in L6 (the door seed 2 closed). The tables record what rendered, not
+  what was asked.
+- **The L6 door impact was never depicted** in either naive render, so that
+  cell tests nothing about impact physics.
+- **Fewer frames on some remedy cells** (1, 3 s, f120 on L6 remedies); hand
+  and impact crops on the cells where contact or a strike happened.
+- **Every L3 and L6 prompt says "the camera remains static"**, to keep camera
+  motion out of the read.
+
 ## Infrastructure notes (not lesson findings)
 
 - The first denoise pass of a job on a cold worker takes about 50–64 s and
@@ -140,3 +248,12 @@ verdict stands.
 - A 401-frame i2v job spent about 330 s in decode and save.
 - The quiet-audio warnings on these jobs are irrelevant to L1 and L2: the
   probes judge the picture only.
+- Stage B: the first two LTX decodes on a fresh worker took 93 s and 125 s
+  (the warm-decode warning); later decodes took about 2 s, and warm LTX
+  121-frame jobs about 35–50 s each.
+- The first z-image job loaded in 17.4 s; warm z-image jobs ran about 14 s.
+- An H3 single-shot `dialogue-short` job ran about 6–9 min on one 3090; the
+  first denoise pass on a cold H3 load took 206 s, against about 30 s warm.
+- The clipping and quiet-audio warnings on L6 jobs are irrelevant: the probes
+  judge the picture only. `dialogue-short` warns that `audio_bleed_ms` has no
+  effect with one shot, which is expected.

From 580365cafb7218444be61af60dca9878381ff198 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 10:48:46 -0600
Subject: [PATCH 100/125] fix(tasks): #1134 - attribute_voices accepts an audio
 step's output (AudioTrack) as a voice reference

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/voice_attribution.py   | 27 +++++++++++++++++++--------
 tests/test_voice_attribution.py | 24 ++++++++++++++++++++++++
 2 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/dw/tasks/voice_attribution.py b/dw/tasks/voice_attribution.py
index 129ef610..2efcbb88 100644
--- a/dw/tasks/voice_attribution.py
+++ b/dw/tasks/voice_attribution.py
@@ -246,6 +246,12 @@ def _voices_hold_reference(voices):
     return False
 
 
+def _is_track(reference):
+    """Whether a voice's reference is a generated audio step's output (an
+    AudioTrack, or anything carrying `.audio`) rather than a path or spans."""
+    return hasattr(reference, "audio") and hasattr(reference, "sample_rate")
+
+
 def parse_voices(voices, duration, min_reference_seconds, clip_duration=None):
     """The voices argument as {name: spans | clip path}, checked.
 
@@ -274,7 +280,7 @@ def parse_voices(voices, duration, min_reference_seconds, clip_duration=None):
                 f"{COMMAND}: voice name {name!r} is not allowed - letters, "
                 f"digits, '_' and '-', starting with a letter or '_' ({error})"
             ) from error
-        if isinstance(reference, str):
+        if isinstance(reference, str) or _is_track(reference):
             length = clip_duration(reference) if clip_duration else None
             parsed[name] = reference
         else:
@@ -662,9 +668,13 @@ def embed(encoder, samples):
 
 
 def _clip_duration(path, clips):
-    """Load a reference clip into `clips` and answer its length in seconds."""
-    clip, rate = load_audio(path)
-    clips[path] = (clip, rate)
+    """Load a reference clip (a path, or an audio step's output) into `clips`
+    and answer its length in seconds."""
+    if isinstance(path, str):
+        clip, rate = load_audio(path)
+    else:
+        clip, rate = waveform_and_rate(path, None, COMMAND)
+    clips[path if isinstance(path, str) else id(path)] = (clip, rate)
     return clip.shape[1] / rate
 
 
@@ -678,9 +688,10 @@ def _embed_references(references, clips, song, encoder, separate, device, dtype)
     """One embedding per voice, from its clip or its spans of the song."""
     embeddings = {}
     for name, reference in references.items():
-        if isinstance(reference, str):
+        if isinstance(reference, str) or _is_track(reference):
+            key = reference if isinstance(reference, str) else id(reference)
             clip = _Voicing(
-                _stem(*clips[reference], separate, device, dtype),
+                _stem(*clips[key], separate, device, dtype),
                 _EMBEDDER_SAMPLE_RATE,
             )
             samples = clip.samples([(0.0, len(clip.waveform) / clip.sample_rate)])
@@ -817,8 +828,8 @@ def attribute_voices(
             earlier step's audio or video.
         voices: Each voice's name mapped to its reference: a list of
             {start_seconds, duration_seconds} (or {start, end}) spans into
-            'audio' itself, or a path/'asset:' of a separate clip of that
-            voice. At least 2 voices; names follow the variable-name pattern
+            'audio' itself, or a path/'asset:' (or a previous_result: audio step)
+            of a separate clip of that voice. At least 2 voices; names follow the variable-name pattern
             (letters, digits, '_', '-').
         lines: The spans to attribute, in seconds - a list of {start, end,
             text?} (transcribe_audio's chunk shape) or {start_seconds,
diff --git a/tests/test_voice_attribution.py b/tests/test_voice_attribution.py
index 7ad9f3f8..9edf083f 100644
--- a/tests/test_voice_attribution.py
+++ b/tests/test_voice_attribution.py
@@ -80,6 +80,30 @@ def tearDownModule():
 
 
 class TestValidationErrors(unittest.TestCase):
+    def test_an_audio_track_reference_is_a_clip_measured_by_its_length(self):
+        # #1134: previous_result: of an audio step resolves to an AudioTrack
+        from dw.media_types import AudioTrack
+        from dw.tasks.voice_attribution import _clip_duration, parse_voices
+
+        clips = {}
+        track = AudioTrack(numpy.zeros((1, 24000 * 5), dtype=numpy.float32), 24000)
+        parsed = parse_voices(
+            {"a": [{"start_seconds": 0, "duration_seconds": 4}], "b": track},
+            10.0,
+            3.0,
+            lambda reference: _clip_duration(reference, clips),
+        )
+        self.assertIs(parsed["b"], track)
+        self.assertIn(id(track), clips)
+        short = AudioTrack(numpy.zeros((1, 24000), dtype=numpy.float32), 24000)
+        with self.assertRaisesRegex(ValueError, "voice 'b' has 1.00 s"):
+            parse_voices(
+                {"a": [{"start_seconds": 0, "duration_seconds": 4}], "b": short},
+                10.0,
+                3.0,
+                lambda reference: _clip_duration(reference, clips),
+            )
+
     def test_fewer_than_two_voices_is_an_error(self):
         with self.assertRaisesRegex(ValueError, "at least 2 voices"):
             attribute_voices(

From ee14a9f70ec6017f6522a83e1e2514a1ec0e3f87 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 10:52:12 -0600
Subject: [PATCH 101/125] feat(docs): #1127 - L4 table cites job ids, not run
 ids

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-11-story-forge-lessons.md          | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/proposals/audits/2026-11-story-forge-lessons.md b/docs/proposals/audits/2026-11-story-forge-lessons.md
index 25e6bde3..1ade727a 100644
--- a/docs/proposals/audits/2026-11-story-forge-lessons.md
+++ b/docs/proposals/audits/2026-11-story-forge-lessons.md
@@ -184,17 +184,17 @@ Prompts `probe-1123/l4-{proud,alone,hurry}-{caps,lower}`: a baker holding a
 tray of croissants, "PROUD"/"proud" of them; a man alone in the rain at night,
 "ALONE"/"alone"; a girl in a yellow raincoat running to a red door in a
 "HURRY"/"hurry". The caps and lowercase prompts differ only in that one word's
-case. Stills from `models/z-image` at its defaults (960x544). Klein was not
+case. Stills from `models/z-image` at its defaults (960x544), each judged on its whole image (`get_output_image`), which is the "frame inspected". Klein was not
 run (see Deviations).
 
 | Cell | Arm | Seed 1 | Seed 2 | Verdict | Observation |
 | --- | --- | --- | --- | --- | --- |
-| proud | naive (caps) | b8f4028b4aca (run 20261101-162016-d3bd254a) | effa9b4d219c (20261101-162040-2ce53f0c) | no text | Baker smiling over a tray of croissants. No lettering anywhere: no sign, apron print or tray label. |
-| proud | remedy (lower) | run 20261101-162055-a3f9299d | run 20261101-162104-4e593ae9 | no text | Near-identical compositions to the caps renders, seed for seed. |
-| alone | naive (caps) | run 20261101-162112-831cc4c7 | run 20261101-162126-4574d07c | no text | Hooded man on a wet street at night. Shop fronts and signs stay blurred and illegible; "ALONE" appears nowhere. |
-| alone | remedy (lower) | run 20261101-162126-39518976 | run 20261101-162140-82c30056 | no text | Near-identical to the caps renders, seed for seed. |
-| hurry | naive (caps) | run 20261101-162147-4e6336c8 | run 20261101-162155-50cd07ed | no text | Girl running to a red door. No lettering on the door, wall or coat. |
-| hurry | remedy (lower) | f47fcbf043b0 (run 20261101-162207-258573e2) | 855955966ac3 (20261101-162209-dc42ad71) | no text | Near-identical to the caps renders, seed for seed. |
+| proud | naive (caps) | b8f4028b4aca | effa9b4d219c | no text | Baker smiling over a tray of croissants. No lettering anywhere: no sign, apron print or tray label. |
+| proud | remedy (lower) | d4987b9329bc | 556194c9ed5b | no text | Near-identical compositions to the caps renders, seed for seed. |
+| alone | naive (caps) | 06f277c06d19 | 64431b97bb07 | no text | Hooded man on a wet street at night. Shop fronts and signs stay blurred and illegible; "ALONE" appears nowhere. |
+| alone | remedy (lower) | 2ecb218715f6 | e62c2c0baa8d | no text | Near-identical to the caps renders, seed for seed. |
+| hurry | naive (caps) | 57fcba14cfcd | 137cc3206146 | no text | Girl running to a red door. No lettering on the door, wall or coat. |
+| hurry | remedy (lower) | f47fcbf043b0 | 855955966ac3 | no text | Near-identical to the caps renders, seed for seed. |
 
 Tally: the caps word appears as legible text in 0 of 6 caps renders and 0 of
 6 lowercase ones, so the plan's "holds" test (at least half of the caps

From d6c3fbfd3fe3360bd26f9a3e452fdd31e0ab89db Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 10:54:36 -0600
Subject: [PATCH 102/125] docs(proposals): #1112 - Audio8-TTS voice cloning
 design record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/audio8-voice-clone-complete.md   | 174 ++++++++++++++++++
 docs/proposals/todo.md                        |   8 +
 2 files changed, 182 insertions(+)
 create mode 100644 docs/proposals/complete/audio8-voice-clone-complete.md

diff --git a/docs/proposals/complete/audio8-voice-clone-complete.md b/docs/proposals/complete/audio8-voice-clone-complete.md
new file mode 100644
index 00000000..c8b452c1
--- /dev/null
+++ b/docs/proposals/complete/audio8-voice-clone-complete.md
@@ -0,0 +1,174 @@
+# Audio8-TTS voice cloning for `generate_speech` (#1112)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). Plan v2 approved by Don on 2026-11-01 as "build smaller":
+stage A (a listening gate, run outside dw) passed, then stages #1120 (B)
+and #1121 (C) were built and verified. The plan comment on #1112 is the
+full design; this doc records what shipped against it.
+
+## The idea
+
+Zero-shot voice cloning: a reference clip plus its exact transcript, then
+new lines spoken in that voice, in many languages, from
+[Edge0/Audio8-TTS-Realistic-0.6b](https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b)
+(Apache-2.0 with a NOTICE; a DualAR model with a bundled 44.1 kHz codec and
+a 2,048-position context). Before this, the only varied-voice route was
+SpeechT5 with a `speaker_embedding` clip, and there was no non-English TTS
+voice. As shipped, the model ran only with `trust_remote_code=True` and
+pinned `transformers<5`, so the route was to vendor and port it.
+
+## Decisions
+
+- **Gate first (stage A).** Don's interactive session ran the upstream
+  code once, on lem, in a throwaway venv outside dw (Q4: a one-time
+  authorization, not a standing one). The same lines were generated by
+  (a) Audio8 cloning the #1096 `tag` vocals stem, (b) SpeechT5 +
+  `speaker_embedding` from that clip and (c) Bark presets, in English and
+  Russian, seed 1112. ECAPA similarity to the reference: Audio8 EN
+  0.56–0.64, RU 0.33–0.37; SpeechT5 0.14–0.20; Bark −0.08–0.10. Whisper
+  read every line back. Recordings and scripts:
+  `lem:/home/don/audio8-stageA/`.
+- **Verdict (Don, 2026-11-01): clearly better.** Named uses: series timbre
+  references (the H3 voice-timbre reference input) and Russian speech.
+- **Q1:** load `codec.pth` with `torch.load(weights_only=True)` at the
+  pinned revision `1e857568bfd4f02931aca3988ee773a44d2d26d3`; no
+  safetensors conversion, no dw-owned repo.
+- **Q2:** a reference longer than 20 s is refused.
+- **Q3:** one plugin line in `minimax-h3/references/dialogue.md`;
+  `SKILL.md` untouched (it was at 12,287 of 12,288 bytes).
+- **No `language` argument:** stage A generated Russian from the text
+  alone.
+
+## What was built
+
+### Stage B, #1120: the vendored model module
+
+`dw/tasks/audio8_tts_model.py` (about 2,000 lines): the upstream config,
+DualAR model, codec and processor at `1e857568`, ported to transformers
+≥5.19. Header in the `rife_model.py` shape with the Apache-2.0 licence and
+the upstream NOTICE; `docs/ATTRIBUTIONS.md` row. Inert on landing.
+
+Deviations from the plan, none changing scope:
+- **No transformers base classes at all.** A plain config class with
+  `from_json_file`, plain-dict outputs, logits processors and stopping
+  criteria as lists of callables. The model is built on meta and loaded
+  with `load_state_dict(strict=True, assign=True)`; the state-dict keys and
+  shapes were checked against the real checkpoint headers.
+- **No Hub I/O, no torchaudio.** Local paths only; resampling and loading
+  go through dw's own audio helpers. Upstream's `reference_codes` `np.load`
+  input was dropped, and a reference given as a URL is refused.
+- **Weight norm folded at load**, and the snake activation runs eagerly
+  instead of under `torch.jit.script`.
+- **Security sweep of the code as vendored:** no subprocess, `os.system`,
+  `eval` or `exec` upstream; Hub fetches and the `trust_remote_code`
+  passthrough were dropped.
+
+Tests: `tests/test_audio8_tts_model.py`, 14 tests (a tiny model through
+`generate` → `decode_audio` on CPU, logits matching the source, the
+weight-norm fold, the codec frame grid, the processor, the `weights_only`
+spy, and no Hub names in the module).
+
+### Stage C, #1121: wiring, template, docs
+
+- **Dispatch.** `generate_speech` has an explicit branch for
+  `Edge0/Audio8-TTS-Realistic-0.6b` ahead of `pipeline("text-to-speech")`.
+  The trust gate runs first, then the argument checks, then the load.
+  Cache key `("speech_generation", repo, device, dtype, revision)`; output
+  a 44.1 kHz mono `AudioTrack`.
+- **Pinned weights.** `required_weights` returns `file_entries` at
+  `1e857568` for `config.json`, `generation_config.json`,
+  `model.safetensors`, `tokenizer.json` and `codec.pth`, each fetched with
+  `hf_hub_download(revision=)`.
+- **Arguments.** `reference_audio` and `reference_text` each need the other
+  (an empty transcript counts as missing). Both are refused on any other
+  model; `speaker_embedding`, `voice_preset` and `messages` are refused on
+  Audio8. No reference means the default voice.
+- **Length.** A reference over 20 s, and text estimated not to fit the
+  context, are refused before the load, never truncated.
+- **Catalog.** `workflows/templates/voice-clone.json` (shape `audio`,
+  `has-audio` + `needs-input-media`, with the model card's consent note);
+  `reference_audio` in `catalog_shape._MEDIA_ARGUMENTS`; one line in
+  `generate-speech.json`'s description.
+- **Docs.** `docs/TASKS.md` (Speech Generation row, both arguments, a
+  "Cloning a voice" section), `docs/SECURITY.md` (the codec load and the
+  remote-code argument refusal), and the plugin line in
+  `minimax-h3/references/dialogue.md`.
+
+Deviations from the plan, none changing scope:
+- bf16 on CUDA, fp32 elsewhere.
+- The fit check is an estimate from text length; a line that passes it but
+  doesn't finish inside the context is refused after generation
+  (`finished` false), never returned cut off.
+- `max_new_tokens` defaults to the room left in the context (up to 2048),
+  not the generation config's 512.
+- `generate_kwargs` / `forward_params` on Audio8 are allowlisted:
+  `temperature`, `top_p`, `top_k`, `do_sample`, `max_new_tokens`.
+- The seed goes to `generate` through an explicit `torch.Generator`,
+  because the codec's lazy construction consumed the global RNG and made
+  the first take differ from later ones.
+- `COMPACT_BUDGET` in `tests/test_catalog_structure.py` raised from 12,400
+  to 12,480.
+
+### Bounce fix (C): top-level Hub-code arguments
+
+`generate_speech` now refuses `trust_remote_code`, `custom_pipeline` and
+`custom_generate` given as top-level step arguments, for every model
+(Audio8, Bark, SpeechT5, the default), before anything loads:
+`UntrustedWorkflowError` when untrusted, a `ValueError` when trusted, a
+falsy value allowed. Before, a kwargs task dropped them silently. No Hub
+code loaded either way (the model is vendored and Bark/SpeechT5 never read
+the key), but the step ran with no refusal and no warning.
+
+## Verification
+
+Over MCP on lem. B: C-F595 (no MCP-visible change). C: C-F596 to
+C-F602, SE-F056, SE-F057 all pass. An English and a Russian clone each came
+back 44.1 kHz mono with the line read back by Whisper, closer to the
+reference than Bark; the same seed gave the same duration; no remote-code
+activity in the events; every refusal before any load; the 20 s cap exact
+at 20.0 s; a ~400-word line refused at 4549 of 2048 positions.
+
+## Bounces per stage
+
+| Stage | Bounces | Why |
+|---|---|---|
+| A | — | Not dw code; Don's session. |
+| B (#1120) | 0 | The build's deploy script reported failure though the server had restarted healthy (its startup check missed the restart); Don's session confirmed health and handed it on. Not a tester bounce. |
+| C (#1121) | 1 | SE-F057 probes a and d: top-level `trust_remote_code` / `custom_pipeline` were dropped silently rather than refused (fixed above). Separately, two tester sessions died on C-F602 arm 4, whose 40× repeated sentence tripped the API's output filter; the driver parked the stage, and the case was rewritten in harnest's suite with original prose. Not a code fault. |
+
+Cost per stage: the stage comments carry no `usage:` figures, so it is left
+out. The plan estimated B at $8–12 and C at $4–6; stage A cost no agent
+spend.
+
+## Not built, and why
+
+- Streaming, SGLang serving, fine-tuning, other Audio8 checkpoints:
+  non-goals.
+- Bark stays the default `generate_speech` model and the H3 timbre
+  template's default; `voice-clone` is named as an alternative.
+- A Russian reference clip for Russian output (the English-reference
+  Russian clones sit near ECAPA's same-speaker line): not probed, out of
+  scope.
+
+## Known edges
+
+- **The template's `reference_audio` default is `asset:voice.wav`**, a
+  placeholder that names no real asset. The variable is required, so a run
+  without one is refused at validate (C-F597); a caller must supply a clip.
+- **The remote-code argument refusals happen at run time**, not validate
+  time, like the `forward_params` / `generate_kwargs` gate before them.
+- **No job event names the pinned revision** when it loads; the pin is
+  visible in the validate plan's `downloads_required`.
+- **Transcribe with a large Whisper for `reference_text`.** The default
+  `whisper-base` badly mis-transcribed the QA reference;
+  `openai/whisper-large-v3-turbo` was close.
+- **Port drift.** A future transformers bump touches little (no base
+  classes are used), but the tiny-model test is the tripwire.
+- Found during verify, filed and fixed separately: #1134 (`attribute_voices`
+  refused a `previous_result:` voice reference).
+
+## Reopen triggers
+
+- Edge0 ships a transformers-5 release, or the architecture lands in
+  transformers: the vendored module could shrink to a pin.
+- A newer Audio8 revision: re-review the code before moving `REVISION`.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 734f3b2c..64ac0364 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -471,6 +471,14 @@ remaining deferred fix is recorded in
   is skipped for a refused reference. The guide no longer promises the form.
   Record, including the deferred in-list cutaway:
   `complete/for-each-cross-entry-complete.md`.
+- **Audio8-TTS voice cloning in `generate_speech`** (#1112, stages #1120,
+  #1121), shipped 2026-11-01, after a listening gate Don judged clearly
+  better than SpeechT5 + `speaker_embedding` and Bark. A vendored,
+  transformers-5 port (no Hub code) with weights and `codec.pth` pinned at
+  one revision (`weights_only=True`); `reference_audio` + `reference_text`
+  clone a voice in English, Russian and more, with a 20 s reference cap and
+  a context-fit refusal. Template `voice-clone`. Record, including the
+  known edges: `complete/audio8-voice-clone-complete.md`.
 
 ## Declined
 

From 9f672175edc42bc91fd98b942c8320bb1dddabc4 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 11:25:35 -0600
Subject: [PATCH 103/125] feat(tasks): #1131 - vendored MMAudio flow network,
 Euler sampler and DFN5B CLIP key map

Inert modules (nothing in dw imports them yet):
- dw/tasks/mmaudio_model.py: MMAudio large_44k_v2 network ported from
  hkchengrex/MMAudio @ 974010a0, our own Euler loop with CFG and the
  empty-condition path, strict weights_only load.
- dw/tasks/mmaudio_clip.py: DFN5B open_clip -> transformers key map,
  patch_clip-equivalent normalised features, in-memory only.
- tests/test_mmaudio_model.py and ATTRIBUTIONS rows (MIT code,
  CC-BY-NC 4.0 weights, Apple AMLR DFN5B).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ATTRIBUTIONS.md        |  12 +
 dw/tasks/mmaudio_clip.py    | 399 +++++++++++++++++++
 dw/tasks/mmaudio_model.py   | 772 ++++++++++++++++++++++++++++++++++++
 tests/test_mmaudio_model.py | 539 +++++++++++++++++++++++++
 4 files changed, 1722 insertions(+)
 create mode 100644 dw/tasks/mmaudio_clip.py
 create mode 100644 dw/tasks/mmaudio_model.py
 create mode 100644 tests/test_mmaudio_model.py

diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
index 2559fdcd..61b8e538 100644
--- a/docs/ATTRIBUTIONS.md
+++ b/docs/ATTRIBUTIONS.md
@@ -17,9 +17,21 @@ Each file keeps its upstream licence notice in its header.
 | [dw/tasks/rife_model.py](../dw/tasks/rife_model.py) | The RIFE interpolation network from [hzwer/Practical-RIFE](https://github.com/hzwer/Practical-RIFE) | MIT, Copyright (c) Megvii Inc. |
 | [dw/tasks/h3_latent_upscaler_model.py](../dw/tasks/h3_latent_upscaler_model.py) | The MiniMax H3 3D-convolution latent upscaler from [LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler](https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler) | MIT, Copyright (c) LBH-123-AI |
 | [dw/tasks/audio8_tts_model.py](../dw/tasks/audio8_tts_model.py) | The Audio8-TTS (ArkTTS) dual-AR speech model, codec and processor from [Edge0/Audio8-TTS-Realistic-0.6b](https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b/tree/1e857568bfd4f02931aca3988ee773a44d2d26d3), ported (upstream NOTICE kept in the file header) | Apache-2.0 |
+| [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py), [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | The MMAudio flow-matching network, its sequence lengths and classifier-free guidance, and the CLIP conditioning from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24), ported (the sampler is dw's own Euler loop, and the DFN5B towers are transformers' CLIP models filled by a key map) | MIT, Copyright (c) 2024 Sony Research Inc. |
 | [dw/community_pipelines/pipeline_flux_rf_inversion.py](../dw/community_pipelines/pipeline_flux_rf_inversion.py) | The diffusers community RF-Inversion pipeline, after [RF Inversion](https://rf-inversion.github.io/) by Litu Rout, Yujia Chen, Nataniel Ruiz, Constantine Caramanis, Sanjay Shakkottai and Wen-Sheng Chu | Apache-2.0, Copyright 2024 Black Forest Labs and The HuggingFace Team |
 | [dw/prompt_weighting.py](../dw/prompt_weighting.py) | Based on [sd_embed](https://github.com/xhinker/sd_embed) by Andrew Zhu | Apache-2.0 |
 
+## Model weights with their own terms
+
+Most weights are named only by their catalog entry. These are listed here as
+well, because their terms are narrower than this repository's licence and
+apply to anything generated with them.
+
+| Weights | Used by | Licence |
+|---|---|---|
+| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) (`weights/mmaudio_large_44k_v2.pth` and its `ext_weights/`) | [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [apple/DFN5B-CLIP-ViT-H-14-384](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384) | MMAudio's CLIP conditioning, [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | [Apple Machine Learning Research Model License](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384/blob/main/LICENSE): research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. dw maps the weights into transformers' layout in memory at load time and never writes or ships converted tensors. |
+
 ## Ideas reimplemented here
 
 These projects showed an approach that dw rebuilt in its own code for
diff --git a/dw/tasks/mmaudio_clip.py b/dw/tasks/mmaudio_clip.py
new file mode 100644
index 00000000..34bf675c
--- /dev/null
+++ b/dw/tasks/mmaudio_clip.py
@@ -0,0 +1,399 @@
+"""
+DFN5B CLIP conditioning for MMAudio (dw/tasks/mmaudio_model.py), v1.
+
+Ported from https://github.com/hkchengrex/MMAudio at commit
+974010a026c731054592d8f777218bd9d85a6c24: the CLIP parts of
+mmaudio/model/utils/features_utils.py (with its patch_clip). The
+weights are apple/DFN5B-CLIP-ViT-H-14-384's open_clip checkpoint
+(CLIP_REPO_ID / CLIP_REVISION), under the Apple Machine Learning Research
+Model License (research purposes only). "Apple Machine Learning Research
+Model is licensed under the Apple Machine Learning Research Model License
+Agreement."
+
+Carried over as written: what upstream reads from the two towers - the image
+tower's normalised projected embedding per frame (encode_video_with_clip),
+and, through upstream's patch_clip, the text tower's normalised last hidden
+states for every one of the 77 token positions rather than the pooled
+embedding; and the CLIP pixel statistics.
+
+Changed in the port, so nothing here touches the Hub or imports open_clip:
+- The towers are transformers' CLIPVisionModelWithProjection and
+  CLIPTextModel, built from DFN5B's open_clip dimensions (ClipConfig, the
+  image side at upstream's 384 pixels) and filled by a key map from the
+  open_clip state dict at load time (open_clip_to_transformers). The mapped
+  tensors are never written to disk. load_clip() reads a local path its
+  caller gives, with torch.load(weights_only=True) or safetensors.
+- The tokenizer is the repository's tokenizer.json read with tokenizers,
+  laid out as open_clip lays it out: start token, text, end token, padded
+  with 0 to 77 tokens. open_clip's ftfy text repair is not carried.
+
+MIT License
+
+Copyright (c) 2024 Sony Research Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from __future__ import annotations
+
+import html
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+CLIP_REPO_ID = "apple/DFN5B-CLIP-ViT-H-14-384"
+CLIP_REVISION = "01b771ed0d1395ca5ffdd279897d665ebe00dfd2"
+CLIP_WEIGHTS_FILE = "open_clip_pytorch_model.bin"
+CLIP_TOKENIZER_FILE = "tokenizer.json"
+
+# upstream's clip_preprocess (the OpenAI CLIP statistics, as DFN5B's config)
+CLIP_MEAN = (0.48145466, 0.4578275, 0.40821073)
+CLIP_STD = (0.26862954, 0.26130258, 0.27577711)
+
+
+# --- configuration -------------------------------------------------
+
+
+@dataclass
+class ClipConfig:
+    """DFN5B-CLIP-ViT-H-14-384's open_clip dimensions. The image side is 384
+    pixels (the open_clip config's 378 gives the same 27x27 patch grid)."""
+
+    embed_dim: int = 1024
+    image_size: int = 384
+    patch_size: int = 14
+    vision_width: int = 1280
+    vision_layers: int = 32
+    vision_heads: int = 16
+    vision_mlp: int = 5120
+    context_length: int = 77
+    vocab_size: int = 49408
+    text_width: int = 1024
+    text_layers: int = 24
+    text_heads: int = 16
+    text_mlp: int = 4096
+    sot_token_id: int = 49406
+    eot_token_id: int = 49407
+    pad_token_id: int = 0
+    layer_norm_eps: float = 1e-5
+
+
+def clip_vision_config(config: ClipConfig):
+    from transformers import CLIPVisionConfig
+
+    return CLIPVisionConfig(
+        hidden_size=config.vision_width,
+        intermediate_size=config.vision_mlp,
+        num_hidden_layers=config.vision_layers,
+        num_attention_heads=config.vision_heads,
+        image_size=config.image_size,
+        patch_size=config.patch_size,
+        projection_dim=config.embed_dim,
+        hidden_act="quick_gelu",
+        layer_norm_eps=config.layer_norm_eps,
+    )
+
+
+def clip_text_config(config: ClipConfig):
+    from transformers import CLIPTextConfig
+
+    return CLIPTextConfig(
+        vocab_size=config.vocab_size,
+        hidden_size=config.text_width,
+        intermediate_size=config.text_mlp,
+        num_hidden_layers=config.text_layers,
+        num_attention_heads=config.text_heads,
+        max_position_embeddings=config.context_length,
+        projection_dim=config.embed_dim,
+        hidden_act="quick_gelu",
+        layer_norm_eps=config.layer_norm_eps,
+        bos_token_id=config.sot_token_id,
+        eos_token_id=config.eot_token_id,
+        pad_token_id=config.pad_token_id,
+    )
+
+
+# open_clip residual-block names -> transformers CLIP encoder-layer names
+_BLOCK_NAMES = (
+    ("ln_1.", "layer_norm1."),
+    ("ln_2.", "layer_norm2."),
+    ("mlp.c_fc.", "mlp.fc1."),
+    ("mlp.c_proj.", "mlp.fc2."),
+    ("attn.out_proj.", "self_attn.out_proj."),
+)
+# the tower-level names, (open_clip, transformers)
+_VISION_NAMES = (
+    ("visual.conv1.weight", "vision_model.embeddings.patch_embedding.weight"),
+    ("visual.class_embedding", "vision_model.embeddings.class_embedding"),
+    (
+        "visual.positional_embedding",
+        "vision_model.embeddings.position_embedding.weight",
+    ),
+    ("visual.ln_pre.weight", "vision_model.pre_layrnorm.weight"),
+    ("visual.ln_pre.bias", "vision_model.pre_layrnorm.bias"),
+    ("visual.ln_post.weight", "vision_model.post_layernorm.weight"),
+    ("visual.ln_post.bias", "vision_model.post_layernorm.bias"),
+)
+_TEXT_NAMES = (
+    ("token_embedding.weight", "embeddings.token_embedding.weight"),
+    ("positional_embedding", "embeddings.position_embedding.weight"),
+    ("ln_final.weight", "final_layer_norm.weight"),
+    ("ln_final.bias", "final_layer_norm.bias"),
+)
+# open_clip tensors the conditioning doesn't use: the text projection and
+# pooling (patch_clip reads the hidden states) and the contrastive scale
+UNUSED_CLIP_KEYS = ("text_projection", "logit_scale", "logit_bias", "attn_mask")
+_VISION_BLOCKS = ("visual.transformer.resblocks.", "vision_model.encoder.layers.")
+_TEXT_BLOCKS = ("transformer.resblocks.", "encoder.layers.")
+
+
+def _map_block(rest: str, value: torch.Tensor, dst: str, out: dict) -> None:
+    index, _, name = rest.partition(".")
+    prefix = f"{dst}{index}."
+    if name in ("attn.in_proj_weight", "attn.in_proj_bias"):
+        kind = name.rsplit("_", 1)[1]
+        for proj, part in zip(("q", "k", "v"), value.chunk(3, dim=0)):
+            out[f"{prefix}self_attn.{proj}_proj.{kind}"] = part
+        return
+    for src_name, dst_name in _BLOCK_NAMES:
+        if name.startswith(src_name):
+            out[prefix + dst_name + name[len(src_name) :]] = value
+            return
+    raise KeyError(f"unmapped open_clip block tensor: {name}")
+
+
+def open_clip_to_transformers(state: dict) -> tuple[dict, dict]:
+    """Split an open_clip CLIP state dict into (vision, text) state dicts for
+    CLIPVisionModelWithProjection and CLIPTextModel. The fused attention
+    in-projection splits into q/k/v; the image projection is transposed into
+    a Linear weight. Any key it doesn't know raises."""
+    vision, text = {}, {}
+    names = dict(_VISION_NAMES)
+    text_names = dict(_TEXT_NAMES)
+    for key, value in state.items():
+        if key in UNUSED_CLIP_KEYS:
+            continue
+        if key == "visual.proj":
+            vision["visual_projection.weight"] = value.t().contiguous()
+        elif key in names:
+            vision[names[key]] = value
+        elif key in text_names:
+            text[text_names[key]] = value
+        elif key.startswith(_VISION_BLOCKS[0]):
+            _map_block(key[len(_VISION_BLOCKS[0]) :], value, _VISION_BLOCKS[1], vision)
+        elif key.startswith(_TEXT_BLOCKS[0]):
+            _map_block(key[len(_TEXT_BLOCKS[0]) :], value, _TEXT_BLOCKS[1], text)
+        else:
+            raise KeyError(f"unmapped open_clip tensor: {key}")
+    return vision, text
+
+
+def _unmap_blocks(state: dict, src: str, dst: str, out: dict) -> None:
+    qkv: dict = {}
+    reverse = [(t, o) for o, t in _BLOCK_NAMES]
+    for key, value in state.items():
+        if not key.startswith(src):
+            continue
+        index, _, name = key[len(src) :].partition(".")
+        if name.startswith("self_attn.") and not name.startswith("self_attn.out_proj."):
+            proj, kind = name[len("self_attn.") :].split("_proj.")
+            qkv.setdefault((index, kind), {})[proj] = value
+            continue
+        for t_name, o_name in reverse:
+            if name.startswith(t_name):
+                out[f"{dst}{index}.{o_name}{name[len(t_name) :]}"] = value
+                break
+        else:
+            raise KeyError(f"unmapped transformers block tensor: {key}")
+    for (index, kind), parts in qkv.items():
+        out[f"{dst}{index}.attn.in_proj_{kind}"] = torch.cat(
+            [parts["q"], parts["k"], parts["v"]], dim=0
+        )
+
+
+def transformers_to_open_clip(vision: dict, text: dict) -> dict:
+    """The inverse of open_clip_to_transformers, less the unused keys."""
+    out = {}
+    for o_name, t_name in _VISION_NAMES:
+        out[o_name] = vision[t_name]
+    for o_name, t_name in _TEXT_NAMES:
+        out[o_name] = text[t_name]
+    out["visual.proj"] = vision["visual_projection.weight"].t().contiguous()
+    _unmap_blocks(vision, _VISION_BLOCKS[1], _VISION_BLOCKS[0], out)
+    _unmap_blocks(text, _TEXT_BLOCKS[1], _TEXT_BLOCKS[0], out)
+    return out
+
+
+def _load_into(model: nn.Module, state: dict) -> None:
+    """Load a mapped state dict strictly, whether or not this transformers
+    version prefixes the text model's keys with 'text_model.'."""
+    own = model.state_dict().keys()
+    if any(k.startswith("text_model.") for k in own) and not any(
+        k.startswith("text_model.") for k in state
+    ):
+        state = {f"text_model.{k}": v for k, v in state.items()}
+    model.load_state_dict(state, strict=True, assign=True)
+    # non-persistent position ids are not in a state dict: rebuild them
+    for name, buffer in list(model.named_buffers()):
+        if not buffer.is_meta:
+            continue
+        if not name.endswith("position_ids"):
+            raise RuntimeError(f"no value for buffer {name}")
+        owner_name, _, attr = name.rpartition(".")
+        owner = model.get_submodule(owner_name)
+        ids = torch.arange(buffer.shape[-1]).expand(buffer.shape)
+        owner.register_buffer(attr, ids, persistent=False)
+
+
+class DFN5BClip(nn.Module):
+    """The two DFN5B towers, with upstream's encode_video_with_clip and
+    patch_clip'd encode_text outputs."""
+
+    def __init__(self, config: Optional[ClipConfig] = None):
+        super().__init__()
+        from transformers import CLIPTextModel, CLIPVisionModelWithProjection
+
+        self.config = config = config or ClipConfig()
+        self.vision = CLIPVisionModelWithProjection(clip_vision_config(config))
+        self.text = CLIPTextModel(clip_text_config(config))
+        self.register_buffer(
+            "mean", torch.tensor(CLIP_MEAN).view(1, 3, 1, 1), persistent=False
+        )
+        self.register_buffer(
+            "std", torch.tensor(CLIP_STD).view(1, 3, 1, 1), persistent=False
+        )
+
+    @property
+    def device(self) -> torch.device:
+        return self.text.get_input_embeddings().weight.device
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return self.text.get_input_embeddings().weight.dtype
+
+    @torch.inference_mode()
+    def encode_frames(self, frames: torch.Tensor, batch_size: int = -1) -> torch.Tensor:
+        """frames (B, T, 3, H, W) in [0, 1] at image_size square -> the
+        normalised image embedding per frame, (B, T, embed_dim)."""
+        b, t, c, h, w = frames.shape
+        size = self.config.image_size
+        if c != 3 or h != size or w != size:
+            raise ValueError(
+                f"CLIP frames {tuple(frames.shape)}: want (B, T, 3, {size}, {size})"
+            )
+        x = frames.to(self.device, self.dtype).reshape(b * t, c, h, w)
+        x = (x - self.mean.to(x.dtype)) / self.std.to(x.dtype)
+        step = b * t if batch_size < 0 else batch_size
+        outputs = [
+            self.vision(pixel_values=x[i : i + step]).image_embeds
+            for i in range(0, b * t, step)
+        ]
+        return F.normalize(torch.cat(outputs, dim=0), dim=-1).view(b, t, -1)
+
+    @torch.inference_mode()
+    def encode_text(self, tokens: torch.Tensor) -> torch.Tensor:
+        """tokens (B, context_length) -> the normalised last hidden state of
+        every token position, (B, context_length, text_width)."""
+        hidden = self.text(input_ids=tokens.to(self.device)).last_hidden_state
+        return F.normalize(hidden, dim=-1)
+
+
+def load_clip(
+    weights_path,
+    *,
+    config: Optional[ClipConfig] = None,
+    device="cpu",
+    dtype: torch.dtype = torch.float32,
+) -> DFN5BClip:
+    """Build the towers from a local open_clip checkpoint: safetensors if the
+    path is one, otherwise torch.load(weights_only=True). The key map runs in
+    memory; nothing converted is written."""
+    path = Path(weights_path)
+    if path.suffix == ".safetensors":
+        from safetensors.torch import load_file
+
+        state = load_file(str(path))
+    else:
+        state = torch.load(path, map_location="cpu", weights_only=True)
+    vision, text = open_clip_to_transformers(state)
+    del state
+    with torch.device("meta"):
+        clip = DFN5BClip(config)
+    _load_into(clip.vision, vision)
+    _load_into(clip.text, text)
+    clip.register_buffer(
+        "mean", torch.tensor(CLIP_MEAN).view(1, 3, 1, 1), persistent=False
+    )
+    clip.register_buffer(
+        "std", torch.tensor(CLIP_STD).view(1, 3, 1, 1), persistent=False
+    )
+    clip.to(device=device, dtype=dtype)
+    return clip.eval().requires_grad_(False)
+
+
+def load_clip_tokenizer(path):
+    """The CLIP BPE tokenizer from a local tokenizer.json."""
+    from tokenizers import Tokenizer
+
+    return Tokenizer.from_file(str(Path(path)))
+
+
+def tokenize(
+    tokenizer, texts: list[str], config: Optional[ClipConfig] = None
+) -> torch.Tensor:
+    """open_clip's layout: start token, the text's BPE ids, end token,
+    truncated to context_length with the end token kept last, padded with
+    pad_token_id (0). Text is html-unescaped, whitespace-collapsed and
+    lower-cased first, as open_clip's 'lower' cleaning does."""
+    config = config or ClipConfig()
+    length = config.context_length
+    rows = []
+    for text in texts:
+        clean = " ".join(html.unescape(html.unescape(text)).split()).lower()
+        ids = tokenizer.encode(clean, add_special_tokens=False).ids
+        row = [config.sot_token_id, *ids, config.eot_token_id]
+        if len(row) > length:
+            row = row[:length]
+            row[-1] = config.eot_token_id
+        rows.append(row + [config.pad_token_id] * (length - len(row)))
+    return torch.tensor(rows, dtype=torch.long)
+
+
+__all__ = [
+    "CLIP_MEAN",
+    "CLIP_REPO_ID",
+    "CLIP_REVISION",
+    "CLIP_STD",
+    "CLIP_TOKENIZER_FILE",
+    "CLIP_WEIGHTS_FILE",
+    "ClipConfig",
+    "DFN5BClip",
+    "UNUSED_CLIP_KEYS",
+    "clip_text_config",
+    "clip_vision_config",
+    "load_clip",
+    "load_clip_tokenizer",
+    "open_clip_to_transformers",
+    "tokenize",
+    "transformers_to_open_clip",
+]
diff --git a/dw/tasks/mmaudio_model.py b/dw/tasks/mmaudio_model.py
new file mode 100644
index 00000000..969b3def
--- /dev/null
+++ b/dw/tasks/mmaudio_model.py
@@ -0,0 +1,772 @@
+"""
+MMAudio - the flow-matching network that turns video and text features into
+an audio latent, and its Euler sampler, v1.
+
+Vendored from https://github.com/hkchengrex/MMAudio at commit
+974010a026c731054592d8f777218bd9d85a6c24 (mmaudio/model/networks.py,
+transformer_layers.py, low_level.py, embeddings.py, sequence_config.py,
+flow_matching.py and mmaudio/ext/rotary_embeddings.py, merged into this one
+file). Its DFN5B CLIP conditioning is dw/tasks/mmaudio_clip.py. The weights
+are hkchengrex/MMAudio's weights/mmaudio_large_44k_v2.pth (REPO_ID /
+REVISION below), under their own licence, stricter than this code's:
+CC-BY-NC 4.0, non-commercial use only.
+
+Carried over as written: the MMAudio network (the joint and fused MM-DiT
+blocks, the input projections, the timestep embedder, the rotary position
+rotations, the synchformer position embedding and the sync upsampling, and
+the final layer's global conditioning, upstream's issue #55, as trained),
+the sequence-length arithmetic of SequenceConfig, and the empty-condition
+sequences and classifier-free guidance (upstream's ode_wrapper).
+
+Changed in the port, so nothing here touches the Hub, a network, timm,
+einops, hydra, tensordict or torchdiffeq:
+- Only the large_44k_v2 configuration is carried (MMAudioConfig's defaults),
+  so only the v2 input projections and timestep embedder; the v1 branches,
+  the other model sizes, training (loss, conditional flow) and the random
+  weight initialisation are not, since the weights always load from the
+  checkpoint. load_network() reads a local .pth path its caller gives, with
+  torch.load(weights_only=True), strictly.
+- The flow-matching sampler is our own Euler loop (euler_sample), the same
+  fixed-step scheme as upstream's 'euler' mode over t in [0, 1]; upstream's
+  adaptive torchdiffeq mode is not carried.
+- einops rearranges are plain view/permute/reshape calls, nn.Buffer is
+  register_buffer, and the autocast-disabled regions compute in float32
+  directly.
+
+MIT License
+
+Copyright (c) 2024 Sony Research Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable, Optional
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+REPO_ID = "hkchengrex/MMAudio"
+REVISION = "eb13a1a98fdbec91753775c57b074ccdfc60587c"
+NETWORK_FILE = "weights/mmaudio_large_44k_v2.pth"
+
+# buffers upstream's load_weights drops from a checkpoint: they are rebuilt
+NON_PERSISTENT_KEYS = ("t_embed.freqs", "latent_rot", "clip_rot")
+
+
+# --- configuration -----------------------------------------------------------
+
+
+@dataclass
+class SequenceConfig:
+    """Upstream's SequenceConfig: how a duration in seconds becomes the latent,
+    CLIP and Synchformer sequence lengths (44.1 kHz defaults)."""
+
+    duration: float = 8.0
+    sampling_rate: int = 44100
+    spectrogram_frame_rate: int = 512
+    latent_downsample_rate: int = 2
+    clip_frame_rate: int = 8
+    sync_frame_rate: int = 25
+    sync_num_frames_per_segment: int = 16
+    sync_step_size: int = 8
+    sync_downsample_rate: int = 2
+
+    @property
+    def num_audio_frames(self) -> int:
+        return (
+            self.latent_seq_len
+            * self.spectrogram_frame_rate
+            * self.latent_downsample_rate
+        )
+
+    @property
+    def latent_seq_len(self) -> int:
+        return int(
+            math.ceil(
+                self.duration
+                * self.sampling_rate
+                / self.spectrogram_frame_rate
+                / self.latent_downsample_rate
+            )
+        )
+
+    @property
+    def clip_seq_len(self) -> int:
+        return int(self.duration * self.clip_frame_rate)
+
+    @property
+    def sync_seq_len(self) -> int:
+        num_frames = self.duration * self.sync_frame_rate
+        num_segments = (
+            num_frames - self.sync_num_frames_per_segment
+        ) // self.sync_step_size + 1
+        return int(
+            num_segments * self.sync_num_frames_per_segment / self.sync_downsample_rate
+        )
+
+
+@dataclass
+class MMAudioConfig:
+    """The network's sizes; the defaults are upstream's large_44k_v2."""
+
+    latent_dim: int = 40
+    clip_dim: int = 1024
+    sync_dim: int = 768
+    text_dim: int = 1024
+    hidden_dim: int = 64 * 14
+    depth: int = 21
+    fused_depth: int = 14
+    num_heads: int = 14
+    mlp_ratio: float = 4.0
+    text_seq_len: int = 77
+
+
+# --- low-level layers --------------------------------------------------------
+
+
+class ChannelLastConv1d(nn.Conv1d):
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return super().forward(x.permute(0, 2, 1)).permute(0, 2, 1)
+
+
+def _swiglu_width(hidden_dim: int, multiple_of: int = 256) -> int:
+    hidden_dim = int(2 * hidden_dim / 3)
+    return multiple_of * ((hidden_dim + multiple_of - 1) // multiple_of)
+
+
+class MLP(nn.Module):
+    """The SwiGLU feed-forward from Stability-AI/sd3-ref."""
+
+    def __init__(self, dim: int, hidden_dim: int):
+        super().__init__()
+        hidden_dim = _swiglu_width(hidden_dim)
+        self.w1 = nn.Linear(dim, hidden_dim, bias=False)
+        self.w2 = nn.Linear(hidden_dim, dim, bias=False)
+        self.w3 = nn.Linear(dim, hidden_dim, bias=False)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.w2(F.silu(self.w1(x)) * self.w3(x))
+
+
+class ConvMLP(nn.Module):
+    """MLP with channel-last 1-D convolutions in place of the linears."""
+
+    def __init__(
+        self, dim: int, hidden_dim: int, kernel_size: int = 3, padding: int = 1
+    ):
+        super().__init__()
+        hidden_dim = _swiglu_width(hidden_dim)
+
+        def conv(i, o):
+            return ChannelLastConv1d(
+                i, o, bias=False, kernel_size=kernel_size, padding=padding
+            )
+
+        self.w1 = conv(dim, hidden_dim)
+        self.w2 = conv(hidden_dim, dim)
+        self.w3 = conv(dim, hidden_dim)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.w2(F.silu(self.w1(x)) * self.w3(x))
+
+
+# --- rotary positions and timestep embedding ---------------------------------
+
+
+def compute_rope_rotations(
+    length: int, dim: int, theta: int, *, freq_scaling: float = 1.0, device=None
+) -> torch.Tensor:
+    """(1, length, dim/2, 2, 2) rotation matrices, in float32."""
+    assert dim % 2 == 0
+    pos = torch.arange(length, dtype=torch.float32, device=device)
+    freqs = 1.0 / (
+        theta ** (torch.arange(0, dim, 2, dtype=torch.float32, device=device) / dim)
+    )
+    freqs = freqs * freq_scaling
+    rot = pos[:, None] * freqs[None, :]
+    rot = torch.stack(
+        [torch.cos(rot), -torch.sin(rot), torch.sin(rot), torch.cos(rot)], dim=-1
+    )
+    return rot.view(1, length, dim // 2, 2, 2)
+
+
+def apply_rope(x: torch.Tensor, rot: torch.Tensor) -> torch.Tensor:
+    _x = x.float()
+    _x = _x.view(*_x.shape[:-1], -1, 1, 2)
+    x_out = rot[..., 0] * _x[..., 0] + rot[..., 1] * _x[..., 1]
+    return x_out.reshape(*x.shape).to(dtype=x.dtype)
+
+
+class TimestepEmbedder(nn.Module):
+    """Sinusoidal timestep features through a two-layer MLP (DiT), with the v2
+    frequencies: max_period 1 over hidden_dim features."""
+
+    def __init__(self, dim: int, frequency_embedding_size: int, max_period: float):
+        super().__init__()
+        self.mlp = nn.Sequential(
+            nn.Linear(frequency_embedding_size, dim), nn.SiLU(), nn.Linear(dim, dim)
+        )
+        self.frequency_embedding_size = frequency_embedding_size
+        self.max_period = max_period
+        self.register_buffer("freqs", self._frequencies(), persistent=False)
+
+    def _frequencies(self, device=None) -> torch.Tensor:
+        size = self.frequency_embedding_size
+        freqs = 1.0 / (
+            10000
+            ** (torch.arange(0, size, 2, dtype=torch.float32, device=device) / size)
+        )
+        return (10000 / self.max_period) * freqs
+
+    def reset_frequencies(self, device=None) -> None:
+        self.freqs = self._frequencies(device)
+
+    def forward(self, t: torch.Tensor) -> torch.Tensor:
+        args = t[:, None].float() * self.freqs[None]
+        t_freq = torch.cat([torch.cos(args), torch.sin(args)], dim=-1)
+        return self.mlp(t_freq.to(t.dtype))
+
+
+# --- transformer blocks ------------------------------------------------------
+
+
+def modulate(x: torch.Tensor, shift: torch.Tensor, scale: torch.Tensor) -> torch.Tensor:
+    return x * (1 + scale) + shift
+
+
+def attention(q: torch.Tensor, k: torch.Tensor, v: torch.Tensor) -> torch.Tensor:
+    out = F.scaled_dot_product_attention(q.contiguous(), k.contiguous(), v.contiguous())
+    b, h, n, d = out.shape
+    return out.transpose(1, 2).reshape(b, n, h * d).contiguous()
+
+
+class SelfAttention(nn.Module):
+    def __init__(self, dim: int, nheads: int):
+        super().__init__()
+        self.dim = dim
+        self.nheads = nheads
+        self.qkv = nn.Linear(dim, dim * 3, bias=True)
+        self.q_norm = nn.RMSNorm(dim // nheads)
+        self.k_norm = nn.RMSNorm(dim // nheads)
+
+    def pre_attention(self, x: torch.Tensor, rot: Optional[torch.Tensor]):
+        b, n, _ = x.shape
+        # 'b n (h d j) -> b h n d j' with j = 3 (q, k, v interleaved last)
+        qkv = self.qkv(x).view(b, n, self.nheads, self.dim // self.nheads, 3)
+        qkv = qkv.permute(0, 2, 1, 3, 4)
+        q, k, v = qkv[..., 0], qkv[..., 1], qkv[..., 2]
+        q = self.q_norm(q)
+        k = self.k_norm(k)
+        if rot is not None:
+            q = apply_rope(q, rot)
+            k = apply_rope(k, rot)
+        return q, k, v
+
+
+class MMDitSingleBlock(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        nhead: int,
+        mlp_ratio: float = 4.0,
+        pre_only: bool = False,
+        kernel_size: int = 7,
+        padding: int = 3,
+    ):
+        super().__init__()
+        self.norm1 = nn.LayerNorm(dim, elementwise_affine=False)
+        self.attn = SelfAttention(dim, nhead)
+        self.pre_only = pre_only
+        if pre_only:
+            self.adaLN_modulation = nn.Sequential(
+                nn.SiLU(), nn.Linear(dim, 2 * dim, bias=True)
+            )
+            return
+        if kernel_size == 1:
+            self.linear1 = nn.Linear(dim, dim)
+            self.ffn = MLP(dim, int(dim * mlp_ratio))
+        else:
+            self.linear1 = ChannelLastConv1d(
+                dim, dim, kernel_size=kernel_size, padding=padding
+            )
+            self.ffn = ConvMLP(
+                dim, int(dim * mlp_ratio), kernel_size=kernel_size, padding=padding
+            )
+        self.norm2 = nn.LayerNorm(dim, elementwise_affine=False)
+        self.adaLN_modulation = nn.Sequential(
+            nn.SiLU(), nn.Linear(dim, 6 * dim, bias=True)
+        )
+
+    def pre_attention(
+        self, x: torch.Tensor, c: torch.Tensor, rot: Optional[torch.Tensor]
+    ):
+        modulation = self.adaLN_modulation(c)
+        if self.pre_only:
+            shift_msa, scale_msa = modulation.chunk(2, dim=-1)
+            gates = (None, None, None, None)
+        else:
+            shift_msa, scale_msa, *gates = modulation.chunk(6, dim=-1)
+        x = modulate(self.norm1(x), shift_msa, scale_msa)
+        return self.attn.pre_attention(x, rot), tuple(gates)
+
+    def post_attention(self, x: torch.Tensor, attn_out: torch.Tensor, c: tuple):
+        if self.pre_only:
+            return x
+        gate_msa, shift_mlp, scale_mlp, gate_mlp = c
+        x = x + self.linear1(attn_out) * gate_msa
+        r = modulate(self.norm2(x), shift_mlp, scale_mlp)
+        return x + self.ffn(r) * gate_mlp
+
+    def forward(self, x: torch.Tensor, cond: torch.Tensor, rot: Optional[torch.Tensor]):
+        x_qkv, x_conditions = self.pre_attention(x, cond, rot)
+        return self.post_attention(x, attention(*x_qkv), x_conditions)
+
+
+class JointBlock(nn.Module):
+    """One joint-attention block over the latent, CLIP and text streams."""
+
+    def __init__(
+        self, dim: int, nhead: int, mlp_ratio: float = 4.0, pre_only: bool = False
+    ):
+        super().__init__()
+        self.pre_only = pre_only
+        self.latent_block = MMDitSingleBlock(
+            dim, nhead, mlp_ratio, pre_only=False, kernel_size=3, padding=1
+        )
+        self.clip_block = MMDitSingleBlock(
+            dim, nhead, mlp_ratio, pre_only=pre_only, kernel_size=3, padding=1
+        )
+        self.text_block = MMDitSingleBlock(
+            dim, nhead, mlp_ratio, pre_only=pre_only, kernel_size=1
+        )
+
+    def forward(
+        self, latent, clip_f, text_f, global_c, extended_c, latent_rot, clip_rot
+    ):
+        x_qkv, x_mod = self.latent_block.pre_attention(latent, extended_c, latent_rot)
+        c_qkv, c_mod = self.clip_block.pre_attention(clip_f, global_c, clip_rot)
+        t_qkv, t_mod = self.text_block.pre_attention(text_f, global_c, rot=None)
+
+        latent_len = latent.shape[1]
+        clip_len = clip_f.shape[1]
+        joint_qkv = [torch.cat([x_qkv[i], c_qkv[i], t_qkv[i]], dim=2) for i in range(3)]
+        attn_out = attention(*joint_qkv)
+        x_attn_out = attn_out[:, :latent_len]
+        c_attn_out = attn_out[:, latent_len : latent_len + clip_len]
+        t_attn_out = attn_out[:, latent_len + clip_len :]
+
+        latent = self.latent_block.post_attention(latent, x_attn_out, x_mod)
+        if not self.pre_only:
+            clip_f = self.clip_block.post_attention(clip_f, c_attn_out, c_mod)
+            text_f = self.text_block.post_attention(text_f, t_attn_out, t_mod)
+        return latent, clip_f, text_f
+
+
+class FinalBlock(nn.Module):
+    def __init__(self, dim: int, out_dim: int):
+        super().__init__()
+        self.adaLN_modulation = nn.Sequential(
+            nn.SiLU(), nn.Linear(dim, 2 * dim, bias=True)
+        )
+        self.norm = nn.LayerNorm(dim, elementwise_affine=False)
+        self.conv = ChannelLastConv1d(dim, out_dim, kernel_size=7, padding=3)
+
+    def forward(self, latent: torch.Tensor, c: torch.Tensor) -> torch.Tensor:
+        shift, scale = self.adaLN_modulation(c).chunk(2, dim=-1)
+        return self.conv(modulate(self.norm(latent), shift, scale))
+
+
+# --- the network -------------------------------------------------------------
+
+
+@dataclass
+class PreprocessedConditions:
+    clip_f: torch.Tensor
+    sync_f: torch.Tensor
+    text_f: torch.Tensor
+    clip_f_c: torch.Tensor
+    text_f_c: torch.Tensor
+
+
+class MMAudioNetwork(nn.Module):
+    """Upstream's MMAudio class (v2): predicts the flow from noise toward an
+    audio latent given CLIP frame features, Synchformer features and text."""
+
+    def __init__(self, config: Optional[MMAudioConfig] = None, duration: float = 8.0):
+        super().__init__()
+        config = config or MMAudioConfig()
+        self.config = config
+        self.latent_dim = config.latent_dim
+        self.hidden_dim = hidden = config.hidden_dim
+        self.num_heads = config.num_heads
+        self._text_seq_len = config.text_seq_len
+
+        self.audio_input_proj = nn.Sequential(
+            ChannelLastConv1d(config.latent_dim, hidden, kernel_size=7, padding=3),
+            nn.SiLU(),
+            ConvMLP(hidden, hidden * 4, kernel_size=7, padding=3),
+        )
+        self.clip_input_proj = nn.Sequential(
+            nn.Linear(config.clip_dim, hidden),
+            nn.SiLU(),
+            ConvMLP(hidden, hidden * 4, kernel_size=3, padding=1),
+        )
+        self.sync_input_proj = nn.Sequential(
+            ChannelLastConv1d(config.sync_dim, hidden, kernel_size=7, padding=3),
+            nn.SiLU(),
+            ConvMLP(hidden, hidden * 4, kernel_size=3, padding=1),
+        )
+        self.text_input_proj = nn.Sequential(
+            nn.Linear(config.text_dim, hidden), nn.SiLU(), MLP(hidden, hidden * 4)
+        )
+        self.clip_cond_proj = nn.Linear(hidden, hidden)
+        self.text_cond_proj = nn.Linear(hidden, hidden)
+        self.global_cond_mlp = MLP(hidden, hidden * 4)
+        # each synchformer output segment has 8 feature frames
+        self.sync_pos_emb = nn.Parameter(torch.zeros((1, 1, 8, config.sync_dim)))
+        self.final_layer = FinalBlock(hidden, config.latent_dim)
+        self.t_embed = TimestepEmbedder(
+            hidden, frequency_embedding_size=hidden, max_period=1
+        )
+
+        joint_depth = config.depth - config.fused_depth
+        self.joint_blocks = nn.ModuleList(
+            JointBlock(
+                hidden,
+                config.num_heads,
+                config.mlp_ratio,
+                pre_only=(i == joint_depth - 1),
+            )
+            for i in range(joint_depth)
+        )
+        self.fused_blocks = nn.ModuleList(
+            MMDitSingleBlock(
+                hidden, config.num_heads, config.mlp_ratio, kernel_size=3, padding=1
+            )
+            for _ in range(config.fused_depth)
+        )
+
+        # loaded from the checkpoint; identity statistics until then
+        frozen = dict(requires_grad=False)
+        self.latent_mean = nn.Parameter(torch.zeros(1, 1, config.latent_dim), **frozen)
+        self.latent_std = nn.Parameter(torch.ones(1, 1, config.latent_dim), **frozen)
+        self.empty_string_feat = nn.Parameter(
+            torch.zeros(config.text_seq_len, config.text_dim), **frozen
+        )
+        self.empty_clip_feat = nn.Parameter(torch.zeros(1, config.clip_dim))
+        self.empty_sync_feat = nn.Parameter(torch.zeros(1, config.sync_dim))
+
+        self.set_duration(duration)
+
+    # sequence lengths -------------------------------------------------------
+
+    def set_duration(self, duration: float) -> SequenceConfig:
+        """Upstream's update_seq_lengths for a duration in seconds; rebuilds the
+        rotations (float32) on the network's device. Returns the sequence
+        config, whose num_audio_frames is the decoded length."""
+        seq = SequenceConfig(duration=duration)
+        self.seq_cfg = seq
+        self._latent_seq_len = seq.latent_seq_len
+        self._clip_seq_len = seq.clip_seq_len
+        self._sync_seq_len = seq.sync_seq_len
+        head_dim = self.hidden_dim // self.num_heads
+        device = None if self.latent_mean.is_meta else self.latent_mean.device
+        latent_rot = compute_rope_rotations(
+            self._latent_seq_len, head_dim, 10000, freq_scaling=1.0, device=device
+        )
+        clip_rot = compute_rope_rotations(
+            self._clip_seq_len,
+            head_dim,
+            10000,
+            freq_scaling=self._latent_seq_len / self._clip_seq_len,
+            device=device,
+        )
+        self.register_buffer("latent_rot", latent_rot, persistent=False)
+        self.register_buffer("clip_rot", clip_rot, persistent=False)
+        return seq
+
+    @property
+    def device(self) -> torch.device:
+        return self.latent_mean.device
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return self.latent_mean.dtype
+
+    @property
+    def latent_seq_len(self) -> int:
+        return self._latent_seq_len
+
+    @property
+    def clip_seq_len(self) -> int:
+        return self._clip_seq_len
+
+    @property
+    def sync_seq_len(self) -> int:
+        return self._sync_seq_len
+
+    # latents ----------------------------------------------------------------
+
+    def normalize(self, x: torch.Tensor) -> torch.Tensor:
+        return (x - self.latent_mean) / self.latent_std
+
+    def unnormalize(self, x: torch.Tensor) -> torch.Tensor:
+        return x * self.latent_std + self.latent_mean
+
+    # conditions -------------------------------------------------------------
+
+    def preprocess_conditions(
+        self, clip_f: torch.Tensor, sync_f: torch.Tensor, text_f: torch.Tensor
+    ) -> PreprocessedConditions:
+        """The work that doesn't depend on the latent or the step, done once."""
+        if clip_f.shape[1] != self._clip_seq_len:
+            raise ValueError(
+                f"clip features {tuple(clip_f.shape)}: want {self._clip_seq_len} frames"
+            )
+        if sync_f.shape[1] != self._sync_seq_len:
+            raise ValueError(
+                f"sync features {tuple(sync_f.shape)}: want {self._sync_seq_len}"
+            )
+        if text_f.shape[1] != self._text_seq_len:
+            raise ValueError(
+                f"text features {tuple(text_f.shape)}: want {self._text_seq_len}"
+            )
+
+        bs = clip_f.shape[0]
+        num_sync_segments = self._sync_seq_len // 8
+        sync_f = sync_f.view(bs, num_sync_segments, 8, -1) + self.sync_pos_emb
+        sync_f = sync_f.flatten(1, 2)
+
+        clip_f = self.clip_input_proj(clip_f)
+        sync_f = self.sync_input_proj(sync_f)
+        text_f = self.text_input_proj(text_f)
+
+        # upsample the sync features to the latent's length
+        sync_f = F.interpolate(
+            sync_f.transpose(1, 2), size=self._latent_seq_len, mode="nearest-exact"
+        ).transpose(1, 2)
+
+        clip_f_c = self.clip_cond_proj(clip_f.mean(dim=1))
+        text_f_c = self.text_cond_proj(text_f.mean(dim=1))
+        return PreprocessedConditions(clip_f, sync_f, text_f, clip_f_c, text_f_c)
+
+    def predict_flow(
+        self, latent: torch.Tensor, t: torch.Tensor, conditions: PreprocessedConditions
+    ) -> torch.Tensor:
+        if latent.shape[1] != self._latent_seq_len:
+            raise ValueError(
+                f"latent {tuple(latent.shape)}: want {self._latent_seq_len} frames"
+            )
+        clip_f = conditions.clip_f
+        text_f = conditions.text_f
+
+        latent = self.audio_input_proj(latent)
+        global_c = self.global_cond_mlp(conditions.clip_f_c + conditions.text_f_c)
+        global_c = self.t_embed(t).unsqueeze(1) + global_c.unsqueeze(1)
+        extended_c = global_c + conditions.sync_f
+
+        for block in self.joint_blocks:
+            latent, clip_f, text_f = block(
+                latent,
+                clip_f,
+                text_f,
+                global_c,
+                extended_c,
+                self.latent_rot,
+                self.clip_rot,
+            )
+        for block in self.fused_blocks:
+            latent = block(latent, extended_c, self.latent_rot)
+
+        # upstream notes this should be extended_c (its issue #55); the
+        # checkpoint was trained with global_c, so global_c it stays
+        return self.final_layer(latent, global_c)
+
+    def forward(self, latent, clip_f, sync_f, text_f, t) -> torch.Tensor:
+        return self.predict_flow(
+            latent, t, self.preprocess_conditions(clip_f, sync_f, text_f)
+        )
+
+    def get_empty_string_sequence(self, bs: int) -> torch.Tensor:
+        return self.empty_string_feat.unsqueeze(0).expand(bs, -1, -1)
+
+    def get_empty_clip_sequence(self, bs: int) -> torch.Tensor:
+        return self.empty_clip_feat.unsqueeze(0).expand(bs, self._clip_seq_len, -1)
+
+    def get_empty_sync_sequence(self, bs: int) -> torch.Tensor:
+        return self.empty_sync_feat.unsqueeze(0).expand(bs, self._sync_seq_len, -1)
+
+    def get_empty_conditions(
+        self, bs: int, *, negative_text_features: Optional[torch.Tensor] = None
+    ) -> PreprocessedConditions:
+        """The unconditional branch of guidance: learned empty CLIP and sync
+        sequences, and the empty string's text features or the negative
+        prompt's."""
+        if negative_text_features is not None:
+            empty_text = negative_text_features
+        else:
+            empty_text = self.get_empty_string_sequence(1)
+        conditions = self.preprocess_conditions(
+            self.get_empty_clip_sequence(1), self.get_empty_sync_sequence(1), empty_text
+        )
+        conditions.clip_f = conditions.clip_f.expand(bs, -1, -1)
+        conditions.sync_f = conditions.sync_f.expand(bs, -1, -1)
+        conditions.clip_f_c = conditions.clip_f_c.expand(bs, -1)
+        if negative_text_features is None:
+            conditions.text_f = conditions.text_f.expand(bs, -1, -1)
+            conditions.text_f_c = conditions.text_f_c.expand(bs, -1)
+        return conditions
+
+    def guided_flow(
+        self,
+        t: torch.Tensor,
+        latent: torch.Tensor,
+        conditions: PreprocessedConditions,
+        empty_conditions: PreprocessedConditions,
+        cfg_strength: float,
+    ) -> torch.Tensor:
+        """Upstream's ode_wrapper: classifier-free guidance, or the conditional
+        flow alone when cfg_strength is below 1."""
+        t = t * torch.ones(len(latent), device=latent.device, dtype=latent.dtype)
+        if cfg_strength < 1.0:
+            return self.predict_flow(latent, t, conditions)
+        return cfg_strength * self.predict_flow(latent, t, conditions) + (
+            1 - cfg_strength
+        ) * self.predict_flow(latent, t, empty_conditions)
+
+
+def load_network(
+    path,
+    *,
+    config: Optional[MMAudioConfig] = None,
+    duration: float = 8.0,
+    device="cpu",
+    dtype: torch.dtype = torch.float32,
+) -> MMAudioNetwork:
+    """Build the network from a local checkpoint (a plain state dict), loaded
+    with weights_only=True and strictly. The rotations are rebuilt in float32
+    after the cast, as upstream's update_seq_lengths leaves them."""
+    state = torch.load(Path(path), map_location="cpu", weights_only=True)
+    for key in NON_PERSISTENT_KEYS:
+        state.pop(key, None)
+    with torch.device("meta"):
+        net = MMAudioNetwork(config, duration=duration)
+    net.load_state_dict(state, strict=True, assign=True)
+    # the non-persistent buffers are still meta: build them, cast with the
+    # rest (upstream casts freqs too), then rebuild the rotations in float32
+    net.t_embed.reset_frequencies()
+    net.set_duration(duration)
+    net.to(device=device, dtype=dtype)
+    net.set_duration(duration)
+    return net.eval().requires_grad_(False)
+
+
+# --- sampling ----------------------------------------------------------------
+
+
+def euler_sample(
+    flow: Callable[[torch.Tensor, torch.Tensor], torch.Tensor],
+    x0: torch.Tensor,
+    steps: int,
+    t0: float = 0.0,
+    t1: float = 1.0,
+) -> torch.Tensor:
+    """Integrate dx/dt = flow(t, x) from t0 to t1 with `steps` fixed Euler
+    steps: upstream FlowMatching's 'euler' mode (min_sigma 0)."""
+    if steps < 1:
+        raise ValueError(f"steps must be at least 1, got {steps}")
+    times = torch.linspace(t0, t1, steps + 1)
+    x = x0
+    for i in range(steps):
+        t = times[i]
+        x = x + (times[i + 1] - t) * flow(t, x)
+    return x
+
+
+@torch.inference_mode()
+def sample_latent(
+    net: MMAudioNetwork,
+    *,
+    clip_features: Optional[torch.Tensor] = None,
+    sync_features: Optional[torch.Tensor] = None,
+    text_features: Optional[torch.Tensor] = None,
+    negative_text_features: Optional[torch.Tensor] = None,
+    steps: int = 25,
+    cfg_strength: float = 4.5,
+    generator: Optional[torch.Generator] = None,
+    batch_size: int = 1,
+) -> torch.Tensor:
+    """Upstream's generate() up to the decoder: noise to an unnormalised audio
+    latent (batch, latent_seq_len, latent_dim). A missing condition takes the
+    network's empty sequence, so text-only (no video features) and video-only
+    (no text features) both run; negative text replaces the empty string in
+    guidance's unconditional branch."""
+    given = [f for f in (clip_features, sync_features, text_features) if f is not None]
+    bs = given[0].shape[0] if given else batch_size
+    device, dtype = net.device, net.dtype
+
+    def cast(features):
+        return None if features is None else features.to(device, dtype)
+
+    clip_f = cast(clip_features)
+    sync_f = cast(sync_features)
+    text_f = cast(text_features)
+    negative = cast(negative_text_features)
+    if clip_f is None:
+        clip_f = net.get_empty_clip_sequence(bs)
+    if sync_f is None:
+        sync_f = net.get_empty_sync_sequence(bs)
+    if text_f is None:
+        text_f = net.get_empty_string_sequence(bs)
+
+    x0 = torch.randn(
+        bs,
+        net.latent_seq_len,
+        net.latent_dim,
+        device=device,
+        dtype=dtype,
+        generator=generator,
+    )
+    conditions = net.preprocess_conditions(clip_f, sync_f, text_f)
+    empty_conditions = net.get_empty_conditions(bs, negative_text_features=negative)
+
+    def flow(t, x):
+        return net.guided_flow(t, x, conditions, empty_conditions, cfg_strength)
+
+    return net.unnormalize(euler_sample(flow, x0, steps))
+
+
+__all__ = [
+    "MMAudioConfig",
+    "MMAudioNetwork",
+    "NETWORK_FILE",
+    "PreprocessedConditions",
+    "REPO_ID",
+    "REVISION",
+    "SequenceConfig",
+    "euler_sample",
+    "load_network",
+    "sample_latent",
+]
diff --git a/tests/test_mmaudio_model.py b/tests/test_mmaudio_model.py
new file mode 100644
index 00000000..ae34adff
--- /dev/null
+++ b/tests/test_mmaudio_model.py
@@ -0,0 +1,539 @@
+"""The vendored MMAudio network and Euler sampler (dw/tasks/mmaudio_model.py)
+and its DFN5B CLIP key map and towers (dw/tasks/mmaudio_clip.py), on tiny random configurations on CPU."""
+
+import math
+import re
+from pathlib import Path
+
+import pytest
+import torch
+import torch.nn.functional as F
+
+import dw.tasks.mmaudio_clip as mc
+import dw.tasks.mmaudio_model as mm
+
+MODULE_PATH = Path(mm.__file__)
+CLIP_MODULE_PATH = Path(mc.__file__)
+
+TINY_NET = mm.MMAudioConfig(
+    latent_dim=4,
+    clip_dim=8,
+    sync_dim=6,
+    text_dim=8,
+    hidden_dim=32,
+    depth=3,
+    fused_depth=1,
+    num_heads=2,
+    mlp_ratio=2.0,
+    text_seq_len=5,
+)
+# one second: 44 latent frames, 8 CLIP frames, 16 sync frames
+DURATION = 1.0
+
+TINY_CLIP = mc.ClipConfig(
+    embed_dim=16,
+    image_size=28,
+    patch_size=14,
+    vision_width=32,
+    vision_layers=2,
+    vision_heads=4,
+    vision_mlp=64,
+    context_length=8,
+    vocab_size=50,
+    text_width=24,
+    text_layers=2,
+    text_heads=4,
+    text_mlp=48,
+    sot_token_id=48,
+    eot_token_id=49,
+)
+
+
+def _randomize(module, seed=0):
+    gen = torch.Generator().manual_seed(seed)
+    with torch.no_grad():
+        for p in module.parameters():
+            p.copy_(torch.randn(p.shape, generator=gen) * 0.2)
+        if hasattr(module, "latent_std"):
+            module.latent_std.abs_().add_(0.5)
+    return module
+
+
+@pytest.fixture
+def tiny_net():
+    return _randomize(mm.MMAudioNetwork(TINY_NET, duration=DURATION)).eval()
+
+
+def _features(net, bs, seed=1):
+    gen = torch.Generator().manual_seed(seed)
+    clip = torch.randn(bs, net.clip_seq_len, TINY_NET.clip_dim, generator=gen)
+    sync = torch.randn(bs, net.sync_seq_len, TINY_NET.sync_dim, generator=gen)
+    text = torch.randn(bs, TINY_NET.text_seq_len, TINY_NET.text_dim, generator=gen)
+    return clip, sync, text
+
+
+# --- sequence lengths and the released configuration -------------------------
+
+
+def test_sequence_lengths_match_upstream():
+    seq = mm.SequenceConfig(duration=8.0)
+    assert (seq.latent_seq_len, seq.clip_seq_len, seq.sync_seq_len) == (345, 64, 192)
+    assert seq.num_audio_frames == 345 * 1024
+    tiny = mm.SequenceConfig(duration=DURATION)
+    assert (tiny.latent_seq_len, tiny.clip_seq_len, tiny.sync_seq_len) == (44, 8, 16)
+
+
+def test_default_config_is_large_44k_v2():
+    with torch.device("meta"):
+        net = mm.MMAudioNetwork()
+    assert (net.latent_seq_len, net.clip_seq_len, net.sync_seq_len) == (345, 64, 192)
+    assert len(net.joint_blocks) == 7 and len(net.fused_blocks) == 14
+    assert net.joint_blocks[-1].pre_only and not net.joint_blocks[0].pre_only
+    shapes = {k: tuple(v.shape) for k, v in net.state_dict().items()}
+    assert shapes["audio_input_proj.0.weight"] == (896, 40, 7)
+    assert shapes["clip_input_proj.0.weight"] == (896, 1024)
+    assert shapes["sync_input_proj.0.weight"] == (896, 768, 7)
+    assert shapes["text_input_proj.0.weight"] == (896, 1024)
+    assert shapes["sync_pos_emb"] == (1, 1, 8, 768)
+    assert shapes["empty_string_feat"] == (77, 1024)
+    assert shapes["t_embed.mlp.0.weight"] == (896, 896)
+    assert shapes["final_layer.conv.weight"] == (40, 896, 7)
+    # SwiGLU width: 256 * ceil(int(2 * 3584 / 3) / 256)
+    assert shapes["global_cond_mlp.w1.weight"] == (2560, 896)
+    for key in mm.NON_PERSISTENT_KEYS:
+        assert key not in shapes
+
+
+def test_v2_timestep_frequencies():
+    net = mm.MMAudioNetwork(TINY_NET, duration=DURATION)
+    size = TINY_NET.hidden_dim
+    expected = 10000 / (10000 ** (torch.arange(0, size, 2).float() / size))
+    torch.testing.assert_close(net.t_embed.freqs, expected)
+
+
+# --- the network samples ---------------------------------------------------
+
+
+def test_tiny_network_samples_a_latent_of_the_right_shape(tiny_net):
+    clip, sync, text = _features(tiny_net, bs=2)
+    gen = torch.Generator().manual_seed(7)
+    latent = mm.sample_latent(
+        tiny_net,
+        clip_features=clip,
+        sync_features=sync,
+        text_features=text,
+        steps=4,
+        cfg_strength=4.5,
+        generator=gen,
+    )
+    assert latent.shape == (2, 44, 4)
+    assert torch.isfinite(latent).all()
+    again = mm.sample_latent(
+        tiny_net,
+        clip_features=clip,
+        sync_features=sync,
+        text_features=text,
+        steps=4,
+        cfg_strength=4.5,
+        generator=torch.Generator().manual_seed(7),
+    )
+    torch.testing.assert_close(latent, again)
+
+
+def test_text_only_and_unconditioned_sampling(tiny_net):
+    _, _, text = _features(tiny_net, bs=1)
+    negative = torch.randn_like(text)
+    latent = mm.sample_latent(
+        tiny_net, text_features=text, negative_text_features=negative, steps=2
+    )
+    assert latent.shape == (1, 44, 4)
+    empty = mm.sample_latent(tiny_net, steps=2, batch_size=3)
+    assert empty.shape == (3, 44, 4)
+    assert torch.isfinite(empty).all()
+
+
+def test_sampling_is_the_euler_loop_over_guided_flow(tiny_net):
+    clip, sync, text = _features(tiny_net, bs=1)
+    gen = torch.Generator().manual_seed(3)
+    latent = mm.sample_latent(
+        tiny_net,
+        clip_features=clip,
+        sync_features=sync,
+        text_features=text,
+        steps=3,
+        cfg_strength=2.0,
+        generator=gen,
+    )
+    x = torch.randn(1, 44, 4, generator=torch.Generator().manual_seed(3))
+    cond = tiny_net.preprocess_conditions(clip, sync, text)
+    empty = tiny_net.get_empty_conditions(1)
+    with torch.no_grad():
+        times = torch.linspace(0, 1, 4)
+        for i in range(3):
+            t = times[i].expand(1)
+            c = tiny_net.predict_flow(x, t, cond)
+            e = tiny_net.predict_flow(x, t, empty)
+            x = x + (times[i + 1] - times[i]) * (2.0 * c + (1 - 2.0) * e)
+    torch.testing.assert_close(latent, tiny_net.unnormalize(x), rtol=1e-4, atol=1e-5)
+
+
+def test_guidance_combines_conditional_and_empty_flows(tiny_net):
+    clip, sync, text = _features(tiny_net, bs=2)
+    x = torch.randn(2, 44, 4)
+    t = torch.tensor(0.25)
+    with torch.no_grad():
+        cond = tiny_net.preprocess_conditions(clip, sync, text)
+        empty = tiny_net.get_empty_conditions(2)
+        tt = torch.full((2,), 0.25)
+        c = tiny_net.predict_flow(x, tt, cond)
+        e = tiny_net.predict_flow(x, tt, empty)
+        torch.testing.assert_close(tiny_net.guided_flow(t, x, cond, empty, 0.5), c)
+        torch.testing.assert_close(
+            tiny_net.guided_flow(t, x, cond, empty, 3.0),
+            3.0 * c - 2.0 * e,
+            rtol=1e-5,
+            atol=1e-5,
+        )
+    assert not torch.allclose(c, e)
+
+
+def test_preprocess_rejects_wrong_lengths(tiny_net):
+    clip, sync, text = _features(tiny_net, bs=1)
+    with pytest.raises(ValueError, match="clip"):
+        tiny_net.preprocess_conditions(clip[:, :-1], sync, text)
+    with pytest.raises(ValueError, match="sync"):
+        tiny_net.preprocess_conditions(clip, sync[:, :-8], text)
+
+
+def test_set_duration_changes_the_lengths(tiny_net):
+    seq = tiny_net.set_duration(2.0)
+    assert tiny_net.latent_seq_len == seq.latent_seq_len == 87
+    assert tiny_net.latent_rot.shape[1] == 87 and tiny_net.clip_rot.shape[1] == 16
+    assert tiny_net.latent_rot.dtype == torch.float32
+    assert mm.sample_latent(tiny_net, steps=1).shape == (1, 87, 4)
+
+
+# --- the Euler loop ------------------------------------------------------------
+
+
+@pytest.mark.parametrize("steps", [1, 4, 25])
+def test_euler_matches_the_closed_form_linear_ode(steps):
+    # dx/dt = x: Euler with N equal steps gives x0 * (1 + 1/N)^N exactly
+    x0 = torch.tensor([1.0, -2.0, 0.5], dtype=torch.float64)
+    seen = []
+
+    def flow(t, x):
+        seen.append(float(t))
+        return x
+
+    out = mm.euler_sample(flow, x0, steps)
+    torch.testing.assert_close(out, x0 * (1 + 1 / steps) ** steps)
+    assert seen == pytest.approx([i / steps for i in range(steps)])
+    if steps == 25:
+        # and converges toward e^1
+        assert abs(out[0].item() - math.e) < 0.06
+
+
+def test_euler_lands_a_straight_flow_exactly():
+    # the rectified-flow ideal: a constant velocity reaches x0 + v at t = 1
+    x0 = torch.randn(2, 5)
+    v = torch.randn(2, 5)
+    torch.testing.assert_close(mm.euler_sample(lambda t, x: v, x0, 7), x0 + v)
+    # dx/dt = 2t integrates to 1 only in the limit; Euler under-shoots by 1/N
+    out = mm.euler_sample(lambda t, x: 2 * t * torch.ones_like(x), torch.zeros(1), 10)
+    torch.testing.assert_close(out, torch.tensor([1 - 1 / 10]))
+    with pytest.raises(ValueError):
+        mm.euler_sample(lambda t, x: x, x0, 0)
+
+
+# --- loading the network ---------------------------------------------------------
+
+
+def test_load_network_reads_weights_only_and_strictly(tiny_net, tmp_path, monkeypatch):
+    state = tiny_net.state_dict()
+    # the released checkpoint carries the buffers upstream drops on load
+    state["t_embed.freqs"] = torch.zeros(1)
+    state["latent_rot"] = torch.zeros(1)
+    state["clip_rot"] = torch.zeros(1)
+    path = tmp_path / "net.pth"
+    torch.save(state, path)
+
+    calls = []
+    real_load = torch.load
+
+    def spy(*args, **kwargs):
+        calls.append(kwargs.get("weights_only"))
+        return real_load(*args, **kwargs)
+
+    monkeypatch.setattr(torch, "load", spy)
+    net = mm.load_network(path, config=TINY_NET, duration=DURATION)
+    assert calls == [True]
+    assert not net.training
+    assert not any(p.requires_grad for p in net.parameters())
+    for key, value in tiny_net.state_dict().items():
+        torch.testing.assert_close(net.state_dict()[key], value)
+    torch.testing.assert_close(net.t_embed.freqs, tiny_net.t_embed.freqs)
+    torch.testing.assert_close(net.latent_rot, tiny_net.latent_rot)
+
+    clip, sync, text = _features(net, bs=1)
+    x, t = torch.randn(1, 44, 4), torch.tensor([0.5])
+    with torch.no_grad():
+        torch.testing.assert_close(
+            net(x, clip, sync, text, t), tiny_net(x, clip, sync, text, t)
+        )
+
+    del state["sync_pos_emb"]
+    torch.save(state, path)
+    with pytest.raises(RuntimeError, match="sync_pos_emb"):
+        mm.load_network(path, config=TINY_NET, duration=DURATION)
+
+
+def test_load_network_in_bfloat16_keeps_rotations_float32(tiny_net, tmp_path):
+    path = tmp_path / "net.pth"
+    torch.save(tiny_net.state_dict(), path)
+    net = mm.load_network(
+        path, config=TINY_NET, duration=DURATION, dtype=torch.bfloat16
+    )
+    assert net.dtype == torch.bfloat16
+    assert net.latent_rot.dtype == torch.float32
+    assert mm.sample_latent(net, steps=2).dtype == torch.bfloat16
+
+
+# --- DFN5B CLIP: key map and towers ---------------------------------------------
+
+
+def _block_state(prefix, width, mlp, gen):
+    def r(*shape):
+        return torch.randn(*shape, generator=gen) * 0.2
+
+    return {
+        f"{prefix}ln_1.weight": 1 + r(width),
+        f"{prefix}ln_1.bias": r(width),
+        f"{prefix}attn.in_proj_weight": r(3 * width, width),
+        f"{prefix}attn.in_proj_bias": r(3 * width),
+        f"{prefix}attn.out_proj.weight": r(width, width),
+        f"{prefix}attn.out_proj.bias": r(width),
+        f"{prefix}ln_2.weight": 1 + r(width),
+        f"{prefix}ln_2.bias": r(width),
+        f"{prefix}mlp.c_fc.weight": r(mlp, width),
+        f"{prefix}mlp.c_fc.bias": r(mlp),
+        f"{prefix}mlp.c_proj.weight": r(width, mlp),
+        f"{prefix}mlp.c_proj.bias": r(width),
+    }
+
+
+def tiny_open_clip_state(c=TINY_CLIP, seed=0):
+    """An open_clip CLIP state dict at the tiny sizes, random."""
+    gen = torch.Generator().manual_seed(seed)
+
+    def r(*shape):
+        return torch.randn(*shape, generator=gen) * 0.2
+
+    vw, tw = c.vision_width, c.text_width
+    grid = c.image_size // c.patch_size
+    state = {
+        "visual.class_embedding": r(vw),
+        "visual.positional_embedding": r(grid * grid + 1, vw),
+        "visual.proj": r(vw, c.embed_dim),
+        "visual.conv1.weight": r(vw, 3, c.patch_size, c.patch_size),
+        "visual.ln_pre.weight": 1 + r(vw),
+        "visual.ln_pre.bias": r(vw),
+        "visual.ln_post.weight": 1 + r(vw),
+        "visual.ln_post.bias": r(vw),
+        "positional_embedding": r(c.context_length, tw),
+        "text_projection": r(tw, c.embed_dim),
+        "logit_scale": torch.tensor(4.6),
+        "token_embedding.weight": r(c.vocab_size, tw),
+        "ln_final.weight": 1 + r(tw),
+        "ln_final.bias": r(tw),
+    }
+    for i in range(c.vision_layers):
+        state.update(
+            _block_state(f"visual.transformer.resblocks.{i}.", vw, c.vision_mlp, gen)
+        )
+    for i in range(c.text_layers):
+        state.update(_block_state(f"transformer.resblocks.{i}.", tw, c.text_mlp, gen))
+    return state
+
+
+def _ref_block(x, s, p, heads, mask):
+    """open_clip's ResidualAttentionBlock, in plain torch (quick_gelu)."""
+    h = F.layer_norm(x, x.shape[-1:], s[p + "ln_1.weight"], s[p + "ln_1.bias"], 1e-5)
+    q, k, v = F.linear(
+        h, s[p + "attn.in_proj_weight"], s[p + "attn.in_proj_bias"]
+    ).chunk(3, -1)
+    b, n, w = q.shape
+
+    def heads_of(t):
+        return t.view(b, n, heads, w // heads).transpose(1, 2)
+
+    a = F.scaled_dot_product_attention(
+        heads_of(q), heads_of(k), heads_of(v), attn_mask=mask
+    )
+    a = a.transpose(1, 2).reshape(b, n, w)
+    x = x + F.linear(a, s[p + "attn.out_proj.weight"], s[p + "attn.out_proj.bias"])
+    h = F.layer_norm(x, x.shape[-1:], s[p + "ln_2.weight"], s[p + "ln_2.bias"], 1e-5)
+    h = F.linear(h, s[p + "mlp.c_fc.weight"], s[p + "mlp.c_fc.bias"])
+    h = h * torch.sigmoid(1.702 * h)
+    return x + F.linear(h, s[p + "mlp.c_proj.weight"], s[p + "mlp.c_proj.bias"])
+
+
+def ref_encode_text(s, tokens, c=TINY_CLIP):
+    """upstream patch_clip's encode_text: normalised ln_final states."""
+    x = s["token_embedding.weight"][tokens] + s["positional_embedding"]
+    n = tokens.shape[1]
+    mask = torch.full((n, n), float("-inf")).triu(1)
+    for i in range(c.text_layers):
+        x = _ref_block(x, s, f"transformer.resblocks.{i}.", c.text_heads, mask)
+    x = F.layer_norm(x, x.shape[-1:], s["ln_final.weight"], s["ln_final.bias"], 1e-5)
+    return F.normalize(x, dim=-1)
+
+
+def ref_encode_image(s, images, c=TINY_CLIP):
+    """open_clip encode_image(normalize=True) on already-normalised pixels."""
+    x = F.conv2d(images, s["visual.conv1.weight"], stride=c.patch_size)
+    x = x.flatten(2).transpose(1, 2)
+    cls = s["visual.class_embedding"].expand(x.shape[0], 1, -1)
+    x = torch.cat([cls, x], dim=1) + s["visual.positional_embedding"]
+    w = x.shape[-1]
+    x = F.layer_norm(x, (w,), s["visual.ln_pre.weight"], s["visual.ln_pre.bias"], 1e-5)
+    for i in range(c.vision_layers):
+        x = _ref_block(x, s, f"visual.transformer.resblocks.{i}.", c.vision_heads, None)
+    x = F.layer_norm(
+        x[:, 0], (w,), s["visual.ln_post.weight"], s["visual.ln_post.bias"], 1e-5
+    )
+    return F.normalize(x @ s["visual.proj"], dim=-1)
+
+
+def test_clip_key_map_round_trips():
+    state = tiny_open_clip_state()
+    vision, text = mc.open_clip_to_transformers(state)
+    back = mc.transformers_to_open_clip(vision, text)
+    expected = {k: v for k, v in state.items() if k not in mc.UNUSED_CLIP_KEYS}
+    assert set(back) == set(expected)
+    for key, value in expected.items():
+        torch.testing.assert_close(back[key], value, msg=key)
+
+
+def test_clip_key_map_fills_the_transformers_towers_exactly():
+    from transformers import CLIPTextModel, CLIPVisionModelWithProjection
+
+    vision, text = mc.open_clip_to_transformers(tiny_open_clip_state())
+    v_model = CLIPVisionModelWithProjection(mc.clip_vision_config(TINY_CLIP))
+    t_model = CLIPTextModel(mc.clip_text_config(TINY_CLIP))
+    mc._load_into(v_model, vision)  # strict: no key missing or left over
+    mc._load_into(t_model, text)
+    with pytest.raises(KeyError, match="unknown"):
+        mc.open_clip_to_transformers({"unknown.weight": torch.zeros(1)})
+
+
+def test_load_clip_reproduces_open_clip(tmp_path, monkeypatch):
+    state = tiny_open_clip_state()
+    path = tmp_path / "open_clip_pytorch_model.bin"
+    torch.save(state, path)
+
+    calls = []
+    real_load = torch.load
+
+    def spy(*args, **kwargs):
+        calls.append(kwargs.get("weights_only"))
+        return real_load(*args, **kwargs)
+
+    monkeypatch.setattr(torch, "load", spy)
+    clip = mc.load_clip(path, config=TINY_CLIP)
+    assert calls == [True]
+    assert sorted(p.name for p in tmp_path.iterdir()) == [path.name]  # nothing written
+
+    # the text path: per-token, normalised, as patch_clip returns it
+    tokens = torch.tensor([[48, 5, 7, 49, 0, 0, 0, 0], [48, 9, 49, 0, 0, 0, 0, 0]])
+    got = clip.encode_text(tokens)
+    assert got.shape == (2, TINY_CLIP.context_length, TINY_CLIP.text_width)
+    torch.testing.assert_close(got.norm(dim=-1), torch.ones(2, 8))
+    torch.testing.assert_close(
+        got, ref_encode_text(state, tokens), rtol=1e-4, atol=1e-5
+    )
+
+    # the image path: [0, 1] frames, CLIP-normalised, one embedding per frame
+    frames = torch.rand(1, 3, 3, 28, 28, generator=torch.Generator().manual_seed(2))
+    mean = torch.tensor(mc.CLIP_MEAN).view(1, 3, 1, 1)
+    std = torch.tensor(mc.CLIP_STD).view(1, 3, 1, 1)
+    want = ref_encode_image(state, (frames[0] - mean) / std).view(1, 3, -1)
+    got = clip.encode_frames(frames, batch_size=2)
+    assert got.shape == (1, 3, TINY_CLIP.embed_dim)
+    torch.testing.assert_close(got, want, rtol=1e-4, atol=1e-5)
+    with pytest.raises(ValueError, match="CLIP frames"):
+        clip.encode_frames(torch.rand(1, 1, 3, 32, 32))
+
+
+def test_default_clip_config_is_dfn5b():
+    c = mc.ClipConfig()
+    v = mc.clip_vision_config(c)
+    t = mc.clip_text_config(c)
+    assert (v.hidden_size, v.num_hidden_layers, v.num_attention_heads) == (1280, 32, 16)
+    assert (v.image_size, v.patch_size, v.projection_dim) == (384, 14, 1024)
+    assert (t.hidden_size, t.num_hidden_layers, t.vocab_size) == (1024, 24, 49408)
+    assert t.max_position_embeddings == 77
+    assert v.hidden_act == t.hidden_act == "quick_gelu"
+    # 384 / 14 -> a 27 x 27 grid, as upstream feeds it
+    assert (v.image_size // v.patch_size) ** 2 + 1 == 730
+
+
+def test_tokenize_uses_open_clip_layout(tmp_path):
+    from tokenizers import Tokenizer, models, pre_tokenizers
+
+    tok = Tokenizer(
+        models.WordLevel({"[UNK]": 1, "a": 2, "cat": 3, "&": 4}, unk_token="[UNK]")
+    )
+    tok.pre_tokenizer = pre_tokenizers.Whitespace()
+    path = tmp_path / "tokenizer.json"
+    tok.save(str(path))
+    tokenizer = mc.load_clip_tokenizer(path)
+
+    out = mc.tokenize(
+        tokenizer, ["A  Cat", "a &amp; cat cat cat cat cat cat"], TINY_CLIP
+    )
+    assert out.dtype == torch.long and out.shape == (2, 8)
+    assert out[0].tolist() == [48, 2, 3, 49, 0, 0, 0, 0]
+    # truncated to the context length, the end token kept last
+    assert out[1].tolist() == [48, 2, 4, 3, 3, 3, 3, 49]
+
+
+# --- the module's rules --------------------------------------------------------
+
+
+@pytest.mark.parametrize("path", [MODULE_PATH, CLIP_MODULE_PATH], ids=lambda p: p.name)
+def test_modules_have_no_hub_io_or_forbidden_imports(path):
+    source = path.read_text(encoding="utf-8")
+    for name in (
+        "from_pretrained",
+        "hf_hub_download",
+        "cached_file",
+        "snapshot_download",
+    ):
+        assert name not in source, name
+    forbidden = r"open_clip|timm|einops|hydra|tensordict|torchdiffeq|torchaudio"
+    assert not re.search(rf"^\s*(import|from)\s+({forbidden})\b", source, re.M)
+    assert "weights_only=True" in source
+    assert "weights_only=False" not in source
+    # converted DFN5B tensors are never written
+    assert "save_file" not in source and "torch.save" not in source
+    assert "974010a026c731054592d8f777218bd9d85a6c24" in source
+    assert "MIT License" in source and "Sony Research Inc." in source
+    assert len(source.splitlines()) <= 1100
+
+
+def test_weights_are_pinned():
+    assert mm.REPO_ID == "hkchengrex/MMAudio"
+    assert mm.REVISION == "eb13a1a98fdbec91753775c57b074ccdfc60587c"
+    assert mm.NETWORK_FILE == "weights/mmaudio_large_44k_v2.pth"
+    assert mc.CLIP_REPO_ID == "apple/DFN5B-CLIP-ViT-H-14-384"
+    assert mc.CLIP_REVISION == "01b771ed0d1395ca5ffdd279897d665ebe00dfd2"
+
+
+def test_modules_are_not_imported_by_dw():
+    # stage B is inert: nothing in dw imports either module
+    own = {MODULE_PATH, CLIP_MODULE_PATH}
+    for path in MODULE_PATH.parents[1].rglob("*.py"):
+        if path not in own:
+            text = path.read_text(encoding="utf-8")
+            assert "mmaudio_model" not in text and "mmaudio_clip" not in text, path

From a85dcbaab2f3a774e0fbb74b6f80ea95d2ac5fc8 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 11:47:28 -0600
Subject: [PATCH 104/125] feat(tasks): #1132 - vendored Synchformer, MMAudio
 decoder load, frame sampling and centroid

- dw/tasks/mmaudio_sync_model.py: MMAudio's Synchformer visual encoder
  (MotionFormer feature extractor) from upstream 974010a0, no timm/einops/
  omegaconf, torch.load(weights_only=True), strict load; 16-frame segments
  8 apart as encode_video_with_sync.
- dw/tasks/mmaudio_decoder.py: diffusers MMAudioVAE + MMAudioVocoder from
  K6's audio_vae/ and vocoder/ safetensors at 4c487e8b, strict; the audio_vae
  file's embedded vocoder.* copy is dropped before the load.
- dw/media.py sample_frames: frames by round(k/fps*src_fps), 8 fps 384x384
  bicubic (CLIP) or 25 fps 224 short side + centre crop in [-1, 1].
- dw/dsp.py spectral_centroid.
- diffusers floor >=0.42.0; ATTRIBUTIONS and SECURITY rows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ATTRIBUTIONS.md              |   4 +
 docs/SECURITY.md                  |  14 +
 dw/dsp.py                         |  18 ++
 dw/media.py                       |  43 ++-
 dw/server/updater.py              |   2 +-
 dw/tasks/mmaudio_decoder.py       | 127 +++++++++
 dw/tasks/mmaudio_sync_model.py    | 452 ++++++++++++++++++++++++++++++
 pyproject.toml                    |   2 +-
 tests/test_dsp.py                 |  26 ++
 tests/test_media_sample_frames.py | 144 ++++++++++
 tests/test_mmaudio_decoder.py     | 161 +++++++++++
 tests/test_mmaudio_sync_model.py  | 188 +++++++++++++
 12 files changed, 1178 insertions(+), 3 deletions(-)
 create mode 100644 dw/tasks/mmaudio_decoder.py
 create mode 100644 dw/tasks/mmaudio_sync_model.py
 create mode 100644 tests/test_media_sample_frames.py
 create mode 100644 tests/test_mmaudio_decoder.py
 create mode 100644 tests/test_mmaudio_sync_model.py

diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
index 61b8e538..43d201c0 100644
--- a/docs/ATTRIBUTIONS.md
+++ b/docs/ATTRIBUTIONS.md
@@ -18,6 +18,8 @@ Each file keeps its upstream licence notice in its header.
 | [dw/tasks/h3_latent_upscaler_model.py](../dw/tasks/h3_latent_upscaler_model.py) | The MiniMax H3 3D-convolution latent upscaler from [LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler](https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler) | MIT, Copyright (c) LBH-123-AI |
 | [dw/tasks/audio8_tts_model.py](../dw/tasks/audio8_tts_model.py) | The Audio8-TTS (ArkTTS) dual-AR speech model, codec and processor from [Edge0/Audio8-TTS-Realistic-0.6b](https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b/tree/1e857568bfd4f02931aca3988ee773a44d2d26d3), ported (upstream NOTICE kept in the file header) | Apache-2.0 |
 | [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py), [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | The MMAudio flow-matching network, its sequence lengths and classifier-free guidance, and the CLIP conditioning from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24), ported (the sampler is dw's own Euler loop, and the DFN5B towers are transformers' CLIP models filled by a key map) | MIT, Copyright (c) 2024 Sony Research Inc. |
+| [dw/tasks/mmaudio_sync_model.py](../dw/tasks/mmaudio_sync_model.py) | MMAudio's Synchformer visual encoder (a MotionFormer feature extractor) and its 16-frame segmenting, from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24)'s `mmaudio/ext/synchformer/`, ported without timm, einops or omegaconf | MIT, Copyright (c) 2024 Vladimir Iashin |
+| [dw/tasks/mmaudio_decoder.py](../dw/tasks/mmaudio_decoder.py) | Loads diffusers' `MMAudioVAE` and `MMAudioVocoder`; the vocoder is [BigVGAN](https://github.com/NVIDIA/BigVGAN) (no BigVGAN code is copied here: the classes are diffusers') | BigVGAN: MIT, Copyright (c) 2024 NVIDIA CORPORATION |
 | [dw/community_pipelines/pipeline_flux_rf_inversion.py](../dw/community_pipelines/pipeline_flux_rf_inversion.py) | The diffusers community RF-Inversion pipeline, after [RF Inversion](https://rf-inversion.github.io/) by Litu Rout, Yujia Chen, Nataniel Ruiz, Constantine Caramanis, Sanjay Shakkottai and Wen-Sheng Chu | Apache-2.0, Copyright 2024 Black Forest Labs and The HuggingFace Team |
 | [dw/prompt_weighting.py](../dw/prompt_weighting.py) | Based on [sd_embed](https://github.com/xhinker/sd_embed) by Andrew Zhu | Apache-2.0 |
 
@@ -30,6 +32,8 @@ apply to anything generated with them.
 | Weights | Used by | Licence |
 |---|---|---|
 | [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) (`weights/mmaudio_large_44k_v2.pth` and its `ext_weights/`) | [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) `ext_weights/synchformer_state_dict.pth` | MMAudio's sync features, [dw/tasks/mmaudio_sync_model.py](../dw/tasks/mmaudio_sync_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers](https://huggingface.co/kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers/tree/4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81) `audio_vae/` and `vocoder/` | MMAudio's decoder, [dw/tasks/mmaudio_decoder.py](../dw/tasks/mmaudio_decoder.py) | The MMAudio VAE tensors: [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/), non-commercial use only, as MMAudio's weights (K6's model card states MIT; dw follows the stricter MMAudio terms). The BigVGAN vocoder: MIT. |
 | [apple/DFN5B-CLIP-ViT-H-14-384](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384) | MMAudio's CLIP conditioning, [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | [Apple Machine Learning Research Model License](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384/blob/main/LICENSE): research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. dw maps the weights into transformers' layout in memory at load time and never writes or ships converted tensors. |
 
 ## Ideas reimplemented here
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index ff848587..ec0d6e24 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -158,6 +158,20 @@ isn't a tensor or a plain container, and only at that pinned revision. Its
 allowlist (`temperature`, `top_p`, `top_k`, `do_sample`, `max_new_tokens`):
 any other key is refused by name before the model loads.
 
+MMAudio (`dw/tasks/mmaudio_model.py`, `dw/tasks/mmaudio_sync_model.py`,
+`dw/tasks/mmaudio_decoder.py`) runs no code from its repo either: the network
+and the Synchformer visual encoder are vendored at upstream commit
+`974010a0`. Their two checkpoints, `hkchengrex/MMAudio`'s
+`weights/mmaudio_large_44k_v2.pth` and `ext_weights/synchformer_state_dict.pth`,
+are pickles, pinned to one 40-hex revision; each is read with
+`torch.load(weights_only=True)` and loaded strictly, so any object that isn't a
+tensor or a plain container is refused and an unexpected key fails the load.
+The decoder's VAE and vocoder are Kandinsky 6's safetensors at a pinned full
+sha, built from their `config.json` read as JSON (only the class's own
+constructor arguments are taken), with no pickle and no `trust_remote_code`.
+The modules take local paths and never fetch: tests pin that none of them
+calls the Hub or writes a checkpoint.
+
 `text_generation`'s `system_prompt` may be read from a Hub repo file
 (`{"from_hub": {...}}`). That fetch is anonymous only: the Hub is asked
 without credentials (`token=False`) whether it serves the file publicly at the
diff --git a/dw/dsp.py b/dw/dsp.py
index eeb90ae0..87d6f2d6 100644
--- a/dw/dsp.py
+++ b/dw/dsp.py
@@ -378,6 +378,24 @@ def spectral_flatness(waveform, sample_rate=None, native_sample_rate=None):
     return float(numpy.mean(geometric_mean / arithmetic_mean))
 
 
+def spectral_centroid(waveform, sample_rate):
+    """The magnitude-weighted mean frequency (Hz) of the rfft spectrum of a
+    (channels, samples) waveform, averaged across channels - low for bass-heavy
+    or tonal material, high for hiss. 0.0 for an all-zero signal.
+
+    MMAudio's noise warning pairs it with spectral flatness: warn when flatness
+    is at least 0.3 and the centroid at least 8 kHz (thresholds not held here).
+    """
+    spectrum = numpy.abs(numpy.fft.rfft(waveform, axis=1))
+    freqs = numpy.fft.rfftfreq(numpy.shape(waveform)[1], 1.0 / sample_rate)
+    total = spectrum.sum(axis=1)
+    weighted = (spectrum * freqs).sum(axis=1)
+    centroids = numpy.divide(
+        weighted, total, out=numpy.zeros_like(total), where=total > 0
+    )
+    return float(numpy.mean(centroids))
+
+
 def harmonicity(waveform, sample_rate):
     """Normalized autocorrelation peak within a plausible pitch range,
     averaged across channels - near 1 for a strongly periodic signal (voiced
diff --git a/dw/media.py b/dw/media.py
index a622f2cf..2a1db47e 100644
--- a/dw/media.py
+++ b/dw/media.py
@@ -13,7 +13,8 @@
   cannot play) or for a track too long to send whole (#193);
 - decodes that answer arrays and rates, never a step type: `decode_soundtrack`,
   `decode_audio_video`, `decode_rgb_frames`, `read_frames`,
-  `read_frame_range`, `count_video_frames`, `read_thumbnails_and_track`.
+  `read_frame_range`, `count_video_frames`, `read_thumbnails_and_track`,
+  `sample_frames` (a clip at a model's frame rate and size).
 
 PyAV only: this runs in the server process, where a request must not pull in
 torch or materialise frames.
@@ -470,6 +471,46 @@ def read_frames(path, indexes, fit=None):
     return found
 
 
+def sample_frames(path, fps, duration, size, crop=False):
+    """A clip sampled at `fps` for `duration` seconds, as a numpy array.
+
+    Frame k (of int(fps * duration), as upstream MMAudio truncates) is source
+    frame round(k / fps * source_fps); indexes past the clip's last frame are
+    dropped, so a short clip returns fewer frames, and an up-rate repeats
+    some. Each frame is fitted as it decodes, so none is held at source size.
+
+    `crop=False` is MMAudio's CLIP input (8 fps): bicubic to size x size,
+    uint8 (N, size, size, 3). `crop=True` is its Synchformer input (25 fps,
+    224): bicubic to a short side of `size`, centre crop (torchvision's
+    CenterCrop rounding), float32 (N, size, size, 3) in [-1, 1] (mean 0.5,
+    std 0.5). After mmaudio/eval_utils.py `load_video` at commit 974010a0.
+    """
+    if fps <= 0 or duration <= 0 or size <= 0:
+        raise ValueError("fps, duration and size must be positive")
+    shape = video_shape(path)  # raises for a file with no video stream
+    if not shape["fps"]:
+        raise ValueError(f"{path} declares no frame rate")
+    indexes = [round(k / fps * shape["fps"]) for k in range(int(fps * duration))]
+    indexes = [i for i in indexes if i < shape["frame_count"]]
+
+    def fit(image, _index):
+        if crop:
+            scale = size / min(image.size)
+            width, height = (max(size, round(side * scale)) for side in image.size)
+            image = image.resize((width, height), Image.BICUBIC)
+            left, top = (int(round((side - size) / 2.0)) for side in (width, height))
+            return image.crop((left, top, left + size, top + size))
+        return image.resize((size, size), Image.BICUBIC)
+
+    found = read_frames(path, indexes, fit=fit) if indexes else {}
+    frames = (
+        numpy.stack([numpy.asarray(found[i]) for i in indexes])
+        if indexes
+        else (numpy.zeros((0, size, size, 3), numpy.uint8))
+    )
+    return frames.astype(numpy.float32) / 127.5 - 1 if crop else frames
+
+
 def _seek_needed(target, position, fps):
     """Whether reaching frame `target` from `position` takes a seek: going
     back, or a long way forward (more than two seconds of decoding)."""
diff --git a/dw/server/updater.py b/dw/server/updater.py
index 364710a2..2d68c56a 100644
--- a/dw/server/updater.py
+++ b/dw/server/updater.py
@@ -31,7 +31,7 @@
 
 # Used only if pyproject.toml can't be read/parsed at runtime (e.g. running
 # from an installed wheel without the source tree alongside it).
-FALLBACK_RELEASE_FLOOR = "0.40.0"
+FALLBACK_RELEASE_FLOOR = "0.42.0"
 
 # dw/server/updater.py -> dw/server -> dw -> repo root
 _PYPROJECT_PATH = Path(__file__).resolve().parents[2] / "pyproject.toml"
diff --git a/dw/tasks/mmaudio_decoder.py b/dw/tasks/mmaudio_decoder.py
new file mode 100644
index 00000000..8e7d31c8
--- /dev/null
+++ b/dw/tasks/mmaudio_decoder.py
@@ -0,0 +1,127 @@
+"""
+MMAudio - the decoder that turns the flow network's latents into a waveform:
+diffusers' MMAudioVAE (latent -> mel spectrogram) and MMAudioVocoder (the
+BigVGAN vocoder, mel -> 44.1 kHz waveform), v1.
+
+The tensors are Kandinsky 6's: K6_REPO_ID's `audio_vae/` and `vocoder/`
+folders at the full pinned K6_REVISION, each a config.json and a safetensors
+file, all float32. They are MMAudio's VAE and BigVGAN, already in diffusers'
+key layout, so there is no key map and no fuse here (safetensors only) - one
+filter: K6's audio_vae file also carries an embedded copy of the vocoder
+(667 `vocoder.`-prefixed tensors, from the 0.40 dev layout) that the 0.42
+MMAudioVAE does not own, so those keys are dropped before the strict load
+(the vocoder loads from its own folder). The diffusers classes need
+diffusers >= 0.42.0 and are imported when a loader runs, so importing this
+module never needs them.
+
+Licences: the BigVGAN vocoder code and design are MIT (NVIDIA); the MMAudio
+VAE tensors are CC-BY-NC 4.0 per MMAudio (K6's card states MIT) -
+ATTRIBUTIONS.md.
+
+load_decoder() reads only local paths its caller gives: a config.json read
+as JSON and a safetensors file read with safetensors.torch.load_file. It
+never touches the Hub.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from pathlib import Path
+
+import torch
+from safetensors.torch import load_file
+
+K6_REPO_ID = "kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers"
+K6_REVISION = "4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81"
+VAE_FOLDER = "audio_vae"
+VOCODER_FOLDER = "vocoder"
+CONFIG_FILE = "config.json"
+WEIGHTS_FILE = "diffusion_pytorch_model.safetensors"
+
+# Prefix of the vocoder copy K6's audio_vae file carries but MMAudioVAE does not own.
+_EMBEDDED_VOCODER = "vocoder."
+
+__all__ = [
+    "CONFIG_FILE",
+    "K6_REPO_ID",
+    "K6_REVISION",
+    "VAE_FOLDER",
+    "VOCODER_FOLDER",
+    "WEIGHTS_FILE",
+    "MMAudioDecoder",
+    "decode_latents",
+    "load_decoder",
+]
+
+
+def _init_kwargs(cls, config):
+    """The config's entries cls.__init__ takes. K6's audio_vae config also
+    names keys the 0.42 class does not (mode, downsample_factor, a nested
+    vocoder_config), which are dropped rather than passed through."""
+    accepted = set(inspect.signature(cls.__init__).parameters) - {"self"}
+    return {key: value for key, value in config.items() if key in accepted}
+
+
+def _load_component(cls, folder, drop_prefix=None):
+    folder = Path(folder)
+    config = json.loads((folder / CONFIG_FILE).read_text(encoding="utf-8"))
+    state = load_file(str(folder / WEIGHTS_FILE), device="cpu")
+    if drop_prefix:
+        state = {k: v for k, v in state.items() if not k.startswith(drop_prefix)}
+    with torch.device("meta"):
+        model = cls(**_init_kwargs(cls, config))
+    model.load_state_dict(state, strict=True, assign=True)
+    return model
+
+
+class MMAudioDecoder:
+    """The VAE and vocoder as one latent -> waveform decode."""
+
+    def __init__(self, vae, vocoder):
+        self.vae = vae
+        self.vocoder = vocoder
+
+    @property
+    def samples_per_latent(self):
+        """Waveform samples per latent frame: the VAE's two-times-hop mel
+        frames per latent, each one vocoder hop long (1024 at 44.1 kHz)."""
+        return self.vae.config.hop_length * 2
+
+    @property
+    def sample_rate(self):
+        return self.vae.config.sample_rate
+
+    def to(self, device=None, dtype=None):
+        self.vae.to(device=device, dtype=dtype)
+        self.vocoder.to(device=device, dtype=dtype)
+        return self
+
+    def decode(self, latents):
+        """`latents` (B, latent_channels, frames), already divided by the
+        VAE's scaling_factor, to a waveform (B, 1, frames * samples_per_latent)."""
+        return decode_latents(self.vae, self.vocoder, latents)
+
+
+def decode_latents(vae, vocoder, latents):
+    """Latents (B, C, F) -> mel (B, mel_bins, 2F) -> waveform (B, 1, 1024F)."""
+    with torch.inference_mode():
+        param = next(vae.parameters())
+        latents = latents.to(device=param.device, dtype=param.dtype)
+        mel = vae.decode(latents).sample
+        waveform = vocoder(mel).sample
+    if waveform.dim() == 2:
+        waveform = waveform.unsqueeze(1)
+    return waveform
+
+
+def load_decoder(vae_folder, vocoder_folder, device="cpu", dtype=torch.float32):
+    """Build MMAudioVAE and MMAudioVocoder from local K6 `audio_vae/` and
+    `vocoder/` folders (config.json + safetensors each), strictly, in eval."""
+    from diffusers import MMAudioVAE, MMAudioVocoder  # needs diffusers >= 0.42.0
+
+    vae = _load_component(MMAudioVAE, vae_folder, drop_prefix=_EMBEDDED_VOCODER)
+    vocoder = _load_component(MMAudioVocoder, vocoder_folder)
+    for model in (vae, vocoder):
+        model.to(device=device, dtype=dtype).eval().requires_grad_(False)
+    return MMAudioDecoder(vae, vocoder)
diff --git a/dw/tasks/mmaudio_sync_model.py b/dw/tasks/mmaudio_sync_model.py
new file mode 100644
index 00000000..c46da500
--- /dev/null
+++ b/dw/tasks/mmaudio_sync_model.py
@@ -0,0 +1,452 @@
+"""
+MMAudio - the Synchformer visual encoder (a MotionFormer feature extractor)
+that turns video frames into the synchronisation features the network
+conditions on, v1.
+
+Vendored from https://github.com/hkchengrex/MMAudio at commit
+974010a026c731054592d8f777218bd9d85a6c24 (mmaudio/ext/synchformer/
+synchformer.py, motionformer.py, video_model_builder.py, vit_helper.py and
+divided_224_16x4.yaml, merged into this one file, plus the segmenting of
+mmaudio/model/utils/features_utils.py's encode_video_with_sync). The weights
+are hkchengrex/MMAudio's ext_weights/synchformer_state_dict.pth (REPO_ID /
+REVISION / SYNC_FILE below), under their own licence, stricter than this
+code's: CC-BY-NC 4.0, non-commercial use only.
+
+Carried over as written: the divided space-time vision transformer (the 3D
+patch embedding, the class token and separate spatial / temporal position
+embeddings, the divided attention in which the class token attends to every
+patch and the patches attend across time or across space, the MLP blocks),
+the spatial aggregation layer (a class-token transformer encoder layer) and
+the identity temporal aggregation of Synchformer(), the 16-frame segments
+with a step of 8, and every parameter and submodule name, so the checkpoint
+loads strictly: the keys are upstream's, under the `vfeat_extractor.` prefix.
+The patch embedding of the 2D stem and the projection of the 3D one are kept
+as parameters although the forward pass only uses the 3D one, as upstream.
+
+Changed in the port, so nothing here touches the Hub, a network, timm,
+einops, omegaconf or hydra:
+- The configuration of divided_224_16x4.yaml and the patches of
+  MotionFormer.__init__ (APPROX_ATTN_DIM and the others) are the SyncConfig
+  dataclass; only the divided, separate-position, extract-features,
+  factorized path of Synchformer() is carried. The checkpoint and config
+  download, the ckpt_path branches, the joint and plain attention blocks, the
+  other aggregation modules, the global representation, the classification
+  heads, token masks, drop-path and training initialisation are not: the
+  head, pre-logits and dropouts are identity (so own no keys) and the
+  weights always load from the checkpoint. load_synchformer() reads a local
+  .pth path its caller gives, with torch.load(weights_only=True), strictly.
+- einops rearranges and reductions are plain view/permute/reshape calls;
+  the attention uses torch's scaled_dot_product_attention with upstream's
+  scale; trunc_normal_ is torch.nn.init's. No float64 anywhere.
+- The upstream sources carry Facebook (Motionformer) and Ross Wightman
+  copyright headers; the licence below is the one upstream's synchformer
+  directory ships.
+
+MIT License
+
+Copyright (c) 2024 Vladimir Iashin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import partial
+from pathlib import Path
+from typing import Any, Mapping
+
+import torch
+import torch.nn.functional as F
+from torch import nn
+
+REPO_ID = "hkchengrex/MMAudio"
+REVISION = "eb13a1a98fdbec91753775c57b074ccdfc60587c"
+SYNC_FILE = "ext_weights/synchformer_state_dict.pth"
+
+__all__ = [
+    "REPO_ID",
+    "REVISION",
+    "SYNC_FILE",
+    "SyncConfig",
+    "Synchformer",
+    "encode_sync_frames",
+    "load_synchformer",
+]
+
+# upstream's segmenting of a video: windows 8 frames apart (16 frames each by default)
+STEP_SIZE = 8
+
+
+# --- configuration -----------------------------------------------------------
+
+
+@dataclass
+class SyncConfig:
+    """divided_224_16x4.yaml's VIT / DATA values with the patches of
+    MotionFormer.__init__ (the defaults), the shape of the vision transformer."""
+
+    image_size: int = 224
+    patch_size: int = 16
+    patch_size_temp: int = 2
+    in_chans: int = 3
+    embed_dim: int = 768
+    depth: int = 12
+    num_heads: int = 12
+    mlp_ratio: int = 4
+    qkv_bias: bool = True
+    temporal_resolution: int = 8
+    segment_frames: int = 16
+
+    def __post_init__(self) -> None:
+        if self.embed_dim % self.num_heads:
+            raise ValueError("embed_dim must be a multiple of num_heads")
+        if self.segment_frames != self.temporal_resolution * self.patch_size_temp:
+            raise ValueError(
+                "segment_frames must be temporal_resolution * patch_size_temp"
+            )
+
+    @property
+    def grid(self) -> int:
+        """Patches along each side of a frame."""
+        return self.image_size // self.patch_size
+
+
+# --- layers (vit_helper.py) --------------------------------------------------
+
+
+class Mlp(nn.Module):
+    def __init__(self, in_features: int, hidden_features: int) -> None:
+        super().__init__()
+        self.fc1 = nn.Linear(in_features, hidden_features)
+        self.act = nn.GELU()
+        self.fc2 = nn.Linear(hidden_features, in_features)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.fc2(self.act(self.fc1(x)))
+
+
+class PatchEmbed(nn.Module):
+    """Image to patch embedding; only its geometry is used (the 3D one embeds)."""
+
+    def __init__(
+        self, img_size: int, patch_size: int, in_chans: int, embed_dim: int
+    ) -> None:
+        super().__init__()
+        self.num_patches = (img_size // patch_size) ** 2
+        self.proj = nn.Conv2d(
+            in_chans, embed_dim, kernel_size=patch_size, stride=patch_size
+        )
+
+
+class PatchEmbed3D(nn.Module):
+    """Video to patch embedding: (B, C, T, H, W) -> (B, t*h*w, D)."""
+
+    def __init__(
+        self,
+        img_size: int,
+        in_chans: int,
+        patch_size: int,
+        z_block_size: int,
+        embed_dim: int,
+    ) -> None:
+        super().__init__()
+        self.height = img_size // patch_size
+        self.width = img_size // patch_size
+        self.z_block_size = z_block_size
+        self.proj = nn.Conv3d(
+            in_chans,
+            embed_dim,
+            kernel_size=(z_block_size, patch_size, patch_size),
+            stride=(z_block_size, patch_size, patch_size),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.proj(x).flatten(2).transpose(1, 2)
+
+
+class DividedAttention(nn.Module):
+    """Attention in which the class token sees every token and the patches see
+    their own time or space group plus the class token (upstream's, no masks)."""
+
+    def __init__(self, dim: int, num_heads: int, qkv_bias: bool) -> None:
+        super().__init__()
+        self.num_heads = num_heads
+        self.scale = (dim // num_heads) ** -0.5
+        self.qkv = nn.Linear(dim, dim * 3, bias=qkv_bias)
+        self.proj = nn.Linear(dim, dim)
+
+    def _attend(self, q, k, v) -> torch.Tensor:
+        return F.scaled_dot_product_attention(q, k, v, scale=self.scale)
+
+    def forward(self, x: torch.Tensor, mode: str, size: int) -> torch.Tensor:
+        """mode "time": size is n, patches per frame, and time is the sequence;
+        mode "space": size is f, frames, and each frame's patches are."""
+        b, n_tok, dim = x.shape
+        h = self.num_heads
+        d = dim // h
+        q, k, v = self.qkv(x).chunk(3, dim=-1)
+        # (b, n, h*d) -> (b*h, n, d)
+        q, k, v = (
+            t.reshape(b, n_tok, h, d).permute(0, 2, 1, 3).reshape(b * h, n_tok, d)
+            for t in (q, k, v)
+        )
+        bh = b * h
+
+        # the class token attends to the keys / values of every token
+        cls_out = self._attend(q[:, :1], k, v)
+
+        q_, k_, v_ = q[:, 1:], k[:, 1:], v[:, 1:]
+        if mode == "time":
+            n = size
+            f = (n_tok - 1) // n
+            # 'b (f n) d -> (b n) f d'
+            q_, k_, v_ = (
+                t.reshape(bh, f, n, d).transpose(1, 2).reshape(bh * n, f, d)
+                for t in (q_, k_, v_)
+            )
+        else:
+            f = size
+            n = (n_tok - 1) // f
+            # 'b (f n) d -> (b f) n d'
+            q_, k_, v_ = (t.reshape(bh * f, n, d) for t in (q_, k_, v_))
+
+        # the class key / value joins every group
+        r = q_.shape[0] // bh
+        cls_k = k[:, :1].repeat_interleave(r, dim=0)
+        cls_v = v[:, :1].repeat_interleave(r, dim=0)
+        out = self._attend(
+            q_, torch.cat((cls_k, k_), dim=1), torch.cat((cls_v, v_), dim=1)
+        )
+
+        if mode == "time":
+            # '(b n) f d -> b (f n) d'
+            out = out.reshape(bh, n, f, d).transpose(1, 2).reshape(bh, f * n, d)
+        else:
+            out = out.reshape(bh, f * n, d)
+        out = torch.cat((cls_out, out), dim=1)
+        # '(b h) n d -> b n (h d)'
+        out = out.reshape(b, h, n_tok, d).permute(0, 2, 1, 3).reshape(b, n_tok, dim)
+        return self.proj(out)
+
+
+class DividedSpaceTimeBlock(nn.Module):
+    def __init__(
+        self,
+        dim: int,
+        num_heads: int,
+        mlp_ratio: int,
+        qkv_bias: bool,
+        norm_layer,
+    ) -> None:
+        super().__init__()
+        self.norm1 = norm_layer(dim)
+        self.attn = DividedAttention(dim, num_heads, qkv_bias)
+        self.timeattn = DividedAttention(dim, num_heads, qkv_bias)
+        self.norm2 = norm_layer(dim)
+        self.mlp = Mlp(dim, int(dim * mlp_ratio))
+        self.norm3 = norm_layer(dim)
+
+    def forward(self, x: torch.Tensor, seq_len: int, num_frames: int) -> torch.Tensor:
+        x = x + self.timeattn(self.norm3(x), "time", seq_len)
+        x = x + self.attn(self.norm1(x), "space", num_frames)
+        return x + self.mlp(self.norm2(x))
+
+
+# --- spatial aggregation (motionformer.py) -----------------------------------
+
+
+class SpatialTransformerEncoderLayer(nn.TransformerEncoderLayer):
+    """Aggregates the patches of each frame into the class token's output: an
+    encoder layer (its keys are torch's) with a class token of its own."""
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self.cls_token = nn.Parameter(torch.zeros(1, 1, self.self_attn.embed_dim))
+        nn.init.trunc_normal_(self.cls_token, std=0.02)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:  # type: ignore[override]
+        """x is (B*S*t, h*w, D); returns (B*S*t, D)."""
+        cls_tokens = self.cls_token.expand(x.shape[0], -1, -1)
+        x = torch.cat((cls_tokens, x), dim=-2)
+        return super().forward(x)[:, 0, :]
+
+
+# --- the encoder (video_model_builder.py, motionformer.py) -------------------
+
+
+class MotionFormer(nn.Module):
+    """VisionTransformer + MotionFormer with extract_features, factorized
+    space and time, a transformer-layer spatial aggregation and an identity
+    temporal one: (B, S, C, T, H, W) -> (B, S, t, D)."""
+
+    def __init__(self, cfg: SyncConfig) -> None:
+        super().__init__()
+        self.cfg = cfg
+        self.embed_dim = cfg.embed_dim
+        self.temporal_resolution = cfg.temporal_resolution
+        norm_layer = partial(nn.LayerNorm, eps=1e-6)
+
+        # the 2D stem is only used for its geometry, its weights are kept
+        self.patch_embed = PatchEmbed(
+            cfg.image_size, cfg.patch_size, cfg.in_chans, cfg.embed_dim
+        )
+        self.patch_embed_3d = PatchEmbed3D(
+            cfg.image_size,
+            cfg.in_chans,
+            cfg.patch_size,
+            cfg.patch_size_temp,
+            cfg.embed_dim,
+        )
+        self.cls_token = nn.Parameter(torch.zeros(1, 1, cfg.embed_dim))
+        self.pos_embed = nn.Parameter(
+            torch.zeros(1, self.patch_embed.num_patches + 1, cfg.embed_dim)
+        )
+        self.temp_embed = nn.Parameter(
+            torch.zeros(1, cfg.temporal_resolution, cfg.embed_dim)
+        )
+        self.blocks = nn.ModuleList(
+            DividedSpaceTimeBlock(
+                cfg.embed_dim, cfg.num_heads, cfg.mlp_ratio, cfg.qkv_bias, norm_layer
+            )
+            for _ in range(cfg.depth)
+        )
+        self.norm = norm_layer(cfg.embed_dim)
+        # no classification head, pre-logits or dropout: identity, no keys
+        self.spatial_attn_agg = SpatialTransformerEncoderLayer(
+            d_model=cfg.embed_dim,
+            nhead=cfg.num_heads,
+            activation=nn.GELU(),
+            batch_first=True,
+            dim_feedforward=cfg.mlp_ratio * cfg.embed_dim,
+            dropout=0.0,
+            layer_norm_eps=1e-6,
+            norm_first=True,
+        )
+        self.temp_attn_agg = nn.Identity()
+        self._init_weights()
+
+    def _init_weights(self) -> None:
+        for p in (self.cls_token, self.pos_embed):
+            nn.init.trunc_normal_(p, std=0.02)
+        nn.init.trunc_normal_(self.temp_embed, std=0.02)
+        for m in self.modules():
+            if isinstance(m, nn.Linear):
+                nn.init.trunc_normal_(m.weight, std=0.02)
+                if m.bias is not None:
+                    nn.init.constant_(m.bias, 0)
+            elif isinstance(m, nn.LayerNorm):
+                nn.init.constant_(m.bias, 0)
+                nn.init.constant_(m.weight, 1.0)
+
+    def forward_features(self, x: torch.Tensor) -> torch.Tensor:
+        """x is (B*S, C, T, H, W); returns (B*S, 1 + t*h*w, D)."""
+        x = self.patch_embed_3d(x)
+        x = torch.cat((self.cls_token.expand(x.shape[0], -1, -1), x), dim=1)
+
+        # separate position embeddings: space tiled over time, time over space
+        npatch = self.patch_embed.num_patches
+        cls_embed = self.pos_embed[:, :1, :]
+        tile_pos = self.pos_embed[:, 1:, :].repeat(1, self.temporal_resolution, 1)
+        tile_temp = self.temp_embed.repeat_interleave(npatch, 1)
+        x = x + torch.cat([cls_embed, tile_pos + tile_temp], dim=1)
+
+        for blk in self.blocks:
+            x = blk(x, seq_len=npatch, num_frames=self.temporal_resolution)
+        return x
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        B, S, C, T, H, W = x.shape
+        x = self.forward_features(x.reshape(B * S, C, T, H, W))
+        x = self.norm(x[:, 1:, :])  # without the class token
+        # (B*S, t*h*w, D) -> (B*S*t, h*w, D): the tokens are ordered (t, h, w)
+        t = T // self.patch_embed_3d.z_block_size
+        hw = self.patch_embed_3d.height * self.patch_embed_3d.width
+        x = x.reshape(B * S * t, hw, self.embed_dim)
+        x = self.spatial_attn_agg(x).reshape(B * S, t, self.embed_dim)
+        x = self.temp_attn_agg(x)
+        return x.view(B, S, *x.shape[1:])
+
+
+class Synchformer(nn.Module):
+    """Upstream's Synchformer(): only the visual feature extractor."""
+
+    def __init__(self, config: SyncConfig | None = None) -> None:
+        super().__init__()
+        self.config = config or SyncConfig()
+        self.vfeat_extractor = MotionFormer(self.config)
+
+    def forward(self, vis: torch.Tensor) -> torch.Tensor:
+        """vis is (B, S, Tv, C, H, W); returns (B, S, t, D), e.g. (B, 7, 8, 768)."""
+        return self.vfeat_extractor(vis.permute(0, 1, 3, 2, 4, 5))  # (B, S, C, Tv, ..)
+
+    def load_state_dict(  # type: ignore[override]
+        self, state_dict: Mapping[str, Any], strict: bool = True, assign: bool = False
+    ):
+        # discard all entries except vfeat_extractor, as upstream
+        state_dict = {
+            k: v for k, v in state_dict.items() if k.startswith("vfeat_extractor")
+        }
+        return super().load_state_dict(state_dict, strict=strict, assign=assign)
+
+
+def load_synchformer(
+    path,
+    device="cpu",
+    dtype: torch.dtype = torch.float32,
+    config: SyncConfig | None = None,
+) -> Synchformer:
+    """Build the encoder from a local checkpoint (a plain state dict), loaded
+    with weights_only=True and strictly; entries outside vfeat_extractor are
+    dropped, as upstream."""
+    state = torch.load(Path(path), map_location="cpu", weights_only=True)
+    with torch.device("meta"):
+        model = Synchformer(config)
+    model.load_state_dict(state, strict=True, assign=True)
+    return model.to(device=device, dtype=dtype).eval().requires_grad_(False)
+
+
+@torch.inference_mode()
+def encode_sync_frames(
+    model: Synchformer, frames: torch.Tensor, batch_size: int = -1
+) -> torch.Tensor:
+    """Upstream's encode_video_with_sync: frames (B, T, 3, H, W) in 16-frame
+    segments 8 apart -> (B, num_segments * t, D)."""
+    b, t, c, h, w = frames.shape
+    size = model.config.image_size
+    if c != model.config.in_chans or h != size or w != size:
+        raise ValueError(
+            f"frames must be (B, T, 3, {size}, {size}), got {tuple(frames.shape)}"
+        )
+    segment = model.config.segment_frames
+    step = STEP_SIZE
+    if t < segment:
+        raise ValueError(f"need at least {segment} frames, got {t}")
+    num_segments = (t - segment) // step + 1
+    x = torch.stack(
+        [frames[:, i * step : i * step + segment] for i in range(num_segments)], dim=1
+    )  # (B, S, T, C, H, W)
+    x = x.reshape(b * num_segments, 1, segment, c, h, w)
+    if batch_size < 0:
+        batch_size = b
+    outputs = [
+        model(x[i : i + batch_size]) for i in range(0, b * num_segments, batch_size)
+    ]
+    x = torch.cat(outputs, dim=0)  # (B*S, 1, t, D)
+    return x.reshape(b, num_segments * x.shape[2], x.shape[3])
diff --git a/pyproject.toml b/pyproject.toml
index ff19b9df..501f7e7e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -36,7 +36,7 @@ dependencies = [
     # Diffusers and the HuggingFace ecosystem. The floor is the newest
     # PyPI release; the newest pipelines may need git HEAD on top, which
     # install.sh layers on (and the web UI's Models page can install)
-    "diffusers>=0.40.0",
+    "diffusers>=0.42.0",
     # The floor is past 5.17.0, whose TextToAudioPipeline.preprocess called
     # BatchEncoding.to(dtype=...) and broke every generate_speech call (#169,
     # #232); later releases only cast a BatchFeature, so the exclusion that
diff --git a/tests/test_dsp.py b/tests/test_dsp.py
index 8a9fe01d..bff8490e 100644
--- a/tests/test_dsp.py
+++ b/tests/test_dsp.py
@@ -14,6 +14,7 @@
 from dw.dsp import (
     SILENCE_DBFS,
     TRUE_PEAK_OVERSAMPLE,
+    spectral_centroid,
     true_peak_dbfs,
     true_peak_envelope,
 )
@@ -69,3 +70,28 @@ def test_resample_waveform_length_is_exact_716():
     for n, src, dst in [(330667, 32000, 44100), (123457, 24000, 44100)]:
         out = resample_waveform(numpy.zeros((2, n), dtype="float32"), src, dst)
         assert out.shape[1] == int(round(n * dst / src))
+
+
+def test_spectral_centroid_of_a_sine_is_its_frequency():
+    time = numpy.arange(44100) / 44100
+    sine = numpy.sin(2 * math.pi * 1000.0 * time)[None, :]
+
+    assert spectral_centroid(sine, 44100) == pytest.approx(1000.0, rel=0.01)
+
+
+def test_spectral_centroid_of_white_noise_is_a_quarter_of_the_rate():
+    noise = numpy.random.default_rng(3).standard_normal((1, 44100))
+
+    assert spectral_centroid(noise, 44100) == pytest.approx(11025.0, rel=0.03)
+
+
+def test_spectral_centroid_averages_channels():
+    time = numpy.arange(44100) / 44100
+    both = numpy.stack([numpy.sin(2 * math.pi * f * time) for f in (1000.0, 3000.0)])
+
+    assert spectral_centroid(both, 44100) == pytest.approx(2000.0, rel=0.01)
+
+
+def test_spectral_centroid_of_silence_is_zero(recwarn):
+    assert spectral_centroid(numpy.zeros((2, 4410)), 44100) == 0.0
+    assert not recwarn.list
diff --git a/tests/test_media_sample_frames.py b/tests/test_media_sample_frames.py
new file mode 100644
index 00000000..a108091b
--- /dev/null
+++ b/tests/test_media_sample_frames.py
@@ -0,0 +1,144 @@
+"""dw.media.sample_frames: a clip at a model's frame rate and size, by source
+frame index (MMAudio's CLIP 8 fps / 384 and Synchformer 25 fps / 224 inputs)."""
+
+import av
+import numpy
+import pytest
+
+from dw.media import sample_frames
+
+SECONDS = 2.0
+WIDTH, HEIGHT = 64, 48
+
+
+def level(index):
+    return (index * 7) % 200 + 20
+
+
+def write_clip(path, fps, frames, frame_pixels):
+    container = av.open(str(path), "w")
+    stream = container.add_stream("libx264", rate=fps)
+    stream.width, stream.height, stream.pix_fmt = WIDTH, HEIGHT, "yuv420p"
+    stream.options = {"crf": "0", "preset": "ultrafast"}
+    for index in range(frames):
+        frame = av.VideoFrame.from_ndarray(frame_pixels(index), format="rgb24")
+        for packet in stream.encode(frame):
+            container.mux(packet)
+    for packet in stream.encode():
+        container.mux(packet)
+    container.close()
+
+
+def grey(index):
+    return numpy.full((HEIGHT, WIDTH, 3), level(index), numpy.uint8)
+
+
+@pytest.fixture(params=[30, 24])
+def clip(request, tmp_path):
+    path = tmp_path / f"clip{request.param}.mp4"
+    write_clip(path, request.param, int(request.param * SECONDS), grey)
+    return str(path), request.param
+
+
+@pytest.mark.parametrize("fps,expected", [(8, 16), (25, 50)])
+def test_counts_follow_the_target_rate(clip, fps, expected):
+    path, _ = clip
+
+    assert len(sample_frames(path, fps, SECONDS, 16)) == expected
+
+
+def test_a_short_clip_returns_only_the_frames_it_has(clip):
+    path, source_fps = clip
+    count = int(source_fps * SECONDS)
+    wanted = [round(k / 8 * source_fps) for k in range(24)]
+
+    frames = sample_frames(path, 8, 3.0, 16)
+
+    assert len(frames) == sum(1 for i in wanted if i < count) == 16
+
+
+@pytest.mark.parametrize("fps", [8, 25])
+def test_frame_k_comes_from_the_rounded_source_index(clip, fps):
+    path, source_fps = clip
+
+    frames = sample_frames(path, fps, SECONDS, 16)
+
+    for k, frame in enumerate(frames):
+        source = round(k / fps * source_fps)
+        assert frame.mean() == pytest.approx(level(source), abs=3)
+
+
+def test_clip_path_is_square_uint8(clip):
+    path, _ = clip
+
+    frames = sample_frames(path, 8, SECONDS, 384)
+
+    assert frames.shape == (16, 384, 384, 3)
+    assert frames.dtype == numpy.uint8
+
+
+def test_small_square_resize_keeps_uint8(clip):
+    path, _ = clip
+
+    frames = sample_frames(path, 8, SECONDS, 32)
+
+    assert frames.shape == (16, 32, 32, 3) and frames.dtype == numpy.uint8
+
+
+def test_synchformer_path_is_float_in_unit_range(clip):
+    path, _ = clip
+
+    frames = sample_frames(path, 25, SECONDS, 224, crop=True)
+
+    assert frames.shape == (50, 224, 224, 3)
+    assert frames.dtype == numpy.float32
+    assert frames.min() >= -1.0 and frames.max() <= 1.0
+    assert frames[0].mean() == pytest.approx(level(0) / 127.5 - 1, abs=0.05)
+
+
+def test_centre_crop_takes_the_middle(tmp_path):
+    def thirds(_index):
+        pixels = numpy.full((HEIGHT, WIDTH, 3), 20, numpy.uint8)
+        pixels[:, WIDTH // 3 : 2 * WIDTH // 3] = 220
+        return pixels
+
+    write_clip(tmp_path / "thirds.mp4", 30, 30, thirds)
+
+    cropped = sample_frames(str(tmp_path / "thirds.mp4"), 8, 1.0, 32, crop=True)
+    squashed = sample_frames(str(tmp_path / "thirds.mp4"), 8, 1.0, 32)
+
+    # 64x48 -> short side 32 -> 43x32 -> a 32-wide window is the middle,
+    # whose centre is bright and whose edges are only the bright third's slope
+    centre = cropped[0][:, 12:20].mean()
+    assert centre > 0.6
+    assert cropped[0][:, :2].mean() < -0.5
+    # without the crop the whole width is squeezed in, so the edges are dark
+    # too but the dark side bands are wider in the crop's view of the same frame
+    assert squashed[0][:, :2].mean() < 60
+
+
+def test_bad_arguments_raise(clip):
+    path, _ = clip
+
+    for args in [(0, 1.0, 8), (8, 0, 8), (8, 1.0, 0), (-1, 1.0, 8)]:
+        with pytest.raises(ValueError):
+            sample_frames(path, *args)
+
+
+def test_audio_only_file_raises(tmp_path):
+    path = tmp_path / "tone.wav"
+    container = av.open(str(path), "w")
+    stream = container.add_stream("pcm_s16le", rate=8000)
+    stream.layout = "mono"
+    frame = av.AudioFrame.from_ndarray(
+        numpy.zeros((1, 800), numpy.int16), format="s16", layout="mono"
+    )
+    frame.sample_rate = 8000
+    for packet in stream.encode(frame):
+        container.mux(packet)
+    for packet in stream.encode():
+        container.mux(packet)
+    container.close()
+
+    with pytest.raises(ValueError):
+        sample_frames(str(path), 8, 1.0, 16)
diff --git a/tests/test_mmaudio_decoder.py b/tests/test_mmaudio_decoder.py
new file mode 100644
index 00000000..c3125267
--- /dev/null
+++ b/tests/test_mmaudio_decoder.py
@@ -0,0 +1,161 @@
+"""MMAudio decoder loader (#1132): MMAudioVAE + MMAudioVocoder from K6-shaped
+folders, strictly, from safetensors, with no Hub I/O or pickle."""
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+import torch
+
+from dw.tasks import mmaudio_decoder as dec
+
+diffusers = pytest.importorskip("diffusers")
+needs_mmaudio = pytest.mark.skipif(
+    not hasattr(diffusers, "MMAudioVAE"),
+    reason="needs diffusers >= 0.42.0 (MMAudioVAE / MMAudioVocoder)",
+)
+
+SOURCE = Path(dec.__file__).read_text(encoding="utf-8")
+
+# A tiny VAE / vocoder pair whose hops agree: the vocoder upsamples
+# 4 * 4 * 4 = 64 = the VAE hop_length.
+VAE_CONFIG = {
+    "_class_name": "MMAudioVAE",
+    "mel_bins": 16,
+    "latent_channels": 4,
+    "hidden_channels": 16,
+    "channel_multipliers": [1, 2],
+    "layers_per_block": 1,
+    "sample_rate": 16000,
+    "n_fft": 256,
+    "hop_length": 64,
+    "scaling_factor": 0.417,
+    # keys K6's 0.40-dev config carries that the 0.42 class does not take
+    "mode": "44k",
+    "downsample_factor": 128,
+    "vocoder_config": {"num_mels": 16},
+}
+VOCODER_CONFIG = {
+    "_class_name": "MMAudioVocoder",
+    "num_mels": 16,
+    "upsample_initial_channel": 16,
+    "upsample_rates": [4, 4, 4],
+    "upsample_kernel_sizes": [8, 8, 8],
+    "resblock_kernel_sizes": [3],
+    "resblock_dilation_sizes": [[1, 3]],
+}
+
+
+def _randomize(module, seed):
+    gen = torch.Generator().manual_seed(seed)
+    with torch.no_grad():
+        for p in module.parameters():
+            p.copy_(torch.randn(p.shape, generator=gen) * 0.1)
+    return module
+
+
+def _write(folder, cls, config, seed, extra=None):
+    from safetensors.torch import save_file
+
+    folder.mkdir(parents=True)
+    (folder / dec.CONFIG_FILE).write_text(json.dumps(config))
+    model = cls(**dec._init_kwargs(cls, config))
+    _randomize(model, seed)
+    state = {k: v.contiguous() for k, v in model.state_dict().items()}
+    state.update(extra or {})
+    save_file(state, str(folder / dec.WEIGHTS_FILE))
+    return model
+
+
+@pytest.fixture
+def k6_folders(tmp_path):
+    vocoder = _write(
+        tmp_path / dec.VOCODER_FOLDER, diffusers.MMAudioVocoder, VOCODER_CONFIG, 1
+    )
+    # K6's audio_vae file embeds a vocoder copy under `vocoder.`; the loader drops it.
+    embedded = {f"vocoder.{k}": v.clone() for k, v in vocoder.state_dict().items()}
+    vae = _write(
+        tmp_path / dec.VAE_FOLDER, diffusers.MMAudioVAE, VAE_CONFIG, 2, embedded
+    )
+    return tmp_path, vae, vocoder
+
+
+@needs_mmaudio
+def test_loader_builds_both_classes_and_decodes_to_the_right_length(k6_folders):
+    root, vae_ref, vocoder_ref = k6_folders
+    decoder = dec.load_decoder(root / dec.VAE_FOLDER, root / dec.VOCODER_FOLDER)
+    assert isinstance(decoder.vae, diffusers.MMAudioVAE)
+    assert isinstance(decoder.vocoder, diffusers.MMAudioVocoder)
+    assert not decoder.vae.training and not decoder.vocoder.training
+    for loaded, ref in ((decoder.vae, vae_ref), (decoder.vocoder, vocoder_ref)):
+        for (name, a), (_, b) in zip(
+            loaded.state_dict().items(), ref.state_dict().items()
+        ):
+            assert torch.equal(a, b), name
+    assert decoder.samples_per_latent == 2 * VAE_CONFIG["hop_length"]
+    assert decoder.sample_rate == VAE_CONFIG["sample_rate"]
+
+    latent_frames = 6
+    z = torch.randn(2, VAE_CONFIG["latent_channels"], latent_frames)
+    waveform = decoder.decode(z)
+    assert waveform.shape == (2, 1, latent_frames * decoder.samples_per_latent)
+    assert torch.isfinite(waveform).all()
+
+
+@needs_mmaudio
+def test_loader_is_strict(k6_folders, tmp_path):
+    root, _, _ = k6_folders
+    from safetensors.torch import load_file, save_file
+
+    weights = root / dec.VOCODER_FOLDER / dec.WEIGHTS_FILE
+    state = load_file(str(weights))
+    state.pop(next(iter(state)))
+    save_file(state, str(weights))
+    with pytest.raises(RuntimeError, match="Missing key"):
+        dec.load_decoder(root / dec.VAE_FOLDER, root / dec.VOCODER_FOLDER)
+
+
+@needs_mmaudio
+def test_init_kwargs_drops_keys_the_class_does_not_take():
+    kwargs = dec._init_kwargs(diffusers.MMAudioVAE, VAE_CONFIG)
+    assert "mode" not in kwargs and "vocoder_config" not in kwargs
+    assert "_class_name" not in kwargs and kwargs["hop_length"] == 64
+
+
+def test_module_rules():
+    for banned in (
+        "from_pretrained",
+        "hf_hub_download",
+        "cached_file",
+        "snapshot_download",
+        "torch.load(",
+        "pickle",
+        "save_file",
+        "torch.save",
+    ):
+        assert banned not in SOURCE, banned
+    assert not re.search(
+        r"^\s*(import|from)\s+(open_clip|timm|einops|hydra|omegaconf)\b",
+        SOURCE,
+        re.M,
+    )
+    # diffusers is imported inside the loader, so the module imports without it
+    assert not re.search(r"^(import|from)\s+diffusers\b", SOURCE, re.M)
+    assert len(SOURCE.splitlines()) <= 1100
+
+
+def test_weights_are_pinned():
+    assert dec.K6_REPO_ID == "kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers"
+    assert re.fullmatch(r"[0-9a-f]{40}", dec.K6_REVISION)
+    assert dec.K6_REVISION == "4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81"
+    assert (dec.VAE_FOLDER, dec.VOCODER_FOLDER) == ("audio_vae", "vocoder")
+    assert dec.WEIGHTS_FILE.endswith(".safetensors")
+
+
+def test_module_is_not_imported_by_dw():
+    dw_root = Path(dec.__file__).resolve().parents[1]
+    for path in dw_root.rglob("*.py"):
+        if path.name == "mmaudio_decoder.py":
+            continue
+        assert "mmaudio_decoder" not in path.read_text(encoding="utf-8"), path
diff --git a/tests/test_mmaudio_sync_model.py b/tests/test_mmaudio_sync_model.py
new file mode 100644
index 00000000..8a80bf2c
--- /dev/null
+++ b/tests/test_mmaudio_sync_model.py
@@ -0,0 +1,188 @@
+"""The vendored Synchformer visual encoder (dw/tasks/mmaudio_sync_model.py)."""
+
+import re
+from pathlib import Path
+
+import pytest
+import torch
+
+from dw.tasks import mmaudio_sync_model as sm
+
+MODULE_PATH = Path(sm.__file__)
+TINY = sm.SyncConfig(
+    image_size=32,
+    patch_size=16,
+    patch_size_temp=2,
+    embed_dim=32,
+    depth=2,
+    num_heads=4,
+    mlp_ratio=2,
+    temporal_resolution=8,
+    segment_frames=16,
+)
+GRID = 2  # patches per side of a tiny frame
+T_OUT = TINY.temporal_resolution
+
+
+@pytest.fixture(scope="module")
+def tiny_model():
+    torch.manual_seed(0)
+    return sm.Synchformer(TINY).eval()
+
+
+# --- shapes ----------------------------------------------------------------------
+
+
+def test_forward_feature_shape(tiny_model):
+    vis = torch.randn(2, 3, 16, 3, 32, 32)
+    with torch.no_grad():
+        out = tiny_model(vis)
+    assert out.shape == (2, 3, 16 // TINY.patch_size_temp, TINY.embed_dim)
+    assert torch.isfinite(out).all()
+    # segments are independent
+    with torch.no_grad():
+        single = tiny_model(vis[:, 1:2])
+    torch.testing.assert_close(out[:, 1:2], single, atol=1e-5, rtol=1e-4)
+
+
+@pytest.mark.parametrize("batch_size", [-1, 1, 2])
+def test_encode_sync_frames_segments(tiny_model, batch_size):
+    frames = torch.randn(2, 32, 3, 32, 32)
+    out = sm.encode_sync_frames(tiny_model, frames, batch_size=batch_size)
+    num_segments = (32 - 16) // 8 + 1
+    assert out.shape == (2, num_segments * T_OUT, TINY.embed_dim)
+    # the first segment's features come first, in order
+    first = tiny_model(frames[:, :16].unsqueeze(1))[:, 0]
+    torch.testing.assert_close(out[:, :T_OUT], first, atol=1e-5, rtol=1e-4)
+    with pytest.raises(ValueError):
+        sm.encode_sync_frames(tiny_model, frames[:, :8])
+    with pytest.raises(ValueError):
+        sm.encode_sync_frames(tiny_model, torch.randn(1, 16, 3, 64, 64))
+
+
+# --- the default configuration and the checkpoint's keys -------------------------
+
+
+def test_default_config_matches_upstream():
+    cfg = sm.SyncConfig()
+    assert (cfg.embed_dim, cfg.depth, cfg.num_heads, cfg.mlp_ratio) == (768, 12, 12, 4)
+    assert (cfg.patch_size, cfg.patch_size_temp, cfg.image_size) == (16, 2, 224)
+    assert (cfg.segment_frames, cfg.temporal_resolution, cfg.in_chans) == (16, 8, 3)
+    assert cfg.qkv_bias is True
+
+
+def _expected_keys(depth):
+    """Upstream's state-dict keys, written out from its attribute names."""
+    keys = {"vfeat_extractor.cls_token", "vfeat_extractor.pos_embed"}
+    keys.add("vfeat_extractor.temp_embed")
+    for name in ("patch_embed", "patch_embed_3d"):
+        keys |= {f"vfeat_extractor.{name}.proj.{p}" for p in ("weight", "bias")}
+    keys |= {f"vfeat_extractor.norm.{p}" for p in ("weight", "bias")}
+    for i in range(depth):
+        b = f"vfeat_extractor.blocks.{i}"
+        for norm in ("norm1", "norm2", "norm3"):
+            keys |= {f"{b}.{norm}.{p}" for p in ("weight", "bias")}
+        for attn in ("attn", "timeattn"):
+            for lin in ("qkv", "proj"):
+                keys |= {f"{b}.{attn}.{lin}.{p}" for p in ("weight", "bias")}
+        for fc in ("fc1", "fc2"):
+            keys |= {f"{b}.mlp.{fc}.{p}" for p in ("weight", "bias")}
+    s = "vfeat_extractor.spatial_attn_agg"
+    keys.add(f"{s}.cls_token")
+    keys |= {f"{s}.self_attn.in_proj_{p}" for p in ("weight", "bias")}
+    keys |= {f"{s}.self_attn.out_proj.{p}" for p in ("weight", "bias")}
+    for name in ("linear1", "linear2", "norm1", "norm2"):
+        keys |= {f"{s}.{name}.{p}" for p in ("weight", "bias")}
+    return keys
+
+
+def test_default_model_state_dict_keys():
+    with torch.device("meta"):
+        model = sm.Synchformer()
+    keys = set(model.state_dict())
+    assert all(k.startswith("vfeat_extractor.") for k in keys)
+    assert keys == _expected_keys(12)
+    sd = model.state_dict()
+    assert sd["vfeat_extractor.patch_embed_3d.proj.weight"].shape == (768, 3, 2, 16, 16)
+    assert sd["vfeat_extractor.patch_embed.proj.weight"].shape == (768, 3, 16, 16)
+    assert sd["vfeat_extractor.blocks.0.attn.qkv.weight"].shape == (2304, 768)
+    assert sd["vfeat_extractor.blocks.0.attn.qkv.bias"].shape == (2304,)
+    assert sd["vfeat_extractor.pos_embed"].shape == (1, 197, 768)
+    assert sd["vfeat_extractor.temp_embed"].shape == (1, 8, 768)
+    assert sd["vfeat_extractor.spatial_attn_agg.linear1.weight"].shape == (3072, 768)
+    # the head, pre-logits and temporal aggregation own no keys
+    assert not any(".head" in k or "pre_logits" in k or "temp_attn" in k for k in keys)
+
+
+# --- loading ---------------------------------------------------------------------
+
+
+def test_load_synchformer_reads_weights_only_and_strictly(
+    tiny_model, tmp_path, monkeypatch
+):
+    state = dict(tiny_model.state_dict())
+    state["afeat_extractor.x"] = torch.zeros(1)
+    path = tmp_path / "sync.pth"
+    torch.save(state, path)
+
+    calls = []
+    real_load = torch.load
+
+    def spy(*args, **kwargs):
+        calls.append(kwargs.get("weights_only"))
+        return real_load(*args, **kwargs)
+
+    monkeypatch.setattr(torch, "load", spy)
+    model = sm.load_synchformer(path, config=TINY)
+    assert calls == [True]
+    assert not model.training
+    assert not any(p.requires_grad for p in model.parameters())
+    for key, value in tiny_model.state_dict().items():
+        torch.testing.assert_close(model.state_dict()[key], value)
+    vis = torch.randn(1, 1, 16, 3, 32, 32)
+    with torch.no_grad():
+        torch.testing.assert_close(model(vis), tiny_model(vis), atol=1e-5, rtol=1e-4)
+
+    # strict: a missing key raises
+    del state["vfeat_extractor.norm.weight"]
+    torch.save(state, path)
+    with pytest.raises(RuntimeError, match="norm.weight"):
+        sm.load_synchformer(path, config=TINY)
+
+
+# --- the module's rules ----------------------------------------------------------
+
+
+def test_module_has_no_hub_io_or_forbidden_imports():
+    source = MODULE_PATH.read_text(encoding="utf-8")
+    for name in (
+        "from_pretrained",
+        "hf_hub_download",
+        "cached_file",
+        "snapshot_download",
+    ):
+        assert name not in source, name
+    forbidden = (
+        r"open_clip|timm|einops|omegaconf|hydra|tensordict|torchdiffeq|torchaudio"
+    )
+    assert not re.search(rf"^\s*(import|from)\s+({forbidden})\b", source, re.M)
+    assert "weights_only=True" in source
+    assert "weights_only=False" not in source
+    assert "save_file" not in source and "torch.save" not in source
+    assert not re.search(r"(?<![.\w])(eval|exec)\(", source)
+    assert "974010a026c731054592d8f777218bd9d85a6c24" in source
+    assert "MIT License" in source and "Vladimir Iashin" in source
+    assert len(source.splitlines()) <= 1100
+
+
+def test_weights_are_pinned():
+    assert sm.REPO_ID == "hkchengrex/MMAudio"
+    assert sm.REVISION == "eb13a1a98fdbec91753775c57b074ccdfc60587c"
+    assert sm.SYNC_FILE == "ext_weights/synchformer_state_dict.pth"
+
+
+def test_module_is_not_imported_by_dw():
+    for path in MODULE_PATH.parents[1].rglob("*.py"):
+        if path != MODULE_PATH:
+            text = path.read_text(encoding="utf-8")
+            assert "mmaudio_sync_model" not in text, path

From a56ce3290a6853741983e7a14bffaf0aa14e528e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 11:56:44 -0600
Subject: [PATCH 105/125] fix(tasks): #1135 - transcribe_audio marks chunks of
 a near-silent clip suspect silent

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                   |  2 +-
 dw/tasks/audio_transcription.py | 16 ++++++++++++++--
 tests/test_transcribe_audio.py  | 21 +++++++++++++++++++++
 3 files changed, 36 insertions(+), 3 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 99fd73c2..20bd4789 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3271,7 +3271,7 @@ Multi-channel audio is downmixed to mono and resampled to 16 kHz before transcri
 
 Set `timestamps` to `"segment"` or `"word"` to get chunk timings instead — a music video cut to the lyric, or a dialogue shot checked against its line, needs the times Whisper already produces past 30 s rather than the collapsed string. The result becomes `{"text": ..., "chunks": [{"start": ..., "end": ..., "text": ...}, ...]}`, so the step's `result.content_type` must be `"application/json"` rather than `"text/plain"`, and it's read with MCP's `get_output_text` (JSON results are text). A clip under 30 s asks Whisper for timestamps explicitly when `timestamps` is set — the 30 s long-form threshold is a separate, unrelated reason to ask. Every `start` and `end` is a number of seconds: a chunk the clip ends inside - a song cut mid-line, which Whisper leaves open-ended - ends at the clip's duration, so the transcript drops straight into [`attribute_voices`](#voice-attribution)' `lines`. `"word"` can give a zero-length chunk (`start` = `end`) on a short or clipped word; `attribute_voices` reads it as a line with no voice.
 
-A chunk that is probably not speech carries one more field, `suspect` (#822), and is never removed. The first reason that holds wins: `"no_words"` when its text has no word at all (`—`, `♪`, `...`); `"repetition"` when it holds a word of a repetition loop (`I'm sorry, I'm sorry, ...`), found by the same detector and `REPEAT_RUN_MIN`/`REPEAT_MAX_PERIOD` [`check_script`](#script-check) discards loops with, however loud; `"silent"` when its loudest window sits at or below the dead-air floor `check_script` discards words at (`GUARD_FLOOR_DBFS`) - Whisper invents text over silence, a fade-out's end credits included; and `"long"` when a `"word"` chunk lasts more than `LONG_WORD_SECONDS` (2 s), an instrumental folded into the word. A `"segment"` chunk is never `long`. A clean input does not prevent the marks: transcribe a song's vocal stem ([`separate_stems`](#stem-separation)) so an instrumental intro is not counted as speech, and the marks catch what Whisper still invents over the stem - its leakage can keep an intro above the floor, which is what `no_words` and `repetition` are for. [`plan_cuts`](#plan_cuts) leaves `no_words`, `repetition` and `silent` chunks out of the lines and warns once per run of marked chunks.
+A chunk that is probably not speech carries one more field, `suspect` (#822), and is never removed. The first reason that holds wins: `"no_words"` when its text has no word at all (`—`, `♪`, `...`); `"repetition"` when it holds a word of a repetition loop (`I'm sorry, I'm sorry, ...`), found by the same detector and `REPEAT_RUN_MIN`/`REPEAT_MAX_PERIOD` [`check_script`](#script-check) discards loops with, however loud; `"silent"` when its loudest window sits at or below the dead-air floor `check_script` discards words at (`GUARD_FLOOR_DBFS`) - Whisper invents text over silence, a fade-out's end credits included; `"silent"` also marks every chunk of a clip whose whole mean level is at or below `NEAR_SILENT_CLIP_DBFS` (-40 dBFS), such as a voiceless vocals stem with residual music (#1135); and `"long"` when a `"word"` chunk lasts more than `LONG_WORD_SECONDS` (2 s), an instrumental folded into the word. A `"segment"` chunk is never `long`. A clean input does not prevent the marks: transcribe a song's vocal stem ([`separate_stems`](#stem-separation)) so an instrumental intro is not counted as speech, and the marks catch what Whisper still invents over the stem - its leakage can keep an intro above the floor, which is what `no_words` and `repetition` are for. [`plan_cuts`](#plan_cuts) leaves `no_words`, `repetition` and `silent` chunks out of the lines and warns once per run of marked chunks.
 
 To compare a take against the lines it was meant to speak, use [`check_script`](#script-check) rather than reading the transcript by eye.
 
diff --git a/dw/tasks/audio_transcription.py b/dw/tasks/audio_transcription.py
index 531acdc4..92af33a7 100644
--- a/dw/tasks/audio_transcription.py
+++ b/dw/tasks/audio_transcription.py
@@ -23,7 +23,7 @@
 from .model_cache import cached_model, hf_pipeline_placement
 from .weights import argument_or_default, repo_entries
 from ..assessment_rules import DEAD_AIR_FLOOR_DBFS
-from ..dsp import loudest_window_dbfs, resample_waveform
+from ..dsp import dbfs, loudest_window_dbfs, resample_waveform, rms
 from ..script_lines import looped_texts, normalize_words
 from .assess import DEAD_AIR_WINDOW
 from .audio_utils import waveform_and_rate
@@ -172,6 +172,13 @@ def load_pipe():
 # instrumental folded into the word, or an invented one (#822)
 LONG_WORD_SECONDS = 2.0
 
+# A clip whose whole-clip mean level is at or below this is near-silent (the
+# audio_qc `NEAR_SILENT_WARN_DBFS` line): speech with its pauses averages far
+# above it, so any text Whisper returns is marked `suspect: "silent"`. This
+# catches a voiceless stem's music bleed, which peaks well over the dead-air
+# floor (#1135)
+NEAR_SILENT_CLIP_DBFS = -40.0
+
 
 def _mark_suspect(chunks, mono, long_word):
     """Chunks with `suspect` set on those that are probably not speech (#822).
@@ -185,10 +192,15 @@ def _mark_suspect(chunks, mono, long_word):
     script_check guards with (`DEAD_AIR_FLOOR_DBFS`, measured by
     `dsp.loudest_window_dbfs`) - Whisper invents text over silence, a
     fade-out's end credits included.
+    "silent" also holds for every chunk when the whole clip's mean level is at
+    or below `NEAR_SILENT_CLIP_DBFS` - a voiceless vocals stem with residual
+    music, which Whisper fills with "Thank you for watching" (#1135).
     "long": a word lasting more than LONG_WORD_SECONDS (`long_word` only,
     since a segment is a line and runs long by nature).
     """
     looped = looped_texts([chunk["text"] for chunk in chunks])
+    clip_level = dbfs(rms(mono))
+    near_silent = clip_level is None or clip_level <= NEAR_SILENT_CLIP_DBFS
     marked = []
     for index, chunk in enumerate(chunks):
         if not chunk["text"]:
@@ -202,7 +214,7 @@ def _mark_suspect(chunks, mono, long_word):
             level = loudest_window_dbfs(
                 mono, _ASR_SAMPLE_RATE, chunk["start"], chunk["end"], DEAD_AIR_WINDOW
             )
-            if level is None or level <= DEAD_AIR_FLOOR_DBFS:
+            if near_silent or level is None or level <= DEAD_AIR_FLOOR_DBFS:
                 reason = "silent"
             elif long_word and chunk["end"] - chunk["start"] > LONG_WORD_SECONDS:
                 reason = "long"
diff --git a/tests/test_transcribe_audio.py b/tests/test_transcribe_audio.py
index 21dc0959..07a8c3ae 100644
--- a/tests/test_transcribe_audio.py
+++ b/tests/test_transcribe_audio.py
@@ -351,6 +351,27 @@ def test_a_word_over_silence_is_marked_silent_not_dropped(self, mock_pipeline):
         self.assertEqual(credits["suspect"], "silent")
         self.assertEqual(credits["text"], "credits")
 
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_a_near_silent_clip_with_bleed_is_marked_silent(self, mock_pipeline):
+        # #1135: a voiceless vocals stem - music bleed peaking at -27 dBFS,
+        # mean about -46 - and Whisper's stock "Thank you for watching"
+        waveform, rate = self._voiced(seconds=5.0)
+        waveform = waveform * 0.0
+        waveform[0, 1000:1800] = 0.045  # a short -27 dBFS burst, mean far lower
+        self._mock_pipe(
+            mock_pipeline,
+            "Thank you very much for watching.",
+            chunks=[
+                {"text": " Thank you very much for watching.", "timestamp": (0.0, 5.0)}
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="segment"
+        )
+
+        self.assertEqual(result["chunks"][0]["suspect"], "silent")
+
     @patch.object(audio_transcription, "hf_pipeline")
     def test_a_voiced_word_over_two_seconds_is_marked_long(self, mock_pipeline):
         waveform, rate = self._voiced(seconds=6.0)

From ebe8d215d909d8b7496950c7d05294188ae9e988 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 12:08:11 -0600
Subject: [PATCH 106/125] feat(skills): enhance voice description guidelines
 for LTX-2.5

---
 plugins/dw/skills/ltx-2.5/SKILL.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index e9a2abc3..d71b279d 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -131,6 +131,20 @@ contradict it, one continuous take, no cuts. The `ltx2/` stored prompts
 put beats in the prompt ("she pauses") or set a duration. On-screen text and
 chaotic physics are unreliable.
 
+**Voice**: the caption steers a speaker's pitch and apparent age and gender, not
+their delivery. Measured 2026-11-01 on mps (one image, seed and line, four voice
+descriptions, 121 frames): median F0 291 Hz for "squeaky little girl", 221 for
+"elderly woman", 136 for "deep booming old man" - an octave apart - but "a
+breathy whisper" came back fully voiced at 160 Hz, and "fast" and "slow" spoke
+over the same span: the clip length paces the line, not the words. Delivery
+adjectives alone ("buzzy", "cheerful") land as a generic voice. Write voices as
+pitch, age and gender; don't promise a whisper or a tempo (an accent is
+unmeasured: listen before claiming one); describe
+a voice you have not heard as asked for, not as delivered. When the voice must
+be exact or held across clips, speak the line with `templates/voice-clone`
+(Audio8-TTS, runs on mps) - that loses LTX's lip sync over the picture - or
+condition MiniMax H3 on the clip as its voice reference (`minimax-h3` skill).
+
 **Several shots**: one chronological paragraph, no shot list or sluglines. At
 each cut name the transition in prose ("a hard cut to"), re-establish scale,
 angle and lighting, reuse the same identifiers for recurring subjects, and

From b4fd85abe5136f25e8aec57e645fad08745d472a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 12:21:39 -0600
Subject: [PATCH 107/125] fix(tasks): #1136 - transcribe_audio marks Whisper's
 stock outro lines suspect stock_phrase

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                   |  2 +-
 dw/script_lines.py              |  2 +-
 dw/tasks/audio_transcription.py | 30 +++++++++++++++++++++++++-
 tests/test_transcribe_audio.py  | 38 +++++++++++++++++++++++++++++++++
 4 files changed, 69 insertions(+), 3 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 20bd4789..4f69727d 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3271,7 +3271,7 @@ Multi-channel audio is downmixed to mono and resampled to 16 kHz before transcri
 
 Set `timestamps` to `"segment"` or `"word"` to get chunk timings instead — a music video cut to the lyric, or a dialogue shot checked against its line, needs the times Whisper already produces past 30 s rather than the collapsed string. The result becomes `{"text": ..., "chunks": [{"start": ..., "end": ..., "text": ...}, ...]}`, so the step's `result.content_type` must be `"application/json"` rather than `"text/plain"`, and it's read with MCP's `get_output_text` (JSON results are text). A clip under 30 s asks Whisper for timestamps explicitly when `timestamps` is set — the 30 s long-form threshold is a separate, unrelated reason to ask. Every `start` and `end` is a number of seconds: a chunk the clip ends inside - a song cut mid-line, which Whisper leaves open-ended - ends at the clip's duration, so the transcript drops straight into [`attribute_voices`](#voice-attribution)' `lines`. `"word"` can give a zero-length chunk (`start` = `end`) on a short or clipped word; `attribute_voices` reads it as a line with no voice.
 
-A chunk that is probably not speech carries one more field, `suspect` (#822), and is never removed. The first reason that holds wins: `"no_words"` when its text has no word at all (`—`, `♪`, `...`); `"repetition"` when it holds a word of a repetition loop (`I'm sorry, I'm sorry, ...`), found by the same detector and `REPEAT_RUN_MIN`/`REPEAT_MAX_PERIOD` [`check_script`](#script-check) discards loops with, however loud; `"silent"` when its loudest window sits at or below the dead-air floor `check_script` discards words at (`GUARD_FLOOR_DBFS`) - Whisper invents text over silence, a fade-out's end credits included; `"silent"` also marks every chunk of a clip whose whole mean level is at or below `NEAR_SILENT_CLIP_DBFS` (-40 dBFS), such as a voiceless vocals stem with residual music (#1135); and `"long"` when a `"word"` chunk lasts more than `LONG_WORD_SECONDS` (2 s), an instrumental folded into the word. A `"segment"` chunk is never `long`. A clean input does not prevent the marks: transcribe a song's vocal stem ([`separate_stems`](#stem-separation)) so an instrumental intro is not counted as speech, and the marks catch what Whisper still invents over the stem - its leakage can keep an intro above the floor, which is what `no_words` and `repetition` are for. [`plan_cuts`](#plan_cuts) leaves `no_words`, `repetition` and `silent` chunks out of the lines and warns once per run of marked chunks.
+A chunk that is probably not speech carries one more field, `suspect` (#822), and is never removed. The first reason that holds wins: `"no_words"` when its text has no word at all (`—`, `♪`, `...`); `"repetition"` when it holds a word of a repetition loop (`I'm sorry, I'm sorry, ...`), found by the same detector and `REPEAT_RUN_MIN`/`REPEAT_MAX_PERIOD` [`check_script`](#script-check) discards loops with, however loud; `"stock_phrase"` when its whole text is one of Whisper's stock outro lines ("Thank you for watching", "Please subscribe"), which it writes over music at any level (#1136); `"silent"` when its loudest window sits at or below the dead-air floor `check_script` discards words at (`GUARD_FLOOR_DBFS`) - Whisper invents text over silence, a fade-out's end credits included; `"silent"` also marks every chunk of a clip whose whole mean level is at or below `NEAR_SILENT_CLIP_DBFS` (-40 dBFS), such as a voiceless vocals stem with residual music (#1135); and `"long"` when a `"word"` chunk lasts more than `LONG_WORD_SECONDS` (2 s), an instrumental folded into the word. A `"segment"` chunk is never `long`. A clean input does not prevent the marks: transcribe a song's vocal stem ([`separate_stems`](#stem-separation)) so an instrumental intro is not counted as speech, and the marks catch what Whisper still invents over the stem - its leakage can keep an intro above the floor, which is what `no_words` and `repetition` are for. [`plan_cuts`](#plan_cuts) leaves `no_words`, `repetition`, `stock_phrase` and `silent` chunks out of the lines and warns once per run of marked chunks.
 
 To compare a take against the lines it was meant to speak, use [`check_script`](#script-check) rather than reading the transcript by eye.
 
diff --git a/dw/script_lines.py b/dw/script_lines.py
index 5a5d12f5..d177feb8 100644
--- a/dw/script_lines.py
+++ b/dw/script_lines.py
@@ -118,7 +118,7 @@ def looped_texts_firsts(texts):
 # transcribe_audio's `suspect` reasons whose chunk plan_cuts leaves out of the
 # sung lines: no word, a repetition loop, no voice under it. A "long" word is
 # real lyric, only mistimed, so it stays
-SUSPECT_LEFT_OUT = ("no_words", "repetition", "silent")
+SUSPECT_LEFT_OUT = ("no_words", "repetition", "stock_phrase", "silent")
 
 
 def suspect_runs(chunks):
diff --git a/dw/tasks/audio_transcription.py b/dw/tasks/audio_transcription.py
index 92af33a7..e7a01b69 100644
--- a/dw/tasks/audio_transcription.py
+++ b/dw/tasks/audio_transcription.py
@@ -96,7 +96,7 @@ def transcribe_audio(audio, device="cpu", sample_rate=None, **kwargs):
                 content_type must then be "application/json" rather than
                 "text/plain", since the return shape follows the argument.
                 A chunk that is probably invented carries a `suspect` reason
-                ("no_words", "repetition", "silent" or "long"), marked and
+                ("no_words", "repetition", "stock_phrase", "silent" or "long"), marked and
                 never dropped (#822).
 
     Returns:
@@ -180,6 +180,29 @@ def load_pipe():
 NEAR_SILENT_CLIP_DBFS = -40.0
 
 
+# Whisper's stock outro lines, learned from YouTube captions: what it writes
+# over music or a fade at any level (#1136). A chunk is marked only when its
+# whole text is one of these, so a longer line that merely contains the words
+# is left alone
+_STOCK_PHRASES = frozenset(
+    " ".join(normalize_words(phrase))
+    for phrase in (
+        "Thank you for watching",
+        "Thank you very much for watching",
+        "Thanks for watching",
+        "Thank you so much for watching",
+        "Thank you for watching this video",
+        "Thanks for watching this video",
+        "Please subscribe",
+        "Please subscribe to my channel",
+        "Subscribe to my channel",
+        "Don't forget to subscribe",
+        "See you in the next video",
+        "See you next time",
+    )
+)
+
+
 def _mark_suspect(chunks, mono, long_word):
     """Chunks with `suspect` set on those that are probably not speech (#822).
 
@@ -195,6 +218,9 @@ def _mark_suspect(chunks, mono, long_word):
     "silent" also holds for every chunk when the whole clip's mean level is at
     or below `NEAR_SILENT_CLIP_DBFS` - a voiceless vocals stem with residual
     music, which Whisper fills with "Thank you for watching" (#1135).
+    "stock_phrase": the whole text is one of Whisper's stock outro lines
+    ('Thank you for watching'), which it writes over music at any level
+    (#1136); tried after "silent", which wins for a quiet clip.
     "long": a word lasting more than LONG_WORD_SECONDS (`long_word` only,
     since a segment is a line and runs long by nature).
     """
@@ -216,6 +242,8 @@ def _mark_suspect(chunks, mono, long_word):
             )
             if near_silent or level is None or level <= DEAD_AIR_FLOOR_DBFS:
                 reason = "silent"
+            elif " ".join(normalize_words(chunk["text"])) in _STOCK_PHRASES:
+                reason = "stock_phrase"
             elif long_word and chunk["end"] - chunk["start"] > LONG_WORD_SECONDS:
                 reason = "long"
             else:
diff --git a/tests/test_transcribe_audio.py b/tests/test_transcribe_audio.py
index 07a8c3ae..c474989d 100644
--- a/tests/test_transcribe_audio.py
+++ b/tests/test_transcribe_audio.py
@@ -372,6 +372,44 @@ def test_a_near_silent_clip_with_bleed_is_marked_silent(self, mock_pipeline):
 
         self.assertEqual(result["chunks"][0]["suspect"], "silent")
 
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_a_stock_outro_over_a_loud_clip_is_marked_stock_phrase(self, mock_pipeline):
+        # #1136: music at a normal level, Whisper's stock outro
+        waveform, rate = self._voiced(seconds=5.0)
+        self._mock_pipe(
+            mock_pipeline,
+            "Thank you very much for watching.",
+            chunks=[
+                {"text": " Thank you very much for watching.", "timestamp": (0.0, 5.0)},
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="segment"
+        )
+
+        self.assertEqual(result["chunks"][0]["suspect"], "stock_phrase")
+
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_a_line_containing_a_stock_phrase_is_not_marked(self, mock_pipeline):
+        waveform, rate = self._voiced(seconds=5.0)
+        self._mock_pipe(
+            mock_pipeline,
+            "He said thank you for watching me.",
+            chunks=[
+                {
+                    "text": " He said thank you for watching me.",
+                    "timestamp": (0.0, 5.0),
+                },
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="segment"
+        )
+
+        self.assertNotIn("suspect", result["chunks"][0])
+
     @patch.object(audio_transcription, "hf_pipeline")
     def test_a_voiced_word_over_two_seconds_is_marked_long(self, mock_pipeline):
         waveform, rate = self._voiced(seconds=6.0)

From b14e244f8543dc6f863a02d3c2bf9920da0f4e88 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 12:22:06 -0600
Subject: [PATCH 108/125] docs(tasks): #1136 - plan_cuts docstring names
 stock_phrase

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/cuts.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/dw/tasks/cuts.py b/dw/tasks/cuts.py
index a361f290..ea26eb5f 100644
--- a/dw/tasks/cuts.py
+++ b/dw/tasks/cuts.py
@@ -1032,7 +1032,7 @@ def plan_cuts(
         transcript: transcribe_audio's result with 'timestamps' set - a
             {text, chunks} dict of {start, end, text} chunks in seconds. A
             null 'end' runs to the next chunk's start, or the song's end. A
-            chunk marked `suspect` no_words, repetition or silent is left
+            chunk marked `suspect` no_words, repetition, stock_phrase or silent is left
             out of the lines; every suspect run is warned about. Or
             analyze_phrases' result, {phrases: [{start, end}],
             duration_seconds}, told by its 'phrases' key (#1095): timing

From 28ef460faf4a75399f0a787b650ea7fe2ffd6aa9 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 12:48:46 -0600
Subject: [PATCH 109/125] feat(tasks): #1105 - phrase advice: floor_db for
 fused legato lines, disproportion warning

Plan v3 (#1095, Q4 = a): the fewer-phrases mismatch warning also names
raising analyze_phrases' floor_db, with a check-by-ear caution; a one-to-one
pairing warns when a phrase is under 1/4 or over 4x the median; the 90%
warning names both remedies (vocal stem on a mix, floor_db on a stem).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                                 | 12 ++--
 dw/tasks/cuts.py                              | 61 +++++++++++++++++--
 dw/tasks/phrases.py                           | 20 ++++--
 .../dw/skills/minimax-h3/references/cuts.md   |  7 ++-
 tests/test_analyze_phrases.py                 |  6 +-
 tests/test_plan_cuts_phrases.py               | 55 +++++++++++++++++
 workflows/templates/minimax/README.md         |  2 +-
 7 files changed, 143 insertions(+), 20 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index 4f69727d..dbf95a53 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -2072,7 +2072,7 @@ the result is JSON and nothing is built:
 | `audio` | Yes | The song or its vocal stem: a path, `asset:`/`output:` reference of an audio or video file, a waveform, or an earlier step's generated audio (`previous_result:<separate_stems step>.vocals`) |
 | `min_gap_seconds` | No | A silence shorter than this between voiced runs is bridged into one phrase (default `0.35`). Raise it to merge phrases split by breaths, lower it to split lines sung close together. At least 0 |
 | `min_phrase_seconds` | No | A phrase shorter than this, after bridging, is dropped as a click or breath (default `0.3`). Above 0 |
-| `floor_db` | No | The level, in dBFS of a 20 ms frame, a frame must reach to count as voiced. Unset, it is the track's 95th-percentile frame less 35 dB, never below -60 dBFS (the floor `attribute_voices` uses). At or below 0 |
+| `floor_db` | No | The level, in dBFS of a 20 ms frame, a frame must reach to count as voiced. Unset, it is the track's 95th-percentile frame less 35 dB, never below -60 dBFS (the floor `attribute_voices` uses). It is the knob for a fused legato or reverberant verse: when the voice never drops below the relative floor between lines, raising it (less negative, e.g. `-30`) splits them where `min_gap_seconds` can't - then check the phrases by ear before trusting a one-to-one pairing: a raised floor can make the counts match on wrong boundaries. At or below 0 |
 | `centre` | No | `true` (the default) weights a stereo file to its centre, where a lead vocal is mixed; `false` uses the band energy of the downmix. A real boolean - `"false"` is refused |
 | `sample_rate` | With a waveform | Rate of a directly passed waveform (files carry their own) |
 
@@ -2094,9 +2094,11 @@ are bridged, then runs shorter than `min_phrase_seconds` are dropped.
 
 Warnings: no phrases found (a silent track, or one whose loudest frame is
 under -50 dBFS in the voice band - room tone, hiss - unless `floor_db` is
-given); and one phrase covering more than 90% of the track, which is usually
-a dense mix whose centred bass and kick fill the voice band: feed it
-`separate_stems`' `vocals` instead. `warnings` repeats what was emitted.
+given); and one phrase covering more than 90% of the track. The task can't tell
+a stem from a mix, so it names both remedies: on a mix whose centred bass and
+kick fill the voice band, feed it `separate_stems`' `vocals` instead; on a
+vocal stem already (legato or reverberant singing), raise `floor_db` and check
+the phrases by ear. `warnings` repeats what was emitted.
 
 Refused at `validate_workflow`: a missing `audio`, a negative
 `min_gap_seconds`, a `min_phrase_seconds` at or below 0, a `floor_db` above 0,
@@ -2135,7 +2137,7 @@ the list rendered. A transcript chunk `transcribe_audio` marked `suspect` `no_wo
 
 | Argument | Required | Description |
 | -------- | -------- | ----------- |
-| `transcript` | Yes | `transcribe_audio`'s result with `timestamps` set (`"segment"` or `"word"`): a `{text, chunks}` dict of `{start, end, text}` chunks in seconds. A null `end` runs to the next chunk's start, or the song's end. Its `result` must be `application/json`. Or an [`analyze_phrases`](#analyze_phrases) result (recognised by its `phrases` key), for a song Whisper can't time: each phrase is one line, and suspect filtering and word alignment don't apply. Without `lyrics` a phrase is a line with no lyric (shot `lyric: null`, kind vocal), and `segment_by` `line`, `stanza` (phrases a silence of at least `min_gap_seconds` apart are grouped) and `beat` all work. With `lyrics` of as many lines as phrases they map one to one, in order. With a different count a warning names both counts and the knob: raise `analyze_phrases`' `min_gap_seconds` when there are more phrases than lyric lines (it bridges more pauses), lower it when fewer; the lines are then spread evenly from the first phrase's start to the last phrase's end, never paired silently. A long phrase split into pieces gives every piece its whole lyric |
+| `transcript` | Yes | `transcribe_audio`'s result with `timestamps` set (`"segment"` or `"word"`): a `{text, chunks}` dict of `{start, end, text}` chunks in seconds. A null `end` runs to the next chunk's start, or the song's end. Its `result` must be `application/json`. Or an [`analyze_phrases`](#analyze_phrases) result (recognised by its `phrases` key), for a song Whisper can't time: each phrase is one line, and suspect filtering and word alignment don't apply. Without `lyrics` a phrase is a line with no lyric (shot `lyric: null`, kind vocal), and `segment_by` `line`, `stanza` (phrases a silence of at least `min_gap_seconds` apart are grouped) and `beat` all work. With `lyrics` of as many lines as phrases they map one to one, in order; a warning names any line whose phrase is under 1/4 or over 4x the median phrase length, since its boundaries may be wrong (the pairing stands - check it by ear). With a different count a warning names both counts and the knob: raise `analyze_phrases`' `min_gap_seconds` when there are more phrases than lyric lines (it bridges more pauses), lower it when fewer, or, for fused legato or reverberant lines, raise its `floor_db` (e.g. `-30`) and check the phrases by ear before trusting the pairing; the lines are then spread evenly from the first phrase's start to the last phrase's end, never paired silently. A long phrase split into pieces gives every piece its whole lyric |
 | `lyrics` | No | The song's own lyrics, one line per line with a blank line or a lone section tag (`[Chorus]`) between stanzas, or a list of lines. The shots carry these lines verbatim and in order; the transcript only times them (an `analyze_phrases` transcript: one line per phrase, see `transcript`). `null` or `""` means none: the transcript's text is used (a phrase result has none: `lyric` is `null`) |
 | `beats` | For `segment_by: "beat"` | `analyze_beats`' result, or a list of beat times in seconds |
 | `segment_by` | No | `line` (default), `stanza` or `beat` |
diff --git a/dw/tasks/cuts.py b/dw/tasks/cuts.py
index ea26eb5f..9d584c50 100644
--- a/dw/tasks/cuts.py
+++ b/dw/tasks/cuts.py
@@ -428,14 +428,22 @@ def _phrase_lines(phrases, lyrics, duration, stanza_gap, warnings):
             lines.append(dict(phrase, stanza=stanza, tokens=None))
         return lines
     if len(lyrics) == len(phrases):
-        return [
+        paired = [
             dict(phrase, text=text, stanza=stanza, tokens=None)
             for phrase, (text, stanza) in zip(phrases, lyrics)
         ]
+        _disproportion_warning(paired, warnings)
+        return paired
     if len(phrases) > len(lyrics):
         knob = "raise analyze_phrases' 'min_gap_seconds' to bridge more pauses"
     else:
-        knob = "lower analyze_phrases' 'min_gap_seconds' to split at shorter pauses"
+        knob = (
+            "lower analyze_phrases' 'min_gap_seconds' to split at shorter "
+            "pauses, or, for legato or reverberant singing whose lines fuse, "
+            "raise its 'floor_db' (less negative, e.g. -30) - then check the "
+            "phrases by ear before trusting a one-to-one pairing, since a "
+            "raised floor can match the counts on wrong boundaries"
+        )
     low = phrases[0]["start"] if phrases else 0.0
     high = phrases[-1]["end"] if phrases else duration
     warnings.append(
@@ -457,6 +465,45 @@ def _phrase_lines(phrases, lyrics, duration, stanza_gap, warnings):
     ]
 
 
+# A paired phrase this far from the median phrase length is likely a bad
+# boundary (#1095): on a fused legato verse, a raised floor_db can split a
+# breath off as a "phrase" and leave another line spanning two.
+DISPROPORTION = 4.0
+
+
+def _disproportion_warning(paired, warnings):
+    """Warn when a lyric line is paired one to one with a phrase under a
+    quarter, or over four times, the median phrase duration. The pairing
+    stands; the warning is advice to check the boundaries by ear."""
+    lengths = sorted(line["end"] - line["start"] for line in paired)
+    if len(lengths) < 2:
+        return
+    middle = len(lengths) // 2
+    median = (
+        lengths[middle]
+        if len(lengths) % 2
+        else (lengths[middle - 1] + lengths[middle]) / 2
+    )
+    if median <= 0:
+        return
+    odd = [
+        f"line {index + 1} ({line['text']!r}, {line['end'] - line['start']:.2f} s)"
+        for index, line in enumerate(paired)
+        if not median / DISPROPORTION
+        <= line["end"] - line["start"]
+        <= median * DISPROPORTION
+    ]
+    if odd:
+        warnings.append(
+            f"{COMMAND}: the lyric lines are paired one to one with "
+            f"analyze_phrases' phrases, but {', '.join(odd)} "
+            f"{'sits' if len(odd) == 1 else 'sit'} on a phrase "
+            f"under 1/{DISPROPORTION:g} or over {DISPROPORTION:g}x the median "
+            f"phrase ({median:.2f} s) - the phrase boundaries may be wrong; "
+            "check them by ear"
+        )
+
+
 def _units(lines, segment_by):
     """The vocal spans scenes are cut around: a line each, or a stanza."""
     units = []
@@ -1038,10 +1085,12 @@ def plan_cuts(
             duration_seconds}, told by its 'phrases' key (#1095): timing
             with no text. Without lyrics each phrase is a line with no
             lyric; with lyrics as many lines as phrases, line n is phrase n,
-            and otherwise the counts are warned about (naming which way to
-            move analyze_phrases' min_gap_seconds) and the lines spread
-            evenly from the first phrase to the last. A phrase is never
-            suspect, and a split piece of one keeps its whole lyric
+            warned about when a phrase is under 1/4 or over 4x the median
+            (check it by ear), and otherwise the counts are warned about
+            (naming which way to move analyze_phrases' min_gap_seconds, and
+            with fewer phrases its floor_db) and the lines spread evenly
+            from the first phrase to the last. A phrase is never suspect,
+            and a split piece of one keeps its whole lyric
         lyrics: The song's own lyrics - one line per line, a blank line or a
             lone section tag ("[Chorus]") between stanzas - or a list of
             lines. The shots carry these lines verbatim and in order; the
diff --git a/dw/tasks/phrases.py b/dw/tasks/phrases.py
index 3bed922f..9d934cb1 100644
--- a/dw/tasks/phrases.py
+++ b/dw/tasks/phrases.py
@@ -47,7 +47,8 @@
 # room tone or hiss that a relative floor would still call voiced. A given
 # `floor_db` is the caller's own floor, and skips this
 NEAR_SILENT_DBFS = -50.0
-# One phrase covering more than this share of the track is a dense mix, fused
+# One phrase covering more than this share of the track is fused: a dense mix,
+# or legato or reverberant singing on a stem (#1095 field case)
 ONE_PHRASE_SHARE = 0.9
 # Seconds as reported
 TIME_PLACES = 2
@@ -139,7 +140,8 @@ def analyze_phrases(
         audio: The song or its vocal stem - a file, a generated audio result
             (`previous_result:<separate_stems step>.vocals`), or a video
             carrying a soundtrack. A vocal stem gives the cleanest phrases;
-            a dense mix can fuse into one
+            a dense mix can fuse into one, and so can legato or
+            reverberant singing (raise floor_db)
         min_gap_seconds: A silence shorter than this between two voiced runs
             is bridged, so they are one phrase. Raise it to merge phrases
             split by breaths, lower it to split lines sung close together
@@ -147,7 +149,10 @@ def analyze_phrases(
             dropped as a click or breath
         floor_db: The level, in dBFS of a 20 ms frame, a frame must reach to
             count as voiced. Unset, it is the track's 95th-percentile frame
-            less 35 dB, never below -60 dBFS
+            less 35 dB, never below -60 dBFS. Raise it (less negative, e.g.
+            -30) when legato or reverberant lines fuse into one phrase, then
+            check the phrases by ear: a raised floor can split on wrong
+            boundaries
         centre: Weight a stereo file to its centre, where a lead vocal is
             mixed, cancelling what is panned to the sides. False uses the
             band energy of the downmix
@@ -243,9 +248,12 @@ def analyze_phrases(
     ):
         warnings.append(
             f"{COMMAND}: one phrase covers more than {ONE_PHRASE_SHARE:.0%} of "
-            "the track - probably a dense mix whose instruments fill the voice "
-            "band. Feed it the vocal stem (separate_stems, then "
-            "previous_result:<step>.vocals)"
+            "the track. On a mix, its instruments probably fill the voice band: "
+            "feed it the vocal stem (separate_stems, then "
+            "previous_result:<step>.vocals). On a vocal stem already, legato or "
+            "reverberant singing never drops below the floor between lines: "
+            "raise 'floor_db' (less negative, e.g. -30) and check the phrases "
+            "by ear"
         )
 
     for message in warnings:
diff --git a/plugins/dw/skills/minimax-h3/references/cuts.md b/plugins/dw/skills/minimax-h3/references/cuts.md
index 108628a5..258f6dd8 100644
--- a/plugins/dw/skills/minimax-h3/references/cuts.md
+++ b/plugins/dw/skills/minimax-h3/references/cuts.md
@@ -46,7 +46,12 @@ all work. With as many lyric lines as phrases they map one to one, in order.
 With a different count it warns with both counts and spreads the lines evenly
 from the first phrase's start to the last's end, never pairing silently: raise
 `analyze_phrases`' `min_gap_seconds` when there are more phrases than lines,
-lower it when fewer. Suspect filtering and word alignment don't apply; a long
+lower it when fewer. A legato or reverberant verse (a choir) can fuse its lines
+into one phrase no `min_gap_seconds` splits: `floor_db` is the knob there
+(less negative, e.g. `-30`), but listen to the phrases before trusting a
+one-to-one pairing - a raised floor can match the counts on wrong boundaries,
+and `plan_cuts` warns when a paired phrase is under 1/4 or over 4x the median
+length. Suspect filtering and word alignment don't apply; a long
 phrase split into pieces gives every piece its whole lyric. The song length
 falls back to the phrase result's `duration_seconds`.
 
diff --git a/tests/test_analyze_phrases.py b/tests/test_analyze_phrases.py
index 84e03f71..3e53b088 100644
--- a/tests/test_analyze_phrases.py
+++ b/tests/test_analyze_phrases.py
@@ -102,7 +102,11 @@ def test_a_dense_track_is_one_phrase_with_a_warning(self):
         wave = noise()
         result = run(numpy.stack([wave, wave]))
         assert len(result["phrases"]) == 1
-        assert any("stems" in w and "90%" in w for w in result["warnings"])
+        (warning,) = [w for w in result["warnings"] if "90%" in w]
+        # Both remedies (#1095 v3): a mix wants the vocal stem, a stem
+        # whose legato lines fuse wants a raised floor_db, checked by ear
+        assert "separate_stems" in warning and ".vocals" in warning
+        assert "'floor_db'" in warning and "by ear" in warning
 
 
 class TestSilence:
diff --git a/tests/test_plan_cuts_phrases.py b/tests/test_plan_cuts_phrases.py
index ce066da0..71f63829 100644
--- a/tests/test_plan_cuts_phrases.py
+++ b/tests/test_plan_cuts_phrases.py
@@ -135,6 +135,25 @@ def test_fewer_phrases_than_lines_says_lower(self):
         (warning,) = self.mismatch(result)
         assert "6 line(s)" in warning and "4 phrase(s)" in warning
         assert "lower analyze_phrases' 'min_gap_seconds'" in warning
+        # Fused legato lines: the floor is the knob that moves the count
+        assert "raise its 'floor_db'" in warning
+        assert "by ear" in warning
+
+    def test_more_phrases_than_lines_does_not_name_floor_db(self):
+        (warning,) = self.mismatch(plan(lyrics="\n".join(LINES[:3])))
+        assert "floor_db" not in warning
+
+    def test_the_field_verse_shape_warns_with_both_knobs(self):
+        # verse_s7.wav at the defaults: one fused phrase, four lines
+        fused = dict(
+            PHRASES, phrases=[{"start": 1.44, "end": 33.0}], duration_seconds=34.0
+        )
+        result = plan(transcript=fused, lyrics="\n".join(LINES))
+        (warning,) = self.mismatch(result)
+        assert "4 line(s)" in warning and "1 phrase(s)" in warning
+        assert "1.44-33.00 s" in warning
+        assert "'min_gap_seconds'" in warning and "'floor_db'" in warning
+        assert [s["lyric"] for s in vocal(result) if s["lyric"]] == LINES
 
     def test_the_lines_spread_evenly_from_first_phrase_to_last(self):
         result = plan(lyrics="\n".join(LINES[:2]), include_instrumental_gaps=False)
@@ -191,3 +210,39 @@ def test_analyze_phrases_result_plans_with_lyrics():
     for shot, (start, _) in zip(shots, bursts):
         assert shot["start_frame"] == pytest.approx(start * FPS, abs=0.05 * FPS + 1)
     assert not any("spread evenly" in w for w in result["warnings"])
+
+
+class TestDisproportion:
+    """Matched counts on phrases far out of proportion (#1095 v3)."""
+
+    def disproportion(self, result):
+        return [w for w in result["warnings"] if "median" in w]
+
+    def test_proportionate_phrases_give_no_warning(self):
+        assert self.disproportion(plan(lyrics=LYRICS)) == []
+
+    def test_the_field_verse_at_floor_db_minus_30_names_the_short_line(self):
+        spans = [(2.66, 5.12), (7.26, 15.58), (16.02, 16.36), (18.40, 33.00)]
+        odd = dict(
+            PHRASES,
+            phrases=[{"start": a, "end": b} for a, b in spans],
+            duration_seconds=34.0,
+        )
+        result = plan(transcript=odd, lyrics=LYRICS)
+        (warning,) = self.disproportion(result)
+        assert "line 3" in warning and "Sing it out loud" in warning
+        assert "0.34 s" in warning and "by ear" in warning
+        for other in ("line 1", "line 2", "line 4"):
+            assert other not in warning
+        # The pairing still stands: advice only
+        assert [s["lyric"] for s in vocal(result)] == LINES
+        assert [s["start_frame"] for s in vocal(result)][1:] == [
+            round(a * FPS) for a, _ in spans[1:]
+        ]
+
+    def test_an_over_long_phrase_is_named(self):
+        spans = [(1.0, 3.0), (3.5, 5.5), (6.0, 8.0), (9.0, 27.0)]
+        odd = dict(PHRASES, phrases=[{"start": a, "end": b} for a, b in spans])
+        (warning,) = self.disproportion(plan(transcript=odd, lyrics=LYRICS))
+        assert "line 4" in warning and "Never let go" in warning
+        assert "line 1" not in warning
diff --git a/workflows/templates/minimax/README.md b/workflows/templates/minimax/README.md
index 79785e2c..ff023d91 100644
--- a/workflows/templates/minimax/README.md
+++ b/workflows/templates/minimax/README.md
@@ -202,7 +202,7 @@ same clip as an audio reference in each shot, as
 }
 ```
 
-Lyric lines map onto phrases one to one when the counts match. When they differ, `plan_cuts` warns with both counts and spreads the lines evenly across the phrases: raise `analyze_phrases`' `min_gap_seconds` when there are more phrases than lines, lower it when fewer. The template's default chain is unchanged (Whisper first).
+Lyric lines map onto phrases one to one when the counts match. When they differ, `plan_cuts` warns with both counts and spreads the lines evenly across the phrases: raise `analyze_phrases`' `min_gap_seconds` when there are more phrases than lines, lower it when fewer. A legato or reverberant verse can fuse its lines into one phrase that no `min_gap_seconds` splits; there `floor_db` is the knob (less negative, e.g. `-30`), but check the phrases by ear before trusting a one-to-one pairing: a raised floor can make the counts match on wrong boundaries. With matched counts, `plan_cuts` also warns when a paired phrase is under 1/4 or over 4x the median length. The template's default chain is unchanged (Whisper first).
 
 ## Field notes from a 24-shot musical
 

From 8818ebaefe7d49ec8f90765f34a3ad79ee8f9371 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 12:56:54 -0600
Subject: [PATCH 110/125] refactor(tasks): #1105 - disproportion warning uses
 statistics.median

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/tasks/cuts.py | 10 +++-------
 1 file changed, 3 insertions(+), 7 deletions(-)

diff --git a/dw/tasks/cuts.py b/dw/tasks/cuts.py
index 9d584c50..275e9408 100644
--- a/dw/tasks/cuts.py
+++ b/dw/tasks/cuts.py
@@ -33,6 +33,7 @@
 import logging
 import math
 import re
+import statistics
 
 from ..script_lines import SUSPECT_LEFT_OUT, suspect_runs
 from ..variable_constraints import aligned, aligned_down
@@ -475,15 +476,10 @@ def _disproportion_warning(paired, warnings):
     """Warn when a lyric line is paired one to one with a phrase under a
     quarter, or over four times, the median phrase duration. The pairing
     stands; the warning is advice to check the boundaries by ear."""
-    lengths = sorted(line["end"] - line["start"] for line in paired)
+    lengths = [line["end"] - line["start"] for line in paired]
     if len(lengths) < 2:
         return
-    middle = len(lengths) // 2
-    median = (
-        lengths[middle]
-        if len(lengths) % 2
-        else (lengths[middle - 1] + lengths[middle]) / 2
-    )
+    median = statistics.median(lengths)
     if median <= 0:
         return
     odd = [

From 12a2b36036bf6ba6ea5c0f9c4031e875696bec0f Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 13:04:33 -0600
Subject: [PATCH 111/125] fix(tasks): #1137 - plan_cuts mismatch warning: 'so
 the counts match' before the floor_db caution

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/cuts.py | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/dw/tasks/cuts.py b/dw/tasks/cuts.py
index 275e9408..9c21f2e9 100644
--- a/dw/tasks/cuts.py
+++ b/dw/tasks/cuts.py
@@ -436,13 +436,13 @@ def _phrase_lines(phrases, lyrics, duration, stanza_gap, warnings):
         _disproportion_warning(paired, warnings)
         return paired
     if len(phrases) > len(lyrics):
-        knob = "raise analyze_phrases' 'min_gap_seconds' to bridge more pauses"
+        knob = "raise analyze_phrases' 'min_gap_seconds' to bridge more pauses, so the counts match"
     else:
         knob = (
             "lower analyze_phrases' 'min_gap_seconds' to split at shorter "
             "pauses, or, for legato or reverberant singing whose lines fuse, "
-            "raise its 'floor_db' (less negative, e.g. -30) - then check the "
-            "phrases by ear before trusting a one-to-one pairing, since a "
+            "raise its 'floor_db' (less negative, e.g. -30), so the counts match - then "
+            "check the phrases by ear before trusting a one-to-one pairing, since a "
             "raised floor can match the counts on wrong boundaries"
         )
     low = phrases[0]["start"] if phrases else 0.0
@@ -450,8 +450,7 @@ def _phrase_lines(phrases, lyrics, duration, stanza_gap, warnings):
     warnings.append(
         f"{COMMAND}: the lyrics have {len(lyrics)} line(s) and analyze_phrases "
         f"found {len(phrases)} phrase(s) - the lines are spread evenly over "
-        f"{low:.2f}-{high:.2f} s, not paired with the phrases; {knob}, so the "
-        "counts match"
+        f"{low:.2f}-{high:.2f} s, not paired with the phrases; {knob}"
     )
     step = (high - low) / len(lyrics)
     return [

From cbe3453f5801f5e07a3accef1ca369547dc98fd1 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 13:41:37 -0600
Subject: [PATCH 112/125] feat(docs): #1127 - L4 Klein probes

Twelve Klein stills (3 prompts x caps/lower x 2 seeds), each with its job
id. L4 is not reproduced on Klein either. The deviations record the
text-encoder offload and the old snapshot that had nothing left to delete.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-11-story-forge-lessons.md     | 59 +++++++++++++++----
 1 file changed, 48 insertions(+), 11 deletions(-)

diff --git a/docs/proposals/audits/2026-11-story-forge-lessons.md b/docs/proposals/audits/2026-11-story-forge-lessons.md
index 1ade727a..25071912 100644
--- a/docs/proposals/audits/2026-11-story-forge-lessons.md
+++ b/docs/proposals/audits/2026-11-story-forge-lessons.md
@@ -43,7 +43,7 @@ any legible text.
 | L1 | LTX-2.5 renders haze over after 2–3.5 s; keep clips short (89 frames). | **not reproduced (on our pipeline at this N)** | 0 of 10 (6 t2v at 241, 2 i2v at 241, 2 i2v at 401) | 8 of 8 at 89 frames, but there was nothing to remove |
 | L2 | i2v invents camera moves unless the prompt pins the camera; "camera remains static" alone is not enough, add "locked-off on a tripod, no pan, no zoom". | **not reproduced (on our pipeline at this N)** | 0 of 6 clear moves; 2 of 6 ambiguous (S3, see below) | 6 of 6 "static", 6 of 6 "locked-off" show no move |
 | L3 | Bodies in contact (hugs, handshakes, a hand on a shoulder) fuse or grow limbs; stage the moment just before contact. | **not reproduced (on our pipeline at this N)** | LTX 2 of 6 (both handshakes, mild); H3 0 of 2 (1 brief ambiguous) | 6 of 6 clean, but 0 of 6 followed the restaging: every remedy render went on into contact |
-| L4 | An ALL-CAPS word in an image prompt renders as written text; write it in lowercase. | **not reproduced (on our pipeline at this N)** | 0 of 6 (z-image only; Klein not run) | 6 of 6, but there was nothing to remove |
+| L4 | An ALL-CAPS word in an image prompt renders as written text; write it in lowercase. | **not reproduced (on our pipeline at this N)** | 0 of 6 z-image, 0 of 6 Klein | 12 of 12, but there was nothing to remove |
 | L6 | Impacts (a strike, a slam) break physics; show the effort, not the impact. | **not reproduced (on our pipeline at this N)** | 1 of 4 (axe seed 1); both door renders never showed the slam | 3 of 4 clean, 1 ambiguous (door seed 2 closes softly) |
 
 L1's two questions:
@@ -184,8 +184,14 @@ Prompts `probe-1123/l4-{proud,alone,hurry}-{caps,lower}`: a baker holding a
 tray of croissants, "PROUD"/"proud" of them; a man alone in the rain at night,
 "ALONE"/"alone"; a girl in a yellow raincoat running to a red door in a
 "HURRY"/"hurry". The caps and lowercase prompts differ only in that one word's
-case. Stills from `models/z-image` at its defaults (960x544), each judged on its whole image (`get_output_image`), which is the "frame inspected". Klein was not
-run (see Deviations).
+case. Each still is judged on its whole image (`get_output_image`), which is
+the "frame inspected". There are two families:
+- `models/z-image` at its defaults (960x544);
+- Klein (`black-forest-labs/flux-3-image-klein`, 1024x1024, 16 steps), run as
+  `templates/flux3/text-to-image` with one change, the text encoder's
+  placement (see Deviations).
+
+### z-image
 
 | Cell | Arm | Seed 1 | Seed 2 | Verdict | Observation |
 | --- | --- | --- | --- | --- | --- |
@@ -200,8 +206,27 @@ Tally: the caps word appears as legible text in 0 of 6 caps renders and 0 of
 6 lowercase ones, so the plan's "holds" test (at least half of the caps
 renders, none of the lowercase) fails. Not reproduced on z-image. The case of
 the word changed nearly nothing: each caps/lowercase pair at the same seed is
-close to the same picture. Whether Klein, the family the lesson was written
-against, behaves differently is untested here.
+close to the same picture.
+
+### Klein
+
+Stage B's second session ran these after Don's `spend` ruling on #1127. Each
+note reads `#1127 L4 cell klein-<word>-<caps|lower> seed <s>`.
+
+| Cell | Arm | Seed 1 | Seed 2 | Verdict | Observation |
+| --- | --- | --- | --- | --- | --- |
+| proud | naive (caps) | 747a40ecd26e | 8dc1157be57f | no text | Grinning baker holding a tray of croissants in a sunlit bakery. No lettering on the apron, tray, shelves or wall. |
+| proud | remedy (lower) | 37721ee6bee7 | 708bec1cc91a | no text | The same scene, with more croissants on the tray. No lettering. |
+| alone | naive (caps) | 887c4be1f269 | baac48e8fcc8 | no text | Man in a wet coat, head bowed, alone on a rainy crosswalk at night. Shop fascias are blurred. One small illegible sign at the left edge (seed 2), not "ALONE". |
+| alone | remedy (lower) | 408a20fe4a00 | 62422200260e | no text | The same scene. Fascias are illegible and "alone" appears nowhere. |
+| hurry | naive (caps) | 946866bee92e | 3faf33a3c088 | no text | Girl in a yellow raincoat and boots running up a cobbled lane to a red door. No lettering on the door, wall or coat. |
+| hurry | remedy (lower) | 898397bfb410 | 640ee4d1af35 | no text | The same scene against a brick wall. No lettering. |
+
+Tally: the caps word appears as legible text in 0 of 6 Klein caps renders
+and 0 of 6 lowercase ones, so the "holds" test fails on Klein as well. **L4
+is not reproduced on either family (on our pipeline at this N).** As on
+z-image, each caps/lowercase pair at the same seed is close to the same
+picture. On Klein, the case of the word changes nothing visible.
 
 ## Deviations from plan v2
 
@@ -211,8 +236,9 @@ against, behaves differently is untested here.
 - **The i2v 121-frame control is borrowed** from L2 s1-static (same still,
   static prompt, 121 frames) rather than run as a separate L1 cell; its note
   names the L2 cell.
-- **Stills from z-image, not Klein.** The Klein route needed a 40 GB model
-  download; `models/z-image` was already on lem.
+- **Stills from z-image first, Klein later.** The Klein route needed a
+  40 GB model download, and `models/z-image` was already on lem. The Klein
+  cells followed once Don ruled the download in (#1127).
 - **Asset names are flat** (`probe-1123-s1-bench.jpg`), not in a folder.
 - **The L1 prompts all say "the camera remains static"**, to keep camera
   motion out of the haze read.
@@ -227,10 +253,21 @@ Stage B (#1127):
 - **The H3 cell has no remedy arm**: one `hug` shot of 124 frames per seed,
   with the template's own drawn portraits. The shot prompt was written inline
   in the shots item; the same text is stored as `probe-1123/l3-h3-hug`.
-- **L4 rests on z-image only.** The Klein half (`templates/flux3/text-to-image`)
-  was not run: Klein is not on lem, and the download is 40.3 GB, a `spend`
-  decision this stage does not hold. The L4 verdict therefore says nothing
-  about Klein.
+- **The Klein L4 cells ran as an inline copy of
+  `templates/flux3/text-to-image`.** Model, size, steps, dtype and seed
+  handling are unchanged. The one difference is that the text encoder is
+  leaf-level group-offloaded (`"group_offload": {"offload_type":
+  "leaf_level"}`), not placed on `cuda`. As written, the template OOMs while
+  loading on an empty 24 GB 3090 against the current `main` (job
+  49459dc14c17), whatever its description says about "about 19 GB". The
+  modular pipeline also has no `offload: "model"` (job 5ec3b2dcb9f5). Neither
+  failed job counts as a probe. With the offload, the text encode takes about
+  8–12 min per still, against about 9 s of denoise.
+- **No old Klein snapshot to delete.** Don's ruling asked for the older,
+  unreferenced 31.8 GB snapshot to be removed. It turned out to be the
+  partial download of the same `main` revision, and the finished download
+  completed it in place, so there was nothing separate to remove. Disk free
+  on lem afterwards was about 262 GB.
 - **The remedy restagings were not followed by LTX** in L3 (0 of 6) and only
   partly in L6 (the door seed 2 closed). The tables record what rendered, not
   what was asked.

From c2496b7eba42672967016d95168e1b89f6fdb857 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 13:58:44 -0600
Subject: [PATCH 113/125] fix(tasks): #1136 - stock_phrase also marks word-mode
 chunks of a stock sentence

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 dw/tasks/audio_transcription.py | 30 ++++++++++++++++++++++--
 tests/test_transcribe_audio.py  | 41 +++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+), 2 deletions(-)

diff --git a/dw/tasks/audio_transcription.py b/dw/tasks/audio_transcription.py
index e7a01b69..120aafa6 100644
--- a/dw/tasks/audio_transcription.py
+++ b/dw/tasks/audio_transcription.py
@@ -203,6 +203,26 @@ def load_pipe():
 )
 
 
+def _stock_sentence_indices(chunks):
+    """Indices of word chunks whose whole sentence is a stock phrase (#1136).
+
+    In word mode a chunk is one word, so the phrase only shows across a run:
+    the words are split into sentences at a word ending in . ! or ?, and every
+    word of a sentence that is exactly a stock phrase is returned.
+    """
+    found = set()
+    sentence = []
+    for index, chunk in enumerate(chunks):
+        sentence.append(index)
+        text = chunk["text"]
+        if index == len(chunks) - 1 or text.rstrip().endswith((".", "!", "?")):
+            words = [w for i in sentence for w in normalize_words(chunks[i]["text"])]
+            if " ".join(words) in _STOCK_PHRASES:
+                found.update(sentence)
+            sentence = []
+    return found
+
+
 def _mark_suspect(chunks, mono, long_word):
     """Chunks with `suspect` set on those that are probably not speech (#822).
 
@@ -220,13 +240,16 @@ def _mark_suspect(chunks, mono, long_word):
     music, which Whisper fills with "Thank you for watching" (#1135).
     "stock_phrase": the whole text is one of Whisper's stock outro lines
     ('Thank you for watching'), which it writes over music at any level
-    (#1136); tried after "silent", which wins for a quiet clip.
+    (#1136); tried after "silent", which wins for a quiet clip. In word mode
+    every word of a sentence that is exactly such a line carries it, and it
+    wins over "long".
     "long": a word lasting more than LONG_WORD_SECONDS (`long_word` only,
     since a segment is a line and runs long by nature).
     """
     looped = looped_texts([chunk["text"] for chunk in chunks])
     clip_level = dbfs(rms(mono))
     near_silent = clip_level is None or clip_level <= NEAR_SILENT_CLIP_DBFS
+    stock_words = _stock_sentence_indices(chunks) if long_word else set()
     marked = []
     for index, chunk in enumerate(chunks):
         if not chunk["text"]:
@@ -242,7 +265,10 @@ def _mark_suspect(chunks, mono, long_word):
             )
             if near_silent or level is None or level <= DEAD_AIR_FLOOR_DBFS:
                 reason = "silent"
-            elif " ".join(normalize_words(chunk["text"])) in _STOCK_PHRASES:
+            elif (
+                index in stock_words
+                or " ".join(normalize_words(chunk["text"])) in _STOCK_PHRASES
+            ):
                 reason = "stock_phrase"
             elif long_word and chunk["end"] - chunk["start"] > LONG_WORD_SECONDS:
                 reason = "long"
diff --git a/tests/test_transcribe_audio.py b/tests/test_transcribe_audio.py
index c474989d..18161e72 100644
--- a/tests/test_transcribe_audio.py
+++ b/tests/test_transcribe_audio.py
@@ -390,6 +390,47 @@ def test_a_stock_outro_over_a_loud_clip_is_marked_stock_phrase(self, mock_pipeli
 
         self.assertEqual(result["chunks"][0]["suspect"], "stock_phrase")
 
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_word_mode_stock_outro_marks_every_word(self, mock_pipeline):
+        # #1136: a word chunk is one word; the sentence is the phrase
+        waveform, rate = self._voiced(seconds=5.0)
+        words = ["Thank", "you", "very", "much", "for", "watching."]
+        self._mock_pipe(
+            mock_pipeline,
+            " ".join(words),
+            chunks=[
+                {"text": f" {w}", "timestamp": (i * 0.8, i * 0.8 + 0.8)}
+                for i, w in enumerate(words)
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="word"
+        )
+
+        self.assertEqual(
+            [c.get("suspect") for c in result["chunks"]], ["stock_phrase"] * 6
+        )
+
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_word_mode_line_containing_stock_phrase_is_not_marked(self, mock_pipeline):
+        waveform, rate = self._voiced(seconds=5.0)
+        words = ["He", "said", "thank", "you", "for", "watching", "me."]
+        self._mock_pipe(
+            mock_pipeline,
+            " ".join(words),
+            chunks=[
+                {"text": f" {w}", "timestamp": (i * 0.8, i * 0.8 + 0.8)}
+                for i, w in enumerate(words)
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="word"
+        )
+
+        self.assertTrue(all("suspect" not in c for c in result["chunks"]))
+
     @patch.object(audio_transcription, "hf_pipeline")
     def test_a_line_containing_a_stock_phrase_is_not_marked(self, mock_pipeline):
         waveform, rate = self._voiced(seconds=5.0)

From e98b083666b831f34e503212ef4d189dc769ec65 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:03:36 -0600
Subject: [PATCH 114/125] feat(plugin): #1128 - land story-forge lesson 5 as
 framing guidance

Stages A and B ruled lessons 1, 2, 3, 4 and 6 not reproduced on dw's
pipeline, so per plan v2 only lesson 5 lands, unmeasured and worded as
guidance: script-to-video step 3 and series-episodes step 0, citing the
findings doc. The findings doc records lesson 5 as unprobed and what
landed. Pins: the guidance phrase in both casting steps, and no rule for
a lesson not reproduced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../audits/2026-11-story-forge-lessons.md     | 16 +++++++
 plugins/dw/skills/script-to-video/SKILL.md    |  5 +++
 plugins/dw/skills/series-episodes/SKILL.md    |  3 ++
 tests/test_plugin_skills.py                   | 44 +++++++++++++++++++
 4 files changed, 68 insertions(+)

diff --git a/docs/proposals/audits/2026-11-story-forge-lessons.md b/docs/proposals/audits/2026-11-story-forge-lessons.md
index 25071912..1c1fdad2 100644
--- a/docs/proposals/audits/2026-11-story-forge-lessons.md
+++ b/docs/proposals/audits/2026-11-story-forge-lessons.md
@@ -294,3 +294,19 @@ Stage B (#1127):
 - The clipping and quiet-audio warnings on L6 jobs are irrelevant: the probes
   judge the picture only. `dialogue-short` warns that `audio_bleed_ms` has no
   effect with one shot, which is expected.
+
+## Lesson 5: wide shots drift hardest on identity (not probed)
+
+Story-forge's lesson: a character small in a wide shot drifts most on
+identity, so frame recurring characters larger, or keep both a wide and a
+close master. Plan v2 lands it unmeasured, as framing guidance (Don's Q4,
+2026-11-01). Nothing here measures it on dw, so the skills word it as
+guidance, not as a rule.
+
+## What landed (#1123 stage C, #1128)
+
+Only lesson 5, as guidance: `script-to-video` step 3 and `series-episodes`
+step 0. Lessons 1, 2, 3, 4 and 6 are not reproduced above, so no skill
+states a rule for any of them: no `ltx-2.5/references/staging.md`, no H3
+staging note, no all-caps rule in `flux3-klein`, and no follow-up issue for
+the `image-to-video` 401-frame default (L1 did not hold at 401 frames).
diff --git a/plugins/dw/skills/script-to-video/SKILL.md b/plugins/dw/skills/script-to-video/SKILL.md
index b3f1c9fb..c06caa36 100644
--- a/plugins/dw/skills/script-to-video/SKILL.md
+++ b/plugins/dw/skills/script-to-video/SKILL.md
@@ -60,6 +60,11 @@ let the family template draw its own portrait. This is the step that goes
 missing silently - nothing validates "the same character looks the same"
 across separately generated shots, so it has to be deliberate.
 
+Framing guidance, not a measured rule (story-forge's lesson 5, unprobed
+on dw: `docs/proposals/audits/2026-11-story-forge-lessons.md`): a face
+small in a wide shot drifts most, so frame a recurring character large,
+and if the piece needs wides, keep a wide master too.
+
 Large `run_workflow` arguments: `save_prompt(name, {"text": ...})` each shot prompt under a
 script-prefixed name (the library is shared across workspaces) and pass
 `prompt:<script>/<shot>` references in the list; they resolve in nested
diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 7c3b68c5..619b30f0 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -57,6 +57,9 @@ generates cleanly, and the drift only shows up when two episodes are
 watched back to back. There is no engine check for "the same character
 looks the same" across separate runs; the fixed-asset reference is the only
 guard, so it has to be a deliberate, first step rather than an implicit one.
+As guidance, not a measured rule (`script-to-video` step 3;
+`docs/proposals/audits/2026-11-story-forge-lessons.md`): frame a recurring
+character large, and if the piece needs wides, keep a wide master too.
 
 Save each portrait prompt with `save_prompt` under one folder for the series
 and reference it as `prompt:<series>/<character>` from every episode.
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 6f9a2fdc..2067b1c9 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -1161,3 +1161,47 @@ def test_a_video_skill_maps_its_failure_modes_to_the_tool_that_shows_them(path):
     judge = text[text.index("## Run and judge") :]
     assert "`seams=true`" in judge
     assert "`at`" in judge
+
+
+STORY_FORGE_FINDINGS = "docs/proposals/audits/2026-11-story-forge-lessons.md"
+
+
+class TestStoryForgeLessons:
+    """Story-forge's production lessons (#1123): only what held on dw's
+    pipeline lands as a rule. The probes ruled lessons 1-4 and 6 not
+    reproduced, so no skill states them; lesson 5 lands unmeasured, worded
+    as guidance and citing the findings doc."""
+
+    def test_the_findings_doc_rules_what_landed(self):
+        text = open(
+            os.path.join(REPO_ROOT, STORY_FORGE_FINDINGS), encoding="utf-8"
+        ).read()
+        assert "## Lesson 5" in text and "(not probed)" in text
+        assert "## What landed" in text
+
+    @pytest.mark.parametrize(
+        "path", [SCRIPT_SKILL, SERIES_SKILL], ids=["script-to-video", "series-episodes"]
+    )
+    def test_lesson_5_is_framing_guidance_citing_the_findings(self, path):
+        body = " ".join(skill_body(path).split())
+        assert "not a measured rule" in body
+        assert "frame a recurring character large" in body
+        assert "keep a wide master too" in body
+        assert STORY_FORGE_FINDINGS in body
+
+    def test_lesson_5_sits_in_the_casting_steps(self):
+        script = skill_body(SCRIPT_SKILL)
+        step3 = script[script.index("## 3.") : script.index("## 4.")]
+        assert "frame a recurring character large" in " ".join(step3.split())
+        series = skill_body(SERIES_SKILL)
+        step0 = series[series.index("## 0.") : series.index("## 1-5.")]
+        assert "frame a recurring character large" in " ".join(step0.split())
+
+    def test_no_rule_lands_for_a_lesson_not_reproduced(self):
+        ltx_dir = os.path.dirname(LTX_SKILL)
+        assert not os.path.exists(os.path.join(ltx_dir, "references", "staging.md"))
+        for path in (LTX_SKILL, H3_SKILL, FLUX3_SKILL, SCRIPT_SKILL, SERIES_SKILL):
+            text = skill_text(path).lower()
+            assert "locked-off on a tripod" not in text  # L2's remedy wording
+            assert "all-caps" not in text and "all caps" not in text  # L4
+            assert "just before contact" not in text  # L3

From eafa8fff11e1c025108416b8592ea3eedf523d52 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:12:14 -0600
Subject: [PATCH 115/125] fix(tasks): #1138 - transcribe_audio marks 5-6 word
 loops and duplicate overlapping chunks repetition

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 docs/TASKS.md                   |  4 +--
 dw/script_lines.py              |  2 +-
 dw/tasks/audio_transcription.py | 23 ++++++++++++++---
 tests/test_transcribe_audio.py  | 44 +++++++++++++++++++++++++++++++++
 4 files changed, 66 insertions(+), 7 deletions(-)

diff --git a/docs/TASKS.md b/docs/TASKS.md
index dbf95a53..7c639f26 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3273,7 +3273,7 @@ Multi-channel audio is downmixed to mono and resampled to 16 kHz before transcri
 
 Set `timestamps` to `"segment"` or `"word"` to get chunk timings instead — a music video cut to the lyric, or a dialogue shot checked against its line, needs the times Whisper already produces past 30 s rather than the collapsed string. The result becomes `{"text": ..., "chunks": [{"start": ..., "end": ..., "text": ...}, ...]}`, so the step's `result.content_type` must be `"application/json"` rather than `"text/plain"`, and it's read with MCP's `get_output_text` (JSON results are text). A clip under 30 s asks Whisper for timestamps explicitly when `timestamps` is set — the 30 s long-form threshold is a separate, unrelated reason to ask. Every `start` and `end` is a number of seconds: a chunk the clip ends inside - a song cut mid-line, which Whisper leaves open-ended - ends at the clip's duration, so the transcript drops straight into [`attribute_voices`](#voice-attribution)' `lines`. `"word"` can give a zero-length chunk (`start` = `end`) on a short or clipped word; `attribute_voices` reads it as a line with no voice.
 
-A chunk that is probably not speech carries one more field, `suspect` (#822), and is never removed. The first reason that holds wins: `"no_words"` when its text has no word at all (`—`, `♪`, `...`); `"repetition"` when it holds a word of a repetition loop (`I'm sorry, I'm sorry, ...`), found by the same detector and `REPEAT_RUN_MIN`/`REPEAT_MAX_PERIOD` [`check_script`](#script-check) discards loops with, however loud; `"stock_phrase"` when its whole text is one of Whisper's stock outro lines ("Thank you for watching", "Please subscribe"), which it writes over music at any level (#1136); `"silent"` when its loudest window sits at or below the dead-air floor `check_script` discards words at (`GUARD_FLOOR_DBFS`) - Whisper invents text over silence, a fade-out's end credits included; `"silent"` also marks every chunk of a clip whose whole mean level is at or below `NEAR_SILENT_CLIP_DBFS` (-40 dBFS), such as a voiceless vocals stem with residual music (#1135); and `"long"` when a `"word"` chunk lasts more than `LONG_WORD_SECONDS` (2 s), an instrumental folded into the word. A `"segment"` chunk is never `long`. A clean input does not prevent the marks: transcribe a song's vocal stem ([`separate_stems`](#stem-separation)) so an instrumental intro is not counted as speech, and the marks catch what Whisper still invents over the stem - its leakage can keep an intro above the floor, which is what `no_words` and `repetition` are for. [`plan_cuts`](#plan_cuts) leaves `no_words`, `repetition`, `stock_phrase` and `silent` chunks out of the lines and warns once per run of marked chunks.
+A chunk that is probably not speech carries one more field, `suspect` (#822), and is never removed. The first reason that holds wins: `"no_words"` when its text has no word at all (`—`, `♪`, `...`); `"repetition"` when it holds a word of a repetition loop (`I'm sorry, I'm sorry, ...`), found by the same detector and `REPEAT_RUN_MIN`/`REPEAT_MAX_PERIOD` [`check_script`](#script-check) discards loops with, however loud, and also a chunk whose text and overlapping span repeat an earlier chunk's (Whisper's duplicate decodes of one loop, #1138); `"stock_phrase"` when its whole text is one of Whisper's stock outro lines ("Thank you for watching", "Please subscribe"), which it writes over music at any level (#1136); `"silent"` when its loudest window sits at or below the dead-air floor `check_script` discards words at (`GUARD_FLOOR_DBFS`) - Whisper invents text over silence, a fade-out's end credits included; `"silent"` also marks every chunk of a clip whose whole mean level is at or below `NEAR_SILENT_CLIP_DBFS` (-40 dBFS), such as a voiceless vocals stem with residual music (#1135); and `"long"` when a `"word"` chunk lasts more than `LONG_WORD_SECONDS` (2 s), an instrumental folded into the word. A `"segment"` chunk is never `long`. A clean input does not prevent the marks: transcribe a song's vocal stem ([`separate_stems`](#stem-separation)) so an instrumental intro is not counted as speech, and the marks catch what Whisper still invents over the stem - its leakage can keep an intro above the floor, which is what `no_words` and `repetition` are for. [`plan_cuts`](#plan_cuts) leaves `no_words`, `repetition`, `stock_phrase` and `silent` chunks out of the lines and warns once per run of marked chunks.
 
 To compare a take against the lines it was meant to speak, use [`check_script`](#script-check) rather than reading the transcript by eye.
 
@@ -3339,7 +3339,7 @@ The thresholds are module constants in `dw/tasks/script_check.py` (the guard's `
 | `CLIP_TAIL_SECONDS` | 0.25 s | The final stretch of the file a line's last word must end in to be `line_clipped_at_end` |
 | `CLIP_TAIL_BELOW_WORD_DB` | 15 dB | A tail more than this far under the last word's loudest window is not the word still sounding (a bed under a finished line), so not `line_clipped_at_end` |
 | `REPEAT_RUN_MIN` | 6 | Heard words repeating the same unit this many times over, back to back, are a repetition loop: every chunk holding one is discarded (`reason: "repetition"`), however loud |
-| `REPEAT_MAX_PERIOD` | 4 words | The longest repeating unit a loop is looked for in - `pre pre pre` has period 1, `thank you thank you` period 2 |
+| `REPEAT_MAX_PERIOD` | 6 words | The longest repeating unit a loop is looked for in - `pre pre pre` has period 1, `thank you thank you` period 2 |
 
 The result: `findings`, `lines[]` (`expected`, `heard`, `similarity`, `start`, `end`, `shot`; with the shot known, `start` and `end` are kept inside it, and the ASR's own times, when they fall outside - a word stretched across the seam over speech Whisper dropped - are kept as `asr_start` / `asr_end`, #1115), `discarded[]` (`text`, `start`, `end`, `level_dbfs`, `reason` - `below_floor`, `repeated_span` (a chunk repeating the previous one's exact span) or `repetition`, `count` - a repetition loop is one entry spanning its chunks), `unmatched[]` (heard words aligned to no line), `transcript`, `model_name`, `rules_applied`, `rules_skipped[]` (`rule`, `reason`, and `line` for a per-line skip) and `thresholds`. A line's `shot` is the shot it names, else the shot its heard words overlap most (null when none is known). `shots` is the map as placed - `[{name, start, end}]` in seconds on the take, or null when none is known - and `shots_source` says where it came from: `argument`, `artifact`, `manifest` or `none`.
 
diff --git a/dw/script_lines.py b/dw/script_lines.py
index d177feb8..c2dd2b09 100644
--- a/dw/script_lines.py
+++ b/dw/script_lines.py
@@ -52,7 +52,7 @@ def normalize_words(text):
 # repeats a word a few times; it does not loop. check_script discards such
 # words and transcribe_audio marks them `suspect: "repetition"` (#822)
 REPEAT_RUN_MIN = 6
-REPEAT_MAX_PERIOD = 4
+REPEAT_MAX_PERIOD = 6
 
 
 def repetition_runs(keys):
diff --git a/dw/tasks/audio_transcription.py b/dw/tasks/audio_transcription.py
index e7a01b69..25b81761 100644
--- a/dw/tasks/audio_transcription.py
+++ b/dw/tasks/audio_transcription.py
@@ -203,6 +203,19 @@ def load_pipe():
 )
 
 
+def _repeats_earlier(chunks, index):
+    """True when an earlier chunk has this chunk's text over an overlapping span
+    - Whisper decoding one stretch of audio again (#1138)."""
+    chunk = chunks[index]
+    words = normalize_words(chunk["text"])
+    return any(
+        normalize_words(other["text"]) == words
+        and other["start"] < chunk["end"]
+        and chunk["start"] < other["end"]
+        for other in chunks[:index]
+    )
+
+
 def _mark_suspect(chunks, mono, long_word):
     """Chunks with `suspect` set on those that are probably not speech (#822).
 
@@ -210,7 +223,9 @@ def _mark_suspect(chunks, mono, long_word):
     "no_words": the text has no word at all ('—', '♪', '...').
     "repetition": a word of a repetition loop ('I'm sorry, I'm sorry, ...'),
     found by `script_lines.looped_texts`, the detector check_script discards
-    loops with - Whisper's hallucination over music or a fade, however loud.
+    loops with - Whisper's hallucination over music or a fade, however loud;
+    also a chunk repeating an earlier chunk's text over an overlapping span
+    (the same stretch decoded again, #1138).
     "silent": the chunk's loudest window sits at or below the dead-air floor
     script_check guards with (`DEAD_AIR_FLOOR_DBFS`, measured by
     `dsp.loudest_window_dbfs`) - Whisper invents text over silence, a
@@ -234,7 +249,7 @@ def _mark_suspect(chunks, mono, long_word):
             continue
         if not normalize_words(chunk["text"]):
             reason = "no_words"
-        elif index in looped:
+        elif index in looped or _repeats_earlier(chunks, index):
             reason = "repetition"
         else:
             level = loudest_window_dbfs(
@@ -359,8 +374,8 @@ def _with_resumed_tail(pipe, samples, result, options):
     ends = _chunk_ends(raw_chunks)
     if ends and speech_end - max(ends) > _TAIL_GAP_SECONDS:
         emit_warning(
-            f"transcribe_audio: transcript ends at {max(ends):.1f} s but audible "
-            f"speech continues to {speech_end:.1f} s; the last line(s) may be "
+            f"transcribe_audio: transcript ends at {max(ends):.1f} s but audio "
+            f"activity continues to {speech_end:.1f} s; the last line(s) may be "
             "missing from the text"
         )
     return {**result, "text": " ".join(texts), "chunks": raw_chunks}
diff --git a/tests/test_transcribe_audio.py b/tests/test_transcribe_audio.py
index c474989d..06ccaf9c 100644
--- a/tests/test_transcribe_audio.py
+++ b/tests/test_transcribe_audio.py
@@ -390,6 +390,50 @@ def test_a_stock_outro_over_a_loud_clip_is_marked_stock_phrase(self, mock_pipeli
 
         self.assertEqual(result["chunks"][0]["suspect"], "stock_phrase")
 
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_a_five_word_loop_and_its_duplicate_chunks_are_marked_repetition(
+        self, mock_pipeline
+    ):
+        # #1138: "I love you so much" x N, decoded again over the same span
+        waveform, rate = self._voiced(seconds=8.0)
+        loop = "I love you so much, " * 20 + "See you in the next video."
+        self._mock_pipe(
+            mock_pipeline,
+            loop,
+            chunks=[
+                {"text": loop, "timestamp": (0.0, 7.0)},
+                {"text": loop, "timestamp": (0.08, 7.08)},
+                {"text": "A different line.", "timestamp": (7.1, 7.9)},
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="segment"
+        )
+
+        self.assertEqual(result["chunks"][0]["suspect"], "repetition")
+        self.assertEqual(result["chunks"][1]["suspect"], "repetition")
+
+    @patch.object(audio_transcription, "hf_pipeline")
+    def test_a_repeat_of_an_earlier_line_over_another_span_is_not_marked(
+        self, mock_pipeline
+    ):
+        waveform, rate = self._voiced(seconds=6.0)
+        self._mock_pipe(
+            mock_pipeline,
+            "Hello there. Hello there.",
+            chunks=[
+                {"text": "Hello there.", "timestamp": (0.0, 2.0)},
+                {"text": "Hello there.", "timestamp": (3.0, 5.0)},
+            ],
+        )
+
+        result = transcribe_audio(
+            waveform, device="cpu", sample_rate=rate, timestamps="segment"
+        )
+
+        self.assertNotIn("suspect", result["chunks"][1])
+
     @patch.object(audio_transcription, "hf_pipeline")
     def test_a_line_containing_a_stock_phrase_is_not_marked(self, mock_pipeline):
         waveform, rate = self._voiced(seconds=5.0)

From 4f56e22ab3dbd89f06e537872833777813007c9a Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:15:23 -0600
Subject: [PATCH 116/125] feat(tasks): #1133 - generate_sound_effects task
 (MMAudio) and its registration

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/arguments.py            |   5 +-
 dw/server/catalog_shape.py |   1 +
 dw/tasks/model_handlers.py |  49 ++++
 dw/tasks/sound_effects.py  | 455 +++++++++++++++++++++++++++++++++++++
 4 files changed, 509 insertions(+), 1 deletion(-)
 create mode 100644 dw/tasks/sound_effects.py

diff --git a/dw/arguments.py b/dw/arguments.py
index 50815678..c08f2f2c 100644
--- a/dw/arguments.py
+++ b/dw/arguments.py
@@ -914,7 +914,9 @@ def resolve_relative_path(path, base_dir):
 # frame list first dropped the soundtrack they measure and failed every probe
 # on an asset:/output: video (#387) - and window_video, which cuts the
 # source's soundtrack with its frames and so reads the file with its audio
-# (#601) - and trim_video, which cuts a soundtrack the same way (#627) - see _realize_lazy_frame_arguments
+# (#601) - and trim_video, which cuts a soundtrack the same way (#627) - and
+# generate_sound_effects, which samples the file at its own rates (#1133) - see
+# _realize_lazy_frame_arguments
 _LAZY_FRAME_COMMANDS = frozenset(
     {
         "get_frame",
@@ -925,6 +927,7 @@ def resolve_relative_path(path, base_dir):
         "analyze_sync_drift",
         "window_video",
         "trim_video",
+        "generate_sound_effects",
     }
 )
 
diff --git a/dw/server/catalog_shape.py b/dw/server/catalog_shape.py
index 7511da82..ec2d648f 100644
--- a/dw/server/catalog_shape.py
+++ b/dw/server/catalog_shape.py
@@ -46,6 +46,7 @@
         "image_to_text",
         "diffusion_upscale",
         "interpolate_frames",
+        "generate_sound_effects",
     }
 )
 SUMMARY_LIMIT = 120
diff --git a/dw/tasks/model_handlers.py b/dw/tasks/model_handlers.py
index a2dab332..69dd985b 100644
--- a/dw/tasks/model_handlers.py
+++ b/dw/tasks/model_handlers.py
@@ -404,3 +404,52 @@ def _handle_speech_generation(task, arguments, previous_pipelines):
         seed=task.seed_for(arguments),
         **arguments,
     )
+
+
+@register_command(
+    "generate_sound_effects",
+    implementation="dw.tasks.sound_effects.generate_sound_effects",
+    consumes_device=True,
+    required_weights="dw.tasks.sound_effects.required_weights",
+    summary=(
+        "Sound effects (MMAudio large 44.1 kHz v2) for a video clip, a text "
+        "prompt, or both, as a 44.1 kHz mono track; pair_audio muxes it back "
+        "under the clip. Video-only is the weaker mode: give a prompt naming "
+        "the on-screen sound sources. Licences: the MMAudio weights are "
+        "CC-BY-NC 4.0 (non-commercial); the DFN5B CLIP encoder is under the "
+        "Apple Machine Learning Research Model License (research only) - "
+        "Apple Machine Learning Research Model is licensed under the Apple "
+        "Machine Learning Research Model License Agreement. Its output runs "
+        "7-25 dB hot: route it through match_levels before mixing."
+    ),
+    parameter_descriptions={
+        "video": (
+            "The clip to score - asset:, output:, a path, or an earlier step's "
+            "video. Optional when 'prompt' is given."
+        ),
+        "prompt": (
+            "What should be heard - name the on-screen sound sources "
+            "('footsteps on gravel, a door slams'). Optional when 'video' is "
+            "given, but recommended: video-only is the weaker mode."
+        ),
+        "negative_prompt": "What should not be heard (e.g. 'music, speech').",
+        "duration": (
+            "Seconds of audio, at most 20 and at most the clip's length "
+            "(default: the clip's whole length, or 8 s text-only). The model "
+            "was trained around 8 s; outside 4-12 s a warning is noted."
+        ),
+        "steps": "Euler flow-matching steps (default 25).",
+        "guidance_scale": "Classifier-free guidance strength (default 4.5).",
+    },
+    domains={"duration": POSITIVE, "steps": POSITIVE, "guidance_scale": POSITIVE},
+    whole_numbers=("steps",),
+)
+def _handle_generate_sound_effects(task, arguments, previous_pipelines):
+    """MMAudio sound effects for a clip and/or a prompt"""
+    from .sound_effects import generate_sound_effects
+
+    return generate_sound_effects(
+        device=task.device_for(arguments),
+        seed=task.seed_for(arguments),
+        **arguments,
+    )
diff --git a/dw/tasks/sound_effects.py b/dw/tasks/sound_effects.py
new file mode 100644
index 00000000..7c729f8d
--- /dev/null
+++ b/dw/tasks/sound_effects.py
@@ -0,0 +1,455 @@
+"""
+generate_sound_effects - MMAudio (large 44.1 kHz v2) sound effects for a clip,
+a prompt, or both (#1124 stage D).
+
+The pieces are stages A-C's: the flow network (`mmaudio_model`), the DFN5B
+CLIP towers (`mmaudio_clip`), the Synchformer encoder (`mmaudio_sync_model`)
+and the VAE + BigVGAN decoder read from Kandinsky 6's `audio_vae/` and
+`vocoder/` folders (`mmaudio_decoder`). This module downloads each one's
+pinned files with `hf_hub_download(revision=...)`, caches it with
+`cached_model`, and runs them in upstream's order: frames at 8 fps (CLIP,
+384) and 25 fps (Synchformer, 224), the prompt through CLIP's text tower,
+Euler flow matching with classifier-free guidance, then the decode.
+
+The network's `unnormalize` returns raw VAE latents, so they go to the
+decoder as they are - no division by the VAE's scaling_factor, which K6's
+own pipeline applies to latents of its own scaled space.
+
+Every refusal runs before any load: the trust gate on a remote-code
+argument, an unknown argument (a kwargs task would otherwise drop it
+silently), no `video` and no `prompt`, and a `duration` over 20 s or
+longer than the clip. Two notes go on the result through
+`dw.events.emit_warning`: a duration outside the 4-12 s the model was
+trained around, and an output that measures noise-like (spectral flatness
+>= 0.3 and centroid >= 8 kHz).
+
+Licences: the MMAudio weights (network, Synchformer, VAE tensors) are
+CC-BY-NC 4.0; DFN5B is under the Apple Machine Learning Research Model
+License (research only) - ATTRIBUTIONS.md.
+"""
+
+import logging
+import math
+import os
+import tempfile
+
+import numpy
+import torch
+
+from .. import get_device_type
+from ..media_types import AudioTrack
+from .weights import file_entries
+
+logger = logging.getLogger("dw")
+
+COMMAND = "generate_sound_effects"
+
+DEFAULT_STEPS = 25
+DEFAULT_GUIDANCE_SCALE = 4.5
+TEXT_ONLY_DURATION = 8.0
+MAX_DURATION = 20.0
+# The span the large 44k v2 network was trained and evaluated around (8 s);
+# outside it the output drifts, so a duration there is noted, not refused
+TRAINED_DURATION = (4.0, 12.0)
+# The noise-like output note: both must hold (dw/dsp.py spectral_centroid)
+NOISE_FLATNESS = 0.3
+NOISE_CENTROID_HZ = 8000.0
+
+CLIP_FPS = 8
+SYNC_FPS = 25
+SYNC_SIZE = 224
+# Synchformer reads 16-frame segments: the shortest clip it can encode
+MIN_SYNC_FRAMES = 16
+# A bare frame list carries no rate; an AudioVideo or a file does
+ASSUMED_FPS = 24
+
+ARGUMENTS = frozenset(
+    {"video", "prompt", "negative_prompt", "duration", "steps", "guidance_scale"}
+)
+
+LICENCE_NOTE = (
+    "MMAudio weights (network, Synchformer, VAE tensors): CC-BY-NC 4.0, "
+    "non-commercial. DFN5B CLIP: Apple Machine Learning Research Model License "
+    "(research only) - Apple Machine Learning Research Model is licensed under "
+    "the Apple Machine Learning Research Model License Agreement."
+)
+
+
+def required_weights(arguments=None):
+    """Every file the task reads, each pinned (dw/tasks/weights.py): the
+    MMAudio network and Synchformer, K6's audio_vae/ and vocoder/ config and
+    safetensors, and DFN5B's open_clip weights and tokenizer. Never MMAudio's
+    own v1-44.pth VAE or bigvgan_generator.pt: the decoder is K6's copy."""
+    from .mmaudio_clip import (
+        CLIP_REPO_ID,
+        CLIP_REVISION,
+        CLIP_TOKENIZER_FILE,
+        CLIP_WEIGHTS_FILE,
+    )
+    from .mmaudio_decoder import K6_REPO_ID, K6_REVISION
+    from .mmaudio_model import NETWORK_FILE, REPO_ID, REVISION
+    from .mmaudio_sync_model import SYNC_FILE
+
+    entries = []
+    for filename in (NETWORK_FILE, SYNC_FILE):
+        entries += file_entries(REPO_ID, filename, REVISION)
+    for filename in _decoder_files():
+        entries += file_entries(K6_REPO_ID, filename, K6_REVISION)
+    for filename in (CLIP_WEIGHTS_FILE, CLIP_TOKENIZER_FILE):
+        entries += file_entries(CLIP_REPO_ID, filename, CLIP_REVISION)
+    return entries
+
+
+def _decoder_files():
+    from .mmaudio_decoder import CONFIG_FILE, VAE_FOLDER, VOCODER_FOLDER, WEIGHTS_FILE
+
+    return [
+        f"{folder}/{name}"
+        for folder in (VAE_FOLDER, VOCODER_FOLDER)
+        for name in (CONFIG_FILE, WEIGHTS_FILE)
+    ]
+
+
+# ---------------------------------------------------------------- refusals
+
+
+def _refuse_remote_code(kwargs):
+    """trust_remote_code / custom_pipeline / custom_generate as a step
+    argument: the trust gate's refusal when workflows are untrusted, and a
+    plain error otherwise - this task loads no Hub code either way."""
+    from ..security import UntrustedWorkflowError
+    from ..trust import TASK_REMOTE_CODE_ARGUMENTS, workflows_are_trusted
+
+    given = [name for name in TASK_REMOTE_CODE_ARGUMENTS if kwargs.get(name)]
+    if not given:
+        return
+    names = " or ".join(map(repr, given))
+    if not workflows_are_trusted():
+        raise UntrustedWorkflowError(
+            f"Refusing to run {COMMAND}: its arguments set {names}, which "
+            "downloads and executes Python from a Hub repository, so it needs "
+            "trusted workflows - see docs/SECURITY.md. generate_sound_effects "
+            "loads no Hub code from its arguments in any case; drop it"
+        )
+    raise ValueError(
+        f"{COMMAND} takes no {names} argument - it loads no Hub code from its "
+        "arguments, so the setting would have no effect. Drop it"
+    )
+
+
+def _refuse_unknown(kwargs):
+    from ..trust import TASK_REMOTE_CODE_ARGUMENTS
+
+    unknown = sorted(set(kwargs) - ARGUMENTS - set(TASK_REMOTE_CODE_ARGUMENTS))
+    if unknown:
+        raise ValueError(
+            f"{COMMAND} takes no {', '.join(map(repr, unknown))} argument - it "
+            f"takes {', '.join(sorted(ARGUMENTS))}"
+        )
+
+
+def _number(name, value, whole=False):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{COMMAND}: '{name}' must be a number, got {value!r}")
+    if not math.isfinite(value) or value <= 0:
+        raise ValueError(f"{COMMAND}: '{name}' must be positive, got {value!r}")
+    if whole and int(value) != value:
+        raise ValueError(f"{COMMAND}: '{name}' must be a whole number, got {value!r}")
+    return int(value) if whole else float(value)
+
+
+def _text(name, value):
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise ValueError(f"{COMMAND}: '{name}' must be text, got {value!r}")
+    return value.strip() or None
+
+
+def _check_duration(duration, clip_seconds):
+    """The duration the run uses: the given one, refused over MAX_DURATION
+    or past the clip's end, else the clip's length (capped), else 8 s."""
+    if duration is None:
+        if clip_seconds is None:
+            return TEXT_ONLY_DURATION
+        return min(clip_seconds, MAX_DURATION)
+    duration = _number("duration", duration)
+    if duration > MAX_DURATION:
+        raise ValueError(
+            f"{COMMAND}: 'duration' {duration:g} s is over the {MAX_DURATION:g} s "
+            "this task generates; ask for less, or generate the clip in pieces"
+        )
+    if clip_seconds is not None and duration > clip_seconds + 1e-3:
+        raise ValueError(
+            f"{COMMAND}: 'duration' {duration:g} s is longer than the "
+            f"{clip_seconds:.2f} s clip in 'video' - leave it unset for the "
+            "clip's whole length"
+        )
+    return duration
+
+
+# ------------------------------------------------------------------- video
+
+
+def _video_file(video):
+    """(path, is_temporary) for a 'video': the file a stored video names, or
+    an in-memory clip (an AudioVideo or a frame list) written to a temporary
+    mp4 at its own frame rate (ASSUMED_FPS for bare frames)."""
+    from ..locations import validate_media_path
+    from .video_utils import VideoFileReference
+
+    if isinstance(video, VideoFileReference):
+        video = video.path
+    if isinstance(video, str):
+        return validate_media_path(video, None, "a video argument"), False
+    frames = getattr(video, "frames", video)
+    fps = getattr(video, "fps", None) or ASSUMED_FPS
+    if frames is None or isinstance(frames, (dict, bytes)):
+        raise ValueError(
+            f"{COMMAND}: 'video' must be a video (asset:, output:, a path or an "
+            f"earlier step's video), not {type(video).__name__}"
+        )
+    from diffusers.utils import export_to_video
+
+    from ..result import _frames_for_export_to_video
+
+    handle, path = tempfile.mkstemp(suffix=".mp4", prefix="dw-sfx-")
+    os.close(handle)
+    export_to_video(_frames_for_export_to_video(frames), path, fps=fps)
+    return path, True
+
+
+def _clip_seconds(path):
+    from ..media import video_shape
+
+    shape = video_shape(path)
+    if shape.get("fps") and shape.get("frame_count"):
+        return shape["frame_count"] / shape["fps"]
+    from ..media import media_duration
+
+    return media_duration(path)
+
+
+def _frame_tensors(path, duration):
+    """The clip's CLIP frames (1, T, 3, 384, 384) in [0, 1] and Synchformer
+    frames (1, T, 3, 224, 224) in [-1, 1], and the duration both cover
+    (upstream trims to the shorter of the two)."""
+    from ..media import sample_frames
+    from .mmaudio_clip import ClipConfig
+
+    clip = sample_frames(path, CLIP_FPS, duration, ClipConfig().image_size)
+    sync = sample_frames(path, SYNC_FPS, duration, SYNC_SIZE, crop=True)
+    if len(sync) < MIN_SYNC_FRAMES or len(clip) < 1:
+        raise ValueError(
+            f"{COMMAND}: the clip in 'video' is too short - it needs at least "
+            f"{MIN_SYNC_FRAMES / SYNC_FPS:.2f} s of frames"
+        )
+    covered = min(len(clip) / CLIP_FPS, len(sync) / SYNC_FPS, duration)
+    clip_t = torch.from_numpy(numpy.ascontiguousarray(clip)).float().div(255.0)
+    sync_t = torch.from_numpy(numpy.ascontiguousarray(sync)).float()
+    return (
+        clip_t.permute(0, 3, 1, 2).unsqueeze(0),
+        sync_t.permute(0, 3, 1, 2).unsqueeze(0),
+        covered,
+    )
+
+
+# ------------------------------------------------------------------ models
+
+
+def _dtype(device):
+    return torch.bfloat16 if get_device_type(device) == "cuda" else torch.float32
+
+
+def _download(repo, filename, revision):
+    from huggingface_hub import hf_hub_download
+
+    return hf_hub_download(repo_id=repo, filename=filename, revision=revision)
+
+
+def _load_models(device, dtype):
+    """The network, CLIP + tokenizer, Synchformer and decoder, each cached
+    under (command, repo, file, revision, device, dtype)."""
+    from . import mmaudio_clip, mmaudio_decoder, mmaudio_model, mmaudio_sync_model
+    from .model_cache import cached_model
+
+    repo, rev = mmaudio_model.REPO_ID, mmaudio_model.REVISION
+    where = (str(device), str(dtype))
+
+    def network():
+        path = _download(repo, mmaudio_model.NETWORK_FILE, rev)
+        logger.info(f"Loading MMAudio network to {device}")
+        return mmaudio_model.load_network(path, device=device, dtype=dtype)
+
+    def sync():
+        path = _download(repo, mmaudio_sync_model.SYNC_FILE, rev)
+        logger.info(f"Loading MMAudio Synchformer to {device}")
+        return mmaudio_sync_model.load_synchformer(path, device=device, dtype=dtype)
+
+    clip_repo, clip_rev = mmaudio_clip.CLIP_REPO_ID, mmaudio_clip.CLIP_REVISION
+
+    def clip():
+        weights = _download(clip_repo, mmaudio_clip.CLIP_WEIGHTS_FILE, clip_rev)
+        tokens = _download(clip_repo, mmaudio_clip.CLIP_TOKENIZER_FILE, clip_rev)
+        logger.info(f"Loading DFN5B CLIP to {device}")
+        model = mmaudio_clip.load_clip(weights, device=device, dtype=dtype)
+        return model, mmaudio_clip.load_clip_tokenizer(tokens)
+
+    k6_repo, k6_rev = mmaudio_decoder.K6_REPO_ID, mmaudio_decoder.K6_REVISION
+
+    def decoder():
+        paths = [_download(k6_repo, name, k6_rev) for name in _decoder_files()]
+        vae_folder, vocoder_folder = (
+            os.path.dirname(paths[0]),
+            os.path.dirname(paths[2]),
+        )
+        logger.info(f"Loading MMAudio VAE + vocoder (K6) to {device}")
+        return mmaudio_decoder.load_decoder(vae_folder, vocoder_folder, device=device)
+
+    return (
+        cached_model((COMMAND, repo, mmaudio_model.NETWORK_FILE, rev, *where), network),
+        cached_model(
+            (COMMAND, clip_repo, mmaudio_clip.CLIP_WEIGHTS_FILE, clip_rev, *where), clip
+        ),
+        cached_model((COMMAND, repo, mmaudio_sync_model.SYNC_FILE, rev, *where), sync),
+        cached_model(
+            (COMMAND, k6_repo, "audio_vae+vocoder", k6_rev, str(device)), decoder
+        ),
+    )
+
+
+# --------------------------------------------------------------- warnings
+
+
+def _warn(waveform, sample_rate, duration):
+    from .. import dsp
+    from ..events import emit_warning
+
+    low, high = TRAINED_DURATION
+    if not low <= duration <= high:
+        emit_warning(
+            f"{COMMAND}: duration {duration:g} s is outside the {low:g}-{high:g} s "
+            "MMAudio was trained around; the effects may drift or thin out - "
+            "generate 8 s pieces for a longer clip",
+            command=COMMAND,
+            duration=duration,
+        )
+    if not numpy.any(waveform):
+        return
+    flatness = dsp.spectral_flatness(waveform)
+    centroid = dsp.spectral_centroid(waveform, sample_rate)
+    if flatness >= NOISE_FLATNESS and centroid >= NOISE_CENTROID_HZ:
+        emit_warning(
+            f"{COMMAND}: the output measures noise-like (spectral flatness "
+            f"{flatness:.2f}, centroid {centroid / 1000:.1f} kHz) - often hiss "
+            "rather than effects. Name the on-screen sound sources in 'prompt' "
+            "(video-only is the weaker mode), or try another seed",
+            command=COMMAND,
+            flatness=flatness,
+            centroid_hz=centroid,
+        )
+
+
+# ------------------------------------------------------------------- task
+
+
+def generate_sound_effects(
+    video=None,
+    prompt=None,
+    negative_prompt=None,
+    duration=None,
+    steps=DEFAULT_STEPS,
+    guidance_scale=DEFAULT_GUIDANCE_SCALE,
+    device="cpu",
+    seed=None,
+    **kwargs,
+):
+    """Sound effects for a clip, a prompt, or both, as a 44.1 kHz mono
+    AudioTrack.
+
+    Args:
+        video: The clip to score (a stored video or an earlier step's).
+            Video-only is the weaker mode; a prompt naming the on-screen
+            sound sources is recommended alongside it
+        prompt: What should be heard
+        negative_prompt: What should not (replaces the empty condition)
+        duration: Seconds of audio, at most 20 and at most the clip's
+            length (default: the clip's length, or 8 s text-only)
+        steps: Euler flow-matching steps (default 25)
+        guidance_scale: Classifier-free guidance strength (default 4.5)
+        device: Where to run
+        seed: The step/workflow seed, for a reproducible take
+    """
+    _refuse_remote_code(kwargs)
+    _refuse_unknown(kwargs)
+    prompt = _text("prompt", prompt)
+    negative_prompt = _text("negative_prompt", negative_prompt)
+    steps = _number("steps", steps, whole=True)
+    guidance_scale = float(_number("guidance_scale", guidance_scale))
+    if video is None and prompt is None:
+        raise ValueError(
+            f"{COMMAND} needs 'video' or 'prompt' (or both): there is nothing "
+            "to make sound effects for"
+        )
+
+    path, temporary = (None, False) if video is None else _video_file(video)
+    try:
+        clip_seconds = None if path is None else _clip_seconds(path)
+        duration = _check_duration(duration, clip_seconds)
+        frames = None if path is None else _frame_tensors(path, duration)
+    finally:
+        if temporary:
+            os.unlink(path)
+    if frames is not None:
+        duration = frames[2]
+    return _generate(
+        frames, prompt, negative_prompt, duration, steps, guidance_scale, device, seed
+    )
+
+
+def _generate(
+    frames, prompt, negative_prompt, duration, steps, guidance_scale, device, seed
+):
+    from .mmaudio_clip import tokenize
+    from .mmaudio_model import sample_latent
+    from .mmaudio_sync_model import encode_sync_frames
+
+    dtype = _dtype(device)
+    net, (clip, tokenizer), sync, decoder = _load_models(device, dtype)
+    seq = net.set_duration(duration)
+
+    clip_f = sync_f = text_f = negative_f = None
+    if frames is not None:
+        clip_frames, sync_frames, _ = frames
+        clip_f = clip.encode_frames(clip_frames)[:, : net.clip_seq_len]
+        param = next(sync.parameters())
+        sync_frames = sync_frames.to(param.device, param.dtype)
+        sync_f = encode_sync_frames(sync, sync_frames)
+        sync_f = sync_f[:, : net.sync_seq_len]
+    if prompt is not None:
+        text_f = clip.encode_text(tokenize(tokenizer, [prompt]))
+    if negative_prompt is not None:
+        negative_f = clip.encode_text(tokenize(tokenizer, [negative_prompt]))
+
+    generator = None
+    if seed is not None:
+        generator = torch.Generator(device=net.device).manual_seed(int(seed))
+    logger.info(
+        f"{COMMAND}: {duration:.2f} s, {steps} steps, guidance {guidance_scale:g}"
+        f"{', video' if frames is not None else ''}{', prompt' if prompt else ''}"
+    )
+    latent = sample_latent(
+        net,
+        clip_features=clip_f,
+        sync_features=sync_f,
+        text_features=text_f,
+        negative_text_features=negative_f,
+        steps=steps,
+        cfg_strength=guidance_scale,
+        generator=generator,
+    )
+    waveform = decoder.decode(latent.transpose(1, 2).float())
+    samples = min(seq.num_audio_frames, round(duration * decoder.sample_rate))
+    audio = waveform[0, :, :samples].float().cpu().numpy()
+    _warn(audio, decoder.sample_rate, duration)
+    return AudioTrack(audio, decoder.sample_rate)

From f48492f5a441c61942add05b0abb84bc81937076 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:19:16 -0600
Subject: [PATCH 117/125] docs: #1095 close-out - analyze_phrases design record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/analyze-phrases-complete.md      | 124 ++++++++++++++++++
 docs/proposals/todo.md                        |   9 ++
 2 files changed, 133 insertions(+)
 create mode 100644 docs/proposals/complete/analyze-phrases-complete.md

diff --git a/docs/proposals/complete/analyze-phrases-complete.md b/docs/proposals/complete/analyze-phrases-complete.md
new file mode 100644
index 00000000..28a8f6f2
--- /dev/null
+++ b/docs/proposals/complete/analyze-phrases-complete.md
@@ -0,0 +1,124 @@
+# Phrase timing without Whisper: `analyze_phrases` and `plan_cuts` (#1095)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). Plan v1 on #1095 was approved on 2026-10-31 under Don's
+delegation with every default (Q1-Q3). v2 folded those answers in with no
+change of scope. v3 re-planned after a failed field verify, and Don ruled
+Q4 = (a), loosen, on 2026-11-01. It was built as two stages: #1104
+(stage A) and #1105 (stage B).
+
+## The report
+
+`plan_cuts` (#600) gets all of its line timing from a `transcribe_audio`
+transcript. When Whisper can't hear the words (a non-English song, a
+hallucination, wordless vocals or vocalise), there is no fallback. The
+field case was `russian-anthem` job `0838f676f51f` (2026-10-12). Whisper
+turned a Russian verse into the subtitle-credit hallucination
+"Россия Редактор субтитров А.Семкин", and the session gave up on the
+planner and cut the song by hand. The same class as #822.
+
+The concept (centre-channel, voice-band energy onsets) comes from
+Longshot_Studio's `audio_sync.detect_phrases`. That repo has no license,
+so no code was copied: only the idea was taken.
+
+## Verdict
+
+**Build smaller.** One new JSON task, `analyze_phrases`, and `plan_cuts`
+accepting its result where it takes a transcript. No new template, no
+`analyze_beats` mode, and no MCP tool, REST route or syntax change. The
+stereo-centre weighting stays in as a default-on detail (`centre=true`,
+Q1), because it costs about 15 lines and the template feeds `plan_cuts` a
+vocal stem anyway (#822).
+
+## What the plan found against the issue
+
+1. **The result is a dict, not a list.** `measure_sync` returns a dict,
+   and a list result would be saved as one artifact per item.
+2. **Empty-text chunks don't "just work" in `plan_cuts`.**
+   `_transcript_lines` drops them, so a phrase list would plan as one
+   instrumental shot. `plan_cuts` recognises the phrase result by its
+   `phrases` key and handles it explicitly.
+3. **It is its own task, not an `analyze_beats` mode.** That task
+   downmixes on load, and its result shape is for beats.
+
+## What was built
+
+### Stage A (#1104): the `analyze_phrases` task
+- `dw/tasks/phrases.py`, registered with `returns="json"`. It answers
+  `{phrases: [{start, end}], duration_seconds, method: "centre"|"band",
+  warnings}`, in seconds rounded to 0.01.
+- Stereo: max(0, P_mid - P_side) in 250-3500 Hz over 20 ms frames,
+  smoothed. Mono, `centre: false` or identical channels: band power of the
+  downmix (`method: "band"`, plus a warning on mono input).
+- Voiced floor: `voice_attribution.voiced_floor_dbfs` (p95 - 35 dB, never
+  below -60 dBFS), unless `floor_db` overrides it. Gaps under
+  `min_gap_seconds` (0.35) are bridged, and runs under
+  `min_phrase_seconds` (0.3) are dropped.
+- Refusals go through the registration's domains and
+  `task_problems.phrases_problems`. The task warns on no phrases and on
+  one phrase covering more than 90% of the track.
+- Docs: a `docs/TASKS.md` entry and a `docs/ARCHITECTURE.md` row.
+
+### Stage B (#1105): `plan_cuts` takes phrases
+- A phrase branch in `dw/tasks/cuts.py` (`_is_phrases`, `_phrases`,
+  `_phrase_lines`). `transcript_problem` accepts the shape.
+- Without `lyrics`: one line per phrase, `lyric: null`. `segment_by`
+  `line`, `stanza` and `beat` all work.
+- With `lyrics` and matching counts: one to one, in order (Q2). A **disproportion
+  warning** (the lead's call at the v3 decompose) names any line whose
+  phrase is under 1/4 or over 4x the median phrase length. The pairing
+  still stands.
+- With mismatched counts: a warning names both counts and the knob, then
+  the lines are spread evenly over the first phrase's start to the last
+  phrase's end. With more phrases than lines, the warning says to raise
+  `min_gap_seconds`. With fewer, it says to lower it, or (v3) to raise
+  `floor_db` for fused legato or reverberant lines, and to check the phrases
+  by ear before trusting a pairing.
+- v3: stage A's 90% warning names both remedies (feed `stems.vocals` on a
+  mix, raise `floor_db` on a stem already).
+- Docs: `docs/TASKS.md` `plan_cuts`, the `music-video-cuts` template
+  description and `workflows/templates/minimax/README.md`, and
+  `plugins/dw/skills/minimax-h3/references/cuts.md`. Its stale chain now
+  includes `separate_stems`, and it documents the swap: `transcribe` →
+  `analyze_phrases` on `previous_result:stems.vocals`, plus `lyrics`.
+
+## What the field case showed (the v3 re-plan)
+
+On lem, `verse_s7.wav` (a legato, reverberant choir, 4 lyric lines) gave
+one phrase over 1.44-33.00 s at the defaults. `min_gap_seconds` 0.15 still
+gave 1 and 0.05 gave 2. Only `floor_db` -30 gave 4, and those were
+2.66-5.12, 7.26-15.58, 16.02-16.36 and 18.40-33.00 s, which don't look like
+sung lines. Between legato lines the energy never drops below the
+track-relative floor, so the plan's Value claim ("this would have fixed
+that run") didn't hold for pairing. It does hold for the timeline: the span
+is the vocal's true span, not a hallucinated one.
+
+Don ruled **Q4 = (a), loosen**. B finishes with the advice fix, and the
+field case is judged on the true span, the warnings and the even spread,
+not on pairing. He also added the pairing caution (`floor_db` can make the
+counts match on bad boundaries, so check by ear).
+
+## Deferred, and what brings it back
+
+- **Stage C, a local-level (rolling 1-2 s) voicing floor.** Dropped by the
+  Q4 ruling. It would come back with a probe on `verse_s7.wav` that finds a
+  setting giving 4 phrases at audible line starts, by ear.
+- **Duration-aligned in-order mapping** of lyric lines onto phrases when
+  the counts differ. It stays a follow-up idea and was not filed. The field
+  case is the first data point that count mismatches are common. A second
+  field report would justify its own design.
+- **Telling lead vocals from backing vocals, and word-level timing without
+  Whisper.** Non-goals.
+
+## Verification and bounces
+
+| Stage | Bounces | Verified |
+|---|---|---|
+| A (#1104) | 0 | mini-ai (mps), develop @ 65f26281: C-F576-C-F582 |
+| B (#1105) | 2: a failed field verify (C-F589 on lem, which led to the v3 re-plan), and one architecture-review bounce (a hand-rolled median replaced by `statistics.median`) | C-F583-C-F588 and C-F624-C-F627 on mini-ai @ 0e35506a / 46d1ec23. All of them, plus field case C-F628, on lem @ d71bc1f5 |
+
+C-F589 (its pairing clause) is superseded by C-F628. Its retirement is
+open as dkackman/harnest#168.
+
+Cost: the stage comments name no `usage:` figures, so none are recorded
+here. The plan estimated $6-9 for both stages, plus about $1 for v3.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 64ac0364..2501e174 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -37,6 +37,15 @@ remaining deferred fix is recorded in
 
 ## Shipped since the ranking
 
+- **Phrase timing without Whisper** (#1095, stages #1104-#1105), shipped
+  2026-11-01. A new JSON task, `analyze_phrases`, times sung phrases from
+  centre-weighted voice-band energy with no model. `plan_cuts` takes its
+  result in place of a transcript, maps `lyrics` one to one when the counts
+  match, and otherwise warns, names the knob (`min_gap_seconds`,
+  `floor_db`) and spreads the lines evenly. The music-video template documents
+  the `transcribe` → `analyze_phrases` swap. Record, including the dropped
+  local-level floor and the deferred duration-aligned mapping:
+  `complete/analyze-phrases-complete.md`.
 - **Beat authoring and the beat review in the story skills** (#1122, stage
   #1125), shipped 2026-11-01. `script-to-video`'s shot sheet gains `beat`
   and `must_not`; a new `references/beat-review.md` holds the beat-writing

From 15fae931e251de9ea8f4af6b4383974407e5bbf5 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:19:46 -0600
Subject: [PATCH 118/125] feat(catalog): #1133 - video-to-sound-effects and
 text-to-sound-effect templates

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 tests/test_catalog_shape.py                   |  1 +
 tests/test_mmaudio_decoder.py                 |  5 +-
 tests/test_mmaudio_model.py                   |  6 +--
 tests/test_mmaudio_sync_model.py              |  5 +-
 workflows/templates/text-to-sound-effect.json | 31 ++++++++++++
 .../templates/video-to-sound-effects.json     | 49 +++++++++++++++++++
 6 files changed, 90 insertions(+), 7 deletions(-)
 create mode 100644 workflows/templates/text-to-sound-effect.json
 create mode 100644 workflows/templates/video-to-sound-effects.json

diff --git a/tests/test_catalog_shape.py b/tests/test_catalog_shape.py
index 76053a2b..2b5d0d10 100644
--- a/tests/test_catalog_shape.py
+++ b/tests/test_catalog_shape.py
@@ -71,6 +71,7 @@ def test_vocabularies_are_closed_and_stable():
             "image_to_text",
             "diffusion_upscale",
             "interpolate_frames",
+            "generate_sound_effects",
         }
     )
 
diff --git a/tests/test_mmaudio_decoder.py b/tests/test_mmaudio_decoder.py
index c3125267..c7832d94 100644
--- a/tests/test_mmaudio_decoder.py
+++ b/tests/test_mmaudio_decoder.py
@@ -153,9 +153,10 @@ def test_weights_are_pinned():
     assert dec.WEIGHTS_FILE.endswith(".safetensors")
 
 
-def test_module_is_not_imported_by_dw():
+def test_module_is_imported_only_by_the_sound_effects_task():
+    # stage D (#1133): generate_sound_effects is its one consumer
     dw_root = Path(dec.__file__).resolve().parents[1]
     for path in dw_root.rglob("*.py"):
-        if path.name == "mmaudio_decoder.py":
+        if path.name in ("mmaudio_decoder.py", "sound_effects.py"):
             continue
         assert "mmaudio_decoder" not in path.read_text(encoding="utf-8"), path
diff --git a/tests/test_mmaudio_model.py b/tests/test_mmaudio_model.py
index ae34adff..769f0ccb 100644
--- a/tests/test_mmaudio_model.py
+++ b/tests/test_mmaudio_model.py
@@ -530,9 +530,9 @@ def test_weights_are_pinned():
     assert mc.CLIP_REVISION == "01b771ed0d1395ca5ffdd279897d665ebe00dfd2"
 
 
-def test_modules_are_not_imported_by_dw():
-    # stage B is inert: nothing in dw imports either module
-    own = {MODULE_PATH, CLIP_MODULE_PATH}
+def test_modules_are_imported_only_by_the_sound_effects_task():
+    # stage D (#1133): generate_sound_effects is their one consumer
+    own = {MODULE_PATH, CLIP_MODULE_PATH, MODULE_PATH.parent / "sound_effects.py"}
     for path in MODULE_PATH.parents[1].rglob("*.py"):
         if path not in own:
             text = path.read_text(encoding="utf-8")
diff --git a/tests/test_mmaudio_sync_model.py b/tests/test_mmaudio_sync_model.py
index 8a80bf2c..e420ea54 100644
--- a/tests/test_mmaudio_sync_model.py
+++ b/tests/test_mmaudio_sync_model.py
@@ -181,8 +181,9 @@ def test_weights_are_pinned():
     assert sm.SYNC_FILE == "ext_weights/synchformer_state_dict.pth"
 
 
-def test_module_is_not_imported_by_dw():
+def test_module_is_imported_only_by_the_sound_effects_task():
+    # stage D (#1133): generate_sound_effects is its one consumer
     for path in MODULE_PATH.parents[1].rglob("*.py"):
-        if path != MODULE_PATH:
+        if path not in (MODULE_PATH, MODULE_PATH.parent / "sound_effects.py"):
             text = path.read_text(encoding="utf-8")
             assert "mmaudio_sync_model" not in text, path
diff --git a/workflows/templates/text-to-sound-effect.json b/workflows/templates/text-to-sound-effect.json
new file mode 100644
index 00000000..c3e68b55
--- /dev/null
+++ b/workflows/templates/text-to-sound-effect.json
@@ -0,0 +1,31 @@
+{
+  "id": "TextToSoundEffect",
+  "description": "Generates a sound effect from a text prompt alone with MMAudio (large 44.1 kHz v2) and saves it as a 44.1 kHz mono wav. 'prompt' says what should be heard ('a heavy wooden door creaks open, then slams'); 'duration' is 8 s by default, at most 20 s, and the model was trained around 8 s, so it warns outside 4-12 s. The effect runs 7-25 dB hot: route it through match_levels before mixing it with dialogue or music. For effects that follow a clip's picture, use the video-to-sound-effects template. Licences: the MMAudio weights (network, Synchformer, VAE tensors) are CC-BY-NC 4.0, non-commercial; the DFN5B CLIP encoder is under the Apple Machine Learning Research Model License, research only - Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement.",
+  "summary": "A sound effect from a text prompt (MMAudio), as a 44.1 kHz mono wav.",
+  "variables": {
+    "prompt": "a heavy wooden door creaks open, then slams shut",
+    "negative_prompt": "music, speech",
+    "duration": 8.0,
+    "steps": 25,
+    "guidance_scale": 4.5
+  },
+  "steps": [
+    {
+      "name": "effect",
+      "task": {
+        "command": "generate_sound_effects",
+        "arguments": {
+          "prompt": "variable:prompt",
+          "negative_prompt": "variable:negative_prompt",
+          "duration": "variable:duration",
+          "steps": "variable:steps",
+          "guidance_scale": "variable:guidance_scale"
+        }
+      },
+      "result": {
+        "content_type": "audio/wav",
+        "subfolder": "final"
+      }
+    }
+  ]
+}
diff --git a/workflows/templates/video-to-sound-effects.json b/workflows/templates/video-to-sound-effects.json
new file mode 100644
index 00000000..f196324c
--- /dev/null
+++ b/workflows/templates/video-to-sound-effects.json
@@ -0,0 +1,49 @@
+{
+  "id": "VideoToSoundEffects",
+  "description": "Generates sound effects for a clip with MMAudio (large 44.1 kHz v2) and muxes them under it, replacing the clip's own sound. 'video' is the clip: an 'asset:' or 'output:' ref. 'prompt' names the on-screen sound sources - what should be heard ('footsteps on wet gravel, a car door slams, distant traffic'); leave it empty only to let the picture alone drive the effects, which is the weaker mode, so a prompt is recommended. 'duration' defaults to the clip's whole length, at most 20 s; the model was trained around 8 s and warns outside 4-12 s. Outputs two files: the effects stem (a 44.1 kHz mono wav) and the clip muxed with it. The effects run 7-25 dB hot: before mixing the stem with dialogue or music, route it through match_levels. Licences: the MMAudio weights (network, Synchformer, VAE tensors) are CC-BY-NC 4.0, non-commercial; the DFN5B CLIP encoder is under the Apple Machine Learning Research Model License, research only - Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement.",
+  "summary": "Sound effects for a clip (MMAudio), muxed under it; name the on-screen sound sources in prompt.",
+  "shape": "audio",
+  "variables": {
+    "video": "asset:clip.mp4",
+    "prompt": "footsteps on gravel, a door closing, wind in the trees",
+    "negative_prompt": "music, speech",
+    "duration": null,
+    "steps": 25,
+    "guidance_scale": 4.5
+  },
+  "steps": [
+    {
+      "name": "effects",
+      "task": {
+        "command": "generate_sound_effects",
+        "arguments": {
+          "video": "variable:video",
+          "prompt": "variable:prompt",
+          "negative_prompt": "variable:negative_prompt",
+          "duration": "variable:duration",
+          "steps": "variable:steps",
+          "guidance_scale": "variable:guidance_scale"
+        }
+      },
+      "result": {
+        "content_type": "audio/wav",
+        "subfolder": "final"
+      }
+    },
+    {
+      "name": "mux",
+      "task": {
+        "command": "pair_audio",
+        "arguments": {
+          "video": "variable:video",
+          "audio": "previous_result:effects",
+          "fit": "video"
+        }
+      },
+      "result": {
+        "content_type": "video/mp4",
+        "subfolder": "final"
+      }
+    }
+  ]
+}

From 3816db31c8884c032991f63832b10f602594eb3e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:26:25 -0600
Subject: [PATCH 119/125] feat(docs): #1133 - sound effects docs, skill lines
 and tests

TASKS.md section, ATTRIBUTIONS "Used by" for the MMAudio/K6/DFN5B rows,
skill lines (series-episodes, ltx-2.5, kandinsky-6) routing effects
through match_levels; tests for refusals, trust gate, warnings, the
pinned weights and loader agreement, catalog shape. Compact listing
budget re-measured for the two new templates.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/ATTRIBUTIONS.md                          |   8 +-
 docs/TASKS.md                                 |  40 +++
 plugins/dw/skills/kandinsky-6/SKILL.md        |   2 +
 plugins/dw/skills/ltx-2.5/SKILL.md            |   1 +
 plugins/dw/skills/series-episodes/SKILL.md    |   2 +
 tests/test_catalog_structure.py               |  14 +-
 tests/test_sound_effects.py                   | 232 ++++++++++++++++++
 tests/test_step_cache.py                      |   2 +
 tests/test_task_weights.py                    | 100 ++++++++
 workflows/templates/text-to-sound-effect.json |   2 +-
 .../templates/video-to-sound-effects.json     |   2 +-
 11 files changed, 396 insertions(+), 9 deletions(-)
 create mode 100644 tests/test_sound_effects.py

diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
index 43d201c0..2745f157 100644
--- a/docs/ATTRIBUTIONS.md
+++ b/docs/ATTRIBUTIONS.md
@@ -31,10 +31,10 @@ apply to anything generated with them.
 
 | Weights | Used by | Licence |
 |---|---|---|
-| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) (`weights/mmaudio_large_44k_v2.pth` and its `ext_weights/`) | [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
-| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) `ext_weights/synchformer_state_dict.pth` | MMAudio's sync features, [dw/tasks/mmaudio_sync_model.py](../dw/tasks/mmaudio_sync_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
-| [kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers](https://huggingface.co/kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers/tree/4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81) `audio_vae/` and `vocoder/` | MMAudio's decoder, [dw/tasks/mmaudio_decoder.py](../dw/tasks/mmaudio_decoder.py) | The MMAudio VAE tensors: [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/), non-commercial use only, as MMAudio's weights (K6's model card states MIT; dw follows the stricter MMAudio terms). The BigVGAN vocoder: MIT. |
-| [apple/DFN5B-CLIP-ViT-H-14-384](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384) | MMAudio's CLIP conditioning, [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | [Apple Machine Learning Research Model License](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384/blob/main/LICENSE): research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. dw maps the weights into transformers' layout in memory at load time and never writes or ships converted tensors. |
+| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) (`weights/mmaudio_large_44k_v2.pth` and its `ext_weights/`) | `generate_sound_effects`: [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) `ext_weights/synchformer_state_dict.pth` | `generate_sound_effects`, MMAudio's sync features, [dw/tasks/mmaudio_sync_model.py](../dw/tasks/mmaudio_sync_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers](https://huggingface.co/kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers/tree/4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81) `audio_vae/` and `vocoder/` | `generate_sound_effects`, MMAudio's decoder, [dw/tasks/mmaudio_decoder.py](../dw/tasks/mmaudio_decoder.py) | The MMAudio VAE tensors: [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/), non-commercial use only, as MMAudio's weights (K6's model card states MIT; dw follows the stricter MMAudio terms). The BigVGAN vocoder: MIT. |
+| [apple/DFN5B-CLIP-ViT-H-14-384](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384) | `generate_sound_effects`, MMAudio's CLIP conditioning, [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | [Apple Machine Learning Research Model License](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384/blob/main/LICENSE): research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. dw maps the weights into transformers' layout in memory at load time and never writes or ships converted tensors. |
 
 ## Ideas reimplemented here
 
diff --git a/docs/TASKS.md b/docs/TASKS.md
index dbf95a53..f236bb91 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3244,6 +3244,46 @@ A speech model is worth releasing before a video model loads — set `release_mo
 - [voice-clone.json](../workflows/templates/voice-clone.json) — Speak a line in the voice of a reference clip (Audio8-TTS)
 - [voice-timbre-reference.json](../workflows/templates/minimax/voice-timbre-reference.json) — Generate a voice, then condition H3's `<Audio 1>` on it
 
+## Sound Effects Generation
+
+`generate_sound_effects` makes sound effects with MMAudio (large 44.1 kHz v2) from a video clip, a text prompt, or both, as a 44.1 kHz mono track. A validate's `downloads_required` lists the pinned weights: `hkchengrex/MMAudio` (the network `weights/mmaudio_large_44k_v2.pth` and Synchformer `ext_weights/synchformer_state_dict.pth`), the `audio_vae/` and `vocoder/` config and safetensors of `kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers`, and the weights and tokenizer of `apple/DFN5B-CLIP-ViT-H-14-384`. MMAudio's own `v1-44.pth` and `bigvgan_generator.pt` are never downloaded.
+
+```json
+{
+    "task": {
+        "command": "generate_sound_effects",
+        "arguments": {
+            "video": "asset:shot.mp4",
+            "prompt": "footsteps on gravel, a door creaking",
+            "negative_prompt": "music, speech"
+        }
+    },
+    "result": { "content_type": "audio/wav" }
+}
+```
+
+| Argument | Required | Description |
+| -------- | -------- | ----------- |
+| `video` | One of `video`/`prompt` | The clip the effects follow (typically an `asset:` or `previous_result:` reference) |
+| `prompt` | One of `video`/`prompt` | What should be heard |
+| `negative_prompt` | No | What to steer away from, such as `music, speech` |
+| `duration` | No | Seconds. Defaults to the clip's length, or 8 s text-only; at most 20 s and never longer than the clip |
+| `steps` | No | Sampler steps (default: 25) |
+| `guidance_scale` | No | Classifier-free guidance (default: 4.5) |
+
+Video-only is the weaker mode: give a `prompt` that names the on-screen sound sources as well. The model was trained around 8 s, so a `duration` outside 4-12 s adds a warning to the result, as does noise-like output (spectral flatness of 0.3 or more with a centroid of 8 kHz or more).
+
+Every refusal fires before anything loads: neither `video` nor `prompt`; a `duration` over 20 s or longer than the clip; an unknown argument; and `trust_remote_code`, `custom_pipeline` or `custom_generate` (the trust gate).
+
+The output runs 7-25 dB hot. Route it through `match_levels` before mixing it with dialogue or music.
+
+**Licences.** The MMAudio weights (network, Synchformer and the VAE tensors) are CC-BY-NC 4.0: non-commercial use only. The DFN5B CLIP encoder is under the Apple Machine Learning Research Model License: research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. See [ATTRIBUTIONS.md](ATTRIBUTIONS.md).
+
+**Examples:**
+
+- [video-to-sound-effects.json](../workflows/templates/video-to-sound-effects.json) — Effects that follow a clip's picture
+- [text-to-sound-effect.json](../workflows/templates/text-to-sound-effect.json) — An effect from a text prompt alone
+
 ## Speech Transcription
 
 A validate's `downloads_required` lists `openai/whisper-base`; `model_name` overrides it. `check_script` uses the same model.
diff --git a/plugins/dw/skills/kandinsky-6/SKILL.md b/plugins/dw/skills/kandinsky-6/SKILL.md
index 9432aa94..14ba2689 100644
--- a/plugins/dw/skills/kandinsky-6/SKILL.md
+++ b/plugins/dw/skills/kandinsky-6/SKILL.md
@@ -64,6 +64,8 @@ read the `workflows` guide's authoring section first.
   and keep the result's `fps` on the same variable.
 - The soundtrack is mono at 44.1 kHz, duplicated to stereo in the mp4.
   `sample_audio` false gives a silent clip and skips the audio decode.
+- To replace a shot's own sound with generated effects, run `video-to-sound-effects`
+  on the clip (MMAudio runs 7-25 dB hot: `match_levels` before mixing), then `pair_audio`.
 
 ## Prompts
 
diff --git a/plugins/dw/skills/ltx-2.5/SKILL.md b/plugins/dw/skills/ltx-2.5/SKILL.md
index d71b279d..b0d7d8e3 100644
--- a/plugins/dw/skills/ltx-2.5/SKILL.md
+++ b/plugins/dw/skills/ltx-2.5/SKILL.md
@@ -117,6 +117,7 @@ LoRAs: `list_loras` first.
 - Audio is generated in the first pass and nothing refines it, so carry the
   audio latents (two-stage) or pair the track back (`pair_audio`, as the
   `-clip` upscales do) on a frames-only step.
+- To swap a shot's sound, `video-to-sound-effects`, then `match_levels`.
 
 ## Prompts
 
diff --git a/plugins/dw/skills/series-episodes/SKILL.md b/plugins/dw/skills/series-episodes/SKILL.md
index 619b30f0..d94dbf82 100644
--- a/plugins/dw/skills/series-episodes/SKILL.md
+++ b/plugins/dw/skills/series-episodes/SKILL.md
@@ -130,6 +130,8 @@ composes into, not something to re-derive:
   mostly in `vocals`, not the rest. Separating an already-scored mix works
   too, but its rest is the score plus the shots' foley, not a clean score:
   keep the original score file to re-mix or replace it.
+- **sound effects**: `video-to-sound-effects` (or `text-to-sound-effect`) makes
+  effects for the `rest` bed; MMAudio runs 7-25 dB hot, so `match_levels` them first.
 - **normalize**: the mixed world sound and score are normalized together
   (`assemble-and-score`'s `balanced` step, -3 dBFS peak ceiling, always
   enforced), but a shared peak is not a shared loudness. Pass one series
diff --git a/tests/test_catalog_structure.py b/tests/test_catalog_structure.py
index ce2f65d6..3db07e78 100644
--- a/tests/test_catalog_structure.py
+++ b/tests/test_catalog_structure.py
@@ -299,6 +299,10 @@ def test_per_entry_problems_reports_a_mismatched_entries_count():
 # sub-workflow's argument, a step argument, a chain field or a result field.
 # One line per entry saying what the name actually is.
 LEGITIMATE_MENTIONS = {
+    # pair_audio's fit value 'video', not a variable
+    "workflows/templates/assemble-and-score.json": {"video"},
+    # the name of the sub-workflow step that makes the clip
+    "workflows/templates/best-of-n-to-video.json": {"video"},
     # attribute_voices' argument, fed the transcript rather than passed
     "workflows/templates/attribute-lines.json": {"lines"},
     # the argument the composed image-to-video workflow receives
@@ -317,8 +321,9 @@ def test_per_entry_problems_reports_a_mismatched_entries_count():
     "workflows/templates/minimax/last-frame-only.json": {"image"},
     # a 'result' field the modular pipeline needs declared
     "workflows/templates/minimax/music.json": {"sample_rate"},
-    # pair_audio's 'fit' argument, and the per-entry 'num_frames' of a shot
-    "workflows/templates/minimax/music-video.json": {"fit", "num_frames"},
+    # pair_audio's 'fit' argument and its value 'video', and the per-entry
+    # 'num_frames' of a shot
+    "workflows/templates/minimax/music-video.json": {"fit", "num_frames", "video"},
     # fields of the plan's entries, which music-video's shots then take
     "workflows/templates/minimax/music-video-cuts.json": {"num_frames", "prompt"},
     # the pipeline's 'cache' block it writes inline, not the H3 templates'
@@ -535,7 +540,10 @@ def test_no_stale_entry_in_the_allowlist():
 # Then to 12_480 for the `voice-clone` template (#1112, stage #1121,
 # 2026-11-01), measured at 12_436: one new entry, the catalog's only voice
 # clone from a reference clip and its transcript, with no cost block yet.
-COMPACT_BUDGET = 12_480
+# Then to 12_650 for `video-to-sound-effects` and `text-to-sound-effect`
+# (#1124, stage #1133, 2026-11-01), measured at 12_609: two new entries, the
+# catalog's only sound-effect generation (MMAudio), with no cost block yet.
+COMPACT_BUDGET = 12_650
 FILTERED_BUDGET = 1_500
 
 
diff --git a/tests/test_sound_effects.py b/tests/test_sound_effects.py
new file mode 100644
index 00000000..99cbeb90
--- /dev/null
+++ b/tests/test_sound_effects.py
@@ -0,0 +1,232 @@
+"""generate_sound_effects (#1124 stage D): every refusal before any load, the
+duration rules, the noise note, the run with stubbed models, the catalog
+templates and the registration."""
+
+import json
+import os
+
+import numpy
+import pytest
+import torch
+from PIL import Image
+
+from dw.media_types import AudioTrack
+from dw.security import UntrustedWorkflowError
+from dw.server.catalog_shape import derive_catalog_metadata
+from dw.tasks import sound_effects
+from dw.tasks.sound_effects import generate_sound_effects
+from dw.trust import TRUST_WORKFLOWS_ENV_VAR
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+LICENCE = (
+    "Apple Machine Learning Research Model is licensed under the Apple Machine "
+    "Learning Research Model License Agreement."
+)
+
+
+@pytest.fixture
+def no_load(monkeypatch):
+    """Any model load or download is a failure."""
+    import huggingface_hub
+
+    def refuse(*args, **kwargs):
+        raise AssertionError("a load ran before the refusal")
+
+    monkeypatch.setattr(sound_effects, "_load_models", refuse)
+    monkeypatch.setattr(huggingface_hub, "hf_hub_download", refuse)
+
+
+@pytest.fixture
+def two_second_clip(tmp_path):
+    from diffusers.utils import export_to_video
+
+    frames = [Image.new("RGB", (64, 64), (i * 5 % 256, 0, 0)) for i in range(48)]
+    path = tmp_path / "clip.mp4"
+    export_to_video(frames, str(path), fps=24)
+    return str(path)
+
+
+class TestRefusals:
+    def test_neither_video_nor_prompt(self, no_load):
+        with pytest.raises(ValueError, match="'video' or 'prompt'"):
+            generate_sound_effects()
+
+    def test_a_text_only_duration_over_20(self, no_load):
+        with pytest.raises(ValueError, match="'duration'"):
+            generate_sound_effects(prompt="rain", duration=21)
+
+    def test_a_duration_longer_than_the_clip(self, no_load, two_second_clip):
+        with pytest.raises(ValueError, match="'duration'"):
+            generate_sound_effects(video=two_second_clip, duration=3)
+
+    def test_an_unknown_argument(self, no_load):
+        with pytest.raises(ValueError, match="'foo'"):
+            generate_sound_effects(prompt="rain", foo=1)
+
+    @pytest.mark.parametrize("steps", [0, "ten", True])
+    def test_bad_steps(self, no_load, steps):
+        with pytest.raises(ValueError, match="'steps'"):
+            generate_sound_effects(prompt="rain", steps=steps)
+
+
+class TestTrustGate:
+    def test_untrusted_workflows_get_the_trust_refusal(self, monkeypatch, no_load):
+        monkeypatch.setenv(TRUST_WORKFLOWS_ENV_VAR, "0")
+        with pytest.raises(UntrustedWorkflowError):
+            generate_sound_effects(prompt="rain", trust_remote_code=True)
+
+    def test_trusted_workflows_get_a_plain_error(self, monkeypatch, no_load):
+        monkeypatch.setenv(TRUST_WORKFLOWS_ENV_VAR, "1")
+        with pytest.raises(ValueError, match="trust_remote_code") as caught:
+            generate_sound_effects(prompt="rain", trust_remote_code=True)
+        assert not isinstance(caught.value, UntrustedWorkflowError)
+
+
+class TestDuration:
+    def test_text_only_defaults_to_8(self):
+        assert sound_effects._check_duration(None, None) == 8.0
+
+    def test_a_clip_sets_it_capped_at_20(self):
+        assert sound_effects._check_duration(None, 30.0) == 20.0
+
+    def test_20_is_allowed(self):
+        assert sound_effects._check_duration(20, None) == 20.0
+
+
+class TestWarnings:
+    @pytest.fixture
+    def warnings(self, monkeypatch):
+        import dw.events
+
+        seen = []
+        monkeypatch.setattr(
+            dw.events, "emit_warning", lambda message, **kw: seen.append(message)
+        )
+        return seen
+
+    def sine(self, seconds=2):
+        t = numpy.arange(44100 * seconds) / 44100
+        return numpy.sin(2 * numpy.pi * 440 * t).astype(numpy.float32)[None]
+
+    def test_white_noise_is_noted(self, warnings):
+        noise = numpy.random.default_rng(0).standard_normal((1, 44100 * 2))
+        sound_effects._warn(noise.astype(numpy.float32), 44100, 8.0)
+        assert len(warnings) == 1
+        assert "noise-like" in warnings[0]
+
+    def test_a_sine_in_range_is_silent(self, warnings):
+        sound_effects._warn(self.sine(), 44100, 8.0)
+        assert warnings == []
+
+    def test_a_short_duration_gets_only_the_duration_note(self, warnings):
+        sound_effects._warn(self.sine(), 44100, 2.0)
+        assert len(warnings) == 1
+        assert "trained around" in warnings[0]
+
+    def test_silence_is_not_noise(self, warnings):
+        sound_effects._warn(numpy.zeros((1, 44100), dtype=numpy.float32), 44100, 8.0)
+        assert not any("noise-like" in message for message in warnings)
+
+
+class TestRunWithStubs:
+    def test_text_only_run(self, monkeypatch):
+        from dw.tasks import mmaudio_clip, mmaudio_model
+
+        class Net:
+            clip_seq_len = 64
+            sync_seq_len = 192
+            device = torch.device("cpu")
+
+            def set_duration(self, duration):
+                class Seq:
+                    num_audio_frames = 10**7
+
+                return Seq()
+
+        class Clip:
+            def encode_text(self, tokens):
+                return torch.zeros(1, 77, 4)
+
+        class Decoder:
+            sample_rate = 44100
+
+            def decode(self, latent):
+                return torch.zeros(1, 1, 44100 * 6)
+
+        monkeypatch.setattr(
+            sound_effects,
+            "_load_models",
+            lambda device, dtype: (Net(), (Clip(), "tok"), None, Decoder()),
+        )
+        monkeypatch.setattr(mmaudio_clip, "tokenize", lambda tok, texts: texts)
+        seen = {}
+
+        def fake_sample(net, **kwargs):
+            seen.update(kwargs)
+            return torch.zeros(1, 10, 40)
+
+        monkeypatch.setattr(mmaudio_model, "sample_latent", fake_sample)
+
+        result = generate_sound_effects(prompt="door slam", duration=5, seed=3)
+
+        assert isinstance(result, AudioTrack)
+        assert result.sample_rate == 44100
+        assert result.audio.shape == (1, round(5 * 44100))
+        assert isinstance(seen["generator"], torch.Generator)
+        assert seen["steps"] == 25
+        assert seen["cfg_strength"] == 4.5
+        assert seen["clip_features"] is None
+        assert seen["text_features"] is not None
+
+
+def load_template(name):
+    with open(os.path.join(ROOT, "workflows", "templates", name)) as handle:
+        return json.load(handle)
+
+
+class TestCatalog:
+    def test_video_template(self):
+        definition = load_template("video-to-sound-effects.json")
+        meta = derive_catalog_metadata(definition)
+        assert meta["shape"] == "audio"
+        assert {"has-audio", "needs-input-media"} <= set(meta["traits"])
+        commands = [step["task"]["command"] for step in definition["steps"]]
+        assert "pair_audio" in commands
+
+    def test_text_template(self):
+        meta = derive_catalog_metadata(load_template("text-to-sound-effect.json"))
+        assert meta["shape"] == "audio"
+        assert "has-audio" in meta["traits"]
+        assert "needs-input-media" not in meta["traits"]
+
+    @pytest.mark.parametrize(
+        "name", ["video-to-sound-effects.json", "text-to-sound-effect.json"]
+    )
+    def test_templates_carry_the_licences(self, name):
+        description = load_template(name)["description"]
+        assert "CC-BY-NC 4.0" in description
+        assert LICENCE in description
+
+    def test_the_command_summary_carries_the_licences(self):
+        from dw.tasks.task import task_command_info
+
+        summary = task_command_info("generate_sound_effects")["summary"]
+        assert "CC-BY-NC 4.0" in summary
+        assert LICENCE in summary
+
+
+class TestRegistration:
+    def test_it_consumes_the_device_and_declares_its_weights(self):
+        from dw.tasks.registry import _COMMAND_REGISTRY, _COMMAND_RULES
+        from dw.tasks.task import task_command_info
+
+        task_command_info("generate_sound_effects")
+        assert (
+            _COMMAND_RULES["generate_sound_effects"]["required_weights"]
+            == "dw.tasks.sound_effects.required_weights"
+        )
+        # a command that does not consume the device is wrapped to drop it
+        assert (
+            _COMMAND_REGISTRY["generate_sound_effects"].__name__
+            == "_handle_generate_sound_effects"
+        )
diff --git a/tests/test_step_cache.py b/tests/test_step_cache.py
index 3bbfdac2..cd3c2606 100644
--- a/tests/test_step_cache.py
+++ b/tests/test_step_cache.py
@@ -911,9 +911,11 @@ def test_normalized_downstream_false_when_nothing_references_it():
     "text-to-image.json": {
         "main": "4e1fd3c983134c89fd764ab8635c410b08a14947fa5a34c372b6567fca12a4d3"
     },
+    "text-to-sound-effect.json": {},
     "transcribe-audio.json": {},
     "upscale-diffusion.json": {},
     "upscale-spandrel.json": {},
+    "video-to-sound-effects.json": {},
     "voice-clone.json": {},
 }
 
diff --git a/tests/test_task_weights.py b/tests/test_task_weights.py
index a87f281a..b3127680 100644
--- a/tests/test_task_weights.py
+++ b/tests/test_task_weights.py
@@ -147,6 +147,106 @@ def test_audio8_lists_its_pinned_files_and_the_codec(self):
         assert a8.REVISION == "1e857568bfd4f02931aca3988ee773a44d2d26d3"
 
 
+class TestSoundEffects:
+    MMAUDIO = "eb13a1a98fdbec91753775c57b074ccdfc60587c"
+    K6 = "4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81"
+    DFN5B = "01b771ed0d1395ca5ffdd279897d665ebe00dfd2"
+    EXPECTED = [
+        ("hkchengrex/MMAudio", "weights/mmaudio_large_44k_v2.pth", MMAUDIO),
+        ("hkchengrex/MMAudio", "ext_weights/synchformer_state_dict.pth", MMAUDIO),
+        (
+            "kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers",
+            "audio_vae/config.json",
+            K6,
+        ),
+        (
+            "kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers",
+            "audio_vae/diffusion_pytorch_model.safetensors",
+            K6,
+        ),
+        (
+            "kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers",
+            "vocoder/config.json",
+            K6,
+        ),
+        (
+            "kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers",
+            "vocoder/diffusion_pytorch_model.safetensors",
+            K6,
+        ),
+        ("apple/DFN5B-CLIP-ViT-H-14-384", "open_clip_pytorch_model.bin", DFN5B),
+        ("apple/DFN5B-CLIP-ViT-H-14-384", "tokenizer.json", DFN5B),
+    ]
+
+    def entries(self):
+        hook = required_weights_hook("generate_sound_effects")
+        assert hook is not None
+        return hook({"prompt": "a door"})
+
+    def test_it_lists_exactly_its_pinned_files(self):
+        got = [(e["repo"], e["filename"], e["revision"]) for e in self.entries()]
+        assert got == self.EXPECTED
+
+    def test_it_never_lists_mmaudios_own_vae_or_vocoder(self):
+        names = [entry["filename"] for entry in self.entries()]
+        assert "v1-44.pth" not in names
+        assert "bigvgan_generator.pt" not in names
+
+    def test_the_loader_downloads_what_the_plan_declares(self, monkeypatch):
+        import huggingface_hub
+        import torch
+
+        from dw.tasks import (
+            mmaudio_clip,
+            mmaudio_decoder,
+            mmaudio_model,
+            mmaudio_sync_model,
+            model_cache,
+            sound_effects,
+        )
+
+        downloads = []
+
+        def fake_download(repo_id=None, filename=None, revision=None, **_):
+            downloads.append((repo_id, filename, revision))
+            return f"/fake/{repo_id}/{filename}"
+
+        monkeypatch.setattr(huggingface_hub, "hf_hub_download", fake_download)
+        monkeypatch.setattr(mmaudio_model, "load_network", lambda *a, **k: "net")
+        monkeypatch.setattr(mmaudio_clip, "load_clip", lambda *a, **k: "clip")
+        monkeypatch.setattr(mmaudio_clip, "load_clip_tokenizer", lambda *a: "tok")
+        monkeypatch.setattr(
+            mmaudio_sync_model, "load_synchformer", lambda *a, **k: "sync"
+        )
+        monkeypatch.setattr(mmaudio_decoder, "load_decoder", lambda *a, **k: "dec")
+
+        keys = []
+
+        def run_factory(key, factory):
+            keys.append(key)
+            return factory()
+
+        monkeypatch.setattr(model_cache, "cached_model", run_factory)
+
+        net, (clip, tokenizer), sync, decoder = sound_effects._load_models(
+            "cpu", torch.float32
+        )
+
+        assert (net, clip, tokenizer, sync, decoder) == (
+            "net",
+            "clip",
+            "tok",
+            "sync",
+            "dec",
+        )
+        assert sorted(downloads) == sorted(self.EXPECTED)
+        revisions = {repo: rev for repo, _, rev in self.EXPECTED}
+        assert len(keys) == 4
+        for key in keys:
+            assert key[0] == "generate_sound_effects"
+            assert revisions[key[1]] in key
+
+
 class TestVoiceAttribution:
     def test_is_only_the_speaker_embedder(self):
         assert declared("attribute_voices") == ["speechbrain/spkrec-ecapa-voxceleb"]
diff --git a/workflows/templates/text-to-sound-effect.json b/workflows/templates/text-to-sound-effect.json
index c3e68b55..a83a35ed 100644
--- a/workflows/templates/text-to-sound-effect.json
+++ b/workflows/templates/text-to-sound-effect.json
@@ -1,7 +1,7 @@
 {
   "id": "TextToSoundEffect",
   "description": "Generates a sound effect from a text prompt alone with MMAudio (large 44.1 kHz v2) and saves it as a 44.1 kHz mono wav. 'prompt' says what should be heard ('a heavy wooden door creaks open, then slams'); 'duration' is 8 s by default, at most 20 s, and the model was trained around 8 s, so it warns outside 4-12 s. The effect runs 7-25 dB hot: route it through match_levels before mixing it with dialogue or music. For effects that follow a clip's picture, use the video-to-sound-effects template. Licences: the MMAudio weights (network, Synchformer, VAE tensors) are CC-BY-NC 4.0, non-commercial; the DFN5B CLIP encoder is under the Apple Machine Learning Research Model License, research only - Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement.",
-  "summary": "A sound effect from a text prompt (MMAudio), as a 44.1 kHz mono wav.",
+  "summary": "A sound effect from a text prompt (MMAudio).",
   "variables": {
     "prompt": "a heavy wooden door creaks open, then slams shut",
     "negative_prompt": "music, speech",
diff --git a/workflows/templates/video-to-sound-effects.json b/workflows/templates/video-to-sound-effects.json
index f196324c..cdf001bb 100644
--- a/workflows/templates/video-to-sound-effects.json
+++ b/workflows/templates/video-to-sound-effects.json
@@ -1,7 +1,7 @@
 {
   "id": "VideoToSoundEffects",
   "description": "Generates sound effects for a clip with MMAudio (large 44.1 kHz v2) and muxes them under it, replacing the clip's own sound. 'video' is the clip: an 'asset:' or 'output:' ref. 'prompt' names the on-screen sound sources - what should be heard ('footsteps on wet gravel, a car door slams, distant traffic'); leave it empty only to let the picture alone drive the effects, which is the weaker mode, so a prompt is recommended. 'duration' defaults to the clip's whole length, at most 20 s; the model was trained around 8 s and warns outside 4-12 s. Outputs two files: the effects stem (a 44.1 kHz mono wav) and the clip muxed with it. The effects run 7-25 dB hot: before mixing the stem with dialogue or music, route it through match_levels. Licences: the MMAudio weights (network, Synchformer, VAE tensors) are CC-BY-NC 4.0, non-commercial; the DFN5B CLIP encoder is under the Apple Machine Learning Research Model License, research only - Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement.",
-  "summary": "Sound effects for a clip (MMAudio), muxed under it; name the on-screen sound sources in prompt.",
+  "summary": "Effects for a clip (MMAudio), muxed under it; name its sound sources in prompt.",
   "shape": "audio",
   "variables": {
     "video": "asset:clip.mp4",

From f1bfb462824228463f37704c81f2aceaee893dcd Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 14:32:15 -0600
Subject: [PATCH 120/125] docs: #1123 close-out - story-forge lessons design
 record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../complete/story-forge-lessons-complete.md  | 117 ++++++++++++++++++
 docs/proposals/todo.md                        |   9 ++
 2 files changed, 126 insertions(+)
 create mode 100644 docs/proposals/complete/story-forge-lessons-complete.md

diff --git a/docs/proposals/complete/story-forge-lessons-complete.md b/docs/proposals/complete/story-forge-lessons-complete.md
new file mode 100644
index 00000000..29ce47db
--- /dev/null
+++ b/docs/proposals/complete/story-forge-lessons-complete.md
@@ -0,0 +1,117 @@
+# Story-forge's production lessons, checked on lem (#1123)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). Plan v1 on #1123 was approved by Don on 2026-11-01 with every
+default (Q1–Q4) and one amendment of his own: the L1 89-frame remedy cell.
+v2 folded those in with no change of scope. It was built as three stages:
+#1126 (stage A), #1127 (stage B) and #1128 (stage C).
+
+The measurements, cell by cell with job ids, are in
+`docs/proposals/audits/2026-11-story-forge-lessons.md`. This record does not
+repeat them.
+
+## The idea
+
+story-forge (https://github.com/nicedreamzapp/story-forge, MIT) has shipped
+several films on LTX-2.5 and wrote down what broke in its `LESSONS.json`. The
+idea was to put the lessons that hold into the dw composition skills. It ran
+LTX-2.5 through MLX (`dgrauet/ltx-2-mlx`) on Apple Silicon, not diffusers, so
+the plan required each lesson to be measured on our pipeline before any text
+landed.
+
+## Verdict
+
+**Build smaller.** Measure lessons 1, 2, 3, 4 and 6 on lem with A/B renders
+in workspace `probe-1123`, land those that hold as skill text, and land
+lesson 5 as unmeasured guidance. Cut lesson 7 and hand lesson 8 to #1122.
+No engine, MCP, REST or syntax change, and no template default change.
+
+**Verdict rule:** a lesson holds when its failure shows in at least half the
+naive renders and its remedy removes it in at least half of the remedy
+renders. N = 2 seeds per cell (Q1).
+
+## What the plan found against the idea
+
+1. Lesson 2 can't edit the caption spec's "camera movement is expected and
+   good", because a test pins the spec verbatim to the pipeline's system
+   prompt. A static rule would have gone in the skill's *Prompts* section.
+2. Lesson 1 collides with dw's measured 401-frame single-pass
+   `image-to-video` advice, so a 401-frame cell was measured too. Don added
+   the 89-frame cell, so the measurement could tell a haze onset fixed in
+   time apart from a tail that degrades.
+3. Lesson 4 on Qwen-Image had nowhere to land (no template or skill).
+   Klein and Z-Image were measured instead.
+
+## Results
+
+| # | Lesson | Verdict (at N = 2) | Landed |
+| --- | --- | --- | --- |
+| L1 | Haze after 2–3.5 s; render at cut length plus about 0.5 s | not reproduced: 0 of 10 naive renders. No fixed-time onset, and no degraded tail at 89, 121, 241 or 401 frames | nothing; no follow-up for the 401-frame default (Q2's trigger didn't fire) |
+| L2 | i2v invents camera moves; static wording | not reproduced: 0 of 6 clear moves | nothing; `ltx-2.5` *Prompts* and `caption-spec.md` unchanged |
+| L3 | Bodies in contact fuse | not reproduced: LTX 2 of 6 (mild, handshakes), H3 0 of 2. LTX followed the "just before contact" restaging in none of 6 renders | nothing |
+| L4 | ALL-CAPS words render as signage | not reproduced: 0 of 6 Z-Image, 0 of 6 Klein | nothing |
+| L6 | Impacts break physics | not reproduced: 1 of 4 | nothing |
+| L5 | Wide shots drift hardest on identity | not measured (Q4) | guidance in `script-to-video` step 3 and `series-episodes` step 0, worded "not a measured rule" and citing the findings doc |
+| L7 | Coverage: 3+ setups per line | cut | nothing |
+| L8 | Write the beat for the viewer | handed to #1122 | #1122 shipped `beat` and `must_not` in `script-to-video`'s shot sheet, plus `references/beat-review.md` |
+
+The main finding is negative: **story-forge's LTX-2.5 lessons do not transfer
+from MLX to our diffusers pipeline**, at least not at N = 2. The two
+lessons that would have contradicted existing dw advice (L1 against 401-frame
+i2v, L2 against the caption spec) were exactly the ones that didn't
+reproduce. Copying the lessons in unverified (the rejected alternative (a))
+would have put wrong rules in two skills.
+
+## What was built
+
+### Stage A (#1126): L1 and L2 probes
+24 L1 renders (t2v 241/121/89 frames on 3 prompts, i2v 241/401/89 on one
+still) and 18 L2 renders (3 stills × 3 camera wordings × 2 seeds). It wrote
+the findings doc's L1 and L2 sections. Docs only.
+
+### Stage B (#1127): L3, L4 and L6 probes
+12 LTX contact renders plus 2 H3 `dialogue-short` hug renders, 8 impact
+renders, and 24 L4 stills (12 Z-Image, 12 Klein). Docs only.
+
+### Stage C (#1128): landing
+Lesson 5's guidance in two skills, and two short sections in the findings
+doc ("Lesson 5" and "What landed"). `TestStoryForgeLessons` in
+`tests/test_plugin_skills.py` pins the L5 wording and where it sits. It also
+pins that **no** rule exists for a lesson that wasn't reproduced: there is no
+`ltx-2.5/references/staging.md`, and none of the remedy phrases appear in the
+LTX, H3, Klein, script-to-video or series-episodes skills. Plugin-only.
+
+**Deviation:** the plan's `ltx-2.5/references/staging.md` wasn't created.
+Its only content would have been the L3 and L6 rules, and neither held.
+
+## Bounces per stage
+
+| Stage | Bounces | Why |
+| --- | --- | --- |
+| A (#1126) | 1 | The hand-off didn't reproduce the findings doc's cell table and job ids. The tester can't read the checkout, and C-F603/C-F605 need the table. It was re-handed with the table and verified. |
+| B (#1127) | 1 | Same missing table, plus the Klein half of L4 hadn't run: it needed a 40 GB model download. Don ruled it in (`spend`), the 12 Klein stills ran, and it was verified. |
+| C (#1128) | 0 | Verified by reading. No landed LTX or image rule meant no verification render. |
+
+Session cost: the stage comments name no `usage:` figures, so none are
+recorded here.
+
+## Found on the way, not fixed here
+
+- **`templates/flux3/text-to-image` OOMs at load on a 24 GB 3090** against
+  the current `main` revision of `black-forest-labs/flux-3-image-klein` (job
+  49459dc14c17), though the template's description says about 19 GB. The
+  modular pipeline has no `offload: "model"` (job 5ec3b2dcb9f5). The probes
+  ran an inline copy with the text encoder leaf-level group-offloaded, which
+  costs about 8–12 min of text encode per still. No issue was filed for it
+  at close-out.
+- A lesson for the hand-off protocol: a measurement stage's hand-off has to
+  paste the findings doc's cell table, since the tester can't read the
+  checkout. That caused both bounces.
+
+## What brings it back
+
+- **Any of L1–L4, L6:** a field report from a dw session that shows the
+  failure on our pipeline, or a larger-N probe. The findings doc's cells and
+  stored `probe-1123/*` prompts are the starting point.
+- **L7:** a field report where a cut lacked a usable alternative take.
+- **L4 on Qwen-Image:** a Qwen-Image template.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index 2501e174..c23fad34 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -37,6 +37,15 @@ remaining deferred fix is recorded in
 
 ## Shipped since the ranking
 
+- **Story-forge's production lessons, checked on lem** (#1123, stages
+  #1126-#1128), closed 2026-11-01. A/B probes in `probe-1123` found none of
+  lessons 1, 2, 3, 4 or 6 (haze, invented camera moves, contact, all-caps
+  signage, impacts) reproduced on our diffusers pipeline at N = 2, so no
+  rule landed for them. Lesson 5 (wide shots drift on identity) landed as
+  unmeasured guidance in `script-to-video` and `series-episodes`. Lesson 7
+  was cut, and lesson 8 went to #1122. Findings:
+  `audits/2026-11-story-forge-lessons.md`. Record, including the Klein
+  template OOM found on the way: `complete/story-forge-lessons-complete.md`.
 - **Phrase timing without Whisper** (#1095, stages #1104-#1105), shipped
   2026-11-01. A new JSON task, `analyze_phrases`, times sung phrases from
   centre-weighted voice-band energy with no model. `plan_cuts` takes its

From c6e674a7c3438aecbf0132e1f1f8d3a28979c1a0 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 15:33:02 -0600
Subject: [PATCH 121/125] fix(tasks): #1133 - shared argument domains and trust
 helper for generate_sound_effects

Arch review bounce: drop sound_effects' hand-rolled _number for
whole_number/real_number + check_arguments, and replace both copies of the
remote-code refusal (sound_effects, speech_generation) with one
dw.trust.refuse_unused_task_remote_code built on require_trusted_task_arguments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/tasks/sound_effects.py         | 49 +++++++------------------------
 dw/tasks/speech_generation.py     | 30 ++-----------------
 dw/trust.py                       | 20 +++++++++++++
 tests/test_security_trust_gate.py |  1 -
 tests/test_workflow_trust.py      | 25 ++++++++++++++++
 5 files changed, 57 insertions(+), 68 deletions(-)

diff --git a/dw/tasks/sound_effects.py b/dw/tasks/sound_effects.py
index 7c729f8d..807cdf48 100644
--- a/dw/tasks/sound_effects.py
+++ b/dw/tasks/sound_effects.py
@@ -29,7 +29,6 @@
 """
 
 import logging
-import math
 import os
 import tempfile
 
@@ -38,6 +37,8 @@
 
 from .. import get_device_type
 from ..media_types import AudioTrack
+from ..task_domains import check_arguments, real_number, whole_number
+from ..trust import refuse_unused_task_remote_code
 from .weights import file_entries
 
 logger = logging.getLogger("dw")
@@ -113,30 +114,6 @@ def _decoder_files():
 # ---------------------------------------------------------------- refusals
 
 
-def _refuse_remote_code(kwargs):
-    """trust_remote_code / custom_pipeline / custom_generate as a step
-    argument: the trust gate's refusal when workflows are untrusted, and a
-    plain error otherwise - this task loads no Hub code either way."""
-    from ..security import UntrustedWorkflowError
-    from ..trust import TASK_REMOTE_CODE_ARGUMENTS, workflows_are_trusted
-
-    given = [name for name in TASK_REMOTE_CODE_ARGUMENTS if kwargs.get(name)]
-    if not given:
-        return
-    names = " or ".join(map(repr, given))
-    if not workflows_are_trusted():
-        raise UntrustedWorkflowError(
-            f"Refusing to run {COMMAND}: its arguments set {names}, which "
-            "downloads and executes Python from a Hub repository, so it needs "
-            "trusted workflows - see docs/SECURITY.md. generate_sound_effects "
-            "loads no Hub code from its arguments in any case; drop it"
-        )
-    raise ValueError(
-        f"{COMMAND} takes no {names} argument - it loads no Hub code from its "
-        "arguments, so the setting would have no effect. Drop it"
-    )
-
-
 def _refuse_unknown(kwargs):
     from ..trust import TASK_REMOTE_CODE_ARGUMENTS
 
@@ -148,16 +125,6 @@ def _refuse_unknown(kwargs):
         )
 
 
-def _number(name, value, whole=False):
-    if isinstance(value, bool) or not isinstance(value, (int, float)):
-        raise ValueError(f"{COMMAND}: '{name}' must be a number, got {value!r}")
-    if not math.isfinite(value) or value <= 0:
-        raise ValueError(f"{COMMAND}: '{name}' must be positive, got {value!r}")
-    if whole and int(value) != value:
-        raise ValueError(f"{COMMAND}: '{name}' must be a whole number, got {value!r}")
-    return int(value) if whole else float(value)
-
-
 def _text(name, value):
     if value is None:
         return None
@@ -173,7 +140,8 @@ def _check_duration(duration, clip_seconds):
         if clip_seconds is None:
             return TEXT_ONLY_DURATION
         return min(clip_seconds, MAX_DURATION)
-    duration = _number("duration", duration)
+    duration = float(real_number(duration, "duration", COMMAND))
+    check_arguments(COMMAND, duration=duration)
     if duration > MAX_DURATION:
         raise ValueError(
             f"{COMMAND}: 'duration' {duration:g} s is over the {MAX_DURATION:g} s "
@@ -380,12 +348,15 @@ def generate_sound_effects(
         device: Where to run
         seed: The step/workflow seed, for a reproducible take
     """
-    _refuse_remote_code(kwargs)
+    refuse_unused_task_remote_code(COMMAND, kwargs)
     _refuse_unknown(kwargs)
     prompt = _text("prompt", prompt)
     negative_prompt = _text("negative_prompt", negative_prompt)
-    steps = _number("steps", steps, whole=True)
-    guidance_scale = float(_number("guidance_scale", guidance_scale))
+    steps = whole_number(steps, "steps", COMMAND, required=True)
+    guidance_scale = float(
+        real_number(guidance_scale, "guidance_scale", COMMAND, required=True)
+    )
+    check_arguments(COMMAND, steps=steps, guidance_scale=guidance_scale)
     if video is None and prompt is None:
         raise ValueError(
             f"{COMMAND} needs 'video' or 'prompt' (or both): there is nothing "
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index c12dd5e1..a49523f0 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -27,11 +27,9 @@
 from ..media_types import AudioTrack
 from ..dsp import resample_waveform
 from .audio_utils import load_audio
-from ..security import UntrustedWorkflowError
 from ..trust import (
-    TASK_REMOTE_CODE_ARGUMENTS,
+    refuse_unused_task_remote_code,
     require_trusted_generate_arguments,
-    workflows_are_trusted,
 )
 from . import audio8_tts_model as audio8
 from .model_cache import cached_model, hf_pipeline_placement
@@ -175,30 +173,6 @@ def _generation_settings(value, name):
     return value
 
 
-def _refuse_top_level_remote_code(kwargs):
-    """Refuse trust_remote_code / custom_pipeline / custom_generate given as
-    step arguments, for every model, before anything loads: the trust gate's
-    refusal for an untrusted workflow, and a plain error for a trusted one
-    (the task still would not use it). generate_speech reads none of them
-    there, and a kwargs task drops what it does not read, so one would
-    otherwise pass silently - looking as if it took effect (#1121 bounce)."""
-    given = [name for name in TASK_REMOTE_CODE_ARGUMENTS if kwargs.get(name)]
-    if not given:
-        return
-    names = " or ".join(map(repr, given))
-    if not workflows_are_trusted():
-        raise UntrustedWorkflowError(
-            f"Refusing to run speech_generation: its arguments set {names}, "
-            "which downloads and executes Python from a Hub repository, so it "
-            "needs trusted workflows - see docs/SECURITY.md. generate_speech "
-            "loads no Hub code from its arguments in any case; drop it"
-        )
-    raise ValueError(
-        f"generate_speech takes no {names} argument - it loads no Hub code "
-        "from its arguments, so the setting would have no effect. Drop it"
-    )
-
-
 def _audio8_dtype(device):
     # The checkpoint is bf16, which a 0.6B Qwen-style decoder keeps finite
     # where fp16 may not; MPS and CPU run it in fp32 (fp16/bf16 NaN or crawl)
@@ -474,7 +448,7 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     if messages is not None:
         _check_messages(messages)
     text_inputs = messages if messages is not None else text
-    _refuse_top_level_remote_code(kwargs)
+    refuse_unused_task_remote_code("generate_speech", kwargs)
     # Both reach model.generate() for a generative model, where
     # custom_generate / trust_remote_code download and run Hub code: refused
     # for an untrusted workflow before anything loads, as text_generation does
diff --git a/dw/trust.py b/dw/trust.py
index 1c80ba66..fef69066 100644
--- a/dw/trust.py
+++ b/dw/trust.py
@@ -363,6 +363,26 @@ def require_trusted_task_arguments(command, arguments) -> None:
         raise UntrustedWorkflowError(_remote_code_task_message(command, path, key))
 
 
+def refuse_unused_task_remote_code(command, arguments) -> None:
+    """For a kwargs task that loads no Hub code from its arguments: the trust
+    gate's refusal when untrusted, and a plain ValueError when trusted for a
+    top-level TASK_REMOTE_CODE_ARGUMENTS key it would otherwise drop
+    silently - looking as if it took effect (#1121, #1133).
+
+    Raises:
+        UntrustedWorkflowError: If untrusted and any such key is set
+        ValueError: If trusted and such a key is set at the top level
+    """
+    require_trusted_task_arguments(command, arguments)
+    given = [name for name in TASK_REMOTE_CODE_ARGUMENTS if arguments.get(name)]
+    if given:
+        names = " or ".join(map(repr, given))
+        raise ValueError(
+            f"{command} takes no {names} argument - it loads no Hub code from "
+            "its arguments, so the setting would have no effect. Drop it"
+        )
+
+
 def task_remote_code_errors(workflow_definition, source_indices=None):
     """require_trusted_task_arguments as a validate pass, over the
     substituted, expanded definition: every remote-code key in a task step's
diff --git a/tests/test_security_trust_gate.py b/tests/test_security_trust_gate.py
index b25acc68..be3ccf68 100644
--- a/tests/test_security_trust_gate.py
+++ b/tests/test_security_trust_gate.py
@@ -944,7 +944,6 @@ def test_a_top_level_remote_code_argument_is_refused_when_trusted(
         loader = MagicMock()
         monkeypatch.setattr(speech_generation, "hf_pipeline", loader)
         monkeypatch.setattr(trust, "workflows_are_trusted", lambda: True)
-        monkeypatch.setattr(speech_generation, "workflows_are_trusted", lambda: True)
         with pytest.raises(ValueError, match="takes no 'trust_remote_code'"):
             speech_generation.generate_speech(
                 "hello", device="cpu", trust_remote_code=True
diff --git a/tests/test_workflow_trust.py b/tests/test_workflow_trust.py
index 4159b973..4c2bff19 100644
--- a/tests/test_workflow_trust.py
+++ b/tests/test_workflow_trust.py
@@ -544,3 +544,28 @@ def test_every_type_and_constant_resolves(self, monkeypatch, workflow_file):
                 # Not installed here, or not a type at all - test_examples
                 # owns whether a name resolves; this owns whether it is refused
                 pass
+
+
+class TestRefuseUnusedTaskRemoteCode:
+    """dw.trust.refuse_unused_task_remote_code: the one helper the kwargs
+    tasks that load no Hub code share (#1133 arch review)."""
+
+    def test_untrusted_gets_the_gate_refusal(self, monkeypatch):
+        from dw.trust import TRUST_WORKFLOWS_ENV_VAR, refuse_unused_task_remote_code
+
+        monkeypatch.setenv(TRUST_WORKFLOWS_ENV_VAR, "0")
+        with pytest.raises(UntrustedWorkflowError, match="generate_x"):
+            refuse_unused_task_remote_code("generate_x", {"custom_pipeline": "p"})
+
+    def test_trusted_gets_a_plain_error_naming_the_argument(self, monkeypatch):
+        from dw.trust import TRUST_WORKFLOWS_ENV_VAR, refuse_unused_task_remote_code
+
+        monkeypatch.setenv(TRUST_WORKFLOWS_ENV_VAR, "1")
+        with pytest.raises(ValueError, match="'trust_remote_code'") as caught:
+            refuse_unused_task_remote_code("generate_x", {"trust_remote_code": True})
+        assert not isinstance(caught.value, UntrustedWorkflowError)
+
+    def test_nothing_set_passes(self):
+        from dw.trust import refuse_unused_task_remote_code
+
+        refuse_unused_task_remote_code("generate_x", {"trust_remote_code": False})

From db84003dec63eff25d1c7a8e616e45d2500a1b6e Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 16:05:13 -0600
Subject: [PATCH 122/125] feat(tasks): #1133 - announce generate_sound_effects
 loads, document the noise warning

Tester bounce on dd497b22:
- C-F617: each model load now emits a `loading` phase and a `log` event
  naming the repo and pinned revision, with the hub download watched by
  dw.download_watch; a cache hit emits a `log` event (cached=True).
- C-F614: get_task's summary states when the noise-like warning fires
  (flatness >= 0.3 and centroid >= 8 kHz) and that it names both values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/tasks/model_handlers.py  |  6 ++-
 dw/tasks/sound_effects.py   | 87 ++++++++++++++++++++++++++++++++-----
 tests/test_sound_effects.py | 87 +++++++++++++++++++++++++++++++++++++
 3 files changed, 168 insertions(+), 12 deletions(-)

diff --git a/dw/tasks/model_handlers.py b/dw/tasks/model_handlers.py
index 69dd985b..ca465210 100644
--- a/dw/tasks/model_handlers.py
+++ b/dw/tasks/model_handlers.py
@@ -420,7 +420,11 @@ def _handle_speech_generation(task, arguments, previous_pipelines):
         "Apple Machine Learning Research Model License (research only) - "
         "Apple Machine Learning Research Model is licensed under the Apple "
         "Machine Learning Research Model License Agreement. Its output runs "
-        "7-25 dB hot: route it through match_levels before mixing."
+        "7-25 dB hot: route it through match_levels before mixing. A result "
+        "that measures noise-like (spectral flatness >= 0.3 and centroid >= "
+        "8 kHz, usually hiss) gets a warning naming both values; the run "
+        "still succeeds. Events name each model's repo and pinned revision "
+        "as it downloads and loads."
     ),
     parameter_descriptions={
         "video": (
diff --git a/dw/tasks/sound_effects.py b/dw/tasks/sound_effects.py
index 807cdf48..848bc3c0 100644
--- a/dw/tasks/sound_effects.py
+++ b/dw/tasks/sound_effects.py
@@ -21,7 +21,9 @@
 longer than the clip. Two notes go on the result through
 `dw.events.emit_warning`: a duration outside the 4-12 s the model was
 trained around, and an output that measures noise-like (spectral flatness
->= 0.3 and centroid >= 8 kHz).
+>= 0.3 and centroid >= 8 kHz). Each model's load is announced with its
+repo and pinned revision (`_cached`): a `loading` phase, a `log` event, and
+the download watched for progress; a cache hit is a `log` event.
 
 Licences: the MMAudio weights (network, Synchformer, VAE tensors) are
 CC-BY-NC 4.0; DFN5B is under the Apple Machine Learning Research Model
@@ -235,11 +237,58 @@ def _download(repo, filename, revision):
     return hf_hub_download(repo_id=repo, filename=filename, revision=revision)
 
 
+def _cached(key, source, factory):
+    """One model through `cached_model`, announced on the run's events.
+
+    A cold load is this task's long silence (about 10 GB on first use), so it
+    says what it fetches, as a pipeline step's load does: a `loading` phase
+    naming the model, repo and revision, a `log` event carrying them as
+    fields, and the hub download watched (`dw.download_watch`) so arriving
+    bytes read as progress. A cache hit says so in a `log` event.
+
+    Args:
+        key: The `cached_model` key
+        source: (label, repo, revision)
+        factory: The zero-argument load
+
+    Returns:
+        (model, whether it was loaded now)
+    """
+    from .. import download_watch
+    from ..events import emit_log, emit_phase
+    from .model_cache import cached_model
+
+    label, repo, revision = source
+    fields = dict(command=COMMAND, model=label, repo_id=repo, revision=revision)
+    loaded = []
+
+    def load():
+        loaded.append(True)
+        emit_phase("loading", detail=f"{label} ({repo} @ {revision[:12]})")
+        emit_log(
+            f"{COMMAND}: loading {label} from {repo} @ {revision}",
+            cached=False,
+            **fields,
+        )
+        with download_watch.watch(repo):
+            return factory()
+
+    model = cached_model(key, load)
+    if not loaded:
+        emit_log(
+            f"{COMMAND}: {label} already loaded ({repo} @ {revision})",
+            cached=True,
+            **fields,
+        )
+    return model, bool(loaded)
+
+
 def _load_models(device, dtype):
     """The network, CLIP + tokenizer, Synchformer and decoder, each cached
-    under (command, repo, file, revision, device, dtype)."""
+    under (command, repo, file, revision, device, dtype) and announced by
+    `_cached`."""
+    from ..events import emit_phase
     from . import mmaudio_clip, mmaudio_decoder, mmaudio_model, mmaudio_sync_model
-    from .model_cache import cached_model
 
     repo, rev = mmaudio_model.REPO_ID, mmaudio_model.REVISION
     where = (str(device), str(dtype))
@@ -274,16 +323,32 @@ def decoder():
         logger.info(f"Loading MMAudio VAE + vocoder (K6) to {device}")
         return mmaudio_decoder.load_decoder(vae_folder, vocoder_folder, device=device)
 
-    return (
-        cached_model((COMMAND, repo, mmaudio_model.NETWORK_FILE, rev, *where), network),
-        cached_model(
-            (COMMAND, clip_repo, mmaudio_clip.CLIP_WEIGHTS_FILE, clip_rev, *where), clip
+    loads = [
+        _cached(
+            (COMMAND, repo, mmaudio_model.NETWORK_FILE, rev, *where),
+            ("MMAudio network", repo, rev),
+            network,
         ),
-        cached_model((COMMAND, repo, mmaudio_sync_model.SYNC_FILE, rev, *where), sync),
-        cached_model(
-            (COMMAND, k6_repo, "audio_vae+vocoder", k6_rev, str(device)), decoder
+        _cached(
+            (COMMAND, clip_repo, mmaudio_clip.CLIP_WEIGHTS_FILE, clip_rev, *where),
+            ("DFN5B CLIP", clip_repo, clip_rev),
+            clip,
         ),
-    )
+        _cached(
+            (COMMAND, repo, mmaudio_sync_model.SYNC_FILE, rev, *where),
+            ("Synchformer", repo, rev),
+            sync,
+        ),
+        _cached(
+            (COMMAND, k6_repo, "audio_vae+vocoder", k6_rev, str(device)),
+            ("MMAudio VAE + vocoder", k6_repo, k6_rev),
+            decoder,
+        ),
+    ]
+    if any(loaded for _, loaded in loads):
+        # Back from the loads' `loading` phase to the task's own
+        emit_phase("task", detail=COMMAND)
+    return tuple(model for model, _ in loads)
 
 
 # --------------------------------------------------------------- warnings
diff --git a/tests/test_sound_effects.py b/tests/test_sound_effects.py
index 99cbeb90..a2d670b2 100644
--- a/tests/test_sound_effects.py
+++ b/tests/test_sound_effects.py
@@ -214,6 +214,93 @@ def test_the_command_summary_carries_the_licences(self):
         assert "CC-BY-NC 4.0" in summary
         assert LICENCE in summary
 
+    def test_the_command_summary_documents_the_noise_warning(self):
+        from dw.tasks.task import task_command_info
+
+        summary = task_command_info("generate_sound_effects")["summary"]
+        assert "noise-like" in summary
+        assert "flatness >= 0.3" in summary
+        assert "8 kHz" in summary
+
+
+class TestLoadEvents:
+    """A cold load names each model's repo and pinned revision on the run's
+    events; a warm one says the models are cached (#1133 bounce)."""
+
+    @pytest.fixture
+    def events(self, monkeypatch):
+        import huggingface_hub
+
+        from dw import events as dw_events
+        from dw.tasks import (
+            mmaudio_clip,
+            mmaudio_decoder,
+            mmaudio_model,
+            mmaudio_sync_model,
+            model_cache,
+        )
+
+        monkeypatch.setattr(
+            huggingface_hub,
+            "hf_hub_download",
+            lambda repo_id=None, filename=None, revision=None, **_: (
+                f"/fake/{repo_id}/{filename}"
+            ),
+        )
+        monkeypatch.setattr(mmaudio_model, "load_network", lambda *a, **k: "net")
+        monkeypatch.setattr(mmaudio_clip, "load_clip", lambda *a, **k: "clip")
+        monkeypatch.setattr(mmaudio_clip, "load_clip_tokenizer", lambda *a: "tok")
+        monkeypatch.setattr(
+            mmaudio_sync_model, "load_synchformer", lambda *a, **k: "sync"
+        )
+        monkeypatch.setattr(mmaudio_decoder, "load_decoder", lambda *a, **k: "dec")
+        monkeypatch.setattr(model_cache, "_cache", {})
+
+        seen = []
+
+        class Recorder(dw_events.RunContext):
+            def emit(self, event_type, **data):
+                seen.append((event_type, data))
+
+        token = dw_events.activate_context(Recorder())
+        yield seen
+        dw_events.deactivate_context(token)
+
+    def revisions(self):
+        from dw.tasks import mmaudio_clip, mmaudio_decoder, mmaudio_model
+
+        return {
+            mmaudio_model.REPO_ID: mmaudio_model.REVISION,
+            mmaudio_clip.CLIP_REPO_ID: mmaudio_clip.CLIP_REVISION,
+            mmaudio_decoder.K6_REPO_ID: mmaudio_decoder.K6_REVISION,
+        }
+
+    def test_a_cold_load_names_every_repo_and_revision(self, events):
+        sound_effects._load_models("cpu", torch.float32)
+
+        logs = [data for kind, data in events if kind == "log"]
+        assert len(logs) == 4
+        assert {log["repo_id"]: log["revision"] for log in logs} == self.revisions()
+        assert all(log["cached"] is False for log in logs)
+        for log in logs:
+            assert log["repo_id"] in log["message"]
+            assert log["revision"] in log["message"]
+
+        phases = [data for kind, data in events if kind == "phase"]
+        assert [p["phase"] for p in phases] == ["loading"] * 4 + ["task"]
+        for phase in phases[:4]:
+            assert any(repo in phase["detail"] for repo in self.revisions())
+
+    def test_a_warm_load_logs_cache_hits_without_a_phase(self, events):
+        sound_effects._load_models("cpu", torch.float32)
+        events.clear()
+
+        sound_effects._load_models("cpu", torch.float32)
+
+        assert [kind for kind, _ in events] == ["log"] * 4
+        assert all(data["cached"] is True for _, data in events)
+        assert {d["repo_id"]: d["revision"] for _, d in events} == self.revisions()
+
 
 class TestRegistration:
     def test_it_consumes_the_device_and_declares_its_weights(self):

From 2d542c3f07c00c2515c0e58d4b7876a3385a5310 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 16:21:44 -0600
Subject: [PATCH 123/125] fix(tasks): #1133 - a clip's fractional length is the
 default duration, not its whole CLIP frames

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 dw/tasks/sound_effects.py   | 15 ++++--
 tests/test_sound_effects.py | 96 +++++++++++++++++++++++++++++++++++++
 2 files changed, 108 insertions(+), 3 deletions(-)

diff --git a/dw/tasks/sound_effects.py b/dw/tasks/sound_effects.py
index 848bc3c0..d7b300b3 100644
--- a/dw/tasks/sound_effects.py
+++ b/dw/tasks/sound_effects.py
@@ -202,8 +202,14 @@ def _clip_seconds(path):
 
 def _frame_tensors(path, duration):
     """The clip's CLIP frames (1, T, 3, 384, 384) in [0, 1] and Synchformer
-    frames (1, T, 3, 224, 224) in [-1, 1], and the duration both cover
-    (upstream trims to the shorter of the two)."""
+    frames (1, T, 3, 224, 224) in [-1, 1], and the duration the run uses.
+
+    That is `duration` itself whenever both samplings came back full: the
+    sequence lengths for `duration` (SequenceConfig) are exactly the
+    int(fps * duration) frames sample_frames returns, so a 2.083 s clip makes
+    2.083 s of sound, not the 2.0 s its whole CLIP frames span (upstream's
+    trim, which left a muxed cut ending in silence). Only when the clip ran
+    short of frames does it fall back to the shorter span they cover."""
     from ..media import sample_frames
     from .mmaudio_clip import ClipConfig
 
@@ -214,7 +220,10 @@ def _frame_tensors(path, duration):
             f"{COMMAND}: the clip in 'video' is too short - it needs at least "
             f"{MIN_SYNC_FRAMES / SYNC_FPS:.2f} s of frames"
         )
-    covered = min(len(clip) / CLIP_FPS, len(sync) / SYNC_FPS, duration)
+    if len(clip) == int(CLIP_FPS * duration) and len(sync) == int(SYNC_FPS * duration):
+        covered = duration
+    else:
+        covered = min(len(clip) / CLIP_FPS, len(sync) / SYNC_FPS, duration)
     clip_t = torch.from_numpy(numpy.ascontiguousarray(clip)).float().div(255.0)
     sync_t = torch.from_numpy(numpy.ascontiguousarray(sync)).float()
     return (
diff --git a/tests/test_sound_effects.py b/tests/test_sound_effects.py
index a2d670b2..7f568eec 100644
--- a/tests/test_sound_effects.py
+++ b/tests/test_sound_effects.py
@@ -179,6 +179,102 @@ def fake_sample(net, **kwargs):
         assert seen["text_features"] is not None
 
 
+@pytest.fixture
+def fractional_clip(tmp_path):
+    """50 frames at 24 fps: 2.0833 s, the tester's qa-fit fixture's shape."""
+    from diffusers.utils import export_to_video
+
+    frames = [Image.new("RGB", (64, 64), (i * 5 % 256, 0, 0)) for i in range(50)]
+    path = tmp_path / "fractional.mp4"
+    export_to_video(frames, str(path), fps=24)
+    return str(path)
+
+
+class TestClipLengthDefault:
+    """A clip's length is the default duration to the sample, fraction and all
+    (#1133 bounce, C-F620: a 2.083 s clip came back as 2.0 s of sound)."""
+
+    def test_frames_cover_the_whole_fractional_clip(self, fractional_clip):
+        from dw.tasks.mmaudio_model import SequenceConfig
+
+        seconds = sound_effects._clip_seconds(fractional_clip)
+        assert seconds == pytest.approx(50 / 24)
+        clip, sync, covered = sound_effects._frame_tensors(fractional_clip, seconds)
+        assert covered == seconds
+        seq = SequenceConfig(duration=covered)
+        assert clip.shape[1] == seq.clip_seq_len
+        # Synchformer's 16-frame segments 8 apart, 8 tokens each.
+        assert ((sync.shape[1] - 16) // 8 + 1) * 8 == seq.sync_seq_len
+
+    def test_a_clip_short_of_frames_falls_back_to_what_they_cover(
+        self, monkeypatch, fractional_clip
+    ):
+        from dw import media
+
+        real = media.sample_frames
+
+        def short(path, fps, duration, size, crop=False):
+            return real(path, fps, duration, size, crop=crop)[:-2]
+
+        monkeypatch.setattr(media, "sample_frames", short)
+        _, _, covered = sound_effects._frame_tensors(fractional_clip, 50 / 24)
+        assert covered == pytest.approx(min(14 / 8, 50 / 25))
+
+    def test_the_run_returns_the_clip_length(self, monkeypatch, fractional_clip):
+        from dw.tasks import mmaudio_clip, mmaudio_model, mmaudio_sync_model
+        from dw.tasks.mmaudio_model import SequenceConfig
+
+        class Net:
+            device = torch.device("cpu")
+
+            def set_duration(self, duration):
+                seq = SequenceConfig(duration=duration)
+                self.clip_seq_len = seq.clip_seq_len
+                self.sync_seq_len = seq.sync_seq_len
+                return seq
+
+        class Clip:
+            def encode_frames(self, frames):
+                return torch.zeros(1, frames.shape[1], 4)
+
+            def encode_text(self, tokens):
+                return torch.zeros(1, 77, 4)
+
+        class Sync(torch.nn.Module):
+            def __init__(self):
+                super().__init__()
+                self.weight = torch.nn.Parameter(torch.zeros(1))
+
+        class Decoder:
+            sample_rate = 44100
+
+            def decode(self, latent):
+                return torch.full((1, 1, 44100 * 3), 0.1)
+
+        monkeypatch.setattr(
+            sound_effects,
+            "_load_models",
+            lambda device, dtype: (Net(), (Clip(), "tok"), Sync(), Decoder()),
+        )
+        monkeypatch.setattr(mmaudio_clip, "tokenize", lambda tok, texts: texts)
+        monkeypatch.setattr(
+            mmaudio_sync_model,
+            "encode_sync_frames",
+            lambda model, frames: torch.zeros(
+                1, ((frames.shape[1] - 16) // 8 + 1) * 8, 4
+            ),
+        )
+        monkeypatch.setattr(
+            mmaudio_model, "sample_latent", lambda net, **kw: torch.zeros(1, 10, 40)
+        )
+
+        result = generate_sound_effects(
+            video=fractional_clip, prompt="a box sliding", seed=1
+        )
+
+        assert result.audio.shape == (1, round(50 / 24 * 44100))
+
+
 def load_template(name):
     with open(os.path.join(ROOT, "workflows", "templates", name)) as handle:
         return json.load(handle)

From 59b7869080f001cbe8c783480911d43cd7f985b0 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 16:29:06 -0600
Subject: [PATCH 124/125] docs(proposals): #1124 close-out - MMAudio sound
 effects design record

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../mmaudio-sound-effects-complete.md         | 224 ++++++++++++++++++
 docs/proposals/todo.md                        |   9 +
 2 files changed, 233 insertions(+)
 create mode 100644 docs/proposals/complete/mmaudio-sound-effects-complete.md

diff --git a/docs/proposals/complete/mmaudio-sound-effects-complete.md b/docs/proposals/complete/mmaudio-sound-effects-complete.md
new file mode 100644
index 00000000..90bf33a8
--- /dev/null
+++ b/docs/proposals/complete/mmaudio-sound-effects-complete.md
@@ -0,0 +1,224 @@
+# MMAudio picture-synced sound effects: `generate_sound_effects` (#1124)
+
+Written by model `claude-opus-5-5` via provider `anthropic` (close-out,
+2026-11-01). Plan v2 was approved by Don on 2026-11-01. Stage A was a
+listening gate run outside dw, and it passed. Stages #1131 (B), #1132 (C)
+and #1133 (D) were then built and verified. The plan comment on #1124 is
+the full design. This doc records what shipped against it.
+
+## The idea
+
+Sound timed to what happens on screen in a video clip, optionally guided by
+a text prompt, plus a text-only mode for one-off effects. It uses MMAudio
+`large_44k_v2` ([hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio),
+code MIT, weights CC-BY-NC 4.0). That is a flow-matching network
+conditioned on DFN5B CLIP features (8 fps, 384 px), Synchformer features
+(25 fps, 224 px) and text. K6, LTX-2.5 and H3 make their own sound, but it
+is often weak on action, and restored, upscaled, retimed or animated-still
+clips have none. Upstream depends on `open_clip_torch`, `timm`,
+`hydra-core`, `torchdiffeq` and others, so the route was to vendor and port
+it with no upstream dependencies, the same as #1112.
+
+## Decisions
+
+- **Gate first (stage A).** Don's session read upstream at
+  `974010a026c731054592d8f777218bd9d85a6c24` and found nothing blocking:
+  every inference-path `torch.load` is `weights_only=True`, and the CUDA
+  kernel build is never reached. It then ran the code once on lem GPU 1 in
+  a throwaway venv. The inputs were a K6 locomotive shot, the H3 melee
+  shot, an LTX-2.5 record lift, a silent LTX2Colorize clip and two
+  text-only effects, at seed 1124 with 25 Euler steps and CFG 4.5 in bf16.
+  Load took 17.6 s with a 5.84–5.87 GiB peak. Generation took 2–3 s per
+  5–8 s clip. The same seed gave bit-identical output. Recordings:
+  `lem:~/mmaudio-stageA/`.
+- **Verdict (Don, 2026-11-01): a clear win on all three named uses.** The
+  record lift and the locomotive were clearly better than their native
+  sound, and the melee was better. The silent clip was usable, with the
+  prompted run preferred: video only gave bells and no pigeons, and the
+  prompt brought the pigeons. The text-only door slam was usable.
+- **Q1:** the upstream run was authorized once, for stage A only.
+- **Q2:** decode with diffusers' `MMAudioVAE` / `MMAudioVocoder`, with a
+  `diffusers>=0.42.0` floor. Stage A found K6's `audio_vae/` and `vocoder/`
+  safetensors bit-identical to upstream's `v1-44.pth` + BigVGAN, so there
+  is no decoder port and no pickle load for decoding.
+- **Q3:** DFN5B's Apple ML Research Model License (research only) is
+  accepted. Both licences and the Apple notice are stated wherever a user
+  meets the model. dw never writes or ships converted weights.
+- **Q4:** warn outside 4–12 s, and refuse over 20 s.
+- **Q5:** text-only mode is in scope.
+- **The prompt is recommended even with a video.** Video-only is documented
+  as the weaker mode, and `prompt` stays optional.
+
+## What was built
+
+### Stage B, #1131: flow network, sampler, CLIP conditioning
+
+- `dw/tasks/mmaudio_model.py` (772 lines) holds the flow network, the
+  `large_44k_v2` config, `euler_sample` / `sample_latent` (our own Euler
+  loop with CFG, the empty-condition path and the negative-text path, and
+  no torchdiffeq), and `load_network`. That load is strict, uses
+  `weights_only=True`, and is pinned to `hkchengrex/MMAudio` @ `eb13a1a9`.
+- `dw/tasks/mmaudio_clip.py` (399 lines) maps DFN5B's open_clip keys onto
+  transformers `CLIPVisionModelWithProjection` / `CLIPTextModel`. The map
+  is strict, works in memory only, and reproduces `patch_clip`'s
+  normalised last hidden states. The plan's vendored-towers fallback was
+  not needed.
+- Tests: `tests/test_mmaudio_model.py`, 24 cases. They include an Euler
+  closed form, a CLIP forward checked against a plain-torch open_clip
+  reference, and pins for no Hub I/O, no forbidden imports and the module
+  being inert.
+- Deviations: there are two modules, not one, because one module came to
+  1,118 lines, over the 1,100 ratchet. ftfy is not carried (the tokenizer
+  helper still does upstream's unescape, whitespace and lowercase steps).
+
+### Stage C, #1132: Synchformer, decoder load, frame sampling, centroid
+
+- `dw/tasks/mmaudio_sync_model.py` is the Synchformer visual encoder,
+  without timm, einops or omegaconf. Its load is `weights_only=True` and
+  strict on `vfeat_extractor*`. Segmentation is 16 frames with a step of 8.
+  Its key set was checked against the real checkpoint by reading pickle
+  opcodes, never by unpickling it.
+- `dw/tasks/mmaudio_decoder.py` builds diffusers `MMAudioVAE` +
+  `MMAudioVocoder` from K6 @ `4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81`.
+  There is no pickle, key map or fuse.
+- `dw/media.py` `sample_frames` (PyAV only) and `dw/dsp.py`
+  `spectral_centroid`.
+- The `diffusers>=0.42.0` floor in `pyproject.toml`, followed by
+  `FALLBACK_RELEASE_FLOOR` in `dw/server/updater.py`.
+- `docs/ATTRIBUTIONS.md` rows (Synchformer, BigVGAN, the Synchformer
+  checkpoint, the K6 audio tensors) and a `docs/SECURITY.md` paragraph on
+  the two pickle loads.
+- Deviations:
+  - K6's `audio_vae` safetensors carries an embedded `vocoder.` copy
+    (667 tensors). The loader filters that prefix out before the strict
+    load; this is a filter, not a key map.
+  - Only the 0.42 class's own constructor arguments are passed from K6's
+    config.
+  - The VAE tensors are recorded as CC-BY-NC 4.0 per the plan, though K6's
+    card says MIT. ATTRIBUTIONS states both.
+  - The K6 pin is newer than the K6 templates' `e056a84f…`.
+  - Numerical equivalence with upstream is not tested, because no upstream
+    code ran in the build.
+
+### Stage D, #1133: the task, templates, docs, skill lines
+
+- **`generate_sound_effects`** is in `dw/tasks/sound_effects.py` and
+  registered in `model_handlers.py` with `consumes_device=True` and
+  `task.seed_for`.
+  - Arguments: `video`, `prompt`, `negative_prompt`, `duration` (the clip's
+    length, or 8 s text-only), `steps` 25 and `guidance_scale` 4.5.
+  - Output: a 44.1 kHz mono `AudioTrack`.
+  - `generate_sound_effects` is in `_LAZY_FRAME_COMMANDS`, so `video`
+    arrives as a file. An in-memory clip is written to a temporary mp4
+    first.
+- **Refusals, all before any load:** the trust gate runs first. Then:
+  neither input given; `duration` over 20 s or longer than the clip; an
+  unknown argument; a non-positive `steps`, `guidance_scale` or `duration`.
+  The number checks go through `whole_number`/`real_number` +
+  `check_arguments`.
+- **Warnings** through `emit_warning`: `duration` outside 4–12 s, and a
+  noise-like result (flatness ≥ 0.3 and centroid ≥ 8 kHz).
+- **Weights:** `required_weights` pins 8 files. They are MMAudio's network
+  and Synchformer @ `eb13a1a9…`, K6's `audio_vae/` + `vocoder/` @
+  `4c487e8b…`, and DFN5B's weights and tokenizer @ `01b771ed…`. Neither
+  `v1-44.pth` nor `bigvgan_generator.pt` is listed. Loads announce
+  themselves with phase/log events and download progress through
+  `download_watch`.
+- **Catalog:** `generate_sound_effects` is in `GENERATIVE_TASKS`. There are
+  two templates:
+  - `workflows/templates/video-to-sound-effects.json` (shape `audio`,
+    declared explicitly; `has-audio`, `needs-input-media`). It outputs the
+    stem plus a `pair_audio` mux.
+  - `workflows/templates/text-to-sound-effect.json`.
+- **Docs:** `docs/TASKS.md` *Sound Effects Generation*. Both licences and
+  the Apple notice appear in the template descriptions, `get_task`,
+  `TASKS.md` and `ATTRIBUTIONS.md`.
+- **Plugin:** skill lines in `series-episodes` (effects in the `rest` bed),
+  `ltx-2.5` and `kandinsky-6` (replacing a shot's own sound). Each one
+  routes through `match_levels`, because MMAudio runs 7–25 dB hot.
+  `minimax-h3` is untouched.
+- Test edits outside the plan: `COMPACT_BUDGET` was raised from 12,480 to
+  12,650 tokens. Three templates whose quoted `'video'` now reads as a
+  variable mention were added to `LEGITIMATE_MENTIONS`. `test_step_cache`
+  got rows for both templates.
+
+### Bounce fixes (D)
+
+1. **Architecture review.** `_number` hand-rolled numeric coercion that
+   belonged to `dw/task_domains.py`, and `_refuse_remote_code` copied the
+   trust gate. The trust-gate copy came from `generate_speech` (#1121).
+   Both copies are gone. The new `dw.trust.refuse_unused_task_remote_code`
+   delegates to `require_trusted_task_arguments` and is used by both tasks.
+2. **Tester (C-F614, C-F617).** `get_task` didn't document the noise
+   warning. A cold run fetched about 10.5 GB of weights with no download
+   or load event, only `phase_stall` for about 645 s. The summary now
+   documents the warning, and a `_cached` helper emits phase and log
+   events plus `download_watch` progress for each load.
+3. **Tester (C-F620 arm 1).** On a 2.083 s clip, the clip-length default
+   rounded down to whole CLIP frames (2.0 s), and the mux padded 0.08 s of
+   silence. The default is now the clip's fractional length.
+
+## Verification
+
+Over MCP on lem.
+- B: C-F612 passed (no MCP-visible change).
+- C: C-F613 passed. The tester flagged at spec time that lem's
+  `0.42.0.dev0` would sort below the `>=0.42.0` floor. The stage verified
+  on the deployed install.
+- D: C-F614 to C-F622, SE-F058 and SE-F059 all pass, at develop
+  `e6864b3f`. In the prompted melee run, the stem was 8.0 s, 44.1 kHz
+  mono, and non-silent at a mean of −24.2 dB, against the clip's own
+  −41.6. The mux was 192 frames.
+- C-F617 step 3 (onsets within 0.2 s of visible hits) was **inconclusive**,
+  not passed. The melee clip is a continuous scrum, so no single strike
+  could be told apart at 320 px, and `measure_sync` wasn't run.
+- C-F623 (mps) was conditional on a mini-ai target being in scope.
+
+## Bounces per stage
+
+| Stage | Bounces | Why |
+|---|---|---|
+| A | — | Not dw code; Don's session. |
+| B (#1131) | 0 | |
+| C (#1132) | 0 | |
+| D (#1133) | 3 | One arch review: numeric coercion and trust-gate copies. Two tester verifies: C-F614 and C-F617, then C-F620 arm 1. All are above. |
+
+Cost per stage: the stage comments carry no `usage:` figures, so cost is
+left out. The plan estimated B at $8–12, C at $4–7 and D at $5–8. Stage A
+cost no agent spend.
+
+## Not built, and why
+
+- MMAudio checkpoints other than `large_44k_v2`, training, chunking past
+  20 s, music and dialogue: non-goals.
+- Mixing policy stays with the skills (`match_levels`), not the task.
+- No H3 line: `minimax-h3/SKILL.md` had no room, and no reference line was
+  needed for the named uses.
+
+## Known edges
+
+- **Picture sync on a clear single hit is unmeasured over MCP** (C-F617
+  step 3, above). Stage A's listening verdict is the evidence.
+- **The noise threshold has never fired on a dw output.** It is set from
+  story-forge's one hiss case (0.45 / 10.7 kHz). All of stage A's outputs
+  had flatness ≤ 0.019.
+- **Output runs hot.** Verify runs peaked at −0.31 to +0.0 dBFS, and
+  `audio_no_headroom` fired. The skills route through `match_levels`, but
+  a direct mux of the stem keeps the level.
+- **The weights are non-commercial:** CC-BY-NC 4.0 for MMAudio and Apple
+  AMLR (research only) for DFN5B. They are dw's first.
+- **mps is unverified.** It runs fp32 by default.
+- **The K6 audio pin (`4c487e8b`) differs from the K6 templates'
+  (`e056a84f`).** That means two snapshots in the cache if both are used.
+- **The arch reviewers noted that `docs/ARCHITECTURE.md` has no rows for
+  the task-argument remote-code gate, `download_watch` or `model_cache`.**
+  This is left for a curator pass.
+
+## Reopen triggers
+
+- A diffusers MMAudio pipeline lands: the vendored modules could shrink to
+  a pin.
+- A newer MMAudio checkpoint or upstream commit: re-review the code before
+  moving `REVISION`.
+- A dw output comes back as hiss without the warning firing: re-measure
+  the threshold.
diff --git a/docs/proposals/todo.md b/docs/proposals/todo.md
index c23fad34..39bb0b9c 100644
--- a/docs/proposals/todo.md
+++ b/docs/proposals/todo.md
@@ -37,6 +37,15 @@ remaining deferred fix is recorded in
 
 ## Shipped since the ranking
 
+- **MMAudio picture-synced sound effects** (#1124, stages #1131-#1133),
+  shipped 2026-11-01. It followed a listening gate in which Don heard a
+  clear win on replacing a shot's own sound, on silent clips and on
+  text-only effects. A new task, `generate_sound_effects`, is a vendored
+  port with no upstream dependencies: the flow network, the DFN5B CLIP key
+  map and Synchformer, with K6's safetensors as the decoder. Its weights
+  are pinned and CC-BY-NC 4.0 / Apple AMLR. Templates:
+  `video-to-sound-effects` and `text-to-sound-effect`. Record, including
+  the known edges: `complete/mmaudio-sound-effects-complete.md`.
 - **Story-forge's production lessons, checked on lem** (#1123, stages
   #1126-#1128), closed 2026-11-01. A/B probes in `probe-1123` found none of
   lessons 1, 2, 3, 4 or 6 (haze, invented camera moves, contact, all-caps

From 894395285efdf68c4557031e96946a2371a4c0b6 Mon Sep 17 00:00:00 2001
From: Don Kackman <dkackman@gmail.com>
Date: Sun, 1 Nov 2026 17:26:52 -0600
Subject: [PATCH 125/125] release prep 0.17.0: ratchet back to green, review
 fixes, H3 skill routes

Architecture ratchet (develop CI red on this alone since 2026-10-31):
- modules 226 -> 236: the rise is the release's new task modules
  (sound_effects, mmaudio_decoder, phrases, ...) plus five companion
  splits made here so every other metric holds - media.py ->
  media_readers.py (frame readers), cuts.py -> cuts_lines.py (line
  timing), script_check.py -> script_findings.py (rules and finding
  builders), pipeline.py -> pipeline_outputs.py (post-call output
  helpers), and h3_mask.py -> h3_mask_cells.py (mask arithmetic), which
  also closes the h3_mask <-> h3_mask_steps import cycle.
- modules_over_size_ceiling 5 -> 0: the four splits above, and the
  upstream model ports (audio8_tts_model, mmaudio_model,
  mmaudio_sync_model, mmaudio_clip) moved to dw/vendored/, excluded from
  the ruler like dw/community_pipelines/ - a port keeps upstream's shape.
- functions_over_150_lines 3 -> 0 (plan_cuts, crop_face_track,
  generate_speech), complex_functions 3 -> 2 (_collect_sources).

Release review fixes (four code reviews of v0.16.0..HEAD):
- generate_sound_effects refuses a duration under 0.64 s before any model
  loads (it crashed after a 10 GB load), unlinks its temp mp4 when the
  export fails; the decoder docstring says latents are raw.
- Audio8 reference_audio accepts an earlier audio step's output.
- H3 regional edit: a source_video off the 17n + 5 grid is refused at
  validate and the call (the pipeline snapped it up over a padded source
  and the mask drifted); refine_sigmas must be finite and strictly
  decreasing as float32, the scheduler's precision.
- check_script: a short shot a block covers whole is folded into its
  neighbour, not dropped; a shot-less unheard line's skip names no shot.
- decode_slow warning states the measurement, not a cause (#1119 rule).
- exact_frame_rate never returns 0 for a tiny rate.

Skills: minimax-h3 routes past-768p latent refine and refine_sigmas
(quality-and-speed.md) and replacing a shot's sound; SKILL.md stays
under its 12 KiB cap. Map rows, guide and TASKS.md updated; 0.17.0 notes
drafted in docs/RELEASING.md.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 docs/ARCHITECTURE.md                          |   7 +-
 docs/ATTRIBUTIONS.md                          |  12 +-
 docs/RELEASING.md                             | 130 ++++
 docs/SECURITY.md                              |   4 +-
 docs/TASKS.md                                 |   6 +-
 docs/WORKFLOW_GUIDE.md                        |   6 +
 docs/stabilization/baseline.json              |   2 +-
 dw/media.py                                   | 420 +-----------
 dw/media_readers.py                           | 410 ++++++++++++
 dw/pipeline_processors/h3_mask.py             |  85 +--
 dw/pipeline_processors/h3_mask_cells.py       |  92 +++
 dw/pipeline_processors/h3_mask_steps.py       |   2 +-
 dw/pipeline_processors/h3_rules.py            |  29 +-
 dw/pipeline_processors/pipeline.py            | 138 +---
 dw/pipeline_processors/pipeline_outputs.py    | 144 ++++
 dw/pipeline_processors/timing.py              |  21 +-
 dw/plan_downloads.py                          |  50 +-
 dw/tasks/cuts.py                              | 520 +++------------
 dw/tasks/cuts_lines.py                        | 380 +++++++++++
 dw/tasks/face_track.py                        | 108 +--
 dw/tasks/mmaudio_decoder.py                   |   5 +-
 dw/tasks/script_check.py                      | 622 ++----------------
 dw/tasks/script_findings.py                   | 580 ++++++++++++++++
 dw/tasks/sound_effects.py                     |  41 +-
 dw/tasks/speech_generation.py                 | 105 +--
 dw/vendored/__init__.py                       |  11 +
 dw/{tasks => vendored}/audio8_tts_model.py    |   2 +-
 dw/{tasks => vendored}/mmaudio_clip.py        |   2 +-
 dw/{tasks => vendored}/mmaudio_model.py       |   2 +-
 dw/{tasks => vendored}/mmaudio_sync_model.py  |   0
 dw/writers.py                                 |   2 +-
 plugins/dw/skills/minimax-h3/SKILL.md         |  38 +-
 .../references/quality-and-speed.md           |  18 +
 scripts/arch_metrics.py                       |  15 +-
 tests/test_arch_metrics.py                    |  11 +
 tests/test_audio8_tts_model.py                |   2 +-
 tests/test_fractional_fps.py                  |   7 +
 tests/test_h3_mask.py                         |  51 +-
 tests/test_h3_refine.py                       |  12 +
 tests/test_media_frames.py                    |   2 +-
 tests/test_media_layering.py                  |   4 +-
 tests/test_mmaudio_model.py                   |  18 +-
 tests/test_mmaudio_sync_model.py              |  14 +-
 tests/test_plugin_skills.py                   |   4 +-
 tests/test_script_check.py                    |  24 +
 tests/test_sound_effects.py                   |  29 +-
 tests/test_speech_generation.py               |   2 +-
 tests/test_task_weights.py                    |  14 +-
 48 files changed, 2398 insertions(+), 1805 deletions(-)
 create mode 100644 dw/media_readers.py
 create mode 100644 dw/pipeline_processors/h3_mask_cells.py
 create mode 100644 dw/pipeline_processors/pipeline_outputs.py
 create mode 100644 dw/tasks/cuts_lines.py
 create mode 100644 dw/tasks/script_findings.py
 create mode 100644 dw/vendored/__init__.py
 rename dw/{tasks => vendored}/audio8_tts_model.py (99%)
 rename dw/{tasks => vendored}/mmaudio_clip.py (99%)
 rename dw/{tasks => vendored}/mmaudio_model.py (99%)
 rename dw/{tasks => vendored}/mmaudio_sync_model.py (100%)

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index fe14df8a..15023b2d 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -33,6 +33,7 @@ one to open.
 | Step progress | `dw/pipeline_processors/progress.py`: `reported_progress_bars` | A pipeline with no step callback reports its denoise steps through its progress bars. | `tests/test_modular_progress.py::test_every_advance_of_the_bar_is_reported` |
 | Step timing | `dw/pipeline_processors/timing.py`: `StepTimer`, `step_timer`, `timed_step`, `mark` | Only a pipeline step that ran is timed, on the worker's monotonic clock: `step_timer` opens a `StepTimer` for a step with a `pipeline` or `pipeline_reference` and None for any other, which also hides an outer step's timer from a composed child. Load, call, denoise start, each pass and save reach the open timer through `mark`, and nowhere else. Denoise start is never taken inside a compiled region: a whole-compiled denoiser (`_compiled_call_impl` set) has that callable wrapped for the call instead of a forward pre-hook, which `fullgraph: true` cannot trace. A span with a missing mark is null, never guessed. `record_step` puts the reading on the step's manifest entry and `step_end`, and a reused step gets no `timing`. A chain sums its pipeline calls into one `timing` with `segments: N`. `ManifestEntry.timing` declares the shape (`docs/WORKSPACES.md` *Step timing*). | `tests/test_step_timing.py::test_a_missing_denoise_start_nulls_encode_and_first_pass`, `tests/test_step_timing.py::test_a_reused_step_carries_no_timing_even_when_one_is_passed`, `tests/test_step_timing.py::test_a_chain_sums_its_segments_and_takes_one_median_over_both`, `tests/test_step_timing.py::test_a_task_step_run_through_the_step_loop_has_no_timing`, `tests/test_step_timing.py::test_the_denoise_hook_marks_the_first_forward_once_and_removes_itself`, `tests/test_step_timing.py::test_a_fullgraph_compiled_denoiser_runs_and_still_gets_the_start_mark` |
 | Step-cache skip counts | `dw/pipeline_processors/timing.py`: `CacheCounter`, `counting_forwards`, `report_cache_stats`, `StepTimer.cache_counted`; `dw/pipeline_processors/components.py`: `stateful_cache_context`; `dw/pipeline_processors/mag_calibration.py`: `get_cache_transformer`, `captured_mag_calibration` | For `first_block` and `mag`, a forward hook on the cache transformer counts computed or skipped once per forward, reading the leader hook's `should_compute` inside the cond/uncond `cache_context` the pipeline opened, so classifier-free guidance counts both forwards. `stateful_cache_context` registers the hook for one pipeline call; its `finally` emits `cache_stats` before `_reset_stateful_cache()` and removes the hook after the event. Private diffusers state that has moved gives null counts and one `cache_stats_unavailable` warning, and never fails the run; `taylorseer`, `faster` and `text_kv` report type and config only, with no warning. The denoiser a cache attaches to (`get_cache_transformer`) and the MagCache calibration capture (`captured_mag_calibration`, the end-of-run log record turned into `cache_stats`-side job events, #891/#927) live in `mag_calibration.py`, which `components.py` imports and re-exports for `pipeline.py`, never the reverse. The counts reach the step's `timing.cache` only through `StepTimer.cache_counted`; a chain sums its calls' counts, and a null in any call nulls the sum. A step with no `cache` has no `cache` key and no event (`docs/ACCELERATION.md` *Reading the skip counts*). | `tests/test_cache_stats.py::test_cfg_counts_two_forwards_per_step_and_they_add_up`, `tests/test_cache_stats.py::test_the_event_names_the_step_and_segment_and_goes_out_before_the_reset`, `tests/test_cache_stats.py::test_moved_hook_state_nulls_the_counts_warns_once_and_the_run_finishes`, `tests/test_cache_stats.py::test_the_private_diffusers_names_are_where_the_counter_reads_them`, `tests/test_cache_stats.py::test_the_timer_sums_counts_and_nulls_on_any_null`, `tests/test_cache_stats.py::test_types_without_a_decision_report_type_only_and_no_warning` |
+| Vendored model ports | `dw/vendored/` (`audio8_tts_model.py`, `mmaudio_model.py`, `mmaudio_sync_model.py`, `mmaudio_clip.py`) | Upstream model code dw carries is one module per port, pinned to the commit or Hub revision its docstring names, so it can be diffed against its source and re-pinned as a unit; a port reaches dw only for the validated media loaders and is imported only by the task that runs it. Like `dw/community_pipelines/`, the package is outside the architecture ratchet (`EXCLUDED` in `scripts/arch_metrics.py`): a port keeps upstream's shape, which the module and function ceilings are not written for. | `tests/test_arch_metrics.py::test_vendored_model_ports_are_not_counted`, `tests/test_mmaudio_model.py::test_modules_are_imported_only_by_the_sound_effects_task`, `tests/test_mmaudio_sync_model.py::test_module_is_imported_only_by_the_sound_effects_task` |
 | Community pipelines | `dw/community_pipelines/` (e.g. `pipeline_ltx2_refine.py`: `LTX2RefinePipeline`), `dw/introspection.py`: `community_pipelines`, `load_allowed_class` | A pipeline dw ships is named by its dotted path (`dw.community_pipelines.<module>.<Class>`), loads untrusted because it is under `dw`, and is listed by `list_pipelines` and resolved by `get_pipeline_signature` - only the modules in that directory, never a caller-chosen import. `LTX2RefinePipeline` VAE-encodes `video` at `width` x `height` and passes it unnormalized as `latents`, because `LTX2Pipeline.prepare_latents` normalizes 5-D latents itself. | `tests/test_ltx2_refine_pipeline.py::TestIntrospection::test_only_the_shipped_modules_resolve`, `tests/test_ltx2_refine_pipeline.py::TestEncode::test_the_latents_are_left_unnormalized_for_the_parent` |
 | Adding a task | `dw/tasks/registry.py`: `register_command`, `RegistryTable` | A task is a function registered with `@register_command`, and the signature of its implementation is its argument schema. Its validate-time rules are declared on the same decorator - `domains`, `choices`, `static_check`, `whole_numbers` and `media_arguments` - and `TASK_ARGUMENT_DOMAINS`, `TASK_ARGUMENT_CHOICES`, `TASK_STATIC_CHECKS`, `TASK_WHOLE_NUMBER_ARGUMENTS` and `TASK_MEDIA_ARGUMENTS` are read-only views derived from them, so there is no second table to forget (#692). The registry lives in `dw/tasks/registry.py`; `dw/tasks/task.py` re-exports it, and a task module may register its own handler, as `dw/tasks/beats.py` does, provided `dw/tasks/task.py` imports it (`docs/TASKS.md` *Adding a task*). The built-in handlers are grouped by family the same way - `dw/tasks/audio_handlers.py`, `dw/tasks/video_handlers.py`, `dw/tasks/finish_handlers.py` and `dw/tasks/model_handlers.py` (#790) - and `dw/tasks/task.py` keeps the general-purpose commands, the processor dispatch and `Task`. | `tests/test_task_discovery.py::TestDescribeTask::test_signature_becomes_the_schema`, `tests/test_task_registry_rules.py::test_every_derived_table_is_the_registrys_view`, `tests/test_task_registry_rules.py::test_every_static_check_is_registered_to_exactly_one_command`, `tests/test_task_registry_rules.py::test_every_media_argument_is_a_parameter_of_its_command` |
 | Task argument domains | `dw/task_domains.py`: `check_arguments`, `task_argument_errors`; `dw/task_problems.py`: `face_track_errors`, `beats_errors`, `cuts_errors`, `lut_errors` | A numeric domain that a signature cannot express is declared on the command's `@register_command(domains=...)`, and it is checked at validation and again at run time. A numeric argument is read by `whole_number` or `real_number`, the only numeric coercion in `dw/tasks/`, and validation applies the same rule (`number_problem`), so a value is refused at both or at neither: `"3.0"` is a whole number, `"3.5"` for one of `whole_numbers` is not, and `true` is no number (#774). `Task.run` coerces every declared argument through `coerce_arguments` before dispatch, so a handler sees a number, and an argument that has no range besides being a number declares `finite`. A command's cross-argument rules are its registered `static_check`, which `task_argument_errors` runs at validation (`attribute_voices`' `voices_argument_errors`, kept in `dw/tasks/voice_attribution.py`, among them). A literal enum choice (`choice_errors`) is refused at validation by the same module. The per-family rules past a single domain live in `dw/task_problems.py`, which reads `task_domains`' helpers and is never imported by it (`task_argument_errors` reaches them only through the registered `static_check`, so `import_cycles` stays 0; #790): the `ingredients_grid` image count against `max_images` (`ingredients_grid_errors`), and `crop_face_track`'s cross-argument rules (`face_track_problems`, `face_track_errors`: crop size a multiple of the step's `multiple` (32 by default), `remainder` below `modulus`, `gate_zero` above `gate_full`, `max_frames` at or above `min_frames`, padding and confidence limits), which the task checks again at run time, as `analyze_beats`' are too (`beats_problems`, `beats_errors`: `min_bpm` below `max_bpm`, and anchors that are one kind per list, ascending, with whole beat indexes; `tests/test_analyze_beats.py`), and `plan_cuts`' (`cuts_problems`, `cuts_errors`: a bare-string transcript (`transcript_problem`, which `plan_cuts` also calls at run time), `min_scene_s` above `max_scene_s`, `segment_by: "beat"` without beats), and `apply_lut`'s (`lut_source_problem`, `palette_problem`, `lut_errors`: exactly one of `lut` or `palette`, and a palette of 2..16 `#rrggbb` colours, re-checked at run time by `check_lut_source`), and `check_face_detector_source` vets its Hub repo and `.onnx` file before any download. `select`'s index stays in `task_domains` with the other media-timing rules (`select_index_problem`, `select_rule_problems`: a whole number, at least 0, and below the candidate count when the count is known, i.e. at run time or when `candidates` is a written list). | `tests/test_task_domains.py::TestTheStaticPass::test_a_negative_frame_count_is_refused_at_its_path`, `tests/test_numeric_coercion.py::TestGradeExposure::test_a_string_number_grades_like_the_number`, `tests/test_task_domains.py::TestAtRunTime::test_slice_audio_refuses_a_negative_count`, `tests/test_ingredients_grid.py::TestStaticValidation::test_bad_layout_and_fit`, `tests/test_face_track.py::TestStaticValidation::test_bad_literal_is_an_error_at_its_argument`, `tests/test_face_track.py::TestCropFaceTrack::test_bad_arguments_are_refused_at_run_time`, `tests/test_face_track.py::TestStaticValidation::test_a_declared_grid_is_accepted`, `tests/test_face_track.py::TestDetectorSource::test_traversing_repo_is_refused`, `tests/test_select_validation.py::TestSelectErrors::test_an_out_of_range_literal_index_names_both_ends`, `tests/test_lut.py::TestPaletteAtValidate::test_both_refuse_naming_the_two`, `tests/test_lut.py::TestPalette::test_a_bad_palette_refuses_naming_the_entry` |
@@ -113,7 +114,7 @@ one to open.
 | Acceleration warnings | `dw/acceleration_warnings.py`: `acceleration_warnings`, `CACHE_MIN_USEFUL_STEPS`, `CUDA_ONLY_ATTENTION_BACKENDS` (the last entry of `WARNING_CHECKS`) | An acceleration setting that can't pay off (a `first_block`/`mag` cache under `CACHE_MIN_USEFUL_STEPS`, any `taylorseer` cache, `compile.fullgraph` with a cache, a cache on a pipeline class with no transformer or whose transformer lacks `enable_cache()`, a CUDA-only `attention_backend` on a non-CUDA device) is a warning and never a refusal, and an unresolvable value (steps, backend, device) leaves it silent. | `tests/test_validation.py::TestAccelerationWarnings::test_warnings_never_refuse`, `tests/test_validation.py::TestAccelerationWarnings::test_steps_that_resolve_to_nothing_are_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unknown_device_is_silent`, `tests/test_validation.py::TestAccelerationWarnings::test_an_unresolvable_backend_is_silent_on_mps` |
 | H3 sparse attention | `dw/sparse_attention.py`: `sparse_call`, `install_sparse`, `install_sparse_for_call`, `apply_sparse_settings`, `SparseH3AttnProcessor`; wired from `dw/pipeline_processors/components.py`: `configure_components` and `dw/pipeline_processors/pipeline.py`: `apply_runtime_settings` | Whether a pipeline call runs sparse is decided once per call, all or nothing (the call's first kernel invocation included); it never changes diffusers' process-wide backend and never reaches `AttentionBackendName`; it installs by a processor swap plus forward hooks, never a `forward` wrapper; and `sparse_tau` is a runtime setting, not part of the weights identity (#931). | `tests/test_sparse_attention_processor.py`, `tests/test_sparse_attention_wiring.py`, `tests/test_sparse_attention_tiles.py`, `tests/test_sparse_attention_backends.py` |
 | H3 adapter partition | `dw/adapter_compatibility.py`; the server's index is `dw/server/deps.py` `lora_index` | The LoRA catalog decides first, on the server only: a `proven` entry's `workflow` refuses a step in the other partition, a `trial`/`rejected` entry's only warns. A file no entry places falls to its name: an FL2VA LoRA on a reference step is refused, and one whose name says neither `ref2v` nor `fl2v` is warned. | `tests/test_h3_adapters.py::TestWhatIsRefused::test_a_keyframe_adapter_on_the_reference_path`, `tests/test_h3_adapters.py::TestWhatIsRefused::test_an_unrecognised_name_is_a_warning_not_a_refusal`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_proven_entry_refuses_the_other_partition`, `tests/test_h3_adapters.py::TestTheCatalogDecidesFirst::test_a_weaker_entry_only_warns`, `tests/test_server_loras.py::TestTheCatalogPlacesAnAdapter::test_a_trial_entry_warns_and_promoting_it_refuses` |
-| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` and the explicit `refine_sigmas` schedule among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then), `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`, and `explicit_sigmas`, a step's `refine_sigmas` list run verbatim in place of the shift grid) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_refine.py::TestSigmaListOneOwner::test_the_runtime_message_is_the_owners`, `tests/test_h3_refine.py::TestSigmaListSchedule::test_the_block_runs_the_list_unshifted`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
+| H3 audio hold, refine, tiled refine, guide layout and regional edit | Nine modules, imported one way: `dw/pipeline_processors/h3_rules.py` holds the names and rules, torch- and diffusers-free (`refine_problems`, the per-argument refine rules, `refine_tiles` and the explicit `refine_sigmas` schedule among them, asked before validation and before the call; `tile_plan`, the tile layout on the 32 px grid, shared by validate and the run; `not_h3`, the step rule; `snap_guide_length`, `guide_frame_problem`, `guide_chain_problems`, `guide_end_problem`; `CHAIN_CONTINUITY_MODES`; the chunk constants; and the regional-edit rules `mask_problems`, `media_problems` and `edits_region`, the argument rules shared by validate and `_with_mask`; `media_problems` is asked by validate too, on the files that resolve then, and refuses a `source_video` off the `17n + 5` grid, which the pipeline would otherwise snap up over a padded source), `dw/pipeline_processors/h3_mask_cells.py` holds the mask-to-rows arithmetic (`binarized`, `regenerate_cells`, `keep_rows`), which `h3_mask.py` re-exports and `h3_mask_steps.py` reads from there so the blocks never import their importer, `dw/pipeline_processors/h3_hold.py` puts the hold and refine blocks in (`insert_audio_hold`, `core_denoise_sequences`, `refines`; `HELD_LATENTS_OUTPUT` and `encoded_hold_audio`, the hold block's encode handed back to it), and `dw/pipeline_processors/h3_guides.py` the guide layout (`LAYOUT_ANCHORS`, `insert_guides`), which imports `h3_hold` and never the reverse, and `dw/pipeline_processors/h3_mask.py` the regional edit (`insert_mask_blocks`, `edits_regions`, and the mask-to-rows arithmetic `binarized`, `regenerate_cells` and `keep_rows`, on Pillow's L conversion, torch's adaptive max pool and scipy's dilation, each imported where it runs), which imports `h3_hold` and never the reverse; the blocks themselves, and the arithmetic they run, are `dw/pipeline_processors/h3_hold_steps.py` (`encode_audio_span`, `refine_sigmas`, and `explicit_sigmas`, a step's `refine_sigmas` list run verbatim in place of the shift grid) `dw/pipeline_processors/h3_guide_steps.py` (`splice_guide_rows`) and `dw/pipeline_processors/h3_mask_steps.py` (the source-latents and mask-blend blocks), which import diffusers when they load, so the three owners import them only inside `blocks()`, `guide_blocks()` and `h3_mask.blocks()` (#790), and `h3_guide_steps` imports `h3_hold_steps` and never the reverse (`_with_guides` in `dw/pipeline_processors/pipeline.py` adds its blocks for a `guides` call, and `_with_mask` checks a regional edit's arguments and media and builds the regenerate mask for a `source_video` call), `dw/guides.py`: the `guides` validation check and the chain `continuity: "guide"` check, `guide_chain_errors`, which asks the `guides` check's own step rule (`_takes_guides_problem`, built on `h3_rules.not_h3` and `REFERENCE_WORKFLOWS`) and reads the mode names from `h3_rules.CHAIN_CONTINUITY_MODES`, the names `chain.py`'s `CONTINUITY_MODES` is zipped against (both registered in `dw/validation.py`; a `previous_result:` guide is checked at run time), `dw/pipeline_processors/h3_tiles.py`: the tiled refine (the tile loop, the latent-space feather blend, the per-tile crop of one whole-canvas noise draw, the decode-free graph variant, and the one spatially tiled decode), which imports `h3_rules`, `h3_hold` and `media_types` (for `FrameList`; and `events`, `progress`) and is imported by `pipeline.py` and, lazily, `components.py` (which attaches the variant at load, behind `h3_hold.core_denoise_sequences`, and calls `insert_mask_blocks` at load), never by `h3_rules` or `h3_hold`, `dw/hold_audio.py`: `hold_audio_errors` (a video is held by its soundtrack), `refine_strength_errors`, `mask_errors` (Check `regional_edit`, which probes the source and mask through `ValidationContext.probe` the way `dw/guides.py` probes guide videos) | The one place dw modifies a diffusers modular pipeline's block graph: three blocks go in, before `set_timesteps`, `denoise` and `after_denoise`, in every H3 core-denoise sequence (the whole graph and the `workflow=`-pruned flat graph), and two more for a regional edit: the source block before `set_timesteps` and the blend block inside the `denoise` loop after `update`. All are no-ops without their arguments (`hold_audio` / `refine_strength`, `source_video`). The tiled refine adds a second graph built at load beside them (`h3_tiles.decode_free_blocks`: the decode and text-encoder blocks dropped, every kept block the graph's own instance, so hold and refine stay in) and swaps it into `pipeline._blocks` only for the duration of the one text-encode call and the tile calls (`swapped_blocks`, restored on failure). Every tile runs the hold block, but the track is encoded once per refine: the first tile is asked for the block's encode (`HELD_LATENTS_OUTPUT`) and every later tile's `hold_audio` carries it (`encoded_hold_audio`, an `EncodedAudioReference`), which the block writes in place of running the audio VAE. A `hold_audio` path is opened only after `locations.validate_media_path` against the step's workflow directory. `dw/introspection.py` builds the same graph without weights, hold included, so `get_pipeline_signature` lists a modular pipeline's block inputs. The copies of diffusers behaviour are pinned to the installed diffusers: `shifted_sigma_grid` (the spacing `refine_sigmas` rests on) to stock `set_timesteps`, `GUIDE_FRAMES_PER_CHUNK`/`GUIDE_LATENTS_PER_CHUNK` to the H3 video VAE's `clip_length` and latents per clip, and every name in `LAYOUT_ANCHORS` (`_fill_audio_positions` among them) to `before_denoise`. | `tests/test_h3_hold_audio.py::TestAnchors::test_inserted_next_to_the_anchors_in_every_shape`, `tests/test_h3_hold_audio.py::TestHoldAudioLocation::test_a_path_outside_the_roots_is_refused_at_the_call`, `tests/test_h3_hold_audio.py::TestRefusals::test_a_non_h3_step_is_refused`, `tests/test_h3_hold_audio.py::TestSignature::test_the_h3_signature_shows_hold_audio`, `tests/test_h3_refine.py::TestAnchors::test_inserted_before_denoise_in_every_shape`, `tests/test_h3_tiles.py::TestDecodeFree::test_variant_has_no_decode_and_shares_blocks`, `tests/test_h3_tiles.py::TestTileLoop::test_blocks_are_restored_when_a_tile_fails`, `tests/test_h3_tiles.py::TestTileLoop::test_the_track_is_encoded_by_one_tile_and_handed_to_the_rest`, `tests/test_h3_hold_audio.py::TestHoldBlock::test_a_carried_encode_is_written_without_encoding_again`, `tests/test_h3_tiles.py`, `tests/test_h3_rules.py` (`tile_plan` and the `refine_tiles` rules), `tests/test_h3_mask.py`, `tests/test_h3_refine.py::TestSigmaGridDrift::test_the_full_grid_is_stock_set_timesteps`, `tests/test_h3_refine.py::TestSigmaListOneOwner::test_the_runtime_message_is_the_owners`, `tests/test_h3_refine.py::TestSigmaListSchedule::test_the_block_runs_the_list_unshifted`, `tests/test_h3_guides.py::TestChunkDrift::test_frames_per_chunk_is_the_vae_clip_length`, `tests/test_h3_guides.py::TestChunkDrift::test_latents_per_chunk_is_the_vae_tokens_per_clip`, `tests/test_h3_guides.py::TestAnchors::test_installed_diffusers_has_every_anchor`, `tests/test_guide_chain_validation.py::TestRefused::test_the_step_rule_is_the_guides_rule`, `tests/test_guide_chain_validation.py::TestRefused::test_every_run_mode_is_known_to_validate`, `tests/test_h3_rules.py::test_h3_rules_imports_neither_torch_nor_diffusers`, `tests/test_h3_rules.py::test_the_block_owners_import_no_diffusers` |
 | IC-LoRA reference scale | `workflows/templates/ltx2/` | The five conditioning templates run at `reference_downscale_factor: 1`, and the two upscalers at 2. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_reference_is_encoded_at_the_output_resolution`, `tests/test_ltx2_ic_loras.py::TestTheGenerativeUpscaleMatchesTheSameCard::test_it_loads_the_upscaler_at_factor_two` |
 | IC-LoRA numbers | `workflows/templates/ltx2/` | Every number in the IC-LoRA templates comes from the vendor's model card. | `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_strength_is_the_cards_default`, `tests/test_ltx2_ic_loras.py::TestEachTemplateMatchesItsCard::test_the_defaults_are_the_trained_bucket` |
 | IC-LoRA prompt genre | `prompts/ltx2/` | A stored prompt tagged `ic-lora` is checked against its trained caption form, not against the T2V paragraph rule. | `tests/test_ltx_prompt_library.py::test_an_ic_lora_prompt_is_in_its_trained_form` |
@@ -136,12 +137,12 @@ one to open.
 
 | Concept | Owner | Rule | Enforced by |
 | --- | --- | --- | --- |
-| Opening media | `dw/media.py` | This is the only module that calls `av.open`. It imports no torch and no step types. | `tests/test_media_layering.py::test_av_open_appears_only_in_media`, `tests/test_media_layering.py::test_media_imports_no_step_types` (no torch: —) |
+| Opening media | `dw/media.py`, `dw/media_readers.py` (the frame readers, re-exported by `dw/media.py`, which imports from it and never the reverse) | These are the only modules that call `av.open`. They import no torch and no step types. | `tests/test_media_layering.py::test_av_open_appears_only_in_media`, `tests/test_media_layering.py::test_media_imports_no_step_types` (no torch: —) |
 | Frame moments and crops | `dw/media_frames.py`: `moment_index`, `parse_crop` | One `at` grammar ("frame:N", or seconds at the clip's fps; negative counts back from the end for `get_output_frames` and is refused by `compare_outputs`) and one `[x, y, width, height]` crop parse serve `get_output_frames` and `compare_outputs`. Only the bounds policy is the caller's: `get_output_frames` refuses a moment past the end and clamps a crop (`_moment_to_index`, `resolve_crop_box`); `compare_outputs` blanks a past-end cell and refuses a crop that doesn't fit an output. | `tests/test_media_compare.py::test_resolve_moments_refuses_what_get_output_frames_refuses`, `tests/test_media_compare.py::test_crop_box_refuses_a_malformed_box_as_resolve_crop_box_does` |
 | Output comparison | `dw/media_compare.py`: `compare`, `psnr`, `ssim`, `mean_abs_diff`, `check_request`, `crop_box` | Metrics always compare the same pixels: one shared crop is the measured region, and per-output crops are display only, leaving metrics on the full frame. An output whose size differs from the baseline's, or a moment past its end, gets null metrics with a reason; nothing is resized to force a number. SSIM is on Rec. 601 luma (SSIM's convention, not `image_ops.luma`). It runs in the server process and decodes through `dw/media.py` and `open_bounded`. | `tests/test_compare_route.py::test_a_shared_crop_is_the_region_measured`, `tests/test_compare_route.py::test_per_output_crops_are_display_only`, `tests/test_compare_route.py::test_a_size_mismatch_gets_no_numbers_and_says_why`, `tests/test_compare_route.py::test_a_moment_past_the_shorter_clip_is_a_blank_cell` |
 | Signal processing | `dw/dsp.py` | It measures and transforms waveforms, decides nothing, and imports nothing from `dw`. | `tests/test_media_layering.py::test_dsp_imports_nothing_from_dw` |
 | Assessment probes | `dw/tasks/assess.py`, `dw/assessment_rules.py` | Exactly three registered commands are assessment probes. Each measures a finished file, and every rule names a real probe field. | `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_assessment_is_exactly_the_three_probes`, `tests/test_assessment_rules.py::TestRuleProbesAreRealCommands::test_every_rule_names_a_registered_json_command` |
-| Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` and the looped-bed self-correlation `dsp.repeat_correlation` (`script_check.is_looped_bed` only decides on it) (`script_take.word_level` wraps it; the guard, the transcription levelling, the floor-gated `audible_runs` and the shot placement (with `clamp_to_shot`, a line's timing kept inside its shot) are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
+| Script check | `dw/tasks/script_check.py`: `check`; `dw/tasks/script_findings.py`: the rule constants and the finding builders `check` calls (imported one way, re-exported by `script_check`); `dw/tasks/script_take.py`: `guard_words`, `word_level`, `shot_spans`; `dw/script_lines.py`: `parse_lines`, `parse_shots`, `shot_names_error` | `check_script` aligns a take's heard words to its expected lines and guards out words heard over silence and repetition loops (Whisper's hallucination over music). It builds its findings with `assessment_rules.finding()` and reads the guard's floor and window (`DEAD_AIR_FLOOR_DBFS`, `DEAD_AIR_WINDOW`) rather than copying them; the loudest-window measure is `dsp.loudest_window_dbfs` and the looped-bed self-correlation `dsp.repeat_correlation` (`script_findings.is_looped_bed` only decides on it) (`script_take.word_level` wraps it; the guard, the transcription levelling, the floor-gated `audible_runs` and the shot placement (with `clamp_to_shot`, a line's timing kept inside its shot) are `dw/tasks/script_take.py`, which `script_check` reads one way - nothing there reads the rule tables), which `transcribe_audio`'s `suspect: "silent"` mark reads with the same floor and window; the repetition-loop detector (`script_lines.looped_texts`, `REPEAT_RUN_MIN`, `REPEAT_MAX_PERIOD`) lives in `dw/script_lines.py` and backs both `check_script`'s `repetition` discard and `transcribe_audio`'s `suspect: "repetition"`, and `script_lines.suspect_runs`/`SUSPECT_LEFT_OUT` are what `plan_cuts` groups and leaves out suspect chunks by - so neither task imports the other. It is not an assessment probe and adds nothing to `RULES`. Its literal `lines` is refused at validation through `task_problems` (`script_lines_errors`), which calls the same `parse_lines` the task runs, and a literal `shots` through the same `parse_shots` and `shot_names_error`; the parsers live in `dw/script_lines.py`, not the task, so that `task_problems` reaches them without importing `script_check` (the `import_cycles` ratchet in `scripts/arch_metrics.py`). A line's `shot` may be the short `@name` of the one recorded shot that carries it (`script_lines.matching_shot_names`, `with_full_shot_names`, shared by the task and the literal-`shots` check); which member key a recorded name carries comes from `references.member_keys`, beside `MEMBER_SEPARATOR` and `for_each.member_name`, never a re-derived pattern: a key ends at the first character outside `references.VARIABLE_NAME_CHARACTERS`, the set `security.validate_variable_name` (which checks a for_each entry's name) builds its pattern from. With `audio` an `output:`/`asset:`/path whose run manifest records shots, `dw/shot_span_preflight.py: script_shot_name_errors` (the `script_shot_names` error check) runs `shot_names_error` at validation, reading the map through `runs.shots_beside`. Its shot map comes from `assess.resolve_shots`, the one the probes use, never a copy; it places each shot on the soundtrack with `assess.sample_span`, decides repeated shot names with `shots.duplicate_shot_names`, and asks `locations.is_http_url` whether the take is a URL. | `tests/test_script_check.py::TestRegistration::test_registered_as_json_command_without_assessment_flag`, `tests/test_script_check.py::TestEmptyLines::test_words_only_over_silence_are_discarded_not_found`, `tests/test_script_check.py::TestLinesErrors::test_literal_with_a_colon_is_not_a_reference`, `tests/test_script_check.py::TestShotValidation::test_a_short_member_name_matches_the_one_shot_carrying_it`, `tests/test_script_check.py::TestShotValidation::test_a_valid_variable_name_comes_back_whole_as_a_member_key`, `tests/test_shot_span_preflight.py::TestScriptShotNames::test_a_wrong_shot_name_is_an_error_at_validate_time` |
 | Audio sync against a source slice | `dw/tasks/measure_sync.py`: `measure_sync`; `dw/dsp.py`: `envelope_lag` | `measure_sync` cross-correlates the onset envelopes of a shot's audio and its source slice and answers the lag and a 0-1 confidence. A positive lag means the audio is LATE (its events fall after the reference's), negative early; `lag_seconds` is None for a silent or flat track. It builds its findings (`sync_unmeasurable`, `sync_low_confidence`, `audio_out_of_sync`) with `assessment_rules.finding()` over module-local rule dicts and adds nothing to `RULES`; it reads the silence floor from `beats.SILENT_DBFS`. `envelope_lag` imports nothing from `dw`. | `tests/test_measure_sync.py::TestLag::test_late_audio_is_a_positive_lag`, `tests/test_measure_sync.py::TestLag::test_early_audio_is_a_negative_lag`, `tests/test_measure_sync.py::TestUnmeasurable::test_a_silent_reference_has_no_lag` |
 | Sung phrases from voiced energy | `dw/tasks/phrases.py`: `analyze_phrases`, `voiced_power`, `voiced_runs`; `dw/task_problems.py`: `phrases_problems`, `phrases_errors` | `analyze_phrases` times a song's sung phrases with no model: a stereo file's centre-weighted band power (max(0, P_mid - P_side), 250-3500 Hz, 20 ms frames) or, for mono, `centre: false` or identical channels, the downmix's band power (`method` `band`). The voiced floor is `voice_attribution.voiced_floor_dbfs`, the rule `attribute_voices` uses, unless `floor_db` is given. It answers a dict - `{phrases, duration_seconds, method, warnings}` - so a step saves one JSON artifact. Its ranges are the registration's domains; `phrases_problems` (a real boolean `centre`) runs at validate and at run time. | `tests/test_analyze_phrases.py::TestCentre::test_centred_bursts_under_hard_panned_noise_are_found`, `tests/test_analyze_phrases.py::TestCentre::test_bursts_panned_hard_to_one_side_are_not_centre`, `tests/test_analyze_phrases.py::TestRefusals::test_validate_refuses_a_missing_audio_and_a_negative_gap` |
 
diff --git a/docs/ATTRIBUTIONS.md b/docs/ATTRIBUTIONS.md
index 2745f157..02d07b21 100644
--- a/docs/ATTRIBUTIONS.md
+++ b/docs/ATTRIBUTIONS.md
@@ -16,9 +16,9 @@ Each file keeps its upstream licence notice in its header.
 |---|---|---|
 | [dw/tasks/rife_model.py](../dw/tasks/rife_model.py) | The RIFE interpolation network from [hzwer/Practical-RIFE](https://github.com/hzwer/Practical-RIFE) | MIT, Copyright (c) Megvii Inc. |
 | [dw/tasks/h3_latent_upscaler_model.py](../dw/tasks/h3_latent_upscaler_model.py) | The MiniMax H3 3D-convolution latent upscaler from [LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler](https://github.com/LBH-123-AI/Comfyui_Minimax_h3_latent_Upscaler) | MIT, Copyright (c) LBH-123-AI |
-| [dw/tasks/audio8_tts_model.py](../dw/tasks/audio8_tts_model.py) | The Audio8-TTS (ArkTTS) dual-AR speech model, codec and processor from [Edge0/Audio8-TTS-Realistic-0.6b](https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b/tree/1e857568bfd4f02931aca3988ee773a44d2d26d3), ported (upstream NOTICE kept in the file header) | Apache-2.0 |
-| [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py), [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | The MMAudio flow-matching network, its sequence lengths and classifier-free guidance, and the CLIP conditioning from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24), ported (the sampler is dw's own Euler loop, and the DFN5B towers are transformers' CLIP models filled by a key map) | MIT, Copyright (c) 2024 Sony Research Inc. |
-| [dw/tasks/mmaudio_sync_model.py](../dw/tasks/mmaudio_sync_model.py) | MMAudio's Synchformer visual encoder (a MotionFormer feature extractor) and its 16-frame segmenting, from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24)'s `mmaudio/ext/synchformer/`, ported without timm, einops or omegaconf | MIT, Copyright (c) 2024 Vladimir Iashin |
+| [dw/vendored/audio8_tts_model.py](../dw/vendored/audio8_tts_model.py) | The Audio8-TTS (ArkTTS) dual-AR speech model, codec and processor from [Edge0/Audio8-TTS-Realistic-0.6b](https://huggingface.co/Edge0/Audio8-TTS-Realistic-0.6b/tree/1e857568bfd4f02931aca3988ee773a44d2d26d3), ported (upstream NOTICE kept in the file header) | Apache-2.0 |
+| [dw/vendored/mmaudio_model.py](../dw/vendored/mmaudio_model.py), [dw/vendored/mmaudio_clip.py](../dw/vendored/mmaudio_clip.py) | The MMAudio flow-matching network, its sequence lengths and classifier-free guidance, and the CLIP conditioning from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24), ported (the sampler is dw's own Euler loop, and the DFN5B towers are transformers' CLIP models filled by a key map) | MIT, Copyright (c) 2024 Sony Research Inc. |
+| [dw/vendored/mmaudio_sync_model.py](../dw/vendored/mmaudio_sync_model.py) | MMAudio's Synchformer visual encoder (a MotionFormer feature extractor) and its 16-frame segmenting, from [hkchengrex/MMAudio](https://github.com/hkchengrex/MMAudio/tree/974010a026c731054592d8f777218bd9d85a6c24)'s `mmaudio/ext/synchformer/`, ported without timm, einops or omegaconf | MIT, Copyright (c) 2024 Vladimir Iashin |
 | [dw/tasks/mmaudio_decoder.py](../dw/tasks/mmaudio_decoder.py) | Loads diffusers' `MMAudioVAE` and `MMAudioVocoder`; the vocoder is [BigVGAN](https://github.com/NVIDIA/BigVGAN) (no BigVGAN code is copied here: the classes are diffusers') | BigVGAN: MIT, Copyright (c) 2024 NVIDIA CORPORATION |
 | [dw/community_pipelines/pipeline_flux_rf_inversion.py](../dw/community_pipelines/pipeline_flux_rf_inversion.py) | The diffusers community RF-Inversion pipeline, after [RF Inversion](https://rf-inversion.github.io/) by Litu Rout, Yujia Chen, Nataniel Ruiz, Constantine Caramanis, Sanjay Shakkottai and Wen-Sheng Chu | Apache-2.0, Copyright 2024 Black Forest Labs and The HuggingFace Team |
 | [dw/prompt_weighting.py](../dw/prompt_weighting.py) | Based on [sd_embed](https://github.com/xhinker/sd_embed) by Andrew Zhu | Apache-2.0 |
@@ -31,10 +31,10 @@ apply to anything generated with them.
 
 | Weights | Used by | Licence |
 |---|---|---|
-| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) (`weights/mmaudio_large_44k_v2.pth` and its `ext_weights/`) | `generate_sound_effects`: [dw/tasks/mmaudio_model.py](../dw/tasks/mmaudio_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
-| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) `ext_weights/synchformer_state_dict.pth` | `generate_sound_effects`, MMAudio's sync features, [dw/tasks/mmaudio_sync_model.py](../dw/tasks/mmaudio_sync_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) (`weights/mmaudio_large_44k_v2.pth` and its `ext_weights/`) | `generate_sound_effects`: [dw/vendored/mmaudio_model.py](../dw/vendored/mmaudio_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
+| [hkchengrex/MMAudio](https://huggingface.co/hkchengrex/MMAudio) `ext_weights/synchformer_state_dict.pth` | `generate_sound_effects`, MMAudio's sync features, [dw/vendored/mmaudio_sync_model.py](../dw/vendored/mmaudio_sync_model.py) | [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/): non-commercial use only |
 | [kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers](https://huggingface.co/kandinskylab/Kandinsky-6.0-Lite-distill-5s-Diffusers/tree/4c487e8b4aeeb9059e5a77905aa2ddb59ec28f81) `audio_vae/` and `vocoder/` | `generate_sound_effects`, MMAudio's decoder, [dw/tasks/mmaudio_decoder.py](../dw/tasks/mmaudio_decoder.py) | The MMAudio VAE tensors: [CC-BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/), non-commercial use only, as MMAudio's weights (K6's model card states MIT; dw follows the stricter MMAudio terms). The BigVGAN vocoder: MIT. |
-| [apple/DFN5B-CLIP-ViT-H-14-384](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384) | `generate_sound_effects`, MMAudio's CLIP conditioning, [dw/tasks/mmaudio_clip.py](../dw/tasks/mmaudio_clip.py) | [Apple Machine Learning Research Model License](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384/blob/main/LICENSE): research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. dw maps the weights into transformers' layout in memory at load time and never writes or ships converted tensors. |
+| [apple/DFN5B-CLIP-ViT-H-14-384](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384) | `generate_sound_effects`, MMAudio's CLIP conditioning, [dw/vendored/mmaudio_clip.py](../dw/vendored/mmaudio_clip.py) | [Apple Machine Learning Research Model License](https://huggingface.co/apple/DFN5B-CLIP-ViT-H-14-384/blob/main/LICENSE): research purposes only. Apple Machine Learning Research Model is licensed under the Apple Machine Learning Research Model License Agreement. dw maps the weights into transformers' layout in memory at load time and never writes or ships converted tensors. |
 
 ## Ideas reimplemented here
 
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
index 41d0efbf..1ca2351a 100644
--- a/docs/RELEASING.md
+++ b/docs/RELEASING.md
@@ -7,6 +7,136 @@ 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.17.0
+
+<!-- Drafted from v0.16.0..develop at release prep (2026-11-01). Paste into the GitHub release body once the tag has published: gh release edit v0.17.0 --notes-file ... -->
+
+A release about fixing a good take instead of re-rolling it, and about
+sound that is not the model's own. MiniMax H3 edits one region of a take
+behind a mask, redraws a soft face and takes an explicit refine schedule;
+LTX-2.5 pulls an alpha matte and colourises black-and-white footage; a
+picture-synced sound-effects task (MMAudio) and a zero-shot voice clone
+(Audio8-TTS) join the catalog as vendored ports that run no Hub code; and
+every one-for-one video task now writes at its source's frame rate, exactly.
+
+**H3 regional edit, face repair and refine schedule** (#1062, #1077, #1078, #1082, #1087, #1092, #1098, #1099)
+
+- `templates/minimax/regional-edit`: an H3 step takes `source_video` and a
+  `mask_image` or `mask_video` (white regenerates) with `refine_strength`,
+  re-denoises the masked rows and writes every other row back to the source
+  at each step, soundtrack held. The guide's *H3: regional edit with
+  source_video and a mask* has the measured strength bands (0.9 replaces an
+  object, 0.6 redraws a face); the `minimax-h3` skill routes "fix one region
+  of a good take" to it (`references/regional-edit.md`). Validate and the call
+  refuse the same things: a mask with no source, a source on a chained step,
+  a size or frame-count mismatch, an all-black mask, a source whose frame
+  count is off the `17n + 5` grid (the pipeline would snap it up over a
+  padded source and the mask would drift).
+- `templates/minimax/face-repair`: `crop_face_track` cuts the face out on H3's
+  grid carrying the take's padded soundtrack, a t2va refine at 0.6 redraws it
+  with `hold_audio` so the mouth stays on the speech, and `paste_face_track`
+  puts it back at the source's frame rate. The crop refuses a window outside
+  124-345 frames or a rate other than 24 before H3 loads.
+- `refine_sigmas` on an H3 refine step gives the schedule as the sigma points
+  themselves (first = `refine_strength`, last = 0, strictly decreasing as
+  float32, finite, `num_inference_steps` = the point count), the guide's
+  *Explicit refine sigmas*. A full-frame refine whose `width`/`height`
+  disagree with the upscaled latents is refused at validate (#1087), and a
+  single-file LoRA is priced as its file, not its repo (#1088).
+- The `minimax-h3` skill gains the style pointer (`references/style.md`,
+  #1070), the AISkills and odd-then-bridge probes recorded as "probed, not a
+  rule" (#1072, #1103), the re-measured lead-in (#1089), and routes for the
+  past-768p latent refine and for replacing a shot's own sound.
+
+**Sound effects and voice cloning** (#1112, #1120, #1121, #1124, #1131-#1133, #1134)
+
+- `generate_sound_effects` (MMAudio, vendored at a pinned commit with its
+  Synchformer and DFN5B CLIP conditioning, decoder weights read from
+  Kandinsky 6's safetensors) makes picture-synced effects for a clip and/or
+  a prompt: `templates/video-to-sound-effects` and
+  `templates/text-to-sound-effect`. Duration is the clip's (0.64-20 s), the
+  model is trained around 8 s, noise-like output is warned about, and the
+  output runs 7-25 dB hot: `match_levels` before mixing. The weights are
+  CC-BY-NC and Apple research-only; `docs/ATTRIBUTIONS.md` lists them.
+- `generate_speech` with `model_name: Edge0/Audio8-TTS-Realistic-0.6b` clones
+  a voice from a short `reference_audio` (a path, an `asset:`, or an earlier
+  audio step's output) and its `reference_text`; `templates/voice-clone` runs
+  it. The model is a vendored port pinned to one revision; its Hub repo's
+  code never runs. `attribute_voices` takes an audio step's output as a voice
+  reference too (#1134).
+- The vendored ports live in `dw/vendored/`, outside the architecture ratchet
+  like `dw/community_pipelines/`.
+
+**LTX-2.5: alpha matte, colourisation, and the source's frame rate** (#1064, #1079, #1080, #1090, #1106-#1109, #1114)
+
+- `templates/ltx2/alpha-matte` (Alpha-Gen IC-LoRA) pulls a grey matte from a
+  clip, one shot at a time (a hard cut leaks), with the decoders kept off the
+  card; `templates/ltx2/restore-colorize` colourises black-and-white footage
+  from a prompt that describes the clip, with its colour limit on low-rate
+  and portrait sources documented.
+- Every one-for-one template (`upscale-clip`, `refine-clip`,
+  `refine-in-place`, `restore-deblur`, `restore-decompression`,
+  `restore-long`, `face-repair`, `alpha-matte`, `restore-colorize`) writes at
+  the source's frame rate (`frame_rate: "source"`), never relabelled to 24,
+  and a fractional rate (29.97, 23.976) is written as its exact rational
+  (#1109). `restore-deblur` and `restore-decompression` fit the clip to the
+  model, then restore to the source's size.
+
+**Cuts, phrases and the script check** (#1095, #1104, #1105, #1115-#1119, #1129, #1130, #1135-#1138)
+
+- `analyze_phrases` times sung phrases from centre-weighted voiced energy,
+  with no transcript, and `plan_cuts` takes its result: lyric lines pair with
+  phrases one to one when the counts match (a disproportionate pairing is
+  warned about) and are spread evenly when they do not, with the warning
+  naming which way to move `min_gap_seconds` or `floor_db`. The music-video
+  templates' README shows the Whisper-free chain.
+- `transcribe_audio` marks Whisper's hallucinations: chunks of a near-silent
+  clip (`silent`), its stock outro lines (`stock_phrase`), 5-6 word loops and
+  duplicate overlapping chunks (`repetition`); `plan_cuts` and `check_script`
+  leave suspect chunks out and say so.
+- `check_script`: an untranscribed block crossing a shot seam is credited to
+  each shot it covers (a shot too short to stand alone is folded into its
+  neighbour, never dropped); a line's timing stays inside its shot; a take
+  with no shots is one implicit shot for `unscripted_speech`; a looped
+  room-tone bed is not untranscribed speech; speech outside a partial shot
+  map is named in `rules_skipped`; an unheard line's clip is checked against
+  its shot's end.
+- `separate_stems` no longer shift-averages a clip shorter than the htdemucs
+  segment, which clipped the stems 9-17 dB hot (#1130).
+
+**Skills and composition** (#1093, #1100, #1122, #1125, #1123, #1126-#1128, #1091, #1096)
+
+- `script-to-video`: cutaway and lead-in joins (`references/joins.md`), beat
+  authoring and the beat review (`references/beat-review.md`), shared with
+  `series-episodes`; `series-episodes` gains the dialogue/rest stem recipe
+  via `separate_stems`, kept balanced for headroom.
+- The story-forge lessons that held on lem (framing, no invented camera, no
+  all-caps) landed as guidance in the `ltx-2.5` skill; the ones that did not
+  are recorded as probed.
+
+**Validation, server and security** (#1086, #1101, #1111, #1116, #1119, GHSA-hhfj-p9xj-xjmr, GHSA-75fh-g499-53cf, GHSA-9597-5qpq-55x6, GHSA-w9qv-2pg5-j79m, GHSA-75cg-7964-pjwx)
+
+- A task step's `trust_remote_code`, `custom_pipeline` or `custom_generate`
+  is refused at validate and again at `Task.run`, for every task; a `videos`
+  list and the active result types are gated at validate; a reference error
+  no longer names a server path.
+- `for_each` refuses a literal cross-entry reference inside one group;
+  `list_jobs` refuses a workspace that does not exist; a cached pipeline's
+  minutes-long decode and a slow first pass are warned about as measurements,
+  with no cause asserted.
+- Python 3.12 or newer is required (#1084); the install scripts and
+  classifiers say so.
+
+**Architecture**
+
+- `dw/media.py`, `dw/tasks/cuts.py`, `dw/tasks/script_check.py` and
+  `dw/pipeline_processors/pipeline.py` each hand a concern to a companion
+  module (`media_readers`, `cuts_lines`, `script_findings`,
+  `pipeline_outputs`), and the regional edit's mask arithmetic moves to
+  `h3_mask_cells` so the blocks never import their importer. The ratchet's
+  module count rises 226 -> 236 for these and the new tasks; every other
+  metric holds.
+
 ### 0.16.0
 
 <!-- Drafted from v0.15.0..develop (7a0884ee). Paste into the GitHub release body once the tag has published: gh release edit v0.16.0 --notes-file ... -->
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index ec0d6e24..55a93e4e 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -148,7 +148,7 @@ the run is refused before it queues. `Task.run` repeats the check for every
 command before its handler runs (GHSA-hhfj-p9xj-xjmr).
 
 `speech_generation`'s Audio8-TTS branch (`Edge0/Audio8-TTS-Realistic-0.6b`,
-`dw/tasks/audio8_tts_model.py`) runs no code from its repo: the model is
+`dw/vendored/audio8_tts_model.py`) runs no code from its repo: the model is
 vendored, so there is no `trust_remote_code` load. Its five files are fetched
 with `hf_hub_download` at one pinned 40-hex revision, never a branch, and the
 weights are safetensors. The audio codec, `codec.pth`, is a pickle checkpoint;
@@ -158,7 +158,7 @@ isn't a tensor or a plain container, and only at that pinned revision. Its
 allowlist (`temperature`, `top_p`, `top_k`, `do_sample`, `max_new_tokens`):
 any other key is refused by name before the model loads.
 
-MMAudio (`dw/tasks/mmaudio_model.py`, `dw/tasks/mmaudio_sync_model.py`,
+MMAudio (`dw/vendored/mmaudio_model.py`, `dw/vendored/mmaudio_sync_model.py`,
 `dw/tasks/mmaudio_decoder.py`) runs no code from its repo either: the network
 and the Synchformer visual encoder are vendored at upstream commit
 `974010a0`. Their two checkpoints, `hkchengrex/MMAudio`'s
diff --git a/docs/TASKS.md b/docs/TASKS.md
index cb127216..96b59323 100644
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -3206,7 +3206,7 @@ The result needs no `sample_rate`. A generated track carries the rate its model
 
 ### Cloning a voice (Audio8-TTS)
 
-`model_name: "Edge0/Audio8-TTS-Realistic-0.6b"` takes its own branch. The model is vendored (`dw/tasks/audio8_tts_model.py`), so it loads no code from its repo, and its files - `config.json`, `generation_config.json`, `model.safetensors`, `tokenizer.json` and the codec `codec.pth` - are fetched at one pinned revision; a validate's `downloads_required` lists all five. The result is a 44.1 kHz mono track.
+`model_name: "Edge0/Audio8-TTS-Realistic-0.6b"` takes its own branch. The model is vendored (`dw/vendored/audio8_tts_model.py`), so it loads no code from its repo, and its files - `config.json`, `generation_config.json`, `model.safetensors`, `tokenizer.json` and the codec `codec.pth` - are fetched at one pinned revision; a validate's `downloads_required` lists all five. The result is a 44.1 kHz mono track.
 
 Give `reference_audio` and `reference_text` together and it speaks `text` in the reference's voice; leave both out and it speaks in its default voice. The language follows `text` - there is no `language` argument. Every refusal fires before the model loads:
 
@@ -3267,13 +3267,13 @@ A speech model is worth releasing before a video model loads — set `release_mo
 | `video` | One of `video`/`prompt` | The clip the effects follow (typically an `asset:` or `previous_result:` reference) |
 | `prompt` | One of `video`/`prompt` | What should be heard |
 | `negative_prompt` | No | What to steer away from, such as `music, speech` |
-| `duration` | No | Seconds. Defaults to the clip's length, or 8 s text-only; at most 20 s and never longer than the clip |
+| `duration` | No | Seconds. Defaults to the clip's length, or 8 s text-only; at least 0.64 s (16 sync frames at 25 fps), at most 20 s and never longer than the clip |
 | `steps` | No | Sampler steps (default: 25) |
 | `guidance_scale` | No | Classifier-free guidance (default: 4.5) |
 
 Video-only is the weaker mode: give a `prompt` that names the on-screen sound sources as well. The model was trained around 8 s, so a `duration` outside 4-12 s adds a warning to the result, as does noise-like output (spectral flatness of 0.3 or more with a centroid of 8 kHz or more).
 
-Every refusal fires before anything loads: neither `video` nor `prompt`; a `duration` over 20 s or longer than the clip; an unknown argument; and `trust_remote_code`, `custom_pipeline` or `custom_generate` (the trust gate).
+Every refusal fires before anything loads: neither `video` nor `prompt`; a `duration` under 0.64 s, over 20 s or longer than the clip; an unknown argument; and `trust_remote_code`, `custom_pipeline` or `custom_generate` (the trust gate).
 
 The output runs 7-25 dB hot. Route it through `match_levels` before mixing it with dialogue or music.
 
diff --git a/docs/WORKFLOW_GUIDE.md b/docs/WORKFLOW_GUIDE.md
index b331b79b..e6294d53 100644
--- a/docs/WORKFLOW_GUIDE.md
+++ b/docs/WORKFLOW_GUIDE.md
@@ -2612,6 +2612,12 @@ Validation and the call both refuse:
 - `source_video` with no `refine_strength`, or one outside (0, 1];
 - `source_video` on a pipeline that is not H3 (`mask_image` there is left alone, since
   inpaint pipelines own that name);
+- a `source_video` whose frame count (and so the step's `num_frames`, inferred or
+  given) is off the `17n + 5` grid: the pipeline would snap the count up and pad the
+  source, and the mask would drift in time - trim or pad the clip to the grid first
+  (the message names both neighbours). An inferred `width` and `height` still have to
+  meet the family's canvas rules (multiples of 32), which the template's variables
+  carry and an inferred size does not check;
 - any of it with `refine_tiles`, which does not combine with a regional edit.
 
 ### Refining above 768p in tiles
diff --git a/docs/stabilization/baseline.json b/docs/stabilization/baseline.json
index 4cb154d8..562025ae 100644
--- a/docs/stabilization/baseline.json
+++ b/docs/stabilization/baseline.json
@@ -1,5 +1,5 @@
 {
-  "modules": 226,
+  "modules": 236,
   "modules_over_size_ceiling": 0,
   "functions_over_150_lines": 0,
   "prefix_literals": 0,
diff --git a/dw/media.py b/dw/media.py
index 2a1db47e..2481a430 100644
--- a/dw/media.py
+++ b/dw/media.py
@@ -1,8 +1,9 @@
-"""The one module that opens a media container.
+"""The module that opens a media container.
 
-Every `av.open` in the engine is here (`tests/test_media_layering.py`
-reads the source tree to keep it so), which is what makes "one call is one
-open" something a test can count and a patch can intercept:
+Every `av.open` in the engine is here or in dw/media_readers.py (the frame
+readers, re-exported here; `tests/test_media_layering.py` reads the source
+tree to keep it so), which is what makes "one call is one open" something a
+test can count and a patch can intercept:
 
 - headers: `media_duration`, `container_fps`, `audio_shape`, `video_shape`,
   `probe_metadata`;
@@ -29,22 +30,31 @@
 import av
 import numpy
 from av.audio.resampler import AudioResampler
-from av.video.reformatter import VideoReformatter
-from PIL import Image
 
 from .dsp import SILENCE_DBFS, dbfs, integrated_lufs, layout_name, true_peak_dbfs
+from .media_readers import (  # noqa: F401 - re-exported
+    ShortFrameRange,
+    _landed_at,
+    _seek_before,
+    _seek_needed,
+    _threaded,
+    as_frame_samples,
+    count_video_frames,
+    decode_audio_video,
+    decode_rgb_frames,
+    iter_rgb_frames,
+    read_frame_range,
+    read_frames,
+    read_thumbnails_and_track,
+    sample_frames,
+    stream_seconds,
+    to_float32,
+    video_shape,
+)
 
 logger = logging.getLogger("dw")
 
 
-def _threaded(stream):
-    """A video stream set to decode on every core. libav defaults a
-    software h264 decode to one thread; AUTO lets it pick frame and
-    slice threading for the codec. Header-only reads do not call this."""
-    stream.thread_type = "AUTO"
-    return stream
-
-
 # The most a soundtrack may be as base64 before the gallery route refuses to
 # extract it whole - the twin of dw_mcp/media.py's MAX_RETURNED_BYTES (the
 # MCP package's cap on any inline payload). Two constants because dw_mcp
@@ -304,68 +314,6 @@ def decode_soundtrack(path):
     return numpy.ascontiguousarray(to_float32(samples).T), rate
 
 
-def to_float32(samples):
-    """A decoded audio frame (or its ndarray) as float32 in [-1, 1].
-
-    An unsigned format is centred on its midpoint, a signed integer one is
-    scaled by its own maximum, and a float one is only cast - the three
-    conversions every decode here (the probe, the assessment reader) used to
-    spell for itself.
-    """
-    if isinstance(samples, av.AudioFrame):
-        samples = samples.to_ndarray()
-    if samples.dtype.kind == "u":
-        iinfo = numpy.iinfo(samples.dtype)
-        half = (iinfo.max + 1) / 2
-        samples = (samples.astype(numpy.float32) - half) / half
-    elif samples.dtype.kind == "i":
-        samples = samples.astype(numpy.float32) / numpy.iinfo(samples.dtype).max
-    return samples.astype(numpy.float32)
-
-
-def as_frame_samples(samples, channels):
-    """One decoded audio frame as a (samples, channels) array.
-
-    A planar format decodes to (channels, samples); a packed one decodes to
-    (1, samples * channels) interleaved. Both have to become a run of
-    samples before they can be cut on a second boundary, or a stereo packed
-    frame would be counted as twice as much time as it holds.
-    """
-    if samples.ndim == 1:
-        return samples[:, numpy.newaxis]
-    if samples.shape[0] == channels and channels > 1:
-        return samples.T
-    if samples.shape[0] == 1 and channels > 1:
-        return samples.reshape(-1, channels)
-    return samples.T if samples.shape[0] < samples.shape[1] else samples
-
-
-def stream_seconds(stream):
-    """A stream's own reported duration in seconds, or None."""
-    if stream is None or stream.duration is None or stream.time_base is None:
-        return None
-    return float(stream.duration * stream.time_base)
-
-
-def video_shape(path):
-    """Frame count, fps and size, from the container's own headers where
-    they are written and by counting otherwise."""
-    with av.open(path) as container:
-        if not container.streams.video:
-            raise ValueError(f"{path} has no video stream")
-        stream = container.streams.video[0]
-        fps = float(stream.average_rate) if stream.average_rate else None
-        count = int(stream.frames) if stream.frames else None
-        if count is None:
-            count = sum(1 for _ in container.decode(_threaded(stream)))
-        return {
-            "frame_count": count,
-            "fps": fps,
-            "width": int(stream.width),
-            "height": int(stream.height),
-        }
-
-
 def faststart(path):
     """Rewrite an MP4 in place with its index (the moov atom) ahead of the
     media data, as ffmpeg's `-movflags +faststart` does. Neither diffusers
@@ -400,326 +348,6 @@ def faststart(path):
             os.remove(temporary)
 
 
-def read_frames(path, indexes, fit=None):
-    """The frames at these indexes, as {index: PIL image}, in one forward
-    pass that seeks to the keyframe before each wanted frame rather than
-    decoding from the top. Decodes are dropped as soon as they are past.
-
-    `fit(image, index)`, when given, is applied to each frame as it is
-    decoded, so a caller tiling many frames never holds one at source size.
-
-    This assumes a constant frame rate, which every file this engine writes
-    has (`encode_video` / `export_to_video` write a fixed `fps`): a
-    `backward=True` seek lands on the keyframe at or before the target
-    timestamp, and `frame.pts * stream.time_base` converts that keyframe's
-    own presentation time back to an exact frame index (`round(seconds *
-    fps)`) - verified against PyAV 18.1's actual seek landings (a
-    single-keyframe short clip, where every seek lands on frame 0; a `g=10`
-    multi-keyframe clip, where a seek to frame 95 lands exactly on frame 90;
-    and a clip whose packets carry a 5-frame pts offset - an edit list or a
-    non-zero start, which real muxers write - where the raw pts arithmetic
-    landed 5 frames off until it was anchored on `stream.start_time`).
-    `start_pts` is that anchor: pts is a timestamp against the *container's*
-    clock, not a frame count from this stream's first frame, so it has to be
-    zeroed against wherever this stream actually starts before it means a
-    frame index. `position` is then a plain frame counter from that
-    landing, decoding forward to the target and dropping what is skipped
-    past.
-    """
-    wanted = sorted(set(int(i) for i in indexes))
-    found = {}
-    with av.open(path) as container:
-        # Not _threaded: frame threads hold frames in flight, and a backward
-        # seek after a decoded frame then yields stale ones (tests/test_media_decode_threads.py)
-        stream = container.streams.video[0]
-        fps = float(stream.average_rate) if stream.average_rate else None
-        start_pts = stream.start_time if stream.start_time is not None else 0
-        position = 0  # index of the next frame decode() will yield
-        # One decode generator for every target: a fresh `decode()` per
-        # target restarts from a demuxer already at EOF when the previous
-        # target sat on the last packets, and raises EOFError (#654)
-        decoded = container.decode(stream)
-        for target in wanted:
-            if _seek_needed(target, position, fps):
-                # seek back or a long way forward: land on the keyframe at
-                # or before the target, then read up to it
-                _seek_before(container, stream, target, fps, start_pts)
-                position = None
-            recovered = False
-            for frame in decoded:
-                if position is None:
-                    # first frame after a seek says where we landed
-                    position = _landed_at(frame, stream, fps, start_pts)
-                    if position > target and not recovered:
-                        # Landed past the target: the keyframe estimate was
-                        # wrong for this file (off-rate or VFR). Reading on
-                        # would scan to EOF and blame the caller; read from
-                        # the top once instead, which is always correct.
-                        container.seek(start_pts, stream=stream, backward=True)
-                        position = None
-                        recovered = True
-                        continue
-                if position == target:
-                    image = frame.to_image()
-                    found[target] = fit(image, target) if fit is not None else image
-                    position += 1
-                    break
-                position += 1
-        missing = [i for i in wanted if i not in found]
-        if missing:
-            raise ValueError(f"could not decode frame(s) {missing} of {path}")
-    return found
-
-
-def sample_frames(path, fps, duration, size, crop=False):
-    """A clip sampled at `fps` for `duration` seconds, as a numpy array.
-
-    Frame k (of int(fps * duration), as upstream MMAudio truncates) is source
-    frame round(k / fps * source_fps); indexes past the clip's last frame are
-    dropped, so a short clip returns fewer frames, and an up-rate repeats
-    some. Each frame is fitted as it decodes, so none is held at source size.
-
-    `crop=False` is MMAudio's CLIP input (8 fps): bicubic to size x size,
-    uint8 (N, size, size, 3). `crop=True` is its Synchformer input (25 fps,
-    224): bicubic to a short side of `size`, centre crop (torchvision's
-    CenterCrop rounding), float32 (N, size, size, 3) in [-1, 1] (mean 0.5,
-    std 0.5). After mmaudio/eval_utils.py `load_video` at commit 974010a0.
-    """
-    if fps <= 0 or duration <= 0 or size <= 0:
-        raise ValueError("fps, duration and size must be positive")
-    shape = video_shape(path)  # raises for a file with no video stream
-    if not shape["fps"]:
-        raise ValueError(f"{path} declares no frame rate")
-    indexes = [round(k / fps * shape["fps"]) for k in range(int(fps * duration))]
-    indexes = [i for i in indexes if i < shape["frame_count"]]
-
-    def fit(image, _index):
-        if crop:
-            scale = size / min(image.size)
-            width, height = (max(size, round(side * scale)) for side in image.size)
-            image = image.resize((width, height), Image.BICUBIC)
-            left, top = (int(round((side - size) / 2.0)) for side in (width, height))
-            return image.crop((left, top, left + size, top + size))
-        return image.resize((size, size), Image.BICUBIC)
-
-    found = read_frames(path, indexes, fit=fit) if indexes else {}
-    frames = (
-        numpy.stack([numpy.asarray(found[i]) for i in indexes])
-        if indexes
-        else (numpy.zeros((0, size, size, 3), numpy.uint8))
-    )
-    return frames.astype(numpy.float32) / 127.5 - 1 if crop else frames
-
-
-def _seek_needed(target, position, fps):
-    """Whether reaching frame `target` from `position` takes a seek: going
-    back, or a long way forward (more than two seconds of decoding)."""
-    return target < position or target - position > 2 * (int(fps) if fps else 24)
-
-
-def _seek_before(container, stream, target, fps, start_pts):
-    """Land on the keyframe at or before frame `target`. The seek target is
-    a container timestamp too, so it needs the same `start_pts` anchor."""
-    seconds = target / fps if fps else 0.0
-    container.seek(
-        int(seconds / stream.time_base) + start_pts,
-        stream=stream,
-        backward=True,
-    )
-
-
-def _landed_at(frame, stream, fps, start_pts):
-    """The frame index of the first frame decoded after a seek."""
-    if not fps or frame.pts is None:
-        return 0
-    return int(round(float((frame.pts - start_pts) * stream.time_base) * fps))
-
-
-class ShortFrameRange(ValueError):
-    """`read_frame_range` reached the end of the file before `stop`;
-    `decoded` is the frame index the decode had reached."""
-
-    def __init__(self, path, start, stop, decoded):
-        super().__init__(
-            f"could not decode frames {start}..{stop - 1} of {path}: the file "
-            f"ended after {decoded} frames"
-        )
-        self.decoded = decoded
-
-
-def read_frame_range(path, start, stop):
-    """The frames `[start, stop)` of `path` as one (n, height, width, 3)
-    uint8 array, from one keyframe seek and one forward decode.
-
-    `read_frames`' seek, for a run of frames rather than a set: the same
-    `start_time` anchor, the same read-from-the-top fallback when the seek
-    lands past `start`, and one decode generator (#654). Each frame is
-    converted to `rgb24` exactly as `decode_audio_video` converts it, so the
-    run is byte for byte what a full decode holds at those indexes, without
-    the rest of the file ever being resident (#695).
-
-    Raises `ShortFrameRange` when the file ends before `stop`.
-    """
-    start, stop = int(start), int(stop)
-    if start < 0 or stop <= start:
-        raise ValueError(
-            f"read_frame_range needs 0 <= start < stop, got {start} and {stop}"
-        )
-    out = None
-    with av.open(path) as container:
-        # Not _threaded: frame threads hold frames in flight, and a backward
-        # seek after a decoded frame then yields stale ones (tests/test_media_decode_threads.py)
-        stream = container.streams.video[0]
-        fps = float(stream.average_rate) if stream.average_rate else None
-        start_pts = stream.start_time if stream.start_time is not None else 0
-        position = 0
-        decoded = container.decode(stream)
-        if _seek_needed(start, position, fps):
-            _seek_before(container, stream, start, fps, start_pts)
-            position = None
-        recovered = False
-        for frame in decoded:
-            if position is None:
-                position = _landed_at(frame, stream, fps, start_pts)
-                if position > start and not recovered:
-                    # Landed past the start: the keyframe estimate was wrong
-                    # for this file; read from the top once instead
-                    container.seek(start_pts, stream=stream, backward=True)
-                    position = None
-                    recovered = True
-                    continue
-            if position >= start:
-                picture = frame.to_ndarray(format="rgb24")
-                if out is None:
-                    out = numpy.empty((stop - start,) + picture.shape, numpy.uint8)
-                out[position - start] = picture
-            position += 1
-            if position >= stop:
-                return out
-    raise ShortFrameRange(path, start, stop, position or 0)
-
-
-def count_video_frames(path):
-    """The picture frame count of `path`, by decoding every frame rather
-    than reading the header. Nothing is held but the frame in hand."""
-    with av.open(path) as container:
-        return sum(1 for _ in container.decode(_threaded(container.streams.video[0])))
-
-
-def decode_audio_video(handle):
-    """A path or file object's picture and soundtrack, decoded in one pass.
-
-    Returns (frames, audio, sample_rate, frame_rate): the frames as RGB PIL
-    images, the track as float32 (channels, samples) - planar float, the
-    layout `AudioVideo` carries - or None when there is none, the audio
-    stream's rate (None with no audio stream) and the picture's declared
-    rate (None when it states none). The codec's padding is the caller's to
-    fit away; building the `AudioVideo` is too.
-    """
-    frames = []
-    chunks = []
-    sample_rate = None
-
-    with av.open(handle) as container:
-        video_stream = _threaded(container.streams.video[0])
-        frame_rate = (
-            float(video_stream.average_rate) if video_stream.average_rate else None
-        )
-        streams = [video_stream]
-        if container.streams.audio:
-            audio_stream = container.streams.audio[0]
-            streams.append(audio_stream)
-            sample_rate = audio_stream.rate
-            resampler = AudioResampler(format="fltp")
-
-        for frame in container.decode(*streams):
-            if isinstance(frame, av.VideoFrame):
-                frames.append(Image.fromarray(frame.to_ndarray(format="rgb24")))
-            else:
-                chunks.extend(f.to_ndarray() for f in resampler.resample(frame))
-
-        if sample_rate is not None:
-            chunks.extend(f.to_ndarray() for f in resampler.resample(None))
-
-    audio = to_float32(numpy.concatenate(chunks, axis=1)) if chunks else None
-    return frames, audio, sample_rate, frame_rate
-
-
-def decode_rgb_frames(path):
-    """Every picture frame of `path` as an (height, width, 3) uint8 array,
-    in order."""
-    with av.open(path) as container:
-        return [
-            frame.to_ndarray(format="rgb24")
-            for frame in container.decode(_threaded(container.streams.video[0]))
-        ]
-
-
-def iter_rgb_frames(path):
-    """The picture frames of `path` as (height, width, 3) uint8 arrays, one at
-    a time, so a caller can stop at the frame it is looking for."""
-    with av.open(path) as container:
-        for frame in container.decode(_threaded(container.streams.video[0])):
-            yield frame.to_ndarray(format="rgb24")
-
-
-def read_thumbnails_and_track(
-    path, thumb_width, thumb_height, look=None, look_width=128, look_height=72
-):
-    """Stream a file once into grey thumbnails and its soundtrack.
-
-    Each decoded picture frame is reduced to a `thumb_height` x `thumb_width`
-    grey array as it arrives and then dropped, so memory holds thumbnails,
-    not pictures. With `look`, each frame is also reformatted to a
-    `look_height` x `look_width` rgb24 array and handed to it at once, and
-    only what it returns is kept (#1031). Returns (thumbs, chunks, fps,
-    video_seconds, audio_seconds, sample_rate, looks): the thumbnails as a
-    list, the track as a list of float32 (samples, channels) chunks, the
-    streams' own rates and durations (None where a stream is absent or
-    states none), and `look`'s results as a list (empty without one).
-    """
-    thumbs = []
-    looks = []
-    chunks = []
-    # Its own scaler: frame.reformat shares one, and alternating two output
-    # sizes through it rebuilds the context every frame - 10x the cost
-    look_scaler = VideoReformatter()
-    with av.open(path) as container:
-        video = (
-            _threaded(container.streams.video[0]) if container.streams.video else None
-        )
-        audio = container.streams.audio[0] if container.streams.audio else None
-        if video is None and audio is None:
-            raise ValueError(f"{path} has neither a video nor an audio stream")
-        fps = float(video.average_rate) if video and video.average_rate else None
-        video_seconds = stream_seconds(video)
-        audio_seconds = stream_seconds(audio)
-        channels = int(audio.channels) if audio is not None else 0
-        streams = [s for s in (video, audio) if s is not None]
-        for frame in container.decode(*streams):
-            if isinstance(frame, av.VideoFrame):
-                thumbs.append(
-                    frame.reformat(
-                        width=thumb_width, height=thumb_height, format="gray"
-                    ).to_ndarray()[:thumb_height, :thumb_width]
-                )
-                if look is not None:
-                    looks.append(
-                        look(
-                            look_scaler.reformat(
-                                frame,
-                                width=look_width,
-                                height=look_height,
-                                format="rgb24",
-                            ).to_ndarray()[:look_height, :look_width]
-                        )
-                    )
-            elif isinstance(frame, av.AudioFrame):
-                chunks.append(as_frame_samples(to_float32(frame), channels))
-        sample_rate = int(audio.rate) if audio is not None else None
-    return thumbs, chunks, fps, video_seconds, audio_seconds, sample_rate, looks
-
-
 def _stream_info(container, audio_stream_seconds=False):
     """The header-level description of an opened container: (info, video,
     audio), or (None, None, None) when it holds neither stream.
diff --git a/dw/media_readers.py b/dw/media_readers.py
new file mode 100644
index 00000000..51c84699
--- /dev/null
+++ b/dw/media_readers.py
@@ -0,0 +1,410 @@
+"""Reading a video's frames with PyAV: whole, sampled at a rate, a frame
+range, thumbnails with the soundtrack, and the decoded audio+video pair - plus
+the small readers both halves of the media module share (`_threaded`,
+`video_shape`, `stream_seconds`, `to_float32`, `as_frame_samples`).
+
+Split from dw/media.py, which re-exports every name here: callers keep
+importing from `dw.media`, and `dw.media` imports from here, never the other
+way (the `import_cycles` ratchet in scripts/arch_metrics.py). Probing,
+soundtrack decoding, envelopes and faststart stay in dw/media.py.
+"""
+
+import logging
+
+import av
+import numpy
+from av.audio.resampler import AudioResampler
+from av.video.reformatter import VideoReformatter
+from PIL import Image
+
+logger = logging.getLogger("dw")
+
+
+def _threaded(stream):
+    """A video stream set to decode on every core. libav defaults a
+    software h264 decode to one thread; AUTO lets it pick frame and
+    slice threading for the codec. Header-only reads do not call this."""
+    stream.thread_type = "AUTO"
+    return stream
+
+
+def to_float32(samples):
+    """A decoded audio frame (or its ndarray) as float32 in [-1, 1].
+
+    An unsigned format is centred on its midpoint, a signed integer one is
+    scaled by its own maximum, and a float one is only cast - the three
+    conversions every decode here (the probe, the assessment reader) used to
+    spell for itself.
+    """
+    if isinstance(samples, av.AudioFrame):
+        samples = samples.to_ndarray()
+    if samples.dtype.kind == "u":
+        iinfo = numpy.iinfo(samples.dtype)
+        half = (iinfo.max + 1) / 2
+        samples = (samples.astype(numpy.float32) - half) / half
+    elif samples.dtype.kind == "i":
+        samples = samples.astype(numpy.float32) / numpy.iinfo(samples.dtype).max
+    return samples.astype(numpy.float32)
+
+
+def as_frame_samples(samples, channels):
+    """One decoded audio frame as a (samples, channels) array.
+
+    A planar format decodes to (channels, samples); a packed one decodes to
+    (1, samples * channels) interleaved. Both have to become a run of
+    samples before they can be cut on a second boundary, or a stereo packed
+    frame would be counted as twice as much time as it holds.
+    """
+    if samples.ndim == 1:
+        return samples[:, numpy.newaxis]
+    if samples.shape[0] == channels and channels > 1:
+        return samples.T
+    if samples.shape[0] == 1 and channels > 1:
+        return samples.reshape(-1, channels)
+    return samples.T if samples.shape[0] < samples.shape[1] else samples
+
+
+def stream_seconds(stream):
+    """A stream's own reported duration in seconds, or None."""
+    if stream is None or stream.duration is None or stream.time_base is None:
+        return None
+    return float(stream.duration * stream.time_base)
+
+
+def video_shape(path):
+    """Frame count, fps and size, from the container's own headers where
+    they are written and by counting otherwise."""
+    with av.open(path) as container:
+        if not container.streams.video:
+            raise ValueError(f"{path} has no video stream")
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        count = int(stream.frames) if stream.frames else None
+        if count is None:
+            count = sum(1 for _ in container.decode(_threaded(stream)))
+        return {
+            "frame_count": count,
+            "fps": fps,
+            "width": int(stream.width),
+            "height": int(stream.height),
+        }
+
+
+def read_frames(path, indexes, fit=None):
+    """The frames at these indexes, as {index: PIL image}, in one forward
+    pass that seeks to the keyframe before each wanted frame rather than
+    decoding from the top. Decodes are dropped as soon as they are past.
+
+    `fit(image, index)`, when given, is applied to each frame as it is
+    decoded, so a caller tiling many frames never holds one at source size.
+
+    This assumes a constant frame rate, which every file this engine writes
+    has (`encode_video` / `export_to_video` write a fixed `fps`): a
+    `backward=True` seek lands on the keyframe at or before the target
+    timestamp, and `frame.pts * stream.time_base` converts that keyframe's
+    own presentation time back to an exact frame index (`round(seconds *
+    fps)`) - verified against PyAV 18.1's actual seek landings (a
+    single-keyframe short clip, where every seek lands on frame 0; a `g=10`
+    multi-keyframe clip, where a seek to frame 95 lands exactly on frame 90;
+    and a clip whose packets carry a 5-frame pts offset - an edit list or a
+    non-zero start, which real muxers write - where the raw pts arithmetic
+    landed 5 frames off until it was anchored on `stream.start_time`).
+    `start_pts` is that anchor: pts is a timestamp against the *container's*
+    clock, not a frame count from this stream's first frame, so it has to be
+    zeroed against wherever this stream actually starts before it means a
+    frame index. `position` is then a plain frame counter from that
+    landing, decoding forward to the target and dropping what is skipped
+    past.
+    """
+    wanted = sorted(set(int(i) for i in indexes))
+    found = {}
+    with av.open(path) as container:
+        # Not _threaded: frame threads hold frames in flight, and a backward
+        # seek after a decoded frame then yields stale ones (tests/test_media_decode_threads.py)
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        start_pts = stream.start_time if stream.start_time is not None else 0
+        position = 0  # index of the next frame decode() will yield
+        # One decode generator for every target: a fresh `decode()` per
+        # target restarts from a demuxer already at EOF when the previous
+        # target sat on the last packets, and raises EOFError (#654)
+        decoded = container.decode(stream)
+        for target in wanted:
+            if _seek_needed(target, position, fps):
+                # seek back or a long way forward: land on the keyframe at
+                # or before the target, then read up to it
+                _seek_before(container, stream, target, fps, start_pts)
+                position = None
+            recovered = False
+            for frame in decoded:
+                if position is None:
+                    # first frame after a seek says where we landed
+                    position = _landed_at(frame, stream, fps, start_pts)
+                    if position > target and not recovered:
+                        # Landed past the target: the keyframe estimate was
+                        # wrong for this file (off-rate or VFR). Reading on
+                        # would scan to EOF and blame the caller; read from
+                        # the top once instead, which is always correct.
+                        container.seek(start_pts, stream=stream, backward=True)
+                        position = None
+                        recovered = True
+                        continue
+                if position == target:
+                    image = frame.to_image()
+                    found[target] = fit(image, target) if fit is not None else image
+                    position += 1
+                    break
+                position += 1
+        missing = [i for i in wanted if i not in found]
+        if missing:
+            raise ValueError(f"could not decode frame(s) {missing} of {path}")
+    return found
+
+
+def sample_frames(path, fps, duration, size, crop=False):
+    """A clip sampled at `fps` for `duration` seconds, as a numpy array.
+
+    Frame k (of int(fps * duration), as upstream MMAudio truncates) is source
+    frame round(k / fps * source_fps); indexes past the clip's last frame are
+    dropped, so a short clip returns fewer frames, and an up-rate repeats
+    some. Each frame is fitted as it decodes, so none is held at source size.
+
+    `crop=False` is MMAudio's CLIP input (8 fps): bicubic to size x size,
+    uint8 (N, size, size, 3). `crop=True` is its Synchformer input (25 fps,
+    224): bicubic to a short side of `size`, centre crop (torchvision's
+    CenterCrop rounding), float32 (N, size, size, 3) in [-1, 1] (mean 0.5,
+    std 0.5). After mmaudio/eval_utils.py `load_video` at commit 974010a0.
+    """
+    if fps <= 0 or duration <= 0 or size <= 0:
+        raise ValueError("fps, duration and size must be positive")
+    shape = video_shape(path)  # raises for a file with no video stream
+    if not shape["fps"]:
+        raise ValueError(f"{path} declares no frame rate")
+    indexes = [round(k / fps * shape["fps"]) for k in range(int(fps * duration))]
+    indexes = [i for i in indexes if i < shape["frame_count"]]
+
+    def fit(image, _index):
+        if crop:
+            scale = size / min(image.size)
+            width, height = (max(size, round(side * scale)) for side in image.size)
+            image = image.resize((width, height), Image.BICUBIC)
+            left, top = (int(round((side - size) / 2.0)) for side in (width, height))
+            return image.crop((left, top, left + size, top + size))
+        return image.resize((size, size), Image.BICUBIC)
+
+    found = read_frames(path, indexes, fit=fit) if indexes else {}
+    frames = (
+        numpy.stack([numpy.asarray(found[i]) for i in indexes])
+        if indexes
+        else (numpy.zeros((0, size, size, 3), numpy.uint8))
+    )
+    return frames.astype(numpy.float32) / 127.5 - 1 if crop else frames
+
+
+def _seek_needed(target, position, fps):
+    """Whether reaching frame `target` from `position` takes a seek: going
+    back, or a long way forward (more than two seconds of decoding)."""
+    return target < position or target - position > 2 * (int(fps) if fps else 24)
+
+
+def _seek_before(container, stream, target, fps, start_pts):
+    """Land on the keyframe at or before frame `target`. The seek target is
+    a container timestamp too, so it needs the same `start_pts` anchor."""
+    seconds = target / fps if fps else 0.0
+    container.seek(
+        int(seconds / stream.time_base) + start_pts,
+        stream=stream,
+        backward=True,
+    )
+
+
+def _landed_at(frame, stream, fps, start_pts):
+    """The frame index of the first frame decoded after a seek."""
+    if not fps or frame.pts is None:
+        return 0
+    return int(round(float((frame.pts - start_pts) * stream.time_base) * fps))
+
+
+class ShortFrameRange(ValueError):
+    """`read_frame_range` reached the end of the file before `stop`;
+    `decoded` is the frame index the decode had reached."""
+
+    def __init__(self, path, start, stop, decoded):
+        super().__init__(
+            f"could not decode frames {start}..{stop - 1} of {path}: the file "
+            f"ended after {decoded} frames"
+        )
+        self.decoded = decoded
+
+
+def read_frame_range(path, start, stop):
+    """The frames `[start, stop)` of `path` as one (n, height, width, 3)
+    uint8 array, from one keyframe seek and one forward decode.
+
+    `read_frames`' seek, for a run of frames rather than a set: the same
+    `start_time` anchor, the same read-from-the-top fallback when the seek
+    lands past `start`, and one decode generator (#654). Each frame is
+    converted to `rgb24` exactly as `decode_audio_video` converts it, so the
+    run is byte for byte what a full decode holds at those indexes, without
+    the rest of the file ever being resident (#695).
+
+    Raises `ShortFrameRange` when the file ends before `stop`.
+    """
+    start, stop = int(start), int(stop)
+    if start < 0 or stop <= start:
+        raise ValueError(
+            f"read_frame_range needs 0 <= start < stop, got {start} and {stop}"
+        )
+    out = None
+    with av.open(path) as container:
+        # Not _threaded: frame threads hold frames in flight, and a backward
+        # seek after a decoded frame then yields stale ones (tests/test_media_decode_threads.py)
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate) if stream.average_rate else None
+        start_pts = stream.start_time if stream.start_time is not None else 0
+        position = 0
+        decoded = container.decode(stream)
+        if _seek_needed(start, position, fps):
+            _seek_before(container, stream, start, fps, start_pts)
+            position = None
+        recovered = False
+        for frame in decoded:
+            if position is None:
+                position = _landed_at(frame, stream, fps, start_pts)
+                if position > start and not recovered:
+                    # Landed past the start: the keyframe estimate was wrong
+                    # for this file; read from the top once instead
+                    container.seek(start_pts, stream=stream, backward=True)
+                    position = None
+                    recovered = True
+                    continue
+            if position >= start:
+                picture = frame.to_ndarray(format="rgb24")
+                if out is None:
+                    out = numpy.empty((stop - start,) + picture.shape, numpy.uint8)
+                out[position - start] = picture
+            position += 1
+            if position >= stop:
+                return out
+    raise ShortFrameRange(path, start, stop, position or 0)
+
+
+def count_video_frames(path):
+    """The picture frame count of `path`, by decoding every frame rather
+    than reading the header. Nothing is held but the frame in hand."""
+    with av.open(path) as container:
+        return sum(1 for _ in container.decode(_threaded(container.streams.video[0])))
+
+
+def decode_audio_video(handle):
+    """A path or file object's picture and soundtrack, decoded in one pass.
+
+    Returns (frames, audio, sample_rate, frame_rate): the frames as RGB PIL
+    images, the track as float32 (channels, samples) - planar float, the
+    layout `AudioVideo` carries - or None when there is none, the audio
+    stream's rate (None with no audio stream) and the picture's declared
+    rate (None when it states none). The codec's padding is the caller's to
+    fit away; building the `AudioVideo` is too.
+    """
+    frames = []
+    chunks = []
+    sample_rate = None
+
+    with av.open(handle) as container:
+        video_stream = _threaded(container.streams.video[0])
+        frame_rate = (
+            float(video_stream.average_rate) if video_stream.average_rate else None
+        )
+        streams = [video_stream]
+        if container.streams.audio:
+            audio_stream = container.streams.audio[0]
+            streams.append(audio_stream)
+            sample_rate = audio_stream.rate
+            resampler = AudioResampler(format="fltp")
+
+        for frame in container.decode(*streams):
+            if isinstance(frame, av.VideoFrame):
+                frames.append(Image.fromarray(frame.to_ndarray(format="rgb24")))
+            else:
+                chunks.extend(f.to_ndarray() for f in resampler.resample(frame))
+
+        if sample_rate is not None:
+            chunks.extend(f.to_ndarray() for f in resampler.resample(None))
+
+    audio = to_float32(numpy.concatenate(chunks, axis=1)) if chunks else None
+    return frames, audio, sample_rate, frame_rate
+
+
+def decode_rgb_frames(path):
+    """Every picture frame of `path` as an (height, width, 3) uint8 array,
+    in order."""
+    with av.open(path) as container:
+        return [
+            frame.to_ndarray(format="rgb24")
+            for frame in container.decode(_threaded(container.streams.video[0]))
+        ]
+
+
+def iter_rgb_frames(path):
+    """The picture frames of `path` as (height, width, 3) uint8 arrays, one at
+    a time, so a caller can stop at the frame it is looking for."""
+    with av.open(path) as container:
+        for frame in container.decode(_threaded(container.streams.video[0])):
+            yield frame.to_ndarray(format="rgb24")
+
+
+def read_thumbnails_and_track(
+    path, thumb_width, thumb_height, look=None, look_width=128, look_height=72
+):
+    """Stream a file once into grey thumbnails and its soundtrack.
+
+    Each decoded picture frame is reduced to a `thumb_height` x `thumb_width`
+    grey array as it arrives and then dropped, so memory holds thumbnails,
+    not pictures. With `look`, each frame is also reformatted to a
+    `look_height` x `look_width` rgb24 array and handed to it at once, and
+    only what it returns is kept (#1031). Returns (thumbs, chunks, fps,
+    video_seconds, audio_seconds, sample_rate, looks): the thumbnails as a
+    list, the track as a list of float32 (samples, channels) chunks, the
+    streams' own rates and durations (None where a stream is absent or
+    states none), and `look`'s results as a list (empty without one).
+    """
+    thumbs = []
+    looks = []
+    chunks = []
+    # Its own scaler: frame.reformat shares one, and alternating two output
+    # sizes through it rebuilds the context every frame - 10x the cost
+    look_scaler = VideoReformatter()
+    with av.open(path) as container:
+        video = (
+            _threaded(container.streams.video[0]) if container.streams.video else None
+        )
+        audio = container.streams.audio[0] if container.streams.audio else None
+        if video is None and audio is None:
+            raise ValueError(f"{path} has neither a video nor an audio stream")
+        fps = float(video.average_rate) if video and video.average_rate else None
+        video_seconds = stream_seconds(video)
+        audio_seconds = stream_seconds(audio)
+        channels = int(audio.channels) if audio is not None else 0
+        streams = [s for s in (video, audio) if s is not None]
+        for frame in container.decode(*streams):
+            if isinstance(frame, av.VideoFrame):
+                thumbs.append(
+                    frame.reformat(
+                        width=thumb_width, height=thumb_height, format="gray"
+                    ).to_ndarray()[:thumb_height, :thumb_width]
+                )
+                if look is not None:
+                    looks.append(
+                        look(
+                            look_scaler.reformat(
+                                frame,
+                                width=look_width,
+                                height=look_height,
+                                format="rgb24",
+                            ).to_ndarray()[:look_height, :look_width]
+                        )
+                    )
+            elif isinstance(frame, av.AudioFrame):
+                chunks.append(as_frame_samples(to_float32(frame), channels))
+        sample_rate = int(audio.rate) if audio is not None else None
+    return thumbs, chunks, fps, video_seconds, audio_seconds, sample_rate, looks
diff --git a/dw/pipeline_processors/h3_mask.py b/dw/pipeline_processors/h3_mask.py
index e602dc36..6f90172d 100644
--- a/dw/pipeline_processors/h3_mask.py
+++ b/dw/pipeline_processors/h3_mask.py
@@ -22,27 +22,26 @@
   touched.
 
 The refine block (unchanged otherwise) hands its re-noise on as
-`REFINE_ROW_NOISE`. This module puts the blocks in and holds the mask-to-rows
-arithmetic (numpy, with Pillow's luma conversion, torch's adaptive max pool and
-scipy's dilation imported where they run); the blocks are dw/pipeline_processors/h3_mask_steps.py,
-imported in `blocks()` only, since it imports diffusers when it loads (#790).
+`REFINE_ROW_NOISE`. This module puts the blocks in; the mask-to-rows
+arithmetic is dw/pipeline_processors/h3_mask_cells.py (re-exported here), and
+the blocks are dw/pipeline_processors/h3_mask_steps.py, imported in `blocks()`
+only, since it imports diffusers when it loads (#790).
 The argument rules shared with validation are
 dw/pipeline_processors/h3_rules.py (`mask_problems`, `media_problems`).
 """
 
 import logging
 
-import numpy as np
 
 from .h3_hold import core_denoise_sequences
 from .h3_rules import (
     BLEND_AFTER,
     BLEND_BLOCK,
-    MASK_THRESHOLD,
     REFINE_BEFORE,
     SOURCE_BEFORE,
     SOURCE_BLOCK,
 )
+from .h3_mask_cells import binarized, keep_rows, regenerate_cells  # noqa: F401 - re-exported
 
 logger = logging.getLogger("dw")
 
@@ -110,77 +109,3 @@ def edits_regions(pipeline):
         ):
             return True
     return False
-
-
-def binarized(mask):
-    """`(n, h, w)` bool - True to regenerate - from a `mask_image` (a PIL image,
-    n = 1) or `(n, h, w, 3|4)` / `(n, h, w)` uint8 `mask_video` frames. Every
-    frame goes through Pillow's L conversion, the one remove_object's
-    `binarize_mask` uses, and is white at or above `MASK_THRESHOLD`, so both
-    masks binarize by one rule."""
-    from PIL import Image
-
-    if isinstance(mask, Image.Image):
-        images = [mask]
-    else:
-        images = [Image.fromarray(frame) for frame in np.asarray(mask)]
-    luma = np.stack([np.asarray(image.convert("L")) for image in images])
-    return luma >= MASK_THRESHOLD
-
-
-def _pool(mask, cells):
-    """`mask` max-pooled onto `cells` (t, h, w) cells by torch's adaptive max
-    pool, cell i of an axis covering pixels floor(i * n / cells) up to
-    ceil((i + 1) * n / cells) - so a pixel on a boundary counts toward both
-    cells it touches. torch is imported here, on first use, so that loading
-    this module (at pipeline load, and by validation) does not."""
-    import torch
-    import torch.nn.functional as F
-
-    grid = torch.from_numpy(np.ascontiguousarray(mask, dtype=np.float32))
-    pooled = F.adaptive_max_pool3d(grid[None, None], cells)[0, 0]
-    return pooled.numpy() > 0
-
-
-def _dilate(grid, grow):
-    """`grid` widened by `grow` cells along every axis, diagonals included (a
-    cube structuring element), clipped at the edges. scipy reads 0 iterations
-    as "until nothing changes", so `grow == 0` returns the grid as it is."""
-    if grow == 0:
-        return grid
-    from scipy.ndimage import binary_dilation
-
-    structure = np.ones((3,) * grid.ndim, dtype=bool)
-    return binary_dilation(grid, structure=structure, iterations=grow)
-
-
-def regenerate_cells(
-    mask, latent_frames, latent_height, latent_width, patch_size, grow
-):
-    """`(t, h, w)` bool over the patch-row grid - True where a row regenerates -
-    from an `(n, height, width)` bool pixel mask (n = 1 for a `mask_image`,
-    which covers every frame).
-
-    A latent frame covers the pixel frames proportional to it, a patch cell
-    `16 * patch` pixels; a cell regenerates if any pixel it covers is white,
-    then the grid is dilated by `grow` cells. The grid flattens frame-major then
-    row-major, the order `patchify_video_latents` packs rows in.
-    """
-    patch_t, patch_h, patch_w = patch_size
-    cells = (
-        latent_frames // patch_t,
-        latent_height // patch_h,
-        latent_width // patch_w,
-    )
-    grid = np.asarray(mask, dtype=bool)
-    if grid.shape[0] == 1:
-        grid = np.repeat(grid, cells[0], axis=0)
-    return _dilate(_pool(grid, cells), grow)
-
-
-def keep_rows(mask, latent_frames, latent_height, latent_width, patch_size, grow):
-    """The generated video rows a regional edit keeps, as a flat bool array in
-    packed order - the complement of `regenerate_cells`."""
-    return ~regenerate_cells(
-        mask, latent_frames, latent_height, latent_width, patch_size, grow
-    ).reshape(-1)
diff --git a/dw/pipeline_processors/h3_mask_cells.py b/dw/pipeline_processors/h3_mask_cells.py
new file mode 100644
index 00000000..6b2634d1
--- /dev/null
+++ b/dw/pipeline_processors/h3_mask_cells.py
@@ -0,0 +1,92 @@
+"""MiniMax-H3 regional edit: the mask-to-rows arithmetic (#1062).
+
+A `mask_image` or `mask_video` - white regenerates - is binarized at
+`MASK_THRESHOLD`, max-pooled onto the transformer's patch-row grid (a cell any
+white pixel touches regenerates) and dilated by `mask_grow` cells; the kept
+rows are the complement, flat in packed order. numpy only at import: Pillow's
+luma conversion, torch's adaptive max pool and scipy's dilation are imported
+where they run, so validation can load this without them.
+
+Split from dw/pipeline_processors/h3_mask.py so that the blocks module
+(dw/pipeline_processors/h3_mask_steps.py, which `h3_mask.blocks()` imports on
+first use) reads `keep_rows` from here and never imports its own importer -
+the `import_cycles` ratchet in scripts/arch_metrics.py.
+"""
+
+import numpy as np
+
+from .h3_rules import MASK_THRESHOLD
+
+
+def binarized(mask):
+    """`(n, h, w)` bool - True to regenerate - from a `mask_image` (a PIL image,
+    n = 1) or `(n, h, w, 3|4)` / `(n, h, w)` uint8 `mask_video` frames. Every
+    frame goes through Pillow's L conversion, the one remove_object's
+    `binarize_mask` uses, and is white at or above `MASK_THRESHOLD`, so both
+    masks binarize by one rule."""
+    from PIL import Image
+
+    if isinstance(mask, Image.Image):
+        images = [mask]
+    else:
+        images = [Image.fromarray(frame) for frame in np.asarray(mask)]
+    luma = np.stack([np.asarray(image.convert("L")) for image in images])
+    return luma >= MASK_THRESHOLD
+
+
+def _pool(mask, cells):
+    """`mask` max-pooled onto `cells` (t, h, w) cells by torch's adaptive max
+    pool, cell i of an axis covering pixels floor(i * n / cells) up to
+    ceil((i + 1) * n / cells) - so a pixel on a boundary counts toward both
+    cells it touches. torch is imported here, on first use, so that loading
+    this module (at pipeline load, and by validation) does not."""
+    import torch
+    import torch.nn.functional as F
+
+    grid = torch.from_numpy(np.ascontiguousarray(mask, dtype=np.float32))
+    pooled = F.adaptive_max_pool3d(grid[None, None], cells)[0, 0]
+    return pooled.numpy() > 0
+
+
+def _dilate(grid, grow):
+    """`grid` widened by `grow` cells along every axis, diagonals included (a
+    cube structuring element), clipped at the edges. scipy reads 0 iterations
+    as "until nothing changes", so `grow == 0` returns the grid as it is."""
+    if grow == 0:
+        return grid
+    from scipy.ndimage import binary_dilation
+
+    structure = np.ones((3,) * grid.ndim, dtype=bool)
+    return binary_dilation(grid, structure=structure, iterations=grow)
+
+
+def regenerate_cells(
+    mask, latent_frames, latent_height, latent_width, patch_size, grow
+):
+    """`(t, h, w)` bool over the patch-row grid - True where a row regenerates -
+    from an `(n, height, width)` bool pixel mask (n = 1 for a `mask_image`,
+    which covers every frame).
+
+    A latent frame covers the pixel frames proportional to it, a patch cell
+    `16 * patch` pixels; a cell regenerates if any pixel it covers is white,
+    then the grid is dilated by `grow` cells. The grid flattens frame-major then
+    row-major, the order `patchify_video_latents` packs rows in.
+    """
+    patch_t, patch_h, patch_w = patch_size
+    cells = (
+        latent_frames // patch_t,
+        latent_height // patch_h,
+        latent_width // patch_w,
+    )
+    grid = np.asarray(mask, dtype=bool)
+    if grid.shape[0] == 1:
+        grid = np.repeat(grid, cells[0], axis=0)
+    return _dilate(_pool(grid, cells), grow)
+
+
+def keep_rows(mask, latent_frames, latent_height, latent_width, patch_size, grow):
+    """The generated video rows a regional edit keeps, as a flat bool array in
+    packed order - the complement of `regenerate_cells`."""
+    return ~regenerate_cells(
+        mask, latent_frames, latent_height, latent_width, patch_size, grow
+    ).reshape(-1)
diff --git a/dw/pipeline_processors/h3_mask_steps.py b/dw/pipeline_processors/h3_mask_steps.py
index 39c635f1..6c4559be 100644
--- a/dw/pipeline_processors/h3_mask_steps.py
+++ b/dw/pipeline_processors/h3_mask_steps.py
@@ -21,7 +21,7 @@
 
 from ..events import emit_log
 
-from .h3_mask import keep_rows
+from .h3_mask_cells import keep_rows
 from .h3_rules import (
     KEEP_ROWS,
     MASK_GROW_DEFAULT,
diff --git a/dw/pipeline_processors/h3_rules.py b/dw/pipeline_processors/h3_rules.py
index 21e9b39f..6d81216a 100644
--- a/dw/pipeline_processors/h3_rules.py
+++ b/dw/pipeline_processors/h3_rules.py
@@ -8,9 +8,12 @@
 that it imports neither.
 """
 
+import math
+from array import array
+
 from .. import references
 from ..adapter_compatibility import FROM_PRETRAINED_KEY, H3_WORKFLOWS, WORKFLOW_KEY
-from ..variable_constraints import aligned_down
+from ..variable_constraints import aligned, aligned_down
 
 MODULAR_PIPELINE = "ModularPipeline"
 
@@ -128,14 +131,21 @@ def _sigma_problems(arguments):
             f"to 0, and {sigmas!r} is not a list of numbers"
         ]
     problems = []
+    if not all(math.isfinite(s) for s in sigmas):
+        return [f"refine_sigmas must be finite numbers, and {list(sigmas)} is not"]
+    # The scheduler compares the points as float32: two that differ only past
+    # that precision collapse there and are refused after the load, so they
+    # are refused here first
+    as_stored = [float(array("f", [s])[0]) for s in sigmas]
     if len(sigmas) < 2:
         problems.append(
             f"refine_sigmas needs at least 2 points, refine_strength and 0, and "
             f"has {len(sigmas)}"
         )
-    elif any(later >= earlier for earlier, later in zip(sigmas, sigmas[1:])):
+    elif any(later >= earlier for earlier, later in zip(as_stored, as_stored[1:])):
         problems.append(
-            f"refine_sigmas must be strictly decreasing, and {list(sigmas)} is not"
+            f"refine_sigmas must be strictly decreasing (as float32, the "
+            f"scheduler's precision), and {list(sigmas)} is not"
         )
     strength = arguments[REFINE_STRENGTH_INPUT]
     if sigmas and _number(strength) and abs(sigmas[0] - strength) > SIGMA_TOLERANCE:
@@ -661,4 +671,17 @@ def media_problems(name, shape, width, height, num_frames=None):
             f"{name} has {shape[0]} frames, and the step renders num_frames="
             f"{num_frames} - they must match"
         )
+    elif num_frames is not None and name == SOURCE_VIDEO_INPUT:
+        # Off the 17n + 5 grid the pipeline snaps num_frames up and the source
+        # is padded to fit, so the mask drifts in time and the output is longer
+        # than the source: refused here, where the count can still be changed
+        on_grid = aligned(num_frames, RENDER_GRID)
+        if on_grid != num_frames:
+            below = aligned_down(num_frames, RENDER_GRID)
+            problems.append(
+                f"{name} has {shape[0]} frames, off the 17n + 5 grid the step "
+                f"renders on: the pipeline would render {on_grid} and pad the "
+                f"source, drifting the mask - trim the clip to {below} frames or "
+                f"pad it to {on_grid}"
+            )
     return problems
diff --git a/dw/pipeline_processors/pipeline.py b/dw/pipeline_processors/pipeline.py
index 03a6bac2..d0fa70a3 100644
--- a/dw/pipeline_processors/pipeline.py
+++ b/dw/pipeline_processors/pipeline.py
@@ -68,8 +68,7 @@
 # dw.prompt_weighting (transformers) and diffusers.hooks (peft, bitsandbytes) are
 # imported where they are used - at module scope they add seconds to every startup
 
-from ..events import WorkflowCancelled, emit_log, emit_phase, emit_warning, get_context
-from ..media_types import AudioVideo
+from ..events import WorkflowCancelled, emit_log, emit_phase, get_context
 from ..output_extraction import attach_video_frame_rate
 from ..step_cache import component_names, copy_containers
 from ..sparse_attention import (
@@ -78,6 +77,13 @@
     install_sparse_for_call,
     sparse_call,
 )
+from .pipeline_outputs import (  # noqa: F401 - re-exported
+    _component_sample_rate,
+    _denoiser,
+    _diagnose_image_crf_error,
+    attach_audio_sample_rate,
+    warn_if_safety_checker_blanked,
+)
 
 logger = logging.getLogger("dw")
 
@@ -1031,131 +1037,3 @@ def configure_loaded_components(self):
                 if torch_dtype is not None:
                     logger.debug(f"Setting {component_name} torch dtype: {torch_dtype}")
                     component.to(torch_dtype)
-
-
-def _denoiser(pipeline):
-    """The module whose forward is one denoise pass, or None."""
-    from .components import get_cache_transformer
-
-    denoiser = get_cache_transformer(pipeline)
-    return denoiser if denoiser is not None else getattr(pipeline, "unet", None)
-
-
-def warn_if_safety_checker_blanked(output):
-    """Say so when a safety checker replaced a generated image with a black one.
-
-    Stable Diffusion 1.5's checker false-positives readily, and it returns a
-    solid black image rather than an error. Run to run that reads as the seed
-    having no effect - the same result every time - so the reason belongs
-    where the identical images do: the run's warnings, which is the only
-    place a consumer of a `succeeded` job would ever see it.
-
-    Args:
-        output: The pipeline output, which may carry nsfw_content_detected
-    """
-    flags = getattr(output, "nsfw_content_detected", None)
-    if not flags:
-        return
-
-    blanked = sum(1 for flag in flags if flag)
-    if blanked:
-        # emit_warning rather than logger.warning: a blanked image is a
-        # succeeded job whose file is solid black, and a consumer over the
-        # API or MCP sees the job's warnings list and nothing else - the log
-        # line never reaches the one party that cannot tell the picture apart
-        # from a rendered one (#133)
-        emit_warning(
-            f"The safety checker blanked {blanked} of {len(flags)} generated "
-            "images - they are solid black, and no seed will change that. "
-            "Pass 'safety_checker': null in from_pretrained_arguments to "
-            "load the pipeline without it.",
-            kind="safety_checker_blanked",
-            blanked=blanked,
-            images=len(flags),
-        )
-
-
-# Where an audio pipeline's components record the rate they generate at, in
-# the order they are tried. LTX-2's vocoder names it output_sampling_rate,
-# AudioLDM2's vocoder and StableAudio's VAE name it sampling_rate, and
-# Kandinsky 6's MMAudioVAE names it sample_rate (its vocoder carries none).
-# A vocoder's rate comes first: LTX-2's audio VAE works below it
-_SAMPLE_RATE_SOURCES = (
-    ("vocoder", "output_sampling_rate"),
-    ("vocoder", "sampling_rate"),
-    ("audio_vae", "sample_rate"),
-    ("vae", "sampling_rate"),
-)
-
-
-def _component_sample_rate(pipeline, has_audios):
-    for component_name, attribute in _SAMPLE_RATE_SOURCES:
-        if component_name == "vae" and not has_audios:
-            # A video VAE's config is not where an audio rate lives - only an
-            # audio-only pipeline's VAE (StableAudio) reports one there
-            continue
-        config = getattr(getattr(pipeline, component_name, None), "config", None)
-        sample_rate = getattr(config, attribute, None)
-        if sample_rate is not None:
-            return sample_rate
-    return None
-
-
-def attach_audio_sample_rate(pipeline, output):
-    """Record the generating component's sample rate on an output that carries audio.
-
-    Pipelines that generate audio - with their video (LTX-2, on `.audio`) or by
-    itself (AudioLDM2, StableAudio, on `.audios`) - return the waveform without
-    its sample rate; only the vocoder or VAE that produced it knows that. Saving
-    needs the rate, so it travels with the output, and get_artifact_list wraps
-    `.audios` items in an AudioTrack that carries it.
-
-    Args:
-        pipeline: The pipeline that produced the output
-        output: The pipeline output
-    """
-    has_audio = getattr(output, "audio", None) is not None
-    has_audios = getattr(output, "audios", None) is not None
-    if not (has_audio or has_audios):
-        return
-
-    sample_rate = _component_sample_rate(pipeline, has_audios)
-    if sample_rate is None:
-        logger.warning(
-            "Pipeline generated audio but no component reports its sample rate - "
-            "set 'sample_rate' (audio results) or 'audio_sample_rate' (muxed video) "
-            "in the step result to save it correctly"
-        )
-        return
-
-    logger.debug(f"Generated audio has a sample rate of {sample_rate}Hz")
-    output.audio_sample_rate = sample_rate
-
-
-def _diagnose_image_crf_error(error, arguments):
-    """Rewrite diffusers' `image_crf` re-compression error into one that
-    names the actual mismatch, when it is one: an argument the pipeline
-    expects as a still image (`PIL.Image.Image`) instead holds an
-    `AudioVideo` - a video where an image was required. Diffusers' own
-    message suggests `image_crf=0`, which does not fix anything, since the
-    argument still receives a video; the caller needs to derive a still
-    first. Returns None when the error is something else, so the caller
-    re-raises unchanged.
-    """
-    if not isinstance(error, (ValueError, TypeError)):
-        return None
-    if "image_crf" not in str(error) or "re-compression requires" not in str(error):
-        return None
-
-    offending = [
-        name for name, value in arguments.items() if isinstance(value, AudioVideo)
-    ]
-    if not offending:
-        return None
-
-    names = ", ".join(sorted(offending))
-    return ValueError(
-        f"Argument(s) {names} expected an image but received a video. Derive a "
-        f"still from it first - `get_last_frame` or `video_frames` - and pass "
-        f"that instead."
-    )
diff --git a/dw/pipeline_processors/pipeline_outputs.py b/dw/pipeline_processors/pipeline_outputs.py
new file mode 100644
index 00000000..a62b8e10
--- /dev/null
+++ b/dw/pipeline_processors/pipeline_outputs.py
@@ -0,0 +1,144 @@
+"""What a pipeline's output needs after the call: the audio sample rate the
+pipeline's components imply, attached so the result writer knows the rate of
+an `audios` output; the safety-checker warning when every image came back
+blank; and the diagnosis of a CRF error that means a video was passed where
+an image step expected a picture.
+
+Split from dw/pipeline_processors/pipeline.py, which imports from here
+(never the other way) and calls these around `_run_once`.
+"""
+
+import logging
+
+from ..events import emit_warning
+from ..media_types import AudioVideo
+
+logger = logging.getLogger("dw")
+
+
+def _denoiser(pipeline):
+    """The module whose forward is one denoise pass, or None."""
+    from .components import get_cache_transformer
+
+    denoiser = get_cache_transformer(pipeline)
+    return denoiser if denoiser is not None else getattr(pipeline, "unet", None)
+
+
+def warn_if_safety_checker_blanked(output):
+    """Say so when a safety checker replaced a generated image with a black one.
+
+    Stable Diffusion 1.5's checker false-positives readily, and it returns a
+    solid black image rather than an error. Run to run that reads as the seed
+    having no effect - the same result every time - so the reason belongs
+    where the identical images do: the run's warnings, which is the only
+    place a consumer of a `succeeded` job would ever see it.
+
+    Args:
+        output: The pipeline output, which may carry nsfw_content_detected
+    """
+    flags = getattr(output, "nsfw_content_detected", None)
+    if not flags:
+        return
+
+    blanked = sum(1 for flag in flags if flag)
+    if blanked:
+        # emit_warning rather than logger.warning: a blanked image is a
+        # succeeded job whose file is solid black, and a consumer over the
+        # API or MCP sees the job's warnings list and nothing else - the log
+        # line never reaches the one party that cannot tell the picture apart
+        # from a rendered one (#133)
+        emit_warning(
+            f"The safety checker blanked {blanked} of {len(flags)} generated "
+            "images - they are solid black, and no seed will change that. "
+            "Pass 'safety_checker': null in from_pretrained_arguments to "
+            "load the pipeline without it.",
+            kind="safety_checker_blanked",
+            blanked=blanked,
+            images=len(flags),
+        )
+
+
+# Where an audio pipeline's components record the rate they generate at, in
+# the order they are tried. LTX-2's vocoder names it output_sampling_rate,
+# AudioLDM2's vocoder and StableAudio's VAE name it sampling_rate, and
+# Kandinsky 6's MMAudioVAE names it sample_rate (its vocoder carries none).
+# A vocoder's rate comes first: LTX-2's audio VAE works below it
+_SAMPLE_RATE_SOURCES = (
+    ("vocoder", "output_sampling_rate"),
+    ("vocoder", "sampling_rate"),
+    ("audio_vae", "sample_rate"),
+    ("vae", "sampling_rate"),
+)
+
+
+def _component_sample_rate(pipeline, has_audios):
+    for component_name, attribute in _SAMPLE_RATE_SOURCES:
+        if component_name == "vae" and not has_audios:
+            # A video VAE's config is not where an audio rate lives - only an
+            # audio-only pipeline's VAE (StableAudio) reports one there
+            continue
+        config = getattr(getattr(pipeline, component_name, None), "config", None)
+        sample_rate = getattr(config, attribute, None)
+        if sample_rate is not None:
+            return sample_rate
+    return None
+
+
+def attach_audio_sample_rate(pipeline, output):
+    """Record the generating component's sample rate on an output that carries audio.
+
+    Pipelines that generate audio - with their video (LTX-2, on `.audio`) or by
+    itself (AudioLDM2, StableAudio, on `.audios`) - return the waveform without
+    its sample rate; only the vocoder or VAE that produced it knows that. Saving
+    needs the rate, so it travels with the output, and get_artifact_list wraps
+    `.audios` items in an AudioTrack that carries it.
+
+    Args:
+        pipeline: The pipeline that produced the output
+        output: The pipeline output
+    """
+    has_audio = getattr(output, "audio", None) is not None
+    has_audios = getattr(output, "audios", None) is not None
+    if not (has_audio or has_audios):
+        return
+
+    sample_rate = _component_sample_rate(pipeline, has_audios)
+    if sample_rate is None:
+        logger.warning(
+            "Pipeline generated audio but no component reports its sample rate - "
+            "set 'sample_rate' (audio results) or 'audio_sample_rate' (muxed video) "
+            "in the step result to save it correctly"
+        )
+        return
+
+    logger.debug(f"Generated audio has a sample rate of {sample_rate}Hz")
+    output.audio_sample_rate = sample_rate
+
+
+def _diagnose_image_crf_error(error, arguments):
+    """Rewrite diffusers' `image_crf` re-compression error into one that
+    names the actual mismatch, when it is one: an argument the pipeline
+    expects as a still image (`PIL.Image.Image`) instead holds an
+    `AudioVideo` - a video where an image was required. Diffusers' own
+    message suggests `image_crf=0`, which does not fix anything, since the
+    argument still receives a video; the caller needs to derive a still
+    first. Returns None when the error is something else, so the caller
+    re-raises unchanged.
+    """
+    if not isinstance(error, (ValueError, TypeError)):
+        return None
+    if "image_crf" not in str(error) or "re-compression requires" not in str(error):
+        return None
+
+    offending = [
+        name for name, value in arguments.items() if isinstance(value, AudioVideo)
+    ]
+    if not offending:
+        return None
+
+    names = ", ".join(sorted(offending))
+    return ValueError(
+        f"Argument(s) {names} expected an image but received a video. Derive a "
+        f"still from it first - `get_last_frame` or `video_frames` - and pass "
+        f"that instead."
+    )
diff --git a/dw/pipeline_processors/timing.py b/dw/pipeline_processors/timing.py
index 75fc6b36..5cb4dfb7 100644
--- a/dw/pipeline_processors/timing.py
+++ b/dw/pipeline_processors/timing.py
@@ -194,22 +194,23 @@ def _warn_on_slow_decode(self, segment):
         """Say so once per call when a cached pipeline's decode runs for minutes.
 
         The decode is the tail of the call, after the last denoise pass. On a
-        pipeline already loaded, a decode this long is not weights loading: it
-        is a one-off cost of meeting a new shape (a different frame count gives
-        the video decoder a chunk shape it has not run: kernel selection,
-        allocator re-growth) or a memory-pressure slow path. Without a word the
-        consumer sees only `phase_stall` notices (#1116)."""
+        pipeline already loaded, a decode this long is not weights loading;
+        what it is cannot be told from here (a shape the cached pipeline has
+        not run and memory pressure on the decode device are the usual causes),
+        so the warning states the measurement and names those as things to
+        check, never as the cause (#1116, the #1119 rule). Without a word the
+        consumer sees only `phase_stall` notices."""
         if self._load_cached is not True:
             return
         decode = segment.spans()[3]
         if decode is None or decode < _SLOW_DECODE_S:
             return
         emit_warning(
-            f"Decode took {decode:.0f}s with the pipeline already loaded. That "
-            "is far past a steady decode and is not proportional to frame "
-            "count: a one-off cost of a cached pipeline meeting a shape it has "
-            "not run (a different number of frames), or memory pressure on the "
-            "decode device.",
+            f"Decode took {decode:.0f}s with the pipeline already loaded, far "
+            "past a steady decode. The cause is not identified from here: a "
+            "shape this cached pipeline has not run before (a different number "
+            "of frames) and memory pressure on the decode device are the usual "
+            "ones to check.",
             kind="decode_slow",
             decode_s=round(decode, 1),
             step=self.step,
diff --git a/dw/plan_downloads.py b/dw/plan_downloads.py
index ca04fb75..ec50673a 100644
--- a/dw/plan_downloads.py
+++ b/dw/plan_downloads.py
@@ -144,28 +144,7 @@ def _collect_sources(tree, names, variants, urls, files=None):
     """
     if isinstance(tree, dict):
         for lora in tree.get(LORAS_KEY) or []:
-            name = lora.get(MODEL_NAME_KEY) if isinstance(lora, dict) else None
-            if not isinstance(name, str):
-                continue
-            weight = lora.get(WEIGHT_NAME_KEY)
-            entries = []
-            if (
-                files is not None
-                and isinstance(weight, str)
-                and not references.is_ref(references.DEFERRED, weight)
-            ):
-                subfolder = lora.get(SUBFOLDER_KEY)
-                if isinstance(subfolder, str) and subfolder:
-                    weight = f"{subfolder.strip('/')}/{weight}"
-                from .tasks.weights import file_entries
-
-                entries = file_entries(name, weight, None)
-            for entry in entries:
-                key = (entry["repo"], entry["filename"], entry["revision"])
-                if key not in files:
-                    files.append(key)
-            if not entries and name not in names:
-                names.append(name)
+            _collect_lora_source(lora, names, files)
         source = tree.get(FROM_PRETRAINED_KEY)
         if isinstance(source, dict):
             name = source.get(MODEL_NAME_KEY)
@@ -185,6 +164,33 @@ def _collect_sources(tree, names, variants, urls, files=None):
             _collect_sources(value, names, variants, urls, files)
 
 
+def _collect_lora_source(lora, names, files):
+    """One `loras` entry into `files` (its single weight file, when it names
+    one and `files` is collected) or `names` (its whole repo otherwise)."""
+    name = lora.get(MODEL_NAME_KEY) if isinstance(lora, dict) else None
+    if not isinstance(name, str):
+        return
+    weight = lora.get(WEIGHT_NAME_KEY)
+    entries = []
+    if (
+        files is not None
+        and isinstance(weight, str)
+        and not references.is_ref(references.DEFERRED, weight)
+    ):
+        subfolder = lora.get(SUBFOLDER_KEY)
+        if isinstance(subfolder, str) and subfolder:
+            weight = f"{subfolder.strip('/')}/{weight}"
+        from .tasks.weights import file_entries
+
+        entries = file_entries(name, weight, None)
+    for entry in entries:
+        key = (entry["repo"], entry["filename"], entry["revision"])
+        if key not in files:
+            files.append(key)
+    if not entries and name not in names:
+        names.append(name)
+
+
 def _collect_component_overrides(arguments, names):
     """The repos a modular step's `load_components.pretrained_model_name_or_path`
     names: a string for every component, or a dict keyed by component name
diff --git a/dw/tasks/cuts.py b/dw/tasks/cuts.py
index 9c21f2e9..9b5bebae 100644
--- a/dw/tasks/cuts.py
+++ b/dw/tasks/cuts.py
@@ -29,38 +29,32 @@
 shot - and builds nothing.
 """
 
-import difflib
 import logging
 import math
-import re
-import statistics
 
 from ..script_lines import SUSPECT_LEFT_OUT, suspect_runs
 from ..variable_constraints import aligned, aligned_down
 from .registry import register_command
-from ..task_domains import NON_NEGATIVE, POSITIVE, real_number, whole_number
+from ..task_domains import NON_NEGATIVE, POSITIVE, whole_number
 from ..task_problems import cuts_errors, transcript_problem
+from .cuts_lines import (  # noqa: F401 - some re-exported
+    align_lyrics,
+    as_number,
+    COMMAND,
+    is_phrases,
+    lines_of_lyrics,
+    lines_of_phrases,
+    lines_of_transcript,
+    phrase_list,
+)
 
 logger = logging.getLogger("dw")
 
-COMMAND = "plan_cuts"
 
 SEGMENT_BY = ("line", "stanza", "beat")
-# A lyric line that is only a section tag ("[Chorus]") is structure, not a
-# sung line: it breaks a stanza, as a blank line does
-SECTION_TAG = re.compile(r"^\s*\[[^\]]*\]\s*$")
-# Two words are the same word sung, misheard by at most this much
-WORD_SIMILARITY = 0.75
 TIME_PLACES = 4
 
 
-def _number(value, name, required=False):
-    """A float from a number or numeric string; None stays None unless
-    required."""
-    number = real_number(value, name, COMMAND, required=required)
-    return None if number is None else float(number)
-
-
 def _grid_up(frames, grid):
     """The smallest render length on the grid at or above `frames`; `frames`
     itself when there is no modulus. The arithmetic is the template
@@ -99,8 +93,8 @@ def _chunks(transcript, duration):
             start, end = (list(chunk["timestamp"]) + [None, None])[:2]
         else:
             end = chunk.get("end")
-        start = _number(start, f"transcript chunks[{index}].start", required=True)
-        end = _number(end, f"transcript chunks[{index}].end")
+        start = as_number(start, f"transcript chunks[{index}].start", required=True)
+        end = as_number(end, f"transcript chunks[{index}].end")
         row = {"start": start, "end": end, "text": str(chunk.get("text") or "").strip()}
         if chunk.get("suspect"):
             row["suspect"] = str(chunk["suspect"])
@@ -140,14 +134,16 @@ def _beats(beats):
     times = beats
     if isinstance(beats, dict):
         times = beats.get("beats") or []
-        bpm = _number(beats.get("bpm"), "beats.bpm")
-        duration = _number(beats.get("duration_seconds"), "beats.duration_seconds")
+        bpm = as_number(beats.get("bpm"), "beats.bpm")
+        duration = as_number(beats.get("duration_seconds"), "beats.duration_seconds")
     if not isinstance(times, (list, tuple)):
         raise ValueError(
             f"{COMMAND}'s 'beats' is an analyze_beats result or a list of "
             f"seconds, not {type(times).__name__}"
         )
-    times = sorted(_number(time, f"beats[{index}]") for index, time in enumerate(times))
+    times = sorted(
+        as_number(time, f"beats[{index}]") for index, time in enumerate(times)
+    )
     if bpm is None and len(times) >= 2:
         gaps = sorted(b - a for a, b in zip(times, times[1:]) if b > a)
         if gaps:
@@ -155,350 +151,6 @@ def _beats(beats):
     return times, bpm, duration
 
 
-def _lyric_lines(lyrics):
-    """[(text, stanza index)] for the sung lines of the lyrics. A blank line
-    or a section tag on its own line starts a new stanza; neither is a line."""
-    if isinstance(lyrics, str):
-        rows = lyrics.splitlines()
-    elif isinstance(lyrics, (list, tuple)):
-        rows = []
-        for row in lyrics:
-            rows.extend(str(row).splitlines() or [""])
-    else:
-        raise ValueError(
-            f"{COMMAND}'s 'lyrics' is the song's text, one line per line, or a "
-            f"list of lines - not {type(lyrics).__name__}"
-        )
-    lines, stanza, broke = [], 0, False
-    for row in rows:
-        text = row.strip()
-        if not text or SECTION_TAG.match(text):
-            broke = bool(lines)
-            continue
-        if broke:
-            stanza += 1
-            broke = False
-        lines.append((text, stanza))
-    if not lines:
-        raise ValueError(f"{COMMAND}'s 'lyrics' has no sung lines")
-    return lines
-
-
-def _words(text):
-    """The text's words, lower-cased with punctuation dropped."""
-    return [word for word in re.findall(r"[\w']+", text.lower().replace("'", ""))]
-
-
-def _timed_words(chunks):
-    """[(word, start, end)] across the transcript: a chunk's span shared out
-    over its words by length, since a segment chunk carries no word times."""
-    timed = []
-    for chunk in chunks:
-        words = _words(chunk["text"])
-        if not words:
-            continue
-        span = chunk["end"] - chunk["start"]
-        total = sum(len(word) for word in words)
-        at = chunk["start"]
-        for word in words:
-            length = span * len(word) / total
-            timed.append((word, at, at + length))
-            at += length
-    return timed
-
-
-def _similar(a, b):
-    return a == b or difflib.SequenceMatcher(None, a, b).ratio() >= WORD_SIMILARITY
-
-
-def _align_words(lyric_words, heard_words):
-    """{lyric word index: heard word index} - the longest in-order run of
-    words the two share, a word matching one misheard by a little."""
-    n, m = len(lyric_words), len(heard_words)
-    # Longest common subsequence by similarity, filled from the end
-    table = [[0] * (m + 1) for _ in range(n + 1)]
-    same = {}
-    for i in range(n - 1, -1, -1):
-        row, below = table[i], table[i + 1]
-        for j in range(m - 1, -1, -1):
-            if _similar(lyric_words[i], heard_words[j]):
-                same[i, j] = True
-                row[j] = below[j + 1] + 1
-            else:
-                row[j] = max(below[j], row[j + 1])
-    pairs, i, j = {}, 0, 0
-    while i < n and j < m:
-        if same.get((i, j)) and table[i][j] == table[i + 1][j + 1] + 1:
-            pairs[i] = j
-            i += 1
-            j += 1
-        elif table[i + 1][j] >= table[i][j + 1]:
-            i += 1
-        else:
-            j += 1
-    return pairs
-
-
-def _heard_spans(lyric_lines, chunks):
-    """[[start, end] or None] per lyric line - the span of its words the
-    transcript heard, aligned word by word, or None when it heard none of
-    them, and [[start or None] per word of the line] (#805) - the time each
-    lyric word was heard at. A line's span runs no further than the next
-    heard line's start. The word-level alignment stays here, apart from
-    placing the unheard lines."""
-    heard = _timed_words(chunks)
-    lyric_words, owner = [], []
-    for index, (text, _) in enumerate(lyric_lines):
-        for word in _words(text):
-            lyric_words.append(word)
-            owner.append(index)
-    pairs = _align_words(lyric_words, [word for word, _, _ in heard])
-
-    timed = [None] * len(lyric_lines)
-    word_times = [[None] * len(_words(text)) for text, _ in lyric_lines]
-    first_word = {}
-    for lyric_index, line in enumerate(owner):
-        first_word.setdefault(line, lyric_index)
-    for lyric_index, heard_index in pairs.items():
-        line = owner[lyric_index]
-        _, start, end = heard[heard_index]
-        word_times[line][lyric_index - first_word[line]] = start
-        if timed[line] is None:
-            timed[line] = [start, end]
-        else:
-            timed[line][0] = min(timed[line][0], start)
-            timed[line][1] = max(timed[line][1], end)
-
-    known = [index for index, span in enumerate(timed) if span is not None]
-    for a, b in zip(known, known[1:]):
-        timed[a][1] = min(timed[a][1], timed[b][0])
-    return timed, word_times
-
-
-def _line_tokens(text, times, span):
-    """[(token, time)] - the line's whitespace-separated tokens, each with
-    the time its first word was heard at (#805). A line none of whose words
-    were heard is spread evenly over its span; a token that is no word, or
-    whose words were not heard, has time None."""
-    pieces = text.split()
-    counts = [len(_words(piece)) for piece in pieces]
-    if not any(time is not None for time in times):
-        total = sum(1 for count in counts if count)
-        tokens, seen = [], 0
-        for piece, count in zip(pieces, counts):
-            if count and span is not None:
-                at = span[0] + (span[1] - span[0]) * seen / total
-                seen += 1
-            else:
-                at = None
-            tokens.append((piece, at))
-        return tokens
-    tokens, used = [], 0
-    for piece, count in zip(pieces, counts):
-        heard = [t for t in times[used : used + count] if t is not None]
-        used += count
-        tokens.append((piece, heard[0] if heard else None))
-    return tokens
-
-
-def _align_lyrics(lyric_lines, chunks, duration, warnings, min_line_s):
-    """[{start, end, text, stanza}] - the lyrics' lines in their order, timed
-    from the transcript. A line none of whose words were heard is placed
-    between its neighbours, and warned about; when they touch it takes
-    min_line_s from them, so it is still a shot of its own."""
-    timed, word_times = _heard_spans(lyric_lines, chunks)
-    heard_times = [list(times) for times in word_times]
-    known = [index for index, span in enumerate(timed) if span is not None]
-    if not known:
-        warnings.append(
-            f"{COMMAND}: none of the lyrics' words were heard in the transcript "
-            "- the lines are spread evenly over the sung part of the song; "
-            "check the transcript is of this song"
-        )
-    vocal_start = chunks[0]["start"] if chunks else 0.0
-    vocal_end = chunks[-1]["end"] if chunks else duration
-    index = 0
-    while index < len(timed):
-        if timed[index] is not None:
-            index += 1
-            continue
-        run_end = index
-        while run_end < len(timed) and timed[run_end] is None:
-            run_end += 1
-        following = timed[run_end][0] if run_end < len(timed) else None
-        if index > 0:
-            low = timed[index - 1][1]
-        else:
-            low = vocal_start if following is None else min(vocal_start, following)
-        high = following if following is not None else max(vocal_end, low)
-        count = run_end - index
-        # The neighbours took the unheard line's time with its misheard words:
-        # give it back from each side, never more than half a neighbour
-        short = count * min_line_s - (high - low)
-        if short > 1e-9:
-            before = timed[index - 1] if index > 0 else None
-            after = timed[run_end] if run_end < len(timed) else None
-            spare_before = (before[1] - before[0]) / 2 if before else 0.0
-            spare_after = (after[1] - after[0]) / 2 if after else 0.0
-            take_before = min(spare_before, max(short / 2, short - spare_after))
-            take_after = min(spare_after, short - take_before)
-            low -= take_before
-            high += take_after
-            if before:
-                before[1] = low
-            if after:
-                after[0] = high
-        step = (high - low) / count
-        for offset in range(count):
-            timed[index + offset] = [low + offset * step, low + (offset + 1) * step]
-            if known:
-                warnings.append(
-                    f"{COMMAND}: lyric line {index + offset + 1} "
-                    f"({lyric_lines[index + offset][0]!r}) was not heard in the "
-                    f"transcript - placed between its neighbours, at "
-                    f"{timed[index + offset][0]:.2f}-{timed[index + offset][1]:.2f} s"
-                )
-        index = run_end
-    return [
-        {
-            "start": span[0],
-            "end": span[1],
-            "text": text,
-            "stanza": stanza,
-            "tokens": _line_tokens(text, times, span) if known else None,
-        }
-        for span, times, (text, stanza) in zip(timed, heard_times, lyric_lines)
-    ]
-
-
-def _transcript_lines(chunks, stanza_gap):
-    """[{start, end, text, stanza}] - a line per chunk; a silence of at least
-    stanza_gap starts a new stanza."""
-    lines, stanza = [], 0
-    for index, chunk in enumerate(chunks):
-        if not chunk["text"]:
-            continue
-        if lines and chunk["start"] - lines[-1]["end"] >= stanza_gap:
-            stanza += 1
-        lines.append(dict(chunk, stanza=stanza))
-    return lines
-
-
-def _is_phrases(transcript):
-    """Whether this is analyze_phrases' result (#1095): timing with no text,
-    told from a transcript by its 'phrases' key."""
-    return (
-        isinstance(transcript, dict)
-        and "phrases" in transcript
-        and "chunks" not in transcript
-    )
-
-
-def _phrases(transcript):
-    """[{start, end, text}] in seconds, ascending - an analyze_phrases
-    result's phrases, each with no text. A phrase is never suspect."""
-    problem = transcript_problem(transcript)
-    if problem:
-        raise ValueError(problem)
-    parsed = []
-    for index, phrase in enumerate(transcript["phrases"]):
-        if not isinstance(phrase, dict):
-            raise ValueError(
-                f"{COMMAND}: phrase {index} is not a {{start, end}} object"
-            )
-        start = _number(phrase.get("start"), f"phrases[{index}].start", required=True)
-        end = _number(phrase.get("end"), f"phrases[{index}].end", required=True)
-        parsed.append({"start": start, "end": max(end, start), "text": ""})
-    parsed.sort(key=lambda phrase: phrase["start"])
-    return parsed
-
-
-def _phrase_lines(phrases, lyrics, duration, stanza_gap, warnings):
-    """[{start, end, text, stanza, tokens}] from analyze_phrases' phrases.
-    Without lyrics a line per phrase, with no text, and a silence of at least
-    stanza_gap starts a stanza. With lyrics whose lines are as many as the
-    phrases, line n is phrase n; otherwise the counts are warned about, with
-    the analyze_phrases knob to turn, and the lines spread evenly from the
-    first phrase to the last - never paired. A phrase has no word times, so
-    a split piece of one keeps its whole lyric."""
-    if lyrics is None:
-        lines, stanza = [], 0
-        for phrase in phrases:
-            if lines and phrase["start"] - lines[-1]["end"] >= stanza_gap:
-                stanza += 1
-            lines.append(dict(phrase, stanza=stanza, tokens=None))
-        return lines
-    if len(lyrics) == len(phrases):
-        paired = [
-            dict(phrase, text=text, stanza=stanza, tokens=None)
-            for phrase, (text, stanza) in zip(phrases, lyrics)
-        ]
-        _disproportion_warning(paired, warnings)
-        return paired
-    if len(phrases) > len(lyrics):
-        knob = "raise analyze_phrases' 'min_gap_seconds' to bridge more pauses, so the counts match"
-    else:
-        knob = (
-            "lower analyze_phrases' 'min_gap_seconds' to split at shorter "
-            "pauses, or, for legato or reverberant singing whose lines fuse, "
-            "raise its 'floor_db' (less negative, e.g. -30), so the counts match - then "
-            "check the phrases by ear before trusting a one-to-one pairing, since a "
-            "raised floor can match the counts on wrong boundaries"
-        )
-    low = phrases[0]["start"] if phrases else 0.0
-    high = phrases[-1]["end"] if phrases else duration
-    warnings.append(
-        f"{COMMAND}: the lyrics have {len(lyrics)} line(s) and analyze_phrases "
-        f"found {len(phrases)} phrase(s) - the lines are spread evenly over "
-        f"{low:.2f}-{high:.2f} s, not paired with the phrases; {knob}"
-    )
-    step = (high - low) / len(lyrics)
-    return [
-        {
-            "start": low + index * step,
-            "end": low + (index + 1) * step,
-            "text": text,
-            "stanza": stanza,
-            "tokens": None,
-        }
-        for index, (text, stanza) in enumerate(lyrics)
-    ]
-
-
-# A paired phrase this far from the median phrase length is likely a bad
-# boundary (#1095): on a fused legato verse, a raised floor_db can split a
-# breath off as a "phrase" and leave another line spanning two.
-DISPROPORTION = 4.0
-
-
-def _disproportion_warning(paired, warnings):
-    """Warn when a lyric line is paired one to one with a phrase under a
-    quarter, or over four times, the median phrase duration. The pairing
-    stands; the warning is advice to check the boundaries by ear."""
-    lengths = [line["end"] - line["start"] for line in paired]
-    if len(lengths) < 2:
-        return
-    median = statistics.median(lengths)
-    if median <= 0:
-        return
-    odd = [
-        f"line {index + 1} ({line['text']!r}, {line['end'] - line['start']:.2f} s)"
-        for index, line in enumerate(paired)
-        if not median / DISPROPORTION
-        <= line["end"] - line["start"]
-        <= median * DISPROPORTION
-    ]
-    if odd:
-        warnings.append(
-            f"{COMMAND}: the lyric lines are paired one to one with "
-            f"analyze_phrases' phrases, but {', '.join(odd)} "
-            f"{'sits' if len(odd) == 1 else 'sit'} on a phrase "
-            f"under 1/{DISPROPORTION:g} or over {DISPROPORTION:g}x the median "
-            f"phrase ({median:.2f} s) - the phrase boundaries may be wrong; "
-            "check them by ear"
-        )
-
-
 def _units(lines, segment_by):
     """The vocal spans scenes are cut around: a line each, or a stanza."""
     units = []
@@ -901,21 +553,21 @@ def _parsed_arguments(transcript, beats, segment_by, **raw):
     from ..task_problems import cuts_problems
 
     # An explicit 0 is a value (every silence counts); only an absent gap takes 2.0.
-    gap = _number(raw["min_gap_seconds"], "min_gap_seconds")
+    gap = as_number(raw["min_gap_seconds"], "min_gap_seconds")
     gap = 2.0 if gap is None else gap
     args = types.SimpleNamespace(
-        fps=_number(raw["fps"], "fps", required=True),
-        duration_s=_number(raw["duration_s"], "duration_s"),
-        min_scene_s=_number(raw["min_scene_s"], "min_scene_s") or 0.0,
-        max_scene_s=_number(raw["max_scene_s"], "max_scene_s"),
-        vocal_tail_s=_number(raw["vocal_tail_s"], "vocal_tail_s") or 0.0,
+        fps=as_number(raw["fps"], "fps", required=True),
+        duration_s=as_number(raw["duration_s"], "duration_s"),
+        min_scene_s=as_number(raw["min_scene_s"], "min_scene_s") or 0.0,
+        max_scene_s=as_number(raw["max_scene_s"], "max_scene_s"),
+        vocal_tail_s=as_number(raw["vocal_tail_s"], "vocal_tail_s") or 0.0,
         min_gap_seconds=gap,
         include_instrumental_gaps=bool(raw["include_instrumental_gaps"]),
         modulus=whole_number(raw["modulus"], "modulus", COMMAND),
         remainder=whole_number(raw["remainder"], "remainder", COMMAND),
         min_frames=whole_number(raw["min_frames"], "min_frames", COMMAND),
         max_frames=whole_number(raw["max_frames"], "max_frames", COMMAND),
-        lead_s=_number(raw["lead_s"], "lead_s"),
+        lead_s=as_number(raw["lead_s"], "lead_s"),
     )
     check_arguments(
         COMMAND,
@@ -958,9 +610,9 @@ def _song_length(args, transcript, beats, beats_duration, warnings):
     long, else the analyze_beats result, else the phrases' duration_seconds;
     failing those the transcript's last end does, and is warned about."""
     duration = args.duration_s or beats_duration
-    if _is_phrases(transcript):
-        chunks = _phrases(transcript)
-        duration = duration or _number(
+    if is_phrases(transcript):
+        chunks = phrase_list(transcript)
+        duration = duration or as_number(
             transcript.get("duration_seconds"), "transcript.duration_seconds"
         )
     else:
@@ -1049,6 +701,66 @@ def _shots(framed, grid, args, warnings):
     return shots
 
 
+def _planned_lines(chunks, lyrics, phrases, duration, args, warnings):
+    """The sung lines, timed and clamped to the song: phrase-paired lyrics,
+    lyrics aligned onto the transcript, or the transcript's own chunks (each
+    the branch `plan_cuts` documents). `lyrics` is None when none were given."""
+    if phrases:
+        lines = lines_of_phrases(
+            chunks,
+            lines_of_lyrics(lyrics) if lyrics is not None else None,
+            duration,
+            args.min_gap_seconds,
+            warnings,
+        )
+        if not lines:
+            warnings.append(
+                f"{COMMAND}: analyze_phrases found no sung phrases - the song is "
+                "planned as instrumental"
+            )
+    elif lyrics is not None:
+        lines = align_lyrics(
+            lines_of_lyrics(lyrics),
+            chunks,
+            duration,
+            warnings,
+            max(args.min_scene_s, 0.5),
+        )
+    else:
+        lines = lines_of_transcript(chunks, args.min_gap_seconds)
+        if not lines:
+            warnings.append(
+                f"{COMMAND}: the transcript has no sung lines - the song is "
+                "planned as instrumental"
+            )
+    for line in lines:
+        line["start"] = min(max(line["start"], 0.0), duration)
+        line["end"] = min(max(line["end"], line["start"]), duration)
+    return lines
+
+
+def _planned_shots(
+    lines, beat_times, duration, total_frames, args, segment_by, snap_to_beats, warnings
+):
+    """The shots from the timed lines: scenes by line, stanza or beat, split
+    over `max_scene_s`, snapped and merged, then framed and raised to the
+    render grid (each the step `plan_cuts` documents)."""
+    if segment_by == "beat":
+        scenes = _scenes_by_beats(lines, beat_times, duration, args)
+    else:
+        scenes = _scenes_by_units(_units(lines, segment_by), duration, args, warnings)
+    scenes = _split_long(scenes, beat_times, args.max_scene_s, warnings)
+    if snap_to_beats:
+        scenes = _snap(scenes, beat_times, warnings)
+    scenes = _merge_short(scenes, args.min_scene_s)
+
+    framed = _frames(scenes, args.fps, total_frames, warnings)
+    grid = _render_grid(args)
+    beat_frames = [int(round(beat * args.fps)) for beat in beat_times]
+    framed = _split_over_max(framed, grid, beat_frames, args.fps, warnings)
+    return _shots(framed, grid, args, warnings)
+
+
 def plan_cuts(
     transcript,
     lyrics=None,
@@ -1161,7 +873,7 @@ def plan_cuts(
     warnings = []
     duration, chunks = _song_length(args, transcript, beats, beats_duration, warnings)
     beat_times = [beat for beat in beat_times if 0.0 < beat < duration]
-    phrases = _is_phrases(transcript)
+    phrases = is_phrases(transcript)
     if not phrases:
         # Phrases have no text, so none is ever suspect (#1095)
         warnings.extend(_suspect_warnings(chunks))
@@ -1170,49 +882,21 @@ def plan_cuts(
         isinstance(lyrics, str) and not lyrics.strip()
     )
 
-    if phrases:
-        lines = _phrase_lines(
-            chunks,
-            _lyric_lines(lyrics) if given_lyrics else None,
-            duration,
-            args.min_gap_seconds,
-            warnings,
-        )
-        if not lines:
-            warnings.append(
-                f"{COMMAND}: analyze_phrases found no sung phrases - the song is "
-                "planned as instrumental"
-            )
-    elif given_lyrics:
-        lines = _align_lyrics(
-            _lyric_lines(lyrics), chunks, duration, warnings, max(args.min_scene_s, 0.5)
-        )
-    else:
-        lines = _transcript_lines(chunks, args.min_gap_seconds)
-        if not lines:
-            warnings.append(
-                f"{COMMAND}: the transcript has no sung lines - the song is "
-                "planned as instrumental"
-            )
-    for line in lines:
-        line["start"] = min(max(line["start"], 0.0), duration)
-        line["end"] = min(max(line["end"], line["start"]), duration)
-
-    if segment_by == "beat":
-        scenes = _scenes_by_beats(lines, beat_times, duration, args)
-    else:
-        scenes = _scenes_by_units(_units(lines, segment_by), duration, args, warnings)
-    scenes = _split_long(scenes, beat_times, args.max_scene_s, warnings)
-    if snap_to_beats:
-        scenes = _snap(scenes, beat_times, warnings)
-    scenes = _merge_short(scenes, args.min_scene_s)
+    lines = _planned_lines(
+        chunks, lyrics if given_lyrics else None, phrases, duration, args, warnings
+    )
 
     total_frames = int(round(duration * args.fps))
-    framed = _frames(scenes, args.fps, total_frames, warnings)
-    grid = _render_grid(args)
-    beat_frames = [int(round(beat * args.fps)) for beat in beat_times]
-    framed = _split_over_max(framed, grid, beat_frames, args.fps, warnings)
-    shots = _shots(framed, grid, args, warnings)
+    shots = _planned_shots(
+        lines,
+        beat_times,
+        duration,
+        total_frames,
+        args,
+        segment_by,
+        snap_to_beats,
+        warnings,
+    )
 
     for message in warnings:
         emit_warning(message, kind="plan_cuts", command=COMMAND)
diff --git a/dw/tasks/cuts_lines.py b/dw/tasks/cuts_lines.py
new file mode 100644
index 00000000..c634863d
--- /dev/null
+++ b/dw/tasks/cuts_lines.py
@@ -0,0 +1,380 @@
+"""plan_cuts' lines: when each sung line starts and ends, from the three
+timing sources the task takes - a transcript's chunks, the song's own lyrics
+aligned word by word onto those chunks, or analyze_phrases' phrases (#1095),
+which pair with lyric lines one to one when the counts match and are spread
+evenly when they do not.
+
+Split from dw/tasks/cuts.py, which imports from here (never the other way):
+cuts.py turns these lines into scenes, frames and a render grid.
+"""
+
+import difflib
+import logging
+import re
+import statistics
+
+from ..task_domains import real_number
+from ..task_problems import transcript_problem
+
+logger = logging.getLogger("dw")
+
+
+COMMAND = "plan_cuts"
+
+# A lyric line that is only a section tag ("[Chorus]") is structure, not a
+# sung line: it breaks a stanza, as a blank line does
+SECTION_TAG = re.compile(r"^\s*\[[^\]]*\]\s*$")
+
+# Two words are the same word sung, misheard by at most this much
+WORD_SIMILARITY = 0.75
+
+
+def as_number(value, name, required=False):
+    """A float from a number or numeric string; None stays None unless
+    required."""
+    number = real_number(value, name, COMMAND, required=required)
+    return None if number is None else float(number)
+
+
+def lines_of_lyrics(lyrics):
+    """[(text, stanza index)] for the sung lines of the lyrics. A blank line
+    or a section tag on its own line starts a new stanza; neither is a line."""
+    if isinstance(lyrics, str):
+        rows = lyrics.splitlines()
+    elif isinstance(lyrics, (list, tuple)):
+        rows = []
+        for row in lyrics:
+            rows.extend(str(row).splitlines() or [""])
+    else:
+        raise ValueError(
+            f"{COMMAND}'s 'lyrics' is the song's text, one line per line, or a "
+            f"list of lines - not {type(lyrics).__name__}"
+        )
+    lines, stanza, broke = [], 0, False
+    for row in rows:
+        text = row.strip()
+        if not text or SECTION_TAG.match(text):
+            broke = bool(lines)
+            continue
+        if broke:
+            stanza += 1
+            broke = False
+        lines.append((text, stanza))
+    if not lines:
+        raise ValueError(f"{COMMAND}'s 'lyrics' has no sung lines")
+    return lines
+
+
+def _words(text):
+    """The text's words, lower-cased with punctuation dropped."""
+    return [word for word in re.findall(r"[\w']+", text.lower().replace("'", ""))]
+
+
+def _timed_words(chunks):
+    """[(word, start, end)] across the transcript: a chunk's span shared out
+    over its words by length, since a segment chunk carries no word times."""
+    timed = []
+    for chunk in chunks:
+        words = _words(chunk["text"])
+        if not words:
+            continue
+        span = chunk["end"] - chunk["start"]
+        total = sum(len(word) for word in words)
+        at = chunk["start"]
+        for word in words:
+            length = span * len(word) / total
+            timed.append((word, at, at + length))
+            at += length
+    return timed
+
+
+def _similar(a, b):
+    return a == b or difflib.SequenceMatcher(None, a, b).ratio() >= WORD_SIMILARITY
+
+
+def _align_words(lyric_words, heard_words):
+    """{lyric word index: heard word index} - the longest in-order run of
+    words the two share, a word matching one misheard by a little."""
+    n, m = len(lyric_words), len(heard_words)
+    # Longest common subsequence by similarity, filled from the end
+    table = [[0] * (m + 1) for _ in range(n + 1)]
+    same = {}
+    for i in range(n - 1, -1, -1):
+        row, below = table[i], table[i + 1]
+        for j in range(m - 1, -1, -1):
+            if _similar(lyric_words[i], heard_words[j]):
+                same[i, j] = True
+                row[j] = below[j + 1] + 1
+            else:
+                row[j] = max(below[j], row[j + 1])
+    pairs, i, j = {}, 0, 0
+    while i < n and j < m:
+        if same.get((i, j)) and table[i][j] == table[i + 1][j + 1] + 1:
+            pairs[i] = j
+            i += 1
+            j += 1
+        elif table[i + 1][j] >= table[i][j + 1]:
+            i += 1
+        else:
+            j += 1
+    return pairs
+
+
+def _heard_spans(lyric_lines, chunks):
+    """[[start, end] or None] per lyric line - the span of its words the
+    transcript heard, aligned word by word, or None when it heard none of
+    them, and [[start or None] per word of the line] (#805) - the time each
+    lyric word was heard at. A line's span runs no further than the next
+    heard line's start. The word-level alignment stays here, apart from
+    placing the unheard lines."""
+    heard = _timed_words(chunks)
+    lyric_words, owner = [], []
+    for index, (text, _) in enumerate(lyric_lines):
+        for word in _words(text):
+            lyric_words.append(word)
+            owner.append(index)
+    pairs = _align_words(lyric_words, [word for word, _, _ in heard])
+
+    timed = [None] * len(lyric_lines)
+    word_times = [[None] * len(_words(text)) for text, _ in lyric_lines]
+    first_word = {}
+    for lyric_index, line in enumerate(owner):
+        first_word.setdefault(line, lyric_index)
+    for lyric_index, heard_index in pairs.items():
+        line = owner[lyric_index]
+        _, start, end = heard[heard_index]
+        word_times[line][lyric_index - first_word[line]] = start
+        if timed[line] is None:
+            timed[line] = [start, end]
+        else:
+            timed[line][0] = min(timed[line][0], start)
+            timed[line][1] = max(timed[line][1], end)
+
+    known = [index for index, span in enumerate(timed) if span is not None]
+    for a, b in zip(known, known[1:]):
+        timed[a][1] = min(timed[a][1], timed[b][0])
+    return timed, word_times
+
+
+def _line_tokens(text, times, span):
+    """[(token, time)] - the line's whitespace-separated tokens, each with
+    the time its first word was heard at (#805). A line none of whose words
+    were heard is spread evenly over its span; a token that is no word, or
+    whose words were not heard, has time None."""
+    pieces = text.split()
+    counts = [len(_words(piece)) for piece in pieces]
+    if not any(time is not None for time in times):
+        total = sum(1 for count in counts if count)
+        tokens, seen = [], 0
+        for piece, count in zip(pieces, counts):
+            if count and span is not None:
+                at = span[0] + (span[1] - span[0]) * seen / total
+                seen += 1
+            else:
+                at = None
+            tokens.append((piece, at))
+        return tokens
+    tokens, used = [], 0
+    for piece, count in zip(pieces, counts):
+        heard = [t for t in times[used : used + count] if t is not None]
+        used += count
+        tokens.append((piece, heard[0] if heard else None))
+    return tokens
+
+
+def align_lyrics(lyric_lines, chunks, duration, warnings, min_line_s):
+    """[{start, end, text, stanza}] - the lyrics' lines in their order, timed
+    from the transcript. A line none of whose words were heard is placed
+    between its neighbours, and warned about; when they touch it takes
+    min_line_s from them, so it is still a shot of its own."""
+    timed, word_times = _heard_spans(lyric_lines, chunks)
+    heard_times = [list(times) for times in word_times]
+    known = [index for index, span in enumerate(timed) if span is not None]
+    if not known:
+        warnings.append(
+            f"{COMMAND}: none of the lyrics' words were heard in the transcript "
+            "- the lines are spread evenly over the sung part of the song; "
+            "check the transcript is of this song"
+        )
+    vocal_start = chunks[0]["start"] if chunks else 0.0
+    vocal_end = chunks[-1]["end"] if chunks else duration
+    index = 0
+    while index < len(timed):
+        if timed[index] is not None:
+            index += 1
+            continue
+        run_end = index
+        while run_end < len(timed) and timed[run_end] is None:
+            run_end += 1
+        following = timed[run_end][0] if run_end < len(timed) else None
+        if index > 0:
+            low = timed[index - 1][1]
+        else:
+            low = vocal_start if following is None else min(vocal_start, following)
+        high = following if following is not None else max(vocal_end, low)
+        count = run_end - index
+        # The neighbours took the unheard line's time with its misheard words:
+        # give it back from each side, never more than half a neighbour
+        short = count * min_line_s - (high - low)
+        if short > 1e-9:
+            before = timed[index - 1] if index > 0 else None
+            after = timed[run_end] if run_end < len(timed) else None
+            spare_before = (before[1] - before[0]) / 2 if before else 0.0
+            spare_after = (after[1] - after[0]) / 2 if after else 0.0
+            take_before = min(spare_before, max(short / 2, short - spare_after))
+            take_after = min(spare_after, short - take_before)
+            low -= take_before
+            high += take_after
+            if before:
+                before[1] = low
+            if after:
+                after[0] = high
+        step = (high - low) / count
+        for offset in range(count):
+            timed[index + offset] = [low + offset * step, low + (offset + 1) * step]
+            if known:
+                warnings.append(
+                    f"{COMMAND}: lyric line {index + offset + 1} "
+                    f"({lyric_lines[index + offset][0]!r}) was not heard in the "
+                    f"transcript - placed between its neighbours, at "
+                    f"{timed[index + offset][0]:.2f}-{timed[index + offset][1]:.2f} s"
+                )
+        index = run_end
+    return [
+        {
+            "start": span[0],
+            "end": span[1],
+            "text": text,
+            "stanza": stanza,
+            "tokens": _line_tokens(text, times, span) if known else None,
+        }
+        for span, times, (text, stanza) in zip(timed, heard_times, lyric_lines)
+    ]
+
+
+def lines_of_transcript(chunks, stanza_gap):
+    """[{start, end, text, stanza}] - a line per chunk; a silence of at least
+    stanza_gap starts a new stanza."""
+    lines, stanza = [], 0
+    for index, chunk in enumerate(chunks):
+        if not chunk["text"]:
+            continue
+        if lines and chunk["start"] - lines[-1]["end"] >= stanza_gap:
+            stanza += 1
+        lines.append(dict(chunk, stanza=stanza))
+    return lines
+
+
+def is_phrases(transcript):
+    """Whether this is analyze_phrases' result (#1095): timing with no text,
+    told from a transcript by its 'phrases' key."""
+    return (
+        isinstance(transcript, dict)
+        and "phrases" in transcript
+        and "chunks" not in transcript
+    )
+
+
+def phrase_list(transcript):
+    """[{start, end, text}] in seconds, ascending - an analyze_phrases
+    result's phrases, each with no text. A phrase is never suspect."""
+    problem = transcript_problem(transcript)
+    if problem:
+        raise ValueError(problem)
+    parsed = []
+    for index, phrase in enumerate(transcript["phrases"]):
+        if not isinstance(phrase, dict):
+            raise ValueError(
+                f"{COMMAND}: phrase {index} is not a {{start, end}} object"
+            )
+        start = as_number(phrase.get("start"), f"phrases[{index}].start", required=True)
+        end = as_number(phrase.get("end"), f"phrases[{index}].end", required=True)
+        parsed.append({"start": start, "end": max(end, start), "text": ""})
+    parsed.sort(key=lambda phrase: phrase["start"])
+    return parsed
+
+
+def lines_of_phrases(phrases, lyrics, duration, stanza_gap, warnings):
+    """[{start, end, text, stanza, tokens}] from analyze_phrases' phrases.
+    Without lyrics a line per phrase, with no text, and a silence of at least
+    stanza_gap starts a stanza. With lyrics whose lines are as many as the
+    phrases, line n is phrase n; otherwise the counts are warned about, with
+    the analyze_phrases knob to turn, and the lines spread evenly from the
+    first phrase to the last - never paired. A phrase has no word times, so
+    a split piece of one keeps its whole lyric."""
+    if lyrics is None:
+        lines, stanza = [], 0
+        for phrase in phrases:
+            if lines and phrase["start"] - lines[-1]["end"] >= stanza_gap:
+                stanza += 1
+            lines.append(dict(phrase, stanza=stanza, tokens=None))
+        return lines
+    if len(lyrics) == len(phrases):
+        paired = [
+            dict(phrase, text=text, stanza=stanza, tokens=None)
+            for phrase, (text, stanza) in zip(phrases, lyrics)
+        ]
+        _disproportion_warning(paired, warnings)
+        return paired
+    if len(phrases) > len(lyrics):
+        knob = "raise analyze_phrases' 'min_gap_seconds' to bridge more pauses, so the counts match"
+    else:
+        knob = (
+            "lower analyze_phrases' 'min_gap_seconds' to split at shorter "
+            "pauses, or, for legato or reverberant singing whose lines fuse, "
+            "raise its 'floor_db' (less negative, e.g. -30), so the counts match - then "
+            "check the phrases by ear before trusting a one-to-one pairing, since a "
+            "raised floor can match the counts on wrong boundaries"
+        )
+    low = phrases[0]["start"] if phrases else 0.0
+    high = phrases[-1]["end"] if phrases else duration
+    warnings.append(
+        f"{COMMAND}: the lyrics have {len(lyrics)} line(s) and analyze_phrases "
+        f"found {len(phrases)} phrase(s) - the lines are spread evenly over "
+        f"{low:.2f}-{high:.2f} s, not paired with the phrases; {knob}"
+    )
+    step = (high - low) / len(lyrics)
+    return [
+        {
+            "start": low + index * step,
+            "end": low + (index + 1) * step,
+            "text": text,
+            "stanza": stanza,
+            "tokens": None,
+        }
+        for index, (text, stanza) in enumerate(lyrics)
+    ]
+
+
+# A paired phrase this far from the median phrase length is likely a bad
+# boundary (#1095): on a fused legato verse, a raised floor_db can split a
+# breath off as a "phrase" and leave another line spanning two.
+DISPROPORTION = 4.0
+
+
+def _disproportion_warning(paired, warnings):
+    """Warn when a lyric line is paired one to one with a phrase under a
+    quarter, or over four times, the median phrase duration. The pairing
+    stands; the warning is advice to check the boundaries by ear."""
+    lengths = [line["end"] - line["start"] for line in paired]
+    if len(lengths) < 2:
+        return
+    median = statistics.median(lengths)
+    if median <= 0:
+        return
+    odd = [
+        f"line {index + 1} ({line['text']!r}, {line['end'] - line['start']:.2f} s)"
+        for index, line in enumerate(paired)
+        if not median / DISPROPORTION
+        <= line["end"] - line["start"]
+        <= median * DISPROPORTION
+    ]
+    if odd:
+        warnings.append(
+            f"{COMMAND}: the lyric lines are paired one to one with "
+            f"analyze_phrases' phrases, but {', '.join(odd)} "
+            f"{'sits' if len(odd) == 1 else 'sit'} on a phrase "
+            f"under 1/{DISPROPORTION:g} or over {DISPROPORTION:g}x the median "
+            f"phrase ({median:.2f} s) - the phrase boundaries may be wrong; "
+            "check them by ear"
+        )
diff --git a/dw/tasks/face_track.py b/dw/tasks/face_track.py
index 11fc78ed..3fba7809 100644
--- a/dw/tasks/face_track.py
+++ b/dw/tasks/face_track.py
@@ -486,6 +486,40 @@ def detect(rgb):
     return detect
 
 
+def _tracked_crops(detector, rgb, shots, settings):
+    """(track, resets, crops): every frame's detections tracked into one face
+    (reset at each recorded shot start, else at each content cut), and the
+    square cut around it. `settings` is (min_confidence, gate_full, gate_zero,
+    padding, crop_size)."""
+    min_confidence, gate_full, gate_zero, padding, crop_size = settings
+    height, width = rgb[0].shape[:2]
+    starts = shot_starts(shots)
+    if starts:
+        resets_at = {frame: ("shot", name) for frame, name in starts.items()}
+    else:
+        resets_at = {frame: ("cut", detail) for frame, detail in content_cuts(rgb)}
+
+    detections = [
+        [d for d in detect_tiled(detector, frame) if d[4] >= min_confidence]
+        for frame in rgb
+    ]
+    track, resets = track_faces(detections, width, resets_at, gate_full, gate_zero)
+
+    # A frame without a box borrows the nearest one, at strength 0, so the
+    # crop does not jump to the frame centre and back across a short miss
+    boxes = [entry["box"] for entry in track]
+    known = [i for i, b in enumerate(boxes) if b is not None]
+    crops = []
+    for index, entry in enumerate(track):
+        box = entry["box"]
+        if box is None and known:
+            box = boxes[min(known, key=lambda k: abs(k - index))]
+        square = crop_square(box, padding, width, height)
+        entry["crop"] = square
+        crops.append(_cut(rgb[index], square, crop_size))
+    return track, resets, crops
+
+
 def crop_face_track(
     clip,
     crop_size=512,
@@ -588,40 +622,19 @@ def crop_face_track(
     detector = _detector(detector_repo, detector_file, min_confidence, device)
     rgb = [np.asarray(frame.convert("RGB")) for frame in frames]
     height, width = rgb[0].shape[:2]
-
-    shots = getattr(clip, "shots", None)
-    starts = shot_starts(shots)
-    if starts:
-        resets_at = {frame: ("shot", name) for frame, name in starts.items()}
-    else:
-        resets_at = {frame: ("cut", detail) for frame, detail in content_cuts(rgb)}
-
-    detections = [
-        [d for d in detect_tiled(detector, frame) if d[4] >= min_confidence]
-        for frame in rgb
-    ]
-    track, resets = track_faces(detections, width, resets_at, gate_full, gate_zero)
+    track, resets, crops = _tracked_crops(
+        detector,
+        rgb,
+        getattr(clip, "shots", None),
+        (min_confidence, gate_full, gate_zero, padding, crop_size),
+    )
     face_found = any(entry["box"] is not None for entry in track)
-
-    # A frame without a box borrows the nearest one, at strength 0, so the
-    # crop does not jump to the frame centre and back across a short miss
-    boxes = [entry["box"] for entry in track]
-    known = [i for i, b in enumerate(boxes) if b is not None]
-    crops = []
-    for index, entry in enumerate(track):
-        box = entry["box"]
-        if box is None and known:
-            box = boxes[min(known, key=lambda k: abs(k - index))]
-        square = crop_square(box, padding, width, height)
-        entry["crop"] = square
-        crops.append(_cut(rgb[index], square, crop_size))
-
     crops = pad_frames(crops, before, after)
     track_audio, sample_rate = crop_soundtrack(
         clip, clip_fps, len(frames), before, after
     )
 
-    record = JsonRecord(
+    record = _track_record(
         {
             "source": {
                 "width": width,
@@ -641,31 +654,42 @@ def crop_face_track(
             "face_found": face_found,
             "frames": track,
             "resets": resets,
-        }
+        },
+        f"{modulus}n+{remainder}",
+        track_audio is not None,
     )
-    if not face_found:
+    return {
+        "crops": AudioVideo(crops, track_audio, sample_rate, fps=clip_fps),
+        "track": record,
+    }
+
+
+def _track_record(fields, grid, with_soundtrack):
+    """The `track` record from its fields, with the no-face warning and the
+    run's log line said once."""
+    record = JsonRecord(fields)
+    track, frames = fields["frames"], fields["source"]["frames"]
+    if not fields["face_found"]:
         record["message"] = (
-            f"No face was found in {len(frames)} frames (min_confidence "
-            f"{min_confidence}); every strength is 0 and each crop is the "
-            f"centre square of the frame"
+            f"No face was found in {frames} frames (min_confidence "
+            f"{fields['min_confidence']}); every strength is 0 and each crop is "
+            f"the centre square of the frame"
         )
         emit_warning(
             f"crop_face_track: {record['message']}",
             kind="no_face_found",
             command="crop_face_track",
-            frames=len(frames),
+            frames=frames,
         )
     tracked = sum(entry["state"] == "tracked" for entry in track)
     emit_log(
-        f"crop_face_track: face in {tracked} of {len(frames)} frames, "
-        f"{len(resets)} reset(s), {len(crops)} crops of {crop_size}px "
-        f"({before} before, {after} after for {modulus}n+{remainder})"
-        + (", with the clip's soundtrack" if track_audio is not None else "")
+        f"crop_face_track: face in {tracked} of {frames} frames, "
+        f"{len(fields['resets'])} reset(s), {fields['crop_frames']} crops of "
+        f"{fields['crop_size']}px ({fields['pad_before']} before, "
+        f"{fields['pad_after']} after for {grid})"
+        + (", with the clip's soundtrack" if with_soundtrack else "")
     )
-    return {
-        "crops": AudioVideo(crops, track_audio, sample_rate, fps=clip_fps),
-        "track": record,
-    }
+    return record
 
 
 def crop_soundtrack(clip, clip_fps, frames, before, after):
diff --git a/dw/tasks/mmaudio_decoder.py b/dw/tasks/mmaudio_decoder.py
index 8e7d31c8..a92779f1 100644
--- a/dw/tasks/mmaudio_decoder.py
+++ b/dw/tasks/mmaudio_decoder.py
@@ -98,8 +98,9 @@ def to(self, device=None, dtype=None):
         return self
 
     def decode(self, latents):
-        """`latents` (B, latent_channels, frames), already divided by the
-        VAE's scaling_factor, to a waveform (B, 1, frames * samples_per_latent)."""
+        """`latents` (B, latent_channels, frames) as the flow network sampled
+        them - no scaling_factor division; MMAudio's VAE takes them raw - to a
+        waveform (B, 1, frames * samples_per_latent)."""
         return decode_latents(self.vae, self.vocoder, latents)
 
 
diff --git a/dw/tasks/script_check.py b/dw/tasks/script_check.py
index 02ad0e31..910ba616 100644
--- a/dw/tasks/script_check.py
+++ b/dw/tasks/script_check.py
@@ -46,17 +46,15 @@
 import math
 from types import SimpleNamespace
 
-from .. import dsp
 from ..assessment_rules import finding
 from ..task_domains import check_arguments
 from ..events import emit_log
 from ..locations import is_http_url
-from ..script_lines import (
+from ..script_lines import (  # noqa: F401 - REPEAT_* re-exported for the thresholds' tests
     COMMAND,
     REPEAT_MAX_PERIOD,
     REPEAT_RUN_MIN,
     disambiguated,
-    looped_texts_firsts,
     normalize_words,
     parse_lines,
     parse_shots,
@@ -66,149 +64,51 @@
 from .assess import resolve_shots
 from .audio_transcription import WHISPER_DEFAULT_MODEL
 from .audio_utils import waveform_and_rate
-from .script_take import (
-    GUARD_FLOOR_DBFS,
-    GUARD_WINDOW_SECONDS,
-    audible_runs,
+from .script_take import (  # noqa: F401 - guard_words, overlapping_shot, shot_spans, word_level re-exported
     clamp_to_shot,
-    heard_shot,
-    round_seconds,
     guard_words,
     level_for_transcription,
     overlapping_shot,
     per_shot_chunks,
+    round_seconds,
     shot_spans,
     shots_entry,
     word_level,
 )
+from .script_findings import (  # noqa: F401 - some re-exported
+    between_lines_findings,
+    CLIP_TAIL_SECONDS,
+    CLIPPED_AT_END,
+    clipped_findings,
+    clipped_tail,
+    contains_words,
+    DEFAULT_SIMILARITY,
+    entry_at,
+    heard_entry,
+    joined_words,
+    LINE_RULES,
+    line_similarity,
+    loop_findings,
+    mismatch_rule,
+    SHOT_RULES,
+    SILENT_RULES,
+    silent_shot_findings,
+    silent_take_findings,
+    SPEECH_NOT_TRANSCRIBED,
+    TAG_SPOKEN,
+    tail_level,
+    THRESHOLDS,
+    unassigned_tags_findings,
+    uncovered_speech_findings,
+    unscripted_findings,
+    untranscribed_findings,
+)
 
 logger = logging.getLogger("dw")
 
-# Default least similarity between a line's expected and heard words before
-# it is a `line_mismatch`. The template's own default is set from stage A's
-# two-model measurement (#609 Q3); this one is the task's
-DEFAULT_SIMILARITY = 0.85
-# GUARD_FLOOR_DBFS and GUARD_WINDOW_SECONDS, the guard over heard words,
-# live in dw/tasks/script_take.py beside `guard_words`
-# A line is clipped at the end when its last heard word ends inside the
-# file's final CLIP_TAIL_SECONDS and that tail measures above
-# GUARD_FLOOR_DBFS - still voiced when the file stops, not a word that
-# finished into a quiet tail
-CLIP_TAIL_SECONDS = 0.25
-# ... and within CLIP_TAIL_BELOW_WORD_DB of the last word's own loudest window:
-# a word cut mid-sound leaves a tail near its level, a score bed or room tone
-# under a word that finished sits far below it (#953)
-CLIP_TAIL_BELOW_WORD_DB = 15.0
-# Audible speech the transcript has no words for (#923): Whisper can drop a
-# passage from its text on a longer input (the ad-lib heard in a short file
-# is gone), and the word alignment hands that time to a neighbouring word,
-# which stretches. A gap between a line's words,
-# or a word, lasting UNHEARD_MIN_SECONDS or more, whose interior - trimmed by
-# UNHEARD_MARGIN_SECONDS each side - holds a window above UNHEARD_FLOOR_DBFS,
-# is speech the words do not account for. The floor is far above the
-# dead-air floor so room tone and a pause's tail do not trip it
-UNHEARD_MIN_SECONDS = 1.0
-UNHEARD_MARGIN_SECONDS = 0.25
-UNHEARD_FLOOR_DBFS = -40.0
-# A block whose samples repeat themselves - one stretch of it matching the
-# same stretch BED_MIN_PERIOD_SECONDS or more later at BED_CORRELATION or
-# better, over at least BED_MIN_OVERLAP_SECONDS - is a looped bed (loop_audio
-# of a room tone), not speech: the same sound does not recur to the sample
-# in a voice (#1118)
-BED_MIN_PERIOD_SECONDS = 0.3
-BED_MIN_OVERLAP_SECONDS = 0.5
-BED_CORRELATION = 0.98
 # REPEAT_RUN_MIN and REPEAT_MAX_PERIOD, the repetition-loop guard, live in
 # dw/script_lines.py beside the detector, which transcribe_audio shares
 
-THRESHOLDS = {
-    "similarity": DEFAULT_SIMILARITY,
-    "guard_floor_dbfs": GUARD_FLOOR_DBFS,
-    "guard_window_seconds": GUARD_WINDOW_SECONDS,
-    "clip_tail_seconds": CLIP_TAIL_SECONDS,
-    "clip_tail_below_word_db": CLIP_TAIL_BELOW_WORD_DB,
-    "unheard_min_seconds": UNHEARD_MIN_SECONDS,
-    "unheard_margin_seconds": UNHEARD_MARGIN_SECONDS,
-    "unheard_floor_dbfs": UNHEARD_FLOOR_DBFS,
-    "bed_correlation": BED_CORRELATION,
-    "repeat_run_min": REPEAT_RUN_MIN,
-    "repeat_max_period": REPEAT_MAX_PERIOD,
-}
-
-LINE_RULES = (
-    "line_mismatch",
-    "transcript_loop",
-    "tag_spoken",
-    "line_clipped_at_end",
-    "speech_not_transcribed",
-)
-SILENT_RULES = ("speech_where_silent",)
-SHOT_RULES = ("speech_in_silent_shot", "unscripted_speech")
-
-
-def _rule(name, threshold, says):
-    return {"name": name, "severity": "warn", "threshold": threshold, "says": says}
-
-
-def mismatch_rule(similarity):
-    return _rule(
-        "line_mismatch",
-        similarity,
-        "the take's words for this line are this similar to the script - listen"
-        " before re-rolling: Whisper mishears names and numbers ('2' for 'two')"
-        " on a correct take",
-    )
-
-
-TAG_SPOKEN = _rule(
-    "tag_spoken",
-    None,
-    "a markup word from this line was heard spoken aloud - the model read the"
-    " tag as dialogue",
-)
-SPEECH_NOT_TRANSCRIBED = _rule(
-    "speech_not_transcribed",
-    UNHEARD_FLOOR_DBFS,
-    "audible sound lasting this many seconds sits between the line's words, between"
-    " two lines, or inside one stretched word, with no word for it - the transcript left speech"
-    " out and the line's timing absorbed it; listen",
-)
-TRANSCRIPT_LOOP = _rule(
-    "transcript_loop",
-    REPEAT_RUN_MIN,
-    "the transcript repeated words of the script in a loop for this many chunks"
-    " (seen at 'seconds' to 'end') - Whisper stuck, so speech after it may be"
-    " missing from 'heard' and lines can read 0.0 without being wrong; listen,"
-    " or check each shot on its own, before re-rolling",
-)
-SPEECH_WHERE_SILENT = _rule(
-    "speech_where_silent",
-    0,
-    "no line was expected, and this many words were heard above the dead-air floor"
-    " and outside a repetition loop",
-)
-CLIPPED_AT_END = _rule(
-    "line_clipped_at_end",
-    GUARD_FLOOR_DBFS,
-    "the line's last word ends inside the final"
-    f" {CLIP_TAIL_SECONDS} s of its shot (or of the file) and that tail is"
-    f" still voiced at this level, within {CLIP_TAIL_BELOW_WORD_DB} dB of the"
-    " word's own level (a quieter tail is a bed or room tone) - the shot"
-    " stops mid-word",
-)
-SPEECH_IN_SILENT_SHOT = _rule(
-    "speech_in_silent_shot",
-    0,
-    "no line names this shot, and this many words were heard in it above the"
-    " dead-air floor and outside a repetition loop",
-)
-UNSCRIPTED_SPEECH = _rule(
-    "unscripted_speech",
-    0,
-    "this many words were heard inside a shot that has a scripted line, matched to"
-    " no line - a line spoken twice (see 'repeats_line'), or an ad-lib; listen",
-)
-
 
 def align(expected_lines, heard):
     """Assign each heard word to the expected line it was spoken for.
@@ -273,7 +173,7 @@ def _release_repeats(expected, heard, assigned, unassigned):
             if (
                 op == "insert"
                 and len(run) >= min(2, len(words))
-                and (_contains(words, run) or _contains(run, words))
+                and (contains_words(words, run) or contains_words(run, words))
             ):
                 moved.update(range(j1, j2))
         if not moved:
@@ -283,53 +183,6 @@ def _release_repeats(expected, heard, assigned, unassigned):
     unassigned.sort()
 
 
-def line_similarity(expected, heard):
-    """How alike two word lists are, 0..1. Two empty lists are identical."""
-    if not expected and not heard:
-        return 1.0
-    return difflib.SequenceMatcher(None, expected, heard, autojunk=False).ratio()
-
-
-def tail_level(mono, sample_rate, end=None):
-    """The rms of the CLIP_TAIL_SECONDS before `end` seconds - the file's
-    final ones when None - in dBFS (None: silent)."""
-    count = max(1, int(round(CLIP_TAIL_SECONDS * sample_rate)))
-    last = len(mono) if end is None else min(len(mono), int(round(end * sample_rate)))
-    return dsp.dbfs(dsp.rms(mono[max(0, last - count) : last]))
-
-
-def _at(line, heard_word=None, seconds=None, shot=None):
-    at = {"line": line}
-    if heard_word is not None:
-        at["seconds"] = round_seconds(heard_word["start"])
-        at["word"] = heard_word["text"]
-    else:
-        at["seconds"] = round_seconds(seconds)
-    if shot is not None:
-        at["shot"] = shot
-    return at
-
-
-def _clipped_tail(mono, sample_rate, end, tails, word=None):
-    """The first of `tails` - (shot name or None, the second it ends at) -
-    that a line ending at `end` is clipped by: the word ends inside its
-    final CLIP_TAIL_SECONDS (within that much past it too, a word timestamp
-    being approximate) and the tail is voiced above GUARD_FLOOR_DBFS and
-    within CLIP_TAIL_BELOW_WORD_DB of the (start, end) span's loudest window,
-    when given: a tail far under the word is a bed, not the word. Returns (shot, level) or None."""
-    word_db = word_level(mono, sample_rate, *word) if word else None
-    floor = GUARD_FLOOR_DBFS
-    if word_db is not None:
-        floor = max(floor, word_db - CLIP_TAIL_BELOW_WORD_DB)
-    for shot, tail_end in tails:
-        if not tail_end - CLIP_TAIL_SECONDS <= end <= tail_end + CLIP_TAIL_SECONDS:
-            continue
-        level = tail_level(mono, sample_rate, tail_end)
-        if level is not None and level > floor:
-            return shot, level
-    return None
-
-
 def _no_shot_reason(shots_source, spans, parsed_lines):
     """Why speech_in_silent_shot cannot run on this call, or None when it
     can."""
@@ -378,20 +231,20 @@ def check(
     (resolve_shots: argument, artifact, manifest or none).
 
     The phases, each a helper below: the guard (`guard_words`) and the
-    silent-take answer (`_silent_take`); the loop findings
-    (`_loop_findings`); the alignment (`align`, `_release_repeats`); the
+    silent-take answer (`silent_take_findings`); the loop findings
+    (`loop_findings`); the alignment (`align`, `_release_repeats`); the
     line pass (`_line_pass`: one `lines` entry and the line rules per line);
-    the tags left between lines (`_unassigned_tags`); the shot rules
+    the tags left between lines (`unassigned_tags_findings`); the shot rules
     (`_shot_rules`)."""
     script_words = {
         word for line in parsed_lines for word in normalize_words(line["text"])
     }
     heard, discarded = guard_words(chunks, mono, sample_rate, script_words)
     if not parsed_lines:
-        return _silent_take(heard, discarded, spans, shots_source)
+        return silent_take_findings(heard, discarded, spans, shots_source)
 
     duration = len(mono) / sample_rate if sample_rate else 0.0
-    findings = _loop_findings(chunks, script_words)
+    findings = loop_findings(chunks, script_words)
     loop_starts = [found["at"]["seconds"] for found in findings]
     expected = [normalize_words(line["text"]) for line in parsed_lines]
     assigned, unassigned = align(expected, heard)
@@ -410,7 +263,9 @@ def check(
         similarity_threshold,
     )
     findings.extend(found)
-    findings.extend(_unassigned_tags(heard, unassigned, parsed_lines, expected, spans))
+    findings.extend(
+        unassigned_tags_findings(heard, unassigned, parsed_lines, expected, spans)
+    )
     rules_applied, rules_skipped, found = _shot_rules(
         spans,
         shots_source,
@@ -423,7 +278,7 @@ def check(
         duration,
     )
     findings.extend(found)
-    rules_skipped.extend(_uncovered_speech(spans, heard, duration))
+    rules_skipped.extend(uncovered_speech_findings(spans, heard, duration))
     found, unchecked = _unheard_line_clips(mono, sample_rate, lines, findings, spans)
     findings.extend(found)
     rules_skipped.extend(unchecked)
@@ -432,7 +287,7 @@ def check(
         "findings": findings,
         "lines": lines,
         "discarded": discarded,
-        "unmatched": [_heard_entry(heard[j]) for j, _ in unassigned],
+        "unmatched": [heard_entry(heard[j]) for j, _ in unassigned],
         "shots": shots_entry(spans),
         "shots_source": shots_source,
         "rules_applied": rules_applied,
@@ -455,8 +310,8 @@ def _line_pass(
 ):
     """The line pass: each line's `lines` entry (`_line_entry`) and, for a
     line something was heard for, the gap before it
-    (`_between_lines_findings`), its clipped tail (`_clipped_findings`) and
-    the sound its words leave out (`_untranscribed_findings`); then the
+    (`between_lines_findings`), its clipped tail (`clipped_findings`) and
+    the sound its words leave out (`untranscribed_findings`); then the
     stretch after the last line heard, to the end of the take.
 
     Returns (lines, claimed, findings): `claimed` maps each assigned heard
@@ -505,7 +360,7 @@ def _line_pass(
         start, end = own[0]["start"], own[-1]["end"]
         if heard_end is not None:
             findings.extend(
-                _between_lines_findings(
+                between_lines_findings(
                     mono,
                     sample_rate,
                     index,
@@ -521,9 +376,9 @@ def _line_pass(
             last_line, last_shot = index, shot
         heard_end = max(heard_end or 0.0, end)
         tails = ([(shot, span["end"])] if span else []) + [(None, duration)]
-        findings.extend(_clipped_findings(mono, sample_rate, tails, index, own, shot))
+        findings.extend(clipped_findings(mono, sample_rate, tails, index, own, shot))
         findings.extend(
-            _untranscribed_findings(
+            untranscribed_findings(
                 mono, sample_rate, index, own, shot, spans, parsed_lines
             )
         )
@@ -534,7 +389,7 @@ def _line_pass(
         # same rule as between two lines, so a shot checked alone agrees with
         # the cut (#970)
         findings.extend(
-            _between_lines_findings(
+            between_lines_findings(
                 mono,
                 sample_rate,
                 last_line,
@@ -554,15 +409,24 @@ def _unheard_line_clips(mono, sample_rate, lines, findings, spans):
     last word, so the speech_not_transcribed blocks credited to it stand in -
     one running to its shot's voiced end is a shot stopping mid-speech. An
     unheard line no block of reaches its shot's end is listed in
-    `rules_skipped` with its index, never reported clean. Returns (findings,
-    skipped)."""
+    `rules_skipped` with its index, never reported clean - so is a line in no
+    known shot, whose reason names no shot. Returns (findings, skipped)."""
     by_name = {span["name"]: span for span in spans or ()}
     found, skipped = [], []
     for index, entry in enumerate(lines):
         span = by_name.get(entry["shot"])
         if entry["start"] is not None:
             continue
-        key = (index, span and span["name"])
+        if span is None:
+            # No shot to end at: the line's own end is unknown too, and the
+            # take's end cannot be checked without it
+            reason = "nothing heard for the line and no shot of its own, so where"
+            reason += " the line ends is unknown - check the take's end by ear"
+            skipped.append(
+                {"rule": CLIPPED_AT_END["name"], "line": index, "reason": reason}
+            )
+            continue
+        key = (index, span["name"])
         ends = [
             f["at"]
             for f in findings
@@ -573,7 +437,7 @@ def _unheard_line_clips(mono, sample_rate, lines, findings, spans):
         ]
         for at in ends:
             tail = [(span["name"], span["end"])]
-            clipped = _clipped_tail(
+            clipped = clipped_tail(
                 mono, sample_rate, at["end"], tail, (at["seconds"], at["end"])
             )
             if clipped is not None:
@@ -605,7 +469,7 @@ def _line_entry(
     )
     entry = {
         "expected": line["text"],
-        "heard": None if looped else _joined(own),
+        "heard": None if looped else joined_words(own),
         "similarity": None if looped else round(score, 4),
         "start": round_seconds(own[0]["start"]) if own else None,
         "end": round_seconds(own[-1]["end"]) if own else None,
@@ -616,14 +480,14 @@ def _line_entry(
         entry["not_transcribed"] = "transcript_loop"
     elif score < similarity_threshold:
         if own:
-            at = _at(index, own[0], shot=shot)
+            at = entry_at(index, own[0], shot=shot)
         else:
-            at = _at(index, seconds=position, shot=shot)
+            at = entry_at(index, seconds=position, shot=shot)
         findings.append(finding(mismatch, round(score, 4), at))
     for word in own:
         if word["word"] in tokens:
             findings.append(
-                finding(TAG_SPOKEN, word["word"], _at(index, word, shot=shot))
+                finding(TAG_SPOKEN, word["word"], entry_at(index, word, shot=shot))
             )
     return entry, findings
 
@@ -652,9 +516,9 @@ def _shot_rules(
     no_shot = _no_shot_reason(shots_source, spans, parsed_lines)
     if no_shot is None:
         rules_applied.extend(SHOT_RULES)
-        findings.extend(_silent_shot_findings(spans, parsed_lines, heard, claimed))
+        findings.extend(silent_shot_findings(spans, parsed_lines, heard, claimed))
         findings.extend(
-            _unscripted_findings(
+            unscripted_findings(
                 spans, parsed_lines, expected, heard, unassigned, similarity_threshold
             )
         )
@@ -672,7 +536,7 @@ def _shot_rules(
             rules_skipped.pop()  # unscripted_speech: run on the implicit shot
             rules_applied.append("unscripted_speech")
             findings.extend(
-                _unscripted_findings(
+                unscripted_findings(
                     implicit,
                     parsed_lines,
                     expected,
@@ -684,354 +548,6 @@ def _shot_rules(
     return rules_applied, rules_skipped, findings
 
 
-def _uncovered_speech(spans, heard, duration):
-    """A `shot_coverage` skip entry (#1129) naming each stretch of the take
-    outside every supplied shot where words were heard: no shot rule looks
-    there, so a clean result must not read as checked."""
-    if not spans:
-        return []
-    gaps, cursor = [], 0.0
-    for span in sorted(spans, key=lambda s: s["start"]):
-        if span["start"] > cursor:
-            gaps.append((cursor, span["start"]))
-        cursor = max(cursor, span["end"])
-    if duration > cursor:
-        gaps.append((cursor, duration))
-    named = []
-    for start, end in gaps:
-        if any(start <= (w["start"] + w["end"]) / 2 < end for w in heard):
-            named.append(f"{round_seconds(start)}-{round_seconds(end)} s")
-    if not named:
-        return []
-    return [
-        {
-            "rule": "shot_coverage",
-            "reason": "speech was heard outside the supplied shot map and "
-            "not checked against any shot: " + ", ".join(named),
-        }
-    ]
-
-
-def _loop_findings(chunks, script_words):
-    """A `transcript_loop` finding for each repetition loop over the script's
-    own words: Whisper stuck on a line it heard, so what follows the loop was
-    never transcribed and its lines read as mismatches (#961)."""
-    spoken = [c for c in chunks if normalize_words(c.get("text", ""))]
-    looped, firsts = looped_texts_firsts([c.get("text", "") for c in spoken])
-    found, run = [], []
-    for index in sorted(looped) + [None]:
-        if run and (index is None or index != run[-1] + 1):
-            if any(i in firsts for i in run):
-                members = [spoken[i] for i in run]
-                if all(
-                    set(normalize_words(m["text"])) <= script_words for m in members
-                ):
-                    at = _at(None, seconds=members[0]["start"])
-                    at["end"] = round_seconds(members[-1]["end"])
-                    found.append(finding(TRANSCRIPT_LOOP, len(members), at))
-            run = []
-        if index is not None:
-            run.append(index)
-    return found
-
-
-def _silent_take(heard, discarded, spans, shots_source):
-    """check's result for `lines: []`: any speech at all is the finding, and
-    the line and shot rules have nothing to compare against."""
-    findings = []
-    if heard:
-        findings.append(
-            finding(
-                SPEECH_WHERE_SILENT,
-                len(heard),
-                _at(None, heard[0], shot=heard_shot(spans, heard[0])),
-            )
-        )
-    return {
-        "findings": findings,
-        "lines": [],
-        "discarded": discarded,
-        "unmatched": [_heard_entry(word) for word in heard],
-        "shots": shots_entry(spans),
-        "shots_source": shots_source,
-        "rules_applied": list(SILENT_RULES),
-        "rules_skipped": [
-            {"rule": rule, "reason": "lines is [] - no speech was expected"}
-            for rule in LINE_RULES + SHOT_RULES
-        ],
-    }
-
-
-def _untranscribed_findings(
-    mono, sample_rate, index, own, shot, spans=None, parsed_lines=()
-):
-    """speech_not_transcribed: audible sound in a gap the line's words leave
-    - between two of them - or inside one word stretched over
-    UNHEARD_MIN_SECONDS (#923). The gap before a line's first word is
-    _between_lines_findings'."""
-    intervals = [(a["end"], b["start"]) for a, b in zip(own, own[1:])]
-    findings = []
-    for start, end in intervals:
-        if end - start >= UNHEARD_MIN_SECONDS:
-            findings.extend(
-                _audible_findings(
-                    mono, sample_rate, index, start, end, shot, spans, parsed_lines
-                )
-            )
-    for word in own:
-        # A word is sound itself: only its interior past the margins is a gap
-        if (
-            word["end"] - word["start"]
-            >= UNHEARD_MIN_SECONDS + 2 * UNHEARD_MARGIN_SECONDS
-        ):
-            findings.extend(
-                _audible_findings(
-                    mono,
-                    sample_rate,
-                    index,
-                    word["start"],
-                    word["end"],
-                    shot,
-                    spans,
-                    parsed_lines,
-                )
-            )
-    return findings
-
-
-def _between_lines_findings(
-    mono, sample_rate, index, start, end, shot, strays, spans=None, parsed_lines=()
-):
-    """speech_not_transcribed for the stretch between one line's last word and
-    the next line's first (#960): audible sound with no word, which the
-    in-line check cannot see when the timing leaves it outside both lines.
-    Heard-but-unmatched words in the gap are unscripted_speech's, but only the
-    stretches they cover: each stretch left between them is judged on its own
-    (#964). Each stretch is attributed to the shot holding most of it, and
-    to the line naming that shot (null when none does), not to the next
-    line's shot by default."""
-    if end - start < UNHEARD_MIN_SECONDS:
-        return []
-    inside = sorted(
-        (w for w in strays if w["start"] < end and w["end"] > start),
-        key=lambda w: w["start"],
-    )
-    stretches, cursor = [], start
-    for word in inside:
-        stretches.append((cursor, word["start"]))
-        cursor = max(cursor, word["end"])
-    stretches.append((cursor, end))
-    found = []
-    for lo, hi in stretches:
-        if hi - lo < UNHEARD_MIN_SECONDS:
-            continue
-        found.extend(
-            _audible_findings(
-                mono, sample_rate, index, lo, hi, shot, spans, parsed_lines
-            )
-        )
-    return [f for f in found if f is not None]
-
-
-def _audible_findings(
-    mono, sample_rate, index, start, end, shot, spans=None, parsed_lines=()
-):
-    """speech_not_transcribed for each audible block of [start, end], each
-    attributed to the shot holding most of it - and to the line naming that
-    shot, null when none does - not to the stretch's own line by default."""
-    found = []
-    pieces = []
-    for lo, hi in audible_runs(
-        mono,
-        sample_rate,
-        start,
-        end,
-        UNHEARD_FLOOR_DBFS,
-        UNHEARD_MIN_SECONDS,
-        UNHEARD_MARGIN_SECONDS,
-    ):
-        # A block crossing a shot seam is one finding per shot (#1115), so the
-        # shot that holds the untranscribed speech is named even if the other
-        # holds more of the block.
-        cuts = [lo]
-        if spans is not None:
-            cuts += sorted(
-                {s["start"] for s in spans if lo < s["start"] < hi}
-                | {s["end"] for s in spans if lo < s["end"] < hi}
-            )
-        cuts.append(hi)
-        parts = [
-            (a, b)
-            for a, b in zip(cuts, cuts[1:])
-            if b - a >= UNHEARD_MIN_SECONDS + 2 * UNHEARD_MARGIN_SECONDS
-        ]
-        # Split only when each side is substantial; else one finding, placed
-        # by majority as before (#964)
-        pieces.extend(parts if len(parts) > 1 else [(lo, hi)])
-    for lo, hi in pieces:
-        where_line, where_shot = index, shot
-        holder = None if spans is None else overlapping_shot(spans, lo, hi)
-        if holder is not None and holder != shot:
-            where_shot = holder
-            where_line = next(
-                (i for i, line in enumerate(parsed_lines) if line["shot"] == holder),
-                None,
-            )
-        found.append(_untranscribed(mono, sample_rate, where_line, lo, hi, where_shot))
-    return [f for f in found if f is not None]
-
-
-def is_looped_bed(mono, sample_rate, start, end):
-    """True when [start, end] repeats itself sample for sample (#1118): a
-    looped room-tone or score bed, which a voice never does. The measurement
-    is `dsp.repeat_correlation`; this is the decision."""
-    first, last = int(round(start * sample_rate)), int(round(end * sample_rate))
-    block = mono[max(0, first) : last]
-    return (
-        dsp.repeat_correlation(
-            block, sample_rate, BED_MIN_PERIOD_SECONDS, BED_MIN_OVERLAP_SECONDS
-        )
-        >= BED_CORRELATION
-    )
-
-
-def _untranscribed(mono, sample_rate, index, start, end, shot):
-    lo, hi = start + UNHEARD_MARGIN_SECONDS, end - UNHEARD_MARGIN_SECONDS
-    level = word_level(mono, sample_rate, lo, hi)
-    if level is None or level <= UNHEARD_FLOOR_DBFS:
-        return None
-    if is_looped_bed(mono, sample_rate, start, end):
-        return None
-    at = _at(index, seconds=start, shot=shot)
-    at["end"] = round_seconds(end)
-    return finding(SPEECH_NOT_TRANSCRIBED, round_seconds(end - start, 2), at)
-
-
-def _clipped_findings(mono, sample_rate, tails, index, own, shot):
-    """line_clipped_at_end for one heard line, as a list of zero or one
-    finding: its last word ends in a voiced tail of its shot or the file. The
-    tail is judged against the whole line's loudest window, not the last
-    word's: under a score the ASR stretches the last word over the bed, and a
-    bed measured against itself passes the guard (#959)."""
-    end = own[-1]["end"]
-    clipped = _clipped_tail(
-        mono, sample_rate, end, tails, (own[0]["start"], own[-1]["end"])
-    )
-    if clipped is None:
-        return []
-    at = {"line": index, "seconds": round_seconds(end), "word": own[-1]["text"]}
-    if clipped[0] is not None or shot is not None:
-        at["shot"] = clipped[0] or shot
-    return [finding(CLIPPED_AT_END, round_seconds(clipped[1], 2), at)]
-
-
-def _unassigned_tags(heard, unassigned, parsed_lines, expected, spans):
-    """tag_spoken for the heard words align left unassigned: a markup token
-    of a neighbouring line, spoken aloud between lines."""
-    findings = []
-    for j, neighbours in unassigned:
-        word = heard[j]
-        for index in neighbours:
-            if word["word"] in set(parsed_lines[index]["tokens"]) - set(
-                expected[index]
-            ):
-                findings.append(
-                    finding(
-                        TAG_SPOKEN,
-                        word["word"],
-                        _at(index, word, shot=heard_shot(spans, word)),
-                    )
-                )
-                break
-    return findings
-
-
-def _silent_shot_findings(spans, parsed_lines, heard, claimed):
-    """speech_in_silent_shot: words heard inside a shot no line names, other
-    than those a line in another shot claimed."""
-    findings = []
-    named = {line["shot"] for line in parsed_lines if line["shot"]}
-    for span in spans:
-        if span["name"] in named:
-            continue
-        inside = [
-            word
-            for j, word in enumerate(heard)
-            if heard_shot(spans, word) == span["name"]
-            and claimed.get(j) in (None, span["name"])
-        ]
-        if inside:
-            at = _at(None, inside[0], shot=span["name"])
-            # A word straddling the cut into this shot is placed at the cut
-            at["seconds"] = max(at["seconds"], round_seconds(span["start"]))
-            findings.append(finding(SPEECH_IN_SILENT_SHOT, len(inside), at))
-    return findings
-
-
-def _unscripted_findings(
-    spans, parsed_lines, expected, heard, unassigned, similarity_threshold
-):
-    """unscripted_speech: heard words align left to no line that sit inside a
-    shot a line names. `repeats_line` is set when the shot's words, in order,
-    contain one of its lines' words again, or score at least the mismatch
-    threshold against one of them (a repeat misheard as the line was)."""
-    findings = []
-    for span in spans:
-        lines = [
-            expected[i]
-            for i, line in enumerate(parsed_lines)
-            if line["shot"] == span["name"]
-        ]
-        if not lines:
-            continue
-        inside = [
-            heard[j]
-            for j, _ in unassigned
-            if heard_shot(spans, heard[j]) == span["name"]
-        ]
-        if not inside:
-            continue
-        at = _at(None, inside[0], shot=span["name"])
-        words = [word["word"] for word in inside]
-        at["end"] = round_seconds(inside[-1]["end"])
-        at["repeats_line"] = any(
-            line and _contains(words, line) for line in lines
-        ) or any(line and _contains(line, words) for line in lines)
-        if not at["repeats_line"]:
-            at["repeats_line"] = any(
-                line and line_similarity(line, words) >= similarity_threshold
-                for line in lines
-            )
-        findings.append(finding(UNSCRIPTED_SPEECH, len(inside), at))
-    return findings
-
-
-def _contains(words, part):
-    """Whether `part` occurs in `words` as a contiguous run."""
-    size = len(part)
-    return any(words[i : i + size] == part for i in range(len(words) - size + 1))
-
-
-def _heard_entry(word):
-    return {
-        "text": word["text"],
-        "start": round_seconds(word["start"]),
-        "end": round_seconds(word["end"]),
-    }
-
-
-def _joined(words):
-    """The heard words as the transcript spelled them, one chunk once."""
-    texts = []
-    last = None
-    for word in words:
-        key = (word["start"], word["end"], word["text"])
-        if key != last:
-            texts.append(word["text"])
-            last = key
-    return " ".join(texts)
-
-
 def check_script(
     audio,
     lines,
@@ -1134,7 +650,7 @@ def check_script(
         spans = shot_spans(records, rate, fps, len(mono) / rate if rate else 0.0)
     chunks, whole = transcript["chunks"], True
     script_words = {w for line in parsed_lines for w in normalize_words(line["text"])}
-    if spans and parsed_lines and _loop_findings(chunks, script_words):
+    if spans and parsed_lines and loop_findings(chunks, script_words):
         # Whisper looped on the whole cut and never transcribed what follows
         # (#961): the shots are known, so transcribe each on its own (#963)
         emit_log("check_script: transcript_loop on the cut; transcribing per shot")
diff --git a/dw/tasks/script_findings.py b/dw/tasks/script_findings.py
new file mode 100644
index 00000000..1ed2540a
--- /dev/null
+++ b/dw/tasks/script_findings.py
@@ -0,0 +1,580 @@
+"""check_script's findings: the rules a take is judged by and the functions
+that build each finding from the aligned lines, the heard words and the take's
+levels - a clipped tail, a loop, an unheard line, speech where the script has
+none, a tag spoken aloud, speech in a shot meant to be silent.
+
+Every threshold is a constant here, named in docs/TASKS.md; findings are built
+with `assessment_rules.finding()`. Split from dw/tasks/script_check.py, which
+imports from here (never the other way) and does the transcription, the
+alignment and the shot placement that these read.
+"""
+
+import difflib
+import logging
+
+from .. import dsp
+from ..assessment_rules import finding
+from ..script_lines import (
+    REPEAT_MAX_PERIOD,
+    REPEAT_RUN_MIN,
+    looped_texts_firsts,
+    normalize_words,
+)
+from .script_take import (
+    GUARD_FLOOR_DBFS,
+    GUARD_WINDOW_SECONDS,
+    audible_runs,
+    heard_shot,
+    overlapping_shot,
+    round_seconds,
+    shots_entry,
+    word_level,
+)
+
+logger = logging.getLogger("dw")
+
+
+def _rule(name, threshold, says):
+    return {"name": name, "severity": "warn", "threshold": threshold, "says": says}
+
+
+def mismatch_rule(similarity):
+    return _rule(
+        "line_mismatch",
+        similarity,
+        "the take's words for this line are this similar to the script - listen"
+        " before re-rolling: Whisper mishears names and numbers ('2' for 'two')"
+        " on a correct take",
+    )
+
+
+# Default least similarity between a line's expected and heard words before
+# it is a `line_mismatch`. The template's own default is set from stage A's
+# two-model measurement (#609 Q3); this one is the task's
+DEFAULT_SIMILARITY = 0.85
+
+# GUARD_FLOOR_DBFS and GUARD_WINDOW_SECONDS, the guard over heard words,
+# live in dw/tasks/script_take.py beside `guard_words`
+# A line is clipped at the end when its last heard word ends inside the
+# file's final CLIP_TAIL_SECONDS and that tail measures above
+# GUARD_FLOOR_DBFS - still voiced when the file stops, not a word that
+# finished into a quiet tail
+CLIP_TAIL_SECONDS = 0.25
+
+# ... and within CLIP_TAIL_BELOW_WORD_DB of the last word's own loudest window:
+# a word cut mid-sound leaves a tail near its level, a score bed or room tone
+# under a word that finished sits far below it (#953)
+CLIP_TAIL_BELOW_WORD_DB = 15.0
+
+# Audible speech the transcript has no words for (#923): Whisper can drop a
+# passage from its text on a longer input (the ad-lib heard in a short file
+# is gone), and the word alignment hands that time to a neighbouring word,
+# which stretches. A gap between a line's words,
+# or a word, lasting UNHEARD_MIN_SECONDS or more, whose interior - trimmed by
+# UNHEARD_MARGIN_SECONDS each side - holds a window above UNHEARD_FLOOR_DBFS,
+# is speech the words do not account for. The floor is far above the
+# dead-air floor so room tone and a pause's tail do not trip it
+UNHEARD_MIN_SECONDS = 1.0
+
+UNHEARD_MARGIN_SECONDS = 0.25
+
+UNHEARD_FLOOR_DBFS = -40.0
+
+# A block whose samples repeat themselves - one stretch of it matching the
+# same stretch BED_MIN_PERIOD_SECONDS or more later at BED_CORRELATION or
+# better, over at least BED_MIN_OVERLAP_SECONDS - is a looped bed (loop_audio
+# of a room tone), not speech: the same sound does not recur to the sample
+# in a voice (#1118)
+BED_MIN_PERIOD_SECONDS = 0.3
+
+BED_MIN_OVERLAP_SECONDS = 0.5
+
+BED_CORRELATION = 0.98
+
+THRESHOLDS = {
+    "similarity": DEFAULT_SIMILARITY,
+    "guard_floor_dbfs": GUARD_FLOOR_DBFS,
+    "guard_window_seconds": GUARD_WINDOW_SECONDS,
+    "clip_tail_seconds": CLIP_TAIL_SECONDS,
+    "clip_tail_below_word_db": CLIP_TAIL_BELOW_WORD_DB,
+    "unheard_min_seconds": UNHEARD_MIN_SECONDS,
+    "unheard_margin_seconds": UNHEARD_MARGIN_SECONDS,
+    "unheard_floor_dbfs": UNHEARD_FLOOR_DBFS,
+    "bed_correlation": BED_CORRELATION,
+    "repeat_run_min": REPEAT_RUN_MIN,
+    "repeat_max_period": REPEAT_MAX_PERIOD,
+}
+
+LINE_RULES = (
+    "line_mismatch",
+    "transcript_loop",
+    "tag_spoken",
+    "line_clipped_at_end",
+    "speech_not_transcribed",
+)
+
+SILENT_RULES = ("speech_where_silent",)
+
+SHOT_RULES = ("speech_in_silent_shot", "unscripted_speech")
+
+TAG_SPOKEN = _rule(
+    "tag_spoken",
+    None,
+    "a markup word from this line was heard spoken aloud - the model read the"
+    " tag as dialogue",
+)
+
+SPEECH_NOT_TRANSCRIBED = _rule(
+    "speech_not_transcribed",
+    UNHEARD_FLOOR_DBFS,
+    "audible sound lasting this many seconds sits between the line's words, between"
+    " two lines, or inside one stretched word, with no word for it - the transcript left speech"
+    " out and the line's timing absorbed it; listen",
+)
+
+TRANSCRIPT_LOOP = _rule(
+    "transcript_loop",
+    REPEAT_RUN_MIN,
+    "the transcript repeated words of the script in a loop for this many chunks"
+    " (seen at 'seconds' to 'end') - Whisper stuck, so speech after it may be"
+    " missing from 'heard' and lines can read 0.0 without being wrong; listen,"
+    " or check each shot on its own, before re-rolling",
+)
+
+SPEECH_WHERE_SILENT = _rule(
+    "speech_where_silent",
+    0,
+    "no line was expected, and this many words were heard above the dead-air floor"
+    " and outside a repetition loop",
+)
+
+CLIPPED_AT_END = _rule(
+    "line_clipped_at_end",
+    GUARD_FLOOR_DBFS,
+    "the line's last word ends inside the final"
+    f" {CLIP_TAIL_SECONDS} s of its shot (or of the file) and that tail is"
+    f" still voiced at this level, within {CLIP_TAIL_BELOW_WORD_DB} dB of the"
+    " word's own level (a quieter tail is a bed or room tone) - the shot"
+    " stops mid-word",
+)
+
+SPEECH_IN_SILENT_SHOT = _rule(
+    "speech_in_silent_shot",
+    0,
+    "no line names this shot, and this many words were heard in it above the"
+    " dead-air floor and outside a repetition loop",
+)
+
+UNSCRIPTED_SPEECH = _rule(
+    "unscripted_speech",
+    0,
+    "this many words were heard inside a shot that has a scripted line, matched to"
+    " no line - a line spoken twice (see 'repeats_line'), or an ad-lib; listen",
+)
+
+
+def line_similarity(expected, heard):
+    """How alike two word lists are, 0..1. Two empty lists are identical."""
+    if not expected and not heard:
+        return 1.0
+    return difflib.SequenceMatcher(None, expected, heard, autojunk=False).ratio()
+
+
+def tail_level(mono, sample_rate, end=None):
+    """The rms of the CLIP_TAIL_SECONDS before `end` seconds - the file's
+    final ones when None - in dBFS (None: silent)."""
+    count = max(1, int(round(CLIP_TAIL_SECONDS * sample_rate)))
+    last = len(mono) if end is None else min(len(mono), int(round(end * sample_rate)))
+    return dsp.dbfs(dsp.rms(mono[max(0, last - count) : last]))
+
+
+def entry_at(line, heard_word=None, seconds=None, shot=None):
+    at = {"line": line}
+    if heard_word is not None:
+        at["seconds"] = round_seconds(heard_word["start"])
+        at["word"] = heard_word["text"]
+    else:
+        at["seconds"] = round_seconds(seconds)
+    if shot is not None:
+        at["shot"] = shot
+    return at
+
+
+def clipped_tail(mono, sample_rate, end, tails, word=None):
+    """The first of `tails` - (shot name or None, the second it ends at) -
+    that a line ending at `end` is clipped by: the word ends inside its
+    final CLIP_TAIL_SECONDS (within that much past it too, a word timestamp
+    being approximate) and the tail is voiced above GUARD_FLOOR_DBFS and
+    within CLIP_TAIL_BELOW_WORD_DB of the (start, end) span's loudest window,
+    when given: a tail far under the word is a bed, not the word. Returns (shot, level) or None."""
+    word_db = word_level(mono, sample_rate, *word) if word else None
+    floor = GUARD_FLOOR_DBFS
+    if word_db is not None:
+        floor = max(floor, word_db - CLIP_TAIL_BELOW_WORD_DB)
+    for shot, tail_end in tails:
+        if not tail_end - CLIP_TAIL_SECONDS <= end <= tail_end + CLIP_TAIL_SECONDS:
+            continue
+        level = tail_level(mono, sample_rate, tail_end)
+        if level is not None and level > floor:
+            return shot, level
+    return None
+
+
+def uncovered_speech_findings(spans, heard, duration):
+    """A `shot_coverage` skip entry (#1129) naming each stretch of the take
+    outside every supplied shot where words were heard: no shot rule looks
+    there, so a clean result must not read as checked."""
+    if not spans:
+        return []
+    gaps, cursor = [], 0.0
+    for span in sorted(spans, key=lambda s: s["start"]):
+        if span["start"] > cursor:
+            gaps.append((cursor, span["start"]))
+        cursor = max(cursor, span["end"])
+    if duration > cursor:
+        gaps.append((cursor, duration))
+    named = []
+    for start, end in gaps:
+        if any(start <= (w["start"] + w["end"]) / 2 < end for w in heard):
+            named.append(f"{round_seconds(start)}-{round_seconds(end)} s")
+    if not named:
+        return []
+    return [
+        {
+            "rule": "shot_coverage",
+            "reason": "speech was heard outside the supplied shot map and "
+            "not checked against any shot: " + ", ".join(named),
+        }
+    ]
+
+
+def loop_findings(chunks, script_words):
+    """A `transcript_loop` finding for each repetition loop over the script's
+    own words: Whisper stuck on a line it heard, so what follows the loop was
+    never transcribed and its lines read as mismatches (#961)."""
+    spoken = [c for c in chunks if normalize_words(c.get("text", ""))]
+    looped, firsts = looped_texts_firsts([c.get("text", "") for c in spoken])
+    found, run = [], []
+    for index in sorted(looped) + [None]:
+        if run and (index is None or index != run[-1] + 1):
+            if any(i in firsts for i in run):
+                members = [spoken[i] for i in run]
+                if all(
+                    set(normalize_words(m["text"])) <= script_words for m in members
+                ):
+                    at = entry_at(None, seconds=members[0]["start"])
+                    at["end"] = round_seconds(members[-1]["end"])
+                    found.append(finding(TRANSCRIPT_LOOP, len(members), at))
+            run = []
+        if index is not None:
+            run.append(index)
+    return found
+
+
+def silent_take_findings(heard, discarded, spans, shots_source):
+    """check's result for `lines: []`: any speech at all is the finding, and
+    the line and shot rules have nothing to compare against."""
+    findings = []
+    if heard:
+        findings.append(
+            finding(
+                SPEECH_WHERE_SILENT,
+                len(heard),
+                entry_at(None, heard[0], shot=heard_shot(spans, heard[0])),
+            )
+        )
+    return {
+        "findings": findings,
+        "lines": [],
+        "discarded": discarded,
+        "unmatched": [heard_entry(word) for word in heard],
+        "shots": shots_entry(spans),
+        "shots_source": shots_source,
+        "rules_applied": list(SILENT_RULES),
+        "rules_skipped": [
+            {"rule": rule, "reason": "lines is [] - no speech was expected"}
+            for rule in LINE_RULES + SHOT_RULES
+        ],
+    }
+
+
+def untranscribed_findings(
+    mono, sample_rate, index, own, shot, spans=None, parsed_lines=()
+):
+    """speech_not_transcribed: audible sound in a gap the line's words leave
+    - between two of them - or inside one word stretched over
+    UNHEARD_MIN_SECONDS (#923). The gap before a line's first word is
+    between_lines_findings'."""
+    intervals = [(a["end"], b["start"]) for a, b in zip(own, own[1:])]
+    findings = []
+    for start, end in intervals:
+        if end - start >= UNHEARD_MIN_SECONDS:
+            findings.extend(
+                _audible_findings(
+                    mono, sample_rate, index, start, end, shot, spans, parsed_lines
+                )
+            )
+    for word in own:
+        # A word is sound itself: only its interior past the margins is a gap
+        if (
+            word["end"] - word["start"]
+            >= UNHEARD_MIN_SECONDS + 2 * UNHEARD_MARGIN_SECONDS
+        ):
+            findings.extend(
+                _audible_findings(
+                    mono,
+                    sample_rate,
+                    index,
+                    word["start"],
+                    word["end"],
+                    shot,
+                    spans,
+                    parsed_lines,
+                )
+            )
+    return findings
+
+
+def between_lines_findings(
+    mono, sample_rate, index, start, end, shot, strays, spans=None, parsed_lines=()
+):
+    """speech_not_transcribed for the stretch between one line's last word and
+    the next line's first (#960): audible sound with no word, which the
+    in-line check cannot see when the timing leaves it outside both lines.
+    Heard-but-unmatched words in the gap are unscripted_speech's, but only the
+    stretches they cover: each stretch left between them is judged on its own
+    (#964). Each stretch is attributed to the shot holding most of it, and
+    to the line naming that shot (null when none does), not to the next
+    line's shot by default."""
+    if end - start < UNHEARD_MIN_SECONDS:
+        return []
+    inside = sorted(
+        (w for w in strays if w["start"] < end and w["end"] > start),
+        key=lambda w: w["start"],
+    )
+    stretches, cursor = [], start
+    for word in inside:
+        stretches.append((cursor, word["start"]))
+        cursor = max(cursor, word["end"])
+    stretches.append((cursor, end))
+    found = []
+    for lo, hi in stretches:
+        if hi - lo < UNHEARD_MIN_SECONDS:
+            continue
+        found.extend(
+            _audible_findings(
+                mono, sample_rate, index, lo, hi, shot, spans, parsed_lines
+            )
+        )
+    return [f for f in found if f is not None]
+
+
+def _audible_findings(
+    mono, sample_rate, index, start, end, shot, spans=None, parsed_lines=()
+):
+    """speech_not_transcribed for each audible block of [start, end], each
+    attributed to the shot holding most of it - and to the line naming that
+    shot, null when none does - not to the stretch's own line by default."""
+    found = []
+    pieces = []
+    for lo, hi in audible_runs(
+        mono,
+        sample_rate,
+        start,
+        end,
+        UNHEARD_FLOOR_DBFS,
+        UNHEARD_MIN_SECONDS,
+        UNHEARD_MARGIN_SECONDS,
+    ):
+        # A block crossing a shot seam is one finding per shot (#1115), so the
+        # shot that holds the untranscribed speech is named even if the other
+        # holds more of the block.
+        cuts = [lo]
+        if spans is not None:
+            cuts += sorted(
+                {s["start"] for s in spans if lo < s["start"] < hi}
+                | {s["end"] for s in spans if lo < s["end"] < hi}
+            )
+        cuts.append(hi)
+        parts = _folded(list(zip(cuts, cuts[1:])))
+        # Split only when each side is substantial; else one finding, placed
+        # by majority as before (#964)
+        pieces.extend(parts if len(parts) > 1 else [(lo, hi)])
+    for lo, hi in pieces:
+        where_line, where_shot = index, shot
+        holder = None if spans is None else overlapping_shot(spans, lo, hi)
+        if holder is not None and holder != shot:
+            where_shot = holder
+            where_line = next(
+                (i for i, line in enumerate(parsed_lines) if line["shot"] == holder),
+                None,
+            )
+        found.append(_untranscribed(mono, sample_rate, where_line, lo, hi, where_shot))
+    return [f for f in found if f is not None]
+
+
+def _folded(parts):
+    """`parts`, consecutive (start, end) slices of one block, with every slice
+    too short to stand as its own finding (under UNHEARD_MIN_SECONDS plus both
+    margins) folded into the slice before it - the first into the one after -
+    so a short shot a block covers whole is never dropped from the report, and
+    the block's whole span stays accounted for."""
+    least = UNHEARD_MIN_SECONDS + 2 * UNHEARD_MARGIN_SECONDS
+    folded = []
+    for a, b in parts:
+        if folded and (b - a < least or folded[-1][1] - folded[-1][0] < least):
+            folded[-1] = (folded[-1][0], b)
+        else:
+            folded.append((a, b))
+    return folded
+
+
+def is_looped_bed(mono, sample_rate, start, end):
+    """True when [start, end] repeats itself sample for sample (#1118): a
+    looped room-tone or score bed, which a voice never does. The measurement
+    is `dsp.repeat_correlation`; this is the decision."""
+    first, last = int(round(start * sample_rate)), int(round(end * sample_rate))
+    block = mono[max(0, first) : last]
+    return (
+        dsp.repeat_correlation(
+            block, sample_rate, BED_MIN_PERIOD_SECONDS, BED_MIN_OVERLAP_SECONDS
+        )
+        >= BED_CORRELATION
+    )
+
+
+def _untranscribed(mono, sample_rate, index, start, end, shot):
+    lo, hi = start + UNHEARD_MARGIN_SECONDS, end - UNHEARD_MARGIN_SECONDS
+    level = word_level(mono, sample_rate, lo, hi)
+    if level is None or level <= UNHEARD_FLOOR_DBFS:
+        return None
+    if is_looped_bed(mono, sample_rate, start, end):
+        return None
+    at = entry_at(index, seconds=start, shot=shot)
+    at["end"] = round_seconds(end)
+    return finding(SPEECH_NOT_TRANSCRIBED, round_seconds(end - start, 2), at)
+
+
+def clipped_findings(mono, sample_rate, tails, index, own, shot):
+    """line_clipped_at_end for one heard line, as a list of zero or one
+    finding: its last word ends in a voiced tail of its shot or the file. The
+    tail is judged against the whole line's loudest window, not the last
+    word's: under a score the ASR stretches the last word over the bed, and a
+    bed measured against itself passes the guard (#959)."""
+    end = own[-1]["end"]
+    clipped = clipped_tail(
+        mono, sample_rate, end, tails, (own[0]["start"], own[-1]["end"])
+    )
+    if clipped is None:
+        return []
+    at = {"line": index, "seconds": round_seconds(end), "word": own[-1]["text"]}
+    if clipped[0] is not None or shot is not None:
+        at["shot"] = clipped[0] or shot
+    return [finding(CLIPPED_AT_END, round_seconds(clipped[1], 2), at)]
+
+
+def unassigned_tags_findings(heard, unassigned, parsed_lines, expected, spans):
+    """tag_spoken for the heard words align left unassigned: a markup token
+    of a neighbouring line, spoken aloud between lines."""
+    findings = []
+    for j, neighbours in unassigned:
+        word = heard[j]
+        for index in neighbours:
+            if word["word"] in set(parsed_lines[index]["tokens"]) - set(
+                expected[index]
+            ):
+                findings.append(
+                    finding(
+                        TAG_SPOKEN,
+                        word["word"],
+                        entry_at(index, word, shot=heard_shot(spans, word)),
+                    )
+                )
+                break
+    return findings
+
+
+def silent_shot_findings(spans, parsed_lines, heard, claimed):
+    """speech_in_silent_shot: words heard inside a shot no line names, other
+    than those a line in another shot claimed."""
+    findings = []
+    named = {line["shot"] for line in parsed_lines if line["shot"]}
+    for span in spans:
+        if span["name"] in named:
+            continue
+        inside = [
+            word
+            for j, word in enumerate(heard)
+            if heard_shot(spans, word) == span["name"]
+            and claimed.get(j) in (None, span["name"])
+        ]
+        if inside:
+            at = entry_at(None, inside[0], shot=span["name"])
+            # A word straddling the cut into this shot is placed at the cut
+            at["seconds"] = max(at["seconds"], round_seconds(span["start"]))
+            findings.append(finding(SPEECH_IN_SILENT_SHOT, len(inside), at))
+    return findings
+
+
+def unscripted_findings(
+    spans, parsed_lines, expected, heard, unassigned, similarity_threshold
+):
+    """unscripted_speech: heard words align left to no line that sit inside a
+    shot a line names. `repeats_line` is set when the shot's words, in order,
+    contain one of its lines' words again, or score at least the mismatch
+    threshold against one of them (a repeat misheard as the line was)."""
+    findings = []
+    for span in spans:
+        lines = [
+            expected[i]
+            for i, line in enumerate(parsed_lines)
+            if line["shot"] == span["name"]
+        ]
+        if not lines:
+            continue
+        inside = [
+            heard[j]
+            for j, _ in unassigned
+            if heard_shot(spans, heard[j]) == span["name"]
+        ]
+        if not inside:
+            continue
+        at = entry_at(None, inside[0], shot=span["name"])
+        words = [word["word"] for word in inside]
+        at["end"] = round_seconds(inside[-1]["end"])
+        at["repeats_line"] = any(
+            line and contains_words(words, line) for line in lines
+        ) or any(line and contains_words(line, words) for line in lines)
+        if not at["repeats_line"]:
+            at["repeats_line"] = any(
+                line and line_similarity(line, words) >= similarity_threshold
+                for line in lines
+            )
+        findings.append(finding(UNSCRIPTED_SPEECH, len(inside), at))
+    return findings
+
+
+def contains_words(words, part):
+    """Whether `part` occurs in `words` as a contiguous run."""
+    size = len(part)
+    return any(words[i : i + size] == part for i in range(len(words) - size + 1))
+
+
+def heard_entry(word):
+    return {
+        "text": word["text"],
+        "start": round_seconds(word["start"]),
+        "end": round_seconds(word["end"]),
+    }
+
+
+def joined_words(words):
+    """The heard words as the transcript spelled them, one chunk once."""
+    texts = []
+    last = None
+    for word in words:
+        key = (word["start"], word["end"], word["text"])
+        if key != last:
+            texts.append(word["text"])
+            last = key
+    return " ".join(texts)
diff --git a/dw/tasks/sound_effects.py b/dw/tasks/sound_effects.py
index d7b300b3..096b6338 100644
--- a/dw/tasks/sound_effects.py
+++ b/dw/tasks/sound_effects.py
@@ -31,6 +31,7 @@
 """
 
 import logging
+import contextlib
 import os
 import tempfile
 
@@ -63,6 +64,10 @@
 SYNC_SIZE = 224
 # Synchformer reads 16-frame segments: the shortest clip it can encode
 MIN_SYNC_FRAMES = 16
+# The shortest sound this task makes: the Synchformer's 16 frames at 25 fps.
+# Under it the sync sequence is empty and the network fails after every model
+# has loaded, so a 'duration' below it is refused before anything loads
+MIN_DURATION = MIN_SYNC_FRAMES / SYNC_FPS
 # A bare frame list carries no rate; an AudioVideo or a file does
 ASSUMED_FPS = 24
 
@@ -83,15 +88,15 @@ def required_weights(arguments=None):
     MMAudio network and Synchformer, K6's audio_vae/ and vocoder/ config and
     safetensors, and DFN5B's open_clip weights and tokenizer. Never MMAudio's
     own v1-44.pth VAE or bigvgan_generator.pt: the decoder is K6's copy."""
-    from .mmaudio_clip import (
+    from ..vendored.mmaudio_clip import (
         CLIP_REPO_ID,
         CLIP_REVISION,
         CLIP_TOKENIZER_FILE,
         CLIP_WEIGHTS_FILE,
     )
     from .mmaudio_decoder import K6_REPO_ID, K6_REVISION
-    from .mmaudio_model import NETWORK_FILE, REPO_ID, REVISION
-    from .mmaudio_sync_model import SYNC_FILE
+    from ..vendored.mmaudio_model import NETWORK_FILE, REPO_ID, REVISION
+    from ..vendored.mmaudio_sync_model import SYNC_FILE
 
     entries = []
     for filename in (NETWORK_FILE, SYNC_FILE):
@@ -136,14 +141,21 @@ def _text(name, value):
 
 
 def _check_duration(duration, clip_seconds):
-    """The duration the run uses: the given one, refused over MAX_DURATION
-    or past the clip's end, else the clip's length (capped), else 8 s."""
+    """The duration the run uses: the given one, refused under MIN_DURATION,
+    over MAX_DURATION or past the clip's end, else the clip's length (capped),
+    else 8 s."""
     if duration is None:
         if clip_seconds is None:
             return TEXT_ONLY_DURATION
         return min(clip_seconds, MAX_DURATION)
     duration = float(real_number(duration, "duration", COMMAND))
     check_arguments(COMMAND, duration=duration)
+    if duration < MIN_DURATION:
+        raise ValueError(
+            f"{COMMAND}: 'duration' {duration:g} s is under the {MIN_DURATION:.2f} s "
+            f"this task generates at least ({MIN_SYNC_FRAMES} frames at {SYNC_FPS} "
+            "fps for the sync encoder); ask for more"
+        )
     if duration > MAX_DURATION:
         raise ValueError(
             f"{COMMAND}: 'duration' {duration:g} s is over the {MAX_DURATION:g} s "
@@ -185,7 +197,13 @@ def _video_file(video):
 
     handle, path = tempfile.mkstemp(suffix=".mp4", prefix="dw-sfx-")
     os.close(handle)
-    export_to_video(_frames_for_export_to_video(frames), path, fps=fps)
+    try:
+        export_to_video(_frames_for_export_to_video(frames), path, fps=fps)
+    except BaseException:
+        # The caller's cleanup starts only once this returns
+        with contextlib.suppress(OSError):
+            os.unlink(path)
+        raise
     return path, True
 
 
@@ -211,7 +229,7 @@ def _frame_tensors(path, duration):
     trim, which left a muxed cut ending in silence). Only when the clip ran
     short of frames does it fall back to the shorter span they cover."""
     from ..media import sample_frames
-    from .mmaudio_clip import ClipConfig
+    from ..vendored.mmaudio_clip import ClipConfig
 
     clip = sample_frames(path, CLIP_FPS, duration, ClipConfig().image_size)
     sync = sample_frames(path, SYNC_FPS, duration, SYNC_SIZE, crop=True)
@@ -297,7 +315,8 @@ def _load_models(device, dtype):
     under (command, repo, file, revision, device, dtype) and announced by
     `_cached`."""
     from ..events import emit_phase
-    from . import mmaudio_clip, mmaudio_decoder, mmaudio_model, mmaudio_sync_model
+    from . import mmaudio_decoder
+    from ..vendored import mmaudio_clip, mmaudio_model, mmaudio_sync_model
 
     repo, rev = mmaudio_model.REPO_ID, mmaudio_model.REVISION
     where = (str(device), str(dtype))
@@ -455,9 +474,9 @@ def generate_sound_effects(
 def _generate(
     frames, prompt, negative_prompt, duration, steps, guidance_scale, device, seed
 ):
-    from .mmaudio_clip import tokenize
-    from .mmaudio_model import sample_latent
-    from .mmaudio_sync_model import encode_sync_frames
+    from ..vendored.mmaudio_clip import tokenize
+    from ..vendored.mmaudio_model import sample_latent
+    from ..vendored.mmaudio_sync_model import encode_sync_frames
 
     dtype = _dtype(device)
     net, (clip, tokenizer), sync, decoder = _load_models(device, dtype)
diff --git a/dw/tasks/speech_generation.py b/dw/tasks/speech_generation.py
index a49523f0..e5ebce1b 100644
--- a/dw/tasks/speech_generation.py
+++ b/dw/tasks/speech_generation.py
@@ -26,12 +26,12 @@
 from ..dsp import as_channels_samples
 from ..media_types import AudioTrack
 from ..dsp import resample_waveform
-from .audio_utils import load_audio
+from .audio_utils import load_audio, waveform_and_rate
 from ..trust import (
     refuse_unused_task_remote_code,
     require_trusted_generate_arguments,
 )
-from . import audio8_tts_model as audio8
+from ..vendored import audio8_tts_model as audio8
 from .model_cache import cached_model, hf_pipeline_placement
 from .weights import argument_or_default, file_entries, repo_entries
 
@@ -292,7 +292,10 @@ def _generate_audio8(text, device, seed, kwargs, settings):
     reference = None
     reference_seconds = 0.0
     if reference_audio is not None:
-        waveform, sample_rate = load_audio(reference_audio)
+        # A path or URL, or an earlier audio step's output (#1134's shape)
+        waveform, sample_rate = waveform_and_rate(
+            reference_audio, None, "generate_speech"
+        )
         reference_seconds = waveform.shape[-1] / float(sample_rate)
         if reference_seconds > _AUDIO8_MAX_REFERENCE_SECONDS:
             raise ValueError(
@@ -355,6 +358,56 @@ def _generate_audio8(text, device, seed, kwargs, settings):
     return AudioTrack(as_channels_samples(samples), int(model.config.codec_sample_rate))
 
 
+def _transformers_pipe(model_name, device, dtype):
+    """The cached transformers text-to-speech pipeline for `model_name`."""
+
+    def load_pipe():
+        logger.info(f"Generating speech with {model_name} on {device}")
+        placement = hf_pipeline_placement(device)
+        return hf_pipeline(
+            "text-to-speech",
+            model=model_name,
+            torch_dtype=dtype,
+            **placement,
+        )
+
+    return cached_model(
+        ("speech_generation", model_name, str(device), str(dtype)), load_pipe
+    )
+
+
+def _with_voice_controls(
+    pipe, model_name, voice_preset, speaker_embedding, forward_params, device, dtype
+):
+    """`forward_params` with the x-vector a SpeechT5 `speaker_embedding` adds;
+    refuses a voice control the loaded model would silently drop."""
+    if voice_preset and getattr(pipe, "processor", None) is None:
+        # A single-voice model has no processor to hand the preset to;
+        # transformers logs the kwarg as unrecognised and speaks anyway
+        raise ValueError(
+            f"{model_name} takes no 'voice_preset' - it has one voice. Drop the "
+            "preset, or use a model with speaker presets such as suno/bark-small"
+        )
+    if not speaker_embedding:
+        return forward_params
+    model_type = getattr(getattr(pipe.model, "config", None), "model_type", None)
+    if model_type != "speecht5":
+        # Only SpeechT5 conditions on an x-vector; a model that does not
+        # would drop 'speaker_embeddings' as an unrecognised forward kwarg
+        # and generate in its own voice, same failure mode as voice_preset
+        raise ValueError(
+            f"{model_name} takes no 'speaker_embedding' - only a SpeechT5 "
+            "model conditions on an x-vector. Drop it, or use a SpeechT5 "
+            "model such as microsoft/speecht5_tts"
+        )
+    return {
+        **forward_params,
+        "speaker_embeddings": _speaker_embedding_tensor(
+            speaker_embedding, device, dtype
+        ),
+    }
+
+
 def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     """Speak a line of text with a local text-to-speech model - any
     transformers text-to-speech checkpoint named by model_name. Three
@@ -406,7 +459,8 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
                 which already reaches the model unchanged through
                 forward_params and needs no argument of its own.
             reference_audio: Edge0/Audio8-TTS-Realistic-0.6b only - a clip of
-                the voice to clone (typically an 'asset:' reference), at most
+                the voice to clone (an 'asset:' reference, a path or URL, or an
+                earlier audio step's 'previous_result:'), at most
                 20 s; 5-10 s of clean speech is plenty. Requires
                 reference_text. Refused on any other model, and refused
                 together with speaker_embedding, voice_preset or messages,
@@ -468,48 +522,11 @@ def generate_speech(text=None, device="cpu", seed=None, **kwargs):
     voice_preset = kwargs.get("voice_preset", None)
     speaker_embedding = kwargs.get("speaker_embedding", None)
     dtype = preferred_task_dtype(device)
-
-    def load_pipe():
-        logger.info(f"Generating speech with {model_name} on {device}")
-        placement = hf_pipeline_placement(device)
-        return hf_pipeline(
-            "text-to-speech",
-            model=model_name,
-            torch_dtype=dtype,
-            **placement,
-        )
-
-    pipe = cached_model(
-        ("speech_generation", model_name, str(device), str(dtype)),
-        load_pipe,
+    pipe = _transformers_pipe(model_name, device, dtype)
+    forward_params = _with_voice_controls(
+        pipe, model_name, voice_preset, speaker_embedding, forward_params, device, dtype
     )
 
-    if voice_preset and getattr(pipe, "processor", None) is None:
-        # A single-voice model has no processor to hand the preset to;
-        # transformers logs the kwarg as unrecognised and speaks anyway
-        raise ValueError(
-            f"{model_name} takes no 'voice_preset' - it has one voice. Drop the "
-            "preset, or use a model with speaker presets such as suno/bark-small"
-        )
-
-    if speaker_embedding:
-        model_type = getattr(getattr(pipe.model, "config", None), "model_type", None)
-        if model_type != "speecht5":
-            # Only SpeechT5 conditions on an x-vector; a model that does not
-            # would drop 'speaker_embeddings' as an unrecognised forward kwarg
-            # and generate in its own voice, same failure mode as voice_preset
-            raise ValueError(
-                f"{model_name} takes no 'speaker_embedding' - only a SpeechT5 "
-                "model conditions on an x-vector. Drop it, or use a SpeechT5 "
-                "model such as microsoft/speecht5_tts"
-            )
-        forward_params = {
-            **forward_params,
-            "speaker_embeddings": _speaker_embedding_tensor(
-                speaker_embedding, device, dtype
-            ),
-        }
-
     if messages is not None:
         logger.info(f"Speaking {len(messages)} chat-templated message(s)")
     else:
diff --git a/dw/vendored/__init__.py b/dw/vendored/__init__.py
new file mode 100644
index 00000000..12e7a9b4
--- /dev/null
+++ b/dw/vendored/__init__.py
@@ -0,0 +1,11 @@
+"""Upstream model code carried into dw as one module per port, each pinned to
+the upstream commit or Hub revision its docstring names, so a port can be
+diffed against its source and re-pinned as a unit. A port reaches dw only for
+its validated media loaders (dw/tasks/audio_utils.py, dw/dsp.py),
+and only a task module imports from here: dw/tasks/speech_generation.py
+(audio8_tts_model) and dw/tasks/sound_effects.py (the mmaudio_* modules).
+
+Like dw/community_pipelines/, this package is outside the architecture
+ratchet (scripts/arch_metrics.py EXCLUDED): a port keeps upstream's shape and
+size, which the module and function ceilings are not written for.
+"""
diff --git a/dw/tasks/audio8_tts_model.py b/dw/vendored/audio8_tts_model.py
similarity index 99%
rename from dw/tasks/audio8_tts_model.py
rename to dw/vendored/audio8_tts_model.py
index e28daff5..abd18764 100644
--- a/dw/tasks/audio8_tts_model.py
+++ b/dw/vendored/audio8_tts_model.py
@@ -1915,7 +1915,7 @@ def _load_audio(
     ) -> Tensor:
         source_rate = sampling_rate
         if isinstance(value, (str, Path)):
-            from .audio_utils import load_audio
+            from ..tasks.audio_utils import load_audio
 
             if str(value).lower().startswith(("http://", "https://")):
                 # load_audio would fetch it; this module reads local files only
diff --git a/dw/tasks/mmaudio_clip.py b/dw/vendored/mmaudio_clip.py
similarity index 99%
rename from dw/tasks/mmaudio_clip.py
rename to dw/vendored/mmaudio_clip.py
index 34bf675c..d9d1246f 100644
--- a/dw/tasks/mmaudio_clip.py
+++ b/dw/vendored/mmaudio_clip.py
@@ -1,5 +1,5 @@
 """
-DFN5B CLIP conditioning for MMAudio (dw/tasks/mmaudio_model.py), v1.
+DFN5B CLIP conditioning for MMAudio (dw/vendored/mmaudio_model.py), v1.
 
 Ported from https://github.com/hkchengrex/MMAudio at commit
 974010a026c731054592d8f777218bd9d85a6c24: the CLIP parts of
diff --git a/dw/tasks/mmaudio_model.py b/dw/vendored/mmaudio_model.py
similarity index 99%
rename from dw/tasks/mmaudio_model.py
rename to dw/vendored/mmaudio_model.py
index 969b3def..d097b584 100644
--- a/dw/tasks/mmaudio_model.py
+++ b/dw/vendored/mmaudio_model.py
@@ -6,7 +6,7 @@
 974010a026c731054592d8f777218bd9d85a6c24 (mmaudio/model/networks.py,
 transformer_layers.py, low_level.py, embeddings.py, sequence_config.py,
 flow_matching.py and mmaudio/ext/rotary_embeddings.py, merged into this one
-file). Its DFN5B CLIP conditioning is dw/tasks/mmaudio_clip.py. The weights
+file). Its DFN5B CLIP conditioning is dw/vendored/mmaudio_clip.py. The weights
 are hkchengrex/MMAudio's weights/mmaudio_large_44k_v2.pth (REPO_ID /
 REVISION below), under their own licence, stricter than this code's:
 CC-BY-NC 4.0, non-commercial use only.
diff --git a/dw/tasks/mmaudio_sync_model.py b/dw/vendored/mmaudio_sync_model.py
similarity index 100%
rename from dw/tasks/mmaudio_sync_model.py
rename to dw/vendored/mmaudio_sync_model.py
diff --git a/dw/writers.py b/dw/writers.py
index 68991f3f..17bfb10d 100644
--- a/dw/writers.py
+++ b/dw/writers.py
@@ -37,7 +37,7 @@ def exact_frame_rate(fps):
     # The NTSC family (24000/1001, 30000/1001, 60000/1001): a rounded 29.97
     # is within a hair of one, and 2997/100 would drift against its audio
     numerator = round(fps * 1001)
-    if numerator % 1000 == 0 and abs(numerator / 1001 - fps) < 0.005:
+    if numerator > 0 and numerator % 1000 == 0 and abs(numerator / 1001 - fps) < 0.005:
         return Fraction(numerator, 1001)
     rate = Fraction(fps).limit_denominator(1001)
     return rate if rate > 0 else Fraction(fps)
diff --git a/plugins/dw/skills/minimax-h3/SKILL.md b/plugins/dw/skills/minimax-h3/SKILL.md
index d7b943d0..eae9f050 100644
--- a/plugins/dw/skills/minimax-h3/SKILL.md
+++ b/plugins/dw/skills/minimax-h3/SKILL.md
@@ -14,14 +14,14 @@ H3 generates video and audio together. Every template fits a 24 GB card.
 2. `list_workflows(shape="shot")`, `list_workflows(shape="sequence")` and
    `list_workflows(shape="audio")`: the family's templates by name,
    `summary`, `traits`, `cost`; it outranks names below.
-3. `get_workflow` on the one chosen: its variables and defaults.
+3. `get_workflow` on the one chosen: variables and defaults.
 
 ## Which shape is the request
 
 - **One clip, up to 14.4 seconds, from text**: `templates/minimax/video-with-audio`
   (960x544, fast), or `templates/minimax/video-with-audio-768p` to render.
   From a one-line idea: `templates/minimax/enhance-prompt` writes it with the
-  built-in Context-IR enhancer first.
+  built-in enhancer first.
 - **Pinned to a picture**: first frame `templates/minimax/image-to-video`;
   first and last `templates/minimax/first-and-last-frame`; last only
   `templates/minimax/last-frame-only`; a one-line idea plus a picture
@@ -30,8 +30,8 @@ H3 generates video and audio together. Every template fits a 24 GB card.
   `hold_audio` keeps the first frame's pixels and the mouth follows the track
   (#985; add the argument to `templates/minimax/image-to-video`'s fl2va step).
   Fallback: Ref2VA `[keyframe completion + audio reuse]`, `<Picture 1>` the
-  first frame, `<Audio 1>` the song, also held (#852). It keeps the framing,
-  not the pixels, at ~4.7x the denoise; a last frame costs 45% more and does not land.
+  first frame, `<Audio 1>` the song, also held. Framing, not pixels,
+  at ~4.7x the denoise; a last frame costs 45% more and does not land.
 - **Pinned to a clip** (hold earlier footage): a `guides` argument on
   `t2va`/`fl2va` - up to 4 clips, 3 on a guide chain, each at a
   `frame` that is a multiple of 17; the VRAM ceiling charges each
@@ -47,7 +47,7 @@ H3 generates video and audio together. Every template fits a 24 GB card.
   `templates/minimax/composable-references` adds a video reference for
   framing and camera, at ~3.4x cost;
   `templates/minimax/generated-subject-reference` draws the subject with
-  Z-Image, references it in the same workflow;
+  Z-Image in the same workflow;
   `templates/minimax/voice-timbre-reference` fixes a voice from a Bark line.
 - **Several boards, one generation, unbroken score**:
   `templates/minimax/storyboard`, cuts no concat matches. One beat only;
@@ -66,8 +66,8 @@ H3 generates video and audio together. Every template fits a 24 GB card.
   voice carry the seam), `templates/minimax/chain-matched-to-audio` (a track
   sets the length), `templates/minimax/chain-matched-and-aligned`
   (per-segment prompts). Drift compounds per seam: reference the subject
-  picture each segment, prefer `last_segment` continuity, use the longest
-  segments memory allows.
+  picture each segment, prefer `last_segment`, use the longest segments
+  memory allows.
 - **A piece with cuts**: fresh shots from shared portraits, then a concat.
   `templates/minimax/dialogue-short` (Z-Image draws the cast, one shot per
   `shots` entry, `concat_videos` splices) and `templates/minimax/music-video`
@@ -81,9 +81,11 @@ H3 generates video and audio together. Every template fits a 24 GB card.
 - **Dialogue into a song**, not a concat: `slice_audio`, `join_into_song`,
   `pair_audio`, in that reference's last section.
 - **Unrelated shots, no cut**: `templates/minimax/shots-batch` - one H3
-  step per `shots` entry, no concat. `keep_output` each clip, then `templates/assemble-and-score` cuts and scores.
+  step per `shots` entry. `keep_output` each clip, then `templates/assemble-and-score` cuts and scores.
 - **Music alone**: `templates/minimax/music` (Music3); the `minimax-music3`
   skill - its `audio_duration` is a ceiling, not a length.
+- **Replace a shot's own sound**: `templates/video-to-sound-effects` (MMAudio,
+  7-25 dB hot: `match_levels` first), then `pair_audio`.
 
 If none fits, compose from `list_tasks` (the `workflows` guide's authoring
 section).
@@ -102,7 +104,8 @@ section).
   Never put an FL2VA LoRA on a reference template: `ref2va` holds
   `transformer_ref` alone, so anything handed there degrades output.
   `validate_workflow` refuses it, warns on a `weight_name` naming neither.
-- Smeary faces (int8 base) or draft -> final tiers: `references/quality-and-speed.md`.
+- Smeary faces (int8 base), draft -> final tiers, or sharper than 768p (tiled
+  1080p latent refine, `refine_sigmas`): `references/quality-and-speed.md`.
 - Backend: default `sparse` (dense off CUDA); same one at draft and final.
 - A crowd, two people in frame, or a three-reference shot: read
   `references/staging.md` before the prompt - who lip-syncs, where the
@@ -117,11 +120,11 @@ section).
   (~4 dB more high band): `lora_model_name: null`, `num_inference_steps: 12`,
   `video_shift: 12.0`, `audio_shift: 3.0`; int4 stays fine without it. Turbo stays the default otherwise (#984 B0).
 - Nothing carries between generations except a passed reference, a
-  held track or a `guides` clip: there is no latent memory. Identity rides
+  held track or a `guides` clip. Identity rides
   on a picture, voice timbre on an audio clip, motion/camera on a video
   tail, score across cuts under concat.
 - Lip sync to supplied audio: an audio reference alone, as the
-  `match_audio` chains pass it, can sing shifted beats off the track; `music-video`
+  `match_audio` chains pass it, can sing beats off the track; `music-video`
   holds each slice as well by default, and the chains' `hold_audio` variable adds a
   hold (`references/cuts.md`, #795, #808).
 - Guidance-distilled: no `guidance_scale` or negative prompt.
@@ -150,7 +153,7 @@ the rules are MiniMax's:
 
 Either way: write the whole script before the first shot. Repeat a speaker's voice description verbatim across shots.
 Several characters: one cropped reference each, never a group picture, which imposes its framing on every shot (`references/per-character.md`).
-Before writing lines, read `references/dialogue.md`: how long a line fits a clip, and what not to name.
+Before writing lines, read `references/dialogue.md`: how long a line fits, and what not to name.
 A wanted look (clay, paper): `references/style.md`.
 
 ## Run and judge
@@ -175,8 +178,8 @@ A wanted look (clay, paper): `references/style.md`.
    `intermediate` the scratch.
 4. Judge: `get_output_frames(count=12)` for a clip's shape,
    `seams=true` (each later shot's start frame) for a cut's joins - a
-   character that changes between shots (reference the same portraits
-   everywhere), a portrait imposing its framing on every shot - `at` late in
+   character changing between shots (same portraits everywhere), a
+   portrait's framing imposed on every shot - `at` late in
    a chain for drift sharpening to noise, and `get_output_audio` for a
    voice-over without affect. It returns sound, not text; to confirm a
    take's lines, run `templates/check-script` with them as `lines` (markup
@@ -184,8 +187,7 @@ A wanted look (clay, paper): `references/style.md`.
    `find_loop_bed` the `output:` cut, then `slice_audio`->`loop_audio`->`mix_audio`
    its pick at its `gain`.
    Then `get_gallery_metadata` for duration/audio and hand the
-   user the gallery `url`. `get_output_image` is for image
-   steps only.
+   user the gallery `url`.
 5. After a run worth keeping, `get_job_workflow` and `save_workflow` it;
    `export_job` bundles it on the server. `auth_required: false` - fetch
    `open_url` into `exports/` (never a temp dir). `true` - hand `open_url`
@@ -193,5 +195,5 @@ A wanted look (clay, paper): `references/style.md`.
 
 ## Sources
 
-Model card, prompt guides, `h3-prompt-writing`, diffusers' pipeline,
-`lightx2v/Minimax-h3-Turbo` notes; read 2026-09-07; audit `docs/proposals/audits/2026-09-07-minimax-h3-audit.md`.
+Model card, prompt guides, `h3-prompt-writing`, diffusers' pipeline, turbo
+LoRA notes; read 2026-09-07; audit `docs/proposals/audits/2026-09-07-minimax-h3-audit.md`.
diff --git a/plugins/dw/skills/minimax-h3/references/quality-and-speed.md b/plugins/dw/skills/minimax-h3/references/quality-and-speed.md
index cc679ef9..13e88388 100644
--- a/plugins/dw/skills/minimax-h3/references/quality-and-speed.md
+++ b/plugins/dw/skills/minimax-h3/references/quality-and-speed.md
@@ -165,6 +165,24 @@ Every rung above moves one. Quote that rung's minutes from the ladder instead
 (the *Attn* column says which backend they were measured with), and say
 which figure you are quoting.
 
+## Past 768p: the latent refine
+
+H3 renders at most 768x1344. A sharper deliverable is a second pass on the
+take's own latents, not a re-render: `upscale_h3_latents` scales the base
+take's latents (cap 1920x1088 or 1088x1920), and an H3 step with `latents`,
+`hold_audio` (the take's soundtrack) and `refine_strength` re-denoises them -
+in feathered tiles (`refine_tiles: {width, height, overlap}` on the 32 px
+grid) so 1080p fits a 24 GB card, about 12 min on an RTX 3090 for 124
+frames. The recipe, the strength bands and the one-decode rule are the
+`workflows` guide's *Refining above 768p in tiles*, *Promoting an H3 take to
+768p in latent space* and *Refining the upscaled latents: refine_strength*;
+`refine_sigmas` (*Explicit refine sigmas*) replaces the shift-spaced schedule
+with the sigma points themselves when a measured schedule is wanted. Validate
+refuses a full-frame refine whose size disagrees with the upscaled latents,
+and references, guides and keyframes in tile mode. A regional fix of one area
+of a good take is `templates/minimax/regional-edit` (`references/regional-edit.md`),
+not a refine of the whole canvas.
+
 ## Prompting the base model
 
 - It invents an extra person unless every subject is placed explicitly
diff --git a/scripts/arch_metrics.py b/scripts/arch_metrics.py
index cee47f60..0ca73653 100644
--- a/scripts/arch_metrics.py
+++ b/scripts/arch_metrics.py
@@ -6,7 +6,8 @@
 to record a baseline and --check to compare against one.
 
 Counting rules, fixed so any commit measures the same way:
-- Sources are dw/ and dw_mcp/, minus EXCLUDED (vendored community pipelines).
+- Sources are dw/ and dw_mcp/, minus EXCLUDED (vendored community pipelines
+  and the upstream model ports in dw/vendored/).
 - Module size is a band: modules_over_size_ceiling counts modules above
   SIZE_CEILING (1,100 lines, ratcheted); a module above SIZE_WARNING (1,000)
   and at or under the ceiling is printed as a `warning:` line on every run,
@@ -61,8 +62,16 @@
 )
 # Modules allowed to spell a reference prefix: the one owner (Phase 2a)
 PREFIX_OWNERS = frozenset({"dw/references.py"})
-# .claude: agent worktrees live under .claude/worktrees, each a full checkout
-EXCLUDED = ("community_pipelines", "node_modules", "venv", ".git", ".claude")
+# .claude: agent worktrees live under .claude/worktrees, each a full checkout.
+# vendored: dw/vendored/, upstream model ports kept at their source's shape
+EXCLUDED = (
+    "community_pipelines",
+    "vendored",
+    "node_modules",
+    "venv",
+    ".git",
+    ".claude",
+)
 PACKAGES = ("dw", "dw_mcp")
 REFERENCES_MODULE = "dw/references.py"
 FALLBACK_REFERENCE_NAMES = frozenset(
diff --git a/tests/test_arch_metrics.py b/tests/test_arch_metrics.py
index 2c9d3c87..34a76892 100644
--- a/tests/test_arch_metrics.py
+++ b/tests/test_arch_metrics.py
@@ -353,3 +353,14 @@ def test_a_fragment_ending_in_a_word_that_merely_ends_like_a_prefix_is_not_count
         )
     )
     assert metrics["prefix_handling"] == 1
+
+
+def test_vendored_model_ports_are_not_counted(tmp_path):
+    # dw/vendored/ holds upstream model code at its source's shape, outside the
+    # module and function ceilings like dw/community_pipelines/
+    metrics = _load().measure(
+        _tree(tmp_path, {"dw/vendored/port.py": _long_function(200) + "\n" * 1000})
+    )
+    assert metrics["modules"] == 0
+    assert metrics["functions_over_150_lines"] == 0
+    assert metrics["modules_over_size_ceiling"] == 0
diff --git a/tests/test_audio8_tts_model.py b/tests/test_audio8_tts_model.py
index 7e6480da..cf57ab55 100644
--- a/tests/test_audio8_tts_model.py
+++ b/tests/test_audio8_tts_model.py
@@ -11,7 +11,7 @@
 import pytest
 import torch
 
-from dw.tasks import audio8_tts_model as a8
+from dw.vendored import audio8_tts_model as a8
 
 MODULE_PATH = Path(a8.__file__)
 
diff --git a/tests/test_fractional_fps.py b/tests/test_fractional_fps.py
index 1536229a..7928ba5f 100644
--- a/tests/test_fractional_fps.py
+++ b/tests/test_fractional_fps.py
@@ -35,6 +35,13 @@ def test_exact_frame_rate(fps, expected):
     assert exact_frame_rate(fps) == expected
 
 
+def test_a_tiny_rate_is_never_zero():
+    # round(fps * 1001) is 0 for a rate under about 0.0005, and 0 % 1000 == 0
+    # took the NTSC branch to Fraction(0, 1001), a rate PyAV refuses at write
+    rate = exact_frame_rate(1e-9)
+    assert rate > 0
+
+
 def test_encode_video_with_audio_keeps_fractional_rate(tmp_path):
     path = tmp_path / "out.mp4"
     encode_video(
diff --git a/tests/test_h3_mask.py b/tests/test_h3_mask.py
index a0d83741..d8712550 100644
--- a/tests/test_h3_mask.py
+++ b/tests/test_h3_mask.py
@@ -13,12 +13,11 @@
 from dw.hold_audio import mask_errors
 from dw.pipeline_processors import h3_mask
 from dw.pipeline_processors.h3_hold import core_denoise_sequences
-from dw.pipeline_processors.h3_mask import (
+from dw.pipeline_processors.h3_mask import edits_regions, insert_mask_blocks
+from dw.pipeline_processors.h3_mask_cells import (
     _dilate,
     _pool,
     binarized,
-    edits_regions,
-    insert_mask_blocks,
     keep_rows,
     regenerate_cells,
 )
@@ -523,11 +522,11 @@ def run_block(self, monkeypatch, mask, strength):
         )
         state = PipelineState()
         state.set("latents", torch.randn(3 * 4 * 4, 4))
-        state.set("source_video", np.zeros((9, SIDE, SIDE, 3), dtype=np.uint8))
+        state.set("source_video", np.zeros((22, SIDE, SIDE, 3), dtype=np.uint8))
         state.set(REGENERATE_MASK, mask)
         state.set("mask_grow", 0)
         state.set("refine_strength", strength)
-        for name, value in (("height", SIDE), ("width", SIDE), ("num_frames", 9)):
+        for name, value in (("height", SIDE), ("width", SIDE), ("num_frames", 22)):
             state.set(name, value)
         state.set("num_latent_frames", 3)
         state.set("latent_height", LATENT_SIDE)
@@ -661,18 +660,31 @@ def test_a_size_mismatch_is_reported(self):
         assert "96x64" in problems[0] and "128x128" in problems[0]
 
     def test_a_frame_mismatch_is_reported(self):
-        problems = media_problems("mask_video", (5, 128, 128), 128, 128, 9)
+        problems = media_problems("mask_video", (5, 128, 128), 128, 128, 22)
         assert len(problems) == 1
-        assert "5 frames" in problems[0] and "num_frames=9" in problems[0]
+        assert "5 frames" in problems[0] and "num_frames=22" in problems[0]
 
     def test_a_match_is_clean(self):
-        assert media_problems("source_video", (9, 128, 128), 128, 128, 9) == []
+        assert media_problems("source_video", (22, 128, 128), 128, 128, 22) == []
+
+    def test_a_source_off_the_render_grid_is_refused(self):
+        # 125 frames match num_frames, but H3 renders 141 and pads the source,
+        # so the mask drifts in time: refused with both grid neighbours named
+        problems = media_problems("source_video", (125, 128, 128), 128, 128, 125)
+        assert len(problems) == 1
+        assert "17n + 5" in problems[0]
+        assert "render 141" in problems[0] and "124 frames" in problems[0]
+
+    def test_a_mask_video_off_the_grid_is_the_frame_mismatch_only(self):
+        # The mask is held to the source's count; the grid is the source's rule
+        problems = media_problems("mask_video", (125, 128, 128), 128, 128, 125)
+        assert problems == []
 
     def test_a_mask_image_ignores_frames(self):
-        assert media_problems("mask_image", (1, 128, 128), 128, 128, 9) == []
+        assert media_problems("mask_image", (1, 128, 128), 128, 128, 22) == []
 
     def test_a_mask_image_still_checks_size(self):
-        assert len(media_problems("mask_image", (1, 64, 64), 128, 128, 9)) == 1
+        assert len(media_problems("mask_image", (1, 64, 64), 128, 128, 22)) == 1
 
     def test_no_frame_count_skips_the_frame_check(self):
         assert media_problems("source_video", (3, 128, 128), 128, 128) == []
@@ -795,7 +807,7 @@ def test_the_check_is_registered(self):
 # 5c. Validation reads the files: size, frame count and an empty mask (#1077)
 
 
-def write_video(path, frames=9, size=(64, 48), value=0, sample_rate=None):
+def write_video(path, frames=22, size=(64, 48), value=0, sample_rate=None):
     """A real h264 mp4 of `frames` flat frames at `value`, `size` (w, h), with a
     soundtrack when `sample_rate` is given."""
     import av
@@ -852,8 +864,19 @@ def test_a_source_off_the_canvas_is_refused(self, tmp_path):
         assert errors[0]["path"].endswith("source_video")
         assert "64x48" in errors[0]["message"] and "128x48" in errors[0]["message"]
 
-    def test_a_source_frame_mismatch_is_refused(self, tmp_path):
+    def test_a_source_off_the_grid_is_refused_before_the_run(self, tmp_path):
+        # 9 frames: validate used to pass it (canvas = source) and the pipeline
+        # then rendered 22 over a padded source
         source = write_video(tmp_path / "src.mp4", frames=9)
+        errors = probed_errors(tmp_path, source_video=source)
+        assert len(errors) == 1
+        assert errors[0]["path"].endswith("source_video")
+        assert (
+            "17n + 5" in errors[0]["message"] and "pad it to 22" in errors[0]["message"]
+        )
+
+    def test_a_source_frame_mismatch_is_refused(self, tmp_path):
+        source = write_video(tmp_path / "src.mp4", frames=22)
         errors = probed_errors(tmp_path, source_video=source, num_frames=17)
         assert len(errors) == 1
         assert "num_frames=17" in errors[0]["message"]
@@ -888,7 +911,7 @@ def test_a_white_mask_video_that_fits_is_clean(self, tmp_path):
         assert probed_errors(tmp_path, source_video=source, mask_video=mask) == []
 
     def test_a_mask_video_frame_mismatch_is_refused(self, tmp_path):
-        source = write_video(tmp_path / "src.mp4", frames=9)
+        source = write_video(tmp_path / "src.mp4", frames=22)
         mask = write_video(tmp_path / "m.mp4", frames=5, value=255)
         errors = probed_errors(tmp_path, source_video=source, mask_video=mask)
         assert len(errors) == 1
@@ -927,7 +950,7 @@ def test_the_size_refusal_surfaces_through_the_workflow(self, tmp_path):
             hold_audio=source,
             width=64,
             height=48,
-            num_frames=9,
+            num_frames=22,
         )
         workflow = workflow_from_definition(
             definition, str(tmp_path), base_dir=str(tmp_path)
diff --git a/tests/test_h3_refine.py b/tests/test_h3_refine.py
index a8275364..f4794f2e 100644
--- a/tests/test_h3_refine.py
+++ b/tests/test_h3_refine.py
@@ -903,6 +903,18 @@ def explicit(**overrides):
         "not a list of numbers",
         id="a-bool",
     ),
+    pytest.param(
+        {"refine_sigmas": [0.909375, float("nan"), 0]},
+        "finite",
+        id="nan",
+    ),
+    pytest.param(
+        # Distinct as float64, equal as the scheduler's float32: refused here,
+        # not after the load
+        {"refine_sigmas": [0.909375, 0.5, 0.5 - 1e-9, 0], "num_inference_steps": 4},
+        "float32",
+        id="float32-collapse",
+    ),
 ]
 
 
diff --git a/tests/test_media_frames.py b/tests/test_media_frames.py
index 098e469a..e8991ca7 100644
--- a/tests/test_media_frames.py
+++ b/tests/test_media_frames.py
@@ -449,7 +449,7 @@ def opening(*args, **kwargs):
         proxies.append(Overshooting(real_open(*args, **kwargs)))
         return proxies[-1]
 
-    with mock.patch("dw.media.av.open", side_effect=opening):
+    with mock.patch("dw.media_readers.av.open", side_effect=opening):
         tiles = frames_at(str(tmp_path / "gop.mp4"), ["frame:35"])
 
     assert grey_of(tiles[0]["image"]) == pytest.approx((35 % 25) * 10, abs=6)
diff --git a/tests/test_media_layering.py b/tests/test_media_layering.py
index bd5a513f..8b9b73a7 100644
--- a/tests/test_media_layering.py
+++ b/tests/test_media_layering.py
@@ -99,10 +99,10 @@ def test_av_open_appears_only_in_media():
     offenders = []
     for path, tree in sources():
         relative = path.relative_to(ROOT).as_posix()
-        if relative == "dw/media.py":
+        if relative in ("dw/media.py", "dw/media_readers.py"):
             continue
         offenders.extend(f"{relative}:{line}" for line in av_open_lines(tree))
-    assert offenders == [], f"av.open outside dw/media.py: {offenders}"
+    assert offenders == [], f"av.open outside dw/media*.py: {offenders}"
 
 
 @pytest.mark.parametrize(
diff --git a/tests/test_mmaudio_model.py b/tests/test_mmaudio_model.py
index 769f0ccb..538326f5 100644
--- a/tests/test_mmaudio_model.py
+++ b/tests/test_mmaudio_model.py
@@ -1,5 +1,5 @@
-"""The vendored MMAudio network and Euler sampler (dw/tasks/mmaudio_model.py)
-and its DFN5B CLIP key map and towers (dw/tasks/mmaudio_clip.py), on tiny random configurations on CPU."""
+"""The vendored MMAudio network and Euler sampler (dw/vendored/mmaudio_model.py)
+and its DFN5B CLIP key map and towers (dw/vendored/mmaudio_clip.py), on tiny random configurations on CPU."""
 
 import math
 import re
@@ -9,8 +9,8 @@
 import torch
 import torch.nn.functional as F
 
-import dw.tasks.mmaudio_clip as mc
-import dw.tasks.mmaudio_model as mm
+import dw.vendored.mmaudio_clip as mc
+import dw.vendored.mmaudio_model as mm
 
 MODULE_PATH = Path(mm.__file__)
 CLIP_MODULE_PATH = Path(mc.__file__)
@@ -532,8 +532,14 @@ def test_weights_are_pinned():
 
 def test_modules_are_imported_only_by_the_sound_effects_task():
     # stage D (#1133): generate_sound_effects is their one consumer
-    own = {MODULE_PATH, CLIP_MODULE_PATH, MODULE_PATH.parent / "sound_effects.py"}
-    for path in MODULE_PATH.parents[1].rglob("*.py"):
+    dw = MODULE_PATH.parents[1]  # dw/, with the ports under dw/vendored/
+    own = {
+        MODULE_PATH,
+        CLIP_MODULE_PATH,
+        dw / "tasks" / "sound_effects.py",
+        dw / "vendored" / "__init__.py",
+    }
+    for path in dw.rglob("*.py"):
         if path not in own:
             text = path.read_text(encoding="utf-8")
             assert "mmaudio_model" not in text and "mmaudio_clip" not in text, path
diff --git a/tests/test_mmaudio_sync_model.py b/tests/test_mmaudio_sync_model.py
index e420ea54..f3e1e783 100644
--- a/tests/test_mmaudio_sync_model.py
+++ b/tests/test_mmaudio_sync_model.py
@@ -1,4 +1,4 @@
-"""The vendored Synchformer visual encoder (dw/tasks/mmaudio_sync_model.py)."""
+"""The vendored Synchformer visual encoder (dw/vendored/mmaudio_sync_model.py)."""
 
 import re
 from pathlib import Path
@@ -6,9 +6,10 @@
 import pytest
 import torch
 
-from dw.tasks import mmaudio_sync_model as sm
+from dw.vendored import mmaudio_sync_model as sm
 
 MODULE_PATH = Path(sm.__file__)
+DW = MODULE_PATH.parents[1]  # dw/, with the port under dw/vendored/
 TINY = sm.SyncConfig(
     image_size=32,
     patch_size=16,
@@ -183,7 +184,12 @@ def test_weights_are_pinned():
 
 def test_module_is_imported_only_by_the_sound_effects_task():
     # stage D (#1133): generate_sound_effects is its one consumer
-    for path in MODULE_PATH.parents[1].rglob("*.py"):
-        if path not in (MODULE_PATH, MODULE_PATH.parent / "sound_effects.py"):
+    own = {
+        MODULE_PATH,
+        DW / "tasks" / "sound_effects.py",
+        DW / "vendored" / "__init__.py",
+    }
+    for path in DW.rglob("*.py"):
+        if path not in own:
             text = path.read_text(encoding="utf-8")
             assert "mmaudio_sync_model" not in text, path
diff --git a/tests/test_plugin_skills.py b/tests/test_plugin_skills.py
index 2067b1c9..f9b27023 100644
--- a/tests/test_plugin_skills.py
+++ b/tests/test_plugin_skills.py
@@ -559,7 +559,7 @@ def test_the_regional_edit_branch_is_the_template_s_and_the_guide_s(self):
             mask_errors,
             refine_strength_errors,
         )
-        from dw.pipeline_processors import h3_mask
+        from dw.pipeline_processors import h3_mask_cells
 
         text = skill_text(H3_SKILL)
         assert "`templates/minimax/regional-edit`" in text
@@ -614,7 +614,7 @@ def test_the_regional_edit_branch_is_the_template_s_and_the_guide_s(self):
         # Both wrap their prose, so the grain is matched with the lines joined
         assert "16 px times the patch size" in " ".join(guide.split())
         assert "16 px times the patch size" in " ".join(reference.split())
-        assert "`16 * patch`" in inspect.getsource(h3_mask)
+        assert "`16 * patch`" in inspect.getsource(h3_mask_cells)
 
 
 LTX_SKILL = os.path.join(PLUGIN_DIR, "skills", "ltx-2.5", "SKILL.md")
diff --git a/tests/test_script_check.py b/tests/test_script_check.py
index 510c072f..c2cf02f7 100644
--- a/tests/test_script_check.py
+++ b/tests/test_script_check.py
@@ -1024,6 +1024,30 @@ def test_an_unheard_line_cut_off_by_its_shot_is_clipped(self):
             [s for s in skipped(answer, "line_clipped_at_end") if "line" in s], []
         )
 
+    def test_a_short_shot_covered_whole_by_a_block_is_not_dropped(self):
+        # #1115 follow-up: sound 1-10 s over A | M | B with M only 1.0 s wide,
+        # under the 1.5 s a piece needs on its own. It used to be filtered
+        # out of the split; folded into A instead, the whole span is reported
+        spans = [
+            {"name": "A", "start": 0.0, "end": 4.0},
+            {"name": "M", "start": 4.0, "end": 5.0},
+            {"name": "B", "start": 5.0, "end": 11.0},
+        ]
+        chunks = [
+            {"start": 0.9, "end": 10.6, "text": " alpha"},
+            {"start": 10.6, "end": 11.0, "text": " bravo"},
+        ]
+        mono = numpy.concatenate([silent(1.0), voiced(9.0), silent(1.0)])
+        answer = shot_run(
+            [{"text": "alpha bravo", "shot": "B"}], chunks, mono=mono, spans=spans
+        )
+        found = sorted(
+            rules(answer, "speech_not_transcribed"), key=lambda f: f["at"]["seconds"]
+        )
+        self.assertEqual([f["at"]["shot"] for f in found], ["A", "B"])
+        self.assertAlmostEqual(found[0]["at"]["end"], 5.0, places=1)
+        self.assertAlmostEqual(found[1]["at"]["seconds"], 5.0, places=1)
+
     def test_an_unheard_line_with_nothing_to_check_is_listed_skipped(self):
         chunks = words("charlie delta", 6.0)
         mono = numpy.concatenate([silent(6.0), voiced(5.042)])
diff --git a/tests/test_sound_effects.py b/tests/test_sound_effects.py
index 7f568eec..aaa216d0 100644
--- a/tests/test_sound_effects.py
+++ b/tests/test_sound_effects.py
@@ -55,6 +55,15 @@ def test_a_text_only_duration_over_20(self, no_load):
         with pytest.raises(ValueError, match="'duration'"):
             generate_sound_effects(prompt="rain", duration=21)
 
+    def test_a_duration_under_the_sync_window(self, no_load):
+        # Under 16 frames at 25 fps the sync sequence is empty and the network
+        # failed after every model had loaded; refused first instead
+        with pytest.raises(ValueError, match="under the 0.64 s"):
+            generate_sound_effects(prompt="click", duration=0.5)
+
+    def test_the_shortest_duration_is_taken(self):
+        assert sound_effects._check_duration(0.64, None) == 0.64
+
     def test_a_duration_longer_than_the_clip(self, no_load, two_second_clip):
         with pytest.raises(ValueError, match="'duration'"):
             generate_sound_effects(video=two_second_clip, duration=3)
@@ -130,7 +139,7 @@ def test_silence_is_not_noise(self, warnings):
 
 class TestRunWithStubs:
     def test_text_only_run(self, monkeypatch):
-        from dw.tasks import mmaudio_clip, mmaudio_model
+        from dw.vendored import mmaudio_clip, mmaudio_model
 
         class Net:
             clip_seq_len = 64
@@ -195,7 +204,7 @@ class TestClipLengthDefault:
     (#1133 bounce, C-F620: a 2.083 s clip came back as 2.0 s of sound)."""
 
     def test_frames_cover_the_whole_fractional_clip(self, fractional_clip):
-        from dw.tasks.mmaudio_model import SequenceConfig
+        from dw.vendored.mmaudio_model import SequenceConfig
 
         seconds = sound_effects._clip_seconds(fractional_clip)
         assert seconds == pytest.approx(50 / 24)
@@ -221,8 +230,8 @@ def short(path, fps, duration, size, crop=False):
         assert covered == pytest.approx(min(14 / 8, 50 / 25))
 
     def test_the_run_returns_the_clip_length(self, monkeypatch, fractional_clip):
-        from dw.tasks import mmaudio_clip, mmaudio_model, mmaudio_sync_model
-        from dw.tasks.mmaudio_model import SequenceConfig
+        from dw.vendored import mmaudio_clip, mmaudio_model, mmaudio_sync_model
+        from dw.vendored.mmaudio_model import SequenceConfig
 
         class Net:
             device = torch.device("cpu")
@@ -328,13 +337,8 @@ def events(self, monkeypatch):
         import huggingface_hub
 
         from dw import events as dw_events
-        from dw.tasks import (
-            mmaudio_clip,
-            mmaudio_decoder,
-            mmaudio_model,
-            mmaudio_sync_model,
-            model_cache,
-        )
+        from dw.tasks import mmaudio_decoder, model_cache
+        from dw.vendored import mmaudio_clip, mmaudio_model, mmaudio_sync_model
 
         monkeypatch.setattr(
             huggingface_hub,
@@ -363,7 +367,8 @@ def emit(self, event_type, **data):
         dw_events.deactivate_context(token)
 
     def revisions(self):
-        from dw.tasks import mmaudio_clip, mmaudio_decoder, mmaudio_model
+        from dw.tasks import mmaudio_decoder
+        from dw.vendored import mmaudio_clip, mmaudio_model
 
         return {
             mmaudio_model.REPO_ID: mmaudio_model.REVISION,
diff --git a/tests/test_speech_generation.py b/tests/test_speech_generation.py
index 60ebe01c..0b9c6635 100644
--- a/tests/test_speech_generation.py
+++ b/tests/test_speech_generation.py
@@ -472,7 +472,7 @@ def seed_for(self, arguments):
 
 import pytest  # noqa: E402
 
-from dw.tasks import audio8_tts_model as a8  # noqa: E402
+from dw.vendored import audio8_tts_model as a8  # noqa: E402
 from dw.tasks import speech_generation as sg  # noqa: E402
 from dw.tasks.model_cache import clear_model_cache  # noqa: E402
 from tests.test_audio8_tts_model import TINY, legacy_codec_state  # noqa: E402
diff --git a/tests/test_task_weights.py b/tests/test_task_weights.py
index b3127680..c9130f5d 100644
--- a/tests/test_task_weights.py
+++ b/tests/test_task_weights.py
@@ -135,7 +135,7 @@ def test_a_local_model_still_lists_the_speaker_encoder(self):
     def test_audio8_lists_its_pinned_files_and_the_codec(self):
         # #1121: a vendored model fetched file by file at one revision, so
         # the plan names each file - codec.pth among them - not the repo
-        from dw.tasks import audio8_tts_model as a8
+        from dw.vendored import audio8_tts_model as a8
 
         hook = required_weights_hook("generate_speech")
         entries = hook({"model_name": a8.REPO_ID})
@@ -196,14 +196,8 @@ def test_the_loader_downloads_what_the_plan_declares(self, monkeypatch):
         import huggingface_hub
         import torch
 
-        from dw.tasks import (
-            mmaudio_clip,
-            mmaudio_decoder,
-            mmaudio_model,
-            mmaudio_sync_model,
-            model_cache,
-            sound_effects,
-        )
+        from dw.tasks import mmaudio_decoder, model_cache, sound_effects
+        from dw.vendored import mmaudio_clip, mmaudio_model, mmaudio_sync_model
 
         downloads = []
 
@@ -453,7 +447,7 @@ def test_generate_speech_loads_the_repo_it_declares(self, monkeypatch, arguments
         assert [key[1] for key in keys] == declared("generate_speech", arguments)
 
     def test_generate_speech_loads_the_audio8_repo_it_declares(self, monkeypatch):
-        from dw.tasks import audio8_tts_model as a8
+        from dw.vendored import audio8_tts_model as a8
         from dw.tasks import speech_generation
 
         keys = recording_cache(monkeypatch, speech_generation)