fix(audio): 写块按时间戳补静音对齐

Author: Aparencia

app/src-tauri/src/audio_align_tests.rs

@@ -101,7 +101,7 @@ fn book_stays_unusable_after_a_single_deviation() {
     // Assert：失效后基准不再推进（纯追加不改变已写样本的会话轴末端）
     assert_eq!(book.first_ts_ms, Some(T0));
     assert_eq!(book.last_end_ms, Some(T0 + 200));
-    assert_eq!(book.aligned, false);
+    assert!(!book.aligned);
 }
 
 // ⑩ 批量 ≡ 增量（对拍）：两条路径在 ≥7 条夹具上逐元素相等

app/src-tauri/src/audio_store.rs

@@ -1,9 +1,16 @@
 //! 实时链路音频落盘（REQ-068 / v0.6.0 M4，S4 早期排）。
 //!
-//! @ai-context: 实时链路当前不落盘（已核查）——本模块按会话落 WAV
-//!              （16kHz 单声道 PCM16，~115MB/小时），为 AL3 漂移实测
-//!              （REQ-063 真机校准数据源）、V4 两遍解码（v0.7.0+）、
-//!              X1 回听（待议）铺路。
+//! @ai-context: 实时链路**已落盘**（2026-09-13 就地更正，批 6 T23）：接线点 =
+//!              `live_session.rs:258-262` 创建 · `live_session_loop.rs:162-164` 每 200ms
+//!              写块 · `:391-397` finalize。**旧注逐字「实时链路当前不落盘（已核查）」
+//!              与代码自相矛盾** ⇒ 保留一行作历史注记（标签不许说谎，批 3 A5/R-3 先例）。
+//! @ai-context: 本模块按会话落 WAV（16kHz 单声道 PCM16，~115MB/小时），为 AL3 漂移实测
+//!              （REQ-063 真机校准数据源）、V4 两遍解码（v0.7.0+）、X1 回听（待议）铺路。
+//! @ai-context: T23/R5.5-b：**WAV 轴 ≡ 会话轴** —— 写块按 `chunk.timestamp_ms` 的空档
+//!              等长补静音（纯函数 `audio_align`；基准轴 = 会话轴，暂停两侧抵消）；
+//!              失效安全（时间戳缺失/回退/超大空档 ⇒ 纯追加 + `aligned = false`，样本
+//!              一个不丢）；`finalize` 把自证量写进 `{id}.wav.meta.json`（读侧
+//!              `commands_audio::read_aligned`；**历史录音无 sidecar ⇒ false**）。
 //! @ai-context: 策略可配：默认开 / 保留期 30 天 / 磁盘预算上限（超限删最旧，
 //!              在会话结束时触发）；清理 UI 由命令层暴露（M6 前端消费）。
 //! @ai-context: 落盘失败不阻断会话主链路（本地优先铁律的降级方向：音频是
@@ -19,7 +26,6 @@ use std::path::{Path, PathBuf};
 /// @ai-context: 由父模块自己声明（DISPATCH-TEMPLATE §二）；`pub(crate)` 是跨模块引用的
 ///              必要条件（`live_session*` 与本模块的测试都要用）。
 #[path = "audio_align.rs"]
-#[allow(dead_code)] // 本提交只落纯函数 + 单测（尚未接线）；接线提交落地后即删
 pub(crate) mod audio_align;
 
 /// 默认保留期（天）。
@@ -63,12 +69,36 @@ pub struct CleanupSummary {
     pub freed_bytes: u64,
 }
 
-/// 会话音频写入器（有状态：目标文件 + 已写样本数）。
+/// 会话音频写入器（有状态：目标文件 + 已写样本数 + 对齐簿记 + sidecar 路径）。
 pub struct SessionAudioWriter {
     file: Option<std::fs::File>,
     samples_written: u64,
+    /// 对齐簿记（T23/R5.5-b：`aligned` 是自证量，禁止恒 true）
+    book: audio_align::AlignBook,
+    /// 对齐 sidecar 路径（`{id}.wav.meta.json`；`create` 时定下 ⇒ 不必再传 session_id）
+    meta_path: PathBuf,
 }
 
