@lemoncat7/dsh-partner 2.8.1 → 2.8.2

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/adoption/narration_binding.py

@@ -0,0 +1,323 @@
+"""Record which narration inputs an assembly consumed: adoption, snapshot, placement, output."""
+
+import json
+import math
+from pathlib import Path
+import shutil
+import subprocess
+
+from adoption.frozen_audio import probe_audio_packets
+from adoption.strict_inputs import (
+    read_json_bytes, require_fields, require_local_path, without_digests, write_json_atomic,
+)
+
+
+ARTIFACT = "narration_input_binding"
+FILENAME = "narration_input_binding.json"
+IDENTITY_STATUSES = frozenset({"UNADOPTED", "BOUND_TO_ADOPTION"})
+# The conservative default an adoption gets when it declares nothing stronger.
+TEMPO_POLICY = {
+    "global_atempo": 1.0,
+    "bounded_segment_fit": False,
+    "segment_tempo_max": 1.0,
+    "cumulative_tempo_max": 1.0,
+    "cumulative_tempo_hard_max": 1.0,
+}
+TEMPO_NUMBERS = ("global_atempo", "segment_tempo_max", "cumulative_tempo_max",
+                 "cumulative_tempo_hard_max")
+
+
+def validate_tempo_policy(value):
+    """Accept any adoption-declared tempo policy whose shape and bounds hold.
+
+    The adoption, not this module, decides how fast its own narration may be
+    played; the module only refuses policies that are malformed or that would
+    let a segment exceed the cumulative hard ceiling the policy itself declares.
+    """
+    require_fields(value, sorted(TEMPO_POLICY), "tempo_policy")
+    policy = {}
+    for key in TEMPO_NUMBERS:
+        number = value[key]
+        if type(number) not in (int, float) or not math.isfinite(number):
+            raise ValueError(f"tempo_policy {key} must be a finite number")
+        policy[key] = float(number)
+    if type(value["bounded_segment_fit"]) is not bool:
+        raise ValueError("tempo_policy bounded_segment_fit must be a boolean")
+    policy["bounded_segment_fit"] = value["bounded_segment_fit"]
+    if policy["cumulative_tempo_max"] < 1.0:
+        raise ValueError("tempo_policy cumulative_tempo_max must be at least 1.0")
+    if policy["cumulative_tempo_hard_max"] < policy["cumulative_tempo_max"]:
+        raise ValueError("tempo_policy cumulative_tempo_hard_max must not be below "
+                         "cumulative_tempo_max")
+    if policy["segment_tempo_max"] < 1.0:
+        raise ValueError("tempo_policy segment_tempo_max must be at least 1.0")
+    if not 0 < policy["global_atempo"] <= policy["cumulative_tempo_hard_max"]:
+        raise ValueError("tempo_policy global_atempo must be positive and within "
+                         "cumulative_tempo_hard_max")
+    return policy
+
+
+def load_adoption(path, *, tts_meta_path, tts_segments):
+    """Load a strict v1 adoption and check it against the current tts_meta segments."""
+    if tts_meta_path is None:
+        raise ValueError("narration adoption requires explicit tts_meta_path")
+    adoption_path, _, adoption = read_json_bytes(path, "narration adoption")
+    adoption = without_digests(adoption, "narration adoption")
+    require_fields(adoption, ["artifact", "schema_version", "segments", "tempo_policy"],
+                   "narration adoption")
+    if adoption["artifact"] != "narration_adoption" or type(adoption["schema_version"]) is not int \
+            or adoption["schema_version"] != 1:
+        raise ValueError("unsupported narration_adoption schema")
+    tts_meta_path, _, tts_meta = read_json_bytes(tts_meta_path, "tts_meta")
+    if not isinstance(tts_meta, dict) or not isinstance(tts_meta.get("segments"), list):
+        raise ValueError("tts_meta requires a segments list")
+    if tts_meta["segments"] != tts_segments:
+        raise ValueError("in-memory narration segments differ from bound tts_meta")
+    tempo_policy = validate_tempo_policy(adoption["tempo_policy"])
+    if not isinstance(adoption["segments"], list) or len(adoption["segments"]) != len(tts_segments):
+        raise ValueError("adoption segments must exactly cover tts_meta segments")
+    normalized_segments = []
+    for adopted, actual in zip(adoption["segments"], tts_segments):
+        adopted = without_digests(adopted, "adoption segment")
+        require_fields(adopted, ["index", "spoken_text", "requested_provider", "requested_voice"],
+                       "adoption segment")
+        if type(adopted["index"]) is not int or adopted["index"] != actual.get("index"):
+            raise ValueError("adoption segment index/order differs from tts_meta")
+        spoken = actual.get("spoken_text", actual.get("narration"))
+        if not isinstance(adopted["spoken_text"], str) or adopted["spoken_text"] != spoken:
+            raise ValueError("adoption spoken_text differs from tts_meta")
+        for key in ("requested_provider", "requested_voice"):
+            if not isinstance(adopted[key], str) or not adopted[key]:
+                raise ValueError(f"adoption {key} must be a non-empty string")
+        normalized_segments.append(dict(adopted))
+    return {
+        "path": str(adoption_path),
+        "tts_meta": {"path": str(tts_meta_path)},
+        "segments": normalized_segments, "tempo_policy": tempo_policy,
+    }
+
+
+def _copy_snapshot(source, destination):
+    """Copy seam kept small so tests can inject a post-preflight source mutation."""
+    shutil.copyfile(source, destination)
+
+
+def prepare_binding(tts_segments, work_dir, *, narration_adoption_path=None,
+                    tts_meta_path=None):
+    """Validate first, then snapshot the adopted narration inputs into work_dir."""
+    if not isinstance(tts_segments, list):
+        raise ValueError("tts_segments must be a list")
+    adoption = (
+        load_adoption(narration_adoption_path, tts_meta_path=tts_meta_path,
+                      tts_segments=tts_segments)
+        if narration_adoption_path is not None else None
+    )
+    if not adoption:
+        originals = [
+            {"index": segment["index"], "source": Path(segment["audio_path"]).resolve(),
+             "spoken_text": segment["spoken_text"]}
+            for segment in tts_segments
+        ]
+        return {
+            "identity_status": "UNADOPTED", "adoption": None, "tempo_policy": None,
+            "originals": originals, "active": False, "segments": [],
+        }
+    originals = []
+    seen_indices = set()
+    for position, segment in enumerate(tts_segments):
+        if not isinstance(segment, dict) or type(segment.get("index")) is not int:
+            raise ValueError("each narration segment requires an integer index")
+        if segment["index"] in seen_indices:
+            raise ValueError("narration segment indices must be unique")
+        seen_indices.add(segment["index"])
+        adopted = adoption["segments"][position]
+        source = require_local_path(segment["audio_path"], "narration audio")
+        originals.append({
+            "index": segment["index"], "source": source,
+            "spoken_text": segment["spoken_text"],
+            "requested_provider": adopted["requested_provider"],
+            "requested_voice": adopted["requested_voice"],
+        })
+    context = {
+        "identity_status": "BOUND_TO_ADOPTION", "adoption": adoption,
+        "tempo_policy": adoption["tempo_policy"],
+        "originals": originals, "active": True, "segments": [], "sealed": None,
+    }
+    snapshot_dir = Path(work_dir).resolve() / ".narration_input_snapshots"
+    snapshot_dir.mkdir(parents=True, exist_ok=False)
+    for position, (segment, original) in enumerate(zip(tts_segments, originals)):
+        suffix = original["source"].suffix or ".audio"
+        snapshot = snapshot_dir / f"segment_{position:04d}_{segment['index']}{suffix}"
+        _copy_snapshot(original["source"], snapshot)
+        segment["audio_path"] = str(snapshot)
+        segment["narration_input_original"] = {"path": str(original["source"])}
+        segment["narration_input_snapshot"] = {"path": str(snapshot)}
+        context["segments"].append({
+            "index": original["index"], "spoken_text": original["spoken_text"],
+            "requested_provider": original["requested_provider"],
+            "requested_voice": original["requested_voice"],
+            "original": dict(segment["narration_input_original"]),
+            "snapshot": dict(segment["narration_input_snapshot"]),
+        })
+    return context
+
+
+def _pcm(path):
+    result = subprocess.run(
+        ["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_streams",
+         "-show_entries", "stream=codec_name,sample_fmt,sample_rate,channels,channel_layout",
+         "-of", "json", str(path)], capture_output=True, text=True, timeout=600,
+    )
+    if result.returncode:
+        raise ValueError(f"audio probe failed: {result.stderr.strip()}")
+    streams = json.loads(result.stdout).get("streams", [])
+    if len(streams) != 1:
+        raise ValueError("expected exactly one audio stream")
+    stream = streams[0]
+    return {key: stream.get(key) for key in (
+        "codec_name", "sample_fmt", "sample_rate", "channels", "channel_layout"
+    )}
+
+
+def _asset(path, *, pcm=False):
+    path = require_local_path(path, "binding asset")
+    value = {"path": str(path)}
+    if pcm:
+        value["pcm"] = _pcm(path)
+    return value
+
+
+def seal_render_inputs(context, tts_segments, narration_wav):
+    """Record every derived audio file that the final FFmpeg command will consume."""
+    if not context.get("active"):
+        return None
+    by_index = {segment["index"]: segment for segment in tts_segments}
+    sealed_segments = []
+    for item in context["segments"]:
+        segment = by_index[item["index"]]
+        placed = segment.get("placed_audio_path")
+        if not placed:
+            raise RuntimeError("active narration binding has no complete placed audio")
+        conversion = segment.get("narration_conversion_path")
+        conversion_asset = (
+            {"applied": True, **_asset(conversion, pcm=True)}
+            if conversion else {"applied": False}
+        )
+        sealed_segments.append({
+            "index": item["index"],
+            "conversion": conversion_asset,
+            "placed": _asset(placed, pcm=True),
+        })
+    context["sealed"] = {
+        "segments": sealed_segments,
+        "narration_bus": _asset(narration_wav, pcm=True),
+    }
+    return context["sealed"]
+
+
+def _active_report(context, rendered_output, final_output):
+    if not context.get("sealed"):
+        raise RuntimeError("active narration inputs must be sealed before finalization")
+    sealed = {item["index"]: item for item in context["sealed"]["segments"]}
+    segments = []
+    for item in context["segments"]:
+        segments.append({
+            **item,
+            "original": _asset(item["original"]["path"], pcm=True),
+            "snapshot": _asset(item["snapshot"]["path"], pcm=True),
+            "conversion": sealed[item["index"]]["conversion"],
+            "placed": sealed[item["index"]]["placed"],
+        })
+    rendered_path = require_local_path(rendered_output, "rendered output")
+    final_audio = probe_audio_packets(rendered_path, 0)
+    return {
+        "artifact": ARTIFACT, "schema_version": 1, "status": "FINALIZED",
+        "identity_status": context["identity_status"], "adoption": context["adoption"],
+        "segments": segments, "narration_bus": context["sealed"]["narration_bus"],
+        "final_output": {
+            "path": str(Path(final_output).resolve()),
+            "audio_stream": {
+                "decoder": final_audio["decoder"], "packet_count": final_audio["packet_count"],
+                "payload_bytes": final_audio["payload_bytes"],
+                "start_time": final_audio["start_time"], "duration": final_audio["duration"],
+            },
+        },
+        "voice_authentication": "NOT_CHECKED", "direct_listening": "NOT_CHECKED",
+    }
+
+
+def finalize_binding(context, tts_segments, narration_wav, final_output, *, rendered_output=None):
+    """Write ``narration_input_binding.json`` beside ``narration_wav`` and return it.
+
+    ``rendered_output`` is the candidate file to probe when the published
+    ``final_output`` path does not exist yet; it defaults to ``final_output``.
+    """
+    del tts_segments  # already sealed; the record describes what was consumed
+    if not context.get("active"):
+        report = {
+            "artifact": ARTIFACT, "schema_version": 1, "status": "FINALIZED",
+            "identity_status": "UNADOPTED", "adoption": None,
+            "segments": [
+                {
+                    "index": original["index"], "spoken_text": original["spoken_text"],
+                    "requested_provider": None, "requested_voice": None,
+                    "original": {"path": str(original["source"])},
+                    "snapshot": None, "conversion": {"applied": False},
+                    "placed": None,
+                }
+                for original in context["originals"]
+            ],
+            "narration_bus": ({"path": str(Path(narration_wav).resolve())}
+                              if Path(narration_wav).is_file() else None),
+            "final_output": ({"path": str(Path(final_output).resolve())}
+                             if Path(final_output).is_file() else None),
+            "voice_authentication": "NOT_CHECKED", "direct_listening": "NOT_CHECKED",
+        }
+    else:
+        report = _active_report(
+            context, final_output if rendered_output is None else rendered_output, final_output
+        )
+    write_json_atomic(Path(narration_wav).resolve().parent / FILENAME, report)
+    return report
+
+
+def record_of(report, path):
+    """The manifest/QC summary of one finalized binding report stored at ``path``."""
+    return {"path": str(Path(path).resolve()),
+            "identity_status": report["identity_status"],
+            "tempo_policy": (
+                report["adoption"]["tempo_policy"]
+                if report["identity_status"] == "BOUND_TO_ADOPTION" else None
+            )}
+
+
+def binding_record(work_dir):
+    """The finalized binding's path, identity status and tempo policy; None when absent/invalid."""
+    path = Path(work_dir) / FILENAME
+    if not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if (
+        not isinstance(value, dict)
+        or value.get("artifact") != ARTIFACT
+        or type(value.get("schema_version")) is not int
+        or value.get("schema_version") != 1
+        or value.get("status") != "FINALIZED"
+        or value.get("identity_status") not in IDENTITY_STATUSES
+    ):
+        return None
+    if value["identity_status"] == "BOUND_TO_ADOPTION":
+        adoption = value.get("adoption")
+        if not isinstance(adoption, dict):
+            return None
+        try:
+            validate_tempo_policy(adoption.get("tempo_policy"))
+        except ValueError:
+            return None
+    final_output = value.get("final_output")
+    if not isinstance(final_output, dict) or not Path(str(final_output.get("path", ""))).is_file():
+        return None
+    return record_of(value, path)

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/adoption/strict_inputs.py

