merge(v0.4.1): nf-recorder 质量审查 + 4 fix · 零回归

session: 0912b6e2-1f27-49c4-8c92-a0d6005cb314

6 ally gpt 并发审查 → 5 P0 + 12 P1 → 修 4 P0(Fix-1 stdout / Fix-2 seek tests / Fix-3 orchestrator tests / Fix-4 v1.x 注释) · 留 1 P0(bounded pool)到 v0.5+ ADR.

- 18 文件 · 305+ / 112-
- cargo test 10 passed 0 failed(新 seek 6 失败路径 + orchestrator 4 range tests)
- 4K HEVC 回归 · 3200211 bytes 跟 v0.4 字节级一致 · 零回归

Co-Authored-By: Claude Opus 4.7

Author: claude

crates/nf-recorder/src/cli.rs

@@ -1,6 +1,7 @@
-//! CLI parser for `nf-recorder` · v1.14 T-09 / T-18 subcommand refactor.
+//! CLI parser for `nf-recorder` · clap subcommands for record / snapshot / verify.
 //!
-//! Contract source: `spec/versions/v1.14/spec/interfaces-delta.json`
+//! Historical: v1.14 T-09 / T-18 subcommand refactor.
+//! Historical: contract source `spec/versions/v1.14/spec/interfaces-delta.json`
 //! → `additions.modules[nf-recorder].subprocess_protocol`.
 //!
 //! ## Invocation shapes (backward-compatible)
@@ -26,7 +27,7 @@ use std::path::PathBuf;
 use crate::pipeline::VideoCodec;
 use crate::record_loop::RecordConfig;
 
-/// v1.14 `nf-recorder` command-line interface.
+/// `nf-recorder` command-line interface.
 ///
 /// The top-level struct doubles as the legacy record invocation (no
 /// subcommand); `command` is an optional subcommand that takes precedence
@@ -35,7 +36,7 @@ use crate::record_loop::RecordConfig;
 #[command(
     name = "nf-recorder",
     version,
