lesiondiffusion-mlx 0.2.1__py3-none-any.whl

lesiondiffusion_mlx/medmlx.py

@@ -0,0 +1,1764 @@
+"""MedMLX file runner for the pinned upstream LMNet and LINet pipeline.
+
+``run`` takes a CT and an organ mask as NIfTI files, standardizes them to a RAS 1 mm
+grid, and writes a CT with one synthetic lesion plus the lesion and organ masks.
+The helpers below it cover weight loading, option parsing, geometry, box placement,
+and output writing. Research software: outputs are synthetic and need human review.
+"""
+
+from __future__ import annotations
+
+import gc
+import json
+import math
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime
+from os import PathLike
+from pathlib import Path
+from typing import TYPE_CHECKING, Final, Literal, TypedDict, cast
+
+import numpy as np
+from medmlx_core.errors import (
+    AssetNotReadyError,
+    InvalidInputError,
+    MedmlxError,
+    ModelExecutionError,
+)
+from medmlx_core.runtime import import_mlx
+
+from lesiondiffusion_mlx._arrays import BoolArray, FloatArray, HostArray, NumericArray
+from lesiondiffusion_mlx._nifti import ImageFileError, NiftiImage, nib
+from lesiondiffusion_mlx._typing import ArrayConstructor
+
+if TYPE_CHECKING:
+    from lesiondiffusion_mlx._typing import Array, Dtype, Mlx
+
+from lesiondiffusion_mlx.mlx_model import (
+    LINET_CONFIG,
+    LMNET_CONFIG,
+    BiomedTextEncoder,
+    LdmUnet,
+    VqAutoencoder,
+)
+from lesiondiffusion_mlx.mlx_pipeline import (
+    LINET_CROP,
+    LMNET_CROP,
+    encode_attributes,
+    encode_source,
+    piecewise_ct,
+    ras_to_source,
+    source_crop,
+    source_to_ras,
+)
+from lesiondiffusion_mlx.mlx_sampling import DdimSampler, lesion_diffusion_timesteps
+
+MODEL_ID: Final = "lesiondiffusion"
+DEFAULT_DIFFUSION_STEPS: Final = 200
+DEFAULT_SEED: Final = 23
+DEFAULT_INFERENCE_MODE: Final = "conditioned"
+DEFAULT_OUTPUT_REGION: Final = "full"
+# Cosine feather width (mm) for ``output_region="box"``: the generated box is kept,
+# blended into the input CT over this margin, and every farther voxel stays exact.
+LOCALIZATION_MARGIN_MM: Final = 6.0
+_REFERENCE: Final = json.loads(Path(__file__).with_name("reference.json").read_text())
+SOURCE_REF: Final = _REFERENCE["revision"]
+CONVERSION_SCHEMA: Final = "medmlx.lesiondiffusion.weights.v1"
+CONVERSION_VERSION: Final = 1
+CONVERTED_FILES: Final = ("lmnet.npz", "linet.npz", "vq.npz", "lmnet_text.npz", "linet_text.npz")
+SOURCE_INFERENCE_FILES: Final = tuple(name for name in CONVERTED_FILES if name != "linet_text.npz")
+TOKENIZER_FILE: Final = "tokenizer.json"
+CONVERSION_FILE: Final = "conversion.json"
+WARNING: Final = (
+    "Synthetic lesion output requires human review and is not patient data or ground truth."
+)
+WEIGHTS_HINT: Final = (
+    "Convert explicit upstream checkpoints with scripts/convert_weights.py; "
+    "weights_path must contain safetensors or NPZ stages, tokenizer.json and conversion.json."
+)
+
+# Canonical labels match upstream organ_type.json and its inference vocabulary.
+SOURCE_ORGAN_LABELS: Final[dict[str, tuple[int, str]]] = {
+    name.lower().replace(" ", "_"): (int(label), name)
+    for label, name in _REFERENCE["organ_labels"].items()
+}
+# Hollow organs for box placement, as in upstream preprocessing. The cavity phrase in
+# _lmnet_attributes follows upstream's inference code, whose set also has gallbladder.
+_HOLLOW_ORGANS = frozenset({"colon", "stomach", "esophagus", "urinary_bladder"})
+_CAVITY_TEXT = {
+    "inside_parenchyma": "within the parenchymal organ",
+    "protruding_from_parenchyma": "protruding from the parenchymal organ",
+    "within_lumen": "within the lumen of a hollow organ",
+    "wall_thickening": "wall thickening",
+}
+
+_SYNTHETIC_CT = "synthetic_ct.nii.gz"
+_RAW_SYNTHETIC_CT = "raw_synthetic_ct.nii.gz"
+_LESION_MASK = "lesion_mask.nii.gz"
+_ORGAN_MASK = "organ_mask.nii.gz"
+
+MODEL: Final[dict[str, str]] = {
+    "id": MODEL_ID,
+    "label": "LesionDiffusion CT lesion insertion",
+    "task": "generation",
+    "run": "lesiondiffusion_mlx.medmlx:run",
+    "summary": (
+        "Insert one mask-generating, phenotype-controlled synthetic lesion into an "
+        "aligned 1 mm RAS CT, given a binary organ mask."
+    ),
+}
+
+
+class NativeRuntime(TypedDict):
+    """Runtime facts recorded under ``details.generation_spec.native_runtime``.
+
+    Covers device, per-stage compute dtypes, the inference mode and the arithmetic it
+    selects, the text attributes sent to each network, per-stage records, and a
+    plain-language statement of what a seed reproduces.
+    """
+
+    conversion: dict[str, object]
+    device: str
+    dtype: dict[str, str]
+    inference_mode: str
+    convolution_arithmetic: str
+    lmnet_attempts: int
+    lmnet_conditioning: dict[str, object]
+    lmnet_anatomy_context: str
+    linet_conditioning: dict[str, object]
+    linet_skip_context: bool
+    lmnet_stage: dict[str, object]
+    linet_stage: dict[str, object]
+    model_organ_label: int
+    sampling: str
+    synchronization: str
+    seed_contract: str
+
+
+class GenerationSpec(TypedDict):
+    """Provenance of one lesion: box (voxel indices on the standardized grid), placement,
+    runtime facts and output checks.
+    """
+
+    schema_version: str
+    source_ref: str
+    bbox_center_voxel: list[int]
+    bbox_size_voxel: list[int]
+    placement: str
+    output_mapping: str
+    native_runtime: NativeRuntime
+    output_validation: dict[str, object]
+
+
+class RunDetails(TypedDict):
+    """JSON-safe record of one run; ``elapsed_s`` is seconds, ``started_at`` UTC ISO 8601."""
+
+    model_id: str
+    source_ref: str
+    organ: str
+    lesion_type: str
+    seed: int
+    diffusion_steps: int
+    generation_spec: GenerationSpec
+    stages: dict[str, dict[str, object]]
+    output_region: str
+    output_kind_by_role: dict[str, str]
+    output_shape_by_role: dict[str, list[int]]
+    output_dtype_by_role: dict[str, str]
+    output_labels_by_role: dict[str, list[dict[str, str | int]]]
+    weights_path: str
+    started_at: str
+    elapsed_s: float
+    requires_human_review: bool
+    warning: str
+
+
+class RunResult(TypedDict):
+    """Return value of ``run``.
+
+    ``outputs`` maps a role to a POSIX file path: ``synthetic_image``, ``target_mask``
+    and ``organ_mask``, plus ``raw_synthetic_image`` when ``output_region="box"``.
+    """
+
+    outputs: dict[str, str]
+    details: RunDetails
+
+
+type _PathArg = str | PathLike[str]
+
+
+@dataclass(frozen=True, slots=True)
+class LesionDiffusionOptions:
+    """Validated controls for one run.
+
+    ``organ`` is a key of ``SOURCE_ORGAN_LABELS``. ``bbox_size_mm`` is the box extent
+    (X, Y, Z) in mm along the standardized RAS axes, at least 2 mm each.
+    ``bbox_center_voxel`` is an optional (I, J, K) voxel index on that grid; when it is
+    ``None`` the box is placed from ``seed``. ``placement`` picks the placement rule and
+    the cavity phrase in the text. ``shape`` through ``specific_features`` are free
+    text for the upstream report. ``seed`` (0 to 2**32 - 1) seeds MT19937 box placement
+    and MLX sampling. ``inference_mode`` is ``"conditioned"`` or ``"source"`` and
+    ``output_region`` is ``"full"`` or ``"box"``; see ``run``.
+
+    Raises:
+        InvalidInputError: From construction, for any value outside these contracts.
+    """
+
+    organ: str
+    lesion_type: str
+    bbox_size_mm: tuple[float, float, float]
+    placement: str
+    shape: str = "irregular"
+    density: str = "hypodense lesion"
+    density_variation: str = "heterogeneous"
+    enhancement: str = "non-contrast CT"
+    surface: str = "ill-defined margin"
+    adjacent_relationship: str = "no close relationship with surrounding organs"
+    specific_features: str = ""
+    bbox_center_voxel: tuple[int, int, int] | None = None
+    diffusion_steps: int = DEFAULT_DIFFUSION_STEPS
+    seed: int = DEFAULT_SEED
+    inference_mode: str = DEFAULT_INFERENCE_MODE
+    output_region: str = DEFAULT_OUTPUT_REGION
+
+    def __post_init__(self) -> None:
+        if self.inference_mode not in {"conditioned", "source"}:
+            raise InvalidInputError("LesionDiffusion inference_mode must be conditioned or source")
+        if self.output_region not in {"full", "box"}:
+            raise InvalidInputError("LesionDiffusion output_region must be full or box")
+        if self.organ not in SOURCE_ORGAN_LABELS:
+            raise InvalidInputError(f"Unknown upstream organ: {self.organ}")
+        if not self.lesion_type.strip():
+            raise InvalidInputError("LesionDiffusion lesion_type must not be empty")
+        if len(self.bbox_size_mm) != 3:
+            raise InvalidInputError("LesionDiffusion bbox_size_mm must contain X, Y, Z")
+        for value in self.bbox_size_mm:
+            if not math.isfinite(value):
+                raise InvalidInputError("LesionDiffusion bbox_size_mm must be finite")
+            if value < 2:
+                raise InvalidInputError("LesionDiffusion bbox dimensions must be at least 2 mm")
+        if self.placement not in _CAVITY_TEXT:
+            raise InvalidInputError(f"Unknown LesionDiffusion placement: {self.placement}")
+        for name, value in (
+            ("shape", self.shape),
+            ("density_variation", self.density_variation),
+            ("density", self.density),
+            ("enhancement", self.enhancement),
+            ("surface", self.surface),
+            ("adjacent_relationship", self.adjacent_relationship),
+        ):
+            if not value.strip():
+                raise InvalidInputError(f"LesionDiffusion {name} must not be empty")
+        if self.bbox_center_voxel is not None:
+            if len(self.bbox_center_voxel) != 3:
+                raise InvalidInputError("LesionDiffusion bbox_center_voxel must contain I, J, K")
+            if any(not _is_integer(value) for value in self.bbox_center_voxel):
+                raise InvalidInputError("LesionDiffusion bbox_center_voxel values must be integers")
+            if any(value < 0 for value in self.bbox_center_voxel):
+                raise InvalidInputError("LesionDiffusion bbox_center_voxel must not be negative")
+        if not _is_integer(self.diffusion_steps):
+            raise InvalidInputError("LesionDiffusion diffusion_steps must be an integer")
+        try:
+            lesion_diffusion_timesteps(self.diffusion_steps)
+        except ValueError as exc:
+            raise InvalidInputError(str(exc)) from exc
+        if not _is_integer(self.seed):
+            raise InvalidInputError("LesionDiffusion seed must be an integer")
+        if self.seed < 0:
+            raise InvalidInputError("LesionDiffusion seed must not be negative")
+        if self.seed >= 2**32:
+            raise InvalidInputError("LesionDiffusion seed must be less than 2**32 for MT19937")
+
+
+@dataclass(frozen=True, slots=True)
+class _Geometry:
+    """Standardized inputs shared by every stage.
+
+    ``reference`` and the arrays are on the even-padded RAS 1 mm grid the networks use;
+    ``output_reference`` is the unpadded standardized grid that outputs are cropped
+    back to. ``bbox_mask`` is uint8 with 2 inside the box. ``center`` is the box
+    center (I, J, K) and ``bbox_size_voxel`` its nominal size; the box spans
+    ``size // 2`` voxels on each side of the center.
+    """
+
+    reference: NiftiImage
+    output_reference: NiftiImage
+    source_data: NumericArray
+    organ_mask: BoolArray
+    organ_label: int
+    organ_source: dict[str, object]
+    bbox_mask: HostArray
+    bbox_size_voxel: tuple[int, int, int]
+    center: tuple[int, int, int]
+    anatomy_mask: HostArray | None = None
+
+
+def run(
+    *,
+    image_path: _PathArg,
+    organ_mask_path: _PathArg,
+    anatomy_mask_path: _PathArg | None = None,
+    output_dir: _PathArg,
+    weights_path: _PathArg,
+    organ: str,
+    lesion_type: str,
+    bbox_size_mm: Sequence[float],
+    placement: str,
+    shape: str = "irregular",
+    density: str = "hypodense lesion",
+    density_variation: str = "heterogeneous",
+    enhancement: str = "non-contrast CT",
+    surface: str = "ill-defined margin",
+    adjacent_relationship: str = "no close relationship with surrounding organs",
+    specific_features: str = "",
+    bbox_center_voxel: Sequence[int] | None = None,
+    diffusion_steps: int = DEFAULT_DIFFUSION_STEPS,
+    seed: int = DEFAULT_SEED,
+    inference_mode: str = DEFAULT_INFERENCE_MODE,
+    output_region: str = DEFAULT_OUTPUT_REGION,
+    overwrite: bool = False,
+) -> RunResult:
+    """Insert one synthetic lesion into a CT and write NIfTI outputs.
+
+    LMNet generates a lesion mask inside a box, then LINet inpaints the CT latent under
+    that mask and the VQ decoder reconstructs the volume (upstream's v2 inpainting
+    route). CT intensities are taken as Hounsfield units. The CT and masks must be
+    axis-aligned grids; they are reoriented and resampled to RAS 1 mm (linear for the
+    CT, nearest for masks) and padded to even extents for the VQ stages, then outputs
+    are cropped back to that standardized grid, which is the input grid when the
+    input is already RAS 1 mm. The generated lesion is not constrained to the box or
+    the organ. Output is synthetic and needs human review.
+
+    Args:
+        image_path: 3-D CT, ``.nii`` or ``.nii.gz``, finite values in HU.
+        organ_mask_path: Binary organ mask (0 background, 1 organ) on the same grid
+            after standardization.
+        anatomy_mask_path: Optional multi-organ map with upstream TotalSegmentator v1
+            labels 0-104 on the same grid; its label for ``organ`` must equal the
+            binary mask. Without it LMNet sees only the target organ.
+        output_dir: Directory for the outputs, created if needed.
+        weights_path: Directory written by ``write_conversion``.
+        organ: Key of ``SOURCE_ORGAN_LABELS`` (lower-case name, spaces as underscores).
+        lesion_type: Free text such as ``"tumor"``. A selected LMNet component of at
+            most 400 voxels (50 if the text contains ``"stone"``) triggers one resample.
+        bbox_size_mm: Box extent (X, Y, Z) in mm, each at least 2.
+        placement: ``inside_parenchyma``, ``protruding_from_parenchyma``,
+            ``within_lumen`` or ``wall_thickening``. It guides automatic box placement
+            and, in ``conditioned`` mode, LINet's text. LMNet's cavity phrase is fixed
+            by organ and lesion type, as in the pinned inference path.
+        shape, density, density_variation, enhancement, surface,
+            adjacent_relationship, specific_features: Free-text phenotype for the
+            upstream report; empty strings are rejected except ``specific_features``.
+        bbox_center_voxel: Optional (I, J, K) box center on the standardized grid.
+        diffusion_steps: DDIM steps for both stages; must give a valid upstream
+            uniform schedule (see ``lesion_diffusion_timesteps``).
+        seed: Seeds box placement and native MLX sampling. MLX's RNG differs from
+            Torch's, so a seed repeats within MLX only.
+        inference_mode: ``"conditioned"`` uses native MLX FP16 convolution and the
+            trained LINet text path. ``"source"`` reproduces upstream's disabled image
+            text path and Torch CPU reduction order.
+        output_region: ``"full"`` writes upstream's full-volume reconstruction, whose HU
+            are clipped to [-1000, 1000] and can differ from the input outside the
+            lesion. ``"box"`` keeps the generated box, feathers it into the input CT over
+            ``LOCALIZATION_MARGIN_MM``, leaves every other voxel exact, and also
+            writes the full reconstruction as ``raw_synthetic_image``. The lesion
+            mask is not clipped to the box.
+        overwrite: Replace existing output files instead of refusing.
+
+    Returns:
+        ``{"outputs": ..., "details": ...}``. ``synthetic_image`` is float32 HU;
+        ``target_mask`` and ``organ_mask`` are uint8 with value 1 for lesion and
+        organ. All keep the standardized grid's affine, qform and sform.
+
+    Raises:
+        InvalidInputError: For invalid options, unreadable or mismatched inputs, or
+            outputs that would overwrite an input or an existing file.
+        AssetNotReadyError: If the weights directory is missing or not current.
+        ModelExecutionError: If a stage produces non-finite values, LMNet yields an
+            empty lesion mask, or another error occurs during execution.
+    """
+
+    options = _parse_options(
+        organ=organ,
+        lesion_type=lesion_type,
+        bbox_size_mm=bbox_size_mm,
+        placement=placement,
+        shape=shape,
+        density=density,
+        density_variation=density_variation,
+        enhancement=enhancement,
+        surface=surface,
+        adjacent_relationship=adjacent_relationship,
+        specific_features=specific_features,
+        bbox_center_voxel=bbox_center_voxel,
+        diffusion_steps=diffusion_steps,
+        seed=seed,
+        inference_mode=inference_mode,
+        output_region=output_region,
+    )
+    source, supplied_mask, outputs = _run_paths(
+        image_path=image_path,
+        organ_mask_path=organ_mask_path,
+        output_dir=output_dir,
+        output_region=options.output_region,
+        overwrite=overwrite,
+    )
+    anatomy_path = (
+        Path(anatomy_mask_path).expanduser().resolve() if anatomy_mask_path is not None else None
+    )
+    if anatomy_path in outputs.values():
+        raise InvalidInputError("LesionDiffusion output files must not overwrite the anatomy mask")
+    directory = require_weights(weights_path, inference_mode=options.inference_mode)
+    started_at = datetime.now(UTC)
+    started = time.perf_counter()
+    try:
+        geometry = prepare_geometry(
+            source=source,
+            supplied_mask=supplied_mask,
+            supplied_anatomy=anatomy_path,
+            options=options,
+        )
+        spec, stages = _execute_run(geometry, options, directory, outputs)
+    except MedmlxError:
+        raise
+    except Exception as exc:
+        raise ModelExecutionError(f"LesionDiffusion failed during execution: {exc}") from exc
+    return _run_result(options, geometry, outputs, directory, spec, stages, started_at, started)
+
+
+def _run_paths(
+    *,
+    image_path: _PathArg,
+    organ_mask_path: _PathArg,
+    output_dir: _PathArg,
+    output_region: str,
+    overwrite: bool,
+) -> tuple[Path, Path, dict[str, Path]]:
+    if not isinstance(cast(object, overwrite), bool):
+        raise InvalidInputError("overwrite must be a boolean")
+    source = Path(image_path).expanduser().resolve()
+    supplied_mask = Path(organ_mask_path).expanduser().resolve()
+    output = Path(output_dir).expanduser().resolve()
+    if not source.is_file():
+        raise InvalidInputError(f"Missing input CT NIfTI: {source}")
+    if not supplied_mask.is_file():
+        raise InvalidInputError(f"Missing organ mask NIfTI: {supplied_mask}")
+    outputs = output_paths(output, output_region)
+    if source in outputs.values():
+        raise InvalidInputError("LesionDiffusion output files must not overwrite the input CT")
+    if supplied_mask in outputs.values():
+        raise InvalidInputError(
+            "LesionDiffusion output files must not overwrite the input organ mask"
+        )
+    if output.exists() and not output.is_dir():
+        raise InvalidInputError(f"LesionDiffusion output path is not a directory: {output}")
+    if not overwrite:
+        existing = [path for path in outputs.values() if path.exists()]
+        if existing:
+            raise InvalidInputError(
+                f"{existing[0]} already exists; pass overwrite=true to replace outputs"
+            )
+    return source, supplied_mask, outputs
+
+
+def _execute_run(
+    geometry: _Geometry,
+    options: LesionDiffusionOptions,
+    directory: Path,
+    outputs: dict[str, Path],
+) -> tuple[GenerationSpec, dict[str, dict[str, object]]]:
+    spec: dict[str, object] = {
+        "schema_version": "medmlx.lesiondiffusion.generation.v1",
+        "source_ref": SOURCE_REF,
+        "bbox_center_voxel": list(geometry.center),
+        "bbox_size_voxel": list(geometry.bbox_size_voxel),
+        "placement": options.placement,
+        "output_mapping": "source_las_zyx_to_input_ras_grid",
+    }
+    model_label, _ = source_organ_label(options.organ)
+    report = _structured_report(
+        reference=geometry.reference,
+        organ_mask=geometry.organ_mask,
+        organ_label=model_label,
+        center=geometry.center,
+        bbox_size=geometry.bbox_size_voxel,
+        options=options,
+    )
+    attributes = cast(dict[str, object], cast(list[object], report[str(model_label)])[2])
+    outputs["synthetic_image"].parent.mkdir(parents=True, exist_ok=True)
+    _save_like_reference(
+        data=np.where(geometry.organ_mask, geometry.organ_label, 0).astype(np.uint8),
+        reference=geometry.output_reference,
+        destination=outputs["organ_mask"],
+        dtype=np.uint8,
+    )
+    mx = cast("Mlx", import_mlx())
+    stages: dict[str, dict[str, object]] = {}
+    image, mask, facts = run_native_pipeline(
+        source_ct_ras=geometry.source_data,
+        organ_mask_ras=geometry.organ_mask,
+        bbox_mask_ras=geometry.bbox_mask,
+        options=options,
+        attributes=attributes,
+        weights_dir=directory,
+        mx=mx,
+        on_stage_completed=stages.__setitem__,
+        anatomy_mask_ras=geometry.anatomy_mask,
+    )
+    spec["native_runtime"] = facts
+    if geometry.anatomy_mask is not None:
+        spec["anatomy_mask"] = geometry.organ_source["anatomy_mask"]
+    materialize_arrays(
+        outputs=outputs,
+        geometry=geometry,
+        image_data=image,
+        lesion_data=mask,
+        generation_spec=spec,
+        output_region=options.output_region,
+    )
+    return cast(GenerationSpec, spec), stages
+
+
+def _run_result(
+    options: LesionDiffusionOptions,
+    geometry: _Geometry,
+    outputs: dict[str, Path],
+    directory: Path,
+    spec: GenerationSpec,
+    stages: dict[str, dict[str, object]],
+    started_at: datetime,
+    started: float,
+) -> RunResult:
+    grid = [int(value) for value in geometry.output_reference.shape]
+    details: dict[str, object] = {
+        "model_id": MODEL_ID,
+        "source_ref": SOURCE_REF,
+        "organ": options.organ,
+        "lesion_type": options.lesion_type,
+        "seed": options.seed,
+        "diffusion_steps": options.diffusion_steps,
+        "generation_spec": spec,
+        "stages": stages,
+        "output_region": options.output_region,
+        "output_kind_by_role": {
+            "synthetic_image": "synthetic_image",
+            "target_mask": "label_map",
+            "organ_mask": "label_map",
+            **(
+                {"raw_synthetic_image": "synthetic_image"}
+                if "raw_synthetic_image" in outputs
+                else {}
+            ),
+        },
+        "output_shape_by_role": {role: grid for role in outputs},
+        "output_dtype_by_role": {
+            "synthetic_image": "float32",
+            "target_mask": "uint8",
+            "organ_mask": "uint8",
+            **({"raw_synthetic_image": "float32"} if "raw_synthetic_image" in outputs else {}),
+        },
+        "output_labels_by_role": {
+            "target_mask": [{"name": options.lesion_type, "value": 1}],
+            "organ_mask": [{"name": options.organ, "value": geometry.organ_label}],
+        },
+        "weights_path": directory.as_posix(),
+        "started_at": started_at.isoformat(timespec="seconds"),
+        "elapsed_s": round(time.perf_counter() - started, 4),
+        "requires_human_review": True,
+        "warning": WARNING,
+    }
+    return {
+        "outputs": {role: path.as_posix() for role, path in outputs.items()},
+        "details": cast(RunDetails, _json_safe(details)),
+    }
+
+
+def run_native_pipeline(
+    *,
+    source_ct_ras: NumericArray,
+    organ_mask_ras: BoolArray,
+    bbox_mask_ras: HostArray,
+    options: LesionDiffusionOptions,
+    attributes: Mapping[str, object],
+    weights_dir: Path,
+    mx: Mlx,
+    on_stage_completed: Callable[[str, dict[str, object]], None],
+    anatomy_mask_ras: HostArray | None = None,
+) -> tuple[HostArray, HostArray, NativeRuntime]:
+    """Run LMNet, then LINet and the VQ decoder, with the released EMA weights.
+
+    Volumes are in standardized RAS ``(X, Y, Z)`` order on the even-padded grid and are
+    converted to upstream's ``(Z, Y, X)`` layout internally. Seeds MLX's RNG with
+    ``options.seed``. Each stage is evaluated and exported to the host before the next
+    loads, to keep peak memory down.
+
+    Args:
+        source_ct_ras: CT in HU.
+        organ_mask_ras: Boolean target-organ mask.
+        bbox_mask_ras: Box volume, 2 inside the box and 0 elsewhere (``bbox_mask``).
+        options: Validated run options.
+        attributes: Upstream report fields from ``_structured_report``.
+        weights_dir: Converted-weights directory (see ``require_weights``).
+        mx: The imported ``mlx.core`` module.
+        on_stage_completed: Called as ``on_stage_completed("lmnet" | "linet", record)``
+            after each stage with its settings and timings.
+        anatomy_mask_ras: Optional TotalSegmentator v1 label map (0-104); defaults to
+            the target organ carrying its upstream label id.
+
+    Returns:
+        ``(generated_ct, label_map, facts)``. ``generated_ct`` is the full
+        VQ-reconstructed CT, float32 HU clipped to [-1000, 1000]. ``label_map`` is
+        uint8 with 2 for lesion, 1 for the remaining organ voxels and 0 elsewhere.
+        ``facts`` records the runtime settings.
+
+    Raises:
+        ModelExecutionError: If a stage produces non-finite values or LMNet yields an
+            empty lesion.
+        InvalidInputError: If the grid is smaller than a network crop.
+    """
+    directory = weights_dir
+    conversion = load_conversion(directory)
+    tokenizer_path = directory / TOKENIZER_FILE
+    mx.random.seed(options.seed)
+    image = ras_to_source(source_ct_ras).astype(np.float32)
+    organ = ras_to_source(organ_mask_ras).astype(bool)
+    bbox = ras_to_source(bbox_mask_ras) == 2
+    organ_id, _ = source_organ_label(options.organ)
+    anatomy = (
+        ras_to_source(anatomy_mask_ras)
+        if anatomy_mask_ras is not None
+        else organ.astype(np.uint8) * organ_id
+    )
+    lm_attributes = _lmnet_attributes(attributes, options)
+    lesion, lm_stage = _run_lmnet(
+        organ, bbox, options, lm_attributes, directory, tokenizer_path, mx, anatomy=anatomy
+    )
+    on_stage_completed("lmnet", lm_stage)
+    lin_attributes = _linet_attributes(attributes, options)
+    generated_ras, lin_stage = _run_linet(
+        image, lesion, options, lin_attributes, directory, tokenizer_path, mx
+    )
+    on_stage_completed("linet", lin_stage)
+    lesion_ras = source_to_ras(np.where(lesion, 2, organ.astype(np.uint8)))
+    details: NativeRuntime = {
+        "conversion": conversion,
+        "device": str(mx.default_device()),
+        "dtype": {"lmnet": "float32", "linet": "float16", "vq": "float16"},
+        "inference_mode": options.inference_mode,
+        "convolution_arithmetic": (
+            "torch_cpu_source_reduction" if options.inference_mode == "source" else "mlx_native"
+        ),
+        "lmnet_attempts": cast(int, lm_stage["attempts"]),
+        "lmnet_conditioning": lm_attributes,
+        "lmnet_anatomy_context": (
+            "supplied_source_labels" if anatomy_mask_ras is not None else "target_organ_only"
+        ),
+        "linet_conditioning": lin_attributes,
+        "linet_skip_context": options.inference_mode == "source",
+        "lmnet_stage": lm_stage,
+        "linet_stage": lin_stage,
+        "model_organ_label": organ_id,
+        "sampling": "source_uniform_ddim_eta_1",
+        "synchronization": "mx.eval_each_ddim_step_and_export",
+        "seed_contract": (
+            "MLX native RNG; same seed is reproducible within MLX, not identical to Torch RNG"
+        ),
+    }
+    return generated_ras, lesion_ras, details
+
+
+def _linet_attributes(
+    attributes: Mapping[str, object], options: LesionDiffusionOptions
+) -> dict[str, object]:
+    _, organ_name = source_organ_label(options.organ)
+    omitted = {"size"}
+    if options.inference_mode == "conditioned":
+        # The report's numeric CT value is the input organ mean, not a requested
+        # lesion density. It must not override the user's categorical phenotype.
+        omitted.add("CT value")
+    return {
+        **{
+            key: value
+            for key, value in attributes.items()
+            if key not in omitted and (options.inference_mode == "source" or value != "")
+        },
+        "lesion location": organ_name,
+    }
+
+
+def _lmnet_attributes(
+    attributes: Mapping[str, object],
+    options: LesionDiffusionOptions,
+) -> dict[str, object]:
+    _, organ_name = source_organ_label(options.organ)
+    lm_attributes = dict(attributes)
+    lm_attributes["lesion location"] = organ_name
+    # The mask generator is not given size, density or the organ-mean CT sentence.
+    for key in ("size", "CT value", "density variations", "density"):
+        lm_attributes.pop(key, None)
+    if not lm_attributes.get("specific features"):
+        lm_attributes.pop("specific features", None)
+    # This matches the pinned inference path: its supplied coarseg and target
+    # are identical, so solid organs receive the protruding condition. The
+    # ``placement`` option does not enter here; it only shapes box placement and
+    # LINet's text. Gallbladder counts as hollow here but not for box placement.
+    lm_attributes["cavity"] = (
+        (
+            "within the lumen of a hollow organ,"
+            if "stone" in options.lesion_type
+            else "wall thickening,"
+        )
+        if options.organ in {"colon", "urinary_bladder", "esophagus", "gallbladder", "stomach"}
+        else "protruding from the parenchymal organ,"
+    )
+    return lm_attributes
+
+
+def _run_lmnet(
+    organ: BoolArray,
+    bbox: BoolArray,
+    options: LesionDiffusionOptions,
+    lm_attributes: Mapping[str, object],
+    directory: Path,
+    tokenizer_path: Path,
+    mx: Mlx,
+    *,
+    anatomy: HostArray,
+) -> tuple[BoolArray, dict[str, object]]:
+    crop = source_crop(bbox, LMNET_CROP)
+    lm_started = time.perf_counter()
+    optimized = options.inference_mode == "conditioned"
+    lmnet = LdmUnet(
+        load_stage(directory, "lmnet", mx, dtype=mx.float32),
+        mx,
+        LMNET_CONFIG,
+        fused_attention=optimized,
+    )
+    text = BiomedTextEncoder(load_stage(directory, "lmnet_text", mx, dtype=mx.float32), mx)
+    condition = encode_attributes(lm_attributes, text, tokenizer_path, mx)
+    denoiser = mx.compile(lmnet.__call__) if optimized else lmnet.__call__
+    # Conditioning channels: anatomy label id / 104 (the upstream label count),
+    # target organ, box; shape (1, 3, *LMNET_CROP).
+    conditioning = cast(ArrayConstructor, mx.array)(
+        np.stack((anatomy[crop].astype(np.float64) / 104.0, organ[crop], bbox[crop]))[None],
+        dtype=mx.float32,
+    )
+    sampler = DdimSampler(lmnet.weights["alphas_cumprod"], mx, options.diffusion_steps)
+    lesion = np.zeros(bbox.shape, dtype=bool)
+    attempts = 0
+    samples: Array | None = None
+    # Volume QC: resample once if the selected component is too small (at most 400
+    # voxels, 50 for stones); the second attempt is kept either way.
+    for attempt in range(1, 3):
+        attempts = attempt
+        samples = sampler(denoiser, condition, conditioning)
+        mx.eval(samples)
+        if not bool(mx.all(mx.isfinite(samples)).item()):
+            raise ModelExecutionError("Native LMNet produced non-finite samples")
+        component = select_lesion_component(cast(FloatArray, np.array(samples))[0, 0], bbox[crop])
+        lesion[crop] = component
+        if int(np.sum(component)) > (50 if "stone" in options.lesion_type else 400):
+            break
+    # Release LMNet before LINet and the VQ autoencoder load, to bound peak memory.
+    del lmnet, denoiser, text, condition, conditioning, sampler, samples
+    gc.collect()
+    mx.clear_cache()
+    if not np.any(lesion):
+        raise ModelExecutionError(
+            "LesionDiffusion LMNet QC rejected this seed: mask has no lesion label 2"
+        )
+    lm_stage: dict[str, object] = {
+        "status": "completed",
+        "device": str(mx.default_device()),
+        "dtype": "float32",
+        "crop_shape": list(LMNET_CROP),
+        "diffusion_steps_actual": len(lesion_diffusion_timesteps(options.diffusion_steps)),
+        "attempts": attempts,
+        "lesion_voxels": int(np.sum(lesion)),
+        "finite": True,
+        "attention": "mlx_fused_padded_fp32" if optimized else "source_explicit",
+        "denoiser_compiled": optimized,
+        "synchronized_elapsed_s": time.perf_counter() - lm_started,
+    }
+    return lesion, lm_stage
+
+
+def _run_linet(
+    image: FloatArray,
+    lesion: BoolArray,
+    options: LesionDiffusionOptions,
+    lin_attributes: Mapping[str, object],
+    directory: Path,
+    tokenizer_path: Path,
+    mx: Mlx,
+) -> tuple[HostArray, dict[str, object]]:
+    lin_started = time.perf_counter()
+    source_arithmetic = options.inference_mode == "source"
+    linet = LdmUnet(
+        load_stage(directory, "linet", mx, dtype=mx.float16),
+        mx,
+        replace(LINET_CONFIG, skip_context=source_arithmetic),
+        source_arithmetic=source_arithmetic,
+    )
+    vq = VqAutoencoder(
+        load_stage(directory, "vq", mx, dtype=mx.float16),
+        mx,
+        source_arithmetic=source_arithmetic,
+    )
+    condition: Array | None = None
+    if not source_arithmetic:
+        text = BiomedTextEncoder(load_stage(directory, "linet_text", mx, dtype=mx.float32), mx)
+        condition = encode_attributes(lin_attributes, text, tokenizer_path, mx)
+        del text
+    # Force the lazy weight loads here so load_and_condition_s measures them.
+    mx.eval(*linet.weights.values(), *vq.weights.values())
+    load_elapsed = time.perf_counter() - lin_started
+    encode_started = time.perf_counter()
+    native_image = piecewise_ct(cast(ArrayConstructor, mx.array)(image[None, None]), mx).astype(
+        mx.float16
+    )
+    latent = encode_source(vq, native_image, mx)
+    mx.eval(latent)
+    if not bool(mx.all(mx.isfinite(latent)).item()):
+        raise ModelExecutionError("Native VQ encoder produced non-finite latents")
+    encode_elapsed = time.perf_counter() - encode_started
+    # Lesion mask on the latent grid: nearest-neighbour resize, then binarize.
+    mask = vq.resize_nearest(
+        cast(ArrayConstructor, mx.array)(lesion[None, None], dtype=mx.float16),
+        tuple(int(value) for value in latent.shape[2:]),
+    )
+    mask = (mask > 0.5).astype(mx.float16)
+    crop = source_crop(lesion, LINET_CROP)
+    # The latent has half the image resolution (VQ factor two), so halve the crop.
+    latent_crop = tuple(slice(int(axis.start) // 2, int(axis.stop) // 2) for axis in crop)
+    selection = (slice(None), slice(None), *latent_crop)
+    sampler = DdimSampler(linet.weights["alphas_cumprod"], mx, options.diffusion_steps)
+    denoiser = linet.__call__ if source_arithmetic else mx.compile(linet.__call__)
+    mx.eval(mask)
+    sampling_started = time.perf_counter()
+    generated = sampler(denoiser, condition, latent[selection], mask=mask[selection])
+    latent[selection] = generated.astype(mx.float16)
+    mx.eval(latent)
+    if not bool(mx.all(mx.isfinite(latent)).item()):
+        raise ModelExecutionError("Native LINet produced non-finite latents before quantization")
+    sampling_elapsed = time.perf_counter() - sampling_started
+    # Free the UNet before decoding; only the VQ autoencoder and latent are still needed.
+    del linet, denoiser, sampler, generated, native_image, mask, condition
+    gc.collect()
+    mx.clear_cache()
+    decode_started = time.perf_counter()
+    decoded = vq.decode(latent)
+    mx.eval(decoded)
+    if not bool(mx.all(mx.isfinite(decoded)).item()):
+        raise ModelExecutionError(
+            "Native VQ decoder produced non-finite voxels before CT remapping"
+        )
+    decoded = piecewise_ct(decoded.astype(mx.float32), mx, inverse=True)
+    mx.eval(decoded)
+    if not bool(mx.all(mx.isfinite(decoded)).item()):
+        raise ModelExecutionError("Native LINet/VQ produced non-finite CT voxels")
+    generated_ras = source_to_ras(np.array(decoded)[0, 0]).astype(np.float32)
+    decode_elapsed = time.perf_counter() - decode_started
+    lin_stage: dict[str, object] = {
+        "status": "completed",
+        "device": str(mx.default_device()),
+        "dtype": "float16",
+        "crop_shape": list(LINET_CROP),
+        "latent_shape": list(latent.shape),
+        "output_shape": list(image.shape),
+        "diffusion_steps_actual": len(lesion_diffusion_timesteps(options.diffusion_steps)),
+        "finite": True,
+        "attention": "source_explicit",
+        "denoiser_compiled": not source_arithmetic,
+        "load_and_condition_s": load_elapsed,
+        "encode_s": encode_elapsed,
+        "sampling_s": sampling_elapsed,
+        "decode_and_export_s": decode_elapsed,
+        "synchronized_elapsed_s": time.perf_counter() - lin_started,
+    }
+    return generated_ras, lin_stage
+
+
+def select_lesion_component(samples: NumericArray, reference: BoolArray) -> BoolArray:
+    """Pick the lesion mask from LMNet samples as upstream does.
+
+    For each threshold in 0.9, 0.8, ..., 0.3 the samples are binarized (``>``), reduced
+    to their largest connected component (SciPy's default face connectivity), and the
+    threshold whose component volume is closest to the box volume wins; ties keep
+    the higher threshold.
+
+    Args:
+        samples: LMNet output crop ``(D, H, W)`` in source order.
+        reference: Boolean box mask of the same shape; only its voxel count is used.
+
+    Returns:
+        Boolean lesion mask with the shape of ``samples``.
+
+    Raises:
+        ModelExecutionError: If no threshold yields a candidate.
+    """
+    from scipy import ndimage
+
+    best: BoolArray | None = None
+    difference = float("inf")
+    for threshold in np.arange(0.9, 0.2, -0.1):
+        mask = samples > threshold
+        labels, count = ndimage.label(mask)
+        if count:
+            sizes = ndimage.sum(mask, labels, range(count + 1))
+            mask = labels == int(np.argmax(sizes[1:]) + 1)
+        current = abs(int(np.sum(mask)) - int(np.sum(reference)))
+        if current < difference:
+            difference, best = current, mask.copy()
+    if best is None:
+        raise ModelExecutionError("LesionDiffusion lesion selection found no threshold")
+    return best
+
+
+def source_organ_label(organ: str) -> tuple[int, str]:
+    """Return ``(upstream label id, report name)`` for an organ key of ``SOURCE_ORGAN_LABELS``."""
+
+    return SOURCE_ORGAN_LABELS[organ]
+
+
+# --- converted weights ----------------------------------------------------------------
+
+
+def _stage_file(directory: Path, name: str) -> Path:
+    """Use the consolidated release or an existing local NPZ conversion."""
+    path = directory / "model.safetensors"
+    return path if path.is_file() else directory / (name + ".npz")
+
+
+def require_weights(path: _PathArg, *, inference_mode: str = DEFAULT_INFERENCE_MODE) -> Path:
+    """Return the resolved weights directory after checking it is a current conversion.
+
+    Stages come from per-stage ``.npz`` files or one consolidated ``model.safetensors``
+    whose keys are prefixed ``<stage>.``. ``tokenizer.json`` and a current
+    ``conversion.json`` are always required. ``source`` mode does not need the LINet
+    text encoder (``linet_text``).
+
+    Raises:
+        AssetNotReadyError: If the directory, a stage, the tokenizer or the metadata is
+            missing, or the metadata does not match this package's conversion schema.
+    """
+
+    directory = Path(path).expanduser().resolve()
+    if not directory.is_dir():
+        raise AssetNotReadyError(
+            f"LesionDiffusion MLX weights directory is missing: {directory}",
+            reason=f"missing {directory.as_posix()}",
+            hint=WEIGHTS_HINT,
+        )
+    inference_files = SOURCE_INFERENCE_FILES if inference_mode == "source" else CONVERTED_FILES
+    files = [_stage_file(directory, Path(name).stem) for name in inference_files]
+    files.extend((directory / TOKENIZER_FILE, directory / CONVERSION_FILE))
+    missing = [file for file in files if not file.is_file()]
+    if missing:
+        raise AssetNotReadyError(
+            f"Native MLX LesionDiffusion weights are not ready: missing {missing[0]}",
+            reason=f"Missing native LesionDiffusion asset: {missing[0]}",
+            hint=WEIGHTS_HINT,
+        )
+    packed = directory / "model.safetensors"
+    if packed.is_file():
+        from safetensors import safe_open
+
+        with safe_open(packed, framework="np") as tensors:
+            names = tensors.keys()
+            present = {key.split(".", 1)[0] for key in names}
+        for name in inference_files:
+            if Path(name).stem not in present:
+                raise AssetNotReadyError(
+                    f"Native MLX LesionDiffusion weights are missing stage {Path(name).stem}",
+                    reason=f"Missing stage in {packed.name}",
+                    hint=WEIGHTS_HINT,
+                )
+    try:
+        load_conversion(directory)
+    except (ValueError, OSError) as exc:
+        raise AssetNotReadyError(
+            f"Native MLX LesionDiffusion weights are not ready: {exc}",
+            reason=str(exc),
+            hint=WEIGHTS_HINT,
+        ) from exc
+    return directory
+
+
+def load_conversion(directory: Path) -> dict[str, object]:
+    """Read and check ``conversion.json``; return its provenance fields.
+
+    Raises:
+        ValueError: If the file is not a JSON object, or its schema, source revision,
+            EMA flag, layout or precision profile is not the current one.
+        OSError: If the file cannot be read.
+    """
+    metadata = _load_json_object(directory / CONVERSION_FILE)
+    if (
+        metadata.get("schema_version") != CONVERSION_SCHEMA
+        or metadata.get("source_ref") != SOURCE_REF
+    ):
+        raise ValueError("LesionDiffusion MLX conversion schema/source is not current")
+    if metadata.get("converter_version") != CONVERSION_VERSION or metadata.get("ema") is not True:
+        raise ValueError("LesionDiffusion MLX conversion must use current EMA conversion")
+    if metadata.get("layout") != "source_torch_ncdhw" or metadata.get("stored_dtype") != "float32":
+        raise ValueError("LesionDiffusion MLX conversion layout/dtype is not current")
+    if metadata.get("inference_dtype") != {
+        "lmnet": "float32",
+        "linet": "float16",
+        "vq": "float16",
+    }:
+        raise ValueError("LesionDiffusion MLX conversion precision profile is not current")
+    return {
+        key: metadata[key]
+        for key in (
+            "schema_version",
+            "converter_version",
+            "source_ref",
+            "layout",
+            "stored_dtype",
+            "inference_dtype",
+            "ema",
+        )
+    }
+
+
+def load_stage(directory: Path, name: str, mx: Mlx, *, dtype: Dtype) -> dict[str, Array]:
+    """Load one stage's converted arrays, cast to ``dtype``.
+
+    Keys are upstream state-dict names (any ``<stage>.`` prefix from a consolidated
+    ``model.safetensors`` is removed). Checks ``conversion.json`` first.
+    """
+    load_conversion(directory)
+    path = _stage_file(directory, name)
+    loaded = mx.load(str(path))
+    if path.name == "model.safetensors":
+        prefix = name + "."
+        return {
+            key.removeprefix(prefix): value.astype(dtype)
+            for key, value in loaded.items()
+            if key.startswith(prefix)
+        }
+    return {key: value.astype(dtype) for key, value in loaded.items()}
+
+
+def _load_json_object(path: Path) -> dict[str, object]:
+    try:
+        payload: object = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"Could not read JSON object: {path}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError(f"Expected JSON object: {path}")
+    return cast(dict[str, object], payload)
+
+
+# --- options --------------------------------------------------------------------------
+
+
+def _parse_options(
+    *,
+    organ: object,
+    lesion_type: object,
+    bbox_size_mm: object,
+    placement: object,
+    shape: object,
+    density: object,
+    density_variation: object,
+    enhancement: object,
+    surface: object,
+    adjacent_relationship: object,
+    specific_features: object,
+    bbox_center_voxel: object,
+    diffusion_steps: object,
+    seed: object,
+    inference_mode: object,
+    output_region: object = DEFAULT_OUTPUT_REGION,
+) -> LesionDiffusionOptions:
+    for name, value in (
+        ("organ", organ),
+        ("lesion_type", lesion_type),
+        ("placement", placement),
+        ("shape", shape),
+        ("density", density),
+        ("density_variation", density_variation),
+        ("enhancement", enhancement),
+        ("surface", surface),
+        ("adjacent_relationship", adjacent_relationship),
+        ("specific_features", specific_features),
+        ("inference_mode", inference_mode),
+        ("output_region", output_region),
+    ):
+        if not isinstance(value, str):
+            raise InvalidInputError(f"LesionDiffusion {name} must be a string")
+    if isinstance(bbox_size_mm, str | bytes) or not isinstance(bbox_size_mm, Sequence):
+        raise InvalidInputError("LesionDiffusion bbox_size_mm must contain X, Y, Z")
+    size_values = cast(Sequence[object], bbox_size_mm)
+    if any(isinstance(value, bool) or not isinstance(value, int | float) for value in size_values):
+        raise InvalidInputError("LesionDiffusion bbox_size_mm values must be numbers")
+    center: tuple[int, int, int] | None = None
+    if bbox_center_voxel is not None:
+        if isinstance(bbox_center_voxel, str | bytes) or not isinstance(
+            bbox_center_voxel, Sequence
+        ):
+            raise InvalidInputError("LesionDiffusion bbox_center_voxel must contain I, J, K")
+        center = cast(tuple[int, int, int], tuple(cast(Sequence[object], bbox_center_voxel)))
+    return LesionDiffusionOptions(
+        organ=cast(str, organ),
+        lesion_type=cast(str, lesion_type),
+        bbox_size_mm=cast(
+            tuple[float, float, float],
+            tuple(float(value) for value in cast(Sequence[int | float], size_values)),
+        ),
+        placement=cast(str, placement),
+        shape=cast(str, shape),
+        density=cast(str, density),
+        density_variation=cast(str, density_variation),
+        enhancement=cast(str, enhancement),
+        surface=cast(str, surface),
+        adjacent_relationship=cast(str, adjacent_relationship),
+        specific_features=cast(str, specific_features),
+        bbox_center_voxel=center,
+        diffusion_steps=cast(int, diffusion_steps),
+        seed=cast(int, seed),
+        inference_mode=cast(str, inference_mode),
+        output_region=cast(str, output_region),
+    )
+
+
+def _is_integer(value: object) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+# --- geometry -------------------------------------------------------------------------
+
+
+def prepare_geometry(
+    *,
+    source: Path,
+    supplied_mask: Path,
+    options: LesionDiffusionOptions,
+    supplied_anatomy: Path | None = None,
+) -> _Geometry:
+    """Standardize the inputs and place the box.
+
+    Loads the CT onto the RAS 1 mm grid, edge-pads to even extents, loads the organ
+    mask (and optional anatomy map) onto the same grid, converts ``bbox_size_mm`` to
+    voxels with ``round`` at the grid spacing, and resolves the box center.
+
+    Raises:
+        InvalidInputError: If a file is unreadable, a grid is oblique or does not
+            match, a mask has invalid labels, the anatomy map disagrees with the organ
+            mask or uses labels above 104, or the box does not fit.
+    """
+    output_reference, standardized = _load_standardized_ct(source)
+    reference, source_data = _pad_to_even(output_reference, standardized, mode="edge")
+    organ_label = 1
+    organ_mask, organ_source = prepare_organ_mask(
+        reference=reference,
+        supplied_mask=supplied_mask,
+    )
+    anatomy_mask = None
+    if supplied_anatomy is not None:
+        anatomy_mask = _load_label_map(reference, supplied_anatomy, "anatomy mask")
+        values = np.unique(anatomy_mask)
+        if np.any(values > 104):
+            raise InvalidInputError(
+                "Anatomy mask must use upstream TotalSegmentator v1 labels 0-104"
+            )
+        source_label, _ = source_organ_label(options.organ)
+        if not np.array_equal(anatomy_mask == source_label, organ_mask):
+            raise InvalidInputError(
+                "Anatomy mask selected-organ label must match the binary organ mask"
+            )
+        anatomy_mask = anatomy_mask.astype(np.uint8)
+        organ_source["anatomy_mask"] = {
+            "path": supplied_anatomy.as_posix(),
+            "label_vocabulary": "upstream_totalsegmentator_v1_104",
+            "labels_present": [int(value) for value in values],
+        }
+    spacing_mm = tuple(float(value) for value in reference.header.get_zooms()[:3])
+    bbox_size = tuple(
+        int(round(options.bbox_size_mm[index] / spacing_mm[index]))  # noqa: RUF046 - verbatim
+        for index in range(3)
+    )
+    bbox_size_voxel = cast(tuple[int, int, int], bbox_size)
+    center = resolve_bbox_center(
+        organ_mask=organ_mask,
+        bbox_size=bbox_size_voxel,
+        placement=options.placement,
+        requested_center=options.bbox_center_voxel,
+        seed=options.seed,
+        organ=options.organ,
+    )
+    bbox_array = bbox_mask(reference.shape, center, bbox_size_voxel)
+    return _Geometry(
+        reference,
+        output_reference,
+        source_data,
+        organ_mask,
+        organ_label,
+        organ_source,
+        bbox_array,
+        bbox_size_voxel,
+        center,
+        anatomy_mask,
+    )
+
+
+_RAS_AXCODES: Final = ("R", "A", "S")
+
+
+def _is_ras_1mm_axis_aligned(image: NiftiImage) -> bool:
+    """True when ``image`` is already RAS, 1 mm isotropic, and axis-aligned."""
+    orientation = tuple(str(value) for value in nib.aff2axcodes(image.affine))
+    spacing = tuple(float(value) for value in image.header.get_zooms()[:3])
+    return bool(
+        orientation == _RAS_AXCODES
+        and np.allclose(spacing, (1.0, 1.0, 1.0), atol=0.01, rtol=0)
+        and np.allclose(image.affine[:3, :3], np.eye(3), atol=1e-4, rtol=0)
+    )
+
+
+def _standardize_to_ras_1mm(
+    image: NiftiImage, data: NumericArray, *, order: Literal[0, 1]
+) -> tuple[NiftiImage, NumericArray]:
+    """Reorient and resample to an axis-aligned RAS 1 mm grid, as upstream's offline
+    ``preprocess.standardize_image`` does, when the input is not already on one.
+
+    Spatial units are normalized to millimeters, including affine translations
+    and coded forms. An unspecified unit retains the established mm interpretation.
+    Reorientation (axis permutation and sign flips) is exact; isotropic resampling
+    uses ``scipy.ndimage.zoom`` (linear for ``order=1`` intensity volumes, nearest
+    for ``order=0`` label maps). Already-conforming input is returned unchanged.
+    A grid that is still not axis-aligned after reorientation (a true oblique or
+    sheared affine) is rejected rather than resampled; this port does not implement
+    general affine resampling.
+    """
+    try:
+        spatial_unit, temporal_unit = image.header.get_xyzt_units()
+        scale = {"unknown": 1.0, "mm": 1.0, "meter": 1000.0, "micron": 0.001}[spatial_unit]
+    except KeyError as error:
+        raise InvalidInputError(
+            "LesionDiffusion NIfTI units must be mm, meter, micron or unknown"
+        ) from error
+    if spatial_unit != "mm":
+        affine_mm = np.array(image.affine, dtype=np.float64, copy=True)
+        affine_mm[:3] *= scale
+        header = nib.Nifti1Header.from_header(image.header)
+        header.set_xyzt_units("mm", temporal_unit)
+        normalized = nib.Nifti1Image(cast(HostArray, data), affine_mm, header)
+        for read_form, write_form in (
+            (image.get_qform, normalized.set_qform),
+            (image.get_sform, normalized.set_sform),
+        ):
+            form, code = read_form(coded=True)
+            form_mm = np.array(affine_mm if form is None else form, copy=True)
+            if form is not None:
+                form_mm[:3] *= scale
+            write_form(form_mm, code=int(code))
+        image = normalized
+    if _is_ras_1mm_axis_aligned(image):
+        return image, data
+    affine = cast(HostArray, np.asarray(image.affine, dtype=np.float64))
+    current = nib.io_orientation(affine)
+    target = nib.orientations.axcodes2ornt(_RAS_AXCODES)
+    transform = nib.orientations.ornt_transform(current, target)
+    reoriented = cast(
+        NumericArray, nib.orientations.apply_orientation(cast(HostArray, data), transform)
+    )
+    reoriented_affine = affine.dot(nib.orientations.inv_ornt_aff(transform, data.shape))
+    linear = reoriented_affine[:3, :3]
+    if not np.allclose(linear, np.diag(np.diagonal(linear)), atol=1e-4, rtol=0):
+        raise InvalidInputError(
+            "LesionDiffusion requires an axis-aligned grid; this NIfTI's transform is "
+            "oblique and is not resampled automatically"
+        )
+    zoom_factors = tuple(float(value) for value in np.abs(np.diagonal(linear)))
+    if np.allclose(zoom_factors, 1.0, atol=1e-6):
+        resampled, new_affine = reoriented, reoriented_affine
+    else:
+        from scipy.ndimage import zoom
+
+        resampled = cast(NumericArray, zoom(reoriented, zoom_factors, order=order))
+        new_affine = cast(HostArray, reoriented_affine.copy())
+        new_affine[:3, :3] = np.diag(np.sign(np.diagonal(linear)))
+    header = nib.Nifti1Header.from_header(image.header)
+    header.set_data_dtype(resampled.dtype.type)
+    standardized = nib.Nifti1Image(cast(HostArray, resampled), new_affine, header)
+    return standardized, resampled
+
+
+def _pad_to_even(
+    image: NiftiImage, data: NumericArray, *, mode: Literal["edge", "constant"]
+) -> tuple[NiftiImage, NumericArray]:
+    """Pad trailing voxels so every spatial axis is even, keeping the origin fixed.
+
+    Resampling to 1 mm can land on an odd extent; the full-volume VQ stages need
+    even dimensions. ``edge`` repeats the border voxel (for an intensity volume),
+    ``constant`` zero-pads (for a label mask already handled as background 0).
+    """
+    pad_width = tuple((0, 1) if size % 2 else (0, 0) for size in data.shape)
+    if not any(width[1] for width in pad_width):
+        return image, data
+    padded = (
+        np.pad(data, pad_width, mode="edge")
+        if mode == "edge"
+        else np.pad(data, pad_width, mode="constant", constant_values=0)
+    )
+    header = nib.Nifti1Header.from_header(image.header)
+    header.set_data_dtype(padded.dtype.type)
+    padded_image = nib.Nifti1Image(cast(HostArray, padded), image.affine, header)
+    return padded_image, padded
+
+
+def load_reference_nifti(path: Path) -> tuple[NiftiImage, NumericArray]:
+    """Load the CT on the even-padded RAS 1 mm grid the networks consume."""
+    image, data = _load_standardized_ct(path)
+    return _pad_to_even(image, data, mode="edge")
+
+
+def _load_standardized_ct(path: Path) -> tuple[NiftiImage, NumericArray]:
+    """Load a finite 3-D NIfTI CT and standardize it to the RAS 1 mm grid (unpadded)."""
+    if not path.name.endswith((".nii", ".nii.gz")):
+        raise InvalidInputError("LesionDiffusion input must be a .nii or .nii.gz NIfTI")
+    try:
+        image = nib.load(str(path))
+    except (OSError, ValueError, ImageFileError) as exc:
+        raise InvalidInputError(f"Could not read input CT NIfTI: {path}") from exc
+    if len(image.shape) != 3:
+        raise InvalidInputError(f"LesionDiffusion input must be 3D; got {image.shape}")
+    if not np.all(np.isfinite(image.affine)):
+        raise InvalidInputError("LesionDiffusion input affine contains non-finite values")
+    data = cast(NumericArray, np.asanyarray(image.dataobj))
+    if not np.all(np.isfinite(data)):
+        raise InvalidInputError("LesionDiffusion input CT contains non-finite values")
+    return _standardize_to_ras_1mm(image, data, order=1)
+
+
+def prepare_organ_mask(
+    *,
+    reference: NiftiImage,
+    supplied_mask: Path,
+) -> tuple[BoolArray, dict[str, object]]:
+    """Load the binary organ mask on the CT's even-padded grid.
+
+    Returns:
+        ``(mask, provenance)``: a boolean array on ``reference``'s grid and a record of
+        the mask file.
+
+    Raises:
+        InvalidInputError: If the file is unreadable, the grid differs from
+            ``reference``, labels are negative or fractional, or the foreground is
+            not exactly the single label 1 (this also rejects an empty mask).
+    """
+    provenance: dict[str, object] = {
+        "producer": "supplied_organ_mask",
+        "mask": supplied_mask.as_posix(),
+        "binary_label_id": 1,
+        "requires_human_review": True,
+        "is_ground_truth": False,
+    }
+    data = _load_label_map(reference, supplied_mask, "organ mask")
+    positive = np.unique(data[data > 0])
+    if len(positive) != 1:
+        raise InvalidInputError(
+            "Organ mask must contain exactly one foreground label; multi-label maps are ambiguous"
+        )
+    if positive[0] != 1:
+        raise InvalidInputError(
+            "Supplied organ mask must be binary with label 1 for the selected organ; "
+            "extract that organ from a labeled anatomy map first"
+        )
+    return data > 0, provenance
+
+
+def _load_label_map(reference: NiftiImage, supplied_mask: Path, role: str) -> NumericArray:
+    """Load an integer label map onto ``reference``'s grid (nearest-neighbour, zero-padded).
+
+    ``role`` names the map in error messages. Raises ``InvalidInputError`` if the file
+    is unreadable, has non-finite or non-integer or negative labels, or its grid
+    differs from ``reference`` after standardization.
+    """
+    if not supplied_mask.is_file():
+        raise InvalidInputError(f"Missing {role} NIfTI: {supplied_mask}")
+    try:
+        image = nib.load(str(supplied_mask))
+    except (OSError, ValueError, ImageFileError) as exc:
+        raise InvalidInputError(f"Could not read {role} NIfTI: {supplied_mask}") from exc
+    data = cast(NumericArray, np.asanyarray(image.dataobj))
+    if not np.all(np.isfinite(data)):
+        raise InvalidInputError(f"LesionDiffusion {role} contains non-finite values")
+    image, data = _standardize_to_ras_1mm(image, data, order=0)
+    image, data = _pad_to_even(image, data, mode="constant")
+    if image.shape != reference.shape or not np.allclose(
+        image.affine, reference.affine, atol=1e-4, rtol=0
+    ):
+        raise InvalidInputError(f"LesionDiffusion {role} must share the input CT grid")
+    values = np.unique(data)
+    if np.any(values < 0) or np.any(values != np.floor(values)):
+        raise InvalidInputError(f"{role.capitalize()} labels must be non-negative integers")
+    return data
+
+
+def resolve_bbox_center(
+    *,
+    organ_mask: BoolArray,
+    bbox_size: tuple[int, int, int],
+    placement: str,
+    requested_center: tuple[int, int, int] | None,
+    seed: int,
+    organ: str = "liver",
+) -> tuple[int, int, int]:
+    """Return the box center ``(I, J, K)`` in voxels, as upstream preprocessing places it.
+
+    An explicit ``requested_center`` is returned unchanged if its box fits the grid; it
+    need not lie inside the organ. Otherwise a ``np.random.RandomState(seed)`` (MT19937)
+    picks a candidate organ voxel. For a solid organ with ``inside_parenchyma`` the
+    candidates are shuffled and the first whose whole box lies in the organ is used.
+    For a hollow organ, ``within_lumen`` draws from the organ eroded by 5 voxels and
+    ``wall_thickening`` from the organ minus that erosion (the whole organ if the
+    region is empty). Any other case, or no fitting candidate, draws one voxel at
+    random. The center is finally clamped so the box stays inside the grid.
+
+    Raises:
+        InvalidInputError: If a requested box does not fit, or the organ has no voxels.
+    """
+    from scipy.ndimage import binary_erosion
+
+    if requested_center is not None:
+        if bbox_slices(requested_center, bbox_size, organ_mask.shape) is None:
+            raise InvalidInputError("Requested bbox_center_voxel does not fit the image grid")
+        return requested_center
+    rng = np.random.RandomState(seed)
+    region = organ_mask
+    if organ in _HOLLOW_ORGANS and placement in {"within_lumen", "wall_thickening"}:
+        eroded = binary_erosion(organ_mask, iterations=5)
+        region = eroded if placement == "within_lumen" else organ_mask & ~eroded
+        if not np.any(region):
+            region = organ_mask
+    candidates = np.argwhere(region)
+    if not len(candidates):
+        raise InvalidInputError("No organ voxels available for box placement")
+    half = np.asarray(bbox_size) // 2
+    center = None
+    if organ not in _HOLLOW_ORGANS and placement == "inside_parenchyma":
+        rng.shuffle(candidates)
+        for candidate in candidates:
+            low, high = candidate - half, candidate + half
+            if np.any(low < 0) or np.any(high >= organ_mask.shape):
+                continue
+            if np.all(organ_mask[tuple(slice(a, b + 1) for a, b in zip(low, high, strict=True))]):
+                center = candidate
+                break
+    if center is None:
+        # Upstream rebuilds the unshuffled candidates after an unsuccessful scan.
+        candidates = np.argwhere(region)
+        center = candidates[rng.randint(len(candidates))]
+    center = np.maximum(center, half)
+    center = np.minimum(center, np.asarray(organ_mask.shape) - half - 1)
+    return int(center[0]), int(center[1]), int(center[2])
+
+
+def bbox_slices(
+    center: tuple[int, int, int],
+    size: tuple[int, int, int],
+    shape: tuple[int, ...],
+) -> tuple[slice, slice, slice] | None:
+    """Return the box as slices ``[center - size // 2, center + size // 2)``, or ``None``.
+
+    Each side has length ``2 * (size // 2)``, so an odd size loses one voxel. ``None``
+    means the box falls outside ``shape``.
+    """
+    half = np.asarray(size) // 2
+    low, high = np.asarray(center) - half, np.asarray(center) + half
+    if np.any(low < 0) or np.any(high > shape):
+        return None
+    slices = [slice(int(a), int(b)) for a, b in zip(low, high, strict=True)]
+    return slices[0], slices[1], slices[2]
+
+
+def bbox_mask(
+    shape: tuple[int, ...],
+    center: tuple[int, int, int],
+    size: tuple[int, int, int],
+) -> HostArray:
+    """Return a uint8 volume of ``shape`` with 2 inside the box and 0 elsewhere.
+
+    Raises:
+        InvalidInputError: If the box extends outside ``shape``.
+    """
+    slices = bbox_slices(center, size, shape)
+    if slices is None:
+        raise InvalidInputError("Resolved LesionDiffusion bbox extends outside the image")
+    mask = np.zeros(shape, dtype=np.uint8)
+    mask[slices] = 2
+    return mask
+
+
+def _structured_report(
+    *,
+    reference: NiftiImage,
+    organ_mask: BoolArray,
+    organ_label: int,
+    center: tuple[int, int, int],
+    bbox_size: tuple[int, int, int],
+    options: LesionDiffusionOptions,
+) -> dict[str, object]:
+    """Build upstream's structured report for one lesion.
+
+    Returns ``{label: [shape, "", fields, [[center], [size]]]}``. Phrases end with a
+    comma, as upstream's do. ``lesion location`` starts as the numeric label and is
+    replaced by the organ name before encoding. ``size`` is in voxels. ``CT value``
+    states the mean HU of the organ in the standardized CT, although its wording says
+    "lesion region"; it is not a lesion density and is never embedded as text.
+    """
+    image_data = cast(NumericArray, np.asanyarray(reference.dataobj))
+    organ_values = image_data[organ_mask]
+    mean_hu = float(np.mean(organ_values)) if organ_values.size else 0.0
+    details = {
+        "enhancement status": _with_comma(options.enhancement),
+        "lesion location": str(organ_label),
+        "shape": _with_comma(options.shape),
+        "size": f"[[{' '.join(str(value) for value in bbox_size)}]] pixel,",
+        "density": _with_comma(options.density),
+        "density variations": _with_comma(options.density_variation),
+        "CT value": f"Mean density of the lesion region is approximately {mean_hu:.1f} HU,",
+        "surface characteristics": _with_comma(options.surface),
+        "relationship with adjacent organs": _with_comma(options.adjacent_relationship),
+        "specific features": _with_comma(options.specific_features)
+        if options.specific_features
+        else "",
+        "cavity": _with_comma(_CAVITY_TEXT[options.placement]),
+    }
+    return {
+        str(organ_label): [
+            _with_comma(options.shape),
+            "",
+            details,
+            [[[int(value) for value in center]], [[int(value) for value in bbox_size]]],
+        ]
+    }
+
+
+# --- outputs --------------------------------------------------------------------------
+
+
+def materialize_arrays(
+    *,
+    outputs: Mapping[str, Path],
+    geometry: _Geometry,
+    image_data: HostArray,
+    lesion_data: HostArray,
+    generation_spec: dict[str, object],
+    output_region: str = DEFAULT_OUTPUT_REGION,
+) -> None:
+    """Validate the generated arrays and write the output NIfTI files.
+
+    Args:
+        outputs: Role to destination path, from ``output_paths``.
+        geometry: Standardized inputs; ``output_reference`` defines the written grid.
+        image_data: Generated CT (HU) on the even-padded grid.
+        lesion_data: Label map on the same grid; 2 marks the lesion.
+        generation_spec: Updated in place with ``output_validation`` and, for the box
+            region, ``compositing``.
+        output_region: ``"full"`` or ``"box"``; see ``run``.
+
+    Raises:
+        ModelExecutionError: If shapes differ from the grid, values are non-finite, or
+            the label map has no lesion.
+    """
+    if (
+        image_data.shape != geometry.reference.shape
+        or lesion_data.shape != geometry.reference.shape
+    ):
+        raise ModelExecutionError("LesionDiffusion generated arrays differ from the input grid")
+    if not np.all(np.isfinite(image_data)) or not np.all(np.isfinite(lesion_data)):
+        raise ModelExecutionError("LesionDiffusion generated arrays contain non-finite voxels")
+    lesion = (lesion_data[_input_grid(geometry.output_reference)] == 2).astype(np.uint8)
+    if not np.any(lesion):
+        raise ModelExecutionError("LesionDiffusion mask output does not contain lesion label 2")
+    images: list[tuple[HostArray, str]] = [(image_data, "synthetic_image")]
+    if output_region == "box":
+        localized, facts = localize_output(
+            original=geometry.source_data,
+            generated=cast(NumericArray, image_data),
+            bbox=cast(
+                tuple[slice, slice, slice],
+                bbox_slices(geometry.center, geometry.bbox_size_voxel, geometry.reference.shape),
+            ),
+            spacing_mm=cast(
+                tuple[float, float, float],
+                tuple(float(value) for value in geometry.reference.header.get_zooms()[:3]),
+            ),
+        )
+        images = [(localized, "synthetic_image"), (image_data, "raw_synthetic_image")]
+        generation_spec["compositing"] = facts
+    for data, role, dtype in (
+        *((data, role, np.float32) for data, role in images),
+        (lesion, "target_mask", np.uint8),
+    ):
+        _save_like_reference(
+            data=data,
+            reference=geometry.output_reference,
+            destination=outputs[role],
+            dtype=dtype,
+        )
+    generation_spec["output_validation"] = {
+        "schema_version": 1,
+        "lesion_voxel_count": int(lesion.sum()),
+        "finite": True,
+        "method": "input_grid_shape_and_finite_voxels",
+    }
+
+
+def _save_like_reference(
+    *,
+    data: HostArray,
+    reference: NiftiImage,
+    destination: Path,
+    dtype: type[np.generic],
+) -> None:
+    """Write ``data`` cropped to ``reference``'s grid, keeping its affine, qform and sform."""
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    header = nib.Nifti1Header.from_header(reference.header)
+    header.set_data_dtype(dtype)
+    cropped = np.asarray(data, dtype=dtype)[_input_grid(reference)]
+    output = nib.Nifti1Image(cropped, reference.affine, header)
+    qform, qcode = reference.get_qform(coded=True)
+    sform, scode = reference.get_sform(coded=True)
+    output.set_qform(reference.affine if qform is None else qform, int(qcode))
+    output.set_sform(reference.affine if sform is None else sform, int(scode))
+    nib.save(output, str(destination))
+
+
+def _input_grid(reference: NiftiImage) -> tuple[slice, ...]:
+    """Drop the trailing ``_pad_to_even`` voxels; the origin is unchanged."""
+    return tuple(slice(0, int(size)) for size in reference.shape[:3])
+
+
+def output_paths(output: Path, output_region: str = DEFAULT_OUTPUT_REGION) -> dict[str, Path]:
+    """Map each output role to its file; ``box`` mode adds ``raw_synthetic_image``."""
+    paths = {
+        "synthetic_image": output / _SYNTHETIC_CT,
+        "target_mask": output / _LESION_MASK,
+        "organ_mask": output / _ORGAN_MASK,
+    }
+    if output_region == "box":
+        paths["raw_synthetic_image"] = output / _RAW_SYNTHETIC_CT
+    return paths
+
+
+def localize_output(
+    *,
+    original: NumericArray,
+    generated: NumericArray,
+    bbox: tuple[slice, slice, slice],
+    spacing_mm: tuple[float, float, float],
+    margin_mm: float = LOCALIZATION_MARGIN_MM,
+) -> tuple[FloatArray, dict[str, object]]:
+    """Composite the generated CT into the original CT around the box.
+
+    Inside ``bbox`` the generated CT is kept. A voxel whose center lies less than
+    ``margin_mm`` from the box (Euclidean distance in mm, from the nearest box voxel
+    center) takes ``w * generated + (1 - w) * original`` with
+    ``w = 0.5 * (1 + cos(pi * d / margin_mm))``; every other voxel is the original CT.
+
+    Args:
+        original: Standardized input CT on the even-padded grid.
+        generated: Full generated CT on the same grid.
+        bbox: Box as slices, from ``bbox_slices``.
+        spacing_mm: Voxel spacing (X, Y, Z) in mm.
+        margin_mm: Feather width in mm.
+
+    Returns:
+        ``(localized_ct, facts)``: a float32 array and a record of the blend policy.
+
+    Raises:
+        ModelExecutionError: If ``original`` and ``generated`` differ in shape.
+    """
+    if original.shape != generated.shape:
+        raise ModelExecutionError("LesionDiffusion raw output shape does not match the original CT")
+    spacing = np.asarray(spacing_mm, dtype=np.float64)
+    radius = np.ceil(margin_mm / spacing).astype(int)
+    start = np.asarray([int(value.start) for value in bbox])
+    stop = np.asarray([int(value.stop) for value in bbox])
+    low = np.maximum(0, start - radius)
+    high = np.minimum(np.asarray(original.shape[:3]), stop + radius)
+    region = cast(
+        tuple[slice, slice, slice],
+        tuple(slice(int(a), int(b)) for a, b in zip(low, high, strict=True)),
+    )
+    squared = np.zeros(tuple(int(value) for value in high - low), dtype=np.float64)
+    for axis in range(3):
+        coordinates = np.arange(int(low[axis]), int(high[axis]))
+        offset = (
+            np.where(
+                coordinates < start[axis],
+                start[axis] - coordinates,
+                np.where(coordinates >= stop[axis], coordinates - (stop[axis] - 1), 0),
+            )
+            * spacing[axis]
+        )
+        shape = [1, 1, 1]
+        shape[axis] = offset.size
+        squared = squared + (offset**2).reshape(shape)
+    distance = np.sqrt(squared)
+    weights = np.zeros(distance.shape, dtype=np.float64)
+    affected = distance < margin_mm
+    weights[affected] = 0.5 * (1.0 + np.cos(np.pi * distance[affected] / margin_mm))
+    localized = np.asarray(original, dtype=np.float32).copy()
+    raw = np.asarray(generated[region], dtype=np.float32)
+    window = localized[region]
+    transition = (weights > 0) & (weights < 1)
+    window[transition] = (
+        raw[transition] * weights[transition] + window[transition] * (1.0 - weights[transition])
+    ).astype(np.float32)
+    localized[bbox] = generated[bbox]
+    return localized, {
+        "policy": "bbox_generated_cosine_feather_to_original_ct",
+        "margin_mm": margin_mm,
+        "blend_weight": "0.5 * (1 + cos(pi * distance_mm / margin_mm))",
+        "distance_metric": "euclidean_voxel_center_distance_in_physical_mm",
+        "bounding_box": {
+            "start_voxel": [int(value) for value in start],
+            "stop_voxel_exclusive": [int(value) for value in stop],
+        },
+        "affected_region": {
+            "start_voxel": [int(value) for value in low],
+            "stop_voxel_exclusive": [int(value) for value in high],
+            "weighted_voxel_count": int(np.count_nonzero(affected)),
+        },
+        "outside_affected_region": "exact_original_ct",
+    }
+
+
+def _with_comma(value: str) -> str:
+    # Upstream report phrases are comma-terminated.
+    stripped = value.strip().rstrip(",")
+    return f"{stripped},"
+
+
+def _json_safe(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {
+            str(key): _json_safe(item) for key, item in cast(Mapping[object, object], value).items()
+        }
+    if isinstance(value, list | tuple):
+        return [_json_safe(item) for item in cast(Sequence[object], value)]
+    if isinstance(value, np.generic):
+        return cast(object, value.item())
+    return value
+
+
+__all__ = [
+    "MODEL",
+    "LesionDiffusionOptions",
+    "load_conversion",
+    "load_stage",
+    "require_weights",
+    "run",
+    "run_native_pipeline",
+    "select_lesion_component",
+    "source_organ_label",
+]