Upload folder using huggingface_hub (part 2)

.gitattributes

@@ -1289,3 +1289,12 @@ ComfyUI-MiniMaxH3-Context-Loop/ComfyUI-MAINodes/assets/uniform_vs_adaptive_sbs.m
 ComfyUI-MiniMaxH3-Context-Loop/ComfyUI-MAINodes/docs/latents/frame0.png filter=lfs diff=lfs merge=lfs -text
 ComfyUI-MiniMaxH3-Context-Loop/ComfyUI-MAINodes/docs/latents/frame72.png filter=lfs diff=lfs merge=lfs -text
 ComfyUI-MiniMaxH3-Context-Loop/__pycache__/chain_nodes.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/__pycache__/upscale_nodes.cpython-312.pyc filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/assets/social-preview.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/docs/assets/minimax-h3-context-loop-0.5-to-0.6-major-improvements.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/example_workflows/assets/h3_v06_courier_greenhouse_arrival.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/example_workflows/assets/h3_v06_courier_greenhouse_delivery.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/example_workflows/assets/jigen_market_garden_doom_last.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/example_workflows/assets/jigen_market_garden_doom_opening.png filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/example_workflows/assets/soldier_crabs_bribie_island_cc0.webm filter=lfs diff=lfs merge=lfs -text
+ComfyUI-MiniMaxH3-Context-Loop/example_workflows/assets/soldier_crabs_reference_cc0.png filter=lfs diff=lfs merge=lfs -text

ComfyUI-MiniMaxH3-Context-Loop/__pycache__/upscale_nodes.cpython-312.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:97a887900e16849e99ee7f73dff27148020bcfd63e4c26c37464afe39df2b0ee
+size 167903

ComfyUI-MiniMaxH3-Context-Loop/asset_store.py

@@ -0,0 +1,397 @@
+"""Portable, versioned media bindings for saved H3 chain runs."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import uuid
+from datetime import datetime, timezone
+from typing import Any
+
+
+# The canvas keeps a small number of direct loader sockets. Semantic Anchor
+# Bundle contributes many loader bindings through one dedicated Run Manager
+# socket, so the persisted manifest accepts a larger bounded collection.
+MAX_DIRECT_ASSET_BINDINGS = 12
+MAX_ASSET_BINDINGS = 128
+ASSET_MANIFEST_FORMAT = "h3_chain_assets_v1"
+ASSET_ROLES = ("picture", "video", "audio_reference", "source_track")
+
+
+def _safe_name(value: Any, fallback: str = "asset") -> str:
+    text = re.sub(r"[^A-Za-z0-9._-]+", "_", str(value or "").strip())
+    text = text.strip("._-")
+    return (text or fallback)[:128]
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).isoformat(
+        timespec="seconds").replace("+00:00", "Z")
+
+
+def _atomic_json(path: str, value: Any) -> None:
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temporary = "%s.%s.tmp" % (path, uuid.uuid4().hex)
+    try:
+        with open(temporary, "w", encoding="utf-8") as handle:
+            json.dump(value, handle, ensure_ascii=False, indent=2, sort_keys=True)
+            handle.write("\n")
+        os.replace(temporary, path)
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+
+
+def _read_json(path: str) -> Any:
+    with open(path, "r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _inside(root: str, path: str) -> bool:
+    try:
+        return os.path.commonpath(
+            (os.path.realpath(root), os.path.realpath(path))) == os.path.realpath(root)
+    except ValueError:
+        return False
+
+
+def _file_sha256(path: str) -> str:
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        while True:
+            chunk = handle.read(1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _role_group(role: str) -> str:
+    if role == "picture":
+        return "images"
+    if role == "video":
+        return "video"
+    return "audio"
+
+
+def _binding_id(value: Any) -> str:
+    text = str(value or "").strip()
+    if re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", text):
+        return text
+    return uuid.uuid4().hex
+
+
+class RunAssetStore:
+    """Save loader-backed media and materialize missing-input fallbacks."""
+
+    def __init__(self, output_root: str, input_root: str | None):
+        self.output_root = os.path.realpath(os.path.abspath(output_root))
+        self.input_root = (os.path.realpath(os.path.abspath(input_root))
+                           if input_root is not None else None)
+        self.chains_root = os.path.join(self.output_root, "h3_chains")
+
+    def _run_dir(self, run_name: Any) -> tuple[str, str]:
+        run = _safe_name(run_name, "")
+        if not run:
+            raise ValueError("A non-empty H3 chain run_name is required.")
+        path = os.path.realpath(os.path.join(self.chains_root, run))
+        if not _inside(self.output_root, path):
+            raise ValueError("H3 asset run path escapes the output directory.")
+        return path, run
+
+    def _manifest_path(self, run_name: Any) -> tuple[str, str, str]:
+        directory, run = self._run_dir(run_name)
+        return (os.path.join(directory, "references", "manifest.json"),
+                directory, run)
+
+    def _source_path(self, value: Any) -> str | None:
+        if self.input_root is None or not isinstance(value, str):
+            return None
+        name = value.strip()
+        if not name:
+            return None
+        if name.endswith("[input]"):
+            name = name[:-7].rstrip()
+        elif name.endswith("[output]") or name.endswith("[temp]"):
+            return None
+        path = os.path.abspath(os.path.join(self.input_root, name))
+        if not _inside(self.input_root, path) or not os.path.isfile(path):
+            return None
+        return path
+
+    def _archived_path(self, run_dir: str, relative: Any) -> str | None:
+        if not isinstance(relative, str) or not relative:
+            return None
+        path = os.path.realpath(os.path.join(run_dir, relative))
+        if not _inside(run_dir, path) or not os.path.isfile(path):
+            return None
+        return path
+
+    def _copy_to_archive(self, source: str, run_dir: str,
+                         role: str) -> dict[str, Any]:
+        group = _role_group(role)
+        destination_dir = os.path.join(run_dir, "references", group)
+        os.makedirs(destination_dir, exist_ok=True)
+        suffix = os.path.splitext(source)[1][:24]
+        basename = _safe_name(os.path.splitext(os.path.basename(source))[0])
+        temporary = os.path.join(destination_dir, ".%s.tmp" % uuid.uuid4().hex)
+        digest = hashlib.sha256()
+        size = 0
+        try:
+            with open(source, "rb") as source_handle, open(temporary, "xb") as target:
+                while True:
+                    chunk = source_handle.read(1024 * 1024)
+                    if not chunk:
+                        break
+                    target.write(chunk)
+                    digest.update(chunk)
+                    size += len(chunk)
+            sha256 = digest.hexdigest()
+            filename = "%s_%s%s" % (sha256, basename, suffix)
+            destination = os.path.join(destination_dir, filename)
+            if (os.path.isfile(destination)
+                    and os.path.getsize(destination) == size
+                    and _file_sha256(destination) == sha256):
+                os.unlink(temporary)
+            else:
+                os.replace(temporary, destination)
+            relative = os.path.relpath(destination, run_dir).replace(os.sep, "/")
+            return {
+                "relative_path": relative,
+                "sha256": sha256,
+                "size": size,
+                "saved_at": _utc_now(),
+                "original_basename": os.path.basename(source),
+            }
+        finally:
+            try:
+                os.unlink(temporary)
+            except FileNotFoundError:
+                pass
+
+    @staticmethod
+    def _normalized_binding(raw: Any) -> dict[str, Any] | None:
+        if not isinstance(raw, dict):
+            return None
+        role = str(raw.get("role") or "").strip()
+        if role not in ASSET_ROLES:
+            return None
+        output_slot = raw.get("output_slot", 0)
+        node_id = raw.get("node_id")
+        try:
+            output_slot = int(output_slot)
+        except (TypeError, ValueError):
+            output_slot = 0
+        return {
+            "binding_id": _binding_id(raw.get("binding_id")),
+            "label": str(raw.get("label") or role).strip()[:160],
+            "role": role,
+            "node_id": str(node_id) if node_id is not None else "",
+            "node_type": str(raw.get("node_type") or "").strip()[:160],
+            "node_title": str(raw.get("node_title") or "").strip()[:160],
+            "output_slot": max(0, output_slot),
+            "output_type": str(raw.get("output_type") or "").strip()[:80],
+            "widget_name": str(raw.get("widget_name") or "").strip()[:120],
+            "original_value": str(raw.get("original_value") or "").strip()[:4096],
+        }
+
+    def load_manifest(self, run_name: Any) -> dict[str, Any] | None:
+        path, _directory, _run = self._manifest_path(run_name)
+        if not os.path.isfile(path):
+            return None
+        document = _read_json(path)
+        if (not isinstance(document, dict)
+                or document.get("format") != ASSET_MANIFEST_FORMAT
+                or not isinstance(document.get("bindings"), list)):
+            raise ValueError("Saved H3 reference manifest has an unsupported format.")
+        return document
+
+    def summary(self, run_name: Any) -> dict[str, Any]:
+        _manifest_path, run_dir, _run = self._manifest_path(run_name)
+        manifest = self.load_manifest(run_name)
+        if manifest is None:
+            return {"asset_count": 0, "asset_bytes": 0}
+        archived = 0
+        for binding in manifest.get("bindings", []):
+            archive = binding.get("archive") if isinstance(binding, dict) else None
+            if isinstance(archive, dict):
+                archived += 1
+        total = 0
+        archive_files = 0
+        # Count the actual retained snapshots, including older versions and
+        # safe orphaned files left by a removed binding. Recovery data is not
+        # deleted implicitly merely to make a manifest smaller.
+        for group in ("images", "audio", "video"):
+            directory = os.path.join(run_dir, "references", group)
+            if not os.path.isdir(directory):
+                continue
+            with os.scandir(directory) as entries:
+                for entry in entries:
+                    if entry.name.startswith(".") or not entry.is_file(
+                            follow_symlinks=False):
+                        continue
+                    archive_files += 1
+                    total += max(0, entry.stat(follow_symlinks=False).st_size)
+        return {
+            "asset_count": len(manifest.get("bindings", [])),
+            "archived_asset_count": archived,
+            "asset_file_count": archive_files,
+            "asset_bytes": total,
+        }
+
+    def save(self, run_name: Any, bindings: Any,
+             policies: dict[str, Any] | None = None) -> dict[str, Any]:
+        manifest_path, run_dir, run = self._manifest_path(run_name)
+        if not isinstance(bindings, list):
+            raise ValueError("H3 asset bindings must be a JSON list.")
+        if len(bindings) > MAX_ASSET_BINDINGS:
+            raise ValueError("H3 Run Manager supports at most %d asset bindings."
+                             % MAX_ASSET_BINDINGS)
+        policies = policies if isinstance(policies, dict) else {}
+        enabled = {
+            "images": bool(policies.get("images", True)),
+            "audio": bool(policies.get("audio", True)),
+            "video": bool(policies.get("video", False)),
+        }
+        try:
+            old_manifest = self.load_manifest(run) or {}
+        except (OSError, ValueError, json.JSONDecodeError):
+            old_manifest = {}
+        old_bindings = {
+            item.get("binding_id"): item
+            for item in old_manifest.get("bindings", [])
+            if isinstance(item, dict) and item.get("binding_id")
+        }
+        saved = []
+        warnings = []
+        for raw in bindings:
+            binding = self._normalized_binding(raw)
+            if binding is None:
+                warnings.append("Ignored one binding with an unsupported media role.")
+                continue
+            previous = old_bindings.get(binding["binding_id"], {})
+            versions = list(previous.get("versions") or [])
+            prior_archive = previous.get("archive")
+            same_source = (
+                previous.get("original_value") == binding["original_value"])
+            source = self._source_path(binding["original_value"])
+            group = _role_group(binding["role"])
+            archive = (prior_archive if same_source
+                       and isinstance(prior_archive, dict) else None)
+            if (isinstance(prior_archive, dict) and not same_source
+                    and not any(item.get("sha256") == prior_archive.get("sha256")
+                                for item in versions if isinstance(item, dict))):
+                versions.append(prior_archive)
+            if source is not None and enabled[group]:
+                next_archive = self._copy_to_archive(source, run_dir, binding["role"])
+                if (archive and archive.get("sha256") != next_archive.get("sha256")
+                        and not any(item.get("sha256") == archive.get("sha256")
+                                    for item in versions if isinstance(item, dict))):
+                    versions.append(archive)
+                archive = next_archive
+            elif not enabled[group] and archive:
+                if not any(item.get("sha256") == archive.get("sha256")
+                           for item in versions if isinstance(item, dict)):
+                    versions.append(archive)
+                archive = None
+            if source is None:
+                warnings.append(
+                    "%s: original input file is unavailable%s." % (
+                        binding["label"],
+                        " and no archived fallback exists" if not archive else ""))
+            binding["archive_policy"] = (
+                "fallback_copy" if enabled[group] else "path_only")
+            binding["source_available_when_saved"] = source is not None
+            if archive:
+                binding["archive"] = archive
+            if versions:
+                binding["versions"] = versions
+            saved.append(binding)
+
+        document = {
+            "format": ASSET_MANIFEST_FORMAT,
+            "run_name": run,
+            "updated_at": _utc_now(),
+            "policies": enabled,
+            "bindings": saved,
+        }
+        _atomic_json(manifest_path, document)
+        summary = self.summary(run)
+        return {
+            "run_name": run,
+            "manifest": os.path.relpath(manifest_path, self.output_root).replace(os.sep, "/"),
+            "bindings": saved,
+            "warnings": warnings,
+            **summary,
+        }
+
+    def _materialize_archive(self, run: str, archived_path: str,
+                             archive: dict[str, Any]) -> str:
+        if self.input_root is None:
+            raise ValueError("The ComfyUI input directory is unavailable.")
+        os.makedirs(self.input_root, exist_ok=True)
+        digest = str(archive.get("sha256") or "")
+        basename = _safe_name(
+            archive.get("original_basename") or os.path.basename(archived_path))
+        filename = "h3_%s_%s_%s" % (run, digest[:16] or "asset", basename)
+        destination = os.path.join(self.input_root, filename)
+        if not _inside(self.input_root, destination):
+            raise ValueError("Restored H3 asset path escapes the input directory.")
+        expected = str(archive.get("sha256") or "")
+        destination_ready = (os.path.isfile(destination)
+                             and (not expected
+                                  or _file_sha256(destination) == expected))
+        if not destination_ready:
+            temporary = "%s.%s.tmp" % (destination, uuid.uuid4().hex)
+            try:
+                shutil.copy2(archived_path, temporary)
+                if expected and _file_sha256(temporary) != expected:
+                    raise ValueError("Archived fallback failed its SHA-256 check.")
+                os.replace(temporary, destination)
+            finally:
+                try:
+                    os.unlink(temporary)
+                except FileNotFoundError:
+                    pass
+        return os.path.basename(destination)
+
+    def prepare_restore(self, run_name: Any) -> dict[str, Any]:
+        _path, run_dir, run = self._manifest_path(run_name)
+        manifest = self.load_manifest(run)
+        if manifest is None:
+            return {"run_name": run, "bindings": [], "warnings": []}
+        restored = []
+        warnings = []
+        for original in manifest.get("bindings", []):
+            if not isinstance(original, dict):
+                continue
+            binding = dict(original)
+            source = self._source_path(binding.get("original_value"))
+            if source is not None:
+                binding["restore_value"] = binding.get("original_value")
+                binding["restore_source"] = "original_input"
+            else:
+                archive = binding.get("archive")
+                archived_path = self._archived_path(
+                    run_dir, archive.get("relative_path")
+                    if isinstance(archive, dict) else None)
+                if archived_path is None:
+                    binding["restore_source"] = "missing"
+                    warnings.append("%s: original and archived files are missing."
+                                    % binding.get("label", binding.get("role", "asset")))
+                else:
+                    try:
+                        binding["restore_value"] = self._materialize_archive(
+                            run, archived_path, archive)
+                        binding["restore_source"] = "archived_fallback"
+                    except (OSError, ValueError) as exc:
+                        binding["restore_source"] = "missing"
+                        warnings.append("%s: %s" % (
+                            binding.get("label", binding.get("role", "asset")), exc))
+            restored.append(binding)
+        return {"run_name": run, "bindings": restored, "warnings": warnings}

ComfyUI-MiniMaxH3-Context-Loop/audio_track_contract.py

@@ -0,0 +1,26 @@
+"""JSON-only contracts for grouped project audio; no media or runtime imports."""
+
+AUDIO_TRACK_ROLES = ("full_mix", "vocals", "instrumental")
+
+
+def audio_track_bindings(value, assets):
+    if value is None:
+        return None
+    if not isinstance(value, dict) or set(value) - set(AUDIO_TRACK_ROLES):
+        raise ValueError("Audio tracks must map full_mix, vocals, and instrumental to asset IDs.")
+    known = {str(asset.get("id") or ""): asset for asset in assets}
+    result = {}
+    for role in AUDIO_TRACK_ROLES:
+        raw = value.get(role, "")
+        if raw is not None and not isinstance(raw, str):
+            raise ValueError("Audio track IDs must be strings.")
+        asset_id = str(raw or "").strip()
+        if asset_id and (asset_id not in known or known[asset_id].get("kind") != "audio"):
+            raise ValueError("Audio track %s must reference an existing audio asset in this project." % role)
+        result[role] = asset_id
+    selected = [asset_id for asset_id in result.values() if asset_id]
+    if not selected:
+        raise ValueError("Select at least one audio track, or reset to the original single track.")
+    if len(selected) != len(set(selected)):
+        raise ValueError("The same audio asset cannot be both a mix and a stem, or both stems.")
+    return result

ComfyUI-MiniMaxH3-Context-Loop/av_timing.py

@@ -0,0 +1,96 @@
+"""Exact MiniMax H3 picture/audio timeline helpers.
+
+H3 picture runs live on a 24 fps clock while generated audio latents live on
+a 40 Hz clock. A decoded audio stream can consequently land a few
+milliseconds either side of its exact frame-derived duration. Small grid
+mismatches are time-conformed here instead of being repaired with silence.
+"""
+
+from __future__ import annotations
+
+from fractions import Fraction
+import logging
+
+import torch
+
+try:
+    import torchaudio
+except ImportError:
+    torchaudio = None
+
+
+_LOG = logging.getLogger("minimax_h3_context_loop.av_timing")
+
+# Private AUDIO mapping fields passed only between Loop Trim and Segment Save.
+# Keeping this transport inside the existing AUDIO value avoids another public
+# socket and another copy of the same decoded stream in user workflows.
+AUDIO_WITH_OVERLAP_WAVEFORM_KEY = "_h3_audio_with_overlap_waveform"
+AUDIO_WITH_OVERLAP_FRAMES_KEY = "_h3_audio_with_overlap_frames"
+AUDIO_TRIM_FRAMES_KEY = "_h3_audio_trim_frames"
+
+
+def sample_boundary_from_seconds(seconds: float, sample_rate: int) -> int:
+    """Return the nearest PCM sample on one absolute time boundary."""
+    return int(round(float(seconds) * int(sample_rate)))
+
+
+def sample_boundary_from_frames(
+        frame_position: int, sample_rate: int, fps: int = 24) -> int:
+    """Return the nearest PCM sample on one absolute video-frame boundary."""
+    return int(round(int(frame_position) / float(fps) * int(sample_rate)))
+
+
+def conform_waveform_length(
+        waveform, samples: int, label: str,
+        max_fractional_change: float = 0.005):
+    """Time-conform a small decoder/grid mismatch to an exact sample span.
+
+    A larger discrepancy is likely incorrect wiring or timing metadata and is
+    rejected instead of being hidden by a large resample.
+    """
+    target = int(samples)
+    current = int(waveform.shape[-1])
+    if current == target:
+        return waveform
+    if current <= 0 or target <= 0:
+        raise ValueError(
+            "%s has an invalid audio sample length %d -> %d." %
+            (label, current, target))
+
+    fractional_change = abs(target - current) / float(target)
+    if fractional_change > float(max_fractional_change):
+        raise ValueError(
+            "%s differs from its exact frame timeline by %.3f%% "
+            "(%d -> %d samples), too large for H3 audio time-conformance." %
+            (label, fractional_change * 100.0, current, target))
+
+    ratio = Fraction(target, current).limit_denominator(10000)
+    if torchaudio is not None:
+        conformed = torchaudio.functional.resample(
+            waveform, int(ratio.denominator), int(ratio.numerator))
+    else:
+        shape = tuple(waveform.shape)
+        conformed = torch.nn.functional.interpolate(
+            waveform.reshape(-1, 1, current),
+            size=target,
+            mode="linear",
+            align_corners=False,
+        ).reshape(*shape[:-1], target)
+
+    # A rational approximation or resampler backend may miss by one sample.
+    # Correct the residual by interpolation so silence is never introduced.
+    if int(conformed.shape[-1]) != target:
+        shape = tuple(conformed.shape)
+        conformed = torch.nn.functional.interpolate(
+            conformed.reshape(-1, 1, int(conformed.shape[-1])),
+            size=target,
+            mode="linear",
+            align_corners=False,
+        ).reshape(*shape[:-1], target)
+
+    _LOG.info(
+        "%s time-conformed %d -> %d audio samples (%+.4f%%) to match "
+        "the exact video timeline",
+        label, current, target,
+        (target - current) / float(current) * 100.0)
+    return conformed

ComfyUI-MiniMaxH3-Context-Loop/chapter_resolution.py

@@ -0,0 +1,97 @@
+"""Chapter-local geometry; no media mutation or implicit latent resizing."""
+
+
+def normalize_resolution(value, label="Chapter resolution"):
+    if value is None:
+        return None
+    if not isinstance(value, dict) or set(value) != {"width", "height"}:
+        raise ValueError(f"{label} must contain width and height, or be null to inherit.")
+    result = {}
+    for key in ("width", "height"):
+        number = value[key]
+        if (isinstance(number, bool) or not isinstance(number, int)
+                or number < 32 or number > 16384 or number % 32):
+            raise ValueError(f"{label} {key} must be a multiple of 32 between 32 and 16384.")
+        result[key] = number
+    return result
+
+
+def scene_resolution(plan, index):
+    shot = plan["shots"][int(index) - 1]
+    return dict(shot.get("resolution") or {
+        key: int(plan["compatibility"][key]) for key in ("width", "height")
+    })
+
+
+def saved_resolution(segment, metadata=None):
+    """Prefer the immutable scene's recorded geometry, including legacy saves."""
+    metadata = metadata or {}
+    dependency = segment.get("scene_dependency") or metadata.get("scene_dependency") or {}
+    candidates = (
+        segment.get("resolution"),
+        dependency.get("scopes", {}).get("global_generation"),
+        metadata.get("compatibility"),
+    )
+    for candidate in candidates:
+        if isinstance(candidate, dict) and all(key in candidate for key in ("width", "height")):
+            return normalize_resolution(
+                {key: candidate[key] for key in ("width", "height")},
+                "Saved scene resolution")
+    return None
+
+
+def apply_chapter_resolutions(plan, chapters, locked_resolutions):
+    """Resolve one size per chapter, pinning inherited chapters to saved locks.
+
+    Only chapter-sized geometry is authored. Locking a saved scene prevents a
+    Plan-default edit from changing the interpretation of its whole chapter.
+    Explicit conflicting chapter edits fail; locks never waive integrity checks.
+    """
+    starts = sorted(chapters, key=lambda row: int(row["start_scene"]))
+    if not starts or int(starts[0]["start_scene"]) > 1:
+        implicit = {"start_scene": 1, "title": "Unassigned",
+                    "start_scene_id": plan["shots"][0]["id"], "text": ""}
+        identifier = "unassigned"
+        while any(row["id"] == identifier for row in chapters):
+            identifier += "_"
+        implicit["id"] = identifier
+        starts.insert(0, implicit)
+    for offset, chapter in enumerate(starts):
+        start = int(chapter["start_scene"])
+        end = int(starts[offset + 1]["start_scene"]) - 1 if offset + 1 < len(starts) else len(plan["shots"])
+        shots = plan["shots"][start - 1:end]
+        explicit = normalize_resolution(chapter.get("resolution"))
+        locked = [locked_resolutions[shot["id"]] for shot in shots
+                  if shot["id"] in locked_resolutions]
+        sizes = {(row["width"], row["height"]) for row in locked}
+        if len(sizes) > 1:
+            raise ValueError(f"{chapter['title']} has locked saved scenes at different resolutions. "
+                             "Place the resolution boundary between chapters before continuing.")
+        pinned = locked[0] if locked else None
+        if pinned and explicit and explicit != pinned:
+            raise ValueError(f"{chapter['title']} is pinned by locked saved scenes to "
+                             f"{pinned['width']}x{pinned['height']}. Unlock those scenes "
+                             "before changing this chapter's resolution; saved files are unchanged.")
+        resolution = pinned or explicit
+        if resolution:
+            if pinned:
+                chapter["resolution"] = dict(pinned)
+                if chapter not in chapters:
+                    # Recovery must retain a pin before the first authored marker.
+                    chapters.insert(0, chapter)
+            for shot in shots:
+                shot["resolution"] = dict(resolution)
+
+
+def common_saved_resolution(segments, label="Video assembly"):
+    sizes = {tuple(value[key] for key in ("width", "height"))
+             for segment in segments
+             if (value := saved_resolution(segment)) is not None}
+    if len(sizes) > 1:
+        raise ValueError(f"{label} contains different chapter resolutions. Export each chapter "
+                         "separately, then resize to a common output size before joining. "
+                         "Saved scenes and exports are unchanged.")
+    if sizes:
+        width, height = next(iter(sizes))
+        return {"width": width, "height": height}
+    return None

ComfyUI-MiniMaxH3-Context-Loop/chapter_snapshot_retirement.py

@@ -0,0 +1,107 @@
+"""Preview-confirmed retirement of chapter recovery pins, never clip media."""
+
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+
+from .checkpoint_manager import (
+    CheckpointDeleteBlocked, CheckpointGraphManager, _fingerprint,
+    _strict_run_name, checkpoint_run_lock,
+)
+
+
+class ChapterSnapshotManager:
+    def __init__(self, output_root):
+        self.root = Path(output_root).resolve()
+
+    def _path(self, address):
+        if not isinstance(address, str) or not address:
+            raise ValueError("Select a saved chapter snapshot.")
+        parts = PurePosixPath(address).parts
+        if (PurePosixPath(address).is_absolute() or ".." in parts or
+                "\\" in address or str(PurePosixPath(address)) != address):
+            raise ValueError("Invalid chapter snapshot address.")
+        path = self.root
+        for part in parts:
+            path /= part
+            if path.is_symlink():
+                raise ValueError("Snapshot retirement cannot follow symlinks.")
+        if not path.resolve().is_relative_to(self.root):
+            raise ValueError("Chapter snapshot escapes the output directory.")
+        return path
+
+    def _preview(self, run, address):
+        path = self._path(address)
+        parts = PurePosixPath(address).parts
+        if not (len(parts) == 6 and parts[:3] == ("h3_chains", run, "chapters")
+                and parts[4] == "manifests"
+                and re.fullmatch(r"[0-9a-f]{32}\.json", parts[5])):
+            raise ValueError("Select an immutable chapter snapshot inside this run.")
+        if not path.is_file():
+            raise FileNotFoundError("The chapter snapshot is no longer available.")
+        data = json.loads(path.read_text(encoding="utf-8"))
+        if not isinstance(data, dict):
+            raise ValueError("Chapter snapshot must be a JSON object.")
+        chapter = data.get("chapter")
+        if (data.get("format") != "h3_chain_chapter_manifest_v1"
+                or data.get("run_name") != run
+                or not isinstance(chapter, dict)
+                or not isinstance(chapter.get("number"), int)
+                or chapter["number"] < 1
+                or not parts[3].startswith("%02d_" % chapter["number"])
+                or not isinstance(data.get("segments"), list)
+                or not data["segments"]
+                or any(not isinstance(s, dict) or not isinstance(s.get("index"), int)
+                       for s in data["segments"])):
+            raise ValueError("Invalid chapter snapshot identity.")
+        identity = {k: v for k, v in data.items()
+                    if k not in ("sealed_at", "chapter_manifest_id", "chapter_manifest_path")}
+        if (_fingerprint(identity)[:32] != path.stem
+                or data.get("chapter_manifest_id") != path.stem
+                or data.get("chapter_manifest_path") != address):
+            raise ValueError("Chapter snapshot failed its identity check.")
+        destination = path.parent.parent / "retired_manifests" / path.name
+        retired_address = destination.relative_to(self.root).as_posix()
+        self._path(retired_address)
+        if destination.exists():
+            raise ValueError("A retired copy already exists; it will not be overwritten.")
+        active, _ = CheckpointGraphManager(str(self.root)).active_selection(run)
+        scenes = [{"scene": s["index"], "revision": s.get("revision", ""),
+                   "active": active.get(s["index"]) == s.get("revision")}
+                  for s in data["segments"]]
+        stat = path.stat()
+        snapshot = _fingerprint({
+            "document": data, "active": active,
+            "file": [stat.st_dev, stat.st_ino, stat.st_size, stat.st_mtime_ns, stat.st_ctime_ns],
+            "path": address, "retired_path": retired_address,
+        })
+        return {"ok": True, "allowed": True, "run_name": run,
+                "path": address, "retired_path": retired_address,
+                "chapter_number": chapter["number"],
+                "chapter_title": str(chapter.get("title") or "Chapter %d" % chapter["number"]),
+                "chapter_manifest_id": path.stem, "scenes": scenes,
+                "snapshot": snapshot,
+                "message": "Retiring releases only this snapshot's recovery pins. "
+                           "Its metadata is archived; no clips, active pointers, "
+                           "references, processing takes or exports are deleted."}
+
+    def retirement_preview(self, run_name, address):
+        run = _strict_run_name(run_name)
+        with checkpoint_run_lock(str(self.root), run):
+            return self._preview(run, address)
+
+    def retire(self, run_name, address, expected_snapshot=""):
+        run = _strict_run_name(run_name)
+        with checkpoint_run_lock(str(self.root), run):
+            preview = self._preview(run, address)
+            if not expected_snapshot or expected_snapshot != preview["snapshot"]:
+                raise CheckpointDeleteBlocked(
+                    "Chapter snapshot or active selection changed; preview retirement again.", preview)
+            path = self._path(preview["path"])
+            destination = self._path(preview["retired_path"])
+            destination.parent.mkdir(exist_ok=True)
+            os.rename(path, destination)
+            return {**preview, "message": "Chapter snapshot %s retired; recovery metadata "
+                    "kept at %s. No clips were deleted." %
+                    (preview["chapter_manifest_id"][:8], preview["retired_path"])}

ComfyUI-MiniMaxH3-Context-Loop/checkpoint_manager.py

