perf(video): accuracy-first round 2 for HunyuanVideo-1.5: compile parity, cache quality presets, dual-GPU CFG

Cuts the shipped default's LPIPS vs the bit-exact reference from 0.224 to 0.139
while going faster (24.9 s to 21.2 s at 720p/33f/30 steps, 22.7x vs reference),
and makes the remaining speed/accuracy trade a user knob.

- inductor precision parity: set emulate_precision_casts=True for the regional
  compile (fused pointwise kernels kept fp32 intermediates where eager rounds to
  bf16 between ops); full-clip LPIPS vs bit-exact 0.221 to 0.052 at zero speed
  cost. Snapshot/restored with the other process-wide backend flags.
- cache x compile composition fix: diffusers cache hooks are
  torch.compiler.disable'd, so every COMPUTED step ran eager (1.69 vs 1.09
  s/step) under MagCache/FBCache in both enable orders. Re-point each hook's
  fn_ref.original_forward at a torch.compile'd wrapper of the same bound method
  (armed only where the speed layer compiled the block; restored before every
  disable_cache so the uncached path stays pristine). Balanced MagCache at 50
  steps: 1.48x to 2.17x, identical skip counts, bit-identical uncached rerun
  after enable/disable cycles.
- transformer_cache_quality knob (quality|balanced|fast; API + UI + bench)
  mapping to (threshold, max_skip_steps, retention_ratio). Auto resolves to the
  near-lossless quality preset (0.06, 2, 0.3; 1.63-1.64x at pairwise LPIPS
  0.05-0.09) for the HunyuanVideo-1.5 families and to balanced (the pre-knob
  values, byte-identical behaviour) everywhere else.
- TE auto-quant resolves dense for HunyuanVideo-1.5: TE fp8_dynamic alone moves
  the clip to LPIPS 0.236 vs bit-exact for zero speed win (the quantised encoder
  perturbs the conditioning and the trajectory amplifies it chaotically); VAE
  fp8 stays in auto (0.053, at the compile floor). Explicit schemes honored.
- dual-GPU CFG branch parallelism (new diffusion_cfg_parallel.py): transformer
  proxy + DiT replica on the most-free second CUDA device + worker thread,
  branch-routed off the pipeline's own cache_context names. Auto engages only
  where measured bit-identical (eager tier: max abs diff 0.0, 1.66x); the
  compiled stack is explicit cfg_parallel=on (1.52x over the sequential
  default; per-device compiled artifacts differ by 1 bf16 ulp/step, documented
  in the resolved record). Fail-soft gates: family allowlist, guider CFG,
  pipeline kind, dense DiT, no offload, free-VRAM check; single-GPU loads are
  untouched and the memory plan stays single-device.
- video API: the transformer_cache literal now accepts auto/magcache (an
  explicit magcache request was rejected at the pydantic layer); the mxfp8
  family deny records the round-2 measurement (block-32 MX scaling fixes the
  zero-row collapse, no black frames, but is latency-neutral at LPIPS 0.37:
  fails both ship bars).

Measured on B200 via the production lever path (video_speedmem_bench.py, which
gained a --cache-quality lever and companion-quant isolation configs). Tests:
441 passing across the video inference suite (32 new for cfg-parallel, 20 for
presets/arming, 3 for the inductor flag, 2 for TE auto-dense); ruff clean.

studio/backend/tests/test_diffusion_cache.py

@@ -609,3 +609,269 @@ def test_toggle_magcache_disengages_below_bar(monkeypatch):
         _pipe(t), steps = 8, mode = TC_MAGCACHE, family = "hunyuanvideo-1.5-720p"
     )
     assert mode is None and t.disables == 1