+/// 对齐自证量 sidecar 的写入面（键名 = 批 6 冻结快照；读侧 `commands_audio.rs:125-139`）。
+///
+/// @ai-context: 键名**不得**单方面改名 —— T22 的读侧按这份快照实现，改名会让它**静默
+///              回落 `false`**（R43④ 裁决：改名必须同提交改读侧）。
+#[derive(serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+struct AlignSidecar {
+    /// 契约版本（本批 = 1）
+    version: u32,
+    /// 自证量（**禁止恒 true**；见 `audio_align::AlignBook`）
+    aligned: bool,
+    /// 首个带时间戳的块的 `timestamp_ms`（`null` = 无基准）
+    first_ts_ms: Option<i64>,
+    /// 已写样本总数（含补的静音）
+    samples_written: u64,
+}
+
+/// 对齐 sidecar 契约版本。
+const ALIGN_SIDECAR_VERSION: u32 = 1;
+
 impl SessionAudioWriter {
     /// 创建会话音频文件（含 WAV 头；失败 → None——落盘降级不阻断主链路）。
     ///
@@ -84,27 +114,47 @@ impl SessionAudioWriter {
         if write_header(&mut file, 0).is_err() {
             return None;
         }
-        Some(Self { file: Some(file), samples_written: 0 })
+        Some(Self {
+            file: Some(file),
+            samples_written: 0,
+            book: audio_align::AlignBook::new(),
+            meta_path: session_audio_dir.join(format!("{}.wav.meta.json", session_id)),
+        })
     }
 
     /// 追加一块样本（f32 → PCM16；失败静默降级——落盘不阻断主链路）。
-    pub fn write_chunk(&mut self, samples: &[f32]) {
-        let Some(file) = self.file.as_mut() else { return };
-        let mut buf = Vec::with_capacity(samples.len() * 2);
+    ///
+    /// @ai-context: T23/R5.5-b：写前按 `timestamp_ms` 与会话轴的**空档等长补静音**
+    ///              （`audio_align::silence_gap_samples`）⇒ WAV 轴 ≡ 会话轴；时间戳
+    ///              缺失/回退/超大空档 ⇒ **失效安全**（不补、`aligned = false`、退回
+    ///              纯追加），**样本一个不丢**。补零与样本**一次 `write_all`**（写失败
+    ///              仍是「释放句柄、后续不再尝试」的既有降级）。
+    pub fn write_chunk(&mut self, samples: &[f32], timestamp_ms: Option<i64>) {
+        if self.file.is_none() {
+            return;
+        }
+        let pad = self.book.step(timestamp_ms, samples.len()).unwrap_or(0);
+        let mut buf = Vec::with_capacity((pad + samples.len()) * 2);
+        buf.resize(pad * 2, 0); // PCM16 静音 = 全 0 字节（小端 i16 的 0 即两字节 0）
         for s in samples {
             // f32 → i16 量化（round 半远离零——截断会引入 -0.5 偏置）
             let v = (s.clamp(-1.0, 1.0) * 32767.0).round() as i16;
             buf.extend_from_slice(&v.to_le_bytes());
         }
+        let Some(file) = self.file.as_mut() else { return };
         if file.write_all(&buf).is_err() {
             // 写盘失败：释放句柄（后续块不再尝试——降级为不落盘）
             self.file = None;
         } else {
-            self.samples_written += samples.len() as u64;
+            self.samples_written += (pad + samples.len()) as u64;
         }
     }
 
-    /// 结束会话：回填 WAV 长度字段（RIFF/data）并关闭文件。
+    /// 结束会话：回填 WAV 长度字段（RIFF/data）并关闭文件，随后写对齐 sidecar。
+    ///
+    /// @ai-context: T23：sidecar **最后写** ⇒ 它存在即说明 WAV 已 finalize（读侧
+    ///              `durationMs` 才有值）；句柄已释放（写盘失败）时连 WAV 长度都没回填
+    ///              ⇒ 不写 sidecar（读侧 `durationMs = None`，本就不该播）。
     pub fn finalize(&mut self) {
         let Some(mut file) = self.file.take() else { return };
         // data 长度 = 样本数 × 2 字节；RIFF 长度 = 36 + data 长度
@@ -115,6 +165,20 @@ impl SessionAudioWriter {
         let _ = file.seek(std::io::SeekFrom::Start(40));
         let _ = file.write_all(&(data_len as u32).to_le_bytes());
         let _ = file.sync_all();
+        self.write_align_sidecar();
+    }
+
+    /// 写对齐 sidecar（失败静默——与 WAV 写盘同向：落盘降级不阻断主链路）。
+    fn write_align_sidecar(&self) {
+        let sidecar = AlignSidecar {
+            version: ALIGN_SIDECAR_VERSION,
+            aligned: self.book.is_aligned(),
+            first_ts_ms: self.book.first_ts_ms,
+            samples_written: self.samples_written,
+        };
+        if let Ok(text) = serde_json::to_string(&sidecar) {
+            let _ = std::fs::write(&self.meta_path, text);
+        }
     }
 }
 

app/src-tauri/src/audio_store_tests.rs

@@ -2,6 +2,9 @@
 //!
 //! @ai-context: AAA 模式；tempfile 隔离；覆盖 WAV 头/数据 roundtrip、
 //!              finalize 回填、保留期/磁盘预算清理、降级路径。
+//! @ai-context: T23 的签名连带（R5.5-b）：`write_chunk` 加了 `timestamp_ms` 入参 ⇒ 本文件
+//!              4 处旧调用点传 `None`（**只改调用形态、断言一字未动**）——`None` 正好
+//!              覆盖「无时间基准 ⇒ 纯追加」的降级路径（与 T23 前的行为逐字节相同）。
 
 use super::*;
 
@@ -14,10 +17,10 @@ fn wav_header_and_data_roundtrip() {
     // Arrange
     let dir = tempfile::tempdir().unwrap();
     let mut writer = SessionAudioWriter::create(dir.path(), 42, &config()).expect("writer");
-    // Act：写两块样本（每块 100 样本）
+    // Act：写两块样本（每块 100 样本；无时间戳 ⇒ 纯追加，与 T23 前同形）
     let chunk: Vec<f32> = (0..100).map(|i| (i as f32 / 100.0) - 0.5).collect();
-    writer.write_chunk(&chunk);
-    writer.write_chunk(&chunk);
+    writer.write_chunk(&chunk, None);
+    writer.write_chunk(&chunk, None);
     writer.finalize();
     // Assert：WAV 头（RIFF/WAVE/PCM16/16kHz/单声道/200 样本）
     let raw = std::fs::read(dir.path().join("42.wav")).unwrap();
@@ -128,10 +131,148 @@ fn stats_counts_files_and_bytes() {
 fn write_after_finalize_is_noop() {
     let dir = tempfile::tempdir().unwrap();
     let mut writer = SessionAudioWriter::create(dir.path(), 7, &config()).unwrap();
-    writer.write_chunk(&[0.1, 0.2]);
+    writer.write_chunk(&[0.1, 0.2], None);
     writer.finalize();
     // finalize 后写入不再增长（句柄已释放）
-    writer.write_chunk(&[0.3]);
+    writer.write_chunk(&[0.3], None);
     let len = std::fs::metadata(dir.path().join("7.wav")).unwrap().len();
     assert_eq!(len, (WAV_HEADER_LEN + 4) as u64);
 }
+
+// ───────────────────────── T23/R5.5-b：WAV 轴 ≡ 会话轴 ─────────────────────────
+
+/// 一块 200 ms @16 kHz 的样本数（与 `capture/audio_loopback.rs:338` 的块长一致）。
+const BLOCK: usize = 3_200;
+
+/// 读 sidecar（断言键名与取值；缺文件即红 —— 不做容错）。
+fn sidecar(dir: &std::path::Path, id: i64) -> serde_json::Value {
+    let text = std::fs::read_to_string(dir.join(format!("{}.wav.meta.json", id))).expect("sidecar");
+    serde_json::from_str(&text).expect("sidecar 是 JSON")
+}
+
+/// V1（行为级）：空档补静音 —— 文件字节数 == `44 + (3200 + 3200 + 200ms×16 + 3200) × 2`。
+#[test]
+fn write_chunk_pads_silence_for_gaps() {
+    // Arrange：t0 → t0+200ms（连续）→ t0+600ms（空档 200ms）
+    let dir = tempfile::tempdir().unwrap();
+    let mut writer = SessionAudioWriter::create(dir.path(), 23, &config()).expect("writer");
+    let block = vec![0.5f32; BLOCK];
+    // Act
+    writer.write_chunk(&block, Some(1_000));
+    writer.write_chunk(&block, Some(1_200));
+    writer.write_chunk(&block, Some(1_600));
+    writer.finalize();
+    // Assert：44 + 12800×2 字节；data 长度字段同步
+    let raw = std::fs::read(dir.path().join("23.wav")).unwrap();
+    assert_eq!(raw.len(), WAV_HEADER_LEN + 12_800 * 2, "空档补静音后的文件长度");
+    assert_eq!(&raw[40..44], &(12_800u32 * 2).to_le_bytes(), "finalize 回填 data 长度");
+    // 空档区（第 3 块之前）确实是零样本：偏移 = 44 + (3200+3200)×2
+    let gap = WAV_HEADER_LEN + 6_400 * 2;
+    assert!(raw[gap..gap + BLOCK * 2].iter().all(|b| *b == 0), "空档必须补静音");
+    // 反证：样本区不得是零（0.5 ⇒ 16384）—— 防「整段填零」的假绿
+    assert_eq!(i16::from_le_bytes([raw[44], raw[45]]), 16_384);
+    let third = gap + BLOCK * 2;
+    assert_eq!(i16::from_le_bytes([raw[third], raw[third + 1]]), 16_384);
+}
+
+/// V2：缺 `timestamp_ms` ⇒ 纯追加 + `aligned = false`，**样本一个不丢**、写盘不中断。
+#[test]
+fn missing_timestamp_degrades_to_append_and_marks_unaligned() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut writer = SessionAudioWriter::create(dir.path(), 24, &config()).expect("writer");
+    let block = vec![0.25f32; BLOCK];
+    writer.write_chunk(&block, Some(1_000));
+    writer.write_chunk(&block, None); // 时间戳缺失 ⇒ 永久失效
+    writer.write_chunk(&block, Some(9_000)); // 后续即便单调也不补（且样本照写）
+    writer.finalize();
+    let raw = std::fs::read(dir.path().join("24.wav")).unwrap();
+    assert_eq!(raw.len(), WAV_HEADER_LEN + 9_600 * 2, "三块样本一个不少、且没有任何补零");
+    assert_eq!(sidecar(dir.path(), 24)["aligned"], serde_json::json!(false));
+    assert_eq!(sidecar(dir.path(), 24)["samplesWritten"], serde_json::json!(9_600));
+}
+
+/// V3：时间戳非单调 ⇒ 同上，且回退块**照常写入**（不被丢弃、不产生负长度）。
+#[test]
+fn non_monotonic_timestamp_degrades_to_append() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut writer = SessionAudioWriter::create(dir.path(), 25, &config()).expect("writer");
+    let block = vec![0.25f32; BLOCK];
+    writer.write_chunk(&block, Some(2_000));
+    writer.write_chunk(&block, Some(1_500)); // 回退 500ms
+    writer.finalize();
+    let raw = std::fs::read(dir.path().join("25.wav")).unwrap();
+    assert_eq!(raw.len(), WAV_HEADER_LEN + 6_400 * 2, "回退块照常写入（纯追加）");
+    assert_eq!(sidecar(dir.path(), 25)["aligned"], serde_json::json!(false));
+}
+
+/// V4：`aligned` **不得恒 true** —— 全程单调 ⇒ `true`；且 sidecar 键名 = 冻结快照
+/// （T22 读侧按它取 `aligned`；改名会让读侧静默回落 `false`）。
+#[test]
+fn sidecar_marks_aligned_session_with_frozen_keys() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut writer = SessionAudioWriter::create(dir.path(), 26, &config()).expect("writer");
+    let block = vec![0.1f32; BLOCK];
+    writer.write_chunk(&block, Some(1_000));
+    writer.write_chunk(&block, Some(1_200));
+    writer.finalize();
+    let s = sidecar(dir.path(), 26);
+    assert_eq!(s["version"], serde_json::json!(1));
+    assert_eq!(s["aligned"], serde_json::json!(true));
+    assert_eq!(s["firstTsMs"], serde_json::json!(1_000));
+    assert_eq!(s["samplesWritten"], serde_json::json!(6_400));
+    let mut keys: Vec<String> = s.as_object().unwrap().keys().cloned().collect();
+    keys.sort();
+    assert_eq!(keys, vec!["aligned", "firstTsMs", "samplesWritten", "version"]);
+}
+
+/// V6：超大空档（> `MAX_GAP_MS`）⇒ 不补（否则会当场写 ≈9.6M 样本静音）+ `aligned = false`。
+#[test]
+fn oversized_gap_does_not_write_bulk_silence() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut writer = SessionAudioWriter::create(dir.path(), 27, &config()).expect("writer");
+    let block = vec![0.1f32; BLOCK];
+    writer.write_chunk(&block, Some(1_000));
+    // 空档自**上块末端**（1_200）起算 ⇒ 取 MAX_GAP_MS + 1 才真的超上限
+    writer.write_chunk(&block, Some(1_200 + audio_align::MAX_GAP_MS + 1));
+    writer.finalize();
+    let raw = std::fs::read(dir.path().join("27.wav")).unwrap();
+    assert_eq!(raw.len(), WAV_HEADER_LEN + 6_400 * 2, "超上限不补");
+    assert_eq!(sidecar(dir.path(), 27)["aligned"], serde_json::json!(false));
+}
+
+/// 自证不变式（writer 级）：`data 长度 ÷ 2 ÷ 16 ==（末块 ts − 首块 ts）+ 块长`，
+/// 在**发生过暂停 + 静默窗**的会话形态上同样成立（暂停两侧抵消：端点停采 ↔ 时间戳冻结）。
+#[test]
+fn wav_axis_equals_session_axis_after_pause_and_silence_window() {
+    let dir = tempfile::tempdir().unwrap();
+    let mut writer = SessionAudioWriter::create(dir.path(), 28, &config()).expect("writer");
+    let block = vec![0.1f32; BLOCK];
+    // 会话形态：连续两块 →（暂停 30s：会话轴上不可见，`timestamp_ms` 已补偿）→ 一块
+    //          → 静默窗 1.8s（无包）→ 收尾两块
+    for ts in [1_000i64, 1_200, 1_400, 3_400, 3_600] {
+        writer.write_chunk(&block, Some(ts));
+    }
+    writer.finalize();
+    let raw = std::fs::read(dir.path().join("28.wav")).unwrap();
+    let data_len = u64::from(u32::from_le_bytes(raw[40..44].try_into().unwrap()));
+    // 逐字读数：44800 样本 ⇒ 2800 ms == (3600 − 1000) + 200
+    assert_eq!(data_len, 44_800 * 2);
+    assert_eq!(data_len / 2 / 16, (3_600 - 1_000) + 200);
+    assert_eq!(sidecar(dir.path(), 28)["aligned"], serde_json::json!(true));
+}
+
+/// R5.5-b 第 3 条：**历史录音必须能区分** —— 本修复之前的 WAV 无 sidecar（读侧 false）；
+/// 本模块产出的会话**一定**带 sidecar（`true`/`false` 皆可读 ⇒ 与历史录音区分得开）。
+#[test]
+fn sidecar_distinguishes_history_from_new_sessions() {
+    let dir = tempfile::tempdir().unwrap();
+    // 历史录音形态：只有 WAV（T23 之前录的）
+    std::fs::write(dir.path().join("9.wav"), b"RIFF").unwrap();
+    assert!(!dir.path().join("9.wav.meta.json").exists(), "历史录音无 sidecar");
+    // 新会话：即便无时间基准（`aligned=false`）也**有据可查**
+    let mut writer = SessionAudioWriter::create(dir.path(), 10, &config()).expect("writer");
+    writer.write_chunk(&vec![0.0f32; BLOCK], None);
+    writer.finalize();
+    assert!(dir.path().join("10.wav.meta.json").exists(), "新会话必写 sidecar");
+    assert_eq!(sidecar(dir.path(), 10)["aligned"], serde_json::json!(false));
+}

app/src-tauri/src/live_session_loop.rs

@@ -160,7 +160,7 @@ pub(crate) fn run_audio_loop(
                 // M4/REQ-068（S4）：原始样本落盘（预处理前——V4 两遍解码/
                 // AL3 漂移实测需原始音频；写盘失败内部降级不阻断）
                 if let Some(w) = ctx.audio_writer.as_mut() {
-                    w.write_chunk(&chunk.samples);
+                    w.write_chunk(&chunk.samples, i64::try_from(chunk.timestamp_ms).ok());
                 }
                 // M6/REQ-041 A1：预处理（默认直通零开销；开启后 AGC/削波/动态阈值）
                 let processed = audio_pre.process(&chunk.samples, SILENCE_RMS_THRESHOLD);