Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

80.4 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0

"""ComfyUI quantized single-file DiTs: stock loader drops scales and renders noise; others refused."""

from __future__ import annotations

import json
import os
import struct
from dataclasses import dataclass, field
from typing import Any, Optional

from .diffusion_comfy_block import BLOCK_SIZES, MXFP8, NVFP4, tiled_scale_numel
from .diffusion_fp8_dequant import chunk_rows, dequant_rows, fused_dequant_enabled
from .diffusion_init_buffers import is_fp32_init_table
from .diffusion_single_file_converters import host_ram_budget_scope
from .diffusion_small_host import FP8_STORAGE_HOST_RESERVE_MIB

COMFY_QUANT_SUFFIX = ".comfy_quant"
QUANT_METADATA_KEY = "_quantization_metadata"
LEGACY_SCALED_FP8_KEY = "scaled_fp8"
COMFY_INT8_ENV = "UNSLOTH_DIFFUSION_COMFY_INT8"
COMFY_FP8_ENV = "UNSLOTH_DIFFUSION_COMFY_FP8"
# Store fp8 layers no fp8 GEMM takes as fp8, widened per layer (ComfyUI manual_cast). Unset: only when widening
# would offload or crowd host RAM (per-layer widen costs eager steps); ``1``: always; ``0``: never.
FP8_STORAGE_ENV = "UNSLOTH_DIFFUSION_FP8_STORAGE"
# Header metadata our own converter writes (base model, scheme); ComfyUI ignores it.
CONVERSION_RECORD_KEY = "unsloth_comfy_conversion"

INT8_TENSORWISE = "int8_tensorwise"
# Unpacked, a ConvRot W4A4 layer is an int8_tensorwise ConvRot layer (run with int8 activations, not int4).
CONVROT_W4A4 = "convrot_w4a4"
FP8_E4M3 = "float8_e4m3fn"
FP8_FORMATS = {"float8_e4m3fn": "F8_E4M3", "float8_e5m2": "F8_E5M2"}

# Every companion tensor a ComfyUI quantized layer can carry. A suffix outside what a supported format
# consumes means a format this loader does not implement, so it is refused rather than dropped.
_SCALE_SUFFIXES = (
    ".weight_scale",
    ".weight_scale_2",
    ".input_scale",
    ".pre_quant_scale",
    ".weight_s_rel",
    ".weight_s_channel",
    ".weight_codebook",
    ".scale_weight",
    ".scale_input",
)
_CONSUMED = {
    INT8_TENSORWISE: (".weight_scale",),
    "float8_e4m3fn": (".weight_scale", ".input_scale"),
    "float8_e5m2": (".weight_scale", ".input_scale"),
    NVFP4: (".weight_scale", ".weight_scale_2", ".input_scale", ".pre_quant_scale"),
    MXFP8: (".weight_scale", ".input_scale"),
}
_LEGACY_RENAME = {".scale_weight": ".weight_scale", ".scale_input": ".input_scale"}
# Container prefixes a declaration may omit while its weight carries one.
_DECLARATION_PREFIXES = ("model.diffusion_model.", "diffusion_model.")

# Row tag: key index * 2**24 + row, exact in float64 for any real checkpoint.
_TAG = float(1 << 24)
# Tag width of the fast pass: enough columns to see a splice (first / middle / last differ), none of the real width.
_NARROW_TAG_COLUMNS = 4
_MAX_HEADER_BYTES = 256 * 1024 * 1024


@dataclass(frozen = True)
class ComfyQuantLayer:
    """One quantized layer of a ComfyUI checkpoint, named as in the file (no ``.weight``)."""

    name: str
    format: str
    convrot: bool = False
    group: int = 0
    # ``.weight`` holds packed int4 (K / 2 columns), unpacked on load.
    packed_int4: bool = False


@dataclass
class ComfyQuantScan:
    """What the header declares; ``problems`` lists everything this module will not load."""

    layers: dict = field(default_factory = dict)
    legacy_scaled_fp8: bool = False
    problems: list = field(default_factory = list)

    def counts(self) -> dict:
        out: dict = {}
        for layer in self.layers.values():
            key = layer.format + ("+convrot" if layer.convrot else "")
            out[key] = out.get(key, 0) + 1
        return out


def _read_header(path: str) -> tuple[dict, int]:
    with open(path, "rb") as handle:
        raw = handle.read(8)
        if len(raw) != 8:
            raise ValueError(f"{os.path.basename(path)} is not a safetensors file")
        size = struct.unpack("<Q", raw)[0]
        if size <= 0 or size > _MAX_HEADER_BYTES:
            raise ValueError(f"{os.path.basename(path)} has an implausible safetensors header")
        return json.loads(handle.read(size)), 8 + size


# A comfy_quant declaration is a few hundred bytes of JSON; a file can claim any span, so never read a large one.
_MAX_COMFY_QUANT_BYTES = 1 << 20


def _read_json_tensor(path: str, entry: dict, base: int) -> Any:
    start, end = entry["data_offsets"]
    if int(start) < 0 or not 0 <= int(end) - int(start) <= _MAX_COMFY_QUANT_BYTES:
        raise ValueError(f"comfy_quant declaration spans {int(end) - int(start)} bytes")
    with open(path, "rb") as handle:
        handle.seek(base + int(start))
        return json.loads(handle.read(int(end) - int(start)).decode("utf-8"))


def _w4a4_group(raw: Any) -> int:
    params = raw.get("params") if isinstance(raw.get("params"), dict) else {}
    group = raw.get("convrot_groupsize", params.get("convrot_groupsize", 256))
    return int(group) if isinstance(group, (int, float)) else 0


def _w4a4_layer_problem(
    name: str, raw: Any, weight: Optional[dict], header: dict, keys: set
) -> Optional[str]:
    params = raw.get("params") if isinstance(raw.get("params"), dict) else {}
    linear = raw.get("linear_dtype", params.get("linear_dtype", "int4"))
    group = _w4a4_group(raw)
    if linear not in ("int4", "int8"):
        return f"{CONVROT_W4A4} with linear_dtype {linear!r}"
    if weight is None:
        return f"{CONVROT_W4A4} declared but there is no {name}.weight"
    shape = weight.get("shape") or ()
    if len(shape) != 2 or weight.get("dtype") != "I8":
        return (
            f"{CONVROT_W4A4} weight {weight.get('dtype')} {list(shape)} (expected packed 2-D int8)"
        )
    if not _is_power_of_four(group):
        return f"ConvRot group {group!r} is not a power of 4"
    if (2 * int(shape[1])) % group:
        return f"in_features {2 * int(shape[1])} not divisible by ConvRot group {group}"
    scale = header.get(name + ".weight_scale")
    if scale is None or _numel(scale) != int(shape[0]):
        return f"{CONVROT_W4A4} needs one weight_scale per row ({shape[0]})"
    leftover = [s for s in _SCALE_SUFFIXES if name + s in keys and s != ".weight_scale"]
    if leftover:
        return f"{CONVROT_W4A4} layer carries {', '.join(leftover)}, which this format does not use"
    return None


def unpack_int4_rows(packed: Any) -> Any:
    """Signed int4 codes, two per byte (low nibble first), as one int8 per code: ``(N, K / 2)`` -> ``(N, K)``."""
    import torch

    from .diffusion_single_file_converters import charge_host_ram

    charge_host_ram(packed.numel() * 10)
    x = packed.to(torch.int16)
    lo = x & 0x0F
    hi = (x >> 4) & 0x0F
    lo = torch.where(lo >= 8, lo - 16, lo)
    hi = torch.where(hi >= 8, hi - 16, hi)
    return torch.stack((lo, hi), dim = -1).reshape(packed.shape[0], -1).to(torch.int8)


def _layer_conf(raw: Any) -> tuple[Optional[str], bool, int]:
    """``(format, convrot, group)`` with ComfyUI's own defaults (``params`` nesting, group 256)."""
    if not isinstance(raw, dict):
        return None, False, 0
    params = raw.get("params") if isinstance(raw.get("params"), dict) else {}
    fmt = raw.get("format")
    convrot = bool(raw.get("convrot", params.get("convrot", False)))
    group = raw.get("convrot_groupsize", params.get("convrot_groupsize", 256)) if convrot else 0
    return (fmt if isinstance(fmt, str) else None), convrot, group


# ROCm-style float8 tags: every loader widens them (fp8 storage keeps only the OCP formats above).
FP8_FNUZ_TAGS = ("F8_E4M3FNUZ", "F8_E5M2FNUZ")


def header_has_fp8_weights(path: Optional[str], *, fnuz_only: bool = False) -> Optional[bool]:
    """Whether a safetensors file stores any fp8 ``.weight`` (plain, scaled or FNUZ; ``fnuz_only``: FNUZ only), or
    None if its header is unreadable."""
    if not path or not os.path.isfile(path):
        return None
    try:
        header, _base = _read_header(str(path))
    except Exception:  # noqa: BLE001
        return None
    tags = FP8_FNUZ_TAGS if fnuz_only else (*FP8_FORMATS.values(), *FP8_FNUZ_TAGS)
    return any(
        key.endswith(".weight") and isinstance(entry, dict) and entry.get("dtype") in tags
        for key, entry in header.items()
    )