+
+
+# ── cache quality presets (speed/accuracy knob) ────────────────────────────────────
+from core.inference.diffusion_cache import (  # noqa: E402
+    CACHE_QUALITY_LEVELS,
+    CQ_BALANCED,
+    CQ_FAST,
+    CQ_QUALITY,
+    _FBCACHE_QUALITY_THRESHOLDS,
+    _MAGCACHE_QUALITY_PRESETS,
+    normalize_cache_quality,
+)
+
+
+def test_normalize_cache_quality_unset_and_auto_are_none():
+    for value in (None, "", "  ", "auto", "AUTO"):
+        assert normalize_cache_quality(value) is None
+
+
+def test_normalize_cache_quality_levels_and_casing():
+    assert normalize_cache_quality("quality") == CQ_QUALITY
+    assert normalize_cache_quality("  Balanced ") == CQ_BALANCED
+    assert normalize_cache_quality("FAST") == CQ_FAST
+
+
+def test_normalize_cache_quality_rejects_unknown():
+    with pytest.raises(ValueError):
+        normalize_cache_quality("ultra")
+
+
+def test_quality_preset_tables_cover_every_level():
+    # A missing preset row would KeyError at engage time; the tables and the public
+    # levels tuple must stay in lockstep.
+    assert set(_MAGCACHE_QUALITY_PRESETS) == set(CACHE_QUALITY_LEVELS)
+    assert set(_FBCACHE_QUALITY_THRESHOLDS) == set(CACHE_QUALITY_LEVELS)
+
+
+def test_balanced_presets_match_the_preknob_defaults():
+    # "balanced" IS the pre-knob shipped behaviour: a load without the knob must be
+    # byte-identical to the round-1 defaults.
+    assert _MAGCACHE_QUALITY_PRESETS[CQ_BALANCED] == (
+        DEFAULT_MAGCACHE_THRESHOLD,
+        MAGCACHE_MAX_SKIP_STEPS,
+        MAGCACHE_RETENTION_RATIO,
+    )
+    assert _FBCACHE_QUALITY_THRESHOLDS[CQ_BALANCED] == (
+        DEFAULT_FBCACHE_THRESHOLD,
+        QUANT_FBCACHE_THRESHOLD,
+    )
+
+
+def test_magcache_quality_preset_engages_conservative_params(monkeypatch):
+    # Calibrated on HunyuanVideo-1.5-720p (50 steps): thr 0.06 / cap 2 / retention 0.3 =
+    # 1.11x at pairwise LPIPS 0.057 vs balanced's 1.49x at 0.126.
+    _stub_diffusers_with_magcache(monkeypatch)
+    t = _MixinTransformer()
+    engaged = apply_step_cache(
+        _pipe(t), mode = "magcache", family = "hunyuanvideo-1.5-720p", steps = 50,
+        quality = "quality",
+    )
+    assert engaged == TC_MAGCACHE
+    thr, cap, retention = _MAGCACHE_QUALITY_PRESETS[CQ_QUALITY]
+    assert t.enabled_with.threshold == thr
+    assert t.enabled_with.max_skip_steps == cap
+    assert t.enabled_with.retention_ratio == retention
+
+
+def test_magcache_explicit_threshold_beats_the_preset(monkeypatch):
+    # The preset still supplies the skip cap / retention window, but a pinned threshold
+    # wins (the documented contract of transformer_cache_threshold).
+    _stub_diffusers_with_magcache(monkeypatch)
+    t = _MixinTransformer()
+    apply_step_cache(
+        _pipe(t), mode = "magcache", family = "hunyuanvideo-1.5-720p", steps = 50,
+        quality = "fast", threshold = 0.05,
+    )
+    assert t.enabled_with.threshold == 0.05
+    assert t.enabled_with.max_skip_steps == _MAGCACHE_QUALITY_PRESETS[CQ_FAST][1]
+
+
+def test_fbcache_quality_preset_thresholds(monkeypatch):
+    _stub_diffusers(monkeypatch)
+    dense_thr, quant_thr = _FBCACHE_QUALITY_THRESHOLDS[CQ_QUALITY]
+    t = _MixinTransformer()
+    apply_step_cache(_pipe(t), mode = "fbcache", quality = "quality")
+    assert t.enabled_with.threshold == dense_thr
+    t2 = _MixinTransformer()
+    apply_step_cache(_pipe(t2), mode = "fbcache", quality = "quality", quant_active = True)
+    assert t2.enabled_with.threshold == quant_thr
+
+
+def test_apply_step_cache_rejects_bad_quality(monkeypatch):
+    _stub_diffusers(monkeypatch)
+    with pytest.raises(ValueError):
+        apply_step_cache(_pipe(_MixinTransformer()), mode = "fbcache", quality = "bogus")
+
+
+def test_toggle_threads_quality_through(monkeypatch):
+    _stub_diffusers_with_magcache(monkeypatch)
+    t = _ToggleTransformer()
+    maybe_toggle_step_cache(
+        _pipe(t), steps = 30, mode = TC_MAGCACHE, family = "hunyuanvideo-1.5-720p",
+        quality = "quality",
+    )
+    assert t.enabled_with.threshold == _MAGCACHE_QUALITY_PRESETS[CQ_QUALITY][0]
+    assert t.enabled_with.max_skip_steps == _MAGCACHE_QUALITY_PRESETS[CQ_QUALITY][1]
+
+
+# ── compiled cache-hook inners (regional compile x step cache composition) ──────────
+import functools  # noqa: E402
+
+from core.inference.diffusion_cache import (  # noqa: E402
+    _compile_hooked_block_inners,
+    _restore_hooked_block_inners,
+    auto_cache_quality,
+)
+
+
+def test_auto_cache_quality_per_family():
+    assert auto_cache_quality("hunyuanvideo-1.5") == CQ_QUALITY
+    assert auto_cache_quality("HunyuanVideo-1.5-720p") == CQ_QUALITY
+    for other in (None, "", "flux", "wan2.2-ti2v-5b", "ltx-2"):
+        assert auto_cache_quality(other) == CQ_BALANCED
+
+
+class _BoundInner:
+    """Provides a plain bound method for fn_ref.original_forward (__self__ present)."""
+
+    def forward(self, *args, **kwargs):
+        return "eager"
+
+
+def _hooked_block(*, compiled = True, hook_name = "mag_cache_block_hook", bound = True):
+    inner = _BoundInner()
+    orig = inner.forward if bound else functools.partial(_BoundInner.forward, inner)
+    hook = types.SimpleNamespace(fn_ref = types.SimpleNamespace(original_forward = orig))
+    block = types.SimpleNamespace(
+        _diffusers_hook = types.SimpleNamespace(hooks = {hook_name: hook}),
+        _compiled_call_impl = object() if compiled else None,
+    )
+    return block, hook, orig
+
+
+def _fake_dit(blocks):
+    return types.SimpleNamespace(modules = lambda: [types.SimpleNamespace()] + blocks)
+
+
+def _stub_torch_compile(monkeypatch):
+    compiled_calls = []
+
+    def _compile(fn, **kwargs):
+        compiled_calls.append((fn, kwargs))
+        wrapper = lambda *a, **k: fn(*a, **k)  # noqa: E731
+        wrapper._unsloth_test_compiled_of = fn
+        return wrapper
+
+    torch = types.ModuleType("torch")
+    torch.compile = _compile
+    monkeypatch.setitem(sys.modules, "torch", torch)
+    return compiled_calls
+
+
+def test_arming_swaps_inner_for_compiled_wrapper(monkeypatch):
+    calls = _stub_torch_compile(monkeypatch)
+    block, hook, orig = _hooked_block()
+    assert _compile_hooked_block_inners(_fake_dit([block])) == 1
+    assert hook.fn_ref.original_forward is not orig
+    assert hook.fn_ref.original_forward._unsloth_test_compiled_of is orig
+    assert hook._unsloth_orig_inner is orig
+    # The inner compile must match the cache-active tier: graph-breakable + dynamic.
+    assert calls[0][1] == {"fullgraph": False, "dynamic": True}
+
+
+def test_arming_is_idempotent(monkeypatch):
+    _stub_torch_compile(monkeypatch)
+    block, hook, _ = _hooked_block()
+    dit = _fake_dit([block])
+    assert _compile_hooked_block_inners(dit) == 1
+    once = hook.fn_ref.original_forward
+    assert _compile_hooked_block_inners(dit) == 0  # marker short-circuits
+    assert hook.fn_ref.original_forward is once
+
+
+def test_arming_skips_uncompiled_blocks(monkeypatch):
+    # An eager-tier load has no _compiled_call_impl: the hook must stay untouched
+    # (compiling the inner would ADD compile where the user chose eager).
+    _stub_torch_compile(monkeypatch)
+    block, hook, orig = _hooked_block(compiled = False)
+    assert _compile_hooked_block_inners(_fake_dit([block])) == 0
+    assert hook.fn_ref.original_forward is orig
+
+
+def test_arming_skips_partial_captured_inner(monkeypatch):
+    # A stacked hook chain (e.g. group offload) captures a functools.partial, not the
+    # plain bound method; arming would compile the wrong layer of the chain.
+    _stub_torch_compile(monkeypatch)
+    block, hook, orig = _hooked_block(bound = False)
+    assert _compile_hooked_block_inners(_fake_dit([block])) == 0
+    assert hook.fn_ref.original_forward is orig
+
+
+def test_arming_covers_every_cache_hook_family(monkeypatch):
+    _stub_torch_compile(monkeypatch)
+    names = (
+        "mag_cache_leader_block_hook",
+        "mag_cache_block_hook",
+        "fbc_leader_block_hook",
+        "fbc_block_hook",
+    )
+    blocks = [_hooked_block(hook_name = n)[0] for n in names]
+    assert _compile_hooked_block_inners(_fake_dit(blocks)) == len(names)
+
+
+def test_restore_puts_the_exact_original_back(monkeypatch):
+    _stub_torch_compile(monkeypatch)
+    block, hook, orig = _hooked_block()
+    dit = _fake_dit([block])
+    _compile_hooked_block_inners(dit)
+    _restore_hooked_block_inners(dit)
+    assert hook.fn_ref.original_forward is orig
+    assert hook._unsloth_orig_inner is None
+
+
+def test_restore_tolerates_fakes_without_modules():
+    _restore_hooked_block_inners(_MixinTransformer())  # no .modules(): no-op
+
+
+def test_disengage_restores_inners_before_disable(monkeypatch):
+    # remove_hook splices fn_ref.original_forward back into module.forward, so the
+    # compiled wrapper must be swapped out BEFORE disable_cache runs.
+    from core.inference import diffusion_cache as dc_mod
+
+    order = []
+
+    class _T(_MixinTransformer):
+        def disable_cache(self):
+            order.append("disable")
+
+        def modules(self):
+            order.append("restore-walk")
+            return []
+
+    t = _T()
+    t._unsloth_step_cache = "magcache@0.12#s50"
+    assert dc_mod._disengage_step_cache(t, reason = "test") is True
+    assert order == ["restore-walk", "disable"]
+
+
+def test_apply_step_cache_arms_compiled_blocks_on_toggle(monkeypatch):
+    # The generation-time toggle engages the cache AFTER the load already compiled the
+    # blocks; apply_step_cache must arm the fresh hooks itself.
+    _stub_diffusers_with_magcache(monkeypatch)
+    _stub_torch_compile(monkeypatch)
+    block, hook, orig = _hooked_block()
+
+    class _T(_MixinTransformer):
+        def modules(self):
+            return [block]
+
+    t = _T()
+    engaged = apply_step_cache(
+        _pipe(t), mode = "magcache", family = "hunyuanvideo-1.5-720p", steps = 50
+    )
+    assert engaged == TC_MAGCACHE
+    assert hook.fn_ref.original_forward is not orig
+    assert hook._unsloth_orig_inner is orig