-    about = "Record bundle.html to MP4 · snapshot single frame to PNG (v1.14)"
+    about = "Record bundle.html to MP4 · snapshot single frame to PNG"
 )]
 pub struct Cli {
     /// Optional subcommand (snapshot / future verify). Absent = legacy record.
@@ -66,14 +67,16 @@ pub struct Cli {
     #[arg(long = "max-duration", default_value_t = 60)]
     pub max_duration: u32,
 
-    /// v1.15 / v1.56 · 时间切片并行录制 · 父进程启 N 个子进程各录 1/N 段 ·
+    /// 时间切片并行录制 · 父进程启 N 个子进程各录 1/N 段 ·
     /// ffmpeg concat 合并。未指定时按分辨率取默认值：1080p=1 · 4k=4。
     /// 显式 `--parallel 1` 可强制串行基线；N≥2 但视频 duration<6s 自动退化单进程。
+    /// Historical: v1.15 / v1.56 parallel export.
     #[arg(long = "parallel")]
     pub parallel: Option<usize>,
 
-    /// v1.15 · 子进程内部参数 · 父 orchestrator 调子进程时传 · 用户不用设（hidden）。
+    /// 子进程内部参数 · 父 orchestrator 调子进程时传 · 用户不用设（hidden）。
     /// 格式 `<start_frame>,<end_frame>` · 半开区间 [start, end) · 0-indexed。
+    /// Historical: v1.15 frame-range worker protocol.
     #[arg(long = "frame-range", hide = true)]
     pub frame_range: Option<String>,
 }

crates/nf-recorder/src/events.rs

@@ -1,21 +1,24 @@
-//! Stdout JSON-Line event emitter · v1.14 T-09 minimal implementation.
+//! Stdout JSON-Line event emitter for recorder progress and verification.
 //!
-//! Contract source: `spec/versions/v1.14/spec/interfaces-delta.json`
+//! Historical: v1.14 T-09 minimal implementation.
+//! Historical: contract source `spec/versions/v1.14/spec/interfaces-delta.json`
 //! → `additions.modules[nf-recorder].subprocess_protocol.stdout_events`.
 //!
 //! Emits one JSON object per line to stdout, flushed on every call so
 //! downstream (nf-cli · verify script · test harness) can read events
 //! incrementally without waiting for buffer flushes.
 //!
 //! **Why sync stdout (not tokio::io)**: recorder pipeline is single-threaded
-//! (worker_count = 1 in v1.14) · sync stdout is simpler · avoids tokio
+//! (single recorder worker) · sync stdout is simpler · avoids tokio
 //! runtime contention with the NSRunLoop pump inside `call_async`.
+//! Historical: v1.14 used `worker_count = 1`.
 
 use serde::Serialize;
 use std::io::Write;
 use std::path::PathBuf;
 
-/// v1.14 recorder stdout events · tagged by `event` field.
+/// Recorder stdout events · tagged by `event` field.
+/// Historical: v1.14 recorder stdout event schema.
 #[derive(Debug, Serialize)]
 #[serde(tag = "event")]
 pub enum Event {
@@ -30,18 +33,20 @@ pub enum Event {
     },
     /// Emitted per frame after successful encode.
     ///
-    /// `t_ms` is the legacy integer-ms value (向后兼容 · v1.14.0/1 字段 · 下游脚本仍用).
+    /// `t_ms` is the legacy integer-ms value (向后兼容 · 下游脚本仍用).
     /// `t_exact_ms` is the precise f64 time the recorder sent to `window.__nf.seek`
-    /// (v1.14.2 FM-T-QUANTIZATION 新增 · 精确 `seq * 1000 / fps` · VP-3 用它做
+    /// (精确 `seq * 1000 / fps` · VP-3 用它做
     /// "帧间 t 序列严格等距" 断言 · spread < 1e-6).
+    /// Historical: v1.14.0/1 integer-ms field; v1.14.2 added FM-T-QUANTIZATION.
     #[serde(rename = "record.frame")]
     RecordFrame {
         t_ms: u64,
         t_exact_ms: f64,
         seq: u64,
         encode_ms: f64,
     },
-    /// Emitted every N frames (recorder chooses cadence, v1.14 = 30).
+    /// Emitted every N frames (recorder chooses cadence).
+    /// Historical: v1.14 cadence = 30.
     #[serde(rename = "record.encode_progress")]
     RecordEncodeProgress {
         frames_encoded: u64,
@@ -84,7 +89,8 @@ pub enum Event {
         duration_ms: u64,
         asserts: Vec<serde_json::Value>,
     },
-    /// v1.15 · 并行录制开始 · orchestrator 父进程 probe duration 后 emit。
+    /// 并行录制开始 · orchestrator 父进程 probe duration 后 emit。
+    /// Historical: v1.15 parallel recording event.
     #[serde(rename = "record.parallel.start")]
     RecordParallelStart {
         parallel: usize,

crates/nf-recorder/src/export_api.rs

@@ -1,4 +1,6 @@
-//! v1.44 · High-level export API · 从 source.json 直接产 MP4。
+//! High-level export API · 从 source.json 直接产 MP4。
+//!
+//! Historical: v1.44 high-level export API.
 //!
 //! 架构(ADR-064):
 //! - 输入:source.json 路径 + 输出 MP4 路径 + 持续时长(秒)
@@ -18,11 +20,13 @@ use crate::pipeline::VideoCodec;
 use crate::record_loop::{self, RecordConfig, RecordError};
 use crate::OutputStats;
 
-/// v1.44 · nf-runtime 浏览器端 IIFE 产物 · 编译时 inline · 跟 nf-shell preview 同源。
+/// nf-runtime 浏览器端 IIFE 产物 · 编译时 inline · 跟 nf-shell preview 同源。
+/// Historical: v1.44 runtime IIFE export source.
 const RUNTIME_IIFE: &str = include_str!("../../nf-runtime/dist/runtime-iife.js");
 
-/// v1.44 · 7 个官方 track 的 JS 源 · 编译时 inline · 喂给 runtime 解析
+/// 7 个官方 track 的 JS 源 · 编译时 inline · 喂给 runtime 解析
 /// `__NF_SOURCE__.tracks[].kind` 定位到对应代码。跟 nf-shell preview 同源。
+/// Historical: v1.44 official track source embedding.
 const TRACK_BG: &str = include_str!("../../nf-tracks/official/bg.js");
 const TRACK_SCENE: &str = include_str!("../../nf-tracks/official/scene.js");
 const TRACK_VIDEO: &str = include_str!("../../nf-tracks/official/video.js");
@@ -76,11 +80,13 @@ pub struct ExportOpts {
     pub fps: u32,
     /// VideoToolbox 目标比特率(bps)· 默认 20Mbps。
     pub bitrate_bps: u32,
-    /// v1.44.1 / v1.56 · 并行切片 N(ADR-061) · `None` = 按分辨率取默认
+    /// 并行切片 N(ADR-061) · `None` = 按分辨率取默认
     /// (1080p=1 / 4k=4) · `Some(1)` 可显式强制串行。
     /// duration < 6s 时 orchestrator 自动降级单进程(segment boot 开销吃掉收益)。
+    /// Historical: v1.44.1 / v1.56 parallel slicing.
     pub parallel: Option<usize>,
-    /// v1.55 · CLI `--resolution` 覆盖 `source.json meta.export.resolution`。
+    /// CLI `--resolution` 覆盖 `source.json meta.export.resolution`。
+    /// Historical: v1.55 resolution override.
     pub resolution_override: Option<ExportResolution>,
 }
 
@@ -149,7 +155,9 @@ struct ResolvedExportPreset {
     codec: VideoCodec,
 }
 
-/// v1.44 · 高层 lib API · 输入 source.json 路径 · 输出 MP4。
+/// 高层 lib API · 输入 source.json 路径 · 输出 MP4。
+///
+/// Historical: v1.44 high-level lib export API.
 ///
 /// 主调方(nf-shell):
 /// ```ignore
@@ -237,7 +245,7 @@ pub async fn run_export_from_source(
         preset.viewport.1,
     )?;
 
-    // v1.44.1 / v1.56 · parallel >= 2 走 orchestrator (spawn N 子进程 +
+    // Historical: v1.44.1 / v1.56 parallel >= 2 走 orchestrator (spawn N 子进程 +
     // ffmpeg concat) · 4k 未显式指定时默认 parallel=4。
     // 短视频(<6s) orchestrator 内部自动降级单进程 · duration 够长走真并行。
     // 单进程路径用 record_loop::run 拿 OutputStats · 并行路径 orchestrator 返 ()
@@ -382,7 +390,7 @@ window.__NF_TRACKS__ = {tracks_map_json};
     var REQUESTED_DURATION_MS = {requested_duration_ms};
     window.__nf = window.__nf || {{}};
     window.__nf_handle = handle;
-    // recorder 合约 (v1.14 FrameReadyContract):
+    // Historical: recorder 合约 (v1.14 FrameReadyContract):
     // - seek(t_ms) 返 {{t, frameReady:true, seq}} · t 在 0.01ms 容差内等于 t_ms · seq 单调递增
     // - 外部 t 纯驱动 (ADR-045) · 不依赖 RAF
     var _seq = 0;

crates/nf-recorder/src/frame_pool.rs

@@ -1,15 +1,19 @@
-//! `FramePool` · v1.14 T-09 placeholder.
+//! `FramePool` · Capacity + submission counter · NOT an SPSC pool.
 //!
-//! v1.14 runs with `worker_count = 1` (scope.json) · the recorder thread is
+//! True bounded in-flight control 留 v0.5 ADR.
+//! Historical: v1.14 T-09 placeholder.
+//!
+//! Historical: v1.14 ran with `worker_count = 1` (scope.json) · the recorder thread is
 //! the sole driver of the VT encoder which already owns a tiny internal
 //! reorder queue inside VideoToolbox. A classic multi-producer SPSC pool
 //! (crossbeam ArrayQueue) is over-engineered for this case: we never hold
 //! more than one outstanding `IOSurface` at a time because `push_frame`
 //! drains the compressor's output queue synchronously each iteration.
 //!
 //! This struct is kept as a named entry point so future versions can swap
-//! in a real pool (v1.19 multi-worker) without touching `record_loop.rs`.
+//! in a real pool without touching `record_loop.rs`.
 //! Today it only records statistics.
+//! Historical: v1.19 multi-worker pool was the planned expansion point.
 
 /// Simplified pool · counts submissions for telemetry.
 #[derive(Debug, Default)]
@@ -19,7 +23,8 @@ pub struct FramePool {
 }
 
 impl FramePool {
-    /// Construct an empty pool with a nominal `capacity` (v1.14 ignores it).
+    /// Construct an empty pool with a nominal `capacity`.
+    /// Historical: v1.14 ignored capacity.
     #[must_use]
     pub fn new(capacity: usize) -> Self {
         Self {
@@ -40,7 +45,8 @@ impl FramePool {
         self.submitted
     }
 
-    /// Nominal capacity (unused in v1.14 · reserved for v1.19).
+    /// Nominal capacity.
+    /// Historical: unused in v1.14 · reserved for v1.19.
     #[must_use]
     pub fn capacity(&self) -> usize {
         self.capacity

crates/nf-recorder/src/lib.rs

@@ -4,11 +4,11 @@ pub mod cli; // T-10 填
 pub mod events; // T-10 填
 pub mod export_api;
 pub mod frame_pool; // T-09 填
-pub mod orchestrator; // v1.15 · 并行录制父进程 · spawn N 子 + ffmpeg concat
+pub mod orchestrator; // Historical: v1.15 · 并行录制父进程 · spawn N 子 + ffmpeg concat
 pub mod pipeline;
 pub mod record_loop; // T-09 填
 pub mod snapshot; // T-18 · product-internal single-frame PNG
-pub mod verify_mp4; // T-17 · product-internal MP4 atom verifier // v1.44 · high-level lib API · 从 source.json 直接导出 MP4
+pub mod verify_mp4; // T-17 · product-internal MP4 atom verifier // Historical: v1.44 · high-level lib API · 从 source.json 直接导出 MP4
 
 pub use export_api::{run_export_from_source, ExportOpts, ExportResolution};
 pub use pipeline::{ColorSpec, OutputStats, PipelineError, RecordOpts, RecordPipeline, VideoCodec};

crates/nf-recorder/src/main.rs

@@ -1,4 +1,6 @@
-//! `nf-recorder` binary entry point · v1.14 T-09 / T-17 / T-18.
+//! `nf-recorder` binary entry point · record / snapshot / verify dispatch.
+//!
+//! Historical: v1.14 T-09 / T-17 / T-18 entry point.
 //!
 //! Single-threaded tokio runtime so the inner `call_async` future can pump
 //! the macOS main run loop on the calling thread (WKWebView / CARenderer