def scan_comfy_quant(path: Optional[str]) -> Optional[ComfyQuantScan]:
    """Torch-free header read; None for a plain checkpoint, and never raises on an unreadable file."""
    if not path or not str(path).lower().endswith(".safetensors") or not os.path.isfile(path):
        return None
    try:
        header, base = _read_header(str(path))
    except Exception:  # noqa: BLE001 -- not ours to diagnose; from_single_file will
        return None
    metadata = header.pop("__metadata__", None) or {}
    keys = set(header)
    declared: dict = {}
    scan = ComfyQuantScan()
    for key, entry in header.items():
        if not key.endswith(COMFY_QUANT_SUFFIX):
            continue
        name = key[: -len(COMFY_QUANT_SUFFIX)]
        try:
            declared[name] = _read_json_tensor(str(path), entry, base)
        except Exception:  # noqa: BLE001
            scan.problems.append(f"{name}: unreadable comfy_quant declaration")
    raw_meta = metadata.get(QUANT_METADATA_KEY) if isinstance(metadata, dict) else None
    if raw_meta:
        # ComfyUI lets the header's table win over per-layer tensors.
        try:
            table = json.loads(raw_meta).get("layers") or {}
            declared.update({str(k): v for k, v in table.items()})
        except Exception:  # noqa: BLE001
            scan.problems.append(f"unreadable {QUANT_METADATA_KEY} header")
    if LEGACY_SCALED_FP8_KEY in keys and not raw_meta:
        scan.legacy_scaled_fp8 = True
        marker = str(header[LEGACY_SCALED_FP8_KEY].get("dtype", ""))
        fmt = "float8_e5m2" if marker == "F8_E5M2" else "float8_e4m3fn"
        for key in keys:
            if key.endswith(".scale_weight"):
                declared.setdefault(key[: -len(".scale_weight")], {"format": fmt})

    for name in [n for n in declared if n + ".weight" not in keys]:
        for prefix in _DECLARATION_PREFIXES:
            if prefix + name + ".weight" in keys and prefix + name not in declared:
                declared[prefix + name] = declared.pop(name)
                break
    scaled = {
        key[: -len(suffix)] for key in keys for suffix in _SCALE_SUFFIXES if key.endswith(suffix)
    }
    for name in sorted(scaled - set(declared)):
        # Undeclared scales: only an fp8 weight with a plain weight_scale has one meaning.
        weight = header.get(name + ".weight") or {}
        dtype = weight.get("dtype")
        fmt = next((f for f, d in FP8_FORMATS.items() if d == dtype), None)
        extra = [
            s
            for s in _SCALE_SUFFIXES
            if name + s in keys and s not in (".weight_scale", ".input_scale")
        ]
        if fmt is not None and name + ".weight_scale" in keys and not extra:
            declared[name] = {"format": fmt}
        else:
            scan.problems.append(
                f"{name}: scale tensors with no quantization format declared (weight {dtype})"
            )
    if not declared and not scan.problems and not scan.legacy_scaled_fp8:
        return None

    unsupported: dict = {}
    for name, raw in sorted(declared.items()):
        fmt, convrot, group = _layer_conf(raw)
        weight = header.get(name + ".weight")
        why = None
        if fmt == CONVROT_W4A4:
            why = _w4a4_layer_problem(name, raw, weight, header, keys)
            if why:
                scan.problems.append(f"{name}: {why}")
            else:
                scan.layers[name] = ComfyQuantLayer(
                    name, INT8_TENSORWISE, True, _w4a4_group(raw), packed_int4 = True
                )
            continue
        if fmt is None:
            why = "no format"
        elif fmt not in _CONSUMED:
            unsupported[fmt] = unsupported.get(fmt, 0) + 1
            continue
        elif weight is None:
            why = f"{fmt} declared but there is no {name}.weight"
        elif len(weight.get("shape") or ()) != 2:
            why = f"{fmt} weight of shape {weight.get('shape')} (only 2-D linears are supported)"
        elif fmt in BLOCK_SIZES:
            why = (
                f"ConvRot on {fmt}" if convrot else _block_layer_problem(name, fmt, weight, header)
            )
        elif fmt == INT8_TENSORWISE and weight.get("dtype") != "I8":
            why = f"int8_tensorwise weight stored as {weight.get('dtype')}"
        elif fmt in FP8_FORMATS and weight.get("dtype") not in ("U8", FP8_FORMATS[fmt]):
            why = f"{fmt} weight stored as {weight.get('dtype')}"
        elif convrot and fmt != INT8_TENSORWISE:
            why = f"ConvRot on {fmt}"
        elif convrot and not _is_power_of_four(group):
            why = f"ConvRot group {group!r} is not a power of 4"
        elif convrot and int(weight["shape"][1]) % int(group):
            why = f"in_features {weight['shape'][1]} not divisible by ConvRot group {group}"
        else:
            scale = header.get(name + ".weight_scale") or header.get(name + ".scale_weight")
            rows = int(weight["shape"][0])
            n = 1
            for d in (scale or {}).get("shape") or ():
                n *= int(d)
            if scale is None:
                why = f"{fmt} declared but {name}.weight_scale is missing"
            elif n not in (1, rows):
                why = f"weight_scale of shape {scale.get('shape')} for {rows} rows (block scales)"
            else:
                leftover = [
                    s
                    for s in _SCALE_SUFFIXES
                    if name + s in keys and _LEGACY_RENAME.get(s, s) not in _CONSUMED[fmt]
                ]
                if leftover:
                    why = (
                        f"{fmt} layer carries {', '.join(leftover)}, which this format does not use"
                    )
        if why:
            scan.problems.append(f"{name}: {why}")
            continue
        scan.layers[name] = ComfyQuantLayer(name, fmt, convrot, int(group) if convrot else 0)
    for fmt, count in sorted(unsupported.items()):
        scan.problems.append(f"{count} layer(s) in ComfyUI format {fmt!r}")
    return scan


_DTYPE_BYTES = {
    "F64": 8,
    "F32": 4,
    "F16": 2,
    "BF16": 2,
    "F8_E4M3": 1,
    "F8_E5M2": 1,
    "F8_E8M0": 1,
    "I8": 1,
    "U8": 1,
    "I16": 2,
    "I32": 4,
    "I64": 8,
    "BOOL": 1,
}


# Original-layout names of modules a DiT keeps in fp32 (Wan's ``time_embedding.N`` loads as ``time_embedder``).
_KEEP_FP32_ORIGINAL_ALIASES = {"time_embedder": ("time_embedding",)}


def keeps_fp32(name: str, keep_fp32: Any = ()) -> bool:
    """Whether header key ``name`` names a ``_keep_in_fp32_modules`` module, under its diffusers or original name."""
    keep = tuple(keep_fp32 or ())
    tokens = str(name).split(".")
    return any(t in tokens for m in keep for t in (m, *_KEEP_FP32_ORIGINAL_ALIASES.get(m, ())))


def keep_fp32_modules_for(fam: Any) -> tuple:
    """The family transformer's ``_keep_in_fp32_modules`` (the loader refuses fp8 storage for them), else ()."""
    try:
        import diffusers
        cls = getattr(diffusers, getattr(fam, "transformer_class", None) or "", None)
        keep = getattr(cls, "_keep_in_fp32_modules", None) or ()
    except Exception:  # noqa: BLE001 -- unknown class: nothing excluded
        return ()
    return (keep,) if isinstance(keep, str) else tuple(keep)


def fp8_stored_by_header(
    fmt: str,
    shape: Any,
    name: str = "",
    keep_fp32: Any = (),
) -> bool:
    """Header rule for fp8 layers kept as codes, shared by the host RAM estimate and the planner; the loader can only
    widen more (charged live)."""
    return fmt in FP8_FORMATS and len(shape or ()) == 2 and not keeps_fp32(name, keep_fp32)


def _packed_runs(fmt: str, target: Any) -> bool:
    from .diffusion_packed_block import packed_block_runs_on
    return packed_block_runs_on(fmt, target)


def packed_block_by_header(
    fmt: str,
    shape: Any,
    name: str = "",
    keep_fp32: Any = (),
) -> bool:
    """Header rule for nvfp4 / mxfp8 layers that fp8 storage keeps packed when no native runtime runs them
    (``diffusion_packed_block``); a key-mapped load and a split with mixed input smoothing still widen."""
    from .diffusion_packed_block import packed_block_enabled
    return (
        fmt in BLOCK_SIZES
        and len(shape or ()) == 2
        and not keeps_fp32(name, keep_fp32)
        and packed_block_enabled()
    )