@@ -0,0 +1,109 @@
+"""Shared strict-input helpers for the explicit-input assemble modules.
+
+Every helper here fails closed with ``ValueError`` on malformed input and never
+guesses: a path must be a local file, a JSON document must parse, a rational must
+be canonical ``N/D``. ``run_logged`` and ``probe_json`` wrap the external tools so
+each caller logs the same evidence.
+"""
+
+from fractions import Fraction
+import json
+import math
+from pathlib import Path
+import subprocess
+
+
+def require_fields(value, required, label):
+    if not isinstance(value, dict) or set(value) != set(required):
+        raise ValueError(f"{label} requires exactly fields {required}")
+
+
+def without_digests(value, label):
+    """Drop the ``sha256`` / ``*_sha256`` keys older caller JSON declared; they are ignored."""
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be an object")
+    return {key: item for key, item in value.items()
+            if key != "sha256" and not key.endswith("_sha256")}
+
+
+def require_integer(value, label, minimum=0):
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{label} must be an integer >= {minimum}")
+    return value
+
+
+def require_number(value, label, minimum, maximum):
+    if type(value) not in (int, float) or not math.isfinite(value) \
+            or not minimum <= value <= maximum:
+        raise ValueError(f"{label} must be finite in [{minimum},{maximum}]")
+    return float(value)
+
+
+def require_local_path(path, label):
+    if not isinstance(path, (str, Path)) or not str(path) or "://" in str(path):
+        raise ValueError(f"{label} requires a local path")
+    resolved = Path(path).resolve()
+    if not resolved.is_file():
+        raise ValueError(f"{label} is missing: {resolved}")
+    return resolved
+
+
+def require_declared_path(value, label):
+    """Resolve a caller ``{"path": ...}`` declaration to an existing local file."""
+    if not isinstance(value, dict):
+        raise ValueError(f"{label} must be an object with a path")
+    return require_local_path(value.get("path"), label)
+
+
+def read_json_bytes(path, label):
+    """Return (resolved_path, raw_bytes, parsed) for one local JSON document."""
+    resolved = require_local_path(path, label)
+    raw = resolved.read_bytes()
+    try:
+        return resolved, raw, json.loads(raw)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError(f"{label} is not valid JSON") from exc
+
+
+def write_json_atomic(path, value):
+    path = Path(path)
+    temporary = path.with_suffix(".writing.json")
+    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    temporary.replace(path)
+
+
+def canonical_fraction(value, label):
+    if not isinstance(value, str):
+        raise ValueError(f"{label} must be a canonical rational string")
+    try:
+        result = Fraction(value)
+    except (ValueError, ZeroDivisionError) as exc:
+        raise ValueError(f"invalid {label}") from exc
+    if result <= 0 or value != f"{result.numerator}/{result.denominator}":
+        raise ValueError(f"{label} must be a positive canonical N/D rational")
+    return result
+
+
+def probe_json(path, *ffprobe_args):
+    result = subprocess.run(
+        ["ffprobe", "-v", "error", *ffprobe_args, "-of", "json", str(path)],
+        capture_output=True, text=True, timeout=600,
+    )
+    if result.returncode or result.stderr.strip():
+        raise ValueError(f"media probe failed for {path}: {result.stderr.strip()}")
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"invalid media probe JSON for {path}") from exc
+
+
+def run_logged(command, directory, label, *, prefix="", timeout=3600):
+    """Run one FFmpeg command, keeping ``<prefix><label>.command.json`` and ``.log``."""
+    directory = Path(directory)
+    name = f"{prefix}{label}"
+    write_json_atomic(directory / f"{name}.command.json", command)
+    result = subprocess.run(command, capture_output=True, text=True, timeout=timeout)
+    (directory / f"{name}.log").write_text(result.stderr, encoding="utf-8")
+    if result.returncode:
+        raise RuntimeError(f"{name} FFmpeg failed; see {name}.log")
+    return result

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/adoption/strict_publish.py

