@lemoncat7/dsh-partner 2.8.0 → 2.8.2

package/resources/skills/video-recap-production/upstream/skills/video-assemble/references/narration-adoption.md

@@ -0,0 +1,103 @@
+# Narration adoption and the consumed-input record
+
+Narration assembly accepts legacy `tts_meta.json`, but a current file by itself is
+not an adoption decision. Use an explicit adoption document when the selected spoken
+text, requested provider/voice, and tempo policy must be bound to the actual final mix.
+
+```bash
+python3 scripts/assemble.py input.mp4 --work-dir work \
+  --tts-meta /local/tts_meta.json \
+  --narration-adoption /local/narration_adoption.json
+```
+
+`--narration-adoption` is narration-only and requires an explicitly supplied
+`--tts-meta`; it never adopts an ambient work-directory file automatically.
+
+## Strict v1 schema
+
+```json
+{
+  "artifact": "narration_adoption",
+  "schema_version": 1,
+  "segments": [
+    {
+      "index": 0,
+      "spoken_text": "exact selected words",
+      "requested_provider": "caller-selected-provider",
+      "requested_voice": "caller-selected-voice"
+    }
+  ],
+  "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
+  }
+}
+```
+
+That policy is the conservative default. An adoption may declare its own values and
+they are honoured: `global_atempo` must be positive and no greater than
+`cumulative_tempo_hard_max`, `segment_tempo_max` and `cumulative_tempo_max` must be at
+least `1.0`, `cumulative_tempo_hard_max` must not be below `cumulative_tempo_max`, and
+`bounded_segment_fit` must be a boolean. Malformed or out-of-bounds policies fail;
+ambient defaults such as a global 1.15 speed never override an adoption. With
+`bounded_segment_fit` false, an adopted segment that does not fit its authored window
+blocks without time trimming or bounded fit.
+
+The adoption's ordered segment indices and spoken text must match both the segment
+list in the supplied `tts_meta.json` and the in-memory list passed to
+`assemble_video`; those two lists must be equal to each other. Unknown fields fail;
+legacy `tts_meta_sha256` / `processed_wav_sha256` keys are ignored. The consumer never
+creates an adoption from metadata that it is about to consume.
+
+## Validation and snapshots
+
+Every adopted `audio_path` must exist before any media is probed or rendered. The
+adopted inputs are then copied to per-run snapshots under
+`work/.narration_input_snapshots/`; the original files are never modified, and the
+render reads only the snapshots. Every conversion, placed WAV, and the completed
+narration bus is recorded with its path and probed PCM facts before the final FFmpeg
+command runs.
+
+On the legacy narration-mix path, Python's standard WAV reader cannot open every valid post-processed WAV encoding.
+Noncanonical input, including `pcm_f32le`, 48 kHz, or stereo WAV, is explicitly
+decoded by the existing FFmpeg executable to 44.1 kHz mono PCM16 before placement.
+The conversion path and actual PCM facts are recorded; the consumer does not claim
+that converted samples equal the original samples.
+
+The explicit full-sound path described in `explicit-audio-mix.md` deliberately does
+not use that 44.1 kHz mono conversion. It consumes the snapshots directly as complete
+48 kHz float placements, preserving native stereo channels.
+
+An adopted render writes to a hidden candidate path. The binding is written, QC runs
+against the candidate, the candidate is renamed to the final path, and QC runs once
+more against the published file. A blocking QC removes the candidate and the binding
+instead of publishing; the run records the final output as absent rather than
+claiming a missing file was published. Non-final work or diagnostic artifacts may
+remain for investigation.
+
+## Binding report
+
+After successful assembly, `work/narration_input_binding.json` records:
+
+- original input path and snapshot path;
+- any explicit conversion path and PCM parameters;
+- each complete placed WAV path and PCM parameters;
+- `narration.wav` path and PCM parameters;
+- the final output path and its encoded audio-stream facts (decoder parameters,
+  packet count, payload bytes, start time, duration);
+- the adoption path, its `tts_meta` path, and the exact tempo policy when supplied.
+
+The report uses one of two identity statuses:
+
+- `UNADOPTED`: no adoption was supplied; the legacy inputs were consumed as given;
+- `BOUND_TO_ADOPTION`: the adoption's selection and tempo policy were carried
+  through the final mix.
+
+`BOUND_TO_ADOPTION` records what was consumed, not provider truth, acoustic speaker
+identity, direct listening, naturalness, or release approval; voice authentication
+and direct listening stay `NOT_CHECKED`. QC, manifest, and settings records reference
+a binding only while its recorded final output path still exists; source-mix and
+adopted-packet-copy modes do not reuse narration binding evidence.