def comfy_resident_mib(
    path: Optional[str],
    scan: Optional[ComfyQuantScan] = None,
    *,
    keep_int8: bool,
    keep_fp8: bool,
    fp8_stored: bool = False,
    keep_nvfp4: bool = False,
    keep_mxfp8: bool = False,
    compute_bytes: int = 2,
    keep_key: Any = None,
    exclude_tokens: Any = (),
    min_features: int = 0,
    fp8_divisible: int = 0,
    block_divisible: Optional[dict] = None,
    key_map: Any = None,
    keep_fp32: Any = (),
    keep_fp32_bytes: Optional[int] = None,
    target: Any = None,
) -> Optional[int]:
    """What the loader leaves resident for a ComfyUI-quantized file, priced from its header: a quantized
    weight a runtime keeps costs its stored bytes, one that is dequantized costs ``numel * compute_bytes``
    (2x an int8 / fp8 file), every other floating tensor is cast to the compute dtype. The file name says
    nothing reliable here (an fp8 file Studio runs natively is not upcast; an int8 one with no runtime is).
    ``keep_key(key)`` limits the count to the keys the loader reads (a file bundling other components);
    an int8 layer whose name holds one of ``exclude_tokens`` is priced dequantized, as Studio's int8 filter
    leaves it, and so is a layer the runtime filter skips (in / out features under ``min_features``, or fp8 features
    not multiples of ``fp8_divisible``). ``key_map`` names layers as the loader's filter sees them (an original-layout
    file). ``keep_fp32``: the transformer's ``_keep_in_fp32_modules``; those layers are never fp8-stored and, widened,
    cost ``keep_fp32_bytes`` per element (4 on an fp16 load, default ``compute_bytes``). Under ``fp8_stored`` an
    nvfp4 / mxfp8 layer no native runtime keeps is priced packed where it can widen on ``target``. None when the
    header cannot be read. Torch-free."""
    fp32_bytes = compute_bytes if keep_fp32_bytes is None else int(keep_fp32_bytes)
    try:
        scan = scan if scan is not None else scan_comfy_quant(path)
        if scan is None:
            return None
        header, _base = _read_header(str(path))
    except Exception:  # noqa: BLE001 -- unknown size: the caller keeps its own estimate
        return None
    header.pop("__metadata__", None)

    def _fits(shape: Any, divisible: int) -> bool:
        if len(shape or ()) != 2:
            return False
        out_f, in_f = (int(d) for d in shape)
        if min(out_f, in_f) < min_features:
            return False
        return not divisible or not (out_f % divisible or in_f % divisible)

    def _names(key: str, shape: Any) -> list:
        names = [key]
        if key_map is not None:
            try:
                names = [k for k, _rows in key_map(key, tuple(shape or ()))] or names
            except ValueError:
                pass
        return names

    def _excluded(key: str, shape: Any) -> bool:
        return any(t in n for n in _names(key, shape) for t in exclude_tokens)

    def _bytes(key: str, shape: Any) -> int:
        if keep_fp32 and any(keeps_fp32(n, keep_fp32) for n in _names(key, shape)):
            return fp32_bytes
        return compute_bytes

    def _logical(fmt: str, shape: Any) -> Any:
        if fmt == NVFP4 and len(shape or ()) == 2:
            return (int(shape[0]), int(shape[1]) * 2)
        return shape

    kept = {}
    for name, layer in scan.layers.items():
        shape = (header.get(name + ".weight") or {}).get("shape")
        kept[name + ".weight"] = (
            layer.format == INT8_TENSORWISE
            and keep_int8
            and not _excluded(name + ".weight", shape)
            and _fits(shape, 0)
        ) or (
            (layer.format == FP8_E4M3 and keep_fp8 and _fits(shape, fp8_divisible))
            or (
                fp8_stored
                and all(
                    fp8_stored_by_header(layer.format, shape, n, keep_fp32)
                    for n in _names(name + ".weight", shape)
                )
            )
            or (
                fp8_stored
                and key_map is None
                and packed_block_by_header(layer.format, shape, name + ".weight", keep_fp32)
                and _packed_runs(layer.format, target)
            )
            or (
                {NVFP4: keep_nvfp4, MXFP8: keep_mxfp8}.get(layer.format, False)
                # input smoothing has no runtime Linear: the loader dequantizes such a layer
                and name + ".pre_quant_scale" not in header
                and _fits(
                    _logical(layer.format, shape), (block_divisible or {}).get(layer.format, 0)
                )
            )
        )
    packed = {name + ".weight" for name, layer in scan.layers.items() if layer.format == NVFP4}
    # Packed int4 is half the int8 the loader unpacks it to, kept or dequantized.
    packed_int4 = {name + ".weight" for name, layer in scan.layers.items() if layer.packed_int4}
    total = 0
    for key, entry in header.items():
        if keep_key is not None and not keep_key(key):
            continue
        shape = entry.get("shape") or ()
        numel = 1
        for d in shape:
            numel *= int(d)
        dtype = str(entry.get("dtype", ""))
        stored = numel * _DTYPE_BYTES.get(dtype, 2)
        if key in kept:
            if kept[key]:
                total += stored * (2 if key in packed_int4 else 1)
            else:
                total += (
                    numel * _bytes(key, shape) * (2 if key in packed or key in packed_int4 else 1)
                )
        elif key.endswith(COMFY_QUANT_SUFFIX) or any(key.endswith(s) for s in _SCALE_SUFFIXES):
            total += stored
        elif dtype.startswith(("F", "BF")):
            total += numel * _bytes(key, shape)
        else:
            total += stored
    return -(-total // (1024 * 1024)) if total > 0 else None


def _numel(entry: Optional[dict]) -> int:
    n = 1
    for d in (entry or {}).get("shape") or ():
        n *= int(d)
    return n


def _block_layer_problem(name: str, fmt: str, weight: dict, header: dict) -> Optional[str]:
    """Why an ``nvfp4`` / ``mxfp8`` layer cannot be decoded, from its header entries, or None."""
    rows, stored = (int(d) for d in weight["shape"])
    if fmt == NVFP4:
        if weight.get("dtype") != "U8":
            return f"nvfp4 weight stored as {weight.get('dtype')}"
        cols = stored * 2
    else:
        if weight.get("dtype") not in ("F8_E4M3", "U8"):
            return f"mxfp8 weight stored as {weight.get('dtype')}"
        cols = stored
    block = BLOCK_SIZES[fmt]
    if cols % block:
        return f"{fmt} weight with {cols} columns (not a multiple of {block})"
    scale = header.get(name + ".weight_scale")
    want = ("F8_E4M3", "U8") if fmt == NVFP4 else ("F8_E8M0", "U8")
    if scale is None:
        return f"{fmt} declared but {name}.weight_scale is missing"
    if scale.get("dtype") not in want:
        return f"{fmt} block scales stored as {scale.get('dtype')}"
    if _numel(scale) != tiled_scale_numel(rows, cols // block):
        return f"{fmt} block scales of shape {scale.get('shape')} for a {rows}x{cols} weight (not the 128x4 tiled layout)"
    if fmt == NVFP4:
        second = header.get(name + ".weight_scale_2")
        if second is None or _numel(second) != 1:
            return f"nvfp4 needs a scalar {name}.weight_scale_2"
        smooth = header.get(name + ".pre_quant_scale")
        if smooth is not None and _numel(smooth) != cols:
            return f"pre_quant_scale of shape {smooth.get('shape')} for {cols} input features"
    entry = header.get(name + ".input_scale")
    if entry is not None and _numel(entry) != 1:
        return f"input_scale of shape {entry.get('shape')} (only a per-tensor scale is supported)"
    leftover = [
        s
        for s in _SCALE_SUFFIXES
        if name + s in header and _LEGACY_RENAME.get(s, s) not in _CONSUMED[fmt]
    ]
    if leftover:
        return f"{fmt} layer carries {', '.join(leftover)}, which this format does not use"
    return None


def _is_power_of_four(size: Any) -> bool:
    from .diffusion_convrot import is_power_of_four
    return is_power_of_four(size)


def comfy_quant_error(scan: Optional[ComfyQuantScan], filename: str = "") -> Optional[str]:
    """A user-facing refusal for ``scan``, or None when every declared layer is loadable."""
    if scan is None or not scan.problems:
        return None
    shown = "; ".join(scan.problems[:4])
    more = f" (and {len(scan.problems) - 4} more)" if len(scan.problems) > 4 else ""
    return (
        f"{filename or 'This checkpoint'} is a ComfyUI-quantized checkpoint Unsloth cannot run "
        f"faithfully: {shown}{more}. Supported ComfyUI formats are int8_tensorwise (with or "
        "without ConvRot), float8_e4m3fn, float8_e5m2, nvfp4 and mxfp8; use the bf16 file, a GGUF, "
        "or Unsloth's own int8 / fp8 transformer quantization instead."
    )


def refuse_comfy_quant(path: Optional[str]) -> Optional[ComfyQuantScan]:
    """``scan_comfy_quant`` that raises ``ValueError`` for a checkpoint it would have to refuse."""
    scan = scan_comfy_quant(path)
    problem = comfy_quant_error(scan, os.path.basename(str(path or "")))
    if problem:
        raise ValueError(problem)
    return scan


def _nbytes(tensors: Any) -> int:
    return sum(int(t.numel()) * int(t.element_size()) for t in tensors)


def _charge_contiguous(tensor: Any) -> None:
    """Check the copy ``tensor.contiguous()`` makes of a non-contiguous host tensor (a view costs nothing)."""
    if not tensor.is_contiguous():
        from .diffusion_single_file_converters import charge_host_ram
        charge_host_ram(_nbytes([tensor]))


def _dequant(codes: Any, scale: Any, group: int, dtype: Any) -> Any:
    """``codes * scale`` in float32, the ConvRot rotation undone, cast to ``dtype``."""
    import torch

    from .diffusion_single_file_converters import charge_host_ram

    rows = codes.shape[0]
    out_size = torch.empty((), dtype = dtype).element_size()
    if not group and codes.dim() == 2 and rows and fused_dequant_enabled():
        cols = codes.shape[1]
        step = chunk_rows(rows, cols, codes.device)
        if step:
            # Row chunks into the output: the output plus one float32 chunk is the peak.
            charge_host_ram(codes.numel() * out_size + step * cols * 4)
            return dequant_rows(
                codes,
                scale.to(torch.float32).reshape(-1).expand(rows),
                dtype,
                lambda c: c.to(torch.float32, copy = True),
                triton_ok = False,
            )
    # Peak, not just the output: the float32 codes and their float32 product are live together (8 bytes per
    # element); ConvRot's batched matmul holds the product, a float32 copy of it and its float32 result (12,
    # measured); last the product and the output.
    charge_host_ram(codes.numel() * max(12 if group else 8, 4 + out_size))
    weight = codes.to(torch.float32) * scale.to(torch.float32).reshape(-1, 1).expand(rows, 1)
    if group:
        from .diffusion_convrot import build_convrot_hadamard

        # The file holds W @ blockdiag(H).T; H is symmetric and orthogonal, so W = that @ H.
        h = build_convrot_hadamard(group, device = weight.device, dtype = torch.float32)
        cols = weight.shape[1]
        weight = (weight.reshape(rows, cols // group, group) @ h).reshape(rows, cols)
    return weight.to(dtype)


@dataclass
class _BlockWeight:
    """Row segments ``(codes, plain scales, extras)`` from one or more layers."""

    fmt: str
    parts: list


def _dequant_parts(fmt: str, parts: list, dtype: Any) -> Any:
    import torch

    from .diffusion_comfy_block import dequant_block

    dense = [
        dequant_block(
            fmt,
            codes,
            scale,
            tensor_scale = extra.get("tensor_scale"),
            pre_quant_scale = extra.get("pre_quant_scale"),
            dtype = dtype,
        )
        for codes, scale, extra in parts
    ]
    if len(dense) == 1:
        return dense[0]
    from .diffusion_single_file_converters import charge_host_ram

    charge_host_ram(_nbytes(dense))
    return torch.cat(dense)


def _block_runtime_args(value: "_BlockWeight") -> Optional[tuple]:
    """``(codes, scales, tensor_scale, input_scale)`` when one runtime Linear holds ``value`` exactly, else None.
    Segments share an input: the largest static input_scale (none clips); any missing one = dynamic (None)."""
    import torch

    extras = [extra for _c, _s, extra in value.parts]
    if len(value.parts) > 1:
        from .diffusion_single_file_converters import charge_host_ram
        charge_host_ram(
            _nbytes([c for c, _s, _e in value.parts]) + _nbytes([s for _c, s, _e in value.parts])
        )
    codes = (
        torch.cat([c for c, _s, _e in value.parts]) if len(value.parts) > 1 else value.parts[0][0]
    )
    scale = (
        torch.cat([s for _c, s, _e in value.parts]) if len(value.parts) > 1 else value.parts[0][1]
    )
    if value.fmt == MXFP8:
        return codes, scale, None, None
    tensor_scales = {e.get("tensor_scale") for e in extras}
    input_scales = [e.get("input_scale") for e in extras]
    if len(tensor_scales) != 1 or None in tensor_scales:
        return None
    if any(e.get("pre_quant_scale") is not None for e in extras):
        return None
    return codes, scale, tensor_scales.pop(), None if None in input_scales else max(input_scales)


def _int8_tensor(name: str, codes: Any, scale: Any, dtype: Any) -> Optional[Any]:
    """The torchao int8 weight a hosted INT8 checkpoint rebuilds into, built by the same decoder."""
    import torch

    from .prequant_native import native_unflatten

    rows, cols = codes.shape
    dtype_name = str(dtype).replace("torch.", "")
    entry = {
        "_type": "Int8Tensor",
        "_data": {
            "act_quant_kwargs": {
                "_type": "QuantizeTensorToInt8Kwargs",
                "_data": {
                    "granularity": {"_type": "PerRow", "_data": {"dim": -1}},
                    "mapping_type": {"_type": "MappingType", "_data": "SYMMETRIC"},
                    "reduce_range": False,
                },
            },
            "reduce_range": False,
            "block_size": [1, cols],
            "dtype": {"_type": "torch.dtype", "_data": dtype_name},
        },
        "_tensor_data_names": ["zero_point", "qdata", "scale"],
    }
    stem = name.rsplit(".", 1)[0]
    _charge_contiguous(codes)
    tensors = {
        f"{stem}._weight_qdata": codes.contiguous(),
        f"{stem}._weight_scale": scale.to(torch.float32).reshape(rows, 1).contiguous(),
        f"{stem}._weight_zero_point": torch.zeros((rows, 1), dtype = torch.int8),
    }
    raw = {"tensor_names": json.dumps([name]), name: json.dumps(entry)}
    rebuilt = native_unflatten(tensors, raw)
    return None if rebuilt is None else rebuilt[name]


def _fp8_tensor(
    name: str,
    codes: Any,
    scale: Any,
    dtype: Any,
    fast_accum: Optional[bool] = None,
) -> Optional[Any]:
    """The torchao fp8 weight a hosted FP8 checkpoint rebuilds into (per-row ``Float8Tensor``, dynamic
    per-row fp8 activations with the same 1e-12 floor, the plain-torch kernel), built by the same decoder.
    A per-tensor scale is the per-row layout with every row's scale equal, so it is repeated, not changed."""
    import torch

    from .diffusion_transformer_quant import _resolve_fast_accum
    from .prequant_native import native_unflatten

    rows, cols = codes.shape
    dtype_name = str(dtype).replace("torch.", "")
    kernel = {"_type": "KernelPreference", "_data": "TORCH"}
    entry = {
        "_type": "Float8Tensor",
        "_data": {
            "block_size": [1, cols],
            "mm_config": {
                "_type": "Float8MMConfig",
                "_data": {
                    "emulate": False,
                    "use_fast_accum": bool(_resolve_fast_accum(fast_accum)),
                    "pad_inner_dim": False,
                },
            },
            "act_quant_kwargs": {
                "_type": "QuantizeTensorToFloat8Kwargs",
                "_data": {
                    "float8_dtype": {"_type": "torch.dtype", "_data": FP8_E4M3},
                    "granularity": {"_type": "PerRow", "_data": {"dim": -1}},
                    "mm_config": None,
                    "hp_value_lb": 1e-12,
                    "hp_value_ub": None,
                    "kernel_preference": kernel,
                },
            },
            "kernel_preference": kernel,
            "dtype": {"_type": "torch.dtype", "_data": dtype_name},
        },
        "_tensor_data_names": ["qdata", "scale"],
    }
    stem = name.rsplit(".", 1)[0]
    _charge_contiguous(codes)
    tensors = {
        f"{stem}._weight_qdata": codes.contiguous(),
        f"{stem}._weight_scale": scale.to(torch.float32)
        .reshape(-1, 1)
        .expand(rows, 1)
        .contiguous(),
    }
    raw = {"tensor_names": json.dumps([name]), name: json.dumps(entry)}
    rebuilt = native_unflatten(tensors, raw)
    return None if rebuilt is None else rebuilt[name]


def _mapping(transformer_cls: Any) -> tuple[Any, Any]:
    from diffusers.loaders import single_file_model as sfm

    from .diffusion_single_file_converters import CONVERTERS

    # Ahead of diffusers' own: its Krea 2 converter (0.41) strips only model.diffusion_model.
    own = CONVERTERS.get(getattr(transformer_cls, "__name__", ""))
    if own is not None:
        return own, sfm
    name = sfm._get_single_file_loadable_mapping_class(transformer_cls)
    entry = sfm.SINGLE_FILE_LOADABLE_CLASSES.get(name or "")
    if not entry:
        # The single-file branch registers Studio's converters for classes diffusers lacks (Qwen-Image-2.1) just
        # before its own call; the hosted prequant route reaches here without passing through it.
        try:
            from .diffusion import _register_unregistered_single_file_classes
            _register_unregistered_single_file_classes()
        except Exception:  # noqa: BLE001 -- nothing more to register: refused below
            pass
        name = sfm._get_single_file_loadable_mapping_class(transformer_cls)
        entry = sfm.SINGLE_FILE_LOADABLE_CLASSES.get(name or "")
    if not entry:
        raise ValueError(f"{transformer_cls.__name__} has no single-file converter")
    if getattr(transformer_cls, "__name__", "") == "Flux3Transformer2DModel":
        return _flux3_split_fused_qkv(entry["checkpoint_mapping_fn"]), sfm
    return entry["checkpoint_mapping_fn"], sfm


def _flux3_split_fused_qkv(mapping_fn: Any) -> Any:
    """``mapping_fn`` after splitting ComfyUI's fused FLUX.3 attention: BFL's ComfyUI int8 files
    (black-forest-labs/flux-3-image-klein-comfy) store ``<block>.qkv.weight`` where the BFL layout diffusers converts
    has ``q_proj`` / ``k_proj`` / ``v_proj`` (24 heads x 128 each, no GQA, so equal thirds). Rows only: per-row int8
    scales and the ConvRot column rotation split with them, and the row tags the loader decodes stay exact. A file in
    the BFL layout passes through unchanged."""
    import functools

    @functools.wraps(mapping_fn)
    def convert(checkpoint, **kwargs):
        for key in [k for k in checkpoint if k.endswith(".qkv.weight")]:
            value = checkpoint.pop(key)
            rows = value.shape[0] // 3
            if rows * 3 != value.shape[0]:
                raise ValueError(f"{key}: {value.shape[0]} rows do not split into q, k and v")
            stem = key[: -len("qkv.weight")]
            for index, part in enumerate(("q_proj", "k_proj", "v_proj")):
                checkpoint[f"{stem}{part}.weight"] = value[index * rows : (index + 1) * rows]
        for key in [k for k in checkpoint if k.endswith(".comfy_attention.config")]:
            del checkpoint[key]  # ComfyUI's attention-backend hint, not a weight
        return mapping_fn(checkpoint, **kwargs)

    return convert


def _decode_rows(
    name: str,
    tagged: Any,
    sources: list,
    width: Optional[int] = None,
) -> list:
    """``[(source index, first row, n rows)]`` for a converted int8 weight, or raise. ``width``: the tag width
    the weights were given (None: their real column count)."""
    import torch

    if tagged.dtype != torch.float64 or tagged.dim() != 2 or tagged.numel() == 0:
        raise ValueError(f"{name}: the converter changed an int8 weight's dtype or rank")
    col = tagged[:, 0]
    for j in (tagged.shape[1] // 2, tagged.shape[1] - 1):
        if not torch.equal(col, tagged[:, j]):
            raise ValueError(f"{name}: the converter mixed columns of an int8 weight")
    # Pure Python on one list: per-weight tensor ops each wake the intra-op pool and cost more than the decode.
    segments: list = []
    for value in col.tolist():
        if value < 0 or value != int(value):
            raise ValueError(f"{name}: the converter transformed int8 weight values")
        i, r = divmod(int(value), int(_TAG))
        if i >= len(sources) or r >= sources[i][1].shape[0]:
            raise ValueError(f"{name}: an int8 row does not decode to a source row")
        if segments and segments[-1][0] == i and segments[-1][1] + segments[-1][2] == r:
            segments[-1][2] += 1
        else:
            segments.append([i, r, 1])
    if any(
        tagged.shape[1] != (sources[i][1].shape[1] if width is None else width)
        for i, _r, _n in segments
    ):
        raise ValueError(f"{name}: the converter changed an int8 weight's column count")
    return segments


def original_layout(transformer_cls: Any, path: str) -> Optional[dict]:
    """The key map / prepare / dtype hooks for a class with no diffusers single-file converter, or None."""
    name = getattr(transformer_cls, "__name__", "")
    if name == "HunyuanVideo15Transformer3DModel":
        from .video_hv15_comfy import comfy_layout
    elif name == "MiniMaxH3Transformer3DModel":
        from .video_minimax_h3_comfy import comfy_layout
    else:
        return None
    return comfy_layout(path)


def _apply_key_map(state: dict, kept: list, key_map: Any) -> dict:
    """``state`` (file keys) renamed and row-split by ``key_map``; kept layers become ``(codes, scale, group, format)``.

    Row selections are views where they are one contiguous run, so no layer is copied except a reordered one."""
    import torch

    sources = {
        layer.name + ".weight": (codes, scale, layer.group, layer.format)
        for layer, codes, scale, *_extra in kept
    }

    def take(value: Any, rows: Any) -> Any:
        if rows is None:
            return value
        if isinstance(value, tuple):
            codes, scale, group, fmt = value
            scale = scale.reshape(-1, 1).expand(codes.shape[0], 1)
            return (take(codes, rows), take(scale, rows), group, fmt)
        if value.dtype not in (torch.int8, torch.uint8) and value.element_size() == 1:
            # float8: concatenation goes through uint8 (not implemented for float8 on every torch)
            return take(value.view(torch.uint8), rows).view(value.dtype)
        parts = [value[int(r) : int(r) + int(n)] for r, n in rows]
        if len(parts) == 1:
            return parts[0]
        from .diffusion_single_file_converters import charge_host_ram

        # a reordered selection (H3's [gate; value] fc1) is a full copy of the rows it joins
        charge_host_ram(_nbytes(parts))
        return torch.cat(parts)

    converted: dict = {}
    for key in list(state):
        value = state.pop(key)
        if value is None:
            value = sources.pop(key)
        data = value[0] if isinstance(value, tuple) else value
        rows_total = data.shape[0] if data.dim() else 0
        for new_key, rows in key_map(key, tuple(data.shape)):
            if rows is not None and any(r < 0 or n <= 0 or r + n > rows_total for r, n in rows):
                raise ValueError(f"{key}: row selection {rows} outside its {rows_total} rows")
            converted[new_key] = take(value, rows)
    return converted


def comfy_torchao_quantized(model: Any) -> bool:
    """Whether a ComfyUI load left torchao-quantized weights in ``model`` (eager is several times slower)."""
    info = getattr(model, "_unsloth_comfy_quant", None) or {}
    return "torchao" in (info.get("backend"), info.get("fp8_backend"))


def comfy_int8_backend(
    target: Any,
    family: Optional[str],
    base_repo: Optional[str] = None,
    *,
    offload: bool = False,
    lora: bool = False,
) -> Optional[str]:
    """int8 runtime: torchao when resident, native under offload (or as storage, ``int8_storage_scheme``, where neither
    runs; never under a LoRA), None to dequantise to bf16."""
    if (os.environ.get(COMFY_INT8_ENV) or "").strip().lower() in ("0", "off", "false", "no"):
        return None
    try:
        from .diffusion_transformer_quant import (
            TQ_INT8,
            int8_storage_scheme,
            native_quant_scheme,
            select_transformer_quant_scheme,
        )

        if native_quant_scheme(target, TQ_INT8, family = family, offload = offload) == TQ_INT8:
            return "native"
        if not offload and (
            select_transformer_quant_scheme(target, TQ_INT8, family = family, base_repo = base_repo)
            == TQ_INT8
        ):
            return "torchao"
        if not lora and int8_storage_scheme(target, family, offload = offload) == TQ_INT8:
            return "native"
    except Exception:  # noqa: BLE001 -- an unanswerable probe takes the exact dense path
        pass
    return None


def comfy_fp8_backend(
    target: Any,
    family: Optional[str],
    base_repo: Optional[str] = None,
    *,
    offload: bool = False,
    torchao_offload: bool = False,
) -> Optional[str]:
    """Which of Studio's fp8 runtimes takes the ``float8_e4m3fn`` layers, by the rule its own fp8 quant
    follows: ``"torchao"`` (the per-row ``Float8Tensor`` and ``_scaled_mm``) on a resident plan whose GPU
    passes Studio's fp8 probe, ``"native"`` (the torchao-free weight-only twin) where Studio's own fp8
    quant runs natively (ROCm, the stubbed torchao), None (dequantize to bf16) where neither runs: an
    older GPU, CPU, MPS, or an offloaded plan on the torchao path (the model offload hooks cannot move a
    ``Float8Tensor``: "Attempted to set the storage of a tensor on device cuda:0 to a storage on ... cpu").
    ``torchao_offload``: the plan streams the denoiser (``torchao_offload_plan``), which torchao survives.
    ``UNSLOTH_DIFFUSION_COMFY_FP8=0`` never takes an fp8 GEMM."""
    if (os.environ.get(COMFY_FP8_ENV) or "").strip().lower() in ("0", "off", "false", "no"):
        return None
    try:
        import torch

        from .diffusion_transformer_quant import (
            TQ_FP8,
            native_quant_scheme,
            select_transformer_quant_scheme,
        )

        if native_quant_scheme(target, TQ_FP8, family = family, offload = offload) == TQ_FP8:
            return "native"
        if (
            (not offload or torchao_offload)
            and getattr(target, "dtype", None) is torch.bfloat16
            and select_transformer_quant_scheme(target, TQ_FP8, family = family, base_repo = base_repo)
            == TQ_FP8
        ):
            return "torchao"
    except Exception:  # noqa: BLE001 -- an unanswerable probe takes the exact dense path
        pass
    return None


FP8_STORED_ATTR = "_unsloth_fp8_stored"


def fp8_stored_layers(model: Any) -> int:
    """Count of fp8-stored Linears (they cannot carry a LoRA)."""
    try:
        return int(getattr(model, FP8_STORED_ATTR, 0) or 0)
    except (TypeError, ValueError):
        return 0


def pipe_fp8_stored_layers(pipe: Any) -> int:
    """fp8-stored plus packed nvfp4 / mxfp8 Linears of the denoisers: buffers widened per forward."""
    from .diffusion_packed_block import packed_block_layers
    return sum(
        fp8_stored_layers(getattr(pipe, attr, None))
        + packed_block_layers(getattr(pipe, attr, None))
        for attr in ("transformer", "transformer_2")
    )


def fp8_storage_disabled() -> bool:
    return (os.environ.get(FP8_STORAGE_ENV) or "").strip().lower() in ("0", "off", "false", "no")


def fp8_storage_forced() -> bool:
    return (os.environ.get(FP8_STORAGE_ENV) or "").strip().lower() in ("1", "on", "true", "yes")


def fp8_storage_wanted(
    target: Any = None,
    *,
    lora: bool = False,
    offload: bool = False,
    widened_mib: Optional[int] = None,
    host_available_mib: Optional[int] = None,
) -> bool:
    """Store fp8 only when widening would offload (on MPS, which never offloads: overrun the resident margin,
    ``diffusion_memory.mps_plan_tight``) or leave under the host reserve: widening is otherwise faster (measured
    +45% s/step eager for storage on Krea 2 / B200, parity compiled; +13% on MPS)."""
    if not comfy_fp8_storage(target, lora = lora):
        return False
    if fp8_storage_forced() or offload:
        return True
    if widened_mib is None or host_available_mib is None:
        return False
    return int(widened_mib) + FP8_STORAGE_HOST_RESERVE_MIB > int(host_available_mib)


def fp8_widen_chosen(
    target: Any = None,
    *,
    lora: bool = False,
    offload: bool = False,
    widened_mib: Optional[int] = None,
    host_available_mib: Optional[int] = None,
) -> bool:
    """Whether ``fp8_storage_wanted`` had the choice and widened because the load fits with its host reserve free. Only
    such a load is refused against that reserve (``single_file_host_reserve_mib``); every other one keeps the
    proportional small-host reserve."""
    if not comfy_fp8_storage(target, lora = lora) or fp8_storage_forced() or offload:
        return False
    if widened_mib is None or host_available_mib is None:
        return False
    return not fp8_storage_wanted(
        target, lora = lora, widened_mib = widened_mib, host_available_mib = host_available_mib
    )


def comfy_fp8_storage(target: Any = None, *, lora: bool = False) -> bool:
    """Whether fp8 storage can run: same weights as the load-time dequant, half the bytes. Off for a LoRA (needs
    dense Linears) and torch without float8."""
    if lora or fp8_storage_disabled():
        return False
    try:
        import torch
        return hasattr(torch, "float8_e4m3fn") and hasattr(torch, "float8_e5m2")
    except Exception:  # noqa: BLE001 -- no torch: nothing to store
        return False


def comfy_conversion_record(path: Optional[str]) -> dict:
    """The ``unsloth_comfy_conversion`` header record our converter writes (base model, scheme, family),
    or {} for any other file. Torch-free, never raises."""
    try:
        header, _base = _read_header(str(path))
        raw = (header.get("__metadata__") or {}).get(CONVERSION_RECORD_KEY)
        record = json.loads(raw) if raw else {}
        return record if isinstance(record, dict) else {}
    except Exception:  # noqa: BLE001 -- no record is not an error
        return {}


# The ComfyUI layer format each Studio prequant scheme is published in.
PREQUANT_SCHEME_FORMATS = {"int8": (INT8_TENSORWISE,), "fp8": (FP8_E4M3,)}


def comfy_prequant_scheme(scan: Optional[ComfyQuantScan]) -> Optional[str]:
    """The Studio prequant scheme a ComfyUI file's quantized layers all share, else None."""
    if scan is None or scan.problems or not scan.layers:
        return None
    formats = {layer.format for layer in scan.layers.values()}
    for scheme, allowed in PREQUANT_SCHEME_FORMATS.items():
        if formats <= set(allowed):
            return scheme
    return None


def load_comfy_prequant(
    transformer_cls: Any,
    path: str,
    *,
    scheme: str,
    base: str,
    family: Optional[str],
    dtype: Any,
    hf_token: Optional[str] = None,
    cache_dir: Optional[str] = None,
    local_files_only: bool = False,
    fast_accum: Optional[bool] = None,
    min_features: Optional[int] = None,
    config_subfolder: str = "transformer",
    logger: Any = None,
) -> Any:
    """Rebuilds a ComfyUI prequant on the CPU as Studio's scheme; ValueError for formats it cannot run."""
    name = os.path.basename(str(path))
    scan = scan_comfy_quant(path)
    if scan is None:
        raise ValueError(f"{name} is not a ComfyUI-quantized checkpoint")
    problem = comfy_quant_error(scan, name)
    if problem:
        raise ValueError(problem)
    found = comfy_prequant_scheme(scan)
    if found != scheme:
        raise ValueError(
            f"{name} holds {', '.join(f'{k} x{v}' for k, v in sorted(scan.counts().items()))}, "
            f"not a {scheme} checkpoint"
        )
    if not family:
        raise ValueError(f"{name}: a ComfyUI checkpoint needs the model family to pick its layers")
    record = comfy_conversion_record(path)
    recorded_base = record.get("base_model_id")
    if recorded_base and base:
        from .diffusion_prequant import _same_base_model
        if not _same_base_model(str(recorded_base), str(base)):
            raise ValueError(f"{name} was converted from {recorded_base}, not {base}")
    kwargs = {
        "config": base,
        "subfolder": config_subfolder,
        "torch_dtype": dtype,
        "cache_dir": cache_dir,
        "local_files_only": local_files_only,
    }
    if hf_token:
        kwargs["token"] = hf_token
    import torch

    if scheme == "fp8" and dtype is not torch.bfloat16:
        raise ValueError(f"{name}: Unsloth's fp8 runtime needs a bfloat16 pipeline, not {dtype}")
    model = load_comfy_quant_transformer(
        transformer_cls,
        path,
        scan,
        kwargs,
        int8_backend = "torchao" if scheme == "int8" else None,
        fp8_backend = "torchao" if scheme == "fp8" else None,
        family = family,
        fast_accum = fast_accum,
        min_features = min_features,
        finalize = False,
        logger = logger,
    )
    kept = (getattr(model, "_unsloth_comfy_quant", None) or {}).get(scheme, 0)
    if not kept:
        # never a dense model under a prequant label: the caller falls back to its own quantize path
        raise ValueError(f"{name}: no layer could be rebuilt as a {scheme} weight on this install")
    return model


@host_ram_budget_scope
def load_comfy_quant_transformer(
    transformer_cls: Any,
    path: str,
    scan: ComfyQuantScan,
    sf_kwargs: dict,
    *,
    int8_backend: Optional[str],
    fp8_backend: Optional[str] = None,
    nvfp4_backend: Optional[str] = None,
    mxfp8_backend: Optional[str] = None,
    family: Optional[str] = None,
    target: Any = None,
    fast_accum: Optional[bool] = None,
    min_features: Optional[int] = None,
    finalize: bool = True,
    logger: Any = None,
    keep_key: Any = None,
    pre_convert: Any = None,
    key_map: Any = None,
    prepare_model: Any = None,
    keep_dtype: Any = None,
    fp8_storage: Optional[bool] = None,
    fp8_widen_chosen: bool = False,
) -> Any:
    """Build ``transformer_cls`` from the ComfyUI-quantized ``path``.

    ``sf_kwargs`` are the ``from_single_file`` kwargs the caller would have used (``config``,
    ``subfolder``, ``torch_dtype``, ``token``, ``cache_dir``, ``local_files_only``). With an
    ``int8_backend`` (``comfy_int8_backend``) the int8 layers Studio's own int8 filter selects keep
    their codes and scales, as torchao ``Int8Tensor`` weights under ConvRot-rotating Linears
    (``"torchao"``) or as native int8 twins (``"native"``); with an ``fp8_backend``
    (``comfy_fp8_backend``) the ``float8_e4m3fn`` layers Studio's own fp8 filter selects do the same,
    as per-row ``Float8Tensor`` weights or native fp8 twins; with an ``nvfp4_backend`` / ``mxfp8_backend``
    (``diffusion_comfy_block.comfy_block_backend``) the nvfp4 / mxfp8 layers the matching Studio filter selects
    keep their codes on Studio's FlashInfer NVFP4 Linear / the ``torch._scaled_mm`` MXFP8 Linear. Everything
    else is dequantized to the compute dtype, except fp8 Linears under ``fp8_storage`` (None = env opt-in
    only), which widen per layer in the forward. ``finalize`` applies the small-M padding here (the single-file path); the hosted
    prequant loader passes False and pads after placement, as for its own checkpoints.

    ``keep_key(key)`` limits the read to the DiT's keys of a file that bundles other components;
    ``pre_convert(state)`` renames keys (never values) before the family converter runs. A family with no
    diffusers single-file converter passes ``key_map(key, shape)`` (or registers it in ``original_layout``):
    ``[(diffusers key, rows)]`` per file key, ``rows`` None (the whole tensor) or ``[(first row, n rows), ...]``;
    ``prepare_model(model)`` reshapes the freshly built model before the weights load, and ``keep_dtype(key)``
    names a dtype a file tensor keeps instead of the compute dtype. Raises ``ValueError`` for a checkpoint it
    must refuse."""
    import torch
    from safetensors.torch import load_file

    from .diffusion_comfy_block import (
        build_runtime_linear,
        decode_layer,
        dequant_block,
        logical_cols,
    )
    from .diffusion_transformer_quant import (
        DEFAULT_MIN_LINEAR_FEATURES,
        TQ_FP8,
        TQ_INT8,
        TQ_MXFP8,
        TQ_NVFP4,
        divisible_for_scheme,
        exclude_tokens_for_scheme,
        make_filter_fn,
        native_int8_act,
    )

    problem = comfy_quant_error(scan, os.path.basename(path))
    if problem:
        raise ValueError(problem)
    if key_map is None:
        layout = original_layout(transformer_cls, path)
        if layout:
            key_map = layout.get("key_map")
            prepare_model = prepare_model or layout.get("prepare_model")
            keep_dtype = keep_dtype or layout.get("keep_dtype")
    kwargs = dict(sf_kwargs)
    dtype = kwargs.pop("torch_dtype", None) or kwargs.pop("dtype", None) or torch.bfloat16
    if dtype is not torch.bfloat16:
        # Studio's fp8 runtime asserts bf16 weights; an fp16 / fp32 pipeline dequantizes them instead.
        fp8_backend = None
        mxfp8_backend = None
    if fp8_storage is None:
        fp8_storage = fp8_storage_forced() and comfy_fp8_storage(target)
    from .diffusion_packed_block import (
        PACKED_BLOCK_ATTR,
        packed_block_args,
        packed_block_enabled,
        packed_block_linear_class,
        packed_block_runs_on,
    )

    # fp8 storage also keeps nvfp4 / mxfp8 layers without a native runtime packed (widened per forward).
    packed = bool(fp8_storage) and key_map is None and packed_block_enabled()
    if keep_key is None:
        state = load_file(str(path))
    else:
        from safetensors import safe_open

        with safe_open(str(path), framework = "pt", device = "cpu") as handle:
            state = {k: handle.get_tensor(k) for k in handle.keys() if keep_key(k)}
        stray = [n for n in scan.layers if n + ".weight" not in state]
        if stray:
            raise ValueError(
                f"{os.path.basename(path)}: ComfyUI-quantized layers outside the denoiser "
                f"({stray[0]}) are not supported"
            )
    state.pop(LEGACY_SCALED_FP8_KEY, None)
    for key in [k for k in state if k.endswith(COMFY_QUANT_SUFFIX)]:
        del state[key]
    for key in list(state):
        for old, new in _LEGACY_RENAME.items():
            if key.endswith(old):
                state[key[: -len(old)] + new] = state.pop(key)

    keep_fp32 = getattr(transformer_cls, "_keep_in_fp32_modules", None) or []
    if isinstance(keep_fp32, str):
        keep_fp32 = [keep_fp32]
    # fp16: _keep_in_fp32_modules names diffusers keys (Wan time_embedder, scale_shift_table), so every layer goes
    # through the converter first and dtypes are decided on the converted names.
    fp16_keep = dtype == torch.float16 and bool(keep_fp32)

    def _dtype_for(key: str) -> Any:
        return torch.float32 if fp16_keep and any(m in key.split(".") for m in keep_fp32) else dtype

    backends = {
        INT8_TENSORWISE: int8_backend,
        FP8_E4M3: fp8_backend,
        NVFP4: nvfp4_backend,
        MXFP8: mxfp8_backend,
    }
    # Without a runtime (fp8 below sm_89) layers widen to ``dtype`` in host RAM: refuse before an OOM.
    from .diffusion_single_file_converters import (
        HostRamBudget,
        HostRamShortfallError,
        charge_cast,
        charge_host_ram,
        converted_host_bytes,
    )

    # Mirrors the source loop below: a layer is kept as codes only with a runtime for its format (fp16_keep
    # merely defers the dtype choice; the layer is still expanded) and, for a block format, no key map.
    # nvfp4 headers describe packed uint8 (K / 2 columns); the dense weight is N x K.
    header_shapes = {}
    if fp8_storage:
        try:
            _hdr, _ = _read_header(str(path))
            header_shapes = {
                k: (v or {}).get("shape") for k, v in _hdr.items() if k != "__metadata__"
            }
        except Exception:  # noqa: BLE001 -- the estimate then prices them widened (conservative)
            header_shapes = {}

    def _stored(layer: Any) -> bool:
        shape = header_shapes.get(layer.name + ".weight")
        return (
            bool(fp8_storage)
            and shape is not None
            and fp8_stored_by_header(layer.format, shape, layer.name, keep_fp32)
        )

    def _packed(layer: Any) -> bool:
        shape = header_shapes.get(layer.name + ".weight")
        return (
            packed
            and shape is not None
            and not backends.get(layer.format)
            and packed_block_runs_on(layer.format, target)
            and packed_block_by_header(layer.format, shape, layer.name, keep_fp32)
        )

    _widened = {
        layer.name + ".weight": (
            (2 if layer.format == NVFP4 or layer.packed_int4 else 1)
            if not (backends.get(layer.format) or _stored(layer) or _packed(layer))
            or (layer.format in BLOCK_SIZES and key_map is not None)
            else 0
        )
        for layer in scan.layers.values()
    }
    _stored_scale_bytes = sum(
        4 * int(header_shapes[layer.name + ".weight"][0])
        for layer in scan.layers.values()
        if (_stored(layer) or _packed(layer)) and not backends.get(layer.format)
    )
    # The header estimate refuses early; the budget it activates is charged by every allocating helper
    # below, so a layer the estimate cannot see (runtime filters, nibble swaps) still cannot OOM the host.
    budget = HostRamBudget(
        path,
        f"expanding its quantized weights to {str(dtype).replace('torch.', '')}",
        logger,
        # The fp8-storage rule chose to widen this load: refuse against its reserve, and only if fp8 layers widen.
        fp8_widen_chosen = bool(fp8_widen_chosen)
        and not fp8_storage
        and any(
            layer.format in FP8_FORMATS and _widened.get(layer.name + ".weight")
            for layer in scan.layers.values()
        ),
    )
    budget.check(
        converted_host_bytes(
            path,
            dtype,
            keep_fp32 = keep_fp32 if fp16_keep else (),
            dequantized = _widened.get,
            keep_key = keep_key,
        )
        + _stored_scale_bytes
    )
    budget.activate()
    sources: list = []  # (layer, codes, scale, block extras or None) kept for a runtime
    dequantized = 0
    for layer in scan.layers.values():
        codes = state.pop(layer.name + ".weight")
        scale = state.pop(layer.name + ".weight_scale")
        if layer.packed_int4:
            codes = unpack_int4_rows(codes)
        # int8 / fp8 / mxfp8 activations are quantized per call; only nvfp4 uses its static input_scale.
        input_scale = state.pop(layer.name + ".input_scale", None)
        extra = None
        if layer.format in BLOCK_SIZES:
            tensor_scale = state.pop(layer.name + ".weight_scale_2", None)
            extra = {
                "tensor_scale": None
                if tensor_scale is None
                else float(tensor_scale.float().reshape(-1)[0]),
                "input_scale": None
                if input_scale is None
                else float(input_scale.float().reshape(-1)[0]),
                "pre_quant_scale": state.pop(layer.name + ".pre_quant_scale", None),
            }
            codes, scale = decode_layer(layer.format, codes, scale)
        elif layer.format in FP8_FORMATS and codes.dtype == torch.uint8:
            codes = codes.view(getattr(torch, layer.format))
        # A key-mapped (original-layout) family moves rows whole, which the tiled block scales do not survive.
        if (
            backends.get(layer.format)
            or fp16_keep
            or (fp8_storage and layer.format in FP8_FORMATS)
            or (packed and extra is not None and packed_block_runs_on(layer.format, target))
        ) and not (extra is not None and key_map is not None):
            sources.append((layer, codes, scale, extra))
            state[layer.name + ".weight"] = None  # placeholder, tagged below
        elif extra is not None:
            state[layer.name + ".weight"] = _dequant_parts(
                layer.format, [(codes, scale, extra)], dtype
            )
            dequantized += 1
        else:
            state[layer.name + ".weight"] = _dequant(codes, scale, layer.group, dtype)
            dequantized += 1

    for key, value in list(state.items()):
        if value is None or not value.is_floating_point():
            continue
        wanted_dtype = keep_dtype(key) if keep_dtype is not None else None
        if wanted_dtype is not None:
            charge_cast(value, wanted_dtype)
            state[key] = value.to(wanted_dtype)
            continue
        if fp16_keep or value.dtype == dtype:
            continue
        charge_cast(value, dtype)
        state[key] = value.to(dtype)
    from accelerate import init_empty_weights

    mapping_fn, sfm = _mapping(transformer_cls) if key_map is None else (None, None)
    config_repo = kwargs.pop("config", None)
    subfolder = kwargs.pop("subfolder", None)
    token = kwargs.pop("token", None)
    cache_dir = kwargs.pop("cache_dir", None)
    local_files_only = bool(kwargs.pop("local_files_only", False))
    if not isinstance(config_repo, str):
        raise ValueError("a ComfyUI-quantized single file needs the base repo's transformer config")
    from .diffusion_families import pinned_revision_kwargs

    kwargs.pop("revision", None)  # the pin below is keyed on config_repo itself
    config = transformer_cls.load_config(
        config_repo,
        subfolder = subfolder,
        token = token,
        cache_dir = cache_dir,
        local_files_only = local_files_only,
        **pinned_revision_kwargs(config_repo),
    )
    expected, optional = transformer_cls._get_signature_keys(transformer_cls)
    config.update({k: v for k, v in kwargs.items() if k in expected or k in optional})
    with init_empty_weights():
        model = transformer_cls.from_config(config)
    if prepare_model is not None:
        prepare_model(model)
    wanted = model.state_dict()

    def _convert_tagged(width: Optional[int]) -> dict:
        # float64 row tags, ``width`` columns wide (None: real width); converted tags name each output's source rows.
        for index, (layer, codes, *_rest) in enumerate(sources):
            rows = torch.arange(codes.shape[0], dtype = torch.float64) + index * _TAG
            cols = codes.shape[1] if width is None else width
            state[layer.name + ".weight"] = rows.view(-1, 1).expand(codes.shape[0], cols)
        checkpoint = pre_convert(dict(state)) if pre_convert is not None else state
        if sfm._should_convert_state_dict_to_diffusers(wanted, checkpoint):
            out = mapping_fn(
                config = config,
                checkpoint = dict(checkpoint),
                **sfm._get_mapping_function_kwargs(mapping_fn, **kwargs),
            )
        else:
            out = dict(checkpoint)
        for name in [k for k, v in out.items() if torch.is_tensor(v) and v.dtype == torch.float64]:
            segments = _decode_rows(name, out[name], sources, width = width)
            kinds = {(sources[i][0].format, sources[i][0].group) for i, _r, _n in segments}
            if len(kinds) != 1:
                raise ValueError(f"{name}: rows from layers of different formats or ConvRot groups")
            fmt, group = kinds.pop()
            if fmt in BLOCK_SIZES:
                blocks = [
                    (sources[i][1][r : r + n], sources[i][2][r : r + n], sources[i][3])
                    for i, r, n in segments
                ]
                logical = (sum(n for _i, _r, n in segments), logical_cols(fmt, blocks[0][0]))
                if name in wanted and tuple(wanted[name].shape) != logical:
                    raise ValueError(
                        f"{name}: rebuilt as {logical}, the model expects {tuple(wanted[name].shape)}"
                    )
                out[name] = _BlockWeight(fmt, blocks)
                continue
            parts = [sources[i][1][r : r + n] for i, r, n in segments]
            scale_parts = [
                sources[i][2].reshape(-1, 1).expand(sources[i][1].shape[0], 1)[r : r + n]
                for i, r, n in segments
            ]
            # one segment (a split or renamed layer) is a row slice of a contiguous tensor: no copy; a
            # reorder (a stock converter swapping gate / proj halves) is a full copy of the kept codes
            charge_host_ram((_nbytes(parts) if len(parts) > 1 else 0) + _nbytes(scale_parts))
            codes = parts[0] if len(parts) == 1 else torch.cat(parts)
            scale = torch.cat(scale_parts)
            if name in wanted and tuple(wanted[name].shape) != tuple(codes.shape):
                raise ValueError(
                    f"{name}: rebuilt as {tuple(codes.shape)}, the model expects {tuple(wanted[name].shape)}"
                )
            out[name] = (codes, scale, group, fmt)
        return out

    if key_map is not None:
        # Rows move whole (no float64 tags: a 21 GB file would need ~5x that in tags)
        converted = _apply_key_map(state, sources, key_map)
        for name, value in converted.items():
            if isinstance(value, tuple) and name in wanted:
                if tuple(wanted[name].shape) != tuple(value[0].shape):
                    raise ValueError(
                        f"{name}: rebuilt as {tuple(value[0].shape)}, the model expects {tuple(wanted[name].shape)}"
                    )
    else:
        try:
            # Narrow tags first (full width is slow on a large DiT); anything unproven reruns at full width.
            converted = _convert_tagged(_NARROW_TAG_COLUMNS if sources else None)
        except HostRamShortfallError:
            raise  # a refusal, not an unproven tag: the full-width retry would only allocate more
        except Exception:  # noqa: BLE001 -- the full-width pass raises the real refusal
            # Full-width float64 tags are views, but a converter that joins or splits rows materializes them
            # (8 bytes per weight element) before any checked helper runs: check that before retrying.
            charge_host_ram(8 * sum(int(codes.numel()) for _layer, codes, *_rest in sources))
            converted = _convert_tagged(None)
    del state
    if fp16_keep:
        for key, value in list(converted.items()):
            if torch.is_tensor(value) and value.is_floating_point():
                charge_cast(value, _dtype_for(key))
                converted[key] = value.to(_dtype_for(key))

    min_features = DEFAULT_MIN_LINEAR_FEATURES if min_features is None else int(min_features)
    schemes = {INT8_TENSORWISE: TQ_INT8, FP8_E4M3: TQ_FP8, NVFP4: TQ_NVFP4, MXFP8: TQ_MXFP8}
    filters = {
        fmt: make_filter_fn(
            min_features,
            exclude_name_tokens = exclude_tokens_for_scheme(scheme, family, baked = True),
            require_divisible = divisible_for_scheme(scheme),
        )
        for fmt, scheme in schemes.items()
    }
    modules = dict(model.named_modules())
    rotations: dict = {}
    native: dict = {}
    stored: dict = {}  # fqn -> (codes, scale)
    block_native: dict = {}  # fqn -> (fmt, codes, scale, tensor_scale, input_scale, bias)
    block_packed: dict = {}  # fqn -> (fmt, codes, scale, row_scale, pre_quant, bias)
    built = {TQ_INT8: 0, TQ_FP8: 0, TQ_NVFP4: 0, TQ_MXFP8: 0}
    for name, value in list(converted.items()):
        if isinstance(value, _BlockWeight):
            fmt = value.fmt
            fqn = name[: -len(".weight")] if name.endswith(".weight") else name
            module = modules.get(fqn)
            runtime = _block_runtime_args(value)
            if (
                backends.get(fmt) is not None
                and runtime is not None
                and isinstance(module, torch.nn.Linear)
                and name.endswith(".weight")
                and filters[fmt](module, fqn)
                and not any(m in fqn.split(".") for m in keep_fp32)
            ):
                codes, scale, tensor_scale, input_scale = runtime
                bias = converted.get(fqn + ".bias")
                if torch.is_tensor(bias):
                    bias = bias.to(dtype)
                block_native[fqn] = (fmt, codes, scale, tensor_scale, input_scale, bias)
                del converted[name]
                built[schemes[fmt]] += 1
            else:
                args = (
                    packed_block_args(value.parts)
                    if packed
                    and packed_block_runs_on(fmt, target)
                    and isinstance(module, torch.nn.Linear)
                    and name.endswith(".weight")
                    and _dtype_for(name) == dtype
                    and not any(m in fqn.split(".") for m in keep_fp32)
                    else None
                )
                if args is not None:
                    bias = converted.get(fqn + ".bias")
                    if torch.is_tensor(bias):
                        bias = bias.to(dtype)
                    block_packed[fqn] = (fmt, *args, bias)
                    del converted[name]
                    continue
                converted[name] = _dequant_parts(fmt, value.parts, _dtype_for(name))
                dequantized += 1
            continue
        if not isinstance(value, tuple):
            continue
        codes, scale, group, fmt = value
        scheme = schemes.get(fmt)
        backend = backends.get(fmt)
        fqn = name[: -len(".weight")] if name.endswith(".weight") else name
        module = modules.get(fqn)
        weight = None
        keep = (
            backend is not None
            and module is not None
            and name.endswith(".weight")
            and filters[fmt](module, fqn)
            # Studio's fp8 quant leaves the Linears a DiT keeps in fp32 (require_bf16) at full precision.
            and not (scheme == TQ_FP8 and any(m in fqn.split(".") for m in keep_fp32))
        )
        if keep:
            if backend == "native":
                native[fqn] = (codes, scale, group, scheme)
                del converted[name]
                built[scheme] += 1
                continue
            if scheme == TQ_INT8:
                weight = _int8_tensor(name, codes, scale, dtype)
            else:
                weight = _fp8_tensor(name, codes, scale, dtype, fast_accum)
        if (
            weight is None
            and fp8_storage
            and fmt in FP8_FORMATS
            and not group
            and isinstance(module, torch.nn.Linear)
            and name.endswith(".weight")
            and _dtype_for(name) == dtype
            and not any(m in fqn.split(".") for m in keep_fp32)
        ):
            # forward widen must match ``_dequant``
            stored[fqn] = (codes, scale.reshape(-1, 1).expand(codes.shape[0], 1))
            del converted[name]
            continue
        if weight is None:
            converted[name] = _dequant(codes, scale, group, _dtype_for(name))
            dequantized += 1
            continue
        converted[name] = weight
        built[scheme] += 1
        if group:
            rotations.setdefault(group, []).append(fqn)
    if len(rotations) > 1:
        raise ValueError(f"ConvRot groups {sorted(rotations)} in one checkpoint")

    def _install_native(model: Any) -> None:
        from .diffusion_native_quant import native_linear_class

        cls = native_linear_class()
        act_int8 = native_int8_act(target) if target is not None else False
        for fqn, (codes, scale, group, scheme) in native.items():
            parent_name, _, leaf = fqn.rpartition(".")
            parent = model.get_submodule(parent_name) if parent_name else model
            # the Linear supplies only shapes, compute dtype and bias (assigned from the checkpoint below)
            linear = getattr(parent, leaf).to(dtype)
            layer = cls(
                linear,
                scheme,
                act_int8 = act_int8 and scheme == TQ_INT8,
                rot_group = group,
                codes = codes,
                scale = scale,
            )
            setattr(parent, leaf, layer)
            converted[fqn + ".weight_q"] = layer.weight_q
            converted[fqn + ".weight_scale"] = layer.weight_scale
        for fqn, (codes, scale) in stored.items():
            parent_name, _, leaf = fqn.rpartition(".")
            parent = model.get_submodule(parent_name) if parent_name else model
            charge_host_ram(
                4 * int(codes.shape[0])
            )  # the fp32 row scale; the codes stay as read (a view)
            layer = cls(getattr(parent, leaf).to(dtype), TQ_FP8, codes = codes, scale = scale)
            setattr(parent, leaf, layer)
            converted[fqn + ".weight_q"] = layer.weight_q
            converted[fqn + ".weight_scale"] = layer.weight_scale
        for fqn, (fmt, codes, scale, tensor_scale, input_scale, bias) in block_native.items():
            parent_name, _, leaf = fqn.rpartition(".")
            parent = model.get_submodule(parent_name) if parent_name else model
            layer = build_runtime_linear(
                fmt,
                getattr(parent, leaf),
                codes,
                scale,
                tensor_scale = tensor_scale,
                input_scale = input_scale,
                bias = bias,
            )
            setattr(parent, leaf, layer)
            for buffer_name, buffer in layer.named_buffers(recurse = False):
                converted[f"{fqn}.{buffer_name}"] = buffer
        if block_packed:
            packed_cls = packed_block_linear_class()
        for fqn, (fmt, codes, scale, row_scale, pre_quant, bias) in block_packed.items():
            parent_name, _, leaf = fqn.rpartition(".")
            parent = model.get_submodule(parent_name) if parent_name else model
            linear = getattr(parent, leaf)
            layer = packed_cls(
                fmt,
                linear.in_features,
                linear.out_features,
                codes = codes,
                scale = scale,
                row_scale = row_scale,
                pre_quant = pre_quant,
                bias = bias,
                compute_dtype = dtype,
            )
            setattr(parent, leaf, layer)
            for buffer_name, buffer in layer.named_buffers(recurse = False):
                converted[f"{fqn}.{buffer_name}"] = buffer

    _install_native(model)
    missing, unexpected = model.load_state_dict(converted, strict = False, assign = True)
    ignore = getattr(model, "_keys_to_ignore_on_load_unexpected", None) or []
    if ignore:
        import re
        unexpected = [k for k in unexpected if not any(re.search(p, k) for p in ignore)]
    if missing:
        raise ValueError(
            f"{os.path.basename(path)} is missing {len(missing)} weight(s) of "
            f"{transformer_cls.__name__} after conversion (e.g. {missing[0]!r})"
        )
    if any(p.device.type == "meta" for p in model.parameters()) or any(
        b.device.type == "meta" for b in model.buffers()
    ):
        # Same rebuild the hosted prequant loader does for buffers made in __init__.
        model = transformer_cls.from_config(config)
        if prepare_model is not None:
            prepare_model(model)
        _install_native(model)
        model.load_state_dict(converted, strict = False, assign = True)
    loaded = set(converted)
    del converted
    # __init__ buffers follow the compute dtype except fp32 tables; checkpoint buffers keep theirs (H3 curve)
    for module_name, module in model.named_modules():
        if module_name in block_native or module_name in block_packed:
            continue  # fp32 scales / alpha the block kernels need; codes are not floating
        for buffer_name, buffer in list(module._buffers.items()):
            if (f"{module_name}.{buffer_name}" if module_name else buffer_name) in loaded:
                continue
            if is_fp32_init_table(module, buffer_name, buffer):
                continue
            if buffer is not None and buffer.is_floating_point():
                want = _dtype_for(f"{module_name}.{buffer_name}")
                if buffer.dtype != want:
                    module._buffers[buffer_name] = buffer.to(want)
    if unexpected and logger is not None:
        logger.warning(
            "diffusion.comfy_quant: %d checkpoint key(s) unused by %s (e.g. %s)",
            len(unexpected),
            transformer_cls.__name__,
            unexpected[0],
        )

    rotated: tuple = ()
    if rotations:
        from .diffusion_convrot import apply_activation_rotation, rotation_metadata

        group, fqns = next(iter(rotations.items()))
        rotated = apply_activation_rotation(model, rotation_metadata(group, fqns), logger = logger)
        device = getattr(target, "torch_device", None) or getattr(target, "device", None)
        if device is not None:
            try:
                from .diffusion_convrot import warm_rotation_cache
                warm_rotation_cache(model, device, dtype)
            except Exception:  # noqa: BLE001 -- only saves one recompile
                pass
    native_schemes = {v[3] for v in native.values()} | {
        schemes[v[0]] for v in block_native.values()
    }
    on_torchao = {s for s, count in built.items() if count and s not in native_schemes}
    if finalize:
        from .diffusion_transformer_quant import apply_small_m_padding, apply_zero_row_guard
        for scheme in sorted(on_torchao):
            apply_small_m_padding(model, scheme, family, logger = logger)
            apply_zero_row_guard(model, scheme, family, logger = logger)
    if any(built.values()):
        try:
            # the scheme the runtime treats this transformer as: the one most of its layers run
            model._unsloth_runtime_quant = max(built, key = lambda s: built[s])
        except Exception:  # noqa: BLE001 -- marker is best-effort
            pass
    if built[TQ_NVFP4]:
        try:
            model._unsloth_nvfp4_backend = nvfp4_backend
        except Exception:  # noqa: BLE001 -- marker is best-effort
            pass
        # per-model step-protect controller, as for Studio's own NVFP4 checkpoints
        from .diffusion_nvfp4_protect import attach_own_controller
        attach_own_controller(model)
    model.eval()
    convrot = len(rotated) + sum(1 for v in native.values() if v[2])
    if logger is not None:
        logger.info(
            "diffusion.comfy_quant: %s loaded from a ComfyUI checkpoint (%s): %d int8 layers kept as "
            "int8 (%s, %d ConvRot), %d fp8 layers kept as fp8 (%s), %d nvfp4 layers kept as nvfp4 (%s), "
            "%d mxfp8 layers kept as mxfp8 (%s), %d fp8 layers stored as fp8 and widened per layer to %s, "
            "%d nvfp4 / mxfp8 layers kept packed and widened per layer, %d layers dequantized to %s",
            transformer_cls.__name__,
            ", ".join(f"{k} x{v}" for k, v in sorted(scan.counts().items())),
            built[TQ_INT8],
            f"{int8_backend} runtime" if built[TQ_INT8] else "no int8 runtime",
            convrot,
            built[TQ_FP8],
            f"{fp8_backend} runtime" if built[TQ_FP8] else "no fp8 runtime",
            built[TQ_NVFP4],
            f"{nvfp4_backend} runtime" if built[TQ_NVFP4] else "no nvfp4 runtime",
            built[TQ_MXFP8],
            f"{mxfp8_backend} runtime" if built[TQ_MXFP8] else "no mxfp8 runtime",
            len(stored),
            str(dtype).replace("torch.", ""),
            len(block_packed),
            dequantized,
            str(dtype).replace("torch.", ""),
        )
    try:
        info = {
            "backend": int8_backend if built[TQ_INT8] else None,
            "int8": built[TQ_INT8],
            "convrot": convrot,
            "fp8_backend": fp8_backend if built[TQ_FP8] else None,
            "fp8": built[TQ_FP8],
            "dequantized": dequantized,
        }
        if stored:
            info["fp8_stored"] = len(stored)
            setattr(model, FP8_STORED_ATTR, len(stored))
        if block_packed:
            for fmt in (NVFP4, MXFP8):
                count = sum(1 for v in block_packed.values() if v[0] == fmt)
                if count:
                    info[f"{fmt}_packed"] = count
            setattr(model, PACKED_BLOCK_ATTR, len(block_packed))
        for fmt, backend in ((NVFP4, nvfp4_backend), (MXFP8, mxfp8_backend)):
            if scan.counts().get(fmt):
                info[f"{fmt}_backend"] = backend if built[schemes[fmt]] else None
                info[fmt] = built[schemes[fmt]]
        model._unsloth_comfy_quant = info
    except Exception:  # noqa: BLE001 -- diagnostic marker only
        pass
    return model