@@ -0,0 +1,130 @@
+"""Publish transaction for strict-adoption renders.
+
+An active narration binding renders to a hidden candidate file. Its binding (and,
+for an explicit mix, the audio mix binding) is written, QC gates the candidate,
+the media file is published, and QC runs once more against the published path.
+Any failure removes the candidate, the published file and the bindings written
+by this render, so a strict output never exists without its consumed-input record.
+"""
+
+from pathlib import Path
+
+import assembly_contract
+import adoption.audio_mix_binding as audio_mix_binding
+import adoption.narration_binding as narration_binding
+
+
+def current_narration_binding(work_dir, audio_mode):
+    """Read the narration record only for the explicit narration render path."""
+    if audio_mode != "narration":
+        return None
+    return narration_binding.binding_record(work_dir)
+
+
+def current_audio_mix_binding(work_dir, audio_mode):
+    if audio_mode != "narration":
+        return None
+    return audio_mix_binding.binding_record(work_dir)
+
+
+def publish_render(*, work_dir, binding, explicit_mix, tts_segments, narration_wav,
+                   render_output, published_output, audio_mode, audio_operations,
+                   adopted_audio, loudness_mode, loudnorm_measurement, visual_qc,
+                   source_has_audio, video_duration, render_delivery, source_audio_status):
+    """Gate the rendered candidate on assembly QC and publish it with its bindings.
+
+    Returns the final output path. Inactive-binding renders only write their
+    binding and QC; strict renders write bindings, publish, and re-run QC, or roll
+    everything back.
+    """
+    active = bool(binding and binding["active"])
+    work_dir = Path(work_dir)
+    binding_path = work_dir / narration_binding.FILENAME
+    mix_binding_path = work_dir / audio_mix_binding.FILENAME
+    binding_written = False
+    mix_binding_written = False
+    try:
+        if active:
+            report = narration_binding.finalize_binding(
+                binding, tts_segments,
+                (work_dir / "narration.wav" if explicit_mix is not None else narration_wav),
+                published_output, rendered_output=render_output,
+            )
+            binding_written = True
+            if not binding_path.is_file():
+                raise RuntimeError("narration binding 未写入")
+            narration_record = narration_binding.record_of(report, binding_path)
+            mix_record = None
+            if explicit_mix is not None:
+                audio_mix_binding.finalize_binding(
+                    explicit_mix, narration_record, render_output, published_output, work_dir
+                )
+                mix_binding_written = True
+                mix_record = {"path": str(mix_binding_path.resolve()), "status": "FINALIZED"}
+        elif binding:
+            narration_binding.finalize_binding(
+                binding, tts_segments, narration_wav, render_output
+            )
+            narration_record = current_narration_binding(work_dir, audio_mode)
+            mix_record = None
+        else:
+            narration_record = current_narration_binding(work_dir, audio_mode)
+            mix_record = None
+        assembly_qc = assembly_contract._build_assembly_qc(
+            tts_segments,
+            video_duration,
+            output_path=render_output,
+            source_has_audio=source_has_audio,
+            loudness_mode=loudness_mode,
+            loudnorm_measurement=loudnorm_measurement,
+            visual_qc=visual_qc,
+            audio_mode=audio_mode,
+            audio_operations=audio_operations,
+            adopted_audio=adopted_audio,
+            narration_input_binding=narration_record,
+            audio_mix_binding=mix_record,
+            source_audio_status=source_audio_status,
+            render_delivery=render_delivery,
+        )
+        if active and assembly_qc["blocking"]:
+            assembly_contract._write_assembly_qc(work_dir, assembly_qc)
+            codes = ", ".join(assembly_qc["blocking_codes"])
+            raise RuntimeError(f"身份约束渲染 QC 失败: {codes}")
+        if active:
+            render_output.rename(published_output)
+            render_output = published_output
+            current_binding = current_narration_binding(work_dir, audio_mode)
+            if current_binding is None:
+                raise RuntimeError("已发布 narration binding 未通过终态检查")
+            current_mix_binding = current_audio_mix_binding(work_dir, audio_mode)
+            if explicit_mix is not None and current_mix_binding is None:
+                raise RuntimeError("已发布 audio mix binding 未通过终态检查")
+            assembly_qc = assembly_contract._build_assembly_qc(
+                tts_segments, video_duration, output_path=render_output,
+                source_has_audio=source_has_audio,
+                loudness_mode=loudness_mode, loudnorm_measurement=loudnorm_measurement,
+                visual_qc=visual_qc, audio_mode=audio_mode,
+                audio_operations=audio_operations, adopted_audio=adopted_audio,
+                narration_input_binding=current_binding,
+                audio_mix_binding=current_mix_binding,
+                source_audio_status=source_audio_status,
+                render_delivery=assembly_qc["delivery_qc"],
+            )
+            if assembly_qc["blocking"]:
+                assembly_qc["output"] = {
+                    "path": str(published_output), "exists": False, "bytes": 0,
+                }
+                assembly_contract._write_assembly_qc(work_dir, assembly_qc)
+                codes = ", ".join(assembly_qc["blocking_codes"])
+                raise RuntimeError(f"身份约束渲染终态 QC 失败: {codes}")
+        assembly_contract._write_assembly_qc(work_dir, assembly_qc)
+    except Exception:
+        if active:
+            render_output.unlink(missing_ok=True)
+            published_output.unlink(missing_ok=True)
+            if binding_written:
+                binding_path.unlink(missing_ok=True)
+            if mix_binding_written:
+                mix_binding_path.unlink(missing_ok=True)
+        raise
+    return render_output

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/artifacts.py