package/resources/skills/video-recap-production/upstream/skills/video-assemble/references/packaging.md

@@ -0,0 +1,45 @@
+# 字幕与包装的推荐顺序
+
+先锁定画面、剪点、旁白和混音，再投入字幕动画或边框包装。字幕样式不能掩盖叙事、剪点或声音问题。
+
+普通交付优先使用现有 ASS 路径。只有用户需要更精细的逐 cue 排版、动画或透明图层时，才使用 Remotion
+或其他代码渲染器作为**项目级可选实现**，不要把特定框架、字体、颜色或黄字写成核心依赖。
+
+## 推荐顺序
+
+1. 输出无包装的锁定母版，确认音画内容不再变化。
+2. 从实际 TTS / 时间线生成 captions；TTS 块保持连续思路，字幕可以按阅读宽度拆 cue。
+3. 先抽检开头、亮背景、暗背景、人物近景和长字幕样帧，确定字号、安全区、描边、阴影及是否需要底板。
+4. 渲染完整透明字幕层，再 overlay 到锁定母版；合成后确认音轨未被意外改写。
+5. 完整播放实际最终文件，并复查字幕遮脸、跳字、断行、首尾帧和边界处残影。
+
+已有项目级渲染器能输出精确包装时，使用 `foreground-compose.md` 将它生成的 RGBA 序列叠到锁定母版，
+而不是用通用白字黑框近似品牌样式。该操作保留实际帧钟和 AAC 包，不生成字体或文案；只有通过验证的
+新文件才写入新目录。片名卡有渐显或动画时须提供完整序列，不能冻结最后一张图代替。
+
+## 静态包装图层 `packaging_layers.json`
+
+包框、标题条、角标 logo 这类整片不动的图片，可以直接在合成时叠加，不必先渲染成逐帧序列。
+在 `work_dir` 写 `packaging_layers.json`：
+
+```json
+{
+  "canvas": {"width": 1080, "height": 1920},
+  "layers": [
+    {"name": "frame", "path": "/abs/frame.png", "rect": {"x": 0, "y": 0, "width": 1080, "height": 1920}}
+  ],
+  "template": {"id": "brand-frame", "version": 2}
+}
+```
+
+- `canvas` 必须等于成片画布，否则合成前报错；`rect` 必须在画布内，图片缩放到 `rect` 大小（透明区域保持透明）。
+- 叠加顺序：遮原字幕 → 包装图层（按数组顺序）→ 画面文字 → 解说字幕 → 缩放。
+- `timeline.json` 同时得到对应的 image 轨，剪映草稿里的包框可单独编辑。
+- `assembly_manifest.json` 的 `video_filters.packaging_layers` 记录每张图片的路径与 `{size, mtime_ns}`。
+- 编排器按项目绑定的 `packaging` 模板写出这个文件时会带 `written_by` 标记；
+  手写的文件不会被它删除。有渐显或动画的包装仍走 `foreground-compose.md`。
+
+## 原则
+
+包装价值来自稳定、可读、与内容一致的排版，不来自效果数量。先建立统一字体、颜色、描边/阴影和轻量动效；
+底板、边框、花字与音效只有解决具体可读性或叙事任务时才加入。一个样帧好看不代表全片成立。

package/resources/skills/video-recap-production/upstream/skills/video-assemble/references/pair-media.md

