Bước 12 — Clamp subtitle safe gaps và validate không overlap

Mục tiêu:
- Kiểm tra toàn bộ subtitle master tạo ở bước 11.
- Sửa cue subtitle để không bị chồng thời gian.
- Tạo khoảng hở an toàn rất nhỏ giữa các cue nếu cần.
- Đảm bảo subtitle sạch trước khi chia part và render.

Vì sao bắt buộc:
- Sau khi map text gốc theo ASR timestamps, cue có thể sát nhau quá, chồng nhau hoặc duration quá ngắn/dài.
- Nếu đưa thẳng subtitle lỗi vào render, có thể làm subtitle nhảy giật, cue sau đè cue trước, lỗi parser SRT/ASS, hoặc khi tách part bị lệch/mất dòng.
- Đây là cổng QA subtitle trước render.

Input:
- subtitles/master_subtitles.srt
- subtitles/master_subtitles_mapping.json nếu có
- audio/master_audio_probe.json để lấy duration thật của audio/master_narration.wav

Cách làm:
1. Đọc toàn bộ cue trong subtitle master.
2. Kiểm tra thứ tự thời gian: start tăng dần, end > start, cue sau không bắt đầu trước cue trước kết thúc.
3. Clamp cue trong giới hạn audio: không start < 0, không end > duration thật của master audio.
4. Tạo safe gap nhỏ giữa các cue nếu hai cue quá sát hoặc overlap.
5. Kiểm tra duration từng cue: không quá ngắn đến mức không đọc được, không kéo quá dài qua câu/ý tiếp theo.
6. Xuất bản subtitle đã làm sạch.

Output bắt buộc:
- subtitles/master_subtitles_clamped.srt
- subtitles/master_subtitles_validation.json
- logs/step12_clamp_subtitles_manifest.json

Validation phải ghi rõ:
- tổng số cue
- số cue đã chỉnh
- số overlap còn lại = 0
- số cue invalid = 0
- subtitle nằm trong duration master audio

Quy tắc quan trọng:
- Không sửa nội dung text subtitle trừ lỗi kỹ thuật rõ ràng.
- Không dùng ASR transcript thay text gốc.
- Không ép subtitle vượt quá duration thật của audio.
- Nếu còn overlap/invalid cue thì không được sang bước 13.

Bước này phục vụ trực tiếp:
- Bước 13: chia render thành sync-safe parts và tạo exact part subtitle
- Bước 14: render từng part bằng subtitle sạch, không overlap

Checklist:
12. Clamp master subtitle timing against the real master audio duration, add tiny safe gaps, and validate zero overlaps/invalid cues before part splitting or render.