@@ -0,0 +1,1541 @@
+"""Dependency-aware discovery and deletion for H3 scene checkpoints."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import re
+import threading
+import uuid
+from collections import defaultdict, deque
+from datetime import datetime, timezone
+from typing import Any
+
+
+_REVISION = re.compile(r"clip_(\d{4})\.([0-9a-f]{32})\.json")
+_ACTIVE = re.compile(r"clip_(\d{4})\.json")
+_ARTIFACT_KEYS = (
+    "segment", "checkpoint", "prompt_file", "generated_audio",
+    "blend_segment", "revision_metadata",
+)
+_ARTIFACT_KINDS = {
+    "segment": "Segment video",
+    "checkpoint": "Continuation checkpoint",
+    "prompt_file": "Prompt snapshot",
+    "generated_audio": "Generated audio",
+    "blend_segment": "Blend-ready video",
+    "revision_metadata": "Revision metadata",
+    "review_preview": "Review preview",
+    "active_pointer": "Active scene pointer",
+}
+def checkpoint_audio_context_length(
+        continuation: str, visual: int, audio: int,
+        generated_continuity: str = "", source_audio_target: str = "") -> int:
+    """Interpret saved predecessor audio using the generation contract.
+
+    Legacy saves recorded the configured audio span even when AV conditioning
+    returned early with no picture prefix. AV modes consume a joint prefix;
+    Guide modes can consume audio alone. Unknown modes/policies retain their
+    recorded dependency rather than treating missing evidence as independence.
+    This must never consult a mutable Plan to reinterpret an existing take.
+    """
+    if generated_continuity == "off" or source_audio_target == "locked":
+        return 0
+    if visual >= 0 and continuation in (
+            "masked_av", "tapered_av", "feathered_av", "audio_feathered_av",
+            "drift_control_av", "color_stable_drift_av"):
+        return visual if audio > 0 else audio
+    return audio
+
+
+_RUN_LOCKS: dict[tuple[str, str], threading.RLock] = {}
+_RUN_LOCKS_GUARD = threading.Lock()
+_LOG = logging.getLogger("minimax_h3_context_loop.checkpoints")
+
+
+def _canonical_json(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True,
+                      separators=(",", ":"))
+
+
+def _fingerprint(value: Any) -> str:
+    return hashlib.sha256(_canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def _safe_name(value: Any) -> str:
+    text = re.sub(r"[^A-Za-z0-9._-]+", "_", str(value or "").strip())
+    return text.strip("._-")[:96]
+
+
+def _strict_run_name(value: Any) -> str:
+    """Validate mutation targets without silently choosing a different Run."""
+    requested = str(value or "").strip()
+    normalized = _safe_name(requested)
+    if not normalized or requested != normalized:
+        raise ValueError("A valid exact H3 chain run_name is required.")
+    return normalized
+
+
+def checkpoint_run_lock(output_root: str, run_name: Any) -> threading.RLock:
+    """Return the process-local mutation lock shared by save and delete."""
+    root = os.path.realpath(os.path.abspath(output_root))
+    run = _safe_name(run_name)
+    key = (root, run)
+    with _RUN_LOCKS_GUARD:
+        return _RUN_LOCKS.setdefault(key, threading.RLock())
+
+
+def checkpoint_revision_token(scene: Any, segment: Any) -> str:
+    """Return the immutable revision id used by current and legacy saves.
+
+    Builds before revision sidecars stored the transaction id only in the
+    versioned MP4 and safetensors filenames. Both artifacts were committed by
+    the same transaction, so a matching filename token is the original
+    revision identity rather than a newly invented one.
+    """
+    if not isinstance(segment, dict):
+        return ""
+    try:
+        index = int(scene)
+    except (TypeError, ValueError):
+        return ""
+    stored = str(segment.get("revision") or "").strip().lower()
+    if re.fullmatch(r"[0-9a-f]{32}", stored):
+        return stored
+    tokens = set()
+    patterns = {
+        "segment": r"clip_%04d\.([0-9a-f]{32})\.mp4" % index,
+        "checkpoint": r"clip_%04d\.([0-9a-f]{32})\.safetensors" % index,
+    }
+    for key, pattern in patterns.items():
+        name = os.path.basename(str(segment.get(key) or "")).lower()
+        match = re.fullmatch(pattern, name)
+        if match is not None:
+            tokens.add(match.group(1))
+    return next(iter(tokens)) if len(tokens) == 1 else ""
+
+
+class CheckpointDeleteBlocked(ValueError):
+    """Deletion was safe to inspect but is blocked by checkpoint state."""
+
+    def __init__(self, message: str, preview: dict[str, Any]):
+        super().__init__(message)
+        self.preview = preview
+
+
+class CheckpointGraphManager:
+    """Build lineage graphs and remove only dependency-free revisions."""
+
+    def __init__(self, output_root: str):
+        self.output_root = os.path.realpath(os.path.abspath(output_root))
+        self.chains_root = os.path.realpath(os.path.join(
+            self.output_root, "h3_chains"))
+
+    @staticmethod
+    def _inside(root: str, path: str) -> bool:
+        try:
+            return os.path.commonpath([root, path]) == root
+        except ValueError:
+            return False
+
+    def _run_dir(self, run_name: Any) -> tuple[str, str]:
+        run = _safe_name(run_name)
+        if not run:
+            raise ValueError("A non-empty H3 chain run_name is required.")
+        path = os.path.realpath(os.path.join(self.chains_root, run))
+        if not self._inside(self.output_root, path):
+            raise ValueError("H3 checkpoint run path escapes the output directory.")
+        return path, run
+
+    def _artifact_path(self, value: Any) -> str:
+        text = str(value or "").strip()
+        if not text:
+            raise ValueError("Checkpoint artifact path is empty.")
+        path = os.path.realpath(
+            text if os.path.isabs(text) else os.path.join(self.output_root, text))
+        if not self._inside(self.output_root, path):
+            raise ValueError("Checkpoint artifact path escapes the output directory.")
+        return path
+
+    def _output_item(self, path: str) -> dict[str, str]:
+        relative = os.path.relpath(path, self.output_root)
+        return {
+            "filename": os.path.basename(relative),
+            "subfolder": os.path.dirname(relative),
+            "type": "output",
+        }
+
+    @staticmethod
+    def _read_json(path: str) -> Any:
+        with open(path, "r", encoding="utf-8") as handle:
+            return json.load(handle)
+
+    @staticmethod
+    def _atomic_json(path: str, value: Any) -> None:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        temporary = "%s.write.%s.tmp" % (path, uuid.uuid4().hex)
+        try:
+            with open(temporary, "w", encoding="utf-8") as handle:
+                json.dump(value, handle, ensure_ascii=False, indent=2)
+                handle.write("\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, path)
+        finally:
+            try:
+                os.unlink(temporary)
+            except FileNotFoundError:
+                pass
+
+    @staticmethod
+    def _integer(value: Any, fallback: int = 0) -> int:
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            return int(fallback)
+
+    @staticmethod
+    def _created_at(metadata: dict[str, Any], path: str) -> str:
+        stored = str(metadata.get("created_at") or
+                     metadata.get("segment", {}).get("created_at") or "")
+        if stored:
+            return stored
+        return datetime.fromtimestamp(
+            os.path.getmtime(path), timezone.utc).isoformat(
+                timespec="seconds").replace("+00:00", "Z")
+
+    @classmethod
+    def _chapter_starts(cls, run_dir: str) -> set[int]:
+        """Read editorial branch roots without making notes executable state."""
+        path = os.path.join(run_dir, "editorial.json")
+        try:
+            document = cls._read_json(path)
+            chapters = document.get("chapters")
+            if not isinstance(chapters, list):
+                return set()
+            return {
+                int(chapter.get("start_scene", 0))
+                for chapter in chapters if isinstance(chapter, dict)
+                and int(chapter.get("start_scene", 0)) > 0
+            }
+        except (OSError, TypeError, ValueError, json.JSONDecodeError,
+                AttributeError):
+            return set()
+
+    def _effective_context(
+            self, scene: int, segment: dict[str, Any],
+            compatibility: dict[str, Any]) -> tuple[str, int, int]:
+        """Return context that actually depended on the preceding checkpoint."""
+        continuation = str(
+            segment.get("continuation_mode") or
+            compatibility.get("continuation_mode") or "guide")
+        context = self._integer(
+            segment.get("resolved_context_length",
+                        segment.get("context_length",
+                                    compatibility.get("context_length", 0))))
+        has_resolved_audio = "resolved_audio_context_length" in segment
+        if has_resolved_audio:
+            audio_context = self._integer(
+                segment.get("resolved_audio_context_length"))
+        elif "audio_context_length" in segment:
+            audio_context = self._integer(segment.get("audio_context_length"))
+        elif "audio_context_length" in compatibility:
+            audio_context = self._integer(
+                compatibility.get("audio_context_length"))
+        else:
+            audio_context = context
+        if scene <= 1:
+            return continuation, 0, 0
+        audio_mode = str(compatibility.get("audio_mode") or "source_track")
+        if (not has_resolved_audio and continuation != "masked_av" and
+                audio_mode not in (
+                    "generated_audio", "source_plus_timeline")):
+            audio_context = 0
+        audio_context = checkpoint_audio_context_length(
+            continuation, context, audio_context,
+            str(segment.get("generated_continuity") or "").lower(),
+            str(segment.get("source_audio_target") or "").lower())
+        return continuation, max(0, context), max(0, audio_context)
+
+    def _adopt_legacy_active_revisions(
+            self, checkpoint_dir: str, run: str) -> int:
+        """Create the small revision sidecars omitted by pre-manager saves.
+
+        Existing video, prompt, audio, and safetensors artifacts remain in
+        place. The canonical ``clip_NNNN.json`` pointer is also left byte-for-
+        byte unchanged so adopting an old run is non-destructive.
+        """
+        if not os.path.isdir(checkpoint_dir):
+            return 0
+        active: dict[int, tuple[str, dict[str, Any], str]] = {}
+        for filename in sorted(os.listdir(checkpoint_dir)):
+            match = _ACTIVE.fullmatch(filename)
+            if match is None:
+                continue
+            path = os.path.realpath(os.path.join(checkpoint_dir, filename))
+            try:
+                metadata = self._read_json(path)
+                segment = metadata.get("segment")
+                scene = int(match.group(1))
+                if (not isinstance(segment, dict) or
+                        int(segment.get("index", -1)) != scene or
+                        _safe_name(metadata.get("run_name") or run) != run):
+                    continue
+                revision = checkpoint_revision_token(scene, segment)
+                if revision:
+                    active[scene] = (revision, metadata, path)
+            except (OSError, TypeError, ValueError, json.JSONDecodeError,
+                    AttributeError):
+                continue
+
+        adopted = 0
+        for scene in sorted(active):
+            revision, metadata, pointer_path = active[scene]
+            sidecar = os.path.realpath(os.path.join(
+                checkpoint_dir, "clip_%04d.%s.json" % (scene, revision)))
+            if os.path.isfile(sidecar):
+                continue
+            segment = dict(metadata["segment"])
+            segment.update({
+                "revision": revision,
+                "revision_metadata": os.path.relpath(sidecar, self.output_root),
+            })
+            predecessor = active.get(scene - 1)
+            if predecessor is not None and not segment.get(
+                    "predecessor_revision"):
+                predecessor_revision, predecessor_metadata, _pointer = predecessor
+                predecessor_segment = predecessor_metadata.get("segment")
+                segment["predecessor_revision"] = predecessor_revision
+                if isinstance(predecessor_segment, dict):
+                    predecessor_hash = str(
+                        predecessor_segment.get("checkpoint_sha256") or "")
+                    if predecessor_hash:
+                        segment["predecessor_checkpoint_sha256"] = predecessor_hash
+                    segment.setdefault(
+                        "branch_id", str(predecessor_segment.get("branch_id") or
+                                         predecessor_revision))
+            snapshot = dict(metadata)
+            snapshot["segment"] = segment
+            snapshot.setdefault(
+                "created_at", self._created_at(metadata, pointer_path))
+            snapshot["legacy_adoption"] = {
+                "version": 1,
+                "source": "active_pointer",
+                "source_metadata": os.path.relpath(
+                    pointer_path, self.output_root),
+            }
+            self._atomic_json(sidecar, snapshot)
+            adopted += 1
+        if adopted:
+            _LOG.info(
+                "H3 Checkpoint Manager adopted %d legacy active revision%s for "
+                "run %s without copying media or latent files.",
+                adopted, "" if adopted == 1 else "s", run)
+        return adopted
+
+    @classmethod
+    def select_active_lineage(
+            cls, segments: dict[int, dict[str, Any]], chapter_starts=()
+            ) -> tuple[dict[int, dict[str, Any]], dict[int, str]]:
+        """Select coherent chapter prefixes, without modifying saved pointers.
+
+        A single-scene rerender can leave canonical pointers belonging to the
+        old branch. Their files remain recoverable, but they are not selected
+        until that lineage is explicitly activated or attributed again.
+        """
+        active, stale = {}, {}
+        roots = {1, *chapter_starts}
+        for scene, segment in sorted(segments.items()):
+            reason = ""
+            if scene not in roots:
+                parent = active.get(scene - 1)
+                if parent is None:
+                    reason = "The preceding scene is not on the active chapter branch."
+                else:
+                    expected = str(
+                        segment.get("predecessor_revision") or "").lower()
+                    digest = str(
+                        segment.get("predecessor_checkpoint_sha256") or "")
+                    if expected and expected != checkpoint_revision_token(
+                            scene - 1, parent):
+                        reason = "This take belongs to a different predecessor revision."
+                    elif digest and digest != str(
+                            parent.get("checkpoint_sha256") or ""):
+                        reason = "This take belongs to a different predecessor checkpoint."
+            if reason:
+                stale[scene] = reason
+            else:
+                active[scene] = segment
+        return active, stale
+
+    def active_selection(
+            self, run_name: Any) -> tuple[dict[int, str], dict[int, str]]:
+        """Cheap, read-only selection shared by recovery and the UI."""
+        run_dir, _run = self._run_dir(run_name)
+        checkpoint_dir = os.path.join(run_dir, "checkpoints")
+        segments = {}
+        if os.path.isdir(checkpoint_dir):
+            for filename in os.listdir(checkpoint_dir):
+                match = _ACTIVE.fullmatch(filename)
+                if match is None:
+                    continue
+                try:
+                    segment = self._read_json(os.path.join(
+                        checkpoint_dir, filename)).get("segment")
+                    scene = int(match.group(1))
+                    if (isinstance(segment, dict) and
+                            int(segment.get("index", -1)) == scene):
+                        segments[scene] = segment
+                except (OSError, TypeError, ValueError, AttributeError):
+                    continue
+        active, stale = self.select_active_lineage(
+            segments, self._chapter_starts(run_dir))
+        return {scene: checkpoint_revision_token(scene, segment)
+                for scene, segment in active.items()}, stale
+
+    def _active_revisions(self, checkpoint_dir: str) -> dict[int, str]:
+        active: dict[int, str] = {}
+        if not os.path.isdir(checkpoint_dir):
+            return active
+        for filename in os.listdir(checkpoint_dir):
+            match = _ACTIVE.fullmatch(filename)
+            if match is None:
+                continue
+            try:
+                metadata = self._read_json(os.path.join(checkpoint_dir, filename))
+                segment = metadata.get("segment")
+                if not isinstance(segment, dict):
+                    continue
+                scene = int(match.group(1))
+                if int(segment.get("index", -1)) != scene:
+                    continue
+                revision = checkpoint_revision_token(scene, segment)
+                if revision:
+                    active[scene] = revision
+            except (OSError, TypeError, ValueError, json.JSONDecodeError,
+                    AttributeError):
+                continue
+        return active
+
+    def _recorded_dependency_keys(
+            self, record: dict[str, Any],
+            parent_key: tuple[int, str] | None,
+            records: dict[tuple[int, str], dict[str, Any]],
+            by_hash: dict[tuple[int, str], list[tuple[int, str]]]
+            ) -> list[tuple[int, str]]:
+        """Resolve saved visual and generated-audio dependencies exactly."""
+        segment = record["_segment"]
+        scene = int(record["scene"])
+        found: list[tuple[int, str]] = []
+
+        def add(scene_value: Any, revision_value: Any,
+                hash_value: Any) -> None:
+            try:
+                source_scene = int(scene_value)
+            except (TypeError, ValueError):
+                return
+            revision = str(revision_value or "").lower()
+            key = ((source_scene, revision)
+                   if re.fullmatch(r"[0-9a-f]{32}", revision) else None)
+            if key not in records:
+                digest = str(hash_value or "")
+                candidates = by_hash.get((source_scene, digest), [])
+                key = candidates[0] if digest and len(candidates) == 1 else None
+            if key in records and key not in found:
+                found.append(key)
+
+        visual_frames = max(0, self._integer(record.get("context_length")))
+        if visual_frames:
+            visual_blocks = segment.get("visual_context_blocks")
+            if isinstance(visual_blocks, list):
+                for block in visual_blocks:
+                    if not isinstance(block, dict):
+                        continue
+                    add(block.get("source_scene"),
+                        block.get("source_revision"),
+                        block.get("source_checkpoint_sha256"))
+            else:
+                source_scene = self._integer(
+                    segment.get("visual_context_source_scene"), scene - 1)
+                if source_scene == scene - 1 and not segment.get(
+                        "visual_context_source_revision"):
+                    if parent_key in records:
+                        found.append(parent_key)
+                else:
+                    add(source_scene,
+                        segment.get("visual_context_source_revision"),
+                        segment.get(
+                            "visual_context_source_checkpoint_sha256"))
+                lead_frames = max(0, self._integer(
+                    segment.get("visual_context_lead_frames")))
+                if lead_frames:
+                    add(segment.get("visual_context_lead_source_scene"),
+                        segment.get("visual_context_lead_source_revision"),
+                        segment.get(
+                            "visual_context_lead_checkpoint_sha256"))
+
+        dependency = record["_metadata"].get("scene_dependency")
+        scopes = dependency.get("scopes") if isinstance(dependency, dict) else None
+        incoming = (scopes.get("incoming_boundary")
+                    if isinstance(scopes, dict) else None)
+        generated = str(
+            segment.get("generated_continuity",
+                        incoming.get("generated_continuity")
+                        if isinstance(incoming, dict) else "off") or "off").lower()
+        audio_frames = max(0, self._integer(
+            segment.get("resolved_audio_context_length",
+                        incoming.get("audio_context_length"))
+            if isinstance(incoming, dict) else
+            record.get("audio_context_length")))
+        audio_frames = checkpoint_audio_context_length(
+            str(record.get("continuation_mode") or ""), visual_frames,
+            audio_frames, generated,
+            str(segment.get("source_audio_target") or "").lower())
+        if generated == "on" and audio_frames and parent_key in records:
+            if parent_key not in found:
+                found.append(parent_key)
+        return found
+
+    def _scan(self, run_name: Any, *, adopt_legacy: bool = True) -> dict[str, Any]:
+        run_dir, run = self._run_dir(run_name)
+        checkpoint_dir = os.path.join(run_dir, "checkpoints")
+        review_dir = os.path.join(run_dir, "reviews")
+        chapter_starts = self._chapter_starts(run_dir)
+        if adopt_legacy:
+            self._adopt_legacy_active_revisions(checkpoint_dir, run)
+        active = self._active_revisions(checkpoint_dir)
+        selected, stale = self.active_selection(run)
+        records: dict[tuple[int, str], dict[str, Any]] = {}
+        if os.path.isdir(checkpoint_dir):
+            for filename in sorted(os.listdir(checkpoint_dir)):
+                match = _REVISION.fullmatch(filename)
+                if match is None:
+                    continue
+                metadata_path = os.path.realpath(os.path.join(
+                    checkpoint_dir, filename))
+                try:
+                    metadata = self._read_json(metadata_path)
+                    segment = metadata.get("segment")
+                    if not isinstance(segment, dict):
+                        continue
+                    scene = int(segment.get("index", int(match.group(1))))
+                    revision = str(
+                        segment.get("revision") or match.group(2)).lower()
+                    stored_run = _safe_name(metadata.get("run_name") or run)
+                    if (scene != int(match.group(1)) or
+                            revision != match.group(2) or stored_run != run):
+                        continue
+                    compatibility = metadata.get("compatibility")
+                    if not isinstance(compatibility, dict):
+                        compatibility = {}
+                    adoption = metadata.get("adoption")
+                    if not isinstance(adoption, dict):
+                        adoption = {}
+                    continuation, context, audio_context = (
+                        self._effective_context(scene, segment, compatibility))
+                    segment_path = self._artifact_path(segment.get("segment"))
+                    checkpoint_path = self._artifact_path(
+                        segment.get("checkpoint"))
+                    record = {
+                        "scene": scene,
+                        "scene_id": str(
+                            segment.get("id") or "clip_%04d" % scene),
+                        "revision": revision,
+                        "active": selected.get(scene) == revision,
+                        "pointer_active": active.get(scene) == revision,
+                        "inactive_reason": (
+                            stale.get(scene, "")
+                            if active.get(scene) == revision else ""),
+                        "ready": (os.path.isfile(segment_path) and
+                                  os.path.isfile(checkpoint_path)),
+                        "raw_frames": self._integer(
+                            segment.get("raw_frames")),
+                        "delivered_frames": self._integer(
+                            segment.get("delivered_frames")),
+                        "seed": str(segment.get("seed") or ""),
+                        "steps": self._integer(segment.get("steps")),
+                        "created_at": self._created_at(metadata, metadata_path),
+                        "branch_id": str(segment.get("branch_id") or ""),
+                        "forked_from_branch_id": str(
+                            segment.get("forked_from_branch_id") or ""),
+                        "adopted_from_revision": str(
+                            segment.get("adopted_from_revision") or
+                            adoption.get("source_revision") or "").lower(),
+                        "predecessor_revision": str(
+                            segment.get("predecessor_revision") or "").lower(),
+                        "predecessor_checkpoint_sha256": str(
+                            segment.get("predecessor_checkpoint_sha256") or ""),
+                        "checkpoint_sha256": str(
+                            segment.get("checkpoint_sha256") or ""),
+                        "segment_sha256": str(
+                            segment.get("segment_sha256") or ""),
+                        "continuation_mode": continuation,
+                        "context_length": context,
+                        "audio_context_length": audio_context,
+                        "compatibility": {
+                            key: compatibility[key] for key in (
+                                "width", "height", "fps", "audio_mode",
+                                "generation_fingerprint", "encode_mode",
+                                "anchor_mode", "crop")
+                            if key in compatibility
+                        },
+                        "prompt_preview": re.sub(
+                            r"\s+", " ", str(
+                                segment.get("scene_prompt") or
+                                segment.get("prompt") or "").strip())[:240],
+                        "prompt": str(segment.get("prompt") or
+                                      segment.get("scene_prompt") or ""),
+                        "take_kind": str(segment.get("take_kind") or
+                                         "generation"),
+                        "alternate_of_revision": str(
+                            segment.get("alternate_of_revision") or "").lower(),
+                        "alternate_media_mode": str(
+                            segment.get("alternate_media_mode") or ""),
+                        "_metadata": metadata,
+                        "_metadata_path": metadata_path,
+                        "_segment": segment,
+                        "_segment_path": segment_path,
+                        "_checkpoint_path": checkpoint_path,
+                        "_chapter_root": scene in chapter_starts,
+                        "_parent": None,
+                        "_children": [],
+                        "_dependencies": [],
+                        "_dependents": [],
+                        "_lineage_issue": "",
+                    }
+                    records[(scene, revision)] = record
+                except (OSError, TypeError, ValueError, json.JSONDecodeError,
+                        AttributeError):
+                    continue
+
+        by_hash: dict[tuple[int, str], list[tuple[int, str]]] = defaultdict(list)
+        for key, record in records.items():
+            digest = record["checkpoint_sha256"]
+            if digest:
+                by_hash[(record["scene"], digest)].append(key)
+        for key, record in records.items():
+            scene = record["scene"]
+            if scene <= 1:
+                continue
+            revision = record["predecessor_revision"]
+            digest = record["predecessor_checkpoint_sha256"]
+            parent_key = (scene - 1, revision) if revision else None
+            parent = records.get(parent_key) if parent_key else None
+            if parent is None and digest:
+                candidates = by_hash.get((scene - 1, digest), [])
+                if len(candidates) == 1:
+                    parent_key = candidates[0]
+                    parent = records[parent_key]
+            if parent is None:
+                dependencies = self._recorded_dependency_keys(
+                    record, None, records, by_hash)
+                for dependency_key in dependencies:
+                    record["_dependencies"].append(dependency_key)
+                    records[dependency_key]["_dependents"].append(key)
+                if not record["_chapter_root"]:
+                    record["_lineage_issue"] = "missing predecessor"
+                continue
+            if digest and parent["checkpoint_sha256"] != digest:
+                record["_lineage_issue"] = "predecessor hash mismatch"
+                # Keep the declared revision edge for conservative cleanup:
+                # corrupted lineage must never make its parent look deletable.
+            # A chapter start is a branch root even though immutable metadata
+            # keeps its original predecessor as provenance. Preserve a
+            # deletion dependency only when that scene actually consumed
+            # predecessor picture/generated-audio context.
+            dependencies = self._recorded_dependency_keys(
+                record, parent_key, records, by_hash)
+            if not record["_chapter_root"]:
+                record["_parent"] = parent_key
+                parent["_children"].append(key)
+                if parent_key not in dependencies:
+                    dependencies.append(parent_key)
+            for dependency_key in dependencies:
+                record["_dependencies"].append(dependency_key)
+                records[dependency_key]["_dependents"].append(key)
+
+        # An editorial alternate is not a lineage child, but its immutable
+        # files are meaningful only while the same-scene base revision still
+        # exists. Model that as a cleanup dependency so Checkpoint Manager
+        # requires deleting unused alternates before their base take.
+        for key, record in records.items():
+            if record.get("take_kind") != "editorial_alternate":
+                continue
+            base_key = (record["scene"], record["alternate_of_revision"])
+            base = records.get(base_key)
+            if base is None:
+                if not record["_lineage_issue"]:
+                    record["_lineage_issue"] = "missing alternate base"
+                continue
+            if base_key not in record["_dependencies"]:
+                record["_dependencies"].append(base_key)
+            if key not in base["_dependents"]:
+                base["_dependents"].append(key)
+
+        try:
+            review_names = os.listdir(review_dir) if os.path.isdir(
+                review_dir) else []
+        except OSError:
+            review_names = []
+        segment_hash_counts: dict[str, int] = defaultdict(int)
+        artifact_path_counts: dict[str, int] = defaultdict(int)
+        for record in records.values():
+            if record["segment_sha256"]:
+                segment_hash_counts[record["segment_sha256"]] += 1
+            for artifact_key in _ARTIFACT_KEYS:
+                artifact_value = record["_segment"].get(artifact_key)
+                if not isinstance(artifact_value, str) or not artifact_value:
+                    continue
+                try:
+                    artifact_path_counts[self._artifact_path(artifact_value)] += 1
+                except ValueError:
+                    continue
+        return {
+            "run_dir": run_dir,
+            "run_name": run,
+            "checkpoint_dir": checkpoint_dir,
+            "review_dir": review_dir,
+            "review_names": review_names,
+            "chapter_starts": chapter_starts,
+            "records": records,
+            "segment_hash_counts": segment_hash_counts,
+            "artifact_path_counts": artifact_path_counts,
+        }
+
+    @staticmethod
+    def _attribution_source(record: dict[str, Any]) -> str:
+        return str(record.get("adopted_from_revision") or
+                   record.get("revision") or "").lower()
+
+    def _attributable_without_predecessor(
+            self, record: dict[str, Any]) -> bool:
+        """Return whether a saved scene can safely receive another parent."""
+        dependency = record["_metadata"].get("scene_dependency")
+        if not isinstance(dependency, dict):
+            dependency = record["_segment"].get("scene_dependency")
+        scopes = dependency.get("scopes") if isinstance(dependency, dict) else None
+        incoming = (scopes.get("incoming_boundary")
+                    if isinstance(scopes, dict) else None)
+        segment = record["_segment"]
+        incoming = incoming if isinstance(incoming, dict) else {}
+        # Resolved values describe the saved take; old scope snapshots can
+        # still contain inherited defaults. Never consult today's edited Plan.
+        visual = segment.get("resolved_context_length", incoming.get(
+            "context_length", record.get("context_length")))
+        audio = segment.get("resolved_audio_context_length", incoming.get(
+            "audio_context_length", record.get("audio_context_length")))
+        generated = str(segment.get("generated_continuity", incoming.get(
+            "generated_continuity", ""))).lower()
+        try:
+            visual, audio = int(visual), int(audio)
+        except (TypeError, ValueError):
+            return False
+        if visual < 0 or audio < 0:
+            return False
+        compatibility = record["_metadata"].get("compatibility")
+        compatibility = compatibility if isinstance(compatibility, dict) else {}
+        continuation = str(segment.get("continuation_mode") or
+                           incoming.get("continuation_mode") or
+                           compatibility.get("continuation_mode") or
+                           record.get("continuation_mode") or "")
+        audio = checkpoint_audio_context_length(
+            continuation, visual, audio, generated,
+            str(segment.get("source_audio_target") or "").lower())
+        # Unknown legacy audio policy must not silently mean 'off'.
+        return visual == 0 and (audio == 0 or (audio > 0 and generated == "off"))
+
+    def _artifacts(self, scan: dict[str, Any], record: dict[str, Any]
+                   ) -> list[dict[str, Any]]:
+        run_dir = scan["run_dir"]
+        allowed_roots = [os.path.realpath(os.path.join(run_dir, name)) for name in (
+            "segments", "checkpoints", "generated_audio", "blend_segments",
+            "reviews")]
+        paths: dict[str, tuple[str, bool]] = {
+            record["_metadata_path"]: ("revision_metadata", False),
+        }
+        for key in _ARTIFACT_KEYS:
+            value = record["_segment"].get(key)
+            if not isinstance(value, str) or not value:
+                continue
+            path = self._artifact_path(value)
+            paths.setdefault(path, (key, False))
+        video_hash = record["segment_sha256"][:12]
+        if video_hash and os.path.isdir(scan["review_dir"]):
+            prefix = "clip_%04d.%s." % (record["scene"], video_hash)
+            shared = scan["segment_hash_counts"].get(
+                record["segment_sha256"], 0) > 1
+            for candidate in scan["review_names"]:
+                if candidate.startswith(prefix) and candidate.endswith(
+                        ".review.mp4"):
+                    path = os.path.realpath(os.path.join(
+                        scan["review_dir"], candidate))
+                    paths[path] = ("review_preview", shared)
+
+        expected_prefix = "clip_%04d.%s" % (
+            record["scene"], record["revision"])
+        canonical = os.path.realpath(os.path.join(
+            scan["checkpoint_dir"], "clip_%04d.json" % record["scene"]))
+        artifacts = []
+        for path, (kind, shared) in sorted(paths.items()):
+            if path == canonical:
+                raise ValueError("Refusing to manage an active checkpoint pointer.")
+            if not any(self._inside(root, path) for root in allowed_roots):
+                raise ValueError("Checkpoint revision owns an unexpected path.")
+            path_references = scan["artifact_path_counts"].get(path, 0)
+            shared = bool(shared or path_references > 1)
+            adopted_prefix = "clip_%04d.%s" % (
+                record["scene"], record.get("adopted_from_revision") or "")
+            owns_named_path = os.path.basename(path).startswith(expected_prefix)
+            adopts_named_path = bool(
+                record.get("adopted_from_revision") and
+                os.path.basename(path).startswith(adopted_prefix))
+            if (not self._inside(scan["review_dir"], path) and
+                    not owns_named_path and not adopts_named_path):
+                raise ValueError(
+                    "Checkpoint revision references a file owned by another revision.")
+            try:
+                exists = os.path.isfile(path)
+                stat_result = os.stat(path) if exists else None
+            except OSError:
+                exists = False
+                stat_result = None
+            size = int(stat_result.st_size) if stat_result is not None else 0
+            mtime_ns = (int(stat_result.st_mtime_ns)
+                        if stat_result is not None else 0)
+            artifacts.append({
+                "kind": kind,
+                "label": _ARTIFACT_KINDS.get(kind, kind.replace("_", " ").title()),
+                "path": os.path.relpath(path, self.output_root),
+                "exists": exists,
+                "size_bytes": size,
+                "shared": bool(shared),
+                "owned": not shared,
+                "_path": path,
+                "_mtime_ns": mtime_ns,
+            })
+        return artifacts
+
+    def _attribution_slot(
+            self, records: dict[tuple[int, str], dict[str, Any]],
+            leaf_key: tuple[int, str]) -> dict[str, Any] | None:
+        leaf = records[leaf_key]
+        scene = int(leaf["scene"]) + 1
+        if any(record["scene"] == scene and record["_chapter_root"]
+               for record in records.values()):
+            return None
+        already_attached = {
+            self._attribution_source(records[key])
+            for key in leaf["_children"] if key in records
+        }
+        candidates: dict[str, dict[str, Any]] = {}
+        blocked = []
+        for key, candidate in records.items():
+            if key[0] != scene or key == leaf_key or not candidate["ready"]:
+                continue
+            if candidate.get("take_kind") == "editorial_alternate":
+                continue
+            if candidate["_parent"] == leaf_key:
+                continue
+            if not self._attributable_without_predecessor(candidate):
+                blocked.append({
+                    "scene": scene, "revision": candidate["revision"],
+                    "reason": "Saved predecessor video/audio context is in use, "
+                              "or the saved metadata cannot prove it was unused. "
+                              "Changing the current Plan does not change a saved take.",
+                })
+                continue
+            source = self._attribution_source(candidate)
+            if not source or source in already_attached:
+                continue
+            previous = candidates.get(source)
+            if previous is None or candidate["revision"] == source:
+                candidates[source] = candidate
+        if not candidates and not blocked:
+            return None
+        ordered = sorted(candidates.values(), key=lambda item: (
+            str(item.get("created_at") or ""), item["revision"]), reverse=True)
+        return {
+            "scene": scene,
+            "parent_scene": leaf["scene"],
+            "parent_revision": leaf["revision"],
+            "blocked_candidates": blocked,
+            "candidates": [
+                {"scene": item["scene"], "revision": item["revision"]}
+                for item in ordered
+            ],
+        }
+
+    def _active_pointer_artifact(
+            self, scan: dict[str, Any], record: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Describe the mutable pointer removed by an active-tip rollback."""
+        path = os.path.realpath(os.path.join(
+            scan["checkpoint_dir"], "clip_%04d.json" % record["scene"]))
+        if not self._inside(scan["checkpoint_dir"], path):
+            raise ValueError("Active checkpoint pointer escapes its run directory.")
+        exists = os.path.isfile(path)
+        stat_result = os.stat(path) if exists else None
+        return {
+            "kind": "active_pointer",
+            "label": _ARTIFACT_KINDS["active_pointer"],
+            "path": os.path.relpath(path, self.output_root),
+            "exists": exists,
+            "size_bytes": int(stat_result.st_size) if stat_result else 0,
+            "shared": False,
+            "owned": True,
+            "_path": path,
+            "_mtime_ns": int(stat_result.st_mtime_ns) if stat_result else 0,
+        }
+
+    @staticmethod
+    def _descendant_keys(records: dict[tuple[int, str], dict[str, Any]],
+                         start: tuple[int, str]) -> list[tuple[int, str]]:
+        found = []
+        queue = deque(records[start]["_dependents"])
+        seen = set()
+        while queue:
+            key = queue.popleft()
+            if key in seen or key not in records:
+                continue
+            seen.add(key)
+            found.append(key)
+            queue.extend(records[key]["_dependents"])
+        return sorted(found, key=lambda item: (item[0], item[1]))
+
+    @staticmethod
+    def _chapter_bounds(scan: dict[str, Any], scene: int) -> tuple[int, int]:
+        records = scan["records"]
+        maximum = max((int(item[0]) for item in records), default=int(scene))
+        starts = sorted({1, *(
+            int(item) for item in scan.get("chapter_starts", set())
+            if int(item) > 0
+        )})
+        start = max((item for item in starts if item <= scene), default=1)
+        following = next((item for item in starts if item > scene), None)
+        return start, (following - 1 if following is not None else maximum)
+
+    def _public_graph(self, scan: dict[str, Any]) -> dict[str, Any]:
+        records = scan["records"]
+        lineage_keys = {
+            key for key, record in records.items()
+            if record.get("take_kind") != "editorial_alternate"
+        }
+        leaves = [
+            key for key in lineage_keys
+            if not any(child in lineage_keys
+                       for child in records[key]["_children"])
+            or (records[key]["active"] and not any(
+                child in lineage_keys and records[child]["active"]
+                for child in records[key]["_children"]))
+        ]
+        branch_paths = []
+        memberships: dict[tuple[int, str], list[dict[str, Any]]] = defaultdict(list)
+        for leaf_key in leaves:
+            path = []
+            cursor = leaf_key
+            seen = set()
+            while cursor in records and cursor not in seen:
+                seen.add(cursor)
+                if cursor in lineage_keys:
+                    path.append(cursor)
+                cursor = records[cursor]["_parent"]
+            path.reverse()
+            leaf = records[leaf_key]
+            active = bool(path) and all(records[key]["active"] for key in path)
+            branch_id = leaf["branch_id"] or leaf["revision"]
+            branch = {
+                "id": branch_id,
+                "label": "Active branch" if active else "Branch %s" % branch_id[:8],
+                "active": active,
+                "leaf_scene": leaf["scene"],
+                "leaf_revision": leaf["revision"],
+                "path": [{"scene": key[0], "revision": key[1]} for key in path],
+            }
+            slot = self._attribution_slot(records, leaf_key)
+            if slot is not None:
+                branch["attribution_slot"] = slot
+            branch_paths.append(branch)
+            membership = {"id": branch["id"], "label": branch["label"],
+                          "active": active}
+            for key in path:
+                memberships[key].append(membership)
+        branch_paths.sort(key=lambda item: (
+            not item["active"], -int(item["leaf_scene"]), item["id"]))
+
+        public_records = []
+        artifact_sizes: dict[str, int] = {}
+        record_artifact_paths: dict[tuple[int, str], dict[str, int]] = {}
+        for key in sorted(records):
+            record = records[key]
+            artifacts = self._artifacts(scan, record)
+            record_artifact_paths[key] = {
+                part["path"]: int(part["size_bytes"])
+                for part in artifacts if part["exists"]
+            }
+            artifact_sizes.update(record_artifact_paths[key])
+            reviews = [item for item in artifacts
+                       if item["kind"] == "review_preview" and item["exists"]]
+            video = (self._output_item(record["_segment_path"])
+                     if os.path.isfile(record["_segment_path"]) else None)
+            audio = None
+            audio_value = record["_segment"].get("generated_audio")
+            if isinstance(audio_value, str) and audio_value:
+                audio_path = self._artifact_path(audio_value)
+                if os.path.isfile(audio_path):
+                    audio = self._output_item(audio_path)
+            parent = record["_parent"]
+            children = []
+            for child_key in sorted(record["_children"]):
+                child = records[child_key]
+                if child.get("take_kind") == "editorial_alternate":
+                    continue
+                children.append({
+                    "scene": child["scene"],
+                    "scene_id": child["scene_id"],
+                    "revision": child["revision"],
+                    "continuation_mode": child["continuation_mode"],
+                    "context_length": child["context_length"],
+                    "audio_context_length": child["audio_context_length"],
+                })
+            item = {name: record[name] for name in (
+                "scene", "scene_id", "revision", "active", "ready",
+                "pointer_active", "inactive_reason",
+                "raw_frames", "delivered_frames", "seed", "steps",
+                "created_at", "branch_id", "forked_from_branch_id",
+                "adopted_from_revision",
+                "predecessor_revision",
+                "predecessor_checkpoint_sha256", "checkpoint_sha256",
+                "continuation_mode", "context_length", "audio_context_length",
+                "compatibility", "prompt_preview", "prompt", "take_kind",
+                "alternate_of_revision", "alternate_media_mode")}
+            item.update({
+                "size_bytes": sum(part["size_bytes"] for part in artifacts),
+                "owned_size_bytes": sum(
+                    part["size_bytes"] for part in artifacts if part["owned"]),
+                "shared_size_bytes": sum(
+                    part["size_bytes"] for part in artifacts if part["shared"]),
+                "missing_files": [part["label"] for part in artifacts
+                                  if not part["exists"]],
+                "video": video,
+                "audio": audio,
+                "preview_video": (
+                    self._output_item(reviews[-1]["_path"]) if reviews else None),
+                "parent": ({"scene": parent[0], "revision": parent[1]}
+                           if parent else None),
+                "dependencies": [
+                    {"scene": dependency[0], "revision": dependency[1]}
+                    for dependency in record["_dependencies"]
+                ],
+                "children": children,
+                "descendant_count": len(self._descendant_keys(records, key)),
+                "branches": memberships.get(key, []),
+                "lineage_status": record["_lineage_issue"] or (
+                    "chapter root" if record["_chapter_root"] else
+                    "root" if record["scene"] == 1 else "linked"),
+                "metadata_path": os.path.relpath(
+                    record["_metadata_path"], self.output_root),
+            })
+            public_records.append(item)
+        try:
+            editorial = self._read_json(os.path.join(
+                scan["run_dir"], "editorial.json"))
+            replacement_rows = editorial.get("replacements", [])
+        except (OSError, TypeError, ValueError, json.JSONDecodeError,
+                AttributeError):
+            replacement_rows = []
+        active_revisions = {
+            int(item["scene"]): str(item["revision"])
+            for item in public_records
+            if item["active"] and item["take_kind"] != "editorial_alternate"
+        }
+        selected_alternates = {
+            (self._integer(item.get("scene")),
+             str(item.get("alternate_revision") or "").lower())
+            for item in replacement_rows if isinstance(item, dict)
+            and str(item.get("base_revision") or "").lower() ==
+            active_revisions.get(self._integer(item.get("scene")), "")
+        }
+        by_key = {
+            (int(item["scene"]), str(item["revision"])): item
+            for item in public_records
+        }
+        for item in public_records:
+            if item["take_kind"] == "editorial_alternate":
+                item["used_in_final_cut"] = (
+                    (int(item["scene"]), str(item["revision"]))
+                    in selected_alternates)
+                base = by_key.get((
+                    int(item["scene"]), str(item["alternate_of_revision"])))
+                if base is not None:
+                    base.setdefault("alternates", []).append(item)
+        for item in public_records:
+            if item.get("alternates"):
+                item["alternates"].sort(key=lambda alternate: (
+                    not bool(alternate.get("used_in_final_cut")),
+                    str(alternate.get("created_at") or "")))
+        scenes = []
+        grouped: dict[int, list[dict[str, Any]]] = defaultdict(list)
+        for item in public_records:
+            grouped[item["scene"]].append(item)
+        for scene in sorted(grouped):
+            revisions = grouped[scene]
+            scene_artifacts: dict[str, int] = {}
+            for revision in revisions:
+                scene_artifacts.update(record_artifact_paths.get(
+                    (int(revision["scene"]), str(revision["revision"])), {}))
+            scenes.append({
+                "scene": scene,
+                "scene_id": next((item["scene_id"] for item in revisions
+                                  if item["active"]), revisions[0]["scene_id"]),
+                "revision_count": len(revisions),
+                "active_revision": next((item["revision"] for item in revisions
+                                         if item["active"]), ""),
+                "bytes": sum(scene_artifacts.values()),
+                "broken_count": sum(not item["ready"] for item in revisions),
+            })
+        graph_hash = _fingerprint([{
+            "scene": item["scene"], "revision": item["revision"],
+            "active": item["active"], "ready": item["ready"],
+            "parent": item["parent"],
+            "dependencies": item["dependencies"],
+            "size_bytes": item["size_bytes"],
+        } for item in public_records])
+        return {
+            "run_name": scan["run_name"],
+            "graph_hash": graph_hash,
+            "scenes": scenes,
+            "branches": branch_paths,
+            "revisions": public_records,
+            "summary": {
+                "scene_count": len(scenes),
+                "revision_count": len(public_records),
+                "branch_count": len(branch_paths),
+                "bytes": sum(artifact_sizes.values()),
+                "broken_count": sum(not item["ready"] for item in public_records),
+            },
+        }
+
+    def graph(self, run_name: Any, *, adopt_legacy: bool = True) -> dict[str, Any]:
+        run_dir, run = self._run_dir(run_name)
+        if not os.path.isdir(run_dir):
+            raise FileNotFoundError("H3 run %r does not exist." % run)
+        return self._public_graph(self._scan(run, adopt_legacy=adopt_legacy))
+
+    def attribute(
+            self, run_name: Any, parent_scene: Any, parent_revision: Any,
+            candidate_scene: Any, candidate_revision: Any) -> dict[str, Any]:
+        """Attach an independent saved candidate to another branch tip.
+
+        Only metadata is created. Video, audio, prompt, and checkpoint files
+        remain shared with the original immutable candidate revision.
+        """
+        run_dir, run = self._run_dir(run_name)
+        parent_scene_number = int(parent_scene)
+        candidate_scene_number = int(candidate_scene)
+        parent_token = str(parent_revision or "").strip().lower()
+        candidate_token = str(candidate_revision or "").strip().lower()
+        if not re.fullmatch(r"[0-9a-f]{32}", parent_token):
+            raise ValueError("Parent revision must be a 32-character revision id.")
+        if not re.fullmatch(r"[0-9a-f]{32}", candidate_token):
+            raise ValueError("Candidate revision must be a 32-character revision id.")
+        if candidate_scene_number != parent_scene_number + 1:
+            raise ValueError(
+                "A candidate can only be attributed to the immediately preceding scene slot.")
+        with checkpoint_run_lock(self.output_root, run):
+            if not os.path.isdir(run_dir):
+                raise FileNotFoundError("H3 run %r does not exist." % run)
+            scan = self._scan(run)
+            records = scan["records"]
+            parent_key = (parent_scene_number, parent_token)
+            candidate_key = (candidate_scene_number, candidate_token)
+            parent = records.get(parent_key)
+            candidate = records.get(candidate_key)
+            if parent is None:
+                raise FileNotFoundError(
+                    "Parent scene %d revision %s is no longer available." %
+                    (parent_scene_number, parent_token[:8]))
+            if candidate is None:
+                raise FileNotFoundError(
+                    "Candidate scene %d revision %s is no longer available." %
+                    (candidate_scene_number, candidate_token[:8]))
+            if (parent.get("take_kind") == "editorial_alternate" or
+                    candidate.get("take_kind") == "editorial_alternate"):
+                raise ValueError(
+                    "Picture-only editorial alternates cannot be attached to "
+                    "generation lineage. Select them in Plan Studio's final "
+                    "cut instead.")
+            if not parent["ready"] or not candidate["ready"]:
+                raise ValueError(
+                    "Both the target branch tip and candidate must have intact video and checkpoint files.")
+            if candidate["_parent"] == parent_key:
+                raise ValueError("This candidate is already attached to that branch.")
+            if not self._attributable_without_predecessor(candidate):
+                raise ValueError(
+                    "This candidate consumes predecessor video or generated-audio context and cannot be safely attributed to another branch.")
+
+            source_revision = self._attribution_source(candidate)
+            for record in records.values():
+                adoption = record["_metadata"].get("adoption")
+                if not isinstance(adoption, dict):
+                    continue
+                if (record["scene"] == candidate_scene_number and
+                        str(adoption.get("source_revision") or "").lower() ==
+                        source_revision and
+                        str(adoption.get("parent_revision") or "").lower() ==
+                        parent_token):
+                    return {
+                        "ok": True,
+                        "created": False,
+                        "run_name": run,
+                        "scene": record["scene"],
+                        "revision": record["revision"],
+                        "source_revision": source_revision,
+                        "parent_scene": parent_scene_number,
+                        "parent_revision": parent_token,
+                        "message": "Candidate is already attributed to this branch.",
+                    }
+
+            revision = uuid.uuid4().hex
+            created_at = datetime.now(timezone.utc).isoformat(
+                timespec="seconds").replace("+00:00", "Z")
+            metadata = json.loads(_canonical_json(candidate["_metadata"]))
+            segment = metadata.get("segment")
+            if not isinstance(segment, dict):
+                raise ValueError("Candidate revision metadata has no segment record.")
+            metadata_path = os.path.join(
+                scan["checkpoint_dir"],
+                "clip_%04d.%s.json" % (candidate_scene_number, revision))
+            segment.update({
+                "revision": revision,
+                "revision_metadata": os.path.relpath(
+                    metadata_path, self.output_root),
+                "predecessor_revision": parent_token,
+                "predecessor_checkpoint_sha256": str(
+                    parent.get("checkpoint_sha256") or ""),
+                "branch_id": str(parent.get("branch_id") or parent_token),
+                "forked_from_branch_id": str(
+                    candidate.get("branch_id") or candidate_token),
+                "adopted_from_revision": source_revision,
+                "adopted_from_branch_id": str(
+                    candidate.get("branch_id") or candidate_token),
+            })
+            metadata["created_at"] = created_at
+            metadata["adoption"] = {
+                "version": 1,
+                "created_at": created_at,
+                "source_scene": candidate_scene_number,
+                "source_revision": source_revision,
+                "candidate_revision": candidate_token,
+                "parent_scene": parent_scene_number,
+                "parent_revision": parent_token,
+                "shared_artifacts": True,
+            }
+            self._atomic_json(metadata_path, metadata)
+            return {
+                "ok": True,
+                "created": True,
+                "run_name": run,
+                "scene": candidate_scene_number,
+                "revision": revision,
+                "source_revision": source_revision,
+                "parent_scene": parent_scene_number,
+                "parent_revision": parent_token,
+                "message": (
+                    "Attributed scene %d candidate %s to branch tip %s; saved media and checkpoint files remain shared." %
+                    (candidate_scene_number, candidate_token[:8],
+                     parent_token[:8])),
+            }
+
+    def _chapter_references(self, scan: dict[str, Any], revision: str,
+                            artifacts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        """Sealed delivery snapshots pin their recovery inputs, not just MP4s.
+
+        Called under the same Run lock used to publish chapter manifests.
+        Inspect small JSON documents only; never follow chapter symlinks.
+        Unreadable snapshots block cleanup rather than risk losing recovery.
+        """
+        root = os.path.join(scan["run_dir"], "chapters")
+        paths = {os.path.realpath(item["_path"]) for item in artifacts
+                 if item.get("owned")}
+
+        def mentions(value: Any) -> bool:
+            if isinstance(value, dict):
+                # Superseded takes are audit history, not inputs required to
+                # recover this snapshot. Keep every other recovery edge.
+                return any(mentions(item) for key, item in value.items()
+                           if key != "supersedes")
+            if isinstance(value, list):
+                return any(mentions(item) for item in value)
+            if not isinstance(value, str):
+                return False
+            if value.lower() == revision:
+                return True
+            relative = value.replace("\\", "/")
+            if not (relative.startswith("h3_chains/") or os.path.isabs(relative)):
+                return False
+            return os.path.realpath(os.path.join(self.output_root, relative)) in paths
+
+        references = []
+        if not os.path.lexists(root):
+            return references
+        try:
+            if os.path.islink(root):
+                raise ValueError("chapter directory is a symlink")
+            with os.scandir(root) as entries:
+                chapters = sorted(entries, key=lambda entry: entry.name)
+            for directory in chapters:
+                if directory.is_symlink():
+                    raise ValueError("chapter directory is a symlink: " + directory.name)
+                if not directory.is_dir(follow_symlinks=False):
+                    continue
+                manifest_dir = os.path.join(directory.path, "manifests")
+                if not os.path.lexists(manifest_dir):
+                    continue
+                if os.path.islink(manifest_dir):
+                    raise ValueError("chapter manifests directory is a symlink")
+                with os.scandir(manifest_dir) as entries:
+                    snapshots = sorted(entries, key=lambda entry: entry.name)
+                for entry in snapshots:
+                    if not re.fullmatch(r"[0-9a-f]{32}\.json", entry.name):
+                        continue
+                    if entry.is_symlink() or not entry.is_file(follow_symlinks=False):
+                        raise ValueError("chapter snapshot is not a regular file")
+                    document = self._read_json(entry.path)
+                    if (not isinstance(document, dict)
+                            or document.get("format") != "h3_chain_chapter_manifest_v1"
+                            or document.get("run_name") != scan["run_name"]
+                            or not isinstance(document.get("segments"), list)
+                            or not document["segments"]
+                            or not isinstance(document.get("chapter"), dict)):
+                        raise ValueError("invalid chapter snapshot: " + entry.name)
+                    if mentions(document):
+                        chapter = document["chapter"]
+                        references.append({
+                            "number": chapter.get("number"),
+                            "title": str(chapter.get("title") or directory.name),
+                            "snapshot": entry.name[:-5],
+                            "path": os.path.relpath(entry.path, self.output_root),
+                        })
+        except (OSError, ValueError, TypeError, RecursionError) as error:
+            references.append({"error": "Cannot verify sealed chapter recovery: " + str(error)})
+        return references
+
+    def deletion_preview(self, run_name: Any, scene: Any,
+                         revision: Any) -> dict[str, Any]:
+        run_dir, run = self._run_dir(run_name)
+        scene_number = int(scene)
+        token = str(revision or "").strip().lower()
+        if not re.fullmatch(r"[0-9a-f]{32}", token):
+            raise ValueError("Checkpoint revision must be a 32-character revision id.")
+        with checkpoint_run_lock(self.output_root, run):
+            if not os.path.isdir(run_dir):
+                raise FileNotFoundError("H3 run %r does not exist." % run)
+            scan = self._scan(run)
+            key = (scene_number, token)
+            record = scan["records"].get(key)
+            if record is None:
+                raise FileNotFoundError(
+                    "Scene %d revision %s is no longer available." %
+                    (scene_number, token[:8]))
+            artifacts = self._artifacts(scan, record)
+            chapter_start, chapter_end = self._chapter_bounds(
+                scan, scene_number)
+            descendant_keys = self._descendant_keys(scan["records"], key)
+            dependents = []
+            for child_key in descendant_keys:
+                child = scan["records"][child_key]
+                dependents.append({
+                    "scene": child["scene"],
+                    "scene_id": child["scene_id"],
+                    "revision": child["revision"],
+                    "active": child["active"],
+                    "direct": key in child["_dependencies"],
+                    "leaf": not child["_dependents"],
+                    "continuation_mode": child["continuation_mode"],
+                    "context_length": child["context_length"],
+                    "audio_context_length": child["audio_context_length"],
+                })
+            dependents.sort(key=lambda item: (
+                not item["leaf"], -int(item["scene"]), item["revision"]))
+            chapter_references = self._chapter_references(scan, token, artifacts)
+            blockers = [
+                item.get("error") or (
+                    "Sealed Chapter %s (%s), snapshot %s, requires this revision "
+                    "or its recovery artifacts. Retire that snapshot explicitly "
+                    "if its chapter recovery is no longer needed." %
+                    (item["number"], item["title"], item["snapshot"][:8]))
+                for item in chapter_references]
+            try:
+                editorial = self._read_json(os.path.join(
+                    scan["run_dir"], "editorial.json"))
+                active_revision = next((
+                    str(record.get("revision") or "").lower()
+                    for record in scan["records"].values()
+                    if int(record.get("scene", 0)) == scene_number
+                    and bool(record.get("active"))
+                    and str(record.get("take_kind") or "") !=
+                    "editorial_alternate"), "")
+                selected_in_cut = any(
+                    isinstance(item, dict)
+                    and self._integer(item.get("scene")) == scene_number
+                    and str(item.get("alternate_revision") or "").lower()
+                    == token
+                    and str(item.get("base_revision") or "").lower()
+                    == active_revision
+                    for item in editorial.get("replacements", []))
+                selected_base = any(
+                    isinstance(item, dict)
+                    and self._integer(item.get("scene")) == scene_number
+                    and str(item.get("base_revision") or "").lower() == token
+                    and str(item.get("base_revision") or "").lower()
+                    == active_revision
+                    for item in editorial.get("replacements", []))
+            except (OSError, TypeError, ValueError, json.JSONDecodeError,
+                    AttributeError):
+                selected_in_cut = False
+                selected_base = False
+            if selected_in_cut:
+                blockers.append(
+                    "This alternate is selected in the final cut. Restore the "
+                    "original take in Plan Studio before deleting it.")
+            if selected_base:
+                blockers.append(
+                    "This generation revision is the immutable base of the "
+                    "selected final-cut alternate. Restore the original take "
+                    "in Plan Studio before rolling it back.")
+            later_active = sorted(
+                item["scene"] for item in scan["records"].values()
+                if (item["active"] and item["scene"] > scene_number and
+                    item["scene"] <= chapter_end))
+            if record.get("pointer_active") and not record["active"]:
+                blockers.append(
+                    "This saved take has a stale active pointer. Make the desired "
+                    "chapter branch active before deleting it; its files are retained.")
+            if dependents:
+                blockers.append(
+                    "%d later checkpoint revision%s depend%s on it." %
+                    (len(dependents), "" if len(dependents) == 1 else "s",
+                     "s" if len(dependents) == 1 else ""))
+            if record["active"] and dependents:
+                blockers.append(
+                    "This active revision can only be rolled back after its "
+                    "later revisions are deleted.")
+            elif record["active"] and later_active:
+                blockers.append(
+                    "A later active scene pointer exists at scene %d." %
+                    later_active[-1])
+            rollback = bool(record["active"] and not blockers)
+            if rollback:
+                artifacts.append(self._active_pointer_artifact(scan, record))
+            public_files = [{key: value for key, value in item.items()
+                             if not key.startswith("_")} for item in artifacts]
+            snapshot = _fingerprint({
+                "run_name": run,
+                "scene": scene_number,
+                "revision": token,
+                "active": record["active"],
+                "rollback": rollback,
+                "chapter_references": chapter_references,
+                "dependents": [(item["scene"], item["revision"])
+                               for item in dependents],
+                "files": [(item["path"], item["exists"], item["size_bytes"],
+                           item["shared"], artifact["_mtime_ns"])
+                          for item, artifact in zip(public_files, artifacts)],
+            })
+            owned = [item for item in public_files if item["owned"]]
+            return {
+                "ok": True,
+                "run_name": run,
+                "scene": scene_number,
+                "scene_id": record["scene_id"],
+                "revision": token,
+                "active": record["active"],
+                "rollback": rollback,
+                "rollback_to_scene": scene_number - 1 if rollback else None,
+                "scope_start_scene": chapter_start,
+                "scope_end_scene": chapter_end,
+                "allowed": not blockers,
+                "blockers": blockers,
+                "dependents": dependents,
+                "chapter_references": chapter_references,
+                "files": public_files,
+                "owned_file_count": sum(item["exists"] for item in owned),
+                "reclaimed_bytes": sum(item["size_bytes"] for item in owned),
+                "snapshot": snapshot,
+                "not_deleted": [
+                    "Run Plan and workflow archives",
+                    "Archived references and source media",
+                    "Prompt revision history",
+                    "Final and partial assembled exports",
+                ],
+            }
+
+    def delete(self, run_name: Any, scene: Any, revision: Any,
+               expected_snapshot: Any = "") -> dict[str, Any]:
+        run_dir, run = self._run_dir(run_name)
+        with checkpoint_run_lock(self.output_root, run):
+            preview = self.deletion_preview(run, scene, revision)
+            expected = str(expected_snapshot or "")
+            if not preview["allowed"]:
+                raise CheckpointDeleteBlocked(" ".join(preview["blockers"]), preview)
+            if not expected:
+                raise CheckpointDeleteBlocked(
+                    "Preview this checkpoint deletion before confirming it.",
+                    preview)
+            if expected != preview["snapshot"]:
+                raise CheckpointDeleteBlocked(
+                    "Checkpoint files or dependencies changed; preview the deletion again.",
+                    preview)
+            scan = self._scan(run)
+            key = (int(scene), str(revision).strip().lower())
+            record = scan["records"][key]
+            managed = self._artifacts(scan, record)
+            if preview["rollback"]:
+                managed.append(self._active_pointer_artifact(scan, record))
+            artifacts = [item for item in managed
+                         if item["owned"] and item["exists"]]
+            transaction = uuid.uuid4().hex
+            staged = []
+            try:
+                for artifact in artifacts:
+                    path = artifact["_path"]
+                    temporary = "%s.delete.%s.tmp" % (path, transaction)
+                    os.replace(path, temporary)
+                    staged.append((path, temporary, artifact["size_bytes"]))
+            except Exception:
+                for original, temporary, _size in reversed(staged):
+                    try:
+                        os.replace(temporary, original)
+                    except Exception:
+                        pass
+                raise
+            failed = []
+            for _original, temporary, _size in staged:
+                try:
+                    os.unlink(temporary)
+                except OSError:
+                    failed.append(temporary)
+            reclaimed = sum(size for _original, temporary, size in staged
+                            if temporary not in failed)
+            return {
+                "ok": True,
+                "run_name": run,
+                "scene": int(scene),
+                "revision": str(revision).strip().lower(),
+                "rollback": bool(preview["rollback"]),
+                "rollback_to_scene": preview["rollback_to_scene"],
+                "deleted_files": len(staged) - len(failed),
+                "reclaimed_bytes": reclaimed,
+                "message": (
+                    ("Rolled the active chain back through scene %d and " %
+                     (int(scene) - 1) if int(scene) > 1 else
+                     "Rolled the active chain back to no saved scenes and ") +
+                    "deleted scene %d revision %s." %
+                    (int(scene), str(revision)[:8])
+                    if preview["rollback"] else
+                    "Deleted scene %d revision %s." %
+                    (int(scene), str(revision)[:8])
+                ),
+            }

ComfyUI-MiniMaxH3-Context-Loop/checkpoint_variants.py

@@ -0,0 +1,278 @@
+"""Read-only catalogue of saved processing takes, separate from generation lineage.
+
+Listing reads JSON and file sizes, never model tensors or multi-GB checksums.
+Execution remains responsible for artifact integrity and latent validation.
+"""
+
+import json
+from pathlib import Path
+import re
+
+
+STAGES = ("derope", "latent_upscale", "pixel_upscale", "other")
+
+
+def processing_lineage(segments):
+    """Small immutable addresses, not copies of tensors or source manifests."""
+    return [{"scene": int(item["index"]), "revision": item["revision"],
+             "metadata_path": item["revision_metadata"],
+             "checkpoint_sha256": item["checkpoint_sha256"]}
+            for item in segments]
+
+
+def validate_processing_lineage(value):
+    if not isinstance(value, list) or not value:
+        raise ValueError("Saved processing branch has no lineage.")
+    for item in value:
+        if (not isinstance(item, dict) or type(item.get("scene")) is not int or
+                item["scene"] < 1 or
+                not re.fullmatch(r"[0-9a-f]{32}", str(item.get("revision") or "")) or
+                not re.fullmatch(r"[0-9a-f]{64}", str(item.get("checkpoint_sha256") or "")) or
+                not isinstance(item.get("metadata_path"), str) or not item["metadata_path"]):
+            raise ValueError("Saved processing branch has an invalid revision address.")
+    first = value[0]["scene"]
+    if [item["scene"] for item in value] != list(range(first, first + len(value))):
+        raise ValueError("Saved processing branch is not contiguous.")
+    return value
+
+
+def processing_stage(config):
+    config = config if isinstance(config, dict) else {}
+    recipe = config.get("recipe") or {}
+    recipe = recipe if isinstance(recipe, dict) else {}
+    explicit = recipe.get("stage")
+    if explicit in STAGES:
+        return explicit
+    # The released combined LBH/DeRoPE example records this recipe field.
+    # Never infer a processing stage from a user-chosen folder/profile name.
+    derope = recipe.get("derope")
+    if derope is True or (isinstance(derope, str) and derope.strip().lower()
+                          not in ("", "false", "off", "none", "disabled")):
+        return "derope"
+    return {"h3_latent": "latent_upscale", "pixel": "pixel_upscale"}.get(
+        config.get("backend"), "other")
+
+
+def saved_checkpoint_variants(output_root, run_name, originals):
+    root = Path(output_root).resolve()
+    run = (root / "h3_chains" / run_name).resolve()
+    if run.parent != root / "h3_chains":
+        raise ValueError("Invalid checkpoint variant run directory.")
+    records, warnings, seen, branches = [], [], set(), []
+    legacy_profiles = set()
+
+    def inside(path, parent):
+        resolved = path.resolve()
+        if not resolved.is_relative_to(parent):
+            raise ValueError("Saved processing artifact escapes its profile directory.")
+        return resolved
+
+    def read(path):
+        with path.open(encoding="utf-8") as handle:
+            value = json.load(handle)
+        if not isinstance(value, dict):
+            raise ValueError("Saved processing metadata is not an object.")
+        return value
+
+    def media(path):
+        rel = path.relative_to(root)
+        return {"filename": rel.name, "subfolder": str(rel.parent), "type": "output"}
+
+    def legacy_branches(profile):
+        # Only legacy DeRoPE takes need these larger, embedded-source files.
+        # New saves use compact immutable lineage snapshots in their metadata.
+        if profile in legacy_profiles:
+            return
+        legacy_profiles.add(profile)
+        manifests = [profile / "upscale_manifest.json"]
+        partial = inside(profile / "partial", profile)
+        if partial.is_dir():
+            manifests.extend(partial.glob("through_clip_*.manifest.json"))
+        for path in manifests:
+            if not path.is_file():
+                continue
+            try:
+                path = inside(path, profile)
+                saved = read(path)
+                if (saved.get("format") not in (
+                        "h3_chain_upscale_manifest_v1", "h3_chain_upscale_partial_manifest_v1") or
+                        saved.get("run_name") != run_name or saved.get("profile") != profile.name):
+                    raise ValueError("Invalid processing branch manifest.")
+                branches.append({"path": str(path.relative_to(root)), "kind": "manifest",
+                                 "lineage": validate_processing_lineage(processing_lineage(saved["segments"]))})
+            except (OSError, ValueError, TypeError, KeyError) as exc:
+                warnings.append("%s: %s" % (path.name, exc))
+
+    parents = [run / "upscaled"]
+    chapters = run / "chapters"
+    if chapters.is_dir():
+        parents.extend(path / "upscaled" for path in chapters.iterdir() if path.is_dir())
+    for parent in parents:
+        try:
+            inside(parent, run)
+            if not parent.is_dir():
+                continue
+            profiles = sorted(parent.iterdir())
+        except (OSError, ValueError) as exc:
+            warnings.append(str(exc))
+            continue
+        for profile in profiles:
+            try:
+                profile = inside(profile, run)
+                folder = inside(profile / "checkpoints", profile)
+                if not folder.is_dir():
+                    continue
+                files = sorted(folder.iterdir())
+            except (OSError, ValueError) as exc:
+                warnings.append(str(exc))
+                continue
+            for path in files:
+                match = re.fullmatch(r"clip_(\d{4})(?:\.([0-9a-f]{32}))?\.json", path.name)
+                if not match:
+                    continue
+                try:
+                    path = inside(path, profile)
+                    metadata = read(path)
+                    if metadata.get("format") != "h3_chain_upscale_segment_v1":
+                        continue
+                    if metadata.get("run_name") != run_name or metadata.get("profile") != profile.name:
+                        raise ValueError("Saved processing metadata belongs to another run/profile.")
+                    segment = metadata["segment"]
+                    scene = int(segment["index"])
+                    revision = str(segment["revision"])
+                    if (scene != int(match[1]) or not re.fullmatch(r"[0-9a-f]{32}", revision)
+                            or (match[2] and match[2] != revision)):
+                        raise ValueError("Saved processing scene/revision does not match its file.")
+                    canonical = inside(root / segment["revision_metadata"], profile)
+                    if canonical != folder / ("clip_%04d.%s.json" % (scene, revision)):
+                        raise ValueError("Saved processing revision address is inconsistent.")
+                    # Ignore mutable pointer copies; their immutable revision
+                    # file is the authority and is scanned separately.
+                    if path != canonical:
+                        continue
+                    identity = str(path.relative_to(root))
+                    if identity in seen:
+                        continue
+                    seen.add(identity)
+                    missing, size, outputs = [], 0, {}
+                    for field in ("segment", "checkpoint", "generated_audio"):
+                        address = segment.get(field)
+                        if not address and field == "generated_audio":
+                            continue
+                        if not isinstance(address, str) or not address:
+                            missing.append(field)
+                            continue
+                        artifact = inside(root / address, profile)
+                        if not artifact.is_file():
+                            missing.append(field)
+                            continue
+                        size += artifact.stat().st_size
+                        if field != "checkpoint":
+                            outputs["video" if field == "segment" else "audio"] = media(artifact)
+                    config = metadata.get("profile_config") or {}
+                    stage = metadata.get("processing_stage")
+                    if stage not in STAGES:
+                        stage = processing_stage(config)
+                    record = {
+                        "key": identity, "metadata_path": identity,
+                        "scene": scene, "scene_id": str(segment.get("id") or ""),
+                        "revision": revision, "stage": stage, "profile": profile.name,
+                        "profile_path": str(profile.relative_to(root)),
+                        "source_manifest_hash": str(metadata.get("source_manifest_hash") or ""),
+                        "source_revision": str(segment.get("source_revision") or ""),
+                        "source_checkpoint_sha256": str(segment.get("source_checkpoint_sha256") or ""),
+                        "checkpoint_sha256": str(segment.get("checkpoint_sha256") or ""),
+                        "created_at": str(segment.get("created_at") or ""),
+                        "width": segment.get("width"), "height": segment.get("height"),
+                        "raw_frames": segment.get("raw_frames"),
+                        "delivered_frames": segment.get("delivered_frames"),
+                        "latent_saved": segment.get("latent_saved") is True,
+                        "latent_layout": str(segment.get("latent_layout") or "omitted"),
+                        "context_steps": segment.get("context_steps", 0),
+                        "audio_route": str(segment.get("audio_route") or "unknown"),
+                        "prompt": str(segment.get("prompt") or ""),
+                        "ready": not missing, "missing_files": missing, "size_bytes": size,
+                        **outputs,
+                    }
+                    records.append(record)
+                    if metadata.get("processing_lineage"):
+                        branches.append({"path": identity, "kind": "metadata",
+                                         "lineage": validate_processing_lineage(metadata["processing_lineage"])})
+                    elif record["stage"] == "derope":
+                        legacy_branches(profile)
+                except (OSError, ValueError, TypeError, KeyError) as exc:
+                    warnings.append("%s: %s" % (path.name, exc))
+
+    # Match the exact source revision AND saved checkpoint identity. A rerun
+    # with the same scene number is not the same take. Follow derived sources
+    # transitively so a future DeRoPE -> upscale take stays beside its original.
+    sources = {}
+    for original in originals:
+        if original.get("take_kind") == "editorial_alternate":
+            continue
+        key = (int(original["scene"]), str(original["revision"]),
+               str(original.get("checkpoint_sha256") or ""))
+        if key[2]:
+            sources.setdefault(key, []).append(original)
+        alias = str(original.get("adopted_from_revision") or "")
+        if alias and key[2]:
+            sources.setdefault((key[0], alias, key[2]), []).append(original)
+    # ALT is not a generation branch, but its processed pictures still belong
+    # beside the immutable base scene. Match the ALT's own checkpoint hash;
+    # never attach an arbitrary same-scene processed take to the active base.
+    bases = {(int(item["scene"]), str(item["revision"])): item
+             for item in originals if item.get("take_kind") != "editorial_alternate"}
+    for alternate in originals:
+        if alternate.get("take_kind") != "editorial_alternate":
+            continue
+        base = bases.get((int(alternate["scene"]), str(alternate.get("alternate_of_revision") or "")))
+        digest = str(alternate.get("checkpoint_sha256") or "")
+        if base is not None and digest:
+            sources.setdefault((int(alternate["scene"]), str(alternate["revision"]), digest), []).append(base)
+    derived = {}
+    for record in records:
+        key = (record["scene"], record["revision"], record["checkpoint_sha256"])
+        if key[2]:
+            derived.setdefault(key, []).append(record)
+
+    def origins(record, visited):
+        key = (record["scene"], record["source_revision"], record["source_checkpoint_sha256"])
+        if not key[1] or not key[2] or key in visited:
+            return []
+        if key in sources:
+            return sources[key]
+        return [origin for parent in derived.get(key, [])
+                for origin in origins(parent, visited | {key})]
+
+    for record in records:
+        matches = {(int(item["scene"]), str(item["revision"]))
+                   for item in origins(record, set())}
+        record["originals"] = [{"scene": scene, "revision": revision}
+                               for scene, revision in sorted(matches)]
+        record["source_status"] = "linked" if matches else "original unavailable or source mismatch"
+    records.sort(key=lambda item: (item["scene"], item["created_at"], item["key"]), reverse=True)
+    # Independent pixel cleanup can leave a hole in an immutable historical
+    # lineage. Keep every surviving take visible, but don't offer that history
+    # as an executable complete branch or silently substitute a newer take.
+    available = {record["key"]: (record["scene"], record["revision"], record["checkpoint_sha256"])
+                 for record in records if record["ready"]}
+    branches = [branch for branch in branches if all(
+        available.get(item["metadata_path"]) == (item["scene"], item["revision"], item["checkpoint_sha256"])
+        for item in branch["lineage"])]
+    for record in records:
+        matches = [branch for branch in branches if any(
+            item.get("metadata_path") == record["key"] and
+            item.get("checkpoint_sha256") == record["checkpoint_sha256"]
+            for item in branch["lineage"] if isinstance(item, dict))]
+        # Remove strict prefixes and duplicate snapshots. Two distinct leaves
+        # are ambiguous: the user must click a take unique to the desired leaf.
+        leaves = {}
+        for branch in matches:
+            lineage = branch["lineage"]
+            if not any(len(other["lineage"]) > len(lineage) and
+                       other["lineage"][:len(lineage)] == lineage for other in matches):
+                key = json.dumps(lineage, sort_keys=True)
+                if key not in leaves or branch["kind"] == "metadata":
+                    leaves[key] = branch
+        record["processing_branch"] = next(iter(leaves.values())) if len(leaves) == 1 else None
+    return {"variants": records, "warnings": warnings}

ComfyUI-MiniMaxH3-Context-Loop/contracts_v05.py

@@ -0,0 +1,569 @@
+"""Stable data-contract declarations for the 0.5 workflow UX migration.
+
+This module is deliberately independent from ComfyUI, PyTorch, and the node
+implementations.  It freezes the vocabulary and compatibility translations
+before runtime nodes start consuming the new contracts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+SOURCE_TIMELINE_VERSION = "h3_source_timeline_v1"
+AUDIO_POLICY_VERSION = "h3_audio_policy_v1"
+TRANSITION_POLICY_VERSION = "h3_transition_policy_v1"
+CHAIN_POLICY_VERSION = "h3_chain_policy_v1"
+LIP_SYNC_OPTIONS_VERSION = "h3_lip_sync_options_v1"
+SCENE_DEPENDENCY_VERSION = "h3_scene_dependency_v1"
+PREFLIGHT_VERSION = "h3_preflight_v1"
+
+FINAL_AUDIO_POLICIES = ("generated", "source", "none")
+SOURCE_REFERENCE_POLICIES = ("off", "on")
+GENERATED_CONTINUITY_POLICIES = ("off", "on")
+SOURCE_AUDIO_TARGET_POLICIES = ("off", "locked")
+PAIRED_AUDIO_POLICIES = ("off", "embedded")
+PRIMARY_TRANSITION_PRESETS = ("cut", "guide", "hard_av", "soft_av")
+GENERATION_SCENE_PROFILES = {
+    "Visual continuity": "guide",
+    "Independent scenes": "cut",
+    "Hard picture + protected audio": "hard_av",
+    "Hard picture + smooth audio": "soft_av",
+}
+GENERATION_AUDIO_PROFILES = {
+    "Generate audio": ("generated", "off", "on", False),
+    "Generate fresh audio per scene": ("generated", "off", "off", False),
+    "Lip-sync to source audio": ("source", "off", "off", True),
+    "Generate audio from source guide": ("generated", "on", "off", False),
+    "Use source soundtrack only": ("source", "off", "off", False),
+    "No final audio": ("none", "off", "off", False),
+}
+ADVANCED_TRANSITION_PRESETS = (
+    "cut", "guide", "tone_guide", "latent_guide", "detail_guide",
+    "detail_av", "drift_av", "color_drift_av", "hard_av", "soft_av",
+)
+DEFAULT_AUDIO_CONTEXT_LENGTH = 22
+CONTEXT_SPATIAL_PROXY_MODES = ("off", "rgb_5_6", "latent_5_6")
+CONTINUATION_POLICIES = (
+    "guide", "tone_carry_guide", "latent_guide", "tapered_guide",
+    "masked_av", "tapered_av", "feathered_av", "audio_feathered_av",
+    "drift_control_av", "color_stable_drift_av")
+TRANSITION_CONTEXT_LENGTHS = (
+    0, 1, 5, 22, 39, 56, 73, 90, 107, 124,
+    141, 158, 175, 192, 209, 226, 243,
+)
+AV_TRANSITION_CONTEXT_LENGTHS = (39, 90, 141, 192, 243)
+VIDEO_ONLY_AV_TRANSITION_CONTEXT_LENGTHS = tuple(
+    value for value in TRANSITION_CONTEXT_LENGTHS if value >= 5
+)
+
+# Experimental one-shot latent-context recipe adapted from beijinren's
+# ComfyUI-H3-Context-Noise. Keep every generation-significant value in the
+# scene dependency contract so changing the recipe cannot silently resume a
+# scene rendered with an older taper.
+DETAIL_AV_RECIPE = {
+    "version": "h3_detail_av_latent_taper_v2",
+    "context_frames": 39,
+    "video_steps": 12,
+    "alpha": 0.30,
+    "alpha_end": 0.00,
+    "ramp_steps": 4,
+    "noise_scale": "match_latent_std",
+    "seed_xor": 0xD37A11,
+}
+
+# Experimental recursive AV treatment.  Unlike Detail AV, this does not bake
+# static noise into the copied predecessor.  At each model evaluation it uses
+# the sampler's existing noise field and advances the video prefix to the next
+# scheduler sigma.  The oldest eight of the 12 carried video steps receive the
+# complete matched-noise ratio; the newest four taper .75/.50/.25/.00 so the
+# generated-future boundary remains exact.  Audio retains the selected Audio
+# Policy's normal hard/open mask.
+DRIFT_CONTROL_AV_RECIPE = {
+    "version": "h3_drift_control_av_v1",
+    "context_frames": 39,
+    "video_steps": 12,
+    "matched_steps": 8,
+    "taper_steps": 4,
+    "sigma_rule": "next_schedule_sigma_over_current_sigma",
+    "mask_quantization": 256,
+    "audio": "unchanged_policy_mask",
+    "validated_steps": 20,
+}
+
+# Optional scene-one color anchor layered onto Drift-Control AV.  Only the
+# disposable copied video prefix is touched.  Two encodes isolate the desired
+# RGB change from ordinary VAE reconstruction error:
+# E(graded decode) - E(original decode).  The low-frequency delta fades from
+# zero at the old overlap edge to full strength beside the generated future.
+# Saved predecessor video/audio latents and the complete audio path remain
+# immutable.
+LATENT_COLOR_CARRY_RECIPE = {
+    "version": "h3_latent_color_delta_v1",
+    "context_frames": 39,
+    "video_steps": 12,
+    "anchor": "first_generated_scene_delivered_tail",
+    "source": "current_predecessor_delivered_tail",
+    "strength": 0.50,
+    "max_luma_shift_code_values": 6.0,
+    "max_saturation_change": 0.06,
+    "spatial_lowpass_kernel": 3,
+    "temporal_taper": "full_prefix_smoothstep_zero_to_one",
+    "delta_rule": "E(graded_D(z))-E(D(z))",
+    "audio": "unchanged",
+}
+
+# Boundary-only low-grid experiment reconstructed from a mixed-resolution
+# chain: a 1376x768 target carried a predecessor generated at 1152x640.  The
+# Guide recipe spatially reduces the complete saved predecessor video latent,
+# decodes that disposable 5/6 latent at its native 1152x640 canvas, then lets
+# Motion Context restore only the requested RGB tail to the target canvas.
+# This deliberately keeps the nonlinear low-grid VAE decode that a simple RGB
+# resize cannot reproduce.  AV keeps its cheaper latent down/up prefix filter.
+# Generated scenes and checkpoint/assembly artifacts keep the Plan canvas.
+CONTEXT_SPATIAL_PROXY_RECIPE = {
+    "version": "h3_context_spatial_proxy_v2",
+    "scale_numerator": 5,
+    "scale_denominator": 6,
+    "pixel_alignment": 32,
+    "guide_source": "saved_predecessor_video_latent",
+    "guide_latent_downsample": "area",
+    "guide_decode": "full_low_grid_stream",
+    "guide_tail": "delivered_frames",
+    "guide_restore": "motion_context_lanczos",
+    "latent_downsample": "area",
+    "latent_restore": "bilinear",
+    "preserve_latent_statistics": False,
+}
+
+LEGACY_AUDIO_MODE_POLICIES = {
+    "source_track": {
+        "final_audio": "source",
+        "source_reference": "on",
+        "generated_continuity": "off",
+    },
+    "generated_audio": {
+        "final_audio": "generated",
+        "source_reference": "off",
+        "generated_continuity": "on",
+    },
+    "source_plus_timeline": {
+        "final_audio": "source",
+        "source_reference": "on",
+        "generated_continuity": "on",
+    },
+}
+
+TRANSITION_PRESETS = {
+    "cut": {
+        "continuation_mode": "guide",
+        "context_length": 0,
+        "label": "Cut / Independent",
+    },
+    "guide": {
+        "continuation_mode": "guide",
+        "context_length": 22,
+        "label": "Guided transition",
+    },
+    "tone_guide": {
+        "continuation_mode": "tone_carry_guide",
+        "context_length": 22,
+        "label": "Tone-carry guided transition",
+    },
+    "latent_guide": {
+        "continuation_mode": "latent_guide",
+        "context_length": 22,
+        "label": "Latent-guided transition",
+    },
+    "detail_guide": {
+        "continuation_mode": "tapered_guide",
+        "context_length": 22,
+        "label": "Detail-preserving guided transition",
+    },
+    "detail_av": {
+        "continuation_mode": "tapered_av",
+        "context_length": 39,
+        "label": "Detail-preserving AV continuation (experimental)",
+    },
+    "drift_av": {
+        "continuation_mode": "drift_control_av",
+        "context_length": 39,
+        "label": "Drift-Control AV continuation (experimental)",
+    },
+    "color_drift_av": {
+        "continuation_mode": "color_stable_drift_av",
+        "context_length": 39,
+        "label": "Color-Stable Drift AV continuation (experimental)",
+    },
+    "hard_av": {
+        "continuation_mode": "masked_av",
+        "context_length": 39,
+        "label": "Hard continuation",
+    },
+    "soft_av": {
+        "continuation_mode": "audio_feathered_av",
+        "context_length": 39,
+        "label": "Soft continuation (hard picture, soft audio)",
+    },
+    "audio_feather_av": {
+        "continuation_mode": "audio_feathered_av",
+        "context_length": 39,
+        "label": "Audio-feathered continuation (legacy alias)",
+    },
+}
+
+DEPENDENCY_SCOPES = (
+    "global_generation",
+    "scene_generation",
+    "incoming_boundary",
+    "assembly_only",
+)
+
+
+def migrate_legacy_audio_mode(mode: str) -> dict[str, str]:
+    """Return a new independent audio-policy record for a 0.4 mode."""
+    try:
+        policy = LEGACY_AUDIO_MODE_POLICIES[str(mode)]
+    except KeyError as exc:
+        raise ValueError("Unknown legacy H3 audio mode %r." % mode) from exc
+    return {"version": AUDIO_POLICY_VERSION, **policy}
+
+
+def migrate_continuation_mode(mode: str) -> str:
+    """Map retired experimental implementations to a supported mode."""
+    value = str(mode)
+    if value == "feathered_av_rgb":
+        return "feathered_av"
+    return value
+
+
+def audio_policy(
+    final_audio: str,
+    source_reference: str,
+    generated_continuity: str,
+    source_audio_target: str | bool = "off",
+    lip_sync_options: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Validate and return one independent 0.5 audio-policy record."""
+    final = str(final_audio)
+    source = str(source_reference)
+    continuity = str(generated_continuity)
+    if isinstance(source_audio_target, bool):
+        target = "locked" if source_audio_target else "off"
+    else:
+        target = str(source_audio_target or "off").strip().lower()
+    if final not in FINAL_AUDIO_POLICIES:
+        raise ValueError("Unknown H3 final-audio policy %r." % final_audio)
+    if source not in SOURCE_REFERENCE_POLICIES:
+        raise ValueError(
+            "Unknown H3 source-reference policy %r." % source_reference)
+    if continuity not in GENERATED_CONTINUITY_POLICIES:
+        raise ValueError(
+            "Unknown H3 generated-continuity policy %r." %
+            generated_continuity)
+    if target not in SOURCE_AUDIO_TARGET_POLICIES:
+        raise ValueError(
+            "Unknown H3 source-audio-target policy %r." %
+            source_audio_target)
+    # A clean source waveform occupying the complete target audio latent is
+    # already the strongest possible audio condition.  Keeping a separate
+    # Ref2VA audio bank or a predecessor audio prefix would describe competing
+    # clocks, so the compact switch resolves both axes off canonically.
+    if target == "locked":
+        source = "off"
+        continuity = "off"
+    policy = {
+        "version": AUDIO_POLICY_VERSION,
+        "final_audio": final,
+        "source_reference": source,
+        "generated_continuity": continuity,
+    }
+    # Preserve the byte-for-byte v1 spelling for existing workflows and
+    # checkpoints when the new opt-in behavior is disabled.
+    if target != "off":
+        policy["source_audio_target"] = target
+    if target == "locked" and lip_sync_options is not None:
+        policy["lip_sync_options"] = masked_song_options(lip_sync_options)
+    return policy
+
+
+def masked_song_options(
+    value: dict[str, Any] | None = None,
+    *,
+    preroll_seconds: float = 1.0,
+    lookahead_seconds: float = 0.2,
+    audio_denoise: float = 0.0,
+    gap_denoise: float = 0.15,
+    gate_hold_seconds: float = 0.2,
+    voice_fingerprint: str = "",
+) -> dict[str, Any]:
+    """Validate the optional contextual song-latent recipe.
+
+    The record is stored only for target-locked source audio.  Its absence is
+    the stable spelling of the pre-feature hard-cut/full-freeze behavior.
+    """
+    if value is not None:
+        if not isinstance(value, dict):
+            raise ValueError(
+                "H3 lip-sync options must come from MiniMax H3 Lip-Sync "
+                "Options.")
+        if value.get("version") != LIP_SYNC_OPTIONS_VERSION:
+            raise ValueError("H3 lip-sync options version is missing or obsolete.")
+        preroll_seconds = value.get("preroll_seconds", preroll_seconds)
+        lookahead_seconds = value.get("lookahead_seconds", lookahead_seconds)
+        audio_denoise = value.get("audio_denoise", audio_denoise)
+        gap_denoise = value.get("gap_denoise", gap_denoise)
+        gate_hold_seconds = value.get(
+            "gate_hold_seconds", gate_hold_seconds)
+        voice_fingerprint = value.get(
+            "voice_fingerprint", voice_fingerprint)
+
+    def bounded(name: str, raw: Any, low: float, high: float) -> float:
+        if isinstance(raw, bool):
+            raise ValueError("H3 lip-sync %s must be a number." % name)
+        try:
+            resolved = float(raw)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                "H3 lip-sync %s must be a number." % name) from exc
+        if resolved < low or resolved > high:
+            raise ValueError(
+                "H3 lip-sync %s must be between %.3g and %.3g." %
+                (name, low, high))
+        return resolved
+
+    resolved = {
+        "version": LIP_SYNC_OPTIONS_VERSION,
+        "preroll_seconds": bounded(
+            "pre-roll", preroll_seconds, 0.0, 4.0),
+        "lookahead_seconds": bounded(
+            "lookahead", lookahead_seconds, 0.0, 2.0),
+        "audio_denoise": bounded(
+            "sung-region denoise", audio_denoise, 0.0, 1.0),
+        "gap_denoise": bounded(
+            "gap denoise", gap_denoise, 0.0, 1.0),
+        "gate_hold_seconds": bounded(
+            "voice-gate hold", gate_hold_seconds, 0.0, 2.0),
+    }
+    fingerprint = str(voice_fingerprint or "").strip().lower()
+    if fingerprint:
+        if (len(fingerprint) != 64 or any(
+                character not in "0123456789abcdef"
+                for character in fingerprint)):
+            raise ValueError(
+                "H3 lip-sync voice fingerprint must be a SHA-256 hex digest.")
+        resolved["voice_fingerprint"] = fingerprint
+    return resolved
+
+
+def compose_chain_policy(
+    audio: dict[str, Any],
+    transition: dict[str, Any],
+    *,
+    audio_context_length: int = DEFAULT_AUDIO_CONTEXT_LENGTH,
+) -> dict[str, Any]:
+    """Combine validated 0.5 policies without changing their stored shape.
+
+    Plan consumes the two canonical child records and the legacy-compatible
+    audio-context value, then persists behavior-only compatibility fields.
+    This keeps checkpoint hashes independent of workflow topology.
+    """
+    if not isinstance(audio, dict) or audio.get("version") != AUDIO_POLICY_VERSION:
+        raise ValueError("H3 Chain Policy requires a current Audio Policy.")
+    resolved_audio = audio_policy(
+        audio.get("final_audio"), audio.get("source_reference"),
+        audio.get("generated_continuity"),
+        audio.get("source_audio_target", "off"),
+        audio.get("lip_sync_options"))
+    if (not isinstance(transition, dict) or
+            transition.get("version") != TRANSITION_POLICY_VERSION):
+        raise ValueError("H3 Chain Policy requires a current Transition Policy.")
+    resolved_transition = transition_policy(
+        transition.get("preset"),
+        expert_override=bool(transition.get("expert_override", False)),
+        continuation_mode=transition.get("continuation_mode"),
+        context_length=transition.get("context_length"))
+    if isinstance(audio_context_length, bool):
+        raise ValueError(
+            "H3 Chain Policy audio context must be between 0 and 240 frames.")
+    try:
+        resolved_audio_context = int(audio_context_length)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(
+            "H3 Chain Policy audio context must be between 0 and 240 frames."
+        ) from exc
+    if resolved_audio_context < 0 or resolved_audio_context > 240:
+        raise ValueError(
+            "H3 Chain Policy audio context must be between 0 and 240 frames.")
+    mode = str(resolved_transition["continuation_mode"])
+    context = int(resolved_transition["context_length"])
+    carries_generated_audio = (
+        resolved_audio["generated_continuity"] == "on"
+        and resolved_audio.get("source_audio_target", "off") != "locked"
+        and resolved_audio_context > 0
+    )
+    if (mode in (
+            "masked_av", "feathered_av", "audio_feathered_av"
+        ) and context > 0 and carries_generated_audio
+            and context not in AV_TRANSITION_CONTEXT_LENGTHS):
+        raise ValueError(
+            "H3 AV generated-audio continuity requires an exact shared "
+            "video/audio boundary: 39, 90, 141, 192, or 243 context "
+            "frames. Set generated continuity off (or audio context to 0) "
+            "to test a video-only AV window from 5 frames.")
+    return {
+        "version": CHAIN_POLICY_VERSION,
+        "audio_policy": resolved_audio,
+        "transition_policy": resolved_transition,
+        "audio_context_length": resolved_audio_context,
+    }
+
+
+def chain_policy(
+    incoming_transition: str,
+    final_audio: str,
+    source_reference: str,
+    generated_continuity: str,
+    lock_source_audio: bool = False,
+    lip_sync_options: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build the compact normal-user policy from its semantic choices."""
+    preset = str(incoming_transition)
+    if preset not in PRIMARY_TRANSITION_PRESETS:
+        raise ValueError(
+            "H3 Chain Policy incoming transition must be one of %s." %
+            (PRIMARY_TRANSITION_PRESETS,))
+    resolved_transition = transition_policy(preset)
+    return compose_chain_policy(
+        audio_policy(
+            final_audio, source_reference, generated_continuity,
+            "locked" if bool(lock_source_audio) else "off",
+            lip_sync_options),
+        resolved_transition,
+        # Normal authoring keeps picture and generated-audio carry on the
+        # same tested boundary. The Advanced Policy keeps that semantic
+        # pairing for experimental recipes; independent numeric values remain
+        # available only through the 0.4 Legacy Policy Adapter.
+        audio_context_length=resolved_transition["context_length"])
+
+
+def paired_audio_policy(value: str | bool) -> str:
+    """Normalize a reference-local paired-audio choice or legacy boolean."""
+    if isinstance(value, bool):
+        return "embedded" if value else "off"
+    normalized = str(value).strip().lower()
+    if normalized not in PAIRED_AUDIO_POLICIES:
+        raise ValueError("Unknown H3 paired-audio policy %r." % value)
+    return normalized
+
+
+def transition_preset(name: str) -> dict[str, Any]:
+    """Return an isolated resolved transition preset."""
+    try:
+        preset = TRANSITION_PRESETS[str(name)]
+    except KeyError as exc:
+        raise ValueError("Unknown H3 transition preset %r." % name) from exc
+    return {"version": TRANSITION_POLICY_VERSION, "preset": str(name), **preset}
+
+
+def transition_policy(
+    preset: str,
+    *,
+    expert_override: bool = False,
+    continuation_mode: str | None = None,
+    context_length: int | None = None,
+) -> dict[str, Any]:
+    """Resolve a semantic preset and optional explicit low-level override."""
+    resolved = transition_preset(preset)
+    expert = bool(expert_override)
+    if expert:
+        mode = migrate_continuation_mode(continuation_mode)
+        if mode not in CONTINUATION_POLICIES:
+            raise ValueError(
+                "Unknown H3 continuation implementation %r." %
+                continuation_mode)
+        try:
+            context = int(context_length)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                "H3 transition context must be 0 or one of %s." %
+                (TRANSITION_CONTEXT_LENGTHS,)) from exc
+        if context not in TRANSITION_CONTEXT_LENGTHS:
+            raise ValueError(
+                "H3 transition context must be 0 or one of %s." %
+                (TRANSITION_CONTEXT_LENGTHS,))
+        if mode == "latent_guide" and 0 < context < 5:
+            raise ValueError(
+                "H3 Latent Guide requires at least 5 context frames.")
+        if (mode in (
+                "masked_av", "feathered_av", "audio_feathered_av"
+        ) and context > 0
+                and context not in VIDEO_ONLY_AV_TRANSITION_CONTEXT_LENGTHS):
+            raise ValueError(
+                "H3 video-only AV transition experiments require at least "
+                "5 context frames (or 0 to disable continuation). Exact "
+                "39/90/141/192/243-frame alignment is still required when "
+                "generated predecessor audio is carried.")
+        if (mode == "tapered_av" and context not in (
+                0, int(DETAIL_AV_RECIPE["context_frames"]))):
+            raise ValueError(
+                "H3 Detail AV currently requires exactly 39 context frames "
+                "(or 0 to disable continuation).")
+        if (mode in ("drift_control_av", "color_stable_drift_av")
+                and context not in (
+                0, int(DRIFT_CONTROL_AV_RECIPE["context_frames"]))):
+            raise ValueError(
+                "H3 Drift-Control AV and Color-Stable Drift AV currently "
+                "require exactly 39 context frames (or 0 to disable "
+                "continuation).")
+        resolved["continuation_mode"] = mode
+        resolved["context_length"] = context
+    resolved["expert_override"] = expert
+    return resolved
+
+
+def source_timeline_shape() -> dict[str, Any]:
+    """Document the required serializable shape without creating media state."""
+    return {
+        "version": SOURCE_TIMELINE_VERSION,
+        "video": {
+            "path": "absolute host path or empty",
+            "stream_index": 0,
+            "native_fps": "positive rational",
+            "start_pts_seconds": "number",
+            "duration_seconds": "positive number",
+            "frame_count_24fps": "non-negative integer",
+        },
+        "audio": {
+            "kind": "embedded | external_path | deferred_tensor | none",
+            "path": "absolute host path or empty",
+            "stream_index": "non-negative integer or null",
+            "sample_rate": "positive integer or null",
+            "duration_seconds": "non-negative number",
+        },
+        "origin": {
+            "skip_native_frames": "non-negative integer",
+            "skip_seconds": "non-negative number",
+        },
+        "fingerprints": {
+            "video": "sha256 or empty",
+            "audio": "sha256 or empty",
+            "timeline": "sha256",
+        },
+        "recovery": {
+            "original_available": "boolean",
+            "archived_path": "absolute host path or empty",
+            "run_owned_audio_path": "absolute host path or empty",
+        },
+    }
+
+
+def scene_dependency_shape() -> dict[str, Any]:
+    """Document the versioned, four-scope checkpoint dependency record."""
+    return {
+        "version": SCENE_DEPENDENCY_VERSION,
+        "scene": "one-based integer",
+        "scopes": {scope: "JSON-safe field map" for scope in DEPENDENCY_SCOPES},
+        "fingerprints": {scope: "sha256" for scope in DEPENDENCY_SCOPES},
+        "generation_hash": "sha256 of scopes except assembly_only",
+    }

ComfyUI-MiniMaxH3-Context-Loop/deferred_checkpoint_source.py

@@ -0,0 +1,152 @@
+"""Read a pinned processing branch as a deferred H3 source, without promotion."""
+
+from pathlib import Path
+import re
+
+from .checkpoint_variants import processing_lineage, processing_stage, validate_processing_lineage
+
+
+def editorial_source_manifest(manifest, chain):
+    """Freeze the selected final-cut pictures without promoting generation takes."""
+    if manifest.get("presentation_source") or manifest.get("processing_source"):
+        return manifest  # Already resolved, including a DeRoPE-derived source.
+    editorial = chain._manifest_editorial(manifest)
+    bases = manifest.get("segments") or []
+    pictures = chain._editorial_presentation_segments(
+        manifest["run_name"], bases, editorial)
+    output = None
+    selected = []
+    for position, (base, picture) in enumerate(zip(bases, pictures)):
+        if picture.get("presentation_media_mode") != "picture_only":
+            continue
+        scene = int(base["index"])
+        metadata, _path = chain._load_checkpoint_revision(
+            manifest["run_name"], scene, picture["revision"], verify_artifacts=False)
+        resolved = dict(picture)
+        compatibility = metadata.get("compatibility") or {}
+        geometry = chain.saved_resolution(picture) or compatibility
+        if geometry.get("width") and geometry.get("height"):
+            resolved["resolution"] = {key: int(geometry[key]) for key in ("width", "height")}
+        # A different prompt/reference registry belongs to this ALT, not the
+        # first base scene's manifest-level conditioning fingerprint.
+        resolved["generation_fingerprint"] = str(compatibility.get("generation_fingerprint") or "")
+        if isinstance(metadata.get("scene_dependency"), dict):
+            resolved["scene_dependency"] = chain._json_document(metadata["scene_dependency"])
+        resolved["sample_rate"] = base.get("sample_rate", 0)
+        resolved["presentation_source"] = {
+            "mode": "picture_only", "original": chain._json_document(base)}
+        if output is None:
+            output = chain._json_document(manifest)
+        output["segments"][position] = resolved
+        selected.append({"scene": scene, "base_revision": base["revision"],
+                         "alternate_revision": picture["revision"]})
+    if not selected:
+        return manifest  # Keep existing no-ALT source/resume hashes unchanged.
+    output["editorial"] = chain._json_document(editorial)
+    output["presentation_source"] = {"format": "h3_deferred_editorial_v1", "scenes": selected}
+    return output
+
+
+def derope_source_manifest(manifest, selection, chain, upscale):
+    manifest = editorial_source_manifest(manifest, chain)
+    if not isinstance(selection, dict) or selection.get("stage") != "derope":
+        raise ValueError("Unknown Checkpoint Manager processing source.")
+    root = Path(chain._output_root()).resolve()
+    run = root / "h3_chains" / chain._strict_run_name(manifest["run_name"])
+    profile = (root / str(selection.get("profile_path") or "")).resolve()
+    # Exactly run/upscaled/profile or run/chapters/chapter/upscaled/profile.
+    relative = profile.relative_to(run).parts if profile.is_relative_to(run) else ()
+    if not ((len(relative) == 2 and relative[0] == "upscaled") or
+            (len(relative) == 4 and relative[0] == "chapters" and relative[2] == "upscaled")):
+        raise ValueError("DeRoPE source profile is outside the selected run.")
+
+    def confined(address):
+        if not isinstance(address, str) or not address:
+            raise ValueError("DeRoPE source has a missing artifact address.")
+        path = (root / address).resolve()
+        if not path.is_relative_to(profile):
+            raise ValueError("DeRoPE source artifact escapes its profile.")
+        return path
+
+    branch = selection.get("branch")
+    if not isinstance(branch, dict) or not branch.get("lineage"):
+        raise ValueError("Select a saved DeRoPE branch, not an isolated clip.")
+    witness = chain._read_json(str(confined(branch.get("path"))))
+    if (not isinstance(witness, dict) or witness.get("run_name") != manifest["run_name"] or
+            witness.get("profile") != profile.name):
+        raise ValueError("DeRoPE branch belongs to another run/profile.")
+    if (branch.get("kind") == "metadata" and
+            witness.get("format") == "h3_chain_upscale_segment_v1"):
+        saved_lineage = witness.get("processing_lineage")
+    elif (branch.get("kind") == "manifest" and witness.get("format") in (
+            "h3_chain_upscale_manifest_v1", "h3_chain_upscale_partial_manifest_v1")):
+        saved_lineage = processing_lineage(witness.get("segments") or [])
+    else:
+        raise ValueError("Invalid saved DeRoPE branch format.")
+    if saved_lineage != branch["lineage"]:
+        raise ValueError("Saved DeRoPE branch changed. Select that processing branch again.")
+    validate_processing_lineage(saved_lineage)
+    by_scene = {int(item["scene"]): item for item in saved_lineage}
+    output = chain._json_document(manifest)
+    used = []
+    for position, original in enumerate(manifest["segments"]):
+        index = int(original["index"])
+        ref = by_scene.get(index)
+        if ref is None:
+            continue  # Only an absent scene falls back to its selected original.
+        revision = str(ref.get("revision") or "")
+        if not re.fullmatch(r"[0-9a-f]{32}", revision):
+            raise ValueError("Invalid saved DeRoPE revision.")
+        path = confined(ref.get("metadata_path"))
+        if path != profile / "checkpoints" / ("clip_%04d.%s.json" % (index, revision)):
+            raise ValueError("Saved DeRoPE revision address does not match its scene.")
+        metadata = chain._read_json(str(path))
+        if not isinstance(metadata, dict) or not isinstance(metadata.get("segment"), dict):
+            raise ValueError("Saved DeRoPE scene %d has invalid metadata." % index)
+        child = metadata.get("segment") or {}
+        if (metadata.get("format") != "h3_chain_upscale_segment_v1" or
+                metadata.get("run_name") != manifest["run_name"] or
+                metadata.get("profile") != profile.name or
+                processing_stage(metadata.get("profile_config")) != "derope" or
+                child.get("revision") != revision or
+                child.get("checkpoint_sha256") != ref.get("checkpoint_sha256")):
+            raise ValueError("Saved DeRoPE scene %d identity or stage does not match." % index)
+        source_revisions = {original.get("revision"), original.get("adopted_from_revision")}
+        if (not child.get("source_revision") or child.get("source_revision") not in source_revisions or
+                child.get("source_checkpoint_sha256") != original.get("checkpoint_sha256")):
+            raise ValueError("DeRoPE scene %d belongs to a different original take or final-cut ALT. "
+                             "Select a DeRoPE branch made from the selected picture, or use Original." % index)
+        for key in ("raw_frames", "delivered_frames", "prompt", "prompt_hash", "seed", "steps"):
+            if child.get(key) != original.get(key):
+                raise ValueError("DeRoPE scene %d has different source timing/settings (%s)." % (index, key))
+        if child.get("latent_saved") is not True:
+            raise ValueError(
+                "DeRoPE scene %d has no full latent (preview/continuation tail only). "
+                "Render it with save_latent enabled and Recovered AV connected; "
+                "or explicitly select Original. No silent fallback." % index)
+        for key in ("checkpoint", "segment", "revision_metadata", "prompt_file", "generated_audio"):
+            if child.get(key) is not None:
+                confined(child[key])
+        upscale._verify_upscale_segment(child, index)
+        # Retain the original continuation, timing, prompts, cache descriptor
+        # and generation fingerprint. Only media/latent identity comes from HQ.
+        resolved = dict(original)
+        for key in ("blend_segment", "blend_segment_sha256", "blend_frames",
+                    "generated_audio", "generated_audio_sha256", "resolution"):
+            resolved.pop(key, None)
+        resolved.update(child)
+        resolved["processing_source"] = {
+            "stage": "derope", "profile_path": str(profile.relative_to(root)),
+            "original": chain._json_document(original),
+        }
+        resolved.pop("presentation_source", None)  # Original owns the ALT/base audio split.
+        upscale._validate_processed_latent_header(resolved)
+        output["segments"][position] = resolved
+        used.append(index)
+    if not used:
+        raise ValueError("Selected DeRoPE branch has no scenes in this output scope.")
+    output["processing_source"] = {"stage": "derope", "scenes": used,
+                                   "fallback": "selected_original", "selection": selection}
+    # Geometry is checked per scene by deferred readers. A partial combined
+    # DeRoPE+upscale branch can legitimately differ from its original fallback.
+    return output

ComfyUI-MiniMaxH3-Context-Loop/docs/ADVANCED_WORKFLOWS.md

@@ -0,0 +1,246 @@
+# Advanced workflows
+
+## Extend an existing video
+
+Use **MiniMax H3 Existing Video Context** when scene 1 must continue a decoded
+video rather than start from an empty timeline. The complete experimental model
+is [Extend Existing Video Model Workflow - MiniMax H3](<../example_workflows/Archive/Extend Existing Video Model Workflow - MiniMax H3.json>).
+
+```text
+Plan ────────────────────────────────┐
+Core Load Video (VIDEO) ─────────────┼→ Existing Video Context → Loop Start
+Other loader IMAGE + AUDIO + FPS ────┘
+H3 audio VAE ─────────────────────────────────────────────→ Loop Context
+```
+
+Use exactly one video route:
+
+- `source_video` accepts native ComfyUI VIDEO, including embedded audio and
+  exact FPS. An explicit audio input overrides embedded audio.
+- `source_frames` accepts IMAGE from VHS or another decoder. Connect optional
+  AUDIO and set the real decoded `source_fps`.
+
+The adapter normalizes frames to the Plan canvas and H3's 24 fps, uses the last
+`context_length` frames as scene 1's predecessor, and can persist the normalized
+source as a prelude. In head mode:
+
+```text
+scene 1 delivered frames = raw frames - imported context frames
+```
+
+Connect the audio VAE to Loop Context for imported-audio timeline guidance in
+`generated_audio` or `source_plus_timeline`. Visual continuation still works
+without imported audio.
+
+With `prepend_original=true`, Assemble places the normalized original before
+generated scenes, including partial output. Arbitrary source codecs and frame
+rates cannot be stream-concatenated safely, so the prelude is encoded once at
+the Plan's `segment_crf`; generated H.264 segments remain stream-copied.
+
+The imported tail is fingerprinted. Reconnect the same Plan and source when
+resuming; a changed source correctly invalidates dependent checkpoints.
+
+Recommended first settings:
+
+```text
+Chain Policy         Guide
+encode_mode          video
+anchor_mode          head
+Loop Trim match_tail true
+Spectrum             off
+```
+
+Chain Policy derives both visual and generated-audio overlap as 22 frames for
+Guide. Use the Legacy 0.4 Policy Adapter only when this imported-context workflow
+deliberately needs different visual and audio overlap lengths.
+
+## Long visual context
+
+`56` is a valid advanced context length. It carries 2.33 seconds of motion in
+17 video latent steps, but head mode regenerates and removes all 56 frames from
+every continuation. Start with `22`; use `56` when a long clip's camera move or
+performance genuinely needs more history.
+
+## Non-linear visual context
+
+Scenes 2 and later normally take visual context from the immediately previous
+timeline scene. **Visual context source** in Plan or Plan Studio can instead
+select any earlier saved scene by stable scene ID:
+
+```json
+{
+  "id": "scene_5",
+  "visual_context_source": "scene_3",
+  "context_length": 39,
+  "video_blend_frames": 0
+}
+```
+
+This changes only the picture-side continuation edge. In this example scene 5
+uses scene 3's retained RGB/video latent, while Generated continuity still
+uses scene 4's audio latent. The timeline, branch ancestry, soundtrack clock,
+and final ordering remain 1 → 2 → 3 → 4 → 5. With head anchoring, the repeated
+scene-3 prefix is removed by Loop Trim, so `video_blend_frames: 0` delivers a
+hard cut from scene 4 to the newly generated part of scene 5.
+
+Non-linear visual context requires a zero assembly blend because the visible
+incoming timeline boundary is still scene 4 → scene 5. Checkpoint preflight
+verifies both consumed dependencies independently: the selected visual scene
+and, when enabled, the immediate generated-audio predecessor. Other earlier
+scenes remain assembly-only and do not become false resume blockers.
+
+### Selecting a source segment instead of its tail
+
+Plan Studio's **Context** tab previews the complete delivered video for every
+visual context block. The highlighted zone is the actual fixed-size context
+window: its width is proportional to the configured frame span. Drag that
+zone across the movie, place it near the player's current frame, or play only
+the selected window. The position snaps to H3's native 17-frame / five-latent-
+step temporal lattice. **Tail (default)**, or **Latest aligned (default)**
+when that block's phase cannot end on the physical tail, removes the override.
+
+The stored values are zero-based frame indexes within the source scene's
+delivered video (after that source's own incoming overlap was trimmed):
+
+```json
+{
+  "id": "scene_5",
+  "context_length": 22,
+  "visual_context_source": "scene_3",
+  "visual_context_start_frame": 119,
+  "video_blend_frames": 0
+}
+```
+
+For an untrimmed source this selects delivered frames 119 through 140 from
+scene 3. Valid numeric starts depend on the source's own trimmed incoming
+prefix, so use Plan Studio instead of hand-authoring an arbitrary frame. The
+backend converts both ends to native latent-step boundaries and slices the
+saved video latent directly. It never replaces that crop with an RGB VAE
+re-encode; RGB Guide/mask consumers use retained frames or a decode-only
+mirror. Generated-audio continuity remains the immediate previous scene's
+tail.
+
+## Composed visual context
+
+A continuation can use any ordered number of saved picture histories back to
+back. In Plan Studio's **Context → Picture** tab, select the total, the number
+of blocks, and the cumulative H3-native divisions. Every block then exposes
+its own earlier-scene source and exact latent-window selector. The last block
+sits immediately before the new generation:
+
+```json
+{
+  "id": "scene_5",
+  "context_length": 39,
+  "visual_context_blocks": [
+    {"source": "scene_3", "frames": 5},
+    {"source": "scene_4", "frames": 12, "start_frame": 0},
+    {"source": "scene_3", "frames": 22}
+  ],
+  "video_blend_frames": 0
+}
+```
+
+This example constructs one 39-frame visual prefix:
+
+```text
+scene 3 block:  5 RGB frames / 2 video-latent steps
+scene 4 block: 12 RGB frames / 3 video-latent steps
+scene 3 block: 22 RGB frames / 7 video-latent steps
+result:        39 RGB frames / 12 video-latent steps
+```
+
+The division selectors expose every valid ordered repartition without building
+an enormous combination menu. For example, three blocks within `39` include
+`5+12+22`, `5+17+17`, `5+29+5`, `17+5+17`, `17+17+5`, and `22+12+5`.
+Changing the count starts from a balanced valid repartition; moving each
+division explores all other native layouts.
+
+The blocks are concatenated in their authored order; they are not blended or
+interpolated. Both `22+17` and `17+22` now select source windows on the target
+block's matching temporal phase and concatenate the saved latent crops
+directly. For an inverse layout, the first block's latest aligned crop can end
+before its source movie's physical tail; Plan Studio shows that position.
+Every source may be any earlier scene on the active branch. Sources do not
+need to be chronologically ordered and the same source can appear more than
+once with independent windows. The composed prefix remains one context, so
+its normal head trim or AV mask uses the selected total exactly once.
+
+Composition changes only picture context. Generated audio remains one complete
+latent tail from the immediately previous timeline scene, so there is no audio
+splice at the internal visual seam and a scene's independent audio-context
+override still works. Final assembly still follows normal scene order and must
+use `video_blend_frames: 0` at this boundary. Checkpoint preflight verifies
+every selected visual revision plus the immediate audio predecessor when that
+audio continuity is active.
+
+Each `visual_context_blocks` item may omit `start_frame` to use its latest
+phase-aligned native crop. The released `visual_context_source` and
+`visual_context_lead_*` one/two-block fields remain accepted for existing
+Plans and checkpoints, but the new builder writes only the ordered list.
+
+## Independent audio context
+
+Plan Studio's **Context** planner keeps Audio locked by default. This preserves
+the established behavior: picture may use one or more selected windows, while
+generated audio remains one continuous tail from the immediately previous
+timeline scene. Existing plans therefore do not change.
+
+Choose **Unlock audio context** to reveal the Audio tab for that scene. It can
+select one earlier saved scene and an exact audio-latent range, or prepend a
+second independently positioned range. The two blocks are sequential context
+excerpts—not a decoded waveform mix—so they can, for example, expose voice
+regions from two characters before the new scene is generated:
+
+```json
+{
+  "id": "scene_5",
+  "audio_context_unlocked": true,
+  "audio_context_source": "scene_3",
+  "audio_context_start_frame": 0,
+  "audio_context_lead_source": "scene_4",
+  "audio_context_lead_frames": 5,
+  "audio_context_lead_start_frame": 12
+}
+```
+
+The lead block is first and `audio_context_source` is nearest generation. Both
+sources may point to the same scene to select two different moments. Positions
+are delivered-frame indexes and snap to crops whose duration is exact on H3's
+40 Hz audio-latent clock; the saved audio tensors are sliced directly without
+decode/re-encode. AV prefix implementations still use the picture context
+duration as their shared target span. Locking Audio again removes these custom
+fields and restores immediate-predecessor continuity.
+
+## Last-frame destinations
+
+When stock H3 Image to Video supplies `last_frame`, Motion Context preserves
+that target on continuation scenes. The carried repeated head replaces a
+conflicting `first_frame` anchor because both cannot own the same opening
+coordinates.
+
+Place official **MiniMax H3 Add Guide** nodes after Loop Context for additional
+scene-local image, video, or audio anchors.
+
+## Re-film a synchronized performance
+
+The [three-angle guitar workflow](<../example_workflows/Archive/Three-Angle Guitar Ref2VA - EXPERIMENTAL - MiniMax H3.json>)
+uses **Reference Video Prep** to convert native VIDEO or decoded IMAGE/AUDIO
+into exact 24 fps Ref2VA input. Its soundtrack is copied without padding or
+time-stretching, allowing one performance to be generated from multiple camera
+angles in one pass.
+
+Reference Video Prep rejects sources shorter than the requested H3-valid length
+instead of silently padding or stretching them.
+
+## External stitchers
+
+Loop Trim's `images_with_overlap` output exposes part of the repeated visual
+context while leaving its normal images and audio fully trimmed. Connect
+**Current Shot → state** to **Loop Trim → state**. Loop Trim then resolves each
+incoming scene's optional `video_blend_frames` override, or the Plan default
+when the scene value is blank. Scene N controls the N−1→N boundary. Keep it at
+`0` for a hard boundary. The old Plan/default and Current Shot/resolved integer
+outputs remain compatibility sockets only; do not wire either one in a 0.5
+workflow.

ComfyUI-MiniMaxH3-Context-Loop/docs/AUDIO_AND_CONTINUITY.md

@@ -0,0 +1,522 @@
+# Audio and continuity
+
+## Choose a generation profile
+
+New workflows should use **Generation Profile**, which replaces the individual
+audio switches with explicit intent:
+
+| Audio profile | Generation and final-output behavior |
+|---|---|
+| Generate audio | H3 generates sound and carries it between scenes |
+| Generate fresh audio per scene | H3 generates sound without carrying the preceding scene's audio latent |
+| Lip-sync to source audio | The exact source window drives generation; with grouped tracks, vocals drive generation and the full mix remains the final soundtrack |
+| Generate audio from source guide | Source audio is a loose reference while H3 creates the final sound |
+| Use source soundtrack only | The source track is used for assembly without guiding generation |
+| No final audio | The assembled MP4 is silent |
+
+Its **Scene continuity** profile separately selects visual continuity,
+independent scenes, a hard picture with protected audio, or a hard picture
+with a smooth audio release. The profile output is the same canonical
+`chain_policy` record used everywhere else and can feed Advanced Policy
+Override before Plan.
+
+For exact songs or dialogue, the optional **Lip-Sync Options** node adds audio
+context around each scene before encoding and can use an aligned isolated vocal
+stem to distinguish sung/spoken regions from instrumental gaps. Wire it as:
+
+```text
+source vocal stem ─→ Lip-Sync Options voice
+Lip-Sync Options lip_sync_options ─→ Generation Profile lip_sync_options
+Lip-Sync Options voice ────────────→ Chain Context lip_sync_voice
+```
+
+Select **Lip-sync to source audio** on Generation Profile. The original source
+song still enters through Loop Start or Source Timeline and remains the final
+soundtrack; the optional vocal stem is only a timing mask. With no options node,
+the established hard-cut/full-freeze behavior remains unchanged.
+
+The deprecated **Manual Chain Policy (Legacy)** remains loadable for existing
+workflows and unusual combinations that do not fit a named profile. Its legacy
+controls are described below.
+
+## Grouped songs: full mix, vocals and instrumental
+
+For songs, import the full mix and aligned stems into **Project Asset Carousel**.
+Keep one card as the **Source track**, then use its **Synchronized audio tracks**
+selectors to assign the full mix, vocals, and optional instrumental. Stem cards
+can have **Available to prompts** disabled and still serve the group. No prompt
+tag is required for source-locked lip-sync.
+
+Alternatively, connect AUDIO loaders to **H3 Audio Tracks** and feed its
+`source_timeline` output to the existing Source Timeline inputs on Run Manager
+or Loop Start. Use Generation Profile → **Lip-sync to source audio**.
+
+- **Full mix supplied:** used unchanged as the final soundtrack; stems are not
+  layered over it. Vocals alone supply the locked generation-audio target.
+- **No full mix:** supplied stems are summed once, matching sample rate and
+  mono/stereo channels. Gain is reduced only if their sum would clip. The
+  synthesized mix is cached for Studio playback; enable Run Manager's audio
+  archive for durable recovery together with the original stems.
+- **Missing vocals in a group:** lip-sync reports an error rather than using
+  instrumental music as its driver.
+- **Existing single track:** retains its previous routing; use **Reset to
+  single track** to remove a Carousel group.
+
+All tracks must have the same start and full duration, including silence during
+instrumental sections. They are aligned on the 24 fps source timeline, not
+automatically beat-matched, stretched or offset. Source routing does not perform
+stem separation; provide your own aligned stems.
+
+The **Lip-sync** selector in each scene's Studio/editor settings offers
+**Inherit**, **On** and **Off**. On locks that scene to vocals (or the original
+single source). Off disables the source target, loose source reference and
+generated-audio carry for that scene, while leaving the final soundtrack alone.
+Inherit restores the Plan's three audio defaults. Existing unusual combinations
+appear as **Custom** and remain editable with the advanced audio controls.
+
+This is a **per-scene** control, not an arbitrary timed on/off lane within one
+scene. Split scenes where you need explicit changes. Vocal silence avoids
+feeding instrumental notes to the lip-sync target, but neither silence nor Off
+guarantees that the model will animate a closed mouth; describe the desired
+action in the prompt. The separate Lip-Sync Options voice input remains an
+optional timing mask, independent of the group's vocal driver.
+
+## Manual policy axes
+
+Version 0.5 separates three independent decisions and one exact-target switch:
+
+| Axis | Values | Meaning |
+|---|---|---|
+| Final audio | `generated`, `source`, `none` | What Assemble places in the final MP4 |
+| Source reference | `on`, `off` | Whether the exact active source window guides H3 |
+| Generated continuity | `on`, `off` | Whether the previous sampled audio latent continues into the next scene |
+| Lock source audio | `on`, `off` | Whether each exact source window occupies the complete target audio latent and is protected from denoising |
+
+Set these controls and the default incoming boundary on the deprecated
+**Manual Chain Policy (Legacy)** node. Its output may connect directly to Plan
+or pass through an
+**Advanced Policy Override**. Advanced Policy preserves every audio choice and
+replaces only the incoming transition with a named experimental recipe such as
+Drift-Control AV. Use the **Legacy 0.4 Policy Adapter** only for a genuine 0.4
+import, a raw implementation/context pair, or an independent numeric audio
+overlap. It can also accept an incoming Chain Policy, in which case its legacy
+`audio_mode` is ignored and the modern audio intent is preserved.
+
+Policy layers are ordered left to right. Each downstream layer replaces only
+the boundary fields it owns; the last boundary layer wins, while the audio
+record continues unchanged:
+
+```text
+Generation Profile → Plan
+Generation Profile → Advanced Policy Override → Plan
+Manual Chain Policy (Legacy) → Plan
+Generation Profile → Legacy 0.4 Policy Adapter → Plan
+```
+
+The reverse Advanced/Legacy order is also valid: whichever is nearest Plan
+owns the effective transition. A standalone Legacy Adapter retains exact 0.4
+`audio_mode` behavior for imported workflows.
+
+### Per-scene audio behavior
+
+Final soundtrack remains a single Chain Policy choice, but the three
+generation-time audio axes can be overridden independently on each scene in
+Plan or Plan Studio:
+
+- **Source reference** decides whether that scene receives its exact source
+  window as a loose Ref2VA audio reference.
+- **Generated continuity** decides whether that scene carries the preceding
+  sampled audio latent.
+- **Lock source audio** places that scene's exact source window in the target
+  audio latent and protects it from denoising. Lock wins over the other two
+  switches for that scene.
+
+Each selector defaults to **Inherit Chain Policy**. Therefore existing plans
+do not change, and only scenes with an explicit override acquire new JSON or a
+new generation dependency. For example, a music video can use a source
+performance reference for scene 1, create fresh generated sound in scene 2,
+and lock an exact source passage in scene 3 while still choosing one global
+final soundtrack:
+
+```json
+{
+  "shots": [
+    {"id": "scene_1", "prompt": "...", "source_reference": "on"},
+    {"id": "scene_2", "prompt": "...", "generated_continuity": "off"},
+    {"id": "scene_3", "prompt": "...", "source_audio_target": "locked"}
+  ]
+}
+```
+
+The canonical stored values are `on`/`off` for `source_reference` and
+`generated_continuity`, and `locked`/`off` for `source_audio_target`. Omitting
+a key means inherit. Source audio still connects once at Loop Start or through
+Source Timeline; scenes that do not consume it need no rewiring. Changing one
+scene's effective source reference, generated carry, or lock invalidates that
+scene and its descendants, not unrelated earlier checkpoints.
+
+For a prerecorded song or dialogue performance that must remain exact, choose
+Source final audio and enable **Lock source audio**. The switch resolves Source
+reference and Generated continuity off: the source is no longer a loose Ref2VA
+audio bank or a carried predecessor prefix. Chain Context VAE-encodes the
+scene-local source window into H3's target audio stream and sets its complete
+denoise mask to zero. Video remains denoisable and can attend to the protected
+audio for timing and lip sync. Source-rate conversion for H3's audio VAE may
+still occur; final assembly with Final audio=source uses the Source Timeline
+track rather than model-decoded audio. For a short voice/timbre
+reference where H3 should generate new words, choose Generated final audio and
+schedule that clip as an ordinary tagged audio reference.
+
+Legacy music-video workflows may still connect a full `AUDIO` directly to
+Loop Start instead of building Source Timeline. Loop Start now materializes
+that waveform once under the run's `source_timeline/` folder and carries its
+path-backed recovery descriptor through recursive state, checkpoint metadata,
+and the final manifest. Current Shot, partial review assembly, final assembly,
+and the full-chain SeedVR2 adapter can therefore recover it without another
+audio wire. Existing redundant downstream wires remain compatible when their
+fingerprint matches. A manifest produced before this recovery descriptor was
+added still needs its legacy `source_audio` fallback connected.
+
+For normal finishing, leave `audio_source` set to `plan`. `Final audio =
+generated` uses the generated WAV sidecars written by Segment Save, `Final
+audio = source` uses the persisted source track, and `Final audio = none`
+stays silent. The explicit source/generated/none choices on finishing nodes are
+overrides, not required routing steps.
+
+Saved 0.4 modes migrate without changing behavior:
+
+| Legacy `audio_mode` | Final | Source reference | Generated continuity |
+|---|---|---|---|
+| `generated_audio` | generated | off | on |
+| `source_track` | source | on | off |
+| `source_plus_timeline` | source | on | on |
+
+These descriptions apply to `guide`, `tone_carry_guide`, `latent_guide`, and
+`tapered_guide`.
+Tone Carry Guide uses the RGB/VAE route and applies the predecessor's saved,
+direct boundary-tone curve before encoding its context. It falls back to clean
+Guide when no coherent curve was detected and never silently takes the direct
+video-latent path.
+When an older checkpoint predates this curve metadata, resume recovers it from
+the two existing scene videos. The saved checkpoint and sampled AV latent are
+reused unchanged; diffusion is not rerun.
+Latent Guide reuses the generated predecessor's sampled video-latent tail
+directly, while imported or incompatible context falls back to the normal
+RGB/VAE Guide route. Tapered Guide changes only the disposable video context
+passed to the Guide VAE. In the
+experimental `masked_av`, `tapered_av`, `feathered_av`, and
+`drift_control_av` modes, Chain Context always places a video prefix inside the
+target latent. With Generated continuity on it also
+places the matching audio prefix; `masked_av` protects that complete prefix and
+`tapered_av` protects a disposable video-only latent-noise copy of that prefix;
+`feathered_av` progressively denoises its final latent steps. With Generated
+continuity off, the audio mask remains fully open even when final assembly uses
+`source_track`. For recursive scenes, enabled audio carry copies the previous
+sampler's audio latent directly. For scene 1 after Existing Video Context,
+carrying imported audio requires source audio and the H3 audio VAE.
+
+With **Lock source audio** on and no Lip-Sync Options, the complete scene-local
+audio mask is zero. Lip-Sync Options can instead encode discarded pre-roll and
+lookahead context around the kept scene ticks. Its Voice-region denoise value
+applies to the whole song when no vocal stem is supplied. With a stem, vocal
+ticks use Voice-region denoise and gaps use Between-phrase denoise; the final
+assembly still uses the unmodified source soundtrack. This composes with every
+picture boundary: Cut and Guide affect only video context, while AV modes
+preserve or taper their video prefix without copying predecessor audio over the
+locked source window.
+
+Experimental `drift_control_av` is a recursive picture-only treatment layered
+on the same 39-frame AV prefix. It does not bake random noise into a checkpoint
+or redraw noise between scenes. At each model evaluation, it uses the sampler's
+existing noise field and sets the prefix mask to `next_sigma / current_sigma`.
+The oldest eight of the 12 video-latent steps use that complete ratio; the last
+four multiply it by `.75`, `.50`, `.25`, and `.00`, leaving the actual seam
+clean. The same live mask drives both ComfyUI's inpaint blend and, through an
+apply-model hook, H3's internal per-row timestep labels. Audio remains exact or
+open according to Audio Policy.
+
+Select **Drift-Control AV**, connect the H3 MODEL to Chain Context's optional
+`model` input, and use its `model` output for the first or only sampler stage.
+Chain Context stops before scene 1 when a Drift-Control Plan is missing that
+route. For a sigma split that switches models, leave Chain Context's `model`
+input disconnected. Connect the original full schedule (before the split) to
+its `drift_sigmas` input, then place **MiniMax H3 Drift-Control Model Patch
+(Sigma Split)** between each raw model and its sampler. Feed every patch Current
+Shot `state`, Chain Context `latent`, and that same original full sigma
+schedule. This keeps both model loaders independent and sequential. Each patch
+stores only a small CPU sigma tuple and cloned ModelPatcher metadata, not
+another copy of either model's weights.
+
+Do not put Differential Diffusion or another dynamic denoise-mask patch on the
+same MODEL path. The initial validated baseline is 39 frames and 20 sampling
+steps; other samplers, schedulers, and step counts remain experimental.
+
+The 0.5 **Soft AV** preset selects `audio_feathered_av`: all picture-prefix
+steps remain exact. With Generated continuity on, only the final eight carried
+audio ticks are released with a half-cosine ramp. With Generated continuity
+off, the target audio stays fully denoisable and paired source audio spans the
+complete raw scene window instead of inheriting the delivered-video window.
+This is the tested upstream AV extension recipe. The older
+dual-stream `feathered_av` remains a raw Legacy Adapter override for
+compatibility.
+
+AV prefixes must end on both native clocks: 39, 90, 141, 192, or 243 frames.
+The normal 39-frame prefix maps exactly to 12 video latent steps and 65 audio
+steps; 22 frames maps to 36.666... audio steps and is rejected before model
+loading. At 39 frames, legacy raw `feathered_av` fully protects the first 8 video /
+42 audio steps and ramps the final 4 video / 23 audio prefix steps.
+
+Chain Policy controls the normal incoming boundary: Cut carries no picture,
+Guide uses 22 clean RGB/VAE guide frames, Tone Carry Guide uses the same RGB
+span with the predecessor's detected tone correction, Latent Guide uses the
+same span from the saved sampled video latent, Detail Guide uses the same span with an
+eight-frame chroma-noise exit taper, Detail AV uses a protected disposable
+39-frame video-latent copy with matched-variance Gaussian noise tapering from
+0.30 to a completely clean boundary while leaving audio exact, Drift-Control
+AV applies schedule-matched noise to a clean carried prefix at every model
+evaluation, Hard AV uses a protected 39-frame prefix, and Soft AV keeps the
+picture exact while feathering only a carried-audio exit. With Generated
+continuity off, all AV presets carry picture only.
+Detail AV v2 is fixed to 39 frames. Its seed and complete recipe enter the
+incoming-boundary dependency fingerprint, its predecessor checkpoint is never
+mutated, and the entire treated prefix is trimmed before delivery. Advanced
+mode may pair either experimental Guide with another Guide context length; 22
+is the published baseline. Mixed plans must still use
+encode/anchor settings compatible with every AV-mask scene.
+
+Drift-Control AV v1 is also fixed to 39 frames. Its sigma rule, 8+4 temporal
+taper, mask quantization, audio behavior, and validated-step baseline enter the
+incoming-boundary dependency fingerprint. Changing the mode or recipe therefore
+requires regenerating that incoming scene, while the saved predecessor remains
+unchanged.
+
+**Color-Stable Drift AV** is the opt-in latent-domain counterpart to Final
+Assembly's scene-one color stabilizer. It keeps Drift-Control's 39-frame mask,
+but adds only the difference between a VAE encode of a weakly corrected RGB
+decode and an encode of the unchanged RGB decode. The shared VAE reconstruction
+error cancels. That low-frequency delta ramps from zero at the old overlap edge
+to full strength beside the generated future. The first generated scene is the
+anchor; scene 2 is therefore neutral, while scene 3 onward can resist recursive
+exposure/saturation drift. Audio and saved checkpoints remain exact. It costs
+one 39-frame decode and two 39-frame encodes only when a non-neutral correction
+is detected.
+
+In Plan Studio, a scene normally chooses Inherit, Cut, Guide, Hard AV, or Soft
+AV. That single choice writes the matching visual and generated-audio overlap.
+The raw per-scene implementation and separate visual/audio context fields are
+under Advanced boundary controls. Plan-wide raw 0.4 defaults belong to the
+Legacy 0.4 Policy Adapter.
+
+### Editorial scene placement, gaps, and subtitles
+
+Plan Studio can place each generated scene at an exact 24 fps timeline frame.
+The first legal position is the end of the preceding scene, so scene order and
+generation dependencies remain unchanged and clips never overlap. Moving a
+scene later creates uncovered track time; preview shows that interval as black
+and final Assemble renders the same number of black frames.
+
+Generated clip audio is moved with its scene and silence is inserted in every
+gap. Source Timeline audio instead remains locked to the absolute project clock,
+so a song continues through black. These positions live in the run's
+`editorial.json`, outside the Plan hash, and do not invalidate checkpoints.
+
+Prompt-word alternates use the same non-destructive editorial layer. An enabled
+`alternate_draft` identifies one active base revision, prompt, and seed. Its
+accepted immutable revision is recorded under `replacements` as
+`media_mode: picture_only`; the canonical `clip_NNNN.json` pointer is never
+changed. Final picture consumers resolve that replacement, while generated
+audio and every later scene dependency continue to resolve the base lineage.
+The boundary after an alternate must be a hard cut because a saved incoming
+blend contains frames from the original base take.
+
+An audio asset may also store lyrics. Timestamp lines as LRC (`[MM:SS.xx]`) or
+paste SRT, then select that asset in Plan Studio's Subtitles tab. Subtitle
+preview and exported `.srt` use the same absolute editorial clock and optional
+offset; they do not enter prompts or generation fingerprints.
+
+### Scheduled boundary spatial proxy
+
+`context_spatial_proxy` is an optional **per-scene incoming-boundary** setting.
+It is off when absent, so it can be scheduled only where a long chain begins
+to burn in or needs a controlled spatial reset:
+
+```json
+{
+  "id": "scene_4",
+  "continuation_mode": "masked_av",
+  "context_length": 39,
+  "context_spatial_proxy": "latent_5_6"
+}
+```
+
+`rgb_5_6` is shown as **Low-grid 5/6 · Guide** and is available for Guide,
+Tone Carry Guide, and Detail Guide on scenes 2 and later. It reduces the
+complete saved predecessor video latent (for example, 86×48 becomes 72×40),
+VAE-decodes that disposable stream natively at 1152×640, and selects the
+requested delivered RGB tail. Motion Context then restores that tail to
+1376×768 before the normal Guide encode. This preserves the nonlinear
+low-grid VAE decode observed in the source mixed-resolution experiment; it is
+not merely an RGB resize.
+Because it VAE-decodes the predecessor stream once more, Low-grid Guide uses
+more preparation time and peak memory than native Guide. Schedule it only on
+boundaries where the reset is wanted.
+`latent_5_6` is available for AV modes. It downscales and restores only the
+copied video-prefix latent (86×48 becomes 72×40 and returns to 86×48). It does
+not filter the paired audio prefix. Neither mode resizes generated frames,
+saved checkpoints, predecessor state, or assembly output. The fixed recipe is
+stored in the incoming-scene dependency, so enabling it for scene 4 leaves
+scenes 2 and 3 valid but requires scene 4 and its successors to be regenerated.
+
+## Source Timeline wiring
+
+Register picture and sound once. New workflows pass a typed descriptor instead
+of repeating a decoded full-track AUDIO wire:
+
+```text
+Load Video ─┐
+            ├→ Source Timeline ─┬→ Preflight / Plan Studio
+Load Audio ─┘                   └→ Loop Start → Current Shot
+                                                   └→ scene-local source slice
+
+Loop End manifest → Assemble (recovers the timeline descriptor)
+```
+
+Current Shot requests each overlap-aware scene window from the descriptor.
+Loop Start fingerprints the source so changed media cannot silently resume old
+checkpoints. Path-backed video and audio remain lazy; only the active scene is
+decoded. A tensor-only AUDIO input is normalized once into a run-owned file.
+The source must cover the required delivered timeline; Preflight reports the
+exact shortfall and last complete scene before model loading.
+
+The 0.4 Lazy Motion AV Loader fan-out remains accepted as a compatibility route:
+
+```text
+Lazy Motion AV Loader source_video ─┬→ Tagged Motion Ref source_video
+                                    └→ Run Manager asset
+Lazy Motion AV Loader source_audio ─┬→ Loop Start
+                                    ├→ Current Shot
+                                    ├→ Tagged Audio Ref
+                                    └→ Assemble
+Lazy Motion AV Loader skip frames ───→ Tagged Motion Ref skip frames
+```
+
+The native VIDEO remains disk-backed. The loader decodes only the complete
+post-skip audio track, which is still required: Loop Start establishes its
+fingerprint and Current Shot maps exact Plan frame windows onto its sample
+clock for H3 audio-latent alignment. Scene-local paired audio from the tagged
+motion reference does not replace this master track.
+
+For new workflows, Source Timeline performs that registration without decoding
+the complete audio track or requiring the downstream fan-out.
+
+### Tagged Ref2VA source timeline
+
+Current Shot's source slice may feed a standalone Tagged Audio Ref. Keep the
+registry fingerprint that returns to Plan independent of that downstream slice:
+
+```text
+Plan → Loop Start → Current Shot → Tagged Audio Ref → Tagged Ref2VA
+  ↑                                                     │
+  └──────── picture/reference registry fingerprint ─────┘
+```
+
+The canonical topology is:
+
+```text
+Load Audio → Source Timeline → Loop Start → Current Shot
+                                             ├→ source_audio_slice → Tagged Audio Ref
+                                             └→ state ─────────────→ Tagged Ref2VA
+```
+
+The structured scene dependency records the canonical PCM window, so that
+scene—not unrelated future audio—is invalidated when the source changes. Do not
+return the slice-derived audio fingerprint to Plan, because that would create a
+real graph cycle. Current Shot's optional alignment switch changes only the
+reference slice.
+
+## Experimental reference-grid alignment
+
+For 362 video frames, the exact picture duration is 15.083333 seconds. Stock H3
+creates 603 target audio steps, while an exact-duration audio reference reaches
+604 steps after audio-VAE padding.
+
+Current Shot's `align_audio_reference` switch shortens only its Ref2VA output:
+
+```text
+362-frame source window: 15.083333 s
+aligned reference slice: 15.070000 s
+reference audio latents: 603, with a 5 ms padded tail in the final step
+```
+
+The exact 15.075-second latent boundary still reproduced visual duplication in
+testing; 15.070 seconds did not. The switch therefore uses a 5 ms safety
+undercut. It computes the equivalent sample boundary for the connected sample
+rate, passes shorter audio through unchanged, and never changes the full source
+used by Assemble.
+
+This remains experimental model-behavior guidance rather than a proven H3
+architecture requirement. Leave the switch off when comparing against stock
+frame-exact behavior.
+
+## Generated audio is always retained
+
+When decoded audio is connected to Segment + Checkpoint, every scene receives
+an uncompressed WAV under:
+
+```text
+output/h3_chains/<run_name>/generated_audio/
+```
+
+Completed assembly also writes `<final-name>.generated.wav` beside the MP4,
+even when the final video uses `source_track`. This keeps H3's ambience, effects,
+and regenerated performance available for post-production.
+
+Generated WAV assembly budgets samples from cumulative delivered-video frame
+boundaries, preventing per-scene rounding from accumulating into drift. This
+approach was inspired by **seitanism's**
+[MultiRef implementation](https://github.com/seitanism/ComfyUI-H3-Motion-Context-MultiRef).
+For masked AV, Loop Trim also carries the complete decoded overlap privately
+inside its normal AUDIO output. Segment Save checkpoints it, and the later
+scene owns that interval during combined generated-audio assembly. This keeps
+Soft AV's half-cosine audio release instead of throwing it away at the trim.
+The same ownership rule applies when scene 1 continues an Existing Video
+Context prelude. Legacy checkpoints without the extra tensor keep
+delivered-only assembly.
+
+## Continuation trimming
+
+Use **MiniMax H3 Context Loop Trim** after decoding. In head mode it removes the
+repeated visual prefix. With `match_tail=true`, it time-conforms the small H3
+grid mismatch to the exact delivered-frame duration and carries the
+full AV overlap privately to Segment Save. Connect Trim's AUDIO output directly;
+there is no second overlap-audio socket.
+
+`images_with_overlap` exposes an additional visual stream containing the
+retained repeated context selected by the active scene state. In 0.5 chains,
+wire **Current Shot → state** to **Loop Trim → state**. A scene-level
+`video_blend_frames` value controls the boundary entering that scene; blank
+inherits the Plan default and explicit `0` keeps a hard cut. The manual
+`retain_overlap_frames` input and both blend integer outputs are legacy routes.
+This assembly-only setting does not alter diffusion, the normal clean images
+output, or audio.
+
+All continuation modes return the prefix length as `trim_frames`. In AV mask
+modes those leading frames come from target-latent rows rather than persistent
+guide-conditioning rows. They still overlap the preceding scene and must be
+removed from delivered duration, including the feathered portion.
+
+## Measure a join
+
+Place **MiniMax H3 Context Loop Seam Probe** between the current clip's untrimmed
+audio decode and Loop Trim. Connect the preceding sampler AV latent, H3 audio
+VAE, and the same `trim_frames` value.
+
+The AUDIO output is unchanged. The report measures:
+
+- correlation across the join;
+- estimated timing offset;
+- broadband level step;
+- low-frequency ambience-floor step.
+
+Strongly periodic music can alias by one complete cycle; the report marks that
+as a known limitation. `tests/seam_probe.py` provides the file-based equivalent.

ComfyUI-MiniMaxH3-Context-Loop/docs/COMPATIBILITY.md

@@ -0,0 +1,132 @@
+# Compatibility
+
+## Runtime scope
+
+Installing the pack does not globally alter ordinary ComfyUI workflows. Its H3
+conditioning patches activate when a Context Loop Context node executes and
+self-check the live model/layout assumptions before use.
+
+The two continuation engines and public masking path are capability-gated:
+
+- `guide`, `latent_guide`, and `tapered_guide` prefer native Add Guide /
+  MultiRef behavior from ComfyUI PR #15439 and use the existing guarded guide
+  fallback only on older builds. Latent Guide directly slices a compatible
+  generated predecessor's saved video latent and otherwise falls back to the
+  RGB/VAE route. Tapered Guide alters only its disposable RGB context before
+  VAE encoding;
+- `masked_av`, `tapered_av`, `feathered_av`, and `drift_control_av` prefer native per-token H3 AV masks from PR
+  #15375 and lazily install only missing mask-engine, payload, token-aligned
+  inpaint-scale, and legacy sampler-bridge behavior when the masked path
+  executes. It follows
+  PR #15375 commit `989e7a9`: pixel masks stay intact for final sampler
+  blending while internal H3 timesteps use pooled token-grid values. It still
+  requires the native #15439 Add Guide / MultiRef core baseline; masked mode
+  is not enabled on the older guide-fallback architecture.
+- `drift_control_av` additionally needs current ModelPatcher dynamic-mask and
+  apply-model-wrapper APIs. Chain Context installs both hooks on a cloned MODEL
+  and refuses an existing dynamic denoise-mask function rather than composing
+  two incompatible owners. A sigma-split model switch uses the dedicated
+  one-model Drift-Control Model Patch for each raw branch and shares the
+  original unsplit sigma schedule; the patch does not copy model weights.
+- `MiniMaxH3ContexMaskedTarget` uses the same native-first per-token AV mask
+  layer for arbitrary manual targets. It activates compatibility only when the
+  node executes and does not require a separate MODEL patch node.
+
+Importing the node pack or running a guide-only workflow does not activate the
+masked runtime compatibility. A partially updated native mask engine is
+rejected rather than mixed with the vendored snapshot.
+
+The general masking IDs are deliberately different from
+`ComfyUI-MiniMaxH3-PerRowMasking`, so both folders may be installed during
+migration without one pack replacing the other's registered nodes.
+
+After updating ComfyUI or H3 optimization packs, restart the process fully so
+patch ownership is rebuilt cleanly.
+
+## H3 Motion Context copies
+
+This pack no longer registers the historical public Motion Context ids, so
+NikoDemon80's original pack or seitanism's maintained MultiRef pack may coexist
+without a node-id collision. When seitanism's registered
+`MiniMaxH3MotionContext` is present on native-guide ComfyUI, Chain Context calls
+it for compatible Guide scenes while retaining the same Chain node UI and
+workflow contract.
+
+Loop-only capabilities currently remain internal: direct saved-video-latent
+Guide reuse, audio-only continuation, a timeline-audio window longer than the
+visual Guide, and the guarded pre-native-core fallback.
+The adapter also resolves carried-head keyframe collisions and restores exact
+latent-audio placement after the upstream call.
+
+The retained engine follows the current provider contract for arbitrary exact
+Guide lengths, interior `target_start` placement, native-run batching, and
+end-aligned 40 Hz source-audio encoding. This keeps a capability-gated fallback
+scene behaviorally consistent instead of silently reverting to the older
+snap-to-grid implementation.
+
+Compatible legacy patch copies share ownership markers; the second copy
+normally stands down.
+
+If an older compatible copy owns the process first, wire **MiniMax H3 Patch
+Priority** before Context Loop Context. It can replace only a recognized sibling
+implementation. Unknown wrappers fail with an ownership explanation rather
+than being overwritten.
+
+## Native MiniMax H3 tokenizer tokens
+
+[ComfyUI PR #15808](https://github.com/Comfy-Org/ComfyUI/pull/15808)
+registers the seven additional tokens declared by MiniMax H3's released
+`tokenizer_config.json`: dialogue open/close, cutoff, lyrics open/close, and
+caption open/close. On an older ComfyUI build, this pack installs the same
+token list on the module-local MiniMax Qwen tokenizer during startup and
+refreshes its inverse vocabulary. General Qwen tokenizers are not changed.
+
+When core exposes its native `MiniMaxQwenSDTokenizer`, the compatibility hook
+stands down. Restart ComfyUI after updating core so tokenizer ownership is
+detected before any H3 text encoder is loaded.
+
+## Native MiniMax H3 Add Guide
+
+When ComfyUI provides native **MiniMax H3 Add Guide**, core owns arbitrary
+video/audio guide records and payload merging. This pack retains only the
+marker-gated target-alignment behavior needed for Ref2VA continuation.
+
+Place official Add Guide nodes after Loop Context so they append scene-local
+anchors to the already constructed continuation guides.
+
+## H3-Multishot and SolAttn
+
+- H3-Multishot's recognized AV-bank payload is reused rather than wrapped a
+  second time.
+- Kijai's SolAttn H3 Morton observer composes safely in either activation order.
+  Recognition is independent of the custom-node folder name: the upstream
+  module, path-loaded PR helpers such as `sol_attn_minimax_v2`, renamed copies,
+  and nested observer copies are identified by their audited `original_init`
+  closure plus read-only `_video_span`/`_SPANS` registration behavior. Merely
+  having a similar name or constructor closure is insufficient, so unknown
+  layout-mutating wrappers remain rejected.
+- Ref2VA media remains intact when continuation guides are merged.
+- Changed layout assumptions and unknown wrappers fail loudly.
+
+Keep Spectrum and other step-skipping systems disabled for baseline continuity
+tests. KJ preview bridging is scoped to the active loop.
+
+## Legacy widget widths
+
+While any Context Loop node is present on a legacy LiteGraph canvas, the pack
+works around
+[ComfyUI frontend issue #12443](https://github.com/Comfy-Org/ComfyUI_frontend/issues/12443)
+for all visible nodes. A separate Legacy Widget Width Fix node is unnecessary
+but remains compatible.
+
+Disable the embedded workaround under **Settings → MiniMax H3 Context Loop →
+Compatibility → Widget widths** if another frontend or extension handles it.
+
+## Platform notes
+
+- Review and Assemble prefer `ffmpeg` but fall back to bundled PyAV.
+- The Plan's Output action opens paths on the ComfyUI host. On headless or
+  remote servers it copies the host path; the browser cannot open an arbitrary
+  remote filesystem path on the client machine.
+- Run Manager operates against the ComfyUI host's input/output folders and is
+  therefore suitable for Docker and remote deployments.

ComfyUI-MiniMaxH3-Context-Loop/docs/FEATURE_TRACEABILITY.md

@@ -0,0 +1,81 @@
+# Feature traceability
+
+This page answers two questions: **where did a feature come from?** and
+**where is it implemented here?** It is a navigation aid, not a replacement
+for the license notices or Git history.
+
+Origin labels have precise meanings:
+
+- **Original** — designed and implemented in this repository.
+- **Adapted** — implementation work is based on an identified upstream
+  project or algorithm.
+- **Inspired** — an upstream idea or interaction informed a new local
+  implementation.
+- **Integrated** — this pack targets or interoperates with an upstream API;
+  it does not claim that upstream implementation.
+- **Compatibility** — retained only so older workflows or compatible packs
+  continue to work.
+
+For copied or adapted work, [Third-party notices](../THIRD_PARTY_NOTICES.md)
+remain the authoritative attribution and license record.
+
+## Production loop and authoring
+
+| Feature | What users get | Origin | Implementation and evidence |
+|---|---|---|---|
+| Recursive scene loop | One reusable H3 sampling body advances through a scene plan. | **Original**, built on the adapted Motion Context foundation described below. | [`chain_nodes.py`](../chain_nodes.py), [initial loop commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/3a744122ce4cf2a2e611a6f2fd90ac8ec7318070) |
+| Plan and scene editor | Multiline prompts, exact H3 timing, per-scene seeds, settings, and bounded scene ranges. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [`web/h3_chain_plan_editor.js`](../web/h3_chain_plan_editor.js), [visual editor commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/c56bc6e85496d66bf08da426567a9ab42cd5c78c) |
+| Per-scene LoRA model routing | Each scene selects the Base model or one of the scheduler's connected LoRA-patched `MODEL` branches. Route inputs grow progressively from A through Z, Plan and Studio expose only connected routes, and unused branches remain lazy. Existing A-D workflows retain their saved route IDs and connections. | **Original**; interoperates with ComfyUI's standard `MODEL` connections and lazy-input contract without loading or applying LoRAs itself. | [`chain_nodes.py`](../chain_nodes.py), [`web/h3_chain_lora_scheduler.js`](../web/h3_chain_lora_scheduler.js), [`web/h3_lora_scheduler_core.mjs`](../web/h3_lora_scheduler_core.mjs), [`web/h3_chain_plan_editor.js`](../web/h3_chain_plan_editor.js), [`web/h3_chain_plan_studio.js`](../web/h3_chain_plan_studio.js), [progressive routing commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/01540d38434d2f7ecbacbcd3a43e8c1da01ceeb8) |
+| Strict H3 prompt authoring | Both prompt editors provide mode-aware section validation/repair, alignment helpers, completions, diagnostics, counts, and Plain/Rich presentation. | **Backported** from the original standalone [H3 Prompt IDE](https://github.com/ethanfel/ComfyUI-H3-Prompt-IDE), which itself was adapted from this repository's editor. | [`web/h3_prompt_schema_core.mjs`](../web/h3_prompt_schema_core.mjs), [`web/h3_prompt_schema_ui.mjs`](../web/h3_prompt_schema_ui.mjs), [`web/h3_prompt_completion_core.mjs`](../web/h3_prompt_completion_core.mjs) |
+| Review, retry, and reroll | Every rendered scene can be approved, edited and retried, rerolled, or used to stop with a valid partial run. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [`web/h3_chain_review_final.js`](../web/h3_chain_review_final.js), [Review Gate commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/6bb0082edf66ce6b199dd165644868fb2ee66a39) |
+| Checkpoints, resume, and assembly | Accepted scenes are saved atomically and assembled from disk without a cumulative image tensor. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [`run_manager.py`](../run_manager.py), [resumable loop commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/3a744122ce4cf2a2e611a6f2fd90ac8ec7318070) |
+| Run Manager and prompt history | Saved plans, branching prompt revisions, archived loader assets, and run restoration. | **Original** | [`run_manager.py`](../run_manager.py), [`prompt_history.py`](../prompt_history.py), [Run Manager](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/2695a9a950511c0f42e95052fcd82b98046c1476), [prompt history](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/5543ff73469a663ac4c07bb6f6ceb9d462f6973b) |
+| Plan Studio and Rich Scene Prompt Editor | Optional timeline authoring, source comparison, richer prompt presentation, and optimizer connections. | **Original, experimental UI**; selected quick-reference and dialogue interactions are **inspired** by `ComfyUI-MiniMaxH3-Easy`. | [`web/h3_chain_plan_studio.js`](../web/h3_chain_plan_studio.js), [`web/h3_chain_rich_scene_prompt_editor.js`](../web/h3_chain_rich_scene_prompt_editor.js), [notice](../THIRD_PARTY_NOTICES.md#comfyui-minimaxh3-easy) |
+| Preflight and structured dependencies | Model-free checks explain source length, references, compatibility, and exactly which change invalidates a saved scene. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [`contracts_v05.py`](../contracts_v05.py), [preflight](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/855c06e6341743246052b2d8530b26da850e689c), [scene dependencies](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/100e65861995b1a59d94ef73b334120e6835988d) |
+| PNG/WAV re-decode | Saved scene latents can be decoded later into lossless PNG sequences, a synchronized PCM WAV, or both. Picture and audio VAEs are independently optional; cached integrity checks, bounded parallel atomic PNG saving, progress, timings, trim/order alignment, and partial recovery remain available. | **Original**; chunked CPU conversion and threaded image saving are **inspired** by [`ethanfel/ComfyUI-JSON-Dynamic`](https://github.com/ethanfel/ComfyUI-JSON-Dynamic)'s Fast Absolute Saver. | [`chain_nodes.py`](../chain_nodes.py), [PNG export commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/d1dd4f7daae15b48a31ec86cc54d0c75de20a769) |
+
+## Continuity, audio, and editing
+
+| Feature | What users get | Origin | Implementation and evidence |
+|---|---|---|---|
+| H3 Motion Context foundation | Previous frames condition the next scene; last-frame targets, 56-frame context, and seam diagnostics remain available. | **Adapted** from [`NikoDemon80/ComfyUI-H3-Motion-Context`](https://github.com/NikoDemon80/ComfyUI-H3-Motion-Context). | [`nodes.py`](../nodes.py), [`probe_node.py`](../probe_node.py), [`patch_layout.py`](../patch_layout.py), [notice](../THIRD_PARTY_NOTICES.md#comfyui-h3-motion-context) |
+| Guide and Cut transitions | Clean RGB/VAE context or no carried picture, selected by an incoming-scene policy. Compatible Guide scenes transparently use the installed upstream Motion Context provider; the retained fallback supports exact arbitrary lengths, interior placement, and exact-grid source audio. | Local policy and compatibility adapter are **Original**; low-level Guide construction and the exact 40 Hz audio-grid helper are **Integrated/adapted** from [`seitanism/ComfyUI-H3-Motion-Context-MultiRef`](https://github.com/seitanism/ComfyUI-H3-Motion-Context-MultiRef), with native placement from [ComfyUI PR #15439](https://github.com/Comfy-Org/ComfyUI/pull/15439). | [`chain_nodes.py`](../chain_nodes.py), [`motion_context_upstream.py`](../motion_context_upstream.py), [`nodes.py`](../nodes.py), [`h3_audio_grid.py`](../h3_audio_grid.py), [`contracts_v05.py`](../contracts_v05.py), [notice](../THIRD_PARTY_NOTICES.md#comfyui-h3-motion-context-multiref) |
+| Tone Carry Guide | Detects a coherent boundary tone difference and applies a saved correction to the next disposable RGB guide. | **Original, experimental** | [`chain_nodes.py`](../chain_nodes.py), [implementation commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/0b2068c238db527910aa727ed4e7ded0bb73af20) |
+| Latent Guide | Reuses the predecessor's compatible sampled video-latent tail and falls back to RGB/VAE Guide when needed. | **Original, opt-in** | [`chain_nodes.py`](../chain_nodes.py), [implementation commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/e211007efb7b872d3dd86d161524ef59f6a9d822) |
+| Detail Guide | Applies a deterministic, tapered chroma-noise treatment to a disposable Guide copy. | **Adapted, experimental** from [`MacroSony/minimax-h3-chained-character-swap`](https://github.com/MacroSony/minimax-h3-chained-character-swap). | [`chain_nodes.py`](../chain_nodes.py), [local integration](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/c797345932d5f8492d8c8f967a73d507b65b5375), [notice](../THIRD_PARTY_NOTICES.md#minimax-h3-chained-character-swap) |
+| Hard AV and Soft AV | Carries an exact protected picture prefix; optionally carries exact or audio-feathered generated sound. | **Adapted** from [`seitanism/ComfyUI-H3-Motion-Context-MultiRef`](https://github.com/seitanism/ComfyUI-H3-Motion-Context-MultiRef). Per-token masking is **Integrated** with [ComfyUI PR #15375](https://github.com/Comfy-Org/ComfyUI/pull/15375). | [`masked_context.py`](../masked_context.py), [`h3_mask_compat.py`](../h3_mask_compat.py), [masked AV commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/e4ec458af0063be7774dae8dc3575c8c96248935), [notices](../THIRD_PARTY_NOTICES.md#comfyui-h3-motion-context-multiref) |
+| Detail AV | Adds matched-variance latent noise to a disposable Hard AV picture prefix, tapering to a clean boundary while leaving audio exact. | **Adapted, experimental** from [`beijinren/ComfyUI-H3-Context-Noise`](https://github.com/beijinren/ComfyUI-H3-Context-Noise). | [`masked_context.py`](../masked_context.py), [local integration](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/72a4e449425c9b4174cabb0eda4da3eeed6d78de), [notice](../THIRD_PARTY_NOTICES.md#comfyui-h3-context-noise) |
+| Drift-Control AV | Applies the sampler's existing noise field to a clean carried video prefix at the next scheduler sigma, with an 8+4 clean-seam mask shared by sampler blending and H3 row timesteps. | **Original, experimental integration** built on ComfyUI's dynamic denoise-mask and H3 per-token mask APIs. | [`drift_control.py`](../drift_control.py), [`chain_nodes.py`](../chain_nodes.py) |
+| Color-Stable Drift AV | Adds a tapered, low-frequency `E(graded D(z)) - E(D(z))` scene-one color delta to Drift-Control's disposable copied video prefix; audio and saved latents remain immutable. | **Original, experimental integration.** | [`latent_color_carry.py`](../latent_color_carry.py), [`masked_context.py`](../masked_context.py), [`chain_nodes.py`](../chain_nodes.py) |
+| Reference Video Fade | Keeps complete native Ref2VA video blocks at full early influence, then applies a full-schedule half-cosine value-row fade while preserving still refs, Qwen presentation, audio, guides, targets, and an existing attention backend. | **Original, experimental.** | [`reference_video_fade.py`](../reference_video_fade.py), [design and wiring](REFERENCE_VIDEO_FADE.md) |
+| Audio policies and exact timing | Final soundtrack, source reference, and generated continuity are independent; cumulative frame boundaries prevent long-run A/V rounding drift. | Policy contract is **Original**. Cumulative audio budgeting is **Inspired** by MultiRef; exact AV timing paths are **Adapted** from later MultiRef updates. | [`av_timing.py`](../av_timing.py), [`chain_nodes.py`](../chain_nodes.py), [audio policy](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/d47523cac69aacd8eed2bd82717771ba49751f7a), [timing integration](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/06045d4aca71316269bbc32b6add6fc843047c1d), [notice](../THIRD_PARTY_NOTICES.md#comfyui-h3-motion-context-multiref) |
+| General masked editing | Loop-aware source AV targets, tracked-mask slicing, 32px cell preview, audio preservation, inpaint/outpaint, and mask composition. | **Adapted** from [`ethanfel/ComfyUI-MiniMaxH3-PerRowMasking`](https://github.com/ethanfel/ComfyUI-MiniMaxH3-PerRowMasking); mask execution uses the PR #15375 integration instead of the earlier model wrapper. | [`masking_nodes.py`](../masking_nodes.py), [`source_av_target.py`](../source_av_target.py), [`masking_ops.py`](../masking_ops.py), [local integration](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/174e8d2dabba6892092300c67286e16aa0dfbbf0), [notice](../THIRD_PARTY_NOTICES.md#comfyui-minimaxh3-perrowmasking) |
+| Exact causal mask conversion | Thin or moving masks are max-reduced through H3's causal frame groups and 2x2 latent-token cells instead of being weakened by temporal interpolation. | **Adapted** from [`drozbay/MaskVidExperiments`](https://github.com/drozbay/MaskVidExperiments). | [`masking_ops.py`](../masking_ops.py), [`masking_nodes.py`](../masking_nodes.py), [notice](../THIRD_PARTY_NOTICES.md#maskvidexperiments-causal-mask-conversion) |
+| Master-audio continuation and two-ended AV bridge | Protects exact soundtrack windows, optionally carries a video prefix, or preserves both clip endpoints while generating the gap. | **Adapted** from MultiRef Updates 4–6. | [`master_audio_context.py`](../master_audio_context.py), [`masked_bridge.py`](../masked_bridge.py), [notice](../THIRD_PARTY_NOTICES.md#comfyui-h3-motion-context-multiref) |
+| Boundary blending and partial recovery | Scene-specific overlap blends also survive interrupted-run assembly. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [frame-exact blending](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/0e4f070e6d95f6288022281cf2b0d0b337443907), [recovery schedules](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/73bfb911871bd593d764479fb256bf1925db26a6) |
+
+## References, media, and interoperability
+
+| Feature | What users get | Origin | Implementation and evidence |
+|---|---|---|---|
+| Prompt-driven tagged references | Stable `@tags` activate only the pictures, videos, motion, and audio used by the current scene. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [`web/h3_reference_autoconnect.js`](../web/h3_reference_autoconnect.js), [v0.4 tagged workflow commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/c21bebd0eb0d72e6c30d4389ab0f1ec0a0bfc9d6) |
+| Qwen-only semantic pictures and timed anchors | Bare `#picture` adds an untimed Qwen visual; `#picture[time]` adds explicit approximate placement or a picture-storyboard cue. Neither creates a native VAE reference. | **Original, experimental** | [`chain_nodes.py`](../chain_nodes.py), [syntax](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/73af736ae9d2e59355e55b3b0c17311e651587aa), [conditioning](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/1355c390e2ead60c19a45024220b50d5d6ebd25f), [storyboard mode](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/11783a3d57982dc3bd00fff4f55c5d2787ea65d4) |
+| Source Timeline and lazy motion media | Register source media once, decode only the active scene window, and retain exact FPS/PTS and recovery provenance. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [disk-backed loader](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/9438c67e3eb10680ed5d9880448936c0908f50f2), [typed timeline](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/f168555e5ff98ec2ec866be2e75a603ca0a6fc11) |
+| Existing-video continuation | Scene 1 can continue an imported clip and optionally prepend the normalized original during assembly. | **Original** | [`chain_nodes.py`](../chain_nodes.py), [workflow commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/a7ebfa7b3bd61458e7efe162165bb1c0ba8a65f1) |
+| Legacy scheduled references | Numeric scene selectors remain available for old graphs and explicit schedules. | **Original, compatibility route** | [`chain_nodes.py`](../chain_nodes.py), [initial schedule commit](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop/commit/6b3a36809f53662aaacf1480716ea62f2345af46) |
+| H3-Multishot and SolAttn coexistence | Known external payload and attention wrappers remain active instead of being overwritten. | **Integrated compatibility**; SolAttn defensive detection includes a contribution by `tsolful` in repository PR #16. | [`patch_layout.py`](../patch_layout.py), [`patch_payload.py`](../patch_payload.py), [compatibility guide](COMPATIBILITY.md) |
+| Legacy widget-width repair | Older serialized widgets remain usable in current ComfyUI frontends. | **Adapted** with permission from [`pekkAi-dev/ComfyUI-LegacyWidgetWidthFix`](https://github.com/pekkAi-dev/ComfyUI-LegacyWidgetWidthFix). | [`web/h3_legacy_widget_width_fix.js`](../web/h3_legacy_widget_width_fix.js), [notice](../THIRD_PARTY_NOTICES.md#comfyui-legacywidgetwidthfix) |
+
+## Example and media provenance
+
+Example-specific prompts, images, footage, and licensing are recorded next to
+the workflow that uses them:
+
+- [Workflow catalog and prompt sources](../example_workflows/README.md)
+- [Bundled example asset licenses](../example_workflows/assets/README.md)
+- [Complete third-party notices](../THIRD_PARTY_NOTICES.md)
+
+When adding a feature from another project, update this page and
+`THIRD_PARTY_NOTICES.md` in the same change. Record the upstream repository,
+author, revision, license, local files, and whether the relationship is
+adapted, inspired, integrated, or compatibility-only.

ComfyUI-MiniMaxH3-Context-Loop/docs/GETTING_STARTED.md

@@ -0,0 +1,186 @@
+# Getting started
+
+This guide takes the shortest path from a clean install to one reviewed,
+assembled video.
+
+## 1. Install the packs
+
+From `ComfyUI/custom_nodes`:
+
+```bash
+git clone https://github.com/seitanism/ComfyUI-H3-Motion-Context-MultiRef.git
+git clone https://github.com/ethanfel/ComfyUI-MiniMaxH3-Contex-Loop.git
+```
+
+Restart ComfyUI. Use a current ComfyUI build with native **Add Guide for
+MiniMax H3** support. `ffmpeg` is recommended for preview and assembly; PyAV is
+the fallback where supported.
+
+You also need your own MiniMax H3 diffusion model, text encoder, video VAE, and
+audio VAE. They are not included in this repository.
+
+## 2. Open the smallest matching example
+
+| Your starting material | Recommended first workflow |
+|---|---|
+| Text only | [T2V Normal](<../example_workflows/T2V Normal - MiniMax H3 0.6.json>) |
+| One opening image | [I2V Normal](<../example_workflows/I2V Normal - MiniMax H3 0.6.json>) |
+| First and last images | [FL2V Normal](<../example_workflows/FL2V Normal - MiniMax H3 0.6.json>) |
+| Prompt-selected references | [Ref2V Tagged](<../example_workflows/Ref2V Tagged - MiniMax H3 0.6.json>) |
+| Existing video | [Masked AV Extension — Single Clip](<../example_workflows/Masked AV Extension - Single Clip - MiniMax H3 0.6.json>) |
+
+Open or drag the JSON into ComfyUI. Start with a **Normal** workflow. Studio is
+an optional editorial interface, not a simpler sampler.
+
+Some examples use bundled media. Copy those files from
+[`example_workflows/assets/`](../example_workflows/assets/) to `ComfyUI/input/`
+before opening the workflow.
+
+## 3. Resolve models and missing nodes
+
+Set the four model loaders:
+
+| Loader | Select |
+|---|---|
+| **Load Diffusion Model** | MiniMax H3 model |
+| **Load CLIP** | H3 text encoder |
+| **Load VAE — Video** | H3 video VAE |
+| **Load VAE — Audio** | H3 audio VAE |
+
+If ComfyUI reports a missing `MiniMaxH3MotionContext` node, install or update
+the MultiRef companion pack and restart. If it reports missing native H3 nodes,
+update ComfyUI.
+
+Deferred-upscale examples need extra packs. Their requirements are listed in
+the [workflow catalog](../example_workflows/README.md#deferred-upscale).
+
+## 4. Edit only the first-run controls
+
+### Plan
+
+For a new graph, use **MiniMax H3 Plan (Modern)**. It keeps the established
+vertical scene-column editor but groups its smaller control set into Project,
+Canvas, Generation defaults, and Delivery. Its Generation Profile connection
+is required, and it has no legacy context, audio, or continuation fallbacks.
+
+The original **MiniMax H3 Context Loop Plan** remains unchanged so old workflows
+open safely. After connecting Generation Profile, right-click it and choose
+**Upgrade to Modern Plan…** to preserve its scenes, supported settings,
+position, and links.
+
+Set these values first:
+
+| Control | First-run choice |
+|---|---|
+| `run_name` | A short unique name, for example `red_kite_test_01` |
+| Width / height | Keep the example defaults |
+| Scene Plan | Replace the sample scene prompts |
+| Default duration | Keep the example default until the graph works |
+
+`run_name` is the identity of the production. Reusing it exposes the same
+checkpoint history; changing it starts a separate run.
+
+Use the visual Scene Plan or Scene Prompt Editor for normal work. Raw Plan JSON
+is an import/export and advanced-editing surface.
+
+### Continuity and audio
+
+For a new graph, connect **Generation Profile** to Plan and begin with:
+
+| Control | Recommended value |
+|---|---|
+| Scene continuity | **Visual continuity** |
+| Audio profile | **Generate audio** |
+
+Some shipped examples still contain the compatible **Manual Chain Policy
+(Legacy)** node. Its saved Guide/generated defaults are safe for a first run;
+you do not need to rebuild the workflow before testing it.
+
+### Review Gate
+
+Keep `enabled = true`. Start with `candidate_count = 1`. Multiple candidates
+are useful after the basic workflow is working.
+
+## 5. Understand the disabled nodes
+
+Most generation examples include two grey or muted recovery nodes:
+
+```text
+[MUTED] Load Manifest  ──>  [MUTED] Assemble — recovery
+```
+
+They are intentionally present but do not execute during generation. Leave
+them muted for the first run. The active Assemble node connected to Loop End
+handles normal final assembly.
+
+A bypassed node is different: it forwards a compatible input without applying
+its operation. Optional attention overrides in some upscale examples are
+bypassed because they are not safe on every system.
+
+See the [disabled-node legend](NODE_REFERENCE.md#how-disabled-nodes-are-shown)
+for the notation used throughout these docs.
+
+## 6. Queue and review
+
+Queue the workflow normally.
+
+1. **Preflight** validates timing, references, media, and resume compatibility
+   before the large models load.
+2. The loop renders and checkpoints one scene.
+3. **Review Gate** opens with synchronized video and audio.
+4. Choose an action:
+
+| Action | Result |
+|---|---|
+| **Approve & continue** | Accept this take and render the next scene. |
+| **Retry scene / seed / length** | Render the scene again from the same accepted predecessor. |
+| **Reroll seed** | Give only this scene a new seed, then retry it. |
+| **Approve & stop** | Accept this scene, optionally assemble a partial video, and stop cleanly. |
+
+When `candidate_count` is greater than one, Review Gate displays saved takes in
+a carousel. The selected take becomes the exact continuation for the next
+scene; checked alternatives remain in checkpoint history.
+
+After the final approval, Loop End emits a manifest and the active Assemble
+node creates the final MP4.
+
+## 7. Find the result
+
+One run is stored under:
+
+```text
+ComfyUI/output/h3_chains/<run_name>/
+├── checkpoints/     saved continuation state and revision data
+├── segments/        reviewed scene media
+├── final/           assembled MP4 and optional audio/subtitle sidecars
+└── ...              manifests, previews, and recovery metadata
+```
+
+Exact subfolders can grow as review branches, project assets, or upscale
+profiles are added. Use **Run Manager** or **Checkpoint Manager** instead of
+manually changing active revision files.
+
+## Assemble later without rendering
+
+1. Open the same workflow.
+2. Set Plan's `run_name` to the saved run.
+3. Unmute the recovery **Load Manifest** and **Assemble** nodes.
+4. Queue only the recovery Assemble node.
+
+This reads the saved manifest and segments from disk. It does not execute the
+sampler body.
+
+## Common first-run problems
+
+| Symptom | What to check |
+|---|---|
+| Preflight says the run already contains incompatible work | Use a new `run_name`, or restore the original generation settings. |
+| Queue pauses after one scene | Review Gate is waiting for a decision. |
+| Opening image appears in every scene | Keep **Frame Gate** active; do not bypass it. |
+| No final MP4 appears | Approve the final scene and confirm the active Assemble node is enabled. |
+| Recovery nodes render unexpectedly | Mute the recovery Load Manifest and Assemble pair. |
+| Audio or preview tools fail | Install `ffmpeg`, or confirm ComfyUI's PyAV installation works. |
+| A source-audio profile fails preflight | Connect a Source Timeline containing enough audio for the plan. |
+
+For deeper diagnosis, use [Compatibility](COMPATIBILITY.md), [Audio and
+continuity](AUDIO_AND_CONTINUITY.md), or [Runs and recovery](RUNS_AND_RECOVERY.md).

ComfyUI-MiniMaxH3-Context-Loop/docs/MASKED_EDITING.md

@@ -0,0 +1,261 @@
+# Masked editing
+
+MiniMax H3 can edit a real source AV latent instead of treating the source as
+an ordinary reference. A nested denoise mask controls every target stream:
+
+```text
+0 = preserve the source latent
+1 = regenerate this row
+```
+
+This is the general form of the chain's `masked_av`, `tapered_av`,
+`feathered_av`, and `drift_control_av` continuation. The chain builds a
+temporal prefix mask automatically; the public masking nodes accept arbitrary
+static or tracked spatial masks.
+
+`masked_av` assigns `0` to the complete repeated picture prefix.
+Experimental `tapered_av` uses the same hard mask after replacing only the
+carried video prefix with a deterministic, disposable matched-variance noise
+taper; audio and the accepted predecessor remain unchanged.
+`feathered_av` keeps most of that picture prefix exact, then raises the mask
+gradually toward `1` over its final latent steps. When Audio Policy enables
+Generated continuity, the matching audio prefix participates too: with the
+recommended 39-frame context, 8 of 12 video steps and 42 of 65 audio steps are
+fully protected; the final 4 video and 23 audio prefix steps form the denoise
+ramp. With Generated continuity off, audio remains fully denoisable. Both modes
+trim all 39 repeated picture frames after decoding.
+
+Experimental `drift_control_av` keeps the accepted predecessor checkpoint
+clean. During sampling it applies the sampler's existing noise field to the
+oldest eight of a 12-step picture prefix at `next_sigma / current_sigma`, then
+tapers the last four steps `.75/.50/.25/.00` so the seam itself stays exact.
+The same live mask reaches H3's row-timestep calculation through Chain
+Context's MODEL output. Audio remains owned by Audio Policy. This mode is fixed
+to 39 context frames and initially validated at 20 sampling steps.
+
+Start with
+[`Masked Video Inpaint - MiniMax H3 0.6.json`](<../example_workflows/Masked Video Inpaint - MiniMax H3 0.6.json>).
+For picture-defined replacement appearance, use
+[`Ref2V Masked Video Inpaint - MiniMax H3 0.6.json`](<../example_workflows/Ref2V Masked Video Inpaint - MiniMax H3 0.6.json>).
+For temporal continuation and bridging, use the three
+[masked AV examples](../example_workflows/README.md#masked-av-extension-and-bridge).
+
+## Ablejones / MaskVidExperiments interoperability
+
+Ablejones/droz's
+[`droz_MiniMaxH3_LatentMaskInpainting_wReference_v3.1.json`](https://discord.com/channels/1076117621407223829/1539132102585356359/1539347237887549512)
+uses `MVEx Mask To Latent Space` in `auto + max + max` mode before stock
+`Set Latent Noise Mask`. At zero additional grow, that is the same H3 mask
+contract as **Apply Target Mask → H3 exact**: VAE-aware causal frame groups,
+conservative max reduction, and 2×2 latent-token unification. The corresponding
+[workflow thread](https://discord.com/channels/1076117621407223829/1539132102585356359/1539132102585356359)
+also documents the crop-based approach and its current border-flicker caveat.
+
+The maintained Ref2V demo maps the remaining wiring as follows:
+
+| Ablejones v3.1 | This pack |
+|---|---|
+| `MiniMaxH3ReferenceToVideo` picture input | The same core Ref2VA picture input |
+| Video/audio VAE encode + two `SetLatentNoiseMask` nodes + `LTXVConcatAVLatent` | **Loop Source AV Target** followed by **Apply Target Mask** on the authoritative stock joint target |
+| `MVEx Subject Crop/Uncrop` | Optional external speed/compositing layer; the maintained loop demo stays full-frame |
+| SAM3 tracked mask | Any static mask or complete tracked MASK batch through **Loop Mask Slice** |
+| `grow_spatial` / `grow_temporal` | Optional pixel-mask preparation before **Loop Mask Slice**; the bundled generous static mask uses zero additional grow |
+
+Do not feed the source movie into Ref2VA again merely to label it. The source
+movie is already the clean target latent and supplies protected pixels, motion,
+camera, and synchronized audio. A picture reference should supply only the
+replacement appearance. Crop/uncrop remains useful when a small subject would
+otherwise spend most compute on an unchanged full frame, but a multi-scene
+chain must slice crop boxes on the same scene windows before uncropping.
+
+## Nodes
+
+### Masking · Loop Source AV Target
+
+**MiniMax H3 Masking · Loop Source AV Target** is the preferred source-video
+path inside Chain Loop. Connect Current Shot `state`, Chain Context `latent`,
+both H3 VAEs, and the complete synchronized source frames/audio. The node uses
+`generation_start_frame` and the stock H3 joint target to select and encode the
+exact current interval.
+
+The stock target's video and audio lengths are authoritative. At fractional
+24-fps/40-Hz boundaries, exact picture-duration audio can encode one token
+shorter than the stock H3 audio target. This node adds only the encoder-grid
+lookahead needed to fill that target and trims back to its exact step count.
+Do not put `LTXVConcatAVLatent` or `LTXVSeparateAVLatent` in this path.
+
+### Masking · Loop Mask Slice
+
+**MiniMax H3 Masking · Loop Mask Slice** accepts either one static mask or a
+complete tracked MASK batch. A single frame is explicitly broadcast across the
+current scene. A multi-frame batch is treated as a source-timeline mask and
+sliced with the current shot's `generation_start_frame` and `raw_frames`.
+
+Set `source_fps` to the rate represented by the tracked mask batch. For a
+24-fps source/mask pair, the bundled two-scene workflow selects mask frames
+0..174 for scene 1 and 136..310 for scene 2. The repeated 136..174 interval is
+therefore identical to the source AV continuation overlap. Connect
+`scene_mask` to Grid Preview; its existing spatial snapping then operates only
+on the correct current interval. Apply Target Mask's exact mode validates that
+the returned tracked batch has the complete raw scene length; it never
+stretches a short tracked batch silently.
+
+### Masking · Trim Source AV
+
+**MiniMax H3 Masking · Trim Source AV** drops only trailing video frames until
+the source has a valid H3 `17k+5` length. Optional source audio is trimmed to
+the same duration at H3's fixed 24 fps. It never resizes frames, changes fps,
+or pads short audio.
+
+Use the returned `h3_length` for the core H3 conditioning node. Resize the
+returned frames once to the final H3 canvas, then feed that exact batch to the
+video VAE, mask preview, and any tracking path.
+
+### Masking · Grid Preview
+
+H3's video VAE reduces each spatial axis by 16 and the DiT groups the result
+into 2×2 latent patches. One independently masked H3 row therefore covers
+roughly **32×32 source pixels**.
+
+**MiniMax H3 Masking · Grid Preview** shows those cells and returns a snapped
+MASK suitable for Apply Target Mask. Its canvas must match the encoded source,
+be divisible by 32, and contain a valid one-frame or `17k+5` H3 run. Runtime
+exact mode also unions every source-frame group that feeds one causal video
+latent, then paints that effective selection back over the grouped frames.
+
+- `runtime exact (latent max)` reproduces the spatial reduction used by H3;
+- `any pixel coverage` selects a whole cell for any marked source pixel;
+- `50% pixel coverage` selects cells at least half covered;
+- `full pixel coverage` selects only completely covered cells;
+- `cell_adjust` grows or shrinks by complete cells.
+
+The `grid_preview` IMAGE contains only the selected `preview_frame` to avoid
+duplicating an entire video for display. The `snapped_mask` output retains the
+complete static or tracked mask batch.
+
+### Masking · Apply Target Mask
+
+**MiniMax H3 Masking · Apply Target Mask** expects the source media as the
+sampler's real joint video/audio target latent. In a loop, produce it with
+**Loop Source AV Target**, apply the mask, and connect `masked_target` to
+`SamplerCustomAdvanced.latent_image`.
+
+Do not also add the same source as `<Video>` merely to make masking work. A
+reference influences generation; it does not provide the clean latent values
+that the mask protects.
+
+The main mask may use either convention:
+
+- `white = generate` for conventional inpainting;
+- `white = preserve` when the supplied artwork describes protected content.
+
+The default **H3 exact (causal/token max)** conversion follows the video VAE's
+repeating `1,4,4,4,4` pixel-frame groups and max-reduces each group to its real
+latent step. It then max-reduces spatially and unifies every 2×2 latent block
+read by one H3 token. This preserves thin details and moving-mask coverage that
+trilinear interpolation can weaken or shift. One mask is broadcast; a tracked
+mask must contain exactly the pixel-frame span represented by the target. In a
+loop, connect Loop Mask Slice to supply it. **legacy trilinear** remains
+available for reproducing earlier workflows. Switching conversion modes changes
+generation, so also change the Plan generation fingerprint and regenerate the
+affected scene history. Batch size is currently one.
+
+This conversion is for inpainting, replacement, removal, outpainting, and
+other masked edits. It does not add a mask input to ordinary AV extension; the
+chain continues to create its own temporal AV-prefix mask automatically.
+
+## Audio modes
+
+| Mode | Behavior |
+|---|---|
+| `preserve source audio` | Protect the complete encoded source-audio latent. This is the default for visual edits. |
+| `generate all audio` | Regenerate the complete H3 audio stream. |
+| `follow video mask` | Generate audio during times where any video region is selected. |
+| `custom audio mask` | Reduce the optional MASK to a time envelope; white generates and black preserves. |
+
+Audio is not spatial, so a visual object mask has no unique audio equivalent.
+Use preserve mode unless the edit deliberately needs new sound.
+
+## Exact master-audio timelines
+
+**Masking · Master Audio + Video Prefix** is the asymmetric timeline-audio
+form of target masking. It takes the empty joint target produced by stock H3
+conditioning, VAE-encodes the exact master-audio interval beginning at
+`clip_start_seconds`, replaces the complete target audio stream, and assigns
+audio mask `0` for the full raw clip. The master may be music, dialogue,
+narration, or another finished soundtrack.
+
+The H3 target audio grid is authoritative when picture duration falls between
+40 Hz boundaries. The node may encode a few milliseconds of additional real
+timeline audio so a floor-style audio VAE fills every target step, then crops
+the latent to the target length. Its `clip_audio` output remains exactly the
+picture duration; it never invents or repeats a latent token.
+
+For live H3 chaining, connect the preceding sampler output to `source_latent`.
+The node copies its phase-aligned video-latent tail directly into the protected
+target prefix without decoding or re-encoding it. The source latent's audio is
+ignored: the selected `master_audio` interval remains authoritative.
+
+`source_frames` remains the legacy fallback for imported or decoded media. The
+node converts it to 24 fps, selects the final native H3 context run, VAE-encodes
+it into the target video prefix, and protects only those video rows. Connect
+either `source_latent` or `source_frames`, never both. Future video rows remain
+`1` and are generated normally. The returned `trim_frames` is authoritative
+for Loop Trim and visual overlap assembly.
+
+The master audio is target content, not a Ref2VA audio reference. Keep every
+`ref_audio_*` input disconnected, and mux the untouched full master audio onto
+the assembled picture for final delivery.
+
+## Composition with chain continuation
+
+If the target already contains a nested H3 noise mask, Apply Target Mask
+intersects the two masks. **Preservation wins.** This allows an arbitrary
+spatial edit to compose safely with the protected or feathered prefix produced
+by either AV mask mode:
+
+```text
+chain prefix mask × spatial edit mask = final generation mask
+```
+
+The same rule holds whether Apply Target Mask sits before or after Chain
+Context, because both nodes emit latent-sized nested AV masks.
+
+## Inpaint, outpaint, and clip bridging
+
+The bundled workflow implements video inpainting. The same mask contract also
+supports the other operations once their source target is prepared:
+
+- **Outpaint:** place the source on a larger H3 canvas, encode that canvas,
+  preserve the original rectangle, and generate the exposed border.
+- **Object removal/replacement:** provide a static or tracked object mask and
+  describe only the intended replacement while asking H3 to retain the rest.
+- **Temporal repair:** use a mask batch that is black on retained frames and
+  white during the interval to regenerate.
+- **Two-clip bridge:** **Masking · Two-Clip AV Bridge** encodes the end of clip
+  A and beginning of clip B into opposite ends of an empty joint H3 target,
+  protects both AV windows, and generates only the middle interval. Use exact
+  H3 endpoint runs; 39 frames is recommended because it maps to exactly 65
+  audio steps.
+
+This integration bundles the arbitrary mask/inpaint workflow and the two-ended
+AV bridge. Expanded-canvas outpaint preparation remains external to the pack;
+it can be added without changing the H3 mask/runtime layer.
+
+## Runtime compatibility
+
+The masking nodes prefer native ComfyUI support equivalent to PR #15375. On a
+supported post-PR-#15439 H3 baseline, they lazily install only the missing mask
+engine, payload extraction, token-aligned inpaint scaling, or legacy sampler
+bridge. The original pixel mask remains authoritative for final sampler
+blending; only H3's internal timestep labels are pooled to the video/audio
+token grids. No MODEL patch node is needed, and importing the pack does not
+modify stock H3 behavior.
+
+A partially updated native implementation is rejected rather than combined
+with the compatibility snapshot. Restart ComfyUI fully after updating core or
+an H3 optimization extension.
+
+Per-row mask support guarantees the sampling mechanics, not that H3 was trained
+equally strongly for every edit topology. Feathered source preparation and a
+short test render remain advisable for outpainting and complex tracked masks.

ComfyUI-MiniMaxH3-Context-Loop/docs/MIGRATING_TO_0_5.md

@@ -0,0 +1,103 @@
+# Migrating workflows to version 0.5
+
+Version 0.5 is backward compatible. Existing 0.4 node ids, positional outputs,
+widget order, manifests, and checkpoints remain supported. Migration is
+recommended for clearer graphs and model-free validation, but it is not
+required merely to open or resume an older workflow.
+
+## What changes
+
+Version 0.5 uses one **Chain Policy** connection for normal authoring. It keeps
+the audio and transition records independent inside the Plan/checkpoint
+contract, but removes the need to wire two policy nodes.
+
+| 0.4 audio mode | Final audio | Source reference | Generated continuity |
+|---|---|---|---|
+| `generated_audio` | generated | off | on |
+| `source_track` | source | on | off |
+| `source_plus_timeline` | source | on | on |
+
+| 0.4 continuation | 0.5 transition | Default context |
+|---|---|---:|
+| guide with zero context | Cut | 0 frames |
+| `guide` | Guide | 22 frames |
+| `masked_av` | Hard AV | 39 frames |
+| `audio_feathered_av` | Soft AV | 39 frames |
+| any other implementation/context pair | Legacy 0.4 Policy Adapter | preserved exactly |
+
+The compact presets derive generated-audio overlap from the same boundary: 0,
+22, or 39 frames. A custom audio overlap, Tone/Latent/Detail Guide, Detail AV,
+Drift-Control AV, old dual-stream Feathered AV, and other raw pairs migrate to
+the single **Legacy 0.4 Policy Adapter** node instead. Nothing is approximated.
+The semantic choice always describes the boundary entering a scene.
+
+## Automatic migration
+
+Back up a custom workflow, then run:
+
+```bash
+python tools/migrate_v05_workflows.py /path/to/workflow.json
+```
+
+Pass several paths to migrate them together. Use `--check` to report files that
+would change without writing them:
+
+```bash
+python tools/migrate_v05_workflows.py --check /path/to/workflow.json
+```
+
+With no paths, the tool checks or migrates the maintained active examples. It
+is idempotent: running it again does not add duplicate policy, preflight, or
+timeline nodes. Exact 0.4 settings become one Chain Policy when they fit the
+normal presets; other implementation/context pairs become one exact Legacy 0.4
+Policy Adapter.
+
+## Source-media rewiring
+
+The old source-track graph repeated one full decoded AUDIO value:
+
+```text
+Load Audio ─┬→ Loop Start
+            ├→ Current Shot
+            ├→ Tagged Audio Ref
+            └→ Assemble
+```
+
+The 0.5 graph registers media once:
+
+```text
+Load Video ─┐
+            ├→ Source Timeline ─┬→ Preflight / Plan Studio
+Load Audio ─┘                   └→ Loop Start → Current Shot
+                                                   └→ scene slice → Tagged Audio Ref
+
+Loop End manifest → Assemble
+```
+
+Path-backed media remains lazy. Current Shot requests only its active window,
+and manifests carry the descriptor to recovery and assembly. If the only audio
+input is a tensor, Loop Start materializes one normalized run-owned copy.
+
+Do not return a Tagged Audio fingerprint derived from Current Shot to Plan;
+that would create a graph cycle. Keep static picture/reference fingerprints on
+Plan. Structured scene dependencies record the exact source PCM window used by
+generation automatically.
+
+## Preflight and resume
+
+Normal workflows insert Chain Preflight before Loop Start. Studio workflows use
+the same backend through Plan Studio. It validates duration, source windows,
+references, compatibility, and resume eligibility without loading H3.
+
+Version 0.5 stores structured per-scene dependencies. A change to the next
+scene, its incoming transition, or assembly-only media does not invalidate an
+already accepted predecessor. Old checkpoints without structured records keep
+their generic hash fallback.
+
+## Compatibility guarantee
+
+The migration tool does not renumber the sampling body or change its node
+types. Loop Start's original optional socket order is preserved so
+numerical 0.4 workflow slots still deserialize correctly. Legacy full-AUDIO
+fan-out, direct media paths, Plan widgets, and archived examples remain
+accepted throughout the 0.5 release.

ComfyUI-MiniMaxH3-Context-Loop/docs/NODE_REFERENCE.md

@@ -0,0 +1,152 @@
+# Node guide
+
+This is a user-facing map of the nodes you normally see in a Context Loop
+workflow. It focuses on what to connect and what comes out; exact expert fields
+remain documented by the node tooltips and the linked specialist guides.
+
+## Read a node at a glance
+
+The tables use this direction:
+
+```text
+input socket or widget  ──>  NODE  ──>  output socket
+```
+
+- **Socket** means connect another node.
+- **Widget** means choose or type a value on the node.
+- Inputs marked optional can stay disconnected for the normal path.
+- Outputs described as status or summary are for inspection; they do not need
+  to be wired for generation.
+
+The flow overview in the [README](../README.md#how-the-graph-is-organized) shows
+where the core nodes sit.
+
+## How disabled nodes are shown
+
+Disabled nodes remain part of the saved workflow, so their sockets and purpose
+still matter. These docs keep their node-shaped representation and add an
+explicit state label:
+
+| Representation | ComfyUI mode | Meaning |
+|---|---:|---|
+| **Solid card — ACTIVE** | `0` | Executes when its output is requested. |
+| **Grey dashed card — MUTED** | `2` | Present, but never executes. No output is produced. |
+| **Dashed amber card — BYPASSED** | `4` | Skips its operation and forwards a compatible input. |
+
+This follows the useful behavior of disabled-pack schema previews: input
+sockets, widgets, defaults, and outputs remain visible even though the node is
+not live. It prevents a muted recovery branch from looking like missing or
+broken documentation.
+
+In the shipped generation examples, **Load Manifest → Assemble — recovery** is
+muted. Unmute that pair only to assemble saved scenes without rendering. In
+some deferred-upscale examples, an attention override is bypassed intentionally
+for compatibility.
+
+## Main loop
+
+| Node | Inputs you normally use | Outputs you normally use | What it does |
+|---|---|---|---|
+| **MiniMax H3 Generation Profile** | Widgets: Scene continuity, Audio profile. Optional: `lip_sync_options`. | `chain_policy`, `status` | Turns two user choices into the complete policy expected by Plan. |
+| **MiniMax H3 Plan (Modern)** | Required `chain_policy`; organized Project, Canvas, Generation defaults, and Delivery settings; optional `project_assets`. | `plan`, `summary`, scene count, width, height, blend frames | Recommended for new graphs. Keeps the familiar scene-column editor, removes all legacy fallback controls, and compiles the same Plan contract as the original node. |
+| **MiniMax H3 Context Loop Plan** | Widgets: Scene Plan, `run_name`, size, duration, seed. Optional sockets: `chain_policy`, `project_assets`. | `plan`, `summary`, scene count, width, height, blend frames | Original compatibility-preserving Plan. Existing workflows keep it unchanged. Connect Generation Profile, then use **Upgrade to Modern Plan…** from its context menu when desired. |
+| **MiniMax H3 Chain Preflight** | `plan` | checked `plan`, `preflight`, `ready`, `status`, report JSON | Validates the full plan before model-heavy nodes execute. Wire its Plan output to Loop Start. |
+| **MiniMax H3 Context Loop Start** | `plan`. Optional: scene range, source timeline, source audio, external context. | `flow`, `state`, `status` | Starts scene 1, a bounded range, or a compatible resume. |
+| **MiniMax H3 Context Loop Current Shot** | `state`. Optional source-audio fallback. | state, scene index/count, prompt, seed, raw length, steps, size, source-audio slice, blend frames | Exposes the current scene as ordinary ComfyUI values. |
+| **MiniMax H3 Current Tagged Ref2VA Scene** | `state`, CLIP, video VAE, audio VAE, tagged references. Optional: Tagged Scene Options. | state, positive conditioning, latent, typed scene data | Compact prompt-driven Ref2VA route. It replaces the visible Current Shot + Tagged Ref2VA pair in new reference graphs. |
+| **MiniMax H3 Context Loop Context** | state, conditioning, video VAE, latent. Optional: audio VAE, model, drift sigmas, anchors, lip-sync voice. | conditioning, trim frames, continuation flag, latent, model | Adds the selected visual/audio continuation. Scene 1 is effectively a pass-through. |
+| **MiniMax H3 Context Loop Trim** | decoded images, trim count. Optional: audio, FPS, overlap controls, state. | delivered images/audio, overlap-ready images, overlap count | Removes the repeated head context and retains any frames needed for assembly blending. |
+| **MiniMax H3 Context Loop Segment + Checkpoint** | state, delivered images, sampled latent. Optional: audio, overlap-ready images, denoised latent. | `segment`, `status` | Saves the scene movie, latent continuation, dependency record, and immutable revision. |
+| **MiniMax H3 Context Loop Review Gate** | state, segment. Widgets: enabled, timeout, candidate count, memory cleanup, partial assembly. | reviewed `segment`, `status` | Pauses for approve, retry, reroll, candidate selection, or clean stop. |
+| **MiniMax H3 Context Loop End** | flow, state, images, sampled latent, reviewed segment. | manifest, manifest JSON, final context frames, final context latent | Recurses into the next scene or finishes the selected range. |
+| **MiniMax H3 Context Loop Assemble** | manifest. Widgets: audio source, filename, bitrate. Optional: output copy, blend/tone controls, recovery media. | `video_path` | Verifies selected segments, joins them, and muxes the chosen audio into the final MP4. |
+
+The H3 model loader, scheduler, sampler, and VAE decoders are ordinary ComfyUI
+or MiniMax H3 nodes. Context Loop provides the plan, continuity, checkpoint, and
+recovery layer around them.
+
+## Authoring and policy nodes
+
+| Node | In → out | Use it when… |
+|---|---|---|
+| **Scene Prompt Editor** | Plan → Plan | You want the stable per-scene prompt editor and prompt history. |
+| **Rich Scene Prompt Editor (Experimental)** | Plan → Plan | You want the experimental rich editor and optional optimizer UI. |
+| **Plan Studio (Experimental)** | Plan and optional Source Timeline → Plan | You want editorial placement, gaps, chapter views, previews, timeline controls, or picture-only alternate final-cut takes. |
+| **Project Asset Carousel** | Project name/catalog; optional existing tagged refs or upscale model → project assets, references, Source Timeline | You want one project library instead of many loader/tag nodes. See the [Carousel guide](PROJECT_ASSETS.md). |
+| **Scene LoRA Scheduler** | Model plus lazily revealed LoRA inputs; state → scene model | Different scenes use different connected LoRA routes. |
+| **Lip-Sync Options** | Timing/denoise widgets; optional vocal stem → lip-sync options and voice | The Generation Profile uses **Lip-sync to source audio**. |
+| **Advanced Policy Override** | chain policy + advanced transition → chain policy | You need Tone, Latent, Detail, Drift-Control, or Color-Stable Drift behavior. |
+| **Manual Chain Policy (Legacy)** | Low-level transition/audio widgets → chain policy | An existing workflow already uses it. Prefer Generation Profile for new graphs. |
+| **Legacy 0.4 Policy Adapter** | Old 0.4 fields; optional current policy → chain policy | You are rebuilding or migrating an old control surface. |
+
+See [Scene authoring](SCENE_AUTHORING.md), [Audio and
+continuity](AUDIO_AND_CONTINUITY.md), and the [complete Plan format](../H3_CHAIN_FORMAT_GUIDE.md).
+
+## References and source media
+
+| Node group | Main inputs → outputs | Use it for |
+|---|---|---|
+| **Tagged Picture / Video / Motion / Audio Ref** | Media + tag/options → tagged references | Build a prompt-selected `@tag` reference collection. |
+| **Tagged Ref2VA** | Tagged refs + CLIP/VAEs + current scene values → conditioning, latent, fingerprint | Compile only the references used by the current prompt. |
+| **Tagged Scene Options** | Reference/backend widgets → options | Keep non-default reference settings off the compact Current Tagged Scene node. |
+| **Scene Data Extract** | typed scene data + selected field → typed value | Recover a secondary Current Tagged Scene value such as source-audio slice or RefMod sources. |
+| **Scheduled Picture / Video / Audio Ref** | Media + scene selector/options → schedule | Assign media by scene number or range instead of prompt tags. |
+| **Scheduled Ref2VA** | Schedule + current scene + CLIP/VAEs → conditioning, latent, fingerprint | Compile the active scheduled references for one scene. |
+| **Source Timeline** | Source media/path and timing options → Source Timeline | Register the reusable video/audio timeline once. |
+| **Audio Tracks** | Optional full mix, vocals, instrumental AUDIO → Source Timeline | Use vocals for source-locked lip-sync while preserving the full mix for delivery; mix stems only when a full mix is absent. See [grouped audio](AUDIO_AND_CONTINUITY.md#grouped-songs-full-mix-vocals-and-instrumental). |
+| **Reference Video Prep** | Video + fit/timing controls → prepared reference | Prepare motion/reference video for H3 timing. |
+| **Frame Gate** | Opening image; optional last frame + scene index → first/last-frame outputs | Apply the opening image only to scene 1. Do not bypass it in I2V workflows. |
+| **Frame Index Switch** | Scene index + image inputs → selected image | Alternate last-frame targets across scenes. |
+| **Existing Video Context** | Plan plus source video or frames; optional audio → external context | Prepend an existing clip and continue from its tail. |
+
+Lazy motion loaders, source-timeline previews, semantic anchors, and Patch
+Priority are advanced reference tools. Their behavior is
+covered by [Scheduled references](SCHEDULED_REFERENCES.md) and [Advanced
+workflows](ADVANCED_WORKFLOWS.md).
+
+## Runs, recovery, and output
+
+| Node | Main inputs → outputs | Use it for |
+|---|---|---|
+| **Run Manager** | Plan, archive controls, optional loader assets/Source Timeline/tagged refs → Plan, Source Timeline | Browse runs, restore a saved Plan and loader bindings, and archive recovery assets. |
+| **Checkpoint Manager** | Saved UI selection; optional Plan → selected manifest | Pin a workflow-local lineage or choose **Selected chapter only** for chapter export/upscaling. Chapter output preserves original scene numbers and timing, and permits different resolutions in earlier chapters. Local output leaves the project and connected Plan unchanged. |
+| **Load Manifest** | Plan; optional source media/context → manifest, manifest JSON, status | Verify and load saved segments without executing the generation loop. Usually muted in generation examples. |
+| **Chapter Delivery** | Manifest, enabled, chapter number → delivery manifest, snapshot path | Seal a chosen chapter's generated scenes for independent export. `0` selects the chapter containing the last generated scene; a positive number selects that chapter explicitly. |
+| **Chapter Recovery Load** | Run name, chapter number, optional snapshot ID → chapter manifest | Recover a sealed chapter's exact saved lineage and editorial state without loading or extending the rest of the run. |
+| **Export PNG Sequence + Audio** | Manifest + optional VAEs, or file-backed VIDEO + upscale state; output folder, 8/16-bit PNGs, workers, verification, reuse → directory, PNG count, status, WAV path, VIDEO | Legacy latent PNG/WAV export remains available. VIDEO mode decodes and publishes one scene at a time with bounded memory, then passes the original VIDEO downstream. Verified unchanged frames can be reused; changed contents are never overwritten. |
+| **Full-Chain Latent Video Adapter** | Generated manifest + video VAE → cached continuous video | Build a low-RAM, disk-backed whole-run input for SeedVR2. |
+| **Assemble** | Manifest + audio/output choices → MP4 path | Join a complete or partial source/upscale manifest. |
+
+See [Runs and recovery](RUNS_AND_RECOVERY.md) for review branches, resume rules,
+folder layout, deferred upscaling, and assembly options.
+
+## Masking nodes
+
+| Node | Main inputs → outputs | Use it for |
+|---|---|---|
+| **Masking · Loop Source AV Target** | State + source video/audio + H3 target → scene target latent | Slice the exact source interval for the current loop scene. |
+| **Masking · Loop Mask Slice** | State + mask batch → current scene masks | Keep a tracked mask aligned with recursive scene timing. |
+| **Masking · Trim Source AV** | Source frames; optional audio → valid-length frames/audio, length, status | Trim the tail to H3's largest valid `17k+5` frame count without padding or resizing. |
+| **Masking · Grid Preview** | Mask + H3 grid controls → snapped mask, preview, status | Inspect the actual 32×32 H3 cells that will change. |
+| **Masking · Apply Target Mask** | H3 target latent + mask → masked target | Combine the spatial mask with any existing AV protection mask. |
+| **Masking · Master Audio + Video Prefix** | H3 target + full source track + timing/prefix options → masked target, audio slice | Protect exact source audio while controlling the incoming video prefix. |
+| **Masking · Two-Clip AV Bridge** | Start/end clips + H3 target → bridge target | Protect both ends and generate only the middle gap. |
+
+Use [Masked editing](MASKED_EDITING.md) for the required wiring and mask/audio
+semantics.
+
+## Upscale and research nodes
+
+Deferred-upscale workflows include a checkpoint adapter, current-scene node,
+reference-conditioning recovery, pass-2 AV preparation, segment save, and an
+upscale Loop End. The de-rope example adds Guard, Freeze Mask, Continuity, and
+Recovered AV nodes. These nodes are designed to be used as a supplied group,
+not assembled one at a time from this short reference.
+
+Start from a [deferred-upscale example](../example_workflows/README.md#deferred-upscale)
+and use [Runs and recovery](RUNS_AND_RECOVERY.md#whole-chain-seedvr2-finishing)
+for the detailed contracts.
+
+Nodes whose names end in **Experimental**, **Research**, **Internal**, or
+**Legacy** are not the normal starting point. Keep their supplied wiring unless
+you are following the matching specialist guide.

ComfyUI-MiniMaxH3-Context-Loop/docs/PROJECT_ASSETS.md

@@ -0,0 +1,137 @@
+# Project Asset Carousel
+
+Project Asset Carousel keeps a run's pictures, video, audio, reference tags,
+and Source track in one project library. Use it when separate loader and tag
+nodes are making the workflow hard to manage.
+
+## Connect it
+
+```text
+Project Asset Carousel.project_assets  ──>  Plan.project_assets
+Project Asset Carousel.references      ──>  Tagged Ref2VA.references
+```
+
+If the project contains a **Source track**, Plan stores its recoverable Source
+Timeline automatically. Loop Start, Plan Studio, recovery, and Assemble can
+read it from the Plan; another Source Timeline wire is normally unnecessary.
+
+## Inputs and outputs
+
+| Side | Field | Use |
+|---|---|---|
+| Input widget | `run_name` | Select or create the project. It synchronizes the connected Plan's run name. |
+| Input widget | Catalog and operation state | Managed by the Carousel interface; do not hand-edit for normal use. |
+| Optional input | `tagged_references` | Import the existing reference carrier as Unassigned cards. |
+| Optional input | `upscale_model` | Enable nondestructive model upscaling in the image editor. |
+| Output | `project_assets` | Connect to Plan. Carries the project catalog, fingerprints, and Source-track recovery data. |
+| Output | `references` | Connect to Tagged Ref2VA or the compact Current Tagged Ref2VA Scene. |
+| Output | `reference_fingerprint` | Inspect the active reference identity; Plan includes it automatically through `project_assets`. |
+| Output | `source_timeline` | Optional direct Source Timeline access for specialized graphs. |
+| Output | `status` | Compact counts and the current catalog revision. |
+
+## Add an asset
+
+Use any of these routes from the Carousel:
+
+- Drop one or several image, video, or audio files onto the node.
+- **Upload** a new file.
+- **Import** a file already in `ComfyUI/input/`.
+- Choose **Other Run** to copy an asset from another live Carousel project.
+- Import from an H3 run recovery backup.
+
+An imported asset receives its own project-owned media copy. Copying from
+another run preserves its role, tag, reference options, and audio lyrics; the
+source project is not changed.
+
+## Assign a role
+
+| Role | What it does |
+|---|---|
+| Native tagged reference | Makes the asset available to prompt-selected `@tag` references. |
+| Semantic picture | Makes a picture available as a `#tag` presentation anchor. |
+| Source track | Supplies the project's recoverable source video/audio timeline. |
+| Unassigned | Keeps the card visible without using an H3 reference slot or changing the generation fingerprint. |
+
+When you connect an existing `tagged_references` line, the Carousel creates
+Unassigned cards for its tags and media roles. Bind each card to an input file,
+upload, another project, or a backup before expecting it to take part in
+generation. Move other server media into the configured ComfyUI input folder
+first; browser requests cannot import arbitrary filesystem paths.
+
+Only references used by the current scene are decoded during sampling.
+
+## Group a song and its stems
+
+On an audio **Source track** card, **Synchronized audio tracks** assigns the
+project's full mix, isolated vocals and optional instrumental. Import the stems
+as audio assets first; they need not be available to prompts. All tracks must
+start together and retain the complete song duration, including silent gaps.
+Only one Source track card needs to be enabled.
+
+The full mix supplies delivery; vocals supply source-locked lip-sync. If no
+full mix is assigned, the stems are mixed automatically without doubling an
+existing mix. Use each scene's **Lip-sync** selector to turn guidance on/off
+without changing the final soundtrack. **Reset to single track** restores the
+old behavior. See [audio routing details](AUDIO_AND_CONTINUITY.md#grouped-songs-full-mix-vocals-and-instrumental).
+
+Copying a grouped Source track from **Other Run** also copies its assigned
+tracks and remaps their IDs. Deleting a referenced stem is blocked until you
+detach it from the group.
+
+## Edit a picture
+
+**Edit / upscale** creates a new PNG variant; it never overwrites the source.
+The editor supports:
+
+- draggable crop and placement;
+- exact width and height or megapixel targets;
+- locked aspect ratio;
+- Lanczos, bicubic, bilinear, or nearest resampling;
+- output snapping to Off, 8, 16, 32, or 64;
+- **Use full image** and **Reset all**;
+- model upscaling when `upscale_model` is connected.
+
+Model upscale queues only the Carousel and its lazy model-loader dependency. It
+does not launch the downstream H3 generation loop.
+
+Every variant records its parent and transform so the original remains
+available.
+
+## Organize the library
+
+- Duplicate a card without copying its media bytes again.
+- Create folders and drag cards onto them.
+- Click a folder card to expand or collapse its assets inline.
+- Duplicate the complete project under a new run name when you want a separate
+  production with the same library.
+
+Folder names, order, membership, and expansion state are presentation only;
+they do not change prompts or generation fingerprints.
+
+Selecting an audio asset opens a lyrics workspace. Lyrics are saved with the
+catalog and recovery backup, but remain notes: they are not added to prompts or
+generation fingerprints.
+
+## Storage and recovery
+
+Project-owned input media is stored under:
+
+```text
+ComfyUI/input/h3_projects/<run_name>/
+```
+
+Recovery copies and catalog metadata are stored with the run under:
+
+```text
+ComfyUI/output/h3_chains/<run_name>/project_assets/
+```
+
+The workflow JSON keeps compact catalog metadata rather than embedding media.
+The run backup lets the project be restored if an input binding is moved or the
+workflow is opened on another system.
+
+Deleting a generated run through Checkpoint Manager does not delete the
+original project-owned assets under `ComfyUI/input/h3_projects/`.
+
+For prompt tag behavior, see [Scheduled references](SCHEDULED_REFERENCES.md).
+For run backups and recovery, see [Runs and recovery](RUNS_AND_RECOVERY.md).

ComfyUI-MiniMaxH3-Context-Loop/docs/README.md

@@ -0,0 +1,60 @@
+# Documentation
+
+Start with the page that matches what you are doing now. You do not need to
+read the implementation references to run a normal workflow.
+
+## New here
+
+1. [Getting started](GETTING_STARTED.md) — install, open an example, render,
+   review, and find the result.
+2. [Workflow catalog](../example_workflows/README.md) — choose the smallest
+   example for your task.
+3. [Node guide](NODE_REFERENCE.md) — understand the visible nodes, sockets, and
+   disabled-node notation.
+4. [0.5 → 0.6 major improvements](assets/minimax-h3-context-loop-0.5-to-0.6-major-improvements.png)
+   — a Discord-ready visual overview of the current release.
+
+## Guides by task
+
+| I need to… | Read this |
+|---|---|
+| Write or reorder scenes | [Scene authoring](SCENE_AUTHORING.md) |
+| Manage pictures, video, audio, and Source-track assets | [Project Asset Carousel](PROJECT_ASSETS.md) |
+| Choose continuity or audio behavior | [Audio and continuity](AUDIO_AND_CONTINUITY.md) |
+| Use image, video, motion, or audio references | [Scheduled references](SCHEDULED_REFERENCES.md) |
+| Review takes, resume, recover, or assemble | [Runs and recovery](RUNS_AND_RECOVERY.md) |
+| Inpaint, outpaint, extend, or bridge video | [Masked editing](MASKED_EDITING.md) |
+| Extend an existing video or use special context | [Advanced workflows](ADVANCED_WORKFLOWS.md) |
+| Fix a missing-node or runtime compatibility problem | [Compatibility](COMPATIBILITY.md) |
+| Move an older workflow to the current contract | [Migrating to 0.5](MIGRATING_TO_0_5.md) |
+
+## Reference material
+
+These pages are useful when you need exact behavior rather than a first-run
+explanation.
+
+| Reference | Contents |
+|---|---|
+| [Complete Plan format](../H3_CHAIN_FORMAT_GUIDE.md) | Every Plan and per-scene field, exact timing, prompt syntax, and JSON forms |
+| [Version 0.5 architecture](V0_5_ARCHITECTURE.md) | Frozen Source Timeline, policy, dependency, migration, and preflight contracts |
+| [Reference Video Fade](REFERENCE_VIDEO_FADE.md) | Experimental denoising-time control of Ref2VA video influence |
+| [Feature traceability](FEATURE_TRACEABILITY.md) | Origins, upstream links, implementation files, and commit evidence |
+
+## Project information
+
+- [Changelog](../CHANGELOG.md)
+- [Third-party credits and licenses](../THIRD_PARTY_NOTICES.md)
+- [Contributing](../CONTRIBUTING.md)
+- [Example asset licenses](../example_workflows/assets/README.md)
+- [Dormant Prompt Assistant design study](../AGENT_PROMPT_ASSISTANT_STUDY.md)
+
+### Terms used in these docs
+
+- **Scene** — one planned H3 generation.
+- **Run** — one named production and its saved checkpoint history.
+- **Segment** — the delivered media saved for one scene.
+- **Manifest** — the verified list of selected segments used for recovery or
+  final assembly.
+- **Muted node** — present in the workflow but not executed.
+- **Bypassed node** — present, but forwarding a compatible input instead of
+  applying its normal operation.

ComfyUI-MiniMaxH3-Context-Loop/docs/REFERENCE_VIDEO_FADE.md

@@ -0,0 +1,114 @@
+# Reference Video Fade (experimental)
+
+## Why it exists
+
+MiniMax H3 does not reduce a Ref2VA video to poses. Core VAE-encodes the
+complete 24 fps reference and packs its latent rows into the same transformer
+sequence as text, reference pictures/audio, and the target AV streams. Those
+video rows remain available at every DiT block and every sampling evaluation.
+
+That strong path explains why a simple character-swap prompt can reproduce the
+reference camera, action, and timing so closely. It also means source color,
+background, framing, and texture can influence the target even though source
+pixels are not directly composited into the output.
+
+Dropping every second or third input frame is not a safe strength control. It
+changes reference speed, duration, and temporal coordinates. Repeating frames
+keeps duration but introduces stepped motion. Reference Video Fade therefore
+keeps the complete video and schedules its transformer contribution instead.
+
+## What the node does
+
+**MiniMax H3 Reference Video Fade (Experimental)** is an opt-in MODEL patch.
+During early denoising, native reference-video rows remain at full value
+strength. After `fade_start`, their value contribution follows a half-cosine
+curve toward `end_strength`:
+
+```text
+strength = 1                                      progress <= fade_start
+u = (progress - fade_start) / (1 - fade_start)
+strength = end + (1-end) × 0.5 × (1 + cos(pi×u)) progress > fade_start
+```
+
+`progress` is measured against the complete sigma schedule from 0 at the first
+sampling level to 1 at the end. The node modifies only H3 attention V slices
+belonging to native `video` and `video_audio` reference blocks. H3's V tensor
+is already fresh scratch memory, so the slices are scaled in place without a
+sequence-sized mask, a duplicate model, or a second attention pass.
+
+The following remain unchanged:
+
+- native still-picture references;
+- Qwen text and visual-presentation tokens;
+- native reference audio;
+- continuation guides or AV-prefix masks;
+- target video and target audio rows.
+
+The reference video is still completely encoded and supplied to H3. This is a
+smooth reduction of its attention value contribution, not a hard removal. Its
+Q/K rows and Qwen presentation can still carry weaker semantic influence.
+
+## Relationship to continuation color control
+
+Reference Video Fade and **Color-Stable Drift AV** act on different inputs and
+can be used together:
+
+- Reference Video Fade reduces late denoising influence from an external
+  native Ref2VA motion video. It is the control to test when source framing,
+  background, or color keeps leaking into the generated scene.
+- Color-Stable Drift AV corrects the disposable previous-scene prefix used for
+  chain continuation. It does not alter the external motion reference, source
+  audio, or saved scene latent.
+
+Use Reference Video Fade alone to diagnose motion-reference leakage. Add
+Color-Stable Drift AV only when chained scenes also develop their own
+scene-to-scene color drift. Neither feature modifies the final assembled video.
+
+## Presets
+
+| Preset | Full reference through | End strength |
+|---|---:|---:|
+| `full` | 100% | 100% (true bypass) |
+| `balanced` | 67% | 20% |
+| `freer` | 50% | 15% |
+| `early_only` | 50% | 0% |
+| `custom` | `custom_fade_start` | `custom_end_strength` |
+
+Start with `balanced`. Use `freer` when the reference reproduces source color,
+background, or camera too literally. `early_only` is an aggressive diagnostic,
+not a recommended default.
+
+## Wiring
+
+For one sampler/model:
+
+```text
+H3 MODEL → other backend/model patches → Reference Video Fade → sampler
+```
+
+In a Context Loop Drift-Control graph, the faded MODEL may feed Chain Context's
+MODEL input; use Chain Context's MODEL output for sampling.
+
+For split-sigma sampling, connect the original **unsplit** schedule to
+`full_sigmas`. If the split switches models, put one Reference Video Fade node
+on each model branch and connect the same `full_sigmas` to every copy. This
+prevents the second half from restarting the fade at progress zero.
+
+Place the node after an attention-backend selector when possible. It chains an
+already installed optimized-attention override, including SolAttn or Comfy
+Kitchen, instead of replacing it.
+
+## Scope and limitations
+
+- All native `video` and `video_audio` reference blocks are faded. Core does
+  not preserve Tagged-reference role names in the packed payload, so a graph
+  with several native reference videos fades all of them. Still pictures are
+  never selected.
+- This is value gating, not an exact target-query-to-reference-key attention
+  mask. It is deliberately the low-memory implementation suitable for H3's
+  very long packed sequence.
+- It does not fade the 2 fps Qwen presentation derived from the reference
+  video. Prompts can therefore retain semantic awareness after the native
+  latent-video contribution has weakened.
+- Results are model-, sampler-, schedule-, and prompt-dependent. Treat the
+  presets as experimental comparisons and keep the rest of the graph fixed.

ComfyUI-MiniMaxH3-Context-Loop/docs/RUNS_AND_RECOVERY.md

@@ -0,0 +1,1077 @@
+# Runs, review, and recovery
+
+## Stable 0.6.2 recovery update
+
+Update the Context Loop pack and restart ComfyUI to load the upscale/cache fixes.
+Existing workflows and legacy reference bundles remain supported; conversion is
+optional. The PNG exporter is still **MiniMax H3 Context Loop Export PNG Sequence
++ Audio**, with optional file-backed VIDEO/state inputs and an appended VIDEO
+passthrough output. No replacement of the old latent-export workflow is required.
+
+New generation and alternate takes save immutable recovery documents under
+`h3_chains/<run>/recovery_archives/<revision>/`. The active Run also retains
+`plan.json`, `workflow.json`, and `api_prompt.json` for older recovery tools.
+Historical checkpoint output uses its own snapshot, not a later edited Plan.
+Older root-only archives remain readable but cannot retroactively supply unknown
+reference timing/settings. Rebuilding disposable reference latents still requires
+the original saved reference media and identities; missing or altered originals
+produce an actionable error instead of silently changing the render.
+
+## Review Gate
+
+Place **Review Gate** between Segment + Checkpoint and Loop End. Each scene is
+persisted before the gate waits, then the gate offers:
+
+- **Approve & continue**
+- **Generate next candidate** when a multi-take batch is not complete
+- **Retry scene / seed / length**
+- **Reroll seed**
+- **Approve & stop**, optionally assembling a partial video
+
+Set Review Gate's optional **candidate_count** above 1 to collect several
+different-seed takes. The gate pauses after every saved candidate instead of
+blindly generating the full batch. Use **Generate next candidate** to continue,
+or accept the current scene early and interrupt the remaining batch. The
+carousel previews every completed take with synchronized sound; arrow keys and
+the visible dots move between them. Mark one or more takes to keep, then choose
+the take that becomes the active continuation. Its saved video frames and AV
+tensors—not the last generated take—become the context for the following scene.
+The active take and checked alternatives remain in checkpoint history; unkept
+alternatives are deleted only after the active checkpoint is promoted safely.
+The default value of 1 keeps the normal one-take review behavior. The widget can
+be converted to an input and driven by a regular INT node; the safety limit is
+20 candidates per scene.
+
+Notification sound, automatic timeout, and model unloading while waiting are
+optional. Drag the bar below the player to resize it; double-click to restore
+the default height.
+
+When a Scene Prompt Editor or Rich Scene Prompt Editor is bound to the same
+Plan, Review Gate selects the scene under review there automatically. Editor
+changes are used by **Retry prompt / seed** or **Reroll seed** through the live
+Plan prompt. In 0.5, Review Gate's own prompt field is disabled by default.
+Restore it under **Settings → MiniMax H3 Context Loop → Interface → Review Gate
+→ Enable prompt editing inside Review Gate**. When enabled, text explicitly
+typed in that field wins for the submitted retry and is synchronized back to
+the Plan and connected editor after the server accepts it.
+
+During sampling, the optional floating **Cancel & reroll scene N** control
+targets only the active H3 prompt. It waits for confirmed interruption, writes a
+new explicit scene seed, moves Loop Start to that scene, preserves a bounded
+range end, and queues normally. Once saving or review begins, Review Gate owns
+the retry instead.
+
+Disable the floating control under **Settings → MiniMax H3 Context Loop →
+Interface → Cancel & reroll** without affecting Review Gate.
+
+## Between-scene memory cleanup
+
+Loop End can apply a runtime-only `between_scene_cleanup` policy after the
+current scene and checkpoint are durable, immediately before it starts the next
+scene or retry:
+
+- `off` keeps ComfyUI's normal caches.
+- `unload_models` unloads model weights and empties the device allocator.
+- `fresh_scene` first asks ComfyUI's active RAM-pressure cache to evict reusable
+  execution outputs and runs Python garbage collection, then releases remaining
+  pinned model pages, unloads models, and empties the device allocator. Use it
+  for chains that switch large models between scenes; the next scene will reload
+  anything that was evicted.
+
+The policy does not enter Plan or resume hashes. It deliberately preserves the
+small recursive carry and dynamic graph result because ComfyUI has no supported
+way to reset the entire executor while that graph is still resolving. On cache
+types other than RAM pressure, `fresh_scene` still unloads models and clears
+allocators, but no executor-output eviction callback is available.
+
+## Resume
+
+For a fresh run:
+
+```text
+run_name: choose a new name
+start_clip: 1
+scene_range: blank
+```
+
+To resume scene N, keep the original `run_name` and dependency settings, then
+set `start_clip: N`. The loop loads checkpoint N−1 and validates all completed
+predecessors that the selected scene actually consumes. Editing scene N or
+later is safe; changing an earlier prompt,
+seed, timing, source waveform, Plan compatibility setting, or
+`generation_fingerprint` invalidates the dependent resume.
+
+A visually new scene can still consume the immediately previous generated
+audio when its video context is `0` but its audio context is positive. That
+audio-only edge validates the predecessor's prompt/model/source identity and
+saved artifacts, but ignores its unrelated incoming visual-boundary recipe.
+Set both scene video context and audio context to `0` (or select Visual Cut)
+for a completely independent scene.
+
+Loop Start's `verify_resume_history` switch is enabled by default. Disable it
+only when you intentionally want scene N to consume the existing saved scene
+N−1 despite a changed Plan. The override skips Plan/history matching; it does
+not skip missing-file checks, SHA-256 artifact validation, checkpoint tensor
+validation, or metadata's own recorded-history consistency. Consequently, any
+new settings that describe the saved predecessor are not retroactively present
+in its pixels or AV latent.
+
+Plan-wide continuation mode and context length are the exceptions: they choose
+how the next scene consumes its saved predecessor. Changing either does not
+alter completed frames or their saved AV latent, so it does not invalidate the
+prefix. If the checkpoint's cached decoded tail is shorter than the newly
+requested context, the loop re-decodes its complete saved video latent and
+extracts the longer tail without regenerating the scene. Explicit per-scene
+continuation and context overrides remain part of that scene's history.
+
+Review Gate's checkpoint browser can set up this resume and preview the joined
+partial through the selected predecessor.
+
+**Manifest Load** also supports interrupted runs. It discovers the longest
+contiguous active checkpoint prefix beginning at scene 1, verifies every scene
+and artifact through that point, and emits a partial manifest when later scenes
+have not been saved. Connect that output directly to **Assemble** to recover the
+finished prefix without sampling again. A missing scene ends the prefix; an
+orphaned later checkpoint is never joined across the gap. When every planned
+scene is present, the same node emits the normal completed manifest.
+
+### Restore an earlier scene revision
+
+**Refresh** in Review Gate discovers the active checkpoint and every immutable
+revision retained for that scene. Choose the scene to resume, then select the
+desired version of each predecessor under **Checkpoint history**. Clicking
+**Restore & load** validates the selected MP4, safetensors checkpoint, hashes,
+shared prompt, and compatibility contract before atomically promoting the
+selected prefix. The corresponding prompts, seeds, lengths, steps, and scene
+identifiers are restored into the connected Plan, and Loop Start is armed for
+the next scene.
+
+The active versions are selected by default. Restoring an earlier version does
+not delete the current one, so another revision can be promoted later. Exact
+continuation requires the revision's checkpoint metadata and safetensors file;
+an MP4 copied from `segments/` or `reviews/` alone cannot recreate the saved AV
+latent. When only video survives, use Existing Video Context as a re-encoded
+continuation instead.
+
+Retrying, rerolling, and candidate collection intentionally retain earlier
+files as immutable revisions; they are recovery points rather than abandoned
+temporary files. Inactive leaf revisions can be deleted from the same panel or
+the dedicated Checkpoint Manager to reclaim space.
+Review Gate now retrieves a fresh server-side deletion preview before asking
+for confirmation. Active revisions and revisions with dependent later scenes
+cannot be deleted. Cleanup is limited to that revision's segment, safetensors
+checkpoint, prompt/audio/blend sidecars, unshared preview, and versioned
+metadata; Plan archives, assets, prompt history, assembled exports, and other
+revisions are never included.
+
+## Checkpoint Manager
+
+Connect the active Plan to **MiniMax H3 Checkpoint Manager** when you want its
+run preselected or want **Load selected branch** to restore saved Plan values.
+The node outputs only `selected_manifest`; it is not a Plan pass-through and is
+normally kept beside the generation route. Its run selector can inspect any
+other folder under `output/h3_chains`.
+
+Select a **branch heading** to choose the whole generated branch for output.
+Clicking an individual clip only previews it; it does not shorten the output
+or switch its branch. Use the downstream upscale/export range controls to
+choose which scenes to process.
+
+For an experiment, click **Use branch locally**. This saves the entire browsed
+branch (the row containing the previewed clip), not just its prefix through
+that clip. It pins the exact lineage on `selected_manifest` in this workflow
+only, including the earlier chapters included in that selection. Browsing
+other takes, refreshing, reopening the workflow, or activating another branch
+in a different tab cannot move this pin. Saved files are still verified on
+execution: a missing or corrupt pinned take fails instead of falling back to
+the project's active branch. The output row and **local output** badges show
+which revisions are pinned. **Follow branch selection** releases the pin;
+output then follows branch-heading selections, never clip previews. An explicit
+run switch asks before releasing it. Save the workflow to keep the pin on disk.
+
+Older workflows can contain a partial pin saved while previewing an ancestor.
+The output row flags this. Choose the intended branch heading and click
+**Use branch locally** once to replace that old selection. Shared ancestors
+can lead to multiple branches, so reopening a workflow never guesses which
+descendant you intended or silently switches an existing snapshot.
+
+**Make branch active (project)**, **Roll active branch back (project)** and
+**Load selected branch** remain project-wide actions. Local selection neither
+restores connected Plan settings nor arms generation/resume. Downstream nodes
+retain their own save and deletion protections. Use the
+manager's manifest output for the experiment, not Manifest Load (which reads the
+project's active checkpoints).
+
+The manager groups immutable scene revisions into inferred branches. A revision
+can appear in more than one branch when it is their shared ancestor. Selecting
+a revision shows its saved preview, prompt, seed, timing, canvas, storage,
+parent, following scenes, and the exact video/audio frame context those
+following scenes consume. Older checkpoints derive this graph from predecessor
+revision and checkpoint hashes; newly saved checkpoints also carry a stable
+branch id and effective context fields.
+
+Plan chapters are checkpoint-management boundaries. The **All scenes** tab
+shows a separate graph for each chapter. Project-wide activation of a Chapter 2
+branch changes only Chapter 2 pointers and connected Plan scene values; Chapter
+1 keeps its current active branch. The chapter-start checkpoint can retain its
+original predecessor as provenance, but that structural edge does not choose
+the preceding chapter. Explicit visual or audio context recorded by a scene is
+still preserved as a generation dependency.
+
+If a branch ends with an empty next-scene slot and saved candidates
+exist elsewhere, the graph displays **Reuse saved clip**. Click it to preview
+the available candidates and choose **Attach selected candidate**. This is
+offered only when the candidate consumes neither predecessor video context nor
+generated-audio continuity. The manager creates a new immutable lineage record
+pointing at the chosen parent; the original video, audio, prompt, and checkpoint
+files remain shared and are not regenerated or copied. Shared-file deletion is
+reference-aware, so those files are retained until the last lineage record that
+uses them is deleted.
+
+Reuse is checked against the saved take's resolved context and audio policy,
+not the current Plan. Candidates that cannot safely change parents show a
+reason instead of disappearing. A rollback tip still appears as an active
+branch even when its old descendants remain saved.
+
+Rerendering an earlier scene can leave old pointer files on disk. Checkpoint
+Manager, Plan Studio and recovery exclude those disconnected descendants from
+the active chapter branch. They remain available as saved inactive takes; no
+media, checkpoint, prompt, scene slot or chapter export is deleted. Use
+**Make branch active / Roll active branch back** to explicitly reconcile those
+old pointers. Recovery stops at the coherent saved prefix, and resuming through
+an inactive tail requires selecting or attributing a matching lineage first,
+even with history verification disabled.
+
+If deleting the active branch tip rolls the run back while alternate leaf
+revisions remain, select the surviving branch and click **Make branch active**.
+The manager validates and promotes that revision's chapter lineage directly,
+including when no Plan is connected. With an editable Plan connected, it also
+restores the lineage's saved scene prompts, seeds, lengths, steps, context,
+LoRA route, and boundary/audio overrides. Exact saved prompts reactivate their
+existing Prompt Editor history revisions instead of adding duplicates.
+Immutable revisions, workflow state, references, and assembled videos are left
+untouched. You can then keep the chosen candidate active and continue deleting
+the rejected inactive leaves.
+**Load selected branch** remains the separate resume operation: it also restores
+saved Plan inputs and arms Loop Start for the following scene.
+
+Deletion is deliberately one scene revision at a time:
+
+1. Select an inactive revision.
+2. Inspect its complete file list, estimated reclaimed size, and preserved
+   categories.
+3. If later revisions depend on it, select and delete those leaf revisions
+   first.
+4. Confirm the now-safe leaf deletion. If anything changed after the preview,
+   the server refuses it and asks for a fresh preview.
+
+This first release does not bulk-delete branches. The leaf-first workflow makes
+the exact context consequences visible and avoids silently orphaning later
+checkpoints.
+
+Chapter recovery snapshots also protect the takes and recovery files they use.
+Historical `supersedes` links do **not** protect a replaced take: they are an
+audit trail, not recovery inputs. Actual scene, alternate and recovery-file
+references still block deletion.
+
+If an unwanted snapshot is the blocker, the deletion inspector offers
+**Retire Chapter … snapshot …**. Inspect the scenes and confirm to move only
+that snapshot's JSON from `chapters/<chapter>/manifests/` into the sibling
+`retired_manifests/` directory. No clip, active pointer, processing take,
+reference or assembled export is deleted. Other retained snapshots and branch
+dependencies still block unsafe deletion; remove unused leaves first.
+
+Retired snapshots no longer appear in Chapter Loader, release their recovery
+pins and cannot be silently republished by a stale selection. Workflows pinned
+to them need a new source. The archived JSON keeps the original bytes; it can
+be moved back to `manifests/` to restore the snapshot only while all its inputs
+still exist. Deleting those inputs later makes full recovery unavailable.
+Retirement requires a fresh preview on confirmation and uses the Run mutation
+lock. Workflow-ownership locking remains nightly-only.
+
+### Saved processing tabs
+
+Checkpoint Manager has **Original**, **DeRoPE**, and **Latent Upscale** tabs.
+**Pixel Upscale** and **Other processing** also appear when those saved profiles
+exist. Chapter filtering applies to the processing views. The original branch
+rows stay in place, with each clip's saved processing takes shown beneath its
+source revision, including retained older takes and multiple profiles.
+
+The catalogue reads the existing `upscaled/<profile>/checkpoints/` directories
+at run and chapter scope. It matches both source revision and checkpoint hash;
+scene number alone never attaches a take to another branch. Attributed aliases
+with matching saved content can share versions. Unresolved sources remain
+visible in a separate section. Stage labels come from the saved recipe/backend,
+not the profile folder name; the bundled combined LBH + DeRoPE recipe appears
+under DeRoPE at its actual saved resolution.
+
+Switching tabs or inspecting a derivative does not rewrite `selected_manifest`,
+move a local pin, activate a branch, restore a Plan, or delete a checkpoint.
+For a later latent-upscale pass, select a saved take in **DeRoPE**, then click
+**Use DeRoPE branch locally**. This pins the whole saved processing branch to
+the browsed original branch; the downstream Adapter still controls start/end.
+Scenes absent from that DeRoPE branch automatically use their selected original
+take. A saved but incomplete/corrupt latent is an error, not an original fallback.
+Return to **Original → Use branch locally** to explicitly use originals again.
+
+New saves keep an immutable processing-lineage snapshot. Older saves can use
+their existing full/partial profile manifest if it identifies the chosen take.
+A shared take with multiple processing descendants is ambiguous: choose a later
+take unique to the desired processing branch. No "latest scene" mixing occurs.
+
+The inspector reports canvas, RAW/delivered frames, audio route, full-latent
+save status, profile and metadata location. A continuation tail is explicitly
+not a full latent. Listing checks file availability without loading tensors or
+hashing every large checkpoint; availability is not execution validation.
+
+To remove a saved processing take, select it in its processing tab and click
+**Delete processed version**. The file/size preview and confirmation cover only
+that take's video, checkpoint, audio and prompt sidecars, its revision metadata,
+its current processed pointer (if still selected), and affected full/partial
+branch manifests. Removing a pointer does not promote another take. Older takes,
+original generation checkpoints, shared references/caches and assembled videos
+are kept. This also works for processing takes whose original is unavailable.
+
+Deletion is blocked while another saved take depends on that processing source
+or requires its saved branch; the inspector lists clickable dependents to
+delete first. Independent **pixel** takes are the exception to sequence ordering:
+the saved pixel backend with zero HQ context proves that a later clip does not
+consume its predecessor's processed output. Such later clips are kept when an
+earlier take is deleted. This applies to legacy full/partial manifests and new
+immutable lineage snapshots, not just newly rendered clips. Actual source or
+context references still block deletion, and unproven/other backends retain
+their conservative branch protection.
+
+Affected sequence manifests are invalidated, not shortened or spliced across
+the missing scene. Surviving clip files, pointers and immutable metadata stay
+unchanged and visible in their processing tab. An old lineage with a missing
+take is no longer offered as a complete source branch. Rebuild the missing
+scenes before resuming a full sequence; no other take is silently substituted.
+
+Ownership is checked again on confirmation, and changed files or
+dependencies require a fresh preview. An in-flight save cannot republish a
+deleted processing dependency. A workflow-local pin is never silently redirected:
+if it referenced the deleted take, explicitly select another source before running.
+Deletion is permanent; the preview does not load or hash large tensor files.
+
+### Alternate final-cut takes
+
+Use an alternate when one accepted scene needs a prompt-level visual correction
+but later scenes already depend on its original checkpoint.
+
+1. Open that scene in Plan Studio and expand **Alternate final-cut take**.
+2. Edit the alternate prompt and seed, then enable the draft.
+3. Queue normally. Loop Start renders only that scene.
+4. Approve the alternate in Review Gate.
+
+Acceptance selects the alternate picture for preview, assembly, PNG export,
+whole-chain latent finishing, and deferred latent/pixel/CAT upscale loops.
+It does not replace the active generation
+checkpoint: later scenes keep their original visual/audio ancestry, and final
+audio for the corrected scene remains the original audio.
+
+Deferred upscale resolves the selected ALT before reading source tensors or
+reference conditioning, for both full-branch and chapter output. It uses the
+ALT's video latent, prompt, seed and reference identity, but reads the original
+audio separately without loading another full video tensor. Adapter/current
+status names the selected ALT, and saved processing takes remain linked to the
+base scene in Checkpoint Manager. A sealed chapter uses its frozen final-cut
+selection; an unsealed full-branch input uses the current selection when the
+loop starts.
+
+Resume checks the actual picture source: an upscale previously made from the
+original cannot be reused for a newly selected ALT (or vice versa). Restart at
+the affected scene, or use a new profile. Saved DeRoPE must likewise belong to
+the selected picture; scenes absent from a partial DeRoPE branch use their
+selected ALT/original. Changing an ALT never overwrites generation checkpoints
+or silently swaps an already selected DeRoPE latent for unprocessed media.
+
+Plan Studio marks the selection `ALT`. Checkpoint Manager nests the immutable
+alternate under its base take rather than drawing a new continuation branch.
+Choose **Original** in Plan Studio to restore the base picture at any time.
+
+An alternate must preserve the scene identity and duration. If a later scene
+exists, set the blend entering that scene to `0`: its saved overlap still shows
+the original base take, so assembly rejects a crossfade from an alternate.
+
+### Whole-chain SeedVR2 finishing
+
+SeedVR2 is best treated as a final whole-video backend, not as another
+scene-recursive H3 pass. Select the final scene of a complete branch in
+Checkpoint Manager and use this graph:
+
+```text
+Checkpoint Manager.selected_manifest
+        + original H3 video VAE
+        ↓
+Full-Chain Latent Video Adapter
+        ↓ native, file-backed VIDEO
+SeedVR2 Direct Video Upscaler
+        ↓
+core Save Video
+```
+
+**Full-Chain Latent Video Adapter** verifies and decodes the original
+safetensors video latent for every selected scene; it never reads the saved
+H.264 scene previews. It trims repeated context, applies the saved incoming
+blend schedule, and writes one lossless RGB movie before SeedVR2 starts.
+SeedVR2 therefore chunks a continuous timeline rather than restarting at H3
+scene boundaries. A chain with Existing Video Context also streams its saved
+prelude into the same movie.
+
+`decode_buffer=disk-backed` is the recommended default. MiniMax H3's VAE keeps
+its native temporal chunking but writes the decoded float scene into a
+temporary mmap. The adapter converts and encodes one frame at a time, retaining
+only the next boundary window in normal RAM, then deletes that scene buffer.
+Peak ordinary RAM is therefore bounded by latent/model overhead and the blend
+window instead of the decoded duration of the full chain. `memory` is a
+compatibility fallback that holds one decoded scene at a time; neither mode
+holds the whole production.
+
+The continuous source is content-addressed and reused at:
+
+```text
+output/h3_chains/<run_name>/upscaled/seedvr2/source/<cache_key>.mkv
+```
+
+The cache key includes the immutable checkpoint lineage, VAE implementation,
+blend schedule, prelude, and selected audio policy. Disable `reuse_cache` to
+force a fresh VAE decode. `audio_source=plan` recovers the saved final-audio
+policy and source audio directly from the manifest. Both an explicit Source
+Timeline and a legacy AUDIO connected once at Loop Start are now materialized
+as path-backed run state. Only manifests created before that legacy promotion,
+and therefore lacking a recovery descriptor, need the optional `source_audio`
+socket.
+
+Use the audio-preserving **SeedVR2 Direct Video Upscaler** from
+[ethanfel/ComfyUI-SeedVR2_VideoUpscaler](https://github.com/ethanfel/ComfyUI-SeedVR2_VideoUpscaler).
+It reads the adapter movie in `chunk_size` batches, returns one file-backed
+H.264 VIDEO, and embeds the source audio in that VIDEO so it can connect
+straight to core Save Video. Its separate AUDIO output remains available for
+alternate muxing graphs.
+
+### Export and recover a particular chapter
+
+Connect **Load Manifest**, **Loop End**, or **Checkpoint Manager** to
+**Chapter Delivery**, then connect `delivery_manifest` to **Assemble** or
+**Export PNG Sequence + Audio**. Set `enabled=true` and `chapter_number=1`, `2`,
+or another explicit chapter number. `0` selects the chapter containing the last
+generated scene; it is not required when you want a particular older chapter.
+
+An unfinished chapter exports only its generated scenes. Chapter Delivery saves
+an immutable manifest with their exact revisions, editorial state, resolution,
+and audio offsets. Later scenes or branch switches cannot extend that snapshot.
+Explicitly deliver the chapter again to capture new scenes or changed takes.
+Unchanged snapshots are reused; changed selections create another snapshot.
+MP4 and PNG/WAV output lives under
+`output/h3_chains/<run>/chapters/<number>_<chapter_id>/`. On main, each PNG export
+uses a new numbered folder; it does not append to an earlier frame export.
+
+Use **Chapter Recovery Load** with the run name and chapter number to load a saved
+snapshot independently. An empty snapshot ID loads the newest; a full ID picks
+an exact older version. This is a recovery manifest, not a copy of all media:
+keep the run's referenced checkpoints and assets. Checkpoint Manager protects
+artifacts needed by sealed snapshots from deletion.
+
+To select chapter output without saving a snapshot, use Checkpoint Manager's
+**Selected chapter only** scope. A local branch pin alone still outputs its
+selected lineage, including earlier chapters; the scope controls the filtering.
+
+### Deferred H3 upscale child runs
+
+Select the generated branch heading you want in Checkpoint Manager and click
+**Use branch locally** to keep that source fixed while experimenting,
+then connect its **selected_manifest** output to **MiniMax H3 Checkpoint Upscale
+Adapter**. The manager verifies the immutable lineage and embeds recovery-only
+compatibility and Source Timeline metadata directly. No source Plan, Chain
+Policy, or decoded source media is retained by the recursive upscale graph.
+
+Use a separate adapter **profile** name for each upscale experiment. Results
+live under `output/h3_chains/<run>/upscaled/<profile>/`; a local source pin is
+not a separate output folder and does not isolate experiments sharing a profile.
+
+To upscale or export just one chapter, set the manager's output scope to
+**Selected chapter only**, select that chapter's branch heading, and click
+**Use branch locally**. Changing the scope of an existing local pin keeps its
+pinned tip; browsing another take does not move it. Earlier chapters may have
+different resolutions: only the selected chapter's media and compatibility are
+validated. Earlier pinned revision metadata is still read to preserve exact
+source-audio and editorial timing. Selecting output does not seal a chapter or
+change project-wide active branches.
+
+Chapter output keeps original scene numbers: a Chapter 2 containing saved
+scenes 8–10 outputs scenes 8–10, even if scenes 11–12 are still planned.
+On Upscale Adapter, `start_clip=1` starts at the first selected scene (8 here),
+`end_clip=0` means the last selected scene (10), and `start_clip=9` resumes after
+verifying scene 8's saved HQ output. No HQ prefix from Chapter 1 is required.
+Reference schedules retain their original Plan scene numbering.
+
+Extending the selected branch from scene 8 to scenes 8–10 does not invalidate
+an unchanged scene 8 upscale. Resume validates every completed scene's source
+revision and media hashes, RAW/delivered frame clock, saved prompt/sampling
+settings, and upscale profile, plus its saved output artifacts. New saves also
+record a per-scene source contract. Older saves use their existing source
+provenance without rewriting the files. The whole-manifest hash remains
+provenance, not a reason to reject an unchanged prefix when later clips are
+added. Changed completed sources or profile settings still require a new pass.
+
+Chapter upscale profiles and finals are isolated under
+`output/h3_chains/<run>/chapters/<number>_<chapter_id>/upscaled/<profile>/`.
+Connect the upscale manifest to **H3 Chain Assemble**; no Chapter Delivery
+filter is needed after a chapter-only selection. Use Chapter Delivery separately
+if you also want to seal an immutable original-quality chapter snapshot.
+
+```text
+Checkpoint Manager → Upscale Adapter → Upscale Current Scene
+                                      → backend graph
+                                      → Upscale Segment Save
+                                      → Upscale Loop End → H3 Chain Assemble
+```
+
+**Upscale Current Scene** prefers the optional `denoised_output` saved by
+Segment + Checkpoint and falls back to the terminal sampler latent in older
+checkpoints. It exposes the joint H3 AV latent as well as separate video and
+audio latents:
+
+- Combined-style nodes can consume `source_latent` directly.
+- Video-only LBH nodes consume `source_video_latent`. **MiniMax H3 Pass-2 AV
+  Prepare** recombines their output with `source_audio_latent`, performs
+  NestedTensor-safe CONST re-noise on video only, and locks the saved audio
+  with a zero denoise mask.
+- LTX 2.5 is a decoded-video V2V path, not an H3-latent path. Decode the H3
+  source latent, run the LTX refinement/upscale graph, and send its raw frame
+  batch to Upscale Segment Save.
+
+For H3 pass-2 conditioning, **Upscale Reference Conditioning** first reads the
+exact cache descriptor recorded on the selected source revision. Tagged and
+Scheduled Ref2VA create that cache automatically: native H3 reference latents
+remain in safetensors while compact Qwen presentation frames allow the saved
+compiled prompt to be tokenized again. **H3 Conditioning Sync From Latents**
+then compares the original scene video latent with the actual LBH output. It
+applies the exact horizontal and vertical scale to `match` picture
+`minimax_refs` and `minimax_keyframes`, while preserving `max` picture refs at
+their Core H3 capped geometry. Pictures already rebuilt from a cache-v2 RGB
+master at the pass-2 canvas are not scaled twice. It updates changed reference
+H/W metadata and deliberately leaves text, temporal positions, and audio
+conditioning untouched. A de-rope target may have a longer video time axis;
+sync accepts that deliberate difference because it changes only spatial
+reference geometry. Upscale Reference
+Conditioning's default `exclude_video_keep_audio` policy removes both the Qwen
+motion-video presentation and native motion-video latent because the pass-2
+source latent already contains the generated motion; audio paired with a video
+reference is converted to an audio-only reference. `keep_video_native` and
+`resize_video` remain available for comparison, and the sync node follows the
+selected conditioning policy automatically. Build sampler 2's new
+Guider from the returned conditioning rather than reusing the original Guider.
+Thus the child graph needs no reference registry or original picture/video/audio
+connections. Both cache versions retain the encoded native reference blocks
+used by sync; cache v2 additionally keeps original picture masters for
+workflows that choose target-resolution VAE re-encoding instead.
+
+The bundled **Deferred Upscale + De-Rope - H3 LBH 3D** workflow wraps
+[ComfyUI-MAINodes](https://github.com/matlowai/ComfyUI-MAINodes)' stable
+decoded time-smear recipe in the child loop:
+
+```text
+source x0 → H3 Jerk Oracle → Chain De-Rope Guard → H3 Time Smear
+          → H3 video VAE encode → LBH 3D → Chain De-Rope Continuity
+          → H3 V2V Init + Inject Schedule → sampler
+          → Exact/Audio Recover → re-encode → Chain Recovered AV
+```
+
+Guard forces the parent scene's repeated prefix to rate 1 and protects the
+last 17 frames when another selected scene follows. It enables Time Smear's
+`expand_to_end` only at the branch tip. Freeze Mask consumes Time Smear's final
+`hold_map_used` (including legal-grid padding) and freezes the protected prefix
+inside H3 V2V Init. For Drift-Control scene 2+, Continuity then replaces that
+target-resolution prefix with the prior HQ tail before sampling.
+
+Audio uses the identical hold map. Decode the source RAW audio latent, run H3
+Audio Smear, VAE-encode it into H3 V2V Init, and recover the pass-2 audio after
+sampling. The workflow seeds audio at strength 0.5 to keep dialogue timing
+aligned but uses MAINodes' safe final preset that retains the original
+performance. Segment Save's optional `recovered_audio` input trims the same
+repeated RAW prefix as video and records the recovered result. Chain Recovered
+AV rejects a still-dilated latent and packs the re-encoded world-clock video
+and audio for optional full-latent saving and compact Drift-Control resume.
+
+This is the stable pixel-smear route, not MAINodes' experimental temporal
+latent insertion. The expanded IMAGE batch stays on CPU, but high-motion
+scenes can still become two to three times longer internally. Narrow the
+adapter's scene range or reduce oracle aggressiveness when RAM or wall time is
+too high. Spatial upscale and de-rope remain in the same regeneration pass so
+a later independent upscale cannot undo the recovered motion timing.
+
+#### Saving DeRoPE for a later deferred pass
+
+The current combined example already wires recovered frames through VAE Encode
+and **Chain Recovered AV**, and sends that recovered latent to Upscale Segment
+Save and Loop End. The example now has **save_latent ON**, so new renders retain
+the complete recovered latent for a later pass. Existing workflows keep their
+stored setting; preview-only results do not gain a latent by opening the tab.
+
+For a separate later latent-upscale pass, a DeRoPE save needs:
+
+- `save_latent` enabled **before rendering**, with Recovered AV connected to
+  Segment Save's `upscaled_latent`. Enabling it changes the profile configuration;
+  use a new profile instead of resuming a prefix saved with the old setting.
+- A full video latent re-encoded **after Exact Recover** on the original RAW
+  clock, including the continuation head (the saver trims delivered pixels
+  separately). Recovered AV checks the H3 temporal length; a stretched pass-2
+  intermediate is not a recovered output.
+- Aligned recovered audio where appropriate. Joint AV saves reuse recovered
+  audio latents and the saved delivered waveform. Video-only saves that preserve
+  the original performance reuse the exact original take's audio latent, loading
+  only audio from that checkpoint. If recovered audio replaces the performance,
+  connect its re-encoded `audio_latent` to Recovered AV before saving.
+- Source revision/hash and reference-cache provenance retained through each
+  stage. Saved child tensors use `upscaled_video`/`upscaled_audio` or
+  `upscaled_samples`; Current Scene translates these into its source AV streams.
+  Reference-cache lookup retains the original generation fingerprint and canvas,
+  then rebuilds conditioning for the processing canvas. New upscale results
+  remain linked through their DeRoPE parent to the original checkpoint.
+
+Select a **different output profile** for the later pass. The original generation
+and DeRoPE source files are not overwritten. Full latent headers and checksums
+are checked at execution; a continuation tail or time-stretched intermediate is
+not a valid recovered source.
+
+When pass 2 should use a different reference set, insert **Upscale Reference +
+Prompt Override** on the normal `H3_TAGGED_REFERENCES` line and connect its
+`references` and `prompt_override` outputs to **Upscale Reference
+Conditioning**. An explicit registry replaces, rather than ambiguously merging
+with, the compiled cache. The node can remove comma-separated tags without
+renumbering references by hand; the conditioning node recompiles the resulting
+prompt, Qwen presentation, and native blocks together. Leave its reference
+input unconnected to retain the automatic cache route. Connected picture/video
+refs require the original H3 video VAE, while activated standalone or paired
+audio additionally requires the H3 audio VAE. No Plan or Source Timeline is
+introduced; sequential/source-timeline live refs should be converted to a
+scene-local restart/standalone reference before use in deferred upscale.
+
+Upscale Reference Conditioning encodes the exact saved compiled prompt by
+default. Its optional `prompt_override` is encoded instead when supplied, so a
+user can provide a short appearance/detail-only pass-2 prompt without repeating
+the source scene's motion or camera instructions. Automatic natural-language
+motion stripping is intentionally avoided because it cannot reliably separate
+action from identity, framing, or continuity clauses. The bundled LBH workflow
+therefore leaves the override blank and uses the original compiled prompt by
+default. Its How To Run note retains a neutral preservation/detail replacement
+prompt for an explicit copy/paste A/B test.
+Missing reference caches are rebuilt automatically before applying
+`missing_cache`, including in Pixel Conditioning and the CAT video wrapper.
+Recovery uses the selected generation take's saved reference lineage (also
+through DeRoPE), not the current Plan or current tag assignments. It verifies
+archived/input project media against saved content hashes, decodes only active
+references, and re-encodes them with the connected H3 VAEs. Native pictures,
+video/audio references, and Qwen-only semantic anchors retain their separate
+roles. No diffusion sampling or source-scene regeneration is needed.
+
+Recovered caches use the existing deduplicated V3 tensor store and a run-local
+`reference_cache/rebuilt_<identity>.json` index. Subsequent upscales reuse them;
+original checkpoint metadata, source media and legacy bundles are not rewritten
+or deleted. An absent cache bundle/object is recoverable; an existing corrupt
+payload still fails integrity validation.
+
+Recovery keeps presentation settings from an exact surviving cache manifest or
+immutable saved recipe/reference lineage. Older takes without those settings
+use `match`, semantic size `512`, and `timestamped_video`; the status explicitly
+lists these defaults. Sequential/source-timeline references additionally need
+their immutable saved Plan timing. Recovery never executes archived workflows.
+
+Saved sizing is also recovered through static string input links and the modern
+Current Tagged Ref2VA Scene's connected Tagged Scene Options. Unconnected
+Options nodes or ambiguous/dynamic links are not treated as historical evidence.
+The upscale `override_ref_image_size` applies to automatic caches and rebuilt
+references as well as connected Tagged overrides. `inherit` keeps the saved
+policy; explicit `match`/`max` rebuilds native picture conditioning as needed
+without changing the source cache. Changing an old Match cache to Max uses its
+picture masters, or reconstructs them from verified archived media when absent;
+it never just relabels the smaller Match tensors. Existing Max caches keep their
+native geometry. Semantic anchors and motion/audio policy remain separate.
+
+`override_semantic_anchor_size` and `override_semantic_anchor_mode` expose the
+same anchor choices as Tagged Scene Options, plus `inherit`. They apply to
+cached references, missing-cache recovery, and connected Tagged references in
+the latent, pixel, and inherited VIDEO conditioning nodes. For example, choose
+`1280` and `timestamped_video` to explicitly restore those legacy settings.
+Anchor size is independent of `override_ref_image_size=match/max` and the output
+canvas. Connected anchor bundles supply their settings when inheriting.
+Changing cached anchor settings rebuilds the presentation **and prompt labels**
+from verified saved media into a separate reusable cache; the source checkpoint
+and original cache remain unchanged. If the required media cannot be recovered,
+connect explicit Tagged references rather than silently keeping the wrong
+cached anchor settings. Status reports the explicit choices. Use a new upscale
+profile for changed conditioning settings to avoid mixing previous processed
+clips with the new pass. The new pixel/VIDEO widgets are appended after the
+existing canvas controls to preserve saved workflows' positional widget values.
+
+Connect `video_vae` for native visual reference rebuilds and `audio_vae` for
+native audio. If an original file, saved reference identity, or required VAE is
+unavailable, `error` names the recovery requirement; `text_only` explicitly
+falls back without reference conditioning. Connected Tagged references remain
+an intentional override and bypass automatic recovery.
+
+Segment Save adopts each verified cache object into
+`output/h3_chains/<run_name>/reference_cache/` and records only that run-local
+descriptor. Copying or backing up the parent run therefore preserves everything
+required to rebuild pass-2 Ref2VA conditioning.
+
+New V3 scene caches are small JSON manifests pointing into
+`reference_cache/objects/<tensor-content-hash>.safetensors`. Identical reference
+originals, previews, and encoded latents are stored once across scenes/revisions
+within the project. Shared staging objects are hard-linked into the project
+where supported, otherwise copied once. V1/V2 scene-sized bundles remain readable
+and unchanged until explicitly converted. Updating the nodes does not compact
+or delete existing bundles. The [reference-cache converter](SCHEDULED_REFERENCES.md#converting-existing-bundles)
+can split them losslessly, then retire each old bundle after a verified render
+using the conversion successfully commits through an H3 saver. Small legacy JSON
+addresses and conversion/retirement receipts remain for checkpoint compatibility.
+Objects must not be deleted individually while any scene still references them.
+
+Legacy checkpoints that still point into `output/h3_reference_cache/` migrate
+without a rerender. Selecting their complete branch in Checkpoint Manager
+hard-links the verified cache into the corresponding run (or copies it when a
+hard link is unavailable) and returns a run-local descriptor. Migration never
+deletes the global object or rewrites immutable revision metadata. Later branch
+loads resolve the verified run-local equivalent first, so the old staging copy
+can be archived or removed after a successful selection and upscale check.
+Read-only workflow-local/chapter-only selections do not perform this migration;
+checkpoints without an exact cache descriptor still use shared-cache discovery.
+
+Send the backend's decoded **raw** frame batch to both Segment Save and Loop
+End. They remove the parent scene's repeated context head exactly once, persist
+the delivered HQ segment, and carry optional HQ context to the next iteration.
+Set a distinct `profile` for each recipe so settings and outputs cannot collide.
+The profile folder is:
+
+```text
+output/h3_chains/<run_name>/upscaled/<profile>/
+├── segments/
+├── checkpoints/
+├── prompts/
+├── audio/
+├── partial/
+├── upscale_manifest.json
+└── final/
+```
+
+`save_latent` defaults off. Segment Save still writes a small verified
+safetensors checkpoint containing the assembly audio, so the child run remains
+resumable and mergeable without duplicating the much larger HQ sampler latent.
+When the following source scene uses Drift-Control AV, that checkpoint also
+contains only the preceding scene's 12-step HQ video tail. Pass-2 AV Prepare
+splices this tail into scene 2+'s prefix, gives it zero added noise and a zero
+denoise mask, and refines only the new video region. This compact context is
+enough for exact interruption-safe HQ continuation without enabling full
+latent saving. Older child checkpoints without the tail safely protect their
+independently upscaled source prefix and report that fallback in node status.
+Enable full latent saving only when you want to reopen/refine the HQ latent
+itself. The transient `upscaled_latent` connection on Loop End remains usable
+for scene continuity whether or not persistence is enabled.
+
+For new parent renders, connect SamplerCustomAdvanced `denoised_output` to
+Segment + Checkpoint's optional `denoised_latent` input. Existing checkpoints
+remain valid and use their terminal sampler output. Keep the parent branch
+until every selected child scene has been persisted; a completed child profile
+contains its own HQ video segments and audio needed by H3 Chain Assemble.
+Assemble recognizes the upscale manifest, reconstructs a recoverable Source
+Timeline from the embedded parent manifest, and keeps the canonical HQ result
+under `upscaled/<profile>/final/`. Its normal `copy_to_output` and
+`output_subfolder` controls can additionally publish the MP4 in ComfyUI's
+regular output tree. Legacy source-track runs without the embedded descriptor
+still need their original full AUDIO connected to Assemble.
+
+## Run Manager
+
+Connect the active Plan output to **MiniMax H3 Run Manager**. It discovers runs
+under the ComfyUI host's `output/h3_chains`, including remote Docker hosts.
+Select a run and choose **Load selected archive into Plan**; after confirmation
+it restores archived prompts and Plan controls without changing graph links.
+
+The two names at the top are deliberately separate:
+
+- **Active Plan** is the connected Plan's current `run_name`. Generation and
+  **Save assets to active Plan** use this name.
+- **Selected archive** is only the folder highlighted in the browser. Selecting
+  it does not change the Plan. **Load selected archive into Plan** is the only
+  action that applies its archived prompts and settings.
+
+When both names match, the archive is marked **ACTIVE PLAN**. When they differ,
+the selected archive is labeled **not loaded**, so opening an old folder or
+inspecting it cannot be mistaken for switching the generation run.
+
+Restore prefers:
+
+1. `api_prompt.json`;
+2. `workflow.json`;
+3. effective settings derived from `plan.json` for older runs.
+
+The fallback retains exact scene lengths, steps, and seeds even when an old run
+did not archive unused default-widget values.
+
+## Archive reference assets
+
+Connect loader outputs to Run Manager's dynamic **Connect loader asset** socket,
+up to 12 assets. Classify each as Picture, Video, Audio reference, or Source
+track so a short voice reference cannot be confused with a project soundtrack.
+
+Wire all Semantic Picture Anchor nodes into one Semantic Anchor Bundle, then
+connect the Bundle's **references** output to Run Manager's
+**tagged_references** socket. The same line can feed Tagged Ref2VA and Plan
+Studio. The interface discovers the Bundle's upstream image loaders and
+archives/restores them as individual picture assets without consuming the 12
+direct loader sockets.
+
+- Archive images and audio default on.
+- Archive video defaults off because video references can be large.
+- Only files inside ComfyUI's input directory are eligible for fallback copies.
+- Content-addressing deduplicates unchanged media and retains changed versions.
+
+Restore first uses the original input-relative path. If it is missing and a
+fallback exists, Run Manager copies the archived asset into a unique ComfyUI
+input filename and updates a compatible loader. Targets are matched by persistent
+binding identity, archived node ID/type, then unambiguous compatible loaders.
+Ambiguous targets remain unchanged and are reported.
+
+## Run folder contents
+
+```text
+output/h3_chains/<run_name>/
+├── plan.json
+├── workflow.json
+├── api_prompt.json
+├── manifest.json
+├── prompt_history/<scene_id>/
+├── segments/clip_0001.<revision>.mp4
+├── segments/clip_0001.<revision>.prompt.txt
+├── checkpoints/clip_0001.json
+├── checkpoints/clip_0001.<revision>.json
+├── checkpoints/clip_0001.<revision>.safetensors
+├── generated_audio/
+├── reference_cache/
+│   ├── scene_0001.<scene-contract>.json
+│   └── objects/<tensor-content-hash>.safetensors
+├── chapters/<number>_<chapter_id>/
+│   ├── manifests/<snapshot_id>.json
+│   ├── final/
+│   ├── frames/
+│   └── upscaled/<profile>/  (including seedvr2/source/)
+├── upscaled/<profile>/
+└── final/<filename>.mp4
+```
+
+Regenerating a scene updates its active checkpoint pointer but retains all
+earlier MP4s, prompt sidecars, metadata, safetensors, and generated WAVs. Each
+revision records what it supersedes.
+
+Workflow and API graph metadata are embedded in segment/final files using
+ComfyUI's standard tags. `workflow.json` is the preferred file to drag back
+into ComfyUI; `plan.json` remains the authoritative effective render record.
+Keep run folders private when workflows contain credentials.
+
+## Assembly
+
+Assemble accepts completed or partial manifests, including an interrupted
+prefix reconstructed by Manifest Load. Its filename supports date
+tokens such as `%date:yyyy-MM-dd%`, `%year%`, `%month%`, `%day%`, `%hour%`,
+`%minute%`, and `%second%`. Existing files are never overwritten; numbered
+suffixes are added automatically.
+
+### Recovery blend schedules
+
+`blend_schedule` can override the Plan's global visual blend only during
+assembly. `plan` preserves the recorded setting. A comma-separated schedule is
+applied to scene boundaries in timeline order: `5,30` uses five frames for the
+first join and thirty for every later join because the last value repeats.
+`0` produces hard cuts. This does not change checkpoints, prompts, seeds, or
+generated frames.
+
+When the requested boundary fits inside the saved blend MP4, assembly reuses
+that artifact directly. If it requests more overlap than Segment Save retained,
+connect the original MiniMax H3 video VAE to `blend_video_vae`. Recovery then
+re-decodes the existing safetensors checkpoint into a temporary lossless RGB
+video and deletes it after assembly. Diffusion is never rerun. The final video
+still receives the one H.264 encode required by any pixel-space crossfade.
+
+Each scheduled value must not exceed that incoming scene's repeated context.
+For example, a chain whose first join has five context frames and later joins
+have thirty-nine can use `5,30`; requesting thirty at the first join is rejected.
+
+### Optional scene-one color stabilization
+
+Set Assemble's `color_stabilization` to `scene_1_anchor` to counter gradual
+exposure or saturation drift in a completed chain. Assembly measures a
+center-weighted sample of the first generated scene, then fits only a weak,
+bounded luma/saturation correction for each later scene. A correction is capped
+at six code values of luma and six percent of saturation, at half the measured
+strength.
+
+The exact join inherits the preceding scene's accepted correction. Starting
+after the retained overlap, that correction moves smoothly to the next scene's
+target over 72 frames. Consequently the option cannot introduce a new grade
+step at the boundary and does not change motion, timing, or audio. A prelude is
+not used as the reference: the first generated scene remains the anchor.
+
+This is an assembly grade, not diffusion conditioning. It does not change
+checkpoints or future continuation input. It is disabled by default. Enabling
+it uses the same single pixel-processing encode as a visual blend; on a hard-cut
+assembly it replaces the otherwise lossless stream copy with one encode.
+
+For an experimental correction that can influence later generation instead of
+only the final MP4, choose **Color-Stable Drift AV** through Advanced Policy or
+on a scene's incoming transition. It applies a bounded scene-one correction to
+the disposable copied video latent as a VAE delta, tapering from zero to full
+strength across the 39-frame context. Scene 1 remains the anchor, scene 2 is
+neutral, and scene 3 onward can receive a corrected predecessor tail. It does
+not alter the saved predecessor checkpoint or audio. Because this changes
+generation conditioning, it is recorded in the incoming-boundary dependency
+and is intentionally separate from this assembly-only option.
+
+Enable `copy_to_output` to keep the canonical final in the run folder and also
+publish an MP4 into the regular ComfyUI output tree. `output_subfolder` is
+relative to that output root, supports nested folders and the same date tokens,
+and may be empty to place the copy directly in `output/`. The existing
+`filename` value is used for both copies, and collisions are versioned.
+
+## Stream pixel-upscale VIDEO to PNG, scene by scene
+
+**Export PNG Sequence + Audio** also has a VIDEO passthrough mode for pixel
+upscales with no saved latent. Put it **inside** the scene loop, before the
+lossy MP4 segment save:
+
+```text
+Final pixel refiner VIDEO -> Export PNG.video -> Segment Save.video
+                                             -> Loop End.video
+Current Scene.state      -> Export PNG.state
+```
+
+Disconnect the exporter's `manifest`, `video_vae` and `audio_vae` in this mode.
+Do not connect the final Loop End manifest back into the in-loop exporter.
+The original four output positions are unchanged; the new `video` output is
+the exact incoming VIDEO, released downstream after the current scene is saved.
+Segment Save still preserves the original audio. The PNG node does not turn
+compressed MP4s back into supposedly lossless originals.
+
+Use `output_folder` for a chosen subfolder of ComfyUI output (relative or
+absolute). When blank, the sequence goes under the upscale profile's
+`frames/<export_name>/`, including the chapter scope when applicable. The first
+exported scene starts at `first_frame_number`; subsequent scenes append without
+resetting numbering. Each scene's repeated RAW context frames are removed using
+the current state, just as in Segment Save. This is the sequential upscale
+delivery clock, not a later editorial reordering or blend pass.
+
+`png_bit_depth` is a user choice: **8** is the existing default; **16** preserves
+the RGB16 file-backed intermediate's precision. Both use lossless PNG compression,
+but 8-bit explicitly quantizes higher-precision input. Neither is an H3 latent
+checkpoint; these are full-resolution pixel backups with provenance and hashes.
+Keep the upscaler's file-backed VIDEO path for bounded memory. Native in-memory
+VIDEO, lazy trims/crops, wrong frame counts and mismatched frame clocks are
+rejected rather than silently materialized or exported incorrectly.
+
+Existing controls remain: `png_compression`, `embed_workflow`, `save_workers`,
+`checkpoint_verification`, and `reuse_existing`. Compression affects speed/size,
+not precision. The decoder streams one frame at a time and never loads all
+scenes; at most `save_workers` PNG jobs are in flight (0 chooses up to eight).
+There is no VAE encode/decode or GPU work in this export path.
+
+Each complete scene is committed to a continuous image sequence plus
+`export.json` before passthrough. The index records source identity, RAW trim,
+numbering, bit depth, profile, source manifest, and PNG hashes. Interrupted
+decode/save operations roll back that scene and keep every earlier scene intact.
+Resume at the next missing scene with the same folder/settings. Exact repeated
+scenes can be reused; `cached` skips hashing when previous PNG size/mtime match,
+but verifies SHA-256 if only the timestamp differs. `strict` always hashes.
+A timestamp difference alone never invalidates byte-identical PNGs or WAVs.
+Incoming VIDEO files are always hashed. Different takes, changed
+settings, missing/modified PNGs, untracked frames or out-of-order scenes never
+overwrite a sequence: select a new folder/export name, or resume the missing
+scene. With reuse disabled, use a new folder for a fresh export. Abrupt process
+death during publication can leave untracked frames; these are kept and reported,
+not silently overwritten. Concurrent writers to one folder are rejected.
+
+Hard links are an optional publishing optimization, not a storage requirement.
+If a network share rejects them (including permission denied / errno 13), the
+exporter falls back to an exclusive file copy with a 1 MiB buffer. Existing
+files are never replaced, and genuine write-permission or storage failures
+still stop the export; no filesystem permissions or project ownership change.
+
+The sequence is a verified export, not an editable working copy. Editing a
+saved PNG makes its checksum differ and prevents VIDEO-mode reuse or append
+when detected, including when exporting a later scene. Even metadata-only edits
+or recompressing identical pixels can change the file hash. Existing PNGs are
+never overwritten. Keep intentional retouches in a separate working copy;
+the VIDEO passthrough still contains the incoming video, not edits made to the
+PNG files. This node does not currently adopt edits into its saved index.
+
+## Re-decode checkpoints to PNG and WAV
+
+Connect a manifest to **Export PNG Sequence + Audio**, then connect the original
+H3 video VAE, audio VAE, or both. Video-only writes PNGs, audio-only writes one
+continuous `audio.wav`, and both inputs produce a synchronized image sequence
+and soundtrack in the same folder. The WAV is decoded from the checkpointed H3
+audio latents, preserves the generated AV boundary ownership, and follows the
+same selected scene order and latent-safe trims as the gap-free PNG sequence.
+
+The node verifies each safetensors checkpoint, decodes one scene at a time,
+removes repeated overlap, converts small frame chunks to the selected 8-bit or
+16-bit RGB depth in one
+operation, and writes each chunk through bounded parallel atomic PNG workers.
+ComfyUI's progress bar covers verification, GPU decode, and saving. The server
+log reports verify, checkpoint-load, decode, conversion, and save timings. The
+deliverables and `export.json` are written under:
+
+```text
+output/h3_chains/<run_name>/frames/<export_name>/
+```
+
+For a Chapter Delivery manifest the equivalent path is
+`chapters/<number>_<chapter_id>/frames/<export_name>/`; `export.json` records
+the chapter number and immutable snapshot id.
+
+Chapter exports default to `reuse_existing = true`. A later export using the
+same export name looks for a successful matching export and reuses its unchanged
+PNG prefix. New scenes continue the existing frame numbering in that folder,
+without decoding or rewriting the earlier PNGs. An identical export skips both
+video and audio decoding. When new scenes extend the chapter, the synchronized
+`audio.wav` is rebuilt and atomically replaced so audio joins remain correct;
+WAV bytes are not blindly appended.
+
+Changed checkpoint revisions, trims, placements, frame numbering, or relevant
+export settings create a new numbered folder instead of mixing old and new
+output. A shorter/older chapter snapshot never truncates a longer export.
+Missing, modified, or untracked PNGs, interrupted exports, and legacy exports
+without the new verification records also use a fresh folder; their existing
+files are left untouched. `cached` checks recorded size and modification time;
+`strict` additionally re-hashes the reusable PNGs and WAV. Concurrent appenders
+to the same chapter/export name are rejected while the first export is running.
+
+Set `reuse_existing = false` to force a fresh folder, especially after changing
+VAE weights, precision, ComfyUI version, or decode settings. The reuse signature
+identifies the VAE class, not the full weights. Whole-Run exports retain their
+existing fresh-folder behaviour regardless of this switch.
+
+Reused PNGs retain their original embedded workflow/manifest metadata.
+`export.json` is the current export index and points to the latest selected
+immutable chapter snapshot; earlier indexes remain in `export.history/`.
+`complete` means that this export succeeded; `chapter_complete` separately
+indicates whether all planned chapter scenes have been generated. The node's
+frame count includes reused frames, and its status reports reused/new counts.
+MP4 assembly still creates a new assembled movie; incremental PNG reuse does
+not imply in-place MP4 appending.
+
+PNG compression is lossless. Use the same VAE, ComfyUI version, precision, and
+decode settings for the closest reconstruction. The checkpointed latent is
+exact, but a new VAE decode is not guaranteed to be bit-identical to an older
+decode made under different settings. New nodes use compression level 1 and
+`save_workers = 0`, which automatically selects at most eight workers. Set the
+worker count to 1 for serial saving or raise it explicitly only when the output
+storage can sustain more concurrent writes.
+
+`checkpoint_verification = cached` still performs a complete SHA-256 check the
+first time. Later exports skip re-hashing only while the checkpoint's recorded
+hash, byte size, and nanosecond modification time all match. Select `strict` to
+re-hash every checkpoint on every export. During execution,
+`export.partial.json` is updated after every converted chunk and retained if the
+export fails or is interrupted; a successful export replaces it with
+`export.json`, including the effective settings and per-scene timings.

ComfyUI-MiniMaxH3-Context-Loop/docs/SCENE_AUTHORING.md

@@ -0,0 +1,195 @@
+# Scene authoring
+
+## Plan structure
+
+The Plan node provides a visual editor and stores ordinary JSON underneath.
+Put shared instructions in `prompt_prefix`; each scene should describe what
+changes.
+
+```json
+{
+  "prompt_prefix": "Keep the same performer, wardrobe and visual language.",
+  "defaults": {"duration_seconds": 15, "steps": 20},
+  "shots": [
+    {"id": "intro", "prompt": "Instrumental opening in the elevator.", "seed": 123},
+    {"id": "street", "prompt": "Continue outside into the rain.", "seed": 456}
+  ]
+}
+```
+
+Prompts may be multiline strings or arrays of lines. Seconds are rounded up to
+H3's valid `17k+5` frame grid. Use `length` when exact raw frames matter.
+
+The [complete format guide](../H3_CHAIN_FORMAT_GUIDE.md) documents every Plan
+and per-scene field, raw versus delivered length, prompt structure, seeds, and
+timing.
+
+## Chapter resolution
+
+Click the chapter marker in **Plan Studio** to choose **Inherit from Plan** or
+**Chapter resolution**, with Width and Height in multiples of 32. Each chapter
+has one size; the next chapter inherits the Plan default, not the previous
+chapter's override. Wire **Current Shot** width/height to conditioning so its
+latent and reference preparation match the active chapter. The combined
+**Current Tagged Ref2VA Scene** node already handles this internally.
+
+The existing scene lock also pins a chapter to its locked saved scenes' size.
+For example, lock Chapter 1's saved scenes, then change the Plan default or set
+Chapter 2's resolution. Chapter 1 stays at its saved size. A conflicting explicit
+size for Chapter 1 is rejected until its saved scenes are unlocked. Locking an
+ungenerated slot cannot pin a size. Locks do not bypass prompt/model identity,
+artifact-integrity, or native latent compatibility checks.
+
+Different-sized chapters need an independent video boundary: set the new
+chapter's first scene's video context to zero for AV masking or latent Guide.
+Export each chapter separately with **Chapter Delivery**. Whole-run assembly
+cannot combine different sizes automatically.
+Saved media is never resized; recovery snapshots retain the resolved chapter size.
+
+In Plan JSON the optional field is, for example:
+
+```json
+{"id":"chapter_2","title":"Chapter 2","start_scene_id":"scene_08",
+ "resolution":{"width":1344,"height":768},"text":""}
+```
+
+Omit `resolution` (or set it to `null`) to inherit. Chapter titles and notes
+remain editorial only and do not change generation identity.
+
+## Per-scene LoRA routes
+
+Each scene has a **Scene LoRA route** selector: Base or LoRA A-D. Connect
+Current Shot `state` to **MiniMax H3 Scene LoRA Scheduler**, connect the normal
+base MODEL to `base_model`, and connect MODEL outputs from ordinary ComfyUI
+LoRA loaders to the A-D inputs. The scheduler only routes those prepared
+models; it never chooses a file or applies a LoRA.
+
+One route can contain a stack of ordinary LoRA loaders. The same LoRA at two
+strengths can be represented by two branches. Inputs are lazy, so a connected
+branch is not evaluated until a scene selects it. Put patches shared by every
+scene after the scheduler. When using Drift-Control, send the scheduled MODEL
+through Chain Context's MODEL input/output before the sampler.
+
+## Scene Prompt Editor
+
+Connect Plan to **MiniMax H3 Scene Prompt Editor** for a large synchronized
+textarea. It edits the selected scene's real `shots[n].prompt`; there is no
+second prompt copy.
+
+- Arrow buttons or `Alt+Left/Right` change scenes.
+- Typing `@` offers the connected Picture/Video/Audio aliases. In Tagged mode,
+  inserting an inactive alias activates it; scheduled references remain limited
+  to the selected scene.
+- Typing `#` offers valid dedicated Semantic Picture Anchors (and legacy
+  Tagged Picture compatibility anchors) only.
+- Typing `<` offers H3 subjects, dialogue tags, and available native reference
+  labels, plus `<scenetrans>` and `<|cutoff|>` dialogue-flow markers. Typing
+  `[` filters 12 shot markers, multilingual dialogue markers, and canonical
+  summary-intent combinations; for example, `[re` lists the supported
+  reference-generation combinations. Typing `(S` offers stable speaker IDs.
+- Typing the start of an H3 section name at the beginning of a line completes
+  `subject_definitions:`, `integrated_multimodal_description:`, and the other
+  standard sections. `Ctrl+Space` (`Cmd+Space` on macOS) opens the full H3
+  completion catalog. Use arrows to select and `Enter` or `Tab` to insert.
+- **@ Reference** remains available for browsing connected media previews.
+- **Dialogue** wraps a selection in `<d>` tags.
+- Choose **Auto schema**, T2VA, I2VA, FL2VA, L2VA, or Ref2VA, then open
+  **Sections** to inspect the exact required order, jump to a category, insert
+  a missing category, or normalize the mode's keyframe-alignment line.
+  Diagnostics cover section spelling/order, shot numbering and timestamps,
+  Ref2VA task directives and definitions, dialogue/language/flow balance, and
+  connected native references. FL2VA/L2VA expose duration and final-shot
+  controls for their exact alignment sentence.
+- Live word/character counts stay in the footer. Both dedicated editors can
+  switch between the ordinary prompt source and rich H3 token presentation;
+  this changes presentation only, never Plan text.
+- `#picture` adds an untimed Qwen-only semantic Picture when the picture is
+  supplied through Semantic Anchor Bundle. Add a time as
+  `#picture[2.50s]` for a scene-local Qwen checkpoint; with the Bundle set to
+  `picture_storyboard`, the time becomes an approximate prompt instruction.
+  Neither form consumes a native H3 reference slot.
+- `A−` and `A+` change persistent type size.
+- The node may sit inline before Loop Start or on an editor-only branch.
+
+The reference tray discovers downstream Scheduled Ref2VA, core Ref2VA, and core
+Image to Video nodes without introducing an execution socket or graph cycle.
+Hovering a loader-backed reference previews its image, video, or audio; computed
+tensors remain usable even when no browser-playable source file can be found.
+
+The schema inspector and completion catalog are shared by the focused Scene
+Prompt Editor and the optimizer-enabled Rich Scene Prompt Editor. They are
+backported from the standalone
+[H3 Prompt IDE](https://github.com/ethanfel/ComfyUI-H3-Prompt-IDE), while these
+nodes retain Motion Context Plan synchronization, revisions, `@tags`,
+semantic anchors, and optimizer integration.
+
+### Editor interactions
+
+Click a Subject, speaker, dialogue, lyrics, caption or flow token to replace
+or remove it. Pasted tokens become interactive immediately. Connected media
+references keep their existing reference/syntax/time popup and previews.
+Ctrl/Cmd-click an ordinary `[Shot N]`, language, task directive or retention
+marker to change it without replacing the surrounding sentence.
+
+Inside `retention_analysis:`, completion offers visual or audio retention
+values according to the reference kind, including known `@aliases` and
+`#picture` anchors. Inside `detailed_description:`, typing
+`[Shot N] At` offers `At 00:00.000, `, selecting the seconds/milliseconds
+for immediate editing. Ctrl/Cmd+Space also offers the timestamp after a plain
+`At` in that section.
+
+ComfyUI **Settings → MiniMax H3 Context Loop → Prompt editor** controls the
+default Rich/Plain presentation, automatic suggestions, optional trailing
+spaces, and the new marker replacement menus. Saved per-node presentation
+choices win. Trailing spaces are off by default to preserve existing typing
+behavior; semantic anchors never receive an inserted space before their time.
+Turning off automatic suggestions still allows Ctrl/Cmd+Space.
+
+Ctrl/Cmd+S saves the workflow while the editor is focused. Ctrl/Cmd+Z remains
+scene-local. Token diagnostics flag malformed lyrics/caption pairs, incorrect
+special-token case, and legacy `<cutoff>`; they do not rewrite saved prompts
+or change generation. No task-aware Edit templates or new node sockets are
+introduced by this port.
+
+## Prompt revisions
+
+The compact `‹ Active current / total ›` selector below the editor activates a
+prompt version in the Plan; it is not a read-only history browser. Each version
+is labeled **Active draft**, **Active executed**, **Draft history**, or
+**Executed history**. Typing updates one active draft rather than creating a
+revision per keystroke. When Current Shot executes, that exact prompt becomes
+immutable; typing from it creates a child draft. Activating an older version
+explicitly replaces the selected scene prompt in the Plan.
+
+History is stored outside Plan JSON and loaded only for the selected scene:
+
+```text
+output/h3_chains/<run_name>/prompt_history/<scene_id>/
+```
+
+The Plan retains only the active prompt, keeping workflow JSON readable and
+load time independent of old revisions.
+
+## Seeds and bounded runs
+
+Set a scene seed explicitly when repeatability matters. If omitted, Plan derives
+a deterministic seed from `base_seed` and scene identity.
+
+Loop Start's `scene_range` accepts one continuous selection:
+
+| Value | Result |
+|---|---|
+| blank | `start_clip` through the end |
+| `3` | scene 3 only |
+| `3:8` | scenes 3 through 8, inclusive |
+
+A range starting above scene 1 requires the preceding checkpoint. Disjoint
+selections are rejected because skipped scenes would break the motion chain.
+
+## Prompt Assistant status
+
+The embedded Prompt Assistant is currently dormant so the editor retains its
+compact manual workflow. Use the `comfyui-mcp` sidebar Agent panel for Codex or
+Hermes assistance. The implementation, safety model, and future console-agent
+design are preserved in the
+[Prompt Assistant study](../AGENT_PROMPT_ASSISTANT_STUDY.md).