@@ -0,0 +1,74 @@
+# Pair rebuilt picture with a retained adopted soundtrack
+
+When the picture is rebuilt/reframed but the adopted mix must not change, use
+`pair_media.py` before `assemble.py --audio-mode adopted-packet-copy`. This is a
+real two-input stream copy, not re-encoding an old finished video's picture.
+It does not generate narration, align speech, design packaging, or create an
+end card. It does not decide which inputs the editor intended to adopt.
+
+```json
+{
+  "artifact": "media_pair",
+  "schema_version": 1,
+  "picture": {"path": "/project/picture.mp4"},
+  "audio": {"path": "/project/adopted.m4a", "selected_stream": 0}
+}
+```
+
+Both paths must be explicit local files. `selected_stream` is the audio ordinal
+(`a:N`), not the absolute stream index. The audio donor may be an old MP4 with
+unrelated video: only the selected audio is used. The picture's audio is ignored.
+Both files must exist when the plan is read. The plan is strict: unknown fields
+do not silently request unsupported retime, gain, trimming or offset operations
+(legacy `sha256` keys are ignored).
+
+```bash
+python3 scripts/pair_media.py pair.json --output-dir new-pair-directory --plan-only
+# A PLANNED directory is not reusable as a rendered candidate: choose a NEW one.
+python3 scripts/pair_media.py pair.json --output-dir new-render-directory
+```
+
+The output directory must not already exist. No existing input, final asset,
+current pointer, or user-approved version is overwritten. `--plan-only` checks
+actual inputs and timing but creates no video and invokes no mux. A rendered run
+provides:
+
+- `paired.mp4`: selected picture and audio, both compressed-stream copied.
+- `pair_run.json`: `PLANNED`, `PAIR_RENDERED`, or `FAILED`, explicit input and
+  plan/output paths, frame count, timing tolerance and output stream numbering.
+- `picture_identity.json`: decoder, geometry/color, complete actual frame clock
+  and compressed packet size/timing/side-data facts.
+- `adopted_audio_identity.json`: donor and output AAC packet/decoder facts.
+- mux command/log for reconstruction and diagnosis.
+
+The first implementation deliberately accepts H264 or HEVC in an MP4-family container,
+complete zero-origin CFR picture (1–120 fps), and contiguous AAC packets with
+known nominal sample duration. No VFR, retime, offset, format conversion, padding,
+trimming, `-shortest`, normalization or gain is inferred. Packet priming and skip
+metadata are retained. The packet clock must also agree with the declared audio
+stream interval (at most one nominal priming packet before the start; the packet
+end matches the stream end within one sample). This is checked again on the
+actual muxed output. Picture/audio starts and ends must differ by no more than
+the larger of one picture frame or one nominal AAC packet. The interval check is
+compatibility, **not perceptual synchronization or acoustic alignment**. A tiny
+container-tail tolerance does not authorize cutting a word.
+
+Muxing goes to a staging file. The output's video decoder/packet sizes and
+timestamps/full frame clock/geometry/color and adopted AAC packets must match
+the inputs, the output must contain only `v:0,a:0`, and full decode must pass
+before final publication. Failure leaves a FAILED record and logs, not a
+final `paired.mp4`. Rebuilding source geometry is certified by its own upstream
+render/map evidence, not by the existence of a successfully paired container.
+
+## Subtitle integration: bind AFTER pairing
+
+The output audio ordinal is always **0**, even when the donor used `a:1`.
+Create the complete output-clock `subtitle_track.json` against
+`subtitles.track_binding.current_bindings(paired_video, 0)`, then run the existing
+adopted assembly path. Do not reuse a binding computed against the picture-only
+file or the donor's old stream ordinal. A present stale subtitle track fails rather than falling
+back to estimated timings. See [subtitle-track.md](subtitle-track.md).
+
+Pairing preserves the input picture, including any explicit black tail; it does
+not turn that black tail into a branded end card. Listening, normal-speed review,
+editorial intent and release approval remain separate from this mechanical proof.

