inline-core 1.2.61__tar.gz → 1.2.63__tar.gz

{inline_core-1.2.61 → inline_core-1.2.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: inline-core
-Version: 1.2.61
+Version: 1.2.63
 Summary: The generation engine behind Inline Studio.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.11
@@ -68,17 +68,24 @@ The generation engine behind Inline. It takes a typed node graph (JSON) and retu
 low-VRAM laptops up to multi-GPU machines that split a single image's sampling across GPUs (via
 xDiT). It is Inline Studio's built-in render backend.
 
-Models today: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow diffusion transformer and the model
-xDiT already supports, so the multi-GPU split works on it from the start; and **Krea 2** (Krea AI),
-a 12.9B single-stream MMDiT released as an undistilled RAW base plus an 8-step distilled Turbo.
-
-> Status: early, and running end to end against a stub engine. In place and tested: the graph engine,
-> the typed `/v1` HTTP + websocket API (durable runs, streamed progress, coalescing), the model-dir
-> scan, the device + memory policy (profiles, dtype, offload, int8), the low-level primitive node
-> vocabulary. The Z-Image loader is written and validates on a GPU.
-> Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler seam, with
-> the policy and IPC round-trip tested), and out-of-process custom nodes are built as seams but not
-> yet running on real hardware.
+Models today, all running locally on your own GPU: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow
+diffusion transformer and the model xDiT already supports, so the multi-GPU split works on it from the
+start; **Krea 2** (Krea AI), a 12.9B single-stream MMDiT released as an undistilled RAW base plus an
+8-step distilled Turbo; **FLUX.2** (Black Forest Labs); and **MiniMax H3**, which generates video and
+its soundtrack in a single pass.
+
+Core also runs the **LoRA trainer** behind Inline Studio's Trainer canvas, so the same engine that
+generates can fine-tune Z-Image, Krea 2, FLUX.2 and MiniMax H3 on your own images without a cloud
+step. Training is cheaper than generating: Krea 2 fits a 16GB card at 512px with a 4-bit base. Its
+dependencies sit behind the `training` extra. See the
+[LoRA training guide](https://inlinestudio.art/lora-training) for the measured VRAM table.
+
+> Status: the graph engine, the typed `/v1` HTTP + websocket API (durable runs, streamed progress,
+> coalescing), the model-dir scan, the device + memory policy (profiles, dtype, offload, int8), the
+> low-level primitive node vocabulary, the model runners above, and the LoRA trainer all run on real
+> hardware. Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler
+> seam, with the policy and IPC round-trip tested), and out-of-process custom nodes are built as
+> seams but are not yet exercised on real hardware.
 
 ## Engine design
 

{inline_core-1.2.61 → inline_core-1.2.63}/README.md

@@ -5,17 +5,24 @@ The generation engine behind Inline. It takes a typed node graph (JSON) and retu
 low-VRAM laptops up to multi-GPU machines that split a single image's sampling across GPUs (via
 xDiT). It is Inline Studio's built-in render backend.
 