studio/backend/tests/test_diffusion_cfg_parallel.py

@@ -0,0 +1,446 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""Hermetic CPU tests for dual-GPU CFG branch parallelism (``diffusion_cfg_parallel``).
+
+torch is stubbed via ``sys.modules`` (the module imports it lazily), the DiT modules are
+fakes that record calls, and the guider is a plain namespace -- so the gating matrix, the
+proxy's routing/fan-out semantics, the per-generation dispatch policy, and teardown are
+all exercised without a GPU, a replica download, or diffusers."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import types
+
+import pytest
+
+from core.inference.diffusion_cfg_parallel import (
+    CFG_PARALLEL_AUTO,
+    CFG_PARALLEL_OFF,
+    CFG_PARALLEL_ON,
+    CFGParallelProxy,
+    _pick_secondary_device,
+    maybe_enable_cfg_parallel,
+    normalize_cfg_parallel,
+    teardown_cfg_parallel,
+)
+
+
+# ── normalisation ─────────────────────────────────────────────────────────────────
+def test_normalize_unset_and_auto():
+    for value in (None, "", "  ", "auto", "AUTO"):
+        assert normalize_cfg_parallel(value) == CFG_PARALLEL_AUTO
+
+
+def test_normalize_modes_and_casing():
+    assert normalize_cfg_parallel("off") == CFG_PARALLEL_OFF
+    assert normalize_cfg_parallel("none") == CFG_PARALLEL_OFF
+    assert normalize_cfg_parallel(" ON ") == CFG_PARALLEL_ON
+
+
+def test_normalize_rejects_unknown():
+    with pytest.raises(ValueError):
+        normalize_cfg_parallel("both")
+
+
+# ── fakes ─────────────────────────────────────────────────────────────────────────
+class _FakeDevice:
+    def __init__(self, type_ = "cuda", index = 0):
+        self.type = type_
+        self.index = index
+
+
+class _FakeTensor:
+    """Just enough tensor for the proxy's _move / guider resolve paths."""
+
+    def __init__(self, device, tag = "t", nbytes = 8):
+        self.device = device
+        self.tag = tag
+        self._nbytes = nbytes
+
+    def numel(self):
+        return self._nbytes
+
+    def element_size(self):
+        return 1
+
+    def to(self, device, non_blocking = False):
+        return _FakeTensor(device, tag = self.tag, nbytes = self._nbytes)
+
+
+class _FakeDiT:
+    def __init__(self, device_index = 0, fail_enable = False):
+        self._device = _FakeDevice(index = device_index)
+        self.fail_enable = fail_enable
+        self.enabled_with = None
+        self.disables = 0
+        self.resets = 0
+        self.contexts: list = []
+        self.calls: list = []
+        self._mods = [self, types.SimpleNamespace(name = f"block{device_index}")]
+
+    def parameters(self):
+        return iter([types.SimpleNamespace(
+            numel = lambda: 100, element_size = lambda: 2, device = self._device
+        )])
+
+    def modules(self):
+        return list(self._mods)
+
+    def enable_cache(self, config):
+        if self.fail_enable:
+            raise RuntimeError("replica enable boom")
+        self.enabled_with = config
+
+    def disable_cache(self):
+        self.disables += 1
+
+    def _reset_stateful_cache(self):
+        self.resets += 1
+
+    @contextlib.contextmanager
+    def cache_context(self, name):
+        self.contexts.append(name)
+        yield
+
+    def __call__(self, *args, **kwargs):
+        self.calls.append((args, kwargs))
+        return (_FakeTensor(self._device, tag = "pred"),)
+
+
+def _stub_torch(monkeypatch, *, device_count = 2, free = None):
+    torch = types.ModuleType("torch")
+    torch.Tensor = _FakeTensor
+    free = free if free is not None else {}
+
+    def _mem_get_info(idx):
+        return free.get(idx, (64 << 30, 80 << 30))
+
+    torch.cuda = types.SimpleNamespace(
+        is_available = lambda: device_count > 0,
+        device_count = lambda: device_count,
+        mem_get_info = _mem_get_info,
+        empty_cache = lambda: None,
+    )
+    torch.inference_mode = contextlib.nullcontext
+    monkeypatch.setitem(sys.modules, "torch", torch)
+    return torch
+
+
+def _make_proxy(monkeypatch, *, compiled = False, explicit_on = False, fail_enable = False):
+    _stub_torch(monkeypatch)
+    primary = _FakeDiT(device_index = 0)
+    replica = _FakeDiT(device_index = 1, fail_enable = fail_enable)
+    guider = types.SimpleNamespace(forward = lambda *a, **k: ("combined", a, k), num_conditions = 2)
+    proxy = CFGParallelProxy(
+        primary, replica, guider, compiled = compiled, explicit_on = explicit_on
+    )
+    return proxy, primary, replica, guider
+
+
+# ── gating matrix ─────────────────────────────────────────────────────────────────
+class _CtxPipe:
+    """A pipeline whose __call__ opens transformer.cache_context (the branch signal)."""
+
+    def __init__(self, transformer):
+        self.transformer = transformer
+        self.guider = types.SimpleNamespace(forward = lambda *a, **k: None)
+
+    def __call__(self):
+        with self.transformer.cache_context("pred_cond"):
+            pass
+
+
+def _fam(name = "hunyuanvideo-1.5-720p", guider = True):
+    return types.SimpleNamespace(name = name, guidance_via_guider = guider)
+
+
+def _gate(monkeypatch, pipe, fam, **overrides):
+    # compiled=False = the eager tier, the only stack auto parallelises (bit-identity).
+    kwargs = dict(
+        requested = None,
+        kind = "pipeline",
+        transformer_source = "repo",
+        hf_token = None,
+        dtype = "bf16",
+        quant_engaged = None,
+        offload_active = False,
+        compiled = False,
+        attention_backend = "_native_cudnn",
+        speed_active = True,
+    )
+    kwargs.update(overrides)
+    return maybe_enable_cfg_parallel(pipe, fam, **kwargs)
+
+
+def test_gate_disabled_by_request(monkeypatch):
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(), requested = "off")
+    assert proxy is None and reason == "disabled by request"
+
+
+def test_gate_family_allowlist(monkeypatch):
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(name = "wan2.2-ti2v-5b"))
+    assert proxy is None and "allowlist" in reason
+
+
+def test_gate_auto_refuses_compiled_stack(monkeypatch):
+    # The per-device inductor artifacts drift ~1 ulp/step; auto is bit-identical-only,
+    # so a compiled load never engages (and never spends the replica VRAM).
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(), compiled = True)
+    assert proxy is None and "cfg_parallel=on" in reason
+
+
+def test_gate_requires_guider_pipeline(monkeypatch):
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(guider = False))
+    assert proxy is None and "guider" in reason
+
+
+def test_gate_requires_pipeline_kind(monkeypatch):
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(), kind = "gguf")
+    assert proxy is None and "second transformer source" in reason
+
+
+def test_gate_skips_quantized_dit(monkeypatch):
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(), quant_engaged = "int8")
+    assert proxy is None and "int8" in reason
+
+
+def test_gate_skips_offload(monkeypatch):
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam(), offload_active = True)
+    assert proxy is None and "offload" in reason
+
+
+def test_gate_needs_two_gpus(monkeypatch):
+    _stub_torch(monkeypatch, device_count = 1)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam())
+    assert proxy is None and "2+ CUDA devices" in reason
+
+
+def test_gate_needs_secondary_vram(monkeypatch):
+    # 1 GiB free on the only other device < weights + headroom -> stay single-device.
+    _stub_torch(monkeypatch, free = {1: (1 << 30, 80 << 30)})
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam())
+    assert proxy is None and "free" in reason and "needs" in reason
+
+
+def test_gate_replica_load_failure_is_soft(monkeypatch):
+    # Every gate passes; the replica from_pretrained blows up (download / VRAM race):
+    # the load must proceed single-device, never raise.
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(monkeypatch, _CtxPipe(_FakeDiT()), _fam())
+    assert proxy is None and reason == "replica load failed"
+
+
+def test_explicit_on_skips_family_allowlist(monkeypatch):
+    # "on" bypasses the measured-family list; it still fails soft at the replica load
+    # (the fake DiT class has no from_pretrained), proving the gate ORDER.
+    _stub_torch(monkeypatch)
+    proxy, reason = _gate(
+        monkeypatch, _CtxPipe(_FakeDiT()), _fam(name = "some-future-family"), requested = "on"
+    )
+    assert proxy is None and reason == "replica load failed"
+
+
+def test_pick_secondary_prefers_most_free(monkeypatch):
+    _stub_torch(
+        monkeypatch,
+        device_count = 3,
+        free = {1: (10 << 30, 80 << 30), 2: (40 << 30, 80 << 30)},
+    )
+    idx, free = _pick_secondary_device(0)
+    assert idx == 2 and free == 40 << 30
+
+
+# ── proxy semantics ───────────────────────────────────────────────────────────────
+def test_proxy_delegates_reads_to_primary(monkeypatch):
+    proxy, primary, _, _ = _make_proxy(monkeypatch)
+    primary.some_flag = "x"
+    assert proxy.some_flag == "x"
+    proxy.shutdown()
+
+
+def test_proxy_modules_covers_both(monkeypatch):
+    # The cache-hook inner arming walks transformer.modules(); missing the replica's
+    # blocks would leave its computed steps eager and erase the parallel win.
+    proxy, primary, replica, _ = _make_proxy(monkeypatch)
+    mods = proxy.modules()
+    for m in primary.modules() + replica.modules():
+        assert any(m is x for x in mods)
+    proxy.shutdown()
+
+
+def test_enable_cache_fans_out(monkeypatch):
+    proxy, primary, replica, _ = _make_proxy(monkeypatch)
+    proxy.enable_cache({"threshold": 0.12})
+    assert primary.enabled_with == {"threshold": 0.12}
+    assert replica.enabled_with == {"threshold": 0.12}
+    proxy.disable_cache()
+    assert primary.disables == 1 and replica.disables == 1
+    proxy.shutdown()
+
+
+def test_replica_enable_failure_reraises_and_breaks(monkeypatch):
+    # A half-cached pair would skip differently per branch; the raise lets the caller's
+    # best-effort path disable both, and _broken pins the sequential passthrough.
+    proxy, primary, _, _ = _make_proxy(monkeypatch, fail_enable = True)
+    with pytest.raises(RuntimeError):
+        proxy.enable_cache({})
+    assert primary.enabled_with == {}  # primary was hooked before the replica failed
+    plan = proxy.plan_generation(
+        cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33
+    )
+    assert plan["enabled"] is False
+    proxy.shutdown()
+
+
+def test_reset_stateful_cache_fans_out(monkeypatch):
+    proxy, primary, replica, _ = _make_proxy(monkeypatch)
+    proxy._reset_stateful_cache()
+    assert primary.resets == 1 and replica.resets == 1
+    proxy.shutdown()
+
+
+def test_cache_context_enters_both_only_when_parallel_inline(monkeypatch):
+    proxy, primary, replica, _ = _make_proxy(monkeypatch)
+    proxy.enabled, proxy.dispatch = True, "inline"
+    with proxy.cache_context("pred_cond"):
+        pass
+    assert primary.contexts == ["pred_cond"] and replica.contexts == ["pred_cond"]
+    proxy.enabled = False
+    with proxy.cache_context("pred_uncond"):
+        pass
+    assert replica.contexts == ["pred_cond"]  # sequential: primary only
+    proxy.shutdown()
+
+
+def test_routing_pred_cond_to_replica_inline(monkeypatch):
+    proxy, primary, replica, _ = _make_proxy(monkeypatch)
+    proxy.enabled, proxy.dispatch = True, "inline"
+    with proxy.cache_context("pred_cond"):
+        proxy("latents")
+    with proxy.cache_context("pred_uncond"):
+        proxy("latents")
+    assert len(replica.calls) == 1 and len(primary.calls) == 1
+    proxy.shutdown()
+
+
+def test_routing_passthrough_when_disabled(monkeypatch):
+    proxy, primary, replica, _ = _make_proxy(monkeypatch)
+    proxy.enabled = False
+    with proxy.cache_context("pred_cond"):
+        proxy("latents")
+    assert len(primary.calls) == 1 and len(replica.calls) == 0
+    proxy.shutdown()
+
+
+def test_thread_dispatch_resolves_through_guider(monkeypatch):
+    proxy, primary, replica, guider = _make_proxy(monkeypatch)
+    proxy.enabled, proxy.dispatch = True, "thread"
+    with proxy.cache_context("pred_cond"):
+        out = proxy("latents")
+    # The worker resolves the pending prediction; the patched guider forward joins it
+    # and hands a primary-device tensor to the original combine.
+    combined, args, _ = guider.forward(out[0], _FakeTensor(_FakeDevice(index = 0)))
+    assert combined == "combined"
+    assert args[0].device.index == 0  # replica output copied to the primary device
+    assert len(replica.calls) == 1
+    proxy.shutdown()
+
+
+# ── per-generation dispatch policy ──────────────────────────────────────────────────
+def test_plan_parallel_on_eager_settles_to_thread(monkeypatch):
+    proxy, _, _, _ = _make_proxy(monkeypatch, compiled = False)
+    plan = proxy.plan_generation(
+        cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33
+    )
+    assert plan["enabled"] is True and plan["dispatch"] == "inline"  # first run: compile-safe
+    proxy.note_generation_done()
+    plan = proxy.plan_generation(
+        cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33
+    )
+    assert plan["dispatch"] == "thread"  # settled key: full overlap
+    proxy.shutdown()
+
+
+def test_plan_sequential_for_compiled_stack_even_with_cache(monkeypatch):
+    # Compiled per-device artifacts drift regardless of the cache state (its computed
+    # steps run the per-device compiled inners): auto stays sequential, an explicit
+    # "on" accepts the fp-noise divergence.
+    proxy, _, _, _ = _make_proxy(monkeypatch, compiled = True)
+    for cache_engaged in (True, False):
+        plan = proxy.plan_generation(
+            cache_engaged = cache_engaged, steps = 30, width = 1280, height = 720, frames = 33
+        )
+        assert plan["enabled"] is False and plan["lossless"] is False
+    proxy.shutdown()
+    proxy_on, _, _, _ = _make_proxy(monkeypatch, compiled = True, explicit_on = True)
+    plan = proxy_on.plan_generation(
+        cache_engaged = False, steps = 10, width = 1280, height = 720, frames = 33
+    )
+    assert plan["enabled"] is True and plan["lossless"] is False
+    proxy_on.shutdown()
+
+
+def test_plan_parallel_for_eager_stack(monkeypatch):
+    proxy, _, _, _ = _make_proxy(monkeypatch, compiled = False)
+    plan = proxy.plan_generation(
+        cache_engaged = False, steps = 10, width = 1280, height = 720, frames = 33
+    )
+    assert plan["enabled"] is True and plan["lossless"] is True
+    proxy.shutdown()
+
+
+def test_plan_requires_cfg_conditions(monkeypatch):
+    # guidance ~1 collapses the guider to one condition: nothing to overlap.
+    proxy, _, _, guider = _make_proxy(monkeypatch)
+    guider.num_conditions = 1
+    plan = proxy.plan_generation(
+        cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33
+    )
+    assert plan["enabled"] is False
+    proxy.shutdown()
+
+
+def test_shape_change_forces_inline_once(monkeypatch):
+    proxy, _, _, _ = _make_proxy(monkeypatch)
+    proxy.plan_generation(cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33)
+    proxy.note_generation_done()
+    plan = proxy.plan_generation(
+        cache_engaged = True, steps = 30, width = 960, height = 544, frames = 33
+    )
+    assert plan["dispatch"] == "inline"  # new shape may recompile: serialize
+    proxy.shutdown()
+
+
+def test_cancelled_generation_stays_inline(monkeypatch):
+    proxy, _, _, _ = _make_proxy(monkeypatch)
+    proxy.plan_generation(cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33)
+    # No note_generation_done (cancel/failure): the same key must stay inline.
+    plan = proxy.plan_generation(
+        cache_engaged = True, steps = 30, width = 1280, height = 720, frames = 33
+    )
+    assert plan["dispatch"] == "inline"
+    proxy.shutdown()
+
+
+# ── teardown ──────────────────────────────────────────────────────────────────────
+def test_teardown_restores_pipe_and_guider(monkeypatch):
+    proxy, primary, _, guider = _make_proxy(monkeypatch)
+    orig_forward = proxy._orig_guider_forward
+    pipe = types.SimpleNamespace(transformer = proxy)
+    teardown_cfg_parallel(pipe, proxy)
+    assert pipe.transformer is primary
+    assert guider.forward is orig_forward
+    assert proxy._replica is None
+
+
+def test_teardown_tolerates_foreign_object():
+    teardown_cfg_parallel(types.SimpleNamespace(transformer = None), object())