package/resources/skills/video-recap-production/upstream/skills/video-assemble/references/source-score.md

@@ -0,0 +1,147 @@
+# Source and score bed producer
+
+`source_score.py` is a standalone producer for explicitly authored source-audio
+intervals and one continuous score playhead. It does not mix narration, inspect old
+masters, infer dialogue, choose music, retime sound, normalize loudness, limit peaks,
+or publish a final video.
+
+```bash
+python3 scripts/source_score.py source_score_plan.json --output-dir a-new-directory
+```
+
+The output directory must not exist. Success creates:
+
+- `source_bed.wav` — reordered/pre-gained source intervals plus explicit silence;
+- `score_bed.wav` — one continuous raw-score window or an adopted frozen stem;
+- `prepared_bed.wav` — source plus score, without master gain/limiting;
+- `prepared_bed_receipt.json` — input paths, clocks, sample ranges, PCM facts and QC facts.
+
+All three beds are `pcm_f32le`, 48 kHz, stereo. Float output avoids repeated integer
+quantization and preserves values outside `[-1,1]`; the receipt records actual peak,
+finite-sample status, and `FLOAT_PRESERVED_NO_MASTER`. A later explicitly adopted
+consumer owns final master gain and delivery encoding.
+
+## Strict plan schema v1
+
+```json
+{
+  "artifact": "source_score_plan",
+  "schema_version": 1,
+  "output": {"sample_rate": 48000, "channels": 2, "total_samples": 1920000},
+  "source_segments": [
+    {
+      "id": "protected-dialogue-1",
+      "path": "/local/source.mov",
+      "audio_stream": 0,
+      "source_fps": "24/1",
+      "source_start_frame": 120,
+      "source_end_frame": 180,
+      "output_start_sample": 240000,
+      "gain": 1.0,
+      "fade_in_samples": 0,
+      "fade_out_samples": 96,
+      "fade_shape": "linear",
+      "role": "protected_original"
+    }
+  ],
+  "source_silence": [
+    {"output_start_sample": 0, "output_end_sample": 240000, "role": "silence"},
+    {"output_start_sample": 360000, "output_end_sample": 1920000, "role": "silence"}
+  ],
+  "score": {
+    "kind": "raw",
+    "path": "/local/score.wav",
+    "audio_stream": 0,
+    "source_offset_sample": 384000,
+    "gain": 0.18,
+    "fade_in_samples": 33600,
+    "fade_out_samples": 120000,
+    "fade_shape": "half_cosine"
+  }
+}
+```
+
+Every source range is half-open in CFR picture frames. Version 1 accepts H.264 and
+HEVC picture sources whose complete packet PTS/duration grid proves one zero-origin
+packet per same-speed frame. Frame boundaries are projected onto the 48 kHz clock by
+rounding the exact position half-up once, so `48000/fps` need not be an integer and a
+broadcast rate such as 30000/1001 is accepted; every derived bound comes from those
+rounded positions. Other codecs, incomplete packet timing, VFR, retime fields,
+nominal time seeks, and unknown fields are rejected rather than called verified
+(legacy `sha256` keys are ignored).
+Each unique selected source stream is decoded from its actual PTS clock to canonical
+48 kHz stereo exactly once. All authored intervals are then cut from that canonical
+sample array—never independently decoded or `-ss`-seeked per edit.
+
+The source segment duration is `(source_end_frame-source_start_frame)*48000/fps`.
+Its output end is derived, not declared. Source segments and explicit silence ranges
+must form an exact, nonoverlapping partition of `[0,total_samples)`. There are no
+implicit gaps. Supported roles are `protected_original` and
+`mixed_original_under_narration`; their gains and labels are retained unchanged.
+
+Source fades are explicitly `linear`. A fade of `N>=2` samples uses inclusive
+endpoints: fade-in gain is `i/(N-1)`, and fade-out gain is `(N-1-i)/(N-1)`. Thus the
+first/last samples are exactly zero and the opposite endpoints exactly one. Zero
+means no fade; a one-sample fade is rejected as ambiguous. Fade windows may not
+overlap within a segment.
+
+## Score modes
+
+`raw` decodes the selected score stream once, advances one playhead from
+`source_offset_sample`, and takes exactly `total_samples`. The input must be long
+enough; there is no implicit loop. Gain and one pair of whole-score fades are applied
+once, so score playback never resets at picture/source cuts. `linear` and
+`half_cosine` fades use inclusive endpoints.
+
+When the adopted source bed is already the complete soundtrack and no additional
+music is selected, use the exact no-score form:
+
+```json
+{"kind":"none"}
+```
+
+It accepts no other fields. `score_bed.wav` is real all-zero float PCM at the exact
+output length, while `prepared_bed.wav` is an exact canonical PCM copy of
+`source_bed.wav`; the receipt records `kind:none` rather than inventing a music asset.
+
+An adopted score that already contains its chosen offset/gain/fades uses the exact
+alternative schema:
+
+```json
+{"kind":"frozen","path":"/local/frozen.wav","audio_stream":0}
+```
+
+Frozen input must be PCM16, PCM24, or PCM float, 48 kHz stereo, and exactly
+`total_samples`. PCM16/24 values convert exactly to float canonical representation.
+No offset, gain, fade, loop, normalization or other processing fields are accepted.
+The receipt records the frozen file path and its probed PCM facts.
+
+## Receipt and failure boundary
+
+`prepared_bed_receipt` schema version 1 records the plan path, each input path,
+selected stream, actual CFR/audio clocks, canonical decoded PCM facts, resolved
+input/output sample ranges, gains, fades, roles, and each output's path, byte size,
+format, sample count, finite status and peak.
+
+Every declared input must exist and probe as declared before work starts. A selected
+source range must fit the actual canonical decoded samples; silence padding can never
+conceal a short source. WAVs remain hidden staging artifacts until every output
+validates. FFmpeg failure, invalid ranges, non-finite PCM, or an existing target
+directory cannot publish final-named beds or a receipt.
+Diagnostic command/log/intermediate files may remain in the unique failed directory.
+
+To consume a completed receipt with explicitly adopted narration, use the strict
+`--audio-mix-adoption` path in `explicit-audio-mix.md`. To deliver an already complete
+prepared bed without narration, a dedicated prepared-audio renderer will follow in a
+later release. Do not feed `prepared_bed.wav` through legacy source ducking or
+ambient BGM/loudness settings.
+
+## 与旧入口的关系（中文摘要）
+
+原片完整解码一次再切样本，分别执行保留对白、低位原声和明确静音；渐变必须显式给定。
+已处理的音乐轨走 `frozen`，不能再次偏移、调增益或加渐变。若采用的原声底轨本身已包含
+完整音乐决定且不再叠加配乐，使用严格的 `score:{"kind":"none"}`；它生成真实全零 score，
+并保持 prepared 与 source 逐字节相同，不伪造静音音乐资产。
+
+这一步仅输出声音底轨和来源回执，不是最终视频。旧入口保留兼容行为；调用方须区分
+“底轨已验证”“配音已验证”和“完整混音已验证”三种状态，不能相互冒充。