@@ -0,0 +1,47 @@
+"""File identity and work-directory JSON helpers for video-assemble."""
+
+import json
+import os
+from pathlib import Path
+
+from lib import CONFIG
+
+
+def file_identity(path):
+    """``{size, mtime_ns}`` of one input file: enough to notice a rewrite, cheap to take."""
+    st = os.stat(os.fspath(path))
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
+
+
+def _artifact_identity(path):
+    path = Path(path)
+    return file_identity(path) if path.exists() else None
+
+
+def _explicit_source_video():
+    """Return the cut-mode source video only when the caller opted in explicitly."""
+    if not CONFIG["source_video_explicit"]:
+        return ""
+    return CONFIG["source_video"]
+
+
+def _source_video_identity():
+    """``{path, size, mtime_ns}`` of the explicit cut-mode source video, else None."""
+    source_video = _explicit_source_video()
+    if not source_video:
+        return None
+    path = Path(source_video)
+    return {"path": str(path.resolve()), **file_identity(path)}
+
+
+def _timeline_provenance_status(work_dir):
+    data = _load_work_json(work_dir, "timeline.json")
+    return None if data is None else data["provenance"]
+
+
+def _load_work_json(work_dir, name):
+    """Parse a JSON artifact in work_dir; None only when the file does not exist."""
+    path = Path(work_dir) / name
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))