studio/backend/tests/test_diffusion_precision.py

@@ -577,3 +577,27 @@ def test_quantize_text_encoders_auto_resolves_and_applies(monkeypatch):
     mode = quantize_text_encoders(pipe, _target(), mode = "auto", family = "qwen-image")
     assert mode == TE_QUANT_FP8_DYNAMIC
     assert calls == [te]
+
+
+def test_select_te_auto_resolves_dense_for_hunyuanvideo15(monkeypatch):
+    # HunyuanVideo-1.5 (both repacks): TE quant perturbs the conditioning and the video
+    # trajectory amplifies it chaotically (measured LPIPS 0.236 vs bit-exact from TE
+    # fp8_dynamic ALONE, vs 0.052 for the rest of the stack) at zero speed win, so the
+    # AUTO default keeps the encoder dense on ANY hardware.
+    _stub_tq_select(monkeypatch, cc = (10, 0), consumer = False)
+    _allow_te(monkeypatch, {TE_QUANT_FP8_DYNAMIC, TE_QUANT_INT8, TE_QUANT_FP8})
+    assert select_te_quant_scheme(_target(), "auto", family = "hunyuanvideo-1.5") is None
+    assert select_te_quant_scheme(_target(), "auto", family = "HunyuanVideo-1.5-720p") is None
+    # Other families keep the normal ladder on the same stubbed hardware.
+    assert select_te_quant_scheme(_target(), "auto", family = "qwen-image") == TE_QUANT_FP8_DYNAMIC
+
+
+def test_select_te_explicit_scheme_still_honored_for_hunyuanvideo15(monkeypatch):
+    # The auto-dense table steers only the DEFAULT; an explicit request stays verbatim
+    # (select returns it as-is; quantize_text_encoders re-gates hardware support).
+    _stub_tq_select(monkeypatch, cc = (10, 0), consumer = False)
+    _allow_te(monkeypatch, {TE_QUANT_FP8_DYNAMIC})
+    assert (
+        select_te_quant_scheme(_target(), "fp8_dynamic", family = "hunyuanvideo-1.5-720p")
+        == TE_QUANT_FP8_DYNAMIC
+    )

