"""Assembly-plan contract for latent-first H3 Continuum V3.""" from __future__ import annotations from typing import Any import torch from ..state import validate_plan ASSEMBLY_PLAN_MAGIC = "H3_CONTINUUM_ASSEMBLY_PLAN" ASSEMBLY_PLAN_SCHEMA_VERSION = 1 FPS = 24 SECOND_PASS_CONTRACT_VERSION = 1 class AssemblyPlanError(ValueError): pass def make_assembly_plan( entries: list[dict[str, Any]], *, chunk_seconds: float, preserve_final_frame: bool, ) -> dict[str, Any]: if not entries: raise AssemblyPlanError("cannot create an assembly plan for an empty sequence") chunks: list[dict[str, Any]] = [] width = height = None for sequence_index, entry in enumerate(entries, start=1): if not isinstance(entry, dict): raise AssemblyPlanError(f"chunk {sequence_index} entry is not a dictionary") plan = validate_plan(entry.get("plan")) video = entry.get("video") audio = entry.get("audio") if not torch.is_tensor(video) or video.ndim < 3: raise AssemblyPlanError(f"chunk {sequence_index} video latent is invalid") if not torch.is_tensor(audio) or audio.ndim < 3: raise AssemblyPlanError(f"chunk {sequence_index} audio latent is invalid") plan_width = int(plan["width"]) plan_height = int(plan["height"]) if width is None: width, height = plan_width, plan_height elif (plan_width, plan_height) != (width, height): raise AssemblyPlanError("chunk dimensions changed within the sequence") chunks.append( { "sequence_index": sequence_index, "chunk_index": int(plan["clip_index"]), "total_frames": int(plan["total_frames"]), "trim_frames": int(plan["trim_frames"]), "net_frames": int(plan["net_frames"]), "context_frames": int(plan["context_frames"]), "expected_video_latent_t": int(video.shape[2]), "expected_audio_latent_t": int(audio.shape[-1]), } ) result = { "magic": ASSEMBLY_PLAN_MAGIC, "schema_version": ASSEMBLY_PLAN_SCHEMA_VERSION, "fps": FPS, "width": int(width), "height": int(height), "chunk_seconds": float(chunk_seconds), "target_frames": int(round(len(chunks) * float(chunk_seconds) * FPS)), "preserve_final_frame": bool(preserve_final_frame), "chunks": chunks, } return validate_assembly_plan(result) def validate_assembly_plan(plan: Any) -> dict[str, Any]: if not isinstance(plan, dict) or plan.get("magic") != ASSEMBLY_PLAN_MAGIC: raise AssemblyPlanError("invalid H3 Continuum V3 assembly plan") if ( type(plan.get("schema_version")) is not int or plan["schema_version"] != ASSEMBLY_PLAN_SCHEMA_VERSION ): raise AssemblyPlanError( f"unsupported assembly plan schema {plan.get('schema_version')!r}" ) if int(plan.get("fps", 0)) != FPS: raise AssemblyPlanError("assembly plan FPS must be 24") if int(plan.get("width", 0)) <= 0 or int(plan.get("height", 0)) <= 0: raise AssemblyPlanError("assembly plan dimensions are invalid") if float(plan.get("chunk_seconds", 0.0)) <= 0: raise AssemblyPlanError("assembly plan chunk duration is invalid") if int(plan.get("target_frames", 0)) <= 0: raise AssemblyPlanError("assembly plan target frame count is invalid") chunks = plan.get("chunks") if not isinstance(chunks, list) or not chunks: raise AssemblyPlanError("assembly plan contains no chunks") for expected_index, chunk in enumerate(chunks, start=1): if not isinstance(chunk, dict): raise AssemblyPlanError(f"assembly chunk {expected_index} is invalid") if int(chunk.get("sequence_index", 0)) != expected_index: raise AssemblyPlanError("assembly chunk order is not contiguous") total = int(chunk.get("total_frames", 0)) trim = int(chunk.get("trim_frames", -1)) net = int(chunk.get("net_frames", 0)) if total <= 0 or trim < 0 or net <= 0 or total - trim != net: raise AssemblyPlanError( f"assembly chunk {expected_index} frame plan is invalid" ) if int(chunk.get("context_frames", -1)) < 0: raise AssemblyPlanError( f"assembly chunk {expected_index} context is invalid" ) if int(chunk.get("expected_video_latent_t", 0)) <= 0: raise AssemblyPlanError( f"assembly chunk {expected_index} video latent length is invalid" ) if int(chunk.get("expected_audio_latent_t", 0)) <= 0: raise AssemblyPlanError( f"assembly chunk {expected_index} audio latent length is invalid" ) return plan # V3.0.1 hardening integration: redundant metadata plus fail-closed validation. from ..hardening import ( enrich_assembly_plan as _enrich_assembly_plan, validate_assembly_plan_contract as _validate_assembly_plan_contract, ) _make_assembly_plan_v300 = make_assembly_plan _validate_assembly_plan_v300 = validate_assembly_plan def validate_assembly_plan(plan): result = _validate_assembly_plan_v300(plan) _validate_assembly_plan_contract(plan) return result def make_assembly_plan(*args, **kwargs): plan = _make_assembly_plan_v300(*args, **kwargs) _enrich_assembly_plan(plan) validate_assembly_plan(plan) return plan def _recombine_terminal_tensor( first, second, *, slices, time_dim: int, name: str, ): """Invert the terminal logical split without changing any tensor value.""" import torch if not torch.is_tensor(first) or not torch.is_tensor(second): raise ValueError(f"terminal {name} entries must be tensors") if first.ndim != second.ndim: raise ValueError(f"terminal {name} tensor ranks differ") dim = int(time_dim) if dim < 0: dim += first.ndim if dim < 0 or dim >= first.ndim: raise ValueError(f"terminal {name} time dimension is invalid") for axis, (left, right) in enumerate(zip(first.shape, second.shape)): if axis != dim and int(left) != int(right): raise ValueError(f"terminal {name} tensor geometry differs") (first_start, first_stop), (second_start, second_stop) = slices first_start = int(first_start) first_stop = int(first_stop) second_start = int(second_start) second_stop = int(second_stop) if first_start != 0 or second_start > first_stop or second_stop <= first_stop: raise ValueError(f"terminal {name} split ranges do not form one physical unit") if int(first.shape[dim]) != first_stop - first_start: raise ValueError(f"terminal {name} first slice length is inconsistent") if int(second.shape[dim]) != second_stop - second_start: raise ValueError(f"terminal {name} second slice length is inconsistent") overlap_start = max(first_start, second_start) overlap_stop = min(first_stop, second_stop) overlap_length = max(0, overlap_stop - overlap_start) if overlap_length: first_overlap = first.narrow(dim, overlap_start - first_start, overlap_length) second_overlap = second.narrow(dim, overlap_start - second_start, overlap_length) if not torch.equal(first_overlap, second_overlap): raise ValueError( f"terminal {name} overlap differs; refusing lossy physical reconstruction" ) output_shape = list(first.shape) output_shape[dim] = second_stop output = first.new_empty(output_shape) output.narrow(dim, first_start, first_stop - first_start).copy_(first) output.narrow(dim, second_start, second_stop - second_start).copy_(second) return output.contiguous() def _terminal_physical_prompt( prompts: list[str], *, chunk_seconds: float, ) -> tuple[str, str]: """Reproduce the established terminal-pair prompt without reparsing it later.""" first, second = prompts if first == second: return first, "shared_prompt_v1" split = f"{float(chunk_seconds):g}" stop = f"{float(chunk_seconds) * 2:g}" return ( f"[0-{split}s]\n{first}\n\n[{split}-{stop}s]\n{second}", "paired_timeline_v1", ) def _attach_second_pass_contract( plan: dict[str, Any], *, logical_entries: list[dict[str, Any]], physical_entries: list[dict[str, Any]], chunk_seconds: float, ) -> None: """Attach additive V3.5 metadata without changing V3.4 generation semantics.""" decode_groups = plan.get("decode_groups") if not isinstance(decode_groups, list): decode_groups = [ { "logical_chunk_indices": [index + 1], "terminal_merged": False, "total_frames": plan["chunks"][index]["total_frames"], "trim_frames": plan["chunks"][index]["trim_frames"], } for index in range(len(physical_entries)) ] groups: list[dict[str, Any]] = [] for group_id, (entry, decode_group) in enumerate( zip(physical_entries, decode_groups, strict=True) ): video = entry["video"] audio = entry["audio"] logical_chunks = [int(value) for value in decode_group["logical_chunk_indices"]] prompts = [str(logical_entries[index - 1].get("prompt", "")) for index in logical_chunks] if len(prompts) == 1: physical_prompt = prompts[0] prompt_policy = "single" elif len(prompts) == 2 and bool(decode_group.get("terminal_merged")): physical_prompt, prompt_policy = _terminal_physical_prompt( prompts, chunk_seconds=chunk_seconds, ) else: physical_prompt = "\n\n".join(prompts) prompt_policy = "physical_group_v1" groups.append( { "group_id": group_id, "logical_chunks": logical_chunks, "physical_prompt": physical_prompt, "prompt_policy": prompt_policy, "physical_frames": int(decode_group["total_frames"]), "trim_prefix_frames": int(decode_group["trim_frames"]), "terminal_merged": bool(decode_group.get("terminal_merged", False)), "source_width": int(plan["width"]), "source_height": int(plan["height"]), "source_batch": int(video.shape[0]), "latent_channels": int(video.shape[1]), "source_latent_t": int(video.shape[2]), "source_latent_h": int(video.shape[3]), "source_latent_w": int(video.shape[4]), "source_audio_shape": [int(value) for value in audio.shape], } ) plan["second_pass_contract"] = { "version": SECOND_PASS_CONTRACT_VERSION, "physical_groups": groups, } def prepare_physical_decode_entries( entries, *, chunk_seconds: float, preserve_final_frame: bool, terminal_merged: bool, ): """Return external-VAE decode units while preserving logical plan metadata.""" logical_entries = list(entries) plan = make_assembly_plan( logical_entries, chunk_seconds=float(chunk_seconds), preserve_final_frame=bool(preserve_final_frame), ) if not terminal_merged: _attach_second_pass_contract( plan, logical_entries=logical_entries, physical_entries=logical_entries, chunk_seconds=float(chunk_seconds), ) return logical_entries, plan if len(logical_entries) < 2: raise ValueError("terminal physical decode requires two logical entries") from ..v2.sequence import _terminal_pair_contract initial_pair = len(logical_entries) == 2 contract = _terminal_pair_contract( initial_pair=initial_pair, chunk_seconds=float(chunk_seconds), ) first_entry = logical_entries[-2] second_entry = logical_entries[-1] physical_video = _recombine_terminal_tensor( first_entry["video"], second_entry["video"], slices=contract["video_slices"], time_dim=2, name="video", ) physical_audio = _recombine_terminal_tensor( first_entry["audio"], second_entry["audio"], slices=contract["audio_slices"], time_dim=-1, name="audio", ) physical_entry = dict(first_entry) physical_entry["video"] = physical_video physical_entry["audio"] = physical_audio decode_entries = [*logical_entries[:-2], physical_entry] logical_chunks = list(plan["chunks"]) decode_groups = [] for chunk in logical_chunks[:-2]: group = dict(chunk) group["logical_chunk_indices"] = [int(chunk["chunk_index"])] group["terminal_merged"] = False decode_groups.append(group) first_chunk = logical_chunks[-2] second_chunk = logical_chunks[-1] frame_start = int(first_chunk.get("frame_start", 0)) net_frames = int(contract["physical_frames"]) - int( contract["physical_context_frames"] ) terminal_group = dict(first_chunk) terminal_group.update( { "total_frames": int(contract["physical_frames"]), "trim_frames": int(contract["physical_context_frames"]), "net_frames": net_frames, "context_frames": int(contract["physical_context_frames"]), "expected_video_latent_t": int(physical_video.shape[2]), "expected_audio_latent_t": int(physical_audio.shape[-1]), "frame_start": frame_start, "frame_stop": frame_start + net_frames, "logical_chunk_indices": [ int(first_chunk["chunk_index"]), int(second_chunk["chunk_index"]), ], "terminal_merged": True, } ) decode_groups.append(terminal_group) plan = dict(plan) plan["decode_group_version"] = 1 plan["logical_chunk_count"] = len(logical_chunks) plan["physical_decode_group_count"] = len(decode_groups) plan["decode_groups"] = decode_groups _attach_second_pass_contract( plan, logical_entries=logical_entries, physical_entries=decode_entries, chunk_seconds=float(chunk_seconds), ) validate_assembly_plan(plan) return decode_entries, plan