"""V3.5 Second Pass contracts and the physical-group sampling runtime.""" from __future__ import annotations import copy import hashlib from collections.abc import Mapping, Sequence from typing import Any import torch from ..model_patch import clone_model_for_chunk from ..state import extract_av_streams from ..v2.h3_builder import encode_prompt_conditioning from ..v2.sampling import latent_from_cpu from .plan import SECOND_PASS_CONTRACT_VERSION from .refine_context import ( MAGIC as REFINE_CONTEXT_MAGIC, RefineConditioningAdaptationError, RefineContextError, adapt_group_conditioning, validate_refine_context, ) from .refine_sampling import sample_refine_chunk class SecondPassContractError(ValueError): """Raised only when a Second Pass structural contract is impossible.""" def derive_refine_seed(refine_seed: int, physical_group_index: int) -> int: """Derive one deterministic seed per physical group in an independent namespace.""" if type(refine_seed) is not int or refine_seed < 0: raise SecondPassContractError("refine_seed must be a non-negative integer") if type(physical_group_index) is not int or physical_group_index < 0: raise SecondPassContractError("physical_group_index must be a non-negative integer") payload = f"h3-continuum-refine-v1:{refine_seed}:{physical_group_index}".encode("ascii") return int.from_bytes(hashlib.blake2b(payload, digest_size=8).digest(), "big") def _latent_samples(value: Any, *, name: str) -> torch.Tensor: if not isinstance(value, Mapping) or "samples" not in value: raise SecondPassContractError(f"{name} must be a LATENT mapping with samples") samples = value["samples"] if not isinstance(samples, torch.Tensor): raise SecondPassContractError(f"{name}.samples must be a tensor") return samples def _contract_groups(assembly_plan: Mapping[str, Any]) -> list[Mapping[str, Any]]: if not isinstance(assembly_plan, Mapping): raise SecondPassContractError("assembly_plan must be a mapping") contract = assembly_plan.get("second_pass_contract") if not isinstance(contract, Mapping): raise SecondPassContractError("assembly_plan has no second_pass_contract") if contract.get("version") != SECOND_PASS_CONTRACT_VERSION: raise SecondPassContractError("unsupported second_pass_contract version") groups = contract.get("physical_groups") if not isinstance(groups, list) or not groups or not all(isinstance(g, Mapping) for g in groups): raise SecondPassContractError("second_pass_contract.physical_groups must be non-empty") return groups def _validate_video_groups( video_latents: Sequence[Any], assembly_plan: Mapping[str, Any], ) -> tuple[list[Mapping[str, Any]], tuple[int, int]]: groups = _contract_groups(assembly_plan) if not isinstance(video_latents, Sequence) or isinstance(video_latents, (str, bytes)): raise SecondPassContractError("video_latents must be a sequence") if len(video_latents) != len(groups): raise SecondPassContractError("video latent group count changed") target_geometry: tuple[int, int] | None = None for position, (latent, group) in enumerate(zip(video_latents, groups, strict=True)): if group.get("group_id") != position: raise SecondPassContractError("physical group order or group_id changed") samples = _latent_samples(latent, name=f"video_latents[{position}]") if samples.ndim != 5: raise SecondPassContractError("video latent must have shape [B,C,T,H,W]") batch, channels, temporal, height, width = (int(value) for value in samples.shape) if channels != 24: raise SecondPassContractError("MiniMax H3 video latent must have 24 channels") if batch != int(group.get("source_batch", -1)): raise SecondPassContractError("video latent batch changed") if temporal != int(group.get("source_latent_t", -1)): raise SecondPassContractError("video latent temporal length changed") source_h = int(group.get("source_latent_h", -1)) source_w = int(group.get("source_latent_w", -1)) if source_h < 1 or source_w < 1 or height < source_h or width < source_w: raise SecondPassContractError("video latent spatial size must be preserved or enlarged") if target_geometry is None: target_geometry = (height, width) elif target_geometry != (height, width): raise SecondPassContractError("all physical groups must use the same target H/W") assert target_geometry is not None return groups, target_geometry def validate_second_pass_inputs( video_latents: Sequence[Any], audio_latents: Sequence[Any], assembly_plan: Mapping[str, Any], ) -> dict[str, Any]: """Validate only structural invariants required by a future Second Pass node.""" groups, target_geometry = _validate_video_groups(video_latents, assembly_plan) if not isinstance(audio_latents, Sequence) or isinstance(audio_latents, (str, bytes)): raise SecondPassContractError("audio_latents must be a sequence") if len(audio_latents) != len(groups): raise SecondPassContractError("audio latent group count changed") for position, (latent, group) in enumerate(zip(audio_latents, groups, strict=True)): samples = _latent_samples(latent, name=f"audio_latents[{position}]") expected_shape = group.get("source_audio_shape") if not isinstance(expected_shape, list) or tuple(expected_shape) != tuple(samples.shape): raise SecondPassContractError("audio latent shape or physical group order changed") return { "physical_group_count": len(groups), "target_latent_h": target_geometry[0], "target_latent_w": target_geometry[1], "audio_passthrough": True, } def passthrough_audio_latents(audio_latents: Sequence[Any]) -> list[Any]: """Return original LATENT objects; temporary refined audio is not adopted in V1.""" return list(audio_latents) def update_second_pass_geometry( assembly_plan: Mapping[str, Any], video_latents: Sequence[Any], ) -> dict[str, Any]: """Return a copied plan whose output geometry follows the upscaled physical latents.""" groups, (target_h, target_w) = _validate_video_groups(video_latents, assembly_plan) scale_h: int | None = None scale_w: int | None = None for group in groups: source_h = int(group["source_latent_h"]) source_w = int(group["source_latent_w"]) source_height = int(group["source_height"]) source_width = int(group["source_width"]) if source_height % source_h or source_width % source_w: raise SecondPassContractError("source pixel/latent geometry is not integral") group_scale_h = source_height // source_h group_scale_w = source_width // source_w if scale_h is None: scale_h, scale_w = group_scale_h, group_scale_w elif (scale_h, scale_w) != (group_scale_h, group_scale_w): raise SecondPassContractError("source geometry scale differs between groups") assert scale_h is not None and scale_w is not None target_height = target_h * scale_h target_width = target_w * scale_w updated = copy.deepcopy(dict(assembly_plan)) updated["width"] = target_width updated["height"] = target_height contract = updated["second_pass_contract"] contract["target_width"] = target_width contract["target_height"] = target_height for group in contract["physical_groups"]: group["target_latent_h"] = target_h group["target_latent_w"] = target_w group["target_width"] = target_width group["target_height"] = target_height return updated def run_second_pass_groups( *, model: Any, clip: Any, sampler: Any, sigmas: torch.Tensor, video_latents: Sequence[Any], audio_latents: Sequence[Any], assembly_plan: Mapping[str, Any], refine_seed: int, refine_context: Any = None, video_vae: Any = None, conditioning_upscale_method: str = "bilinear", enable_preview: bool = True, encode_prompt_fn=None, latent_builder=None, sample_fn=None, stream_extractor=None, clone_model_fn=None, validate_refine_context_fn=None, adapt_group_conditioning_fn=None, ) -> tuple[list[dict[str, Any]], list[Any], dict[str, Any], str]: """Refine complete physical groups while preserving first-pass audio exactly.""" validation = validate_second_pass_inputs(video_latents, audio_latents, assembly_plan) groups = _contract_groups(assembly_plan) encode_prompt_fn = encode_prompt_fn or encode_prompt_conditioning latent_builder = latent_builder or latent_from_cpu sample_fn = sample_fn or sample_refine_chunk stream_extractor = stream_extractor or extract_av_streams clone_model_fn = clone_model_fn or clone_model_for_chunk validate_refine_context_fn = validate_refine_context_fn or validate_refine_context adapt_group_conditioning_fn = ( adapt_group_conditioning_fn or adapt_group_conditioning ) captured_groups: Sequence[Mapping[str, Any]] | None = None context_warnings: list[str] = [] if refine_context is None: context_warnings.append( "WARNING: refine_context is not connected; using legacy prompt-only " "conditioning." ) else: typed_context = ( isinstance(refine_context, Mapping) and refine_context.get("magic") == REFINE_CONTEXT_MAGIC ) try: validated_context = validate_refine_context_fn( refine_context, assembly_plan=assembly_plan, ) except RefineContextError as exc: if typed_context: raise SecondPassContractError( f"refine_context contract is invalid: {exc}" ) from exc context_warnings.append( "WARNING: optional refine_context was not a typed Continuum context; " f"using legacy prompt-only conditioning ({exc})." ) else: if bool(validated_context.get("complete")): captured_groups = validated_context["groups"] else: context_warnings.append( "WARNING: refine_context capture is incomplete; using legacy " "prompt-only conditioning." ) refined_videos: list[dict[str, Any]] = [] group_seeds: list[int] = [] conditioning_sources: list[str] = [] report_lines = [ "H3 Continuum Second Pass V3.5", "Mode: context-aware physical-group refine when a complete First Pass " "refine_context is available.", f"Physical groups: {validation['physical_group_count']}.", "Sampling contract: video random noise/mask=1; audio zero noise/mask=0; " "workflow SIGMAS are applied directly by Core.", *context_warnings, ] for group_index, (video_latent, audio_latent, group) in enumerate( zip(video_latents, audio_latents, groups, strict=True) ): video_samples = _latent_samples(video_latent, name=f"video_latents[{group_index}]") audio_samples = _latent_samples(audio_latent, name=f"audio_latents[{group_index}]") captured_group = ( captured_groups[group_index] if captured_groups is not None else None ) model_group = captured_group if captured_group is not None else group adaptation_stats: Mapping[str, Any] | None = None context_conditioning_available = False if captured_group is not None: try: conditioning, adaptation_stats = adapt_group_conditioning_fn( captured_group, target_latent_h=validation["target_latent_h"], target_latent_w=validation["target_latent_w"], video_vae=video_vae, upscale_method=str(conditioning_upscale_method), ) conditioning_source = "refine_context" context_conditioning_available = True except RefineConditioningAdaptationError as exc: report_lines.append( f"WARNING: group {group_index + 1} refine_context target " f"adaptation was unavailable; using legacy prompt-only " f"conditioning ({exc})." ) except RefineContextError as exc: raise SecondPassContractError( f"refine_context group {group_index} is invalid: {exc}" ) from exc if not context_conditioning_available: prompt = str(group.get("physical_prompt", "")) conditioning = encode_prompt_fn( clip, prompt, first_image=None, last_image=None, reference_audio_assets=None, timeline_video_assets=None, ) conditioning_source = "prompt_only_fallback" logical_chunks = model_group.get("logical_chunks") if not isinstance(logical_chunks, Sequence) or not logical_chunks: logical_chunks = group.get("logical_chunks") if not isinstance(logical_chunks, Sequence) or not logical_chunks: raise SecondPassContractError( f"physical group {group_index} has no logical chunk identity" ) physical_clip_index = int( model_group.get("physical_clip_index", logical_chunks[0]) ) context_frames = int( model_group.get( "context_frames", group.get("trim_prefix_frames", 0), ) ) if physical_clip_index <= 0 or context_frames < 0: raise SecondPassContractError( f"physical group {group_index} MODEL context is invalid" ) chunk_model = clone_model_fn( model, strict=False, debug=False, chunk_index=physical_clip_index, context_frames=context_frames if context_frames > 0 else None, ) physical_seed = derive_refine_seed(int(refine_seed), group_index) group_seeds.append(physical_seed) conditioning_sources.append(conditioning_source) nested_latent = latent_builder(video_samples, audio_samples) sampled = sample_fn( model=chunk_model, conditioning=conditioning, latent=nested_latent, sampler=sampler, sigmas=sigmas, seed=physical_seed, enable_preview=bool(enable_preview), ) refined_video, _temporary_audio = stream_extractor(sampled) if tuple(refined_video.shape) != tuple(video_samples.shape): raise SecondPassContractError( f"refined video group {group_index} changed B/C/T/H/W geometry" ) if not bool(torch.isfinite(refined_video.float()).all().item()): raise SecondPassContractError( f"refined video group {group_index} contains NaN or Inf" ) output_latent = dict(video_latent) output_latent["samples"] = refined_video refined_videos.append(output_latent) report_lines.append( "group " f"{group_index + 1}: logical_chunks={group.get('logical_chunks')}, " f"prompt_policy={group.get('prompt_policy', 'unknown')}, " f"conditioning_source={conditioning_source}, " f"physical_clip_index={physical_clip_index}, " f"context_frames={context_frames}, " f"refine_seed={physical_seed}, shape={tuple(refined_video.shape)}, " "sampling_passes=1, temporary_audio_discarded=true" ) if adaptation_stats is not None: report_lines.append( "group " f"{group_index + 1} target conditioning: " f"keyframes_resized={int(adaptation_stats.get('keyframes_resized', 0))}, " f"keyframes_reencoded={int(adaptation_stats.get('keyframes_reencoded', 0))}, " f"context_refs_resized={int(adaptation_stats.get('context_refs_resized', 0))}" ) report_lines.extend( f"WARNING: {warning}" for warning in adaptation_stats.get("warnings", ()) ) passthrough_audio = passthrough_audio_latents(audio_latents) updated_plan = update_second_pass_geometry(assembly_plan, refined_videos) contract = updated_plan["second_pass_contract"] if conditioning_sources and all( source == "refine_context" for source in conditioning_sources ): contract["execution"] = "context_aware_physical_groups_audio_locked_v3" elif any(source == "refine_context" for source in conditioning_sources): contract["execution"] = "mixed_context_physical_groups_audio_locked_v3" else: contract["execution"] = "t2va_physical_groups_audio_locked_v2" contract["conditioning_sources"] = conditioning_sources contract["refine_seed_base"] = int(refine_seed) contract["refine_group_seeds"] = group_seeds contract["audio_output"] = "bit_exact_first_pass_passthrough" contract["audio_sampling"] = "zero_noise_mask_locked" report_lines.append( "Audio output: first-pass physical audio LATENT objects returned bit-exact; " "temporary refined audio discarded." ) return refined_videos, passthrough_audio, updated_plan, "\n".join(report_lines)