@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-assemble/scripts/assemble_constants.py

@@ -1,12 +1,34 @@
 """Shared constants for the self-contained video-assemble skill."""
 
-SUBTITLE_RENDER_VERSION = 8
-SUBTITLE_TEXT_NORMALIZE_VERSION = 1
+from fractions import Fraction
+import math
+
 ASSEMBLY_MANIFEST = "assembly_manifest.json"
 ASSEMBLY_QC = "assembly_qc.json"
 VISUAL_QC = "visual_qc.json"
 VISUAL_OVERLAYS = "visual_overlays.json"
 SEGMENT_AUDIO_SCHEMA_VERSION = 1
+
+# The picture codecs every packet/frame clock proof in this skill accepts.
+SUPPORTED_PICTURE_CODECS = frozenset({"h264", "hevc"})
+
+# The one exact output audio clock every explicit-sound artifact in this skill uses.
+OUTPUT_SAMPLE_RATE = 48_000
+
+
+def frame_clock_samples(frame, fps, rate=OUTPUT_SAMPLE_RATE):
+    """Project an exact frame boundary of a video clock onto the output sample clock.
+
+    Broadcast rates such as 30000/1001 put frame boundaries between whole samples, so
+    the exact Fraction position is rounded half-up once, here. Every sample bound in
+    the skill - a segment edge and the whole-picture `total_samples` alike - is this
+    single projection, so an integral clock is unchanged and a fractional one stays
+    consistent across the explicit-sound tools.
+    """
+    exact = Fraction(int(frame) * rate, 1) / Fraction(fps)
+    return math.floor(exact + Fraction(1, 2))
+
+
 FILTER_SCRIPT_THRESHOLD_BYTES = 8000
 
 # The default subtitle metrics were tuned in this reference canvas.
@@ -18,17 +40,12 @@ _SUBTITLE_CLOSING_QUOTES = "」』”’）)]】》〉\"'"
 _MIN_GAP_TO_SUBTITLE = 0.8
 _MIN_READABLE_SECONDS = 0.3
 _MIN_ASR_CLIP_OVERLAP = 0.05
+# timeline.py serializes interval bounds onto a 1e-4 second grid, flooring starts
+# and ceiling ends, so two bounds that were identical before serialization can come
+# back one grid step apart. Contiguity joins must tolerate that whole step.
+_TIMELINE_TIME_GRID_SECONDS = 1e-4
+_CLIP_CONTIGUITY_TOLERANCE = 1.5 * _TIMELINE_TIME_GRID_SECONDS
 _MAX_ORIGINAL_READ_CPS = 9.0
 _AUTO_ORIGINAL_READ_CPS = 6.0
 
-_VISUAL_DELIVERY_FORBIDDEN_KEYS = {
-    "video_encode_passes",
-    "reencode_reason",
-    "audio_sample_rate",
-    "final_compat_notes",
-    "double_encode",
-    "delivery_compatibility",
-    "loudness_mode",
-    "loudnorm_measurement",
-}
 _SUPPORTED_VISUAL_OVERLAY_TYPES = {"top_title", "inline_label_or_callout"}

package/lib/video-recap/skills/video-assemble/scripts/assembly_contract.py

@@ -1,7 +1,9 @@
 """Assembly manifest/QC persistence and delivery contract helpers."""
 
 import json
+from fractions import Fraction
 import math
+import subprocess
 import wave
 from pathlib import Path
 
@@ -12,6 +14,7 @@ from assemble_constants import (
     SEGMENT_AUDIO_SCHEMA_VERSION,
 )
 from audio_mix import _loudness_mode
+from subtitles.track_binding import manifest_subtitle_evidence
 from artifacts import (
     _load_work_json,
     _source_video_identity,
@@ -25,44 +28,60 @@ _AUDIO_QC_CODES = frozenset({
 
 
 def _assembly_manifest_payload(input_video, tts_segments, work_dir, output_path,
-                               tts_meta_path=None, final_output=None, *, settings_fingerprint):
+                               tts_meta_path=None, final_output=None, *, settings_payload,
+                               audio_mode="narration", audio_stream_index=0,
+                               narration_input_binding=None, audio_mix_binding=None):
     """Slim render record. The orchestrator reads `final_output` to report the result;
     `source_video` stays None unless cut mode explicitly passed --source-video, proving a
     stale ambient SOURCE_VIDEO never leaked into a full-mode timeline / 剪映 export."""
     input_video = Path(input_video)
     output_path = Path(output_path)
-    source_video, source_video_fingerprint = _source_video_identity()
+    source_video_identity = _source_video_identity()
     qc_path = Path(work_dir) / ASSEMBLY_QC
-    qc = _load_work_json(work_dir, ASSEMBLY_QC) or {}
+    qc = _load_work_json(work_dir, ASSEMBLY_QC)  # always written by publish_render first
+    settings = settings_payload(
+        work_dir, audio_mode=audio_mode, audio_stream_index=audio_stream_index
+    )
     payload = {
         "schema_version": 2,
         "input_video": str(input_video.resolve()),
-        "source_video": source_video,
-        "source_video_fingerprint": source_video_fingerprint,
+        "source_video": source_video_identity["path"] if source_video_identity else None,
+        "source_video_identity": source_video_identity,
         "tts_meta": str(Path(tts_meta_path).resolve()) if tts_meta_path else None,
         "tts_segments": len(tts_segments),
-        "assembly_settings": settings_fingerprint(work_dir),
+        "audio_mode": audio_mode,
+        "selected_audio_stream_index": audio_stream_index,
+        "assembly_settings": settings,
         "output_path": str(output_path.resolve()),
         "segment_audio_schema_version": SEGMENT_AUDIO_SCHEMA_VERSION,
-        "qc_path": str(qc_path.resolve()) if qc else None,
-        "qc_verdict": qc.get("verdict"),
-        "qc_blocking_codes": qc.get("blocking_codes", []),
-        # The settings fingerprint records the configured/fallback loudness policy; these QC
+        "qc_path": str(qc_path.resolve()),
+        "qc_verdict": qc["verdict"],
+        "qc_blocking_codes": qc["blocking_codes"],
+        # The settings payload records the configured/fallback loudness policy; these QC
         # fields record what the just-finished render actually used after the loudnorm probe.
-        "qc_loudness_mode": qc.get("loudness_mode"),
-        "qc_loudnorm_measurement": qc.get("loudnorm_measurement"),
+        "qc_loudness_mode": qc["loudness_mode"],
+        "qc_loudnorm_measurement": qc["loudnorm_measurement"],
+        "audio_operations": qc["audio_operations"],
+        "adopted_audio": qc["adopted_audio"],
+        "narration_input_binding": narration_input_binding,
+        "audio_mix_binding": audio_mix_binding,
         "audio_segments": [
             {
                 "index": seg["index"],
-                "segment_audio_schema_version": seg.get("segment_audio_schema_version", SEGMENT_AUDIO_SCHEMA_VERSION),
+                # Informational manifest fields: a tts_meta without the schema marker is v1,
+                # and the loudness measurements are None whenever voiceover skipped
+                # normalization (strict adoption fixtures in tests/orchestrator omit both).
+                "segment_audio_schema_version": seg.get(
+                    "segment_audio_schema_version", SEGMENT_AUDIO_SCHEMA_VERSION
+                ),
                 "narration": seg["narration"],
-                "spoken_text": seg.get("spoken_text", seg["narration"]),
-                "truncated": seg.get("truncated", False),
-                "truncate_reason": seg.get("truncate_reason", "none"),
-                "fit_status": seg.get("fit_status"),
-                "blocking": seg.get("blocking", False),
-                "audio_duration": seg.get("audio_duration"),
-                "placed_audio_duration": seg.get("placed_audio_duration"),
+                "spoken_text": seg["spoken_text"],
+                "truncated": seg["truncated"],
+                "truncate_reason": seg["truncate_reason"],
+                "fit_status": seg["fit_status"],
+                "blocking": seg["blocking"],
+                "audio_duration": seg["audio_duration"],
+                "placed_audio_duration": seg["placed_audio_duration"],
                 "placed_audio_path": seg.get("placed_audio_path"),
                 "actual_place_start": seg.get("actual_place_start"),
                 "actual_place_end": seg.get("actual_place_end"),
@@ -70,12 +89,15 @@ def _assembly_manifest_payload(input_video, tts_segments, work_dir, output_path,
                 "source_restore_at": seg.get("source_restore_at"),
                 "source_handoff_status": seg.get("source_handoff_status"),
                 "source_entry_status": seg.get("source_entry_status"),
-                "global_narration_speed": seg.get("global_narration_speed"),
-                "segment_tempo_factor": seg.get("segment_tempo_factor"),
-                "effective_tempo": seg.get("effective_tempo"),
+                "global_narration_speed": seg["global_narration_speed"],
+                "segment_tempo_factor": seg["segment_tempo_factor"],
+                "effective_tempo": seg["effective_tempo"],
                 "rms_dbfs_before": seg.get("rms_dbfs_before"),
                 "rms_dbfs_after": seg.get("rms_dbfs_after"),
                 "peak_after": seg.get("peak_after"),
+                "output_start_sample": seg.get("output_start_sample"),
+                "output_end_sample": seg.get("output_end_sample"),
+                "adopted_gain": seg.get("adopted_gain"),
             }
             for seg in tts_segments
         ],
@@ -85,6 +107,9 @@ def _assembly_manifest_payload(input_video, tts_segments, work_dir, output_path,
     provenance = _timeline_provenance_status(work_dir)
     if provenance:
         payload["timeline_provenance"] = provenance
+    subtitle_evidence = manifest_subtitle_evidence(work_dir, input_video, output_path)
+    if subtitle_evidence is not None:
+        payload["subtitle_track"] = subtitle_evidence
     return payload
 
 
@@ -115,8 +140,8 @@ def _visual_qc_rollup(visual_qc):
         "overlays": {
             "present": overlays["present"],
             "rendered": overlays["rendered"],
-            "unsupported": overlays.get("unsupported", []),
-            "overflow": overlays.get("overflow", []),
+            "unsupported": overlays["unsupported"],
+            "overflow": overlays["overflow"],
         },
     }
 
@@ -126,10 +151,27 @@ def _placed_audio_matches_timeline(seg):
     placed_path = Path(seg["placed_audio_path"])
     if not placed_path.exists():
         return False
-    with wave.open(str(placed_path), "rb") as placed_wav:
-        placed_duration = placed_wav.getnframes() / placed_wav.getframerate()
-        tolerance = 1.0 / placed_wav.getframerate()
-    timeline_start = round(float(seg["actual_place_start"]), 4)
+    try:
+        with wave.open(str(placed_path), "rb") as placed_wav:
+            placed_duration = placed_wav.getnframes() / placed_wav.getframerate()
+            tolerance = 1.0 / placed_wav.getframerate()
+    except wave.Error:
+        result = subprocess.run(
+            ["ffprobe", "-v", "error", "-select_streams", "a:0", "-show_entries",
+             "stream=sample_rate,time_base,duration_ts", "-of", "json", str(placed_path)],
+            capture_output=True, text=True, timeout=600,
+        )
+        streams = json.loads(result.stdout).get("streams", []) if not result.returncode else []
+        if len(streams) != 1:
+            return False
+        stream = streams[0]
+        try:
+            rate = int(stream["sample_rate"])
+            placed_duration = float(Fraction(stream["duration_ts"]) * Fraction(stream["time_base"]))
+            tolerance = 1.0 / rate
+        except (KeyError, TypeError, ValueError, ZeroDivisionError):
+            return False
+    timeline_start = math.floor(float(seg["actual_place_start"]) * 10_000 + 1e-9) / 10_000
     timeline_end = math.ceil(float(seg["actual_place_end"]) * 10_000 - 1e-9) / 10_000
     serialized_span = timeline_end - timeline_start
     return (
@@ -138,9 +180,12 @@ def _placed_audio_matches_timeline(seg):
     )
 
 
-def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
-                       source_has_audio=None, loudness_mode=None, loudnorm_measurement=None,
-                       visual_qc=None, render_delivery=None):
+def _build_assembly_qc(tts_segments, video_duration, *, audio_operations, render_delivery,
+                       output_path=None, source_has_audio=None, loudness_mode=None,
+                       loudnorm_measurement=None, visual_qc=None, audio_mode="narration",
+                       adopted_audio=None,
+                       narration_input_binding=None, audio_mix_binding=None,
+                       source_audio_status=None):
     """Machine-readable assembly release gate.
 
     Visual facts are rolled up from visual_qc.json. Delivery/render facts live here
@@ -150,11 +195,11 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
     segments = tts_segments
     no_safe = [
         s["index"] for s in segments
-        if s.get("fit_status") == "no_safe_fit"
-        or s.get("truncate_reason") in {"no_safe_boundary", "no_room"}
-        or s.get("blocking", False)
+        if s["fit_status"] == "no_safe_fit"
+        or s["truncate_reason"] in {"no_safe_boundary", "no_room"}
+        or s["blocking"]
     ]
-    skipped = [s["index"] for s in segments if s.get("fit_status") == "skipped"]
+    skipped = [s["index"] for s in segments if s["fit_status"] == "skipped"]
     tempo_exceeded = []
     truncated = []
     handoff_failed = []
@@ -165,7 +210,7 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
         max_effective = max(max_effective, eff)
         if eff > hard_max + 1e-6:
             tempo_exceeded.append(s["index"])
-        if s.get("truncated", False) or s.get("truncate_reason") == "tail_trim_tolerance":
+        if s["truncated"] or s["truncate_reason"] == "tail_trim_tolerance":
             truncated.append(s["index"])
         if s.get("source_handoff_blocking", False):
             handoff_failed.append(s["index"])
@@ -174,7 +219,7 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
 
     placed = [s["placed_audio_duration"] for s in segments]
     blocking_codes = []
-    if not segments:
+    if audio_mode == "narration" and not segments:
         blocking_codes.append("missing_narration")
     if skipped:
         blocking_codes.append("skipped_segments")
@@ -197,7 +242,9 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
     )
     if visual_rollup["blocking"]:
         blocking_codes.append("visual_qc_failed")
-    if source_has_audio is False:
+    if source_audio_status is not None:
+        source_audio = source_audio_status
+    elif source_has_audio is False:
         # Not blocking: assemble can synthesize a silent original track.
         source_audio = "synthetic_silence"
     elif source_has_audio is True:
@@ -216,7 +263,6 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
         if output_path.exists() and output["bytes"] <= 0:
             blocking_codes.append("empty_output")
 
-    delivery = render_delivery if render_delivery is not None else {}
     return {
         "schema_version": 1,
         "artifact": ASSEMBLY_QC,
@@ -224,6 +270,11 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
         "blocking": bool(blocking_codes),
         "blocking_codes": blocking_codes,
         "duration": round(float(video_duration), 4),
+        "audio_mode": audio_mode,
+        "audio_operations": audio_operations,
+        "adopted_audio": adopted_audio,
+        "narration_input_binding": narration_input_binding,
+        "audio_mix_binding": audio_mix_binding,
         "source_audio": source_audio,
         "loudness_mode": loudness_mode or _loudness_mode(loudnorm_measurement),
         "loudnorm_measurement": loudnorm_measurement,
@@ -235,10 +286,10 @@ def _build_assembly_qc(tts_segments, video_duration, *, output_path=None,
         },
         "visual_qc": visual_rollup,
         "delivery_qc": {
-            "video_encode_passes": delivery.get("video_encode_passes"),
-            "reencode_reason": delivery.get("reencode_reason"),
-            "audio_sample_rate": delivery.get("audio_sample_rate"),
-            "final_compat_notes": delivery.get("final_compat_notes", []),
+            "video_encode_passes": render_delivery["video_encode_passes"],
+            "reencode_reason": render_delivery["reencode_reason"],
+            "audio_sample_rate": render_delivery["audio_sample_rate"],
+            "final_compat_notes": render_delivery["final_compat_notes"],
         },
         "summary": {
             "segments": len(segments),

package/lib/video-recap/skills/video-assemble/scripts/assembly_settings.py

@@ -1,31 +1,34 @@
-"""Render-affecting settings fingerprint for cache/resume decisions."""
+"""Render-affecting settings payload recorded in the manifest and compared by resume logic."""
 
 from pathlib import Path
 
-from artifacts import _artifact_fingerprint
-from assemble_constants import (
-    SUBTITLE_RENDER_VERSION,
-    SUBTITLE_TEXT_NORMALIZE_VERSION,
-    VISUAL_OVERLAYS,
-)
+from artifacts import _artifact_identity
+from assemble_constants import VISUAL_OVERLAYS
 from audio_mix import _loudness_mode, final_loudnorm_filter
 from lib import CONFIG
 from source_subtitles import _has_user_subtitles, _source_subtitle_mask_policy
-from subtitle_core import _subtitle_style_config
+from subtitles.core import _subtitle_style_config
+from adoption.narration_binding import binding_record
+from adoption.audio_mix_binding import binding_record as audio_mix_binding_record
+from packaging import packaging_settings
 
-def assembly_settings_fingerprint(work_dir=None):
-    """Settings that affect the rendered video, used by pipeline resume cache. When work_dir is
-    given, a user_subtitles presence flag is included so dropping in a user-subtitle file rebuilds
-    the cached subtitles."""
+
+def assembly_settings_payload(work_dir=None, *, audio_mode="narration", audio_stream_index=0):
+    """Settings that affect the rendered video, as a plain nested dict compared with ``==`` by
+    pipeline resume logic. When work_dir is given, a user_subtitles presence flag and the
+    ``{size, mtime_ns}`` identity of the overlay/subtitle-track inputs are included so dropping
+    in or rewriting one of those files rebuilds the cached subtitles."""
     burn_subtitles = CONFIG["burn_subtitles"]
     mask_policy = _source_subtitle_mask_policy(work_dir)
     mask_source_subtitles = mask_policy["active"]
-    overlay_fingerprint = (
-        _artifact_fingerprint(Path(work_dir) / VISUAL_OVERLAYS) if work_dir is not None else None
+    overlay_identity = (
+        _artifact_identity(Path(work_dir) / VISUAL_OVERLAYS) if work_dir is not None else None
+    )
+    subtitle_track_identity = (
+        _artifact_identity(Path(work_dir) / "subtitle_track.json")
+        if work_dir is not None else None
     )
-    fingerprint = {
-        "version": SUBTITLE_RENDER_VERSION,
-        "subtitle_text_normalize": SUBTITLE_TEXT_NORMALIZE_VERSION,
+    settings = {
         "user_subtitles": _has_user_subtitles(work_dir),
         "burn_subtitles": burn_subtitles,
         "force_video_reencode": CONFIG["force_video_reencode"],
@@ -55,19 +58,55 @@ def assembly_settings_fingerprint(work_dir=None):
             "subtitle_y_bot": CONFIG["subtitle_y_bot"],
             "visual_overlays": {
                 "artifact": VISUAL_OVERLAYS,
-                "present": overlay_fingerprint is not None,
-                "fingerprint": overlay_fingerprint,
+                "present": overlay_identity is not None,
+                "identity": overlay_identity,
             },
+            "packaging_layers": packaging_settings(work_dir),
         },
-        "narration_timing": {
-            "delay_seconds": CONFIG["narration_delay_seconds"],
-            "tail_pad_seconds": CONFIG["narration_tail_pad_seconds"],
-            "fade_ms": CONFIG["fade_ms"],
-            "narration_speed": CONFIG["narration_speed"],
-            "narration_cumulative_tempo_max": CONFIG["narration_cumulative_tempo_max"],
-            "tts_segment_tempo_max": CONFIG["tts_segment_tempo_max"],
+        "audio": {
+            "mode": audio_mode,
+            "selected_stream_index": audio_stream_index,
         },
-        "audio_mix": {
+    }
+    explicit_mix = (
+        audio_mix_binding_record(work_dir)
+        if work_dir is not None and audio_mode == "narration" else None
+    )
+    if explicit_mix:
+        settings["audio"]["path"] = "explicit_adopted_full_sound"
+        settings["audio_mix_binding"] = explicit_mix
+    if audio_mode == "narration":
+        narration_binding = binding_record(work_dir) if work_dir else None
+        settings["narration_input_binding"] = narration_binding
+        adopted_tempo = (
+            narration_binding.get("tempo_policy") if narration_binding else None
+        )
+        settings["narration_timing"] = {
+            "delay_seconds": 0.0 if explicit_mix else CONFIG["narration_delay_seconds"],
+            "tail_pad_seconds": 0.0 if explicit_mix else CONFIG["narration_tail_pad_seconds"],
+            "fade_ms": 0 if explicit_mix else CONFIG["fade_ms"],
+            "narration_speed": (
+                1.0 if explicit_mix else
+                adopted_tempo["global_atempo"] if adopted_tempo else CONFIG["narration_speed"]
+            ),
+            "tempo_source": (
+                "explicit_audio_mix" if explicit_mix else
+                "adoption" if adopted_tempo else "configuration"
+            ),
+            "narration_cumulative_tempo_max": CONFIG["narration_cumulative_tempo_max"],
+            "tts_segment_tempo_max": (
+                adopted_tempo["segment_tempo_max"]
+                if explicit_mix and adopted_tempo else CONFIG["tts_segment_tempo_max"]
+            ),
+        }
+        if explicit_mix and adopted_tempo:
+            settings["narration_timing"]["narration_cumulative_tempo_max"] = \
+                adopted_tempo["cumulative_tempo_max"]
+            settings["narration_timing"]["narration_cumulative_tempo_hard_max"] = \
+                adopted_tempo["cumulative_tempo_hard_max"]
+    if audio_mode in {"narration", "source-mix"} and not explicit_mix:
+        # adopted-packet-copy never decodes or mixes, so mix settings cannot change it.
+        settings["audio_mix"] = {
             "ducking_mode": CONFIG["ducking_mode"],
             "duck_fade_seconds": CONFIG["duck_fade_seconds"],
             "duck_bridge_seconds": CONFIG["duck_bridge_seconds"],
@@ -87,9 +126,13 @@ def assembly_settings_fingerprint(work_dir=None):
             "bgm_path": CONFIG["bgm_path"],
             "bgm_volume": CONFIG["bgm_volume"],
             "bgm_ducking_volume": CONFIG["bgm_ducking_volume"],
-        },
-    }
+        }
     if burn_subtitles:
-        fingerprint["subtitle_renderer"] = "ass"
-        fingerprint["subtitle_style"] = _subtitle_style_config()
-    return fingerprint
+        settings["subtitle_renderer"] = "ass"
+        settings["subtitle_style"] = _subtitle_style_config()
+    if subtitle_track_identity is not None:
+        settings["subtitle_track"] = {
+            "artifact": "subtitle_track.json",
+            "identity": subtitle_track_identity,
+        }
+    return settings

package/lib/video-recap/skills/video-assemble/scripts/audio_mix.py

@@ -4,13 +4,13 @@ import json
 import re
 from pathlib import Path
 
-from artifacts import _load_work_json, _value_fingerprint
+from artifacts import _load_work_json
 from audio_automation import (
     coalesce_duck_windows,
     ducking_expression,
     release_ducking_expression,
 )
-from lib import CONFIG, log, run_cmd
+from lib import CONFIG, filter_file_args, log, run_cmd
 
 def _limiter_filter():
     return f"alimiter=limit={CONFIG['final_limiter_peak']:.2f}:level=false"
@@ -92,7 +92,7 @@ def _run_loudnorm_first_pass(input_video, narration_wav, original_audio_input,
         "-i", str(narration_wav),
         *original_audio_input,
         *bgm_input,
-        "-filter_complex_script", str(probe_script),
+        *filter_file_args("filter_complex", probe_script),
         "-map", "[lnprobe]",
         "-f", "null", "-",
     ]
@@ -126,13 +126,13 @@ def _load_sentence_handoff_anchors(work_dir):
     if payload is None:
         return [], None, {"require_measured": cut_mode}
     if cut_mode:
-        # Output-clock anchors are only trusted when they were derived from the current cut plan.
-        plan = _load_work_json(work_dir, "clip_plan_validated.json")
+        # Output-clock anchors are only trusted when they are at least as new as the cut plan.
+        plan_path = work_dir / "clip_plan_validated.json"
         fresh = (
             payload.get("schema_version") == 2
             and payload.get("timeline") == "cut_output"
-            and plan is not None
-            and payload.get("clip_plan_fingerprint") == _value_fingerprint(plan)
+            and plan_path.exists()
+            and (work_dir / artifact).stat().st_mtime_ns >= plan_path.stat().st_mtime_ns
         )
         if not fresh:
             return [], None, {"require_measured": True}
@@ -172,7 +172,7 @@ def _handoff_speech_evidence(work_dir, payload):
         speech = _timed_rows(_asr_segments(work_dir))
     if not quiet:
         silence = _load_work_json(work_dir, "silence_periods.json") or []
-        quiet = _timed_rows(row for row in silence if not row.get("has_speech", False))
+        quiet = _timed_rows(row for row in silence if not row["has_speech"])
     return speech, quiet
 
 
@@ -278,7 +278,7 @@ def _apply_source_sentence_handoffs(tts_segments, work_dir, video_duration):
                 speech_spans,
                 quiet_windows,
                 anchors,
-                seg.get("overlaps_speech", True),
+                seg["overlaps_speech"],
                 require_measured=require_measured,
             )
             seg["overlaps_speech"] = measured
@@ -374,7 +374,7 @@ def _duck_envelope(tts_segments, idle, speech_vol, quiet_vol, fade, bridge):
             continue
         hold_end = max(narration_end, seg.get("source_duck_end", narration_end))
         restore_at = max(hold_end, seg.get("source_restore_at", hold_end + fade))
-        level = speech_vol if seg.get("overlaps_speech", True) else quiet_vol
+        level = speech_vol if seg["overlaps_speech"] else quiet_vol
         windows.append((start, hold_end, level, restore_at))
     return release_ducking_expression(windows, idle, fade, bridge=bridge)
 
@@ -455,7 +455,7 @@ def _build_audio_filter_complex(
     quiet_vol = CONFIG["zone_ducking_volume"]
     expr = _duck_envelope(tts_segments, idle, speech_vol, quiet_vol, fade, bridge)
     if expr:
-        n_overlap = sum(1 for s in tts_segments if s.get("overlaps_speech", True))
+        n_overlap = sum(1 for s in tts_segments if s["overlaps_speech"])
         n_quiet = len(tts_segments) - n_overlap
         log(f"gap-fill ducking: 间隙原声={idle}, 对白段={speech_vol}({n_overlap}), 安静段={quiet_vol}({n_quiet}), 桥接间隙<{bridge}s")
         orig = f"{original_in}volume='{expr}':eval=frame,aresample=48000[orig];"