studio/backend/tests/test_diffusion_speed.py

@@ -531,3 +531,81 @@ def test_fp16_accum_allowed_on_fp16_dtype_under_max(monkeypatch):
     )
     assert applied["fp16_accum"] is True
     assert torch.backends.cuda.matmul.allow_fp16_accumulation is True
+
+
+# ── inductor precision-cast emulation (compile-vs-eager numeric parity) ─────────
+
+
+def _stub_inductor_config(monkeypatch, torch, *, emulate = False):
+    """Attach a fake ``_inductor.config`` to the stubbed torch module (diffusion_speed
+    resolves it as attributes off the imported torch, never via sys.modules -- so the
+    real torch._inductor lingering in sys.modules cannot leak into stubbed tests)."""
+    cfg = types.SimpleNamespace(emulate_precision_casts = emulate)
+    torch._inductor = types.SimpleNamespace(config = cfg)
+    return cfg
+
+
+def test_regional_compile_enables_emulate_precision_casts(monkeypatch):
+    # Inductor's fused pointwise kernels keep intermediates in fp32 where eager rounds
+    # to bf16 between ops; over a multi-step denoise that compounds to a visible drift
+    # (LPIPS 0.221 vs bit-exact on HunyuanVideo-1.5-720p). emulate_precision_casts
+    # restores eager's rounding at zero measured speed cost (LPIPS 0.052), so the
+    # regional compile path must switch it on.
+    torch = _stub_torch(monkeypatch)
+    _stub_gguf_accel(monkeypatch)
+    cfg = _stub_inductor_config(monkeypatch, torch, emulate = False)
+    pipe = _Pipe(with_compile = True)
+    applied = apply_speed_optims(
+        pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT
+    )
+    assert applied["compiled"] is True
+    assert cfg.emulate_precision_casts is True
+
+
+def test_snapshot_restores_emulate_precision_casts(monkeypatch):
+    # The flag is process-global, so the unload path must restore the pre-load value
+    # exactly like the TF32 / cudnn.benchmark globals.
+    torch = _stub_torch(monkeypatch)
+    cfg = _stub_inductor_config(monkeypatch, torch, emulate = False)
+    snap = snapshot_backend_flags()
+    assert snap["inductor_emulate_precision_casts"] is False
+    cfg.emulate_precision_casts = True
+    restore_backend_flags(snap)
+    assert cfg.emulate_precision_casts is False
+
+
+def test_missing_inductor_config_is_tolerated(monkeypatch):
+    # A build without torch._inductor (or with the flag renamed) must neither break the
+    # snapshot nor the compile path.
+    _stub_torch(monkeypatch)  # the stub torch has no _inductor attribute
+    _stub_gguf_accel(monkeypatch)
+    snap = snapshot_backend_flags()
+    assert "inductor_emulate_precision_casts" not in snap
+    pipe = _Pipe(with_compile = True)
+    applied = apply_speed_optims(
+        pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT
+    )
+    assert applied["compiled"] is True
+
+
+def test_regional_compile_arms_cache_hook_inners(monkeypatch):
+    # The production load order engages the step cache BEFORE compile, so the regional
+    # compile pass must re-arm the already-installed cache hooks with compiled inner
+    # forwards (otherwise every computed step runs eager under the hook's
+    # torch.compiler.disable; measured 1.69 vs 1.09 s/step on HunyuanVideo-1.5-720p).
+    _stub_torch(monkeypatch)
+    _stub_gguf_accel(monkeypatch)
+    from core.inference import diffusion_cache as dc_mod
+
+    armed = []
+    monkeypatch.setattr(
+        dc_mod,
+        "_compile_hooked_block_inners",
+        lambda transformer, logger = None: armed.append(transformer) or 1,
+    )
+    pipe = _Pipe(with_compile = True)
+    applied = apply_speed_optims(
+        pipe, _target(), is_gguf = False, family = _family(), speed_mode = SPEED_DEFAULT
+    )
+    assert applied["compiled"] is True
+    assert armed == [pipe.transformer]