package/resources/skills/video-recap-production/upstream/skills/video-assemble/references/subtitle-track.md

@@ -0,0 +1,202 @@
+# Independent subtitle track contract (schema v1)
+
+`scripts/subtitles/track.py` loads a subtitle track whose cue times already use
+the final **output clock**. It validates the track against picture, edit, audio,
+and duration facts independently supplied by the caller. It does not align
+speech, remap source time, split text, repair cue boundaries, or prove that a
+subtitle is perceptually synchronized.
+
+## Loader API
+
+```python
+from fractions import Fraction
+from subtitles.track import load_subtitle_track
+
+loaded = load_subtitle_track(
+    "subtitle_track.json",
+    expected_picture_identity={
+        "path": "/project/paired.mp4",
+        "edit_plan": "/project/edit_plan.json",
+    },
+    expected_audio_identity={
+        "selected_stream": 1,
+        "sample_rate": 48000,
+        "packet_count": 4700,
+    },
+    expected_duration_seconds=Fraction(duration_ts) * stream_time_base,
+    reject_legacy_estimate=True,
+)
+metadata = loaded["metadata"]
+entries = loaded["entries"]
+```
+
+The input may also be an in-memory mapping. `entries` is a list of dictionaries
+ready for the existing seconds-based subtitle renderer:
+
+```json
+{
+  "start": 1.0,
+  "end": 3.0,
+  "text": "example",
+  "source": "narration",
+  "source_ref": "narration:7",
+  "timing_evidence": {
+    "kind": "asr_boundary_calibrated",
+    "evidence_refs": ["alignment-run:example"],
+    "calibration": "asr_energy",
+    "word_alignment": "none"
+  }
+}
+```
+
+The loader preserves cue text and boundaries. The only conversion is exact
+integer ticks to renderer-facing seconds. `metadata.timing_evidence_kinds`
+reports the labels present; it is not an aggregate precision verdict.
+
+## Schema v1
+
+```json
+{
+  "schema_version": 1,
+  "clock": {
+    "kind": "output",
+    "timebase": {"numerator": 1, "denominator": 30},
+    "duration_ticks": 300
+  },
+  "overlap_policy": "forbid",
+  "bindings": {
+    "picture": {
+      "path": "/project/paired.mp4",
+      "edit_plan": "/project/edit_plan.json"
+    },
+    "audio": {
+      "selected_stream": 1,
+      "sample_rate": 48000,
+      "packet_count": 4700
+    }
+  },
+  "cues": [
+    {
+      "start_tick": 30,
+      "end_tick": 90,
+      "text": "example",
+      "attribution": {"kind": "narration", "ref": "narration:7"},
+      "timing_evidence": {
+        "kind": "asr_boundary_calibrated",
+        "evidence_refs": ["alignment-run:example"],
+        "calibration": "asr_energy",
+        "word_alignment": "none"
+      }
+    }
+  ]
+}
+```
+
+- `timebase` is rational seconds per tick. Cue intervals are half-open
+  `[start_tick, end_tick)`.
+- `duration_ticks`, cue bounds, and stream indexes are nonnegative integers
+  (booleans are not integers for this contract).
+- Cues must be ordered, non-overlapping, nonempty, and contained by the output
+  duration. Adjacent half-open cues may touch.
+- Distinct tick bounds must remain a positive, finite interval after conversion
+  to the renderer's float seconds. Tracks beyond that projection precision fail
+  closed rather than becoming a zero-length rendered cue.
+- `overlap_policy` must be `forbid`. Schema v1 has no permissive overlap mode.
+- `attribution.kind` is `source` or `narration`; `ref` identifies the source
+  utterance or narration item without changing its text.
+- Unknown fields and schema versions other than integer `1` are rejected, so a
+  newer producer cannot be silently interpreted as v1. Legacy `sha256` /
+  `edit_sha256` binding keys are the one exception: they are ignored.
+
+## Independent binding checks
+
+The loader compares track declarations with the caller's current facts; it never
+treats a track's own binding as evidence that the track is fresh.
+
+- `picture.path` is mandatory and must resolve to the caller's current picture
+  path. `edit_plan` is optional for inputs without a separately materialized
+  edit plan; if the track contains it, the caller must supply the same path.
+- `audio.selected_stream`, `sample_rate` and `packet_count` describe the
+  **actually adopted** audio stream, not merely a source filename or an intended
+  mix manifest. Pass the facts probed from the current media; this module
+  deliberately does not run ffprobe itself.
+- `expected_duration_seconds` is mandatory and checked against
+  `duration_ticks * timebase`. Prefer `Fraction(duration_ts) * time_base` from
+  the actual output stream to avoid decimal/container rounding. `int`, finite
+  `float`, and finite `Decimal` are also accepted.
+
+## Timing evidence labels
+
+Evidence labels describe how a cue boundary was obtained. They do not change
+the exact burn time represented by its ticks.
+
+| `kind` | Required calibration | Required word alignment | Evidence refs |
+|---|---|---|---|
+| `legacy_estimate` | `none` | `none` | optional |
+| `asr_boundary_calibrated` | `asr_energy` | `none` | required |
+| `word_timestamps` | `none` or `asr_energy` | `asr_words` | required |
+| `human_verified` | `human_boundary` | `none` or `human_words` | required |
+
+`asr_boundary_calibrated` is the label for a coarse-ASR boundary adjusted with
+ASR context and/or energy evidence. Energy onset is not proof of a phoneme, so
+this label cannot claim word alignment or human verification. Missing evidence
+references cannot claim any non-legacy kind. A strict caller may reject
+`legacy_estimate`; accepting another label still does not automatically call it
+strong alignment.
+
+Because cue intervals are half-open, a cue is not visible at any tick before its
+`start_tick`; the tick immediately preceding it belongs to whatever came before.
+
+## Deliberate limits
+
+- Schema v1 has no source-to-cut/edit map and cannot map source-clock cues.
+- The module does not inspect media, select audio streams, or tolerate a
+  self-declared binding without current caller facts.
+- Validation proves schema consistency and the requested bindings only. Actual
+  rendered first/last subtitle frames and perceptual speech alignment require
+  separate render/media review.
+
+## Current assembly integration (bounded, not automatic alignment)
+
+Place `subtitle_track.json` in `work_dir` and select
+`assemble.py --audio-mode adopted-packet-copy`. A present track is a **complete
+replacement** of all generated narration/original-dialogue subtitles, not a
+partial patch and not merged with legacy subtitles. Carry every cue that should
+remain; an empty `cues` array intentionally removes all generated subtitles.
+Unknown patch/merge modes are rejected by schema v1. This does not detect words
+missing from the authored full track: acoustic/coverage review remains required.
+
+The assembly integration independently probes the chosen input stream for its
+sample rate and packet count, resolves the input path for the picture binding,
+and records the `{size, mtime_ns}` of the track, video and optional edit plan in
+`subtitle_track_validation.json`. It does not use the track's own declarations
+as current facts.
+
+Actual decoded frame PTS are read before projection. Integer cue ticks and the
+rational timebase are retained until each boundary is resolved to the first
+frame at or after it. `subtitle_track_validation.json` records original ticks,
+resolved frame indexes/PTS, quantization deltas, ASS thresholds, validation
+schema and projector version. SRT and timeline consume resolved frame seconds;
+ASS thresholds are chosen to switch on those same frames despite ASS's 10ms
+clock. A cue with no visible frame, or a boundary that ASS cannot distinguish,
+is rejected rather than silently dropped. The original author file is not
+rewritten. Legacy subtitles keep their previous rendering behavior.
+
+Each consumption re-checks the track/media/optional edit plan `{size, mtime_ns}`
+and the consumer duration; a rewritten input is stale and must be prepared
+again. Deleting the explicit track clears its previous validation record.
+An invalid/stale track never falls back to character-proportional timing.
+
+Current limits:
+- Integration is for output media starting at zero with an adopted AAC track,
+  not raw-source-to-edited-output mapping or a newly mixed narration track.
+- The low-level preparation API accepts `edit_plan_path`, but the assembly CLI
+  does not yet expose it. CLI tracks must omit `edit_plan`; that path binds the
+  input media, not edit-plan ancestry.
+- The low-level policy `reject_legacy_estimate=True` is available. There is not
+  yet a wired commercial-profile CLI gate. The current CLI preserves timing
+  evidence labels and does not call every accepted cue precisely aligned.
+- The actual FFmpeg regression demonstrates frame timing with a synthetic cue,
+  not phoneme alignment. `direct_listening` and `acoustic_alignment` remain
+  `NOT_CHECKED`; evidence labels are declarations, not automatically verified
+  human approval or proof that an external evidence reference is true.

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

@@ -0,0 +1 @@
+"""Adoption family: narration/audio-mix binding + strict publish for adopted-source audio."""