-Models today: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow diffusion transformer and the model
-xDiT already supports, so the multi-GPU split works on it from the start; and **Krea 2** (Krea AI),
-a 12.9B single-stream MMDiT released as an undistilled RAW base plus an 8-step distilled Turbo.
-
-> Status: early, and running end to end against a stub engine. In place and tested: the graph engine,
-> the typed `/v1` HTTP + websocket API (durable runs, streamed progress, coalescing), the model-dir
-> scan, the device + memory policy (profiles, dtype, offload, int8), the low-level primitive node
-> vocabulary. The Z-Image loader is written and validates on a GPU.
-> Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler seam, with
-> the policy and IPC round-trip tested), and out-of-process custom nodes are built as seams but not
-> yet running on real hardware.
+Models today, all running locally on your own GPU: **Z-Image** (Alibaba Tongyi), a 6B rectified-flow
+diffusion transformer and the model xDiT already supports, so the multi-GPU split works on it from the
+start; **Krea 2** (Krea AI), a 12.9B single-stream MMDiT released as an undistilled RAW base plus an
+8-step distilled Turbo; **FLUX.2** (Black Forest Labs); and **MiniMax H3**, which generates video and
+its soundtrack in a single pass.
+
+Core also runs the **LoRA trainer** behind Inline Studio's Trainer canvas, so the same engine that
+generates can fine-tune Z-Image, Krea 2, FLUX.2 and MiniMax H3 on your own images without a cloud
+step. Training is cheaper than generating: Krea 2 fits a 16GB card at 512px with a 4-bit base. Its
+dependencies sit behind the `training` extra. See the
+[LoRA training guide](https://inlinestudio.art/lora-training) for the measured VRAM table.
+
+> Status: the graph engine, the typed `/v1` HTTP + websocket API (durable runs, streamed progress,
+> coalescing), the model-dir scan, the device + memory policy (profiles, dtype, offload, int8), the
+> low-level primitive node vocabulary, the model runners above, and the LoRA trainer all run on real
+> hardware. Cross-request batching, single-image multi-GPU (an xDiT worker group behind the sampler
+> seam, with the policy and IPC round-trip tested), and out-of-process custom nodes are built as
+> seams but are not yet exercised on real hardware.
 
 ## Engine design
 

{inline_core-1.2.61 → inline_core-1.2.63}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI name; the import package is `inline_core` (src/inline_core).
 name = "inline-core"
-version = "1.2.61"
+version = "1.2.63"
 description = "The generation engine behind Inline Studio."
 readme = "README.md"
 license = "GPL-3.0-or-later"

inline_core-1.2.63/scripts/minimax_h3_lora_check.py

@@ -0,0 +1,145 @@
+"""Render the same seed with and without a LoRA, and measure what changed.
+
+The question a unit test cannot answer: does an adapter trained by the Trainer actually reach the
+denoiser at generation time? A LoRA that changes nothing means the fuse silently missed its
+targets; one that produces noise means the training convention is wrong. Both pass a test suite.
+
+Two loads in one process, because the pipeline cache keys on the LoRA stack and evicting between
+them is the same path a user takes when they wire an adapter in.
+
+    cd core && PYTHONPATH=src .venv/bin/python scripts/minimax_h3_lora_check.py \
+        --lora ../outputs/.../skin-h3.safetensors "a close-up portrait ..."
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+logger = logging.getLogger("h3lora")
+OUT = Path(__file__).resolve().parents[2] / "outputs" / "minimax-h3-bench" / "lora-check"
+
+
+def _render(policy: Any, prompt: str, loras: tuple[Any, ...], args: Any) -> dict[str, Any]:
+    import torch
+
+    from inline_core.models import pipeline_runtime as rt
+    from inline_core.models.minimaxh3.pipeline import load_pipeline, render_staged
+    from inline_core.models.minimaxh3.runner import GRID
+    from inline_core.models.video_params import snap_canvas, snap_frames
+
+    width, height = snap_canvas(args.width, args.height, multiple=32, minimum=32)
+    frames = snap_frames(args.seconds, GRID)
+
+    started = time.perf_counter()
+    pipe = load_pipeline(policy, params={}, partition="fl2va", loras=loras)
+    load_s = round(time.perf_counter() - started, 1)
+
+    rt.reset_peak_vram()
+    started = time.perf_counter()
+    state = render_staged(
+        pipe, policy.placement("denoiser").device,
+        prompt=prompt, num_frames=frames, height=height, width=width,
+        num_inference_steps=args.steps, output_type="pil",
+        generator=torch.Generator(device="cpu").manual_seed(args.seed),
+    )
+    return {
+        "load_s": load_s,
+        "generate_s": round(time.perf_counter() - started, 1),
+        "videos": state.get("videos"),
+        "audio": state.get("audio"),
+        "sampling_rate": state.get("sampling_rate"),
+        "frames": frames,
+        "size": (width, height),
+    }
+
+
+def _difference(a: Any, b: Any) -> dict[str, float]:
+    """Mean absolute pixel difference between two clips, in 0-255 units."""
+    import numpy as np
+
+    left = np.stack([np.asarray(f, dtype=np.float32) for f in a])
+    right = np.stack([np.asarray(f, dtype=np.float32) for f in b])
+    delta = np.abs(left - right)
+    return {
+        "mean_abs": round(float(delta.mean()), 4),
+        "max_abs": round(float(delta.max()), 2),
+        "changed_fraction": round(float((delta > 1.0).mean()), 4),
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("prompt")
+    parser.add_argument("--lora", required=True)
+    parser.add_argument("--strength", type=float, default=1.0)
+    parser.add_argument("--label", default="lora-check")
+    parser.add_argument("--width", type=int, default=608)
+    parser.add_argument("--height", type=int, default=352)
+    parser.add_argument("--seconds", type=float, default=5.0)
+    parser.add_argument("--steps", type=int, default=20)
+    parser.add_argument("--seed", type=int, default=1234)
+    args = parser.parse_args()
+
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(message)s", datefmt="%H:%M:%S")
+
+    from inline_core.device.memory import MemoryPolicy
+    from inline_core.graph.loader_runners import LoraRef
+    from inline_core.models.minimaxh3.runner import GRID
+    from inline_core.runtime.video_encode import encode_video_file
+
+    out = OUT.parent / args.label
+    out.mkdir(parents=True, exist_ok=True)
+    policy = MemoryPolicy()
+    record: dict[str, Any] = {"prompt": args.prompt, "seed": args.seed, "steps": args.steps}
+
+    # Base first, so the LoRA'd load is the one that has to evict a live pipeline - which is what a
+    # user does when they wire an adapter into a node they have already rendered from.
+    logger.info("--- rendering WITHOUT the LoRA ---")
+    base = _render(policy, args.prompt, (), args)
+    record["without"] = {k: base[k] for k in ("load_s", "generate_s")}
+    encode_video_file(
+        out / "without-lora.mp4", base["videos"][0], fps=GRID.fps,
+        audio=base["audio"][0] if base["audio"] is not None and len(base["audio"]) else None,
+        sample_rate=base["sampling_rate"],
+    )
+
+    logger.info("--- rendering WITH the LoRA ---")
+    tuned = _render(policy, args.prompt, (LoraRef(file=args.lora, strength=args.strength),), args)
+    record["with"] = {k: tuned[k] for k in ("load_s", "generate_s")}
+    encode_video_file(
+        out / "with-lora.mp4", tuned["videos"][0], fps=GRID.fps,
+        audio=tuned["audio"][0] if tuned["audio"] is not None and len(tuned["audio"]) else None,
+        sample_rate=tuned["sampling_rate"],
+    )
+
+    record["difference"] = _difference(base["videos"][0], tuned["videos"][0])
+    record["lora"] = args.lora
+    record["strength"] = args.strength
+
+    # A few frames side by side, so the change can be looked at rather than only measured.
+    for index in (0, base["frames"] // 2, base["frames"] - 1):
+        base["videos"][0][index].save(out / f"frame{index:03d}-without.png")
+        tuned["videos"][0][index].save(out / f"frame{index:03d}-with.png")
+
+    (out / "result.json").write_text(json.dumps(record, indent=2))
+    print(json.dumps(record, indent=2))
+
+    delta = record["difference"]["mean_abs"]
+    if delta == 0.0:
+        print("\nFAIL: identical output - the LoRA reached nothing")
+        return 1
+    print(f"\nclips differ by {delta} mean absolute (0-255).")
+    print("Look at the frames before believing it.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

inline_core-1.2.63/scripts/minimax_h3_train_matrix.py

@@ -0,0 +1,206 @@
+"""VRAM + step-time sweep for MiniMax H3 LoRA training: the cells behind the README benchmark table.
+
+    cd core && PYTHONPATH=src .venv/bin/python scripts/minimax_h3_train_matrix.py --dataset <dir>
+
+One cell = one real run of `python -m inline_core.training`, the same entry point the Trainer tab
+spawns, so a number here is a number a user would see.
+
+Held fixed at the settings the other architectures' rows used: 12 steps, rank 16, batch 1, gradient
+checkpointing on. Only resolution varies, because H3 has a single base mode and is 4-bit only: its
+base is 40 GB after the AdaLN factorisation, so a bf16 cell would be measuring an OOM.
+
+The peak here is not the peak a user waits on. H3 encodes latents and captions in two passes that
+never overlap the base, and the conditioner pass is the tallest of the three, so the run's
+high-water mark is set before training starts. Both are reported.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+
+_REPO = Path(__file__).resolve().parent.parent.parent
+_CORE = _REPO / "core"
+_DEFAULT_OUT = _REPO / "outputs" / "minimax-h3-bench" / "train"
+
+#: Resolutions to sweep. 512 is the practical setting; 768 matches H3's own short edge at inference.
+CELLS: tuple[int, ...] = (512, 768)
+
+_STEPS = 12
+_RANK = 16
+
+
+def _manifest(
+    work: Path, dataset: Path, models: Path, resolution: int, steps: int = _STEPS
+) -> Path:
+    """The same manifest shape `studio/training.py::_prepare` writes."""
+    checkpoints = work / "checkpoints"
+    checkpoints.mkdir(parents=True, exist_ok=True)
+    manifest = {
+        "runId": work.name,
+        "workingDir": str(work),
+        "datasetDir": str(dataset),
+        "checkpointDir": str(checkpoints),
+        "outputPath": str(work / "lora.safetensors"),
+        "resumeFrom": None,
+        "modelsDir": str(models),
+        "arch": "minimax-h3",
+        # H3 ships one undistilled build per partition; `raw` is that mode's key.
+        "baseMode": "raw",
+        "triggerWord": "",
+        "hyperparams": {
+            "arch": "minimax-h3",
+            "baseMode": "raw",
+            "baseQuant": "auto",
+            "offload": "off",
+            "loraScope": "full",
+            "captionDropout": 0.0,
+            "flipAugment": False,
+            "rank": _RANK,
+            "alpha": _RANK,
+            "learningRate": 1e-4,
+            "batchSize": 1,
+            "steps": steps,
+            "saveEvery": steps,
+            "resolution": resolution,
+        },
+        "gpuIds": [],
+    }
+    path = work / "manifest.json"
+    path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return path
+
+
+def _run_cell(python: str, manifest: Path, log: Path) -> dict[str, object]:
+    """Drain the JSON-line protocol, keeping the VRAM readings and the step timing.
+
+    The precache peak is read from the progress lines before the first training step; the training
+    peak is the last reading. They are different numbers on H3 and conflating them would overstate
+    what training itself costs.
+    """
+    env = {**os.environ, "PYTHONPATH": str(_CORE / "src")}
+    proc = subprocess.Popen(
+        [python, "-m", "inline_core.training", str(manifest)],
+        cwd=str(_CORE),
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+    vram: float | None = None
+    error: str | None = None
+    first_step_at: float | None = None
+    last_step_at: float | None = None
+    steps_seen = 0
+    losses: list[float] = []
+    started = time.perf_counter()
+    lines: list[str] = []
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        lines.append(line)
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            message = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        kind = message.get("type")
+        if kind == "progress":
+            if message.get("vram") is not None:
+                vram = float(message["vram"])
+            if message.get("loss") is not None:
+                losses.append(float(message["loss"]))
+            if message.get("step"):
+                steps_seen = int(message["step"])
+                now = time.perf_counter()
+                if first_step_at is None:
+                    first_step_at = now
+                last_step_at = now
+        elif kind == "error":
+            error = str(message.get("message") or "")
+    proc.wait()
+    log.write_text("".join(lines), encoding="utf-8")
+
+    oom = bool(error) and ("out of gpu memory" in error.lower() or "out of memory" in error.lower())
+    # Step 1 pays for the first graph build, so time the interval after it and scale by the gap.
+    per_step: float | None = None
+    if first_step_at is not None and last_step_at is not None and steps_seen > 1:
+        per_step = (last_step_at - first_step_at) / (steps_seen - 1)
+    return {
+        "peak_vram_gb": vram,
+        "seconds_per_step": round(per_step, 2) if per_step else None,
+        "seconds_12_steps": round(per_step * _STEPS, 1) if per_step else None,
+        "total_seconds": round(time.perf_counter() - started, 1),
+        "steps_completed": steps_seen,
+        "first_loss": round(losses[0], 4) if losses else None,
+        "last_loss": round(losses[-1], 4) if losses else None,
+        "status": "oom" if oom else ("ok" if proc.returncode == 0 else "failed"),
+        "error": error,
+        "log": log.name,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dataset", type=Path, required=True, help="dir of NNNN.jpg + NNNN.txt")
+    parser.add_argument("--out", type=Path, default=_DEFAULT_OUT)
+    parser.add_argument("--models", type=Path, default=_CORE / "models")
+    parser.add_argument("--python", default=str(_CORE / ".venv" / "bin" / "python"))
+    parser.add_argument("--gpu", default="", help="label for the results file, e.g. 'L40S (46GB)'")
+    parser.add_argument("--only", default="", help="one resolution, to redo a single row")
+    parser.add_argument("--steps", type=int, default=_STEPS, help="override for a smoke run")
+    args = parser.parse_args()
+
+    if not args.dataset.is_dir():
+        raise SystemExit(f"dataset not found: {args.dataset}")
+
+    args.out.mkdir(parents=True, exist_ok=True)
+    results_path = args.out / "results.json"
+    results: dict[str, dict[str, object]] = {}
+    if results_path.exists():
+        results = json.loads(results_path.read_text()).get("cells", {})
+
+    label = args.gpu
+    if not label:
+        try:
+            label = subprocess.run(
+                ["nvidia-smi", "--query-gpu=name,memory.total", "--format=csv,noheader"],
+                capture_output=True, text=True, check=True,
+            ).stdout.strip().splitlines()[0]
+        except Exception:  # noqa: BLE001 - the label is cosmetic
+            label = "unknown GPU"
+
+    def write() -> None:
+        results_path.write_text(
+            json.dumps(
+                {"gpu": label, "steps": _STEPS, "rank": _RANK, "cells": results}, indent=2
+            )
+        )
+
+    for resolution in CELLS:
+        cell_id = str(resolution)
+        if args.only and args.only != cell_id:
+            continue
+        work = args.out / cell_id
+        work.mkdir(parents=True, exist_ok=True)
+        manifest = _manifest(work, args.dataset, args.models, resolution, args.steps)
+        print(f"--- {cell_id}px, 4-bit base ---", flush=True)
+        result = _run_cell(args.python, manifest, args.out / f"{cell_id}.log")
+        result.update({"resolution": resolution, "base_quant": "nf4"})
+        results[cell_id] = result
+        print(json.dumps(result, indent=2), flush=True)
+        write()
+
+    write()
+    print(f"\n{results_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{inline_core-1.2.61 → inline_core-1.2.63}/src/inline_core/device/memory.py

@@ -302,8 +302,9 @@ class MemoryPolicy(DevicePolicy):
 
         **int8 overrides the fp16 preference to bf16.** torchao weight-only int8 only supports a
         bf16 compute dtype - with fp16 the quantization silently no-ops, so the "int8" weights load
-        at *full* fp16 size and blow the VRAM budget (a T4 then OOMs mid-load). The int8 matmul still
-        runs on the card's int8 tensor cores; only the residual bf16 activations pay the slow path.
+        at *full* fp16 size and blow the VRAM budget (a T4 then OOMs mid-load). The int8 matmul
+        still runs on the card's int8 tensor cores; only the residual bf16 activations pay the
+        slow path.
         bf16 also has fp32's exponent range, so the VAE no longer needs the fp32 anti-overflow
         upcast - it rides along at bf16."""
         if self.quantization() is Quantization.INT8:

{inline_core-1.2.61 → inline_core-1.2.63}/src/inline_core/models/minimaxh3/adaln.py

@@ -17,9 +17,17 @@ factorisation from the bf16 weights instead, which means:
   needs snapping or interpolation. Projecting a continuous ``t`` through the basis is exact for any
   timestep, so the sampler is unconstrained.
 
-Verified against their published tables: our factorisation reproduces the full-precision modulation
-to 1.1e-4 relative error, theirs to 2e-4, and the two span the same subspace (principal angles 1.0
-for the seven directions that carry any energy).
+Their tables are **not** compared against; nothing here reads their ``convrot`` build. What is
+measured is this factorisation against the unfactorised weights: it perturbs the modulation by
+1.095e-4 relative, where one bf16 ulp of re-rounding moves it 1.530e-3, so the change sits a factor
+of fourteen below the ambiguity the checkpoint's own storage already carries.
+``scripts/minimax_h3_adaln_gate.py`` computes both and renders the same seed each way; its numbers
+land in ``outputs/minimax-h3-bench/adaln-gate/``.
+
+Note the pixel measure disagrees in direction and is not settled: the rendered clips differ by
+0.0385 mean absolute against 0.0258 for that same one-ulp perturbation. Low-rank truncation is
+systematic where rounding is not, so it can compound across the 50 blocks and every step in a way
+the modulation figure does not capture. The gate ran at 8 steps against production's 20.
 
 The vendored port is **not** edited for this. The factorised module is swapped in after the model is
 built, so ``vendor/`` stays verbatim.

{inline_core-1.2.61 → inline_core-1.2.63}/src/inline_core/models/minimaxh3/load.py

@@ -21,6 +21,7 @@ import torch
 from safetensors import safe_open
 
 from ...errors import ComponentError
+from .. import lora as lora_module
 from ..keymap import (
     AssertEqual,
     Rename,
@@ -108,12 +109,16 @@ def load_transformer(
     device: str = "cpu",
     layout: RowLayout | None = None,
     shrink: Any = None,
+    loras: tuple[Any, ...] = (),
 ) -> MiniMaxH3Transformer3DModel:
     """Build the port and stream ``path`` into it through the key plan.
 
     ``layout`` overrides the measurement, which is only useful in tests; leave it None so the file
     decides. ``shrink(model, prefix)`` is called as each transformer block finishes, which is how a
     64 GB machine loads a model whose bf16 footprint is 66 GB.
+
+    ``loras`` are fused into each block as it lands, **before** ``shrink`` factorises or quantises
+    it, because a fuse adds a full-precision delta that quantized weights cannot accept in place.
     """
     if not path.is_file():
         raise ComponentError(f"MiniMax H3 transformer not found: {path}")
@@ -121,6 +126,12 @@ def load_transformer(
     with torch.device("meta"):
         model = MiniMaxH3Transformer3DModel(**transformer_kwargs(config))
 
+    # Resolved against module names on the meta model, so a LoRA trained for another architecture
+    # is refused before the 62 GB read rather than a block into it.
+    lora_plan = lora_module.plan_loras(model, loras) if loras else {}
+    fused: set[str] = set()
+    shrink = _fusing_shrink(lora_plan, fused, shrink) if lora_plan else shrink
+
     with safe_open(str(path), framework="pt") as handle:
         source_keys = list(handle.keys())  # noqa: SIM118 - safe_open has no __contains__
         if _PROBE_KEY not in source_keys:
@@ -144,11 +155,61 @@ def load_transformer(
             model, handle, plan, dtype=dtype, device=device, shrink=shrink
         )
 
+    if lora_plan:
+        _finish_fuse(model, lora_plan, fused)
     _assert_nothing_left_on_meta(model, filled)
     model.eval()
     return model
 
 
+def _fusing_shrink(plan: Any, fused: set[str], inner: Any) -> Any:
+    """Fuse a block's share of the LoRA stack the moment it lands, then hand off to ``shrink``.
+
+    The only window that works: after the stream the weights exist, before ``shrink`` they are
+    still unquantised, and a full-precision delta cannot be added to a quantised weight.
+    """
+
+    def shrink(model: Any, prefix: str) -> None:
+        module = model
+        for part in prefix.split("."):
+            module = module[int(part)] if part.isdigit() else getattr(module, part)
+        fused.update(_fuse_subtree(module, plan, f"{prefix}."))
+        if inner is not None:
+            inner(model, prefix)
+
+    return shrink
+
+
+def _fuse_subtree(module: Any, plan: Any, prefix: str) -> set[str]:
+    """Apply the plan's share for one subtree, reporting which of its targets were covered."""
+    hit = {
+        path
+        for name, _child in module.named_modules()
+        if (path := f"{prefix}{name}" if prefix else name) in plan
+    }
+    lora_module.apply_plan(module, plan, prefix)
+    return hit
+
+
+def _finish_fuse(model: Any, plan: Any, fused: set[str]) -> None:
+    """Fuse what the block callback never saw, then prove nothing was missed.
+
+    The callback fires only for ``transformer_blocks.N``, so ``context_embedder`` and the token
+    refiner would keep their base weights. ``plan_loras`` raises only when a key matches *no*
+    module, and these exist, so a partial fuse validates clean and then degrades output silently.
+    """
+    residual = {name: deltas for name, deltas in plan.items() if name not in fused}
+    if residual:
+        fused |= _fuse_subtree(model, residual, "")
+    missed = sorted(set(plan) - fused)
+    if missed:
+        raise ComponentError(
+            f"{len(missed)} LoRA layers resolved to modules that were never fused, starting with "
+            f"{missed[0]}. Applying only part of a LoRA degrades output without erroring, so this "
+            "is refused instead."
+        )
+
+
 def _source_for(layout: RowLayout) -> str:
     for name, known in h3keys.SOURCE_LAYOUTS.items():
         if known is layout: