#!/usr/bin/env python3 """Gate for ComfyUI-Easy-Media MultiTrack plans: outline, task segments, TRACK_DATA, patch plan. The validator mirrors every check that the node pack's own `skills/easy-media-multitrack-workflow/scripts/patch_workflow.py` performs at apply time (ids, ordering, overlap, frame ranges, media sources, image counts, audio locks, shared references, resolution combos, project fields), so a plan that passes here cannot be rejected there for schema reasons. On top it enforces the gates that upstream leaves to discipline: * outline pins — each segment's id, start/end frames, task_mode, continuity_mode and reference-image set must match the approved outline row; media `file_path` strings must be character-for-character copies of the outline's media_inventory entries (the same verbatim contract the h3-plan-gate enforces for refmods); * context prompt rules — self-contained prompts (no "same as before" references), keep-then-change openers for context/context_drift joins, end-in-motion tails when more context segments follow; * drift uniformity — when any task segment is context_drift, all are, with the contiguous 10-second split unless the user pinned lengths. Sub-commands: (no args) embedded self-test suite outline OUTLINE.json validate the timeline guide segment SEGMENT_NN.json --index N --total T --outline OUTLINE.json [--prev PREV.json] trackdata TRACK_DATA.json [--outline OUTLINE.json] plan PLAN.json [--outline OUTLINE.json] override PROMPT_OVERRIDE.json --outline OUTLINE.json validate the minimax_prompt_override paste payload for the multitrack editor node suite embedded self-test suite Exit code 0 = pass, 1 = fail. Standard library only. """ from __future__ import annotations import json import re import sys from pathlib import Path from typing import Any TRACK_TYPES = {"task", "video", "audio", "subtitle"} TASK_MODES = {"default", "l2v", "ref", "edit"} CONTINUITY_MODES = {"shot", "context", "context_drift"} CONTINUITY_JOIN_MODES = {"context", "context_drift"} REF_IMAGE_SIZES = {"match", "max"} PROMPT_VARIANTS = {"a", "b"} SOURCE_TYPES = {"input", "output", "local", "url", "slot"} SOURCE_FIELD = { "input": "file_path", "output": "file_path", "local": "local_path", "url": "url", "slot": "slot_name", } MEDIA_KINDS = {"image", "audio", "video"} RESIZE_METHODS = { "stretch", "resize", "pad", "pad (white)", "pad_edge", "pad_edge_pixel", "crop", "pillarbox_blur", } ASPECT_RATIOS = { "1:1 (Square)", "2:3 (Portrait Photo)", "3:2 (Photo)", "3:4 (Portrait Standard)", "4:3 (Standard)", "9:16 (Portrait Widescreen)", "16:9 (Widescreen)", "21:9 (Ultrawide)", } PROJECT_FIELDS = { "project_name", "project_save", "segment_start_number", "segment_count", "seed", "control_after_generate", "sampling_plan", "sampling_mode", "1st_pass_only", "disable_2nd_noise", "upscale_by", "upscale_model", } EDITOR_PLAN_FIELDS = {"node_id", "track_data", "format", "resolution", "recalculate_total_length"} SNAKE_RE = re.compile(r"^[a-z][a-z0-9_]*$") # The multitrack editor's prompt_override input (format MiniMax) accepts exactly one JSON # payload type. Anything else falls back to the '|'-separated text parser and renders ONE # clip over the whole timeline — the classic single-clip failure. OVERRIDE_TYPE = "minimax_prompt_override" OVERRIDE_VERSION = 1 OVERRIDE_GEN_TYPES = {"r2v", "t2v", "i2v", "v2v", "l2v"} OVERRIDE_DURATION_MIN = 2.0 OVERRIDE_DURATION_MAX = 15.0 OVERRIDE_FIELDS = {"type", "version", "prompts", "duration", "generation_type", "continuity_mode", "system_prompt", "video_track_lock", "audio_track_lock"} _TASK_MODE_TO_GEN = {"ref": "r2v", "l2v": "l2v", "default": "t2v"} _PICTURE_RE = re.compile(r"", re.IGNORECASE) _AUDIO_RE = re.compile(r"", re.IGNORECASE) _VIDEO_RE = re.compile(r"", re.IGNORECASE) _ATREF_RE = re.compile(r"@(?:image|img|audio|video|\u56fe\u7247|\u56fe|\u97f3\u9891|\u89c6\u9891)\s*\d+", re.IGNORECASE) MAX_IMAGES = 9 PROMPT_MIN_WORDS = 60 END_STATE_MIN_WORDS = 15 OPEN_WINDOW = 240 # chars inspected for keep/cut rules at the prompt start TAIL_WINDOW = 240 # chars inspected for the end-in-motion rule at the prompt end # A task segment renders standalone: the model never sees any other segment's prompt. BANNED_SELFREF = [ "same as before", "the same as before", "as before", "as mentioned", "as above", "same as above", "previous shot", "previous segment", "previous scene", "previous clip", "previous frame", "previous prompt", "the last shot", "the last segment", "the last scene", "the last clip", "the last frame", "same as the previous", "like the previous", "identical to the previous", "same character as", "同上", "和之前一样", "上一段", "上一镜头", ] # Context/drift joins must open by keeping the delivered tail, not by restating a plan. KEEP_TOKENS = [ "hold", "keep", "continu", "maintain", "carry", "resume", "unchanged", "same direction", "same framing", "same pose", "same speed", "same light", "steady", "incoming", "arrives with", "already in", ] # New compositions belong in `shot` segments, not in the opening of a context join. CUT_TOKENS_OPEN = [ "cut to", "cuts to", "hard cut", "smash cut", "jump cut", "new angle", "new shot", "new scene", "new composition", "new setup", ] # A context join that is followed by another context join must not end its motion. REST_TOKENS_TAIL = [ "comes to rest", "comes to a stop", "comes to a complete stop", "comes to a halt", "freezes in place", "holds still", "stops moving", "motionless", "stands still", "lies still", "sits still", "slows to a stop", "slows to a halt", "grinds to a halt", "ends on a held frame", "freezes the frame", "falls asleep", "settles into stillness", ] class Fail(Exception): """A validation failure with an actionable message.""" def load_json(path: str | Path, label: str) -> dict[str, Any]: try: value = json.loads(Path(path).read_text(encoding="utf-8")) except OSError as exc: raise Fail(f"cannot read {label} {path}: {exc}") from exc except json.JSONDecodeError as exc: raise Fail(f"{label} {path} is not valid JSON: {exc}") from exc if not isinstance(value, dict): raise Fail(f"{label} must be a JSON object: {path}") return value def is_int(value: Any) -> bool: return isinstance(value, int) and not isinstance(value, bool) def require_snake(value: Any, where: str) -> str: if not isinstance(value, str) or not SNAKE_RE.fullmatch(value): raise Fail(f"{where} must be lowercase snake_case (letters, digits, underscores): {value!r}") return value def word_count(text: str) -> int: return len(text.split()) # ---------------------------------------------------------------- resolution def validate_resolution(value: Any, where: str) -> dict[str, Any]: if isinstance(value, str): patch: dict[str, Any] = {"resolution": value} elif isinstance(value, dict): patch = dict(value) else: raise Fail(f"{where} must be a string or an object") allowed = {"resolution", "resize_method", "resize_to_pixel", "width", "height", "aspect_ratio", "megapixels"} unknown = sorted(set(patch) - allowed) if unknown: raise Fail(f"{where} has unsupported fields {unknown}; allowed: {sorted(allowed)}") label = patch.get("resolution") if not isinstance(label, str) or not label: raise Fail(f"{where}.resolution must be a non-empty string label") def reject_unused(expected: set[str]) -> None: unused = sorted(set(patch) - {"resolution"} - expected) if unused: raise Fail(f"resolution option {label!r} does not use fields {unused}") def check_method() -> str: method = patch.get("resize_method", "stretch") if method not in RESIZE_METHODS: raise Fail(f"{where}.resize_method {method!r} not in {sorted(RESIZE_METHODS)}") return method if label == "width x height (custom)": reject_unused({"width", "height", "resize_method"}) for field in ("width", "height"): dim = patch.get(field) if not is_int(dim) or dim < 64 or dim > 8096: raise Fail(f"{where}.{field} must be an integer from 64 to 8096") check_method() elif label in {"width x height (shortest)", "width x height (longest)"}: reject_unused({"resize_to_pixel", "resize_method"}) pixels = patch.get("resize_to_pixel") if not is_int(pixels) or pixels < 64 or pixels > 8096: raise Fail(f"{where}.resize_to_pixel must be an integer from 64 to 8096") check_method() elif label == "width x height (megapixels)": reject_unused({"aspect_ratio", "megapixels"}) aspect = patch.get("aspect_ratio") mp = patch.get("megapixels") if aspect not in ASPECT_RATIOS: raise Fail( f"{where}.aspect_ratio must be the exact full token, one of " f"{sorted(ASPECT_RATIOS)}; got {aspect!r} (plain '16:9' is a rewrite — " "copy the token verbatim from the outline)" ) if not isinstance(mp, (int, float)) or isinstance(mp, bool) or not 0.1 <= float(mp) <= 16.0: raise Fail(f"{where}.megapixels must be a number from 0.1 to 16.0") else: reject_unused({"resize_method"}) is_auto = label == "width x height (auto)" is_fixed = re.fullmatch(r"\s*\d+\s*x\s*\d+\s*\([^()]+\)\s*", label) is not None if not is_auto and not is_fixed: raise Fail(f"{where}.resolution label {label!r} is not a supported option") check_method() return patch # ------------------------------------------------------------ media sources def validate_media_source(content: dict[str, Any], where: str, kinds: set[str]) -> str: media_type = content.get("media_type") if media_type not in kinds: raise Fail(f"{where}.content.media_type must be one of {sorted(kinds)}; got {media_type!r}") source_type = content.get("source_type") if source_type not in SOURCE_TYPES: raise Fail(f"{where}.content.source_type must be one of {sorted(SOURCE_TYPES)}; got {source_type!r}") field = SOURCE_FIELD[source_type] value = content.get(field) if not isinstance(value, str) or not value.strip(): raise Fail( f"{where}.content.source_type {source_type!r} requires a non-empty " f"`{field}` field (the path field must match the source type)" ) if source_type in {"input", "output", "local"} and value.startswith(("/", "~")): raise Fail( f"{where}.content.{field} must be the relative path returned by the upload " f"API (like codex/session/file.mp4), not a machine-absolute path: {value!r}" ) return str(value) # ------------------------------------------------------------ prompt rules def prompt_rules(user_prompt: str, continuity_mode: str, followed_by_join: bool, where: str) -> None: if not isinstance(user_prompt, str) or not user_prompt.strip(): raise Fail(f"{where}.content.user_prompt must be a non-empty string") text = " ".join(user_prompt.split()) lowered = text.lower() words = word_count(text) if words < PROMPT_MIN_WORDS: raise Fail( f"{where}.content.user_prompt is too thin ({words} words; floor {PROMPT_MIN_WORDS}). " "Compose the segment, do not summarize: subject anchor with its look, blocking, " "one camera idea, ordered body-mechanics motion, physical texture, exit state." ) for token in BANNED_SELFREF: if token in lowered: raise Fail( f"{where}.content.user_prompt references another segment ({token!r}). Each task " "segment renders standalone — the model never sees any other prompt. Fully " "restate scene, light and subject identity inside this prompt." ) if continuity_mode in CONTINUITY_JOIN_MODES: opener = lowered[:OPEN_WINDOW] if not any(token in opener for token in KEEP_TOKENS): raise Fail( f"{where}.content.user_prompt must open by keeping the delivered tail " f"(one of {KEEP_TOKENS[:8]} ... in the first ~{OPEN_WINDOW} characters). " "Context joins start from the previous segment's real last frames: keep " "camera direction, pose and light first; put every change later." ) for token in CUT_TOKENS_OPEN: if token in opener: raise Fail( f"{where}.content.user_prompt opens with a new composition ({token!r}). " "A context join keeps first and changes later (changes from ~00:02, " "written as an explicit cut); for a genuinely new composition use a " "`shot` segment." ) if followed_by_join: tail = lowered[-TAIL_WINDOW:] for token in REST_TOKENS_TAIL: if token in tail: raise Fail( f"{where}.content.user_prompt ends in rest ({token!r}) but another " "context segment follows. End in motion — the next join opens inside " "this segment's real last frames." ) # ----------------------------------------------------------------- outline def _validate_media_inventory(outline: dict[str, Any]) -> dict[str, dict[str, Any]]: rows = outline.get("media_inventory") if not isinstance(rows, list): raise Fail( "outline.media_inventory must be an array of media rows — use [] for a pure " "t2v story with no media at all (no picture tokens may then appear in prompts)") inventory: dict[str, dict[str, Any]] = {} for i, row in enumerate(rows): where = f"media_inventory[{i}]" if not isinstance(row, dict): raise Fail(f"{where} must be an object") key = row.get("key") if not isinstance(key, str) or not re.fullmatch(r"^[A-Z][A-Z0-9_]*$", key): raise Fail(f"{where}.key must be an UPPERCASE key (like POSE_REF): {key!r}") if key in inventory: raise Fail(f"duplicate media_inventory key: {key}") kind = row.get("kind") if kind not in MEDIA_KINDS: raise Fail(f"{where}.kind must be one of {sorted(MEDIA_KINDS)}; got {kind!r}") path = validate_media_source( {"media_type": kind, "source_type": row.get("source_type", "input"), **{k: v for k, v in row.items() if k in {"file_path", "local_path", "url", "slot_name"}}}, where, {kind}, ) entry = {"kind": kind, "source_type": row.get("source_type", "input"), "path": path} name = row.get("file_name") if name is not None: if not isinstance(name, str) or not name.strip(): raise Fail(f"{where}.file_name must be a non-empty string when present") entry["file_name"] = name inventory[key] = entry return inventory def _validate_track_roles(outline: dict[str, Any], inventory: dict[str, dict[str, Any]]) -> dict[str, Any]: tracks = outline.get("tracks") if not isinstance(tracks, dict): raise Fail("outline.tracks must be an object with master_audio / reference_video / extra_tracks") roles: dict[str, Any] = {"master_audio": None, "reference_video": None, "extra_tracks": []} for role, kind in (("master_audio", "audio"), ("reference_video", "video")): spec = tracks.get(role) if spec is None: continue if not isinstance(spec, dict): raise Fail(f"outline.tracks.{role} must be an object or null") key = spec.get("key") if key not in inventory: raise Fail(f"outline.tracks.{role}.key {key!r} is not a media_inventory key") if inventory[key]["kind"] != kind: raise Fail( f"outline.tracks.{role}.key {key!r} is a {inventory[key]['kind']} row; " f"the {role} role needs a {kind} row" ) if spec.get("lock") is not True: raise Fail( f"outline.tracks.{role}.lock must be true: this gate only builds tracks that " "drive generation; ordinary background media does not belong in the plan" ) name = spec.get("name", "Master Audio" if role == "master_audio" else "Reference Video") roles[role] = {"key": key, "name": name} extra = tracks.get("extra_tracks", []) if extra != []: raise Fail("outline.tracks.extra_tracks must be [] in this gate version") return roles def _validate_project(project: Any) -> dict[str, Any]: if not isinstance(project, dict): raise Fail("outline.project must be an object") unknown = sorted(set(project) - ({"node_id"} | PROJECT_FIELDS)) if unknown: raise Fail(f"outline.project has unsupported fields {unknown}") if project.get("project_save") not in {"new", "override"}: raise Fail("outline.project.project_save must be 'new' or 'override'") start = project.get("segment_start_number", 1) if not is_int(start) or start < 1: raise Fail("outline.project.segment_start_number must be a positive integer (1-based)") count = project.get("segment_count", -1) if not is_int(count) or count < -1: raise Fail("outline.project.segment_count must be -1 or a non-negative integer") mode = project.get("sampling_mode", "single") if mode not in {"single", "dual"}: raise Fail("outline.project.sampling_mode must be 'single' or 'dual'") plan = project.get("sampling_plan") if not isinstance(plan, str) or not plan.strip(): raise Fail("outline.project.sampling_plan must be a non-empty preset name (e.g. 'medium')") if "upscale_by" in project: up = project["upscale_by"] if not isinstance(up, (int, float)) or isinstance(up, bool) or up <= 0: raise Fail("outline.project.upscale_by must be a positive number") if round(float(up), 3) != float(up): raise Fail("outline.project.upscale_by keeps three decimals (step 0.001)") for flag in ("1st_pass_only", "disable_2nd_noise"): if flag in project and not isinstance(project[flag], bool): raise Fail(f"outline.project.{flag} must be a boolean") if "seed" in project and not is_int(project["seed"]): raise Fail("outline.project.seed must be an integer") return project def outline_frames(outline: dict[str, Any]) -> list[dict[str, Any]]: """Return the outline rows with computed start_frame/end_frame and joined flags.""" fps = outline.get("defaults", {}).get("frame_rate") rows = outline.get("segments", []) out: list[dict[str, Any]] = [] for i, row in enumerate(rows): start_s = float(row["start_seconds"]) dur_s = float(row["duration_seconds"]) start_f = round(start_s * fps) end_f = start_f + round(dur_s * fps) joined_after = any( r["continuity_mode"] in CONTINUITY_JOIN_MODES for r in rows[i + 1:] ) out.append({**row, "start_frame": start_f, "end_frame": end_f, "followed_by_join": joined_after}) return out def validate_outline(obj: dict[str, Any]) -> dict[str, Any]: if obj.get("title") is None or not SNAKE_RE.fullmatch(str(obj.get("title"))): raise Fail("outline.title must be lowercase snake_case") editor = obj.get("editor") if not isinstance(editor, dict): raise Fail("outline.editor must be an object") fmt = editor.get("format") if not isinstance(fmt, str) or not fmt.strip(): raise Fail("outline.editor.format must be a non-empty string (the editor's format pack, e.g. 'MiniMax')") if "resolution" not in editor: raise Fail("outline.editor.resolution is required (the DynamicCombo setting)") validate_resolution(editor["resolution"], "outline.editor.resolution") defaults = obj.get("defaults") if not isinstance(defaults, dict): raise Fail("outline.defaults must be an object") fps = defaults.get("frame_rate") if not is_int(fps) or fps < 1: raise Fail("outline.defaults.frame_rate must be a positive integer") seg_s = defaults.get("segment_seconds", 10) if not isinstance(seg_s, (int, float)) or isinstance(seg_s, bool) or seg_s <= 0: raise Fail("outline.defaults.segment_seconds must be a positive number") inventory = _validate_media_inventory(obj) _validate_track_roles(obj, inventory) _validate_project(obj.get("project")) rows = obj.get("segments") if not isinstance(rows, list) or not rows: raise Fail("outline.segments must be a non-empty array of segment rows") ids: set[str] = set() pinned = obj.get("lengths_user_pinned") is True drift_rows = 0 cursor = 0.0 for i, row in enumerate(rows): where = f"segments[{i}]" if not isinstance(row, dict): raise Fail(f"{where} must be an object") if row.get("index") != i + 1: raise Fail(f"{where}.index must be {i + 1} (contiguous, 1-based)") seg_id = require_snake(row.get("id"), f"{where}.id") if seg_id in ids: raise Fail(f"duplicate segment id: {seg_id}") ids.add(seg_id) start_s = row.get("start_seconds") dur_s = row.get("duration_seconds") if not isinstance(start_s, (int, float)) or isinstance(start_s, bool) or start_s < 0: raise Fail(f"{where}.start_seconds must be a non-negative number") if not isinstance(dur_s, (int, float)) or isinstance(dur_s, bool) or dur_s < 1: raise Fail(f"{where}.duration_seconds must be a number >= 1") if abs(float(start_s) - cursor) > 1e-6: raise Fail( f"{where}.start_seconds is {start_s} but the timeline cursor is {cursor} " "(previous start + duration + gap_after_seconds). Keep the rows cumulative." ) cursor = float(start_s) + float(dur_s) if row.get("task_mode") not in TASK_MODES: raise Fail(f"{where}.task_mode must be one of {sorted(TASK_MODES)}") cm = row.get("continuity_mode") if cm not in CONTINUITY_MODES: raise Fail(f"{where}.continuity_mode must be one of {sorted(CONTINUITY_MODES)}; " "write 'context_drift' (the legacy 'context_swap' is not accepted in new plans)") if cm == "context_drift": drift_rows += 1 beat = row.get("beat") if not isinstance(beat, str) or word_count(beat) < 6: raise Fail(f"{where}.beat must say in one sentence what happens AND where the segment ends") brief = row.get("prompt_brief") if not isinstance(brief, str) or word_count(brief) < 6: raise Fail(f"{where}.prompt_brief must sketch the prompt's keep/change plan in 1-2 sentences") images = row.get("images", []) if not isinstance(images, list): raise Fail(f"{where}.images must be an array") if len(images) > MAX_IMAGES: raise Fail(f"{where}.images holds {len(images)} items; the schema allows at most {MAX_IMAGES} per task") seen_keys: set[str] = set() for j, img in enumerate(images): img_where = f"{where}.images[{j}]" if not isinstance(img, dict) or img.get("key") not in inventory: raise Fail(f"{img_where}.key must be a media_inventory key") key = img["key"] if key in seen_keys: raise Fail(f"{img_where} repeats media key {key}") seen_keys.add(key) if inventory[key]["kind"] != "image": raise Fail(f"{img_where}.key {key} is a {inventory[key]['kind']} row; task images need image rows") if "shared_reference" in img and not isinstance(img["shared_reference"], bool): raise Fail(f"{img_where}.shared_reference must be a boolean") gap = row.get("gap_after_seconds", 0) if not isinstance(gap, (int, float)) or isinstance(gap, bool) or gap < 0: raise Fail(f"{where}.gap_after_seconds must be a non-negative number") cursor += float(gap) if drift_rows and drift_rows != len(rows): offenders = [r["id"] for r in rows if r.get("continuity_mode") != "context_drift"] raise Fail( "context_drift is all-or-nothing: every task segment in scope carries " f"context_drift (the first one included), but {offenders} do not. Set all rows " "to context_drift — or none of them." ) if drift_rows and not pinned: expected = float(defaults.get("segment_seconds", 10)) off = [f"{r['id']}={r['duration_seconds']}" for r in rows if abs(float(r["duration_seconds"]) - expected) > 1e-6] if off: raise Fail( "context_drift without user-pinned lengths splits the task range into " f"consecutive {expected:g}s pieces (the last takes the remainder, no padding). " f"These rows deviate: {off}. Set lengths_user_pinned=true only if the user " "actually specified the lengths." ) if drift_rows: for i in range(1, len(rows)): prev, cur = rows[i - 1], rows[i] expected_start = float(prev["start_seconds"]) + float(prev["duration_seconds"]) \ + float(prev.get("gap_after_seconds", 0)) if abs(float(cur["start_seconds"]) - expected_start) > 1e-6: raise Fail( f"context_drift splits are consecutive: segments[{i}].start_seconds must be " f"{expected_start:g} (previous start + duration + gap), got {cur['start_seconds']}" ) obj["inventory"] = inventory obj["_roles"] = _validate_track_roles(obj, inventory) obj["rows"] = outline_frames(obj) return obj # ---------------------------------------------------------------- fragment def _validate_task_images(images: Any, where: str, outline: dict[str, Any] | None) -> list[str]: if not isinstance(images, list): raise Fail(f"{where}.content.images must be an array") if len(images) > MAX_IMAGES: raise Fail(f"{where}.content.images holds {len(images)} items; at most {MAX_IMAGES} is allowed") paths: list[str] = [] for j, img in enumerate(images): img_where = f"{where}.content.images[{j}]" if not isinstance(img, dict): raise Fail(f"{img_where} must be an object") if "shared_reference" in img and not isinstance(img["shared_reference"], bool): raise Fail(f"{img_where}.shared_reference must be a boolean") if "key" in img: raise Fail(f"{img_where} must not carry the outline's `key` field — copy the real " "file_path from the media_inventory row instead") path = validate_media_source( {"media_type": "image", "source_type": img.get("source_type", "input"), **{k: v for k, v in img.items() if k in {"file_path", "local_path", "url", "slot_name"}}}, img_where, {"image"}, ) if outline is not None: inv = outline["inventory"] matches = [k for k, v in inv.items() if v["kind"] == "image" and v["path"] == path] if not matches: nearest = min( (v["path"] for v in inv.values() if v["kind"] == "image"), default="", key=lambda p: _distance(p, path), ) raise Fail( f"{img_where}.file_path {path!r} is not a verbatim copy of any outline " f"media_inventory image path (closest: {nearest!r}). Open outline.json, " "select the exact file_path text, copy, paste — never retype it." ) paths.append(path) return paths def _distance(a: str, b: str) -> int: """Cheap similarity proxy for the error hint (absolute difference in shared prefix).""" i = 0 for ca, cb in zip(a, b): if ca != cb: break i += 1 return len(a) + len(b) - 2 * i def _validate_task_content(content: dict[str, Any], where: str, outline: dict[str, Any] | None, followed_by_join: bool) -> None: if not isinstance(content, dict): raise Fail(f"{where}.content must be an object") if "media_type" in content and content["media_type"] != "none": raise Fail(f"{where}.content.media_type must be 'none' on a task segment") if content.get("task_mode") not in TASK_MODES: raise Fail(f"{where}.content.task_mode must be one of {sorted(TASK_MODES)}") cm = content.get("continuity_mode") if cm not in CONTINUITY_MODES: raise Fail( f"{where}.content.continuity_mode must be one of {sorted(CONTINUITY_MODES)}; " "write 'context_drift' (the legacy 'context_swap' is not accepted in new plans)" ) if "ref_image_size" in content and content["ref_image_size"] not in REF_IMAGE_SIZES: raise Fail(f"{where}.content.ref_image_size must be 'match' or 'max'") if "user_prompt_variant" in content and content["user_prompt_variant"] not in PROMPT_VARIANTS: raise Fail(f"{where}.content.user_prompt_variant must be 'a' or 'b'") for field in ("user_prompt", "system_prompt", "user_prompt_b"): if field in content and not isinstance(content[field], str): raise Fail(f"{where}.content.{field} must be a string") if not isinstance(content.get("muted", False), bool) or not isinstance(content.get("volume_db", 0), (int, float)): raise Fail(f"{where}.content.muted must be a boolean and volume_db a number") _validate_task_images(content.get("images", []), where, outline) prompt_field = "user_prompt_b" if content.get("user_prompt_variant") == "b" else "user_prompt" prompt_rules(content.get(prompt_field, ""), cm, followed_by_join, where) def validate_fragment(obj: dict[str, Any], index: int = 1, total: int | None = None, prev: dict[str, Any] | None = None, outline: dict[str, Any] | None = None) -> dict[str, Any]: if not isinstance(obj, dict): raise Fail("segment fragment must be a JSON object") if total is not None and outline is not None and total != len(outline["rows"]): raise Fail(f"--total {total} does not match the outline's {len(outline['rows'])} segment rows") if outline is not None and not 1 <= index <= len(outline["rows"]): raise Fail(f"--index {index} is outside the outline's 1..{len(outline['rows'])} rows") seg_id = require_snake(obj.get("id"), "fragment.id") start = obj.get("start_frame") end = obj.get("end_frame") if not is_int(start) or start < 0: raise Fail("fragment.start_frame must be a non-negative integer") if not is_int(end) or end <= start: raise Fail("fragment.end_frame must be an integer greater than start_frame " "(start_frame inclusive, end_frame exclusive)") row: dict[str, Any] | None = None if outline is not None: row = outline["rows"][index - 1] if seg_id != row["id"]: raise Fail(f"fragment.id {seg_id!r} does not match the approved outline row " f"{index} id {row['id']!r} — ids are never silently altered") if start != row["start_frame"] or end != row["end_frame"]: raise Fail( f"fragment frames [{start}, {end}) do not match the approved outline row " f"[{row['start_frame']}, {row['end_frame']}) " f"(row start_seconds {row['start_seconds']} + duration_seconds " f"{row['duration_seconds']} at {outline['defaults']['frame_rate']} fps). " "The approved guide is the contract; fix the fragment, or revise the outline first." ) if obj.get("content", {}).get("task_mode") not in (None, row["task_mode"]): raise Fail(f"outline pins segment {seg_id} as task_mode {row['task_mode']!r}; " f"the fragment says {obj['content']['task_mode']!r}") if obj.get("content", {}).get("continuity_mode") not in (None, row["continuity_mode"]): raise Fail(f"outline pins segment {seg_id} as continuity_mode {row['continuity_mode']!r}; " f"the fragment says {obj['content']['continuity_mode']!r}") _validate_task_content(obj.get("content", {}), "fragment", outline, bool(row and row["followed_by_join"])) if outline is not None and row is not None: content = obj["content"] frag_paths = _validate_task_images(content.get("images", []), "fragment", outline) row_keys = [img["key"] for img in row.get("images", [])] row_paths = [outline["inventory"][k]["path"] for k in row_keys] if frag_paths != row_paths: raise Fail( f"fragment image order/set {frag_paths} does not match the approved outline " f"row {row_paths} — carry exactly the pinned references in the pinned order " "(image order defines the picture-reference order)" ) handoff = obj.get("_handoff") if not isinstance(handoff, dict): raise Fail("fragment._handoff must be an object with an end_state") end_state = handoff.get("end_state") if not isinstance(end_state, str) or word_count(end_state) < END_STATE_MIN_WORDS: raise Fail( f"fragment._handoff.end_state must describe the real final frame in at least " f"{END_STATE_MIN_WORDS} words (pose, motion in progress, camera state) — the next " "context join opens inside these frames" ) if prev is not None: prev_end = prev.get("end_frame") if is_int(prev_end) and start != prev_end and (outline is None or _row_gap(outline, index) == 0): raise Fail( f"fragment starts at frame {start} but the previous segment ends at {prev_end}. " "Task segments of one chain are consecutive: [0,N), [N,2N), ... — never an " "extra frame at the boundary, no overlap." ) return obj def _row_gap(outline: dict[str, Any], index: int) -> float: if index < 2 or index > len(outline["rows"]): return 0.0 return float(outline["rows"][index - 2].get("gap_after_seconds", 0)) # ------------------------------------------------- plain-text segment fragments _HANDOFF_LINE_RE = re.compile(r"^#\s*handoff\s*:\s*(.*)$", re.IGNORECASE) def fragment_from_text(outline: dict[str, Any], index: int, prompt_text: str, handoff: str | None) -> dict[str, Any]: """Synthesize the minimal segment fragment from an approved outline row plus the scene prompt text (the body of a plain-text segment_NN.txt fragment). The row is the single source of truth: id, frames, task/continuity modes and the image set come straight from the outline — nothing is retyped, so the classic fragment failures (paraphrased media paths, drifting frames, swapped modes) cannot happen by construction. Only two things are genuinely new per segment: the prompt text and the handoff end_state. Both are prose — which is why the fragment file is plain text, not JSON. """ rows = outline["rows"] if not 1 <= index <= len(rows): raise Fail(f"fragment index {index} is outside the outline's 1..{len(rows)} rows") row = rows[index - 1] where = f"txt fragment {row['id']}" if not isinstance(prompt_text, str) or not prompt_text.strip(): raise Fail(f"{where}: the fragment file has no scene prompt text") if "|" in prompt_text: raise Fail( f"{where}: the scene prompt contains '|' — it would split the scene in the " "plain-text paste. One scene per fragment file; move the pipe out." ) if _TEXT_MARKER_RE.search(prompt_text): raise Fail( f"{where}: the scene prompt contains a [start-end] marker. The merge appends " "the markers itself; a hand-written one doubles up, and bare [number-number] " "prose is eaten by the editor's parser as a frame range." ) if "@" in prompt_text: raise Fail( f"{where}: '@' never survives to the model (the editor strips it) — media " "rides in the JSON payload's /